@kangentic/protocol 0.1.0 → 0.2.0

package/dist/wire/payloads.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Concrete per-verb request/response payload shapes. `CapabilityRequestMessage.payload`
+ * and `CapabilityResponseMessage.payload` stay `JsonValue` on the envelope
+ * (messages.ts) - these interfaces narrow that generic value at the handler
+ * boundary, and the `parse*RequestPayload` guards below are the runtime
+ * checks a handler runs against an untrusted phone-originated request before
+ * trusting any field.
+ *
+ * Fields that mirror an app-internal shape the protocol package cannot
+ * import (git diff results, board rows, an MCP tool's result) stay
+ * `JsonValue`, same rationale as messages.ts/events/event.ts: this package
+ * is a dependency-light leaf shared by desktop and phone, so it does not
+ * know the desktop app's internal types. Only the fixed envelope fields
+ * (ids, actions, booleans) are concretely typed and runtime-validated here.
+ */
+import type { CapabilityVerb } from '../capabilities/verbs';
+import type { JsonValue } from './messages';
+import { type ActivityReasonWire, type ActivityStateWire, type BacklogItemWire, type BoardColumnWire, type BoardTaskWire, type DiffFileContentWire, type DiffFileListWire, type SessionUsageWire } from '../events/payloads';
+export interface ReadStreamRequestPayload {
+    sessionId: string;
+    action: 'subscribe' | 'unsubscribe';
+}
+/** Initial snapshot returned on subscribe; live updates arrive as TerminalEvent/ActivityEvent/TranscriptEvent. */
+export interface ReadStreamResponsePayload {
+    scrollback: string;
+    activity: {
+        state: ActivityStateWire | null;
+        reason: ActivityReasonWire | null;
+    };
+    usage: SessionUsageWire | null;
+    /** The live outstanding permission-prompt id (see answer-permission-prompt), or null when none is pending. */
+    awaitedPromptId: string | null;
+}
+/** Phone-side narrowing of a read-stream subscribe response. Throws on a malformed required field. */
+export declare function parseReadStreamResponsePayload(payload: JsonValue): ReadStreamResponsePayload;
+export interface ReadBoardRequestPayload {
+    projectId?: string;
+    /** Defaults to 'subscribe' when omitted. 'unsubscribe' only has an effect when projectId is set - the no-projectId project list is a one-shot read with no live feed to tear down. */
+    action?: 'subscribe' | 'unsubscribe';
+}
+export interface ReadBoardProjectSummary {
+    id: string;
+    name: string;
+}
+/** Returned when the request omits projectId - the phone's project-bootstrap listing. */
+export interface ReadBoardProjectListResponsePayload {
+    projects: ReadBoardProjectSummary[];
+}
+/** Returned when the request carries a projectId - a snapshot of that project's board. */
+export interface ReadBoardSnapshotResponsePayload {
+    projectId: string;
+    columns: BoardColumnWire[];
+    tasks: BoardTaskWire[];
+    backlog: BacklogItemWire[];
+}
+export type ReadBoardResponsePayload = ReadBoardProjectListResponsePayload | ReadBoardSnapshotResponsePayload;
+/** Phone-side narrowing of a read-board response (project list or board snapshot). Throws on a malformed required field. */
+export declare function parseReadBoardResponsePayload(payload: JsonValue): ReadBoardResponsePayload;
+/** Mirrors DiffService's GitDiffScope in the desktop app; kept as a literal union here rather than an import, since the protocol package does not depend on the app. */
+export type ReadDiffScope = 'working' | 'staged' | 'branch';
+export interface ReadDiffRequestPayload {
+    taskId: string;
+    projectId: string;
+    filePath?: string;
+    scope?: ReadDiffScope;
+    /** Defaults to 'subscribe' when omitted. Only the file-list watch (no filePath) has a live feed to tear down; a single-file content fetch is always one-shot. */
+    action?: 'subscribe' | 'unsubscribe';
+}
+/** The desktop's GitDiffFilesResult mirror (no filePath) or GitFileContentResult mirror (filePath set). */
+export type ReadDiffResponsePayload = DiffFileListWire | DiffFileContentWire;
+/** Phone-side narrowing of a read-diff response, discriminated by the presence of "files". Throws on a malformed required field. */
+export declare function parseReadDiffResponsePayload(payload: JsonValue): ReadDiffResponsePayload;
+export interface SendUserMessageRequestPayload {
+    sessionId: string;
+    text: string;
+}
+export interface SendUserMessageResponsePayload {
+    delivered: boolean;
+}
+export interface MoveTaskRequestPayload {
+    taskId: string;
+    targetSwimlaneId: string;
+    targetPosition: number;
+    projectId: string;
+}
+export interface MoveTaskResponsePayload {
+    ok: boolean;
+}
+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. */
+    promptId: string;
+    keystrokes: string;
+}
+export interface AnswerPermissionPromptResponsePayload {
+    answered: boolean;
+}
+export interface InteractiveTerminalRequestPayload {
+    sessionId: string;
+    data: string;
+}
+export interface InteractiveTerminalResponsePayload {
+    written: boolean;
+}
+export interface BoardToolRequestPayload {
+    tool: string;
+    params: JsonValue;
+}
+export interface BoardToolResponsePayload {
+    result: JsonValue;
+}
+export interface CapabilityRequestPayloadMap {
+    'read-stream': ReadStreamRequestPayload;
+    'read-board': ReadBoardRequestPayload;
+    'read-diff': ReadDiffRequestPayload;
+    'send-user-message': SendUserMessageRequestPayload;
+    'move-task': MoveTaskRequestPayload;
+    'answer-permission-prompt': AnswerPermissionPromptRequestPayload;
+    'interactive-terminal': InteractiveTerminalRequestPayload;
+    'board-tool-read': BoardToolRequestPayload;
+    'board-tool-write': BoardToolRequestPayload;
+}
+export interface CapabilityResponsePayloadMap {
+    'read-stream': ReadStreamResponsePayload;
+    'read-board': ReadBoardResponsePayload;
+    'read-diff': ReadDiffResponsePayload;
+    'send-user-message': SendUserMessageResponsePayload;
+    'move-task': MoveTaskResponsePayload;
+    'answer-permission-prompt': AnswerPermissionPromptResponsePayload;
+    'interactive-terminal': InteractiveTerminalResponsePayload;
+    'board-tool-read': BoardToolResponsePayload;
+    'board-tool-write': BoardToolResponsePayload;
+}
+/**
+ * Validates and narrows a decoded capability-request's generic JsonValue
+ * payload into its verb-specific shape. This is the runtime trust boundary:
+ * every field the phone supplies is checked before a handler reads it.
+ */
+export declare function parseCapabilityRequestPayload<Verb extends CapabilityVerb>(verb: Verb, payload: JsonValue): CapabilityRequestPayloadMap[Verb];

package/package.json

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