@kangentic/protocol 0.13.1 → 0.15.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

@@ -278,6 +278,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 +395,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 +408,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.13.1",
+  "version": "0.15.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",