@namzu/sdk 39.0.0 → 40.0.0

package/src/runtime/query/plugin-hooks.ts

@@ -59,3 +59,23 @@ export function applyLifecycleHookResults(
 	}
 	return annotations
 }
+
+/**
+ * What a `pre_tool_use` hook's SKIP goes back to the model as.
+ *
+ * A function rather than a template at the one call site, because the text is
+ * a SIGNAL as well as prose. A skipped call gets a non-error receipt — the
+ * hook refused it, nothing failed — so the transcript's only record that the
+ * tool never ran is this sentence. `file-evidence-replay.ts` reads it back to
+ * keep a skipped `write` from being replayed as a body the file now holds,
+ * and it can only do that while one function owns both the writing and the
+ * recognising.
+ */
+export function skippedToolResultText(toolName: string, reason: string): string {
+	return `Tool ${toolName} skipped by plugin: ${reason}`
+}
+
+/** Whether `content` is the receipt {@link skippedToolResultText} writes for `toolName`. */
+export function isSkippedToolResult(toolName: string, content: string): boolean {
+	return content.startsWith(skippedToolResultText(toolName, ''))
+}

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

@@ -1,3 +1,4 @@
+import { createRuntimeContextMessage } from '../../types/message/index.js'
 import type { Message } from '../../types/message/index.js'
 import { stableStringify } from './tool-grants.js'
 
@@ -128,11 +129,24 @@ export class RepeatCallTracker {
 }
 
 /**
- * Rides the notice out on the last `tool_result` of the batch.
+ * Rides the notice out on the last `tool_result` of the batch, same 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.
  *
- * 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.
+ * That slot only exists when the trailing result's content is plain text. A
+ * result answered with structured content (an image, a document, an MCP
+ * block) has a shape the model reads positionally, and appending a string to
+ * it is either dropped or corrupts the block — this used to mean the notice
+ * was simply dropped, on the theory that an advisory costs nothing to lose.
+ * It costs more than a refusal would: `RepeatCallTracker.record` already
+ * marked the threshold as announced the moment it fired, so a notice lost
+ * here never comes back, unlike steering, which can requeue and wait for a
+ * later plain-text result. The fallback instead rides out as its own
+ * `runtime-context` message placed AFTER the complete tool-result batch —
+ * never between a `tool_use` and its `tool_result`, so provider-required
+ * adjacency still holds — carrying that provenance so it is never mistaken
+ * for operator input (see `isOperatorUserMessage` in `steering.ts`).
  */
 export function attachRepeatNotice(
 	messages: readonly Message[],
@@ -140,6 +154,8 @@ export function attachRepeatNotice(
 ): readonly Message[] {
 	if (notices.length === 0) return messages
 
+	const noticeText = notices.map((n) => n.text).join('\n')
+
 	let lastToolIndex = -1
 	for (let index = messages.length - 1; index >= 0; index--) {
 		if (messages[index]?.role === 'tool') {
@@ -147,19 +163,13 @@ export function attachRepeatNotice(
 			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')}`,
+	const target = lastToolIndex === -1 ? undefined : (messages[lastToolIndex] as Message)
+
+	if (target && typeof target.content === 'string') {
+		const next = [...messages]
+		next[lastToolIndex] = { ...target, content: `${target.content}\n\n${noticeText}` }
+		return next
 	}
-	return next
+
+	return [...messages, createRuntimeContextMessage(noticeText, 'repeat-call')]
 }

package/src/runtime/query/steering.ts

@@ -100,6 +100,16 @@ export function attachNotice(
 	messages: readonly Message[],
 	channel: SteeringChannel | undefined,
 	format: (text: string) => string,
+	/**
+	 * Told only when the text actually landed on a result the model will read.
+	 *
+	 * Not on the two paths above it: a batch with no tool result leaves the
+	 * notice queued, and a result whose content is not a string puts it back.
+	 * Draining is therefore not delivery, which matters to the caller that
+	 * keeps its own record of what the text accounts for — `AwaitedJobs`
+	 * drops an exit's entry here, and a premature drop would strand the exit.
+	 */
+	onDelivered?: () => void,
 ): readonly Message[] {
 	if (!channel?.pending) return messages
 	let lastToolIndex = -1
@@ -119,6 +129,7 @@ export function attachNotice(
 	}
 	const next = [...messages]
 	next[lastToolIndex] = { ...target, content: target.content + format(text) }
+	onDelivered?.()
 	return next
 }
 

package/src/runtime/query/tooling.ts

@@ -38,6 +38,8 @@ export interface ToolingBootstrapConfig {
 	backgroundJobs?: BackgroundJobRegistry
 	/** See `QueryParams.backgroundJobOwner`. */
 	backgroundJobOwner?: string
+	/** Where `wait_for_job` records wait-intent; see the executor's own field. */
+	onJobAwaited?: (id: string) => void
 	/** Where the `skill` tool reads from. */
 	skills?: SkillRegistryRef
 	/** How this run reaches the web. */
@@ -85,6 +87,7 @@ export class ToolingBootstrap {
 				pluginManager: config.pluginManager,
 				...(config.backgroundJobs ? { backgroundJobs: config.backgroundJobs } : {}),
 				...(config.backgroundJobOwner ? { backgroundJobOwner: config.backgroundJobOwner } : {}),
+				...(config.onJobAwaited ? { onJobAwaited: config.onJobAwaited } : {}),
 				...(config.skills ? { skills: config.skills } : {}),
 				...(config.web ? { web: config.web } : {}),
 				...(config.toolTimeoutMs !== undefined ? { toolTimeoutMs: config.toolTimeoutMs } : {}),

package/src/scheduler/completion-inbox.ts

@@ -26,6 +26,23 @@ import { type Logger, resolveLogger } from '../utils/logger.js'
  */
 const UNOWNED_BUFFER_LIMIT = 32
 
+/**
+ * How many owned tasks {@link CompletionInbox.describeOwnedWork} can name at
+ * once.
+ *
+ * Unrelated to {@link UNOWNED_BUFFER_LIMIT} — that one bounds a memory leak;
+ * this one bounds a request payload. `describeOwnedWork`'s output is admitted
+ * into the request through `appendWorkContext`'s 8,000-character / ~2,000-token
+ * gate (`runtime/query/iteration/index.ts`), and 16 tasks' worth of scheduler
+ * state fits that with room to spare, including the overflow note below.
+ *
+ * Running tasks fill these slots first — see {@link CompletionInbox.runningOwned}
+ * — so a task still going is never bumped out by launch count alone the way a
+ * single FIFO over every owned task used to bump it. Only once every running
+ * task has a slot do the most recently SETTLED tasks take what is left.
+ */
+const OWNED_WORK_DISPLAY_LIMIT = 16
+
 /**
  * Completions that finished with nobody left to hear them.
  *
@@ -77,7 +94,30 @@ export class CompletionInbox {
 	 * takes one, and a host that owns a gateway naturally reuses it.
 	 */
 	private readonly ours = new Set<TaskId>()
-	private readonly recentOwned: TaskId[] = []
+	/**
+	 * Owned tasks not yet observed to have settled, in launch order.
+	 *
+	 * A `Set`'s iteration order is insertion order, so the most recently
+	 * launched entry is always last — {@link describeOwnedWork} reads that
+	 * order back to front. An id leaves this set the moment its completion is
+	 * observed, by whichever of the three paths sees it first: the gateway's
+	 * broadcast, an announcement recovered from {@link unowned}, or a launch
+	 * that finds the task already terminal. It is never evicted for any other
+	 * reason, so a long-running task stays in here — and therefore visible —
+	 * for exactly as long as it is actually running, regardless of how many
+	 * other tasks this run launches meanwhile.
+	 */
+	private readonly runningOwned = new Set<TaskId>()
+	/**
+	 * Owned tasks observed to have settled, oldest first, bounded to
+	 * {@link OWNED_WORK_DISPLAY_LIMIT}.
+	 *
+	 * This bound is display-driven, not a memory concern the way
+	 * {@link UNOWNED_BUFFER_LIMIT} is: a settled task's own result already
+	 * reached the model once (inline or as a notification), so dropping it
+	 * from here loses a convenience, not the only record of it.
+	 */
+	private readonly settledOwned: TaskId[] = []
 	/**
 	 * Announcements that arrived before anyone said whose task it was.
 	 *
@@ -130,6 +170,7 @@ export class CompletionInbox {
 			// finished its wait faster than the listener ran — is already
 			// delivered. Nothing to queue.
 			this.outstanding.delete(handle.taskId)
+			this.markSettled(handle.taskId)
 			if (this.claimed.has(handle.taskId)) return
 			this.unheard.set(handle.taskId, handle)
 			for (const wake of this.arrivals) wake()
@@ -193,25 +234,49 @@ export class CompletionInbox {
 	launched(taskId: TaskId): void {
 		if (this.ours.has(taskId)) return
 		this.ours.add(taskId)
-		this.recentOwned.push(taskId)
-		if (this.recentOwned.length > 16) this.recentOwned.shift()
 
-		if (this.claimed.has(taskId) || this.unheard.has(taskId)) return
+		if (this.claimed.has(taskId) || this.unheard.has(taskId)) {
+			this.markSettled(taskId)
+			return
+		}
 
 		const parked = this.unowned.get(taskId)
 		if (parked) {
 			this.unowned.delete(taskId)
 			this.unheard.set(taskId, parked)
+			this.markSettled(taskId)
 			for (const wake of [...this.arrivals]) wake()
 			return
 		}
 
 		const settled = this.gateway?.getTask(taskId)
-		if (!settled || !isTerminalAgentTaskState(settled.state)) return
+		if (!settled || !isTerminalAgentTaskState(settled.state)) {
+			// Not observed terminal by any of the checks above: still running,
+			// as far as this inbox knows.
+			this.runningOwned.add(taskId)
+			return
+		}
 		this.unheard.set(taskId, settled)
+		this.markSettled(taskId)
 		for (const wake of [...this.arrivals]) wake()
 	}
 
+	/**
+	 * Move an owned task from {@link runningOwned} to {@link settledOwned}.
+	 *
+	 * Idempotent: `claim` and the completion listener can both observe the
+	 * same settlement (the race either can win), and re-marking a task that
+	 * is already in {@link settledOwned} moves it to the most-recently-settled
+	 * end rather than duplicating it there.
+	 */
+	private markSettled(taskId: TaskId): void {
+		this.runningOwned.delete(taskId)
+		const at = this.settledOwned.indexOf(taskId)
+		if (at !== -1) this.settledOwned.splice(at, 1)
+		this.settledOwned.push(taskId)
+		if (this.settledOwned.length > OWNED_WORK_DISPLAY_LIMIT) this.settledOwned.shift()
+	}
+
 	/**
 	 * Say that a task was launched with nothing waiting on it.
 	 *
@@ -274,6 +339,13 @@ export class CompletionInbox {
 		this.claimed.add(taskId)
 		this.unheard.delete(taskId)
 		this.outstanding.delete(taskId)
+		// A tool only claims a result it is already holding, so a claim is
+		// itself proof of settlement — independent of whether the gateway's
+		// own broadcast has reached this inbox yet. Without this, a task
+		// claimed ahead of its announcement (see the race above) stayed in
+		// {@link runningOwned} until that announcement arrived, understating
+		// its own "still running" count in the meantime.
+		this.markSettled(taskId)
 	}
 
 	/** Whether anything is waiting to be told. */
@@ -281,10 +353,29 @@ export class CompletionInbox {
 		return this.unheard.size > 0
 	}
 
-	/** Bounded, non-consuming scheduler observations. Delivery never establishes user-facing completion. */
+	/**
+	 * Bounded, non-consuming scheduler observations. Delivery never
+	 * establishes user-facing completion.
+	 *
+	 * Running tasks — most recently launched first, matching the order the
+	 * rest of this projection has always used — fill the {@link
+	 * OWNED_WORK_DISPLAY_LIMIT} slots first, so a task still going is named
+	 * here for as long as it keeps running, no matter how many other tasks
+	 * this run has since launched. The most recently SETTLED tasks fill
+	 * whatever slots running tasks leave over. A settled task bumped out
+	 * entirely is not reported missing — its own result already reached the
+	 * model once — but a RUNNING task that does not fit is: the preamble
+	 * says exactly how many, so the model never mistakes the cap for the
+	 * task having ended.
+	 */
 	describeOwnedWork(): string | undefined {
 		if (this.ours.size === 0) return
-		const ids = this.recentOwned
+		const running = [...this.runningOwned].reverse()
+		const shownRunning = running.slice(0, OWNED_WORK_DISPLAY_LIMIT)
+		const stillRunningNotShown = running.length - shownRunning.length
+		const settled = [...this.settledOwned].reverse()
+		const shownSettled = settled.slice(0, OWNED_WORK_DISPLAY_LIMIT - shownRunning.length)
+		const ids = [...shownRunning, ...shownSettled]
 		const tasks = ids.map((taskId) => {
 			let handle = this.unheard.get(taskId)
 			try {
@@ -300,7 +391,11 @@ export class CompletionInbox {
 				resultDelivery: this.claimed.has(taskId) ? 'delivered-to-history' : 'not-delivered',
 			}
 		})
-		return `Owned delegated work (current scheduler observations). Result delivery is not proof that you answered the original request. Answer the latest operator message and complete the requested synthesis of available results unless the operator cancelled or changed that request. Reuse delivered results when sufficient; do not relaunch completed work. If a delivered result is no longer visible, retrieve it by task ID. A terminal state with a non-end_turn stop reason is not successful task completion. Do not repeat a synthesis already given.\n${JSON.stringify({ tasks, omitted: this.ours.size - ids.length })}`
+		const overflow =
+			stillRunningNotShown > 0
+				? ` ${shownRunning.length} running tasks are shown below, and ${stillRunningNotShown} more still running.`
+				: ''
+		return `Owned delegated work (current scheduler observations).${overflow} Result delivery is not proof that you answered the original request. Answer the latest operator message and complete the requested synthesis of available results unless the operator cancelled or changed that request. Reuse delivered results when sufficient; do not relaunch completed work. If a delivered result is no longer visible, retrieve it by task ID. A terminal state with a non-end_turn stop reason is not successful task completion. Do not repeat a synthesis already given.\n${JSON.stringify({ tasks, omitted: this.ours.size - ids.length })}`
 	}
 
 	/**
@@ -391,7 +486,8 @@ export class CompletionInbox {
 		this.unheard.clear()
 		this.outstanding.clear()
 		this.ours.clear()
-		this.recentOwned.length = 0
+		this.runningOwned.clear()
+		this.settledOwned.length = 0
 		this.claimed.clear()
 		this.unowned.clear()
 		// Release anyone still waiting. A closed inbox would otherwise hold

package/src/tools/builtins/bash.ts

@@ -5,6 +5,7 @@ import { SANDBOX_KILL_GRACE_MS } from '../../constants/sandbox/index.js'
 import { DANGEROUS_PATTERNS } from '../../constants/tools/index.js'
 import { killTree } from '../../process/kill-tree.js'
 import { subscribeToAbort } from '../../utils/abort.js'
+import { readPositiveIntEnv } from '../../utils/env.js'
 import { defineTool } from '../defineTool.js'
 import { scrubInheritedEnv } from '../env-scrub.js'
 
@@ -57,13 +58,13 @@ const inputSchema = z.object({
 			z.number().positive().max(MAX_BASH_TIMEOUT_MS).default(DEFAULT_BASH_TIMEOUT_MS),
 		)
 		.describe(
-			`Command timeout in milliseconds. Default: ${DEFAULT_BASH_TIMEOUT_MS}, maximum: ${MAX_BASH_TIMEOUT_MS}. For work that legitimately runs longer than the maximum, set run_in_background and poll with the \`job\` tool, rather than holding the turn open.`,
+			`Command timeout in milliseconds. Default: ${DEFAULT_BASH_TIMEOUT_MS}, maximum: ${MAX_BASH_TIMEOUT_MS}. For work that legitimately runs longer than the maximum, set run_in_background and await it with \`wait_for_job\`, rather than holding the turn open.`,
 		),
 	run_in_background: z
 		.boolean()
 		.optional()
 		.describe(
-			'Start the command as a background job and return its id immediately, instead of waiting. The turn is not held open; read its output with the `job` tool. Use for watchers, dev servers and long builds. Do NOT write `cmd &` yourself — under the sandbox the shell that backgrounds it exits immediately and takes the job with it.',
+			'Start the command as a background job and return its id immediately, instead of waiting. The turn is not held open; await its completion with `wait_for_job` — one call, no waiting turns. Use `job` with action "read" only for incremental output while it keeps running, or to pick up after a `wait_for_job` call times out. Use for watchers, dev servers and long builds. Do NOT write `cmd &` yourself — under the sandbox the shell that backgrounds it exits immediately and takes the job with it.',
 		),
 })
 
@@ -343,7 +344,7 @@ export const BashTool = defineTool({
 				})
 				return {
 					success: true,
-					output: `Started background job ${job.id}. Read its output with the \`job\` tool: {"action":"read","id":"${job.id}"}.`,
+					output: `Started background job ${job.id}. Await its completion with wait_for_job: {"id":"${job.id}"}. Use job with action "read" only for output while it keeps running.`,
 					data: { jobId: job.id, background: true },
 				}
 			} catch (err) {
@@ -539,10 +540,3 @@ function describeWithheldEnv(dropped: readonly string[]): string {
 	const names = rest > 0 ? `${shown}, and ${rest} more` : shown
 	return `NOTE: ${dropped.length} credential-shaped environment variable(s) were withheld from this command and are unset rather than empty: ${names}. A host that means this command to have one passes it explicitly.`
 }
-
-function readPositiveIntEnv(key: string, fallback: number): number {
-	const value = process.env[key]?.trim()
-	if (!value) return fallback
-	const parsed = Number(value)
-	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback
-}