kankaku 0.1.0 → 0.4.6

package/src/adapters/status-bar.ts

@@ -0,0 +1,86 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+// U+FE0F forces emoji presentation so terminals do not fall back to monochrome text glyphs.
+const CLOCK_EMOJI = "\u{1F552}️";
+const CLIENT_EMOJI = "\u{1F4BC}️";
+
+/** Footer status key; footer statuses are sorted alphabetically by key, "zz-" keeps kankaku last. */
+export const STATUS_KEY = "zz-kankaku";
+
+export function formatElapsed(ms: number, client?: string): string {
+  const totalSeconds = Math.max(0, Math.round(ms / 1000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  const elapsed = `${CLOCK_EMOJI} ${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`;
+  return client ? `${elapsed} · ${client}` : elapsed;
+}
+
+export interface StatusBarDeps {
+  /** Status line refresh interval in ms while a run is active. Defaults to 1000. */
+  intervalMs?: number;
+  /** Resolve the client label to show for the run that is starting now. */
+  resolveRunClient: () => string | undefined;
+  /** Resolve the client label to show while idle. */
+  resolveIdleClient: () => string | undefined;
+  /** Injectable for tests; defaults to the global timer functions. */
+  setInterval?: (handler: () => void, ms: number) => NodeJS.Timeout;
+  clearInterval?: (timer: NodeJS.Timeout) => void;
+  /** Injectable clock for tests; defaults to `Date.now`. */
+  now?: () => number;
+}
+
+export interface StatusBar {
+  /** Start (or, if already running, leave untouched) the elapsed-time status; a no-op without a UI. */
+  start(ctx: ExtensionContext): void;
+  /** Stop the elapsed-time status and fall back to the idle status. */
+  stop(ctx: ExtensionContext): void;
+  /** While idle, keep the billing client visible (`💼 <client>`), or clear the status when none resolves. */
+  showIdle(ctx: ExtensionContext): void;
+}
+
+/**
+ * Owns the `/kankaku` footer status: the running elapsed-time clock (with
+ * its refresh timer) while a run is active, and the idle billing-client
+ * label otherwise.
+ */
+export function createStatusBar(deps: StatusBarDeps): StatusBar {
+  const intervalMs = deps.intervalMs ?? 1000;
+  const scheduleInterval = deps.setInterval ?? setInterval;
+  const cancelInterval = deps.clearInterval ?? clearInterval;
+  const now = deps.now ?? Date.now;
+
+  let runStartedAt: number | undefined;
+  let statusTimer: NodeJS.Timeout | undefined;
+
+  function showIdle(ctx: ExtensionContext): void {
+    if (!ctx.hasUI) return;
+    const client = deps.resolveIdleClient();
+    ctx.ui.setStatus(STATUS_KEY, client ? `${CLIENT_EMOJI} ${client}` : undefined);
+  }
+
+  function start(ctx: ExtensionContext): void {
+    // Retries within the same run fire before_agent_start again; only the
+    // first one starts the timer.
+    if (runStartedAt !== undefined) return;
+    if (!ctx.hasUI) return;
+    runStartedAt = now();
+    const client = deps.resolveRunClient();
+    ctx.ui.setStatus(STATUS_KEY, formatElapsed(0, client));
+    statusTimer = scheduleInterval(() => {
+      if (runStartedAt === undefined) return;
+      ctx.ui.setStatus(STATUS_KEY, formatElapsed(now() - runStartedAt, client));
+    }, intervalMs);
+    statusTimer.unref?.();
+  }
+
+  function stop(ctx: ExtensionContext): void {
+    if (statusTimer) {
+      cancelInterval(statusTimer);
+      statusTimer = undefined;
+    }
+    runStartedAt = undefined;
+    showIdle(ctx);
+  }
+
+  return { start, stop, showIdle };
+}

package/src/config.ts

@@ -1,3 +1,5 @@
+import type { SegmentRule } from "./domain/segment-rule.ts";
+
 export interface KankakuConfig {
   /** Directory for the work log, relative to the project cwd unless absolute. */
   dir: string;
@@ -5,12 +7,68 @@ export interface KankakuConfig {
   interactiveTools: string[];
   /** Tool name used to run subagents. */
   subagentTool: string;
+  /** Rules that tag a tool execution's span under a named segment (e.g. `review`). */
+  segmentRules: SegmentRule[];
+  /** Default billing client for this project, from `KANKAKU_CLIENT`. See `domain/client-label.ts`. */
+  client?: string;
 }
 
 const DEFAULT_DIR = ".kankaku";
 const DEFAULT_INTERACTIVE_TOOLS = ["ask_user_question", "ask_user_choice"];
 const SUBAGENT_TOOL = "subagent_run";
 
+/**
+ * Default segment rule: with gentle-ai, the review-with-receipts step runs
+ * as `gentle-ai review ...` commands through the `bash` tool, so tag that
+ * span `review`.
+ */
+const DEFAULT_SEGMENT_RULES: SegmentRule[] = [{ tag: "review", tool: "bash", pattern: /\bgentle-ai review\b/ }];
+
+/** Tags allowed for a segment rule: letters, digits, `_` and `-`, 1-32 chars. */
+const SAFE_TAG = /^[A-Za-z0-9_-]{1,32}$/;
+/** Property names that behave specially on a plain object; never usable as a tag. */
+const RESERVED_TAGS = new Set(["__proto__", "constructor", "prototype"]);
+
+function isSafeTag(tag: string): boolean {
+  return SAFE_TAG.test(tag) && !RESERVED_TAGS.has(tag);
+}
+
+/**
+ * Parse `KANKAKU_SEGMENTS`, a `;`-separated list of `tag=tool:regex`
+ * entries (example: `review=bash:gentle-ai review;commit=bash:git commit`).
+ * Malformed entries (missing tag, tool or regex, an invalid regex source,
+ * or a tag that is not a safe identifier such as `__proto__`) are skipped
+ * rather than failing the whole variable.
+ */
+function parseSegmentRules(raw: string): SegmentRule[] {
+  const rules: SegmentRule[] = [];
+
+  for (const entry of raw.split(";")) {
+    const trimmed = entry.trim();
+    if (!trimmed) continue;
+
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex <= 0) continue;
+
+    const tag = trimmed.slice(0, eqIndex).trim();
+    const rest = trimmed.slice(eqIndex + 1);
+    const colonIndex = rest.indexOf(":");
+    if (colonIndex <= 0) continue;
+
+    const tool = rest.slice(0, colonIndex).trim();
+    const regexSource = rest.slice(colonIndex + 1).trim();
+    if (!tag || !tool || !regexSource || !isSafeTag(tag)) continue;
+
+    try {
+      rules.push({ tag, tool, pattern: new RegExp(regexSource) });
+    } catch {
+      continue;
+    }
+  }
+
+  return rules;
+}
+
 export function loadConfig(env: NodeJS.ProcessEnv = process.env): KankakuConfig {
   const dir = env["KANKAKU_DIR"]?.trim() || DEFAULT_DIR;
   const interactiveToolsRaw = env["KANKAKU_INTERACTIVE_TOOLS"]?.trim();
@@ -21,10 +79,17 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): KankakuConfig
         .filter((tool) => tool.length > 0)
     : DEFAULT_INTERACTIVE_TOOLS;
 
+  const segmentsRaw = env["KANKAKU_SEGMENTS"]?.trim();
+  const segmentRules = segmentsRaw ? parseSegmentRules(segmentsRaw) : DEFAULT_SEGMENT_RULES;
+
+  const client = env["KANKAKU_CLIENT"]?.trim() || undefined;
+
   return {
     dir,
     interactiveTools,
     subagentTool: SUBAGENT_TOOL,
+    segmentRules,
+    ...(client !== undefined ? { client } : {}),
   };
 }
 

package/src/domain/client-label.ts

@@ -0,0 +1,56 @@
+/**
+ * Client (billing target) label resolution: pure, no I/O.
+ *
+ * A client name identifies who a piece of work is billed to. It can come
+ * from three sources, in decreasing precedence: the pi session (set with
+ * `/kankaku client <name>`), the `KANKAKU_CLIENT` environment variable, or
+ * the project's `.kankaku/config.json`.
+ */
+
+/** Safe client name: letters, digits, `.`, `_`, `-`, 1-64 chars. */
+const CLIENT_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+
+/** Property names that behave specially on a plain object; never usable as a client name. */
+const RESERVED_NAMES = new Set(["__proto__", "constructor", "prototype"]);
+
+export interface ClientSources {
+  /** Set for the current pi session via `/kankaku client <name>`. Highest precedence. */
+  session?: string;
+  /** From the `KANKAKU_CLIENT` environment variable. */
+  env?: string;
+  /** From the project's `.kankaku/config.json`. Lowest precedence. */
+  project?: string;
+}
+
+export type ClientSourceName = "session" | "env" | "project";
+
+/** `true` when `value` is a non-empty, safe client name. */
+export function isValidClient(value: string): boolean {
+  return CLIENT_PATTERN.test(value) && !RESERVED_NAMES.has(value);
+}
+
+/** Trim and validate a candidate client name; `undefined` when absent or invalid. */
+function normalize(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return undefined;
+  return isValidClient(trimmed) ? trimmed : undefined;
+}
+
+/**
+ * Resolve the effective client name from `session`, `env` and `project`
+ * sources, in that precedence order. Each candidate is trimmed; an empty
+ * string or a value that does not match the safe client-name pattern is
+ * treated as absent and resolution falls through to the next source.
+ */
+export function resolveClient(sources: ClientSources): string | undefined {
+  return normalize(sources.session) ?? normalize(sources.env) ?? normalize(sources.project);
+}
+
+/** Which source produced {@link resolveClient}'s result, or `undefined` when none applies. */
+export function resolveClientSource(sources: ClientSources): ClientSourceName | undefined {
+  if (normalize(sources.session) !== undefined) return "session";
+  if (normalize(sources.env) !== undefined) return "env";
+  if (normalize(sources.project) !== undefined) return "project";
+  return undefined;
+}

package/src/domain/day.ts

@@ -0,0 +1,8 @@
+/** Local (not UTC) calendar day of an ISO timestamp, as `YYYY-MM-DD`. */
+export function localDay(iso: string): string {
+  const date = new Date(iso);
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}

package/src/domain/export.ts

@@ -0,0 +1,107 @@
+import { localDay } from "./day.ts";
+import { finiteOrZero } from "./work-record.ts";
+import type { WorkStatus } from "./work-record.ts";
+import type { TaskView } from "./task-view.ts";
+
+/** One flat, spreadsheet-friendly row per {@link TaskView}. */
+export interface ExportRow {
+  id: string;
+  /** Local calendar day (`YYYY-MM-DD`) the task started on. */
+  day: string;
+  startedAt: string;
+  endedAt: string;
+  /** Empty string when the task has no resolved client. */
+  client: string;
+  /** Empty string when the orchestrator record has no session name. */
+  sessionName: string;
+  /** Empty string when the orchestrator record has no session id. */
+  sessionId: string;
+  project: string;
+  status: WorkStatus;
+  /** First 200 chars of the task's prompt, with newlines collapsed to spaces. */
+  prompt: string;
+  wallMs: number;
+  waitingMs: number;
+  workMs: number;
+  cost: number;
+  tokensIn: number;
+  tokensOut: number;
+  cacheRead: number;
+  subagentCount: number;
+  /** JSON-encoded `TaskView.segments` map. */
+  segments: string;
+  /** Empty string when the orchestrator record has no model. */
+  model: string;
+}
+
+/** First 200 chars of `prompt`, with `\n`/`\r` collapsed to a single space. */
+function truncatePrompt(prompt: string): string {
+  return prompt.slice(0, 200).replace(/\r\n|\r|\n/g, " ");
+}
+
+/** Build one flat {@link ExportRow} per task, in the same order as `tasks`. */
+export function exportRows(tasks: TaskView[]): ExportRow[] {
+  return tasks.map((task) => ({
+    id: task.id,
+    day: localDay(task.startedAt),
+    startedAt: task.startedAt,
+    endedAt: task.endedAt,
+    client: task.client ?? "",
+    sessionName: task.sessionName ?? "",
+    sessionId: task.sessionId ?? "",
+    project: task.project,
+    status: task.status,
+    prompt: truncatePrompt(task.prompt),
+    wallMs: task.wallMs,
+    waitingMs: task.waitingMs,
+    workMs: task.workMs,
+    cost: finiteOrZero(task.usage.cost),
+    tokensIn: finiteOrZero(task.usage.input),
+    tokensOut: finiteOrZero(task.usage.output),
+    cacheRead: finiteOrZero(task.usage.cacheRead),
+    subagentCount: task.subagents.length,
+    segments: JSON.stringify(task.segments),
+    model: task.orchestrator.model ?? "",
+  }));
+}
+
+/** Column order for {@link toCsv}'s header row, matching {@link ExportRow}'s field order. */
+const COLUMNS: Array<keyof ExportRow> = [
+  "id",
+  "day",
+  "startedAt",
+  "endedAt",
+  "client",
+  "sessionName",
+  "sessionId",
+  "project",
+  "status",
+  "prompt",
+  "wallMs",
+  "waitingMs",
+  "workMs",
+  "cost",
+  "tokensIn",
+  "tokensOut",
+  "cacheRead",
+  "subagentCount",
+  "segments",
+  "model",
+];
+
+/** RFC 4180 field quoting: quote a field containing `,`, `"`, or a newline; double any embedded quote. */
+function csvField(value: string | number): string {
+  const text = String(value);
+  return /[",\r\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+
+/** Render `rows` as RFC 4180 CSV: a header row, one row per record, `\n` line endings. */
+export function toCsv(rows: ExportRow[]): string {
+  const lines = [COLUMNS.join(","), ...rows.map((row) => COLUMNS.map((column) => csvField(row[column])).join(","))];
+  return lines.join("\n");
+}
+
+/** Render `rows` as pretty-printed (2-space indent) JSON. */
+export function toJson(rows: ExportRow[]): string {
+  return JSON.stringify(rows, null, 2);
+}

package/src/domain/segment-rule.ts

@@ -0,0 +1,10 @@
+/**
+ * A rule that tags a tool execution as belonging to a named segment (e.g.
+ * `review`) when the tool name matches `tool` and the tool's argument text
+ * matches `pattern`.
+ */
+export interface SegmentRule {
+  tag: string;
+  tool: string;
+  pattern: RegExp;
+}

package/src/domain/task-view.ts

@@ -1,5 +1,5 @@
 import { unionMs } from "./intervals.ts";
-import { emptyUsage } from "./work-record.ts";
+import { emptyUsage, finiteOrZero } from "./work-record.ts";
 import type { UsageTotals, WorkRecord, WorkStatus } from "./work-record.ts";
 
 /**
@@ -22,6 +22,17 @@ export interface TaskView {
   orchestrator: WorkRecord;
   subagents: WorkRecord[];
   usage: UsageTotals;
+  /** Who this task is billed to, from the orchestrator record only — subagent children do not carry their own. */
+  client?: string;
+  /** pi's session display name, from the orchestrator record. */
+  sessionName?: string;
+  /**
+   * Per-tag total milliseconds across the orchestrator and every subagent,
+   * summed rather than unioned: unlike `wallMs`, segment intervals are not
+   * persisted on disk, so once a record settles its per-tag total is all
+   * that remains, and there is nothing left to union across records.
+   */
+  segments: Record<string, number>;
 }
 
 /** One or more tasks grouped by their pi session, with the same union rule. */
@@ -35,20 +46,39 @@ export interface SessionView {
   workMs: number;
   tasks: TaskView[];
   usage: UsageTotals;
+  /** Per-tag total milliseconds summed across the session's tasks. See {@link TaskView.segments}. */
+  segments: Record<string, number>;
 }
 
 function toMs(iso: string): number {
   return Date.parse(iso);
 }
 
-function sumUsage(totals: UsageTotals[]): UsageTotals {
+/** Sum per-tag milliseconds across several segment maps (older records without one count as `{}`). */
+function sumSegments(segmentMaps: Array<Record<string, number> | undefined>): Record<string, number> {
+  const result: Record<string, number> = {};
+  for (const segments of segmentMaps) {
+    for (const [tag, ms] of Object.entries(segments ?? {})) {
+      result[tag] = (result[tag] ?? 0) + ms;
+    }
+  }
+  return result;
+}
+
+/**
+ * Sum several {@link UsageTotals}, tolerating a missing entry (a record
+ * without a `usage` field) and missing or non-finite numeric fields on an
+ * entry — both treated as zero rather than corrupting the sum with
+ * `undefined`/`NaN`.
+ */
+export function sumUsage(totals: Array<UsageTotals | undefined>): UsageTotals {
   const usage = emptyUsage();
   for (const total of totals) {
-    usage.input += total.input;
-    usage.output += total.output;
-    usage.cacheRead += total.cacheRead;
-    usage.cacheWrite += total.cacheWrite;
-    usage.cost += total.cost;
+    usage.input += finiteOrZero(total?.input);
+    usage.output += finiteOrZero(total?.output);
+    usage.cacheRead += finiteOrZero(total?.cacheRead);
+    usage.cacheWrite += finiteOrZero(total?.cacheWrite);
+    usage.cost += finiteOrZero(total?.cost);
   }
   return usage;
 }
@@ -117,10 +147,13 @@ function buildTaskView(orchestrator: WorkRecord, subagents: WorkRecord[]): TaskV
   const waitingMs = orchestrator.waitingMs;
   const workMs = wallMs - waitingMs;
   const usage = sumUsage([orchestrator.usage, ...subagents.map((child) => child.usage)]);
+  const segments = sumSegments([orchestrator.segments, ...subagents.map((child) => child.segments)]);
 
   return {
     id: orchestrator.id,
     ...(orchestrator.sessionId !== undefined ? { sessionId: orchestrator.sessionId } : {}),
+    ...(orchestrator.client !== undefined ? { client: orchestrator.client } : {}),
+    ...(orchestrator.sessionName !== undefined ? { sessionName: orchestrator.sessionName } : {}),
     project: orchestrator.project,
     prompt: orchestrator.prompt,
     startedAt: orchestrator.startedAt,
@@ -132,6 +165,7 @@ function buildTaskView(orchestrator: WorkRecord, subagents: WorkRecord[]): TaskV
     orchestrator,
     subagents,
     usage,
+    segments,
   };
 }
 
@@ -182,6 +216,7 @@ export function buildSessions(tasks: TaskView[]): SessionView[] {
     const startedAtMs = Math.min(...sessionTasks.map((task) => toMs(task.startedAt)));
     const endedAtMs = Math.max(...sessionTasks.map((task) => toMs(task.endedAt)));
     const usage = sumUsage(sessionTasks.map((task) => task.usage));
+    const segments = sumSegments(sessionTasks.map((task) => task.segments));
 
     sessions.push({
       sessionId,
@@ -193,6 +228,7 @@ export function buildSessions(tasks: TaskView[]): SessionView[] {
       workMs,
       tasks: sessionTasks,
       usage,
+      segments,
     });
   }
 

package/src/domain/work-record.ts

@@ -38,6 +38,13 @@ export interface WorkRecordCore {
   turns: number;
   tools: Record<string, number>;
   subagents: SubagentSpan[];
+  /**
+   * Union milliseconds per tag spent in tool calls matched by a
+   * {@link SegmentRule} (e.g. `review`). Optional so older persisted
+   * records without this field still satisfy the type; callers reading
+   * from disk should treat a missing value as `{}`.
+   */
+  segments?: Record<string, number>;
   usage: UsageTotals;
   status: WorkStatus;
 }
@@ -52,6 +59,10 @@ export interface WorkRecordMetadata {
   sessionFile?: string;
   mode?: string;
   model?: string;
+  /** Who this work is billed to. See {@link resolveClient} in `client-label.ts`. */
+  client?: string;
+  /** pi's session display name at the time this record settled. */
+  sessionName?: string;
 }
 
 export type WorkRecord = WorkRecordCore & WorkRecordMetadata;
@@ -59,3 +70,51 @@ export type WorkRecord = WorkRecordCore & WorkRecordMetadata;
 export function emptyUsage(): UsageTotals {
   return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
 }
+
+/** A finite number, or `0` for `undefined`/`NaN`/`Infinity`/non-numbers. */
+export function finiteOrZero(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+const ROLES = new Set<WorkRole>(["orchestrator", "subagent"]);
+const STATUSES = new Set<WorkStatus>(["completed", "aborted", "interrupted"]);
+
+/** A finite, non-negative number: durations such as `wallMs` can never be negative. */
+function isNonNegativeFinite(value: unknown): boolean {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+/**
+ * Runtime guard for a {@link WorkRecord} read back from disk. `readAll`
+ * skips lines that parse as JSON but fail this check, so a torn write or a
+ * record from an incompatible schema does not crash task/session views.
+ */
+export function isWorkRecord(value: unknown): value is WorkRecord {
+  if (!value || typeof value !== "object") return false;
+  const record = value as Record<string, unknown>;
+
+  return (
+    typeof record["schema"] === "number" &&
+    typeof record["id"] === "string" &&
+    ROLES.has(record["role"] as WorkRole) &&
+    typeof record["pid"] === "number" &&
+    typeof record["parentPid"] === "number" &&
+    typeof record["project"] === "string" &&
+    typeof record["prompt"] === "string" &&
+    typeof record["startedAt"] === "string" &&
+    typeof record["settledAt"] === "string" &&
+    isNonNegativeFinite(record["wallMs"]) &&
+    isNonNegativeFinite(record["waitingMs"]) &&
+    isNonNegativeFinite(record["workMs"]) &&
+    typeof record["runs"] === "number" &&
+    typeof record["turns"] === "number" &&
+    typeof record["tools"] === "object" &&
+    record["tools"] !== null &&
+    Array.isArray(record["subagents"]) &&
+    typeof record["usage"] === "object" &&
+    record["usage"] !== null &&
+    STATUSES.has(record["status"] as WorkStatus) &&
+    (record["client"] === undefined || typeof record["client"] === "string") &&
+    (record["sessionName"] === undefined || typeof record["sessionName"] === "string")
+  );
+}