@wardby/cli 0.7.0 → 0.9.0

package/dist/providers/coding-proxy/run-step-forwarder.js

@@ -0,0 +1,206 @@
+/**
+ * Hands coding runs' steps from the proxy to the control plane's run-steps listener
+ * (`POST <WARDBY_RUN_STEPS_URL>/internal/run-steps`, `Authorization: Bearer <the run capability>`).
+ * The proxy forwards raw step text over the authenticated in-cluster listener; the control plane
+ * redacts by exact value before anything is stored. Because the body is raw, this class never logs,
+ * echoes, or puts into an error any part of the body, the step text, or the capability: log lines
+ * carry a fixed reason and a count only.
+ *
+ * A bounded in-memory queue, drained one POST at a time off the relay path: a full queue or a slow
+ * or failing control plane drops steps and never delays a model request.
+ */
+import { logger } from "../../core/logger.js";
+import { MAX_RESULTS_PER_POST, MAX_RUN_STEPS_POST_BYTES, MAX_STEPS_PER_POST, RUN_STEPS_INGRESS_PATH, } from "../../core/run-steps/types.js";
+const forwarderLog = logger.child({ module: "coding-proxy" });
+export const MAX_FORWARD_QUEUE = 256;
+/** A queue holds at most this many bytes of (estimated) serialized submissions. */
+export const MAX_FORWARD_QUEUE_BYTES = 8 * 1024 * 1024;
+/** Margin over the listener's 15 s request limit (its write can take lock wait 5 s + transaction 10 s). */
+const DEFAULT_TIMEOUT_MS = 20_000;
+const DEFAULT_FLUSH_TIMEOUT_MS = 5_000;
+/** The envelope around the arrays, with slack for the runId. */
+const ENVELOPE_SLACK_BYTES = 1024;
+/** A cheap upper-ish bound on a batch's serialized size, with no stringify on the caller's stack. */
+function estimate(batch) {
+    let bytes = ENVELOPE_SLACK_BYTES;
+    for (const step of batch.steps) {
+        bytes += step.text.length * 3 + step.callId.length * 3 + 256;
+        if (step.kind === "tool")
+            bytes += (step.input?.length ?? 0) * 3;
+    }
+    for (const result of batch.results)
+        bytes += 128 + (result.output?.length ?? 0) * 3;
+    return bytes;
+}
+/** Splits by count and by serialized UTF-8 size, so no body passes MAX_RUN_STEPS_POST_BYTES. */
+function split(batch, runId) {
+    const parts = [];
+    const base = ENVELOPE_SLACK_BYTES + Buffer.byteLength(runId);
+    let steps = [];
+    let size = base;
+    for (const step of batch.steps) {
+        const bytes = Buffer.byteLength(JSON.stringify(step)) + 1;
+        if (steps.length > 0 && (steps.length >= MAX_STEPS_PER_POST || size + bytes > MAX_RUN_STEPS_POST_BYTES)) {
+            parts.push({ steps, results: [] });
+            steps = [];
+            size = base;
+        }
+        steps.push(step);
+        size += bytes;
+    }
+    if (steps.length > 0)
+        parts.push({ steps, results: [] });
+    let results = [];
+    let resultBytes = base;
+    for (const result of batch.results) {
+        const bytes = Buffer.byteLength(JSON.stringify(result)) + 1;
+        if (results.length > 0 &&
+            (results.length >= MAX_RESULTS_PER_POST || resultBytes + bytes > MAX_RUN_STEPS_POST_BYTES)) {
+            parts.push({ steps: [], results });
+            results = [];
+            resultBytes = base;
+        }
+        results.push(result);
+        resultBytes += bytes;
+    }
+    if (results.length > 0)
+        parts.push({ steps: [], results });
+    return parts;
+}
+export class RunStepForwarder {
+    options;
+    queue = [];
+    queueBytes = 0;
+    draining;
+    scheduled = false;
+    closed = false;
+    inflight;
+    dropped = 0;
+    loggedReasons = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    submit(capability, runId, batch) {
+        try {
+            if (this.closed)
+                return this.drop("closed");
+            const size = estimate(batch);
+            if (this.queue.length >= (this.options.maxQueue ?? MAX_FORWARD_QUEUE) ||
+                this.queueBytes + size > (this.options.maxQueueBytes ?? MAX_FORWARD_QUEUE_BYTES)) {
+                return this.drop("queue_full");
+            }
+            this.queue.push({ capability, runId, batch, estimate: size });
+            this.queueBytes += size;
+            this.kick();
+        }
+        catch {
+            this.drop("submit_failed");
+        }
+    }
+    /** Resolves once everything submitted so far was posted or dropped, or after a bound. Never rejects. */
+    async flush() {
+        let timer;
+        const bound = new Promise((resolve) => {
+            timer = setTimeout(resolve, this.options.flushTimeoutMs ?? DEFAULT_FLUSH_TIMEOUT_MS);
+            timer.unref();
+        });
+        const settled = (async () => {
+            while (this.draining || this.scheduled)
+                await (this.draining ?? new Promise((r) => setImmediate(r)));
+        })().catch(() => undefined);
+        await Promise.race([settled, bound]);
+        clearTimeout(timer);
+    }
+    /** Stops accepting, waits at most the flush bound, then drops what is left and aborts the in-flight POST. */
+    async close() {
+        this.closed = true;
+        await this.flush();
+        const left = this.queue.length;
+        this.queue = [];
+        this.queueBytes = 0;
+        for (let n = 0; n < left; n += 1)
+            this.drop("closed");
+        this.inflight?.abort();
+    }
+    kick() {
+        if (this.draining || this.scheduled || this.queue.length === 0)
+            return;
+        this.scheduled = true;
+        // Off the caller's stack: the first serialization must not run on the relay path.
+        setImmediate(() => {
+            this.scheduled = false;
+            if (this.draining || this.queue.length === 0)
+                return;
+            this.draining = this.drain().finally(() => {
+                this.draining = undefined;
+                this.kick();
+            });
+        });
+    }
+    async drain() {
+        for (let next = this.queue.shift(); next; next = this.queue.shift()) {
+            this.queueBytes -= next.estimate;
+            if (this.closed) {
+                this.drop("closed");
+                continue;
+            }
+            let bodies;
+            try {
+                bodies = split(next.batch, next.runId).map((part) => JSON.stringify({ runId: next.runId, ...part }));
+            }
+            catch {
+                this.drop("serialize_failed");
+                continue;
+            }
+            for (const body of bodies) {
+                if (this.closed)
+                    this.drop("closed");
+                else
+                    await this.post(next.capability, body);
+            }
+        }
+    }
+    /**
+     * The capability goes in the Authorization header only. The response body is never read, and a
+     * failure is logged by a fixed reason: an error's or a response's text never reaches a log line.
+     */
+    async post(capability, body) {
+        const controller = new AbortController();
+        this.inflight = controller;
+        const timer = setTimeout(() => controller.abort(), this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        timer.unref();
+        try {
+            const response = await (this.options.fetchImpl ?? fetch)(`${this.options.url}${RUN_STEPS_INGRESS_PATH}`, {
+                method: "POST",
+                headers: { authorization: `Bearer ${capability}`, "content-type": "application/json" },
+                body,
+                redirect: "error",
+                signal: controller.signal,
+            });
+            await response.body?.cancel().catch(() => undefined);
+            if (!response.ok)
+                this.drop(`http_${response.status}`);
+        }
+        catch {
+            this.drop(this.closed ? "closed" : controller.signal.aborted ? "timeout" : "unreachable");
+        }
+        finally {
+            clearTimeout(timer);
+            if (this.inflight === controller)
+                this.inflight = undefined;
+        }
+    }
+    drop(reason) {
+        this.dropped += 1;
+        const first = !this.loggedReasons.has(reason);
+        this.loggedReasons.add(reason);
+        if (first || this.dropped % 100 === 0) {
+            try {
+                (this.options.log ?? forwarderLog).info({ event: "run_steps.forward_dropped", reason, droppedParts: this.dropped }, "coding proxy: run steps not delivered to the control plane");
+            }
+            catch {
+                // logging must never break the relay
+            }
+        }
+    }
+}

package/dist/providers/coding-proxy/runtime.d.ts

@@ -14,6 +14,19 @@ import type { ProxyAuditSink } from "./types.js";
  *  JSON). Exported so its header-mapping can be unit-tested directly,
  *  without needing a live upstream. */
 export declare function createRegistryUpstream(pinned: typeof globalThis.fetch): UpstreamFetch;
+/**
+ * WARDBY_MCP_GATEWAY_URL: the native gateway's base URL, which the /mcp route forwards to (its
+ * /coding-mcp route). Unset or empty: /mcp answers 503 mcp_unavailable. Anything but an http(s) URL
+ * without credentials, query or fragment stops start-up (the value is not echoed).
+ */
+export declare function loadMcpGatewayUrl(env: NodeJS.ProcessEnv): string | undefined;
+/**
+ * WARDBY_RUN_STEPS_URL: the control plane's run-steps listener (WARDBY_RUN_STEPS_LISTEN on the
+ * server), which the proxy posts coding runs' steps to. Unset or empty: coding runs record no steps.
+ * Anything but an http(s) origin without credentials, path, query or fragment stops start-up (the
+ * value is not echoed, so a credential in it never reaches a log).
+ */
+export declare function loadRunStepsUrl(env: NodeJS.ProcessEnv): string | undefined;
 export interface CodingProxyRuntimeOptions {
     db: PrismaClient;
     /** The package registry's own client, so its traffic (many concurrent

package/dist/providers/coding-proxy/runtime.js

@@ -1,6 +1,7 @@
 import { loadDependencyCacheConfig } from "../../config/dependency-cache.js";
 import { createSimulatorModelFetch, createSimulatorRegistryFetch, startupTestSimulators, } from "../../config/test-simulators.js";
 import { logger } from "../../core/logger.js";
+import { loadRunStepsLevel } from "../../core/run-steps/config.js";
 import { REGISTRY_ADAPTERS } from "../../coding/registry/adapters.js";
 import { CODING_PROXY_ALIAS, CODING_PROXY_DENY_PORT, CODING_PROXY_PORT } from "../jobs/docker-isolation.js";
 import { createBlobStore } from "../storage/index.js";
@@ -10,9 +11,11 @@ import { ModelRequestSeal } from "./dependency-cache/model-request-seal.js";
 import { DependencyCacheService } from "./dependency-cache/service.js";
 import { startDenyPortListener } from "./deny-port.js";
 import { EnvironmentCredentialResolver } from "./environment-credentials.js";
+import { createMcpRoute } from "./mcp-route.js";
 import { createMockUpstream, mockUpstreamFromEnv } from "./mock-upstream.js";
 import { CodingProxy } from "./proxy.js";
 import { PrismaProxyLedger } from "./prisma-ledger.js";
+import { RunStepForwarder } from "./run-step-forwarder.js";
 import { OsvAudit } from "./registry/audit.js";
 import { PrismaRegistryStore } from "./registry/prisma-store.js";
 import { DEFAULT_PLAN_MAX_ENTRIES, DEFAULT_PLAN_TIMEOUT_MS } from "./registry/plan.js";
@@ -44,6 +47,60 @@ export function createRegistryUpstream(pinned) {
         },
     });
 }
+/**
+ * WARDBY_MCP_GATEWAY_URL: the native gateway's base URL, which the /mcp route forwards to (its
+ * /coding-mcp route). Unset or empty: /mcp answers 503 mcp_unavailable. Anything but an http(s) URL
+ * without credentials, query or fragment stops start-up (the value is not echoed).
+ */
+export function loadMcpGatewayUrl(env) {
+    const value = env.WARDBY_MCP_GATEWAY_URL?.trim();
+    if (!value)
+        return undefined;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        url = undefined;
+    }
+    if (!url ||
+        (url.protocol !== "http:" && url.protocol !== "https:") ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash) {
+        throw new Error("WARDBY_MCP_GATEWAY_URL must be an http(s) URL without credentials, query or fragment");
+    }
+    return url.href.replace(/\/+$/, "");
+}
+/**
+ * WARDBY_RUN_STEPS_URL: the control plane's run-steps listener (WARDBY_RUN_STEPS_LISTEN on the
+ * server), which the proxy posts coding runs' steps to. Unset or empty: coding runs record no steps.
+ * Anything but an http(s) origin without credentials, path, query or fragment stops start-up (the
+ * value is not echoed, so a credential in it never reaches a log).
+ */
+export function loadRunStepsUrl(env) {
+    const value = env.WARDBY_RUN_STEPS_URL?.trim();
+    if (!value)
+        return undefined;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        url = undefined;
+    }
+    if (!url ||
+        (url.protocol !== "http:" && url.protocol !== "https:") ||
+        url.username ||
+        url.password ||
+        url.pathname !== "/" ||
+        url.search ||
+        url.hash) {
+        throw new Error("WARDBY_RUN_STEPS_URL must be an http(s) URL without credentials, path, query or fragment");
+    }
+    return url.origin;
+}
 /** Starts the trusted proxy with the fixed worker-only Docker endpoint, plus the deny port the enforcement witness probes. */
 export async function startConfiguredCodingProxy(options) {
     const env = options.env ?? process.env;
@@ -57,6 +114,12 @@ export async function startConfiguredCodingProxy(options) {
     const audit = mock
         ? (event) => options.audit?.({ ...event, mockUpstream: true })
         : options.audit;
+    // Throws on an invalid setting, before anything listens.
+    const mcpGatewayUrl = loadMcpGatewayUrl(env);
+    // Throws on an invalid setting, before anything listens.
+    const runStepsUrl = loadRunStepsUrl(env);
+    // Throws on an invalid WARDBY_RUN_STEPS. At off no step text leaves the proxy.
+    const runStepsCeiling = loadRunStepsLevel(env);
     // Throws (test_simulators_refused) on any refusal, before anything listens.
     const simulators = startupTestSimulators("coding-proxy", env);
     const buildPinnedFetch = options.createPinnedFetch ?? createPinnedProxyFetch;
@@ -123,8 +186,13 @@ export async function startConfiguredCodingProxy(options) {
         logger.warn({ module: "coding-proxy-runtime", event: "proxy.dependency_cache_no_blob_store" }, "coding proxy: WARDBY_DEPENDENCY_CACHE=true but no BLOB_STORE is configured; the dependency cache is off");
     }
     const seal = modelRequestSeal;
+    // Coding runs' steps go to the control plane only when WARDBY_RUN_STEPS_URL is set and
+    // WARDBY_RUN_STEPS is not off; otherwise no
+    // submitter is passed and the proxy does no step extraction.
+    const steps = runStepsUrl && runStepsCeiling !== "off" ? new RunStepForwarder({ url: runStepsUrl }) : undefined;
+    const ledger = new PrismaProxyLedger(options.db);
     const proxy = new CodingProxy({
-        ledger: new PrismaProxyLedger(options.db),
+        ledger,
         credentials: new EnvironmentCredentialResolver(env),
         audit,
         // WARDBY_TEST_SIMULATORS (test only; refused alongside the mock upstream): the scripted model,
@@ -136,6 +204,8 @@ export async function startConfiguredCodingProxy(options) {
                 : {}),
         // The run's first model request closes its dependency cache (no-op for a run with it off).
         ...(seal ? { onModelRequest: (runId) => seal.onModelRequest(runId) } : {}),
+        ...(steps ? { steps } : {}),
+        runStepsCeiling,
     });
     const startServer = options.startServer ?? startCodingProxyServer;
     let server;
@@ -146,11 +216,13 @@ export async function startConfiguredCodingProxy(options) {
             expectedHost: `${CODING_PROXY_ALIAS}:${CODING_PROXY_PORT}`,
             registry,
             ...(dependencyCache ? { dependencyCache } : {}),
+            mcp: createMcpRoute({ ledger, gatewayUrl: mcpGatewayUrl }),
             onRequest: options.onRequest,
         });
     }
     catch (error) {
         eviction?.stop();
+        await steps?.close();
         throw error;
     }
     let deny;
@@ -161,15 +233,26 @@ export async function startConfiguredCodingProxy(options) {
         // A proxy without its witness must not stay up: the launcher's gate would never be able to
         // prove a policy is enforced, and every launch would fail at the gate instead of at startup.
         eviction?.stop();
-        await server.close();
+        try {
+            await server.close();
+        }
+        finally {
+            await steps?.close();
+        }
         throw error;
     }
     return {
         port: server.port,
         close: async () => {
             eviction?.stop();
-            await deny.close();
-            await server.close();
+            try {
+                await deny.close();
+                await server.close();
+            }
+            finally {
+                // Last: requests are done, so this is the final chance to hand over queued steps (bounded).
+                await steps?.close();
+            }
         },
     };
 }

package/dist/providers/coding-proxy/server.d.ts

@@ -1,3 +1,4 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
 import type { ProxyAuditEvent } from "./types.js";
 import { type CodingProxy } from "./proxy.js";
 import { type RegistryService } from "./registry/service.js";
@@ -19,6 +20,8 @@ export interface CodingProxyServerConfig {
     dependencyCache?: Pick<DependencyCacheService, "handle" | "uploadMs">;
     /** Time to receive a whole request (default HTTP_LIMITS.requestMs); a cache upload gets its upload window instead. */
     requestMs?: number;
+    /** The worker's MCP route (`/mcp`, createMcpRoute); absent, /mcp is not found. */
+    mcp?: (request: IncomingMessage, response: ServerResponse) => Promise<void>;
     onRequest?: (event: {
         protocol: ProxyProtocol | "other";
         status: number;

package/dist/providers/coding-proxy/server.js

@@ -6,6 +6,7 @@ import { logger } from "../../core/logger.js";
 import { CodingProxyError, PROXY_MAX_BODY_BYTES } from "./proxy.js";
 import { RegistryError } from "../../coding/registry/types.js";
 import { MAX_PLAN_BODY_BYTES } from "./registry/service.js";
+import { MCP_ROUTE_PATH } from "./mcp-route.js";
 const proxyLog = logger.child({ module: "coding-proxy" });
 /**
  * Writes a proxy audit event to the operator log. The events carry ids,
@@ -266,6 +267,15 @@ export async function startCodingProxyServer(proxy, config) {
                 });
                 return;
             }
+            if (request.url === MCP_ROUTE_PATH || request.url?.startsWith(`${MCP_ROUTE_PATH}?`)) {
+                if (!config.mcp) {
+                    closeIfBodyUnread(request, response);
+                    sendError(response, 404, "not_found");
+                    return;
+                }
+                await config.mcp(request, response);
+                return;
+            }
             if (request.method === "HEAD" && request.url === "/api/hello") {
                 response.writeHead(200, { "cache-control": "no-store" }).end();
                 return;

package/dist/providers/coding-proxy/types.d.ts

@@ -1,6 +1,8 @@
 import { type CatalogEntry } from "../llm/catalog-types.js";
+import type { RunStepsLevel } from "../../core/run-steps/config.js";
 import type { ModelPricing } from "../llm/pricing-core.js";
 import type { ProxyRefusalDetails } from "../../core/budget-events.js";
+import type { McpToolPin } from "../../core/mcp-tools.js";
 export type ProxySessionStatus = "active" | "cancelled";
 export type ProxyRequestStatus = "reserved" | "completed" | "released" | "uncertain";
 export type ProxyProtocol = "openai-responses" | "anthropic-messages";
@@ -46,6 +48,14 @@ export interface ProxySession {
     upstreamFailure?: string | null;
     /** The run's catalog entry, copied at session creation; null on sessions from before the catalog. */
     terms?: ProxyModelTerms | null;
+    /** The run's pinned MCP tools (no URLs or secrets); null when the run has none, and on older sessions. */
+    mcpTools: McpToolPin[] | null;
+    /** SHA-256 (base64url) of the run's MCP token; null when the run has no MCP tools. */
+    mcpTokenHash: string | null;
+    /** The run's MCP tools/call count so far. */
+    mcpCallCount: number;
+    /** The run's Run.runStepsLevel, copied at session creation; null on sessions from before run steps detail. */
+    runStepsLevel: RunStepsLevel | null;
 }
 export interface ProxyRequest {
     id: string;
@@ -89,6 +99,12 @@ export interface CreateProxySessionInput {
     budgetUsd: number;
     registryTokenHash: string;
     terms?: ProxyModelTerms;
+    /** The run's pinned MCP tools; set together with mcpTokenHash, and only when there is at least one. */
+    mcpTools?: McpToolPin[];
+    /** SHA-256 (base64url) of the run's MCP token (mcpTokenHash in src/coding/mcp-token.ts). */
+    mcpTokenHash?: string;
+    /** The run's level, fixed at dispatch; absent counts as summary. */
+    runStepsLevel?: RunStepsLevel;
 }
 export interface ReserveProxyRequestInput {
     id: string;
@@ -122,6 +138,8 @@ export type ReserveProxyRequestResult = {
 export interface ProxyLedger {
     createSession(input: CreateProxySessionInput): Promise<void>;
     findSessionByCapabilityHash(capabilityHash: string): Promise<ProxySession | null>;
+    /** The session whose MCP token hashes to this; any status (the caller checks it is active and in time). */
+    findSessionByMcpTokenHash(mcpTokenHash: string): Promise<ProxySession | undefined>;
     reserve(input: ReserveProxyRequestInput): Promise<ReserveProxyRequestResult>;
     complete(requestId: string, usage: ProxyUsage, actualCostUsd: number, upstreamStatus: number): Promise<ProxyRequest>;
     release(requestId: string, upstreamStatus: number): Promise<void>;

package/dist/providers/engine/types.d.ts

@@ -117,9 +117,35 @@ export interface EngineRunContext {
     onText?: (delta: string) => void;
     /** Called after each model turn that completed without error; the engine awaits it. */
     onProgress?: (progress: EngineProgress) => Promise<void>;
+    /**
+     * Receives each model turn's text and tool calls, then the turn's tool results, as the engine saw
+     * them. The runner turns them into the run's steps (src/core/run-steps); the engine never imports
+     * that code, so the sandbox worker image does not ship it. Synchronous and not awaited. A replay
+     * delivers the same call ids again; the writer drops the repeats.
+     */
+    onTurn?: (event: EngineTurnEvent) => void;
     /** See StepRunner. Optional; the in-process executor leaves it unset. */
     step?: StepRunner;
 }
+/** What EngineRunContext.onTurn receives: a turn's output, then (if it called tools) their results in call order. */
+export type EngineTurnEvent = {
+    kind: "turn";
+    /** 1-based turn number. */
+    turn: number;
+    text: string;
+    toolCalls: readonly {
+        id: string;
+        name: string;
+        argsJson: string;
+    }[];
+} | {
+    kind: "results";
+    turn: number;
+    toolCalls: readonly {
+        id: string;
+    }[];
+    results: readonly string[];
+};
 export type EngineStatus = "succeeded" | "budget_exhausted" | "refused" | "failed";
 export interface EngineResult {
     status: EngineStatus;

package/dist/providers/executor/composition.js

@@ -26,6 +26,7 @@ import { RunTranscriptRecorder, loadTranscriptMaxBytes, loadTranscriptRetentionD
 import { loadAgentSecretValues } from "../../core/secret-guard.js";
 import { createBlobStore } from "../storage/index.js";
 import { ContainerExecutor, PrismaContainerExecutionStore, RunCapabilityVault } from "./container.js";
+import { loadMcpToolPins } from "../../core/mcp-tools.js";
 import { PrismaExecutionKindResolver, RoutingExecutor } from "./routing.js";
 import { createRepoAccessGate } from "../../core/repo-access.js";
 import { buildIssueTrackers } from "../issue-tracker/index.js";
@@ -116,6 +117,7 @@ export function buildConfiguredExecutor(options) {
             config: kubernetes,
             workspaceRoot,
             resolveCapability: (runId) => capabilities.get(runId),
+            resolveMcpToken: (runId) => capabilities.mcpToken(runId),
             readyTimeoutMs: kubernetes.readyTimeoutMs,
             enforcementExecTimeoutMs: kubernetes.enforcementExecTimeoutMs,
             power: options.power ?? DISABLED_POWER,
@@ -140,6 +142,7 @@ export function buildConfiguredExecutor(options) {
             workspaceRoot,
             proxyContainer: proxyContainer,
             resolveCapability: (runId) => capabilities.get(runId),
+            resolveMcpToken: (runId) => capabilities.mcpToken(runId),
             isRunActive: async (runId, handle) => {
                 const coding = await options.db.codingRun.findUnique({
                     where: { runId },
@@ -177,6 +180,8 @@ export function buildConfiguredExecutor(options) {
         vcs,
         sessions,
         capabilities,
+        // Remote MCP servers: a coding run gets its agent's pinned tools and an MCP token ([] when off).
+        mcpToolPins: (agentId, pinOptions) => loadMcpToolPins(options.db, agentId, pinOptions),
         artifactRoot,
         workerImage: config.workerImage,
         claudeWorkerImage: config.claudeWorkerImage,

package/dist/providers/executor/container.d.ts

@@ -1,6 +1,8 @@
+import type { RunStepsLevel } from "../../core/run-steps/config.js";
 import { type PackageAuditEntry, type PackageAuditMode } from "../../coding/registry/audit-mode.js";
 import type { PrismaClient } from "#prisma";
 import type { RunTranscriptRecorder } from "../../coding/transcript/recorder.js";
+import { type McpToolPin } from "../../core/mcp-tools.js";
 import { type CodingProvider } from "../../coding/provider.js";
 import { type TopUpOutcome } from "../../core/budget-topup.js";
 import type { IssueTrackerRegistry } from "../issue-tracker/types.js";
@@ -100,6 +102,8 @@ export type StoredDescriptionBaseline = DescriptionBaseline & {
     legacySource?: LegacyDescriptionSource;
 };
 export interface ContainerRunSnapshot {
+    /** Run.runStepsLevel, fixed at dispatch; absent on older snapshots = summary. */
+    runStepsLevel?: RunStepsLevel | null;
     runId: string;
     agentId: string;
     status: string;
@@ -172,6 +176,12 @@ export interface ContainerRunSnapshot {
     profileRepository: string | null;
     /** How the profile's repository was authorized (CodingAgentProfile.repositoryAuthorizedVia). */
     repositoryAuthorizedVia: string | null;
+    /** The run's repository was chosen from the agent's list (CodingRun.viaRepositoryLink). */
+    viaRepositoryLink: boolean;
+    /** How the agent's current write link for the run's repository was authorized; null when there is none. */
+    repositoryLinkAuthorizedVia: string | null;
+    /** The agent's write link for the run's repository still exists (always false for a run not made via a link). */
+    repositoryLinkExists: boolean;
     /** The run's catalog entry recorded at dispatch (Run.pricingSnapshot); null on runs from before the catalog. */
     pricingVersion: string | null;
     pricingSnapshot: unknown;
@@ -327,6 +337,12 @@ export interface CodingSessionController {
         budgetUsd: number;
         /** The run's catalog entry; the proxy prices and shapes the run's requests from it. */
         terms?: ProxyModelTerms;
+        /** The run's pinned MCP tools; set with mcpTokenHash, only when the agent has at least one. */
+        mcpTools?: McpToolPin[];
+        /** The hash of the run's MCP token (src/coding/mcp-token.ts); the token itself stays in the vault. */
+        mcpTokenHash?: string;
+        /** The run's run-steps level (Run.runStepsLevel); the proxy reads tool output only at detail. */
+        runStepsLevel?: RunStepsLevel;
     }): Promise<{
         id: string;
         capability: string;
@@ -337,11 +353,19 @@ export interface CodingSessionController {
     /** The code of the first model-provider failure the proxy relayed for this session, if any. */
     upstreamFailure?(sessionId: string): Promise<string | null>;
 }
-/** Plain capabilities live only for the short provisioning window. */
+/**
+ * Plain capabilities live only for the short provisioning window. A run with MCP tools keeps its
+ * MCP token here too, next to the capability, so the launcher delivers it the same way; both are
+ * deleted together.
+ */
 export declare class RunCapabilityVault {
     private readonly values;
+    private readonly mcpTokens;
     set(runId: string, capability: string): void;
     get(runId: string): Promise<string>;
+    setMcpToken(runId: string, token: string): void;
+    /** The run's MCP token; undefined for a run without MCP tools (and once the launch is over). */
+    mcpToken(runId: string): Promise<string | undefined>;
     delete(runId: string): void;
 }
 export interface ContainerExecutorOptions {
@@ -352,6 +376,15 @@ export interface ContainerExecutorOptions {
     vcs: VcsProvider;
     sessions: CodingSessionController;
     capabilities: RunCapabilityVault;
+    /**
+     * The agent's MCP tool pins (composition wires loadMcpToolPins; [] when WARDBY_MCP_SERVERS=off).
+     * Absent = no coding run gets MCP tools. A run with pins gets an MCP token, delivered as
+     * WARDBY_MCP_TOKEN; one without gets neither. `readOnlyOnly` comes from the run's dispatched
+     * provider (isCodexCoding(run.provider)), never the agent's current profile.
+     */
+    mcpToolPins?: (agentId: string, options: {
+        readOnlyOnly: boolean;
+    }) => Promise<McpToolPin[]>;
     artifactRoot: string;
     /**
      * The Codex worker for the "node" toolchain (CODING_WORKER_IMAGE). Optional on a Claude-only
@@ -725,3 +758,16 @@ export declare class ContainerExecutor implements Executor {
 }
 /** Operator-facing failure text: the message plus its cause chain, redacted. */
 export declare function describeFailure(error: unknown, depth?: number): string;
+/** The agent's MCP tool pins could not be read at launch (a database error): the run fails, nothing launched. */
+export declare const MCP_PINS_UNAVAILABLE_ERROR = "coding_mcp_pins_unavailable";
+/** Its category: the run's error is coding_failure_mcp_pins_unavailable:<diagnostic id>. */
+export declare const MCP_PINS_UNAVAILABLE_CATEGORY = "mcp_pins_unavailable";
+/** Low-power mode: the native gateway serving a run's MCP tools did not wake; nothing launched. */
+export declare const MCP_GATEWAY_UNAVAILABLE_CATEGORY = "mcp_gateway_unavailable";
+/**
+ * Error-code prefixes that name their category outright, checked before the
+ * substring heuristics below. Those heuristics filed every `github_*` error
+ * (a failed PR lookup or create after the push, a token mint) under
+ * "workspace" because "github" contains "git".
+ */
+export declare const CATEGORY_BY_PREFIX: ReadonlyArray<readonly [prefix: string, category: string]>;