@kangentic/protocol 0.20.0 → 0.22.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

@@ -182,9 +182,10 @@ export interface SessionUsageWire {
  * 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.
+ * owns those aggregation rules - they are not re-derived here. Cost, duration
+ * and tokens are each conversation's cumulative reading, so they count once per
+ * session lineage and add across lineages; tool calls and lines SUM; files
+ * changed takes the MAX.
  *
  * `sessionId` is the transcript ANCHOR, not a live session: it resolves
  * through the desktop's session records, which outlive the agent, so it reads
@@ -465,6 +466,74 @@ export interface BoardTaskWire {
      * key from every real wire response.
      */
     pausable?: boolean | null;
+    /**
+     * True when column automations are off for this task: no On task enter, On
+     * agent turn end or On task exit row runs for it in any column, and a move
+     * types no column message. Column settings, a hand's moves and the task's own
+     * first command are untouched. It is the fact the desktop card's "Automations
+     * disabled" strip reads, and the desktop menu's Enable or Disable automations
+     * row flips it.
+     *
+     * There is no verb for it. A phone flips it with the `board-tool-write`
+     * `update_task` call, whose param is camelCase: `automationsDisabled: true`
+     * or `false`, never `automations_disabled`. A workflow task always reads
+     * false, because its workflow's Pause holds it, and `update_task` refuses
+     * `true` for one. Hide the control while `workflow` is non-null, as the
+     * desktop menu does.
+     *
+     * The desktop also clears it by itself: when the task leaves Done (a rollback
+     * of a failed move excepted), when it is restored from the archive, and when
+     * it joins a workflow. Every change, by any hand, reaches the phone as a
+     * `task-updated` board event, after which the next snapshot carries the new
+     * value.
+     *
+     * Null or absent means a desktop that predates the field (pre-0.22.0). A
+     * client offers no control then, since it cannot read the switch's state.
+     *
+     * Declared OPTIONAL (`?`) like `pausable`; `parseBoardTaskWire` populates the
+     * key from every real wire response.
+     */
+    automations_disabled?: 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 +633,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,25 @@ 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"),
+    automations_disabled: nullableBoolean(value, "automations_disabled"),
+    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 +6205,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 +6223,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 +6429,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,25 @@ 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"),
+    automations_disabled: nullableBoolean(value, "automations_disabled"),
+    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 +6065,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 +6083,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 +6288,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.22.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",