kankaku-pi 1.0.0

package/dist/adapters/project-config.d.ts

@@ -0,0 +1,42 @@
+import type { WorkTargetCandidate } from "../domain/work-target.ts";
+/**
+ * Read the project's default billing client from `<dir>/config.json`
+ * (`{ "client": "acme" }`), the lowest-precedence source in
+ * `domain/client-label.ts#resolveClient`. `dir` is the kankaku dir (same
+ * directory as the work log).
+ *
+ * Tolerates a missing file, malformed JSON, a non-object document, or a
+ * `client` field that is not a string — all return `undefined` rather than
+ * throwing, since this file is optional and hand-edited.
+ */
+export declare function readProjectClient(dir: string): string | undefined;
+/** Reads the project client from a kankaku dir resolved lazily against `fallbackCwd()` at call time. */
+export declare class LazyProjectClientSource {
+    private readonly dirOrRelative;
+    private readonly fallbackCwd;
+    constructor(dirOrRelative: string, fallbackCwd?: () => string);
+    read(): string | undefined;
+}
+/**
+ * Read `clientId`/`projectId` from `<dir>/config.json`, the lowest-precedence
+ * source in `domain/work-target.ts#resolveWorkTarget`. Tolerates the same
+ * failure modes as {@link readProjectClient}. `undefined` when `clientId`
+ * is absent or not a string (a `projectId` without a `clientId` is not a
+ * valid candidate); a non-string `projectId` is dropped, keeping `clientId`.
+ */
+export declare function readProjectTargetIds(dir: string): WorkTargetCandidate | undefined;
+/**
+ * Merge `clientId`/`projectId` into `<dir>/config.json`, preserving every
+ * other existing key (including the legacy `client` label). Writes
+ * atomically (tmp + rename), mirroring `file-inflight-store.ts`. A missing
+ * or malformed existing file is treated as `{}` rather than failing.
+ */
+export declare function writeProjectTargetIds(dir: string, ids: WorkTargetCandidate): void;
+/** Reads target ids from a kankaku dir resolved lazily against `fallbackCwd()` at call time. */
+export declare class LazyProjectTargetSource {
+    private readonly dirOrRelative;
+    private readonly fallbackCwd;
+    constructor(dirOrRelative: string, fallbackCwd?: () => string);
+    read(): WorkTargetCandidate | undefined;
+    write(ids: WorkTargetCandidate): void;
+}

package/dist/adapters/project-config.js

@@ -0,0 +1,108 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveKankakuDir } from "./kankaku-dir.js";
+const CONFIG_FILE_NAME = "config.json";
+/**
+ * Read the project's default billing client from `<dir>/config.json`
+ * (`{ "client": "acme" }`), the lowest-precedence source in
+ * `domain/client-label.ts#resolveClient`. `dir` is the kankaku dir (same
+ * directory as the work log).
+ *
+ * Tolerates a missing file, malformed JSON, a non-object document, or a
+ * `client` field that is not a string — all return `undefined` rather than
+ * throwing, since this file is optional and hand-edited.
+ */
+export function readProjectClient(dir) {
+    const filePath = join(dir, CONFIG_FILE_NAME);
+    if (!existsSync(filePath))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return undefined;
+        const client = parsed["client"];
+        return typeof client === "string" ? client : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Reads the project client from a kankaku dir resolved lazily against `fallbackCwd()` at call time. */
+export class LazyProjectClientSource {
+    dirOrRelative;
+    fallbackCwd;
+    constructor(dirOrRelative, fallbackCwd = () => process.cwd()) {
+        this.dirOrRelative = dirOrRelative;
+        this.fallbackCwd = fallbackCwd;
+    }
+    read() {
+        return readProjectClient(resolveKankakuDir(this.dirOrRelative, this.fallbackCwd()));
+    }
+}
+/**
+ * Read `clientId`/`projectId` from `<dir>/config.json`, the lowest-precedence
+ * source in `domain/work-target.ts#resolveWorkTarget`. Tolerates the same
+ * failure modes as {@link readProjectClient}. `undefined` when `clientId`
+ * is absent or not a string (a `projectId` without a `clientId` is not a
+ * valid candidate); a non-string `projectId` is dropped, keeping `clientId`.
+ */
+export function readProjectTargetIds(dir) {
+    const filePath = join(dir, CONFIG_FILE_NAME);
+    if (!existsSync(filePath))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return undefined;
+        const record = parsed;
+        const clientId = record["clientId"];
+        if (typeof clientId !== "string")
+            return undefined;
+        const projectId = record["projectId"];
+        return typeof projectId === "string" ? { clientId, projectId } : { clientId };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Merge `clientId`/`projectId` into `<dir>/config.json`, preserving every
+ * other existing key (including the legacy `client` label). Writes
+ * atomically (tmp + rename), mirroring `file-inflight-store.ts`. A missing
+ * or malformed existing file is treated as `{}` rather than failing.
+ */
+export function writeProjectTargetIds(dir, ids) {
+    const filePath = join(dir, CONFIG_FILE_NAME);
+    let existing = {};
+    if (existsSync(filePath)) {
+        try {
+            const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                existing = parsed;
+            }
+        }
+        catch {
+            existing = {};
+        }
+    }
+    const merged = { ...existing, clientId: ids.clientId, ...(ids.projectId !== undefined ? { projectId: ids.projectId } : {}) };
+    mkdirSync(dir, { recursive: true });
+    const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(merged, null, 2));
+    renameSync(tmp, filePath);
+}
+/** Reads target ids from a kankaku dir resolved lazily against `fallbackCwd()` at call time. */
+export class LazyProjectTargetSource {
+    dirOrRelative;
+    fallbackCwd;
+    constructor(dirOrRelative, fallbackCwd = () => process.cwd()) {
+        this.dirOrRelative = dirOrRelative;
+        this.fallbackCwd = fallbackCwd;
+    }
+    read() {
+        return readProjectTargetIds(resolveKankakuDir(this.dirOrRelative, this.fallbackCwd()));
+    }
+    write(ids) {
+        writeProjectTargetIds(resolveKankakuDir(this.dirOrRelative, this.fallbackCwd()), ids);
+    }
+}

package/dist/adapters/report-data.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pi-free home for {@link KankakuReportData}, the shape every `/kankaku`
+ * report view and the panel's report screen produce. Extracted out of
+ * `kankaku-command.ts` (which still re-exports it) so `report-views.ts` can
+ * be published through `kankaku-pi/hub` without pulling in anything that
+ * touches `@earendil-works/*` — see AGENTS.md "Code conventions".
+ */
+/** Durable report rendered inside the chat transcript; never sent to the LLM. */
+export interface KankakuReportData {
+    title: string;
+    lines: string[];
+}

package/dist/adapters/report-data.js

@@ -0,0 +1,8 @@
+/**
+ * Pi-free home for {@link KankakuReportData}, the shape every `/kankaku`
+ * report view and the panel's report screen produce. Extracted out of
+ * `kankaku-command.ts` (which still re-exports it) so `report-views.ts` can
+ * be published through `kankaku-pi/hub` without pulling in anything that
+ * touches `@earendil-works/*` — see AGENTS.md "Code conventions".
+ */
+export {};

package/dist/adapters/report-views.d.ts

@@ -0,0 +1,45 @@
+import type { WorkRecord } from "../domain/work-record.ts";
+import type { KankakuReportData } from "./report-data.ts";
+/** Shared by every view except `buildTasksView`: `all` includes every day, otherwise only today's local day. */
+export interface ReportViewOptions {
+    all: boolean;
+}
+/** `buildTasksView`'s own options: `all` scopes to every session instead of local-day range (tasks are never day-filtered — see `kankaku-command.ts`'s original `tasks` handler). */
+export interface TasksViewOptions {
+    all: boolean;
+    sessionId: string | undefined;
+}
+/** The plain-text summary view (`/kankaku` with no view token): role/task totals, plus a one-line hint when uncertain records were excluded (SUBAGENT-REQ-017). */
+export declare function buildSummaryView(records: WorkRecord[], options: ReportViewOptions): KankakuReportData;
+/** `/kankaku clients [all]`: per-client totals. */
+export declare function buildClientsView(records: WorkRecord[], options: ReportViewOptions): KankakuReportData;
+/** `/kankaku projects [all]`: per-project totals. */
+export declare function buildProjectsView(records: WorkRecord[], options: ReportViewOptions): KankakuReportData;
+/** `/kankaku sessions [all]`: per-session totals. */
+export declare function buildSessionsView(records: WorkRecord[], options: ReportViewOptions): KankakuReportData;
+/**
+ * `/kankaku tasks [all]`: one line per task. Unlike every other view, tasks
+ * are never restricted by local day — `all` (or a missing `sessionId`)
+ * instead scopes from "this session" to "every session".
+ */
+export declare function buildTasksView(records: WorkRecord[], options: TasksViewOptions): KankakuReportData;
+/** {@link buildExportContent}'s options: `format` picks csv/json, `all` includes every day instead of just today's local day (mirrors every other view except `buildTasksView`). */
+export interface ExportContentOptions {
+    format: "csv" | "json";
+    all: boolean;
+}
+/**
+ * `/kankaku export [csv|json] [all]`'s file content: the flat export rows
+ * for today's (or every) task, rendered as csv or json, with the file name
+ * `/kankaku export` and the panel's export screen (`panel/screens/
+ * export.ts`) both use. Extracted from `kankaku-command.ts`'s
+ * `handleExportCommand` (see odd/tasks/kankaku-panel.md P4) so the
+ * subcommand and the panel never drift. `rowCount` is exposed only for the
+ * subcommand's "wrote N row(s) to <path>" confirmation line — the panel's
+ * own confirmation is simpler ("wrote <path>").
+ */
+export declare function buildExportContent(records: WorkRecord[], options: ExportContentOptions): {
+    name: string;
+    content: string;
+    rowCount: number;
+};

package/dist/adapters/report-views.js

@@ -0,0 +1,73 @@
+/**
+ * The five `/kankaku` report views (summary/tasks/sessions/clients/
+ * projects), each as one pure `WorkRecord[] -> KankakuReportData` builder.
+ * Extracted from `kankaku-command.ts`'s subcommand handlers (see
+ * odd/tasks/kankaku-panel.md P3) so the `/kankaku` subcommands and the
+ * panel's report screen (`panel/screens/report.ts`) always compute the
+ * exact same lines — neither ever re-implements the other's logic.
+ */
+import { buildSessions, buildTasks } from "../domain/task-view.js";
+import { exportRows, toCsv, toJson } from "../domain/export.js";
+import { countUncertain, formatClients, formatProjects, formatReport, formatSessions, formatTasks, localDay, summarize, summarizeByClient, summarizeByProject } from "./report.js";
+/** The plain-text summary view (`/kankaku` with no view token): role/task totals, plus a one-line hint when uncertain records were excluded (SUBAGENT-REQ-017). */
+export function buildSummaryView(records, options) {
+    const { all } = options;
+    const summary = summarize(records, { all });
+    const lines = formatReport(summary).split(" | ");
+    const uncertainCount = countUncertain(records, { all });
+    if (uncertainCount > 0) {
+        lines.push(`kankaku: ${uncertainCount} uncertain record(s) excluded from tasks — run /kankaku doctor`);
+    }
+    return { title: all ? "summary (all days)" : "summary (today)", lines };
+}
+/** `/kankaku clients [all]`: per-client totals. */
+export function buildClientsView(records, options) {
+    const { all } = options;
+    const today = localDay(new Date().toISOString());
+    const tasks = buildTasks(records).filter((task) => all || localDay(task.startedAt) === today);
+    return { title: all ? "clients (all days)" : "clients (today)", lines: formatClients(summarizeByClient(tasks)).split("\n") };
+}
+/** `/kankaku projects [all]`: per-project totals. */
+export function buildProjectsView(records, options) {
+    const { all } = options;
+    const today = localDay(new Date().toISOString());
+    const tasks = buildTasks(records).filter((task) => all || localDay(task.startedAt) === today);
+    return { title: all ? "projects (all days)" : "projects (today)", lines: formatProjects(summarizeByProject(tasks)).split("\n") };
+}
+/** `/kankaku sessions [all]`: per-session totals. */
+export function buildSessionsView(records, options) {
+    const { all } = options;
+    const today = localDay(new Date().toISOString());
+    const tasks = buildTasks(records).filter((task) => all || localDay(task.startedAt) === today);
+    return { title: all ? "sessions (all days)" : "sessions (today)", lines: formatSessions(buildSessions(tasks)).split("\n") };
+}
+/**
+ * `/kankaku tasks [all]`: one line per task. Unlike every other view, tasks
+ * are never restricted by local day — `all` (or a missing `sessionId`)
+ * instead scopes from "this session" to "every session".
+ */
+export function buildTasksView(records, options) {
+    const { all, sessionId } = options;
+    const scoped = all || !sessionId;
+    const tasks = buildTasks(records).filter((task) => scoped || task.sessionId === sessionId);
+    return { title: scoped ? "tasks (every session)" : "tasks (this session)", lines: formatTasks(tasks).split("\n") };
+}
+/**
+ * `/kankaku export [csv|json] [all]`'s file content: the flat export rows
+ * for today's (or every) task, rendered as csv or json, with the file name
+ * `/kankaku export` and the panel's export screen (`panel/screens/
+ * export.ts`) both use. Extracted from `kankaku-command.ts`'s
+ * `handleExportCommand` (see odd/tasks/kankaku-panel.md P4) so the
+ * subcommand and the panel never drift. `rowCount` is exposed only for the
+ * subcommand's "wrote N row(s) to <path>" confirmation line — the panel's
+ * own confirmation is simpler ("wrote <path>").
+ */
+export function buildExportContent(records, options) {
+    const { format, all } = options;
+    const today = localDay(new Date().toISOString());
+    const tasks = buildTasks(records).filter((task) => all || localDay(task.startedAt) === today);
+    const rows = exportRows(tasks);
+    const content = format === "json" ? toJson(rows) : toCsv(rows);
+    const name = `tasks-${all ? "all" : today}.${format}`;
+    return { name, content, rowCount: rows.length };
+}

package/dist/adapters/report.d.ts

@@ -0,0 +1,112 @@
+import type { SessionView, TaskView } from "../domain/task-view.ts";
+import type { WorkRecord, WorkRole } from "../domain/work-record.ts";
+export { localDay } from "../domain/day.ts";
+export interface RoleTotals {
+    workMs: number;
+    waitingMs: number;
+    wallMs: number;
+    count: number;
+    /** Estimated cost in USD, as priced by pi's model table. */
+    cost: number;
+    /** Prompt input tokens, summed across every record of this role. */
+    input: number;
+    /** Prompt-cache read tokens, summed across every record of this role. */
+    cacheRead: number;
+    /** Prompt-cache write tokens, summed across every record of this role. */
+    cacheWrite: number;
+    /** Per-tag total milliseconds summed across every record of this role. */
+    segments: Record<string, number>;
+}
+export interface TaskTotals {
+    count: number;
+    wallMs: number;
+    workMs: number;
+    /** Estimated cost in USD, orchestrator and subagents combined. */
+    cost: number;
+    /** Prompt input tokens, orchestrator and subagents combined. */
+    input: number;
+    /** Prompt-cache read tokens, orchestrator and subagents combined. */
+    cacheRead: number;
+    /** Prompt-cache write tokens, orchestrator and subagents combined. */
+    cacheWrite: number;
+    /** Per-tag total milliseconds summed across every task (orchestrator and subagents). */
+    segments: Record<string, number>;
+}
+export type Summary = Record<WorkRole, RoleTotals> & {
+    tasks: TaskTotals;
+};
+export interface SummarizeOptions {
+    /** Local day in `YYYY-MM-DD` format. Defaults to today when `all` is not set. */
+    day?: string;
+    /** Include every record regardless of day. */
+    all?: boolean;
+}
+/**
+ * Aggregate work records by role, restricted to one local day unless `all`
+ * is set. Also computes a `tasks` segment (union-based `wallMs`/`workMs`
+ * over one orchestrator run and its subagents) for tasks whose `startedAt`
+ * falls on the same day.
+ */
+export declare function summarize(records: WorkRecord[], options: SummarizeOptions): Summary;
+/**
+ * Count of `uncertain` records (ADR 0022) within the same day scope
+ * `summarize` uses, so the `/kankaku` report can surface a one-line hint
+ * when some records are silently excluded from the task count
+ * (SUBAGENT-REQ-017): an undercount must never be silent.
+ */
+export declare function countUncertain(records: WorkRecord[], options: SummarizeOptions): number;
+/** Render a short, human-readable summary for the `/kankaku` command. */
+export declare function formatReport(summary: Summary): string;
+/** Render one line per task: time, client (when present), union-based wall/work, cost, non-zero segment tags, subagent count, and a truncated prompt (`…` marks a cut). */
+export declare function formatTasks(tasks: TaskView[]): string;
+export interface ClientTotals {
+    wallMs: number;
+    waitingMs: number;
+    workMs: number;
+    /** Estimated cost in USD, summed across this client's tasks. */
+    cost: number;
+    /** Prompt input tokens, summed across this client's tasks. */
+    input: number;
+    /** Prompt-cache read tokens, summed across this client's tasks. */
+    cacheRead: number;
+    /** Prompt-cache write tokens, summed across this client's tasks. */
+    cacheWrite: number;
+    count: number;
+}
+/**
+ * Aggregate tasks by billing client (see `domain/client-label.ts`), summing
+ * work/waiting/wall time, cost, and task count. Tasks without a `client`
+ * are grouped under `"(none)"`. Returned as a `Map` rather than a plain
+ * object so an attacker-controlled client name can never repoint a
+ * prototype property.
+ */
+export declare function summarizeByClient(tasks: TaskView[]): Map<string, ClientTotals>;
+export interface ProjectTotals {
+    /** Display name: the project's `projectName`, or `"(no project)"` for the ungrouped bucket. */
+    name: string;
+    wallMs: number;
+    waitingMs: number;
+    workMs: number;
+    /** Estimated cost in USD, summed across this project's tasks. */
+    cost: number;
+    /** Prompt input tokens, summed across this project's tasks. */
+    input: number;
+    /** Prompt-cache read tokens, summed across this project's tasks. */
+    cacheRead: number;
+    /** Prompt-cache write tokens, summed across this project's tasks. */
+    cacheWrite: number;
+    count: number;
+}
+/**
+ * Aggregate tasks by hub project (see `domain/work-target.ts`), keyed by
+ * `projectId` (so two projects that happen to share a display name are
+ * never merged) with the name denormalised alongside for display. Tasks
+ * without a `projectId` are grouped under `"(no project)"`.
+ */
+export declare function summarizeByProject(tasks: TaskView[]): Map<string, ProjectTotals>;
+/** Render one line per project, sorted alphabetically by display name, with work/waiting/wall time, cost, and task count. */
+export declare function formatProjects(totals: Map<string, ProjectTotals>): string;
+/** Render one line per client, sorted alphabetically, with work/waiting/wall time, cost, and task count. */
+export declare function formatClients(totals: Map<string, ClientTotals>): string;
+/** Render one line per session: truncated id, time range, union-based wall/work, cost, non-zero segment tags, and task count. */
+export declare function formatSessions(sessions: SessionView[]): string;

package/dist/adapters/report.js

@@ -0,0 +1,236 @@
+import { buildTasks, uncertainRecords } from "../domain/task-view.js";
+import { localDay } from "../domain/day.js";
+import { cacheHitRatio, finiteOrZero } from "../domain/work-record.js";
+export { localDay } from "../domain/day.js";
+const ROLES = ["orchestrator", "subagent"];
+function emptyTotals() {
+    return { workMs: 0, waitingMs: 0, wallMs: 0, count: 0, cost: 0, input: 0, cacheRead: 0, cacheWrite: 0, segments: {} };
+}
+/**
+ * Add per-tag milliseconds from `segments` (missing on older records) into
+ * `into`, a `Map` rather than a plain object so a tag from a hand-edited
+ * worklog line named `__proto__` or `constructor` accumulates as a normal
+ * entry instead of silently reading (and arithmetically corrupting) an
+ * inherited `Object.prototype` value.
+ */
+function addSegments(into, segments) {
+    for (const [tag, ms] of Object.entries(segments ?? {})) {
+        into.set(tag, (into.get(tag) ?? 0) + ms);
+    }
+}
+/**
+ * Aggregate work records by role, restricted to one local day unless `all`
+ * is set. Also computes a `tasks` segment (union-based `wallMs`/`workMs`
+ * over one orchestrator run and its subagents) for tasks whose `startedAt`
+ * falls on the same day.
+ */
+export function summarize(records, options) {
+    const targetDay = options.all ? undefined : (options.day ?? localDay(new Date().toISOString()));
+    const summary = {
+        orchestrator: emptyTotals(),
+        subagent: emptyTotals(),
+        tasks: { count: 0, wallMs: 0, workMs: 0, cost: 0, input: 0, cacheRead: 0, cacheWrite: 0, segments: {} },
+    };
+    // Accumulated in Maps (see `addSegments`) and only converted to the
+    // returned plain objects at the very end, via `Object.fromEntries`.
+    const segmentsByRole = { orchestrator: new Map(), subagent: new Map() };
+    const taskSegments = new Map();
+    for (const record of records) {
+        if (targetDay !== undefined && localDay(record.startedAt) !== targetDay)
+            continue;
+        const totals = summary[record.role];
+        totals.workMs += record.workMs;
+        totals.waitingMs += record.waitingMs;
+        totals.wallMs += record.wallMs;
+        totals.count += 1;
+        totals.cost += finiteOrZero(record.usage.cost);
+        totals.input += finiteOrZero(record.usage.input);
+        totals.cacheRead += finiteOrZero(record.usage.cacheRead);
+        totals.cacheWrite += finiteOrZero(record.usage.cacheWrite);
+        addSegments(segmentsByRole[record.role], record.segments);
+    }
+    const tasks = buildTasks(records).filter((task) => targetDay === undefined || localDay(task.startedAt) === targetDay);
+    for (const task of tasks) {
+        summary.tasks.count += 1;
+        summary.tasks.wallMs += task.wallMs;
+        summary.tasks.workMs += task.workMs;
+        summary.tasks.cost += task.usage.cost;
+        summary.tasks.input += finiteOrZero(task.usage.input);
+        summary.tasks.cacheRead += finiteOrZero(task.usage.cacheRead);
+        summary.tasks.cacheWrite += finiteOrZero(task.usage.cacheWrite);
+        addSegments(taskSegments, task.segments);
+    }
+    summary.orchestrator.segments = Object.fromEntries(segmentsByRole.orchestrator);
+    summary.subagent.segments = Object.fromEntries(segmentsByRole.subagent);
+    summary.tasks.segments = Object.fromEntries(taskSegments);
+    return summary;
+}
+/**
+ * Count of `uncertain` records (ADR 0022) within the same day scope
+ * `summarize` uses, so the `/kankaku` report can surface a one-line hint
+ * when some records are silently excluded from the task count
+ * (SUBAGENT-REQ-017): an undercount must never be silent.
+ */
+export function countUncertain(records, options) {
+    const targetDay = options.all ? undefined : (options.day ?? localDay(new Date().toISOString()));
+    return uncertainRecords(records).filter((record) => targetDay === undefined || localDay(record.startedAt) === targetDay).length;
+}
+function formatMinutes(ms) {
+    const totalSeconds = Math.round(ms / 1000);
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    return `${minutes}m${String(seconds).padStart(2, "0")}s`;
+}
+/** Estimated USD cost with two decimals, e.g. `$1.23`. */
+function formatCost(cost) {
+    return `$${cost.toFixed(2)}`;
+}
+function formatTime(iso) {
+    const date = new Date(iso);
+    const hours = String(date.getHours()).padStart(2, "0");
+    const minutes = String(date.getMinutes()).padStart(2, "0");
+    return `${hours}:${minutes}`;
+}
+/** Render `cache hit NN%` (integer percent) for a usage totals triple, or `undefined` when the ratio is undefined (nothing recorded). */
+function formatCacheHit(usage) {
+    const ratio = cacheHitRatio(usage);
+    return ratio === undefined ? undefined : `cache hit ${Math.round(ratio * 100)}%`;
+}
+/** Render non-zero segment tags as `tag Xm00s` pairs, sorted alphabetically, joined by `, `. Undefined when none are non-zero. */
+function formatSegmentTags(segments) {
+    const tags = Object.keys(segments)
+        .filter((tag) => segments[tag] > 0)
+        .sort();
+    if (tags.length === 0)
+        return undefined;
+    return tags.map((tag) => `${tag} ${formatMinutes(segments[tag])}`).join(", ");
+}
+/** Render a short, human-readable summary for the `/kankaku` command. */
+export function formatReport(summary) {
+    const lines = ROLES.map((role) => {
+        const totals = summary[role];
+        const cacheHit = formatCacheHit(totals);
+        const cacheHitPart = cacheHit !== undefined ? `, ${cacheHit}` : "";
+        return `${role}: work ${formatMinutes(totals.workMs)}, waiting ${formatMinutes(totals.waitingMs)}, ${totals.count} record(s), ${formatCost(totals.cost)}${cacheHitPart}`;
+    });
+    const tasksCacheHit = formatCacheHit(summary.tasks);
+    const tasksCacheHitPart = tasksCacheHit !== undefined ? `, ${tasksCacheHit}` : "";
+    lines.push(`tasks: ${summary.tasks.count}, wall ${formatMinutes(summary.tasks.wallMs)}, work ${formatMinutes(summary.tasks.workMs)}, ${formatCost(summary.tasks.cost)}${tasksCacheHitPart}`);
+    const segmentTags = formatSegmentTags(summary.tasks.segments);
+    if (segmentTags !== undefined) {
+        lines.push(`segments: ${segmentTags}`);
+    }
+    return lines.join(" | ");
+}
+/** Maximum visible width of a task prompt before it is truncated with an ellipsis marker. */
+const PROMPT_DISPLAY_LIMIT = 60;
+/** Truncate `text` to `limit` visible characters, appending `…` (counted within the limit) when it was cut. */
+function truncateWithEllipsis(text, limit) {
+    return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+}
+/** Render one line per task: time, client (when present), union-based wall/work, cost, non-zero segment tags, subagent count, and a truncated prompt (`…` marks a cut). */
+export function formatTasks(tasks) {
+    if (tasks.length === 0)
+        return "no tasks";
+    return tasks
+        .map((task) => {
+        const prompt = truncateWithEllipsis(task.prompt, PROMPT_DISPLAY_LIMIT);
+        const segmentTags = formatSegmentTags(task.segments);
+        const segmentPart = segmentTags !== undefined ? `  ${segmentTags}` : "";
+        const clientPart = task.client !== undefined ? `  client:${task.client}` : "";
+        const cacheHit = formatCacheHit(task.usage);
+        const cacheHitPart = cacheHit !== undefined ? `  ${cacheHit}` : "";
+        return `${formatTime(task.startedAt)}${clientPart}  wall ${formatMinutes(task.wallMs)}  work ${formatMinutes(task.workMs)}  ${formatCost(task.usage.cost)}${cacheHitPart}${segmentPart}  subagents ${task.subagents.length}  ${prompt}`;
+    })
+        .join("\n");
+}
+/** Client name under which tasks without a resolved client are grouped. */
+const NO_CLIENT = "(none)";
+/**
+ * Aggregate tasks by billing client (see `domain/client-label.ts`), summing
+ * work/waiting/wall time, cost, and task count. Tasks without a `client`
+ * are grouped under `"(none)"`. Returned as a `Map` rather than a plain
+ * object so an attacker-controlled client name can never repoint a
+ * prototype property.
+ */
+export function summarizeByClient(tasks) {
+    const totals = new Map();
+    for (const task of tasks) {
+        const key = task.client ?? NO_CLIENT;
+        const entry = totals.get(key) ?? { wallMs: 0, waitingMs: 0, workMs: 0, cost: 0, input: 0, cacheRead: 0, cacheWrite: 0, count: 0 };
+        entry.wallMs += task.wallMs;
+        entry.waitingMs += task.waitingMs;
+        entry.workMs += task.workMs;
+        entry.cost += finiteOrZero(task.usage.cost);
+        entry.input += finiteOrZero(task.usage.input);
+        entry.cacheRead += finiteOrZero(task.usage.cacheRead);
+        entry.cacheWrite += finiteOrZero(task.usage.cacheWrite);
+        entry.count += 1;
+        totals.set(key, entry);
+    }
+    return totals;
+}
+/** Key (and display name) under which tasks without a resolved project are grouped. */
+const NO_PROJECT = "(no project)";
+/**
+ * Aggregate tasks by hub project (see `domain/work-target.ts`), keyed by
+ * `projectId` (so two projects that happen to share a display name are
+ * never merged) with the name denormalised alongside for display. Tasks
+ * without a `projectId` are grouped under `"(no project)"`.
+ */
+export function summarizeByProject(tasks) {
+    const totals = new Map();
+    for (const task of tasks) {
+        const key = task.projectId ?? NO_PROJECT;
+        const name = task.projectId !== undefined ? (task.projectName ?? task.projectId) : NO_PROJECT;
+        const entry = totals.get(key) ?? { name, wallMs: 0, waitingMs: 0, workMs: 0, cost: 0, input: 0, cacheRead: 0, cacheWrite: 0, count: 0 };
+        entry.wallMs += task.wallMs;
+        entry.waitingMs += task.waitingMs;
+        entry.workMs += task.workMs;
+        entry.cost += finiteOrZero(task.usage.cost);
+        entry.input += finiteOrZero(task.usage.input);
+        entry.cacheRead += finiteOrZero(task.usage.cacheRead);
+        entry.cacheWrite += finiteOrZero(task.usage.cacheWrite);
+        entry.count += 1;
+        totals.set(key, entry);
+    }
+    return totals;
+}
+/** Render one line per project, sorted alphabetically by display name, with work/waiting/wall time, cost, and task count. */
+export function formatProjects(totals) {
+    if (totals.size === 0)
+        return "no projects";
+    return Array.from(totals.values())
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((t) => {
+        const cacheHit = formatCacheHit(t);
+        const cacheHitPart = cacheHit !== undefined ? `  ${cacheHit}` : "";
+        return `${t.name}  work ${formatMinutes(t.workMs)}  waiting ${formatMinutes(t.waitingMs)}  wall ${formatMinutes(t.wallMs)}  ${formatCost(t.cost)}${cacheHitPart}  tasks ${t.count}`;
+    })
+        .join("\n");
+}
+/** Render one line per client, sorted alphabetically, with work/waiting/wall time, cost, and task count. */
+export function formatClients(totals) {
+    if (totals.size === 0)
+        return "no clients";
+    return Array.from(totals.entries())
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([client, t]) => {
+        const cacheHit = formatCacheHit(t);
+        const cacheHitPart = cacheHit !== undefined ? `  ${cacheHit}` : "";
+        return `${client}  work ${formatMinutes(t.workMs)}  waiting ${formatMinutes(t.waitingMs)}  wall ${formatMinutes(t.wallMs)}  ${formatCost(t.cost)}${cacheHitPart}  tasks ${t.count}`;
+    })
+        .join("\n");
+}
+/** Render one line per session: truncated id, time range, union-based wall/work, cost, non-zero segment tags, and task count. */
+export function formatSessions(sessions) {
+    if (sessions.length === 0)
+        return "no sessions";
+    return sessions
+        .map((session) => {
+        const segmentTags = formatSegmentTags(session.segments);
+        const segmentPart = segmentTags !== undefined ? `  ${segmentTags}` : "";
+        return `${session.sessionId.slice(0, 8)}  ${formatTime(session.startedAt)}–${formatTime(session.endedAt)}  wall ${formatMinutes(session.wallMs)}  work ${formatMinutes(session.workMs)}  ${formatCost(session.usage.cost)}${segmentPart}  tasks ${session.tasks.length}`;
+    })
+        .join("\n");
+}