@claxedo/agent-runtime-contract 0.8.0 → 0.10.0

package/dist/mcp-app.d.ts

@@ -0,0 +1,24 @@
+export declare const MCP_APP_MIME = "text/html;profile=mcp-app";
+export declare const MCP_APP_MAX_BYTES: number;
+export declare const MCP_APP_DOMAIN_LIMIT = 32;
+export declare const MCP_APP_DOMAIN_MAX_LENGTH = 256;
+export declare const MCP_APP_CSP_KEYS: readonly ["connectDomains", "resourceDomains", "frameDomains", "baseUriDomains"];
+export type McpAppCsp = Partial<Record<(typeof MCP_APP_CSP_KEYS)[number], readonly string[]>>;
+export type McpAppReference = {
+    readonly resourceUri: string;
+    readonly csp?: McpAppCsp;
+    readonly prefersBorder?: boolean;
+};
+export type ToolMcpFacts = {
+    readonly server: string;
+    readonly tool: string;
+    readonly resultMeta?: Record<string, unknown>;
+    readonly structuredContent?: unknown;
+    readonly app?: McpAppReference;
+};
+export declare function mcpAppCsp(value: unknown): McpAppCsp | undefined;
+export type McpToolAudience = "model" | "app";
+export declare function mcpToolVisibleTo(toolMeta: unknown, audience: McpToolAudience): boolean;
+export declare function mcpAppResourceUri(toolMeta: unknown): string | undefined;
+export declare function toolMcpFacts(metadata: Record<string, unknown> | undefined): ToolMcpFacts | undefined;
+export declare function toolMcpHeader(metadata: Record<string, unknown> | undefined): Record<string, unknown>;

package/dist/message-page.d.ts

@@ -0,0 +1,101 @@
+import type { AgentMessage } from "./content";
+import type { AgentTurnOutcome } from "./sessions";
+/** The most messages a numeric page may ask for; every producer rejects a larger `limit`. */
+export declare const AGENT_MESSAGE_PAGE_LIMIT = 500;
+/**
+ * An authoritative transcript-window request. Cursors are opaque to every
+ * consumer.
+ *
+ * Semantic views are intentionally distinct from numeric pages. `latest-turn`
+ * returns the complete latest turn, or with `before` the complete turn that
+ * ends at that cursor; its cursor points at the turn's user message, so a
+ * reader walks back one whole turn per read. `latest-surface` returns at most
+ * its owning user and final message; its cursor points at the final message so
+ * ordinary paging restores every omitted intermediate without a second cursor
+ * protocol. The surface is a first-paint projection: the two envelopes whole,
+ * and their text parts only, whole. It is what a folded turn draws — the
+ * prompt, the fold row and the answer — so the answer is never the thing a
+ * budget trims.
+ */
+export type AgentMessagePageInput = {
+    view: "latest-turn";
+    limit?: never;
+    before?: string;
+} | {
+    view: "latest-surface";
+    limit?: never;
+    before?: never;
+} | {
+    view?: never;
+    limit: number;
+    before?: string;
+};
+/**
+ * A coverage request for one named turn, answered by whoever owns its journal.
+ *
+ * Either of the turn's two message ids names it: a caller that admitted the
+ * turn holds the user message id, while the journal keys the turn on the
+ * assistant message id, and neither side can derive the other.
+ */
+type AgentTurnCoverageInput = {
+    turnId: string;
+};
+/** What a `GET /session/:id/message` read asks for; the shapes are exclusive. */
+export type AgentMessageReadInput = AgentMessagePageInput | AgentTurnCoverageInput;
+/**
+ * How much of one turn a producer can account for.
+ *
+ * `complete` is a claim that nothing more will be added to this turn and that
+ * every message of it is in `messages`; only a producer holding the turn's
+ * journal can make it. `partial` names a turn whose extent is known and whose
+ * transcript is not all here yet. `unavailable` is the answer of a producer
+ * that cannot establish either, and it always carries a reason.
+ */
+export type AgentTurnCoverage = "complete" | "partial" | "unavailable";
+/** One turn, and how much of it the answering producer can account for. */
+export type AgentTurnCoveragePage = {
+    /** The turn that was asked for, never the turn the producer found instead. */
+    turnId: string;
+    coverage: AgentTurnCoverage;
+    /** Why the coverage is not `complete`, from the producer that decided it. */
+    reason?: string;
+    /** Present only when the journal records the turn finished. */
+    terminal?: AgentTurnOutcome;
+    /** The last journal sequence the answering projection applied, not the journal's head. */
+    committedSequence: number;
+    messages: AgentMessage[];
+};
+/** One chronological transcript page and the cursor for the next older page. */
+export type AgentMessagePage = {
+    /** Committed event-log position represented by a runtime-owned projection. */
+    maxEventOrdinal?: number;
+    messages: AgentMessage[];
+    nextCursor?: string;
+};
+/** The message shape the latest-surface projection reads. */
+export type LatestSurfaceMessage = {
+    info: Record<string, unknown>;
+    parts: unknown[];
+};
+/**
+ * Apply the producer-independent `latest-surface` projection: every text part
+ * of the message, in canonical order, and nothing else.
+ */
+export declare function projectLatestSurfaceMessage<TMessage extends LatestSurfaceMessage>(message: TMessage): TMessage;
+export declare function projectLatestSurfaceMessages<TMessage extends LatestSurfaceMessage>(messages: readonly TMessage[]): TMessage[];
+/** An authoritative message-page producer rejected the request. */
+export declare class AgentMessagePageError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * The `before` cursor a message-page producer hands out: its own versioned
+ * prefix, then the session and the ordinal the next page ends before. A
+ * producer that changes the payload changes its prefix, so a cursor minted
+ * before is refused by version rather than misread.
+ */
+export declare function encodeMessagePageCursor(prefix: string, sessionId: string, ordinal: number): string;
+export declare function decodeMessagePageCursor(prefix: string, sessionId: string, input: string): number;
+/** The `limit`/`before`/`view` query of a message page read; every producer refuses a malformed one with a 400. */
+export declare function parseMessagePageQuery(limit: string | undefined, before: string | undefined, view?: string): AgentMessagePageInput | undefined;
+export {};

package/dist/permissions.d.ts

@@ -0,0 +1,47 @@
+export type PermissionDecision = "allow_once" | "allow_always" | "deny" | "reject_always";
+/**
+ * The three rungs every harness's permission surface is mapped onto.
+ *
+ * A LADDER, not a taxonomy: the rungs are ordered by how much runs without
+ * asking, and that ordering is the only thing shared across harnesses. What each
+ * rung concretely does is the harness's business and differs wildly — `auto` is
+ * an OS sandbox on codex and a model classifier on claude and cursor.
+ *
+ * `level` is therefore a HINT for choosing a default, never a promise about
+ * behaviour. Anything user-facing must show `AgentPermissionMode.name` — the
+ * harness's own word for it — because that is the only label guaranteed to
+ * describe what actually happens.
+ */
+export type AutoLevel = "ask" | "auto" | "full";
+/** One selectable permission mode, in the harness's own vocabulary. */
+export type AgentPermissionMode = {
+    id: string;
+    /** The harness's own name. Rendered as-is; never paraphrased. */
+    name: string;
+    description?: string;
+    /**
+     * Which rung this is, when it maps to one at all. Absent means the harness
+     * offers it but it does not correspond to a rung — still selectable, just not
+     * a candidate for the default.
+     */
+    level?: AutoLevel;
+};
+export type AgentPermissionModeState = {
+    modes: AgentPermissionMode[];
+    /**
+     * Read back from the harness, never assumed from the last write. An ACP agent
+     * may clamp this to a different mode when its available set changes.
+     */
+    currentModeId?: string;
+    /**
+     * Set when this harness has no mode surface. Distinct from `modes: []`, which
+     * means it has one and reported nothing — greying out for the right reason
+     * requires telling those apart.
+     */
+    unsupported?: string;
+    /**
+     * When the harness applies a change: acknowledged live control, next turn,
+     * or next agent session.
+     */
+    appliesFrom: "immediate" | "next-turn" | "next-session";
+};

package/dist/pi-providers.d.ts

@@ -0,0 +1,36 @@
+import type { PromptModel } from "./sessions";
+/**
+ * The providers Pi can be launched on, and the stored rows each one can be
+ * launched from.
+ *
+ * Here rather than beside either consumer, because two of them ask the same
+ * question and a disagreement between them is invisible: the credential
+ * catalog decides whether Settings calls a provider connected, and the harness
+ * decides whether it writes that provider an overlay. Held apart, a provider
+ * reads as connected and then has nothing to bind at the turn.
+ *
+ * `openai-codex` is Pi's own name for the ChatGPT-plan endpoint. It is a
+ * different destination from its `openai` provider rather than the same one
+ * signed in differently, which is why the plan and the key never appear in
+ * each other's lists.
+ */
+export declare const PI_LAUNCH_PROVIDERS: readonly ["openai-codex", "anthropic", "openai", "openrouter", "google", "groq", "xai"];
+export type PiLaunchProvider = (typeof PI_LAUNCH_PROVIDERS)[number];
+/**
+ * The model a Pi draft starts on for each provider: the vendor's newest
+ * general model. Pi's catalog carries no release dates and lists ids
+ * alphabetically, so its first row is the oldest-looking name, not the newest.
+ */
+export declare const PI_DEFAULT_MODELS: Readonly<Partial<Record<PiLaunchProvider, string>>>;
+export declare const PI_PROVIDER_LABELS: Readonly<Record<PiLaunchProvider, string>>;
+/**
+ * The vendor and the vendor's own model id a model selection runs. Pi keys a
+ * model as `<vendor>/<model>` under its own provider `pi`; every other
+ * harness's selection already names its vendor.
+ */
+export declare function vendorModel(model: PromptModel): PromptModel;
+export declare function isPiLaunchProvider(providerID: string): providerID is PiLaunchProvider;
+/** The stored provider ids a Pi provider can be launched on, best first. */
+export declare function piCredentialProviderIDs(providerID: string): readonly string[];
+/** The Pi provider that spends a stored row of this provider id, where one does. */
+export declare function piProviderSpending(credentialProviderId: string): PiLaunchProvider | undefined;

package/dist/prompt-title.d.ts

@@ -0,0 +1,2 @@
+export declare const PROMPT_TITLE_MAX_CHARS = 60;
+export declare function promptTitle(prompt: string): string;

package/dist/provider-projection.d.ts

@@ -0,0 +1,166 @@
+import type { ConnectionSecretAuthority } from "./connections";
+/**
+ * What a harness receives in place of a credential.
+ *
+ * A bound row carries one binding's broker path, a signed capability for that
+ * binding alone, and the mode naming the header the harness must carry it in.
+ * The credential's own bytes stay with the authority that minted the binding
+ * and never reach this process.
+ *
+ * An unavailable row says the operator selected an account for this provider
+ * that cannot be bound. Without it a withdrawn account reaches a harness as an
+ * absent projection, and the turn runs on whatever login the machine holds —
+ * under an identity the operator did not choose.
+ */
+export type ProviderBinding = {
+    baseUrl: string;
+    placeholder: string;
+    authMode: "api-key" | "bearer";
+    /**
+     * Absent when the placeholder has no lifetime of its own: a sandbox provider
+     * that substitutes on egress holds the value until the authority withdraws
+     * it, so there is no moment at which the harness must stop using it.
+     */
+    expiresAt?: number;
+    /**
+     * Where the vendor's API root sits under `baseUrl`. A client that appends the
+     * whole vendor path itself (Claude Code, the Cursor SDK) is configured with
+     * `baseUrl`; one configured with an API root (Codex, Pi, the OpenCode engine)
+     * appends this. Absent from an authority that does not model vendor paths,
+     * which means `baseUrl` is already the root.
+     */
+    apiPath?: string;
+    /** The stored credential the placeholder spends, by its non-secret metadata, so a turn can say which account it ran on. */
+    account?: BindingAccount;
+};
+/** `revision` names the stored value handed over, so a refusal of it is told apart from a refusal of an older one. */
+export type BindingAccount = {
+    credentialId: string;
+    providerId: string;
+    label?: string;
+    revision?: number;
+};
+export type ProviderUnavailable = {
+    unavailable: true;
+    reason: string;
+};
+/**
+ * The refusal an account carries in a sandbox whose provider cannot keep the
+ * secret out of it: no harness running inside that sandbox may be handed it.
+ * A harness that calls the vendor from outside the sandbox still can.
+ */
+export declare const HARNESS_NEEDS_BROKERING = "harness_needs_brokering";
+/** The refusal a provider carries for a person who chose the organization's account for it while the organization has none. */
+export declare const ORG_ACCOUNT_UNAVAILABLE = "org_account_unavailable";
+/**
+ * Whether a row is the refusal rather than a binding.
+ *
+ * Takes any object rather than a `ProviderProjection`, because the same
+ * refusal travels alongside binding shapes this module does not own — the
+ * engine's provider overlay carries `baseURL`/`apiKey` — and a second copy of
+ * the predicate beside each of them is how two of them came to disagree.
+ */
+export declare function isProviderUnavailable(row: object): row is ProviderUnavailable;
+export type ProviderProjection = ProviderBinding | ProviderUnavailable;
+/**
+ * What an authority puts on the wire, before the runtime resolves it.
+ *
+ * An authority that mints the placeholder itself sends it. One whose sandbox
+ * provider issues the placeholder — the provider substitutes the value of an
+ * env var it filled, and only the sandbox can read it — names that env var
+ * instead, and `providerProjection` reads it off the runtime's own environment.
+ * Exactly one of the two is a projection; both or neither is not.
+ */
+export type ProviderBindingSource = Omit<ProviderBinding, "placeholder"> & ({
+    placeholder: string;
+    placeholderEnv?: undefined;
+} | {
+    placeholderEnv: string;
+    placeholder?: undefined;
+});
+export type ProviderProjectionSource = ProviderBindingSource | ProviderUnavailable;
+/**
+ * A credential handed to a harness that calls the vendor itself, in process,
+ * with no broker between: the subscription providers that read the account
+ * from the token, and a Durable Object host that has no egress broker.
+ */
+export type ProviderDirect = {
+    delivery: "direct";
+    baseUrl: string;
+    apiPath?: string;
+    secret: string;
+    authKind: "api-key" | "subscription";
+    expiresAt?: number;
+    account?: BindingAccount;
+};
+/**
+ * A fresh copy of a direct credential, asked of the authority that handed it
+ * over, under the proof of the turn that needs it; nothing when that authority
+ * has no newer one to give or no turn is running.
+ */
+export type DirectCredentialRefresh = (input: {
+    authority: ConnectionSecretAuthority;
+    credentialProviderId: string;
+    rejectedExpiresAt?: number;
+}) => Promise<ProviderDirect | undefined>;
+export declare function isProviderDirect(row: object): row is ProviderDirect;
+export type CredentialSnapshot<T = ProviderProjectionSource> = {
+    machineOwnerUserId: string;
+    /**
+     * The account each person spends, by user id and provider: their own, or the
+     * org's account for a provider they chose it for. Nothing else is spent.
+     */
+    accounts: Record<string, Record<string, T>>;
+    direct?: Record<string, Record<string, ProviderDirect>>;
+};
+/** The environment a `placeholderEnv` row is resolved against. */
+export type PlaceholderEnvironment = Record<string, string | undefined>;
+export declare function providerProjection(input: unknown, env?: PlaceholderEnvironment): ProviderProjection | undefined;
+export declare function providerDirect(input: unknown): ProviderDirect | undefined;
+/**
+ * What a row this validator cannot read does to the whole record.
+ *
+ * `reject` is for a map that crossed a process boundary: a producer that sent a
+ * row this runtime cannot read has said nothing trustworthy about the rest, so
+ * the snapshot is refused whole and the one already applied stays. Only a
+ * process projecting its own authority passes `unavailable`, where refusing
+ * everything would disable every working account over one malformed row; that
+ * row alone becomes an unavailable projection, which disables its provider and
+ * refuses a turn on it rather than letting the harness fall back to a login the
+ * operator did not choose.
+ */
+type ProviderProjectionRowPolicy = "reject" | "unavailable";
+export declare function credentialSnapshot(input: unknown, env: PlaceholderEnvironment): CredentialSnapshot<ProviderProjection> | undefined;
+export declare function providerProjectionRecord(input: unknown, env: PlaceholderEnvironment, options: {
+    onInvalid: ProviderProjectionRowPolicy;
+}): Record<string, ProviderProjection> | undefined;
+/**
+ * Whether a held projection is due for replacement. `all` is the caller saying
+ * the process lost track of time — a laptop resumed from sleep reads a clock
+ * later than any tick the timer saw — so nothing that expires may be trusted.
+ */
+export declare function projectionRenewalDue(input: {
+    at: number;
+    all?: boolean;
+}, renewAt: number | undefined): boolean;
+/**
+ * When the earliest placeholder or direct credential in this map has to be
+ * replaced: half of its own lifetime before it expires, so a turn that starts
+ * just before renewal still finishes on a valid one.
+ *
+ * Read from `expiresAt` rather than from a fixed interval, because the lifetime
+ * belongs to the authority that minted the placeholder and can be shorter than
+ * any interval chosen here. A map carrying no row that expires never needs
+ * renewing.
+ */
+export declare function projectionRenewalDueAt(auth: Record<string, ProviderProjectionSource | ProviderProjection | ProviderDirect>, appliedAt: number): number | undefined;
+/**
+ * The earliest renewal any account row of a snapshot needs, across every
+ * person, and none of its direct rows: for an authority whose direct
+ * credentials are renewed by the harness mid-turn and whose placeholders are
+ * its own to re-deliver.
+ */
+export declare function accountsRenewalDueAt(auth: Pick<CredentialSnapshot, "accounts" | "direct">, appliedAt: number): number | undefined;
+/** The earliest renewal any row of a snapshot needs, across every person's accounts and direct credentials. */
+export declare function credentialSnapshotRenewalDueAt(auth: CredentialSnapshot<ProviderProjection>, appliedAt: number): number | undefined;
+export {};

package/dist/raw-harness-event.d.ts

@@ -0,0 +1,7 @@
+export type RawHarnessEvent = {
+    source: string;
+    method?: string;
+    payload: unknown;
+    receivedAt?: number;
+};
+export declare function rawHarnessEvent(input: RawHarnessEvent): RawHarnessEvent;

package/dist/recovery/actions.d.ts

@@ -0,0 +1,20 @@
+import { type RecoveryTargetScope, type RecoveryTarget } from "./targets";
+export declare const RECOVERY_ACTIONS: readonly ["inspect", "cancel_turn", "reconcile_session", "retire_harness", "drain_daemon", "stop_daemon", "release_drain"];
+export type RecoveryAction = (typeof RECOVERY_ACTIONS)[number];
+export declare const RECOVERY_MUTATING_ACTIONS: readonly ["cancel_turn", "reconcile_session", "retire_harness", "drain_daemon", "stop_daemon", "release_drain"];
+export type RecoveryMutatingAction = (typeof RECOVERY_MUTATING_ACTIONS)[number];
+/**
+ * `read_operation` reads an existing operation by id, so it is not itself a
+ * `RecoveryAction`: it has no target, no scope and no receipt of its own.
+ */
+export declare const RECOVERY_READ_ACTIONS: readonly ["inspect", "read_operation"];
+export type RecoveryReadAction = (typeof RECOVERY_READ_ACTIONS)[number];
+export declare function isMutatingRecoveryAction(action: RecoveryAction): action is RecoveryMutatingAction;
+/**
+ * Which target an action may name. `reconcile_session` accepts a turn so a
+ * caller can narrow reconciliation to one turn of a session; every other
+ * action has exactly the owner its postcondition is written against.
+ */
+export declare const RECOVERY_ACTION_SCOPES: Readonly<Record<RecoveryAction, readonly RecoveryTargetScope[]>>;
+/** Incoming requests and published operations must obey the same action-to-owner constraint. */
+export declare function scopedTarget(action: RecoveryAction, input: unknown): RecoveryTarget;

package/dist/recovery/budgets.d.ts

@@ -0,0 +1,16 @@
+export type RecoveryBudgets = {
+    ackMs: number;
+    providerQueryMs: number;
+    gracefulCancelMs: number;
+    termGraceMs: number;
+    killVerifyMs: number;
+    reconcileMs: number;
+    drainMs: number;
+};
+export declare const DEFAULT_RECOVERY_BUDGETS: Readonly<RecoveryBudgets>;
+/**
+ * The deadline a child phase may run to. The parent caps it, so a sequence of
+ * child phases cannot multiply the deadline the caller was promised. An already
+ * expired parent yields `now`, which every phase treats as no time left.
+ */
+export declare function capChildBudget(parentDeadlineAt: number, childMs: number, now: number): number;

package/dist/recovery/facts.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The owner's identity on the wire and across a restart. The in-process object
+ * generation is a different value and is never sent: it cannot survive the
+ * process that minted it, so a stale caller could not be told apart from a
+ * replacement one.
+ */
+export type RecoveryGeneration = string;
+export declare const EXECUTION_FACTS: readonly ["running", "terminal", "unknown"];
+export declare const CLEANUP_FACTS: readonly ["owned", "verified_clear", "unknown"];
+export declare const PERSISTENCE_FACTS: readonly ["committed", "pending", "unavailable"];
+export type ExecutionFact = (typeof EXECUTION_FACTS)[number];
+export type CleanupFact = (typeof CLEANUP_FACTS)[number];
+export type PersistenceFact = (typeof PERSISTENCE_FACTS)[number];
+/** `observedAt` is epoch milliseconds; the wire carries no Date. */
+export type RecoveryFactEvidence<V extends string> = {
+    value: V;
+    source: string;
+    observedAt: number;
+    generation: RecoveryGeneration;
+};
+/**
+ * Execution, cleanup and persistence are three fields rather than one status
+ * because they are three independent events: a provider can confirm
+ * cancellation while a turn-owned child survives, and an exited process group
+ * can still fail to finalize in SQLite. A single boolean outcome can let a
+ * timed-out stop read as success and admit conflicting work.
+ *
+ * Session availability is deliberately absent. `AgentRuntimeStatus`
+ * and `ExecutionAvailability` remain the only session-status authority; a
+ * recovery operation's state describes the command, not the transcript.
+ */
+export type RecoveryFacts = {
+    execution: RecoveryFactEvidence<ExecutionFact>;
+    cleanup: RecoveryFactEvidence<CleanupFact>;
+    persistence: RecoveryFactEvidence<PersistenceFact>;
+};
+export declare function parseRecoveryFacts(input: unknown): RecoveryFacts;

package/dist/recovery/operations.d.ts

@@ -0,0 +1,66 @@
+import { type RecoveryAction } from "./actions";
+import { type RecoveryFacts } from "./facts";
+import { type RecoveryTarget } from "./targets";
+export declare const RECOVERY_OPERATION_STATES: readonly ["accepted", "running", "succeeded", "failed", "needs_action"];
+export type RecoveryOperationState = (typeof RECOVERY_OPERATION_STATES)[number];
+export declare const RECOVERY_PHASES: readonly ["ack", "provider_query", "graceful_cancel", "term_grace", "kill_verify", "reconcile", "drain"];
+export type RecoveryPhase = (typeof RECOVERY_PHASES)[number];
+/** A volatile receipt was never durably recorded and never survives a restart. */
+export type RecoveryReceipt = "durable" | "volatile";
+export type RecoveryNextAction = {
+    action: RecoveryAction;
+    scopePreviewRequired: boolean;
+    reason: string;
+};
+export declare const RECOVERY_ERROR_CODES: readonly ["provider_unreachable", "cancellation_unsupported", "cancellation_timeout", "signal_denied", "exit_unverified", "ownership_unverified", "persistence_unavailable", "projection_failed", "generation_retired", "authority_lost", "deadline_exceeded", "owner_unavailable", "internal_error"];
+export type RecoveryErrorCode = (typeof RECOVERY_ERROR_CODES)[number];
+/**
+ * `message` is the whole public payload by construction: there is no free-form
+ * details field, so a credential or a raw tool argument has nowhere to ride
+ * out to a caller.
+ */
+export type RecoveryError = {
+    code: RecoveryErrorCode;
+    /** The owner that reported it, by its own name. */
+    origin: string;
+    target: RecoveryTarget;
+    stage: RecoveryPhase;
+    executionMayContinue: boolean;
+    message: string;
+    at: number;
+};
+export type RecoveryOperation = {
+    operationId: string;
+    requestId: string;
+    target: RecoveryTarget;
+    action: RecoveryAction;
+    scopeRevision: string;
+    attempt: number;
+    state: RecoveryOperationState;
+    phase: RecoveryPhase;
+    phaseDeadlineAt: number;
+    facts: RecoveryFacts;
+    initiatingError?: RecoveryError;
+    cleanupErrors: RecoveryError[];
+    nextActions: RecoveryNextAction[];
+    receipt: RecoveryReceipt;
+    linkedOperationId?: string;
+    createdAt: number;
+    updatedAt: number;
+};
+/**
+ * How long a settled recovery operation stays listed and stored. Ten reconcile
+ * budgets: long enough that a caller which lost its connection can still read
+ * its own receipt, short enough that the list is current work. An operation
+ * whose facts still show cleanup owned or unknown, or persistence pending, is
+ * exempt at every layer: it is the only record of an undischarged obligation.
+ */
+export declare const RECOVERY_OPERATION_RETENTION_MS: number;
+/**
+ * Applies the latest evidence to an attempt. A terminal attempt keeps its
+ * state: later evidence corrects the facts, but an attempt that timed out is
+ * not rewritten into a success.
+ */
+export declare function finalizeRecoveryOperation(operation: RecoveryOperation, facts: RecoveryFacts): RecoveryOperation;
+export declare function parseRecoveryError(input: unknown): RecoveryError;
+export declare function parseRecoveryOperation(input: unknown): RecoveryOperation;

package/dist/recovery/outcomes.d.ts

@@ -0,0 +1,48 @@
+import { type RecoveryOperation } from "./operations";
+import { type RecoveryTarget } from "./targets";
+/** The sessions and resources an escalation would interrupt, named individually. */
+export type RecoveryScopePreview = {
+    sessions: string[];
+    resources: string[];
+    summary: string;
+};
+export type RecoveryRefusal = {
+    kind: "generation_conflict";
+    message: string;
+    current?: RecoveryTarget;
+} | {
+    kind: "intent_conflict";
+    message: string;
+    requestId: string;
+} | {
+    kind: "receipt_expired";
+    message: string;
+    requestId: string;
+} | {
+    kind: "scope_changed";
+    message: string;
+    scopeRevision: string;
+    preview: RecoveryScopePreview;
+} | {
+    kind: "unauthorized";
+    message: string;
+} | {
+    kind: "unavailable";
+    message: string;
+} | {
+    kind: "version_update_required";
+    message: string;
+    contractVersion: number;
+};
+export type RecoveryOutcome = {
+    kind: "operation";
+    operation: RecoveryOperation;
+} | {
+    kind: "refused";
+    refusal: RecoveryRefusal;
+};
+export declare function parseRecoveryRefusal(input: unknown): RecoveryRefusal;
+export declare function serializeRecoveryOutcome(outcome: RecoveryOutcome): string;
+/** Accepts the HTTP body as text or an already decoded IPC value. */
+export declare function parseRecoveryOutcome(input: unknown): RecoveryOutcome;
+export declare function isRecoveryOutcome(value: unknown): value is RecoveryOutcome;

package/dist/recovery/payload-line.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Marks the line carrying a recovery tool's JSON payload.
+ *
+ * A tool answers in two parts — a sentence a person reads, then the payload a
+ * renderer decodes — and they arrive joined into one string. Without a marker a
+ * reader has to guess where the prose stops, and the first guess (the first
+ * line opening a brace) silently lost the payload as soon as the prose above it
+ * changed shape.
+ */
+export declare const RECOVERY_PAYLOAD_PREFIX = "recovery-payload: ";
+/**
+ * The payload a recovery tool marked, or nothing when the text carries none.
+ *
+ * The last marked line wins. An owner's prose precedes the payload and may
+ * quote a marker back — a refusal message repeating what a caller sent, for
+ * instance — and the tool writes its own payload last, so reading from the end
+ * cannot be talked into decoding someone's quotation instead.
+ */
+export declare function readRecoveryPayloadLine(text: string): string | undefined;

package/dist/recovery/postconditions.d.ts

@@ -0,0 +1,18 @@
+import { type RecoveryAction } from "./actions";
+import { type RecoveryFacts } from "./facts";
+import { type RecoveryOutcome } from "./outcomes";
+export declare function recoveryPostconditionHolds(action: RecoveryAction, facts: RecoveryFacts): boolean;
+/**
+ * Whether the turn is over and the record of it is durable: the postcondition a
+ * dependent mutation waits on, and the only honest reading of "it stopped".
+ *
+ * The operation's state is not that test. `cancel_turn` additionally requires
+ * `cleanup: verified_clear` to reach `succeeded`, which an adapter reports only
+ * when it can prove nothing the turn started survives; a harness that cannot
+ * prove it leaves cleanup `unknown`, so a working cancellation closes as
+ * `needs_action`. Reading that as "did not stop" marks every healthy Stop a
+ * failure and blocks the revert, undo and handoff that need only the turn to be
+ * over and written down. Cleanup stays a separate fact rather than a weaker
+ * form of this one.
+ */
+export declare function turnStopped(outcome: RecoveryOutcome): boolean;