@awak-app/simy-cli 0.1.0 → 0.1.2

package/src/orchestrator/loop.js

@@ -4,7 +4,7 @@ import {
   buildIndependentAuditInstruction,
 } from "./independent-audit.js";
 import { buildCodingInstruction, buildPromptInterventions } from "./instruction.js";
-import { buildAttempt } from "./result.js";
+import { buildAttempt, mergeTokenUsage } from "./result.js";
 import { appendEvent, publish } from "./shared.js";
 
 export async function runCodingLoop({
@@ -13,41 +13,53 @@ export async function runCodingLoop({
   executeIndependentAudit,
   collectEvidence,
   onUpdate,
+  humanGuidance = "",
+  resume = false,
+  shouldStop = () => false,
+  consumeHumanGuidance = () => "",
 }) {
-  appendEvent(snapshot, "risk_classifying", "PR risk classification completed.", {
-    risk: snapshot.charter.risk,
-  });
-  await publish(snapshot, "risk_classifying", onUpdate);
+  if (!resume || snapshot.attempts.length === 0) {
+    appendEvent(snapshot, "risk_classifying", "PR risk classification completed.", {
+      risk: snapshot.charter.risk,
+    });
+    await publish(snapshot, "risk_classifying", onUpdate);
 
-  const charterFindings = validateCharter(snapshot.charter);
-  if (charterFindings.length > 0) {
-    snapshot.final_audit = humanGate(
-      "Requirements or design review must be completed before implementation.",
-      charterFindings,
-    );
-    appendEvent(snapshot, "waiting_human", "Requirements require human clarification.", {
-      finding_codes: charterFindings.map((finding) => finding.code),
+    const charterFindings = validateCharter(snapshot.charter);
+    if (charterFindings.length > 0) {
+      snapshot.final_audit = humanGate(
+        "Requirements or design review must be completed before implementation.",
+        charterFindings,
+      );
+      appendEvent(snapshot, "waiting_human", "Requirements require human clarification.", {
+        finding_codes: charterFindings.map((finding) => finding.code),
+      });
+      await publish(snapshot, "waiting_human", onUpdate);
+      return snapshot;
+    }
+
+    appendEvent(snapshot, "chartering", "Requirement charter created locally.", {
+      charter_id: snapshot.charter.id,
+      base_branch: snapshot.charter.base_branch,
+      risk_level: snapshot.charter.risk.level,
     });
-    await publish(snapshot, "waiting_human", onUpdate);
-    return snapshot;
+    await publish(snapshot, "chartering", onUpdate);
   }
 
-  appendEvent(snapshot, "chartering", "Requirement charter created locally.", {
-    charter_id: snapshot.charter.id,
-    base_branch: snapshot.charter.base_branch,
-    risk_level: snapshot.charter.risk.level,
-  });
-  await publish(snapshot, "chartering", onUpdate);
-
-  let previousFindings = [];
+  let previousFindings = resume ? snapshot.final_audit?.findings || [] : [];
+  const firstAttempt = resume ? snapshot.attempts.length + 1 : 1;
+  const lastAttempt = resume ? firstAttempt : snapshot.charter.max_attempts;
   for (
-    let attemptNumber = 1;
-    attemptNumber <= snapshot.charter.max_attempts;
+    let attemptNumber = firstAttempt;
+    attemptNumber <= lastAttempt;
     attemptNumber += 1
   ) {
+    if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
+    const queuedGuidance = consumeHumanGuidance();
+    const attemptGuidance = [humanGuidance, queuedGuidance].filter(Boolean).join("\n\n");
     const promptInterventions = buildPromptInterventions(snapshot.charter, {
       attemptNumber,
       previousFindings,
+      humanGuidance: attemptGuidance,
     });
     const instruction = buildCodingInstruction(snapshot.charter, {
       attemptNumber,
@@ -78,6 +90,7 @@ export async function runCodingLoop({
         charter: snapshot.charter,
       }),
     );
+    if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
     const attempt = buildAttempt({
       attemptNumber,
       charter: snapshot.charter,
@@ -88,6 +101,11 @@ export async function runCodingLoop({
 
     appendEvent(snapshot, "collecting_evidence", `Collecting attempt ${attemptNumber} evidence.`, {
       attempt_number: attemptNumber,
+      outcome_kind: attempt.outcome_kind,
+      branch_name: attempt.branch_name,
+      commit_sha: attempt.commit_sha,
+      pr_url: attempt.pr_url,
+      tests_run: attempt.tests_run,
     });
     await publish(snapshot, "collecting_evidence", onUpdate);
     attempt.observed_evidence = await safeEvidence(collectEvidence, attempt);
@@ -95,6 +113,12 @@ export async function runCodingLoop({
     appendEvent(snapshot, "auditing", `Verifying local evidence for attempt ${attemptNumber}.`, {
       attempt_number: attemptNumber,
       outcome_kind: attempt.outcome_kind,
+      tests_run: attempt.tests_run,
+      tests_passed: attempt.tests_passed,
+      changed_files: attempt.raw_output?.changed_files,
+      evidence_available:
+        attempt.observed_evidence?.local?.available === true ||
+        attempt.observed_evidence?.github?.available === true,
     });
     await publish(snapshot, "auditing", onUpdate);
     attempt.audit = await auditAttempt(snapshot.charter, attempt);
@@ -121,6 +145,7 @@ export async function runCodingLoop({
       backend: snapshot.charter.audit_backend,
     });
     await publish(snapshot, "independent_auditing", onUpdate);
+    if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
     const auditInstruction = buildIndependentAuditInstruction(snapshot.charter, attempt);
     const auditExecution = await safeExecution(() =>
       executeIndependentAudit({
@@ -131,7 +156,9 @@ export async function runCodingLoop({
         attempt,
       }),
     );
+    if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
     attempt.independent_audit = buildIndependentAudit(auditExecution);
+    attempt.token_usage = mergeTokenUsage(attempt.token_usage, auditExecution.tokenUsage);
 
     // Re-collect after the read-only auditor to catch any mutated HEAD or working tree.
     attempt.observed_evidence = await safeEvidence(collectEvidence, attempt);
@@ -177,6 +204,15 @@ export async function runCodingLoop({
   return snapshot;
 }
 
+async function stopCodingLoop(snapshot, onUpdate) {
+  if (snapshot.state === "stopped") return snapshot;
+  appendEvent(snapshot, "stopped", "Coding loop stopped by the local human operator.", {
+    source: "local_cli",
+  });
+  await publish(snapshot, "stopped", onUpdate);
+  return snapshot;
+}
+
 export async function recheckPrReadiness({ snapshot, collectEvidence, onUpdate }) {
   const attempt = snapshot.attempts.at(-1);
   if (!attempt || !attempt.audit?.passed || !attempt.independent_audit?.passed) return snapshot;

package/src/orchestrator/presentation.js

@@ -0,0 +1,189 @@
+import { cleanString } from "./shared.js";
+
+export function summarizeCodingLoopEvent(snapshot, event) {
+  const detail = objectValue(event?.detail);
+  const state = cleanString(detail.pr_lifecycle_state) || cleanString(event?.state);
+  const explicit = {
+    summary: cleanString(detail.step_summary),
+    result: cleanString(detail.step_result),
+    next: cleanString(detail.next_action),
+  };
+  if (explicit.summary) return explicit;
+
+  const charter = objectValue(snapshot?.charter);
+  const attemptNumber = numberValue(detail.attempt_number) || latestAttemptNumber(snapshot);
+  const maxAttempts = numberValue(charter.max_attempts) || 1;
+  const executor = executorLabel(detail.backend || charter.backend);
+  const repository = cleanString(charter.repository) || "the selected repository";
+  const branch = cleanString(detail.branch_name || charter.base_branch) || "the selected branch";
+  const requirement = sentencePreview(charter.requirement, 120) || "the requested change";
+  const findings = stringArray(detail.finding_codes);
+  const pendingReasons = stringArray(detail.pending_reasons);
+
+  switch (state) {
+    case "queued":
+      return {
+        summary: `Task recorded for local execution in ${repository} on ${branch}.`,
+        result: `Goal: ${requirement}`,
+        next: "SIMY will classify risk and turn the request into an execution charter.",
+      };
+    case "risk_classifying": {
+      const risk = objectValue(detail.risk || charter.risk);
+      const level = cleanString(risk.level) || "unknown";
+      return {
+        summary: `Risk classified as ${level}; the required review gates are now known.`,
+        result: risk.requires_design_review
+          ? "A design review is required before implementation."
+          : "No pre-implementation design review is required.",
+        next: "SIMY will finalize scope, acceptance criteria, tests, and evidence requirements.",
+      };
+    }
+    case "chartering":
+      return {
+        summary: `Execution scope set for: ${requirement}`,
+        result: `${countLabel(charter.acceptance_criteria, "acceptance criterion")}, ${countLabel(charter.expected_tests, "expected test")}, and ${countLabel(charter.expected_evidence, "evidence requirement")}.`,
+        next: `Attempt 1 of ${maxAttempts} will be handed to ${executor}.`,
+      };
+    case "dispatching":
+      return {
+        summary: `Preparing ${executor} attempt ${attemptNumber}/${maxAttempts} for ${branch}.`,
+        result: "The executor instruction now includes the task, constraints, checks, and prior findings.",
+        next: `${executor} will start the local coding process.`,
+      };
+    case "coding":
+      return {
+        summary: `${executor} is implementing attempt ${attemptNumber}/${maxAttempts} on ${branch}.`,
+        result: "Live provider output is shown below as the local process works.",
+        next: "When execution finishes, SIMY will collect code, test, PR, and UI evidence.",
+      };
+    case "collecting_evidence":
+      return {
+        summary: `Attempt ${attemptNumber} finished; SIMY is collecting verifiable implementation evidence.`,
+        result: listResult(detail.tests_run, "Checks to verify", "Checks will be read from the executor result and repository."),
+        next: "The evidence will be checked against the original requirement and acceptance criteria.",
+      };
+    case "auditing":
+      return {
+        summary: `SIMY is verifying attempt ${attemptNumber} against the requirement and recorded evidence.`,
+        result: evidenceResult(detail),
+        next: "A passing implementation proceeds to an independent AI review; findings trigger repair or human input.",
+      };
+    case "independent_auditing":
+      return {
+        summary: `${executorLabel(detail.backend || charter.audit_backend)} is independently reviewing attempt ${attemptNumber}.`,
+        result: "The reviewer uses the frozen instruction, diff, checks, and evidence rather than the implementer's conclusion.",
+        next: "SIMY will combine both audits and decide whether the PR is ready for human review.",
+      };
+    case "checking_pr":
+      return {
+        summary: "SIMY is refreshing the latest GitHub review and CI evidence.",
+        result: "The existing PR, commit, approvals, mergeability, and required checks are being re-read.",
+        next: "The run will move to merge-ready when every required gate passes.",
+      };
+    case "re_instructing":
+      return {
+        summary: `Attempt ${attemptNumber} needs another coding pass before review.`,
+        result: findingResult(findings),
+        next: `SIMY will give the findings to ${executor} for attempt ${Math.min(attemptNumber + 1, maxAttempts)}/${maxAttempts}.`,
+      };
+    case "pr_ready_for_review":
+      return {
+        summary: "Implementation is complete, but the PR still needs human review or external evidence.",
+        result: pendingReasons.length ? `Pending: ${pendingReasons.join("; ")}` : cleanString(event?.message),
+        next: "Review or approve the PR, then refresh its evidence from Web or CLI.",
+      };
+    case "merge_ready":
+      return {
+        summary: "Implementation, checks, evidence, and required review gates have passed.",
+        result: cleanString(detail.pr_url) ? `Merge-ready PR: ${detail.pr_url}` : "The recorded PR is ready to merge.",
+        next: "A human can merge the PR when the release timing is appropriate.",
+      };
+    case "waiting_human":
+      return {
+        summary: "The automated loop is paused because a human decision or missing input is required.",
+        result: findings.length ? findingResult(findings) : cleanString(snapshot?.final_audit?.summary || event?.message),
+        next: "Provide guidance or approval in Web or CLI to continue the same run.",
+      };
+    case "blocked":
+      return {
+        summary: "The run cannot continue automatically with its current attempt budget or evidence.",
+        result: findings.length ? findingResult(findings) : cleanString(event?.message),
+        next: "Review the findings, adjust the request or evidence, and resume the run.",
+      };
+    case "failed":
+      return {
+        summary: "Local orchestration stopped before the requested outcome was verified.",
+        result: cleanString(detail.error || event?.message),
+        next: "Fix the reported problem, then retry or continue the run.",
+      };
+    case "stopped":
+      return {
+        summary: "The local human operator stopped this coding run.",
+        result: "No further executor handoff will occur for this run.",
+        next: "Start a new run or explicitly continue this one when ready.",
+      };
+    default:
+      return {
+        summary: cleanString(event?.message) || "SIMY recorded a coding lifecycle update.",
+        result: "Open details for the complete structured record.",
+        next: "SIMY will continue from the latest recorded state.",
+      };
+  }
+}
+
+function evidenceResult(detail) {
+  const testsPassed = detail.tests_passed;
+  const changedFiles = stringArray(detail.changed_files);
+  const parts = [];
+  if (testsPassed === true) parts.push("reported checks passed");
+  if (testsPassed === false) parts.push("one or more reported checks failed");
+  if (changedFiles.length) parts.push(`${changedFiles.length} changed ${changedFiles.length === 1 ? "file" : "files"} recorded`);
+  return parts.length ? `${capitalize(parts.join("; "))}.` : "SIMY is checking the code result, tests, PR facts, and any required UI evidence.";
+}
+
+function findingResult(findings) {
+  return findings.length ? `Findings: ${findings.join(", ")}.` : "The audit recorded findings that require attention.";
+}
+
+function listResult(values, label, fallback) {
+  const items = stringArray(values);
+  return items.length ? `${label}: ${items.join(", ")}.` : fallback;
+}
+
+function countLabel(values, singular) {
+  const count = Array.isArray(values) ? values.length : 0;
+  const plural = singular === "acceptance criterion" ? "acceptance criteria" : `${singular}s`;
+  return `${count} ${count === 1 ? singular : plural}`;
+}
+
+function latestAttemptNumber(snapshot) {
+  const attempts = Array.isArray(snapshot?.attempts) ? snapshot.attempts : [];
+  return numberValue(attempts.at(-1)?.attempt_number) || 1;
+}
+
+function executorLabel(value) {
+  return cleanString(value) === "claude" ? "Claude Code" : "Codex";
+}
+
+function sentencePreview(value, maxLength) {
+  const text = cleanString(value).replace(/\s+/g, " ");
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength - 3).trimEnd()}...`;
+}
+
+function stringArray(value) {
+  return Array.isArray(value) ? value.map(cleanString).filter(Boolean) : [];
+}
+
+function numberValue(value) {
+  const number = Number.parseInt(String(value ?? ""), 10);
+  return Number.isFinite(number) && number > 0 ? number : 0;
+}
+
+function objectValue(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function capitalize(value) {
+  return value ? `${value[0].toUpperCase()}${value.slice(1)}` : value;
+}

package/src/orchestrator/result.js

@@ -44,6 +44,13 @@ export function buildAttempt({ attemptNumber, charter, instruction, promptInterv
   };
 }
 
+export function mergeTokenUsage(...values) {
+  const records = values.flatMap((value) =>
+    Array.isArray(value?.records) ? value.records.filter(isUsageRecord) : [],
+  );
+  return records.length > 0 ? { records } : {};
+}
+
 export function parseStructuredResult(text) {
   return parseStructuredMarker(text, "SIMY_RESULT_JSON:");
 }
@@ -89,3 +96,7 @@ function buildArtifactPreviews(result) {
       : null,
   ].filter(Boolean);
 }
+
+function isUsageRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/src/provider-stream.js

@@ -0,0 +1,310 @@
+import { stripVTControlCharacters } from "node:util";
+
+const MAX_LINE_CHARS = 2_000;
+const STRUCTURED_MARKERS = ["SIMY_RESULT_JSON:", "SIMY_AUDIT_JSON:"];
+
+export function createProviderStreamDecoder({ backend, stream = "stdout", onLine, onUsage }) {
+  let pending = "";
+  let previous = "";
+  let model = "";
+
+  function consume(value) {
+    const text = stripVTControlCharacters(String(value || "")).trim();
+    if (!text || STRUCTURED_MARKERS.some((marker) => text.startsWith(marker))) return;
+
+    let event;
+    try {
+      event = JSON.parse(text);
+    } catch {
+      emit(formatPlainLine(backend, stream, text));
+      return;
+    }
+
+    model = providerModel(backend, event) || model;
+    const usage = extractProviderTokenUsage(backend, event, { model });
+    if (usage && onUsage) onUsage(usage);
+
+    for (const line of formatProviderEvent(backend, event)) emit(line);
+  }
+
+  function emit(line) {
+    const text = cleanLine(line);
+    if (!text || text === previous) return;
+    previous = text;
+    onLine(text);
+  }
+
+  return {
+    push(chunk) {
+      pending += String(chunk || "");
+      const lines = pending.split(/\r?\n/);
+      pending = lines.pop() || "";
+      for (const line of lines) consume(line);
+    },
+    flush() {
+      consume(pending);
+      pending = "";
+    },
+  };
+}
+
+export function extractProviderTokenUsage(backend, event, { model = "" } = {}) {
+  if (!event || typeof event !== "object") return null;
+  if (backend === "claude") {
+    if (event.type !== "result") return null;
+    return normalizeClaudeUsage(event.usage, model || event.model);
+  }
+  if (event.type !== "turn.completed") return null;
+  return normalizeCodexUsage(event.usage, model || event.model);
+}
+
+export function formatProviderEvent(backend, event) {
+  if (!event || typeof event !== "object") return [];
+  return backend === "claude" ? formatClaudeEvent(event) : formatCodexEvent(event);
+}
+
+function formatCodexEvent(event) {
+  const prefix = "[Codex]";
+  if (event.type === "thread.started") {
+    return [`${prefix} session started${shortIdentifier(event.thread_id)}`];
+  }
+  if (event.type === "turn.started") return [`${prefix} turn started`];
+  if (event.type === "turn.completed") {
+    return [`${prefix} completed${formatUsage(event.usage)}`];
+  }
+  if (event.type === "turn.failed" || event.type === "error") {
+    return [`${prefix} error: ${errorMessage(event)}`];
+  }
+  if (event.type !== "item.started" && event.type !== "item.completed") return [];
+
+  const item = event.item && typeof event.item === "object" ? event.item : {};
+  const phase = event.type === "item.started" ? "started" : "completed";
+  switch (item.type) {
+    case "agent_message":
+      return contentLines(prefix, "assistant", item.text || item.message);
+    case "reasoning":
+      return contentLines(prefix, "reasoning", item.text || item.summary);
+    case "command_execution":
+      return formatCodexCommand(prefix, item, phase);
+    case "file_change":
+      return formatFileChanges(prefix, item);
+    case "mcp_tool_call":
+      return [`${prefix} tool ${phase}: ${toolName(item)}`];
+    case "web_search":
+      return [`${prefix} web search ${phase}: ${cleanLine(item.query || "search")}`];
+    case "todo_list":
+      return [`${prefix} plan updated`];
+    case "error":
+      return [`${prefix} error: ${cleanLine(item.message || "provider item failed")}`];
+    default:
+      return item.type ? [`${prefix} ${cleanLine(item.type)} ${phase}`] : [];
+  }
+}
+
+function formatClaudeEvent(event) {
+  const prefix = "[Claude Code]";
+  if (event.type === "system" && event.subtype === "init") {
+    const model = cleanLine(event.model || "");
+    return [`${prefix} session started${model ? ` | ${model}` : ""}`];
+  }
+  if (event.type === "system" && event.subtype === "hook_response") {
+    const warning = cleanLine(event.stderr || "");
+    return warning ? [`${prefix} hook warning: ${warning}`] : [];
+  }
+  if (event.type === "assistant") {
+    return formatClaudeContent(prefix, event.message?.content);
+  }
+  if (event.type === "user") {
+    return formatClaudeToolResults(prefix, event.message?.content);
+  }
+  if (event.type === "result") {
+    if (event.is_error) return [`${prefix} error: ${cleanLine(event.result || event.subtype)}`];
+    const turns = Number.isInteger(event.num_turns) ? ` | ${event.num_turns} turn(s)` : "";
+    const duration = Number.isFinite(event.duration_ms)
+      ? ` | ${(event.duration_ms / 1_000).toFixed(1)}s`
+      : "";
+    return [`${prefix} completed${turns}${duration}${formatUsage(event.usage)}`];
+  }
+  if (event.type === "rate_limit_event") return [`${prefix} rate limit status updated`];
+  return [];
+}
+
+function formatCodexCommand(prefix, item, phase) {
+  const command = cleanLine(item.command || item.cmd || "command");
+  if (phase === "started") return [`${prefix} command started: ${command}`];
+  const exitCode = Number.isInteger(item.exit_code) ? ` (exit ${item.exit_code})` : "";
+  const lines = [`${prefix} command completed${exitCode}: ${command}`];
+  const output = item.aggregated_output || item.output || "";
+  if (String(output).trim()) lines.push(...contentLines(prefix, "output", output).slice(-6));
+  return lines;
+}
+
+function formatFileChanges(prefix, item) {
+  const changes = Array.isArray(item.changes) ? item.changes : [];
+  const paths = changes
+    .map((change) => cleanLine(change?.path || change?.file || ""))
+    .filter(Boolean);
+  if (paths.length > 0) return [`${prefix} files changed: ${paths.join(", ")}`];
+  return [`${prefix} file changes completed`];
+}
+
+function formatClaudeContent(prefix, content) {
+  const blocks = Array.isArray(content) ? content : [];
+  const lines = [];
+  for (const block of blocks) {
+    if (block?.type === "text") lines.push(...contentLines(prefix, "assistant", block.text));
+    if (block?.type === "thinking") lines.push(...contentLines(prefix, "reasoning", block.thinking));
+    if (block?.type === "tool_use") {
+      const detail = toolInputSummary(block.input);
+      lines.push(`${prefix} tool started: ${cleanLine(block.name || "tool")}${detail}`);
+    }
+  }
+  return lines;
+}
+
+function formatClaudeToolResults(prefix, content) {
+  const blocks = Array.isArray(content) ? content : [];
+  const lines = [];
+  for (const block of blocks) {
+    if (block?.type !== "tool_result") continue;
+    const status = block.is_error ? "failed" : "completed";
+    lines.push(`${prefix} tool ${status}${shortIdentifier(block.tool_use_id)}`);
+    const output = toolResultText(block.content);
+    if (output) {
+      lines.push(
+        ...contentLines(prefix, block.is_error ? "error" : "output", output).slice(-6),
+      );
+    }
+  }
+  return lines;
+}
+
+function contentLines(prefix, label, value) {
+  return String(value || "")
+    .split(/\r?\n/)
+    .map((line) => cleanLine(line))
+    .filter(Boolean)
+    .map((line) => `${prefix} ${label}: ${line}`);
+}
+
+function formatPlainLine(backend, stream, value) {
+  const prefix = backend === "claude" ? "[Claude Code]" : "[Codex]";
+  const diagnostic = String(value).match(
+    /^\S+\s+(WARN|ERROR|INFO)\s+([\w.-]+(?:::[\w.-]+)*):\s*(.*)$/,
+  );
+  if (diagnostic) {
+    const level = diagnostic[1].toLowerCase();
+    return `${prefix} ${level}: ${diagnostic[3] || diagnostic[2]}`;
+  }
+  return stream === "stderr" ? `${prefix} stderr: ${value}` : `${prefix} ${value}`;
+}
+
+function toolResultText(value) {
+  if (typeof value === "string") return value;
+  if (!Array.isArray(value)) return "";
+  return value
+    .map((item) => (typeof item === "string" ? item : item?.text || item?.content || ""))
+    .filter(Boolean)
+    .join("\n");
+}
+
+function formatUsage(usage) {
+  if (!usage || typeof usage !== "object") return "";
+  const input = integer(usage.input_tokens ?? usage.inputTokens);
+  const output = integer(usage.output_tokens ?? usage.outputTokens);
+  const cached = integer(usage.cached_input_tokens ?? usage.cache_read_input_tokens);
+  const parts = [];
+  if (input !== null) parts.push(`${input.toLocaleString("en-US")} in`);
+  if (output !== null) parts.push(`${output.toLocaleString("en-US")} out`);
+  if (cached !== null) parts.push(`${cached.toLocaleString("en-US")} cached`);
+  return parts.length > 0 ? ` | ${parts.join(" / ")}` : "";
+}
+
+function normalizeCodexUsage(usage, model) {
+  if (!usage || typeof usage !== "object") return null;
+  const tokensIn = tokenNumber(usage.input_tokens ?? usage.inputTokens);
+  const tokensOut = tokenNumber(usage.output_tokens ?? usage.outputTokens);
+  if (tokensIn + tokensOut <= 0) return null;
+  const cached = tokenNumber(usage.cached_input_tokens ?? usage.cachedInputTokens);
+  return compactUsage({
+    tokens_in: tokensIn,
+    tokens_out: tokensOut,
+    total_tokens: tokensIn + tokensOut,
+    cached_input_tokens: cached,
+    model: cleanLine(model || usage.model || ""),
+  });
+}
+
+function normalizeClaudeUsage(usage, model) {
+  if (!usage || typeof usage !== "object") return null;
+  const uncached = tokenNumber(usage.input_tokens ?? usage.inputTokens);
+  const cacheRead = tokenNumber(
+    usage.cache_read_input_tokens ?? usage.cacheReadInputTokens,
+  );
+  const cacheCreation = tokenNumber(
+    usage.cache_creation_input_tokens ?? usage.cacheCreationInputTokens,
+  );
+  const tokensOut = tokenNumber(usage.output_tokens ?? usage.outputTokens);
+  const tokensIn = uncached + cacheRead + cacheCreation;
+  if (tokensIn + tokensOut <= 0) return null;
+  return compactUsage({
+    tokens_in: tokensIn,
+    tokens_out: tokensOut,
+    total_tokens: tokensIn + tokensOut,
+    uncached_input_tokens: uncached,
+    cached_input_tokens: cacheRead,
+    cache_creation_input_tokens: cacheCreation,
+    model: cleanLine(model || usage.model || ""),
+  });
+}
+
+function compactUsage(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, item]) => item !== "" && item !== null && item !== undefined),
+  );
+}
+
+function providerModel(backend, event) {
+  if (backend === "claude" && event.type === "system" && event.subtype === "init") {
+    return cleanLine(event.model || "");
+  }
+  return cleanLine(event.model || "");
+}
+
+function tokenNumber(value) {
+  return Number.isFinite(value) && value >= 0 ? Math.round(value) : 0;
+}
+
+function toolName(item) {
+  const server = cleanLine(item.server || item.server_name || "");
+  const tool = cleanLine(item.tool || item.tool_name || item.name || "tool");
+  return server ? `${server}.${tool}` : tool;
+}
+
+function toolInputSummary(input) {
+  if (!input || typeof input !== "object") return "";
+  const value = input.command || input.file_path || input.path || input.query || input.pattern;
+  const summary = cleanLine(value || "");
+  return summary ? `: ${summary}` : "";
+}
+
+function errorMessage(event) {
+  const error = event.error;
+  if (typeof error === "string") return cleanLine(error);
+  return cleanLine(error?.message || event.message || "provider turn failed");
+}
+
+function shortIdentifier(value) {
+  const text = cleanLine(value || "");
+  return text ? ` | ${text.slice(0, 8)}` : "";
+}
+
+function integer(value) {
+  return Number.isInteger(value) ? value : null;
+}
+
+function cleanLine(value) {
+  const text = stripVTControlCharacters(String(value || "")).replace(/\s+/g, " ").trim();
+  if (text.length <= MAX_LINE_CHARS) return text;
+  return `${text.slice(0, MAX_LINE_CHARS - 3)}...`;
+}