@minhspark/codex-mcp-bridge 1.22.21 → 1.24.0

package/src/antigravity-cli.mjs

@@ -0,0 +1,248 @@
+import { spawn as spawnProcess } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function failure(message, code, deliveryState = "not-sent") {
+  return Object.assign(new Error(message), { code, deliveryState });
+}
+
+function directory(value) {
+  if (typeof value !== "string" || !path.isAbsolute(value)) throw new Error("Antigravity CLI cwd must be an absolute directory");
+  const resolved = fs.realpathSync.native(value);
+  if (!fs.statSync(resolved).isDirectory()) throw new Error("Antigravity CLI cwd must be a directory");
+  return resolved;
+}
+
+function positive(value, fallback, name) {
+  const result = value ?? fallback;
+  if (!Number.isSafeInteger(result) || result < 1) throw new Error(`${name} must be a positive integer`);
+  return result;
+}
+
+export function resolveAntigravityCliBinary({ binary, env = process.env, platform = process.platform } = {}) {
+  const selected = binary ?? env.ANTIGRAVITY_CLI_BIN;
+  const windows = platform === "win32";
+  const name = windows ? "agy.exe" : "agy";
+  const home = env.HOME ?? env.USERPROFILE ?? os.homedir();
+  const candidates = selected !== undefined ? [selected] : [
+    ...(windows ? [path.join(env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"), "agy", "bin", name)] : [path.join(home, ".local", "bin", name)]),
+    ...(env.PATH ?? env.Path ?? "").split(path.delimiter).filter((item) => path.isAbsolute(item)).map((item) => path.join(item, name)),
+  ];
+  if (selected !== undefined && (typeof selected !== "string" || !path.isAbsolute(selected))) throw new Error("Antigravity CLI binary must be an absolute executable path");
+  for (const candidate of candidates) {
+    try {
+      const resolved = fs.realpathSync.native(candidate);
+      if (!fs.statSync(resolved).isFile() || windows && !/\.exe$/i.test(resolved)) continue;
+      fs.accessSync(resolved, windows ? fs.constants.R_OK : fs.constants.X_OK);
+      return resolved;
+    } catch {}
+  }
+  throw new Error("Antigravity CLI executable was not found; set ANTIGRAVITY_CLI_BIN to its absolute path");
+}
+
+export class AntigravityCliSession {
+  constructor(options = {}) {
+    this.cwd = directory(options.cwd);
+    this.env = { ...(options.env ?? process.env) };
+    this.binary = resolveAntigravityCliBinary({ binary: options.binary, env: this.env });
+    this.spawn = options.spawn ?? spawnProcess;
+    this.requestedConversationId = options.conversationId ?? null;
+    if (this.requestedConversationId !== null && !UUID.test(this.requestedConversationId)) throw new Error("Invalid Antigravity conversation ID");
+    this.startupTimeoutMs = positive(options.startupTimeoutMs, 30000, "startupTimeoutMs");
+    this.turnTimeoutMs = positive(options.turnTimeoutMs, 600000, "turnTimeoutMs");
+    this.closeTimeoutMs = positive(options.closeTimeoutMs, 3000, "closeTimeoutMs");
+    this.maxFrameBytes = positive(options.maxFrameBytes, 2 * 1024 * 1024, "maxFrameBytes");
+    this.maxTurnBytes = positive(options.maxTurnBytes, 16 * 1024 * 1024, "maxTurnBytes");
+    this.status = "new";
+    this.conversationId = null;
+    this.permissionMode = null;
+    this.child = null;
+    this.pending = null;
+    this.awaitingResult = false;
+    this.lastResult = null;
+    this.lastError = null;
+    this.deliveryState = "not-sent";
+    this.turnBytes = 0;
+    this.buffer = "";
+    this.decoder = new StringDecoder("utf8");
+    this.exited = false;
+  }
+
+  read() {
+    return {
+      conversationId: this.conversationId,
+      cwd: this.cwd,
+      permissionMode: this.permissionMode,
+      pid: this.child?.pid ?? null,
+      status: this.status,
+      deliveryState: this.deliveryState,
+      result: this.lastResult ? structuredClone(this.lastResult) : null,
+      error: this.lastError ? { code: this.lastError.code, message: this.lastError.message } : null,
+    };
+  }
+
+  start() {
+    if (this.startPromise) return this.startPromise;
+    if (this.status !== "new") return Promise.reject(failure("Antigravity CLI session cannot be started", "SESSION_CLOSED"));
+    this.status = "starting";
+    this.startPromise = new Promise((resolve, reject) => {
+      this.startResolve = resolve;
+      this.startReject = reject;
+    });
+    this.startTimer = setTimeout(() => this.fail(failure("Antigravity CLI did not emit a valid init event before the deadline", "STARTUP_TIMEOUT")), this.startupTimeoutMs);
+    const args = ["--input-format", "stream-json", "--output-format", "stream-json"];
+    if (this.requestedConversationId) args.push("--conversation", this.requestedConversationId);
+    try {
+      this.child = this.spawn(this.binary, args, { cwd: this.cwd, env: this.env, shell: false, windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
+      this.child.on("error", () => this.fail(failure("Antigravity CLI process failed", "PROCESS_ERROR", this.pending ? "unknown" : this.deliveryState)));
+      this.child.stdin.on("error", () => this.fail(failure("Antigravity CLI input pipe failed", "STDIN_ERROR", this.pending ? "unknown" : this.deliveryState)));
+      this.child.stdout.on("error", () => this.fail(failure("Antigravity CLI output pipe failed", "STDOUT_ERROR", this.pending ? "unknown" : this.deliveryState)));
+      this.child.stderr.on("error", () => this.fail(failure("Antigravity CLI diagnostic pipe failed", "STDERR_ERROR", this.pending ? "unknown" : this.deliveryState)));
+      this.child.stderr.resume();
+      this.child.stdout.on("data", (chunk) => this.consume(chunk));
+      this.child.on("close", (code, signal) => {
+        this.exited = true;
+        this.exitCode = code;
+        this.exitSignal = signal;
+        if (this.status === "starting" || this.pending) this.fail(failure("Antigravity CLI exited before completing the operation", "PROCESS_EXIT", this.pending ? "unknown" : this.deliveryState));
+        else if (!["failed", "unknown"].includes(this.status)) this.status = "closed";
+        this.closeResolve?.();
+      });
+    } catch {
+      this.fail(failure("Antigravity CLI could not be launched", "SPAWN_FAILED"));
+    }
+    return this.startPromise;
+  }
+
+  consume(chunk) {
+    if (["failed", "closed"].includes(this.status)) return;
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    this.turnBytes += bytes.length;
+    if (this.turnBytes > this.maxTurnBytes) return this.fail(failure("Antigravity CLI output exceeds its per-turn limit", "OUTPUT_LIMIT", this.pending ? "unknown" : this.deliveryState));
+    this.buffer += this.decoder.write(bytes);
+    let newline;
+    while ((newline = this.buffer.indexOf("\n")) >= 0) {
+      const line = this.buffer.slice(0, newline).replace(/\r$/, "");
+      this.buffer = this.buffer.slice(newline + 1);
+      if (Buffer.byteLength(line) > this.maxFrameBytes) return this.fail(failure("Antigravity CLI frame exceeds its limit", "FRAME_LIMIT", this.pending ? "unknown" : this.deliveryState));
+      if (!line.trim()) continue;
+      try { this.event(JSON.parse(line)); }
+      catch (error) { return this.fail(failure(error.message === "Invalid Antigravity event" ? error.message : "Antigravity CLI emitted invalid protocol data", "INVALID_PROTOCOL", this.pending ? "unknown" : this.deliveryState)); }
+      if (["failed", "closed"].includes(this.status)) return;
+    }
+    if (Buffer.byteLength(this.buffer) > this.maxFrameBytes) this.fail(failure("Antigravity CLI frame exceeds its limit", "FRAME_LIMIT", this.pending ? "unknown" : this.deliveryState));
+  }
+
+  event(event) {
+    if (!event || typeof event !== "object" || Array.isArray(event) || typeof event.event !== "string") throw new Error("Invalid Antigravity event");
+    if (event.event === "init") {
+      if (this.status !== "starting" || !UUID.test(event.conversation_id ?? "")
+          || this.requestedConversationId && event.conversation_id.toLowerCase() !== this.requestedConversationId.toLowerCase()
+          || directory(event.init?.cwd) !== this.cwd
+          || typeof event.init?.permission_mode !== "string" || !event.init.permission_mode || event.init.permission_mode.length > 128) throw new Error("Invalid Antigravity event");
+      this.conversationId = event.conversation_id;
+      this.permissionMode = event.init.permission_mode;
+      this.status = "idle";
+      clearTimeout(this.startTimer);
+      this.startResolve(this.read());
+      this.startResolve = null;
+      this.startReject = null;
+      return;
+    }
+    if (!this.conversationId) throw new Error("Invalid Antigravity event");
+    if (event.event !== "result") return;
+    const result = event.result;
+    if (!this.awaitingResult || !result || result.conversation_id !== this.conversationId
+        || typeof result.status !== "string" || !/^[A-Z][A-Z_]{0,127}$/.test(result.status)
+        || typeof result.response !== "string" || result.error !== undefined && typeof result.error !== "string") throw new Error("Invalid Antigravity event");
+    this.lastResult = { conversation_id: result.conversation_id, status: result.status, response: result.response, ...(result.error === undefined ? {} : { error: result.error }) };
+    this.awaitingResult = false;
+    this.deliveryState = "completed";
+    if (this.pending) {
+      const pending = this.pending;
+      this.pending = null;
+      clearTimeout(pending.timer);
+      this.status = "idle";
+      pending.resolve(structuredClone(this.lastResult));
+    }
+  }
+
+  async send(prompt) {
+    if (typeof prompt !== "string" || !prompt.trim()) throw failure("Antigravity prompt must be non-empty text", "INVALID_PROMPT");
+    const frame = `${JSON.stringify({ event: "user", message: { content: prompt } })}\n`;
+    if (Buffer.byteLength(frame) > this.maxFrameBytes) throw failure("Antigravity prompt exceeds its frame limit", "PROMPT_LIMIT");
+    await this.start();
+    if (this.status !== "idle" || this.pending) throw failure("Antigravity CLI session is busy, closed, or has an uncertain delivery; inspect its receipt instead of resending", "SESSION_UNAVAILABLE", this.deliveryState);
+    if (directory(this.cwd) !== this.cwd) throw failure("Antigravity CLI working directory changed", "CWD_CHANGED");
+    this.status = "running";
+    this.awaitingResult = true;
+    this.deliveryState = "unknown";
+    this.turnBytes = 0;
+    this.lastResult = null;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        const pending = this.pending;
+        if (!pending) return;
+        this.pending = null;
+        this.status = "unknown";
+        this.lastError = failure("Antigravity CLI turn exceeded the observation deadline; it may still be running. Do not resend.", "TURN_TIMEOUT", "unknown");
+        pending.reject(this.lastError);
+      }, this.turnTimeoutMs);
+      this.pending = { resolve, reject, timer };
+      try {
+        this.child.stdin.write(frame, (error) => {
+          if (error) this.fail(failure("Antigravity CLI input write failed; delivery may have started", "STDIN_ERROR", "unknown"));
+        });
+      } catch {
+        this.fail(failure("Antigravity CLI input write failed; delivery may have started", "STDIN_ERROR", "unknown"));
+      }
+    });
+  }
+
+  fail(error) {
+    this.lastError = error;
+    this.deliveryState = error.deliveryState;
+    this.status = error.deliveryState === "unknown" ? "unknown" : "failed";
+    clearTimeout(this.startTimer);
+    this.startReject?.(error);
+    this.startResolve = null;
+    this.startReject = null;
+    if (this.pending) {
+      const pending = this.pending;
+      this.pending = null;
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    try { this.child?.kill(); } catch {}
+  }
+
+  close() {
+    if (this.closePromise) return this.closePromise;
+    this.closePromise = this.finishClose();
+    return this.closePromise;
+  }
+
+  async finishClose() {
+    if (!this.child || this.exited) {
+      this.status = "closed";
+      return this.read();
+    }
+    const closed = new Promise((resolve) => { this.closeResolve = resolve; });
+    try { this.child.stdin.end(); } catch {}
+    let timer;
+    await Promise.race([closed, new Promise((resolve) => { timer = setTimeout(resolve, this.closeTimeoutMs); })]);
+    clearTimeout(timer);
+    if (!this.exited) {
+      if (this.pending || this.status === "starting") this.fail(failure("Antigravity CLI session was closed before its operation completed", "SESSION_CLOSED", this.pending ? "unknown" : this.deliveryState));
+      else try { this.child.kill(); } catch {}
+      await Promise.race([closed, new Promise((resolve) => { timer = setTimeout(resolve, this.closeTimeoutMs); })]);
+      clearTimeout(timer);
+    }
+    this.status = this.exited ? "closed" : "closing";
+    return this.read();
+  }
+}

package/src/antigravity-deliveries.mjs

@@ -0,0 +1,93 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { ensureBridgeDirectory } from "./antigravity-ipc.mjs";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export class AntigravityDeliveries {
+  constructor(directory) {
+    this.directory = ensureBridgeDirectory(directory);
+    this.active = new Set();
+  }
+
+  file(requestId) {
+    if (!UUID.test(requestId)) throw new Error("requestId must be a UUID");
+    return path.join(this.directory, `${requestId}.json`);
+  }
+
+  read(requestId) {
+    const file = this.file(requestId);
+    let descriptor;
+    try { descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0)); }
+    catch (error) { if (error.code === "ENOENT") return null; throw error; }
+    let record;
+    try {
+      const stat = fs.lstatSync(file, { bigint: true });
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1n || stat.size > 4n * 1024n * 1024n) throw new Error("Invalid delivery record");
+      const opened = fs.fstatSync(descriptor, { bigint: true });
+      if (!opened.isFile() || opened.nlink !== 1n || opened.dev !== stat.dev || opened.ino !== stat.ino || opened.size !== stat.size || opened.mtimeNs !== stat.mtimeNs) throw new Error("Delivery record changed before reading");
+      const buffer = Buffer.alloc(Number(opened.size) + 1);
+      let bytes = 0;
+      while (bytes < buffer.length) {
+        const count = fs.readSync(descriptor, buffer, bytes, buffer.length - bytes, bytes);
+        if (!count) break;
+        bytes += count;
+      }
+      const after = fs.fstatSync(descriptor, { bigint: true });
+      if (bytes !== Number(opened.size) || after.size !== opened.size || after.mtimeNs !== opened.mtimeNs || after.ctimeNs !== opened.ctimeNs) throw new Error("Delivery record changed while reading");
+      record = JSON.parse(buffer.subarray(0, bytes).toString("utf8"));
+    } finally { fs.closeSync(descriptor); }
+    if (record.requestId !== requestId) throw new Error("Delivery identity mismatch");
+    if (record.status === "pending" && !this.active.has(requestId)) return { ...record, status: "unknown", reason: "This process cannot observe the original worker. Inspect the exact destination; do not resend." };
+    return record;
+  }
+
+  identify(requestId, conversationId) {
+    if (!UUID.test(conversationId) || !this.active.has(requestId)) throw new Error("Cannot bind inactive delivery");
+    const record = this.read(requestId);
+    record.conversationId = conversationId;
+    this.write(record);
+  }
+
+  write(record) {
+    const temporary = `${this.file(record.requestId)}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, JSON.stringify(record), { flag: "wx", mode: 0o600 });
+    fs.renameSync(temporary, this.file(record.requestId));
+  }
+
+  async dispatch(request, operation) {
+    const { requestId, ...identity } = request;
+    const digest = crypto.createHash("sha256").update(JSON.stringify(identity)).digest("hex");
+    const existing = this.read(requestId);
+    if (existing) {
+      if (existing.digest !== digest) throw new Error("requestId was already used for a different delivery");
+      return existing;
+    }
+    const record = { requestId, digest, status: "pending", cwd: request.cwd, sender: request.sender, conversationId: request.conversationId ?? null, surface: request.surface, createdAt: new Date().toISOString() };
+    try { fs.writeFileSync(this.file(requestId), JSON.stringify(record), { flag: "wx", mode: 0o600 }); }
+    catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      throw new Error("Delivery is owned by another process. Inspect requestId; do not resend.");
+    }
+    this.active.add(requestId);
+    void Promise.resolve().then(operation).then((result) => {
+      record.status = ["accepted", "sent_unconfirmed", "held", "refused"].includes(result?.status) ? result.status : result?.status && result.status !== "SUCCESS" ? "failed" : "completed";
+      record.result = result;
+      record.conversationId = result?.conversationId ?? result?.conversation_id ?? record.conversationId;
+    }, (error) => {
+      record.status = ["not_sent", "not-sent"].includes(error.deliveryState) ? "failed" : "unknown";
+      record.reason = error.message;
+      if (typeof error.msgId === "string" && UUID.test(error.msgId)) record.result = { msgId: error.msgId, completed: false };
+      if (error.accountContext) record.result = { ...record.result, accountContext: error.accountContext };
+    }).finally(() => {
+      record.finishedAt = new Date().toISOString();
+      try {
+        record.conversationId ??= this.read(requestId)?.conversationId;
+        this.write(record);
+      } catch (error) { process.stderr.write(`Could not persist Antigravity delivery outcome: ${error.code ?? "WRITE_FAILED"}\n`); }
+      this.active.delete(requestId);
+    });
+    return record;
+  }
+}

package/src/antigravity-desktop.mjs

@@ -0,0 +1,146 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execute = promisify(execFile);
+const SURFACES = { desktop: "antigravity", cli: "antigravity-cli" };
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+
+function failure(code, message) {
+  return Object.assign(new Error(message), { code, deliveryState: "not_sent" });
+}
+
+function nativeDiagnostic(error, env, args) {
+  const exitCode = Number.isInteger(error.code) ? String(error.code) : /^[A-Z_]{2,40}$/.test(error.code ?? "") ? error.code : "unknown";
+  let detail = "";
+  try {
+    const parsed = JSON.parse(error.stdout);
+    if (typeof parsed.error === "string") detail = parsed.error;
+  } catch {}
+  for (const value of [...Object.entries(env).filter(([key]) => /ANTIGRAVITY|TOKEN|SECRET|PASSWORD|AUTH|KEY/i.test(key)).map(([, value]) => value), ...args.slice(1)]) {
+    if (typeof value === "string" && value) detail = detail.split(value).join("[redacted]");
+  }
+  detail = detail.replace(/https?:\/\/[^\s"']+/gi, "[endpoint]").replace(/Bearer\s+\S+/gi, "Bearer [redacted]").replace(/[\r\n\x00-\x1f]/g, " ").slice(0, 400);
+  return `exit ${exitCode}${detail ? `: ${detail}` : ""}`;
+}
+
+function canonicalCwd(value) {
+  if (typeof value !== "string" || !path.isAbsolute(value)) throw failure("ANTIGRAVITY_CWD_INVALID", "An absolute existing workspace directory is required");
+  const resolved = fs.realpathSync.native(value);
+  if (!fs.statSync(resolved).isDirectory()) throw failure("ANTIGRAVITY_CWD_INVALID", "Workspace is not a directory");
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+function workspaceCwd(uris) {
+  if (typeof uris === "string") uris = JSON.parse(uris);
+  if (!Array.isArray(uris) || uris.length !== 1 || typeof uris[0] !== "string") throw failure("ANTIGRAVITY_WORKSPACE_AMBIGUOUS", "Conversation must have exactly one workspace");
+  const uri = new URL(uris[0]);
+  if (uri.protocol !== "file:" || uri.search || uri.hash) throw failure("ANTIGRAVITY_CWD_INVALID", "Conversation workspace must be a local file URI");
+  return canonicalCwd(fileURLToPath(uri));
+}
+
+export async function listAntigravityConversations({ home = os.homedir(), surface = "all", limit = 100 } = {}) {
+  if (surface !== "all" && !Object.hasOwn(SURFACES, surface)) throw failure("ANTIGRAVITY_SURFACE_INVALID", "Surface must be desktop, cli, or all");
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000) throw new Error("Conversation limit must be between 1 and 1000");
+  const { DatabaseSync } = await import("node:sqlite");
+  const rows = [];
+  for (const [kind, directory] of Object.entries(SURFACES)) {
+    if (surface !== "all" && surface !== kind) continue;
+    const filename = path.join(home, ".gemini", directory, "conversation_summaries.db");
+    if (!fs.existsSync(filename)) continue;
+    const db = new DatabaseSync(filename, { readOnly: true });
+    try {
+      const records = db.prepare("SELECT conversation_id, title, workspace_uris, project_id, status, not_fully_idle, killed, app_data_dir, source FROM conversation_summaries WHERE app_data_dir = ? ORDER BY last_modified_time DESC LIMIT ?").all(directory, limit);
+      for (const row of records) {
+        if (!UUID.test(row.conversation_id) || row.killed) continue;
+        if (kind === "desktop" && ["CORTEX_TRAJECTORY_SOURCE_CLI", "CORTEX_TRAJECTORY_SOURCE_VSCODE", "CORTEX_TRAJECTORY_SOURCE_VISUAL_STUDIO", "CORTEX_TRAJECTORY_SOURCE_SDK", "CORTEX_TRAJECTORY_SOURCE_PYTHON_SDK"].includes(row.source)) continue;
+        let cwd;
+        try { cwd = workspaceCwd(row.workspace_uris); } catch { continue; }
+        rows.push({ conversationId: row.conversation_id, cwd, projectId: row.project_id, title: row.title, status: row.not_fully_idle ? "busy" : row.status || "unknown", surface: kind });
+      }
+    } finally { db.close(); }
+  }
+  return rows;
+}
+
+function nativeMetadata(result) {
+  return result.metadata ?? result.response?.conversationMetadata?.metadata ?? result.response?.conversation_metadata?.metadata ?? result.payload?.conversationMetadata?.metadata ?? result.payload?.conversation_metadata?.metadata ?? result.conversationMetadata?.metadata ?? result.conversation_metadata?.metadata;
+}
+
+function metadataShape(result) {
+  const rows = [];
+  const visit = (value, prefix, depth) => {
+    if (!value || typeof value !== "object" || Array.isArray(value) || depth > 3) return;
+    for (const key of Object.keys(value).slice(0, 20)) {
+      if (!/^[a-zA-Z_][a-zA-Z0-9_]{0,63}$/.test(key)) continue;
+      const field = prefix ? `${prefix}.${key}` : key;
+      rows.push(field);
+      visit(value[key], field, depth + 1);
+    }
+  };
+  visit(result, "", 0);
+  return rows.join(", ").slice(0, 800);
+}
+
+export function sanitizeAntigravityMetadata(result, conversationId) {
+  const metadata = nativeMetadata(result);
+  if (!metadata || typeof metadata !== "object") throw failure("ANTIGRAVITY_METADATA_UNSUPPORTED", `Native Antigravity metadata is missing or unsupported (fields: ${metadataShape(result)})`);
+  const returnedId = result.conversationId ?? result.conversation_id ?? result.response?.conversationId ?? result.response?.conversation_id ?? metadata.conversationId ?? metadata.conversation_id;
+  if (returnedId !== undefined && returnedId !== conversationId) throw failure("ANTIGRAVITY_METADATA_MISMATCH", "Native metadata identifies a different conversation");
+  return {
+    conversationId,
+    cwd: workspaceCwd(metadata.workspaceUris ?? metadata.workspace_uris),
+    projectId: metadata.projectId ?? metadata.project_id ?? "",
+    surface: "desktop",
+  };
+}
+
+export async function runAgentApi(options) {
+  try { return await executeAgentApi(options); } catch (error) {
+    error.deliveryState ??= "not_sent";
+    throw error;
+  }
+}
+
+async function executeAgentApi({ command, conversationId, prompt, expectedCwd, home = os.homedir(), env = process.env, executable = env.ANTIGRAVITY_AGENTAPI_EXE, run = execute, list = listAntigravityConversations }) {
+  if (!UUID.test(conversationId)) throw failure("ANTIGRAVITY_ID_INVALID", "An exact conversation UUID is required");
+  if (!["metadata", "send"].includes(command)) throw new Error("Unsupported Antigravity agentapi command");
+  if (!env.ANTIGRAVITY_LS_ADDRESS || !env.ANTIGRAVITY_CSRF_TOKEN) throw failure("ANTIGRAVITY_SIDECAR_REQUIRED", "Antigravity must launch the bridge sidecar before native requests are available");
+  if (executable && (!path.isAbsolute(executable) || /\.(bat|cmd|ps1)$/i.test(executable))) throw failure("ANTIGRAVITY_EXECUTABLE_INVALID", "Antigravity agentapi executable must be an absolute native executable path");
+  if (!executable && process.platform === "win32") throw failure("ANTIGRAVITY_EXECUTABLE_MISSING", "The Antigravity sidecar must provide ANTIGRAVITY_AGENTAPI_EXE on Windows");
+  const invoke = async (args) => {
+    let output;
+    try {
+      output = await run(executable || "agentapi", executable ? ["agentapi", ...args] : args, { env, encoding: "utf8", timeout: 30000, maxBuffer: 1048576, windowsHide: true, shell: false });
+    } catch (error) {
+      const nativeError = failure(error.killed || error.code === "ETIMEDOUT" ? "ANTIGRAVITY_OUTCOME_UNKNOWN" : "ANTIGRAVITY_NATIVE_FAILED", `Native Antigravity request failed (${nativeDiagnostic(error, env, args)}); inspect the original conversation before resending`);
+      nativeError.deliveryState = args[0] === "send-message" ? "unknown" : "not_sent";
+      throw nativeError;
+    }
+    let result;
+    try { result = JSON.parse(output.stdout); } catch { throw Object.assign(failure("ANTIGRAVITY_RESPONSE_INVALID", "Native Antigravity returned invalid JSON; do not automatically resend"), { deliveryState: args[0] === "send-message" ? "unknown" : "not_sent" }); }
+    if (!result || typeof result !== "object" || Array.isArray(result) || result.error || result.success === false) throw Object.assign(failure("ANTIGRAVITY_NATIVE_REJECTED", "Native Antigravity rejected the request"), { deliveryState: args[0] === "send-message" ? "unknown" : "not_sent" });
+    return result;
+  };
+  if (command === "metadata") return invoke(["get-conversation-metadata", conversationId]);
+  if (typeof prompt !== "string" || !prompt.trim() || prompt.length > 32768 || prompt.includes("\0")) throw new Error("Prompt must contain between 1 and 32768 characters without NUL");
+  const cwd = canonicalCwd(expectedCwd);
+  const select = async () => {
+    const records = (await list({ home, surface: "desktop", limit: 1000 })).filter((row) => row.conversationId === conversationId);
+    if (records.length !== 1) throw failure("ANTIGRAVITY_RECIPIENT_MISSING", "Exact desktop conversation is unavailable or has an ambiguous workspace");
+    const row = records[0];
+    if (row.surface !== "desktop" || canonicalCwd(row.cwd) !== cwd) throw failure("ANTIGRAVITY_WORKSPACE_MISMATCH", "Conversation workspace does not match the authorized workspace");
+    if (row.status !== "CASCADE_RUN_STATUS_IDLE") throw failure("ANTIGRAVITY_RECIPIENT_BUSY", "Conversation is busy or its idle state cannot be verified");
+    return row;
+  };
+  const before = await select();
+  const metadata = sanitizeAntigravityMetadata(await invoke(["get-conversation-metadata", conversationId]), conversationId);
+  if (metadata.cwd !== cwd || metadata.projectId !== before.projectId) throw failure("ANTIGRAVITY_METADATA_MISMATCH", "Native metadata does not match the selected conversation workspace and project");
+  const current = await select();
+  if (current.projectId !== before.projectId) throw failure("ANTIGRAVITY_METADATA_MISMATCH", "Conversation project changed during delivery preflight");
+  await invoke(["send-message", conversationId, prompt]);
+  return { conversationId, status: "accepted", completed: false, surface: "desktop" };
+}

package/src/antigravity-ipc.mjs

@@ -0,0 +1,141 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { protectCurrentUserPipe } from "./windows-pipe-acl.mjs";
+import { relayFileIdentity, removeRelayFile } from "./native-relay-files.mjs";
+
+const LIMIT = 2 * 1024 * 1024;
+
+async function socketRefused(socketPath) {
+  return new Promise((resolve) => {
+    const socket = net.createConnection(socketPath);
+    let settled = false;
+    const done = (refused) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      resolve(refused);
+    };
+    const timer = setTimeout(() => done(false), 1000);
+    socket.on("connect", () => done(false));
+    socket.on("error", (error) => done(error.code === "ECONNREFUSED"));
+  });
+}
+
+export function antigravityBridgeDirectory(home = os.homedir()) {
+  return path.join(home, ".codex", "antigravity-bridge");
+}
+
+export function antigravitySocket(directory = antigravityBridgeDirectory()) {
+  const hash = crypto.createHash("sha256").update(path.resolve(directory).toLowerCase()).digest("hex").slice(0, 24);
+  return process.platform === "win32" ? `\\\\.\\pipe\\LOCAL\\codex-bridge-antigravity-${hash}` : path.join(directory, "desktop.sock");
+}
+
+export function ensureBridgeDirectory(directory) {
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const stat = fs.lstatSync(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("Bridge directory must be a real directory");
+  if (typeof process.getuid === "function" && (stat.uid !== process.getuid() || (stat.mode & 0o077))) throw new Error("Bridge directory must be owned by this user with mode 0700");
+  return directory;
+}
+
+export function callAntigravityDesktop(request, { directory = antigravityBridgeDirectory(), timeoutMs = 30000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(antigravitySocket(directory));
+    let buffer = Buffer.alloc(0);
+    let finished = false;
+    let dispatched = false;
+    const done = (error, result) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      socket.destroy();
+      if (error) {
+        error.deliveryState ??= dispatched ? "unknown" : "not_sent";
+        reject(error);
+      } else resolve(result);
+    };
+    const timer = setTimeout(() => done(Object.assign(new Error("Antigravity sidecar did not reply; inspect the original requestId before retrying"), { deliveryState: "unknown" })), timeoutMs);
+    socket.on("error", (error) => done(error));
+    socket.on("end", () => done(new Error("Antigravity sidecar disconnected before replying")));
+    socket.on("connect", () => {
+      const frame = JSON.stringify(request) + "\n";
+      if (Buffer.byteLength(frame) > LIMIT) return done(new Error("Request exceeds size limit"));
+      dispatched = true;
+      socket.write(frame);
+    });
+    socket.on("data", (chunk) => {
+      buffer = Buffer.concat([buffer, chunk]);
+      if (buffer.length > LIMIT) return done(new Error("Sidecar response exceeds size limit"));
+      const end = buffer.indexOf(10);
+      if (end < 0) return;
+      try {
+        const response = JSON.parse(buffer.subarray(0, end).toString("utf8"));
+        if (response.error) return done(Object.assign(new Error(response.error), { deliveryState: response.deliveryState }));
+        done(null, response.result);
+      } catch (error) { done(error); }
+    });
+  });
+}
+
+export async function serveAntigravityDesktop(handler, { directory = antigravityBridgeDirectory() } = {}) {
+  ensureBridgeDirectory(directory);
+  const socketPath = antigravitySocket(directory);
+  let ready = false;
+  const connections = new Set();
+  const server = net.createServer((socket) => {
+    if (!ready || connections.size >= 32) return socket.destroy();
+    connections.add(socket);
+    socket.on("close", () => connections.delete(socket));
+    socket.on("error", () => {});
+    socket.setTimeout(35000, () => socket.destroy());
+    let buffer = Buffer.alloc(0);
+    let received = false;
+    socket.on("data", async (chunk) => {
+      if (received) return;
+      buffer = Buffer.concat([buffer, chunk]);
+      if (buffer.length > LIMIT) return socket.destroy();
+      const end = buffer.indexOf(10);
+      if (end < 0) return;
+      received = true;
+      try {
+        const result = await handler(JSON.parse(buffer.subarray(0, end).toString("utf8")));
+        const frame = JSON.stringify({ result }) + "\n";
+        if (Buffer.byteLength(frame) > LIMIT) throw new Error("Sidecar response exceeds size limit");
+        socket.end(frame);
+      } catch (error) { socket.end(JSON.stringify({ error: error.message, deliveryState: error.deliveryState }) + "\n"); }
+    });
+  });
+  const privatePath = process.platform === "win32" ? socketPath : path.join(directory, `.${crypto.randomBytes(6).toString("hex")}.sock`);
+  let identity;
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(privatePath, () => { server.off("error", reject); resolve(); });
+  });
+  try {
+    if (process.platform === "win32") await protectCurrentUserPipe(socketPath);
+    else {
+      fs.chmodSync(privatePath, 0o600);
+      try { fs.linkSync(privatePath, socketPath); }
+      catch (error) {
+        if (error.code !== "EEXIST") throw error;
+        const existing = relayFileIdentity(socketPath, "socket");
+        if (!await socketRefused(socketPath)) throw new Error("Another Antigravity sidecar owns the socket");
+        removeRelayFile(socketPath, { expected: existing });
+        fs.linkSync(privatePath, socketPath);
+      }
+      fs.unlinkSync(privatePath);
+      identity = relayFileIdentity(socketPath, "socket");
+    }
+    ready = true;
+  } catch (error) { server.close(); throw error; }
+  return { server, close: () => new Promise((resolve) => {
+    ready = false;
+    for (const socket of connections) socket.destroy();
+    if (identity) removeRelayFile(socketPath, { expected: identity });
+    server.close(resolve);
+  }) };
+}