agy-plugin-porter 0.1.0 → 0.2.0

package/scripts/mod-runtime/instance.mjs

@@ -0,0 +1,250 @@
+// One Antigravity conversation's copy of a ported Claude Code mod. Each conversation
+// gets its own module instance, so module variables and $.state are per conversation,
+// like Claude Code's per-session state (live, Phase 2.5A).
+import { readFile } from 'node:fs/promises';
+
+import { ELEMENTS, serialize } from './elements.mjs';
+import { overwriteOf, toClaudeCall } from './tool-calls.mjs';
+
+const matches = (matcher, e) => !matcher || Object.entries(matcher).every(([k, v]) => e[k] === v);
+const quiet = (p) => { p.catch(() => {}); return p; };
+
+// $ methods with no Antigravity equivalent that optional features call: they resolve
+// to nothing so the mod keeps working (plan §5.5).
+const NO_OPS = new Set(['ui.blit', 'ui.selection', 'session.messages']);
+const NO_OP_NOUNS = new Set(['model', 'agent']);
+
+export class Instance {
+  constructor(engine, conv, cwd) {
+    Object.assign(this, { engine, conv, cwd: cwd ?? '' });
+    this.hooks = [];
+    this.state = new Map();
+    this.panes = new Map();
+    this.commands = new Map();
+    this.tools = new Map();
+    this.callbacks = new Map();
+    this.pending = [];
+    this.inTurn = false;
+    this.status = undefined;
+    this.renderQueued = false;
+    this.$ = this.dollar();
+  }
+
+  async load() {
+    const mod = await import(`${this.engine.modUrl}?conv=${encodeURIComponent(this.conv || '_none')}`);
+    const register = mod.register ?? mod.default?.register ?? mod.default;
+    if (typeof register !== 'function') throw new Error('the mod exports no register function');
+    const on = (event, a, b) => {
+      const hook = b ? { event, matcher: a, fn: b } : { event, matcher: null, fn: a };
+      this.hooks.push(hook);
+      // on(...).catch(fn): fn($, e, next) runs when the handler throws.
+      const registration = { catch: (fn) => { hook.onError = fn; return registration; } };
+      return registration;
+    };
+    await register(on, this.engine.options);
+    await this.dispatch('session.start', { cwd: this.cwd, source: 'startup' }, () => ({}));
+  }
+
+  has(event) { return this.hooks.some((h) => h.event === event); }
+
+  // Claude's middleware chain: each handler gets next(), the last next() runs `core`.
+  // next() runs the rest once; a second call (from a .catch handler) gets the same result.
+  dispatch(event, e, core) {
+    const hooks = this.hooks.filter((h) => h.event === event && matches(h.matcher, e));
+    const run = (i, input) => {
+      if (i >= hooks.length) return Promise.resolve(core(input));
+      const hook = hooks[i];
+      let result;
+      const next = (changed = input) => {
+        if (!next.called) { next.called = true; result = run(i + 1, changed); }
+        return result;
+      };
+      next.called = false;
+      const frozen = Object.freeze({ ...input });
+      return Promise.resolve().then(() => hook.fn(this.$, frozen, next)).catch((err) => {
+        if (!hook.onError) throw err;
+        this.engine.log('handler-error', { conv: this.conv, event, message: err?.message ?? String(err) });
+        return hook.onError(this.$, frozen, next, err);
+      });
+    };
+    return run(0, e);
+  }
+
+  emit(msg) { this.engine.emit(this.conv, msg); }
+  // Only views the person can see count: Hangar keeps hidden copies of every view.
+  get isPlaced() { return this.engine.visibleViews(this.conv) > 0; }
+
+  impl() {
+    const inst = this;
+    const { store } = this.engine;
+    return {
+      ui: {
+        resolve: () => ELEMENTS,
+        invalidate: () => { inst.scheduleRender(); },
+        open: async ({ id, title }) => {
+          inst.panes.set(id, { id, title: title ?? id });
+          inst.scheduleRender();
+          return { id, isPlaced: inst.isPlaced };
+        },
+        close: async ({ id }) => { inst.panes.delete(id); inst.scheduleRender(); return {}; },
+        panes: async () => [...inst.panes.values()].map((p) => ({ id: p.id, title: p.title, isPlaced: inst.isPlaced, isShown: inst.isPlaced })),
+        status: async (text) => { inst.status = text ?? undefined; inst.emit({ type: 'status', text: text ?? null }); },
+        toast: async (text) => { inst.emit({ type: 'toast', text: String(text) }); },
+        copy: async ({ text }) => {
+          if (!inst.isPlaced) return { isCopied: false, reason: 'no view is open' };
+          inst.emit({ type: 'copy', text: String(text) });
+          return { isCopied: true };
+        },
+      },
+      // Never drafts or sends into agy's prompt box (it can't): copies, and says so.
+      prompt: {
+        fill: async ({ text }) => {
+          if (!inst.isPlaced) return { isFilled: false, reason: 'no view is open' };
+          inst.emit({ type: 'fill', text: String(text) });
+          return { isFilled: true };
+        },
+      },
+      state: {
+        get: async (key) => inst.state.get(key),
+        set: async (key, value) => { inst.state.set(key, value); inst.scheduleRender(); return {}; },
+      },
+      store: {
+        keys: async () => Object.keys(store.data),
+        get: async (key) => (Object.hasOwn(store.data, key) ? store.data[key] : undefined),
+        set: async (key, value) => { store.data[key] = value; store.save(); },
+        delete: async (key) => { delete store.data[key]; store.save(); },
+      },
+      clock: { now: async () => Date.now() },
+      fs: { read: async (path) => readFile(path, 'utf8') },
+      session: { cwd: async () => inst.cwd, id: async () => inst.conv },
+      command: { register: async (def) => { inst.commands.set(String(def.name), { ...def }); inst.scheduleRender(); return {}; } },
+      tool: { register: async (def) => { inst.tools.set(String(def.name), { ...def }); return {}; } },
+    };
+  }
+
+  // $ exposes only what the static scan found (mod.json `allow`); anything else throws.
+  dollar() {
+    const impl = this.impl();
+    const allow = new Set(this.engine.mod.allow ?? []);
+    const plugin = Object.freeze({ name: this.engine.mod.pluginName ?? this.engine.mod.plugin });
+    return new Proxy(Object.create(null), {
+      get: (_, noun) => {
+        if (typeof noun !== 'string' || noun === 'then') return undefined;
+        if (noun === 'plugin') {
+          if (!allow.has('plugin.name')) throw new Error("$.plugin wasn't in the mod's static scan");
+          return plugin;
+        }
+        return new Proxy(Object.create(null), {
+          get: (__, method) => {
+            if (typeof method !== 'string' || method === 'then') return undefined;
+            const name = `${noun}.${method}`;
+            if (!allow.has(name)) throw new Error(`$.${name} wasn't in the mod's static scan`);
+            if (NO_OPS.has(name) || NO_OP_NOUNS.has(noun)) return async () => undefined;
+            const fn = Object.hasOwn(impl, noun) && Object.hasOwn(impl[noun], method) ? impl[noun][method] : null;
+            return fn ?? (() => quiet(Promise.reject(new Error(`$.${name} is not available in the Antigravity port`))));
+          },
+        });
+      },
+    });
+  }
+
+  scheduleRender() {
+    if (this.renderQueued) return;
+    this.renderQueued = true;
+    setTimeout(() => {
+      this.renderQueued = false;
+      this.render().catch((err) => this.engine.log('render-error', { conv: this.conv, message: err.message }));
+    }, 0);
+  }
+
+  async renderOne(e, cb) {
+    try {
+      return { tree: serialize(await this.dispatch('ui.render', e, () => null), cb) };
+    } catch (err) {
+      return { tree: null, error: err.message };
+    }
+  }
+
+  async render() {
+    const callbacks = new Map();
+    const gen = (this.gen = (this.gen ?? 0) + 1);
+    let n = 0;
+    const cb = (fn) => { const id = `${gen}.${n++}`; callbacks.set(id, fn); return id; };
+    const props = { bodyColumns: 80, bodyRows: 40 };
+    const panes = [];
+    for (const p of this.panes.values()) {
+      const e = { component: 'Pane', requestId: p.id, surface: 'desktop', props };
+      panes.push({ id: p.id, title: p.title, ...(await this.renderOne(e, cb)) });
+    }
+    // AbovePrompt and PromptHint draw as a strip above the panes (plan §5.5).
+    const strips = [];
+    for (const component of ['AbovePrompt', 'PromptHint']) {
+      if (!this.hooks.some((h) => h.event === 'ui.render' && h.matcher?.component === component)) continue;
+      const r = await this.renderOne({ component, surface: 'desktop', props }, cb);
+      if (r.tree) strips.push({ component, tree: r.tree });
+    }
+    // Keep the previous render's callbacks too, for a click that crossed a redraw.
+    this.callbacks = new Map([...(this.lastCallbacks ?? []), ...callbacks]);
+    this.lastCallbacks = callbacks;
+    this.snapshot = { type: 'state', panes, strips, status: this.status ?? null, commands: [...this.commands.values()] };
+    this.emit(this.snapshot);
+  }
+
+  async act(id, args) {
+    const fn = this.callbacks.get(id);
+    if (!fn) throw new Error('that control is gone; the pane was redrawn');
+    await fn(...args);
+    this.scheduleRender();
+  }
+
+  // PreToolUse: run the tool.call chain until a handler returns or calls next().
+  // A handler waiting in next() resumes at PostToolUse (plan §5.2).
+  async preToolUse(payload) {
+    const { e, args } = toClaudeCall(payload.toolCall);
+    let reached;
+    const reachedNext = new Promise((r) => { reached = r; });
+    const core = (e2) => {
+      reached({ e2 });
+      return new Promise((resolve) => this.pending.push({ stepIdx: payload.stepIdx, tool: e.tool, at: Date.now(), resolve }));
+    };
+    const handled = this.dispatch('tool.call', e, core).then((returned) => ({ returned }), (error) => ({ error }));
+    let timer;
+    const timeout = new Promise((r) => { timer = setTimeout(() => r({ timeout: true }), this.engine.preToolWaitMs); });
+    const first = await Promise.race([reachedNext, handled, timeout]);
+    clearTimeout(timer);
+    if (first.e2) {
+      const overwrite = overwriteOf(args, e, first.e2);
+      return { decision: overwrite ? { decision: 'allow', overwrite } : null, path: overwrite ? 'next(changed)' : 'next' };
+    }
+    if (first.returned?.deny) return { decision: { decision: 'deny', reason: String(first.returned.deny) }, path: 'deny' };
+    if (first.error) this.engine.log('tool-call-error', { conv: this.conv, message: first.error?.message ?? String(first.error) });
+    return { decision: null, path: first.timeout ? 'timeout' : first.error ? 'error' : 'returned' };
+  }
+
+  // PostToolUse: resume the suspended handler with the same stepIdx (live: Post
+  // carries its Pre's stepIdx), else the oldest one for the same tool.
+  postToolUse(payload) {
+    this.dropStale();
+    const { e } = toClaudeCall(payload.toolCall);
+    let i = this.pending.findIndex((p) => p.stepIdx !== undefined && p.stepIdx === payload.stepIdx);
+    const by = i >= 0 ? 'stepIdx' : 'fifo';
+    if (i < 0) i = this.pending.findIndex((p) => p.tool === e.tool);
+    if (i < 0) return 'no suspended handler';
+    const [p] = this.pending.splice(i, 1);
+    const error = payload.error || '';
+    p.resolve(error ? { result: undefined, text: error, isError: true, error } : { result: undefined, text: '', isError: false });
+    return `resumed (${by})`;
+  }
+
+  // Handlers whose PostToolUse never came (a denied call, a lost event).
+  dropPending(reason) {
+    for (const p of this.pending.splice(0)) p.resolve({ result: undefined, text: reason, isError: true, error: reason });
+  }
+
+  dropStale(now = Date.now()) {
+    const stale = this.pending.filter((p) => now - p.at > this.engine.pendingMaxMs);
+    this.pending = this.pending.filter((p) => !stale.includes(p));
+    for (const p of stale) p.resolve({ result: undefined, text: 'no PostToolUse in time', isError: true, error: 'no PostToolUse in time' });
+    return stale.length;
+  }
+}

package/scripts/mod-runtime/lifecycle.mjs

@@ -0,0 +1,45 @@
+// The sidecar's server_info.json and its exit. On Windows, quitting the app
+// hard-kills the language server and orphans every sidecar (live,
+// ui-mods-baseline.md), so the sidecar exits once ANTIGRAVITY_LS_ADDRESS stops
+// answering. An orphan can notice that after its replacement started, so it
+// removes server_info.json only while the file still holds its own pid (live fix).
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { connect } from 'node:net';
+import { join } from 'node:path';
+
+export function writeServerInfo(dataDir, info) {
+  writeFileSync(join(dataDir, 'server_info.json'), JSON.stringify({ ...info, pid: process.pid }, null, 2));
+}
+
+export function removeServerInfoIfOurs(dataDir, pid = process.pid) {
+  const file = join(dataDir, 'server_info.json');
+  try {
+    if (JSON.parse(readFileSync(file, 'utf8')).pid !== pid) return false;
+    rmSync(file, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Calls onGone after two failed connects in a row, 5 s apart.
+export function watchLanguageServer(address, onGone, { everyMs = 5000 } = {}) {
+  const m = /([^/:]+|\[[^\]]+\]):(\d+)/.exec(address ?? '');
+  if (!m) return null;
+  let failures = 0;
+  return setInterval(() => {
+    const socket = connect({ host: m[1].replace(/^\[|\]$/g, ''), port: Number(m[2]) });
+    const done = (alive) => {
+      socket.destroy();
+      failures = alive ? 0 : failures + 1;
+      if (failures >= 2) onGone('language server gone');
+    };
+    socket.setTimeout(2000, () => done(false));
+    socket.once('connect', () => done(true));
+    socket.once('error', () => done(false));
+  }, everyMs).unref();
+}
+
+export function stopOnSignals(stop) {
+  for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGBREAK']) process.on(sig, () => stop(sig));
+}

package/scripts/mod-runtime/locate.mjs

@@ -0,0 +1,48 @@
+// Shared by the sidecar, the MCP server and the hook forwarder. mod.json (next to
+// this file, written by agy-plugin-porter) names the plugin, the sidecar and what the
+// mod's static scan found. Finds the sidecar's data dir the way Google's science
+// plugin does, and calls the sidecar through server_info.json.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const MOD = JSON.parse(readFileSync(new URL('./mod.json', import.meta.url), 'utf8'));
+export const LOOPBACK = '127.0.0.1';
+
+// ANTIGRAVITY_EXECUTABLE_DATA_DIR (set for the sidecar only, live), else the first
+// ~/.gemini/<product>/sidecar_data/<plugin>/<sidecar>/data that exists.
+export function findDataDir() {
+  const env = process.env.ANTIGRAVITY_EXECUTABLE_DATA_DIR?.trim();
+  if (env) return env;
+  const gemini = join(homedir(), '.gemini');
+  let products = [];
+  try { products = readdirSync(gemini, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name); } catch {}
+  for (const product of products) {
+    const dir = join(gemini, product, 'sidecar_data', MOD.plugin, MOD.sidecar, 'data');
+    if (existsSync(dir)) return dir;
+  }
+  return null;
+}
+
+export function readServerInfo(dir = findDataDir()) {
+  if (!dir) return null;
+  try { return JSON.parse(readFileSync(join(dir, 'server_info.json'), 'utf8')); } catch { return null; }
+}
+
+// Loopback only, whatever server_info.json says. Re-reads the file on every call:
+// a restart changes the port and token, and orphans leave stale files behind (live).
+export async function callSidecar(path, body, timeoutMs = 2000) {
+  const info = readServerInfo();
+  if (!info) throw new Error('sidecar not running (no server_info.json)');
+  const port = Number(info.port);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('bad port in server_info.json');
+  if (typeof info.token !== 'string' || !/^[0-9a-f]{16,128}$/.test(info.token)) throw new Error('bad token in server_info.json');
+  const res = await fetch(`http://${LOOPBACK}:${port}${path}`, {
+    method: body === undefined ? 'GET' : 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-Sidecar-Token': info.token },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status} from the sidecar`);
+  return res.json();
+}

package/scripts/mod-runtime/mcp-entry.mjs

@@ -0,0 +1,55 @@
+// Stdio MCP server for a ported Claude Code mod: the tools the mod registers with
+// $.tool.register, plus one slash_<name> tool per $.command.register. Forwards to the
+// sidecar. With the sidecar down it lists what the static scan found (mod.json) and
+// fails calls with a clear error.
+import { createInterface } from 'node:readline';
+
+import { MOD, callSidecar } from './locate.mjs';
+
+const CONVERSATION_META = 'antigravity.google/conversation_id';
+const write = (msg) => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', ...msg }) + '\n');
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+const OPEN_SCHEMA = { type: 'object', properties: {} };
+
+const scannedTools = () => [
+  ...(MOD.tools ?? []).map((t) => ({ name: t.name, description: t.description ?? '', inputSchema: OPEN_SCHEMA })),
+  ...(MOD.commands ?? []).map((c) => ({
+    name: `slash_${c.name}`,
+    description: `Runs the /${c.name} command: ${c.description ?? ''}`.trim(),
+    inputSchema: { type: 'object', properties: { args: { type: 'string' } } },
+  })),
+];
+
+// The sidecar may still be starting when agy asks for the list: retry for ~6 s.
+async function listTools() {
+  for (let i = 0; i < 6; i++) {
+    try { return (await callSidecar('/api/mcp', { op: 'list' })).tools; } catch { await wait(500); }
+  }
+  return scannedTools();
+}
+
+createInterface({ input: process.stdin }).on('line', async (line) => {
+  let msg;
+  try { msg = JSON.parse(line); } catch { return; }
+  const { id, method, params = {} } = msg ?? {};
+  switch (method) {
+    case 'initialize':
+      return write({ id, result: { protocolVersion: params.protocolVersion ?? '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: MOD.mcpServer, version: MOD.version ?? '0.0.0' } } });
+    case 'ping':
+      return write({ id, result: {} });
+    case 'tools/list':
+      return write({ id, result: { tools: await listTools() } });
+    case 'tools/call': {
+      const conv = params._meta?.[CONVERSATION_META] ?? '';
+      try {
+        // A mod's own tool may do real work, so calls get longer than the 2 s default.
+        const r = await callSidecar('/api/mcp', { op: 'call', name: params.name, args: params.arguments ?? {}, conv }, 20_000);
+        return write({ id, result: { content: [{ type: 'text', text: r.text }], isError: Boolean(r.isError) } });
+      } catch (err) {
+        return write({ id, result: { content: [{ type: 'text', text: `${MOD.title} isn't running, so ${params.name} can't run (${err.message}).` }], isError: true } });
+      }
+    }
+    default:
+      if (id !== undefined) write({ id, error: { code: -32601, message: `method not found: ${method}` } });
+  }
+});

package/scripts/mod-runtime/server.mjs

@@ -0,0 +1,178 @@
+// Sidecar for a Claude Code mod ported by agy-plugin-porter. Hosts the mod (engine.mjs)
+// and serves its panes to the side-pane view, the hook forwarder (hook.mjs) and the
+// MCP server (mcp-entry.mjs). Zero dependencies. The view's static files and the SDK's
+// preload.js are public; every /api route needs this server's token (server_info.json)
+// or the host's ANTIGRAVITY_SIDECAR_UI_TOKEN (the view's ?token=).
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { Engine } from './engine.mjs';
+import { removeServerInfoIfOurs, stopOnSignals, watchLanguageServer, writeServerInfo } from './lifecycle.mjs';
+import { LOOPBACK, MOD } from './locate.mjs';
+
+const DATA_DIR = process.env.ANTIGRAVITY_EXECUTABLE_DATA_DIR?.trim()
+  || join(homedir(), '.gemini', 'antigravity', 'sidecar_data', MOD.plugin, MOD.sidecar, 'data');
+mkdirSync(DATA_DIR, { recursive: true });
+const tokens = [randomBytes(24).toString('hex'), process.env.ANTIGRAVITY_SIDECAR_UI_TOKEN].filter(Boolean);
+const views = new Map(); // conversation id -> Map(view id -> {res, visible})
+let nextView = 1;
+
+function log(event, data = {}) {
+  try { appendFileSync(join(DATA_DIR, 'runtime.log'), JSON.stringify({ at: new Date().toISOString(), pid: process.pid, event, ...data }) + '\n'); } catch {}
+}
+process.on('unhandledRejection', (err) => log('unhandled-rejection', { message: err?.message ?? String(err) }));
+
+const engine = new Engine({
+  mod: MOD,
+  modUrl: pathToFileURL(join(import.meta.dirname, MOD.entry)).href,
+  dataDir: DATA_DIR,
+  log,
+  visibleViews: (conv) => [...(views.get(conv)?.values() ?? [])].filter((v) => v.visible).length,
+  emit: (conv, msg) => {
+    const text = `data: ${JSON.stringify(msg)}\n\n`;
+    for (const v of views.get(conv)?.values() ?? []) v.res.write(text);
+  },
+});
+
+const pill = `[Open ${MOD.title}](sidecar://${MOD.plugin}/${MOD.sidecar}/ui.html)`;
+
+function send(res, status, body, type = 'application/json; charset=utf-8') {
+  res.writeHead(status, { 'Content-Type': type, 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' });
+  res.end(typeof body === 'string' ? body : JSON.stringify(body));
+}
+
+function readJson(req) {
+  return new Promise((resolve) => {
+    let raw = '';
+    req.on('data', (c) => { if (raw.length < 4e6) raw += c; });
+    req.on('end', () => { try { const v = raw ? JSON.parse(raw) : {}; resolve(v && typeof v === 'object' ? v : {}); } catch { resolve({}); } });
+  });
+}
+
+// The SDK's preload.js gives the view window.sidecar (live: the host doesn't).
+// Same lookup as science's server.cjs: ANTIGRAVITY_APP_DATA_DIR, else ~/.gemini/antigravity.
+function preloadJs() {
+  const appDir = process.env.ANTIGRAVITY_APP_DATA_DIR?.trim() || join(homedir(), '.gemini', 'antigravity');
+  try { return readFileSync(join(appDir, 'lib', 'node_modules', 'sidecar_sdk', 'preload.js'), 'utf8'); } catch { return null; }
+}
+
+const STATIC = { '/ui.html': 'text/html', '/ui.js': 'application/javascript', '/ui-draw.js': 'application/javascript' };
+
+// A view's conversation: a real id, or '' for a new-conversation view (no data shown).
+const convOf = (v) => (typeof v === 'string' && v && v !== '_new' ? v : '');
+
+const routes = {
+  'GET /api/events': async (req, res, url) => {
+    const conv = convOf(url.searchParams.get('conv'));
+    const id = String(nextView++);
+    res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-store', Connection: 'keep-alive' });
+    res.write(`data: ${JSON.stringify({ type: 'hello', mod: MOD.title, conv, view: id })}\n\n`);
+    if (!conv) return;
+    if (!views.has(conv)) views.set(conv, new Map());
+    views.get(conv).set(id, { res, visible: false });
+    req.on('close', () => views.get(conv)?.delete(id));
+    log('view-open', { conv, view: id, views: views.get(conv).size });
+    const inst = await engine.get(conv);
+    await inst.render();
+  },
+  // The view reports its workspace, which is the conversation's cwd until a hook says otherwise.
+  'POST /api/view': async (req, res, url, body) => {
+    const conv = convOf(body.conv);
+    if (conv) await engine.get(conv, typeof body.cwd === 'string' && body.cwd ? body.cwd : undefined);
+    send(res, 200, { ok: true });
+  },
+  // visibilityState + IntersectionObserver from the view: hidden copies don't count.
+  'POST /api/visibility': async (req, res, url, body) => {
+    const v = views.get(convOf(body.conv))?.get(String(body.view));
+    if (v) v.visible = body.visible === true;
+    send(res, 200, { ok: Boolean(v) });
+  },
+  'POST /api/action': async (req, res, url, body) => {
+    const inst = await engine.get(convOf(body.conv));
+    await inst.act(String(body.cb), Array.isArray(body.args) ? body.args : []);
+    send(res, 200, { ok: true });
+  },
+  'POST /api/command': async (req, res, url, body) => {
+    const inst = await engine.get(convOf(body.conv));
+    const r = await engine.runCommand(inst, String(body.command), typeof body.args === 'string' ? body.args : '', 'view');
+    if (r.text) inst.emit({ type: 'toast', text: r.text });
+    send(res, 200, r);
+  },
+  'POST /api/close': async (req, res, url, body) => {
+    const inst = await engine.get(convOf(body.conv));
+    inst.panes.delete(String(body.id));
+    await inst.dispatch('ui.close', { id: String(body.id), origin: { kind: 'person' } }, () => undefined);
+    await inst.render();
+    send(res, 200, { ok: true });
+  },
+  'POST /api/hook': async (req, res, url, body) => {
+    const started = Date.now();
+    const payload = body.payload && typeof body.payload === 'object' ? body.payload : {};
+    const out = await engine.hook(String(body.event), payload);
+    log('hook', { hookEvent: body.event, ms: Date.now() - started, path: out.path, stdout: out.stdout,
+      conv: payload.conversationId, stepIdx: payload.stepIdx, tool: payload.toolCall?.name, error: payload.error });
+    send(res, 200, out);
+  },
+  'POST /api/mcp': async (req, res, url, body) => {
+    if (body.op === 'list') return send(res, 200, { tools: await engine.listTools() });
+    const name = String(body.name);
+    const r = await engine.callTool(convOf(body.conv), name, body.args && typeof body.args === 'object' ? body.args : {});
+    log('mcp-call', { name, conv: body.conv, isError: r.isError });
+    // A server can't open a view (live), so command results say how to.
+    const link = name.startsWith('slash_') && MOD.hasPane ? `\n\nGive the user this link on its own line, exactly: ${pill}` : '';
+    send(res, 200, { isError: r.isError, text: `${r.text || '(done)'}${link}` });
+  },
+  'GET /api/debug': (req, res) => send(res, 200, {
+    instances: [...engine.instances.values()].map(({ inst }) => ({
+      conv: inst.conv, cwd: inst.cwd, panes: [...inst.panes.keys()], pending: inst.pending.length,
+      views: views.get(inst.conv)?.size ?? 0, visibleViews: engine.visibleViews(inst.conv),
+    })),
+  }),
+};
+
+function tokenOk(t) {
+  if (typeof t !== 'string' || !t) return false;
+  const given = Buffer.from(t);
+  return tokens.some((k) => { const want = Buffer.from(k); return want.length === given.length && timingSafeEqual(want, given); });
+}
+
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url, `http://${LOOPBACK}`);
+  if (req.method === 'GET' && url.pathname === '/preload.js') {
+    const js = preloadJs();
+    return js ? send(res, 200, js, 'application/javascript; charset=utf-8') : send(res, 404, { error: 'sidecar_sdk preload.js not found' });
+  }
+  if (req.method === 'GET' && Object.hasOwn(STATIC, url.pathname)) {
+    return send(res, 200, readFileSync(join(import.meta.dirname, url.pathname.slice(1)), 'utf8'), `${STATIC[url.pathname]}; charset=utf-8`);
+  }
+  if (!tokenOk(req.headers['x-sidecar-token'] || url.searchParams.get('token'))) return send(res, 401, { error: 'no valid token' });
+  const key = `${req.method} ${url.pathname}`;
+  if (!Object.hasOwn(routes, key)) return send(res, 404, { error: 'not found' });
+  try {
+    await routes[key](req, res, url, req.method === 'POST' ? await readJson(req) : null);
+  } catch (err) {
+    log('route-error', { path: url.pathname, message: err.message });
+    if (!res.headersSent) send(res, 500, { error: err.message });
+  }
+});
+
+function stop(reason) {
+  log('stop', { reason });
+  removeServerInfoIfOurs(DATA_DIR);
+  process.exit(0);
+}
+
+const webPort = Number.parseInt(process.env.ANTIGRAVITY_SIDECAR_WEB_PORT ?? '', 10);
+server.on('error', (err) => { log('listen-error', { message: err.message }); process.exit(1); });
+server.listen(Number.isNaN(webPort) ? 0 : webPort, LOOPBACK, () => {
+  const { port } = server.address();
+  writeServerInfo(DATA_DIR, { host: LOOPBACK, port, token: tokens[0] });
+  log('start', { port, node: process.version, dataDir: DATA_DIR, mod: MOD.entry, hostToken: tokens.length > 1 });
+  console.log(`[${MOD.plugin}/${MOD.sidecar}] listening on ${LOOPBACK}:${port}`);
+  watchLanguageServer(process.env.ANTIGRAVITY_LS_ADDRESS, stop);
+});
+stopOnSignals(stop);

package/scripts/mod-runtime/tool-calls.mjs

@@ -0,0 +1,83 @@
+// agy tool calls <-> Claude Code tool.call input. The names match lib/tool-map.mjs
+// (test/mod-runtime.test.mjs checks it); this copy ships alone inside each sidecar.
+// Arg names: the agy CLI's, which the desktop app uses too (live, ui-mods-baseline.md).
+const AGY_TO_CLAUDE = {
+  run_command: 'Bash', view_file: 'Read', read_file: 'Read', write_to_file: 'Write', write_file: 'Write',
+  replace_file_content: 'Edit', edit_file: 'Edit', multi_replace_file_content: 'MultiEdit', grep_search: 'Grep',
+  find_by_name: 'Glob', list_dir: 'LS', read_url_content: 'WebFetch', search_web: 'WebSearch',
+  notebook_edit: 'NotebookEdit', invoke_subagent: 'Task',
+};
+const ARG_NAMES = {
+  CommandLine: 'command', Path: 'file_path', TargetFile: 'file_path', AbsolutePath: 'file_path',
+  Content: 'content', CodeContent: 'content', Target: 'old_string', Replacement: 'new_string',
+};
+// Tool args come from the model; never let one reach an object's prototype.
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+export const claudeToolName = (agyName) => AGY_TO_CLAUDE[agyName] ?? agyName;
+
+function safeJson(text) { try { return JSON.parse(text); } catch { return {}; } }
+
+// Returns {e, args}: the Claude-shaped event and the raw agy args.
+export function toClaudeCall(toolCall) {
+  const raw = typeof toolCall?.args === 'string' ? safeJson(toolCall.args) : toolCall?.args;
+  const args = raw && typeof raw === 'object' ? raw : {};
+  const toolName = toolCall?.name ?? '';
+  if ((toolName === 'call_mcp_tool' || toolName === 'mcp_tool') && (args.ServerName || args.server_name) && (args.ToolName || args.tool_name)) {
+    const server = args.ServerName ?? args.server_name;
+    const tool = args.ToolName ?? args.tool_name;
+    const argKey = 'Arguments' in args ? 'Arguments' : ('arguments' in args ? 'arguments' : 'Arguments');
+    const rawInner = args[argKey];
+    const inner = typeof rawInner === 'string' ? safeJson(rawInner) : (rawInner && typeof rawInner === 'object' ? rawInner : {});
+    const e = { tool: `mcp__${server}__${tool}` };
+    for (const [k, v] of Object.entries(inner)) if (!UNSAFE_KEYS.has(k)) e[k] = v;
+    const taggedArgs = Object.defineProperty({ ...args }, '_mcpEnvelope', {
+      value: { argKey, wasString: typeof rawInner === 'string', inner },
+      enumerable: false,
+    });
+    return { e, args: taggedArgs };
+  }
+  let mappedTool = claudeToolName(toolName);
+  if (mappedTool === toolName && toolName.startsWith('mcp_') && toolName !== 'mcp_tool') {
+    const rest = toolName.slice(4);
+    const idx = rest.indexOf('_');
+    if (idx > 0) mappedTool = `mcp__${rest.slice(0, idx)}__${rest.slice(idx + 1)}`;
+  }
+  const e = { tool: mappedTool };
+  for (const [k, v] of Object.entries(args)) if (!UNSAFE_KEYS.has(k)) e[ARG_NAMES[k] ?? k] = v;
+  const chunks = args.ReplacementChunks;
+  if (Array.isArray(chunks) && chunks.length) {
+    e.old_string = chunks.map((c) => c?.TargetContent ?? '').join('\n…\n');
+    e.new_string = chunks.map((c) => c?.ReplacementContent ?? '').join('\n…\n');
+  }
+  return { e, args };
+}
+
+// The args a handler's next({...changed}) changed, under their agy names: an agy
+// `overwrite`. Returns null when nothing changed.
+export function overwriteOf(args, before, after) {
+  if (args?._mcpEnvelope) {
+    const { argKey, wasString, inner } = args._mcpEnvelope;
+    const nextInner = { ...inner };
+    let changed = false;
+    for (const k of Object.keys({ ...inner, ...after })) {
+      if (k === 'tool' || UNSAFE_KEYS.has(k)) continue;
+      if (after[k] !== before[k]) {
+        nextInner[k] = after[k];
+        changed = true;
+      }
+    }
+    if (!changed) return null;
+    return {
+      ...args,
+      [argKey]: wasString ? JSON.stringify(nextInner) : nextInner,
+    };
+  }
+  const out = {};
+  for (const k of Object.keys(args)) {
+    if (UNSAFE_KEYS.has(k)) continue;
+    const name = ARG_NAMES[k] ?? k;
+    if (after[name] !== before[name]) out[k] = after[name];
+  }
+  return Object.keys(out).length ? out : null;
+}