@namzu/sdk 35.0.0 → 37.0.0

package/src/provider/token-budget.ts

@@ -49,8 +49,44 @@ export function withTokenBudget(provider: LLMProvider, budget: TokenBudget): LLM
 		let completed = false
 		let outputObserved = false
 		let uncertainRetry = false
+		let contacted = false
+		let abandoned = false
+		let iterator: AsyncIterator<StreamChunk> | undefined
+		let onAbort: (() => void) | undefined
+		const signal = params.signal
+		const cancellation = signal
+			? new Promise<never>((_resolve, reject) => {
+					onAbort = () => {
+						abandoned = true
+						reject(signal.reason)
+					}
+					signal.addEventListener('abort', onAbort, { once: true })
+				})
+			: undefined
+		// Admission persistence can have outlived the caller's authority. The
+		// check below may reject before the first pull attaches a race handler.
+		cancellation?.catch(() => {})
 		try {
-			for await (const chunk of provider.chatStream(params)) {
+			signal?.throwIfAborted()
+			contacted = true
+			iterator = provider.chatStream(params)[Symbol.asyncIterator]()
+			for (;;) {
+				signal?.throwIfAborted()
+				const next = iterator.next()
+				// Observe an already-issued pull even after cancellation wins the
+				// race. A late usage frame is evidence of spend, not permission to
+				// reopen the account or to request another frame.
+				void next
+					.then(async (result) => {
+						if (!result.done && result.value.usage) {
+							usage = usage ? mergeTokenUsage(usage, result.value.usage) : { ...result.value.usage }
+							if (abandoned) await budget.failRequest(requestId, usage)
+						}
+					})
+					.catch(() => {})
+				const result = await (cancellation ? Promise.race([next, cancellation]) : next)
+				if (result.done) break
+				const chunk = result.value
 				const recovery = chunk.retry ?? chunk.fallback
 				if (
 					recovery &&
@@ -71,9 +107,6 @@ export function withTokenBudget(provider: LLMProvider, budget: TokenBudget): LLM
 					})
 				}
 				if (Object.keys(chunk.delta).length > 0) outputObserved = true
-				if (chunk.usage) {
-					usage = usage ? mergeTokenUsage(usage, chunk.usage) : { ...chunk.usage }
-				}
 				if (chunk.error) throw new Error(chunk.error)
 				yield chunk
 			}
@@ -88,16 +121,27 @@ export function withTokenBudget(provider: LLMProvider, budget: TokenBudget): LLM
 			// A typed rejection before any generation differs from a lost reply.
 			// In particular a context-overflow retry must not reset or poison spend.
 			if (
-				!outputObserved &&
-				usage === undefined &&
-				!uncertainRetry &&
-				rejectedBeforeGeneration(error)
+				!contacted ||
+				(!abandoned &&
+					!outputObserved &&
+					usage === undefined &&
+					!uncertainRetry &&
+					rejectedBeforeGeneration(error))
 			) {
 				await budget.finishRequest(requestId, { ...EMPTY_TOKEN_USAGE })
 				completed = true
 			}
 			throw error
 		} finally {
+			abandoned = !completed
+			if (onAbort) signal?.removeEventListener('abort', onAbort)
+			// A blocked async generator queues return() behind its pending next().
+			// Waiting for it would also delay the durable unknown-spend marker.
+			try {
+				void iterator?.return?.().catch(() => {})
+			} catch {
+				// Cleanup cannot replace the provider outcome.
+			}
 			if (!completed) await budget.failRequest(requestId, usage)
 		}
 	}

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 ──────────────────────────────────────────
 
@@ -649,8 +651,9 @@ export {
 	LocalSandboxProvider,
 	missingIsolation,
 	SandboxProviderFactory,
+	walkFilesViaExec,
 } from './sandbox/index.js'
-export type { LocalSandboxProviderOptions } from './sandbox/index.js'
+export type { LocalSandboxProviderOptions, SandboxFileWalkExec } from './sandbox/index.js'
 
 // The classified provider-failure surface: a driver states what went wrong
 // first-hand, and the run boundary reads it to choose between a pause and a
@@ -1110,6 +1113,8 @@ export { anyOf, hasToolCall, stepCountIs } from './types/run/step.js'
 // ─── evaluation harness ──────────────────────────────────────────────────
 
 export {
+	compareHarnessTrials,
+	reviewHarnessCandidate,
 	completionScorer,
 	containsScorer,
 	customScorer,

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,

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,

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',
+			},
 		})
 	}
 }