@namzu/sdk 43.0.0 → 44.0.0

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'
+}

package/src/types/session/durable.ts

@@ -0,0 +1,150 @@
+/**
+ * Durable turns: what an approval inbox, a crash sweep and `drainParkedTurns`
+ * read about turns that outlived the process that ran them.
+ *
+ * The session log is the source of truth. A parked turn is a `turn_paused`
+ * record followed by an open `decision_requested`; a claim is the session's
+ * `lease.json`. The rows below are projections of those, served by
+ * `SessionIndex.listTurns` and `SessionIndex.listPendingDecisions`.
+ */
+
+import type { HITLDecisionRequest } from '../hitl/index.js'
+import type { CheckpointId, ProjectId, SessionId, TenantId, TurnId } from '../ids/index.js'
+
+/**
+ * A monotonically increasing number identifying one holding of a session's
+ * lease.
+ *
+ * The load-bearing word is *fencing*. A mutex answers "may I proceed", and a
+ * holder that stalls past its lease answers it "yes" and then writes, long
+ * after somebody else legitimately took over. A fence answers a different
+ * question at the moment of the WRITE: "is the holding I belong to still the
+ * current one". Every claim mints a number strictly greater than the last,
+ * and every session-log record carries the fence it was written under
+ * (`gen`), so an append from a superseded holder is refused.
+ *
+ * Not a random token, deliberately: randomness proves identity and cannot
+ * establish *order*, and order is the entire mechanism.
+ */
+export type FencingToken = number
+
+/** A session's lease as a listing reports it. */
+export interface LeaseSummary {
+	readonly holder: string
+	readonly fence: FencingToken
+	readonly expiresAt: number
+	/**
+	 * Whether the lease had expired at the instant the listing was taken.
+	 *
+	 * A separate field rather than something the caller derives from
+	 * `expiresAt`, because the caller would derive it against a DIFFERENT
+	 * clock than the index used, and one page would then disagree with itself
+	 * about which rows are available.
+	 */
+	readonly expired: boolean
+}
+
+/**
+ * What a turn's human-in-the-loop park is doing, as far as the log can tell.
+ *
+ * A closed union rather than a boolean because the two unanswered states are
+ * drained by DIFFERENT operators: `outstanding` is an approval inbox's queue
+ * and `expired` is a reclamation sweep's.
+ *
+ * **Do not widen this union to say who is working on the turn.** A park is a
+ * question put to a HUMAN; a lease is held by a PROCESS, and one turn can
+ * have both, neither, or either. That is why {@link DurableTurnEntry.claim}
+ * is a sibling field.
+ */
+export type ParkState =
+	/** Decision requested, not resolved, deadline not passed. A human owes an answer. */
+	| 'outstanding'
+	/** Decision requested, not resolved, deadline passed (`decision_expired`). Nobody will answer it. */
+	| 'expired'
+	/** Decision resolved. Kept as evidence of who decided what. */
+	| 'resolved'
+
+/** A turn's park disposition, projected from its `decision_*` records. */
+export interface ParkSummary {
+	readonly state: ParkState
+	/** The checkpoint the decision references. */
+	readonly checkpointId: CheckpointId
+	/** What the human was asked. Enough to route an inbox without a second read. */
+	readonly requestType: HITLDecisionRequest['type']
+	/** Epoch ms at which the turn parked. */
+	readonly parkedAt: number
+	/** Absolute expiry, when the decision carries one. */
+	readonly deadlineAt?: number
+	/** Epoch ms at which the answer arrived. Only on `resolved`. */
+	readonly resolvedAt?: number
+}
+
+/**
+ * One turn that has durable state: a row an approval inbox or a crash sweep
+ * works from.
+ *
+ * It carries the full attribution, so `resumeSession({ scope: entry, … })`
+ * and `claimSession(entry, …)` accept a row straight out of the listing.
+ */
+export interface DurableTurnEntry {
+	readonly tenantId: TenantId
+	readonly projectId: ProjectId
+	readonly sessionId: SessionId
+	readonly turnId: TurnId
+	/** When the turn started (`turn_started.ts`), epoch ms. */
+	readonly turnCreatedAt: number
+	/** How many checkpoints the turn has right now. Pruning lowers it. */
+	readonly checkpointCount: number
+	/** Newest checkpoint — the one a resume restores by default. */
+	readonly latestCheckpointId: CheckpointId
+	/** Creation time of {@link DurableTurnEntry.latestCheckpointId}. */
+	readonly latestCheckpointAt: number
+	/** Absent when the turn has never parked. */
+	readonly park?: ParkSummary
+	/** Absent when no process holds or has held the session's lease. */
+	readonly claim?: LeaseSummary
+}
+
+/**
+ * Which order a listing comes back in.
+ *
+ *  - `'turnId'` — ascending by turn id. Stable and total; UUIDv7 ids sort by
+ *    creation time, so this is also roughly chronological.
+ *  - `'createdAt'` — oldest first by `turnCreatedAt`, then `turnId`: the
+ *    triage order ("which turn has been waiting longest").
+ */
+export type DurableTurnOrder = 'turnId' | 'createdAt'
+
+/** Filters and paging for a durable-turn listing. */
+export interface ListDurableTurnsOptions {
+	readonly tenantId: TenantId
+	/** Narrow to one project. */
+	readonly projectId?: ProjectId
+	/** Narrow to one session. */
+	readonly sessionId?: SessionId
+	/** Defaults to `'turnId'`. A cursor is only meaningful within one order. */
+	readonly orderBy?: DurableTurnOrder
+	/**
+	 * Keep only turns whose park is in one of these states. A turn that never
+	 * parked is excluded by ANY value here; omit the filter to include it.
+	 */
+	readonly park?: readonly ParkState[]
+	/**
+	 * Keep only turns whose session is, or is not, currently leased. An
+	 * expired lease counts as NOT held.
+	 */
+	readonly claimed?: boolean
+	/** Page size. Defaults to 100, clamped to at least 1. */
+	readonly limit?: number
+	/** Resume token from the previous page's {@link DurableTurnPage.cursor}. */
+	readonly cursor?: string
+	/** Clock for expiry, so every entry in one page is judged against one instant. */
+	readonly now?: number
+}
+
+/** One page of {@link DurableTurnEntry}. */
+export interface DurableTurnPage {
+	readonly entries: readonly DurableTurnEntry[]
+	/** Pass to the next call. **Absent means the listing is exhausted.** */
+	readonly cursor?: string
+}

package/src/types/session/entity.ts

@@ -42,7 +42,7 @@ export type SessionStatus =
  *   - `workspaceId` is nullable for sessions whose workspace has not yet
  *     been provisioned (or has been torn down during archival).
  *
- * The pure `deriveStatus(session, runs)` fan-in helper lives at
+ * The pure `deriveStatus(session, turns)` fan-in helper lives at
  * `session/status/derive.ts` — it is runtime, not a shape, so it is not
  * colocated with this interface.
  */