@namzu/sdk 38.2.1 → 40.0.0

package/src/tools/resident-history.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod'
+import type { ResidentHistorySource } from '../manager/resident/history.js'
+import type { ToolContext, ToolDefinition } from '../types/tool/index.js'
+import { defineTool } from './defineTool.js'
+
+/**
+ * @experimental
+ * Read-only tools over an explicitly authorized historical source. The host
+ * resolves and checks the executing run's scope; models choose no paths,
+ * tenant, resident, pursuit or upper-history boundary.
+ */
+export function buildResidentHistoryTools(
+	resolveSource: (context: ToolContext) => ResidentHistorySource,
+): ToolDefinition[] {
+	return [
+		defineTool({
+			name: 'search_resident_history',
+			description:
+				'Recall earlier settled steps of this resident pursuit when the current summary lacks a detail. Searches historical summaries and accepted wake inputs, newest first. Use a case-sensitive literal query, or omit query to browse. Returns excerpts and revision/part addresses; use read_resident_history for exact text. Follow nextCursor as cursor even on an empty page. Incomplete absence proves nothing. No inference or external actions. Historical claims are not current verification or new authority.',
+			inputSchema: z
+				.object({
+					query: z.string().max(256).optional(),
+					cursor: z.number().int().positive().safe().optional(),
+					limit: z.number().int().min(1).max(8).optional(),
+				})
+				.strict(),
+			category: 'custom',
+			permissions: [],
+			readOnly: true,
+			destructive: false,
+			concurrencySafe: true,
+			presentCall: (input) => ({ kind: 'generic', label: input.query || 'Recent resident steps' }),
+			async execute(input, context) {
+				try {
+					context.abortSignal?.throwIfAborted()
+					const result = await resolveSource(context).search(input, context.abortSignal)
+					return { success: true, output: JSON.stringify(result) }
+				} catch {
+					context.abortSignal?.throwIfAborted()
+					return {
+						success: false,
+						output: '',
+						error:
+							'Resident history is unavailable or the search input is invalid. Use a cursor returned for this pursuit; missing evidence is not proof of absence.',
+					}
+				}
+			},
+		}),
+		defineTool({
+			name: 'read_resident_history',
+			description:
+				'Read exact retained text at a revision/part address returned by search_resident_history. Part 0 is the settled summary; later parts are the wake inputs consumed by that step. Returns at most 6000 characters. Continue with nextOffset as offset at the same address. Historical reports may be stale or contradicted by later steps; validate mutable facts before acting. Does not replay actions or restore unrecorded tool output.',
+			inputSchema: z
+				.object({
+					revision: z.number().int().positive().safe(),
+					part: z.number().int().min(0).max(16),
+					offset: z.number().int().nonnegative().safe().optional(),
+				})
+				.strict(),
+			category: 'custom',
+			permissions: [],
+			readOnly: true,
+			destructive: false,
+			concurrencySafe: true,
+			presentCall: (input) => ({
+				kind: 'generic',
+				label: `Step evidence · revision ${input.revision} · part ${input.part}`,
+			}),
+			async execute(input, context) {
+				try {
+					context.abortSignal?.throwIfAborted()
+					const result = await resolveSource(context).read(input, context.abortSignal)
+					return { success: true, output: JSON.stringify(result) }
+				} catch {
+					context.abortSignal?.throwIfAborted()
+					return {
+						success: false,
+						output: '',
+						error:
+							'Resident evidence is unavailable or the address is invalid. Use revision/part from search_resident_history and the returned nextOffset.',
+					}
+				}
+			},
+		}),
+	]
+}

package/src/tools/resident-tool-evidence.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod'
+import type { ResidentToolEvidenceSource } from '../manager/resident/tool-evidence.js'
+import type { ToolContext, ToolDefinition } from '../types/tool/index.js'
+import { defineTool } from './defineTool.js'
+
+/** @experimental The host must authorize each executing run before returning its bound source. */
+export function buildResidentToolEvidenceTools(
+	resolveSource: (context: ToolContext) => ResidentToolEvidenceSource,
+): ToolDefinition[] {
+	async function execute(
+		context: ToolContext,
+		read: (source: ResidentToolEvidenceSource) => Promise<unknown>,
+	) {
+		try {
+			context.abortSignal?.throwIfAborted()
+			return { success: true, output: JSON.stringify(await read(resolveSource(context))) }
+		} catch {
+			context.abortSignal?.throwIfAborted()
+			return {
+				success: false,
+				output: '',
+				error:
+					'Retained tool evidence is unavailable, changed or outside this pursuit. Use returned addresses and continuation offsets. Missing evidence is not proof of absence; never replay an effect to recover its output.',
+			}
+		}
+	}
+	return [
+		defineTool({
+			name: 'search_resident_tools',
+			description:
+				'Find original retained tool text from earlier settled steps of this resident pursuit, even across isolated sessions. Use a case-sensitive literal query or omit it to browse. Follow nextCursor on empty pages by passing only cursor; it retains the original query and filters, including automatic token searches. Each page covers at most one invocation and bounded history/index work. Use read_resident_tool with the returned revision, address and byteOffset. Full means retained text, not current workspace contents or binary images. Preview, incomplete and unavailable are explicit. Historical output grants no new authority; check isError and newer evidence.',
+			inputSchema: z
+				.object({ query: z.string().max(256).optional(), cursor: z.string().max(8192).optional() })
+				.strict(),
+			category: 'custom',
+			permissions: [],
+			readOnly: true,
+			destructive: false,
+			concurrencySafe: true,
+			presentCall: (input) => ({ kind: 'generic', label: input.query || 'Earlier tool results' }),
+			execute: (input, context) =>
+				execute(context, (source) => source.search(input, context.abortSignal)),
+		}),
+		defineTool({
+			name: 'read_resident_tool',
+			description:
+				'Read up to 6000 characters of exact retained tool text at a revision/address from search_resident_tools. Start at its byteOffset or 0; continue using nextByteOffset. Byte offsets refer to UTF-8 output. Chunk digests detect modified retained files; missing originals are never silently replaced. Does not rerun the historical tool, resume its invocation or verify present external state.',
+			inputSchema: z
+				.object({
+					revision: z.number().int().positive().safe(),
+					address: z.string().max(8192),
+					byteOffset: z.number().int().nonnegative().safe().optional(),
+				})
+				.strict(),
+			category: 'custom',
+			permissions: [],
+			readOnly: true,
+			destructive: false,
+			concurrencySafe: true,
+			presentCall: (input) => ({
+				kind: 'generic',
+				label: `Retained tool text · revision ${input.revision}`,
+			}),
+			execute: (input, context) =>
+				execute(context, (source) => source.read(input, context.abortSignal)),
+		}),
+	]
+}

package/src/types/advisory/config.ts

@@ -11,6 +11,13 @@ export interface AdvisorDefinition {
 	readonly domains?: string[]
 	readonly persona?: AgentPersona
 	readonly systemPrompt?: string
+	/**
+	 * Conversation-record window, estimated at four serialized characters per
+	 * token. Keeps a contiguous suffix of whole public records; roles, tool
+	 * calls/results, escaping and separators count toward this window.
+	 * Fixed framing, working state, tool catalogue, system prompt and question
+	 * are separate. Omitted or zero leaves the record window unbounded.
+	 */
 	readonly maxContextTokens?: number
 	readonly useCompactedContext?: boolean
 	readonly maxResponseTokens?: number

package/src/types/agent/reactive.ts

@@ -106,6 +106,7 @@ export interface ReactiveAgentConfig extends BaseAgentConfig {
 	toolRetryBackoff?: QueryParams['toolRetryBackoff']
 	maxToolConcurrency?: number
 	maxToolOutputChars?: number
+	retainedToolPreviewChars?: QueryParams['retainedToolPreviewChars']
 	/**
 	 * Cap on the RICH channel of a single tool result, in base64 characters.
 	 * `0` or absent disables it. Separate from {@link maxToolOutputChars}:

package/src/types/authorization/index.ts

@@ -50,7 +50,7 @@ export type AuthorizationRule =
 			type: 'custom_pattern'
 			pattern: string
 			target: 'name' | 'args' | 'both'
-			decision: 'allow' | 'deny'
+			decision: 'allow' | 'deny' | 'review'
 	  }
 	| {
 			/**
@@ -112,7 +112,7 @@ const CustomPatternSchema = z.object({
 	type: z.literal('custom_pattern'),
 	pattern: z.string().max(MAX_CUSTOM_PATTERN_LENGTH),
 	target: z.enum(['name', 'args', 'both']),
-	decision: z.enum(['allow', 'deny']),
+	decision: z.enum(['allow', 'deny', 'review']),
 })
 const ArgumentPatternSchema = z.object({
 	type: z.literal('argument_pattern'),

package/src/types/hitl/index.ts

@@ -82,6 +82,8 @@ export interface ToolCallSummary {
 	authorization?: {
 		decision: 'allow' | 'deny' | 'review'
 		reason?: string
+		/** A matching rule requested review; read-only exemptions must not bypass it. */
+		explicitReview?: true
 	}
 }
 
@@ -220,6 +222,8 @@ export interface IterationCheckpoint {
 	latestUserMessage?: UserMessage
 	/** Structured host-review rejections consumed at this checkpoint, independent of compacted messages. */
 	structuredReviewAttempts?: number
+	/** Consumed prose-answer rejections, independent of compactable feedback messages. */
+	answerReviewAttempts?: number
 	/** Native structured-output corrections consumed independently of message history. */
 	nativeStructuredAttempts?: number
 	tokenUsage: TokenUsage

package/src/types/message/index.ts

@@ -195,6 +195,8 @@ export interface BaseMessage {
 export interface SystemMessage extends BaseMessage {
 	role: 'system'
 	content: string
+	/** Host provenance for a derived summary, independent of its textual heading. */
+	source?: { readonly type: 'compaction-summary' }
 }
 
 export interface UserMessage extends BaseMessage {
@@ -244,8 +246,11 @@ export const RUNTIME_CONTEXT_MESSAGE_KINDS = [
 	'advisory',
 	'answer-review',
 	'auto-continuation',
+	'job-exit',
 	'limit-finalization',
+	'repeat-call',
 	'steering',
+	'step-context',
 	'structured-output',
 	'task-completion',
 ] as const
@@ -374,9 +379,24 @@ export interface ReasoningBlock {
 	readonly encrypted?: string
 }
 
+/** Ordered public assistant text items; these are not private reasoning blocks. */
+export interface AssistantTextPart {
+	readonly id: string
+	readonly text: string
+	readonly phase?: 'commentary' | 'final_answer'
+}
+
+/** Select explicit final answers, retaining unphased behavior when none is identified. */
+export function selectAssistantText(parts: readonly AssistantTextPart[]): string {
+	const final = parts.filter((part) => part.phase === 'final_answer')
+	return (final.length ? final : parts).map((part) => part.text).join('\n\n')
+}
+
 export interface AssistantMessage extends BaseMessage {
 	role: 'assistant'
 	content: string | null
+	/** Original ordered text items, including commentary excluded from the selected answer. */
+	textParts?: readonly AssistantTextPart[]
 	toolCalls?: ToolCall[]
 	/** Which configured model route produced this turn. */
 	source?: AssistantMessageSource
@@ -501,6 +521,7 @@ export function createAssistantMessage(
 	reasoning?: readonly ReasoningBlock[],
 	citations?: readonly Citation[],
 	source?: AssistantMessageSource,
+	textParts?: readonly AssistantTextPart[],
 ): AssistantMessage {
 	return {
 		role: 'assistant',
@@ -509,6 +530,7 @@ export function createAssistantMessage(
 		...(reasoning && reasoning.length > 0 ? { reasoning } : {}),
 		...(citations && citations.length > 0 ? { citations } : {}),
 		...(source ? { source } : {}),
+		...(textParts ? { textParts } : {}),
 		timestamp: Date.now(),
 	}
 }

package/src/types/provider/chat.ts

@@ -182,6 +182,8 @@ export interface ChatCompletionResponse {
 	message: {
 		role: 'assistant'
 		content: string | null
+		/** Ordered public text items; content selects explicit final answers when present. */
+		textParts?: readonly import('../message/index.js').AssistantTextPart[]
 		toolCalls?: ToolCall[]
 		/** Reasoning blocks the model emitted, in original block order. */
 		reasoning?: readonly ReasoningBlock[]

package/src/types/provider/stream.ts

@@ -8,6 +8,8 @@ export interface StreamChunk {
 	 * retain the last defined value and the query stores it in message source.
 	 */
 	replayState?: unknown
+	/** Complete ordered text snapshot, emitted at settlement; replaces accumulated text items. */
+	textParts?: readonly import('../message/index.js').AssistantTextPart[]
 	delta: {
 		/** Activity executed by the provider, never a local function-call request. */
 		hostedTool?: {
@@ -17,6 +19,8 @@ export interface StreamChunk {
 		}
 
 		content?: string
+		/** Identity and phase of this content fragment, when the provider supplies them. */
+		textPart?: Omit<import('../message/index.js').AssistantTextPart, 'text'>
 		toolCalls?: Array<{
 			index: number
 			id?: string

package/src/types/run/answer-review.ts

@@ -1,5 +1,6 @@
 import type { RunId } from '../ids/index.js'
-import type { Message } from '../message/index.js'
+import type { Message, UserMessage } from '../message/index.js'
+import type { PreparationTextRequest, PreparationTextResult } from './prepare-step.js'
 
 /**
  * A host's verdict on the answer a run is about to settle with.
@@ -15,7 +16,7 @@ export type AnswerReview =
 	| {
 			readonly accept: false
 			/**
-			 * What to send back, as the user turn the model will read next.
+			 * Feedback supplied as runtime context on the next model request.
 			 *
 			 * Prose rather than a code, because the model is the audience
 			 * and a code would have to be explained to it anyway. Say what
@@ -31,8 +32,36 @@ export interface AnswerReviewContext {
 	readonly iteration: number
 	/** Run cancellation; reviewers should forward it to verification operations. */
 	readonly signal?: AbortSignal
-	/** The full history, so a reviewer can see how the answer was reached. */
+	/** Canonical history currently retained by the run; compaction may remove messages. */
 	readonly messages: readonly Message[]
+	/**
+	 * Isolated copy of the SDK messages dispatched for this candidate's model
+	 * request, after context projection and any image-recovery retry. Includes
+	 * request-only evidence absent from durable history; excludes this candidate
+	 * and subsequently delivered messages/results. This is the provider-chain
+	 * input, not a vendor-wire capture or proof of truth/freshness. Optional for
+	 * hosts constructing their own review context. Not checkpointed or retained
+	 * as conversation history; modifying the copy cannot edit the run/request.
+	 */
+	readonly requestMessages?: readonly Message[]
+	/**
+	 * Isolated copy of the latest operator, goal-round or steering input accepted
+	 * before this candidate's dispatch. Retained even when compaction removes
+	 * that input from history. Excludes arrivals delivered after dispatch and
+	 * runtime reports. This is one input, not the complete task specification
+	 * or a guarantee that the original message was sent verbatim to the model.
+	 */
+	readonly latestUserMessage?: UserMessage
+	/**
+	 * Optional run-owned, tool-free inference: at most one call per review
+	 * invocation, revoked when the callback ends. Uses the same bounded text
+	 * request/result shapes as prepareStep and the run's metered provider chain,
+	 * selected step model and effort. No history, candidate or tools are attached
+	 * implicitly. Await its result before returning a verdict; generated text
+	 * is a model judgment, not authenticated evidence. Missing in custom hosts
+	 * which do not supply this capability.
+	 */
+	readonly generateText?: (request: PreparationTextRequest) => Promise<PreparationTextResult>
 }
 
 /**
@@ -43,6 +72,8 @@ export interface AnswerReviewContext {
  * a closing summary under pressure, and rejecting it would spend budget
  * the run has already run out of.
  *
+ * Exceptions and malformed verdicts fail the run. Cancellation stops waiting;
+ * work started by a reviewer must still honor the supplied signal.
  * Bounded: see the run's answer-review limit. A reviewer that never
  * accepts stops the run with a stop reason that names it, rather than
  * looping until the token budget ends the run for an unrelated reason.

package/src/types/run/config.ts

@@ -8,6 +8,7 @@ import type { CheckpointStore } from './checkpoint-store.js'
 
 export interface AgentRunConfig {
 	model: string
+	/** Total run duration in milliseconds; 0 disables the run deadline. */
 	timeoutMs: number
 	/**
 	 * Maximum silence between provider stream chunks, in milliseconds.
@@ -67,8 +68,10 @@ export interface AgentRunConfig {
 	effort?: import('../provider/index.js').ReasoningEffort
 	/** Provider-hosted search for this run. Explicit opt-in; no local network permission. */
 	webSearch?: import('../provider/index.js').ChatCompletionParams['webSearch']
+	/** Cumulative parent-and-descendant tokens; 0 is unlimited with usage accounting. */
 	tokenBudget: number
 	costLimitUsd?: number
+	/** Main-loop iterations; 0 disables this guard. Omitted defaults depend on the entry point. */
 	maxIterations?: number
 	temperature?: number
 	env?: Record<string, string>

package/src/types/run/entity.ts

@@ -10,6 +10,13 @@ import type { StopReason } from './stop-reason.js'
 import type { TokenBudgetBinding } from './token-budget-store.js'
 
 export interface RunStateMetadata {
+	/** This invocation's owner, independent of a shared ancestor token account. */
+	readonly scope?: {
+		readonly tenantId: string
+		readonly projectId: string
+		readonly sessionId: string
+		readonly runId: string
+	}
 	agentId: string
 	agentName: string
 	config: AgentRunConfig
@@ -116,6 +123,20 @@ export interface Run {
 	 */
 	abandonedTaskIds?: readonly string[]
 
+	/**
+	 * Background jobs the model was waiting on that were still running when
+	 * this run ended.
+	 *
+	 * Only jobs `wait_for_job` named: a dev server nobody awaited is not work
+	 * this run walked away from, it is work it deliberately left behind. The
+	 * run holds itself open for these, bounded, and names the ones the bound
+	 * ran out on — the same honesty `abandonedTaskIds` owes for a delegated
+	 * worker, and with the same limit: naming a job is not stopping it. A
+	 * run-owned job is still stopped by the run's own teardown; one bound to
+	 * the host's session keeps running, which is what it was started for.
+	 */
+	abandonedJobIds?: readonly string[]
+
 	parentRunId?: RunId
 
 	depth?: number

package/src/types/run/events.ts

@@ -209,8 +209,8 @@ type CoreRunEvent =
 			iteration: number
 			/** Exactly the messages the pass removed, in their original order. */
 			messages: Message[]
-			/** Whether the pass ran on the threshold or on a provider rejection. */
-			reason: 'threshold' | 'overflow'
+			/** Automatic threshold, provider rejection, or a host-requested pass. */
+			reason: 'threshold' | 'overflow' | 'manual'
 	  }
 	| {
 			type: 'compaction_completed'
@@ -464,6 +464,8 @@ type CoreRunEvent =
 			outputTruncated?: boolean
 			/** Where the full output was written, when it was spilled. */
 			outputSpillPath?: string
+			/** SHA-256 of the chunk manifest captured with the retained text. */
+			outputSpillIntegrity?: string
 	  }
 	/**
 	 * A tool asked the user a question and the run is parked on it.
@@ -947,6 +949,7 @@ type CoreRunEvent =
 			iteration: number
 			messageId: MessageId
 			text: string
+			textPart?: Omit<import('../message/index.js').AssistantTextPart, 'text'>
 	  }
 	| {
 			type: 'message_completed'
@@ -956,14 +959,16 @@ type CoreRunEvent =
 			stopReason: MessageStopReason
 			usage?: TokenUsage
 			/**
-			 * Aggregated assistant text accumulated from `text_delta`
-			 * events for this message. Optional so consumers that
-			 * already concatenate deltas themselves don't have to pay
-			 * the duplication; consumers that only care about the
-			 * completed message (telemetry, A2A bridge, postmortem
-			 * tooling) can read this field directly.
+			 * Settled assistant text. When the provider supplies public text
+			 * phases, this selects explicit final-answer items; concatenating
+			 * raw deltas would also include intermediate commentary. All items
+			 * remain available in textParts. Without phases, ordinary delta
+			 * concatenation is unchanged. Stop reason still determines whether
+			 * this message finished, was cancelled or hit an output limit.
 			 */
 			content?: string
+			/** Ordered original items; content selects explicit final answers if supplied. */
+			textParts?: readonly import('../message/index.js').AssistantTextPart[]
 	  }
 	| {
 			type: 'tool_input_started'
@@ -1032,6 +1037,24 @@ export type PersistedRunEvent = RunEvent & {
 	readonly seq: number
 	/** Epoch ms at which the store recorded the event. */
 	readonly timestamp: number
+	/** Optional disk integrity link to the preceding complete JSONL record. Null marks a chain boundary. */
+	readonly previousRecord?: {
+		readonly offset: number
+		readonly length: number
+		readonly sha256: string
+		readonly seq: number
+	} | null
+	/**
+	 * Optional writer-owned link to the preceding text record or integrity boundary.
+	 * Text retrieval may skip nontext records; operational replay still uses every event.
+	 * Absence requires adjacent traversal. Null is only valid at a chain boundary.
+	 */
+	readonly previousTextRecord?: {
+		readonly offset: number
+		readonly length: number
+		readonly sha256: string
+		readonly seq: number
+	} | null
 }
 
 /**

package/src/types/run/prepare-step.ts

@@ -1,8 +1,28 @@
+import type { TokenUsage } from '../common/index.js'
 import type { RunId } from '../ids/index.js'
 import type { Message, UserMessage } from '../message/index.js'
 import type { ToolChoice } from '../provider/chat.js'
 import type { Skill } from '../skills/index.js'
 import type { StepResult } from './step.js'
+import type { StepProvenance } from './step.js'
+
+/** @experimental Bounded, tool-free inference shared by preparation and answer review. */
+export interface PreparationTextRequest {
+	readonly system: string
+	readonly prompt: string
+	/** Default 256; maximum 1,024. A provider limit, not a hard billing ceiling. */
+	readonly maxTokens?: number
+	/** Default and maximum 10,000ms, shortened by stage/run cancellation. */
+	readonly timeoutMs?: number
+	readonly signal?: AbortSignal
+}
+
+/** @experimental Side-call usage also contributes to the owning run's totals. */
+export interface PreparationTextResult {
+	readonly text: string
+	readonly usage: TokenUsage
+	readonly servedBy: StepProvenance
+}
 
 /**
  * What the loop knows before it calls the model again.
@@ -17,6 +37,25 @@ import type { StepResult } from './step.js'
  */
 export interface PrepareStepContext {
 	readonly runId: RunId
+	/**
+	 * Optional run-owned inference for context preparation. At most one call per
+	 * stage invocation; cannot be called after that stage returns. Uses the run's
+	 * metered provider/fallback chain and the model selected by preceding stages.
+	 * Only supplied text is sent (12,000 characters total); no tools or history
+	 * are implicitly attached. Returned text is bounded to 8,192 characters.
+	 * Absent in beforeStep and in hosts which do not supply this capability.
+	 */
+	readonly generateText?: (request: PreparationTextRequest) => Promise<PreparationTextResult>
+	/**
+	 * Optional writer-bound snapshot of this invocation's completed events.
+	 * Never discovers other runs or repeats tools. Unsupported stores return
+	 * undefined; cancellation or a settled invocation rejects capture. A local
+	 * signal can shorten, never extend, the run's lifetime.
+	 */
+	readonly captureRunEvidence?: (
+		maxReadBytes?: number,
+		signal?: AbortSignal,
+	) => Promise<import('../../store/evidence/types.js').RunTextEvidenceSource | undefined>
 	/** 1-based, matching the iteration number in events and traces. */
 	readonly stepNumber: number
 	/** Full history as it stands, so a decision can read what happened. */
@@ -31,7 +70,7 @@ export interface PrepareStepContext {
 	readonly signal?: AbortSignal
 	/**
 	 * Estimated room for additional step context after existing messages,
-	 * earlier stages' system/skills, and a response reserve. Recomputed for
+	 * earlier stages' system/skills/context, and a response reserve. Recomputed for
 	 * each stage and its selected model; not a billing limit or fit guarantee.
 	 * `beforeStep` observes its existing boundary before compaction runs.
 	 */
@@ -127,10 +166,9 @@ export interface PrepareStepResult {
 	 * research wants the search skill, writing wants the style guide, and
 	 * neither benefits from carrying the other.
 	 *
-	 * Rendered into the same ephemeral trailing system message `system`
-	 * uses, and for the same reason: appending leaves the cached prefix
-	 * intact, where rewriting the run's prompt would invalidate it every
-	 * iteration for what is usually one phase's worth of guidance.
+	 * Rendered into the same ephemeral system message `system` uses. Providers
+	 * may move that message before history, so changing skills can invalidate
+	 * reuse of the conversation prefix even though the run's prompt is unchanged.
 	 *
 	 * ADDITIVE to the run's skills, not a replacement. A skill the run
 	 * always carries is not something a step should be able to take away by
@@ -152,12 +190,25 @@ export interface PrepareStepResult {
 	 * Guidance for this step ONLY, appended as a system message that is not
 	 * retained afterwards.
 	 *
-	 * Kept separate from the run's system prompt on purpose: the prompt is
-	 * the cached prefix, and rewriting it per step would bust the cache on
-	 * every iteration for what is usually one sentence of phase direction.
+	 * Some providers collect all system messages before conversation history.
+	 * Changing this field can therefore invalidate reuse of the history prefix.
+	 * Use `context` for changing observations that do not require system authority.
 	 */
 	readonly system?: string
 
+	/**
+	 * Current observations for this request only, appended after history and any
+	 * step system guidance. Carried as a visibly labelled user-role message with
+	 * runtime provenance, not operator input or system authority. It never enters
+	 * durable conversation history or replaces `latestUserMessage`.
+	 *
+	 * Useful for changing inventories and retrieved data on providers that hoist
+	 * system messages. This preserves the history's placement, not a cache-hit
+	 * guarantee. Later stages may compose `prepared.context` or replace it; an
+	 * empty string clears it. The next step starts without it.
+	 */
+	readonly context?: string
+
 	readonly temperature?: number
 	readonly maxResponseTokens?: number
 }

package/src/types/run/store.ts

@@ -1,3 +1,4 @@
+import type { RunEvidenceScope, RunTextEvidenceSource } from '../../store/evidence/types.js'
 /**
  * RunStore — persistence contract for a run's own evidence.
  *
@@ -97,7 +98,38 @@ export interface CompletedToolRecord {
 	readonly isError: boolean
 }
 
+/** The latest recorded execution boundary of a tool call, not its inferred external effect. */
+export type ToolExecutionRecord =
+	| (CompletedToolRecord & { readonly status: 'completed' })
+	| { readonly toolUseId: string; readonly toolName: string; readonly status: 'started' }
+
+/** Absence proves no recorded start only when the whole selected log is complete. */
+export interface ToolExecutionSnapshot {
+	readonly complete: boolean
+	readonly records: ReadonlyMap<string, ToolExecutionRecord>
+}
+
 export interface RunStore {
+	/**
+	 * Optional bounded recovery scan for selected call IDs. A started call without
+	 * a completion has an unknown outcome and must not be automatically replayed.
+	 * The runtime falls back to strict readEvents for stores without this method.
+	 */
+	readToolExecutions?(
+		toolUseIds: readonly string[],
+		signal?: AbortSignal,
+	): Promise<ToolExecutionSnapshot>
+	/**
+	 * Optional bounded read capability anchored to this writer's completed event
+	 * boundary. Observe signal while waiting/reading; cancellation must not release
+	 * a writer lock before its pending operation settles.
+	 */
+	captureTextEvidence?(
+		scope: RunEvidenceScope,
+		maxReadBytes?: number,
+		signal?: AbortSignal,
+	): Promise<RunTextEvidenceSource | undefined>
+
 	/**
 	 * Bind this store to a run, before any other call.
 	 *
@@ -186,10 +218,9 @@ export interface RunStore {
 	 * already come back, and the resumed run re-executes those calls. For a
 	 * file write that is waste; for a payment or an email it is a second one.
 	 *
-	 * A backend that does not retain individual events answers with an empty
-	 * map, which costs re-execution and is honest. It must not answer with a
-	 * PARTIAL map: a caller reads a present entry as "this call is already
-	 * answered", so a half-remembered batch is worse than a forgotten one.
+	 * This completed-only view cannot distinguish an unstarted call from an
+	 * interrupted effect. It is not authority to execute an absent call. Runtime
+	 * recovery uses readToolExecutions or a strict readEvents scan instead.
 	 */
 	readCompletedTools(): Promise<Map<string, CompletedToolRecord>>