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

package/dist/server/auth.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Bearer-token authentication for Runner SDK servers.
+ *
+ * Mirrors Python's `agent_engine_runner_shared.server.auth`. Both runtimes are parallel
+ * implementations of the same server architecture, so this file and its
+ * Python twin must be changed together.
+ *
+ * Runner servers registered every route — `/execute`, `/invoke_llm`, the AER
+ * session-message reads — with no authentication at all, relying on network
+ * reachability. The only legitimate caller is the Orchestration Engine, so
+ * this is service-to-service auth using the same bearer-token shape as the
+ * operator's gRPC control plane.
+ *
+ * Enforcement is conditional on `RUNNER_AUTH_TOKEN` being configured. The
+ * runner image also runs under `agentengine dev up` on a developer's laptop,
+ * where no deploy-time secret exists and hard-failing would break local
+ * development outright; an unconfigured server logs a warning at startup so
+ * the weaker posture is visible rather than silent.
+ *
+ * Deployments that provision the token can additionally set
+ * `RUNNER_AUTH_REQUIRED=true` to make a missing token fatal at startup: the
+ * server throws {@link MissingRunnerAuthTokenError} instead of serving
+ * unauthenticated, so a provisioning gap crash-loops loudly rather than
+ * silently weakening auth. The signal is opt-in so shipping this code
+ * changes no running behavior until token provisioning is in place.
+ */
+import type { FastifyInstance } from "fastify";
+export declare function isUnauthenticatedPath(pathname: string): boolean;
+/**
+ * Constant-time comparison, so a caller cannot recover the configured token
+ * byte by byte from response timing.
+ *
+ * Both values are hashed first so the comparison is always over two 32-byte
+ * buffers: `timingSafeEqual` throws on length mismatch, and short-circuiting
+ * on length would otherwise leak the configured token's length.
+ */
+export declare function tokensEqual(presented: string, expected: string): boolean;
+/** Extracts the bearer token from an Authorization header value. */
+export declare function bearerToken(headerValue: string | undefined): string | null;
+/**
+ * Thrown at startup when `RUNNER_AUTH_REQUIRED=true` is set but no auth
+ * token is configured.
+ */
+export declare class MissingRunnerAuthTokenError extends Error {
+    constructor(modeName: string);
+}
+/**
+ * Registers the authentication hook on `app`, if a token is configured.
+ *
+ * Returns whether enforcement is active, so the caller can surface it.
+ * Throws {@link MissingRunnerAuthTokenError} when `RUNNER_AUTH_REQUIRED` is
+ * set to `true` (or `1`) but no token is configured, so a deployment that
+ * mandates auth fails loudly instead of serving unauthenticated.
+ */
+export declare function registerAuthHook(app: FastifyInstance, modeName: string, env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/server/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAgC,MAAM,SAAS,CAAC;AA0B7E,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG/D;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAIxE;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAY1E;AAED;;;GAGG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,QAAQ,EAAE,MAAM;CAU7B;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,MAAM,EAChB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAoCT"}

package/dist/server/auth.js

@@ -0,0 +1,132 @@
+/**
+ * Bearer-token authentication for Runner SDK servers.
+ *
+ * Mirrors Python's `agent_engine_runner_shared.server.auth`. Both runtimes are parallel
+ * implementations of the same server architecture, so this file and its
+ * Python twin must be changed together.
+ *
+ * Runner servers registered every route — `/execute`, `/invoke_llm`, the AER
+ * session-message reads — with no authentication at all, relying on network
+ * reachability. The only legitimate caller is the Orchestration Engine, so
+ * this is service-to-service auth using the same bearer-token shape as the
+ * operator's gRPC control plane.
+ *
+ * Enforcement is conditional on `RUNNER_AUTH_TOKEN` being configured. The
+ * runner image also runs under `agentengine dev up` on a developer's laptop,
+ * where no deploy-time secret exists and hard-failing would break local
+ * development outright; an unconfigured server logs a warning at startup so
+ * the weaker posture is visible rather than silent.
+ *
+ * Deployments that provision the token can additionally set
+ * `RUNNER_AUTH_REQUIRED=true` to make a missing token fatal at startup: the
+ * server throws {@link MissingRunnerAuthTokenError} instead of serving
+ * unauthenticated, so a provisioning gap crash-loops loudly rather than
+ * silently weakening auth. The signal is opt-in so shipping this code
+ * changes no running behavior until token provisioning is in place.
+ */
+import { createHash, timingSafeEqual } from "node:crypto";
+import { getLogger } from "../logger.js";
+const logger = getLogger("agent_engine_runner_shared.server.auth");
+/**
+ * Routes reachable without a token.
+ *
+ * Liveness and readiness probes originate from the kubelet and cannot
+ * present one, and these responses carry no tenant data. Everything else —
+ * including every credential-bearing and data-returning route — is gated.
+ *
+ * `/metrics` is deliberately NOT here: it returns `Metrics.getAll()`, whose
+ * counter names carry tenant-derived labels (`tool_name`, `model_name`), so
+ * an unauthenticated reader could enumerate which tools and models an agent
+ * uses. It is not a Prometheus scrape target — nothing in the platform reads
+ * it, so gating it costs nothing.
+ */
+const UNAUTHENTICATED_PATHS = new Set([
+    "/",
+    "/health",
+    "/healthz",
+    "/ready",
+    "/readyz",
+]);
+export function isUnauthenticatedPath(pathname) {
+    const path = (pathname || "").split("?")[0];
+    return UNAUTHENTICATED_PATHS.has(path ?? "");
+}
+/**
+ * Constant-time comparison, so a caller cannot recover the configured token
+ * byte by byte from response timing.
+ *
+ * Both values are hashed first so the comparison is always over two 32-byte
+ * buffers: `timingSafeEqual` throws on length mismatch, and short-circuiting
+ * on length would otherwise leak the configured token's length.
+ */
+export function tokensEqual(presented, expected) {
+    const a = createHash("sha256").update(presented, "utf8").digest();
+    const b = createHash("sha256").update(expected, "utf8").digest();
+    return timingSafeEqual(a, b);
+}
+/** Extracts the bearer token from an Authorization header value. */
+export function bearerToken(headerValue) {
+    if (!headerValue) {
+        return null;
+    }
+    const prefix = "bearer ";
+    if (headerValue.length <= prefix.length) {
+        return null;
+    }
+    if (headerValue.slice(0, prefix.length).toLowerCase() !== prefix) {
+        return null;
+    }
+    return headerValue.slice(prefix.length);
+}
+/**
+ * Thrown at startup when `RUNNER_AUTH_REQUIRED=true` is set but no auth
+ * token is configured.
+ */
+export class MissingRunnerAuthTokenError extends Error {
+    constructor(modeName) {
+        super(`${modeName} server refusing to start without request authentication: ` +
+            `RUNNER_AUTH_REQUIRED is set but RUNNER_AUTH_TOKEN is not, so any ` +
+            `caller that could reach this port would be able to execute tools ` +
+            `and read session data. Provision RUNNER_AUTH_TOKEN, or unset ` +
+            `RUNNER_AUTH_REQUIRED to accept running unauthenticated.`);
+        this.name = "MissingRunnerAuthTokenError";
+    }
+}
+/**
+ * Registers the authentication hook on `app`, if a token is configured.
+ *
+ * Returns whether enforcement is active, so the caller can surface it.
+ * Throws {@link MissingRunnerAuthTokenError} when `RUNNER_AUTH_REQUIRED` is
+ * set to `true` (or `1`) but no token is configured, so a deployment that
+ * mandates auth fails loudly instead of serving unauthenticated.
+ */
+export function registerAuthHook(app, modeName, env = process.env) {
+    const expected = (env["RUNNER_AUTH_TOKEN"] ?? "").trim();
+    if (!expected) {
+        const required = (env["RUNNER_AUTH_REQUIRED"] ?? "").trim().toLowerCase();
+        if (required === "1" || required === "true") {
+            throw new MissingRunnerAuthTokenError(modeName);
+        }
+        logger.warn(`${modeName} server is running without request authentication: ` +
+            `RUNNER_AUTH_TOKEN is not set, so any caller that can reach this ` +
+            `port can execute tools and read session data.`);
+        return false;
+    }
+    app.addHook("onRequest", async (request, reply) => {
+        // Fastify's request.url is the raw request-line URL; it never consults
+        // the Host header, so it cannot be corrupted the way starlette's
+        // Host-derived request.url.path can (see the Python twin). No fix
+        // is needed here — this comment exists so the difference isn't mistaken
+        // for an oversight.
+        if (isUnauthenticatedPath(request.url)) {
+            return;
+        }
+        const presented = bearerToken(request.headers.authorization);
+        if (presented === null || !tokensEqual(presented, expected)) {
+            // Returning the reply is the documented way to halt the lifecycle;
+            // relying on the `reply.sent` short-circuit is version-dependent.
+            return reply.code(401).send({ detail: "unauthorized" });
+        }
+    });
+    return true;
+}

package/dist/server/base.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Base server class for Runner SDK components.
+ *
+ * Provides common Fastify setup, health/root/metrics endpoints, and
+ * startup/shutdown lifecycle hooks shared by all runtime modes.
+ *
+ * Mirrors Python's `BaseServer` (FastAPI/uvicorn → Fastify).
+ */
+import { type FastifyInstance } from "fastify";
+import type { BaseAgent, BaseExecutionCallback } from "@mongodb-js/agent-engine-sdk";
+import type { RuntimeAgentConfig } from "../agent_config.js";
+import type { TurnMemoryWriter } from "../memory_writer.js";
+import { DrainRegistry } from "./drain.js";
+export declare const DEFAULT_PORTS: Record<string, number>;
+/** Tool function signature — receives the full arguments Record, may return a Promise. */
+export type ServerToolFn = (args: Record<string, unknown>) => unknown;
+/** Minimal graph builder interface. */
+export interface GraphBuilderLike {
+    getAgent?(opts?: {
+        callbacks?: BaseExecutionCallback[];
+    }): BaseAgent;
+    /**
+     * Resolves once any async setup kicked off during construction (e.g. MCP
+     * tool discovery) has finished registering tools. `TenantRuntime.runAsync()`
+     * awaits this before binding the server, so no request can land before
+     * setup completes. Optional — builders with no async setup can omit it.
+     */
+    ready?(): Promise<void>;
+    /**
+     * Build the agent graph before first use when explicitly requested. The
+     * TypeScript AER does not call this synchronous hook during standby warming
+     * because doing so would block the Node event loop and server health.
+     */
+    warmUp?(): void;
+}
+/**
+ * Minimal runtime interface that server classes depend on.
+ */
+export interface ITenantRuntime {
+    readonly appName: string;
+    readonly appVersion?: string;
+    readonly orgId: string | null;
+    /**
+     * Optional so pre-existing hand-written implementations (custom runtimes,
+     * test doubles) keep typechecking across the SDK bump that introduced it.
+     * The capability-advertise path treats absent and null alike by skipping.
+     */
+    readonly projectId?: string | null;
+    /** Native-checkpoint turn writer, present only when Memory is enabled. */
+    readonly memoryWriter?: TurnMemoryWriter | null;
+    /** Graph builder instance — null if not set at startup. */
+    readonly graphBuilder: GraphBuilderLike | null;
+    /** Raw tool functions registered via `app.tool()`, keyed by name. */
+    readonly tools: Record<string, ServerToolFn>;
+    /** Tool metadata (description, is_local, etc.), keyed by name. */
+    readonly toolDefinitions: Record<string, Record<string, unknown>>;
+    /** Parsed `agent.yaml` configuration. */
+    getAgentConfig(): RuntimeAgentConfig;
+    /** Resolved MongoDB URI: constructor option > `MONGODB_URI` env var > null. */
+    getMongodbUri(): string | null;
+    /** Get a `BaseAgent` instance, optionally wired with execution callbacks. */
+    getAgent(opts?: {
+        callbacks?: BaseExecutionCallback[];
+    }): BaseAgent;
+    /** Explicit pre-build via the graph builder's `warmUp()`, if it has one. */
+    warmUpAgent?(): void;
+}
+/**
+ * Abstract base server for all Runner SDK runtime modes.
+ *
+ * Subclasses implement:
+ * - `modeName` — 'aer' | 'tool' | 'memory-server'
+ * - `registerRoutes(app)` — mode-specific Fastify routes
+ * - `onStartup` / `onShutdown` — optional lifecycle hooks
+ * - `getHealthDetails` — optional extra fields for /health
+ */
+export declare abstract class BaseServer {
+    protected readonly runtime: ITenantRuntime;
+    protected app: FastifyInstance | null;
+    private _drainRegistry?;
+    constructor(runtime: ITenantRuntime);
+    /**
+     * Execution-scoped drain state for POST /drain; work routes register
+     * against it so a cancelled execution's in-flight work can be stopped.
+     * Lazily created on the prototype so tests that skip the constructor
+     * (`Object.create`) still get a working registry.
+     */
+    get drainRegistry(): DrainRegistry;
+    abstract get modeName(): string;
+    get defaultPort(): number;
+    abstract registerRoutes(app: FastifyInstance): void;
+    onStartup(): Promise<void>;
+    onShutdown(): Promise<void>;
+    getHealthDetails(): Record<string, unknown>;
+    createApp(): FastifyInstance;
+    /**
+     * Gracefully close the underlying Fastify server, draining in-flight
+     * requests and running `onClose` hooks. No-op if the app was never created.
+     */
+    close(): Promise<void>;
+    protected registerCommonRoutes(app: FastifyInstance): void;
+    run(host?: string, port?: number): Promise<void>;
+}
+//# sourceMappingURL=base.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/server/base.ts"],"names":[],"mappings":"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"}

package/dist/server/base.js

@@ -0,0 +1,150 @@
+/**
+ * Base server class for Runner SDK components.
+ *
+ * Provides common Fastify setup, health/root/metrics endpoints, and
+ * startup/shutdown lifecycle hooks shared by all runtime modes.
+ *
+ * Mirrors Python's `BaseServer` (FastAPI/uvicorn → Fastify).
+ */
+import fastify from "fastify";
+import cors from "@fastify/cors";
+import { ZodError } from "zod";
+import { getLogger } from "../logger.js";
+import { Metrics } from "../metrics.js";
+import { HealthStatus } from "../models.js";
+import { tracingStatus } from "../tracing/index.js";
+import { resolveCorsPolicy } from "./cors.js";
+import { registerAuthHook } from "./auth.js";
+import { DrainRegistry, registerDrainRoute } from "./drain.js";
+import { registerCallInterruptRoute } from "./callInterrupt.js";
+const logger = getLogger("agent_engine_runner_shared.server.base");
+export const DEFAULT_PORTS = {
+    aer: 8001,
+    tool: 8002,
+    "memory-server": 8081,
+};
+/**
+ * Abstract base server for all Runner SDK runtime modes.
+ *
+ * Subclasses implement:
+ * - `modeName` — 'aer' | 'tool' | 'memory-server'
+ * - `registerRoutes(app)` — mode-specific Fastify routes
+ * - `onStartup` / `onShutdown` — optional lifecycle hooks
+ * - `getHealthDetails` — optional extra fields for /health
+ */
+export class BaseServer {
+    runtime;
+    app = null;
+    _drainRegistry;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    /**
+     * Execution-scoped drain state for POST /drain; work routes register
+     * against it so a cancelled execution's in-flight work can be stopped.
+     * Lazily created on the prototype so tests that skip the constructor
+     * (`Object.create`) still get a working registry.
+     */
+    get drainRegistry() {
+        return (this._drainRegistry ??= new DrainRegistry());
+    }
+    get defaultPort() {
+        return DEFAULT_PORTS[this.modeName] ?? 8000;
+    }
+    async onStartup() { }
+    async onShutdown() { }
+    getHealthDetails() {
+        return {};
+    }
+    createApp() {
+        const corsPolicy = resolveCorsPolicy(process.env["CORS_ALLOWED_ORIGINS"]);
+        const app = fastify({ logger: false });
+        void app.register(cors, {
+            origin: corsPolicy.origin,
+            credentials: corsPolicy.credentials,
+            methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS", "HEAD"],
+        });
+        registerAuthHook(app, this.modeName);
+        app.addHook("onReady", async () => {
+            logger.info(`Starting ${this.modeName} server...`);
+            await this.onStartup();
+            logger.info(`${this.modeName} server started`);
+        });
+        app.addHook("onClose", async () => {
+            logger.info(`Shutting down ${this.modeName} server...`);
+            await this.onShutdown();
+            logger.info(`${this.modeName} server stopped`);
+        });
+        this.registerCommonRoutes(app);
+        this.registerRoutes(app);
+        // Map request-validation failures to client errors. FastAPI/Pydantic
+        // returns 422 for a malformed body; without this, a ZodError thrown by a
+        // route's `Schema.parse(request.body)` becomes a generic 500, which OE and
+        // other callers may retry as a transient infra failure rather than reject
+        // as a bad payload. Non-Zod errors keep their explicit `statusCode`
+        // (e.g. the 400/504 set by the AER execute path) or default to 500.
+        app.setErrorHandler((error, _request, reply) => {
+            if (error instanceof ZodError) {
+                return reply
+                    .status(422)
+                    .send({ error: "Validation failed", detail: error.issues });
+            }
+            const err = error;
+            const statusCode = err.statusCode ?? 500;
+            const message = err.message ?? "Internal Server Error";
+            if (statusCode >= 500) {
+                logger.error({ err: error }, `Unhandled error: ${message}`);
+            }
+            return reply.status(statusCode).send({ error: message });
+        });
+        this.app = app;
+        return app;
+    }
+    /**
+     * Gracefully close the underlying Fastify server, draining in-flight
+     * requests and running `onClose` hooks. No-op if the app was never created.
+     */
+    async close() {
+        if (this.app) {
+            await this.app.close();
+        }
+    }
+    registerCommonRoutes(app) {
+        registerDrainRoute(app, this.drainRegistry);
+        registerCallInterruptRoute(app, this.drainRegistry);
+        app.get("/health", async () => {
+            // Probes check the HTTP status code (2xx = pass), not the body, so a
+            // `degraded` status surfaces the state for observability without
+            // triggering a pod restart — e.g. the trace store being unreachable at
+            // startup while the pod keeps serving traffic.
+            const tracing = tracingStatus();
+            const status = tracing.database_exporter === "degraded"
+                ? HealthStatus.DEGRADED
+                : HealthStatus.HEALTHY;
+            return {
+                status,
+                component: this.runtime.appName,
+                mode: this.modeName,
+                version: "1.0.0",
+                details: { ...this.getHealthDetails(), tracing },
+            };
+        });
+        app.get("/", async () => ({
+            service: this.runtime.appName,
+            mode: this.modeName,
+            status: "running",
+        }));
+        app.get("/metrics", async () => ({
+            status: "ok",
+            component: this.modeName,
+            metrics: Metrics.getAll(),
+            timestamp: new Date().toISOString(),
+        }));
+    }
+    async run(host = "0.0.0.0", port) {
+        const listenPort = port ?? this.defaultPort;
+        const app = this.createApp();
+        logger.info(`Starting ${this.modeName} server on ${host}:${listenPort}`);
+        await app.listen({ host, port: listenPort });
+    }
+}

package/dist/server/callInterrupt.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Per-call interrupt receiver for Runner SDK servers.
+ *
+ * Mirrors Python's `agent_engine_runner_shared.server.call_interrupt`. Both runtimes are
+ * parallel implementations of the same server architecture, so this file and
+ * its Python twin must be changed together.
+ *
+ * When the OE's per-call interrupt fires, it POSTs `/interrupt/call` with
+ * the execution and the step to abandon. The runtime aborts exactly that
+ * call's controller and nothing else — unlike `POST /drain`, which is
+ * terminal for the execution, an interrupt is surgical: no admission latch,
+ * no record, and later steps of the same execution proceed.
+ *
+ * Contract (pinned by the shared fixture in
+ * `client-libraries/test-fixtures/interrupt-call/contract.json`):
+ *
+ * - `POST /interrupt/call {execution_id, step_number, workspace_id}` —
+ *   `workspace_id` is mandatory on workspace-scoped runtimes (`APP_ID` set)
+ *   and must match it exactly.
+ * - Always 200 with an outcome: `interrupted` (the call's controller was
+ *   aborted), `not_found` (no such in-flight call), `already_settled` (the
+ *   call ended first), `not_cancellable` (tracked work with no signal
+ *   channel — a plain tool function — reported honestly, never claimed
+ *   abandoned).
+ * - Idempotent by (execution_id, step_number): a repeat re-reads the
+ *   outcome.
+ */
+import { z } from "zod";
+import type { FastifyInstance } from "fastify";
+import type { DrainRegistry } from "./drain.js";
+export declare const CallInterruptRequestSchema: z.ZodObject<{
+    execution_id: z.ZodString;
+    step_number: z.ZodNumber;
+    workspace_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type CallInterruptRequest = z.infer<typeof CallInterruptRequestSchema>;
+/**
+ * Register `POST /interrupt/call` on a runner server.
+ *
+ * The bearer-auth middleware already gates the path; this adds the
+ * execution/workspace-scoped validation on top, identical to the drain
+ * route's: 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) no workspace check is possible and
+ * none is enforced.
+ */
+export declare function registerCallInterruptRoute(app: FastifyInstance, registry: DrainRegistry, env?: NodeJS.ProcessEnv): void;
+//# sourceMappingURL=callInterrupt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"callInterrupt.d.ts","sourceRoot":"","sources":["../../src/server/callInterrupt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAG/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD,eAAO,MAAM,0BAA0B;;;;iBAOrC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,aAAa,EACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,IAAI,CAqBN"}

package/dist/server/callInterrupt.js

@@ -0,0 +1,68 @@
+/**
+ * Per-call interrupt receiver for Runner SDK servers.
+ *
+ * Mirrors Python's `agent_engine_runner_shared.server.call_interrupt`. Both runtimes are
+ * parallel implementations of the same server architecture, so this file and
+ * its Python twin must be changed together.
+ *
+ * When the OE's per-call interrupt fires, it POSTs `/interrupt/call` with
+ * the execution and the step to abandon. The runtime aborts exactly that
+ * call's controller and nothing else — unlike `POST /drain`, which is
+ * terminal for the execution, an interrupt is surgical: no admission latch,
+ * no record, and later steps of the same execution proceed.
+ *
+ * Contract (pinned by the shared fixture in
+ * `client-libraries/test-fixtures/interrupt-call/contract.json`):
+ *
+ * - `POST /interrupt/call {execution_id, step_number, workspace_id}` —
+ *   `workspace_id` is mandatory on workspace-scoped runtimes (`APP_ID` set)
+ *   and must match it exactly.
+ * - Always 200 with an outcome: `interrupted` (the call's controller was
+ *   aborted), `not_found` (no such in-flight call), `already_settled` (the
+ *   call ended first), `not_cancellable` (tracked work with no signal
+ *   channel — a plain tool function — reported honestly, never claimed
+ *   abandoned).
+ * - Idempotent by (execution_id, step_number): a repeat re-reads the
+ *   outcome.
+ */
+import { z } from "zod";
+import { getLogger } from "../logger.js";
+const logger = getLogger("agent_engine_runner_shared.server.callInterrupt");
+export const CallInterruptRequestSchema = z.object({
+    execution_id: z.string().min(1).max(256),
+    step_number: z.number().int().nonnegative(),
+    // Null is an accepted spelling of omission, matching the Python twin and
+    // the drain contract (string|null). The route's truthiness checks treat it
+    // as a missing scope claim either way.
+    workspace_id: z.string().max(256).nullish(),
+});
+/**
+ * Register `POST /interrupt/call` on a runner server.
+ *
+ * The bearer-auth middleware already gates the path; this adds the
+ * execution/workspace-scoped validation on top, identical to the drain
+ * route's: 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) no workspace check is possible and
+ * none is enforced.
+ */
+export function registerCallInterruptRoute(app, registry, env = process.env) {
+    const workspaceId = (env["APP_ID"] ?? "").trim();
+    app.post("/interrupt/call", async (request, reply) => {
+        const body = CallInterruptRequestSchema.parse(request.body);
+        if (workspaceId) {
+            if (!body.workspace_id) {
+                return reply.code(400).send({ detail: "workspace_id required" });
+            }
+            if (body.workspace_id !== workspaceId) {
+                return reply.code(403).send({ detail: "workspace mismatch" });
+            }
+        }
+        const outcome = registry.abortCall(body.execution_id, body.step_number);
+        // The runtime-side evidence of a per-call abort, mirroring the drain
+        // receiver's accepted/finalized markers.
+        logger.info(`Call interrupt ${outcome} for execution ${body.execution_id} (step ${body.step_number})`);
+        return reply.send({ outcome });
+    });
+}

package/dist/server/callback_delivery.d.ts

@@ -0,0 +1,14 @@
+/** Process-local executor callback delivery and redelivery. */
+import type { ExecutorCallbackRequest } from "../models.js";
+export declare class CallbackDelivery {
+    private pending;
+    private tasks;
+    private retryController;
+    send(oeUrl: string, callback: ExecutorCallbackRequest, ownerUrl?: string | null, onOwnerFailure?: (() => void) | null): Promise<void>;
+    shutdown(): Promise<void>;
+    waitForTerminal(executionId: string): Promise<boolean>;
+    private reserve;
+    private startRedelivery;
+    private redeliver;
+}
+//# sourceMappingURL=callback_delivery.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"callback_delivery.d.ts","sourceRoot":"","sources":["../../src/server/callback_delivery.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAE/D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAmD5D,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,OAAO,CAAsC;IACrD,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,eAAe,CAAyB;IAE1C,IAAI,CACR,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,uBAAuB,EACjC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,EACxB,cAAc,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GACnC,OAAO,CAAC,IAAI,CAAC;IA2CV,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAOzB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAO5D,OAAO,CAAC,OAAO;IAiCf,OAAO,CAAC,eAAe;YAaT,SAAS;CAwCxB"}