@fastagent-sh/fastagent 0.28.0 → 0.29.0

package/dist/cli/add-feishu.js

@@ -7,9 +7,10 @@ import { isCancel, log as clackLog, password, text as clackText } from "@clack/p
 import { bootstrapFeishuVerificationToken } from "../channels/feishu/bootstrap-token.js";
 import { FEISHU_APP_CONFIG_SCOPE, feishuAppAddons, feishuAppScopes, feishuScopeRequestUrl, scopeSatisfied, } from "../channels/feishu/setup-mode.js";
 import { cloudFor } from "../channels/feishu/cloud.js";
-import { createFeishuApi, isFeishuConfigApiMissing, isTransientFeishuRegistrationError, } from "../channels/feishu/feishu-api.js";
+import { createFeishuApi, isFeishuConfigApiMissing, isFeishuCredentialsRefused, isTransientFeishuRegistrationError, } from "../channels/feishu/feishu-api.js";
 import { registerFeishuApp } from "../channels/feishu/register-app.js";
-import { LARK_CONSOLE_URL, onboardLarkApp } from "../channels/lark/onboard.js";
+import { LarkCredentialsRefused, startLarkCredentialsPage, startLarkVerificationPage, } from "../channels/lark/credentials-page.js";
+import { onboardLarkApp } from "../channels/lark/onboard.js";
 import { dotEnvPath, loadEnvValues, parseEnvContent } from "../value-file.js";
 import { openExternalUrl } from "../open-url.js";
 import { terminalPerson } from "./person.js";
@@ -88,7 +89,7 @@ person = terminalPerson) {
         return undefined;
     }
     // guided-console (lark): the intl cloud cannot complete the bound device flow — collect + validate.
-    const credentials = await onboardLarkApp(person === terminalPerson ? larkAtTerminal : larkThrough(person, env, rerun), {
+    const credentials = await onboardLarkApp(person === terminalPerson ? larkAtTerminal : larkThrough(person, target), {
         existing,
         ingress,
         rerun,
@@ -99,6 +100,17 @@ person = terminalPerson) {
             await createFeishuApi({ kind: "lark", baseUrl: apiBase, appId, appSecret }).verifyCredentials();
             console.error(`[fastagent] Lark App ID / Secret verified`);
         },
+        // The same boundary `add feishu` keeps: a pair given just now is written before any step that can fail, so a
+        // rerun finds it and carries on, instead of asking for it again.
+        keep: async (appId, appSecret) => {
+            const kept = {
+                LARK_APP_ID: appId,
+                LARK_APP_SECRET: appSecret,
+                ...(ingress === "webhook" ? { LARK_VERIFICATION_TOKEN: "" } : {}),
+            };
+            await appendChannelDotEnv(target, "lark", kept, Object.keys(kept), ingress);
+            console.error(`[fastagent] wrote LARK_APP_ID, LARK_APP_SECRET to ${env}`);
+        },
         bootstrapWebhook: async (appId, appSecret) => {
             const api = createFeishuApi({ kind: "lark", baseUrl: apiBase, appId, appSecret });
             console.error(`[fastagent] trying Lark's webhook-mode + Verification-Token bootstrap (temporary tunnel)…`);
@@ -152,16 +164,56 @@ const larkAtTerminal = {
         return isCancel(result) ? undefined : result;
     },
 };
-/**
- * Lark's guided console through a coding agent's person: a page is a step left to them, with what they do there; a
- * value it would ask for is theirs to set in the value file, and the setup continues when run again.
- */
-function larkThrough(person, env, rerun) {
+async function waitForLarkPage(person, page, action) {
+    const port = new URL(page.url).port;
+    try {
+        person.waitsOn(page.url, action +
+            " If the CLI runs remotely, forward this loopback port to the same local port " +
+            `(SSH: ssh -N -L ${port}:127.0.0.1:${port} user@host), then open the same URL in your browser. ` +
+            "Keep the forwarding session open; never paste secrets into the conversation.");
+        const value = await page.credentials;
+        person.carriesOn();
+        return value;
+    }
+    finally {
+        await page.close();
+    }
+}
+function larkThrough(person, target) {
     return {
         note: (message) => console.error(`[fastagent] ${message}`),
         openUrl: (url, action) => person.afterwards(action, url),
-        async prompt(message) {
-            throw new Error(`${message} is needed: ask the user to set it in ${env}, then run \`${rerun}\` again`);
+        async prompt() {
+            throw new Error("Lark setup must collect secrets on its page, not through terminal prompts");
+        },
+        async verificationToken(consoleUrl) {
+            const page = await startLarkVerificationPage({
+                consoleUrl,
+                save: async (token) => {
+                    await appendChannelDotEnv(target, "lark", { LARK_VERIFICATION_TOKEN: token }, ["LARK_VERIFICATION_TOKEN"]);
+                },
+            });
+            return waitForLarkPage(person, page, "Paste the Lark Verification Token on this page.");
+        },
+        async collect({ consoleUrl, check }) {
+            const page = await startLarkCredentialsPage({
+                consoleUrl,
+                check: async ({ appId, appSecret }) => {
+                    try {
+                        await check(appId, appSecret);
+                    }
+                    catch (error) {
+                        // Only a known credential refusal is safe to retry on the form.
+                        if (!isFeishuCredentialsRefused(error))
+                            throw error;
+                        throw new LarkCredentialsRefused("Lark refused that App ID or Secret.", {
+                            fix: "Copy both again from Credentials & Basic Info.",
+                            why: `Lark said: ${error instanceof Error ? error.message : String(error)}`,
+                        });
+                    }
+                },
+            });
+            return waitForLarkPage(person, page, "Create the Lark app, then paste its App ID and App Secret on this page.");
         },
     };
 }
@@ -280,34 +332,6 @@ async function createFeishuAppFlow(target, existing, ingress, rerun, person) {
             person.afterwards(`after the permission work above, ${publish}: ${versionUrl}`);
     }
 }
-/**
- * Lark's app credentials, which only the person can get, from the app they create in Lark's console: with no one at a
- * terminal to type them, the report naming where they set them (the selected environment's file), when either is
- * absent. `again` is the command that continues once they have.
- */
-export async function larkCredentialsNeeded(agentDir, again) {
-    const held = await activeDotEnvValues(agentDir, ["LARK_APP_ID", "LARK_APP_SECRET"]);
-    if (held.LARK_APP_ID && held.LARK_APP_SECRET)
-        return undefined;
-    const valueFile = dotEnvPath(agentDir);
-    return {
-        json: {
-            status: "need_user_action",
-            url: LARK_CONSOLE_URL,
-            variables: ["LARK_APP_ID", "LARK_APP_SECRET"],
-            value_file: valueFile,
-            check_command: `${again} --json`,
-            agent_next_steps: "Give the URL to the user so they can create the Lark app there, and ask them to set LARK_APP_ID and " +
-                `LARK_APP_SECRET (from its Credentials & Basic Info) in ${valueFile} themselves, not in this ` +
-                "conversation. Once they say they have, run check_command.",
-        },
-        text: [
-            `need_user_action: create the Lark app at ${LARK_CONSOLE_URL}`,
-            `  and set LARK_APP_ID and LARK_APP_SECRET in ${valueFile}`,
-            `then run: ${again}`,
-        ],
-    };
-}
 /**
  * Active agent `.env` (`.secrets/.env`) values for the requested names — decided by THE .env parser, so this check can
  * never disagree with what `loadDotEnv` reads.

package/dist/cli/commands/add.js

@@ -4,7 +4,7 @@
  */
 import { randomBytes } from "node:crypto";
 import { join, relative, resolve } from "node:path";
-import { assertIndependentFeishuApps, larkCredentialsNeeded, onboardFeishuCloudApp } from "../add-feishu.js";
+import { assertIndependentFeishuApps, onboardFeishuCloudApp } from "../add-feishu.js";
 import { terminalPerson } from "../person.js";
 import { isInteractive, shellArg } from "../shared.js";
 import { checkTicket, printReport, refusedCheck, runTicket, startTicket, ticketExitCode, ticketReport, } from "../ticket.js";
@@ -211,20 +211,13 @@ const SETUP_ACTIONS = {
     lark: "finish setting up the Lark app",
 };
 /**
- * `add slack|feishu|lark` with no one at a terminal to ask, for a coding agent: what the person must provide first is
- * named (Lark's app credentials, in the file the agent reads), never asked for in the agent's conversation; then the
- * app's setup runs in a process of its own (ticket.ts), and the command returns once the person has a step to take, it
- * is done, or it is still working at it.
+ * `add slack|feishu|lark` with no one at a terminal to ask, for a coding agent: the app's setup runs in a process of its
+ * own (ticket.ts), and the command returns once the person has a step to take, it is done, or it is still working at it.
+ * What only the person has (Slack's tokens, Lark's App ID and Secret) is pasted on a page of the setup's own, never asked
+ * for in the agent's conversation and never typed into a file.
  */
 async function setUpUnattended(kind, opts, at) {
     const { target } = at;
-    if (kind === "lark") {
-        const needed = await larkCredentialsNeeded(target, at.rerun).catch(failStartup);
-        if (needed !== undefined) {
-            printReport(opts.json, needed.json, needed.text);
-            process.exit(0);
-        }
-    }
     const timeout = opts.timeout === undefined ? UNATTENDED_TIMEOUT_SECONDS : Number(opts.timeout);
     if (!Number.isInteger(timeout) || timeout <= 0)
         failUsage(`--timeout must be a whole number of seconds`);

package/dist/cli/commands/deploy.js

@@ -8,7 +8,7 @@ import { FEISHU_INGRESS_SETTINGS } from "../../channels/feishu/setup-mode.js";
 import { assembleSecrets, divergentSettingsGate, missingValuesGate } from "../../deploy/secrets.js";
 import { dotEnvPath, loadEnvValues } from "../../value-file.js";
 import { unmarkDevServe } from "../../serving-command.js";
-import { assertIndependentFeishuApps, feishuAppSecretNames, larkCredentialsNeeded, prepareFeishuApps, unpreparedFeishuApps, } from "../add-feishu.js";
+import { assertIndependentFeishuApps, feishuAppSecretNames, prepareFeishuApps, unpreparedFeishuApps, } from "../add-feishu.js";
 import { displayPath, selectAgentEnvironment } from "../../paths.js";
 import { preflightDeploy } from "../../deploy/preflight.js";
 import { apiReport, deploymentApi, writeApiKey } from "../../deploy/api.js";
@@ -139,13 +139,6 @@ async function deploy(host, dirArg, opts, step) {
     const unprepared = opts.run ? unpreparedFeishuApps(pre.channels, pre.values) : [];
     if (opts.json && step === undefined) {
         // A coding agent's deploy: what this machine can refuse is refused above, at once; the rest runs in a ticket.
-        if (unprepared.some(({ kind }) => kind === "lark")) {
-            const needed = await larkCredentialsNeeded(agentDir, rerun).catch(failStartup);
-            if (needed !== undefined) {
-                printReport(true, needed.json, needed.text);
-                process.exit(0);
-            }
-        }
         const timeout = opts.timeout === undefined ? TICKET_TIMEOUT_SECONDS : Number(opts.timeout);
         if (!Number.isInteger(timeout) || timeout <= 0)
             failUsage("--timeout must be a whole number of seconds");

package/dist/cli/commands/info.js

@@ -8,6 +8,7 @@ import { enterAgentEnv } from "../../env.js";
 import { modelEnvironment } from "../../harnesses/models/environment.js";
 import { buildDefinition, modelSpecFor, prepareDefinition, secretsManifest } from "../../harnesses/pi-durable/open.js";
 import { readCommands } from "../../harnesses/pi-durable/text.js";
+import { inspectMcp } from "../../mcp/host.js";
 import { resolveStateRoot } from "../../paths.js";
 import { nextRun } from "../../schedule/cron.js";
 import { contentLines } from "../content-view.js";
@@ -60,6 +61,7 @@ export async function runInfo(dirArg, opts) {
     const commands = readCommands(agentDir).map(({ name, description }) => ({ name, description: description ?? null }));
     const stateRoot = resolveStateRoot(agentDir);
     const auth = models.auth;
+    const mcp = await inspectMcp(agentDir).catch(failStartup);
     if (opts.json) {
         console.log(JSON.stringify({
             agentDir,
@@ -72,6 +74,7 @@ export async function runInfo(dirArg, opts) {
             modelError: modelError ?? null,
             thinkingLevel: config.thinkingLevel ?? null,
             tools: code?.tools.map(({ name }) => name) ?? null,
+            mcp,
             extensions: code?.extensions.map(({ name }) => name) ?? null,
             channels: code === undefined ? null : channels,
             schedules: code === undefined ? null : schedules,
@@ -102,6 +105,7 @@ export async function runInfo(dirArg, opts) {
     line("tools", code ? code.tools.map(({ name }) => name).join(", ") || "(none)" : unbuilt);
     if (code && code.extensions.length > 0)
         line("extensions", code.extensions.map(({ name }) => name).join(", "));
+    line("mcp", mcp.map((server) => `${server.name} (${server.transport}, ${server.authorization})`).join(", ") || "(none)");
     line("channels", code ? channels.map((c) => `${c.name} (${c.ingress})`).join(", ") || "(none)" : unbuilt);
     line("schedules", code ? schedules.map((s) => `${s.name} (next ${s.next ?? "never"})`).join(", ") || "(none)" : unbuilt);
     line("commands", commands.map(({ name }) => `/${name}`).join(", ") || "(none)");

package/dist/cli/commands/mcp.d.ts

@@ -0,0 +1,12 @@
+export interface McpCommandOptions {
+    json?: boolean;
+    environment?: string;
+    scopes?: string;
+    timeout?: string;
+    clientId?: string;
+    callbackPort?: string;
+    check?: string;
+    ticket?: string;
+    input?: boolean;
+}
+export declare function runMcp(action: "list" | "login" | "disconnect", server: string | undefined, dir: string, options: McpCommandOptions): Promise<void>;

package/dist/cli/commands/mcp.js

@@ -0,0 +1,156 @@
+/** MCP inspection, explicit sign-in and local binding removal. */
+import { confirm, isCancel } from "@clack/prompts";
+import { inspectMcp, mcpContext, writeMcpBinding, httpServer } from "../../mcp/host.js";
+import { signInMcp } from "../../mcp/sign-in.js";
+import { holdingInstance } from "../../harnesses/pi-durable/serve.js";
+import { resolveMcpServers } from "../../mcp/config.js";
+import { McpError } from "../../mcp-api.js";
+import { selectAgentEnvironment } from "../../paths.js";
+import { enterAgentEnv } from "../../env.js";
+import { openExternalUrl } from "../../open-url.js";
+import { isInteractive, shellArg } from "../shared.js";
+import { agentDirOrExit, failStartup, failUsage } from "../fail.js";
+import { checkTicket, refusedCheck, runTicket, startTicket, ticketExitCode, ticketReport, printReport, } from "../ticket.js";
+const CHECK = "fastagent mcp login --check";
+function report(ticket, json, when) {
+    const result = ticketReport(ticket, when, (value) => ({
+        fields: value,
+        text: ["MCP authorization saved and bound; reopen the agent to use it"],
+        next: "Reopen the agent to use its MCP tools.",
+    }));
+    printReport(json, result.json, result.text);
+}
+export async function runMcp(action, server, dir, options) {
+    if (options.check) {
+        const refusal = refusedCheck(options.check, CHECK);
+        if (refusal)
+            return failUsage(refusal);
+        const ticket = await checkTicket(options.check);
+        if (!ticket)
+            return failUsage("MCP sign-in ticket not found");
+        report(ticket, !!options.json, "checked");
+        process.exit(ticketExitCode(ticket));
+    }
+    const target = agentDirOrExit(dir);
+    const environment = options.environment ?? "dev";
+    if (environment !== "dev" && environment !== "production")
+        return failUsage("--env must be dev or production");
+    selectAgentEnvironment(environment);
+    enterAgentEnv(target);
+    if (action === "list") {
+        const servers = await inspectMcp(target).catch(failStartup);
+        if (options.json)
+            console.log(JSON.stringify(servers));
+        else
+            for (const item of servers)
+                console.log(`${item.name}\t${item.transport}\t${item.authorization}`);
+        return;
+    }
+    if (!server)
+        return failUsage(`mcp ${action} needs a server name from .mcp.json`);
+    const context = mcpContext(target);
+    if (action === "disconnect") {
+        await holdingInstance(context.stateRoot, () => writeMcpBinding(context.stateRoot, server, undefined)).catch(failStartup);
+        printReport(!!options.json, {
+            status: "done",
+            server,
+            grant_revoked: false,
+            agent_next_steps: "The instance binding was removed. The stored grant was not revoked; reauthorize or update .mcp.json before reopening.",
+        }, ["Binding removed; the stored grant was not revoked. Reauthorize or update .mcp.json before reopening."]);
+        return;
+    }
+    httpServer(resolveMcpServers(target, context.environment, server), server);
+    const seconds = options.timeout === undefined ? 900 : Number(options.timeout);
+    if (!Number.isInteger(seconds) || seconds <= 0)
+        return failUsage("--timeout must be a positive whole number of seconds");
+    const scopes = options.scopes
+        ?.split(",")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    const unattended = options.json || options.input === false || !isInteractive();
+    if (unattended && scopes === undefined)
+        return failUsage("mcp login without a terminal needs --scopes <comma-separated-scopes>; consult the MCP service's authorization requirements");
+    const run = async (step) => {
+        const grant = await signInMcp({
+            agentDir: target,
+            server,
+            store: context.auth.store,
+            scopes,
+            clientId: options.clientId,
+            callbackPort: options.callbackPort === undefined ? undefined : Number(options.callbackPort),
+            timeoutSeconds: seconds,
+            interaction: {
+                signal: step?.signal,
+                async confirmAuthorization(request) {
+                    const message = `Authorize ${request.server} at ${request.issuer} for ${request.scopes.join(", ") || "server-defined scopes"}?`;
+                    if (step) {
+                        console.error(`[fastagent] ${message}`);
+                        return true;
+                    }
+                    const choice = await confirm({ message, initialValue: false });
+                    return !isCancel(choice) && choice;
+                },
+                notify(event) {
+                    if (event.type === "auth_url") {
+                        const instructions = `Authorize the MCP server ${server} in your browser; scope: ${scopes?.join(", ") ?? "as approved"}. The callback is on the machine running this command; do not paste codes into chat.`;
+                        if (step)
+                            step.person.waitsOn(event.url, instructions);
+                        else {
+                            console.error(`${instructions}\n${event.url}`);
+                            openExternalUrl(event.url);
+                        }
+                    }
+                    else {
+                        step?.person.carriesOn();
+                        console.error(`[fastagent] ${event.message}`);
+                    }
+                },
+            },
+        });
+        await writeMcpBinding(context.stateRoot, server, grant.id);
+        return { server, grant_id: grant.id, scopes: grant.scopes };
+    };
+    if (options.ticket) {
+        await runTicket(options.ticket, (step) => run(step));
+        process.exit(0);
+    }
+    if (unattended && scopes !== undefined) {
+        const args = [
+            process.argv[1],
+            "mcp",
+            "login",
+            server,
+            target,
+            "--env",
+            environment,
+            "--scopes",
+            scopes.join(","),
+            "--timeout",
+            String(seconds),
+        ];
+        if (options.clientId)
+            args.push("--client-id", options.clientId);
+        if (options.callbackPort)
+            args.push("--callback-port", options.callbackPort);
+        const ticket = await startTicket({
+            subject: `mcp:login:${environment}:${target}:${server}`,
+            action: `authorize MCP server ${server}`,
+            check: CHECK,
+            restart: `fastagent ${args.slice(1).map(shellArg).join(" ")}`,
+            timeoutSeconds: seconds,
+            whenRunning: "replace",
+            waitsFirst: false,
+            command: { file: process.execPath, args: [...process.execArgv, ...args], cwd: process.cwd() },
+        });
+        report(ticket, !!options.json, "started");
+        process.exit(ticketExitCode(ticket));
+    }
+    const result = await run().catch((error) => {
+        if (error instanceof McpError && error.code === "canceled")
+            return failUsage(error.message);
+        return failStartup(error);
+    });
+    printReport(!!options.json, { status: "done", ...result }, [
+        "MCP authorization saved and bound; reopen the agent to use it",
+    ]);
+}

package/dist/cli/program.js

@@ -703,6 +703,64 @@ const auth = {
         },
     ],
 };
+const mcp = {
+    name: "mcp",
+    summary: "inspect MCP servers and manage explicit OAuth bindings",
+    subcommands: [
+        {
+            name: "list",
+            summary: "inspect declarations and local auth",
+            description: "Read .mcp.json and local grant metadata without contacting servers.",
+            examples: [{ cmd: "fastagent mcp list --json" }],
+            args: [AGENT_ARG],
+            flags: [CHANNEL_ENVIRONMENT, JSON_FLAG],
+            run: async (args, f) => (await import("./commands/mcp.js")).runMcp("list", undefined, args[0], {
+                json: f.json === true,
+                environment: f.env,
+            }),
+        },
+        {
+            name: "login",
+            summary: "sign in to an MCP server",
+            description: "Authorize in the browser and save an explicit grant binding for this instance.",
+            examples: [
+                { cmd: "fastagent mcp login linear --scopes read --json" },
+                { cmd: "fastagent mcp login --check <ticket> --json" },
+            ],
+            args: [{ name: "[server]", description: "the server name in .mcp.json" }, AGENT_ARG],
+            flags: [
+                CHANNEL_ENVIRONMENT,
+                ...UNATTENDED_SETUP,
+                { flags: "--scopes <scopes>", description: "comma-separated OAuth scopes; required without a terminal" },
+                { flags: "--client-id <id>", description: "a pre-registered public client ID or client metadata URL" },
+                { flags: "--callback-port <port>", description: "local callback port (default: allocate an available port)" },
+            ],
+            run: async (args, f) => (await import("./commands/mcp.js")).runMcp("login", args[0], args[1], {
+                json: f.json === true,
+                input: f.input !== false,
+                environment: f.env,
+                scopes: f.scopes,
+                clientId: f.clientId,
+                callbackPort: f.callbackPort,
+                check: f.check,
+                ticket: f.ticket,
+                timeout: f.timeout,
+            }),
+        },
+        {
+            name: "disconnect",
+            summary: "remove a local OAuth binding",
+            description: "Remove this instance's binding without revoking or deleting a shared grant. Reopen running instances afterward.",
+            examples: [{ cmd: "fastagent mcp disconnect linear" }],
+            args: [{ name: "<server>", description: "the server name" }, AGENT_ARG],
+            flags: [CHANNEL_ENVIRONMENT, JSON_FLAG],
+            run: async (args, f) => (await import("./commands/mcp.js")).runMcp("disconnect", args[0], args[1], {
+                json: f.json === true,
+                environment: f.env,
+            }),
+        },
+    ],
+};
 /**
  * Registration order = help order — the ORIGINAL usage wall's order, kept verbatim (this is a commander refactor of
  * the same CLI, not a redesign).
@@ -710,6 +768,7 @@ const auth = {
 export const specs = [
     init,
     models,
+    mcp,
     info,
     content,
     env,

package/dist/deploy/agentcore/destroy.js

@@ -142,7 +142,7 @@ export async function destroyAgentcoreDeployment(plan, runner, announce = () =>
     // FAILURE vs WARNING is decided by whether the resource SURVIVES it, not by whether a call failed. The
     // forwarder's group is named exactly, so a `--run` deletes it by name and the failed listing changed nothing
     // — reporting `1 resource(s) survived` for a teardown that removed everything is the same false signal as the
-    // reverse, and `test/live/env.ts` treats it as a leak. In the inventory, where no delete follows, the same
+    // reverse. In the inventory, where no delete follows, the same
     // unreadable listing DOES mean the answer is incomplete.
     const failures = [];
     const warnings = [];

package/dist/deploy/build-context.js

@@ -3,6 +3,7 @@ import { isAbsolute, relative, join, sep } from "node:path";
 import ignore from "ignore";
 import { AGENT_CONFIG_FILE, CONTENT_DIRNAME, LOCAL_CONTEXT_FILE, SECRETS_DIRNAME, exists, readTextIfExists, resolveSecretsDir, resolveStateRoot, } from "../paths.js";
 import { isGeneratedDockerignore } from "./container.js";
+import { MCP_FILE } from "../mcp/config.js";
 /**
  * "Would docker's packer drop this path?" — built from a `.dockerignore`'s text via the `ignore` matcher (the same
  * library the scaffolded ignore files use), so `!` negation and last-match-wins are the library's problem, not ours.
@@ -120,6 +121,9 @@ export async function checkKeptIgnoreFiles(ctx, report) {
                 `config (the deployed box has no agent to open and crash-loops). Remove that rule before deploying.`;
             report.issue(text);
         }
+        if (excluded(MCP_FILE) && (await exists(join(agentDir, MCP_FILE)))) {
+            report.issue(`your ${rel} excludes ${MCP_FILE}; the deployment would lose its MCP servers. Remove that rule before deploying.`);
+        }
         // Resolved paths, not spellings: dockerignore patterns are root-anchored (unlike .gitignore).
         const leaks = leakCandidates.filter((p) => !excluded(p));
         if (leaks.length > 0) {

package/dist/deploy/container.js

@@ -149,8 +149,7 @@ ${deployment}`;
     //
     // `*.tgz` RIDES ALONG with the manifest, because the install layer runs BEFORE `COPY . .` and a
     // `"dep": "file:./something.tgz"` resolves against the directory it is installing in. Without this the file is
-    // not there yet and the build fails on a dependency the author can see sitting in the agent directory. It is
-    // also what lets a live probe deploy the CHECKOUT (`npm pack` output) rather than the published release.
+    // not there yet and the build fails on a dependency the author can see sitting in the agent directory.
     if (isBun) {
         // `--frozen-lockfile` needs bun.lock and hard-fails without it.
         const install = input.hasLockfile ? "bun install --frozen-lockfile" : "bun install";

package/dist/deploy/docker/run.d.ts

@@ -1,8 +1,7 @@
-/** `fastagent deploy docker --run` — reconcile the generated/user-owned Compose application locally. */
 import type { BoxLoginStep } from "../box-shell.ts";
 import type { DeclaredChannel } from "../../channels/discover.ts";
 import type { RegistrationOutcome } from "../../channels/registration.ts";
-import type { CliRunner } from "../runner.ts";
+import { type CliRunner } from "../runner.ts";
 export interface DockerRunPlan {
     /** Compose file relative to the runner cwd (the agent directory). */
     composeFile: string;
@@ -54,6 +53,11 @@ type DockerAnnounce = (baseUrl: string) => Promise<{
  * budget.
  */
 export type DockerHealthProbe = (healthUrl: string, stillStarting: () => Promise<boolean>) => Promise<boolean>;
+/**
+ * Whether something already accepts connections at `host:port`. The answer to "is the port the agent is about to
+ * publish free", asked before `up`, because afterwards a `/health` that answers cannot say whose it is.
+ */
+export type HostPortProbe = (host: string, port: number) => Promise<boolean>;
 /** A published Quick Tunnel URL, and whether its tunnel ever reported an edge connection. */
 export interface ComposeTunnel {
     url: string;
@@ -62,6 +66,15 @@ export interface ComposeTunnel {
 export type DockerTunnelUrlProbe = (docker: CliRunner, composeFile: string) => Promise<ComposeTunnel | undefined>;
 /** Resolve Docker Compose's `host:port` output to a loopback URL (safe for 0.0.0.0/[::] bindings too). */
 export declare function localUrlFromComposePort(stdout: string): string | undefined;
+/**
+ * The host ports the `agent` service publishes, from `docker compose config --format json` (Compose has already
+ * normalised every short or long syntax into `ports[]`). A port with no fixed host side (`published` unset: Docker picks
+ * one) cannot collide and is left out. A wildcard bind is asked on loopback, which is where the URL we report points.
+ */
+export declare function agentPublishedPorts(stdout: string): {
+    host: string;
+    port: number;
+}[];
 /**
  * Poll the detached cloudflared service's logs until its Quick Tunnel URL is assigned AND the tunnel reports an edge
  * connection.
@@ -71,5 +84,5 @@ export declare function waitForComposeTunnelUrl(docker: CliRunner, composeFile:
     intervalMs?: number;
     sleep?: (ms: number) => Promise<void>;
 }): Promise<ComposeTunnel | undefined>;
-export declare function deployDockerRun(plan: DockerRunPlan, docker: CliRunner, log: (message: string) => void, healthProbe?: DockerHealthProbe, tunnelUrlProbe?: DockerTunnelUrlProbe): Promise<DockerRunOutcome>;
+export declare function deployDockerRun(plan: DockerRunPlan, docker: CliRunner, log: (message: string) => void, healthProbe?: DockerHealthProbe, tunnelUrlProbe?: DockerTunnelUrlProbe, hostPortBusy?: HostPortProbe): Promise<DockerRunOutcome>;
 export {};

package/dist/deploy/docker/run.js

@@ -1,8 +1,11 @@
+/** `fastagent deploy docker --run` — reconcile the generated/user-owned Compose application locally. */
+import { connect } from "node:net";
 import { waitForHealth } from "../../channels/wait-health.js";
 import { loginGate } from "../channel-ingress.js";
 import { TUNNEL_DNS_LAG_MS, hasTunnelConnection, parseTunnelUrl } from "../../tunnel.js";
 import { registrationGate } from "../registration-gate.js";
 import { MIN_DOCKER_COMPOSE_VERSION } from "./plan.js";
+import { readOutput } from "../runner.js";
 import { missingValuesGate } from "../secrets.js";
 /** Resolve Docker Compose's `host:port` output to a loopback URL (safe for 0.0.0.0/[::] bindings too). */
 export function localUrlFromComposePort(stdout) {
@@ -18,6 +21,36 @@ export function localUrlFromComposePort(stdout) {
  * so this budget covers a copy on a slow Docker Desktop disk, not a listen.
  */
 const defaultHealthProbe = (healthUrl, stillStarting) => waitForHealth(healthUrl, 180_000, 500, stillStarting);
+const defaultHostPortBusy = (host, port) => new Promise((resolve) => {
+    const socket = connect({ host, port });
+    const answer = (busy) => {
+        socket.destroy();
+        resolve(busy);
+    };
+    socket.setTimeout(1_000, () => answer(false)); // a filtered port is not one something is serving
+    socket.once("connect", () => answer(true));
+    socket.once("error", () => answer(false));
+});
+/**
+ * The host ports the `agent` service publishes, from `docker compose config --format json` (Compose has already
+ * normalised every short or long syntax into `ports[]`). A port with no fixed host side (`published` unset: Docker picks
+ * one) cannot collide and is left out. A wildcard bind is asked on loopback, which is where the URL we report points.
+ */
+export function agentPublishedPorts(stdout) {
+    const config = JSON.parse(stdout);
+    const ports = config?.services?.agent?.ports;
+    if (ports === undefined)
+        return [];
+    if (!Array.isArray(ports))
+        throw new Error("services.agent.ports is not a list");
+    return ports.flatMap((entry) => {
+        const port = Number(entry?.published);
+        if (!Number.isInteger(port) || port <= 0 || (entry.protocol ?? "tcp") !== "tcp")
+            return [];
+        const wildcard = !entry.host_ip || entry.host_ip === "0.0.0.0" || entry.host_ip === "::";
+        return [{ host: wildcard ? "127.0.0.1" : entry.host_ip, port }];
+    });
+}
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
  * Poll the detached cloudflared service's logs until its Quick Tunnel URL is assigned AND the tunnel reports an edge
@@ -59,7 +92,7 @@ async function containerHealthy(docker, compose, port, stillStarting) {
     }
     return false;
 }
-export async function deployDockerRun(plan, docker, log, healthProbe = defaultHealthProbe, tunnelUrlProbe = defaultTunnelUrlProbe) {
+export async function deployDockerRun(plan, docker, log, healthProbe = defaultHealthProbe, tunnelUrlProbe = defaultTunnelUrlProbe, hostPortBusy = defaultHostPortBusy) {
     const gate = (message) => ({ ok: false, gate: message });
     const compose = ["compose", "-f", plan.composeFile];
     // CLI/plugin gate first: unlike a daemon error, spawn ENOENT becomes 127 at the shared runner seam.
@@ -99,6 +132,26 @@ export async function deployDockerRun(plan, docker, log, healthProbe = defaultHe
         return gate(`--tunnel was requested but the kept ${plan.composeFile} has no "tunnel" service — ` +
             `edit it, delete it and regenerate, or pass --force`);
     }
+    // A port something else already serves would answer the `/health` this run waits for, and the run would report that
+    // process's answer as the agent's. A container this project already runs holds its own port, so only a first start
+    // (or a start after `down`) asks. Before the first side effect: a refusal leaves nothing to undo.
+    const hostPorts = await readOutput(docker, "docker", [...compose, "config", "--format", "json"], agentPublishedPorts);
+    if ("gate" in hostPorts)
+        return gate(hostPorts.gate);
+    if (hostPorts.value.length > 0) {
+        const running = await docker([...compose, "ps", "--status", "running", "--services"], { capture: true });
+        const ours = running.code === 0 && running.stdout.split(/\s+/).includes("agent");
+        if (!ours) {
+            for (const { host, port } of hostPorts.value) {
+                if (await hostPortBusy(host, port)) {
+                    return gate(`${host}:${port} is already in use by another process, so the agent's published port is not free and a ` +
+                        `health check there would answer for that process, not for the agent — stop it, or move the agent: ` +
+                        `edit the published port in ${plan.composeFile}, or change http.port in fastagent.config.ts and re-run ` +
+                        `with --force (a generated Compose file is kept otherwise)`);
+                }
+            }
+        }
+    }
     // Quick Tunnel logs are the control-plane output (the assigned URL).
     if (hasTunnel) {
         log("recreating the ephemeral tunnel service…");