trajectory

type BackgroundMemberOutcome struct {
	TaskID string `json:"task_id"`
	Status string `json:"status"`

	// ResultRef is the ArtifactRef key for the task result, or empty
	// when the task did not produce a heavy result.
	ResultRef string `json:"result_ref,omitempty"`

	// ErrorCode is the failure code when Status == "failed".
	ErrorCode string `json:"error_code,omitempty"`

	// ErrorMessage is the human-readable failure message when
	// Status == "failed".
	ErrorMessage string `json:"error_message,omitempty"`
}

type BackgroundResult struct {
	// GroupID is the resolved group's identifier.
	GroupID string `json:"group_id"`

	// Status is the group's terminal status ("completed" /
	// "cancelled").
	Status string `json:"status"`

	// ResolvedAt is the resolution wall-clock timestamp.
	ResolvedAt time.Time `json:"resolved_at,omitempty"`

	// Members is the per-member outcome summary (Result / Error /
	// Cancelled, ref-shaped per D-026).
	Members []BackgroundMemberOutcome `json:"members,omitempty"`

	// Reason is the cancel reason when Status == "cancelled";
	// empty otherwise.
	Reason string `json:"reason,omitempty"`
}

type ErrToolContextLost struct {
	// Handle is the missing HandleID.
	Handle HandleID
}

type ErrUnserializable struct {
	// Field is the dotted path to the offending leaf, rooted at
	// "Trajectory". Example: "Trajectory.Steps[2].Action.fn".
	Field string
}

type FailureRecord struct {
	// Code is the failure classification ("schema_repair_exhausted",
	// "arg_fill_failed", "graceful_failure", etc.).
	Code string `json:"code"`

	// Message is the human-readable failure message.
	Message string `json:"message"`

	// Attempts is the count of repair attempts before giving up.
	Attempts int `json:"attempts"`
}

type HandleID string

type HandleRegistry interface {
	// Set installs value under id. Re-installing an existing id
	// overwrites silently (standard map semantics). The runtime is
	// responsible for collision-free HandleID generation (ULIDs are
	// the recommended convention).
	Set(id HandleID, value any)

	// Get retrieves the value under id. Returns
	// (nil, ErrToolContextLost{Handle: id}) on miss — never
	// (nil, nil). This is the fail-loudly contract that closes the
	// predecessor's silent-tool-context-loss bug.
	Get(id HandleID) (any, error)

	// Delete removes the mapping for id. Deleting a non-existent id
	// is a no-op (returns no error).
	Delete(id HandleID)
}

type ResumeHint struct {
	// PauseToken is the opaque token the runtime issued at pause time.
	PauseToken string `json:"pause_token"`

	// ResumedAt is the wall-clock resume timestamp.
	ResumedAt time.Time `json:"resumed_at,omitempty"`

	// ResumePayload is the sanitised payload the resumer supplied
	// (APPROVE/REJECT decision, USER_MESSAGE content, etc.).
	ResumePayload map[string]any `json:"resume_payload,omitempty"`
}

type Source struct {
	// Kind is the source kind: "tool" / "memory" / "skill" /
	// "user_message" / "artifact".
	Kind string `json:"kind"`

	// Ref is the source-specific reference (tool name + step index;
	// memory key; skill id; etc.).
	Ref string `json:"ref"`
}

type SteeringInjection struct {
	// Kind is the control event type (CtlInjectContext, CtlRedirect, etc).
	Kind string `json:"kind"`

	// Payload is the sanitised payload the planner sees.
	Payload map[string]any `json:"payload,omitempty"`

	// AtStep is the trajectory step index at which the injection
	// was observed.
	AtStep int `json:"at_step"`
}

type Step struct {
	// Action is the Decision the planner returned for this step.
	// Typed as `any` to avoid a cycle with the planner package;
	// must be JSON-encodable (struct with JSON tags or
	// map[string]any).
	Action any `json:"action,omitempty"`

	// ReasoningTrace is the provider-side thinking trace captured for
	// this step (Phase 83e — D-147). The planner stamps it from
	// `llm.CompleteResponse.Reasoning` after the step's LLM call.
	// It is captured content, kept for observability and `inspect-runs`
	// — it is NEVER re-injected into a subsequent prompt unless the
	// agent's `ReasoningReplay` mode is `text` (D-148). Empty when the
	// provider surfaced no reasoning. Reasoning content can be
	// sensitive; any sink that persists or logs it routes through the
	// audit redactor (CLAUDE.md §7).
	ReasoningTrace string `json:"reasoning_trace,omitempty"`

	// AssistantPreamble is the natural-language content the assistant
	// emitted alongside the tool_call on this step — the "preamble"
	// prose providers stream as `delta.content` while the structured
	// `tool_calls` block is being assembled. The planner stamps it
	// from `llm.CompleteResponse.Content` after the step's LLM call.
	// The trajectory renderer replays it as the assistant message's
	// content on the next turn so the model retains its narrative
	// thread across steps.
	//
	// Distinct from `ReasoningTrace` which is the provider-side
	// thinking channel (opt-in, often empty, sometimes redacted).
	// AssistantPreamble is the model's visible prose preamble —
	// always part of the wire shape, no opt-in required. Empty when
	// the model emitted a tool_call with no preamble.
	AssistantPreamble string `json:"assistant_preamble,omitempty"`

	// Observation is the runtime's executed-decision result. Shape
	// depends on the Decision: a CallTool yields a ToolResult; a
	// SpawnTask yields a TaskHandle; etc.
	Observation any `json:"observation,omitempty"`

	// LLMObservation is the projection of Observation that becomes
	// the next prompt's input. Distinct from Observation so heavy
	// blobs can be summarised before reaching the LLM (D-026).
	LLMObservation any `json:"llm_observation,omitempty"`

	// Error captures a step-level failure (tool error, repair
	// failure). Empty when the step succeeded.
	Error string `json:"error,omitempty"`

	// Failure is the structured failure record (Phase 44 repair
	// pipeline populates).
	Failure *FailureRecord `json:"failure,omitempty"`

	// Streams captures per-chunk stream outputs the runtime
	// collected during the step.
	Streams map[string][]StreamChunk `json:"streams,omitempty"`

	// StartedAt is the wall-clock step-start timestamp.
	StartedAt time.Time `json:"started_at,omitempty"`

	// LatencyMS is the step end-to-end latency in milliseconds.
	LatencyMS int64 `json:"latency_ms,omitempty"`

	// TokenEstimate is the LLM token consumption estimate for this
	// step (input + output combined).
	TokenEstimate int `json:"token_estimate,omitempty"`
}

type StreamChunk struct {
	// At is the wall-clock chunk-arrival timestamp.
	At time.Time `json:"at,omitempty"`

	// Data is the raw chunk payload (typically text bytes).
	Data []byte `json:"data,omitempty"`

	// Final is true on the terminating chunk.
	Final bool `json:"final,omitempty"`
}

type Summary struct {
	// Goals captures the planner's running goal-tracking.
	Goals []string `json:"goals,omitempty"`

	// Facts captures the running fact-list extracted from prior
	// observations.
	Facts []string `json:"facts,omitempty"`

	// Pending captures the open subgoals.
	Pending []string `json:"pending,omitempty"`

	// LastOutputDigest is a short hash + summary of the most recent
	// observation, kept so the planner has context for the next step.
	LastOutputDigest string `json:"last_output_digest,omitempty"`

	// Note is the summariser's free-text note (rationale for the
	// compaction, surfaced in observability).
	Note string `json:"note,omitempty"`
}

type ToolContext struct {
	// Serializable carries the JSON-encodable values shared across
	// tool invocations within a run. Non-JSON-encodable values here
	// cause Trajectory.Serialize to return ErrUnserializable.
	Serializable map[string]any `json:"serializable,omitempty"`

	// Handles carries the keys for non-serialisable values the
	// HandleRegistry holds. The actual values are NEVER stored in
	// this struct — they live in the runtime's HandleRegistry and
	// are re-attached by key on resume.
	Handles []HandleID `json:"handles,omitempty"`
}

type Trajectory struct {
	// Query is the user-facing query that started the run.
	Query string `json:"query,omitempty"`

	// LLMContext is the visible-to-LLM context snapshot at run start
	// (memories, system notes, prior turn summaries). Values must be
	// JSON-encodable for Serialize to succeed; a non-encodable leaf
	// surfaces ErrUnserializable.
	LLMContext map[string]any `json:"llm_context,omitempty"`

	// ToolContext is the tool-only handle bundle. The Serializable
	// half is JSON-encoded as part of the trajectory; the Handles
	// slice carries opaque IDs whose actual values live in the
	// HandleRegistry.
	ToolContext ToolContext `json:"tool_context"`

	// Steps is the append-only list of trajectory steps.
	Steps []Step `json:"steps,omitempty"`

	// Summary is the compaction artefact produced by the trajectory
	// summariser (Phase 46). Non-nil when the runtime compressed the
	// trajectory; the planner sees only the compacted view.
	Summary *Summary `json:"summary,omitempty"`

	// Sources captures the citations / provenance for the planner's
	// terminal observation.
	Sources []Source `json:"sources,omitempty"`

	// Artifacts is the run's named artifact references. Values are
	// JSON-encoded ArtifactRefs (content-addressed; the bytes live
	// elsewhere via the ArtifactStore).
	Artifacts map[string]artifacts.ArtifactRef `json:"artifacts,omitempty"`

	// HintState carries planner-internal hint state across steps
	// (e.g. "I last summarised at step 4"). Opaque to the Runtime.
	// Values must be JSON-encodable.
	HintState map[string]any `json:"hint_state,omitempty"`

	// SteeringInputs is the history of steering injections observed
	// during the run.
	SteeringInputs []SteeringInjection `json:"steering_inputs,omitempty"`

	// Background captures the resolved outcomes of non-retain-turn
	// background tasks the planner spawned. Keyed by TaskGroupID
	// string for fast lookup.
	Background map[string]BackgroundResult `json:"background,omitempty"`

	// ResumeHint, when non-nil, signals the planner that this is a
	// resume continuation; the planner SHOULD use the hint to
	// reconstruct prior state.
	ResumeHint *ResumeHint `json:"resume_hint,omitempty"`
}