@wardby/cli 0.7.0 → 0.8.0

package/dist/providers/host-tools/request-guard.js

@@ -0,0 +1,99 @@
+/**
+ * Where one bound tool's request may go: the provider's API hosts, inside the path of
+ * the repository this call is for, using the operation's own methods. Wardby picks
+ * the repository, so a tool can't point a token at another one. Pure.
+ */
+export const MAX_HOST_TOOL_FETCHES = 3;
+export class HostToolRequestDenied extends Error {
+    constructor() {
+        super("host_tool_request_denied");
+        this.name = "HostToolRequestDenied";
+    }
+}
+export function assertHostToolRequest(url, method, scope) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new HostToolRequestDenied();
+    }
+    if (parsed.protocol !== "https:" || parsed.port !== "" || parsed.username || parsed.password) {
+        throw new HostToolRequestDenied();
+    }
+    if (!scope.apiHosts.includes(parsed.hostname.toLowerCase()))
+        throw new HostToolRequestDenied();
+    if (!scope.methods.includes(method.toUpperCase()))
+        throw new HostToolRequestDenied();
+    // Some frameworks read the method from these, which would turn a checked GET into a write.
+    for (const key of parsed.searchParams.keys()) {
+        const name = key.toLowerCase();
+        if (name === "_method" || name.startsWith("x-http-method"))
+            throw new HostToolRequestDenied();
+    }
+    const prefix = scope.pathPrefix.toLowerCase();
+    if (!prefix.startsWith("/"))
+        throw new HostToolRequestDenied();
+    // The repository is matched literally on the raw path; decoding is only for the segment rules.
+    const raw = parsed.pathname.toLowerCase();
+    if (raw !== prefix && !raw.startsWith(`${prefix}/`))
+        throw new HostToolRequestDenied();
+    assertSafeSegments(parsed.pathname);
+}
+const MAX_DECODE_ROUNDS = 8;
+const ALLOWED_HEADERS = ["accept", "content-type", "if-match", "if-none-match"];
+const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+/** Decodes every run of valid %XX escapes as UTF-8 bytes; a stray % stays literal. */
+function decodeOnce(text) {
+    return text.replace(/(?:%[0-9a-f]{2})+/gi, (run) => {
+        const bytes = Uint8Array.from(run.match(/%([0-9a-f]{2})/gi) ?? [], (hex) => parseInt(hex.slice(1), 16));
+        return utf8.decode(bytes);
+    });
+}
+/**
+ * The path as a server may finally read it: decoded and NFKC-normalized together to
+ * stable (a fullwidth percent sign becomes a real one), then judged per segment. Servers and proxies disagree on what a segment "is" (encoded or
+ * Unicode lookalike separators, stripped whitespace or format characters, trailing
+ * delimiters), so a segment that is only dots once those are removed is refused, and so
+ * is anything that changes the segment count. Ordinary names with odd characters pass.
+ */
+function assertSafeSegments(pathname) {
+    let current = pathname;
+    for (let round = 0;; round++) {
+        if (round > MAX_DECODE_ROUNDS)
+            throw new HostToolRequestDenied();
+        let next;
+        try {
+            next = decodeOnce(current).normalize("NFKC");
+        }
+        catch {
+            throw new HostToolRequestDenied();
+        }
+        if (next === current)
+            break;
+        current = next;
+    }
+    // eslint-disable-next-line no-control-regex
+    if (/[\\\u0000\u2215\u2044]/.test(current))
+        throw new HostToolRequestDenied();
+    const segments = current.split("/");
+    if (segments.length !== pathname.split("/").length)
+        throw new HostToolRequestDenied();
+    for (const segment of segments) {
+        // % is stripped too: a stray % must not turn "..%" into a passing name.
+        const bare = segment.replace(/[\p{Z}\p{C}%]/gu, "");
+        if (/^\.+(?:[;?#,:].*)?$/.test(bare))
+            throw new HostToolRequestDenied();
+    }
+}
+/** Request headers a bound tool may set: no override, routing or credential headers. */
+export function assertHostToolHeaders(headers) {
+    if (headers === undefined)
+        return;
+    if (typeof headers !== "object" || headers === null || Array.isArray(headers))
+        throw new HostToolRequestDenied();
+    for (const name of Object.keys(headers)) {
+        if (!ALLOWED_HEADERS.includes(name.toLowerCase()))
+            throw new HostToolRequestDenied();
+    }
+}

package/dist/providers/host-tools/self-test.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Calling a provider's approved snapshots, and the read-only checks test_host_provider reports.
+ * A report holds an operation, its repository, an outcome and a fixed code, so it can be shared
+ * from a team whose host we can't reach, carrying nothing else.
+ */
+import type { PrismaClient, Secret } from "#prisma";
+import { safeFetch } from "../../sandbox/safe-fetch.js";
+import type { SecretCipher } from "../secrets/types.js";
+import { type HostToolResult } from "./invoke.js";
+import { type HostOperation } from "./operations.js";
+type StoredSecret = Pick<Secret, "ciphertext" | "broker">;
+export interface LoadedProvider {
+    name: string;
+    apiHosts: string[];
+    repositoryApiPath: string;
+    permissionApiPath: string | null;
+    permissionSecret: StoredSecret | null;
+    credentials: {
+        repositoryPattern: string;
+        secret: StoredSecret;
+    }[];
+    operations: {
+        operation: string;
+        code: string;
+        paramsZod: string;
+        timeoutMs?: number | null;
+    }[];
+}
+/**
+ * The fetch for bound tools: the real one, or under WARDBY_TEST_SIMULATORS the simulator's. Under
+ * the switch only `sim-` credentials are sent, as the switch refuses every other real credential.
+ */
+export declare function hostToolFetch(env?: NodeJS.ProcessEnv): {
+    fetchImpl?: typeof safeFetch;
+    simulated: boolean;
+};
+export declare function loadProviderForCalls(db: PrismaClient, name: string): Promise<LoadedProvider | null>;
+/** The repository is compared in its normalized form, so callers must pass one. */
+export declare function callHostOperation(provider: LoadedProvider, cipher: SecretCipher, repository: string, operation: HostOperation, fields: Record<string, unknown>, options?: {
+    fetchImpl?: typeof safeFetch;
+    simulated?: boolean;
+}): Promise<HostToolResult>;
+export interface SelfTestInput {
+    repository: string;
+    pullRequest?: number;
+    headRef?: string;
+    ref?: string;
+    accountId?: string;
+}
+export interface SelfTestReport {
+    provider: string;
+    repository: string;
+    mode: "permission" | "allowlist";
+    results: {
+        operation: string;
+        outcome: "pass" | "fail" | "skipped";
+        code?: string;
+    }[];
+}
+export declare function selfTestHostProvider(provider: LoadedProvider, cipher: SecretCipher, input: SelfTestInput, options?: {
+    fetchImpl?: typeof safeFetch;
+    simulated?: boolean;
+}): Promise<SelfTestReport>;
+export {};

package/dist/providers/host-tools/self-test.js

@@ -0,0 +1,142 @@
+import { codeProviderOf, normalizeHostedRepository } from "../../coding/code-host.js";
+import { loadTestSimulators, simulatorHostFetch } from "../../config/test-simulators.js";
+import { parseSecretBrokerConfig } from "../../core/secret-broker-config.js";
+import { safeFetch } from "../../sandbox/safe-fetch.js";
+import { invokeHostTool } from "./invoke.js";
+import { HOST_OPERATIONS, isHostOperation } from "./operations.js";
+import { findCredential } from "./registry.js";
+import { effectiveToolTimeoutMs } from "../../sandbox/tool-timeout.js";
+import { loadToolMaxTimeoutMs } from "../../config/tool-timeout.js";
+/**
+ * The fetch for bound tools: the real one, or under WARDBY_TEST_SIMULATORS the simulator's. Under
+ * the switch only `sim-` credentials are sent, as the switch refuses every other real credential.
+ */
+export function hostToolFetch(env = process.env) {
+    const simulators = loadTestSimulators(env);
+    return simulators ? { fetchImpl: simulatorHostFetch(simulators, safeFetch), simulated: true } : { simulated: false };
+}
+export async function loadProviderForCalls(db, name) {
+    const row = await db.hostProvider.findUnique({
+        where: { name },
+        include: { permissionSecret: true, credentials: { include: { secret: true } }, operations: true },
+    });
+    if (!row)
+        return null;
+    return {
+        name: row.name,
+        apiHosts: row.apiHosts,
+        repositoryApiPath: row.repositoryApiPath,
+        permissionApiPath: row.permissionApiPath,
+        permissionSecret: row.permissionSecret,
+        credentials: row.credentials,
+        operations: row.operations,
+    };
+}
+// No URL-encoding: callHostOperation only takes a repository in its normalized form, which admits only [A-Za-z0-9._-], and the request guard compares a raw prefix.
+function encodePath(template, fields) {
+    return template.replace(/\{([a-z]+)\}/g, (_m, field) => fields[field]);
+}
+/** The repository is compared in its normalized form, so callers must pass one. */
+export async function callHostOperation(provider, cipher, repository, operation, fields, options = {}) {
+    let ours = false;
+    try {
+        ours = normalizeHostedRepository(repository) === repository && codeProviderOf(repository) === provider.name;
+    }
+    catch {
+        // Not a repository we can name: denied below.
+    }
+    if (!ours)
+        return { ok: false, code: "host_tool_request_denied" };
+    const snapshot = provider.operations.find((o) => o.operation === operation);
+    if (!snapshot)
+        return { ok: false, code: "host_tool_failed" };
+    const path = repository.slice(`${provider.name}:`.length);
+    const [workspace, repo] = path.split("/");
+    const permission = HOST_OPERATIONS[operation].credential === "permission";
+    const stored = permission ? provider.permissionSecret : (findCredential(provider.credentials, path)?.secret ?? null);
+    const template = permission ? provider.permissionApiPath : provider.repositoryApiPath;
+    if (!stored || !template)
+        return { ok: false, code: "host_tool_no_credential" };
+    const credential = async () => {
+        const value = await cipher.decrypt(stored.ciphertext);
+        if (options.simulated && !value.startsWith("sim-"))
+            return undefined;
+        return { value, broker: parseSecretBrokerConfig(stored.broker) };
+    };
+    return invokeHostTool({
+        provider: provider.name,
+        operation,
+        snapshot,
+        params: { ...fields, workspace, repo, repository: path },
+        apiHosts: provider.apiHosts,
+        pathPrefix: encodePath(template, { repository: path, workspace, repo }),
+        credential,
+        fetchImpl: options.fetchImpl,
+        timeoutMs: effectiveToolTimeoutMs(snapshot.timeoutMs, loadToolMaxTimeoutMs()),
+    });
+}
+export async function selfTestHostProvider(provider, cipher, input, options = {}) {
+    const repository = normalizeHostedRepository(input.repository);
+    if (codeProviderOf(repository) !== provider.name)
+        throw new Error("host_provider_repository_mismatch");
+    const results = [];
+    const skip = (operation, code) => results.push({ operation, outcome: "skipped", code });
+    const check = async (operation, fields) => {
+        const result = await callHostOperation(provider, cipher, repository, operation, fields, options);
+        results.push(result.ok ? { operation, outcome: "pass" } : { operation, outcome: "fail", code: result.code });
+        return result;
+    };
+    const bound = (name) => provider.operations.some((o) => o.operation === name);
+    // The pull request comes first: its head is the ref for the checks that need one.
+    let ref = input.ref;
+    const number = input.pullRequest;
+    if (!bound("getPullRequest"))
+        skip("getPullRequest", "not_bound");
+    else if (number === undefined)
+        skip("getPullRequest", "needs_pull_request");
+    else {
+        const pr = await check("getPullRequest", { number });
+        if (pr.ok)
+            ref ??= pr.value.headSha;
+    }
+    for (const operation of ["listPullRequestFiles", "getDiff", "listComments"]) {
+        if (!bound(operation))
+            skip(operation, "not_bound");
+        else if (number === undefined)
+            skip(operation, "needs_pull_request");
+        else
+            await check(operation, { number });
+    }
+    if (!bound("findPullRequest"))
+        skip("findPullRequest", "not_bound");
+    else if (input.headRef === undefined)
+        skip("findPullRequest", "needs_head_ref");
+    else
+        await check("findPullRequest", { headRef: input.headRef });
+    for (const [operation, fields] of [
+        ["readFile", { path: "README.md" }],
+        ["listFiles", { path: "" }],
+        ["listCommitStatuses", {}],
+    ]) {
+        if (!bound(operation))
+            skip(operation, "not_bound");
+        else if (ref === undefined)
+            skip(operation, "needs_ref");
+        else
+            await check(operation, { ref, ...fields });
+    }
+    const mode = provider.permissionSecret ? "permission" : "allowlist";
+    if (mode === "allowlist")
+        skip("getRepositoryPermission", "allowlist_mode");
+    else if (!bound("getRepositoryPermission"))
+        skip("getRepositoryPermission", "not_bound");
+    else if (input.accountId === undefined)
+        skip("getRepositoryPermission", "needs_account");
+    else
+        await check("getRepositoryPermission", { accountId: input.accountId });
+    for (const { operation } of provider.operations) {
+        if (isHostOperation(operation) && !HOST_OPERATIONS[operation].readOnly)
+            skip(operation, "not_read_only");
+    }
+    return { provider: provider.name, repository, mode, results };
+}

package/dist/providers/jobs/docker-isolation.d.ts

@@ -214,6 +214,6 @@ export declare function assertStorageVolumeInspection(volume: DockerVolumeInspec
 export declare function assertKeeperContainerInspection(container: DockerContainerInspection, spec: JobSpec): void;
 export declare function assertNetworkKeeperContainerInspection(container: DockerContainerInspection, spec: JobSpec): void;
 export declare function assertProxyContainerInspection(container: DockerContainerInspection, runId: string): void;
-export declare function assertWorkerContainerInspection(container: DockerContainerInspection, spec: JobSpec, expectedCapability: string, networkKeeperId?: string): void;
-export declare function assertClaudeAgentContainerInspection(container: DockerContainerInspection, spec: JobSpec, expectedCapability: string): void;
+export declare function assertWorkerContainerInspection(container: DockerContainerInspection, spec: JobSpec, expectedCapability: string, networkKeeperId?: string, expectedMcpToken?: string): void;
+export declare function assertClaudeAgentContainerInspection(container: DockerContainerInspection, spec: JobSpec, expectedCapability: string, expectedMcpToken?: string): void;
 export declare function assertClaudeToolRunnerContainerInspection(container: DockerContainerInspection, spec: JobSpec, expectedSetup: string, networkKeeperId?: string): void;

package/dist/providers/jobs/docker-isolation.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { MCP_TOKEN_ENV } from "../../coding/mcp-token.js";
 export const CODING_WORKER_UID = 10001;
 export const CODING_WORKER_GID = 10001;
 // The keeper needs headroom for runc's short-lived exec process plus Node's threads.
@@ -101,6 +102,8 @@ function validateSpec(spec) {
     if (spec.sessionResume !== undefined && (spec.sessionResume !== true || spec.provider !== "claude-code")) {
         throw isolationError();
     }
+    if (spec.mcpTools !== undefined && spec.mcpTools !== true)
+        throw isolationError();
     if (spec.services !== undefined) {
         // docker-services.ts re-validates every entry against the catalog schema. Both providers' shells
         // share the network keeper's namespace: Codex's worker, and Claude Code's tool runner.
@@ -306,6 +309,27 @@ function workerNetworkMode(spec) {
     const names = isolationNames(spec.runId);
     return spec.services === undefined ? names.network : `container:${names.networkKeeperContainer}`;
 }
+/**
+ * A run with MCP tools only: the agent's MCP token, by name. Like the capability, its value comes
+ * from the docker process's own environment (DockerCommandOptions.env), never the command line.
+ */
+function mcpTokenEnvArgs(spec) {
+    return spec.mcpTools ? ["--env", MCP_TOKEN_ENV] : [];
+}
+/**
+ * The agent container's exact WARDBY_ environment: the proxy URL, the capability, and for a run with
+ * MCP tools its MCP token. Anything missing, changed or extra fails the attestation.
+ */
+function agentEnvironmentMatches(environment, spec, expectedCapability, expectedMcpToken) {
+    if (spec.mcpTools && expectedMcpToken === undefined)
+        return false;
+    const expected = [
+        `WARDBY_PROXY_URL=http://${CODING_PROXY_ALIAS}:${CODING_PROXY_PORT}`,
+        `WARDBY_RUN_CAPABILITY=${expectedCapability}`,
+        ...(spec.mcpTools ? [`${MCP_TOKEN_ENV}=${expectedMcpToken}`] : []),
+    ];
+    return environment.length === expected.length && expected.every((value) => environment.includes(value));
+}
 export function buildWorkerCreateArgs(spec, proxyPort = CODING_PROXY_PORT) {
     validateSpec(spec);
     assertIntegerRange(proxyPort, 1, 65_535);
@@ -360,6 +384,7 @@ export function buildWorkerCreateArgs(spec, proxyPort = CODING_PROXY_PORT) {
         `WARDBY_PROXY_URL=http://${CODING_PROXY_ALIAS}:${proxyPort}`,
         "--env",
         "WARDBY_RUN_CAPABILITY",
+        ...mcpTokenEnvArgs(spec),
         "--restart",
         "no",
         "--stop-signal",
@@ -459,6 +484,7 @@ export function buildClaudeAgentCreateArgs(spec, proxyPort = CODING_PROXY_PORT)
         `WARDBY_PROXY_URL=http://${CODING_PROXY_ALIAS}:${proxyPort}`,
         "--env",
         "WARDBY_RUN_CAPABILITY",
+        ...mcpTokenEnvArgs(spec),
         "--restart",
         "no",
         "--stop-signal",
@@ -780,7 +806,7 @@ function assertExactWorkerMounts(container, names) {
         }
     }
 }
-export function assertWorkerContainerInspection(container, spec, expectedCapability, networkKeeperId) {
+export function assertWorkerContainerInspection(container, spec, expectedCapability, networkKeeperId, expectedMcpToken) {
     validateSpec(spec);
     const names = isolationNames(spec.runId);
     const host = container.HostConfig;
@@ -822,9 +848,7 @@ export function assertWorkerContainerInspection(container, spec, expectedCapabil
         Object.keys(container.NetworkSettings?.Ports ?? {}).length !== 0) {
         throw isolationError();
     }
-    if (wardbyEnvironment.length !== 2 ||
-        !wardbyEnvironment.includes(`WARDBY_PROXY_URL=http://${CODING_PROXY_ALIAS}:${CODING_PROXY_PORT}`) ||
-        !wardbyEnvironment.includes(`WARDBY_RUN_CAPABILITY=${expectedCapability}`)) {
+    if (!agentEnvironmentMatches(wardbyEnvironment, spec, expectedCapability, expectedMcpToken)) {
         throw isolationError();
     }
     const tmpfs = host.Tmpfs ?? {};
@@ -893,16 +917,14 @@ function assertClaudeContainerBaseline(container, image, spec, limits) {
         !host.Tmpfs?.["/home/wardby"]?.includes("noexec"))
         throw isolationError();
 }
-export function assertClaudeAgentContainerInspection(container, spec, expectedCapability) {
+export function assertClaudeAgentContainerInspection(container, spec, expectedCapability, expectedMcpToken) {
     validateSpec(spec);
     if (spec.provider !== "claude-code")
         throw isolationError();
     const names = isolationNames(spec.runId);
     assertClaudeContainerBaseline(container, spec.image, spec, claudeAgentLimits(spec));
     const environment = (container.Config?.Env ?? []).filter((value) => value.startsWith("WARDBY_"));
-    if (environment.length !== 2 ||
-        !environment.includes(`WARDBY_PROXY_URL=http://${CODING_PROXY_ALIAS}:${CODING_PROXY_PORT}`) ||
-        !environment.includes(`WARDBY_RUN_CAPABILITY=${expectedCapability}`))
+    if (!agentEnvironmentMatches(environment, spec, expectedCapability, expectedMcpToken))
         throw isolationError();
     assertExactMountSet(container, names, [
         { path: WORKER_PATHS.input, writable: false, subpath: "input" },

package/dist/providers/jobs/docker.d.ts

@@ -88,6 +88,12 @@ export interface DockerJobLauncherOptions {
     workspaceRoot: string;
     proxyContainer: string;
     resolveCapability: (runId: string) => Promise<string>;
+    /**
+     * The run's MCP token (the capability vault), asked for only when the spec has mcpTools; the agent
+     * container gets it as WARDBY_MCP_TOKEN, through the docker process's environment like the
+     * capability. Absent = a run with MCP tools can't be launched.
+     */
+    resolveMcpToken?: (runId: string) => Promise<string | undefined>;
     /** Consult the durable application state before a startup sweep deletes resources. */
     isRunActive: (runId: string, handle: JobHandle) => Promise<boolean>;
     docker?: DockerCommandRunner;
@@ -131,6 +137,8 @@ export declare class DockerJobLauncher implements WorkspaceJobLauncher {
     remove(handle: JobHandle): Promise<void>;
     private initialize;
     private launchLocked;
+    /** The run's MCP token for a spec with mcpTools (refused unless well formed); undefined otherwise, unasked. */
+    private mcpTokenFor;
     private provision;
     /**
      * A run with services (docs/coding-services.md). The network keeper joins the run's internal

package/dist/providers/jobs/docker.js

@@ -12,6 +12,7 @@ import { assertDockerHostSupportsIsolation, assertClaudeAgentContainerInspection
 import { serviceUnreadyError } from "../../coding/services/wording.js";
 import { assertServiceContainerInspection, buildDockerServicePlan, dockerServiceContainerNames, } from "./docker-services.js";
 import { claudeToolSetup } from "./claude-tool-setup.js";
+import { isMcpToken, MCP_TOKEN_ENV } from "../../coding/mcp-token.js";
 import { reportServiceState, } from "./service-state.js";
 import { replaceDirectoryFromStaging } from "./workspace-swap.js";
 const BACKEND = "docker";
@@ -95,7 +96,7 @@ export class NodeDockerCommandRunner {
         if (args.some((argument) => argument.includes("\0")))
             throw new Error("docker_argument_invalid");
         const extraEnv = options.env ?? {};
-        if (Object.keys(extraEnv).some((key) => key !== "WARDBY_RUN_CAPABILITY" && key !== CLAUDE_TOOL_SETUP_ENV))
+        if (Object.keys(extraEnv).some((key) => key !== "WARDBY_RUN_CAPABILITY" && key !== MCP_TOKEN_ENV && key !== CLAUDE_TOOL_SETUP_ENV))
             throw new Error("docker_environment_invalid");
         const env = {
             PATH: this.path,
@@ -447,6 +448,10 @@ function serviceUnready(name, cause) {
 function capabilityFromInspection(container) {
     return container.Config?.Env?.find((value) => value.startsWith("WARDBY_RUN_CAPABILITY="))?.slice("WARDBY_RUN_CAPABILITY=".length);
 }
+function mcpTokenFromInspection(container) {
+    const prefix = `${MCP_TOKEN_ENV}=`;
+    return container.Config?.Env?.find((value) => value.startsWith(prefix))?.slice(prefix.length);
+}
 function dockerState(inspection) {
     const state = inspection.State;
     if (!state)
@@ -655,14 +660,19 @@ export class DockerJobLauncher {
             const capability = ensureCapability(await this.options.resolveCapability(spec.runId));
             if (hash(capability) !== existing.capabilityHash)
                 throw new Error("docker_capability_changed");
+            const mcpToken = await this.mcpTokenFor(spec);
+            if ((mcpToken === undefined ? undefined : hash(mcpToken)) !== existing.mcpTokenHash) {
+                throw new Error("docker_mcp_token_changed");
+            }
             if (existing.phase === "active") {
                 await this.refresh(existing);
                 return clone(existing.handle);
             }
-            return this.provision(existing, plan, services, capability);
+            return this.provision(existing, plan, services, capability, mcpToken);
         }
         await this.validateInputArtifact(spec.inputArtifact);
         const capability = ensureCapability(await this.options.resolveCapability(spec.runId));
+        const mcpToken = await this.mcpTokenFor(spec);
         const record = {
             schemaVersion: STATE_SCHEMA_VERSION,
             runId: spec.runId,
@@ -673,12 +683,13 @@ export class DockerJobLauncher {
             createdAt: this.now(),
             deadlineAt: this.now() + plan.deadlineMs,
             capabilityHash: hash(capability),
+            ...(mcpToken !== undefined ? { mcpTokenHash: hash(mcpToken) } : {}),
             phase: "provisioning",
         };
         // This durable record is the idempotency fence before any Docker side effect.
         await this.writeRecord(record);
         try {
-            return await this.provision(record, plan, services, capability);
+            return await this.provision(record, plan, services, capability, mcpToken);
         }
         catch (error) {
             await this.options
@@ -691,7 +702,16 @@ export class DockerJobLauncher {
             throw error;
         }
     }
-    async provision(record, plan, services, capability) {
+    /** The run's MCP token for a spec with mcpTools (refused unless well formed); undefined otherwise, unasked. */
+    async mcpTokenFor(spec) {
+        if (!spec.mcpTools)
+            return undefined;
+        const token = await this.options.resolveMcpToken?.(spec.runId);
+        if (!isMcpToken(token))
+            throw new Error("docker_mcp_token_invalid");
+        return token;
+    }
+    async provision(record, plan, services, capability, mcpToken) {
         await this.assertHost();
         const labels = resourceLabels(record);
         await this.createAndAssert(appendLabels(plan.networkCreateArgs, labels), ["network", "inspect", plan.names.network], (value) => {
@@ -740,14 +760,14 @@ export class DockerJobLauncher {
         await this.createAndAssert(workerArgs, ["container", "inspect", plan.names.workerContainer], (value) => {
             const inspected = value;
             if (record.spec.provider === "claude-code") {
-                assertClaudeAgentContainerInspection(inspected, record.spec, capability);
+                assertClaudeAgentContainerInspection(inspected, record.spec, capability, mcpToken);
             }
             else {
-                assertWorkerContainerInspection(inspected, record.spec, capability, networkKeeperId);
+                assertWorkerContainerInspection(inspected, record.spec, capability, networkKeeperId, mcpToken);
             }
             if (!labelsMatch(inspected.Config?.Labels, labels))
                 throw new Error("docker_resource_attestation_failed");
-        }, { env: { WARDBY_RUN_CAPABILITY: capability } });
+        }, { env: { WARDBY_RUN_CAPABILITY: capability, ...(mcpToken !== undefined ? { [MCP_TOKEN_ENV]: mcpToken } : {}) } });
         await this.startContainer(plan.names.workerContainer);
         record.phase = "active";
         await this.writeRecord(record);
@@ -939,8 +959,12 @@ export class DockerJobLauncher {
         const capability = capabilityFromInspection(inspection);
         if (!capability || hash(capability) !== record.capabilityHash)
             throw new Error("docker_resource_attestation_failed");
+        // Only a run with MCP tools carries a token, and only the one its record hashed.
+        const mcpToken = record.spec.mcpTools ? mcpTokenFromInspection(inspection) : undefined;
+        if (record.spec.mcpTools && (!mcpToken || hash(mcpToken) !== record.mcpTokenHash))
+            throw new Error("docker_resource_attestation_failed");
         if (record.spec.provider === "claude-code") {
-            assertClaudeAgentContainerInspection(inspection, record.spec, capability);
+            assertClaudeAgentContainerInspection(inspection, record.spec, capability, mcpToken);
             const tool = await this.inspect([
                 "container",
                 "inspect",
@@ -956,7 +980,7 @@ export class DockerJobLauncher {
             }
         }
         else {
-            assertWorkerContainerInspection(inspection, record.spec, capability, await this.attestedNetworkKeeperId(record));
+            assertWorkerContainerInspection(inspection, record.spec, capability, await this.attestedNetworkKeeperId(record), mcpToken);
         }
         const phase = dockerState(inspection);
         if (!phase || phase === "provisioning" || phase === "active")

package/dist/providers/jobs/kubernetes-isolation.d.ts

@@ -13,6 +13,8 @@ export declare const WORKER_CONTAINER = "worker";
 export declare const TOOL_RUNNER_CONTAINER = "tool-runner";
 /** The run Secret's key holding the tool runner's setup (claude-tool-setup.ts). */
 export declare const TOOL_SETUP_SECRET_KEY = "tool-setup";
+/** The run Secret's key for the MCP token (a run with MCP tools only); the agent container alone reads it. */
+export declare const MCP_TOKEN_SECRET_KEY = "mcp-token";
 /** Where the tool runner listens and the agent's relay connects (claude-tool-runner/main.mjs). */
 export declare const TOOL_SOCKET_PATH = "/run/wardby/tool/runner.sock";
 /** Every service sidecar's container name starts with this (service-postgres, service-redis, ...). */
@@ -82,7 +84,7 @@ export interface RunPodOptions {
 }
 export declare function buildRunPod(spec: JobSpec, options: RunPodOptions): V1Pod;
 export declare function buildRunNetworkPolicy(spec: JobSpec, namespace: string): V1NetworkPolicy;
-export declare function buildCapabilitySecret(spec: JobSpec, namespace: string, capability: string, toolSetup?: string): V1Secret;
+export declare function buildCapabilitySecret(spec: JobSpec, namespace: string, capability: string, toolSetup?: string, mcpToken?: string): V1Secret;
 /** A copy of a container's resources with every quantity in one rendering ("1" and "1000m" alike); see normalizeResources. */
 export declare function canonicalResources(r?: V1Container["resources"]): V1Container["resources"];
 /**

package/dist/providers/jobs/kubernetes-isolation.js

@@ -7,6 +7,7 @@
 import { createHash } from "node:crypto";
 import { isIP } from "node:net";
 import { StoredCodingServicesSchema } from "../../coding/services/catalog.js";
+import { MCP_TOKEN_ENV } from "../../coding/mcp-token.js";
 import { CLAUDE_CONFIG_PATH, CLAUDE_CONFIG_SCRATCH_MIB, CLAUDE_TOOL_SETUP_ENV, CODING_PROXY_ALIAS, CODING_PROXY_DENY_PORT, CODING_PROXY_PORT, CODING_WORKER_GID, CODING_WORKER_UID, WORKER_STOP_GRACE_SECONDS, claudeToolLimits, isRepositoryDigest, } from "./docker-isolation.js";
 import { GVISOR_RUNTIME_CLASS, KubernetesPlatformError, STORAGE_INIT_EPHEMERAL_MIB, TOOL_RUNNER_EPHEMERAL_MIB, WORKER_EPHEMERAL_MIB, conformResources, describeMib, normalizePlatformMetadata, platformProfile, podEphemeralStorageMib, } from "./kubernetes-platform.js";
 export const KUBERNETES_ISOLATION_ERROR = "kubernetes_isolation_unsupported";
@@ -19,6 +20,8 @@ export const WORKER_CONTAINER = "worker";
 export const TOOL_RUNNER_CONTAINER = "tool-runner";
 /** The run Secret's key holding the tool runner's setup (claude-tool-setup.ts). */
 export const TOOL_SETUP_SECRET_KEY = "tool-setup";
+/** The run Secret's key for the MCP token (a run with MCP tools only); the agent container alone reads it. */
+export const MCP_TOKEN_SECRET_KEY = "mcp-token";
 /** Where the tool runner listens and the agent's relay connects (claude-tool-runner/main.mjs). */
 export const TOOL_SOCKET_PATH = "/run/wardby/tool/runner.sock";
 const CODEX_ENTRYPOINT = "/opt/wardby/coding-worker/main.js";
@@ -172,6 +175,8 @@ export function validateKubernetesSpec(spec) {
     if (spec.sessionResume !== undefined && (spec.sessionResume !== true || spec.provider !== "claude-code")) {
         throw isolationError("session-resume-not-claude");
     }
+    if (spec.mcpTools !== undefined && spec.mcpTools !== true)
+        throw isolationError("mcp-tools-invalid");
     if (!isRegistryDigest(spec.image))
         throw isolationError("image-not-registry-digest");
     if (spec.services !== undefined) {
@@ -313,6 +318,10 @@ export function buildRunPod(spec, options) {
         env: [
             { name: "WARDBY_PROXY_URL", value: `http://${CODING_PROXY_ALIAS}:${CODING_PROXY_PORT}` },
             { name: "WARDBY_RUN_CAPABILITY", valueFrom: { secretKeyRef: { name: names.secret, key: "capability" } } },
+            // A run with MCP tools only: the agent's bearer for the proxy's /mcp route. Never the tool runner's.
+            ...(spec.mcpTools
+                ? [{ name: MCP_TOKEN_ENV, valueFrom: { secretKeyRef: { name: names.secret, key: MCP_TOKEN_SECRET_KEY } } }]
+                : []),
         ],
         securityContext: containerSecurity(),
         resources: conformResources(profile, {
@@ -464,14 +473,18 @@ export function buildRunNetworkPolicy(spec, namespace) {
         },
     };
 }
-export function buildCapabilitySecret(spec, namespace, capability, toolSetup) {
+export function buildCapabilitySecret(spec, namespace, capability, toolSetup, mcpToken) {
     const names = kubernetesRunNames(spec.runId);
     return {
         apiVersion: "v1",
         kind: "Secret",
         type: "Opaque",
         metadata: { name: names.secret, namespace, labels: runLabels(spec.runId) },
-        stringData: { capability, ...(toolSetup !== undefined ? { [TOOL_SETUP_SECRET_KEY]: toolSetup } : {}) },
+        stringData: {
+            capability,
+            ...(toolSetup !== undefined ? { [TOOL_SETUP_SECRET_KEY]: toolSetup } : {}),
+            ...(mcpToken !== undefined ? { [MCP_TOKEN_SECRET_KEY]: mcpToken } : {}),
+        },
     };
 }
 /**

package/dist/providers/jobs/kubernetes.d.ts

@@ -14,6 +14,11 @@ export interface KubernetesJobLauncherOptions {
     config: KubernetesJobConfig;
     workspaceRoot: string;
     resolveCapability: (runId: string) => Promise<string>;
+    /**
+     * The run's MCP token (the capability vault), asked for only when the spec has mcpTools; it goes into
+     * the run's Secret next to the capability. Absent = a run with MCP tools can't be launched.
+     */
+    resolveMcpToken?: (runId: string) => Promise<string | undefined>;
     /**
      * Cluster preflight run once before the first launch; failure fails every launch. It may return the
      * proxy ClusterIP it validated; otherwise the launcher reads the proxy witness once itself. Either way