@fastagent-sh/fastagent 0.27.0 → 0.29.0

package/dist/cli/content-view.js

@@ -8,13 +8,13 @@ function contentKind(c) {
     return c.clone ? `${github}, a clone brought up to date at each start` : `${github}, your checkout bound here`;
 }
 /**
- * The report lines for an agent's content — `works on` / `knows`, one per entry, then a `notice` line for each
+ * The report lines for an agent's content — `works on`, one per entry, then a `notice` line for each
  * thing its resolution has to say, then one for each directory this machine binds that is not here — shared by the
  * startup report, `info` and `content list`, so the three say the same thing.
  */
 export function contentLines(content, absent = []) {
     const lines = content.flatMap((c) => [
-        [c.readonly ? "knows" : "works on", `${c.name.padEnd(width(content))}  ${c.location} (${contentKind(c)})`],
+        ["works on", `${c.name.padEnd(width(content))}  ${c.location} (${contentKind(c)})`],
         ...c.notices.map((notice) => ["notice", `${c.name}: ${notice}`]),
     ]);
     for (const binding of absent)

package/dist/cli/program.js

@@ -56,7 +56,7 @@ const init = {
     ],
     notes: "An agent is a directory holding a fastagent.config.ts, and it is also the agent's working directory. " +
         "It lives in a directory of its own, never inside a project or another agent: what it works on is declared " +
-        "as its content. Add a directory it only knows later with `fastagent content add <dir> --readonly`.",
+        "as its content. Add a directory later with `fastagent content add <dir>`.",
     run: async (args, f) => (await import("./commands/init.js")).runInit(args[0], {
         install: f.install !== false,
         content: f.content ?? [],
@@ -434,14 +434,14 @@ const env = {
 };
 const content = {
     name: "content",
-    summary: "list, add or remove what the agent works on and knows",
-    description: "Content is a directory the agent works on (or only knows, with --readonly): a GitHub repository declared " +
+    summary: "list, add or remove what the agent works on",
+    description: "Content is a directory the agent works on: a GitHub repository declared " +
         "by name in context.json, shared with the agent and cloned at content/<name>, or a directory of this " +
         "machine bound in context.local.json, which never leaves it.",
     subcommands: [
         {
             name: "list",
-            summary: "each content entry, where it is, and whether the agent works on it or only knows it",
+            summary: "each content entry and where it is",
             args: [AGENT_ARG],
             flags: [JSON_FLAG],
             examples: [{ cmd: "fastagent content list" }],
@@ -452,15 +452,13 @@ const content = {
             summary: "add a GitHub repository, or bind a directory of this machine, as content",
             args: [{ name: "<source>", description: "a directory, or github:owner/repo" }, AGENT_ARG],
             flags: [
-                { flags: "--readonly", description: "the agent knows it and does not write it" },
                 { flags: "--ref <ref>", description: "a repository: the branch, tag or commit to clone" },
                 { flags: "--name <name>", description: "its name (default: the directory's or repository's)" },
                 { flags: "--description <text>", description: "one sentence for the agent: what it is, how to treat it" },
             ],
             examples: [
-                { cmd: "fastagent content add ~/code/app", note: "works on" },
-                { cmd: "fastagent content add ~/handbook --readonly", note: "knows" },
-                { cmd: "fastagent content add github:acme/docs --readonly", note: "knows a clone" },
+                { cmd: "fastagent content add ~/code/app", note: "a directory of this machine" },
+                { cmd: "fastagent content add github:acme/docs", note: "a clone" },
             ],
             notes: "The root of a GitHub checkout is declared in context.json as that repository, and bound in " +
                 "context.local.json to the checkout, used as it is on this machine. github:owner/repo is cloned into " +
@@ -469,7 +467,6 @@ const content = {
                 "Any other directory is bound in context.local.json only: a deployed instance works without it. A bound " +
                 "directory may not contain the agent directory, nor sit inside it.",
             run: async (args, f) => (await import("./commands/content.js")).runContentAdd(args[0], args[1], {
-                readonly: f.readonly === true,
                 ...(typeof f.ref === "string" ? { ref: f.ref } : {}),
                 ...(typeof f.name === "string" ? { name: f.name } : {}),
                 ...(typeof f.description === "string" ? { description: f.description } : {}),
@@ -706,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).
@@ -713,6 +768,7 @@ const auth = {
 export const specs = [
     init,
     models,
+    mcp,
     info,
     content,
     env,

package/dist/content/declare.d.ts

@@ -4,8 +4,6 @@ export interface ContentEntry {
     github: string;
     /** The branch, tag or commit to clone. */
     ref?: string;
-    /** The agent knows it and does not write it. */
-    readonly?: boolean;
     /** One sentence for the agent: what this is, and how to treat it. */
     description?: string;
 }
@@ -15,7 +13,6 @@ export interface DeclaredContent {
     /** `owner/repo`. */
     repo: string;
     ref?: string;
-    readonly: boolean;
     description?: string;
 }
 /**
@@ -25,7 +22,6 @@ export interface DeclaredContent {
 export interface ContentBinding {
     /** Absolute, `~/`, or relative to the agent directory. */
     path: string;
-    readonly?: boolean;
     description?: string;
 }
 /** A binding, read: `path` absolute. */
@@ -38,7 +34,6 @@ export type BoundContent = {
 } | {
     /** A directory only this machine has. */
     kind: "local";
-    readonly: boolean;
     description?: string;
 });
 /** What an agent's content is declared as: the shared declaration, and this machine's bindings. */
@@ -64,7 +59,7 @@ export declare function declareContent(raw: unknown): DeclaredContent[];
 export declare function declareBindings(raw: unknown, declared: readonly DeclaredContent[], agentDir: string): BoundContent[];
 /**
  * A directory the agent is bound to and the agent directory are kept apart (agent-model.md §2): a definition is
- * released, writable content is kept, and one directory cannot be both. The ONE statement of the rule; resolve.ts asks
+ * released, content is kept, and one directory cannot be both. The ONE statement of the rule; resolve.ts asks
  * it of the real paths.
  */
 export declare function nestingError(agentDir: string, location: string, name: string): string | undefined;

package/dist/content/declare.js

@@ -1,5 +1,5 @@
 /**
- * WHAT AN AUTHOR DECLARES an agent works on or knows, read and refused in ONE place (file.ts reads the files through
+ * WHAT AN AUTHOR DECLARES an agent works on, read and refused in ONE place (file.ts reads the files through
  * it): the `content` map of `context.json`, which is shared and so holds only repositories every instance reaches, and
  * the `content` map of `context.local.json`, the directories of this machine it is bound to. Pure: what is on the disk
  * is resolve.ts's question. docs/design/agent-model.md §3 is the rule.
@@ -11,8 +11,8 @@ import { CONTEXT_FILE, LOCAL_CONTEXT_FILE, isUnderDir } from "../paths.js";
  * The keys an entry and a binding carry, in the order they are written: where it is, then how it is treated. One list
  * each, so a key the reader accepts is one the writer keeps.
  */
-const ENTRY_KEYS = ["github", "ref", "readonly", "description"];
-const BINDING_KEYS = ["path", "readonly", "description"];
+const ENTRY_KEYS = ["github", "ref", "description"];
+const BINDING_KEYS = ["path", "description"];
 /** A name becomes a directory name, so it is one path segment (the spelling a release's agent name has). */
 const NAME = /^[A-Za-z0-9_-]+$/;
 /** Whether `name` can name a content entry. */
@@ -62,16 +62,14 @@ export function declareBindings(raw, declared, agentDir) {
             if (shared.name !== name) {
                 throw new Error(`${at} binds the entry ${CONTEXT_FILE} names "${shared.name}": spell it the same`);
             }
-            for (const key of ["readonly", "description"]) {
-                if (e[key] !== undefined) {
-                    throw new Error(`${at} binds this machine's checkout of the entry ${CONTEXT_FILE} declares, which says "${key}" for ` +
-                        `every instance: give it only "path"`);
-                }
+            if (e.description !== undefined) {
+                throw new Error(`${at} binds this machine's checkout of the entry ${CONTEXT_FILE} declares, which says "description" for ` +
+                    `every instance: give it only "path"`);
             }
             return { name, path, kind: "checkout" };
         }
-        const treatment = treatmentOf(at, e);
-        return { name, path, kind: "local", ...treatment };
+        const description = descriptionOf(at, e);
+        return { name, path, kind: "local", ...(description !== undefined ? { description } : {}) };
     });
 }
 /** `path` as written in `context.local.json`, absolute: `~/` is the home directory, a relative one the agent's. */
@@ -112,14 +110,11 @@ function objectWithKeys(at, value, keys) {
     }
     return e;
 }
-function treatmentOf(at, e) {
+function descriptionOf(at, e) {
     if (e.description !== undefined && (typeof e.description !== "string" || e.description === "")) {
         throw new Error(`${at}: "description" must be a non-empty string`);
     }
-    if (e.readonly !== undefined && typeof e.readonly !== "boolean")
-        throw new Error(`${at}: "readonly" must be a boolean`);
-    const description = e.description;
-    return { readonly: e.readonly === true, ...(description !== undefined ? { description } : {}) };
+    return e.description;
 }
 function declareOne(name, entry) {
     const at = `content "${name}"`;
@@ -129,7 +124,7 @@ function declareOne(name, entry) {
             throw new Error(`${at}: "${key}" must be a non-empty string`);
         }
     }
-    const treatment = treatmentOf(at, e);
+    const description = descriptionOf(at, e);
     if (e.github === undefined) {
         throw new Error(`${at} needs "github": ${CONTEXT_FILE} is shared, so it declares only what every instance reaches — bind a ` +
             `directory of this machine in ${LOCAL_CONTEXT_FILE} instead (fastagent content add <dir>)`);
@@ -141,11 +136,11 @@ function declareOne(name, entry) {
     // git reads a leading "-" as an option, and no branch, tag or commit name has one.
     if (ref?.startsWith("-"))
         throw new Error(`${at}: "ref" must name a branch, tag or commit, got "${ref}"`);
-    return { name, repo, ...(ref !== undefined ? { ref } : {}), ...treatment };
+    return { name, repo, ...(ref !== undefined ? { ref } : {}), ...(description !== undefined ? { description } : {}) };
 }
 /**
  * A directory the agent is bound to and the agent directory are kept apart (agent-model.md §2): a definition is
- * released, writable content is kept, and one directory cannot be both. The ONE statement of the rule; resolve.ts asks
+ * released, content is kept, and one directory cannot be both. The ONE statement of the rule; resolve.ts asks
  * it of the real paths.
  */
 export function nestingError(agentDir, location, name) {

package/dist/content/resolve.d.ts

@@ -4,8 +4,6 @@ import { type CloneOutcome } from "./git.ts";
 export type ResolvedContent = {
     /** Unique within the agent, ignoring case; one path segment. */
     name: string;
-    /** The agent knows it and does not write it. */
-    readonly: boolean;
     /** What the declaration tells the agent about it. */
     description?: string;
     /** Where the agent reaches it on this instance, absolute. */

package/dist/content/resolve.js

@@ -33,10 +33,9 @@ export function absentNotice(binding) {
         `not told of it`);
 }
 function resolveRepository(agentDir, entry, checkout) {
-    const { name, readonly, description } = entry;
+    const { name, description } = entry;
     const repository = {
         name,
-        readonly,
         ...(description !== undefined ? { description } : {}),
         kind: "github",
         repo: entry.repo,
@@ -62,12 +61,11 @@ function resolveRepository(agentDir, entry, checkout) {
     return { ...repository, location, notices, clone: true };
 }
 function resolveLocal(agentDir, binding) {
-    const { name, readonly, description } = binding;
+    const { name, description } = binding;
     const location = realpathSync(binding.path);
     checkBinding(agentDir, name, location);
     return {
         name,
-        readonly,
         ...(description !== undefined ? { description } : {}),
         location,
         notices: [],

package/dist/content/source.d.ts

@@ -1,6 +1,5 @@
 import { type ContentBinding, type ContentEntry } from "./declare.ts";
 export interface SourceOptions {
-    readonly?: boolean;
     name?: string;
     /** A github entry's branch, tag or commit. */
     ref?: string;

package/dist/content/source.js

@@ -14,7 +14,6 @@ import { checkoutOf, githubRepoOf } from "./git.js";
  */
 export function readContentSource(source, cwd, options = {}) {
     const treated = {
-        ...(options.readonly ? { readonly: true } : {}),
         ...(options.description !== undefined ? { description: options.description } : {}),
     };
     const ref = options.ref !== undefined ? { ref: options.ref } : {};

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…");

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

@@ -37,18 +37,4 @@ export type FlyRunOutcome = {
     ok: false;
     gate: string;
 };
-/**
- * Which PUBLIC ingress families `fly ips list --json` shows — asked per family, because "has an ingress address" is
- * not the question the two allocate commands answer.
- */
-export declare function ingressAddresses(stdout: string): {
-    v4: boolean;
-    v6: boolean;
-};
-/**
- * Whether `fly apps list --json` lists an app called `name`. flyctl capitalizes the field; the live probe
- * (test/live/fly.live.test.ts) is what pins that against real output, since an offline fixture can only repeat what
- * we already believe.
- */
-export declare function listHasName(stdout: string, name: string): boolean;
 export declare function deployFlyRun(plan: FlyRunPlan, fly: CliRunner, log: (msg: string) => void, registrars: Registrars, healthProbe?: PublicHealthProbe): Promise<FlyRunOutcome>;

package/dist/deploy/fly/run.js

@@ -10,7 +10,7 @@ const INGRESS_TYPES = { v4: ["v4", "shared_v4"], v6: ["v6"] };
  * Which PUBLIC ingress families `fly ips list --json` shows — asked per family, because "has an ingress address" is
  * not the question the two allocate commands answer.
  */
-export function ingressAddresses(stdout) {
+function ingressAddresses(stdout) {
     const entries = JSON.parse(stdout);
     if (!Array.isArray(entries))
         throw new Error(`expected a JSON array, got ${typeof entries}`);
@@ -18,11 +18,10 @@ export function ingressAddresses(stdout) {
     return { v4: has(INGRESS_TYPES.v4), v6: has(INGRESS_TYPES.v6) };
 }
 /**
- * Whether `fly apps list --json` lists an app called `name`. flyctl capitalizes the field; the live probe
- * (test/live/fly.live.test.ts) is what pins that against real output, since an offline fixture can only repeat what
- * we already believe.
+ * Whether `fly apps list --json` lists an app called `name`. flyctl capitalizes the field, and an
+ * offline fixture can only repeat what we already believe, so a change in flyctl's output is not caught here.
  */
-export function listHasName(stdout, name) {
+function listHasName(stdout, name) {
     const entries = JSON.parse(stdout);
     if (!Array.isArray(entries))
         throw new Error(`expected a JSON array, got ${typeof entries}`);

package/dist/deploy/preflight.js

@@ -27,33 +27,25 @@ import { checkPackages, MISE_PACKAGE_NAMES, miseBinary, packageSpecs } from "../
 /**
  * What each content entry becomes on the host, one line each, so none is missing there unsaid (agent-model.md §3). A
  * repository `context.json` declares is cloned there, as on this machine without a checkout bound. A directory only
- * this machine binds stays here: the deployed agent works without it, which the line says and says how to change. One
- * the agent works on is a warning, since the deployed agent lacks data it was meant to work on; one it only knows, a
- * note.
+ * this machine binds stays here: the deployed agent works without it, which the line says and says how to change. It
+ * is a warning, since the deployed agent lacks data it was meant to work on.
  */
 function checkContent({ declared, bound }, storageResets, report) {
     for (const entry of declared) {
         const fate = storageResets
             ? "cloned afresh on every deployment, since the host's storage starts over; what the agent did not push is lost"
             : "cloned on the host, and brought up to date in place at each start";
-        report.note(`${roleOf(entry)} ${entry.name}: github ${entry.repo}${entry.ref ? `@${entry.ref}` : ""}, ${fate}`);
+        report.note(`works on ${entry.name}: github ${entry.repo}${entry.ref ? `@${entry.ref}` : ""}, ${fate}`);
     }
     for (const binding of bound) {
         if (binding.kind !== "local")
             continue;
-        const stays = `${roleOf(binding)} ${binding.name}: a directory of this machine (${binding.path}, bound in ` +
+        const stays = `works on ${binding.name}: a directory of this machine (${binding.path}, bound in ` +
             `${LOCAL_CONTEXT_FILE}), stays here, and the deployed agent works without it`;
-        if (binding.readonly) {
-            report.note(`${stays}; to ship what the agent reads there, copy it into the agent directory, which every release carries`);
-        }
-        else {
-            report.warn(`${stays}; to work on it from a host, move it to a GitHub repository and add it as github:owner/repo`);
-        }
+        report.warn(`${stays}; to work on it from a host, move it to a GitHub repository and add it as github:owner/repo, or copy ` +
+            `what it only needs to read there into the agent directory, which every release carries`);
     }
 }
-function roleOf(entry) {
-    return entry.readonly ? "knows" : "works on";
-}
 /**
  * What the image needs to install the packages the agent declares: the agent's own mise for linux in its package.json,
  * so the image's install brings it, packages FastAgent installs from, and a PyPI package's runtime. A machine without

package/dist/dev-supervisor.js

@@ -7,6 +7,7 @@ import { relative, sep } from "node:path";
 import { watch as watchTree } from "chokidar";
 import { AGENT_CONFIG_FILE, CONTEXT_FILE, LOCAL_CONTEXT_FILE, resolveStateRoot, isUnderDir } from "./paths.js";
 import { dotEnvPath } from "./value-file.js";
+import { MCP_FILE } from "./mcp/config.js";
 import { log } from "./log.js";
 import { openExternalUrl } from "./open-url.js";
 import { declaredChannels } from "./channels/discover.js";
@@ -14,7 +15,7 @@ import { activeWork } from "./channels/busy.js";
 import { announceWebhooks, startCloudflareTunnel } from "./tunnel.js";
 /** The agent's code (its tools, extensions, channels and schedules), loaded ONCE per worker: a restart is its only re-read. */
 const CODE_DIR = "src";
-const WATCHED_HINT = `${CODE_DIR}/, package.json, fastagent.config.ts, context.json, context.local.json, .secrets/.env`;
+const WATCHED_HINT = `${CODE_DIR}/, package.json, fastagent.config.ts, context.json, context.local.json, .mcp.json, .secrets/.env`;
 /** chokidar `ignored` matcher for the narrow watch scope (true = ignore), rooted at the AGENT DIR. */
 export function devWatchIgnored(root, envFile) {
     // The `.env` is allow-listed by its RESOLVED path, not by the `.secrets` name.
@@ -27,7 +28,7 @@ export function devWatchIgnored(root, envFile) {
         // their only re-read).
         if (rel === AGENT_CONFIG_FILE || rel === CONTEXT_FILE || rel === LOCAL_CONTEXT_FILE)
             return false;
-        if (rel === "package.json")
+        if (rel === "package.json" || rel === MCP_FILE)
             return false;
         const segments = rel.split(sep);
         if (segments[0] === CODE_DIR)

package/dist/harnesses/pi-durable/mcp.d.ts

@@ -0,0 +1,3 @@
+import { type ToolRegistration } from "@earendil-works/pi-durable";
+import type { McpTool } from "../../mcp/client.ts";
+export declare function mcpTools(tools: readonly McpTool[]): ToolRegistration[];

package/dist/harnesses/pi-durable/mcp.js

@@ -0,0 +1,34 @@
+/** MCP tools on pi-durable. No replay promise is inferred from a server's annotations. */
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-durable";
+import { McpError } from "../../mcp-api.js";
+export function mcpTools(tools) {
+    return tools.map((tool) => defineTool({
+        name: tool.name,
+        description: tool.definition.description ?? `MCP tool ${tool.definition.name} from ${tool.server}`,
+        parameters: Type.Unsafe(tool.definition.inputSchema),
+        replay: "unsafe",
+        execute: async (args, api, context) => {
+            try {
+                const result = await tool.call(args, context.abortSignal, (text) => api.output(text));
+                if (result.content.some((part) => part.type !== "text"))
+                    throw new McpError("protocol", "MCP tool returned unsupported content; only text/JSON is supported", tool.server);
+                const output = result.content.flatMap((part) => part.type === "text" ? [{ type: "text", text: part.text }] : []);
+                if (result.structuredContent !== undefined)
+                    output.push({ type: "text", text: JSON.stringify(result.structuredContent) });
+                return { output, ...(result.isError ? { isError: true } : {}) };
+            }
+            catch (error) {
+                context.abortSignal?.throwIfAborted();
+                if (!(error instanceof McpError))
+                    throw error;
+                // Preserve actionable auth/connection classification in the existing tool-result details.
+                return {
+                    output: [{ type: "text", text: error.message }],
+                    isError: true,
+                    details: { mcp: { server: tool.server, code: error.code } },
+                };
+            }
+        },
+    }));
+}