@oddessentials/agent-guild 1.21.1 → 1.22.0

package/bin/agent-guild-report.mjs

@@ -17,9 +17,9 @@
 //                      (reads Claude Code status line JSON on stdin; prints a
 //                       status line, or the JSON itself with --passthrough)
 
-import fs from 'node:fs';
 import { createRequire } from 'node:module';
-import { hookToReports, hookRoute, dockerHookEvent, claudeStatuslineToReport, formatStatusLine, antigravityUserConversation, antigravityReply, claudeCompactBoundary } from '../src/report/hooks.mjs';
+import { claudeStatuslineToReport, formatStatusLine } from '../src/report/hooks.mjs';
+import { handleHookEvent, reportKind } from '../src/report/hook-event.mjs';
 
 // Importing node:http as an ES module costs a hook about 50 ms more than requiring it.
 const http = createRequire(import.meta.url)('node:http');
@@ -66,12 +66,7 @@ function readStdin() {
   });
 }
 
-function send(report, kind = report.compaction !== undefined ? 'context'
-  : report.reply !== undefined ? 'reply'
-  : report.shell !== undefined ? 'shells'
-  : report.agentId !== undefined || report.finishForeground === true ? 'agents'
-  : report.hello === true ? 'reporting'
-  : report.toolSessionId !== undefined ? 'tool-session' : 'model') {
+function send(report, kind = reportKind(report)) {
   const body = JSON.stringify(report);
   return new Promise((resolve, reject) => {
     const req = http.request(`${env.AGENT_GUILD_URL}/api/v1/sessions/${env.AGENT_GUILD_SESSION_ID}/${kind}`, {
@@ -97,85 +92,6 @@ function send(report, kind = report.compaction !== undefined ? 'context'
 /** A hook must never break the coding tool, so report failures quietly. */
 const sendQuietly = (report, kind) => send(report, kind).catch((err) => console.error(`agent-guild-report: ${err.message}`));
 
-const MAX_FIRST_LINE = 1024 * 1024;
-
-/** The first JSON record of a JSONL file, or null. */
-function firstRecord(file) {
-  if (typeof file !== 'string') return null;
-  let fd;
-  try {
-    fd = fs.openSync(file, 'r');
-    const chunks = [];
-    const buffer = Buffer.alloc(64 * 1024);
-    for (let total = 0; total < MAX_FIRST_LINE;) {
-      const n = fs.readSync(fd, buffer, 0, buffer.length, null);
-      if (n === 0) break;
-      const end = buffer.subarray(0, n).indexOf(10);
-      chunks.push(Buffer.from(buffer.subarray(0, end === -1 ? n : end)));
-      if (end !== -1) break;
-      total += n;
-    }
-    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
-  } catch {
-    return null;
-  } finally {
-    if (fd !== undefined) fs.closeSync(fd);
-  }
-}
-
-/** The last response of an Antigravity CLI turn, read back from the end of its transcript. */
-function antigravityTranscriptReply(file) {
-  if (typeof file !== 'string') return null;
-  let fd;
-  try {
-    fd = fs.openSync(file, 'r');
-    const size = fs.fstatSync(fd).size;
-    for (let bytes = 256 * 1024; ; bytes *= 4) {
-      const start = Math.max(0, size - bytes);
-      const buffer = Buffer.alloc(size - start);
-      fs.readSync(fd, buffer, 0, buffer.length, start);
-      const lines = buffer.toString('utf8').split('\n');
-      // A window that starts mid-file starts mid-line.
-      if (start > 0) lines.shift();
-      const reply = antigravityReply(lines.map(parseJson));
-      if (reply !== undefined || start === 0) return reply ?? null;
-    }
-  } catch {
-    return null;
-  } finally {
-    if (fd !== undefined) fs.closeSync(fd);
-  }
-}
-
-// Claude Code writes the compaction record a moment after its PostCompact hook starts.
-async function claudeCompaction(file, since) {
-  if (typeof file !== 'string') return null;
-  for (let waited = 0; waited <= 3000; waited += 250) {
-    if (waited) await new Promise((resolve) => setTimeout(resolve, 250));
-    const key = claudeCompactBoundary(tailRecords(file, 1024 * 1024), since);
-    if (key) return key;
-  }
-  return null;
-}
-
-function tailRecords(file, bytes) {
-  let fd;
-  try {
-    fd = fs.openSync(file, 'r');
-    const size = fs.fstatSync(fd).size;
-    const start = Math.max(0, size - bytes);
-    const buffer = Buffer.alloc(size - start);
-    fs.readSync(fd, buffer, 0, buffer.length, start);
-    const lines = buffer.toString('utf8').split('\n');
-    if (start > 0) lines.shift();
-    return lines.map(parseJson);
-  } catch {
-    return [];
-  } finally {
-    if (fd !== undefined) fs.closeSync(fd);
-  }
-}
-
 function parseJson(raw) {
   try { return JSON.parse(raw); } catch { return null; }
 }
@@ -189,25 +105,8 @@ async function main() {
   if (args.hook) {
     const input = parseJson(await readStdin());
     if (!inSession || !input || typeof input !== 'object') return;
-    if (args.event && input.hook_event_name === undefined) input.hook_event_name = args.event;
-    const route = hookRoute(input, env.AGENT_GUILD_REPORTING);
-    if (!route) return;
-    // Docker Agent's events go whole to the manager, which tells its sessions (tabs, sub-agents) apart.
-    if (route === 'docker') {
-      const event = dockerHookEvent(input);
-      if (event) await sendQuietly(event, 'docker');
-      return;
-    }
-    // Antigravity CLI runs the hook in its sub-agents too, each a conversation of its own.
-    if (typeof input.conversationId === 'string' && !antigravityUserConversation(firstRecord(input.transcriptPath))) return;
-    for (const report of hookToReports(input)) {
-      if (report.transcript === undefined) await sendQuietly(report);
-      else {
-        const key = await claudeCompaction(report.transcript, performance.timeOrigin - 2000);
-        if (key) await sendQuietly({ compaction: report.compaction, key });
-      }
-    }
-    if (typeof input.conversationId === 'string' && input.hook_event_name === 'Stop') await sendQuietly({ reply: antigravityTranscriptReply(input.transcriptPath) });
+    const { later } = await handleHookEvent(input, { reporting: env.AGENT_GUILD_REPORTING, event: args.event, since: performance.timeOrigin - 2000, send: sendQuietly });
+    await later;
     return;
   }
   if (args.claudeStatusline) {

package/bin/agent-guild.mjs

@@ -360,6 +360,8 @@ async function main() {
     }
     case 'mcp': {
       // stdout carries only protocol messages from here on.
+      const home = args.find((a) => a.startsWith('--home='))?.slice('--home='.length);
+      if (home) process.env.AGENT_GUILD_HOME = home;
       const { serveMcp } = await import('../src/mcp/server.mjs');
       await serveMcp({ allowInput: flags.has('--allow-input') });
       return undefined;

package/config/providers.default.json

@@ -12,6 +12,7 @@
       "memory": "claude",
       "instructions": "claude",
       "reporting": "claude",
+      "mcp": "claude",
       "homeVar": "CLAUDE_CONFIG_DIR",
       "accountEnv": { "CLAUDE_SECURESTORAGE_CONFIG_DIR": "{dir}" },
       "hooks": { "path": "settings.json", "example": "claude-code-settings.json" },
@@ -55,6 +56,7 @@
       "memory": "codex",
       "instructions": "codex",
       "reporting": "codex",
+      "mcp": "codex",
       "homeVar": "CODEX_HOME",
       "hooks": { "path": "hooks.json", "example": "codex-hooks.json" },
       "modelPattern": "\\bgpt-\\d[a-z0-9.-]*",
@@ -93,6 +95,7 @@
       "history": "antigravity",
       "instructions": "google",
       "reporting": "antigravity",
+      "mcp": "antigravity",
       "modelPattern": "\\bgemini-\\d[a-z0-9.-]*",
       "args": [],
       "resumeArgs": ["--conversation", "{id}"],
@@ -126,6 +129,7 @@
       "memory": "grok",
       "instructions": "grok",
       "reporting": "grok",
+      "mcp": "grok",
       "homeVar": "GROK_HOME",
       "hooks": { "path": "hooks/agent-guild.json", "example": "grok-hooks.json" },
       "modelPattern": "\\bgrok-(?:build|\\d)[a-z0-9.-]*",

package/docs/api.md

@@ -123,8 +123,10 @@ whether its folder is on PATH. `uninstall` is null when Agent Guild cannot
 remove that copy, and `uninstallGuidance` then says how to remove it instead.
 `POST /providers/:id/uninstall` removes one copy.
 
-For a tool that is a Docker CLI plugin (Docker Agent), `installCommand` is the
-command **Install** and **Update** run. `pluginError` says why docker could not
+`installCommand` is the command **Install** and **Update** run for a tool that
+is a Docker CLI plugin (Docker Agent), or that a configured install command
+updates by running again, and null otherwise. `plugin` names the Docker CLI
+plugin the tool is, or is null. `pluginError` says why docker could not
 list the plugin's copies, or is null; `pluginPending` is true until docker has
 listed them once.
 
@@ -151,7 +153,24 @@ leaves the multiplexer's own session running, and
 
 For a tool whose agent or model reporting has to be turned on,
 `reportingEnabled` says whether it is, and `reportingNote` says why that switch
-cannot be used, or is null. `usageUrl`, `billingUrl` and `cloudUrl` are
+cannot be used, or is null.
+
+`mcp` is null unless the tool is installed and Agent Guild can add its own MCP
+server (`agent-guild mcp`, see [mcp.md](mcp.md)) to the tool's settings:
+Claude Code, Codex CLI, Antigravity CLI and Grok Build. Otherwise it is
+`{ state, on, total, accounts }`, read from each account's settings and kept
+for up to a minute. `accounts` lists `{ id, label, state, detail }` per
+account, where `state` is `on`, `off`, `disabled` (Agent Guild's server, turned
+off in the tool), `other` (a server of that name that runs something else,
+which Agent Guild never changes) or `unknown` (the settings could not be
+read), and `detail` says why for `other` and `unknown`. An account whose home folder does not exist yet
+reads `off`, and turning the server on makes the folder. `on` counts the
+accounts that are on, of `total`. The provider's `state` is `on` or `off` when
+every account is, `partial` when some but not all are on, else `unknown`,
+`other` or `disabled` for the first of those any account has; `checking`
+before the first read, with `accounts` empty.
+
+`usageUrl`, `billingUrl` and `cloudUrl` are
 `https://` links to the vendor's usage and billing pages and web app, or null.
 
 ### Manager environment
@@ -622,6 +641,7 @@ All paths are under `/api/v1`.
 | PATCH | `/providers/:id/accounts/:account` | `{ label, revision }` | `{ account, dir, providers, revision }`: renames an account, including `default`. |
 | DELETE | `/providers/:id/accounts/:account?revision=` | | `{ account, dir, providers, revision }`: removes an account from `providers.json`. Its home folder, `dir`, stays on disk. 409 `default_account` for `default`; 409 `account_in_use` while a running session uses it. |
 | POST | `/providers/:id/reporting` | `{ enabled }` | `{ provider }`: turns agent or model reporting on or off for a tool that has `reportingEnabled`. |
+| POST | `/providers/:id/mcp` | `{ enabled }` | `{ provider, results }`: adds Agent Guild's MCP server to, or removes it from, each account of a tool that has `mcp`. Each account is read again first; one whose state is then `other` or `unknown` is left as it is. `results` has one `{ id, label, outcome, state, detail? }` per account, `outcome` `added`, `removed`, `unchanged`, `skipped` or `failed`; a failed account does not undo the others. 400 `not_applicable` for a tool without `mcp`; 409 `provider_unavailable` when it is not installed; 409 `busy` while a change for that tool is running. |
 | POST | `/providers/:id/install` | `{ force? }` | `201 { session }`: a session that installs or updates the tool. 409 `provider_in_use` (with `running`, the session count) while the provider's sessions are running; retry with `force: true` after the user confirms. |
 | POST | `/providers/:id/uninstall` | `{ path, force? }` | `201 { session }`: a session that removes the copy at `path`, one of the provider's `installs`. `force` as for `install`. |
 | GET | `/environment?scope=&cwd=&id=` | | An environment snapshot; see [Manager environment](#manager-environment). |
@@ -674,6 +694,7 @@ All paths are under `/api/v1`.
 | POST | `/sessions/:id/reporting` | | `{ reporting }`: the tool's hooks announce themselves. |
 | POST | `/sessions/:id/docker` | `{ event, sessionId, agentName?, toolName?, toolUseId?, command?, model?, reply? }` | `{ ok }`. One Docker Agent hook event. |
 | POST | `/sessions/:id/shells` | `{ shell, key \| task, match?, agentId?, persist?, endsWithAgent?, kind?, tasks? }` | `{ ok }`. A shell command the tool started, ended or put in the background. |
+| POST | `/sessions/:id/hook?event=&reporting=` | A coding tool's hook event, as the tool gives it to its hooks | `{ ok }`, or `{ ok, errors }` when reports the event makes are refused, each `{ status, code?, message }` as its own route would answer. The manager turns the event into the session's reports as `agent-guild-report --hook` does. `event` names an event that does not name itself; `reporting` is the session's `AGENT_GUILD_REPORTING` where the hook ran, and defaults to the session's own. A transcript the event names is read only if it is a regular file. |
 | POST | `/shutdown` | `{ force?, restart? }` | `202 { ok, running, restart }`: stops the manager and every session, detaching tmux and herdr sessions. 409 `sessions_running` (with `running`) while other sessions run; retry with `force: true` after the user confirms. With `restart`, a new manager takes over on the same port and token, running the version on disk. |
 
 `cwd` defaults to the user's home folder, and a leading `~` is expanded.
@@ -686,14 +707,15 @@ session the card holds; renaming the card to its default name drops it for
 the tool session it holds then.
 
 The `POST /sessions/:id/…` report routes (`agents`, `model`, `tool-session`,
-`context`, `reply`, `reporting`, `docker` and `shells`) also accept the per-session
+`context`, `reply`, `reporting`, `docker`, `shells` and `hook`) also accept the per-session
 report token instead of the API token, in an `X-Agent-Guild-Report-Token`
 header. The manager gives that token only to the processes inside that
 session.
 
 Request bodies are limited to 64 KiB, except `PUT /notes`,
 `POST /sessions/:id/reply` and `POST /sessions/:id/docker`, which accept
-1 MiB. Messages a client sends on a WebSocket are limited to 1 MiB.
+1 MiB, and `POST /sessions/:id/hook`, which accepts 32 MiB and checks the token
+before reading the body. Messages a client sends on a WebSocket are limited to 1 MiB.
 
 ## WebSockets
 

package/examples/terminal-ai-chat.json

@@ -0,0 +1,27 @@
+{
+  "providers": [
+    {
+      "id": "terminal-ai-chat",
+      "vendor": "Odd Essentials",
+      "tool": "Terminal AI Chat",
+      "command": "terminal-ai-chat",
+      "versionArgs": ["--version"],
+      "color": "#E11D48",
+      "monogram": "T",
+      "releases": "https://github.com/oddessentials/terminal-ai-chat-releases/releases/latest",
+      "install": "curl -fsSL https://github.com/oddessentials/terminal-ai-chat-releases/releases/latest/download/install.sh | sh",
+      "docs": "https://github.com/oddessentials/terminal-ai-chat-releases",
+      "channels": {
+        "native": { "paths": ["~/.local/bin/terminal-ai-chat"], "remove": ["~/.local/bin/terminal-ai-chat"], "reinstall": true, "versionEnv": "TAC_VERSION" },
+        "brew": { "names": ["terminal-ai-chat"] }
+      },
+      "win32": {
+        "install": "irm https://github.com/oddessentials/terminal-ai-chat-releases/releases/latest/download/install.ps1 | iex",
+        "channels": {
+          "native": { "paths": ["~/AppData/Local/Programs/terminal-ai-chat"], "remove": ["~/AppData/Local/Programs/terminal-ai-chat"], "reinstall": true, "versionEnv": "TAC_VERSION" },
+          "winget": { "id": "OddEssentials.TerminalAIChat" }
+        }
+      }
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "1.21.1",
+  "version": "1.22.0",
   "description": "Launch and watch AI coding-assistant terminal sessions from one local web page. A bundled session manager owns the terminals so the page can close and reconnect.",
   "mcpName": "ai.oddessentials/agent-guild",
   "license": "AGPL-3.0-only",
@@ -38,6 +38,7 @@
     "manager": "node bin/agent-guild.mjs start",
     "stop": "node bin/agent-guild.mjs stop",
     "build:windows": "node scripts/build-windows-launcher.mjs",
+    "build:reporter": "node scripts/build-reporter.mjs",
     "status": "node bin/agent-guild.mjs status",
     "doctor": "node bin/agent-guild.mjs doctor",
     "demo:build": "node docs/demo/build.mjs",

package/src/manager/install-channels.mjs

@@ -227,6 +227,9 @@ export function classifyInstall({
       if (!npmOnPath) return result('native', { guidance: `${provider.tool} at ${resolvedPath} is updated through npm, but npm was not found.` });
       return result('native', { update: { file: npmOnPath, args: ['install', '-g'], package: provider.package } });
     }
+    if (native.reinstall && provider.install && !provider.package) {
+      return result('native', { update: { file: null, args: [], command: provider.install, reinstall: true } });
+    }
     if (native.update.length === 0) {
       return result('native', { guidance: `${provider.tool} at ${resolvedPath} has no update command configured. Update it the way you installed it.` });
     }

package/src/manager/main.mjs

@@ -23,8 +23,9 @@ import { createCardNames } from './card-names.mjs';
 import { RemoteAccess, loadRemoteAccess } from './remote-access.mjs';
 import { SelfUpdate } from './self-update.mjs';
 import { addRuntimePaths, resolveBaseEnv, pathReader } from './shell-env.mjs';
-import { writeReportShims } from './report-shims.mjs';
+import { nativeReporter, writeReportShims } from './report-shims.mjs';
 import { SessionHooks } from './session-hooks.mjs';
+import { McpConnect, ownServer } from './mcp-connect.mjs';
 import { launcherPath, nextManager } from './launch.mjs';
 import { createAutostart } from './autostart.mjs';
 import { bootSupported, createBootService } from './systemd-service.mjs';
@@ -68,7 +69,7 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
   // because the Node.js path can change between runs.
   let shimDir = null;
   try {
-    shimDir = writeReportShims({ dir: paths.shims, script: path.join(rootDir, 'bin', 'agent-guild-report.mjs') });
+    shimDir = writeReportShims({ dir: paths.shims, script: path.join(rootDir, 'bin', 'agent-guild-report.mjs'), native: nativeReporter(rootDir) });
   } catch (err) {
     console.warn(`[manager] could not write the agent-guild-report launchers to ${paths.shims}: ${err.message}; hooks need the command on PATH`);
   }
@@ -92,6 +93,8 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
   const manager = new SessionManager({
     registry, baseEnv, getApiUrl: () => api.url, sessionDefaults, shimDir, selfUpdate, github, sessionHooks, store: multiplexerStore, cardNames,
   });
+  const mcpConnect = new McpConnect({ registry, own: ownServer(), prepareAccount: (provider, account) => manager.prepareAccount(provider, account), dir: dataDir() });
+  registry.mcpState = (provider) => mcpConnect.describe(provider);
   environment.setSessionLookup((id) => {
     let session;
     try { session = manager.get(id); } catch { return null; }
@@ -184,6 +187,7 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
     notes: createNotesStore(paths.notes),
     launcher: launcherPath(),
     yardArt: new YardArt({ webDir, dir: paths.yardArt }),
+    mcpConnect,
     onShutdownRequest: ({ restart = false } = {}) => shutdown('requested via API', { restart }).then((code) => process.exit(code)),
   });
   remoteAccess.attach({ apply: (access) => api.setAccessPolicy(access), getTarget: () => api.url });

package/src/manager/mcp-connect.mjs

@@ -0,0 +1,249 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { buildSpawnSpec, runSpec } from './command-resolver.mjs';
+import { antigravityConfigFile } from './session-hooks.mjs';
+import { stableExecPath } from './autostart.mjs';
+import { PACKAGE_SCRIPT } from './launch.mjs';
+import { dataDir } from './config.mjs';
+
+export const SERVER_NAME = 'agent-guild';
+export const MCP_MODES = ['claude', 'codex', 'antigravity', 'grok'];
+const STATE_TTL_MS = 60 * 1000;
+const RUN_TIMEOUT_MS = 30000;
+
+export function ownServer(execPath = process.execPath, home = dataDir()) {
+  return { command: stableExecPath(execPath), args: [PACKAGE_SCRIPT, 'mcp', `--home=${path.resolve(home)}`] };
+}
+
+const homeOf = (env, platform) => (platform === 'win32' ? env.USERPROFILE : env.HOME) || os.homedir();
+
+export function classify(entry, own, { enabled = true, command, args, remote = null } = {}) {
+  if (entry === undefined || entry === null) return { state: 'off' };
+  if (remote) return { state: 'other', detail: `agent-guild is already set to ${remote}` };
+  if (typeof command !== 'string' || !Array.isArray(args) || !args.every((a) => typeof a === 'string')) {
+    return { state: 'unknown', detail: 'its MCP settings name the agent-guild server in a form Agent Guild does not recognize' };
+  }
+  if (command !== own.command || args.length !== own.args.length || args.some((a, i) => a !== own.args[i])) {
+    return { state: 'other', detail: `agent-guild is already set to run ${[command, ...args].join(' ')}` };
+  }
+  return { state: enabled === false ? 'disabled' : 'on' };
+}
+
+function readJsonFile(file) {
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return { missing: true };
+    return { error: `${file} cannot be read: ${err.message}` };
+  }
+  try {
+    return { value: JSON.parse(text) };
+  } catch {
+    return { error: `${file} is not valid JSON` };
+  }
+}
+
+function fromServersFile(file, own, enabledOf) {
+  const read = readJsonFile(file);
+  if (read.missing) return { state: 'off' };
+  if (read.error) return { state: 'unknown', detail: read.error };
+  const servers = read.value?.mcpServers;
+  if (servers === undefined) return { state: 'off' };
+  if (!servers || typeof servers !== 'object' || Array.isArray(servers)) return { state: 'unknown', detail: `${file} has mcpServers in a form Agent Guild does not recognize` };
+  const entry = Object.hasOwn(servers, SERVER_NAME) ? servers[SERVER_NAME] : undefined;
+  if (entry === undefined) return { state: 'off' };
+  if (!entry || typeof entry !== 'object') return classify(entry, own);
+  const remote = entry.type !== undefined && entry.type !== 'stdio' ? String(entry.url ?? entry.type) : null;
+  return classify(entry, own, { enabled: enabledOf(entry), command: entry.command, args: entry.args ?? [], remote });
+}
+
+function fromList(stdout, own, pick) {
+  let list;
+  try { list = JSON.parse(stdout); } catch { list = null; }
+  if (!Array.isArray(list)) return { state: 'unknown', detail: 'its MCP server list was not in a form Agent Guild recognizes' };
+  const entry = list.find((item) => item?.name === SERVER_NAME && pick.match(item));
+  if (!entry) return { state: 'off' };
+  return classify(entry, own, pick.fields(entry));
+}
+
+const TOOLS = {
+  claude: {
+    file: (env, platform) => path.join(env.CLAUDE_CONFIG_DIR || homeOf(env, platform), '.claude.json'),
+    read(ctx) { return fromServersFile(this.file(ctx.env, ctx.platform), ctx.own, () => true); },
+    add: (own) => ['mcp', 'add', '-s', 'user', SERVER_NAME, '--', own.command, ...own.args],
+    remove: () => ['mcp', 'remove', '-s', 'user', SERVER_NAME],
+  },
+  codex: {
+    list: ['mcp', 'list', '--json'],
+    pick: {
+      match: () => true,
+      fields: (e) => ({ enabled: e.enabled, command: e.transport?.command, args: e.transport?.args ?? [], remote: e.transport?.type && e.transport.type !== 'stdio' ? String(e.transport.url ?? e.transport.type) : null }),
+    },
+    add: (own) => ['mcp', 'add', SERVER_NAME, '--', own.command, ...own.args],
+    // Adding again replaces the entry, and with it the `enabled = false` that turned it off.
+    enable: (own) => ['mcp', 'add', SERVER_NAME, '--', own.command, ...own.args],
+    remove: () => ['mcp', 'remove', SERVER_NAME],
+  },
+  antigravity: {
+    file: (env, platform) => path.join(path.dirname(antigravityConfigFile(env, platform)), 'mcp_config.json'),
+    read(ctx) { return fromServersFile(this.file(ctx.env, ctx.platform), ctx.own, (entry) => entry.disabled !== true); },
+    add: (own) => ['mcp', 'add', SERVER_NAME, '--', own.command, ...own.args],
+    enable: () => ['mcp', 'enable', SERVER_NAME],
+    remove: () => ['mcp', 'remove', SERVER_NAME],
+  },
+  grok: {
+    list: ['mcp', 'list', '--json'],
+    pick: { match: (e) => e.scope === undefined || e.scope === 'user', fields: (e) => ({ enabled: e.enabled, command: e.command, args: e.args ?? [], remote: e.url ? String(e.url) : null }) },
+    add: (own) => ['mcp', 'add', '-s', 'user', SERVER_NAME, '--', own.command, ...own.args],
+    enable: () => ['mcp', 'enable', SERVER_NAME],
+    remove: () => ['mcp', 'remove', '-s', 'user', SERVER_NAME],
+  },
+};
+
+function lastLine(err) {
+  return `${err.stderr || ''}\n${err.stdout || ''}`.trim().split('\n').map((l) => l.trim()).filter(Boolean).pop() || err.message;
+}
+
+function refusal(status, code, message) {
+  return Object.assign(new Error(message), { status, code });
+}
+
+export function summarize(accounts) {
+  const count = (state) => accounts.filter((a) => a.state === state).length;
+  const total = accounts.length;
+  const on = count('on');
+  const state = on === total ? 'on'
+    : count('off') === total ? 'off'
+      : on > 0 ? 'partial'
+        : count('unknown') ? 'unknown'
+          : count('other') ? 'other'
+            : count('disabled') ? 'disabled'
+              : 'off';
+  return { state, on, total };
+}
+
+export class McpConnect {
+  constructor({ registry, own, prepareAccount, dir = os.homedir(), ttlMs = STATE_TTL_MS }) {
+    this.registry = registry;
+    this.prepareAccount = prepareAccount;
+    this.own = own;
+    this.dir = dir;
+    this.ttlMs = ttlMs;
+    this.cache = new Map();
+    this.reading = new Map();
+    this.reads = 0;
+    this.busy = new Set();
+  }
+
+  _tool(provider) {
+    return MCP_MODES.includes(provider.mcp) ? TOOLS[provider.mcp] : null;
+  }
+
+  _accounts(provider) {
+    return this.registry.accountsFor(provider).map((account) => ({
+      id: account.id, label: account.label, dir: account.dir, account, env: { ...this.registry.env, ...provider.env, ...account.env },
+    }));
+  }
+
+  _signature(provider) {
+    return JSON.stringify(this._accounts(provider).map((a) => [a.id, a.label, a.dir, provider.homeVar ? a.env[provider.homeVar] ?? null : null]));
+  }
+
+  async _run(provider, resolved, env, args) {
+    return runSpec(buildSpawnSpec(resolved, args, env, this.registry.platform), { env, cwd: this.dir, timeoutMs: RUN_TIMEOUT_MS, killTree: true });
+  }
+
+  async readAccount(provider, resolved, account) {
+    const tool = this._tool(provider);
+    // A managed home that does not exist yet holds no settings, and some tools create it when asked.
+    if (account.dir && !fs.existsSync(account.dir)) return { state: 'off' };
+    const ctx = { env: account.env, platform: this.registry.platform, own: this.own };
+    if (tool.read) return tool.read(ctx);
+    try {
+      const { stdout } = await this._run(provider, resolved, account.env, tool.list);
+      return fromList(stdout, this.own, tool.pick);
+    } catch (err) {
+      return { state: 'unknown', detail: `${provider.command} ${tool.list.join(' ')} failed: ${lastLine(err)}` };
+    }
+  }
+
+  async _readAll(provider, resolved) {
+    return Promise.all(this._accounts(provider).map(async (account) => ({ id: account.id, label: account.label, ...await this.readAccount(provider, resolved, account) })));
+  }
+
+  refresh(provider, { force = false } = {}) {
+    const resolved = this.registry.resolve(provider);
+    if (!this._tool(provider) || !resolved) return Promise.resolve(null);
+    const sig = this._signature(provider);
+    const cached = this.cache.get(provider.id);
+    if (!force && cached && cached.resolved === resolved && cached.sig === sig && Date.now() - cached.at < this.ttlMs) return Promise.resolve(cached.accounts);
+    // A forced read follows a change, so a read that started before it must not be the one kept.
+    const pending = this.reading.get(provider.id);
+    if (!force && pending?.sig === sig) return pending.job;
+    const seq = ++this.reads;
+    const job = this._readAll(provider, resolved).then((accounts) => {
+      if (this.reading.get(provider.id)?.seq !== seq) return accounts;
+      this.reading.delete(provider.id);
+      // Accounts that changed during the read make its result obsolete.
+      const current = this.registry.get(provider.id);
+      if (!current || this._signature(current) !== sig) return accounts;
+      const before = this.cache.get(provider.id);
+      this.cache.set(provider.id, { resolved, sig, accounts, at: Date.now() });
+      // A page showing "checking" for a new account set needs this read even when every state is the same.
+      if (before?.sig !== sig || JSON.stringify(accounts) !== JSON.stringify(before.accounts)) this.registry.emit?.('updated');
+      return accounts;
+    }, (err) => {
+      if (this.reading.get(provider.id)?.seq === seq) this.reading.delete(provider.id);
+      throw err;
+    });
+    this.reading.set(provider.id, { seq, sig, job });
+    return job;
+  }
+
+  describe(provider) {
+    if (!this._tool(provider) || !this.registry.resolve(provider)) return null;
+    this.refresh(provider).catch(() => {});
+    const cached = this.cache.get(provider.id);
+    if (!cached || cached.sig !== this._signature(provider)) return { state: 'checking', on: 0, total: provider.accounts.length, accounts: [] };
+    return { ...summarize(cached.accounts), accounts: cached.accounts.map(({ id, label, state, detail }) => ({ id, label, state, detail: detail ?? null })) };
+  }
+
+  async setEnabled(provider, enabled) {
+    const tool = this._tool(provider);
+    if (!tool) throw refusal(400, 'not_applicable', `${provider.tool} has no MCP settings Agent Guild can change`);
+    const resolved = this.registry.resolve(provider);
+    if (!resolved) throw refusal(409, 'provider_unavailable', `${provider.tool} is not installed`);
+    if (this.busy.has(provider.id)) throw refusal(409, 'busy', `${provider.tool}'s MCP settings are already being changed`);
+    this.busy.add(provider.id);
+    try {
+      const results = [];
+      for (const account of this._accounts(provider)) {
+        results.push({ id: account.id, label: account.label, ...await this._change(provider, resolved, tool, account, enabled) });
+      }
+      await this.refresh(provider, { force: true });
+      return results;
+    } finally {
+      this.busy.delete(provider.id);
+    }
+  }
+
+  async _change(provider, resolved, tool, account, enabled) {
+    // The cache is for display only: every change acts on a fresh read of the account.
+    const now = await this.readAccount(provider, resolved, account);
+    const want = enabled ? 'on' : 'off';
+    if (now.state === want) return { outcome: 'unchanged', state: now.state };
+    if (now.state === 'unknown' || now.state === 'other') return { outcome: 'skipped', state: now.state, detail: now.detail };
+    const args = !enabled ? tool.remove() : now.state === 'disabled' ? tool.enable(this.own) : tool.add(this.own);
+    try {
+      if (enabled && account.dir) this.prepareAccount(provider, account.account);
+      await this._run(provider, resolved, account.env, args);
+    } catch (err) {
+      return { outcome: 'failed', state: now.state, detail: `${provider.command} ${args.slice(0, 2).join(' ')} failed: ${lastLine(err)}` };
+    }
+    const after = await this.readAccount(provider, resolved, account);
+    if (after.state !== want) return { outcome: 'failed', state: after.state, detail: after.detail ?? `${provider.tool} reported success, but the server is ${after.state}` };
+    return { outcome: enabled ? 'added' : 'removed', state: after.state };
+  }
+}