@yitom/agy-acp-map 0.1.14 → 0.1.17

package/README.md

@@ -95,7 +95,7 @@ Configure on **`session/new`** (preferred) and/or env fallbacks. Stored on the S
 | `--sandbox` | `sandbox: true` | `AGY_ACP_SANDBOX=1` |
 | `--json-schema` | `jsonSchema` (string or object→stringify) | `AGY_ACP_JSON_SCHEMA` (string or path) |
 | `--conversation` | `conversationId` (resume / switch-model flow) | _(from prior turn)_ |
-| `--dangerously-skip-permissions` | `safety: 'autonomous' \| 'autonomous-unsandboxed'` or `skipPermissions: true` | `AGY_ACP_SAFETY=…` / `AGY_ACP_SKIP_PERMISSIONS=1` if safety unset (**default off / safe**) |
+| `--dangerously-skip-permissions` | `safety: 'autonomous' \| 'autonomous-unsandboxed'` or `skipPermissions: true` | `AGY_ACP_SAFETY=…` / `AGY_ACP_SKIP_PERMISSIONS=1` if safety unset (**default: skip on, unsandboxed**) |
 | `--disable-slash-commands` | `disableSlashCommands` (default **true**) | `AGY_ACP_DISABLE_SLASH_COMMANDS=0` to omit |
 | `--print-timeout` | `printTimeout` (e.g. `30m`, `120s`, `0`) | `AGY_ACP_PRINT_TIMEOUT` (default `0`) |
 
@@ -159,7 +159,7 @@ Display-history path: `~/.agy-acp-map/history/`. Override with `AGY_ACP_HISTORY_
 | Env | Default | Meaning |
 |-----|---------|---------|
 | `AGY_ACP_SAFETY` | `safe` | `safe` \| `autonomous` \| `autonomous-unsandboxed` (aliases: `unsandboxed`, `autonomous_unsandboxed`). See Safety modes table. |
-| `AGY_ACP_SKIP_PERMISSIONS` | `0` | If **safety unset**: `1` ≈ treat as `autonomous`; `0` ≈ `safe`. Explicit `AGY_ACP_SAFETY` / `session.safety` wins. |
+| `AGY_ACP_SKIP_PERMISSIONS` | `0` | If **safety unset**: `1` ≈ treat as `autonomous-unsandboxed`; `0` ≈ `safe`. Explicit `AGY_ACP_SAFETY` / `session.safety` wins. |
 | `AGY_ACP_DISABLE_SLASH_COMMANDS` | `1` | When `1` (default), pass `--disable-slash-commands`. Set `0` to omit. |
 | `AGY_ACP_PRINT_TIMEOUT` | `0` | Passed as `--print-timeout` (e.g. `30m`, `120s`, `0` = wait until turn completes). |
 | `AGY_BIN` | `agy` | Override binary |
@@ -167,7 +167,7 @@ Display-history path: `~/.agy-acp-map/history/`. Override with `AGY_ACP_HISTORY_
 | `AGY_ACP_EFFORT` | — | Default `--effort` |
 | `AGY_ACP_MODE` | — | Default `--mode` |
 | `AGY_ACP_AGENT` | — | Default `--agent` |
-| `AGY_ACP_SANDBOX` | — | `1`/`0` → force sandbox on/off for `safe`/`autonomous`. Ignored for `autonomous-unsandboxed` (never sandboxed). |
+| `AGY_ACP_SANDBOX` | — | `1`/`0` → force sandbox on/off for `safe`/`autonomous`/defaulted tier. Ignored only when `autonomous-unsandboxed` was explicitly selected. |
 | `AGY_ACP_JSON_SCHEMA` | — | Schema string or file path for `--json-schema` |
 | `AGY_ACP_KEEP_STAGING` | — | `1` → keep `.agy-acp-staging` files after turn/close (debug) |
 | `AGY_ACP_STORE` / `AGY_ACP_SESSION_STORE` | `~/.agy-acp-map/sessions.json` | Disk session index path (`SESSION_STORE` wins if both set) |
@@ -209,15 +209,15 @@ No interactive ACP permission UI — **launch strategies only** (`resolveSafety`
 
 | Mode / 模式 | Skip permissions / 跳过权限 | Sandbox / 沙箱 |
 |-------------|------------------------------|----------------|
-| **safe** (default) | no — rely on agy `settings.json` allow/deny + soft-deny messages | only if user sets `sandbox: true` / `AGY_ACP_SANDBOX=1` |
+| **safe** | no — rely on agy `settings.json` allow/deny + soft-deny messages | only if user sets `sandbox: true` / `AGY_ACP_SANDBOX=1` |
 | **autonomous** | yes (`--dangerously-skip-permissions`) | **default `--sandbox`** unless user sets `sandbox: false` / `AGY_ACP_SANDBOX=0` |
-| **autonomous-unsandboxed** (aliases: `autonomous_unsandboxed`, `unsandboxed`) | yes (`--dangerously-skip-permissions`) | **never** pass `--sandbox` (explicit dangerous tier; ignores sandbox overrides) |
+| **autonomous-unsandboxed** (default; aliases: `autonomous_unsandboxed`, `unsandboxed`) | yes (`--dangerously-skip-permissions`) | **never** when explicitly selected (ignores sandbox overrides); the defaulted tier honors explicit `sandbox: true` / `AGY_ACP_SANDBOX=1` |
 
 Accept via:
 - `session/new` field `safety`: `'safe' | 'autonomous' | 'autonomous-unsandboxed'`
 - env `AGY_ACP_SAFETY` (same values)
 - idle `session/set_config_option` with `configId: "safety"`
-- Backward compat: `AGY_ACP_SKIP_PERMISSIONS=1` ≈ `autonomous` **if safety unset**; `=0` ≈ `safe`
+- Backward compat: `AGY_ACP_SKIP_PERMISSIONS=1` ≈ `autonomous-unsandboxed` **if safety unset**; `=0` ≈ `safe`
 
 输入：`session/new.safety` / `AGY_ACP_SAFETY` / `set_config_option`；兼容 `AGY_ACP_SKIP_PERMISSIONS`（仅在未设 safety 时生效）。
 

package/dist/bin.js

@@ -10750,14 +10750,15 @@ function normalizePrintTimeout(v) {
   return s === "" ? undefined : s;
 }
 function resolveSafety(session = {}, env = process.env) {
-  let safety = normalizeSafety(session.safety) ?? normalizeSafety(env.AGY_ACP_SAFETY) ?? undefined;
+  const explicitSafety = normalizeSafety(session.safety) ?? normalizeSafety(env.AGY_ACP_SAFETY) ?? undefined;
+  let safety = explicitSafety;
   if (!safety) {
     const envSkip = env.AGY_ACP_SKIP_PERMISSIONS;
     if (envSkip !== undefined && envSkip !== "") {
       const skip = !(envSkip === "0" || envSkip === "false" || envSkip === "no");
-      safety = skip ? "autonomous" : "safe";
+      safety = skip ? "autonomous-unsandboxed" : "safe";
     } else {
-      safety = "autonomous";
+      safety = "autonomous-unsandboxed";
     }
   }
   let skipPermissions = safety === "autonomous" || safety === "autonomous-unsandboxed";
@@ -10765,7 +10766,7 @@ function resolveSafety(session = {}, env = process.env) {
     skipPermissions = Boolean(session.skipPermissions);
   }
   let sandbox;
-  if (safety === "autonomous-unsandboxed") {
+  if (safety === "autonomous-unsandboxed" && explicitSafety === "autonomous-unsandboxed") {
     sandbox = false;
   } else if (session.sandbox !== undefined) {
     sandbox = Boolean(session.sandbox);
@@ -11692,7 +11693,7 @@ function formatSoftDenyMessage(denies) {
       bits.push(`(via ${d.source})`);
     lines.push(bits.join(" "));
   }
-  lines.push("Or set AGY_ACP_SAFETY=safe / AGY_ACP_SKIP_PERMISSIONS=0 to re-enable permission checks (autonomous + sandbox is the bridge default).");
+  lines.push("Or set AGY_ACP_SAFETY=safe / AGY_ACP_SKIP_PERMISSIONS=0 to re-enable permission checks (autonomous-unsandboxed — full permissions, no sandbox — is the bridge default; AGY_ACP_SAFETY=autonomous re-enables sandbox containment).");
   if (denies.some((d) => d.source?.includes("sandbox"))) {
     lines.push("Sandbox note: --sandbox = terminal restrictions, not verified offline. Built-in search may still work; if `curl`/`Invoke-WebRequest` failed, retry once with safety=autonomous-unsandboxed (or sandbox:false) to confirm it is a sandbox network block.");
   }
@@ -12540,11 +12541,183 @@ class SessionHistoryStore {
   }
 }
 
+// src/lib/mcp-servers.ts
+import { execFile } from "node:child_process";
+function fail(msg) {
+  throw new RequestError(-32602, msg);
+}
+function nonEmptyString(v) {
+  return typeof v === "string" && v.length > 0;
+}
+function strArray(v, what) {
+  if (v === undefined)
+    return [];
+  if (!Array.isArray(v) || v.some((x) => typeof x !== "string")) {
+    fail(`mcpServers[].${what} must be an array of strings`);
+  }
+  return v;
+}
+function nameValueList(v, what) {
+  if (v === undefined)
+    return [];
+  if (!Array.isArray(v))
+    fail(`mcpServers[].${what} must be an array`);
+  return v.map((e, i) => {
+    if (!e || typeof e !== "object")
+      fail(`mcpServers[].${what}[${i}] must be {name, value}`);
+    const rec = e;
+    if (!nonEmptyString(rec.name) || typeof rec.value !== "string") {
+      fail(`mcpServers[].${what}[${i}] must be {name: string, value: string}`);
+    }
+    return { name: rec.name, value: rec.value };
+  });
+}
+function normalizeMcpServer(input) {
+  if (!input || typeof input !== "object")
+    fail("mcpServers[] must be an object");
+  const s = input;
+  if (!nonEmptyString(s.name))
+    fail("mcpServers[].name must be a non-empty string");
+  const name = s.name.trim();
+  if (name.length > 64 || /[\s\x00-\x1f]/.test(name)) {
+    fail(`mcpServers[].name must be ≤64 chars with no whitespace: ${JSON.stringify(name)}`);
+  }
+  const t = typeof s.type === "string" ? s.type.trim().toLowerCase() : "";
+  if (t === "sse" || t === "acp") {
+    fail(`mcpServers[] '${name}': type '${t}' has no 'agy mcp add' equivalent ` + `(agy supports stdio|http only). Resend as stdio or http.`);
+  }
+  if (t !== "" && t !== "stdio" && t !== "http") {
+    fail(`mcpServers[] '${name}': unknown type ${JSON.stringify(s.type)} (want stdio|http)`);
+  }
+  const hasCommand = nonEmptyString(s.command);
+  const hasUrl = nonEmptyString(s.url);
+  if (hasCommand && hasUrl) {
+    fail(`mcpServers[] '${name}': ambiguous (both command and url set); send one`);
+  }
+  if (t === "http" || !hasCommand && hasUrl) {
+    if (!hasUrl)
+      fail(`mcpServers[] '${name}': http server needs a url`);
+    const url = s.url;
+    if (!/^https?:\/\//i.test(url))
+      fail(`mcpServers[] '${name}': url must start with http(s)://`);
+    return { name, kind: "http", args: [], env: [], url, headers: nameValueList(s.headers, "headers") };
+  }
+  if (!hasCommand) {
+    fail(`mcpServers[] '${name}': stdio server needs a command (or send type:"http" with a url)`);
+  }
+  return {
+    name,
+    kind: "stdio",
+    command: s.command,
+    args: strArray(s.args, "args"),
+    env: nameValueList(s.env, "env"),
+    headers: []
+  };
+}
+function validateMcpServers(input) {
+  if (input === undefined)
+    return [];
+  if (!Array.isArray(input))
+    fail("mcpServers must be an array");
+  const seen = new Set;
+  return input.map((e) => {
+    const n = normalizeMcpServer(e);
+    if (seen.has(n.name))
+      fail(`mcpServers[] duplicate name: '${n.name}'`);
+    seen.add(n.name);
+    return n;
+  });
+}
+function mcpServerToAgyAddArgs(s) {
+  const argv = ["mcp", "add"];
+  if (s.kind === "stdio") {
+    for (const e of s.env)
+      argv.push("--env", `${e.name}=${e.value}`);
+    argv.push(s.name, "--", s.command, ...s.args);
+    return argv;
+  }
+  for (const h of s.headers)
+    argv.push("--header", `${h.name}: ${h.value}`);
+  argv.push("--type", "http", s.name, s.url);
+  return argv;
+}
+function execFileAsync(bin, args, timeoutMs) {
+  return new Promise((resolve) => {
+    execFile(bin, args, { timeout: timeoutMs, maxBuffer: 512 * 1024, windowsHide: true }, (err, stdout, stderr) => {
+      const e = err;
+      resolve({
+        status: typeof e?.code === "number" ? e.code : e ? 1 : 0,
+        stdout: String(stdout ?? ""),
+        stderr: e?.message ? `${e.message}
+${String(stderr ?? "")}` : String(stderr ?? "")
+      });
+    });
+  });
+}
+var defaultMcpRunFn = (bin, args, opts) => execFileAsync(bin, args, opts.timeoutMs);
+function tail(text, n = 600) {
+  const t = String(text || "").trim();
+  return t.length > n ? "…" + t.slice(-n) : t;
+}
+async function syncMcpServers(bin, servers, runFn = defaultMcpRunFn, timeoutMs = 30000) {
+  const added = [];
+  for (const s of servers) {
+    let r;
+    try {
+      r = await runFn(bin, mcpServerToAgyAddArgs(s), { timeoutMs });
+    } catch (err) {
+      throw new RequestError(-32603, `failed to register MCP server '${s.name}': ${err?.message || err}`);
+    }
+    if (r.status !== 0) {
+      throw new RequestError(-32603, `failed to register MCP server '${s.name}' (exit ${r.status}): ${tail(`${r.stdout}
+${r.stderr}`)}`);
+    }
+    added.push(s.name);
+  }
+  if (added.length) {
+    let listed = "";
+    try {
+      const lr = await runFn(bin, ["mcp", "list"], { timeoutMs });
+      listed = String(lr.stdout ?? "");
+    } catch (err) {
+      throw new RequestError(-32603, `registered MCP server(s) [${added.join(", ")}] but 'mcp list' verification failed: ${err?.message || err}`);
+    }
+    const lines = listed.split(`
+`);
+    const missing = added.filter((n) => !lines.some((ln) => ln.includes(n)));
+    if (missing.length) {
+      throw new RequestError(-32603, `MCP server(s) [${missing.join(", ")}] exited 0 on 'mcp add' but are absent from 'mcp list' ` + `(agy swallows its global --version/--help flags even after '--'; check server args). ` + `List tail: ${tail(listed, 300)}`);
+    }
+  }
+  return { added };
+}
+async function removeMcpServers(bin, names, runFn = defaultMcpRunFn, timeoutMs = 30000) {
+  const removed = [];
+  const warnings = [];
+  for (const name of names) {
+    try {
+      const r = await runFn(bin, ["mcp", "remove", name], { timeoutMs });
+      if (r.status !== 0) {
+        warnings.push(`mcp remove '${name}' exit ${r.status}: ${tail(`${r.stdout}
+${r.stderr}`, 200)}`);
+      } else {
+        removed.push(name);
+      }
+    } catch (err) {
+      warnings.push(`mcp remove '${name}' threw: ${err?.message || err}`);
+    }
+  }
+  if (warnings.length) {
+    console.warn(`[ACP-MCP] cleanup warnings: ${warnings.join(" | ")}`);
+  }
+  return { removed, warnings };
+}
+
 // src/core/types.ts
 var AGENT_INFO = {
   name: "agy-acp",
   title: "agy ACP (stream-json)",
-  version: "0.1.14"
+  version: "0.1.17"
 };
 var BRIDGE_CAPABILITIES = {
   prompt: true,
@@ -12652,6 +12825,17 @@ function debugLog(msg) {
 
 // src/core/session-core.ts
 var EMPTY_SESSION_MAX_AGE_MS = 60 * 60 * 1000;
+function resolveAgyBin() {
+  const rawBin = process.env.AGY_BIN;
+  let bin = rawBin && rawBin !== "undefined" && rawBin !== "null" ? rawBin : "agy";
+  if (bin === "agy" || bin === "agy.exe") {
+    const geminiBin = path10.join(process.env.USERPROFILE || process.env.HOME || "", ".gemini", "bin", process.platform === "win32" ? "agy.exe" : "agy");
+    if (fs9.existsSync(geminiBin)) {
+      bin = geminiBin;
+    }
+  }
+  return bin;
+}
 function deriveTitle(text, maxLen = 60) {
   const line = String(text || "").split(/\r?\n/).map((s) => s.trim()).find(Boolean) || "";
   const flat = line.replace(/\s+/g, " ");
@@ -12663,7 +12847,10 @@ class AgySessionCore {
   sessionStore;
   historyStore;
   catalogPromise = null;
+  mcpRunner;
+  mcpRefs = new Map;
   constructor(options) {
+    this.mcpRunner = options?.mcpRunner ?? defaultMcpRunFn;
     if (options?.sessionStore instanceof SessionStore) {
       this.sessionStore = options.sessionStore;
     } else if (typeof options?.sessionStore === "string") {
@@ -12712,14 +12899,8 @@ class AgySessionCore {
       disableSlashCommands: disableSlash,
       printTimeout
     });
-    const rawBin = process.env.AGY_BIN;
-    let bin = rawBin && rawBin !== "undefined" && rawBin !== "null" ? rawBin : "agy";
-    if (bin === "agy" || bin === "agy.exe") {
-      const geminiBin = path10.join(process.env.USERPROFILE || process.env.HOME || "", ".gemini", "bin", process.platform === "win32" ? "agy.exe" : "agy");
-      if (fs9.existsSync(geminiBin)) {
-        bin = geminiBin;
-      }
-    }
+    const rawBin = resolveAgyBin();
+    const bin = rawBin;
     let execBin = bin;
     let execArgs = args;
     if (/\.(js|cjs|mjs|ts)$/i.test(bin)) {
@@ -12850,6 +13031,43 @@ class AgySessionCore {
     if (!session.agent && agents.length)
       session.agent = agents[0].value;
   }
+  async applySessionMcpServers(sessionId, input) {
+    const servers = validateMcpServers(input ?? []);
+    if (!servers.length)
+      return [];
+    const live = this.sessions.get(sessionId);
+    const hadLiveProc = live ? live.proc.isWritable() : false;
+    await syncMcpServers(resolveAgyBin(), servers, this.mcpRunner);
+    const names = servers.map((s) => ({ name: s.name }));
+    if (live)
+      live.mcpServers = names;
+    this.trackMcpServers(sessionId, names.map((n) => n.name));
+    if (hadLiveProc) {
+      console.warn(`[ACP-MCP] session ${sessionId}: MCP servers [${names.map((n) => n.name).join(", ")}] ` + `registered while the session process is live; they apply to fresh spawns (reconnect to use them).`);
+    }
+    return names;
+  }
+  trackMcpServers(sessionId, names) {
+    for (const name of names) {
+      let set = this.mcpRefs.get(name);
+      if (!set) {
+        set = new Set;
+        this.mcpRefs.set(name, set);
+      }
+      set.add(sessionId);
+    }
+  }
+  untrackMcpServers(sessionId) {
+    const freed = [];
+    for (const [name, set] of this.mcpRefs) {
+      set.delete(sessionId);
+      if (set.size === 0) {
+        this.mcpRefs.delete(name);
+        freed.push(name);
+      }
+    }
+    return freed;
+  }
   async createSession(params, protocolVersion = 1) {
     const cwd = params?.cwd;
     debugLog(`createSession v${protocolVersion} cwd=${cwd}`);
@@ -12872,6 +13090,7 @@ class AgySessionCore {
     if (params?.mcpServers !== undefined && !Array.isArray(params.mcpServers)) {
       throw new RequestError(-32602, "mcpServers must be an array");
     }
+    validateMcpServers(params?.mcpServers);
     const launch = extractLaunchConfig(params);
     const discovery = await this.getDiscovery();
     const sessionId = randomUUID3();
@@ -12914,6 +13133,7 @@ class AgySessionCore {
     };
     this.applyCatalogDefaults(session, discovery);
     this.sessions.set(sessionId, session);
+    await this.applySessionMcpServers(sessionId, params?.mcpServers);
     this.persistSession(session);
     this.warmupSession(sessionId);
     return {
@@ -12942,14 +13162,10 @@ class AgySessionCore {
         throw new RequestError(-32602, protocolVersion === 2 ? 'only replayFrom.type="start" is supported by this agent' : "session/resume with replayFrom is only supported by ACP v2");
       }
     }
-    if (params?.mcpServers !== undefined) {
-      if (!Array.isArray(params.mcpServers)) {
-        throw new RequestError(-32602, "mcpServers must be an array");
-      }
-      if (params.mcpServers.length > 0) {
-        throw new RequestError(-32602, "mcpServers are not supported by this agent");
-      }
+    if (params?.mcpServers !== undefined && !Array.isArray(params.mcpServers)) {
+      throw new RequestError(-32602, "mcpServers must be an array");
     }
+    validateMcpServers(params?.mcpServers);
     let additionalDirectories = [];
     if (params?.additionalDirectories !== undefined) {
       if (!Array.isArray(params.additionalDirectories)) {
@@ -13024,6 +13240,7 @@ class AgySessionCore {
     }
     const discovery = await this.getDiscovery();
     this.applyCatalogDefaults(session, discovery);
+    await this.applySessionMcpServers(sessionId, params?.mcpServers);
     if (!session.title) {
       try {
         const first = this.historyStore.firstUserText(sessionId);
@@ -13200,6 +13417,14 @@ class AgySessionCore {
     }
     this.sessionStore.delete(sessionId);
     this.historyStore.delete(sessionId);
+    try {
+      const freed = this.untrackMcpServers(sessionId);
+      if (freed.length) {
+        await removeMcpServers(resolveAgyBin(), freed, this.mcpRunner);
+      }
+    } catch (err) {
+      console.warn(`[ACP-MCP] cleanup after delete ${sessionId} failed: ${err?.message || err}`);
+    }
     return {};
   }
   async closeSession(params) {

package/dist/core/session-core.d.ts

@@ -1,14 +1,22 @@
 import { type DiscoveryResult } from '../lib/agy-discovery.ts';
 import { SessionStore } from '../lib/session-store.ts';
 import { SessionHistoryStore } from '../lib/session-history.ts';
+import { type McpRunFn } from '../lib/mcp-servers.ts';
 import { type SdkSession, type ProtocolVersion } from './types.ts';
 export interface SessionCoreOptions {
     sessionStore?: SessionStore | string;
     historyStore?: SessionHistoryStore | string;
+    /**
+     * `agy mcp ...` runner override (tests inject a fake; prod spawns agy).
+     * Keeps MCP sync unit-testable without touching the real global config.
+     */
+    mcpRunner?: McpRunFn;
 }
 /** Rows without any completed turn older than this are hidden from
  * session/list (still resumable/deletable by id — the store keeps them). */
 export declare const EMPTY_SESSION_MAX_AGE_MS: number;
+/** Resolve the agy binary (AGY_BIN, else ~/.gemini/bin/agy). Shared by spawn and `agy mcp ...` sync. */
+export declare function resolveAgyBin(): string;
 /** First user prompt collapsed to one line, capped for list display. */
 export declare function deriveTitle(text: string, maxLen?: number): string;
 export declare class AgySessionCore {
@@ -16,6 +24,13 @@ export declare class AgySessionCore {
     readonly sessionStore: SessionStore;
     readonly historyStore: SessionHistoryStore;
     private catalogPromise;
+    private readonly mcpRunner;
+    /**
+     * MCP server name → sessionIds that registered it (this process only).
+     * Drives delete-time cleanup: a server is `agy mcp remove`d only when its
+     * last referencing session goes away.
+     */
+    private readonly mcpRefs;
     constructor(options?: SessionCoreOptions);
     getDiscovery(): Promise<DiscoveryResult>;
     /** Warm-up toggle: AGY_ACP_WARMUP=0/false/no disables connect-time pre-spawn. */
@@ -41,6 +56,19 @@ export declare class AgySessionCore {
     replayHistory(sessionId: string, protocolVersion: ProtocolVersion, notifyClient: (update: any) => Promise<void> | void): Promise<void>;
     sessionMeta(session: SdkSession): Record<string, unknown> | undefined;
     applyCatalogDefaults(session: SdkSession, discovery: DiscoveryResult): void;
+    /**
+     * Sync ACP mcpServers into agy's MCP config BEFORE the session process
+     * spawns, so tools are listed from the first turn. Throws loud on any
+     * failure (a client that asked for MCP must never get a silent
+     * tools-less session). Tracks names per session for delete-time cleanup.
+     */
+    private applySessionMcpServers;
+    private trackMcpServers;
+    /**
+     * Drop one session's references; returns names no other live session
+     * references anymore (safe to `agy mcp remove`).
+     */
+    private untrackMcpServers;
     createSession(params: any, protocolVersion?: ProtocolVersion): Promise<{
         session: SdkSession;
         discovery: DiscoveryResult;

package/dist/core/types.d.ts

@@ -58,6 +58,10 @@ export interface SdkSession {
     disableSlashCommands?: boolean;
     printTimeout?: string;
     deleted?: boolean;
+    /** MCP servers this session registered (tracked for delete-time cleanup). */
+    mcpServers?: Array<{
+        name: string;
+    }>;
 }
 /**
  * Sequential FIFO execution queue to eliminate notification ordering races.

package/dist/index.js

@@ -10421,14 +10421,15 @@ function normalizePrintTimeout(v) {
   return s === "" ? undefined : s;
 }
 function resolveSafety(session = {}, env = process.env) {
-  let safety = normalizeSafety(session.safety) ?? normalizeSafety(env.AGY_ACP_SAFETY) ?? undefined;
+  const explicitSafety = normalizeSafety(session.safety) ?? normalizeSafety(env.AGY_ACP_SAFETY) ?? undefined;
+  let safety = explicitSafety;
   if (!safety) {
     const envSkip = env.AGY_ACP_SKIP_PERMISSIONS;
     if (envSkip !== undefined && envSkip !== "") {
       const skip = !(envSkip === "0" || envSkip === "false" || envSkip === "no");
-      safety = skip ? "autonomous" : "safe";
+      safety = skip ? "autonomous-unsandboxed" : "safe";
     } else {
-      safety = "autonomous";
+      safety = "autonomous-unsandboxed";
     }
   }
   let skipPermissions = safety === "autonomous" || safety === "autonomous-unsandboxed";
@@ -10436,7 +10437,7 @@ function resolveSafety(session = {}, env = process.env) {
     skipPermissions = Boolean(session.skipPermissions);
   }
   let sandbox;
-  if (safety === "autonomous-unsandboxed") {
+  if (safety === "autonomous-unsandboxed" && explicitSafety === "autonomous-unsandboxed") {
     sandbox = false;
   } else if (session.sandbox !== undefined) {
     sandbox = Boolean(session.sandbox);
@@ -11402,7 +11403,7 @@ function formatSoftDenyMessage(denies) {
       bits.push(`(via ${d.source})`);
     lines.push(bits.join(" "));
   }
-  lines.push("Or set AGY_ACP_SAFETY=safe / AGY_ACP_SKIP_PERMISSIONS=0 to re-enable permission checks (autonomous + sandbox is the bridge default).");
+  lines.push("Or set AGY_ACP_SAFETY=safe / AGY_ACP_SKIP_PERMISSIONS=0 to re-enable permission checks (autonomous-unsandboxed — full permissions, no sandbox — is the bridge default; AGY_ACP_SAFETY=autonomous re-enables sandbox containment).");
   if (denies.some((d) => d.source?.includes("sandbox"))) {
     lines.push("Sandbox note: --sandbox = terminal restrictions, not verified offline. Built-in search may still work; if `curl`/`Invoke-WebRequest` failed, retry once with safety=autonomous-unsandboxed (or sandbox:false) to confirm it is a sandbox network block.");
   }
@@ -12327,11 +12328,183 @@ class SessionHistoryStore {
   }
 }
 
+// src/lib/mcp-servers.ts
+import { execFile } from "node:child_process";
+function fail(msg) {
+  throw new RequestError(-32602, msg);
+}
+function nonEmptyString(v) {
+  return typeof v === "string" && v.length > 0;
+}
+function strArray(v, what) {
+  if (v === undefined)
+    return [];
+  if (!Array.isArray(v) || v.some((x) => typeof x !== "string")) {
+    fail(`mcpServers[].${what} must be an array of strings`);
+  }
+  return v;
+}
+function nameValueList(v, what) {
+  if (v === undefined)
+    return [];
+  if (!Array.isArray(v))
+    fail(`mcpServers[].${what} must be an array`);
+  return v.map((e, i) => {
+    if (!e || typeof e !== "object")
+      fail(`mcpServers[].${what}[${i}] must be {name, value}`);
+    const rec = e;
+    if (!nonEmptyString(rec.name) || typeof rec.value !== "string") {
+      fail(`mcpServers[].${what}[${i}] must be {name: string, value: string}`);
+    }
+    return { name: rec.name, value: rec.value };
+  });
+}
+function normalizeMcpServer(input) {
+  if (!input || typeof input !== "object")
+    fail("mcpServers[] must be an object");
+  const s = input;
+  if (!nonEmptyString(s.name))
+    fail("mcpServers[].name must be a non-empty string");
+  const name = s.name.trim();
+  if (name.length > 64 || /[\s\x00-\x1f]/.test(name)) {
+    fail(`mcpServers[].name must be ≤64 chars with no whitespace: ${JSON.stringify(name)}`);
+  }
+  const t = typeof s.type === "string" ? s.type.trim().toLowerCase() : "";
+  if (t === "sse" || t === "acp") {
+    fail(`mcpServers[] '${name}': type '${t}' has no 'agy mcp add' equivalent ` + `(agy supports stdio|http only). Resend as stdio or http.`);
+  }
+  if (t !== "" && t !== "stdio" && t !== "http") {
+    fail(`mcpServers[] '${name}': unknown type ${JSON.stringify(s.type)} (want stdio|http)`);
+  }
+  const hasCommand = nonEmptyString(s.command);
+  const hasUrl = nonEmptyString(s.url);
+  if (hasCommand && hasUrl) {
+    fail(`mcpServers[] '${name}': ambiguous (both command and url set); send one`);
+  }
+  if (t === "http" || !hasCommand && hasUrl) {
+    if (!hasUrl)
+      fail(`mcpServers[] '${name}': http server needs a url`);
+    const url = s.url;
+    if (!/^https?:\/\//i.test(url))
+      fail(`mcpServers[] '${name}': url must start with http(s)://`);
+    return { name, kind: "http", args: [], env: [], url, headers: nameValueList(s.headers, "headers") };
+  }
+  if (!hasCommand) {
+    fail(`mcpServers[] '${name}': stdio server needs a command (or send type:"http" with a url)`);
+  }
+  return {
+    name,
+    kind: "stdio",
+    command: s.command,
+    args: strArray(s.args, "args"),
+    env: nameValueList(s.env, "env"),
+    headers: []
+  };
+}
+function validateMcpServers(input) {
+  if (input === undefined)
+    return [];
+  if (!Array.isArray(input))
+    fail("mcpServers must be an array");
+  const seen = new Set;
+  return input.map((e) => {
+    const n = normalizeMcpServer(e);
+    if (seen.has(n.name))
+      fail(`mcpServers[] duplicate name: '${n.name}'`);
+    seen.add(n.name);
+    return n;
+  });
+}
+function mcpServerToAgyAddArgs(s) {
+  const argv = ["mcp", "add"];
+  if (s.kind === "stdio") {
+    for (const e of s.env)
+      argv.push("--env", `${e.name}=${e.value}`);
+    argv.push(s.name, "--", s.command, ...s.args);
+    return argv;
+  }
+  for (const h of s.headers)
+    argv.push("--header", `${h.name}: ${h.value}`);
+  argv.push("--type", "http", s.name, s.url);
+  return argv;
+}
+function execFileAsync(bin, args, timeoutMs) {
+  return new Promise((resolve) => {
+    execFile(bin, args, { timeout: timeoutMs, maxBuffer: 512 * 1024, windowsHide: true }, (err, stdout, stderr) => {
+      const e = err;
+      resolve({
+        status: typeof e?.code === "number" ? e.code : e ? 1 : 0,
+        stdout: String(stdout ?? ""),
+        stderr: e?.message ? `${e.message}
+${String(stderr ?? "")}` : String(stderr ?? "")
+      });
+    });
+  });
+}
+var defaultMcpRunFn = (bin, args, opts) => execFileAsync(bin, args, opts.timeoutMs);
+function tail(text, n = 600) {
+  const t = String(text || "").trim();
+  return t.length > n ? "…" + t.slice(-n) : t;
+}
+async function syncMcpServers(bin, servers, runFn = defaultMcpRunFn, timeoutMs = 30000) {
+  const added = [];
+  for (const s of servers) {
+    let r;
+    try {
+      r = await runFn(bin, mcpServerToAgyAddArgs(s), { timeoutMs });
+    } catch (err) {
+      throw new RequestError(-32603, `failed to register MCP server '${s.name}': ${err?.message || err}`);
+    }
+    if (r.status !== 0) {
+      throw new RequestError(-32603, `failed to register MCP server '${s.name}' (exit ${r.status}): ${tail(`${r.stdout}
+${r.stderr}`)}`);
+    }
+    added.push(s.name);
+  }
+  if (added.length) {
+    let listed = "";
+    try {
+      const lr = await runFn(bin, ["mcp", "list"], { timeoutMs });
+      listed = String(lr.stdout ?? "");
+    } catch (err) {
+      throw new RequestError(-32603, `registered MCP server(s) [${added.join(", ")}] but 'mcp list' verification failed: ${err?.message || err}`);
+    }
+    const lines = listed.split(`
+`);
+    const missing = added.filter((n) => !lines.some((ln) => ln.includes(n)));
+    if (missing.length) {
+      throw new RequestError(-32603, `MCP server(s) [${missing.join(", ")}] exited 0 on 'mcp add' but are absent from 'mcp list' ` + `(agy swallows its global --version/--help flags even after '--'; check server args). ` + `List tail: ${tail(listed, 300)}`);
+    }
+  }
+  return { added };
+}
+async function removeMcpServers(bin, names, runFn = defaultMcpRunFn, timeoutMs = 30000) {
+  const removed = [];
+  const warnings = [];
+  for (const name of names) {
+    try {
+      const r = await runFn(bin, ["mcp", "remove", name], { timeoutMs });
+      if (r.status !== 0) {
+        warnings.push(`mcp remove '${name}' exit ${r.status}: ${tail(`${r.stdout}
+${r.stderr}`, 200)}`);
+      } else {
+        removed.push(name);
+      }
+    } catch (err) {
+      warnings.push(`mcp remove '${name}' threw: ${err?.message || err}`);
+    }
+  }
+  if (warnings.length) {
+    console.warn(`[ACP-MCP] cleanup warnings: ${warnings.join(" | ")}`);
+  }
+  return { removed, warnings };
+}
+
 // src/core/types.ts
 var AGENT_INFO = {
   name: "agy-acp",
   title: "agy ACP (stream-json)",
-  version: "0.1.14"
+  version: "0.1.17"
 };
 var BRIDGE_CAPABILITIES = {
   prompt: true,
@@ -12452,6 +12625,17 @@ function installFileLogging() {
 
 // src/core/session-core.ts
 var EMPTY_SESSION_MAX_AGE_MS = 60 * 60 * 1000;
+function resolveAgyBin() {
+  const rawBin = process.env.AGY_BIN;
+  let bin = rawBin && rawBin !== "undefined" && rawBin !== "null" ? rawBin : "agy";
+  if (bin === "agy" || bin === "agy.exe") {
+    const geminiBin = path10.join(process.env.USERPROFILE || process.env.HOME || "", ".gemini", "bin", process.platform === "win32" ? "agy.exe" : "agy");
+    if (fs9.existsSync(geminiBin)) {
+      bin = geminiBin;
+    }
+  }
+  return bin;
+}
 function deriveTitle(text, maxLen = 60) {
   const line = String(text || "").split(/\r?\n/).map((s) => s.trim()).find(Boolean) || "";
   const flat = line.replace(/\s+/g, " ");
@@ -12463,7 +12647,10 @@ class AgySessionCore {
   sessionStore;
   historyStore;
   catalogPromise = null;
+  mcpRunner;
+  mcpRefs = new Map;
   constructor(options) {
+    this.mcpRunner = options?.mcpRunner ?? defaultMcpRunFn;
     if (options?.sessionStore instanceof SessionStore) {
       this.sessionStore = options.sessionStore;
     } else if (typeof options?.sessionStore === "string") {
@@ -12512,14 +12699,8 @@ class AgySessionCore {
       disableSlashCommands: disableSlash,
       printTimeout
     });
-    const rawBin = process.env.AGY_BIN;
-    let bin = rawBin && rawBin !== "undefined" && rawBin !== "null" ? rawBin : "agy";
-    if (bin === "agy" || bin === "agy.exe") {
-      const geminiBin = path10.join(process.env.USERPROFILE || process.env.HOME || "", ".gemini", "bin", process.platform === "win32" ? "agy.exe" : "agy");
-      if (fs9.existsSync(geminiBin)) {
-        bin = geminiBin;
-      }
-    }
+    const rawBin = resolveAgyBin();
+    const bin = rawBin;
     let execBin = bin;
     let execArgs = args;
     if (/\.(js|cjs|mjs|ts)$/i.test(bin)) {
@@ -12650,6 +12831,43 @@ class AgySessionCore {
     if (!session.agent && agents.length)
       session.agent = agents[0].value;
   }
+  async applySessionMcpServers(sessionId, input) {
+    const servers = validateMcpServers(input ?? []);
+    if (!servers.length)
+      return [];
+    const live = this.sessions.get(sessionId);
+    const hadLiveProc = live ? live.proc.isWritable() : false;
+    await syncMcpServers(resolveAgyBin(), servers, this.mcpRunner);
+    const names = servers.map((s) => ({ name: s.name }));
+    if (live)
+      live.mcpServers = names;
+    this.trackMcpServers(sessionId, names.map((n) => n.name));
+    if (hadLiveProc) {
+      console.warn(`[ACP-MCP] session ${sessionId}: MCP servers [${names.map((n) => n.name).join(", ")}] ` + `registered while the session process is live; they apply to fresh spawns (reconnect to use them).`);
+    }
+    return names;
+  }
+  trackMcpServers(sessionId, names) {
+    for (const name of names) {
+      let set = this.mcpRefs.get(name);
+      if (!set) {
+        set = new Set;
+        this.mcpRefs.set(name, set);
+      }
+      set.add(sessionId);
+    }
+  }
+  untrackMcpServers(sessionId) {
+    const freed = [];
+    for (const [name, set] of this.mcpRefs) {
+      set.delete(sessionId);
+      if (set.size === 0) {
+        this.mcpRefs.delete(name);
+        freed.push(name);
+      }
+    }
+    return freed;
+  }
   async createSession(params, protocolVersion = 1) {
     const cwd = params?.cwd;
     debugLog(`createSession v${protocolVersion} cwd=${cwd}`);
@@ -12672,6 +12890,7 @@ class AgySessionCore {
     if (params?.mcpServers !== undefined && !Array.isArray(params.mcpServers)) {
       throw new RequestError(-32602, "mcpServers must be an array");
     }
+    validateMcpServers(params?.mcpServers);
     const launch = extractLaunchConfig(params);
     const discovery = await this.getDiscovery();
     const sessionId = randomUUID3();
@@ -12714,6 +12933,7 @@ class AgySessionCore {
     };
     this.applyCatalogDefaults(session, discovery);
     this.sessions.set(sessionId, session);
+    await this.applySessionMcpServers(sessionId, params?.mcpServers);
     this.persistSession(session);
     this.warmupSession(sessionId);
     return {
@@ -12742,14 +12962,10 @@ class AgySessionCore {
         throw new RequestError(-32602, protocolVersion === 2 ? 'only replayFrom.type="start" is supported by this agent' : "session/resume with replayFrom is only supported by ACP v2");
       }
     }
-    if (params?.mcpServers !== undefined) {
-      if (!Array.isArray(params.mcpServers)) {
-        throw new RequestError(-32602, "mcpServers must be an array");
-      }
-      if (params.mcpServers.length > 0) {
-        throw new RequestError(-32602, "mcpServers are not supported by this agent");
-      }
+    if (params?.mcpServers !== undefined && !Array.isArray(params.mcpServers)) {
+      throw new RequestError(-32602, "mcpServers must be an array");
     }
+    validateMcpServers(params?.mcpServers);
     let additionalDirectories = [];
     if (params?.additionalDirectories !== undefined) {
       if (!Array.isArray(params.additionalDirectories)) {
@@ -12824,6 +13040,7 @@ class AgySessionCore {
     }
     const discovery = await this.getDiscovery();
     this.applyCatalogDefaults(session, discovery);
+    await this.applySessionMcpServers(sessionId, params?.mcpServers);
     if (!session.title) {
       try {
         const first = this.historyStore.firstUserText(sessionId);
@@ -13000,6 +13217,14 @@ class AgySessionCore {
     }
     this.sessionStore.delete(sessionId);
     this.historyStore.delete(sessionId);
+    try {
+      const freed = this.untrackMcpServers(sessionId);
+      if (freed.length) {
+        await removeMcpServers(resolveAgyBin(), freed, this.mcpRunner);
+      }
+    } catch (err) {
+      console.warn(`[ACP-MCP] cleanup after delete ${sessionId} failed: ${err?.message || err}`);
+    }
     return {};
   }
   async closeSession(params) {
@@ -17669,7 +17894,8 @@ __export(exports_core3, {
   BRIDGE_CAPABILITIES: () => BRIDGE_CAPABILITIES,
   EMPTY_SESSION_MAX_AGE_MS: () => EMPTY_SESSION_MAX_AGE_MS,
   catalogChoices: () => catalogChoices,
-  deriveTitle: () => deriveTitle
+  deriveTitle: () => deriveTitle,
+  resolveAgyBin: () => resolveAgyBin
 });
 // src/v1/index.ts
 var exports_v1 = {};

package/dist/lib/agy-args.d.ts

@@ -114,14 +114,17 @@ export type SafetyResolveInput = {
  *
  * Tiers:
  *   safe                        — no skip-permissions; sandbox only if explicitly true
- *   autonomous (default)        — skip-permissions; default --sandbox unless sandbox:false
- *   autonomous-unsandboxed      — skip-permissions; NEVER --sandbox
+ *   autonomous                  — skip-permissions; default --sandbox unless sandbox:false
+ *                                 (opt-in containment; explicit safety/autonomous only)
+ *   autonomous-unsandboxed      — skip-permissions; NEVER --sandbox (the default:
+ *                                 full permissions, no terminal restrictions)
  *
  * Inputs:
  *   session.safety / AGY_ACP_SAFETY
- *   AGY_ACP_SKIP_PERMISSIONS=0 ≈ safe if safety unset; otherwise autonomous
+ *   AGY_ACP_SKIP_PERMISSIONS=0 ≈ safe if safety unset; otherwise autonomous-unsandboxed
  *   explicit session.skipPermissions overrides the skip flag only
- *   explicit session.sandbox / AGY_ACP_SANDBOX override sandbox except unsandboxed tier
+ *   explicit session.sandbox / AGY_ACP_SANDBOX override sandbox except when the
+ *   unsandboxed tier was explicitly selected (defaulted tier honors opt-in)
  */
 export declare function resolveSafety(session?: SafetyResolveInput, env?: NodeJS.ProcessEnv): ResolvedSafety;
 /**

package/dist/lib/mcp-servers.d.ts

@@ -0,0 +1,91 @@
+/**
+ * ACP `mcpServers` → `agy mcp add/remove` bridging.
+ *
+ * The bridge owns MCP registration end-to-end:
+ * - `session/new|resume` accept the standard ACP `mcpServers` list and sync
+ *   it into agy's MCP config (`~/.gemini/config/mcp_config.json`) via
+ *   `agy mcp add` BEFORE the session process spawns, so tools are listed
+ *   from the first turn.
+ * - `session/delete` removes the servers this session registered (refcounted
+ *   per bridge process; best-effort, never breaks close/delete).
+ * - Permissions stay under the bridge safety policy: MCP tool calls run with
+ *   the session's `--dangerously-skip-permissions`/`--sandbox` flags, and
+ *   headless soft-denies still surface `permissions.allow` guidance.
+ *
+ * Supported ACP shapes: stdio `{name, command, args, env[]}` and http
+ * `{name, url, headers[], type:"http"}`. `sse`/`acp` transports have no
+ * `agy mcp add` equivalent and fail fast (no silent downgrade).
+ */
+export interface AcpMcpServerInput {
+    name?: unknown;
+    type?: unknown;
+    command?: unknown;
+    args?: unknown;
+    env?: unknown;
+    url?: unknown;
+    headers?: unknown;
+    [k: string]: unknown;
+}
+export interface NormalizedMcpServer {
+    name: string;
+    kind: 'stdio' | 'http';
+    command?: string;
+    args: string[];
+    env: Array<{
+        name: string;
+        value: string;
+    }>;
+    url?: string;
+    headers: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+/**
+ * Validate one ACP McpServer entry. Throws RequestError(-32602) — loud,
+ * so a client that sent an unusable server never gets a silent no-tools
+ * session.
+ */
+export declare function normalizeMcpServer(input: unknown): NormalizedMcpServer;
+/** Validate a full session/new|resume mcpServers list (non-array → loud). */
+export declare function validateMcpServers(input: unknown): NormalizedMcpServer[];
+/**
+ * Build `agy mcp add` argv. agy rejects flags placed after <name>, so all
+ * flags come first: mcp add [--env K=V] [--header K:V] [--type t] <name>
+ * <commandOrUrl> [args...].
+ * stdio ALWAYS inserts `--` after <name>: agy consumes a global `--version`
+ * (and may misparse other dash-args) even in post-positional slots, which
+ * exits 0 while registering nothing (verified against agy 1.2.8). `--` ends
+ * flag parsing so command/args pass through verbatim.
+ */
+export declare function mcpServerToAgyAddArgs(s: NormalizedMcpServer): string[];
+export interface McpRunResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** Injectable `agy mcp ...` runner (tests stub it; prod spawns agy). */
+export type McpRunFn = (bin: string, args: string[], opts: {
+    timeoutMs: number;
+}) => Promise<McpRunResult>;
+/** Production runner: real `agy mcp ...` subprocess. */
+export declare const defaultMcpRunFn: McpRunFn;
+/**
+ * Register every server via `agy mcp add` (idempotent: add == upsert).
+ * Any failure throws RequestError — a client that asked for MCP must never
+ * get a silent tools-less session.
+ * Verify-after-add: agy exits 0 while registering NOTHING when argv contains
+ * its global flags (`--version`/`--help` are swallowed even after `--`),
+ * so every add is confirmed via `mcp list`. Absent-after-add throws loud.
+ */
+export declare function syncMcpServers(bin: string, servers: NormalizedMcpServer[], runFn?: McpRunFn, timeoutMs?: number): Promise<{
+    added: string[];
+}>;
+/**
+ * Remove servers by name. Best-effort by design: returns per-name warnings
+ * instead of throwing, so session close/delete can never break on cleanup.
+ */
+export declare function removeMcpServers(bin: string, names: string[], runFn?: McpRunFn, timeoutMs?: number): Promise<{
+    removed: string[];
+    warnings: string[];
+}>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yitom/agy-acp-map",
-  "version": "0.1.14",
+  "version": "0.1.17",
   "publishConfig": {
     "access": "public"
   },
@@ -48,8 +48,11 @@
     "smoke:permissions": "bun tests/smoke/smoke-permissions.ts",
     "smoke:image-in": "bun tests/smoke/smoke-image-in.ts",
     "smoke:image-out": "bun tests/smoke/smoke-image-out.ts",
+    "smoke:mcp": "bun tests/smoke/smoke-mcp.ts",
+    "smoke:mcp-resume": "bun tests/smoke/smoke-mcp-resume.ts",
+    "smoke:mcp-e2e": "bun tests/smoke/smoke-mcp-e2e.ts",
     "smoke:robustness": "bun tests/smoke/smoke-robustness.ts",
-    "smoke:all": "bun test src/lib && bun tests/test-agy-args.ts && bun tests/smoke/smoke-basic.ts && bun tests/smoke/smoke-flags.ts && bun tests/smoke/smoke-permissions.ts && bun tests/smoke/smoke-image-in.ts && bun tests/smoke/smoke-image-out.ts && bun tests/smoke/smoke-robustness.ts"
+    "smoke:all": "bun test src/lib && bun tests/test-agy-args.ts && bun tests/smoke/smoke-mcp.ts && bun tests/smoke/smoke-mcp-resume.ts && bun tests/smoke/smoke-basic.ts && bun tests/smoke/smoke-flags.ts && bun tests/smoke/smoke-permissions.ts && bun tests/smoke/smoke-image-in.ts && bun tests/smoke/smoke-image-out.ts && bun tests/smoke/smoke-robustness.ts"
   },
   "keywords": [
     "antigravity",