mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/INDEX.md

@@ -0,0 +1,255 @@
+# Borrowed from OpenCode — RISE Specification Index
+
+> Cross-pollination specifications extracted from [OpenCode](https://github.com/anomalyco/opencode), an open-source AI coding agent, for implementation in mia-code.
+
+## How to Use This Folder
+
+Each `.rispec.md` file is a **self-contained RISE specification** describing one feature or capability that can enhance mia-code. An implementing LLM should:
+
+1. Read this index to understand the full scope
+2. Read individual specs in dependency order (noted below)
+3. Implement each spec independently — they are designed to be modular
+4. Refer to mia-code's existing `rispecs/core.rispecs.md` for current architecture
+
+## Dependency Graph
+
+```
+001-client-server-architecture
+  └── 088-http-api-server
+       ├── 089-openapi-spec-generation
+       ├── 090-websocket-support
+       └── 091-sse-streaming
+
+002-event-bus-system ← foundational, many specs depend on this
+
+003-instance-state-pattern ← foundational pattern
+
+080-sqlite-storage
+  ├── 018-session-persistence
+  │    ├── 019-session-compaction
+  │    ├── 020-session-forking
+  │    ├── 021-session-revert-snapshot
+  │    └── 022-session-sharing
+  ├── 081-database-migrations
+  └── 082-database-transactions
+
+034-tool-registry ← all tool specs (035-048) depend on this
+
+064-multi-level-config ← configuration foundation
+
+071-plugin-architecture ← plugin specs (072-074) depend on this
+
+074-permission-system ← many tool/agent specs reference this
+```
+
+## Specification Categories
+
+### 1. Architecture (001–008)
+Core architectural patterns that form the foundation.
+
+| File | Feature |
+|------|---------|
+| [001](001-client-server-architecture.rispec.md) | Client/Server Architecture |
+| [002](002-event-bus-system.rispec.md) | Event Bus System |
+| [003](003-instance-state-pattern.rispec.md) | Instance State Pattern |
+| [004](004-namespace-module-pattern.rispec.md) | Namespace Module Pattern |
+| [005](005-zod-schema-validation.rispec.md) | Zod Schema Validation |
+| [006](006-named-error-system.rispec.md) | Named Error System |
+| [007](007-structured-logging.rispec.md) | Structured Logging |
+| [008](008-lazy-initialization.rispec.md) | Lazy Initialization Pattern |
+
+### 2. Agent System (009–017)
+Multi-agent orchestration with modes, permissions, and generation.
+
+| File | Feature |
+|------|---------|
+| [009](009-multi-agent-system.rispec.md) | Multi-Agent System with Modes |
+| [010](010-agent-definition-config.rispec.md) | Agent Definition & Configuration |
+| [011](011-agent-permission-rulesets.rispec.md) | Agent Permission Rulesets |
+| [012](012-agent-prompt-templates.rispec.md) | Agent Prompt Templates |
+| [013](013-agent-generation.rispec.md) | AI-Powered Agent Generation |
+| [014](014-plan-build-mode-toggle.rispec.md) | Plan/Build Mode Toggle |
+| [015](015-subagent-task-delegation.rispec.md) | Sub-Agent Task Delegation |
+| [016](016-agent-model-selection.rispec.md) | Per-Agent Model Selection |
+| [017](017-compaction-agent.rispec.md) | Session Compaction Agent |
+
+### 3. Session Management (018–027)
+Persistent, forkable, shareable conversation sessions.
+
+| File | Feature |
+|------|---------|
+| [018](018-session-persistence.rispec.md) | SQLite Session Persistence |
+| [019](019-session-compaction.rispec.md) | Session History Compaction |
+| [020](020-session-forking.rispec.md) | Session Forking |
+| [021](021-session-revert-snapshot.rispec.md) | Session Revert & Snapshots |
+| [022](022-session-sharing.rispec.md) | Session Sharing |
+| [023](023-session-summary-diffs.rispec.md) | Session Summary with Diffs |
+| [024](024-child-sessions.rispec.md) | Child Sessions |
+| [025](025-session-title-generation.rispec.md) | AI Session Title Generation |
+| [026](026-message-parts-model.rispec.md) | Message Parts Model |
+| [027](027-streaming-message-deltas.rispec.md) | Streaming Message Deltas |
+
+### 4. Provider System (028–033)
+Multi-provider LLM integration with cost tracking.
+
+| File | Feature |
+|------|---------|
+| [028](028-multi-provider-architecture.rispec.md) | Multi-Provider Architecture |
+| [029](029-provider-authentication.rispec.md) | Provider Authentication |
+| [030](030-model-registry.rispec.md) | Model Registry (models.dev) |
+| [031](031-cost-tracking.rispec.md) | Token Cost Tracking |
+| [032](032-provider-transform-pipeline.rispec.md) | Provider Transform Pipeline |
+| [033](033-provider-sdk-abstraction.rispec.md) | Provider SDK Abstraction |
+
+### 5. Tool System (034–048)
+Comprehensive tool registry with 15+ built-in tools.
+
+| File | Feature |
+|------|---------|
+| [034](034-tool-registry.rispec.md) | Tool Registry Pattern |
+| [035](035-tool-context-injection.rispec.md) | Tool Context Injection |
+| [036](036-tool-output-truncation.rispec.md) | Tool Output Truncation |
+| [037](037-batch-tool.rispec.md) | Batch File Operations Tool |
+| [038](038-multi-edit-tool.rispec.md) | Multi-Edit Tool |
+| [039](039-apply-patch-tool.rispec.md) | Apply Patch Tool |
+| [040](040-code-search-tool.rispec.md) | Code Search Tool |
+| [041](041-web-fetch-tool.rispec.md) | Web Fetch Tool |
+| [042](042-web-search-tool.rispec.md) | Web Search Tool |
+| [043](043-todo-tool.rispec.md) | Built-in Todo Tool |
+| [044](044-plan-mode-tool.rispec.md) | Plan Mode Tool |
+| [045](045-task-tool.rispec.md) | Background Task Tool |
+| [046](046-question-tool.rispec.md) | User Question Tool |
+| [047](047-external-directory-tool.rispec.md) | External Directory Access Tool |
+| [048](048-file-read-write-tools.rispec.md) | File Read/Write Tools |
+
+### 6. LSP Integration (049–052)
+Language Server Protocol for code intelligence.
+
+| File | Feature |
+|------|---------|
+| [049](049-lsp-server-management.rispec.md) | LSP Server Management |
+| [050](050-lsp-hover-completion.rispec.md) | LSP Hover & Completion |
+| [051](051-lsp-diagnostics.rispec.md) | LSP Diagnostics Integration |
+| [052](052-lsp-root-detection.rispec.md) | LSP Root Detection |
+
+### 7. MCP Enhancement (053–057)
+Enhanced Model Context Protocol integration.
+
+| File | Feature |
+|------|---------|
+| [053](053-remote-mcp-servers.rispec.md) | Remote MCP Servers |
+| [054](054-mcp-oauth-flow.rispec.md) | MCP OAuth Flow |
+| [055](055-mcp-tool-conversion.rispec.md) | MCP Tool Conversion |
+| [056](056-mcp-connection-monitoring.rispec.md) | MCP Connection Monitoring |
+| [057](057-local-mcp-servers.rispec.md) | Local MCP Server Management |
+
+### 8. TUI/Interface (058–063)
+Rich terminal user interface.
+
+| File | Feature |
+|------|---------|
+| [058](058-rich-tui.rispec.md) | Rich Terminal UI |
+| [059](059-streaming-display.rispec.md) | Streaming Message Display |
+| [060](060-permission-prompts.rispec.md) | Interactive Permission Prompts |
+| [061](061-session-navigation.rispec.md) | Session Navigation UI |
+| [062](062-syntax-highlighting.rispec.md) | Syntax Highlighting |
+| [063](063-keybinding-system.rispec.md) | Keybinding System |
+
+### 9. Configuration (064–070)
+Multi-level configuration with deep merging.
+
+| File | Feature |
+|------|---------|
+| [064](064-multi-level-config.rispec.md) | Multi-Level Configuration |
+| [065](065-jsonc-config.rispec.md) | JSONC Config Support |
+| [066](066-config-env-variables.rispec.md) | Config Environment Variables |
+| [067](067-config-deep-merging.rispec.md) | Config Deep Merging |
+| [068](068-remote-org-config.rispec.md) | Remote Organization Config |
+| [069](069-config-markdown-frontmatter.rispec.md) | Config Markdown Frontmatter |
+| [070](070-managed-config-directory.rispec.md) | Managed Config Directory |
+
+### 10. Plugin System (071–074)
+Extensible plugin architecture with hooks.
+
+| File | Feature |
+|------|---------|
+| [071](071-plugin-architecture.rispec.md) | Plugin Architecture |
+| [072](072-plugin-hooks.rispec.md) | Plugin Hook System |
+| [073](073-plugin-auto-install.rispec.md) | Plugin Auto-Install |
+| [074](074-permission-system.rispec.md) | Granular Permission System |
+
+### 11. Git Integration (075–079)
+Worktrees, snapshots, and file tracking.
+
+| File | Feature |
+|------|---------|
+| [075](075-git-worktree-management.rispec.md) | Git Worktree Management |
+| [076](076-snapshot-system.rispec.md) | File Snapshot System |
+| [077](077-snapshot-diff.rispec.md) | Snapshot Diff & Comparison |
+| [078](078-snapshot-restore.rispec.md) | Snapshot Restore |
+| [079](079-worktree-branch-naming.rispec.md) | Worktree Branch Naming |
+
+### 12. Storage (080–083)
+SQLite database layer with ORM.
+
+| File | Feature |
+|------|---------|
+| [080](080-sqlite-storage.rispec.md) | SQLite Storage Layer |
+| [081](081-database-migrations.rispec.md) | Database Migrations |
+| [082](082-database-transactions.rispec.md) | Database Transactions |
+| [083](083-deferred-effects.rispec.md) | Deferred Side Effects |
+
+### 13. Permission System (084–087)
+Granular access control.
+
+| File | Feature |
+|------|---------|
+| [084](084-permission-rules.rispec.md) | Permission Rule Definitions |
+| [085](085-permission-glob-patterns.rispec.md) | Permission Glob Patterns |
+| [086](086-permission-merging.rispec.md) | Permission Layered Merging |
+| [087](087-permission-modes.rispec.md) | Permission Modes (Allow/Deny/Ask) |
+
+### 14. Server & API (088–092)
+HTTP server with real-time communication.
+
+| File | Feature |
+|------|---------|
+| [088](088-http-api-server.rispec.md) | HTTP API Server |
+| [089](089-openapi-spec-generation.rispec.md) | OpenAPI Spec Generation |
+| [090](090-websocket-support.rispec.md) | WebSocket Real-Time Support |
+| [091](091-sse-streaming.rispec.md) | SSE Event Streaming |
+| [092](092-mdns-discovery.rispec.md) | mDNS Local Discovery |
+
+### 15. SDK & Extension Points (093–096)
+External integration and extension capabilities.
+
+| File | Feature |
+|------|---------|
+| [093](093-javascript-sdk.rispec.md) | JavaScript SDK |
+| [094](094-skill-system.rispec.md) | Skill System |
+| [095](095-skill-discovery.rispec.md) | Skill Discovery & Remote Loading |
+| [096](096-desktop-remote-driving.rispec.md) | Desktop & Remote Driving |
+
+## Implementation Priority for mia-code
+
+### Phase 1 — Foundation (implement first)
+- 002 Event Bus, 003 Instance State, 005 Zod Validation, 006 Named Errors
+- 064 Multi-Level Config, 080 SQLite Storage
+- 034 Tool Registry, 074 Permission System
+
+### Phase 2 — Agent Enhancement
+- 009 Multi-Agent, 014 Plan/Build Toggle, 015 Sub-Agent Delegation
+- 018 Session Persistence, 026 Message Parts Model
+
+### Phase 3 — Developer Experience
+- 049-052 LSP Integration (massive DX improvement)
+- 058-063 Rich TUI
+- 094-095 Skill System
+
+### Phase 4 — Platform
+- 001 Client/Server, 088-092 HTTP API & real-time
+- 022 Session Sharing, 093 SDK
+
+---
+
+*Generated: 2026-02-25 | Source: OpenCode (anomalyco/opencode) | Target: mia-code*

package/rispecs/core.rispecs.md

@@ -0,0 +1,261 @@
+# mia-code Core Specification
+
+> RISE Framework Specification v1.0
+> Document: mia-code/rispecs/core.rispecs.md
+
+## Creative Intent
+
+mia-code enables developers to create focused, meaningful interactions with AI coding agents through a unified terminal interface. Users achieve clarity and ceremonial depth in their code collaboration by channeling raw agent outputs through dual-perspective interpretation.
+
+## Structural Tension Analysis
+
+**Current Structural Reality:**
+- Developers interact with AI coding agents (Gemini CLI, Claude CLI) through raw output streams
+- Agent responses blend technical actions with implicit reasoning, creating cognitive load
+- Session continuity requires manual tracking across project contexts
+- No unified abstraction layer exists for multi-engine agent workflows
+
+**Desired Structural State:**
+- Every agent interaction produces structurally clear (🧠 Mia) and resonantly meaningful (🌸 Miette) outputs
+- Session persistence auto-resumes project context without user intervention
+- Engine selection becomes a configuration choice, not an interface change
+- Users focus on desired outcomes while the system handles orchestration complexity
+
+## Application Overview
+
+mia-code is a terminal coding agent that wraps Gemini CLI, Claude CLI, and Copilot CLI in headless mode, providing:
+- Dual-session architecture: primary agent performs work, unifier interprets essence
+- Multi-engine support: configurable between Gemini (default), Claude, and Copilot
+- Session management: per-project persistence with automatic resume
+- Ceremonial output: 🧠 Mia (structure) + 🌸 Miette (echo) dual-perspective summaries
+- MCP servers: three sub-CLIs (miaco, miatel, miawa) exposed as MCP tools for external agent orchestration
+
+## Screens
+
+### Interactive Chat Session
+
+**Description:** Primary interface where users create coding conversations with AI agents. Each prompt flows through primary agent execution and ceremonial interpretation.
+
+**Behavior:**
+- User enters prompt via readline interface
+- Primary agent session (Gemini or Claude) executes with tools/code/analysis
+- Unifier session interprets raw events into dual-perspective output
+- Session ID persists for conversation continuity
+
+**Layout:** Contains `PromptInput`, `ThinkingIndicator`, `CeremonialOutput`
+
+### Single Prompt Mode
+
+**Description:** Non-interactive mode for scripted or single-shot agent interactions.
+
+**Behavior:**
+- Accepts prompt as command-line argument
+- Executes same dual-session flow as interactive mode
+- Outputs to stdout and exits
+- Supports `--raw` flag for uninterpreted output
+
+### Configuration View
+
+**Description:** Users configure agent preferences and view current settings.
+
+**Behavior:**
+- Display current configuration as JSON
+- Accept `--set-*` flags to update individual settings
+- Persist to `~/.mia-code.json`
+
+### Session List
+
+**Description:** Users review and manage saved sessions across projects.
+
+**Behavior:**
+- List sessions with truncated IDs, project paths, and timestamps
+- Support `--clear` to remove all sessions
+- Interactive session picker when resuming without explicit ID
+
+## Components
+
+### PromptInput
+
+**Description:** Readline-based text input with ceremonial prompt styling.
+
+**Behavior:**
+- Displays `you> ` prompt in yellow
+- Handles slash commands (`/help`, `/exit`, `/session`)
+- Submits non-command input to agent processing pipeline
+
+**Styling:** Fixed terminal input, yellow accent color for prompt
+
+### ThinkingIndicator
+
+**Description:** Visual feedback during agent processing.
+
+**Behavior:**
+- Displays `⏳ thinking...` during primary session
+- Displays `⏳ interpreting...` during unifier session
+- Clears lines via ANSI codes upon completion
+
+**Styling:** Dimmed text, transient display
+
+### CeremonialOutput
+
+**Description:** Dual-perspective rendering of agent session results.
+
+**Behavior:**
+- Renders `🧠 mia (structure)` section with factual summary
+- Renders `🌸 miette (echo)` section with resonant reflection
+- Falls back to raw output if unifier fails
+
+**Styling:**
+- Bold green header for `🧠🌸 miawa:`
+- Dimmed text for session metadata
+- Standard text for body content
+
+## Data
+
+### MiaCodeConfig
+
+**Description:** User preferences and agent configuration.
+
+```typescript
+interface MiaCodeConfig {
+  engine: "gemini" | "claude" | "copilot";  // Primary agent engine
+  geminiBinary: string;              // Path to gemini CLI
+  claudeBinary: string;              // Path to claude CLI
+  copilotBinary: string;             // Path to copilot CLI
+  model: string;                     // Model name (engine-specific)
+  headlessOutputFormat: "json" | "stream-json";
+  defaultMode: "code" | "chat";
+  defaultProjectRoot: string | null;
+  yoloMode: boolean;                 // Auto-approve agent actions
+}
+```
+
+**Storage:** `~/.mia-code.json`
+**Defaults:** `gemini` engine, `gemini-2.5-pro` model, YOLO disabled
+
+### MiaCodeSessionMeta
+
+**Description:** Session tracking metadata for conversation continuity.
+
+```typescript
+interface MiaCodeSessionMeta {
+  id: string;              // Session UUID (from agent CLI)
+  startedAt: string;       // ISO timestamp
+  model: string;           // Model used for session
+  projectRoot: string | null;  // Project directory
+}
+```
+
+**Storage:** `~/.mia-code-sessions.json`
+**Index:** By project root and by session ID
+
+### GeminiJsonEvent
+
+**Description:** Normalized event structure from agent CLI output streams.
+
+```typescript
+interface GeminiJsonEvent {
+  type: "init" | "message" | "tool_use" | "tool_result" | "error" | "result" | string;
+  session_id?: string;
+  timestamp?: string;
+  role?: "user" | "assistant" | "system";
+  text?: string;
+  content?: string;
+  tool?: { name: string; input: unknown; };
+  result?: unknown;
+  error?: { code: string; message: string; };
+}
+```
+
+**Sources:** Gemini CLI stream-json, Claude CLI json output
+
+## Creative Advancement Scenarios
+
+### Creative Advancement Scenario: First Project Interaction
+
+**Desired Outcome:** Developer creates initial conversation with AI agent in new project
+
+**Current Structural Reality:** No session exists for current directory
+
+**Natural Progression:**
+1. User invokes `mia-code` in project directory
+2. Header displays project path and "new session will be created"
+3. User enters first prompt
+4. Agent CLI spawns, executes, returns events
+5. Session ID captured from agent response
+6. Session meta persisted to index
+7. Unifier interprets, displays ceremonial output
+
+**Achieved Outcome:** Developer sees meaningful dual-perspective response, session auto-persists for future resume
+
+### Creative Advancement Scenario: Engine Switching
+
+**Desired Outcome:** Developer selects optimal agent engine for task type
+
+**Current Structural Reality:** Using Gemini (default) but task requires Claude capabilities
+
+**Natural Progression:**
+1. User adds `--claude` flag to invocation
+2. Config override applies for this session
+3. Primary agent spawns Claude CLI instead of Gemini
+4. Engine-specific argument translation occurs (YOLO → dangerously-skip-permissions)
+5. Unifier always uses Claude (requires --system-prompt)
+
+**Achieved Outcome:** Developer uses Claude for primary agent while maintaining ceremonial interpretation
+
+### Creative Advancement Scenario: Session Resume
+
+**Desired Outcome:** Developer continues previous conversation context
+
+**Current Structural Reality:** Session exists from prior work in same project
+
+**Natural Progression:**
+1. User invokes `mia-code` in same project directory
+2. Session index lookup finds matching project root
+3. Last session ID retrieved, displayed in header
+4. Agent CLI receives `--resume <sessionId>` flag
+5. Conversation context restored by agent
+
+**Achieved Outcome:** Developer seamlessly continues prior conversation without manual session management
+
+## Supporting Structures
+
+### Command-Line Interface
+
+```bash
+# Primary commands
+mia-code chat [--project <path>] [--resume [id]] [--yolo] [--raw] [--claude|--gemini]
+mia-code prompt <text> [--project <path>] [--resume <id>] [--yolo] [--raw] [--claude|--gemini]
+mia-code config [--set-engine <e>] [--set-model <m>] [--set-yolo <bool>]
+mia-code sessions [--clear]
+mia-code where-config
+```
+
+### Slash Commands (Interactive Mode)
+
+```
+/help, /h, /?   - Display available commands
+/exit, /quit, /q - Exit CLI
+/session        - Show current session info
+/sessions       - List all saved sessions
+/clear          - Clear session history
+/config         - Display current configuration
+```
+
+## Advancing Patterns
+
+1. **Dual-Session Architecture:** Every interaction naturally produces both technical clarity and resonant meaning without user configuration
+2. **Engine Abstraction:** Multi-engine support enables advancing toward optimal tool selection per context
+3. **Session Continuity:** Per-project persistence eliminates friction in returning to work contexts
+4. **Graceful Degradation:** Unifier failures fallback to raw output, ensuring reliable function
+
+## Implementation Reference
+
+- **Entry Point:** `src/index.ts` - Commander CLI setup
+- **Interactive Loop:** `src/cli.ts` - Readline session handling
+- **Agent Interface:** `src/geminiHeadless.ts` - Multi-engine wrapper
+- **Interpretation:** `src/unifier.ts` - Ceremonial interpretation layer
+- **Persistence:** `src/sessionStore.ts` - Session index management
+- **Configuration:** `src/config.ts` - Config file handling
+- **MCP Servers:** `src/mcp/*.ts` - JSON-RPC stdio servers (see `mcp.rispecs.md`)
+- **Sub-CLIs:** `miaco/`, `miatel/`, `miawa/` - Domain-specific CLI tools