@namzu/sdk 19.0.0 → 20.1.0

package/src/store/run/listing.ts

@@ -0,0 +1,229 @@
+/**
+ * Shared machinery for {@link CheckpointStore.listDurableRuns}.
+ *
+ * Every rule the listing promises — the contiguous-prefix refusal, the park
+ * precedence, the ordering, the paging — lives here and is used by BOTH
+ * shipped implementations. A rule implemented twice is a rule that holds in
+ * one store and not the other, and the whole point of a store contract is
+ * that a host can swap the backend without swapping the semantics.
+ */
+
+import { NamzuError } from '../../types/errors/index.js'
+import type { IterationCheckpoint, PendingDecision } from '../../types/hitl/index.js'
+import type {
+	CheckpointListingScope,
+	CheckpointRunScope,
+	CheckpointStore,
+	DurableRunEntry,
+	DurableRunPage,
+	ListDurableRunsOptions,
+	ParkState,
+	ParkSummary,
+} from '../../types/run/checkpoint-store.js'
+
+/** Page size when the caller names none. */
+export const DEFAULT_DURABLE_RUN_LIMIT = 100
+
+/**
+ * Refuse a listing scope with a hole in it.
+ *
+ * `{ tenantId, sessionId }` reads as "that session under whichever project
+ * holds it". A flat backend can answer it; a hierarchical one cannot look up
+ * a session without its project. Answering differently per backend is the
+ * one thing the contract exists to prevent, so neither answers: the caller
+ * names the project it means.
+ */
+export function assertContiguousListingScope(scope: CheckpointListingScope, caller: string): void {
+	if (scope.sessionId !== undefined && scope.projectId === undefined) {
+		throw new NamzuError({
+			code: 'invalid_config',
+			message: `${caller}: listing scope has a hole — \`sessionId\` was supplied without \`projectId\`. A run listing scope is a contiguous prefix of tenant → project → session; name the project the session belongs to.`,
+			details: { tenantId: scope.tenantId, sessionId: scope.sessionId },
+		})
+	}
+}
+
+/** Whether a park's absolute deadline has passed. No deadline never expires. */
+function isPastDeadline(pending: PendingDecision, now: number): boolean {
+	return pending.deadlineAt !== undefined && now >= pending.deadlineAt
+}
+
+/**
+ * Which of the three states a recorded park is in.
+ *
+ * `resolved` is checked FIRST: a park that was answered after its deadline
+ * passed is answered, not expired. Reading the deadline first would report
+ * a decision a human actually made as an expiry nobody made, and the
+ * checkpoint is the evidence record for exactly that question.
+ */
+function parkStateOf(pending: PendingDecision, now: number): ParkState {
+	if (pending.resolvedAt !== undefined) return 'resolved'
+	return isPastDeadline(pending, now) ? 'expired' : 'outstanding'
+}
+
+function toParkSummary(
+	cp: IterationCheckpoint,
+	pending: PendingDecision,
+	now: number,
+): ParkSummary {
+	return {
+		state: parkStateOf(pending, now),
+		checkpointId: cp.id,
+		requestType: pending.request.type,
+		parkedAt: pending.parkedAt,
+		...(pending.deadlineAt !== undefined ? { deadlineAt: pending.deadlineAt } : {}),
+		...(pending.resolvedAt !== undefined ? { resolvedAt: pending.resolvedAt } : {}),
+	}
+}
+
+/**
+ * The one park that describes what a run is doing now, out of every park it
+ * ever recorded.
+ *
+ * Precedence: newest `outstanding`, else newest `expired`, else newest
+ * `resolved`.
+ *
+ * `outstanding` wins because that is the question an inbox is asking, and
+ * because the answer has to be the SAME checkpoint `findPendingCheckpoint`
+ * returns. A run can hold several parks — it parks, a human answers, it runs
+ * on, it parks again — and it can hold an outstanding one that is older than
+ * a resolved one only in the reverse case, where an earlier park expired
+ * unanswered and the run was resumed past it. Ranking by recency alone would
+ * then hand an inbox a resolved checkpoint and report the live park as
+ * nothing.
+ *
+ * @param checkpoints the run's checkpoints, any order.
+ */
+export function summarizePark(
+	checkpoints: readonly IterationCheckpoint[],
+	now: number,
+): ParkSummary | undefined {
+	let best: ParkSummary | undefined
+	let bestRank = -1
+	let bestParkedAt = Number.NEGATIVE_INFINITY
+
+	for (const cp of checkpoints) {
+		const pending = cp.pending
+		if (!pending) continue
+		const summary = toParkSummary(cp, pending, now)
+		const rank = PARK_RANK[summary.state]
+		if (rank > bestRank || (rank === bestRank && pending.parkedAt > bestParkedAt)) {
+			best = summary
+			bestRank = rank
+			bestParkedAt = pending.parkedAt
+		}
+	}
+
+	return best
+}
+
+const PARK_RANK: Record<ParkState, number> = {
+	resolved: 0,
+	expired: 1,
+	outstanding: 2,
+}
+
+/**
+ * Project one run's checkpoints into a listing entry.
+ *
+ * Returns `null` for a run with no checkpoints: the listing is of runs with
+ * DURABLE state, and a run with nothing stored has nothing a sweeper could
+ * resume. A disk walk hits this case for real — a sub-run's directory is
+ * created as a bare shell under its own id before anything is written to it.
+ */
+export function toDurableRunEntry(
+	scope: CheckpointRunScope,
+	checkpoints: readonly IterationCheckpoint[],
+	now: number,
+): DurableRunEntry | null {
+	if (checkpoints.length === 0) return null
+
+	let latest = checkpoints[0] as IterationCheckpoint
+	for (const cp of checkpoints) {
+		if (cp.createdAt > latest.createdAt) latest = cp
+	}
+
+	const park = summarizePark(checkpoints, now)
+
+	return {
+		tenantId: scope.tenantId,
+		projectId: scope.projectId,
+		sessionId: scope.sessionId,
+		runId: scope.runId,
+		...(scope.parentRunId ? { parentRunId: scope.parentRunId } : {}),
+		checkpointCount: checkpoints.length,
+		latestCheckpointId: latest.id,
+		latestCheckpointAt: latest.createdAt,
+		...(park ? { park } : {}),
+	}
+}
+
+/**
+ * Apply the park filter, the contract's ordering and the cursor to a set of
+ * entries an implementation has gathered.
+ *
+ * Both shipped stores gather differently — one walks a directory tree, one
+ * reads a map — and then hand the result here, so "ordered by `runId`, page
+ * ends where the next begins" is one implementation rather than two.
+ */
+export function paginateDurableRuns(
+	entries: readonly DurableRunEntry[],
+	options?: ListDurableRunsOptions,
+): DurableRunPage {
+	const wanted = options?.park
+	const filtered =
+		wanted && wanted.length > 0
+			? entries.filter((e) => e.park !== undefined && wanted.includes(e.park.state))
+			: entries
+
+	// Ordered by `runId` because it is the only per-run key that cannot move
+	// under a paging caller — see the contract comment on `listDurableRuns`.
+	const ordered = [...filtered].sort((a, b) => (a.runId < b.runId ? -1 : a.runId > b.runId ? 1 : 0))
+
+	const after = options?.cursor
+	const start = after === undefined ? 0 : ordered.findIndex((e) => e.runId > after)
+	const from = start < 0 ? ordered.length : start
+
+	const limit = Math.max(1, Math.trunc(options?.limit ?? DEFAULT_DURABLE_RUN_LIMIT))
+	const page = ordered.slice(from, from + limit)
+	const exhausted = from + page.length >= ordered.length
+
+	return {
+		entries: page,
+		// No cursor when there is nothing behind it, so `while (cursor)`
+		// terminates rather than fetching one empty page to find out.
+		...(exhausted || page.length === 0
+			? {}
+			: { cursor: (page[page.length - 1] as DurableRunEntry).runId }),
+	}
+}
+
+/**
+ * Every run with durable state under a scope, refusing when the store cannot
+ * answer.
+ *
+ * The refusal is the point. `listDurableRuns` is optional on the contract so
+ * that adding it did not break every host that had already implemented the
+ * interface — and an optional capability reached without a check degrades
+ * into a wrong answer: a store that cannot list would hand an approval inbox
+ * an empty page, and "nothing is waiting on a human" is not what "I cannot
+ * tell" means. A host that gets this error knows to supply a backend that
+ * implements the listing; a host that got `[]` would ship an inbox that
+ * silently never fires.
+ */
+export async function listDurableRuns(
+	store: CheckpointStore,
+	scope: CheckpointListingScope,
+	options?: ListDurableRunsOptions,
+): Promise<DurableRunPage> {
+	if (typeof store.listDurableRuns !== 'function') {
+		throw new NamzuError({
+			code: 'capability_unavailable',
+			message:
+				'listDurableRuns: the injected checkpoint store does not implement `listDurableRuns`, so it cannot enumerate runs above a run id. Refusing rather than reporting an empty listing, which would read as "no runs are parked" when the truth is that this store cannot tell. Supply a store that implements it (the built-in disk and in-memory stores both do).',
+			details: { tenantId: scope.tenantId },
+		})
+	}
+	assertContiguousListingScope(scope, 'listDurableRuns')
+	return store.listDurableRuns(scope, options)
+}

package/src/tools/coordinator/agent.ts

@@ -175,12 +175,27 @@ export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
 			// the other one.
 			const succeeded = taskSucceeded(completed)
 
+			// A schema-configured child answers with an OBJECT, and this used to
+			// hand the parent model the child's prose instead — so a supervisor
+			// fanning out to five specialists got five strings and had to
+			// re-parse what it had just caused to be serialized.
+			//
+			// `structuredOutput` wins over `result` when present, and reading it
+			// first is what makes that true. They agree by construction anyway:
+			// `setStructuredOutput` serializes the value into `result`, so this
+			// preference is about which field is authoritative rather than about
+			// which string is produced.
+			const structured = completed.result?.structuredOutput
 			const resultText =
-				typeof completed.result?.result === 'string'
-					? completed.result.result
-					: completed.result?.result !== undefined
-						? JSON.stringify(completed.result.result)
-						: ''
+				structured !== undefined
+					? typeof structured === 'string'
+						? structured
+						: JSON.stringify(structured)
+					: typeof completed.result?.result === 'string'
+						? completed.result.result
+						: completed.result?.result !== undefined
+							? JSON.stringify(completed.result.result)
+							: ''
 
 			if (!succeeded) {
 				const detail =

package/src/tools/coordinator/index.ts

@@ -288,6 +288,26 @@ function readPositiveIntEnv(key: string, fallback: number): number {
 	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback
 }
 
+/**
+ * The answer a delegated child produced, as the string a parent model reads.
+ *
+ * One function because two delegation surfaces ask the same question, and the
+ * comment on the other one records what happens when a rule lives at one site
+ * only: create_task shipped without the success check that agent already had.
+ *
+ * A schema-configured child answers with an object. Reading structuredOutput
+ * first is what stops a supervisor receiving prose it then has to re-parse.
+ */
+function delegatedAnswer(
+	result: { structuredOutput?: unknown; result?: string } | undefined,
+): string | undefined {
+	const structured = result?.structuredOutput
+	if (structured !== undefined) {
+		return typeof structured === 'string' ? structured : JSON.stringify(structured)
+	}
+	return result?.result
+}
+
 export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefinition[] {
 	const {
 		gateway,
@@ -614,7 +634,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			// the work had been done.
 			const success = taskSucceeded(completed)
 			const resultText =
-				completed.result?.result ??
+				delegatedAnswer(completed.result) ??
 				completed.result?.lastError ??
 				`Task finished with state: ${failureLabel(completed)}`
 
@@ -744,7 +764,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 
 			const success = completed.state === 'completed'
 			const resultText =
-				completed.result?.result ??
+				delegatedAnswer(completed.result) ??
 				completed.result?.lastError ??
 				`Task finished with state: ${completed.state}`
 			return {

package/src/types/agent/base.ts

@@ -186,6 +186,26 @@ export interface BaseAgentResult {
 	durationMs: number
 	messages: Message[]
 	result?: string
+	/**
+	 * The schema-validated answer, when the run was configured to produce one.
+	 *
+	 * `Run.structuredOutput` has carried this all along and every ergonomic
+	 * boundary above it dropped the value three lines from its caller: an
+	 * archetype's result literal did not copy it, `runAgent` did not even
+	 * forward the config that produces it, and both delegation tools handed a
+	 * parent the child's prose. So a supervisor fanning out to five
+	 * schema-configured specialists received five strings and had to make the
+	 * model re-parse what it had just caused to be serialized.
+	 *
+	 * `unknown` rather than a generic, deliberately. The schema lives on the
+	 * run's config and a result type parameter would have to be threaded
+	 * through every archetype, both delegation tools and the task record to
+	 * reach here — and at the delegation boundary the parent does not hold the
+	 * child's schema anyway, so the parameter would be `unknown` again at the
+	 * only place it was wanted. Narrow it at the call site with the schema you
+	 * already have.
+	 */
+	structuredOutput?: unknown
 	lastError?: string
 }
 

package/src/types/plugin/index.ts

@@ -9,7 +9,7 @@ import {
 	PLUGIN_NAME_MAX_LENGTH,
 } from '../../constants/plugin/index.js'
 import type { PluginId, RunId } from '../ids/index.js'
-import type { Message } from '../message/index.js'
+import type { Message, ToolResultContent } from '../message/index.js'
 import type { ToolResult } from '../tool/index.js'
 
 // ---------------------------------------------------------------------------
@@ -191,6 +191,31 @@ export type PluginHookResult =
 	| { action: 'modify'; input: unknown }
 	| { action: 'error'; message: string }
 	| { action: 'retry' }
+	/**
+	 * Replace what the model sees, WITHOUT reporting the call as failed.
+	 *
+	 * The substitution seam already existed and was typed as a failure channel:
+	 * the only way a `post_tool_use` hook could change the output was
+	 * `action: 'error'`, which prefixes `Error: ` and sets the error flag. So
+	 * redacting a credential out of a successful result was delivered to the
+	 * model as a tool failure, and the model routed around a call that had
+	 * worked — retrying it, or reporting to the user that it had failed.
+	 *
+	 * That is the difference this variant exists for. `error` says the call went
+	 * wrong; this says the call went right and the model may not see all of it.
+	 *
+	 * `modify` is not this. It carries `input` and belongs to the pre-call
+	 * hooks, which is why `post_tool_use` rejects it — a result is not an input,
+	 * and reusing the variant would have made one action mean two things
+	 * depending on where it was returned.
+	 *
+	 * Rich content blocks SURVIVE a replace unless `content` is given, because
+	 * the common case is redacting text from a result whose image or resource
+	 * is unaffected. A hook that needs to drop them passes `content: []`, and a
+	 * hook redacting a secret that also appears in an image must — this variant
+	 * cannot inspect what it is preserving.
+	 */
+	| { action: 'replace'; output: string; content?: ToolResultContent }
 
 export function assertPluginHookResult(result: PluginHookResult): asserts result {
 	const action = result.action
@@ -200,6 +225,7 @@ export function assertPluginHookResult(result: PluginHookResult): asserts result
 		case 'modify':
 		case 'error':
 		case 'retry':
+		case 'replace':
 			break
 		default: {
 			const _exhaustive: never = action

package/src/types/run/checkpoint-store.ts

@@ -9,7 +9,7 @@
  * five-layer attribution (Convention #17) instead of a filesystem path.
  */
 
-import type { CheckpointId, IterationCheckpoint } from '../hitl/index.js'
+import type { CheckpointId, HITLDecisionRequest, IterationCheckpoint } from '../hitl/index.js'
 import type { RunId, SessionId, TenantId } from '../ids/index.js'
 import type { ProjectId } from '../session/ids.js'
 
@@ -39,6 +39,160 @@ export interface CheckpointRunScope {
 	parentRunId?: RunId
 }
 
+/**
+ * A CONTIGUOUS PREFIX of the run attribution hierarchy, addressing a SET of
+ * runs rather than one.
+ *
+ * A separate type from {@link CheckpointRunScope} on purpose. That type
+ * addresses exactly one run and four accessors depend on it doing so; making
+ * its one distinguishing field optional in place would turn "the scope of a
+ * run" into "some identifiers, maybe", and every accessor's guarantee with
+ * it.
+ *
+ * Three properties, each deliberate:
+ *
+ *  - **`tenantId` is required.** Isolation is the one boundary that is never
+ *    optional here. An untenanted listing is a cross-tenant read with a
+ *    friendly name.
+ *  - **It stops ABOVE the run.** No `runId`, no `parentRunId`. A caller
+ *    holding a run id already has a full {@link CheckpointRunScope} and four
+ *    accessors that take it; admitting one here would make
+ *    `CheckpointRunScope` structurally assignable to this type and re-merge
+ *    the two ideas the split exists to keep apart.
+ *  - **The prefix must be contiguous.** A `sessionId` with no `projectId` is
+ *    REFUSED, not silently widened to "that session under whichever project
+ *    holds it". A flat backend can answer it and a hierarchical one cannot,
+ *    so the answer would depend on the backend's storage shape — which is
+ *    the one thing a store contract exists to hide.
+ */
+export interface CheckpointListingScope {
+	/** Isolation boundary (Convention #17). Never optional. */
+	readonly tenantId: TenantId
+	/** Narrow to one project. Absent = every project of the tenant. */
+	readonly projectId?: ProjectId
+	/** Narrow to one session. Requires `projectId`. */
+	readonly sessionId?: SessionId
+}
+
+/**
+ * What a run's human-in-the-loop park is doing, as far as durable state 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, and serving one to the other either
+ * re-presents a dead approval forever or discards a live one.
+ */
+export type ParkState =
+	/** `pending` set, no `resolvedAt`, deadline not passed. A human owes an answer. */
+	| 'outstanding'
+	/** `pending` set, no `resolvedAt`, deadline passed. Nobody will answer it. */
+	| 'expired'
+	/** `pending` set with `resolvedAt`. Kept as evidence of who decided what. */
+	| 'resolved'
+
+/**
+ * **Do not widen this union to say who is working on the run.**
+ *
+ * A consumer switches over `ParkState` exhaustively, so a fourth member is a
+ * backward-incompatible change and a `major` — and the pull to add one is
+ * real, because the next capability this contract takes is a cross-process
+ * claim, and a queue worker draining the inbox wants to skip runs another
+ * worker already holds.
+ *
+ * That is a different fact about a different subject. A park is a question
+ * put to a HUMAN; a claim is a lease held by a PROCESS, and one run can have
+ * both, neither, or either. Encoding them in one union makes the pair
+ * unsayable and loses the state a worker needs most: parked AND unclaimed.
+ *
+ * The additive shape is a sibling optional field — `claim?: …` on
+ * {@link DurableRunEntry}, `claimed?: …` on {@link ListDurableRunsOptions}.
+ * A consumer reading rows is not broken by a new optional field, so the
+ * claim ships as a second `minor` on this contract rather than a second
+ * migration of it. This note exists because the union is the obvious place
+ * to reach for and the wrong one.
+ */
+
+/** A run's park disposition, projected from the checkpoint that carries it. */
+export interface ParkSummary {
+	readonly state: ParkState
+	/** The parked checkpoint — address it directly with `readCheckpoint`. */
+	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 run parked. */
+	readonly parkedAt: number
+	/** Absolute expiry, when the park carries one. */
+	readonly deadlineAt?: number
+	/** Epoch ms at which the answer arrived. Only on `resolved`. */
+	readonly resolvedAt?: number
+}
+
+/**
+ * One run that has durable checkpoint state under the queried scope.
+ *
+ * **Extends {@link CheckpointRunScope}, and that is the load-bearing part.**
+ * A listing whose rows cannot be turned back into an addressable scope is a
+ * report, not a work queue. Because an entry IS a run scope,
+ * `findPendingCheckpoint(store, entry)`, `new CheckpointManager(store, entry)`
+ * and `resumeRun({ scope: entry, … })` all accept a row straight out of the
+ * listing — with no re-assembly, and so no chance of assembling it wrong.
+ *
+ * ### What an entry deliberately does NOT carry
+ *
+ * A run STATUS. A checkpoint is written mid-flight, so nothing in this store
+ * distinguishes a run that finished from one that died — the same fact
+ * {@link import('../../runtime/query/run-state.js').loadRunState} already
+ * states, where a rebuilt snapshot always reports `running` and the host's
+ * own record stays the authority. A `status` field here would answer
+ * "mid-flight" for every run that ever succeeded, and a sweeper built on it
+ * would resume finished work.
+ *
+ * A crash sweep is therefore: list every run with durable state under the
+ * scope, intersect with the host's own run records, resume the difference.
+ */
+export interface DurableRunEntry extends CheckpointRunScope {
+	/** How many checkpoints the run has right now. Pruning lowers it. */
+	readonly checkpointCount: number
+	/** Newest checkpoint by `createdAt` — the one a resume restores by default. */
+	readonly latestCheckpointId: CheckpointId
+	/** `createdAt` of {@link DurableRunEntry.latestCheckpointId}. */
+	readonly latestCheckpointAt: number
+	/** Absent when the run has never parked. */
+	readonly park?: ParkSummary
+}
+
+/** Filters and paging for {@link CheckpointStore.listDurableRuns}. */
+export interface ListDurableRunsOptions {
+	/**
+	 * Keep only runs whose park is in one of these states. A run that never
+	 * parked has no state and is excluded by ANY value here; omit the filter
+	 * to include it.
+	 */
+	readonly park?: readonly ParkState[]
+	/** Page size. Defaults to 100, clamped to at least 1. */
+	readonly limit?: number
+	/** Resume token from the previous page's {@link DurableRunPage.cursor}. */
+	readonly cursor?: string
+	/**
+	 * Clock for expiry, so a sweep can be tested and so every entry in one
+	 * page is judged against the same instant. Defaults to `Date.now()` — the
+	 * same seam `findPendingCheckpoint` already takes.
+	 */
+	readonly now?: number
+}
+
+/** One page of {@link DurableRunEntry}. */
+export interface DurableRunPage {
+	readonly entries: readonly DurableRunEntry[]
+	/**
+	 * Pass to the next call. **Absent means the listing is exhausted**, so
+	 * `while (cursor)` terminates; a store never returns a cursor it already
+	 * knows yields nothing.
+	 */
+	readonly cursor?: string
+}
+
 /**
  * Persistence contract consumed by
  * {@link import('../../runtime/query/checkpoint.js').CheckpointManager} and
@@ -49,6 +203,27 @@ export interface CheckpointRunScope {
  * not-found error. `deleteCheckpoint` is idempotent: deleting an absent
  * checkpoint succeeds as a no-op (mirrors the disk store's ENOENT
  * swallowing).
+ *
+ * ## Optional capabilities, and the rule that comes with them
+ *
+ * {@link CheckpointStore.listDurableRuns} is optional, following
+ * `SessionStore.listSessionsByProject`. A required method would break every
+ * host that has already implemented this interface, which is a `major` for
+ * what is otherwise an additive capability.
+ *
+ * The rule optionality obliges: **a caller of an optional capability REFUSES
+ * when it is absent; it never degrades.** An approval inbox built on a store
+ * that cannot list has to throw, because an empty page would say "nothing is
+ * waiting on a human" when the truth is "I cannot tell" — an optional
+ * dependency degrading a check, which this repository has been bitten by
+ * before. Reach the capability through
+ * {@link import('../../store/run/listing.js').listDurableRuns}, which
+ * refuses on absence rather than answering.
+ *
+ * Any capability added here later takes the same shape — optional method,
+ * refusing helper. A cross-process claim is the next one, and a two-worker
+ * deployment against a store with no lease has to fail loudly rather than
+ * proceed.
  */
 export interface CheckpointStore {
 	/** Persist one checkpoint. Overwrites an existing checkpoint with the same id. */
@@ -69,4 +244,49 @@ export interface CheckpointStore {
 
 	/** Delete a checkpoint by id. Absent checkpoints succeed as a no-op. */
 	deleteCheckpoint(scope: CheckpointRunScope, checkpointId: CheckpointId): Promise<void>
+
+	/**
+	 * Every run with durable checkpoint state under a scope ABOVE the run.
+	 * OPTIONAL — see the optional-capability rule on this interface.
+	 *
+	 * This is the read an approval inbox and a park sweep are built from, and
+	 * the one thing this contract had no way to express: every other accessor
+	 * needs a `runId`, so a host could only ask about runs it already knew
+	 * about. `hitlParkTtlMs` documents a host sweep as the reclamation path
+	 * for an unanswered park, and until this existed the sweep had no way to
+	 * enumerate what to sweep.
+	 *
+	 * ### Ordering, and why it is not chronological
+	 *
+	 * Rows come back ordered by `runId` ascending, and the cursor is a
+	 * position in that order.
+	 *
+	 * A cursor has to sort on a key that cannot move, or a paging caller
+	 * skips rows and repeats rows. Every time-valued key this store can
+	 * derive per run DOES move: the newest checkpoint's timestamp advances
+	 * whenever the run checkpoints again, and the oldest one's advances
+	 * whenever `CheckpointManager.prune` deletes oldest-first, which is what
+	 * pruning does. `runId` is the only immutable, unique per-run key
+	 * available, and being unique it is already a total order — the
+	 * degenerate case of the rule `orderChildren` follows (sort on a key that
+	 * cannot move, make the order total with an id), not a departure from it.
+	 *
+	 * The cost is that page order is arbitrary rather than oldest-first,
+	 * because run ids carry no timestamp. Entries carry `latestCheckpointAt`
+	 * and `park.parkedAt` so a caller can sort what it has read.
+	 *
+	 * A run whose FIRST checkpoint is written after paging began may be
+	 * missed by that pass — it lands at whatever `runId` it minted, possibly
+	 * behind the cursor. That is the right trade for a queue: the sweep runs
+	 * again and picks it up next pass, whereas a moving sort key loses runs
+	 * that already existed.
+	 *
+	 * @param scope contiguous prefix; `tenantId` required. Implementations
+	 *   reject a hole (`sessionId` with no `projectId`) rather than guessing.
+	 * @param options filters and paging. See {@link ListDurableRunsOptions}.
+	 */
+	listDurableRuns?(
+		scope: CheckpointListingScope,
+		options?: ListDurableRunsOptions,
+	): Promise<DurableRunPage>
 }