@minhspark/codex-mcp-bridge 1.25.3 → 1.26.0

package/src/background-relay-client.mjs

@@ -0,0 +1,107 @@
+import net from "node:net";
+import { readRelayConfiguration, relayFailure } from "./background-relay-config.mjs";
+import { RELAY_FRAME_LIMIT, RELAY_REPLY_LIMIT, relayHello, validRelayHello, verifyRelayChallenge, relayOperation, verifyRelayResponse } from "./background-relay-protocol.mjs";
+
+export function relayConnection(env = process.env) {
+  if (env.AGENT_RELAY_TOKEN || env.AGENT_RELAY_WORKER_ID || env.AGENT_RELAY_ENDPOINT) {
+    if (!env.AGENT_RELAY_TOKEN || !env.AGENT_RELAY_WORKER_ID || !env.AGENT_RELAY_ENDPOINT) throw relayFailure("WORKER_IDENTITY_INCOMPLETE", "The worker relay capability is incomplete");
+    return { endpoint: env.AGENT_RELAY_ENDPOINT, token: env.AGENT_RELAY_TOKEN, workerId: env.AGENT_RELAY_WORKER_ID };
+  }
+  const config = readRelayConfiguration({ env, missing: true });
+  if (!config) throw relayFailure("WORKER_RELAY_NOT_CONFIGURED", "Run the package update or setup command to configure the independent background relay");
+  if (!config.enabled) throw relayFailure("WORKER_RELAY_DISABLED", "Background relay is intentionally disabled in its configuration");
+  return { endpoint: config.endpoint, token: config.token, workerId: null };
+}
+
+export async function callBackgroundRelay(method, params = {}, { env = process.env, connection = relayConnection(env), timeoutMs = 10000, connect = net.createConnection } = {}) {
+  const initial = relayHello(connection.workerId ?? null);
+  if (!validRelayHello(initial) || typeof connection.token !== "string" || !connection.token || typeof connection.endpoint !== "string" || !connection.endpoint
+    || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120000) throw relayFailure("WORKER_CONNECTION_INVALID", "Background relay connection options are invalid");
+  const operation = JSON.parse(JSON.stringify({ schemaVersion: 1, id: initial.id, workerId: initial.workerId, clientPid: process.pid, method, params }));
+  if (Buffer.byteLength(JSON.stringify(operation)) + 256 > RELAY_FRAME_LIMIT) throw relayFailure("WORKER_REQUEST_TOO_LARGE", "Background relay request is too large");
+  return new Promise((resolve, reject) => {
+    let socket;
+    let sent = false;
+    let complete = false;
+    let attempts = 0;
+    let retryTimer;
+    const deadline = Date.now() + timeoutMs;
+    const state = () => sent && method === "send" ? "unknown" : "not_sent";
+    const failed = (code, message) => relayFailure(code, message, state(), "relay_transport");
+    const finish = (error, result) => {
+      if (complete) return;
+      complete = true;
+      clearTimeout(timer);
+      clearTimeout(retryTimer);
+      socket?.destroy();
+      error ? reject(error) : resolve(result);
+    };
+    const timer = setTimeout(() => finish(failed("WORKER_RELAY_TIMEOUT", "The independent relay did not answer before the deadline")), timeoutMs);
+    const attempt = () => {
+      if (complete) return;
+      if (Date.now() >= deadline) { finish(failed("WORKER_RELAY_TIMEOUT", "The independent relay did not answer before the deadline")); return; }
+      attempts++;
+      let current;
+      let connected = false;
+      let received = false;
+      let retired = false;
+      let buffer = "";
+      let challenge;
+      const hello = relayHello(initial.workerId, initial.id);
+      const disconnect = (error, code = "WORKER_RELAY_UNAVAILABLE") => {
+        if (complete || retired) return;
+        retired = true;
+        current?.destroy();
+        const transient = ["ENOENT", "ECONNREFUSED", "ECONNRESET", "EBUSY", "EPIPE"].includes(error?.code)
+          || connected && code === "WORKER_RELAY_INTERRUPTED";
+        if (!sent && !received && attempts < 12 && transient) {
+          const remaining = deadline - Date.now();
+          if (remaining <= 0) { finish(failed("WORKER_RELAY_TIMEOUT", "The independent relay did not answer before the deadline")); return; }
+          retryTimer = setTimeout(attempt, Math.min(250 * 2 ** (attempts - 1), 1000, remaining));
+        } else finish(failed(code, "The independent relay connection ended before a verified receipt was received"));
+      };
+      try { current = socket = connect(connection.endpoint); }
+      catch (error) { disconnect(error); return; }
+      current.setEncoding("utf8");
+      current.on("connect", () => {
+        if (complete || retired) return;
+        if (Date.now() >= deadline) { finish(failed("WORKER_RELAY_TIMEOUT", "The independent relay did not answer before the deadline")); return; }
+        connected = true;
+        try { current.write(JSON.stringify(hello) + "\n"); }
+        catch (error) { disconnect(error); }
+      });
+      current.on("error", error => disconnect(error));
+      current.on("close", () => disconnect(null, "WORKER_RELAY_INTERRUPTED"));
+      current.on("data", data => {
+        if (complete || retired) return;
+        if (Buffer.byteLength(data)) received = true;
+        buffer += data;
+        if (Buffer.byteLength(buffer) > (challenge ? RELAY_REPLY_LIMIT : 4096)) { finish(failed("WORKER_REPLY_TOO_LARGE", "The relay response exceeded its limit")); return; }
+        const end = buffer.indexOf("\n");
+        if (end < 0) return;
+        if (buffer.slice(end + 1).length) { finish(failed("WORKER_REPLY_INVALID", "The relay sent multiple or trailing protocol frames")); return; }
+        let message;
+        try { message = JSON.parse(buffer.slice(0, end)); }
+        catch { finish(failed("WORKER_REPLY_INVALID", "The relay response is not valid JSON")); return; }
+        buffer = "";
+        if (!challenge) {
+          if (!verifyRelayChallenge(connection.token, hello, message)) { finish(failed("WORKER_RELAY_AUTH_FAILED", "The local endpoint could not prove its relay identity; no operation was sent")); return; }
+          if (Date.now() >= deadline) { finish(failed("WORKER_RELAY_TIMEOUT", "The independent relay did not answer before the deadline")); return; }
+          challenge = message;
+          const wire = JSON.stringify(relayOperation(connection.token, hello, challenge, operation)) + "\n";
+          sent = true;
+          try { current.write(wire); } catch (error) { disconnect(error); }
+          return;
+        }
+        if (!verifyRelayResponse(connection.token, hello, challenge, message)) { finish(failed("WORKER_REPLY_INVALID", "The relay response failed authentication or request correlation")); return; }
+        const response = message.response;
+        if (response.error) {
+          const error = relayFailure(response.error.code ?? "WORKER_OPERATION_FAILED", response.error.message ?? "Background relay operation failed", response.error.deliveryState ?? "unknown", response.error.phase ?? "relay");
+          if (response.error.diagnostic) error.diagnostic = response.error.diagnostic;
+          finish(error);
+        } else finish(null, response.result);
+      });
+    };
+    attempt();
+  });
+}

package/src/background-relay-config.mjs

@@ -0,0 +1,98 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { readRegularConfigFile } from "./project-policy.mjs";
+import { protectPrivateRelayDirectory, assertPrivateRelayDirectory, assertPrivateRelayFile,
+  beginPrivateRelayWrite, bindPrivateRelayWrite, finishPrivateRelayWrite, abortPrivateRelayWrite } from "./background-relay-storage.mjs";
+
+export const BACKGROUND_AGENTS = Object.freeze(["codex", "claude", "antigravity"]);
+export const BACKGROUND_TOOLS = Object.freeze(["worker_status", "list_workers", "send_to_worker", "read_worker_delivery"]);
+export const RELAY_UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
+
+export function canStartBackgroundWorker(agent, readiness) {
+  return readiness.available === true && readiness.authenticated !== false && (readiness.ready === true
+    || agent === "antigravity" && readiness.authenticated === null && /AUTH_UNVERIFIED$/.test(readiness.code ?? ""));
+}
+
+export function relayFailure(code, message, deliveryState = "not_sent", phase = "preflight") {
+  return Object.assign(new Error(message), { code, phase, deliveryState, sent: deliveryState === "not_sent" ? false : deliveryState === "sent" ? true : null });
+}
+
+export function relayPaths(env = process.env, platform = process.platform) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  const directory = env.AGENT_RELAY_DIRECTORY || path.join(env.XDG_CONFIG_HOME || path.join(home, ".config"), "GptClaudeBridge", "agent-relay");
+  if (!path.isAbsolute(directory)) throw relayFailure("WORKER_CONFIG_INVALID", "The background relay directory must be absolute");
+  const root = path.resolve(directory);
+  const hash = createHash("sha256").update(platform === "win32" ? root.toLowerCase() : root).digest("hex").slice(0, 24);
+  return { root, config: path.join(root, "config.json"), jobs: path.join(root, "jobs"),
+    endpoint: platform === "win32" ? `\\\\.\\pipe\\LOCAL\\minhspark-agent-relay-${hash}` : path.join(root, "relay.sock"),
+    defaultPolicy: env.CODEX_BRIDGE_PROJECT_POLICY || path.join(home, ".config", "GptClaudeBridge", "projects.json") };
+}
+
+export function privateRelayDirectory(directory) {
+  return protectPrivateRelayDirectory(directory);
+}
+
+export function writeRelayJson(file, value) {
+  const directory = path.dirname(file);
+  const temporary = path.join(directory, `.${path.basename(file)}.${randomUUID()}.tmp`);
+  const encoded = JSON.stringify(value, null, 2) + "\n";
+  if (Buffer.byteLength(encoded) > 4 * 1024 * 1024) throw relayFailure("WORKER_STORAGE_LIMIT", "Relay state exceeds its storage limit");
+  const ticket = beginPrivateRelayWrite(file);
+  let descriptor;
+  try {
+    const existing = readRegularConfigFile(file, { missing: true, maxBytes: 4 * 1024 * 1024, label: "Relay state" });
+    descriptor = fs.openSync(temporary, "wx", 0o600);
+    fs.writeFileSync(descriptor, encoded);
+    fs.fsyncSync(descriptor);
+    bindPrivateRelayWrite(ticket, temporary, descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    if (readRegularConfigFile(file, { missing: true, maxBytes: 4 * 1024 * 1024, label: "Relay state" }) !== existing) throw relayFailure("WORKER_CONFIG_CHANGED", "Relay state changed concurrently");
+    fs.renameSync(temporary, file);
+    finishPrivateRelayWrite(ticket);
+  } finally {
+    abortPrivateRelayWrite(ticket);
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+    try { fs.unlinkSync(temporary); } catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+}
+
+export function readRelayConfiguration({ env = process.env, platform = process.platform, missing = false } = {}) {
+  const paths = relayPaths(env, platform);
+  try { fs.lstatSync(paths.root); }
+  catch (error) { if (missing && error.code === "ENOENT") return null; throw error; }
+  assertPrivateRelayDirectory(paths.root);
+  if (!assertPrivateRelayFile(paths.config, { missing })) return null;
+  const raw = readRegularConfigFile(paths.config, { missing, maxBytes: 64 * 1024, label: "Relay configuration" });
+  if (raw === null) return null;
+  let config;
+  try { config = JSON.parse(raw); } catch { throw relayFailure("WORKER_CONFIG_INVALID", "Relay configuration is not valid JSON"); }
+  if (!config || config.schemaVersion !== 1 || typeof config.enabled !== "boolean" || config.endpoint !== paths.endpoint
+      || typeof config.token !== "string" || !/^[A-Za-z0-9_-]{43}$/.test(config.token)
+      || typeof config.projectPolicy !== "string" || !path.isAbsolute(config.projectPolicy)
+      || !config.providers || typeof config.providers !== "object" || Array.isArray(config.providers)) {
+    throw relayFailure("WORKER_CONFIG_INVALID", "Relay configuration has an unsupported schema");
+  }
+  for (const name of BACKGROUND_AGENTS) {
+    const provider = config.providers[name];
+    if (!provider || typeof provider.enabled !== "boolean" || provider.executable !== null && (typeof provider.executable !== "string" || !path.isAbsolute(provider.executable))) {
+      throw relayFailure("WORKER_CONFIG_INVALID", "Worker executable configuration is invalid");
+    }
+  }
+  return { ...config, paths };
+}
+
+export function configureRelay({ env = process.env, platform = process.platform, providers = {}, projectPolicy } = {}) {
+  const paths = relayPaths(env, platform);
+  const previous = readRelayConfiguration({ env, platform, missing: true });
+  const config = { schemaVersion: 1, enabled: previous?.enabled ?? true, endpoint: paths.endpoint,
+    token: previous?.token ?? randomBytes(32).toString("base64url"),
+    projectPolicy: projectPolicy ?? previous?.projectPolicy ?? paths.defaultPolicy,
+    providers: Object.fromEntries(BACKGROUND_AGENTS.map(name => [name, { enabled: previous?.providers[name]?.enabled ?? true,
+      executable: providers[name]?.executable ?? previous?.providers[name]?.executable ?? null }])) };
+  if (!path.isAbsolute(config.projectPolicy)) throw relayFailure("WORKER_CONFIG_INVALID", "Project policy must use an absolute path");
+  writeRelayJson(paths.config, config);
+  return readRelayConfiguration({ env, platform });
+}

package/src/background-relay-daemon.mjs

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import { sourceRevision } from "./release-snapshot.mjs";
+import { fileURLToPath } from "node:url";
+import { isMainModule } from "./install-paths.mjs";
+import { readRelayConfiguration, relayFailure, writeRelayJson } from "./background-relay-config.mjs";
+import { BackgroundRelay, backgroundAdapters, serveBackgroundRelay } from "./background-relay.mjs";
+import { bridgeDiagnostic } from "./recipient-preflight.mjs";
+import path from "node:path";
+
+export async function runBackgroundDaemon({ env = process.env, exit = code => process.exit(code) } = {}) {
+  const config = readRelayConfiguration({ env });
+  if (!config.enabled) throw relayFailure("WORKER_RELAY_DISABLED", "The independent background relay is disabled");
+  const configuration = JSON.stringify(config);
+  const root = fileURLToPath(new URL("..", import.meta.url));
+  const revision = sourceRevision(root);
+  const relay = new BackgroundRelay({ config, env, adapters: await backgroundAdapters() });
+  let transport;
+  try { transport = await serveBackgroundRelay(relay); }
+  catch (error) {
+    if (error.code === "EADDRINUSE") throw relayFailure("WORKER_RELAY_ALREADY_RUNNING", "A relay already owns this endpoint; another daemon was not started");
+    throw error;
+  }
+  try { await relay.initialize(); }
+  catch (error) { await transport.close(); throw error; }
+  let stopping = false;
+  let requestedExit = null;
+  const stop = async code => {
+    if (stopping) return;
+    stopping = true;
+    clearInterval(poll);
+    clearInterval(health);
+    await transport.close();
+    exit(code);
+  };
+  const requestStop = code => { requestedExit = code; relay.accepting = false; };
+  const poll = setInterval(() => {
+    if (stopping) return;
+    try {
+      if (requestedExit === null && (sourceRevision(root) !== revision || JSON.stringify(readRelayConfiguration({ env })) !== configuration)) requestStop(75);
+      if (!relay.accepting && requestedExit === null) requestedExit = 75;
+      if (requestedExit !== null && relay.active.size === 0) void stop(requestedExit);
+    } catch (error) {
+      const diagnostic = bridgeDiagnostic(error, { component: "background-relay", operation: "watch_update", readOnly: true });
+      try { writeRelayJson(path.join(config.paths.root, "last-service-error.json"), diagnostic); } catch {}
+    }
+  }, 2000);
+  const health = setInterval(() => { void relay.refreshHealth(); }, 60000);
+  process.once("SIGTERM", () => requestStop(0));
+  process.once("SIGINT", () => requestStop(0));
+  process.stdout.write(JSON.stringify({ event: "relay_ready", pid: process.pid, version: JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version, desktopRequired: false }) + "\n");
+  return { relay, transport, stop: () => requestStop(0) };
+}
+
+if (isMainModule(process.argv[1], import.meta.url)) {
+  runBackgroundDaemon().catch(error => {
+    const diagnostic = bridgeDiagnostic(error, { component: "background-relay", operation: "startup" });
+    process.stderr.write(JSON.stringify({ diagnostic }) + "\n");
+    process.exitCode = 1;
+  });
+}

package/src/background-relay-mcp.mjs

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { isMainModule } from "./install-paths.mjs";
+import { callBackgroundRelay } from "./background-relay-client.mjs";
+import { withBridgeDiagnostic } from "./recipient-preflight.mjs";
+
+export const BACKGROUND_WORKER_GUIDANCE = "For explicitly authorized work that must run with Desktop apps closed or frozen, use worker_status, send_to_worker and read_worker_delivery for separate background CLI workers. These tools have independent identities and project authorization; they never open, resume or impersonate a Desktop chat. Keep native task IDs on native tools. Never replay an uncertain native send through a worker. Show diagnostic codes and report blocks in the current chat when a relay call fails. ";
+
+export function registerBackgroundTools(register, { env = process.env, call = callBackgroundRelay } = {}) {
+  const titles = { worker_status: "Inspect background relay", list_workers: "List background workers", send_to_worker: "Send work to a background agent", read_worker_delivery: "Read background delivery" };
+  const tool = (name, description, inputSchema, readOnly, method) => register(name, { title: titles[name], description, inputSchema,
+    annotations: { readOnlyHint: readOnly, destructiveHint: !readOnly, idempotentHint: true, openWorldHint: !readOnly } }, async args => {
+    try {
+      const result = await call(method, args, { env, timeoutMs: method === "read" ? ((args.waitSec ?? 0) + 10) * 1000 : 15000 });
+      const failed = result.status === "failed" || result.status === "unknown";
+      const response = { ...(failed ? { isError: true } : {}), content: [{ type: "text", text: JSON.stringify(result, null, 2) }], structuredContent: result };
+      return failed ? withBridgeDiagnostic(response, { diagnostic: result.diagnostic, message: "The independent background worker did not complete successfully" },
+        { component: "background-relay", operation: name, requestId: result.requestId, deliveryState: result.deliveryState }) : response;
+    } catch (error) {
+      return withBridgeDiagnostic({ isError: true, content: [] }, error, { component: "background-relay", operation: name,
+        requestId: args.requestId, readOnly: readOnly && method !== "read" });
+    }
+  });
+  tool("worker_status", "Inspect the independent background relay, CLI readiness and recent diagnostic reports. Desktop apps may be closed or frozen. Transport readiness is separate from each CLI's authentication/model readiness. authentication-unverified with canAcceptWork=true is informational: that CLI lacks an auth probe and may run authorized work. Do not call it an authentication failure; report actual job failures from their receipts.", {}, true, "status");
+  tool("list_workers", "List independently identified CLI workers and this caller's background task receipts. These are separate from Desktop chats; never use a native chat ID as a worker destination.", {}, true, "list");
+  tool("send_to_worker", "Queue explicitly authorized work to a separate background CLI worker in an explicitly selected, authorized project. This does not address, open or resume any Desktop chat. Generate requestId once and keep it for retries; an uncertain result must be inspected with read_worker_delivery, never resent under another ID. Use worker-relay tools for subsequent cross-agent delegation. Work continues independently when Desktop apps close or freeze.", {
+    agent: z.enum(["codex", "claude", "antigravity"]).describe("The separate CLI agent that will perform this authorized task."),
+    cwd: z.string().min(1).describe("Absolute path to the explicitly selected and authorized project."),
+    prompt: z.string().min(1).max(262144).describe("Complete authorized task brief, including context, scope, constraints and completion criteria. Never request a Desktop chat substitution."),
+    requestId: z.string().uuid().describe("Generate once for this independent task and reuse for retries; inspect this ID after any uncertain delivery."),
+  }, false, "send");
+  tool("read_worker_delivery", "Read or wait for a durable background task receipt using its original requestId. A queued receipt is not a completed response. Failed and unknown receipts include the report block to show directly in this chat. Unknown work is never automatically replayed.", {
+    requestId: z.string().uuid().describe("The original request ID returned by send_to_worker."),
+    waitSec: z.number().int().min(0).max(60).optional().describe("Maximum seconds to wait for a terminal receipt; zero returns immediately."),
+  }, true, "read");
+}
+
+if (isMainModule(process.argv[1], import.meta.url)) {
+  const { version } = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  const server = new McpServer({ name: "worker-relay", version }, { instructions: BACKGROUND_WORKER_GUIDANCE + "Preserve request IDs, poll receipts until a terminal result, and never replay uncertain work. Delegate only authorized work in the same project. Native account logins and CLI logins are separate readiness checks; never copy credentials or open apps/chats to recover the relay." });
+  registerBackgroundTools(server.registerTool.bind(server));
+  await server.connect(new StdioServerTransport());
+}

package/src/background-relay-protocol.mjs

@@ -0,0 +1,54 @@
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+
+export const RELAY_FRAME_LIMIT = 1024 * 1024;
+export const RELAY_REPLY_LIMIT = 4 * 1024 * 1024;
+const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
+const NONCE = /^[A-Za-z0-9_-]{43}$/;
+const object = value => value !== null && typeof value === "object" && !Array.isArray(value);
+const keys = (value, expected) => object(value) && Object.keys(value).length === expected.length && expected.every(key => Object.hasOwn(value, key));
+const sign = (secret, domain, ...values) => createHmac("sha256", secret).update(JSON.stringify(["minhspark-background-relay", 1, domain, ...values])).digest("base64url");
+const equal = (left, right) => typeof left === "string" && NONCE.test(left) && timingSafeEqual(Buffer.from(left), Buffer.from(right));
+
+export function relayHello(workerId = null, id = randomUUID()) {
+  return { schemaVersion: 1, type: "hello", id, workerId, clientNonce: randomBytes(32).toString("base64url") };
+}
+
+export function validRelayHello(value) {
+  return keys(value, ["schemaVersion", "type", "id", "workerId", "clientNonce"]) && value.schemaVersion === 1 && value.type === "hello"
+    && UUID.test(value.id) && (value.workerId === null || UUID.test(value.workerId)) && NONCE.test(value.clientNonce);
+}
+
+export function relayChallenge(secret, hello) {
+  const serverNonce = randomBytes(32).toString("base64url");
+  return { schemaVersion: 1, type: "challenge", id: hello.id, serverNonce, proof: sign(secret, "server-proof", hello, serverNonce) };
+}
+
+export function verifyRelayChallenge(secret, hello, value) {
+  return keys(value, ["schemaVersion", "type", "id", "serverNonce", "proof"]) && value.schemaVersion === 1 && value.type === "challenge"
+    && value.id === hello.id && NONCE.test(value.serverNonce) && equal(value.proof, sign(secret, "server-proof", hello, value.serverNonce));
+}
+
+export function relayOperation(secret, hello, challenge, operation) {
+  return { schemaVersion: 1, type: "operation", operation, proof: sign(secret, "client-operation", hello, challenge.serverNonce, operation) };
+}
+
+export function verifyRelayOperation(secret, hello, challenge, value) {
+  const operation = value?.operation;
+  return keys(value, ["schemaVersion", "type", "operation", "proof"]) && value.schemaVersion === 1 && value.type === "operation"
+    && keys(operation, ["schemaVersion", "id", "workerId", "clientPid", "method", "params"]) && operation.schemaVersion === 1
+    && operation.id === hello.id && operation.workerId === hello.workerId && Number.isSafeInteger(operation.clientPid) && operation.clientPid > 0
+    && ["status", "list", "read", "send", "drain"].includes(operation.method) && object(operation.params)
+    && equal(value.proof, sign(secret, "client-operation", hello, challenge.serverNonce, operation));
+}
+
+export function relayResponse(secret, hello, challenge, response) {
+  return { schemaVersion: 1, type: "response", response, proof: sign(secret, "server-response", hello, challenge.serverNonce, response) };
+}
+
+export function verifyRelayResponse(secret, hello, challenge, value) {
+  const response = value?.response;
+  return keys(value, ["schemaVersion", "type", "response", "proof"]) && value.schemaVersion === 1 && value.type === "response"
+    && object(response) && response.schemaVersion === 1 && response.id === hello.id
+    && (keys(response, ["schemaVersion", "id", "result"]) || keys(response, ["schemaVersion", "id", "error"]) && object(response.error))
+    && equal(value.proof, sign(secret, "server-response", hello, challenge.serverNonce, response));
+}

package/src/background-relay-registration.mjs

@@ -0,0 +1,198 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { BACKGROUND_TOOLS, relayFailure } from "./background-relay-config.mjs";
+import { readRegularConfigFile } from "./project-policy.mjs";
+import { stableInstallPath, stableNodeBin } from "./install-paths.mjs";
+
+const MAX_BYTES = 1024 * 1024;
+const NAME = "worker-relay";
+const DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const invalid = () => relayFailure("WORKER_MCP_CONFIG_INVALID", "Antigravity worker configuration must contain valid JSON objects and permission lists.", "not_sent", "setup");
+const unsafe = () => relayFailure("WORKER_MCP_CONFIG_UNSAFE", "Antigravity worker configuration must use bounded regular files and unlinked directories.", "not_sent", "setup");
+const changed = () => relayFailure("WORKER_MCP_CONFIG_CHANGED", "Antigravity worker configuration changed during setup; concurrent changes were preserved.", "not_sent", "setup");
+const sameFile = (left, right) => left === null || right === null ? left === right
+  : ["dev", "ino", "size", "mode", "mtimeNs", "ctimeNs", "nlink"].every((field) => left[field] === right[field]);
+
+function stat(file) {
+  try { return fs.lstatSync(file, { bigint: true }); }
+  catch (error) { if (error.code === "ENOENT") return null; throw unsafe(); }
+}
+
+function directories(home, file, create = false) {
+  const relative = path.relative(home, path.dirname(file));
+  if (path.isAbsolute(relative) || relative === ".." || relative.startsWith(`..${path.sep}`)) throw unsafe();
+  let current = home;
+  for (const segment of ["", ...relative.split(path.sep).filter(Boolean)]) {
+    if (segment) current = path.join(current, segment);
+    let entry = stat(current);
+    if (entry === null && create) {
+      try { fs.mkdirSync(current, { mode: 0o700 }); }
+      catch (error) { if (error.code !== "EEXIST") throw unsafe(); }
+      entry = stat(current);
+    }
+    if (entry === null) return;
+    if (!entry.isDirectory() || entry.isSymbolicLink()) throw unsafe();
+  }
+}
+
+function snapshot(home, file) {
+  directories(home, file);
+  const before = stat(file);
+  let text;
+  try { text = readRegularConfigFile(file, { missing: true, maxBytes: MAX_BYTES, label: "Antigravity worker configuration" }); }
+  catch { throw unsafe(); }
+  const after = stat(file);
+  if (!sameFile(before, after)) throw changed();
+  let value;
+  try { value = text === null ? {} : JSON.parse(text); }
+  catch { throw invalid(); }
+  if (!object(value)) throw invalid();
+  return { file, text, value, stat: after, mode: after ? Number(after.mode & 0o777n) : 0o600 };
+}
+
+function assertCurrent(home, expected) {
+  const current = snapshot(home, expected.file);
+  if (current.text !== expected.text || !sameFile(current.stat, expected.stat)) throw changed();
+  return current;
+}
+
+function replace(home, original, text, mode, applied) {
+  if (Buffer.byteLength(text) > MAX_BYTES) throw unsafe();
+  directories(home, original.file, true);
+  assertCurrent(home, original);
+  const temporary = path.join(path.dirname(original.file), `.${path.basename(original.file)}.${randomUUID()}.tmp`);
+  let descriptor;
+  let identity;
+  try {
+    descriptor = fs.openSync(temporary, "wx", mode);
+    identity = fs.fstatSync(descriptor, { bigint: true });
+    fs.writeFileSync(descriptor, text, "utf8");
+    if (process.platform !== "win32") fs.fchmodSync(descriptor, mode);
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    assertCurrent(home, original);
+    fs.renameSync(temporary, original.file);
+    applied?.push({ original, text, identity });
+    const current = snapshot(home, original.file);
+    if (current.text !== text || current.stat?.dev !== identity.dev || current.stat?.ino !== identity.ino) throw changed();
+    return current;
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+    const remaining = stat(temporary);
+    if (remaining && identity && remaining.dev === identity.dev && remaining.ino === identity.ino) fs.unlinkSync(temporary);
+  }
+}
+
+function apply(home, edits) {
+  const applied = [];
+  try {
+    for (const edit of edits) assertCurrent(home, edit);
+    for (const edit of edits) replace(home, edit, edit.next, edit.mode, applied);
+  } catch (error) {
+    let incomplete = false;
+    for (const record of applied.reverse()) {
+      try {
+        const current = snapshot(home, record.original.file);
+        if (current.text !== record.text || current.stat?.dev !== record.identity.dev || current.stat?.ino !== record.identity.ino) throw changed();
+        if (record.original.text === null) {
+          assertCurrent(home, current);
+          fs.unlinkSync(current.file);
+          if (snapshot(home, current.file).text !== null) throw changed();
+        } else replace(home, current, record.original.text, record.original.mode);
+      } catch { incomplete = true; }
+    }
+    if (incomplete) throw relayFailure("WORKER_MCP_REGISTRATION_INCOMPLETE", "Antigravity worker setup stopped after a partial update. Concurrent changes prevented safe rollback; inspect both configuration files.", "not_sent", "setup");
+    if (/^WORKER_MCP_/.test(error?.code ?? "")) throw error;
+    throw relayFailure("WORKER_MCP_WRITE_FAILED", "Antigravity worker configuration could not be saved. Previously completed updates were restored.", "not_sent", "setup");
+  }
+}
+
+function samePath(left, right, platform) {
+  if (typeof left !== "string" || !path.isAbsolute(left) || left.includes("\0")) return false;
+  const normalize = (value) => platform === "win32" ? path.resolve(value).toLowerCase() : path.resolve(value);
+  if (normalize(left) === normalize(right)) return true;
+  try { return normalize(fs.realpathSync.native(left)) === normalize(fs.realpathSync.native(right)); }
+  catch { return false; }
+}
+
+function ownedEntry(entry, expected, platform) {
+  if (entry === undefined) return;
+  if (!object(entry) || !samePath(entry.command, expected.command, platform)
+      || !Array.isArray(entry.args) || entry.args.length !== 1 || !samePath(entry.args[0], expected.args[0], platform)
+      || entry.type !== undefined && entry.type !== "stdio"
+      || ["url", "serverUrl", "serverURL", "httpUrl", "headers", "oauth", "authProviderType"].some((key) => Object.hasOwn(entry, key))
+      || entry.env !== undefined && (!object(entry.env) || Object.keys(entry.env).length !== 0)) {
+    throw relayFailure("WORKER_MCP_COLLISION", "The canonical worker-relay MCP name is already used by a different configuration. It was not overwritten.", "not_sent", "setup");
+  }
+  if (entry.disabled !== undefined && typeof entry.disabled !== "boolean") throw invalid();
+  for (const key of ["enabledTools", "disabledTools"]) {
+    if (entry[key] !== undefined && (!Array.isArray(entry[key]) || entry[key].length > 4096 || entry[key].some((value) => typeof value !== "string" || value.length > 1024))) throw invalid();
+  }
+}
+
+function permissionState(settings, entry) {
+  if (settings.permissions !== undefined && !object(settings.permissions)) throw invalid();
+  const permissions = settings.permissions ?? {};
+  for (const key of ["allow", "ask", "deny"]) {
+    if (permissions[key] !== undefined && (!Array.isArray(permissions[key]) || permissions[key].length > 4096 || permissions[key].some((rule) => typeof rule !== "string" || rule.length > 1024))) throw invalid();
+  }
+  if (settings.toolPermission !== undefined && typeof settings.toolPermission !== "string") throw invalid();
+  const policyVerified = settings.toolPermission === undefined || ["request-review", "proceed-in-sandbox", "always-proceed", "strict"].includes(settings.toolPermission);
+  const matches = (rule, tool) => {
+    const match = /^mcp\((.*)\)$/.exec(rule.trim());
+    return match && ["*", `${NAME}/*`, `${NAME}/${tool}`].includes(match[1].trim());
+  };
+  const blockedTools = BACKGROUND_TOOLS.filter((tool) => !policyVerified || settings.toolPermission === "strict" || entry.disabled === true
+    || entry.enabledTools !== undefined && !entry.enabledTools.includes(tool)
+    || entry.disabledTools?.includes(tool)
+    || [...(permissions.deny ?? []), ...(permissions.ask ?? [])].some((rule) => matches(rule, tool)));
+  return { blockedTools, policyVerified };
+}
+
+export function configureBackgroundWorkerMcp({ env = process.env, platform = process.platform, root = DEFAULT_ROOT, dryRun = false, check = false } = {}) {
+  const selectedHome = platform === "win32" ? env.USERPROFILE || env.HOME || os.homedir() : env.HOME || env.USERPROFILE || os.homedir();
+  if (typeof selectedHome !== "string" || !path.isAbsolute(selectedHome) || typeof root !== "string" || !path.isAbsolute(root)) throw invalid();
+  let home;
+  let entry;
+  try {
+    home = fs.realpathSync.native(selectedHome);
+    if (!fs.statSync(home).isDirectory()) throw unsafe();
+    entry = path.join(stableInstallPath(fs.realpathSync.native(root), env), "src", "background-relay-mcp.mjs");
+    if (!fs.statSync(entry).isFile()) throw invalid();
+  } catch { throw relayFailure("WORKER_MCP_PATH_INVALID", "The user home or installed background relay entrypoint is unavailable.", "not_sent", "setup"); }
+  const files = { mcp: path.join(home, ".gemini", "config", "mcp_config.json"), settings: path.join(home, ".gemini", "antigravity-cli", "settings.json") };
+  const originals = { mcp: snapshot(home, files.mcp), settings: snapshot(home, files.settings) };
+  const mcp = structuredClone(originals.mcp.value);
+  const settings = structuredClone(originals.settings.value);
+  if (mcp.mcpServers !== undefined && !object(mcp.mcpServers)) throw invalid();
+  const expected = { command: stableNodeBin(env), args: [entry] };
+  const existing = mcp.mcpServers?.[NAME];
+  ownedEntry(existing, expected, platform);
+  const policy = permissionState(settings, existing ?? expected);
+  mcp.mcpServers ??= {};
+  if (existing === undefined) mcp.mcpServers[NAME] = expected;
+  settings.permissions ??= {};
+  settings.permissions.allow ??= [];
+  const grants = BACKGROUND_TOOLS.map((tool) => `mcp(${NAME}/${tool})`);
+  const added = grants.filter((rule) => !settings.permissions.allow.includes(rule));
+  settings.permissions.allow.push(...added);
+  const edits = Object.entries({ mcp, settings }).flatMap(([key, value]) => {
+    const original = originals[key];
+    if (JSON.stringify(value) === JSON.stringify(original.value)) return [];
+    const next = JSON.stringify(value, null, 2) + "\n";
+    if (Buffer.byteLength(next) > MAX_BYTES) throw unsafe();
+    return [{ ...original, next }];
+  });
+  if (!dryRun && !check) apply(home, edits);
+  const configured = !edits.length || !dryRun && !check;
+  const blocked = policy.blockedTools.length > 0;
+  return { configured, changed: Boolean(edits.length && !dryRun && !check), wouldChange: edits.length > 0, blocked, files,
+    permissions: { ...policy, required: grants, added }, isolatedMcpInventory: false, nativeFallback: false,
+    ...(blocked ? { code: policy.policyVerified ? "WORKER_MCP_POLICY_BLOCKED" : "WORKER_MCP_POLICY_UNVERIFIED", reason: "Existing Antigravity permissions or MCP tool restrictions prevent unattended relay access. Those restrictions were preserved." }
+      : !configured ? { code: "WORKER_MCP_NOT_CONFIGURED", reason: "The Antigravity worker MCP registration or scoped permission grants require configuration." } : {}) };
+}