kankaku-pi 1.0.0

package/src/adapters/report.ts

@@ -0,0 +1,335 @@
+import { buildTasks, uncertainRecords } from "../domain/task-view.ts";
+import type { SessionView, TaskView } from "../domain/task-view.ts";
+import { localDay } from "../domain/day.ts";
+import { cacheHitRatio, finiteOrZero } from "../domain/work-record.ts";
+import type { WorkRecord, WorkRole } from "../domain/work-record.ts";
+
+export { localDay } from "../domain/day.ts";
+
+export interface RoleTotals {
+  workMs: number;
+  waitingMs: number;
+  wallMs: number;
+  count: number;
+  /** Estimated cost in USD, as priced by pi's model table. */
+  cost: number;
+  /** Prompt input tokens, summed across every record of this role. */
+  input: number;
+  /** Prompt-cache read tokens, summed across every record of this role. */
+  cacheRead: number;
+  /** Prompt-cache write tokens, summed across every record of this role. */
+  cacheWrite: number;
+  /** Per-tag total milliseconds summed across every record of this role. */
+  segments: Record<string, number>;
+}
+
+export interface TaskTotals {
+  count: number;
+  wallMs: number;
+  workMs: number;
+  /** Estimated cost in USD, orchestrator and subagents combined. */
+  cost: number;
+  /** Prompt input tokens, orchestrator and subagents combined. */
+  input: number;
+  /** Prompt-cache read tokens, orchestrator and subagents combined. */
+  cacheRead: number;
+  /** Prompt-cache write tokens, orchestrator and subagents combined. */
+  cacheWrite: number;
+  /** Per-tag total milliseconds summed across every task (orchestrator and subagents). */
+  segments: Record<string, number>;
+}
+
+export type Summary = Record<WorkRole, RoleTotals> & { tasks: TaskTotals };
+
+export interface SummarizeOptions {
+  /** Local day in `YYYY-MM-DD` format. Defaults to today when `all` is not set. */
+  day?: string;
+  /** Include every record regardless of day. */
+  all?: boolean;
+}
+
+const ROLES: WorkRole[] = ["orchestrator", "subagent"];
+
+function emptyTotals(): RoleTotals {
+  return { workMs: 0, waitingMs: 0, wallMs: 0, count: 0, cost: 0, input: 0, cacheRead: 0, cacheWrite: 0, segments: {} };
+}
+
+/**
+ * Add per-tag milliseconds from `segments` (missing on older records) into
+ * `into`, a `Map` rather than a plain object so a tag from a hand-edited
+ * worklog line named `__proto__` or `constructor` accumulates as a normal
+ * entry instead of silently reading (and arithmetically corrupting) an
+ * inherited `Object.prototype` value.
+ */
+function addSegments(into: Map<string, number>, segments: Record<string, number> | undefined): void {
+  for (const [tag, ms] of Object.entries(segments ?? {})) {
+    into.set(tag, (into.get(tag) ?? 0) + ms);
+  }
+}
+
+/**
+ * Aggregate work records by role, restricted to one local day unless `all`
+ * is set. Also computes a `tasks` segment (union-based `wallMs`/`workMs`
+ * over one orchestrator run and its subagents) for tasks whose `startedAt`
+ * falls on the same day.
+ */
+export function summarize(records: WorkRecord[], options: SummarizeOptions): Summary {
+  const targetDay = options.all ? undefined : (options.day ?? localDay(new Date().toISOString()));
+
+  const summary: Summary = {
+    orchestrator: emptyTotals(),
+    subagent: emptyTotals(),
+    tasks: { count: 0, wallMs: 0, workMs: 0, cost: 0, input: 0, cacheRead: 0, cacheWrite: 0, segments: {} },
+  };
+  // Accumulated in Maps (see `addSegments`) and only converted to the
+  // returned plain objects at the very end, via `Object.fromEntries`.
+  const segmentsByRole: Record<WorkRole, Map<string, number>> = { orchestrator: new Map(), subagent: new Map() };
+  const taskSegments = new Map<string, number>();
+
+  for (const record of records) {
+    if (targetDay !== undefined && localDay(record.startedAt) !== targetDay) continue;
+    const totals = summary[record.role];
+    totals.workMs += record.workMs;
+    totals.waitingMs += record.waitingMs;
+    totals.wallMs += record.wallMs;
+    totals.count += 1;
+    totals.cost += finiteOrZero(record.usage.cost);
+    totals.input += finiteOrZero(record.usage.input);
+    totals.cacheRead += finiteOrZero(record.usage.cacheRead);
+    totals.cacheWrite += finiteOrZero(record.usage.cacheWrite);
+    addSegments(segmentsByRole[record.role], record.segments);
+  }
+
+  const tasks = buildTasks(records).filter((task) => targetDay === undefined || localDay(task.startedAt) === targetDay);
+  for (const task of tasks) {
+    summary.tasks.count += 1;
+    summary.tasks.wallMs += task.wallMs;
+    summary.tasks.workMs += task.workMs;
+    summary.tasks.cost += task.usage.cost;
+    summary.tasks.input += finiteOrZero(task.usage.input);
+    summary.tasks.cacheRead += finiteOrZero(task.usage.cacheRead);
+    summary.tasks.cacheWrite += finiteOrZero(task.usage.cacheWrite);
+    addSegments(taskSegments, task.segments);
+  }
+
+  summary.orchestrator.segments = Object.fromEntries(segmentsByRole.orchestrator);
+  summary.subagent.segments = Object.fromEntries(segmentsByRole.subagent);
+  summary.tasks.segments = Object.fromEntries(taskSegments);
+
+  return summary;
+}
+
+/**
+ * Count of `uncertain` records (ADR 0022) within the same day scope
+ * `summarize` uses, so the `/kankaku` report can surface a one-line hint
+ * when some records are silently excluded from the task count
+ * (SUBAGENT-REQ-017): an undercount must never be silent.
+ */
+export function countUncertain(records: WorkRecord[], options: SummarizeOptions): number {
+  const targetDay = options.all ? undefined : (options.day ?? localDay(new Date().toISOString()));
+  return uncertainRecords(records).filter((record) => targetDay === undefined || localDay(record.startedAt) === targetDay).length;
+}
+
+function formatMinutes(ms: number): string {
+  const totalSeconds = Math.round(ms / 1000);
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return `${minutes}m${String(seconds).padStart(2, "0")}s`;
+}
+
+/** Estimated USD cost with two decimals, e.g. `$1.23`. */
+function formatCost(cost: number): string {
+  return `$${cost.toFixed(2)}`;
+}
+
+function formatTime(iso: string): string {
+  const date = new Date(iso);
+  const hours = String(date.getHours()).padStart(2, "0");
+  const minutes = String(date.getMinutes()).padStart(2, "0");
+  return `${hours}:${minutes}`;
+}
+
+/** Render `cache hit NN%` (integer percent) for a usage totals triple, or `undefined` when the ratio is undefined (nothing recorded). */
+function formatCacheHit(usage: { input: number; cacheRead: number; cacheWrite: number }): string | undefined {
+  const ratio = cacheHitRatio(usage);
+  return ratio === undefined ? undefined : `cache hit ${Math.round(ratio * 100)}%`;
+}
+
+/** Render non-zero segment tags as `tag Xm00s` pairs, sorted alphabetically, joined by `, `. Undefined when none are non-zero. */
+function formatSegmentTags(segments: Record<string, number>): string | undefined {
+  const tags = Object.keys(segments)
+    .filter((tag) => segments[tag]! > 0)
+    .sort();
+  if (tags.length === 0) return undefined;
+  return tags.map((tag) => `${tag} ${formatMinutes(segments[tag]!)}`).join(", ");
+}
+
+/** Render a short, human-readable summary for the `/kankaku` command. */
+export function formatReport(summary: Summary): string {
+  const lines = ROLES.map((role) => {
+    const totals = summary[role];
+    const cacheHit = formatCacheHit(totals);
+    const cacheHitPart = cacheHit !== undefined ? `, ${cacheHit}` : "";
+    return `${role}: work ${formatMinutes(totals.workMs)}, waiting ${formatMinutes(totals.waitingMs)}, ${totals.count} record(s), ${formatCost(totals.cost)}${cacheHitPart}`;
+  });
+  const tasksCacheHit = formatCacheHit(summary.tasks);
+  const tasksCacheHitPart = tasksCacheHit !== undefined ? `, ${tasksCacheHit}` : "";
+  lines.push(
+    `tasks: ${summary.tasks.count}, wall ${formatMinutes(summary.tasks.wallMs)}, work ${formatMinutes(summary.tasks.workMs)}, ${formatCost(summary.tasks.cost)}${tasksCacheHitPart}`,
+  );
+  const segmentTags = formatSegmentTags(summary.tasks.segments);
+  if (segmentTags !== undefined) {
+    lines.push(`segments: ${segmentTags}`);
+  }
+  return lines.join(" | ");
+}
+
+/** Maximum visible width of a task prompt before it is truncated with an ellipsis marker. */
+const PROMPT_DISPLAY_LIMIT = 60;
+
+/** Truncate `text` to `limit` visible characters, appending `…` (counted within the limit) when it was cut. */
+function truncateWithEllipsis(text: string, limit: number): string {
+  return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+}
+
+/** Render one line per task: time, client (when present), union-based wall/work, cost, non-zero segment tags, subagent count, and a truncated prompt (`…` marks a cut). */
+export function formatTasks(tasks: TaskView[]): string {
+  if (tasks.length === 0) return "no tasks";
+  return tasks
+    .map((task) => {
+      const prompt = truncateWithEllipsis(task.prompt, PROMPT_DISPLAY_LIMIT);
+      const segmentTags = formatSegmentTags(task.segments);
+      const segmentPart = segmentTags !== undefined ? `  ${segmentTags}` : "";
+      const clientPart = task.client !== undefined ? `  client:${task.client}` : "";
+      const cacheHit = formatCacheHit(task.usage);
+      const cacheHitPart = cacheHit !== undefined ? `  ${cacheHit}` : "";
+      return `${formatTime(task.startedAt)}${clientPart}  wall ${formatMinutes(task.wallMs)}  work ${formatMinutes(task.workMs)}  ${formatCost(task.usage.cost)}${cacheHitPart}${segmentPart}  subagents ${task.subagents.length}  ${prompt}`;
+    })
+    .join("\n");
+}
+
+export interface ClientTotals {
+  wallMs: number;
+  waitingMs: number;
+  workMs: number;
+  /** Estimated cost in USD, summed across this client's tasks. */
+  cost: number;
+  /** Prompt input tokens, summed across this client's tasks. */
+  input: number;
+  /** Prompt-cache read tokens, summed across this client's tasks. */
+  cacheRead: number;
+  /** Prompt-cache write tokens, summed across this client's tasks. */
+  cacheWrite: number;
+  count: number;
+}
+
+/** Client name under which tasks without a resolved client are grouped. */
+const NO_CLIENT = "(none)";
+
+/**
+ * Aggregate tasks by billing client (see `domain/client-label.ts`), summing
+ * work/waiting/wall time, cost, and task count. Tasks without a `client`
+ * are grouped under `"(none)"`. Returned as a `Map` rather than a plain
+ * object so an attacker-controlled client name can never repoint a
+ * prototype property.
+ */
+export function summarizeByClient(tasks: TaskView[]): Map<string, ClientTotals> {
+  const totals = new Map<string, ClientTotals>();
+  for (const task of tasks) {
+    const key = task.client ?? NO_CLIENT;
+    const entry = totals.get(key) ?? { wallMs: 0, waitingMs: 0, workMs: 0, cost: 0, input: 0, cacheRead: 0, cacheWrite: 0, count: 0 };
+    entry.wallMs += task.wallMs;
+    entry.waitingMs += task.waitingMs;
+    entry.workMs += task.workMs;
+    entry.cost += finiteOrZero(task.usage.cost);
+    entry.input += finiteOrZero(task.usage.input);
+    entry.cacheRead += finiteOrZero(task.usage.cacheRead);
+    entry.cacheWrite += finiteOrZero(task.usage.cacheWrite);
+    entry.count += 1;
+    totals.set(key, entry);
+  }
+  return totals;
+}
+
+export interface ProjectTotals {
+  /** Display name: the project's `projectName`, or `"(no project)"` for the ungrouped bucket. */
+  name: string;
+  wallMs: number;
+  waitingMs: number;
+  workMs: number;
+  /** Estimated cost in USD, summed across this project's tasks. */
+  cost: number;
+  /** Prompt input tokens, summed across this project's tasks. */
+  input: number;
+  /** Prompt-cache read tokens, summed across this project's tasks. */
+  cacheRead: number;
+  /** Prompt-cache write tokens, summed across this project's tasks. */
+  cacheWrite: number;
+  count: number;
+}
+
+/** Key (and display name) under which tasks without a resolved project are grouped. */
+const NO_PROJECT = "(no project)";
+
+/**
+ * Aggregate tasks by hub project (see `domain/work-target.ts`), keyed by
+ * `projectId` (so two projects that happen to share a display name are
+ * never merged) with the name denormalised alongside for display. Tasks
+ * without a `projectId` are grouped under `"(no project)"`.
+ */
+export function summarizeByProject(tasks: TaskView[]): Map<string, ProjectTotals> {
+  const totals = new Map<string, ProjectTotals>();
+  for (const task of tasks) {
+    const key = task.projectId ?? NO_PROJECT;
+    const name = task.projectId !== undefined ? (task.projectName ?? task.projectId) : NO_PROJECT;
+    const entry = totals.get(key) ?? { name, wallMs: 0, waitingMs: 0, workMs: 0, cost: 0, input: 0, cacheRead: 0, cacheWrite: 0, count: 0 };
+    entry.wallMs += task.wallMs;
+    entry.waitingMs += task.waitingMs;
+    entry.workMs += task.workMs;
+    entry.cost += finiteOrZero(task.usage.cost);
+    entry.input += finiteOrZero(task.usage.input);
+    entry.cacheRead += finiteOrZero(task.usage.cacheRead);
+    entry.cacheWrite += finiteOrZero(task.usage.cacheWrite);
+    entry.count += 1;
+    totals.set(key, entry);
+  }
+  return totals;
+}
+
+/** Render one line per project, sorted alphabetically by display name, with work/waiting/wall time, cost, and task count. */
+export function formatProjects(totals: Map<string, ProjectTotals>): string {
+  if (totals.size === 0) return "no projects";
+  return Array.from(totals.values())
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((t) => {
+      const cacheHit = formatCacheHit(t);
+      const cacheHitPart = cacheHit !== undefined ? `  ${cacheHit}` : "";
+      return `${t.name}  work ${formatMinutes(t.workMs)}  waiting ${formatMinutes(t.waitingMs)}  wall ${formatMinutes(t.wallMs)}  ${formatCost(t.cost)}${cacheHitPart}  tasks ${t.count}`;
+    })
+    .join("\n");
+}
+
+/** Render one line per client, sorted alphabetically, with work/waiting/wall time, cost, and task count. */
+export function formatClients(totals: Map<string, ClientTotals>): string {
+  if (totals.size === 0) return "no clients";
+  return Array.from(totals.entries())
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([client, t]) => {
+      const cacheHit = formatCacheHit(t);
+      const cacheHitPart = cacheHit !== undefined ? `  ${cacheHit}` : "";
+      return `${client}  work ${formatMinutes(t.workMs)}  waiting ${formatMinutes(t.waitingMs)}  wall ${formatMinutes(t.wallMs)}  ${formatCost(t.cost)}${cacheHitPart}  tasks ${t.count}`;
+    })
+    .join("\n");
+}
+
+/** Render one line per session: truncated id, time range, union-based wall/work, cost, non-zero segment tags, and task count. */
+export function formatSessions(sessions: SessionView[]): string {
+  if (sessions.length === 0) return "no sessions";
+  return sessions
+    .map((session) => {
+      const segmentTags = formatSegmentTags(session.segments);
+      const segmentPart = segmentTags !== undefined ? `  ${segmentTags}` : "";
+      return `${session.sessionId.slice(0, 8)}  ${formatTime(session.startedAt)}–${formatTime(session.endedAt)}  wall ${formatMinutes(session.wallMs)}  work ${formatMinutes(session.workMs)}  ${formatCost(session.usage.cost)}${segmentPart}  tasks ${session.tasks.length}`;
+    })
+    .join("\n");
+}

package/src/adapters/session-client.ts

@@ -0,0 +1,116 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { resolveClient, resolveClientSource } from "../domain/client-label.ts";
+import type { ClientSourceName, ClientSources } from "../domain/client-label.ts";
+import type { WorkRole } from "../domain/work-record.ts";
+
+/** Persisted as a `kankaku-client` custom session entry so the session-level client survives a reload. */
+export interface KankakuClientEntryData {
+  client: string | undefined;
+}
+
+export const CLIENT_ENTRY_TYPE = "kankaku-client";
+
+export interface SessionClientDeps {
+  role: WorkRole;
+  /** Default billing client for this project, from `KANKAKU_CLIENT` (config.ts). See `domain/client-label.ts`. */
+  envClient?: string;
+  /**
+   * Lazily reads the project's default billing client from
+   * `<kankaku dir>/config.json`. Injected from `extension.ts` so this
+   * adapter stays free of filesystem code.
+   */
+  resolveProjectClient?: () => string | undefined;
+}
+
+export interface SessionClient {
+  /** Restore the session-level client from the last `kankaku-client` custom entry; call on `session_start`. */
+  restore(ctx: ExtensionContext): void;
+  /** Set (or clear with `undefined`) the session client and persist it as a durable session entry. */
+  set(pi: ExtensionAPI, client: string | undefined): void;
+  /** Current client sources (session > env > project), reading the project client fresh unless `project` is given. */
+  sources(project?: string | undefined): ClientSources;
+  /** The effective client from {@link sources}, regardless of role. */
+  effectiveClient(): string | undefined;
+  /** Which source produced {@link effectiveClient}. */
+  effectiveSource(): ClientSourceName | undefined;
+  /** Role-gated client for the in-progress run (`undefined` for a subagent); caches the project client for the run. */
+  runClient(): string | undefined;
+  /** Role-gated client to show while idle, reusing the run's cached project client when still held. */
+  idleClient(): string | undefined;
+  /** Drop the per-run cached project client; call when a run settles or the session shuts down. */
+  endRun(): void;
+}
+
+/**
+ * Owns the session-level billing client override (`/kankaku client <name>`),
+ * its restore/persist round-trip through session entries, and client-source
+ * resolution for both the in-progress run and the idle status line. See
+ * README "Billing labels" and `domain/client-label.ts#resolveClient`.
+ */
+export function createSessionClient(deps: SessionClientDeps): SessionClient {
+  /** Session-level client override, set with `/kankaku client <name>` and restored on `session_start`. Highest precedence. */
+  let sessionClient: string | undefined;
+  /** Project client read once per run (first record build) so checkpoints do not hit the filesystem repeatedly. */
+  let runProjectClient: { value: string | undefined } | undefined;
+
+  function sources(project: string | undefined = deps.resolveProjectClient?.()): ClientSources {
+    return {
+      session: sessionClient,
+      env: deps.envClient,
+      project,
+    };
+  }
+
+  function runSources(): ClientSources {
+    if (!runProjectClient) {
+      runProjectClient = { value: deps.resolveProjectClient?.() };
+    }
+    return sources(runProjectClient.value);
+  }
+
+  /**
+   * Scan the session's entries for the last `kankaku-client` custom entry
+   * and restore the client it recorded (`undefined` when that entry cleared
+   * the label, or when no such entry exists yet).
+   */
+  function restore(ctx: ExtensionContext): void {
+    const entries = ctx.sessionManager.getEntries();
+    for (let i = entries.length - 1; i >= 0; i--) {
+      const entry = entries[i] as { type: string; customType?: string; data?: unknown };
+      if (entry.type === "custom" && entry.customType === CLIENT_ENTRY_TYPE) {
+        const data = entry.data as KankakuClientEntryData | undefined;
+        sessionClient = data?.client;
+        return;
+      }
+    }
+    sessionClient = undefined;
+  }
+
+  function set(pi: ExtensionAPI, client: string | undefined): void {
+    sessionClient = client;
+    pi.appendEntry<KankakuClientEntryData>(CLIENT_ENTRY_TYPE, { client });
+  }
+
+  function effectiveClient(): string | undefined {
+    return resolveClient(sources());
+  }
+
+  function effectiveSource(): ClientSourceName | undefined {
+    return resolveClientSource(sources());
+  }
+
+  function runClient(): string | undefined {
+    return deps.role === "orchestrator" ? resolveClient(runSources()) : undefined;
+  }
+
+  function idleClient(): string | undefined {
+    const idleSources = runProjectClient ? sources(runProjectClient.value) : sources();
+    return deps.role === "orchestrator" ? resolveClient(idleSources) : undefined;
+  }
+
+  function endRun(): void {
+    runProjectClient = undefined;
+  }
+
+  return { restore, set, sources, effectiveClient, effectiveSource, runClient, idleClient, endRun };
+}

package/src/adapters/session-dir.ts

@@ -0,0 +1,28 @@
+/**
+ * `SessionManager#usesDefaultSessionDir()`/`#getSessionDir()` are real
+ * methods on pi's session manager (mirrors what pi's own
+ * `formatResumeCommand` does to decide whether to print `--session-dir`),
+ * but `usesDefaultSessionDir` is not part of the `ReadonlySessionManager`
+ * type `ctx.sessionManager` is typed as — so this is a guarded duck-typed
+ * call, not a typed one: an older pi version (or any future shape change)
+ * that lacks the method degrades to "no sessionDir," never a crash.
+ * Returns the session dir only when it is genuinely non-default, exactly
+ * the condition under which pi itself would print `--session-dir`. Shared
+ * by `pi-tracker.ts` (record metadata) and `kankaku-command.ts` (the
+ * `/kankaku doctor` display) — kept as its own module so neither adapter
+ * has to import the other.
+ */
+export function readNonDefaultSessionDir(sessionManager: unknown): string | undefined {
+  const candidate = sessionManager as { usesDefaultSessionDir?: () => boolean; getSessionDir?: () => string };
+  if (typeof candidate.usesDefaultSessionDir !== "function" || typeof candidate.getSessionDir !== "function") return undefined;
+  try {
+    if (candidate.usesDefaultSessionDir()) return undefined;
+    const dir = candidate.getSessionDir();
+    // An unpersisted session (e.g. `--no-session`) can report
+    // usesDefaultSessionDir() === false with an empty getSessionDir() — not
+    // a real custom directory, so there is nothing meaningful to carry.
+    return dir ? dir : undefined;
+  } catch {
+    return undefined;
+  }
+}