@minhspark/codex-mcp-bridge 1.25.3 → 1.26.0

package/scripts/worker-relay.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { callBackgroundRelay } from "../src/background-relay-client.mjs";
+import { withBridgeDiagnostic } from "../src/recipient-preflight.mjs";
+import { relayFailure, RELAY_UUID } from "../src/background-relay-config.mjs";
+import { exitForVersionRequest } from "../src/cli-version.mjs";
+
+exitForVersionRequest(import.meta.url);
+const args = process.argv.slice(2);
+const action = args.shift() ?? "status";
+const option = name => { const index = args.indexOf(name); return index < 0 ? undefined : args[index + 1]; };
+try {
+  let result;
+  if (action === "status" || action === "list") result = await callBackgroundRelay(action);
+  else if (action === "read") result = await callBackgroundRelay("read", { requestId: option("--request-id"), waitSec: Number(option("--wait") ?? 0) }, { timeoutMs: (Number(option("--wait") ?? 0) + 10) * 1000 });
+  else if (action === "send") {
+    if (!args.includes("--stdin") || !RELAY_UUID.test(option("--request-id") ?? "")) throw relayFailure("WORKER_REQUEST_INVALID", "Use --stdin and a persistent --request-id UUID so uncertain deliveries can be inspected safely");
+    const chunks = [];
+    let bytes = 0;
+    for (;;) {
+      const buffer = Buffer.alloc(65536);
+      const count = fs.readSync(0, buffer, 0, buffer.length, null);
+      if (!count) break;
+      bytes += count;
+      if (bytes > 256 * 1024) throw relayFailure("WORKER_REQUEST_TOO_LARGE", "The authorized prompt exceeds the worker input limit");
+      chunks.push(buffer.subarray(0, count));
+    }
+    const prompt = Buffer.concat(chunks).toString("utf8");
+    result = await callBackgroundRelay("send", { agent: option("--agent"), cwd: option("--cwd"), requestId: option("--request-id"), prompt });
+  } else if (action === "--help" || action === "help") {
+    process.stdout.write("worker-relay status | list | send --agent <codex|claude|antigravity> --cwd <project> --request-id <uuid> --stdin | read --request-id <uuid> [--wait <0-60>]\n");
+  } else throw relayFailure("WORKER_COMMAND_INVALID", "Unknown worker relay command");
+  if (result) {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    if (result.status === "failed" || result.status === "unknown") process.exitCode = 1;
+  }
+} catch (error) {
+  const result = withBridgeDiagnostic({ isError: true, content: [] }, error, { component: "worker-relay-cli", operation: action, requestId: option("--request-id") });
+  process.stderr.write(result.content.map(item => item.text ?? "").join("\n") + "\n");
+  process.exitCode = 1;
+}

package/src/antigravity-bridge.mjs

@@ -15,6 +15,7 @@ import { exitForVersionRequest } from "./cli-version.mjs";
 import { NativeDesktopRelay, desktopTaskSocketPath, accountRelaySocketPath } from "./native-relay.mjs";
 import { requireBridgeAccounts, readBridgeAccounts, assertAccountIdentity } from "./bridge-account-context.mjs";
 import { bridgeDiagnostic, withBridgeDiagnostic, preflightFailure } from "./recipient-preflight.mjs";
+import { createReloadControl, exitWhenClientCloses } from "./reload-control.mjs";
 
 exitForVersionRequest(import.meta.url);
 
@@ -28,6 +29,19 @@ const caller = process.env.ANTIGRAVITY_BRIDGE_CALLER;
 const senderRelay = new NativeDesktopRelay({ socketPath: desktopTaskSocketPath(), accountSocketPath: accountRelaySocketPath() });
 const result = (value) => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
 const schema = { requestId: z.string().uuid(), cwd: z.string().min(1), prompt: z.string().min(1).max(65536) };
+const reloadReason = () => startingSessions ? "Antigravity CLI sessions are still starting"
+  : deliveries.active.size ? "Antigravity deliveries are still active"
+    : sessions.size ? "Open Antigravity CLI sessions retain process pipes and cannot migrate" : null;
+const reload = createReloadControl({
+  entry: "antigravity-bridge.mjs",
+  inspect: reloadReason,
+  exportState: () => ({ caller: caller ?? null, directory }),
+  restore: (state) => {
+    if (state.caller !== (caller ?? null) || typeof state.directory !== "string" || path.relative(state.directory, directory)) {
+      throw new Error("Antigravity caller or durable receipt directory changed during reload");
+    }
+  },
+});
 
 async function identifySender(extra) {
   if (caller === "codex") {
@@ -89,7 +103,7 @@ function register(name, description, inputSchema, readOnly, handler) {
   server.registerTool(name, { description, inputSchema, annotations: { readOnlyHint: readOnly, destructiveHint: !readOnly, idempotentHint: true, openWorldHint: !readOnly } }, async (args, extra) => {
     const options = { component: "antigravity-bridge", operation: name, requestId: args.requestId, conversationId: args.conversationId, readOnly };
     try {
-      const value = await handler(args, extra);
+      const value = await reload.run(() => handler(args, extra));
       const failure = antigravityDeliveryError(value);
       if (failure) return withBridgeDiagnostic({ ...result(value), isError: true }, failure, { ...options, readOnly: false, msgId: value.result?.msgId });
       if (value?.desktop?.available === false) return withBridgeDiagnostic({ ...result(value), isError: true }, { diagnostic: value.desktop.diagnostic }, options);
@@ -219,6 +233,7 @@ async function stop() {
   await stopProcessInspectors();
   await server.close();
 }
-for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => { void stop(); });
-process.stdin.once("end", () => { void stop(); });
 await server.connect(new StdioServerTransport());
+const shutdown = exitWhenClientCloses({ busy: () => startingSessions || deliveries.active.size ? "Antigravity deliveries are still active" : null, stop });
+for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => { void shutdown.close(signal); });
+reload.listen();

package/src/antigravity-cli.mjs

@@ -50,6 +50,8 @@ export class AntigravityCliSession {
     this.env = { ...(options.env ?? process.env) };
     this.binary = resolveAntigravityCliBinary({ binary: options.binary, env: this.env });
     this.spawn = options.spawn ?? spawnProcess;
+    this.onEvent = options.onEvent;
+    this.onStderr = options.onStderr;
     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");
@@ -102,7 +104,11 @@ export class AntigravityCliSession {
       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();
+      if (this.onStderr) this.child.stderr.on("data", (chunk) => {
+        try { this.onStderr(chunk); }
+        catch { this.fail(failure("Antigravity CLI diagnostic observer failed", "OBSERVER_ERROR", this.pending ? "unknown" : this.deliveryState)); }
+      });
+      else this.child.stderr.resume();
       this.child.stdout.on("data", (chunk) => this.consume(chunk));
       this.child.on("close", (code, signal) => {
         this.exited = true;
@@ -147,6 +153,7 @@ export class AntigravityCliSession {
       this.conversationId = event.conversation_id;
       this.permissionMode = event.init.permission_mode;
       this.status = "idle";
+      this.onEvent?.(structuredClone(event));
       clearTimeout(this.startTimer);
       this.startResolve(this.read());
       this.startResolve = null;
@@ -154,11 +161,15 @@ export class AntigravityCliSession {
       return;
     }
     if (!this.conversationId) throw new Error("Invalid Antigravity event");
-    if (event.event !== "result") return;
+    if (event.event !== "result") {
+      this.onEvent?.(structuredClone(event));
+      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.onEvent?.(structuredClone(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";

package/src/antigravity-outbound-bridge.mjs

@@ -12,16 +12,36 @@ import { antigravityBridgeDirectory } from "./antigravity-ipc.mjs";
 import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
 import { stopProcessInspectors } from "./claude-sender-context.mjs";
 import { exitForVersionRequest } from "./cli-version.mjs";
+import { BACKGROUND_WORKER_GUIDANCE, registerBackgroundTools } from "./background-relay-mcp.mjs";
 import { assertAccountIdentity } from "./bridge-account-context.mjs";
 import { bridgeDiagnostic, withBridgeDiagnostic, preflightFailure } from "./recipient-preflight.mjs";
+import { createReloadControl, exitWhenClientCloses } from "./reload-control.mjs";
 
 const { version } = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const result = (value) => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
 const targetSchema = { target: z.enum(["codex", "claude"]) };
 const taskSchema = { ...targetSchema, conversationId: z.string().uuid(), taskId: z.string().min(1).max(256).optional() };
 
-export function createAntigravityOutboundBridge({ resolveSender = resolveAntigravitySenderContext, targets = createAntigravityOutboundTargets(), deliveries = new AntigravityDeliveries(path.join(antigravityBridgeDirectory(), "outbound-deliveries")), rootPolicy = createHardenedRootPolicy() } = {}) {
-  const server = new McpServer({ name: "agent-bridge", version }, { instructions: "Send user-authorized work FROM the current Antigravity Desktop conversation to an exact existing Codex Desktop task or Claude Desktop Code session in the same project. Use list_agent_tasks first, verify title and identity, then send_to_agent_task with a fresh requestId. Keep requestId after uncertainty and read_agent_delivery; never automatically resend. Native permissions and sender identity are verified on every call. Do not launch a CLI substitute, impersonate Codex/Claude, or change permissions to overcome a rejection. Native acceptance is not task completion; read_agent_task for Codex or read_agent_delivery for a Claude reply. Independent new work requires a separate native conversation; this bridge only continues existing tasks. Never use Computer Use, open an old chat, or create an empty, new, or error chat to load or recover a relay. Report the structured diagnostic when a native relay or session is unavailable. Agent-authored handoffs must be in English and name Antigravity as the author." });
+export function createAntigravityOutboundBridge({ resolveSender = resolveAntigravitySenderContext, targets = createAntigravityOutboundTargets(), deliveries = new AntigravityDeliveries(path.join(antigravityBridgeDirectory(), "outbound-deliveries")), rootPolicy = createHardenedRootPolicy(), env = process.env, channel = process } = {}) {
+  const reload = createReloadControl({
+    entry: "antigravity-outbound-bridge.mjs", env, channel,
+    inspect: () => deliveries.active.size ? "Antigravity outbound deliveries are still active" : targets.reloadReason?.() ?? null,
+    quiesce: () => targets.quiesce(),
+    exportState: () => ({ directory: deliveries.directory, targets: targets.exportReloadState() }),
+    restore: (state) => {
+      if (typeof state.directory !== "string" || path.relative(state.directory, deliveries.directory)) throw new Error("Antigravity durable receipt directory changed during reload");
+      targets.restoreReloadState(state.targets);
+    },
+    activate: () => targets.activate(),
+  });
+  const server = new McpServer({ name: "agent-bridge", version }, { instructions: "Send user-authorized work FROM the current Antigravity Desktop conversation to an exact existing Codex Desktop task or Claude Desktop Code session in the same project. Use list_agent_tasks first, verify title and identity, then send_to_agent_task with a fresh requestId. Keep requestId after uncertainty and read_agent_delivery; never automatically resend. Native permissions and sender identity are verified on every call. Do not launch a CLI substitute for a native task, impersonate Codex/Claude, or change permissions to overcome a rejection. Native acceptance is not task completion; read_agent_task for Codex or read_agent_delivery for a Claude reply. Independent new native work requires a separate native conversation; native handoff tools only continue existing tasks. Never use Computer Use, open an old chat, or create an empty, new, or error chat to load or recover a relay. Report the structured diagnostic when a native relay or session is unavailable. Agent-authored handoffs must be in English and name Antigravity as the author. " + BACKGROUND_WORKER_GUIDANCE });
+
+  registerBackgroundTools((name, config, handler) => server.registerTool(name, config, async (args, extra) => {
+    try { return await reload.run(() => handler(args, extra)); }
+    catch (error) {
+      return withBridgeDiagnostic({ isError: true, content: [] }, error, { component: "agent-bridge", operation: name, requestId: args.requestId, readOnly: config.annotations?.readOnlyHint === true });
+    }
+  }), { env });
 
   function scope(expected, actual) {
     try {
@@ -64,7 +84,7 @@ export function createAntigravityOutboundBridge({ resolveSender = resolveAntigra
     server.registerTool(name, { description, inputSchema, annotations: { readOnlyHint: readOnly, destructiveHint: !readOnly, idempotentHint: true, openWorldHint: !readOnly } }, async (args, extra) => {
       const options = { component: "agent-bridge", operation: name, requestId: args.requestId, conversationId: args.conversationId, readOnly };
       try {
-        const value = await handler(args, extra);
+        const value = await reload.run(() => handler(args, extra));
         const failure = antigravityDeliveryError(value);
         if (failure) return withBridgeDiagnostic({ ...result(value), isError: true }, failure, { ...options, readOnly: false, msgId: value.result?.msgId });
         if (value?.diagnostic && (value.nativeReceipt === null || value.sender?.status !== "verified")) return withBridgeDiagnostic({ ...result(value), isError: true }, { diagnostic: value.diagnostic }, options);
@@ -123,7 +143,8 @@ export function createAntigravityOutboundBridge({ resolveSender = resolveAntigra
     return targets.read({ ...args, cwd: identity.cwd, sender: identity, ...(args.target === "codex" ? { threadId: args.conversationId } : { sessionId: args.conversationId }), beforeSend: recheck(identity, extra) });
   });
 
-  return { server, close: async () => { await targets.close(); await server.close(); } };
+  reload.listen();
+  return { server, reload, busy: () => deliveries.active.size ? "Antigravity outbound deliveries are still active" : null, close: async () => { await targets.close(); await server.close(); } };
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
@@ -136,7 +157,7 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
     await bridge.close();
     await stopProcessInspectors();
   };
-  for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => { void stop(); });
-  process.stdin.once("end", () => { void stop(); });
   await bridge.server.connect(new StdioServerTransport());
+  const shutdown = exitWhenClientCloses({ busy: bridge.busy, stop });
+  for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => { void shutdown.close(signal); });
 }

package/src/antigravity-outbound-targets.mjs

@@ -9,6 +9,7 @@ import { assertRecipientClass } from "./recipient-preflight.mjs";
 import { recoverClaudeDesktopSession, sameClaudeDesktopRecipient } from "./claude-session-router.mjs";
 import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
 import { protectCurrentUserPipe } from "./windows-pipe-acl.mjs";
+import { cloneReloadState } from "./reload-control.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;
 
@@ -50,10 +51,12 @@ export function createAntigravityOutboundTargets(options = {}) {
   const peerFactory = options.peerFactory ?? ((settings) => new PeerEndpoint(settings));
   const receipts = new Map();
   let peer;
+  let peerCwd;
+  let paused = false;
   let closed = false;
 
   function operation(sender, beforeSend, required = false) {
-    if (closed) throw blocked("Antigravity outbound targets have been closed");
+    if (closed || paused) throw blocked("Antigravity outbound targets are closed or quiesced");
     if (required && typeof beforeSend !== "function") throw blocked("A live Antigravity sender revalidation callback is required");
     const identity = senderIdentity(sender);
     const cwd = captureDirectory(identity.cwd);
@@ -61,7 +64,7 @@ export function createAntigravityOutboundTargets(options = {}) {
     const accounts = readAccounts();
     const accountContext = requireBridgeAccounts(accounts);
     const check = async () => {
-      if (closed) throw blocked("Antigravity outbound targets have been closed");
+      if (closed || paused) throw blocked("Antigravity outbound targets are closed or quiesced");
       assertAccounts(accountContext);
       roots.recheck(root, "Antigravity sender project");
       const current = captureDirectory(identity.cwd);
@@ -210,7 +213,10 @@ export function createAntigravityOutboundTargets(options = {}) {
     if (target !== "claude") throw blocked("Target must be codex or claude");
     const recipient = await recoverClaudeRecipient(context, sessionId, taskId);
     assertRecipientClass(recipient, context.identity);
-    if (!peer) peer = peerFactory({ name: `antigravity-${process.pid}`, cwd: context.cwd, signalExit: false, env, protectSocket: protectCurrentUserPipe });
+    if (!peer) {
+      peerCwd = context.cwd;
+      peer = peerFactory({ name: `antigravity-${process.pid}`, cwd: peerCwd, signalExit: false, env, protectSocket: protectCurrentUserPipe });
+    }
     await peer.start();
     let msgId;
     try {
@@ -275,5 +281,54 @@ export function createAntigravityOutboundTargets(options = {}) {
     await peer?.closed;
   }
 
-  return { list, send, read, close };
+  const reloadReason = () => peer?.reloadReason() ?? null;
+
+  async function quiesce() {
+    const reason = reloadReason();
+    if (reason) throw new Error(reason);
+    paused = true;
+    await peer?.quiesce();
+  }
+
+  function exportReloadState() {
+    if (!paused || reloadReason()) throw new Error("Quiesce Antigravity targets before exporting reload state");
+    return cloneReloadState({ receipts: [...receipts], peer: peer ? { cwd: peerCwd, state: peer.exportReloadState() } : null });
+  }
+
+  function restoreReloadState(input) {
+    if (peer || receipts.size || closed) throw new Error("Antigravity reload state requires empty targets");
+    const state = cloneReloadState(input);
+    if (!state || !Array.isArray(state.receipts) || state.receipts.length > 100000
+      || state.peer !== null && (!state.peer || typeof state.peer.cwd !== "string" || !path.isAbsolute(state.peer.cwd))) {
+      throw new Error("Invalid Antigravity target reload state");
+    }
+    const restored = new Map();
+    for (const pair of state.receipts) {
+      if (!Array.isArray(pair) || pair.length !== 2 || typeof pair[0] !== "string" || !pair[0] || restored.has(pair[0])) throw new Error("Invalid Antigravity receipt reload record");
+      const record = pair[1];
+      const identity = senderIdentity(record?.sender);
+      if (typeof record.cwd !== "string" || !path.isAbsolute(record.cwd) || typeof identity.cwd !== "string" || !sameDirectory(record.cwd, identity.cwd)
+        || !record.accountContext || typeof record.accountContext.codex !== "string" || !record.accountContext.codex
+        || typeof record.accountContext.claude !== "string" || !record.accountContext.claude) throw new Error("Invalid Antigravity receipt ownership reload record");
+      restored.set(pair[0], { ...record, sender: identity });
+    }
+    if (!state.peer && restored.size) throw new Error("Antigravity receipts require their native peer state");
+    if (state.peer) {
+      const nativeMessages = state.peer.state?.sentMessages;
+      if (!Array.isArray(nativeMessages) || nativeMessages.length !== restored.size || nativeMessages.some(([id]) => !restored.has(id))) throw new Error("Antigravity receipt ownership does not match native peer state");
+      const candidate = peerFactory({ name: `antigravity-${process.pid}`, cwd: state.peer.cwd, signalExit: false, env, protectSocket: protectCurrentUserPipe });
+      candidate.restoreReloadState(state.peer.state);
+      peer = candidate;
+      peerCwd = state.peer.cwd;
+    }
+    for (const [id, record] of restored) receipts.set(id, record);
+  }
+
+  async function activate() {
+    if (closed) throw new Error("Antigravity targets are closed");
+    await peer?.resume();
+    paused = false;
+  }
+
+  return { list, send, read, close, reloadReason, quiesce, exportReloadState, restoreReloadState, activate };
 }

package/src/background-antigravity-worker.mjs

@@ -0,0 +1,192 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { AntigravityCliSession, resolveAntigravityCliBinary } from "./antigravity-cli.mjs";
+
+const runFile = promisify(execFile);
+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;
+const RELAY_TOOLS = ["worker_status", "list_workers", "send_to_worker", "read_worker_delivery"];
+const RELAY_ENV = ["AGENT_RELAY_ENDPOINT", "AGENT_RELAY_TOKEN", "AGENT_RELAY_WORKER_ID", "AGENT_RELAY_REQUEST_ID"];
+const MAX_STDERR_BYTES = 65536;
+
+function failure(code, reason, phase, deliveryState = "not_sent") {
+  return Object.assign(new Error(reason), { code, phase, deliveryState, sent: deliveryState === "sent" ? true : deliveryState === "not_sent" ? false : null });
+}
+
+export async function inspectAntigravityWorker({ env = process.env, executable, platform = process.platform, run = runFile } = {}) {
+  const state = { agent: "antigravity", available: false, authenticated: null, ready: false };
+  let binary;
+  try { binary = resolveAntigravityCliBinary({ binary: executable, env, platform }); }
+  catch { return { ...state, code: "ANTIGRAVITY_CLI_UNAVAILABLE", reason: "The dedicated Antigravity CLI executable is unavailable." }; }
+  try {
+    const result = await run(binary, ["--version"], { env: { ...env }, windowsHide: true, shell: false, timeout: 5000, maxBuffer: 4096, encoding: "utf8" });
+    const status = result?.exitCode ?? result?.status ?? result?.code ?? 0;
+    const version = String(result?.stdout ?? "").trim();
+    if (status !== 0 || !/^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?$/i.test(version)) throw new Error("Invalid version result");
+    return { ...state, available: true, executable: binary, version, code: "ANTIGRAVITY_AUTH_UNVERIFIED", reason: "Antigravity CLI has no supported read-only authentication probe. An authorized job must establish runtime authentication." };
+  } catch {
+    return { ...state, executable: binary, code: "ANTIGRAVITY_INSPECTION_FAILED", reason: "Antigravity CLI version inspection failed or returned an unsupported response." };
+  }
+}
+
+function classifyDiagnostic(value) {
+  if (typeof value !== "string") return null;
+  const text = value.slice(0, 8192).replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ");
+  if (/\b(?:unauthenticated|auth(?:entication)?[ _-]+(?:required|failed)|not[ _-]+authenticated|not[ _-]+logged[ _-]+in|(?:login|sign[ -]?in)[ _-]+required|(?:credentials?|tokens?)[ _-]+(?:are[ _-]+|is[ _-]+|has[ _-]+|have[ _-]+)?(?:expired|invalid|missing))\b/i.test(text)) return "authentication";
+  if (/\b(?:soft[ _-]+denied|permission[ _-]+(?:denied|required|rejected)|approval[ _-]+required|requires?[ _-]+(?:user[ _-]+)?(?:approval|permission))\b/i.test(text)
+      || /\b(?:tool|mcp)\b[^\r\n]{0,160}\b(?:not allowed|blocked|denied)\b/i.test(text)) return "permission";
+  return null;
+}
+
+function discoverRelayTools(tools) {
+  if (tools === undefined) return { relayToolsVerified: false, relayToolDiscovery: "unadvertised" };
+  if (!Array.isArray(tools) || tools.length > 4096 || tools.some((name) => typeof name !== "string" || !name || name.length > 256)) {
+    throw failure("ANTIGRAVITY_WORKER_PROTOCOL_ERROR", "Antigravity CLI advertised an invalid tool list.", "startup");
+  }
+  const names = new Set(tools.map((name) => name.replace(/[-_:/\.]+/g, "_")));
+  if (RELAY_TOOLS.every((name) => names.has(name) || names.has(`worker_relay_${name}`) || names.has(`mcp_worker_relay_${name}`))) return { relayToolsVerified: true, relayToolDiscovery: "explicit-tools" };
+  if (tools.includes("call_mcp_tool")) return { relayToolsVerified: false, relayToolDiscovery: "mcp-dispatcher" };
+  throw failure("ANTIGRAVITY_RELAY_TOOLS_MISSING", "Antigravity CLI advertised neither its native MCP dispatcher nor all required worker-relay tools. Inspect the CLI MCP configuration.", "relay");
+}
+
+function workerEnvironment(env, relayMcp, requestId) {
+  const grant = relayMcp?.env;
+  if (typeof relayMcp?.command !== "string" || !relayMcp.command || !Array.isArray(relayMcp.args)
+      || relayMcp.args.some((value) => typeof value !== "string") || !grant || typeof grant !== "object" || Array.isArray(grant)
+      || RELAY_ENV.some((key) => typeof grant[key] !== "string" || !grant[key] || grant[key].length > 8192 || grant[key].includes("\0"))
+      || grant.AGENT_RELAY_REQUEST_ID !== requestId) {
+    throw failure("ANTIGRAVITY_RELAY_GRANT_INVALID", "The Antigravity worker requires a complete relay grant bound to this request.", "preflight");
+  }
+  const cleaned = Object.fromEntries(Object.entries(env).filter(([name]) => !/^(?:CODEX_|CLAUDE|ANTHROPIC_|MCP_|AGENT_RELAY_)/i.test(name)));
+  for (const key of RELAY_ENV) cleaned[key] = grant[key];
+  return cleaned;
+}
+
+export async function runAntigravityWorker({ executable, cwd, prompt, requestId, sessionId, env = process.env, relayMcp, onEvent = () => {}, signal, timeoutMs = 600000, spawn, conversationId, resume } = {}) {
+  if (conversationId !== undefined || resume !== undefined) throw failure("ANTIGRAVITY_WORKER_RESUME_UNSUPPORTED", "Background Antigravity jobs require a fresh CLI conversation and cannot resume an external conversation.", "preflight");
+  if (typeof prompt !== "string" || !prompt.trim() || !UUID.test(requestId ?? "")
+      || sessionId !== undefined && !UUID.test(sessionId) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1
+      || typeof onEvent !== "function") {
+    throw failure("ANTIGRAVITY_WORKER_INPUT_INVALID", "The Antigravity worker requires a non-empty prompt, valid request identity, and bounded timeout.", "preflight");
+  }
+  if (signal?.aborted) throw failure("ANTIGRAVITY_WORKER_ABORTED", "The Antigravity worker was canceled before dispatch.", "cancellation");
+  const workerEnv = workerEnvironment(env, relayMcp, requestId);
+  const deadline = Date.now() + timeoutMs;
+  let session;
+  let initialized;
+  let accepted = false;
+  let terminal = false;
+  let diagnosticKind = null;
+  let stderrBytes = 0;
+  let stderrTail = "";
+  let stderrOverflow = false;
+  let observerFailed = false;
+  let finalError;
+  let deadlineTimer;
+  let rejectInterruption;
+  const interrupted = new Promise((resolve, reject) => { rejectInterruption = reject; });
+  interrupted.catch(() => {});
+  const observers = [];
+  const deliveryState = () => accepted ? "sent" : session && ["unknown", "completed"].includes(session.read().deliveryState) ? "unknown" : "not_sent";
+  const notify = (event) => {
+    try { observers.push(Promise.resolve(onEvent(event)).catch(() => { observerFailed = true; })); }
+    catch { observerFailed = true; }
+  };
+  const accept = () => {
+    if (accepted) return;
+    accepted = true;
+    notify({ type: "accepted", sessionId: initialized.conversation_id });
+  };
+  const observeDiagnostic = (value) => {
+    const kind = classifyDiagnostic(value);
+    if (kind && (!diagnosticKind || kind === "authentication")) diagnosticKind = kind;
+  };
+  const diagnosticFailure = () => diagnosticKind === "authentication"
+    ? failure("ANTIGRAVITY_AUTH_REQUIRED", "Antigravity CLI could not authenticate the background worker. Restore its configured credentials without opening a Desktop chat.", "authentication", deliveryState())
+    : diagnosticKind === "permission"
+      ? failure("ANTIGRAVITY_PERMISSION_DENIED", "Antigravity CLI denied a required tool operation. Inspect its scoped permission rules; no permissions were changed.", "permission", deliveryState())
+      : stderrOverflow ? failure("ANTIGRAVITY_WORKER_DIAGNOSTIC_LIMIT", "Antigravity CLI exceeded its bounded diagnostic limit; successful execution could not be verified.", "observation", deliveryState()) : null;
+  const abort = () => {
+    if (!terminal) {
+      const error = failure("ANTIGRAVITY_WORKER_ABORTED", "The Antigravity worker was canceled. Inspect its existing receipt before further action.", "cancellation", deliveryState());
+      session?.fail(error);
+      rejectInterruption(error);
+    }
+  };
+  const observe = (promise) => Promise.race([promise, interrupted]);
+  try {
+    session = new AntigravityCliSession({
+      binary: executable, cwd, env: workerEnv, spawn,
+      startupTimeoutMs: Math.min(30000, timeoutMs), turnTimeoutMs: timeoutMs, closeTimeoutMs: Math.min(1000, timeoutMs),
+      onStderr(chunk) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        if (bytes.length > MAX_STDERR_BYTES - stderrBytes) stderrOverflow = true;
+        if (stderrBytes >= MAX_STDERR_BYTES) return;
+        const text = bytes.subarray(0, MAX_STDERR_BYTES - stderrBytes).toString("utf8");
+        stderrBytes += Math.min(bytes.length, MAX_STDERR_BYTES - stderrBytes);
+        for (let offset = 0; offset < text.length; offset += 4096) {
+          stderrTail = `${stderrTail}${text.slice(offset, offset + 4096)}`.slice(-8192);
+          observeDiagnostic(stderrTail);
+        }
+      },
+      onEvent(event) {
+        if (event.event === "init") {
+          initialized = { conversation_id: event.conversation_id, tools: event.init.tools };
+          return;
+        }
+        if (event.event === "result") {
+          accept();
+          terminal = true;
+          observeDiagnostic(event.result.error);
+          return;
+        }
+        if (event.event !== "step_update") return;
+        const step = event.step_update;
+        if (!step || step.conversation_id !== initialized?.conversation_id) throw new Error("Invalid Antigravity event");
+        if (!session.awaitingResult) throw new Error("Invalid Antigravity event");
+        if (step.step_type === "user_input" && step.state === "DONE") accept();
+        const error = step.tool_info?.error;
+        if (error) observeDiagnostic(typeof error === "string" ? error : `${typeof error.type === "string" ? error.type : ""} ${typeof error.message === "string" ? error.message : ""}`);
+      },
+    });
+    deadlineTimer = setTimeout(() => {
+      const error = failure("ANTIGRAVITY_WORKER_TIMEOUT", "The Antigravity worker exceeded its observation deadline. Inspect its existing receipt before further action.", "observation", deliveryState());
+      session.fail(error);
+      rejectInterruption(error);
+    }, Math.max(1, deadline - Date.now()));
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) throw failure("ANTIGRAVITY_WORKER_ABORTED", "The Antigravity worker was canceled before dispatch.", "cancellation");
+    const started = await observe(session.start());
+    if (diagnosticFailure()) throw diagnosticFailure();
+    const relayTools = discoverRelayTools(initialized?.tools);
+    notify({ type: "session", sessionId: started.conversationId });
+    await observe(Promise.all(observers));
+    if (observerFailed) throw failure("ANTIGRAVITY_WORKER_OBSERVER_FAILED", "The Antigravity worker could not record its session event.", "observation");
+    if (signal?.aborted) throw failure("ANTIGRAVITY_WORKER_ABORTED", "The Antigravity worker was canceled before dispatch.", "cancellation");
+    const remaining = deadline - Date.now();
+    if (remaining < 1) throw failure("ANTIGRAVITY_WORKER_TIMEOUT", "The Antigravity worker exceeded its observation deadline.", "observation");
+    session.turnTimeoutMs = remaining;
+    const result = await observe(session.send(prompt));
+    await observe(session.close());
+    await observe(Promise.all(observers));
+    if (observerFailed) throw failure("ANTIGRAVITY_WORKER_OBSERVER_FAILED", "The Antigravity worker could not record its acceptance event.", "observation", deliveryState());
+    if (diagnosticFailure()) throw diagnosticFailure();
+    if (result.status !== "SUCCESS" || result.error) throw failure("ANTIGRAVITY_WORKER_TURN_FAILED", "Antigravity CLI returned an unsuccessful background turn. Inspect the existing worker receipt.", "execution", deliveryState());
+    return { output: result.response, sessionId: result.conversation_id, ...(sessionId ? { workerSessionId: sessionId } : {}), deliveryState: "sent", sent: true, authenticated: true, ...relayTools };
+  } catch (error) {
+    const state = deliveryState();
+    if (/^ANTIGRAVITY_[A-Z_]+$/.test(error?.code ?? "")) finalError = failure(error.code, error.message, error.phase, state);
+    else if (diagnosticFailure()) finalError = diagnosticFailure();
+    else if (["STARTUP_TIMEOUT", "TURN_TIMEOUT"].includes(error?.code)) finalError = failure("ANTIGRAVITY_WORKER_TIMEOUT", "The Antigravity worker exceeded its observation deadline. Inspect its existing receipt before further action.", "observation", state);
+    else if (error?.code === "INVALID_PROTOCOL") finalError = failure("ANTIGRAVITY_WORKER_PROTOCOL_ERROR", "Antigravity CLI returned invalid or mismatched streaming data.", "protocol", state);
+    else finalError = failure("ANTIGRAVITY_WORKER_FAILED", "The Antigravity CLI worker could not complete its operation. Inspect its existing receipt before further action.", state === "not_sent" ? "startup" : "execution", state);
+    finalError.requestId = requestId;
+    if (initialized?.conversation_id) finalError.sessionId = initialized.conversation_id;
+    if (sessionId) finalError.workerSessionId = sessionId;
+    throw finalError;
+  } finally {
+    clearTimeout(deadlineTimer);
+    signal?.removeEventListener("abort", abort);
+    const closed = await session?.close();
+    if (!finalError && closed?.status === "closing") throw failure("ANTIGRAVITY_WORKER_STOP_FAILED", "The Antigravity worker did not confirm process shutdown.", "shutdown", deliveryState());
+  }
+}