kankaku-claude 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -8,6 +8,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- `/kankaku:sync-status` and `/kankaku:sync-all` slash commands for local
+  sync state inspection and full hub sync, respectively.
+
 - Phase 1: per-prompt work records from Claude Code hooks. Writes one
   `WorkRecord` per user prompt to `<KANKAKU_DIR>/worklog.jsonl`, in the same
   schema the kankaku pi extension writes, so kankaku's existing
@@ -28,8 +31,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
     `/kankaku:status`, `/kankaku:setup` slash commands.
 
 - Manual hub sync via `node src/cli.ts sync [all|status]` and the
-  `/kankaku:sync` slash command (default sync only). No automatic sync hooks;
-  prompts are omitted by default.
+  `/kankaku:sync` slash command (default sync only). Prompts are omitted by default.
+- Best-effort automatic hub sync on `SessionStart`, `Stop`, and `SessionEnd`;
+  disabled with `KANKAKU_SYNC_AUTO=0`. Missing credentials and sync failures
+  never block local records or cleanup.
 
 ### Fixed
 

package/README.md

@@ -20,7 +20,7 @@ Records are written in kankaku's own `WorkRecord` schema
 (`WORK_RECORD_SCHEMA = 1`), the exact one the kankaku pi extension writes to
 its own `worklog.jsonl`. This means kankaku's existing report and export
 tooling can read this plugin's worklog unchanged. kankaku-claude also exposes
-manual hub sync through kankaku's public hub adapters (below).
+manual and best-effort automatic hub sync through kankaku's public hub adapters (below).
 
 ## Requirements
 
@@ -85,8 +85,11 @@ anything behind in whatever project happens to be open.
   and the last cost the statusline reported (wraps `node src/cli.ts status`).
 - `/kankaku:setup` — prints the `statusLine` snippet described above (wraps
   `node src/cli.ts setup`).
-- `/kankaku:sync` — manually syncs local work records to the hub (wraps
-  `node src/cli.ts sync`; the slash command does not forward arguments).
+- `/kankaku:sync` — manually syncs recent local work records to the hub
+  (wraps `node src/cli.ts sync`; the slash command does not forward arguments).
+- `/kankaku:sync-status` — inspects local pending counts and sync state
+  (wraps `node src/cli.ts sync status`; no hub request or credentials required).
+- `/kankaku:sync-all` — requests a full sync (wraps `node src/cli.ts sync all`).
 
 The report, status, and setup subcommands are also available directly via
 `node src/cli.ts <report|status|setup>`; `report` accepts `--days N` and
@@ -96,9 +99,10 @@ defaults to the last 7 days.
 
 Configure hub credentials with `KANKAKU_PB_URL`, `KANKAKU_PB_EMAIL`, and
 `KANKAKU_PB_PASSWORD`, or use `~/.kankaku/credentials.json` (the shared
-kankaku hub credential file). Then run `/kankaku:sync` or
-`node src/cli.ts sync` in the project whose worklog you want to upload.
-For options not forwarded by the slash command, use the CLI directly:
+kankaku hub credential file). Then run `/kankaku:sync` for recent records or
+`/kankaku:sync-all` for a full sync in the project whose worklog you want to
+upload. Use `/kankaku:sync-status` to inspect local sync state without a hub
+request or credentials. The same operations are available directly via CLI:
 
 | Command | Purpose |
 |---------|---------|
@@ -114,8 +118,19 @@ Optional environment settings:
 | `KANKAKU_SYNC_PROMPT` | Prompt privacy: omitted by default; set `truncated` or `full` to include prompts. |
 | `KANKAKU_SYNC_WINDOW_HOURS` | Recent sync window in hours (defaults to 24). |
 | `KANKAKU_SYNC_RECORDS` | Set to `0` to disable uploading raw `work_records` children; consolidated `task_entries` still sync. |
+| `KANKAKU_SYNC_AUTO` | Set to `0` to disable automatic sync; manual sync remains available. |
+| `KANKAKU_SYNC_MIN_INTERVAL_MINUTES` | Minimum interval between automatic per-prompt attempts (defaults to 5; `0` disables throttling). |
 
-This first slice is **manual-only**: no automatic sync hooks run yet.
+### Automatic hub sync
+
+With valid hub credentials, heavy hooks attempt a best-effort sync at session start
+(after recovery), after each settled prompt has been appended, and on session end
+(after any interrupted record is appended, before cleanup). Missing/invalid
+credentials silently skip automatic sync. Failures are reported on stderr but
+never prevent local worklog writes or session cleanup. Prompt privacy, machine,
+window, and record settings above apply to both manual and automatic sync.
+Automatic runs use kankaku's change detection and per-prompt throttle; session
+boundaries are not throttled. Set `KANKAKU_SYNC_AUTO=0` to opt out.
 
 ## Where the files live
 
@@ -170,9 +185,9 @@ also runs for the current session's own leftover state at `SessionEnd`.
   document a link between a `SubagentStart`/`SubagentStop` pair and the
   `tool_use_id` that launched it, so kankaku-claude cannot join them; the
   subagent's own time is not separately measured here.
-- **Hub sync is manual-only.** Use `/kankaku:sync` or the direct CLI as
-  described above; no automatic sync hooks run yet. Prompts are omitted
-  from uploads unless `KANKAKU_SYNC_PROMPT` is `truncated` or `full`.
+- **Hub sync is best-effort.** Use `/kankaku:sync` to retry recent records or
+  `/kankaku:sync-all` to request a full sync. Prompts are omitted from uploads
+  unless `KANKAKU_SYNC_PROMPT` is `truncated` or `full`.
 
 See [kankaku.io](https://kankaku.io) for the pi extension this plugin shares
 its worklog format with.

package/commands/sync-all.md

@@ -0,0 +1,9 @@
+---
+description: Request a full sync of local kankaku work records to the hub
+allowed-tools: Bash(node:*)
+---
+
+Run the kankaku CLI sync all command and show its output to the user verbatim,
+inside a code block, with no summarizing or reformatting:
+
+!node "${CLAUDE_PLUGIN_ROOT}/src/cli.ts" sync all

package/commands/sync-status.md

@@ -0,0 +1,9 @@
+---
+description: Show local kankaku hub sync status
+allowed-tools: Bash(node:*)
+---
+
+Run the kankaku CLI sync status command and show its output to the user verbatim,
+inside a code block, with no summarizing or reformatting:
+
+!node "${CLAUDE_PLUGIN_ROOT}/src/cli.ts" sync status

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku-claude",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Claude Code plugin that records how long the agent works on each user prompt, in kankaku's worklog format.",
   "type": "module",
   "files": [

package/src/auto-sync.ts

@@ -0,0 +1,32 @@
+import type { SyncTrigger } from "kankaku/hub";
+import type { SyncCliDeps } from "./sync-cli.ts";
+
+export interface AutoSyncDeps extends SyncCliDeps {
+  stderr: (message: string) => void;
+}
+
+/** Best-effort heavy-hook sync; credential/transport errors never escape into record handling. */
+export async function autoSync(trigger: SyncTrigger, deps: AutoSyncDeps): Promise<void> {
+  if (deps.env.KANKAKU_SYNC_AUTO === "0") return;
+  try {
+    const { resolveHubCredentials } = await import("kankaku/hub");
+    const { homedir } = await import("node:os");
+    const hub = resolveHubCredentials({ env: deps.env, homeDir: deps.homeDir ?? (() => deps.env.HOME || homedir()) });
+    if (!hub.credentials || hub.invalidReason) return;
+    const { syncConfigured } = await import("./sync-cli.ts");
+    // One deadline across catalog and upload requests; the public client also
+    // imposes its own per-request timeout. No timer persists after the hook.
+    const deadline = AbortSignal.timeout(8_000);
+    const doFetch = deps.fetch ?? fetch;
+    const boundedFetch: typeof fetch = (input, init) => doFetch(input, {
+      ...init,
+      signal: init?.signal ? AbortSignal.any([init.signal, deadline]) : deadline,
+    });
+    const result = await syncConfigured({ ...deps, fetch: boundedFetch }, hub.credentials, { trigger });
+    if (result.error || result.failed.length) {
+      deps.stderr(`kankaku auto-sync: ${result.error ?? result.failed.map((f) => f.reason).join("; ")}`);
+    }
+  } catch (error) {
+    deps.stderr(`kankaku auto-sync: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}

package/src/handle-hook.ts

@@ -7,6 +7,7 @@ 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";
+import type { SyncTrigger } from "kankaku/hub";
 
 export interface HandleHookDeps {
   env: NodeJS.ProcessEnv;
@@ -18,6 +19,8 @@ export interface HandleHookDeps {
   isAlive: (pid: number) => boolean;
   runPs: (pid: number) => PsInfo | undefined;
   stderr: (message: string) => void;
+  /** Optional heavy-hook seam for tests. */
+  autoSync?: (trigger: SyncTrigger) => Promise<void>;
 }
 
 const STOP_COST_WAIT_POLL_MS = 100;
@@ -118,7 +121,7 @@ export async function handleHook(input: unknown, deps: HandleHookDeps): Promise<
     case "SessionEnd": {
       const reason = readString(raw.reason) ?? "other";
       appendEvent(paths.eventsFile, { ts, event: "SessionEnd", reason });
-      await handleSessionEnd(paths, sessionId, ts, deps);
+      await handleSessionEnd(paths, sessionId, cwd, ts, deps);
       return;
     }
     default:
@@ -166,6 +169,7 @@ async function handleStop(paths: ResolvedPaths, sessionId: string, deps: HandleH
   writeState(paths.stateFile, { ...state, promptOpen: null, permissionOpen: null });
   const keep = events.slice(0, events.length - last.events.length);
   dropSettledPrompts(paths.eventsFile, keep);
+  if (core) await syncHeavy("agent_settled", state.cwd, deps);
 }
 
 async function handleSessionStart(
@@ -194,7 +198,10 @@ async function handleSessionStart(
   }
 
   const existing = readState(paths.stateFile);
-  if (existing) return; // resume/fork on an existing state: keep it as-is
+  if (existing) {
+    await syncHeavy("session_start", cwd, deps);
+    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);
@@ -209,9 +216,10 @@ async function handleSessionStart(
     permissionOpen: null,
   };
   writeState(paths.stateFile, state);
+  await syncHeavy("session_start", cwd, deps);
 }
 
-async function handleSessionEnd(paths: ResolvedPaths, sessionId: string, ts: number, deps: HandleHookDeps): Promise<void> {
+async function handleSessionEnd(paths: ResolvedPaths, sessionId: string, cwd: string, ts: number, deps: HandleHookDeps): Promise<void> {
   const state = readState(paths.stateFile);
   if (state?.promptOpen) {
     const { replayPrompt } = await import("./replay.ts");
@@ -230,8 +238,24 @@ async function handleSessionEnd(paths: ResolvedPaths, sessionId: string, ts: num
       }
     }
   }
-  deleteSessionFiles(paths);
-  deleteCost(deps.env, sessionId);
+  try {
+    await syncHeavy("session_shutdown", state?.cwd ?? cwd, deps);
+  } finally {
+    deleteSessionFiles(paths);
+    deleteCost(deps.env, sessionId);
+  }
+}
+
+async function syncHeavy(trigger: SyncTrigger, cwd: string, deps: HandleHookDeps): Promise<void> {
+  try {
+    if (deps.autoSync) await deps.autoSync(trigger);
+    else {
+      const { autoSync } = await import("./auto-sync.ts");
+      await autoSync(trigger, { env: deps.env, cwd, now: deps.now, stderr: deps.stderr });
+    }
+  } catch (error) {
+    deps.stderr(`kankaku auto-sync: ${error instanceof Error ? error.message : String(error)}`);
+  }
 }
 
 function deleteSessionFiles(paths: ResolvedPaths): void {

package/src/sync-cli.ts

@@ -7,8 +7,10 @@ import {
   computeSyncStatus, createPocketBaseCatalogFetcher, resolveHubCredentials,
   runSync, safeHomeDir,
 } from "kankaku/hub";
+import type { SyncTrigger } from "kankaku/hub";
 import { resolveKankakuDir } from "./paths.ts";
 import type { CliResult } from "./cli-core.ts";
+import type { WorkSink } from "kankaku/ports";
 
 export interface SyncCliDeps {
   env: NodeJS.ProcessEnv;
@@ -66,26 +68,7 @@ export async function runSyncCli(args: string[], deps: SyncCliDeps): Promise<Cli
     if (hub.invalidReason) return { stdout: "", stderr: `kankaku sync: invalid hub URL: ${hub.invalidReason}\n`, exitCode: 1 };
     if (!hub.credentials) return { stdout: "", stderr: "kankaku sync: hub credentials are not configured (KANKAKU_PB_URL, KANKAKU_PB_EMAIL, KANKAKU_PB_PASSWORD).\n", exitCode: 1 };
 
-    const credentials = hub.credentials;
-    const client = new PocketBaseClient({ ...credentials, ...(deps.fetch ? { fetch: deps.fetch } : {}) });
-    const catalog = new CachedCatalog({
-      filePath: join(safeHomeDir(homeDir) ?? tmpdir(), ".kankaku", "catalog.json"),
-      url: credentials.url,
-      clock: { now: deps.now },
-      fetchCatalog: createPocketBaseCatalogFetcher(client),
-    });
-    // Refresh before resolving assignments; on an offline hub the cached snapshot remains usable.
-    await catalog.refresh();
-    const snapshot = catalog.read();
-    const sink = new PocketBaseSink({
-      client, clients: snapshot?.clients ?? [], projects: snapshot?.projects ?? [],
-      machine: deps.env.KANKAKU_MACHINE || (deps.hostname ?? hostname)(),
-      promptMode: promptMode(deps.env), syncRecords: deps.env.KANKAKU_SYNC_RECORDS !== "0",
-      agent: "claude-code", plugin: "kankaku-claude", pluginVersion: packageVersion(),
-    });
-    const summary = await runSync({
-      log, sink, stateStore, clock: { now: deps.now }, target: credentials.url, windowHours: hours,
-    }, { full: args[0] === "all" });
+    const summary = await syncConfigured(deps, hub.credentials, { full: args[0] === "all" });
     const stdout = `uploaded: ${summary.uploaded}, updated: ${summary.updated}, skipped: ${summary.skipped}, failed: ${summary.failed.length}\n`;
     if (summary.locked) return { stdout, stderr: "kankaku sync: another sync is running.\n", exitCode: 1 };
     if (summary.error || summary.failed.length) {
@@ -97,3 +80,43 @@ export async function runSyncCli(args: string[], deps: SyncCliDeps): Promise<Cli
     return { stdout: "", stderr: `kankaku sync: ${error instanceof Error ? error.message : String(error)}\n`, exitCode: 1 };
   }
 }
+
+/** Shared manual/automatic hub adapters and Claude attribution. */
+export async function syncConfigured(
+  deps: SyncCliDeps,
+  credentials: NonNullable<ReturnType<typeof resolveHubCredentials>["credentials"]>,
+  options: { full?: boolean; trigger?: SyncTrigger } = {},
+) {
+    const homeDir = deps.homeDir ?? (() => deps.env.HOME || homedir());
+    const dir = resolveKankakuDir(deps.env.KANKAKU_DIR ?? ".kankaku", deps.cwd);
+    const log = new JsonlWorkLog(dir);
+    const stateStore = new SyncStateStore({ dir, pid: process.pid, now: deps.now });
+    // Build the catalog only after runSync's unchanged-log and throttle gates.
+    // The public runner still owns locking, planning and the sync watermark.
+    const sink: WorkSink = { push: async (tasks) => {
+      if (tasks.length === 0) return [];
+      const client = new PocketBaseClient({ ...credentials, ...(deps.fetch ? { fetch: deps.fetch } : {}) });
+      const catalog = new CachedCatalog({
+        filePath: join(safeHomeDir(homeDir) ?? tmpdir(), ".kankaku", "catalog.json"),
+        url: credentials.url,
+        clock: { now: deps.now },
+        fetchCatalog: createPocketBaseCatalogFetcher(client),
+      });
+      // On an offline hub the cached snapshot remains usable.
+      await catalog.refresh();
+      const snapshot = catalog.read();
+      return new PocketBaseSink({
+        client, clients: snapshot?.clients ?? [], projects: snapshot?.projects ?? [],
+        machine: deps.env.KANKAKU_MACHINE || (deps.hostname ?? hostname)(),
+        promptMode: promptMode(deps.env), syncRecords: deps.env.KANKAKU_SYNC_RECORDS !== "0",
+        agent: "claude-code", plugin: "kankaku-claude", pluginVersion: packageVersion(),
+      }).push(tasks);
+    } };
+    const interval = Number(deps.env.KANKAKU_SYNC_MIN_INTERVAL_MINUTES);
+    const minAutoIntervalMs = deps.env.KANKAKU_SYNC_MIN_INTERVAL_MINUTES !== undefined && Number.isFinite(interval) && interval >= 0
+      ? interval * 60_000 : undefined;
+    return runSync({
+      log, sink, stateStore, clock: { now: deps.now }, target: credentials.url,
+      windowHours: windowHours(deps.env), ...(minAutoIntervalMs !== undefined ? { minAutoIntervalMs } : {}),
+    }, options);
+}