@namzu/sdk 50.0.0 → 51.0.0

package/src/execution/workflow/schema.ts

@@ -0,0 +1,137 @@
+/**
+ * A small JSON Schema validator for `agent(..., { schema })`.
+ *
+ * Supported keywords: `type` (string or list), `enum`, `const`, `properties`,
+ * `required`, `additionalProperties` (boolean or schema), `items` (one
+ * schema), `minItems`, `maxItems`, `minLength`, `maxLength`, `minimum`,
+ * `maximum`, `anyOf`, `oneOf`, `allOf`. Any other keyword is ignored, and the
+ * schema is also handed to the host so a model-side structured-output
+ * mechanism can enforce more. `pattern` is deliberately not supported: the
+ * schema is model-authored and a regular expression is a CPU risk.
+ */
+const MAX_DEPTH = 32
+
+function typeOf(value: unknown): string {
+	if (value === null) return 'null'
+	if (Array.isArray(value)) return 'array'
+	if (typeof value === 'number') return Number.isInteger(value) ? 'integer' : 'number'
+	return typeof value
+}
+
+function matchesType(value: unknown, type: string): boolean {
+	const actual = typeOf(value)
+	return actual === type || (type === 'number' && actual === 'integer')
+}
+
+function same(a: unknown, b: unknown): boolean {
+	return JSON.stringify(a) === JSON.stringify(b)
+}
+
+function isSchema(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function check(value: unknown, schema: unknown, path: string, depth: number): string | undefined {
+	if (schema === true || schema === undefined) return undefined
+	if (schema === false) return `${path}: nothing is allowed here`
+	if (!isSchema(schema)) return undefined
+	if (depth > MAX_DEPTH) return `${path}: schema is nested too deeply`
+	const here = path || 'the result'
+
+	const type = schema.type
+	if (typeof type === 'string' && !matchesType(value, type)) {
+		return `${here} must be ${type}, got ${typeOf(value)}`
+	}
+	if (Array.isArray(type) && !type.some((t) => typeof t === 'string' && matchesType(value, t))) {
+		return `${here} must be one of ${type.join(', ')}, got ${typeOf(value)}`
+	}
+	if (Array.isArray(schema.enum) && !schema.enum.some((e) => same(e, value))) {
+		return `${here} must be one of ${JSON.stringify(schema.enum)}`
+	}
+	if ('const' in schema && !same(schema.const, value)) {
+		return `${here} must equal ${JSON.stringify(schema.const)}`
+	}
+	if (typeof value === 'string') {
+		if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
+			return `${here} is shorter than ${schema.minLength} characters`
+		}
+		if (typeof schema.maxLength === 'number' && value.length > schema.maxLength) {
+			return `${here} is longer than ${schema.maxLength} characters`
+		}
+	}
+	if (typeof value === 'number') {
+		if (typeof schema.minimum === 'number' && value < schema.minimum) {
+			return `${here} is below ${schema.minimum}`
+		}
+		if (typeof schema.maximum === 'number' && value > schema.maximum) {
+			return `${here} is above ${schema.maximum}`
+		}
+	}
+	if (Array.isArray(value)) {
+		if (typeof schema.minItems === 'number' && value.length < schema.minItems) {
+			return `${here} has fewer than ${schema.minItems} items`
+		}
+		if (typeof schema.maxItems === 'number' && value.length > schema.maxItems) {
+			return `${here} has more than ${schema.maxItems} items`
+		}
+		if (schema.items !== undefined) {
+			for (const [i, item] of value.entries()) {
+				const problem = check(item, schema.items, `${path}[${i}]`, depth + 1)
+				if (problem) return problem
+			}
+		}
+	}
+	if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+		const object = value as Record<string, unknown>
+		if (Array.isArray(schema.required)) {
+			for (const key of schema.required) {
+				if (typeof key === 'string' && !Object.hasOwn(object, key)) {
+					return `${here} is missing "${key}"`
+				}
+			}
+		}
+		const properties = isSchema(schema.properties) ? schema.properties : {}
+		for (const [key, child] of Object.entries(object)) {
+			const childPath = path ? `${path}.${key}` : key
+			if (Object.hasOwn(properties, key)) {
+				const problem = check(child, properties[key], childPath, depth + 1)
+				if (problem) return problem
+			} else if (schema.additionalProperties === false) {
+				return `${here} has an unexpected property "${key}"`
+			} else if (isSchema(schema.additionalProperties)) {
+				const problem = check(child, schema.additionalProperties, childPath, depth + 1)
+				if (problem) return problem
+			}
+		}
+	}
+	if (Array.isArray(schema.allOf)) {
+		for (const part of schema.allOf) {
+			const problem = check(value, part, path, depth + 1)
+			if (problem) return problem
+		}
+	}
+	if (Array.isArray(schema.anyOf) && !schema.anyOf.some((p) => !check(value, p, path, depth + 1))) {
+		return `${here} matches none of the allowed shapes`
+	}
+	if (Array.isArray(schema.oneOf)) {
+		const matching = schema.oneOf.filter((p) => !check(value, p, path, depth + 1)).length
+		if (matching !== 1) return `${here} must match exactly one allowed shape, matches ${matching}`
+	}
+	return undefined
+}
+
+/** `undefined` when `value` satisfies `schema`, otherwise a plain sentence naming the first problem. */
+export function validateAgainstSchema(value: unknown, schema: unknown): string | undefined {
+	return check(value, schema, '', 0)
+}
+
+/** Parse a model's text as JSON, tolerating one surrounding code fence. */
+export function parseJsonText(text: string): { ok: true; value: unknown } | { ok: false } {
+	const trimmed = text.trim()
+	const fenced = /^```(?:json)?\s*\n([\s\S]*?)\n```$/.exec(trimmed)
+	try {
+		return { ok: true, value: JSON.parse(fenced ? (fenced[1] as string) : trimmed) }
+	} catch {
+		return { ok: false }
+	}
+}

package/src/execution/workflow/types.ts

@@ -0,0 +1,300 @@
+/**
+ * Types of the workflow runtime: a script the model wrote once decides how
+ * many subagents run, with which prompts and under which phase titles; the
+ * runtime schedules them. See `docs/sdk/workflows.md`.
+ */
+
+/** One phase declared in `meta.phases`. */
+export interface WorkflowPhaseMeta {
+	readonly title: string
+	readonly detail?: string
+	readonly model?: string
+}
+
+/** The pure literal a script exports as `meta`. */
+export interface WorkflowMeta {
+	readonly name: string
+	readonly description: string
+	readonly whenToUse?: string
+	readonly phases: readonly WorkflowPhaseMeta[]
+}
+
+/** What the host is asked to run for one `agent()` call. */
+export interface WorkflowAgentRequest {
+	/** 1-based, in the order the script asked. */
+	readonly index: number
+	readonly label: string
+	readonly prompt: string
+	readonly phaseIndex?: number
+	readonly phaseTitle?: string
+	/** JSON Schema the result must satisfy; the runtime validates `data`. */
+	readonly schema?: Readonly<Record<string, unknown>>
+	readonly agentType?: string
+	readonly model?: string
+	readonly effort?: string
+	/** Report live progress; the runtime turns it into `workflow_agent` events. */
+	readonly onProgress: (progress: WorkflowAgentProgress) => void
+}
+
+export interface WorkflowAgentProgress {
+	readonly tokens?: number
+	readonly toolCalls?: number
+	readonly lastToolName?: string
+	readonly lastToolSummary?: string
+}
+
+/** What the host's agent run came to. */
+export interface WorkflowAgentOutcome {
+	readonly state: 'done' | 'error' | 'skipped'
+	/** The agent's final text. */
+	readonly text?: string
+	/** A structured result, when the host produced one for the schema. */
+	readonly data?: unknown
+	readonly tokens: number
+	readonly toolCalls: number
+	readonly error?: string
+}
+
+/**
+ * Starts one subagent through the host's own delegation path (the same
+ * policy, sandbox, accounting and cancellation as the `Agent` tool).
+ * Must honour `signal`.
+ */
+export type WorkflowSpawnAgent = (
+	request: WorkflowAgentRequest,
+	signal: AbortSignal,
+) => Promise<WorkflowAgentOutcome>
+
+export type WorkflowAgentState = 'start' | 'progress' | 'done' | 'error'
+
+export interface WorkflowStartedEvent {
+	readonly type: 'workflow_started'
+	readonly runId: string
+	readonly name: string
+	readonly description: string
+	readonly phases: readonly WorkflowPhaseMeta[]
+	readonly at: number
+}
+
+export interface WorkflowPhaseEvent {
+	readonly type: 'workflow_phase'
+	readonly runId: string
+	/** 1-based first-seen order; declared titles come first. */
+	readonly index: number
+	readonly title: string
+	readonly declared: boolean
+	readonly at: number
+}
+
+/**
+ * One agent changed state. `start` without `startedAt` means queued;
+ * `start` with `startedAt` means running. A `done` agent that was skipped
+ * (by the host, the operator or the token budget) carries `skipped: true`.
+ */
+export interface WorkflowAgentEvent {
+	readonly type: 'workflow_agent'
+	readonly runId: string
+	readonly state: WorkflowAgentState
+	readonly index: number
+	readonly label: string
+	readonly phaseIndex?: number
+	readonly phaseTitle?: string
+	readonly agentType?: string
+	readonly model?: string
+	readonly queuedAt: number
+	readonly startedAt?: number
+	readonly finishedAt?: number
+	readonly lastProgressAt: number
+	readonly tokens: number
+	readonly toolCalls: number
+	readonly lastToolName?: string
+	readonly lastToolSummary?: string
+	readonly promptPreview: string
+	readonly resultPreview?: string
+	readonly error?: string
+	readonly skipped?: boolean
+}
+
+export interface WorkflowLogEvent {
+	readonly type: 'workflow_log'
+	readonly runId: string
+	readonly message: string
+	readonly at: number
+}
+
+export type WorkflowFinishStatus = 'completed' | 'failed' | 'stopped'
+
+export interface WorkflowUsage {
+	/** Agents the script asked for and the runtime accepted. */
+	readonly agents: number
+	readonly agentsDone: number
+	readonly agentsFailed: number
+	readonly agentsSkipped: number
+	readonly tokens: number
+	readonly toolCalls: number
+	readonly elapsedMs: number
+}
+
+export interface WorkflowFinishedEvent {
+	readonly type: 'workflow_finished'
+	readonly runId: string
+	readonly status: WorkflowFinishStatus
+	readonly result?: unknown
+	readonly error?: string
+	readonly usage: WorkflowUsage
+	readonly at: number
+}
+
+export type WorkflowEvent =
+	| WorkflowStartedEvent
+	| WorkflowPhaseEvent
+	| WorkflowAgentEvent
+	| WorkflowLogEvent
+	| WorkflowFinishedEvent
+
+export type WorkflowPhaseStatus = 'not-started' | 'running' | 'done' | 'failed'
+
+export interface WorkflowPhaseSummary {
+	/** 0 for the derived "Agents" group, which has no phase index. */
+	readonly index: number
+	readonly title: string
+	readonly detail?: string
+	readonly status: WorkflowPhaseStatus
+	readonly agents: number
+	readonly done: number
+	readonly failed: number
+	readonly tokens: number
+}
+
+/** Append-only audit records, one JSON object per line. */
+export type WorkflowJournalRecord =
+	| {
+			readonly type: 'run_started'
+			readonly at: number
+			readonly runId: string
+			readonly scriptSha256: string
+			readonly scriptBytes: number
+			readonly meta: WorkflowMeta
+			readonly args: unknown
+			readonly limits: WorkflowResolvedLimits
+	  }
+	| {
+			readonly type: 'phase'
+			readonly at: number
+			readonly index: number
+			readonly title: string
+			readonly declared: boolean
+	  }
+	| {
+			readonly type: 'agent_request'
+			readonly at: number
+			readonly index: number
+			readonly label: string
+			readonly phaseIndex?: number
+			readonly phaseTitle?: string
+			readonly promptPreview: string
+			readonly promptSha256: string
+			readonly options: {
+				readonly agentType?: string
+				readonly model?: string
+				readonly effort?: string
+				readonly schema: boolean
+			}
+	  }
+	| {
+			readonly type: 'agent_outcome'
+			readonly at: number
+			readonly index: number
+			readonly state: 'done' | 'error' | 'skipped'
+			readonly tokens: number
+			readonly toolCalls: number
+			readonly queuedAt: number
+			readonly startedAt?: number
+			readonly finishedAt: number
+			readonly resultPreview?: string
+			readonly error?: string
+	  }
+	| { readonly type: 'log'; readonly at: number; readonly message: string }
+	| {
+			readonly type: 'run_finished'
+			readonly at: number
+			readonly status: WorkflowFinishStatus
+			readonly result?: unknown
+			readonly error?: string
+			readonly usage: WorkflowUsage
+	  }
+
+/** Where a run's audit trail goes. Injected so the SDK stays host-agnostic. */
+export interface WorkflowJournal {
+	/** Called once, before the first record, with the exact script text. */
+	writeScript?(source: string, sha256: string): Promise<void> | void
+	append(record: WorkflowJournalRecord): Promise<void> | void
+}
+
+export interface WorkflowLimits {
+	/** Agents running at once. Default `min(8, cpus - 2)`, at least 1; at most 16. */
+	readonly maxConcurrency?: number
+	/** Agents one run may start. Default 200; at most 1000. */
+	readonly maxAgents?: number
+	/** UTF-8 script size. Default 256 KiB. */
+	readonly maxSourceBytes?: number
+	/** Interpreter memory. Default 64 MiB. */
+	readonly memoryLimitBytes?: number
+	/** One value crossing the bridge, either way. Default 1 MiB. */
+	readonly maxValueBytes?: number
+	/** Stop admitting new agents once this many tokens are spent. Default: none. */
+	readonly tokenBudget?: number
+	/** Wall clock for the whole run. Default 6 hours. */
+	readonly maxDurationMs?: number
+	/** One synchronous stretch of script execution. Default 2 seconds. */
+	readonly cpuSliceMs?: number
+	/** All synchronous script execution together. Default 60 seconds. */
+	readonly cpuTotalMs?: number
+}
+
+export interface WorkflowResolvedLimits {
+	readonly maxConcurrency: number
+	readonly maxAgents: number
+	readonly maxSourceBytes: number
+	readonly memoryLimitBytes: number
+	readonly maxValueBytes: number
+	readonly tokenBudget?: number
+	readonly maxDurationMs: number
+	readonly cpuSliceMs: number
+	readonly cpuTotalMs: number
+}
+
+/** Lets the host act on one running agent. Handed to `onControl`. */
+export interface WorkflowControl {
+	/** Skip an agent: queued ones never start, running ones are aborted. Its `agent()` resolves `null`. */
+	skipAgent(index: number): boolean
+}
+
+export interface WorkflowRunOptions {
+	/** The script, including its `export const meta` literal. Untrusted. */
+	readonly script: string
+	/** JSON handed to the script as `args`. */
+	readonly args?: unknown
+	readonly limits?: WorkflowLimits
+	readonly spawnAgent: WorkflowSpawnAgent
+	readonly journal?: WorkflowJournal
+	readonly signal?: AbortSignal
+	readonly onEvent?: (event: WorkflowEvent) => void
+	readonly onControl?: (control: WorkflowControl) => void
+	/** Default: a fresh `w` + 8 base36 id. */
+	readonly runId?: string
+}
+
+export interface WorkflowRunResult {
+	readonly runId: string
+	readonly status: WorkflowFinishStatus
+	/** What the script returned (`completed` only). */
+	readonly result?: unknown
+	readonly error?: string
+	readonly usage: WorkflowUsage
+	readonly phases: readonly WorkflowPhaseSummary[]
+	/** True when the script logged more than the output cap and later lines were dropped. */
+	readonly logsTruncated: boolean
+	/** Set when the journal could not be written; the run itself was not affected. */
+	readonly journalError?: string
+}

package/src/index.ts

@@ -19,6 +19,10 @@ export {
 	UnknownBackgroundJobError,
 	bindOwner,
 } from './runtime/jobs/registry.js'
+export {
+	createBackgroundJobId,
+	isBackgroundJobId,
+} from './runtime/jobs/job-id.js'
 export type {
 	BackgroundJob,
 	BackgroundJobOutput,

package/src/plugin/shell-hook.ts

@@ -231,7 +231,8 @@ export function runShellHook(
 				// its own — the hook's deadline becomes the grandchild's.
 				detached: process.platform !== 'win32',
 				// A hook has always run under `sh`, whatever shell the `bash` tool
-				// chose. Windows has no `sh`, so there the host's own shell runs it.
+				// chose. Windows has no `sh`, so there the host's own shell runs it: Git Bash
+				// when installed, cmd.exe when not.
 				...(process.platform === 'win32'
 					? {}
 					: { shell: { path: 'sh', dialect: 'sh', source: 'sh' } as const }),

package/src/process/kill-tree.ts

@@ -1,6 +1,47 @@
 import { execFileSync } from 'node:child_process'
 import type { spawn } from 'node:child_process'
 
+/**
+ * Git Bash children that the Windows process tree cannot reach.
+ *
+ * Git for Windows' msys runtime starts a command that is not the last of its
+ * line by `fork`, and the process that forked is gone by the time the command
+ * runs: the command's Windows parent no longer exists, so `taskkill /T` walks
+ * from the shell to its child and never finds the grandchild (`sleep 60; echo`,
+ * `cd app && npm start & wait`). Each such shell is started with a unique tag
+ * in its environment, which every descendant inherits however it was started;
+ * the tag is how the tree is found again.
+ */
+const MSYS_SHELLS = new WeakMap<object, { readonly bash: string; readonly tag: string }>()
+
+/** Remember how to find every process a Git Bash child started. Called by the spawn. */
+export function registerMsysShell(child: object, shell: { bash: string; tag: string }): void {
+	MSYS_SHELLS.set(child, shell)
+}
+
+/** The environment variable that carries the tag. */
+export const MSYS_TAG_VARIABLE = 'NAMZU_SHELL_TAG'
+
+/** Kill every process whose environment carries the tag, from inside the msys runtime. */
+function killMsysTagged(shell: { readonly bash: string; readonly tag: string }): void {
+	// `$$` is skipped so the killer cannot end itself. Parameter expansion keeps
+	// the script to the two programs (grep, kill) the launcher puts on PATH.
+	const script = [
+		`for f in $(grep -laF "${MSYS_TAG_VARIABLE}=${shell.tag}" /proc/[0-9]*/environ 2>/dev/null); do`,
+		'p=${f#/proc/}; p=${p%/environ}; [ "$p" != "$$" ] && kill -9 $p;',
+		'done',
+	].join(' ')
+	try {
+		execFileSync(shell.bash, ['-c', script], {
+			stdio: 'ignore',
+			windowsHide: true,
+			timeout: 5000,
+		})
+	} catch {
+		// Nothing tagged was left, or the runtime could not start: taskkill still runs.
+	}
+}
+
 /** The system's own taskkill, so a PATH entry cannot stand in for it. */
 function taskkillPath(): string {
 	const root = process.env.SystemRoot ?? process.env.windir
@@ -46,6 +87,8 @@ export function killTree(child: ReturnType<typeof spawn>, signal: NodeJS.Signals
 	if (!child.pid) return
 	try {
 		if (process.platform === 'win32') {
+			const msys = MSYS_SHELLS.get(child)
+			if (msys !== undefined) killMsysTagged(msys)
 			execFileSync(taskkillPath(), ['/pid', String(child.pid), '/t', '/f'], {
 				stdio: 'ignore',
 				windowsHide: true,

package/src/provider/strict-schema.ts

@@ -157,6 +157,37 @@ export function findStrictSchemaViolations(schema: unknown, path = ''): StrictSc
 			})
 			continue
 		}
+		// Every branch of a union has to state its `type`.
+		//
+		// `anyOf` is in the subset but its BRANCHES are still schemas, and a
+		// branch that says only `{ const: 'end' }` says what value it admits
+		// without saying what kind of value it is. Measured on the Zen
+		// free-tier gateway, which enforces `strict` on every model that
+		// reaches it: the answer is `Invalid schema for function 'edit': In
+		// context=('properties', 'insertLine', 'anyOf', '1'), schema must have
+		// a 'type' key`, and it refuses the whole request — so the tool never
+		// mounts and the turn dies before a single token.
+		//
+		// This is the structural half the deny-list could not see: no keyword
+		// here is banned, only absent. Stating the type costs nothing, because
+		// `{ type: 'string', const: 'end' }` admits exactly the strings the
+		// bare form did.
+		if ((keyword === 'anyOf' || keyword === 'allOf') && Array.isArray(value)) {
+			for (const [index, branch] of value.entries()) {
+				if (
+					typeof branch !== 'object' ||
+					branch === null ||
+					Array.isArray(branch) ||
+					!('type' in branch)
+				) {
+					found.push({
+						path: `${here}[${index}]`,
+						keyword,
+						remedy: 'state a `type` on every branch of a union',
+					})
+				}
+			}
+		}
 		found.push(...findStrictSchemaViolations(value, here))
 	}
 	return found
@@ -180,3 +211,62 @@ export function assertStrictSchema(toolName: string, schema: unknown): void {
 		`Tool "${toolName}" is marked for strict input validation, but its model-facing schema uses ${violations.length} construct(s) the strict subset does not accept. The request would be rejected whole, taking every other tool in it down as well.\n${detail}`,
 	)
 }
+
+/**
+ * Whether a wire enforcing `strict` would actually take this schema.
+ *
+ * Wider than {@link findStrictSchemaViolations}, and the difference is not
+ * redundancy. That function answers "can this schema be SAID in the strict
+ * dialect" — it denies keywords the dialect has no spelling for, and it is
+ * what registration checks, because a schema that fails it could never be
+ * sent anywhere. A schema can pass it and still be REFUSED by a wire that
+ * applies the dialect's structural rules on top, and the two questions have
+ * different owners: registration decides whether a tool may ask for the
+ * guarantee at all, a driver decides whether to claim it on THIS wire.
+ *
+ * The structural rule measured here: every object that declares `properties`
+ * must list all of them in `required`. The Zen free-tier gateway says so in
+ * as many words — `In context=('properties', 'edits', 'items'), 'required' is
+ * required to be supplied and to be an array including every key in
+ * properties` — and it refuses the WHOLE request, so one optional field in one
+ * tool takes every other tool in the call down with it.
+ *
+ * That is why a driver must ask rather than assume. Namzu's tool contracts are
+ * written with optional fields, on purpose: `edit` accepts a find-and-replace
+ * OR an insertion, and saying "either, never both" as `required` on a union
+ * would be a worse schema, not a stricter one. So the schema stays as it is
+ * and the driver stops vouching for a guarantee the wire cannot carry — the
+ * same call the Zen driver already makes for the Responses wire, and the one
+ * OpenCode makes for every tool on this gateway (`strict: false`).
+ */
+export function acceptsStrictSchema(schema: unknown): boolean {
+	// A missing schema cannot be vouched for. `findStrictSchemaViolations`
+	// walks nothing in `undefined` and finds nothing, so without this the
+	// predicate would answer `true` for a tool that declared no schema at all
+	// — and the driver would put `strict: true` on a wire whose `parameters`
+	// came from somewhere else entirely.
+	if (typeof schema !== 'object' || schema === null || Array.isArray(schema)) return false
+	if (findStrictSchemaViolations(schema).length > 0) return false
+	return !hasUngatedProperties(schema)
+}
+
+/**
+ * Whether any object declares `properties` without requiring all of them.
+ */
+function hasUngatedProperties(node: unknown): boolean {
+	if (Array.isArray(node)) return node.some((item) => hasUngatedProperties(item))
+	if (typeof node !== 'object' || node === null) return false
+
+	const record = node as Record<string, unknown>
+	const properties = record.properties
+	if (
+		typeof properties === 'object' &&
+		properties !== null &&
+		!Array.isArray(properties) &&
+		(!Array.isArray(record.required) ||
+			Object.keys(properties).some((key) => !(record.required as unknown[]).includes(key)))
+	)
+		return true
+
+	return Object.values(record).some((value) => hasUngatedProperties(value))
+}

package/src/provider/token-budget.ts

@@ -1,8 +1,10 @@
+import { estimateMessagesTokens } from '../compaction/token-estimate.js'
 import { EMPTY_TOKEN_USAGE } from '../constants/limits.js'
 import type { SessionTokenBudget } from '../store/budget/ledger.js'
 import { type TokenUsage, mergeTokenUsage } from '../types/common/index.js'
 import { ProviderError, classifyProviderError } from '../types/provider/errors.js'
 import type { LLMProvider, StreamChunk } from '../types/provider/index.js'
+import { cancelCauseOf } from '../types/session/cancel-cause.js'
 import { isProviderRequestError } from './errors.js'
 
 export class TokenBudgetAdmissionError extends ProviderError {
@@ -49,6 +51,7 @@ export function withTokenBudget(provider: LLMProvider, budget: SessionTokenBudge
 		let completed = false
 		let outputObserved = false
 		let uncertainRetry = false
+		let streamedChars = 0
 		let contacted = false
 		let abandoned = false
 		let iterator: AsyncIterator<StreamChunk> | undefined
@@ -107,6 +110,7 @@ export function withTokenBudget(provider: LLMProvider, budget: SessionTokenBudge
 					})
 				}
 				if (Object.keys(chunk.delta).length > 0) outputObserved = true
+				if (typeof chunk.delta.content === 'string') streamedChars += chunk.delta.content.length
 				if (chunk.error) throw new Error(chunk.error)
 				yield chunk
 			}
@@ -142,7 +146,33 @@ export function withTokenBudget(provider: LLMProvider, budget: SessionTokenBudge
 			} catch {
 				// Cleanup cannot replace the provider outcome.
 			}
-			if (!completed) await budget.failRequest(requestId, usage)
+			if (!completed) {
+				// A request the operator deliberately cancelled (a `user` cancel cause,
+				// not a parent or a runtime tearing the tree down) before any usage frame
+				// arrived is closed on an estimate (the prompt and what streamed), not
+				// left as unknown spend. Left open it poisons the whole tree: every
+				// sibling and every later child is refused for the rest of the turn,
+				// because of work somebody chose to stop. The estimate can under-count
+				// what the provider billed for the part it never reported; a failure
+				// that was not a cancellation keeps its marker as before.
+				if (
+					usage === undefined &&
+					signal?.aborted === true &&
+					cancelCauseOf(signal.reason) === 'user' &&
+					!uncertainRetry
+				) {
+					const prompt = estimateMessagesTokens(params.messages)
+					const completion = Math.ceil(streamedChars / 4)
+					await budget.finishRequest(requestId, {
+						...EMPTY_TOKEN_USAGE,
+						promptTokens: prompt,
+						completionTokens: completion,
+						totalTokens: prompt + completion,
+					})
+				} else {
+					await budget.failRequest(requestId, usage)
+				}
+			}
 		}
 	}