@namzu/sdk 42.0.2 → 44.0.0

package/src/types/session/step.ts

@@ -0,0 +1,214 @@
+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. The returned turn and `BaseAgentResult`
+ * had no `steps[]`, so a host that persisted the returned turn — the natural
+ * thing — permanently lost per-step attribution: answering "which step
+ * cost the most" meant correlating raw `SessionEvent`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 turn events. */
+	stepNumber: number
+	/**
+	 * The model this step ASKED for: the turn's configured model, or the
+	 * override a `prepareStep` hook returned for this step.
+	 *
+	 * It used to be the turn'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 turn
+	 * 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 turns
+	 * where it was wrong. Every step this build produces has it.
+	 *
+	 * **Reaches a host through the returned `Turn`.** The session log records
+	 * the turn-level {@link import('./turn.js').TurnMetadata.servingProvider}
+	 * on `turn_completed.settlement`; a host that wants per-step provenance
+	 * on disk persists the `Turn` 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 turn 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 turn'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 turn already carries —
+ * {@link import('./turn.js').Turn.lastError} and
+ * {@link import('./turn.js').Turn.lastProviderError} — and shaped from the
+ * same classification, so the two agree when the failed step is the one that
+ * ended the turn. What a turn records once, a turn of twenty iterations records
+ * per iteration, which is the difference between "this turn 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 turn 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 turn 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/session/stop-reason.ts

@@ -0,0 +1,83 @@
+export type StopReason =
+	| 'end_turn'
+	| 'token_budget'
+	| 'cost_limit'
+	/**
+	 * A `costLimitUsd` was set and part of the turn 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 turn.
+	 *
+	 * `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 turn it covers.
+	 *
+	 * A hard stop issues no further model request. Completed messages and
+	 * tool results remain in the turn 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 turn ran out of
+	 * attempts.
+	 *
+	 * Distinct from a budget stop on purpose: without it the turn 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 turn before it started. */
+	| 'input_guardrail'
+	/** An output guardrail refused the produced result. */
+	| 'output_guardrail'
+	| 'paused'
+	| 'error'
+
+/**
+ * Per-LLM-message stop reason — distinct from the turn-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'

package/src/types/session/store.ts

@@ -9,7 +9,6 @@
 import type { Project, ProjectStatus } from '../../types/project/entity.js'
 import type { ActorRef } from '../../types/session/actor.js'
 import type { Session } from '../../types/session/entity.js'
-import type { SessionMessage } from '../../types/session/messages.js'
 import type {
 	CompletionMode,
 	FailureMode,
@@ -17,8 +16,7 @@ import type {
 	SubSessionKind,
 } from '../../types/session/sub-session.js'
 import type { SessionSummaryRef } from '../../types/summary/ref.js'
-import type { MessageId, SessionId, TenantId } from '../ids/index.js'
-import type { Message } from '../message/index.js'
+import type { SessionId, TenantId } from '../ids/index.js'
 import type { ProjectId, SubSessionId, SummaryId, TopicId } from '../session/ids.js'
 
 /**
@@ -46,7 +44,7 @@ export interface CreateSessionParams {
 	projectId: ProjectId
 	/**
 	 * Initial owner of the session. May be `null` for bootstrap scenarios where
-	 * the first Run attaches an actor; the store rejects mutations against
+	 * the first turn attaches an actor; the store rejects mutations against
 	 * actor-less sessions from downstream consumers.
 	 */
 	currentActor: ActorRef | null
@@ -320,54 +318,9 @@ export interface SessionStore {
 	 */
 	deleteSubSession(subSessionId: SubSessionId, tenantId: TenantId): Promise<void>
 
-	// Messages -----------------------------------------------------------------
-
-	/**
-	 * Append a single message to the session's message log. Returns the
-	 * assigned {@link MessageId}. Write is append-only; the store never
-	 * rewrites or reorders previously persisted messages.
-	 */
-	appendMessage(sessionId: SessionId, message: Message, tenantId: TenantId): Promise<MessageId>
-
-	/**
-	 * Replace the conversation view with a compacted history. OPTIONAL.
-	 *
-	 * This is not deletion of the underlying log. A durable implementation may
-	 * append one replacement record and project every later read from it, which
-	 * keeps the write atomic while preserving the earlier records for recovery.
-	 *
-	 * Optional because existing hosts implement this interface, and manual
-	 * compaction is a host capability rather than a requirement every store must
-	 * gain. A caller that offers durable compaction checks for it and refuses to
-	 * claim persistence when the store cannot perform the replacement.
-	 */
-	replaceMessages?(
-		sessionId: SessionId,
-		messages: readonly Message[],
-		tenantId: TenantId,
-	): Promise<void>
-
-	/**
-	 * Load the full message history for a session in insertion order.
-	 * Returns an empty array when the session has no messages.
-	 *
-	 * Returns payload-only {@link Message} records. Callers that need the
-	 * full persistence envelope (including {@link MessageId} and timestamp)
-	 * should use {@link SessionStore.loadSessionMessages} instead.
-	 */
-	loadMessages(sessionId: SessionId, tenantId: TenantId): Promise<readonly Message[]>
-
-	/**
-	 * Load the full {@link SessionMessage} envelope for every persisted
-	 * message in insertion order (Phase 9 Known Delta #7). Unlike
-	 * {@link SessionStore.loadMessages} this preserves the original
-	 * {@link MessageId} and timestamp — required for full-fidelity archival
-	 * round-trips via {@link ArchivalManager.archive}.
-	 *
-	 * Returns an empty array when the session has no messages; cross-tenant
-	 * reads reject with `TenantIsolationError` (Convention #17).
-	 */
-	loadSessionMessages(sessionId: SessionId, tenantId: TenantId): Promise<readonly SessionMessage[]>
+	// Messages are not on this contract. They live in the session log and are
+	// read through `foldSessionMessages(log)`; only `TurnRecorder` writes them,
+	// under the session lease.
 
 	// Linkage (pattern doc §10.4 / §14.3) ------------------------------------
 

package/src/types/session/tool-execution.ts

@@ -0,0 +1,32 @@
+/**
+ * Tool calls a turn already executed, recovered from the session log.
+ *
+ * A batch's results reach the message history only once the WHOLE batch
+ * settles, so a hard kill part-way through loses every result that had
+ * already come back, and a resumed turn would re-execute those calls. For a
+ * file write that is waste; for a payment or an email it is a second one.
+ * These shapes are what the resume path reads to avoid that.
+ */
+
+/** One finished tool call, recovered from the session log. */
+export interface CompletedToolRecord {
+	readonly toolUseId: string
+	readonly toolName: string
+	readonly result: string
+	readonly isError: boolean
+}
+
+/** The latest recorded execution boundary of a tool call, not its inferred external effect. */
+export type ToolExecutionRecord =
+	| (CompletedToolRecord & { readonly status: 'completed' })
+	| { readonly toolUseId: string; readonly toolName: string; readonly status: 'started' }
+
+/**
+ * Absence proves no recorded start only when the whole selected log is
+ * complete. A started call without a completion has an unknown outcome and
+ * must not be replayed automatically.
+ */
+export interface ToolExecutionSnapshot {
+	readonly complete: boolean
+	readonly records: ReadonlyMap<string, ToolExecutionRecord>
+}

package/src/types/session/turn-state.ts

@@ -0,0 +1,136 @@
+import {
+	asCheckpointId,
+	asProjectId,
+	asSessionId,
+	asTenantId,
+	asTopicId,
+	asTurnId,
+} from '../../utils/id.js'
+import type { CostInfo, TokenUsage } from '../common/index.js'
+import type { CheckpointId, PendingDecision } from '../hitl/index.js'
+import type { SessionId, TenantId, TurnId } from '../ids/index.js'
+import type { Message } from '../message/index.js'
+import type { ProjectId, TopicId } from './ids.js'
+import type { StopReason } from './stop-reason.js'
+import type { TurnBudgetBinding, TurnExecutionStatus } from './turn.js'
+
+/**
+ * Everything needed to pick a turn back up in a DIFFERENT process.
+ *
+ * A flat, JSON-safe snapshot: a serverless handler writes one when a turn
+ * parks, returns, and a later invocation — a different container — reads it
+ * back and continues the SAME turn (`resumeSession`).
+ *
+ * It is a SNAPSHOT, not a live handle. Nothing in it points at a socket, a
+ * sandbox, a provider client, or an open file. `messages` is the fold of the
+ * session log through the checkpoint.
+ */
+export interface TurnState {
+	/** Schema version. Any other value is refused by {@link parseTurnState}. */
+	readonly version: typeof TURN_STATE_VERSION
+
+	readonly sessionId: SessionId
+	readonly turnId: TurnId
+	readonly topicId: TopicId
+	readonly projectId: ProjectId
+	readonly tenantId: TenantId
+	/** Present on a child session's turn. */
+	readonly parentSessionId?: SessionId
+	/** Present on a child session's turn. */
+	readonly parentTurnId?: TurnId
+
+	readonly agentId?: string
+	readonly agentName?: string
+
+	readonly status: TurnExecutionStatus
+	readonly stopReason?: StopReason
+	readonly lastError?: string
+
+	readonly messages: Message[]
+	readonly tokenUsage: TokenUsage
+	readonly costInfo: CostInfo
+	readonly currentIteration: number
+	readonly startedAt: number
+	/**
+	 * Wall-clock the turn has already consumed. Restored into the guard so a
+	 * resumed turn does not get a fresh timeout budget.
+	 */
+	readonly elapsedMs: number
+
+	/** The checkpoint this snapshot corresponds to, when one was written. */
+	readonly checkpointId?: CheckpointId
+
+	/** The decision the turn is parked on, if any. */
+	readonly pending?: PendingDecision
+
+	/** The ledger the turn spends from, keyed by (rootSessionId, rootTurnId). */
+	readonly budgetBinding?: TurnBudgetBinding
+
+	readonly capturedAt: number
+}
+
+/**
+ * Thrown by {@link parseTurnState} when a snapshot cannot be trusted: an
+ * unknown version, or a `RunState` written by an SDK before sessions and
+ * turns replaced runs.
+ */
+export class TurnStateVersionError extends Error {
+	constructor(
+		readonly found: unknown,
+		readonly expected: number,
+		message?: string,
+	) {
+		super(
+			message ??
+				`TurnState version mismatch: snapshot declares ${JSON.stringify(found)}, this SDK reads ${expected}. Restoring across an incompatible version would silently drop fields; start a new turn instead.`,
+		)
+		this.name = 'TurnStateVersionError'
+	}
+}
+
+export const TURN_STATE_VERSION = 1 as const
+
+function requireEntityIds(record: Record<string, unknown>): Record<string, unknown> {
+	const validators = {
+		sessionId: asSessionId,
+		turnId: asTurnId,
+		parentSessionId: asSessionId,
+		parentTurnId: asTurnId,
+		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.
+ *
+ * A `RunState` (it carries `runId`) is refused with a message that names it:
+ * the turn model is gone and there is no migration. Resolve or abandon parked
+ * runs on the previous major before upgrading.
+ */
+export function parseTurnState(json: string | unknown): TurnState {
+	const raw: unknown = typeof json === 'string' ? JSON.parse(json) : json
+	if (typeof raw !== 'object' || raw === null) {
+		throw new TurnStateVersionError(raw, TURN_STATE_VERSION)
+	}
+	const record = raw as Record<string, unknown>
+	if ('runId' in record) {
+		throw new TurnStateVersionError(
+			record.version,
+			TURN_STATE_VERSION,
+			`This is a RunState (version ${JSON.stringify(record.version)}), written before sessions and turns replaced runs. It cannot be resumed by this SDK; resolve or abandon it on the previous major.`,
+		)
+	}
+	if (record.version !== TURN_STATE_VERSION) {
+		throw new TurnStateVersionError(record.version, TURN_STATE_VERSION)
+	}
+	return requireEntityIds(record) as unknown as TurnState
+}