@kangentic/protocol 0.20.0 → 0.21.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", "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 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", "list_workflows", "get_workflow"];
+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", "pause_workflow", "resume_workflow"];
 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/crypto/push-envelope.d.ts

@@ -1,4 +1,9 @@
-export declare const PUSH_CATEGORIES: readonly ["input-required", "turn-complete", "session-failed", "plan-complete", "spawn-stalled"];
+/**
+ * Append only. `workflow-complete` (every task of a workflow reached Done) is
+ * the newest; a phone that predates it reads the envelope as an unknown
+ * category and shows the generic placeholder.
+ */
+export declare const PUSH_CATEGORIES: readonly ["input-required", "turn-complete", "session-failed", "plan-complete", "spawn-stalled", "workflow-complete"];
 export type PushCategory = (typeof PUSH_CATEGORIES)[number];
 export declare function isPushCategory(value: unknown): value is PushCategory;
 /** Reject an opened envelope whose sentAt is older than this (stale replay). */

package/dist/events/payloads.d.ts

@@ -465,6 +465,46 @@ export interface BoardTaskWire {
      * key from every real wire response.
      */
     pausable?: boolean | null;
+    /**
+     * The workflow the task belongs to (a set of linked tasks that runs through
+     * its boards by itself), or null for an ordinary task. Absent from desktops
+     * that predate workflows, which the parser reads as null, as it does a value
+     * it cannot read. Declared OPTIONAL for the reason `pr_merge_readiness` is.
+     */
+    workflow?: BoardTaskWorkflowWire | null;
+}
+/**
+ * A board task's workflow, as its card draws it: the strip (name, color), what
+ * the task waits for, and whether a hand may move it. `lock_reason` is the
+ * desktop's own sentence, so a phone that refuses a move says what the desktop
+ * would; the desktop refuses a locked move on its own anyway.
+ */
+export interface BoardTaskWorkflowWire {
+    id: string;
+    title: string;
+    /** The workflow's home project, which may not be the board's. */
+    project_id: string;
+    /** `running`, `paused`, `draft` or `done`; a value a client does not know reads as running. */
+    state: string;
+    /** Which of six categorical colors (1 to 6) the desktop paints its icon in. */
+    color_slot: number;
+    /** The columns the task visits, by id, in board order. */
+    route: string[];
+    /** The tasks it waits for that are not done, named as the card's footer names them ("#413"). */
+    waiting_for: string[];
+    /**
+     * While the card is locked (its workflow runs and it is not waiting in a
+     * human gate), the desktop's sentence for a refused move; null otherwise,
+     * which is when the desktop draws no lock. An unlocked card still never
+     * moves into To Do, and while `gate_target_id` is set it moves only there.
+     */
+    lock_reason: string | null;
+    /**
+     * While the workflow runs and the card waits in a column no agent judges
+     * (a human gate): the one column a hand may move it to, the next on its
+     * route. Moving it there is how the person reports the step done. Null otherwise.
+     */
+    gate_target_id: string | null;
 }
 /**
  * One live Command Terminal of a project (protocol 0.20.0): an agent the
@@ -564,6 +604,11 @@ export declare function parseSessionEventWire(payload: JsonValue): SessionEventW
 export declare function parseBoardColumnWire(value: JsonValue): BoardColumnWire;
 /** Narrows one board-task row. Throws on a malformed required field. */
 export declare function parseBoardTaskWire(value: JsonValue): BoardTaskWire;
+/**
+ * A board task's workflow, or null when absent or unreadable. Lenient on
+ * purpose: a malformed workflow costs the card its strip, never the board.
+ */
+export declare function parseBoardTaskWorkflowWire(value: JsonValue | undefined): BoardTaskWorkflowWire | null;
 /**
  * Narrows one Command Terminal row. Throws on a malformed required field. An
  * unrecognized activity state or reason reads as null rather than throwing, so

package/dist/index.cjs

@@ -97,6 +97,7 @@ __export(index_exports, {
   parseBacklogItemWire: () => parseBacklogItemWire,
   parseBoardColumnWire: () => parseBoardColumnWire,
   parseBoardTaskWire: () => parseBoardTaskWire,
+  parseBoardTaskWorkflowWire: () => parseBoardTaskWorkflowWire,
   parseCapabilityRequestPayload: () => parseCapabilityRequestPayload,
   parseCommandTerminalStartResponsePayload: () => parseCommandTerminalStartResponsePayload,
   parseCommandTerminalWire: () => parseCommandTerminalWire,
@@ -5228,7 +5229,7 @@ function base64UrlDecode(encoded) {
 }
 
 // src/crypto/push-envelope.ts
-var PUSH_CATEGORIES = ["input-required", "turn-complete", "session-failed", "plan-complete", "spawn-stalled"];
+var PUSH_CATEGORIES = ["input-required", "turn-complete", "session-failed", "plan-complete", "spawn-stalled", "workflow-complete"];
 function isPushCategory(value) {
   return typeof value === "string" && PUSH_CATEGORIES.includes(value);
 }
@@ -5509,7 +5510,24 @@ function parseBoardTaskWire(value) {
     spawn_progress: nullableString(value, "spawn_progress"),
     resumable: nullableBoolean(value, "resumable"),
     paused: nullableBoolean(value, "paused"),
-    pausable: nullableBoolean(value, "pausable")
+    pausable: nullableBoolean(value, "pausable"),
+    workflow: parseBoardTaskWorkflowWire(value.workflow)
+  };
+}
+function parseBoardTaskWorkflowWire(value) {
+  if (value === void 0 || !isRecord(value)) return null;
+  const strings = (field) => Array.isArray(field) ? field.filter((entry) => typeof entry === "string") : [];
+  if (typeof value.id !== "string" || typeof value.title !== "string" || typeof value.project_id !== "string") return null;
+  return {
+    id: value.id,
+    title: value.title,
+    project_id: value.project_id,
+    state: typeof value.state === "string" ? value.state : "running",
+    color_slot: typeof value.color_slot === "number" ? value.color_slot : 1,
+    route: strings(value.route),
+    waiting_for: strings(value.waiting_for),
+    lock_reason: typeof value.lock_reason === "string" ? value.lock_reason : null,
+    gate_target_id: typeof value.gate_target_id === "string" ? value.gate_target_id : null
   };
 }
 function parseCommandTerminalWire(value) {
@@ -6186,7 +6204,10 @@ var BOARD_TOOL_READ_NAMES = [
   "get_transcript",
   "get_session_files",
   "get_session_events",
-  "get_activity_intervals"
+  "get_activity_intervals",
+  // Workflows: the project's workflows and one workflow's tasks, routes and links.
+  "list_workflows",
+  "get_workflow"
 ];
 var BOARD_TOOL_WRITE_NAMES = [
   "create_task",
@@ -6201,7 +6222,10 @@ var BOARD_TOOL_WRITE_NAMES = [
   "create_backlog_task",
   "promote_backlog",
   "update_backlog_item",
-  "delete_backlog_item"
+  "delete_backlog_item",
+  // Workflows: stop every task of a running workflow at once, and start them again.
+  "pause_workflow",
+  "resume_workflow"
 ];
 function isBoardToolReadName(value) {
   return BOARD_TOOL_READ_NAMES.includes(value);
@@ -6404,6 +6428,7 @@ function isBridgeEvent(value) {
   parseBacklogItemWire,
   parseBoardColumnWire,
   parseBoardTaskWire,
+  parseBoardTaskWorkflowWire,
   parseCapabilityRequestPayload,
   parseCommandTerminalStartResponsePayload,
   parseCommandTerminalWire,

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, parseCommandTerminalWire, 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 CommandTerminalWire, 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, parseCommandTerminalWire, parseBoardTaskWorkflowWire, 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 CommandTerminalWire, type BoardTaskWorkflowWire, 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

@@ -5089,7 +5089,7 @@ function base64UrlDecode(encoded) {
 }
 
 // src/crypto/push-envelope.ts
-var PUSH_CATEGORIES = ["input-required", "turn-complete", "session-failed", "plan-complete", "spawn-stalled"];
+var PUSH_CATEGORIES = ["input-required", "turn-complete", "session-failed", "plan-complete", "spawn-stalled", "workflow-complete"];
 function isPushCategory(value) {
   return typeof value === "string" && PUSH_CATEGORIES.includes(value);
 }
@@ -5370,7 +5370,24 @@ function parseBoardTaskWire(value) {
     spawn_progress: nullableString(value, "spawn_progress"),
     resumable: nullableBoolean(value, "resumable"),
     paused: nullableBoolean(value, "paused"),
-    pausable: nullableBoolean(value, "pausable")
+    pausable: nullableBoolean(value, "pausable"),
+    workflow: parseBoardTaskWorkflowWire(value.workflow)
+  };
+}
+function parseBoardTaskWorkflowWire(value) {
+  if (value === void 0 || !isRecord(value)) return null;
+  const strings = (field) => Array.isArray(field) ? field.filter((entry) => typeof entry === "string") : [];
+  if (typeof value.id !== "string" || typeof value.title !== "string" || typeof value.project_id !== "string") return null;
+  return {
+    id: value.id,
+    title: value.title,
+    project_id: value.project_id,
+    state: typeof value.state === "string" ? value.state : "running",
+    color_slot: typeof value.color_slot === "number" ? value.color_slot : 1,
+    route: strings(value.route),
+    waiting_for: strings(value.waiting_for),
+    lock_reason: typeof value.lock_reason === "string" ? value.lock_reason : null,
+    gate_target_id: typeof value.gate_target_id === "string" ? value.gate_target_id : null
   };
 }
 function parseCommandTerminalWire(value) {
@@ -6047,7 +6064,10 @@ var BOARD_TOOL_READ_NAMES = [
   "get_transcript",
   "get_session_files",
   "get_session_events",
-  "get_activity_intervals"
+  "get_activity_intervals",
+  // Workflows: the project's workflows and one workflow's tasks, routes and links.
+  "list_workflows",
+  "get_workflow"
 ];
 var BOARD_TOOL_WRITE_NAMES = [
   "create_task",
@@ -6062,7 +6082,10 @@ var BOARD_TOOL_WRITE_NAMES = [
   "create_backlog_task",
   "promote_backlog",
   "update_backlog_item",
-  "delete_backlog_item"
+  "delete_backlog_item",
+  // Workflows: stop every task of a running workflow at once, and start them again.
+  "pause_workflow",
+  "resume_workflow"
 ];
 function isBoardToolReadName(value) {
   return BOARD_TOOL_READ_NAMES.includes(value);
@@ -6264,6 +6287,7 @@ export {
   parseBacklogItemWire,
   parseBoardColumnWire,
   parseBoardTaskWire,
+  parseBoardTaskWorkflowWire,
   parseCapabilityRequestPayload,
   parseCommandTerminalStartResponsePayload,
   parseCommandTerminalWire,

package/package.json

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