@namzu/sdk 38.1.0 → 39.0.0

package/src/tools/builtins/job.ts

@@ -47,11 +47,10 @@ export const JobTool = defineTool({
 	inputSchema,
 	category: 'shell',
 	permissions: ['shell_execute'],
-	// `read` and `list` observe; `kill` stops work. The tool as a whole is not
-	// read-only, and claiming otherwise would let a read-only permission
-	// preset hand the model a way to terminate a running process.
-	readOnly: false,
-	destructive: (input: JobInput) => input.action === 'kill',
+	// The static permission describes the full capability. The prepared action
+	// determines whether this call only observes its owner-bound registry.
+	readOnly: (input: JobInput) => input?.action === 'read' || input?.action === 'list',
+	destructive: (input: JobInput) => input?.action === 'kill',
 	concurrencySafe: true,
 
 	presentCall(input) {

package/src/tools/builtins/write-file.ts

@@ -150,7 +150,7 @@ export const WriteFileTool = defineTool({
 				// This write is now the runtime's newest observation. Recording only
 				// the boolean would leave an older content fingerprint in place and
 				// make the next same-run write refuse its own predecessor as drift.
-				context.fileReadTracker?.recordRead(valid.path, content)
+				context.fileReadTracker?.recordRead(valid.path, content, context.toolUseId)
 				return fileWriteResult(
 					valid.path,
 					current === null ? null : current?.toString('utf-8'),
@@ -171,7 +171,7 @@ export const WriteFileTool = defineTool({
 			// leaves the destination truncated — and this tool overwrites a
 			// whole file, so the truncation is the user's previous work.
 			await atomicWriteFile(hostPath, content)
-			context.fileReadTracker?.recordRead(hostPath, content)
+			context.fileReadTracker?.recordRead(hostPath, content, context.toolUseId)
 
 			return fileWriteResult(hostPath, current, content)
 		})

package/src/tools/defineTool.ts

@@ -17,7 +17,8 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	validationErrorHint?: string
 	category: ToolDefinition['category']
 	permissions: ToolPermission[]
-	readOnly: boolean
+	/** Whether this exact call only observes state; conservative for unknown inputs. */
+	readOnly: boolean | ((input: z.infer<S>) => boolean)
 	destructive: boolean | ((input: z.infer<S>) => boolean)
 	concurrencySafe: boolean
 	/** Batch ordering boundary; see {@link ToolDefinition.executionBarrier}. */
@@ -88,7 +89,8 @@ export function defineTool<S extends z.ZodType>(
 			: {}),
 		category: options.category,
 		permissions: options.permissions,
-		isReadOnly: () => options.readOnly,
+		isReadOnly:
+			typeof options.readOnly === 'function' ? options.readOnly : () => options.readOnly as boolean,
 		isDestructive:
 			typeof options.destructive === 'function'
 				? options.destructive

package/src/tools/file-read-tracker.ts

@@ -5,12 +5,18 @@ import { fingerprintContent } from './builtins/content-fingerprint.js'
 export function createFileReadTracker(): FileReadTracker {
 	const paths = new Set<string>()
 	const fingerprints = new Map<string, string>()
+	const writes = new Map<string, string>()
 	return {
-		recordRead(key, content) {
+		recordRead(key, content, fullWriteCallId) {
 			paths.add(key)
-			if (content !== undefined) fingerprints.set(key, fingerprintContent(content))
+			const next = content === undefined ? undefined : fingerprintContent(content)
+			if (next === undefined || next !== fingerprints.get(key)) writes.delete(key)
+			if (next !== undefined) fingerprints.set(key, next)
+			else fingerprints.delete(key)
+			if (next !== undefined && fullWriteCallId) writes.set(key, fullWriteCallId)
 		},
 		hasRead: (key) => paths.has(key),
 		fingerprint: (key) => fingerprints.get(key),
+		writeCallId: (key) => writes.get(key),
 	}
 }

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 {
@@ -246,6 +248,7 @@ export const RUNTIME_CONTEXT_MESSAGE_KINDS = [
 	'auto-continuation',
 	'limit-finalization',
 	'steering',
+	'step-context',
 	'structured-output',
 	'task-completion',
 ] as const
@@ -374,9 +377,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 +519,7 @@ export function createAssistantMessage(
 	reasoning?: readonly ReasoningBlock[],
 	citations?: readonly Citation[],
 	source?: AssistantMessageSource,
+	textParts?: readonly AssistantTextPart[],
 ): AssistantMessage {
 	return {
 		role: 'assistant',
@@ -509,6 +528,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

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
 }
 
 /**