@mongodb-js/agent-engine-runner-shared 0.11.3

package/dist/server/callback_delivery.js

@@ -0,0 +1,141 @@
+/** Process-local executor callback delivery and redelivery. */
+import { getLogger } from "../logger.js";
+import { postWithRetries, RetryablePostError } from "./http_retry.js";
+const logger = getLogger("agent_engine_runner_shared.server.callback_delivery");
+const CALLBACK_POST_BASE_DELAY_MS = 100;
+const CALLBACK_RETRY_MAX_DELAY_MS = 5_000;
+function callbackKey(callback) {
+    if (callback.status !== "SUSPENDED") {
+        return terminalCallbackKey(callback.execution_id);
+    }
+    // Rolling-upgrade compatibility for OE versions that do not yet send a
+    // suspension generation. Remove this bounded legacy path once every
+    // supported OE consistently supplies suspend_generation.
+    if (callback.suspend_generation === undefined)
+        return null;
+    return JSON.stringify([
+        "suspension",
+        callback.execution_id,
+        callback.suspend_generation,
+    ]);
+}
+function terminalCallbackKey(executionId) {
+    return JSON.stringify(["terminal", executionId]);
+}
+function waitForRetry(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve(false);
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve(false);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(true);
+        }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+export class CallbackDelivery {
+    pending = new Map();
+    tasks = new Map();
+    retryController = new AbortController();
+    async send(oeUrl, callback, ownerUrl, onOwnerFailure) {
+        const key = callbackKey(callback);
+        let pending = null;
+        if (key !== null) {
+            pending = this.reserve(key, oeUrl, callback);
+            if (pending === null)
+                return;
+        }
+        try {
+            await postWithRetries(`${oeUrl}/executor/callback`, callback, ownerUrl ? `${ownerUrl}/executor/callback` : null, onOwnerFailure, undefined, undefined, undefined, key === null
+                ? () => !this.pending.has(terminalCallbackKey(callback.execution_id))
+                : undefined);
+        }
+        catch (error) {
+            if (error instanceof RetryablePostError && key !== null) {
+                this.startRedelivery(key, callback.execution_id);
+                logger.warn({ err: error, execution_id: callback.execution_id }, "Retaining callback after transient delivery failure");
+                return;
+            }
+            logger.error({ err: error, execution_id: callback.execution_id }, key !== null
+                ? "Callback failed with a non-retryable error"
+                : "Suspension callback failed; not retaining because suspend_generation is absent");
+        }
+        if (pending !== null && key !== null && this.pending.get(key) === pending) {
+            this.pending.delete(key);
+        }
+    }
+    async shutdown() {
+        this.retryController.abort();
+        await Promise.allSettled(this.tasks.values());
+        this.tasks.clear();
+        this.pending.clear();
+    }
+    async waitForTerminal(executionId) {
+        const key = terminalCallbackKey(executionId);
+        const task = this.tasks.get(key);
+        if (task !== undefined)
+            await task;
+        return !this.retryController.signal.aborted && !this.pending.has(key);
+    }
+    reserve(key, oeUrl, callback) {
+        const executionId = callback.execution_id;
+        if (this.retryController.signal.aborted) {
+            logger.error({ execution_id: executionId }, "Cannot retain callback during shutdown");
+            return null;
+        }
+        const pending = { oeUrl, callback };
+        const existing = this.pending.get(key);
+        if (existing !== undefined) {
+            if (existing.oeUrl !== oeUrl ||
+                JSON.stringify(existing.callback) !== JSON.stringify(callback)) {
+                logger.error({ execution_id: executionId }, "Refusing to replace conflicting callback");
+            }
+            return null;
+        }
+        this.pending.set(key, pending);
+        return pending;
+    }
+    startRedelivery(key, executionId) {
+        if (!this.tasks.has(key)) {
+            const task = this.redeliver(key, executionId, this.retryController.signal).finally(() => {
+                this.tasks.delete(key);
+            });
+            this.tasks.set(key, task);
+        }
+    }
+    async redeliver(key, executionId, signal) {
+        let delayMs = CALLBACK_POST_BASE_DELAY_MS;
+        while (!signal.aborted) {
+            if (!(await waitForRetry(delayMs, signal)))
+                return;
+            const pending = this.pending.get(key);
+            if (pending === undefined)
+                return;
+            try {
+                await postWithRetries(`${pending.oeUrl}/executor/callback`, pending.callback, null, null, signal);
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return;
+                if (error instanceof RetryablePostError) {
+                    delayMs = Math.min(delayMs * 2, CALLBACK_RETRY_MAX_DELAY_MS);
+                    logger.warn({ err: error, execution_id: executionId }, "Callback redelivery remains pending");
+                    continue;
+                }
+                logger.error({ err: error, execution_id: executionId }, "Dropping callback after a non-retryable redelivery error");
+                if (this.pending.get(key) === pending)
+                    this.pending.delete(key);
+                return;
+            }
+            if (this.pending.get(key) === pending)
+                this.pending.delete(key);
+            return;
+        }
+    }
+}

package/dist/server/chunk_types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Wire-protocol constants for AER → OE stream chunks.
+ *
+ * Centralized so a typo in one site can't silently desync the consumer.
+ * Values are stable strings forwarded verbatim through OE to the API gateway
+ * and on to the UI; do not rename without coordinating across all three
+ * layers (and the Go-side StreamChunk model).
+ */
+export declare const TEXT = "text";
+export declare const SUBAGENT_START = "subagent_start";
+export declare const SUBAGENT_END = "subagent_end";
+export declare const STEP = "step";
+export declare const CUSTOM_EVENT = "custom_event";
+export declare const DONE = "done";
+export declare const ERROR = "error";
+export declare const POLICY_DENIED_ERROR_CODE = "policy_denied";
+/**
+ * Machine-readable discriminator set on `metadata.error_code` of an ERROR
+ * chunk/callback when a deadline expired rather than the work failing. Covers
+ * both flavours — one tool/LLM call overrunning, and the whole turn overrunning —
+ * because a consumer's response to either is the same: offer more time or a
+ * retry, not a bug report. Forwarded verbatim like the values above.
+ */
+export declare const TIMEOUT_ERROR_CODE = "timeout";
+/**
+ * Machine-readable discriminator set on `metadata.error_code` of an ERROR
+ * chunk/callback when the agent's LLM call failed after OE approval (provider
+ * 401/404, rate limit, etc.). `metadata.source` is `llm` so invoke
+ * attribution does not have to string-match the error prose.
+ */
+export declare const LLM_INVOCATION_ERROR_CODE = "llm_invocation_failed";
+/** Owner attribution for LLM-provider failures. Must match the gateway invoke-owner source switch. */
+export declare const LLM_INVOCATION_ERROR_SOURCE = "llm";
+/**
+ * Machine-readable discriminator set on `metadata.error_code` when the LLM
+ * provider rejected the configured credential (HTTP 401/403). Unlike
+ * `llm_invocation_failed` this is deliberately stamped WITHOUT
+ * `metadata.source`: the fix is the customer's own project secret, and the
+ * gateway's owner switch maps the bare code to client-owned, whereas an
+ * `llm` source would attribute it to provider flakiness.
+ */
+export declare const LLM_CREDENTIAL_REJECTED_ERROR_CODE = "llm_credential_rejected";
+/**
+ * Same carrier when a run fails because a tool call's classified external-API
+ * failure was an auth rejection (AUTH_FAILED): the rejected credential is one
+ * of the project's secrets for that tool, not the LLM key. Also stamped
+ * without `metadata.source` so the code drives client-owned attribution.
+ */
+export declare const TOOL_CREDENTIAL_REJECTED_ERROR_CODE = "tool_credential_rejected";
+//# sourceMappingURL=chunk_types.d.ts.map

package/dist/server/chunk_types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_types.d.ts","sourceRoot":"","sources":["../../src/server/chunk_types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,eAAO,MAAM,IAAI,SAAS,CAAC;AAG3B,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAG3C,eAAO,MAAM,IAAI,SAAS,CAAC;AAM3B,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAG3C,eAAO,MAAM,IAAI,SAAS,CAAC;AAC3B,eAAO,MAAM,KAAK,UAAU,CAAC;AAO7B,eAAO,MAAM,wBAAwB,kBAAkB,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,YAAY,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,0BAA0B,CAAC;AAEjE,sGAAsG;AACtG,eAAO,MAAM,2BAA2B,QAAQ,CAAC;AAEjD;;;;;;;GAOG;AACH,eAAO,MAAM,kCAAkC,4BAA4B,CAAC;AAE5E;;;;;GAKG;AACH,eAAO,MAAM,mCAAmC,6BAA6B,CAAC"}

package/dist/server/chunk_types.js

@@ -0,0 +1,62 @@
+/**
+ * Wire-protocol constants for AER → OE stream chunks.
+ *
+ * Centralized so a typo in one site can't silently desync the consumer.
+ * Values are stable strings forwarded verbatim through OE to the API gateway
+ * and on to the UI; do not rename without coordinating across all three
+ * layers (and the Go-side StreamChunk model).
+ */
+// Token of agent output (post-<think> filter, per-source state).
+export const TEXT = "text";
+// Subagent lifecycle markers — emitted only when guardrails are disabled.
+export const SUBAGENT_START = "subagent_start";
+export const SUBAGENT_END = "subagent_end";
+// Mid-execution progress update emitted by tool functions via emitStep().
+export const STEP = "step";
+// Output-parser frame: carries only the custom_event payload
+// field, no platform data. Consumers gate on both this chunk_type and the
+// field's presence — chunk_type is the explicit discriminator; presence guards
+// against a parser payload of JSON null.
+export const CUSTOM_EVENT = "custom_event";
+// Stream terminators.
+export const DONE = "done";
+export const ERROR = "error";
+// Machine-readable discriminator set on metadata.error_code of an ERROR
+// chunk/callback when the OE policy engine denied the call (as opposed to a
+// crash or timeout). Lets the OE/UI render a "blocked by policy" outcome
+// distinctly instead of string-matching the error message. Forwarded verbatim
+// like the chunk_type values above.
+export const POLICY_DENIED_ERROR_CODE = "policy_denied";
+/**
+ * Machine-readable discriminator set on `metadata.error_code` of an ERROR
+ * chunk/callback when a deadline expired rather than the work failing. Covers
+ * both flavours — one tool/LLM call overrunning, and the whole turn overrunning —
+ * because a consumer's response to either is the same: offer more time or a
+ * retry, not a bug report. Forwarded verbatim like the values above.
+ */
+export const TIMEOUT_ERROR_CODE = "timeout";
+/**
+ * Machine-readable discriminator set on `metadata.error_code` of an ERROR
+ * chunk/callback when the agent's LLM call failed after OE approval (provider
+ * 401/404, rate limit, etc.). `metadata.source` is `llm` so invoke
+ * attribution does not have to string-match the error prose.
+ */
+export const LLM_INVOCATION_ERROR_CODE = "llm_invocation_failed";
+/** Owner attribution for LLM-provider failures. Must match the gateway invoke-owner source switch. */
+export const LLM_INVOCATION_ERROR_SOURCE = "llm";
+/**
+ * Machine-readable discriminator set on `metadata.error_code` when the LLM
+ * provider rejected the configured credential (HTTP 401/403). Unlike
+ * `llm_invocation_failed` this is deliberately stamped WITHOUT
+ * `metadata.source`: the fix is the customer's own project secret, and the
+ * gateway's owner switch maps the bare code to client-owned, whereas an
+ * `llm` source would attribute it to provider flakiness.
+ */
+export const LLM_CREDENTIAL_REJECTED_ERROR_CODE = "llm_credential_rejected";
+/**
+ * Same carrier when a run fails because a tool call's classified external-API
+ * failure was an auth rejection (AUTH_FAILED): the rejected credential is one
+ * of the project's secrets for that tool, not the LLM key. Also stamped
+ * without `metadata.source` so the code drives client-owned attribution.
+ */
+export const TOOL_CREDENTIAL_REJECTED_ERROR_CODE = "tool_credential_rejected";

package/dist/server/cors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * CORS origin allowlist resolution for Runner SDK servers.
+ *
+ * Mirrors Python's `agent_engine_runner_shared.server.cors`. Both runtimes are parallel
+ * implementations of the same server architecture, so this file and its
+ * Python twin must be changed together.
+ *
+ * The default is deny-all rather than `*`. Runner servers register
+ * credential-bearing routes (`/execute`, `/invoke_llm`, AER session reads),
+ * so a wildcard default meant any web page a developer visited could drive
+ * tool execution and read stored conversation history once `agentengine dev`
+ * published the ports locally.
+ */
+/** Result of resolving the configured origin allowlist. */
+export interface CorsPolicy {
+    /**
+     * Value for `@fastify/cors`'s `origin` option. `false` disables
+     * cross-origin access entirely (the deny-all default).
+     */
+    origin: false | string[] | "*";
+    /**
+     * Whether to send `Access-Control-Allow-Credentials`. Never true
+     * alongside a wildcard origin — that combination lets any site issue
+     * credentialed requests and read the responses.
+     */
+    credentials: boolean;
+}
+/**
+ * Normalizes `scheme://host[:port]` into the form browsers put in the
+ * `Origin` header — lowercased scheme and host, default port dropped — so
+ * an operator-written `HTTPS://A.com:443` still matches `https://a.com`.
+ *
+ * Returns `null` for anything an `Origin` header never carries (a path,
+ * userinfo, a query, a non-http(s) scheme, wildcards inside the host), so
+ * the entry is reported at startup rather than silently never matching.
+ * Kept behaviourally identical to the Python twin's `_normalize_origin`.
+ */
+export declare function normalizeOrigin(origin: string): string | null;
+/**
+ * Resolves the CORS policy from a raw `CORS_ALLOWED_ORIGINS` value.
+ *
+ * Entries are trimmed before validation: an operator who writes
+ * `a.com, b.com` reasonably expects both to be honoured, and the previous
+ * behaviour of comparing the untrimmed `" b.com"` meant a configured
+ * origin silently never matched — an operator could believe they had
+ * restricted origins when they had not.
+ *
+ * Malformed entries are dropped and logged at warn level for the same
+ * reason: silent non-matching is the failure mode worth eliminating.
+ */
+export declare function resolveCorsPolicy(raw: string | undefined): CorsPolicy;
+//# sourceMappingURL=cors.d.ts.map

package/dist/server/cors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../../src/server/cors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,2DAA2D;AAC3D,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,MAAM,EAAE,KAAK,GAAG,MAAM,EAAE,GAAG,GAAG,CAAC;IAC/B;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAAC;CACtB;AAKD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA4B7D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CA8CrE"}

package/dist/server/cors.js

@@ -0,0 +1,107 @@
+/**
+ * CORS origin allowlist resolution for Runner SDK servers.
+ *
+ * Mirrors Python's `agent_engine_runner_shared.server.cors`. Both runtimes are parallel
+ * implementations of the same server architecture, so this file and its
+ * Python twin must be changed together.
+ *
+ * The default is deny-all rather than `*`. Runner servers register
+ * credential-bearing routes (`/execute`, `/invoke_llm`, AER session reads),
+ * so a wildcard default meant any web page a developer visited could drive
+ * tool execution and read stored conversation history once `agentengine dev`
+ * published the ports locally.
+ */
+import { getLogger } from "../logger.js";
+const logger = getLogger("agent_engine_runner_shared.server.cors");
+/** A DNS name, an IPv4 literal, or a bracketed IPv6 literal. */
+const HOST_PATTERN = /^(?:[a-z0-9.-]+|\[[0-9a-f:.]+\])$/;
+/**
+ * Normalizes `scheme://host[:port]` into the form browsers put in the
+ * `Origin` header — lowercased scheme and host, default port dropped — so
+ * an operator-written `HTTPS://A.com:443` still matches `https://a.com`.
+ *
+ * Returns `null` for anything an `Origin` header never carries (a path,
+ * userinfo, a query, a non-http(s) scheme, wildcards inside the host), so
+ * the entry is reported at startup rather than silently never matching.
+ * Kept behaviourally identical to the Python twin's `_normalize_origin`.
+ */
+export function normalizeOrigin(origin) {
+    // The literal `null` origin sandboxed iframes and `file://` documents send.
+    if (origin === "null") {
+        return "null";
+    }
+    let parsed;
+    try {
+        parsed = new URL(origin);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return null;
+    }
+    // `new URL` normalizes an empty path to "/", so that is the only path an
+    // origin-shaped value may have.
+    if (parsed.pathname !== "/" && parsed.pathname !== "") {
+        return null;
+    }
+    if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+        return null;
+    }
+    // WHATWG parsing permits `*` in a host, which no browser will ever send.
+    if (!HOST_PATTERN.test(parsed.hostname)) {
+        return null;
+    }
+    // `URL.origin` already lowercases and strips the scheme's default port.
+    return parsed.origin;
+}
+/**
+ * Resolves the CORS policy from a raw `CORS_ALLOWED_ORIGINS` value.
+ *
+ * Entries are trimmed before validation: an operator who writes
+ * `a.com, b.com` reasonably expects both to be honoured, and the previous
+ * behaviour of comparing the untrimmed `" b.com"` meant a configured
+ * origin silently never matched — an operator could believe they had
+ * restricted origins when they had not.
+ *
+ * Malformed entries are dropped and logged at warn level for the same
+ * reason: silent non-matching is the failure mode worth eliminating.
+ */
+export function resolveCorsPolicy(raw) {
+    const entries = (raw ?? "")
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    if (entries.length === 0) {
+        // Distinguished from the misconfiguration warnings below: an unset value
+        // used to mean "allow every origin", so a deployment that never set it is
+        // exactly the one whose cross-origin access this change removes.
+        logger.warn("CORS_ALLOWED_ORIGINS is unset — denying all cross-origin requests. " +
+            "Set it to a comma-separated list of origins to allow any.");
+        return { origin: false, credentials: false };
+    }
+    if (entries.includes("*")) {
+        // Explicit opt-in only, and never with credentials. Kept as an escape
+        // hatch for local experimentation; production origins must be listed.
+        logger.warn("CORS_ALLOWED_ORIGINS contains '*' — allowing all origins WITHOUT " +
+            "credentials. List explicit origins to enable credentialed requests.");
+        return { origin: "*", credentials: false };
+    }
+    const valid = [];
+    for (const entry of entries) {
+        const normalized = normalizeOrigin(entry);
+        if (normalized !== null) {
+            if (!valid.includes(normalized)) {
+                valid.push(normalized);
+            }
+        }
+        else {
+            logger.warn(`Ignoring malformed CORS origin ${JSON.stringify(entry)} — expected ` +
+                `scheme://host[:port] with no trailing path.`);
+        }
+    }
+    if (valid.length === 0) {
+        return { origin: false, credentials: false };
+    }
+    return { origin: valid, credentials: true };
+}

package/dist/server/drain.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Execution-scoped drain receiver for Runner SDK servers.
+ *
+ * Mirrors Python's `agent_engine_runner_shared.server.drain`. Both runtimes are parallel
+ * implementations of the same server architecture, so this file and its
+ * Python twin must be changed together.
+ *
+ * When the OE durably cancels an execution it POSTs `/drain` to the Tool/AER
+ * runtime owning that execution. The runtime blocks new work for the
+ * execution, aborts tracked in-flight work where a signal channel exists,
+ * and records an idempotent final outcome the caller retrieves by re-sending
+ * the same request.
+ *
+ * Contract (pinned by the shared fixture in
+ * `client-libraries/test-fixtures/drain/contract.json`):
+ *
+ * - `POST /drain {request_id, execution_id, reason, deadline_at_ms, workspace_id}`
+ *   — `workspace_id` is mandatory on workspace-scoped runtimes (`APP_ID`
+ *   set) and must match it exactly.
+ * - `202 {"outcome": "accepted"}` while draining; `200` with the final
+ *   outcome (`completed` / `timed_out` / `delivery_failed`) afterwards.
+ * - `deadline_at_ms` is absolute. The runtime never extends it.
+ * - `accepted` is HTTP-level acceptance only; `completed` is the only
+ *   quiescence signal.
+ * - An execution this runtime never served is `delivery_failed` with
+ *   `reason_code=execution_not_found` — exact OE targeting does not prove a
+ *   false `completed` safe, since one execution can span AER and Tool
+ *   runtimes independently.
+ *
+ * TS-vs-Python divergence, matching the existing boundary tests: Python can
+ * cancel coroutine tasks outright; a promise has no cancellation, so "notify
+ * active work" here means aborting an AbortController. That reaches work
+ * only where a signal channel already exists (AER execution context, LLM
+ * streams). Plain tool functions receive no signal — they are tracked and
+ * admission-blocked, and outliving the deadline is an honest `timed_out`.
+ *
+ * State is process-local by design: a restarted runtime has lost its active
+ * work and answers `delivery_failed`; reconciliation across restarts belongs
+ * to the caller's durable record, not to this registry.
+ */
+import { z } from "zod";
+import type { FastifyInstance } from "fastify";
+export declare const DrainRequestSchema: z.ZodObject<{
+    request_id: z.ZodString;
+    execution_id: z.ZodString;
+    reason: z.ZodEnum<{
+        execution_cancelled: "execution_cancelled";
+        rolling_restart: "rolling_restart";
+    }>;
+    deadline_at_ms: z.ZodNumber;
+    workspace_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type DrainRequest = z.infer<typeof DrainRequestSchema>;
+export type DrainOutcome = "accepted" | "completed" | "timed_out" | "delivery_failed";
+export type DrainReasonCode = "execution_not_found" | "deadline_exceeded" | "execution_draining";
+export interface DrainVerdict {
+    status: number;
+    body: {
+        outcome: DrainOutcome;
+        reason_code?: DrainReasonCode;
+    };
+}
+/**
+ * Outcome of one per-call abort (POST /interrupt/call). Unlike a drain, an
+ * interrupt is surgical: the execution is never admission-latched and later
+ * calls of the same execution proceed. `not_cancellable` is the honest
+ * answer for tracked work with no signal channel (a plain tool function) —
+ * never a claimed abandonment the runtime cannot perform.
+ */
+export type CallInterruptOutcome = "interrupted" | "not_found" | "already_settled" | "not_cancellable";
+/**
+ * `AbortController.abort()` reason used by the per-call abort, distinct from
+ * DRAIN_ABORT_REASON so error paths can tell the two apart.
+ */
+export declare const CALL_INTERRUPT_REASON = "call_interrupted";
+/**
+ * `AbortController.abort()` reason used by the drain, so error paths can tell
+ * "stopped by cancellation" apart from the execution timeout, which shares
+ * the same controller in the AER.
+ */
+export declare const DRAIN_ABORT_REASON = "execution_drained";
+/**
+ * Execution-scoped admission + active-work registry for one runtime process.
+ *
+ * Mutating methods are synchronous, so check-and-set is atomic on Node's
+ * single thread. The registry is created per server; per-process state only.
+ */
+export declare class DrainRegistry {
+    private readonly recordTtlMs;
+    private readonly maxDeadlineMsValue;
+    private readonly entries;
+    /**
+     * Aborts that arrived before their call registered, keyed by execution and
+     * step, valued by expiry. The window is the OE-claim → in-graph-dispatch
+     * handoff; the retention covers graph scheduling delays, not call lifetimes.
+     */
+    private readonly preAborted;
+    constructor(opts?: {
+        recordTtlMs?: number;
+        maxDeadlineMs?: number;
+        env?: NodeJS.ProcessEnv;
+    });
+    get maxDeadlineMs(): number;
+    /** Reject work for a draining execution without registering it. */
+    checkAdmission(executionId: string): void;
+    /**
+     * Register in-flight work for an execution, rejecting drained ones.
+     *
+     * `controller` is the abort handle the drain fires; omit it for work the
+     * runtime can only wait out (e.g. a tool function with no signal channel).
+     * `stepNumber` makes the work addressable by the per-call abort
+     * (`abortCall`); work registered without it is only ever drained
+     * execution-wide.
+     *
+     * Returns true when a per-call abort preceded this registration (the Stop
+     * landed in the OE-claim → in-graph-dispatch handoff): the caller must not
+     * start the body and must settle the call interrupted.
+     */
+    beginWork(executionId: string, controller?: AbortController, stepNumber?: number): boolean;
+    private preAbortKey;
+    private popPreAborted;
+    private sweepPreAborted;
+    /**
+     * Signal exactly one in-flight call, leaving the execution open — the
+     * surgical sibling of a drain: no admission latch, no record, no deadline,
+     * and later steps of the same execution proceed. Idempotent: a repeat
+     * abort of the same step re-reads the same outcome.
+     */
+    abortCall(executionId: string, stepNumber: number): CallInterruptOutcome;
+    /**
+     * Close a call's interruptibility as its result report begins: the body
+     * already produced its outcome, so a late abort must read already_settled
+     * rather than claim a stop the durable record will contradict.
+     */
+    claimSettlement(executionId: string, stepNumber: number): void;
+    /**
+     * Attach an abort handle to already-registered work. The AER builds its
+     * execution-wide controller inside the handler, after admission — a drain
+     * that landed in between aborts it here, at attach time.
+     */
+    attachController(executionId: string, controller: AbortController): void;
+    endWork(executionId: string, controller?: AbortController, stepNumber?: number): void;
+    /** Apply one drain request; idempotent by request_id, coalescing per execution. */
+    apply(request: DrainRequest): DrainVerdict;
+    private finalize;
+    private scheduleEviction;
+    private cancelEviction;
+    private evict;
+    private current;
+    private final;
+}
+/**
+ * Register `POST /drain` on a runner server.
+ *
+ * The bearer-auth hook already gates the path; this adds the
+ * execution/workspace-scoped validation on top. Callers of this endpoint
+ * must not follow redirects — the bearer token must never be forwarded to
+ * another host.
+ *
+ * Scope check: the bearer token authenticates the caller but does not
+ * establish that the named drain belongs to this runtime, so when the
+ * platform scopes this process to a workspace (`APP_ID` set — every managed
+ * runtime), the request must name that workspace exactly; a missing
+ * `workspace_id` is a 400, a mismatch a 403. When `APP_ID` is unset (local
+ * development against a single unscoped runtime) no workspace check is
+ * possible and none is enforced.
+ */
+export declare function registerDrainRoute(app: FastifyInstance, registry: DrainRegistry, env?: NodeJS.ProcessEnv): void;
+//# sourceMappingURL=drain.d.ts.map

package/dist/server/drain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drain.d.ts","sourceRoot":"","sources":["../../src/server/drain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAY/C,eAAO,MAAM,kBAAkB;;;;;;;;;iBAa7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,MAAM,MAAM,YAAY,GACpB,UAAU,GACV,WAAW,GACX,WAAW,GACX,iBAAiB,CAAC;AAEtB,MAAM,MAAM,eAAe,GACvB,qBAAqB,GACrB,mBAAmB,GACnB,oBAAoB,CAAC;AAEzB,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE;QAAE,OAAO,EAAE,YAAY,CAAC;QAAC,WAAW,CAAC,EAAE,eAAe,CAAA;KAAE,CAAC;CAChE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAC5B,aAAa,GACb,WAAW,GACX,iBAAiB,GACjB,iBAAiB,CAAC;AAEtB;;;GAGG;AACH,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAiCxD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,sBAAsB,CAAC;AA8CtD;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;gBAGtD,IAAI,GAAE;QACJ,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;KACpB;IAmBR,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,mEAAmE;IACnE,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAKzC;;;;;;;;;;;;OAYG;IACH,SAAS,CACP,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,eAAe,EAC5B,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO;IAuCV,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,eAAe;IAQvB;;;;;OAKG;IACH,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,oBAAoB;IA0BxE;;;;OAIG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAK9D;;;;OAIG;IACH,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,GAAG,IAAI;IASxE,OAAO,CACL,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,eAAe,EAC5B,UAAU,CAAC,EAAE,MAAM,GAClB,IAAI;IAuBP,mFAAmF;IACnF,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY;YAkE5B,QAAQ;IA4BtB,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,KAAK;IAQb,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,KAAK;CAYd;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,aAAa,EACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,IAAI,CAmBN"}