@wrongstack/webui 0.257.2 → 0.264.0

package/dist/types.d.ts

@@ -0,0 +1,1208 @@
+import { Usage } from '@wrongstack/core';
+
+interface WSMessage {
+    type: string;
+    payload: unknown;
+}
+interface WSSessionStart {
+    type: 'session.start';
+    payload: {
+        sessionId: string;
+        model: string;
+        provider: string;
+        maxContext?: number | undefined;
+        projectName?: string | undefined;
+        cwd?: string | undefined;
+        mode?: string | undefined;
+        contextMode?: string | undefined;
+        inputCost?: number | undefined;
+        outputCost?: number | undefined;
+        cacheReadCost?: number | undefined;
+        reset?: boolean | undefined;
+        replayMessages?: Array<{
+            role: string | undefined;
+            content: unknown;
+        }>;
+        replayUsage?: Usage | undefined;
+        /** True when no provider+model is configured yet — show the setup screen. */
+        needsSetup?: boolean | undefined;
+    };
+}
+interface WSSessionEnd {
+    type: 'session.end';
+    payload: {
+        sessionId: string;
+        usage: Usage;
+        totalCost: number;
+    };
+}
+interface WSUserMessage {
+    type: 'user_message';
+    payload: {
+        id: string;
+        content: string;
+        timestamp: number;
+        /** Base64-encoded clipboard image, if the user pasted one. */
+        imageBase64?: string;
+    };
+}
+interface WSTextDelta {
+    type: 'provider.text_delta';
+    payload: {
+        text: string;
+        messageId: string;
+    };
+}
+interface WSThinkingDelta {
+    type: 'provider.thinking_delta';
+    payload: {
+        text: string;
+    };
+}
+interface WSToolUseStart {
+    type: 'tool.started';
+    payload: {
+        id: string;
+        name: string;
+        input?: unknown | undefined;
+        messageId: string;
+    };
+}
+interface WSToolProgress {
+    type: 'tool.progress';
+    payload: {
+        name: string;
+        id: string;
+        event: {
+            type: 'log' | 'warning' | 'metric' | 'file_changed' | 'partial_output';
+            text?: string | undefined;
+            data?: Record<string, unknown>;
+        };
+    };
+}
+interface WSToolExecuted {
+    type: 'tool.executed';
+    payload: {
+        id: string;
+        name: string;
+        durationMs: number;
+        ok: boolean;
+        input?: unknown | undefined;
+        output?: string | undefined;
+    };
+}
+interface WSIterationStarted {
+    type: 'iteration.started';
+    payload: {
+        index: number;
+        maxIterations?: number | undefined;
+    };
+}
+interface WSIterationCompleted {
+    type: 'iteration.completed';
+    payload: {
+        index: number;
+        totalIterations: number;
+    };
+}
+interface WSProviderResponse {
+    type: 'provider.response';
+    payload: {
+        usage: Usage;
+        stopReason: string;
+        messageId: string;
+    };
+}
+interface WSRunResult {
+    type: 'run.result';
+    payload: {
+        status: 'done' | 'failed' | 'max_iterations' | 'aborted';
+        iterations: number;
+        finalText?: string | undefined;
+        error?: {
+            code: string;
+            message: string;
+            recoverable: boolean;
+        };
+    };
+}
+interface WSSessionStats {
+    type: 'session.stats';
+    payload: {
+        messages: number;
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cost: number;
+        duration: number;
+    };
+}
+interface WSError {
+    type: 'error';
+    payload: {
+        phase: string;
+        message: string;
+    };
+}
+interface WSToolConfirmNeeded {
+    type: 'tool.confirm_needed';
+    payload: {
+        id: string;
+        toolName: string;
+        input: unknown;
+        suggestedPattern: string;
+        resolve: (decision: 'yes' | 'no' | 'always' | 'deny') => void;
+    };
+}
+interface WSToolConfirmResult {
+    type: 'tool.confirm_result';
+    payload: {
+        id: string;
+        decision: 'yes' | 'no' | 'always' | 'deny';
+    };
+}
+interface WSModelSwitch {
+    type: 'model.switch';
+    payload: {
+        provider: string;
+        model: string;
+    };
+}
+type MemoryScope = 'project-agents' | 'project-memory' | 'user-memory';
+interface WSContextDebug {
+    type: 'context.debug';
+    payload: {
+        total: number;
+        mode?: string | undefined;
+        policy?: unknown | undefined;
+        systemPrompt: number;
+        tools: {
+            total: number;
+            count: number;
+            breakdown: Array<{
+                name: string;
+                tokens: number;
+            }>;
+        };
+        messages: {
+            total: number;
+            count: number;
+            breakdown: Array<{
+                index: number;
+                role: string;
+                tokens: number;
+                preview: string;
+            }>;
+        };
+    };
+}
+interface WSContextCompacted {
+    type: 'context.compacted';
+    payload: {
+        before: number;
+        after: number;
+        saved: number;
+        reductions: Array<{
+            phase: string;
+            saved: number;
+        }>;
+        repaired?: {
+            removedToolUses: string[];
+            removedToolResults: string[];
+            removedMessages: number;
+        };
+    };
+}
+interface WSContextRepaired {
+    type: 'context.repaired';
+    payload: {
+        removedToolUses: string[];
+        removedToolResults: string[];
+        removedMessages: number;
+        beforeMessages?: number | undefined;
+        afterMessages?: number | undefined;
+    };
+}
+interface WSContextModesList {
+    type: 'context.modes.list';
+    payload: {
+        activeId: string;
+        modes: Array<{
+            id: string;
+            name: string;
+            description: string;
+            isActive: boolean;
+            thresholds: {
+                warn: number;
+                soft: number;
+                hard: number;
+            };
+            preserveK: number;
+            eliseThreshold: number;
+        }>;
+    };
+}
+interface WSContextModeChanged {
+    type: 'context.mode.changed';
+    payload: {
+        id: string;
+        name: string;
+        policy: unknown;
+    };
+}
+interface WSToolsList {
+    type: 'tools.list';
+    payload: {
+        tools: Array<{
+            name: string;
+            description: string;
+            params: string[];
+        }>;
+    };
+}
+interface WSMemoryList {
+    type: 'memory.list';
+    payload: {
+        text: string;
+        error?: string | undefined;
+    };
+}
+interface WSSkillsList {
+    type: 'skills.list';
+    payload: {
+        enabled: boolean;
+        error?: string | undefined;
+        skills: Array<{
+            name: string;
+            description: string;
+            version: string;
+            source: string;
+            path: string;
+            trigger: string;
+            scope: string[];
+        }>;
+    };
+}
+interface WSDiagGet {
+    type: 'diag.get';
+    payload: {
+        provider: string;
+        model: string;
+        cwd: string;
+        sessionId: string;
+        tools: {
+            count: number;
+            names: string[];
+        };
+        features: {
+            memory: boolean;
+            skills: boolean;
+            modelsRegistry: boolean;
+        };
+        mode: string;
+        usage: {
+            input: number;
+            output: number;
+            cacheRead?: number | undefined;
+        };
+        messages: number;
+        todos: number;
+    };
+}
+interface WSStatsGet {
+    type: 'stats.get';
+    payload: {
+        sessionId: string;
+        provider: string;
+        model: string;
+        usage: {
+            input: number;
+            output: number;
+            cacheRead?: number | undefined;
+            cacheWrite?: number | undefined;
+        };
+        cache: {
+            readTokens: number;
+            writeTokens: number;
+            hitRatio: number;
+        } | null;
+        cost: number;
+        messages: number;
+        readFiles: number;
+        tools: number;
+        elapsedMs: number;
+    };
+}
+interface WSSessionsList {
+    type: 'sessions.list';
+    payload: {
+        sessions: Array<{
+            id: string;
+            title: string;
+            startedAt: string;
+            model: string;
+            provider: string;
+            tokenTotal: number;
+            isCurrent: boolean;
+        }>;
+        error?: string | undefined;
+    };
+}
+interface WSProviderCatalog {
+    type: 'provider.catalog';
+    payload: {
+        providers: Array<{
+            id: string;
+            name: string;
+            family: string;
+            apiBase?: string | undefined;
+            envVars: string[];
+            modelCount: number;
+            hasApiKey: boolean;
+        }>;
+    };
+}
+interface WSProviderModels {
+    type: 'provider.models';
+    payload: {
+        provider: string;
+        models: Array<{
+            id: string;
+            name: string;
+            releaseDate?: string | undefined;
+            contextWindow?: number | undefined;
+            inputCost?: number | undefined;
+            outputCost?: number | undefined;
+            capabilities: string[];
+        }>;
+    };
+}
+interface WSSavedProviders {
+    type: 'providers.saved';
+    payload: {
+        providers: Array<{
+            id: string;
+            family?: string | undefined;
+            baseUrl?: string | undefined;
+            /** Saved model allowlist, in the order the user pinned them. */
+            models?: string[] | undefined;
+            /** First entry of `models`, surfaced for the panel's "Using" line. */
+            pickedModelId?: string | undefined;
+            apiKeys: Array<{
+                label: string;
+                maskedKey: string;
+                isActive: boolean;
+                createdAt: string;
+            }>;
+        }>;
+    };
+}
+/**
+ * Health-probe result for a single provider, broadcast in reply to a
+ * `provider.probe` client message. Mirrors the `ProbeResult` shape
+ * from `@wrongstack/runtime/probe`, plus the `providerId` so panels
+ * can route the reply to the right card.
+ */
+interface WSProviderProbe {
+    type: 'provider.probe';
+    payload: {
+        providerId: string;
+        ok: boolean;
+        status: string;
+        httpStatus?: number | undefined;
+        elapsedMs?: number | undefined;
+        modelCount?: number | undefined;
+        modelIds?: string[] | undefined;
+        detail?: string | undefined;
+    };
+}
+interface WSKeyOperationResult {
+    type: 'key.operation_result';
+    payload: {
+        success: boolean;
+        message: string;
+    };
+}
+interface WSFilesList {
+    type: 'files.list';
+    payload: {
+        files: string[];
+    };
+}
+interface WSTodosUpdated {
+    type: 'todos.updated';
+    payload: {
+        todos: Array<{
+            id: string;
+            content: string;
+            status: 'pending' | 'in_progress' | 'completed';
+            activeForm?: string | undefined;
+        }>;
+    };
+}
+interface WSModesList {
+    type: 'modes.list';
+    payload: {
+        modes: Array<{
+            id: string;
+            name: string;
+            description: string;
+            isActive: boolean;
+        }>;
+        activeId: string;
+    };
+}
+/** AutoPhase live state broadcast (see server/autophase-ws-handler.ts). */
+interface WSAutoPhaseState {
+    type: 'autophase.state';
+    payload: Record<string, unknown>;
+}
+/** One worktree lane in the swim-lane / DAG view. */
+interface WorktreeHandleView {
+    handleId: string;
+    ownerId: string;
+    ownerLabel: string;
+    branch: string;
+    baseBranch: string;
+    status: 'allocating' | 'active' | 'committing' | 'merging' | 'merged' | 'needs-review' | 'failed';
+    insertions: number;
+    deletions: number;
+    files: number;
+    conflictFiles?: string[] | undefined;
+    allocatedAt: number;
+    lastEventAt: number;
+    recentActivity: Array<{
+        kind: string;
+        text: string;
+        at: number;
+    }>;
+}
+/** Full worktree snapshot (broadcast on a timer, see worktree-ws-handler.ts). */
+interface WSWorktreeState {
+    type: 'worktree.state';
+    payload: {
+        worktrees: WorktreeHandleView[];
+        baseBranch: string;
+    };
+}
+/** Incremental worktree lifecycle event — drives the flowing activity strip. */
+interface WSWorktreeEvent {
+    type: 'worktree.event';
+    payload: {
+        kind: string;
+        handleId: string;
+        text: string;
+        at: number;
+    };
+}
+type WSClientMessage = WSUserMessage | WSToolConfirmResult | {
+    type: 'autophase.start';
+    payload: {
+        title: string;
+        phases?: unknown[] | undefined;
+        autonomous?: boolean | undefined;
+    };
+} | {
+    type: 'autophase.pause';
+    payload: Record<string, never>;
+} | {
+    type: 'autophase.resume';
+    payload: Record<string, never>;
+} | {
+    type: 'autophase.stop';
+    payload: Record<string, never>;
+} | {
+    type: 'autophase.toggleAutonomous';
+    payload: {
+        autonomous?: boolean | undefined;
+    };
+} | {
+    type: 'autophase.selectPhase';
+    payload: {
+        phaseId: string;
+    };
+} | {
+    type: 'autophase.taskStatus';
+    payload: {
+        taskId: string;
+        status: string;
+    };
+} | {
+    type: 'abort';
+    payload: Record<string, never>;
+} | {
+    type: 'session.resume';
+    payload: {
+        id: string;
+    };
+} | {
+    type: 'session.new';
+} | {
+    type: 'session.checkpoints';
+} | {
+    type: 'session.rewind';
+    payload: {
+        checkpointIndex: number;
+    };
+} | {
+    type: 'context.clear';
+} | {
+    type: 'context.compact';
+    payload: {
+        aggressive: boolean;
+    };
+} | {
+    type: 'context.repair';
+} | {
+    type: 'context.debug';
+} | {
+    type: 'context.modes.list';
+} | {
+    type: 'context.mode.switch';
+    payload: {
+        id: string;
+    };
+} | {
+    type: 'context.mode.create';
+    payload: {
+        id: string;
+        name: string;
+        description: string;
+        thresholds: {
+            warn: number;
+            soft: number;
+            hard: number;
+        };
+        preserveK: number;
+        eliseThreshold: number;
+    };
+} | {
+    type: 'context.mode.update';
+    payload: {
+        id: string;
+        name?: string | undefined;
+        description?: string | undefined;
+        thresholds?: {
+            warn?: number | undefined;
+            soft?: number | undefined;
+            hard?: number | undefined;
+        } | undefined;
+        preserveK?: number | undefined;
+        eliseThreshold?: number | undefined;
+    };
+} | {
+    type: 'context.mode.delete';
+    payload: {
+        id: string;
+    };
+} | WSModelSwitch | {
+    type: 'providers.list';
+} | {
+    type: 'provider.models';
+    payload: {
+        providerId: string;
+    };
+} | {
+    type: 'providers.saved';
+} | {
+    type: 'key.add';
+    payload: {
+        providerId: string;
+        label: string;
+        apiKey: string;
+    };
+} | {
+    type: 'key.update';
+    payload: {
+        providerId: string;
+        label: string;
+        apiKey: string;
+    };
+} | {
+    type: 'key.delete';
+    payload: {
+        providerId: string;
+        label: string;
+    };
+} | {
+    type: 'key.set_active';
+    payload: {
+        providerId: string;
+        label: string;
+    };
+} | {
+    type: 'provider.add';
+    payload: {
+        id: string;
+        family: string;
+        baseUrl?: string | undefined;
+        apiKey?: string | undefined;
+    };
+} | {
+    type: 'provider.remove';
+    payload: {
+        providerId: string;
+    };
+} | {
+    type: 'provider.clear_models';
+    payload: {
+        providerId: string;
+    };
+} | {
+    type: 'provider.undo_clear';
+    payload: {
+        providerId: string;
+        previousModels: string[];
+    };
+} | {
+    type: 'provider.update';
+    payload: {
+        id: string;
+        family?: string | undefined;
+        baseUrl?: string | undefined;
+        envVars?: string[] | undefined;
+        models?: string[] | undefined;
+    };
+} | {
+    type: 'provider.probe';
+    payload: {
+        providerId: string;
+        timeoutMs?: number | undefined;
+    };
+} | {
+    type: 'tools.list';
+} | {
+    type: 'memory.list';
+} | {
+    type: 'memory.remember';
+    payload: {
+        text: string;
+        scope?: MemoryScope | undefined;
+    };
+} | {
+    type: 'memory.forget';
+    payload: {
+        text: string;
+        scope?: MemoryScope | undefined;
+    };
+} | {
+    type: 'skills.list';
+} | {
+    type: 'diag.get';
+} | {
+    type: 'stats.get';
+} | {
+    type: 'session.save';
+} | {
+    type: 'sessions.list';
+    payload: {
+        limit: number;
+    };
+} | {
+    type: 'session.delete';
+    payload: {
+        id: string;
+    };
+} | {
+    type: 'modes.list';
+} | {
+    type: 'mode.switch';
+    payload: {
+        id: string;
+    };
+} | {
+    type: 'files.list';
+    payload: {
+        query?: string | undefined;
+        limit?: number | undefined;
+        path?: string | undefined;
+    };
+} | {
+    type: 'files.tree';
+    payload: {
+        path?: string | undefined;
+    } | Record<string, never>;
+} | {
+    type: 'files.read';
+    payload: {
+        filePath: string;
+    };
+} | {
+    type: 'files.write';
+    payload: {
+        filePath: string;
+        content: string;
+    };
+} | {
+    type: 'todos.get';
+} | {
+    type: 'todos.clear';
+} | {
+    type: 'todos.remove';
+    payload: {
+        id?: string | undefined;
+        index?: number | undefined;
+    };
+} | {
+    type: 'todo.update';
+    payload: {
+        id: string;
+        status?: 'pending' | 'in_progress' | 'completed' | undefined;
+        activeForm?: string | undefined;
+    };
+} | {
+    type: 'tasks.get';
+} | {
+    type: 'task.update';
+    payload: {
+        id: string;
+        status: string;
+    };
+} | {
+    type: 'plan.get';
+} | {
+    type: 'plan.item.update';
+    payload: {
+        target: string;
+        status: 'open' | 'in_progress' | 'done';
+    };
+} | {
+    type: 'ping';
+} | {
+    type: 'process.list';
+} | {
+    type: 'process.kill';
+    payload: {
+        pid: number;
+    };
+} | {
+    type: 'process.killAll';
+} | {
+    type: 'git.info';
+} | {
+    type: 'goal.get';
+} | {
+    type: 'autonomy.switch';
+    payload: {
+        mode: string;
+    };
+} | {
+    type: 'prefs.update';
+    payload: Record<string, unknown>;
+} | {
+    type: 'prefs.get';
+} | {
+    type: 'projects.list';
+} | {
+    type: 'projects.add';
+    payload: {
+        root: string;
+        name?: string | undefined;
+    };
+} | {
+    type: 'projects.select';
+    payload: {
+        root: string;
+        name?: string | undefined;
+    };
+} | {
+    type: 'working_dir.set';
+    payload: {
+        path: string;
+    };
+} | {
+    type: 'shell.open';
+    payload: {
+        path: string;
+        target: 'terminal' | 'file-manager';
+    };
+} | WSCollabJoin | WSCollabLeave | WSCollabAnnotate | WSCollabResolve | WSCollabRequestPause | WSCollabResume | WSCollabGrantControl | WSCollabInjectTool | {
+    type: 'mailbox.messages';
+    payload: {
+        limit?: number | undefined;
+        incompleteOnly?: boolean | undefined;
+    };
+} | {
+    type: 'mailbox.agents';
+    payload: {
+        onlineOnly?: boolean | undefined;
+    } | Record<string, never>;
+} | {
+    type: 'mailbox.clear';
+} | {
+    type: 'mailbox.purge';
+    payload?: {
+        completedMaxAgeMs?: number;
+        incompleteMaxAgeMs?: number;
+    } | undefined;
+} | {
+    type: 'brain.status';
+} | {
+    type: 'brain.risk';
+    payload: {
+        level: string;
+    };
+} | {
+    type: 'brain.ask';
+    payload: {
+        question: string;
+    };
+} | {
+    type: 'model.refine';
+    payload: {
+        text: string;
+    };
+};
+type WSServerMessage = WSSessionStart | WSSessionEnd | WSTextDelta | WSThinkingDelta | WSToolUseStart | WSToolProgress | WSToolExecuted | WSIterationStarted | WSIterationCompleted | WSProviderResponse | WSRunResult | WSSessionStats | WSError | WSToolConfirmNeeded | WSContextDebug | WSContextCompacted | WSContextRepaired | WSContextModesList | WSContextModeChanged | WSToolsList | WSMemoryList | WSSkillsList | WSDiagGet | WSStatsGet | WSSessionsList | WSProviderCatalog | WSProviderModels | WSSavedProviders | WSProviderProbe | WSKeyOperationResult | WSFilesList | {
+    type: 'files.tree';
+    payload: {
+        root: string;
+        tree: unknown[];
+        error?: string | undefined;
+    };
+} | {
+    type: 'files.read';
+    payload: {
+        filePath: string;
+        content: string;
+        error?: string | undefined;
+    };
+} | {
+    type: 'files.written';
+    payload: {
+        filePath: string;
+        success: boolean;
+        error?: string | undefined;
+    };
+} | WSTodosUpdated | {
+    type: 'tasks.updated';
+    payload: {
+        tasks: unknown[];
+        error?: string | undefined;
+    };
+} | {
+    type: 'plan.updated';
+    payload: {
+        plan: unknown | null;
+        error?: string | undefined;
+    };
+} | WSModesList | WSAutoPhaseState | WSWorktreeState | WSWorktreeEvent | WSCollabState | WSCollabParticipantJoined | WSCollabParticipantLeft | WSCollabEvent | WSCollabAnnotationAdded | WSCollabAnnotationResolved | WSCollabPauseGranted | WSCollabPauseReleased | WSCollabInjectionGranted | {
+    type: 'session.checkpoints';
+    payload: {
+        checkpoints: Array<{
+            index: number;
+            iteration: number;
+            timestamp: string;
+            label: string;
+            messageCount: number;
+            tokens: number;
+        }>;
+    };
+} | {
+    type: 'goal.updated';
+    payload: Record<string, unknown> | null;
+} | {
+    type: 'prefs.updated';
+    payload: Record<string, unknown>;
+} | {
+    type: 'process.list';
+    payload: {
+        processes: Array<{
+            pid: number;
+            command: string;
+            tool: string;
+            startedAt: number;
+            status: 'running' | 'exited' | 'killed';
+            protected?: boolean | undefined;
+        }>;
+    };
+} | {
+    type: 'git.info';
+    payload: {
+        branch: string;
+        added: number;
+        deleted: number;
+        untracked: number;
+        behind: number;
+        ahead: number;
+    };
+} | {
+    type: 'projects.list';
+    payload: {
+        projects: Array<{
+            name: string;
+            root: string;
+            slug: string;
+            lastSeen?: string | undefined;
+        }>;
+    };
+} | {
+    type: 'projects.added';
+    payload: {
+        name: string;
+        root: string;
+        slug: string;
+        message: string;
+    };
+} | {
+    type: 'projects.selected';
+    payload: {
+        root: string;
+        name: string;
+        message: string;
+    };
+} | {
+    type: 'working_dir.changed';
+    payload: {
+        cwd: string;
+        projectRoot: string;
+    };
+} | {
+    type: 'brain.status';
+    payload: {
+        maxAutoRisk: string;
+        log: Array<{
+            at: number;
+            kind: string;
+            question: string;
+            outcome: string;
+        }>;
+    };
+} | {
+    type: 'brain.answer';
+    payload: {
+        question: string;
+        decision: {
+            type: string;
+            optionId?: string | undefined;
+            text?: string | undefined;
+            rationale?: string | undefined;
+            reason?: string | undefined;
+            prompt?: string | undefined;
+        };
+    };
+} | {
+    type: 'brain.event';
+    payload: Record<string, unknown> & {
+        event: string;
+    };
+} | {
+    type: 'model.refine_result';
+    payload: {
+        refined: string;
+        english: string;
+        error?: string | undefined;
+    };
+};
+type BroadcastFn = (msg: WSServerMessage) => void;
+/** Narrow type for CollabPanel event handlers — only collab-related messages + errors. */
+type CollabPanelMessage = WSCollabState | WSCollabParticipantJoined | WSCollabParticipantLeft | WSCollabAnnotationAdded | WSCollabAnnotationResolved | WSCollabPauseGranted | WSCollabPauseReleased | WSCollabInjectionGranted | WSError;
+/**
+ * Roles a collaboration participant can hold. The string union is the
+ * wire contract — adding new roles (e.g. `controller`) in later phases
+ * is a backward-compatible widening of this type as long as the server
+ * gracefully rejects roles it does not yet implement.
+ */
+type CollabRole = 'observer' | 'annotator' | 'controller';
+interface WSCollabJoin {
+    type: 'collab.join';
+    payload: {
+        sessionId: string;
+        role: CollabRole;
+    };
+}
+interface WSCollabLeave {
+    type: 'collab.leave';
+    payload: {
+        sessionId: string;
+    };
+}
+/**
+ * Annotate a specific event in the session log. The `atEventIndex`
+ * is a stable pointer the UI can scroll to / highlight. The server
+ * persists the annotation and broadcasts it to every participant
+ * in the same session, including the author.
+ */
+interface WSCollabAnnotate {
+    type: 'collab.annotate';
+    payload: {
+        sessionId: string;
+        atEventIndex: number;
+        text: string;
+    };
+}
+/** Mark an existing annotation as resolved. */
+interface WSCollabResolve {
+    type: 'collab.resolve';
+    payload: {
+        sessionId: string;
+        annotationId: string;
+    };
+}
+/** Sent on connect and every 2s while at least one participant is watching. */
+interface WSCollabState {
+    type: 'collab.state';
+    payload: {
+        sessionId: string;
+        participants: Array<{
+            participantId: string;
+            role: CollabRole;
+            joinedAt: string;
+        }>;
+    };
+}
+/** Broadcast when a new participant joins the session. */
+interface WSCollabParticipantJoined {
+    type: 'collab.participant.joined';
+    payload: {
+        participantId: string;
+        sessionId: string;
+        role: CollabRole;
+        joinedAt: string;
+    };
+}
+/** Broadcast when a participant leaves (explicit leave or WS close/error). */
+interface WSCollabParticipantLeft {
+    type: 'collab.participant.left';
+    payload: {
+        participantId: string;
+        sessionId: string;
+    };
+}
+/** Broadcast when a new annotation is added. Sent to all participants. */
+interface WSCollabAnnotationAdded {
+    type: 'collab.annotation.added';
+    payload: {
+        sessionId: string;
+        annotation: {
+            id: string;
+            atEventIndex: number;
+            authorId: string;
+            authorRole: 'annotator';
+            text: string;
+            createdAt: string;
+            resolved: boolean;
+        };
+    };
+}
+/** Broadcast when an annotation is resolved. Sent to all participants. */
+interface WSCollabAnnotationResolved {
+    type: 'collab.annotation.resolved';
+    payload: {
+        sessionId: string;
+        annotationId: string;
+        resolvedBy: string;
+        resolvedAt: string;
+    };
+}
+/** Client → server: controller asks the agent loop to pause before the next tool call. */
+interface WSCollabRequestPause {
+    type: 'collab.request_pause';
+    payload: {
+        sessionId: string;
+    };
+}
+/** Client → server: controller (or owner) clears the pause. */
+interface WSCollabResume {
+    type: 'collab.resume';
+    payload: {
+        sessionId: string;
+    };
+}
+/**
+ * Client → server: owner hands the controller role to a different
+ * participant. The current implementation is metadata-only — the
+ * existing controller's effective permissions don't change yet;
+ * the wire is reserved for a future iteration where per-participant
+ * RBAC becomes dynamic.
+ */
+interface WSCollabGrantControl {
+    type: 'collab.grant_control';
+    payload: {
+        sessionId: string;
+        toParticipant: string;
+    };
+}
+/** Server → client: the bus transitioned to paused (controller's pause took effect). */
+interface WSCollabPauseGranted {
+    type: 'collab.pause.granted';
+    payload: {
+        sessionId: string;
+        pausedBy: string;
+        pausedAt: string;
+        /**
+         * How long until the middleware auto-resumes (in ms). Clients
+         * can render a countdown. Defaults to 60_000 on the server.
+         */
+        autoResumeInMs: number;
+    };
+}
+/** Server → client: the bus transitioned back to running. */
+interface WSCollabPauseReleased {
+    type: 'collab.pause.released';
+    payload: {
+        sessionId: string;
+        /** 'controller' when a participant asked; 'timeout' when the middleware fired auto-resume. */
+        reason: 'controller' | 'timeout';
+        at: string;
+    };
+}
+/**
+ * Generic envelope wrapping a kernel event mirrored to observers.
+ * `kind` matches the original kernel event name (e.g. `tool.started`),
+ * `payload` is the original event payload (best-effort serialized),
+ * `at` is the broadcast timestamp.
+ *
+ * `replay` is true when the event was sent from the on-disk session
+ * log to a late-joining observer (Phase 1.5). Live events leave it
+ * undefined. Clients use the flag to render a "history" affordance
+ * (e.g. dim the styling or annotate the timestamp as "[joined late]").
+ */
+interface WSCollabEvent {
+    type: 'collab.event';
+    payload: {
+        kind: string;
+        payload: unknown;
+        at: string;
+        replay?: boolean | undefined;
+    };
+}
+/**
+ * Client → server: a controller injects a synthetic tool_result for
+ * the given tool_use_id. The next time the agent's toolCall pipeline
+ * sees that id, the real tool is skipped and the injected content
+ * is used. The injection is one-shot — consumed on first match.
+ */
+interface WSCollabInjectTool {
+    type: 'collab.inject_tool';
+    payload: {
+        sessionId: string;
+        toolUseId: string;
+        /** String or JSON-serializable value. */
+        content: unknown;
+        isError: boolean;
+        /** Free-form context surfaced in the broadcast and audit log. */
+        reason: string;
+    };
+}
+/**
+ * Server → client: an injection was queued or consumed. Sent to
+ * every participant so observers can show "the controller just
+ * replaced the tool result for tool X".
+ */
+interface WSCollabInjectionGranted {
+    type: 'collab.injection.granted';
+    payload: {
+        sessionId: string;
+        toolUseId: string;
+        toolName: string;
+        authorId: string;
+        reason: string;
+        isError: boolean;
+        /** 'queued' or 'consumed' — the bus does both. */
+        phase: 'queued' | 'consumed';
+        at: string;
+    };
+}
+
+export type { BroadcastFn, CollabPanelMessage, CollabRole, MemoryScope, WSAutoPhaseState, WSClientMessage, WSCollabAnnotate, WSCollabAnnotationAdded, WSCollabAnnotationResolved, WSCollabEvent, WSCollabGrantControl, WSCollabInjectTool, WSCollabInjectionGranted, WSCollabJoin, WSCollabLeave, WSCollabParticipantJoined, WSCollabParticipantLeft, WSCollabPauseGranted, WSCollabPauseReleased, WSCollabRequestPause, WSCollabResolve, WSCollabResume, WSCollabState, WSContextCompacted, WSContextDebug, WSContextModeChanged, WSContextModesList, WSContextRepaired, WSDiagGet, WSError, WSFilesList, WSIterationCompleted, WSIterationStarted, WSKeyOperationResult, WSMemoryList, WSMessage, WSModelSwitch, WSModesList, WSProviderCatalog, WSProviderModels, WSProviderProbe, WSProviderResponse, WSRunResult, WSSavedProviders, WSServerMessage, WSSessionEnd, WSSessionStart, WSSessionStats, WSSessionsList, WSSkillsList, WSStatsGet, WSTextDelta, WSThinkingDelta, WSTodosUpdated, WSToolConfirmNeeded, WSToolConfirmResult, WSToolExecuted, WSToolProgress, WSToolUseStart, WSToolsList, WSUserMessage, WSWorktreeEvent, WSWorktreeState, WorktreeHandleView };