@pocketcoder/shared 0.0.2

package/src/types/messages.ts

@@ -0,0 +1,1310 @@
+/**
+ * WebSocket message types for communication between daemon, relay, and client.
+ * All types match the PRD exactly.
+ */
+
+// ---------------------------------------------------------------------------
+// Shared primitives
+// ---------------------------------------------------------------------------
+
+/** All known message type strings */
+export type MessageType =
+  // Filesystem
+  | "fs_list"
+  | "fs_list_response"
+  | "fs_read"
+  | "fs_read_response"
+  | "fs_write"
+  | "fs_write_response"
+  | "fs_create"
+  | "fs_create_response"
+  | "fs_delete"
+  | "fs_delete_response"
+  | "fs_search"
+  | "fs_search_response"
+  | "fs_replace"
+  | "fs_replace_response"
+  | "fs_changed"
+  // Git
+  | "git_status"
+  | "git_status_response"
+  | "git_branches"
+  | "git_branches_response"
+  | "git_branch_create"
+  | "git_branch_create_response"
+  | "git_checkout"
+  | "git_checkout_response"
+  | "git_stage"
+  | "git_stage_response"
+  | "git_unstage"
+  | "git_unstage_response"
+  | "git_commit"
+  | "git_commit_response"
+  | "git_push"
+  | "git_push_response"
+  | "git_pull"
+  | "git_pull_response"
+  | "git_file_base"
+  | "git_file_base_response"
+  | "git_discard"
+  | "git_discard_response"
+  | "git_diff"
+  | "git_diff_response"
+  // Commands
+  | "command_exec"
+  | "command_output"
+  | "command_exit"
+  | "command_cancel"
+  // Terminal
+  | "terminal_create"
+  | "terminal_create_response"
+  | "terminal_stdin"
+  | "terminal_stdout"
+  | "terminal_resize"
+  | "terminal_kill"
+  | "terminal_exit"
+  // Agent / Claude
+  | "agent_sessions_list"
+  | "agent_sessions_list_response"
+  | "agent_session_new"
+  | "agent_session_new_response"
+  | "agent_message"
+  | "agent_message_response"
+  | "agent_event"
+  | "agent_cancel"
+  | "agent_prompt_response"
+  // Discovery
+  | "daemon_register"
+  | "project_added"
+  | "project_removed"
+  | "machines_list"
+  | "machines_list_response"
+  | "projects_list"
+  | "projects_list_response"
+  | "project_create"
+  | "project_create_response"
+  | "project_delete"
+  | "project_delete_response"
+  // Credentials (git push/pull)
+  | "credential_prompt"
+  | "credential_response"
+  // OpenCode SSE
+  | "sse_event"
+  // OpenCode permission
+  | "permission_reply"
+  | "permission_reply_response"
+  // Generic
+  | "error";
+
+// ---------------------------------------------------------------------------
+// Error format (shared across all error responses)
+// ---------------------------------------------------------------------------
+
+export interface MessageError {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Filesystem types
+// ---------------------------------------------------------------------------
+
+export interface FsNode {
+  name: string;
+  path: string; // Relative to project
+  type: "file" | "dir";
+  size?: number; // Only for files
+  mtime?: string; // ISO 8601
+  children?: FsNode[]; // Only if expanded
+  expanded?: boolean;
+}
+
+export interface FsChange {
+  kind: "create" | "modify" | "delete";
+  path: string;
+}
+
+// -- fs_list --
+
+export interface FsListRequest {
+  type: "fs_list";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    path: string; // Relative path, '' for root
+    depth?: number; // Default 1
+  };
+}
+
+export interface FsListResponse {
+  type: "fs_list_response";
+  requestId: string;
+  sessionId: string;
+  payload?: {
+    path: string;
+    children: FsNode[];
+    seq: number;
+  };
+  error?: MessageError;
+}
+
+// -- fs_read --
+
+export interface FsReadRequest {
+  type: "fs_read";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    path: string;
+  };
+}
+
+export interface FsReadResponse {
+  type: "fs_read_response";
+  requestId: string;
+  payload?: {
+    path: string;
+    content: string;
+    encoding: string;
+    size: number;
+    mtime: string;
+  };
+  error?: MessageError;
+}
+
+// -- fs_write --
+
+export interface FsWriteRequest {
+  type: "fs_write";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    path: string;
+    content: string;
+    createDirs?: boolean; // Default true
+  };
+}
+
+export interface FsWriteResponse {
+  type: "fs_write_response";
+  requestId: string;
+  payload?: {
+    path: string;
+    size: number;
+    mtime: string;
+  };
+  error?: MessageError;
+}
+
+// -- fs_create --
+
+export interface FsCreateRequest {
+  type: "fs_create";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    path: string;
+    itemType: "file" | "directory";
+    createDirs?: boolean; // Default true
+  };
+}
+
+export interface FsCreateResponse {
+  type: "fs_create_response";
+  requestId: string;
+  payload?: {
+    path: string;
+    itemType: "file" | "directory";
+  };
+  error?: MessageError;
+}
+
+// -- fs_delete --
+
+export interface FsDeleteRequest {
+  type: "fs_delete";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    path: string;
+  };
+}
+
+export interface FsDeleteResponse {
+  type: "fs_delete_response";
+  requestId: string;
+  payload?: {
+    path: string;
+  };
+  error?: MessageError;
+}
+
+// -- fs_search --
+
+export interface FsSearchMatch {
+  line: number;
+  content: string;
+  column?: number;
+}
+
+export interface FsSearchFileResult {
+  path: string;
+  matches: FsSearchMatch[];
+}
+
+export interface FsSearchRequest {
+  type: "fs_search";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    query: string;
+    glob?: string; // Optional file pattern filter
+    caseSensitive?: boolean; // Default false
+    regex?: boolean; // Default false
+  };
+}
+
+export interface FsSearchResponse {
+  type: "fs_search_response";
+  requestId: string;
+  payload?: {
+    query: string;
+    totalMatches: number;
+    truncated: boolean;
+    files: FsSearchFileResult[];
+  };
+  error?: MessageError;
+}
+
+// -- fs_replace --
+
+export interface FsReplaceFileResult {
+  path: string;
+  replacements: number;
+}
+
+export interface FsReplaceRequest {
+  type: "fs_replace";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    find: string;
+    replace: string;
+    glob?: string; // Optional file pattern filter
+    caseSensitive?: boolean; // Default false
+    regex?: boolean; // Default false
+  };
+}
+
+export interface FsReplaceResponse {
+  type: "fs_replace_response";
+  requestId: string;
+  payload?: {
+    totalReplacements: number;
+    filesModified: FsReplaceFileResult[];
+  };
+  error?: MessageError;
+}
+
+// -- fs_changed (push event, no requestId) --
+
+export interface FsChangedEvent {
+  type: "fs_changed";
+  sessionId: string;
+  payload: {
+    seq: number;
+    changes: FsChange[];
+    changesTruncated?: boolean;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Git types
+// ---------------------------------------------------------------------------
+
+export interface GitFileStatus {
+  path: string;
+  status: string;
+}
+
+export interface GitBranch {
+  name: string;
+  remote: string | null;
+  ahead: number;
+  behind: number;
+}
+
+// -- git_status --
+
+export interface GitStatusRequest {
+  type: "git_status";
+  requestId: string;
+  sessionId: string;
+  payload: Record<string, never>;
+}
+
+export interface GitStatusResponse {
+  type: "git_status_response";
+  requestId: string;
+  payload?: {
+    branch: string;
+    clean: boolean;
+    staged: GitFileStatus[];
+    unstaged: GitFileStatus[];
+    conflicts: GitFileStatus[];
+  };
+  error?: MessageError;
+}
+
+// -- git_branches --
+
+export interface GitBranchesRequest {
+  type: "git_branches";
+  requestId: string;
+  sessionId: string;
+  payload: Record<string, never>;
+}
+
+export interface GitBranchesResponse {
+  type: "git_branches_response";
+  requestId: string;
+  payload?: {
+    current: string;
+    branches: GitBranch[];
+  };
+  error?: MessageError;
+}
+
+// -- git_branch_create --
+
+export interface GitBranchCreateRequest {
+  type: "git_branch_create";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    name: string;
+    startPoint?: string; // Default HEAD
+  };
+}
+
+export interface GitBranchCreateResponse {
+  type: "git_branch_create_response";
+  requestId: string;
+  payload?: {
+    name: string;
+    created: boolean;
+  };
+  error?: MessageError;
+}
+
+// -- git_checkout --
+
+export interface GitCheckoutRequest {
+  type: "git_checkout";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    ref: string;
+  };
+}
+
+export interface GitCheckoutResponse {
+  type: "git_checkout_response";
+  requestId: string;
+  payload?: {
+    ref: string;
+    switched: boolean;
+  };
+  error?: MessageError;
+}
+
+// -- git_stage --
+
+export interface GitStageRequest {
+  type: "git_stage";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    paths: string[];
+  };
+}
+
+export interface GitStageResponse {
+  type: "git_stage_response";
+  requestId: string;
+  payload?: {
+    staged: string[];
+  };
+  error?: MessageError;
+}
+
+// -- git_unstage --
+
+export interface GitUnstageRequest {
+  type: "git_unstage";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    paths: string[];
+  };
+}
+
+export interface GitUnstageResponse {
+  type: "git_unstage_response";
+  requestId: string;
+  payload?: {
+    unstaged: string[];
+  };
+  error?: MessageError;
+}
+
+// -- git_commit --
+
+export interface GitCommitRequest {
+  type: "git_commit";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    message: string;
+  };
+}
+
+export interface GitCommitResponse {
+  type: "git_commit_response";
+  requestId: string;
+  payload?: {
+    sha: string;
+    message: string;
+  };
+  error?: MessageError;
+}
+
+// -- git_push --
+
+export interface GitPushRequest {
+  type: "git_push";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    remote?: string; // Default origin
+    branch?: string; // Default current branch
+    force?: boolean; // Default false
+  };
+}
+
+export interface GitPushResponse {
+  type: "git_push_response";
+  requestId: string;
+  payload?: {
+    remote: string;
+    branch: string;
+    pushed: boolean;
+  };
+  error?: MessageError;
+}
+
+// -- git_pull --
+
+export interface GitPullRequest {
+  type: "git_pull";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    remote?: string; // Default origin
+    branch?: string; // Default current branch
+  };
+}
+
+export interface GitPullResponse {
+  type: "git_pull_response";
+  requestId: string;
+  payload?: {
+    remote: string;
+    branch: string;
+    pulled: boolean;
+    conflicts?: string[];
+  };
+  error?: MessageError;
+}
+
+// -- git_file_base --
+
+export interface GitFileBaseRequest {
+  type: "git_file_base";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    path: string;
+    ref?: string; // Default HEAD
+  };
+}
+
+export interface GitFileBaseResponse {
+  type: "git_file_base_response";
+  requestId: string;
+  payload?: {
+    path: string;
+    ref: string;
+    content: string | null; // null if file is new
+  };
+  error?: MessageError;
+}
+
+// -- git_discard --
+
+export interface GitDiscardRequest {
+  type: "git_discard";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    paths?: string[]; // Specific files to discard; omit or empty for all
+    all?: boolean; // Discard all changes (tracked + untracked)
+  };
+}
+
+export interface GitDiscardResponse {
+  type: "git_discard_response";
+  requestId: string;
+  payload?: {
+    discarded: number; // Count of discarded files
+  };
+  error?: MessageError;
+}
+
+// -- git_diff --
+
+export interface GitDiffRequest {
+  type: "git_diff";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    path?: string; // Specific file; omit for all
+    staged?: boolean; // Default false
+  };
+}
+
+export interface GitDiffFileResult {
+  path: string;
+  status: string; // added, modified, deleted
+  additions: number;
+  deletions: number;
+  diff: string;
+}
+
+export interface GitDiffResponse {
+  type: "git_diff_response";
+  requestId: string;
+  payload?: {
+    files: GitDiffFileResult[];
+  };
+  error?: MessageError;
+}
+
+// -- credential_prompt (host → client, during git push/pull) --
+
+export type CredentialPromptType = "password" | "passphrase" | "username" | "pin";
+
+export interface CredentialPromptEvent {
+  type: "credential_prompt";
+  requestId: string;
+  payload: {
+    promptType: CredentialPromptType;
+    prompt: string;
+  };
+}
+
+// -- credential_response (client → host) --
+
+export interface CredentialResponseRequest {
+  type: "credential_response";
+  requestId: string;
+  payload: {
+    value: string;
+    cancelled: boolean;
+  };
+}
+
+// -- sse_event (OpenCode SSE events forwarded through tunnel) --
+
+export interface SseEventMessage {
+  type: "sse_event";
+  payload: {
+    event: string;
+    data: string;
+    sessionId?: string;
+  };
+}
+
+// -- permission_reply (forward permission reply to OpenCode) --
+
+export type PermissionReplyValue = "once" | "always" | "reject";
+
+export interface PermissionReplyRequest {
+  type: "permission_reply";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    permissionId: string;
+    reply: PermissionReplyValue;
+  };
+}
+
+export interface PermissionReplyResponse {
+  type: "permission_reply_response";
+  requestId: string;
+  payload?: {
+    status: number;
+    body?: unknown;
+  };
+  error?: MessageError;
+}
+
+// ---------------------------------------------------------------------------
+// Command types
+// ---------------------------------------------------------------------------
+
+// -- command_exec --
+
+export interface CommandExecRequest {
+  type: "command_exec";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    command: string;
+  };
+}
+
+export interface CommandOutputEvent {
+  type: "command_output";
+  requestId: string;
+  payload: {
+    stdoutChunk?: string;
+    stderrChunk?: string;
+  };
+}
+
+export interface CommandExitEvent {
+  type: "command_exit";
+  requestId: string;
+  payload: {
+    exitCode: number | null; // null if cancelled/killed
+    signal?: string;
+    durationMs: number;
+  };
+}
+
+// -- command_cancel --
+
+export interface CommandCancelRequest {
+  type: "command_cancel";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    requestId: string; // ID of command to cancel
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Terminal types
+// ---------------------------------------------------------------------------
+
+// -- terminal_create --
+
+export interface TerminalCreateRequest {
+  type: "terminal_create";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    cols?: number;
+    rows?: number;
+  };
+}
+
+export interface TerminalCreateResponse {
+  type: "terminal_create_response";
+  requestId: string;
+  payload: {
+    terminalId: string;
+  };
+  error?: MessageError;
+}
+
+// -- terminal_stdin --
+
+export interface TerminalStdinRequest {
+  type: "terminal_stdin";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    terminalId: string;
+    data: string;
+  };
+}
+
+// -- terminal_stdout --
+
+export interface TerminalStdoutEvent {
+  type: "terminal_stdout";
+  payload: {
+    terminalId: string;
+    data: string;
+  };
+}
+
+// -- terminal_resize --
+
+export interface TerminalResizeRequest {
+  type: "terminal_resize";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    terminalId: string;
+    cols: number;
+    rows: number;
+  };
+}
+
+// -- terminal_kill --
+
+export interface TerminalKillRequest {
+  type: "terminal_kill";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    terminalId: string;
+  };
+}
+
+// -- terminal_exit --
+
+export interface TerminalExitEvent {
+  type: "terminal_exit";
+  payload: {
+    terminalId: string;
+    exitCode: number;
+    signal?: number;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Agent / Claude types
+// ---------------------------------------------------------------------------
+
+export type AgentEvent =
+  | { type: "init"; sessionId: string; tools: string[]; model: string }
+  | { type: "thinking"; content: string }
+  | { type: "text"; content: string }
+  | { type: "tool_use"; tool: string; input: Record<string, unknown> }
+  | { type: "tool_complete"; toolUseId: string }
+  | { type: "file_edit"; path: string; diff?: string }
+  | { type: "file_create"; path: string }
+  | { type: "file_delete"; path: string }
+  | {
+      type: "prompt";
+      questions: Array<{
+        question: string;
+        header: string;
+        options: Array<{ label: string; description: string }>;
+        multiSelect: boolean;
+      }>;
+    }
+  | {
+      type: "done";
+      usage?: { input_tokens: number; output_tokens: number };
+      cancelled?: boolean;
+      error?: string;
+    };
+
+export interface AgentSessionInfo {
+  agentSessionId: string;
+  lastUsedAt: string;
+  title: string | null;
+}
+
+// -- agent_sessions_list --
+
+export interface AgentSessionsListRequest {
+  type: "agent_sessions_list";
+  requestId: string;
+  sessionId: string;
+  payload: Record<string, never>;
+}
+
+export interface AgentSessionsListResponse {
+  type: "agent_sessions_list_response";
+  requestId: string;
+  payload?: {
+    sessions: AgentSessionInfo[];
+  };
+  error?: MessageError;
+}
+
+// -- agent_session_new --
+
+export interface AgentSessionNewRequest {
+  type: "agent_session_new";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    content: string;
+  };
+}
+
+export interface AgentSessionNewResponse {
+  type: "agent_session_new_response";
+  requestId: string;
+  payload?: {
+    agentSessionId: string;
+  };
+  error?: MessageError;
+}
+
+// -- agent_message --
+
+export interface AgentMessageRequest {
+  type: "agent_message";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    agentSessionId: string;
+    content: string;
+  };
+}
+
+export interface AgentMessageResponse {
+  type: "agent_message_response";
+  requestId: string;
+  payload?: {
+    queued?: boolean;
+    started?: boolean;
+  };
+  error?: MessageError;
+}
+
+// -- agent_event (push, multiple during execution) --
+
+export interface AgentEventMessage {
+  type: "agent_event";
+  sessionId: string;
+  payload: {
+    agentSessionId: string;
+    event: AgentEvent;
+  };
+}
+
+// -- agent_cancel --
+
+export interface AgentCancelRequest {
+  type: "agent_cancel";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    agentSessionId: string;
+  };
+}
+
+// -- agent_prompt_response --
+
+export interface AgentPromptResponseRequest {
+  type: "agent_prompt_response";
+  requestId: string;
+  sessionId: string;
+  payload: {
+    agentSessionId: string;
+    response: string;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Discovery types
+// ---------------------------------------------------------------------------
+
+export interface MachineMetadata {
+  os: "darwin" | "linux" | "win32";
+  osVersion: string;
+  hostname: string;
+  username: string;
+  label: string | null;
+}
+
+export interface RegisterProject {
+  projectId: string;
+  name: string;
+  path?: string; // Absolute path (for Host reference only)
+}
+
+// -- daemon_register (daemon → relay, no requestId) --
+
+export interface DaemonRegisterMessage {
+  type: "daemon_register";
+  payload: {
+    machineKey: string;
+    token: string;
+    machine: MachineMetadata;
+    projects: RegisterProject[];
+  };
+}
+
+// -- project_added (daemon → relay, no requestId) --
+
+export interface ProjectAddedMessage {
+  type: "project_added";
+  payload: {
+    projectId: string;
+    name: string;
+    path: string;
+  };
+}
+
+// -- project_removed (daemon → relay, no requestId) --
+
+export interface ProjectRemovedMessage {
+  type: "project_removed";
+  payload: {
+    projectId: string;
+  };
+}
+
+// -- machines_list --
+
+export interface MachinesListRequest {
+  type: "machines_list";
+  requestId: string;
+  payload: Record<string, never>;
+}
+
+export interface MachineInfo {
+  machineKey: string;
+  label: string;
+  os: string;
+  osVersion: string;
+  username: string;
+  online: boolean;
+  lastSeen: string;
+  projectCount: number;
+}
+
+export interface MachinesListResponse {
+  type: "machines_list_response";
+  requestId: string;
+  payload?: {
+    machines: MachineInfo[];
+  };
+  error?: MessageError;
+}
+
+// -- projects_list --
+
+export interface ProjectsListRequest {
+  type: "projects_list";
+  requestId: string;
+  payload: {
+    machineKey: string;
+  };
+}
+
+export interface ProjectInfo {
+  projectId: string;
+  name: string;
+  path: string;
+  hasActiveSession: boolean;
+  lastAccessed: string;
+}
+
+export interface ProjectsListResponse {
+  type: "projects_list_response";
+  requestId: string;
+  payload?: {
+    projects: ProjectInfo[];
+  };
+  error?: MessageError;
+}
+
+// -- project_create (client → daemon, creates a new project) --
+
+export interface ProjectCreateRequest {
+  type: "project_create";
+  requestId: string;
+  payload: {
+    path: string;
+  };
+}
+
+export interface ProjectCreateResponse {
+  type: "project_create_response";
+  requestId: string;
+  payload?: {
+    project: {
+      projectId: string;
+      name: string;
+      path: string;
+    };
+  };
+  error?: MessageError;
+}
+
+// -- project_delete (client → daemon, deletes a project) --
+
+export interface ProjectDeleteRequest {
+  type: "project_delete";
+  requestId: string;
+  payload: {
+    projectId: string;
+  };
+}
+
+export interface ProjectDeleteResponse {
+  type: "project_delete_response";
+  requestId: string;
+  payload?: {
+    success: boolean;
+  };
+  error?: MessageError;
+}
+
+// ---------------------------------------------------------------------------
+// Generic error response
+// ---------------------------------------------------------------------------
+
+export interface ErrorResponse {
+  type: "error";
+  requestId: string;
+  error: MessageError;
+}
+
+// ---------------------------------------------------------------------------
+// Union of all messages
+// ---------------------------------------------------------------------------
+
+export type RequestMessage =
+  | FsListRequest
+  | FsReadRequest
+  | FsWriteRequest
+  | FsCreateRequest
+  | FsDeleteRequest
+  | FsSearchRequest
+  | FsReplaceRequest
+  | GitStatusRequest
+  | GitBranchesRequest
+  | GitBranchCreateRequest
+  | GitCheckoutRequest
+  | GitStageRequest
+  | GitUnstageRequest
+  | GitCommitRequest
+  | GitPushRequest
+  | GitPullRequest
+  | GitFileBaseRequest
+  | GitDiscardRequest
+  | GitDiffRequest
+  | CommandExecRequest
+  | CommandCancelRequest
+  | TerminalCreateRequest
+  | TerminalStdinRequest
+  | TerminalResizeRequest
+  | TerminalKillRequest
+  | AgentSessionsListRequest
+  | AgentSessionNewRequest
+  | AgentMessageRequest
+  | AgentCancelRequest
+  | AgentPromptResponseRequest
+  | MachinesListRequest
+  | ProjectsListRequest
+  | ProjectCreateRequest
+  | ProjectDeleteRequest
+  | CredentialResponseRequest
+  | PermissionReplyRequest;
+
+export type ResponseMessage =
+  | FsListResponse
+  | FsReadResponse
+  | FsWriteResponse
+  | FsCreateResponse
+  | FsDeleteResponse
+  | FsSearchResponse
+  | FsReplaceResponse
+  | GitStatusResponse
+  | GitBranchesResponse
+  | GitBranchCreateResponse
+  | GitCheckoutResponse
+  | GitStageResponse
+  | GitUnstageResponse
+  | GitCommitResponse
+  | GitPushResponse
+  | GitPullResponse
+  | GitFileBaseResponse
+  | GitDiscardResponse
+  | GitDiffResponse
+  | AgentSessionsListResponse
+  | AgentSessionNewResponse
+  | AgentMessageResponse
+  | MachinesListResponse
+  | ProjectsListResponse
+  | ProjectCreateResponse
+  | ProjectDeleteResponse
+  | TerminalCreateResponse
+  | PermissionReplyResponse
+  | ErrorResponse;
+
+export type EventMessage =
+  | FsChangedEvent
+  | CommandOutputEvent
+  | TerminalStdoutEvent
+  | TerminalExitEvent
+  | CommandExitEvent
+  | AgentEventMessage
+  | CredentialPromptEvent
+  | SseEventMessage;
+
+export type Message =
+  | RequestMessage
+  | ResponseMessage
+  | EventMessage
+  | DaemonRegisterMessage
+  | ProjectAddedMessage
+  | ProjectRemovedMessage;
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function hasType(value: unknown): value is { type: string } {
+  return isObject(value) && typeof value.type === "string";
+}
+
+function hasRequestId(value: unknown): value is { requestId: string } {
+  return isObject(value) && typeof value.requestId === "string";
+}
+
+function hasSessionId(value: unknown): value is { sessionId: string } {
+  return isObject(value) && typeof value.sessionId === "string";
+}
+
+function hasPayload(value: unknown): value is { payload: Record<string, unknown> } {
+  return isObject(value) && isObject((value as Record<string, unknown>).payload);
+}
+
+/** Validate that value looks like an fs_list request */
+export function isFsListRequest(value: unknown): value is FsListRequest {
+  return (
+    hasType(value) &&
+    value.type === "fs_list" &&
+    hasRequestId(value) &&
+    hasSessionId(value) &&
+    hasPayload(value) &&
+    typeof (value as FsListRequest).payload.path === "string"
+  );
+}
+
+/** Validate that value looks like an fs_read request */
+export function isFsReadRequest(value: unknown): value is FsReadRequest {
+  return (
+    hasType(value) &&
+    value.type === "fs_read" &&
+    hasRequestId(value) &&
+    hasSessionId(value) &&
+    hasPayload(value) &&
+    typeof (value as FsReadRequest).payload.path === "string"
+  );
+}
+
+/** Validate that value looks like a git_status request */
+export function isGitStatusRequest(value: unknown): value is GitStatusRequest {
+  return (
+    hasType(value) && value.type === "git_status" && hasRequestId(value) && hasSessionId(value)
+  );
+}
+
+/** Validate that value looks like an agent_message request */
+export function isAgentMessageRequest(value: unknown): value is AgentMessageRequest {
+  return (
+    hasType(value) &&
+    value.type === "agent_message" &&
+    hasRequestId(value) &&
+    hasSessionId(value) &&
+    hasPayload(value) &&
+    typeof (value as AgentMessageRequest).payload.agentSessionId === "string" &&
+    typeof (value as AgentMessageRequest).payload.content === "string"
+  );
+}
+
+/** Validate that value looks like an error response */
+export function isErrorResponse(value: unknown): value is ErrorResponse {
+  if (!hasType(value) || value.type !== "error" || !hasRequestId(value)) {
+    return false;
+  }
+  const v = value as Record<string, unknown>;
+  return isObject(v.error) && typeof (v.error as Record<string, unknown>).code === "string";
+}
+
+/** Validate that value is a valid message (has at least a type field) */
+export function isMessage(value: unknown): value is Message {
+  return hasType(value);
+}
+
+/** Validate that value is a request message (has type, requestId, and usually sessionId) */
+export function isRequestMessage(value: unknown): value is RequestMessage {
+  return hasType(value) && hasRequestId(value);
+}
+
+/** Validate that value is an AgentEvent with type 'init' */
+export function isAgentInitEvent(value: unknown): value is Extract<AgentEvent, { type: "init" }> {
+  return (
+    isObject(value) &&
+    (value as Record<string, unknown>).type === "init" &&
+    typeof (value as Record<string, unknown>).sessionId === "string" &&
+    Array.isArray((value as Record<string, unknown>).tools) &&
+    typeof (value as Record<string, unknown>).model === "string"
+  );
+}
+
+/** Validate that value is an AgentEvent with type 'done' */
+export function isAgentDoneEvent(value: unknown): value is Extract<AgentEvent, { type: "done" }> {
+  if (!isObject(value) || (value as Record<string, unknown>).type !== "done") {
+    return false;
+  }
+  const v = value as Record<string, unknown>;
+  // usage is optional but must be correct shape if present
+  if (v.usage !== undefined) {
+    if (
+      !isObject(v.usage) ||
+      typeof (v.usage as Record<string, unknown>).input_tokens !== "number" ||
+      typeof (v.usage as Record<string, unknown>).output_tokens !== "number"
+    ) {
+      return false;
+    }
+  }
+  // error is optional but must be string if present
+  if (v.error !== undefined && typeof v.error !== "string") {
+    return false;
+  }
+  // cancelled is optional but must be boolean if present
+  if (v.cancelled !== undefined && typeof v.cancelled !== "boolean") {
+    return false;
+  }
+  return true;
+}
+
+/** Validate that value is any valid AgentEvent (has a recognized type) */
+export function isAgentEvent(value: unknown): value is AgentEvent {
+  if (!isObject(value) || typeof (value as Record<string, unknown>).type !== "string") {
+    return false;
+  }
+  const validTypes = [
+    "init",
+    "thinking",
+    "text",
+    "tool_use",
+    "tool_complete",
+    "file_edit",
+    "file_create",
+    "file_delete",
+    "prompt",
+    "done",
+  ];
+  return validTypes.includes((value as Record<string, unknown>).type as string);
+}