@namzu/sdk 27.1.0 → 29.0.0

package/src/types/run/cancel-cause.ts

@@ -0,0 +1,60 @@
+/**
+ * Why a run stopped, when it stopped because somebody stopped it.
+ *
+ * `stopReason: 'cancelled'` says the run was cancelled and nothing more,
+ * and the four cases behind it want four different responses. An operator
+ * pressing cancel is not a defect. A parent abandoning its children is a
+ * fact about the parent, and looking for the child's problem wastes the
+ * reader's time. A budget stop is a configuration question. A hook's
+ * refusal is a policy one.
+ *
+ * The gap was not that the information was thrown away — it was never
+ * carried. `AbstractAgent.cancel()` aborted with no argument at all, and
+ * `AgentManager` aborted a child with the bare string `'canceled'`, which
+ * `abortReasonText` deliberately renders as no reason (it would otherwise
+ * print "was cancelled: canceled"). So both paths arrived at the run loop
+ * indistinguishable.
+ */
+export type CancelCause = 'user' | 'parent' | 'budget' | 'hook'
+
+/**
+ * The abort reason a cancellation carries.
+ *
+ * An `Error` subclass rather than a bare value, because `AbortController`
+ * reasons cross package boundaries and a plain object gives a reader
+ * nothing in a stack trace. `name` is checked rather than `instanceof`,
+ * the answer this codebase already settled on for provider errors: two
+ * copies of a package defeat `instanceof` and nothing announces it.
+ */
+export class RunCancelled extends Error {
+	override readonly name = 'RunCancelled'
+
+	/**
+	 * Named `cancelCause`, not `cause`. `Error.cause` already exists and
+	 * means "the error this one wrapped", so reusing it would put two
+	 * unrelated meanings on one property name and silently change what
+	 * anything reading `err.cause` gets.
+	 */
+	readonly cancelCause: CancelCause
+
+	constructor(cancelCause: CancelCause) {
+		super(`run cancelled by ${cancelCause}`)
+		this.cancelCause = cancelCause
+	}
+}
+
+/**
+ * The cause an abort reason carries, or `undefined` for one that carries
+ * none.
+ *
+ * `undefined` is a real answer and not a fallback. A cancellation whose
+ * origin nobody recorded is not a user cancellation, and substituting
+ * `'user'` would put a confident wrong value where an honest absence
+ * belongs.
+ */
+export function cancelCauseOf(reason: unknown): CancelCause | undefined {
+	if (reason instanceof Error && reason.name === 'RunCancelled') {
+		return (reason as RunCancelled).cancelCause
+	}
+	return undefined
+}

package/src/types/run/checkpoint-store.ts

@@ -185,7 +185,7 @@ export interface DurableRunEntry extends CheckpointRunScope {
 	 * neither, or either, and the state a queue worker needs most is parked
 	 * AND unclaimed, which one union cannot say.
 	 */
-	readonly claim?: ClaimSummary
+	readonly claim?: LeaseSummary
 }
 
 /**
@@ -234,14 +234,14 @@ export type DurableRunOrder =
  * Not a random token, deliberately: randomness proves identity and cannot
  * establish *order*, and order is the entire mechanism.
  */
-export type ClaimFence = number
+export type FencingToken = number
 
 /** A holding of a run's claim, as issued to the process that took it. */
-export interface RunClaim {
+export interface RunLease {
 	/** Opaque caller-supplied identity — a worker id, a pod name. Evidence, not authority. */
 	readonly holder: string
-	/** See {@link ClaimFence}. Present it on every durable write. */
-	readonly fence: ClaimFence
+	/** See {@link FencingToken}. Present it on every durable write. */
+	readonly fence: FencingToken
 	/**
 	 * Absolute epoch ms after which the claim may be taken by somebody else.
 	 *
@@ -253,9 +253,9 @@ export interface RunClaim {
 }
 
 /** A run's claim as a listing reports it. */
-export interface ClaimSummary {
+export interface LeaseSummary {
 	readonly holder: string
-	readonly fence: ClaimFence
+	readonly fence: FencingToken
 	readonly expiresAt: number
 	/**
 	 * Whether the claim had expired at the instant the listing was taken.
@@ -268,6 +268,19 @@ export interface ClaimSummary {
 	readonly expired: boolean
 }
 
+/**
+ * Old spellings of the three above, live for one deprecation window.
+ *
+ * These are types with no runtime value, so a plain `export type` carries
+ * the `@deprecated` tag fine — the `const`+`type` pair the SDK barrel uses
+ * for renamed CLASSES is not needed here and would not compile.
+ *
+ * The verbs did NOT move with them. `claimRun`, `releaseRun` and
+ * `toClaimSummary` keep their names: "claim a lease" is idiomatic, and
+ * renaming the methods would break every `CheckpointStore` implementor for
+ * no reading gain — the opposite of the point.
+ */
+
 /** What a caller asks for when taking a run. */
 export interface ClaimRunOptions {
 	/** Who is taking it. Recorded so an operator can see what holds a stuck run. */
@@ -362,7 +375,7 @@ export interface CheckpointStore {
 	/**
 	 * Persist one checkpoint. Overwrites an existing checkpoint with the same id.
 	 *
-	 * @param fence the {@link ClaimFence} of the holding this write belongs
+	 * @param fence the {@link FencingToken} of the holding this write belongs
 	 *   to, when the run is claimed. A store that supports claims REFUSES a
 	 *   write whose fence is below the run's current one — that refusal is
 	 *   what makes a claim a lease rather than a suggestion, because a holder
@@ -378,7 +391,7 @@ export interface CheckpointStore {
 	writeCheckpoint(
 		scope: CheckpointRunScope,
 		checkpoint: IterationCheckpoint,
-		fence?: ClaimFence,
+		fence?: FencingToken,
 	): Promise<void>
 
 	/** Load a single checkpoint by id. Returns `null` when it does not exist. */
@@ -512,7 +525,7 @@ export interface CheckpointStore {
 	 *     claim from each other instantly. Use something per-process, not a
 	 *     per-deployment name.
 	 */
-	claimRun?(scope: CheckpointRunScope, options: ClaimRunOptions): Promise<RunClaim | null>
+	claimRun?(scope: CheckpointRunScope, options: ClaimRunOptions): Promise<RunLease | null>
 
 	/**
 	 * Give a claim up early. Idempotent: releasing a claim that already
@@ -528,5 +541,5 @@ export interface CheckpointStore {
 	 * difference, never a correctness one, which is the property that lets a
 	 * crashed worker be indistinguishable from a slow one.
 	 */
-	releaseRun?(scope: CheckpointRunScope, fence: ClaimFence): Promise<void>
+	releaseRun?(scope: CheckpointRunScope, fence: FencingToken): Promise<void>
 }

package/src/types/run/config.ts

@@ -2,7 +2,7 @@ import type { ModelPricing } from '../../utils/cost.js'
 import type { Logger } from '../../utils/logger.js'
 import type { RunId, SessionId, TenantId } from '../ids/index.js'
 import type { PermissionMode } from '../permission/index.js'
-import type { ProjectId, ThreadId } from '../session/ids.js'
+import type { ProjectId, TopicId } from '../session/ids.js'
 import type { CheckpointStore } from './checkpoint-store.js'
 
 export interface AgentRunConfig {
@@ -54,6 +54,12 @@ export interface AgentRunConfig {
 		timeoutMs?: number
 		memoryLimitMb?: number
 		maxProcesses?: number
+		/**
+		 * What the sandbox is rooted at — see `SandboxConfigSchema.workspace`.
+		 * Absent means `'ephemeral'`: a fresh temp directory, which is the
+		 * behaviour every sandboxed run had before this existed.
+		 */
+		workspace?: 'ephemeral' | 'working-directory'
 	}
 
 	/**
@@ -102,12 +108,27 @@ export interface AgentRunConfig {
 	 * Default `undefined` — no deadline, today's behaviour.
 	 */
 	hitlParkTtlMs?: number
+
+	/**
+	 * Override the logger a run's log lines derive from.
+	 *
+	 * This is an override of the SOURCE, not a substitute for correlation:
+	 * `RunContextFactory.buildLogger` always calls `.child()` on whichever
+	 * logger this resolves to, so a host-supplied logger still gains
+	 * `namzu.run.id`, `sessionId`, `threadId`, `projectId` and `tenantId` —
+	 * the same binding the process default gets. A host that wants its own
+	 * sink, format or destination threaded through every record a run
+	 * produces sets this once; a host that wants the process default
+	 * (`getRootLogger()`) sets nothing, which is what absent has always
+	 * meant.
+	 */
+	logger?: Logger
 }
 
 /**
- * Config for {@link RunPersistence}. `sessionId`, `threadId`, `tenantId`,
+ * Config for {@link RunPersistence}. `sessionId`, `topicId`, `tenantId`,
  * and `projectId` are required — every Run is attributed across the full
- * five-layer scope (Tenant → Project → Thread → Session → Run,
+ * five-layer scope (Tenant → Project → Topic → Session → Run,
  * Convention #17).
  */
 export interface RunPersistenceConfig {
@@ -121,7 +142,7 @@ export interface RunPersistenceConfig {
 	log: Logger
 
 	sessionId: SessionId
-	threadId: ThreadId
+	topicId: TopicId
 	tenantId: TenantId
 	projectId: ProjectId
 

package/src/types/run/derive-status.ts

@@ -1,4 +1,4 @@
-import type { AgentStatus } from '../common/index.js'
+import type { RunExecutionStatus } from '../common/index.js'
 import type { PendingDecision } from '../hitl/index.js'
 import type { RunStatus } from './status.js'
 
@@ -6,7 +6,7 @@ import type { RunStatus } from './status.js'
  * Project what the SDK records about a run onto the session-layer
  * {@link RunStatus}.
  *
- * `Run.status` is an {@link AgentStatus} — six values, none of which can
+ * `Run.status` is an {@link RunExecutionStatus} — six values, none of which can
  * say "a human owes this run an answer". `RunStatus` has the vocabulary for
  * that and is consumed by session-status derivation and by handoff gating,
  * but nothing in the repo ever produced it: a host implementing a resolver
@@ -21,7 +21,7 @@ import type { RunStatus } from './status.js'
  */
 export function deriveRunStatus(input: {
 	/** What the run itself recorded. */
-	readonly status: AgentStatus
+	readonly status: RunExecutionStatus
 	/** The run's outstanding park, if it has one. */
 	readonly park?: PendingDecision
 	/** Injectable for tests; defaults to now. */

package/src/types/run/entity.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 } from '../ids/index.js'
 import type { Message } from '../message/index.js'
 import type { ProviderErrorInfo } from '../provider/index.js'
@@ -52,8 +52,6 @@ export interface RunStateMetadata {
 	servingProvider?: string
 }
 
-export type SessionMetadata = RunStateMetadata
-
 /**
  * Domain Run entity — the persistence record for a single agent invocation
  * under a {@link import('../session/entity.js').Session}. Renamed from
@@ -67,7 +65,7 @@ export type SessionMetadata = RunStateMetadata
  */
 export interface Run {
 	id: RunId
-	status: AgentStatus
+	status: RunExecutionStatus
 	metadata: RunStateMetadata
 	messages: Message[]
 	tokenUsage: TokenUsage

package/src/types/run/event-cursor.ts

@@ -9,7 +9,7 @@
  * subscription rather than to a capability.
  */
 
-import type { ClaimFence } from './checkpoint-store.js'
+import type { FencingToken } from './checkpoint-store.js'
 import type { PersistedRunEvent } from './events.js'
 
 /** What a consumer holds when it comes back. */
@@ -27,7 +27,7 @@ export interface RunEventCursor {
 	 * mismatch: it is an unfenced run, where the sequence is the only evidence
 	 * available and the log persisting is the assumption.
 	 */
-	readonly generation?: ClaimFence
+	readonly generation?: FencingToken
 }
 
 /** Why a cursor could not be honoured. */
@@ -68,7 +68,7 @@ export interface RunEventLogHead {
 	/** Highest sequence in the log; zero when it is empty. */
 	readonly lastSeq: number
 	/** The fence the run is being written under, when it holds a claim. */
-	readonly generation?: ClaimFence
+	readonly generation?: FencingToken
 }
 
 /**

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.
  *