@gonrocca/zero-pi 0.1.56 → 0.1.57

package/README.md

@@ -76,6 +76,7 @@ into `/forge` for you.
 | **Strict TDD** | The build phase drives RED → GREEN → TRIANGULATE → REFACTOR with a TDD Cycle Evidence table; veredicto audits it. On by default, runtime-gated on a test runner; `tdd.mode: "off"` disables it. |
 | **`/zero-models`** | Pick the model + provider + thinking level for each SDD phase — a boxed-window picker, or set one directly. |
 | **Autotune** | Learns which model fits each phase from your run history and re-tunes itself. |
+| **`/zero-cost`** | Aggregates a run's sub-agent `meta.json` files into a per-phase token/cost/duration report — no schema change, reads what pi already writes. |
 | **`/zero-sync` / `/zero-archive`** | Folds each run's spec delta into a canonical, project-wide spec store and archives approved runs. |
 | **Git / PR / Issues** | `/zero-branch`, `/zero-git-validate`, `/zero-pr`, and `/zero-issue` keep branches and GitHub links audit-ready. |
 | **Run memory** | Every run recalls and saves traces to Cortex, so runs learn from each other. |
@@ -98,6 +99,7 @@ into `/forge` for you.
 | `/zero-archive <slug>` | Merge an approved run into `.sdd/specs/`, move it to `.sdd/archive/YYYY-MM-DD-<slug>/`, and persist `archivePath`. |
 | `/zero-validate <slug>` | Validate proposal/spec/design/tasks artifacts, including task schema and per-domain specs. |
 | `/zero-status` | Show each `.sdd/` run's artifact, sync, latest-verdict, and GitHub-link status. |
+| `/zero-cost [<slug>]` | Report tokens (in/out/cache), USD cost, duration, and tool-count per SDD phase for a run — `<slug>` for a specific run, no argument for the most recent. |
 | `/zero-branch <slug>` | Create/reuse the configured SDD Git branch and persist `branch`/`baseBranch`. |
 | `/zero-git-validate <slug>` | Check worktree, branch, remote, `gh auth`, and verdict gating before PR/archive. |
 | `/zero-pr <slug>` | Create an audit-ready GitHub PR from a run that already has verdict `pasa`. |

package/extensions/format-tokens.ts

@@ -0,0 +1,14 @@
+// Pure helper: compact token count to a short human string.
+// 1234 → "1.2k", 4_695_040 → "4.7M", 999 → "999".
+//
+// Intentionally separate from `formatTokenCount` in zero-statusline.ts,
+// which uses a different contract; this helper requires lowercase `k`,
+// uppercase `M`, and uppercase `B` suffixes.
+
+export function formatTokens(n: number): string {
+  if (!Number.isFinite(n) || n < 0) return "0";
+  if (n < 1000) return `${Math.floor(n)}`;
+  if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
+  if (n < 1_000_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  return `${(n / 1_000_000_000).toFixed(1)}B`;
+}

package/extensions/zero-cost-extension.ts

@@ -0,0 +1,59 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { parseMeta, selectRunMetas, aggregateRun, formatReport, type PhaseMeta } from "./zero-cost.ts";
+
+type NotifyType = "info" | "warning" | "error";
+interface PiCommandContext { ui: { notify(message: string, type?: NotifyType): void } }
+interface PiExtensionAPI { registerCommand(name: string, options: { description?: string; handler: (args: string, ctx: PiCommandContext) => void | Promise<void> }): void }
+
+/** Read every sub-agent `meta.json` across all pi session dirs and parse the
+ *  zero-<phase> ones. Scanning every session keeps us decoupled from pi's
+ *  cwd-encoding scheme; selection by slug/timestamp narrows to one run. */
+function readAllPhaseMetas(): PhaseMeta[] {
+  const root = join(homedir(), ".pi", "agent", "sessions");
+  if (!existsSync(root)) return [];
+  const out: PhaseMeta[] = [];
+  for (const session of readdirSync(root, { withFileTypes: true })) {
+    if (!session.isDirectory()) continue;
+    const artifacts = join(root, session.name, "subagent-artifacts");
+    if (!existsSync(artifacts)) continue;
+    for (const f of readdirSync(artifacts)) {
+      if (!f.endsWith("_meta.json")) continue;
+      try {
+        const meta = parseMeta(JSON.parse(readFileSync(join(artifacts, f), "utf8")));
+        if (meta) out.push(meta);
+      } catch { /* skip unreadable / malformed meta */ }
+    }
+  }
+  return out;
+}
+
+function runCost(args: string, ctx: PiCommandContext): void {
+  const notify = (m: string, t?: NotifyType) => { try { ctx.ui.notify(m, t); } catch {} };
+  const slug = args.trim() || null;
+  const metas = readAllPhaseMetas();
+  const selected = selectRunMetas(metas, slug);
+  if (selected.length === 0) {
+    notify(
+      slug
+        ? `zero-cost: no encontré datos de costo para "${slug}".`
+        : "zero-cost: no encontré runs con datos de costo todavía.",
+      "info",
+    );
+    return;
+  }
+  notify(formatReport(aggregateRun(selected, slug ?? selected[0]?.slug ?? null)), "info");
+}
+
+export default function register(pi?: PiExtensionAPI): void {
+  if (!pi || typeof pi.registerCommand !== "function") return;
+  pi.registerCommand("zero-cost", {
+    description: "Reporta tokens, costo y duración por fase de un run SDD (slug opcional; sin slug = el más reciente)",
+    handler: (args: string, ctx: PiCommandContext): void => {
+      try { if (ctx?.ui?.notify) runCost(args ?? "", ctx); }
+      catch (err) { try { ctx.ui.notify(`zero-cost: ${err instanceof Error ? err.message : String(err)}`, "error"); } catch {} }
+    },
+  });
+}

package/extensions/zero-cost.ts

@@ -0,0 +1,220 @@
+// zero-pi — per-run cost/usage report, pure-logic module.
+//
+// A `/forge` run delegates each phase to a sub-agent that writes a
+// `*_meta.json` under `~/.pi/agent/sessions/<session>/subagent-artifacts/`
+// carrying real `usage` (tokens + cost), `model`, `durationMs` and
+// `toolCount`. `~/.pi/zero-runs.jsonl` records the verdict/rounds/model but
+// never cost — so there is no aggregate view of what a run cost, by phase.
+//
+// This module turns those raw meta records into a per-phase + total report.
+// Every decision (phase mapping, slug extraction, selection, aggregation,
+// formatting) lives here as plain, dependency-free TypeScript so it is
+// testable in isolation. The pi wiring lives in `zero-cost-extension.ts`.
+
+import { formatTokens } from "./format-tokens.ts";
+
+/** The SDD phases a run is composed of, in pipeline order. */
+export const COST_PHASES = ["explore", "plan", "build", "veredicto"] as const;
+export type CostPhase = (typeof COST_PHASES)[number];
+
+/** Token + cost usage of a single sub-agent run. */
+export interface PhaseUsage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  turns: number;
+}
+
+/** One normalized sub-agent `meta.json` belonging to a phase. */
+export interface PhaseMeta {
+  runId: string;
+  phase: CostPhase;
+  /** Feature slug extracted from the sub-agent task, or `null`. */
+  slug: string | null;
+  model: string;
+  usage: PhaseUsage;
+  durationMs: number;
+  toolCount: number;
+  /** Epoch ms the meta was written (newest wins for selection/model). */
+  timestamp: number;
+}
+
+/** One phase row: summed usage of every sub-agent that ran that phase. */
+export interface PhaseAggregate extends PhaseUsage {
+  phase: CostPhase;
+  model: string;
+  subAgents: number;
+  durationMs: number;
+  toolCount: number;
+}
+
+/** The aggregated cost of a whole run. */
+export interface RunCost {
+  slug: string | null;
+  phases: PhaseAggregate[];
+  total: PhaseUsage & { durationMs: number; toolCount: number; subAgents: number };
+}
+
+const PHASE_INDEX: Record<CostPhase, number> = { explore: 0, plan: 1, build: 2, veredicto: 3 };
+
+/** Map a sub-agent name `zero-<phase>` to its phase, or `null`. */
+export function phaseFromAgent(agent: unknown): CostPhase | null {
+  if (typeof agent !== "string") return null;
+  const m = /^zero-(explore|plan|build|veredicto)$/.exec(agent);
+  return m ? (m[1] as CostPhase) : null;
+}
+
+/** Extract the feature slug from the first `.sdd/<slug>/` in a task string.
+ *  The internal `specs` and `archive` directories are never slugs. */
+export function extractSlug(task: unknown): string | null {
+  if (typeof task !== "string") return null;
+  const re = /\.sdd\/([A-Za-z0-9._-]+)\//g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(task)) !== null) {
+    const slug = m[1];
+    if (slug && slug !== "specs" && slug !== "archive") return slug;
+  }
+  return null;
+}
+
+function num(v: unknown): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+
+function asUsage(raw: unknown): PhaseUsage | null {
+  if (!raw || typeof raw !== "object") return null;
+  const u = raw as Record<string, unknown>;
+  // A usage object must carry at least the token fields as numbers.
+  if (typeof u.input !== "number" && typeof u.output !== "number") return null;
+  return {
+    input: num(u.input),
+    output: num(u.output),
+    cacheRead: num(u.cacheRead),
+    cacheWrite: num(u.cacheWrite),
+    cost: num(u.cost),
+    turns: num(u.turns),
+  };
+}
+
+/** Parse one raw `meta.json` object into a `PhaseMeta`, or `null` if it is not
+ *  a zero-<phase> sub-agent or lacks a usage object. */
+export function parseMeta(raw: unknown): PhaseMeta | null {
+  if (!raw || typeof raw !== "object") return null;
+  const r = raw as Record<string, unknown>;
+  const phase = phaseFromAgent(r.agent);
+  if (!phase) return null;
+  const usage = asUsage(r.usage);
+  if (!usage) return null;
+  return {
+    runId: typeof r.runId === "string" ? r.runId : "",
+    phase,
+    slug: extractSlug(r.task),
+    model: typeof r.model === "string" ? r.model : "",
+    usage,
+    durationMs: num(r.durationMs),
+    toolCount: num(r.toolCount),
+    timestamp: num(r.timestamp),
+  };
+}
+
+/** Select the phase-metas for one run: the given slug, or — by default — the
+ *  slug whose newest meta has the greatest timestamp. Slug-less metas are
+ *  ignored for the default pick. */
+export function selectRunMetas(metas: readonly PhaseMeta[], slug?: string | null): PhaseMeta[] {
+  if (slug) return metas.filter((m) => m.slug === slug);
+  let bestSlug: string | null = null;
+  let bestTs = -Infinity;
+  for (const m of metas) {
+    if (m.slug && m.timestamp > bestTs) {
+      bestTs = m.timestamp;
+      bestSlug = m.slug;
+    }
+  }
+  if (bestSlug === null) return [];
+  return metas.filter((m) => m.slug === bestSlug);
+}
+
+/** Aggregate selected phase-metas into per-phase rows (pipeline order) plus a
+ *  run total. A phase that ran multiple sub-agents sums them; its model is the
+ *  newest meta's model. */
+export function aggregateRun(metas: readonly PhaseMeta[], slug: string | null): RunCost {
+  const byPhase = new Map<CostPhase, PhaseAggregate & { _modelTs: number }>();
+  for (const m of metas) {
+    let agg = byPhase.get(m.phase);
+    if (!agg) {
+      agg = {
+        phase: m.phase,
+        model: m.model,
+        subAgents: 0,
+        input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0,
+        durationMs: 0, toolCount: 0,
+        _modelTs: -Infinity,
+      };
+      byPhase.set(m.phase, agg);
+    }
+    agg.subAgents += 1;
+    agg.input += m.usage.input;
+    agg.output += m.usage.output;
+    agg.cacheRead += m.usage.cacheRead;
+    agg.cacheWrite += m.usage.cacheWrite;
+    agg.cost += m.usage.cost;
+    agg.turns += m.usage.turns;
+    agg.durationMs += m.durationMs;
+    agg.toolCount += m.toolCount;
+    if (m.timestamp >= agg._modelTs) {
+      agg._modelTs = m.timestamp;
+      agg.model = m.model;
+    }
+  }
+  const phases = [...byPhase.values()]
+    .sort((a, b) => PHASE_INDEX[a.phase] - PHASE_INDEX[b.phase])
+    .map(({ _modelTs, ...row }) => row);
+
+  const total = phases.reduce(
+    (t, p) => {
+      t.input += p.input; t.output += p.output; t.cacheRead += p.cacheRead;
+      t.cacheWrite += p.cacheWrite; t.cost += p.cost; t.turns += p.turns;
+      t.durationMs += p.durationMs; t.toolCount += p.toolCount; t.subAgents += p.subAgents;
+      return t;
+    },
+    { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0, durationMs: 0, toolCount: 0, subAgents: 0 },
+  );
+
+  return { slug, phases, total };
+}
+
+/** Human-readable duration: `12s`, `5m31s`. */
+export function formatDuration(ms: number): string {
+  const safe = Number.isFinite(ms) && ms > 0 ? ms : 0;
+  const totalSec = Math.round(safe / 1000);
+  const min = Math.floor(totalSec / 60);
+  const sec = totalSec % 60;
+  return min > 0 ? `${min}m${sec.toString().padStart(2, "0")}s` : `${sec}s`;
+}
+
+/** USD with two decimals: `$2.48`. */
+export function formatUsd(n: number): string {
+  const safe = Number.isFinite(n) ? n : 0;
+  return `$${safe.toFixed(2)}`;
+}
+
+/** Render an aligned per-phase + total report. */
+export function formatReport(run: RunCost): string {
+  if (run.phases.length === 0) return "zero-cost: no encontré datos de costo para ese run.";
+  const head = `zero-cost: ${run.slug ?? "(run reciente)"}`;
+  const cols = `fase       sub  in      out     cache    tools  dur     costo`;
+  const lines = [head, cols];
+  const row = (
+    label: string, subs: string, inn: number, out: number, cache: number,
+    tools: number, dur: number, cost: number,
+  ): string =>
+    `${label.padEnd(10)} ${subs.padStart(3)}  ${formatTokens(inn).padStart(6)}  ${formatTokens(out).padStart(6)}  ${formatTokens(cache).padStart(7)}  ${String(tools).padStart(5)}  ${formatDuration(dur).padStart(6)}  ${formatUsd(cost).padStart(7)}`;
+  for (const p of run.phases) {
+    lines.push(row(p.phase, String(p.subAgents), p.input, p.output, p.cacheRead, p.toolCount, p.durationMs, p.cost));
+  }
+  const t = run.total;
+  lines.push(row("TOTAL", String(t.subAgents), t.input, t.output, t.cacheRead, t.toolCount, t.durationMs, t.cost));
+  return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonrocca/zero-pi",
-  "version": "0.1.56",
+  "version": "0.1.57",
   "description": "zero-pi — an installable layer for pi (pi.dev): the zero spec-driven development workflow (explore → plan → build → veredicto) with per-phase model autotune and token-efficient batched builds. Adds capability to pi without modifying pi.",
   "type": "module",
   "keywords": [
@@ -35,6 +35,7 @@
       "./extensions/spec-merge-extension.ts",
       "./extensions/zero-validate-extension.ts",
       "./extensions/zero-status-extension.ts",
+      "./extensions/zero-cost-extension.ts",
       "./extensions/zero-pr-extension.ts",
       "./extensions/zero-branch-extension.ts",
       "./extensions/zero-git-validate-extension.ts",
@@ -66,6 +67,9 @@
     "extensions/zero-validate-extension.ts",
     "extensions/zero-status.ts",
     "extensions/zero-status-extension.ts",
+    "extensions/zero-cost.ts",
+    "extensions/zero-cost-extension.ts",
+    "extensions/format-tokens.ts",
     "extensions/pr-body.ts",
     "extensions/sdd-links.ts",
     "extensions/sdd-config.ts",