@chatpanel/bridge 0.10.41 → 0.11.0

package/src/cli-errors.js

@@ -7,6 +7,10 @@
 //
 // The failure is also usually not ChatPanel's to fix. Saying whose it is, and naming the
 // server, is the difference between "something broke" and "re-auth that server".
+//
+// `mcpFailure` is the machine-readable half of the same knowledge: mcp-quarantine.js reads
+// it to DROP the offending server and run again, so the common cases never reach a human at
+// all. One set of patterns serves both — a second copy would drift.
 
 const NOISE = [
   /^\s*$/,
@@ -27,19 +31,79 @@ export function stripMarkup(text) {
     .replace(/[ \t]+/g, ' ');
 }
 
-// The named causes worth translating. Each returns a sentence that says what to DO.
-function knownCause(text) {
-  const server = /refresh OAuth tokens for server ([\w.-]+)/i.exec(text)?.[1]
-    || /server ['"]?([\w.-]+)['"]? (?:requires|failed) auth/i.exec(text)?.[1];
-  if (/refresh token (?:does not exist|was rejected)|invalid_grant/i.test(text)) {
-    return `${server ? `its MCP server "${server}"` : 'one of its MCP servers'} needs re-authentication — its saved OAuth token has expired or been revoked. Re-login to that server in the agent's own config; ChatPanel can't refresh it.`;
-  }
-  if (/invalid_token|AuthRequired|www-authenticate|\b401\b/i.test(text)) {
-    return `${server ? `its MCP server "${server}"` : 'one of its MCP servers'} rejected the agent's token (401/invalid_token). Re-authenticate that server in the agent, then retry.`;
+// Which server the output blames, if it names one. Codex and Claude Code phrase this several
+// ways, so try each; a name we cannot read means there is nothing to disable, which is why
+// every caller must tolerate `null`.
+const SERVER_PATTERNS = [
+  /(?:refresh OAuth tokens|refresh tools) for (?:MCP )?server ['"`]?([\w.-]+)['"`]?/i,
+  /MCP server ['"`]([\w.-]+)['"`]/i,
+  /server ['"]?([\w.-]+)['"]? (?:requires|failed) auth/i,
+];
+export function mcpServerName(text) {
+  for (const re of SERVER_PATTERNS) {
+    const name = re.exec(String(text || ''))?.[1];
+    if (name) return name;
   }
-  if (/HTTP 403|\b403\b/.test(text)) {
-    return `${server ? `its MCP server "${server}"` : 'one of its MCP servers'} returned 403 and an error page — that server is refusing requests or is temporarily down. This is outside ChatPanel; retry when it recovers.`;
+  return null;
+}
+
+// The named MCP causes worth translating. `say` is the sentence for a human; `short` is the
+// clause used when we skip the server and carry on. Order matters — specific before generic.
+const MCP_CAUSES = [
+  {
+    kind: 'expired',
+    test: /refresh token (?:does not exist|was rejected)|invalid_grant/i,
+    short: 'its saved login has expired',
+    say: (who) => `${who} needs re-authentication — its saved OAuth token has expired or been revoked. Re-login to that server in the agent's own config; ChatPanel can't refresh it.`,
+  },
+  {
+    kind: 'unauthorized',
+    test: /invalid_token|AuthRequired|www-authenticate|\b401\b/i,
+    short: 'it rejected the agent\'s token',
+    say: (who) => `${who} rejected the agent's token (401/invalid_token). Re-authenticate that server in the agent, then retry.`,
+  },
+  {
+    kind: 'refused',
+    test: /HTTP 403|\b403\b/,
+    short: 'it is refusing requests',
+    say: (who) => `${who} returned 403 and an error page — that server is refusing requests or is temporarily down. This is outside ChatPanel; retry when it recovers.`,
+  },
+  {
+    // The off-network case: a VPN-only server seen from a cafe. Only counted when the text
+    // is talking about MCP at all, so an ordinary provider timeout is not misread as this.
+    kind: 'unreachable',
+    requiresMcpContext: true,
+    test: /handshaking with MCP server failed|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|dns error|connection (?:refused|reset)|failed to start and is unavailable|network is unreachable/i,
+    short: 'it could not be reached',
+    say: (who) => `${who} could not be reached — it is offline, or needs a network (VPN) this machine is not on. ChatPanel can't reach it either; retry when it is available.`,
+  },
+];
+
+/**
+ * Classify an MCP-server failure in an agent's output.
+ * @returns {{server: string|null, kind: string, short: string, say: string}|null}
+ */
+export function mcpFailure(text) {
+  const raw = String(text || '');
+  const server = mcpServerName(raw);
+  const hasMcpContext = /\bmcp\b/i.test(raw) || !!server;
+  for (const cause of MCP_CAUSES) {
+    if (cause.requiresMcpContext && !hasMcpContext) continue;
+    if (!cause.test.test(raw)) continue;
+    return {
+      server,
+      kind: cause.kind,
+      short: cause.short,
+      say: cause.say(server ? `its MCP server "${server}"` : 'one of its MCP servers'),
+    };
   }
+  return null;
+}
+
+// The named causes worth translating. Each returns a sentence that says what to DO.
+function knownCause(text) {
+  const mcp = mcpFailure(text);
+  if (mcp) return mcp.say;
   if (/ENOENT|command not found/i.test(text)) return 'the command could not be found on PATH.';
   return null;
 }

package/src/engines/claude.js

@@ -49,6 +49,37 @@ const IDLE_MS = Number(process.env.CHATPANEL_CLAUDE_TIMEOUT_MS) || 180_000;
 // gated behind the agent's permission mode.
 const READONLY_TOOLS = ['Read', 'Grep', 'Glob', 'WebFetch', 'WebSearch', 'TodoWrite', 'Task'];
 
+// A remote (channel) caller declares the actor's trust tier via options.reach. Unlike
+// permissionMode (which a local, already-trusted UI chooses), reach is a CEILING enforced HERE
+// at the trust boundary — a paired-but-prompt-injected phone cannot exceed its tier no matter
+// what the message says. This is the tool-authorization half of feature-f7 §7; pairing proves
+// WHO, this constrains WHAT.
+//
+// Posture (security-first): the exfil chain needs read-a-secret AND an egress to send it. We cut
+// the egress on every capped tier by dropping web tools, so even machine-wide reads can't phone
+// home; writes/shell are never granted to a capped tier.
+//   device  — conversational only: no filesystem, no web, no writes/shell.
+//   trusted — machine-wide READ (inspect your own files/projects), but NO web and NO writes/shell.
+//   any     — no cap here (operator/local console); falls through to permissionMode below.
+const CHANNEL_ALLOW = Object.freeze({
+  device: Object.freeze(['TodoWrite', 'Task']),
+  trusted: Object.freeze(['Read', 'Grep', 'Glob', 'TodoWrite', 'Task']),
+});
+// Belt-and-suspenders: the allow-list already omits these, but we also forbid them explicitly so
+// a capped turn can never reach shell, writes, or a network egress even via an MCP alias.
+const CHANNEL_DENY = Object.freeze(['Bash', 'Edit', 'Write', 'WebFetch', 'WebSearch']);
+
+/**
+ * Tool policy for a channel/remote caller. Returns { allow, deny } for a capped tier, or null
+ * when reach is absent or 'any' (no cap — the existing permissionMode logic applies). An unknown
+ * tier is treated as the MOST restrictive ('device'), never as "no cap" — fail closed.
+ */
+export function channelToolPolicy(reach) {
+  if (!reach || reach === 'any') return null;
+  const allow = CHANNEL_ALLOW[reach] || CHANNEL_ALLOW.device;
+  return { allow: [...allow], deny: [...CHANNEL_DENY] };
+}
+
 let lastReason = 'Claude Code not found.';
 let lastProbe = 0;
 let cachedOk = false;
@@ -272,10 +303,19 @@ export async function chat({ messages, system, options, images }, emit, { signal
     mcpAllow.push(...mcpConfig.allowedTools);
   }
 
+  // A remote (channel) caller's reach tier caps the toolset and OVERRIDES permissionMode: a
+  // capped tier never gets --permission-mode, so writes/shell stay denied headlessly even if a
+  // message (or a bug upstream) asked to escalate. Local callers (no reach) keep the existing
+  // permissionMode behavior unchanged.
+  const channelPolicy = channelToolPolicy(options.reach);
+  if (channelPolicy) {
+    args.push('--allowedTools', ...channelPolicy.allow, ...mcpAllow);
+    args.push('--disallowedTools', ...channelPolicy.deny);
+  }
   // Gate writes/shell behind the chosen mode; otherwise restrict to read-only
   // tools so headless runs never block on an approval prompt. The relayed browser
   // tools are always pre-allowed (the user explicitly armed them this turn).
-  if (permissionMode === 'bypassPermissions') args.push('--permission-mode', 'bypassPermissions');
+  else if (permissionMode === 'bypassPermissions') args.push('--permission-mode', 'bypassPermissions');
   else if (permissionMode === 'acceptEdits') {
     args.push('--permission-mode', 'acceptEdits');
     if (mcpAllow.length) args.push('--allowedTools', ...mcpAllow);

package/src/engines/codex.js

@@ -25,6 +25,7 @@ import { buildCliPrompt } from './prompt.js';
 import { pushExtraArgs, FORBIDDEN } from './args.js';
 import { resolveWorkdir } from '../workdir.js';
 import { summarizeCliError } from '../cli-errors.js';
+import { disabledMcpServers, planMcpRetry, quarantine } from '../mcp-quarantine.js';
 
 // Idle timeout: re-armed on every stdout/stderr chunk, so a long run that keeps
 // streaming never trips it — only true silence does. Override with
@@ -117,6 +118,40 @@ export function codexMcpConfigArgs(mcp) {
   return args;
 }
 
+// Which MCP servers this Codex actually has configured.
+//
+// READ THIS BEFORE TOUCHING codexDisableArgs. `-c mcp_servers.X.enabled=false` for a name
+// that is NOT already in config.toml does not disable anything — it DEFINES a new server
+// that has no transport, and Codex then refuses to start at all:
+//     Error: failed to load bootstrap configuration
+//     Caused by: invalid transport in `mcp_servers.does_not_exist`
+// So a stale quarantine entry, or a typo in the user's deny list, would break EVERY run —
+// strictly worse than the failure this feature exists to fix. We therefore only ever disable
+// a server we can see, and a name we cannot see is left alone (a no-op, never a break).
+//
+// Read from config.toml — instant, and the same source listModels() already reads — rather
+// than shelling out to `codex mcp list --json`, which is authoritative but costs ~0.8s on
+// every single turn.
+export function configuredMcpServers(home) {
+  try {
+    const cfg = readFileSync(path.join(home, 'config.toml'), 'utf8');
+    const names = new Set();
+    for (const m of cfg.matchAll(/^\s*\[mcp_servers\.([A-Za-z0-9_-]+)\s*[.\]]/gm)) names.add(m[1]);
+    return names;
+  } catch {
+    return new Set(); // no config (or the isolated home) — there is nothing to disable
+  }
+}
+
+// Turn off servers from the user's own config.toml for THIS RUN only — never by editing
+// their file. Names are validated upstream (mcp-quarantine.js) and filtered against
+// configuredMcpServers by the caller, which is what makes it safe to interpolate one into a
+// `-c` override key; `-c` is otherwise blocked in extraArgs precisely because it reaches
+// config that matters.
+export function codexDisableArgs(names = []) {
+  return names.flatMap((name) => ['-c', `mcp_servers.${name}.enabled=false`]);
+}
+
 // Write base64 data-URL images to temp files so `codex exec -i <file>` can
 // attach them to the prompt as vision input. Returns the paths (caller cleans up).
 async function writeImages(images, tag) {
@@ -132,54 +167,15 @@ async function writeImages(images, tag) {
   return files;
 }
 
-export async function chat({ messages, system, options, images }, emit, { signal } = {}) {
-  const tag = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
-  const outFile = path.join(os.tmpdir(), `chatpanel-codex-${tag}.txt`);
-  const imageFiles = await writeImages(images, tag);
-  const cleanupImages = () => imageFiles.forEach((f) => unlink(f).catch(() => {}));
-
-  const cwd = resolveWorkdir(options.workingDir);
-  const args = ['exec', '--json', '--skip-git-repo-check', '-o', outFile];
-  // Headless exec has no human to approve actions. With MCP/browser tools armed
-  // Codex would otherwise raise an approval prompt it can't show — and cancel the
-  // tool call. So in bypassPermissions (full autonomy, what "Act on page" needs)
-  // use the all-in bypass flag, which also clears MCP-tool approval. Lower modes
-  // keep the sandbox + never-ask, which auto-runs within bounds.
-  if (options.permissionMode === 'bypassPermissions') {
-    args.push('--dangerously-bypass-approvals-and-sandbox');
-  } else {
-    const sandbox = options.permissionMode === 'acceptEdits' ? 'workspace-write' : 'read-only';
-    args.push('-s', sandbox, '-c', 'approval_policy=never');
-  }
-  if (REASONING) args.push('-c', `model_reasoning_effort=${REASONING}`);
-  // Ask Codex to emit reasoning SUMMARIES so the panel can stream the model's thinking.
-  // Additive + safe: a no-op for models/providers that don't produce summaries (e.g. some
-  // hosted models expose none), and cheap at the default effort. forwardEvent renders them.
-  args.push('-c', 'model_reasoning_summary=auto');
-  // Browser tools: register the bridge's MCP server as a stdio MCP server (the
-  // bridge binary in --mcp-stdio mode), so Codex can call our page-action tools.
-  // `-c key=value` parses value as TOML; JSON.stringify yields valid TOML here.
-  args.push(...codexMcpConfigArgs(options.mcp));
-  if (options.model) args.push('-m', options.model);
-  // Drop caller extras that would re-open the sandbox/approval boundary (shared sanitizer).
-  pushExtraArgs(args, options.extraArgs, FORBIDDEN.codex, emit);
-  for (const f of imageFiles) args.push('-i', f); // attach images to the initial prompt
-  args.push('-');
-
-  // Default: use the user's skills/config. Opt-out → isolated home.
-  const useLocal = options.useLocalConfig !== false;
-  const env = { ...process.env };
-  if (!useLocal) {
-    const home = ensureIsolatedHome();
-    if (home) env.CODEX_HOME = home;
-  }
-
-  await new Promise((resolve, reject) => {
+// A single `codex exec` attempt. Resolves with how it ended rather than emitting the final
+// message itself, so the caller can decide whether the run is worth ATTEMPTING AGAIN — the
+// terminal delta/done belongs to whichever attempt actually answered.
+function runCodex({ args, cwd, env, prompt, outFile, emit, signal }) {
+  return new Promise((resolve, reject) => {
     let child;
     try {
       child = spawn('codex', args, { cwd, stdio: ['pipe', 'pipe', 'pipe'], env, ...spawnGroupOpts });
     } catch (e) {
-      cleanupImages();
       return reject(new Error(`Failed to start codex: ${e.message}`));
     }
 
@@ -187,6 +183,13 @@ export async function chat({ messages, system, options, images }, emit, { signal
 
     let stdout = '';
     let stderr = '';
+    // Retrying is only honest while nothing the user can see has been produced. Status lines
+    // are ours and are replaceable; a delta, a tool call or a reasoning summary is not.
+    let streamed = false;
+    const relay = (ev) => {
+      if (ev?.type !== 'status') streamed = true;
+      emit(ev);
+    };
     // Per-run event state: correlate a command's started/completed events and emit each
     // reasoning summary once (Codex sends the same item id across item.started/updated/completed).
     const evState = { started: new Set(), reasoned: new Set(), n: 0 };
@@ -209,7 +212,7 @@ export async function chat({ messages, system, options, images }, emit, { signal
         stdout = stdout.slice(nl + 1);
         if (!line.startsWith('{')) continue;
         try {
-          forwardEvent(JSON.parse(line), emit, evState);
+          forwardEvent(JSON.parse(line), relay, evState);
         } catch {
           /* not a JSON event line */
         }
@@ -219,7 +222,6 @@ export async function chat({ messages, system, options, images }, emit, { signal
     child.on('error', (e) => {
       clearTimeout(idleTimer);
       detach();
-      cleanupImages();
       reject(e);
     });
     child.on('close', async (code) => {
@@ -232,22 +234,98 @@ export async function chat({ messages, system, options, images }, emit, { signal
         /* no message file */
       }
       unlink(outFile).catch(() => {});
-      cleanupImages();
-      if (signal?.aborted) { resolve(); return; } // Stop pressed — end quietly, no error
-      if (code === 0) {
-        emit({ type: 'delta', text: text || '(no output)' });
-        emit({ type: 'done', text: '' });
-        resolve();
-      } else {
-        reject(new Error(summarizeCliError('Codex', code, stderr)));
-      }
+      resolve({ code, stderr, text, streamed });
     });
 
-    child.stdin.write(buildCliPrompt(messages, system));
+    child.stdin.write(prompt);
     child.stdin.end();
   });
 }
 
+export async function chat({ messages, system, options, images }, emit, { signal } = {}) {
+  const tag = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const outFile = path.join(os.tmpdir(), `chatpanel-codex-${tag}.txt`);
+  const imageFiles = await writeImages(images, tag);
+  const cleanupImages = () => imageFiles.forEach((f) => unlink(f).catch(() => {}));
+
+  const cwd = resolveWorkdir(options.workingDir);
+  // Sanitized once, not per attempt — pushExtraArgs emits a status when it drops something,
+  // and a retry must not say it twice.
+  const extraArgs = [];
+  pushExtraArgs(extraArgs, options.extraArgs, FORBIDDEN.codex, emit);
+
+  const buildArgs = (disabled) => {
+    const args = ['exec', '--json', '--skip-git-repo-check', '-o', outFile];
+    // Headless exec has no human to approve actions. With MCP/browser tools armed
+    // Codex would otherwise raise an approval prompt it can't show — and cancel the
+    // tool call. So in bypassPermissions (full autonomy, what "Act on page" needs)
+    // use the all-in bypass flag, which also clears MCP-tool approval. Lower modes
+    // keep the sandbox + never-ask, which auto-runs within bounds.
+    if (options.permissionMode === 'bypassPermissions') {
+      args.push('--dangerously-bypass-approvals-and-sandbox');
+    } else {
+      const sandbox = options.permissionMode === 'acceptEdits' ? 'workspace-write' : 'read-only';
+      args.push('-s', sandbox, '-c', 'approval_policy=never');
+    }
+    if (REASONING) args.push('-c', `model_reasoning_effort=${REASONING}`);
+    // Ask Codex to emit reasoning SUMMARIES so the panel can stream the model's thinking.
+    // Additive + safe: a no-op for models/providers that don't produce summaries (e.g. some
+    // hosted models expose none), and cheap at the default effort. forwardEvent renders them.
+    args.push('-c', 'model_reasoning_summary=auto');
+    // Browser tools: register the bridge's MCP server as a stdio MCP server (the
+    // bridge binary in --mcp-stdio mode), so Codex can call our page-action tools.
+    // `-c key=value` parses value as TOML; JSON.stringify yields valid TOML here.
+    args.push(...codexMcpConfigArgs(options.mcp));
+    // ...and the other direction: the user's own servers we've been told to leave out.
+    args.push(...codexDisableArgs(disabled));
+    if (options.model) args.push('-m', options.model);
+    // Drop caller extras that would re-open the sandbox/approval boundary (shared sanitizer).
+    args.push(...extraArgs);
+    for (const f of imageFiles) args.push('-i', f); // attach images to the initial prompt
+    args.push('-');
+    return args;
+  };
+
+  // Default: use the user's skills/config. Opt-out → isolated home.
+  const useLocal = options.useLocalConfig !== false;
+  const env = { ...process.env };
+  if (!useLocal) {
+    const home = ensureIsolatedHome();
+    if (home) env.CODEX_HOME = home;
+  }
+
+  const ownServer = options.mcp?.serverName || 'chatpanel_browser';
+  // Only servers Codex already knows about can be switched off — see configuredMcpServers.
+  const known = configuredMcpServers(env.CODEX_HOME || process.env.CODEX_HOME || path.join(os.homedir(), '.codex'));
+  let disabled = disabledMcpServers('codex', options, [ownServer]).filter((n) => known.has(n));
+  const prompt = buildCliPrompt(messages, system);
+  const attempt = () => runCodex({ args: buildArgs(disabled), cwd, env, prompt, outFile, emit, signal });
+
+  try {
+    let result = await attempt();
+
+    // The failure this exists for: one of the user's OWN MCP servers could not authenticate
+    // or could not be reached, and took a turn with it that never needed that server. Drop it
+    // and run again — once, out loud, and only while nothing has been streamed.
+    if (!signal?.aborted && result.code !== 0 && !result.streamed) {
+      const drop = planMcpRetry({ agent: 'codex', text: result.stderr, protect: [ownServer], already: disabled });
+      if (drop && known.has(drop.server)) {
+        quarantine('codex', drop.server);
+        emit({ type: 'status', text: `MCP server "${drop.server}" failed to load — ${drop.short}. Skipping it and retrying.` });
+        disabled = [...disabled, drop.server];
+        result = await attempt();
+      }
+    }
+
+    if (signal?.aborted) return; // Stop pressed — end quietly, no error
+    if (result.code !== 0) throw new Error(summarizeCliError('Codex', result.code, result.stderr));
+    emit({ type: 'delta', text: result.text || '(no output)' });
+    emit({ type: 'done', text: '' });
+  } finally {
+    cleanupImages();
+  }
+}
+
 // Translate Codex `exec --json` events into the bridge's streaming vocabulary the panel
 // renders richly. Codex sends item.started (in_progress) then item.completed for each item,
 // reusing the item id — so we correlate a tool's start/done by that id and show its command,

package/src/events/capability.js

@@ -0,0 +1,134 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-events/capability.js (npm @chatpanel/events).
+// Edit there, then run: npm run sync:events
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve.
+
+// The capability signature — one call shape a rule, a schedule, the user or a model all
+// invoke identically, through one policy path.
+//
+// `actor` is the field that makes capabilities turn-independent; it is the whole of the
+// "capabilities are not turn-shaped" principle expressed as data rather than as a
+// subsystem.
+//
+// `requirements` is what the router dispatches on: not "which model" but "what must be
+// true". {maxLatencyMs:100, deterministic:true, egress:'none'} selects class R or M on a
+// host that can realize it — or REFUSES. Silently exceeding a declared budget is the
+// failure mode this exists to prevent.
+
+import { CLASSES, EFFECTS, EGRESS, ACTOR_KINDS, SCOPE_KINDS, EventError } from './event.js';
+import { DATA_SCOPES } from './scopes.js';
+import { validateView } from './view.js';
+
+export { DATA_SCOPES } from './scopes.js';
+
+const str = (v) => typeof v === 'string' && v.length > 0;
+const strs = (v, allowed = null) => Array.isArray(v) && v.every((x) => str(x) && (!allowed || allowed.includes(x)));
+
+/**
+ * Validate a capability DECLARATION — the static surface a reviewer, a user or an admin
+ * approves BEFORE the capability runs. Everything here is readable without executing
+ * anything, which is what makes load-time approval possible.
+ */
+export function validateCapability(c) {
+  if (!c || typeof c !== 'object') throw new EventError('SHAPE', 'capability must be an object');
+  if (!str(c.id)) throw new EventError('SHAPE', 'capability.id required');
+  if (!str(c.version)) throw new EventError('SHAPE', 'capability.version required');
+  if (!CLASSES.includes(c.class)) throw new EventError('SHAPE', `capability.class must be one of ${CLASSES}`);
+  if (!strs(c.requires)) throw new EventError('SHAPE', 'capability.requires must be string[]');
+  if (!strs(c.provides)) throw new EventError('SHAPE', 'capability.provides must be string[]');
+  if (!strs(c.reads, DATA_SCOPES)) throw new EventError('SHAPE', `capability.reads must be within ${DATA_SCOPES}`);
+  if (!strs(c.writes, DATA_SCOPES)) throw new EventError('SHAPE', `capability.writes must be within ${DATA_SCOPES}`);
+  if (!EGRESS.includes(c.egress)) throw new EventError('SHAPE', `capability.egress must be one of ${EGRESS}`);
+  if (!EFFECTS.includes(c.effects)) throw new EventError('SHAPE', `capability.effects must be one of ${EFFECTS}`);
+  if (typeof c.invoke !== 'function') throw new EventError('SHAPE', 'capability.invoke required');
+  if (typeof c.disclose !== 'function') throw new EventError('SHAPE', 'capability.disclose required');
+  if (!c.output || typeof c.output.render !== 'function') {
+    throw new EventError('SHAPE', 'capability.output.render required — canonical value and rendering are separate');
+  }
+  // A capability MAY ship its own UI. Optional, and validated against this capability so a
+  // view can never name a capability its owner isn't already allowed to call.
+  if (c.view != null) validateView(c.view, c);
+  // A class-R capability that declares egress is a contradiction: R is a determinism
+  // guarantee, and a network round-trip is not deterministic.
+  if (c.class === 'R' && c.egress !== 'none') {
+    throw new EventError('CONTRADICTION', 'class R must declare egress:none');
+  }
+  return c;
+}
+
+/**
+ * Validate an INVOCATION. Enforces the one rule that is easiest to forget and worst to
+ * miss: a capability that is not `pure` cannot be invoked without an idempotency key,
+ * because a retried delegated call would otherwise perform the side effect twice.
+ */
+export function validateInvocation(inv, capability) {
+  if (!inv || typeof inv !== 'object') throw new EventError('SHAPE', 'invocation must be an object');
+  if (!str(inv.capability)) throw new EventError('SHAPE', 'invocation.capability required');
+  if (!inv.actor || !ACTOR_KINDS.includes(inv.actor.kind) || !str(inv.actor.id)) {
+    throw new EventError('SHAPE', `invocation.actor.kind must be one of ${ACTOR_KINDS}`);
+  }
+  if (!inv.scope || !SCOPE_KINDS.includes(inv.scope.kind) || !str(inv.scope.id)) {
+    throw new EventError('SHAPE', `invocation.scope.kind must be one of ${SCOPE_KINDS}`);
+  }
+  if (!Array.isArray(inv.causes)) throw new EventError('SHAPE', 'invocation.causes must be string[]');
+  const effects = capability ? capability.effects : inv.effects;
+  if (effects && effects !== 'pure' && !str(inv.idempotencyKey)) {
+    throw new EventError('IDEMPOTENCY', `invocation of a '${effects}' capability requires an idempotencyKey`);
+  }
+  return inv;
+}
+
+/**
+ * Can this capability satisfy these requirements on this host?
+ * Returns { ok, reasons[] } — REFUSING is a valid, expected outcome.
+ *
+ * `host` supplies what it can actually realize: { realizes: {R:{maxMs},M:{maxMs},...} }.
+ * Class is intrinsic (a guarantee); latency is host-bound. Never fuse the two.
+ */
+export function canSatisfy(capability, requirements = {}, host = null) {
+  const reasons = [];
+  const { maxLatencyMs, deterministic, egress, maxCostUsd } = requirements;
+
+  if (deterministic === true && !['R', 'M'].includes(capability.class)) {
+    reasons.push(`class ${capability.class} is not deterministic`);
+  }
+  if (egress === 'none' && capability.egress !== 'none') {
+    reasons.push(`capability egresses '${capability.egress}', requirement is 'none'`);
+  }
+  if (egress === 'redacted' && capability.egress === 'delegated') {
+    reasons.push('delegated egress is not controlled, requirement is redacted');
+  }
+  if (maxLatencyMs != null && host) {
+    const realized = host.realizes && host.realizes[capability.class];
+    if (!realized) reasons.push(`host cannot realize class ${capability.class}`);
+    else if (realized.maxMs > maxLatencyMs) {
+      reasons.push(`host realizes class ${capability.class} at ~${realized.maxMs}ms, requirement is ${maxLatencyMs}ms`);
+    }
+  }
+  if (maxCostUsd != null && capability.class === 'C' && maxCostUsd <= 0) {
+    reasons.push('cloud class requires a positive cost ceiling');
+  }
+  return { ok: reasons.length === 0, reasons };
+}
+
+/**
+ * The model-facing projection — an ALLOWLIST built from exactly three fields.
+ *
+ * Never an omit-list. An omit-list leaks the next field someone adds; this cannot,
+ * because `invoke`, `effects`, `cost`, `writes` and `egress` are never copied.
+ */
+export function toModelSchema(capability) {
+  return {
+    name: capability.id,
+    description: capability.disclose().gist,
+    parameters: capability.input || { type: 'object', properties: {} },
+  };
+}
+
+/** The same allowlist over a toolset — the only supported way to build a model request. */
+export function toModelSchemas(capabilities) {
+  return capabilities.map(toModelSchema);
+}