kankaku 0.7.1 → 0.8.0

package/src/adapters/hub-actions.ts

@@ -6,15 +6,14 @@
  * see odd/tasks/kankaku-panel.md P4.
  */
 import type { CatalogSnapshot } from "../ports/catalog.ts";
-import type { SyncCommandDeps } from "./kankaku-command.ts";
-import type { SyncSummary } from "./sync-runner.ts";
+import type { SyncStatusSnapshot, SyncSummary } from "./sync-runner.ts";
 
 /**
  * `/kankaku sync status`'s report lines: the watermark, the pending count,
  * how many tasks fell outside this run's revisit window (R3), and the last
  * error, when any. Exact body of `handleSyncCommand`'s `status` branch.
  */
-export function buildSyncStatusLines(status: ReturnType<SyncCommandDeps["status"]>): string[] {
+export function buildSyncStatusLines(status: SyncStatusSnapshot): string[] {
   const { state, pending, staleOutsideWindow } = status;
   const lines = [state?.syncedThrough ? `synced through ${state.syncedThrough}` : "never synced", `pending: ${pending}`];
   if (staleOutsideWindow > 0) {

package/src/adapters/kankaku-command.ts

@@ -7,24 +7,20 @@ import { formatWorkTargetLabel } from "../domain/work-target.ts";
 import { findAmbiguousToolNames } from "../domain/subagent-profile.ts";
 import type { SubagentProfile } from "../domain/subagent-profile.ts";
 import type { RejectedChildEnvMarker } from "../config.ts";
-import type { SyncState } from "../domain/sync-plan.ts";
 import type { RegistryClassification } from "../domain/registry-health.ts";
 import type { Catalog } from "../ports/catalog.ts";
 import type { WorkLog } from "../ports/work-log.ts";
 import { buildSyncStatusLines, formatBackfillLines, formatCatalogRefreshLines, formatSyncSummaryLines } from "./hub-actions.ts";
 import { buildClientsView, buildExportContent, buildProjectsView, buildSessionsView, buildSummaryView, buildTasksView } from "./report-views.ts";
-import type { SyncSummary, SyncTrigger } from "./sync-runner.ts";
+import type { SyncStatusSnapshot, SyncSummary, SyncTrigger } from "./sync-runner.ts";
 import type { SessionClient } from "./session-client.ts";
 import { readNonDefaultSessionDir } from "./session-dir.ts";
 import type { SessionTarget } from "./session-target.ts";
+import type { KankakuReportData } from "./report-data.ts";
 
-const REPORT_ENTRY_TYPE = "kankaku-report";
+export type { KankakuReportData } from "./report-data.ts";
 
-/** Durable report rendered inside the chat transcript; never sent to the LLM. */
-export interface KankakuReportData {
-  title: string;
-  lines: string[];
-}
+const REPORT_ENTRY_TYPE = "kankaku-report";
 
 /** Notify the user of an error through the UI, when one is available. */
 export function notifyError(ctx: ExtensionContext, error: unknown): void {
@@ -217,7 +213,7 @@ export interface SyncCommandDeps {
    * count, and (R3) how many tasks changed since their last sync but fall
    * outside this run's revisit window — needs `sync all`. No network.
    */
-  status: () => { state: SyncState | undefined; pending: number; staleOutsideWindow: number };
+  status: () => SyncStatusSnapshot;
 }
 
 export interface KankakuCommandDeps {

package/src/adapters/pi-tracker.ts

@@ -496,6 +496,14 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
       ...(roleConfidence !== undefined ? { roleConfidence } : {}),
       ...(deps.orchestratorRef !== undefined ? { orchestratorRef: deps.orchestratorRef } : {}),
       ...(deps.profile !== undefined ? { profile: deps.profile } : {}),
+      // Who measured this record, not who later syncs it — see
+      // `domain/work-record.ts#WorkRecordMetadata.agent`. Always stamped for
+      // every record this process appends; the versions are the same ones
+      // `extension.ts` already resolves for the `about` screen.
+      agent: "pi",
+      ...(deps.agentVersion !== undefined ? { agentVersion: deps.agentVersion } : {}),
+      plugin: "kankaku",
+      ...(deps.pluginVersion !== undefined ? { pluginVersion: deps.pluginVersion } : {}),
     };
   }
 

package/src/adapters/report-data.ts

@@ -0,0 +1,13 @@
+/**
+ * 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/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/src/adapters/report-views.ts

@@ -9,7 +9,7 @@
 import { buildSessions, buildTasks } from "../domain/task-view.ts";
 import { exportRows, toCsv, toJson } from "../domain/export.ts";
 import type { WorkRecord } from "../domain/work-record.ts";
-import type { KankakuReportData } from "./kankaku-command.ts";
+import type { KankakuReportData } from "./report-data.ts";
 import { countUncertain, formatClients, formatProjects, formatReport, formatSessions, formatTasks, localDay, summarize, summarizeByClient, summarizeByProject } from "./report.ts";
 
 /** Shared by every view except `buildTasksView`: `all` includes every day, otherwise only today's local day. */

package/src/adapters/sync-runner.ts

@@ -250,12 +250,31 @@ function persistError(deps: SyncRunnerDeps, state: ReturnType<SyncStateStore["re
   });
 }
 
-/** Number of tasks pending a sync right now, for `/kankaku sync status` — computed locally, no network. */
+/**
+ * Number of tasks pending a sync right now — computed locally, no network.
+ *
+ * @deprecated Superseded by {@link computeSyncStatus}, which returns the same
+ * `pending` count together with `state` and `staleOutsideWindow`. Nothing in
+ * kankaku calls this any more; it stays only because it is part of the
+ * published `kankaku/hub` surface. It will be removed in the next minor.
+ */
 export function pendingCount(tasks: TaskView[], state: ReturnType<SyncStateStore["read"]>, target: string, windowHours?: number): number {
   const plan = planSync(tasks, state, { target, ...(windowHours !== undefined ? { windowHours } : {}) });
   return plan.toSync.length + plan.correctionsDeferred;
 }
 
+/**
+ * {@link computeSyncStatus}'s return shape, exported so a caller (e.g.
+ * `hub-actions.ts#buildSyncStatusLines`, or a future standalone TUI reusing
+ * `kankaku/hub`) can depend on this type without importing anything that
+ * touches `@earendil-works/*` — see AGENTS.md "Code conventions".
+ */
+export interface SyncStatusSnapshot {
+  state: SyncState | undefined;
+  pending: number;
+  staleOutsideWindow: number;
+}
+
 /**
  * `/kankaku sync status`: the persisted state, a locally-computed pending
  * count, and (R3) how many tasks changed since their last sync but fall
@@ -263,12 +282,7 @@ export function pendingCount(tasks: TaskView[], state: ReturnType<SyncStateStore
  * (see `domain/sync-plan.ts#SyncPlan.staleOutsideWindow`, and README "Hub
  * (PocketBase)" > "Sync" > "Limitations"). No network.
  */
-export function computeSyncStatus(
-  log: WorkLog,
-  stateStore: SyncStateStore,
-  target: string,
-  windowHours?: number,
-): { state: ReturnType<SyncStateStore["read"]>; pending: number; staleOutsideWindow: number } {
+export function computeSyncStatus(log: WorkLog, stateStore: SyncStateStore, target: string, windowHours?: number): SyncStatusSnapshot {
   const state = stateStore.read();
   const tasks = buildTasks(log.readAll());
   const plan = planSync(tasks, state, { target, ...(windowHours !== undefined ? { windowHours } : {}) });

package/src/domain/hub-entry.ts

@@ -207,10 +207,12 @@ export interface TaskEntryPayload {
   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;
@@ -218,12 +220,59 @@ export interface TaskEntryPayload {
   subagent_linkage: SubagentLinkage;
 }
 
-/** `TaskEntryPayload` minus the assignment fields — what an update sends. See the module docs' CRITICAL rule. */
-export type TaskEntryUpdatePayload = Omit<TaskEntryPayload, "client" | "project" | "task" | "legacy_client_label">;
+/**
+ * `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;
+};
+
+/**
+ * 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: TaskView,
+  ctx: HubEntryContext,
+): { agent: string; agentVersion?: string; plugin: string; pluginVersion?: string } {
+  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: TaskView, ctx: HubEntryContext): TaskEntryPayload {
   const assignment = resolveTaskAssignment(task, ctx.clients, ctx.projects, ctx.tasks);
+  const identity = resolveTaskIdentity(task, ctx);
   return {
     task_id: task.id,
     client: assignment.clientId,
@@ -253,11 +302,11 @@ export function buildTaskEntryCreatePayload(task: TaskView, ctx: HubEntryContext
     legacy_client_label: assignment.legacyClientLabel,
     repo_project: task.project,
     schema: task.orchestrator.schema,
-    agent: ctx.agent,
-    ...(ctx.agentVersion !== undefined ? { agent_version: ctx.agentVersion } : {}),
+    agent: identity.agent,
+    ...(identity.agentVersion !== undefined ? { agent_version: identity.agentVersion } : {}),
     ...(task.sessionDir !== undefined ? { session_dir: task.sessionDir } : {}),
-    plugin: ctx.plugin,
-    ...(ctx.pluginVersion !== undefined ? { plugin_version: ctx.pluginVersion } : {}),
+    plugin: identity.plugin,
+    ...(identity.pluginVersion !== undefined ? { plugin_version: identity.pluginVersion } : {}),
     waiting_quality: computeWaitingQuality(),
     cost_quality: computeCostQuality(task),
     subagent_linkage: computeSubagentLinkage(task),
@@ -269,10 +318,40 @@ export function buildTaskEntryCreatePayload(task: TaskView, ctx: HubEntryContext
  * 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: TaskView, ctx: HubEntryContext): TaskEntryUpdatePayload {
-  const { client: _client, project: _project, task: _task, legacy_client_label: _legacy, ...rest } = buildTaskEntryCreatePayload(task, ctx);
-  return rest;
+  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 } : {}),
+  };
 }
 
 /** One `work_records` row — raw per-`WorkRecord` detail, always `rollup: false`. */

package/src/domain/sync-plan.ts

@@ -134,6 +134,16 @@ export function computeTaskContentHash(task: TaskView): string {
       // `undefined` is dropped by the serialiser, so a task that never knew
       // its reasoning effort keeps the hash it had before this field existed.
       thinkingLevel: task.orchestrator.thinkingLevel,
+      // A task gaining a who-measured identity
+      // (domain/hub-entry.ts#resolveTaskIdentity) must resync, since it
+      // changes which agent/plugin the row is attributed to; the version
+      // fields are left out on purpose so a version-only bump alone does not
+      // force a resync. The keys are added CONDITIONALLY: `stableStringify`
+      // renders an `undefined` value as `"agent":undefined`, so an
+      // unconditional key would change every legacy task's hash and force a
+      // full resync right after upgrading (see the golden-hash test).
+      ...(task.orchestrator.agent !== undefined ? { agent: task.orchestrator.agent } : {}),
+      ...(task.orchestrator.plugin !== undefined ? { plugin: task.orchestrator.plugin } : {}),
     }),
   );
 }

package/src/domain/work-record.ts

@@ -201,6 +201,23 @@ export interface WorkRecordMetadata {
    * (SUBAGENT-REQ-017). Never set on an `orchestrator` record.
    */
   profile?: string;
+  /**
+   * Coding agent that MEASURED this record, lowercase slug (e.g. `"pi"`).
+   * Who measured, not who syncs — a different process (a standalone
+   * `kankaku` TUI, or a session for a different agent sharing the same
+   * `worklog.jsonl`) may later push this record to the hub, and must never
+   * overwrite this identity with its own. See kankaku-hub `docs/contract.md`
+   * "Agent and measurement quality" and `domain/hub-entry.ts`. Optional and
+   * additive: `WORK_RECORD_SCHEMA` is unchanged and an older record without
+   * it still validates.
+   */
+  agent?: string;
+  /** The measuring agent'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 record, lowercase slug (e.g. `"kankaku"`). Same who-measured-not-who-syncs rule as {@link agent}. */
+  plugin?: string;
+  /** This integration's own version, from its `package.json`, read once. */
+  pluginVersion?: string;
 }
 
 export type WorkRecord = WorkRecordCore & WorkRecordMetadata;
@@ -294,6 +311,10 @@ export function isWorkRecord(value: unknown): value is WorkRecord {
     (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["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/src/hub/index.ts

@@ -7,7 +7,9 @@
  * for which ones and why.
  */
 export * from "../adapters/cached-catalog.ts";
+export * from "../adapters/export-writer.ts";
 export * from "../adapters/file-modes.ts";
+export * from "../adapters/hub-actions.ts";
 export * from "../adapters/hub-credentials.ts";
 export * from "../adapters/jsonl-work-log.ts";
 export * from "../adapters/kankaku-dir.ts";
@@ -15,5 +17,9 @@ export * from "../adapters/lazy-jsonl-work-log.ts";
 export * from "../adapters/pocketbase-catalog.ts";
 export * from "../adapters/pocketbase-client.ts";
 export * from "../adapters/pocketbase-sink.ts";
+export * from "../adapters/project-config.ts";
+export * from "../adapters/report-data.ts";
+export * from "../adapters/report.ts";
+export * from "../adapters/report-views.ts";
 export * from "../adapters/sync-runner.ts";
 export * from "../adapters/sync-state-store.ts";