@namzu/sdk 27.0.0 → 28.0.0

package/src/types/run/audit.ts

@@ -0,0 +1,164 @@
+import type { CostInfo, RunExecutionStatus } from '../common/index.js'
+import type { AuditEventId, RunId, TenantId } from '../ids/index.js'
+
+/**
+ * What happened to the thing this event describes.
+ *
+ * `'refused'` is a VALUE, not an absent record — the whole reason this type
+ * exists rather than reusing whatever shape {@link import('./events.js').RunEvent}
+ * already had. Before this, a permission denial (the `AuthorizationGate`) and
+ * a guardrail block each produced nothing durable with cost/outcome/identity
+ * attached — the one outcome an auditor most needs was the one absent from
+ * the trail. See ses_020's logging design §5.
+ */
+export type AuditOutcome = 'success' | 'failure' | 'refused'
+
+/**
+ * Who acted, in the compliance-audit sense: the actor's identity and the
+ * tenant it acted under.
+ *
+ * `persona` is the label a host assigned the agent for THIS run — absent
+ * when the run was not configured with one (most runs today), and nothing
+ * here invents a value for it. Populated only at call sites that actually
+ * have a persona in scope (`runtime/query/index.ts`'s guardrail-block
+ * branches, via `params.persona?.identity.role`); a call site with no
+ * persona in scope (the verification-gate denial inside `tool-review.ts`)
+ * legitimately omits it rather than guessing.
+ */
+export interface AuditActor {
+	readonly agentId: string
+	readonly tenantId: TenantId
+	readonly persona?: string
+}
+
+/**
+ * What was attempted. `tool` is present for a tool-scoped action; absent for
+ * a run-level one (an input/output guardrail, the run's own completion or
+ * failure). `resource` names the thing the action targeted when that is
+ * narrower than the tool itself — a guardrail's own name, for instance.
+ *
+ * `action` is deliberately a free-text label, not a closed union: unlike
+ * `RunEvent['type']` (which a switch must exhaustively handle, per
+ * Convention #16), nothing here switches on `action` today, and closing it
+ * prematurely would be inventing a vocabulary nobody has asked to enumerate
+ * yet.
+ */
+export interface AuditAction {
+	readonly action: string
+	readonly tool?: string
+	readonly resource?: string
+}
+
+/**
+ * One entry in a run's audit trail — durable evidence of what the agent
+ * did, under whose identity, at what cost, and whether it was allowed.
+ *
+ * ## Why this is a SEPARATE trail from `RunEvent`
+ *
+ * See {@link import('./store.js').RunStore.appendAuditEvent}'s own doc and
+ * ses_020's logging design §5 for the full reasoning. In short: an
+ * operational log is level-filtered, sampled, rotatable and legitimately
+ * absent when no host installed a sink. None of that is acceptable for the
+ * kernel's own claim — "an auditable trail of what it did and what it
+ * cost", the README's sentence about itself.
+ *
+ * ## `seq` is this trail's OWN sequence space
+ *
+ * Independent of {@link import('./events.js').RunEvent}'s envelope `seq`,
+ * which numbers the (much higher-volume) operational transcript. Two logs,
+ * two cursors, and forcing them to share one counter would make an
+ * unrelated burst on one trail move the other's cursor — see
+ * `manager/run/persistence.ts`'s `_lastAuditSeq` for where this is held.
+ *
+ * ## `cost` is NON-OPTIONAL
+ *
+ * "What it did and what it cost" is the kernel's own sentence about itself
+ * (README) — an audit entry that cannot say what something cost has not
+ * answered the question it exists to answer. It carries the run's
+ * CUMULATIVE total AT THIS MOMENT, matching `Run.costInfo`'s own semantics
+ * (see `utils/cost.ts`'s `accumulateCost`: the field IS the running total,
+ * not a delta, so "the most recent entry carries the answer whole" is
+ * already how the derived summary treats it — see {@link replayRun}).
+ */
+export interface AuditEvent {
+	readonly id: AuditEventId
+	readonly runId: RunId
+	readonly seq: number
+	/** Epoch ms at which the store recorded the event. */
+	readonly timestamp: number
+	readonly who: AuditActor
+	readonly what: AuditAction
+	readonly outcome: AuditOutcome
+	readonly cost: CostInfo
+	/** Present on `'refused'` and `'failure'` — the reason a reader needs. */
+	readonly reason?: string
+	/**
+	 * The active span's identity at the moment this entry was recorded —
+	 * resolved the same way `utils/log/create-logger.ts`'s `emit` resolves
+	 * `LogRecord.traceId`/`spanId`: fresh per record, off the live
+	 * `@opentelemetry/api` global, never captured once and reused. Genuinely
+	 * absent — not `''`, not `'unknown'` — whenever nothing is active. See
+	 * `telemetry/runtime-accessors.ts`'s `getActiveSpanContext` for why.
+	 */
+	readonly traceId?: string
+	readonly spanId?: string
+}
+
+/**
+ * What a caller hands
+ * {@link import('../../manager/run/persistence.js').RunPersistence.recordAudit} —
+ * the fields ONLY the call site knows. `id`, `runId`, `seq`, `timestamp`,
+ * `who.agentId`/`who.tenantId` and `cost` are filled in by `recordAudit`
+ * itself from the run it is bound to; a caller supplying them would be
+ * asserting facts about identity and cost that only the run-persistence
+ * layer is positioned to know, and could disagree with what the run
+ * actually holds.
+ */
+export interface AuditEventInput {
+	readonly what: AuditAction
+	readonly outcome: AuditOutcome
+	readonly reason?: string
+	readonly persona?: string
+}
+
+/** What {@link replayRun} reconstructs from the trail alone. */
+export interface RunSummary {
+	readonly costInfo: CostInfo
+	readonly status: Extract<RunExecutionStatus, 'completed' | 'failed'>
+}
+
+/**
+ * Reconstruct a completed run's cost and status from its audit trail alone,
+ * with no read of the derived `Run` record.
+ *
+ * This is the verification ses_020's design promises (§5): `Run.costInfo`
+ * and `Run.status`, persisted through `RunStore.writeRunMeta`
+ * (`manager/run/persistence.ts:221`/`:569`), are a full-record overwrite
+ * with no `seq` and no prior-value retention — a DERIVED summary cache, not
+ * the evidence. The audit trail is the evidence, and a divergence between
+ * what this returns and what `Run.costInfo`/`Run.status` actually hold is a
+ * defect in the summary, never in the trail.
+ *
+ * Walks from the END rather than folding forward: `cost` on each entry is
+ * already the run's cumulative total (see {@link AuditEvent.cost}), so the
+ * most recent entry that actually SETTLES the run — `'success'` or
+ * `'failure'` — carries the answer whole. A `'refused'` entry is a single
+ * action inside a still-open run, never the run's own verdict, and is
+ * skipped rather than treated as terminal: otherwise a refusal that
+ * happened to be the last write before a crash would replay as the run's
+ * final status, which is not what it means.
+ *
+ * `undefined` when no terminal entry exists — a run still in progress, or
+ * one that crashed before a terminal write landed. Callers that need "no
+ * answer yet" and "diverges from the derived summary" to read differently
+ * should treat `undefined` as the former.
+ */
+export function replayRun(events: readonly AuditEvent[]): RunSummary | undefined {
+	for (let i = events.length - 1; i >= 0; i--) {
+		const event = events[i]
+		if (event === undefined) continue
+		if (event.outcome === 'success') return { costInfo: event.cost, status: 'completed' }
+		if (event.outcome === 'failure') return { costInfo: event.cost, status: 'failed' }
+	}
+	return undefined
+}

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,26 @@ 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.
+ */
+
+/** @deprecated Renamed to {@link RunLease}. Removed in the next major. */
+export type RunClaim = RunLease
+/** @deprecated Renamed to {@link FencingToken}. Removed in the next major. */
+export type ClaimFence = FencingToken
+/** @deprecated Renamed to {@link LeaseSummary}. Removed in the next major. */
+export type ClaimSummary = LeaseSummary
+
 /** 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 +382,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 +398,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 +532,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 +548,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
 }
 
 /**