kankaku-pi 1.0.0

package/dist/domain/work-record.js

@@ -0,0 +1,91 @@
+/** Current schema version for {@link WorkRecord}. */
+export const WORK_RECORD_SCHEMA = 1;
+/** The `prompt` of a record no user prompt started — see {@link RunTrigger}. */
+export const EXTENSION_RUN_PROMPT = "(no user prompt — run started by an extension)";
+export function emptyUsage() {
+    return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+}
+/** A finite number, or `0` for `undefined`/`NaN`/`Infinity`/non-numbers. */
+export function finiteOrZero(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+/**
+ * Share of prompt input tokens served from the provider's prompt cache:
+ * `cacheRead / (input + cacheRead + cacheWrite)`. pi's `usage.input` maps to
+ * the provider's `input_tokens`, which already excludes cached tokens, so
+ * the three fields are disjoint and this sum is the true denominator.
+ * Returns `undefined` when the denominator is `0` (nothing to compute a
+ * ratio from) rather than `0`, so callers never render a misleading `0%`.
+ * Non-finite fields count as `0`, mirroring {@link finiteOrZero}.
+ */
+export function cacheHitRatio(usage) {
+    const input = finiteOrZero(usage.input);
+    const cacheRead = finiteOrZero(usage.cacheRead);
+    const cacheWrite = finiteOrZero(usage.cacheWrite);
+    const denominator = input + cacheRead + cacheWrite;
+    return denominator === 0 ? undefined : cacheRead / denominator;
+}
+const ROLES = new Set(["orchestrator", "subagent"]);
+const STATUSES = new Set(["completed", "aborted", "interrupted"]);
+/** A finite, non-negative number: durations such as `wallMs` can never be negative. */
+function isNonNegativeFinite(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function isOrchestratorRef(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const ref = value;
+    return (typeof ref["pid"] === "number" &&
+        typeof ref["project"] === "string" &&
+        typeof ref["startedAt"] === "string" &&
+        (ref["dir"] === undefined || typeof ref["dir"] === "string"));
+}
+/**
+ * Runtime guard for a {@link WorkRecord} read back from disk. `readAll`
+ * skips lines that parse as JSON but fail this check, so a torn write or a
+ * record from an incompatible schema does not crash task/session views.
+ */
+export function isWorkRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return (typeof record["schema"] === "number" &&
+        typeof record["id"] === "string" &&
+        ROLES.has(record["role"]) &&
+        typeof record["pid"] === "number" &&
+        typeof record["parentPid"] === "number" &&
+        typeof record["project"] === "string" &&
+        typeof record["prompt"] === "string" &&
+        typeof record["startedAt"] === "string" &&
+        typeof record["settledAt"] === "string" &&
+        isNonNegativeFinite(record["wallMs"]) &&
+        isNonNegativeFinite(record["waitingMs"]) &&
+        isNonNegativeFinite(record["workMs"]) &&
+        typeof record["runs"] === "number" &&
+        typeof record["turns"] === "number" &&
+        typeof record["tools"] === "object" &&
+        record["tools"] !== null &&
+        Array.isArray(record["subagents"]) &&
+        typeof record["usage"] === "object" &&
+        record["usage"] !== null &&
+        STATUSES.has(record["status"]) &&
+        (record["client"] === undefined || typeof record["client"] === "string") &&
+        (record["sessionName"] === undefined || typeof record["sessionName"] === "string") &&
+        (record["sessionDir"] === undefined || typeof record["sessionDir"] === "string") &&
+        (record["thinkingLevel"] === undefined || typeof record["thinkingLevel"] === "string") &&
+        (record["clientId"] === undefined || typeof record["clientId"] === "string") &&
+        (record["clientName"] === undefined || typeof record["clientName"] === "string") &&
+        (record["projectId"] === undefined || typeof record["projectId"] === "string") &&
+        (record["projectName"] === undefined || typeof record["projectName"] === "string") &&
+        (record["hubTaskId"] === undefined || typeof record["hubTaskId"] === "string") &&
+        (record["hubTaskTitle"] === undefined || typeof record["hubTaskTitle"] === "string") &&
+        (record["machine"] === undefined || typeof record["machine"] === "string") &&
+        (record["roleConfidence"] === undefined || record["roleConfidence"] === "uncertain") &&
+        (record["orchestratorRef"] === undefined || isOrchestratorRef(record["orchestratorRef"])) &&
+        (record["costObserved"] === undefined || record["costObserved"] === true) &&
+        (record["profile"] === undefined || typeof record["profile"] === "string") &&
+        (record["agent"] === undefined || typeof record["agent"] === "string") &&
+        (record["agentVersion"] === undefined || typeof record["agentVersion"] === "string") &&
+        (record["plugin"] === undefined || typeof record["plugin"] === "string") &&
+        (record["pluginVersion"] === undefined || typeof record["pluginVersion"] === "string"));
+}

package/dist/domain/work-target.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Hub work-target resolution: pure, no I/O.
+ *
+ * A `WorkTarget` identifies who a piece of work is billed to (client) and,
+ * optionally, which project it belongs to, both by PocketBase record id.
+ * Names travel alongside for display; no aggregation ever keys on a name
+ * (see `kankaku-pocketbase-proposal.md` D1).
+ *
+ * Resolution mirrors `client-label.ts#resolveClient`'s precedence pattern:
+ * session > project config file > catalog `repo_paths` match for the cwd >
+ * none. An id from any source that no longer resolves to an active,
+ * non-"unassigned" catalog row is treated as absent for that source and
+ * resolution falls through to the next one.
+ */
+export interface Client {
+    id: string;
+    name: string;
+    code: string;
+    active: boolean;
+    /** `true` only for the single "Sin determinar" row; never offered by the picker. */
+    unassigned?: boolean;
+}
+export interface Project {
+    id: string;
+    name: string;
+    code?: string;
+    clientId: string;
+    /** Absolute paths that map to this project; enables auto-selection by cwd. */
+    repoPaths: string[];
+    active: boolean;
+}
+/**
+ * A hub `tasks` row: something kankaku can link a session's `task_entries`
+ * row to (`task_entries.task`), never create. See `domain/hub-entry.ts` for
+ * the create-only assignment rule this feeds.
+ */
+export interface HubTask {
+    id: string;
+    title: string;
+    projectId: string;
+    status: "open" | "doing" | "done";
+    externalRef?: string;
+}
+export interface WorkTarget {
+    clientId: string;
+    clientCode: string;
+    clientName: string;
+    projectId?: string;
+    projectCode?: string;
+    projectName?: string;
+    /** Hub `tasks` record id, kept only when it belongs to `projectId`. See {@link resolveWorkTarget}. */
+    hubTaskId?: string;
+    /** Denormalised alongside `hubTaskId` for display. */
+    hubTaskTitle?: string;
+}
+/** ids picked from the session, or from the project's `.kankaku/config.json`. */
+export interface WorkTargetCandidate {
+    clientId: string;
+    projectId?: string;
+    /**
+     * A hub task the user picked for this session (`/kankaku task pick`).
+     * Only ever set on the session-level candidate — the project config file
+     * and `repoPaths` matching never carry one (task linking is session-only,
+     * see AGENTS.md).
+     */
+    hubTaskId?: string;
+}
+/**
+ * The session-level override: `undefined` when no session entry exists yet
+ * (resolution falls through to the project/repo-paths sources), the literal
+ * `"skipped"` when the user explicitly declined the picker (resolution
+ * stops here, at "no target", and does not fall through), or explicit ids.
+ */
+export type WorkTargetSessionOverride = "skipped" | WorkTargetCandidate | undefined;
+export interface ResolveWorkTargetInput {
+    session?: WorkTargetSessionOverride;
+    /** ids from the project's `.kankaku/config.json`. */
+    project?: WorkTargetCandidate;
+    /** Current working directory, matched against `Project.repoPaths`. */
+    cwd: string;
+    clients: Client[];
+    projects: Project[];
+    /** The hub's known tasks, to validate a candidate's `hubTaskId` against. Defaults to `[]` so existing callers compile unchanged. */
+    tasks?: HubTask[];
+}
+export type WorkTargetSourceName = "session" | "project" | "repoPaths";
+/** Which source (if any) {@link resolveWorkTarget} would use, computed independently so callers can display it. */
+export declare function resolveWorkTargetSource(input: ResolveWorkTargetInput): WorkTargetSourceName | undefined;
+/**
+ * Resolve the effective {@link WorkTarget}: session override > project
+ * config file > catalog `repo_paths` match for `cwd` > none. A `"skipped"`
+ * session override stops resolution immediately (the user explicitly
+ * declined), returning `undefined` rather than falling through.
+ */
+export declare function resolveWorkTarget(input: ResolveWorkTargetInput): WorkTarget | undefined;
+/**
+ * `<clientName>`, `<clientName> · <projectName>`, or with a linked hub task
+ * appended as `... › <hubTaskTitle>` — the display label used by the
+ * status bar and the "remember" prompt.
+ */
+export declare function formatWorkTargetLabel(target: WorkTarget): string;

package/dist/domain/work-target.js

@@ -0,0 +1,149 @@
+/**
+ * Hub work-target resolution: pure, no I/O.
+ *
+ * A `WorkTarget` identifies who a piece of work is billed to (client) and,
+ * optionally, which project it belongs to, both by PocketBase record id.
+ * Names travel alongside for display; no aggregation ever keys on a name
+ * (see `kankaku-pocketbase-proposal.md` D1).
+ *
+ * Resolution mirrors `client-label.ts#resolveClient`'s precedence pattern:
+ * session > project config file > catalog `repo_paths` match for the cwd >
+ * none. An id from any source that no longer resolves to an active,
+ * non-"unassigned" catalog row is treated as absent for that source and
+ * resolution falls through to the next one.
+ */
+/** A client usable as a work target: exists, active, and not the "unassigned" row. */
+function findUsableClient(clients, clientId) {
+    const client = clients.find((candidate) => candidate.id === clientId);
+    if (!client || !client.active || client.unassigned)
+        return undefined;
+    return client;
+}
+/** A project usable as a work target: exists, active, and belongs to `clientId`. */
+function findUsableProject(projects, projectId, clientId) {
+    const project = projects.find((candidate) => candidate.id === projectId);
+    if (!project || !project.active || project.clientId !== clientId)
+        return undefined;
+    return project;
+}
+/**
+ * A hub task usable as a link target: exists and belongs to `projectId`.
+ * Any {@link HubTask.status} is accepted — a task marked `done` mid-session
+ * keeps linking — only the project match matters here.
+ */
+function findUsableTask(tasks, taskId, projectId) {
+    const task = tasks.find((candidate) => candidate.id === taskId);
+    if (!task || task.projectId !== projectId)
+        return undefined;
+    return task;
+}
+function buildTarget(client, project, task) {
+    return {
+        clientId: client.id,
+        clientCode: client.code,
+        clientName: client.name,
+        ...(project !== undefined
+            ? {
+                projectId: project.id,
+                ...(project.code !== undefined ? { projectCode: project.code } : {}),
+                projectName: project.name,
+            }
+            : {}),
+        ...(task !== undefined ? { hubTaskId: task.id, hubTaskTitle: task.title } : {}),
+    };
+}
+/**
+ * Resolve a candidate (from the session override or the project config
+ * file) into a target, or `undefined` when the client id does not resolve
+ * to a usable client. A projectId that does not resolve to a usable
+ * project of that client is dropped — the client-only target is still
+ * returned — rather than failing the whole candidate. A `hubTaskId` is
+ * kept only when it resolves to a task of the resolved project; a target
+ * with no project never carries one.
+ */
+function resolveCandidate(candidate, clients, projects, tasks) {
+    const client = findUsableClient(clients, candidate.clientId);
+    if (!client)
+        return undefined;
+    const project = candidate.projectId !== undefined ? findUsableProject(projects, candidate.projectId, client.id) : undefined;
+    const task = project !== undefined && candidate.hubTaskId !== undefined ? findUsableTask(tasks, candidate.hubTaskId, project.id) : undefined;
+    return buildTarget(client, project, task);
+}
+/** The longest-matching active project whose `repoPaths` contains `cwd`, exactly or as an ancestor directory. */
+function matchByRepoPath(cwd, projects) {
+    let best;
+    let bestLength = -1;
+    for (const project of projects) {
+        if (!project.active)
+            continue;
+        for (const repoPath of project.repoPaths) {
+            if (!isCwdWithin(cwd, repoPath))
+                continue;
+            if (repoPath.length > bestLength) {
+                bestLength = repoPath.length;
+                best = project;
+            }
+        }
+    }
+    return best;
+}
+/** `true` when `cwd` equals `repoPath`, or is a subdirectory of it. */
+function isCwdWithin(cwd, repoPath) {
+    if (cwd === repoPath)
+        return true;
+    const withSeparator = repoPath.endsWith("/") ? repoPath : `${repoPath}/`;
+    return cwd.startsWith(withSeparator);
+}
+/** Which source (if any) {@link resolveWorkTarget} would use, computed independently so callers can display it. */
+export function resolveWorkTargetSource(input) {
+    const { session } = input;
+    const tasks = input.tasks ?? [];
+    if (session === "skipped")
+        return undefined;
+    if (session !== undefined && resolveCandidate(session, input.clients, input.projects, tasks) !== undefined)
+        return "session";
+    if (input.project !== undefined && resolveCandidate(input.project, input.clients, input.projects, tasks) !== undefined)
+        return "project";
+    const matched = matchByRepoPath(input.cwd, input.projects);
+    if (matched && findUsableClient(input.clients, matched.clientId))
+        return "repoPaths";
+    return undefined;
+}
+/**
+ * Resolve the effective {@link WorkTarget}: session override > project
+ * config file > catalog `repo_paths` match for `cwd` > none. A `"skipped"`
+ * session override stops resolution immediately (the user explicitly
+ * declined), returning `undefined` rather than falling through.
+ */
+export function resolveWorkTarget(input) {
+    const { session } = input;
+    const tasks = input.tasks ?? [];
+    if (session === "skipped")
+        return undefined;
+    if (session !== undefined) {
+        const resolved = resolveCandidate(session, input.clients, input.projects, tasks);
+        if (resolved)
+            return resolved;
+    }
+    if (input.project !== undefined) {
+        const resolved = resolveCandidate(input.project, input.clients, input.projects, tasks);
+        if (resolved)
+            return resolved;
+    }
+    const matched = matchByRepoPath(input.cwd, input.projects);
+    if (matched) {
+        const client = findUsableClient(input.clients, matched.clientId);
+        if (client)
+            return buildTarget(client, matched, undefined);
+    }
+    return undefined;
+}
+/**
+ * `<clientName>`, `<clientName> · <projectName>`, or with a linked hub task
+ * appended as `... › <hubTaskTitle>` — the display label used by the
+ * status bar and the "remember" prompt.
+ */
+export function formatWorkTargetLabel(target) {
+    const base = target.projectName ? `${target.clientName} · ${target.projectName}` : target.clientName;
+    return target.hubTaskTitle ? `${base} › ${target.hubTaskTitle}` : base;
+}

package/dist/domain/work-tracker.d.ts

@@ -0,0 +1,90 @@
+import type { Clock } from "../ports/clock.ts";
+import type { RunTrigger, UsageTotals, WorkRecordCore, WorkStatus } from "./work-record.ts";
+import type { SegmentRule } from "./segment-rule.ts";
+import type { SubagentProfile } from "./subagent-profile.ts";
+export interface WorkTrackerOptions {
+    clock: Clock;
+    interactiveTools: string[];
+    /** Every active {@link SubagentProfile} (ADR 0020); a tool call opens a subagent span when its name matches any profile's `toolNames`. See `config.ts#loadConfig`. */
+    subagentProfiles: SubagentProfile[];
+    /** Rules that tag a tool execution's span under a named segment. Defaults to none. */
+    segmentRules?: SegmentRule[];
+}
+interface RunEndMessage {
+    role: string;
+    stopReason?: string;
+}
+/**
+ * Pure domain state machine that turns pi lifecycle events into finished
+ * {@link WorkRecord} entries. Holds no I/O; timestamps come from the
+ * injected {@link Clock} so behaviour is deterministic under test.
+ */
+export declare class WorkTracker {
+    private readonly clock;
+    private readonly interactiveTools;
+    private readonly subagentProfiles;
+    private readonly segmentRules;
+    private state;
+    /** Set by {@link onRunStart}, consumed by {@link onAgentStart}: tells a user-announced run from one an extension started. */
+    private runAnnounced;
+    /** `true` between an agent loop's start and its `agent_end`. */
+    private loopActive;
+    /**
+     * The previous record, set aside because a new run began after its last
+     * loop ended but BEFORE its `agent_settled` reached us. pi clears its
+     * "run active" flag and only then awaits the `agent_settled` handlers, in
+     * extension load order; an extension loaded earlier (gentle-pi) can start
+     * the next run from its own handler. Whether that `agent_start` was a new
+     * run or an `agent.continue()` of the same one is only knowable at settle
+     * time — see {@link settleAll}.
+     */
+    private closing;
+    constructor(options: WorkTrackerOptions);
+    /**
+     * An agent loop actually started. pi announces a USER prompt with
+     * `before_agent_start` ({@link onRunStart}) and then this; a run an
+     * extension starts itself (`sendCustomMessage(..., { triggerTurn: true })`,
+     * how gentle-pi wakes the orchestrator when a background subagent
+     * finishes) only ever produces this one. Without it that whole run — its
+     * time, its cost, and the subagent spans it opens, which its children need
+     * to join — was never recorded.
+     */
+    onAgentStart(): void;
+    onRunStart(prompt: string, trigger?: RunTrigger): void;
+    private openRun;
+    onTurnEnd(usage: Partial<UsageTotals> | undefined): void;
+    onToolStart(toolCallId: string, toolName: string, args: Record<string, unknown> | undefined): void;
+    onToolEnd(toolCallId: string, result: unknown): void;
+    onUiPromptStart(_kind: string): void;
+    onUiPromptEnd(_kind: string): void;
+    onRunEnd(messages: RunEndMessage[]): void;
+    /** Single-record convenience over {@link settleAll}; production code uses `settleAll`. */
+    onSettled(): WorkRecordCore | undefined;
+    /**
+     * `agent_settled` arrived. Normally closes the one open record. When a
+     * record was set aside (see {@link closing}):
+     * - a loop is still running → the `agent_start` was a genuinely NEW run
+     *   that overtook this settle: close only the old record, at the instant
+     *   the new run began, and leave the new one open;
+     * - no loop is running → it was an `agent.continue()` of the same run
+     *   (retry, overflow recovery, queued message): fold it back, one record.
+     *   A user-announced prompt is never folded — it keeps its own record.
+     */
+    settleAll(): WorkRecordCore[];
+    /** Single-record convenience over {@link shutdownAll}. */
+    onShutdown(): WorkRecordCore | undefined;
+    /** The session is going away: every open record is written, the running one as `interrupted`. */
+    shutdownAll(): WorkRecordCore[];
+    /**
+     * Returns what {@link onSettled}/{@link onShutdown} would produce right
+     * now, without mutating any state: open spans are truncated only in the
+     * returned snapshot, so the tracker keeps running unaffected and a later
+     * `peek` or the eventual settle still sees the spans' true open-ended
+     * state. `undefined` when idle. The returned `id` matches the id the
+     * eventual settled record will carry, since both are generated once
+     * in {@link onRunStart}.
+     */
+    peek(status: WorkStatus): WorkRecordCore | undefined;
+    private buildRecordFrom;
+}
+export {};