kankaku-claude 0.1.0

package/src/cost-store.ts

@@ -0,0 +1,138 @@
+import { chmodSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Only the field this module actually needs from `process.env`. */
+export interface CostEnv {
+  HOME?: string;
+}
+
+export interface CostState {
+  totalUsd: number;
+  updatedAt: number;
+  model?: string;
+}
+
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Cost lives under the HOME directory, never a project: the statusline
+ * command is wired globally and runs in every session on the machine, so a
+ * project-relative path would litter whatever project happens to be open
+ * (the defect this module fixes — see `odd/tasks/hook-tracking.md` T7).
+ * Imports only node builtins so light hooks that read/write cost stay off
+ * the `kankaku` import path.
+ */
+export function costDir(env: CostEnv): string {
+  const home = env.HOME || homedir();
+  return join(home, ".kankaku", "claude", "cost");
+}
+
+export function costFile(env: CostEnv, sessionId: string): string {
+  return join(costDir(env), `${sessionId}.json`);
+}
+
+function isCostState(value: unknown): value is CostState {
+  if (typeof value !== "object" || value === null) return false;
+  const o = value as Record<string, unknown>;
+  return (
+    typeof o.totalUsd === "number" &&
+    typeof o.updatedAt === "number" &&
+    (o.model === undefined || typeof o.model === "string")
+  );
+}
+
+/** `undefined` when the file is absent or its contents are malformed. */
+export function readCost(env: CostEnv, sessionId: string): CostState | undefined {
+  let text: string;
+  try {
+    text = readFileSync(costFile(env, sessionId), "utf8");
+  } catch {
+    return undefined;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  return isCostState(parsed) ? parsed : undefined;
+}
+
+/**
+ * Atomic tmp+rename write. Creates `claude/` and `claude/cost/` (both owned
+ * exclusively by this plugin) as owner-only (`0700`) when it creates them —
+ * `mkdirSync`'s `mode` only ever applies to a directory the call actually
+ * creates, so an existing `~/.kankaku` is never chmod'd by this. The written
+ * file is chmod'd `0600` best-effort. Never lowers `updatedAt`: a statusline
+ * write racing an older one loses.
+ */
+export function writeCost(env: CostEnv, sessionId: string, cost: CostState): void {
+  const dir = costDir(env);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  const existing = readCost(env, sessionId);
+  if (existing && existing.updatedAt > cost.updatedAt) return;
+
+  const file = costFile(env, sessionId);
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(cost));
+  renameSync(tmp, file);
+  try {
+    chmodSync(file, 0o600);
+  } catch {
+    // best-effort
+  }
+}
+
+export function deleteCost(env: CostEnv, sessionId: string): void {
+  try {
+    unlinkSync(costFile(env, sessionId));
+  } catch {
+    // already gone
+  }
+}
+
+export interface SweepStaleCostFilesOptions {
+  now: number;
+  maxAgeMs?: number;
+}
+
+/**
+ * Deletes cost files whose `updatedAt` (or mtime, when the file is
+ * unparsable) is older than `maxAgeMs` (default 7 days). No-op when the
+ * cost directory does not exist yet.
+ */
+export function sweepStaleCostFiles(env: CostEnv, opts: SweepStaleCostFilesOptions): void {
+  const maxAgeMs = opts.maxAgeMs ?? SEVEN_DAYS_MS;
+  const dir = costDir(env);
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (!name.endsWith(".json")) continue;
+    const file = join(dir, name);
+    const sessionId = name.slice(0, -".json".length);
+    const cost = readCost(env, sessionId);
+    let age: number;
+    if (cost) {
+      age = opts.now - cost.updatedAt;
+    } else {
+      try {
+        age = opts.now - statSync(file).mtimeMs;
+      } catch {
+        continue;
+      }
+    }
+    if (age > maxAgeMs) {
+      try {
+        unlinkSync(file);
+      } catch {
+        // already gone
+      }
+    }
+  }
+}

package/src/event-log.ts

@@ -0,0 +1,33 @@
+import { appendFileSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { readEvents, serializeEvent, type Event } from "./events.ts";
+
+/** Appends one event line, creating parent directories as needed. */
+export function appendEvent(file: string, event: Event): void {
+  mkdirSync(dirname(file), { recursive: true });
+  appendFileSync(file, serializeEvent(event) + "\n");
+}
+
+/** Empty array when the file does not exist. Tolerant of malformed/truncated lines (see `readEvents`). */
+export function readEventLog(file: string): Event[] {
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return [];
+  }
+  return readEvents(text);
+}
+
+/**
+ * Rewrites the events file atomically (tmp+rename) so it holds only `keep`
+ * — used to drop a prompt's events once it has settled, keeping only the
+ * still-open prompt's events, if any.
+ */
+export function dropSettledPrompts(file: string, keep: Event[]): void {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  const text = keep.length === 0 ? "" : keep.map(serializeEvent).join("\n") + "\n";
+  writeFileSync(tmp, text);
+  renameSync(tmp, file);
+}

package/src/events.ts

@@ -0,0 +1,145 @@
+/**
+ * The append-only event line format written to
+ * `<KANKAKU_DIR>/claude/<session_id>.events.jsonl`. One line per hook
+ * invocation, minimal fields only — see AGENTS.md / odd/tasks/hook-tracking.md
+ * "Event line".
+ */
+
+export interface UserPromptSubmitEvent {
+  ts: number;
+  event: "UserPromptSubmit";
+  prompt: string;
+  promptId?: string;
+}
+
+export interface PreToolUseEvent {
+  ts: number;
+  event: "PreToolUse";
+  toolUseId: string;
+  toolName: string;
+  toolInput: Record<string, unknown>;
+}
+
+export interface PostToolUseEvent {
+  ts: number;
+  event: "PostToolUse";
+  toolUseId: string;
+  toolName: string;
+}
+
+export interface PermissionRequestEvent {
+  ts: number;
+  event: "PermissionRequest";
+  toolUseId: string;
+  toolName: string;
+}
+
+export interface SubagentStartEvent {
+  ts: number;
+  event: "SubagentStart";
+  agentId: string;
+  agentType: string;
+}
+
+export interface SubagentStopEvent {
+  ts: number;
+  event: "SubagentStop";
+  agentId: string;
+  agentType: string;
+}
+
+export interface StopEvent {
+  ts: number;
+  event: "Stop";
+  stopHookActive: boolean;
+}
+
+export interface SessionStartEvent {
+  ts: number;
+  event: "SessionStart";
+  source: string;
+}
+
+export interface SessionEndEvent {
+  ts: number;
+  event: "SessionEnd";
+  reason: string;
+}
+
+export type Event =
+  | UserPromptSubmitEvent
+  | PreToolUseEvent
+  | PostToolUseEvent
+  | PermissionRequestEvent
+  | SubagentStartEvent
+  | SubagentStopEvent
+  | StopEvent
+  | SessionStartEvent
+  | SessionEndEvent;
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function isString(value: unknown): value is string {
+  return typeof value === "string";
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+const validators: Record<string, (o: Record<string, unknown>) => boolean> = {
+  UserPromptSubmit: (o) =>
+    isString(o.prompt) && (o.promptId === undefined || isString(o.promptId)),
+  PreToolUse: (o) =>
+    isString(o.toolUseId) && isString(o.toolName) && isPlainObject(o.toolInput),
+  PostToolUse: (o) => isString(o.toolUseId) && isString(o.toolName),
+  PermissionRequest: (o) => isString(o.toolUseId) && isString(o.toolName),
+  SubagentStart: (o) => isString(o.agentId) && isString(o.agentType),
+  SubagentStop: (o) => isString(o.agentId) && isString(o.agentType),
+  Stop: (o) => typeof o.stopHookActive === "boolean",
+  SessionStart: (o) => isString(o.source),
+  SessionEnd: (o) => isString(o.reason),
+};
+
+/** One JSON line, no trailing newline. */
+export function serializeEvent(event: Event): string {
+  return JSON.stringify(event);
+}
+
+/**
+ * Parses one event line. Never throws: malformed JSON, a non-object value,
+ * an unknown `event` name, or a known event missing/mistyping a required
+ * field all return `undefined` instead.
+ */
+export function parseEventLine(line: string): Event | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return undefined;
+  }
+  if (!isPlainObject(parsed)) return undefined;
+  if (!isFiniteNumber(parsed.ts)) return undefined;
+  if (!isString(parsed.event)) return undefined;
+  const validate = validators[parsed.event];
+  if (!validate) return undefined;
+  if (!validate(parsed)) return undefined;
+  return parsed as unknown as Event;
+}
+
+/**
+ * Parses every line of an events file. Tolerant of blank lines and of a
+ * truncated last line (a partial write left by a crash): any line that
+ * fails to parse is simply skipped, never thrown.
+ */
+export function readEvents(text: string): Event[] {
+  const events: Event[] = [];
+  for (const line of text.split("\n")) {
+    if (line.trim() === "") continue;
+    const event = parseEventLine(line);
+    if (event) events.push(event);
+  }
+  return events;
+}

package/src/handle-hook.ts

@@ -0,0 +1,275 @@
+import { unlinkSync } from "node:fs";
+import { resolvePaths, type ResolvedPaths } from "./paths.ts";
+import { appendEvent, readEventLog, dropSettledPrompts } from "./event-log.ts";
+import { readState, writeState, updateState, type SessionState } from "./session-state.ts";
+import { resolveClaudePid, type PsInfo } from "./claude-pid.ts";
+import { splitPrompts, type PromptEvents } from "./prompts.ts";
+import { readCost, deleteCost, sweepStaleCostFiles } from "./cost-store.ts";
+import type { Event } from "./events.ts";
+import type { WorkLog } from "kankaku/ports";
+
+export interface HandleHookDeps {
+  env: NodeJS.ProcessEnv;
+  /** Epoch ms; called once per event to stamp it and drive the Stop cost wait. */
+  now: () => number;
+  sleep: (ms: number) => Promise<void>;
+  /** Injected for tests; production defaults to `new JsonlWorkLog(kankakuDir)`. */
+  log?: WorkLog;
+  isAlive: (pid: number) => boolean;
+  runPs: (pid: number) => PsInfo | undefined;
+  stderr: (message: string) => void;
+}
+
+const STOP_COST_WAIT_POLL_MS = 100;
+const STOP_COST_WAIT_MAX_MS = 1500;
+
+/**
+ * Dispatches one Claude Code hook invocation. Light events (everything but
+ * Stop/SessionStart/SessionEnd) only append one event line plus a tiny
+ * state update, and never import `kankaku` at runtime — the heavier replay/
+ * storage layer is loaded with dynamic `import()` only inside the three
+ * branches that actually settle or recover a record.
+ */
+export async function handleHook(input: unknown, deps: HandleHookDeps): Promise<void> {
+  const common = parseCommon(input);
+  if (!common) {
+    deps.stderr("kankaku: malformed hook input, ignoring");
+    return;
+  }
+  const { sessionId, cwd, hookEventName, raw } = common;
+  const paths = resolvePaths({ env: deps.env, cwd, sessionId });
+  const ts = deps.now();
+
+  switch (hookEventName) {
+    case "UserPromptSubmit": {
+      const prompt = readString(raw.prompt) ?? "";
+      const promptId = readString(raw.prompt_id);
+      const event: Event = promptId
+        ? { ts, event: "UserPromptSubmit", prompt, promptId }
+        : { ts, event: "UserPromptSubmit", prompt };
+      appendEvent(paths.eventsFile, event);
+      const costAtStart = readCost(deps.env, sessionId)?.totalUsd;
+      updateState(paths.stateFile, (state) => ({
+        pid: state?.pid ?? 0,
+        parentPid: state?.parentPid ?? 0,
+        cwd: state?.cwd || cwd,
+        startedAt: state?.startedAt ?? ts,
+        promptOpen: { id: promptId ?? `${sessionId}:${ts}`, startedAt: ts, costAtStart },
+        permissionOpen: null,
+      }));
+      return;
+    }
+    case "PreToolUse": {
+      const toolUseId = readString(raw.tool_use_id) ?? "";
+      const toolName = readString(raw.tool_name) ?? "";
+      const toolInput = isPlainObject(raw.tool_input) ? raw.tool_input : {};
+      appendEvent(paths.eventsFile, { ts, event: "PreToolUse", toolUseId, toolName, toolInput });
+      clearPermissionOpen(paths.stateFile);
+      return;
+    }
+    case "PostToolUse": {
+      const toolUseId = readString(raw.tool_use_id) ?? "";
+      const toolName = readString(raw.tool_name) ?? "";
+      appendEvent(paths.eventsFile, { ts, event: "PostToolUse", toolUseId, toolName });
+      clearPermissionOpen(paths.stateFile);
+      return;
+    }
+    case "PermissionRequest": {
+      const toolUseId = readString(raw.tool_use_id) ?? "";
+      const toolName = readString(raw.tool_name) ?? "";
+      appendEvent(paths.eventsFile, { ts, event: "PermissionRequest", toolUseId, toolName });
+      updateState(paths.stateFile, (state) => ({
+        pid: state?.pid ?? 0,
+        parentPid: state?.parentPid ?? 0,
+        cwd: state?.cwd || cwd,
+        startedAt: state?.startedAt ?? ts,
+        promptOpen: state?.promptOpen ?? null,
+        permissionOpen: ts,
+      }));
+      return;
+    }
+    case "SubagentStart": {
+      const agentId = readString(raw.agent_id) ?? "";
+      const agentType = readString(raw.agent_type) ?? "";
+      appendEvent(paths.eventsFile, { ts, event: "SubagentStart", agentId, agentType });
+      clearPermissionOpen(paths.stateFile);
+      return;
+    }
+    case "SubagentStop": {
+      const agentId = readString(raw.agent_id) ?? "";
+      const agentType = readString(raw.agent_type) ?? "";
+      appendEvent(paths.eventsFile, { ts, event: "SubagentStop", agentId, agentType });
+      clearPermissionOpen(paths.stateFile);
+      return;
+    }
+    case "Stop": {
+      const stopHookActive = raw.stop_hook_active === true;
+      appendEvent(paths.eventsFile, { ts, event: "Stop", stopHookActive });
+      clearPermissionOpen(paths.stateFile);
+      await handleStop(paths, sessionId, deps);
+      return;
+    }
+    case "SessionStart": {
+      const source = readString(raw.source) ?? "startup";
+      appendEvent(paths.eventsFile, { ts, event: "SessionStart", source });
+      await handleSessionStart(paths, sessionId, cwd, source, ts, deps);
+      return;
+    }
+    case "SessionEnd": {
+      const reason = readString(raw.reason) ?? "other";
+      appendEvent(paths.eventsFile, { ts, event: "SessionEnd", reason });
+      await handleSessionEnd(paths, sessionId, ts, deps);
+      return;
+    }
+    default:
+      return;
+  }
+}
+
+async function handleStop(paths: ResolvedPaths, sessionId: string, deps: HandleHookDeps): Promise<void> {
+  const { replayPrompt } = await import("./replay.ts");
+  const { buildClaudeRecord } = await import("./record.ts");
+  const { JsonlWorkLog } = await import("kankaku/hub");
+
+  const events = readEventLog(paths.eventsFile);
+  const beforeStopTs = events.length >= 2 ? events[events.length - 2]!.ts : events[events.length - 1]?.ts ?? deps.now();
+
+  const deadline = deps.now() + STOP_COST_WAIT_MAX_MS;
+  let cost = readCost(deps.env, sessionId);
+  while ((!cost || cost.updatedAt < beforeStopTs) && deps.now() < deadline) {
+    await deps.sleep(STOP_COST_WAIT_POLL_MS);
+    cost = readCost(deps.env, sessionId);
+  }
+
+  const prompts = splitPrompts(events);
+  const last: PromptEvents | undefined = prompts[prompts.length - 1];
+  const state = readState(paths.stateFile);
+  if (!last || !state) {
+    if (!state) deps.stderr(`kankaku: no session state at Stop for ${sessionId}`);
+    return;
+  }
+
+  const costAtStart = state.promptOpen?.costAtStart;
+  const totalUsd = cost?.totalUsd;
+  const costDelta =
+    typeof costAtStart === "number" && typeof totalUsd === "number"
+      ? Math.max(0, Math.round((totalUsd - costAtStart) * 1e6) / 1e6) // micro-dollars: no binary float noise in the record
+      : undefined;
+
+  const core = replayPrompt(last, { cost: costDelta });
+  if (core) {
+    const record = buildClaudeRecord(core, state, sessionId, cost?.model);
+    const log = deps.log ?? new JsonlWorkLog(paths.kankakuDir);
+    log.append(record);
+  }
+
+  writeState(paths.stateFile, { ...state, promptOpen: null, permissionOpen: null });
+  const keep = events.slice(0, events.length - last.events.length);
+  dropSettledPrompts(paths.eventsFile, keep);
+}
+
+async function handleSessionStart(
+  paths: ResolvedPaths,
+  sessionId: string,
+  cwd: string,
+  source: string,
+  ts: number,
+  deps: HandleHookDeps,
+): Promise<void> {
+  if (source !== "compact") {
+    const { recoverStaleSessions } = await import("./inflight-recovery.ts");
+    const { JsonlWorkLog } = await import("kankaku/hub");
+    const recovered = recoverStaleSessions({
+      claudeDir: paths.claudeDir,
+      currentSessionId: sessionId,
+      isAlive: deps.isAlive,
+      now: deps.now(),
+      env: deps.env,
+    });
+    if (recovered.length > 0) {
+      const log = deps.log ?? new JsonlWorkLog(paths.kankakuDir);
+      for (const record of recovered) log.append(record);
+    }
+    sweepStaleCostFiles(deps.env, { now: deps.now() });
+  }
+
+  const existing = readState(paths.stateFile);
+  if (existing) return; // resume/fork on an existing state: keep it as-is
+
+  const pid = resolveClaudePid({ startPid: process.ppid, runPs: deps.runPs });
+  const resolvedInfo = deps.runPs(pid);
+  const parentPid = resolvedInfo?.ppid ?? process.ppid;
+
+  const state: SessionState = {
+    pid,
+    parentPid,
+    cwd,
+    startedAt: ts,
+    promptOpen: null,
+    permissionOpen: null,
+  };
+  writeState(paths.stateFile, state);
+}
+
+async function handleSessionEnd(paths: ResolvedPaths, sessionId: string, ts: number, deps: HandleHookDeps): Promise<void> {
+  const state = readState(paths.stateFile);
+  if (state?.promptOpen) {
+    const { replayPrompt } = await import("./replay.ts");
+    const { buildClaudeRecord } = await import("./record.ts");
+    const { JsonlWorkLog } = await import("kankaku/hub");
+    const events = readEventLog(paths.eventsFile);
+    const prompts = splitPrompts(events);
+    const last = prompts[prompts.length - 1];
+    if (last) {
+      const core = replayPrompt(last, { settledAt: ts });
+      if (core) {
+        const model = readCost(deps.env, sessionId)?.model;
+        const record = buildClaudeRecord(core, state, sessionId, model);
+        const log = deps.log ?? new JsonlWorkLog(paths.kankakuDir);
+        log.append(record);
+      }
+    }
+  }
+  deleteSessionFiles(paths);
+  deleteCost(deps.env, sessionId);
+}
+
+function deleteSessionFiles(paths: ResolvedPaths): void {
+  for (const file of [paths.stateFile, paths.eventsFile]) {
+    try {
+      unlinkSync(file);
+    } catch {
+      // already gone
+    }
+  }
+}
+
+function clearPermissionOpen(stateFile: string): void {
+  const state = readState(stateFile);
+  if (!state || state.permissionOpen === null) return;
+  writeState(stateFile, { ...state, permissionOpen: null });
+}
+
+interface CommonHookFields {
+  sessionId: string;
+  cwd: string;
+  hookEventName: string;
+  raw: Record<string, unknown>;
+}
+
+function parseCommon(input: unknown): CommonHookFields | undefined {
+  if (!isPlainObject(input)) return undefined;
+  const sessionId = readString(input.session_id);
+  const cwd = readString(input.cwd);
+  const hookEventName = readString(input.hook_event_name);
+  if (!sessionId || !cwd || !hookEventName) return undefined;
+  return { sessionId, cwd, hookEventName, raw: input };
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}

package/src/hook.ts

@@ -0,0 +1,41 @@
+import { handleHook } from "./handle-hook.ts";
+import { isAlive, runPsProcess } from "./claude-pid.ts";
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function main(): Promise<void> {
+  const text = await readStdin();
+  let input: unknown;
+  try {
+    input = JSON.parse(text);
+  } catch (error) {
+    process.stderr.write(`kankaku: could not parse hook input: ${String(error)}\n`);
+    return;
+  }
+  await handleHook(input, {
+    env: process.env,
+    now: () => Date.now(),
+    sleep,
+    isAlive,
+    runPs: runPsProcess,
+    stderr: (message) => process.stderr.write(`${message}\n`),
+  });
+}
+
+main()
+  .catch((error) => {
+    process.stderr.write(`kankaku: ${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+  })
+  .finally(() => {
+    process.exit(0);
+  });