pi-long-task 0.2.0 → 0.3.1

package/README.md

@@ -1,29 +1,40 @@
 # Pi Long Task
 
-Pi Long Task is a Pi extension that turns a larger coding request into a clear TODO plan, works through the tasks one by one, and reports the result.
+Pi Long Task is a Pi extension that breaks large coding requests into tracked TODOs, executes them in isolated worker sessions, shows progress in a sidebar, and optionally commits completed work.
 
-It is useful when you want Pi to handle a multi-step change without losing track of what has been done, what is still left, and whether changes should be committed.
+Use it when a coding request is bigger than one focused interaction. Pi Long Task creates or cleans up the TODO plan, hands each TODO to a fresh worker session, tracks every attempt, and keeps the run artifacts so you can inspect what happened later.
 
-## What you get
+## Why use it
 
-When you ask Pi to run a long task, it will:
+- **Take on bigger tasks:** split broad product, refactor, testing, or cleanup requests into smaller TODOs that Pi can complete one at a time.
+- **Track progress visibly:** see the active TODO, inferred `**Status:**` subtasks, completed/failed/blocked counts, and remaining work in Pi's long-task sidebar.
+- **Recover with retries:** tasks that do not report completion can be retried with context from previous attempts instead of losing the thread.
+- **Commit safely when asked:** enable commits for completed task work, while generated run files and pre-existing dirty files are kept out of those commits.
+- **Keep task artifacts:** every run writes a generated `TODO.md`, generated `TASK_RESULT.md`, attempt summaries, and final status under `tmp/pi-long-task/<run-id>/`.
+- **Watch cost visibility:** worker spend is captured and surfaced in progress and final summaries when usage cost data is available.
 
-1. Recognize natural-language requests like "run a long task with commits" and route them to `pi_long_task`.
-2. Create or clean up a TODO plan from your request.
-3. Work through each unfinished TODO task in order.
-4. Show the current task and inferred subtask progress while it runs.
-5. Record progress and final results under `tmp/pi-long-task/<run-id>/`.
-6. Return a summary with completed, failed, blocked, and remaining task counts.
-7. Optionally commit completed work after each task.
+## What happens during a run
+
+When you ask Pi to run a long task, Pi Long Task:
+
+1. Recognizes natural-language requests like "run a long task with commits" and routes them to `pi_long_task`.
+2. Creates or cleans up a TODO plan from your request.
+3. Works through each unfinished TODO task in order using isolated worker sessions.
+4. Shows the current task and inferred subtask progress in a sidebar while it runs.
+5. Retries unfinished tasks up to the configured attempt limit.
+6. Records progress, task artifacts, and final results under `tmp/pi-long-task/<run-id>/`.
+7. Returns a summary with completed, failed, blocked, and remaining task counts, plus worker spend when available.
+8. Optionally commits completed work after each task.
 
 A finished run gives you:
 
 - a concise status summary in Pi
 - a generated `TODO.md`
 - a generated `TASK_RESULT.md`
-- live progress for the active task and its `**Status:**` checkbox subtasks
+- live sidebar progress for the active task and its `**Status:**` checkbox subtasks
+- task attempt history and any remaining or blocked tasks clearly listed
+- worker spend when cost data is available
 - commit hashes when commits were enabled and created
-- any remaining or blocked tasks clearly listed
 
 ## Install
 
@@ -59,18 +70,74 @@ Or update all installed Pi extension packages:
 pi update --extensions
 ```
 
-## Usage
+## Quick start examples
+
+Use natural language; you do not need to mention `pi_long_task` explicitly. Copy one of these prompts and replace the quoted work with your own task.
 
-Use natural language; you do not need to mention `pi_long_task` explicitly:
+Run with commits enabled, so each completed TODO can be committed separately:
+
+```text
+Run a long task with commits to implement the TODOs in @TODO.md.
+```
+
+```text
+Run a long task with commits to refactor the checkout flow, update the tests, and commit each completed task.
+```
+
+Run without commits when you want to review all changes yourself before committing:
 
 ```text
 Run a long task without commits to add tests for the parser and fix any failures.
 ```
 
 ```text
-Run a long task with commits to implement the TODOs in @TODO.md.
+Run a long task without commits to audit the README examples and leave the final diff uncommitted.
 ```
 
+## What it looks like
+
+Pi keeps the active worker transcript in the main content area and shows the run timeline in the sidebar:
+
+```text
+┌─ Main content: active worker activity ───────────────┬─ Pi Long Task sidebar ───────────────┐
+│ Worker TODO 2 — Add parser tests                    │ Progress: 2/5 tasks complete (40%)   │
+│                                                      │ Worker spend: $0.18                  │
+│ $ npm test -- parser                                │                                      │
+│ ✓ parser handles nested arrays                      │ Timeline                             │
+│ ✗ parser rejects invalid escapes                    │ ● TODO 1 Rewrite intro        done   │
+│                                                      │ ● TODO 2 Add parser tests     active │
+│ Editing src/parser.test.ts...                       │   ◌ add edge-case fixtures           │
+│ Re-running focused tests after fix...               │   ◌ fix failing assertions           │
+│                                                      │ ○ TODO 3 Update docs          next   │
+│                                                      │ ○ TODO 4 Validate install     later  │
+│                                                      │                                      │
+│ The worker reports commands, file edits, and result  │ Sidebar tracks task statuses,        │
+│ details here while the current TODO is running.      │ subtask progress, timeline, spend.   │
+└──────────────────────────────────────────────────────┴──────────────────────────────────────┘
+```
+
+## How it works
+
+Pi Long Task coordinates a long request from planning through task completion:
+
+1. **Plan the work:** it creates a TODO plan from your request, or normalizes pasted TODO markdown so each item can be tracked consistently.
+2. **Run isolated workers:** each TODO is assigned to its own fresh worker session with the relevant task text, global instructions, attempt history, and commit setting.
+3. **Stream progress back:** the active worker's activity streams into the main Pi thread, so you can follow commands, edits, verification, and the final `TASK_RESULT` as they happen.
+4. **Show every task in the sidebar:** the sidebar lists the full run timeline, including completed, active, upcoming, failed, or blocked tasks and inferred subtask progress from each task's `**Status:**` checklist.
+5. **Write run artifacts:** the coordinator writes the generated/normalized `TODO.md`, `TASK_RESULT.md`, attempt summaries, and final run details to `tmp/pi-long-task/<run-id>/`.
+6. **Commit only when enabled:** if `commit` is `true`, Pi Long Task may create a commit after each completed task using only eligible task changes. If commits are disabled, no commits are created; even when enabled, commits can be skipped when there are no eligible changes or the task outcome is not commit-worthy.
+
+## Feature reference
+
+- **Sidebar task timeline:** every TODO appears in the sidebar with past, current, and future statuses so you can distinguish completed, active, upcoming, failed, blocked, and remaining work at a glance.
+- **Main-thread worker activity:** the active worker streams commands, edits, verification, and its per-task `TASK_RESULT` back into the main Pi conversation.
+- **Cost visibility:** worker spend is included in Pi Long Task progress and is added to the main Pi `$ spent` total when cost data is available.
+- **Result and TODO artifacts:** each run keeps the generated or normalized `TODO.md`, aggregate `TASK_RESULT.md`, per-attempt summaries, and final run details under `tmp/pi-long-task/<run-id>/`.
+- **Commit-safe behavior:** when commits are enabled, Pi Long Task commits only eligible completed-task changes and skips generated run files.
+- **Dirty-worktree protection:** files that were dirty before a worker started are not included in Pi Long Task commits, keeping your existing local work separate.
+
+## Usage
+
 You can also call the tool explicitly.
 
 Run without commits:
@@ -79,7 +146,7 @@ Run without commits:
 Use pi_long_task with inputText "add tests for the parser and fix any failures" and commit false.
 ```
 
-Run and allow commits:
+Run with commits:
 
 ```text
 Use pi_long_task with inputText "implement the TODOs in @TODO.md" and commit true.
@@ -137,9 +204,9 @@ This lets you keep existing local work separate from Pi Long Task changes.
 
 Commit messages are generated from the task title and adjusted to resemble recent commit-message style in the repository. Pi Long Task does not prefix commits with generated labels like `Complete TODO 1 — ...`.
 
-## Validate the install
+## Development and validation
 
-Run the local checks:
+Run the local development checks:
 
 ```bash
 cd /path/to/pi-long-task
@@ -160,10 +227,11 @@ npm run smoke:native
 
 That smoke test creates disposable git repos and verifies both `commit: false` and `commit: true` runs.
 
-## Notes
+## Limitations and expectations
 
-- Tasks run one at a time.
-- Real runs require a working Pi model/login or API key.
+- Tasks run sequentially, one TODO at a time; Pi Long Task prioritizes isolation, progress tracking, and safe handoff over parallel execution.
+- Real runs require usable Pi model credentials, such as a working Pi login or API key for the selected model.
+- Worker spend is added to the main Pi `$ spent` total as cost-only usage. Token counts are not merged into the main thread because worker sessions have separate context windows, and merging their token usage would corrupt the main conversation's context statistics.
 - Run artifacts are written under `tmp/pi-long-task/<run-id>/`.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-long-task",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "Pi extension for breaking down and running long coding tasks safely.",
   "keywords": [

package/src/coordinator.ts

@@ -80,6 +80,7 @@ export interface CoordinatorProgressUpdate {
   workerEventType?: string;
   isError?: boolean;
   totalTasks?: number;
+  workerCostTotal: number;
   currentTask?: CoordinatorProgressTask;
   subtasks?: CoordinatorProgressSubtask[];
   taskProgress?: TaskProgressModel;
@@ -145,10 +146,18 @@ export interface CoordinatorResult {
   commits: CoordinatorCommitSummary[];
   attempts: TaskAttemptSummary[];
   taskProgress: TaskProgressModel;
+  workerCostTotal: number;
   commit: boolean;
   error?: string;
 }
 
+interface WorkerCostState {
+  total: number;
+  finalizedByWorker: Map<string, number>;
+  liveByWorker: Map<string, number>;
+  liveByMessage: Map<string, number>;
+}
+
 interface RuntimeOptions {
   cwd: string;
   runId: string;
@@ -167,6 +176,7 @@ interface RuntimeOptions {
   todoSessionFactory?: WorkerSessionFactory;
   now: () => Date;
   onProgress?: CoordinatorProgressHandler;
+  workerCostState: WorkerCostState;
 }
 
 export async function runCoordinator(options: RunCoordinatorOptions): Promise<CoordinatorResult> {
@@ -237,6 +247,7 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
         onEvent: (event) => emitWorkerEventProgress(runtime, tasksBeforeAttempt, nextTask, attempts, attempt, event),
       });
       outcomes.push(outcome);
+      finalizeWorkerCost(runtime.workerCostState, outcome);
 
       if (outcome.done) {
         todoMarkdown = markTaskDone(todoMarkdown, nextTask.taskId);
@@ -346,6 +357,7 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       commits,
       attempts,
       taskProgress,
+      workerCostTotal: runtime.workerCostState.total,
       commit: options.commit,
       error: failure,
     };
@@ -385,6 +397,7 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       commits,
       attempts,
       taskProgress: buildTaskProgressModel({ tasks: [], attempts }),
+      workerCostTotal: runtime.workerCostState.total,
       commit: options.commit,
       error: message,
     };
@@ -467,23 +480,101 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     todoSessionFactory: options.todoSessionFactory,
     now: options.now ?? (() => new Date()),
     onProgress: options.onProgress,
+    workerCostState: createWorkerCostState(),
   };
 }
 
 function emitProgress(
   runtime: RuntimeOptions,
   message: string,
-  update: Omit<CoordinatorProgressUpdate, "message" | "runId" | "todoPath" | "resultPath">,
+  update: Omit<CoordinatorProgressUpdate, "message" | "runId" | "todoPath" | "resultPath" | "workerCostTotal">,
 ): void {
   runtime.onProgress?.({
     message,
     runId: runtime.runId,
     todoPath: runtime.todoPath,
     resultPath: runtime.taskResultPath,
+    workerCostTotal: runtime.workerCostState.total,
     ...update,
   });
 }
 
+function createWorkerCostState(): WorkerCostState {
+  return {
+    total: 0,
+    finalizedByWorker: new Map(),
+    liveByWorker: new Map(),
+    liveByMessage: new Map(),
+  };
+}
+
+function recordLiveWorkerCost(
+  state: WorkerCostState,
+  worker: string,
+  event: { usageCostTotal?: number; usageCostKey?: string },
+): boolean {
+  if (state.finalizedByWorker.has(worker) || event.usageCostTotal === undefined || !event.usageCostKey) {
+    return false;
+  }
+
+  const cost = finiteNonNegativeNumber(event.usageCostTotal);
+  if (cost === undefined) {
+    return false;
+  }
+
+  const messageKey = `${worker}:${event.usageCostKey}`;
+  if (state.liveByMessage.get(messageKey) === cost) {
+    return false;
+  }
+
+  state.liveByMessage.set(messageKey, cost);
+  recomputeLiveWorkerCost(state, worker);
+  recomputeWorkerCostTotal(state);
+  return true;
+}
+
+function finalizeWorkerCost(
+  state: WorkerCostState,
+  outcome: Pick<SessionOutcome, "task" | "attempt" | "workerCostTotal">,
+): void {
+  const worker = workerKey(outcome.task.taskId, outcome.attempt);
+  state.finalizedByWorker.set(worker, finiteNonNegativeNumber(outcome.workerCostTotal) ?? 0);
+  state.liveByWorker.delete(worker);
+  for (const messageKey of state.liveByMessage.keys()) {
+    if (messageKey.startsWith(`${worker}:`)) {
+      state.liveByMessage.delete(messageKey);
+    }
+  }
+  recomputeWorkerCostTotal(state);
+}
+
+function recomputeLiveWorkerCost(state: WorkerCostState, worker: string): void {
+  let total = 0;
+  for (const [messageKey, cost] of state.liveByMessage) {
+    if (messageKey.startsWith(`${worker}:`)) {
+      total += cost;
+    }
+  }
+  state.liveByWorker.set(worker, total);
+}
+
+function recomputeWorkerCostTotal(state: WorkerCostState): void {
+  let total = 0;
+  for (const cost of state.finalizedByWorker.values()) {
+    total += cost;
+  }
+  for (const [worker, cost] of state.liveByWorker) {
+    if (!state.finalizedByWorker.has(worker)) {
+      total += cost;
+    }
+  }
+  state.total = total;
+}
+
+function workerKey(taskId: string, attempt: number): string {
+  return `${taskId}:${attempt}`;
+}
+
 function currentTaskProgress(
   task: Pick<Task, "taskId" | "title" | "statusItems">,
   status: CoordinatorProgressItemStatus,
@@ -521,13 +612,33 @@ function emitWorkerEventProgress(
   task: Pick<Task, "taskId" | "title" | "statusItems">,
   attempts: readonly TaskAttemptSummary[],
   attempt: number,
-  event: { type: string; toolName?: string; isError?: boolean },
+  event: { type: string; toolName?: string; isError?: boolean; usageCostTotal?: number; usageCostKey?: string },
 ): void {
+  if (event.usageCostTotal !== undefined) {
+    const changed = recordLiveWorkerCost(runtime.workerCostState, workerKey(task.taskId, attempt), event);
+    if (changed) {
+      emitProgress(
+        runtime,
+        `TODO ${task.taskId}: worker cost updated to ${formatCost(runtime.workerCostState.total)}.`,
+        {
+          phase: "worker_tool",
+          taskId: task.taskId,
+          title: task.title,
+          attempt,
+          status: "in_progress",
+          workerEventType: event.type,
+          ...currentTaskProgress(task, "in_progress"),
+          taskProgress: buildTaskProgressModel({ tasks, attempts, currentTaskId: task.taskId }),
+        },
+      );
+    }
+  }
+
   if (!event.toolName || (event.type !== "tool_execution_start" && event.type !== "tool_execution_end")) {
     return;
   }
   const action = event.type === "tool_execution_start" ? "started" : event.isError ? "failed" : "finished";
-  const update: Omit<CoordinatorProgressUpdate, "message" | "runId" | "todoPath" | "resultPath"> = {
+  const update: Omit<CoordinatorProgressUpdate, "message" | "runId" | "todoPath" | "resultPath" | "workerCostTotal"> = {
     phase: "worker_tool",
     taskId: task.taskId,
     title: task.title,
@@ -568,7 +679,7 @@ function emitTaskOutcomeProgress(
     : outcome.reportedStatus === "blocked"
       ? "task_blocked"
       : "task_failed";
-  const update: Omit<CoordinatorProgressUpdate, "message" | "runId" | "todoPath" | "resultPath"> = {
+  const update: Omit<CoordinatorProgressUpdate, "message" | "runId" | "todoPath" | "resultPath" | "workerCostTotal"> = {
     phase,
     taskId: task.taskId,
     title: task.title,
@@ -759,6 +870,20 @@ function positiveMilliseconds(value: number | undefined, fallback: number): numb
   return fallback;
 }
 
+function finiteNonNegativeNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+function formatCost(value: number): string {
+  if (value === 0) {
+    return "$0";
+  }
+  if (value < 0.01) {
+    return `$${value.toFixed(4)}`;
+  }
+  return `$${value.toFixed(2)}`;
+}
+
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }

package/src/index.ts

@@ -1,10 +1,60 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
 
 import { runCoordinator, type CoordinatorProgressUpdate, type CoordinatorResult } from "./coordinator.ts";
 import { longTaskInputTransform } from "./input_router.ts";
 import { renderLongTaskToolCall, renderLongTaskToolResult } from "./render.ts";
 import { PiLongTaskParams } from "./types.ts";
 
+export function createWorkerCostAccumulator() {
+  let pendingWorkerCostTotal = 0;
+
+  return {
+    add(cost: number): void {
+      const value = finiteNonNegativeNumber(cost);
+      if (value && value > 0) {
+        pendingWorkerCostTotal += value;
+      }
+    },
+    applyToAssistantMessage(message: AssistantMessage): AssistantMessage | undefined {
+      if (pendingWorkerCostTotal <= 0) {
+        return undefined;
+      }
+
+      const replacement = addWorkerCostToAssistantMessage(message, pendingWorkerCostTotal);
+      if (replacement) {
+        pendingWorkerCostTotal = 0;
+      }
+      return replacement;
+    },
+  };
+}
+
+export function addWorkerCostToAssistantMessage(
+  message: AssistantMessage,
+  workerCostTotal: number,
+): AssistantMessage | undefined {
+  const workerCost = finiteNonNegativeNumber(workerCostTotal);
+  if (!workerCost || workerCost <= 0) {
+    return undefined;
+  }
+
+  return {
+    ...message,
+    usage: {
+      ...message.usage,
+      cost: {
+        ...message.usage.cost,
+        total: message.usage.cost.total + workerCost,
+      },
+    },
+  };
+}
+
+function finiteNonNegativeNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
 function toolDetails(result: CoordinatorResult) {
   return {
     runId: result.runId,
@@ -19,11 +69,23 @@ function toolDetails(result: CoordinatorResult) {
     blockedTasks: result.blockedTasks,
     remainingTasks: result.remainingTasks,
     taskProgress: result.taskProgress,
+    workerCostTotal: result.workerCostTotal,
     summary: result.summary,
   };
 }
 
 export default function registerPiLongTaskExtension(pi: ExtensionAPI) {
+  const workerCostAccumulator = createWorkerCostAccumulator();
+
+  pi.on("message_end", (event) => {
+    if (event.message.role !== "assistant") {
+      return undefined;
+    }
+
+    const message = workerCostAccumulator.applyToAssistantMessage(event.message);
+    return message ? { message } : undefined;
+  });
+
   pi.on("input", (event) => {
     if (event.source === "extension") {
       return { action: "continue" as const };
@@ -64,6 +126,7 @@ export default function registerPiLongTaskExtension(pi: ExtensionAPI) {
         abortSignal: signal,
         onProgress: publishProgress,
       });
+      workerCostAccumulator.add(result.workerCostTotal);
 
       return {
         content: [

package/src/render.ts

@@ -17,6 +17,7 @@ export interface CoordinatorResultForRendering {
   commits?: CoordinatorCommitSummary[];
   remainingTasks?: CoordinatorRemainingTask[];
   taskProgress?: TaskProgressModel;
+  workerCostTotal?: number;
   error?: string;
 }
 
@@ -45,11 +46,13 @@ const SIDEBAR_GAP = 2;
 class LongTaskSidebarShell implements Component {
   private readonly mainText: string;
   private readonly taskProgress: TaskProgressModel;
+  private readonly workerCostTotal: number | undefined;
   private readonly theme: Theme;
 
-  constructor(mainText: string, taskProgress: TaskProgressModel, theme: Theme) {
+  constructor(mainText: string, taskProgress: TaskProgressModel, theme: Theme, workerCostTotal?: number) {
     this.mainText = mainText;
     this.taskProgress = taskProgress;
+    this.workerCostTotal = workerCostTotal;
     this.theme = theme;
   }
 
@@ -92,7 +95,7 @@ class LongTaskSidebarShell implements Component {
     }
 
     const innerWidth = Math.max(0, width - 2);
-    const rows = sidebarRows(this.taskProgress, this.theme);
+    const rows = sidebarRows(this.taskProgress, this.theme, this.workerCostTotal);
     return [
       sidebarBorder("Long Task", width, this.theme),
       ...rows.map((row) => sidebarRow(row, innerWidth, this.theme)),
@@ -113,6 +116,10 @@ export function formatCoordinatorResultMessage(result: CoordinatorResultForRende
     `TODO file: ${result.todoPath}`,
   ];
 
+  if (result.workerCostTotal) {
+    lines.push(`Worker spend: ${formatCost(result.workerCostTotal)}`);
+  }
+
   const commitLines = commits
     .filter((commit) => commit.hash || commit.error)
     .map((commit) => {
@@ -154,8 +161,9 @@ export function renderLongTaskToolResult(
   const details = recordOrUndefined(result.details);
   if (options.isPartial) {
     const taskProgress = taskProgressModel(details?.taskProgress);
+    const workerCostTotal = numberValue(details?.workerCostTotal);
     const main = renderLongTaskProgress(details, contentText(result), theme);
-    return taskProgress ? new LongTaskSidebarShell(main, taskProgress, theme) : new Text(main, 0, 0);
+    return taskProgress ? new LongTaskSidebarShell(main, taskProgress, theme, workerCostTotal) : new Text(main, 0, 0);
   }
 
   const finalDetails = longTaskDetails(details);
@@ -165,7 +173,7 @@ export function renderLongTaskToolResult(
 
   const main = renderLongTaskSummary(finalDetails, options.expanded, theme);
   return finalDetails.taskProgress
-    ? new LongTaskSidebarShell(main, finalDetails.taskProgress, theme)
+    ? new LongTaskSidebarShell(main, finalDetails.taskProgress, theme, finalDetails.workerCostTotal)
     : new Text(main, 0, 0);
 }
 
@@ -208,6 +216,7 @@ function renderLongTaskSummary(details: CoordinatorToolRenderDetails, expanded:
     details.blockedTasks ? theme.fg("warning", `${details.blockedTasks} blocked`) : undefined,
     remainingCount ? theme.fg("muted", `${remainingCount} remaining`) : undefined,
     commitCount ? theme.fg("success", `${commitCount} commit${commitCount === 1 ? "" : "s"}`) : undefined,
+    details.workerCostTotal ? theme.fg("muted", `worker ${formatCost(details.workerCostTotal)}`) : undefined,
   ].filter(Boolean);
 
   if (!expanded) {
@@ -252,9 +261,12 @@ function padLine(line: string, width: number): string {
   return truncateToWidth(line, width, "…", true);
 }
 
-function sidebarRows(taskProgress: TaskProgressModel, theme: Theme): string[] {
+function sidebarRows(taskProgress: TaskProgressModel, theme: Theme, workerCostTotal?: number): string[] {
   const summary = normalizedTaskProgressSummary(taskProgress);
   const rows = [theme.fg("toolTitle", theme.bold("Task sidebar")), theme.fg("dim", "Centered timeline")];
+  if (workerCostTotal) {
+    rows.push(theme.fg("muted", `Worker spend: ${formatCost(workerCostTotal)}`));
+  }
   if (summary.totalTasks === 0) {
     rows.push("", theme.fg("muted", "Waiting for TODO plan..."));
     return rows;
@@ -503,6 +515,7 @@ function longTaskDetails(details: Record<string, unknown> | undefined): Coordina
     commits: commitSummaries(details.commits),
     remainingTasks: remainingTaskSummaries(details.remainingTasks),
     taskProgress: taskProgressModel(details.taskProgress),
+    workerCostTotal: nonNegativeNumberValue(details.workerCostTotal),
     error: stringValue(details.error),
   };
 }
@@ -592,6 +605,20 @@ function numberValue(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
 
+function nonNegativeNumberValue(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+function formatCost(value: number): string {
+  if (value === 0) {
+    return "$0";
+  }
+  if (value < 0.01) {
+    return `$${value.toFixed(4)}`;
+  }
+  return `$${value.toFixed(2)}`;
+}
+
 function recordOrUndefined(value: unknown): Record<string, unknown> | undefined {
   return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined;
 }

package/src/types.ts

@@ -62,6 +62,7 @@ export interface PiLongTaskResult {
     commitSkipped?: string;
   }>;
   taskProgress: TaskProgressModel;
+  workerCostTotal: number;
   commit: boolean;
   error?: string;
 }

package/src/worker_session.ts

@@ -201,7 +201,7 @@ export interface WorkerSessionLike {
   compact?(customInstructions?: string): Promise<unknown>;
   dispose?(): void;
   getLastAssistantText?(): string | undefined;
-  getSessionStats?(): unknown;
+  getSessionStats?(): unknown | Promise<unknown>;
   getContextUsage?(): unknown;
   sessionFile?: string;
   sessionId?: string;
@@ -246,6 +246,8 @@ export interface CapturedWorkerEvent {
   toolName?: string;
   isError?: boolean;
   note?: string;
+  usageCostTotal?: number;
+  usageCostKey?: string;
 }
 
 export interface SessionOutcome {
@@ -261,6 +263,8 @@ export interface SessionOutcome {
   contextObservations: string[];
   compactionEvents: string[];
   events: CapturedWorkerEvent[];
+  workerCostTotal: number;
+  workerCostSource?: string;
   shutdownRequested: boolean;
   timedOut: boolean;
   aborted: boolean;
@@ -345,6 +349,9 @@ export async function runWorkerTask(options: RunWorkerTaskOptions): Promise<Sess
   let error: string | undefined;
   let finished = false;
   let turnCount = 0;
+  let messageUsageCostTotal = 0;
+  let hasMessageUsageCost = false;
+  let sessionStatsCostTotal: number | undefined;
 
   const prompt = buildTaskPrompt(options);
   const taskTimeoutSeconds = options.taskTimeoutSeconds ?? DEFAULT_TASK_TIMEOUT_SECONDS;
@@ -366,6 +373,22 @@ export async function runWorkerTask(options: RunWorkerTaskOptions): Promise<Sess
     timers.clear();
   };
 
+  const messageUsageCostsByKey = new Map<string, number>();
+  const recordWorkerUsageCost = (cost: number | undefined, key: string | undefined) => {
+    if (cost === undefined) {
+      return;
+    }
+    hasMessageUsageCost = true;
+    if (!key) {
+      messageUsageCostTotal += cost;
+      return;
+    }
+
+    const previousCost = messageUsageCostsByKey.get(key) ?? 0;
+    messageUsageCostsByKey.set(key, cost);
+    messageUsageCostTotal += cost - previousCost;
+  };
+
   const schedule = (fn: () => void | Promise<void>, ms: number) => {
     const timer = setTimeout(() => {
       timers.delete(timer);
@@ -458,6 +481,7 @@ export async function runWorkerTask(options: RunWorkerTaskOptions): Promise<Sess
           if (messageText) {
             assistantText = messageText;
           }
+          recordWorkerUsageCost(workerUsageCostFromEvent(event), workerUsageCostKeyFromEvent(event));
           break;
         }
         case "turn_end": {
@@ -538,6 +562,7 @@ export async function runWorkerTask(options: RunWorkerTaskOptions): Promise<Sess
       assistantText = latestAssistantText(session, assistantText);
       sessionFile = session.sessionFile ?? sessionFile;
       sessionId = session.sessionId ?? sessionId;
+      sessionStatsCostTotal = await workerUsageCostFromSessionStats(session);
       session.dispose?.();
     }
   }
@@ -547,6 +572,10 @@ export async function runWorkerTask(options: RunWorkerTaskOptions): Promise<Sess
   }
 
   const reportedStatus = parseReportedStatus(assistantText);
+  const capturedWorkerCost = selectWorkerCostTotal({
+    messageCostTotal: hasMessageUsageCost ? messageUsageCostTotal : undefined,
+    statsCostTotal: sessionStatsCostTotal,
+  });
   return {
     task: options.task,
     attempt: options.attempt,
@@ -560,6 +589,8 @@ export async function runWorkerTask(options: RunWorkerTaskOptions): Promise<Sess
     contextObservations,
     compactionEvents,
     events,
+    workerCostTotal: capturedWorkerCost.total,
+    workerCostSource: capturedWorkerCost.source,
     shutdownRequested,
     timedOut,
     aborted: aborted || Boolean(options.abortSignal?.aborted),
@@ -723,9 +754,15 @@ function summarizeWorkerEvent(event: unknown): CapturedWorkerEvent | undefined {
     };
   }
 
+  if (event.type === "message_end") {
+    const usageCostTotal = workerUsageCostFromEvent(event);
+    return usageCostTotal === undefined
+      ? { type: event.type }
+      : { type: event.type, usageCostTotal, usageCostKey: workerUsageCostKeyFromEvent(event) };
+  }
+
   if (
     event.type === "turn_end" ||
-    event.type === "message_end" ||
     event.type === "compaction_start" ||
     event.type === "compaction_end" ||
     event.type === "agent_end" ||
@@ -738,6 +775,109 @@ function summarizeWorkerEvent(event: unknown): CapturedWorkerEvent | undefined {
   return undefined;
 }
 
+export function workerUsageCostFromEvent(event: unknown): number | undefined {
+  if (!isRecord(event)) {
+    return undefined;
+  }
+
+  for (const candidate of [event.assistantMessage, event.message, event]) {
+    const cost = workerUsageCostFromAssistantMessage(candidate);
+    if (cost !== undefined) {
+      return cost;
+    }
+  }
+  return undefined;
+}
+
+export function workerUsageCostFromAssistantMessage(message: unknown): number | undefined {
+  if (!isRecord(message)) {
+    return undefined;
+  }
+  return usageCostTotal(message.usage);
+}
+
+export function workerUsageCostKeyFromEvent(event: unknown): string | undefined {
+  if (!isRecord(event)) {
+    return undefined;
+  }
+
+  for (const candidate of [event.assistantMessage, event.message, event]) {
+    const key = workerUsageCostKeyFromAssistantMessage(candidate);
+    if (key) {
+      return key;
+    }
+  }
+  return undefined;
+}
+
+function workerUsageCostKeyFromAssistantMessage(message: unknown): string | undefined {
+  if (!isRecord(message)) {
+    return undefined;
+  }
+
+  for (const keyName of ["id", "messageId", "uuid"] as const) {
+    const value = message[keyName];
+    if (typeof value === "string" && value) {
+      return `${keyName}:${value}`;
+    }
+  }
+  return undefined;
+}
+
+export function workerUsageCostFromStats(stats: unknown): number | undefined {
+  if (!isRecord(stats)) {
+    return undefined;
+  }
+
+  const directCost = finiteNonNegativeNumber(stats.cost);
+  if (directCost !== undefined) {
+    return directCost;
+  }
+
+  return usageCostTotal(stats.usage) ?? usageCostTotal(stats);
+}
+
+async function workerUsageCostFromSessionStats(session: WorkerSessionLike): Promise<number | undefined> {
+  if (!session.getSessionStats) {
+    return undefined;
+  }
+
+  try {
+    return workerUsageCostFromStats(await session.getSessionStats());
+  } catch {
+    return undefined;
+  }
+}
+
+function usageCostTotal(usage: unknown): number | undefined {
+  if (!isRecord(usage)) {
+    return undefined;
+  }
+
+  const cost = usage.cost;
+  if (isRecord(cost)) {
+    return finiteNonNegativeNumber(cost.total);
+  }
+  return finiteNonNegativeNumber(cost);
+}
+
+function selectWorkerCostTotal(options: { messageCostTotal: number | undefined; statsCostTotal: number | undefined }): {
+  total: number;
+  source?: string;
+} {
+  if (options.statsCostTotal !== undefined) {
+    return { total: options.statsCostTotal, source: "session_stats" };
+  }
+  if (options.messageCostTotal !== undefined) {
+    return { total: options.messageCostTotal, source: "message_end" };
+  }
+  return { total: 0 };
+}
+
+function finiteNonNegativeNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
 function captureContextUsage(
   session: WorkerSessionLike | undefined,
   turnCount: number,