fapony 0.1.0

package/src/session/opencode.ts

@@ -0,0 +1,167 @@
+// src/session/opencode.ts — OpenCode passive usage reader
+//
+// Reads ~/.local/share/opencode/opencode.db (SQLite).
+// Schema: session + project + part tables.
+
+import { Database } from "bun:sqlite";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  beginSnapshot,
+  buildWhereClause,
+  endSnapshot,
+  readDetailFromDb,
+  readTimingFromDb,
+} from "./helpers.js";
+import {
+  EMPTY_RESULT,
+  type ModelBreakdown,
+  type PassiveUsageResult,
+} from "./types.js";
+
+const DB_PATH = join(homedir(), ".local", "share", "opencode", "opencode.db");
+
+function resolveDbPath(optDbPath?: string): string {
+  return optDbPath ?? process.env.FAPONY_OPENCODE_DB ?? DB_PATH;
+}
+
+/**
+ * Read passive usage from OpenCode's session database.
+ * Returns EMPTY_RESULT when the DB file doesn't exist.
+ */
+export function readPassiveUsage(
+  worktree?: string,
+  since?: number,
+  until?: number,
+  detailOrOpts?:
+    | boolean
+    | { detail?: boolean; dbPath?: string; full?: boolean },
+): PassiveUsageResult {
+  const detail =
+    typeof detailOrOpts === "boolean" ? detailOrOpts : !!detailOrOpts?.detail;
+  const full = typeof detailOrOpts === "object" && !!detailOrOpts?.full;
+  const dbPath =
+    typeof detailOrOpts === "object"
+      ? resolveDbPath(detailOrOpts.dbPath)
+      : resolveDbPath();
+  if (!existsSync(dbPath)) {
+    return EMPTY_RESULT;
+  }
+
+  let db: Database | null = null;
+  let snapshot = false;
+  try {
+    db = new Database(dbPath, { readonly: true });
+    db.run("PRAGMA query_only = ON");
+    snapshot = beginSnapshot(db);
+
+    // OpenCode's `project.worktree` is the repo ROOT, so a git worktree under it
+    // (…/fapony/wt-fapony) never matches and every per-project query came back
+    // empty. `session.directory` is the actual cwd — the same value runs.worktree
+    // holds. ponytail: filter on the session row, keep the join for by-model.
+    const filter = buildWhereClause(
+      "s.directory",
+      worktree,
+      since,
+      until,
+      "WHERE",
+    );
+
+    const totalsRow = db
+      .prepare(
+        `
+        SELECT
+          COALESCE(SUM(s.tokens_input), 0) AS total_tokens_input,
+          COALESCE(SUM(s.tokens_output), 0) AS total_tokens_output,
+          COALESCE(SUM(s.tokens_reasoning), 0) AS total_tokens_reasoning,
+          COALESCE(SUM(s.tokens_cache_read), 0) AS total_tokens_cache_read,
+          COALESCE(SUM(s.tokens_cache_write), 0) AS total_tokens_cache_write,
+          COALESCE(SUM(s.cost), 0) AS total_cost,
+          COUNT(*) AS session_count
+        FROM session s
+        JOIN project p ON s.project_id = p.id
+        ${filter.clause}
+      `,
+      )
+      .get(...filter.params) as {
+      total_tokens_input: number;
+      total_tokens_output: number;
+      total_tokens_reasoning: number;
+      total_tokens_cache_read: number;
+      total_tokens_cache_write: number;
+      total_cost: number;
+      session_count: number;
+    };
+
+    if (!totalsRow || totalsRow.session_count === 0) {
+      return EMPTY_RESULT;
+    }
+
+    const byModelRows = db
+      .prepare(
+        `
+        SELECT
+          CASE WHEN json_valid(s.model) THEN COALESCE(json_extract(s.model, '$.providerID'), '') ELSE '' END AS provider,
+          CASE WHEN json_valid(s.model) THEN COALESCE(json_extract(s.model, '$.id'), s.model) ELSE s.model END AS model,
+          COUNT(*) AS session_count,
+          SUM(s.tokens_input) AS tokens_input,
+          SUM(s.tokens_output) AS tokens_output,
+          SUM(s.tokens_reasoning) AS tokens_reasoning,
+          SUM(s.tokens_cache_read) AS tokens_cache_read,
+          SUM(s.tokens_cache_write) AS tokens_cache_write,
+          SUM(s.cost) AS cost
+        FROM session s
+        JOIN project p ON s.project_id = p.id
+        ${filter.clause}
+        GROUP BY CASE WHEN json_valid(s.model) THEN COALESCE(json_extract(s.model, '$.providerID'), '') ELSE '' END,
+                 CASE WHEN json_valid(s.model) THEN COALESCE(json_extract(s.model, '$.id'), s.model) ELSE s.model END
+        ORDER BY (tokens_input + tokens_output + tokens_reasoning + tokens_cache_read + tokens_cache_write) DESC
+      `,
+      )
+      .all(...filter.params) as ModelBreakdown[];
+
+    const result: PassiveUsageResult = {
+      total_tokens_input: totalsRow.total_tokens_input,
+      total_tokens_output: totalsRow.total_tokens_output,
+      total_tokens_reasoning: totalsRow.total_tokens_reasoning,
+      total_tokens_cache_read: totalsRow.total_tokens_cache_read,
+      total_tokens_cache_write: totalsRow.total_tokens_cache_write,
+      total_cost: totalsRow.total_cost,
+      session_count: totalsRow.session_count,
+      by_model: byModelRows,
+    };
+
+    if (detail) {
+      result.detail = readDetailFromDb(
+        db,
+        "s.directory",
+        "s.model",
+        worktree,
+        since,
+        until,
+      );
+      try {
+        result.detail.timing = readTimingFromDb(db, "s.directory", {
+          worktree,
+          since,
+          until,
+          limit: full ? false : undefined,
+        });
+      } catch {
+        // Timing is additive signal — a part-table shape mismatch must
+        // never break totals/detail that already succeeded. Say so instead of
+        // letting a silent null read as "this client records no timing".
+        result.detail.timing = null;
+        result.error = "opencode_timing_read_failed";
+      }
+    }
+
+    return result;
+  } catch {
+    return { ...EMPTY_RESULT, error: "opencode_read_failed" };
+  } finally {
+    if (db) endSnapshot(db, snapshot);
+    db?.close();
+  }
+}

package/src/session/registry.ts

@@ -0,0 +1,45 @@
+// src/session/registry.ts — single source of truth for supported clients.
+//
+// Adding a client: write its reader (src/session/<name>.ts, same
+// PassiveUsageResult shape as an existing one — SQLite or JSONL, whatever the
+// client actually stores), then add one entry below. usage-scan and
+// fapony_usage both iterate this list; neither needs any other change.
+//
+// This does not remove the real work of a new client (reverse-engineering
+// its storage format) — it only removes the "wire it into 2 call sites"
+// step that used to come after.
+
+import { readClaudeCodeUsage } from "./claude-code.js";
+import { readCodexUsage } from "./codex.js";
+import { readPassiveUsage } from "./opencode.js";
+import type { PassiveUsageReader } from "./types.js";
+import { readZcodeUsage } from "./zcode.js";
+
+export interface ClientAdapter {
+  /** cache `client` field and fapony_usage JSON key. */
+  key: string;
+  /** usage-scan progress label — defaults to `key`. */
+  scanLabel?: string;
+  /** fapony_usage text-report section label — defaults to `key`. */
+  reportLabel?: string;
+  /** The one client whose totals lead the report as the unlabeled top-level summary. */
+  primary?: boolean;
+  read: PassiveUsageReader;
+}
+
+export const CLIENTS: ClientAdapter[] = [
+  {
+    key: "opencode",
+    primary: true,
+    read: (worktree, since, until, detail, full) =>
+      readPassiveUsage(worktree, since, until, { detail, full }),
+  },
+  { key: "zcode", read: readZcodeUsage },
+  {
+    key: "claude_code",
+    scanLabel: "claude-code",
+    reportLabel: "claude code",
+    read: readClaudeCodeUsage,
+  },
+  { key: "codex", read: readCodexUsage },
+];

package/src/session/types.ts

@@ -0,0 +1,128 @@
+// src/session/types.ts — shared types + constants for session usage providers
+
+export interface ModelBreakdown {
+  provider: string;
+  model: string;
+  session_count: number;
+  tokens_input: number;
+  tokens_output: number;
+  tokens_reasoning: number;
+  tokens_cache_read: number;
+  tokens_cache_write: number;
+  cost: number;
+}
+
+export interface SessionDetail {
+  session_id: string;
+  model: string;
+  steps: number;
+  tools: Record<string, number>;
+}
+
+export interface ToolLatencyStat {
+  count: number;
+  avgMs: number;
+}
+
+export interface StepTimingSummary {
+  /** step-finish row count (mirrors UsageDetail.steps for SQLite providers). */
+  steps: number;
+  /** Mean per-part duration from embedded data.time (row-timestamp fallback when absent). */
+  avgStepMs: number | null;
+  /** How many durations were actually measured (vs. steps with no time signal). */
+  stepSamples: number;
+  /** Mean per-step tokens — averages only, never summed (sums overlap). */
+  avgStepInput: number | null;
+  avgStepOutput: number | null;
+  avgStepCost: number | null;
+  /** Mean tool latency grouped by tool name (from data.state.time). */
+  toolLatencyMsByType: Record<string, ToolLatencyStat>;
+  note: string;
+}
+
+export interface StaleReadFile {
+  file: string;
+  /** How many distinct sessions read this file (diversity, not just count). */
+  sessions: number;
+  /** Total Read calls across those sessions. */
+  reads: number;
+}
+
+export interface UsageDetail {
+  /** Global tool-call counts across the filtered sessions (activity signal, not quality). */
+  tool_breakdown: Record<string, number>;
+  /** Context bytes per tool — size of tool_result content blocks. */
+  bytes_by_tool?: Record<string, number>;
+  /** Total step-finish parts across the filtered sessions. */
+  steps: number;
+  /** Per-session breakdown (SQL-aggregated, never raw part rows). */
+  by_session: SessionDetail[];
+  /**
+   * Files read across 2+ sessions in this window and never edited/written —
+   * candidates for pasting into CLAUDE.md instead of re-reading every
+   * session. Top 20 by session count. Needs a wide `since` window (many
+   * sessions) before the pattern means anything — noise below that.
+   */
+  stale_reads?: StaleReadFile[];
+  /**
+   * Step-token sums are NOT reported: per-step tokens overlap (each step
+   * carries the full context window), so SUM(step tokens) >> session tokens.
+   * Verified on real data — see testSessionDetailStepTokensNotSummed.
+   */
+  note: string;
+  /** Per-step timing/token/latency signal — present only when detail:true was requested. */
+  timing?: StepTimingSummary | null;
+}
+
+export interface PassiveUsageResult {
+  total_tokens_input: number;
+  total_tokens_output: number;
+  total_tokens_reasoning: number;
+  total_tokens_cache_read: number;
+  total_tokens_cache_write: number;
+  total_cost: number;
+  session_count: number;
+  by_model: ModelBreakdown[];
+  /** Present only when detail:true was requested (additive, default absent). */
+  detail?: UsageDetail | null;
+  /** ZCode sessions, when available. Absent when ZCode DB not found. */
+  zcode?: PassiveUsageResult | null;
+  /** Claude Code sessions, when available. Absent when projects dir not found. */
+  claude_code?: PassiveUsageResult | null;
+  /**
+   * Why this read came back short, when it did. Absent on success.
+   *
+   * Zeros with no `error` mean "no sessions matched"; zeros WITH an error mean
+   * "could not read the client's log" — most often schema drift after the
+   * client updated. The two used to be indistinguishable: a renamed column
+   * made the query throw, the catch-all swallowed it, and the numbers just
+   * quietly went missing.
+   */
+  error?: string;
+}
+
+export const EMPTY_RESULT: PassiveUsageResult = {
+  total_tokens_input: 0,
+  total_tokens_output: 0,
+  total_tokens_reasoning: 0,
+  total_tokens_cache_read: 0,
+  total_tokens_cache_write: 0,
+  total_cost: 0,
+  session_count: 0,
+  by_model: [],
+};
+
+/** Common shape every client reader implements — see registry.ts. */
+export type PassiveUsageReader = (
+  worktree?: string,
+  since?: number,
+  until?: number,
+  detail?: boolean,
+  full?: boolean,
+) => PassiveUsageResult;
+
+export const STEP_TOKENS_NOTE =
+  "step tokens overlap (per-step context window) — SUM(step tokens) != session tokens; steps is a count only";
+
+export const TIMING_NOTE =
+  "timing from embedded part fields only (data.time/data.state.time/step-finish tokens) with row-timestamp fallback; averages, never raw I/O";

package/src/session/zcode.ts

@@ -0,0 +1,151 @@
+// src/session/zcode.ts — ZCode passive usage reader
+//
+// Reads ~/.zcode/cli/db/db.sqlite (SQLite).
+// Schema: session + model_usage + part tables (different from OpenCode).
+// Worktree lives on session.directory, not a separate project table.
+
+import { Database } from "bun:sqlite";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  beginSnapshot,
+  buildWhereClause,
+  endSnapshot,
+  readDetailFromDb,
+  readTimingFromDb,
+} from "./helpers.js";
+import {
+  EMPTY_RESULT,
+  type ModelBreakdown,
+  type PassiveUsageResult,
+} from "./types.js";
+
+const ZCODE_DB_PATH = join(homedir(), ".zcode", "cli", "db", "db.sqlite");
+
+function resolveZcodeDbPath(optDbPath?: string): string {
+  return optDbPath ?? process.env.FAPONY_ZCODE_DB ?? ZCODE_DB_PATH;
+}
+
+/**
+ * Read passive usage from ZCode's own session DB.
+ * Returns EMPTY_RESULT when the DB file doesn't exist (ZCode never started).
+ */
+export function readZcodeUsage(
+  worktree?: string,
+  since?: number,
+  until?: number,
+  detail?: boolean,
+  full?: boolean,
+): PassiveUsageResult {
+  const dbPath = resolveZcodeDbPath();
+  if (!existsSync(dbPath)) return EMPTY_RESULT;
+
+  let db: Database | null = null;
+  let snapshot = false;
+  try {
+    db = new Database(dbPath, { readonly: true });
+    db.run("PRAGMA query_only = ON");
+    snapshot = beginSnapshot(db);
+
+    const filter = buildWhereClause("s.directory", worktree, since, until);
+
+    const totalsRow = db
+      .prepare(
+        `
+        SELECT
+          COALESCE(SUM(mu.input_tokens), 0) AS total_tokens_input,
+          COALESCE(SUM(mu.output_tokens), 0) AS total_tokens_output,
+          COALESCE(SUM(mu.reasoning_tokens), 0) AS total_tokens_reasoning,
+          COALESCE(SUM(mu.cache_read_input_tokens), 0) AS total_tokens_cache_read,
+          COALESCE(SUM(mu.cache_creation_input_tokens), 0) AS total_tokens_cache_write,
+          0 AS total_cost,
+          COUNT(DISTINCT s.id) AS session_count
+        FROM model_usage mu
+        JOIN session s ON mu.session_id = s.id
+        ${filter.clause}
+      `,
+      )
+      .get(...filter.params) as {
+      total_tokens_input: number;
+      total_tokens_output: number;
+      total_tokens_reasoning: number;
+      total_tokens_cache_read: number;
+      total_tokens_cache_write: number;
+      total_cost: number;
+      session_count: number;
+    };
+
+    if (!totalsRow || totalsRow.session_count === 0) return EMPTY_RESULT;
+
+    const byModelRows = db
+      .prepare(
+        `
+        SELECT
+          '' AS provider,
+          mu.model_id AS model,
+          COUNT(DISTINCT s.id) AS session_count,
+          SUM(mu.input_tokens) AS tokens_input,
+          SUM(mu.output_tokens) AS tokens_output,
+          SUM(mu.reasoning_tokens) AS tokens_reasoning,
+          SUM(mu.cache_read_input_tokens) AS tokens_cache_read,
+          SUM(mu.cache_creation_input_tokens) AS tokens_cache_write,
+          0 AS cost
+        FROM model_usage mu
+        JOIN session s ON mu.session_id = s.id
+        ${filter.clause}
+        GROUP BY mu.model_id
+        ORDER BY SUM(mu.computed_total_tokens) DESC
+      `,
+      )
+      .all(...filter.params) as ModelBreakdown[];
+
+    const result: PassiveUsageResult = {
+      total_tokens_input: totalsRow.total_tokens_input,
+      total_tokens_output: totalsRow.total_tokens_output,
+      total_tokens_reasoning: totalsRow.total_tokens_reasoning,
+      total_tokens_cache_read: totalsRow.total_tokens_cache_read,
+      total_tokens_cache_write: 0, // ZCode doesn't separately track cache write
+      total_cost: totalsRow.total_cost,
+      session_count: totalsRow.session_count,
+      by_model: byModelRows,
+    };
+
+    if (detail) {
+      result.detail = readDetailFromDb(
+        db,
+        "s.directory",
+        "s.directory",
+        worktree,
+        since,
+        until,
+      );
+      // ZCode part table has no time_updated column (spec §1: verify before
+      // coding) — embedded data.time only, row fallback disabled.
+      // ASSUMPTION: ZCode part.data.type uses the same vocabulary as OpenCode
+      // ("tool", "step-finish", "reasoning"). If ZCode uses different type
+      // strings, timing silently returns empty (graceful degradation, no error).
+      try {
+        result.detail.timing = readTimingFromDb(db, "s.directory", {
+          worktree,
+          since,
+          until,
+          hasTimeUpdated: false,
+          limit: full ? false : undefined,
+        });
+      } catch {
+        // Timing is additive signal — never break totals/detail. The code
+        // distinguishes "ZCode records no timing" from "we could not read it".
+        result.detail.timing = null;
+        result.error = "zcode_timing_read_failed";
+      }
+    }
+
+    return result;
+  } catch {
+    return { ...EMPTY_RESULT, error: "zcode_read_failed" };
+  } finally {
+    if (db) endSnapshot(db, snapshot);
+    db?.close();
+  }
+}