@kangentic/protocol 0.14.0 → 0.16.0

package/dist/capabilities/verbs.d.ts

@@ -8,8 +8,17 @@
  * the desktop's capability router (Phase 2) still has to implement and
  * wire a handler, and a device's roster entry still has to include it in
  * its CapabilitySet.
+ *
+ * Append only. The desktop mirrors this tuple by hand in its import-free
+ * types module and pins the two equal INDEX for index, so a verb inserted
+ * mid-list fails that parity test even when both lists hold the same names.
+ *
+ * `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.
  */
-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"];
+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 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/event.d.ts

@@ -27,6 +27,7 @@
  * event before its router dispatches on `kind`.
  */
 import type { JsonValue } from '../wire/messages';
+import { type ReadStreamSessionStatusWire } from '../wire/payloads';
 import { type ActivityReasonWire, type ActivityStateWire, type SessionEventWire, type SessionUsageWire, type TerminalDimensionsWire, type TranscriptEventPayload } from './payloads';
 export interface TranscriptEvent {
     kind: 'transcript';
@@ -60,16 +61,33 @@ export type ActivityEventPayload = {
     options?: string[];
 }
 /**
- * The streamed session's PTY exited. Pushed once by the desktop's
- * read-stream subscription right before it tears itself down, so the
- * phone learns "this session is over" from the feed itself instead of
- * inferring it from silence. `intentional` distinguishes a deliberate
- * stop (desktop Stop button, suspend, shutdown) from a crash.
+ * The feed's last word: the desktop's read-stream subscription pushes this
+ * once, right before it tears itself down, so the phone learns "this
+ * session is over" from the feed itself instead of inferring it from
+ * silence. Sent when the streamed session's PTY exits. From 0.16.0 it is
+ * also sent when a paused row, which the feed holds without a PTY, is
+ * replaced or removed. `intentional` distinguishes a deliberate stop
+ * (desktop Stop button, suspend, shutdown, a resume replacing a paused row)
+ * from a crash.
+ *
+ * `successorSessionId`, when present, names the session that replaced this
+ * one for the same task. A desktop resume never reuses the paused session's
+ * id: it spawns a new session and drops the paused row, so a feed held on
+ * the paused session can only end, never turn back into `running`. The task
+ * continues as the successor; subscribe to it. Its snapshot carries
+ * `sessionStatus` (`queued` when the desktop's concurrency limit holds it)
+ * and `resuming: true`. Absent when no successor exists (a removed paused
+ * row, or a successor whose own spawn failed), and from pre-0.16.0
+ * desktops, which never end a feed this way and leave it silent instead. An
+ * older phone ignores the field and still sees an ended session.
  *
  * `spawnProgressLabel`, when present, means the desktop had a respawn in
  * flight for this task when the session ended - a same-column respawn
  * (model switch, agent switch, effort change, isolated-session-track
- * switch) rather than a genuine park. Read it as what the desktop
+ * switch) or an in-place restart (a model or effort pick on the running
+ * task, a board-profile change, or the auto_command escalation that
+ * re-sends a command as the resume prompt, "Re-sending command...") rather
+ * than a genuine park. Read it as what the desktop
  * believed, not as a fact about what happens next; the caveats below
  * bound it. `intentional` cannot carry this distinction on its own:
  * the desktop's SessionManager.suspend() sets `status = 'suspended'`
@@ -78,7 +96,8 @@ export type ActivityEventPayload = {
  * the desktop's own display text for what it is doing ("Switching
  * model...", "Starting agent...", a live git-queue wait count) - treat it
  * as untrusted display text, not a key to switch on, cap its length, and
- * fall back to generic copy rather than parsing it.
+ * fall back to generic copy rather than parsing it. From 0.16.0 the desktop
+ * sends it sanitized as `BoardTaskWire.spawn_progress` describes.
  *
  * INTENT, not a guarantee, on the same terms `BoardColumnWire.spawns_session`
  * documents: the desktop can suspend without a successor ever landing (a
@@ -104,6 +123,41 @@ export type ActivityEventPayload = {
     type: 'session-ended';
     intentional: boolean;
     spawnProgressLabel?: string;
+    successorSessionId?: string;
+}
+/**
+ * The streamed session's lifecycle status changed after the subscribe
+ * snapshot: `queued` -> `running` when the desktop's concurrency limit
+ * frees a slot, -> `suspended` on a pause or a respawn, -> `exited` when the
+ * desktop retires a session whose agent already ended. Sent only on an
+ * actual change, for the same session id only. A resume is a NEW session
+ * id, so suspended -> running never arrives here: see `session-ended`'s
+ * `successorSessionId`.
+ *
+ * A `suspended` push precedes the PTY's `session-ended` when a running
+ * session is suspended, so for an instant both say the session is parked.
+ *
+ * Precedence, matching the desktop card: a non-null `spawn_progress` on the
+ * task's board row overrides `suspended` (the desktop suspends a session
+ * before every model, agent or effort respawn), and never `running` or
+ * `queued`. Read `suspended` alone as "Paused"; read it next to a label as
+ * that label.
+ *
+ * `resuming` and `resumable` repeat the snapshot fields so the payload is
+ * complete on its own. The desktop re-reads all three on each lifecycle
+ * edge of this session and sends the payload when any of them differs. A
+ * move to Done or an archive of a paused task is no edge of its row, so
+ * `resumable` here can stay true until the feed ends; gate Resume on
+ * `BoardTaskWire.resumable`, which the board event for that move refreshes.
+ * Absent from pre-0.16.0 desktops, whose phones drop the unknown
+ * type through `isBridgeEvent` and keep inferring status from activity
+ * events.
+ */
+ | {
+    type: 'status';
+    status: ReadStreamSessionStatusWire;
+    resuming: boolean;
+    resumable: boolean;
 }
 /**
  * The agent's most recent assistant message, already collapsed to a short

package/dist/events/payloads.d.ts

@@ -160,6 +160,12 @@ export interface SessionUsageWire {
         totalCostUsd: number;
         totalDurationMs: number;
     };
+    /**
+     * Completed tool calls across every run of the session. A resume (an app
+     * restart, a pause and resume) is a new run, and the desktop adds the
+     * session's earlier runs to the live count. Optional: an older desktop
+     * omits it.
+     */
     toolCallCount?: number;
     model: {
         id: string;
@@ -325,6 +331,77 @@ export interface BoardTaskWire {
     archived_at: string | null;
     created_at: string;
     updated_at: string;
+    /**
+     * The task's in-flight spawn-progress label, the text of the desktop card's
+     * preparing footer: "Creating worktree...", "Fetching latest...",
+     * "Waiting (2 ahead)", "Switching model...", "Starting agent...", a git-queue
+     * wait with its elapsed time, and any staleness note the desktop appends
+     * ("Starting agent... (base 3 behind)"). The desktop announces every change
+     * with a `task-updated` board event, coalesced to at most about one a
+     * second per task.
+     *
+     * Untrusted display text, the same terms as `session-ended`'s
+     * `spawnProgressLabel`: never parse it or switch on it, and fall back to
+     * generic copy. It can carry text the desktop did not write: a column
+     * automation's name, in `Running "<name>"...`, from a config a team may
+     * share. From 0.16.0 the desktop strips escape sequences, control characters,
+     * invisible format characters (bidi controls, the zero-width space, the soft
+     * hyphen, the byte order mark) and tag characters outside the England,
+     * Scotland and Wales flag emoji, turns line breaks and tabs into spaces, and
+     * caps it at
+     * 120 characters ending in "...", but a client still caps it for its own
+     * layout.
+     *
+     * Precedence, matching the desktop card: a label overrides a `suspended`
+     * session status (a respawn is in flight behind a session that was just
+     * suspended for it), and never a `running` or `queued` one. A client that
+     * reads the read-stream feed's `status: 'suspended'` during a model or
+     * effort switch shows this label, not "Paused".
+     *
+     * A spawn path that dies without clearing its label leaves it in place for
+     * up to the desktop's 120s spawn-progress TTL, and the TTL expiry sends no
+     * board event, so a stale label can outlive its spawn until the next
+     * snapshot. Null or absent means no spawn is in flight, or a desktop that
+     * predates the field (pre-0.16.0). Under `view: 'sessions'` a task with a
+     * label is kept even while its `session_id` is null, so a first start and
+     * a respawn's gap stay visible.
+     *
+     * Declared OPTIONAL (`?`) like `pr_merge_readiness`; `parseBoardTaskWire`
+     * populates the key from every real wire response.
+     */
+    spawn_progress?: string | null;
+    /**
+     * True when the task's session is paused and the desktop's own task view
+     * would offer Resume for it: the task is not in To Do or Done and not
+     * archived. It is the desktop's promise that `start-session` for this task
+     * resumes the paused session exactly as its Resume button does: the same
+     * conversation, the column's model, effort and permission, a "Resuming
+     * session..." label, and NO enter automations or column message. Gate a
+     * phone's Resume control on THIS field.
+     *
+     * On the board row because the phone always holds the board: a desktop
+     * pause clears the task's `session_id`, so a phone keeps no read-stream on
+     * a paused session (the stream's `resumable` covers only an open session
+     * screen through the suspend itself). A pause, a resume, a column move and
+     * an archive each reach the phone as a `task-updated` board event, after
+     * which the next snapshot carries the new value. Under `view: 'sessions'` a
+     * resumable task is kept even though its `session_id` is null, so an agent
+     * feed can draw it as Paused with a Resume control.
+     *
+     * Explicit on purpose, never inferred from another field: a pre-0.16.0
+     * desktop answers `start-session` by STARTING the column, which re-runs its
+     * enter automations and resends its message (a paused task in Code Review
+     * would get `/code-review` again). Null or absent means such a desktop; a
+     * client offers no Resume then. While `spawn_progress` is non-null a spawn
+     * is already in flight and the desktop card shows that label instead of a
+     * 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.
+     *
+     * Declared OPTIONAL (`?`) like `spawns_session`; `parseBoardTaskWire`
+     * populates the key from every real wire response.
+     */
+    resumable?: boolean | null;
 }
 /** Phone-needed subset of the desktop's BacklogTask row. */
 export interface BacklogItemWire {