@yitom/agy-acp-map 0.1.13 → 0.1.16

package/README.md

@@ -64,6 +64,21 @@ bun run smoke:all                 # units + full live matrix
 
 **Windows:** install [Bun](https://bun.sh), put `agy` on `PATH`, then the same commands.
 
+## Run via bunx / npx (no install, codex-style)
+
+The npm tarball is thin (~5MB: `dist/bin.js` + `dist/agy-headless.exe`, no runtime
+needed beyond node/bun). First run downloads `@latest` into the runner cache,
+later runs reuse it:
+
+```powershell
+bunx @yitom/agy-acp-map@latest        # bun users (preferred: no prompt, no shim flash)
+npx -y @yitom/agy-acp-map@latest      # node users
+```
+
+Requirements are the same as source runs: a logged-in `agy` on `PATH`. The
+optional 95MB single-file `agy-acp-win-x64.exe` is **not** in the npm package —
+grab it from GitHub Releases if you want zero-runtime distribution.
+
 
 ## Launch flags / 启动参数 (v0.1.2)
 

package/dist/bin.js

@@ -12463,7 +12463,7 @@ class SessionHistoryStore {
   filePath(sessionId) {
     return path8.join(this.directory, historyFileName(sessionId));
   }
-  appendTurn(sessionId, userText, assistantText) {
+  appendTurn(sessionId, userText, assistantText, opts) {
     const records = [];
     const now = new Date().toISOString();
     if (userText) {
@@ -12483,7 +12483,8 @@ class SessionHistoryStore {
         messageId: `history_agent_${randomUUID2()}`,
         role: "assistant",
         text: assistantText,
-        createdAt: new Date().toISOString()
+        createdAt: new Date().toISOString(),
+        ...opts?.partial ? { partial: true } : {}
       });
     }
     if (!records.length)
@@ -12539,11 +12540,168 @@ 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);
+  }
+  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.13"
+  version: "0.1.16"
 };
 var BRIDGE_CAPABILITIES = {
   prompt: true,
@@ -12651,6 +12809,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, " ");
@@ -12662,7 +12831,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") {
@@ -12711,14 +12883,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)) {
@@ -12792,7 +12958,8 @@ class AgySessionCore {
   }
   persistTurnHistory(sessionId, userText, assistantText, stopReason, eligible = true) {
     try {
-      this.historyStore.appendTurn(sessionId, userText, eligible && stopReason !== "cancelled" ? assistantText : undefined);
+      const partial = stopReason === "cancelled" || !eligible;
+      this.historyStore.appendTurn(sessionId, userText, assistantText, partial ? { partial: true } : undefined);
     } catch (err) {
       console.warn(`[ACP-HISTORY] Warning: failed to persist turn ${sessionId}:`, err);
     }
@@ -12848,6 +13015,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}`);
@@ -12870,6 +13074,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();
@@ -12912,6 +13117,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 {
@@ -12940,14 +13146,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)) {
@@ -13022,6 +13224,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);
@@ -13198,6 +13401,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

@@ -12250,7 +12250,7 @@ class SessionHistoryStore {
   filePath(sessionId) {
     return path8.join(this.directory, historyFileName(sessionId));
   }
-  appendTurn(sessionId, userText, assistantText) {
+  appendTurn(sessionId, userText, assistantText, opts) {
     const records = [];
     const now = new Date().toISOString();
     if (userText) {
@@ -12270,7 +12270,8 @@ class SessionHistoryStore {
         messageId: `history_agent_${randomUUID2()}`,
         role: "assistant",
         text: assistantText,
-        createdAt: new Date().toISOString()
+        createdAt: new Date().toISOString(),
+        ...opts?.partial ? { partial: true } : {}
       });
     }
     if (!records.length)
@@ -12326,11 +12327,168 @@ 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);
+  }
+  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.13"
+  version: "0.1.16"
 };
 var BRIDGE_CAPABILITIES = {
   prompt: true,
@@ -12451,6 +12609,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, " ");
@@ -12462,7 +12631,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") {
@@ -12511,14 +12683,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)) {
@@ -12592,7 +12758,8 @@ class AgySessionCore {
   }
   persistTurnHistory(sessionId, userText, assistantText, stopReason, eligible = true) {
     try {
-      this.historyStore.appendTurn(sessionId, userText, eligible && stopReason !== "cancelled" ? assistantText : undefined);
+      const partial = stopReason === "cancelled" || !eligible;
+      this.historyStore.appendTurn(sessionId, userText, assistantText, partial ? { partial: true } : undefined);
     } catch (err) {
       console.warn(`[ACP-HISTORY] Warning: failed to persist turn ${sessionId}:`, err);
     }
@@ -12648,6 +12815,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}`);
@@ -12670,6 +12874,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();
@@ -12712,6 +12917,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 {
@@ -12740,14 +12946,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)) {
@@ -12822,6 +13024,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);
@@ -12998,6 +13201,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) {
@@ -17667,7 +17878,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/mcp-servers.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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...].
+ */
+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.
+ */
+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/dist/lib/session-history.d.ts

@@ -5,6 +5,11 @@
  * only stores the text that an ACP client can display: user prompts and final
  * assistant text. Tool calls, tool output, thoughts, and internal events are
  * deliberately excluded.
+ *
+ * Display/persist parity: whatever text the client actually saw must be
+ * reloadable. Interrupted turns (cancelled / failed) still persist their
+ * partial text, marked with `partial: true`, so `session/load` replay shows
+ * exactly what was on screen instead of dropping the turn entirely.
  */
 export type SessionHistoryRole = 'user' | 'assistant';
 export type SessionHistoryRecord = {
@@ -14,6 +19,12 @@ export type SessionHistoryRecord = {
     role: SessionHistoryRole;
     text: string;
     createdAt: string;
+    /**
+     * True when the turn did not complete (cancelled / failed) and `text` is
+     * only the partial output the client saw. Replay ignores the flag and
+     * returns the text; readers must tolerate its absence (old journals).
+     */
+    partial?: boolean;
 };
 export declare function resolveHistoryDir(sessionStorePath?: string, env?: NodeJS.ProcessEnv, homedir?: () => string): string;
 export declare class SessionHistoryStore {
@@ -21,12 +32,16 @@ export declare class SessionHistoryStore {
     constructor(directory?: string);
     filePath(sessionId: string): string;
     /**
-     * Append one completed turn as two JSONL records.
+     * Append one completed (or interrupted) turn as JSONL records.
      *
-     * The assistant record is omitted when the turn produced no visible final
-     * text. This keeps cancelled/error-only turns from becoming fake answers.
+     * The assistant record is written whenever the turn produced visible text —
+     * including cancelled/failed turns (`partial: true`). Only a truly empty
+     * assistant answer is omitted, so cancelled/error-only turns never become
+     * fake answers, while partial output stays reloadable.
      */
-    appendTurn(sessionId: string, userText: string, assistantText?: string): void;
+    appendTurn(sessionId: string, userText: string, assistantText?: string, opts?: {
+        partial?: boolean;
+    }): void;
     /** Read valid records and ignore incomplete/corrupt trailing lines. */
     read(sessionId: string): SessionHistoryRecord[];
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yitom/agy-acp-map",
-  "version": "0.1.13",
+  "version": "0.1.16",
   "publishConfig": {
     "access": "public"
   },