trajectory

Documentation

Overview

Package trajectory holds the capture queue + label sidecar for the P6 agentic- trace flywheel. When enabled (OFF by default), a sampled fraction of completed standalone agent goals is appended here as an Item; an offline drain replays each goal under a candidate planner prompt, judges goal-satisfaction, and writes correctness labels to a sidecar (via ledger.AppendLabel — NEVER the savings ledger). The queue mechanics mirror internal/shadow (append-only Enqueue + atomic rename-aside Drain with crash recovery + corrupt-line skip).

Index

• Constants
• func AppendLabel(path string, l Label) error
• func Capture(path string, rate float64, it Item) (bool, error)
• func Enqueue(path string, it Item) error
• func JudgeGoalReached(ctx context.Context, ...) (decision, reason string, ok bool)
• func LabelQueue(ctx context.Context, items []Item, cap int, d LabelDeps) (written int)
• type Item
  • func Drain(path string) ([]Item, error)
• type Label
  • func ReadLabels(path string) ([]Label, error)
• type LabelDeps

Constants

const SchemaVersion = 1

SchemaVersion is the Item format version (bump on a breaking field change).

Functions

func AppendLabel

func AppendLabel(path string, l Label) error

AppendLabel appends one label as a JSON line to the sidecar (concurrency-safe). Mirrors ledger.AppendLabel's mechanics; it is NOT ledger.Record — the savings ledger is never touched.

func Capture

func Capture(path string, rate float64, it Item) (bool, error)

Capture samples (rate in [0,1]) and, on a hit, appends the item. Returns (captured, err). rate<=0 never captures; rate>=1 always. The CALLER must treat any error as non-fatal — capture is best-effort and must never affect the run.

func Enqueue

func Enqueue(path string, it Item) error

Enqueue appends one item as a JSON line (concurrency-safe).

func JudgeGoalReached

func JudgeGoalReached(ctx context.Context, runTier func(context.Context, core.Request, string) (core.Result, bool), model, goal, output string) (decision, reason string, ok bool)

JudgeGoalReached asks a local triage model whether the agent's final answer accomplished the goal — the signal StopReason "done" does NOT provide. Reuses the proven triage task + its GBNF grammar via RunTier(record=false); returns (decision yes|no|unsure, reason, ok). ok=false ⇒ un-judgeable, caller skips.

func LabelQueue

func LabelQueue(ctx context.Context, items []Item, cap int, d LabelDeps) (written int)

LabelQueue judges up to cap trajectories (cap<=0 = all) for goal satisfaction and appends a label per judged item to the sidecar. Fail-safe: an un-judgeable or un-writable item is skipped, never aborts the batch. Returns labels written.

Types

type Item

type Item struct {
	TS         int64    `json:"ts"`
	Schema     int      `json:"schema"`
	ID         string   `json:"id"`
	Goal       string   `json:"goal"`
	Envelope   []string `json:"envelope"` // capabilities granted this run: read/write/fetch/shell
	Tools      []string `json:"tools"`    // tool names called, in order (the trajectory shape)
	Steps      int      `json:"steps"`
	StopReason string   `json:"stop_reason"`
	Output     string   `json:"output"`
	TracePath  string   `json:"trace_path,omitempty"`
}

Item is one captured agent trajectory — enough to replay + judge it offline. The full transcript stays in the standalone trace file, referenced by TracePath.

func Drain

func Drain(path string) ([]Item, error)

Drain atomically claims the queue (rename aside), reads it, and deletes the claim — the cross-process cursor + crash-recovery + corrupt-line-skip pattern from internal/shadow, so an item is never lost to a read/truncate race. A missing/empty queue returns (nil, nil).

type Label

type Label struct {
	Schema      int      `json:"schema"`
	TS          int64    `json:"ts"`
	ID          string   `json:"id"`
	Goal        string   `json:"goal"`
	Envelope    []string `json:"envelope"`
	Tools       []string `json:"tools"`
	Steps       int      `json:"steps"`
	StopReason  string   `json:"stop_reason"`
	Decision    string   `json:"decision"`     // judge verdict: yes | no | unsure
	GoalReached bool     `json:"goal_reached"` // decision == "yes"
	JudgeReason string   `json:"judge_reason,omitempty"`
}

Label is one manufactured agent-trajectory label: the captured trajectory plus the goal-satisfaction judge's verdict. Written to a SIDECAR (never the savings ledger) so the flywheel's ledger-pristine invariant holds by construction.

func ReadLabels

func ReadLabels(path string) ([]Label, error)

ReadLabels loads all manufactured labels from the sidecar (corrupt lines skipped).

type LabelDeps

type LabelDeps struct {
	// RunTier runs req on the named model (record=false — it must NOT write the
	// savings ledger, cache, or shadow). The judge routes a triage through it.
	RunTier func(ctx context.Context, req core.Request, model string) (core.Result, bool)
	// JudgeModel is the model the goal-satisfaction judge runs on.
	JudgeModel string
	// AppendLabel writes one manufactured label to the sidecar.
	AppendLabel func(path string, l Label) error
	// LabelsPath is the trajectory-label sidecar file.
	LabelsPath string
}

LabelDeps are the injected dependencies for LabelQueue — fully fakeable for a unit test with no model or filesystem.