@kangentic/protocol 0.12.0 → 0.13.1

package/dist/events/payloads.d.ts

@@ -217,17 +217,79 @@ export interface SessionEventWire {
     toolId?: string;
     detail?: string;
 }
+/**
+ * The system column roles, mirroring the desktop's `SWIMLANE_ROLES` /
+ * `SwimlaneRole` (`src/shared/types.ts`). This package cannot import that
+ * file (see the module doc), so the two lists are a deliberate mirror, kept
+ * in sync by `tests/unit/protocol/board-column-role-parity.test.ts` on the
+ * desktop side rather than by a shared import.
+ */
+export declare const BOARD_COLUMN_ROLES: readonly ["todo", "done"];
+export type BoardColumnRoleWire = (typeof BOARD_COLUMN_ROLES)[number];
+/** True for a column whose role is the system 'todo' role. Prefer this at a call site over a literal `=== 'todo'`, which the `(string & {})` widening leaves unchecked. */
+export declare function isTodoRole(role: string | null | undefined): boolean;
+/** True for a column whose role is the system 'done' role. Prefer this at a call site over a literal `=== 'done'`, which the `(string & {})` widening leaves unchecked. */
+export declare function isDoneRole(role: string | null | undefined): boolean;
 /** Phone-needed subset of the desktop's Swimlane row (snake_case preserved so the desktop mapper is a mechanical pick). */
 export interface BoardColumnWire {
     id: string;
     name: string;
     description: string | null;
-    role: string | null;
+    /**
+     * `'todo'` / `'done'` are the system roles; anything else (including a
+     * future role this package predates) is a custom or not-yet-known column,
+     * which is exactly what the `(string & {})` escape hatch preserves - the
+     * literal union alone would reject a value a newer desktop legitimately
+     * sends. That widening does NOT make a typo'd comparison a compile error
+     * (a string literal is assignable to `string & {}`), so call sites should
+     * use `isTodoRole` / `isDoneRole` rather than `=== 'todo'` / `=== 'done'`.
+     */
+    role: BoardColumnRoleWire | (string & {}) | null;
     position: number;
     color: string;
     icon: string | null;
     is_archived: boolean;
     is_ghost: boolean;
+    /**
+     * Whether moving a task into this column spawns a successor agent
+     * session, derived desktop-side from the column's `auto_spawn` flag and
+     * role. This is INTENT, not a guarantee:
+     *
+     * - `false` - this column does not intend to spawn. Reliable enough to act
+     *   on ONLY when the column's own `role` is 'todo' or 'done': those two
+     *   produce a full reset or an archive, and a Board Profile cannot change a
+     *   column's role, so a client MAY skip a session-swap transition entirely
+     *   for them. `role` rides this same object, so
+     *   `isTodoRole(column.role) || isDoneRole(column.role)` is how a client
+     *   recognizes that case. A `false` that came from `auto_spawn: false` on
+     *   any other column is intent only, exactly like `true`: a Board Profile
+     *   can set `autoSpawn: true` for one task on that column, and the move
+     *   then does spawn.
+     * - `true` - this column intends to spawn, but a handful of desktop-side
+     *   conditions can suspend the old session without a successor actually
+     *   landing (a board profile disabling auto_spawn for this task, a failed
+     *   worktree checkout that reverts the move, a shutdown or a newer move
+     *   racing this one). A client MUST NOT treat `true` as a promise; keep
+     *   whatever timeout already bounds a session-swap wait and let `true`
+     *   only skip a redundant one.
+     * - `null` / absent - a desktop that predates this field. A client falls
+     *   back to its pre-existing behavior, the same way an absent
+     *   `pr_merge_readiness` reads as "never judged".
+     *
+     * Declared OPTIONAL (`?`) so a hand-built `BoardColumnWire` literal does
+     * not have to list it. `parseBoardColumnWire` populates the key from every
+     * real wire response regardless, so the optionality costs nothing at
+     * runtime.
+     *
+     * Ordering precondition this field depends on: the phone must learn a
+     * MOVE's destination column before the old session's `session-ended`
+     * arrives, or it cannot resolve `spawns_session` against the right column.
+     * That holds today because `handleTaskMove` emits its board-changed event
+     * at the commit point rather than at settle time. See the comment above
+     * `emitBoardChanged()` in `src/main/ipc/handlers/task-move.ts`, and
+     * `docs/mobile-bridge.md`.
+     */
+    spawns_session?: boolean | null;
 }
 /** Phone-needed subset of the desktop's Task row. A non-null `session_id` is the live-session signal the phone's triage view keys on. */
 export interface BoardTaskWire {
@@ -244,6 +306,18 @@ export interface BoardTaskWire {
     pr_number: number | null;
     pr_url: string | null;
     pr_state: string | null;
+    /**
+     * Normalized merge readiness of the linked PR: `ready` / `blocked` /
+     * `conflicting` / `queued` / `running` / `unknown`, or null when never
+     * judged. `queued` and `running` mean a blocking check is still in flight.
+     * Absent from desktops that predate it, which the parser reads as null; a
+     * value a client does not know should render as plain open.
+     *
+     * Declared OPTIONAL (`?`) so a hand-built `BoardTaskWire` literal does not
+     * have to list it. `parseBoardTaskWire` populates the key from every real
+     * wire response regardless, so the optionality costs nothing at runtime.
+     */
+    pr_merge_readiness?: string | null;
     base_branch: string | null;
     labels: string[];
     priority: number;

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod2) => __copyProps(__defProp({}, "__esModule", { value: tr
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BOARD_COLUMN_ROLES: () => BOARD_COLUMN_ROLES,
   BOARD_TOOL_READ_NAMES: () => BOARD_TOOL_READ_NAMES,
   BOARD_TOOL_WRITE_NAMES: () => BOARD_TOOL_WRITE_NAMES,
   CAPABILITY_VERBS: () => CAPABILITY_VERBS,
@@ -69,11 +70,13 @@ __export(index_exports, {
   isBoardToolWriteName: () => isBoardToolWriteName,
   isBridgeEvent: () => isBridgeEvent,
   isCapabilityVerb: () => isCapabilityVerb,
+  isDoneRole: () => isDoneRole,
   isJsonValue: () => isJsonValue,
   isPushCategory: () => isPushCategory,
   isRecord: () => isRecord,
   isRosterEntryExpired: () => isRosterEntryExpired,
   isSecureRelayAddress: () => isSecureRelayAddress,
+  isTodoRole: () => isTodoRole,
   openPairingConfirm: () => openPairingConfirm,
   openPushEnvelope: () => openPushEnvelope,
   parseActivityEventPayload: () => parseActivityEventPayload,
@@ -5249,6 +5252,15 @@ function openPushEnvelope(pushKey, recipientStaticPublicKey, blob) {
 }
 
 // src/events/payloads.ts
+var BOARD_COLUMN_ROLES = ["todo", "done"];
+var TODO_ROLE = "todo";
+var DONE_ROLE = "done";
+function isTodoRole(role) {
+  return role === TODO_ROLE;
+}
+function isDoneRole(role) {
+  return role === DONE_ROLE;
+}
 var DIFF_FILE_STATUSES = ["A", "M", "D", "R", "C", "U"];
 var TRANSCRIPT_SYSTEM_SUBTYPES = ["compaction", "command", "command_output", "session_boundary"];
 function requireString(record, field, context) {
@@ -5415,18 +5427,26 @@ function nullableNumber(record, field) {
   const value = record[field];
   return typeof value === "number" ? value : null;
 }
+function nullableBoolean(record, field) {
+  const value = record[field];
+  return typeof value === "boolean" ? value : null;
+}
 function parseBoardColumnWire(value) {
   if (!isRecord(value)) throw new Error("board column must be an object");
   return {
     id: requireString(value, "id", "board column"),
     name: requireString(value, "name", "board column"),
     description: nullableString(value, "description"),
+    // An unrecognized role passes through rather than throwing: it is a
+    // custom column (or a future system role this package predates), not a
+    // malformed payload. See the BoardColumnRoleWire doc comment.
     role: nullableString(value, "role"),
     position: requireNumber(value, "position", "board column"),
     color: requireString(value, "color", "board column"),
     icon: nullableString(value, "icon"),
     is_archived: requireBoolean(value, "is_archived", "board column"),
-    is_ghost: requireBoolean(value, "is_ghost", "board column")
+    is_ghost: requireBoolean(value, "is_ghost", "board column"),
+    spawns_session: nullableBoolean(value, "spawns_session")
   };
 }
 function parseBoardTaskWire(value) {
@@ -5445,6 +5465,7 @@ function parseBoardTaskWire(value) {
     pr_number: nullableNumber(value, "pr_number"),
     pr_url: nullableString(value, "pr_url"),
     pr_state: nullableString(value, "pr_state"),
+    pr_merge_readiness: nullableString(value, "pr_merge_readiness"),
     base_branch: nullableString(value, "base_branch"),
     labels: Array.isArray(value.labels) ? parseStringArray(value.labels, "board task labels") : [],
     priority: typeof value.priority === "number" ? value.priority : 0,
@@ -6146,6 +6167,7 @@ function isBridgeEvent(value) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BOARD_COLUMN_ROLES,
   BOARD_TOOL_READ_NAMES,
   BOARD_TOOL_WRITE_NAMES,
   CAPABILITY_VERBS,
@@ -6195,11 +6217,13 @@ function isBridgeEvent(value) {
   isBoardToolWriteName,
   isBridgeEvent,
   isCapabilityVerb,
+  isDoneRole,
   isJsonValue,
   isPushCategory,
   isRecord,
   isRosterEntryExpired,
   isSecureRelayAddress,
+  isTodoRole,
   openPairingConfirm,
   openPushEnvelope,
   parseActivityEventPayload,

package/dist/index.d.ts

@@ -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, 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 { parseTranscriptEntriesWire, parseTranscriptEventPayload, type TranscriptEventPayload, type TranscriptUpsertWire, isActivityStateWire, isActivityReasonWire, parseSessionUsageWire, parseSessionSummaryWire, parseSessionEventWire, parseTerminalDimensionsWire, parseBoardColumnWire, parseBoardTaskWire, parseBacklogItemWire, parseDiffFileListWire, parseDiffFileContentWire, isTodoRole, isDoneRole, BOARD_COLUMN_ROLES, type TranscriptBlockWire, type TranscriptEntryWire, type TranscriptTurnUsageWire, type TranscriptSystemSubtypeWire, type ActivityStateWire, type ActivityReasonWire, type SessionUsageWire, type SessionSummaryWire, type SessionEventWire, type TerminalDimensionsWire, type BoardColumnWire, type BoardColumnRoleWire, 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

@@ -5131,6 +5131,15 @@ function openPushEnvelope(pushKey, recipientStaticPublicKey, blob) {
 }
 
 // src/events/payloads.ts
+var BOARD_COLUMN_ROLES = ["todo", "done"];
+var TODO_ROLE = "todo";
+var DONE_ROLE = "done";
+function isTodoRole(role) {
+  return role === TODO_ROLE;
+}
+function isDoneRole(role) {
+  return role === DONE_ROLE;
+}
 var DIFF_FILE_STATUSES = ["A", "M", "D", "R", "C", "U"];
 var TRANSCRIPT_SYSTEM_SUBTYPES = ["compaction", "command", "command_output", "session_boundary"];
 function requireString(record, field, context) {
@@ -5297,18 +5306,26 @@ function nullableNumber(record, field) {
   const value = record[field];
   return typeof value === "number" ? value : null;
 }
+function nullableBoolean(record, field) {
+  const value = record[field];
+  return typeof value === "boolean" ? value : null;
+}
 function parseBoardColumnWire(value) {
   if (!isRecord(value)) throw new Error("board column must be an object");
   return {
     id: requireString(value, "id", "board column"),
     name: requireString(value, "name", "board column"),
     description: nullableString(value, "description"),
+    // An unrecognized role passes through rather than throwing: it is a
+    // custom column (or a future system role this package predates), not a
+    // malformed payload. See the BoardColumnRoleWire doc comment.
     role: nullableString(value, "role"),
     position: requireNumber(value, "position", "board column"),
     color: requireString(value, "color", "board column"),
     icon: nullableString(value, "icon"),
     is_archived: requireBoolean(value, "is_archived", "board column"),
-    is_ghost: requireBoolean(value, "is_ghost", "board column")
+    is_ghost: requireBoolean(value, "is_ghost", "board column"),
+    spawns_session: nullableBoolean(value, "spawns_session")
   };
 }
 function parseBoardTaskWire(value) {
@@ -5327,6 +5344,7 @@ function parseBoardTaskWire(value) {
     pr_number: nullableNumber(value, "pr_number"),
     pr_url: nullableString(value, "pr_url"),
     pr_state: nullableString(value, "pr_state"),
+    pr_merge_readiness: nullableString(value, "pr_merge_readiness"),
     base_branch: nullableString(value, "base_branch"),
     labels: Array.isArray(value.labels) ? parseStringArray(value.labels, "board task labels") : [],
     priority: typeof value.priority === "number" ? value.priority : 0,
@@ -6027,6 +6045,7 @@ function isBridgeEvent(value) {
   }
 }
 export {
+  BOARD_COLUMN_ROLES,
   BOARD_TOOL_READ_NAMES,
   BOARD_TOOL_WRITE_NAMES,
   CAPABILITY_VERBS,
@@ -6076,11 +6095,13 @@ export {
   isBoardToolWriteName,
   isBridgeEvent,
   isCapabilityVerb,
+  isDoneRole,
   isJsonValue,
   isPushCategory,
   isRecord,
   isRosterEntryExpired,
   isSecureRelayAddress,
+  isTodoRole,
   openPairingConfirm,
   openPushEnvelope,
   parseActivityEventPayload,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kangentic/protocol",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "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",