@minhspark/codex-mcp-bridge 1.26.10 → 1.27.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-mcp-bridge",
-  "version": "1.26.10",
+  "version": "1.27.0",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh"

package/CHANGELOG.md

@@ -2,7 +2,16 @@
 
 Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](https://semver.org/).
 
-## [Unreleased]
+## [1.27.0] - 2026-11-05
+
+### Added
+
+- A versioned local Antigravity human-dashboard channel with exact conversation/workspace validation, fixed human sender identity, durable idempotent request receipts and explicit preflight/uncertain delivery outcomes. It requires the app-launched sidecar and never treats native acceptance as a completed reply.
+
+### Verification and limits
+
+- Unit tests cover preflight, idempotent receipts and refusal paths on Windows, macOS and Linux with Node 22 and 24. Delivery through a live Antigravity sidecar was not exercised before this release.
+- Upgrade with `npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts`, then restart Antigravity so its sidecar loads the new channel.
 
 ## [1.26.10] - 2026-11-03
 

package/docs/daily-handoffs.md

@@ -154,3 +154,7 @@ is still null. Continue with `wait_codex_reply`; do not create again to obtain t
 ID. The updated companion retains late creation acknowledgements. If it reports
 unsupported `get_creation_receipt`, reload both bridge workers after installing
 the update; that compatibility check occurs before any new task is dispatched.
+
+## Local human dashboards
+
+Local human dashboards can use `src/antigravity-human.mjs`: `inspectHumanConversation({ conversationId, cwd })`, `sendHumanMessage({ requestId, conversationId, cwd, prompt })`, and `readHumanReceipt({ requestId, conversationId, cwd })`. The native app must have launched an updated sidecar advertising `humanDispatchVersion: 1`. Requests use an existing desktop conversation UUID, its canonical workspace and a stable request UUID. The sender is fixed to `human-web` / `minh-spark-company`; caller-supplied agent identities are rejected. Reusing a request ID never resends it, and changed request contents are refused. Poll the receipt after an uncertain outcome. Native acceptance does not prove a reply or completion. This channel does not answer permission prompts or create conversations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.26.10",
+  "version": "1.27.0",
   "description": "Connect Claude, Codex, and Antigravity through MCP, with native Desktop handoffs and bridge-owned Antigravity CLI sessions.",
   "keywords": [
     "mcp",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "codex-mcp-bridge",
-  "version": "1.26.10",
+  "version": "1.27.0",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-native-relay.mjs

@@ -25,7 +25,7 @@ import { removeRelayFile } from "../src/native-relay-files.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.26.10";
+const VERSION = "1.27.0";
 const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
 const entryArgs = ["native-relay-companion.mjs"];

package/src/antigravity-human.mjs

@@ -0,0 +1,70 @@
+import fs from "node:fs";
+import path from "node:path";
+import { callAntigravityDesktop } 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 const HUMAN_SENDER = Object.freeze({ provider: "human-web", id: "minh-spark-company" });
+
+function invalid(message, code = "ANTIGRAVITY_HUMAN_REQUEST_INVALID") {
+  return Object.assign(new Error(message), { code, phase: "validation", deliveryState: "not_sent" });
+}
+
+export function humanWorkspace(value) {
+  if (typeof value !== "string" || !path.isAbsolute(value)) throw invalid("An absolute existing workspace is required");
+  try {
+    const resolved = fs.realpathSync.native(value);
+    if (!fs.statSync(resolved).isDirectory()) throw new Error("not a directory");
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+  } catch { throw invalid("The requested workspace is unavailable"); }
+}
+
+export function humanDeliveryInput(input, operation) {
+  if (!input || typeof input !== "object" || !UUID.test(input.conversationId) || input.sender !== undefined) throw invalid("An exact conversation UUID and a fixed human sender are required");
+  const out = { conversationId: input.conversationId.toLowerCase(), cwd: humanWorkspace(input.cwd) };
+  if (operation !== "inspect") {
+    if (typeof input.requestId !== "string" || !UUID.test(input.requestId)) throw invalid("requestId must be a UUID");
+    out.requestId = input.requestId.toLowerCase();
+  }
+  if (operation === "send") {
+    if (typeof input.prompt !== "string" || !input.prompt.trim() || input.prompt.length > 30000 || input.prompt.includes("\0")) throw invalid("Prompt must contain between 1 and 30000 characters without NUL");
+    out.prompt = input.prompt;
+  }
+  return out;
+}
+
+export function humanReceipt(record, target) {
+  if (record === null) return null;
+  if (!record || record.requestId !== target.requestId || record.conversationId !== target.conversationId || record.surface !== "desktop" || record.sender?.provider !== HUMAN_SENDER.provider || record.sender?.id !== HUMAN_SENDER.id || humanWorkspace(record.cwd) !== target.cwd) throw invalid("Receipt does not belong to this human delivery", "ANTIGRAVITY_HUMAN_RECEIPT_MISMATCH");
+  return record;
+}
+
+async function callHuman(operation, input, options = {}) {
+  const target = humanDeliveryInput(input, operation);
+  const call = options.call ?? ((request) => callAntigravityDesktop(request, { directory: options.directory, timeoutMs: options.timeoutMs ?? 10000 }));
+  let status;
+  try { status = await call({ operation: "status" }); }
+  catch (error) {
+    if (operation === "send") {
+      error.deliveryState = "not_sent";
+      error.phase = "preflight";
+    }
+    throw error;
+  }
+  if (status?.available !== true || status.humanDispatchVersion !== 1) throw invalid("The app-launched Antigravity sidecar must be updated to support human dashboard messages", "ANTIGRAVITY_HUMAN_UNSUPPORTED");
+  const result = await call({ operation: `human-${operation}`, ...target });
+  if (operation !== "inspect") {
+    try {
+      if (operation === "send" && result === null) throw invalid("No delivery receipt returned");
+      return humanReceipt(result, target);
+    } catch (error) {
+      if (operation === "send") { error.deliveryState = "unknown"; error.phase = "response"; }
+      throw error;
+    }
+  }
+  if (!result || result.conversationId !== target.conversationId || humanWorkspace(result.cwd) !== target.cwd || result.surface !== "desktop" || result.available !== true || result.status !== "CASCADE_RUN_STATUS_IDLE") throw invalid("Native conversation does not match the requested idle workspace", "ANTIGRAVITY_HUMAN_TARGET_MISMATCH");
+  return result;
+}
+
+export function inspectHumanConversation(input, options) { return callHuman("inspect", input, options); }
+export function sendHumanMessage(input, options) { return callHuman("send", input, options); }
+export function readHumanReceipt(input, options) { return callHuman("receipt", input, options); }

package/src/antigravity-sidecar.mjs

@@ -6,6 +6,7 @@ import { AntigravityDeliveries } from "./antigravity-deliveries.mjs";
 import { listAntigravityConversations, observeAntigravityDelivery, runAgentApi, sanitizeAntigravityMetadata } from "./antigravity-desktop.mjs";
 import { exitForVersionRequest } from "./cli-version.mjs";
 import { readProcessAncestry } from "./claude-sender-context.mjs";
+import { HUMAN_SENDER, humanDeliveryInput, humanReceipt, humanWorkspace } from "./antigravity-human.mjs";
 
 export async function createAntigravityParentGuard({ parentPid = process.ppid, inspect = readProcessAncestry } = {}) {
   if (!Number.isSafeInteger(parentPid) || parentPid <= 1 || parentPid > 0xffffffff) throw new Error("Antigravity sidecar parent is unavailable; relaunch it from the native app");
@@ -34,7 +35,7 @@ export async function createAntigravityParentGuard({ parentPid = process.ppid, i
   };
 }
 
-export async function startAntigravitySidecar({ directory = antigravityBridgeDirectory(), env = process.env, createParentGuard = createAntigravityParentGuard, serve = serveAntigravityDesktop, parentCheckIntervalMs = 5000, onParentLost = () => {}, runNative = runAgentApi, observeDelivery = observeAntigravityDelivery } = {}) {
+export async function startAntigravitySidecar({ directory = antigravityBridgeDirectory(), env = process.env, createParentGuard = createAntigravityParentGuard, serve = serveAntigravityDesktop, parentCheckIntervalMs = 5000, onParentLost = () => {}, list = listAntigravityConversations, runNative = runAgentApi, observeDelivery = observeAntigravityDelivery } = {}) {
   if (!env.ANTIGRAVITY_AGENTAPI_EXE || !env.ANTIGRAVITY_LS_ADDRESS) throw new Error("Antigravity must launch this sidecar. Do not run it as a replacement app server.");
   const assertParent = await createParentGuard();
   const deliveries = new AntigravityDeliveries(path.join(directory, "desktop-deliveries"));
@@ -59,7 +60,33 @@ export async function startAntigravitySidecar({ directory = antigravityBridgeDir
   sidecar = await serve(async (request) => {
     await checkParent();
     if (!request || typeof request !== "object") throw new Error("Invalid sidecar request");
-    if (request.operation === "status") return { available: true, transport: "native-agentapi", permissionPolicy: "native-unchanged" };
+    if (request.operation === "status") return { available: true, transport: "native-agentapi", permissionPolicy: "native-unchanged", humanDispatchVersion: 1 };
+    if (["human-inspect", "human-send", "human-receipt"].includes(request.operation)) {
+      const operation = request.operation.slice("human-".length);
+      const target = humanDeliveryInput(request, operation);
+      if (operation === "receipt") return humanReceipt(deliveries.read(target.requestId), target);
+      const inspect = async () => {
+        await checkParent();
+        const records = (await list({ surface: "desktop", limit: 1000 })).filter((record) => record.conversationId === target.conversationId);
+        if (records.length !== 1 || records[0].surface !== "desktop" || humanWorkspace(records[0].cwd) !== target.cwd) throw Object.assign(new Error("Exact Antigravity conversation and workspace are unavailable"), { code: "ANTIGRAVITY_RECIPIENT_MISSING", deliveryState: "not_sent" });
+        const record = records[0];
+        if (record.status !== "CASCADE_RUN_STATUS_IDLE") throw Object.assign(new Error("Antigravity conversation is busy; no message was sent"), { code: "ANTIGRAVITY_RECIPIENT_BUSY", deliveryState: "not_sent" });
+        const metadata = sanitizeAntigravityMetadata(await runNative({ command: "metadata", conversationId: target.conversationId, env }), target.conversationId);
+        if (humanWorkspace(metadata.cwd) !== target.cwd || metadata.projectId !== record.projectId) throw Object.assign(new Error("Native Antigravity workspace or project changed"), { code: "ANTIGRAVITY_METADATA_MISMATCH", deliveryState: "not_sent" });
+        await checkParent();
+        return { ...record, ...metadata, available: true };
+      };
+      if (operation === "inspect") return inspect();
+      return deliveries.dispatch({ ...target, surface: "desktop", sender: HUMAN_SENDER }, async () => {
+        await checkParent();
+        if (sending.has(target.conversationId)) throw Object.assign(new Error("Another delivery is pending for this conversation"), { deliveryState: "not_sent" });
+        sending.add(target.conversationId);
+        try {
+          await inspect();
+          return await runNative({ command: "send", conversationId: target.conversationId, expectedCwd: target.cwd, prompt: target.prompt, env });
+        } finally { sending.delete(target.conversationId); }
+      });
+    }
     if (request.operation === "list") return listAntigravityConversations({ surface: "desktop" });
     if (request.operation === "read") {
       const records = await listAntigravityConversations({ surface: "desktop" });

package/src/claude-bridge.mjs

@@ -31,7 +31,7 @@ import { BACKGROUND_WORKER_GUIDANCE, registerBackgroundTools } from "./backgroun
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.26.10";
+const VERSION = "1.27.0";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;

package/src/index.mjs

@@ -44,7 +44,7 @@ import { BACKGROUND_WORKER_GUIDANCE, registerBackgroundTools } from "./backgroun
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.26.10";
+const VERSION = "1.27.0";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 

package/src/native-relay-companion.mjs

@@ -43,7 +43,7 @@ import { remoteCodexSocketPath, remoteNativeAdapter, remoteRequestResponse } fro
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.26.10";
+const VERSION = "1.27.0";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent, details) {