@namzu/sdk 27.1.0 → 29.0.0

package/src/runtime/query/repeat-call.ts

@@ -0,0 +1,130 @@
+import type { Message } from '../../types/message/index.js'
+import { stableStringify } from './tool-grants.js'
+
+/**
+ * Notices a model issuing the same tool call over and over, and says so.
+ *
+ * Nothing in the kernel observed cross-call repetition. The guardrails
+ * screen calls in isolation — input at run start, output at run end, one
+ * result at a time — so a model re-running a failing command or
+ * re-applying a diff that does not apply got no correction from anything.
+ * The only lever was an iteration checkpoint, which fires on a COUNT
+ * regardless of whether anything is repeating and needs a human at the
+ * other end.
+ *
+ * It advises; it never denies. A repeat is not necessarily wrong — polling
+ * for a build to finish is the same call by design — and a tracker that
+ * refused would break that case to fix a different one. What the model
+ * lacks is not permission but the observation, which it cannot make about
+ * itself: each turn it sees a history, not a count.
+ */
+
+/** Same key `ToolGrantSet` uses, so "the same call" means one thing here. */
+function keyFor(name: string, input: unknown): string {
+	return `${name}:${stableStringify(input)}`
+}
+
+export interface RepeatCallThresholds {
+	/** Repeats at which a first, mild notice is attached. */
+	readonly notifyAfter: number
+	/** Repeats at which the wording escalates. */
+	readonly escalateAfter: number
+}
+
+export const DEFAULT_REPEAT_THRESHOLDS: RepeatCallThresholds = {
+	notifyAfter: 3,
+	escalateAfter: 5,
+}
+
+export interface RepeatCallNotice {
+	readonly toolName: string
+	readonly count: number
+	readonly level: 'notice' | 'escalated'
+	readonly text: string
+}
+
+/**
+ * Run-scoped, like `ToolGrantSet` and for the same reason: a count carried
+ * into a later run is a statement about work nobody repeated.
+ */
+export class RepeatCallTracker {
+	private readonly counts = new Map<string, number>()
+	/** Which keys have already been reported at which level, so one repeat
+	 *  does not produce the same sentence on every subsequent turn. */
+	private readonly announced = new Map<string, 'notice' | 'escalated'>()
+
+	constructor(private readonly thresholds: RepeatCallThresholds = DEFAULT_REPEAT_THRESHOLDS) {}
+
+	/**
+	 * Records one call and returns a notice when this is the repeat that
+	 * crosses a threshold, `undefined` otherwise.
+	 */
+	record(toolName: string, input: unknown): RepeatCallNotice | undefined {
+		const key = keyFor(toolName, input)
+		const count = (this.counts.get(key) ?? 0) + 1
+		this.counts.set(key, count)
+
+		const already = this.announced.get(key)
+		if (count >= this.thresholds.escalateAfter && already !== 'escalated') {
+			this.announced.set(key, 'escalated')
+			return {
+				toolName,
+				count,
+				level: 'escalated',
+				text: `You have now called \`${toolName}\` with identical arguments ${count} times in this run. Repeating it again will produce the same result. Change the arguments, use a different tool, or tell the user what is blocking you and stop.`,
+			}
+		}
+		if (count >= this.thresholds.notifyAfter && already === undefined) {
+			this.announced.set(key, 'notice')
+			return {
+				toolName,
+				count,
+				level: 'notice',
+				text: `Note: this is call ${count} of \`${toolName}\` with identical arguments in this run. If the previous results were not what you needed, changing the arguments is more likely to help than repeating them.`,
+			}
+		}
+		return undefined
+	}
+
+	/** Repeats seen for one call, for a host that wants to render it. */
+	countOf(toolName: string, input: unknown): number {
+		return this.counts.get(keyFor(toolName, input)) ?? 0
+	}
+}
+
+/**
+ * Rides the notice out on the last `tool_result` of the batch.
+ *
+ * The same and only legal slot steering uses: a `tool_use` block must be
+ * answered by a `tool_result` with the same id, so a user message wedged
+ * between them is rejected by the provider outright.
+ */
+export function attachRepeatNotice(
+	messages: readonly Message[],
+	notices: readonly RepeatCallNotice[],
+): readonly Message[] {
+	if (notices.length === 0) return messages
+
+	let lastToolIndex = -1
+	for (let index = messages.length - 1; index >= 0; index--) {
+		if (messages[index]?.role === 'tool') {
+			lastToolIndex = index
+			break
+		}
+	}
+	if (lastToolIndex === -1) return messages
+
+	const target = messages[lastToolIndex] as Message
+	// Text only, for the reason `attachSteering` gives: a result answered
+	// with structured content has a shape the model reads positionally, and
+	// appending a string to it is either dropped or corrupts the block. The
+	// notice is advisory, so dropping it costs nothing a refusal would.
+	if (typeof target.content !== 'string') return messages
+
+	const next = [...messages]
+	next[lastToolIndex] = {
+		...target,
+		content: `${target.content}\n\n${notices.map((n) => n.text).join('\n')}`,
+	}
+	return next
+}

package/src/runtime/query/replay/mutate.ts

@@ -67,6 +67,12 @@ function applyOne(messages: Message[], mutation: Mutation): Message[] {
 			if (!match) {
 				throw new MutationNotApplicableError(
 					`No pending tool call ${mutation.toolCallId} at fork point`,
+					// `ToolCall.id` is a bare `string` — a provider chooses its own
+					// shape, which is what `ToolUseId` exists to say. This assertion
+					// satisfies `MutationNotApplicableError`'s parameter and is only
+					// ever read back as text in that message; it never becomes a
+					// key. Left as a cast because the honest fix is that parameter
+					// type, not this line.
 					pending.map((tc) => tc.id as ToolCallId),
 				)
 			}

package/src/runtime/query/result.ts

@@ -7,6 +7,7 @@ import { GENAI, NAMZU } from '../../telemetry/attributes.js'
 import { explainError } from '../../types/errors/catalog.js'
 import { toPlatformError } from '../../types/errors/index.js'
 import type { CheckpointId } from '../../types/hitl/index.js'
+import { cancelCauseOf } from '../../types/run/cancel-cause.js'
 import type { Run, RunEvent } from '../../types/run/index.js'
 import { toErrorMessage } from '../../utils/error.js'
 import type { Logger } from '../../utils/logger.js'
@@ -27,6 +28,13 @@ export interface ResultAssemblerConfig {
 	 * construction would pin the first one forever.
 	 */
 	resumeCheckpointId?: () => CheckpointId | undefined
+	/**
+	 * The run's abort signal, read only to recover WHY a cancellation
+	 * happened. Optional so a caller that never cancels needs no extra
+	 * wiring, and absent simply means the cause is unknown — which is the
+	 * same answer an unattributed cancellation gives.
+	 */
+	signal?: AbortSignal
 }
 
 export class ResultAssembler {
@@ -38,6 +46,7 @@ export class ResultAssembler {
 
 	async *completeRun(rootSpan: Span): AsyncGenerator<RunEvent> {
 		const { runMgr, planManager, activityStore, log, emitEvent, drainPending } = this.config
+		const cancelCause = cancelCauseOf(this.config.signal?.reason)
 
 		if (runMgr.status === 'running') {
 			runMgr.markCompleted(runMgr.stopReason)
@@ -60,6 +69,20 @@ export class ResultAssembler {
 			planManager.completePlan()
 		}
 
+		// The run's own terminal verdict — first-class in the audit trail per
+		// LOG-14, scoped deliberately: only the one outcome `AuditOutcome` can
+		// name for a settled run today ('completed' → 'success'). This also
+		// covers a guardrail-blocked run, which reaches `status: 'completed'`
+		// via the `markCompleted` call above — "completed is not succeeded"
+		// (see `types/run/events.ts`'s `run_completed` doc), and the granular
+		// 'refused' entry for the block itself was already recorded at the
+		// point it happened. 'cancelled'/'paused' are left unaudited here
+		// rather than forced into a mapping nothing asked for — a later minor
+		// can widen `AuditOutcome` additively when that scope is taken on.
+		if (runMgr.status === 'completed') {
+			await runMgr.recordAudit({ what: { action: 'run_completed' }, outcome: 'success' })
+		}
+
 		await emitEvent({
 			type: 'run_completed',
 			runId: runMgr.id,
@@ -69,6 +92,11 @@ export class ResultAssembler {
 			// consumer can tell "answered" from "ran out of budget" without
 			// holding the `Run`.
 			...(runMgr.getRun().stopReason ? { stopReason: runMgr.getRun().stopReason } : {}),
+			// Only on a cancellation, and only when one was recorded. Absent is
+			// a real answer: a cancellation nobody attributed is not a user
+			// cancellation, and defaulting would put a confident wrong value
+			// where an honest gap belongs.
+			...(cancelCause !== undefined ? { cancelCause } : {}),
 		})
 		yield* drainPending()
 
@@ -81,10 +109,10 @@ export class ResultAssembler {
 		rootSpan.setStatus({ code: SpanStatusCode.OK })
 
 		log.info('Query completed', {
-			runId: runMgr.id,
-			iterations: runMgr.currentIteration,
-			stopReason: runMgr.stopReason,
-			activityStats: activityStore.enabled ? activityStore.stats() : undefined,
+			[NAMZU.RUN_ID]: runMgr.id,
+			'namzu.runtime.iterations': runMgr.currentIteration,
+			'namzu.runtime.stop_reason': runMgr.stopReason,
+			'namzu.runtime.activity_stats': activityStore.enabled ? activityStore.stats() : undefined,
 		})
 	}
 
@@ -130,10 +158,10 @@ export class ResultAssembler {
 			rootSpan.setStatus({ code: SpanStatusCode.OK })
 
 			log.warn('Run paused on a recoverable failure — resume from the checkpoint', {
-				runId: runMgr.id,
-				checkpointId: resumeFrom,
-				code: failure.code,
-				error: errorMessage,
+				[NAMZU.RUN_ID]: runMgr.id,
+				'namzu.checkpoint.id': resumeFrom,
+				'namzu.runtime.code': failure.code,
+				'exception.message': errorMessage,
 			})
 			return
 		}
@@ -166,6 +194,15 @@ export class ResultAssembler {
 		// remediation is editorial and belongs in a list a human appends to.
 		const explanation = explainError(err) ?? undefined
 
+		// Same terminal-verdict recording as the success path in completeRun —
+		// see LOG-14, design §5. Placed AFTER the early `resumeFrom !== undefined`
+		// return above, so a paused/resumable run is never audited as 'failure'.
+		await runMgr.recordAudit({
+			what: { action: 'run_failed' },
+			outcome: 'failure',
+			reason: errorMessage,
+		})
+
 		await emitEvent({
 			type: 'run_failed',
 			runId: runMgr.id,
@@ -184,8 +221,8 @@ export class ResultAssembler {
 		rootSpan.recordException(err instanceof Error ? err : new Error(errorMessage))
 
 		log.error('Query failed', {
-			runId: runMgr.id,
-			error: errorMessage,
+			[NAMZU.RUN_ID]: runMgr.id,
+			'exception.message': errorMessage,
 		})
 	}
 

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

@@ -79,9 +79,9 @@ export function planPendingResume(
 
 	if (pending.request.type !== 'tool_review') {
 		log.info('Pending decision supplied for a park that leaves no tool calls to apply it to', {
-			checkpointId: checkpoint.id,
-			pendingType: pending.request.type,
-			decision: decision.action,
+			'namzu.checkpoint.id': checkpoint.id,
+			'namzu.runtime.pending_type': pending.request.type,
+			'namzu.runtime.decision': decision.action,
 		})
 		return null
 	}
@@ -89,7 +89,7 @@ export function planPendingResume(
 	const assistant = lastAssistantWithUnansweredCalls(checkpoint.messages)
 	if (!assistant?.toolCalls || assistant.toolCalls.length === 0) {
 		log.warn('Checkpoint records a tool_review park but has no unanswered tool calls', {
-			checkpointId: checkpoint.id,
+			'namzu.checkpoint.id': checkpoint.id,
 		})
 		return null
 	}
@@ -102,9 +102,9 @@ export function planPendingResume(
 	const mismatched = actualIds.filter((id) => !recordedIds.has(id))
 	if (mismatched.length > 0 || recordedIds.size !== actualIds.length) {
 		log.error('Tool calls in the checkpoint do not match the ones the decision was made about', {
-			checkpointId: checkpoint.id,
-			recorded: [...recordedIds],
-			actual: actualIds,
+			'namzu.checkpoint.id': checkpoint.id,
+			'namzu.runtime.recorded': [...recordedIds],
+			'namzu.runtime.actual': actualIds,
 		})
 		return null
 	}
@@ -145,7 +145,7 @@ function planQuestionResume(
 	const assistant = lastAssistantWithUnansweredCalls(checkpoint.messages)
 	if (!assistant?.toolCalls || assistant.toolCalls.length === 0) {
 		log.warn('Checkpoint records a question park but has no unanswered tool calls', {
-			checkpointId: checkpoint.id,
+			'namzu.checkpoint.id': checkpoint.id,
 		})
 		return null
 	}
@@ -165,8 +165,8 @@ function planQuestionResume(
 	// under the bare tool-use id.
 	if (!assistant.toolCalls.some((tc) => isPauseForCall(questionId, tc.id))) {
 		log.error('The parked question does not belong to any unanswered call in this turn', {
-			checkpointId: checkpoint.id,
-			questionId,
+			'namzu.checkpoint.id': checkpoint.id,
+			'namzu.runtime.question_id': questionId,
 		})
 		return null
 	}
@@ -215,10 +215,12 @@ export function planCrashResume(
 	if (done.length === 0) return null
 
 	log.warn('Checkpoint holds a tool batch that was part-way through executing', {
-		checkpointId: checkpoint.id,
-		completed: done.length,
-		total: calls.length,
-		remaining: calls.filter((tc) => !completed.has(tc.id)).map((tc) => tc.function.name),
+		'namzu.checkpoint.id': checkpoint.id,
+		'namzu.runtime.completed': done.length,
+		'namzu.runtime.total': calls.length,
+		'namzu.runtime.remaining': calls
+			.filter((tc) => !completed.has(tc.id))
+			.map((tc) => tc.function.name),
 	})
 
 	return {
@@ -276,15 +278,15 @@ export async function recoverCompletedCalls(
 		}
 	} catch (error) {
 		log.warn('Could not read the transcript to recover completed tool calls', {
-			error: error instanceof Error ? error.message : String(error),
+			'exception.message': error instanceof Error ? error.message : String(error),
 		})
 		return new Map()
 	}
 
 	if (recovered.size > 0) {
 		log.info('Recovered tool results from the transcript instead of re-executing', {
-			recovered: recovered.size,
-			ofCalls: toolCalls.length,
+			'namzu.runtime.recovered': recovered.size,
+			'namzu.runtime.of_calls': toolCalls.length,
 		})
 	}
 	return recovered

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

@@ -1,5 +1,5 @@
 import type { PendingDecision } from '../../types/hitl/index.js'
-import type { CheckpointStore, ClaimFence } from '../../types/run/checkpoint-store.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'
@@ -62,7 +62,7 @@ export interface ResumeRunParams
 	 * is what a queue reader does with a parked run — so this is the call that
 	 * most needs to carry one.
 	 */
-	readonly claimFence?: ClaimFence
+	readonly claimFence?: FencingToken
 	/**
 	 * Resume a specific checkpoint instead of the one the store would pick.
 	 * Absent means the parked checkpoint if there is one, else the newest.

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

@@ -2,14 +2,14 @@ import type { RunPersistence } from '../../manager/run/persistence.js'
 import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
 import type { CheckpointRunScope, CheckpointStore } from '../../types/run/checkpoint-store.js'
 import { RUN_STATE_VERSION, type RunState } from '../../types/run/state.js'
-import type { ThreadId } from '../../types/session/ids.js'
+import type { TopicId } from '../../types/session/ids.js'
 import { findPendingCheckpoint } from './checkpoint.js'
 
 /**
  * A {@link CheckpointRunScope} plus the one attribution field checkpoints
  * do not record.
  *
- * `threadId` is denormalized onto a run at `query()` time and never written
+ * `topicId` is denormalized onto a run at `query()` time and never written
  * into a checkpoint, so a snapshot rebuilt from the store alone cannot
  * derive it. Requiring the caller to supply it is better than inventing one
  * or widening `RunState` to make it optional: the field is required by
@@ -17,7 +17,7 @@ import { findPendingCheckpoint } from './checkpoint.js'
  * and less clearly.
  */
 export interface RunStateScope extends CheckpointRunScope {
-	threadId: ThreadId
+	topicId: TopicId
 }
 
 /**
@@ -42,7 +42,7 @@ export function captureRunState(
 		version: RUN_STATE_VERSION,
 		runId: runMgr.id,
 		sessionId: scope.sessionId,
-		threadId: scope.threadId,
+		topicId: scope.topicId,
 		projectId: scope.projectId,
 		tenantId: scope.tenantId,
 		...(scope.parentRunId ? { parentRunId: scope.parentRunId } : {}),
@@ -98,7 +98,7 @@ export async function loadRunState(
 		version: RUN_STATE_VERSION,
 		runId: checkpoint.runId,
 		sessionId: scope.sessionId,
-		threadId: scope.threadId,
+		topicId: scope.topicId,
 		projectId: scope.projectId,
 		tenantId: scope.tenantId,
 		...(scope.parentRunId ? { parentRunId: scope.parentRunId } : {}),

package/src/runtime/query/tool-grants.ts

@@ -71,7 +71,7 @@ export class ToolGrantSet {
  * Arrays keep their order, which is meaningful; object key order is not,
  * and letting it into the key would make the same call hash two ways.
  */
-function stableStringify(value: unknown): string {
+export function stableStringify(value: unknown): string {
 	if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'
 	if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`
 

package/src/runtime/query/tool-output-budget.ts

@@ -169,15 +169,48 @@ function spill(
 	onError?: (message: string) => void,
 ): string | undefined {
 	try {
-		mkdirSync(dir, { recursive: true })
+		// `0o700` on the directory and `0o600` on the file: a spilled output is
+		// routinely the largest and most sensitive thing a run produces — whole
+		// files, whole command outputs — and the default `0o755`/`0o644` made
+		// every one of them world-readable on a shared host.
+		//
+		// The mode is applied to directories this call CREATES. A spill
+		// directory the host made itself keeps whatever mode the host chose,
+		// which is the host's decision to make and not this function's to
+		// override.
+		mkdirSync(dir, { recursive: true, mode: 0o700 })
 		// The tool_use id is already unique per call and safe as a filename.
 		const path = join(dir, `${toolUseId}.txt`)
-		writeFileSync(path, content, 'utf-8')
+		// `wx`, not the default `w`. `w` creates-or-truncates and FOLLOWS a
+		// symlink, at a path anything that can write to this directory could
+		// predict and pre-plant — so the kernel would overwrite the symlink's
+		// target with content the model chose. `wx` fails with EEXIST instead,
+		// and never follows.
+		//
+		// The property being bought is exclusivity of the open, not
+		// unpredictability of the name: `toolUseId` is already unique per call,
+		// so randomising the filename would add nothing this does not already
+		// have. Do not "improve" it back to a random name and a plain `w` —
+		// that trades a guarantee for a guess.
+		writeFileSync(path, content, { encoding: 'utf-8', flag: 'wx', mode: 0o600 })
 		return path
 	} catch (err) {
 		// A spill failure must never fail the tool call — the model still
 		// gets the preview, just without a path to recover the rest.
-		onError?.(err instanceof Error ? err.message : String(err))
+		//
+		// EEXIST is reported as its own sentence rather than folded into the
+		// generic message, because the two causes lead to opposite next moves:
+		// a stale file from a reused output directory is housekeeping, while
+		// something arriving at a path only this run should know is the case
+		// the exclusive open exists to refuse, and an operator has to be able
+		// to tell them apart from the log line alone.
+		const code = (err as NodeJS.ErrnoException | undefined)?.code
+		const detail = err instanceof Error ? err.message : String(err)
+		onError?.(
+			code === 'EEXIST'
+				? `Refused to overwrite an existing file at the spill path; the output was not retained. ${detail}`
+				: detail,
+		)
 		return undefined
 	}
 }

package/src/runtime/query/tool-pause.ts

@@ -1,6 +1,7 @@
 import type { HITLResumeDecision, ResumeHandler, UserQuestionData } from '../../types/hitl/index.js'
 import type { RunId } from '../../types/ids/index.js'
 import type { RequestToolPause, ToolPauseRequest } from '../../types/tool/index.js'
+import { asCheckpointId } from '../../utils/id.js'
 import type { PendingAnswers, QuestionParkRecorder } from './question-park.js'
 
 /**
@@ -120,7 +121,7 @@ export function createToolPause(deps: ToolPauseDeps): RequestToolPause {
 			(await deps.parkHandler({
 				type: 'user_question',
 				runId: deps.runId,
-				checkpointId: parkedAt ?? `cp_pause_${id}`,
+				checkpointId: parkedAt ?? asCheckpointId(`cp_pause_${id}`),
 				question,
 			}))
 

package/src/runtime/query/tooling.ts

@@ -4,10 +4,15 @@ import type { RunId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
 import type { PermissionMode } from '../../types/permission/index.js'
 import type { RunEvent } from '../../types/run/index.js'
-import type { RequestToolPause, ToolRegistryContract } from '../../types/tool/index.js'
+import type {
+	RequestToolPause,
+	SkillRegistryRef,
+	ToolRegistryContract,
+} from '../../types/tool/index.js'
 import type { RepairToolCall } from '../../types/tool/repair.js'
 import type { BackoffPolicy } from '../../utils/backoff.js'
 import type { Logger } from '../../utils/logger.js'
+import type { BackgroundJobRegistry } from '../jobs/registry.js'
 import { ToolExecutor } from './executor.js'
 
 export type EmitEvent = (event: RunEvent) => Promise<void>
@@ -16,13 +21,20 @@ export interface ToolingBootstrapConfig {
 	tools: ToolRegistryContract
 	runId: RunId
 	workingDirectory: string
-	permissionMode: PermissionMode
+	/** A resolver, so an approval inside a run can change it. See the executor. */
+	permissionMode: PermissionMode | (() => PermissionMode)
 	env: Record<string, string>
 	abortSignal: AbortSignal
 	allowedTools?: readonly string[]
 	invocationState?: InvocationState
 	pluginManager?: PluginLifecycleManager
 	toolTimeoutMs?: number
+	/** Host-owned and shared; the executor binds it to this run. */
+	backgroundJobs?: BackgroundJobRegistry
+	/** Where the `skill` tool reads from. */
+	skills?: SkillRegistryRef
+	/** How this run reaches the web. */
+	web?: import('../../types/tool/index.js').ToolContext['web']
 	toolRetryBackoff?: Partial<BackoffPolicy>
 	maxToolConcurrency?: number
 	maxToolOutputChars?: number
@@ -51,6 +63,9 @@ export class ToolingBootstrap {
 				allowedTools: config.allowedTools,
 				invocationState: config.invocationState,
 				pluginManager: config.pluginManager,
+				...(config.backgroundJobs ? { backgroundJobs: config.backgroundJobs } : {}),
+				...(config.skills ? { skills: config.skills } : {}),
+				...(config.web ? { web: config.web } : {}),
 				...(config.toolTimeoutMs !== undefined ? { toolTimeoutMs: config.toolTimeoutMs } : {}),
 				...(config.toolRetryBackoff !== undefined
 					? { toolRetryBackoff: config.toolRetryBackoff }