runctx

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.