@promptctl/cc-candybar 1.17.4 → 1.18.0

package/src/segments/session.ts

@@ -1,30 +1,7 @@
-import { debug } from "../utils/logger";
-import { PricingService } from "./pricing";
-import { failed, ok, type Outcome } from "../utils/outcome";
-import {
-  findAgentTranscripts,
-  parseJsonlFile,
-  type ParsedEntry,
-} from "../utils/claude";
-import { dirname } from "node:path";
-
-export interface SessionUsageEntry {
-  timestamp: string;
-  message: {
-    usage: {
-      input_tokens: number;
-      output_tokens: number;
-      cache_creation_input_tokens?: number;
-      cache_read_input_tokens?: number;
-    };
-  };
-  costUSD?: number;
-}
-
-export interface SessionUsage {
-  totalCost: number;
-  entries: SessionUsageEntry[];
-}
+// [LAW:decomposition] The session usage CONTRACT — the shapes the daemon's
+// SessionUsageStore produces and the render payload reads. The transcript fold
+// that produces them is incremental and lives in the store (its single owner);
+// this module is the type seam both sides agree on.
 
 export interface TokenBreakdown {
   input: number;
@@ -44,145 +21,3 @@ export interface SessionInfo {
 export interface UsageInfo {
   session: SessionInfo;
 }
-
-function convertToSessionEntry(entry: ParsedEntry): SessionUsageEntry {
-  return {
-    timestamp: entry.timestamp.toISOString(),
-    message: {
-      usage: {
-        input_tokens: entry.message?.usage?.input_tokens || 0,
-        output_tokens: entry.message?.usage?.output_tokens || 0,
-        cache_creation_input_tokens:
-          entry.message?.usage?.cache_creation_input_tokens,
-        cache_read_input_tokens: entry.message?.usage?.cache_read_input_tokens,
-      },
-    },
-    costUSD: entry.costUSD,
-  };
-}
-
-export class SessionProvider {
-  // [LAW:one-source-of-truth] The transcript path is always in hand — the
-  // daemon's SessionUsageStore holds it (hookData.transcript_path or its seed
-  // scan) and passes it straight here. There is no lookup-by-id path: recovering
-  // a path we already hold by scanning every project dir is the data-duplication
-  // this method exists to avoid.
-  // [LAW:no-silent-failure] A transcript that exists but can't be read or
-  // parsed is `failed`, not an empty session — the old catch-to-null dressed
-  // a read failure as "no usage", and the lie survived all the way to the
-  // rendered bar. An empty transcript is a real (zero-entry) usage, not
-  // absence.
-  async getSessionUsageFromPath(
-    sessionId: string,
-    transcriptPath: string,
-  ): Promise<Outcome<SessionUsage>> {
-    try {
-      debug(`Found transcript at: ${transcriptPath}`);
-
-      const mainEntries = await parseJsonlFile(transcriptPath);
-      const projectPath = dirname(transcriptPath);
-      const agentTranscripts = await findAgentTranscripts(
-        sessionId,
-        projectPath,
-      );
-
-      debug(`Found ${agentTranscripts.length} agent transcripts for session`);
-
-      // [LAW:one-source-of-truth] parseJsonlFile returns its cached entries
-      // array BY REFERENCE; the parse cache is the canonical store of a file's
-      // parsed entries and is shared across providers. Mutating that array
-      // (the old `push`) corrupted the cache — agent entries leaked into the
-      // main transcript's cached value and re-appended on every warm hit.
-      // Build a fresh combined list instead so no shared array is touched.
-      const agentEntries = (
-        await Promise.all(agentTranscripts.map((p) => parseJsonlFile(p)))
-      ).flat();
-      const parsedEntries = [...mainEntries, ...agentEntries];
-
-      if (parsedEntries.length === 0) {
-        return ok({ totalCost: 0, entries: [] });
-      }
-
-      const entries: SessionUsageEntry[] = [];
-      let totalCost = 0;
-
-      for (const entry of parsedEntries) {
-        if (entry.message?.usage) {
-          const sessionEntry = convertToSessionEntry(entry);
-
-          if (sessionEntry.costUSD !== undefined) {
-            totalCost += sessionEntry.costUSD;
-          } else {
-            const cost = await PricingService.calculateCostForEntry(entry.raw);
-            sessionEntry.costUSD = cost;
-            totalCost += cost;
-          }
-
-          entries.push(sessionEntry);
-        }
-      }
-
-      debug(
-        `Parsed ${entries.length} usage entries, total cost: $${totalCost.toFixed(4)}`,
-      );
-      return ok({ totalCost, entries });
-    } catch (error) {
-      return failed(
-        `session transcript (${sessionId}): ${error instanceof Error ? error.message : String(error)}`,
-      );
-    }
-  }
-
-  calculateTokenBreakdown(entries: SessionUsageEntry[]): TokenBreakdown {
-    return entries.reduce(
-      (breakdown, entry) => ({
-        input: breakdown.input + (entry.message.usage.input_tokens || 0),
-        output: breakdown.output + (entry.message.usage.output_tokens || 0),
-        cacheCreation:
-          breakdown.cacheCreation +
-          (entry.message.usage.cache_creation_input_tokens || 0),
-        cacheRead:
-          breakdown.cacheRead +
-          (entry.message.usage.cache_read_input_tokens || 0),
-      }),
-      { input: 0, output: 0, cacheCreation: 0, cacheRead: 0 },
-    );
-  }
-
-  // [LAW:types-are-the-program] Pure projection SessionUsage → SessionInfo, no
-  // I/O. The store computes it once per ingest from already-parsed usage; the
-  // empty-usage arm yields the all-null SessionInfo (which the payload drops).
-  toSessionInfo(sessionUsage: SessionUsage): SessionInfo {
-    if (sessionUsage.entries.length === 0) {
-      return {
-        cost: null,
-        calculatedCost: null,
-        officialCost: null,
-        tokens: null,
-        tokenBreakdown: null,
-      };
-    }
-
-    const tokenBreakdown = this.calculateTokenBreakdown(sessionUsage.entries);
-    const totalTokens =
-      tokenBreakdown.input +
-      tokenBreakdown.output +
-      tokenBreakdown.cacheCreation +
-      tokenBreakdown.cacheRead;
-
-    // [LAW:single-enforcer] Transcript-derived projection only. `cost` is the
-    // priced-transcript total; the authoritative native cost (officialCost =
-    // hook total_cost_usd) is overlaid by the store at READ time — it is
-    // per-render and must not be frozen into this mtime-keyed record, so it is
-    // null here by construction.
-    const calculatedCost = sessionUsage.totalCost;
-
-    return {
-      cost: calculatedCost,
-      calculatedCost,
-      officialCost: null,
-      tokens: totalTokens,
-      tokenBreakdown,
-    };
-  }
-}

package/src/utils/claude.ts

@@ -1,11 +1,12 @@
 import { existsSync, createReadStream } from "node:fs";
 // [LAW:single-enforcer] readdir/readFile/stat come from the gated transcript-fs
 // owner, not node:fs/promises — the in-flight-I/O bound lives at one seam.
-import { readdir, readFile, stat } from "./transcript-fs";
+import { readdir, readFile, readAppended, stat } from "./transcript-fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { createInterface } from "node:readline";
 import { debug } from "./logger";
+import { ok, type Outcome } from "./outcome";
 
 export interface ClaudeHookData {
   // cc-candybar internal — not part of Anthropic's schema
@@ -147,6 +148,12 @@ export async function findProjectPaths(
 export async function findAgentTranscripts(
   sessionId: string,
   projectPath: string,
+  // [LAW:one-source-of-truth] Agent-file session identity is IMMUTABLE — a file
+  // that belonged to this session never changes owner. Paths in `verified` skip
+  // the first-line readFile, so an incremental refold (which passes its prior
+  // file set) pays the O(file) verification only for NEWLY-appeared sidechains,
+  // not every sidechain every render. The readdir still runs (cheap).
+  verified?: ReadonlySet<string>,
 ): Promise<string[]> {
   const agentFiles: string[] = [];
 
@@ -160,6 +167,10 @@ export async function findAgentTranscripts(
 
     for (const fileName of agentFileNames) {
       const filePath = join(subagentsDir, fileName);
+      if (verified?.has(filePath)) {
+        agentFiles.push(filePath);
+        continue;
+      }
       try {
         const content = await readFile(filePath, "utf-8");
         const firstLine = content.split("\n")[0];
@@ -436,17 +447,13 @@ function makeEntry(parsed: Record<string, unknown>): ParsedEntry | null {
   };
 }
 
-async function parseJsonlFileInMemory(
-  filePath: string,
-): Promise<ParsedEntry[]> {
-  const content = await readFile(filePath, "utf-8");
-  const lines = content
-    .trim()
-    .split("\n")
-    .filter((line) => line.trim());
+// [LAW:one-source-of-truth] The one line→entry loop. Both the whole-file parse
+// and the incremental append reader frame their text into lines through here, so
+// a malformed-line policy or a projected field can never diverge between the two.
+function parseJsonlLines(text: string): ParsedEntry[] {
   const entries: ParsedEntry[] = [];
-
-  for (const line of lines) {
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
     try {
       const entry = makeEntry(JSON.parse(line));
       if (entry) entries.push(entry);
@@ -455,10 +462,70 @@ async function parseJsonlFileInMemory(
       continue;
     }
   }
-
   return entries;
 }
 
+async function parseJsonlFileInMemory(
+  filePath: string,
+): Promise<ParsedEntry[]> {
+  const content = await readFile(filePath, "utf-8");
+  return parseJsonlLines(content);
+}
+
+// A byte cursor into an append-only transcript: the offset consumed through the
+// last complete line, the mtime observed at that read, and the inode. The store
+// keys its per-file fold by this — `offset` bounds the next read to only what's
+// new; `mtimeMs` lets an unchanged file skip the read entirely; `ino` detects a
+// rewrite (a rename-based /compact swaps the inode) so the fold resets instead
+// of splicing new bytes onto a stale prefix.
+export interface TranscriptCursor {
+  readonly offset: number;
+  readonly mtimeMs: number;
+  readonly ino: number;
+}
+
+// [LAW:dataflow-not-control-flow][LAW:one-source-of-truth] Read only the entries
+// appended to an append-only transcript since `prior`. The returned `entries`
+// are TRANSIENT — the caller folds them into its own compact aggregate and drops
+// them, so this reader (unlike the retained parseCache) pins no O(file) memory:
+// its cost is O(bytes appended since last render), which is the whole point.
+//
+// A partial trailing line (a render observing the file mid-write, before its
+// newline) is NOT consumed: the cursor advances only through the last complete
+// line, so the partial line is re-read intact once its newline lands. Cutting at
+// a newline also guarantees clean UTF-8 boundaries (0x0A is never a continuation
+// byte), so no multibyte codepoint is split across reads.
+//
+// `reset` (from readAppended) means the file shrank/was rewritten (a /compact):
+// `entries` then cover the whole new file from offset 0 and the caller discards
+// its prior fold for this file. Absent/failed pass straight through.
+export async function readAppendedEntries(
+  filePath: string,
+  prior: TranscriptCursor | undefined,
+): Promise<
+  Outcome<{ entries: ParsedEntry[]; cursor: TranscriptCursor; reset: boolean }>
+> {
+  const r = await readAppended(
+    filePath,
+    prior === undefined ? undefined : { offset: prior.offset, ino: prior.ino },
+  );
+  if (r.kind !== "ok") return r;
+  const { buf, start, mtimeMs, ino, reset } = r.value;
+  // Consume only through the last newline; a trailing partial line waits.
+  const lastNl = buf.lastIndexOf(0x0a);
+  if (lastNl < 0) {
+    return ok({ entries: [], cursor: { offset: start, mtimeMs, ino }, reset });
+  }
+  const entries = parseJsonlLines(
+    buf.subarray(0, lastNl + 1).toString("utf-8"),
+  );
+  return ok({
+    entries,
+    cursor: { offset: start + lastNl + 1, mtimeMs, ino },
+    reset,
+  });
+}
+
 async function parseJsonlFileStreaming(
   filePath: string,
 ): Promise<ParsedEntry[]> {

package/src/utils/transcript-fs.ts

@@ -5,8 +5,25 @@ import {
   stat as fsStat,
 } from "node:fs/promises";
 import type { FileHandle } from "node:fs/promises";
+import { statSync } from "node:fs";
 
 import { ABSENT, failed, ok, type Outcome } from "./outcome";
+import { debug } from "./logger";
+
+// [LAW:single-enforcer] The one per-render freshness probe: a SYNC single-file
+// stat's mtimeMs (0 when the file is absent or unreadable). Sync by design — the
+// mtime gate must resolve before deciding whether to read, and a sync stat
+// consumes no gate slot (the async `readAppended`/`readFile` bulk reads are what
+// the limiter bounds). Both the usage store and the metrics provider key their
+// incremental fold off this one helper so the ENOENT→0 policy lives in one place.
+export function statMtimeMs(filePath: string | undefined): number {
+  if (!filePath) return 0;
+  try {
+    return statSync(filePath).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
 
 // [LAW:single-enforcer] One owner of the transcript-scanning in-flight-I/O
 // budget. Every readdir/stat/readFile over the ~/.claude/projects tree passes
@@ -120,6 +137,97 @@ export const stat = gated(fsStat);
 // (permissions, I/O) is a real read failure — `failed`, carrying its reason
 // to whichever boundary owns the log effect. Folding both into one null made
 // a broken transcript indistinguishable from a missing one.
+// [LAW:single-enforcer] The forward complement of readTail, through the SAME
+// gate: read the bytes of an append-only file from `priorOffset` to EOF (the
+// whole file when `priorOffset` is undefined). One open→stat→read→close per
+// gate slot, exactly like readTail. A transcript scanner that maintains a byte
+// cursor to re-read only what was appended MUST use this, not raw node:fs, or it
+// reintroduces the unbounded-fs state the gate forbids.
+//
+// [LAW:one-source-of-truth] `reset` is the single signal that the file shrank
+// below the caller's cursor — a truncation or /compact rewrite — so the caller
+// discards its prior fold for this file and re-folds from the returned bytes
+// (which then start at offset 0). Append-only monotonicity makes every other
+// case a pure suffix read: `start..size` is exactly what's new.
+//
+// [LAW:no-silent-failure] ENOENT (fresh session, no transcript yet) is `absent`;
+// any other error is `failed`, carrying its reason to the boundary that logs.
+export async function readAppended(
+  path: string,
+  prior: { offset: number; ino: number } | undefined,
+): Promise<
+  Outcome<{
+    buf: Buffer;
+    start: number;
+    size: number;
+    mtimeMs: number;
+    ino: number;
+    reset: boolean;
+  }>
+> {
+  return gate.run(async () => {
+    let fh: FileHandle | null = null;
+    try {
+      fh = await fsOpen(path, "r");
+      const { size, mtimeMs, ino } = await fh.stat();
+      // [LAW:one-source-of-truth] The prior fold is a valid PREFIX of this file
+      // only while the file stays append-only. Two independent signals break
+      // that: the inode changed (a rename-based /compact or log rotation swapped
+      // the file under the path — the realistic rewrite mechanism), or the file
+      // shrank below our cursor (an in-place truncate). Either ⇒ re-read from 0;
+      // the suffix-only read would otherwise splice new bytes onto a fold of a
+      // file that no longer exists. (A cursor-only size check missed a rewrite
+      // that grew back to ≥ the cursor.)
+      const reset =
+        prior !== undefined && (ino !== prior.ino || size < prior.offset);
+      const start = reset || prior === undefined ? 0 : prior.offset;
+      if (start >= size) {
+        return ok({ buf: Buffer.alloc(0), start, size, mtimeMs, ino, reset });
+      }
+      const buf = Buffer.alloc(size - start);
+      // [LAW:no-silent-fallbacks] A single read may return short — parsing a
+      // zero-padded tail would fabricate entries. Loop until the window fills or
+      // EOF; on a short final read (the file shrank under us) return only the
+      // bytes actually read, never the zero padding.
+      let off = 0;
+      while (off < buf.length) {
+        const { bytesRead } = await fh.read(
+          buf,
+          off,
+          buf.length - off,
+          start + off,
+        );
+        if (bytesRead === 0) break;
+        off += bytesRead;
+      }
+      return ok({
+        buf: off === buf.length ? buf : buf.subarray(0, off),
+        start,
+        size,
+        mtimeMs,
+        ino,
+        reset,
+      });
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code === "ENOENT") return ABSENT;
+      return failed(
+        `readAppended ${path}: ${e instanceof Error ? e.message : String(e)}`,
+      );
+    } finally {
+      // [LAW:no-silent-failure] A close() rejection must NOT override the typed
+      // Outcome the try returned — callers await this and read `.kind`, so a raw
+      // rejection would escape every failed-guard. A failed close after a good
+      // read doesn't invalidate the read, but it can signal a real fs problem
+      // (ENOSPC on fsync), so log it at debug rather than swallowing it blind.
+      await fh?.close().catch((e: unknown) => {
+        debug(
+          `transcript-fs: close failed: ${e instanceof Error ? e.message : String(e)}`,
+        );
+      });
+    }
+  });
+}
+
 export async function readTail(
   path: string,
   maxBytes: number,
@@ -156,7 +264,16 @@ export async function readTail(
         `readTail ${path}: ${e instanceof Error ? e.message : String(e)}`,
       );
     } finally {
-      await fh?.close();
+      // [LAW:no-silent-failure] A close() rejection must NOT override the typed
+      // Outcome the try returned — callers await this and read `.kind`, so a raw
+      // rejection would escape every failed-guard. A failed close after a good
+      // read doesn't invalidate the read, but it can signal a real fs problem
+      // (ENOSPC on fsync), so log it at debug rather than swallowing it blind.
+      await fh?.close().catch((e: unknown) => {
+        debug(
+          `transcript-fs: close failed: ${e instanceof Error ? e.message : String(e)}`,
+        );
+      });
     }
   });
 }