@kangentic/protocol 0.1.1 → 0.3.0

package/dist/capabilities/board-tools.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The board-tool names a phone may pass in a board-tool-read /
+ * board-tool-write request's `tool` field. Each name is the desktop's
+ * INTERNAL command-registry key (src/main/agent/commands/index.ts
+ * `commandHandlers`), not a public MCP tool name, and this is NOT the MCP
+ * protocol - see the desktop's board-tool-allowlist.ts doc comment for the
+ * full rationale and the deliberate exclusions (query_db, move_task,
+ * list_tasks, list_columns, list_backlog).
+ *
+ * The desktop builds its enforcement allowlist FROM these tuples, so its
+ * allowlist parity test (board-tool-allowlist.test.ts, which diffs the
+ * allowlist against the real `commandHandlers` key set) transitively keeps
+ * 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", "get_handoff_context", "get_transcript", "get_session_files", "get_session_events"];
+export declare const BOARD_TOOL_WRITE_NAMES: readonly ["create_task", "update_task", "delete_task", "link_pr", "remove_attachment", "update_column", "create_backlog_task", "promote_backlog", "update_backlog_item", "delete_backlog_item"];
+export type BoardToolReadName = (typeof BOARD_TOOL_READ_NAMES)[number];
+export type BoardToolWriteName = (typeof BOARD_TOOL_WRITE_NAMES)[number];
+export type BoardToolName = BoardToolReadName | BoardToolWriteName;
+export declare function isBoardToolReadName(value: string): value is BoardToolReadName;
+export declare function isBoardToolWriteName(value: string): value is BoardToolWriteName;

package/dist/capabilities/verbs.d.ts

@@ -9,7 +9,7 @@
  * wire a handler, and a device's roster entry still has to include it in
  * its CapabilitySet.
  */
-export declare const CAPABILITY_VERBS: readonly ["read-stream", "read-board", "read-diff", "send-user-message", "move-task", "answer-permission-prompt"];
+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"];
 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/crypto/slot.d.ts

@@ -0,0 +1 @@
+export declare function deriveSessionSlotId(desktopStaticPublicKey: Uint8Array, phoneStaticPublicKey: Uint8Array): string;

package/dist/events/event.d.ts

@@ -1,29 +1,90 @@
 /**
- * The event contract skeleton the phone consumes. Phase 1 establishes the
- * three event FAMILIES (transcript, board, activity) and their envelope
- * shape; Phase 2 (data feeds & interactive control) is what actually maps
- * desktop internals - SessionManager's `data`/`activity` events,
- * transcript-service output, repository/DiffService mutations - onto
- * these envelopes. Keeping `payload` as JsonValue here rather than a
- * fully-typed shape per event avoids guessing at Phase 2's real mapping
- * before that integration exists.
+ * The event contract the phone consumes, pushed as EventMessage.event over
+ * an established BridgeSession once Phase 2's capability handlers (desktop
+ * bridge module) subscribe SessionManager/transcript-service/DiffService to
+ * a session's live state. Five kinds:
+ *
+ * - transcript: a revision-gated delta from resolveTaskTranscript, for the
+ *   phone's transcript-styled conversation view.
+ * - activity: a discriminated union consolidating SessionManager's
+ *   separate `activity`/`usage`/`event` emissions plus permission state
+ *   (carrying the synthesized prompt id `answer-permission-prompt` binds
+ *   to), so one event kind covers session telemetry instead of three.
+ * - terminal: raw PTY output from the unfiltered data-tap, for the phone's
+ *   raw-terminal-mirror view (a distinct consumer from the parsed
+ *   transcript).
+ * - board: a board-mutation notification, filterable by project and
+ *   (optionally) task.
+ * - diff: a payload-less "something under this task's worktree changed,
+ *   re-fetch via read-diff" signal, mirroring the desktop's GIT_DIFF_CHANGED.
+ *
+ * Payload contents are typed by the wire mirrors in events/payloads.ts
+ * (protocol Phase 2); the desktop's wire-mappers produce them and
+ * isBridgeEvent() is the phone's structural trust boundary for a decoded
+ * event before its router dispatches on `kind`.
  */
 import type { JsonValue } from '../wire/messages';
+import { type ActivityReasonWire, type ActivityStateWire, type SessionEventWire, type SessionUsageWire, type TranscriptEventPayload } from './payloads';
 export interface TranscriptEvent {
     kind: 'transcript';
     sessionId: string;
     taskId: string;
-    payload: JsonValue;
-}
-export interface BoardEvent {
-    kind: 'board';
-    taskId: string;
-    payload: JsonValue;
+    /** Incremental (protocol v2): indexed upserts or a reset signal, never the whole transcript. See TranscriptEventPayload. */
+    payload: TranscriptEventPayload;
 }
+export type ActivityEventPayload = {
+    type: 'activity';
+    state: ActivityStateWire;
+    reason: ActivityReasonWire;
+} | {
+    type: 'usage';
+    usage: SessionUsageWire;
+} | {
+    type: 'event';
+    event: SessionEventWire;
+} | {
+    type: 'permission';
+    promptId: string;
+    pending: boolean;
+};
 export interface ActivityEvent {
     kind: 'activity';
     sessionId: string;
     taskId: string;
-    payload: JsonValue;
+    payload: ActivityEventPayload;
 }
-export type BridgeEvent = TranscriptEvent | BoardEvent | ActivityEvent;
+export interface TerminalEvent {
+    kind: 'terminal';
+    sessionId: string;
+    taskId: string;
+    payload: {
+        data: string;
+    };
+}
+export interface BoardEventPayload {
+    change: 'task-created' | 'task-updated' | 'task-deleted' | 'swimlane-updated' | 'backlog-changed';
+    ids: string[];
+}
+export interface BoardEvent {
+    kind: 'board';
+    projectId: string;
+    taskId?: string;
+    payload: BoardEventPayload;
+}
+export interface DiffEvent {
+    kind: 'diff';
+    taskId: string;
+    payload: null;
+}
+export type BridgeEvent = TranscriptEvent | ActivityEvent | TerminalEvent | BoardEvent | DiffEvent;
+/**
+ * Narrows an activity event's payload to its typed union. Throws on a
+ * malformed required field so the caller can drop the event cleanly.
+ */
+export declare function parseActivityEventPayload(payload: JsonValue): ActivityEventPayload;
+/**
+ * Full structural validation of a decoded event - envelope ids AND payload
+ * shape per kind. This is the phone-side trust boundary its feed router
+ * runs before dispatching; a false return means "drop the event".
+ */
+export declare function isBridgeEvent(value: unknown): value is BridgeEvent;

package/dist/events/payloads.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Wire-level mirrors of the desktop-app shapes that flow to a phone inside
+ * feed events and read-* responses, plus the runtime guards a phone runs
+ * before trusting any field. Phase 2 of the protocol: the envelope
+ * (messages.ts) and event skeleton (event.ts) were final in Phase 1; these
+ * types pin down the payload CONTENTS that were deferred as JsonValue.
+ *
+ * These are deliberate structural MIRRORS, not imports: this package is a
+ * dependency-light leaf shared by desktop and phone, so it cannot import
+ * the desktop app's internal types (src/shared/types.ts). The desktop's
+ * wire-mappers (src/main/mobile-bridge/handlers/wire-mappers.ts) are the
+ * one place each mirror meets its source shape, so a drift shows up there
+ * as a compile error instead of a silent phone-side parse failure.
+ *
+ * Guard philosophy: validate the discriminants and required scalars a
+ * consumer dispatches on, pass unrecognized extra fields through untouched
+ * (lenient forward compatibility - an older phone must tolerate fields a
+ * newer desktop adds), and throw on a malformed required field so the
+ * caller can drop the payload cleanly.
+ */
+import type { JsonValue } from '../wire/messages';
+/** Mirrors the desktop's TranscriptBlock. `tool_use.input` is JSON-sanitized by the desktop mapper before it reaches the wire. */
+export type TranscriptBlockWire = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'thinking';
+    text: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: JsonValue;
+};
+/** Mirrors the desktop's per-turn TranscriptTurnUsage token counts. */
+export interface TranscriptTurnUsageWire {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens: number;
+    cacheReadInputTokens: number;
+}
+export type TranscriptSystemSubtypeWire = 'compaction' | 'command' | 'command_output' | 'session_boundary';
+/** Mirrors the desktop's TranscriptEntry union - the parsed conversation the phone's transcript-terminal renders. */
+export type TranscriptEntryWire = {
+    kind: 'user';
+    uuid: string;
+    ts: number;
+    text: string;
+} | {
+    kind: 'assistant';
+    uuid: string;
+    ts: number;
+    model?: string;
+    agentName?: string;
+    usage?: TranscriptTurnUsageWire;
+    blocks: TranscriptBlockWire[];
+} | {
+    kind: 'tool_result';
+    uuid: string;
+    ts: number;
+    toolUseId: string;
+    content: string;
+    isError?: boolean;
+} | {
+    kind: 'system';
+    uuid: string;
+    ts: number;
+    subtype: TranscriptSystemSubtypeWire;
+    text: string;
+};
+/** One transcript entry at its absolute position in the full transcript at the delta's revision. */
+export interface TranscriptUpsertWire {
+    index: number;
+    entry: TranscriptEntryWire;
+}
+/**
+ * Protocol v2 transcript payload: incremental, never the whole transcript.
+ *
+ * - 'delta' carries only the entries that changed or appeared since the
+ *   last delta the desktop sent on this subscription, as absolute-indexed
+ *   upserts in ascending order. A large delta is split across several
+ *   events (same revision) so every frame stays well under the transport
+ *   caps and the first chunk renders without waiting for the rest. The
+ *   phone applies upserts inside or adjacent to its loaded window and
+ *   re-requests a window when it detects a gap.
+ * - 'reset' tells the phone its local state is unreconstructable from
+ *   deltas (entries removed or reordered, or a degraded transcript source
+ *   whose uuids are unstable) - drop local entries and re-request a
+ *   window via the read-stream 'transcript-window' action.
+ *
+ * `revision` is the desktop's monotonically increasing whole-transcript
+ * version; `totalEntries` is the full transcript length at that revision,
+ * which is how the phone knows history extends above its window.
+ */
+export type TranscriptEventPayload = {
+    mode: 'delta';
+    revision: number;
+    totalEntries: number;
+    upserts: TranscriptUpsertWire[];
+} | {
+    mode: 'reset';
+    revision: number;
+    totalEntries: number;
+};
+/** Mirrors the desktop's ActivityState. 'permission' means the agent paused for user approval (incl. AskUserQuestion / ExitPlanMode pauses). */
+export type ActivityStateWire = 'thinking' | 'idle' | 'permission';
+/** Mirrors the desktop's ActivityReason discriminated union. */
+export type ActivityReasonWire = {
+    kind: 'idle';
+} | {
+    kind: 'permission';
+} | {
+    kind: 'tool';
+    pendingCount: number;
+    currentTool: string | null;
+} | {
+    kind: 'subagent';
+    depth: number;
+} | {
+    kind: 'background-shell';
+    count: number;
+    ids: string[];
+} | {
+    kind: 'turn-active';
+};
+/**
+ * Phone-needed subset of the desktop's SessionUsage. The desktop mapper
+ * explicitly picks these fields; renderer-only extras (transcriptPath,
+ * rateLimits, sessionId echo) never reach the wire.
+ */
+export interface SessionUsageWire {
+    contextWindow: {
+        usedPercentage: number;
+        usedTokens: number;
+        cacheTokens: number;
+        totalInputTokens: number;
+        totalOutputTokens: number;
+        contextWindowSize: number;
+    };
+    cost: {
+        totalCostUsd: number;
+        totalDurationMs: number;
+    };
+    toolCallCount?: number;
+    model: {
+        id: string;
+        displayName: string;
+        effort?: string;
+    };
+}
+/**
+ * Loose mirror of the desktop's SessionEvent telemetry entry. `type` is
+ * deliberately a plain string, not the desktop's EventType enum, so a new
+ * desktop event type does not break an older phone's parser.
+ */
+export interface SessionEventWire {
+    ts: number;
+    type: string;
+    tool?: string;
+    toolId?: string;
+    detail?: string;
+}
+/** Phone-needed subset of the desktop's Swimlane row (snake_case preserved so the desktop mapper is a mechanical pick). */
+export interface BoardColumnWire {
+    id: string;
+    name: string;
+    description: string | null;
+    role: string | null;
+    position: number;
+    color: string;
+    icon: string | null;
+    is_archived: boolean;
+    is_ghost: boolean;
+}
+/** Phone-needed subset of the desktop's Task row. A non-null `session_id` is the live-session signal the phone's triage view keys on. */
+export interface BoardTaskWire {
+    id: string;
+    display_id: number;
+    title: string;
+    description: string;
+    swimlane_id: string;
+    position: number;
+    agent: string | null;
+    session_id: string | null;
+    worktree_path: string | null;
+    branch_name: string | null;
+    pr_number: number | null;
+    pr_url: string | null;
+    pr_state: string | null;
+    base_branch: string | null;
+    labels: string[];
+    priority: number;
+    attachment_count: number;
+    archived_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** Phone-needed subset of the desktop's BacklogTask row. */
+export interface BacklogItemWire {
+    id: string;
+    title: string;
+    description: string;
+    priority: number;
+    labels: string[];
+    position: number;
+    item_type: string | null;
+    external_url: string | null;
+    attachment_count: number;
+    created_at: string;
+    updated_at: string;
+}
+/** Mirrors the desktop's GitDiffStatus. */
+export type DiffFileStatusWire = 'A' | 'M' | 'D' | 'R' | 'C' | 'U';
+/** Exact mirror of the desktop's GitDiffFileEntry. */
+export interface DiffFileWire {
+    path: string;
+    status: DiffFileStatusWire;
+    insertions: number;
+    deletions: number;
+    oldPath?: string;
+    binary: boolean;
+}
+/** Exact mirror of the desktop's GitDiffFilesResult - the read-diff file-list response. */
+export interface DiffFileListWire {
+    files: DiffFileWire[];
+    totalInsertions: number;
+    totalDeletions: number;
+}
+/** Exact mirror of the desktop's GitFileContentResult - the read-diff single-file response. */
+export interface DiffFileContentWire {
+    original: string;
+    modified: string;
+    language: string;
+}
+/** Narrows a transcript entry array (windowed-history pages). Throws on a malformed entry so the caller can drop the payload. */
+export declare function parseTranscriptEntriesWire(payload: JsonValue): TranscriptEntryWire[];
+/** Narrows a transcript event's delta/reset payload. Throws on a malformed required field so the caller can drop the push. */
+export declare function parseTranscriptEventPayload(payload: JsonValue): TranscriptEventPayload;
+/** True for a well-formed ActivityStateWire value. */
+export declare function isActivityStateWire(value: unknown): value is ActivityStateWire;
+/** True for a well-formed ActivityReasonWire value. */
+export declare function isActivityReasonWire(value: unknown): value is ActivityReasonWire;
+/** Narrows a usage payload to the SessionUsageWire subset. Throws on a malformed required field. */
+export declare function parseSessionUsageWire(payload: JsonValue): SessionUsageWire;
+/** Narrows a session-event payload to SessionEventWire. Throws on a malformed required field. */
+export declare function parseSessionEventWire(payload: JsonValue): SessionEventWire;
+/** Narrows one board-column row. Throws on a malformed required field. */
+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;
+/** Narrows one backlog-item row. Throws on a malformed required field. */
+export declare function parseBacklogItemWire(value: JsonValue): BacklogItemWire;
+/** Narrows a read-diff file-list payload. Throws on a malformed required field. */
+export declare function parseDiffFileListWire(payload: JsonValue): DiffFileListWire;
+/** Narrows a read-diff single-file payload. Throws on a malformed required field. */
+export declare function parseDiffFileContentWire(payload: JsonValue): DiffFileContentWire;