mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/091-sse-streaming.rispec.md

@@ -0,0 +1,168 @@
+# RISE-091: SSE Streaming
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/091-sse-streaming.rispec.md
+
+## Creative Intent
+
+mia-code provides Server-Sent Events (SSE) as a lightweight one-way streaming protocol alongside the full WebSocket channel. SSE is the pragmatic choice for clients that only need to receive events — web UIs rendering agent output, monitoring dashboards, CI scripts waiting for results. It works through proxies, reconnects automatically, and requires no special server infrastructure. A `curl` command is all you need to watch an agent think in real-time.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code streams output only to the local terminal via stdout
+- No HTTP-based streaming mechanism exists for remote clients
+- Polling the API for new messages is wasteful and introduces latency
+- WebSocket (RISE-090) provides full bidirectional streaming but requires client library support
+- Simple clients (curl, EventSource, server-rendered pages) cannot use WebSocket easily
+- No reconnection protocol exists — if the connection drops, context is lost
+
+**Desired State:**
+- An SSE endpoint streams typed events for any session
+- Clients connect with a standard `EventSource` (browser) or `curl` (terminal)
+- Events are typed: message, delta, tool_start, tool_result, permission, error, done
+- Automatic reconnection via `Last-Event-ID` header resumes where the client left off
+- SSE coexists with WebSocket — clients choose the protocol that fits their needs
+- Multiple SSE streams per session are supported (multiple observers)
+
+## Desired Outcome Definition
+
+A client connects to `GET /api/session/{id}/events` and receives a stream of typed server-sent events as the agent processes messages. The stream includes message deltas, tool execution updates, permission prompts, and completion signals. Disconnected clients reconnect and resume from their last received event.
+
+## Natural Language Functional Description
+
+### SSE Endpoint
+
+```
+GET /api/session/{id}/events
+Accept: text/event-stream
+Authorization: Basic base64(user:password)    # if authentication configured
+Last-Event-ID: evt_42                          # for reconnection
+```
+
+The server responds with `Content-Type: text/event-stream` and begins pushing events.
+
+### Event Format
+
+Each event follows the SSE specification:
+
+```
+id: evt_42
+event: message.delta
+data: {"messageId":"msg_1","content":"Hello","index":7}
+
+id: evt_43
+event: tool.start
+data: {"toolName":"bash","parameters":{"command":"ls"},"toolCallId":"tc_1"}
+
+```
+
+Fields:
+- `id` — monotonically increasing event ID for reconnection
+- `event` — event type string
+- `data` — JSON payload (single line)
+- Empty line terminates each event
+
+### Event Types
+
+| Event Type     | Payload                                          | Description                          |
+|----------------|--------------------------------------------------|--------------------------------------|
+| `message`      | `{messageId, role, content}`                     | New complete message added           |
+| `delta`        | `{messageId, content, index}`                    | Streaming token from agent           |
+| `tool_start`   | `{toolName, parameters, toolCallId}`             | Tool execution beginning             |
+| `tool_result`  | `{toolCallId, result, duration, success}`        | Tool execution completed             |
+| `permission`   | `{requestId, permission, target, preview}`       | Permission prompt (respond via API)  |
+| `error`        | `{name, message, code}`                          | Error during processing              |
+| `done`         | `{messageId, usage}`                             | Agent response complete              |
+| `session`      | `{id, title, status}`                            | Session metadata updated             |
+| `cost`         | `{sessionCost, totalCost, inputTokens, outputTokens}` | Cost and token update          |
+| `heartbeat`    | `{}`                                             | Keep-alive (every 30s)               |
+
+### Reconnection
+
+SSE has built-in reconnection support:
+
+1. Client tracks the last received event ID (automatic in `EventSource`)
+2. On disconnect, client reconnects with `Last-Event-ID: evt_42` header
+3. Server replays all events after `evt_42` from the session event buffer
+4. Client resumes seamlessly — no duplicate or missed events
+5. Event buffer retains the last 1000 events per session (configurable)
+
+If the requested `Last-Event-ID` is no longer in the buffer, the server sends a `reset` event instructing the client to reload full state from the REST API.
+
+### Heartbeat
+
+The server sends a heartbeat comment every 30 seconds to keep the connection alive through proxies:
+
+```
+: heartbeat
+
+```
+
+SSE comments (lines starting with `:`) are ignored by `EventSource` but prevent proxy timeouts.
+
+### Connection Parameters
+
+Query parameters customize the stream:
+
+- `?types=delta,tool_start,done` — filter to specific event types (default: all)
+- `?lastEventId=evt_42` — alternative to `Last-Event-ID` header
+- `?heartbeat=15` — custom heartbeat interval in seconds
+
+### Comparison with WebSocket
+
+| Feature            | SSE (RISE-091)              | WebSocket (RISE-090)           |
+|--------------------|-----------------------------|--------------------------------|
+| Direction          | Server → Client only        | Bidirectional                  |
+| Reconnection       | Automatic (built-in)        | Manual (client must implement) |
+| Proxy support      | Works through HTTP proxies  | May require proxy configuration|
+| Client complexity  | EventSource (3 lines of JS) | WebSocket API (more setup)     |
+| Send messages      | Separate HTTP POST           | Same connection                |
+| Browser support    | Native EventSource          | Native WebSocket               |
+| Use case           | Monitoring, streaming UI    | Interactive driving, real-time |
+
+### Usage Examples
+
+**Browser (EventSource):**
+```javascript
+const events = new EventSource("/api/session/abc/events")
+events.addEventListener("delta", (e) => {
+  const data = JSON.parse(e.data)
+  document.getElementById("output").textContent += data.content
+})
+events.addEventListener("done", () => console.log("Response complete"))
+```
+
+**Terminal (curl):**
+```bash
+curl -N -H "Accept: text/event-stream" http://localhost:4096/api/session/abc/events
+```
+
+**Permission Handling via SSE:**
+When a `permission` event arrives, the client responds via the REST API:
+```
+POST /api/permission/respond
+{"requestId": "perm_1", "response": "y"}
+```
+
+## Supporting Structures
+
+- **HTTP API Server (RISE-088)** provides the server hosting the SSE endpoint
+- **WebSocket Support (RISE-090)** provides the bidirectional alternative
+- **Event Bus (RISE-002)** provides internal events that SSE mirrors externally
+- **Permission Modes (RISE-087)** defines permission events streamed via SSE
+- **JavaScript SDK (RISE-093)** wraps SSE in a typed `AsyncIterable` interface
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — curl Monitoring:**
+A developer runs `curl -N http://localhost:4096/api/session/abc/events` in a second terminal. They watch tool executions and message deltas scroll by as the agent works. When the agent finishes, a `done` event appears. No web browser needed — just curl.
+
+**Scenario 2 — Lightweight Web Dashboard:**
+A server-rendered HTML page includes three lines of JavaScript using `EventSource`. As the agent streams tokens, they appear in the page. No React, no build step, no WebSocket library — just native browser APIs rendering a live agent session.
+
+**Scenario 3 — CI Pipeline Integration:**
+A CI script sends a prompt via POST, then connects to SSE to wait for the `done` event. It captures the final message content and posts it as a PR comment. The SSE connection times out gracefully if the agent takes too long.
+
+**Scenario 4 — Resilient Mobile Client:**
+A mobile app uses SSE for streaming. The user walks between WiFi networks. Each time the connection drops, `EventSource` reconnects automatically and sends `Last-Event-ID`. The server replays missed events. The user sees continuous output with no gaps.

package/rispecs/borrowed_from_opencode/092-mdns-discovery.rispec.md

@@ -0,0 +1,145 @@
+# RISE-092: mDNS Discovery
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/092-mdns-discovery.rispec.md
+
+## Creative Intent
+
+mia-code announces itself on the local network via mDNS (multicast DNS), letting clients discover running instances without knowing IP addresses or port numbers. A developer starts the server on their workstation and their phone finds it automatically. A desktop app scans for local instances and presents a connection list. mDNS transforms "enter the server URL" into "select which agent to connect to" — zero-configuration networking for AI-assisted development.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code runs only as a local CLI process — there is nothing to discover
+- When the HTTP server (RISE-088) is added, clients must know the exact IP and port
+- Developers working across devices (workstation + laptop + phone) must manually configure connection URLs
+- No automatic service announcement exists — each device is an island
+- Multiple mia-code instances on a network are invisible to each other
+
+**Desired State:**
+- When mia-code server starts, it announces a service via mDNS: `_mia-code._tcp.local.`
+- Clients on the same network discover running instances without manual configuration
+- Service metadata includes version, hostname, project name, port, and authentication status
+- Multiple instances are differentiated by project name in their service names
+- Discovery completes in under 5 seconds — fast enough for interactive use
+- mDNS is optional and can be disabled via configuration
+
+## Desired Outcome Definition
+
+A running mia-code server automatically announces itself as a Bonjour/mDNS service on the local network. Any mDNS-capable client discovers it by browsing for `_mia-code._tcp.local.` services. The client receives the server's IP, port, and metadata without any manual configuration.
+
+## Natural Language Functional Description
+
+### Service Announcement
+
+When `mia-code serve` starts and mDNS is enabled, it publishes a service:
+
+```
+Service Type:  _mia-code._tcp.local.
+Service Name:  mia-code - my-project._mia-code._tcp.local.
+Port:          4096
+TXT Records:
+  version=1.0.0
+  project=my-project
+  hostname=workstation.local
+  auth=true
+  directory=/home/user/my-project
+```
+
+The service name includes the project name (derived from the project directory or package.json name) to differentiate multiple instances.
+
+### Discovery Process
+
+A client discovers mia-code instances:
+
+1. Browse for services of type `_mia-code._tcp.local.`
+2. mDNS resolver returns a list of matching services (typically within 2-3 seconds)
+3. For each service, resolve the hostname to an IP address
+4. Read TXT records for metadata (version, project, auth requirement)
+5. Present the list to the user or auto-connect to a preferred instance
+
+### Discovery Timeout
+
+- Default scan duration: 5 seconds
+- Quick scan (for UIs with auto-refresh): 2 seconds
+- Extended scan (for first-time setup): 10 seconds
+- Scan runs asynchronously — results stream in as they are discovered
+
+### TXT Record Fields
+
+| Field       | Description                               | Example                    |
+|-------------|-------------------------------------------|----------------------------|
+| `version`   | mia-code server version                   | `1.0.0`                    |
+| `project`   | Project name from package.json or dirname | `my-project`               |
+| `hostname`  | Machine hostname                          | `workstation.local`        |
+| `auth`      | Whether authentication is required        | `true` or `false`          |
+| `directory` | Project root directory path               | `/home/user/my-project`    |
+
+### Multiple Instances
+
+Multiple mia-code servers on the same network each publish their own service:
+
+```
+mia-code - frontend._mia-code._tcp.local.    port:4096
+mia-code - backend._mia-code._tcp.local.     port:4097
+mia-code - infra._mia-code._tcp.local.       port:4098
+```
+
+Clients see all instances and can connect to any of them. Each instance operates independently.
+
+### Configuration
+
+mDNS is enabled by default. Disable via config:
+
+```json
+{
+  "server": {
+    "mdns": false
+  }
+}
+```
+
+Or via CLI flag:
+
+```bash
+mia-code serve --no-mdns
+```
+
+### Implementation
+
+Use the `bonjour-service` npm package (or `multicast-dns`) for cross-platform mDNS:
+
+- **Publish**: on server start, call `bonjour.publish({type: "mia-code", protocol: "tcp", port, txt: {...}})`
+- **Browse**: clients call `bonjour.find({type: "mia-code"})` and receive service events
+- **Unpublish**: on server shutdown, call `bonjour.unpublishAll()` to clean up announcements
+- Works on macOS (native Bonjour), Linux (Avahi), and Windows (Bonjour for Windows)
+
+### Security Considerations
+
+mDNS is used **only** for service discovery — it reveals that a mia-code instance exists and its connection parameters. It does not bypass authentication:
+
+- If `auth=true` in TXT records, the client must provide the password to use the API
+- mDNS broadcasts are limited to the local network segment (not routable)
+- The `directory` TXT record can be omitted for privacy: `{"server": {"mdns": {"exposeDirectory": false}}}`
+- Service names do not contain sensitive information
+
+## Supporting Structures
+
+- **HTTP API Server (RISE-088)** provides the server that mDNS announces
+- **Desktop Remote Driving (RISE-096)** uses mDNS to auto-discover local servers
+- **JavaScript SDK (RISE-093)** includes mDNS discovery in `MiaCodeClient.discover()`
+- **Structured Logging (RISE-007)** logs service publication and discovery events
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Phone Auto-Connect:**
+A developer opens the mia-code mobile app. It scans for `_mia-code._tcp.local.` and finds their workstation running on port 4096 with project "frontend." One tap connects. No URL typing, no port memorization — just tap and drive.
+
+**Scenario 2 — Desktop App Server Picker:**
+The mia-code desktop app shows a "Connect" screen listing all discovered instances: "frontend on workstation (port 4096)" and "backend on server (port 4097)." The developer clicks one and is connected. The list auto-refreshes as servers start and stop.
+
+**Scenario 3 — Multi-Project Dashboard:**
+A monitoring dashboard discovers all mia-code instances on the team network. It shows a grid: three developers each running agents on different projects. Token costs, active sessions, and error rates for each instance — all discovered automatically via mDNS.
+
+**Scenario 4 — Pair Programming Discovery:**
+Developer A starts `mia-code serve` on their machine. Developer B runs `mia-code connect --discover` and sees Developer A's instance in the list. They connect and join the session. mDNS made the connection possible without exchanging IPs or URLs.

package/rispecs/borrowed_from_opencode/093-javascript-sdk.rispec.md

@@ -0,0 +1,200 @@
+# RISE-093: JavaScript SDK
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/093-javascript-sdk.rispec.md
+
+## Creative Intent
+
+mia-code publishes a TypeScript/JavaScript SDK that gives developers programmatic control over every aspect of the platform. Instead of shelling out to the CLI or crafting raw HTTP requests, a developer writes `const client = new MiaCodeClient({url, password})` and immediately has typed methods for sessions, messages, tools, and configuration. The SDK is auto-generated from the OpenAPI spec, ensuring types are always accurate. It is the bridge between mia-code and the ecosystem — custom UIs, workflow automation, CI/CD integration, and creative applications that no one has imagined yet.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code can only be controlled via the CLI — there is no programmatic API
+- External scripts interact by spawning `mia-code` as a subprocess and parsing stdout
+- No TypeScript types exist for request/response shapes — consumers guess at structures
+- Building integrations requires reverse-engineering the CLI's behavior
+- No streaming support for programmatic consumers — you get all output or nothing
+
+**Desired State:**
+- A published npm package `@mia-code/sdk` provides a typed API client
+- All methods are auto-generated from the OpenAPI spec (RISE-089) — types cannot drift
+- Streaming support via `AsyncIterable` for real-time message consumption
+- Error handling uses typed errors matching the Named Error System (RISE-006)
+- The SDK works in Node.js, Deno, Bun, and browser environments
+- Documentation is generated from TypeDoc and published alongside the package
+
+## Desired Outcome Definition
+
+A developer installs `@mia-code/sdk`, creates a client instance with a URL and optional password, and has full typed access to sessions, messages, tools, configuration, and permissions. Message streaming returns an `AsyncIterable` for real-time consumption. Errors are typed and descriptive.
+
+## Natural Language Functional Description
+
+### Installation and Setup
+
+```bash
+npm install @mia-code/sdk
+```
+
+```typescript
+import { MiaCodeClient } from "@mia-code/sdk"
+
+const client = new MiaCodeClient({
+  url: "http://localhost:4096",
+  password: "optional-password",
+})
+```
+
+### Client API Surface
+
+**Sessions:**
+```typescript
+const sessions = await client.sessions.list()
+const session = await client.sessions.create({ title: "Refactor auth", directory: "/app" })
+const details = await client.sessions.get(session.id)
+await client.sessions.delete(session.id)
+await client.sessions.update(session.id, { title: "New title" })
+```
+
+**Messages:**
+```typescript
+// Send and wait for complete response
+const response = await client.messages.send(sessionId, "Explain this function")
+
+// Stream response tokens as they arrive
+for await (const event of client.messages.stream(sessionId, "Refactor this")) {
+  if (event.type === "delta") process.stdout.write(event.content)
+  if (event.type === "tool_start") console.log(`Running ${event.toolName}...`)
+  if (event.type === "done") console.log("\nComplete!")
+}
+
+// Get message history
+const messages = await client.messages.list(sessionId, { limit: 50 })
+```
+
+**Tools:**
+```typescript
+const tools = await client.tools.list()
+const result = await client.tools.execute("bash", { command: "ls -la" })
+const tool = await client.tools.get("grep")
+```
+
+**Configuration:**
+```typescript
+const config = await client.config.get()
+await client.config.update({ model: "claude-sonnet-4-20250514" })
+```
+
+**Permissions:**
+```typescript
+const rules = await client.permissions.list()
+await client.permissions.respond(requestId, "y")
+await client.permissions.reset()
+```
+
+**Discovery (mDNS):**
+```typescript
+const instances = await MiaCodeClient.discover({ timeout: 5000 })
+// [{url: "http://192.168.1.10:4096", project: "frontend", auth: true}, ...]
+const client = new MiaCodeClient(instances[0])
+```
+
+### Streaming Implementation
+
+Message streaming uses SSE (RISE-091) under the hood, exposed as an `AsyncIterable`:
+
+```typescript
+interface StreamEvent {
+  type: "delta" | "tool_start" | "tool_result" | "permission" | "error" | "done"
+  data: object
+}
+
+// The stream is an AsyncIterable — works with for-await-of
+const stream = client.messages.stream(sessionId, content)
+
+// Can also be consumed with callbacks
+stream.on("delta", (data) => { /* ... */ })
+stream.on("done", (data) => { /* ... */ })
+```
+
+### Error Handling
+
+SDK errors are typed and match the Named Error System:
+
+```typescript
+import { SessionNotFoundError, PermissionDeniedError, ValidationError } from "@mia-code/sdk"
+
+try {
+  await client.sessions.get("nonexistent")
+} catch (error) {
+  if (error instanceof SessionNotFoundError) {
+    console.log("Session does not exist:", error.message)
+  }
+}
+```
+
+All errors extend `MiaCodeError` with `name`, `message`, and `code` properties.
+
+### Type Safety
+
+All request and response types are generated from Zod schemas via the OpenAPI spec:
+
+```typescript
+import type { Session, Message, Tool, PermissionRule } from "@mia-code/sdk"
+
+// TypeScript enforces correct usage
+const session: Session = await client.sessions.create({
+  title: "My session",
+  directory: "/app",
+  // model: 123  ← TypeScript error: must be string
+})
+```
+
+### Package Structure
+
+```
+@mia-code/sdk/
+├── index.ts          # main exports: MiaCodeClient, types, errors
+├── client.ts         # MiaCodeClient class
+├── sessions.ts       # SessionsAPI class
+├── messages.ts       # MessagesAPI class (with streaming)
+├── tools.ts          # ToolsAPI class
+├── config.ts         # ConfigAPI class
+├── permissions.ts    # PermissionsAPI class
+├── discovery.ts      # mDNS discovery
+├── errors.ts         # typed error classes
+├── types.ts          # generated types from OpenAPI
+└── stream.ts         # SSE/WebSocket streaming utilities
+```
+
+### Environment Support
+
+The SDK works across JavaScript runtimes:
+
+- **Node.js 18+**: full support including mDNS discovery
+- **Deno**: full support via npm compatibility
+- **Bun**: full support
+- **Browser**: all features except mDNS discovery (uses EventSource for streaming)
+
+## Supporting Structures
+
+- **HTTP API Server (RISE-088)** provides the endpoints the SDK calls
+- **OpenAPI Spec Generation (RISE-089)** generates the spec the SDK types are derived from
+- **SSE Streaming (RISE-091)** powers the message streaming feature
+- **WebSocket Support (RISE-090)** provides an alternative streaming transport
+- **mDNS Discovery (RISE-092)** powers the `MiaCodeClient.discover()` method
+- **Named Error System (RISE-006)** defines the error types the SDK exposes
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Custom Web UI:**
+A developer builds a custom chat interface using React and the SDK. `client.messages.stream()` feeds tokens into a state store. Tool executions render as expandable panels. The entire UI is 200 lines of TypeScript because the SDK handles all API complexity.
+
+**Scenario 2 — CI/CD Code Review Bot:**
+A GitHub Actions workflow uses the SDK to create a session, send a PR diff as a prompt, and collect the agent's review. The response is posted as a PR comment. The SDK's typed API ensures correct usage without reading API docs.
+
+**Scenario 3 — Batch Automation:**
+A Node.js script iterates over 50 files and sends each to mia-code for refactoring. `for await` streams each response, logging progress. Errors are caught and logged with typed error names. The script runs unattended overnight.
+
+**Scenario 4 — VS Code Extension:**
+A VS Code extension uses the SDK to connect to a running mia-code server. The developer highlights code, triggers a command, and the extension sends the selection as a prompt via `client.messages.send()`. The response appears in a panel — IDE-integrated AI assistance powered by the same mia-code agent.