amalgm 0.0.0 → 0.0.1

package/runtime/scripts/chat-core/normalizers/codex.js

@@ -0,0 +1,380 @@
+'use strict';
+
+const { compactionFinished, compactionStarted, done, errorEvent, reasoningDelta, textDelta, toolCompleted, toolStarted, toolUpdated, usageFinal } = require('../events');
+const { stringifyResult, summarizeToolOutput, summarizeToolRequest } = require('../tool-display');
+const { normalizeError, titleForTool, toolKind } = require('../tool-shape');
+const { normalizeUsage } = require('../usage');
+
+const NON_TOOL_ITEM_TYPES = new Set(['agentMessage', 'contextCompaction', 'reasoning', 'userMessage']);
+
+function isCodexToolItem(item = {}) {
+  return Boolean(item?.id && item?.type && !NON_TOOL_ITEM_TYPES.has(item.type));
+}
+
+function codexToolName(item = {}) {
+  if (item.type === 'commandExecution') return 'Bash';
+  if (item.type === 'fileChange') return 'Edit';
+  if (item.type === 'webSearch') return 'WebSearch';
+  if (item.type === 'collabAgentToolCall') return 'Agent';
+  if (item.type === 'mcpToolCall') return item.tool || item.toolName || item.name || 'mcpToolCall';
+  return item.name || item.toolName || item.type || 'unknown';
+}
+
+function codexToolInput(item = {}) {
+  if (item.type === 'commandExecution') {
+    return { command: item.command || item.rawCommand || '', cwd: item.cwd };
+  }
+  if (item.type === 'collabAgentToolCall') {
+    return {
+      prompt: item.prompt || '',
+      model: item.model || undefined,
+      reasoningEffort: item.reasoningEffort || undefined,
+      receiverThreadIds: item.receiverThreadIds || undefined,
+    };
+  }
+  const input = {};
+  for (const key of ['path', 'filePath', 'file_path', 'query', 'pattern', 'url', 'server', 'serverName', 'tool', 'toolName', 'name']) {
+    if (item[key] !== undefined) input[key] = item[key];
+  }
+  if (item.input && typeof item.input === 'object') Object.assign(input, item.input);
+  if (item.arguments && typeof item.arguments === 'object') Object.assign(input, item.arguments);
+  if (item.action && typeof item.action === 'object') {
+    if (useful(item.action.query) || !useful(input.query)) input.query = item.action.query;
+    if (useful(item.action.url) || !useful(input.url)) input.url = item.action.url;
+    if (useful(item.action.pattern) || !useful(input.pattern)) input.pattern = item.action.pattern;
+    if (Array.isArray(item.action.queries) && item.action.queries.length > 0) input.queries = item.action.queries;
+  }
+  if (Object.keys(input).length === 0) input.itemType = item.type || 'unknown';
+  return input;
+}
+
+function useful(value) {
+  return value !== undefined && value !== null && value !== '';
+}
+
+function codexToolOutput(item = {}) {
+  if (item.status === 'failed' && item.error) return '';
+  const direct = item.aggregatedOutput ?? item.output ?? item.result ?? item.diff ?? item.error ?? item.message ?? item.text ?? item.finalText;
+  if (direct == null) return '';
+  return direct;
+}
+
+function codexToolError(item = {}) {
+  if (item.status !== 'failed' && !item.error) return undefined;
+  return normalizeError(item.error || item.message || item.text || 'Codex tool failed');
+}
+
+function codexToolMetadata(item = {}) {
+  const metadata = {
+    providerItemType: item.type || 'unknown',
+    providerStatus: item.status,
+  };
+  if (item.type === 'webSearch' && item.action) metadata.action = item.action;
+  if (item.type === 'mcpToolCall') {
+    metadata.mcp = {
+      server: item.server || item.serverName || 'unknown',
+      tool: item.tool || item.toolName || item.name || 'unknown',
+    };
+  }
+  if (item.type === 'collabAgentToolCall') {
+    metadata.subagent = true;
+    metadata.senderThreadId = item.senderThreadId;
+    metadata.receiverThreadIds = item.receiverThreadIds;
+    metadata.agentsStates = item.agentsStates;
+  }
+  if (Number.isFinite(Number(item.durationMs))) metadata.durationMs = Number(item.durationMs);
+  return metadata;
+}
+
+function codexToolDetail(item = {}) {
+  const input = codexToolInput(item);
+  const inputDetail = summarizeToolRequest(
+    codexToolName(item),
+    input,
+    item.command || item.title || item.summary || item.text || item.path || item.prompt || '',
+  );
+  if (inputDetail) return inputDetail;
+  return summarizeToolOutput(codexToolOutput(item));
+}
+
+function codexToolTitle(item = {}) {
+  const input = codexToolInput(item);
+  const metadata = codexToolMetadata(item);
+  return titleForTool({
+    name: codexToolName(item),
+    input,
+    output: codexToolOutput(item),
+    error: codexToolError(item),
+    metadata,
+    fallback: item.title || item.summary || item.text || item.path || item.prompt || item.command || '',
+  });
+}
+
+function codexToolData(item = {}) {
+  return {
+    providerItemType: item.type || 'unknown',
+    item,
+  };
+}
+
+function codexDelta(msg, p = {}) {
+  return msg.textDelta ?? p.delta ?? p.textDelta ?? p.outputDelta ?? p.text ?? '';
+}
+
+function codexItemId(p = {}) {
+  return p.itemId || p.item?.id || p.id || p.callId || p.toolCallId;
+}
+
+function codexTokenTotal(value = {}) {
+  const direct = Number(value.totalTokens);
+  if (Number.isFinite(direct) && direct > 0) return direct;
+  return Number(value.inputTokens || 0) + Number(value.outputTokens || 0);
+}
+
+function codexTokenBucketTotal(value = {}) {
+  return Number(value.inputTokens || 0)
+    + Number(value.outputTokens || 0)
+    + Number(value.cachedInputTokens || 0)
+    + Number(value.cacheWriteTokens || value.cacheWriteInputTokens || value.cacheCreationInputTokens || 0);
+}
+
+function codexTokenList(value = {}) {
+  const cacheRead = Number(value.cachedInputTokens || 0);
+  const cacheWrite = Number(value.cacheWriteTokens || value.cacheWriteInputTokens || value.cacheCreationInputTokens || 0);
+  const output = Number(value.outputTokens || 0);
+  const thought = Number(value.reasoningOutputTokens || 0);
+  const totalInput = Number(value.inputTokens || 0);
+  const input = Math.max(0, totalInput - cacheRead - cacheWrite);
+  return {
+    input,
+    output,
+    cacheRead,
+    cacheWrite,
+    thought,
+    total: input + output + cacheRead + cacheWrite,
+  };
+}
+
+function codexCumulativeUsage(total = {}, state) {
+  if (codexTokenBucketTotal(total) <= 0) return {};
+  const cumulativeTokenList = codexTokenList(total);
+  const previousCumulativeTokenList = state?.codexCumulativeTokenList || null;
+  if (state) state.codexCumulativeTokenList = cumulativeTokenList;
+  return { cumulativeTokenList, previousCumulativeTokenList };
+}
+
+function codexErrorMessage(error, fallback = 'Codex turn failed') {
+  if (!error) return fallback;
+  if (typeof error === 'string') return error;
+  if (error.data?.message) return error.data.message;
+  if (error.data?.error?.message) return error.data.error.message;
+  if (error.cause?.message) return error.cause.message;
+  if (error.message) return error.message;
+  if (error.name) return error.name;
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return fallback;
+  }
+}
+
+function eventRaw(method, payload) {
+  return { raw: { source: 'codex.app-server.notification', method, payload } };
+}
+
+function isCodexCompactionItem(item = {}) {
+  return item?.type === 'contextCompaction';
+}
+
+function normalizeCodexNotification(msg, providerSessionId, state) {
+  const method = msg.method;
+  const p = msg.params || msg.payload || {};
+  const raw = eventRaw(method || 'unknown', msg);
+  if (method === 'item/started' && isCodexCompactionItem(p.item)) {
+    if (state) {
+      state.codexCompactionActive = true;
+      state.codexCompactionUsageEmitted = false;
+      state.codexCompactionItemId = p.item.id || null;
+    }
+    return [compactionStarted({
+      providerSessionId,
+      trigger: 'auto',
+      ...raw,
+    })];
+  }
+  if (method === 'item/completed' && isCodexCompactionItem(p.item)) {
+    if (state) state.codexCompactionActive = false;
+    return [compactionFinished({
+      providerSessionId,
+      trigger: 'auto',
+      ...raw,
+    })];
+  }
+  if (method === 'item/agentMessage/delta' && codexDelta(msg, p)) return [textDelta(codexDelta(msg, p), { providerSessionId, ...raw })];
+  if ((method === 'item/reasoning/delta' || method === 'item/reasoning/textDelta' || method === 'item/reasoning/summaryTextDelta') && codexDelta(msg, p)) {
+    return [reasoningDelta(codexDelta(msg, p), { providerSessionId, ...raw })];
+  }
+  if (method === 'item/plan/delta' && codexDelta(msg, p)) return [reasoningDelta(codexDelta(msg, p), { providerSessionId, streamKind: 'plan', ...raw })];
+  if ((method === 'item/commandExecution/outputDelta' || method === 'item/fileChange/outputDelta') && codexDelta(msg, p)) {
+    const id = codexItemId(p);
+    if (!id) return [];
+    return [toolUpdated(id, {
+      providerSessionId,
+      outputDelta: codexDelta(msg, p),
+      status: 'in_progress',
+      ...raw,
+    })];
+  }
+  if (method === 'item/mcpToolCall/progress') {
+    const id = codexItemId(p);
+    if (!id) return [];
+    return [toolUpdated(id, {
+      providerSessionId,
+      outputDelta: p.message || p.progress || p.summary || '',
+      status: 'in_progress',
+      ...raw,
+    })];
+  }
+  if (method === 'item/started' && isCodexToolItem(p.item)) {
+    const toolName = codexToolName(p.item);
+    const input = codexToolInput(p.item);
+    const detail = codexToolDetail(p.item);
+    const metadata = codexToolMetadata(p.item);
+    return [toolStarted(p.item.id, {
+      providerSessionId,
+      toolName,
+      title: codexToolTitle(p.item),
+      kind: toolKind(toolName, input, metadata),
+      detail,
+      input,
+      metadata,
+      data: codexToolData(p.item),
+      ...raw,
+    })];
+  }
+  if (method === 'item/updated' && isCodexToolItem(p.item)) {
+    const input = codexToolInput(p.item);
+    const toolName = codexToolName(p.item);
+    const metadata = codexToolMetadata(p.item);
+    return [toolUpdated(p.item.id, {
+      providerSessionId,
+      toolName,
+      title: codexToolTitle(p.item),
+      kind: toolKind(toolName, input, metadata),
+      detail: codexToolDetail(p.item),
+      inputDelta: input,
+      status: 'in_progress',
+      metadata,
+      data: codexToolData(p.item),
+      ...raw,
+    })];
+  }
+  if (method === 'item/completed' && isCodexToolItem(p.item)) {
+    const toolName = codexToolName(p.item);
+    const input = codexToolInput(p.item);
+    const output = codexToolOutput(p.item);
+    const error = codexToolError(p.item);
+    const metadata = codexToolMetadata(p.item);
+    const detail = codexToolDetail(p.item);
+    return [toolCompleted(p.item.id, {
+      providerSessionId,
+      toolName,
+      title: codexToolTitle(p.item),
+      kind: toolKind(toolName, input, metadata),
+      detail: detail || summarizeToolOutput(output),
+      input,
+      result: stringifyResult(output),
+      output,
+      error,
+      isError: p.item.status === 'failed' || Boolean(error),
+      timing: Number.isFinite(Number(p.item.durationMs)) ? { elapsedMs: Number(p.item.durationMs) } : undefined,
+      metadata,
+      data: codexToolData(p.item),
+      ...raw,
+    })];
+  }
+  if (method === 'thread/tokenUsage/updated') {
+    const last = p.tokenUsage?.last || (Array.isArray(p.tokenUsage?.lastTurn) ? p.tokenUsage.lastTurn[0] : p.tokenUsage?.lastTurn);
+    const total = p.tokenUsage?.total || {};
+    const totalProcessedTokens = codexTokenTotal(total);
+    const lastTotal = codexTokenTotal(last);
+    const lastBucketTotal = codexTokenBucketTotal(last);
+    const cumulativeUsage = codexCumulativeUsage(total, state);
+    if (state?.codexCompactionActive) {
+      if (state.codexCompactionUsageEmitted && state.lastCodexCompactionSnapshotTotal === lastTotal) return [];
+      state.codexCompactionUsageEmitted = true;
+      state.lastCodexCompactionSnapshotTotal = lastTotal;
+      if (lastBucketTotal === 0 && lastTotal > 0) {
+        return [usageFinal(normalizeUsage({
+          tokenList: {
+            input: lastTotal,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            thought: 0,
+            total: lastTotal,
+          },
+          inputContextSize: lastTotal,
+          contextLimit: p.tokenUsage?.modelContextWindow,
+          totalProcessedTokens: totalProcessedTokens > 0 ? totalProcessedTokens : undefined,
+          ...cumulativeUsage,
+          operation: 'compaction',
+          billable: false,
+          source: 'codex_app_server_context_snapshot',
+          exact: false,
+        }), { providerSessionId, ...raw })];
+      }
+      return [usageFinal(normalizeUsage({
+        totalInputTokens: last?.inputTokens,
+        outputTokens: last?.outputTokens,
+        cachedInputTokens: last?.cachedInputTokens,
+        cacheWriteTokens: last?.cacheWriteTokens ?? last?.cacheWriteInputTokens ?? last?.cacheCreationInputTokens,
+        thoughtTokens: last?.reasoningOutputTokens,
+        contextLimit: p.tokenUsage?.modelContextWindow,
+        totalProcessedTokens: totalProcessedTokens > 0 ? totalProcessedTokens : undefined,
+        ...cumulativeUsage,
+        operation: 'compaction',
+        source: 'codex_app_server',
+        exact: true,
+      }), { providerSessionId, ...raw })];
+    }
+    if (state?.lastCodexCompactionSnapshotTotal === lastTotal && lastBucketTotal === 0 && lastTotal > 0) return [];
+    return [usageFinal(normalizeUsage({
+      totalInputTokens: last?.inputTokens,
+      outputTokens: last?.outputTokens,
+      cachedInputTokens: last?.cachedInputTokens,
+      cacheWriteTokens: last?.cacheWriteTokens ?? last?.cacheWriteInputTokens ?? last?.cacheCreationInputTokens,
+      thoughtTokens: last?.reasoningOutputTokens,
+      contextLimit: p.tokenUsage?.modelContextWindow,
+      totalProcessedTokens: totalProcessedTokens > 0 ? totalProcessedTokens : undefined,
+      ...cumulativeUsage,
+      operation: 'chat_step',
+      source: 'codex_app_server',
+      exact: true,
+    }), { providerSessionId, ...raw })];
+  }
+  if (method === 'turn/completed') {
+    const error = p.error || p.lastError || p.turn?.error || p.turn?.lastError;
+    if (error) return [errorEvent(codexErrorMessage(error), { providerSessionId, ...raw }), done({ providerSessionId, stopReason: 'error', ...raw })];
+    return [done({ providerSessionId, ...raw })];
+  }
+  if ((method === 'turn/error' || method === 'error') && p.willRetry === true) {
+    return [];
+  }
+  if (method === 'turn/failed' || method === 'turn/error' || method === 'error') {
+    return [errorEvent(codexErrorMessage(p.error || p), { providerSessionId, ...raw }), done({ providerSessionId, stopReason: 'error', ...raw })];
+  }
+  return [];
+}
+
+module.exports = {
+  codexErrorMessage,
+  codexToolInput,
+  codexToolDetail,
+  codexToolError,
+  codexToolName,
+  codexToolOutput,
+  codexToolTitle,
+  isCodexToolItem,
+  normalizeCodexNotification,
+};

package/runtime/scripts/chat-core/normalizers/normalizer_spec.md

@@ -0,0 +1,259 @@
+# Agent event normalization matrix
+
+Source of truth for how Claude Code / Codex / OpenCode native events map to the unified amalgm event shape. Lives next to the normalizers so the contract stays close to the code.
+
+**Files**
+- Normalizers (this dir): `claude.js`, `codex.js`, `opencode.js`
+- Tool contract: `tool_contract.md`
+- Adapters: `../adapters/{claude,codex,opencode}.js`
+- Wire framing: `../sse.js` → `toAgentStreamEvent()`
+- UI consumer: `amalgm-ui/lib/agents/acpAdapter.ts`
+- UI schema: `amalgm-ui/lib/agents/acpTypes.ts`
+
+**Capturing fixtures**
+
+```sh
+CHAT_CORE_RECORD=1 <run a session>
+# writes ~/.amalgm/chat-core-recordings/<date>.ndjson
+```
+
+Cell legend: ✅ handled · ⚠️ handled, with gaps · ❌ dropped · `TBD` not yet captured from a real fixture.
+
+---
+
+## 1. Text parts
+
+Streamed assistant text. The user-visible response.
+
+| | Claude Code | Codex | OpenCode |
+|---|---|---|---|
+| Native | `assistant.message.content[]` block `type:'text'` | `item/agentMessage/delta` | `message.part.delta` type `text` + `message.part.updated` snapshots |
+| Amalgm | `agent_message_chunk` | `agent_message_chunk` | `agent_message_chunk` |
+| Dedup | ❌ none | ❌ none | ✅ suffix-prefix overlap (40 / 80 char thresholds) |
+| Gaps | SDK retransmit would double — untested | Same | Magic thresholds undocumented; no test |
+
+---
+
+## 2. Reasoning parts
+
+Model thinking stream. Separate from text.
+
+| | Claude Code | Codex | OpenCode |
+|---|---|---|---|
+| Native | blocks `type:'thinking'` or `'redacted_thinking'` | `item/reasoning/delta`, `reasoning/textDelta`, `reasoning/summaryTextDelta` | `message.part` type `reasoning` |
+| Amalgm | `agent_thought_chunk` | `agent_thought_chunk` | `agent_thought_chunk` |
+| Sub-types | `redacted_thinking` flattened, lost | `summaryTextDelta` vs `textDelta` flattened, lost | none |
+| Done signal | implicit (assistant message ends) | implicit | implicit |
+| Gaps | Sub-type info lost; UI can't differentiate redacted | Same | TBD |
+
+---
+
+## 3. Tool parts (the call)
+
+Tool invocation: id, name, title.
+
+| | Claude Code | Codex | OpenCode |
+|---|---|---|---|
+| Native | content block `tool_use` / `server_tool_use` / `mcp_tool_use` | `item/started` (tool item) | `message.part` type `tool`, status `pending` / `running` |
+| Amalgm | `tool_call` | `tool_call` | `tool_call` |
+| Tool name | canonical (`Read`, `Edit`, `Bash`, …) | semantic (`commandExecution`, `fileChange`, `webSearch`, `mcpToolCall`) | inferred from input shape via `resolveToolName()` |
+| Gaps | ✅ matches UI taxonomy | ⚠️ Codex names ≠ Claude names → UI falls through to `tool-unknown` for `fileChange` etc. | ⚠️ heuristic; ambiguous inputs → `unknown` |
+
+---
+
+## 4. Tool input
+
+Initial input + streaming JSON deltas while model writes args.
+
+| | Claude Code | Codex | OpenCode |
+|---|---|---|---|
+| Native (initial) | `tool_use.input` object | `item.input` / `item.arguments` | `part.state.input` |
+| Native (delta) | `content_block_delta` with `delta.type:'input_json_delta'` (partial JSON string) | `item/updated` (full input snapshot) | `message.part.updated` (snapshot) |
+| Amalgm | `tool_call_update.inputDelta` (parsed object) | same (full snapshot) | same (full snapshot) |
+| Partial-parse | `tool.partialInputJson` accumulator + `stableStringify` fingerprint dedup | none | none |
+| Gaps | Never-closing JSON when cancelled mid-args — untested | No granularity (snapshot only) | Same |
+
+---
+
+## 5. Tool state
+
+Lifecycle: started → in_progress → completed / failed.
+
+| | Claude Code | Codex | OpenCode |
+|---|---|---|---|
+| started | `tool_use` block first seen | `item/started` | `part.state.status === 'pending' \| 'running'` |
+| in_progress | `tool_progress` messages | `item/commandExecution/outputDelta`, `item/fileChange/outputDelta`, `item/mcpToolCall/progress` | `part.state.status === 'running'` |
+| completed | `user.content` `tool_result` block | `item/completed` (status not failed) | `part.state.status === 'completed'` |
+| failed | `tool_result.is_error: true` | `item/completed` with `status:'failed'` | `part.state.status === 'error'` |
+| Amalgm | `tool_call_update` with `status ∈ { calling, output-available, output-error }` | same | same |
+| Gaps | TBD | TBD | TBD |
+
+---
+
+## 6. Tool output
+
+Actual result content (string, blob, structured).
+
+| | Claude Code | Codex | OpenCode |
+|---|---|---|---|
+| Native field | `tool_result.content` (string or blocks) | `item.aggregatedOutput ?? output ?? result ?? diff ?? error ?? message ?? text ?? finalText` | `part.state.output ?? part.state.error` |
+| Amalgm | `tool_call_update.content` + `rawOutput` | same | same |
+| Image outputs | possible but unhandled | none observed | none observed |
+| Gaps | Multi-block `tool_result` may not flatten correctly — TBD | Long fallback chain may pick wrong field | TBD |
+
+---
+
+## 7. Permissions / approvals
+
+Tool gating: the model wants to run a tool, user must approve. Interrupts the tool lifecycle between **started** and **completed**. Distinct from tool state.
+
+| | Claude Code | Codex | OpenCode |
+|---|---|---|---|
+| Native | SDK exposes `canUseTool` callback; in stream form, TBD: confirm whether a `permission_request` event is emitted | TBD: Codex has approval mode (`approval_policy`); items carry an `approval_required` flag — confirm event shape from fixture | `question.asked` event (closest analog) — partially mapped today as a tool call named `AskUserQuestion` |
+| User response | resume via callback / decision RPC | resume RPC | `question.replied` (with answer) or `question.rejected` |
+| Decline behavior | tool not executed; turn continues without it | TBD | tool reported as completed-with-rejection |
+| Amalgm | ❌ no first-class event today; auto-approve assumed | ❌ same | ⚠️ shoehorned into `tool_call` for `AskUserQuestion` |
+| Proposed | new `SessionUpdate` variant `permission_request { toolCallId, action, args, severity }` plus `permission_response { toolCallId, approved, reason? }` | same | same |
+| Gaps | No standardized permission UI across CLIs. Cross-CLI parity needed. |
+
+---
+
+## 8. Stop / end turn / cancellation
+
+Turn termination signal + reason.
+
+| | Claude Code | Codex | OpenCode |
+|---|---|---|---|
+| End turn | `result` message → `done(stopReason: stop_reason)` | `turn/completed` → `done` | `session.idle` / `message.finish` → `done` |
+| Cancel | SDK iterator close → `done(stopReason:'cancelled')` | RPC cancel → `done` | prompt abort → `done(stopReason:'cancelled')` |
+| Error end | `result.is_error` → `errorEvent` + `done(stopReason:'error')` | `turn/failed` / `turn/error` → same | `session.error` → same |
+| Amalgm | `complete` event with `stopReason` | same | same |
+| Gaps | `stop_reason` values not enumerated/typed | TBD | TBD |
+
+---
+
+## 9. Usage (tokens)
+
+Per-turn token counts.
+
+| | Claude Code | Codex | OpenCode |
+|---|---|---|---|
+| Source | `result.usage` at turn end | `thread/tokenUsage/updated` (multiple per turn) | `step-finish` parts + `message.tokens` |
+| input | `input_tokens` | `inputTokens` | `tokens.input` |
+| output | `output_tokens` | `outputTokens` | `tokens.output` |
+| cache read | `cache_read_input_tokens` | `cachedInputTokens` | `tokens.cache.read` |
+| cache write | `cache_creation_input_tokens` | ❓ folded into input? | `tokens.cache.write` |
+| reasoning | folded into output | `reasoningOutputTokens` → `thoughtTokens` | `tokens.reasoning` → `thoughtTokens` |
+| Amalgm | `usage_update` (normalized) | same | same |
+| Cadence | once per turn | per notification (multi) | per step (multi) |
+| Gaps | Cache-write field semantics differ — confirm Codex | Same | TBD |
+
+---
+
+## 10. Cost (USD)
+
+Dollar cost; separate concern from tokens.
+
+| | Claude Code | Codex | OpenCode |
+|---|---|---|---|
+| Native | `result.total_cost_usd` once at turn end | ❌ never emitted | per-step `tokens.cost` |
+| Amalgm | `usage_update.cost.amount` once | ❌ never set | `usage_update.cost.amount` per step |
+| Cadence | once / turn | never | per step |
+| Gaps | Three different semantics across CLIs → downstream sums are wrong. Pick one canonical place to compute. |
+
+---
+
+## 11. Compaction
+
+End-to-end wiring shipped. Canonical event shape: `compaction.started` and `compaction.finished`, converted to ACP `SessionUpdate.compaction_boundary { phase: 'started' | 'finished', trigger, preTokens?, postTokens?, durationMs?, summary? }`. UI renders compaction as a ProcessChain element with the same white loading dot used by the message waiting state: `Compacting context` while active, then `Compacted context in 23s` when timing is known. Saved as a normal assistant message part so users can see prior compactions after reload.
+
+| | Claude Code | Codex | OpenCode |
+|---|---|---|---|
+| Native start | `{ type:'system', subtype:'status', status:'compacting' }` (`SDKStatusMessage`) | `item/started` with `item.type:'contextCompaction'` | `message.part.updated` with `part.type:'compaction'` |
+| Native finish | `{ type:'system', subtype:'compact_boundary', compact_metadata:{ trigger, pre_tokens, post_tokens, duration_ms } }` | `item/completed` with `item.type:'contextCompaction'` | `{ type:'session.compacted', properties:{ sessionID } }` |
+| In-progress signal | ✅ `status:'compacting'` continues until boundary | ✅ context compaction item lifecycle | ✅ compaction part before session finish |
+| Engine emit | ✅ `compactionStarted` + `compactionFinished` | ✅ `compactionStarted` + `compactionFinished` | ✅ `compactionStarted` + `compactionFinished` |
+| UI render | Same ProcessChain element | Same ProcessChain element | Same ProcessChain element |
+| Persistence | ✅ saved in assistant `messages.parts` as `{ type:'compaction', phase, startedAt, finishedAt, durationMs, ... }` | same | same |
+| Gaps | Compaction billing needs usage decision | Compaction billing unclear; usage shows context reset | Native exposes compaction cost/tokens; usage logging decision pending |
+
+---
+
+## 12. Errors
+
+Auth, model, transport — three flavors that need separate signals.
+
+| | Claude Code | Codex | OpenCode |
+|---|---|---|---|
+| Auth | SDK throws with auth message | RPC error w/ auth code | session error with auth flag |
+| Model (rate limit, overflow, unavailable) | `result.is_error` with `errors[]` | `turn/error` with `error.type` | `session.error` |
+| Runtime / transport | adapter try-catch | RPC reject + child exit | stream / prompt reject |
+| Amalgm | `error`, `auth_error`, `model_error` (inconsistent) | same | same |
+| Gaps | All three often flatten to plain `error`. UI can't tell severity. `auth_error` / `model_error` exist in ACP but not consistently emitted. |
+
+---
+
+## 13. Session init
+
+Fires once per session. Identifies provider session, cwd, model, tool list.
+
+| | Claude Code | Codex | OpenCode |
+|---|---|---|---|
+| Native | `system` msg `subtype:'init'` with `cwd`, `model`, `tools[]` | `session/created` notification | `session.created` event |
+| Amalgm | `session_init { sessionId, containerId }` | same | same |
+| Extra fields (cwd / model / tools) | TBD: do they reach UI? | TBD | TBD |
+| Title | `title_generated` event — when does each CLI emit one? | TBD | TBD |
+| Gaps | Confirm cwd/model/tool propagation. |
+
+---
+
+## 14. Multimodal content (images, audio, files)
+
+Non-text content blocks. Today only images are partially handled.
+
+| | Claude Code | Codex | OpenCode |
+|---|---|---|---|
+| Image input | block `type:'image'` (`source.type:'base64'` or `'url'`) | TBD | TBD |
+| Image output | block `type:'image'` (rare; vision-capable models) | none observed | none observed |
+| Audio | ACP defines `content.type:'audio'`; never observed in stream | TBD | TBD |
+| Files / attachments | ACP defines `content.type:'resource'` and `'resource_link'`; never observed | TBD | TBD |
+| Amalgm | `agent_message_chunk` with `content.type:'image'` only — audio / resource paths exist but unused | TBD | TBD |
+| Gaps | UI image-part path rarely exercised. Tool screenshot outputs (e.g. browser/preview) untested. Audio + file blocks parked in schema, no renderer. |
+
+---
+
+## 15. MCP tool metadata
+
+Branding: server name, app id, icon.
+
+| | Claude Code | Codex | OpenCode |
+|---|---|---|---|
+| Native marker | tool name pattern `mcp__<server>__<tool>` | `mcpToolCall` item with `serverName`, `toolName` | name pattern `mcp__<server>__<tool>` |
+| Amalgm | `tool_call`; UI infers app via `resolveMcpAppMeta()` (3 strategies) | same | same |
+| App branding | `mcpMappings` lookup at UI | same | same |
+| Gaps | No metadata field on the wire — relies on string parsing. If server name ≠ configured app id, branding silently falls through. |
+
+---
+
+## 16. Dropped today
+
+Thrown away at [acpAdapter.ts:147-153](../../../../../amalgm-ui/lib/agents/acpAdapter.ts). Listed so we know what we're losing — not necessarily wrong to drop, but worth tracking.
+
+| | Claude Code | Codex | OpenCode |
+|---|---|---|---|
+| Plan | `system.subtype:'plan'` (Plan Mode) | TBD | TBD |
+| Mode | `current_mode_update` | TBD | TBD |
+| Available commands | `available_commands_update` | TBD | TBD |
+| Config option changes | `config_option_update` | TBD | TBD |
+| User message echo | `user_message_chunk` | TBD | TBD |
+
+If any of these become product-relevant, lift the drop in the ACP adapter and add a UI renderer.
+
+---
+
+## How to fill this in
+
+1. Set `CHAT_CORE_RECORD=1` and run the scenarios from the test plan against each CLI.
+2. For each cell currently `TBD`, find the matching event in the recorder ndjson and replace `TBD` with the real shape.
+3. For each ⚠️ / ❌ row, link the resulting fixture file so future readers can see real data.
+4. When a CLI vendor ships an SDK update that adds new event types, the unmapped-event counter (proposed in critique) will surface them — add a row here and decide whether to map or drop.