@namzu/sdk 43.0.0 → 44.0.0

package/src/types/run/state.ts

@@ -1,206 +0,0 @@
-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.
- *
- * A run's live state was spread across objects that only exist in memory —
- * `RunPersistence`, `GuardCoordinator`, the suspended `await` inside a HITL
- * gate. `IterationCheckpoint` carries the history and the budgets, but it
- * is keyed by a store scope the reader has to already know, and it says
- * nothing about the run's status or why it stopped. So "resume this run"
- * meant "the original process is still alive and holding it".
- *
- * That is the constraint this removes. `RunState` is a flat, JSON-safe
- * snapshot: a serverless handler writes one when a run parks, returns, and
- * a later invocation — a different container — reads it back and continues.
- *
- * It is a SNAPSHOT, not a live handle. Nothing in it points at a socket, a
- * sandbox, a provider client, or an open file. Re-establishing those is the
- * 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. 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: 4
-
-	readonly runId: RunId
-	readonly sessionId: SessionId
-	readonly topicId: TopicId
-	readonly projectId: ProjectId
-	readonly tenantId: TenantId
-	/** Present for sub-runs, so a hierarchical store can key the snapshot. */
-	readonly parentRunId?: RunId
-
-	readonly agentId?: string
-	readonly agentName?: string
-
-	readonly status: RunExecutionStatus
-	readonly stopReason?: StopReason
-	readonly lastError?: string
-
-	readonly messages: Message[]
-	readonly tokenUsage: TokenUsage
-	readonly costInfo: CostInfo
-	readonly currentIteration: number
-	readonly startedAt: number
-	/**
-	 * Wall-clock the run has already consumed. Restored into the guard so a
-	 * resumed run does not get a fresh timeout budget — the timeout is a
-	 * property of the RUN, not of the process hosting it.
-	 */
-	readonly elapsedMs: number
-
-	/**
-	 * The checkpoint this snapshot corresponds to, when one was written.
-	 * Pass it as `resumeFromCheckpoint`.
-	 */
-	readonly checkpointId?: CheckpointId
-
-	/**
-	 * The decision the run is parked on, if any. A host reads this to know
-	 * what to ask a human, and feeds the answer back as
-	 * `QueryParams.pendingDecision`.
-	 */
-	readonly pending?: PendingDecision
-
-	readonly capturedAt: number
-}
-
-/** Thrown by {@link parseRunState} when a snapshot cannot be trusted. */
-export class RunStateVersionError extends Error {
-	constructor(
-		readonly found: unknown,
-		readonly expected: number,
-	) {
-		super(
-			`RunState version mismatch: snapshot declares ${JSON.stringify(found)}, this SDK reads ${expected}. Restoring across an incompatible version would silently drop fields; re-run instead.`,
-		)
-		this.name = 'RunStateVersionError'
-	}
-}
-
-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
-
-/**
- * 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
-
-/** 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
-}
-
-/**
- * Parse a serialized snapshot, refusing anything this SDK cannot fully
- * restore.
- *
- * 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 — for
- * 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
- * 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,
- * 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 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
-		const withTopicId = {
-			...rest,
-			...(threadId !== undefined ? { topicId: threadId } : {}),
-		}
-		return {
-			...requireEntityIds(withTopicId),
-			version: RUN_STATE_VERSION,
-		} as RunState
-	}
-
-	if (version === RUN_STATE_PRE_PREFIX_VERSION || version === RUN_STATE_PRE_BUDGET_VERSION) {
-		return {
-			...requireEntityIds(record),
-			version: RUN_STATE_VERSION,
-		} as RunState
-	}
-
-	if (version !== RUN_STATE_VERSION) {
-		throw new RunStateVersionError(version, RUN_STATE_VERSION)
-	}
-	return requireEntityIds(record) as unknown as RunState
-}

package/src/types/run/status.ts

@@ -1,33 +0,0 @@
-/**
- * Domain Run status enum. See session-hierarchy.md §4.6 + §5.2 state machine.
- *
- * Distinct from the wire-side {@link WireRunStatus} in `contracts/api.ts`,
- * which maps these states onto HTTP payload shapes (`completed` /
- * `cancelling` / `expired`). Keep this enum purely the domain surface; any
- * consumer that needs the HTTP representation should translate at the bridge
- * boundary.
- *
- * Variants:
- *  - `queued` — run created, not yet started.
- *  - `running` — iteration loop in flight.
- *  - `awaiting_hitl` — synchronous-wait on a HITL gate (user present).
- *  - `awaiting_hitl_resolution` — persisted-wait after a HITL timeout under
- *    `HITLConfig.onTimeout = 'pause_run_until_resolved'`. User absent; Run
- *    persists until resolved or cancelled (permission-policies.md §13.3).
- *  - `awaiting_subsession` — parent Run has delegated to a child SubSession
- *    and is suspended until the Materializer seals the child's summary.
- *    Session-level fan-in treats this as `active` (delegation in flight
- *    means the parent IS active). See session-hierarchy.md §5.1.
- *  - `succeeded` — terminal, run completed without error.
- *  - `failed` — terminal, run errored out.
- *  - `cancelled` — terminal, explicitly cancelled.
- */
-export type RunStatus =
-	| 'queued'
-	| 'running'
-	| 'awaiting_hitl'
-	| 'awaiting_hitl_resolution'
-	| 'awaiting_subsession'
-	| 'succeeded'
-	| 'failed'
-	| 'cancelled'

package/src/types/run/step.ts

@@ -1,217 +0,0 @@
-import type { CostInfo, TokenUsage } from '../common/index.js'
-import type { MessageId } from '../ids/index.js'
-import type { ProviderRoute, ToolCall } from '../message/index.js'
-import type { ProviderErrorCode } from '../provider/errors.js'
-
-/**
- * What one iteration of the agent loop did.
- *
- * None of this was reachable before. `Run` and `BaseAgentResult` have no
- * `steps[]`, so a host that persisted the returned `Run` — the natural
- * thing — permanently lost per-step attribution: answering "which step
- * cost the most" meant correlating raw `RunEvent`s by iteration number and
- * diffing cumulative counters, and per-tool duration was never emitted at
- * all. Every field here was already computed somewhere in the loop.
- */
-export interface StepResult {
-	/** 1-based, matching `iteration` on the run events. */
-	stepNumber: number
-	/**
-	 * The model this step ASKED for: the run's configured model, or the
-	 * override a `prepareStep` hook returned for this step.
-	 *
-	 * It used to be the run's model unconditionally — the loop passed its own
-	 * `model` here while building the request from `step.model ?? model` a few
-	 * lines above — so a host that routed one step to a cheaper model read the
-	 * expensive one back out of the ledger. No chain was needed to see it.
-	 *
-	 * What was asked for and what answered are two facts, and after a provider
-	 * chain falls over they differ. This is the first; {@link servedBy} is the
-	 * second.
-	 */
-	model: string
-	/**
-	 * Who actually answered, and with which model.
-	 *
-	 * Equal to {@link model} and to `run.metadata.provider` on every run
-	 * without a chain, which is most of them; it diverges exactly when
-	 * `withProviderFallback` advanced. Recorded even when it agrees, because a
-	 * ledger that carries the fact only when it is surprising cannot be read as
-	 * evidence — a reader could not tell "the head served" from "nobody wrote
-	 * it down".
-	 *
-	 * Optional only for records that predate the field. Absence means "not
-	 * recorded", and it is left meaning that rather than backfilled: the sdk
-	 * shipped a chain that could fall over one release before it recorded
-	 * which member did, so filling those in from the declared head would state
-	 * as fact the exact thing that release got wrong, on exactly the runs
-	 * where it was wrong. Every step this build produces has it.
-	 *
-	 * **Reaches a host through the returned `Run`, not through `run.json`.**
-	 * `RunDiskStore.writeRunMeta` persists the metadata and the counters and
-	 * does not write `steps` at all, so the built-in store carries the
-	 * run-level {@link
-	 * import('./entity.js').RunStateMetadata.servingProvider} and none of
-	 * this. A host that wants per-step provenance on disk persists the `Run`
-	 * it is handed.
-	 */
-	servedBy?: StepProvenance
-	/**
-	 * The assistant message this step produced.
-	 *
-	 * Absent only on a step whose iteration ended before the model's message
-	 * was announced — a compaction failure, a lifecycle hook that threw, a
-	 * transport error raised before the first chunk. Absence is left meaning
-	 * "there was no message" rather than filled with an id the event stream
-	 * never carried: a `messageId` a reader cannot find a `message_started`
-	 * for is worse evidence than no id at all, because it invites the
-	 * correlation and then loses it.
-	 *
-	 * Present, and correlatable, on every step whose iteration got as far as
-	 * the provider call — including one that failed mid-stream. The loop
-	 * mints the id before the call that announces it, and a dying stream
-	 * emits `message_completed` on its way out, so the events carry both
-	 * ends of the message a failed step points at.
-	 */
-	messageId?: MessageId
-	/** Assistant text for this step, if any. */
-	content: string | null
-	toolCalls: readonly ToolCall[]
-	/**
-	 * Tool outcomes, in the same order as `toolCalls`.
-	 *
-	 * Shorter than `toolCalls` on a step that ended in failure: only the
-	 * outcomes that exist are recorded, so a call with no entry here reads
-	 * as "never came back" rather than as an empty success. Pair by
-	 * `toolCallId`, not by index.
-	 */
-	toolResults: readonly StepToolResult[]
-	/**
-	 * How the turn ended.
-	 *
-	 * `error` and `cancelled` are not provider verdicts — no provider reports
-	 * them — but a step exists for a failed iteration too, and it has to say
-	 * how it ended in the same field a reader already sorts by. `error` comes
-	 * with {@link failure}; `cancelled` means a Stop tore the turn down and
-	 * there is no failure to report.
-	 */
-	finishReason: 'stop' | 'tool_calls' | 'length' | 'content_filter' | 'error' | 'cancelled'
-	/**
-	 * What went wrong, on a step with `finishReason: 'error'`.
-	 *
-	 * Absent everywhere else. A run whose ledger is complete except on the
-	 * turns that failed reads as "nothing went wrong" precisely when
-	 * something did, which is worse than an absent record — so the failed
-	 * turn gets the same record as every other, and this is what makes it
-	 * legible as a failure.
-	 */
-	failure?: StepFailure
-	/** Usage for THIS step, not the run's cumulative total. */
-	usage: TokenUsage
-	/** Cost delta attributable to this step. Zero without a pricing table. */
-	costDelta: CostInfo
-	startedAt: number
-	/** Wall-clock for the whole step, including tool execution. */
-	durationMs: number
-	/** Portion of `durationMs` spent inside tools. */
-	toolExecutionMs: number
-}
-
-/**
- * The chain member that served one step.
- *
- * `chainIndex` is a position in the chain the host declared, and it is here
- * rather than derived from `providerId` because a chain may legitimately name
- * the same provider twice — two models, or two credentials, on one driver.
- * `providerId` alone could not tell those apart.
- */
-export interface StepProvenance extends ProviderRoute {}
-
-/**
- * Why a step ended in `finishReason: 'error'`.
- *
- * The step-level counterpart of the pair a failed run already carries —
- * {@link import('./entity.js').Run.lastError} and
- * {@link import('./entity.js').Run.lastProviderError} — and shaped from the
- * same classification, so the two agree when the failed step is the one that
- * ended the run. What a run records once, a run of twenty iterations records
- * per iteration, which is the difference between "this run failed" and "this
- * turn failed, and the next four succeeded".
- */
-export interface StepFailure {
-	/** The failure's message, as the iteration's span and log recorded it. */
-	readonly message: string
-	/**
-	 * Where the classifier placed it.
-	 *
-	 * `unknown` for a failure that is not a provider failure at all — a
-	 * plugin hook that threw, a bug in a tool wrapper. That is the honest
-	 * reading of the code's own contract ("unclassifiable"), and it is left
-	 * saying so rather than being given a more specific-looking code.
-	 */
-	readonly code: ProviderErrorCode
-	/** HTTP status, when the failure carried one. */
-	readonly status?: number
-	/** Whether sending the same request again could have worked. */
-	readonly retryable: boolean
-}
-
-export interface StepToolResult {
-	toolCallId: string
-	toolName: string
-	/** Text form, after the model-visible output budget was applied. */
-	output: string
-	isError: boolean
-	durationMs: number
-}
-
-/**
- * A programmable halt condition, evaluated after each step's tools have
- * run.
- *
- * `GuardCoordinator` — the only halt before this — consumes
- * `{aborted, totalTokens, totalCost, currentIteration, startTime}` and
- * never sees messages, tool calls or results. So "stop after three steps
- * with no progress" and "stop once the plan is complete" were
- * inexpressible, and a terminal `submit_answer` tool could not end the
- * run: the model had to be prompt-begged to stop, with `maxIterations:
- * 200` as the only backstop.
- *
- * Returning `true` ends the run with `stop_reason: 'stop_condition'`.
- */
-export type StopCondition = (state: StopConditionState) => boolean | Promise<boolean>
-
-export interface StopConditionState {
-	/** Every step so far, most recent last. */
-	readonly steps: readonly StepResult[]
-	readonly latestStep: StepResult
-	readonly totalUsage: TokenUsage
-	readonly totalCost: CostInfo
-}
-
-/** Stop once `n` steps have completed. */
-export function stepCountIs(n: number): StopCondition {
-	return ({ steps }) => steps.length >= n
-}
-
-/**
- * Stop when the latest step called any of `names`.
- *
- * The tool still executes and its result is still recorded — the run ends
- * after, not instead. That is what makes a `submit_answer` / `verify` tool
- * usable as a terminator without losing its output.
- */
-export function hasToolCall(...names: string[]): StopCondition {
-	const wanted = new Set(names)
-	return ({ latestStep }) => latestStep.toolCalls.some((tc) => wanted.has(tc.function.name))
-}
-
-/** Stop when any of the given conditions does. */
-export function anyOf(...conditions: StopCondition[]): StopCondition {
-	return async (state) => {
-		for (const condition of conditions) {
-			if (await condition(state)) return true
-		}
-		return false
-	}
-}

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

@@ -1,83 +0,0 @@
-export type StopReason =
-	| 'end_turn'
-	| 'token_budget'
-	| 'cost_limit'
-	/**
-	 * A `costLimitUsd` was set and part of the run ran at a rate nobody has, so
-	 * the limit could not be measured.
-	 *
-	 * Distinct from `cost_limit`, and the distinction is the reason this value
-	 * exists: nothing was overspent. Reporting `cost_limit` would send the
-	 * reader to look at spend that was never computed, and would hide the one
-	 * fact they need — that the budget they configured was unenforceable for
-	 * part of this run.
-	 *
-	 * `query()` refuses the same combination up front, so this is the case
-	 * preflight cannot see: a step naming its own model, or a chain member
-	 * declaring one, arriving at a model the price catalogue has no row for.
-	 * `costInfo.unpricedTokens` says how much of the run it covers.
-	 *
-	 * 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'
-	| 'max_iterations'
-	| 'cancelled'
-	| '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'
-	/**
-	 * A host reviewer kept rejecting the answer and the run ran out of
-	 * attempts.
-	 *
-	 * Distinct from a budget stop on purpose: without it the run would end
-	 * on `max_iterations` or a token cap, naming the resource it exhausted
-	 * rather than the judgement that exhausted it — and the reader would go
-	 * looking for a loop instead of at the reviewer.
-	 */
-	| 'answer_rejected'
-	/** An input guardrail refused the run before it started. */
-	| 'input_guardrail'
-	/** An output guardrail refused the produced result. */
-	| 'output_guardrail'
-	| 'paused'
-	| 'error'
-
-/**
- * Per-LLM-message stop reason — distinct from the run-level {@link 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 budget warnings request a final response
- * without a model-issued stop reason.
- */
-export type MessageStopReason =
-	| 'end_turn'
-	| 'tool_use'
-	| 'max_tokens'
-	| 'stop_sequence'
-	| 'pause_turn'
-	| 'refusal'
-	| 'forced_finalize'
-	/**
-	 * The turn was cancelled mid-stream.
-	 *
-	 * Also Namzu-specific, and added because the cancel path had no way to
-	 * close the message it had opened: it re-threw from inside the chunk
-	 * loop, so the terminal event never fired and a host consuming the
-	 * message lifecycle saw a message begin and never end. A turn that
-	 * stops is still a turn that finished streaming, whatever stopped it.
-	 */
-	| 'cancelled'