@namzu/sdk 50.1.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/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)
+				}
+			}
 		}
 	}
 

package/src/public-runtime.ts

@@ -20,6 +20,17 @@ export { BackgroundJobOutputWaitLimitError } from './runtime/jobs/registry.js'
 export { HostCallDeniedError } from './execution/code-runtime/types.js'
 export { WorkerCodeRuntime } from './execution/code-runtime/worker.js'
 
+// The workflow runtime: runs a model-authored orchestration script on the
+// interpreter above, with `agent()` as its only host call.
+export {
+	FileWorkflowJournal,
+	parseWorkflowMeta,
+	resolveWorkflowLimits,
+	summarizeWorkflowPhases,
+	WorkflowRuntime,
+	WorkflowScriptError,
+} from './execution/workflow/index.js'
+
 export {
 	CompactionConfigSchema,
 	PluginRuntimeConfigSchema,

package/src/public-tools.ts

@@ -54,9 +54,15 @@ export { builtinCommandArguments, commandArgumentOf } from './tools/command-argu
 export {
 	type CommandShell,
 	type CommandShellProbe,
+	WINDOWS_BASH_GUIDANCE,
+	WINDOWS_CMD_FALLBACK_NOTICE,
 	findCommandShell,
 	findCommandShellForDialect,
+	findGitBash,
 	hostCommandShell,
+	isWindowsBash,
+	rewriteWindowsNullRedirect,
+	windowsShellNotice,
 	describeSpawnFailure,
 	hostShellSpawn,
 	installedCommandShellForDialect,

package/src/public-types.ts

@@ -32,6 +32,9 @@ export type { CoalesceOptions } from './streaming/coalesce.js'
 export type * from './types/bidi/index.js'
 export type * from './types/tool/index.js'
 export type * from './types/job/index.js'
+export type * from './execution/workflow/types.js'
+export type { PhaseAgentView, PhaseRecord } from './execution/workflow/phases.js'
+export type { WorkflowRuntimeOptions } from './execution/workflow/runtime.js'
 export type { WorkerCodeRuntimeOptions } from './execution/code-runtime/worker.js'
 export type {
 	CodeRunOutcome,

package/src/runtime/jobs/job-id.ts

@@ -0,0 +1,66 @@
+import { randomBytes } from 'node:crypto'
+
+/**
+ * Background job ids: `b` and eight characters of `0-9a-z`.
+ *
+ * Random rather than counted. A counter restarts with every registry, so a
+ * resumed conversation that still says `job_1` about a dead job would be
+ * answered by whatever job happens to be `job_1` in the new session. A random
+ * id from a space of 36^8 does not collide across sessions in practice, and
+ * the registry additionally never hands out one it already holds.
+ *
+ * Ids are opaque to callers: nothing may parse them or rely on the shape.
+ */
+const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz'
+const ID_BODY_LENGTH = 8
+const ID_PATTERN = /^b[0-9a-z]{8}$/
+
+/**
+ * Whether `id` looks like one this SDK minted (`b` + 8 base36 characters).
+ * A helper only: the tools do not gate on it, because a host's own registry
+ * may use other ids. Ids are opaque; a host must not parse them.
+ */
+export function isBackgroundJobId(id: unknown): id is string {
+	return typeof id === 'string' && ID_PATTERN.test(id)
+}
+
+/**
+ * A fresh id. Bytes are mapped onto the alphabet by rejection so every
+ * character is uniform (256 is not a multiple of 36).
+ */
+export function createBackgroundJobId(isTaken: (id: string) => boolean = () => false): string {
+	for (;;) {
+		let body = ''
+		while (body.length < ID_BODY_LENGTH) {
+			for (const byte of randomBytes(ID_BODY_LENGTH * 2)) {
+				if (byte >= 252) continue // 252 = 36 * 7
+				body += ALPHABET[byte % 36]
+				if (body.length === ID_BODY_LENGTH) break
+			}
+		}
+		const id = `b${body}`
+		if (!isTaken(id)) return id
+	}
+}
+
+const MAX_JOB_ID_INPUT_LENGTH = 128
+
+/**
+ * The tools' only gate on an id a caller passes in. A host may supply its own
+ * registry with its own id format, so shape is NOT checked here: anything that
+ * is a sane single token goes on to the registry, whose "No background job
+ * <id>." answers for an unknown one. Returns a plain refusal for input that
+ * cannot be an id at all (not a string, empty, over 128 characters, or
+ * containing whitespace or control characters), otherwise undefined.
+ */
+export function invalidBackgroundJobIdInput(id: unknown): string | undefined {
+	if (typeof id !== 'string' || id.length === 0) return 'A background job id is required.'
+	if (id.length > MAX_JOB_ID_INPUT_LENGTH) {
+		return `That is not a background job id: it is longer than ${MAX_JOB_ID_INPUT_LENGTH} characters.`
+	}
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: rejecting control characters is the point.
+	if (/[\s\u0000-\u001f\u007f-\u009f]/u.test(id)) {
+		return 'That is not a background job id: ids contain no spaces or control characters.'
+	}
+	return undefined
+}