@bytespell/shella 0.2.4 → 0.2.6

package/bundled-plugins/agent/AGENT_SPEC.md

@@ -0,0 +1,611 @@
+# Agent Plugin UI Specification
+
+This document specifies how the agent plugin UI should handle all RPC events from the pi-agent and render the conversation.
+
+## Table of Contents
+
+1. [Architecture Overview](#architecture-overview)
+2. [State Management](#state-management)
+3. [Event Handling](#event-handling)
+4. [Message Rendering](#message-rendering)
+5. [Streaming Behavior](#streaming-behavior)
+6. [Tool Execution](#tool-execution)
+7. [User Interactions](#user-interactions)
+8. [Edge Cases](#edge-cases)
+9. [Components](#components)
+
+---
+
+## Architecture Overview
+
+### Data Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         WebSocket                                │
+│                                                                 │
+│   Client (App.tsx)  ◄────────────────────►  Server (server.js)  │
+│         │                                          │            │
+│         │                                          │            │
+│         ▼                                          ▼            │
+│   React State                              pi --mode rpc        │
+│   - messages[]                             (stdio JSON lines)   │
+│   - sessionState                                                │
+│   - activeToolCalls                                             │
+│   - streamingContent                                            │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Key Principle
+
+**Messages are the source of truth.** The UI builds its render tree from the `messages[]` array. Streaming updates modify the last message in-place. Tool executions are tracked separately only for showing progress indicators.
+
+---
+
+## State Management
+
+### Primary State
+
+```typescript
+interface AppState {
+  // Connection
+  status: 'connecting' | 'connected' | 'disconnected' | 'error'
+  error: string | null
+  currentCwd: string | null
+
+  // Session
+  sessionState: SessionState | null
+  sessionStats: SessionStats | null
+
+  // Messages - THE source of truth for rendering
+  messages: AgentMessage[]
+
+  // Streaming indicators (not for rendering content, just for UI feedback)
+  isStreaming: boolean           // Is the agent currently processing?
+  streamingMessageIndex: number | null  // Which message is being streamed?
+
+  // Active tool calls (for progress indicators during execution)
+  activeToolCalls: Map<string, ActiveToolCall>
+
+  // UI state
+  availableModels: AvailableModel[]
+  pendingExtensionRequest: ExtensionUIRequest | null
+}
+
+interface ActiveToolCall {
+  toolCallId: string
+  toolName: string
+  args: Record<string, unknown>
+  status: 'running' | 'done' | 'error'
+  partialOutput: string | null  // Streaming output for bash/etc
+}
+
+interface SessionState {
+  model?: Model
+  thinkingLevel: ThinkingLevel
+  isStreaming: boolean
+  isCompacting: boolean
+  steeringMode: 'all' | 'one-at-a-time'
+  followUpMode: 'all' | 'one-at-a-time'
+  sessionFile?: string
+  sessionId: string
+  autoCompactionEnabled: boolean
+  messageCount: number
+  pendingMessageCount: number  // Queued steering/follow-up messages
+}
+```
+
+### Message Types
+
+```typescript
+type AgentMessage =
+  | UserMessage
+  | AssistantMessage
+  | ToolResultMessage
+  | BashExecutionMessage
+  | CompactionSummaryMessage
+  | CustomMessage
+
+interface UserMessage {
+  role: 'user'
+  content: string | ContentBlock[]
+  timestamp: number
+}
+
+interface AssistantMessage {
+  role: 'assistant'
+  content: ContentBlock[]  // text, thinking, toolCall blocks
+  model: string
+  usage: Usage
+  stopReason: 'stop' | 'length' | 'toolUse' | 'error' | 'aborted'
+  timestamp: number
+}
+
+interface ToolResultMessage {
+  role: 'toolResult'
+  toolCallId: string
+  toolName: string
+  content: ContentBlock[]
+  details?: unknown  // Tool-specific display data
+  isError: boolean
+  timestamp: number
+}
+
+type ContentBlock =
+  | { type: 'text'; text: string }
+  | { type: 'thinking'; thinking: string }
+  | { type: 'toolCall'; id: string; name: string; arguments: Record<string, unknown> }
+  | { type: 'image'; data: string; mimeType: string }
+```
+
+---
+
+## Event Handling
+
+### Connection Events
+
+| Event | Action |
+|-------|--------|
+| `ready` | Set status='connected', set cwd if provided, request initial state |
+| `cwd_changed` | Update cwd, clear messages (new session in new directory) |
+| `error` | Display error message |
+| `process_exit` | Show reconnection UI or error |
+
+### Agent Lifecycle Events
+
+| Event | Action |
+|-------|--------|
+| `agent_start` | Set isStreaming=true, clear activeToolCalls |
+| `agent_end` | Set isStreaming=false, clear activeToolCalls, request stats |
+
+### Message Events
+
+| Event | Action |
+|-------|--------|
+| `message_start` | Append message to messages[], set streamingMessageIndex if assistant |
+| `message_update` | Update message at streamingMessageIndex with new content |
+| `message_end` | Clear streamingMessageIndex |
+
+**Important:** `message_update` includes `assistantMessageEvent` with granular streaming info:
+- `text_delta` - Append text to current text block
+- `thinking_delta` - Append to thinking block
+- `toolcall_end` - Tool call block complete
+- `done` - Message complete
+
+### Tool Execution Events
+
+| Event | Action |
+|-------|--------|
+| `tool_execution_start` | Add to activeToolCalls with status='running' |
+| `tool_execution_update` | Update partialOutput in activeToolCalls |
+| `tool_execution_end` | Update status='done' or 'error', keep until toolResult message arrives |
+
+**When `message_start` arrives with role='toolResult':**
+- Remove corresponding entry from activeToolCalls (it's now in messages)
+
+### Response Events
+
+| Event | Action |
+|-------|--------|
+| `response` to `get_state` | Update sessionState |
+| `response` to `get_messages` | Set messages (only on initial load, not during streaming) |
+| `response` to `get_session_stats` | Update sessionStats |
+| `response` to `get_available_models` | Update availableModels |
+
+### Extension UI Events
+
+| Event | Action |
+|-------|--------|
+| `extension_ui_request` | Show appropriate dialog/input, send response back |
+
+---
+
+## Message Rendering
+
+### Render Order
+
+Messages are rendered in array order. Each message type has specific rendering:
+
+```
+┌─────────────────────────────────────────┐
+│ User message (right-aligned bubble)     │
+├─────────────────────────────────────────┤
+│ Assistant text (left-aligned bubble)    │
+│   - Render markdown                     │
+│   - Show thinking in collapsible        │
+├─────────────────────────────────────────┤
+│ Tool Call Card                          │
+│   - Show tool name + args               │
+│   - While executing: show progress      │
+├─────────────────────────────────────────┤
+│ Tool Result Card                        │
+│   - For bash: show $ command + output   │
+│   - For others: show formatted result   │
+│   - Error state: red styling            │
+├─────────────────────────────────────────┤
+│ Assistant text (continuation)           │
+│   - Streaming cursor if active          │
+└─────────────────────────────────────────┘
+```
+
+### Splitting Assistant Messages
+
+Assistant messages may contain mixed content (text + toolCall + more text). Split for display:
+
+```typescript
+function splitAssistantContent(content: ContentBlock[]): RenderItem[] {
+  const items: RenderItem[] = []
+  let textBuffer: ContentBlock[] = []
+
+  for (const block of content) {
+    if (block.type === 'toolCall') {
+      // Flush text buffer
+      if (textBuffer.length > 0) {
+        items.push({ type: 'text-chunk', blocks: textBuffer })
+        textBuffer = []
+      }
+      items.push({ type: 'tool-call', block })
+    } else {
+      textBuffer.push(block)
+    }
+  }
+
+  // Flush remaining text
+  if (textBuffer.length > 0) {
+    items.push({ type: 'text-chunk', blocks: textBuffer })
+  }
+
+  return items
+}
+```
+
+### Content Block Rendering
+
+| Block Type | Rendering |
+|------------|-----------|
+| `text` | Markdown with syntax highlighting. Use streaming-capable renderer. |
+| `thinking` | Collapsible "Thinking..." section, muted styling |
+| `toolCall` | Tool call card showing name + arguments (only during streaming before result) |
+| `image` | Inline image |
+
+### Tool Result Rendering
+
+| Tool | Rendering |
+|------|-----------|
+| `bash` / `Bash` | Mini-terminal: `$ command` header + scrollable output |
+| `Read` | File content with path header |
+| `Write` / `Edit` | Diff view component |
+| `Grep` / `Glob` | Formatted list of matches/files |
+| Other | JSON-formatted arguments + result |
+
+---
+
+## Streaming Behavior
+
+### Text Streaming
+
+1. On `message_start` (assistant): Add message to array, set streamingMessageIndex
+2. On `message_update`: Replace message at streamingMessageIndex
+3. Show pulsing cursor after last text in streaming message
+4. On `message_end`: Clear streamingMessageIndex, cursor disappears
+
+### Tool Execution Streaming
+
+1. `tool_execution_start`: Add to activeToolCalls, show card with spinner
+2. `tool_execution_update`: Update partialOutput, show in card (for bash output)
+3. `tool_execution_end`: Mark complete, show success/error indicator
+4. `message_start` (toolResult): Move from activeToolCalls to messages
+
+**Visual transition:** The tool card should smoothly transition from "running" state (in activeToolCalls) to "complete" state (in messages) without flashing or jumping.
+
+### Render Priority
+
+During streaming, render in this order:
+1. All messages from `messages[]` (split as needed)
+2. Active tool calls from `activeToolCalls` (only those not yet in messages)
+3. (Streaming cursor shown inline in last assistant message)
+
+---
+
+## Tool Execution
+
+### Tool Call Card (During Execution)
+
+```
+┌────────────────────────────────────────┐
+│ ● bash                        Running  │
+│ $ ls -la                               │
+├────────────────────────────────────────┤
+│ total 48                               │
+│ drwxr-xr-x  12 user staff  384 ...     │
+│ ...                                    │
+│ (streaming output)                     │
+└────────────────────────────────────────┘
+```
+
+- Yellow pulsing dot while running
+- Green dot when complete
+- Red dot on error
+- Show command for bash tools
+- Stream partial output as it arrives
+
+### Tool Result Card (After Completion)
+
+```
+┌────────────────────────────────────────┐
+│ ● $ ls -la                             │
+├────────────────────────────────────────┤
+│ total 48                               │
+│ drwxr-xr-x  12 user staff  384 ...     │
+│ ...                                    │
+│ (full output, scrollable)              │
+└────────────────────────────────────────┘
+```
+
+- Green dot for success, red for error
+- Command in header for bash
+- Scrollable output area (max-height with overflow)
+- Error output in red text
+
+### Special Tool Rendering
+
+**Edit/Write Tools (Diff View):**
+```
+┌────────────────────────────────────────┐
+│ Edit: src/App.tsx                      │
+├────────────────────────────────────────┤
+│ - old line                             │
+│ + new line                             │
+│   unchanged line                       │
+└────────────────────────────────────────┘
+```
+
+**Read Tool:**
+```
+┌────────────────────────────────────────┐
+│ Read: package.json                     │
+├────────────────────────────────────────┤
+│ {                                      │
+│   "name": "my-app",                    │
+│   ...                                  │
+│ }                                      │
+└────────────────────────────────────────┘
+```
+
+---
+
+## User Interactions
+
+### Sending Messages
+
+**Normal prompt:**
+```typescript
+ws.send({ type: 'prompt', message: text })
+```
+
+**With images:**
+```typescript
+ws.send({ type: 'prompt', message: text, images: [{ type: 'image', data: base64, mimeType: 'image/png' }] })
+```
+
+### Steering (Interrupt)
+
+When agent is streaming and user sends a message:
+```typescript
+ws.send({ type: 'steer', message: text })
+```
+
+- Interrupts current tool execution
+- Message is injected before next LLM turn
+- Show indicator that message was queued for steering
+
+### Follow-Up (Queue)
+
+Queue a message to run after agent finishes:
+```typescript
+ws.send({ type: 'follow_up', message: text })
+```
+
+- Does not interrupt
+- Show indicator that message is queued
+- Show pending count from sessionState.pendingMessageCount
+
+### Abort
+
+Stop agent execution:
+```typescript
+ws.send({ type: 'abort' })
+```
+
+- Show "Stop" button when isStreaming
+- Cancel current tool execution
+- Agent will emit `agent_end`
+
+### UI Indicators
+
+| State | Indicator |
+|-------|-----------|
+| Agent streaming | Pulsing cursor, "Stop" button |
+| Tool running | Yellow spinner on tool card |
+| Message queued | Badge showing pending count |
+| Compacting | "Compacting..." status |
+| Error | Red error banner |
+
+---
+
+## Edge Cases
+
+### 1. Multiple Tool Calls in One Message
+
+Assistant may request multiple tools at once:
+```typescript
+{
+  role: 'assistant',
+  content: [
+    { type: 'text', text: 'I will read both files...' },
+    { type: 'toolCall', id: 'call_1', name: 'Read', arguments: { path: 'a.txt' } },
+    { type: 'toolCall', id: 'call_2', name: 'Read', arguments: { path: 'b.txt' } }
+  ]
+}
+```
+
+**Handling:**
+- Split into: text chunk, tool card 1, tool card 2
+- Tool results arrive as separate `toolResult` messages
+- Match by `toolCallId`
+
+### 2. Steering Mid-Tool-Execution
+
+User steers while tool is running:
+- Tool execution continues until next checkpoint
+- Steering message is queued
+- After tool completes, steering is processed
+- May result in remaining tool calls being skipped
+
+### 3. Auto-Compaction
+
+Events: `auto_compaction_start`, `auto_compaction_end`
+
+**Handling:**
+- Show "Compacting context..." indicator
+- On completion, a `compactionSummary` message may be added
+- Older messages may be removed from context (but kept in history)
+
+### 4. Auto-Retry
+
+Events: `auto_retry_start`, `auto_retry_end`
+
+**Handling:**
+- Show "Retrying... (attempt N of M)"
+- Show countdown timer if delay > 1s
+- On success, continue normally
+- On final failure, show error
+
+### 5. Extension UI Requests
+
+Agent may request user input via `extension_ui_request`:
+
+| Method | UI |
+|--------|-----|
+| `select` | Dropdown/radio buttons |
+| `confirm` | Yes/No dialog |
+| `input` | Text input |
+| `editor` | Multi-line text editor |
+| `notify` | Toast notification |
+
+**Response:**
+```typescript
+ws.send({
+  type: 'extension_ui_response',
+  id: request.id,
+  value: userInput  // or { cancelled: true }
+})
+```
+
+### 6. Connection Loss
+
+- Show disconnected state
+- Auto-reconnect with exponential backoff
+- On reconnect, request `get_state` and `get_messages` to sync
+
+### 7. CWD Change
+
+- Kills pi process, respawns in new directory
+- Clears messages (new session)
+- Show brief "Switching directory..." indicator
+
+### 8. Session Switch
+
+User may switch to different session file:
+- Current conversation is saved
+- New session loaded
+- Messages replaced with new session's history
+
+### 9. Empty Responses
+
+Assistant may return empty text (only tool calls, or aborted):
+- Don't render empty text bubbles
+- Still show tool calls if present
+
+### 10. Long-Running Tools
+
+Some tools take a long time (build, test):
+- Show elapsed time indicator
+- Stream partial output if available
+- Allow abort via "Stop" button
+
+---
+
+## Components
+
+### Required Components
+
+1. **MessageBubble** - User/assistant text messages with markdown
+2. **ToolCallCard** - Tool execution progress (running state)
+3. **ToolResultCard** - Tool result display (completed state)
+4. **BashResultCard** - Specialized for bash with command header
+5. **DiffView** - For Edit/Write tool results
+6. **ThinkingBlock** - Collapsible thinking content
+7. **StreamingCursor** - Pulsing cursor for active streaming
+8. **QueueIndicator** - Shows pending message count
+9. **StatusBar** - Session stats, model, connection status
+10. **DirectoryPicker** - CWD selection
+11. **ExtensionDialog** - Generic dialog for extension UI requests
+
+### Component Hierarchy
+
+```
+<App>
+  <Header>
+    <DirectoryPicker />
+    <SessionStats />
+    <StatusIndicator />
+    <SettingsMenu />
+  </Header>
+
+  <MessageList>
+    {messages.map(msg => {
+      if (msg.role === 'user') return <UserBubble />
+      if (msg.role === 'assistant') return <AssistantMessage />
+      if (msg.role === 'toolResult') return <ToolResultCard />
+      ...
+    })}
+
+    {activeToolCalls.map(tool => (
+      <ToolCallCard status="running" />
+    ))}
+  </MessageList>
+
+  <InputArea>
+    <Textarea />
+    <SendButton /> or <StopButton />
+    {pendingCount > 0 && <QueueIndicator count={pendingCount} />}
+  </InputArea>
+
+  {extensionRequest && <ExtensionDialog />}
+</App>
+```
+
+---
+
+## Implementation Notes
+
+### Performance
+
+1. **Virtualization:** For long conversations, consider virtualizing the message list
+2. **Memoization:** Memoize message components to avoid re-renders
+3. **Streaming:** Use streaming-capable markdown renderer (e.g., streamdown)
+4. **Debounce:** Debounce rapid `message_update` events if needed
+
+### Accessibility
+
+1. Keyboard navigation for message list
+2. Screen reader announcements for new messages
+3. Focus management for dialogs
+4. High contrast support for tool status indicators
+
+### Mobile
+
+1. Responsive layout for smaller screens
+2. Touch-friendly buttons and controls
+3. Swipe gestures for common actions

package/bundled-plugins/agent/README.md

@@ -0,0 +1,7 @@
+# Agent Plugin
+
+A web UI for AI coding agents. Point it at any directory and start a conversation—the agent can read files, write code, run commands, and iterate on your codebase. Sessions persist across restarts, so you can pick up where you left off.
+
+**Usage:** Split a panel, select "Agent", choose a working directory, and start prompting. Switch between sessions or start new ones from the session picker. Each panel instance maintains its own independent session.
+
+**Vision:** Your AI pair programmer, always available in a panel alongside your terminal and editor. No context switching to a separate app—just split, prompt, and ship.

package/bundled-plugins/agent/components.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "radix-vega",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/index.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "menuColor": "default",
+  "menuAccent": "subtle",
+  "registries": {}
+}

package/bundled-plugins/agent/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

package/bundled-plugins/agent/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en" class="dark">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Agent</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>