@intentface/latch-core 0.9.1

package/dist/runtime.d.ts

@@ -0,0 +1,670 @@
+import type { Experimental_SandboxSession } from "ai";
+import type { AppMessage } from "./message.js";
+import type { ReconstructPrincipal } from "./principal.js";
+import type { ContextDefinition } from "./context.js";
+import type { AgentConfig, AgentFactory, AgentInfo, ToolSource } from "./agent.js";
+import type { MemoryProvider } from "./memory.js";
+import { type Pricing } from "./pricing.js";
+import { type PromptCachingPlan } from "./prompt-caching.js";
+import type { TurnTrigger, LatchTelemetry } from "./telemetry.js";
+import { type LatchLimits } from "./limits.js";
+import type { ChatRecord, RunRecord, RunStatus, ScheduleRecord, StorageAdapter } from "./storage.js";
+/**
+ * The Runtime — composition root + operations facade.
+ *
+ * `createRuntime(config)` wires the chosen seams (storage, context, agent
+ * registry) and exposes the operations. Routes/cron/CLI/tests all call the
+ * runtime, never the seams directly. It's stateless and re-creatable (holds
+ * adapters, no per-run state — that lives in the DB), so it's serverless-safe.
+ *
+ * T1: `handleChat` runs one turn with a `ToolLoopAgent` and persists via the
+ * stock AI SDK stream helper — `onStepEnd` → runs/usage, `onFinish` → messages.
+ */
+/**
+ * T2 durability (opt-in). When enabled, each turn claims a single-writer lease,
+ * heartbeats it while streaming, and aborts if the lease is lost. A reaper
+ * (`runtime.cron()` → `sweep`, driven by cron) reclaims runs whose owner died.
+ */
+export interface DurabilityConfig {
+    enabled?: boolean;
+    /** Lease lifetime in ms; a run is reapable once `now > leaseExpiresAt` (default 30s). */
+    leaseTtlMs?: number;
+    /** Heartbeat cadence in ms; must be comfortably < leaseTtlMs (default 10s). */
+    heartbeatMs?: number;
+    /** Stable owner id for this runtime instance (default: random per process). */
+    instanceId?: string;
+}
+/**
+ * A connection registry seam: resolve a set of connection names to a single
+ * per-turn tool source. `@intentface/latch-mcp`'s `McpConnections` satisfies
+ * this structurally, so `core` stays decoupled from MCP. When set on the
+ * runtime, an agent's `connections: [...]` names are resolved through it.
+ */
+export interface ConnectionRegistry<P> {
+    hostFor(names: string[]): ToolSource<P>;
+}
+/**
+ * A source of agents resolved at request time (e.g. DB/UI-created), consulted
+ * when a name isn't in the static `agents` registry. Lets agents be data, not
+ * just code — scoped per `Principal`. `@intentface` platforms back this with a
+ * table; `resolve` builds the same `AgentConfig` a code agent would.
+ */
+export interface DynamicAgentStore<P> {
+    /** Build an agent's config for this caller, or undefined if not found. */
+    resolve(name: string, principal: P): AgentConfig<P> | undefined | Promise<AgentConfig<P> | undefined>;
+    /** The caller's dynamic agents, for the picker. */
+    list(principal: P): AgentInfo[] | Promise<AgentInfo[]>;
+}
+export interface RuntimeConfig<P, RuntimeContext = unknown> {
+    storage: StorageAdapter<P>;
+    context: ContextDefinition<P, RuntimeContext>;
+    /** The agent registry: name → factory (file-based or DB-driven upstream). */
+    agents: Record<string, AgentFactory<P, RuntimeContext>>;
+    durability?: DurabilityConfig;
+    /** Optional cost calculation. Without it, recorded cost is 0. */
+    pricing?: Pricing;
+    /**
+     * Connection registry used to resolve each agent's `connections: [...]` names
+     * into a per-turn tool source (MCP servers / integrations). Optional — without
+     * it, `connections` on an agent is ignored.
+     */
+    connections?: ConnectionRegistry<P>;
+    /**
+     * Resolve agents not in the static `agents` registry (e.g. DB/UI-created),
+     * per caller. Optional — without it, only code-declared agents exist.
+     */
+    dynamicAgents?: DynamicAgentStore<P>;
+    /**
+     * Memory seam: gives agents that declare `memory` persistent cross-session
+     * memory (compiled index injected into instructions + scope-bound
+     * `memory_search`/`memory_save` tools). Optional — without it, an agent's
+     * `memory` declaration is ignored. See `MemoryProvider`.
+     */
+    memory?: MemoryProvider<P>;
+    /**
+     * Rebuild a `Principal` from the opaque identity blob a run stored, for
+     * resume/cron (no request). Default: passthrough (`identity as P`). Override to
+     * re-hydrate (e.g. re-fetch fresh identity) or validate on resume.
+     */
+    reconstructPrincipal?: ReconstructPrincipal<P>;
+    /**
+     * Next-fire evaluator for scheduled agents: given a cron expression, a lower
+     * bound (epoch ms), and an optional IANA timezone the expression is
+     * interpreted in, return the next fire time (epoch ms) or null if it never
+     * fires again. Keeps core cron-library-free — wire e.g. `croner`. Required to
+     * create recurring schedules.
+     */
+    cron?: (expr: string, afterMs: number, timezone?: string) => number | null;
+    /**
+     * Optional per-fire override for `runDue`, so a host can run a scheduled turn
+     * somewhere the default can't reach — typically a chat channel, where the
+     * report should land in the conversation the person actually replies in.
+     *
+     * Return true when the host ran (and delivered) this fire ITSELF; core then
+     * skips its own fresh-chat run. Anything else — false, absent, or a throw —
+     * falls through to the default, so a host whose delivery target has gone
+     * stale (bot disabled, user unlinked) still gets the work done in a chat
+     * rather than losing the fire.
+     *
+     * A host that wants the SAME accounting the default path gets can return the
+     * object form instead of a bare boolean: `chatId` lets the next occurrence's
+     * `onParked` check see this fire's conversation, and `parked` joins `runDue`'s
+     * `parked` count. Core cannot derive either itself — the host owns the chat a
+     * channel fire runs in. Omit them and this fire simply isn't accounted (the
+     * bare-boolean behavior), which is correct for a host that reports its own.
+     *
+     * Core keeps owning the claim, the lease and the advance either way, and
+     * stays entirely channel-blind: `schedule.delivery` is opaque here and only
+     * ever interpreted by this hook.
+     */
+    runSchedule?: (input: {
+        schedule: ScheduleRecord;
+        principal: P;
+    }) => Promise<boolean | {
+        handled: boolean;
+        chatId?: string;
+        parked?: boolean;
+    }>;
+    /**
+     * Resolve a per-session sandbox for an agent that declares `sandbox: true`.
+     * Returns the AI SDK `Experimental_SandboxSession` passed to the model
+     * (`agent.stream({ experimental_sandbox })`) and read by sandbox tools. Keeps
+     * core free of any sandbox backend dep — the platform supplies the provider
+     * (e.g. just-bash / Daytona). The sandbox is per chat (`chatId`).
+     */
+    sandbox?: (args: {
+        principal: P;
+        chatId: string;
+        agent: string;
+        provider?: string;
+    }) => Experimental_SandboxSession | Promise<Experimental_SandboxSession>;
+    /**
+     * The default harness tools, supplied by the platform (kept out of core so we
+     * carry no sandbox/QuickJS deps). `sandbox` tools (bash/read_file/write_file/
+     * glob/grep) operate on the resolved `experimental_sandbox`; `app` tools
+     * (web_fetch, askUser, scheduling, …) run in the app process. Merged into an
+     * agent's toolset per its `sandbox`/`defaultTools` flags.
+     */
+    harnessTools?: {
+        sandbox?: Record<string, unknown>;
+        /**
+         * App-process tools. A static record for principal-independent tools
+         * (web_fetch, …), or a per-turn factory when the tools must bind to the
+         * caller (e.g. workspace file/db tools scoped to the user's permissions
+         * and the current chat).
+         */
+        app?: Record<string, unknown> | ((args: {
+            principal: unknown;
+            chatId: string;
+            agent: string;
+        }) => Record<string, unknown> | Promise<Record<string, unknown>>);
+        /**
+         * Platform render tool(s) — attached only when an agent sets
+         * `renderTools: true`, never by `defaultTools`. Kept a separate capability
+         * (like `sandbox`) because it's platform-specific (needs a deployed render
+         * service) and should be opted into explicitly.
+         */
+        render?: Record<string, unknown>;
+        /**
+         * Default approval policy for harness tools, by tool name (e.g.
+         * `{ create_schedule: "user-approval" }`). Applied only to tools actually
+         * attached to the agent, and merged like a tool source's: the AGENT WINS
+         * for names it lists in its own `toolApproval`, so a host can ship a
+         * side-effecting harness tool gated by default without freezing that
+         * choice.
+         */
+        approval?: Record<string, unknown>;
+    };
+    /**
+     * Resolve the model provider's NATIVE web tools (server-side search/fetch) for
+     * a model id — kept out of core so it carries no provider SDK dep. Merged into
+     * an agent's toolset when it sets `providerWebTools`. Return `{}` for providers
+     * without native web tools.
+     */
+    resolveProviderTools?: (modelId: string) => Record<string, unknown>;
+    /**
+     * Resolve an agent's `effort` to provider-specific reasoning options for a
+     * model id — kept out of core (no provider SDK dep). Returns the
+     * `providerOptions` (keyed by provider id) and an optional `maxOutputTokens`
+     * (token-budget providers need the budget to stay under the model's max).
+     * Return `undefined` to leave the provider default (e.g. non-reasoning model).
+     */
+    resolveReasoningOptions?: (modelId: string, effort: string) => {
+        providerOptions?: Record<string, unknown>;
+        maxOutputTokens?: number;
+    } | undefined;
+    /**
+     * Resolve the prompt-caching plan for a model id. Supply it when you own a
+     * model catalog (you know the provider family better than the model object
+     * does) or need per-principal cache routing — typically
+     * `promptCachingPlanFor(providerOf(modelId), { agent, cacheKeySuffix })`.
+     * `memoryScoped` is true when the turn's system prompt is per-principal
+     * (memory-enabled agent) — use it to scope OpenAI's cache routing key.
+     *
+     * ABSENT hook → caching defaults ON for first-party Anthropic/OpenAI models
+     * (see `defaultPromptCachingPlan`; measured ~6x unit cost on MCP-heavy
+     * agents). Opt out with `resolvePromptCaching: () => undefined`, or per turn
+     * with `promptCaching: false`. Returning `undefined` for a model disables
+     * caching for it.
+     */
+    resolvePromptCaching?: (modelId: string, args: {
+        agent: string;
+        memoryScoped: boolean;
+        principal: P;
+    }) => PromptCachingPlan | undefined;
+    /**
+     * The observation seam (kept out of core — no OTEL/vendor dep): per-run AI
+     * SDK telemetry options, an optional trace wrapper around the model call, a
+     * per-step hook and a post-turn hook. A full tracer
+     * (`@intentface/latch-langfuse`) or just the callbacks a host wants (usage
+     * rollups, per-tool analytics, "a scheduled fire parked — notify someone").
+     * Fires for subagent turns too — distinguish via `depth` and `trigger`.
+     * Optional — without it, nothing is observed and behavior is unchanged.
+     */
+    telemetry?: LatchTelemetry<P>;
+    /**
+     * Per org / user / agent budgets on turns, tokens and cost (see `limits.ts`).
+     * The host names the counters a turn counts against and their caps; the
+     * runtime refuses at admission (`LimitExceededError`, HTTP 429), stops the
+     * tool loop at the tightest remaining token budget, and settles usage on
+     * finish. Optional — without it, nothing is limited.
+     */
+    limits?: LatchLimits<P>;
+}
+export interface HandleChatInput<P> {
+    /** Which registered agent to run. */
+    agent: string;
+    /** Client-chosen chat id (create-or-continue). Omit to start a new chat. */
+    chatId?: string;
+    /** Resolved by the caller's ContextResolver (isolation flows from this). */
+    principal: P;
+    /** The incoming user message. */
+    message: AppMessage;
+    /** Optional original request, passed to context.build. */
+    request?: Request;
+    /**
+     * Per-turn request payload, passed to `context.build` and the agent factory.
+     * EPHEMERAL: never persisted with the run (only the principal is stored as
+     * `runs.identity`), so it is absent on resume/cron. Use it for request-scoped
+     * inputs (active document, UI selection, parsed body fields) — never identity.
+     */
+    turnContext?: unknown;
+}
+export interface Runtime<P> {
+    /** The agents available to the caller (code-declared + dynamic) — for a picker. */
+    listAgents(principal: P): Promise<AgentInfo[]>;
+    /** Run one turn; returns a streaming UIMessage `Response`. */
+    handleChat(input: HandleChatInput<P>): Promise<Response>;
+    /**
+     * Run one agent to completion once, autonomously, in an isolated throwaway
+     * thread (no streaming) — for programmatic use like the Agent Builder testing
+     * an agent it just created. `blockGated` (default true) stubs approval-gated
+     * (mutating) tools so a test run has no real side effects; pass false for a
+     * true end-to-end run. Returns the throwaway threadId + the final answer.
+     */
+    runAgent(input: {
+        principal: P;
+        agent: string;
+        prompt: string;
+        threadId?: string;
+        blockGated?: boolean;
+        /**
+         * Per-turn request payload, passed to `context.build` and the agent
+         * factory (see `HandleChatInput.turnContext`). Ephemeral — never persisted,
+         * absent on resume.
+         */
+        turnContext?: unknown;
+        /**
+         * Per-turn prompt-caching override. `false` = set no caching provider
+         * options for this run (the control arm of an A/B comparison); default on
+         * when the runtime has a `resolvePromptCaching` hook.
+         */
+        promptCaching?: boolean;
+        /**
+         * How to classify this run on the telemetry run meta (see `TurnTrigger`).
+         * Defaults to `"programmatic"` — there is no client stream here, so the
+         * safe assumption is that nobody is watching, and a host that knows better
+         * (a webhook with a user waiting) says so by passing `"chat"`.
+         */
+        trigger?: TurnTrigger;
+    }): Promise<{
+        threadId: string;
+        answer: string;
+    }>;
+    /**
+     * Summarize a conversation and append a compaction boundary, so later turns
+     * send the model the summary instead of the turns it replaces. Stored history
+     * is untouched — this shrinks the model projection, not the record. Null when
+     * there's too little to compact (or the chat isn't the caller's); throws
+     * `PendingApprovalError` when the last turn is paused awaiting a human.
+     */
+    compactChat(input: {
+        chatId: string;
+        principal: P;
+        /** Optional steer for the summary ("keep the training plan"). */
+        focus?: string;
+        request?: Request;
+        turnContext?: unknown;
+    }): Promise<{
+        summary: string;
+        compacted: number;
+    } | null>;
+    /**
+     * Client-projected conversation history (`toClientMessages`): the stored
+     * messages with `internal`/`redacted` ones filtered out. For rendering past
+     * turns on load.
+     */
+    loadHistory(input: {
+        chatId: string;
+        principal: P;
+    }): Promise<AppMessage[]>;
+    /**
+     * The caller's chats, most-recent first (for a chat list / sidebar).
+     * `kind` filters to one chat kind (e.g. `'user'` to hide the runtime's
+     * internal `sub_…` threads); omitted → all kinds (back-compatible default).
+     */
+    listChats(input: {
+        principal: P;
+        limit?: number;
+        kind?: string;
+    }): Promise<ChatRecord[]>;
+    /**
+     * One chat by id, scoped to the caller (null when it isn't theirs or doesn't
+     * exist). A direct lookup, not a capped scan — so "does this chat exist, and
+     * whose agent is it?" stays correct for a tenant with any number of chats.
+     */
+    getChat(input: {
+        principal: P;
+        id: string;
+    }): Promise<ChatRecord | null>;
+    /** The caller's runs, most-recent first (status, usage, cost — for an ops view). */
+    listRuns(input: {
+        principal: P;
+        limit?: number;
+    }): Promise<RunRecord[]>;
+    /**
+     * One run by id, scoped to the caller: returns it only when the run's chat is
+     * owned by `principal` (else null). A direct lookup — no capped scan — so it's
+     * safe for ownership checks on arbitrarily old runs.
+     */
+    getRun(input: {
+        principal: P;
+        runId: string;
+    }): Promise<RunRecord | null>;
+    /**
+     * Resume an interrupted run (requires durability). Re-claims it exactly-once,
+     * re-runs the turn from persisted history, and completes it server-side.
+     * Returns the run's final state, or null if it wasn't resumable (already
+     * completed, or claimed by another node).
+     */
+    resume(runId: string): Promise<RunOutcome | null>;
+    /**
+     * Reaper + auto-resume in one call — the durability half of `cron()`. Reaps
+     * lease-expired runs, then resumes each whose attempt count is still under
+     * `maxAttempts` (default 5; the cap stops poison runs from looping forever).
+     * Safe to fire on every node: reap and reclaim are atomic, so each run is
+     * handled exactly once. Requires durability.
+     */
+    sweep(opts?: {
+        now?: number;
+        maxAttempts?: number;
+        error?: string;
+    }): Promise<{
+        reaped: RunRecord[];
+        resumed: RunOutcome[];
+    }>;
+    /**
+     * THE cron entry point — point a platform cron or the in-process scheduler at
+     * this and nothing else. Fires due schedules (`runDue`), then, when
+     * durability is on, reaps lease-expired runs and resumes them (`sweep`). One
+     * call per tick, so a deploy can't wire half of the operational surface. The
+     * two phases are isolated: a failure in one lands in `errors` and the other
+     * still runs. Safe to fire on every node concurrently (claims are atomic).
+     */
+    cron(opts?: {
+        now?: number;
+        maxAttempts?: number;
+    }): Promise<{
+        due: {
+            fired: number;
+            errors: number;
+            skipped: number;
+            parked: number;
+        };
+        reaped: RunRecord[];
+        resumed: RunOutcome[];
+        /** Phase failures (`"runDue: …"` / `"sweep: …"`) — reported, never thrown. */
+        errors: string[];
+    }>;
+    /**
+     * Apply HITL tool-approval decisions and continue the turn. Records each
+     * decision onto the persisted assistant message (approval-requested →
+     * approval-responded), then re-runs the agent from history: approved tools
+     * execute, denied ones are skipped. Returns the continuation's streaming
+     * Response. No suspension machinery — approvals round-trip as message state.
+     */
+    applyApproval(input: {
+        chatId: string;
+        principal: P;
+        decisions: ApprovalDecision[];
+        request?: Request;
+        /** Per-turn request payload (see HandleChatInput.turnContext). */
+        turnContext?: unknown;
+    }): Promise<Response>;
+    /**
+     * Resume a turn paused on a client-handled tool (no `execute`, e.g.
+     * `askUser`): record the supplied output onto the matching tool call and
+     * re-run from history. Returns the continuation stream, or an empty 200 if
+     * other client tool calls in the step still need results.
+     */
+    applyToolResult(input: {
+        chatId: string;
+        principal: P;
+        toolCallId: string;
+        output: unknown;
+        request?: Request;
+        /** Per-turn request payload (see HandleChatInput.turnContext). */
+        turnContext?: unknown;
+    }): Promise<Response>;
+    /**
+     * Schedule an agent to run on a cron expression (or `cron: null` for one-shot,
+     * fired on the next `runDue`). Captures the caller's identity for fire-time.
+     * Requires `cron` in the runtime config for recurring schedules.
+     */
+    schedule(input: {
+        principal: P;
+        agent: string;
+        cron: string | null;
+        /** IANA timezone the cron is interpreted in (e.g. "Europe/Helsinki"). */
+        timezone?: string;
+        prompt: string;
+        /**
+         * Opaque, host-interpreted delivery target for each fire (see
+         * `RuntimeConfig.runSchedule`). Stored verbatim; core never reads it.
+         */
+        delivery?: unknown;
+        /**
+         * What a fire does while the previous fire's chat is still parked waiting
+         * on a human (see `ScheduleRecord.onParked`). Default `"skip"`.
+         */
+        onParked?: "skip" | "fire";
+    }): Promise<ScheduleRecord>;
+    /** The caller's schedules. */
+    listSchedules(input: {
+        principal: P;
+    }): Promise<ScheduleRecord[]>;
+    /** Delete one of the caller's schedules. */
+    unschedule(input: {
+        principal: P;
+        id: string;
+    }): Promise<void>;
+    /**
+     * Make one of the caller's schedules due immediately. It then fires through
+     * the ordinary `runDue` path — same claim, same delivery, same advance — so
+     * "run now" can never drift from what the cron actually does.
+     *
+     * False when nothing was armed: unknown id, not the caller's, or already
+     * spent.
+     */
+    runScheduleNow(input: {
+        principal: P;
+        id: string;
+    }): Promise<boolean>;
+    /**
+     * Fire all due schedules across ALL tenants (system op — the cron entry point).
+     * Claims each, consumes the occurrence (advances `nextRunAt` BEFORE firing,
+     * so no concurrent claimer can fire it again), reconstructs its principal,
+     * and runs the turn in a fresh chat (or via `runSchedule`, when the host
+     * handles the fire). Point a platform cron (or the in-process scheduler) at
+     * this.
+     *
+     * Occurrences are at-most-once: a process that dies mid-fire does not retry
+     * the occurrence — the run row survives and `sweep()` resumes the turn
+     * instead, so recovery never means a second paid attempt.
+     *
+     * Awaits each fired turn to completion before returning. A driver that also
+     * gates on this promise (the in-process interval scheduler does) is stalled
+     * for the duration of the longest turn — fan out per tenant rather than
+     * looping serially if that matters to you.
+     *
+     * `skipped` counts occurrences consumed WITHOUT running because the previous
+     * fire's chat is still parked on a human (see `ScheduleRecord.onParked`) —
+     * distinct from `errors` so a quiet schedule is legible as "waiting on you",
+     * never mistaken for "ran fine" or "broken".
+     *
+     * `parked` counts fires that RAN and then stopped waiting on a human (an
+     * approval or question they cannot answer) — tokens spent, no answer
+     * delivered. They are counted in `fired` too: the turn did happen. A
+     * non-zero `parked` is the signal to go look — a cron whose every fire parks
+     * is paying for nothing, and for a one-shot schedule there is no later
+     * occurrence to notice. Chats awaiting a human are queryable via
+     * `ChatRecord.lastRunStatus`.
+     */
+    runDue(opts?: {
+        now?: number;
+    }): Promise<{
+        fired: number;
+        errors: number;
+        skipped: number;
+        parked: number;
+    }>;
+}
+/** A user's decision on one pending tool-approval request. */
+export interface ApprovalDecision {
+    approvalId: string;
+    approved: boolean;
+    reason?: string;
+}
+/** The terminal state of a resumed run. */
+export interface RunOutcome {
+    runId: string;
+    status: RunStatus;
+    attempt: number | null;
+}
+/**
+ * The minimal `UIMessageStreamWriter` surface we use: `merge` to fold in the
+ * model's stream, and `write` for custom data parts (exposed to tools/context).
+ */
+export interface TurnWriter {
+    write(part: unknown): void;
+    merge(stream: ReadableStream<unknown>): void;
+}
+/**
+ * The `data-subagent-progress` part `spawn_agent` streams into the PARENT
+ * turn while a subagent runs (one part, reconciled in place by id) — lets the
+ * host render the delegated conversation live instead of a silent spinner.
+ * Written immediately on spawn (empty `messages`) so the client learns the
+ * sub-thread id up front, then re-written (throttled) as the subagent streams.
+ */
+export interface SubagentProgressData {
+    /** The spawn_agent tool call this progress belongs to. */
+    toolCallId?: string;
+    agent: string;
+    threadId: string;
+    /** The sub-thread's current exchange: the prompt + the streaming assistant snapshot. */
+    messages: AppMessage[];
+}
+/** A subagent's undecided approval, lifted so the parent turn can surface it. */
+export interface SubagentPending {
+    approvalId: string;
+    toolName: string;
+    summary: string;
+}
+/**
+ * Thrown when work is attempted on a chat whose last turn is still paused
+ * awaiting a human — by `compactChat`, where the pause can also be a parked
+ * client tool call and there's no sensible way to summarize around it. Carries
+ * a stable `code` so the handler can map it to a 409 and the client can prompt
+ * the user to resolve it first.
+ *
+ * `handleChat` deliberately does NOT throw this: a new message supersedes the
+ * pause (see `declinePendingApprovals`).
+ */
+export declare class PendingApprovalError extends Error {
+    readonly code = "pending_approval";
+    constructor(message: string);
+}
+/**
+ * What crash recovery should DO with a run it just reclaimed, read off the tail
+ * of persisted history.
+ *
+ * The subtlety this exists for: finishing the tool loop and RECORDING that fact
+ * are two different writes. The per-step checkpoint is fire-and-forget at each
+ * step's end, while the run row only becomes `completed` in `onFinish`. Die in
+ * that gap and the row still says `active` with a lease — so the reaper takes a
+ * run whose work is already done and whose answer is already stored.
+ *
+ * Re-running the model there is worse than useless: it pays for a second
+ * generation, and (because the SDK reuses the message id) the new text lands in
+ * the same message as the old, so the reader can end up with the answer twice.
+ * Reconciling the row costs nothing and loses nothing.
+ *
+ *  - `superseded` — not produced here but by `supersededBy`, from the runs
+ *    table: the chat opened a later turn while this run sat reaped. Settle it as
+ *    errored with the same "superseded" outcome `openTurn` gives a stale run.
+ *  - `decision-pending` — a gate is awaiting a human. The row never got its
+ *    `awaiting_input`; settle it there and let `applyApproval` drive the rest.
+ *    (Reaping is scoped to `active`, so this only ever arrives via that gap.)
+ *  - `loop-finished` — the last step called no tool, which is exactly the
+ *    condition on which the tool loop stops; or it is waiting on a CLIENT-
+ *    handled tool (askUser), which `onFinish` also records as completed, the
+ *    answer arriving later via `applyToolResult`. The turn is done; settle it.
+ *  - `continue` — there is real work left (a tool result to consume, a step that
+ *    produced nothing, or no assistant message at all). Re-run the model.
+ *
+ * The yardstick for every verdict: what `onFinish` would have written had the
+ * process lived. That is what makes each one checkable — a `stopWhen` cut (step
+ * cap, token budget) leaves a tool part in the final step and so reads as
+ * `continue`, which costs a wasted turn but never loses work; the reverse
+ * mistake, calling an unfinished turn finished, would silently drop the user's
+ * request.
+ *
+ * The final step is the parts after the last `step-start`; a tool part there
+ * means the loop had gone round again and was still going.
+ */
+export type ResumeShape = "superseded" | "decision-pending" | "loop-finished" | "continue";
+/**
+ * Has this chat opened another turn since `run` started? Then `run` was
+ * superseded — the conversation moved on while it sat reaped — and it must
+ * settle rather than run: re-running would generate against a conversation that
+ * has moved on and, because the message id is reused, append the result to the
+ * later turn's message.
+ *
+ * Read off the RUNS, not the messages. Every user message is persisted together
+ * with its run (`openTurn`), so a later run in the chat is the one fact that
+ * proves a later turn exists. Messages cannot tell us this: user messages carry
+ * no run id, and when a turn crashes before its first checkpoint the previous
+ * turn's assistant message is legitimately the last assistant in history —
+ * reading either as "someone else's" marks a live run superseded and drops the
+ * user's request without a model call, which is the one failure worse than the
+ * bug this all fixes.
+ *
+ * Compaction runs summarise the conversation so far; they are not turns.
+ */
+export declare function supersededBy(run: Pick<RunRecord, "id" | "chatId" | "startedAt">, runs: readonly RunRecord[]): boolean;
+/**
+ * What a reclaimed run's OWN history says it needs. Pure: whether the chat has
+ * since moved on is `supersededBy`'s question, answered from the runs table.
+ */
+export declare function resumeShapeOf(messages: AppMessage[]): ResumeShape;
+/**
+ * The resume paths ({@link applyApproval} / {@link applyToolResult}) re-run the
+ * model from history whose LAST message is the assistant turn that paused — no
+ * fresh user message is appended. If that turn streamed trailing user-facing
+ * text before pausing (e.g. "…ready to create the page but needs your approval
+ * first"), the model projection ends on an assistant message. Some providers
+ * reject that ("This model does not support assistant message prefill. The
+ * conversation must end with a user message.").
+ *
+ * Drop the trailing text/reasoning that follows the final TOOL part of the last
+ * assistant message, so the projection ends on the tool result (a user turn) and
+ * the model generates a fresh continuation. Returns a shallow copy touching only
+ * the last message.
+ *
+ * **The anchor must be a part the model projection keeps.** `toModelMessages`
+ * drops every `data-*` part, so anchoring on a bubbled `data-subagent-approval`
+ * kept the text BEFORE it — leaving the projection ending on assistant text,
+ * i.e. exactly the prefill this exists to prevent. That is the shape the
+ * agent-builder produces on every approval round: `… tool-spawn_agent,
+ * data-subagent-progress, data-subagent-approval, step-start, text,
+ * data-subagent-approval`. Only `tool-*` / `dynamic-tool` anchor.
+ *
+ * `data-*` parts after the anchor are KEPT: the resumed turn's `onFinish`
+ * re-persists this message, so removing them would erase the approval markers
+ * the UI renders and `hasPendingApproval` reads. Trailing `step-start` is
+ * DROPPED along with the text: it is invisible content, but it instructs
+ * `convertToModelMessages` to open a NEW assistant message — and with the text
+ * gone, that message is empty, so the projection would still end on the
+ * assistant (`{ role: "assistant", content: [] }`), trading the prefill
+ * rejection for an empty-content one. The only thing in that step was the
+ * narration being removed, so history loses nothing but an empty divider.
+ * The trailing text is dropped from stored history too — it is provisional
+ * commentary about a decision that has now been made; the resumed turn
+ * regenerates the real continuation.
+ */
+export declare function trimTrailingAssistantPrefill(messages: AppMessage[], opts?: {
+    unanchored?: boolean;
+}): AppMessage[];
+export declare function clientErrorMessage(error: unknown): string;
+export declare function createRuntime<P, RC = unknown>(config: RuntimeConfig<P, RC>): Runtime<P>;
+//# sourceMappingURL=runtime.d.ts.map