kankaku 0.1.0 → 0.4.5

package/README.md

@@ -55,6 +55,8 @@ Each line in `worklog.jsonl` is one JSON object:
   "sessionFile": "…",
   "mode": "tui",
   "model": "anthropic/claude-opus",
+  "client": "acme",
+  "sessionName": "billing sprint",
   "prompt": "first 200 chars of the first prompt",
   "startedAt": "2026-09-10T16:00:00.000Z",
   "settledAt": "2026-09-10T16:04:10.000Z",
@@ -65,6 +67,7 @@ Each line in `worklog.jsonl` is one JSON object:
   "turns": 9,
   "tools": { "bash": 4, "read": 3, "subagent_run": 1, "ask_user_question": 1 },
   "subagents": [{ "toolCallId": "…", "agent": "sdd-explore", "mode": "task", "taskId": "t1", "ms": 90000 }],
+  "segments": { "review": 62000 },
   "usage": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0, "cost": 0 },
   "status": "completed"
 }
@@ -122,22 +125,136 @@ Arguments are whitespace-separated and order-insensitive:
   session are shown instead.
 - `/kankaku sessions` — one line per session (id, time range, union
   wall/work, cost, task count) for today. Add `all` for every day.
+- `/kankaku client <name>` — set the billing client for the current pi
+  session. `/kankaku client` alone shows the effective client and which
+  source it came from; `/kankaku client --clear` removes the session-level
+  override. See "Billing labels" below.
+- `/kankaku clients` — one line per client (work/waiting/wall time, cost,
+  task count) for today. Add `all` for every day. Tasks with no resolved
+  client are grouped under `(none)`.
 
 Cost figures are the sum of `usage.cost` as priced by pi's model table
 (per-million-token rates in `models.json`, adjustable with `modelOverrides`).
 For subscription-based providers this is an estimate at API list prices, not
 an invoice.
 
-While an agent is running, pi's status bar shows a `⏱ mm:ss` indicator with
+While an agent is running, pi's status bar shows a `🕒 mm:ss · <client>` indicator (the client part appears only when one resolves); while idle it shows `💼 <client>`, or nothing when no client resolves. The entry is keyed `zz-kankaku` so it sorts last among extension statuses. The running indicator carries
 the elapsed time for the current run.
 
+## Billing labels
+
+Every `WorkRecord` can carry a `client` — who the work is billed to — so
+reports and exports can be grouped by client. The effective client is
+resolved from three sources, in decreasing precedence:
+
+1. **Session** — set with `/kankaku client <name>` (see above), persisted as
+   a `kankaku-client` custom session entry and restored on session reload.
+2. **`KANKAKU_CLIENT`** — the environment variable, a per-process default.
+3. **Project** — `client` in `<KANKAKU_DIR>/config.json` (e.g.
+   `{"client": "acme"}`), the project's own default.
+
+A client name must match `/^[A-Za-z0-9._-]{1,64}$/`; anything else (empty,
+too long, containing spaces or other characters) is ignored and resolution
+falls through to the next source.
+
+A `subagent_run` child process does not resolve its own client — a
+subagent's own `WorkRecord` never carries `client`. Instead, the **task**
+view (see "Task and session views") exposes the client from its
+orchestrator record only, so `/kankaku tasks`, `/kankaku clients`, and the
+export all see subagent work grouped under the task's (i.e. the
+orchestrator's) client.
+
+`sessionName` is also attached to every record from `pi.getSessionName()`,
+so reports can show which named session produced a task.
+
+## Tagged segments
+
+While a run is open, kankaku can also time tool executions that match a
+configured rule and tag the resulting span with a name — for example,
+knowing how much of a task went to gentle-ai's review-with-receipts step,
+which runs as `gentle-ai review ...` commands through the `bash` tool inside
+the prompt's run.
+
+The default rule tags `review`: tool `bash` running a command matching
+`/\bgentle-ai review\b/`. Configure rules with `KANKAKU_SEGMENTS`, a
+`;`-separated list of `tag=tool:regex` entries, e.g.:
+
+```
+KANKAKU_SEGMENTS="review=bash:gentle-ai review;commit=bash:git commit"
+```
+
+Setting `KANKAKU_SEGMENTS` replaces the default rule entirely; malformed
+entries (missing tag, tool or regex, or an invalid regex) are skipped.
+When several rules could match the same tool call, only the first one
+applies. A `WorkRecord`'s `segments` field is the **union** of milliseconds
+per tag within that one record, so overlapping matching calls are not
+double-counted. `TaskView.segments` and `SessionView.segments` are instead
+the **sum** of `segments` across the orchestrator and its children (or
+across a session's tasks): segment spans are not persisted to
+`worklog.jsonl`, so once a record settles there is nothing left to union
+across records, only per-record totals to add up.
+
+Note that the reviewer's own token cost is not observable here: gentle-pi
+runs it with `--no-extensions`, so kankaku never sees the reviewer's own
+prompt/tool events, only the `bash` call the orchestrator makes to invoke
+it.
+
+## Crash recovery
+
+While a run is open, each pi process periodically writes a checkpoint of
+its current record to `<KANKAKU_DIR>/inflight/<pid>.json` (after every
+`turn_end` and `tool_execution_end`), and removes it on a normal
+`agent_settled`/`session_shutdown`. If the process is killed outright
+(`kill -9`, power loss) before it can settle, the checkpoint file survives
+it. On the next pi start, `session_start` scans `inflight/` for checkpoints
+whose owning pid is no longer alive, appends each one to `worklog.jsonl` as
+`interrupted`, deletes the checkpoint file, and shows a
+`kankaku: recovered N interrupted record(s)` notice. `settledAt` on a
+recovered record is the time of its last checkpoint, not the actual crash
+time, so `wallMs`/`workMs` are a **lower bound** on the real duration.
+
+## Export
+
+`/kankaku export [csv|json] [all]` writes one flat row per task (today's
+tasks by default, or every task with `all`) to
+`<KANKAKU_DIR>/export/tasks-<YYYY-MM-DD or all>.<csv|json>`, and confirms
+with the file's path and row count via the durable report card. Format
+defaults to `csv`; each subagent's own time is folded into its task's row
+rather than exported separately (see "Task and session views").
+
+Columns (in this order for CSV; the same fields for JSON):
+
+| Column | Meaning |
+| --- | --- |
+| `id` | Task id (the orchestrator record's `id`). |
+| `day` | Local calendar day (`YYYY-MM-DD`) the task started on. |
+| `startedAt` / `endedAt` | ISO timestamps of the task's span. |
+| `client` | Billing client, or empty when unresolved. |
+| `sessionName` | pi session display name, or empty. |
+| `sessionId` | pi session id, or empty. |
+| `project` | Project cwd. |
+| `status` | `completed`, `aborted`, or `interrupted`. |
+| `prompt` | First 200 chars of the prompt, newlines collapsed to spaces. |
+| `wallMs` / `waitingMs` / `workMs` | Union-based task timings (see "Task and session views"). |
+| `cost` | Estimated USD cost, orchestrator plus subagents. |
+| `tokensIn` / `tokensOut` / `cacheRead` | Token usage totals. |
+| `subagentCount` | Number of subagent records matched to the task. |
+| `segments` | JSON-encoded per-tag segment totals (see "Tagged segments"). |
+| `model` | The orchestrator record's model, or empty. |
+
 ## Environment variables
 
-- `KANKAKU_DIR`: directory for the work log, relative to the project cwd
-  unless given as an absolute path. Defaults to `.kankaku`.
+- `KANKAKU_DIR`: directory for the work log (`worklog.jsonl`) and the
+  crash-recovery checkpoints (`inflight/`, see above), relative to the
+  project cwd unless given as an absolute path. Defaults to `.kankaku`.
 - `KANKAKU_INTERACTIVE_TOOLS`: comma-separated list of tool names whose
   execution span counts as waiting time. Defaults to
   `ask_user_question,ask_user_choice`.
+- `KANKAKU_SEGMENTS`: `;`-separated `tag=tool:regex` rules for tagged
+  segments (see above). Defaults to the single `review` rule.
+- `KANKAKU_CLIENT`: default billing client for this project (see "Billing
+  labels" above). Lower precedence than the session-level
+  `/kankaku client` override, higher than `<KANKAKU_DIR>/config.json`.
 
 ## Limitations
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku",
-  "version": "0.1.0",
+  "version": "0.4.5",
   "description": "pi extension that records agent work time per prompt, excluding waits for the user, with subagent linkage and task/session views",
   "license": "MIT",
   "author": "soyunninja",

package/src/adapters/export-writer.ts

@@ -0,0 +1,33 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { resolveKankakuDir } from "./kankaku-dir.ts";
+
+const EXPORT_SUBDIR = "export";
+
+/**
+ * Write `content` to `<dir>/export/<name>` (creating the `export`
+ * subdirectory as needed, overwriting any existing file with the same
+ * name) and return the absolute path it was written to.
+ */
+export function writeExport(dir: string, name: string, content: string): string {
+  const exportDir = join(dir, EXPORT_SUBDIR);
+  mkdirSync(exportDir, { recursive: true });
+  const filePath = resolve(join(exportDir, name));
+  writeFileSync(filePath, content);
+  return filePath;
+}
+
+/** Writes exports under a kankaku dir resolved lazily against `fallbackCwd()` at call time. */
+export class LazyExportWriter {
+  private readonly dirOrRelative: string;
+  private readonly fallbackCwd: () => string;
+
+  constructor(dirOrRelative: string, fallbackCwd: () => string = () => process.cwd()) {
+    this.dirOrRelative = dirOrRelative;
+    this.fallbackCwd = fallbackCwd;
+  }
+
+  write(name: string, content: string): string {
+    return writeExport(resolveKankakuDir(this.dirOrRelative, this.fallbackCwd()), name, content);
+  }
+}

package/src/adapters/file-inflight-store.ts

@@ -0,0 +1,83 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { isWorkRecord } from "../domain/work-record.ts";
+import type { WorkRecord } from "../domain/work-record.ts";
+import type { InflightStore } from "../ports/inflight-store.ts";
+
+const INFLIGHT_DIR_NAME = "inflight";
+const JSON_EXT = ".json";
+
+function safeUnlink(filePath: string): void {
+  try {
+    unlinkSync(filePath);
+  } catch {
+    // Best effort: another process may have already removed it.
+  }
+}
+
+/**
+ * {@link InflightStore} backed by one checkpoint file per process,
+ * `<dir>/inflight/<pid>.json`. `save` writes to a temp file then renames
+ * it into place so a reader never observes a partially written checkpoint.
+ */
+export class FileInflightStore implements InflightStore {
+  private readonly dir: string;
+  private readonly pid: number;
+
+  constructor(dir: string, pid: number) {
+    this.dir = dir;
+    this.pid = pid;
+  }
+
+  private get inflightDir(): string {
+    return join(this.dir, INFLIGHT_DIR_NAME);
+  }
+
+  private filePathFor(pid: number): string {
+    return join(this.inflightDir, `${pid}${JSON_EXT}`);
+  }
+
+  save(record: WorkRecord): void {
+    mkdirSync(this.inflightDir, { recursive: true });
+    const target = this.filePathFor(this.pid);
+    const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(record));
+    renameSync(tmp, target);
+  }
+
+  clear(): void {
+    safeUnlink(this.filePathFor(this.pid));
+  }
+
+  recoverStale(isAlive: (pid: number) => boolean): WorkRecord[] {
+    if (!existsSync(this.inflightDir)) return [];
+
+    const recovered: WorkRecord[] = [];
+    const ownFileName = `${this.pid}${JSON_EXT}`;
+
+    for (const entry of readdirSync(this.inflightDir)) {
+      if (!entry.endsWith(JSON_EXT) || entry === ownFileName) continue;
+
+      const filePath = join(this.inflightDir, entry);
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(readFileSync(filePath, "utf8"));
+      } catch {
+        safeUnlink(filePath);
+        continue;
+      }
+
+      if (!isWorkRecord(parsed)) {
+        safeUnlink(filePath);
+        continue;
+      }
+
+      if (isAlive(parsed.pid)) continue;
+
+      recovered.push({ ...parsed, status: "interrupted" });
+      safeUnlink(filePath);
+    }
+
+    return recovered;
+  }
+}

package/src/adapters/jsonl-work-log.ts

@@ -2,6 +2,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { WorkLog } from "../ports/work-log.ts";
 import type { WorkRecord } from "../domain/work-record.ts";
+import { isWorkRecord } from "../domain/work-record.ts";
 
 const LOG_FILE_NAME = "worklog.jsonl";
 
@@ -34,7 +35,12 @@ export class JsonlWorkLog implements WorkLog {
       const trimmed = line.trim();
       if (!trimmed) continue;
       try {
-        records.push(JSON.parse(trimmed) as WorkRecord);
+        const parsed: unknown = JSON.parse(trimmed);
+        if (isWorkRecord(parsed)) {
+          records.push(parsed);
+        }
+        // Tolerate a structurally invalid record (e.g. an incompatible
+        // schema or a torn write that still parses as JSON); skip it.
       } catch {
         // Tolerate malformed lines (e.g. a torn write); skip them.
       }

package/src/adapters/kankaku-dir.ts

@@ -0,0 +1,10 @@
+import { isAbsolute, join } from "node:path";
+
+/**
+ * Resolve the kankaku data directory: an absolute `dirOrRelative` is used
+ * as-is, a relative one is joined against `cwd`. Shared by every lazy
+ * adapter so the rule lives in exactly one place.
+ */
+export function resolveKankakuDir(dirOrRelative: string, cwd: string): string {
+  return isAbsolute(dirOrRelative) ? dirOrRelative : join(cwd, dirOrRelative);
+}

package/src/adapters/lazy-file-inflight-store.ts

@@ -0,0 +1,43 @@
+import type { WorkRecord } from "../domain/work-record.ts";
+import type { InflightStore } from "../ports/inflight-store.ts";
+import { FileInflightStore } from "./file-inflight-store.ts";
+import { resolveKankakuDir } from "./kankaku-dir.ts";
+
+/**
+ * {@link InflightStore} that resolves a relative checkpoint directory
+ * lazily, mirroring {@link LazyJsonlWorkLog}: against the project of the
+ * first saved record, or against `fallbackCwd()` when `clear` or
+ * `recoverStale` happens before any record was saved in this process
+ * (e.g. `session_start`, which runs before `before_agent_start`).
+ */
+export class LazyFileInflightStore implements InflightStore {
+  private readonly dirOrRelative: string;
+  private readonly pid: number;
+  private readonly fallbackCwd: () => string;
+  private resolved: FileInflightStore | undefined;
+
+  constructor(dirOrRelative: string, pid: number, fallbackCwd: () => string = () => process.cwd()) {
+    this.dirOrRelative = dirOrRelative;
+    this.pid = pid;
+    this.fallbackCwd = fallbackCwd;
+  }
+
+  private resolveFor(cwd: string): FileInflightStore {
+    if (!this.resolved) {
+      this.resolved = new FileInflightStore(resolveKankakuDir(this.dirOrRelative, cwd), this.pid);
+    }
+    return this.resolved;
+  }
+
+  save(record: WorkRecord): void {
+    this.resolveFor(record.project).save(record);
+  }
+
+  clear(): void {
+    this.resolveFor(this.fallbackCwd()).clear();
+  }
+
+  recoverStale(isAlive: (pid: number) => boolean): WorkRecord[] {
+    return this.resolveFor(this.fallbackCwd()).recoverStale(isAlive);
+  }
+}

package/src/adapters/lazy-jsonl-work-log.ts

@@ -1,7 +1,7 @@
-import { isAbsolute, join } from "node:path";
 import type { WorkRecord } from "../domain/work-record.ts";
 import type { WorkLog } from "../ports/work-log.ts";
 import { JsonlWorkLog } from "./jsonl-work-log.ts";
+import { resolveKankakuDir } from "./kankaku-dir.ts";
 
 /**
  * {@link WorkLog} that resolves a relative log directory lazily: against the
@@ -20,8 +20,7 @@ export class LazyJsonlWorkLog implements WorkLog {
 
   private resolveFor(cwd: string): JsonlWorkLog {
     if (!this.resolved) {
-      const dir = isAbsolute(this.dirOrRelative) ? this.dirOrRelative : join(cwd, this.dirOrRelative);
-      this.resolved = new JsonlWorkLog(dir);
+      this.resolved = new JsonlWorkLog(resolveKankakuDir(this.dirOrRelative, cwd));
     }
     return this.resolved;
   }