@namzu/sdk 34.2.0 → 35.0.0

package/src/types/run/emergency.ts

@@ -2,8 +2,13 @@ import { z } from 'zod'
 import type { TokenUsage } from '../common/index.js'
 import type { EmergencySaveId, RunId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
+import type { TokenBudgetBinding } from './token-budget-store.js'
 
 export interface EmergencySaveData {
+	/** Reference to the canonical tree ledger; a checkpoint never resets it. */
+	readonly budgetBinding?: TokenBudgetBinding
+	/** Also present for non-durable accounts; those require the live authority on resume. */
+	readonly budgetAccountId?: string
 	id: EmergencySaveId
 	runId: RunId
 	messages: Message[]

package/src/types/run/entity.ts

@@ -1,3 +1,4 @@
+import type { TokenBudgetSummary } from '../../run/token-budget.js'
 import type { CostInfo, RunExecutionStatus, TokenUsage } from '../common/index.js'
 import type { RunId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
@@ -6,6 +7,7 @@ import type { AgentRunConfig } from './config.js'
 import type { ReplayAttribution } from './replay.js'
 import type { StepResult } from './step.js'
 import type { StopReason } from './stop-reason.js'
+import type { TokenBudgetBinding } from './token-budget-store.js'
 
 export interface RunStateMetadata {
 	agentId: string
@@ -60,15 +62,17 @@ export interface RunStateMetadata {
  *
  * The wire counterpart is `WireRun` under `contracts/api.ts` — the two stay
  * decoupled so the HTTP field shape can evolve independently from this
- * persistence record. See `docs/sdk/sessions/` for the public hierarchy
- * reference.
+ * persistence record.
  */
 export interface Run {
 	id: RunId
 	status: RunExecutionStatus
 	metadata: RunStateMetadata
 	messages: Message[]
+	/** Usage of this invocation only; descendant spend is in budget. */
 	tokenUsage: TokenUsage
+	budget?: TokenBudgetSummary
+	budgetBinding?: TokenBudgetBinding
 	costInfo: CostInfo
 	currentIteration: number
 	startedAt: number

package/src/types/run/events.ts

@@ -1,3 +1,4 @@
+import type { TokenBudgetSummary } from '../../run/token-budget.js'
 import type { ActivityStatus, ActivityType } from '../activity/index.js'
 import type { BaseAgentResult } from '../agent/base.js'
 import type { CostInfo, PlatformError, TokenUsage } from '../common/index.js'
@@ -245,6 +246,8 @@ type CoreRunEvent =
 			iteration: number
 			/** How many `tool_result` bodies were emptied. */
 			clearedCount: number
+			/** Assistant narrations cut to their first sentence by the salience pass, when it ran. */
+			stubbedCount?: number
 			/** Characters removed, summed across those results. */
 			charsReclaimed: number
 			/** `charsReclaimed` as tokens, by the same estimate the trigger uses. */
@@ -502,6 +505,7 @@ type CoreRunEvent =
 	  }
 	| {
 			type: 'run_paused'
+			budget?: TokenBudgetSummary
 			runId: RunId
 			checkpointId: CheckpointId
 			reason: string
@@ -550,8 +554,38 @@ 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.
 	 */
+	/**
+	 * What the run learned was written to the host's memory store: its
+	 * decisions, discoveries and failures as one entry a later run can
+	 * search for. Emitted only when a host asked (`consolidateInto`) and
+	 * the run had something to say.
+	 */
+	/**
+	 * A background job this run (or the owner it runs under) started has
+	 * ended. The model learns it from a notice on its next tool result;
+	 * the host learns it from this, whether or not a turn is running.
+	 */
+	| {
+			type: 'background_job_exited'
+			runId: RunId
+			jobId: string
+			command: string
+			status: 'exited' | 'killed'
+			exitCode?: number
+			signal?: string
+	  }
+	| {
+			type: 'memory_consolidated'
+			runId: RunId
+			memoryId: string
+			title: string
+			decisions: number
+			discoveries: number
+			failures: number
+	  }
 	| {
 			type: 'run_completed'
+			budget?: TokenBudgetSummary
 			runId: RunId
 			result: string
 			stopReason?: StopReason
@@ -581,6 +615,7 @@ type CoreRunEvent =
 	 */
 	| {
 			type: 'run_failed'
+			budget?: TokenBudgetSummary
 			runId: RunId
 			error: string
 			failure?: PlatformError
@@ -638,6 +673,8 @@ type CoreRunEvent =
 	  }
 	| {
 			type: 'token_usage_updated'
+			/** Aggregate tree spend, distinct from this run's own usage. */
+			budget?: TokenBudgetSummary
 			runId: RunId
 			usage: TokenUsage
 			cost: CostInfo

package/src/types/run/index.ts

@@ -18,6 +18,7 @@ export * from './events.js'
 export * from './metadata.js'
 export * from './emergency.js'
 export * from './state.js'
+export * from './token-budget-store.js'
 export type { Lineage } from './lineage.js'
 export type {
 	SubsessionIdledEvent,

package/src/types/run/state.ts

@@ -1,9 +1,19 @@
+import {
+	asCheckpointId,
+	asProjectId,
+	asRunId,
+	asSessionId,
+	asTenantId,
+	asTopicId,
+} from '../../utils/id.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, TopicId } from '../session/ids.js'
 import type { StopReason } from './stop-reason.js'
+import { validateTokenBudgetBinding } from './token-budget-store.js'
+import type { TokenBudgetBinding } from './token-budget-store.js'
 
 /**
  * Everything needed to pick a run back up in a DIFFERENT process.
@@ -24,17 +34,17 @@ import type { StopReason } from './stop-reason.js'
  * host's job on the way back in, which is exactly why they are absent.
  */
 export interface RunState {
+	/** Reference to the canonical tree ledger; a checkpoint never resets it. */
+	readonly budgetBinding?: TokenBudgetBinding
+	/** Also present for non-durable accounts; those require the live authority on resume. */
+	readonly budgetAccountId?: string
 	/**
-	 * 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.
+	 * Schema version. Versions 1–3 are coerced forward by {@link parseRunState}.
+	 * Version 4 carries aggregate token authority references; earlier readers
+	 * must refuse it rather than silently discarding that authority on resume.
+	 * Other unrecognized versions are refused instead of partially restored.
 	 */
-	readonly version: 3
+	readonly version: 4
 
 	readonly runId: RunId
 	readonly sessionId: SessionId
@@ -92,7 +102,7 @@ export class RunStateVersionError extends Error {
 	}
 }
 
-export const RUN_STATE_VERSION = 3 as const
+export const RUN_STATE_VERSION = 4 as const
 
 /** The shape `RunState` had before NZ-TOPIC-03: `threadId`, not `topicId`. */
 const RUN_STATE_LEGACY_VERSION = 1
@@ -104,17 +114,27 @@ const RUN_STATE_LEGACY_VERSION = 1
  */
 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)}` }
+/** Before checkpoints referred to a canonical aggregate token ledger. */
+const RUN_STATE_PRE_BUDGET_VERSION = 3
+
+/** Require UUIDs on every supplied identity field without rewriting records. */
+function requireEntityIds(record: Record<string, unknown>): Record<string, unknown> {
+	if (record.budgetBinding !== undefined) validateTokenBudgetBinding(record.budgetBinding)
+	if (record.budgetAccountId !== undefined) asRunId(record.budgetAccountId as string)
+	const validators = {
+		runId: asRunId,
+		parentRunId: asRunId,
+		sessionId: asSessionId,
+		projectId: asProjectId,
+		tenantId: asTenantId,
+		topicId: asTopicId,
+		checkpointId: asCheckpointId,
+	}
+	for (const [field, validate] of Object.entries(validators)) {
+		const value = record[field]
+		if (value !== undefined) validate(value as string)
+	}
+	return record
 }
 
 /**
@@ -125,15 +145,15 @@ function rewriteLegacyTopicIdPrefix(record: Record<string, unknown>): Record<str
  * 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 — for
- * every version this build does not otherwise recognize. Versions 1 and 2
- * are the exceptions: both are coerced forward rather than refused, the
+ * every version this build does not otherwise recognize. Versions 1 through 3
+ * are the exceptions: they 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.
+ * topic IDs are validated without changing their value. Retired `thd_`
+ * values are refused; opaque UUIDs
+ * are preserved. An absent topic field is not added.
  * 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,
@@ -151,6 +171,14 @@ export function parseRunState(json: string | unknown): RunState {
 	}
 	const record = raw as Record<string, unknown>
 	const version = record.version
+	if (
+		(version === RUN_STATE_LEGACY_VERSION ||
+			version === RUN_STATE_PRE_PREFIX_VERSION ||
+			version === RUN_STATE_PRE_BUDGET_VERSION) &&
+		(record.budgetBinding !== undefined || record.budgetAccountId !== undefined)
+	) {
+		throw new RunStateVersionError(version, RUN_STATE_VERSION)
+	}
 
 	if (version === RUN_STATE_LEGACY_VERSION) {
 		const { threadId, ...rest } = record
@@ -159,14 +187,14 @@ export function parseRunState(json: string | unknown): RunState {
 			...(threadId !== undefined ? { topicId: threadId } : {}),
 		}
 		return {
-			...rewriteLegacyTopicIdPrefix(withTopicId),
+			...requireEntityIds(withTopicId),
 			version: RUN_STATE_VERSION,
 		} as RunState
 	}
 
-	if (version === RUN_STATE_PRE_PREFIX_VERSION) {
+	if (version === RUN_STATE_PRE_PREFIX_VERSION || version === RUN_STATE_PRE_BUDGET_VERSION) {
 		return {
-			...rewriteLegacyTopicIdPrefix(record),
+			...requireEntityIds(record),
 			version: RUN_STATE_VERSION,
 		} as RunState
 	}
@@ -174,5 +202,5 @@ export function parseRunState(json: string | unknown): RunState {
 	if (version !== RUN_STATE_VERSION) {
 		throw new RunStateVersionError(version, RUN_STATE_VERSION)
 	}
-	return raw as RunState
+	return requireEntityIds(record) as unknown as RunState
 }

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

@@ -17,19 +17,8 @@ export type StopReason =
 	 * declaring one, arriving at a model the price catalogue has no row for.
 	 * `costInfo.unpricedTokens` says how much of the run it covers.
 	 *
-	 * ## The closing call is outside the budget, deliberately
-	 *
-	 * Every hard stop is followed by one more model call — `requestFinalResponse`
-	 * asks for a closing summary, and the guard does not run again before or
-	 * after it. That is pre-existing and true of `cost_limit` and
-	 * `token_budget` alike, and it is stated here rather than left to be
-	 * discovered because for THIS reason it cannot be otherwise: the model that
-	 * triggered the stop is by definition one with no rate, so the closing
-	 * call's cost is unmeasurable by construction. Bounding it would mean
-	 * refusing to close the run at all, which loses the work.
-	 *
-	 * Its tokens are counted, so `costInfo.unpricedTokens` includes them and
-	 * the run reports honestly what it could not price.
+	 * A hard stop issues no further model request. Completed messages and
+	 * tool results remain in the run even when no closing prose was produced.
 	 */
 	| 'cost_unmeasurable'
 	| 'timeout'
@@ -71,7 +60,7 @@ export type StopReason =
  *
  * The union of the finish reasons providers report, normalised into a
  * provider-agnostic vocabulary. `forced_finalize` is a Namzu-specific value
- * emitted by the orchestrator when iteration limits force a final response
+ * emitted by the orchestrator when budget warnings request a final response
  * without a model-issued stop reason.
  */
 export type MessageStopReason =

package/src/types/run/token-budget-store.ts

@@ -0,0 +1,54 @@
+import type { TokenBudgetSnapshot } from '../../run/token-budget.js'
+import { entityIdPattern } from '../../utils/id-format.js'
+import { asProjectId, asRunId, asSessionId, asTenantId } from '../../utils/id.js'
+import type { ProjectId, RunId, SessionId, TenantId } from '../ids/index.js'
+
+/** The root run owns the ledger, including every descendant account. */
+export interface TokenBudgetScope {
+	readonly tenantId: TenantId
+	readonly projectId: ProjectId
+	readonly sessionId: SessionId
+	readonly runId: RunId
+}
+
+/** JSON-safe checkpoint reference; the latest ledger remains authoritative. */
+export interface TokenBudgetBinding {
+	readonly scope: TokenBudgetScope
+	readonly accountId: string
+}
+
+/**
+ * Durable storage for one canonical token ledger per root run.
+ *
+ * A root and all its descendants share one writer. Save must atomically
+ * replace a complete record; a missing record is null and corrupt records
+ * throw. This interface provides no compare-and-swap or distributed lease.
+ * Hosts must ensure exclusive root ownership when resuming in another process.
+ */
+export interface TokenBudgetStore {
+	load(scope: TokenBudgetScope): Promise<TokenBudgetSnapshot | null>
+	save(scope: TokenBudgetScope, snapshot: TokenBudgetSnapshot): Promise<void>
+}
+
+/** Validate an untrusted checkpoint reference without inventing missing identity. */
+export function validateTokenBudgetBinding(value: unknown): TokenBudgetBinding {
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+		throw new Error('Invalid token budget binding')
+	}
+	const binding = value as Partial<TokenBudgetBinding>
+	if (typeof binding.accountId !== 'string' || !entityIdPattern().test(binding.accountId)) {
+		throw new Error('Invalid token budget account identity')
+	}
+	if (typeof binding.scope !== 'object' || binding.scope === null) {
+		throw new Error('Token budget binding is missing its root scope')
+	}
+	return {
+		accountId: binding.accountId,
+		scope: {
+			tenantId: asTenantId(binding.scope.tenantId),
+			projectId: asProjectId(binding.scope.projectId),
+			sessionId: asSessionId(binding.scope.sessionId),
+			runId: asRunId(binding.scope.runId),
+		},
+	}
+}

package/src/types/sandbox/index.ts

@@ -206,6 +206,19 @@ export interface SandboxNetworkPolicy {
 	readonly allowedHosts: readonly string[]
 }
 
+/** A process the sandbox started and does not wait for; see `Sandbox.spawnDetached`. */
+export interface SandboxDetachedProcess {
+	/** The wrapper process. Its stdout and stderr are pipes the caller reads; stdin is closed. */
+	readonly child: import('node:child_process').ChildProcess
+	/** Signal everything the sandbox started for this process, inside the boundary and out. */
+	kill(signal: NodeJS.Signals): void
+}
+
+export interface SandboxSpawnOptions {
+	readonly cwd?: string
+	readonly env?: Record<string, string>
+}
+
 export interface Sandbox {
 	readonly id: SandboxId
 	readonly status: SandboxStatus
@@ -213,6 +226,19 @@ export interface Sandbox {
 	readonly environment: SandboxEnvironment
 	exec(command: string, args?: string[], opts?: SandboxExecOptions): Promise<SandboxExecResult>
 
+	/**
+	 * Start a process inside the boundary and hand it back running, for a
+	 * host that keeps long-lived processes — a background job registry.
+	 * The same confinement as `exec`; the difference is who waits. A
+	 * provider without this cannot host background jobs, and the tools
+	 * say so rather than running the job on the host.
+	 */
+	spawnDetached?(
+		command: string,
+		args?: readonly string[],
+		opts?: SandboxSpawnOptions,
+	): SandboxDetachedProcess
+
 	/**
 	 * Narrow or widen what this sandbox can reach, while it is running.
 	 *
@@ -467,6 +493,12 @@ export interface SandboxCreateConfig {
 	 */
 	readonly signal?: AbortSignal
 	readonly workingDirectory?: string
+	/**
+	 * Directories bound into the sandbox read-write besides the working
+	 * directory, absolute on the host. Only meaningful with
+	 * `workingDirectory`; an ephemeral root has nothing to add to.
+	 */
+	readonly additionalDirectories?: readonly string[]
 	readonly env?: Record<string, string>
 	readonly timeoutMs?: number
 	readonly memoryLimitMb?: number

package/src/types/session/store.ts

@@ -34,6 +34,14 @@ import type { ProjectId, SubSessionId, SummaryId, TopicId } from '../session/ids
  * tracks both.
  */
 export interface CreateSessionParams {
+	/**
+	 * The id the session is created under. A host that needs to know a
+	 * conversation's id before the conversation is written — to name a
+	 * log, to label a hook, to show it — mints one with `generateSessionId`
+	 * and passes it here; the store refuses an id it already holds. Absent,
+	 * the store mints one.
+	 */
+	id?: SessionId
 	topicId: TopicId
 	projectId: ProjectId
 	/**

package/src/types/tool/index.ts

@@ -223,6 +223,13 @@ export interface ToolDispatchOptions {
 export interface ToolContext {
 	runId: RunId
 	workingDirectory: string
+	/**
+	 * Directories besides the working directory the file tools may reach,
+	 * absolute. A host adds one for a session (`/add-dir`); a sandboxed run
+	 * binds each. Relative paths still resolve against the working
+	 * directory; an absolute path inside any of these is accepted.
+	 */
+	additionalDirectories?: readonly string[]
 	abortSignal: AbortSignal
 	env: Record<string, string>
 	log: (level: 'info' | 'warn' | 'error', message: string) => void
@@ -490,6 +497,14 @@ export interface ToolResult {
 	 * what it sets here.
 	 */
 	retryable?: boolean
+	/**
+	 * Facts this result pins into the run's working memory, by key. The
+	 * kernel keeps them in the working-memory slot — in front of the model
+	 * every iteration, across compaction — and a later pin under the same
+	 * key replaces the earlier one. For what a tool knows and the model
+	 * must not lose: what its controls do, where things are, what failed.
+	 */
+	workingState?: readonly import('../../compaction/types.js').WorkingStatePin[]
 }
 
 export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInput> {

package/src/utils/frontmatter.ts

@@ -8,7 +8,7 @@
  * metadata**, so the same file was a hard error in one code path and a skill
  * named after its own directory with "(no description)" in the other. Refuse
  * versus degrade, on one file shape, is the divergence this module exists to
- * end — see `docs/conventions/refuse-do-not-degrade.md`.
+ * end — see "refuse do not degrade".
  *
  * **Deliberately not a YAML parser.** It is a flat key/value splitter with one
  * level of nesting, and it refuses the constructs in {@link UNSUPPORTED_YAML}

package/src/utils/id-format.ts

@@ -0,0 +1,9 @@
+const HEX = '[0-9a-fA-F]'
+const UUID = `${HEX}{8}-${HEX}{4}-[1-8]${HEX}{3}-[89abAB]${HEX}{3}-${HEX}{12}`
+
+/** Internal shared spelling rule for runtime checks and JSON-schema-compatible schemas. */
+export function entityIdPattern(): RegExp {
+	// JavaScript's $ also matches before a final newline. The final lookahead
+	// requires the actual end so no accepted id can carry a control character.
+	return new RegExp(String.raw`^${UUID}$(?![\s\S])`)
+}