@nylorun/runtime 0.15.2-beta → 0.16.0-beta

package/dist/gates/inflight.js

@@ -2,6 +2,10 @@
 export class InflightConflict extends Error {
     name = "InflightConflict";
 }
+/** A re-send under an older lease epoch than the call's: never joins (G4). */
+export class InflightStale extends Error {
+    name = "InflightStale";
+}
 export function createInflightCalls(options = {}) {
     const ttlMs = options.ttlMs ?? 30 * 60_000;
     const max = options.max ?? 10_000;
@@ -23,12 +27,19 @@ export function createInflightCalls(options = {}) {
         }
     }
     return {
-        run(key, hash, start) {
+        run(key, hash, start, owner) {
             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}`));
+                if (owner && existing.owner) {
+                    if (owner.sessionId !== existing.owner.sessionId)
+                        return Promise.reject(new InflightConflict(`The call under ${key} is another session's`));
+                    if (owner.epoch < existing.owner.epoch)
+                        return Promise.reject(new InflightStale(`A newer owner of the session holds the call under ${key}`));
+                    existing.owner = owner;
+                }
                 return existing.promise;
             }
             const controller = new AbortController();
@@ -42,7 +53,7 @@ export function createInflightCalls(options = {}) {
             });
             // Nobody may be waiting (the client went away); a rejection is not an unhandled one.
             promise.catch(() => { });
-            const entry = { hash, controller, promise };
+            const entry = { hash, controller, promise, ...(owner ? { owner } : {}) };
             entries.set(key, entry);
             return promise;
         },
@@ -50,12 +61,15 @@ export function createInflightCalls(options = {}) {
             prune();
             return entries.has(key);
         },
-        cancel(key) {
+        cancel(key, sessionId) {
             const entry = entries.get(key);
             if (!entry)
-                return;
+                return true;
+            if (sessionId !== undefined && entry.owner && entry.owner.sessionId !== sessionId)
+                return false;
             entries.delete(key);
             entry.controller.abort(new Error("The caller cancelled the call"));
+            return true;
         },
         close() {
             for (const entry of entries.values())

package/dist/gates/model-gate.d.ts

@@ -11,7 +11,11 @@
  */
 import type { RuntimeModelAdapter, RuntimeModelCall } from "../contracts.js";
 export type { ModelCallSettings } from "../model/pi-model.js";
-/** One model call, as the loop hands it to the gate. JSON-safe: it crosses the network. */
+/**
+ * One model call, as the loop hands it to the gate. JSON-safe: it crosses the network. Over
+ * HTTP the session, turn and agent travel in the run token, not the body (F5): the gate's route
+ * fills them in from its claims.
+ */
 export interface ModelGateRequest {
     readonly tenantId: string;
     readonly sessionId: string;
@@ -41,5 +45,5 @@ export interface ModelGate {
      * Stops a call that outlives its caller (a user cancel). Best-effort: never rejects. Only a
      * gate that `recovers` needs it; for the others aborting `signal` already stops the call.
      */
-    cancel?(request: Pick<ModelGateRequest, "tenantId" | "effectId">): Promise<void>;
+    cancel?(request: Pick<ModelGateRequest, "tenantId" | "sessionId" | "effectId">): Promise<void>;
 }

package/dist/gates/tool-calls.d.ts

@@ -15,7 +15,7 @@
  */
 import type { McpServerRef } from "../mcp/pool.js";
 import type { Logger } from "../tenant/types.js";
-import { type InflightCallsOptions } from "./inflight.js";
+import { type InflightCallsOptions, type InflightOwner } from "./inflight.js";
 import type { McpHandler } from "./mcp-handler.js";
 import type { TenantVaults } from "./tenant-vaults.js";
 import type { McpAnswer } from "./tool-contract.js";
@@ -31,11 +31,15 @@ export interface ToolCallRequest {
 export interface ToolCalls {
     /**
      * Runs, joins or answers the call under `key`. Rejects with `InflightConflict` when a
-     * different request already ran under it.
+     * different request already ran under it, and as `InflightCalls.run` does for `owner`, the
+     * run that sends it (F5).
      */
-    run(tenantId: string | undefined, key: string, hash: string, request: ToolCallRequest): Promise<ToolCallAnswer>;
-    /** Aborts the call under `key`; it is never run again under that key. */
-    cancel(key: string): void;
+    run(tenantId: string | undefined, key: string, hash: string, request: ToolCallRequest, owner?: InflightOwner): Promise<ToolCallAnswer>;
+    /**
+     * Aborts the call under `key`; it is never run again under that key. With `sessionId`, false
+     * when the running call is another session's (nothing is aborted).
+     */
+    cancel(key: string, sessionId?: string): boolean;
     /** Aborts every running call (gateway shutdown). */
     close(): void;
     /** Deletes crossings settled more than `TOOL_CROSSING_TTL_MS` ago. */

package/dist/gates/tool-calls.js

@@ -1,4 +1,4 @@
-import { createInflightCalls, InflightConflict } from "./inflight.js";
+import { createInflightCalls, InflightConflict, } from "./inflight.js";
 /** How long a settled crossing is kept. */
 export const TOOL_CROSSING_TTL_MS = 24 * 60 * 60_000;
 const LOST = {
@@ -14,9 +14,9 @@ export function createToolCalls(options) {
     const inflight = createInflightCalls(options.inflight);
     const iso = () => new Date(now()).toISOString();
     return {
-        async run(tenantId, key, hash, request) {
+        async run(tenantId, key, hash, request, owner) {
             if (inflight.has(key))
-                return inflight.run(key, hash, () => Promise.resolve(LOST));
+                return inflight.run(key, hash, () => Promise.resolve(LOST), owner);
             const vault = await vaults.open(tenantId);
             const store = vault.store;
             const row = await store.tx((t) => t.toolCrossing(key));
@@ -27,7 +27,7 @@ export function createToolCalls(options) {
                     return row.answer;
                 // Started here a moment ago, or lost with an earlier gateway.
                 if (inflight.has(key))
-                    return inflight.run(key, hash, () => Promise.resolve(LOST));
+                    return inflight.run(key, hash, () => Promise.resolve(LOST), owner);
                 return LOST;
             }
             return inflight.run(key, hash, async (signal) => {
@@ -46,9 +46,9 @@ export function createToolCalls(options) {
                     message: error instanceof Error ? error.message : String(error),
                 }));
                 return answer;
-            });
+            }, owner);
         },
-        cancel: (key) => inflight.cancel(key),
+        cancel: (key, sessionId) => inflight.cancel(key, sessionId),
         close: () => inflight.close(),
         async prune() {
             try {

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

@@ -1,9 +1,16 @@
 import type { ToolGate } from "./tool-gate.js";
+import type { RunTokens } from "../tenant/run-grants.js";
 export interface HttpToolGateOptions {
     /** The gates service, e.g. `http://gateway:4100` (`NYLORUN_GATES_URL`). */
     readonly url: string;
-    /** `NYLORUN_GATES_TOKEN`. */
-    readonly token: string;
+    /**
+     * `NYLORUN_GATES_TOKEN`: core's credential, for deliveries and MCP requests outside a run. A
+     * harness has none (F6.2): its requests outside a run carry the session's last run token, or
+     * nothing, and the gate refuses them.
+     */
+    readonly token?: string;
+    /** The run token of each session an advance of this process owns. Without it, core's only. */
+    readonly runTokens?: RunTokens;
     /** Sent as `Nylorun-Tenant`; the gate checks it against its database's Tenant. */
     readonly tenantId?: string;
     /** How long an MCP request may stay silent. Default `GATE_CLIENT_TIMEOUT_MS`. */

package/dist/gates/tool-client.js

@@ -9,6 +9,12 @@
  *   diagnostic and `resolveEffect` marks a call `uncertain`, as before.
  * - A delivery never throws. A hop that failed before the request was sent is `not_sent`
  *   (the deliverer sends it again, even a tool); one that failed after is `lost`.
+ *
+ * Credentials (F5): a session's MCP requests and keyed cancels carry its run token, read per
+ * request from the advance's grant, and leave the session out of the body: the gate takes it
+ * from the token. Deliveries, pings, and MCP requests made outside a run (closing a pooled
+ * connection after the advance ended) carry core's credential, `NYLORUN_GATES_TOKEN`, and name
+ * the session in the body.
  */
 import { randomUUID } from "node:crypto";
 import { request as httpRequest } from "node:http";
@@ -57,7 +63,9 @@ export function httpToolGate(options) {
             const outgoing = send(url, {
                 method: "POST",
                 headers: {
-                    authorization: `Bearer ${options.token}`,
+                    ...((request.bearer ?? options.token)
+                        ? { authorization: `Bearer ${request.bearer ?? options.token}` }
+                        : {}),
                     "content-type": "application/json",
                     "content-length": payload.byteLength,
                     ...(options.tenantId ? { [TENANT_HEADER]: options.tenantId } : {}),
@@ -88,9 +96,24 @@ export function httpToolGate(options) {
             outgoing.end(payload);
         });
     }
+    /**
+     * The body and credential of a request for `server`'s session: its run token and no session
+     * in the body while an advance holds a grant, core's credential and the session otherwise.
+     */
+    function scoped(server, body) {
+        const token = options.runTokens?.token(server.sessionId);
+        if (!token)
+            return { body: body({ ...server }) };
+        const { sessionId: _, ...unnamed } = server;
+        return { body: body(unnamed), bearer: token };
+    }
     /** The result of an MCP request, or a throw the pool and `resolveEffect` read as before. */
-    async function mcp(path, body, request) {
-        const result = await exchange(path, body, { ...request, timeoutMs });
+    async function mcp(path, scope, request) {
+        const result = await exchange(path, scope.body, {
+            ...request,
+            timeoutMs,
+            ...(scope.bearer ? { bearer: scope.bearer } : {}),
+        });
         if (result.kind === "aborted")
             throw result.reason ?? new Error("aborted");
         if (result.kind !== "answer")
@@ -102,32 +125,43 @@ export function httpToolGate(options) {
             return parsed.result;
         throw mcpError(parsed.error);
     }
-    async function fireAndForget(path, body) {
-        await exchange(path, body, { timeoutMs: SHORT_TIMEOUT_MS });
+    async function fireAndForget(path, scope) {
+        await exchange(path, scope.body, {
+            timeoutMs: SHORT_TIMEOUT_MS,
+            ...(scope.bearer ? { bearer: scope.bearer } : {}),
+        });
     }
     return {
         recovers: true,
         async openMcp(server) {
-            await mcp(MCP_CONNECT_PATH, { server }, {});
+            // The credential is read per request: the connection outlives the advance that opened it.
+            await mcp(MCP_CONNECT_PATH, scoped(server, (named) => ({ server: named })), {});
             const client = {
-                listTools: (params, request) => mcp(MCP_LIST_PATH, { server, ...(params?.cursor ? { cursor: params.cursor } : {}) }, request?.signal ? { signal: request.signal } : {}),
-                callTool: (params, request) => {
-                    const body = {
-                        server: { ...server },
-                        effectId: request?.key ?? randomUUID(),
-                        name: params.name,
-                        arguments: params.arguments,
-                    };
-                    return mcp(TOOL_CALLS_PATH, body, {
-                        ...(request?.signal ? { signal: request.signal } : {}),
-                        ...(request?.key ? { idempotencyKey: request.key } : {}),
-                    });
-                },
+                listTools: (params, request) => mcp(MCP_LIST_PATH, scoped(server, (named) => ({
+                    server: named,
+                    ...(params?.cursor ? { cursor: params.cursor } : {}),
+                })), request?.signal ? { signal: request.signal } : {}),
+                callTool: (params, request) => mcp(TOOL_CALLS_PATH, scoped(server, (named) => ({
+                    server: named,
+                    effectId: request?.key ?? randomUUID(),
+                    name: params.name,
+                    arguments: params.arguments,
+                })), {
+                    ...(request?.signal ? { signal: request.signal } : {}),
+                    ...(request?.key ? { idempotencyKey: request.key } : {}),
+                }),
+            };
+            return {
+                client,
+                close: () => fireAndForget(MCP_CLOSE_PATH, scoped(server, (named) => ({ server: named }))),
             };
-            return { client, close: () => fireAndForget(MCP_CLOSE_PATH, { server }) };
         },
         async cancel(request) {
-            await fireAndForget(`${TOOL_CALLS_PATH}/${encodeURIComponent(request.effectId)}/cancel`, undefined);
+            const token = options.runTokens?.token(request.sessionId);
+            await fireAndForget(`${TOOL_CALLS_PATH}/${encodeURIComponent(request.effectId)}/cancel`, {
+                body: undefined,
+                ...(token ? { bearer: token } : {}),
+            });
         },
         async post(delivery, signal) {
             const result = await exchange(DELIVERIES_PATH, {
@@ -174,7 +208,7 @@ function mcpError(error) {
 function gateRefusal(status, parsed) {
     const message = parsed?.error?.message;
     if (status === 401)
-        return "The tool gate refused this Runtime's token: the runtime and gateway containers must share NYLORUN_GATES_TOKEN";
+        return `The tool gate refused the credential${typeof message === "string" ? `: ${message}` : ""}`;
     return `Tool gate answered ${status}${typeof message === "string" ? `: ${message}` : ""}`;
 }
 function parse(text) {

package/dist/gates/tool-contract.d.ts

@@ -1,8 +1,12 @@
 /**
  * The Tool Gate's wire format (blueprint §12, F4.1): the routes the loop calls on the gates
  * service for remote MCP servers and Action deliveries. Internal, like the model call route
- * (`contract.ts`): same token, same optional Tenant header, not in the published OpenAPI
- * documents.
+ * (`contract.ts`): same optional Tenant header, not in the published OpenAPI documents.
+ *
+ * Credentials (F5). A session's MCP requests carry its run token, and the gate takes the
+ * session from it: `server.sessionId` is then absent (or the token's). Core's credential
+ * (`NYLORUN_GATES_TOKEN`) is accepted too, for requests made outside a run, and then
+ * `server.sessionId` names the session. Deliveries accept core's credential only.
  *
  * Remote MCP. The gate holds the connection and the vault credential; the loop names the
  * server, never a URL or a credential, and the gate finds it in the session's pinned manifest.
@@ -12,7 +16,8 @@
  * - `POST /nylorun/v1/tool-calls` `{server, effectId, name, arguments}`: one
  *   `tools/call`. With an `Idempotency-Key` (the effect id) the call outlives its client and runs
  *   once (G3); a re-send joins it or gets its outcome.
- * - `POST /nylorun/v1/tool-calls/{key}/cancel`: aborts a keyed call; `204` either way.
+ * - `POST /nylorun/v1/tool-calls/{key}/cancel`: aborts a keyed call; `204` either way, `403
+ *   gate_forbidden` for another session's call under a run token.
  * - `POST /nylorun/v1/mcp/close` `{server}`: closes the server's connection; `204`.
  * Each answers `200 {ok: true, result}` or `200 {ok: false, error}`: an MCP failure is an
  * answer, not a gate error. A keyed call whose earlier attempt was lost with the gateway answers
@@ -35,14 +40,14 @@ export declare const MAX_DELIVERY_TIMEOUT_MS: number;
 /** The only headers the gate forwards on a delivery, lower-cased. */
 export declare const DELIVERY_HEADERS: ReadonlySet<string>;
 export declare const McpServerRefSchema: z.ZodObject<{
-    sessionId: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
     agentId: z.ZodOptional<z.ZodString>;
     capabilityId: z.ZodString;
     serverName: z.ZodString;
 }, z.core.$strip>;
 export declare const McpServerBodySchema: z.ZodObject<{
     server: z.ZodObject<{
-        sessionId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
         agentId: z.ZodOptional<z.ZodString>;
         capabilityId: z.ZodString;
         serverName: z.ZodString;
@@ -50,7 +55,7 @@ export declare const McpServerBodySchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const McpListBodySchema: z.ZodObject<{
     server: z.ZodObject<{
-        sessionId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
         agentId: z.ZodOptional<z.ZodString>;
         capabilityId: z.ZodString;
         serverName: z.ZodString;
@@ -59,7 +64,7 @@ export declare const McpListBodySchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const ToolCallBodySchema: z.ZodObject<{
     server: z.ZodObject<{
-        sessionId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
         agentId: z.ZodOptional<z.ZodString>;
         capabilityId: z.ZodString;
         serverName: z.ZodString;

package/dist/gates/tool-contract.js

@@ -1,8 +1,12 @@
 /**
  * The Tool Gate's wire format (blueprint §12, F4.1): the routes the loop calls on the gates
  * service for remote MCP servers and Action deliveries. Internal, like the model call route
- * (`contract.ts`): same token, same optional Tenant header, not in the published OpenAPI
- * documents.
+ * (`contract.ts`): same optional Tenant header, not in the published OpenAPI documents.
+ *
+ * Credentials (F5). A session's MCP requests carry its run token, and the gate takes the
+ * session from it: `server.sessionId` is then absent (or the token's). Core's credential
+ * (`NYLORUN_GATES_TOKEN`) is accepted too, for requests made outside a run, and then
+ * `server.sessionId` names the session. Deliveries accept core's credential only.
  *
  * Remote MCP. The gate holds the connection and the vault credential; the loop names the
  * server, never a URL or a credential, and the gate finds it in the session's pinned manifest.
@@ -12,7 +16,8 @@
  * - `POST /nylorun/v1/tool-calls` `{server, effectId, name, arguments}`: one
  *   `tools/call`. With an `Idempotency-Key` (the effect id) the call outlives its client and runs
  *   once (G3); a re-send joins it or gets its outcome.
- * - `POST /nylorun/v1/tool-calls/{key}/cancel`: aborts a keyed call; `204` either way.
+ * - `POST /nylorun/v1/tool-calls/{key}/cancel`: aborts a keyed call; `204` either way, `403
+ *   gate_forbidden` for another session's call under a run token.
  * - `POST /nylorun/v1/mcp/close` `{server}`: closes the server's connection; `204`.
  * Each answers `200 {ok: true, result}` or `200 {ok: false, error}`: an MCP failure is an
  * answer, not a gate error. A keyed call whose earlier attempt was lost with the gateway answers
@@ -40,7 +45,8 @@ export const DELIVERY_HEADERS = new Set([
     "idempotency-key",
 ]);
 export const McpServerRefSchema = z.object({
-    sessionId: z.string().min(1),
+    /** Required with core's credential; a run token names the session itself. */
+    sessionId: z.string().min(1).optional(),
     agentId: z.string().min(1).optional(),
     capabilityId: z.string().min(1),
     serverName: z.string().min(1),

package/dist/gates/tool-gate.d.ts

@@ -38,6 +38,7 @@ export interface ToolGate {
     /** Stops a keyed MCP call that outlives its caller (a user cancel). Never rejects. */
     cancel?(request: {
         tenantId: string;
+        sessionId: string;
         effectId: string;
     }): Promise<void>;
 }

package/dist/harness/calls.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The calls a harness executes, as pure helpers over what routes them: the Model Gate (or the
+ * Tenant's provider), the MCP pool, the SandboxManager. No store, no record: the session's
+ * routing comes with the run (`TurnStart.routing`).
+ */
+import { type AgentManifest } from "@nylorun/core/define";
+import type { HostEffect } from "@nylorun/harness/run";
+import type { AbortReason } from "@nylorun/core/harness-api";
+import type { ModelProvider } from "../core/provider.js";
+import type { ModelGate } from "../gates/model-gate.js";
+import { type McpPool } from "../mcp/pool.js";
+import { type McpSnapshot } from "../mcp/snapshot.js";
+import type { SandboxManager } from "../sandbox/manager.js";
+/** Where a Tenant's model calls go. */
+export interface ModelRoute {
+    readonly tenantId: string;
+    readonly modelGate: ModelGate;
+    readonly modelProvider: ModelProvider;
+    /** True when the model comes from the Tenant vault selection, served by `modelGate`. */
+    readonly useVaultModel: boolean;
+}
+/** What a session's tool calls are routed by. */
+export interface ToolRouting {
+    readonly rootManifest: AgentManifest;
+    readonly pluginRoots: Readonly<Record<string, string>>;
+    readonly mcpSnapshot?: McpSnapshot;
+    /** The session that owns the tree's sandbox, and the sandbox resource it is attached to. */
+    readonly sandboxOwnerId: string;
+    readonly sandboxId?: string;
+    readonly activeTurnId: string | null;
+    /** Who the sandbox call's events are claimed for: the run's id. */
+    readonly claim?: string;
+}
+/**
+ * Call the model for one effect. A provider failure comes back as a failure outcome
+ * (Model Calls §6), whichever provider serves the call; only an abort throws, and the
+ * advance decides what the abort means.
+ */
+export declare function invokeModel(route: ModelRoute, request: HostEffect, signal: AbortSignal, model?: ModelProvider): Promise<unknown>;
+/**
+ * A signal that follows `signal` only for the abort kinds in `kinds`. An MCP call stops on a
+ * cancel; at the Tool Gate it also stops waiting on a shutdown, since the gate keeps the call
+ * for the next owner. Otherwise a shutdown or a deadline lets the call finish and records it,
+ * so the next advance replays it.
+ */
+export declare function abortOn(signal: AbortSignal, kinds: readonly AbortReason[]): AbortSignal;
+/** True when `request` calls `save_artifact` of the `nylorun.artifacts` capability `manifest` has. */
+export declare function isSaveArtifactCall(manifest: AgentManifest | undefined, request: HostEffect): boolean;
+/** True when `request` calls a tool of a remote (`streamable-http` or `sse`) MCP server. */
+export declare function isRemoteMcpCall(routing: Pick<ToolRouting, "rootManifest" | "mcpSnapshot">, request: HostEffect): boolean;
+export declare function callMcpTool(mcp: McpPool, routing: ToolRouting, request: HostEffect, signal: AbortSignal): Promise<unknown>;
+export declare function callSandboxTool(sandbox: SandboxManager, routing: ToolRouting, request: HostEffect, signal: AbortSignal): Promise<unknown>;

package/dist/harness/calls.js

@@ -0,0 +1,113 @@
+/**
+ * The calls a harness executes, as pure helpers over what routes them: the Model Gate (or the
+ * Tenant's provider), the MCP pool, the SandboxManager. No store, no record: the session's
+ * routing comes with the run (`TurnStart.routing`).
+ */
+import { ARTIFACTS_CAPABILITY_ID, SAVE_ARTIFACT_TOOL } from "@nylorun/core/define";
+import { runAbortKind } from "@nylorun/harness/api";
+import { classifyThrown } from "../model/classify.js";
+import { findServer } from "../mcp/pool.js";
+import { manifestFor, mcpToolOf } from "../mcp/snapshot.js";
+import { sandboxCapabilityOf } from "../sandbox/capability.js";
+/**
+ * Call the model for one effect. A provider failure comes back as a failure outcome
+ * (Model Calls §6), whichever provider serves the call; only an abort throws, and the
+ * advance decides what the abort means.
+ */
+export async function invokeModel(route, request, signal, model) {
+    try {
+        if (model)
+            return await model(request, signal);
+        if (!route.useVaultModel)
+            return await route.modelProvider(request, signal);
+        return await route.modelGate.call({
+            tenantId: route.tenantId,
+            sessionId: request.sessionId,
+            turnId: request.turnId,
+            agentId: request.agentId,
+            effectId: request.effectId,
+            invocationId: String(request.context.invocationId),
+            call: request.input,
+        }, signal);
+    }
+    catch (error) {
+        if (signal.aborted) {
+            // A call that outlives this process stops only when told to: on a user cancel. After a
+            // shutdown or a lost lease the next owner re-sends it and picks up its outcome (P1.2).
+            if (!model && route.useVaultModel && runAbortKind(signal) === "cancel" && route.modelGate.cancel)
+                await route.modelGate.cancel({
+                    tenantId: route.tenantId,
+                    sessionId: request.sessionId,
+                    effectId: request.effectId,
+                });
+            throw error;
+        }
+        return classifyThrown(error);
+    }
+}
+/**
+ * A signal that follows `signal` only for the abort kinds in `kinds`. An MCP call stops on a
+ * cancel; at the Tool Gate it also stops waiting on a shutdown, since the gate keeps the call
+ * for the next owner. Otherwise a shutdown or a deadline lets the call finish and records it,
+ * so the next advance replays it.
+ */
+export function abortOn(signal, kinds) {
+    const controller = new AbortController();
+    const follow = () => {
+        const kind = runAbortKind(signal);
+        if (kind && kinds.includes(kind))
+            controller.abort(signal.reason);
+    };
+    if (signal.aborted)
+        follow();
+    else
+        signal.addEventListener("abort", follow, { once: true });
+    return controller.signal;
+}
+/** True when `request` calls `save_artifact` of the `nylorun.artifacts` capability `manifest` has. */
+export function isSaveArtifactCall(manifest, request) {
+    return (request.kind === "tool" &&
+        request.capabilityId === ARTIFACTS_CAPABILITY_ID &&
+        request.toolName === SAVE_ARTIFACT_TOOL &&
+        manifest?.capabilities.some((capability) => capability.id === ARTIFACTS_CAPABILITY_ID) === true);
+}
+/** True when `request` calls a tool of a remote (`streamable-http` or `sse`) MCP server. */
+export function isRemoteMcpCall(routing, request) {
+    if (request.kind !== "tool")
+        return false;
+    const tool = mcpToolOf(routing.mcpSnapshot, request);
+    if (!tool)
+        return false;
+    const declared = findServer(routing.rootManifest, tool.agentId, tool.capabilityId, tool.serverName);
+    return declared !== undefined && declared.server.type !== "stdio";
+}
+export async function callMcpTool(mcp, routing, request, signal) {
+    const tool = mcpToolOf(routing.mcpSnapshot, request);
+    if (!tool)
+        throw new Error(`MCP tool '${request.toolName ?? ""}' is not in the session snapshot`);
+    return mcp.call({
+        sessionId: request.sessionId,
+        ...(tool.agentId === undefined ? {} : { agentId: tool.agentId }),
+        capabilityId: tool.capabilityId,
+        serverName: tool.serverName,
+        serverToolName: tool.serverToolName,
+        args: request.input,
+        manifest: routing.rootManifest,
+        pluginRoots: routing.pluginRoots,
+        effectId: request.effectId,
+        signal,
+    });
+}
+export async function callSandboxTool(sandbox, routing, request, signal) {
+    const capability = sandboxCapabilityOf(manifestFor(routing.rootManifest, request.agent), request.capabilityId, request.toolName);
+    if (!capability)
+        throw new Error(`'${request.toolName ?? ""}' is not a sandbox tool`);
+    // Agents used as tools share the session's sandbox; the tree declares one sandbox spec.
+    return sandbox.run({
+        id: routing.sandboxOwnerId,
+        activeTurnId: routing.activeTurnId,
+        manifest: routing.rootManifest,
+        ...(routing.sandboxId === undefined ? {} : { sandboxId: routing.sandboxId }),
+        ...(routing.claim === undefined ? {} : { claim: routing.claim }),
+    }, capability, request.toolName, request.input, signal);
+}

package/dist/harness/executors.d.ts

@@ -0,0 +1,22 @@
+import type { HarnessExecutors, HarnessRun, McpRecorder, PreparedRun } from "@nylorun/harness/api";
+import type { ToolGate } from "../gates/tool-gate.js";
+import { type McpPool } from "../mcp/pool.js";
+import type { SandboxManager } from "../sandbox/manager.js";
+import { type ModelRoute, type ToolRouting } from "./calls.js";
+export interface HarnessExecutorsOptions {
+    /** Where model calls go. Read per call: a harness process learns its Tenant at `hello`. */
+    readonly model: ModelRoute;
+    readonly toolGate: Pick<ToolGate, "recovers" | "cancel">;
+    readonly mcp: McpPool;
+    /** The SandboxManager; a harness process creates it once `hello` names the Tenant. */
+    readonly sandbox: () => SandboxManager;
+}
+export declare function harnessExecutors(options: HarnessExecutorsOptions): HarnessExecutors;
+/**
+ * Readies the run's MCP servers (§10.5 step 3): the first segment of a session discovers their
+ * tools and records the snapshot (the first recorded wins); later ones reconnect them and record
+ * what failed. Nothing for a session without MCP servers.
+ */
+export declare function prepareMcp(pool: McpPool, run: HarnessRun, record: McpRecorder): Promise<PreparedRun | undefined>;
+/** A run's routing, as the call helpers take it. Its sandbox events are claimed for the run. */
+export declare function routingOf(run: HarnessRun): ToolRouting;