kankaku 0.1.0 → 0.4.6

package/src/domain/work-tracker.ts

@@ -1,13 +1,16 @@
 import { randomUUID } from "node:crypto";
 import type { Clock } from "../ports/clock.ts";
 import { clampIntervals, unionMs } from "./intervals.ts";
-import { emptyUsage, WORK_RECORD_SCHEMA } from "./work-record.ts";
+import { emptyUsage, finiteOrZero, WORK_RECORD_SCHEMA } from "./work-record.ts";
 import type { SubagentSpan, UsageTotals, WorkRecordCore, WorkStatus } from "./work-record.ts";
+import type { SegmentRule } from "./segment-rule.ts";
 
 export interface WorkTrackerOptions {
   clock: Clock;
   interactiveTools: string[];
   subagentTool: string;
+  /** Rules that tag a tool execution's span under a named segment. Defaults to none. */
+  segmentRules?: SegmentRule[];
 }
 
 interface Interval {
@@ -23,6 +26,8 @@ interface OpenSubagentSpan {
 }
 
 interface RunState {
+  /** Generated once when the run opens, so it stays stable across `peek` and the final `onSettled`/`onShutdown`. */
+  id: string;
   startedAt: number;
   prompt: string;
   runs: number;
@@ -35,6 +40,14 @@ interface RunState {
   openToolWaits: Map<string, Interval>;
   subagents: SubagentSpan[];
   openSubagents: Map<string, OpenSubagentSpan>;
+  /**
+   * Segment spans opened by a matching {@link SegmentRule}, keyed by tag.
+   * A `Map` rather than a plain object so a tag such as `__proto__` cannot
+   * pollute the object prototype while the run is in progress.
+   */
+  segmentSpans: Map<string, Interval[]>;
+  /** The still-open segment span for a tool call id, if any. */
+  openSegments: Map<string, Interval>;
 }
 
 interface RunEndMessage {
@@ -51,17 +64,20 @@ export class WorkTracker {
   private readonly clock: Clock;
   private readonly interactiveTools: Set<string>;
   private readonly subagentTool: string;
+  private readonly segmentRules: SegmentRule[];
   private state: RunState | undefined;
 
   constructor(options: WorkTrackerOptions) {
     this.clock = options.clock;
     this.interactiveTools = new Set(options.interactiveTools);
     this.subagentTool = options.subagentTool;
+    this.segmentRules = options.segmentRules ?? [];
   }
 
   onRunStart(prompt: string): void {
     if (!this.state) {
       this.state = {
+        id: randomUUID(),
         startedAt: this.clock.now(),
         prompt,
         runs: 1,
@@ -73,6 +89,8 @@ export class WorkTracker {
         openToolWaits: new Map(),
         subagents: [],
         openSubagents: new Map(),
+        segmentSpans: new Map(),
+        openSegments: new Map(),
       };
       return;
     }
@@ -83,17 +101,26 @@ export class WorkTracker {
     if (!this.state) return;
     this.state.turns++;
     if (!usage) return;
-    this.state.usage.input += usage.input ?? 0;
-    this.state.usage.output += usage.output ?? 0;
-    this.state.usage.cacheRead += usage.cacheRead ?? 0;
-    this.state.usage.cacheWrite += usage.cacheWrite ?? 0;
-    this.state.usage.cost += usage.cost ?? 0;
+    this.state.usage.input += finiteOrZero(usage.input);
+    this.state.usage.output += finiteOrZero(usage.output);
+    this.state.usage.cacheRead += finiteOrZero(usage.cacheRead);
+    this.state.usage.cacheWrite += finiteOrZero(usage.cacheWrite);
+    this.state.usage.cost += finiteOrZero(usage.cost);
   }
 
   onToolStart(toolCallId: string, toolName: string, args: Record<string, unknown> | undefined): void {
     if (!this.state) return;
     this.state.tools[toolName] = (this.state.tools[toolName] ?? 0) + 1;
 
+    const rule = this.segmentRules.find((candidate) => candidate.tool === toolName && candidate.pattern.test(segmentText(args)));
+    if (rule) {
+      const span: Interval = { start: this.clock.now(), end: undefined };
+      const spans = this.state.segmentSpans.get(rule.tag) ?? [];
+      spans.push(span);
+      this.state.segmentSpans.set(rule.tag, spans);
+      this.state.openSegments.set(toolCallId, span);
+    }
+
     if (this.interactiveTools.has(toolName)) {
       const span: Interval = { start: this.clock.now(), end: undefined };
       this.state.waitingSpans.push(span);
@@ -116,6 +143,12 @@ export class WorkTracker {
   onToolEnd(toolCallId: string, result: unknown): void {
     if (!this.state) return;
 
+    const openSegment = this.state.openSegments.get(toolCallId);
+    if (openSegment) {
+      this.state.openSegments.delete(toolCallId);
+      openSegment.end = this.clock.now();
+    }
+
     const openSubagent = this.state.openSubagents.get(toolCallId);
     if (openSubagent) {
       this.state.openSubagents.delete(toolCallId);
@@ -125,7 +158,9 @@ export class WorkTracker {
         agent: openSubagent.agent,
         mode: openSubagent.mode,
         ...(taskId !== undefined ? { taskId } : {}),
-        ms: this.clock.now() - openSubagent.start,
+        // Clamped to >= 0: a backward clock jump while the subagent was
+        // running must never produce a negative duration.
+        ms: Math.max(0, this.clock.now() - openSubagent.start),
       });
       return;
     }
@@ -164,39 +199,61 @@ export class WorkTracker {
 
   onSettled(): WorkRecordCore | undefined {
     if (!this.state) return undefined;
-    const record = this.finalize(this.state.status);
+    const record = this.buildRecord(this.state.status, this.clock.now());
     this.state = undefined;
     return record;
   }
 
   onShutdown(): WorkRecordCore | undefined {
     if (!this.state) return undefined;
-    const record = this.finalize("interrupted");
+    const record = this.buildRecord("interrupted", this.clock.now());
     this.state = undefined;
     return record;
   }
 
-  private finalize(status: WorkStatus): WorkRecordCore {
+  /**
+   * Returns what {@link onSettled}/{@link onShutdown} would produce right
+   * now, without mutating any state: open spans are truncated only in the
+   * returned snapshot, so the tracker keeps running unaffected and a later
+   * `peek` or the eventual settle still sees the spans' true open-ended
+   * state. `undefined` when idle. The returned `id` matches the id the
+   * eventual settled record will carry, since both are generated once
+   * in {@link onRunStart}.
+   */
+  peek(status: WorkStatus): WorkRecordCore | undefined {
+    if (!this.state) return undefined;
+    return this.buildRecord(status, this.clock.now());
+  }
+
+  private buildRecord(status: WorkStatus, settledAt: number): WorkRecordCore {
     const state = this.state;
     if (!state) {
-      throw new Error("finalize called without an open run");
+      throw new Error("buildRecord called without an open run");
     }
-    const settledAt = this.clock.now();
-    const wallMs = settledAt - state.startedAt;
+    // Clamped to >= 0: a backward clock jump (system clock adjustment, NTP
+    // correction) must never produce a negative duration.
+    const wallMs = Math.max(0, settledAt - state.startedAt);
+
+    const closedSpans = state.waitingSpans.map((span) => ({ start: span.start, end: span.end ?? settledAt }));
+    const waitingMs = Math.max(0, unionMs(clampIntervals(closedSpans, state.startedAt, settledAt)));
+    const workMs = Math.max(0, wallMs - waitingMs);
 
-    for (const span of state.waitingSpans) {
-      if (span.end === undefined) {
-        span.end = settledAt;
+    const segmentEntries: Array<[string, number]> = [];
+    for (const [tag, spans] of state.segmentSpans) {
+      const closedTagSpans = spans.map((span) => ({ start: span.start, end: span.end ?? settledAt }));
+      const tagMs = Math.max(0, unionMs(clampIntervals(closedTagSpans, state.startedAt, settledAt)));
+      if (tagMs > 0) {
+        segmentEntries.push([tag, tagMs]);
       }
     }
-
-    const closedSpans = state.waitingSpans.map((span) => ({ start: span.start, end: span.end as number }));
-    const waitingMs = unionMs(clampIntervals(closedSpans, state.startedAt, settledAt));
-    const workMs = wallMs - waitingMs;
+    // Built via Object.fromEntries (never `segments[tag] = ...`) so a tag
+    // such as `__proto__` becomes an own data property instead of silently
+    // repointing the object's prototype.
+    const segments = Object.fromEntries(segmentEntries);
 
     return {
       schema: WORK_RECORD_SCHEMA,
-      id: randomUUID(),
+      id: state.id,
       prompt: state.prompt,
       startedAt: new Date(state.startedAt).toISOString(),
       settledAt: new Date(settledAt).toISOString(),
@@ -207,12 +264,19 @@ export class WorkTracker {
       turns: state.turns,
       tools: state.tools,
       subagents: state.subagents,
+      segments,
       usage: state.usage,
       status,
     };
   }
 }
 
+/** Text to match a {@link SegmentRule} pattern against: the `command` string arg when present, else the whole args object as JSON. */
+function segmentText(args: Record<string, unknown> | undefined): string {
+  const command = args?.["command"];
+  return typeof command === "string" ? command : JSON.stringify(args ?? {});
+}
+
 function extractTaskId(result: unknown): string | undefined {
   if (!result || typeof result !== "object") return undefined;
   const details = (result as { details?: unknown }).details;

package/src/extension.ts

@@ -2,7 +2,10 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { detectRole, loadConfig } from "./config.ts";
 import { WorkTracker } from "./domain/work-tracker.ts";
 import { LazyJsonlWorkLog } from "./adapters/lazy-jsonl-work-log.ts";
+import { LazyFileInflightStore } from "./adapters/lazy-file-inflight-store.ts";
 import { createPiTracker } from "./adapters/pi-tracker.ts";
+import { LazyProjectClientSource } from "./adapters/project-config.ts";
+import { LazyExportWriter } from "./adapters/export-writer.ts";
 
 export default function kankaku(pi: ExtensionAPI): void {
   const config = loadConfig();
@@ -12,15 +15,24 @@ export default function kankaku(pi: ExtensionAPI): void {
     clock: { now: () => Date.now() },
     interactiveTools: config.interactiveTools,
     subagentTool: config.subagentTool,
+    segmentRules: config.segmentRules,
   });
 
   const log = new LazyJsonlWorkLog(config.dir);
+  const inflight = new LazyFileInflightStore(config.dir, process.pid);
+
+  const projectClient = new LazyProjectClientSource(config.dir);
+  const exportWriter = new LazyExportWriter(config.dir);
 
   createPiTracker(pi, {
     tracker,
     log,
+    inflight,
     role,
     pid: process.pid,
     parentPid: process.ppid,
+    ...(config.client !== undefined ? { envClient: config.client } : {}),
+    resolveProjectClient: () => projectClient.read(),
+    writeExportFile: (name, content) => exportWriter.write(name, content),
   });
 }

package/src/ports/inflight-store.ts

@@ -0,0 +1,16 @@
+import type { WorkRecord } from "../domain/work-record.ts";
+
+/**
+ * Crash-recovery checkpoint store: one process periodically saves the
+ * record its {@link WorkTracker} would produce right now, so a hard crash
+ * (kill -9, power loss) still leaves a record behind — recovered as
+ * `interrupted` on the next pi start rather than lost entirely.
+ */
+export interface InflightStore {
+  /** Upsert this process's checkpoint. */
+  save(record: WorkRecord): void;
+  /** Remove this process's checkpoint (normal settle/shutdown). */
+  clear(): void;
+  /** Return and delete every checkpoint whose owning pid is no longer alive. */
+  recoverStale(isAlive: (pid: number) => boolean): WorkRecord[];
+}

package/src/ports/work-log.ts

@@ -3,4 +3,13 @@ import type { WorkRecord } from "../domain/work-record.ts";
 export interface WorkLog {
   append(record: WorkRecord): void;
   readAll(): WorkRecord[];
+  /**
+   * Optional cheap change signal: a value that changes whenever `append()`
+   * would change what `readAll()` returns, computable without reading the
+   * whole log (e.g. from file stat metadata). Callers that cache a view
+   * derived from `readAll()` (see `pi-tracker.ts`'s client-name completion
+   * cache) may use this to invalidate cheaply; a `WorkLog` that omits it
+   * simply leaves such callers relying on their own explicit invalidation.
+   */
+  version?(): string | number;
 }