synabun 2.0.10 → 2.2.0

package/neural-interface/lib/antigravity/policy-hook.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// ═══════════════════════════════════════════
+// SynaBun — the PreToolUse hook of a SynaBun Antigravity home (lib/antigravity/home.js)
+// ═══════════════════════════════════════════
+//
+// Antigravity runs this before every tool call of a brain or run SynaBun started, with the call on
+// stdin ({ toolCall: { name, args }, conversationId, workspacePaths, … }) and the agent's own
+// environment, which carries where SynaBun listens (SYNABUN_AGY_POLICY_URL, a loopback address) and
+// the home's token (SYNABUN_AGY_POLICY_TOKEN). It prints SynaBun's answer ({ decision, reason? }).
+// Whatever goes wrong (no token, SynaBun not answering, a bad answer) the call is refused with the
+// reason: a SynaBun home never runs a tool nobody checked. No imports of SynaBun's own: it starts
+// for every call, so it stays small.
+
+const MAX_INPUT = 4 * 1024 * 1024;
+const TIMEOUT_MS = 15_000;
+
+function answer(value) {
+  process.stdout.write(JSON.stringify(value));
+}
+function refuse(reason) {
+  answer({ decision: 'deny', reason: `SynaBun policy: ${reason}` });
+}
+
+async function readStdin() {
+  let size = 0;
+  const chunks = [];
+  let truncated = false;
+  for await (const chunk of process.stdin) {
+    size += chunk.length;
+    if (size > MAX_INPUT) { truncated = true; continue; }
+    chunks.push(chunk);
+  }
+  return { text: Buffer.concat(chunks).toString('utf8'), truncated };
+}
+
+function loopbackUrl(raw) {
+  try {
+    const url = new URL(String(raw || ''));
+    if (url.protocol !== 'http:') return null;
+    const host = url.hostname.replace(/^\[|\]$/g, '');
+    return host === '127.0.0.1' || host === 'localhost' || host === '::1' ? url : null;
+  } catch { return null; }
+}
+
+async function main() {
+  const url = loopbackUrl(process.env.SYNABUN_AGY_POLICY_URL);
+  const token = String(process.env.SYNABUN_AGY_POLICY_TOKEN || '');
+  if (!url || !token) { refuse('this Antigravity session is missing its SynaBun policy settings, so no tool runs. End the turn and report it.'); return; }
+  const input = await readStdin();
+  if (input.truncated) { refuse('the tool-call input exceeded the size limit, so it is refused.'); return; }
+  let payload;
+  try { payload = JSON.parse(input.text); } catch { refuse('the tool-call input is not valid JSON, so it is refused.'); return; }
+  const toolCall = payload?.toolCall;
+  if (!toolCall || typeof toolCall !== 'object' || Array.isArray(toolCall) || typeof toolCall.name !== 'string' || !toolCall.name.trim()) {
+    refuse('the input has no valid tool call, so it is refused.'); return;
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      // An agent's own call says who it is (lib/owner-authority.js isAgentCall): its pin, never a secret.
+      headers: { 'Content-Type': 'application/json', 'X-Synabun-Terminal': String(process.env.SYNABUN_TERMINAL_SESSION || 'antigravity').slice(0, 200) },
+      body: JSON.stringify({ token, payload: { toolCall: payload?.toolCall || null, conversationId: payload?.conversationId || null, stepIdx: payload?.stepIdx ?? null } }),
+      signal: controller.signal,
+    });
+    const body = await res.json().catch(() => null);
+    if (!res.ok || !body || typeof body.decision !== 'string') { refuse(`SynaBun did not answer for this call (HTTP ${res.status}), so it is refused.`); return; }
+    if (body.decision === 'deny') { answer({ decision: 'deny', reason: String(body.reason || 'SynaBun refused this call.') }); return; }
+    answer(body.decision === 'allow' ? { decision: 'allow' } : { decision: 'ask' });
+  } catch (error) {
+    refuse(`SynaBun could not be reached to check this call (${error?.name === 'AbortError' ? 'timed out' : String(error?.message || error).slice(0, 120)}), so it is refused.`);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+main().catch((error) => refuse(`the check failed (${String(error?.message || error).slice(0, 120)}).`));

package/neural-interface/lib/antigravity/policy.js

@@ -0,0 +1,74 @@
+// ═══════════════════════════════════════════
+// SynaBun — Antigravity tool policy: what the PreToolUse hook of a SynaBun home asks
+// ═══════════════════════════════════════════
+//
+// Every Antigravity brain and run SynaBun starts has a hook (lib/antigravity/policy-hook.mjs) that
+// Antigravity runs before each tool call. The hook sends the call to this process
+// (POST /api/antigravity/policy, loopback only) with its home's token; the token names the brain or
+// run that registered a checker here, and the checker answers:
+//   { decision: 'deny', reason }   refused: the model reads the reason ("tool call denied by pre-tool
+//                                   hook: …") and its turn goes on
+//   { decision: 'ask' }             allowed by policy, approval by the usual permission request
+//                                   (session/request_permission: the brain's card, the run's broker)
+//   { decision: 'allow' }           allowed by policy, no approval needed
+// A token nobody registered (a run that ended, a restarted server) is refused: a home is never used
+// without the process that wrote it watching. A checker that throws refuses too (fail closed).
+
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { acpCall } from './tool-call.js';
+
+export const POLICY_TOKEN_RE = /^agp_[A-Za-z0-9_-]{32,64}$/;
+const DECISIONS = new Set(['deny', 'ask', 'allow']);
+const MAX_REASON = 2000;
+
+function sameToken(a, b) {
+  const x = Buffer.from(String(a || ''));
+  const y = Buffer.from(String(b || ''));
+  return x.length === y.length && timingSafeEqual(x, y);
+}
+
+/** A checker's answer as the hook prints it ({ decision, reason? }); anything else is a refusal. */
+export function normalizePolicyAnswer(answer) {
+  const decision = DECISIONS.has(answer?.decision) ? answer.decision : 'deny';
+  if (decision !== 'deny') return { decision };
+  const reason = String(answer?.reason || 'SynaBun refused this call.').replace(/\s+/g, ' ').trim().slice(0, MAX_REASON);
+  return { decision, reason };
+}
+
+export function createAntigravityPolicyRegistry({ log = () => {} } = {}) {
+  const entries = new Map(); // token → { check, label }
+
+  /** Register a checker ((call, payload) → answer | Promise<answer>) → { token, dispose() }. */
+  function register(check, { label = 'antigravity' } = {}) {
+    if (typeof check !== 'function') throw new Error('An Antigravity policy needs a checker');
+    const token = `agp_${randomBytes(32).toString('base64url')}`;
+    entries.set(token, { check, label });
+    return { token, dispose: () => { entries.delete(token); } };
+  }
+
+  /** The answer for one hook payload ({ toolCall: { name, args }, conversationId, … }) under `token`. */
+  async function decide(token, payload = {}) {
+    const raw = String(token || '');
+    let entry = null;
+    if (POLICY_TOKEN_RE.test(raw)) {
+      for (const [known, value] of entries) if (sameToken(known, raw)) { entry = value; break; }
+    }
+    if (!entry) return { decision: 'deny', reason: 'SynaBun no longer runs this Antigravity session (its run ended or the server restarted), so nothing it does is allowed. End the turn.' };
+    const toolCall = payload?.toolCall;
+    if (!toolCall || typeof toolCall !== 'object' || Array.isArray(toolCall) || typeof toolCall.name !== 'string' || !toolCall.name.trim()) {
+      return { decision: 'deny', reason: 'SynaBun received no valid tool call, so it is refused.' };
+    }
+    try {
+      const call = acpCall(payload);
+      return normalizePolicyAnswer(await entry.check(call, payload));
+    } catch (error) {
+      log(`antigravity policy ${entry.label}: ${error?.message || error}`);
+      return { decision: 'deny', reason: `SynaBun could not check this call (${String(error?.message || error).slice(0, 200)}), so it is refused.` };
+    }
+  }
+
+  return { register, decide, get size() { return entries.size; } };
+}
+
+/** The one registry of this process (server.js mounts its route; brains and runs register here). */
+export const defaultAntigravityPolicy = createAntigravityPolicyRegistry();

package/neural-interface/lib/antigravity/tool-call.js

@@ -0,0 +1,178 @@
+// ═══════════════════════════════════════════
+// SynaBun — what an Antigravity tool call is, read one way everywhere
+// ═══════════════════════════════════════════
+//
+// Antigravity describes a tool call in two shapes: an ACP tool call (session/update tool_call,
+// session/request_permission: { toolCallId, name, kind, title, locations, rawInput }) and the
+// payload of a PreToolUse hook ({ toolCall: { name, args } }, no kind). Both name the tool by
+// Antigravity's own word (read_file, run_command, write_to_file, call_mcp_tool …); an MCP call
+// names its server and tool in its arguments ({ ServerName, ToolName, Arguments }), a command
+// its line in CommandLine. Measured on agy 1.4.12 (docs/antigravity-sidepanel.md → Assistant).
+//
+//   acpCall(value)        either shape → { id, name, kind, title, args, locations, mcp, command }
+//   acpToolName(call)     the name SynaBun's policies read: mcp__<server>__<tool> for an MCP call
+//   acpUiToolName(call)   the name the Assistant panel shows: <server>_<tool> (SynaBun_agent_route) for MCP
+//   acpToolKind(call)     ACP kind, from the call or from the tool's name when the hook payload has none
+//   acpWebTool(call)      Antigravity's own web search, URL reading or browser (the browser policy refuses it)
+//   acpToolPaths(call)    every path the call names
+//
+// Pure: no I/O.
+
+export const ACP_MCP_TOOL = 'call_mcp_tool';
+
+// Antigravity's own tools, by what they do (the names its agent and its hooks use).
+const READ_TOOLS = new Set([
+  'read_file', 'view_file', 'view_file_outline', 'view_code_item', 'view_content_chunk', 'list_dir', 'list_directory',
+  'grep_search', 'find_by_name', 'find', 'codebase_search', 'code_search', 'read_resource', 'list_resources',
+  'read_terminal', 'command_status', 'read_notebook', 'trajectory_search', 'internal_search', 'retrieve_memory',
+  'find_all_references',
+]);
+const EDIT_TOOLS = new Set([
+  'write_to_file', 'write_file', 'create_file', 'replace_file_content', 'multi_replace_file_content', 'edit_file',
+  'apply_patch', 'propose_code', 'file_change', 'edit_notebook', 'write_blob',
+]);
+const DELETE_TOOLS = new Set(['delete_file', 'delete_directory']);
+const MOVE_TOOLS = new Set(['move_file', 'move', 'rename_file']);
+const EXECUTE_TOOLS = new Set(['run_command', 'shell_exec', 'send_command_input', 'execute_notebook', 'run_extension_code']);
+// Antigravity's own web: search, URL reading, its browser and browser subagent.
+const WEB_TOOLS = new Set([
+  'search_web', 'read_url_content', 'execute_url', 'open_browser_url', 'read_browser_page', 'browser_subagent', 'list_browser_pages',
+  'capture_browser_screenshot', 'capture_browser_console_logs', 'execute_browser_javascript', 'click_browser_pixel',
+]);
+const THINK_TOOLS = new Set(['task_boundary', 'notify_user', 'ask_question', 'suggested_responses', 'checkpoint']);
+
+const PATH_KEYS = ['path', 'Path', 'file_path', 'filePath', 'filepath', 'AbsolutePath', 'TargetFile', 'DirectoryPath', 'SearchPath', 'SearchDirectory', 'target', 'dest', 'destination', 'Destination', 'newPath', 'new_path', 'source', 'Source', 'from', 'to', 'oldPath', 'old_path'];
+const COMMAND_KEYS = ['CommandLine', 'command', 'cmd'];
+
+const asObject = (value) => (value && typeof value === 'object' && !Array.isArray(value) ? value : {});
+const text = (value) => (typeof value === 'string' ? value : '');
+
+/** The MCP server, tool and arguments of an Antigravity MCP call, else null. */
+export function acpMcpTarget(nameOrCall, rawArgs) {
+  const name = typeof nameOrCall === 'string' ? nameOrCall : text(nameOrCall?.name);
+  const args = asObject(typeof nameOrCall === 'string' ? rawArgs : (nameOrCall?.rawInput ?? nameOrCall?.args));
+  const server = text(args.ServerName || args.serverName || args.server).trim();
+  const tool = text(args.ToolName || args.toolName || args.tool).trim();
+  if (name !== ACP_MCP_TOOL && !(server && tool && /mcp/i.test(name || text(nameOrCall?.title)))) return null;
+  if (!server || !tool) return null;
+  let inner = args.Arguments ?? args.arguments ?? {};
+  if (typeof inner === 'string') inner = JSON.parse(inner);
+  if (!inner || typeof inner !== 'object' || Array.isArray(inner)) throw new Error('MCP arguments must be an object');
+  return { server, tool, args: inner };
+}
+
+/**
+ * Either shape as one: { id, name, kind, title, args, locations, mcp, command }. `name` is Antigravity's own
+ * word for the tool ('' when the call names none: an older agy, a stand-in), `kind` the ACP kind (from the
+ * name when the shape has none), `mcp` the MCP target ({ server, tool, args }) or null.
+ */
+export function acpCall(value) {
+  const source = asObject(value);
+  const inner = source.toolCall && typeof source.toolCall === 'object' ? source.toolCall : source;
+  const args = asObject(inner.rawInput ?? inner.args ?? inner.input);
+  const name = text(inner.name).trim();
+  const mcp = acpMcpTarget(name || text(inner.title), args) || (name ? null : acpMcpTarget({ name: ACP_MCP_TOOL, rawInput: args }));
+  const call = {
+    id: text(inner.toolCallId) || null,
+    name,
+    kind: '',
+    title: text(inner.title),
+    args,
+    locations: Array.isArray(inner.locations) ? inner.locations : [],
+    mcp,
+    command: '',
+  };
+  call.kind = acpToolKind({ ...call, kind: text(inner.kind) });
+  for (const key of COMMAND_KEYS) {
+    const v = args[key];
+    if (typeof v === 'string' && v.trim()) { call.command = v; break; }
+    if (Array.isArray(v) && v.length) { call.command = v.map(String).join(' '); break; }
+  }
+  return call;
+}
+
+/** The ACP kind of a call: its own when it has one (and it is not an MCP call), else read from its name. */
+export function acpToolKind(call) {
+  const named = text(call?.name).toLowerCase();
+  if (call?.mcp || named === ACP_MCP_TOOL) return 'mcp';
+  const own = text(call?.kind).toLowerCase();
+  if (own && own !== 'other') return own;
+  if (READ_TOOLS.has(named)) return named.includes('search') || named.startsWith('find') ? 'search' : 'read';
+  if (EDIT_TOOLS.has(named)) return 'edit';
+  if (DELETE_TOOLS.has(named)) return 'delete';
+  if (MOVE_TOOLS.has(named)) return 'move';
+  if (EXECUTE_TOOLS.has(named)) return 'execute';
+  if (WEB_TOOLS.has(named) || /^browser_/.test(named)) return 'fetch';
+  if (THINK_TOOLS.has(named)) return 'think';
+  return own || 'other';
+}
+
+/** The name SynaBun's policies read: mcp__<server>__<tool> for an MCP call (the Claude spelling), else Antigravity's word. */
+export function acpToolName(value) {
+  const call = value?.args && 'mcp' in value ? value : acpCall(value);
+  if (call.mcp) return `mcp__${call.mcp.server}__${call.mcp.tool}`;
+  return call.name || call.title || call.kind || 'tool';
+}
+
+/** The name the Assistant panel shows: <server>_<tool> for an MCP call (SynaBun_agent_route, as OpenCode's), else Antigravity's word. */
+export function acpUiToolName(value) {
+  const call = value?.args && 'mcp' in value ? value : acpCall(value);
+  if (call.mcp) return `${call.mcp.server}_${call.mcp.tool}`;
+  return call.name || call.kind || 'tool';
+}
+
+/** Whether this is Antigravity's own web search, URL reading or browser (never SynaBun's browser tools). */
+export function acpWebTool(value) {
+  const call = value?.args && 'mcp' in value ? value : acpCall(value);
+  if (call.mcp) return false;
+  const named = call.name.toLowerCase();
+  return WEB_TOOLS.has(named) || /^browser_/.test(named) || (!named && call.kind === 'fetch');
+}
+
+/** Every path the call names, including nested path-like values in an MCP call's arguments. */
+export function acpToolPaths(value) {
+  const call = value?.args && 'mcp' in value ? value : acpCall(value);
+  const out = [];
+  for (const location of call.locations) if (typeof location?.path === 'string' && location.path) out.push(location.path);
+  if (call.mcp) {
+    let nodes = 0;
+    const visit = (value, key = '', depth = 0) => {
+      if (++nodes > 10000 || depth > 32) throw new Error('MCP arguments exceed the path inspection limit');
+      if (typeof value === 'string') {
+        if (PATH_KEYS.includes(key) || /[\\/]|^(?:[~.]|\$\{?HOME\}?)/.test(value.trim())) out.push(value.trim());
+      } else if (Array.isArray(value)) {
+        for (const item of value) visit(item, key, depth + 1);
+      } else if (value && typeof value === 'object') {
+        for (const [childKey, child] of Object.entries(value)) visit(child, childKey, depth + 1);
+      }
+    };
+    visit(call.mcp.args);
+  } else {
+    for (const key of PATH_KEYS) {
+      const v = call.args[key];
+      if (typeof v === 'string' && v) out.push(v);
+      else if (Array.isArray(v)) for (const item of v) if (typeof item === 'string' && item) out.push(item);
+    }
+  }
+  return [...new Set(out)];
+}
+
+/** Whether a call only reads (Antigravity's read and search tools), for plan mode and the read-only level. */
+export function acpReadOnlyKind(kind) {
+  return kind === 'read' || kind === 'search' || kind === 'think';
+}
+
+/**
+ * The call as the arguments a host-agnostic policy reads: an MCP call's own arguments, a command as `command`
+ * (and its working folder as `cwd`), paths as `file_path`; the rest as Antigravity sent them.
+ */
+export function acpPolicyInput(value) {
+  const call = value?.args && 'mcp' in value ? value : acpCall(value);
+  if (call.mcp) return { ...call.mcp.args };
+  const out = { ...call.args };
+  if (call.command && typeof out.command !== 'string') out.command = call.command;
+  if (typeof call.args.Cwd === 'string' && call.args.Cwd && typeof out.cwd !== 'string') out.cwd = call.args.Cwd;
+  const paths = acpToolPaths(call);
+  if (paths.length && typeof out.file_path !== 'string') out.file_path = paths[0];
+  return out;
+}

package/neural-interface/lib/antigravity/transcripts.js

@@ -0,0 +1,252 @@
+// ═══════════════════════════════════════════
+// SynaBun — Antigravity's conversations, read where agy keeps them (never written)
+// ═══════════════════════════════════════════
+//
+// agy (1.4.x) keeps each conversation under <gemini dir>/antigravity-cli/:
+//   brain/<conversation id>/.system_generated/logs/transcript.jsonl
+//       one JSON line per step, appended as the steps happen: { step_index, source, type, status, created_at,
+//       content, thinking?, tool_calls?, input_tokens?, output_tokens? }. A person's message is USER_EXPLICIT /
+//       USER_INPUT, its words inside <USER_REQUEST> (agy adds <ADDITIONAL_METADATA> and <USER_SETTINGS_CHANGE>
+//       blocks around them); the model's answer is MODEL / PLANNER_RESPONSE (`content`; `thinking` is its
+//       reasoning and is never read; `tool_calls` [{ name, args }]); a tool's output is MODEL / GENERIC; SYSTEM /
+//       SYSTEM_MESSAGE is agy's own.
+//   conversation_summaries.db
+//       SQLite, one row per conversation: its title, its folders (`workspace_uris`, a JSON list of file: URIs, the
+//       first being where it runs), when it changed, and its parent when it is a subagent's.
+//   conversations/<id>.db  the steps again, as protobuf (no schema: never read).
+// Measured on agy 1.4.12 (docs/antigravity-sidepanel.md → Conversations in SynaBun).
+//
+// The index is opened read-only with SQLite's immutable flag: nothing is created beside it (no -wal or -shm), and a
+// change agy has not checkpointed yet is simply not seen until it has. A conversation the index does not name yet
+// has no folder: memory keeps it without a project, and Resume shows it once the index names it.
+//
+// Where: the user's own gemini dir (~/.gemini: the side panel's and a terminal agy's; Resume lists these and the
+// panel can load them again) and every SynaBun home (lib/antigravity/home.js: an Assistant brain's or a dispatched
+// run's; kept for memory only, since only the gemini dir that holds a conversation can load it). A folder or a
+// transcript that is a link is never followed, and a transcript is read only up to MAX_TRANSCRIPT_BYTES.
+
+import { closeSync, fstatSync, lstatSync, openSync, readdirSync, readSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { DatabaseSync } from 'node:sqlite';
+import { stripGreetingNote } from '../../public/shared/agy/agy-greeting.js';
+
+/** agy's own folder inside a gemini dir (`--gemini-dir <dir>` keeps it there too). */
+export const AGY_DATA_DIR = 'antigravity-cli';
+/** A transcript bigger than this is read up to here (its first steps; the rest is left out). */
+export const MAX_TRANSCRIPT_BYTES = 50 * 1024 * 1024;
+/** What a conversation id may look like (agy's are UUIDs); anything else in brain/ is not a conversation. */
+export const CONVERSATION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{5,127}$/;
+/** The SynaBun homes that hold conversations of their own (a model-list home holds none worth keeping). */
+const HOME_RE = /^(?:brain|run)-[A-Za-z0-9_-]+$/;
+
+/** The transcript of a conversation in a gemini dir. */
+export function transcriptPath(geminiDir, sessionId) {
+  return join(geminiDir, AGY_DATA_DIR, 'brain', sessionId, '.system_generated', 'logs', 'transcript.jsonl');
+}
+
+const isDir = (path) => { try { const stat = lstatSync(path); return stat.isDirectory() && !stat.isSymbolicLink(); } catch { return false; } };
+
+/**
+ * The gemini dirs whose conversations SynaBun reads: the user's (`kind: 'user'`), then each SynaBun home under
+ * `homesRoot` (`kind: 'synabun'`). A missing folder is simply not there.
+ */
+export function antigravityStores({ home = homedir(), homesRoot = null } = {}) {
+  const stores = [];
+  const user = join(home, '.gemini');
+  if (isDir(join(user, AGY_DATA_DIR))) stores.push({ dir: user, kind: 'user' });
+  if (homesRoot && isDir(homesRoot)) {
+    let names = [];
+    try { names = readdirSync(homesRoot).sort(); } catch { names = []; }
+    for (const name of names) {
+      const dir = join(homesRoot, name);
+      // A home is SynaBun's own folder: one that is a link (to anywhere) is not one.
+      if (HOME_RE.test(name) && isDir(dir) && isDir(join(dir, AGY_DATA_DIR))) stores.push({ dir, kind: 'synabun' });
+    }
+  }
+  return stores;
+}
+
+/** A folder from a file: URI (agy's workspace_uris), or null. */
+export function folderOfUri(uri) {
+  try {
+    const url = new URL(String(uri || ''));
+    if (url.protocol !== 'file:') return null;
+    const path = fileURLToPath(url);
+    return path || null;
+  } catch { return null; }
+}
+
+/** agy's time ("2026-10-31 07:08:50.511446+00:00", the zero time for none) as ISO, or null. */
+export function indexTime(value) {
+  const text = String(value || '').trim();
+  if (!text || text.startsWith('0001-01-01')) return null;
+  const at = Date.parse(text.replace(' ', 'T').replace(/(\.\d{3})\d+/, '$1'));
+  return Number.isFinite(at) ? new Date(at).toISOString() : null;
+}
+
+/**
+ * conversation_summaries.db of one agy folder, as `Map(id → { title, cwd, folders, updatedAt, parentId, steps })`.
+ * Empty when there is none or it cannot be read (a title and a folder are extras: the transcript is the record).
+ */
+export function readAntigravityIndex(dataDir, { Database = DatabaseSync } = {}) {
+  const index = new Map();
+  const file = join(dataDir, 'conversation_summaries.db');
+  try { const stat = lstatSync(file); if (!stat.isFile() || stat.isSymbolicLink()) return index; } catch { return index; }
+  let db = null;
+  try {
+    db = new Database(`${pathToFileURL(file).href}?immutable=1`, { readOnly: true });
+    const rows = db.prepare(`SELECT conversation_id, title, workspace_uris, last_modified_time, parent_conversation_id, step_count
+      FROM conversation_summaries`).all();
+    for (const row of rows) {
+      const id = String(row.conversation_id || '');
+      if (!CONVERSATION_ID_RE.test(id)) continue;
+      let uris = [];
+      try { const parsed = JSON.parse(String(row.workspace_uris || '[]')); if (Array.isArray(parsed)) uris = parsed; } catch { uris = []; }
+      const folders = uris.map(folderOfUri).filter(Boolean);
+      index.set(id, {
+        title: String(row.title || '').trim(),
+        cwd: folders[0] || null,
+        folders,
+        updatedAt: indexTime(row.last_modified_time),
+        parentId: String(row.parent_conversation_id || '') || null,
+        steps: Number(row.step_count) || 0,
+      });
+    }
+  } catch { /* an index being written, an older layout: no extras */ }
+  finally { try { db?.close(); } catch { /* closed */ } }
+  return index;
+}
+
+/**
+ * Every conversation with a transcript in these stores: `{ sessionId, store, geminiDir, transcript, size, mtimeMs,
+ * title, cwd, folders, updatedAt, parentId }`. A subagent's conversation (one with a parent) is its parent's work
+ * and is left out, as Claude Code's sidechains are.
+ */
+export function listAntigravityConversations(stores, { readIndex = readAntigravityIndex } = {}) {
+  const out = [];
+  const seen = new Set();
+  for (const store of Array.isArray(stores) ? stores : []) {
+    const dataDir = join(store.dir, AGY_DATA_DIR);
+    const brain = join(dataDir, 'brain');
+    if (!isDir(brain)) continue;
+    let ids = [];
+    try { ids = readdirSync(brain).filter((name) => CONVERSATION_ID_RE.test(name)); } catch { ids = []; }
+    if (!ids.length) continue;
+    const index = readIndex(dataDir);
+    for (const id of ids) {
+      if (seen.has(id) || !isDir(join(brain, id))) continue;
+      const meta = index.get(id) || null;
+      if (meta?.parentId) continue;
+      const transcript = transcriptPath(store.dir, id);
+      let stat;
+      try { stat = lstatSync(transcript); } catch { continue; }
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size <= 0) continue;
+      seen.add(id);
+      out.push({
+        sessionId: id, store: store.kind, geminiDir: store.dir, transcript, size: stat.size, mtimeMs: stat.mtimeMs,
+        title: meta?.title || '', cwd: meta?.cwd || null, folders: meta?.folders || [], updatedAt: meta?.updatedAt || null, parentId: null,
+      });
+    }
+  }
+  return out;
+}
+
+/** One conversation of the user's own store by id (the panel's and Resume's), or null. */
+export function findUserConversation(sessionId, { home = homedir(), readIndex = readAntigravityIndex } = {}) {
+  if (!CONVERSATION_ID_RE.test(String(sessionId || ''))) return null;
+  const stores = antigravityStores({ home }).filter((store) => store.kind === 'user');
+  const dir = stores[0]?.dir;
+  if (!dir) return null;
+  const transcript = transcriptPath(dir, sessionId);
+  let stat;
+  try { stat = lstatSync(transcript); } catch { return null; }
+  if (!stat.isFile() || stat.isSymbolicLink() || !isDir(join(dir, AGY_DATA_DIR, 'brain', sessionId))) return null;
+  const meta = readIndex(join(dir, AGY_DATA_DIR)).get(sessionId) || null;
+  return { sessionId, store: 'user', geminiDir: dir, transcript, size: stat.size, mtimeMs: stat.mtimeMs, title: meta?.title || '', cwd: meta?.cwd || null, folders: meta?.folders || [], updatedAt: meta?.updatedAt || null, parentId: meta?.parentId || null };
+}
+
+/**
+ * A transcript's text, read without following a link and up to `maxBytes` (a cut line at the end is left out by
+ * the parser). '' when it cannot be read.
+ */
+export function readTranscriptText(path, { maxBytes = MAX_TRANSCRIPT_BYTES } = {}) {
+  let fd = null;
+  try {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink()) return '';
+    fd = openSync(path, 'r');
+    const size = Math.min(fstatSync(fd).size, maxBytes);
+    const buffer = Buffer.alloc(size);
+    let read = 0;
+    while (read < size) {
+      const n = readSync(fd, buffer, read, size - read, read);
+      if (!n) break;
+      read += n;
+    }
+    return buffer.subarray(0, read).toString('utf8');
+  } catch { return ''; }
+  finally { if (fd !== null) { try { closeSync(fd); } catch { /* closed */ } } }
+}
+
+const META_BLOCKS = /<(ADDITIONAL_METADATA|USER_SETTINGS_CHANGE|EPHEMERAL_MESSAGE|SYSTEM_MESSAGE)>[\s\S]*?<\/\1>/g;
+
+/** What a person typed, out of agy's USER_INPUT `content` (its own blocks and SynaBun's greeting note left out). */
+export function antigravityUserWords(content) {
+  const text = String(content ?? '');
+  const request = /<USER_REQUEST>\r?\n?([\s\S]*?)\r?\n?<\/USER_REQUEST>/.exec(text);
+  const words = request ? request[1] : text.replace(META_BLOCKS, '');
+  return stripGreetingNote(words).trim();
+}
+
+/** One transcript line as a message: { role: 'user' | 'assistant' | 'tool_result', text, at, step, tools } or null. */
+export function antigravityStepMessage(record) {
+  if (!record || typeof record !== 'object') return null;
+  const at = typeof record.created_at === 'string' && Number.isFinite(Date.parse(record.created_at)) ? new Date(record.created_at).toISOString() : null;
+  const step = Number.isInteger(record.step_index) ? record.step_index : null;
+  if (record.type === 'USER_INPUT' && record.source === 'USER_EXPLICIT') {
+    const text = antigravityUserWords(record.content);
+    return text ? { role: 'user', text, at, step, tools: [] } : null;
+  }
+  if (record.type === 'PLANNER_RESPONSE' && record.source === 'MODEL') {
+    const tools = (Array.isArray(record.tool_calls) ? record.tool_calls : [])
+      .filter((call) => call && typeof call.name === 'string' && call.name)
+      .map((call) => ({ name: call.name, input: call.args ?? {} }));
+    const text = typeof record.content === 'string' ? record.content.trim() : '';
+    return text || tools.length ? { role: 'assistant', text, at, step, tools } : null;
+  }
+  if (record.type === 'GENERIC' && record.source === 'MODEL' && typeof record.content === 'string' && record.content.trim()) {
+    return { role: 'tool_result', text: record.content, at, step, tools: [], error: record.status === 'ERROR' };
+  }
+  return null;
+}
+
+/**
+ * A transcript's text as the conversation: `{ records, messages, firstPrompt, messageCount, created, modified }`.
+ * `records` are the parsed lines (for memory capture); `messages` the person's and the model's turns and the tool
+ * output, in order; `messageCount` counts the person's and the model's messages that say something.
+ */
+export function parseAntigravityTranscript(text) {
+  const records = [];
+  const messages = [];
+  for (const line of String(text || '').split('\n')) {
+    if (!line.trim()) continue;
+    let record;
+    try { record = JSON.parse(line); } catch { continue; }
+    if (!record || typeof record !== 'object' || Array.isArray(record)) continue;
+    records.push(record);
+    const message = antigravityStepMessage(record);
+    if (message) messages.push(message);
+  }
+  const said = messages.filter((m) => (m.role === 'user' || m.role === 'assistant') && m.text);
+  const times = messages.map((m) => m.at).filter(Boolean).sort();
+  return {
+    records,
+    messages,
+    firstPrompt: said.find((m) => m.role === 'user')?.text.replace(/\s+/g, ' ').slice(0, 200) || '',
+    messageCount: said.length,
+    created: times[0] || null,
+    modified: times[times.length - 1] || null,
+  };
+}

package/neural-interface/lib/antigravity/usage.js

@@ -0,0 +1,43 @@
+// ═══════════════════════════════════════════
+// SynaBun — Antigravity: one turn's tokens out of ACP's session totals
+// ═══════════════════════════════════════════
+//
+// ACP's `usage` block on a session/prompt answer counts the whole session
+// ("total input tokens across all turns"), so a turn's own tokens are the
+// difference from the previous answer. A counter that went down means the
+// agent started counting again (a new process, a reloaded session): that
+// answer is a turn of its own. The five-class reading of a block is
+// lib/assistant-usage.js antigravityUsageTokens.
+
+const FIELDS = Object.freeze(['inputTokens', 'outputTokens', 'thoughtTokens', 'cachedReadTokens', 'cachedWriteTokens', 'totalTokens']);
+const SNAKE = Object.freeze({ inputTokens: 'input_tokens', outputTokens: 'output_tokens', thoughtTokens: 'thought_tokens', cachedReadTokens: 'cached_read_tokens', cachedWriteTokens: 'cached_write_tokens', totalTokens: 'total_tokens' });
+
+function count(value) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? Math.trunc(n) : 0;
+}
+
+/** An ACP usage block in camelCase with every field a count (null when there is none). */
+export function normalizeAcpUsage(usage) {
+  if (!usage || typeof usage !== 'object') return null;
+  const out = {};
+  let any = false;
+  for (const key of FIELDS) {
+    const value = usage[key] ?? usage[SNAKE[key]];
+    if (value !== undefined && value !== null) any = true;
+    out[key] = count(value);
+  }
+  return any ? out : null;
+}
+
+/** The turn's own usage: `current` minus `previous` (both session totals), or `current` after a reset. */
+export function acpTurnUsage(current, previous) {
+  const now = normalizeAcpUsage(current);
+  if (!now) return null;
+  const before = normalizeAcpUsage(previous);
+  if (!before) return now;
+  if (FIELDS.some((key) => now[key] < before[key])) return now;
+  const out = {};
+  for (const key of FIELDS) out[key] = now[key] - before[key];
+  return out;
+}