@pi-archimedes/subagent 2.10.3 → 2.11.0

package/src/types.ts

@@ -1,3 +1,5 @@
+import type { Usage } from "@earendil-works/pi-ai";
+
 export interface SubagentUsage {
   input: number;
   output: number;
@@ -13,9 +15,27 @@ export interface SubagentToolCall {
   error: boolean;
 }
 
+/**
+ * The terminal state of a finished run — the suite's fixed vocabulary for it
+ * (`CONTEXT.md`: *Run outcome*).
+ *
+ * `completed` finished within limits; `truncated` finished but hit the output
+ * token limit, so the answer is partial; `aborted` was cancelled. None of them
+ * is a *failed* run — a pre/during-run error carries `error` and **no** outcome.
+ */
+export type RunOutcome = "completed" | "truncated" | "aborted";
+
 export interface SubagentProgress {
   agent: string;
+  /**
+   * The coarse view axis (still running / finished / broke). The three-valued
+   * *Run outcome* lives in `outcome`, which is what the renderers show when a
+   * run has finished — a truncated run is not `failed`, and an aborted one is
+   * not `completed`, whatever the row's status has to say for layout.
+   */
   status: "running" | "completed" | "failed";
+  /** Set once the run reaches a terminal state; absent for a failed run. */
+  outcome?: RunOutcome;
   task: string;
   currentTool: string | undefined;
   currentToolArgs: string | undefined;
@@ -43,7 +63,29 @@ export interface SubagentResult {
   /** Logical Pi session UUID for this spawned subagent process. */
   childSessionId?: string;
   exitCode: number;
+  /**
+   * How the run ended, when it ended. Absent when the run **failed** (an error
+   * before or during the run), which is the case `error` and `isError` describe.
+   */
+  outcome?: RunOutcome;
   usage: SubagentUsage;
+  /**
+   * The run happened somewhere that already books its usage, so **this** session
+   * must not also report it on the tool result.
+   *
+   * Set for a bridge-dispatched run: the desktop runs it as a session of its own
+   * on its worker runtime, and that session's total is the number its Client
+   * shows. `usage` still carries the metrics for display in `details`, but
+   * `toNativeUsage`/`sumNativeUsage` leave it out, because pi folds a tool
+   * result's `usage` into *this* session's totals — publishing it here would add
+   * the same money to the parent's view of a run the parent did not perform
+   * (ADR 0028: cost is counted once, which is why the `COST_UPDATE` bus route was
+   * deleted rather than left alone).
+   *
+   * Absent on the fork path, where the child is a bare `pi --mode json` process
+   * that reports nothing to anyone: the tool result is the only cost report.
+   */
+  usageAccountedElsewhere?: boolean;
   model: string | undefined;
   finalOutput: string | undefined;
   error: string | undefined;
@@ -54,9 +96,49 @@ export interface SubagentResult {
 export interface SubagentToolResult {
   content: Array<{ type: "text"; text: string }>;
   details: SubagentDetails;
+  /**
+   * The machine-readable result for programmatic callers, matching
+   * `SUBAGENT_OUTPUT_SCHEMA`. Success results only: a failed run reports
+   * `isError` and carries none, so a codemode script keeps rejecting with the
+   * text it rejects with today.
+   *
+   * A type alias, not an interface: `AgentToolResult.structuredContent` is
+   * `JsonValue`, and TypeScript will not match an interface against its index
+   * signature.
+   */
+  structuredContent?: {
+    mode: "single" | "parallel";
+    results: SubagentRunReport[];
+  };
+  /**
+   * The runs' summed usage, in pi's own shape (see `usage.ts`).
+   *
+   * This is the cost report: pi persists it onto the toolResult message and
+   * folds it into `/session`, which is why the `COST_UPDATE` bus route to the
+   * footer was deleted instead of merely abandoned — the footer reads the same
+   * entries and would have counted the money twice.
+   */
+  usage?: Usage;
   isError?: boolean;
 }
 
+/**
+ * The machine-readable report for one run — `SubagentResult` without the live
+ * progress blob (see `subagentStructuredContent()` in `tool-schema.ts`).
+ */
+export type SubagentRunReport = {
+  agent: string;
+  task: string;
+  exitCode: number;
+  childSessionId?: string;
+  outcome?: RunOutcome;
+  usage: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number; turns: number };
+  model?: string;
+  finalOutput?: string;
+  error?: string;
+  progressSummary?: { toolCount: number; tokens: number; durationMs: number };
+};
+
 export interface SubagentDetails {
   mode: "single" | "parallel";
   results: SubagentResult[];
@@ -73,6 +155,10 @@ export interface StreamState {
   totalCacheRead: number;
   totalCacheWrite: number;
   totalCost: number;
+  /** `stopReason` of the last assistant message seen (`length` ⇒ truncated). */
+  lastStopReason?: string;
+  /** `agent_settled.aborted` — pi 1.1.0's own account of a cancelled run. */
+  settledAborted?: boolean;
   currentTool: string | undefined;
   currentToolArgs: string | undefined;
   currentToolStartedAt: number | undefined;

package/src/usage.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from "vitest";
+import { toNativeUsage, sumNativeUsage } from "./usage.js";
+import type { SubagentResult, SubagentUsage } from "./types.js";
+
+// pi folds a tool result's `usage` into the session totals, and it reads exactly
+// these fields (`addUsageToTotals`: input/output/cacheRead/cacheWrite and
+// `cost.total`). A field it has to dereference and finds missing is a NaN in the
+// session's cost, so the shape is the contract these tests pin.
+
+function usage(overrides: Partial<SubagentUsage> = {}): SubagentUsage {
+  return {
+    input: 4000,
+    output: 1500,
+    cacheRead: 512,
+    cacheWrite: 8,
+    cost: 0.2,
+    turns: 3,
+    ...overrides,
+  };
+}
+
+function result(withUsage: SubagentUsage): SubagentResult {
+  return {
+    agent: "reviewer",
+    task: "t",
+    exitCode: 0,
+    usage: withUsage,
+    model: undefined,
+    finalOutput: "x",
+    error: undefined,
+    progress: undefined,
+    progressSummary: undefined,
+  };
+}
+
+describe("toNativeUsage", () => {
+  it("carries every field pi dereferences, with the cost under cost.total", () => {
+    const native = toNativeUsage(usage());
+    expect(native.input).toBe(4000);
+    expect(native.output).toBe(1500);
+    expect(native.cacheRead).toBe(512);
+    expect(native.cacheWrite).toBe(8);
+    expect(native.cost.total).toBeCloseTo(0.2);
+    expect(typeof native.cost.input).toBe("number");
+    expect(typeof native.cost.output).toBe("number");
+    expect(typeof native.cost.cacheRead).toBe("number");
+    expect(typeof native.cost.cacheWrite).toBe("number");
+  });
+
+  it("totalTokens is the sum of the four token kinds, as pi defines it", () => {
+    expect(toNativeUsage(usage()).totalTokens).toBe(4000 + 1500 + 512 + 8);
+  });
+
+  it("a zero run produces zeros, not undefined", () => {
+    const native = toNativeUsage(usage({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 }));
+    expect(native.totalTokens).toBe(0);
+    expect(native.cost.total).toBe(0);
+  });
+});
+
+describe("sumNativeUsage", () => {
+  it("adds a parallel batch into one usage (one tool call, one toolResult message)", () => {
+    const total = sumNativeUsage([result(usage()), result(usage())])!;
+    expect(total.input).toBe(8000);
+    expect(total.output).toBe(3000);
+    expect(total.cost.total).toBeCloseTo(0.4);
+    expect(total.totalTokens).toBe(2 * (4000 + 1500 + 512 + 8));
+  });
+
+  it("returns undefined when there is nothing to report", () => {
+    expect(sumNativeUsage([])).toBeUndefined();
+  });
+});
+
+describe("sumNativeUsage: which runs this session is allowed to report", () => {
+  // A bridge-dispatched run is a session of the desktop's own, and that session
+  // reports its usage to its own Client. Folding the same metrics into THIS
+  // session's totals (which is what a toolResult `usage` does) is the
+  // double-count ADR 0028 deleted the `COST_UPDATE` route to avoid — one tool
+  // call performed elsewhere must not cost twice.
+  const elsewhere = (over: Partial<SubagentUsage> = {}): SubagentResult => ({
+    ...result(usage(over)),
+    usageAccountedElsewhere: true,
+  });
+
+  it("leaves out a run whose usage the runtime that performed it already books", () => {
+    const total = sumNativeUsage([result(usage()), elsewhere()])!;
+    expect(total.input).toBe(4000);
+    expect(total.cost.total).toBeCloseTo(0.2);
+  });
+
+  it("reports nothing at all when every run in the batch was performed elsewhere", () => {
+    expect(sumNativeUsage([elsewhere(), elsewhere()])).toBeUndefined();
+  });
+});

package/src/usage.ts

@@ -0,0 +1,87 @@
+import type { Usage } from "@earendil-works/pi-ai";
+import type { SubagentResult, SubagentUsage } from "./types.js";
+
+// ── Native cost reporting (ADR 0028) ────────────────────────────────────────
+//
+// A tool result may carry `usage`, and pi does the accounting from there: the
+// field is copied onto the toolResult message it persists
+// (`pi-agent-core/dist/agent-loop.js`, `createToolResultMessage` — `usage:
+// finalized.result.usage`) and `AgentSession.getSessionStats()` folds every
+// toolResult message's usage into the session totals
+// (`pi-coding-agent/dist/core/agent-session.js`, the `message.role ===
+// "toolResult"` branch). So a subagent that returns `usage` is counted by
+// `/session`, by the footer's own session scan, and by anything else that reads
+// session stats — with no side channel involved.
+//
+// That is why the old bus route (`subagent/src/cost.ts` → `COST_UPDATE` →
+// `footer/CostAccumulator`) had to go rather than just stop being used: the
+// footer already counts toolResult usage, so leaving the accumulator in place
+// would add the same money twice.
+
+/**
+ * The child's summed usage in pi's own `Usage` shape.
+ *
+ * The child's JSON stream reports one cost **total** per message, which is what
+ * pi adds up (`addUsageToTotals` reads `usage.cost.total`); the per-kind split is
+ * not observable from out here, so it is reported as zero rather than guessed at.
+ * `totalTokens` follows pi's own definition — input + output + both cache kinds.
+ */
+export function toNativeUsage(usage: SubagentUsage): Usage {
+  return {
+    input: usage.input,
+    output: usage.output,
+    cacheRead: usage.cacheRead,
+    cacheWrite: usage.cacheWrite,
+    totalTokens: usage.input + usage.output + usage.cacheRead + usage.cacheWrite,
+    cost: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      total: usage.cost,
+    },
+  };
+}
+
+/**
+ * Sum the usage of several runs into the one `usage` a single tool result can
+ * carry — a parallel batch is one tool call, so it has one toolResult message.
+ *
+ * Runs performed by another runtime (`usageAccountedElsewhere`, i.e. everything
+ * the bridge dispatched) are left out: their session reports its own usage, and
+ * this sum lands in *this* session's totals. A batch of nothing but such runs
+ * reports nothing at all.
+ */
+export function sumNativeUsage(results: SubagentResult[]): Usage | undefined {
+  const counted = results.filter(
+    (r) => r.usage !== undefined && r.usageAccountedElsewhere !== true,
+  );
+  if (counted.length === 0) return undefined;
+  const zero: Usage = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  };
+  return counted.reduce<Usage>((total, result) => {
+      const next = toNativeUsage(result.usage);
+      return {
+        input: total.input + next.input,
+        output: total.output + next.output,
+        cacheRead: total.cacheRead + next.cacheRead,
+        cacheWrite: total.cacheWrite + next.cacheWrite,
+        totalTokens: total.totalTokens + next.totalTokens,
+        cost: {
+          input: total.cost.input + next.cost.input,
+          output: total.cost.output + next.cost.output,
+          cacheRead: total.cost.cacheRead + next.cost.cacheRead,
+          cacheWrite: total.cost.cacheWrite + next.cost.cacheWrite,
+          total: total.cost.total + next.cost.total,
+        },
+      };
+    },
+    zero,
+  );
+}

package/src/cost.test.ts

@@ -1,62 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { Events } from "@pi-archimedes/core/bus";
-
-// ── mock bus ────────────────────────────────────────────────────────────────
-
-let mockEmit: ReturnType<typeof vi.fn>;
-
-vi.mock("@pi-archimedes/core/bus", async (importOriginal) => {
-  const actual = await importOriginal() as typeof import("@pi-archimedes/core/bus");
-  return {
-    ...actual,
-    getBus: () => ({
-      emit: mockEmit,
-    }),
-  };
-});
-
-const { emitCostUpdate } = await import("./cost.js");
-
-describe("emitCostUpdate", () => {
-  beforeEach(() => {
-    mockEmit = vi.fn();
-  });
-
-  it("emits COST_UPDATE event with correct source prefix", () => {
-    emitCostUpdate("my-agent", { inputTokens: 100, outputTokens: 50 });
-
-    expect(mockEmit).toHaveBeenCalledWith(Events.COST_UPDATE, {
-      source: "subagent:my-agent",
-      inputTokens: 100,
-      outputTokens: 50,
-    });
-  });
-
-  it("passes through all usage fields", () => {
-    emitCostUpdate("test-agent", {
-      inputTokens: 1000,
-      outputTokens: 500,
-      cacheReadTokens: 200,
-      cacheWriteTokens: 100,
-      cost: 0.05,
-    });
-
-    expect(mockEmit).toHaveBeenCalledWith(Events.COST_UPDATE, {
-      source: "subagent:test-agent",
-      inputTokens: 1000,
-      outputTokens: 500,
-      cacheReadTokens: 200,
-      cacheWriteTokens: 100,
-      cost: 0.05,
-    });
-  });
-
-  it("works with partial usage fields", () => {
-    emitCostUpdate("minimal", { cost: 0.01 });
-
-    expect(mockEmit).toHaveBeenCalledWith(Events.COST_UPDATE, {
-      source: "subagent:minimal",
-      cost: 0.01,
-    });
-  });
-});

package/src/cost.ts

@@ -1,8 +0,0 @@
-import { getBus, Events } from "@pi-archimedes/core/bus";
-
-export function emitCostUpdate(agent: string, usage: { inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; cost?: number }): void {
-  getBus().emit(Events.COST_UPDATE, {
-    source: `subagent:${agent}`,
-    ...usage,
-  });
-}