@namzu/sdk 38.2.1 → 40.0.0

package/src/runtime/query/file-evidence-seed.ts

@@ -0,0 +1,126 @@
+import { resolveWithinAnyReal, toolRoots } from '../../tools/paths.js'
+import type { Message } from '../../types/message/index.js'
+import type { FileReadTracker } from '../../types/tool/index.js'
+import {
+	type FileKeyResolver,
+	type LedgerReplayReport,
+	type PathAttributions,
+	collectObservedPaths,
+	createPathAttributions,
+	replayObservationLedger,
+} from './file-evidence-replay.js'
+
+/**
+ * Seeding an observation ledger from history, in the key space the tools use.
+ *
+ * The replay itself is pure and stays that way. What lives here is the one
+ * thing it cannot do for itself: work out which ledger key each path in the
+ * history belongs to. On a host that is not `resolve(cwd, path)` — `write`,
+ * `edit` and `read` all key on `resolveWithinAnyReal`, which canonicalizes
+ * every symlink on the way, because a ledger entry has to identify a FILE and
+ * two spellings of one file must not become two entries.
+ *
+ * Seeding lexically instead is worse than useless. The projection looks up
+ * lexically too, so it would match a fingerprint the seed had just written into
+ * a key space nothing else touches — while every drift refusal, made by a tool,
+ * lands on the canonical key and never withdraws it. The runtime would go on
+ * telling the model a body it can no longer vouch for, with no mechanism left
+ * to take it back. So the resolution happens here, with the tools' own
+ * function, and a path that will not resolve gets no key at all.
+ */
+const NOTHING: LedgerReplayReport = { pathsWitnessed: 0, pathsSeen: 0, unitsReplayed: 0 }
+
+/**
+ * Distinct paths one seeding will canonicalize before it replays anything.
+ *
+ * A ceiling rather than a budget because the work is uniform: each path is a
+ * handful of `realpath` calls, once per conversation. Counted on distinct
+ * SPELLINGS, the ones only `read` names included — a read has to be keyed too
+ * or it cannot contradict a claim — so two spellings of one file count twice.
+ * A history naming more paths than this is not a conversation whose ledger is
+ * worth guessing at, and it seeds nothing rather than resolving a prefix and
+ * abandoning the rest — a partially keyed walk is a walk that cannot say what
+ * a mutation replaced. That is a total loss for the conversation, not a partial
+ * one: it starts from the empty ledger a resume has always started from, and
+ * its first mutation of each path re-establishes it.
+ */
+export const MAX_RESOLVED_PATHS = 1024
+
+/** What a caller needs to key a path the way its tools will. */
+export interface ObservationSeedContext {
+	readonly workingDirectory: string
+	/** See `ToolContext.additionalDirectories`; part of the tools' resolution. */
+	readonly additionalDirectories?: readonly string[]
+	/** True when this run's tools address a sandbox, whose keys are paths as written. */
+	readonly sandboxed?: boolean
+}
+
+/**
+ * Rebuild `tracker` from a conversation's own `messages`.
+ *
+ * For a host that keeps one tracker per conversation and has just restored one:
+ * the ledger is process memory, so a resumed conversation starts with nothing
+ * in it and re-reads files whose whole body is already in the transcript. Call
+ * it once, before the conversation's first request. Reading files is confined
+ * to canonicalizing the paths in the history; no file's CONTENT is read, and
+ * every body restored is one the visible calls reconstruct exactly.
+ *
+ * Content-backed observations, and only those. A path the walk cannot rebuild
+ * is left out of the ledger rather than entered without a fingerprint, so
+ * `write`'s read-before-overwrite refusal stands over it exactly as it does
+ * against the empty ledger a resume gets today. Three things seed nothing at
+ * all, and the report says so: a history naming more than
+ * {@link MAX_RESOLVED_PATHS} distinct path spellings, one whose ids are
+ * ambiguous, and one holding a mutation no path can be recovered from —
+ * whatever the transcript says came back to that mutation, since a key is what
+ * withdrawing one path rather than the whole pass takes. A call whose arguments
+ * are too long to read as JSON at all is one of that last kind; the replay
+ * states the ceiling.
+ */
+export async function seedObservationLedger(
+	messages: readonly Message[],
+	tracker: FileReadTracker,
+	context: ObservationSeedContext,
+): Promise<LedgerReplayReport> {
+	// One attribution cache across both halves. The path collection and the
+	// walk ask the same question of the same calls — which file did this touch
+	// — and answering it means reading a string that, for a `write`, is a whole
+	// file body. Asking once per seeding rather than once per half is why the
+	// replay's own ceiling on that read can be as generous as it is.
+	const attributions = createPathAttributions()
+	const keyOf = await resolveObservedFileKeys(messages, context, attributions)
+	return keyOf ? replayObservationLedger(messages, tracker, keyOf, attributions) : NOTHING
+}
+
+/**
+ * The tools' key for every path this history names, or `undefined` when the
+ * pass should not run at all.
+ *
+ * `undefined` for a history with nothing to reconstruct and for one past the
+ * ceiling. A path the resolver refuses — it escapes the roots this run may
+ * reach, or the working directory itself is gone — is simply left unkeyed;
+ * the replay then treats the mutation that named it as unattributable, which
+ * is the fail-closed answer and the same one it gives a call it cannot parse.
+ */
+async function resolveObservedFileKeys(
+	messages: readonly Message[],
+	context: ObservationSeedContext,
+	attributions: PathAttributions,
+): Promise<FileKeyResolver | undefined> {
+	const paths = collectObservedPaths(messages, attributions)
+	if (paths.length === 0 || paths.length > MAX_RESOLVED_PATHS) return undefined
+	// A sandbox has its own root and its own resolver, and the tools key on the
+	// path as written there. Canonicalizing it against the host filesystem would
+	// ask about the wrong machine.
+	if (context.sandboxed) return (path: string) => path
+	const roots = toolRoots(context)
+	const keys = new Map<string, string>()
+	for (const path of paths) {
+		try {
+			keys.set(path, await resolveWithinAnyReal(roots, path))
+		} catch {
+			// Left unkeyed on purpose; see above.
+		}
+	}
+	return (path: string) => keys.get(path)
+}

package/src/runtime/query/guard.ts

@@ -83,6 +83,7 @@ export class GuardCoordinator {
 	 * on the RUN rather than on the process now hosting it.
 	 */
 	remainingBeforeFinalizeMs(): number {
+		if (this.limitConfig.timeoutMs === 0) return Number.POSITIVE_INFINITY
 		const finalizeAt = this.limitConfig.timeoutMs * this.limitConfig.budgetWarningThreshold
 		return Math.max(0, finalizeAt - (Date.now() - this.startTime))
 	}
@@ -96,6 +97,7 @@ export class GuardCoordinator {
 	 * deadline around such work instead of inventing a second clock.
 	 */
 	remainingUntilTimeoutMs(): number {
+		if (this.limitConfig.timeoutMs === 0) return Number.POSITIVE_INFINITY
 		return Math.max(0, this.limitConfig.timeoutMs - (Date.now() - this.startTime))
 	}
 

package/src/runtime/query/index.ts

@@ -112,6 +112,7 @@ import { toErrorMessage } from '../../utils/error.js'
 import { generateCheckpointId, generateRunId } from '../../utils/id.js'
 import { errorAttributes } from '../../utils/log/exception.js'
 import type { Logger } from '../../utils/logger.js'
+import { AwaitedJobs } from '../jobs/awaited-jobs.js'
 import type { BackgroundJobRegistry } from '../jobs/registry.js'
 import { AUTO_APPROVE_POLICY_NAME, createRunApprovalPolicy } from './approval-policy.js'
 import { CheckpointManager } from './checkpoint.js'
@@ -139,10 +140,10 @@ import { ResultAssembler } from './result.js'
 import {
 	type PendingResumePlan,
 	applyPendingResume,
+	interruptedToolCalls,
 	planCrashResume,
 	planPendingResume,
 	recoverCompletedCalls,
-	unansweredToolCalls,
 } from './resume-pending.js'
 import {
 	acquireSandbox,
@@ -362,6 +363,14 @@ export interface QueryParams {
 	 * agent decides the rest is worth re-reading. Set `0` to disable.
 	 */
 	maxToolOutputChars?: number
+	/**
+	 * Smaller preview for text that exceeded maxToolOutputChars, after its full
+	 * host output and integrity manifest have been saved. Unset/0 keeps the old
+	 * preview size. Does not change the spill threshold, rich blocks or ordinary
+	 * results. A failed spill/manifest or a cap too small for its recovery path
+	 * retains the ordinary output budget. Re-supply on resume.
+	 */
+	retainedToolPreviewChars?: number
 
 	/**
 	 * Cap on the RICH channel of a single tool result, in base64 characters.
@@ -411,6 +420,7 @@ export interface QueryParams {
 	 *
 	 * Bounded by {@link maxAnswerReviews}. Never called on the forced-final
 	 * turn, which exists to extract a closing summary under pressure.
+	 * Exceptions or malformed verdicts fail the run; cancellation stops waiting.
 	 */
 	reviewAnswer?: ReviewAnswer
 
@@ -422,7 +432,7 @@ export interface QueryParams {
 	 */
 	promoteMemory?: PromoteMemory
 
-	/** Rejections allowed before the run stops. Default 3. */
+	/** Corrections allowed before the run stops. Nonnegative safe integer; default 3. Consumed rejections survive checkpoints. */
 	maxAnswerReviews?: number
 
 	/** Called with each completed step, as it completes. */
@@ -931,11 +941,10 @@ async function resolveProviderContextWindow(
 		onAbort = () => resolve(interrupted)
 		resolverSignal.addEventListener('abort', onAbort, { once: true })
 	})
-	// Wire and directory config validation already limit this field to one
-	// hour. The clamp also keeps a direct QueryParams caller from triggering
-	// Node's >2^31-1 one-millisecond timer coercion and turning a huge run
-	// budget into an immediate metadata fallback.
-	const deadlineMs = Math.min(Math.max(0, timeoutMs), 2_147_483_647)
+	// Direct QueryParams callers can supply a large run deadline. The clamp
+	// avoids Node's >2^31-1 one-millisecond timer coercion during metadata lookup.
+	// Metadata discovery remains optional and bounded even without a run deadline.
+	const deadlineMs = timeoutMs === 0 ? 5_000 : Math.min(Math.max(0, timeoutMs), 2_147_483_647)
 	const timer = setTimeout(() => {
 		deadline.abort(new Error(`Provider context-window lookup exceeded ${deadlineMs}ms`))
 	}, deadlineMs)
@@ -1026,6 +1035,56 @@ function withoutOwnedResumeTurn(
 	)
 }
 
+/**
+ * The history plus the part of the owned resume turn that already RAN, for the
+ * observation ledger to be seeded from.
+ *
+ * `withoutOwnedResumeTurn` takes that turn out so generic repair cannot answer
+ * it, and the plan re-appends it much later — after the sandbox exists, after
+ * the input guardrails, immediately before the loop. Seeding from the list the
+ * model finally sees would therefore have to happen after `applyPendingResume`,
+ * and that is the wrong seam for a reason that is not about ordering: the plan
+ * does not merely re-append the turn, it EXECUTES the calls in it that never
+ * started. Those tools read the ledger this seeding builds, so a seed placed
+ * after them would refuse the very write the resume exists to carry out — no
+ * `hasRead` for a file the conversation had read three turns earlier.
+ *
+ * So the turn is folded in here instead, and only as far as it actually got.
+ * A call `recoverCompletedCalls` found an outcome for is one that ran: its
+ * receipt goes in beside it, and the walk reads it exactly as it reads any
+ * other — a completed `write` restores the body it put there, and the
+ * unknown-outcome result the recovery writes for an interrupted one withdraws
+ * the path instead. A call ABSENT from that map is absent because a complete
+ * scan proved it has no recorded start, so the file it names is untouched and
+ * the claim history established for it still stands; leaving it out is what
+ * lets it execute in a moment. Without any of this the seed never saw the
+ * turn at all, and an executed write inside it left the pre-write body standing
+ * as a claim until the next mutation's drift check happened to catch it.
+ */
+function withOwnedResumeOutcomes(
+	messages: readonly Message[],
+	assistant: AssistantMessage,
+	recovered: ReadonlyMap<string, { result: string; isError: boolean }>,
+): Message[] {
+	const ran = (assistant.toolCalls ?? []).flatMap((call) => {
+		const outcome = recovered.get(call.id)
+		return outcome ? [{ call, outcome }] : []
+	})
+	if (ran.length === 0) return [...messages]
+	return [
+		...messages,
+		{ ...assistant, toolCalls: ran.map(({ call }) => call) },
+		...ran.map(
+			({ call, outcome }): Message => ({
+				role: 'tool',
+				toolCallId: call.id,
+				content: outcome.result,
+				isError: outcome.isError,
+			}),
+		),
+	]
+}
+
 export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run> {
 	assertMaxToolCalls(params.maxToolCalls)
 	// Required types do not protect JavaScript callers. Reject missing scope
@@ -1707,10 +1766,41 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		? new AuthorizationGate(gateConfig, ctx.log)
 		: undefined
 
-	//  is null only when the run has no disk layout (tests,
-	// in-memory hosts); the budget then degrades to middle-elision.
-	const runDirForTools = ctx.runMgr.getRunDir()
-	const toolOutputDir = runDirForTools ? join(runDirForTools, TOOL_OUTPUT_DIR_NAME) : undefined
+	// The store is initialized when the async query starts, after tooling is
+	// composed. Resolve lazily at execution time: capturing getRunDir() here
+	// permanently disabled retention for fresh disk-backed invocations.
+	const toolOutputDir = () => {
+		const runDir = ctx.runMgr.getRunDir()
+		return runDir ? join(runDir, TOOL_OUTPUT_DIR_NAME) : undefined
+	}
+	// The same invocation-owned capability serves tools and optional preparation.
+	// Local cancellation cannot override the run's cancellation or settled state.
+	const captureRunEvidence = async (maxReadBytes?: number, signal?: AbortSignal) => {
+		const combined = signal
+			? AbortSignal.any([ctx.abortController.signal, signal])
+			: ctx.abortController.signal
+		combined.throwIfAborted()
+		const source = await eventTranslator.captureRunEvidence(maxReadBytes, combined)
+		combined.throwIfAborted()
+		return source
+	}
+
+	// Whose jobs this run speaks for: its own by default, the session's when
+	// the host said so. Resolved before the tools are built, because the
+	// wait-intent recorder below is bound into them.
+	const jobOwner = params.backgroundJobOwner ?? ctx.runId
+	// What the model reads when a job ends. Built up here, ahead of the
+	// subscription that fills it below, because the wait-intent recorder needs
+	// to ask whether its text has been read yet.
+	const jobNotices = params.backgroundJobs ? new SteeringBinding() : undefined
+	// Jobs the model told `wait_for_job` it is waiting on, which is the only
+	// thing that can hold this run open for a job. Built only where there is a
+	// registry, so a host with no background mode carries no recorder and the
+	// bound ref has no `markAwaited` to offer.
+	const awaitedJobs = params.backgroundJobs
+		? new AwaitedJobs(params.backgroundJobs, jobOwner, () => jobNotices?.pending ?? false)
+		: undefined
+	awaitedJobs?.attach()
 
 	const toolExecutor = ToolingBootstrap.init(
 		{
@@ -1728,6 +1818,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			pluginManager: params.pluginManager,
 			...(params.backgroundJobs ? { backgroundJobs: params.backgroundJobs } : {}),
 			...(params.backgroundJobOwner ? { backgroundJobOwner: params.backgroundJobOwner } : {}),
+			...(awaitedJobs ? { onJobAwaited: (id: string) => awaitedJobs.expect(id) } : {}),
 			// The `skill` tool's registry. Threaded from the run rather than
 			// held by the tool, because a tool that reached for a module-level
 			// registry would answer about whatever the last run configured.
@@ -1750,13 +1841,17 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			...(params.maxToolOutputChars !== undefined
 				? { maxToolOutputChars: params.maxToolOutputChars }
 				: {}),
+			...(params.retainedToolPreviewChars !== undefined
+				? { retainedToolPreviewChars: params.retainedToolPreviewChars }
+				: {}),
 			...(params.maxToolContentBytes !== undefined
 				? { maxToolContentBytes: params.maxToolContentBytes }
 				: {}),
 			// Overflow lands beside the run's other artifacts, so it is
 			// cleaned up with the run and reachable by the model's own
 			// `read`/`grep` without a new affordance.
-			...(toolOutputDir ? { toolOutputDir } : {}),
+			toolOutputDir,
+			captureRunEvidence,
 			...(params.repairToolCall ? { repairToolCall: params.repairToolCall } : {}),
 			...(verificationGate ? { authorizationGate: verificationGate } : {}),
 			recordAudit: (input) => ctx.runMgr.recordAudit(input),
@@ -1783,8 +1878,6 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	// result, and the host as an event — without either polling. Subscribed
 	// for the owner the run's jobs are bound to, so a session-owned job that
 	// ends during this run is reported here too.
-	const jobOwner = params.backgroundJobOwner ?? ctx.runId
-	const jobNotices = params.backgroundJobs ? new SteeringBinding() : undefined
 	const unsubscribeJobExits = params.backgroundJobs?.onExit((job) => {
 		if (job.owner !== jobOwner) return
 		const outcome =
@@ -1930,6 +2023,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 					: undefined
 			return {
 				messages: ctx.runMgr.messages,
+				turn: iterationOrchestrator.getAdvisoryTurnContext(),
 				...(summary !== undefined ? { workingStateSummary: summary } : {}),
 				...(advisoryConfig.includeToolCatalog
 					? { toolCatalog: params.tools.toLLMTools(effectiveAllowedTools) }
@@ -1950,6 +2044,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	}
 
 	const iterationOrchestrator = new IterationOrchestrator({
+		captureRunEvidence,
 		provider: resilientProvider,
 		providerCapabilities: capabilities,
 		strictCapabilities: params.strictCapabilities === true,
@@ -1982,6 +2077,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		promptContributions,
 		...(params.steering ? { steering: params.steering } : {}),
 		...(jobNotices ? { jobNotices } : {}),
+		...(awaitedJobs ? { awaitedJobs } : {}),
 		checkpointMgr,
 		planManager: ctx.planManager,
 		taskGateway: taskScheduler,
@@ -2294,23 +2390,19 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 						? planPendingResume(projectedCheckpoint, params.pendingDecision, ctx.log)
 						: null
 
-				// Results of tools that finished before the process died. The
-				// executor already emits one `tool_completed` per tool inline
-				// and the transcript already persists it, so the record was
-				// durable all along — it was simply never read back, and the
-				// resumed run re-ran calls that had already charged a card or
-				// sent an email.
-				const unanswered = unansweredToolCalls(projectedCheckpoint.messages)
+				// Recover completed observations and explicitly unknown outcomes.
+				// A recorded start is not proof that its external effect failed.
+				const unanswered = interruptedToolCalls(projectedCheckpoint.messages)
 				recoveredResults =
 					unanswered.length > 0
-						? await recoverCompletedCalls(ctx.runMgr, unanswered, ctx.log)
+						? await recoverCompletedCalls(ctx.runMgr, unanswered, ctx.log, {
+								answers: pendingResume?.answers,
+								signal: ctx.abortController.signal,
+							})
 						: new Map()
 
-				// A batch caught MID-execution is a resume, not a fresh
-				// decision: stripping the turn and letting the model re-decide
-				// would re-run everything that already ran. Only taken when
-				// the transcript proves execution had begun — a tool-review
-				// park has no completions and keeps the cheap repair below.
+				// Preserve both known and unknown outcomes before continuing calls
+				// whose absence of a start was established by a complete scan.
 				if (!pendingResume && recoveredResults.size > 0) {
 					pendingResume = planCrashResume(projectedCheckpoint, recoveredResults, ctx.log)
 				}
@@ -2344,6 +2436,37 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 					})
 				}
 
+				// The ledger is process state and a resumed run starts with an empty
+				// one, so until something reads a file again this run knows nothing
+				// about files the conversation already wrote in full — and re-reads
+				// them. Rebuilt from the REPAIRED history, which is what the model
+				// is about to be shown, rather than from the checkpoint's own
+				// messages — plus whatever of the owned resume turn actually ran,
+				// which the repaired list does not carry; see
+				// `withOwnedResumeOutcomes`. Reads no file's content: every
+				// fingerprint recovered here is still checked against the real one
+				// at mutation time.
+				try {
+					await toolExecutor.seedFileObservations(
+						pendingResume
+							? withOwnedResumeOutcomes(restoredMessages, pendingResume.assistant, recoveredResults)
+							: restoredMessages,
+						params.sandboxProvider !== undefined,
+					)
+				} catch (err: unknown) {
+					// A ledger that could not be rebuilt is the empty one every resume
+					// used to get, so the run continues without its witnesses and the
+					// model reads what it needs. Failing the resume over it would trade
+					// a conversation that works for one that does not, to protect an
+					// optimisation. Said out loud all the same, because a seeding that
+					// failed and one that found nothing are otherwise the same silence.
+					ctx.log.debug('Could not rebuild the file observation ledger on resume', {
+						[NAMZU.RUN_ID]: ctx.runMgr.id,
+						'namzu.checkpoint.id': checkpoint.id,
+						'exception.message': err instanceof Error ? err.message : String(err),
+					})
+				}
+
 				for (const msg of restoredMessages) {
 					if (msg.role === 'system') {
 						// Re-push the FRESH static/dynamic floor (done above) but PRESERVE
@@ -2854,6 +2977,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			// Awaited, and its failure swallowed. A job that would not die is
 			// worth a log line, and is not worth retracting a run's answer.
 			unsubscribeJobExits?.()
+			// The wait-intent recorder listens on the same shared registry and
+			// leaks the same way if it is left attached.
+			awaitedJobs?.close()
 			// Only jobs bound to this run. Jobs a host bound to its session are
 			// the host's to stop, when the session ends.
 			if (params.backgroundJobs && (params.backgroundJobOwner ?? ctx.runId) === ctx.runId) {