runctx

func ComposeCallerMemory ¶ added in v1.25.0

func ComposeCallerMemory(mb *planner.MemoryBlocks, raw json.RawMessage) (*planner.MemoryBlocks, error)

ComposeCallerMemory composes caller-supplied content into the run's `External` memory tier under CallerSuppliedKey.

It returns a NEW *planner.MemoryBlocks and never mutates its argument: the run loop's value is derived from identity-scoped store reads and must stay untouched.

The no-aliasing guarantee is scoped to the tier this function WRITES, and — stated precisely, because an earlier wording overclaimed it — scoped to that tier's MAP rather than to the values inside it. `External` is rebuilt as a fresh map, so adding, replacing or deleting a TOP-LEVEL key on either side cannot be observed through the other; in particular the caller's key is never written into the input. The entries are copied SHALLOWLY, so a value that is itself a map or slice is SHARED, and a mutation reaching INTO such a value — the runtime's own producer writes `{"recalled_turns": []map[string]any{…}}`, so this is the normal shape rather than a corner — IS visible on both sides.

That sharing is safe today for a structural reason, not a hopeful one: the input has exactly one holder. The blocks are built per run by the memory fetch and handed straight to this function, whose result replaces the local; the pre-composition value is then unreachable, so there is no second observer for a nested write to reach. Deep-copying an arbitrary `any` to close the gap would need a reflective or round-trip copy — the same cost, and the same objection, that keeps `Conversation` shared below. Both halves are pinned by a test, so a producer that starts retaining its blocks past composition turns that test's premise red rather than silently invalidating this paragraph.

`Conversation` is carried across BY REFERENCE — it is an `any` this function never reads into and never writes, so copying it would mean a reflective or round-trip deep copy of an arbitrary value, and a partial (top-level-only) copy would be worse than none: a half-true invariant is what a future author reasons from. The sharing is safe today because nothing downstream writes the tier — the planner's renderer only reads it — and it is pinned by a test asserting BOTH halves, the copy AND the share, so a change to either forces this sentence to be re-derived rather than silently invalidated.

Behaviour:

• An empty raw returns mb unchanged and byte-identically (the same pointer), so a run that supplied no caller memory is indistinguish- able from one made before the field existed.
• A nil mb with a non-empty raw allocates a MemoryBlocks carrying only the External tier — composition must also work for a session with no stored memory at all, and for a runtime with no memory subsystem configured.
• An explicit JSON `null`, or invalid JSON, returns ErrCallerMemoryInvalid. It is never treated as "absent".
• `Conversation` is copied across untouched. It is a claim about the session's stored turns that only the runtime may make, and it is written unconditionally by ProjectMemoryBlocks — a second writer would be silent last-writer-wins.

func DispositionHints ¶ added in v1.4.0

func DispositionHints(raw map[string]string) map[string]planner.AttachmentDisposition

DispositionHints converts the string-typed per-attachment hint map a task record carries (`tasks.Task.InputArtifactDispositions` — the Protocol carrier, validated at the edge via `planner.ParseDisposition`) into the typed hint map InputArtifactOptions.Hints expects. Nil in, nil out.

func ExtractAssistantAnswer ¶

func ExtractAssistantAnswer(fin planner.Finish) string

ExtractAssistantAnswer pulls the planner's natural-language answer out of a terminal Finish for the memory.AddTurn writeback and the `planner.AnswerEnvelope` projection (promoted by the runtime promotion). The react planner's FinishGoal carries Payload = map[string]any{"answer": "<the LLM's answer>"}. Other planners may shape Payload differently; we accept any string-valued "answer" key and otherwise fall back to a Sprintf so something always lands in memory (matching CLAUDE.md §5 fail-loud — silent "nothing written" would lose the run's outcome).

func FetchMemoryBlocks ¶ added in v1.4.0

func FetchMemoryBlocks(
	ctx context.Context,
	store memory.MemoryStore,
	id identity.Quadruple,
	query string,
	recall memory.RecallSettings,
	logger *slog.Logger,
) (*planner.MemoryBlocks, error)

FetchMemoryBlocks fetches the session's memory patch, optionally recalls semantically similar past turns for the given query, and projects both into the planner's MemoryBlocks. This is the single production home for the memory step of run-loop RunContext population.

When recall is disabled (RecallSettings.Enabled == false) the output is identical to calling GetLLMContext + ProjectMemoryBlocks directly — the External tier remains nil and SearchTurns is never called.

When recall is enabled:

• SearchTurns is called with the session-scoped identity triple (RunID zeroed) and the caller-supplied query.
• Turns scoring below RecallSettings.MinScore are dropped.
• Turns whose UserMessage is already present in the patch's RecentTurns window are deduped out.
• Each remaining turn's user and assistant text are capped at recalledTurnTextCap bytes (with a "…[truncated]" marker).
• The resulting slice is marshalled as map["recalled_turns"][]map[string]any and stored in MemoryBlocks.External alongside the Conversation tier.

An error from GetLLMContext or SearchTurns is returned unwrapped so the caller can fail the run loudly via MarkFailed(runtime_fetch_error). There is no silent fallback to rolling-summary-only on a recall error.

A Debug line is emitted on the supplied logger when recall fires (count + top score) so operators can see retrieval activity without seeing turn content. A nil logger falls back to slog.Default().

func FinishAnswerEnvelope ¶ added in v1.10.0

func FinishAnswerEnvelope(fin planner.Finish, traj *planner.Trajectory, schema *planner.OutputSchemaValidator) (planner.AnswerEnvelope, error)

FinishAnswerEnvelope builds the canonical planner.AnswerEnvelope from a terminal Finish, applying output-schema validation at the ONE shared site. The three call sites (assemble.RunOnce, the cmd/harbor per-task driver, the devstack twin) consume it so the answer envelope — and, on a schema-constrained goal Finish, the validated AnswerPayload — is byte-identical wherever a run is hosted.

Behaviour:

• schema == nil, OR fin.Reason != FinishGoal → the plain three-key envelope ({answer, finish_reason, tool_calls_seen}), byte-identical to a no-schema run. A non-goal terminal (a steering CANCEL surfaced as Finish{Cancelled}, a NoPath / deadline / constraints terminal) was never asked to produce a schema-shaped answer, so it is NEVER validated and NEVER returns ErrOutputInvalid.
• schema != nil AND fin.Reason == FinishGoal → the terminal payload is captured to its exact bytes at the validation site (never a lossy string round-trip) and validated against the compiled schema. On success AnswerPayload carries the exact validated bytes and Answer carries their string rendering. On a capture or validation failure the returned error wraps planner.ErrOutputInvalid — a loud, typed failure, never a silent fallback to unvalidated text (CLAUDE.md §13). A caller mapping this to a task terminal stamps planner.TaskErrorCodeOutputInvalid.

The trajectory is read only for planner.CountToolInvocations; a nil trajectory yields ToolCallsSeen == 0.

func NewRunContext ¶ added in v1.8.0

func NewRunContext(
	ctx context.Context,
	src Sources,
	q identity.Quadruple,
	goal string,
	opts ...Option,
) (planner.RunContext, error)

NewRunContext projects the stack-derived sources into a fully-formed planner.RunContext for the run identified by q and driven toward goal. It is the single production home for run-loop RunContext population that a one-call runner or a headless RunSpec builder composes; the per-task drivers keep their own population bodies (they thread control-plane projections this factory deliberately omits) but call the SAME underlying helpers, so the projected memory / skills / input-artifact / streaming surface is identical. The read-only cross-turn session-artifact manifest the dev drivers attach is one of those control-plane projections this factory omits; a headless run that needs input artifacts resolves them explicitly via WithInputArtifacts.

Identity is mandatory and fails loud: an incomplete quadruple returns a wrapped identity error rather than a half-scoped RunContext. Memory and skills are SESSION-scoped (the fetch quadruple zeroes RunID) so a run inherits the session's accumulated state; a fetch error is returned unwrapped enough for the caller to fail the run loudly (no silent degradation, CLAUDE.md §5/§13).

func ProjectMemoryBlocks ¶

func ProjectMemoryBlocks(patch memory.LLMContextPatch) *planner.MemoryBlocks

ProjectMemoryBlocks shapes a memory.LLMContextPatch into the JSON-encodable map the planner's `<read_only_conversation_memory>` wrapper renders. Returns nil when the patch is empty — the wrapper is omitted entirely. Only the Conversation tier is populated here; callers that enable semantic recall (via FetchMemoryBlocks) will additionally populate the External tier with retrieved turns.

func ProjectSkillsContext ¶

func ProjectSkillsContext(ranked []skills.RankedSkill) []any

ProjectSkillsContext shapes a []skills.RankedSkill into the []any the planner's `<skills_context>` wrapper renders ( the reasoning-replay knob). Each element is a small map carrying the body fields the LLM consumes (name / title / description / steps). An empty input returns nil so the wrapper is omitted.

func ProjectSkillsDirectory ¶

func ProjectSkillsDirectory(views []skills.SkillView) []any

ProjectSkillsDirectory shapes a `skills.Directory.View` snapshot into the []any the planner's `<skills_context>` wrapper renders (, executing the deprecation notice: the keyword-shaped raw-Search injection path and its `ExtractSkillKeywords` helper are deleted; the Directory's bounded, pinned-then-recent, capability-filtered, redacted browse window is the canonical producer). Each element is the compact `skills.SkillView` projection (name / title / trigger / task_type / pinned) — full skill content stays behind the `skill_get` meta-tool. An empty input returns nil so the wrapper is omitted.

func ResolveInputArtifacts ¶

func ResolveInputArtifacts(
	ctx context.Context,
	store artifacts.ArtifactStore,
	q identity.Quadruple,
	ids []string,
	logger *slog.Logger,
	opts InputArtifactOptions,
) []planner.InputArtifactView

ResolveInputArtifacts pre-fetches the metadata (+ bytes for inline dispositions) for every operator-uploaded artifact ID on a task, producing the `planner.InputArtifactView` slice the run loop hands to the planner's first turn (promoted by the runtime promotion). The synchronous pre-resolution keeps the planner's prompt assembly I/O-free.

each view's `Disposition` is resolved here via the pure `planner.ResolveDisposition` (per-attachment caller hint > per-agent policy map > runtime default) + capability normalisation via `planner.EffectiveDisposition`. This helper is a THIN caller — the precedence logic lives in `internal/planner`; the helper adds only the I/O (byte fetch for inline) and the logging/emission of the returned winning-layer + degradation facts (the resolver is pure and never logs).

Failures are bounded:

• Nil artifact store with non-empty IDs → empty slice + Warn log (the LLM still sees a text-only prompt; the operator can re- attach after wiring the store). Avoids a hard fail-loud here because the artifact-store dependency is genuinely optional in some dev postures.
• `GetRef` not-found / errored → skip that ID + Warn (the rest of the slice survives; the artifact may have been GC'd between spawn and run).
• `Get` (bytes fetch) errored on an inline disposition → keep the entry but leave Bytes nil. The materializer falls back to a stub-text part for missing-bytes inlines.

The scope on every store call is the run's identity tuple — the artifact store enforces tenant isolation on read. A nil logger defaults to slog.Default() so the Warn paths above stay loud for every caller.