customer-map-codex-bridge 0.5.0

package/README.md

@@ -0,0 +1,50 @@
+# Customer Map Codex Bridge
+
+This local helper connects a user's already-authenticated Codex installation to Customer Map without sending Codex credentials or API keys to Customer Map.
+
+## Requirements
+
+- Codex CLI installed and already signed in locally (`codex login`).
+- Optional Gmail actions require `gog` v0.11.0+ with the intended Gmail account already authorized locally.
+- Node.js 18+.
+- The Customer Map Agent settings panel must provide a one-time `CMAP-CODEX-*` code.
+
+The settings panel reports **Connected** only after both the local Codex app-server and the Customer Map relay WebSocket are online. A claimed code by itself is only a pending binding.
+
+## Run
+
+```bash
+npx -y customer-map-codex-bridge@0.5.0 \
+  --site https://your-customer-map.example \
+  --code CMAP-CODEX-XXXXXXXXXXXX
+```
+
+Starting a newly authorized Bridge automatically replaces the older Bridge for the same Customer Map account. Clicking **Remove connection** in Customer Map disconnects the running Bridge, so users do not need to find or kill local processes.
+
+The bridge initializes Codex App Server with native live web search enabled, then explicitly applies a read-only sandbox with no approval prompts and command network access disabled to every new thread and every turn. This lets the assistants search and read public pages without granting model-generated shell commands arbitrary network or file-write access. Credentials stay on the local machine, and thread IDs are stored under `~/.customer-map-codex/state.json` and resumed after Bridge restarts. Task Assistant, Workbench Assistant, and Sales Assistant use separate thread scopes.
+
+When the user explicitly chooses **Save Gmail draft** or **Send email** in Customer Map, the bridge bypasses the Codex turn and executes only a validated, fixed `gog gmail drafts create` or `gog gmail send` argument list. It verifies the content hash and requires a real Gmail message/draft ID before reporting success. Chat cannot turn this into an arbitrary shell or network action.
+
+If the protocol handler cannot find `codex`, pass its absolute path explicitly:
+
+```bash
+npx -y customer-map-codex-bridge@0.5.0 \
+  --site https://your-customer-map.example \
+  --code CMAP-CODEX-XXXXXXXXXXXX \
+  --codex /absolute/path/to/codex
+```
+
+If `gog` is outside the standard Homebrew/system paths, pass it explicitly:
+
+```bash
+npx -y customer-map-codex-bridge@0.5.0 \
+  --site https://your-customer-map.example \
+  --code CMAP-CODEX-XXXXXXXXXXXX \
+  --gog /absolute/path/to/gog
+```
+
+The website can then open:
+
+```text
+customer-map-codex://connect?site=https%3A%2F%2Fyour-customer-map.example&code=CMAP-CODEX-XXXXXXXXXXXX
+```

package/index.mjs

@@ -0,0 +1,527 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { spawn, spawnSync } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { delimiter, dirname, join } from 'node:path';
+import process from 'node:process';
+import WebSocket from 'ws';
+import { executeCustomerMapMailAction } from './mail-action.mjs';
+
+const BRIDGE_VERSION = '0.5.0';
+
+const args = parseArgs(process.argv.slice(2));
+if (args.help) {
+  console.log('Usage: customer-map-codex-bridge --site <Customer Map URL> --code <one-time code> [--cwd <folder>] [--codex <path>] [--gog <path>]');
+  process.exit(0);
+}
+
+const uri = args.uri || process.argv.slice(2).find(value => String(value).startsWith('customer-map-codex://'));
+const uriValues = uri ? parseConnectUri(uri) : {};
+const site = validateSite(args.site || uriValues.site);
+const code = validateCode(args.code || uriValues.code);
+const clientId = args.client || `codex-bridge-${process.platform}-${process.pid}`;
+const stateDir = args.state || join(homedir(), '.customer-map-codex');
+const stateFile = join(stateDir, 'state.json');
+
+let bridgeToken = '';
+let connectionId = '';
+let codex = null;
+let codexLines = null;
+let relay = null;
+let state = { threads: {} };
+let rpcId = 0;
+let initialized = false;
+let closed = false;
+let active = null;
+let shutdownPromise = null;
+const pendingRpc = new Map();
+const loadedThreads = new Set();
+
+process.once('SIGINT', () => { void shutdown(new Error('Codex Bridge interrupted')); });
+process.once('SIGTERM', () => { void shutdown(new Error('Codex Bridge terminated')); });
+
+await main();
+
+async function main() {
+  try {
+    await requestAuthorization(site);
+    state = await loadState();
+
+    const codexCommand = resolveCodexCommand(args.codex);
+    codex = startCodexAppServer(args.cwd || process.cwd(), codexCommand);
+    codexLines = createInterface({ input: codex.stdout });
+    attachCodexHandlers();
+
+    await rpc('initialize', {
+      clientInfo: { name: 'customer_map_codex_bridge', title: 'Customer Map Codex Bridge', version: BRIDGE_VERSION },
+      capabilities: { experimentalApi: true },
+    });
+    sendCodex({ method: 'initialized', params: {} });
+    initialized = true;
+    const accountStatus = await rpc('account/read', { refreshToken: true }, 30_000);
+    if (accountStatus?.requiresOpenaiAuth && !accountStatus.account) {
+      throw new Error('Codex CLI 尚未登录，请先运行 codex login。');
+    }
+
+    // Only consume the one-time code after the local Codex runtime is healthy.
+    // A failed app-server launch must not strand the code as "expired".
+    const bridge = await claim();
+    bridgeToken = bridge.bridgeToken;
+    connectionId = bridge.connectionId;
+    relay = await connectRelay(bridge);
+    console.log('Customer Map Codex Bridge connected.');
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error || 'Codex Bridge failed'));
+    await shutdown(error);
+    process.exitCode = 1;
+  }
+}
+
+function attachCodexHandlers() {
+  codexLines.on('line', handleCodexLine);
+  codex.on('error', error => {
+    rejectPendingRpc(error);
+    if (!closed) {
+      console.error(`Could not start Codex app-server: ${error.message}`);
+      void shutdown(error);
+    }
+  });
+  codex.on('exit', codeValue => {
+    const error = new Error(`Codex app-server exited (${codeValue ?? 'unknown'})`);
+    rejectPendingRpc(error);
+    if (active) failActiveJob(error.message);
+    if (!closed) {
+      console.error(error.message);
+      void shutdown(error);
+    }
+  });
+}
+
+function handleCodexLine(line) {
+  let message;
+  try { message = JSON.parse(line); } catch { return; }
+  if (message.id !== undefined && pendingRpc.has(message.id)) {
+    const entry = pendingRpc.get(message.id);
+    pendingRpc.delete(message.id);
+    if (message.error) entry.reject(new Error(message.error.message || 'Codex app-server request failed'));
+    else entry.resolve(message.result);
+    return;
+  }
+  if (message.method === 'item/agentMessage/delta') {
+    const job = activeJob(message.params);
+    const delta = String(message.params?.delta || message.params?.text || '');
+    if (job && delta) {
+      job.text += delta;
+      sendRelay({ type: 'progress', jobId: job.id, content: job.text.slice(-100000) });
+    }
+  }
+  if (message.method === 'item/completed') {
+    const item = message.params?.item;
+    if ((item?.type === 'agent_message' || item?.type === 'agentMessage') && typeof item.text === 'string') {
+      const job = activeJob(message.params);
+      if (job) job.text = item.text;
+    }
+  }
+  if (message.method === 'error' && !message.params?.willRetry && activeJob(message.params)) {
+    failActiveJob(message.params?.error?.message || 'Codex turn failed');
+  }
+  if (message.method === 'turn/completed' && activeJob(message.params)) {
+    const turn = message.params?.turn;
+    if (turn?.status === 'failed' || turn?.status === 'interrupted') {
+      failActiveJob(turn?.error?.message || `Codex turn ${turn.status}`);
+    } else {
+      finishActiveJob();
+    }
+  }
+  if (message.method === 'turn/failed' && activeJob(message.params)) {
+    failActiveJob(message.params?.error?.message || 'Codex turn failed');
+  }
+}
+
+function connectRelay(bridge) {
+  return new Promise((resolve, reject) => {
+    const socket = new WebSocket(webSocketUrl(bridge.relayUrl));
+    relay = socket;
+    let ready = false;
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      socket.close();
+      reject(new Error('Codex Relay 握手超时，请检查 Relay 或 Tunnel 是否在线。'));
+    }, 20_000);
+
+    socket.on('open', () => {
+      sendRelay({
+        type: 'hello',
+        runtime: 'codex',
+        bridgeToken: bridge.bridgeToken,
+        connectionId: bridge.connectionId,
+        clientId,
+        pluginVersion: BRIDGE_VERSION,
+        capabilities: {
+          runtime: 'verified',
+          sessionContext: 'verified',
+          customerMapData: 'declared',
+          webRead: 'declared',
+          webSearch: 'declared',
+          gmailDraft: 'declared',
+          gmailSend: 'confirmation',
+        },
+      });
+    });
+
+    socket.on('message', raw => {
+      let message;
+      try { message = JSON.parse(String(raw)); } catch { return; }
+      if (message.type === 'ready') {
+        if (ready) return;
+        ready = true;
+        settled = true;
+        clearTimeout(timer);
+        resolve(socket);
+        return;
+      }
+      if (message.type === 'error' && !ready && !settled) {
+        settled = true;
+        clearTimeout(timer);
+        socket.close();
+        reject(new Error(String(message.error || 'Codex Relay rejected the Bridge')));
+        return;
+      }
+      handleRelayMessage(message);
+    });
+
+    socket.on('error', error => {
+      if (!ready && !settled) {
+        settled = true;
+        clearTimeout(timer);
+        reject(new Error(`Codex Relay 连接失败：${error.message}`));
+      } else {
+        console.error(`Codex Relay error: ${error.message}`);
+      }
+    });
+
+    socket.on('close', (codeValue, reasonValue) => {
+      const reason = String(reasonValue || '').trim();
+      if (!ready && !settled) {
+        settled = true;
+        clearTimeout(timer);
+        reject(new Error(`Codex Relay 在握手前断开 (${codeValue ?? 'unknown'})${reason ? `: ${reason}` : ''}`));
+        return;
+      }
+      if (!closed) void shutdown(new Error(`Codex Relay 已断开 (${codeValue ?? 'unknown'})${reason ? `: ${reason}` : ''}`));
+    });
+  });
+}
+
+function handleRelayMessage(message) {
+  if (message.type === 'ping') {
+    sendRelay({ type: 'pong', at: Date.now() });
+    return;
+  }
+  if (message.type === 'job') {
+    void runJob(message.job).catch(error => sendRelay({ type: 'complete', jobId: message.job?.id, error: error?.message || 'Codex request failed' }));
+  }
+}
+
+async function runJob(job) {
+  if (!initialized) throw new Error('Codex app-server is not initialized');
+  if (!job?.id) throw new Error('Missing relay job id');
+  if (activeJob()) throw new Error('Codex is already processing another request');
+
+  if (job.request?.mailAction) {
+    const controller = new AbortController();
+    active = { id: String(job.id), threadId: '', text: '', abort: () => controller.abort() };
+    try {
+      const response = await executeCustomerMapMailAction(job.request.mailAction, {
+        signal: controller.signal,
+        timeoutMs: job.timeoutMs,
+        gogCommand: args.gog,
+      });
+      if (!active || active.id !== String(job.id)) return;
+      active = null;
+      sendRelay({ type: 'complete', jobId: String(job.id), response: { output_text: JSON.stringify(response) } });
+    } catch (error) {
+      failActiveJob(error instanceof Error ? error.message : String(error || 'Codex mail action failed'));
+    }
+    return;
+  }
+
+  const sessionKey = String(job.request?.sessionKey || job.request?.conversationSessionId || 'default');
+  const threadId = await ensureThread(sessionKey);
+  const input = Array.isArray(job.request?.input) ? job.request.input : [];
+  const prompt = input
+    .map(item => `${String(item.role || 'user').toUpperCase()}:\n${stringifyContent(item.content)}`)
+    .join('\n\n')
+    .slice(-200000);
+  active = { id: String(job.id), threadId, text: '' };
+  try {
+    await rpc('turn/start', {
+      threadId,
+      approvalPolicy: 'never',
+      sandboxPolicy: { type: 'readOnly', networkAccess: false },
+      input: [{ type: 'text', text: prompt }],
+    });
+  } catch (error) {
+    failActiveJob(error instanceof Error ? error.message : String(error || 'Codex turn failed'));
+  }
+}
+
+async function ensureThread(sessionKey) {
+  let threadId = String(state.threads?.[sessionKey] || '');
+  if (threadId && !loadedThreads.has(threadId)) {
+    try {
+      const resumed = await rpc('thread/resume', {
+        threadId,
+        sandbox: 'read-only',
+        approvalPolicy: 'never',
+        excludeTurns: true,
+      }, 60_000);
+      threadId = String(resumed?.thread?.id || threadId);
+      loadedThreads.add(threadId);
+    } catch (error) {
+      if (!/thread not found/i.test(String(error?.message || error))) throw error;
+      threadId = '';
+    }
+  }
+  if (!threadId) {
+    threadId = String((await rpc('thread/start', {
+      sandbox: 'read-only',
+      approvalPolicy: 'never',
+    }, 60_000)).thread?.id || '');
+    if (!threadId) throw new Error('Codex did not return a thread id');
+    loadedThreads.add(threadId);
+  }
+  state.threads = { ...(state.threads || {}), [sessionKey]: threadId };
+  await saveState();
+  return threadId;
+}
+
+function activeJob(params) {
+  if (!active) return null;
+  const threadId = String(params?.threadId || '');
+  return threadId && threadId !== active.threadId ? null : active;
+}
+function finishActiveJob() {
+  if (!active) return;
+  const job = active;
+  active = null;
+  sendRelay({ type: 'complete', jobId: job.id, response: { output_text: job.text.trim() || 'Codex returned an empty response.' } });
+}
+function failActiveJob(error) {
+  if (!active) return;
+  const job = active;
+  active = null;
+  sendRelay({ type: 'complete', jobId: job.id, error: String(error || 'Codex request failed') });
+}
+
+function rpc(method, params, timeoutMs = 20_000) {
+  const id = ++rpcId;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pendingRpc.delete(id);
+      reject(new Error(`Codex app-server ${method} 超时`));
+    }, timeoutMs);
+    pendingRpc.set(id, {
+      resolve: value => { clearTimeout(timer); resolve(value); },
+      reject: error => { clearTimeout(timer); reject(error); },
+    });
+    try {
+      sendCodex({ method, id, params });
+    } catch (error) {
+      pendingRpc.delete(id);
+      clearTimeout(timer);
+      reject(error);
+    }
+  });
+}
+
+function rejectPendingRpc(error) {
+  for (const entry of pendingRpc.values()) entry.reject(error);
+  pendingRpc.clear();
+}
+
+function sendCodex(message) {
+  if (!codex?.stdin?.writable) throw new Error('Codex app-server stdin is unavailable');
+  codex.stdin.write(`${JSON.stringify(message)}\n`);
+}
+
+function sendRelay(message) {
+  if (relay?.readyState === WebSocket.OPEN) relay.send(JSON.stringify(message));
+}
+
+function startCodexAppServer(cwd, command) {
+  const codexArgs = ['app-server', '--listen', 'stdio://', '-c', 'web_search="live"'];
+  const pathValue = [dirname(process.execPath), dirname(command), process.env.PATH || ''].filter(Boolean).join(delimiter);
+  const options = { cwd, stdio: ['pipe', 'pipe', 'inherit'], windowsHide: true, env: { ...process.env, PATH: pathValue } };
+  if (process.platform !== 'win32') return spawn(command, codexArgs, options);
+  const commandShell = process.env.ComSpec || process.env.COMSPEC || 'C:\\Windows\\System32\\cmd.exe';
+  const commandLine = [command, ...codexArgs].map(quoteWindowsArg).join(' ');
+  return spawn(commandShell, ['/d', '/s', '/c', commandLine], options);
+}
+
+function resolveCodexCommand(value) {
+  const requested = String(value || process.env.CUSTOMER_MAP_CODEX_BIN || '').trim();
+  if (requested && requested !== 'codex' && requested !== 'codex.cmd') return requested;
+  if (process.platform === 'win32') return requested || 'codex.cmd';
+  const candidates = [
+    join(homedir(), '.npm-global', 'bin', 'codex'),
+    join(homedir(), '.local', 'bin', 'codex'),
+    '/opt/homebrew/bin/codex',
+    '/usr/local/bin/codex',
+    '/usr/bin/codex',
+  ];
+  return candidates.find(candidate => existsSync(candidate)) || 'codex';
+}
+
+function quoteWindowsArg(value) {
+  return `"${String(value).replaceAll('"', '\\"')}"`;
+}
+
+async function claim() {
+  const response = await fetch(`${site.replace(/\/$/, '')}/api/codex-link`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ action: 'claim', code, clientId }),
+  });
+  const data = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(data?.error || `Claim failed (${response.status})`);
+  const nextBridgeToken = String(data?.bridgeToken || '');
+  const nextConnectionId = String(data?.connectionId || '');
+  if (!nextBridgeToken || !nextConnectionId) throw new Error('Customer Map returned an incomplete Codex connection');
+  return { ...data, bridgeToken: nextBridgeToken, connectionId: nextConnectionId };
+}
+
+async function notifyOffline(error) {
+  if (!bridgeToken || !clientId) return;
+  const response = await fetch(`${site.replace(/\/$/, '')}/api/codex-link`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ action: 'bridge-offline', bridgeToken, clientId, error: String(error?.message || error || '') }),
+  });
+  if (!response.ok) throw new Error(`Customer Map offline status failed (${response.status})`);
+}
+
+async function shutdown(error) {
+  if (shutdownPromise) return shutdownPromise;
+  shutdownPromise = (async () => {
+    if (closed) return;
+    closed = true;
+    active?.abort?.();
+    if (active) failActiveJob(error instanceof Error ? error.message : String(error || 'Codex Bridge stopped'));
+    rejectPendingRpc(error instanceof Error ? error : new Error(String(error || 'Codex Bridge stopped')));
+    await notifyOffline(error).catch(() => undefined);
+    if (relay && (relay.readyState === WebSocket.OPEN || relay.readyState === WebSocket.CONNECTING)) relay.close();
+    if (codex && !codex.killed) codex.kill();
+    codexLines?.close();
+  })();
+  return shutdownPromise;
+}
+
+async function loadState() {
+  try {
+    const parsed = JSON.parse(await readFile(stateFile, 'utf8'));
+    return parsed && typeof parsed === 'object' && parsed.threads && typeof parsed.threads === 'object'
+      ? parsed
+      : { threads: {} };
+  } catch {
+    return { threads: {} };
+  }
+}
+
+async function saveState() {
+  await mkdir(stateDir, { recursive: true });
+  await writeFile(stateFile, JSON.stringify(state, null, 2), 'utf8');
+}
+
+function stringifyContent(value) {
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value)) return value.map(item => stringifyContent(item)).join('\n');
+  if (value && typeof value === 'object') {
+    const text = value.text || value.content || value.value;
+    if (typeof text === 'string') return text;
+    try { return JSON.stringify(value); } catch { return String(value); }
+  }
+  return String(value ?? '');
+}
+
+function required(value, name) { if (!value) throw new Error(`Missing ${name}`); return value; }
+function validateSite(value) {
+  const url = new URL(required(value, '--site'));
+  const localHttp = url.protocol === 'http:' && ['localhost', '127.0.0.1', '::1', '[::1]'].includes(url.hostname);
+  if (url.protocol !== 'https:' && !localHttp) throw new Error('Customer Map site must use HTTPS (localhost may use HTTP)');
+  return url.origin;
+}
+function validateCode(value) {
+  const normalized = String(required(value, '--code')).trim().toUpperCase().replace(/\s+/g, '');
+  if (!/^CMAP-CODEX-[A-F0-9]{12}$/.test(normalized)) throw new Error('Invalid Customer Map Codex connection code');
+  return normalized;
+}
+function parseArgs(values) {
+  const result = {};
+  for (let i = 0; i < values.length; i += 1) {
+    const value = values[i];
+    if (!value.startsWith('--')) continue;
+    const key = value.slice(2);
+    const next = values[i + 1];
+    if (!next || next.startsWith('--')) result[key] = true;
+    else { result[key] = next; i += 1; }
+  }
+  return result;
+}
+function webSocketUrl(value) {
+  const url = new URL(required(value, 'relayUrl'));
+  if (url.protocol === 'https:') url.protocol = 'wss:';
+  if (url.protocol === 'http:') url.protocol = 'ws:';
+  if (!/^wss?:$/.test(url.protocol)) throw new Error('Invalid relay URL');
+  return url.toString();
+}
+function parseConnectUri(value) {
+  const url = new URL(value);
+  return { site: url.searchParams.get('site') || '', code: url.searchParams.get('code') || '' };
+}
+
+async function requestAuthorization(siteUrl) {
+  if (process.platform === 'win32') {
+    const dialog = spawnSync('powershell.exe', [
+      '-NoLogo', '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass',
+      '-WindowStyle', 'Hidden', '-Command',
+      "$ErrorActionPreference='Stop'; Add-Type -AssemblyName PresentationFramework; $site = $env:CUSTOMER_MAP_CODEX_SITE; $message = \"Customer Map wants to connect to the Codex installed on this computer.`n`nSite: $site`n`nCodex chat stays read-only. Live web search may read public sites; shell network and file writes stay blocked. Only explicit Gmail draft/send actions may run local gog. Credentials stay local.\"; $result = [System.Windows.MessageBox]::Show($message, 'Customer Map - Codex authorization', 'YesNo', 'Question', 'No'); if ($result -eq 'Yes') { exit 0 }; exit 1",
+    ], { env: { ...process.env, CUSTOMER_MAP_CODEX_SITE: siteUrl }, stdio: 'ignore', windowsHide: true });
+    if (!dialog.error) {
+      if (dialog.status === 0) return;
+      console.log('Codex connection cancelled.');
+      process.exit(0);
+    }
+  }
+  if (process.platform === 'darwin') {
+    const dialog = spawnSync('osascript', ['-e', [
+      'on run argv',
+      '  set siteUrl to item 1 of argv',
+      '  set promptText to "Customer Map wants to connect to the Codex installed on this Mac." & return & return & "Site: " & siteUrl & return & return & "Codex chat stays read-only. Live web search may read public sites; shell network and file writes stay blocked. Only explicit Gmail draft/send actions may run local gog. Credentials stay local."',
+      '  display dialog promptText with title "Customer Map - Codex authorization" buttons {"Cancel", "Allow"} default button "Cancel"',
+      '  if button returned of result is "Allow" then return 0',
+      '  return 1',
+      'end run',
+    ].join('\n'), siteUrl], { stdio: 'ignore' });
+    if (!dialog.error) {
+      if (dialog.status === 0) return;
+      console.log('Codex connection cancelled.');
+      process.exit(0);
+    }
+  }
+  console.log(`\nCustomer Map wants to connect to the Codex installed on this computer.`);
+  console.log(`Site: ${siteUrl}`);
+  console.log('Codex chat stays read-only. Live web search may read public sites; shell network and file writes stay blocked. Only explicit Gmail draft/send actions may run local gog. Credentials stay local.');
+  process.stdout.write('Allow this connection? [y/N] ');
+  const input = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise(resolve => input.once('line', resolve));
+  input.close();
+  if (String(answer).trim().toLowerCase() !== 'y') {
+    console.log('Codex connection cancelled.');
+    process.exit(0);
+  }
+}

package/mail-action.mjs

@@ -0,0 +1,363 @@
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, isAbsolute, join, resolve } from 'node:path';
+import process from 'node:process';
+
+const MIN_GOG_VERSION = [0, 11, 0];
+const MAX_GOG_BODY_BYTES = 100_000;
+const MAX_PROCESS_OUTPUT_CHARS = 1_000_000;
+const mailActionResults = new Map();
+const gogVersionCache = new Map();
+
+export async function executeCustomerMapMailAction(
+  value,
+  { signal, timeoutMs, gogCommand: requestedGogCommand = '' },
+) {
+  let action;
+  try {
+    action = normalizeMailAction(value);
+  } catch (error) {
+    return mailActionResult(value, 'failed', { error: formatError(error) });
+  }
+
+  const cacheKey = `${action.kind}:${action.actionId}`;
+  const cached = mailActionResults.get(cacheKey);
+  if (cached) {
+    if (cached.bodyHash !== action.bodyHash) {
+      return mailActionResult(action, 'failed', { error: 'Mail action id was reused with different content.' });
+    }
+    return cached.result;
+  }
+
+  let gogCommand;
+  let toolVersion;
+  try {
+    gogCommand = resolveGogCommand(requestedGogCommand);
+    toolVersion = await readGogVersion(gogCommand, signal);
+  } catch (error) {
+    return cacheMailResult(cacheKey, action, mailActionResult(action, 'failed', {
+      error: `gog is unavailable or unsupported: ${compactStatus(formatError(error))}`,
+    }));
+  }
+
+  const processResult = await runProcess(gogCommand, buildGogMailArgs(action), {
+    signal,
+    timeoutMs: Math.max(5_000, Math.min(Number(timeoutMs) - 2_000 || 90_000, 90_000)),
+  });
+  return cacheMailResult(cacheKey, action, classifyGogProcessResult(action, processResult, toolVersion));
+}
+
+export function normalizeMailAction(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Invalid Customer Map mail action.');
+  }
+  const source = value;
+  const kind = source.kind === 'sendEmail' || source.kind === 'saveDraft' ? source.kind : '';
+  const actionId = cleanText(source.actionId).toLowerCase();
+  const account = cleanText(source.account).toLowerCase();
+  const recipient = cleanText(source.recipient).toLowerCase();
+  const subject = cleanText(source.subject);
+  const plainTextBody = stringValue(source.plainTextBody);
+  const htmlBody = stringValue(source.htmlBody);
+  const bodyHash = cleanText(source.bodyHash).toLowerCase();
+  if (source.version !== 1 || !kind) throw new Error('Unsupported Customer Map mail action version or kind.');
+  if (!/^[0-9a-f]{32}$/.test(actionId)) throw new Error('Invalid Customer Map mail action id.');
+  if (!validEmail(account) || !validEmail(recipient)) throw new Error('Invalid Gmail account or recipient.');
+  if (!subject || /[\r\n]/.test(subject)) throw new Error('Invalid email subject.');
+  if (!plainTextBody && !htmlBody) throw new Error('Email body is empty.');
+  if (looksLikeBodyPath(plainTextBody) || looksLikeBodyPath(htmlBody)) {
+    throw new Error('Email body cannot be a filesystem or stdin path.');
+  }
+  if (Buffer.byteLength(plainTextBody, 'utf8') > MAX_GOG_BODY_BYTES || Buffer.byteLength(htmlBody, 'utf8') > MAX_GOG_BODY_BYTES) {
+    throw new Error('Email body is too large for safe gog argument execution.');
+  }
+  if (!htmlBody && containsMarkdownTable(plainTextBody)) {
+    throw new Error('Markdown table requires an HTML body before using Gmail.');
+  }
+  if (bodyHash !== mailBodyHash(recipient, subject, plainTextBody, htmlBody)) {
+    throw new Error('Email body integrity check failed.');
+  }
+  return { version: 1, actionId, kind, account, recipient, subject, plainTextBody, htmlBody, bodyHash };
+}
+
+export function buildGogMailArgs(action) {
+  const args = action.kind === 'sendEmail' ? ['gmail', 'send'] : ['gmail', 'drafts', 'create'];
+  args.push(`--to=${action.recipient}`, `--subject=${action.subject}`);
+  if (action.htmlBody) args.push(`--body-html=${action.htmlBody}`);
+  if (action.plainTextBody) args.push(`--body=${action.plainTextBody}`);
+  args.push(`--account=${action.account}`);
+  if (action.kind === 'sendEmail') args.push('--force');
+  args.push('--json', '--no-input');
+  return args;
+}
+
+export function mailBodyHash(recipient, subject, plainTextBody, htmlBody) {
+  return createHash('sha256')
+    .update(recipient)
+    .update('\n')
+    .update(subject)
+    .update('\n')
+    .update(plainTextBody)
+    .update('\n')
+    .update(htmlBody)
+    .digest('hex');
+}
+
+export function extractMailResultId(text, kind) {
+  if (!text) return '';
+  const candidates = [];
+  try {
+    candidates.push(JSON.parse(text));
+  } catch {
+    for (const line of String(text).split(/\r?\n/).reverse()) {
+      try {
+        candidates.push(JSON.parse(line));
+        break;
+      } catch {
+        // Keep looking for the final JSON line.
+      }
+    }
+  }
+  for (const candidate of candidates) {
+    const found = findMailResultId(candidate, kind);
+    if (found) return found;
+  }
+  return /"(?:draftId|draft_id|messageId|message_id|id)"\s*:\s*"([^"\s]{6,})"/.exec(String(text))?.[1] || '';
+}
+
+export function classifyGogProcessResult(action, result, toolVersion = '') {
+  const operation = action.kind === 'sendEmail' ? 'send' : 'draft create';
+  const mailbox = action.kind === 'sendEmail' ? 'Gmail Sent' : 'Gmail Drafts';
+  if (result.timedOut || result.aborted) {
+    return mailActionResult(action, 'needsConfirmation', {
+      error: `gog ${operation} timed out or was cancelled; check ${mailbox} before retrying.`,
+      toolVersion,
+      exitCode: result.exitCode,
+    });
+  }
+  if (result.error) {
+    return mailActionResult(action, 'failed', {
+      error: `gog ${operation} could not start: ${compactStatus(result.error)}`,
+      toolVersion,
+      exitCode: result.exitCode,
+    });
+  }
+  const messageId = extractMailResultId(result.stdout, action.kind);
+  if (result.exitCode === 0 && messageId) {
+    return mailActionResult(action, 'succeeded', { messageId, toolVersion, exitCode: 0 });
+  }
+  if (result.exitCode === 0) {
+    return mailActionResult(action, 'needsConfirmation', {
+      error: `gog ${operation} returned success without a verifiable Gmail id; check ${mailbox} before retrying.`,
+      toolVersion,
+      exitCode: 0,
+    });
+  }
+  const details = compactStatus(result.stderr || result.stdout || '');
+  return mailActionResult(action, 'failed', {
+    error: `gog ${operation} failed with exit code ${result.exitCode ?? 'unknown'}${details ? `: ${details}` : '.'}`,
+    toolVersion,
+    exitCode: result.exitCode,
+  });
+}
+
+export function resolveGogCommand(value = '') {
+  const requested = cleanText(value || process.env.CUSTOMER_MAP_GOG_BIN);
+  const fixedCandidates = process.platform === 'win32'
+    ? []
+    : [
+        '/opt/homebrew/bin/gog',
+        '/usr/local/bin/gog',
+        '/usr/bin/gog',
+        join(homedir(), '.local', 'bin', 'gog'),
+        join(homedir(), 'go', 'bin', 'gog'),
+      ];
+  const candidates = [
+    ...resolveCommandCandidate(requested),
+    ...fixedCandidates,
+    ...pathCommandCandidates(),
+  ];
+  const found = candidates.find(candidate => candidate && existsSync(candidate));
+  if (!found) throw new Error('gog was not found. Install it or pass --gog /absolute/path/to/gog.');
+  return found;
+}
+
+function mailActionResult(value, status, options = {}) {
+  const source = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  const error = options.error || '';
+  const successReply = source.kind === 'saveDraft'
+    ? '邮件已通过 Codex Bridge 的固定 gog 参数保存到 Gmail 草稿。'
+    : '邮件已通过 Codex Bridge 的固定 gog 参数发送。';
+  return {
+    reply: status === 'succeeded' ? successReply : error,
+    subject: '',
+    sendText: '',
+    tag: '',
+    aiNote: '',
+    continue: false,
+    actionReceipt: {
+      kind: source.kind === 'saveDraft' ? 'saveDraft' : 'sendEmail',
+      status,
+      provider: 'gmail',
+      messageId: options.messageId || '',
+      recipient: cleanText(source.recipient).toLowerCase(),
+      occurredAt: status === 'succeeded' ? new Date().toISOString() : '',
+      error,
+      tool: 'gog',
+      toolVersion: options.toolVersion || '',
+      bodyMode: bodyMode(source),
+      bodyHash: cleanText(source.bodyHash).toLowerCase(),
+      actionId: cleanText(source.actionId).toLowerCase(),
+      exitCode: options.exitCode ?? null,
+    },
+  };
+}
+
+async function readGogVersion(command, signal) {
+  if (gogVersionCache.has(command)) return gogVersionCache.get(command);
+  const result = await runProcess(command, ['--version'], { signal, timeoutMs: 10_000 });
+  if (result.timedOut || result.aborted) throw new Error('unable to read gog version before timeout');
+  if (result.error) throw new Error(result.error);
+  const match = /v?(\d+)\.(\d+)\.(\d+)/.exec(result.stdout || result.stderr);
+  if (result.exitCode !== 0 || !match) throw new Error('unable to read gog version');
+  const version = match.slice(1, 4).map(Number);
+  if (compareVersion(version, MIN_GOG_VERSION) < 0) {
+    throw new Error(`gog v${version.join('.')} is older than v${MIN_GOG_VERSION.join('.')}`);
+  }
+  const normalized = version.join('.');
+  gogVersionCache.set(command, normalized);
+  return normalized;
+}
+
+function runProcess(executable, args, { signal, timeoutMs }) {
+  return new Promise(resolveResult => {
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let child;
+    const finish = result => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', abort);
+      resolveResult({ ...result, stdout, stderr });
+    };
+    const terminate = (timedOut, aborted) => {
+      child?.kill();
+      finish({ exitCode: null, timedOut, aborted, error: '' });
+    };
+    const abort = () => terminate(false, true);
+    const timer = setTimeout(() => terminate(true, false), Math.max(1_000, timeoutMs));
+    try {
+      child = spawn(executable, args, { shell: false, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (error) {
+      finish({ exitCode: null, timedOut: false, aborted: false, error: formatError(error) });
+      return;
+    }
+    child.stdout?.on('data', chunk => { stdout = appendBounded(stdout, chunk); });
+    child.stderr?.on('data', chunk => { stderr = appendBounded(stderr, chunk); });
+    child.once('error', error => finish({ exitCode: null, timedOut: false, aborted: false, error: formatError(error) }));
+    child.once('close', code => finish({ exitCode: code, timedOut: false, aborted: false, error: '' }));
+    if (signal?.aborted) abort();
+    else signal?.addEventListener('abort', abort, { once: true });
+  });
+}
+
+function cacheMailResult(cacheKey, action, result) {
+  mailActionResults.set(cacheKey, { bodyHash: action.bodyHash, result });
+  while (mailActionResults.size > 200) mailActionResults.delete(mailActionResults.keys().next().value);
+  return result;
+}
+
+function findMailResultId(value, kind) {
+  if (Array.isArray(value)) {
+    for (const child of value) {
+      const found = findMailResultId(child, kind);
+      if (found) return found;
+    }
+    return '';
+  }
+  if (!value || typeof value !== 'object') return '';
+  const keys = kind === 'saveDraft'
+    ? ['draftId', 'draft_id', 'id', 'messageId', 'message_id']
+    : ['messageId', 'message_id', 'id', 'threadId', 'thread_id'];
+  for (const key of keys) {
+    const candidate = cleanText(value[key]);
+    if (candidate.length >= 6) return candidate;
+  }
+  for (const child of Object.values(value)) {
+    const found = findMailResultId(child, kind);
+    if (found) return found;
+  }
+  return '';
+}
+
+function resolveCommandCandidate(value) {
+  if (!value) return [];
+  if (isAbsolute(value)) return [value];
+  if (value.includes('/') || value.includes('\\')) return [resolve(value)];
+  return pathCommandCandidates(value);
+}
+
+function pathCommandCandidates(command = process.platform === 'win32' ? 'gog.exe' : 'gog') {
+  return cleanText(process.env.PATH)
+    .split(delimiter)
+    .filter(Boolean)
+    .flatMap(pathEntry => {
+      const path = join(pathEntry, command);
+      return process.platform === 'win32' && !/\.(?:exe|cmd)$/i.test(command) ? [path, `${path}.exe`, `${path}.cmd`] : [path];
+    });
+}
+
+function bodyMode(value) {
+  const hasHtml = Boolean(stringValue(value.htmlBody));
+  const hasPlain = Boolean(stringValue(value.plainTextBody));
+  if (hasHtml && hasPlain) return 'body-html+body';
+  if (hasHtml) return 'body-html';
+  if (hasPlain) return 'body';
+  return '';
+}
+
+function compareVersion(left, right) {
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const difference = (left[index] || 0) - (right[index] || 0);
+    if (difference) return difference > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+function appendBounded(current, chunk) {
+  if (current.length >= MAX_PROCESS_OUTPUT_CHARS) return current;
+  return (current + String(chunk)).slice(0, MAX_PROCESS_OUTPUT_CHARS);
+}
+
+function validEmail(value) {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+}
+
+function looksLikeBodyPath(value) {
+  return /^(?:\/dev\/stdin|\/(?:private\/)?tmp\/\S+|[A-Za-z]:\\\S+|file:\/\/\S+)$/i.test(value.trim());
+}
+
+function containsMarkdownTable(value) {
+  return /(?:^|\n)\s*\|?.+\|.+\n\s*\|?\s*:?-{3,}/.test(value);
+}
+
+function compactStatus(value) {
+  const compact = String(value || '').replace(/\s+/g, ' ').trim();
+  return compact.length <= 320 ? compact : `${compact.slice(0, 317).trimEnd()}...`;
+}
+
+function cleanText(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function stringValue(value) {
+  return typeof value === 'string' ? value : '';
+}
+
+function formatError(error) {
+  return error instanceof Error ? error.message : String(error || 'Unknown error');
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "customer-map-codex-bridge",
+  "version": "0.5.0",
+  "description": "Connect a locally authenticated Codex CLI to Customer Map.",
+  "type": "module",
+  "bin": {
+    "customer-map-codex-bridge": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "mail-action.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://www.customer-map.com",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ws": "^8.21.0"
+  }
+}