@namzu/sdk 52.7.0 → 53.0.0

package/src/plugin/shell-hook.ts

@@ -57,7 +57,7 @@
  * - `systemMessage` — a warning for the operator, reported through the logger.
  * - `suppressOutput` — keep this hook's stdout out of the debug log.
  * - `hookSpecificOutput` with `hookEventName` naming this event (Namzu's
- *   name or the reference spelling `PreToolUse`, `Stop`, ...):
+ *   name or the PascalCase spelling `PreToolUse`, `Stop`, ...):
  *   `permissionDecision` (`allow`, `deny` or `ask`) with
  *   `permissionDecisionReason`, `updatedInput` and `additionalContext` for
  *   `pre_tool_use`; `additionalContext` for `user_prompt_submit`,
@@ -458,8 +458,8 @@ function pathOf(toolInput: unknown): string | undefined {
 	return undefined
 }
 
-/** The reference spelling of each event name, which a hook's JSON may use. */
-const REFERENCE_EVENT_NAMES: Readonly<Partial<Record<ShellHookEvent, string>>> = {
+/** The PascalCase spelling of each event name, which a hook's JSON may use. */
+const PASCAL_EVENT_NAMES: Readonly<Partial<Record<ShellHookEvent, string>>> = {
 	user_prompt_submit: 'UserPromptSubmit',
 	session_start: 'SessionStart',
 	session_end: 'SessionEnd',
@@ -565,7 +565,7 @@ function readShellHookJson(event: ShellHookEvent, stdout: string): ShellHookRead
 	if (typeof named !== 'string') {
 		return { invalid: '`hookSpecificOutput` is missing its `hookEventName`' }
 	}
-	if (named !== event && named !== REFERENCE_EVENT_NAMES[event]) {
+	if (named !== event && named !== PASCAL_EVENT_NAMES[event]) {
 		return {
 			invalid: `\`hookSpecificOutput.hookEventName\` is "${named}" but this hook ran for ${event}`,
 		}

package/src/provider/errors.ts

@@ -260,8 +260,8 @@ const OVERFLOW_BODY_PATTERNS: readonly RegExp[] = [
 	// length" — so a pattern anchored on "exceeded" misses it entirely.
 	/exceeds?\s+(?:the\s+)?(?:model'?s?\s+)?context\s+(?:length|window|size)/i,
 	/context\s+(?:length|window|size)\s+exceed/i,
-	// The reference terminal's own list matches the bare phrase "context
-	// window". Here it must sit next to a verb that says the request did not
+	// The bare phrase "context
+	// window" is too broad on its own. Here it must sit next to a verb that says the request did not
 	// fit ("larger than the model context window of N tokens"), so a 400 that
 	// only names the window ("does not support this parameter with the 1M
 	// context window beta") stays an invalid request. The same pattern lives in

package/src/public-runtime.ts

@@ -722,6 +722,7 @@ export {
 	CompletionInbox,
 	formatCompletionNotification,
 } from './scheduler/completion-inbox.js'
+export type { CompletionInboxOptions } from './scheduler/completion-inbox.js'
 
 // Scheduled jobs: WHEN something is due, and nothing about how a host stores
 // or runs a job. The time engine and the evaluator are pure (`Intl` for time

package/src/runtime/jobs/monitor-stream.ts

@@ -15,8 +15,7 @@
  * work without any injection), which is what lets the tests advance a window
  * by calling a function rather than by waiting for one.
  *
- * The constants and the wording come from the reference implementation of this
- * tool; deviations are named where they are made.
+ * The constants and the wording are fixed here.
  */
 
 /** A longer line keeps its first this-many characters. */

package/src/runtime/jobs/websocket-source.ts

@@ -29,7 +29,7 @@ import type { JobHost, JobSource } from './registry.js'
  * asks a person first (see `tools/builtins/monitor.ts`).
  */
 
-/** The largest frame accepted; a bigger one ends the watch. Same as the reference. */
+/** The largest frame accepted; a bigger one ends the watch. */
 export const WEBSOCKET_MAX_PAYLOAD_BYTES = 1_048_576
 export const WEBSOCKET_HANDSHAKE_TIMEOUT_MS = 15_000
 /** After a polite close, how long a peer gets to answer before the socket is destroyed. */

package/src/runtime/query/iteration/index.ts

@@ -526,7 +526,7 @@ export class IterationOrchestrator {
 		await this.ctx.checkpointMgr.markLoopStart?.(recorder)
 
 		// Context-overflow relief is a two-rung ladder per *stuck point*, not per
-		// turn, as in the reference terminal (at most two reactive compactions per
+		// turn (at most two reactive compactions per
 		// overflow): the first relief, then one deeper pass if the retry still
 		// overflows.
 		//
@@ -2121,7 +2121,7 @@ export class IterationOrchestrator {
 						classifyProviderError(err, this.ctx.provider.id).code === 'context_length_exceeded'
 					) {
 						// The rapid-refill check comes first, before the first reactive relief
-						// of an overflow, as in the reference terminal. A relief that follows
+						// of an overflow. A relief that follows
 						// the previous compaction within the refill window counts toward the
 						// limit, so a tool that re-fills the window every time it is called
 						// stops the turn instead of being cleared and called again without end.
@@ -2155,7 +2155,7 @@ export class IterationOrchestrator {
 							continue
 						}
 						// Out of rungs. The conversation is kept; say why compaction could not
-						// make room when it errored, as the reference does.
+						// make room when it errored.
 						const cause = compactionErrorNote(this.ctx)
 						if (cause !== undefined && err instanceof Error) {
 							try {

package/src/runtime/query/iteration/outstanding-work.ts

@@ -163,7 +163,7 @@ export async function* holdForOutstandingWork(
 	hasToolCalls: boolean,
 	deliverInbound: () => number | Promise<number>,
 ): AsyncGenerator<SessionEvent, boolean> {
-	const inbox = ctx.completionInbox?.hasPendingWork ? ctx.completionInbox : undefined
+	const inbox = ctx.completionInbox?.holdsTurn ? ctx.completionInbox : undefined
 	const jobs = ctx.awaitedJobs?.hasPendingWork ? ctx.awaitedJobs : undefined
 	if (!inbox && !jobs) return false
 
@@ -370,7 +370,14 @@ export function settleOutstandingWork(ctx: IterationContext): void {
 /** Work this turn walked away from. See {@link settleOutstandingWork}. */
 export function recordAbandonedWork(ctx: IterationContext): void {
 	const abandoned = ctx.completionInbox?.outstandingTaskIds ?? []
-	if (abandoned.length > 0) {
+	if (abandoned.length > 0 && ctx.completionInbox?.holdsTurnOpen === false) {
+		// Handed over on purpose: the host keeps these running and tells the
+		// model when they end, so the turn did not walk away from them.
+		ctx.log.info('Turn ended with delegated work left running in the background', {
+			[NAMZU.TURN_ID]: ctx.recorder.turnId,
+			'namzu.runtime.tasks': abandoned,
+		})
+	} else if (abandoned.length > 0) {
 		ctx.log.warn('Turn ended with delegated work still running', {
 			[NAMZU.TURN_ID]: ctx.recorder.turnId,
 			'namzu.runtime.tasks': abandoned,

package/src/runtime/query/iteration/phases/compaction-breaker.ts

@@ -30,8 +30,8 @@ export const COMPACTION_REFILL_LIMIT = 3
 
 /**
  * One short line, shown once, when the turn stops on refills. It names the
- * cause and a step that keeps the conversation: the reference terminal also
- * offers to start over here, and Namzu never does.
+ * cause and a step that keeps the conversation: starting over is never
+ * offered here.
  */
 export const COMPACTION_REFILL_MESSAGE =
 	'The context filled up again right after being compacted, three times in a row. A file being read or a tool output is probably too large for the context window. Try reading it in smaller parts.'

package/src/runtime/query/iteration/phases/compaction.ts

@@ -221,8 +221,7 @@ export function measureContext(ctx: IterationContext): {
 }
 
 /**
- * Reactive compactions allowed for one overflow, as in the reference
- * terminal: the first relief, then at most one deeper pass.
+ * Reactive compactions allowed for one overflow: the first relief, then at most one deeper pass.
  */
 export const OVERFLOW_RELIEF_LIMIT = 2
 
@@ -350,8 +349,8 @@ export async function relieveOverflow(
 
 /**
  * Why the last compaction attempt errored, kept for the turn so that when
- * relief runs out the failure it ends on can say so, as the reference
- * terminal's " · automatic compaction failed: <cause>" does.
+ * relief runs out the failure it ends on can say so, and it reads
+ * " · automatic compaction failed: <cause>".
  */
 const compactionErrors = new WeakMap<object, string>()
 const MAX_COMPACTION_CAUSE_CHARS = 300
@@ -430,9 +429,8 @@ async function declined(
 /**
  * The third refill in a row: stop the turn instead of compacting again.
  * Returns true when this pass must not run. Only with `circuitBreaker`.
- * The loop also asks it before the first reactive relief of an overflow, as
- * the reference terminal does (`rhr` runs first in its withheld-overflow
- * handling), so a re-read loop made only of overflows is counted too.
+ * The loop also asks it before the first reactive relief of an overflow, so a re-read loop made
+ * only of overflows is counted too.
  */
 export async function stopOnRefill(ctx: IterationContext): Promise<boolean> {
 	const breaker = compactionBreaker(ctx)
@@ -721,7 +719,7 @@ async function runCompactionCheckInner(
 	const breaker = compactionBreaker(ctx)
 	if (breaker?.failuresOpen && !options?.force) {
 		if (breaker.takeFailureNotice()) {
-			// Silent for the person, as in the reference terminal: a log line and the
+			// Silent for the person: a log line and the
 			// event for a host that wants it, but no sentence to show. Only the
 			// proactive pass stops; a real overflow still runs the reactive ladder.
 			ctx.log.warn('Compaction failed three times in a row — switched off for this turn', {

package/src/runtime/query/iteration/request-repair.ts

@@ -21,7 +21,7 @@ import { isProviderRejectedImageError } from './provider-rejected-image.js'
  * Repair-and-retry for a request a provider rejects as invalid (a 400 that is
  * not a context overflow), so a conversation does not dead-end on it.
  *
- * Mirrors the reference terminal's table of silent 400 recoveries: pair tool
+ * The silent 400 recoveries, in order: pair tool
  * calls with results before a send, strip rejected reasoning, drop a
  * parameter the model refuses, and take rejected media out of the OUTGOING
  * request. Stored history is never edited.
@@ -77,7 +77,7 @@ type Rejection =
 /** Most repair resends for one original request, across every send it makes. */
 export const MAX_REPAIRS_PER_REQUEST = 5
 const MAX_STRIPS_PER_INDEX = 3
-/** The reference drops media in these steps for an unprocessable request. */
+/** Media is dropped in these steps for an unprocessable request. */
 const GENERIC_MEDIA_LIMITS: readonly number[] = [510, 255, 127]
 
 const PARAMETER_CODES: ReadonlySet<string> = new Set([
@@ -608,7 +608,7 @@ export class RequestRepair {
 				victims = slots.filter((slot) => slot.messageIndex === newest.messageIndex)
 			}
 		} else {
-			// The reference's steps, then halving for smaller requests, down to
+			// The media steps, then halving for smaller requests, down to
 			// none: each step keeps fewer than the request held, newest first.
 			const limit =
 				GENERIC_MEDIA_LIMITS.find((candidate) => candidate < slots.length) ??

package/src/runtime/query/path-escalation.ts

@@ -46,8 +46,7 @@ export interface PathEscalationContext {
  * a root that itself sits under a protected name is not a reason to ask about
  * every file in it. The case that matters is the managed worktree a sub-agent
  * runs in, `~/.namzu/projects/<slug>/worktrees/<name>`, which lies under
- * `.namzu` by construction; the reference terminal makes the same exception
- * for its own worktrees directory. A path in no root is looked at whole.
+ * `.namzu` by construction. A path in no root is looked at whole.
  */
 function protectedScope(absolute: string, roots: readonly string[]): string {
 	let best: string | undefined
@@ -194,7 +193,7 @@ export async function shellEscalations(
 				if (!context.reviewOutside) continue
 				if (unresolved) {
 					// A write whose target is decided at runtime cannot be checked; a
-					// read of one is left, as the reference leaves it.
+					// read of one is left alone.
 					if (use.access === 'write') outside.add(spelled)
 					continue
 				}

package/src/scheduler/completion-inbox.ts

@@ -43,6 +43,11 @@ const UNOWNED_BUFFER_LIMIT = 32
  */
 const OWNED_WORK_DISPLAY_LIMIT = 16
 
+export interface CompletionInboxOptions {
+	/** See {@link CompletionInbox.holdsTurnOpen}. Default `true`. */
+	readonly holdsTurnOpen?: boolean
+}
+
 /**
  * Completions that finished with nobody left to hear them.
  *
@@ -151,7 +156,23 @@ export class CompletionInbox {
 	 * `log` is optional and unresolved until it is actually needed (the
 	 * eviction-warning path in `hold()`), same reason as `LocalTaskScheduler`.
 	 */
-	constructor(private readonly log?: Logger) {}
+	constructor(
+		private readonly log?: Logger,
+		options: CompletionInboxOptions = {},
+	) {
+		this.holdsTurnOpen = options.holdsTurnOpen !== false
+	}
+
+	/**
+	 * Whether a turn about to end waits here for the tasks still running.
+	 *
+	 * `true` (the default) is the original contract: the turn parks at its settle
+	 * point until the tasks it launched report back, so their results enter the
+	 * same turn. `false` lets the turn end with them still running; the host owns
+	 * their completion from then on (it keeps them alive and wakes the model when
+	 * they end). Completions that have already arrived are delivered either way.
+	 */
+	readonly holdsTurnOpen: boolean
 
 	/**
 	 * Start listening.
@@ -349,6 +370,15 @@ export class CompletionInbox {
 		return this.unheard.size > 0 || this.outstanding.size > 0
 	}
 
+	/**
+	 * Whether the turn has a reason to wait at its settle point: anything
+	 * pending when it {@link holdsTurnOpen}, else only a completion already in
+	 * hand (waiting for its persistence gate).
+	 */
+	get holdsTurn(): boolean {
+		return this.holdsTurnOpen ? this.hasPendingWork : this.unheard.size > 0
+	}
+
 	/**
 	 * Wait for the next completion, deadline or abort, whichever comes first.
 	 * Aborting releases only this waiter; work and undelivered results remain owned.

package/src/session/workspace/driver.ts

@@ -22,7 +22,7 @@ export interface CreateWorkspaceParams {
 	/**
 	 * Traceable name below the configured workspace root. Nested names are
 	 * accepted; absolute paths, traversal, and paths rewritten by a filesystem
-	 * link are refused by the reference Git driver.
+	 * link are refused by the Git driver.
 	 */
 	label?: string
 }

package/src/store/checkpoint/memory.ts

@@ -26,7 +26,7 @@ export interface InMemorySessionCheckpointStoreOptions {
  *
  * It keeps the serialised bytes rather than the object, so `restore` hashes
  * exactly what `write` hashed and refuses exactly what the disk store
- * refuses. It is the parity partner of the disk store and the store an
+ * refuses. It is the counterpart of the disk store and the store an
  * in-memory session keeps its checkpoints in.
  */
 export class InMemorySessionCheckpointStore implements SessionCheckpointStore {

package/src/store/memory/markdown-format.ts

@@ -249,7 +249,7 @@ export interface MemoryFileFields {
 /**
  * The file for one memory. Fields that repeat another are left out — a title
  * equal to the name, a summary equal to the description, the default format —
- * so an ordinary file carries the reference shape and nothing else.
+ * so an ordinary file carries the canonical shape and nothing else.
  */
 export function formatMemoryFile(fields: MemoryFileFields, body: string): string {
 	const lines: string[] = ['---']

package/src/store/memory/markdown.ts

@@ -53,7 +53,7 @@ import { MemoryRevisionConflictError, assertMemoryRevision, memoryRevision } fro
 
 /**
  * Versioned like every other record this SDK persists. A memory file carries
- * no `schemaVersion` while it is at version 1 — the reference shape has no
+ * no `schemaVersion` while it is at version 1 — the canonical shape has no
  * such field and a hand-written file should not need one — so the stamp only
  * appears once a later build writes a later version, and THIS build refuses
  * that file rather than reading it partially and writing the difference away.

package/src/tools/builtins/bash.ts

@@ -52,8 +52,7 @@ const DEFAULT_BASH_MAX_BUFFER_BYTES = readPositiveIntEnv(
  *
  * So the tool declares a ceiling and the executor is given a deadline above
  * it (see `timeoutMs` on the definition), which makes this the only clock
- * that can fire in practice. A request past the ceiling is CLAMPED to it, as
- * the reference terminal does: the command still runs, and a timeout reports
+ * that can fire in practice. A request past the ceiling is CLAMPED to it: the command still runs, and a timeout reports
  * the deadline that was actually applied, so the number the model sees on a
  * timeout is the one that fired.
  */

package/src/tools/builtins/edit-match.ts

@@ -9,18 +9,17 @@
  * carries the same transformation across to `new_string` so the replacement
  * stays consistent with what it replaced.
  *
- * The strategies and their order are a faithful port of the reference client's
- * file-edit resolver (the `lje`/`b`/`_`/`L`/`k`/`R`/`C`/`cDs`/`ipt`/`H`/`Q`/`N`
- * functions in its shipped bundle), so an edit that lands there lands here:
+ * The strategies and their order are fixed as follows, so an edit that matches
+ * under one of them matches here:
  *
  *   1. exact
  *   2. curly vs straight quotes, both directions
  *   3. `\uXXXX` escape in `old_string`, character in the file
  *   4. character in `old_string`, `\uXXXX` escape in the file
  *
- * The reference also expands a map of its own prompt delimiters (`<fnr>` →
- * `<function_results>`, `\n\nH:` → `\n\nHuman:`, …). That is deliberately NOT
- * ported: those tokens are artifacts of that client's own transcript format,
+ * Prompt delimiters from a transcript format (`<fnr>` →
+ * `<function_results>`, `\n\nH:` → `\n\nHuman:`, …) are deliberately NOT
+ * expanded: those tokens are artifacts of a transcript format,
  * not a mismatch a Namzu model produces against a real source file.
  *
  * Pure by construction, like `edit-apply`: every function here is from strings

package/src/types/provider/errors.ts

@@ -337,7 +337,7 @@ function codeFromMessage(message: string, status?: number): ProviderErrorCode |
 		// overflow rescue tests for by exact equality. The turn died holding
 		// the remedy.
 		m.includes('too long for') ||
-		// The reference terminal's own wordings (its `context window` and
+		// Known wordings: `context window` and
 		// `input length and max_tokens exceed context limit` matchers).
 		// Only where the status cannot say otherwise: a 429, 5xx or 401 that
 		// mentions the window is still a rate limit, a server fault or an auth