@namzu/sdk 36.0.0 → 38.0.0

package/src/provider/capabilities.ts

@@ -1,4 +1,9 @@
-import type { LLMProvider, ProviderCapabilities } from '../types/provider/index.js'
+import type {
+	ChatCompletionParams,
+	LLMProvider,
+	ProviderCapabilities,
+} from '../types/provider/index.js'
+import { ProviderRequestError } from './errors.js'
 
 /**
  * Fully-resolved capability set: every flag present, no optionals left.
@@ -59,3 +64,38 @@ export function resolveProviderCapabilities(
 		maxOutputTokens: declared?.maxOutputTokens,
 	}
 }
+
+/** Require explicit wire support before dispatching a native JSON Schema request. */
+export function assertNativeStructuredOutputSupported(
+	provider: Pick<LLMProvider, 'id' | 'capabilities'>,
+	params: Pick<ChatCompletionParams, 'responseFormat'>,
+): void {
+	if (
+		params.responseFormat?.type === 'json_schema' &&
+		provider.capabilities?.supportsNativeStructuredOutput !== true
+	) {
+		throw new ProviderRequestError({
+			kind: 'bad_request',
+			providerId: provider.id,
+			providerCode: 'native_structured_output_unsupported',
+			detail:
+				'Native JSON Schema output requires a provider that declares supportsNativeStructuredOutput: true.',
+		})
+	}
+}
+
+/** Refuse a hosted search request before dispatch when the route cannot honor it. */
+export function assertHostedWebSearchSupported(
+	provider: Pick<LLMProvider, 'id' | 'capabilities'>,
+	params: Pick<ChatCompletionParams, 'webSearch'>,
+): void {
+	if (params.webSearch && provider.capabilities?.supportsHostedWebSearch !== true) {
+		throw new ProviderRequestError({
+			kind: 'bad_request',
+			providerId: provider.id,
+			providerCode: 'hosted_web_search_unsupported',
+			detail:
+				'This provider does not support hosted web search. Disable web.search or select a supported provider.',
+		})
+	}
+}

package/src/provider/fallback.ts

@@ -31,6 +31,10 @@ import type {
 	ThinkingConfig,
 } from '../types/provider/index.js'
 import type { Logger } from '../utils/logger.js'
+import {
+	assertHostedWebSearchSupported,
+	assertNativeStructuredOutputSupported,
+} from './capabilities.js'
 
 /**
  * One member of the chain: a constructed provider, and the model to ask it for.
@@ -209,13 +213,14 @@ function shouldFallOver(err: unknown, providerId: string): boolean {
  */
 function isOutputChunk(chunk: StreamChunk): boolean {
 	if (chunk.retry !== undefined || chunk.fallback !== undefined) return false
-	const { content, toolCalls, toolCallEnd, reasoning, citation } = chunk.delta
+	const { content, toolCalls, toolCallEnd, reasoning, citation, hostedTool } = chunk.delta
 	return Boolean(
 		content ||
 			toolCalls?.length ||
 			toolCallEnd ||
 			reasoning !== undefined ||
-			citation !== undefined,
+			citation !== undefined ||
+			hostedTool !== undefined,
 	)
 }
 
@@ -396,6 +401,8 @@ export function withProviderFallback(
 					chainIndex: cursor,
 				},
 			}
+			assertNativeStructuredOutputSupported(member.provider, request)
+			assertHostedWebSearchSupported(member.provider, request)
 			let produced = false
 			try {
 				for await (const chunk of member.provider.chatStream(request)) {

package/src/public-runtime.ts

@@ -380,6 +380,8 @@ export type {
 // nothing.
 export { RUN_MEMORY_TAG, createMemoryPromoter } from './run/index.js'
 export type { MemoryPromoterOptions } from './run/index.js'
+export { createMemoryRecallStep } from './run/memory-recall.js'
+export type { MemoryRecallOptions } from './run/memory-recall.js'
 
 // ─── personas, skills, advisory ──────────────────────────────────────────
 
@@ -1111,6 +1113,8 @@ export { anyOf, hasToolCall, stepCountIs } from './types/run/step.js'
 // ─── evaluation harness ──────────────────────────────────────────────────
 
 export {
+	compareHarnessTrials,
+	reviewHarnessCandidate,
 	completionScorer,
 	containsScorer,
 	customScorer,
@@ -1335,3 +1339,5 @@ export { WORKING_STATE_MIME } from './connector/mcp/adapter.js'
 export { TokenBudget, validateTokenBudgetSnapshot } from './run/token-budget.js'
 export { DiskTokenBudgetStore, openTokenBudget } from './store/run/token-budget-disk.js'
 export { validateTokenBudgetBinding } from './types/run/token-budget-store.js'
+
+export { snapshotRequestContext, diffRequestContext } from './runtime/query/request-context.js'

package/src/public-tools.ts

@@ -97,7 +97,11 @@ export {
 	buildTaskUpdateTool,
 } from './tools/task/index.js'
 export { buildAdvisoryTools } from './tools/advisory/index.js'
-export { buildMemoryTools } from './tools/memory/index.js'
+export {
+	buildMemoryTools,
+	buildUpdateMemoryTool,
+	buildDeleteMemoryTool,
+} from './tools/memory/index.js'
 export { buildCoordinatorTools } from './tools/coordinator/index.js'
 export {
 	buildAskUserQuestionTool,
@@ -121,3 +125,5 @@ export {
 	createConnectorRouterTool,
 	createConnectorTools,
 } from './connector/tools/index.js'
+
+export { createFileReadTracker } from './tools/file-read-tracker.js'

package/src/public-types.ts

@@ -19,6 +19,7 @@ export type * from './types/common/index.js'
 export type { CoalesceOptions } from './streaming/coalesce.js'
 export type * from './types/bidi/index.js'
 export type * from './types/tool/index.js'
+export type { WorkerCodeRuntimeOptions } from './execution/code-runtime/worker.js'
 export type {
 	CodeRunOutcome,
 	CodeRunResult,
@@ -438,3 +439,9 @@ export type {
 	DiskTokenBudgetStoreConfig,
 	OpenTokenBudgetOptions,
 } from './store/run/token-budget-disk.js'
+
+export type {
+	RequestContextPart,
+	RequestContextSnapshot,
+	RequestContextChange,
+} from './runtime/query/request-context.js'

package/src/registry/tool/execute.ts

@@ -18,6 +18,7 @@ import type {
 	ToolTierConfig,
 } from '../../types/tool/index.js'
 import { toErrorMessage } from '../../utils/error.js'
+import { cloneJsonValue as clonePreparedInput } from '../../utils/json-snapshot.js'
 import { ManagedRegistry } from '../ManagedRegistry.js'
 import { renderToolSchema } from './schema.js'
 import { ToolResultHalted, screenToolResult } from './screen.js'
@@ -90,82 +91,6 @@ export function assertToolName(name: string): void {
 	)
 }
 
-function clonePreparedInput(value: unknown, freeze: boolean, path = '$'): unknown {
-	const active = new WeakSet<object>()
-	const copies = new WeakMap<object, object>()
-
-	const clone = (candidate: unknown, at: string): unknown => {
-		if (candidate === null || typeof candidate === 'string' || typeof candidate === 'boolean') {
-			return candidate
-		}
-		if (typeof candidate === 'number') {
-			if (!Number.isFinite(candidate) || Object.is(candidate, -0)) {
-				throw new TypeError(`${at} must be a finite JSON number`)
-			}
-			return candidate
-		}
-		if (typeof candidate !== 'object') {
-			throw new TypeError(`${at} must be a JSON value, not ${typeof candidate}`)
-		}
-		if (active.has(candidate)) throw new TypeError(`${at} contains a cycle`)
-		const existing = copies.get(candidate)
-		if (existing) return existing
-
-		active.add(candidate)
-		try {
-			if (Array.isArray(candidate)) {
-				const extra = Reflect.ownKeys(candidate).filter(
-					(key) => key !== 'length' && (typeof key !== 'string' || !/^(0|[1-9]\d*)$/.test(key)),
-				)
-				if (extra.length > 0) throw new TypeError(`${at} has non-JSON array properties`)
-				const result: unknown[] = new Array(candidate.length)
-				copies.set(candidate, result)
-				for (let index = 0; index < candidate.length; index++) {
-					const descriptor = Object.getOwnPropertyDescriptor(candidate, String(index))
-					if (!descriptor) throw new TypeError(`${at}[${index}] is a sparse array hole`)
-					if (!descriptor.enumerable || !('value' in descriptor)) {
-						throw new TypeError(`${at}[${index}] must be an enumerable data property`)
-					}
-					result[index] = clone(descriptor.value, `${at}[${index}]`)
-				}
-				if (freeze) Object.freeze(result)
-				return result
-			}
-
-			const prototype = Object.getPrototypeOf(candidate)
-			if (prototype !== Object.prototype && prototype !== null) {
-				throw new TypeError(`${at} must be a plain JSON object`)
-			}
-			// JSON does not preserve prototypes. Canonicalize both admitted plain
-			// shapes to an ordinary object so a disk checkpoint round-trip compares
-			// equal to a fresh preparation of the same semantic value. Properties
-			// are still defined explicitly, so a literal "__proto__" key remains
-			// data rather than changing this object's prototype.
-			const result: Record<string, unknown> = {}
-			copies.set(candidate, result)
-			for (const key of Reflect.ownKeys(candidate)) {
-				if (typeof key !== 'string') throw new TypeError(`${at} has a symbol property`)
-				const descriptor = Object.getOwnPropertyDescriptor(candidate, key)
-				if (!descriptor?.enumerable || !('value' in descriptor)) {
-					throw new TypeError(`${at}.${key} must be an enumerable data property`)
-				}
-				Object.defineProperty(result, key, {
-					value: clone(descriptor.value, `${at}.${key}`),
-					enumerable: true,
-					writable: !freeze,
-					configurable: !freeze,
-				})
-			}
-			if (freeze) Object.freeze(result)
-			return result
-		} finally {
-			active.delete(candidate)
-		}
-	}
-
-	return clone(value, path)
-}
-
 /**
  * Two sources contributed the same tool name and neither may take it.
  *
@@ -364,17 +289,30 @@ export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 	 * would churn that prefix repeatedly and is rejected.
 	 */
 	searchDeferred(query: string): ToolDefinition[] {
+		return this.searchByAvailability(query, ['deferred'])
+	}
+
+	/** Active matches use the same ranking, also recognizing exact short or generic names. */
+	searchActive(query: string): ToolDefinition[] {
+		return this.searchByAvailability(query, ['active'], true)
+	}
+
+	private searchByAvailability(
+		query: string,
+		states: ToolAvailability[],
+		allowExactName = false,
+	): ToolDefinition[] {
 		const q = query.toLowerCase().trim()
 		if (q.length === 0) return []
 		const terms = q.split(/\s+/).filter((tok) => tok.length >= 3 && !SEARCH_STOP_TOKENS.has(tok))
-		if (terms.length === 0) return []
+		if (terms.length === 0 && !allowExactName) return []
 
 		const scored: Array<{ tool: ToolDefinition; score: number }> = []
-		for (const tool of this.getByAvailability(['deferred'])) {
+		for (const tool of this.getByAvailability(states)) {
 			const name = tool.name.toLowerCase()
 			const description = tool.description.toLowerCase()
 			const argumentNames = listArgumentNames(tool)
-			let score = 0
+			let score = allowExactName && terms.length === 0 && name === q ? SEARCH_WEIGHT_NAME_EXACT : 0
 			for (const term of terms) {
 				if (name === term) {
 					score += SEARCH_WEIGHT_NAME_EXACT

package/src/run/command-gate.ts

@@ -110,11 +110,18 @@ export interface CommandGateOptions {
 
 /** Head and tail of a command's output, with the middle marked as dropped. */
 export function clipOutput(text: string, max: number): string {
+	if (!Number.isSafeInteger(max) || max < 0) {
+		throw new RangeError('maxOutputChars must be a nonnegative safe integer.')
+	}
 	const trimmed = text.trimEnd()
 	if (trimmed.length <= max) return trimmed
-	const half = Math.floor(max / 2)
-	const dropped = trimmed.length - half * 2
-	return `${trimmed.slice(0, half)}\n… ${dropped} characters omitted …\n${trimmed.slice(-half)}`
+	const markerBudget = `\n… ${trimmed.length} characters omitted …\n`.length
+	if (max < markerBudget) return max === 0 ? '' : '…'
+	const retained = max - markerBudget
+	const head = Math.ceil(retained / 2)
+	const tail = retained - head
+	const marker = `\n… ${trimmed.length - retained} characters omitted …\n`
+	return `${trimmed.slice(0, head)}${marker}${tail > 0 ? trimmed.slice(-tail) : ''}`
 }
 
 interface LastFailure {
@@ -142,7 +149,7 @@ function failureFeedback(
 					`Retained output is incomplete: ${truncatedStreams.join(' and ')} ${truncatedStreams.length === 1 ? 'was' : 'were'} truncated by the execution context. Re-run with a narrower command or filter to recover the missing diagnostics.`,
 				]
 	return [
-		`The answer was not accepted: \`${command}\` failed (attempt ${attempt}, exit ${result.exitCode}).`,
+		`The answer was not accepted: \`${command}\` failed (attempt ${attempt}, exit ${result.exitCode}${result.termination ? `, terminated: ${result.termination.origin}` : ''}).`,
 		'',
 		'Output:',
 		'```',
@@ -158,9 +165,9 @@ function unchangedFeedback(command: string, attempt: number): string {
 	return [
 		`The answer was not accepted, and \`${command}\` was NOT re-run (attempt ${attempt}).`,
 		'',
-		'The workspace is byte-for-byte identical to what it was when that command last failed — no file was created, edited or deleted since. Running it again would produce the failure you have already been shown.',
+		'The configured change detector reports the same state as after the last failure. The default detector covers the Git commit and Git-visible working state; ignored files and external inputs may have changed.',
 		'',
-		'Edit something before trying to finish again. If you believe the change you described was made, verify it by reading the file: it is not on disk.',
+		'Check that the intended fix is present and addresses the reported failure. If verification depends on state outside the detector, the host should supply a matching fingerprint or return null to re-run checks.',
 	].join('\n')
 }
 
@@ -183,20 +190,39 @@ export function createCommandGate(options: CommandGateOptions): ReviewAnswer {
 	const timeoutMs = options.timeoutMs ?? DEFAULT_GATE_TIMEOUT_MS
 	const maxRetries = options.maxRetries ?? DEFAULT_GATE_MAX_RETRIES
 	const maxOutputChars = options.maxOutputChars ?? DEFAULT_GATE_OUTPUT_CHARS
+	// Validate before a reviewer is installed: malformed limits cannot turn
+	// a formatting exception during verification into an unreviewed answer.
+	clipOutput('', maxOutputChars)
 
 	// Built once and reused: constructing a context per attempt would re-stat
 	// the directory for no gain, and the context holds nothing per-run.
 	const context = new LocalExecutionContext({ id: 'namzu-command-gate', cwd })
 	const exec: GateExec =
 		options.exec ?? ((command, args, opts) => context.executeCommand(command, args, opts))
-	const fingerprint =
-		options.fingerprint ?? (() => fingerprintWorkspace({ cwd, exec, timeoutMs: 20_000 }))
+	const readFingerprint = async (signal?: AbortSignal): Promise<string | null> => {
+		if (signal?.aborted) return null
+		try {
+			return options.fingerprint
+				? await options.fingerprint()
+				: await fingerprintWorkspace({
+						cwd,
+						timeoutMs: 20_000,
+						exec: (command, args, commandOptions) =>
+							exec(command, args, { ...commandOptions, ...(signal ? { signal } : {}) }),
+					})
+		} catch {
+			return null
+		}
+	}
 
 	let attempt = 0
 	let last: LastFailure | undefined
 	let executions = 0
 
-	return async (): Promise<AnswerReview> => {
+	return async (_answer, reviewContext): Promise<AnswerReview> => {
+		const signal = reviewContext.signal
+		if (signal?.aborted)
+			return { accept: false, feedback: 'Verification was cancelled before admission.' }
 		attempt += 1
 
 		// A gate that already failed, over a tree nothing has touched since.
@@ -209,7 +235,7 @@ export function createCommandGate(options: CommandGateOptions): ReviewAnswer {
 		// that deleted it killed no test, which is what a dead condition looks
 		// like from the outside.
 		if (last && last.fingerprint !== null) {
-			const now = await fingerprint()
+			const now = await readFingerprint(signal)
 			if (now === last.fingerprint) {
 				return { accept: false, feedback: unchangedFeedback(last.command, attempt) }
 			}
@@ -221,20 +247,42 @@ export function createCommandGate(options: CommandGateOptions): ReviewAnswer {
 
 		executions += 1
 		for (const command of commands) {
+			if (signal?.aborted)
+				return { accept: false, feedback: 'Verification was cancelled before admission.' }
 			// `shell: true` because the operator handed over a command LINE —
 			// `pnpm test -- --run`, with its flags and its quoting — and taking
 			// that as an executable name plus literal arguments would fail on
 			// every gate anyone would actually write. Explicit, per the note on
 			// `LocalExecutionContext.executeCommand`: shell interpretation is
 			// opt-in, and this is the opt-in.
-			const result = await exec(command, [], { cwd, timeoutMs, shell: true })
-			if (result.exitCode === 0) continue
+			let result: CommandResult
+			try {
+				result = await exec(command, [], {
+					cwd,
+					timeoutMs,
+					shell: true,
+					...(signal ? { signal } : {}),
+				})
+			} catch (error) {
+				// A command that could not be observed completing is not a pass.
+				// Keep this inside the builtin reviewer: generic review callbacks
+				// historically fail open on throws. No fabricated exit status.
+				last = { command, fingerprint: null }
+				return {
+					accept: false,
+					feedback: `The answer was not accepted: verification with \`${command}\` could not complete (attempt ${attempt}).\n${clipOutput(error instanceof Error ? error.message : String(error), maxOutputChars)}\nCheck the execution problem and any partial effects before retrying. Do not claim verification passed.`,
+				}
+			}
+			if (signal?.aborted) return { accept: false, feedback: 'Verification was cancelled.' }
+			if (result.exitCode === 0 && result.termination === undefined) continue
 
 			// Taken AFTER the failure, not before the run: the comparison next
 			// time is against the tree this verdict was formed over. A snapshot
 			// from before the command would miss anything the command itself
 			// wrote — a formatter, a snapshot updater, a lockfile.
-			last = { command, fingerprint: await fingerprint() }
+			// Interrupted verification is not a stable failure of these source
+			// bytes. Allow another check even when no tracked file has changed.
+			last = { command, fingerprint: result.termination ? null : await readFingerprint(signal) }
 			return { accept: false, feedback: failureFeedback(command, attempt, result, maxOutputChars) }
 		}
 

package/src/run/index.ts

@@ -27,3 +27,5 @@ export type { LimitCheckerState, LimitCheckResult } from './LimitChecker.js'
 
 export { RUN_MEMORY_TAG, createMemoryPromoter } from './memory-promoter.js'
 export type { MemoryPromoterOptions } from './memory-promoter.js'
+export { createMemoryRecallStep } from './memory-recall.js'
+export type { MemoryRecallOptions } from './memory-recall.js'

package/src/run/memory-promoter.ts

@@ -1,41 +1,10 @@
 /**
- * The default {@link PromoteMemory}: write what a run learned into a
- * {@link MemoryStore}, or write nothing at all.
- *
- * `promoteMemory` is called once at settle with the compaction extractor's
- * already-structured output — decisions, discoveries, user requirements,
- * failures, environment facts — and **nothing shipped supplied the hook**.
- * So the structure the compaction pass had spent tokens producing was
- * serialized into one system message and dropped on the floor when the run
- * ended, exactly as its own module comment says. This is the supplier, and
- * it is mostly a filter: the hard part — extracting facts from a transcript
- * — already happened.
- *
- * ## The filter, which is the only decision here
- *
- * **A run that learned nothing must leave nothing.** Not an empty record,
- * not a record whose body says "no decisions" — nothing. A promoter that
- * wrote a row per run would fill the store with the runs least worth
- * remembering, and `search_memory` would then return them: the model reads
- * that store on later runs, so noise here is not merely wasted disk, it is
- * context spent on a run that did nothing.
- *
- * What counts as having learned something is the five KNOWLEDGE categories —
- * decisions, discoveries, user requirements, failures, environment. Not
- * `task`, which every run has because it is the prompt restated. Not
- * `files`, which every run that opened anything has, and which says what was
- * touched rather than what was learned. A run whose only trace is "it read
- * six files" is the exact record this filter exists to refuse.
- *
- * ## What it does NOT do
- *
- * Deduplicate against what is already stored, merge with a previous run's
- * record, or expire anything. Each is a policy with real trade-offs and a
- * host that wants one owns it — `promoteMemory` is a callback precisely so
- * that the runtime does not decide this. This is the obvious default, not
- * the only possible one.
+ * Select useful extracted claims for durable recall. Exact repeated claim sets
+ * are suppressed when already stored; archived claims are not reactivated.
+ * This deterministic filter does not verify truth or reconcile paraphrases.
  */
 
+import { createHash } from 'node:crypto'
 import type { MemoryStore } from '../types/memory/index.js'
 import type { PromoteMemory, RunMemoryCandidate } from '../types/run/memory-promotion.js'
 
@@ -85,15 +54,18 @@ function knowledge(
 ): readonly (readonly [string, readonly string[]])[] {
 	const out: (readonly [string, readonly string[]])[] = []
 	for (const [key, heading] of KNOWLEDGE) {
-		const items = candidate[key] as readonly string[]
+		const items = [
+			...new Set((candidate[key] as readonly string[]).map((item) => item.trim()).filter(Boolean)),
+		]
 		if (items.length > 0) out.push([heading, items.slice(0, cap)])
 	}
 	return out
 }
 
-/** A one-line summary naming what kind of knowledge the record holds. */
+/** Carry actual claims into search results, with their category attribution. */
 function summarize(sections: readonly (readonly [string, readonly string[]])[]): string {
-	return sections.map(([heading, items]) => `${heading.toLowerCase()} (${items.length})`).join(', ')
+	const text = sections.map(([heading, items]) => `${heading}: ${items[0]}`).join('; ')
+	return text.length <= 600 ? text : `${text.slice(0, 599).replace(/[\uD800-\uDBFF]$/, '')}…`
 }
 
 function render(
@@ -131,6 +103,8 @@ function render(
  */
 export function createMemoryPromoter(options: MemoryPromoterOptions): PromoteMemory {
 	const cap = options.maxPerCategory ?? 20
+	if (!Number.isSafeInteger(cap) || cap < 1)
+		throw new Error('maxPerCategory must be a positive integer')
 	const tags = [RUN_MEMORY_TAG, ...(options.tags ?? [])]
 
 	return async (candidate: RunMemoryCandidate): Promise<void> => {
@@ -139,17 +113,35 @@ export function createMemoryPromoter(options: MemoryPromoterOptions): PromoteMem
 		// of rows describing runs that discovered nothing is a store whose
 		// search results are mostly noise, and the model reads that store.
 		if (sections.length === 0) return
+		const digest = createHash('sha256').update(JSON.stringify(sections)).digest('hex')
+		const knowledgeTag = `knowledge:${digest}`
+		// A prior exact claim, including one deliberately archived, need not be
+		// saved again. This is not a cross-process uniqueness guarantee: the
+		// store's individual operations are atomic, not this read/create pair.
+		const existing = await options.store.list({
+			tags: [...tags, knowledgeTag],
+		})
+		for (const entry of existing.entries) {
+			const full = await options.store.get(entry.id)
+			if (full?.metadata?.source === RUN_MEMORY_TAG && full.metadata.knowledgeDigest === digest)
+				return
+		}
 
 		await options.store.create({
 			title: candidate.task.trim() || `Run ${candidate.runId}`,
 			summary: summarize(sections),
 			content: render(candidate, sections),
-			tags,
+			tags: [...tags, knowledgeTag],
 			format: 'markdown',
 			// The run id, so a record can be traced back to the run that formed
 			// it. Evidence rather than decoration: without it a surprising
 			// memory cannot be checked against what actually happened.
-			metadata: { runId: candidate.runId, source: RUN_MEMORY_TAG },
+			metadata: {
+				runId: candidate.runId,
+				source: RUN_MEMORY_TAG,
+				knowledgeDigest: digest,
+				verification: 'unverified',
+			},
 		})
 	}
 }