kankaku 0.6.0 → 0.6.5

package/src/domain/hub-entry.ts

@@ -13,13 +13,15 @@
 import type { TaskView } from "./task-view.ts";
 import type { WorkRecord, WorkRole, WorkStatus } from "./work-record.ts";
 import { finiteOrZero } from "./work-record.ts";
-import type { Client, Project } from "./work-target.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}. */
@@ -39,6 +41,8 @@ export interface TaskAssignment {
   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. */
@@ -46,7 +50,8 @@ export interface TaskAssignment {
 }
 
 /**
- * Resolve which client/project a task's `task_entries` row should link to.
+ * 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
@@ -57,16 +62,25 @@ export interface TaskAssignment {
  *   `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: TaskView, clients: Client[], projects: Project[]): TaskAssignment {
+export function resolveTaskAssignment(task: TaskView, clients: Client[], projects: Project[], tasks: HubTask[]): TaskAssignment {
   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,
     };
@@ -76,6 +90,7 @@ export function resolveTaskAssignment(task: TaskView, clients: Client[], project
   return {
     clientId: unassigned ? unassigned.id : "",
     projectId: "",
+    hubTaskId: "",
     legacyClientLabel: task.client ?? task.clientName ?? "",
     routedToUnassigned: true,
   };
@@ -208,12 +223,12 @@ export type TaskEntryUpdatePayload = Omit<TaskEntryPayload, "client" | "project"
 
 /** Build the full `task_entries` payload for a **create** request — every field, including assignment. */
 export function buildTaskEntryCreatePayload(task: TaskView, ctx: HubEntryContext): TaskEntryPayload {
-  const assignment = resolveTaskAssignment(task, ctx.clients, ctx.projects);
+  const assignment = resolveTaskAssignment(task, ctx.clients, ctx.projects, ctx.tasks);
   return {
     task_id: task.id,
     client: assignment.clientId,
     project: assignment.projectId,
-    task: "",
+    task: assignment.hubTaskId,
     started_at: toPbDate(task.startedAt),
     ended_at: toPbDate(task.endedAt),
     wall_ms: task.wallMs,

package/src/domain/task-view.ts

@@ -36,6 +36,10 @@ export interface TaskView {
   projectId?: string;
   /** Hub project display name, from the orchestrator record only. */
   projectName?: string;
+  /** Hub task record id, from the orchestrator record only. See `domain/work-target.ts#HubTask`. */
+  hubTaskId?: string;
+  /** Hub task title, from the orchestrator record only. */
+  hubTaskTitle?: string;
   /**
    * Per-tag total milliseconds across the orchestrator and every subagent,
    * summed rather than unioned: unlike `wallMs`, segment intervals are not
@@ -368,6 +372,8 @@ function buildTaskView(orchestrator: WorkRecord, subagents: WorkRecord[]): TaskV
     ...(orchestrator.clientName !== undefined ? { clientName: orchestrator.clientName } : {}),
     ...(orchestrator.projectId !== undefined ? { projectId: orchestrator.projectId } : {}),
     ...(orchestrator.projectName !== undefined ? { projectName: orchestrator.projectName } : {}),
+    ...(orchestrator.hubTaskId !== undefined ? { hubTaskId: orchestrator.hubTaskId } : {}),
+    ...(orchestrator.hubTaskTitle !== undefined ? { hubTaskTitle: orchestrator.hubTaskTitle } : {}),
     project: orchestrator.project,
     prompt: orchestrator.prompt,
     startedAt: orchestrator.startedAt,

package/src/domain/work-record.ts

@@ -168,6 +168,10 @@ export interface WorkRecordMetadata {
   projectId?: string;
   /** Hub project display name, denormalised alongside `projectId`. */
   projectName?: string;
+  /** Hub `tasks` record id linked for this session (`/kankaku task pick`), when one is active. See `domain/work-target.ts#HubTask`. */
+  hubTaskId?: string;
+  /** Hub task title, denormalised alongside `hubTaskId`. */
+  hubTaskTitle?: string;
   /** This machine's hostname, or `KANKAKU_MACHINE`, set only when the hub is configured. */
   machine?: string;
   /**
@@ -210,6 +214,23 @@ export function finiteOrZero(value: unknown): number {
   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: { input: number; cacheRead: number; cacheWrite: number }): number | undefined {
+  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<WorkRole>(["orchestrator", "subagent"]);
 const STATUSES = new Set<WorkStatus>(["completed", "aborted", "interrupted"]);
 
@@ -267,6 +288,8 @@ export function isWorkRecord(value: unknown): value is WorkRecord {
     (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"])) &&

package/src/domain/work-target.ts

@@ -32,6 +32,19 @@ export interface Project {
   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;
@@ -39,12 +52,23 @@ export interface WorkTarget {
   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;
 }
 
 /**
@@ -63,6 +87,8 @@ export interface ResolveWorkTargetInput {
   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";
@@ -81,7 +107,18 @@ function findUsableProject(projects: Project[], projectId: string, clientId: str
   return project;
 }
 
-function buildTarget(client: Client, project: Project | undefined): WorkTarget {
+/**
+ * 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: HubTask[], taskId: string, projectId: string): HubTask | undefined {
+  const task = tasks.find((candidate) => candidate.id === taskId);
+  if (!task || task.projectId !== projectId) return undefined;
+  return task;
+}
+
+function buildTarget(client: Client, project: Project | undefined, task: HubTask | undefined): WorkTarget {
   return {
     clientId: client.id,
     clientCode: client.code,
@@ -93,6 +130,7 @@ function buildTarget(client: Client, project: Project | undefined): WorkTarget {
           projectName: project.name,
         }
       : {}),
+    ...(task !== undefined ? { hubTaskId: task.id, hubTaskTitle: task.title } : {}),
   };
 }
 
@@ -101,13 +139,17 @@ function buildTarget(client: Client, project: Project | undefined): WorkTarget {
  * 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.
+ * 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: WorkTargetCandidate, clients: Client[], projects: Project[]): WorkTarget | undefined {
+function resolveCandidate(candidate: WorkTargetCandidate, clients: Client[], projects: Project[], tasks: HubTask[]): WorkTarget | undefined {
   const client = findUsableClient(clients, candidate.clientId);
   if (!client) return undefined;
   const project = candidate.projectId !== undefined ? findUsableProject(projects, candidate.projectId, client.id) : undefined;
-  return buildTarget(client, project);
+  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. */
@@ -139,10 +181,11 @@ function isCwdWithin(cwd: string, repoPath: string): boolean {
 /** Which source (if any) {@link resolveWorkTarget} would use, computed independently so callers can display it. */
 export function resolveWorkTargetSource(input: ResolveWorkTargetInput): WorkTargetSourceName | undefined {
   const { session } = input;
+  const tasks = input.tasks ?? [];
   if (session === "skipped") return undefined;
-  if (session !== undefined && resolveCandidate(session, input.clients, input.projects) !== undefined) return "session";
+  if (session !== undefined && resolveCandidate(session, input.clients, input.projects, tasks) !== undefined) return "session";
 
-  if (input.project !== undefined && resolveCandidate(input.project, input.clients, input.projects) !== undefined) return "project";
+  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";
@@ -158,28 +201,34 @@ export function resolveWorkTargetSource(input: ResolveWorkTargetInput): WorkTarg
  */
 export function resolveWorkTarget(input: ResolveWorkTargetInput): WorkTarget | undefined {
   const { session } = input;
+  const tasks = input.tasks ?? [];
   if (session === "skipped") return undefined;
 
   if (session !== undefined) {
-    const resolved = resolveCandidate(session, input.clients, input.projects);
+    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);
+    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);
+    if (client) return buildTarget(client, matched, undefined);
   }
 
   return undefined;
 }
 
-/** `<clientName>` or `<clientName> · <projectName>` — the display label used by the status bar and the "remember" prompt. */
+/**
+ * `<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: WorkTarget): string {
-  return target.projectName ? `${target.clientName} · ${target.projectName}` : target.clientName;
+  const base = target.projectName ? `${target.clientName} · ${target.projectName}` : target.clientName;
+  return target.hubTaskTitle ? `${base} › ${target.hubTaskTitle}` : base;
 }

package/src/extension.ts

@@ -240,6 +240,7 @@ export default function kankaku(pi: ExtensionAPI): void {
         client,
         clients: snapshot?.clients ?? [],
         projects: snapshot?.projects ?? [],
+        tasks: snapshot?.tasks ?? [],
         machine: machineName,
         promptMode: syncConfig.promptMode,
         syncRecords: syncConfig.syncRecords,

package/src/ports/catalog.ts

@@ -1,11 +1,13 @@
-import type { Client, Project } from "../domain/work-target.ts";
+import type { Client, HubTask, Project } from "../domain/work-target.ts";
 
-/** A cached read of the hub's clients/projects, plus when and against which hub URL it was fetched. */
+/** A cached read of the hub's clients/projects/tasks, plus when and against which hub URL it was fetched. */
 export interface CatalogSnapshot {
   fetchedAt: number;
   url: string;
   clients: Client[];
   projects: Project[];
+  /** Optional because a cache written by an older build (before hub task linking) never had this field; a missing value reads as "no tasks known yet." */
+  tasks?: HubTask[];
 }
 
 /**