@namzu/sdk 27.0.0 → 28.0.0

package/src/types/run/events.ts

@@ -12,10 +12,12 @@ import type {
 	TaskId,
 	ToolUseId,
 } from '../ids/index.js'
+import type { Message } from '../message/index.js'
 import type { PlanStep } from '../plan/index.js'
 import type { PluginHookEvent, PluginHookResult } from '../plugin/index.js'
 import type { TaskStatus } from '../task/index.js'
-import type { ClaimFence } from './checkpoint-store.js'
+import type { CancelCause } from './cancel-cause.js'
+import type { FencingToken } from './checkpoint-store.js'
 import type { Lineage } from './lineage.js'
 import type { MessageStopReason, StopReason } from './stop-reason.js'
 import type {
@@ -94,12 +96,62 @@ interface RunEventEnvelope {
 	 * does, an in-memory store's does not, and `cursor_ahead` is the verdict
 	 * that catches the difference.
 	 */
-	generation?: ClaimFence
+	generation?: FencingToken
 }
 
 type CoreRunEvent =
 	| { type: 'run_started'; runId: RunId; systemPrompt?: string }
 	| { type: 'iteration_started'; runId: RunId; iteration: number }
+	/**
+	 * Who answers when this run asks a human, changed mid-run.
+	 *
+	 * The policy used to be a closure captured at `query()` start, so
+	 * changing it meant ending the run. Now it is a value a host can swap —
+	 * and a swap that left no trace would be the worst version of that: an
+	 * incident review would see approvals with no way to tell which rule
+	 * granted them.
+	 *
+	 * Names, not handlers. A durable log cannot hold a function, and
+	 * `[Function (anonymous)]` is what a log says when somebody tries.
+	 */
+	| {
+			type: 'approval_policy_changed'
+			runId: RunId
+			from: string
+			to: string
+			reason: string
+	  }
+	/**
+	 * What the model was actually asked, when it changed.
+	 *
+	 * `run_started` records a system prompt once, and tool schemas never
+	 * reached the transcript at all — yet the effective envelope changes
+	 * mid-run: `prepareStep` rewrites the system text, narrows the tool
+	 * list, or swaps the model, and a step's skills ride an ephemeral
+	 * trailing system message. So a transcript showed one prompt and a run
+	 * that had asked several different questions.
+	 *
+	 * Emitted only when the tuple DIFFERS from the last one recorded. The
+	 * common case — nothing changed — costs one hash and no event, because
+	 * a per-iteration copy of an unchanged system prompt is the fastest way
+	 * to make a durable log too large to read.
+	 */
+	| {
+			type: 'request_envelope'
+			runId: RunId
+			iteration: number
+			model: string
+			/** Leading system messages plus this step's preamble, concatenated. */
+			systemPrompt: string
+			toolNames: readonly string[]
+			/**
+			 * Stable hash over the sorted tool schemas. A name list cannot see
+			 * a tool whose SCHEMA changed while its name did not — which is
+			 * the change most likely to alter what the model does and least
+			 * likely to be noticed.
+			 */
+			toolSchemaDigest: string
+	  }
 	| {
 			type: 'iteration_completed'
 			runId: RunId
@@ -115,6 +167,39 @@ type CoreRunEvent =
 	 * lost its middle. Every field here is measured, not estimated, where
 	 * the provider reported it (`measuredBy`).
 	 */
+	/**
+	 * What a compaction pass removed, recorded before it is gone.
+	 *
+	 * `compaction_completed` carries counts and nothing else, and both shed
+	 * sites REPLACE the live message array — which `persist()` then writes
+	 * over `messages.json` wholesale. So the shed content existed nowhere
+	 * afterwards: not in memory, not on disk, not in the transcript. "What
+	 * did the agent decide three compactions ago" was unanswerable, an undo
+	 * had no input, and a search index over run history could never see the
+	 * part that mattered most.
+	 *
+	 * Emitted BEFORE the array is replaced, and that ordering is the whole
+	 * mechanism: `transcript.jsonl` is append-only and `emitEvent` reaches it
+	 * synchronously with the pass, so the record is durable before the
+	 * deletion is. Emitted after, a crash between the two loses exactly what
+	 * this exists to keep.
+	 *
+	 * This does NOT make the transcript the source of truth for a live run —
+	 * the message array still is. It adds a parallel append-only record
+	 * beside it.
+	 *
+	 * Carries whole message bodies, tool output included, which is why both
+	 * external wire mappers decline it.
+	 */
+	| {
+			type: 'compaction_shed'
+			runId: RunId
+			iteration: number
+			/** Exactly the messages the pass removed, in their original order. */
+			messages: Message[]
+			/** Whether the pass ran on the threshold or on a provider rejection. */
+			reason: 'threshold' | 'overflow'
+	  }
 	| {
 			type: 'compaction_completed'
 			runId: RunId
@@ -129,7 +214,7 @@ type CoreRunEvent =
 			measuredBy: 'provider' | 'estimate'
 			/** The window the trigger measured against, and where it came from. */
 			contextWindowTokens: number
-			windowSource: 'config' | 'model-table' | 'default'
+			windowSource: 'config' | 'provider' | 'model-table' | 'default'
 			/**
 			 * False when the pass could not get the context below
 			 * `resetThreshold` — the trigger is still armed, and a host may
@@ -137,6 +222,39 @@ type CoreRunEvent =
 			 */
 			reachedResetThreshold?: boolean
 	  }
+	/**
+	 * Oversized tool results were emptied instead of the history being
+	 * summarized.
+	 *
+	 * This is the most common context-relief path and it was the only one
+	 * that emitted nothing. It edits the conversation the model sees —
+	 * `tool_result` bodies are replaced, irrecoverably — so a host reading
+	 * `transcript.jsonl` saw results it no longer has and no record of why.
+	 * The two summarization outcomes were both on the wire; the cheap one
+	 * that runs far more often was not.
+	 *
+	 * Emitted on BOTH branches. `reliefWasEnough: false` means the clear
+	 * happened and was insufficient, so a full summarization followed and a
+	 * `compaction_completed` is coming — the history took two edits, not
+	 * one, and a reader that only saw the second would misattribute the
+	 * first.
+	 */
+	| {
+			type: 'compaction_tool_results_cleared'
+			runId: RunId
+			iteration: number
+			/** How many `tool_result` bodies were emptied. */
+			clearedCount: number
+			/** Characters removed, summed across those results. */
+			charsReclaimed: number
+			/** `charsReclaimed` as tokens, by the same estimate the trigger uses. */
+			reclaimedTokens: number
+			/**
+			 * Whether the clear alone brought the context back under
+			 * `triggerThreshold`. `false` means summarization ran afterwards.
+			 */
+			reliefWasEnough: boolean
+	  }
 	/**
 	 * A compaction pass ran and shed nothing, so the history is unchanged.
 	 *
@@ -185,6 +303,24 @@ type CoreRunEvent =
 			toolUseId: ToolUseId
 			toolName: string
 			input: unknown
+			/**
+			 * Present when another TOOL dispatched this call, rather than the
+			 * model.
+			 *
+			 * `run_code` is the reason: a program it runs calls tools in a
+			 * loop, and those calls went through `registry.execute` directly —
+			 * so they reached the permission gate and reached the event stream
+			 * not at all. A run whose transcript showed one `run_code` call and
+			 * nothing about the eleven writes it performed is a transcript
+			 * that cannot be audited.
+			 *
+			 * Named rather than merely present, and this is the load-bearing
+			 * part: without it a consumer counting tool calls double-counts —
+			 * the parent AND each child — and a consumer rendering a timeline
+			 * draws eleven siblings where there is one call with eleven
+			 * children.
+			 */
+			via?: { readonly tool: string; readonly toolUseId: ToolUseId }
 	  }
 	/**
 	 * A tool saying how far along it is.
@@ -274,6 +410,9 @@ type CoreRunEvent =
 			toolName: string
 			result: string
 			isError: boolean
+			/** See {@link tool_executing}'s `via`. Carried on both, so a
+			 * consumer can pair them without holding the start event. */
+			via?: { readonly tool: string; readonly toolUseId: ToolUseId }
 			/**
 			 * Wall-clock the tool took. Computed since the first version of
 			 * the executor but only ever logged; a host asking "which tool
@@ -388,7 +527,19 @@ type CoreRunEvent =
 	 * `stopReason` is what separates them, and it is on the event because the
 	 * alternative is asking every consumer to hold the `Run` as well.
 	 */
-	| { type: 'run_completed'; runId: RunId; result: string; stopReason?: StopReason }
+	| {
+			type: 'run_completed'
+			runId: RunId
+			result: string
+			stopReason?: StopReason
+			/**
+			 * Present only on a cancellation whose origin was recorded. Absent
+			 * is a real answer: a cancellation nobody attributed is not a user
+			 * cancellation, and defaulting to one would put a confident wrong
+			 * value where an honest gap belongs.
+			 */
+			cancelCause?: CancelCause
+	  }
 	/**
 	 * The run failed.
 	 *
@@ -476,7 +627,7 @@ type CoreRunEvent =
 			contextTokens?: number
 			contextMeasuredBy?: 'provider' | 'estimate'
 			contextWindowTokens?: number
-			windowSource?: 'config' | 'model-table' | 'default'
+			windowSource?: 'config' | 'provider' | 'model-table' | 'default'
 	  }
 	| {
 			type: 'activity_created'
@@ -559,7 +710,15 @@ type CoreRunEvent =
 			taskId: TaskId
 			error: string
 	  }
-	| { type: 'agent_canceled'; runId: RunId; taskId: TaskId }
+	| {
+			type: 'agent_canceled'
+			runId: RunId
+			taskId: TaskId
+			/** Same value the child's own `run_completed` carries, so the two
+			 *  sides of one cancellation agree rather than being correlated
+			 *  by timing. */
+			cancelCause?: CancelCause
+	  }
 	| {
 			type: 'task_created'
 			runId: RunId

package/src/types/run/index.ts

@@ -1,8 +1,10 @@
 export * from './step.js'
+export * from './cancel-cause.js'
 export * from './prepare-step.js'
 export * from './stop-reason.js'
 export * from './config.js'
 export * from './checkpoint-store.js'
+export * from './audit.js'
 export * from './store.js'
 export * from './event-cursor.js'
 export * from './entity.js'

package/src/types/run/metadata.ts

@@ -1,4 +1,4 @@
-import type { AgentStatus, CostInfo, TokenUsage } from '../common/index.js'
+import type { CostInfo, RunExecutionStatus, TokenUsage } from '../common/index.js'
 import type { RunId, TaskId, TenantId } from '../ids/index.js'
 import type { ProjectId } from '../session/ids.js'
 import type { StopReason } from './stop-reason.js'
@@ -17,7 +17,7 @@ export interface RunMetadata {
 	tenantId: TenantId
 	agentId: string
 	agentName: string
-	status: AgentStatus
+	status: RunExecutionStatus
 	config: RunConfigSnapshot
 	provider: string
 

package/src/types/run/prepare-step.ts

@@ -157,6 +157,39 @@ export type PrepareStep = (
 	context: PrepareStepContext,
 ) => PrepareStepResult | undefined | Promise<PrepareStepResult | undefined>
 
+/**
+ * A refusal of the next model call, with the reason it happened.
+ *
+ * An object rather than a boolean, for two reasons that are both about the
+ * reader. A bare boolean does not say which polarity means stop — `true`
+ * is equally readable as "allowed" and as "veto" — and it carries nothing
+ * into the run record, so an operator finds a run that stopped and no
+ * account of why.
+ */
+export interface StepVeto {
+	readonly reason: string
+}
+
+/**
+ * Called before each model call, and able to refuse it.
+ *
+ * `prepareStep` can only RESHAPE a step — `activeTools`, `model`,
+ * `system`, `temperature` — and cannot reject one. `StopCondition` reads
+ * `steps`, so it fires after the step it disliked has already run and been
+ * paid for. Neither is what a host with a live rate limit, a revoked
+ * tenant or a spend ceiling needs, and the only remaining path was a
+ * durable checkpoint built for human review of tool calls.
+ *
+ * A throw fails CLOSED, deliberately opposite to `prepareStep` above.
+ * They are different kinds of hook: a broken step-SHAPER should not kill
+ * an otherwise healthy run, because nothing unsafe gets through when it is
+ * skipped. A broken step-REFUSER skipped is a refusal that did not happen,
+ * which is the thing it exists to prevent.
+ */
+export type BeforeStep = (
+	context: PrepareStepContext,
+) => StepVeto | undefined | Promise<StepVeto | undefined>
+
 /**
  * One shaping stage, or several applied in order.
  *

package/src/types/run/state.ts

@@ -1,8 +1,8 @@
-import type { AgentStatus, CostInfo, TokenUsage } from '../common/index.js'
+import type { CostInfo, RunExecutionStatus, TokenUsage } from '../common/index.js'
 import type { CheckpointId, PendingDecision } from '../hitl/index.js'
 import type { RunId, SessionId, TenantId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
-import type { ProjectId, ThreadId } from '../session/ids.js'
+import type { ProjectId, TopicId } from '../session/ids.js'
 import type { StopReason } from './stop-reason.js'
 
 /**
@@ -25,15 +25,20 @@ import type { StopReason } from './stop-reason.js'
  */
 export interface RunState {
 	/**
-	 * Schema version. Bumped when the shape changes incompatibly, so a
-	 * host that stored a snapshot with an older SDK gets a clear failure
-	 * from {@link parseRunState} instead of a partial restore.
+	 * Schema version. A v1 snapshot (the pre-NZ-TOPIC-03 shape — `threadId`
+	 * instead of `topicId`) and a v2 snapshot (the shape between NZ-TOPIC-03
+	 * and NZ-TOPIC-04 — `topicId` already the field name, but its value can
+	 * still carry the pre-narrowing `thd_` prefix) are both coerced forward
+	 * by {@link parseRunState}; any other unrecognized version is refused
+	 * with a clear failure rather than a partial restore, because silently
+	 * dropping fields this build does not know about is the outcome worth
+	 * failing loudly to avoid.
 	 */
-	readonly version: 1
+	readonly version: 3
 
 	readonly runId: RunId
 	readonly sessionId: SessionId
-	readonly threadId: ThreadId
+	readonly topicId: TopicId
 	readonly projectId: ProjectId
 	readonly tenantId: TenantId
 	/** Present for sub-runs, so a hierarchical store can key the snapshot. */
@@ -42,7 +47,7 @@ export interface RunState {
 	readonly agentId?: string
 	readonly agentName?: string
 
-	readonly status: AgentStatus
+	readonly status: RunExecutionStatus
 	readonly stopReason?: StopReason
 	readonly lastError?: string
 
@@ -87,7 +92,30 @@ export class RunStateVersionError extends Error {
 	}
 }
 
-export const RUN_STATE_VERSION = 1 as const
+export const RUN_STATE_VERSION = 3 as const
+
+/** The shape `RunState` had before NZ-TOPIC-03: `threadId`, not `topicId`. */
+const RUN_STATE_LEGACY_VERSION = 1
+
+/**
+ * The shape `RunState` had between NZ-TOPIC-03 and NZ-TOPIC-04: `topicId`
+ * is already the field name, but its value can still carry the
+ * pre-narrowing `thd_` prefix.
+ */
+const RUN_STATE_PRE_PREFIX_VERSION = 2
+
+/**
+ * Shared by both legacy branches below: rewrite a `thd_`-prefixed topicId
+ * value to `top_`, leaving everything else — including an absent topicId —
+ * untouched. Mirrors `store/session/disk.ts`'s
+ * `migrateSessionStoreTopicIdPrefix`: same no-op-when-already-correct
+ * shape, same reason (idempotence under a repeated migration pass).
+ */
+function rewriteLegacyTopicIdPrefix(record: Record<string, unknown>): Record<string, unknown> {
+	const topicId = record.topicId
+	if (typeof topicId !== 'string' || !topicId.startsWith('thd_')) return record
+	return { ...record, topicId: `top_${topicId.slice('thd_'.length)}` }
+}
 
 /**
  * Parse a serialized snapshot, refusing anything this SDK cannot fully
@@ -96,14 +124,53 @@ export const RUN_STATE_VERSION = 1 as const
  * The version guard is the point. A snapshot is written by one deployment
  * and read by another, possibly weeks later and possibly after an SDK
  * upgrade; a silent partial restore there produces a run that looks healthy
- * and has lost its budgets. Failing loudly is the only honest option.
+ * and has lost its budgets. Failing loudly is the only honest option — for
+ * every version this build does not otherwise recognize. Versions 1 and 2
+ * are the exceptions: both are coerced forward rather than refused, the
+ * same shape-tolerant rename `store/schema.ts`'s migrations use for the
+ * on-disk session record, because a host that parks a run across either
+ * release boundary would otherwise have every in-flight snapshot refused
+ * on the way back in. `threadId` is renamed only when present (v1), and
+ * a `thd_`-prefixed `topicId` is rewritten only when present (v1 and v2),
+ * so a snapshot a host wrote with the field already absent, or already
+ * `top_`-prefixed, does not gain a stamped or double-rewritten value.
+ * Nothing here re-persists the coerced snapshot — a host that calls
+ * `parseRunState` and then serializes the result back out upgrades the
+ * record on THAT write, same as `store/schema.ts`'s "migrate on read,
+ * re-stamp on next write" contract.
+ *
+ * A snapshot from a NEWER build read by an OLDER SDK is refused, not
+ * partially restored: that SDK's `RUN_STATE_VERSION` is behind, so a
+ * record's `version` matches neither the current version nor a legacy
+ * version it knows how to coerce, and falls through to the throw below.
  */
 export function parseRunState(json: string | unknown): RunState {
 	const raw: unknown = typeof json === 'string' ? JSON.parse(json) : json
 	if (typeof raw !== 'object' || raw === null) {
 		throw new RunStateVersionError(raw, RUN_STATE_VERSION)
 	}
-	const version = (raw as { version?: unknown }).version
+	const record = raw as Record<string, unknown>
+	const version = record.version
+
+	if (version === RUN_STATE_LEGACY_VERSION) {
+		const { threadId, ...rest } = record
+		const withTopicId = {
+			...rest,
+			...(threadId !== undefined ? { topicId: threadId } : {}),
+		}
+		return {
+			...rewriteLegacyTopicIdPrefix(withTopicId),
+			version: RUN_STATE_VERSION,
+		} as RunState
+	}
+
+	if (version === RUN_STATE_PRE_PREFIX_VERSION) {
+		return {
+			...rewriteLegacyTopicIdPrefix(record),
+			version: RUN_STATE_VERSION,
+		} as RunState
+	}
+
 	if (version !== RUN_STATE_VERSION) {
 		throw new RunStateVersionError(version, RUN_STATE_VERSION)
 	}

package/src/types/run/stop-reason.ts

@@ -38,6 +38,15 @@ export type StopReason =
 	| 'plan_rejected'
 	/** A caller-supplied `stopWhen` predicate returned true. */
 	| 'stop_condition'
+	/**
+	 * A host's `beforeStep` refused the next model call.
+	 *
+	 * Distinct from `stop_condition`, which reads `steps` and therefore
+	 * only fires AFTER the step it disliked ran and was paid for. This one
+	 * fires before the provider is called at all — the case a host with a
+	 * live rate limit, a revoked tenant or a spend ceiling actually has.
+	 */
+	| 'step_refused'
 	/** The model never produced a valid structured output within its retries. */
 	| 'structured_output_failed'
 	/**

package/src/types/run/store.ts

@@ -27,6 +27,7 @@
  * re-keyed per call, it happens once, deliberately, as its own change.
  */
 
+import type { AuditEvent } from './audit.js'
 import type { Run } from './entity.js'
 import type { PersistedRunEvent, RunEvent } from './events.js'
 
@@ -140,6 +141,45 @@ export interface RunStore {
 	 */
 	getRunDir(): string | null
 
+	/**
+	 * Append one entry to this run's AUDIT trail. OPTIONAL on the contract,
+	 * the same way {@link RunStore.addToIndex} is — an existing custom
+	 * `RunStore` keeps compiling without it. Unlike `addToIndex`, though, its
+	 * absence is not a shrug:
+	 * {@link import('../../manager/run/persistence.js').RunPersistence.recordAudit}
+	 * REFUSES rather than silently running a bound store that lacks it, per
+	 * `refuse-do-not-degrade` — an audit trail nobody can point at is not a
+	 * degraded feature, it is the kernel's central claim quietly not being
+	 * true. NOTE: because `recordAudit` is called from every run's terminal
+	 * path, a `RunStore` implementer that adopts this contract without also
+	 * implementing this method will see every run throw. See the major-bump
+	 * changeset.
+	 *
+	 * A SEPARATE trail from {@link RunStore.appendEvent}: an operational log
+	 * is level-filtered, sampled, rotatable and legitimately absent when no
+	 * host installed a sink. None of that is acceptable for evidence of what
+	 * an agent did, under whose identity, at what cost, and whether it was
+	 * allowed — see `types/run/audit.ts` for the full reasoning (ses_020's
+	 * logging design §5).
+	 *
+	 * A write that rejects here must fail the caller's operation. This is the
+	 * one place on this whole contract where that is true — every other write
+	 * here may be retried or reported by a caller that chooses to; this one
+	 * is durability's last line, and a caller that catches and continues past
+	 * a rejection here has silently degraded the audit trail into decoration.
+	 */
+	appendAuditEvent?(event: AuditEvent): Promise<void>
+
+	/**
+	 * Read the run's audit trail back, oldest first. OPTIONAL for the same
+	 * reason {@link RunStore.appendAuditEvent} is. What a resumed run seeds
+	 * its next audit `seq` from, and the input to
+	 * {@link import('./audit.js').replayRun}. See {@link RunStore.readEvents}
+	 * for the ordering and gap obligations — the same three apply here,
+	 * against this trail's own sequence space.
+	 */
+	readAuditEvents?(): Promise<readonly AuditEvent[]>
+
 	/**
 	 * Record the run in a browsable catalogue of runs. OPTIONAL.
 	 *

package/src/types/sandbox/index.ts

@@ -4,6 +4,7 @@ import {
 	SANDBOX_DEFAULT_MEMORY_LIMIT_MB,
 	SANDBOX_DEFAULT_TIMEOUT_MS,
 } from '../../constants/sandbox/index.js'
+import type { OpenTerminalOptions, TerminalSession } from '../../sandbox/terminal.js'
 import type { SandboxId } from '../ids/index.js'
 
 // ---------------------------------------------------------------------------
@@ -204,6 +205,21 @@ export interface Sandbox {
 	 * same rule the tiered sandbox provider follows, for the same reason.
 	 */
 	setNetworkPolicy?(policy: SandboxNetworkPolicy): Promise<void>
+
+	/**
+	 * Open a real pseudo-terminal inside this sandbox.
+	 *
+	 * Optional, and a backend that cannot provide one must **throw** rather
+	 * than hand back a pipe — the same rule {@link Sandbox.setNetworkPolicy}
+	 * states one line up, and for a sharper reason. A pipe would appear to
+	 * work: bytes would flow, and every program that calls `isatty` would
+	 * take its non-interactive branch. The prompt never appears, the REPL
+	 * exits immediately, the progress bar prints ten thousand lines, and
+	 * nothing says why.
+	 *
+	 * See `sandbox/terminal.ts` for why the backing binding is optional.
+	 */
+	openTerminal?(options: OpenTerminalOptions): Promise<TerminalSession>
 	writeFile(path: string, content: string | Buffer): Promise<void>
 	readFile(path: string): Promise<Buffer>
 	/**
@@ -454,6 +470,27 @@ export const SandboxConfigSchema = z.object({
 	 * quiet downgrade.
 	 */
 	requireIsolation: z.array(z.enum(['filesystem', 'network', 'process'])).default([]),
+	/**
+	 * What the sandbox is rooted at.
+	 *
+	 * `'ephemeral'` (the default, and the previous and only behaviour) gives
+	 * the run a fresh temp directory. Nothing the agent writes touches the
+	 * caller's files, and nothing the caller has is visible to it.
+	 *
+	 * `'working-directory'` roots it at the run's own `workingDirectory`, so
+	 * a sandboxed `bash` acts on the project the agent was asked about
+	 * instead of on an empty directory. That is the case the sandbox was
+	 * wanted for and the one it could not do: the field existed on
+	 * `SandboxCreateConfig` and the kernel never set it, so configuring a
+	 * sandbox through `runConfig.sandbox` always got a temp directory
+	 * whatever the run's own cwd was.
+	 *
+	 * The trade is the point of naming it rather than inferring it. Rooted
+	 * at the working directory, confinement still bounds the agent to that
+	 * subtree — but the subtree is now the caller's real files, and a
+	 * destructive command inside it is destructive for real.
+	 */
+	workspace: z.enum(['ephemeral', 'working-directory']).default('ephemeral'),
 })
 
 export type SandboxConfig = z.infer<typeof SandboxConfigSchema>

package/src/types/session/actor.ts

@@ -1,4 +1,4 @@
-import type { AgentId, TenantId, UserId } from '../ids/index.js'
+import type { TenantId, UserId } from '../ids/index.js'
 
 /**
  * Discriminated union of actors that can own a {@link Session}.
@@ -10,7 +10,15 @@ import type { AgentId, TenantId, UserId } from '../ids/index.js'
  */
 export type ActorRef =
 	| { kind: 'user'; userId: UserId; tenantId: TenantId }
-	| { kind: 'agent'; agentId: AgentId; tenantId: TenantId; parentActor?: ActorRef }
+	// `agentId` is a plain `string`, and that is a correction rather than a
+	// loosening. It was annotated `AgentId` (`` `agt_${string}` ``) and every
+	// value that ever reached it was an agent's REGISTRY KEY — `'worker'`,
+	// `'supervisor'` — put there through an `as AgentId` cast. Nothing in this
+	// kernel has ever minted an `agt_` id; there is no `generateAgentId`. Now
+	// that the id types are nominal (NZ-SURF-11) the annotation could only be
+	// satisfied by an assertion, so it would have documented a guarantee that
+	// is impossible to hold rather than one nobody kept.
+	| { kind: 'agent'; agentId: string; tenantId: TenantId; parentActor?: ActorRef }
 	| { kind: 'system'; role: SystemRoleId; tenantId: TenantId }
 
 /** Branded id for the {@link ActorRef} `system` variant. */

package/src/types/session/entity.ts

@@ -1,6 +1,6 @@
 import type { SessionId, TenantId } from '../ids/index.js'
 import type { ActorRef } from './actor.js'
-import type { ProjectId, ThreadId, WorkspaceId } from './ids.js'
+import type { ProjectId, TopicId, WorkspaceId } from './ids.js'
 
 /**
  * Session lifecycle states. See session-hierarchy.md §4.3 and the state
@@ -21,14 +21,16 @@ export type SessionStatus =
  * Multi-turn work unit owned by exactly one {@link ActorRef} at a time.
  *
  * Scope identifiers:
- *   - `threadId` — the topic-level {@link import('../thread/entity.js').Thread}
- *     this Session lives under. Set at creation, immutable; Sessions never
- *     move threads.
+ *   - `topicId` — the {@link import('../topic/entity.js').Topic} this
+ *     Session lives under. Set at creation, immutable; Sessions never move
+ *     topics. Spelled `threadId` before NZ-TOPIC-03 — see
+ *     `session/migration/id-prefix.ts` for the UNRELATED `thd_` meaning
+ *     that rename did not touch (D2, ses_020).
  *   - `projectId` — the {@link import('../project/entity.js').Project} the
- *     owning Thread belongs to. **Denormalized** from `thread.projectId` at
+ *     owning Topic belongs to. **Denormalized** from `topic.projectId` at
  *     creation time; immutable. Kept on the Session record for ergonomic
  *     access (Project-scoped consumers — handoff validators, archival,
- *     retention — would otherwise need a second round-trip to ThreadStore
+ *     retention — would otherwise need a second round-trip to TopicStore
  *     on every read). This is NOT a deprecated mirror of a fading field;
  *     it is a deliberate denormalization of structurally-immutable derived
  *     data.
@@ -46,7 +48,7 @@ export type SessionStatus =
  */
 export interface Session {
 	id: SessionId
-	threadId: ThreadId
+	topicId: TopicId
 	projectId: ProjectId
 	tenantId: TenantId
 	status: SessionStatus

package/src/types/session/ids.ts

@@ -8,7 +8,9 @@
 
 export type {
 	ProjectId,
+	/** @deprecated Use `TopicId`. */
 	ThreadId,
+	TopicId,
 	SubSessionId,
 	HandoffId,
 	WorkspaceId,

package/src/types/session/index.ts

@@ -4,6 +4,7 @@
 
 export type {
 	ProjectId,
+	/** @deprecated Use `TopicId`. */
 	ThreadId,
 	SubSessionId,
 	HandoffId,
@@ -38,5 +39,6 @@ export type {
 	FailureMode,
 	SubSession,
 	SubSessionKind,
+	SubSessionDelegationStatus,
 	SubSessionStatus,
 } from './sub-session.js'