@kangentic/protocol 0.14.0 → 0.16.0

package/dist/wire/framing.d.ts

@@ -1,8 +1,37 @@
-import type { BridgeMessage } from './messages';
+import type { BridgeMessage, CapabilityErrorCode } from './messages';
 export declare const MAX_FRAME_LENGTH: number;
 /** Upper bound on the JSON a compressed frame may declare/inflate to. */
 export declare const MAX_DECODED_LENGTH: number;
 /** JSON below this size ships raw - deflate overhead is not worth it. */
 export declare const COMPRESSION_THRESHOLD: number;
+/** The `code` a desktop puts on its refusal of a verb its build does not know. */
+export declare const UNSUPPORTED_VERB_ERROR_CODE: CapabilityErrorCode;
+/**
+ * Thrown by `decodeMessage` for a capability-request whose envelope is
+ * well-formed (a string `requestId`, a string `verb`, a JSON `payload`) but
+ * whose verb this build's `CAPABILITY_VERBS` does not carry. It is the one
+ * decode failure that names its request, so the receiver can ANSWER it
+ * (`{ ok: false, code: 'unsupported-verb' }`) instead of dropping the frame.
+ *
+ * Without this a desktop that predates a verb sent nothing back at all, and
+ * the phone that sent it timed out, unable to tell an old desktop from an
+ * unreachable one. Every verb added to the protocol has that failure mode on
+ * a mixed-version pair. A frame that is NOT a well-formed request (a missing
+ * `requestId`, a non-string `verb`, a non-JSON `payload`) still throws a
+ * plain `Error` and stays a silent rejection: there is nothing to answer, and
+ * answering unstructured input would hand a probe to whoever sent it.
+ */
+export declare class UnsupportedVerbError extends Error {
+    readonly requestId: string;
+    readonly verb: string;
+    constructor(requestId: string, verb: string);
+}
+/**
+ * Keyed on `name`, not `instanceof`: the desktop consumes this package from
+ * source through a workspace alias while the mobile app resolves the published
+ * `dist`, and a bundler can hold two copies of the class, which `instanceof`
+ * would tell apart.
+ */
+export declare function isUnsupportedVerbError(error: unknown): error is UnsupportedVerbError;
 export declare function encodeMessage(message: BridgeMessage): Uint8Array;
 export declare function decodeMessage(bytes: Uint8Array): BridgeMessage;

package/dist/wire/messages.d.ts

@@ -30,6 +30,15 @@ export interface CapabilityRequestMessage {
     verb: CapabilityVerb;
     payload: JsonValue;
 }
+/**
+ * A stable key a client can branch on, beside the human-readable `error`.
+ * Today the one member is the refusal a desktop sends for a verb its build
+ * does not know (see `UnsupportedVerbError` in framing.ts), so a newer phone
+ * can tell "desktop is old" from "desktop is unreachable" and show the right
+ * copy. A union rather than a bare string so a second code is a deliberate
+ * addition here, not a typo at a call site.
+ */
+export type CapabilityErrorCode = 'unsupported-verb';
 export interface CapabilityResponseMessage {
     type: 'capability-response';
     requestId: string;
@@ -37,6 +46,12 @@ export interface CapabilityResponseMessage {
     payload?: JsonValue;
     /** Present only when ok is false. */
     error?: string;
+    /**
+     * Present only when ok is false AND the refusal has a stable key. Additive
+     * on the wire: a peer whose decoder predates the field rebuilds the message
+     * from the keys it knows and keeps `error`, so the text still shows.
+     */
+    code?: CapabilityErrorCode;
 }
 export interface EventMessage {
     type: 'event';

package/dist/wire/payloads.d.ts

@@ -53,6 +53,8 @@ export interface ReadStreamRequestPayload {
  * snapshot races the session's teardown.
  */
 export type ReadStreamSessionStatusWire = 'running' | 'queued' | 'suspended' | 'exited';
+/** True for a value that is one of the four session lifecycle statuses. */
+export declare function isReadStreamSessionStatusWire(value: unknown): value is ReadStreamSessionStatusWire;
 /** Initial snapshot returned on subscribe; live updates arrive as TerminalEvent/ActivityEvent/TranscriptEvent. */
 export interface ReadStreamResponsePayload {
     scrollback: string;
@@ -80,9 +82,34 @@ export interface ReadStreamResponsePayload {
     ptyDimensions?: TerminalDimensionsWire;
     /**
      * The session's lifecycle status at snapshot time. Absent from
-     * pre-0.5.0 desktops; the phone then assumes 'running'.
+     * pre-0.5.0 desktops; the phone then assumes 'running'. Later changes for
+     * the same session id arrive as the `status` activity payload.
      */
     sessionStatus?: ReadStreamSessionStatusWire;
+    /**
+     * True when the desktop spawned this session as a resume of an earlier
+     * conversation. The desktop card then reads "Resuming agent..." where it
+     * would read "Starting agent...", for as long as a running session has no
+     * model name yet. Fixed for the life of a session id. Absent from pre-0.16.0
+     * desktops; read absent as false.
+     */
+    resuming?: boolean;
+    /**
+     * The streamed session's copy of `BoardTaskWire.resumable`: true when this
+     * session is paused (`suspended`) and the desktop's own task view would
+     * offer Resume for it. Gate a Resume control on the BOARD ROW's field, not
+     * this one: a desktop pause clears the task's `session_id`, so a phone holds
+     * no stream on a paused session once its board refreshes. This copy keeps a
+     * session screen that is open during the suspend current until then, and it
+     * carries the same promise: `start-session` resumes rather than starts.
+     *
+     * Recomputed on each lifecycle edge of this session, and a `status` push
+     * carries it even when it is the only value that changed. A move to Done or
+     * an archive of a paused task is no edge of its row, so this copy can stay
+     * true after the board row's turns false. Absent from pre-0.16.0 desktops,
+     * which a client reads as "offer no Resume".
+     */
+    resumable?: boolean;
 }
 /** Phone-side narrowing of a read-stream subscribe response. Throws on a malformed required field. */
 export declare function parseReadStreamResponsePayload(payload: JsonValue): ReadStreamResponsePayload;
@@ -105,7 +132,10 @@ export declare function parseTranscriptWindowResponsePayload(payload: JsonValue)
  * - 'sessions': columns, per-column task counts, and only the non-archived
  *   tasks that carry a `session_id`. This is what an agent feed renders: it
  *   watches every project at once but only ever draws the handful of tasks
- *   with a live agent on them.
+ *   with a live agent on them. From 0.16.0 it also keeps a task with a
+ *   `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.
  * - 'full': every non-archived task, for the one project whose board the user
  *   actually has open.
  *
@@ -195,7 +225,7 @@ export interface ReadBoardProjectListResponsePayload {
 export interface ReadBoardSnapshotResponsePayload {
     projectId: string;
     columns: BoardColumnWire[];
-    /** Non-archived tasks; filtered to the ones carrying a `session_id` when `view` is 'sessions'. */
+    /** Non-archived tasks; filtered when `view` is 'sessions' (see ReadBoardView for which tasks it keeps). */
     tasks: BoardTaskWire[];
     /** Absent whenever the request carried a `view` (protocol 0.9.0) - no phone has ever rendered it. */
     backlog?: BacklogItemWire[];
@@ -278,6 +308,38 @@ export interface MoveTaskRequestPayload {
 export interface MoveTaskResponsePayload {
     ok: boolean;
 }
+/**
+ * Keyed by task, not by session: the state this verb exists for is a task
+ * whose session has ENDED, so there is no live session id to name. The
+ * desktop spawns or resumes in the task's current column with that column's
+ * settings; a live session is an idempotent no-op.
+ */
+export interface StartSessionRequestPayload {
+    taskId: string;
+    projectId: string;
+}
+/**
+ * What the desktop did with an accepted start. `starting`: the worktree and
+ * PTY work run behind this response and the successor's arrival reaches the
+ * phone as a board / stream event, the same way a column move's does. `live`:
+ * the task already had a running session, nothing was spawned, and NO event
+ * is coming, so a phone that tapped Start from a stale screen must refresh
+ * its board and stream itself rather than wait.
+ */
+export type StartSessionOutcome = 'starting' | 'live';
+/**
+ * `ok` means the start was ACCEPTED (the task exists, is in a column that may
+ * run an agent, and either has no live session or already has one), not that
+ * a successor is up: the desktop answers before the worktree and PTY work so
+ * the response fits the phone's per-verb budget. `outcome` says which of the
+ * two accepted shapes this was.
+ */
+export interface StartSessionResponsePayload {
+    ok: boolean;
+    outcome: StartSessionOutcome;
+}
+/** Phone-side guard: narrows a decoded start-session response before the phone acts on it. */
+export declare function parseStartSessionResponsePayload(payload: JsonValue): StartSessionResponsePayload;
 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. */
@@ -363,6 +425,7 @@ export interface CapabilityRequestPayloadMap {
     'board-tool-read': BoardToolRequestPayload;
     'board-tool-write': BoardToolRequestPayload;
     'register-push': RegisterPushRequestPayload;
+    'start-session': StartSessionRequestPayload;
 }
 export interface CapabilityResponsePayloadMap {
     'read-stream': ReadStreamResponsePayload | TranscriptWindowResponsePayload;
@@ -375,6 +438,7 @@ export interface CapabilityResponsePayloadMap {
     'board-tool-read': BoardToolResponsePayload;
     'board-tool-write': BoardToolResponsePayload;
     'register-push': RegisterPushResponsePayload;
+    'start-session': StartSessionResponsePayload;
 }
 /**
  * Validates and narrows a decoded capability-request's generic JsonValue

package/package.json

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