Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

29.1 KB
Raw Blame
package cmd

import (
	"context"
	"encoding/json"
	"fmt"
	"io"
	"os"
	"strings"
	"time"

	"github.com/spf13/cobra"

	"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/dashboard"
	"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lifecycle"
	"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/learning"
	"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
)

var memoryOpts struct {
	userMode     bool
	systemMode   bool
	logPath      string
	jsonOutput   bool
	projectPath  string
	limit        int
	page         int
	query        string
	harness      string
	traceID      string
	since        string
	until        string
	dryRun       bool
	evaluator    string
	jevEndpoint  string
	jevAPIKey    string
	jevModel     string
	costPerTrace float64
	subqEndpoint string
	subqAPIKey   string
	subqModel    string
	timeout      time.Duration
	state        string
	kind         string
	reason       string
	replacement  string
	force        bool
	title        string
	body         string
	bodyFile     string
	applies      string
	tags         []string
}

var memoryCmd = &cobra.Command{
	Use:   "memory",
	Short: "Evaluate and review cross-harness agent memory",
}

var memoryListCmd = &cobra.Command{
	Use:          "list",
	Short:        "List approved project memory",
	SilenceUsage: true,
	RunE:         runMemoryList,
}

var memoryShowCmd = &cobra.Command{
	Use:          "show <memory-id>",
	Short:        "Show one approved memory item",
	Args:         cobra.ExactArgs(1),
	SilenceUsage: true,
	RunE:         runMemoryShow,
}

var memoryEvaluationsCmd = &cobra.Command{
	Use:   "evaluations",
	Short: "Run and inspect local trace evaluations",
}

var memoryEvaluationsRunCmd = &cobra.Command{
	Use:          "run",
	Short:        "Evaluate local traces with Jev or SubQ",
	SilenceUsage: true,
	RunE:         runMemoryEvaluationsRun,
}

var memoryEvaluationsListCmd = &cobra.Command{
	Use:          "list",
	Short:        "List persisted trace evaluations",
	SilenceUsage: true,
	RunE:         runMemoryEvaluationsList,
}

var memoryEvaluationsShowCmd = &cobra.Command{
	Use:          "show <evaluation-id>",
	Short:        "Show one persisted trace evaluation",
	Args:         cobra.ExactArgs(1),
	SilenceUsage: true,
	RunE:         runMemoryEvaluationsShow,
}

var memoryCandidatesCmd = &cobra.Command{
	Use:   "candidates",
	Short: "Review extracted memory candidates",
}

var memoryCandidatesListCmd = &cobra.Command{
	Use:          "list",
	Short:        "List memory candidates",
	SilenceUsage: true,
	RunE:         runMemoryCandidatesList,
}

var memoryCandidatesShowCmd = &cobra.Command{
	Use:          "show <candidate-id>",
	Short:        "Show one memory candidate",
	Args:         cobra.ExactArgs(1),
	SilenceUsage: true,
	RunE:         runMemoryCandidatesShow,
}

var memoryCandidatesCreateCmd = &cobra.Command{
	Use:   "create",
	Short: "Write a memory candidate for a trace you have reviewed",
	Long: `Write a memory candidate for a trace you have reviewed.

Unlike "evaluations run", no evaluator is involved: you read the trace and state the
lesson. The candidate records the trace and its events as evidence and waits for
"candidates approve" like any other. Memory is scoped to the trace's repository when
it recorded one, otherwise to --project or the current directory.`,
	SilenceUsage: true,
	RunE:         runMemoryCandidatesCreate,
}

var memoryCandidatesApproveCmd = &cobra.Command{
	Use:          "approve <candidate-id>",
	Short:        "Approve a candidate into project memory",
	Args:         cobra.ExactArgs(1),
	SilenceUsage: true,
	RunE:         runMemoryCandidatesApprove,
}

var memoryCandidatesRejectCmd = &cobra.Command{
	Use:          "reject <candidate-id>",
	Short:        "Reject a memory candidate",
	Args:         cobra.ExactArgs(1),
	SilenceUsage: true,
	RunE:         runMemoryCandidatesReject,
}

var memoryCandidatesSupersedeCmd = &cobra.Command{
	Use:          "supersede <candidate-id>",
	Short:        "Mark a candidate as superseded by approved memory",
	Args:         cobra.ExactArgs(1),
	SilenceUsage: true,
	RunE:         runMemoryCandidatesSupersede,
}

var memorySkillsCmd = &cobra.Command{
	Use:   "skills",
	Short: "Preview and install approved memory as Agent Skills",
}

var memorySkillsPreviewCmd = &cobra.Command{
	Use:          "preview <candidate-id>",
	Short:        "Preview the Agent Skill for an approved candidate",
	Args:         cobra.ExactArgs(1),
	SilenceUsage: true,
	RunE:         runMemorySkillsPreview,
}

var memorySkillsInstallCmd = &cobra.Command{
	Use:          "install <candidate-id>",
	Short:        "Install the Agent Skill for an approved candidate",
	Args:         cobra.ExactArgs(1),
	SilenceUsage: true,
	RunE:         runMemorySkillsInstall,
}

// evaluationRunResult reports one `evaluations run`. Project is set only when --project
// pinned every trace to one project; otherwise each trace is scoped to its own
// repository, and the project lives on each preview and evaluation instead.
type evaluationRunResult struct {
	DryRun           bool                                    `json:"dry_run"`
	Project          *asymptoteobserve.LearningProjectV1     `json:"project,omitempty"`
	StorePath        string                                  `json:"store_path"`
	TraceCount       int                                     `json:"trace_count"`
	EstimatedCalls   int                                     `json:"estimated_calls"`
	EstimatedCostUSD float64                                 `json:"estimated_cost_usd"`
	Previews         []learning.EvaluationPreview            `json:"previews,omitempty"`
	Evaluations      []asymptoteobserve.LearningEvaluationV1 `json:"evaluations,omitempty"`
	Candidates       []asymptoteobserve.LearningCandidateV1  `json:"candidates,omitempty"`
}

func init() {
	rootCmd.AddCommand(memoryCmd)
	memoryCmd.AddCommand(memoryListCmd)
	memoryCmd.AddCommand(memoryShowCmd)
	memoryCmd.AddCommand(memoryEvaluationsCmd)
	memoryCmd.AddCommand(memoryCandidatesCmd)
	memoryCmd.AddCommand(memorySkillsCmd)
	memoryEvaluationsCmd.AddCommand(memoryEvaluationsRunCmd)
	memoryEvaluationsCmd.AddCommand(memoryEvaluationsListCmd)
	memoryEvaluationsCmd.AddCommand(memoryEvaluationsShowCmd)
	memoryCandidatesCmd.AddCommand(memoryCandidatesListCmd)
	memoryCandidatesCmd.AddCommand(memoryCandidatesShowCmd)
	memoryCandidatesCmd.AddCommand(memoryCandidatesCreateCmd)
	memoryCandidatesCmd.AddCommand(memoryCandidatesApproveCmd)
	memoryCandidatesCmd.AddCommand(memoryCandidatesRejectCmd)
	memoryCandidatesCmd.AddCommand(memoryCandidatesSupersedeCmd)
	memorySkillsCmd.AddCommand(memorySkillsPreviewCmd)
	memorySkillsCmd.AddCommand(memorySkillsInstallCmd)

	for _, c := range []*cobra.Command{memoryListCmd, memoryShowCmd, memoryEvaluationsRunCmd, memoryEvaluationsListCmd, memoryEvaluationsShowCmd, memoryCandidatesListCmd, memoryCandidatesShowCmd, memoryCandidatesCreateCmd, memoryCandidatesApproveCmd, memoryCandidatesRejectCmd, memoryCandidatesSupersedeCmd, memorySkillsPreviewCmd, memorySkillsInstallCmd} {
		c.Flags().BoolVar(&memoryOpts.userMode, "user", true, "Use per-user endpoint paths")
		c.Flags().BoolVar(&memoryOpts.systemMode, "system", false, "Use system endpoint paths")
		c.Flags().StringVar(&memoryOpts.logPath, "log-path", "", "Runtime JSONL log path")
		c.Flags().BoolVar(&memoryOpts.jsonOutput, "json", false, "Print machine-readable JSON")
		c.Flags().StringVar(&memoryOpts.projectPath, "project", "", "Project path for memory scoping (defaults to the trace's repository, then the current directory)")
	}
	memoryCandidatesCreateCmd.Flags().StringVar(&memoryOpts.traceID, "trace", "", "Trace ID the lesson was learned from (required)")
	_ = memoryCandidatesCreateCmd.MarkFlagRequired("trace")
	memoryCandidatesCreateCmd.Flags().StringVar(&memoryOpts.title, "title", "", "Title for the memory (required)")
	memoryCandidatesCreateCmd.Flags().StringVar(&memoryOpts.body, "body", "", "Lesson text (required unless --body-file is given)")
	memoryCandidatesCreateCmd.Flags().StringVar(&memoryOpts.bodyFile, "body-file", "", "Read the lesson text from a file, or - for stdin")
	memoryCandidatesCreateCmd.Flags().StringVar(&memoryOpts.applies, "applicability", "", "When the memory applies, such as \"when package smoke fails on macOS\"")
	memoryCandidatesCreateCmd.Flags().StringVar(&memoryOpts.kind, "kind", "", "Memory kind: workflow, correction, debugging_pattern, gotcha, or convention (required)")
	memoryCandidatesCreateCmd.Flags().StringSliceVar(&memoryOpts.tags, "tag", nil, "Tag for the memory; repeat or comma-separate (defaults to beacon, the kind, and the harness)")
	for _, c := range []*cobra.Command{memoryListCmd, memoryEvaluationsRunCmd, memoryEvaluationsListCmd, memoryCandidatesListCmd} {
		c.Flags().IntVar(&memoryOpts.limit, "limit", 25, "Limit returned traces or evaluations")
		c.Flags().IntVar(&memoryOpts.page, "page", 1, "Page number for collection output")
		c.Flags().StringVarP(&memoryOpts.query, "query", "q", "", "Free-text query")
	}
	memoryCandidatesListCmd.Flags().StringVar(&memoryOpts.state, "state", "", "Filter candidates by state")
	memoryCandidatesListCmd.Flags().StringVar(&memoryOpts.kind, "kind", "", "Filter candidates by memory kind")
	memoryListCmd.Flags().StringVar(&memoryOpts.kind, "kind", "", "Filter approved memory by kind")
	memoryCandidatesApproveCmd.Flags().StringVar(&memoryOpts.title, "title", "", "Title for the approved memory (defaults to the candidate title)")
	memoryCandidatesApproveCmd.Flags().StringVar(&memoryOpts.body, "body", "", "Lesson text for the approved memory (defaults to the candidate body)")
	memoryCandidatesApproveCmd.Flags().StringVar(&memoryOpts.bodyFile, "body-file", "", "Read the lesson text from a file, or - for stdin")
	memoryCandidatesApproveCmd.Flags().StringVar(&memoryOpts.applies, "applicability", "", "When the memory applies, such as \"when package smoke fails on macOS\"")
	memoryCandidatesApproveCmd.Flags().StringVar(&memoryOpts.kind, "kind", "", "Memory kind: workflow, correction, debugging_pattern, gotcha, or convention")
	memoryCandidatesApproveCmd.Flags().StringSliceVar(&memoryOpts.tags, "tag", nil, "Tag for the approved memory; repeat or comma-separate (replaces the candidate tags)")
	for _, c := range []*cobra.Command{memoryCandidatesApproveCmd, memoryCandidatesRejectCmd, memoryCandidatesSupersedeCmd} {
		c.Flags().StringVar(&memoryOpts.reason, "reason", "", "Review reason recorded with the candidate")
	}
	memoryCandidatesSupersedeCmd.Flags().StringVar(&memoryOpts.replacement, "replacement", "", "Approved memory ID that supersedes this candidate")
	memorySkillsInstallCmd.Flags().BoolVar(&memoryOpts.force, "force", false, "Overwrite an existing generated skill")
	memoryEvaluationsRunCmd.Flags().StringVar(&memoryOpts.harness, "harness", "", "Filter traces by harness")
	memoryEvaluationsRunCmd.Flags().StringVar(&memoryOpts.traceID, "trace", "", "Evaluate a single trace ID")
	memoryEvaluationsRunCmd.Flags().StringVar(&memoryOpts.since, "since", "", "RFC3339 lower time bound, inclusive")
	memoryEvaluationsRunCmd.Flags().StringVar(&memoryOpts.until, "until", "", "RFC3339 upper time bound, inclusive")
	memoryEvaluationsRunCmd.Flags().BoolVar(&memoryOpts.dryRun, "dry-run", false, "Preview selected traces, evaluator calls, and estimated cost without writing evaluations")
	memoryEvaluationsRunCmd.Flags().StringVar(&memoryOpts.evaluator, "evaluator", "", "Evaluator provider: jev or subq (defaults to BEACON_EVALUATOR, then jev)")
	memoryEvaluationsRunCmd.Flags().StringVar(&memoryOpts.jevEndpoint, "jev-endpoint", "", "Jev System One endpoint (defaults to BEACON_JEV_ENDPOINT, then "+learning.DefaultJevEndpoint+")")
	memoryEvaluationsRunCmd.Flags().StringVar(&memoryOpts.jevAPIKey, "jev-api-key", "", "Jev API key (defaults to TYPESAFE_API_KEY, then BEACON_JEV_API_KEY)")
	memoryEvaluationsRunCmd.Flags().StringVar(&memoryOpts.jevModel, "jev-model", "", "Jev model name, such as jev-latest or a pinned Jev version (defaults to BEACON_JEV_MODEL, then "+learning.DefaultJevModel+")")
	memoryEvaluationsRunCmd.Flags().Float64Var(&memoryOpts.costPerTrace, "cost-per-trace", learning.DefaultCostPerTrace, "Estimated evaluator cost per trace in USD, for Jev or SubQ")
	// --jev-cost-per-trace is the pre-SubQ name, kept so existing scripts still work.
	memoryEvaluationsRunCmd.Flags().Float64Var(&memoryOpts.costPerTrace, "jev-cost-per-trace", learning.DefaultCostPerTrace, "Estimated evaluator cost per trace in USD")
	_ = memoryEvaluationsRunCmd.Flags().MarkDeprecated("jev-cost-per-trace", "use --cost-per-trace")
	memoryEvaluationsRunCmd.Flags().StringVar(&memoryOpts.subqEndpoint, "subq-endpoint", "", "SubQ Decisions API endpoint (defaults to BEACON_SUBQ_ENDPOINT, then "+learning.DefaultSubQEndpoint+")")
	memoryEvaluationsRunCmd.Flags().StringVar(&memoryOpts.subqAPIKey, "subq-api-key", "", "SubQ API key (defaults to SUBQ_API_KEY, then BEACON_SUBQ_API_KEY)")
	memoryEvaluationsRunCmd.Flags().StringVar(&memoryOpts.subqModel, "subq-model", "", "SubQ System One model name (defaults to BEACON_SUBQ_MODEL, then "+learning.DefaultSubQModel+")")
	memoryEvaluationsRunCmd.Flags().DurationVar(&memoryOpts.timeout, "timeout", 10*time.Second, "Evaluator request timeout")
}

func runMemoryList(cmd *cobra.Command, args []string) error {
	query, err := memoryQuery()
	if err != nil {
		return err
	}
	query.Kind = memoryOpts.kind
	memories, err := memoryStore().ListMemories(query)
	if err != nil {
		return err
	}
	if memoryOpts.jsonOutput {
		if memories == nil {
			memories = []asymptoteobserve.LearningMemoryV1{}
		}
		return json.NewEncoder(cmd.OutOrStdout()).Encode(memories)
	}
	for _, memory := range memories {
		fmt.Fprintf(cmd.OutOrStdout(), "%s\t%s\t%s\n", memory.ID, memory.Kind, memory.Title)
	}
	return nil
}

func runMemoryShow(cmd *cobra.Command, args []string) error {
	memory, ok, err := memoryStore().GetMemory(args[0])
	if err != nil {
		return err
	}
	if !ok || memory.SupersededBy != "" {
		return fmt.Errorf("memory not found: %s", args[0])
	}
	if memoryOpts.jsonOutput {
		return json.NewEncoder(cmd.OutOrStdout()).Encode(memory)
	}
	fmt.Fprintf(cmd.OutOrStdout(), "%s\t%s\n", memory.ID, memory.Kind)
	fmt.Fprintln(cmd.OutOrStdout(), memory.Title)
	if memory.Applicability != "" {
		fmt.Fprintln(cmd.OutOrStdout(), "Applies "+memory.Applicability)
	}
	fmt.Fprintln(cmd.OutOrStdout())
	fmt.Fprintln(cmd.OutOrStdout(), memory.Body)
	for _, evidence := range memory.Evidence {
		fmt.Fprintf(cmd.OutOrStdout(), "\nTrace %s", evidence.TraceID)
		if evidence.Summary != "" {
			fmt.Fprintf(cmd.OutOrStdout(), ": %s", evidence.Summary)
		}
	}
	if len(memory.Evidence) > 0 {
		fmt.Fprintln(cmd.OutOrStdout())
	}
	return nil
}

func runMemoryEvaluationsRun(cmd *cobra.Command, args []string) error {
	store := memoryStore()
	inputs, err := selectedEvaluationInputs()
	if err != nil {
		return err
	}
	evaluatorOpts, err := evaluatorOptions()
	if err != nil {
		return err
	}
	result := evaluationRunResult{
		DryRun:           memoryOpts.dryRun,
		StorePath:        store.Path(),
		TraceCount:       len(inputs),
		EstimatedCalls:   len(inputs),
		EstimatedCostUSD: float64(len(inputs)) * memoryOpts.costPerTrace,
	}
	if strings.TrimSpace(memoryOpts.projectPath) != "" {
		project, err := learning.ResolveProject(memoryOpts.projectPath)
		if err != nil {
			return err
		}
		result.Project = &project
	}
	for _, input := range inputs {
		input.DryRun = memoryOpts.dryRun
		if memoryOpts.dryRun {
			result.Previews = append(result.Previews, learning.Preview(input, evaluatorOpts))
			continue
		}
		ctx := cmd.Context()
		if ctx == nil {
			ctx = context.Background()
		}
		eval, err := learning.Evaluate(ctx, evaluatorOpts, input)
		if err != nil {
			return err
		}
		if err := store.PutEvaluation(eval); err != nil {
			return err
		}
		result.Evaluations = append(result.Evaluations, eval)
		if candidate, ok := learning.CandidateFromEvaluation(eval); ok {
			stored, err := store.InsertCandidate(candidate)
			if err != nil {
				return err
			}
			result.Candidates = append(result.Candidates, stored)
		}
	}
	if memoryOpts.jsonOutput {
		return json.NewEncoder(cmd.OutOrStdout()).Encode(result)
	}
	if result.DryRun {
		fmt.Fprintf(cmd.OutOrStdout(), "Selected %d trace(s); estimated %s calls: %d; estimated cost: $%.5f\n", result.TraceCount, evaluatorDisplayName(evaluatorOpts.Provider), result.EstimatedCalls, result.EstimatedCostUSD)
		for _, preview := range result.Previews {
			fmt.Fprintf(cmd.OutOrStdout(), "%s\t%s\t%s\t$%.5f\n", preview.TraceID, preview.Title, firstNonEmpty(preview.Project.Path, preview.Project.ID), preview.EstimatedCostUSD)
		}
		return nil
	}
	fmt.Fprintf(cmd.OutOrStdout(), "Evaluated %d trace(s); wrote results to %s\n", len(result.Evaluations), store.Path())
	for _, eval := range result.Evaluations {
		fmt.Fprintf(cmd.OutOrStdout(), "%s\t%s\t%.2f\t%s\n", eval.ID, eval.Trace.ID, eval.Score, eval.Status)
	}
	for _, eval := range result.Evaluations {
		if eval.Status != asymptoteobserve.LearningEvaluationStatusCompleted {
			continue
		}
		if ok, reason := learning.PromotionDecision(eval); !ok {
			fmt.Fprintf(cmd.OutOrStdout(), "Not promoted: %s (%s)\n", eval.ID, reason)
		}
	}
	for _, candidate := range result.Candidates {
		fmt.Fprintf(cmd.OutOrStdout(), "%s\t%s\t%s\n", candidate.ID, candidate.State, candidate.Kind)
	}
	return nil
}

func runMemoryEvaluationsList(cmd *cobra.Command, args []string) error {
	query, err := memoryQuery()
	if err != nil {
		return err
	}
	evals, err := memoryStore().ListEvaluations(query)
	if err != nil {
		return err
	}
	if memoryOpts.jsonOutput {
		return json.NewEncoder(cmd.OutOrStdout()).Encode(evals)
	}
	for _, eval := range evals {
		fmt.Fprintf(cmd.OutOrStdout(), "%s\t%s\t%s\t%.2f\t%s\n", eval.ID, eval.Trace.ID, eval.Status, eval.Score, eval.Trace.Title)
	}
	return nil
}

func runMemoryEvaluationsShow(cmd *cobra.Command, args []string) error {
	eval, ok, err := memoryStore().GetEvaluation(args[0])
	if err != nil {
		return err
	}
	if !ok {
		return fmt.Errorf("evaluation not found: %s", args[0])
	}
	if memoryOpts.jsonOutput {
		return json.NewEncoder(cmd.OutOrStdout()).Encode(eval)
	}
	fmt.Fprintf(cmd.OutOrStdout(), "%s\t%s\t%s\t%.2f\n", eval.ID, eval.Trace.ID, eval.Status, eval.Score)
	for _, question := range eval.Questions {
		fmt.Fprintf(cmd.OutOrStdout(), "%s\t%.2f\t%.2f\t%s\n", question.ID, question.Probability, question.Confidence, learning.QuestionReason(question))
	}
	return nil
}

func runMemoryCandidatesList(cmd *cobra.Command, args []string) error {
	query, err := memoryCandidateQuery()
	if err != nil {
		return err
	}
	candidates, err := memoryStore().ListCandidates(query)
	if err != nil {
		return err
	}
	if memoryOpts.jsonOutput {
		return json.NewEncoder(cmd.OutOrStdout()).Encode(candidates)
	}
	for _, candidate := range candidates {
		fmt.Fprintf(cmd.OutOrStdout(), "%s\t%s\t%s\t%s\n", candidate.ID, candidate.State, candidate.Kind, candidate.Title)
	}
	return nil
}

func runMemoryCandidatesShow(cmd *cobra.Command, args []string) error {
	candidate, ok, err := memoryStore().GetCandidate(args[0])
	if err != nil {
		return err
	}
	if !ok {
		return fmt.Errorf("candidate not found: %s", args[0])
	}
	if memoryOpts.jsonOutput {
		return json.NewEncoder(cmd.OutOrStdout()).Encode(candidate)
	}
	printCandidate(cmd, candidate)
	return nil
}

func runMemoryCandidatesCreate(cmd *cobra.Command, args []string) error {
	if strings.TrimSpace(memoryOpts.traceID) == "" {
		return fmt.Errorf("--trace is required")
	}
	lesson, err := memoryApprovalEdits(cmd)
	if err != nil {
		return err
	}
	show, ok, err := dashboard.ShowTrace(memoryLogPath(), memoryOpts.traceID, dashboard.TraceQuery{EventQuery: dashboard.EventQuery{NoLimit: true}})
	if err != nil {
		return err
	}
	if !ok {
		return fmt.Errorf("trace not found: %s", memoryOpts.traceID)
	}
	project, err := learning.ProjectForTrace(memoryOpts.projectPath, show.Trace)
	if err != nil {
		return err
	}
	candidate, err := learning.CandidateFromTrace(project, show, lesson)
	if err != nil {
		return err
	}
	candidate, err = memoryStore().InsertCandidate(candidate)
	if err != nil {
		return err
	}
	if memoryOpts.jsonOutput {
		return json.NewEncoder(cmd.OutOrStdout()).Encode(candidate)
	}
	fmt.Fprintf(cmd.OutOrStdout(), "%s\t%s\t%s\t%s\n", candidate.ID, candidate.State, candidate.Kind, firstNonEmpty(candidate.Project.Path, candidate.Project.ID))
	return nil
}

func runMemoryCandidatesApprove(cmd *cobra.Command, args []string) error {
	edits, err := memoryApprovalEdits(cmd)
	if err != nil {
		return err
	}
	candidate, memory, err := learning.ApproveCandidateWithEdits(memoryStore(), args[0], memoryOpts.reason, edits)
	if err != nil {
		return err
	}
	if memoryOpts.jsonOutput {
		return json.NewEncoder(cmd.OutOrStdout()).Encode(map[string]interface{}{"candidate": candidate, "memory": memory})
	}
	fmt.Fprintf(cmd.OutOrStdout(), "Approved %s as memory %s\n", candidate.ID, memory.ID)
	return nil
}

// memoryApprovalEdits collects the reviewer-authored fields for an approval.
// --body and --body-file are exclusive so it is never ambiguous which text was
// approved.
func memoryApprovalEdits(cmd *cobra.Command) (learning.ApprovalEdits, error) {
	body := memoryOpts.body
	if memoryOpts.bodyFile != "" {
		if strings.TrimSpace(body) != "" {
			return learning.ApprovalEdits{}, fmt.Errorf("use --body or --body-file, not both")
		}
		var raw []byte
		var err error
		if memoryOpts.bodyFile == "-" {
			raw, err = io.ReadAll(cmd.InOrStdin())
		} else {
			raw, err = os.ReadFile(memoryOpts.bodyFile)
		}
		if err != nil {
			return learning.ApprovalEdits{}, fmt.Errorf("read --body-file: %w", err)
		}
		body = string(raw)
	}
	return learning.ApprovalEdits{
		Title:         memoryOpts.title,
		Body:          body,
		Applicability: memoryOpts.applies,
		Kind:          memoryOpts.kind,
		Tags:          memoryOpts.tags,
	}, nil
}

func runMemoryCandidatesReject(cmd *cobra.Command, args []string) error {
	candidate, err := learning.RejectCandidate(memoryStore(), args[0], memoryOpts.reason)
	if err != nil {
		return err
	}
	if memoryOpts.jsonOutput {
		return json.NewEncoder(cmd.OutOrStdout()).Encode(candidate)
	}
	fmt.Fprintf(cmd.OutOrStdout(), "Rejected %s\n", candidate.ID)
	return nil
}

func runMemoryCandidatesSupersede(cmd *cobra.Command, args []string) error {
	candidate, err := learning.SupersedeCandidate(memoryStore(), args[0], memoryOpts.replacement, memoryOpts.reason)
	if err != nil {
		return err
	}
	if memoryOpts.jsonOutput {
		return json.NewEncoder(cmd.OutOrStdout()).Encode(candidate)
	}
	fmt.Fprintf(cmd.OutOrStdout(), "Superseded %s with %s\n", candidate.ID, candidate.SupersededBy)
	return nil
}

func runMemorySkillsPreview(cmd *cobra.Command, args []string) error {
	candidate, memory, err := learning.CandidateMemoryForSkill(memoryStore(), args[0])
	if err != nil {
		return err
	}
	content := learning.RenderSkill(candidate, memory)
	result := learning.SkillInstallResult{Slug: learning.SkillSlug(memory), Content: content}
	if memoryOpts.jsonOutput {
		return json.NewEncoder(cmd.OutOrStdout()).Encode(result)
	}
	fmt.Fprint(cmd.OutOrStdout(), content)
	return nil
}

func runMemorySkillsInstall(cmd *cobra.Command, args []string) error {
	candidate, memory, err := learning.CandidateMemoryForSkill(memoryStore(), args[0])
	if err != nil {
		return err
	}
	projectPath := memoryOpts.projectPath
	if projectPath == "" {
		projectPath = firstNonEmpty(memory.Project.Path, candidate.Project.Path)
	}
	result, err := learning.InstallSkill(projectPath, candidate, memory, memoryOpts.force)
	if err != nil {
		return err
	}
	if memoryOpts.jsonOutput {
		return json.NewEncoder(cmd.OutOrStdout()).Encode(result)
	}
	fmt.Fprintf(cmd.OutOrStdout(), "Installed %s\n", result.Path)
	return nil
}

// selectedEvaluationInputs picks the traces to evaluate. Each trace is scoped to its
// own repository through ProjectForTrace unless --project pins one. Without --trace,
// traces that are a single event with no session, such as OTLP metric samples, are
// skipped: they carry nothing to learn from and would otherwise crowd out sessions
// because each fresh sample sorts to the top.
func selectedEvaluationInputs() ([]learning.EvaluationInput, error) {
	logPath := memoryLogPath()
	// The evaluator bounds its projection after sampling the actual head and tail.
	if memoryOpts.traceID != "" {
		show, ok, err := dashboard.ShowTrace(logPath, memoryOpts.traceID, dashboard.TraceQuery{EventQuery: dashboard.EventQuery{NoLimit: true}})
		if err != nil {
			return nil, err
		}
		if !ok {
			return nil, fmt.Errorf("trace not found: %s", memoryOpts.traceID)
		}
		project, err := learning.ProjectForTrace(memoryOpts.projectPath, show.Trace)
		if err != nil {
			return nil, err
		}
		return []learning.EvaluationInput{{Project: project, Trace: show}}, nil
	}
	query := dashboard.TraceQuery{
		EventQuery: dashboard.EventQuery{
			Q:       memoryOpts.query,
			Harness: memoryOpts.harness,
		},
		Limit: memoryOpts.limit,
		Page:  memoryOpts.page,
	}
	var err error
	if query.Since, err = parseMemoryTime("since", memoryOpts.since); err != nil {
		return nil, err
	}
	if query.Until, err = parseMemoryTime("until", memoryOpts.until); err != nil {
		return nil, err
	}
	traces, err := dashboard.ReadTraceList(logPath, query)
	if err != nil {
		return nil, err
	}
	inputs := make([]learning.EvaluationInput, 0, len(traces.Traces))
	for _, summary := range traces.Traces {
		if strings.HasPrefix(summary.ID, "event:") {
			continue
		}
		show, ok, err := dashboard.ShowTrace(logPath, summary.ID, dashboard.TraceQuery{EventQuery: dashboard.EventQuery{NoLimit: true}})
		if err != nil {
			return nil, err
		}
		if !ok {
			continue
		}
		project, err := learning.ProjectForTrace(memoryOpts.projectPath, show.Trace)
		if err != nil {
			return nil, err
		}
		inputs = append(inputs, learning.EvaluationInput{Project: project, Trace: show})
	}
	return inputs, nil
}

func memoryQuery() (learning.Query, error) {
	project, err := learning.ResolveProject(memoryOpts.projectPath)
	if err != nil {
		return learning.Query{}, err
	}
	return learning.Query{
		ProjectID: project.ID,
		Q:         memoryOpts.query,
		Limit:     memoryOpts.limit,
		Page:      memoryOpts.page,
	}, nil
}

func memoryCandidateQuery() (learning.Query, error) {
	query, err := memoryQuery()
	if err != nil {
		return learning.Query{}, err
	}
	query.State = memoryOpts.state
	query.Kind = memoryOpts.kind
	return query, nil
}

func printCandidate(cmd *cobra.Command, candidate asymptoteobserve.LearningCandidateV1) {
	fmt.Fprintf(cmd.OutOrStdout(), "%s\t%s\t%s\n", candidate.ID, candidate.State, candidate.Kind)
	fmt.Fprintln(cmd.OutOrStdout(), candidate.Title)
	fmt.Fprintln(cmd.OutOrStdout())
	fmt.Fprintln(cmd.OutOrStdout(), candidate.Body)
}

func memoryStore() *learning.Store {
	return learning.Open(learning.PathForRuntimeLog(memoryLogPath()))
}

func memoryLogPath() string {
	runtimeLog := lifecycle.ResolveRuntimeLog(memoryUserMode(), memoryOpts.logPath)
	return runtimeLog.EffectiveLogPath
}

func memoryUserMode() bool {
	return memoryOpts.userMode && !memoryOpts.systemMode
}

func parseMemoryTime(name, value string) (time.Time, error) {
	if strings.TrimSpace(value) == "" {
		return time.Time{}, nil
	}
	parsed, err := time.Parse(time.RFC3339, value)
	if err != nil {
		return time.Time{}, fmt.Errorf("%s must be RFC3339: %w", name, err)
	}
	return parsed, nil
}

// evaluatorOptions picks the provider from --evaluator, then BEACON_EVALUATOR,
// then Jev, and resolves that provider's settings.
func evaluatorOptions() (learning.EvaluatorOptions, error) {
	provider := learning.NormalizeProvider(firstNonEmpty(memoryOpts.evaluator, os.Getenv("BEACON_EVALUATOR")))
	switch provider {
	case learning.ProviderJev:
		return jevEvaluatorOptions(), nil
	case learning.ProviderSubQ:
		return subqEvaluatorOptions(), nil
	}
	_, _, err := learning.ProviderDefaults(provider)
	return learning.EvaluatorOptions{}, err
}

func evaluatorDisplayName(provider string) string {
	if learning.NormalizeProvider(provider) == learning.ProviderSubQ {
		return "SubQ"
	}
	return "Jev"
}

// subqEvaluatorOptions resolves each SubQ setting from its flag, then the
// environment, then the built-in default, the same way as the Jev settings.
func subqEvaluatorOptions() learning.EvaluatorOptions {
	return learning.EvaluatorOptions{
		Provider:     learning.ProviderSubQ,
		Endpoint:     firstNonEmpty(memoryOpts.subqEndpoint, os.Getenv("BEACON_SUBQ_ENDPOINT"), learning.DefaultSubQEndpoint),
		APIKey:       firstNonEmpty(memoryOpts.subqAPIKey, os.Getenv("SUBQ_API_KEY"), os.Getenv("BEACON_SUBQ_API_KEY")),
		Model:        firstNonEmpty(memoryOpts.subqModel, os.Getenv("BEACON_SUBQ_MODEL"), learning.DefaultSubQModel),
		CostPerTrace: memoryOpts.costPerTrace,
		Timeout:      memoryOpts.timeout,
	}
}

// jevEvaluatorOptions resolves each Jev setting from its flag, then the environment,
// then the built-in default. The flags must not carry the defaults themselves, or the
// environment variables documented for them would never be consulted.
func jevEvaluatorOptions() learning.EvaluatorOptions {
	return learning.EvaluatorOptions{
		Provider:     learning.ProviderJev,
		Endpoint:     firstNonEmpty(memoryOpts.jevEndpoint, os.Getenv("BEACON_JEV_ENDPOINT"), learning.DefaultJevEndpoint),
		APIKey:       firstNonEmpty(memoryOpts.jevAPIKey, os.Getenv("TYPESAFE_API_KEY"), os.Getenv("BEACON_JEV_API_KEY")),
		Model:        firstNonEmpty(memoryOpts.jevModel, os.Getenv("BEACON_JEV_MODEL"), learning.DefaultJevModel),
		CostPerTrace: memoryOpts.costPerTrace,
		Timeout:      memoryOpts.timeout,
	}
}

func firstNonEmpty(values ...string) string {
	for _, value := range values {
		if strings.TrimSpace(value) != "" {
			return strings.TrimSpace(value)
		}
	}
	return ""
}