@retinue/agentkit 0.1.0

package/dist/runtime/index.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Run lifecycle and execution limits — `docs/04-durable-runtime-and-hitl.md`.
+ */
+import type { PlatformError } from "../core/errors.js";
+import type { AgentId, ConversationId, PrincipalId, RunId, TenantId } from "../core/ids.js";
+export declare const RUN_STATUSES: readonly ["queued", "running", "waiting-for-question", "waiting-for-approval", "retry-pending", "completed", "failed", "cancelled"];
+export type RunStatus = (typeof RUN_STATUSES)[number];
+/**
+ * The state machine from the specification. A transition absent from this map is a
+ * bug, not an undefined behaviour — the worker rejects it rather than guessing.
+ */
+export declare const RUN_TRANSITIONS: Readonly<Record<RunStatus, readonly RunStatus[]>>;
+export declare const canTransition: (from: RunStatus, to: RunStatus) => boolean;
+export declare const isTerminal: (status: RunStatus) => boolean;
+export type ExecutionLimits = {
+    readonly maxSteps: number;
+    readonly maxToolCalls: number;
+    readonly wallClockTimeoutMs: number;
+    readonly maxInputTokens: number;
+    readonly maxOutputTokens: number;
+    readonly costCeilingMinorUnits: number;
+    readonly maxRetries: number;
+    readonly retryBackoffMs: number;
+    /** Beyond this, a tool result is spilled to blob storage and referenced. */
+    readonly maxInlineToolOutputBytes: number;
+    /**
+     * Sampling temperature, when the agent wants to pin it (#160).
+     *
+     * Optional, because "leave the provider's default alone" is a real and common choice, and a required field
+     * would force every agent to invent a number. `0` is meaningful and distinct from absent — a graded run needs
+     * to be able to ask for it, which is what the evaluation harness's reproducibility argument rests on.
+     */
+    readonly temperature?: number;
+};
+/**
+ * The conversation a run belongs to, or a refusal — #198 AC-3.
+ *
+ * The whole point of making `conversationId` optional is that a run without one no longer invents one. That
+ * creates a second hazard immediately: a caller reaching for conversation-scoped data — history, compaction,
+ * thread summaries — and receiving *nothing* rather than an error.
+ *
+ * Silently empty is the worse failure. An automation whose history came back empty would look like a fresh
+ * conversation, the model would be prompted as if nothing had happened, and the run would produce a confident
+ * answer built on an absence nobody reported. That is the same class of defect as a scan reporting zero
+ * references for a directory it could not read.
+ *
+ * So this throws, naming the capability the caller asked for. Reaching for history on a run that has no
+ * conversation is a programming error, and the message says which one.
+ */
+export declare const conversationScoped: (run: Run, capability: string) => ConversationId;
+export type Run = {
+    readonly id: RunId;
+    readonly tenantId: TenantId;
+    /** Absent for a run that belongs to no conversation — see `NewRun.conversationId` (#198). */
+    readonly conversationId?: ConversationId;
+    readonly agentId: AgentId;
+    readonly agentVersion: number;
+    /** What this run was asked to do, for a run with no conversation to read — see `NewRun.input` (#202). */
+    readonly input?: unknown;
+    /** Per-run ceilings from admission, overriding the manifest's — see `NewRun.limits` (#202). */
+    readonly limits?: {
+        readonly maxSteps?: number;
+        readonly costCeilingMinorUnits?: number;
+        readonly wallClockTimeoutMs?: number;
+    };
+    readonly status: RunStatus;
+    readonly createdAt: string;
+    readonly startedAt?: string;
+    readonly finishedAt?: string;
+    readonly error?: PlatformError;
+    /** Identifies the worker holding the claim; used to reap stale streams. */
+    readonly claimedBy?: string;
+    readonly keepaliveAt?: string;
+    /** When the current claim's lease expires. A past value marks the run reclaimable. */
+    readonly leaseExpiresAt?: string;
+    /** Set when a cancel was requested; the owning worker observes it and stops. Durable so a
+     * cancel issued to one process is honored by whichever worker holds the run. */
+    readonly cancelRequestedAt?: string;
+    /**
+     * The caller this run was admitted for — #164.
+     *
+     * Absent for runs created before this was recorded, and for a caller that did not supply it. That absence is
+     * deliberately visible rather than defaulted: `buildContext` substituting an identity is the bug this exists
+     * to end, and a default here would move the substitution one layer down where it is harder to see.
+     */
+    readonly principalId?: PrincipalId;
+    readonly roleIds?: readonly string[];
+};
+/** Durable job enqueue. Adapters: BullMQ, in-memory for tests. */
+export interface JobDispatcher {
+    /**
+     * `traceparent` and `enqueuedAt` are the trace hop (#143).
+     *
+     * On the port rather than smuggled through a side channel on the adapter, because the alternative was an
+     * instrumented wrapper remembering the last span it opened — which is wrong the moment two enqueues overlap,
+     * and overlapping enqueues are the normal case. Optional so every existing caller is unaffected and a job
+     * already sitting on the queue still runs; a job with no traceparent starts its own trace, which loses a link
+     * rather than a run.
+     */
+    enqueueRun(input: {
+        tenantId: TenantId;
+        runId: RunId;
+        readonly traceparent?: string;
+        readonly enqueuedAt?: string;
+    }): Promise<void>;
+}
+/** Atomic claim so two workers never process one run. Adapters: Redis, Postgres. */
+export interface DistributedLockStore {
+    acquire(key: string, ttlMs: number): Promise<{
+        released: () => Promise<void>;
+    } | null>;
+}
+export * from "./retry.js";
+export * from "./checkpoint.js";
+export * from "./worker.js";
+export * from "./streaming.js";
+export * from "./serialization.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.js

@@ -0,0 +1,69 @@
+/**
+ * Run lifecycle and execution limits — `docs/04-durable-runtime-and-hitl.md`.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+export const RUN_STATUSES = [
+    "queued",
+    "running",
+    "waiting-for-question",
+    "waiting-for-approval",
+    "retry-pending",
+    "completed",
+    "failed",
+    "cancelled",
+];
+/**
+ * The state machine from the specification. A transition absent from this map is a
+ * bug, not an undefined behaviour — the worker rejects it rather than guessing.
+ */
+export const RUN_TRANSITIONS = {
+    queued: ["running", "cancelled"],
+    running: [
+        "waiting-for-question",
+        "waiting-for-approval",
+        "retry-pending",
+        "completed",
+        "failed",
+        "cancelled",
+    ],
+    "waiting-for-question": ["queued", "cancelled"],
+    "waiting-for-approval": ["queued", "cancelled"],
+    "retry-pending": ["queued", "cancelled"],
+    completed: [],
+    failed: [],
+    cancelled: [],
+};
+export const canTransition = (from, to) => RUN_TRANSITIONS[from].includes(to);
+export const isTerminal = (status) => RUN_TRANSITIONS[status].length === 0;
+/**
+ * The conversation a run belongs to, or a refusal — #198 AC-3.
+ *
+ * The whole point of making `conversationId` optional is that a run without one no longer invents one. That
+ * creates a second hazard immediately: a caller reaching for conversation-scoped data — history, compaction,
+ * thread summaries — and receiving *nothing* rather than an error.
+ *
+ * Silently empty is the worse failure. An automation whose history came back empty would look like a fresh
+ * conversation, the model would be prompted as if nothing had happened, and the run would produce a confident
+ * answer built on an absence nobody reported. That is the same class of defect as a scan reporting zero
+ * references for a directory it could not read.
+ *
+ * So this throws, naming the capability the caller asked for. Reaching for history on a run that has no
+ * conversation is a programming error, and the message says which one.
+ */
+export const conversationScoped = (run, capability) => {
+    if (run.conversationId !== undefined)
+        return run.conversationId;
+    throw new AgentPlatformError({
+        code: "invalid_input",
+        message: `${capability} needs a conversation, and run ${run.id} belongs to none. This is a run admitted without ` +
+            `a conversation — a triggered automation rather than a chat turn — so conversation-scoped capabilities ` +
+            `are unavailable to it. Either give the run a conversation, or turn ${capability} off for this runtime.`,
+        retryable: false,
+    });
+};
+export * from "./retry.js";
+export * from "./checkpoint.js";
+export * from "./worker.js";
+export * from "./streaming.js";
+export * from "./serialization.js";
+//# sourceMappingURL=index.js.map

package/dist/runtime/retry.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Claude/Anthropic-SDK-style retry policy — `docs/04-durable-runtime-and-hitl.md` → Retry policy.
+ *
+ * A single provider call is retried on transient failures with exponential backoff plus jitter,
+ * honoring any server-supplied `retry-after`, and only for the transient HTTP classes the spec
+ * enumerates (408/409/429/5xx/529). Deterministic 4xx validation errors fail fast.
+ *
+ * This layer retries *provider calls*, which are side-effect-free to repeat. External/destructive
+ * tool writes are made safe to retry separately, via idempotency keys (see `../idempotency`), so
+ * nothing here fires a side effect twice.
+ */
+import { type PlatformError } from "../core/errors.js";
+export type RetryPolicy = {
+    /** Total attempts including the first. `maxAttempts: 1` disables retrying. */
+    readonly maxAttempts: number;
+    /** Backoff for the first retry, before jitter. */
+    readonly baseDelayMs: number;
+    /** Upper bound on the computed (pre-`retry-after`) backoff. */
+    readonly maxDelayMs: number;
+    /** Geometric growth per attempt. */
+    readonly backoffFactor: number;
+    /** Fraction of the backoff shaved off by jitter, in `[0, 1]`. 0.25 mirrors the Anthropic SDK. */
+    readonly jitter: number;
+    /** A server `retry-after` is honored up to this ceiling, so a hostile value cannot stall a run. */
+    readonly retryAfterCapMs: number;
+};
+/** Mirrors the Anthropic TS SDK defaults: 0.5s base, 8s cap, x2, -25% jitter. */
+export declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+/**
+ * The transient HTTP status classes, matching the spec and the Anthropic SDK's `shouldRetry`:
+ * `408` request timeout, `409` conflict, `429` rate limited, any `5xx`, and `529` overloaded.
+ */
+export declare const isRetryableStatus: (status: number) => boolean;
+/** Map a raw provider HTTP status to the platform error code the runtime reasons about. */
+export declare const statusToErrorCode: (status: number) => PlatformError["code"];
+/**
+ * Parse a `Retry-After` / `retry-after-ms` header into milliseconds. Accepts a delta-seconds
+ * integer, a millisecond value, or an HTTP-date (resolved against `now`). Returns `undefined`
+ * when absent or unparseable so the caller falls back to computed backoff.
+ */
+export declare const parseRetryAfterMs: (headers: {
+    retryAfter?: string | number | null;
+    retryAfterMs?: string | number | null;
+}, now: number) => number | undefined;
+export type RetryDecision = {
+    readonly retry: true;
+    readonly attempt: number;
+    readonly maxAttempts: number;
+    readonly delayMs: number;
+} | {
+    readonly retry: false;
+    readonly reason: "non-retryable" | "exhausted";
+};
+/**
+ * Compute the pre-jitter backoff for the retry that follows `attempt` (1-based). Exposed for tests
+ * and so a transport can preview the schedule.
+ */
+export declare const backoffMs: (policy: RetryPolicy, attempt: number) => number;
+/**
+ * Decide whether the failed `attempt` should be retried and, if so, how long to wait. `random`
+ * defaults to `Math.random`; inject a fixed value for deterministic tests. When the error carries
+ * `retryAfterMs`, the wait is at least that long (capped by `retryAfterCapMs`) — honoring the
+ * server without letting it stall the run indefinitely.
+ */
+export declare const decideRetry: (input: {
+    readonly error: PlatformError;
+    readonly attempt: number;
+    readonly policy: RetryPolicy;
+    readonly random?: () => number;
+}) => RetryDecision;
+/** Normalize a thrown value to a `PlatformError`. Unclassified throws fail fast (non-retryable). */
+export declare const toPlatformError: (value: unknown) => PlatformError;
+export type RetryPendingInfo = {
+    readonly attempt: number;
+    readonly maxAttempts: number;
+    readonly delayMs: number;
+    readonly nextAttemptAt: string;
+    readonly error: PlatformError;
+};
+/**
+ * Run `operation` with the retry policy. `operation` receives the 1-based attempt number and MUST
+ * be safe to repeat (provider call, or an idempotent tool). Between attempts `onRetryPending` fires
+ * so the worker can persist a `retry-pending` status and publish a `run.retry-pending` event, then
+ * `sleep` waits out the backoff. Exhausting the budget rethrows the last error unchanged.
+ */
+export declare const runWithRetry: <T>(input: {
+    readonly operation: (attempt: number) => Promise<T>;
+    readonly sleep: (ms: number) => Promise<void>;
+    readonly now: () => number;
+    readonly policy?: RetryPolicy;
+    readonly random?: () => number;
+    readonly startAttempt?: number;
+    readonly onRetryPending?: (info: RetryPendingInfo) => void | Promise<void>;
+}) => Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/runtime/retry.js

@@ -0,0 +1,126 @@
+/**
+ * Claude/Anthropic-SDK-style retry policy — `docs/04-durable-runtime-and-hitl.md` → Retry policy.
+ *
+ * A single provider call is retried on transient failures with exponential backoff plus jitter,
+ * honoring any server-supplied `retry-after`, and only for the transient HTTP classes the spec
+ * enumerates (408/409/429/5xx/529). Deterministic 4xx validation errors fail fast.
+ *
+ * This layer retries *provider calls*, which are side-effect-free to repeat. External/destructive
+ * tool writes are made safe to retry separately, via idempotency keys (see `../idempotency`), so
+ * nothing here fires a side effect twice.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+/** Mirrors the Anthropic TS SDK defaults: 0.5s base, 8s cap, x2, -25% jitter. */
+export const DEFAULT_RETRY_POLICY = {
+    maxAttempts: 5,
+    baseDelayMs: 500,
+    maxDelayMs: 8_000,
+    backoffFactor: 2,
+    jitter: 0.25,
+    retryAfterCapMs: 60_000,
+};
+/**
+ * The transient HTTP status classes, matching the spec and the Anthropic SDK's `shouldRetry`:
+ * `408` request timeout, `409` conflict, `429` rate limited, any `5xx`, and `529` overloaded.
+ */
+export const isRetryableStatus = (status) => status === 408 || status === 409 || status === 429 || status >= 500;
+/** Map a raw provider HTTP status to the platform error code the runtime reasons about. */
+export const statusToErrorCode = (status) => {
+    if (status === 408)
+        return "timeout";
+    if (status === 429)
+        return "rate_limited";
+    if (status === 529 || status === 503)
+        return "provider_unavailable";
+    if (status >= 500)
+        return "provider_error";
+    if (status === 409)
+        return "conflict";
+    return "provider_error";
+};
+/**
+ * Parse a `Retry-After` / `retry-after-ms` header into milliseconds. Accepts a delta-seconds
+ * integer, a millisecond value, or an HTTP-date (resolved against `now`). Returns `undefined`
+ * when absent or unparseable so the caller falls back to computed backoff.
+ */
+export const parseRetryAfterMs = (headers, now) => {
+    const ms = headers.retryAfterMs;
+    if (ms !== undefined && ms !== null && ms !== "") {
+        const n = typeof ms === "number" ? ms : Number(ms);
+        if (Number.isFinite(n) && n >= 0)
+            return n;
+    }
+    const ra = headers.retryAfter;
+    if (ra === undefined || ra === null || ra === "")
+        return undefined;
+    const n = typeof ra === "number" ? ra : Number(ra);
+    if (Number.isFinite(n) && n >= 0)
+        return n * 1000;
+    const dateMs = Date.parse(String(ra));
+    if (Number.isFinite(dateMs))
+        return Math.max(0, dateMs - now);
+    return undefined;
+};
+/**
+ * Compute the pre-jitter backoff for the retry that follows `attempt` (1-based). Exposed for tests
+ * and so a transport can preview the schedule.
+ */
+export const backoffMs = (policy, attempt) => Math.min(policy.baseDelayMs * policy.backoffFactor ** (attempt - 1), policy.maxDelayMs);
+/**
+ * Decide whether the failed `attempt` should be retried and, if so, how long to wait. `random`
+ * defaults to `Math.random`; inject a fixed value for deterministic tests. When the error carries
+ * `retryAfterMs`, the wait is at least that long (capped by `retryAfterCapMs`) — honoring the
+ * server without letting it stall the run indefinitely.
+ */
+export const decideRetry = (input) => {
+    const { error, attempt, policy } = input;
+    if (!error.retryable)
+        return { retry: false, reason: "non-retryable" };
+    if (attempt >= policy.maxAttempts)
+        return { retry: false, reason: "exhausted" };
+    const random = input.random ?? Math.random;
+    const jittered = backoffMs(policy, attempt) * (1 - random() * policy.jitter);
+    const honored = error.retryAfterMs !== undefined
+        ? Math.max(jittered, Math.min(error.retryAfterMs, policy.retryAfterCapMs))
+        : jittered;
+    return { retry: true, attempt, maxAttempts: policy.maxAttempts, delayMs: Math.round(honored) };
+};
+/** Normalize a thrown value to a `PlatformError`. Unclassified throws fail fast (non-retryable). */
+export const toPlatformError = (value) => {
+    if (value instanceof AgentPlatformError)
+        return value.toPlatformError();
+    const message = value instanceof Error ? value.message : String(value);
+    return { code: "internal", message, retryable: false };
+};
+/**
+ * Run `operation` with the retry policy. `operation` receives the 1-based attempt number and MUST
+ * be safe to repeat (provider call, or an idempotent tool). Between attempts `onRetryPending` fires
+ * so the worker can persist a `retry-pending` status and publish a `run.retry-pending` event, then
+ * `sleep` waits out the backoff. Exhausting the budget rethrows the last error unchanged.
+ */
+export const runWithRetry = async (input) => {
+    const policy = input.policy ?? DEFAULT_RETRY_POLICY;
+    let attempt = input.startAttempt ?? 1;
+    for (;;) {
+        try {
+            return await input.operation(attempt);
+        }
+        catch (thrown) {
+            const error = toPlatformError(thrown);
+            const decision = decideRetry({ error, attempt, policy, random: input.random });
+            if (!decision.retry)
+                throw new AgentPlatformError(error, { cause: thrown });
+            const nextAttemptAt = new Date(input.now() + decision.delayMs).toISOString();
+            await input.onRetryPending?.({
+                attempt,
+                maxAttempts: policy.maxAttempts,
+                delayMs: decision.delayMs,
+                nextAttemptAt,
+                error,
+            });
+            await input.sleep(decision.delayMs);
+            attempt += 1;
+        }
+    }
+};
+//# sourceMappingURL=retry.js.map

package/dist/runtime/serialization.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Per-conversation run serialization + turn commit — `docs/13-sessions-and-threads.md`.
+ *
+ * Runs within one conversation are serialized: at most one is `Running`, the rest queue FIFO, so
+ * session-state and message order stay deterministic. A turn reads session state at claim time and
+ * commits its state write in the same unit of work that finalizes the run, so state and messages
+ * never diverge. The agent binding makes resumption deterministic — a resumed thread runs the same
+ * agent, and the same version when pinned.
+ */
+import type { ConversationId, RunId, TenantId } from "../core/ids.js";
+import type { ConversationBinding, ConversationRunCoordinator, UnitOfWork } from "../persistence/index.js";
+import type { JobDispatcher } from "./index.js";
+import type { RunEventLog } from "../core/events.js";
+/**
+ * Start `runId` now if the conversation is free, else enqueue it FIFO. Returns whether it started.
+ * The claim-or-enqueue is atomic, so two runs racing to start the same conversation cannot both win,
+ * and a run can never slip into an idle-but-unclaimed slot and strand itself.
+ */
+export declare const startOrEnqueueRun: (coordinator: ConversationRunCoordinator, input: {
+    tenantId: TenantId;
+    /**
+     * Absent for a run that belongs to no conversation — #198.
+     *
+     * Then **no slot is claimed at all**, and the run is admitted directly. The SPEC first proposed a
+     * *tenant-level* slot for these; that was wrong and is corrected here. A tenant-level slot would serialise
+     * every automation a tenant owns — two unrelated webhooks would queue behind each other for no reason —
+     * and the reason there is a conversation slot in the first place is that turns in one conversation have an
+     * order a person can see. An automation has no such ordering requirement.
+     *
+     * Concurrency for these runs is bounded where it should be: the worker's own limits, and quotas.
+     */
+    conversationId?: ConversationId;
+    runId: RunId;
+    /**
+     * The durable log, so admission is *observable* — #170.
+     *
+     * `run.queued` was in `RUN_EVENT_TYPES`, mapped to a telemetry span, and mapped by the frontend reducer to
+     * the status `queued` — and **nothing emitted it**. So a client subscribing to a run saw nothing at all
+     * between sending a message and a worker picking it up: the one moment where "queued" is the only true
+     * thing to say, and the state the reducer had a case for could never be reached.
+     *
+     * Emitted here rather than by each caller because admission is the event. Two hosts emitting their own
+     * would be two answers to "when was this queued", and the one that forgot would look like a hang.
+     *
+     * Optional: a caller with no log still admits runs. Sequence 1 by definition — admission is the first thing
+     * that happens to a run, and the worker reconciles from the log before emitting, so its own first event
+     * continues from here rather than colliding.
+     */
+    eventLog?: RunEventLog;
+    now?: () => string;
+}) => Promise<"started" | "queued">;
+/**
+ * On a run reaching a terminal state, atomically release the conversation and promote the next queued
+ * run, then hand it to the dispatcher. Returns the promoted run, or null when the backlog is empty.
+ * Because release+promote is atomic, two runs can never both become active. This is the per-thread
+ * mailbox drain that guarantees FIFO execution.
+ */
+export declare const advanceConversation: (coordinator: ConversationRunCoordinator, dispatcher: JobDispatcher, input: {
+    tenantId: TenantId;
+    conversationId: ConversationId;
+    runId: RunId;
+}) => Promise<RunId | null>;
+/**
+ * The agent version a resumed thread must run. `pinned` keeps the recorded version even when a newer
+ * one exists (deterministic continuation); `latest` tracks the newest. Throws if a pinned binding is
+ * missing its version — a data error, not a silent fallback.
+ */
+export declare const resolveAgentVersionForResume: (binding: ConversationBinding, latestVersion: number) => number;
+/** One write in a turn commit: `do` performs it, `undo` compensates it if a later step fails. */
+export type CommitStep<T> = {
+    readonly do: () => Promise<T>;
+    readonly undo?: (result: T) => void | Promise<void>;
+};
+/**
+ * Commit a turn's writes together. Every step runs inside the unit of work; if any step throws, the
+ * already-applied steps are compensated in reverse — so session state and messages commit
+ * all-or-nothing. The Postgres `UnitOfWork` makes this a real transaction; the memory one compensates
+ * explicitly. Pass a `UnitOfWork` exposing `runTx` (the memory/Postgres adapters do) to get rollback.
+ */
+export declare const commitTurn: (uow: UnitOfWork & {
+    runTx<T>(fn: (tx: {
+        onRollback(c: () => void | Promise<void>): void;
+    }) => Promise<T>): Promise<T>;
+}, steps: ReadonlyArray<CommitStep<unknown>>) => Promise<void>;
+//# sourceMappingURL=serialization.d.ts.map

package/dist/runtime/serialization.js

@@ -0,0 +1,95 @@
+/**
+ * Per-conversation run serialization + turn commit — `docs/13-sessions-and-threads.md`.
+ *
+ * Runs within one conversation are serialized: at most one is `Running`, the rest queue FIFO, so
+ * session-state and message order stay deterministic. A turn reads session state at claim time and
+ * commits its state write in the same unit of work that finalizes the run, so state and messages
+ * never diverge. The agent binding makes resumption deterministic — a resumed thread runs the same
+ * agent, and the same version when pinned.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+/**
+ * Start `runId` now if the conversation is free, else enqueue it FIFO. Returns whether it started.
+ * The claim-or-enqueue is atomic, so two runs racing to start the same conversation cannot both win,
+ * and a run can never slip into an idle-but-unclaimed slot and strand itself.
+ */
+export const startOrEnqueueRun = async (coordinator, input) => {
+    /**
+     * A conversation-less run skips the coordinator entirely, and is `started` by definition — there is nothing
+     * for it to be queued *behind*. Calling `claimOrEnqueue` with no conversation would mean inventing a slot key,
+     * which is the fabricated-identity failure this whole change exists to remove.
+     */
+    const status = input.conversationId === undefined
+        ? "started"
+        : (await coordinator.claimOrEnqueue({ ...input, conversationId: input.conversationId })).status;
+    if (input.eventLog !== undefined) {
+        /**
+         * Best-effort, and deliberately so.
+         *
+         * The run is already admitted by the time this runs; failing the request now would report an error for work
+         * that is going to happen anyway, and the caller would retry an admission that cannot be repeated. A missing
+         * `run.queued` costs a client one status label. Losing the run costs the answer.
+         */
+        try {
+            await input.eventLog.append({
+                tenantId: input.tenantId,
+                event: {
+                    type: "run.queued",
+                    runId: input.runId,
+                    sequence: 1,
+                    occurredAt: (input.now ?? (() => new Date().toISOString()))(),
+                },
+            });
+        }
+        catch {
+            // A duplicate sequence means this run was already admitted and logged — a retried request, which is not
+            // an error. Any other failure is a lost status label, which is not worth failing admission over.
+        }
+    }
+    return status;
+};
+/**
+ * On a run reaching a terminal state, atomically release the conversation and promote the next queued
+ * run, then hand it to the dispatcher. Returns the promoted run, or null when the backlog is empty.
+ * Because release+promote is atomic, two runs can never both become active. This is the per-thread
+ * mailbox drain that guarantees FIFO execution.
+ */
+export const advanceConversation = async (coordinator, dispatcher, input) => {
+    const next = await coordinator.releaseAndPromote(input);
+    if (next === null)
+        return null;
+    await dispatcher.enqueueRun({ tenantId: input.tenantId, runId: next });
+    return next;
+};
+/**
+ * The agent version a resumed thread must run. `pinned` keeps the recorded version even when a newer
+ * one exists (deterministic continuation); `latest` tracks the newest. Throws if a pinned binding is
+ * missing its version — a data error, not a silent fallback.
+ */
+export const resolveAgentVersionForResume = (binding, latestVersion) => {
+    if (binding.agentVersionPolicy === "latest")
+        return latestVersion;
+    if (binding.agentVersion === undefined)
+        throw new AgentPlatformError({
+            code: "invalid_input",
+            message: `Pinned conversation binding for ${binding.conversationId} has no agentVersion`,
+            retryable: false,
+        });
+    return binding.agentVersion;
+};
+/**
+ * Commit a turn's writes together. Every step runs inside the unit of work; if any step throws, the
+ * already-applied steps are compensated in reverse — so session state and messages commit
+ * all-or-nothing. The Postgres `UnitOfWork` makes this a real transaction; the memory one compensates
+ * explicitly. Pass a `UnitOfWork` exposing `runTx` (the memory/Postgres adapters do) to get rollback.
+ */
+export const commitTurn = async (uow, steps) => {
+    await uow.runTx(async (tx) => {
+        for (const step of steps) {
+            const result = await step.do();
+            if (step.undo)
+                tx.onRollback(() => step.undo(result));
+        }
+    });
+};
+//# sourceMappingURL=serialization.js.map

package/dist/runtime/streaming.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Transport-neutral streaming — `docs/04-durable-runtime-and-hitl.md` → Transport events.
+ *
+ * The reconnect layer that sits under every transport (GraphQL subscription, SSE, …): a client
+ * reconnects, reads everything after its cursor from the durable `RunEventLog`, then follows the
+ * live feed — with catch-up and live de-duplicated by `sequence` so no part is missed or repeated.
+ * Nothing here knows about a wire format, which is what keeps the layer transport-agnostic.
+ */
+import { type RealtimePublisher, type RunEvent, type RunEventLog, type RunEventType, type RunStreamState } from "../core/events.js";
+import type { RunId, TenantId } from "../core/ids.js";
+export declare const isTerminalEventType: (type: RunEventType) => boolean;
+/** Live fan-in half of reconnect. `subscribe` must begin buffering at call time so the catch-up
+ * read cannot race ahead of live events. Adapters: the in-memory bus below, Supabase Realtime, Redis. */
+export interface LiveEventSource {
+    subscribe(channel: string): AsyncIterable<RunEvent>;
+}
+/**
+ * The persisted snapshot a transport sends on connect: the projected state plus the cursor to
+ * resume streaming from. Built purely from the durable log, so it never disagrees with live deltas.
+ */
+export declare const reconnectSnapshot: (input: {
+    readonly tenantId: TenantId;
+    readonly runId: RunId;
+    readonly log: RunEventLog;
+}) => Promise<{
+    readonly state: RunStreamState;
+    readonly after: number;
+}>;
+/**
+ * Ordered, gap-free, duplicate-free event stream from `after`. Subscribes first (so no live event
+ * is lost during catch-up), replays the durable log, then follows live — skipping anything whose
+ * sequence was already delivered. Ends on the run's terminal event or when `signal` aborts.
+ */
+export declare function openRunEventStream(input: {
+    readonly tenantId: TenantId;
+    readonly runId: RunId;
+    readonly channel: string;
+    readonly after: number;
+    readonly log: RunEventLog;
+    readonly live: LiveEventSource;
+    readonly signal?: {
+        readonly aborted: boolean;
+    };
+}): AsyncIterable<RunEvent>;
+/**
+ * In-memory event bus: a `RealtimePublisher` paired with a `LiveEventSource`. Each subscriber gets
+ * its own queue that starts filling the moment it subscribes, so `openRunEventStream` never races.
+ * Serves tests, single-process deployments and the SSE embedded profile (#37).
+ */
+export declare const createMemoryEventBus: () => {
+    publisher: RealtimePublisher;
+    live: LiveEventSource;
+};
+//# sourceMappingURL=streaming.d.ts.map