@dreb/coding-agent 2.34.3 → 2.36.0

package/dist/modes/rpc/rpc-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"rpc-types.js","sourceRoot":"","sources":["../../../src/modes/rpc/rpc-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG","sourcesContent":["/**\n * RPC protocol types for headless operation.\n *\n * Commands are sent as JSON lines on stdin.\n * Responses and events are emitted as JSON lines on stdout.\n */\n\nimport type { AgentMessage, ThinkingLevel } from \"@dreb/agent-core\";\nimport type { ImageContent, Model } from \"@dreb/ai\";\nimport type { SessionStats } from \"../../core/agent-session.js\";\nimport type { BashResult } from \"../../core/bash-executor.js\";\nimport type { CompactionResult } from \"../../core/compaction/index.js\";\nimport type { SourceInfo } from \"../../core/source-info.js\";\n\n// ============================================================================\n// RPC Commands (stdin)\n// ============================================================================\n\nexport type RpcCommand =\n\t// Prompting\n\t| { id?: string; type: \"prompt\"; message: string; images?: ImageContent[]; streamingBehavior?: \"steer\" | \"followUp\" }\n\t| { id?: string; type: \"steer\"; message: string; images?: ImageContent[] }\n\t| { id?: string; type: \"follow_up\"; message: string; images?: ImageContent[] }\n\t| { id?: string; type: \"abort\" }\n\t| { id?: string; type: \"new_session\"; parentSession?: string }\n\n\t// State\n\t| { id?: string; type: \"get_state\" }\n\n\t// Model\n\t| { id?: string; type: \"set_model\"; provider: string; modelId: string }\n\t| { id?: string; type: \"resolve_model\"; pattern: string }\n\t| { id?: string; type: \"cycle_model\" }\n\t| { id?: string; type: \"get_available_models\" }\n\n\t// Buddy — hatch/reroll run inside the agent process so API keys never leave\n\t| { id?: string; type: \"buddy_hatch\" }\n\t| { id?: string; type: \"buddy_reroll\" }\n\n\t// Thinking\n\t| { id?: string; type: \"set_thinking_level\"; level: ThinkingLevel }\n\t| { id?: string; type: \"cycle_thinking_level\" }\n\n\t// Queue modes\n\t| { id?: string; type: \"set_steering_mode\"; mode: \"all\" | \"one-at-a-time\" }\n\t| { id?: string; type: \"set_follow_up_mode\"; mode: \"all\" | \"one-at-a-time\" }\n\n\t// Compaction\n\t| { id?: string; type: \"compact\"; customInstructions?: string }\n\t| { id?: string; type: \"set_auto_compaction\"; enabled: boolean }\n\n\t// Retry\n\t| { id?: string; type: \"set_auto_retry\"; enabled: boolean }\n\t| { id?: string; type: \"abort_retry\" }\n\n\t// Bash\n\t| { id?: string; type: \"bash\"; command: string }\n\t| { id?: string; type: \"abort_bash\" }\n\n\t// Session\n\t| { id?: string; type: \"get_session_stats\" }\n\t| { id?: string; type: \"get_performance_stats\" }\n\t| { id?: string; type: \"export_html\"; outputPath?: string }\n\t| { id?: string; type: \"switch_session\"; sessionPath: string }\n\t| { id?: string; type: \"fork\"; entryId: string }\n\t| { id?: string; type: \"get_fork_messages\" }\n\t| { id?: string; type: \"get_last_assistant_text\" }\n\t| { id?: string; type: \"set_session_name\"; name: string }\n\n\t// Messages\n\t| { id?: string; type: \"get_messages\" }\n\n\t// Commands (available for invocation via prompt)\n\t| { id?: string; type: \"get_commands\" }\n\n\t// Session listing\n\t| { id?: string; type: \"list_sessions\" }\n\n\t// Version\n\t| { id?: string; type: \"get_version\" };\n\n// ============================================================================\n// RPC Slash Command (for get_commands response)\n// ============================================================================\n\n/** A command available for invocation via prompt */\nexport interface RpcSlashCommand {\n\t/** Command name (without leading slash) */\n\tname: string;\n\t/** Human-readable description */\n\tdescription?: string;\n\t/** What kind of command this is */\n\tsource: \"extension\" | \"prompt\" | \"skill\";\n\t/** Source metadata for the owning resource */\n\tsourceInfo: SourceInfo;\n}\n\n// ============================================================================\n// RPC State\n// ============================================================================\n\nexport interface RpcSessionState {\n\tmodel?: Model<any>;\n\tthinkingLevel: ThinkingLevel;\n\tisStreaming: boolean;\n\tisCompacting: boolean;\n\tsteeringMode: \"all\" | \"one-at-a-time\";\n\tfollowUpMode: \"all\" | \"one-at-a-time\";\n\tsessionFile?: string;\n\tsessionId: string;\n\tsessionName?: string;\n\tautoCompactionEnabled: boolean;\n\tmessageCount: number;\n\tpendingMessageCount: number;\n\t/** Non-empty when the model was changed from the user's saved preference\n\t *  (e.g. saved model unavailable after restart). */\n\tmodelFallbackMessage?: string;\n}\n\n// ============================================================================\n// RPC Responses (stdout)\n// ============================================================================\n\n// Success responses with data\nexport type RpcResponse =\n\t// Prompting (async - events follow)\n\t| { id?: string; type: \"response\"; command: \"prompt\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"steer\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"follow_up\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"abort\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"new_session\"; success: true; data: { cancelled: boolean } }\n\n\t// State\n\t| { id?: string; type: \"response\"; command: \"get_state\"; success: true; data: RpcSessionState }\n\n\t// Model\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"set_model\";\n\t\t\tsuccess: true;\n\t\t\tdata: Model<any>;\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"resolve_model\";\n\t\t\tsuccess: true;\n\t\t\tdata: { model: Model<any>; warning?: string } | null;\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"cycle_model\";\n\t\t\tsuccess: true;\n\t\t\tdata: { model: Model<any>; thinkingLevel: ThinkingLevel; isScoped: boolean } | null;\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_available_models\";\n\t\t\tsuccess: true;\n\t\t\tdata: { models: Model<any>[] };\n\t  }\n\n\t// Buddy\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"buddy_hatch\";\n\t\t\tsuccess: true;\n\t\t\tdata: { state: import(\"../../core/buddy/buddy-types.js\").BuddyState };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"buddy_reroll\";\n\t\t\tsuccess: true;\n\t\t\tdata: { state: import(\"../../core/buddy/buddy-types.js\").BuddyState };\n\t  }\n\n\t// Thinking\n\t| { id?: string; type: \"response\"; command: \"set_thinking_level\"; success: true }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"cycle_thinking_level\";\n\t\t\tsuccess: true;\n\t\t\tdata: { level: ThinkingLevel } | null;\n\t  }\n\n\t// Queue modes\n\t| { id?: string; type: \"response\"; command: \"set_steering_mode\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"set_follow_up_mode\"; success: true }\n\n\t// Compaction\n\t| { id?: string; type: \"response\"; command: \"compact\"; success: true; data: CompactionResult }\n\t| { id?: string; type: \"response\"; command: \"set_auto_compaction\"; success: true }\n\n\t// Retry\n\t| { id?: string; type: \"response\"; command: \"set_auto_retry\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"abort_retry\"; success: true }\n\n\t// Bash\n\t| { id?: string; type: \"response\"; command: \"bash\"; success: true; data: BashResult }\n\t| { id?: string; type: \"response\"; command: \"abort_bash\"; success: true }\n\n\t// Session\n\t| { id?: string; type: \"response\"; command: \"get_session_stats\"; success: true; data: SessionStats }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_performance_stats\";\n\t\t\tsuccess: true;\n\t\t\tdata: { models: Array<{ provider: string; modelId: string; median: number; mean: number; count: number }> };\n\t  }\n\t| { id?: string; type: \"response\"; command: \"export_html\"; success: true; data: { path: string } }\n\t| { id?: string; type: \"response\"; command: \"switch_session\"; success: true; data: { cancelled: boolean } }\n\t| { id?: string; type: \"response\"; command: \"fork\"; success: true; data: { text: string; cancelled: boolean } }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_fork_messages\";\n\t\t\tsuccess: true;\n\t\t\tdata: { messages: Array<{ entryId: string; text: string }> };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_last_assistant_text\";\n\t\t\tsuccess: true;\n\t\t\tdata: { text: string | null };\n\t  }\n\t| { id?: string; type: \"response\"; command: \"set_session_name\"; success: true }\n\n\t// Messages\n\t| { id?: string; type: \"response\"; command: \"get_messages\"; success: true; data: { messages: AgentMessage[] } }\n\n\t// Commands\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_commands\";\n\t\t\tsuccess: true;\n\t\t\tdata: { commands: RpcSlashCommand[] };\n\t  }\n\n\t// Session listing\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"list_sessions\";\n\t\t\tsuccess: true;\n\t\t\tdata: { sessions: RpcSessionInfo[] };\n\t  }\n\n\t// Version\n\t| { id?: string; type: \"response\"; command: \"get_version\"; success: true; data: { version: string } }\n\n\t// Error response (any command can fail)\n\t| { id?: string; type: \"response\"; command: string; success: false; error: string };\n\n// ============================================================================\n// Session Info (for list_sessions response)\n// ============================================================================\n\n/** Session metadata returned by list_sessions */\nexport interface RpcSessionInfo {\n\t/** Full path to the session JSONL file */\n\tpath: string;\n\t/** Session UUID */\n\tid: string;\n\t/** Working directory where the session was started */\n\tcwd: string;\n\t/** User-defined display name */\n\tname?: string;\n\t/** ISO timestamp of session creation */\n\tcreated: string;\n\t/** ISO timestamp of last modification */\n\tmodified: string;\n\t/** Number of messages in the session */\n\tmessageCount: number;\n\t/** First user message text */\n\tfirstMessage: string;\n}\n\n// ============================================================================\n// Extension UI Events (stdout)\n// ============================================================================\n\n/** Emitted when an extension needs user input */\nexport type RpcExtensionUIRequest =\n\t| { type: \"extension_ui_request\"; id: string; method: \"select\"; title: string; options: string[]; timeout?: number }\n\t| { type: \"extension_ui_request\"; id: string; method: \"confirm\"; title: string; message: string; timeout?: number }\n\t| {\n\t\t\ttype: \"extension_ui_request\";\n\t\t\tid: string;\n\t\t\tmethod: \"input\";\n\t\t\ttitle: string;\n\t\t\tplaceholder?: string;\n\t\t\ttimeout?: number;\n\t  }\n\t| { type: \"extension_ui_request\"; id: string; method: \"editor\"; title: string; prefill?: string }\n\t| {\n\t\t\ttype: \"extension_ui_request\";\n\t\t\tid: string;\n\t\t\tmethod: \"notify\";\n\t\t\tmessage: string;\n\t\t\tnotifyType?: \"info\" | \"warning\" | \"error\";\n\t  }\n\t| {\n\t\t\ttype: \"extension_ui_request\";\n\t\t\tid: string;\n\t\t\tmethod: \"setStatus\";\n\t\t\tstatusKey: string;\n\t\t\tstatusText: string | undefined;\n\t  }\n\t| {\n\t\t\ttype: \"extension_ui_request\";\n\t\t\tid: string;\n\t\t\tmethod: \"setWidget\";\n\t\t\twidgetKey: string;\n\t\t\twidgetLines: string[] | undefined;\n\t\t\twidgetPlacement?: \"aboveEditor\" | \"belowEditor\";\n\t  }\n\t| { type: \"extension_ui_request\"; id: string; method: \"setTitle\"; title: string }\n\t| { type: \"extension_ui_request\"; id: string; method: \"set_editor_text\"; text: string };\n\n// ============================================================================\n// Extension UI Commands (stdin)\n// ============================================================================\n\n/** Response to an extension UI request */\nexport type RpcExtensionUIResponse =\n\t| { type: \"extension_ui_response\"; id: string; value: string }\n\t| { type: \"extension_ui_response\"; id: string; confirmed: boolean }\n\t| { type: \"extension_ui_response\"; id: string; cancelled: true };\n\n// ============================================================================\n// Helper type for extracting command types\n// ============================================================================\n\nexport type RpcCommandType = RpcCommand[\"type\"];\n"]}
+{"version":3,"file":"rpc-types.js","sourceRoot":"","sources":["../../../src/modes/rpc/rpc-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG","sourcesContent":["/**\n * RPC protocol types for headless operation.\n *\n * Commands are sent as JSON lines on stdin.\n * Responses and events are emitted as JSON lines on stdout.\n */\n\nimport type { AgentMessage, ThinkingLevel } from \"@dreb/agent-core\";\nimport type { ImageContent, Model, Transport } from \"@dreb/ai\";\nimport type { SessionStats } from \"../../core/agent-session.js\";\nimport type { BashResult } from \"../../core/bash-executor.js\";\nimport type { CompactionResult } from \"../../core/compaction/index.js\";\nimport type { ContextUsage } from \"../../core/extensions/types.js\";\nimport type { SessionEntry } from \"../../core/session-manager.js\";\nimport type { SourceInfo } from \"../../core/source-info.js\";\n\n// ============================================================================\n// RPC Commands (stdin)\n// ============================================================================\n\nexport type RpcCommand =\n\t// Prompting\n\t| { id?: string; type: \"prompt\"; message: string; images?: ImageContent[]; streamingBehavior?: \"steer\" | \"followUp\" }\n\t| { id?: string; type: \"steer\"; message: string; images?: ImageContent[] }\n\t| { id?: string; type: \"follow_up\"; message: string; images?: ImageContent[] }\n\t| { id?: string; type: \"abort\" }\n\t| { id?: string; type: \"new_session\"; parentSession?: string }\n\n\t// State\n\t| { id?: string; type: \"get_state\" }\n\t| { id?: string; type: \"get_resources\" }\n\t| { id?: string; type: \"get_git_branch\" }\n\t| { id?: string; type: \"get_daily_cost\" }\n\n\t// Model\n\t| { id?: string; type: \"set_model\"; provider: string; modelId: string }\n\t| { id?: string; type: \"resolve_model\"; pattern: string }\n\t| { id?: string; type: \"cycle_model\" }\n\t| { id?: string; type: \"get_available_models\" }\n\n\t// Buddy — hatch/reroll run inside the agent process so API keys never leave\n\t| { id?: string; type: \"buddy_hatch\" }\n\t| { id?: string; type: \"buddy_reroll\" }\n\n\t// Thinking\n\t| { id?: string; type: \"set_thinking_level\"; level: ThinkingLevel }\n\t| { id?: string; type: \"cycle_thinking_level\" }\n\n\t// Queue modes\n\t| { id?: string; type: \"set_steering_mode\"; mode: \"all\" | \"one-at-a-time\" }\n\t| { id?: string; type: \"set_follow_up_mode\"; mode: \"all\" | \"one-at-a-time\" }\n\t| { id?: string; type: \"get_pending_messages\" }\n\t| { id?: string; type: \"clear_pending_messages\" }\n\n\t// Compaction\n\t| { id?: string; type: \"compact\"; customInstructions?: string }\n\t| { id?: string; type: \"set_auto_compaction\"; enabled: boolean }\n\t| { id?: string; type: \"abort_compaction\" }\n\n\t// Retry\n\t| { id?: string; type: \"set_auto_retry\"; enabled: boolean }\n\t| { id?: string; type: \"abort_retry\" }\n\n\t// Bash\n\t| { id?: string; type: \"bash\"; command: string }\n\t| { id?: string; type: \"abort_bash\" }\n\n\t// Session\n\t| { id?: string; type: \"get_session_stats\" }\n\t| { id?: string; type: \"get_performance_stats\" }\n\t| { id?: string; type: \"export_html\"; outputPath?: string }\n\t| { id?: string; type: \"switch_session\"; sessionPath: string }\n\t| { id?: string; type: \"delete_session\"; sessionPath: string }\n\t| { id?: string; type: \"fork\"; entryId: string }\n\t| { id?: string; type: \"get_fork_messages\" }\n\t| { id?: string; type: \"get_tree\" }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"navigate_tree\";\n\t\t\ttargetId: string;\n\t\t\tsummarize?: boolean;\n\t\t\tcustomInstructions?: string;\n\t\t\treplaceInstructions?: boolean;\n\t\t\tlabel?: string;\n\t  }\n\t| { id?: string; type: \"get_last_assistant_text\" }\n\t| { id?: string; type: \"set_session_name\"; name: string }\n\n\t// Messages\n\t| { id?: string; type: \"get_messages\" }\n\n\t// Commands (available for invocation via prompt)\n\t| { id?: string; type: \"get_commands\" }\n\n\t// Session listing\n\t| { id?: string; type: \"list_sessions\" }\n\t| { id?: string; type: \"list_all_sessions\" }\n\n\t// Background agents\n\t| { id?: string; type: \"list_background_agents\" }\n\t| { id?: string; type: \"list_agent_types\" }\n\n\t// Settings (persistent defaults)\n\t| { id?: string; type: \"get_settings\" }\n\t| { id?: string; type: \"set_settings\"; settings: RpcSettingsUpdate }\n\n\t// Version\n\t| { id?: string; type: \"get_version\" };\n\n// ============================================================================\n// RPC Slash Command (for get_commands response)\n// ============================================================================\n\n/** A command available for invocation via prompt */\nexport interface RpcSlashCommand {\n\t/** Command name (without leading slash) */\n\tname: string;\n\t/** Human-readable description */\n\tdescription?: string;\n\t/** What kind of command this is */\n\tsource: \"extension\" | \"prompt\" | \"skill\";\n\t/** Source metadata for the owning resource */\n\tsourceInfo: SourceInfo;\n}\n\nexport interface RpcScopedModel {\n\tprovider: string;\n\tid: string;\n\tname?: string;\n\treasoning?: boolean;\n\tthinkingLevel?: string;\n}\n\nexport interface RpcResources {\n\tcontextFiles: Array<{ path: string }>;\n\tskills: Array<{ name: string; description: string }>;\n\textensions: Array<{ name?: string; path: string }>;\n\tpromptTemplates: Array<{ name: string; description?: string }>;\n\tsystemPromptPresent: boolean;\n}\n\nexport interface RpcQueuedMessage {\n\ttext: string;\n\timages?: ImageContent[];\n}\n\nexport interface RpcPendingMessages {\n\t/** Text-only compatibility view for existing clients. */\n\tsteering: string[];\n\t/** Text-only compatibility view for existing clients. */\n\tfollowUp: string[];\n\t/** Full queued payloads, including inline image attachments. */\n\tsteeringMessages?: RpcQueuedMessage[];\n\t/** Full queued payloads, including inline image attachments. */\n\tfollowUpMessages?: RpcQueuedMessage[];\n}\n\n// ============================================================================\n// RPC State\n// ============================================================================\n\nexport interface RpcSessionState {\n\tmodel?: Model<any>;\n\tscopedModels: RpcScopedModel[];\n\tusingSubscription: boolean;\n\tthinkingLevel: ThinkingLevel;\n\tisStreaming: boolean;\n\tisCompacting: boolean;\n\tsteeringMode: \"all\" | \"one-at-a-time\";\n\tfollowUpMode: \"all\" | \"one-at-a-time\";\n\tsessionFile?: string;\n\tsessionId: string;\n\tsessionName?: string;\n\tautoCompactionEnabled: boolean;\n\tmessageCount: number;\n\tpendingMessageCount: number;\n\t/**\n\t * Context window usage computed by the session — the exact numbers the TUI footer\n\t * renders (AgentSession.getContextUsage()). `tokens`/`percent` are null when usage\n\t * is unknown (e.g. right after compaction, before the next LLM response). Undefined\n\t * when no model is set or the model has no context window.\n\t */\n\tcontextUsage?: ContextUsage;\n\t/** Non-empty when the model was changed from the user's saved preference\n\t *  (e.g. saved model unavailable after restart). */\n\tmodelFallbackMessage?: string;\n}\n\n// ============================================================================\n// RPC Responses (stdout)\n// ============================================================================\n\n// Success responses with data\nexport type RpcResponse =\n\t// Prompting (async - events follow)\n\t| { id?: string; type: \"response\"; command: \"prompt\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"steer\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"follow_up\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"abort\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"new_session\"; success: true; data: { cancelled: boolean } }\n\n\t// State\n\t| { id?: string; type: \"response\"; command: \"get_state\"; success: true; data: RpcSessionState }\n\t| { id?: string; type: \"response\"; command: \"get_resources\"; success: true; data: RpcResources }\n\t| { id?: string; type: \"response\"; command: \"get_git_branch\"; success: true; data: { branch: string | null } }\n\t| { id?: string; type: \"response\"; command: \"get_daily_cost\"; success: true; data: { cost: number } }\n\n\t// Model\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"set_model\";\n\t\t\tsuccess: true;\n\t\t\tdata: Model<any>;\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"resolve_model\";\n\t\t\tsuccess: true;\n\t\t\tdata: { model: Model<any>; warning?: string } | null;\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"cycle_model\";\n\t\t\tsuccess: true;\n\t\t\tdata: { model: Model<any>; thinkingLevel: ThinkingLevel; isScoped: boolean } | null;\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_available_models\";\n\t\t\tsuccess: true;\n\t\t\tdata: { models: Model<any>[] };\n\t  }\n\n\t// Buddy\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"buddy_hatch\";\n\t\t\tsuccess: true;\n\t\t\tdata: { state: import(\"../../core/buddy/buddy-types.js\").BuddyState };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"buddy_reroll\";\n\t\t\tsuccess: true;\n\t\t\tdata: { state: import(\"../../core/buddy/buddy-types.js\").BuddyState };\n\t  }\n\n\t// Thinking\n\t| { id?: string; type: \"response\"; command: \"set_thinking_level\"; success: true }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"cycle_thinking_level\";\n\t\t\tsuccess: true;\n\t\t\tdata: { level: ThinkingLevel } | null;\n\t  }\n\n\t// Queue modes\n\t| { id?: string; type: \"response\"; command: \"set_steering_mode\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"set_follow_up_mode\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"get_pending_messages\"; success: true; data: RpcPendingMessages }\n\t| { id?: string; type: \"response\"; command: \"clear_pending_messages\"; success: true; data: RpcPendingMessages }\n\n\t// Compaction\n\t| { id?: string; type: \"response\"; command: \"compact\"; success: true; data: CompactionResult }\n\t| { id?: string; type: \"response\"; command: \"set_auto_compaction\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"abort_compaction\"; success: true }\n\n\t// Retry\n\t| { id?: string; type: \"response\"; command: \"set_auto_retry\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"abort_retry\"; success: true }\n\n\t// Bash\n\t| { id?: string; type: \"response\"; command: \"bash\"; success: true; data: BashResult }\n\t| { id?: string; type: \"response\"; command: \"abort_bash\"; success: true }\n\n\t// Session\n\t| { id?: string; type: \"response\"; command: \"get_session_stats\"; success: true; data: SessionStats }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_performance_stats\";\n\t\t\tsuccess: true;\n\t\t\tdata: { models: Array<{ provider: string; modelId: string; median: number; mean: number; count: number }> };\n\t  }\n\t| { id?: string; type: \"response\"; command: \"export_html\"; success: true; data: { path: string } }\n\t| { id?: string; type: \"response\"; command: \"switch_session\"; success: true; data: { cancelled: boolean } }\n\t| { id?: string; type: \"response\"; command: \"delete_session\"; success: true; data: { method: \"trash\" | \"unlink\" } }\n\t| { id?: string; type: \"response\"; command: \"fork\"; success: true; data: { text: string; cancelled: boolean } }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_fork_messages\";\n\t\t\tsuccess: true;\n\t\t\tdata: { messages: Array<{ entryId: string; text: string }> };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_tree\";\n\t\t\tsuccess: true;\n\t\t\tdata: { roots: RpcTreeNode[]; leafId: string | null };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"navigate_tree\";\n\t\t\tsuccess: true;\n\t\t\tdata: { cancelled: boolean; editorText?: string };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_last_assistant_text\";\n\t\t\tsuccess: true;\n\t\t\tdata: { text: string | null };\n\t  }\n\t| { id?: string; type: \"response\"; command: \"set_session_name\"; success: true }\n\n\t// Messages\n\t| { id?: string; type: \"response\"; command: \"get_messages\"; success: true; data: { messages: AgentMessage[] } }\n\n\t// Commands\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_commands\";\n\t\t\tsuccess: true;\n\t\t\tdata: { commands: RpcSlashCommand[] };\n\t  }\n\n\t// Session listing\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"list_sessions\";\n\t\t\tsuccess: true;\n\t\t\tdata: { sessions: RpcSessionInfo[] };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"list_all_sessions\";\n\t\t\tsuccess: true;\n\t\t\tdata: { sessions: RpcSessionInfo[] };\n\t  }\n\n\t// Background agents\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"list_background_agents\";\n\t\t\tsuccess: true;\n\t\t\tdata: { agents: RpcBackgroundAgentInfo[] };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"list_agent_types\";\n\t\t\tsuccess: true;\n\t\t\tdata: { agentTypes: RpcAgentTypeInfo[] };\n\t  }\n\n\t// Settings\n\t| { id?: string; type: \"response\"; command: \"get_settings\"; success: true; data: RpcSettingsSnapshot }\n\t| { id?: string; type: \"response\"; command: \"set_settings\"; success: true; data: RpcSettingsSetResult }\n\n\t// Version\n\t| { id?: string; type: \"response\"; command: \"get_version\"; success: true; data: { version: string } }\n\n\t// Error response (any command can fail)\n\t| { id?: string; type: \"response\"; command: string; success: false; error: string };\n\n// ============================================================================\n// Session Info (for list_sessions response)\n// ============================================================================\n\n/** Session metadata returned by list_sessions */\nexport interface RpcSessionInfo {\n\t/** Full path to the session JSONL file */\n\tpath: string;\n\t/** Session UUID */\n\tid: string;\n\t/** Working directory where the session was started */\n\tcwd: string;\n\t/** User-defined display name */\n\tname?: string;\n\t/** ISO timestamp of session creation */\n\tcreated: string;\n\t/** ISO timestamp of last modification */\n\tmodified: string;\n\t/** Number of messages in the session */\n\tmessageCount: number;\n\t/** First user message text */\n\tfirstMessage: string;\n}\n\n/** Background agent metadata returned by list_background_agents */\nexport interface RpcBackgroundAgentInfo {\n\t/** Registry ID (hex) used in background_agent_* events */\n\tagentId: string;\n\t/** Agent type name (e.g. \"Explore\") */\n\tagentType: string;\n\t/** Short human-readable task label */\n\ttaskSummary: string;\n\t/** ISO timestamp of launch */\n\tstartedAt: string;\n\t/** Lifecycle status */\n\tstatus: \"running\" | \"completed\" | \"failed\";\n\t/** Directory containing the agent's session JSONL file (known at spawn time) */\n\tsessionDir?: string;\n\t/** Path to the agent's session JSONL file (available after the child exits) */\n\tsessionFile?: string;\n\t/** Working directory the agent runs in */\n\tcwd?: string;\n}\n\n/** Agent type metadata returned by list_agent_types */\nexport interface RpcAgentTypeInfo {\n\t/** Agent type name, e.g. \"Explore\" */\n\tname: string;\n\t/** Human-readable description from the agent frontmatter */\n\tdescription: string;\n}\n\n/** Serializable session tree node returned by get_tree. Stable DTO — no raw entry payloads. */\nexport interface RpcTreeNode {\n\t/** Entry id */\n\tid: string;\n\t/**\n\t * Parent entry id, or null for a root. Orphaned roots (broken parent chains) keep their\n\t * original non-null parentId, which references an entry not present in the tree — prefer\n\t * the nested `children` structure over parentId when reconstructing hierarchy.\n\t */\n\tparentId: string | null;\n\t/** Session entry type */\n\ttype: SessionEntry[\"type\"];\n\t/** Message role, present only when type === \"message\" (user, assistant, toolResult, bashExecution, ...) */\n\trole?: string;\n\t/** Short single-line content preview (whitespace-collapsed, max 200 chars) */\n\tpreview: string;\n\t/** ISO timestamp of the entry */\n\ttimestamp: string;\n\t/** Resolved label, if any */\n\tlabel?: string;\n\t/** Child nodes, oldest first */\n\tchildren: RpcTreeNode[];\n}\n\n// ============================================================================\n// Settings (persistent defaults)\n// ============================================================================\n\n/**\n * Snapshot of persistent default settings returned by `get_settings` and `set_settings`.\n *\n * These are the values persisted via SettingsManager (merged global + project view) that\n * seed fresh runtimes — NOT the live session state. For the current runtime state\n * (active model, effective thinking level, modes in effect), use `get_state`.\n */\nexport interface RpcSettingsSnapshot {\n\t/** Default provider used at startup (absent if never set) */\n\tdefaultProvider?: string;\n\t/** Default model id used at startup (absent if never set) */\n\tdefaultModel?: string;\n\t/** Default thinking level applied at startup (absent if never set) */\n\tdefaultThinkingLevel?: ThinkingLevel;\n\t/** How queued steering messages are delivered */\n\tsteeringMode: \"all\" | \"one-at-a-time\";\n\t/** How queued follow-up messages are delivered */\n\tfollowUpMode: \"all\" | \"one-at-a-time\";\n\t/** Whether automatic context compaction is enabled */\n\tcompactionEnabled: boolean;\n\t/** Whether automatic retry on transient errors is enabled */\n\tretryEnabled: boolean;\n\t/** Whether image inputs are automatically resized before sending to providers */\n\timageAutoResize?: boolean;\n\t/** Whether image inputs are blocked from being sent to providers */\n\tblockImages?: boolean;\n\t/** Whether skills are registered as slash commands */\n\tenableSkillCommands?: boolean;\n\t/** Whether nested AGENTS.md/CLAUDE.md context auto-loads when tools enter subdirectories */\n\tautoLoadNestedContext?: boolean;\n\t/** Preferred model transport */\n\ttransport?: Transport;\n\t/** Whether raw thinking blocks are hidden in rendered transcripts */\n\thideThinkingBlock?: boolean;\n\t/** Per-agent model fallback lists, merged global + project with project entries winning */\n\tagentModels?: Record<string, string[]>;\n}\n\n/** Settings snapshot returned by `set_settings`; warnings are present for loud shadowing notices. */\nexport type RpcSettingsSetResult = RpcSettingsSnapshot & { warnings?: string[] };\n\n/**\n * Partial update payload for `set_settings`. All fields optional, but at least one\n * must be present. `defaultProvider` and `defaultModel` must be supplied together.\n * Writes persistent defaults only — never touches live session state.\n */\nexport interface RpcSettingsUpdate {\n\tdefaultProvider?: string;\n\tdefaultModel?: string;\n\tdefaultThinkingLevel?: ThinkingLevel;\n\tsteeringMode?: \"all\" | \"one-at-a-time\";\n\tfollowUpMode?: \"all\" | \"one-at-a-time\";\n\tcompactionEnabled?: boolean;\n\tretryEnabled?: boolean;\n\timageAutoResize?: boolean;\n\tblockImages?: boolean;\n\tenableSkillCommands?: boolean;\n\tautoLoadNestedContext?: boolean;\n\ttransport?: Transport;\n\thideThinkingBlock?: boolean;\n\tagentModels?: Record<string, string[]>;\n}\n\n// ============================================================================\n// Extension UI Events (stdout)\n// ============================================================================\n\n/** Emitted when an extension needs user input */\nexport type RpcExtensionUIRequest =\n\t| { type: \"extension_ui_request\"; id: string; method: \"select\"; title: string; options: string[]; timeout?: number }\n\t| { type: \"extension_ui_request\"; id: string; method: \"confirm\"; title: string; message: string; timeout?: number }\n\t| {\n\t\t\ttype: \"extension_ui_request\";\n\t\t\tid: string;\n\t\t\tmethod: \"input\";\n\t\t\ttitle: string;\n\t\t\tplaceholder?: string;\n\t\t\ttimeout?: number;\n\t  }\n\t| { type: \"extension_ui_request\"; id: string; method: \"editor\"; title: string; prefill?: string }\n\t| {\n\t\t\ttype: \"extension_ui_request\";\n\t\t\tid: string;\n\t\t\tmethod: \"notify\";\n\t\t\tmessage: string;\n\t\t\tnotifyType?: \"info\" | \"warning\" | \"error\";\n\t  }\n\t| {\n\t\t\ttype: \"extension_ui_request\";\n\t\t\tid: string;\n\t\t\tmethod: \"setStatus\";\n\t\t\tstatusKey: string;\n\t\t\tstatusText: string | undefined;\n\t  }\n\t| {\n\t\t\ttype: \"extension_ui_request\";\n\t\t\tid: string;\n\t\t\tmethod: \"setWidget\";\n\t\t\twidgetKey: string;\n\t\t\twidgetLines: string[] | undefined;\n\t\t\twidgetPlacement?: \"aboveEditor\" | \"belowEditor\";\n\t  }\n\t| { type: \"extension_ui_request\"; id: string; method: \"setTitle\"; title: string }\n\t| { type: \"extension_ui_request\"; id: string; method: \"set_editor_text\"; text: string };\n\n// ============================================================================\n// Extension UI Commands (stdin)\n// ============================================================================\n\n/** Response to an extension UI request */\nexport type RpcExtensionUIResponse =\n\t| { type: \"extension_ui_response\"; id: string; value: string }\n\t| { type: \"extension_ui_response\"; id: string; confirmed: boolean }\n\t| { type: \"extension_ui_response\"; id: string; cancelled: true };\n\n// ============================================================================\n// Helper type for extracting command types\n// ============================================================================\n\nexport type RpcCommandType = RpcCommand[\"type\"];\n"]}

package/docs/dashboard.md

@@ -0,0 +1,254 @@
+# Web Dashboard
+
+`dreb dashboard` launches a browser UI for dreb: a fleet overview of sessions
+across projects, a full-parity chat view, live background-subagent
+observability, host file browsing, and settings — usable from desktop and
+mobile browsers.
+
+The dashboard lives in the `@dreb/dashboard` package. Live agent control goes
+over [RPC mode](rpc.md): the server maintains a pool of `dreb --mode rpc`
+child processes, one per live session. The server uses dreb's public session
+APIs for on-disk inventory/delete and serves its own host file API.
+
+## Launching
+
+```bash
+# via the dreb CLI (requires @dreb/dashboard to be installed)
+dreb dashboard [--port 5343]
+
+# or directly
+dreb-dashboard [--port 5343]
+
+# remote over Tailscale with HTTPS (PWA + notifications on mobile)
+dreb dashboard --remote --allow you@example.com \
+  --https --cert /path/cert.pem --key /path/key.pem
+```
+
+If `@dreb/dashboard` is not installed, `dreb dashboard` fails loudly with
+install instructions (`npm install -g @dreb/dashboard`).
+
+Open `http://127.0.0.1:5343` on the same machine.
+
+## Local vs remote — exactly two modes
+
+**Local-only (default).** The server binds `127.0.0.1` exclusively. Machines
+on your LAN cannot reach it — packets never arrive at the process. No login or
+pairing. Works without Tailscale installed. This is the right mode for
+same-machine use, including work environments.
+
+Requests are additionally validated for loopback `Host`/`Origin` headers, so a
+malicious website cannot drive the dashboard API through DNS rebinding.
+
+**Remote (opt-in).** For any access from another device — phone, laptop, even
+on the same LAN — the path is [Tailscale](https://tailscale.com):
+
+```bash
+dreb dashboard --remote --allow you@example.com --allow teammate@example.com
+# or: dreb-dashboard --remote --allow you@example.com --allow teammate@example.com
+```
+
+Layers, in order, all fail-closed (any auth-subsystem error denies):
+
+1. **Tailscale reachability** — the peer address must resolve to a tailnet
+   identity via `tailscale status --json`. No Tailscale, no access.
+2. **Identity allowlist** — `--allow` login names. An empty allowlist denies
+   everyone. Rejected identities see a denial page naming the identity.
+3. **Pairing code** — first login from a new device requires the current
+   6-digit rotating code. The code is shown live in settings → devices on the
+   host/local dashboard and rotates every 30 seconds (the current code is also
+   printed at server start as a headless fallback). It proves the person can
+   see the host machine's local dashboard, so a stolen allowlist identity can't
+   quietly gain access.
+4. **Device cookie** — successful pairing sets a signed HttpOnly cookie
+   (30-day expiry). Paired devices are listed in settings → devices and can be
+   unpaired at any time.
+
+**There is no LAN mode.** The server never listens on a LAN-reachable
+interface without Tailscale identity enforcement.
+
+### What a paired device can do
+
+Pairing grants the same power as sitting at the terminal: chatting with
+agents, running commands through them, browsing the whole host filesystem
+(anywhere the dreb process can read), and uploading/downloading files. The
+pairing screen states this before the PIN is entered. Every file operation is
+logged server-side.
+
+## Screens
+
+| Screen | What it does |
+|---|---|
+| **Fleet** | Home. Live-first: one grid of every live session at the top — status chip (● running / ◆ needs-attention / ○ idle / ✕ error), project path, activity line, live subagent lines, tasks progress, ctx%, model, last activity. Live cards keep a deterministic order by project path, then session start time; needs-attention cards badge the browser tab without jumping around. Below the grid: past sessions grouped by project, three compact rows per group with an "all N on disk" expander, resume and delete. |
+| **Session view** | Full chat drill-in. Markdown streaming transcript (text, thinking blocks with expand preference, agent-result cards, tool cards with bespoke read/write/edit/bash bodies plus full expandable inputs and markdown-rendered results for markdown-contract tools like subagent/skill/web_fetch/suggest_next, compaction/branch summaries, custom messages), per-message copy, tasks panel, subagent strip, status line with elapsed time plus ■ stop and compaction/retry aborts, and an info bar with cwd, branch, session name, token breakdown, cost/(sub)/daily rollup, ctx%, median tok/s, and a stats popover. Composer supports auto-grow, history, `/` autocomplete from `get_commands`, image attach/paste, queued-message chips with restore-all, steer/follow-up modes, and suggest-next. The ⋯ menu covers export HTML, compact, rename, fork-from-message, loaded context, and tool expand/collapse. Session names update live from manual rename or auto-naming. Extension UI requests (select/confirm/input/editor) render as modals; notifications as toasts. |
+| **Subagent view** | Read-only transcript of a background agent: live events via the RPC relay, hydrated from the agent's on-disk session log (`/subagents/:agentId/messages`) so the view survives browser reloads. Shows the task, streaming output, and tool activity. No composer — subagents can't be steered yet; the parent session controls them. |
+| **Files** | Host-wide browser with places shortcuts (home, /tmp, project roots), breadcrumbs to `/`, new-folder, download, drop-zone/picker upload with explicit collision prompts, and "new session here" on any directory. |
+| **Settings** | Persistent defaults (default model, thinking level, steering/follow-up queue modes, auto-compaction, auto-retry) via `get_settings`/`set_settings` — validation errors are shown verbatim. Dashboard-local preferences (always expand thinking, needs-attention notification permission) live in the browser. Shows the current rotating pairing code on the host/local dashboard, plus the paired-devices list with unpair. |
+| **Pairing** | Remote first-login: identity echo, rotating-code entry, and the security copy explaining what pairing grants. |
+
+### Composer modes
+
+While the agent is streaming, the send button becomes mode-aware:
+
+- **steer** — deliver now: injected into the running turn after the current
+  tool call completes.
+- **follow-up** — queued; delivered after the agent finishes the current work.
+- **■ stop** — abort the current turn. Only visible while streaming.
+
+When the agent is idle, send is a plain prompt.
+
+## Notifications
+
+Needs-attention notifications are delivered through a **service worker**
+(`registration.showNotification()`), not the page-context `Notification`
+constructor — the constructor was removed from Android Chrome (throws
+`Illegal constructor`) and is absent from iOS Safari entirely. The service
+worker handles `notificationclick`: it focuses an open dashboard client and
+navigates to the session that needs attention, or opens one. All browsers still
+get a `◆` tab-title badge fallback when the tab is hidden.
+
+The settings tab exposes a browser-local permission toggle. Gating is unchanged:
+notifications fire only when permission is granted **and** the tab is hidden.
+
+**iOS:** notifications exist only in the **installed PWA** (Add to Home Screen,
+iOS 16.4+) — a plain Safari tab has no Notification API regardless of HTTPS.
+The settings copy explains the install prerequisite when it detects an
+un-installed iOS Safari session. (Note: iOS 17.4+ in the EU dropped standalone
+PWA support — installed PWAs open as Safari tabs and push is unavailable there.)
+
+## Installable PWA + secure context
+
+The dashboard ships a web app manifest (`display: standalone`, theme/background
+colors, icon set), an apple-touch-icon, and service worker registration, so it
+is **installable to the home screen** on Android Chrome and iOS Safari 16.4+ —
+no URL bar, app-like presence, and (on iOS) the only context where
+notifications work.
+
+Service workers and the Notifications API require a **secure context**: HTTPS,
+or `localhost`/`127.0.0.1`. Local mode (`http://127.0.0.1:<port>`) already
+qualifies — install and notifications work with no TLS setup. **Remote mode
+over the tailnet is plain HTTP**, which is not a secure context, so the service
+worker will not register and notifications are unavailable until you enable
+HTTPS. See [Native TLS](#native-tls-remote-https) below.
+
+## Native TLS (remote HTTPS)
+
+For PWA install + notifications from a phone over the tailnet, the dashboard
+terminates TLS itself using certificate files from
+[`tailscale cert`](https://tailscale.com/docs/how-to/set-up-https-certificates)
+(no reverse proxy, **no auth-model change**):
+
+```bash
+dreb dashboard --remote --allow you@example.com \
+  --https --cert /etc/dreb/cert.pem --key /etc/dreb/key.pem
+```
+
+Because the dashboard terminates TLS directly, `req.socket.remoteAddress` is
+still the phone's real tailnet IP — Tailscale identity resolution, the
+allowlist, and pairing all keep working exactly as in plain-HTTP remote mode.
+There is no header trust, no proxy, no weakening of the auth model.
+
+### One-time cert setup with `tailscale cert`
+
+```bash
+# Enable HTTPS certificates in the Tailscale admin console (DNS → HTTPS) first.
+sudo tailscale cert \
+  --cert-file=/etc/dreb/cert.pem \
+  --key-file=/etc/dreb/key.pem \
+  hostname.tailXXXX.ts.net
+sudo chown dreb:dreb /etc/dreb/cert.pem /etc/dreb/key.pem
+sudo chmod 644 /etc/dreb/cert.pem && sudo chmod 600 /etc/dreb/key.pem
+```
+
+Renewal is **manual** — `tailscale cert` certs are Let's Encrypt, 90-day
+lifetime. The dashboard hot-reloads the cert files on change
+(`setSecureContext`), so a renewal that rewrites the files is picked up with
+zero downtime. A daily systemd timer with `--min-validity=720h` (only renews
+when within 30 days of expiry) is the recommended cadence:
+
+```ini
+# /etc/systemd/system/dreb-cert.service
+[Service]
+Type=oneshot
+ExecStart=/usr/bin/tailscale cert --cert-file=/etc/dreb/cert.pem \
+  --key-file=/etc/dreb/key.pem --min-validity=720h hostname.tailXXXX.ts.net
+ExecStartPost=/bin/chown dreb:dreb /etc/dreb/cert.pem /etc/dreb/key.pem
+
+# /etc/systemd/system/dreb-cert.timer
+[Timer]
+OnCalendar=daily
+RandomizedDelaySec=3600
+[Install]
+WantedBy=timers.target
+```
+
+Then open `https://hostname.tailXXXX.ts.net:<port>` on the phone.
+
+> **Hostname note (important):** the `tailscale cert` certificate is issued
+> for your machine's tailnet name (`hostname.tailXXXX.ts.net`) **only** — not
+> `127.0.0.1`, not a raw tailnet IP. When `--https` is enabled the server
+> speaks TLS on every address it binds, so on the host itself:
+>
+> - `https://hostname.tailXXXX.ts.net:<port>` — works, cert validates (resolves
+>   to your tailnet IP). But it's a *remote* request: you go through the full
+>   Tailscale allowlist + pairing flow, not instant loopback local mode.
+> - `https://127.0.0.1:<port>` — the server answers, but the browser rejects
+>   the cert (no `127.0.0.1` SAN) with a scary warning.
+> - `http://127.0.0.1:<port>` — **dead**: the server only speaks TLS now.
+>
+> If you want the host dashboard tab to stay instant (loopback local mode, no
+> pairing, no warning), run a **second** dashboard process without `--https` on
+> a different port for local-only use, and keep the TLS-enabled one for remote.
+> `--https` is primarily for the `--remote` path; pure-local setups don't need
+> it (`127.0.0.1` is already a secure context).
+
+## Subagent observability
+
+Background subagents are first-class:
+
+- Fleet cards show running/done counts and live agent lines.
+- The session view shows a chip strip — one chip per background agent; click
+  to drill into its live transcript.
+- The drill-in view streams the child's events in real time via the
+  `background_agent_event` relay (see [RPC events](rpc.md#event-types)) and
+  hydrates from the agent's on-disk session log on mount, so transcripts
+  survive browser reloads and remain viewable after the agent finishes.
+
+## Responsive behavior
+
+Single breakpoint at 700px. On mobile: fleet cards stack, the session view
+prioritizes read-and-steer (model/thinking switchers collapse into ⋯, tasks
+default collapsed), file table shows name + download only. Composer modes,
+abort, and needs-attention affordances are never reduced away — steering a
+running agent from a phone is the primary remote use case.
+
+## Architecture
+
+```
+Browser dashboard (SolidJS + Vite, tokens.css design system)
+  ⇄ Express server: fail-closed auth, REST, SSE fanout, file API
+  ⇄ RpcClient pool — one `dreb --mode rpc --ui dashboard` child per session
+  ⇄ sessions on disk (~/.dreb/agent/sessions), settings, models
+```
+
+- **SSE catch-up**: events carry sequence IDs; reconnects replay from
+  `Last-Event-ID` against a bounded buffer, falling back to a full state
+  refetch when the gap is too old. Slow clients whose server-side write
+  buffer exceeds a bound are disconnected (loudly logged) and recover via
+  the same reconnect path. Deleting a runtime publishes `runtime_removed`
+  so browsers evict that session's transcript state.
+- **ctx%** comes from the session itself (`get_state.contextUsage` — the same
+  numbers the TUI footer shows), never client-side estimates.
+- **Auto-naming** runs in the shared `AgentSession` layer, so dashboard-created
+  RPC sessions get the same LLM-generated session names as the TUI and update
+  live via `session_name_changed`.
+- **Visual language**: `tokens.css` (`packages/dashboard/src/client/styles/`),
+  the dashboard's design system — IBM Plex Mono, light + dark via
+  `prefers-color-scheme`.
+
+## Limitations (deliberate, sequenced later)
+
+- No session tree screen yet (fork-from-message covers the go-back-and-re-edit
+  loop; the tree design and RPC are ready).
+- No shell passthrough from the browser.
+- No subagent steering (the drill-in view is read-only).
+- Fixed light/dark via `prefers-color-scheme` — no TUI-theme following.

package/docs/development.md

@@ -28,13 +28,16 @@ The script can be run from any directory. dreb keeps the caller's current workin
 
 ```
 packages/
-  ai/           # Model registry, provider APIs, types (@dreb/ai)
-  agent/        # Core agent loop, event system, types (@dreb/agent-core)
-  tui/          # Terminal UI components (@dreb/tui)
-  coding-agent/ # CLI, tools, interactive mode, TUI app (@dreb/coding-agent)
+  ai/              # Model registry, provider APIs, types (@dreb/ai)
+  agent/           # Core agent loop, event system, types (@dreb/agent-core)
+  tui/             # Terminal UI components (@dreb/tui)
+  coding-agent/    # CLI, tools, interactive mode, TUI app (@dreb/coding-agent)
+  semantic-search/ # Semantic code search library + MCP server (@dreb/semantic-search)
+  telegram/        # Telegram bot frontend over RPC (@dreb/telegram)
+  dashboard/       # Web dashboard server/client over RPC (@dreb/dashboard)
 ```
 
-Dependencies flow one way: `coding-agent` → `agent` → `ai`, and `coding-agent` → `tui`. Changes to a dependency require rebuilding downstream packages — `npm run build` handles this automatically in the correct order.
+Dependencies flow one way through the workspace: `coding-agent` depends on `agent`, `ai`, and `tui`; frontend packages such as `telegram`, `dashboard`, and `semantic-search` build on the published workspace APIs instead of creating reverse dependencies. Changes to a dependency require rebuilding downstream packages — `npm run build` handles this automatically in the correct order.
 
 ## Code style