mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/087-permission-modes.rispec.md

@@ -0,0 +1,145 @@
+# RISE-087: Permission Modes
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/087-permission-modes.rispec.md
+
+## Creative Intent
+
+mia-code provides three distinct permission action modes that govern how each rule resolves at runtime. "Allow" is silent trust. "Deny" is silent refusal. "Ask" is a conversation — the agent pauses, presents details, and the user decides. Each mode serves a different risk profile. Together they let developers build nuanced permission policies where safe operations flow freely, dangerous ones are blocked, and everything in between gets human judgment.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has only two effective modes: full trust (`--yolo`) or full prompting (default)
+- There is no "deny" mode — every action either proceeds or is prompted
+- When prompted, the user can only say yes or no for that single occurrence
+- No mechanism to escalate a single "yes" into a persistent "always allow" rule
+- No mechanism to escalate a single "no" into a persistent "never allow" rule
+- The agent receives no structured feedback when an action is denied — it may retry indefinitely
+
+**Desired State:**
+- Three modes: "allow" (silent proceed), "deny" (silent block with reason), "ask" (interactive prompt)
+- "Ask" mode offers five response options: y, n, always, never, session
+- "Always" and "never" responses create persistent session-scoped rules (RISE-086 layer 5)
+- "Session" response allows for the rest of the session without creating a permanent rule
+- Deny mode sends a structured denial message to the agent so it can adapt
+- The agent gracefully handles denials — suggests alternatives or asks the user to adjust permissions
+
+## Desired Outcome Definition
+
+Each permission rule action resolves through one of three modes. Allow and deny are non-interactive. Ask pauses execution for user input and supports five response types that range from one-time decisions to persistent session rules. The agent receives clear feedback on denials and can adapt its behavior.
+
+## Natural Language Functional Description
+
+### Allow Mode
+
+When a rule resolves to `"allow"`:
+
+1. The action proceeds immediately with no user interaction
+2. No visual indicator is shown (silent operation)
+3. The tool executes and returns its result to the agent
+4. Logging records the permission check: `permission.allowed: write src/foo.test.ts (rule #3, project)`
+
+Allow mode is appropriate for: reading files, running safe commands (linters, tests), writing to well-understood paths, asking questions.
+
+### Deny Mode
+
+When a rule resolves to `"deny"`:
+
+1. The action is blocked immediately with no user interaction
+2. The agent receives a structured denial message:
+   ```
+   Permission denied: [tool] on [path/command]
+   Reason: [rule description from matching rule]
+   Source: [rule source layer]
+   ```
+3. The tool returns an error result, not a thrown exception
+4. The agent should interpret the denial and adapt — suggest alternatives, ask the user, or proceed differently
+5. Logging records: `permission.denied: bash "rm -rf /" (rule #4, global)`
+
+Deny messages are designed to be informative. The agent receives enough context to understand *why* the action was blocked and *what rule* caused it. This enables the agent to explain the denial to the user or try an alternative approach.
+
+### Ask Mode
+
+When a rule resolves to `"ask"`:
+
+1. Execution pauses
+2. The user is presented with the action details:
+   ```
+   🔐 Permission required: write
+   Target: src/components/Header.tsx
+   Content preview: [first 5 lines of content]
+   
+   Allow? (y)es / (n)o / (a)lways / ne(v)er / (s)ession
+   ```
+3. The user responds with one of five options:
+
+| Response  | Key | Behavior |
+|-----------|-----|----------|
+| Yes       | `y` | Allow this one action, continue. No rule created. |
+| No        | `n` | Deny this one action, continue. No rule created. Agent receives denial message. |
+| Always    | `a` | Allow this action AND create a session-scoped allow rule for this permission+pattern. Future matching actions auto-allow. |
+| Never     | `v` | Deny this action AND create a session-scoped deny rule for this permission+pattern. Future matching actions auto-deny. |
+| Session   | `s` | Allow this action for the rest of the session. Creates a temporary allow rule that is discarded on session end. Functionally similar to "always" but semantically different — it signals "I trust this for now." |
+
+### Always / Never Rule Creation
+
+When a user responds "always" to a write permission on `src/**/*.ts`:
+
+```json
+{"permission": "write", "pattern": "src/**/*.ts", "action": "allow", "source": "session"}
+```
+
+This rule is prepended to the session layer (RISE-086). All subsequent writes to TypeScript files under `src/` will silently allow without prompting.
+
+When a user responds "never" to a bash permission on `rm *`:
+
+```json
+{"permission": "bash", "pattern": "rm *", "action": "deny", "source": "session"}
+```
+
+All subsequent bash commands matching `rm *` will silently deny.
+
+### Agent Denial Handling
+
+When the agent receives a denial, it should:
+
+1. Acknowledge the denial in its response to the user
+2. Explain what it was trying to do and why it was blocked
+3. Suggest alternatives: different approach, different path, or ask the user to adjust permissions
+4. Not retry the same denied action immediately — this wastes tokens and annoys users
+
+Example agent response after denial:
+> I tried to delete the old config file but was blocked by a permission rule. I can either leave it in place or you can adjust permissions with `/permissions`. Would you like me to try a different approach?
+
+### Visual Presentation
+
+The ask prompt is rendered with clear formatting:
+
+- 🔐 emoji prefix for visual distinctiveness
+- Permission type and target are highlighted
+- For file writes, a content preview shows the first few lines
+- For bash commands, the full command string is shown
+- Response options are shown with keyboard shortcuts
+
+## Supporting Structures
+
+- **Permission Rules (RISE-084)** defines the rule objects that specify actions
+- **Permission Glob Patterns (RISE-085)** defines pattern matching that scopes rules
+- **Permission Merging (RISE-086)** defines how "always"/"never" responses become session rules
+- **Event Bus (RISE-002)** emits permission events for external clients (RISE-090, RISE-091)
+- **Named Error System (RISE-006)** provides PermissionDeniedError for deny mode
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Progressive Trust Building:**
+A developer starts with all "ask" defaults. The agent requests write access to a test file — the developer responds "always." Next, a bash command for `npm test` — "always." Over a session, the developer builds up a set of trusted operations. The ask prompts become rarer as trust accumulates.
+
+**Scenario 2 — Guarded Exploration:**
+The agent tries to read `.env` — denied by a global rule. The agent reports: "I can't read .env due to permission rules. Could you paste the relevant environment variable values?" The developer shares only what's needed. Security is maintained through structured denial and agent adaptation.
+
+**Scenario 3 — Session-Scoped Experimentation:**
+A developer responds "session" to a write prompt. For the rest of this session, similar writes proceed silently. On the next session, the permission resets to "ask." This lets developers experiment with trust levels without permanent consequences.
+
+**Scenario 4 — Remote Permission Approval:**
+A developer drives mia-code remotely via the HTTP API (RISE-088). The ask prompt is serialized as a permission event over WebSocket (RISE-090). The developer approves from their phone. The agent continues on the workstation. Permission modes work identically regardless of interface.

package/rispecs/borrowed_from_opencode/088-http-api-server.rispec.md

@@ -0,0 +1,165 @@
+# RISE-088: HTTP API Server
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/088-http-api-server.rispec.md
+
+## Creative Intent
+
+mia-code exposes its full capabilities through an HTTP API server, enabling any program — web UIs, desktop apps, mobile clients, CI scripts, custom bots — to create sessions, send messages, manage tools, and control permissions over standard HTTP. The server transforms mia-code from a terminal-only tool into a platform that any interface can drive. A developer starts the server on their workstation and connects from anywhere.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code runs exclusively as a CLI process — interaction requires a terminal
+- No HTTP endpoints exist; external programs cannot interact with a running agent
+- Building a web UI or desktop app requires reimplementing the entire agent stack
+- CI/CD integration means shelling out to the CLI and parsing stdout — fragile and limited
+- Multi-client access to the same session is impossible
+- No authentication mechanism exists for remote access
+
+**Desired State:**
+- A lightweight HTTP server exposes mia-code's capabilities as JSON endpoints
+- Endpoints are organized by domain: sessions, messages, tools, config, permissions, projects
+- The server starts via `mia-code serve --port 4096` or auto-starts in background mode
+- Optional authentication via password protects remote access
+- CORS is configurable for web client access
+- Standardized error responses enable reliable client error handling
+- The server is the foundation for web UI, desktop app, mobile app, and API automation
+
+## Desired Outcome Definition
+
+Running `mia-code serve` starts an HTTP server that accepts JSON requests and returns JSON responses. Any HTTP client can create sessions, send messages, list tools, read configuration, and manage permissions. The server is lightweight, secure by default, and designed for both local and remote access.
+
+## Natural Language Functional Description
+
+### Server Startup
+
+```bash
+mia-code serve                         # start on default port 4096
+mia-code serve --port 8080             # custom port
+mia-code serve --password mysecret     # require authentication
+mia-code serve --host 0.0.0.0          # bind to all interfaces (for remote access)
+```
+
+The server binds to `127.0.0.1` by default (localhost only). Use `--host 0.0.0.0` for remote access. Environment variable `MIA_CODE_SERVER_PASSWORD` sets the password without command-line exposure.
+
+### Framework Choice
+
+The server uses Hono — a lightweight, fast HTTP framework with TypeScript-first design. Hono provides routing, middleware, and request validation with minimal overhead. Alternative: Express if Hono proves unsuitable.
+
+### API Endpoints
+
+**Sessions** (`/api/session`):
+- `GET    /api/session` — list all sessions (pagination, filtering by status)
+- `POST   /api/session` — create a new session `{title, directory, model?}`
+- `GET    /api/session/:id` — get session details with message history
+- `DELETE /api/session/:id` — archive a session
+- `PATCH  /api/session/:id` — update session metadata (title, model)
+
+**Messages** (`/api/message`):
+- `POST   /api/session/:id/message` — send a user message `{content: string}`
+- `GET    /api/session/:id/message` — list messages (pagination, cursor-based)
+- `GET    /api/session/:id/message/:msgId` — get a specific message
+
+**Tools** (`/api/tool`):
+- `GET    /api/tool` — list available tools with descriptions and schemas
+- `POST   /api/tool/:name/execute` — execute a tool directly `{parameters: object}`
+- `GET    /api/tool/:name` — get tool details and parameter schema
+
+**Configuration** (`/api/config`):
+- `GET    /api/config` — get current effective configuration
+- `PATCH  /api/config` — update configuration values `{key: value}`
+
+**Permissions** (`/api/permission`):
+- `GET    /api/permission` — get effective merged permission rules
+- `POST   /api/permission/respond` — respond to a pending permission prompt `{requestId, response}`
+- `POST   /api/permission/reset` — reset session-scoped permissions
+
+**Project** (`/api/project`):
+- `GET    /api/project` — get project information (root, git status, file count)
+
+**System** (`/api`):
+- `GET    /api/health` — server health: uptime, version, active sessions
+- `GET    /api/openapi.json` — OpenAPI specification (RISE-089)
+
+### Authentication
+
+When a password is configured, all requests must include it:
+
+```
+Authorization: Basic base64(username:password)
+```
+
+Username can be anything (conventionally "mia-code"). Unauthenticated requests receive `401 Unauthorized`. The `/api/health` endpoint is always public (allows connection testing).
+
+### Error Responses
+
+All errors follow a consistent structure:
+
+```json
+{
+  "error": {
+    "name": "SessionNotFoundError",
+    "message": "Session abc-123 does not exist",
+    "code": 404
+  }
+}
+```
+
+Error names map to the Named Error System (RISE-006). HTTP status codes: 400 (bad request), 401 (unauthorized), 404 (not found), 422 (validation error), 500 (internal error).
+
+### CORS Configuration
+
+CORS headers are configurable in the server config:
+
+```json
+{
+  "server": {
+    "cors": {
+      "origins": ["http://localhost:3000", "https://mia-code.app"],
+      "methods": ["GET", "POST", "PATCH", "DELETE"],
+      "credentials": true
+    }
+  }
+}
+```
+
+Default: allow `localhost` origins only.
+
+### Request Validation
+
+All request bodies are validated against Zod schemas. Invalid requests receive a 422 response with detailed validation errors:
+
+```json
+{
+  "error": {
+    "name": "ValidationError",
+    "message": "Invalid request body",
+    "code": 422,
+    "details": [{"path": "content", "message": "Required"}]
+  }
+}
+```
+
+## Supporting Structures
+
+- **Client-Server Architecture (RISE-001)** provides the architectural foundation this server implements
+- **OpenAPI Spec Generation (RISE-089)** auto-generates API documentation from these endpoints
+- **WebSocket Support (RISE-090)** adds real-time bidirectional communication alongside HTTP
+- **SSE Streaming (RISE-091)** adds server-sent events for message streaming
+- **mDNS Discovery (RISE-092)** enables automatic discovery of the running server
+- **Zod Schema Validation (RISE-005)** validates all request/response payloads
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Web UI Dashboard:**
+A React web app connects to the HTTP API. It lists sessions in a sidebar, shows message history in the main panel, and sends new messages via POST. The web app provides a richer interface than the terminal — syntax highlighting, file previews, tool execution visualizations.
+
+**Scenario 2 — CI/CD Agent:**
+A GitHub Actions workflow starts the server, sends a prompt via `curl -X POST /api/session/:id/message`, and polls for the response. The agent reviews a PR diff and posts its analysis as a comment. No terminal, no human — pure API automation.
+
+**Scenario 3 — Multi-Client Collaboration:**
+Two developers connect to the same server. One drives the agent from a web UI, the other monitors from a terminal client. Both see the same messages in real-time via SSE (RISE-091). Permission prompts route to whichever client responds first.
+
+**Scenario 4 — Remote Workstation:**
+A developer runs `mia-code serve --host 0.0.0.0 --password secret` on their powerful desktop. They connect from a laptop on the same network via `http://desktop:4096/api`. The agent runs on the desktop's 64GB RAM while the developer works from a lightweight notebook.

package/rispecs/borrowed_from_opencode/089-openapi-spec-generation.rispec.md

@@ -0,0 +1,164 @@
+# RISE-089: OpenAPI Spec Generation
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/089-openapi-spec-generation.rispec.md
+
+## Creative Intent
+
+mia-code auto-generates an OpenAPI 3.0 specification from its HTTP API routes, turning route definitions into living documentation. Every endpoint, every request body, every response shape is derived from the same Zod schemas that validate runtime data. Documentation cannot drift from implementation because they share a single source of truth. The spec enables client SDK generation, Swagger UI exploration, and automated testing — all without manual documentation effort.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has no HTTP API and therefore no API documentation
+- When an API is added (RISE-088), documentation will need to be written and maintained
+- Manual API documentation drifts from implementation — endpoints change, docs stay stale
+- No mechanism exists to generate client SDKs for TypeScript, Python, or other languages
+- Zod schemas exist for internal validation but are not exposed as machine-readable contracts
+
+**Desired State:**
+- Each API route is annotated with metadata: path, method, request schema, response schema, description, tags
+- Zod schemas are automatically converted to JSON Schema for OpenAPI compatibility
+- The OpenAPI specification is generated at build time and also served live at `/api/openapi.json`
+- Swagger UI is available at `/api/docs` for interactive API exploration
+- The spec is the source for auto-generating the TypeScript SDK (RISE-093)
+- API versioning tracks mia-code's version number
+
+## Desired Outcome Definition
+
+The HTTP API server serves a complete OpenAPI 3.0 specification at `/api/openapi.json`. The spec is auto-generated from route definitions and Zod schemas. Developers and tools can consume it for documentation, SDK generation, testing, and validation. No manual spec maintenance is needed.
+
+## Natural Language Functional Description
+
+### Route Annotation
+
+Each API route carries metadata alongside its handler:
+
+```typescript
+const createSession = route({
+  method: "POST",
+  path: "/api/session",
+  operationId: "createSession",
+  summary: "Create a new agent session",
+  description: "Creates a new session with the specified configuration. Returns the session ID and initial state.",
+  tags: ["sessions"],
+  request: z.object({
+    title: z.string().optional(),
+    directory: z.string(),
+    model: z.string().optional(),
+  }),
+  responses: {
+    200: z.object({
+      id: z.string(),
+      title: z.string(),
+      createdAt: z.string().datetime(),
+    }),
+    400: ErrorResponseSchema,
+    401: ErrorResponseSchema,
+  },
+})
+```
+
+### Zod-to-JSON-Schema Conversion
+
+Zod schemas are converted to JSON Schema using `zod-to-json-schema` or an equivalent library. Conversion handles:
+
+- Primitive types: `z.string()` → `{"type": "string"}`
+- Objects: `z.object({...})` → `{"type": "object", "properties": {...}}`
+- Arrays: `z.array(z.string())` → `{"type": "array", "items": {"type": "string"}}`
+- Enums: `z.enum(["a", "b"])` → `{"type": "string", "enum": ["a", "b"]}`
+- Optional fields: `z.string().optional()` → property not in `required` array
+- Descriptions: `z.string().describe("User's name")` → `{"description": "User's name"}`
+- Unions, intersections, and refinements mapped to appropriate JSON Schema constructs
+
+### OpenAPI Spec Structure
+
+The generated specification follows OpenAPI 3.0:
+
+```yaml
+openapi: "3.0.3"
+info:
+  title: "mia-code API"
+  version: "1.0.0"          # matches mia-code package version
+  description: "HTTP API for programmatic control of mia-code"
+servers:
+  - url: "http://localhost:4096"
+paths:
+  /api/session:
+    post:
+      operationId: createSession
+      tags: [sessions]
+      summary: Create a new agent session
+      requestBody:
+        content:
+          application/json:
+            schema: { ... }   # from Zod
+      responses:
+        "200": { ... }        # from Zod
+        "400": { ... }
+components:
+  schemas:
+    Session: { ... }
+    Message: { ... }
+    Error: { ... }
+  securitySchemes:
+    basicAuth:
+      type: http
+      scheme: basic
+```
+
+### Tags
+
+Tags group endpoints by domain for organized documentation:
+
+| Tag          | Endpoints                    |
+|--------------|------------------------------|
+| sessions     | `/api/session/*`             |
+| messages     | `/api/session/:id/message/*` |
+| tools        | `/api/tool/*`                |
+| config       | `/api/config/*`              |
+| permissions  | `/api/permission/*`          |
+| project      | `/api/project/*`             |
+| system       | `/api/health`, `/api/openapi.json` |
+
+### Serving the Spec
+
+- `GET /api/openapi.json` — returns the generated OpenAPI spec as JSON
+- `GET /api/docs` — serves Swagger UI pointed at the spec (optional, dev mode only)
+- Build-time generation: `mia-code build:openapi` writes the spec to `dist/openapi.json`
+
+### Versioning
+
+The API version in the spec matches the mia-code package version from `package.json`. Breaking API changes increment the major version. The version is also included in response headers: `X-MiaCode-Version: 1.0.0`.
+
+### Response Schemas
+
+Every endpoint defines response schemas for common status codes:
+
+- `200` — success response with typed body
+- `400` — bad request (malformed input)
+- `401` — unauthorized (missing or invalid credentials)
+- `404` — resource not found
+- `422` — validation error (input fails schema validation)
+- `500` — internal server error
+
+## Supporting Structures
+
+- **HTTP API Server (RISE-088)** defines the routes this spec documents
+- **Zod Schema Validation (RISE-005)** provides the schemas converted to JSON Schema
+- **JavaScript SDK (RISE-093)** is auto-generated from this OpenAPI spec
+- **Named Error System (RISE-006)** defines the error response shapes documented in the spec
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Swagger UI Exploration:**
+A developer visits `http://localhost:4096/api/docs` and sees all endpoints organized by tag. They expand "sessions," click "Create Session," fill in parameters, and hit "Try it out." The API responds with a new session. Documentation and testing in one interface.
+
+**Scenario 2 — SDK Generation Pipeline:**
+A CI pipeline runs `mia-code build:openapi`, then feeds the spec to `openapi-typescript` to generate type definitions. The generated types are published as `@mia-code/sdk`. Any breaking API change triggers a type error in SDK consumers — drift is impossible.
+
+**Scenario 3 — Third-Party Integration:**
+A developer imports the OpenAPI spec into Postman. All endpoints appear as a collection with example request bodies pre-filled from schemas. They build an integration test suite against the live API using the imported collection.
+
+**Scenario 4 — Contract Testing:**
+The OpenAPI spec serves as a contract. Integration tests validate that every endpoint returns responses matching their declared schemas. If a handler returns an undocumented field or omits a required one, the test fails. The spec is both documentation and test oracle.

package/rispecs/borrowed_from_opencode/090-websocket-support.rispec.md

@@ -0,0 +1,136 @@
+# RISE-090: WebSocket Support
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/090-websocket-support.rispec.md
+
+## Creative Intent
+
+mia-code provides a WebSocket connection for real-time bidirectional communication between the server and clients. While HTTP endpoints handle request-response operations, the WebSocket channel carries live streaming data — message deltas as the agent thinks, tool execution updates, permission requests that need immediate user response, and session state changes. The WebSocket makes remote driving feel as responsive as sitting at the terminal.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code renders output directly to the terminal — there is no streaming protocol
+- Agent responses appear character-by-character via ora spinners and chalk formatting, tightly coupled to stdout
+- No mechanism exists for a remote client to receive real-time updates from a running agent
+- Permission prompts are blocking terminal reads — they cannot be routed to a remote client
+- Tool execution progress is visible only in the terminal that started the process
+
+**Desired State:**
+- A WebSocket endpoint at `ws://localhost:4096/ws` accepts client connections
+- Connected clients receive real-time events: message deltas, tool updates, permission requests, cost data
+- Clients send messages, permission responses, and cancel signals over the same connection
+- Multiple clients can connect simultaneously — all receive the same events
+- The protocol uses typed JSON messages with clear event categorization
+- Connection health is maintained via ping/pong heartbeats
+
+## Desired Outcome Definition
+
+A client opens a WebSocket connection to the mia-code server and receives typed JSON events in real-time as the agent processes messages. The same connection carries client-to-server messages like user input and permission responses. The experience is instantaneous, bidirectional, and multiplexed across clients.
+
+## Natural Language Functional Description
+
+### Connection Lifecycle
+
+1. **Connect**: Client opens WebSocket to `ws://localhost:4096/ws`
+2. **Authenticate**: If password configured, client sends `{type: "auth", data: {password: "..."}}`
+3. **Subscribe**: Client sends `{type: "subscribe", data: {sessionId: "..."}}`
+4. **Receive events**: Server pushes typed events as they occur
+5. **Send messages**: Client sends user messages, permission responses, cancel signals
+6. **Disconnect**: Either side closes the connection; client can reconnect at any time
+
+### Message Protocol
+
+All messages follow a uniform structure:
+
+```typescript
+interface WebSocketMessage {
+  type: string        // event type identifier
+  data: object        // typed payload
+  timestamp: string   // ISO 8601 timestamp
+  sessionId?: string  // session scope (absent for system messages)
+}
+```
+
+### Server → Client Events
+
+| Event Type            | Payload                                        | Description                        |
+|-----------------------|------------------------------------------------|------------------------------------|
+| `message.start`       | `{messageId, role}`                            | Agent begins generating a response |
+| `message.delta`       | `{messageId, content, index}`                  | Streaming text chunk               |
+| `message.complete`    | `{messageId, content, usage}`                  | Agent finished, full response      |
+| `tool.start`          | `{toolName, parameters, toolCallId}`           | Tool execution begins              |
+| `tool.result`         | `{toolCallId, result, duration}`               | Tool execution completed           |
+| `permission.request`  | `{requestId, permission, target, preview}`     | Permission prompt needs response   |
+| `session.updated`     | `{session}`                                    | Session metadata changed           |
+| `cost.updated`        | `{sessionCost, totalCost, tokens}`             | Token usage and cost update        |
+| `error`               | `{name, message, code}`                        | Error occurred during processing   |
+| `heartbeat`           | `{}`                                           | Keep-alive ping                    |
+
+### Client → Server Messages
+
+| Message Type          | Payload                                        | Description                        |
+|-----------------------|------------------------------------------------|------------------------------------|
+| `auth`                | `{password}`                                   | Authenticate connection            |
+| `subscribe`           | `{sessionId}`                                  | Subscribe to session events        |
+| `unsubscribe`         | `{sessionId}`                                  | Unsubscribe from session           |
+| `message.send`        | `{sessionId, content}`                         | Send a user message                |
+| `permission.respond`  | `{requestId, response}`                        | Respond to permission prompt       |
+| `cancel`              | `{sessionId}`                                  | Cancel current agent operation     |
+
+### Multi-Client Support
+
+Multiple clients can connect to the same server simultaneously:
+
+- All clients subscribed to a session receive the same events
+- Any client can send a user message — messages are queued and processed in order
+- Permission requests are broadcast to all clients — the first response wins
+- Client disconnect does not affect other clients or the running agent
+- Each client maintains its own subscription state
+
+### Heartbeat Protocol
+
+- Server sends `{type: "heartbeat"}` every 30 seconds
+- Client should respond with a WebSocket pong frame
+- If no pong received within 10 seconds, server considers client disconnected
+- Client should reconnect if no heartbeat received within 60 seconds
+- Heartbeat interval configurable: `{"server": {"heartbeatInterval": 30000}}`
+
+### Authentication Flow
+
+When a server password is configured:
+
+1. Client connects via WebSocket
+2. Client sends `{type: "auth", data: {password: "secret"}}`
+3. Server responds with `{type: "auth.success"}` or `{type: "auth.failed", data: {message: "Invalid password"}}`
+4. Unauthenticated clients receive no events and cannot send messages
+5. Authentication is per-connection — reconnections must re-authenticate
+
+### Error Handling
+
+- Malformed messages receive `{type: "error", data: {message: "Invalid message format"}}`
+- Messages to non-existent sessions receive `{type: "error", data: {message: "Session not found"}}`
+- Server errors during message processing are sent as error events, not connection closures
+- The WebSocket connection stays open through errors — only explicit close or timeout disconnects
+
+## Supporting Structures
+
+- **HTTP API Server (RISE-088)** provides the server that hosts the WebSocket endpoint
+- **SSE Streaming (RISE-091)** provides an alternative one-way streaming protocol
+- **Event Bus (RISE-002)** provides the internal event system that WebSocket events mirror
+- **Permission Modes (RISE-087)** defines permission prompts routed via WebSocket
+- **Client-Server Architecture (RISE-001)** defines the overall architecture this implements
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Real-Time Web UI:**
+A React web app opens a WebSocket connection and renders message deltas as they arrive. The user sees the agent's response streaming character-by-character, tool executions appearing as they start and complete, and permission prompts appearing as modal dialogs. The experience mirrors the terminal but with richer rendering.
+
+**Scenario 2 — Mobile Remote Driving:**
+A mobile app connects via WebSocket over the local network. The developer sends prompts by typing on their phone. Message deltas stream back in real-time. Permission prompts appear as push notifications. The developer approves from the lock screen.
+
+**Scenario 3 — Multi-Monitor Pair Programming:**
+Developer A drives the agent from a web UI on one monitor. Developer B has a terminal client on another monitor subscribed to the same session. Both see identical real-time output. Developer B spots an issue and sends a correction — it appears in both clients immediately.
+
+**Scenario 4 — Dashboard Monitoring:**
+An ops dashboard subscribes to all active sessions via WebSocket. It shows a grid of running agents: current task, token usage, tool executions, and errors. Cost updates stream in real-time. A sudden spike in errors triggers an alert without polling.