kankaku 0.6.5 → 0.7.1

package/README.md

@@ -41,6 +41,37 @@ trusted, which a subagent child may not inherit.
 
 To try it without installing: `pi -e /absolute/path/to/kankaku`.
 
+## Quick start
+
+Once installed, kankaku records every prompt on its own; there is nothing
+to start. Inside pi's TUI, type `/kankaku` to open the panel, the one
+place everything is managed from:
+
+```
+╭─ >_ kankaku ─────────────────────────────────────────╮
+│                                                      │
+│ → Target        Billing client, project, hub task    │
+│   Report        Today/all totals, tasks, sessions    │
+│   Sync          Status, sync now, sync all, backfill │
+│   Export        Write today's or every task as csv   │
+│   Doctor        Orphan/uncertain subagent counts     │
+│   About         Versions, KANKAKU_DIR, hub URL       │
+│                                                      │
+│ ↑↓ move · enter open · esc close                     │
+╰──────────────────────────────────────────────────────╯
+```
+
+- **Target** is where you pick the client and project the time is billed
+  to and, with a hub, the task you are working on right now.
+- **Report** shows today's work, waiting and cost, per task or grouped by
+  client or project.
+- **Sync** pushes the consolidated tasks to your hub when one is configured.
+
+Every panel action is also a subcommand (`/kankaku tasks`, `/kankaku sync`,
+…) for scripts and headless runs — see "The `/kankaku` command" below. The
+footer clock (`🕒 03:12 · acme`) shows the running prompt's elapsed time
+and billing client while an agent works.
+
 ## Record schema
 
 Each line in `worklog.jsonl` is one JSON object:
@@ -687,17 +718,53 @@ the future, this is the signal that would surface it.
 
 ## The `/kankaku` command
 
-Run `/kankaku` inside pi to see today's totals (work, waiting, record count)
-per role, plus a union-based tasks segment. Each totals line also shows
-`cache hit NN%` when tokens were recorded: the share of prompt input tokens
-served from the provider's prompt cache, cache reads over input plus cache
-reads plus cache writes; the segment is omitted, not shown as `0%`, when no
-tokens were recorded. In the interactive TUI the report
-is appended to the chat transcript as a durable card that is never sent to
-the LLM; without a UI (print or RPC mode) it falls back to a notification.
-Arguments are whitespace-separated and order-insensitive:
-
-- `/kankaku` — today's role totals and tasks segment, each with its estimated cost.
+`/kankaku` with no arguments, run inside pi's TUI, opens an overlay panel
+modelled on pi's own `/settings` (the same pi-tui `SettingsList`/
+`SelectList` widgets, the same keys) from which every kankaku view and
+action is reachable:
+
+- **Target** — billing client, project, hub task, and the legacy label
+  (see "Billing labels" and "Hub (PocketBase)" below). The Task row lists
+  the open/doing hub tasks of the current project; picking one links the
+  session, exactly like `/kankaku task pick` below — **session-only**,
+  never persisted (see "Linking to a hub task").
+- **Report** — today/all totals, tasks, sessions, clients, and projects:
+  the same five views `/kankaku`'s subcommands produce.
+- **Sync** (hub only) — status, sync now, sync all, backfill, and a
+  catalog refresh.
+- **Export** — write today's or every task as csv/json.
+- **Doctor** — orphan/uncertain subagent counts and ancestor-detection
+  availability.
+- **About** — versions, the resolved `KANKAKU_DIR`, the hub URL, and every
+  env-only setting, read-only.
+
+Keys: `↑↓` move, `Enter` open a section or select a value, `Esc` or `←` go
+back (or close the panel at the root), `q` close from anywhere. Mouse: the
+footer hints and list rows are clickable, but only in pi's fullscreen
+mode — pi does not dispatch mouse events in its regular (non-fullscreen)
+mode, so there the panel is keyboard-only.
+
+Every subcommand below is unchanged, and is exactly what headless (print
+or RPC) mode still uses — `/kankaku` there keeps showing today's totals
+directly, never the panel, since there is no UI to open one in. Run
+`/kankaku <subcommand>` (with arguments) in the TUI to skip the panel and
+go straight to that subcommand's output, exactly as before the panel
+existed.
+
+Plain `/kankaku` (headless, or any subcommand below) shows today's totals
+(work, waiting, record count) per role, plus a union-based tasks segment.
+Each totals line also shows `cache hit NN%` when tokens were recorded: the
+share of prompt input tokens served from the provider's prompt cache, cache
+reads over input plus cache reads plus cache writes; the segment is
+omitted, not shown as `0%`, when no tokens were recorded. In the
+interactive TUI the report is appended to the chat transcript as a durable
+card that is never sent to the LLM; without a UI (print or RPC mode) it
+falls back to a notification. Arguments are whitespace-separated and
+order-insensitive:
+
+- `/kankaku` (headless only — the TUI opens the panel instead, whose
+  Report screen defaults to the same view) — today's role totals and
+  tasks segment, each with its estimated cost.
 - `/kankaku all` — same, but across every record.
 - `/kankaku tasks` — one line per task (time, union wall/work, cost,
   subagent count, truncated prompt) for the **current pi session**. Add `all` for
@@ -834,6 +901,12 @@ task view exposes it from the orchestrator record only.
 The status bar shows `💼 <client> · <project>` (or just `💼 <client>` without
 a project) in place of the legacy client label, both idle and during a run.
 
+Mid-session, the `/kankaku` panel's Target screen (see "The `/kankaku`
+command" above) is the interactive way to change the client or project
+without going through `/kankaku target pick`'s picker dialog — it edits the
+same session-level target, applies through the same `SessionTarget`, and
+has its own "Remember" row for `<KANKAKU_DIR>/config.json`.
+
 ### Linking to a hub task
 
 `/kankaku task` (or `/kankaku task pick`) links the current session to one
@@ -861,6 +934,12 @@ the task view exposes it from the orchestrator record only, and
 `formatWorkTargetLabel` appends it to the status-bar/report label as
 `<client> · <project> › <task title>`.
 
+The `/kankaku` panel's Target screen's Task row is the interactive
+equivalent of `/kankaku task pick`/`clear`: it lists the same open/doing
+tasks, applies the link through the same `SessionTarget.setTask`, and
+stays just as session-only — picking a task there is never persisted to
+`config.json` either.
+
 ### Caching and offline behaviour
 
 The catalog (clients/projects) is cached machine-wide at

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku",
-  "version": "0.6.5",
+  "version": "0.7.1",
   "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/hub-actions.ts

@@ -0,0 +1,83 @@
+/**
+ * Shared line-building for the hub-facing `/kankaku` subcommands (`sync`,
+ * `sync all`, `sync status`, `backfill`, `catalog refresh`) and the panel's
+ * `sync`/`export` screens (`adapters/panel/screens/sync.ts`), extracted from
+ * `kankaku-command.ts` so the subcommands and the panel can never drift —
+ * see odd/tasks/kankaku-panel.md P4.
+ */
+import type { CatalogSnapshot } from "../ports/catalog.ts";
+import type { SyncCommandDeps } from "./kankaku-command.ts";
+import type { SyncSummary } from "./sync-runner.ts";
+
+/**
+ * `/kankaku sync status`'s report lines: the watermark, the pending count,
+ * how many tasks fell outside this run's revisit window (R3), and the last
+ * error, when any. Exact body of `handleSyncCommand`'s `status` branch.
+ */
+export function buildSyncStatusLines(status: ReturnType<SyncCommandDeps["status"]>): string[] {
+  const { state, pending, staleOutsideWindow } = status;
+  const lines = [state?.syncedThrough ? `synced through ${state.syncedThrough}` : "never synced", `pending: ${pending}`];
+  if (staleOutsideWindow > 0) {
+    lines.push(`${staleOutsideWindow} task(s) never synced fall outside the sync window — run '/kankaku sync all' to upload them`);
+  }
+  if (state?.lastError) lines.push(`last error: ${state.lastError.message} (at ${state.lastError.at})`);
+  return lines;
+}
+
+/**
+ * Render a {@link SyncSummary} as report lines: counts, any stop reason, the
+ * new watermark, and the unassigned/failed breakdowns. Used by `/kankaku
+ * sync`/`sync all` and the panel's sync screen.
+ */
+export function formatSyncSummaryLines(summary: SyncSummary): string[] {
+  const lines = [`uploaded ${summary.uploaded}, updated ${summary.updated}, skipped ${summary.skipped}, failed ${summary.failed.length}`];
+
+  if (summary.locked) lines.push("another sync is already in progress; nothing was attempted");
+  if (summary.error) lines.push(`stopped early: ${summary.error}`);
+  if (summary.syncedThrough) lines.push(`synced through ${summary.syncedThrough}`);
+
+  const unassignedEntries = Object.entries(summary.unassigned).sort(([a], [b]) => a.localeCompare(b));
+  if (unassignedEntries.length > 0) {
+    lines.push("unassigned (Sin determinar):");
+    for (const [label, count] of unassignedEntries) lines.push(`  ${label}: ${count}`);
+  }
+
+  if (summary.failed.length > 0) {
+    lines.push("failed:");
+    for (const entry of summary.failed) lines.push(`  ${entry.id}: ${entry.reason}`);
+  }
+
+  return lines;
+}
+
+/**
+ * `/kankaku backfill`'s report lines: tasks routed to Sin determinar this
+ * run, grouped by their old free-text label, or "no unassigned tasks" when
+ * none were. Exact body of `handleBackfillCommand`.
+ */
+export function formatBackfillLines(summary: SyncSummary): string[] {
+  const unassignedEntries = Object.entries(summary.unassigned).sort(([a], [b]) => a.localeCompare(b));
+
+  const lines =
+    unassignedEntries.length > 0
+      ? [
+          ...unassignedEntries.map(([label, count]) => `${label}: ${count} task(s) -> Sin determinar`),
+          "reassign these in the hub web app's unassigned queue",
+        ]
+      : ["no unassigned tasks"];
+
+  if (summary.error) lines.push(`stopped early: ${summary.error}`);
+  return lines;
+}
+
+/**
+ * `/kankaku catalog refresh`'s report lines: client/project counts, or an
+ * unreachable notice when the refresh failed (`snapshot` is `undefined`).
+ * The subcommand still notifies that failure as an error rather than a
+ * report (see `handleCatalogCommand`); the panel's sync screen shows
+ * whatever this returns either way.
+ */
+export function formatCatalogRefreshLines(snapshot: CatalogSnapshot | undefined): string[] {
+  if (!snapshot) return ["hub unreachable; catalog not refreshed"];
+  return [`refreshed: ${snapshot.clients.length} client(s), ${snapshot.projects.length} project(s)`];
+}