@namzu/sdk 1.4.0 → 3.0.0

package/src/types/errors/__tests__/errors.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest'
+
+import { ProviderError } from '../../provider/errors.js'
+import { NamzuError, isNamzuError, toPlatformError } from '../index.js'
+
+/**
+ * `PlatformError` was declared and never constructed — a shape nothing
+ * produced and nothing consumed — while the runtime threw bare `Error`
+ * everywhere. A caller catching a failure from `query()` could not tell
+ * "the model rate-limited us" from "the run was configured wrong" from
+ * "that checkpoint does not exist". Matching on message text was the only
+ * recourse, and message text is not an interface.
+ */
+
+describe('NamzuError', () => {
+	it('is an Error, so code that only knows about Error still works', () => {
+		const err = new NamzuError({ code: 'invalid_config', message: 'no model' })
+		expect(err).toBeInstanceOf(Error)
+		expect(err.message).toBe('no model')
+		expect(err.stack).toBeDefined()
+	})
+
+	it('preserves the cause chain', () => {
+		const root = new Error('ENOENT')
+		const err = new NamzuError({ code: 'storage_error', message: 'write failed', cause: root })
+		expect(err.cause).toBe(root)
+	})
+
+	it('defaults `retryable` per code, and lets a caller override it', () => {
+		expect(new NamzuError({ code: 'invalid_config', message: 'x' }).retryable).toBe(false)
+		expect(new NamzuError({ code: 'storage_error', message: 'x' }).retryable).toBe(true)
+		expect(
+			new NamzuError({ code: 'invalid_config', message: 'x', retryable: true }).retryable,
+		).toBe(true)
+	})
+
+	it('narrows through `isNamzuError`', () => {
+		expect(isNamzuError(new NamzuError({ code: 'unknown', message: 'x' }))).toBe(true)
+		expect(isNamzuError(new Error('x'))).toBe(false)
+		expect(isNamzuError('x')).toBe(false)
+	})
+})
+
+describe('toPlatformError', () => {
+	it('gives a host ONE shape regardless of what was thrown', () => {
+		// Which is the entire point: without this, "handle errors from the
+		// SDK" means writing the same instanceof ladder in every caller.
+		for (const thrown of [
+			new NamzuError({ code: 'plugin_error', message: 'a' }),
+			new ProviderError({ code: 'rate_limit', message: 'b' }),
+			new Error('c'),
+			'not even an error',
+		]) {
+			const platform = toPlatformError(thrown)
+			expect(typeof platform.code).toBe('string')
+			expect(typeof platform.message).toBe('string')
+			expect(typeof platform.retryable).toBe('boolean')
+		}
+	})
+
+	it('carries a NamzuError through unchanged', () => {
+		const err = new NamzuError({
+			code: 'not_found',
+			message: 'Checkpoint not found: cp_1',
+			details: { checkpointId: 'cp_1' },
+		})
+		expect(toPlatformError(err)).toEqual({
+			code: 'not_found',
+			message: 'Checkpoint not found: cp_1',
+			details: { checkpointId: 'cp_1' },
+			retryable: false,
+		})
+	})
+
+	it('keeps a ProviderError`s classification instead of recomputing it', () => {
+		// The provider taxonomy already knows things this one does not —
+		// which status codes back off, what the server asked for.
+		const err = new ProviderError({
+			code: 'rate_limit',
+			message: 'slow down',
+			providerId: 'anthropic',
+			status: 429,
+			retryAfterMs: 3_000,
+		})
+
+		expect(toPlatformError(err)).toEqual({
+			code: 'provider_error',
+			message: 'slow down',
+			details: {
+				providerCode: 'rate_limit',
+				providerId: 'anthropic',
+				status: 429,
+				retryAfterMs: 3_000,
+			},
+			retryable: true,
+		})
+	})
+
+	it('does not claim a non-retryable provider failure is retryable', () => {
+		const err = new ProviderError({ code: 'auth', message: 'bad key' })
+		expect(toPlatformError(err).retryable).toBe(false)
+	})
+
+	it('reports a plain Error honestly as `unknown` rather than guessing', () => {
+		expect(toPlatformError(new Error('something broke'))).toEqual({
+			code: 'unknown',
+			message: 'something broke',
+			retryable: false,
+		})
+	})
+
+	it('does not lose a thrown non-Error', () => {
+		// Rare, and usually a bug elsewhere — but dropping it is worse than
+		// reporting it as-is.
+		expect(toPlatformError({ weird: true }).message).toBe('[object Object]')
+		expect(toPlatformError(undefined).message).toBe('undefined')
+	})
+})

package/src/types/errors/catalog.ts

@@ -0,0 +1,211 @@
+import { ProviderError } from '../provider/errors.js'
+import { isNamzuError } from './index.js'
+
+/**
+ * An ordered rule layer between a caught throwable and the operator.
+ *
+ * A failure surfaced as whatever prose the vendor SDK happened to write:
+ * no stable id to grep for in logs, and no instruction on what to change.
+ * There was also no growth point — a newly-observed failure shape could
+ * only be given curated copy by editing the classifier itself, which mixes
+ * "what kind of failure is this" with "what should a person do about it".
+ *
+ * The two are separate jobs. Classification is structural and belongs at
+ * the boundary; remediation is editorial and belongs in a list a human
+ * appends to. `DoctorCheckResult` already proves the pattern is native
+ * here: it carries `message` and `remediation` as separate fields, and
+ * `namzu doctor` has been the only surface that got either.
+ *
+ * Rules match on STRUCTURAL signals — code, status, error name, an
+ * explicit `hint` own-property from the throw site — never on volatile
+ * vendor prose, which changes without warning and differs per SDK version.
+ */
+
+/** What a rule knows about a failure, flattened for matching. */
+export interface ErrorFacts {
+	/** namzu or provider code, whichever classification produced one. */
+	readonly code?: string
+	readonly status?: number
+	/** Constructor name, for a throwable neither classifier recognised. */
+	readonly name?: string
+	readonly message: string
+	/** Server-directed backoff, when one was parsed. */
+	readonly retryAfterMs?: number
+	/** A hint the throw site attached directly. See {@link readHint}. */
+	readonly hint?: string
+}
+
+export interface ErrorCatalogRule {
+	/**
+	 * Stable id. Appears in logs and in operator output, so it is greppable
+	 * and can be linked to. Never renamed once shipped — a rule whose
+	 * meaning changes gets a new id.
+	 */
+	readonly id: string
+	readonly when: (facts: ErrorFacts) => boolean
+	/** What happened, in an operator's terms rather than the vendor's. */
+	readonly message: string
+	/** What to change. Separate from `message` so a surface can override it. */
+	readonly hint: string
+}
+
+export interface ErrorExplanation {
+	readonly id: string
+	readonly message: string
+	readonly hint: string
+}
+
+/**
+ * A hint attached at the throw site.
+ *
+ * Infrastructure code knows things the classifier cannot infer — that a
+ * daemon is not running, that a socket path is wrong — and had no channel
+ * to say so except by baking prose into the message, where it cannot be
+ * separated from the failure again. An own-property survives every
+ * `instanceof` check and every rethrow, and rules can pass it through
+ * under a stable id.
+ */
+export function readHint(err: unknown): string | undefined {
+	if (typeof err !== 'object' || err === null) return undefined
+	const hint = (err as { hint?: unknown }).hint
+	return typeof hint === 'string' && hint.length > 0 ? hint : undefined
+}
+
+/** Attach a hint to a throwable without changing its message or type. */
+export function withHint<E>(err: E, hint: string): E {
+	if (typeof err === 'object' && err !== null) {
+		Object.defineProperty(err, 'hint', { value: hint, enumerable: false, configurable: true })
+	}
+	return err
+}
+
+/** Flatten a throwable into the shape rules match on. */
+export function factsOf(err: unknown): ErrorFacts {
+	const hint = readHint(err)
+	const message = err instanceof Error ? err.message : String(err)
+
+	if (err instanceof ProviderError) {
+		return {
+			code: err.code,
+			message,
+			name: err.name,
+			...(err.status !== undefined ? { status: err.status } : {}),
+			...(err.retryAfterMs !== undefined ? { retryAfterMs: err.retryAfterMs } : {}),
+			...(hint !== undefined ? { hint } : {}),
+		}
+	}
+
+	if (isNamzuError(err)) {
+		const status = err.details?.status
+		return {
+			code: err.code,
+			message,
+			name: err.name,
+			...(typeof status === 'number' ? { status } : {}),
+			...(hint !== undefined ? { hint } : {}),
+		}
+	}
+
+	return {
+		message,
+		...(err instanceof Error ? { name: err.name } : {}),
+		...(hint !== undefined ? { hint } : {}),
+	}
+}
+
+/**
+ * The seed rules.
+ *
+ * Ordered, first match wins — so a rule may be as specific as it likes
+ * without having to exclude everything below it. Three to start, chosen
+ * because they are the failures an operator hits first and the ones where
+ * the vendor's own words help least.
+ */
+export const DEFAULT_ERROR_RULES: readonly ErrorCatalogRule[] = [
+	{
+		id: 'hint.from_throw_site',
+		// Highest precedence on purpose: code that raised the failure knows
+		// more about it than a rule matching on a status code ever will.
+		when: (facts) => facts.hint !== undefined,
+		message: '',
+		hint: '',
+	},
+	{
+		// Before the generic auth rule: the codes collapse 401 and 403 into
+		// one, but the two call for different actions and the status still
+		// separates them when the provider sent it.
+		id: 'provider.permission',
+		when: (facts) => facts.status === 403,
+		message: 'The credentials are valid but not permitted to use this model.',
+		hint: 'The key authenticated, so this is an entitlement rather than a secret problem: check the model name and whether the account has access to it.',
+	},
+	{
+		id: 'provider.auth',
+		when: (facts) => facts.code === 'auth' || facts.status === 401,
+		message: 'The provider rejected the credentials for this run.',
+		hint: 'Check that the API key is set, is not expired, and belongs to the account the model is billed to. Retrying will not help until it changes.',
+	},
+	{
+		id: 'provider.rate_limit',
+		when: (facts) => facts.code === 'rate_limit' || facts.status === 429,
+		message: 'The provider is rate limiting this run.',
+		hint: 'Automatic retries with backoff have already been exhausted. Lower concurrency, or wait for the quota window to reset before resuming.',
+	},
+	{
+		id: 'provider.context_overflow',
+		when: (facts) => facts.code === 'context_length_exceeded',
+		message: 'The prompt is larger than the model can accept.',
+		hint: 'Compaction ran and could not make enough room. Lower `compactionConfig.triggerThreshold`, reduce `keepRecentMessages`, or cap large tool outputs so history stops growing faster than it can be shed.',
+	},
+	{
+		id: 'provider.unavailable',
+		when: (facts) =>
+			facts.code === 'server_error' ||
+			facts.code === 'overloaded' ||
+			(facts.status !== undefined && facts.status >= 500),
+		message: 'The provider is failing on its own side.',
+		hint: 'Nothing in the run is wrong. Resume from the last checkpoint once the provider recovers.',
+	},
+	{
+		id: 'provider.network',
+		when: (facts) => facts.code === 'network' || facts.code === 'timeout',
+		message: 'The provider could not be reached.',
+		hint: 'Check network reachability and any proxy or firewall between this host and the provider endpoint, then resume from the last checkpoint.',
+	},
+	{
+		id: 'provider.model_not_found',
+		when: (facts) => facts.code === 'not_found' || facts.status === 404,
+		message: 'The provider does not recognise the model or endpoint requested.',
+		hint: "Check `runConfig.model` against the provider's current model list — a model id that was valid can be retired, and a deployment-scoped provider needs the deployment name rather than the base model name.",
+	},
+	{
+		id: 'provider.content_filter',
+		when: (facts) => facts.code === 'content_filter',
+		message: 'The provider refused the request on safety grounds.',
+		hint: "This is the provider's policy decision, not a namzu one, and resending the same prompt cannot change it. The refusal usually names the category it triggered.",
+	},
+]
+
+/**
+ * Explain a failure, or return `null` when no rule claims it.
+ *
+ * `null` rather than a generic fallback: inventing advice for a failure
+ * nobody has characterised is worse than saying nothing, because it sends
+ * the reader somewhere specific and wrong.
+ */
+export function explainError(
+	err: unknown,
+	rules: readonly ErrorCatalogRule[] = DEFAULT_ERROR_RULES,
+): ErrorExplanation | null {
+	const facts = factsOf(err)
+	for (const rule of rules) {
+		if (!rule.when(facts)) continue
+		// The throw-site rule carries no copy of its own — it exists to give
+		// a hint written at the raise point precedence over a generic one.
+		if (rule.id === 'hint.from_throw_site') {
+			return { id: rule.id, message: facts.message, hint: facts.hint ?? '' }
+		}
+		return { id: rule.id, message: rule.message, hint: rule.hint }
+	}
+	return null
+}

package/src/types/errors/index.ts

@@ -0,0 +1,121 @@
+import type { PlatformError } from '../common/index.js'
+import { ProviderError } from '../provider/errors.js'
+
+/**
+ * What went wrong, at the granularity a HOST actually branches on.
+ *
+ * `PlatformError` was declared and never constructed — a shape nothing
+ * produced and nothing consumed. Meanwhile the runtime threw bare `Error`
+ * everywhere, so a caller catching a failure from `query()` could not tell
+ * "the model rate-limited us" from "the run was configured wrong" from
+ * "that checkpoint does not exist". The only recourse was matching on
+ * message text, which is not an interface.
+ *
+ * The union stays small on purpose: each member exists because a caller
+ * does something DIFFERENT about it. `provider_error` carries the finer
+ * {@link ProviderErrorCode} in `details` rather than being fanned out
+ * here, because that taxonomy answers the runtime's questions, not a
+ * host's.
+ */
+export type NamzuErrorCode =
+	/** The run was set up wrong — missing model, contradictory options. Retrying cannot help. */
+	| 'invalid_config'
+	/** The upstream model call failed. `details.providerCode` narrows it. */
+	| 'provider_error'
+	/** A tool could not be executed or resolved. */
+	| 'tool_error'
+	/** A referenced checkpoint, run or emergency dump does not exist. */
+	| 'not_found'
+	/** A plugin hook failed or refused. */
+	| 'plugin_error'
+	/** The provider or environment cannot do what the run requires. */
+	| 'capability_unavailable'
+	/** Persistence (checkpoint store, run store, workspace) failed. */
+	| 'storage_error'
+	/** Unclassified. Treated as non-retryable. */
+	| 'unknown'
+
+export interface NamzuErrorInit {
+	readonly code: NamzuErrorCode
+	readonly message: string
+	readonly details?: Record<string, unknown>
+	/** Defaults per code; pass explicitly to override. */
+	readonly retryable?: boolean
+	readonly cause?: unknown
+}
+
+/** Codes for which the same operation may succeed if repeated. */
+const RETRYABLE: ReadonlySet<NamzuErrorCode> = new Set<NamzuErrorCode>(['storage_error'])
+
+/**
+ * A runtime failure a host can branch on.
+ *
+ * Implements {@link PlatformError} so the declared shape finally has a
+ * producer, and extends `Error` so it still behaves like one everywhere
+ * that only knows about `Error` — stack, `instanceof`, `cause`.
+ */
+export class NamzuError extends Error implements PlatformError {
+	readonly code: NamzuErrorCode
+	readonly details: Record<string, unknown> | undefined
+	readonly retryable: boolean
+
+	constructor(init: NamzuErrorInit) {
+		super(init.message, init.cause !== undefined ? { cause: init.cause } : undefined)
+		this.name = 'NamzuError'
+		this.code = init.code
+		this.details = init.details
+		this.retryable = init.retryable ?? RETRYABLE.has(init.code)
+	}
+}
+
+export function isNamzuError(err: unknown): err is NamzuError {
+	return err instanceof NamzuError
+}
+
+/**
+ * Normalize ANYTHING thrown into the declared shape.
+ *
+ * This is what makes `PlatformError` worth having: a host wraps one call
+ * and gets a consistent `{ code, message, details, retryable }` no matter
+ * what came out — a `NamzuError`, a `ProviderError`, a plain `Error` from
+ * a dependency, or a thrown string. Without it, "handle errors from the
+ * SDK" means writing the same defensive `instanceof` ladder in every
+ * caller.
+ *
+ * A `ProviderError` keeps its classification: its code lands in
+ * `details.providerCode` and its `retryable` verdict is preserved rather
+ * than recomputed, because that verdict already encodes what the provider
+ * taxonomy knows and this one does not.
+ */
+export function toPlatformError(err: unknown): PlatformError {
+	if (isNamzuError(err)) {
+		return {
+			code: err.code,
+			message: err.message,
+			...(err.details ? { details: err.details } : {}),
+			retryable: err.retryable,
+		}
+	}
+
+	if (err instanceof ProviderError) {
+		return {
+			code: 'provider_error',
+			message: err.message,
+			details: {
+				providerCode: err.code,
+				...(err.providerId !== undefined ? { providerId: err.providerId } : {}),
+				...(err.status !== undefined ? { status: err.status } : {}),
+				...(err.retryAfterMs !== undefined ? { retryAfterMs: err.retryAfterMs } : {}),
+			},
+			retryable: err.retryable,
+		}
+	}
+
+	if (err instanceof Error) {
+		return { code: 'unknown', message: err.message, retryable: false }
+	}
+
+	// A thrown non-Error is rare and usually a bug elsewhere, but losing it
+	// entirely is worse than reporting it as-is.
+	return { code: 'unknown', message: String(err), retryable: false }
+}

package/src/types/guardrail/index.ts

@@ -0,0 +1,62 @@
+import type { RunId } from '../ids/index.js'
+import type { Message } from '../message/index.js'
+
+/**
+ * Guardrails inspect what goes INTO a run and what comes OUT of it.
+ *
+ * namzu had three good gates on tool calls — probe veto, `VerificationGate`,
+ * HITL review — and they all point the same way: they protect the world
+ * from the agent. Nothing protected the user from the agent's own output,
+ * and nothing looked at the prompt before the run started.
+ *
+ * The concrete failure: an agent reads a credential file, the read is
+ * allowed (it is a legitimate file), the secret enters context, and it is
+ * repeated in the final answer. Every existing gate is upstream of that
+ * and none of them fire.
+ */
+
+export interface InputGuardrailContext {
+	readonly runId: RunId
+	/** The messages the run is about to start with. */
+	readonly messages: readonly Message[]
+	/** The assembled system prompt, when there is one. */
+	readonly systemPrompt?: string
+}
+
+export interface OutputGuardrailContext {
+	readonly runId: RunId
+	/** The run's final assistant text. */
+	readonly output: string
+	/** Full message history, for a guardrail that needs the conversation. */
+	readonly messages: readonly Message[]
+}
+
+/**
+ * What a guardrail decided.
+ *
+ * `rewrite` matters as much as `tripwire`: a PII policy usually wants to
+ * redact an account number, not throw the whole answer away. A gate that
+ * can only abort forces every redaction use case to be implemented
+ * somewhere else.
+ */
+export type GuardrailVerdict =
+	| { readonly action: 'pass' }
+	| { readonly action: 'block'; readonly reason: string }
+	| { readonly action: 'rewrite'; readonly output: string; readonly reason?: string }
+
+export type InputGuardrail = (
+	ctx: InputGuardrailContext,
+) => GuardrailVerdict | Promise<GuardrailVerdict>
+
+export type OutputGuardrail = (
+	ctx: OutputGuardrailContext,
+) => GuardrailVerdict | Promise<GuardrailVerdict>
+
+/** Convenience: a named guardrail, so a block can say which rule tripped. */
+export interface NamedGuardrail<T> {
+	readonly name: string
+	readonly check: T
+}
+
+export type InputGuardrailSpec = InputGuardrail | NamedGuardrail<InputGuardrail>
+export type OutputGuardrailSpec = OutputGuardrail | NamedGuardrail<OutputGuardrail>

package/src/types/hitl/index.ts

@@ -1,3 +1,5 @@
+import type { WorkingStateSnapshot } from '../../compaction/wire.js'
+import type { SerializedSpanContext } from '../../telemetry/attributes.js'
 import type { CostInfo, TokenUsage } from '../common/index.js'
 import type { CheckpointId, PlanId, RunId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
@@ -9,7 +11,27 @@ export type HITLResumeDecision =
 	| { action: 'continue' }
 	| { action: 'approve_plan'; feedback?: string }
 	| { action: 'reject_plan'; feedback: string }
-	| { action: 'approve_tools' }
+	| {
+			action: 'approve_tools'
+			/**
+			 * Grant keys to remember, so calls covered by them are not asked
+			 * about again for the rest of the run.
+			 *
+			 * Nothing is remembered unless this says so, and only an explicit
+			 * approval can say it — a denial or a non-response leaves nothing
+			 * behind. Non-reuse was deliberate ("consent is not
+			 * transferable"); what changes is that the SCOPE becomes the
+			 * approver's to choose rather than being fixed at "this one call"
+			 * or, in the only escape available, "everything for the session".
+			 *
+			 * Keys come from {@link ToolGrantKeys}, so a grant can be as
+			 * narrow as one exact invocation or as wide as a whole tool.
+			 * `bash` is unconditionally non-read-only and in no allowlist, so
+			 * `bash: git status` re-prompted on every batch forever and the
+			 * only way out was a blanket grant that also covered `rm -rf`.
+			 */
+			remember?: readonly string[]
+	  }
 	| { action: 'modify_tools'; modifications: ToolModification[] }
 	| { action: 'reject_tools'; feedback: string }
 	| {
@@ -101,22 +123,54 @@ export interface CheckpointSummary {
 	lastAssistantMessage?: string
 }
 
-export interface ActiveNodeInfo {
-	agentId: string
-	agentType: 'reactive' | 'pipeline' | 'router' | 'supervisor'
-
-	nodeRef?: string
-
-	parentAgentId?: string
-
-	depth: number
-}
-
-export interface BranchStackEntry {
-	agentId: string
-	decision: string
-	confidence: number
-	timestamp: number
+/**
+ * A decision the run is parked on, recorded durably.
+ *
+ * Without this the park exists only as a suspended `await` inside one
+ * process: a checkpoint written at a tool-review gate looks identical to a
+ * checkpoint written mid-run, so nothing on disk says "a human owes this
+ * run an answer". Kill the process and the request is gone — the approval
+ * queue a host would build from durable state has nothing to read, and a
+ * resumed run silently re-asks the model instead of honoring the approval
+ * that was already granted.
+ *
+ * `request` is stored verbatim so a fresh process can render exactly what
+ * the human was shown, and apply the answer to exactly those tool calls.
+ */
+export interface PendingDecision {
+	/** The request the run parked on, as the `resumeHandler` received it. */
+	readonly request: HITLDecisionRequest
+	/** Epoch ms at which the run parked. */
+	readonly parkedAt: number
+	/**
+	 * Epoch ms after which this park is no longer worth serving.
+	 *
+	 * Absolute, not a duration, so it survives the process that set it —
+	 * every timer in the SDK is an in-process `setTimeout` and the
+	 * park-record delay is deliberately `unref`'d, so nothing in-memory can
+	 * outlive a redeploy. Without it a run parks for approval, the worker is
+	 * replaced, nobody answers, and the checkpoint stays outstanding
+	 * forever: every approval-queue reader keeps serving it and its
+	 * workspace is never reclaimed.
+	 *
+	 * The run timeout cannot cover this. `checkLimitsDetailed` is only
+	 * reached between iterations and a park suspends mid-iteration, so a
+	 * long-lived process hard-stops the run immediately AFTER the human
+	 * finally approves, while across a restart the restored elapsed time
+	 * excludes parked time entirely — the same configuration giving two
+	 * opposite outcomes.
+	 *
+	 * Absent means no deadline, which is today's behaviour.
+	 */
+	readonly deadlineAt?: number
+	/**
+	 * Set once the decision arrives, so a resolved checkpoint stays
+	 * distinguishable from one that was never parked. A checkpoint is
+	 * outstanding when `pending` is set and `resolvedAt` is not.
+	 */
+	readonly resolvedAt?: number
+	/** The answer, when one arrived. Kept as evidence of who decided what. */
+	readonly decision?: HITLResumeDecision
 }
 
 export interface IterationCheckpoint {
@@ -127,6 +181,12 @@ export interface IterationCheckpoint {
 	tokenUsage: TokenUsage
 	costInfo: CostInfo
 	planStatus?: PlanStatus
+
+	/**
+	 * Present when the run parked at this checkpoint awaiting a human.
+	 * See {@link PendingDecision}.
+	 */
+	pending?: PendingDecision
 	guardState: {
 		iterationCount: number
 		elapsedMs: number
@@ -135,9 +195,31 @@ export interface IterationCheckpoint {
 
 	toolResultHashes?: Record<string, string>
 
-	branchStack?: BranchStackEntry[]
-
-	activeNode?: ActiveNodeInfo
+	/**
+	 * Compaction's accumulated working state at the moment of the
+	 * checkpoint.
+	 *
+	 * Absent on checkpoints written before this existed, and absent when
+	 * compaction is disabled — in both cases the resumed run starts with an
+	 * empty manager, which is exactly today's behaviour.
+	 */
+	workingState?: WorkingStateSnapshot
+
+	/**
+	 * The trace this checkpoint was taken inside.
+	 *
+	 * A resumed run used to mint a fresh root span with a new trace id and
+	 * no link to the one that crashed, so the failure and its recovery could
+	 * not be reconstructed as one timeline. Every span carries the run id,
+	 * which is enough to find both traces by query and not enough to see one
+	 * waterfall — and even that goes away for a replay fork, which mints a
+	 * new run id.
+	 *
+	 * Absent on checkpoints written before this existed, and on runs with no
+	 * telemetry registered; in both cases the resumed run starts its own
+	 * trace, which is exactly today's behaviour.
+	 */
+	traceContext?: SerializedSpanContext
 }
 
 export function autoApproveHandler(request: HITLDecisionRequest): Promise<HITLResumeDecision> {

package/src/types/ids/index.ts

@@ -4,11 +4,11 @@ export type SessionId = `ses_${string}`
 export type ToolCallId = `call_${string}`
 /**
  * Provider-issued tool-use identifier surfaced on the streaming event bus.
- * Providers emit different prefixes (Anthropic: `toolu_*`, OpenAI: `call_*`,
+ * Providers emit different prefixes (`toolu_*`, `call_*`,
  * others vary), so this type intentionally stays unbranded — we accept the
  * provider's verbatim string and use it solely as a correlation key across
  * `tool_input_*`, `tool_executing`, and `tool_completed` events. Distinct
- * from {@link ToolCallId} which is the OpenAI-format identifier carried in
+ * from {@link ToolCallId} which is the wire-format identifier carried in
  * persisted assistant messages and replay records.
  */
 export type ToolUseId = string