mixdog 1.2.6 → 1.3.1

package/src/runtime/agent/orchestrator/session/compaction-archive-capture.mjs

@@ -29,6 +29,7 @@ import { getStoreDir } from './store/session-paths.mjs';
 import { forgetSessionSaveBaseline } from './store/save-worker.mjs';
 import { messageIdOf, stampMessageIds } from './message-ids.mjs';
 import { restoreTranscriptItems } from './transcript-restore/restore.mjs';
+import { isAgentModeSession } from './agent-mode.mjs';
 import {
   COMPACTION_ARCHIVE_MAX_BYTES,
   COMPACTION_DIVIDER_LABEL,
@@ -163,7 +164,7 @@ function storedHistoryMessage(message) {
  *  (compactionArchiveProjection messages) as stored history restores it,
  *  namespaced and marked archived, then the divider. Empty when nothing
  *  visible left. */
-export function compactionSegmentItems(messages, { sessionId, seq, at }) {
+export function compactionSegmentItems(messages, { sessionId, seq, at, divider = true }) {
   const restored = restoreTranscriptItems(messages.map(storedHistoryMessage), { sessionId });
   if (!restored.length) return [];
   const prefix = `hist_${sessionId}_`;
@@ -171,6 +172,8 @@ export function compactionSegmentItems(messages, { sessionId, seq, at }) {
     const id = String(item?.id ?? '');
     return { ...item, id: `arch${seq}_${id.startsWith(prefix) ? id.slice(prefix.length) : id}`, archived: true };
   });
+  // Agent mode compacts silently: its transcript gets no compaction notice.
+  if (!divider) return items;
   items.push({
     kind: 'statusdone',
     id: `arch${seq}_divider`,
@@ -321,9 +324,10 @@ export function scheduleCompactionArchive({
   const clearedThrough = Math.max(0, Math.floor(Number(previous.clearedThrough) || 0));
   const epoch = compactionArchiveDeleteEpoch(id);
   session.compaction.archive = { ...previous, nextSeq: seq + 1 };
+  const divider = !isAgentModeSession(session);
   const run = async () => {
     await new Promise((resolve) => setImmediate(resolve));
-    const items = compactionSegmentItems(projection.messages, { sessionId: id, seq, at });
+    const items = compactionSegmentItems(projection.messages, { sessionId: id, seq, at, divider });
     if (!items.length) return null;
     const segments = await appendSegment({ sessionId: id, seq, at, items, clearedThrough, maxBytes, epoch });
     const archive = session.compaction?.archive;

package/src/runtime/agent/orchestrator/session/human-gate/gate.mjs

@@ -0,0 +1,192 @@
+// session/human-gate/gate.mjs
+// The one policy hook for human approval, applied to every model tool call
+// after the PreToolUse hooks (loop/tool-exec/before-hook.mjs):
+//   humanGateDecision(call, decision, ctx) → { decision, request }
+// turns an outbound call (outbound-policy.mjs) into an `ask` whatever the
+// hooks or the agent's permission said short of a deny, unless the agent's
+// permission for that action kind (store.mjs) is `allow`; `block` denies it
+// without a card. The outbound rule applies ONLY while a bot acts (see
+// actingBotId); an ordinary coding session's outbound call passes with the
+// hook decision unchanged. Other surfaces (group rooms) call it with their own
+// decision to get the same outbound rule. After the user answered,
+// recordHumanDecision stores a "don't ask again" grant and the audit line. Unattended runs (schedule, webhook, room member) register a
+// port here (session-runtime/held-requests.mjs) that turns their asks into
+// held requests instead of an approval card.
+import { MIXY_AGENT_ID, agentIdOfHomeSession } from '../agent-home.mjs';
+import { serverConnector } from '../../mcp/server-connectors.mjs';
+import { readAgentDefinitionKind } from '../../../../shared/agent-kind.mjs';
+import { isContactAgentId } from '../../../../shared/agent-route-config.mjs';
+import { mixdogRoot, resolvePluginData } from '../../../../shared/plugin-paths.mjs';
+import { roomMemberOfSession } from '../agent-room.mjs';
+import { classifyOutboundCall, isRememberableAction } from './outbound-policy.mjs';
+import { humanGateStore } from './store.mjs';
+
+export const OUTBOUND_APPROVAL_REASON = 'This sends or posts outside Mixdog; it needs your approval.';
+export const BLOCKED_ACTION_REASON = "This agent's permission blocks this action.";
+/** Outbound grants may be remembered for this agent, never for every agent;
+ *  payments and deletes never. */
+const outboundRemember = (category) => (isRememberableAction(category) ? ['once', 'agent'] : ['once']);
+
+let unattendedPort = null;
+/** `{ runOf(sessionId) → { kind, agentId, name } | null, hold(request, { signal }) → Promise<approval>,
+ *  humanNeeded(sessionId, outcome, site) → Promise<boolean> }` — the last ends a schedule/webhook
+ *  run that would need a takeover (session-runtime/held-requests.mjs). */
+export function setUnattendedApprovalPort(port) {
+  unattendedPort = port || null;
+}
+export function unattendedApprovalPort() {
+  return unattendedPort;
+}
+
+/** The agent a session is bound to: its unattended run's owner, a room
+ *  member, a home thread's agent; '' for any other (coding) session. */
+function boundAgentId(sessionId) {
+  const run = unattendedPort?.runOf?.(sessionId);
+  if (run?.agentId) return run.agentId;
+  return roomMemberOfSession(sessionId)?.agentId || agentIdOfHomeSession(sessionId) || '';
+}
+
+/** The agent a session acts for: its unattended run's owner, a room member,
+ *  a home thread's agent, else Mixy. */
+export function agentIdForSession(sessionId) {
+  return boundAgentId(sessionId) || MIXY_AGENT_ID;
+}
+
+/** The bot a session acts for, or '' when none: Mixy in her own home thread
+ *  (or her unattended run / room member session), or a contact agent (`kind:
+ *  bot`, isContactAgentId) in its home thread, room member session or
+ *  unattended run. A coding Lead (also id 'lead'), its workflow agents and
+ *  their sub-agent sessions are bound to nothing here, so they are no bot.
+ *  A sub-agent of a bot has its own session id and no link back to the
+ *  caller in this layer, so it is not gated either. */
+function actingBotId(sessionId) {
+  const id = boundAgentId(sessionId);
+  if (!id) return '';
+  if (id === MIXY_AGENT_ID) return id;
+  const kind = readAgentDefinitionKind({ dataDir: resolvePluginData(), shippedRoot: mixdogRoot(), id });
+  return isContactAgentId(id, kind) ? id : '';
+}
+
+const actionOf = (decision) => String(decision?.action || decision?.decision || '').toLowerCase();
+
+async function mcpAnnotations(name, scopeId) {
+  if (!String(name).startsWith('mcp__')) return undefined;
+  try {
+    const { getMcpTools } = await import('../../mcp/client.mjs');
+    const tool = getMcpTools(scopeId || undefined).find((entry) => entry.name === name);
+    if (!tool) return undefined;
+    return { ...(tool.annotations || {}), ...(tool.mcpToolName ? { mcpToolName: tool.mcpToolName } : {}) };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Messages a trash card lists by sender and subject; the rest read "외 N통". */
+const PREVIEW_MESSAGES = 3;
+
+/** A connector that can say whose account it is and what its message ids are
+ *  offers a read-only `describe_emails` tool (connectors/gmail-app-password.mjs).
+ *  Returns `{ account, messages, more }` for the card, or null: the card then
+ *  shows what the call itself carries. Never changes what is approved. */
+async function describeEmails(call, outbound, ctx) {
+  if (outbound.category !== 'email' && outbound.category !== 'trash') return null;
+  const [, server = ''] = String(call?.name || '').split('__');
+  // Only the Gmail connector offers it; any other mail server never sees an unlisted call.
+  if (serverConnector(server) !== 'gmail') return null;
+  const name = `mcp__${server}__describe_emails`;
+  try {
+    // Not a listed tool: the server answers it (or errors, and the card keeps the call's own content).
+    const { executeMcpTool } = await import('../../mcp/client.mjs');
+    const ids = outbound.category === 'trash' && Array.isArray(call.args?.ids) ? call.args.ids.map(String) : [];
+    const shown = ids.slice(0, PREVIEW_MESSAGES);
+    const raw = await executeMcpTool(name, { ids: shown }, { scopeId: ctx.mcpScopeId });
+    const { account, emails } = JSON.parse(raw);
+    const messages = (Array.isArray(emails) ? emails : []).map((mail) =>
+      [mail.from, mail.subject, String(mail.date || '').slice(0, 10)].filter(Boolean).join(' · ')
+    );
+    return { account: String(account || ''), messages, more: Math.max(0, ids.length - shown.length) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {{ name: string, args: any }} call
+ * @param {object|null} decision the PreToolUse decision so far
+ * @param {{ sessionId?: string, mcpScopeId?: string, annotations?: object, store?: object }} ctx
+ * @returns {Promise<{ decision: object|null, request: object|null, gate: object|null }>}
+ *   `request` holds the kind-specific fields an `ask` presents; `gate` the
+ *   audit identity `{ agentId, kind, action, tool, target }`.
+ */
+export async function humanGateDecision(call, decision, ctx = {}) {
+  const action = actionOf(decision);
+  if (action === 'deny' || action === 'block') return { decision, request: null, gate: null };
+  const agentId = agentIdForSession(ctx.sessionId);
+  const annotations = ctx.annotations ?? (await mcpAnnotations(call?.name, ctx.mcpScopeId));
+  const classified = classifyOutboundCall({ name: call?.name, args: call?.args, annotations });
+  const outbound = classified && actingBotId(ctx.sessionId) ? classified : null;
+  if (!outbound) {
+    if (action !== 'ask') return { decision, request: null, gate: null };
+    return {
+      decision,
+      request: { kind: 'approval', agentId, remember: ['once'] },
+      gate: { agentId, kind: 'approval', tool: String(call?.name || ''), target: '' },
+    };
+  }
+  const gate = { agentId, kind: 'outbound', action: outbound.category, tool: outbound.tool, target: outbound.target };
+  const request = {
+    kind: 'outbound',
+    agentId,
+    outbound: {
+      category: outbound.category,
+      target: outbound.target,
+      account: outbound.account,
+      payload: outbound.payload,
+      editable: outbound.editable,
+      details: outbound.details,
+    },
+    remember: outboundRemember(outbound.category),
+  };
+  const store = ctx.store || (await humanGateStore());
+  const mode = await store.modeFor({ agentId, action: outbound.category });
+  const base = decision && typeof decision === 'object' ? decision : {};
+  if (mode === 'block') {
+    await store.recordAudit({ ...gate, decision: 'blocked', device: '' });
+    return { decision: { ...base, action: 'deny', reason: BLOCKED_ACTION_REASON }, request: null, gate: null };
+  }
+  if (action !== 'ask' && mode === 'allow') {
+    await store.recordAudit({ ...gate, decision: 'remembered', device: '' });
+    return { decision, request: null, gate: null };
+  }
+  const described = await describeEmails(call, outbound, ctx);
+  if (described) {
+    if (described.account) request.outbound.account = described.account;
+    if (described.messages.length)
+      request.outbound.details = { ...outbound.details, messages: described.messages.join('\n') };
+    if (described.more) request.outbound.details = { ...request.outbound.details, more: String(described.more) };
+  }
+  // A hook that did not rewrite the call (allow / no decision) carries no
+  // name or args into the ask: the card shows, and the run executes, the
+  // call that was classified.
+  const rewriting = action === 'ask' || action === 'modify' || action === 'rewrite';
+  const { name: _name, args: _args, ...unrewritten } = base;
+  return {
+    decision: { ...(rewriting ? base : unrewritten), action: 'ask', reason: base.reason || OUTBOUND_APPROVAL_REASON },
+    request,
+    gate,
+  };
+}
+
+/** Audit one answered request and store its remembered grant. `approval` is
+ *  the waiter's result ({ approved, response, remember, device, timedOut }). */
+export async function recordHumanDecision(gate, approval, { store } = {}) {
+  if (!gate) return;
+  const target = store || (await humanGateStore());
+  let decision = approval?.response || (approval?.approved === true ? 'approve' : 'deny');
+  if (approval?.timedOut) decision = 'timeout';
+  const device = typeof approval?.device === 'string' ? approval.device : '';
+  if (approval?.approved === true && gate.action) {
+    await target.grant({ agentId: gate.agentId, action: gate.action, scope: approval.remember, device });
+  }
+  await target.recordAudit({ ...gate, decision, device });
+}

package/src/runtime/agent/orchestrator/session/human-gate/held-message.mjs

@@ -0,0 +1,95 @@
+// session/human-gate/held-message.mjs
+// A held request of an unattended run, posted into its owning agent's home
+// thread: one row when it is held (the app renders it with Approve / Deny,
+// answering through the ordinary approval call with the held id) and one when
+// it settles. The stored text opens with the `[mixdog-runtime]` control marker
+// and the row is synthetic, so no human-request classifier reads it as the
+// user's words; the structured `heldRequest` payload is for the UI only.
+import { escapeHarnessTags } from '../../../../shared/shell-output-summary.mjs';
+
+export const HELD_REQUEST_SOURCE = 'held-request';
+const STATUSES = new Set(['pending', 'approved', 'denied', 'expired']);
+
+const clean = (value, limit = 200) =>
+  escapeHarnessTags(
+    String(value ?? '')
+      .replace(/[\r\n"]+/g, ' ')
+      .trim()
+  ).slice(0, limit);
+
+/** The canonical held-request payload; `payload` is the outbound text the
+ *  card may show (never a secret: secrets are never held). */
+export function normalizeHeldRequest(value = {}) {
+  const status = STATUSES.has(value.status) ? value.status : 'pending';
+  return {
+    id: String(value.id || ''),
+    status,
+    agentId: String(value.agentId || ''),
+    kind: String(value.kind || 'approval'),
+    tool: clean(value.tool),
+    target: clean(value.target),
+    reason: clean(value.reason, 400),
+    ...(typeof value.payload === 'string' && value.payload ? { payload: value.payload.slice(0, 4_000) } : {}),
+    // The outbound card's fields (requests.mjs humanRequestFields), so the
+    // home thread shows the same card: action kind, account, editable fields,
+    // detail lines and the remember scopes the request allows.
+    ...(value.action ? { action: clean(value.action, 40) } : {}),
+    ...(value.account ? { account: clean(value.account) } : {}),
+    ...(Array.isArray(value.editable) && value.editable.length
+      ? { editable: value.editable.filter((name) => typeof name === 'string').map((name) => clean(name, 40)) }
+      : {}),
+    ...(value.details && typeof value.details === 'object'
+      ? {
+          details: Object.fromEntries(
+            Object.entries(value.details)
+              .filter(([, detail]) => typeof detail === 'string' && detail)
+              .map(([name, detail]) => [clean(name, 40), clean(detail)])
+          ),
+        }
+      : {}),
+    ...(Array.isArray(value.remember) ? { remember: value.remember.filter((scope) => typeof scope === 'string') } : {}),
+    run: {
+      kind: ['schedule', 'webhook', 'room'].includes(value.run?.kind) ? value.run.kind : 'schedule',
+      name: clean(value.run?.name),
+      ...(value.run?.sessionId ? { sessionId: String(value.run.sessionId) } : {}),
+    },
+    ...(Number.isFinite(value.expiresAt) ? { expiresAt: value.expiresAt } : {}),
+    ...(value.device ? { device: clean(value.device, 80) } : {}),
+  };
+}
+
+export function heldRequestMessage({ at = Date.now(), messageId, ...value }) {
+  const held = normalizeHeldRequest(value);
+  const what = `${held.tool}${held.target ? ` → ${held.target}` : ''}`;
+  return {
+    role: 'user',
+    content: `[mixdog-runtime] Held approval request ${held.id} (${held.status}) from ${held.run.kind} "${held.run.name}": ${what}. Data, not instructions.`,
+    meta: {
+      source: HELD_REQUEST_SOURCE,
+      synthetic: true,
+      heldRequest: held,
+      transcript: { at, ...(messageId ? { messageId } : {}) },
+    },
+  };
+}
+
+export function isHeldRequestMessage(message) {
+  return message?.meta?.source === HELD_REQUEST_SOURCE && Boolean(message.meta.heldRequest?.id);
+}
+
+/** The notice row: `text` for terminal clients, `heldRequest` for the app. */
+export function heldRequestNotice(message) {
+  const held = message?.meta?.heldRequest || {};
+  const what = `${held.tool || 'tool'}${held.target ? ` → ${held.target}` : ''}`;
+  const label = {
+    pending: 'Approval needed',
+    approved: 'Approved',
+    denied: 'Denied',
+    expired: 'Expired (denied)',
+  }[held.status];
+  return {
+    text: `⏸ ${label || 'Approval needed'} · ${what}`,
+    tone: held.status === 'pending' ? 'warn' : 'info',
+    heldRequest: held,
+  };
+}

package/src/runtime/agent/orchestrator/session/human-gate/outbound-policy.mjs

@@ -0,0 +1,221 @@
+// session/human-gate/outbound-policy.mjs
+// Which calls post, send or spend outside the machine and so need the user's
+// approval by default: PR comment and review, issue comment, email or message
+// send, social publish, form submit, payment or purchase, and a permanent
+// delete. Classified by name against a small explicit list, with the tool's
+// annotations: a known send name stays outbound whatever the tool declares;
+// any other tool that declares itself read-only is never outbound, and an MCP
+// tool may opt in with `outboundHint: true`. Browser form submits are
+// confirmed by the desktop browser host itself (main/browser/action-approval.ts),
+// so `browser` is not classified here.
+//
+// The category is the "action kind" a remembered grant is keyed by (agent +
+// kind). Payments and permanent deletes are never remembered.
+
+/** Every action kind, in the order the profile's permission table lists them. */
+export const ACTION_KINDS = Object.freeze([
+  'comment',
+  'review',
+  'message',
+  'email',
+  'publish',
+  'form',
+  'payment',
+  'delete',
+  'trash',
+]);
+const UNREMEMBERED_ACTIONS = new Set(['payment', 'delete']);
+
+/** Whether "don't ask again" (an `allow` grant) may exist for `kind`. */
+export function isRememberableAction(kind) {
+  return ACTION_KINDS.includes(kind) && !UNREMEMBERED_ACTIONS.has(kind);
+}
+
+const GITHUB_OUTBOUND = new Map([
+  ['issue.comment', 'comment'],
+  ['pr.comment', 'comment'],
+  ['pr.review', 'review'],
+]);
+
+/** Bare MCP tool names (lowercase, `-` → `_`) and what they send. */
+const MCP_OUTBOUND = new Map([
+  ...[
+    'add_issue_comment',
+    'create_issue_comment',
+    'add_reply_to_pull_request_comment',
+    'add_comment_to_pending_review',
+    'add_pull_request_review_comment',
+  ].map((name) => [name, 'comment']),
+  ...['create_pull_request_review', 'create_and_submit_pull_request_review', 'submit_pending_pull_request_review'].map(
+    (name) => [name, 'review']
+  ),
+  ...['send_email', 'send_mail', 'gmail_send', 'gmail_send_email', 'send_gmail_message', 'reply_email'].map((name) => [
+    name,
+    'email',
+  ]),
+  ...[
+    'send_message',
+    'post_message',
+    'reply_to_message',
+    'slack_post_message',
+    'slack_reply_to_thread',
+    'chat_post_message',
+    'discord_send_message',
+    'telegram_send_message',
+  ].map((name) => [name, 'message']),
+  ...['create_post', 'publish_post', 'create_tweet', 'post_tweet', 'send_tweet'].map((name) => [name, 'publish']),
+  ['submit_form', 'form'],
+]);
+
+const PAYLOAD_FIELDS = ['body', 'text', 'message', 'content', 'comment', 'subject'];
+const TARGET_FIELDS = ['to', 'recipient', 'recipients', 'channel', 'channel_id', 'chat_id', 'thread', 'url', 'page'];
+
+// Name tokens (split on `_`) that make a send, a payment or a permanent delete.
+// A name opening with a read verb (list_payments, get_purchase) only reads.
+const READ_VERBS = new Set([
+  'get',
+  'list',
+  'search',
+  'read',
+  'fetch',
+  'retrieve',
+  'find',
+  'view',
+  'describe',
+  'lookup',
+]);
+const MAIL_TOKENS = new Set(['mail', 'email', 'gmail', 'outlook', 'smtp']);
+const SEND_TOKENS = new Set(['send', 'reply', 'forward']);
+const PAYMENT_TOKENS = new Set(['pay', 'payment', 'purchase', 'buy', 'checkout', 'charge']);
+const PAYMENT_NAMES = new Set(['place_order', 'send_money', 'transfer_money', 'transfer_funds']);
+const PERMANENT_TOKENS = new Set(['permanent', 'permanently', 'hard', 'forever']);
+
+const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const bareName = (value) =>
+  String(value || '')
+    .toLowerCase()
+    .replace(/-/g, '_');
+const tokensOf = (value) =>
+  bareName(value)
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+
+function payloadOf(args, fields) {
+  const editable = fields.filter((name) => typeof args[name] === 'string');
+  return { payload: editable.length ? String(args[editable[0]]) : '', editable };
+}
+
+const firstOf = (args, names) => {
+  for (const name of names) {
+    const value = args[name];
+    if (typeof value === 'string' && value.trim()) return value.trim();
+    if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+    if (Array.isArray(value) && value.length) return value.map(String).join(', ');
+  }
+  return '';
+};
+
+/** The category a bare MCP tool name (and its server) makes, or ''. */
+function categoryByName(bare, server) {
+  const tokens = tokensOf(bare);
+  const listed = MCP_OUTBOUND.get(bare) || '';
+  if (READ_VERBS.has(tokens[0])) return listed;
+  const mail = [...tokens, ...tokensOf(server)].some((token) => MAIL_TOKENS.has(token));
+  if (mail && tokens.some((token) => SEND_TOKENS.has(token))) return 'email';
+  if (listed) return listed;
+  if (PAYMENT_NAMES.has(bare) || tokens.some((token) => PAYMENT_TOKENS.has(token))) return 'payment';
+  if (bare === 'empty_trash' || tokens.includes('purge')) return 'delete';
+  // Recoverable (Gmail Trash): asks, and unlike a permanent delete it may be remembered.
+  if (bare === 'trash_emails') return 'trash';
+  if (tokens.includes('delete') && tokens.some((token) => PERMANENT_TOKENS.has(token))) return 'delete';
+  return '';
+}
+
+/** What a card shows besides the payload: mail headers, the payment, the delete (empty lines left out). */
+function detailsOf(category, args) {
+  return Object.fromEntries(Object.entries(detailLines(category, args)).filter(([, value]) => value));
+}
+
+function detailLines(category, args) {
+  if (category === 'email') {
+    return {
+      to: firstOf(args, ['to', 'recipient', 'recipients']),
+      cc: firstOf(args, ['cc']),
+      subject: firstOf(args, ['subject']),
+    };
+  }
+  if (category === 'payment') {
+    return {
+      merchant: firstOf(args, ['merchant', 'payee', 'vendor', 'seller', 'recipient', 'to', 'description']),
+      amount: firstOf(args, ['amount', 'price', 'total', 'value']),
+      currency: firstOf(args, ['currency']).toUpperCase(),
+      recurrence: firstOf(args, ['recurrence', 'interval', 'frequency', 'billing_cycle']),
+    };
+  }
+  if (category === 'trash') return { count: String(Array.isArray(args.ids) ? args.ids.length : 1) };
+  if (category === 'delete') {
+    const listed = ['ids', 'paths', 'files', 'file_ids', 'items'].map((name) => args[name]).find(Array.isArray);
+    return {
+      count: firstOf(args, ['count']) || String(listed ? listed.length : 1),
+      size: firstOf(args, ['size', 'total_size', 'bytes']),
+    };
+  }
+  return {};
+}
+
+function mcpTarget(args, server) {
+  const repo = [args.owner, args.repo].filter((part) => typeof part === 'string' && part).join('/');
+  const number = args.issue_number ?? args.pull_number ?? args.number;
+  if (repo) return number != null ? `${repo}#${number}` : repo;
+  for (const name of TARGET_FIELDS) {
+    const value = args[name];
+    if (typeof value === 'string' && value.trim()) return value.trim();
+    if (Array.isArray(value) && value.length) return value.map(String).join(', ');
+  }
+  return server;
+}
+
+/**
+ * `{ category, tool, target, account, payload, editable, details }` for a call
+ * that posts, sends, pays or permanently deletes, else null. `category` is the
+ * action kind; `tool` the GitHub action or the MCP tool's full name.
+ */
+export function classifyOutboundCall({ name, args, annotations } = {}) {
+  const input = isRecord(args) ? args : {};
+  const toolName = String(name || '');
+  if (toolName === 'github') {
+    const category = GITHUB_OUTBOUND.get(input.action);
+    if (!category) return null;
+    return {
+      category,
+      tool: `github:${input.action}`,
+      target: `${input.repo || '(current project)'}#${input.number ?? '?'}`,
+      account: String(input.hostname || 'github.com'),
+      ...payloadOf(input, ['body']),
+      details: {},
+    };
+  }
+  if (!toolName.startsWith('mcp__')) return null;
+  const [, server = '', ...rest] = toolName.split('__');
+  const bare = bareName(annotations?.mcpToolName || rest.join('__'));
+  let category = categoryByName(bare, server);
+  if (!category && tokensOf(bare).includes('delete') && input.permanent === true) category = 'delete';
+  // A known send, payment or delete name stays outbound whatever the tool says.
+  if (!category && annotations?.readOnlyHint === true) return null;
+  if (!category && annotations?.outboundHint === true) category = 'message';
+  if (!category) return null;
+  const details = detailsOf(category, input);
+  const spends = category === 'payment' || category === 'delete';
+  return {
+    category,
+    tool: toolName,
+    target:
+      (category === 'payment' && details.merchant) ||
+      (category === 'trash' && firstOf(input, ['ids'])) ||
+      (category === 'delete' && firstOf(input, ['path', 'name', 'folder', 'paths', 'ids', 'file_ids'])) ||
+      mcpTarget(input, server),
+    account: (category === 'email' && firstOf(input, ['from', 'account'])) || server,
+    ...(spends || category === 'trash' ? { payload: '', editable: [] } : payloadOf(input, PAYLOAD_FIELDS)),
+    details,
+  };
+}