@namzu/sdk 30.2.0 → 31.1.0

package/src/runtime/query/project-instructions.ts

@@ -0,0 +1,212 @@
+import { isDeepStrictEqual } from 'node:util'
+
+import { NamzuError } from '../../types/errors/index.js'
+import type { RunId } from '../../types/ids/index.js'
+import {
+	type Message,
+	type UserMessage,
+	isProjectInstructionMessageSource,
+} from '../../types/message/index.js'
+import type { ToolResult } from '../../types/tool/index.js'
+
+/** One real registry execution, after retries and its terminal event. */
+export interface ToolResultObservation {
+	readonly runId: RunId
+	readonly toolUseId: string
+	readonly toolName: string
+	readonly input: unknown
+	readonly result: ToolResult
+	/** Present when another tool dispatched this call. */
+	readonly parentToolUseId?: string
+}
+
+/** Authority and durable conversation visible to one host policy callback. */
+export interface ProjectInstructionCallbackContext {
+	/** A snapshot of the messages accepted before this callback starts. */
+	readonly messages: readonly Message[]
+	/** The run-owned cancellation signal for any host I/O the callback starts. */
+	readonly signal: AbortSignal
+}
+
+export type ProjectInstructionSnapshotUpdate = UserMessage | null | undefined
+
+/**
+ * Host-owned live project policy for one run.
+ *
+ * Tool results are observed only after the registry has produced its final
+ * result and the complete tool-result batch is in `context.messages`. Each
+ * accepted observation returns its desired complete snapshot and the loop
+ * persists it before entering the next observation. `undefined` means no
+ * change; `null` explicitly removes the old snapshot.
+ *
+ * Callbacks must derive publication decisions from `context.messages`, not
+ * advance a private "published" cursor before returning: cancellation may win
+ * after host work finishes but before the returned value is accepted.
+ */
+export interface ProjectInstructionContext {
+	/**
+	 * Rebuild the first-request snapshot from host authority. Persisted source
+	 * paths may guide discovery; persisted policy text must not be trusted.
+	 * `undefined` leaves history unchanged, while `null` removes stale state.
+	 */
+	prepareInitialSnapshot?(
+		context: ProjectInstructionCallbackContext,
+	): ProjectInstructionSnapshotUpdate | Promise<ProjectInstructionSnapshotUpdate>
+	observeToolResult(
+		observation: ToolResultObservation,
+		context: ProjectInstructionCallbackContext,
+	): ProjectInstructionSnapshotUpdate | Promise<ProjectInstructionSnapshotUpdate>
+}
+
+/**
+ * Await opaque host work without giving it ownership of run cancellation.
+ *
+ * The callback receives the signal for cooperative cleanup. The independent
+ * settlement boundary is still required: a host implementation that ignores
+ * the signal may continue its own work, but it cannot keep Namzu pending or
+ * publish a value after authority was withdrawn.
+ */
+export async function awaitProjectInstructionCallback<T>(
+	signal: AbortSignal,
+	start: () => T | Promise<T>,
+): Promise<T> {
+	signal.throwIfAborted()
+
+	return new Promise<T>((resolve, reject) => {
+		let settled = false
+		const cleanup = (): void => signal.removeEventListener('abort', onAbort)
+		const rejectOnce = (reason: unknown): void => {
+			if (settled) return
+			settled = true
+			cleanup()
+			reject(reason)
+		}
+		const resolveOnce = (value: T): void => {
+			if (settled) return
+			settled = true
+			cleanup()
+			resolve(value)
+		}
+		// Abort delivery is synchronous. This first-cause latch decides whether
+		// host completion or authority withdrawal owns publication, even when
+		// both happen in the same event-loop turn.
+		const onAbort = (): void => rejectOnce(signal.reason)
+
+		signal.addEventListener('abort', onAbort, { once: true })
+		try {
+			Promise.resolve(start()).then(resolveOnce, rejectOnce)
+		} catch (error) {
+			rejectOnce(error)
+		}
+	})
+}
+
+export function isProjectInstructionMessage(message: Message): message is UserMessage {
+	return (
+		message.role === 'user' &&
+		message.source?.type === 'project-instructions' &&
+		isProjectInstructionMessageSource(message.source)
+	)
+}
+
+function assertsProjectInstructionMessage(message: UserMessage): asserts message is UserMessage & {
+	readonly source: {
+		readonly type: 'project-instructions'
+		readonly files: readonly string[]
+	}
+} {
+	if (!isProjectInstructionMessage(message)) {
+		throw new NamzuError({
+			code: 'invalid_config',
+			message:
+				'A project-instruction snapshot must be a user message with valid project-relative provenance.',
+		})
+	}
+}
+
+/**
+ * Keep only the latest structurally valid project snapshot, at its own
+ * chronological position. Invalid tagged provenance refuses before a provider
+ * can be called; an untrusted persisted object cannot acquire policy status by
+ * spelling one discriminator.
+ */
+export function collapseProjectInstructionSnapshots(messages: readonly Message[]): Message[] {
+	let latest = -1
+	for (let index = 0; index < messages.length; index += 1) {
+		const message = messages[index]
+		if (message?.role !== 'user' || message.source?.type !== 'project-instructions') continue
+		assertsProjectInstructionMessage(message)
+		latest = index
+	}
+	if (latest < 0) return [...messages]
+	return messages.flatMap((message, index) => {
+		if (message.role === 'user' && message.source?.type === 'project-instructions') {
+			return index === latest
+				? [message.retain === true ? message : { ...message, retain: true }]
+				: []
+		}
+		return [message]
+	})
+}
+
+/**
+ * Replace project policy without mutating the caller's history.
+ *
+ * Runtime updates append after the finalized tool batch. A host seeding a new
+ * human turn uses `before-latest-user`, so the policy is context for that
+ * request rather than a reply after it.
+ */
+export function replaceProjectInstructionSnapshot(
+	messages: readonly Message[],
+	snapshot: UserMessage | null,
+	placement: 'append' | 'before-latest-user' = 'append',
+): Message[] {
+	if (snapshot) assertsProjectInstructionMessage(snapshot)
+	// Validate every tagged predecessor before removing it. A host-authoritative
+	// replacement must not turn malformed persisted provenance into a silent
+	// success merely because the bad record happens to be superseded.
+	const validated = collapseProjectInstructionSnapshots(messages)
+	let current: UserMessage | undefined
+	for (let index = validated.length - 1; index >= 0; index -= 1) {
+		const message = validated[index]
+		if (message && isProjectInstructionMessage(message)) {
+			current = message
+			break
+		}
+	}
+	if (
+		snapshot !== null &&
+		current !== undefined &&
+		isDeepStrictEqual(
+			{
+				content: current.content,
+				attachments: current.attachments,
+				source: current.source,
+				cacheHint: current.cacheHint,
+			},
+			{
+				content: snapshot.content,
+				attachments: snapshot.attachments,
+				source: snapshot.source,
+				cacheHint: snapshot.cacheHint,
+			},
+		)
+	) {
+		return validated
+	}
+	if (snapshot === null && current === undefined) return validated
+	const without = validated.filter(
+		(message) => !(message.role === 'user' && message.source?.type === 'project-instructions'),
+	)
+	if (!snapshot) return without
+	const retained = snapshot.retain === true ? snapshot : { ...snapshot, retain: true }
+	if (placement === 'append') return [...without, retained]
+	let insertion = without.length
+	for (let index = without.length - 1; index >= 0; index -= 1) {
+		if (without[index]?.role === 'user') {
+			insertion = index
+			break
+		}
+	}
+	return [...without.slice(0, insertion), retained, ...without.slice(insertion)]
+}

package/src/runtime/query/request-rich-content.ts

@@ -0,0 +1,153 @@
+import type { Message, MessageAttachment, ToolResultBlock } from '../../types/message/index.js'
+
+/**
+ * Maximum accumulated inline rich-content payload sent on one model request.
+ *
+ * Base64 is ASCII, so its JavaScript string length is also its encoded wire
+ * payload length before the surrounding JSON. The bound deliberately counts
+ * the encoded value rather than estimating decoded bytes: request gateways
+ * reject the body they receive, not the file the body represents.
+ */
+export const DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES = 24 * 1024 * 1024
+
+const MAX_REQUEST_RICH_CONTENT_BYTES = Number.MAX_SAFE_INTEGER
+
+export function resolveMaxRequestRichContentBytes(value: number | undefined): number {
+	const resolved = value ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES
+	if (
+		!Number.isSafeInteger(resolved) ||
+		resolved < 0 ||
+		resolved > MAX_REQUEST_RICH_CONTENT_BYTES
+	) {
+		throw new RangeError(
+			`maxRequestRichContentBytes must be a safe integer from 0 to ${MAX_REQUEST_RICH_CONTENT_BYTES}; received ${String(resolved)}`,
+		)
+	}
+	return resolved
+}
+
+type RichKind = 'image' | 'document'
+
+interface RichOccurrence {
+	readonly messageIndex: number
+	readonly itemIndex: number
+	readonly source: 'user' | 'tool'
+	readonly kind: RichKind
+	readonly bytes: number
+}
+
+const userMarker = (kind: RichKind): string =>
+	`[${kind} omitted from this model request to keep the accumulated rich-content payload within its configured size limit; attach it again in a new message if it is still needed.]`
+
+const toolMarker = (kind: RichKind): string =>
+	`[${kind} omitted from this model request to keep the accumulated rich-content payload within its configured size limit; call the producing tool again if it is still needed.]`
+
+function assertInlineAttachment(
+	attachment: MessageAttachment,
+): asserts attachment is Exclude<MessageAttachment, { readonly type: 'stored' }> {
+	if (attachment.type === 'stored') {
+		throw new TypeError(
+			'Cannot budget an unresolved stored attachment; resolve attachment bytes before building a model request',
+		)
+	}
+}
+
+function collectRichOccurrences(messages: readonly Message[]): RichOccurrence[] {
+	const occurrences: RichOccurrence[] = []
+
+	for (const [messageIndex, message] of messages.entries()) {
+		if (message.role === 'user') {
+			for (const [itemIndex, attachment] of (message.attachments ?? []).entries()) {
+				assertInlineAttachment(attachment)
+				occurrences.push({
+					messageIndex,
+					itemIndex,
+					source: 'user',
+					kind: attachment.type === 'document' ? 'document' : 'image',
+					bytes: attachment.data.length,
+				})
+			}
+			continue
+		}
+
+		if (message.role !== 'tool' || !Array.isArray(message.content)) continue
+		for (const [itemIndex, block] of message.content.entries()) {
+			if (block.type !== 'image' && block.type !== 'document') continue
+			occurrences.push({
+				messageIndex,
+				itemIndex,
+				source: 'tool',
+				kind: block.type,
+				bytes: block.data.length,
+			})
+		}
+	}
+
+	return occurrences
+}
+
+function appendMarkers(content: string, kinds: readonly RichKind[]): string {
+	if (kinds.length === 0) return content
+	const markers = kinds.map(userMarker).join('\n\n')
+	return content.length > 0 ? `${content}\n\n${markers}` : markers
+}
+
+/**
+ * Build the provider-bound view of a conversation without editing history.
+ *
+ * User attachments and rich tool-result blocks share one oldest-first budget.
+ * Tool messages and their `toolCallId` are never removed, so the projected
+ * transcript retains its provider-valid call/result structure. Returning the
+ * original array when nothing is omitted makes the no-op and exact-boundary
+ * cases observable and keeps the common path allocation-free.
+ */
+export function projectRequestRichContent(messages: Message[], maxBytes: number): Message[] {
+	const occurrences = collectRichOccurrences(messages)
+	if (maxBytes === 0 || occurrences.length === 0) return messages
+
+	let total = occurrences.reduce((sum, occurrence) => sum + occurrence.bytes, 0)
+	if (total <= maxBytes) return messages
+
+	const omitted = new Map<number, Map<number, RichOccurrence>>()
+	for (const occurrence of occurrences) {
+		if (total <= maxBytes) break
+		total -= occurrence.bytes
+		let byItem = omitted.get(occurrence.messageIndex)
+		if (!byItem) {
+			byItem = new Map()
+			omitted.set(occurrence.messageIndex, byItem)
+		}
+		byItem.set(occurrence.itemIndex, occurrence)
+	}
+
+	return messages.map((message, messageIndex) => {
+		const byItem = omitted.get(messageIndex)
+		if (!byItem) return message
+
+		if (message.role === 'user') {
+			const { attachments = [], ...withoutAttachments } = message
+			const kept = attachments.filter((_attachment, itemIndex) => !byItem.has(itemIndex))
+			const omittedKinds = [...byItem.values()]
+				.filter((occurrence) => occurrence.source === 'user')
+				.sort((a, b) => a.itemIndex - b.itemIndex)
+				.map((occurrence) => occurrence.kind)
+			return {
+				...withoutAttachments,
+				content: appendMarkers(message.content, omittedKinds),
+				...(kept.length > 0 ? { attachments: kept } : {}),
+			}
+		}
+
+		if (message.role === 'tool' && Array.isArray(message.content)) {
+			const content: ToolResultBlock[] = message.content.map((block, itemIndex) => {
+				const occurrence = byItem.get(itemIndex)
+				return occurrence?.source === 'tool'
+					? { type: 'text', text: toolMarker(occurrence.kind) }
+					: block
+			})
+			return { ...message, content }
+		}
+
+		return message
+	})
+}

package/src/runtime/query/result.ts

@@ -1,7 +1,7 @@
 import { type Span, SpanStatusCode } from '@opentelemetry/api'
 import type { PlanManager } from '../../manager/plan/lifecycle.js'
 import type { RunPersistence } from '../../manager/run/persistence.js'
-import { isProviderRequestError } from '../../provider/errors.js'
+import { isCallerAbortError, isProviderRequestError } from '../../provider/errors.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
 import { GENAI, NAMZU } from '../../telemetry/attributes.js'
 import { explainError } from '../../types/errors/catalog.js'
@@ -122,6 +122,17 @@ export class ResultAssembler {
 
 	async *handleError(err: unknown, rootSpan: Span): AsyncGenerator<RunEvent> {
 		const { runMgr, planManager, log, emitEvent, drainPending } = this.config
+		if (isCallerAbortError(err, this.config.signal)) {
+			// Cancellation may happen before the iteration loop owns control —
+			// project preparation, a run-start hook and a pre-model hook all sit
+			// outside its catch. The loop already settles its own aborts, but an
+			// abort escaping one of these boundaries reached the outer catch and
+			// was historically rewritten as a run failure. Preserve the caller's
+			// control-flow verdict and let the normal terminal-event path report it.
+			runMgr.markCancelled()
+			yield* this.completeRun(rootSpan)
+			return
+		}
 		const errorMessage = toErrorMessage(err)
 		// The classifier at the provider boundary already walked the cause
 		// chain over status, errno and `Retry-After`, so a fully-populated

package/src/runtime/query/resume-pending.ts

@@ -86,7 +86,7 @@ export function planPendingResume(
 		return null
 	}
 
-	const assistant = lastAssistantWithUnansweredCalls(checkpoint.messages)
+	const assistant = lastUnansweredBatch(checkpoint.messages)?.assistant
 	if (!assistant?.toolCalls || assistant.toolCalls.length === 0) {
 		log.warn('Checkpoint records a tool_review park but has no unanswered tool calls', {
 			'namzu.checkpoint.id': checkpoint.id,
@@ -142,7 +142,7 @@ function planQuestionResume(
 	questionId: string,
 	log: Logger,
 ): PendingResumePlan | null {
-	const assistant = lastAssistantWithUnansweredCalls(checkpoint.messages)
+	const assistant = lastUnansweredBatch(checkpoint.messages)?.assistant
 	if (!assistant?.toolCalls || assistant.toolCalls.length === 0) {
 		log.warn('Checkpoint records a question park but has no unanswered tool calls', {
 			'namzu.checkpoint.id': checkpoint.id,
@@ -207,7 +207,7 @@ export function planCrashResume(
 	completed: ReadonlyMap<string, unknown>,
 	log: Logger,
 ): PendingResumePlan | null {
-	const assistant = lastAssistantWithUnansweredCalls(checkpoint.messages)
+	const assistant = lastUnansweredBatch(checkpoint.messages)?.assistant
 	const calls = assistant?.toolCalls
 	if (!assistant || !calls || calls.length === 0) return null
 
@@ -376,29 +376,31 @@ function synthesizeResponse(assistant: AssistantMessage): ChatCompletionResponse
  * result is in the history and needs no recovery.
  */
 export function unansweredToolCalls(messages: readonly Message[]): ToolCall[] {
-	const assistant = lastAssistantWithUnansweredCalls(messages)
-	if (!assistant?.toolCalls) return []
-
-	const answered = new Set<string>()
-	for (const msg of messages) {
-		if (msg.role === 'tool' && msg.toolCallId) answered.add(msg.toolCallId)
-	}
-	return assistant.toolCalls.filter((tc) => !answered.has(tc.id))
+	return lastUnansweredBatch(messages)?.unanswered ?? []
 }
 
-function lastAssistantWithUnansweredCalls(messages: readonly Message[]): AssistantMessage | null {
-	const answered = new Set<string>()
-	for (const msg of messages) {
-		if (msg.role === 'tool' && msg.toolCallId) answered.add(msg.toolCallId)
-	}
-
+function lastUnansweredBatch(
+	messages: readonly Message[],
+): { readonly assistant: AssistantMessage; readonly unanswered: ToolCall[] } | null {
 	for (let i = messages.length - 1; i >= 0; i--) {
 		const msg = messages[i]
 		if (msg?.role !== 'assistant') continue
 		const assistant = msg as AssistantMessage
 		const calls = assistant.toolCalls
 		if (!calls || calls.length === 0) continue
-		if (calls.some((tc) => !answered.has(tc.id))) return assistant
+
+		// Only the contiguous result run immediately after this assistant owns
+		// its calls. A future/displaced result cannot prove the call completed;
+		// treating it as one would skip both crash recovery and the conservative
+		// synthetic outcome that prevents a blind side-effect retry.
+		const answered = new Set<string>()
+		for (let resultIndex = i + 1; resultIndex < messages.length; resultIndex++) {
+			const result = messages[resultIndex]
+			if (result?.role !== 'tool') break
+			answered.add(result.toolCallId)
+		}
+		const unanswered = calls.filter((call) => !answered.has(call.id))
+		if (unanswered.length > 0) return { assistant, unanswered }
 		return null
 	}
 	return null

package/src/runtime/query/resume-run.ts

@@ -1,11 +1,12 @@
+import { NamzuError } from '../../types/errors/index.js'
 import type { PendingDecision } from '../../types/hitl/index.js'
 import type { CheckpointStore, FencingToken } from '../../types/run/checkpoint-store.js'
 import type { Run } from '../../types/run/entity.js'
 import type { RunEventReplay } from '../../types/run/event-cursor.js'
 import type { RunEventListener } from '../../types/run/events.js'
 import type { RunState } from '../../types/run/state.js'
-import { type QueryParams, drainQuery } from './index.js'
-import { type RunStateScope, loadRunState } from './run-state.js'
+import { type QueryParams, drainQueryWithSelectedResumeState } from './index.js'
+import { type RunStateScope, loadSelectedRunState } from './run-state.js'
 
 /**
  * What a resume attempt found.
@@ -117,24 +118,35 @@ export async function resumeRun(params: ResumeRunParams): Promise<ResumeOutcome>
 		...rest
 	} = params
 
-	const state = await loadRunState(checkpointStore, scope, checkpointId)
-	if (!state?.checkpointId) return { resumed: false, reason: 'no-checkpoint' }
+	const selected = await loadSelectedRunState(checkpointStore, scope, checkpointId)
+	const state = selected?.state
+	if (!state?.checkpointId || !selected) return { resumed: false, reason: 'no-checkpoint' }
+	assertResumeRequestAttribution(params, state)
 
 	// A park is outstanding until it is answered. `resolvedAt` is what marks
 	// an answered one, so a checkpoint that carries a resolved decision is an
 	// ordinary resume, not a question waiting on anybody.
 	const outstanding = state.pending && !state.pending.resolvedAt ? state.pending : undefined
 	if (outstanding && !pendingDecision) {
-		return { resumed: false, reason: 'awaiting-decision', pending: outstanding, state }
+		return {
+			resumed: false,
+			reason: 'awaiting-decision',
+			pending: outstanding,
+			state,
+		}
 	}
 
 	let replay: RunEventReplay | undefined
 
-	const run = await drainQuery(
+	const run = await drainQueryWithSelectedResumeState(
 		{
 			...rest,
 			messages: [],
 			runId: state.runId,
+			sessionId: state.sessionId,
+			topicId: state.topicId,
+			projectId: state.projectId,
+			tenantId: state.tenantId,
 			// Forwarded, and it is not cosmetic: the run store nests a sub-run's
 			// evidence under `<parent>/children/<run>`, so resuming a sub-run
 			// without this binds `<base>/<run>` instead — a second, empty
@@ -148,11 +160,43 @@ export async function resumeRun(params: ResumeRunParams): Promise<ResumeOutcome>
 			...(pendingDecision ? { pendingDecision } : {}),
 			onEventReplay: (verdict: RunEventReplay) => {
 				replay = verdict
-				onEventReplay?.(verdict)
+				return onEventReplay?.(verdict)
 			},
 		} as QueryParams,
+		{
+			...state,
+			checkpointId: state.checkpointId,
+			...(selected.checkpoint.traceContext
+				? { traceContext: selected.checkpoint.traceContext }
+				: {}),
+		},
 		listener,
 	)
 
-	return { resumed: true, run, state, ...(replay !== undefined ? { replay } : {}) }
+	return {
+		resumed: true,
+		run,
+		state,
+		...(replay !== undefined ? { replay } : {}),
+	}
+}
+
+function assertResumeRequestAttribution(params: ResumeRunParams, state: RunState): void {
+	const mismatchedFields: string[] = []
+	if (params.scope.runId !== state.runId) mismatchedFields.push('runId')
+	if (params.sessionId !== state.sessionId) mismatchedFields.push('sessionId')
+	if (params.topicId !== state.topicId) mismatchedFields.push('topicId')
+	if (params.projectId !== state.projectId) mismatchedFields.push('projectId')
+	if (params.tenantId !== state.tenantId) mismatchedFields.push('tenantId')
+	if (params.parentRunId !== undefined && params.parentRunId !== state.parentRunId) {
+		mismatchedFields.push('parentRunId')
+	}
+	if (mismatchedFields.length === 0) return
+
+	throw new NamzuError({
+		code: 'invalid_config',
+		message:
+			'The resume request attribution does not match the checkpoint scope selected for this run.',
+		details: { fields: mismatchedFields },
+	})
 }

package/src/runtime/query/run-state.ts

@@ -88,13 +88,22 @@ export async function loadRunState(
 	scope: RunStateScope,
 	checkpointId?: CheckpointId,
 ): Promise<RunState | null> {
+	return (await loadSelectedRunState(store, scope, checkpointId))?.state ?? null
+}
+
+/** @internal The exact checkpoint selected together with its public run-state projection. */
+export async function loadSelectedRunState(
+	store: CheckpointStore,
+	scope: RunStateScope,
+	checkpointId?: CheckpointId,
+): Promise<{ readonly state: RunState; readonly checkpoint: IterationCheckpoint } | null> {
 	const checkpoint = checkpointId
 		? await store.readCheckpoint(scope, checkpointId)
 		: ((await findPendingCheckpoint(store, scope)) ?? (await newest(store, scope)))
 
 	if (!checkpoint) return null
 
-	return {
+	const state: RunState = {
 		version: RUN_STATE_VERSION,
 		runId: checkpoint.runId,
 		sessionId: scope.sessionId,
@@ -113,6 +122,7 @@ export async function loadRunState(
 		...(checkpoint.pending ? { pending: checkpoint.pending } : {}),
 		capturedAt: Date.now(),
 	}
+	return { state, checkpoint }
 }
 
 async function newest(