@tangle-network/agent-app 0.8.1 → 0.9.1

package/dist/trace/index.js

@@ -0,0 +1,145 @@
+// src/trace/index.ts
+function timedEventsFromLines(lines) {
+  const out = [];
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line);
+      if (typeof parsed._t === "number") out.push({ t: parsed._t, event: parsed });
+    } catch {
+    }
+  }
+  return out.sort((a, b) => a.t - b.t);
+}
+function innerOf(e) {
+  return (e.kind === "event" ? e.event : e) ?? {};
+}
+function buildFlowTrace(events, opts) {
+  const spans = [];
+  let promptTokens = 0;
+  let completionTokens = 0;
+  let toolCalls = 0;
+  const first = events[0]?.t ?? 0;
+  if (first > 0) {
+    spans.push({ kind: "pipeline", name: "dispatch \u2192 first event", startMs: 0, endMs: first });
+  }
+  let segStart = null;
+  let segEnd = 0;
+  let segKinds = /* @__PURE__ */ new Set();
+  let lastDeltaT = first;
+  const openCalls = /* @__PURE__ */ new Map();
+  const closeSegment = () => {
+    if (segStart !== null) {
+      spans.push({
+        kind: "model",
+        name: segKinds.has("reasoning") ? "model turn (reasoning + text)" : "model turn",
+        startMs: segStart,
+        endMs: segEnd,
+        approx: true
+      });
+      segStart = null;
+      segKinds = /* @__PURE__ */ new Set();
+    }
+  };
+  for (const { t, event } of events) {
+    const inner = innerOf(event);
+    const type = String(event.kind === "tool_result" ? "tool_result" : inner.type ?? "");
+    if (type === "text" || type === "reasoning") {
+      if (segStart === null) segStart = t;
+      segEnd = t;
+      segKinds.add(type);
+      lastDeltaT = t;
+    } else if (type === "tool_call") {
+      closeSegment();
+      toolCalls++;
+      const call = inner.call ?? inner;
+      const id = String(call.toolCallId ?? `call_${toolCalls}`);
+      openCalls.set(id, { name: String(call.toolName ?? "tool"), emitT: t, lastDeltaT });
+    } else if (type === "tool_result") {
+      const id = String(event.toolCallId ?? inner.toolCallId ?? "");
+      const open = openCalls.get(id);
+      if (open) {
+        spans.push({
+          kind: "tool",
+          name: open.name,
+          // Execution happens between the end of the model turn that emitted
+          // the call and the result landing in the buffer.
+          startMs: open.lastDeltaT,
+          endMs: t,
+          approx: true,
+          meta: { ok: (event.outcome ?? inner.outcome)?.ok }
+        });
+        openCalls.delete(id);
+      }
+    } else if (type === "usage") {
+      const u = inner.usage ?? {};
+      promptTokens += u.promptTokens ?? 0;
+      completionTokens += u.completionTokens ?? 0;
+    }
+  }
+  closeSegment();
+  const totalMs = events.length ? events[events.length - 1].t : 0;
+  const trace = { spans, totalMs, promptTokens, completionTokens, toolCalls };
+  const p = opts?.pricing;
+  if (p && (p.prompt != null || p.completion != null)) {
+    trace.costUsd = promptTokens * Number(p.prompt ?? 0) + completionTokens * Number(p.completion ?? 0);
+  }
+  return trace;
+}
+var fmtS = (ms) => `${(ms / 1e3).toFixed(1)}s`;
+function renderWaterfall(trace, opts) {
+  const width = opts?.width ?? 40;
+  const scale = trace.totalMs > 0 ? width / trace.totalMs : 0;
+  const lines = [];
+  const spans = [...trace.spans].sort((a, b) => a.startMs - b.startMs);
+  for (let i = 0; i < spans.length; i++) {
+    const s = spans[i];
+    const offset = Math.round(s.startMs * scale);
+    const len = Math.max(1, Math.round((s.endMs - s.startMs) * scale));
+    const bar = " ".repeat(offset) + (s.kind === "tool" ? "\u2593" : s.kind === "pipeline" ? "\u2591" : "\u2588").repeat(len);
+    const branch = i === spans.length - 1 ? "\u2514\u2500" : "\u251C\u2500";
+    const dur = `${fmtS(s.endMs - s.startMs)}${s.approx ? "~" : ""}`;
+    lines.push(`${fmtS(s.startMs).padStart(7)} ${branch} ${bar.padEnd(width + 2)} ${s.name} (${dur})`);
+  }
+  const cost = trace.costUsd != null ? `  $${trace.costUsd.toFixed(trace.costUsd < 0.01 ? 6 : 4)}` : "";
+  lines.push(
+    `${fmtS(trace.totalMs).padStart(7)} \u2500\u2500 total \xB7 ${trace.promptTokens}p + ${trace.completionTokens}c tok \xB7 ${trace.toolCalls} tool calls${cost}`
+  );
+  return lines.join("\n");
+}
+function summarize(values) {
+  const sorted = [...values].sort((a, b) => a - b);
+  const q = (p) => sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))] ?? 0;
+  return { n: sorted.length, min: sorted[0] ?? 0, p50: q(0.5), p90: q(0.9), max: sorted[sorted.length - 1] ?? 0 };
+}
+function renderHistogram(values, opts) {
+  if (!values.length) return "(no samples)";
+  const buckets = opts?.buckets ?? 6;
+  const width = opts?.width ?? 24;
+  const fmt = opts?.format ?? ((v) => `${Math.round(v)}${opts?.unit ?? ""}`);
+  const s = summarize(values);
+  const lo = s.min;
+  const hi = s.max === s.min ? s.min + 1 : s.max;
+  const counts = new Array(buckets).fill(0);
+  for (const v of values) {
+    counts[Math.min(buckets - 1, Math.floor((v - lo) / (hi - lo) * buckets))]++;
+  }
+  const maxCount = Math.max(...counts);
+  const lines = [
+    `n=${s.n}  min=${fmt(s.min)}  p50=${fmt(s.p50)}  p90=${fmt(s.p90)}  max=${fmt(s.max)}`
+  ];
+  for (let i = 0; i < buckets; i++) {
+    const a = lo + (hi - lo) * i / buckets;
+    const b = lo + (hi - lo) * (i + 1) / buckets;
+    const bar = "\u2588".repeat(Math.max(counts[i] > 0 ? 1 : 0, Math.round(counts[i] / maxCount * width)));
+    lines.push(`${fmt(a).padStart(8)}-${fmt(b).padEnd(8)} ${bar} ${counts[i]}`);
+  }
+  return lines.join("\n");
+}
+export {
+  buildFlowTrace,
+  renderHistogram,
+  renderWaterfall,
+  summarize,
+  timedEventsFromLines
+};
+//# sourceMappingURL=index.js.map

package/dist/trace/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/trace/index.ts"],"sourcesContent":["/**\n * `@tangle-network/agent-app/trace` — flow observability for agent turns.\n *\n * The turn buffer stamps `_t` (ms since turn start) on every event, so any\n * live stream OR any historical turn replayed from a TurnEventStore can be\n * reconstructed into a span trace: pipeline overhead, model segments (with\n * thinking TTFT), tool executions, token usage, and cost. Renderers turn\n * traces and multi-run samples into ASCII waterfalls and histograms — the\n * default artifact for \"how did this run actually behave\" questions across\n * evals, hill-climbs, and production debugging.\n *\n * Span boundaries derived from a buffered stream are quantized by the\n * pump's flush window and the reader's poll cadence (~100–400ms); spans\n * carry `approx: true` to keep reports honest about that.\n */\n\nexport interface TimedEvent {\n  /** ms since turn start (`_t` stamped by pumpBufferedTurn). */\n  t: number\n  event: Record<string, unknown>\n}\n\nexport interface FlowSpan {\n  kind: 'pipeline' | 'model' | 'tool'\n  name: string\n  startMs: number\n  endMs: number\n  approx?: boolean\n  meta?: Record<string, unknown>\n}\n\nexport interface FlowTrace {\n  spans: FlowSpan[]\n  totalMs: number\n  promptTokens: number\n  completionTokens: number\n  /** Computed when per-token pricing is supplied. */\n  costUsd?: number\n  toolCalls: number\n}\n\n/** Parse stored turn-event lines (JSON strings with `_t`) into TimedEvents. */\nexport function timedEventsFromLines(lines: string[]): TimedEvent[] {\n  const out: TimedEvent[] = []\n  for (const line of lines) {\n    try {\n      const parsed = JSON.parse(line) as Record<string, unknown>\n      if (typeof parsed._t === 'number') out.push({ t: parsed._t, event: parsed })\n    } catch {\n      /* skip torn lines */\n    }\n  }\n  return out.sort((a, b) => a.t - b.t)\n}\n\nfunction innerOf(e: Record<string, unknown>): Record<string, unknown> {\n  return (e.kind === 'event' ? (e.event as Record<string, unknown>) : e) ?? {}\n}\n\n/**\n * Derive a span trace from timestamped turn events. Model segments are runs\n * of text/reasoning deltas; a tool span opens at the last delta before its\n * tool_call emission and closes at the matching tool_result.\n */\nexport function buildFlowTrace(\n  events: TimedEvent[],\n  opts?: { pricing?: { prompt?: string | number; completion?: string | number } },\n): FlowTrace {\n  const spans: FlowSpan[] = []\n  let promptTokens = 0\n  let completionTokens = 0\n  let toolCalls = 0\n\n  const first = events[0]?.t ?? 0\n  if (first > 0) {\n    spans.push({ kind: 'pipeline', name: 'dispatch → first event', startMs: 0, endMs: first })\n  }\n\n  let segStart: number | null = null\n  let segEnd = 0\n  let segKinds = new Set<string>()\n  let lastDeltaT = first\n  const openCalls = new Map<string, { name: string; emitT: number; lastDeltaT: number }>()\n\n  const closeSegment = () => {\n    if (segStart !== null) {\n      spans.push({\n        kind: 'model',\n        name: segKinds.has('reasoning') ? 'model turn (reasoning + text)' : 'model turn',\n        startMs: segStart,\n        endMs: segEnd,\n        approx: true,\n      })\n      segStart = null\n      segKinds = new Set()\n    }\n  }\n\n  for (const { t, event } of events) {\n    const inner = innerOf(event)\n    const type = String(event.kind === 'tool_result' ? 'tool_result' : (inner.type ?? ''))\n\n    if (type === 'text' || type === 'reasoning') {\n      if (segStart === null) segStart = t\n      segEnd = t\n      segKinds.add(type)\n      lastDeltaT = t\n    } else if (type === 'tool_call') {\n      closeSegment()\n      toolCalls++\n      const call = (inner.call ?? inner) as Record<string, unknown>\n      const id = String(call.toolCallId ?? `call_${toolCalls}`)\n      openCalls.set(id, { name: String(call.toolName ?? 'tool'), emitT: t, lastDeltaT })\n    } else if (type === 'tool_result') {\n      const id = String(event.toolCallId ?? inner.toolCallId ?? '')\n      const open = openCalls.get(id)\n      if (open) {\n        spans.push({\n          kind: 'tool',\n          name: open.name,\n          // Execution happens between the end of the model turn that emitted\n          // the call and the result landing in the buffer.\n          startMs: open.lastDeltaT,\n          endMs: t,\n          approx: true,\n          meta: { ok: ((event.outcome ?? inner.outcome) as { ok?: boolean } | undefined)?.ok },\n        })\n        openCalls.delete(id)\n      }\n    } else if (type === 'usage') {\n      const u = (inner.usage ?? {}) as { promptTokens?: number; completionTokens?: number }\n      promptTokens += u.promptTokens ?? 0\n      completionTokens += u.completionTokens ?? 0\n    }\n  }\n  closeSegment()\n\n  const totalMs = events.length ? events[events.length - 1]!.t : 0\n  const trace: FlowTrace = { spans, totalMs, promptTokens, completionTokens, toolCalls }\n  const p = opts?.pricing\n  if (p && (p.prompt != null || p.completion != null)) {\n    trace.costUsd = promptTokens * Number(p.prompt ?? 0) + completionTokens * Number(p.completion ?? 0)\n  }\n  return trace\n}\n\nconst fmtS = (ms: number) => `${(ms / 1000).toFixed(1)}s`\n\n/** ASCII waterfall cascade — the default artifact for explaining a flow. */\nexport function renderWaterfall(trace: FlowTrace, opts?: { width?: number }): string {\n  const width = opts?.width ?? 40\n  const scale = trace.totalMs > 0 ? width / trace.totalMs : 0\n  const lines: string[] = []\n  const spans = [...trace.spans].sort((a, b) => a.startMs - b.startMs)\n  for (let i = 0; i < spans.length; i++) {\n    const s = spans[i]!\n    const offset = Math.round(s.startMs * scale)\n    const len = Math.max(1, Math.round((s.endMs - s.startMs) * scale))\n    const bar = ' '.repeat(offset) + (s.kind === 'tool' ? '▓' : s.kind === 'pipeline' ? '░' : '█').repeat(len)\n    const branch = i === spans.length - 1 ? '└─' : '├─'\n    const dur = `${fmtS(s.endMs - s.startMs)}${s.approx ? '~' : ''}`\n    lines.push(`${fmtS(s.startMs).padStart(7)} ${branch} ${bar.padEnd(width + 2)} ${s.name} (${dur})`)\n  }\n  const cost = trace.costUsd != null ? `  $${trace.costUsd.toFixed(trace.costUsd < 0.01 ? 6 : 4)}` : ''\n  lines.push(\n    `${fmtS(trace.totalMs).padStart(7)} ── total · ${trace.promptTokens}p + ${trace.completionTokens}c tok · ${trace.toolCalls} tool calls${cost}`,\n  )\n  return lines.join('\\n')\n}\n\nexport interface DistributionSummary {\n  n: number\n  min: number\n  p50: number\n  p90: number\n  max: number\n}\n\nexport function summarize(values: number[]): DistributionSummary {\n  const sorted = [...values].sort((a, b) => a - b)\n  const q = (p: number) => sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))] ?? 0\n  return { n: sorted.length, min: sorted[0] ?? 0, p50: q(0.5), p90: q(0.9), max: sorted[sorted.length - 1] ?? 0 }\n}\n\n/** ASCII histogram for multi-run samples (eval latencies, costs, scores). */\nexport function renderHistogram(\n  values: number[],\n  opts?: { buckets?: number; width?: number; unit?: string; format?: (v: number) => string },\n): string {\n  if (!values.length) return '(no samples)'\n  const buckets = opts?.buckets ?? 6\n  const width = opts?.width ?? 24\n  const fmt = opts?.format ?? ((v: number) => `${Math.round(v)}${opts?.unit ?? ''}`)\n  const s = summarize(values)\n  const lo = s.min\n  const hi = s.max === s.min ? s.min + 1 : s.max\n  const counts = new Array<number>(buckets).fill(0)\n  for (const v of values) {\n    counts[Math.min(buckets - 1, Math.floor(((v - lo) / (hi - lo)) * buckets))]!++\n  }\n  const maxCount = Math.max(...counts)\n  const lines = [\n    `n=${s.n}  min=${fmt(s.min)}  p50=${fmt(s.p50)}  p90=${fmt(s.p90)}  max=${fmt(s.max)}`,\n  ]\n  for (let i = 0; i < buckets; i++) {\n    const a = lo + ((hi - lo) * i) / buckets\n    const b = lo + ((hi - lo) * (i + 1)) / buckets\n    const bar = '█'.repeat(Math.max(counts[i]! > 0 ? 1 : 0, Math.round((counts[i]! / maxCount) * width)))\n    lines.push(`${fmt(a).padStart(8)}-${fmt(b).padEnd(8)} ${bar} ${counts[i]}`)\n  }\n  return lines.join('\\n')\n}\n"],"mappings":"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","names":[]}

package/dist/web-react/index.d.ts

@@ -185,8 +185,11 @@ interface ChatToolCallInfo {
     id: string;
     name: string;
     status: 'running' | 'done' | 'error';
+    /** The call arguments, captured from the tool_call event — shown in the
+     *  expanded card so users see exactly what the agent invoked. */
+    args?: Record<string, unknown>;
     /** The tool outcome (`{ok, result}` shape). When `result.status` is
-     *  'queued_for_approval' the chip renders the approval state. */
+     *  'queued_for_approval' the card renders the approval state. */
     result?: unknown;
 }
 /** Extract `{proposalId, status}` from a tool outcome when it is a proposal
@@ -216,19 +219,24 @@ interface ChatMessagesProps {
     /** Approve/Reject handlers for proposals awaiting approval. When omitted the
      *  chip still shows "awaiting approval" but without action buttons. */
     approval?: ProposalApprovalHandlers;
-    /** Make tool chips clickable (e.g. open a {@link RunDrillIn} panel). */
+    /** Open a full-transcript view (e.g. {@link RunDrillIn}) from a tool card. */
     onToolCallClick?: (call: ChatToolCallInfo, message: ChatUiMessage) => void;
+    /** Per-tool custom detail renderers for expanded tool cards. */
+    toolRenderers?: ToolDetailRenderers;
 }
 interface ProposalApprovalHandlers {
     onApprove: (proposalId: string, toolCallId: string) => void | Promise<void>;
     onReject: (proposalId: string, toolCallId: string) => void | Promise<void>;
 }
+/** Per-tool custom detail renderers for the expanded card body — keyed by
+ *  tool name. Return null to fall back to the generic detail view. */
+type ToolDetailRenderers = Record<string, (call: ChatToolCallInfo, message: ChatUiMessage) => ReactNode>;
 /**
  * The message thread: one centered column; user messages are right-aligned
  * bubbles with a User label; agent messages carry an Agent meta line with
  * model id, tokens/sec, and cost, plus a collapsible thinking section and
  * tool-call chips.
  */
-declare function ChatMessages({ messages, models, renderMarkdown, renderExtras, userLabel, agentLabel, loading, approval, onToolCallClick, }: ChatMessagesProps): react.JSX.Element;
+declare function ChatMessages({ messages, models, renderMarkdown, renderExtras, userLabel, agentLabel, loading, approval, onToolCallClick, toolRenderers, }: ChatMessagesProps): react.JSX.Element;
 
-export { type ChatMessageMetrics, ChatMessages, type ChatMessagesProps, type ChatStreamCallbacks, type ChatStreamToolCall, type ChatStreamToolResult, type ChatToolCallInfo, type ChatUiMessage, type ConsumeChatStreamResult, EffortPicker, type EffortPickerProps, ModelPicker, type ModelPickerProps, type ProposalApprovalHandlers, ProviderLogo, type ProviderLogoProps, RunDrillIn, type RunDrillInProps, type SmoothRevealOptions, type StreamChatOptions, type ToolRunRecord, type ToolRunStep, consumeChatStream, dispatchChatStreamLine, formatModelCost, formatTokensPerSecond, nextRevealCount, pendingApprovalOf, streamChatTurn, useSmoothText };
+export { type ChatMessageMetrics, ChatMessages, type ChatMessagesProps, type ChatStreamCallbacks, type ChatStreamToolCall, type ChatStreamToolResult, type ChatToolCallInfo, type ChatUiMessage, type ConsumeChatStreamResult, EffortPicker, type EffortPickerProps, ModelPicker, type ModelPickerProps, type ProposalApprovalHandlers, ProviderLogo, type ProviderLogoProps, RunDrillIn, type RunDrillInProps, type SmoothRevealOptions, type StreamChatOptions, type ToolDetailRenderers, type ToolRunRecord, type ToolRunStep, consumeChatStream, dispatchChatStreamLine, formatModelCost, formatTokensPerSecond, nextRevealCount, pendingApprovalOf, streamChatTurn, useSmoothText };

package/dist/web-react/index.js

@@ -449,62 +449,125 @@ function pendingApprovalOf(call) {
   if (!outcome?.ok || outcome.result?.status !== "queued_for_approval" || !outcome.result.proposalId) return null;
   return { proposalId: outcome.result.proposalId };
 }
-function ToolChips({
-  toolCalls,
+function toolOutcomeOf(call) {
+  return call.result;
+}
+function friendlyToolTitle(call) {
+  const a = call.args ?? {};
+  switch (call.name) {
+    case "submit_proposal":
+      return `Proposal \xB7 ${String(a.type ?? "")}${a.title ? `: ${String(a.title)}` : ""}`;
+    case "sandbox_create":
+      return `Create sandbox (${String(a.environment ?? "universal")})`;
+    case "sandbox_run_command":
+      return `$ ${String(a.command ?? "")}`;
+    case "sandbox_destroy":
+      return `Destroy sandbox ${String(a.sandbox_id ?? "")}`;
+    case "schedule_followup":
+      return `Follow-up \xB7 ${String(a.title ?? "")}`;
+    case "render_ui":
+      return `Render view \xB7 ${String(a.title ?? "")}`;
+    case "add_citation":
+      return `Citation \xB7 ${String(a.path ?? "")}`;
+    default:
+      return call.name;
+  }
+}
+function truncate(v, max = 240) {
+  const s = typeof v === "string" ? v : JSON.stringify(v);
+  return s.length > max ? `${s.slice(0, max)}\u2026` : s;
+}
+function KvRows({ data }) {
+  const entries = Object.entries(data).filter(([, v]) => v !== void 0 && v !== null && v !== "");
+  if (!entries.length) return null;
+  return /* @__PURE__ */ jsx2("dl", { className: "grid grid-cols-[auto_1fr] gap-x-3 gap-y-1", children: entries.map(([k, v]) => /* @__PURE__ */ jsxs2("div", { className: "contents", children: [
+    /* @__PURE__ */ jsx2("dt", { className: "font-mono text-[11px] text-muted-foreground/70", children: k }),
+    /* @__PURE__ */ jsx2("dd", { className: "min-w-0 whitespace-pre-wrap break-words font-mono text-[11px] text-muted-foreground", children: truncate(v) })
+  ] }, k)) });
+}
+function DefaultToolDetail({ call }) {
+  const outcome = toolOutcomeOf(call);
+  return /* @__PURE__ */ jsxs2("div", { className: "space-y-2", children: [
+    call.args && Object.keys(call.args).length > 0 && /* @__PURE__ */ jsxs2("div", { children: [
+      /* @__PURE__ */ jsx2("p", { className: "mb-1 text-[10px] font-semibold uppercase tracking-wide text-muted-foreground/50", children: "Called with" }),
+      /* @__PURE__ */ jsx2(KvRows, { data: call.args })
+    ] }),
+    outcome && /* @__PURE__ */ jsxs2("div", { children: [
+      /* @__PURE__ */ jsx2("p", { className: "mb-1 text-[10px] font-semibold uppercase tracking-wide text-muted-foreground/50", children: outcome.ok === false ? "Failed" : "Result" }),
+      outcome.ok === false ? /* @__PURE__ */ jsx2("p", { className: "text-xs text-red-600", children: outcome.message ?? "Tool failed" }) : outcome.result && typeof outcome.result === "object" ? /* @__PURE__ */ jsx2(KvRows, { data: outcome.result }) : /* @__PURE__ */ jsx2("p", { className: "font-mono text-[11px] text-muted-foreground", children: truncate(outcome.result) })
+    ] })
+  ] });
+}
+function ToolCallCard({
+  call,
+  message,
   approval,
-  onClick
+  onOpenRun,
+  renderers
 }) {
-  return /* @__PURE__ */ jsx2("div", { className: "mt-2 flex flex-col gap-1", children: toolCalls.map((tc) => {
-    const pending = tc.status === "done" ? pendingApprovalOf(tc) : null;
-    if (pending) {
-      return /* @__PURE__ */ jsxs2(
-        "div",
-        {
-          className: "inline-flex w-fit items-center gap-2 rounded-md bg-amber-500/10 px-2.5 py-1 text-xs text-amber-700",
-          children: [
-            /* @__PURE__ */ jsx2("span", { className: "font-mono opacity-70", children: "\u23F8" }),
-            /* @__PURE__ */ jsx2("span", { className: "font-medium", children: tc.name }),
-            /* @__PURE__ */ jsx2("span", { className: "opacity-60", children: "awaiting approval" }),
-            approval && /* @__PURE__ */ jsxs2("span", { className: "ml-1 inline-flex items-center gap-1", children: [
+  const [expanded, setExpanded] = useState2(false);
+  const pending = call.status === "done" ? pendingApprovalOf(call) : null;
+  const failed = call.status === "error" || toolOutcomeOf(call)?.ok === false;
+  const custom = renderers?.[call.name]?.(call, message);
+  return /* @__PURE__ */ jsxs2(
+    "div",
+    {
+      className: `w-fit min-w-[280px] max-w-full rounded-lg border text-xs transition ${pending ? "border-amber-300/60 bg-amber-500/5" : failed ? "border-red-300/60 bg-red-500/5" : "border-border/60 bg-muted/20"}`,
+      children: [
+        /* @__PURE__ */ jsxs2(
+          "button",
+          {
+            type: "button",
+            onClick: () => setExpanded((v) => !v),
+            className: "flex w-full items-center gap-2 px-3 py-2 text-left",
+            children: [
               /* @__PURE__ */ jsx2(
-                "button",
+                "span",
                 {
-                  type: "button",
-                  onClick: () => approval.onApprove(pending.proposalId, tc.id),
-                  className: "rounded bg-green-600/90 px-2 py-0.5 text-[11px] font-semibold text-white transition hover:bg-green-600",
-                  children: "Approve"
+                  className: `h-2 w-2 shrink-0 rounded-full ${call.status === "running" ? "animate-pulse bg-yellow-500" : pending ? "bg-amber-500" : failed ? "bg-red-500" : "bg-green-500"}`
                 }
               ),
-              /* @__PURE__ */ jsx2(
-                "button",
-                {
-                  type: "button",
-                  onClick: () => approval.onReject(pending.proposalId, tc.id),
-                  className: "rounded border border-border bg-card px-2 py-0.5 text-[11px] font-medium text-foreground transition hover:bg-accent/30",
-                  children: "Reject"
-                }
-              )
-            ] })
-          ]
-        },
-        tc.id
-      );
+              /* @__PURE__ */ jsx2("span", { className: "min-w-0 flex-1 truncate font-medium", children: friendlyToolTitle(call) }),
+              pending && approval && /* @__PURE__ */ jsxs2("span", { className: "flex shrink-0 items-center gap-1", onClick: (e) => e.stopPropagation(), children: [
+                /* @__PURE__ */ jsx2(
+                  "button",
+                  {
+                    type: "button",
+                    onClick: () => approval.onApprove(pending.proposalId, call.id),
+                    className: "rounded bg-green-600/90 px-2 py-0.5 text-[11px] font-semibold text-white transition hover:bg-green-600",
+                    children: "Approve"
+                  }
+                ),
+                /* @__PURE__ */ jsx2(
+                  "button",
+                  {
+                    type: "button",
+                    onClick: () => approval.onReject(pending.proposalId, call.id),
+                    className: "rounded border border-border bg-card px-2 py-0.5 text-[11px] font-medium text-foreground transition hover:bg-accent/30",
+                    children: "Reject"
+                  }
+                )
+              ] }),
+              /* @__PURE__ */ jsx2("span", { className: "shrink-0 text-[11px] text-muted-foreground/70", children: call.status === "running" ? "running\u2026" : pending ? "awaiting approval" : failed ? "failed" : "done" }),
+              /* @__PURE__ */ jsx2(ChevronDown, { className: `h-3 w-3 shrink-0 text-muted-foreground transition-transform ${expanded ? "rotate-180" : ""}` })
+            ]
+          }
+        ),
+        expanded && /* @__PURE__ */ jsxs2("div", { className: "border-t border-border/40 px-3 py-2.5", children: [
+          custom ?? /* @__PURE__ */ jsx2(DefaultToolDetail, { call }),
+          onOpenRun && call.name.startsWith("sandbox_") && /* @__PURE__ */ jsx2(
+            "button",
+            {
+              type: "button",
+              onClick: () => onOpenRun(call, message),
+              className: "mt-2 rounded border border-border bg-card px-2 py-1 text-[11px] font-medium transition hover:bg-accent/30",
+              children: "Open full transcript \u2192"
+            }
+          )
+        ] })
+      ]
     }
-    const Tag = onClick ? "button" : "div";
-    return /* @__PURE__ */ jsxs2(
-      Tag,
-      {
-        ...onClick ? { type: "button", onClick: () => onClick(tc) } : {},
-        className: `inline-flex w-fit items-center gap-2 rounded-md px-2.5 py-1 text-xs ${tc.status === "running" ? "bg-yellow-500/10 text-yellow-700" : tc.status === "error" ? "bg-red-500/10 text-red-700" : "bg-green-500/10 text-green-700"} ${onClick ? "cursor-pointer transition hover:ring-1 hover:ring-border" : ""}`,
-        children: [
-          /* @__PURE__ */ jsx2("span", { className: "font-mono opacity-70", children: tc.status === "running" ? "\u26A1" : tc.status === "error" ? "\u2717" : "\u2713" }),
-          /* @__PURE__ */ jsx2("span", { className: "font-medium", children: tc.name }),
-          /* @__PURE__ */ jsx2("span", { className: "opacity-60", children: tc.status === "running" ? "running\u2026" : tc.status === "error" ? "failed" : "done" })
-        ]
-      },
-      tc.id
-    );
-  }) });
+  );
 }
 function AssistantMessage({
   msg,
@@ -514,6 +577,7 @@ function AssistantMessage({
   renderBody,
   approval,
   onToolCallClick,
+  toolRenderers,
   renderExtras
 }) {
   const content = useSmoothText(msg.content, streaming);
@@ -538,14 +602,17 @@ function AssistantMessage({
       /* @__PURE__ */ jsx2("div", { ref: reasoningScrollRef, className: "mt-2 max-h-48 overflow-y-auto whitespace-pre-wrap text-sm text-muted-foreground/80", children: reasoning })
     ] }),
     /* @__PURE__ */ jsx2("div", { className: "text-base leading-[1.75]", children: renderBody(content) }),
-    msg.toolCalls && msg.toolCalls.length > 0 && /* @__PURE__ */ jsx2(
-      ToolChips,
+    msg.toolCalls && msg.toolCalls.length > 0 && /* @__PURE__ */ jsx2("div", { className: "mt-2 flex flex-col gap-1.5", children: msg.toolCalls.map((tc) => /* @__PURE__ */ jsx2(
+      ToolCallCard,
       {
-        toolCalls: msg.toolCalls,
+        call: tc,
+        message: msg,
         approval,
-        onClick: onToolCallClick ? (tc) => onToolCallClick(tc, msg) : void 0
-      }
-    ),
+        onOpenRun: onToolCallClick,
+        renderers: toolRenderers
+      },
+      tc.id
+    )) }),
     renderExtras?.(msg)
   ] });
 }
@@ -573,7 +640,8 @@ function ChatMessages({
   agentLabel = "Agent",
   loading,
   approval,
-  onToolCallClick
+  onToolCallClick,
+  toolRenderers
 }) {
   const renderBody = renderMarkdown ?? ((content) => /* @__PURE__ */ jsx2("p", { className: "whitespace-pre-wrap", children: content }));
   const lastIsUser = messages[messages.length - 1]?.role === "user";
@@ -592,6 +660,7 @@ function ChatMessages({
           renderBody,
           approval,
           onToolCallClick,
+          toolRenderers,
           renderExtras
         },
         msg.id