synabun 1.3.0 → 2.0.0

package/neural-interface/lib/assistant-attachments.js

@@ -0,0 +1,121 @@
+// ═══════════════════════════════════════════
+// SynaBun — Assistant attachments (POST /api/assistant/attachments)
+// ═══════════════════════════════════════════
+//
+// The composer's paperclip takes any file. Images the brains can see and small
+// text files still ride inline in the turn; everything else is streamed to the
+// route in assistant-api.js and saved here, under
+// DATA_HOME/data/attachments/<session>/<upload id>/<name>. The prompt carries
+// the absolute path and the brain reads the file with its own tools, so a PDF
+// reaches Claude, Codex and OpenCode the same way and a worker can be handed
+// the path. Binary bytes never enter a prompt (a raw binary inlined in 2026-03
+// corrupted the Claude NDJSON stream). Files are written, never opened or run.
+
+import { createWriteStream, mkdirSync, rmSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join, resolve, sep } from 'node:path';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+/** The upload cap. The composer checks the same number before it sends. */
+export const ATTACHMENT_MAX_BYTES = 100 * 1024 * 1024;
+// Most file systems cap a name at 255 bytes; this leaves room for the ones that count differently.
+const NAME_MAX_BYTES = 180;
+const WINDOWS_RESERVED = /^(?:con|prn|aux|nul|com\d|lpt\d)(?:\..*)?$/i;
+// Control characters, characters Windows refuses, the backtick (it would break
+// the prompt's code span) and the invisible direction marks that disguise an extension.
+const UNSAFE_CHARS = /[\u0000-\u001f\u007f<>:"|?*`\u200b-\u200f\u202a-\u202e\u2066-\u2069]/g;
+
+function attachmentError(code, message, status) {
+  return Object.assign(new Error(message), { code, status });
+}
+
+/** "The file is larger than 100 MB" — the refusal both the store and the route give. */
+export function tooLargeMessage(maxBytes) {
+  const mb = maxBytes / (1024 * 1024);
+  return `The file is larger than ${Number.isInteger(mb) ? `${mb} MB` : `${maxBytes} bytes`}`;
+}
+
+function clipBytes(text, max) {
+  let out = '';
+  let bytes = 0;
+  for (const ch of text) {
+    const size = Buffer.byteLength(ch);
+    if (bytes + size > max) break;
+    out += ch;
+    bytes += size;
+  }
+  return out;
+}
+
+/**
+ * A name safe to create inside the attachments folder: the last path segment
+ * only, no control or reserved characters, no leading dots ("..", hidden
+ * files), at most 180 bytes with the extension kept. Never empty.
+ */
+export function sanitizeAttachmentName(name) {
+  let base = String(name ?? '').normalize('NFC').split(/[\\/]/).pop() || '';
+  base = base.replace(UNSAFE_CHARS, '').replace(/\s+/g, ' ').replace(/^[\s.]+|[\s.]+$/g, '');
+  if (WINDOWS_RESERVED.test(base)) base = `_${base}`;
+  if (Buffer.byteLength(base) > NAME_MAX_BYTES) {
+    const dot = base.lastIndexOf('.');
+    const ext = dot > 0 && base.length - dot <= 16 ? base.slice(dot) : '';
+    base = `${clipBytes(base.slice(0, base.length - ext.length), NAME_MAX_BYTES - Buffer.byteLength(ext)).trimEnd()}${ext}`;
+  }
+  return base || 'attachment';
+}
+
+/** The per-session folder: the assistant session id when it is a plain id, else "unsorted". */
+export function attachmentSessionFolder(sessionId) {
+  const id = String(sessionId ?? '').trim();
+  return /^[A-Za-z0-9][A-Za-z0-9_-]{0,79}$/.test(id) ? id : 'unsorted';
+}
+
+/** A MIME type as the browser reported it, or application/octet-stream. */
+export function normalizeAttachmentMime(value) {
+  const mime = String(value ?? '').trim().toLowerCase();
+  return mime.length <= 127 && /^[a-z0-9][\w.+-]*\/[\w.+-]+$/.test(mime) ? mime : 'application/octet-stream';
+}
+
+function uploadFolder(ms) {
+  const stamp = new Date(ms).toISOString().slice(0, 19).replace(/[-:]/g, '').replace('T', '-');
+  return `${stamp}-${randomBytes(4).toString('hex')}`;
+}
+
+/**
+ * createAttachmentStore({ root }) → { root, maxBytes, save(source, meta) }.
+ * save() streams `source` (the request) to <root>/<session>/<upload id>/<name>
+ * and resolves { path, name, size, mime } with the absolute path. Past
+ * `maxBytes` it stops, removes what it wrote and rejects with
+ * ATTACHMENT_TOO_LARGE (413); an aborted upload is removed the same way.
+ */
+export function createAttachmentStore({ root, maxBytes = ATTACHMENT_MAX_BYTES, now = Date.now } = {}) {
+  if (!root) throw new Error('createAttachmentStore requires a root');
+  const base = resolve(root);
+
+  async function save(source, { name, sessionId = null, mime = '' } = {}) {
+    const fileName = sanitizeAttachmentName(name);
+    const dir = join(base, attachmentSessionFolder(sessionId), uploadFolder(now()));
+    const path = join(dir, fileName);
+    // The name and the folders are sanitized above; this is the backstop.
+    if (!path.startsWith(`${base}${sep}`)) throw attachmentError('ATTACHMENT_INVALID_NAME', 'Invalid attachment name', 400);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    let size = 0;
+    const cap = new Transform({
+      transform(chunk, _encoding, done) {
+        size += chunk.length;
+        if (size > maxBytes) done(attachmentError('ATTACHMENT_TOO_LARGE', tooLargeMessage(maxBytes), 413));
+        else done(null, chunk);
+      },
+    });
+    try {
+      await pipeline(source, cap, createWriteStream(path, { flags: 'wx', mode: 0o600 }));
+    } catch (error) {
+      rmSync(dir, { recursive: true, force: true });
+      throw error;
+    }
+    return { path, name: fileName, size, mime: normalizeAttachmentMime(mime) };
+  }
+
+  return { root: base, maxBytes, save };
+}

package/neural-interface/lib/assistant-brains/claude.js

@@ -0,0 +1,207 @@
+// ═══════════════════════════════════════════
+// SynaBun — Assistant brain: Claude (Agent SDK via ClaudeSession)
+// ═══════════════════════════════════════════
+//
+// Reuses the sidepanel's ClaudeSession end to end (streaming, permission cards,
+// resume, idle reaping, cost accounting). The session talks to a virtual socket
+// whose outbound packets are already the unified envelope, so they are forwarded
+// verbatim to the assistant UI. Persona, memory hooks, role headers, the account
+// config dir and the budget cap ride in through the ClaudeSession opts.
+
+import { createVirtualSocket } from '../virtual-socket.js';
+import { claudePlanHookDecision, claudePlanPermission, claudeReadOnlyHookDecision, claudeReadOnlyPermission, planDenyMessage, readOnlyDenyMessage } from '../assistant-plan-permissions.js';
+import { planModeInstructions } from '../assistant-persona.js';
+import { isComputerTool } from '../remote-policy.js';
+
+const PERMISSION_MODES = new Set(['default', 'acceptEdits', 'plan', 'bypassPermissions']);
+const APPROVAL_MODES = new Set(['default', 'acceptEdits', 'bypassPermissions']);
+
+/**
+ * The SDK permission mode for an approval mode + the plan flag. Plan mode is
+ * the SDK's 'plan'; approving the plan (ExitPlanMode) returns to the approval
+ * mode — bypass included, which is why the session allows bypass up front.
+ */
+export function claudeSdkMode(approvalMode, planMode) {
+  if (planMode || approvalMode === 'plan') return 'plan';
+  return APPROVAL_MODES.has(approvalMode) ? approvalMode : 'default';
+}
+
+// Never gate these behind a permission card: routing must not wait on an
+// approval prompt, and computer use is fully autonomous (its guards live in
+// the desktop service, not in the host's permission layer).
+export const CLAUDE_BRAIN_ALLOWED_TOOLS = Object.freeze([
+  'mcp__SynaBun__agent_route', 'mcp__SynaBun__agent_catalog', 'mcp__SynaBun__agent_status', 'mcp__SynaBun__agent_read',
+  'mcp__SynaBun__agent_list', 'mcp__SynaBun__agent_wait', 'mcp__SynaBun__agent_usage',
+  'mcp__SynaBun__computer', 'mcp__SynaBun__computer_apps', 'mcp__SynaBun__computer_ax', 'mcp__SynaBun__computer_status',
+]);
+
+/**
+ * The tools pre-approved for this brain. A remote (WhatsApp) brain pre-approves
+ * no computer-use tool, whatever its level: its PreToolUse hook decides each
+ * call (lib/remote-policy.js remoteComputerUse: refused, asked once per turn,
+ * or allowed), so nothing here can let one through.
+ */
+export function claudeBrainAllowedTools(remoteLevel = null) {
+  return remoteLevel ? CLAUDE_BRAIN_ALLOWED_TOOLS.filter((name) => !isComputerTool(name)) : [...CLAUDE_BRAIN_ALLOWED_TOOLS];
+}
+
+/** Bypass as a switch target: always for a desktop session (no remote level), only at autonomous for a remote one. */
+export function claudeBypassAllowed(remoteLevel = null) {
+  return !remoteLevel || remoteLevel === 'autonomous';
+}
+
+export function createClaudeBrain({ session, sink, deps = {}, persona = '', hooks = null, mcpHeaders = {} } = {}) {
+  if (!deps.ClaudeSession) throw new Error('Claude brain requires deps.ClaudeSession');
+  const brain = session.brain || {};
+  const windowId = `assistant-${session.id}`;
+  let providerSessionId = session.providerSessionId || null;
+  let costUsd = 0;
+  let disposed = false;
+  const socket = createVirtualSocket({
+    name: `claude-brain-${session.id}`,
+    onSend: (packet) => {
+      if (disposed || !packet || typeof packet !== 'object') return;
+      if (packet.type === 'event') {
+        const event = packet.event || {};
+        if (event.type === 'system' && event.subtype === 'init' && event.session_id) providerSessionId = event.session_id;
+        if (event.type === 'result') {
+          if (event.session_id) providerSessionId = event.session_id;
+          const cost = Number(event.total_cost_usd);
+          if (Number.isFinite(cost)) costUsd = cost;
+        }
+      }
+      if (packet.type === 'engine') { sink.send({ ...packet, brain: 'claude-code' }); return; }
+      sink.send(packet);
+    },
+  });
+  let approvalMode = APPROVAL_MODES.has(brain.permissionMode) ? brain.permissionMode : 'default';
+  let planMode = brain.planMode === true || brain.permissionMode === 'plan';
+  const permissionMode = claudeSdkMode(approvalMode, planMode);
+  const allowedTools = claudeBrainAllowedTools(deps.remoteLevel);
+  // A remote (WhatsApp) session at the read-only level plans read-only (its level
+  // is read now, so a lowered level applies without a restart); every other
+  // session's plan mode refuses code changes only.
+  const planReadOnly = () => typeof deps.planReadOnly === 'function' && deps.planReadOnly() === true;
+  const inner = new deps.ClaudeSession(socket, {
+    ownerKey: session.id,
+    windowId,
+    sessionId: providerSessionId,
+    model: brain.model || null,
+    effort: brain.effort || null,
+    cwd: brain.cwd || deps.PACKAGE_ROOT || null,
+    permissionMode,
+    // The mode an approved plan continues in, and bypass allowed as a switch
+    // target (the SDK refuses bypassPermissions later without it). A remote
+    // session (WhatsApp) allows it only at the autonomous level.
+    planExitMode: approvalMode,
+    allowDangerouslySkipPermissions: claudeBypassAllowed(deps.remoteLevel),
+    // Plan mode refuses code changes (Edit, Write, MultiEdit, NotebookEdit, a
+    // file-writing MCP tool) whatever the approval mode; reads run without a
+    // card, and everything else is asked as outside plan mode. ExitPlanMode
+    // still waits for the user. The hook refuses before the user's allow rules
+    // run (canUseTool alone never sees an allow-listed tool), subagents included.
+    planPermission: (tool, input, { approvalMode: mode = 'default' } = {}) => (planReadOnly()
+      ? claudeReadOnlyPermission(tool, input)
+      : claudePlanPermission(tool, input, { approvalMode: mode, preApproved: allowedTools })),
+    planHook: (tool, input) => (planReadOnly() ? claudeReadOnlyHookDecision(tool, input) : claudePlanHookDecision(tool, input)),
+    planDenyMessage: (tool) => (planReadOnly() ? readOnlyDenyMessage(tool) : planDenyMessage(tool, { host: 'claude' })),
+    // What plan mode means here, inside the CLI's own plan-mode reminder. A remote
+    // session keeps the CLI's read-only wording: its level can hold plan mode read-only.
+    planModeInstructions: deps.remoteLevel ? undefined : planModeInstructions({ provider: 'claude-code' }),
+    systemPromptAppend: persona || undefined,
+    // User-level settings (global permissions, CLAUDE.md) apply; project hooks
+    // are CLI-oriented (greeting, loop driver, stop nudges) and are not loaded.
+    settingSources: Array.isArray(deps.settingSources) ? deps.settingSources : ['user'],
+    hooks: hooks || undefined,
+    mcpHeaders: {
+      'X-Synabun-Role': 'assistant', 'X-Synabun-Terminal': session.id, 'X-Synabun-Memory-Session': session.id,
+      ...(deps.desktopGrant ? { 'X-Synabun-Desktop-Grant': deps.desktopGrant } : {}),
+      ...mcpHeaders,
+    },
+    // A remote (WhatsApp) session never pre-approves computer use: its PreToolUse hook refuses, asks or allows each call.
+    allowedTools,
+    // The user-level SynaBun hooks run in this CLI too (settingSources 'user').
+    // The marker tells them the brain recalls in-process (assistant-memory.js):
+    // prompt-submit.mjs steps aside (it injected every memory twice and paid Jev
+    // twice) and stop.mjs skips the claim check (a relayed worker "tests pass"
+    // has its evidence in the worker's turn, not here). Hooks read it from env.
+    env: {
+      ...(typeof deps.claudeAccountEnv === 'function' ? deps.claudeAccountEnv(brain.accountId) : {}),
+      SYNABUN_ASSISTANT_SESSION: String(session.id),
+    },
+    maxBudgetUsd: Number(deps.maxBudgetUsd) > 0 ? Number(deps.maxBudgetUsd) : undefined,
+  });
+  sink.send({ type: 'engine', engine: 'sdk', brain: 'claude-code', sdkVersion: deps.sdkVersion || null });
+
+  const handle = (msg) => { if (!disposed) return inner.handleMessage(msg); return undefined; };
+  function applyModes(mode, plan) {
+    if (mode === 'plan') planMode = true;
+    else if (APPROVAL_MODES.has(mode)) approvalMode = mode;
+    if (typeof plan === 'boolean') planMode = plan;
+    // The session's own setter; a session without it (an older bridge, a test double) takes the field.
+    if (typeof inner.setPlanExitMode === 'function') inner.setPlanExitMode(approvalMode);
+    else if (inner.opts && typeof inner.opts === 'object') inner.opts.planExitMode = approvalMode;
+    return claudeSdkMode(approvalMode, planMode);
+  }
+
+  // Per-turn model switch. ClaudeSession._handleQuery pushes the prompt before
+  // calling setModel (the turn can start on the old model) and skips the switch
+  // entirely when its model was null, so the brain switches first itself.
+  async function applyTurnModel(model) {
+    const want = model || null;
+    if (typeof inner.setModel === 'function') {
+      const switched = await inner.setModel(want);
+      if (!switched.ok) sink.send({ type: 'stderr', text: `Model switch failed: ${switched.error}` });
+      return;
+    }
+    if ((inner.model || null) === want) return;
+    if (inner.q?.setModel) {
+      try { await inner.q.setModel(want || undefined); }
+      catch (error) { sink.send({ type: 'stderr', text: `Model switch failed: ${error?.message || error}` }); return; }
+    }
+    inner.model = want; // ensureQuery() reads it when the next query is created
+  }
+
+  return {
+    kind: 'claude-code',
+    async start() { return true; },
+    async sendUserTurn({ text, images = [], cwd = null, model = null, effort = null, permissionMode: mode = null, planMode: plan = null } = {}) {
+      await applyTurnModel(model);
+      const query = { type: 'query', prompt: text, windowId };
+      if (Array.isArray(images) && images.length) query.images = images;
+      if (providerSessionId) query.sessionId = providerSessionId;
+      if (cwd) query.cwd = cwd;
+      if (effort) query.effort = effort;
+      if ((mode && PERMISSION_MODES.has(mode)) || typeof plan === 'boolean') query.permissionMode = applyModes(mode, plan);
+      await handle(query);
+      return true;
+    },
+    async abort() { await handle({ type: 'abort' }); },
+    async setPermissionMode(mode, { planMode: plan = null } = {}) {
+      if (!PERMISSION_MODES.has(mode) && typeof plan !== 'boolean') return;
+      await handle({ type: 'set_permission_mode', mode: applyModes(mode, plan) });
+    },
+    respondControl(requestId, response) { handle({ type: 'control_response', request_id: requestId, response }); },
+    async compact() { await handle({ type: 'compact' }); },
+    async mcpStatus() { await handle({ type: 'mcp_status' }); },
+    async resume(sessionId) { providerSessionId = sessionId || null; inner.sessionId = providerSessionId; if (inner.q) await inner._endQuery?.({ graceful: true }); },
+    async listSessions() { return []; },
+    isBusy() { return !!(inner.inTurn || inner.pendingPerms?.size > 0 || inner.pendingTurns > 0); },
+    // Background agents or scheduled wakeups still running after their turn
+    // ended. Not "busy" (the mailbox may deliver), but disposing would kill them.
+    hasPendingWork() { return !!inner._hasPendingWork?.(); },
+    identity() {
+      return {
+        providerSessionId: inner.sessionId || providerSessionId, providerThreadId: null, accountId: brain.accountId || 'default',
+        model: inner.model || brain.model || null, effort: inner.effort || brain.effort || null, cwd: inner.cwd || brain.cwd || null,
+        costUsd, busy: !!(inner.inTurn || inner.pendingPerms?.size > 0),
+      };
+    },
+    async dispose() {
+      if (disposed) return;
+      disposed = true;
+      try { inner.destroy(); } catch {}
+      socket.close();
+    },
+  };
+}

package/neural-interface/lib/assistant-brains/codex-browser-policy-hook.mjs

@@ -0,0 +1,43 @@
+// SynaBun — Codex PreToolUse hook: the browser policy of an Assistant task run.
+// Installed only on the Codex workers the Assistant dispatches
+// (native-loop-providers.js, createCodexNativeLoopAdapter with runMode "task"),
+// as `codex exec` session flags the user's Codex trusts by hash
+// (lib/assistant-route-gate-codex.js codexBrowserPolicyHook). Reads the
+// PreToolUse payload from stdin and asks lib/browser-tool-policy.js here, with
+// no server round trip; a refusal becomes permissionDecision "deny" with the
+// reason. Script paths resolve against the payload's cwd, else
+// SYNABUN_BROWSER_POLICY_CWD (the run's project). An unreadable payload allows
+// the call: the policy is a speed bump, not a sandbox. A policy module that
+// cannot load fails closed (logged on stderr): shell commands, web search and
+// every MCP tool but SynaBun's are denied with that reason.
+
+let browserToolDenial = null;
+let loadError = null;
+try { ({ browserToolDenial } = await import('../browser-tool-policy.js')); } catch (error) { loadError = error; }
+
+// Codex's shell family and web search, by the names its hooks report.
+const SHELL_OR_WEB = /^(?:bash|shell|shell_command|exec_command|local_shell|container\.exec|unified_exec|web_search|web_search_preview)$/i;
+
+/** The refusal while the policy module is missing, else null. */
+function unloadedDenial(tool) {
+  const synabun = /^mcp__(?:[a-z0-9-]+_)*synabun__/i.test(tool) || /^synabun[_.:/-]/i.test(tool);
+  if (synabun || !(SHELL_OR_WEB.test(tool) || /^mcp__/i.test(tool))) return null;
+  return `SynaBun browser policy: ${tool} was refused — SynaBun's browser policy could not load (${loadError?.message || 'browserToolDenial is missing'}), so no command, web search or other server's tool can be checked for a browser launch. SynaBun's own tools still work. Stop and report this`;
+}
+
+let raw = '';
+try { for await (const chunk of process.stdin) raw += chunk; } catch {}
+let payload = {};
+try { payload = JSON.parse(raw || '{}') || {}; } catch {}
+
+try {
+  const tool = String(payload.tool_name || payload.toolName || payload.tool || '');
+  const input = payload.tool_input && typeof payload.tool_input === 'object' ? payload.tool_input : {};
+  const cwd = (typeof payload.cwd === 'string' && payload.cwd) || process.env.SYNABUN_BROWSER_POLICY_CWD || process.cwd();
+  if (typeof browserToolDenial !== 'function') process.stderr.write(`[SynaBun] browser policy could not load (${loadError?.message || 'browserToolDenial is missing'}); denying shell, web search and other servers' tools\n`);
+  const reason = !tool ? null : typeof browserToolDenial === 'function' ? browserToolDenial(tool, input, { host: 'codex', cwd }) : unloadedDenial(tool);
+  // Codex prints "Command blocked by PreToolUse hook: <reason>. Command: <cmd>", so
+  // the reason goes without its own final period.
+  if (reason) process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason.replace(/[.\s]+$/, '') } }));
+} catch {}
+process.exit(0);

package/neural-interface/lib/assistant-brains/codex-route-gate-hook.mjs

@@ -0,0 +1,56 @@
+// SynaBun — Codex PreToolUse hook for the Assistant's route gate.
+// Installed only on the assistant brain's app-server (session flag, see
+// lib/assistant-route-gate-codex.js). Asks the Neural Interface whether the
+// tool may run; a refusal becomes permissionDecision "deny" with the reason.
+// The call's whole tool_input travels (the remote denylist reads paths from
+// it), marked inputComplete; one too big to send goes as its command/action
+// only, marked incomplete. Any failure (no env, server unreachable, bad reply)
+// allows the call — except in a WhatsApp session (SYNABUN_ROUTE_GATE_REMOTE=1),
+// where a call SynaBun could not check is denied.
+
+const url = process.env.SYNABUN_ROUTE_GATE_URL;
+const session = process.env.SYNABUN_ROUTE_GATE_SESSION;
+const token = process.env.SYNABUN_ROUTE_GATE_TOKEN;
+const remote = process.env.SYNABUN_ROUTE_GATE_REMOTE === '1';
+const MAX_INPUT_BYTES = 256 * 1024;
+const UNCHECKED = 'SynaBun could not check this call, so a WhatsApp session does not run it.';
+
+let raw = '';
+try { for await (const chunk of process.stdin) raw += chunk; } catch {}
+let input = {};
+try { input = JSON.parse(raw || '{}'); } catch {}
+
+/** { input, inputComplete }: the whole tool_input when the host gave one small enough to send. */
+function callArguments(toolInput) {
+  if (!toolInput || typeof toolInput !== 'object' || Array.isArray(toolInput)) return { input: {}, inputComplete: false };
+  let size = Infinity;
+  try { size = Buffer.byteLength(JSON.stringify(toolInput)); } catch {}
+  if (size <= MAX_INPUT_BYTES) return { input: toolInput, inputComplete: true };
+  const subset = {};
+  for (const key of ['command', 'action']) {
+    if (typeof toolInput[key] === 'string' && toolInput[key].length <= 64 * 1024) subset[key] = toolInput[key];
+  }
+  return { input: subset, inputComplete: false };
+}
+// Codex prints "Command blocked by PreToolUse hook: <reason>. Command: <cmd>", so the
+// reason goes without its own final period.
+function deny(reason) {
+  process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: String(reason).replace(/[.\s]+$/, '') } }));
+}
+
+if (url && session && token) {
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ session, token, host: 'codex', tool: String(input.tool_name || input.toolName || input.tool || ''), agent: input.agent_id || null, ...callArguments(input.tool_input) }),
+      signal: AbortSignal.timeout(5000),
+    });
+    const decision = await response.json();
+    if (decision && decision.allow === false) deny(decision.reason || 'SynaBun refused this call.');
+    else if (remote && !(decision && decision.allow === true)) deny(UNCHECKED);
+  } catch {
+    if (remote) deny(UNCHECKED);
+  }
+}
+process.exit(0);

package/neural-interface/lib/assistant-brains/codex.js

@@ -0,0 +1,213 @@
+// ═══════════════════════════════════════════
+// SynaBun — Assistant brain: Codex (app-server via the codex-skin handler)
+// ═══════════════════════════════════════════
+//
+// Drives the existing `handleCodexSkinWebSocket` (accounts, thread lifecycle,
+// approvals, MCP pins, rate limits) through a virtual socket, speaking the
+// sidepanel protocol with a fixed ownership envelope. Packets coming back are
+// translated into the unified envelope; the persona rides as
+// `developerInstructions` on every query (collaborationMode.settings).
+
+import { randomUUID } from 'node:crypto';
+import { createVirtualSocket } from '../virtual-socket.js';
+import { createCodexEnvelopeTranslator, codexControlResponse } from '../assistant-envelope.js';
+import { baseModelId, contextVariantOf } from '../assistant-catalog.js';
+import { codexPlanPermission, codexReadOnlyPermission, planDenyMessage, readOnlyDenyMessage } from '../assistant-plan-permissions.js';
+import { planModeInstructions } from '../assistant-persona.js';
+
+const READY_TIMEOUT_MS = 90_000;
+// Approvals the Codex sidepanel's Auto-accept answers on its own (cdx-requests.js).
+const AUTO_ACCEPT_METHODS = new Set(['item/commandExecution/requestApproval', 'item/fileChange/requestApproval', 'item/permissions/requestApproval']);
+
+/** The assistant's Codex approval mode: 'auto' (auto-accept) or 'default'. Claude's names read as auto. */
+export function codexApprovalMode(mode) {
+  return mode === 'auto' || mode === 'acceptEdits' || mode === 'bypassPermissions' ? 'auto' : 'default';
+}
+
+export function createCodexBrain({ session, sink, deps = {}, persona = '' } = {}) {
+  if (typeof deps.handleCodexSkinWebSocket !== 'function') throw new Error('Codex brain requires deps.handleCodexSkinWebSocket');
+  const brain = session.brain || {};
+  const ownerSessionId = session.id;
+  const connectionEpoch = randomUUID();
+  const windowId = `assistant-${session.id}`;
+  const pendingControls = new Map();
+  let threadId = session.providerThreadId || null;
+  let disposed = false;
+  let readyResolve = null;
+  let readyPromise = null;
+  let turnActive = false;
+  // The query sent whose turn has not started (its requestId). Codex answers a
+  // query it refuses before any turn starts (turn/start rejected, a pending
+  // approval, a turn already running) with an `error` for it and nothing else.
+  let startingRequest = null;
+  let lastTurn = null;
+  let usage = null;
+  // Approval mode and plan mode are independent: plan runs Codex's native plan
+  // collaboration mode (read-only sandbox, so a patch has to ask) and its policy
+  // (codexPlanPermission) declines patches and file-write grants, allows reads,
+  // and leaves every other approval to the approval mode, as outside plan. The
+  // server-side MCP auto-accept is off in plan so every approval reaches it.
+  let approvalMode = codexApprovalMode(brain.permissionMode);
+  let planMode = brain.planMode === true || brain.permissionMode === 'plan';
+  // A remote (WhatsApp) session: Codex cannot ask before ordinary commands, so the
+  // brain is read-only for good — the read-only sandbox (network off) on every
+  // turn, every escalation declined as in plan mode, never auto-accept.
+  const remoteReadOnly = deps.remoteReadOnly === true;
+  const readOnlyTurn = () => (remoteReadOnly ? { sandboxMode: 'read-only' } : {});
+  function applyModes(mode, plan) {
+    if (mode === 'plan') planMode = true;
+    else if (mode) approvalMode = codexApprovalMode(mode);
+    if (typeof plan === 'boolean') planMode = plan;
+  }
+  // Route gate: 'hook' when the app-server runs the trusted PreToolUse hook,
+  // 'reactive' otherwise (the runtime interrupts ungated tool starts).
+  let gateMode = deps.routeGate ? 'reactive' : null;
+  // Whether the last query asked for Codex's plan collaboration mode: only that
+  // turn's proposed plan is a plan (the translator reads it as the turn starts).
+  let queryPlanMode = false;
+
+  const translator = createCodexEnvelopeTranslator({
+    priceUsage: typeof deps.priceCodexUsage === 'function' ? deps.priceCodexUsage : null,
+    brain: { cwd: brain.cwd || null, model: brain.model || null },
+    planTurn: () => queryPlanMode,
+    emit: (packet) => {
+      if (disposed) return;
+      // A WhatsApp session's brain answers every approval read-only (anything that
+      // would leave the read-only sandbox is declined). Plan mode declines code
+      // changes, allows reads, and hands the rest to the approval mode (auto
+      // allows it here, default leaves it to a card below).
+      let planned = null;
+      if (packet.type === 'control_request') {
+        if (remoteReadOnly) planned = codexReadOnlyPermission(packet);
+        else if (planMode) planned = codexPlanPermission(packet, { approvalMode });
+      }
+      if (planned) {
+        const method = packet.request?.brain_native?.method || packet.request?.method || '';
+        const tool = packet.request?.brain_native?.params?._meta?.tool_name || packet.request?.tool_name || 'request';
+        const response = planned === 'allow'
+          ? { behavior: 'allow', ...(!remoteReadOnly && approvalMode === 'auto' ? { always: true } : {}) }
+          : { behavior: 'deny', decline: true, message: remoteReadOnly ? readOnlyDenyMessage(tool) : planDenyMessage(tool, { host: 'codex' }) };
+        send({ type: 'server_request_response', ...codexControlResponse(packet, response) });
+        sink.send({ type: 'stderr', text: `${planMode ? 'Plan mode' : 'Read-only (WhatsApp)'}: ${planned === 'allow' ? 'allowed' : 'declined'} ${String(method).split('/').slice(1, -1).join('/') || 'request'} ${tool}${planned === 'allow' ? '' : remoteReadOnly ? ' (read-only)' : ' (no code changes)'}` });
+        return;
+      }
+      if (packet.type === 'control_request' && !planMode && !remoteReadOnly && approvalMode === 'auto' && AUTO_ACCEPT_METHODS.has(packet.request?.brain_native?.method || packet.request?.method)) {
+        // Auto-accept: approve at once (for the session when offered), as the Codex sidepanel does.
+        send({ type: 'server_request_response', ...codexControlResponse(packet, { behavior: 'allow', always: true }) });
+        sink.send({ type: 'stderr', text: `Auto-accepted: ${String(packet.request?.brain_native?.method || packet.request?.method).split('/').slice(1, -1).join('/')}` });
+        return;
+      }
+      if (packet.type === 'control_request') pendingControls.set(packet.request_id, packet);
+      // That error is the refused query's only answer: its turn, which never started, ends here.
+      const refused = packet.type === 'error' && !!startingRequest && packet.requestId === startingRequest;
+      if (packet.type === 'done' || packet.type === 'aborted' || packet.type === 'error') {
+        if (packet.type !== 'error') { turnActive = false; startingRequest = null; }
+        for (const [id, pending] of pendingControls) if (pending.request?.provider === 'codex') pendingControls.delete(id);
+      }
+      sink.send(packet);
+      if (refused) {
+        startingRequest = null;
+        turnActive = false;
+        sink.send({ type: 'done', code: 1 });
+      }
+    },
+    // The thread hook is metering: a throw there must not leave the brain waiting for ready.
+    onThread: (id) => { if (id) { threadId = id; try { deps.onCodexThread?.(id); } catch {} } readyResolve?.(); },
+    onTurnStart: () => { turnActive = true; startingRequest = null; },
+    onTurnEnd: (info) => { turnActive = false; lastTurn = info; },
+    onUsage: (value) => { usage = value; try { deps.onCodexUsage?.(); } catch {} },
+  });
+  const socket = createVirtualSocket({
+    name: `codex-brain-${session.id}`,
+    onSend: (packet) => {
+      if (disposed || !packet || typeof packet !== 'object') return;
+      if (packet.type === 'ready') readyResolve?.();
+      translator.handle(packet);
+    },
+  });
+  deps.handleCodexSkinWebSocket(socket);
+  const send = (message) => socket.receive({ ...message, sessionId: ownerSessionId, connectionEpoch });
+  // A query: busy from before it is sent (a refusal may come back at once) until its turn ends or Codex refuses it.
+  const sendQuery = (message) => {
+    const requestId = randomUUID();
+    startingRequest = requestId;
+    turnActive = true;
+    send({ ...message, type: 'query', requestId });
+  };
+  sink.send({ type: 'engine', engine: 'codex', brain: 'codex' });
+
+  let startPromise = null;
+  function start() {
+    if (!startPromise) startPromise = boot();
+    return startPromise;
+  }
+  async function boot() {
+    if (disposed) throw new Error('Codex brain disposed');
+    if (readyPromise) return readyPromise;
+    let routeGate = null;
+    if (typeof deps.routeGate === 'function') {
+      try { routeGate = await deps.routeGate(); } catch { routeGate = null; }
+      gateMode = routeGate ? 'hook' : 'reactive';
+    }
+    if (disposed) throw new Error('Codex brain disposed');
+    readyPromise = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('Codex app-server did not become ready')), READY_TIMEOUT_MS);
+      timer.unref?.();
+      readyResolve = () => { clearTimeout(timer); resolve(true); };
+    });
+    send({
+      type: 'bootstrap', windowId, accountId: brain.accountId || 'default', mcpProfile: brain.mcpProfile || null,
+      cwd: brain.cwd || deps.PACKAGE_ROOT || undefined, threadId: threadId || null, role: 'assistant',
+      // Unlocks the capability-gated `computer` MCP group for this brain only.
+      desktopGrant: deps.desktopGrant || null,
+      ...(routeGate ? { routeGate } : {}),
+    });
+    return readyPromise;
+  }
+
+  return {
+    kind: 'codex',
+    start,
+    async sendUserTurn({ text, images = [], cwd = null, model = null, effort = null, permissionMode: mode = null, planMode: plan = null } = {}) {
+      await start();
+      applyModes(mode, plan);
+      queryPlanMode = planMode;
+      // "<id>[extended]" = the model at its extended context window (the sidepanel's contextMode).
+      const picked = model || brain.model || null;
+      sendQuery({
+        prompt: text, images: Array.isArray(images) && images.length ? images : undefined,
+        cwd: cwd || brain.cwd || deps.PACKAGE_ROOT || undefined, model: picked ? baseModelId(picked) : null, effort: effort || brain.effort || null,
+        contextMode: contextVariantOf(picked) === 'extended' ? 'extended' : undefined,
+        threadId: threadId || null, autoAccept: approvalMode === 'auto' && !planMode && !remoteReadOnly, planMode,
+        // A plan turn carries what plan mode means here (a WhatsApp session's read-only brain does not).
+        developerInstructions: [persona, planMode && !remoteReadOnly ? planModeInstructions({ provider: 'codex' }) : ''].filter(Boolean).join('\n\n') || null,
+        windowId, ...readOnlyTurn(),
+      });
+      return true;
+    },
+    async abort() { send({ type: 'interrupt', threadId: threadId || null }); },
+    async setPermissionMode(mode, { planMode: plan = null } = {}) { applyModes(mode, plan); sink.send({ type: 'mode_changed', mode: approvalMode, planMode }); },
+    respondControl(requestId, response) {
+      const pending = pendingControls.get(String(requestId));
+      if (!pending) { sink.send({ type: 'error', message: `No pending Codex request ${requestId}` }); return; }
+      pendingControls.delete(String(requestId));
+      send({ type: 'server_request_response', ...codexControlResponse(pending, response) });
+    },
+    // A turn of its own: busy until its `done`, like sendUserTurn (the runtime starts nothing meanwhile).
+    async compact() { queryPlanMode = false; sendQuery({ prompt: '/compact', threadId: threadId || null, cwd: brain.cwd || undefined, windowId, ...readOnlyTurn() }); },
+    async mcpStatus() { send({ type: 'mcp_status' }); },
+    async resume(id) { if (!id) return; threadId = id; send({ type: 'thread_resume', threadId: id, cwd: brain.cwd || undefined }); },
+    async listSessions() { return []; },
+    isBusy() { return turnActive || pendingControls.size > 0; },
+    get gateMode() { return gateMode; },
+    identity() {
+      return { providerSessionId: threadId, providerThreadId: threadId, accountId: brain.accountId || 'default', model: brain.model || null, effort: brain.effort || null, cwd: brain.cwd || null, usage, lastTurn, busy: turnActive };
+    },
+    async dispose() {
+      if (disposed) return;
+      disposed = true;
+      try { send({ type: 'release', windowId }); } catch {}
+      socket.close();
+    },
+  };
+}