feat(web): summarize T3 orchestration actions

Author: juliusmarminge

apps/web/src/components/chat/MessagesTimeline.logic.test.ts

@@ -1,4 +1,7 @@
 import { describe, expect, it } from "vite-plus/test";
+import { RunId, ThreadId, TurnItemId } from "@t3tools/contracts";
+import * as DateTime from "effect/DateTime";
+import type { WorkLogEntry } from "../../session-logic";
 import {
   computeStableMessagesTimelineRows,
   computeMessageDurationStart,
@@ -7,8 +10,125 @@ import {
   resolveAssistantMessageCopyState,
   resolveTimelineToolPresentation,
   shouldPreserveAssistantLineBreaks,
+  summarizeToolGroup,
 } from "./MessagesTimeline.logic";
 
+describe("summarizeToolGroup", () => {
+  const now = DateTime.makeUnsafe("2026-08-29T00:00:00Z");
+  function work(overrides: Partial<WorkLogEntry> = {}): WorkLogEntry {
+    return {
+      id: "tool",
+      createdAt: "2026-08-29T00:00:00Z",
+      label: "Tool call",
+      tone: "tool",
+      toolLifecycleStatus: "completed",
+      ...overrides,
+    };
+  }
+  function t3(toolName: string, input: unknown = {}, output: unknown = {}): WorkLogEntry {
+    return work({
+      itemType: "dynamic_tool",
+      toolTitle: "Friendly display name",
+      structuredPayload: {
+        id: TurnItemId.make("tool"),
+        threadId: ThreadId.make("parent"),
+        runId: RunId.make("run"),
+        nodeId: null,
+        providerThreadId: null,
+        providerTurnId: null,
+        nativeItemRef: null,
+        parentItemId: null,
+        ordinal: 0,
+        status: "completed",
+        title: "Friendly display name",
+        startedAt: now,
+        completedAt: now,
+        updatedAt: now,
+        type: "dynamic_tool",
+        toolName,
+        input,
+        output,
+      },
+    });
+  }
+
+  it("summarizes commands and thread messages using canonical names despite humanized titles", () => {
+    const entries = [
+      work({ command: "git diff" }),
+      ...["mcp__t3-code__t3_thread_send", "t3_code.t3_thread_send", "t3_thread_send"].map(
+        (toolName, i) =>
+          t3(
+            toolName,
+            { threadId: `thread-${i}` },
+            { messageId: `message-${i}`, threadId: `thread-${i}` },
+          ),
+      ),
+      work({ command: "git status" }),
+    ];
+    expect(summarizeToolGroup(entries)).toEqual({
+      summary: "Ran 2 commands and sent messages to 3 threads",
+      hasFailure: false,
+    });
+  });
+
+  it("prioritizes actions over polling, caps the clauses, and retains an omitted failure", () => {
+    const status = t3("task_status", { taskId: "task-1" }, { taskId: "task-1", status: "running" });
+    expect(
+      summarizeToolGroup([
+        status,
+        status,
+        status,
+        work({ command: "git diff" }),
+        t3(
+          "t3_thread_send",
+          { threadId: "thread-1" },
+          { threadId: "thread-1", messageId: "message-1" },
+        ),
+        t3(
+          "schedule_task",
+          {},
+          { isError: true, content: [{ type: "text", text: "Schedule rejected" }] },
+        ),
+        status,
+      ]),
+    ).toEqual({
+      summary:
+        "1 failed · Ran 1 command, sent 1 message to 1 thread, and performed 5 other actions",
+      hasFailure: true,
+    });
+  });
+
+  it("counts status checks without treating the reported child failure as a failed tool", () => {
+    const status = {
+      ...t3("task_status", { taskId: "task-1" }, { taskId: "task-1", status: "failed" }),
+      detail: "Child failed: command not found",
+    };
+    expect(
+      summarizeToolGroup([
+        t3("delegate_task", {}, { taskId: "task-1" }),
+        t3("delegate_task", {}, { taskId: "task-2" }),
+        status,
+        status,
+        status,
+        status,
+      ]),
+    ).toEqual({
+      summary: "Delegated 2 tasks and checked task status 4 times",
+      hasFailure: false,
+    });
+  });
+
+  it("leaves foreign, unknown, and preview tools generic instead of guessing from display titles", () => {
+    expect(
+      summarizeToolGroup([
+        { ...t3("mcp__github__t3_thread_send"), toolTitle: "t3-code.t3_thread_send" },
+        t3("t3-code.future_tool"),
+        t3("t3-code.preview_snapshot"),
+      ]),
+    ).toEqual({ summary: "Used 3 tools", hasFailure: false });
+  });
+});
+
 describe("shouldPreserveAssistantLineBreaks", () => {
   it("preserves Claude insight formatting without changing regular markdown", () => {
     expect(
@@ -1242,36 +1362,36 @@ describe("deriveMessagesTimelineRows", () => {
     expect(assistantRow?.showAssistantCopyButton).toBe(false);
   });
 
-  it("summarizes a settled tool group even when a command in it failed", () => {
+  it("retains a failed command in the summary after a later command succeeds", () => {
     const rows = deriveMessagesTimelineRows({
       timelineEntries: [
         {
-          id: "work-entry-ok",
+          id: "work-entry-failed",
           kind: "work" as const,
           createdAt: "2026-01-01T00:00:01Z",
           entry: {
-            id: "work-ok",
+            id: "work-failed",
             createdAt: "2026-01-01T00:00:01Z",
             label: "Ran command",
-            command: "true",
+            command: "ssh host true",
+            detail: "connection refused",
             tone: "tool" as const,
             itemType: "command_execution" as const,
-            toolLifecycleStatus: "completed" as const,
+            toolLifecycleStatus: "failed" as const,
           },
         },
         {
-          id: "work-entry-failed",
+          id: "work-entry-ok",
           kind: "work" as const,
           createdAt: "2026-01-01T00:00:02Z",
           entry: {
-            id: "work-failed",
+            id: "work-ok",
             createdAt: "2026-01-01T00:00:02Z",
             label: "Ran command",
-            command: "ssh host true",
-            detail: "connection refused",
+            command: "true",
             tone: "tool" as const,
             itemType: "command_execution" as const,
-            toolLifecycleStatus: "failed" as const,
+            toolLifecycleStatus: "completed" as const,
           },
         },
       ],
@@ -1283,7 +1403,7 @@ describe("deriveMessagesTimelineRows", () => {
     expect(rows).toHaveLength(1);
     expect(rows[0]).toMatchObject({
       kind: "work-toggle",
-      summary: "Ran 2 commands",
+      summary: "1 failed · Ran 2 commands",
       hasFailure: true,
     });
   });

apps/web/src/components/chat/MessagesTimeline.logic.ts

@@ -17,9 +17,15 @@ import {
   type RunId,
 } from "@t3tools/contracts";
 import type { ThreadRunSummary } from "@t3tools/client-runtime/state/shell";
+import {
+  summarizeT3ToolCalls,
+  type T3ToolSummaryCall,
+} from "@t3tools/client-runtime/t3ToolSummary";
 import {
   resolveT3McpToolPresentation,
+  resolveT3McpToolSummaryAction,
   type T3McpToolPresentation,
+  type T3McpToolSummaryAction,
 } from "@t3tools/shared/t3McpToolPresentation";
 
 export function workEntryIsVisibleInGroup(
@@ -360,24 +366,112 @@ function toolGroupActionLabel(action: ToolGroupAction, count: number): string {
   }
 }
 
-/** Immediate, provider-neutral fallback while generated tool summaries are unavailable. */
-export function summarizeToolGroup(entries: ReadonlyArray<WorkLogEntry>): string {
-  const groupedEntries = new Map<ToolGroupAction, WorkLogEntry[]>();
+function t3ToolSummaryCall(entry: WorkLogEntry): T3ToolSummaryCall {
+  const item = entry.structuredPayload ?? entry.projectedItem?.item;
+  const data =
+    entry.toolData !== null && typeof entry.toolData === "object"
+      ? (entry.toolData as Record<string, unknown>)
+      : undefined;
+  return {
+    input: item?.type === "dynamic_tool" ? item.input : data?.input,
+    output: item?.type === "dynamic_tool" ? item.output : data?.output,
+    // A status/read result may describe a failed child. Only the call's own lifecycle
+    // and MCP error envelope determine whether the orchestration action failed.
+    outcome:
+      entry.toolLifecycleStatus === "failed" ||
+      entry.toolLifecycleStatus === "declined" ||
+      entry.tone === "error"
+        ? "failed"
+        : entry.toolLifecycleStatus === "completed"
+          ? "completed"
+          : "unfinished",
+  };
+}
+
+function summaryActionPriority(action: ToolGroupAction | T3McpToolSummaryAction): number {
+  switch (action) {
+    case "command":
+    case "edit":
+    case "delegate":
+    case "task-cancel":
+    case "thread-create":
+    case "thread-send":
+    case "thread-interrupt":
+    case "schedule-create":
+    case "schedule-update":
+    case "schedule-delete":
+      return 0;
+    case "other":
+    case "update":
+      return 2;
+    default:
+      return 1;
+  }
+}
+
+/** Summarizes at most two action categories; every omitted call still counts in the remainder. */
+export function summarizeToolGroup(entries: ReadonlyArray<WorkLogEntry>): {
+  summary: string;
+  hasFailure: boolean;
+} {
+  const groups = new Map<
+    ToolGroupAction | T3McpToolSummaryAction,
+    {
+      action: ToolGroupAction;
+      t3Action: T3McpToolSummaryAction | null;
+      entries: WorkLogEntry[];
+    }
+  >();
   for (const entry of entries) {
+    const item = entry.structuredPayload ?? entry.projectedItem?.item;
+    const t3Action = resolveT3McpToolSummaryAction(
+      (item?.type === "dynamic_tool" ? item.toolName : null) ?? entry.toolTitle ?? entry.label,
+    );
     const action = toolGroupAction(entry);
-    const group = groupedEntries.get(action);
-    if (group) group.push(entry);
-    else groupedEntries.set(action, [entry]);
+    const key = t3Action ?? action;
+    const group = groups.get(key);
+    if (group) group.entries.push(entry);
+    else groups.set(key, { action, t3Action, entries: [entry] });
+  }
+  const summaries = [...groups].map(([action, group], index) => ({
+    index,
+    count: group.entries.length,
+    priority: summaryActionPriority(action),
+    ...(group.t3Action
+      ? summarizeT3ToolCalls(group.t3Action, group.entries.map(t3ToolSummaryCall))
+      : {
+          label: toolGroupActionLabel(
+            group.action,
+            toolGroupActionCount(group.action, group.entries),
+          ),
+          failedCount: group.entries.filter(workEntryDisplayIndicatesToolFailure).length,
+          unfinishedCount: 0,
+        }),
+  }));
+  const selected = summaries
+    .toSorted((a, b) => a.priority - b.priority || a.index - b.index)
+    .slice(0, 2)
+    .sort((a, b) => a.index - b.index);
+  const labels = selected.map(({ label }) => label);
+  const remainingCount = entries.length - selected.reduce((count, group) => count + group.count, 0);
+  if (remainingCount > 0) {
+    labels.push(`Performed ${remainingCount} other ${remainingCount === 1 ? "action" : "actions"}`);
   }
-  const labels = [...groupedEntries].map(([action, actionEntries]) =>
-    toolGroupActionLabel(action, toolGroupActionCount(action, actionEntries)),
-  );
   const sentenceLabels = labels.map((label, index) =>
     index === 0 ? label : label.charAt(0).toLowerCase() + label.slice(1),
   );
-  if (sentenceLabels.length < 2) return sentenceLabels[0] ?? "";
-  if (sentenceLabels.length === 2) return sentenceLabels.join(" and ");
-  return `${sentenceLabels.slice(0, -1).join(", ")}, and ${sentenceLabels.at(-1)}`;
+  const summary =
+    sentenceLabels.length < 3
+      ? sentenceLabels.join(" and ")
+      : `${sentenceLabels.slice(0, -1).join(", ")}, and ${sentenceLabels.at(-1)}`;
+  const failedCount = summaries.reduce((count, group) => count + group.failedCount, 0);
+  const unfinishedCount = summaries.reduce((count, group) => count + group.unfinishedCount, 0);
+  const statuses = [
+    ...(failedCount > 0 ? [`${failedCount} failed`] : []),
+    ...(unfinishedCount > 0 ? [`${unfinishedCount} unfinished`] : []),
+  ];
+  // Keep failure counts visible when a narrow timeline truncates the action text.
+  return { summary: [...statuses, summary].join(" · "), hasFailure: failedCount > 0 };
 }
 
 function toolGroupSummaryKind(entries: ReadonlyArray<WorkLogEntry>): ToolGroupSummaryKind {
@@ -833,7 +927,7 @@ export function deriveMessagesTimelineRows(input: {
           const groupId = workGroupId(timelineEntry.id);
           const expanded = input.expandedWorkGroupIds?.has(groupId) ?? false;
           const summaryKind = toolGroupSummaryKind(visibleGroupedEntries);
-          const latestToolEntry = visibleGroupedEntries.findLast(workLogEntryIsToolLike);
+          const groupSummary = summarizeToolGroup(visibleGroupedEntries);
           nextRows.push({
             kind: "work-toggle",
             id: `work-toggle:${timelineEntry.id}`,
@@ -845,11 +939,9 @@ export function deriveMessagesTimelineRows(input: {
               visibleGroupedEntries.length === 1 &&
               !workLogEntryIsToolLike(visibleGroupedEntries[0]!)
                 ? visibleGroupedEntries[0]!.label
-                : summarizeToolGroup(visibleGroupedEntries),
+                : groupSummary.summary,
             summaryKind,
-            hasFailure:
-              latestToolEntry !== undefined &&
-              workEntryDisplayIndicatesToolFailure(latestToolEntry),
+            hasFailure: groupSummary.hasFailure,
           });
           if (expanded) {
             for (const [entryIndex, workEntry] of visibleGroupedEntries.entries()) {

docs/user/activity-log.md

@@ -0,0 +1,17 @@
+# Activity log
+
+On web and desktop, consecutive tool calls appear as an expandable summary. Open it to inspect
+each command or tool result.
+
+T3 Orchestrator summaries describe the actions taken, such as **Ran 2 commands and sent messages
+to 3 threads**. Repeated messages to the same destinations show both counts: **Sent 5 messages to
+2 threads**. Thread creation counts the threads returned by the tool, including batches.
+
+Groups with many kinds of activity show up to two specific action categories and a count of the
+remaining actions. Commands, file changes, and orchestration changes take priority over reads and
+status checks. Expand the group for the full list.
+
+Failed calls are counted separately and do not count as successful messages or creations. Waiting
+on a thread does not mean it finished, and an interrupt or cancellation request does not mean the
+thread stopped. When tool details are unavailable, summaries use a broader description instead of
+guessing how many threads were affected.

packages/client-runtime/package.json

@@ -43,6 +43,10 @@
       "types": "./src/providerSkills.ts",
       "default": "./src/providerSkills.ts"
     },
+    "./t3ToolSummary": {
+      "types": "./src/t3ToolSummary.ts",
+      "default": "./src/t3ToolSummary.ts"
+    },
     "./relay": {
       "types": "./src/relay/index.ts",
       "default": "./src/relay/index.ts"