@namzu/sdk 58.1.1 → 60.0.0

package/src/execution/workflow/types.ts

@@ -53,6 +53,8 @@ export interface WorkflowAgentOutcome {
 	readonly tokens: number
 	readonly toolCalls: number
 	readonly error?: string
+	/** The id of the child session the host ran this agent in, recorded in the journal. */
+	readonly sessionId?: string
 }
 
 /**
@@ -113,6 +115,8 @@ export interface WorkflowAgentEvent {
 	readonly resultPreview?: string
 	readonly error?: string
 	readonly skipped?: boolean
+	/** True when the agent did not run: a resumed run returned the result it saved earlier. */
+	readonly cached?: boolean
 }
 
 export interface WorkflowLogEvent {
@@ -133,6 +137,8 @@ export interface WorkflowUsage {
 	readonly tokens: number
 	readonly toolCalls: number
 	readonly elapsedMs: number
+	/** Agents that returned a result saved by an earlier pass instead of running (a subset of `agentsDone`). */
+	readonly cachedAgents?: number
 }
 
 export interface WorkflowFinishedEvent {
@@ -177,6 +183,14 @@ export type WorkflowJournalRecord =
 			readonly meta: WorkflowMeta
 			readonly args: unknown
 			readonly limits: WorkflowResolvedLimits
+			/** Present on every pass after the first; a resumed run keeps its run id and journal. */
+			readonly resume?: {
+				readonly pass: number
+				readonly previousFinish: WorkflowFinishStatus | 'unfinished'
+				readonly scriptSha256Changed: boolean
+			}
+			/** Where the script came from when the host read it from a file. */
+			readonly scriptPath?: string
 	  }
 	| {
 			readonly type: 'phase'
@@ -200,6 +214,12 @@ export type WorkflowJournalRecord =
 				readonly effort?: string
 				readonly schema: boolean
 			}
+			/** Identifies the call across passes; see `workflowCallKey`. */
+			readonly key?: string
+			/** 1 for the first pass. A record from an older pass than the latest `run_started` is stale. */
+			readonly pass?: number
+			/** The agent did not run; its result came from an earlier pass. */
+			readonly cached?: true
 	  }
 	| {
 			readonly type: 'agent_outcome'
@@ -213,6 +233,18 @@ export type WorkflowJournalRecord =
 			readonly finishedAt: number
 			readonly resultPreview?: string
 			readonly error?: string
+			readonly key?: string
+			readonly pass?: number
+			readonly cached?: true
+			/** The agent's full value (after schema validation); present only for a finished, non-null result. */
+			readonly result?: unknown
+			/** A value existed but could not be saved; a resume runs this agent again. */
+			readonly unsaved?: true
+			/** The run or the agent was stopped before the agent finished; a resume runs it again and keeps its saved results valid. */
+			readonly interrupted?: true
+			/** Where a cached result was first recorded. */
+			readonly resultFrom?: { readonly pass: number; readonly index: number }
+			readonly childSessionId?: string
 	  }
 	| { readonly type: 'log'; readonly at: number; readonly message: string }
 	| {
@@ -222,12 +254,14 @@ export type WorkflowJournalRecord =
 			readonly result?: unknown
 			readonly error?: string
 			readonly usage: WorkflowUsage
+			/** Written by a later session for a run whose process ended without finishing it. */
+			readonly recovered?: true
 	  }
 
 /** 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
+	writeScript?(source: string, sha256: string, pass?: number): Promise<void> | void
 	append(record: WorkflowJournalRecord): Promise<void> | void
 }
 
@@ -283,6 +317,80 @@ export interface WorkflowRunOptions {
 	readonly onControl?: (control: WorkflowControl) => void
 	/** Default: a fresh `w` + 8 base36 id. */
 	readonly runId?: string
+	/**
+	 * Continue an earlier run: agents whose prompt and options are unchanged
+	 * return the result saved in the journal instead of running. Build it with
+	 * `loadWorkflowResume`, and pass the same `runId`.
+	 */
+	readonly resume?: WorkflowResumeState
+	/**
+	 * Make the script repeatable, which resuming needs: `Date.now()`,
+	 * `new Date()` with no argument and `Math.random()` throw, and `eval` is
+	 * removed. Default false.
+	 */
+	readonly deterministic?: boolean
+	/** Say in a failure that the run can be resumed. Default false. */
+	readonly canResume?: boolean
+	/** Recorded in `run_started` when the host read the script from a file. */
+	readonly scriptPath?: string
+}
+
+/** Everything a resumed pass needs from the earlier passes of one run. */
+export interface WorkflowResumeState {
+	/** The number of the pass about to run (2 for the first resume). */
+	readonly pass: number
+	readonly results: ReadonlyMap<
+		string,
+		{
+			readonly value: unknown
+			readonly pass: number
+			readonly index: number
+			readonly childSessionId?: string
+		}
+	>
+	/** Keys the earlier passes asked for, finished or not. */
+	readonly seen: ReadonlySet<string>
+	/** Keys whose last outcome was a failure or a skip. */
+	readonly failed: ReadonlySet<string>
+	/** Keys that were asked for again after a result was saved and never finished since. */
+	readonly demoted: ReadonlySet<string>
+	readonly scriptSha256?: string
+	readonly previousFinish: WorkflowFinishStatus | 'unfinished'
+	/** Plain-language findings about the journal (changed, cut short, saved before resuming existed). */
+	readonly problems: readonly string[]
+	readonly resumable: boolean
+	/** First line (1-based) the integrity check could not trust, when any. */
+	readonly brokenAt?: number
+}
+
+/** A journal that can be read back, with its integrity checked. */
+export interface WorkflowJournalReader {
+	read(): Promise<CheckedWorkflowJournal>
+}
+
+/** A journal record as written by `FileWorkflowJournal`: numbered and chained to the line before it. */
+export type ChainedWorkflowJournalRecord = WorkflowJournalRecord & {
+	readonly seq: number
+	readonly prev: string
+}
+
+/** What reading a journal found. Only `records` can be trusted. */
+export interface CheckedWorkflowJournal {
+	/** Records that passed the integrity check, in order. */
+	readonly records: readonly ChainedWorkflowJournalRecord[]
+	/** The journal was written before records were chained; it can be shown but not resumed. */
+	readonly legacy: boolean
+	/** The last write was cut off mid-line and was ignored. */
+	readonly tornTail: boolean
+	/** First line (1-based) that failed the check, when lines were changed, removed or cut short. */
+	readonly brokenAt?: number
+	/** Sequence number and hash the next record must chain from. */
+	readonly lastSeq: number
+	readonly lastHash: string
+	/** The file ends in a newline (false after a torn write). */
+	readonly endsWithNewline: boolean
+	/** Records of a legacy journal, for display only. */
+	readonly untrusted: readonly WorkflowJournalRecord[]
 }
 
 export interface WorkflowRunResult {

package/src/index.ts

@@ -41,10 +41,27 @@ export type {
 	MonitorStreamOptions,
 	MonitorStreamStats,
 } from './runtime/jobs/monitor-stream.js'
+export { WakeBudget, wakeBudgetFromEnv } from './runtime/jobs/wake-budget.js'
 export {
 	createBackgroundJobId,
 	isBackgroundJobId,
 } from './runtime/jobs/job-id.js'
+// Three facts about a running item (where it is, when it last progressed,
+// whether it is alive) and the one verdict derived from them.
+export {
+	LIVENESS_QUIET_MS,
+	LIVENESS_STALLED_MS,
+	formatLivenessAge,
+	formatLivenessLine,
+	judgeLiveness,
+} from './runtime/jobs/liveness.js'
+export type {
+	Liveness,
+	LivenessInput,
+	LivenessKind,
+	LivenessThresholds,
+	LivenessVerdict,
+} from './runtime/jobs/liveness.js'
 export type {
 	BackgroundJob,
 	ForegroundCommand,

package/src/peers/record.ts

@@ -43,9 +43,27 @@ export const PeerRecordSchema = z
 		token: z.string().min(1),
 		protocol: z.literal(PEER_PROTOCOL_VERSION),
 		cliVersion: z.string(),
+		/** The slot a spaces host gave this terminal at launch; how the host finds its own sessions. */
+		hostSlot: z.string().min(1).max(128).optional(),
+		/** The conversation this terminal is on, once it has one. */
+		conversationId: z.string().min(1).optional(),
+		/** The label of the non-default account the conversation is bound to; absent for the default. */
+		account: z.string().min(1).optional(),
+		/** True while the bound account is out of allowance and the terminal is waiting for a choice. */
+		limited: z.boolean().optional(),
+		/** When the allowance is expected back (epoch ms); absent when the provider did not say. */
+		limitedUntil: z.number().int().positive().optional(),
 	})
 	.strict()
 
+/**
+ * The reader's view of a record: the same fields, but a key this build does
+ * not know is dropped instead of failing the whole record. A record written by
+ * a newer build (extra optional fields) stays visible to an older reader.
+ * Writers keep using the strict `PeerRecordSchema`.
+ */
+export const PeerRecordReaderSchema = PeerRecordSchema.strip()
+
 export type PeerRecord = z.infer<typeof PeerRecordSchema>
 
 const PEER_REF_HEX_LENGTH = 6

package/src/peers/registry.ts

@@ -20,7 +20,7 @@ import {
 import { basename, dirname, join } from 'node:path'
 import { parsePeerAddress } from './address.js'
 import { pingPeer } from './client.js'
-import { type PeerRecord, PeerRecordSchema } from './record.js'
+import { type PeerRecord, PeerRecordReaderSchema, PeerRecordSchema } from './record.js'
 
 const RECORD_FILE_MODE = 0o600
 
@@ -75,7 +75,7 @@ function parseRecordText(text: string): PeerRecord | undefined {
 	} catch {
 		return undefined
 	}
-	const result = PeerRecordSchema.safeParse(parsed)
+	const result = PeerRecordReaderSchema.safeParse(parsed)
 	return result.success ? result.data : undefined
 }
 

package/src/plugin/compat.ts

@@ -0,0 +1,173 @@
+import type { PluginManifest } from '../types/plugin/index.js'
+
+/**
+ * Whether a plugin can run on this machine and this runtime, decided from what
+ * its manifest declares. A manifest that declares nothing is compatible with
+ * everything, so every plugin written before these fields existed loads as it did.
+ */
+
+type Triple = readonly [number, number, number]
+
+interface Parsed {
+	readonly triple: Triple
+	/** The prerelease tag (`rc.1`), or undefined for a release. */
+	readonly pre: string | undefined
+	/** How many numeric parts were written: `1` is 1, `1.4` is 2, `1.4.2` is 3. */
+	readonly written: number
+}
+
+const VERSION_PATTERN =
+	/^v?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?(?:-([0-9A-Za-z.-]+))?(?:\+.*)?$/i
+
+function parseVersion(text: string): Parsed | undefined {
+	const match = VERSION_PATTERN.exec(text.trim())
+	if (!match) return undefined
+	const part = (value: string | undefined): number =>
+		value === undefined || value === 'x' || value === '*' ? 0 : Number(value)
+	const written = [match[1], match[2], match[3]].filter(
+		(p) => p !== undefined && p !== 'x' && p !== '*',
+	).length
+	return {
+		triple: [Number(match[1]), part(match[2]), part(match[3])],
+		pre: match[4],
+		written,
+	}
+}
+
+function compareTriples(a: Triple, b: Triple): number {
+	for (let i = 0; i < 3; i++) {
+		const diff = (a[i] as number) - (b[i] as number)
+		if (diff !== 0) return diff
+	}
+	return 0
+}
+
+/** Full precedence: a release is above any prerelease of the same numbers. */
+function compare(a: Parsed, b: Parsed): number {
+	const order = compareTriples(a.triple, b.triple)
+	if (order !== 0) return order
+	if (a.pre === b.pre) return 0
+	if (a.pre === undefined) return 1
+	if (b.pre === undefined) return -1
+	return a.pre < b.pre ? -1 : 1
+}
+
+/**
+ * The first version a `^` or `~` range excludes, from how many parts were
+ * written. `^1` and `~1` stop below 2.0.0; `~1.4` and `~1.4.2` below 1.5.0;
+ * `^0` below 1.0.0, `^0.2` below 0.3.0, `^0.0.3` below 0.0.4.
+ */
+function upperBound(operator: '^' | '~', target: Parsed): Triple {
+	const [major, minor, patch] = target.triple
+	if (operator === '~') return target.written <= 1 ? [major + 1, 0, 0] : [major, minor + 1, 0]
+	if (major > 0 || target.written <= 1) return [major + 1, 0, 0]
+	if (minor > 0 || target.written === 2) return [0, minor + 1, 0]
+	return [0, 0, patch + 1]
+}
+
+/** One comparator such as `>=1.2.0`, `^2`, `~1.4` or `3.1.0`; undefined when unreadable. */
+function satisfiesComparator(version: Parsed, token: string): boolean | undefined {
+	const op = /^(>=|<=|>|<|=|\^|~)?\s*(.+)$/.exec(token)
+	if (!op) return undefined
+	const operator = op[1] ?? '='
+	const target = parseVersion(op[2] as string)
+	if (!target) return undefined
+	const order = compare(version, target)
+	switch (operator) {
+		case '>=':
+			return order >= 0
+		case '<=':
+			return order <= 0
+		case '>':
+			return order > 0
+		case '<':
+			return order < 0
+		case '^':
+		case '~':
+			// The upper bound is compared on the numbers alone, so a prerelease of the
+			// next major (`2.0.0-rc.1`) is not inside `^1`.
+			return order >= 0 && compareTriples(version.triple, upperBound(operator, target)) < 0
+		default: {
+			// A bare `1` or `1.4` names a whole major or minor.
+			if (version.pre !== target.pre) return false
+			const written = (op[2] as string).replace(/^v/i, '').split(/[-+]/)[0] as string
+			const parts = written.split('.').filter((p) => p !== 'x' && p !== '*')
+			return parts.every((p, i) => Number(p) === version.triple[i])
+		}
+	}
+}
+
+/**
+ * Whether `version` satisfies `range`. Supports space-separated comparators
+ * that must all hold, `||` between alternatives, and the operators `>=`, `>`,
+ * `<=`, `<`, `=`, `^` and `~`. Returns undefined when the range cannot be read.
+ */
+export function versionSatisfies(versionText: string, range: string): boolean | undefined {
+	const version = parseVersion(versionText)
+	if (!version) return undefined
+	let readable = true
+	let any = false
+	for (const alternative of range.split('||')) {
+		// Join an operator written apart from its number (">= 1.2") first.
+		const tokens = alternative
+			.trim()
+			.replace(/(>=|<=|>|<|=|\^|~)\s+/g, '$1')
+			.split(/\s+/)
+			.filter(Boolean)
+		if (tokens.length === 0) {
+			readable = false
+			continue
+		}
+		let all = true
+		for (const token of tokens) {
+			const ok = satisfiesComparator(version, token)
+			if (ok === undefined) {
+				readable = false
+				all = false
+				break
+			}
+			if (!ok) all = false
+		}
+		if (all) any = true
+	}
+	if (any) return true
+	return readable ? false : undefined
+}
+
+export interface PluginHostFacts {
+	/** The operating system, as `process.platform` names it. Default: this process. */
+	readonly platform?: string
+	/** The Namzu runtime version. Default: this package's own version. */
+	readonly namzuVersion?: string
+}
+
+/**
+ * Refuse a plugin that declares it does not support this platform or this
+ * Namzu version. The reason names the plugin, what it declares and what this
+ * machine is, so a person can act on it without reading the manifest.
+ *
+ * A runtime whose own version is unknown (`0.0.0`, the placeholder a bundle
+ * reports when it cannot read its package file) is not held against the range:
+ * refusing every plugin on a guess would be worse than admitting one.
+ */
+export function assertCompatible(manifest: PluginManifest, host: Required<PluginHostFacts>): void {
+	const platforms = manifest.platforms
+	if (platforms && platforms.length > 0 && !platforms.includes(host.platform)) {
+		throw new Error(
+			`Plugin "${manifest.name}" supports only ${platforms.join(', ')}, and this machine runs ${host.platform}, so it was not loaded.`,
+		)
+	}
+	const range = manifest.engines?.namzu
+	if (range === undefined || host.namzuVersion === '0.0.0') return
+	const ok = versionSatisfies(host.namzuVersion, range)
+	if (ok === undefined) {
+		throw new Error(
+			`Plugin "${manifest.name}" declares the Namzu version range "${range}", which cannot be read, so it was not loaded. Write it like ">=60.0.0" or "^60.1.0".`,
+		)
+	}
+	if (!ok) {
+		throw new Error(
+			`Plugin "${manifest.name}" needs Namzu ${range}, and this is Namzu ${host.namzuVersion}, so it was not loaded. Update Namzu or use a plugin version made for this one.`,
+		)
+	}
+}

package/src/plugin/loader.ts

@@ -11,6 +11,8 @@ import { type PluginManifest, PluginManifestSchema } from '../types/plugin/index
 import { toErrorMessage } from '../utils/error.js'
 import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 import { type Logger, resolveLogger } from '../utils/logger.js'
+import { VERSION } from '../version.js'
+import { type PluginHostFacts, assertCompatible } from './compat.js'
 
 /**
  * Scans a directory for subdirectories containing a plugin manifest.
@@ -161,7 +163,7 @@ const REGISTRY_BACKED_CONTRIBUTIONS = ['skills'] as const
  * through host configuration; what does not exist is the manifest path
  * into them. Naming the types is what makes that actionable.
  */
-export interface PluginEnablementCapabilities {
+export interface PluginEnablementCapabilities extends PluginHostFacts {
 	/**
 	 * Whether the host wired a `SkillRegistry`.
 	 *
@@ -178,6 +180,10 @@ export function assertEnableable(
 	manifest: PluginManifest,
 	capabilities: PluginEnablementCapabilities = {},
 ): void {
+	assertCompatible(manifest, {
+		platform: capabilities.platform ?? platform(),
+		namzuVersion: capabilities.namzuVersion ?? VERSION,
+	})
 	const record = manifest as unknown as Record<string, unknown[] | undefined>
 	// One ordered pass over all three rather than two group filters
 	// concatenated, so the message keeps naming them in the order the

package/src/pricing/index.ts

@@ -14,6 +14,7 @@
  * than refreshed, and `rates.source.json` for the rates themselves.
  */
 
+import { stripModelWindowSuffix } from '../compaction/context-window.js'
 import type { ModelPricing } from '../utils/cost.js'
 import { VENDOR_RATES } from './catalogue.generated.js'
 
@@ -35,7 +36,7 @@ const SNAPSHOT_SUFFIX = /[-@]\d{8}$/
 
 /** Lowercase, snapshot suffix removed. Exported because tests assert it. */
 export function normaliseModelId(model: string): string {
-	return model.toLowerCase().replace(SNAPSHOT_SUFFIX, '')
+	return stripModelWindowSuffix(model).toLowerCase().replace(SNAPSHOT_SUFFIX, '')
 }
 
 /**

package/src/process/kill-tree.ts

@@ -1,4 +1,5 @@
 import { execFileSync } from 'node:child_process'
+import { readFileSync, readdirSync } from 'node:fs'
 
 /**
  * Git Bash children that the Windows process tree cannot reach.
@@ -11,13 +12,82 @@ import { execFileSync } from 'node:child_process'
  * 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 }>()
+const MSYS_SHELLS = new WeakMap<object, { readonly bash?: string; readonly tag: string }>()
+
+/**
+ * Whether a pid may be signalled, or addressed as a group with `-pid`.
+ *
+ * `kill(-1, sig)` signals every process the user may signal and `kill(0, sig)`
+ * signals the caller's own process group, so a recorded pid of 1, 0, a negative
+ * or a fractional number (a test double, a corrupt record, `NaN`) would take
+ * down the host's whole session. Only an integer above 1 that is not this
+ * process is a real, separate process. A refused pid is treated as already gone.
+ */
+export function isSignalablePid(pid: unknown): pid is number {
+	return typeof pid === 'number' && Number.isInteger(pid) && pid > 1 && pid !== process.pid
+}
 
 /** 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)
 }
 
+/**
+ * Remember the tag a POSIX child's environment carries, so a kill can also find
+ * a descendant that left the child's process group (`setsid`, a double fork
+ * that starts its own session). Such a process has no group to signal, but it
+ * inherited the environment, and the tag is how it is found again.
+ *
+ * The limit is the same as the group's own: a process that clears its
+ * environment before it forks escapes this too.
+ */
+export function registerProcessTag(child: object, tag: string): void {
+	MSYS_SHELLS.set(child, { tag })
+}
+
+/**
+ * Signal every process of this user whose environment carries one of the tags,
+ * by reading `/proc/<pid>/environ`. Linux only: other POSIX systems have no
+ * `/proc`, and there the process group is all a kill can reach. A process whose
+ * environment cannot be read (another user's, or one that has just ended) is
+ * skipped without further work.
+ *
+ * Several tags are looked for in one pass, so stopping many jobs at once reads
+ * each environment once, not once per job. The scan is synchronous and its cost
+ * grows with the number of processes on the machine. There is also a window
+ * between reading an environment and signalling its pid in which the pid could
+ * be reused by an unrelated process of the same user; the window is the length
+ * of one read, and the signal goes only to a pid whose environment carried the
+ * tag a moment before.
+ */
+export function signalTagged(tags: string | readonly string[], signal: NodeJS.Signals): number {
+	const needles = (typeof tags === 'string' ? [tags] : tags).map(
+		(tag) => `${MSYS_TAG_VARIABLE}=${tag}\0`,
+	)
+	if (needles.length === 0) return 0
+	let entries: string[]
+	try {
+		entries = readdirSync('/proc')
+	} catch {
+		return 0
+	}
+	let signalled = 0
+	for (const entry of entries) {
+		if (!/^\d+$/.test(entry)) continue
+		const pid = Number(entry)
+		if (!isSignalablePid(pid)) continue
+		try {
+			const environ = readFileSync(`/proc/${entry}/environ`, 'latin1')
+			if (!needles.some((needle) => environ.includes(needle))) continue
+			process.kill(pid, signal)
+			signalled++
+		} catch {
+			// Not ours to read, or gone since the listing.
+		}
+	}
+	return signalled
+}
+
 /** The environment variable that carries the tag. */
 export const MSYS_TAG_VARIABLE = 'NAMZU_SHELL_TAG'
 
@@ -86,17 +156,49 @@ export function killTree(
 	child: { readonly pid?: number | undefined },
 	signal: NodeJS.Signals,
 ): void {
-	if (!child.pid) return
+	killTrees([child], signal)
+}
+
+/**
+ * `killTree` for several children at once: each child's group is signalled, then
+ * the environment scan runs once for all their tags. Used where the number of
+ * kills is unbounded and cannot wait, such as the host's exit.
+ */
+export function killTrees(
+	children: readonly { readonly pid?: number | undefined }[],
+	signal: NodeJS.Signals,
+): void {
+	const tags: string[] = []
+	for (const child of children) {
+		if (!isSignalablePid(child.pid)) continue
+		killOne(child, signal, tags)
+	}
+	if (tags.length > 0 && process.platform === 'linux') signalTagged(tags, signal)
+}
+
+function killOne(
+	child: { readonly pid?: number | undefined },
+	signal: NodeJS.Signals,
+	tags: string[],
+): void {
+	if (!isSignalablePid(child.pid)) return
 	try {
 		if (process.platform === 'win32') {
 			const msys = MSYS_SHELLS.get(child)
-			if (msys !== undefined) killMsysTagged(msys)
+			if (msys?.bash !== undefined) killMsysTagged({ bash: msys.bash, tag: msys.tag })
 			execFileSync(taskkillPath(), ['/pid', String(child.pid), '/t', '/f'], {
 				stdio: 'ignore',
 				windowsHide: true,
 			})
 		} else {
-			process.kill(-child.pid, signal)
+			try {
+				process.kill(-child.pid, signal)
+			} finally {
+				// After the group, which is cheap and exact: what is left is only
+				// what started its own session. Also when the group is already gone.
+				const tagged = MSYS_SHELLS.get(child)
+				if (tagged !== undefined) tags.push(tagged.tag)
+			}
 		}
 	} catch {
 		// Group (or tree) already gone

package/src/prompt/coding-agent-doctrine.ts

@@ -82,7 +82,15 @@ export const CODING_AGENT_DELEGATION_DOCTRINE = `### Planning and delegating
 - When the \`Agent\` tool is available, delegate independent work through it and give each delegation a short, specific description; the user watches those descriptions, not the prompts. Brief each sub-agent with four things: the objective; what is out of bounds; which tools and sources to use; and the shape of the reply you want, such as a short summary with a file path for anything long. A fresh sub-agent starts with none of your context and returns what you ask for.
 - When the \`Agent\` tool lists a \`fork\` type, use \`subagent_type: "fork"\` when a side task would fill your context with output you will not need again, such as an open-ended survey. A fork starts from this conversation under your own instructions, so its prompt is only the directive: what to do and where its scope ends, without the background. Never write or guess what a fork will find before its report arrives. A fork cannot start forks of its own.
 - When delegated agents finish, tell the user what each one found in your next message. Their results reach you and not the user, so a result you do not pass on stays unseen.
-- Delegate lookups — where something is defined, which files reference it, how a module works — with \`subagent_type: "explore"\`: it has reading and searching tools only and never interrupts the user for permission. Reserve the default sub-agent for work that changes files or runs commands.`
+- Delegate lookups — where something is defined, which files reference it, how a module works — with \`subagent_type: "explore"\`: it has reading and searching tools only and never interrupts the user for permission. Reserve the default sub-agent for work that changes files or runs commands.
+
+### Answering how work is going
+- When asked how things stand while background work runs, read the note about running work on your request first if the host gives you one, and add one status read from the tool that started an item only when the note does not say enough. The answer needs no waiting or polling and leaves the work running, because stopping or restarting an item to answer would lose what it has done.
+- Give each item the state you were given for it (progressing, waiting, stalled or dead) and how long ago it last moved, so the person can judge it for themselves. Stalled means only quiet for a while, not stuck.
+- Group the answer as finished (with its result), running (and where it is), queued, and needing a decision. Lead with the outcome, keep it short, and write in the language the person used, states included.
+- Name each item by what it is doing, not by its id: an id means nothing to the person, so give one only when they ask for it or need it for a command.
+- A result exists only once its completion message has arrived, so for an unfinished item say it is still running; a predicted result reads as a fact and may be wrong.
+- For an item reported dead, say it ended without a result and offer to run it again; starting the same work again unasked could repeat what it already did.`
 
 /**
  * For a session whose permission layer refuses every mutation. Says what that

package/src/provider/errors.ts

@@ -33,6 +33,7 @@ import { LOG_SECRET_PATTERNS } from '../constants/secret-patterns.js'
 import type { ProviderErrorKind, ProviderRequestErrorInit } from '../types/provider/error.js'
 import {
 	type TransportCause,
+	isUsageLimitSignal,
 	readCertificateFailure,
 	readTransportCause,
 } from '../types/provider/errors.js'
@@ -130,6 +131,31 @@ function providerCode(value: unknown): string | undefined {
 	return safeProviderCode(record.code ?? nested)
 }
 
+/**
+ * A vendor can name a spent allowance in `type` instead of `code`
+ * (`{"error":{"type":"usage_limit_reached"}}`, `{"error":{"type":"billing_error"}}`).
+ * Only those identifiers are lifted to a provider code; any other `type` is a
+ * category and stays where it was.
+ */
+function usageLimitTypeOf(error: unknown): string | undefined {
+	if (typeof error !== 'object' || error === null) return undefined
+	const outer = error as { type?: unknown; error?: unknown }
+	const inner =
+		typeof outer.error === 'object' && outer.error !== null
+			? (outer.error as { type?: unknown; error?: unknown })
+			: undefined
+	const innermost =
+		typeof inner?.error === 'object' && inner.error !== null
+			? (inner.error as { type?: unknown })
+			: undefined
+	for (const candidate of [outer.type, inner?.type, innermost?.type]) {
+		if (typeof candidate === 'string' && isUsageLimitSignal(candidate, undefined)) {
+			return safeProviderCode(candidate)
+		}
+	}
+	return undefined
+}
+
 /**
  * Credential shapes to scrub before a provider's words are kept.
  *
@@ -524,7 +550,7 @@ export function providerVendorError(input: {
 }): ProviderRequestError {
 	const { error } = input
 	const status = vendorErrorStatus(error)
-	const exactProviderCode = providerCode(error)
+	const exactProviderCode = providerCode(error) ?? usageLimitTypeOf(error)
 	const name = error instanceof Error ? error.name : ''
 	const message = error instanceof Error ? error.message : ''