amalgm 0.0.0 → 0.0.1

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

@@ -0,0 +1,552 @@
+'use strict';
+
+const { compactionFinished, compactionStarted, done, errorEvent, reasoningDelta, textDelta, toolCompleted, toolStarted, toolUpdated, usageFinal, warningEvent } = require('../events');
+const { stringifyResult, summarizeToolOutput, summarizeToolRequest } = require('../tool-display');
+const { mcpMetadataFromName, normalizeError, titleForTool, toolKind } = require('../tool-shape');
+const { normalizeUsage } = require('../usage');
+
+const CROSS_PART_DEDUPE_MIN_CHARS = 40;
+const CROSS_PART_OVERLAP_MIN_CHARS = 80;
+
+function usageFromOpenCodeTokens(tokens, cost, contextLimit, operation = 'chat_step') {
+  const inputTokens = Number(tokens?.input || 0);
+  const cacheReadTokens = Number(tokens?.cache?.read || 0);
+  const cacheWriteTokens = Number(tokens?.cache?.write || 0);
+  const thoughtTokens = Number(tokens?.reasoning || 0);
+  const outputTokens = Number(tokens?.output || 0) + thoughtTokens;
+  return normalizeUsage({
+    inputTokens,
+    outputTokens,
+    thoughtTokens,
+    cacheReadTokens,
+    cacheWriteTokens,
+    contextLimit,
+    costUsd: cost,
+    operation,
+    source: 'opencode_sdk',
+    exact: true,
+  });
+}
+
+function openCodeErrorMessage(err, fallback = 'OpenCode session error') {
+  if (!err) return fallback;
+  if (typeof err === 'string') return err;
+  if (err.data?.message) return err.data.message;
+  if (err.data?.error?.message) return err.data.error.message;
+  if (err.cause?.message) return err.cause.message;
+  if (err.message) return err.message;
+  if (err.name) return err.name;
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return fallback;
+  }
+}
+
+function openCodeRequestId(prefix, id) {
+  return `${prefix}_${String(id || 'unknown')}`;
+}
+
+function eventRaw(type, payload) {
+  return { raw: { source: 'opencode.sdk.event', method: type || 'unknown', payload } };
+}
+
+function commonPrefixLength(a = '', b = '') {
+  const max = Math.min(a.length, b.length);
+  let index = 0;
+  while (index < max && a[index] === b[index]) index += 1;
+  return index;
+}
+
+function suffixPrefixOverlap(text = '', delta = '') {
+  const max = Math.min(text.length, delta.length);
+  for (let length = max; length > 0; length -= 1) {
+    if (text.endsWith(delta.slice(0, length))) return length;
+  }
+  return 0;
+}
+
+function mergeOpenCodeSnapshot(previousText = '', nextText = '') {
+  const latestText = previousText.length > nextText.length && previousText.startsWith(nextText)
+    ? previousText
+    : nextText;
+  return {
+    latestText,
+    deltaToEmit: latestText.slice(commonPrefixLength(previousText, latestText)),
+  };
+}
+
+function appendOpenCodeDelta(previousText = '', delta = '') {
+  const deltaToEmit = delta.slice(suffixPrefixOverlap(previousText, delta));
+  return {
+    nextText: `${previousText}${deltaToEmit}`,
+    deltaToEmit,
+  };
+}
+
+function dedupeOpenCodeAssistantText(state, text = '') {
+  if (!text) return '';
+  const aggregate = String(state.assistantTextAggregate || '');
+  let emitText = text;
+
+  if (emitText.length >= CROSS_PART_DEDUPE_MIN_CHARS && aggregate.endsWith(emitText)) {
+    emitText = '';
+  } else {
+    const overlap = suffixPrefixOverlap(aggregate, emitText);
+    const mostlyDuplicate =
+      emitText.length >= CROSS_PART_DEDUPE_MIN_CHARS &&
+      overlap > 0 &&
+      (overlap >= CROSS_PART_OVERLAP_MIN_CHARS || overlap / emitText.length >= 0.8);
+    if (mostlyDuplicate) emitText = emitText.slice(overlap);
+  }
+
+  if (emitText) state.assistantTextAggregate = `${aggregate}${emitText}`;
+  return emitText;
+}
+
+function openCodeToolDetail(part) {
+  const toolName = part?.tool || 'unknown';
+  const status = part?.state?.status;
+  if (status === 'completed' || status === 'error') {
+    return summarizeToolOutput(part?.state?.output ?? part?.state?.error ?? '');
+  }
+  return summarizeToolRequest(toolName, part?.state?.input || {}, part?.state?.title || '');
+}
+
+function openCodeToolData(part) {
+  return {
+    tool: part?.tool || 'unknown',
+    state: part?.state || {},
+  };
+}
+
+function openCodeToolMetadata(part) {
+  const toolName = part?.tool || 'unknown';
+  const metadata = {
+    providerTool: toolName,
+    providerStatus: part?.state?.status,
+    ...mcpMetadataFromName(toolName),
+  };
+  const stateMetadata = part?.state?.metadata;
+  if (stateMetadata && typeof stateMetadata === 'object') {
+    Object.assign(metadata, stateMetadata);
+    if (stateMetadata.sessionId) {
+      metadata.childSessionId = stateMetadata.sessionId;
+      metadata.subagent = true;
+    }
+  }
+  if (part?.tool === 'task') metadata.subagent = true;
+  if (part?.state?.title) metadata.title = part.state.title;
+  return metadata;
+}
+
+function openCodeToolError(part) {
+  if (part?.state?.status !== 'error') return undefined;
+  return normalizeError(part?.state?.error || part?.state?.output || 'Tool failed');
+}
+
+function openCodeToolTitle(part) {
+  const toolName = part?.tool || 'unknown';
+  const input = part?.state?.input || {};
+  const metadata = openCodeToolMetadata(part);
+  return titleForTool({
+    name: toolName,
+    input,
+    output: part?.state?.output,
+    error: part?.state?.error,
+    metadata,
+    fallback: part?.state?.title || toolName,
+  });
+}
+
+function stopReasonFromOpenCodeFinish(finish) {
+  if (finish === 'length') return 'max_tokens';
+  if (finish === 'content_filter') return 'content_filter';
+  if (finish === 'error') return 'error';
+  if (finish === 'stop') return 'end_turn';
+  return null;
+}
+
+function pendingParts(state) {
+  if (!state.pendingParts) state.pendingParts = new Map();
+  return state.pendingParts;
+}
+
+function messageRoles(state) {
+  if (!state.messageRoles) state.messageRoles = new Map();
+  return state.messageRoles;
+}
+
+function compactionContinuationMessages(state) {
+  if (!state.compactionContinuationMessageIds) state.compactionContinuationMessageIds = new Set();
+  return state.compactionContinuationMessageIds;
+}
+
+function rememberCompactionContinuation(part, state) {
+  if (part?.messageID) compactionContinuationMessages(state).add(part.messageID);
+}
+
+function isOpenCodeInternalUsage(info, state) {
+  if (!info || info.sessionID !== state.providerSessionId || info.role !== 'assistant') return false;
+  if (info.mode === 'compaction' || info.agent === 'compaction') return true;
+  return Boolean(info.parentID && state.compactionContinuationMessageIds?.has(info.parentID));
+}
+
+function cachePendingPart(part, state, delta) {
+  if (!part?.id) return;
+  const cache = pendingParts(state);
+  const previous = cache.get(part.id)?.part || part;
+  const next = { ...previous, ...part };
+  if (typeof delta === 'string' && (part.type === 'text' || part.type === 'reasoning')) {
+    const base = String(previous.text || part.text || '');
+    const merged = appendOpenCodeDelta(base, delta);
+    next.text = merged.nextText;
+  }
+  cache.set(part.id, { part: next, delta: undefined });
+}
+
+function dropPendingParts(messageId, state) {
+  const cache = pendingParts(state);
+  for (const [partId, entry] of [...cache.entries()]) {
+    if (entry.part?.messageID === messageId) cache.delete(partId);
+  }
+}
+
+function flushPendingParts(messageId, state) {
+  const cache = pendingParts(state);
+  const events = [];
+  for (const [partId, entry] of [...cache.entries()]) {
+    if (entry.part?.messageID !== messageId) continue;
+    cache.delete(partId);
+    events.push(...normalizeOpenCodePart(entry.part, state, entry.delta));
+  }
+  return events;
+}
+
+function normalizeOpenCodePart(part, state, delta) {
+  if (!part || part.sessionID !== state.providerSessionId) return [];
+  if (part.type === 'compaction') {
+    if (part.tail_start_id) return [];
+    if (!state.compactionsStarted) state.compactionsStarted = new Set();
+    const compactionId = part.id || part.messageID || 'opencode-compaction';
+    if (state.compactionsStarted.has(compactionId)) return [];
+    state.compactionsStarted.add(compactionId);
+    return [compactionStarted({
+      providerSessionId: state.providerSessionId,
+      trigger: part.auto === false ? 'manual' : 'auto',
+      ...eventRaw('part/compaction', part),
+    })];
+  }
+  if (!state.assistantMessageIds.has(part.messageID)) return [];
+  if (part.id && part.type) {
+    if (!state.partTypes) state.partTypes = new Map();
+    state.partTypes.set(part.id, part.type);
+  }
+  if (part.metadata?.compaction_continue) {
+    rememberCompactionContinuation(part, state);
+    return [];
+  }
+  const seen = state.partText.get(part.id) || '';
+  if (part.type === 'text') {
+    const merged = typeof delta === 'string'
+      ? appendOpenCodeDelta(seen, delta)
+      : mergeOpenCodeSnapshot(seen, String(part.text || ''));
+    const text = dedupeOpenCodeAssistantText(state, merged.deltaToEmit);
+    state.partText.set(part.id, merged.latestText || merged.nextText || `${seen}${text}`);
+    return text ? [textDelta(text, { providerSessionId: state.providerSessionId, ts: part.time?.start, ...eventRaw(`part/${part.type}`, part) })] : [];
+  }
+  if (part.type === 'reasoning') {
+    const merged = typeof delta === 'string'
+      ? appendOpenCodeDelta(seen, delta)
+      : mergeOpenCodeSnapshot(seen, String(part.text || ''));
+    const text = merged.deltaToEmit;
+    state.partText.set(part.id, merged.latestText || merged.nextText || `${seen}${text}`);
+    return text ? [reasoningDelta(text, { providerSessionId: state.providerSessionId, ts: part.time?.start, ...eventRaw(`part/${part.type}`, part) })] : [];
+  }
+  if (part.type === 'tool') {
+    const toolId = part.callID || part.id;
+    const status = part.state?.status;
+    const toolName = part.tool || 'unknown';
+    const input = part.state?.input || {};
+    const metadata = openCodeToolMetadata(part);
+    const title = openCodeToolTitle(part);
+    const kind = toolKind(toolName, input, metadata);
+    const timing = part.state?.time || part.time;
+    if (status === 'pending' || status === 'running') {
+      const detail = openCodeToolDetail(part);
+      if (state.toolsStarted.has(toolId)) {
+        return [toolUpdated(toolId, {
+          providerSessionId: state.providerSessionId,
+          toolName,
+          title,
+          kind,
+          detail,
+          inputDelta: input,
+          status: 'in_progress',
+          metadata,
+          timing,
+          data: openCodeToolData(part),
+          ...eventRaw('part/tool', part),
+        })];
+      }
+      state.toolsStarted.add(toolId);
+      return [toolStarted(toolId, {
+        providerSessionId: state.providerSessionId,
+        toolName,
+        title,
+        kind,
+        detail,
+        input,
+        ts: part.state?.time?.start,
+        metadata,
+        timing,
+        data: openCodeToolData(part),
+        ...eventRaw('part/tool', part),
+      })];
+    }
+    if ((status === 'completed' || status === 'error') && !state.toolsCompleted.has(toolId)) {
+      state.toolsCompleted.add(toolId);
+      const output = part.state?.output ?? part.state?.error ?? '';
+      const detail = openCodeToolDetail(part);
+      return [toolCompleted(toolId, {
+        providerSessionId: state.providerSessionId,
+        toolName,
+        title,
+        kind,
+        detail,
+        input,
+        output,
+        result: stringifyResult(output),
+        isError: status === 'error',
+        error: openCodeToolError(part),
+        ts: part.state?.time?.end,
+        metadata,
+        timing,
+        data: openCodeToolData(part),
+        ...eventRaw('part/tool', part),
+      })];
+    }
+  }
+  if (part.type === 'step-finish') {
+    const stopReason = stopReasonFromOpenCodeFinish(part.reason);
+    if (stopReason) state.pendingStopReason = stopReason;
+    return [usageFinal(usageFromOpenCodeTokens(part.tokens, part.cost, state.contextLimit), { providerSessionId: state.providerSessionId, ...eventRaw('part/step-finish', part) })];
+  }
+  return [];
+}
+
+function isOurAssistant(info, state) {
+  if (!info || info.sessionID !== state.providerSessionId || info.role !== 'assistant') return false;
+  if (state.userMessageId && info.parentID && info.parentID !== state.userMessageId) return false;
+  const created = Number(info.time?.created || 0);
+  if (state.turnStartedAt && created && created < state.turnStartedAt) return false;
+  return true;
+}
+
+function normalizeOpenCodeEvent(event, state) {
+  const payload = event?.payload || event;
+  if (!payload || typeof payload !== 'object') return [];
+  const raw = eventRaw(payload.type, event);
+  if (payload.type === 'message.updated') {
+    const info = payload.properties?.info;
+    if (info?.id && info.sessionID === state.providerSessionId && info.role) {
+      messageRoles(state).set(info.id, info.role);
+      if (info.role === 'user') {
+        const created = Number(info.time?.created || 0);
+        const isCurrentTurnUser = !state.turnStartedAt || !created || created >= state.turnStartedAt;
+        if (!state.userMessageId && isCurrentTurnUser) state.userMessageId = info.id;
+        dropPendingParts(info.id, state);
+        return [];
+      }
+    }
+  }
+  if (payload.type === 'message.part.delta') {
+    const props = payload.properties || {};
+    const delta = typeof props.delta === 'string' ? props.delta : '';
+    if (!delta) return [];
+    if (!state.assistantMessageIds.has(props.messageID)) {
+      const pending = state.pendingParts?.get(props.partID);
+      if (pending?.part) cachePendingPart(pending.part, state, delta);
+      return [];
+    }
+    const knownType = state.partTypes?.get(props.partID);
+    const previous = state.partText.get(props.partID) || '';
+    const merged = appendOpenCodeDelta(previous, delta);
+    state.partText.set(props.partID, merged.nextText);
+    if (!merged.deltaToEmit) return [];
+    if (knownType === 'text' || (!knownType && props.field === 'text')) {
+      const text = dedupeOpenCodeAssistantText(state, merged.deltaToEmit);
+      return text ? [textDelta(text, { providerSessionId: state.providerSessionId, ts: payload.time || payload.properties?.time, ...raw })] : [];
+    }
+    if (knownType === 'reasoning' || props.field === 'reasoning' || props.field === 'thinking') {
+      return [reasoningDelta(merged.deltaToEmit, { providerSessionId: state.providerSessionId, ...raw })];
+    }
+    return [];
+  }
+  if (payload.type === 'message.part.updated') {
+    const part = payload.properties?.part;
+    if (part?.id && part?.type) {
+      if (!state.partTypes) state.partTypes = new Map();
+      state.partTypes.set(part.id, part.type);
+    }
+    if (part?.metadata?.compaction_continue) {
+      rememberCompactionContinuation(part, state);
+      return [];
+    }
+    const role = part?.messageID ? state.messageRoles?.get(part.messageID) : undefined;
+    if (role && role !== 'assistant') return [];
+    if (part?.type === 'compaction') return normalizeOpenCodePart(part, state, payload.properties?.delta);
+    if (part?.messageID && !state.assistantMessageIds.has(part.messageID)) {
+      cachePendingPart(part, state, payload.properties?.delta);
+      return [];
+    }
+    const events = normalizeOpenCodePart(part, state, payload.properties?.delta);
+    if (part?.type === 'step-finish' && part.messageID) state.usageEmittedForAssistant.add(part.messageID);
+    return events;
+  }
+  if (payload.type === 'message.updated') {
+    const info = payload.properties?.info;
+    if (isOpenCodeInternalUsage(info, state)) {
+      if (info.id && info.tokens && (info.finish || info.time?.completed)) {
+        if (state.finishedAssistantIds.has(info.id)) return [];
+        state.finishedAssistantIds.add(info.id);
+        const operation = info.mode === 'compaction' || info.agent === 'compaction' ? 'compaction' : 'chat_step';
+        return [usageFinal(usageFromOpenCodeTokens(info.tokens, info.cost, state.contextLimit, operation), { providerSessionId: state.providerSessionId, ...raw })];
+      }
+      return [];
+    }
+    if (!isOurAssistant(info, state)) return [];
+    if (info.id) {
+      state.assistantMessageIds.add(info.id);
+      state.sawTurnActivity = true;
+    }
+    const flushed = info.id ? flushPendingParts(info.id, state) : [];
+    if (info.tokens && (info.finish || info.time?.completed)) {
+      if (state.finishedAssistantIds.has(info.id)) return [];
+      state.finishedAssistantIds.add(info.id);
+      const events = [...flushed];
+      if (!state.usageEmittedForAssistant.has(info.id)) {
+        state.usageEmittedForAssistant.add(info.id);
+        events.push(usageFinal(usageFromOpenCodeTokens(info.tokens, info.cost, state.contextLimit), { providerSessionId: state.providerSessionId, ...raw }));
+      }
+      if (!state.doneEmitted && (info.finish === 'stop' || info.finish === 'length' || info.finish === 'content_filter')) {
+        state.pendingStopReason = stopReasonFromOpenCodeFinish(info.finish) || 'end_turn';
+      }
+      return events;
+    }
+    return flushed;
+  }
+  if (payload.type === 'session.compacted' && payload.properties?.sessionID === state.providerSessionId) {
+    return [compactionFinished({
+      providerSessionId: state.providerSessionId,
+      trigger: 'auto',
+      ...raw,
+    })];
+  }
+  if (payload.type === 'session.error' && payload.properties?.sessionID === state.providerSessionId) {
+    const err = payload.properties?.error;
+    const message = openCodeErrorMessage(err);
+    if (state.doneEmitted) return [errorEvent(message, { providerSessionId: state.providerSessionId, ...raw })];
+    state.doneEmitted = true;
+    return [errorEvent(message, { providerSessionId: state.providerSessionId, ...raw }), done({ providerSessionId: state.providerSessionId, stopReason: 'error', ...raw })];
+  }
+  if (payload.type === 'permission.asked' || payload.type === 'permission.replied') return [];
+  if (payload.type === 'question.asked') {
+    const props = payload.properties || {};
+    if (props.sessionID && props.sessionID !== state.providerSessionId) return [];
+    const id = openCodeRequestId('question', props.id);
+    return [toolStarted(id, {
+      providerSessionId: state.providerSessionId,
+      toolName: 'AskUserQuestion',
+      title: 'Question',
+      kind: 'question',
+      detail: 'Question',
+      input: {
+        questions: props.questions || props.question || [],
+      },
+      metadata: { providerEvent: payload.type, question: true },
+      data: { question: props },
+      ts: payload.time,
+      ...raw,
+    })];
+  }
+  if (payload.type === 'question.replied' || payload.type === 'question.rejected') {
+    const props = payload.properties || {};
+    if (props.sessionID && props.sessionID !== state.providerSessionId) return [];
+    const id = openCodeRequestId('question', props.requestID || props.id);
+    const rejected = payload.type === 'question.rejected';
+    return [toolCompleted(id, {
+      providerSessionId: state.providerSessionId,
+      toolName: 'AskUserQuestion',
+      title: 'Question',
+      kind: 'question',
+      detail: rejected ? 'Question rejected' : 'Question answered',
+      result: rejected ? 'Question rejected' : JSON.stringify(props.answers || {}),
+      output: props,
+      isError: rejected,
+      error: rejected ? normalizeError('Question rejected') : undefined,
+      metadata: { providerEvent: payload.type, question: true },
+      data: { question: props },
+      ts: payload.time,
+      ...raw,
+    })];
+  }
+  if ((payload.type === 'session.idle' || payload.type === 'session.status') && payload.properties?.sessionID === state.providerSessionId) {
+    const status = payload.properties?.status;
+    if (status?.type === 'busy' || status === 'busy') state.sawBusy = true;
+    if (status?.type === 'retry') {
+      const attempt = status.attempt ?? status.count ?? status.retry ?? '?';
+      const reason = status.message || openCodeErrorMessage(status.error, 'unknown upstream error');
+      const message = `OpenCode upstream retrying: ${reason} (attempt ${attempt})`;
+      return [warningEvent(message, { providerSessionId: state.providerSessionId, ...raw })];
+    }
+    if ((!status || status === 'idle' || status?.type === 'idle') && state.sawTurnActivity && !state.doneEmitted) {
+      state.doneEmitted = true;
+      return [done({ providerSessionId: state.providerSessionId, stopReason: state.pendingStopReason, ...raw })];
+    }
+  }
+  return [];
+}
+
+function normalizeOpenCodePromptResult(data, state) {
+  const raw = eventRaw('prompt.result', data);
+  const resultError = data?.error || data?.info?.error;
+  if (resultError) {
+    const message = openCodeErrorMessage(resultError);
+    if (state.doneEmitted) return [errorEvent(message, { providerSessionId: state.providerSessionId, ...raw })];
+    state.doneEmitted = true;
+    return [errorEvent(message, { providerSessionId: state.providerSessionId, ...raw }), done({ providerSessionId: state.providerSessionId, stopReason: 'error', ...raw })];
+  }
+  const info = data?.info;
+  if (!info?.id) return [];
+  if (!isOurAssistant(info, state)) return [];
+  state.assistantMessageIds.add(info.id);
+  state.sawTurnActivity = true;
+  const events = [];
+  for (const part of data.parts || []) {
+    events.push(...normalizeOpenCodePart(part, state));
+  }
+  const finished = Boolean(info.finish || info.time?.completed);
+  if (!finished) return events;
+  if (info.tokens && !state.usageEmittedForAssistant.has(info.id)) {
+    state.usageEmittedForAssistant.add(info.id);
+    events.push(usageFinal(usageFromOpenCodeTokens(info.tokens, info.cost, state.contextLimit), { providerSessionId: state.providerSessionId, ...raw }));
+  }
+  if (!state.doneEmitted) {
+    state.doneEmitted = true;
+    const stopReason = info.finish === 'length' ? 'max_tokens'
+      : info.finish === 'content_filter' ? 'content_filter'
+      : 'end_turn';
+    events.push(done({ providerSessionId: state.providerSessionId, stopReason, ...raw }));
+  }
+  return events;
+}
+
+module.exports = {
+  normalizeOpenCodeEvent,
+  normalizeOpenCodePart,
+  normalizeOpenCodePromptResult,
+  openCodeErrorMessage,
+  suffixPrefixOverlap,
+  usageFromOpenCodeTokens,
+};

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

@@ -0,0 +1,123 @@
+# Tool normalization contract
+
+This contract is only for tool parts. Text and reasoning normalization stay as-is.
+
+## Canonical shape
+
+Every provider tool event should normalize toward this shape:
+
+```ts
+type ToolState = 'started' | 'running' | 'complete' | 'error';
+
+type ToolKind =
+  | 'web_search'
+  | 'browser'
+  | 'file_read'
+  | 'file_write'
+  | 'file_edit'
+  | 'bash'
+  | 'subagent'
+  | 'mcp'
+  | 'question'
+  | 'todo'
+  | 'unknown';
+
+type NormalizedToolPart = {
+  id: string;
+  name: string;      // canonical machine-ish name: Bash, Read, webSearch, browser_navigate
+  kind: ToolKind;    // stable UI bucket for icon/grouping
+  title: string;     // human title shown in UI
+  input: unknown;    // provider args, normalized only enough to be inspectable
+  output?: unknown;  // successful result, if present
+  error?: {
+    message: string;
+    code?: string;
+    details?: unknown;
+  };
+  state: ToolState;
+  timing?: {
+    startedAt?: string | number;
+    completedAt?: string | number;
+    elapsedMs?: number;
+  };
+  metadata?: Record<string, unknown>; // provider-specific detail that UI may use later
+};
+```
+
+## Rules
+
+1. `id` must be stable for the whole lifecycle.
+2. `name` is the normalized tool identity. It should not be guessed from input if
+   the provider gave an explicit tool name.
+3. `kind` is a small taxonomy for UI rendering. It is not the provider tool name.
+4. `title` is the human line. Prefer action text over raw names.
+5. `input` should preserve meaningful args: command, cwd, path, query, url,
+   prompt, MCP arguments.
+6. `output` is only successful result data.
+7. `error` is only failure data. Do not force errors into `output`.
+8. `metadata` preserves useful provider detail without expanding the core shape:
+   MCP server/tool, Codex action type, Claude task id, OpenCode child session id,
+   provider raw item type, attachments, truncation flags.
+9. Avoid persisting giant raw provider blobs in `metadata`. Keep raw fixtures in
+   the recorder/audit layer.
+
+## Title examples
+
+| Native source | Title |
+| --- | --- |
+| Codex `webSearch.action.type = "search"` | `Searching Reuters top news` |
+| Codex `webSearch.action.type = "openPage"` | `Opening apnews.com` |
+| Codex `webSearch.action.type = "findInPage"` | `Finding "Updated" on apnews.com` |
+| Codex `mcpToolCall` `{ server:"amalgm", tool:"browser_snapshot" }` | `Reading browser page` |
+| Codex `mcpToolCall` `{ server:"amalgm", tool:"browser_navigate" }` | `Opening browser page` |
+| Claude `mcp__amalgm__artifacts_register` | `Registering artifact Spotify Clone` |
+| OpenCode `amalgm_browser_tabs_new` | `Opening browser tab` |
+| OpenCode `task` with description | `Research Northern India politics` |
+
+## Provider mapping targets
+
+### Claude Code
+
+- `tool_use.name` -> `name`
+- `tool_use.input` -> `input`
+- `tool_result.content` -> `output`
+- `tool_result.is_error` -> `error`
+- `mcp__<server>__<tool>` -> `metadata.mcp = { server, tool }`
+- `task_started/task_progress/task_completed` -> `kind: "subagent"` or
+  `metadata.task`, without changing text/reasoning.
+
+### Codex
+
+- `item.id` -> `id`
+- `item.type` + explicit tool fields -> `name` / `kind`
+- `item.arguments` or provider args -> `input`
+- `item.result` / `aggregatedOutput` / `diff` -> `output`
+- `item.error` or failed status -> `error`
+- `item.durationMs` -> `timing.elapsedMs`
+- `mcpToolCall.server/tool` -> `metadata.mcp`
+- `webSearch.action` -> `metadata.action` and title derivation
+- `collabAgentToolCall` -> `kind: "subagent"`
+
+### OpenCode
+
+- `part.callID || part.id` -> `id`
+- `part.tool` -> `name`
+- `part.state.input` -> `input`
+- `part.state.output` -> `output`
+- `part.state.error` -> `error`
+- `part.state.time` -> `timing`
+- `part.state.metadata.actionDescriptor` -> preferred `title`
+- `part.state.metadata.sessionId` on `task` -> `metadata.childSessionId`
+
+## Compatibility path
+
+The first implementation should add fields without breaking existing consumers:
+
+1. Engine emits richer tool events.
+2. ACP frames carry `toolName`, `kind`, `title`, `rawInput`, `rawOutput`,
+   `error`, `metadata`, `timing`.
+3. UI maps these into the existing `ToolPart` while keeping old
+   `calling/output-available/output-error` state names until the renderer is
+   ready to switch.
+4. Once fixtures pass, rename UI state internally to
+   `started/running/complete/error`.