kankaku-pi 1.0.0

package/dist/domain/ancestry-match.js

@@ -0,0 +1,82 @@
+/**
+ * Max allowed drift (ms) between a live process's freshly re-derived start
+ * identity and the one recorded in its registry entry. Absorbs
+ * second-granularity rounding/reading noise from the underlying OS
+ * start-time source (`adapters/ancestry.ts`) — not a measure of real clock
+ * error, since both readings of the *same* process instance stay tightly
+ * consistent regardless of that source's own precision (see that module's
+ * docs). A genuine pid-reuse produces a gap far larger than this.
+ */
+export const START_ID_TOLERANCE_MS = 2000;
+/** Whether two start identities are close enough to be the same process instance. `undefined` on either side is always "no", never a coincidental match. */
+function sameProcessInstance(recorded, live) {
+    if (recorded === undefined || live === undefined)
+        return false;
+    return Math.abs(recorded - live) <= START_ID_TOLERANCE_MS;
+}
+/**
+ * The nearest tracked ancestor whose identity can actually be *proven*: the
+ * first `ancestryPids` entry (ordered nearest-parent first, see
+ * `adapters/ancestry.ts#walkAncestry`) that has a matching
+ * {@link RegistryEntry} AND whose registry-recorded `processStartId`
+ * agrees, within {@link START_ID_TOLERANCE_MS}, with `liveStartId(pid)` —
+ * a fresh re-derivation of that same pid's actual OS start time, taken
+ * from the same ancestry snapshot the caller already has. Matching by pid
+ * number alone is not safe: the OS reuses pids, so a stale entry left
+ * behind by a dead, never-cleaned-up process can otherwise be
+ * misattributed to whatever unrelated live process the kernel later hands
+ * that same pid to (a genuine top-level session silently misclassified as
+ * someone's subagent forever). A candidate whose identity cannot be
+ * verified — no `processStartId` on the entry (legacy/malformed), or no
+ * live start id available for that pid (platform without ancestor-chain
+ * support, or a snapshot gap) — is never matched; the walk continues past
+ * it exactly like an untracked hop, so a further genuine ancestor can still
+ * be found. Returns `undefined` when no ancestor pid is trackable at all —
+ * callers must treat that exactly like "no registry available" (safe
+ * fallback to the pre-registry behaviour), never invent a match.
+ */
+export function findAncestorEntry(ancestryPids, entries, liveStartId) {
+    if (ancestryPids.length === 0 || entries.length === 0)
+        return undefined;
+    const byPid = new Map();
+    for (const entry of entries) {
+        // First entry for a given pid wins; a pid should only ever have one
+        // live registry file, but a torn write racing a sweep could in theory
+        // leave two candidates behind — deterministic tie-break, not correctness-critical.
+        if (!byPid.has(entry.pid))
+            byPid.set(entry.pid, entry);
+    }
+    for (const pid of ancestryPids) {
+        const entry = byPid.get(pid);
+        if (!entry)
+            continue;
+        if (sameProcessInstance(entry.processStartId, liveStartId(pid)))
+            return entry;
+        // Either unprovable, or this pid has genuinely been reused by a
+        // different process instance since the entry was written: not our
+        // ancestor. Keep walking — a further, verifiable ancestor may still exist.
+    }
+    return undefined;
+}
+/**
+ * Resolve the ultimate, top-level {@link OrchestratorRef} for `ancestorEntry`
+ * (the nearest verified ancestor {@link findAncestorEntry} returned) — F4's
+ * nested-subagent fix. When that ancestor is itself a `subagent`-role entry
+ * that already resolved its own verified `orchestratorRef` (a
+ * subagent-of-subagent chain: this process's parent is itself someone's
+ * child), that inherited ref is returned instead of one built from the
+ * ancestor's own identity — so a grandchild's `orchestratorRef` (and, via
+ * its `dir`, `extension.ts`'s F1 write-routing target) always points at
+ * the real top-level orchestrator, never a middle hop. Falls back to an
+ * ancestor's own identity when it is an orchestrator, or a subagent that
+ * never resolved a ref of its own (e.g. it discovered no tracked ancestor
+ * at its own startup) — never invents one. `undefined` in, `undefined` out.
+ */
+export function resolveOrchestratorRef(ancestorEntry) {
+    if (ancestorEntry === undefined)
+        return undefined;
+    if (ancestorEntry.role === "subagent" && ancestorEntry.orchestratorRef !== undefined) {
+        return ancestorEntry.orchestratorRef;
+    }
+    return { pid: ancestorEntry.pid, project: ancestorEntry.project, startedAt: ancestorEntry.startedAt, dir: ancestorEntry.dir };
+}

package/dist/domain/client-label.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Client (billing target) label resolution: pure, no I/O.
+ *
+ * A client name identifies who a piece of work is billed to. It can come
+ * from three sources, in decreasing precedence: the pi session (set with
+ * `/kankaku client <name>`), the `KANKAKU_CLIENT` environment variable, or
+ * the project's `.kankaku/config.json`.
+ */
+export interface ClientSources {
+    /** Set for the current pi session via `/kankaku client <name>`. Highest precedence. */
+    session?: string;
+    /** From the `KANKAKU_CLIENT` environment variable. */
+    env?: string;
+    /** From the project's `.kankaku/config.json`. Lowest precedence. */
+    project?: string;
+}
+export type ClientSourceName = "session" | "env" | "project";
+/** `true` when `value` is a non-empty, safe client name. */
+export declare function isValidClient(value: string): boolean;
+/**
+ * Resolve the effective client name from `session`, `env` and `project`
+ * sources, in that precedence order. Each candidate is trimmed; an empty
+ * string or a value that does not match the safe client-name pattern is
+ * treated as absent and resolution falls through to the next source.
+ */
+export declare function resolveClient(sources: ClientSources): string | undefined;
+/** Which source produced {@link resolveClient}'s result, or `undefined` when none applies. */
+export declare function resolveClientSource(sources: ClientSources): ClientSourceName | undefined;

package/dist/domain/client-label.js

@@ -0,0 +1,44 @@
+/**
+ * Client (billing target) label resolution: pure, no I/O.
+ *
+ * A client name identifies who a piece of work is billed to. It can come
+ * from three sources, in decreasing precedence: the pi session (set with
+ * `/kankaku client <name>`), the `KANKAKU_CLIENT` environment variable, or
+ * the project's `.kankaku/config.json`.
+ */
+/** Safe client name: letters, digits, `.`, `_`, `-`, 1-64 chars. */
+const CLIENT_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+/** Property names that behave specially on a plain object; never usable as a client name. */
+const RESERVED_NAMES = new Set(["__proto__", "constructor", "prototype"]);
+/** `true` when `value` is a non-empty, safe client name. */
+export function isValidClient(value) {
+    return CLIENT_PATTERN.test(value) && !RESERVED_NAMES.has(value);
+}
+/** Trim and validate a candidate client name; `undefined` when absent or invalid. */
+function normalize(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    return isValidClient(trimmed) ? trimmed : undefined;
+}
+/**
+ * Resolve the effective client name from `session`, `env` and `project`
+ * sources, in that precedence order. Each candidate is trimmed; an empty
+ * string or a value that does not match the safe client-name pattern is
+ * treated as absent and resolution falls through to the next source.
+ */
+export function resolveClient(sources) {
+    return normalize(sources.session) ?? normalize(sources.env) ?? normalize(sources.project);
+}
+/** Which source produced {@link resolveClient}'s result, or `undefined` when none applies. */
+export function resolveClientSource(sources) {
+    if (normalize(sources.session) !== undefined)
+        return "session";
+    if (normalize(sources.env) !== undefined)
+        return "env";
+    if (normalize(sources.project) !== undefined)
+        return "project";
+    return undefined;
+}

package/dist/domain/day.d.ts

@@ -0,0 +1,2 @@
+/** Local (not UTC) calendar day of an ISO timestamp, as `YYYY-MM-DD`. */
+export declare function localDay(iso: string): string;

package/dist/domain/day.js

@@ -0,0 +1,8 @@
+/** Local (not UTC) calendar day of an ISO timestamp, as `YYYY-MM-DD`. */
+export function localDay(iso) {
+    const date = new Date(iso);
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+}

package/dist/domain/export.d.ts

@@ -0,0 +1,38 @@
+import type { WorkStatus } from "./work-record.ts";
+import type { TaskView } from "./task-view.ts";
+/** One flat, spreadsheet-friendly row per {@link TaskView}. */
+export interface ExportRow {
+    id: string;
+    /** Local calendar day (`YYYY-MM-DD`) the task started on. */
+    day: string;
+    startedAt: string;
+    endedAt: string;
+    /** Empty string when the task has no resolved client. */
+    client: string;
+    /** Empty string when the orchestrator record has no session name. */
+    sessionName: string;
+    /** Empty string when the orchestrator record has no session id. */
+    sessionId: string;
+    project: string;
+    status: WorkStatus;
+    /** First 200 chars of the task's prompt, with newlines collapsed to spaces. */
+    prompt: string;
+    wallMs: number;
+    waitingMs: number;
+    workMs: number;
+    cost: number;
+    tokensIn: number;
+    tokensOut: number;
+    cacheRead: number;
+    subagentCount: number;
+    /** JSON-encoded `TaskView.segments` map. */
+    segments: string;
+    /** Empty string when the orchestrator record has no model. */
+    model: string;
+}
+/** Build one flat {@link ExportRow} per task, in the same order as `tasks`. */
+export declare function exportRows(tasks: TaskView[]): ExportRow[];
+/** Render `rows` as RFC 4180 CSV: a header row, one row per record, `\n` line endings. */
+export declare function toCsv(rows: ExportRow[]): string;
+/** Render `rows` as pretty-printed (2-space indent) JSON. */
+export declare function toJson(rows: ExportRow[]): string;

package/dist/domain/export.js

@@ -0,0 +1,68 @@
+import { localDay } from "./day.js";
+import { finiteOrZero } from "./work-record.js";
+/** First 200 chars of `prompt`, with `\n`/`\r` collapsed to a single space. */
+function truncatePrompt(prompt) {
+    return prompt.slice(0, 200).replace(/\r\n|\r|\n/g, " ");
+}
+/** Build one flat {@link ExportRow} per task, in the same order as `tasks`. */
+export function exportRows(tasks) {
+    return tasks.map((task) => ({
+        id: task.id,
+        day: localDay(task.startedAt),
+        startedAt: task.startedAt,
+        endedAt: task.endedAt,
+        client: task.client ?? "",
+        sessionName: task.sessionName ?? "",
+        sessionId: task.sessionId ?? "",
+        project: task.project,
+        status: task.status,
+        prompt: truncatePrompt(task.prompt),
+        wallMs: task.wallMs,
+        waitingMs: task.waitingMs,
+        workMs: task.workMs,
+        cost: finiteOrZero(task.usage.cost),
+        tokensIn: finiteOrZero(task.usage.input),
+        tokensOut: finiteOrZero(task.usage.output),
+        cacheRead: finiteOrZero(task.usage.cacheRead),
+        subagentCount: task.subagents.length,
+        segments: JSON.stringify(task.segments),
+        model: task.orchestrator.model ?? "",
+    }));
+}
+/** Column order for {@link toCsv}'s header row, matching {@link ExportRow}'s field order. */
+const COLUMNS = [
+    "id",
+    "day",
+    "startedAt",
+    "endedAt",
+    "client",
+    "sessionName",
+    "sessionId",
+    "project",
+    "status",
+    "prompt",
+    "wallMs",
+    "waitingMs",
+    "workMs",
+    "cost",
+    "tokensIn",
+    "tokensOut",
+    "cacheRead",
+    "subagentCount",
+    "segments",
+    "model",
+];
+/** RFC 4180 field quoting: quote a field containing `,`, `"`, or a newline; double any embedded quote. */
+function csvField(value) {
+    const text = String(value);
+    return /[",\r\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+/** Render `rows` as RFC 4180 CSV: a header row, one row per record, `\n` line endings. */
+export function toCsv(rows) {
+    const lines = [COLUMNS.join(","), ...rows.map((row) => COLUMNS.map((column) => csvField(row[column])).join(","))];
+    return lines.join("\n");
+}
+/** Render `rows` as pretty-printed (2-space indent) JSON. */
+export function toJson(rows) {
+    return JSON.stringify(rows, null, 2);
+}

package/dist/domain/hub-entry.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Map a {@link TaskView} (and its `WorkRecord`s) to the hub's `task_entries`
+ * / `work_records` payload shapes. Pure, no I/O — see `contract.md` in
+ * kankaku-hub for the exact field names/types this mirrors.
+ *
+ * The CRITICAL rule this file encodes: assignment (`client`/`project`/
+ * `task`/`legacy_client_label`) is create-only. The owner reassigns rows in
+ * the web; a later re-sync of the same task must never undo that, so
+ * `buildTaskEntryUpdatePayload` never includes those fields. See
+ * `buildTaskEntryCreatePayload` vs `buildTaskEntryUpdatePayload`.
+ */
+import type { TaskView } from "./task-view.ts";
+import type { WorkRecord, WorkRole, WorkStatus } from "./work-record.ts";
+import type { Client, HubTask, Project } from "./work-target.ts";
+export type PromptPrivacyMode = "none" | "truncated" | "full";
+export interface HubEntryContext {
+    clients: Client[];
+    projects: Project[];
+    /** The hub's known tasks, to validate a task's linked `hubTaskId` against. See {@link resolveTaskAssignment}. */
+    tasks: HubTask[];
+    /** This machine's hostname or `KANKAKU_MACHINE`. */
+    machine: string;
+    /** `KANKAKU_SYNC_PROMPT`; see {@link applyPromptPrivacy}. */
+    promptMode: PromptPrivacyMode;
+    /** Coding agent that produced this row, lowercase slug. Always `"pi"` for this package. See kankaku-hub `docs/contract.md` "Agent and measurement quality". */
+    agent: string;
+    /** The `pi` package's own version, when it could be determined without a hot-path cost. Never guessed — omitted rather than sent wrong. */
+    agentVersion?: string;
+    /** The integration that wrote this row, lowercase slug. Always `"kankaku"` for this package. */
+    plugin: string;
+    /** This kankaku package's own version, from its `package.json`, read once. */
+    pluginVersion?: string;
+}
+export interface TaskAssignment {
+    /** `clients` relation id, or `""` when no usable client could be resolved. */
+    clientId: string;
+    /** `projects` relation id, or `""`. */
+    projectId: string;
+    /** `tasks` relation id, or `""` when no usable hub task could be resolved. See {@link resolveTaskAssignment}. */
+    hubTaskId: string;
+    /** Only set (non-empty) for a task routed to the unassigned client. */
+    legacyClientLabel: string;
+    /** `true` when this task was routed to the catalog's unassigned ("Sin determinar") client. */
+    routedToUnassigned: boolean;
+}
+/**
+ * Resolve which client/project/hub-task a task's `task_entries` row should
+ * link to.
+ *
+ * - A task whose `clientId` still exists in `clients` links to that client
+ *   (regardless of its `active` flag — this is a historical fact, not a
+ *   future selection), and to `projectId` too when it still exists and
+ *   belongs to that client; otherwise the project relation is empty.
+ * - A task with no `clientId`, or whose `clientId` no longer resolves,
+ *   routes to the catalog's unassigned client (the row with
+ *   `unassigned: true`), carrying forward the record's free-text `client`
+ *   label (or its `clientName` when the label itself is absent) as
+ *   `legacyClientLabel` — the historical backfill rule (proposal §5.3).
+ * - `hubTaskId` is kept only when it still exists in `tasks` AND belongs to
+ *   the resolved `projectId` (non-empty); otherwise it is `""` — including
+ *   whenever the client fell back to unassigned, since there is then no
+ *   resolved project for a task to belong to.
+ */
+export declare function resolveTaskAssignment(task: TaskView, clients: Client[], projects: Project[], tasks: HubTask[]): TaskAssignment;
+/**
+ * Privacy transform for a prompt about to leave the machine
+ * (`KANKAKU_SYNC_PROMPT`, default `none`): `none` omits it entirely,
+ * `truncated` keeps the first 120 chars plus an ellipsis marker when
+ * anything was cut, `full` sends it verbatim.
+ */
+export declare function applyPromptPrivacy(prompt: string, mode: PromptPrivacyMode): string;
+export type WaitingQuality = "measured" | "unavailable";
+export type CostQuality = "measured" | "estimated" | "unknown";
+export type SubagentLinkage = "linked" | "unlinked" | "not_applicable";
+/**
+ * Whether waiting time (time blocked on the human) was actually observed
+ * for this task, as opposed to `work_ms` being an unmeasured upper bound
+ * equal to `wall_ms`. pi always instruments `ui_prompt_start`/`_end` and
+ * interactive-tool spans (`domain/work-tracker.ts`), so this is always
+ * `"measured"` for kankaku/pi — a constant here, not computed from a
+ * record, kept as its own function (rather than a literal in the payload)
+ * so the reasoning has one documented home.
+ */
+export declare function computeWaitingQuality(): WaitingQuality;
+/**
+ * Whether this task's cost figure came from a real provider-reported cost
+ * (`"measured"`) or not (`"unknown"`) — never `"estimated"`: kankaku has no
+ * token-based price-table estimator today, only a real provider figure or
+ * nothing. A task counts as measured when its own orchestrator record OR
+ * any of its joined subagent records observed one (see
+ * `WorkRecord.costObserved`, set by `domain/work-tracker.ts`).
+ */
+export declare function computeCostQuality(task: TaskView): CostQuality;
+/**
+ * Whether this task's subagent tool spans (`orchestrator.subagents`,
+ * `SubagentSpan[]` — the orchestrator's own tool-call bookkeeping) are
+ * accounted for by joined child `WorkRecord`s (`task.subagents`, from
+ * `domain/task-view.ts#matchChildren`). There is no explicit per-span
+ * correlation id today (README "Subagents" > "Limitations": upstream
+ * gentle-pi does not hand a child its own task id), so this is a
+ * task-level approximation, not a per-span one:
+ *
+ * - `not_applicable`: the orchestrator opened no subagent spans at all.
+ * - `linked`: at least as many child records were joined as spans were
+ *   opened — plausibly every span is accounted for (a gentle-pi subagent
+ *   spawns exactly one child process per span, so counts normally match
+ *   1:1).
+ * - `unlinked`: fewer joined children than spans (including zero) — at
+ *   least one span's time is only visible inside the orchestrator's own
+ *   tool-call span, with no corroborating child record. This also covers
+ *   a fully in-process subagent mechanism (no separate OS process at all,
+ *   invisible to the registry/ancestry machinery) and a genuine join miss
+ *   alike — kankaku cannot tell those apart from here, so it reports the
+ *   conservative, visible-gap answer rather than guessing "linked".
+ */
+export declare function computeSubagentLinkage(task: TaskView): SubagentLinkage;
+/** The `task_entries` fields present on every write. */
+export interface TaskEntryPayload {
+    task_id: string;
+    client: string;
+    project: string;
+    task: string;
+    started_at: string;
+    ended_at: string;
+    wall_ms: number;
+    waiting_ms: number;
+    work_ms: number;
+    input: number;
+    output: number;
+    cache_read: number;
+    cache_write: number;
+    cost: number;
+    segments: Record<string, number>;
+    subagent_count: number;
+    runs: number;
+    turns: number;
+    status: WorkStatus;
+    session_id: string;
+    session_name: string;
+    machine: string;
+    model: string;
+    /** The model's reasoning effort; omitted when the record does not know it. */
+    thinking_level?: string;
+    prompt: string;
+    legacy_client_label: string;
+    repo_project: string;
+    schema: number;
+    /** Coding agent that MEASURED this task, lowercase slug — the orchestrator record's own {@link WorkRecordMetadata.agent} when it carries one (who measured, not who syncs), else `ctx.agent` (the syncing process's own identity) as a legacy fallback. See {@link WorkRecordMetadata.agent}. */
+    agent: string;
+    agent_version?: string;
+    /** Non-default session directory, see `TaskView.sessionDir`. A measurement field, not assignment: sent on both create and update. */
+    session_dir?: string;
+    /** The integration that wrote this task's records, lowercase slug — same record-wins-over-ctx rule as {@link agent}. */
+    plugin: string;
+    plugin_version?: string;
+    waiting_quality: WaitingQuality;
+    cost_quality: CostQuality;
+    subagent_linkage: SubagentLinkage;
+}
+/**
+ * `TaskEntryPayload` minus the assignment fields — what an update sends. See
+ * the module docs' CRITICAL rule.
+ *
+ * `agent`/`agent_version`/`plugin`/`plugin_version` are optional here (unlike
+ * on `TaskEntryPayload`, where they are always sent on create): an update for
+ * a task whose orchestrator record carries no who-measured identity (a
+ * legacy record, written before this feature existed) omits them entirely,
+ * so a re-sync by a DIFFERENT process never overwrites a row's original
+ * identity with its own. See {@link buildTaskEntryUpdatePayload}.
+ */
+export type TaskEntryUpdatePayload = Omit<TaskEntryPayload, "client" | "project" | "task" | "legacy_client_label" | "agent" | "agent_version" | "plugin" | "plugin_version"> & {
+    agent?: string;
+    agent_version?: string;
+    plugin?: string;
+    plugin_version?: string;
+};
+/** Build the full `task_entries` payload for a **create** request — every field, including assignment. */
+export declare function buildTaskEntryCreatePayload(task: TaskView, ctx: HubEntryContext): TaskEntryPayload;
+/**
+ * Build the `task_entries` payload for an **update** request: measurement
+ * fields only — never `client`, `project`, `task` or `legacy_client_label`,
+ * so a re-sync can never undo a reassignment made in the web. See the
+ * module docs' CRITICAL rule.
+ *
+ * `agent`/`agent_version`/`plugin`/`plugin_version` are included ONLY when
+ * the orchestrator record itself carries a who-measured `agent` — otherwise
+ * they are OMITTED entirely (never sent as `ctx`'s own identity), so a
+ * re-sync of a legacy record by a different process never overwrites the
+ * row's original identity in the hub. See `domain/work-record.ts`'s
+ * "Measurement rules" and {@link resolveTaskIdentity}.
+ */
+export declare function buildTaskEntryUpdatePayload(task: TaskView, ctx: HubEntryContext): TaskEntryUpdatePayload;
+/** One `work_records` row — raw per-`WorkRecord` detail, always `rollup: false`. */
+export interface WorkRecordPayload {
+    kankaku_id: string;
+    task_entry: string;
+    rollup: false;
+    role: WorkRole;
+    pid: number;
+    parent_pid: number;
+    started_at: string;
+    settled_at: string;
+    wall_ms: number;
+    waiting_ms: number;
+    work_ms: number;
+    runs: number;
+    turns: number;
+    status: WorkStatus;
+    model: string;
+    thinking_level?: string;
+    input: number;
+    output: number;
+    cache_read: number;
+    cache_write: number;
+    cost: number;
+    segments: Record<string, number>;
+    tools: Record<string, number>;
+    session_id: string;
+    prompt: string;
+    machine: string;
+    schema: number;
+}
+/**
+ * Build one `work_records` payload from a raw {@link WorkRecord}
+ * (orchestrator or subagent), linked to its parent `task_entries` row by
+ * PocketBase id. `work_records` carries no assignment fields, so there is
+ * no create/update distinction here — this payload is sent as-is either way.
+ */
+export declare function buildWorkRecordPayload(record: WorkRecord, taskEntryRecordId: string, ctx: {
+    machine: string;
+    promptMode: PromptPrivacyMode;
+}): WorkRecordPayload;
+/** Every `WorkRecord` folded into a task: the orchestrator plus its subagents, in that order. */
+export declare function taskWorkRecords(task: TaskView): WorkRecord[];