@namzu/sdk 42.0.2 → 44.0.0

package/src/types/session/audit.ts

@@ -0,0 +1,167 @@
+import type { CostInfo } from '../common/index.js'
+import type { AuditEventId, SessionId, TenantId, TurnId } from '../ids/index.js'
+import type { TurnExecutionStatus } from './turn.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').SessionEvent}
+ * 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.
+ *
+ * `'approved'` is its counterpart for an action that crossed a boundary with
+ * consent: a path outside the working directory a review approved, a command
+ * a reviewer confirmed outside the sandbox. Like `'refused'` it is one action
+ * inside an open turn, never the turn's verdict, so {@link replayAudit} skips
+ * it.
+ */
+export type AuditOutcome = 'success' | 'failure' | 'refused' | 'approved'
+
+/**
+ * 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 turn — absent
+ * when the turn 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 turn-level one (an input/output guardrail, the turn'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
+ * `SessionEvent['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 session's audit trail — durable evidence of what the agent
+ * did, under whose identity, at what cost, and whether it was allowed.
+ *
+ * ## Why this is not an operational log line
+ *
+ * See ses_020's logging design §5 for the full reasoning. It is appended to
+ * the session log as an `audit` record. 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 the audit trail's OWN sequence
+ *
+ * Independent of the session log's record `seq`: the audit entries of a
+ * session are numbered among themselves, so a reader can tell whether one is
+ * missing.
+ *
+ * ## `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 turn's
+ * CUMULATIVE total AT THIS MOMENT, matching `Turn.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 replayAudit}).
+ */
+export interface AuditEvent {
+	readonly id: AuditEventId
+	readonly sessionId: SessionId
+	/** Absent for an entry recorded outside any turn. */
+	readonly turnId?: TurnId
+	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'`, `'failure'` and `'approved'` — 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/session/turn-recorder.js').TurnRecorder.recordAudit} —
+ * the fields ONLY the call site knows. `id`, `sessionId`, `turnId`, `seq`, `timestamp`,
+ * `who.agentId`/`who.tenantId` and `cost` are filled in by `recordAudit`
+ * itself from the turn it is bound to; a caller supplying them would be
+ * asserting facts about identity and cost that only the turn-persistence
+ * layer is positioned to know, and could disagree with what the turn
+ * actually holds.
+ */
+export interface AuditEventInput {
+	readonly what: AuditAction
+	readonly outcome: AuditOutcome
+	readonly reason?: string
+	readonly persona?: string
+}
+
+/** What {@link replayAudit} reconstructs from the trail alone. */
+export interface AuditSummary {
+	readonly costInfo: CostInfo
+	readonly status: Extract<TurnExecutionStatus, 'completed' | 'failed'>
+}
+
+/**
+ * Reconstruct a completed turn's cost and status from its audit trail alone,
+ * with no read of the derived `Turn`.
+ *
+ * `Turn.costInfo` and `Turn.status` are a DERIVED summary; the audit trail is
+ * the evidence, and a divergence between what this returns and what the
+ * summary holds 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 turn's cumulative total (see {@link AuditEvent.cost}), so the
+ * most recent entry that actually SETTLES the turn — `'success'` or
+ * `'failure'` — carries the answer whole. A `'refused'` entry is a single
+ * action inside a still-open run, never the turn'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 turn's
+ * final status, which is not what it means.
+ *
+ * `undefined` when no terminal entry exists — a turn 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 replayAudit(events: readonly AuditEvent[]): AuditSummary | 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/session/cancel-cause.ts

@@ -0,0 +1,60 @@
+/**
+ * Why a turn stopped, when it stopped because somebody stopped it.
+ *
+ * `stopReason: 'cancelled'` says the turn 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 turn 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 TurnCancelled extends Error {
+	override readonly name = 'TurnCancelled'
+
+	/**
+	 * 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(`turn 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 === 'TurnCancelled') {
+		return (reason as TurnCancelled).cancelCause
+	}
+	return undefined
+}

package/src/types/session/checkpoint.ts

@@ -0,0 +1,167 @@
+import { z } from 'zod'
+import type { WorkingStateSnapshot } from '../../compaction/wire.js'
+import type { SerializedSpanContext } from '../../telemetry/attributes.js'
+import { type EntityIdKind, isEntityId } from '../../utils/id.js'
+import type { CostInfo, TokenUsage } from '../common/index.js'
+import type { CheckpointId, MessageId, SessionId, TurnId } from '../ids/index.js'
+import type { TurnBudgetBinding } from './turn.js'
+
+/** Version of the checkpoint document. An older or unknown version is refused, never migrated. */
+export const CHECKPOINT_DOCUMENT_VERSION = 1 as const
+
+/**
+ * A checkpoint of one turn, stored at `<session-id>/checkpoints/<id>.json`.
+ *
+ * It holds NO messages. The context it restores is the fold of the session
+ * log from seq 1 through `throughSeq`, which equals the session's context at
+ * that seq because no other turn can interleave. `throughSha256` is the hash
+ * of the record at `throughSeq`, and the `checkpoint_written` record carries
+ * the document's own hash (`docSha256`): a restore refuses the checkpoint when
+ * either does not match.
+ */
+export interface Checkpoint {
+	readonly v: typeof CHECKPOINT_DOCUMENT_VERSION
+	readonly kind: 'checkpoint'
+	readonly checkpointId: CheckpointId
+	readonly sessionId: SessionId
+	readonly turnId: TurnId
+	readonly iteration: number
+	readonly throughSeq: number
+	readonly throughSha256: string
+	readonly tokenUsage: TokenUsage
+	readonly costInfo: CostInfo
+	/** The ledger reference; the ledger itself stays authoritative. */
+	readonly budget?: {
+		readonly binding?: TurnBudgetBinding
+		/** Present for non-durable accounts too; those need the live authority on resume. */
+		readonly accountId: string
+	}
+	readonly guards: { readonly iteration: number; readonly elapsedMs: number }
+	/**
+	 * Review corrections already consumed at this checkpoint, independent of
+	 * compactable history: host structured-output review, prose-answer review
+	 * and native structured-output correction.
+	 */
+	readonly review: {
+		readonly structuredAttempts: number
+		readonly answerAttempts: number
+		readonly nativeStructuredAttempts: number
+	}
+	/** The turn's current operator/goal/steering message, independent of compaction. */
+	readonly latestUserMessageId?: MessageId
+	/** Compaction's accumulated working state, when compaction is enabled. */
+	readonly workingState?: WorkingStateSnapshot
+	/** The trace the checkpoint was taken inside, so a resume continues it. */
+	readonly trace?: SerializedSpanContext
+	/** When the turn was attributed (ISO-8601). Identical on every checkpoint of the turn. */
+	readonly turnCreatedAt: string
+	/** When this checkpoint was written (ISO-8601). */
+	readonly createdAt: string
+}
+
+const count = z.number().int().nonnegative().safe()
+const sha256 = z.string().regex(/^[a-f0-9]{64}$/)
+const iso = z.string().datetime({ offset: false })
+/** Annotated with the id's own alias, so declarations name it rather than expanding its brand. */
+function id<T extends string>(kind: EntityIdKind): z.ZodType<T, z.ZodTypeDef, unknown> {
+	return z.custom<T>((value) => isEntityId(value, kind), {
+		message: `expected a ${kind} id (UUID)`,
+	})
+}
+
+export const TokenUsageSchema = z
+	.object({
+		promptTokens: count,
+		completionTokens: count,
+		totalTokens: count,
+		cachedTokens: count,
+		cacheWriteTokens: count,
+		reasoningTokens: count.optional(),
+	})
+	.strict()
+
+export const CostInfoSchema = z
+	.object({
+		inputCostPer1M: z.number().nonnegative().optional(),
+		outputCostPer1M: z.number().nonnegative().optional(),
+		totalCost: z.number().nonnegative(),
+		cacheDiscount: z.number(),
+		unpricedTokens: count,
+	})
+	.strict()
+
+export const TurnBudgetBindingSchema = z
+	.object({
+		rootSessionId: id<SessionId>('session'),
+		rootTurnId: id<TurnId>('turn'),
+		accountId: z.string().min(1),
+	})
+	.strict()
+
+export const CheckpointSchema = z
+	.object({
+		v: z.literal(CHECKPOINT_DOCUMENT_VERSION),
+		kind: z.literal('checkpoint'),
+		checkpointId: id<CheckpointId>('checkpoint'),
+		sessionId: id<SessionId>('session'),
+		turnId: id<TurnId>('turn'),
+		iteration: count,
+		throughSeq: count.positive(),
+		throughSha256: sha256,
+		tokenUsage: TokenUsageSchema,
+		costInfo: CostInfoSchema,
+		budget: z
+			.object({ binding: TurnBudgetBindingSchema.optional(), accountId: z.string().min(1) })
+			.strict()
+			.optional(),
+		guards: z.object({ iteration: count, elapsedMs: count }).strict(),
+		review: z
+			.object({
+				structuredAttempts: count,
+				answerAttempts: count,
+				nativeStructuredAttempts: count,
+			})
+			.strict(),
+		latestUserMessageId: id<MessageId>('message').optional(),
+		// Each has its own validator where it is restored; the document only
+		// requires an object.
+		workingState: z.custom<WorkingStateSnapshot>(isPlainObject).optional(),
+		trace: z.custom<SerializedSpanContext>(isPlainObject).optional(),
+		turnCreatedAt: iso,
+		createdAt: iso,
+	})
+	.strict()
+
+function isPlainObject(value: unknown): boolean {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Raised for a checkpoint document written by another version or another shape. */
+export class CheckpointDocumentError extends Error {
+	override readonly name = 'CheckpointDocumentError'
+}
+
+/**
+ * Parse a checkpoint document. A document from the run-era layout
+ * (`kind: 'run-checkpoint'`) or any other version is refused by name.
+ */
+export function parseCheckpoint(value: unknown): Checkpoint {
+	if (isPlainObject(value)) {
+		const record = value as Record<string, unknown>
+		if (record.kind !== undefined && record.kind !== 'checkpoint') {
+			throw new CheckpointDocumentError(
+				`Not a session checkpoint: kind ${JSON.stringify(record.kind)}. Checkpoints from earlier releases are not read.`,
+			)
+		}
+		if (record.v !== CHECKPOINT_DOCUMENT_VERSION) {
+			throw new CheckpointDocumentError(
+				`Unsupported checkpoint version ${JSON.stringify(record.v)}; this release reads version ${CHECKPOINT_DOCUMENT_VERSION}.`,
+			)
+		}
+	}
+	const parsed = CheckpointSchema.safeParse(value)
+	if (!parsed.success) {
+		throw new CheckpointDocumentError(`Invalid checkpoint document: ${parsed.error.message}`)
+	}
+	return parsed.data
+}

package/src/types/session/config.ts

@@ -0,0 +1,212 @@
+import type { SessionTokenBudget } from '../../store/budget/index.js'
+import type { SessionCheckpointStore } from '../../store/checkpoint/index.js'
+import type { SessionLog } from '../../store/session-log/index.js'
+import type { ModelPricing } from '../../utils/cost.js'
+import type { Logger } from '../../utils/logger.js'
+import type { SessionId, TenantId, TurnId } from '../ids/index.js'
+import type { PermissionMode } from '../permission/index.js'
+import type { ProjectId, TopicId } from './ids.js'
+
+/** The configuration one turn runs with. */
+export interface TurnConfig {
+	model: string
+	/** Total turn duration in milliseconds; 0 disables the turn deadline. */
+	timeoutMs: number
+	/**
+	 * Maximum silence between provider stream chunks, in milliseconds.
+	 *
+	 * Defaults to five minutes at the `query()` boundary. This is distinct
+	 * from `timeoutMs`, which is checked between agent iterations and cannot
+	 * settle a provider iterator whose pending `next()` never returns. Set
+	 * `0` to retain unbounded stream silence. Positive values must be integer
+	 * milliseconds accepted by the platform timer.
+	 */
+	streamIdleTimeoutMs?: number
+	/**
+	 * Maximum accumulated inline image/document payload on one provider request.
+	 *
+	 * Defaults to 24 MiB. The budget is shared by user attachments and rich
+	 * tool-result blocks. When history exceeds it, the provider-bound projection
+	 * replaces the oldest values with model-visible omission markers; the turn's
+	 * canonical messages and durable evidence remain unchanged. Set `0` to keep
+	 * the prior unbounded behaviour.
+	 */
+	maxRequestRichContentBytes?: number
+	maxResponseTokens?: number
+
+	/**
+	 * Extended-thinking request, forwarded on every model call in the turn.
+	 *
+	 * Drivers that do not support it ignore the field. Note that a provider
+	 * rejects temperature/top_p/top_k while thinking is enabled, so the
+	 * driver omits them rather than sending a request it knows will 400.
+	 */
+	thinking?: import('../provider/index.js').ThinkingConfig
+
+	/**
+	 * How much work the model should spend on each call in the turn.
+	 *
+	 * A SIBLING of {@link TurnConfig.thinking}, not a field inside it.
+	 * On some models the two are independent controls that apply together —
+	 * effort shapes the answer while a budget sets thinking depth — so
+	 * nesting one inside the other would make that combination unsayable.
+	 *
+	 * The failure this closes is the one this codebase keeps finding: the
+	 * field existed on the provider params, a driver already read it and
+	 * wrote it to the wire, and nothing in the kernel ever set it. So a
+	 * caller could not reach it at all, and the symptom — every request
+	 * going out at the model's default — reads as "this model ignores
+	 * effort" rather than "nobody plumbed it through".
+	 *
+	 * Turn-level rather than per-step, deliberately. It is a property of what
+	 * the turn is FOR, and a value that moves between steps buys a different
+	 * answer shape at the cost of the prompt-cache prefix on every step that
+	 * changes it.
+	 *
+	 * A driver that cannot honour it REFUSES rather than dropping it, on the
+	 * same reasoning as `thinking`: paying for a turn you believe was
+	 * high-effort and silently was not is worse than a startup error.
+	 */
+	effort?: import('../provider/index.js').ReasoningEffort
+	/** Provider-hosted search for this turn. Explicit opt-in; no local network permission. */
+	webSearch?: import('../provider/index.js').ChatCompletionParams['webSearch']
+	/** Cumulative parent-and-descendant tokens; 0 is unlimited with usage accounting. */
+	tokenBudget: number
+	costLimitUsd?: number
+	/** Main-loop iterations; 0 disables this guard. Omitted defaults depend on the entry point. */
+	maxIterations?: number
+	temperature?: number
+	env?: Record<string, string>
+	permissionMode?: PermissionMode
+	sandbox?: {
+		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 turn had before this existed.
+		 */
+		workspace?: 'ephemeral' | 'working-directory'
+	}
+
+	/**
+	 * Iteration-checkpoint cadence: create a checkpoint on every Nth
+	 * tool-call iteration (iterations 1, 1+N, 1+2N, …). Default `1` —
+	 * a checkpoint per iteration, today's behavior. Values < 1 are
+	 * treated as 1. Off-cadence iterations also skip the HITL
+	 * `iteration_checkpoint` park (there is no checkpoint id to park on).
+	 * Tool-review and plan-approval checkpoints are unaffected — those
+	 * exist to anchor a pending HITL decision, not for growth control.
+	 */
+	checkpointEvery?: number
+
+	/**
+	 * After creating an iteration checkpoint, prune the turn's checkpoint
+	 * set down to the newest N. Default `undefined` — never prune. A
+	 * checkpoint holds no inline messages (its context is the fold of the
+	 * session log through `throughSeq`), so it costs its own bookkeeping
+	 * rather than a copy of the conversation, but the COUNT only ever grows
+	 * unless a host bounds it here. The CLI does.
+	 *
+	 * Oldest-first by `createdAt`, across all of the turn's checkpoints — but
+	 * a checkpoint an open decision references is never collected, whatever
+	 * its age. Those rows are what `SessionIndex.listPendingDecisions` serves
+	 * to an approval queue and what a sweep enumerates, so pruning
+	 * briefly holds more than N while a park is outstanding; the next prune
+	 * after the park resolves — by `unpark`, or by `expire` for one that ran
+	 * out of time — collects them. A host that needs the bound to hold
+	 * regardless should sweep expired parks itself.
+	 */
+	pruneKeepLast?: number
+
+	/**
+	 * How long a human-in-the-loop park stays worth serving, in ms.
+	 *
+	 * Written onto the park as an ABSOLUTE deadline, so it survives the
+	 * process that set it. Every timer in the SDK is an in-process
+	 * `setTimeout` and the park-record delay is deliberately `unref`'d, so
+	 * nothing in memory can outlive a redeploy: without this a turn parks for
+	 * approval, the worker is replaced, nobody answers, and the checkpoint
+	 * stays outstanding forever — every approval-queue reader keeps serving
+	 * it and its workspace is never reclaimed.
+	 *
+	 * The turn timeout does not cover this. It is only checked between
+	 * iterations and a park suspends mid-iteration, so a long-lived process
+	 * hard-stops the turn immediately *after* the human finally approves,
+	 * while across a restart the restored elapsed clock excludes parked time
+	 * entirely — the same configuration producing two opposite outcomes.
+	 *
+	 * Expiry is enforced on READ (`findPendingCheckpoint` skips an expired
+	 * park) and by a host sweep (`listExpiredParks` + `CheckpointManager
+	 * .expire`). An out-of-process timer stays a host concern, consistent
+	 * with the same decision made for retention.
+	 *
+	 * Default `undefined` — no deadline, today's behaviour.
+	 */
+	hitlParkTtlMs?: number
+
+	/**
+	 * Override the logger a turn's log lines derive from.
+	 *
+	 * This is an override of the SOURCE, not a substitute for correlation:
+	 * `TurnContextFactory.buildLogger` always calls `.child()` on whichever
+	 * logger this resolves to, so a host-supplied logger still gains
+	 * `namzu.turn.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 turn
+	 * 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 import('../../manager/session/turn-recorder.js').TurnRecorder}.
+ *
+ * `sessionId`, `topicId`, `tenantId` and `projectId` are required: every
+ * turn is attributed across the full scope (Tenant → Project → Topic →
+ * Session → Turn). The recorder appends records to `sessionLog` under the
+ * session lease; it writes no `run.json`, `messages.json` or `report.md`.
+ */
+export interface TurnRecorderConfig {
+	/** The ledger this turn and its child sessions spend from, keyed by (rootSessionId, rootTurnId). */
+	budget?: SessionTokenBudget
+	sessionId: SessionId
+	turnId: TurnId
+	agentId: string
+	agentName: string
+	turnConfig: TurnConfig
+	providerId: string
+	pricing?: ModelPricing
+	log: Logger
+
+	topicId: TopicId
+	tenantId: TenantId
+	projectId: ProjectId
+
+	/** Present on a child session's turn: the parent session that delegated it. */
+	parentSessionId?: SessionId
+	/** Present on a child session's turn: the parent turn whose tool call spawned the child. */
+	parentTurnId?: TurnId
+
+	depth?: number
+
+	/** The session log the turn's records are appended to. */
+	sessionLog: SessionLog
+
+	/**
+	 * Optional checkpoint persistence override. Defaults to the disk layout
+	 * under `<session-id>/checkpoints/`; hosts inject a scope-keyed backend here.
+	 */
+	checkpointStore?: SessionCheckpointStore
+}
+
+export interface LimitCheckerConfig {
+	tokenBudget: number
+	timeoutMs: number
+	costLimitUsd?: number
+	maxIterations: number
+	budgetWarningThreshold: number
+}

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

@@ -0,0 +1,61 @@
+import type { PendingDecision } from '../hitl/index.js'
+import type { TurnExecutionStatus, TurnStatus } from './turn.js'
+
+/**
+ * Project what the SDK records about a turn onto the session-layer
+ * {@link TurnStatus}.
+ *
+ * `Turn.status` is a {@link TurnExecutionStatus} — six values, none of which can
+ * say "a human owes this turn an answer". `TurnStatus` 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
+ * had to invent the projection, and the two `awaiting_hitl*` variants in
+ * particular had no producer at all. `awaiting_hitl_resolution` documented
+ * a "persisted wait after a HITL timeout" for a timeout nothing could
+ * raise.
+ *
+ * The park record is the missing input. It is durable, it is what an
+ * approval queue already reads, and it carries the deadline that separates
+ * "waiting" from "waited too long".
+ */
+export function deriveTurnStatus(input: {
+	/** What the turn itself recorded. */
+	readonly status: TurnExecutionStatus
+	/** The turn's outstanding park, if it has one. */
+	readonly park?: PendingDecision
+	/** Injectable for tests; defaults to now. */
+	readonly now?: number
+}): TurnStatus {
+	const { status, park } = input
+	const now = input.now ?? Date.now()
+
+	// Terminal beats parked. A turn that finished, failed or was cancelled
+	// is not waiting for anyone, whatever a stale park record says.
+	switch (status) {
+		case 'completed':
+			return 'succeeded'
+		case 'failed':
+			return 'failed'
+		case 'cancelled':
+			return 'cancelled'
+		case 'idle':
+		case 'pending':
+		case 'running':
+			break
+		default: {
+			const _exhaustive: never = status
+			throw new Error(`Unmapped agent status: ${_exhaustive as string}`)
+		}
+	}
+
+	if (park && park.resolvedAt === undefined) {
+		// A deadline that has passed means the window closed with nobody
+		// answering. The work is not lost and the turn stays resumable from
+		// its checkpoint, so this is a persisted wait rather than a terminal
+		// state — which is exactly what the reserved variant describes.
+		const expired = park.deadlineAt !== undefined && now >= park.deadlineAt
+		return expired ? 'awaiting_hitl_resolution' : 'awaiting_hitl'
+	}
+
+	return status === 'running' ? 'running' : 'queued'
+}