kankaku-pi 1.0.0

package/dist/domain/hub-entry.js

@@ -0,0 +1,265 @@
+/**
+ * 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 { finiteOrZero } from "./work-record.js";
+/**
+ * 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 function resolveTaskAssignment(task, clients, projects, tasks) {
+    const client = task.clientId !== undefined ? clients.find((candidate) => candidate.id === task.clientId) : undefined;
+    if (client) {
+        const project = task.projectId !== undefined ? projects.find((candidate) => candidate.id === task.projectId && candidate.clientId === client.id) : undefined;
+        const hubTask = project !== undefined && task.hubTaskId !== undefined
+            ? tasks.find((candidate) => candidate.id === task.hubTaskId && candidate.projectId === project.id)
+            : undefined;
+        return {
+            clientId: client.id,
+            projectId: project ? project.id : "",
+            hubTaskId: hubTask ? hubTask.id : "",
+            legacyClientLabel: "",
+            routedToUnassigned: false,
+        };
+    }
+    const unassigned = clients.find((candidate) => candidate.unassigned === true);
+    return {
+        clientId: unassigned ? unassigned.id : "",
+        projectId: "",
+        hubTaskId: "",
+        legacyClientLabel: task.client ?? task.clientName ?? "",
+        routedToUnassigned: true,
+    };
+}
+/**
+ * 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 function applyPromptPrivacy(prompt, mode) {
+    if (mode === "full")
+        return prompt;
+    if (mode === "truncated")
+        return prompt.length > 120 ? `${prompt.slice(0, 120)}…` : prompt;
+    return "";
+}
+/**
+ * PocketBase `date` fields read back as `"YYYY-MM-DD HH:MM:SS.mmmZ"` (space,
+ * not `T`) though both forms are accepted on write; kankaku always sends
+ * the space form so a round trip through the contract's documented shape
+ * never depends on PocketBase's own normalization.
+ */
+function toPbDate(iso) {
+    return iso.replace("T", " ");
+}
+/**
+ * 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 function computeWaitingQuality() {
+    return "measured";
+}
+/**
+ * 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 function computeCostQuality(task) {
+    const observed = task.orchestrator.costObserved === true || task.subagents.some((child) => child.costObserved === true);
+    return observed ? "measured" : "unknown";
+}
+/**
+ * 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 function computeSubagentLinkage(task) {
+    const spanCount = task.orchestrator.subagents.length;
+    if (spanCount === 0)
+        return "not_applicable";
+    return task.subagents.length >= spanCount ? "linked" : "unlinked";
+}
+/**
+ * The who-measured identity (`agent`/`agentVersion`/`plugin`/`pluginVersion`)
+ * for a task's payload: the orchestrator record's own fields, taken as a
+ * unit, when it carries an `agent` — a missing version on the record is
+ * omitted, never backfilled from `ctx` — otherwise `ctx`'s identity (the
+ * syncing process's own), exactly as before this feature existed. See
+ * `domain/work-record.ts#WorkRecordMetadata.agent`'s doc comment.
+ */
+function resolveTaskIdentity(task, ctx) {
+    const orchestrator = task.orchestrator;
+    if (orchestrator.agent !== undefined) {
+        // The record's four fields are taken as a unit. A record written by an
+        // integration that stamped `agent` but not `plugin` gets the syncing
+        // context's `plugin` ONLY on create, so the row is never blank; the
+        // update payload below never resends a plugin the record does not own.
+        return {
+            agent: orchestrator.agent,
+            agentVersion: orchestrator.agentVersion,
+            plugin: orchestrator.plugin ?? ctx.plugin,
+            pluginVersion: orchestrator.plugin !== undefined ? orchestrator.pluginVersion : undefined,
+        };
+    }
+    return { agent: ctx.agent, agentVersion: ctx.agentVersion, plugin: ctx.plugin, pluginVersion: ctx.pluginVersion };
+}
+/** Build the full `task_entries` payload for a **create** request — every field, including assignment. */
+export function buildTaskEntryCreatePayload(task, ctx) {
+    const assignment = resolveTaskAssignment(task, ctx.clients, ctx.projects, ctx.tasks);
+    const identity = resolveTaskIdentity(task, ctx);
+    return {
+        task_id: task.id,
+        client: assignment.clientId,
+        project: assignment.projectId,
+        task: assignment.hubTaskId,
+        started_at: toPbDate(task.startedAt),
+        ended_at: toPbDate(task.endedAt),
+        wall_ms: task.wallMs,
+        waiting_ms: task.waitingMs,
+        work_ms: task.workMs,
+        input: finiteOrZero(task.usage.input),
+        output: finiteOrZero(task.usage.output),
+        cache_read: finiteOrZero(task.usage.cacheRead),
+        cache_write: finiteOrZero(task.usage.cacheWrite),
+        cost: finiteOrZero(task.usage.cost),
+        segments: task.segments,
+        subagent_count: task.subagents.length,
+        runs: task.orchestrator.runs,
+        turns: task.orchestrator.turns,
+        status: task.status,
+        session_id: task.sessionId ?? "",
+        session_name: task.sessionName ?? "",
+        machine: ctx.machine,
+        model: task.orchestrator.model ?? "",
+        ...(task.orchestrator.thinkingLevel !== undefined ? { thinking_level: task.orchestrator.thinkingLevel } : {}),
+        prompt: applyPromptPrivacy(task.prompt, ctx.promptMode),
+        legacy_client_label: assignment.legacyClientLabel,
+        repo_project: task.project,
+        schema: task.orchestrator.schema,
+        agent: identity.agent,
+        ...(identity.agentVersion !== undefined ? { agent_version: identity.agentVersion } : {}),
+        ...(task.sessionDir !== undefined ? { session_dir: task.sessionDir } : {}),
+        plugin: identity.plugin,
+        ...(identity.pluginVersion !== undefined ? { plugin_version: identity.pluginVersion } : {}),
+        waiting_quality: computeWaitingQuality(),
+        cost_quality: computeCostQuality(task),
+        subagent_linkage: computeSubagentLinkage(task),
+    };
+}
+/**
+ * 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 function buildTaskEntryUpdatePayload(task, ctx) {
+    const { client: _client, project: _project, task: _task, legacy_client_label: _legacy, agent, agent_version, plugin, plugin_version, ...rest } = buildTaskEntryCreatePayload(task, ctx);
+    if (task.orchestrator.agent === undefined)
+        return rest;
+    // `plugin`/`plugin_version` are resent only when the record itself carries
+    // them; a record with `agent` but no `plugin` must never have the syncing
+    // process's plugin written over the row's original one.
+    const recordHasPlugin = task.orchestrator.plugin !== undefined;
+    return {
+        ...rest,
+        agent,
+        ...(agent_version !== undefined ? { agent_version } : {}),
+        ...(recordHasPlugin ? { plugin } : {}),
+        ...(recordHasPlugin && plugin_version !== undefined ? { plugin_version } : {}),
+    };
+}
+/**
+ * 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 function buildWorkRecordPayload(record, taskEntryRecordId, ctx) {
+    return {
+        kankaku_id: record.id,
+        task_entry: taskEntryRecordId,
+        rollup: false,
+        role: record.role,
+        pid: record.pid,
+        parent_pid: record.parentPid,
+        started_at: toPbDate(record.startedAt),
+        settled_at: toPbDate(record.settledAt),
+        wall_ms: record.wallMs,
+        waiting_ms: record.waitingMs,
+        work_ms: record.workMs,
+        runs: record.runs,
+        turns: record.turns,
+        status: record.status,
+        model: record.model ?? "",
+        ...(record.thinkingLevel !== undefined ? { thinking_level: record.thinkingLevel } : {}),
+        input: finiteOrZero(record.usage.input),
+        output: finiteOrZero(record.usage.output),
+        cache_read: finiteOrZero(record.usage.cacheRead),
+        cache_write: finiteOrZero(record.usage.cacheWrite),
+        cost: finiteOrZero(record.usage.cost),
+        segments: record.segments ?? {},
+        tools: record.tools,
+        session_id: record.sessionId ?? "",
+        prompt: applyPromptPrivacy(record.prompt, ctx.promptMode),
+        machine: ctx.machine,
+        schema: record.schema,
+    };
+}
+/** Every `WorkRecord` folded into a task: the orchestrator plus its subagents, in that order. */
+export function taskWorkRecords(task) {
+    return [task.orchestrator, ...task.subagents];
+}

package/dist/domain/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Public library entrypoint (`kankaku-pi/domain`): the pure domain layer, with
+ * no I/O and no pi imports. See AGENTS.md "Architecture (hexagonal)" and
+ * odd/tasks/library-exports.md.
+ */
+export * from "./ancestry-match.ts";
+export * from "./client-label.ts";
+export * from "./day.ts";
+export * from "./export.ts";
+export * from "./hub-entry.ts";
+export * from "./intervals.ts";
+export * from "./registry-health.ts";
+export * from "./segment-rule.ts";
+export * from "./subagent-profile.ts";
+export * from "./sync-plan.ts";
+export * from "./task-view.ts";
+export * from "./work-record.ts";
+export * from "./work-target.ts";
+export * from "./work-tracker.ts";

package/dist/domain/index.js

@@ -0,0 +1,19 @@
+/**
+ * Public library entrypoint (`kankaku-pi/domain`): the pure domain layer, with
+ * no I/O and no pi imports. See AGENTS.md "Architecture (hexagonal)" and
+ * odd/tasks/library-exports.md.
+ */
+export * from "./ancestry-match.js";
+export * from "./client-label.js";
+export * from "./day.js";
+export * from "./export.js";
+export * from "./hub-entry.js";
+export * from "./intervals.js";
+export * from "./registry-health.js";
+export * from "./segment-rule.js";
+export * from "./subagent-profile.js";
+export * from "./sync-plan.js";
+export * from "./task-view.js";
+export * from "./work-record.js";
+export * from "./work-target.js";
+export * from "./work-tracker.js";

package/dist/domain/intervals.d.ts

@@ -0,0 +1,17 @@
+export interface Interval {
+    start: number;
+    end: number;
+}
+/**
+ * Restrict every interval to `[windowStart, windowEnd]` and drop any that
+ * become empty (or invalid) after clamping.
+ */
+export declare function clampIntervals(intervals: Interval[], windowStart: number, windowEnd: number): Interval[];
+/**
+ * Total duration covered by the union of the given intervals — never the
+ * sum, so overlapping (e.g. parallel subagent) spans are not double-counted.
+ */
+export declare function unionMs(intervals: Array<{
+    start: number;
+    end: number;
+}>): number;

package/dist/domain/intervals.js

@@ -0,0 +1,43 @@
+/**
+ * Restrict every interval to `[windowStart, windowEnd]` and drop any that
+ * become empty (or invalid) after clamping.
+ */
+export function clampIntervals(intervals, windowStart, windowEnd) {
+    return intervals
+        .map((interval) => ({
+        start: Math.max(interval.start, windowStart),
+        end: Math.min(interval.end, windowEnd),
+    }))
+        .filter((interval) => interval.end > interval.start);
+}
+/**
+ * Total duration covered by the union of the given intervals — never the
+ * sum, so overlapping (e.g. parallel subagent) spans are not double-counted.
+ */
+export function unionMs(intervals) {
+    const sorted = [...intervals].sort((a, b) => a.start - b.start);
+    let total = 0;
+    let currentStart;
+    let currentEnd;
+    for (const interval of sorted) {
+        if (interval.end <= interval.start)
+            continue;
+        if (currentStart === undefined || currentEnd === undefined) {
+            currentStart = interval.start;
+            currentEnd = interval.end;
+            continue;
+        }
+        if (interval.start <= currentEnd) {
+            currentEnd = Math.max(currentEnd, interval.end);
+        }
+        else {
+            total += currentEnd - currentStart;
+            currentStart = interval.start;
+            currentEnd = interval.end;
+        }
+    }
+    if (currentStart !== undefined && currentEnd !== undefined) {
+        total += currentEnd - currentStart;
+    }
+    return total;
+}

package/dist/domain/registry-health.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Decide which machine-wide {@link RegistryEntry} rows a sweep should keep
+ * vs discard, and why. Pure, no I/O — `adapters/machine-process-registry.ts`
+ * drives this with real `isAlive`/`liveStartId`/`now`, and
+ * `adapters/kankaku-command.ts`'s `/kankaku doctor` reuses it (cheap mode,
+ * no fresh identity re-verification) to report registry health.
+ */
+import type { RegistryEntry } from "../ports/process-registry.ts";
+/** Sane last-resort ceiling on an entry's age, regardless of aliveness/identity: 7 days. */
+export declare const DEFAULT_MAX_ENTRY_AGE_MS: number;
+export type DiscardReason = "dead"
+/** The pid is alive, but its live start identity no longer matches what this entry recorded: the OS has reused this pid for a different process instance. */
+ | "stale-reuse" | "over-age";
+export interface RegistryClassifyDeps {
+    isAlive: (pid: number) => boolean;
+    /** Live start identity for a pid, from the same ancestry snapshot the caller already took. `undefined` means "unknown" — never treated as evidence of reuse. */
+    liveStartId: (pid: number) => number | undefined;
+    now: number;
+    maxAgeMs: number;
+}
+export interface RegistryClassification {
+    keep: RegistryEntry[];
+    discard: Array<{
+        entry: RegistryEntry;
+        reason: DiscardReason;
+    }>;
+}
+/**
+ * Classify every entry except `ownPid`'s (the caller's own, just-written
+ * entry — always kept, never re-evaluated against its own freshly-recorded
+ * data). An entry is discarded the first reason that applies, in this
+ * order: dead pid; alive but identity mismatched beyond
+ * {@link START_ID_TOLERANCE_MS} (pid reuse) — only ever checked when the
+ * entry actually carries a `processStartId`; older than `maxAgeMs`.
+ * Anything else is kept.
+ *
+ * An entry with no verifiable `processStartId` at all (written by a build
+ * predating this field, or a torn/partial write) is **never used for
+ * identity matching** (`domain/ancestry-match.ts#findAncestorEntry` already
+ * requires both sides to carry a start id) — but that alone is no longer
+ * grounds for deletion here (F4): a live, in-age entry that merely cannot be
+ * verified is kept, exactly like a verified one, so a sweep run by an
+ * unrelated sibling process can never un-register a genuinely live
+ * orchestrator whose own start-time read happened to fail. It still gets
+ * cleaned up the ordinary way once its pid dies or it ages out — dead and
+ * over-age entries are discarded regardless of whether they carry a
+ * `processStartId`.
+ */
+export declare function classifyRegistryEntries(entries: RegistryEntry[], ownPid: number, deps: RegistryClassifyDeps): RegistryClassification;

package/dist/domain/registry-health.js

@@ -0,0 +1,58 @@
+/**
+ * Decide which machine-wide {@link RegistryEntry} rows a sweep should keep
+ * vs discard, and why. Pure, no I/O — `adapters/machine-process-registry.ts`
+ * drives this with real `isAlive`/`liveStartId`/`now`, and
+ * `adapters/kankaku-command.ts`'s `/kankaku doctor` reuses it (cheap mode,
+ * no fresh identity re-verification) to report registry health.
+ */
+import { START_ID_TOLERANCE_MS } from "./ancestry-match.js";
+/** Sane last-resort ceiling on an entry's age, regardless of aliveness/identity: 7 days. */
+export const DEFAULT_MAX_ENTRY_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Classify every entry except `ownPid`'s (the caller's own, just-written
+ * entry — always kept, never re-evaluated against its own freshly-recorded
+ * data). An entry is discarded the first reason that applies, in this
+ * order: dead pid; alive but identity mismatched beyond
+ * {@link START_ID_TOLERANCE_MS} (pid reuse) — only ever checked when the
+ * entry actually carries a `processStartId`; older than `maxAgeMs`.
+ * Anything else is kept.
+ *
+ * An entry with no verifiable `processStartId` at all (written by a build
+ * predating this field, or a torn/partial write) is **never used for
+ * identity matching** (`domain/ancestry-match.ts#findAncestorEntry` already
+ * requires both sides to carry a start id) — but that alone is no longer
+ * grounds for deletion here (F4): a live, in-age entry that merely cannot be
+ * verified is kept, exactly like a verified one, so a sweep run by an
+ * unrelated sibling process can never un-register a genuinely live
+ * orchestrator whose own start-time read happened to fail. It still gets
+ * cleaned up the ordinary way once its pid dies or it ages out — dead and
+ * over-age entries are discarded regardless of whether they carry a
+ * `processStartId`.
+ */
+export function classifyRegistryEntries(entries, ownPid, deps) {
+    const keep = [];
+    const discard = [];
+    for (const entry of entries) {
+        if (entry.pid === ownPid) {
+            keep.push(entry);
+            continue;
+        }
+        if (!deps.isAlive(entry.pid)) {
+            discard.push({ entry, reason: "dead" });
+            continue;
+        }
+        if (entry.processStartId !== undefined) {
+            const liveId = deps.liveStartId(entry.pid);
+            if (liveId !== undefined && Math.abs(liveId - entry.processStartId) > START_ID_TOLERANCE_MS) {
+                discard.push({ entry, reason: "stale-reuse" });
+                continue;
+            }
+        }
+        if (deps.now - Date.parse(entry.startedAt) > deps.maxAgeMs) {
+            discard.push({ entry, reason: "over-age" });
+            continue;
+        }
+        keep.push(entry);
+    }
+    return { keep, discard };
+}

package/dist/domain/segment-rule.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A rule that tags a tool execution as belonging to a named segment (e.g.
+ * `review`) when the tool name matches `tool` and the tool's argument text
+ * matches `pattern`.
+ */
+export interface SegmentRule {
+    tag: string;
+    tool: string;
+    pattern: RegExp;
+}

package/dist/domain/segment-rule.js

@@ -0,0 +1 @@
+export {};