@kangentic/protocol 0.9.0 → 0.11.0

package/dist/capabilities/board-tools.d.ts

@@ -13,8 +13,8 @@
  * this protocol surface honest: a tool renamed or removed desktop-side
  * fails that test instead of silently breaking phones.
  */
-export declare const BOARD_TOOL_READ_NAMES: readonly ["search_tasks", "find_task", "get_current_task", "get_task_stats", "get_usage_stats", "board_summary", "list_sessions", "get_session_history", "get_column_detail", "get_handoff_context", "get_transcript", "get_session_files", "get_session_events", "get_activity_intervals"];
-export declare const BOARD_TOOL_WRITE_NAMES: readonly ["create_task", "update_task", "delete_task", "link_pr", "remove_attachment", "update_column", "create_backlog_task", "promote_backlog", "update_backlog_item", "delete_backlog_item"];
+export declare const BOARD_TOOL_READ_NAMES: readonly ["search_tasks", "find_task", "get_current_task", "get_task_stats", "get_usage_stats", "board_summary", "list_sessions", "get_session_history", "get_column_detail", "list_board_profiles", "get_handoff_context", "get_transcript", "get_session_files", "get_session_events", "get_activity_intervals"];
+export declare const BOARD_TOOL_WRITE_NAMES: readonly ["create_task", "update_task", "delete_task", "link_pr", "remove_attachment", "update_column", "create_board_profile", "update_board_profile", "delete_board_profile", "create_backlog_task", "promote_backlog", "update_backlog_item", "delete_backlog_item"];
 export type BoardToolReadName = (typeof BOARD_TOOL_READ_NAMES)[number];
 export type BoardToolWriteName = (typeof BOARD_TOOL_WRITE_NAMES)[number];
 export type BoardToolName = BoardToolReadName | BoardToolWriteName;

package/dist/events/payloads.d.ts

@@ -167,6 +167,44 @@ export interface SessionUsageWire {
         effort?: string;
     };
 }
+/**
+ * Phone-needed subset of the desktop's SessionSummary: what a task COST over
+ * its whole life, as opposed to SessionUsageWire's live snapshot of one
+ * running agent.
+ *
+ * Every figure is a lifetime aggregate across every session record of the
+ * task, which is what makes it meaningful for a completed one: a task worked
+ * across five `--resume` legs has five session rows, and reporting only the
+ * final leg would under-report everything. The desktop's getSummaryForTask
+ * owns those aggregation rules (SUM cost/duration/tool calls/lines, MAX files
+ * changed, and tokens taken as the latest row per session lineage so a
+ * resumed session is not double-counted) - they are not re-derived here.
+ *
+ * `sessionId` is the transcript ANCHOR, not a live session: it resolves
+ * through the desktop's session records, which outlive the agent, so it reads
+ * a finished task's conversation with nothing running. An archived task's
+ * `session_id` on the board is null by then, so this is the only handle to it.
+ */
+export interface SessionSummaryWire {
+    sessionId: string;
+    totalCostUsd: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    modelDisplayName: string;
+    durationMs: number;
+    toolCallCount: number;
+    compactionCount: number;
+    linesAdded: number;
+    linesRemoved: number;
+    filesChanged: number;
+    /** ISO 8601. The task's creation, which is where its timeline starts. */
+    taskCreatedAt: string;
+    /** ISO 8601. Earliest session start across every leg. */
+    startedAt: string;
+    /** ISO 8601, or null while a leg is still open. Latest exit or suspend. */
+    exitedAt: string | null;
+    exitCode: number | null;
+}
 /**
  * Loose mirror of the desktop's SessionEvent telemetry entry. `type` is
  * deliberately a plain string, not the desktop's EventType enum, so a new
@@ -267,6 +305,16 @@ export declare function isActivityStateWire(value: unknown): value is ActivitySt
 export declare function isActivityReasonWire(value: unknown): value is ActivityReasonWire;
 /** Narrows a usage payload to the SessionUsageWire subset. Throws on a malformed required field. */
 export declare function parseSessionUsageWire(payload: JsonValue): SessionUsageWire;
+/**
+ * Narrows a session-summary payload to SessionSummaryWire. Throws on a
+ * malformed required field.
+ *
+ * The numeric metrics are required rather than optional because the desktop
+ * COALESCEs each to 0 before it sends them, so "no data" arrives as a real
+ * zero. Making them optional here would invite a phone to render an em-dash
+ * where the honest answer is 0.
+ */
+export declare function parseSessionSummaryWire(payload: JsonValue): SessionSummaryWire;
 /** Narrows a session-event payload to SessionEventWire. Throws on a malformed required field. */
 export declare function parseSessionEventWire(payload: JsonValue): SessionEventWire;
 /** Narrows one board-column row. Throws on a malformed required field. */

package/dist/index.cjs

@@ -88,6 +88,7 @@ __export(index_exports, {
   parseReadStreamResponsePayload: () => parseReadStreamResponsePayload,
   parseRegisterPushRequestPayload: () => parseRegisterPushRequestPayload,
   parseSessionEventWire: () => parseSessionEventWire,
+  parseSessionSummaryWire: () => parseSessionSummaryWire,
   parseSessionUsageWire: () => parseSessionUsageWire,
   parseTerminalDimensionsWire: () => parseTerminalDimensionsWire,
   parseTranscriptEntriesWire: () => parseTranscriptEntriesWire,
@@ -5364,6 +5365,26 @@ function parseSessionUsageWire(payload) {
     }
   };
 }
+function parseSessionSummaryWire(payload) {
+  if (!isRecord(payload)) throw new Error("session summary payload must be an object");
+  return {
+    sessionId: requireString(payload, "sessionId", "session summary"),
+    totalCostUsd: requireNumber(payload, "totalCostUsd", "session summary"),
+    totalInputTokens: requireNumber(payload, "totalInputTokens", "session summary"),
+    totalOutputTokens: requireNumber(payload, "totalOutputTokens", "session summary"),
+    modelDisplayName: requireString(payload, "modelDisplayName", "session summary"),
+    durationMs: requireNumber(payload, "durationMs", "session summary"),
+    toolCallCount: requireNumber(payload, "toolCallCount", "session summary"),
+    compactionCount: requireNumber(payload, "compactionCount", "session summary"),
+    linesAdded: requireNumber(payload, "linesAdded", "session summary"),
+    linesRemoved: requireNumber(payload, "linesRemoved", "session summary"),
+    filesChanged: requireNumber(payload, "filesChanged", "session summary"),
+    taskCreatedAt: requireString(payload, "taskCreatedAt", "session summary"),
+    startedAt: requireString(payload, "startedAt", "session summary"),
+    exitedAt: typeof payload.exitedAt === "string" ? payload.exitedAt : null,
+    exitCode: typeof payload.exitCode === "number" ? payload.exitCode : null
+  };
+}
 function parseSessionEventWire(payload) {
   if (!isRecord(payload)) throw new Error("session event payload must be an object");
   return {
@@ -5566,6 +5587,18 @@ function parseAccentColor(value, context) {
 }
 function parseReadBoardResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("read-board response must be an object");
+  if (Array.isArray(payload.archivedTasks)) {
+    if (typeof payload.projectId !== "string") throw new Error('read-board archived response is missing "projectId"');
+    if (typeof payload.archivedTotalCount !== "number") {
+      throw new Error('read-board archived response is missing "archivedTotalCount"');
+    }
+    return {
+      projectId: payload.projectId,
+      archivedTasks: payload.archivedTasks.map((task) => parseBoardTaskWire(task)),
+      archivedTotalCount: payload.archivedTotalCount,
+      summariesByTaskId: parseSummariesByTaskId(payload.summariesByTaskId)
+    };
+  }
   if (Array.isArray(payload.projects)) {
     const projects = payload.projects.map((project, index) => {
       if (!isRecord(project) || typeof project.id !== "string" || typeof project.name !== "string") {
@@ -5574,10 +5607,15 @@ function parseReadBoardResponsePayload(payload) {
       return {
         id: project.id,
         name: project.name,
-        ...project.color !== void 0 ? { color: parseAccentColor(project.color, `read-board project ${index}`) } : {}
+        ...project.color !== void 0 ? { color: parseAccentColor(project.color, `read-board project ${index}`) } : {},
+        ...typeof project.groupId === "string" ? { groupId: project.groupId } : {},
+        ...typeof project.position === "number" ? { position: project.position } : {}
       };
     });
-    return { projects };
+    const groups = Array.isArray(payload.groups) ? payload.groups.flatMap(
+      (group) => isRecord(group) && typeof group.id === "string" && typeof group.name === "string" && typeof group.position === "number" ? [{ id: group.id, name: group.name, position: group.position }] : []
+    ) : void 0;
+    return { projects, ...groups !== void 0 ? { groups } : {} };
   }
   if (typeof payload.projectId !== "string") throw new Error('read-board response is missing "projectId"');
   if (!Array.isArray(payload.columns)) throw new Error('read-board response is missing "columns"');
@@ -5610,18 +5648,42 @@ function parseTaskCountsByColumnId(value) {
   }
   return counts;
 }
+function parseSummariesByTaskId(value) {
+  if (value === void 0) return {};
+  if (!isRecord(value)) throw new Error('read-board archived response has a non-object "summariesByTaskId"');
+  const summaries = {};
+  for (const [taskId, summary] of Object.entries(value)) {
+    try {
+      summaries[taskId] = parseSessionSummaryWire(summary);
+    } catch {
+    }
+  }
+  return summaries;
+}
 function parseReadBoardRequestPayload(payload) {
   if (!isRecord(payload)) throw new Error("read-board payload must be an object");
   if (payload.projectId !== void 0 && typeof payload.projectId !== "string") {
     throw new Error('read-board payload has a non-string "projectId"');
   }
-  if (payload.action !== void 0 && payload.action !== "subscribe" && payload.action !== "unsubscribe") {
+  if (payload.action !== void 0 && payload.action !== "subscribe" && payload.action !== "unsubscribe" && payload.action !== "archived") {
     throw new Error('read-board payload has an invalid "action"');
   }
   if (payload.view !== void 0 && payload.view !== "full" && payload.view !== "sessions") {
     throw new Error('read-board payload has an invalid "view"');
   }
-  return { projectId: payload.projectId, action: payload.action, view: payload.view };
+  if (payload.limit !== void 0 && (typeof payload.limit !== "number" || !Number.isInteger(payload.limit) || payload.limit < 1)) {
+    throw new Error('read-board payload has an invalid "limit"');
+  }
+  if (payload.offset !== void 0 && (typeof payload.offset !== "number" || !Number.isInteger(payload.offset) || payload.offset < 0)) {
+    throw new Error('read-board payload has an invalid "offset"');
+  }
+  return {
+    projectId: payload.projectId,
+    action: payload.action,
+    view: payload.view,
+    limit: payload.limit,
+    offset: payload.offset
+  };
 }
 function parseReadDiffResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("read-diff response must be an object");
@@ -5942,6 +6004,7 @@ var BOARD_TOOL_READ_NAMES = [
   "list_sessions",
   "get_session_history",
   "get_column_detail",
+  "list_board_profiles",
   "get_handoff_context",
   "get_transcript",
   "get_session_files",
@@ -5955,6 +6018,9 @@ var BOARD_TOOL_WRITE_NAMES = [
   "link_pr",
   "remove_attachment",
   "update_column",
+  "create_board_profile",
+  "update_board_profile",
+  "delete_board_profile",
   "create_backlog_task",
   "promote_backlog",
   "update_backlog_item",
@@ -6122,6 +6188,7 @@ function isBridgeEvent(value) {
   parseReadStreamResponsePayload,
   parseRegisterPushRequestPayload,
   parseSessionEventWire,
+  parseSessionSummaryWire,
   parseSessionUsageWire,
   parseTerminalDimensionsWire,
   parseTranscriptEntriesWire,

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export type { JsonValue, BridgeMessage, HeartbeatMessage, CapabilityRequestMessa
 export { encodeMessage, decodeMessage, MAX_FRAME_LENGTH, MAX_DECODED_LENGTH, COMPRESSION_THRESHOLD } from './wire/framing';
 export { isJsonValue, isRecord } from './wire/json-value';
 export { SessionFrameKind, wrapSessionFrame, unwrapSessionFrame } from './wire/session-frame';
-export { parseCapabilityRequestPayload, parseReadStreamResponsePayload, parseReadBoardResponsePayload, parseReadDiffResponsePayload, parseTranscriptWindowResponsePayload, parseRegisterPushRequestPayload, type CapabilityRequestPayloadMap, type CapabilityResponsePayloadMap, type ReadStreamRequestPayload, type ReadStreamResponsePayload, type ReadStreamSessionStatusWire, type TranscriptWindowResponsePayload, type ReadBoardRequestPayload, type ReadBoardView, type ReadBoardProjectSummary, type ReadBoardProjectListResponsePayload, type ReadBoardSnapshotResponsePayload, type ReadBoardResponsePayload, type ReadDiffScope, type ReadDiffRequestPayload, type ReadDiffResponsePayload, type SendUserMessageRequestPayload, type SendUserMessageResponsePayload, type MoveTaskRequestPayload, type MoveTaskResponsePayload, type AnswerPermissionPromptRequestPayload, type AnswerPermissionPromptResponsePayload, type InteractiveTerminalRequestPayload, type InteractiveTerminalResponsePayload, type BoardToolRequestPayload, type BoardToolResponsePayload, type RegisterPushRequestPayload, type RegisterPushResponsePayload, } from './wire/payloads';
+export { parseCapabilityRequestPayload, parseReadStreamResponsePayload, parseReadBoardResponsePayload, parseReadDiffResponsePayload, parseTranscriptWindowResponsePayload, parseRegisterPushRequestPayload, type CapabilityRequestPayloadMap, type CapabilityResponsePayloadMap, type ReadStreamRequestPayload, type ReadStreamResponsePayload, type ReadStreamSessionStatusWire, type TranscriptWindowResponsePayload, type ReadBoardRequestPayload, type ReadBoardView, type ReadBoardProjectSummary, type ReadBoardProjectGroup, type ReadBoardProjectListResponsePayload, type ReadBoardSnapshotResponsePayload, type ReadBoardArchivedResponsePayload, type ReadBoardResponsePayload, type ReadDiffScope, type ReadDiffRequestPayload, type ReadDiffResponsePayload, type SendUserMessageRequestPayload, type SendUserMessageResponsePayload, type MoveTaskRequestPayload, type MoveTaskResponsePayload, type AnswerPermissionPromptRequestPayload, type AnswerPermissionPromptResponsePayload, type InteractiveTerminalRequestPayload, type InteractiveTerminalResponsePayload, type BoardToolRequestPayload, type BoardToolResponsePayload, type RegisterPushRequestPayload, type RegisterPushResponsePayload, } from './wire/payloads';
 export { PUSH_CATEGORIES, isPushCategory, parsePushEnvelopePlaintext, sealPushEnvelope, openPushEnvelope, PUSH_ENVELOPE_MAX_AGE_MS, PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS, type PushCategory, type PushEnvelopePlaintext, } from './crypto/push-envelope';
 export { PAIRING_URI_SCHEME, encodePairingQrPayload, decodePairingQrPayload, type PairingQrPayload, } from './pairing/qr';
 export { sealPairingConfirm, openPairingConfirm } from './pairing/confirm';
@@ -22,5 +22,5 @@ export { formatKeyFingerprint } from './roster/fingerprint';
 export { CAPABILITY_VERBS, isCapabilityVerb, capabilitySetFromArray, capabilitySetToArray, type CapabilityVerb, type CapabilitySet, } from './capabilities/verbs';
 export { BOARD_TOOL_READ_NAMES, BOARD_TOOL_WRITE_NAMES, isBoardToolReadName, isBoardToolWriteName, type BoardToolReadName, type BoardToolWriteName, type BoardToolName, } from './capabilities/board-tools';
 export { isBridgeEvent, parseActivityEventPayload, type BridgeEvent, type TranscriptEvent, type ActivityEvent, type ActivityEventPayload, type TerminalEvent, type TerminalResizeEvent, type BoardEvent, type BoardEventPayload, type DiffEvent, } from './events/event';
-export { parseTranscriptEntriesWire, parseTranscriptEventPayload, type TranscriptEventPayload, type TranscriptUpsertWire, isActivityStateWire, isActivityReasonWire, parseSessionUsageWire, parseSessionEventWire, parseTerminalDimensionsWire, parseBoardColumnWire, parseBoardTaskWire, parseBacklogItemWire, parseDiffFileListWire, parseDiffFileContentWire, type TranscriptBlockWire, type TranscriptEntryWire, type TranscriptTurnUsageWire, type TranscriptSystemSubtypeWire, type ActivityStateWire, type ActivityReasonWire, type SessionUsageWire, type SessionEventWire, type TerminalDimensionsWire, type BoardColumnWire, type BoardTaskWire, type BacklogItemWire, type DiffFileStatusWire, type DiffFileWire, type DiffFileListWire, type DiffFileContentWire, } from './events/payloads';
+export { parseTranscriptEntriesWire, parseTranscriptEventPayload, type TranscriptEventPayload, type TranscriptUpsertWire, isActivityStateWire, isActivityReasonWire, parseSessionUsageWire, parseSessionSummaryWire, parseSessionEventWire, parseTerminalDimensionsWire, parseBoardColumnWire, parseBoardTaskWire, parseBacklogItemWire, parseDiffFileListWire, parseDiffFileContentWire, type TranscriptBlockWire, type TranscriptEntryWire, type TranscriptTurnUsageWire, type TranscriptSystemSubtypeWire, type ActivityStateWire, type ActivityReasonWire, type SessionUsageWire, type SessionSummaryWire, type SessionEventWire, type TerminalDimensionsWire, type BoardColumnWire, type BoardTaskWire, type BacklogItemWire, type DiffFileStatusWire, type DiffFileWire, type DiffFileListWire, type DiffFileContentWire, } from './events/payloads';
 export type { Transport, TransportState, Unsubscribe } from './transport/transport';

package/dist/index.mjs

@@ -5248,6 +5248,26 @@ function parseSessionUsageWire(payload) {
     }
   };
 }
+function parseSessionSummaryWire(payload) {
+  if (!isRecord(payload)) throw new Error("session summary payload must be an object");
+  return {
+    sessionId: requireString(payload, "sessionId", "session summary"),
+    totalCostUsd: requireNumber(payload, "totalCostUsd", "session summary"),
+    totalInputTokens: requireNumber(payload, "totalInputTokens", "session summary"),
+    totalOutputTokens: requireNumber(payload, "totalOutputTokens", "session summary"),
+    modelDisplayName: requireString(payload, "modelDisplayName", "session summary"),
+    durationMs: requireNumber(payload, "durationMs", "session summary"),
+    toolCallCount: requireNumber(payload, "toolCallCount", "session summary"),
+    compactionCount: requireNumber(payload, "compactionCount", "session summary"),
+    linesAdded: requireNumber(payload, "linesAdded", "session summary"),
+    linesRemoved: requireNumber(payload, "linesRemoved", "session summary"),
+    filesChanged: requireNumber(payload, "filesChanged", "session summary"),
+    taskCreatedAt: requireString(payload, "taskCreatedAt", "session summary"),
+    startedAt: requireString(payload, "startedAt", "session summary"),
+    exitedAt: typeof payload.exitedAt === "string" ? payload.exitedAt : null,
+    exitCode: typeof payload.exitCode === "number" ? payload.exitCode : null
+  };
+}
 function parseSessionEventWire(payload) {
   if (!isRecord(payload)) throw new Error("session event payload must be an object");
   return {
@@ -5450,6 +5470,18 @@ function parseAccentColor(value, context) {
 }
 function parseReadBoardResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("read-board response must be an object");
+  if (Array.isArray(payload.archivedTasks)) {
+    if (typeof payload.projectId !== "string") throw new Error('read-board archived response is missing "projectId"');
+    if (typeof payload.archivedTotalCount !== "number") {
+      throw new Error('read-board archived response is missing "archivedTotalCount"');
+    }
+    return {
+      projectId: payload.projectId,
+      archivedTasks: payload.archivedTasks.map((task) => parseBoardTaskWire(task)),
+      archivedTotalCount: payload.archivedTotalCount,
+      summariesByTaskId: parseSummariesByTaskId(payload.summariesByTaskId)
+    };
+  }
   if (Array.isArray(payload.projects)) {
     const projects = payload.projects.map((project, index) => {
       if (!isRecord(project) || typeof project.id !== "string" || typeof project.name !== "string") {
@@ -5458,10 +5490,15 @@ function parseReadBoardResponsePayload(payload) {
       return {
         id: project.id,
         name: project.name,
-        ...project.color !== void 0 ? { color: parseAccentColor(project.color, `read-board project ${index}`) } : {}
+        ...project.color !== void 0 ? { color: parseAccentColor(project.color, `read-board project ${index}`) } : {},
+        ...typeof project.groupId === "string" ? { groupId: project.groupId } : {},
+        ...typeof project.position === "number" ? { position: project.position } : {}
       };
     });
-    return { projects };
+    const groups = Array.isArray(payload.groups) ? payload.groups.flatMap(
+      (group) => isRecord(group) && typeof group.id === "string" && typeof group.name === "string" && typeof group.position === "number" ? [{ id: group.id, name: group.name, position: group.position }] : []
+    ) : void 0;
+    return { projects, ...groups !== void 0 ? { groups } : {} };
   }
   if (typeof payload.projectId !== "string") throw new Error('read-board response is missing "projectId"');
   if (!Array.isArray(payload.columns)) throw new Error('read-board response is missing "columns"');
@@ -5494,18 +5531,42 @@ function parseTaskCountsByColumnId(value) {
   }
   return counts;
 }
+function parseSummariesByTaskId(value) {
+  if (value === void 0) return {};
+  if (!isRecord(value)) throw new Error('read-board archived response has a non-object "summariesByTaskId"');
+  const summaries = {};
+  for (const [taskId, summary] of Object.entries(value)) {
+    try {
+      summaries[taskId] = parseSessionSummaryWire(summary);
+    } catch {
+    }
+  }
+  return summaries;
+}
 function parseReadBoardRequestPayload(payload) {
   if (!isRecord(payload)) throw new Error("read-board payload must be an object");
   if (payload.projectId !== void 0 && typeof payload.projectId !== "string") {
     throw new Error('read-board payload has a non-string "projectId"');
   }
-  if (payload.action !== void 0 && payload.action !== "subscribe" && payload.action !== "unsubscribe") {
+  if (payload.action !== void 0 && payload.action !== "subscribe" && payload.action !== "unsubscribe" && payload.action !== "archived") {
     throw new Error('read-board payload has an invalid "action"');
   }
   if (payload.view !== void 0 && payload.view !== "full" && payload.view !== "sessions") {
     throw new Error('read-board payload has an invalid "view"');
   }
-  return { projectId: payload.projectId, action: payload.action, view: payload.view };
+  if (payload.limit !== void 0 && (typeof payload.limit !== "number" || !Number.isInteger(payload.limit) || payload.limit < 1)) {
+    throw new Error('read-board payload has an invalid "limit"');
+  }
+  if (payload.offset !== void 0 && (typeof payload.offset !== "number" || !Number.isInteger(payload.offset) || payload.offset < 0)) {
+    throw new Error('read-board payload has an invalid "offset"');
+  }
+  return {
+    projectId: payload.projectId,
+    action: payload.action,
+    view: payload.view,
+    limit: payload.limit,
+    offset: payload.offset
+  };
 }
 function parseReadDiffResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("read-diff response must be an object");
@@ -5826,6 +5887,7 @@ var BOARD_TOOL_READ_NAMES = [
   "list_sessions",
   "get_session_history",
   "get_column_detail",
+  "list_board_profiles",
   "get_handoff_context",
   "get_transcript",
   "get_session_files",
@@ -5839,6 +5901,9 @@ var BOARD_TOOL_WRITE_NAMES = [
   "link_pr",
   "remove_attachment",
   "update_column",
+  "create_board_profile",
+  "update_board_profile",
+  "delete_board_profile",
   "create_backlog_task",
   "promote_backlog",
   "update_backlog_item",
@@ -6005,6 +6070,7 @@ export {
   parseReadStreamResponsePayload,
   parseRegisterPushRequestPayload,
   parseSessionEventWire,
+  parseSessionSummaryWire,
   parseSessionUsageWire,
   parseTerminalDimensionsWire,
   parseTranscriptEntriesWire,

package/dist/wire/payloads.d.ts

@@ -16,7 +16,7 @@
 import type { CapabilityVerb } from '../capabilities/verbs';
 import type { JsonValue } from './messages';
 import { type PushCategory } from '../crypto/push-envelope';
-import { type ActivityReasonWire, type ActivityStateWire, type BacklogItemWire, type BoardColumnWire, type BoardTaskWire, type DiffFileContentWire, type DiffFileListWire, type SessionUsageWire, type TerminalDimensionsWire, type TranscriptEntryWire } from '../events/payloads';
+import { type ActivityReasonWire, type ActivityStateWire, type BacklogItemWire, type BoardColumnWire, type BoardTaskWire, type DiffFileContentWire, type DiffFileListWire, type SessionSummaryWire, type SessionUsageWire, type TerminalDimensionsWire, type TranscriptEntryWire } from '../events/payloads';
 export interface ReadStreamRequestPayload {
     sessionId: string;
     /**
@@ -116,8 +116,24 @@ export declare function parseTranscriptWindowResponsePayload(payload: JsonValue)
 export type ReadBoardView = 'full' | 'sessions';
 export interface ReadBoardRequestPayload {
     projectId?: string;
-    /** Defaults to 'subscribe' when omitted. 'unsubscribe' only has an effect when projectId is set - the no-projectId project list is a one-shot read with no live feed to tear down. */
-    action?: 'subscribe' | 'unsubscribe';
+    /**
+     * Defaults to 'subscribe' when omitted. 'unsubscribe' only has an effect
+     * when projectId is set - the no-projectId project list is a one-shot read
+     * with no live feed to tear down.
+     *
+     * 'archived' (protocol 0.10.0) is a one-shot page of the project's COMPLETED
+     * tasks, which no other projection carries: both 'full' and 'sessions' are
+     * built from the desktop's non-archived task list. It is deliberately not a
+     * field on the snapshot, because a board subscription re-snapshots on every
+     * board change - archived tasks would then repeat down the wire forever,
+     * which is the exact bloat the 0.9.0 projections removed. Completed work
+     * changes rarely and is read on demand.
+     */
+    action?: 'subscribe' | 'unsubscribe' | 'archived';
+    /** 'archived' only: page size, newest-archived first. The desktop clamps it. */
+    limit?: number;
+    /** 'archived' only: how many newest to skip, for paging. Defaults to 0. */
+    offset?: number;
     /**
      * subscribe only: the projection wanted (protocol 0.9.0). Omitted means the
      * legacy full board WITH the backlog.
@@ -135,9 +151,28 @@ export interface ReadBoardRequestPayload {
      */
     view?: ReadBoardView;
 }
+/**
+ * A desktop project group ("KANGENTIC", "TROY WEB"), for a phone rendering
+ * its project list with the same structure the desktop sidebar shows
+ * (protocol 0.11.0).
+ */
+export interface ReadBoardProjectGroup {
+    id: string;
+    name: string;
+    /** Display order among groups. */
+    position: number;
+}
 export interface ReadBoardProjectSummary {
     id: string;
     name: string;
+    /**
+     * The group this project belongs to, or null/absent for an ungrouped one
+     * (protocol 0.11.0). Absent from an older desktop, which is indistinguishable
+     * from ungrouped and renders the same flat list as before.
+     */
+    groupId?: string | null;
+    /** Display order within the group, mirroring the desktop's own ordering (protocol 0.11.0). */
+    position?: number;
     /**
      * Accent color for this project ("#rrggbb"). Today the desktop derives
      * it deterministically from the project id; a user-set project color
@@ -149,6 +184,12 @@ export interface ReadBoardProjectSummary {
 /** Returned when the request omits projectId - the phone's project-bootstrap listing. */
 export interface ReadBoardProjectListResponsePayload {
     projects: ReadBoardProjectSummary[];
+    /**
+     * The desktop's project groups, in display order (protocol 0.11.0). Absent
+     * from an older desktop; a phone that gets none renders one flat list, which
+     * is exactly the pre-0.11.0 behaviour.
+     */
+    groups?: ReadBoardProjectGroup[];
 }
 /** Returned when the request carries a projectId - a snapshot of that project's board. */
 export interface ReadBoardSnapshotResponsePayload {
@@ -179,8 +220,33 @@ export interface ReadBoardSnapshotResponsePayload {
      */
     taskCountsByColumnId?: Record<string, number>;
 }
-export type ReadBoardResponsePayload = ReadBoardProjectListResponsePayload | ReadBoardSnapshotResponsePayload;
-/** Phone-side narrowing of a read-board response (project list or board snapshot). Throws on a malformed required field. */
+/**
+ * Returned for `action: 'archived'` - one page of a project's completed tasks
+ * (protocol 0.10.0).
+ *
+ * These never appear in a board snapshot: the desktop builds those from its
+ * non-archived task list, so a phone that only ever subscribed has no way to
+ * know a completed task exists at all.
+ */
+export interface ReadBoardArchivedResponsePayload {
+    projectId: string;
+    /** Newest-archived first. At most the requested `limit`. */
+    archivedTasks: BoardTaskWire[];
+    /**
+     * Total archived tasks in the project, NOT the length of the page above.
+     * Drives the column count and tells the phone whether another page exists.
+     */
+    archivedTotalCount: number;
+    /**
+     * Lifetime cost/duration/churn per task id, for the tasks on THIS page that
+     * have recorded metrics. Sparse on purpose: a task archived without ever
+     * running an agent has nothing to summarize and is simply absent, which is
+     * not an error.
+     */
+    summariesByTaskId: Record<string, SessionSummaryWire>;
+}
+export type ReadBoardResponsePayload = ReadBoardProjectListResponsePayload | ReadBoardSnapshotResponsePayload | ReadBoardArchivedResponsePayload;
+/** Phone-side narrowing of a read-board response (project list, board snapshot, or archived page). Throws on a malformed required field. */
 export declare function parseReadBoardResponsePayload(payload: JsonValue): ReadBoardResponsePayload;
 /** Mirrors DiffService's GitDiffScope in the desktop app; kept as a literal union here rather than an import, since the protocol package does not depend on the app. */
 export type ReadDiffScope = 'working' | 'staged' | 'branch';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kangentic/protocol",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Kangentic mobile bridge wire protocol: framing, Noise-based pairing and session handshakes, signed device roster, and capability verbs shared between desktop and mobile.",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -25,6 +25,7 @@
   ],
   "author": {
     "name": "Kangentic",
+    "email": "hello@kangentic.com",
     "url": "https://github.com/Kangentic"
   },
   "license": "AGPL-3.0-only",