@kangentic/protocol 0.16.0 → 0.18.0

package/dist/capabilities/verbs.d.ts

@@ -16,9 +16,15 @@
  * `start-session` is the second lifecycle verb beside `move-task`: it spawns
  * or resumes a task's session in the column the task is already in, so a
  * phone's "Session ended" state can bring the agent back without moving the
- * task. A live session is an idempotent no-op; nothing is ever stopped.
+ * task. A live session is an idempotent no-op; `start-session` never stops
+ * anything.
+ *
+ * `pause-session` is the third lifecycle verb: it suspends a task's live
+ * session exactly as the desktop's Pause button does, without moving the task,
+ * and keeps the conversation for a later `start-session` Resume. Gate it on
+ * `BoardTaskWire.pausable`.
  */
-export declare const CAPABILITY_VERBS: readonly ["read-stream", "read-board", "read-diff", "send-user-message", "move-task", "answer-permission-prompt", "interactive-terminal", "board-tool-read", "board-tool-write", "register-push", "start-session"];
+export declare const CAPABILITY_VERBS: readonly ["read-stream", "read-board", "read-diff", "send-user-message", "move-task", "answer-permission-prompt", "interactive-terminal", "board-tool-read", "board-tool-write", "register-push", "start-session", "pause-session"];
 export type CapabilityVerb = (typeof CAPABILITY_VERBS)[number];
 export declare function isCapabilityVerb(value: string): value is CapabilityVerb;
 /** Deny-by-default: a verb absent from the set is not authorized. */

package/dist/events/payloads.d.ts

@@ -397,11 +397,74 @@ export interface BoardTaskWire {
      * Resume control; a client applies the same precedence. `start-session`
      * re-checks the column and refuses a To Do, Done or archived task with the
      * desktop's Resume copy, so a value overtaken by a move is safe to act on.
+     * A paused task that offers no Resume reads false here. From 0.17.0 `paused`
+     * tells it apart from a task with no paused session.
      *
      * Declared OPTIONAL (`?`) like `spawns_session`; `parseBoardTaskWire`
      * populates the key from every real wire response.
      */
     resumable?: boolean | null;
+    /**
+     * True when the task has a paused session (a `suspended` session that is not
+     * a Command Terminal) and no live one. No column or archive gate applies. It
+     * is the fact the desktop card's "Paused" footer reads, so a paused task in
+     * Done or on the archived page reads true here while `resumable` reads
+     * false. The desktop draws an archived task as a compact card with no
+     * footer, so a client that matches the desktop card draws "Paused" only
+     * when `archived_at` is null. A move from another column into Done
+     * archives the task in the same step, so only a task that sits in Done
+     * unarchived gets the full card and its footer. A move into To Do removes
+     * the task's session rows, so a task there normally reads false. Gate
+     * Resume on `resumable` only; `resumable: true` always comes with
+     * `paused: true`.
+     *
+     * A desktop pause clears the task's `session_id`, so find a paused session
+     * from this field, not from `session_id`. A respawn queued behind the
+     * desktop's concurrency limit leaves the task holding a paused session and a
+     * queued one; that task reads false, as the desktop card shows the queued
+     * session. While `spawn_progress` is non-null the desktop card shows that
+     * label instead of "Paused"; a client applies the same precedence.
+     *
+     * Under `view: 'sessions'` a paused task that offers no Resume stays out of
+     * the snapshot, because an agent feed has nothing to act on for it. Null or
+     * absent means a desktop that predates the field (pre-0.17.0); a client
+     * then reads a paused task from `resumable` alone, as before.
+     *
+     * Declared OPTIONAL (`?`) like `resumable`; `parseBoardTaskWire` populates
+     * the key from every real wire response.
+     */
+    paused?: boolean | null;
+    /**
+     * True when the task has a live session (`running` or `queued`) and is not
+     * in To Do. It is the desktop's promise that `pause-session` for this task
+     * pauses that session exactly as its Pause button does: the conversation is
+     * kept for a later Resume, and the pause sticks, so a column with auto-spawn
+     * on does not start the task again by itself. Gate a phone's Pause control on
+     * THIS field.
+     *
+     * Done and archived do not clear it, matching the desktop, whose Pause stays
+     * available there because it is the only in-window stop for a live agent. A
+     * move into Done suspends the task's session in the same step, so a task
+     * there normally has no live session and reads false. It reads true only
+     * when that suspend failed and left the agent running.
+     *
+     * Never true while `paused` is true: a paused task has no live session. While
+     * `spawn_progress` is non-null and no session is live, the desktop card still
+     * shows a Pause control, but its click only cancels an in-flight resume or
+     * start, which `pause-session` does not promise. This field reads false
+     * then, and the verb refuses a task with no live session.
+     *
+     * A pause, a session's start and its end each reach 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.18.0), and a client offers no Pause then: a 0.15.0 to 0.17.0
+     * desktop refuses `pause-session` with the `unsupported-verb` code, and an
+     * older one does not answer it at all.
+     *
+     * Declared OPTIONAL (`?`) like `paused`; `parseBoardTaskWire` populates the
+     * key from every real wire response.
+     */
+    pausable?: boolean | null;
 }
 /** Phone-needed subset of the desktop's BacklogTask row. */
 export interface BacklogItemWire {

package/dist/index.cjs

@@ -90,6 +90,7 @@ __export(index_exports, {
   parseCapabilityRequestPayload: () => parseCapabilityRequestPayload,
   parseDiffFileContentWire: () => parseDiffFileContentWire,
   parseDiffFileListWire: () => parseDiffFileListWire,
+  parsePauseSessionResponsePayload: () => parsePauseSessionResponsePayload,
   parsePushEnvelopePlaintext: () => parsePushEnvelopePlaintext,
   parseReadBoardResponsePayload: () => parseReadBoardResponsePayload,
   parseReadDiffResponsePayload: () => parseReadDiffResponsePayload,
@@ -4971,7 +4972,8 @@ var CAPABILITY_VERBS = [
   "board-tool-read",
   "board-tool-write",
   "register-push",
-  "start-session"
+  "start-session",
+  "pause-session"
 ];
 function isCapabilityVerb(value) {
   return CAPABILITY_VERBS.includes(value);
@@ -5465,7 +5467,9 @@ function parseBoardTaskWire(value) {
     created_at: requireString(value, "created_at", "board task"),
     updated_at: requireString(value, "updated_at", "board task"),
     spawn_progress: nullableString(value, "spawn_progress"),
-    resumable: nullableBoolean(value, "resumable")
+    resumable: nullableBoolean(value, "resumable"),
+    paused: nullableBoolean(value, "paused"),
+    pausable: nullableBoolean(value, "pausable")
   };
 }
 function parseBacklogItemWire(value) {
@@ -5777,6 +5781,20 @@ function parseStartSessionResponsePayload(payload) {
   }
   return { ok: payload.ok, outcome: payload.outcome };
 }
+function parsePauseSessionRequestPayload(payload) {
+  if (!isRecord(payload)) throw new Error("pause-session payload must be an object");
+  if (typeof payload.taskId !== "string") throw new Error('pause-session payload missing "taskId"');
+  if (typeof payload.projectId !== "string") throw new Error('pause-session payload missing "projectId"');
+  return {
+    taskId: payload.taskId,
+    projectId: payload.projectId
+  };
+}
+function parsePauseSessionResponsePayload(payload) {
+  if (!isRecord(payload)) throw new Error("pause-session response must be an object");
+  if (typeof payload.ok !== "boolean") throw new Error('pause-session response missing "ok"');
+  return { ok: payload.ok };
+}
 function parseAnswerPermissionPromptRequestPayload(payload) {
   if (!isRecord(payload)) throw new Error("answer-permission-prompt payload must be an object");
   if (typeof payload.sessionId !== "string") throw new Error('answer-permission-prompt payload missing "sessionId"');
@@ -5874,6 +5892,8 @@ function parseCapabilityRequestPayload(verb, payload) {
       return parseRegisterPushRequestPayload(payload);
     case "start-session":
       return parseStartSessionRequestPayload(payload);
+    case "pause-session":
+      return parsePauseSessionRequestPayload(payload);
     default: {
       const exhaustiveCheck = verb;
       throw new Error(`Unknown capability verb: ${String(exhaustiveCheck)}`);
@@ -6277,6 +6297,7 @@ function isBridgeEvent(value) {
   parseCapabilityRequestPayload,
   parseDiffFileContentWire,
   parseDiffFileListWire,
+  parsePauseSessionResponsePayload,
   parsePushEnvelopePlaintext,
   parseReadBoardResponsePayload,
   parseReadDiffResponsePayload,

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export type { JsonValue, BridgeMessage, HeartbeatMessage, CapabilityRequestMessa
 export { encodeMessage, decodeMessage, UnsupportedVerbError, isUnsupportedVerbError, UNSUPPORTED_VERB_ERROR_CODE, 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, parseStartSessionResponsePayload, isReadStreamSessionStatusWire, 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, type StartSessionRequestPayload, type StartSessionResponsePayload, type StartSessionOutcome, } from './wire/payloads';
+export { parseCapabilityRequestPayload, parseReadStreamResponsePayload, parseReadBoardResponsePayload, parseReadDiffResponsePayload, parseTranscriptWindowResponsePayload, parseRegisterPushRequestPayload, parseStartSessionResponsePayload, parsePauseSessionResponsePayload, isReadStreamSessionStatusWire, 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, type StartSessionRequestPayload, type StartSessionResponsePayload, type StartSessionOutcome, type PauseSessionRequestPayload, type PauseSessionResponsePayload, } 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';

package/dist/index.mjs

@@ -4845,7 +4845,8 @@ var CAPABILITY_VERBS = [
   "board-tool-read",
   "board-tool-write",
   "register-push",
-  "start-session"
+  "start-session",
+  "pause-session"
 ];
 function isCapabilityVerb(value) {
   return CAPABILITY_VERBS.includes(value);
@@ -5339,7 +5340,9 @@ function parseBoardTaskWire(value) {
     created_at: requireString(value, "created_at", "board task"),
     updated_at: requireString(value, "updated_at", "board task"),
     spawn_progress: nullableString(value, "spawn_progress"),
-    resumable: nullableBoolean(value, "resumable")
+    resumable: nullableBoolean(value, "resumable"),
+    paused: nullableBoolean(value, "paused"),
+    pausable: nullableBoolean(value, "pausable")
   };
 }
 function parseBacklogItemWire(value) {
@@ -5651,6 +5654,20 @@ function parseStartSessionResponsePayload(payload) {
   }
   return { ok: payload.ok, outcome: payload.outcome };
 }
+function parsePauseSessionRequestPayload(payload) {
+  if (!isRecord(payload)) throw new Error("pause-session payload must be an object");
+  if (typeof payload.taskId !== "string") throw new Error('pause-session payload missing "taskId"');
+  if (typeof payload.projectId !== "string") throw new Error('pause-session payload missing "projectId"');
+  return {
+    taskId: payload.taskId,
+    projectId: payload.projectId
+  };
+}
+function parsePauseSessionResponsePayload(payload) {
+  if (!isRecord(payload)) throw new Error("pause-session response must be an object");
+  if (typeof payload.ok !== "boolean") throw new Error('pause-session response missing "ok"');
+  return { ok: payload.ok };
+}
 function parseAnswerPermissionPromptRequestPayload(payload) {
   if (!isRecord(payload)) throw new Error("answer-permission-prompt payload must be an object");
   if (typeof payload.sessionId !== "string") throw new Error('answer-permission-prompt payload missing "sessionId"');
@@ -5748,6 +5765,8 @@ function parseCapabilityRequestPayload(verb, payload) {
       return parseRegisterPushRequestPayload(payload);
     case "start-session":
       return parseStartSessionRequestPayload(payload);
+    case "pause-session":
+      return parsePauseSessionRequestPayload(payload);
     default: {
       const exhaustiveCheck = verb;
       throw new Error(`Unknown capability verb: ${String(exhaustiveCheck)}`);
@@ -6150,6 +6169,7 @@ export {
   parseCapabilityRequestPayload,
   parseDiffFileContentWire,
   parseDiffFileListWire,
+  parsePauseSessionResponsePayload,
   parsePushEnvelopePlaintext,
   parseReadBoardResponsePayload,
   parseReadDiffResponsePayload,

package/dist/wire/payloads.d.ts

@@ -136,6 +136,8 @@ export declare function parseTranscriptWindowResponsePayload(payload: JsonValue)
  *   `spawn_progress` label in flight (a first start, or a respawn that has
  *   nulled `session_id`) and a `resumable` paused task (a desktop pause
  *   nulls `session_id` too), so the feed can draw "Paused" with a Resume.
+ *   A paused task that offers no Resume (in Done, say) stays out even though
+ *   its row reads `paused: true` from 0.17.0 (see `BoardTaskWire.paused`).
  * - 'full': every non-archived task, for the one project whose board the user
  *   actually has open.
  *
@@ -340,6 +342,29 @@ export interface StartSessionResponsePayload {
 }
 /** Phone-side guard: narrows a decoded start-session response before the phone acts on it. */
 export declare function parseStartSessionResponsePayload(payload: JsonValue): StartSessionResponsePayload;
+/**
+ * Keyed by task, like `start-session`: the desktop resolves the task's live
+ * session itself (a pause clears the task's `session_id`, and a stale phone
+ * view may name a session that already ended). It suspends that session the
+ * way the desktop's Pause button does, in the column the task is already in.
+ */
+export interface PauseSessionRequestPayload {
+    taskId: string;
+    projectId: string;
+}
+/**
+ * `ok` means the pause was ACCEPTED: the task had a live session, and the
+ * desktop has recorded it as paused by the user. The agent's own shutdown runs
+ * behind this response, because it can outlast the phone's per-verb budget,
+ * and its end reaches the phone as the board event that carries
+ * `paused: true`. A task with no live session is refused (`ok: false` on the
+ * capability response), so there is no idempotent shape to report here.
+ */
+export interface PauseSessionResponsePayload {
+    ok: boolean;
+}
+/** Phone-side guard: narrows a decoded pause-session response before the phone acts on it. */
+export declare function parsePauseSessionResponsePayload(payload: JsonValue): PauseSessionResponsePayload;
 export interface AnswerPermissionPromptRequestPayload {
     sessionId: string;
     /** The prompt id the phone believes is outstanding - the handler rejects a stale/replayed answer whose id no longer matches the live awaited prompt. */
@@ -426,6 +451,7 @@ export interface CapabilityRequestPayloadMap {
     'board-tool-write': BoardToolRequestPayload;
     'register-push': RegisterPushRequestPayload;
     'start-session': StartSessionRequestPayload;
+    'pause-session': PauseSessionRequestPayload;
 }
 export interface CapabilityResponsePayloadMap {
     'read-stream': ReadStreamResponsePayload | TranscriptWindowResponsePayload;
@@ -439,6 +465,7 @@ export interface CapabilityResponsePayloadMap {
     'board-tool-write': BoardToolResponsePayload;
     'register-push': RegisterPushResponsePayload;
     'start-session': StartSessionResponsePayload;
+    'pause-session': PauseSessionResponsePayload;
 }
 /**
  * Validates and narrows a decoded capability-request's generic JsonValue

package/package.json

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