@ilya-lesikov/pi-pi 0.5.0 → 0.7.0

package/extensions/orchestrator/usage-tracker.ts

@@ -1,23 +1,41 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { SUB_MODEL_PREFIX, SUB_PROVIDER } from "./flant-infra.js";
+
+/**
+ * A usage unit is subscription-routed (flat-rate personal Claude subscription,
+ * not per-token billed) when its main-turn provider is the subscription
+ * provider, or when the registered model id carries the `sub/` prefix. The
+ * prefix is the only signal available for subagents (subagents:completed has no
+ * provider field), so we always check it in addition to the provider.
+ */
+export function isSubscriptionRouted(modelId?: string, provider?: string): boolean {
+  if (provider === SUB_PROVIDER) return true;
+  return typeof modelId === "string" && modelId.startsWith(SUB_MODEL_PREFIX);
+}
 
 export interface ModelUsage {
   inputTokens: number;
   outputTokens: number;
   cacheReadTokens: number;
   cacheWriteTokens: number;
+  cacheSupported: boolean;
   turns: number;
+  /** Flat-rate personal subscription: dollars are excluded from cost totals, tokens are not. */
+  subscription: boolean;
 }
 
 export interface UsageTracker {
-  recordTurn(modelId: string, provider: string, input: number, output: number, cacheRead: number, cacheWrite: number, cost: number): void;
+  recordTurn(modelId: string, provider: string, input: number, output: number, cacheRead: number, cacheWrite: number, cost: number, cacheSupported?: boolean): void;
   recordSubagentCompletion(tokens: { input?: number; output?: number; total?: number }, cost?: number, meta?: { description?: string; agentType?: string; modelId?: string; durationMs?: number; toolUses?: number }): void;
   loadFromSummary(summary: Record<string, unknown>): void;
   getTotalInputTokens(): number;
   getTotalOutputTokens(): number;
   getTotalCacheReadTokens(): number;
   getTotalCacheWriteTokens(): number;
+  /** Total input the model actually processed: uncached input + cache read + cache write (main + subagents). */
+  getTotalProcessedInputTokens(): number;
   getTotalCost(): number;
   getMainInputTokens(): number;
   getMainOutputTokens(): number;
@@ -25,6 +43,7 @@ export interface UsageTracker {
   getMainCacheWriteTokens(): number;
   getMainCost(): number;
   getCacheHitRate(): number;
+  isCacheSupported(): boolean;
   getPerModelUsage(): Record<string, ModelUsage>;
   getSubagentTotals(): { inputTokens: number; outputTokens: number; cost: number };
   getSubagentList(): SubagentUsage[];
@@ -40,9 +59,12 @@ export interface SubagentUsage {
   outputTokens: number;
   cacheReadTokens: number;
   cacheWriteTokens: number;
+  cacheSupported: boolean;
   cost: number;
   durationMs: number;
   toolUses: number;
+  /** Flat-rate personal subscription: dollars are excluded from cost totals, tokens are not. */
+  subscription: boolean;
 }
 
 interface TrackerState {
@@ -55,6 +77,8 @@ interface TrackerState {
   totalTurns: number;
   subagentInputTokens: number;
   subagentOutputTokens: number;
+  subagentCacheReadTokens: number;
+  subagentCacheWriteTokens: number;
   subagentCost: number;
   models: Map<string, ModelUsage>;
   subagents: SubagentUsage[];
@@ -86,6 +110,8 @@ function createInitialState(): TrackerState {
     totalTurns: 0,
     subagentInputTokens: 0,
     subagentOutputTokens: 0,
+    subagentCacheReadTokens: 0,
+    subagentCacheWriteTokens: 0,
     subagentCost: 0,
     models: new Map<string, ModelUsage>(),
     subagents: [],
@@ -96,12 +122,15 @@ export function createUsageTracker(): UsageTracker {
   const state = createInitialState();
 
   return {
-    recordTurn(modelId: string, _provider: string, input: number, output: number, cacheRead: number, cacheWrite: number, cost: number): void {
+    recordTurn(modelId: string, provider: string, input: number, output: number, cacheRead: number, cacheWrite: number, cost: number, cacheSupported?: boolean): void {
       const safeInput = toFiniteNumber(input);
       const safeOutput = toFiniteNumber(output);
       const safeCacheRead = toFiniteNumber(cacheRead);
       const safeCacheWrite = toFiniteNumber(cacheWrite);
-      const safeCost = toFiniteNumber(cost);
+      const subscription = isSubscriptionRouted(modelId, provider);
+      // Subscription-routed turns are flat-rate: keep the tokens but exclude the
+      // fictitious per-token dollars so totals stay paid-only by construction.
+      const safeCost = subscription ? 0 : toFiniteNumber(cost);
 
       state.totalInputTokens += safeInput;
       state.totalOutputTokens += safeOutput;
@@ -110,19 +139,27 @@ export function createUsageTracker(): UsageTracker {
       state.totalCost += safeCost;
       state.totalTurns += 1;
 
-      const key = modelId || "unknown-model";
+      // Key subscription turns under the sub/ prefix even when detected only by
+      // provider (bare model id), so a paid and a subscription turn for the same
+      // underlying model never share a row and the paid dollars stay visible.
+      const baseKey = modelId || "unknown-model";
+      const key = subscription && !baseKey.startsWith(SUB_MODEL_PREFIX) ? `${SUB_MODEL_PREFIX}${baseKey}` : baseKey;
       const usage = state.models.get(key) ?? {
         inputTokens: 0,
         outputTokens: 0,
         cacheReadTokens: 0,
         cacheWriteTokens: 0,
+        cacheSupported: false,
         turns: 0,
+        subscription: false,
       };
 
       usage.inputTokens += safeInput;
       usage.outputTokens += safeOutput;
       usage.cacheReadTokens += safeCacheRead;
       usage.cacheWriteTokens += safeCacheWrite;
+      if (cacheSupported) usage.cacheSupported = true;
+      if (subscription) usage.subscription = true;
       usage.turns += 1;
       state.models.set(key, usage);
     },
@@ -137,14 +174,21 @@ export function createUsageTracker(): UsageTracker {
       const safeTotal = toFiniteNumber(tokens.total);
       const safeCacheRead = toFiniteNumber(tokens.cacheRead);
       const safeCacheWrite = toFiniteNumber(tokens.cacheWrite);
-      const safeCost = toFiniteNumber(tokens.cost ?? cost);
+      // Subagents carry no provider field, so detect subscription routing from
+      // the registered model id prefix. Zero the dollars when subscription.
+      const subscription = isSubscriptionRouted(meta?.modelId);
+      const safeCost = subscription ? 0 : toFiniteNumber(tokens.cost ?? cost);
 
       const effectiveInput = safeInput === 0 && safeOutput === 0 ? safeTotal : safeInput;
 
       state.subagentInputTokens += effectiveInput;
       state.subagentOutputTokens += safeOutput;
+      state.subagentCacheReadTokens += safeCacheRead;
+      state.subagentCacheWriteTokens += safeCacheWrite;
       state.subagentCost += safeCost;
 
+      const cacheSupported = typeof tokens.cacheRead === "number" || typeof tokens.cacheWrite === "number";
+
       state.subagents.push({
         description: meta?.description ?? "unknown",
         agentType: meta?.agentType ?? "unknown",
@@ -153,9 +197,11 @@ export function createUsageTracker(): UsageTracker {
         outputTokens: safeOutput,
         cacheReadTokens: safeCacheRead,
         cacheWriteTokens: safeCacheWrite,
+        cacheSupported,
         cost: safeCost,
         durationMs: toFiniteNumber(meta?.durationMs),
         toolUses: toFiniteNumber(meta?.toolUses),
+        subscription,
       });
     },
 
@@ -172,22 +218,36 @@ export function createUsageTracker(): UsageTracker {
         state.totalTurns = toFiniteNumber(totals.turns);
       }
       if (Array.isArray(summary.subagents)) {
+        state.subagents = [];
+        state.subagentInputTokens = 0;
+        state.subagentOutputTokens = 0;
+        state.subagentCacheReadTokens = 0;
+        state.subagentCacheWriteTokens = 0;
+        state.subagentCost = 0;
         for (const sa of summary.subagents as Record<string, unknown>[]) {
+          const modelId = typeof sa.modelId === "string" ? sa.modelId : "unknown";
+          // Pre-change summaries lack the flag; recover it from the sub/ prefix
+          // so legacy subscription rows are not restored as paid.
+          const subscription = sa.subscription === true || isSubscriptionRouted(modelId);
           const entry: SubagentUsage = {
             description: typeof sa.description === "string" ? sa.description : "unknown",
             agentType: typeof sa.agentType === "string" ? sa.agentType : "unknown",
-            modelId: typeof sa.modelId === "string" ? sa.modelId : "unknown",
+            modelId,
             inputTokens: toFiniteNumber(sa.inputTokens),
             outputTokens: toFiniteNumber(sa.outputTokens),
             cacheReadTokens: toFiniteNumber(sa.cacheReadTokens),
             cacheWriteTokens: toFiniteNumber(sa.cacheWriteTokens),
-            cost: toFiniteNumber(sa.cost),
+            cacheSupported: sa.cacheSupported === true,
+            cost: subscription ? 0 : toFiniteNumber(sa.cost),
             durationMs: toFiniteNumber(sa.durationMs),
             toolUses: toFiniteNumber(sa.toolUses),
+            subscription,
           };
           state.subagents.push(entry);
           state.subagentInputTokens += entry.inputTokens;
           state.subagentOutputTokens += entry.outputTokens;
+          state.subagentCacheReadTokens += entry.cacheReadTokens;
+          state.subagentCacheWriteTokens += entry.cacheWriteTokens;
           state.subagentCost += entry.cost;
         }
       }
@@ -198,7 +258,9 @@ export function createUsageTracker(): UsageTracker {
             outputTokens: toFiniteNumber(usage.outputTokens),
             cacheReadTokens: toFiniteNumber(usage.cacheReadTokens),
             cacheWriteTokens: toFiniteNumber(usage.cacheWriteTokens),
+            cacheSupported: (usage as any).cacheSupported === true,
             turns: toFiniteNumber(usage.turns),
+            subscription: (usage as any).subscription === true || isSubscriptionRouted(modelId),
           });
         }
       }
@@ -216,11 +278,22 @@ export function createUsageTracker(): UsageTracker {
     },
 
     getTotalCacheReadTokens(): number {
-      return state.totalCacheReadTokens;
+      return state.totalCacheReadTokens + state.subagentCacheReadTokens;
     },
 
     getTotalCacheWriteTokens(): number {
-      return state.totalCacheWriteTokens;
+      return state.totalCacheWriteTokens + state.subagentCacheWriteTokens;
+    },
+
+    getTotalProcessedInputTokens(): number {
+      return (
+        state.totalInputTokens +
+        state.subagentInputTokens +
+        state.totalCacheReadTokens +
+        state.subagentCacheReadTokens +
+        state.totalCacheWriteTokens +
+        state.subagentCacheWriteTokens
+      );
     },
 
     getTotalCost(): number {
@@ -248,13 +321,22 @@ export function createUsageTracker(): UsageTracker {
     },
 
     getCacheHitRate(): number {
-      const totalInput = state.totalInputTokens + state.subagentInputTokens;
-      const totalCacheRead = state.totalCacheReadTokens;
-      const denominator = totalCacheRead + totalInput;
+      const totalCacheRead = state.totalCacheReadTokens + state.subagentCacheReadTokens;
+      // Session-wide, token-weighted average: cache reads over all processed
+      // input (uncached input + cache read + cache write). Including cache
+      // writes keeps first-touch (uncached) content from inflating the rate.
+      const denominator = this.getTotalProcessedInputTokens();
       if (denominator <= 0) return 0;
       return totalCacheRead / denominator;
     },
 
+    isCacheSupported(): boolean {
+      for (const usage of state.models.values()) {
+        if (usage.cacheSupported) return true;
+      }
+      return state.subagents.some((sa) => sa.cacheSupported);
+    },
+
     getPerModelUsage(): Record<string, ModelUsage> {
       const out: Record<string, ModelUsage> = {};
       for (const [model, usage] of state.models.entries()) {
@@ -303,6 +385,8 @@ export function createUsageTracker(): UsageTracker {
       state.totalTurns = 0;
       state.subagentInputTokens = 0;
       state.subagentOutputTokens = 0;
+      state.subagentCacheReadTokens = 0;
+      state.subagentCacheWriteTokens = 0;
       state.subagentCost = 0;
       state.models.clear();
       state.subagents = [];

package/extensions/orchestrator/validate-artifacts.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { validatePlan, validateUserRequest } from "./validate-artifacts.js";
+import { validateArtifact, validatePlan, validateResearch, validateUserRequest } from "./validate-artifacts.js";
 
 describe("validateUserRequest", () => {
   it("rejects placeholder distillation and constraints content", () => {
@@ -86,3 +86,85 @@ Ship minimal fix.
     expect(result.errors).toContain("Section ## Scope is empty. Expected 2-4 lines summarizing scope and constraints.");
   });
 });
+
+describe("validateResearch", () => {
+  it("accepts valid research content", () => {
+    const content = `## Affected Code
+src/main.ts:run — entry point
+
+## Architecture Context
+- Main flow calls run and dispatches handlers
+
+## Constraints & Edge Cases
+- MUST: Keep behavior backward compatible
+- RISK: Regression in startup path
+
+## Open Questions
+Need confirmation about deprecated flag
+`;
+
+    const result = validateResearch(content);
+
+    expect(result.ok).toBe(true);
+  });
+
+  it("fails when required sections are missing", () => {
+    const content = `## Affected Code
+src/main.ts:run — entry point
+
+## Constraints & Edge Cases
+- MUST: Keep behavior backward compatible
+`;
+
+    const result = validateResearch(content);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.errors.some((error) => error.includes("Missing required section: ## Architecture Context"))).toBe(true);
+  });
+
+  it("fails when affected code section is empty", () => {
+    const content = `## Affected Code
+...
+
+## Architecture Context
+- Main flow calls run and dispatches handlers
+
+## Constraints & Edge Cases
+- MUST: Keep behavior backward compatible
+`;
+
+    const result = validateResearch(content);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.errors).toContain("Section ## Affected Code is empty. Expected non-empty content.");
+  });
+});
+
+describe("validateArtifact", () => {
+  it("accepts valid artifact with top-level title", () => {
+    const content = `# Risk Analysis
+
+- First risk
+- Second risk
+`;
+
+    const result = validateArtifact(content);
+
+    expect(result.ok).toBe(true);
+  });
+
+  it("fails when top-level title heading is missing", () => {
+    const content = `## Risk Analysis
+
+- First risk
+`;
+
+    const result = validateArtifact(content);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.errors.some((error) => error.includes("Expected a top-level heading"))).toBe(true);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ilya-lesikov/pi-pi",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Pi-Pi Coding Agent: based on Pi Coding Agent, but twice as good",
   "keywords": [
     "pi-package",
@@ -52,6 +52,7 @@
     "@pierre/diffs": "^1.2.0",
     "effect": "^3.0.0",
     "minimatch": "^10.0.0",
+    "pino": "^10.3.1",
     "proper-lockfile": "^4.1.2",
     "turndown": "^7.2.0",
     "typebox": "^1.0.0"