@nylorun/runtime 0.13.0-beta → 0.15.0-beta

package/dist/gates/mcp-handler.d.ts

@@ -0,0 +1,35 @@
+import { openMcpServer, type McpToolPage } from "../mcp/connect.js";
+import { type McpServerRef } from "../mcp/pool.js";
+import type { Logger } from "../tenant/types.js";
+import type { McpAnswer } from "./tool-contract.js";
+import { type TenantVaults } from "./tenant-vaults.js";
+/** A connection unused this long is closed; the next request opens it again. */
+export declare const GATE_MCP_IDLE_MS: number;
+export interface McpHandlerOptions {
+    readonly vaults: TenantVaults;
+    readonly logger: Logger;
+    /** Default `GATE_MCP_IDLE_MS`. */
+    readonly idleMs?: number;
+    readonly now?: () => number;
+    /** Tests replace how a server is opened. */
+    readonly open?: typeof openMcpServer;
+}
+export interface McpHandler {
+    connect(tenantId: string | undefined, server: McpServerRef): Promise<McpAnswer<null>>;
+    list(tenantId: string | undefined, server: McpServerRef, cursor: string | undefined, signal: AbortSignal): Promise<McpAnswer<McpToolPage>>;
+    /** One `tools/call`; the raw `CallToolResult` on success. */
+    call(tenantId: string | undefined, request: {
+        server: McpServerRef;
+        effectId: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }, signal: AbortSignal): Promise<McpAnswer<Record<string, unknown>>>;
+    close(server: McpServerRef): Promise<void>;
+    /** Closes connections idle past the timeout. */
+    sweep(): Promise<void>;
+    /** Closes every connection (gateway shutdown). */
+    closeAll(): Promise<void>;
+    /** Open connections (tests). */
+    readonly size: number;
+}
+export declare function createMcpHandler(options: McpHandlerOptions): McpHandler;

package/dist/gates/mcp-handler.js

@@ -0,0 +1,142 @@
+import { openMcpServer, } from "../mcp/connect.js";
+import { findServer } from "../mcp/pool.js";
+import { GateRefusal } from "./tenant-vaults.js";
+/** A connection unused this long is closed; the next request opens it again. */
+export const GATE_MCP_IDLE_MS = 15 * 60_000;
+/** The server is not one the session may reach through the gate. */
+class NotDeclared extends Error {
+}
+export function createMcpHandler(options) {
+    const { vaults, logger } = options;
+    const idleMs = options.idleMs ?? GATE_MCP_IDLE_MS;
+    const now = options.now ?? Date.now;
+    const open = options.open ?? openMcpServer;
+    const live = new Map();
+    const opening = new Map();
+    const keyOf = (server) => JSON.stringify([server.sessionId, server.agentId ?? null, server.capabilityId, server.serverName]);
+    /** The declared remote server, from the session's pinned manifest. */
+    async function declared(vault, server) {
+        const session = await vault.session(server.sessionId);
+        if (!session)
+            throw new NotDeclared(`Session ${server.sessionId} not found`);
+        const found = findServer(session.manifest, server.agentId, server.capabilityId, server.serverName);
+        if (!found)
+            throw new NotDeclared(`MCP server '${server.serverName}' is not declared`);
+        if (found.server.type === "stdio")
+            throw new NotDeclared(`MCP server '${server.serverName}' is a stdio server, which runs beside the loop`);
+        return found.server;
+    }
+    async function connection(tenantId, server) {
+        const key = keyOf(server);
+        const existing = live.get(key);
+        if (existing)
+            return existing;
+        let pending = opening.get(key);
+        if (!pending) {
+            pending = (async () => {
+                const vault = await vaults.open(tenantId);
+                const manifest = await declared(vault, server);
+                const connection = await open({
+                    server: manifest,
+                    authorize: (url) => vault.authorizeMcp(server.sessionId, { url, serverName: server.serverName }),
+                    pluginData: "",
+                });
+                const entry = { connection, lastUsedAt: now(), active: 0 };
+                live.set(key, entry);
+                return entry;
+            })().finally(() => opening.delete(key));
+            opening.set(key, pending);
+        }
+        return pending;
+    }
+    async function answer(what, server, run, extra = {}) {
+        const started = now();
+        try {
+            const result = await run();
+            logger.info("mcp_request", { what, ...fields(server), ...extra, ms: now() - started, outcome: "ok" });
+            return { ok: true, result };
+        }
+        catch (error) {
+            const failed = errorOf(error);
+            logger.info("mcp_request", {
+                what,
+                ...fields(server),
+                ...extra,
+                ms: now() - started,
+                outcome: failed.code === undefined ? "failed" : String(failed.code),
+            });
+            return { ok: false, error: failed };
+        }
+    }
+    async function use(tenantId, server, run) {
+        const entry = await connection(tenantId, server);
+        entry.active += 1;
+        try {
+            return await run(entry);
+        }
+        finally {
+            entry.active -= 1;
+            entry.lastUsedAt = now();
+        }
+    }
+    return {
+        connect: (tenantId, server) => answer("connect", server, async () => {
+            await connection(tenantId, server);
+            return null;
+        }),
+        list: (tenantId, server, cursor, signal) => answer("list", server, () => use(tenantId, server, (entry) => entry.connection.client.listTools(cursor ? { cursor } : undefined, { signal }))),
+        call: (tenantId, request, signal) => answer("call", request.server, () => use(tenantId, request.server, (entry) => entry.connection.client.callTool({ name: request.name, arguments: request.arguments }, { signal })), { effect: request.effectId }),
+        async close(server) {
+            const key = keyOf(server);
+            const entry = live.get(key);
+            if (!entry)
+                return;
+            live.delete(key);
+            await entry.connection.close().catch(() => { });
+        },
+        async sweep() {
+            const cutoff = now() - idleMs;
+            const idle = [];
+            for (const [key, entry] of live) {
+                if (entry.active > 0 || entry.lastUsedAt > cutoff)
+                    continue;
+                live.delete(key);
+                idle.push(entry);
+            }
+            await Promise.all(idle.map((entry) => entry.connection.close().catch(() => { })));
+        },
+        async closeAll() {
+            const all = [...live.values()];
+            live.clear();
+            await Promise.all(all.map((entry) => entry.connection.close().catch(() => { })));
+        },
+        get size() {
+            return live.size;
+        },
+    };
+}
+function fields(server) {
+    return {
+        session: server.sessionId,
+        capability: server.capabilityId,
+        server: server.serverName,
+        ...(server.agentId === undefined ? {} : { agent: server.agentId }),
+    };
+}
+/** An error as the loop's `diagnosticFromError` reads it. */
+function errorOf(error) {
+    if (error instanceof GateRefusal)
+        return { message: error.outcome.message };
+    const message = error instanceof Error ? error.message.slice(0, 2000) : String(error);
+    const code = error && typeof error === "object" && "code" in error && typeof error.code === "number"
+        ? error.code
+        : undefined;
+    const credentialIds = error && typeof error === "object" && "credentialIds" in error
+        ? error.credentialIds
+        : undefined;
+    return {
+        message,
+        ...(code === undefined ? {} : { code }),
+        ...(credentialIds === undefined ? {} : { credentialIds: [...credentialIds] }),
+    };
+}

package/dist/gates/meter.d.ts

@@ -0,0 +1,24 @@
+import type { ModelBudgetRow, ModelUsageRow, ModelUsageTotals, SessionStore } from "../store/types.js";
+import type { Logger } from "../tenant/types.js";
+import type { ModelGateOutcome, ModelGateRequest } from "./model-gate.js";
+export interface Meter {
+    /**
+     * Runs `call` for `request` unless a budget's cap is reached, then records its usage in
+     * `store`. A reached cap answers a `budget_exhausted` failure without calling.
+     */
+    call(store: SessionStore, request: ModelGateRequest, call: () => Promise<ModelGateOutcome>): Promise<ModelGateOutcome>;
+}
+export interface MeterOptions {
+    readonly logger: Logger;
+    readonly now?: () => Date;
+}
+export declare function createMeter(options: MeterOptions): Meter;
+/** The ledger row of an outcome that carries usage; undefined for a failure. */
+export declare function usageRow(request: ModelGateRequest, outcome: ModelGateOutcome, at: Date): Omit<ModelUsageRow, "duplicate"> | undefined;
+/**
+ * Why the budget refuses another call, or undefined. Calls in flight count at the scope's
+ * average cost per recorded call.
+ */
+export declare function capReached(budget: Pick<ModelBudgetRow, "scope" | "scopeId" | "period" | "limitUsd" | "limitTokens">, spent: ModelUsageTotals, inflight: number): string | undefined;
+/** When the UTC `period` containing `now` started, as an ISO time. */
+export declare function periodStart(period: "day" | "month", now: Date): string;

package/dist/gates/meter.js

@@ -0,0 +1,165 @@
+/**
+ * The meter (blueprint §15, P1.3). Every model call a gate serves is recorded once in the
+ * Tenant's usage ledger (`model_usage`), by the gate itself: the gates service for the stack,
+ * the in-process gate otherwise. A failed ledger write is logged and never fails the call.
+ *
+ * Before the call the meter checks the Tenant's budgets (hard caps). There is no reservation
+ * (M7): a cap is reached when the scope's recorded spend, plus this gate's calls in flight in
+ * the scope at the scope's average cost per call, reaches its limit. Calls in a turn run one
+ * at a time, so a scope overspends by at most one call per concurrent call. The refusal is a
+ * `budget_exhausted` failure, which the turn does not retry.
+ */
+import { randomUUID } from "node:crypto";
+import { failure } from "../model/classify.js";
+export function createMeter(options) {
+    const now = options.now ?? (() => new Date());
+    /** Calls running through this gate, per Tenant and budget scope. */
+    const inflight = new Map();
+    async function check(store, request) {
+        const at = now();
+        try {
+            return await store.tx(async (t) => {
+                const keys = [];
+                for (const budget of await t.listModelBudgets()) {
+                    const query = scopeOf(budget, request, at);
+                    if (!query)
+                        continue;
+                    const key = `${request.tenantId}|${query.scope}|${query.id ?? "*"}|${query.since ?? ""}`;
+                    keys.push(key);
+                    const reached = capReached(budget, await t.modelUsageTotals(query), inflight.get(key) ?? 0);
+                    if (reached) {
+                        options.logger.warn("model_budget_exhausted", {
+                            tenant: request.tenantId,
+                            session: request.sessionId,
+                            effect: request.effectId,
+                            scope: budget.scope,
+                            ...(budget.scope === "agent" ? { agent: budget.scopeId } : {}),
+                        });
+                        return { keys, refusal: failure("budget_exhausted", reached, false) };
+                    }
+                }
+                return { keys };
+            });
+        }
+        catch (error) {
+            // The caps can't be read: the call goes ahead, as it would without budgets.
+            options.logger.warn("model_budget_check_failed", {
+                tenant: request.tenantId,
+                effect: request.effectId,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            return { keys: [] };
+        }
+    }
+    return {
+        async call(store, request, call) {
+            const { keys, refusal } = await check(store, request);
+            if (refusal)
+                return refusal;
+            // A call counts as in flight until its usage is recorded, so the check never misses it.
+            for (const key of keys)
+                inflight.set(key, (inflight.get(key) ?? 0) + 1);
+            try {
+                const outcome = await call();
+                await record(store, request, outcome);
+                return outcome;
+            }
+            finally {
+                for (const key of keys) {
+                    const left = (inflight.get(key) ?? 1) - 1;
+                    if (left > 0)
+                        inflight.set(key, left);
+                    else
+                        inflight.delete(key);
+                }
+            }
+        },
+    };
+    async function record(store, request, outcome) {
+        const row = usageRow(request, outcome, now());
+        if (!row)
+            return;
+        try {
+            const recorded = await store.tx((t) => t.recordModelUsage(row));
+            if (recorded.duplicate)
+                options.logger.warn("model_usage_duplicate", {
+                    tenant: request.tenantId,
+                    effect: request.effectId,
+                });
+        }
+        catch (error) {
+            options.logger.warn("model_usage_failed", {
+                tenant: request.tenantId,
+                effect: request.effectId,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+}
+/** The ledger row of an outcome that carries usage; undefined for a failure. */
+export function usageRow(request, outcome, at) {
+    if (typeof outcome !== "object" || "kind" in outcome || !outcome.usage)
+        return undefined;
+    const usage = outcome.usage;
+    const producer = producerOf(outcome);
+    const inputTokens = count(usage.inputTokens);
+    const outputTokens = count(usage.outputTokens);
+    return {
+        id: randomUUID(),
+        effectKey: request.effectId,
+        sessionId: request.sessionId,
+        turnId: request.turnId,
+        agentId: request.agentId,
+        provider: producer.provider ?? null,
+        model: producer.model ?? outcome.evidence?.resolvedModel ?? request.call.model?.id ?? null,
+        inputTokens,
+        outputTokens,
+        totalTokens: count(usage.totalTokens) || inputTokens + outputTokens,
+        cachedTokens: count(usage.cachedTokens),
+        cacheWriteTokens: count(usage.cacheWriteTokens),
+        reasoningTokens: count(usage.reasoningTokens),
+        costUsd: Number.isFinite(usage.costUsd) && usage.costUsd > 0 ? usage.costUsd : 0,
+        createdAt: at.toISOString(),
+    };
+}
+/** The ledger rows a budget counts for `request`; undefined when it doesn't apply. */
+function scopeOf(budget, request, at) {
+    const since = budget.period ? { since: periodStart(budget.period, at) } : {};
+    if (budget.scope === "turn")
+        return { scope: "turn", id: request.turnId };
+    if (budget.scope === "agent")
+        return budget.scopeId === request.agentId ? { scope: "agent", id: request.agentId, ...since } : undefined;
+    return { scope: "tenant", ...since };
+}
+/**
+ * Why the budget refuses another call, or undefined. Calls in flight count at the scope's
+ * average cost per recorded call.
+ */
+export function capReached(budget, spent, inflight) {
+    const projected = (total) => total + (spent.calls > 0 ? (inflight * total) / spent.calls : 0);
+    const name = budget.scope === "turn"
+        ? "The turn's cap"
+        : `${budget.scope === "agent" ? `Agent ${budget.scopeId}'s` : "The Tenant's"} ${budget.period === "day" ? "daily" : "monthly"} cap`;
+    const raise = "raise it with PUT /v1/tenant/budgets";
+    if (budget.limitTokens !== null && projected(spent.tokens) >= budget.limitTokens)
+        return `${name} of ${budget.limitTokens} tokens is reached (${spent.tokens} used); ${raise}`;
+    if (budget.limitUsd !== null && projected(spent.costUsd) >= budget.limitUsd)
+        return `${name} of $${budget.limitUsd} is reached ($${spent.costUsd.toFixed(4)} spent); ${raise}`;
+    return undefined;
+}
+/** When the UTC `period` containing `now` started, as an ISO time. */
+export function periodStart(period, now) {
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), period === "day" ? now.getUTCDate() : 1)).toISOString();
+}
+const count = (value) => Number.isFinite(value) && value > 0 ? Math.round(value) : 0;
+/** The provider and model `piModel` records as the candidate's producer. */
+function producerOf(candidate) {
+    const producer = candidate.evidence?.extras?.producer;
+    if (typeof producer !== "object" || producer === null || Array.isArray(producer))
+        return {};
+    const { provider, model } = producer;
+    return {
+        ...(typeof provider === "string" ? { provider } : {}),
+        ...(typeof model === "string" ? { model } : {}),
+    };
+}

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

@@ -0,0 +1,45 @@
+/**
+ * The Model Gate seam (blueprint §15, P1.1). Every vault-backed model call of the loop goes
+ * through one `ModelGate`: the call, who it is for, and nothing else. The gate owns what the
+ * call needs that the loop must not hold: the provider credential, pi-ai, its retries and
+ * idle watchdog, failure classification and scrubbing.
+ *
+ * Two implementations: `inProcessModelGate` (embedding, the ephemeral Runtime, tests) and the
+ * HTTP client of the gates service (the `gateway` container), which keeps the credential out
+ * of the loop process. Both return what `piModel` returns, so the effect journal is the same
+ * either way.
+ */
+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. */
+export interface ModelGateRequest {
+    readonly tenantId: string;
+    readonly sessionId: string;
+    readonly turnId: string;
+    /** The session's agent, for the usage ledger and its budgets (P1.3). */
+    readonly agentId: string;
+    /** The effect's journal id; sent as `Idempotency-Key` (acted on from P1.2). */
+    readonly effectId: string;
+    readonly invocationId: string;
+    readonly call: RuntimeModelCall;
+}
+/** A model candidate or a failure outcome: exactly what `piModel` returns. */
+export type ModelGateOutcome = Awaited<ReturnType<RuntimeModelAdapter>>;
+export interface ModelGate {
+    /**
+     * Calls the model. A provider or gate failure comes back as a failure outcome; only an abort
+     * of `signal` throws, so the advance decides what the abort means.
+     */
+    call(request: ModelGateRequest, signal: AbortSignal): Promise<ModelGateOutcome>;
+    /**
+     * True when a call outlives the caller's process (the gates service, P1.2): after a takeover
+     * or a shutdown, re-sending the journaled request joins the call or returns its outcome
+     * instead of calling the provider again. The in-process gate dies with the loop.
+     */
+    readonly recovers?: boolean;
+    /**
+     * 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>;
+}

package/dist/gates/model-gate.js

@@ -0,0 +1 @@
+export {};

package/dist/gates/tenant-vaults.d.ts

@@ -0,0 +1,64 @@
+/**
+ * What the gates service opens of the Tenant: its vault's host model, and nothing else. The
+ * full Tenant (`TenantRuntime.open`) migrates its database, creates its key file and starts
+ * its services; the gate does none of that. The database holds one Tenant (tenancy.md §1):
+ * the gate reads which one from it, refuses a database whose Tenant schema isn't at this
+ * build's version (the Runtime migrates it when it opens the Tenant) and never creates a vault
+ * key. The vault is opened once and kept.
+ */
+import type { Credential } from "@earendil-works/pi-ai";
+import type { ModelFailureOutcome } from "@nylorun/core/define";
+import type { PostgresClient } from "../store/postgres/connect.js";
+import { VaultService, type AuthorizeResult, type HostModelSecret } from "../vault/service.js";
+import type { SessionStore } from "../store/types.js";
+import type { Session } from "../tenant/context.js";
+import { type Keys } from "../keys/keys.js";
+/** The Tenant, as a model call needs it. */
+export interface TenantVault {
+    readonly tenantId: string;
+    /** The Tenant's store, for the usage ledger (P1.3). */
+    readonly store: SessionStore;
+    /** The Tenant's home: secrets found there are redacted from failure messages. */
+    readonly root: string;
+    readHostModel(): Promise<HostModelSecret | undefined>;
+    /** Writes back a credential pi-ai refreshed (OAuth). */
+    writeHostCredential(credential: Credential): Promise<void>;
+    /** A session, for the remote MCP servers its pinned manifest declares (F4.1). */
+    session(sessionId: string): Promise<Session | undefined>;
+    /**
+     * The vault authorization of one request to a session's remote MCP server: its credential
+     * from the session's attached vaults, refreshed when due (F4.1).
+     */
+    authorizeMcp(sessionId: string, request: {
+        url: string;
+        serverName: string;
+    }): Promise<AuthorizeResult>;
+    /** Vault writes and token signing with the Tenant's vault key (the keys service, F4.2). */
+    keys(): Keys;
+}
+export interface TenantVaults {
+    /**
+     * Opens the Tenant's vault, or rejects with a `GateRefusal`. `tenantId`, when the caller
+     * names one, must be the database's Tenant.
+     */
+    open(tenantId?: string): Promise<TenantVault>;
+}
+/** A call the gate refuses before the provider is called; it answers with `outcome`. */
+export declare class GateRefusal extends Error {
+    readonly outcome: ModelFailureOutcome;
+    constructor(outcome: ModelFailureOutcome);
+}
+export interface TenantVaultsOptions {
+    readonly sql: PostgresClient;
+    /** The Host root; the gate reads `keys/vault-kek` and `tenant/home` under it. */
+    readonly hostRoot: string;
+}
+export declare function createTenantVaults(options: TenantVaultsOptions): TenantVaults;
+/**
+ * A request to a session's remote MCP server, authorized from the session's attached vaults:
+ * what the loop did in its own process before F4.1 (`tenant/effects.ts` `authorize`).
+ */
+export declare function authorizeSessionMcp(credentials: VaultService, session: (sessionId: string) => Promise<Session | undefined>, sessionId: string, request: {
+    url: string;
+    serverName: string;
+}): Promise<AuthorizeResult>;

package/dist/gates/tenant-vaults.js

@@ -0,0 +1,94 @@
+import { isTenantId } from "@nylorun/core/compatibility";
+import { failure } from "../model/classify.js";
+import { database } from "../store/postgres/db.js";
+import { expectedSchemaVersion, readSchemaVersion } from "../store/postgres/migrate.js";
+import { readTenantEnvelope } from "../store/postgres/tenant.js";
+import { createPostgresSessionStore } from "../store/postgres/store.js";
+import { tenantPaths } from "../tenant/paths.js";
+import { readVaultKek } from "../vault/kek.js";
+import { HostModelVault } from "../vault/host-model.js";
+import { VaultService } from "../vault/service.js";
+import { inProcessKeys } from "../keys/keys.js";
+import { SigningKeys } from "../tenant/signing-keys.js";
+/** A call the gate refuses before the provider is called; it answers with `outcome`. */
+export class GateRefusal extends Error {
+    outcome;
+    constructor(outcome) {
+        super(outcome.message);
+        this.outcome = outcome;
+        this.name = "GateRefusal";
+    }
+}
+export function createTenantVaults(options) {
+    const { sql, hostRoot } = options;
+    let opened;
+    function build(tenantId) {
+        const paths = tenantPaths(hostRoot);
+        const store = createPostgresSessionStore({ sql, tenantId });
+        let kek;
+        const readKek = () => {
+            kek ??= readVaultKek({ vaultKekPath: paths.kek });
+            if (!kek)
+                throw new GateRefusal(failure("auth", "The Tenant's vault key is missing on the gateway container; check that it mounts the Host's keys directory, which `nylorun start` creates", false));
+            return kek;
+        };
+        const vault = new HostModelVault({ store, kek: readKek });
+        const credentials = new VaultService({ store, kek: readKek, fetch: globalThis.fetch });
+        const keys = inProcessKeys({
+            store,
+            vault: credentials,
+            signingKeys: new SigningKeys({ tenantId, kek: readKek }),
+            kek: readKek,
+        });
+        const session = (sessionId) => store.tx((t) => t.get("sessions", sessionId));
+        return {
+            tenantId,
+            store,
+            root: paths.home,
+            readHostModel: () => vault.readHostModel(),
+            writeHostCredential: (credential) => vault.updateHostCredential(credential),
+            session,
+            authorizeMcp: (sessionId, request) => authorizeSessionMcp(credentials, session, sessionId, request),
+            keys: () => keys,
+        };
+    }
+    /** The database's Tenant, once its schema is at this build's version. */
+    async function load() {
+        const version = await readSchemaVersion(database(sql));
+        const expected = expectedSchemaVersion();
+        if (version === undefined || version === 0)
+            throw new GateRefusal(failure("transient", "The Tenant's database is not migrated yet; the Runtime does that when it starts", true));
+        if (version !== expected)
+            throw new GateRefusal(failure("transient", `The Tenant is at schema version ${version}; the gateway serves version ${expected}`, version < expected));
+        const envelope = await readTenantEnvelope(sql).catch(() => undefined);
+        if (!envelope)
+            throw new GateRefusal(failure("transient", "The database holds no Tenant yet; the Runtime creates it when it starts", true));
+        return build(envelope.id);
+    }
+    return {
+        async open(tenantId) {
+            if (tenantId !== undefined && !isTenantId(tenantId))
+                throw new GateRefusal(failure("invalid_request", "Not a Tenant id", false));
+            opened ??= await load();
+            if (tenantId !== undefined && tenantId !== opened.tenantId)
+                throw new GateRefusal(failure("invalid_request", `Tenant ${tenantId} is not this installation's Tenant`, false));
+            return opened;
+        },
+    };
+}
+/**
+ * A request to a session's remote MCP server, authorized from the session's attached vaults:
+ * what the loop did in its own process before F4.1 (`tenant/effects.ts` `authorize`).
+ */
+export async function authorizeSessionMcp(credentials, session, sessionId, request) {
+    const found = await session(sessionId);
+    if (!found)
+        throw new Error(`Session ${sessionId} not found`);
+    return credentials.authorize({
+        sessionId,
+        vaultIds: found.vaultIds ?? [],
+        credentialSelections: found.credentialSelections ?? [],
+        url: request.url,
+        serverName: request.serverName,
+    });
+}

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

@@ -0,0 +1,51 @@
+/**
+ * Keyed remote MCP calls in the gates service (F4.1 G3). A call sent with an `Idempotency-Key`
+ * (the loop's effect id) runs once:
+ *
+ * - While it runs, and for 30 minutes after, a re-send joins it or gets its answer from memory
+ *   (`inflight.ts`), as model calls do (P1.2). So a runtime that dies or shuts down mid-call
+ *   leaves nothing `uncertain`: the next owner re-sends the call and gets its answer.
+ * - The gate also writes a `tool_crossings` row before it calls the server, and the answer
+ *   after. A re-send that finds the answer gets it. One that finds a row without an answer,
+ *   for a call this gateway is not running, was lost with an earlier gateway (a restart mid
+ *   call): it answers `uncertain`, because the call may have run, and is never run again.
+ *
+ * A cancel aborts the call and leaves its row without an answer. Settled rows are deleted a day
+ * later (`prune`).
+ */
+import type { McpServerRef } from "../mcp/pool.js";
+import type { Logger } from "../tenant/types.js";
+import { type InflightCallsOptions } from "./inflight.js";
+import type { McpHandler } from "./mcp-handler.js";
+import type { TenantVaults } from "./tenant-vaults.js";
+import type { McpAnswer } from "./tool-contract.js";
+/** How long a settled crossing is kept. */
+export declare const TOOL_CROSSING_TTL_MS: number;
+export type ToolCallAnswer = McpAnswer<Record<string, unknown>>;
+export interface ToolCallRequest {
+    readonly server: McpServerRef;
+    readonly effectId: string;
+    readonly name: string;
+    readonly arguments: Record<string, unknown>;
+}
+export interface ToolCalls {
+    /**
+     * Runs, joins or answers the call under `key`. Rejects with `InflightConflict` when a
+     * different request already ran under it.
+     */
+    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;
+    /** Aborts every running call (gateway shutdown). */
+    close(): void;
+    /** Deletes crossings settled more than `TOOL_CROSSING_TTL_MS` ago. */
+    prune(): Promise<void>;
+}
+export interface ToolCallsOptions {
+    readonly vaults: TenantVaults;
+    readonly mcp: McpHandler;
+    readonly logger: Logger;
+    readonly inflight?: InflightCallsOptions;
+    readonly now?: () => number;
+}
+export declare function createToolCalls(options: ToolCallsOptions): ToolCalls;