@nylorun/runtime 0.13.0-beta → 0.15.0-beta

package/dist/execution/types.d.ts

@@ -27,21 +27,31 @@
  *   becomes `uncertain` is settled in the Session Store and `advance` returns
  *   `done`.
  * - **Sweeps.** `armSweep` arms one self-re-arming sweep per Tenant; arming an
- *   armed Tenant is a no-op. The sweep expires claims, re-wakes orphaned
- *   `runnable` sessions and relays outbox rows left behind.
+ *   armed Tenant is a no-op. The sweep settles lapsed deliveries and re-wakes
+ *   orphaned `runnable` sessions.
+ * - **One delivery per Action at a time.** `deliver` runs
+ *   `WorkerHandlers.deliver` for the key `<tenantId>:<actionId>` at least once
+ *   after it resolves. Two deliveries for one key never overlap; repeated
+ *   `deliver` calls may each run it, so the handler reads the Action's state
+ *   and does nothing when there is nothing to deliver.
+ * - **Retry after `retry`.** A delivery that returns `retry` is run again for
+ *   the same key after `retryAfterMs`. This is how an Action endpoint that is
+ *   down or busy is retried; the handler throws only on infrastructure errors.
  */
 /** Why a session is woken (§12.3, "Where wakes come from"). */
 export type WakeReason = 
 /** Session commands. */
 "message" | "approve" | "respond"
-/** An executor posted an Action result. */
+/** An Action's outcome was recorded (a delivery's answer or a background result). */
  | "action_result"
 /** A linked agent turn completed, failed or was cancelled. */
  | "linked"
 /** Queued flow effects, pending agent effects reconciled. */
  | "flow"
 /** The Tenant sweep and `busy` re-wakes. */
- | "recover";
+ | "recover"
+/** A long turn ended a segment at a step boundary and continues in the next (Model Calls §10). */
+ | "rollover";
 export declare const WAKE_REASONS: readonly WakeReason[];
 export interface Wake {
     reason: WakeReason;
@@ -59,6 +69,14 @@ export type AdvanceResult = {
     status: "busy";
     retryAfterMs: number;
 };
+export type DeliverResult = {
+    status: "done";
+}
+/** The Action is still to be delivered; run again for this key after `retryAfterMs`. */
+ | {
+    status: "retry";
+    retryAfterMs: number;
+};
 /** What a Worker runs when Durable Session Execution calls it. */
 export interface WorkerHandlers {
     /**
@@ -71,6 +89,11 @@ export interface WorkerHandlers {
     sweep(tenantId: string): Promise<void>;
     /** A durable timer set with `timer` fired. Required when `timer` is used. */
     fire?(tenantId: string, key: string): Promise<void>;
+    /**
+     * Delivers one Action to its Action endpoint. `signal` aborts when the Worker
+     * stops. Throw only on infrastructure errors. Required when `deliver` is used.
+     */
+    deliver?(tenantId: string, actionId: string, signal: AbortSignal): Promise<DeliverResult>;
 }
 export interface DurableExecution {
     /** At-least-once. `dedupeKey` merges repeated wakes for the same cause. */
@@ -81,6 +104,12 @@ export interface DurableExecution {
      * implementation can; `fire` must be idempotent either way.
      */
     timer(tenantId: string, key: string, at: Date): Promise<void>;
+    /**
+     * At-least-once: `WorkerHandlers.deliver(tenantId, actionId)` runs after this
+     * resolves, never overlapping another delivery of the same Action. Send it
+     * after the transaction that made the Action pending commits.
+     */
+    deliver(tenantId: string, actionId: string): Promise<void>;
     /** Arms the Tenant's self-re-arming sweep. Idempotent. */
     armSweep(tenantId: string): Promise<void>;
     /** Stops re-arming the Tenant's sweep (Tenant deleted). A pass already running finishes. */
@@ -109,14 +138,17 @@ export interface StuckInvocation {
     /** Service name without any prefix, e.g. `NylorunSession`. */
     service: string;
     handler: string;
-    /** Object key: `<tenantId>:<sessionId>`, `<tenantId>` or `<tenantId>:<timer key>`. */
+    /**
+     * Object key: `<tenantId>:<sessionId>`, `<tenantId>`, `<tenantId>:<timer key>` or
+     * `<tenantId>:<actionId>`.
+     */
     key: string;
     tenantId?: string;
     retryCount: number;
     lastFailure?: string;
     modifiedAt?: string;
 }
-/** The key one advance at a time is serialized on. */
+/** The key one advance (or one delivery, with an Action id) at a time is serialized on. */
 export declare function sessionKey(tenantId: string, sessionId: string): string;
 /** Splits a key made by `sessionKey`. Tenant ids never contain `:`. */
 export declare function parseSessionKey(key: string): {

package/dist/execution/types.js

@@ -27,8 +27,16 @@
  *   becomes `uncertain` is settled in the Session Store and `advance` returns
  *   `done`.
  * - **Sweeps.** `armSweep` arms one self-re-arming sweep per Tenant; arming an
- *   armed Tenant is a no-op. The sweep expires claims, re-wakes orphaned
- *   `runnable` sessions and relays outbox rows left behind.
+ *   armed Tenant is a no-op. The sweep settles lapsed deliveries and re-wakes
+ *   orphaned `runnable` sessions.
+ * - **One delivery per Action at a time.** `deliver` runs
+ *   `WorkerHandlers.deliver` for the key `<tenantId>:<actionId>` at least once
+ *   after it resolves. Two deliveries for one key never overlap; repeated
+ *   `deliver` calls may each run it, so the handler reads the Action's state
+ *   and does nothing when there is nothing to deliver.
+ * - **Retry after `retry`.** A delivery that returns `retry` is run again for
+ *   the same key after `retryAfterMs`. This is how an Action endpoint that is
+ *   down or busy is retried; the handler throws only on infrastructure errors.
  */
 export const WAKE_REASONS = [
     "message",
@@ -38,8 +46,9 @@ export const WAKE_REASONS = [
     "linked",
     "flow",
     "recover",
+    "rollover",
 ];
-/** The key one advance at a time is serialized on. */
+/** The key one advance (or one delivery, with an Action id) at a time is serialized on. */
 export function sessionKey(tenantId, sessionId) {
     return `${tenantId}:${sessionId}`;
 }

package/dist/gates/contract.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The gates service's wire format (blueprint §15, P1.1). Internal: only the loop calls it, so
+ * it is not in the published OpenAPI documents.
+ *
+ * `POST /nylorun/v1/model-calls`
+ * - Headers: `Authorization: Bearer <NYLORUN_GATES_TOKEN>`, `Idempotency-Key: <effect id>`,
+ *   and optionally `Nylorun-Tenant: <tenant id>`, which must then be the database's one
+ *   Tenant (a call naming another is refused).
+ * - Body: `ModelCallBody`, at most `MAX_MODEL_CALL_BYTES`.
+ * - `200 {outcome}` once the call has finished, whether the outcome is a candidate or a
+ *   failure; nothing is sent while it runs. `401 gate_unauthorized` for a missing or wrong
+ *   token, `400 invalid_request` for a malformed Tenant header or a bad body, `409
+ *   gate_conflict` when a different request already runs under the same key.
+ * - With an `Idempotency-Key` the call outlives its client (P1.2): a re-send with the same key
+ *   and body joins it, or gets its outcome for 30 minutes. Without one, a client that goes
+ *   away aborts the call.
+ *
+ * `POST /nylorun/v1/model-calls/{key}/cancel` (same headers): aborts the keyed call; `204`
+ * whether or not it exists.
+ */
+import { z } from "zod";
+import type { ModelGateOutcome } from "./model-gate.js";
+export declare const MODEL_CALLS_PATH = "/nylorun/v1/model-calls";
+/** Header naming the Tenant a call is for: optional, and checked against the gate's Tenant. */
+export declare const TENANT_HEADER = "nylorun-tenant";
+/** Largest request body the gate reads: one `ModelCall` with its whole projected history. */
+export declare const MAX_MODEL_CALL_BYTES: number;
+export declare const ModelCallBodySchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    turnId: z.ZodString;
+    agentId: z.ZodString;
+    effectId: z.ZodString;
+    invocationId: z.ZodString;
+    call: z.ZodObject<{
+        prompt: z.ZodArray<z.ZodUnknown>;
+        tools: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>;
+}, z.core.$strip>;
+export type ModelCallBody = z.infer<typeof ModelCallBodySchema>;
+export interface ModelCallResponse {
+    readonly outcome: ModelGateOutcome;
+}
+/** An error answer: `{error: {code, message}}`. */
+export interface GateErrorBody {
+    readonly error: {
+        readonly code: "gate_unauthorized" | "invalid_request" | "gate_conflict";
+        readonly message: string;
+    };
+}

package/dist/gates/contract.js

@@ -0,0 +1,37 @@
+/**
+ * The gates service's wire format (blueprint §15, P1.1). Internal: only the loop calls it, so
+ * it is not in the published OpenAPI documents.
+ *
+ * `POST /nylorun/v1/model-calls`
+ * - Headers: `Authorization: Bearer <NYLORUN_GATES_TOKEN>`, `Idempotency-Key: <effect id>`,
+ *   and optionally `Nylorun-Tenant: <tenant id>`, which must then be the database's one
+ *   Tenant (a call naming another is refused).
+ * - Body: `ModelCallBody`, at most `MAX_MODEL_CALL_BYTES`.
+ * - `200 {outcome}` once the call has finished, whether the outcome is a candidate or a
+ *   failure; nothing is sent while it runs. `401 gate_unauthorized` for a missing or wrong
+ *   token, `400 invalid_request` for a malformed Tenant header or a bad body, `409
+ *   gate_conflict` when a different request already runs under the same key.
+ * - With an `Idempotency-Key` the call outlives its client (P1.2): a re-send with the same key
+ *   and body joins it, or gets its outcome for 30 minutes. Without one, a client that goes
+ *   away aborts the call.
+ *
+ * `POST /nylorun/v1/model-calls/{key}/cancel` (same headers): aborts the keyed call; `204`
+ * whether or not it exists.
+ */
+import { z } from "zod";
+export const MODEL_CALLS_PATH = "/nylorun/v1/model-calls";
+/** Header naming the Tenant a call is for: optional, and checked against the gate's Tenant. */
+export const TENANT_HEADER = "nylorun-tenant";
+/** Largest request body the gate reads: one `ModelCall` with its whole projected history. */
+export const MAX_MODEL_CALL_BYTES = 32 * 1024 * 1024;
+export const ModelCallBodySchema = z.object({
+    sessionId: z.string().min(1),
+    turnId: z.string().min(1),
+    agentId: z.string().min(1),
+    effectId: z.string().min(1),
+    invocationId: z.string().min(1),
+    call: z.looseObject({
+        prompt: z.array(z.unknown()),
+        tools: z.array(z.looseObject({ name: z.string() })),
+    }),
+});

package/dist/gates/handler.d.ts

@@ -0,0 +1,21 @@
+import type { Logger } from "../tenant/types.js";
+import type { ModelCallSettings, ModelGate, ModelGateRequest } from "./model-gate.js";
+import { type TenantVaults } from "./tenant-vaults.js";
+export interface ModelCallHandlerOptions {
+    readonly vaults: TenantVaults;
+    readonly logger: Logger;
+    /** Retries and timeouts; `piModel`'s defaults when absent. */
+    readonly settings?: ModelCallSettings;
+}
+/**
+ * A model call as the gate receives it: the Tenant is optional (the loop of a protocol 4
+ * Runtime names it; the gate serves the database's one Tenant either way).
+ */
+export type ModelCallRequest = Omit<ModelGateRequest, "tenantId"> & {
+    readonly tenantId?: string;
+};
+/** What the gate's route calls: a `ModelGate` whose request may leave the Tenant out. */
+export interface ModelCallHandler {
+    call(request: ModelCallRequest, signal: AbortSignal): ReturnType<ModelGate["call"]>;
+}
+export declare function createModelCallHandler(options: ModelCallHandlerOptions): ModelCallHandler;

package/dist/gates/handler.js

@@ -0,0 +1,55 @@
+/**
+ * Serves one model call in the gates service: opens the Tenant's vault (the database's one
+ * Tenant; a call naming another is refused) and calls the model
+ * through `inProcessModelGate`, the same code the loop ran before the gate, so outcomes,
+ * retries, classification and redaction are unchanged. The meter records the call's usage in
+ * the Tenant's ledger. Logs one line per call, never the prompt, the output or a credential.
+ */
+import { classifyThrown } from "../model/classify.js";
+import { inProcessModelGate } from "./in-process.js";
+import { createMeter } from "./meter.js";
+import { GateRefusal } from "./tenant-vaults.js";
+export function createModelCallHandler(options) {
+    const { vaults, logger, settings } = options;
+    const meter = createMeter({ logger });
+    return {
+        async call(named, signal) {
+            const started = Date.now();
+            let request = named;
+            let outcome;
+            try {
+                const vault = await vaults.open(named.tenantId);
+                const call = { ...named, tenantId: vault.tenantId };
+                request = call;
+                const gate = inProcessModelGate({
+                    root: vault.root,
+                    readHostModel: () => vault.readHostModel(),
+                    writeHostCredential: (credential) => vault.writeHostCredential(credential),
+                    ...(settings ? { settings } : {}),
+                });
+                outcome = await meter.call(vault.store, call, () => gate.call(call, signal));
+            }
+            catch (error) {
+                if (signal.aborted) {
+                    logger.info("model_call", { ...fields(request), ms: Date.now() - started, outcome: "aborted" });
+                    throw error;
+                }
+                outcome = error instanceof GateRefusal ? error.outcome : classifyThrown(error);
+            }
+            logger.info("model_call", {
+                ...fields(request),
+                ms: Date.now() - started,
+                outcome: typeof outcome === "object" && outcome !== null && "kind" in outcome
+                    ? outcome.code
+                    : "ok",
+            });
+            return outcome;
+        },
+    };
+}
+const fields = (request) => ({
+    tenant: request.tenantId,
+    session: request.sessionId,
+    effect: request.effectId,
+    ...(request.call.model?.id ? { model: request.call.model.id } : {}),
+});

package/dist/gates/http-client.d.ts

@@ -0,0 +1,12 @@
+import type { ModelGate } from "./model-gate.js";
+/** Above the gate's 600 s provider request timeout. */
+export declare const GATE_CLIENT_TIMEOUT_MS = 630000;
+export interface HttpModelGateOptions {
+    /** The gates service, e.g. `http://gateway:4100` (`NYLORUN_GATES_URL`). */
+    readonly url: string;
+    /** `NYLORUN_GATES_TOKEN`. */
+    readonly token: string;
+    /** How long the connection may stay silent. Default `GATE_CLIENT_TIMEOUT_MS`. */
+    readonly timeoutMs?: number;
+}
+export declare function httpModelGate(options: HttpModelGateOptions): ModelGate;

package/dist/gates/http-client.js

@@ -0,0 +1,160 @@
+/**
+ * The loop's client of the gates service (blueprint §15, P1.1): each vault-backed model call
+ * is one POST to the gate and one JSON answer, `gates/contract.ts`. The loop never sees the
+ * model credential.
+ *
+ * Over `node:http`, not `fetch`: the gate answers only when the call has finished, and
+ * `fetch`'s default 300 s headers timeout would end every longer call. The only timeout here
+ * is the socket's idle time, above the gate's own 600 s provider timeout.
+ *
+ * A failure of the hop is a failure outcome, never a throw: `resolveEffect` marks anything
+ * thrown `uncertain`. Only an abort of the caller's signal throws. The client never retries;
+ * the gate retries the provider.
+ */
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { failure } from "../model/classify.js";
+import { MODEL_CALLS_PATH, TENANT_HEADER, } from "./contract.js";
+/** How long a cancel may take; the call it stops ends with the provider timeout anyway. */
+const CANCEL_TIMEOUT_MS = 2_000;
+/** Above the gate's 600 s provider request timeout. */
+export const GATE_CLIENT_TIMEOUT_MS = 630_000;
+export function httpModelGate(options) {
+    const endpoint = new URL(MODEL_CALLS_PATH, options.url);
+    const send = endpoint.protocol === "https:" ? httpsRequest : httpRequest;
+    const timeoutMs = options.timeoutMs ?? GATE_CLIENT_TIMEOUT_MS;
+    const where = new URL(options.url).origin;
+    return {
+        recovers: true,
+        async cancel(request) {
+            const url = new URL(`${MODEL_CALLS_PATH}/${encodeURIComponent(request.effectId)}/cancel`, options.url);
+            await new Promise((resolve) => {
+                const outgoing = send(url, {
+                    method: "POST",
+                    headers: {
+                        authorization: `Bearer ${options.token}`,
+                        [TENANT_HEADER]: request.tenantId,
+                        "content-length": 0,
+                    },
+                    timeout: CANCEL_TIMEOUT_MS,
+                }, (response) => {
+                    response.resume();
+                    response.on("end", resolve);
+                    response.on("error", () => resolve());
+                });
+                outgoing.on("timeout", () => outgoing.destroy());
+                outgoing.on("error", () => resolve());
+                outgoing.end();
+            });
+        },
+        async call(request, signal) {
+            signal.throwIfAborted();
+            const body = {
+                sessionId: request.sessionId,
+                turnId: request.turnId,
+                agentId: request.agentId,
+                effectId: request.effectId,
+                invocationId: request.invocationId,
+                call: request.call,
+            };
+            const payload = Buffer.from(JSON.stringify(body), "utf8");
+            return new Promise((resolve, reject) => {
+                let settled = false;
+                /** True once the whole request was handed to the socket. */
+                let sent = false;
+                /** True once the gate's answer started; its body settles the call. */
+                let responded = false;
+                let timedOut = false;
+                const settle = (outcome) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    signal.removeEventListener("abort", onAbort);
+                    resolve(outcome);
+                };
+                const onAbort = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    outgoing.destroy();
+                    reject(signal.reason ?? new Error("aborted"));
+                };
+                const lost = (error) => settle(timedOut
+                    ? failure("transient", `Model gate at ${where} sent nothing for ${Math.round(timeoutMs / 1000)} s`, true)
+                    : sent
+                        ? failure("transient", `Model gate connection lost mid-call${error ? ` (${error.message})` : ""}; the provider may have billed the call`, true)
+                        : failure("transient", `Model gate unreachable at ${where}${error ? ` (${error.message})` : ""}`, true));
+                const outgoing = send(endpoint, {
+                    method: "POST",
+                    headers: {
+                        authorization: `Bearer ${options.token}`,
+                        "content-type": "application/json",
+                        "content-length": payload.byteLength,
+                        [TENANT_HEADER]: request.tenantId,
+                        "idempotency-key": request.effectId,
+                    },
+                    timeout: timeoutMs,
+                }, (response) => {
+                    responded = true;
+                    readBody(response).then((text) => settle(answer(response.statusCode ?? 0, text)), (error) => lost(error));
+                });
+                outgoing.on("socket", (socket) => socket.setKeepAlive(true, 30_000));
+                outgoing.on("finish", () => {
+                    sent = true;
+                });
+                outgoing.on("timeout", () => {
+                    timedOut = true;
+                    outgoing.destroy();
+                });
+                outgoing.on("error", (error) => {
+                    if (signal.aborted)
+                        return;
+                    lost(error);
+                });
+                outgoing.on("close", () => {
+                    if (!signal.aborted && !responded)
+                        lost();
+                });
+                signal.addEventListener("abort", onAbort, { once: true });
+                outgoing.end(payload);
+            });
+        },
+    };
+}
+function readBody(response) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        response.on("data", (chunk) => chunks.push(chunk));
+        response.on("end", () => {
+            if (response.complete)
+                resolve(Buffer.concat(chunks).toString("utf8"));
+            else
+                reject(new Error("response ended early"));
+        });
+        response.on("error", reject);
+        response.on("aborted", () => reject(new Error("response aborted")));
+    });
+}
+/** The outcome a gate answer stands for. */
+function answer(status, text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (status === 200) {
+        if (typeof parsed === "object" && parsed !== null && "outcome" in parsed)
+            return parsed.outcome;
+        return failure("transient", "Model gate answered without an outcome", false);
+    }
+    const message = parsed?.error?.message;
+    if (status === 401)
+        return failure("auth", "The model gate refused this Runtime's token: the runtime and gateway containers must share NYLORUN_GATES_TOKEN", false);
+    if (status === 409)
+        return failure("invalid_request", `The call's request changed under the same effect id${message ? `: ${message}` : ""}`, false);
+    if (status === 400)
+        return failure("invalid_request", message ?? "The model gate refused the call", false);
+    return failure("transient", `Model gate answered ${status}${message ? `: ${message}` : ""}`, true);
+}

package/dist/gates/in-process.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The Model Gate in the caller's own process: `piModel` with the Tenant's host model. Used
+ * when nothing separates the loop from the credential anyway (the ephemeral Runtime,
+ * embedding, tests), and by the gates service itself to serve each call.
+ */
+import type { Credential } from "@earendil-works/pi-ai";
+import { type ModelCallSettings } from "../model/pi-model.js";
+import type { SessionStore } from "../store/types.js";
+import type { Logger } from "../tenant/types.js";
+import type { HostModelSecret } from "../vault/service.js";
+import type { ModelGate } from "./model-gate.js";
+export interface InProcessModelGateOptions {
+    /** The Tenant's home: `piModel` redacts secrets it finds there from failure messages. */
+    readonly root?: string;
+    readonly readHostModel: () => Promise<HostModelSecret | undefined>;
+    /** Writes back a credential pi-ai refreshed (OAuth). */
+    readonly writeHostCredential: (credential: Credential) => Promise<void>;
+    readonly settings?: ModelCallSettings;
+}
+/**
+ * The in-process gate of an open Tenant: reads its host model from its own vault and records
+ * each call in its usage ledger. Only a Runtime without the gates service (embedding, the
+ * ephemeral Runtime, tests) builds one.
+ */
+export declare function tenantModelGate(options: {
+    readonly store: SessionStore;
+    readonly kek: () => Buffer;
+    readonly root: string;
+    readonly logger: Logger;
+    readonly settings?: ModelCallSettings;
+}): ModelGate;
+export declare function inProcessModelGate(options: InProcessModelGateOptions): ModelGate;

package/dist/gates/in-process.js

@@ -0,0 +1,42 @@
+import { piModel } from "../model/pi-model.js";
+import { HostModelVault } from "../vault/host-model.js";
+import { createMeter } from "./meter.js";
+/**
+ * The in-process gate of an open Tenant: reads its host model from its own vault and records
+ * each call in its usage ledger. Only a Runtime without the gates service (embedding, the
+ * ephemeral Runtime, tests) builds one.
+ */
+export function tenantModelGate(options) {
+    const vault = new HostModelVault({ store: options.store, kek: options.kek });
+    const gate = inProcessModelGate({
+        root: options.root,
+        readHostModel: () => vault.readHostModel(),
+        writeHostCredential: (credential) => vault.updateHostCredential(credential),
+        ...(options.settings ? { settings: options.settings } : {}),
+    });
+    const meter = createMeter({ logger: options.logger });
+    return {
+        call: (request, signal) => meter.call(options.store, request, () => gate.call(request, signal)),
+    };
+}
+export function inProcessModelGate(options) {
+    return {
+        async call(request, signal) {
+            // One adapter per call, as before the gate: it reads the host model when invoked.
+            const adapter = piModel({
+                ...(options.root !== undefined ? { root: options.root } : {}),
+                readHostModel: options.readHostModel,
+                writeHostCredential: options.writeHostCredential,
+                ...(options.settings ? { settings: options.settings } : {}),
+            });
+            return adapter(request.call, {
+                // The Runtime never journals the provider request (harness `durable.ts`), and
+                // `piModel` doesn't read it.
+                request: undefined,
+                invocationId: request.invocationId,
+                signal,
+                reportPreparedCall() { },
+            });
+        },
+    };
+}

package/dist/gates/inflight.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The model calls (and, from F4.1, the remote MCP tool calls) the gates service is running or
+ * has just finished, by caller key (blueprint §15, P1.2). A call with an `Idempotency-Key` (the loop's effect id) runs under its own
+ * controller, so it outlives its client: when the runtime that sent it dies or shuts down, the
+ * runtime that takes the session over re-sends the call and joins it, or gets the outcome kept
+ * here, instead of calling the provider again.
+ *
+ * In memory, one gateway only (M2): a gateway restart loses these, and a re-sent call runs
+ * again (the ledger flags the duplicate). Outcomes are kept `ttlMs` after they settle; a call
+ * that throws (an abort) is not kept.
+ */
+import type { ModelGateOutcome } from "./model-gate.js";
+/** A re-send whose request differs from the call already running under its key. */
+export declare class InflightConflict extends Error {
+    readonly name = "InflightConflict";
+}
+export interface InflightCalls<T = ModelGateOutcome> {
+    /**
+     * Joins the call under `key`, or starts it with `start` under the entry's own signal.
+     * Rejects with `InflightConflict` when `hash` differs from the running call's.
+     */
+    run(key: string, hash: string, start: (signal: AbortSignal) => Promise<T>): Promise<T>;
+    /** True while a call runs under `key`, or its outcome is still kept. */
+    has(key: string): boolean;
+    /** Aborts the call under `key` and forgets it; nothing when there is none. */
+    cancel(key: string): void;
+    /** Aborts every running call (gateway shutdown). */
+    close(): void;
+    /** Entries held: running, or settled within the TTL. */
+    readonly size: number;
+}
+export interface InflightCallsOptions {
+    /** How long a settled outcome is kept. Default 30 minutes. */
+    readonly ttlMs?: number;
+    /** Most entries; the oldest settled ones go first. Default 10,000. */
+    readonly max?: number;
+    readonly now?: () => number;
+}
+export declare function createInflightCalls<T = ModelGateOutcome>(options?: InflightCallsOptions): InflightCalls<T>;

package/dist/gates/inflight.js

@@ -0,0 +1,70 @@
+/** A re-send whose request differs from the call already running under its key. */
+export class InflightConflict extends Error {
+    name = "InflightConflict";
+}
+export function createInflightCalls(options = {}) {
+    const ttlMs = options.ttlMs ?? 30 * 60_000;
+    const max = options.max ?? 10_000;
+    const now = options.now ?? Date.now;
+    const entries = new Map();
+    /** Drops expired outcomes, then the oldest settled ones while over `max`. */
+    function prune() {
+        const expired = now() - ttlMs;
+        for (const [key, entry] of entries)
+            if (entry.settledAt !== undefined && entry.settledAt <= expired)
+                entries.delete(key);
+        if (entries.size <= max)
+            return;
+        for (const [key, entry] of entries) {
+            if (entries.size <= max)
+                break;
+            if (entry.settledAt !== undefined)
+                entries.delete(key);
+        }
+    }
+    return {
+        run(key, hash, start) {
+            prune();
+            const existing = entries.get(key);
+            if (existing) {
+                if (existing.hash !== hash)
+                    return Promise.reject(new InflightConflict(`A different request is already running under ${key}`));
+                return existing.promise;
+            }
+            const controller = new AbortController();
+            const promise = start(controller.signal).then((outcome) => {
+                entry.settledAt = now();
+                return outcome;
+            }, (error) => {
+                if (entries.get(key) === entry)
+                    entries.delete(key);
+                throw error;
+            });
+            // Nobody may be waiting (the client went away); a rejection is not an unhandled one.
+            promise.catch(() => { });
+            const entry = { hash, controller, promise };
+            entries.set(key, entry);
+            return promise;
+        },
+        has(key) {
+            prune();
+            return entries.has(key);
+        },
+        cancel(key) {
+            const entry = entries.get(key);
+            if (!entry)
+                return;
+            entries.delete(key);
+            entry.controller.abort(new Error("The caller cancelled the call"));
+        },
+        close() {
+            for (const entry of entries.values())
+                if (entry.settledAt === undefined)
+                    entry.controller.abort(new Error("The gateway is shutting down"));
+            entries.clear();
+        },
+        get size() {
+            return entries.size;
+        },
+    };
+}