mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/048-file-read-write-tools.rispec.md

@@ -0,0 +1,205 @@
+# RISE-048: File Read/Write Tools
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/048-file-read-write-tools.rispec.md
+
+## Creative Intent
+
+mia-code provides core file read and write tools that form the foundation of all file-based agent interactions. The read tool returns file content with line numbers, handles large files gracefully, detects binary content, resolves symlinks, and respects encoding. The write tool creates or overwrites files safely, creating parent directories as needed, taking snapshots before overwrites, and validating paths against the project boundary. Both tools integrate with the permission system for fine-grained access control — allowing configurations like "read everything, write only to src/" or "deny writes to *.lock files." These are the most frequently used tools in any coding agent session.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- File operations are handled by the underlying CLI's built-in capabilities — mia-code has no control over their behavior
+- There is no line-number annotation on file reads — the agent and developer cannot reference specific lines
+- Large files are dumped entirely into the context, consuming the token budget
+- Binary files are read as garbled text, wasting context and confusing the agent
+- There is no snapshot before overwrite — accidental file corruption cannot be undone
+- No path validation — the agent can write to any location the process has access to
+- All files are treated identically regardless of permission policy
+
+**Desired State:**
+- A `file_read` tool returns content with line numbers, handles large files via truncation, and detects binary files
+- A `file_write` tool creates/overwrites files with parent directory creation, snapshot-before-overwrite, and path validation
+- Both tools enforce the permission system: read requires "read" permission, write requires "write" permission
+- Permission patterns enable fine-grained control: `{"pattern": "*.lock", "permission": "deny"}` prevents lock file modification
+- Large files are truncated with a reference to the full content
+- Binary files return metadata instead of content
+- Symlinks are resolved and validated before access
+
+## Desired Outcome Definition
+
+The agent reads `src/auth/middleware.ts` and receives clean output with line numbers. It writes a modified version back — the tool snapshots the original first, creates the backup, validates the path is within the project, checks write permission, and saves the file. If the agent tries to read a 5MB binary file, it receives `{type: "binary", size: 5242880, mime: "application/octet-stream"}` instead of garbled content.
+
+## Natural Language Functional Description
+
+### File Read Tool
+
+**Input:**
+```typescript
+interface FileReadInput {
+  path: string;                    // relative or absolute path
+  lineRange?: [number, number];    // optional line range [start, end] (1-indexed)
+  encoding?: string;               // default: "utf-8"
+}
+```
+
+**Processing pipeline:**
+
+1. **Path resolution** — resolve relative paths against project root, resolve symlinks
+2. **Path validation** — verify path is within project root (or delegate to external directory tool, RISE-047)
+3. **Permission check** — verify "read" permission for this file path pattern
+4. **Binary detection** — check first 8KB for null bytes; if binary, return metadata only
+5. **Size check** — if file exceeds truncation limit, apply truncation (RISE-036)
+6. **Encoding detection** — use specified encoding or detect from BOM/content
+7. **Line numbering** — prefix each line with its line number
+8. **Range extraction** — if `lineRange` specified, return only those lines
+
+**Output:**
+```json
+{
+  "path": "src/auth/middleware.ts",
+  "content": "1. import { verify } from 'jsonwebtoken';\n2. import { AuthError } from './errors';\n3. \n4. export function authMiddleware(req, res, next) {\n...",
+  "lineCount": 47,
+  "size": 1834,
+  "encoding": "utf-8",
+  "truncated": false
+}
+```
+
+**Binary file output:**
+```json
+{
+  "path": "assets/logo.png",
+  "binary": true,
+  "size": 524288,
+  "mime": "image/png",
+  "content": null
+}
+```
+
+### File Write Tool
+
+**Input:**
+```typescript
+interface FileWriteInput {
+  path: string;                    // relative or absolute path
+  content: string;                 // file content to write
+  createDirectories?: boolean;     // create parent dirs if missing (default: true)
+}
+```
+
+**Processing pipeline:**
+
+1. **Path resolution** — resolve relative paths against project root
+2. **Path validation** — verify path is within project root; reject external paths entirely
+3. **Permission check** — verify "write" permission for this file path pattern
+4. **Pattern check** — verify path doesn't match any deny patterns (e.g., `*.lock`, `node_modules/**`)
+5. **Parent directories** — if `createDirectories` is true and parents don't exist, create them
+6. **Snapshot** — if the file already exists, copy it to the snapshot system (RISE-076) before overwriting
+7. **Write** — atomically write the content (write to temp file, then rename)
+8. **Verify** — read back the file to confirm content matches
+
+**Output:**
+```json
+{
+  "path": "src/auth/middleware.ts",
+  "created": false,
+  "size": 1923,
+  "previousSize": 1834,
+  "snapshotId": "snap_20260301_143022",
+  "directoriesCreated": []
+}
+```
+
+For new files:
+```json
+{
+  "path": "src/auth/types.ts",
+  "created": true,
+  "size": 456,
+  "directoriesCreated": ["src/auth/"]
+}
+```
+
+### Permission Patterns
+
+File permissions support glob patterns for fine-grained control:
+
+```json
+{
+  "permissions": {
+    "file_read": { "mode": "allow" },
+    "file_write": {
+      "mode": "allow",
+      "deny": [
+        "*.lock",
+        "package-lock.json",
+        "node_modules/**",
+        ".env*",
+        ".git/**"
+      ]
+    }
+  }
+}
+```
+
+When the agent attempts to write to a denied path:
+```json
+{
+  "error": "Write denied: path 'package-lock.json' matches deny pattern '*.lock'",
+  "suggestion": "Modify package.json instead and run 'npm install' to update the lock file."
+}
+```
+
+### Symlink Resolution
+
+Both tools resolve symlinks before operations:
+
+1. Resolve the symlink chain to the final real path
+2. Validate the real path is within the project root
+3. If the real path is external, delegate to the external directory tool (RISE-047)
+4. Report the resolved path in the output for transparency
+
+This prevents symlink-based sandbox escapes while supporting legitimate project symlinks.
+
+### Atomic Writes
+
+File writes use an atomic write pattern to prevent corruption:
+
+1. Write content to a temporary file in the same directory (`.file.tmp.XXXXX`)
+2. Sync the temporary file to disk (`fsync`)
+3. Rename the temporary file to the target path (atomic on POSIX systems)
+
+If the process crashes mid-write, the original file remains intact. The temporary file is cleaned up on next startup.
+
+### Large File Handling
+
+Files exceeding the truncation threshold are handled differently for read vs write:
+
+- **Read** — truncated output with reference to full file (RISE-036). The agent can request specific line ranges for targeted reading.
+- **Write** — no size limit on writes. The agent can write files of any size. However, writing very large files produces a warning in the output.
+
+## Supporting Structures
+
+- **Tool Registry (RISE-034)** registers file_read and file_write with their respective IDs
+- **Tool Context Injection (RISE-035)** provides session context and cancellation
+- **Tool Output Truncation (RISE-036)** handles large file read outputs
+- **File Snapshot System (RISE-076)** stores pre-overwrite snapshots for undo capability
+- **Permission System (RISE-074)** enforces read/write permissions with pattern matching
+- **External Directory Tool (RISE-047)** handles paths outside the project root
+- **Named Error System (RISE-006)** provides FileNotFoundError, FilePermissionError, FileBinaryError
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Safe Overwrite:**
+The agent modifies `src/config.ts`. Before writing, the tool snapshots the original. After writing, the output shows `snapshotId: "snap_20260301_143022"`. Later, the developer says "undo that config change." The agent restores from the snapshot — no data lost.
+
+**Scenario 2 — Binary Detection:**
+The agent tries to read `assets/logo.png` as part of a file listing. Instead of injecting 500KB of garbled binary into the context, the read tool returns `{binary: true, mime: "image/png", size: 524288}`. The agent reports "logo.png is a 512KB PNG image" — useful information without context waste.
+
+**Scenario 3 — Lock File Protection:**
+The agent attempts to write to `package-lock.json` to fix a dependency issue. The permission system blocks it with a helpful suggestion: "Modify package.json instead and run npm install." The agent follows the suggestion and achieves the correct result through the proper workflow.
+
+**Scenario 4 — Line Range Reading:**
+The agent knows an error is on line 42 of a 2000-line file. Instead of reading the entire file, it requests `lineRange: [35, 50]` — getting just 16 lines of context around the error. This preserves context budget for other operations.

package/rispecs/borrowed_from_opencode/049-lsp-server-management.rispec.md

@@ -0,0 +1,104 @@
+# RISE-049: LSP Server Management
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/049-lsp-server-management.rispec.md
+
+## Creative Intent
+
+mia-code gains deep code intelligence by managing multiple Language Server Protocol servers. An agent working across a polyglot monorepo — TypeScript frontend, Python ML pipeline, Rust core — gets type-aware understanding from each language's LSP server without reading entire codebases. The developer configures once; mia-code orchestrates the lifecycle of every server, starting them lazily, restarting them on crash, and shutting them down cleanly when the session ends.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has no LSP integration — agents rely on text-based grep/glob for code understanding
+- Type information is invisible: the agent cannot know that `foo.bar()` returns a `Promise<User[]>` without reading source
+- Code navigation requires manual file reading — "go to definition" means grepping for function names
+- Each agent turn that needs type context must read and parse files, consuming tokens and time
+- No awareness of compilation errors until the agent runs `tsc` or `cargo check` explicitly
+- The three-world model (miaco/miatel/miawa) has MCP servers but no language-aware intelligence layer
+
+**Desired State:**
+- mia-code manages LSP servers as first-class infrastructure alongside MCP servers
+- Each supported language has a registered LSP server with spawn command, file extension mapping, and root detection
+- Servers start lazily on first access to a relevant file — no upfront cost for unused languages
+- Multiple LSP servers run simultaneously for polyglot projects
+- Server health is monitored: crashed servers restart automatically with backoff
+- Configuration lives in `mia-code.json` alongside existing MCP server definitions
+
+## Desired Outcome Definition
+
+A developer opens a session in a project containing TypeScript and Python files. When the agent first accesses a `.ts` file, mia-code spawns `typescript-language-server --stdio`, connects via JSON-RPC, and initializes the workspace. When the agent later touches a `.py` file, `pyright` starts alongside. Both servers run concurrently, providing type information to their respective file types. If `pyright` crashes, mia-code restarts it within seconds. When the session ends, both servers receive shutdown signals and exit cleanly.
+
+## Natural Language Functional Description
+
+### Server Registry
+
+Each LSP server is defined by a registration object:
+
+- **id**: unique identifier (e.g., `"typescript"`, `"python"`, `"rust"`)
+- **extensions**: file extensions this server handles (e.g., `[".ts", ".tsx", ".js", ".jsx"]`)
+- **rootDetection**: function that walks up from a file path looking for marker files (e.g., `tsconfig.json`)
+- **command**: spawn command as array (e.g., `["typescript-language-server", "--stdio"]`)
+- **initializationOptions**: optional LSP initialization parameters
+
+Built-in server definitions cover: TypeScript/JavaScript (tsserver via typescript-language-server), Python (pyright), Rust (rust-analyzer), Go (gopls), Java (jdtls), C/C++ (clangd). Custom servers are added via configuration.
+
+### Lifecycle Management
+
+**Lazy Start:** No LSP server starts at session begin. When a tool accesses a file with extension `.ts`, mia-code checks the registry, finds the TypeScript server definition, detects the project root (nearest `tsconfig.json`), and spawns the process. The server remains running for subsequent requests.
+
+**Health Monitoring:** A heartbeat check runs every 30 seconds. If a server process has exited unexpectedly, mia-code logs the event and schedules a restart. Restart uses exponential backoff: 1s, 2s, 4s, up to 30s maximum. After 5 consecutive failures, the server is marked as failed and requires manual intervention.
+
+**Graceful Shutdown:** On session end, each running LSP server receives a `shutdown` request followed by an `exit` notification per the LSP protocol. A 5-second timeout ensures hung servers are force-killed.
+
+### Configuration
+
+Server configuration in `mia-code.json`:
+
+```json
+{
+  "lsp": {
+    "typescript": {
+      "enabled": true,
+      "command": ["typescript-language-server", "--stdio"],
+      "extensions": [".ts", ".tsx", ".js", ".jsx"]
+    },
+    "python": {
+      "enabled": true,
+      "command": ["pyright-langserver", "--stdio"]
+    },
+    "custom-server": {
+      "enabled": true,
+      "command": ["my-lsp", "--mode", "stdio"],
+      "extensions": [".myext"],
+      "rootMarkers": ["my-project.json"]
+    }
+  }
+}
+```
+
+### Communication
+
+All LSP servers communicate via JSON-RPC 2.0 over stdio (stdin/stdout). mia-code maintains a JSON-RPC client per server that handles request/response correlation, notification dispatch, and protocol error handling. Stderr from each server is captured and routed to structured logging.
+
+## Supporting Structures
+
+- **Event Bus (RISE-002)** publishes `lsp.started`, `lsp.stopped`, `lsp.crashed`, `lsp.restarted` events
+- **Lazy Initialization (RISE-008)** provides the pattern for deferred server spawning
+- **Structured Logging (RISE-007)** captures LSP communication traces at debug level
+- **Instance State (RISE-003)** scopes LSP server instances per project workspace
+- **LSP Root Detection (RISE-052)** determines workspace roots for server initialization
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Polyglot Monorepo:**
+A developer works in a repo with `packages/web` (TypeScript), `services/ml` (Python), and `core/engine` (Rust). The agent edits across all three. Three LSP servers run simultaneously, each rooted at the appropriate subdirectory. The agent gets hover information in TypeScript, completion in Python, and diagnostics in Rust — all in the same session.
+
+**Scenario 2 — Crash Recovery:**
+The rust-analyzer process segfaults while indexing a large workspace. mia-code detects the exit, logs the crash with stderr output, waits 1 second, and restarts the server. The agent's next Rust file access works seamlessly — the brief interruption is invisible.
+
+**Scenario 3 — Custom Language Server:**
+A team uses an internal DSL with a custom LSP server. They add a `"dsl"` entry to `mia-code.json` with the server command and file extensions. mia-code treats it identically to built-in servers — lazy start, health monitoring, graceful shutdown. The agent gets type information for `.dsl` files without any code changes to mia-code itself.
+
+**Scenario 4 — Resource-Constrained Environment:**
+On a CI server with limited RAM, a developer disables Python and Rust LSP servers in config, keeping only TypeScript. mia-code respects the `"enabled": false` flags and never spawns those processes. The TypeScript server starts only when needed, minimizing resource usage.

package/rispecs/borrowed_from_opencode/050-lsp-hover-completion.rispec.md

@@ -0,0 +1,102 @@
+# RISE-050: LSP Hover and Completion
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/050-lsp-hover-completion.rispec.md
+
+## Creative Intent
+
+mia-code exposes LSP hover and completion as agent-accessible tools, giving agents type-aware understanding of code without reading entire codebases. An agent editing a TypeScript file can ask "what type does this variable have?" or "what methods are available on this object?" and receive precise answers from the language server. The agent writes better code because it sees the same type information a human developer sees in their IDE.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Agents infer types by reading source files, consuming tokens and often guessing wrong
+- No way to ask "what is the type of `response` at line 42?" without reading the full file and its imports
+- Method discovery requires reading class definitions, interface files, and type declaration files
+- Completion suggestions are nonexistent — agents guess method names from memory or grep results
+- An agent editing a function has no way to know the return type of a called function without tracing through source
+- Token budgets are wasted on reading `.d.ts` files and tracing import chains for type context
+
+**Desired State:**
+- A `lsp` tool is available to agents with `hover` and `completion` actions
+- Hover returns precise type signatures, documentation, and definition locations for any position in any file
+- Completion returns ranked suggestions with kind labels (method, property, class, variable)
+- Agents interact with LSP capabilities through the same tool interface as any other mia-code tool
+- Type queries are cheap: a single JSON-RPC call replaces reading multiple files
+
+## Desired Outcome Definition
+
+An agent working on a TypeScript file calls the `lsp` tool with `{action: "hover", file: "src/api/users.ts", line: 42, character: 15}` and receives back `{type: "(method) UserService.findByEmail(email: string): Promise<User | null>", documentation: "Find a user by their email address. Returns null if not found.", definition: "src/services/user.service.ts:87:3"}`. The agent now knows the return type without reading the service file.
+
+## Natural Language Functional Description
+
+### Hover Action
+
+The hover action sends a `textDocument/hover` LSP request for the specified file and position.
+
+**Input:**
+```json
+{
+  "action": "hover",
+  "file": "src/api/users.ts",
+  "line": 42,
+  "character": 15
+}
+```
+
+**Processing:**
+1. Resolve the file path to an absolute URI
+2. Identify the appropriate LSP server from the file extension (RISE-049)
+3. Ensure the server is running (lazy-start if needed)
+4. Send `textDocument/hover` with the position
+5. Optionally send `textDocument/definition` for the definition location
+6. Format the response for agent consumption
+
+**Output:**
+```json
+{
+  "type": "(method) UserService.findByEmail(email: string): Promise<User | null>",
+  "documentation": "Find a user by their email address. Returns null if not found.",
+  "definition": {
+    "file": "src/services/user.service.ts",
+    "line": 87,
+    "character": 3
+  }
+}
+```
+
+If no hover information is available at the position, the tool returns `{type: null, message: "No type information available at this position"}`.
+
+### Completion Action
+
+The completion action sends a `textDocument/completion` LSP request.
+
+**Input:** `{action: "completion", file: "src/api/users.ts", line: 42, character: 15}`. Processing: resolve file path, sync document state, send `textDocument/completion`, sort by relevance, limit to top 20, map kinds to labels.
+
+**Output:** sorted list of items with `label`, `kind` (method/property/class), `detail` (type signature), and `insertText` (snippet).
+
+### Document Synchronization and Error Handling
+
+The tool manages document state with the LSP server. On first access, a `textDocument/didOpen` notification is sent; subsequent modifications trigger `textDocument/didChange`. If no LSP server is configured for the file type, the tool returns an error listing available servers. If the server is still initializing, requests wait up to 10 seconds before timing out.
+
+## Supporting Structures
+
+- **LSP Server Management (RISE-049)** provides server lifecycle and communication
+- **LSP Root Detection (RISE-052)** ensures the server is initialized with the correct workspace
+- **File Read/Write Tools (RISE-048)** coordinate document synchronization on file changes
+- **Agent Permission Rulesets (RISE-011)** govern which files the agent can query
+- **LSP Diagnostics (RISE-051)** complements hover/completion with error information
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Type-Aware Editing:**
+An agent is asked to add error handling to a function. It hovers over the function's return value and discovers it returns `Result<Data, ApiError>`. It hovers over `ApiError` and finds it's a union type with variants. The agent writes a proper match/switch covering all error variants — something it couldn't do by reading only the current file.
+
+**Scenario 2 — Method Discovery:**
+An agent needs to filter a list but doesn't know the exact API. It requests completion on the array variable and sees `filter`, `find`, `findIndex`, `some`, `every` with their signatures. It picks the right method with the correct parameter types on the first try.
+
+**Scenario 3 — Cross-File Understanding:**
+An agent is reviewing a Python file that calls `db.session.query(User).filter_by(email=email).first()`. It hovers over `.first()` and learns it returns `Optional[User]`. It hovers over `filter_by` and sees the signature. No need to read SQLAlchemy source — the type information is immediate.
+
+**Scenario 4 — Verifying Edits:**
+After writing a new function call, the agent hovers over the call site to verify the types match. The hover shows `Argument of type 'number' is not assignable to parameter of type 'string'` — the agent catches its own mistake before any build step.

package/rispecs/borrowed_from_opencode/051-lsp-diagnostics.rispec.md

@@ -0,0 +1,86 @@
+# RISE-051: LSP Diagnostics
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/051-lsp-diagnostics.rispec.md
+
+## Creative Intent
+
+mia-code provides real-time code diagnostics from LSP servers to agents, enabling a self-correcting edit cycle. After every file modification, the agent can see type errors, missing imports, and warnings — the same feedback loop a human gets from red squiggly lines in their editor. The agent no longer waits for a full build to discover mistakes; it catches them at the speed of thought.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Agents discover errors only by running build commands (`tsc`, `cargo check`, `pytest`)
+- A full build cycle can take 30+ seconds, wasting time on errors a type checker catches instantly
+- Build output is unstructured text that must be parsed to extract file, line, and error message
+- No automatic feedback after file writes — the agent must explicitly decide to check for errors
+- Warning-level issues (unused variables, deprecated APIs) are invisible until a linter is run
+- Multiple edit-build-fix cycles consume agent turns and tokens for problems LSP solves in milliseconds
+
+**Desired State:**
+- After any file modification, diagnostics are collected automatically from active LSP servers
+- A `diagnostics` tool returns structured error/warning/info/hint data for any file or the entire project
+- Auto-diagnostic mode: file write tools automatically check diagnostics and report issues inline
+- Diagnostic counts are visible in session status, giving the agent ambient awareness of code health
+- The agent self-corrects based on immediate LSP feedback without running builds
+
+## Desired Outcome Definition
+
+An agent writes a TypeScript file with a type error. Within 500ms, the LSP server publishes diagnostics. The agent calls the diagnostics tool and receives a structured list: file path, line range, severity, message, and source server. The agent fixes the error and calls diagnostics again — zero errors. No build command was ever run.
+
+## Natural Language Functional Description
+
+### Diagnostics Tool
+
+**Input:** `{action: "diagnostics"}` for all files, or `{action: "diagnostics", file: "src/api/users.ts"}` for a specific file.
+
+**Output:** structured list of diagnostics, each containing:
+- `file`: the file path with the issue
+- `range`: start and end position (line/character)
+- `severity`: error, warning, info, or hint
+- `message`: human-readable diagnostic message
+- `source`: which LSP server produced this diagnostic
+- `code`: language-specific error code (e.g., `ts(2551)`)
+
+Plus a summary object with counts per severity level and total files with issues.
+
+### Diagnostic Collection
+
+mia-code listens for `textDocument/publishDiagnostics` notifications from all active LSP servers. These notifications arrive asynchronously after file changes. Diagnostics are stored in a per-file map, keyed by server ID to avoid cross-server conflicts.
+
+When the diagnostics tool is called:
+1. If a specific file is requested, return diagnostics only for that file
+2. If no file is specified, return diagnostics across all files with issues
+3. Results are aggregated across all active LSP servers (TypeScript errors + ESLint warnings together)
+4. Diagnostics are sorted: errors first, then warnings, then info, then hints
+5. Within each severity, sorted by file path then line number
+
+### Auto-Diagnostic After File Write
+
+When the file write tool (RISE-048) modifies a file, mia-code sends `textDocument/didChange` and waits up to 2 seconds for diagnostics. Errors are appended to the write output: `⚠ 1 error detected after write: ...`. Clean writes show `✓ No diagnostics issues detected`. This auto-check is configurable: `{"lsp": {"autoDiagnostics": true}}` (default: true).
+
+### Severity, Status, and Staleness
+
+Severity levels: **error** (won't compile), **warning** (potential issues), **information** (suggestions), **hint** (style notes). The session status line shows diagnostic counts when issues exist. Diagnostics older than 30 seconds are marked as potentially stale. If no LSP server is active for a file type, the tool returns a clear notice.
+
+## Supporting Structures
+
+- **LSP Server Management (RISE-049)** provides the server connections that publish diagnostics
+- **LSP Hover/Completion (RISE-050)** complements diagnostics with type exploration
+- **Event Bus (RISE-002)** publishes `lsp.diagnostics.updated` events when diagnostic state changes
+- **File Read/Write Tools (RISE-048)** trigger document sync and auto-diagnostic checks
+- **Structured Logging (RISE-007)** records diagnostic events for debugging
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Self-Correcting Edit:**
+An agent adds a new function call with a typo in a property name. The auto-diagnostic fires and reports `Property 'emial' does not exist on type 'User'. Did you mean 'email'?` inline with the write output. The agent immediately corrects the typo in its next tool call — no build step, no wasted turn.
+
+**Scenario 2 — Multi-Language Diagnostics:**
+An agent refactors a Python backend and TypeScript frontend simultaneously. After editing `api.py`, pyright reports a missing import. After editing `client.ts`, tsserver reports an incompatible type. The agent calls `diagnostics` with no file filter and sees both issues in one structured response, fixing them in order.
+
+**Scenario 3 — Clean Verification:**
+After completing a complex refactoring across 12 files, the agent calls the diagnostics tool. Zero errors, zero warnings. The agent reports to the user with confidence that the refactoring is type-safe — no need to run a full build.
+
+**Scenario 4 — Warning Cleanup:**
+A developer asks "clean up all warnings in this project." The agent calls diagnostics, receives 15 warnings across 8 files (unused imports, deprecated APIs, unnecessary type assertions). It systematically fixes each one, checking diagnostics after each file to confirm the warning is resolved.

package/rispecs/borrowed_from_opencode/052-lsp-root-detection.rispec.md

@@ -0,0 +1,109 @@
+# RISE-052: LSP Root Detection
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/052-lsp-root-detection.rispec.md
+
+## Creative Intent
+
+mia-code intelligently detects project roots for each LSP server, so language servers initialize with the correct workspace context. A monorepo with a TypeScript frontend at `packages/web` and a Python backend at `services/api` gets two separate roots — each language server sees only its relevant project tree. Root detection is automatic, cached, and overridable, ensuring LSP servers provide accurate results without manual configuration.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code sessions have a single project root (the directory where the session started)
+- No mechanism to detect language-specific project boundaries within a larger workspace
+- A TypeScript language server initialized at the monorepo root may miss nested `tsconfig.json` configurations
+- Python LSP servers need the virtualenv root, which differs from the git root
+- No caching: if root detection were added naively, it would walk the filesystem on every file access
+- Monorepo projects with multiple package managers and build systems have no structured handling
+
+**Desired State:**
+- Each language has defined root markers (config files that indicate a project boundary)
+- Root detection walks up from a file's location, finding the nearest marker
+- Monorepo support: different files can resolve to different roots for the same language
+- Detection results are cached per file extension to avoid repeated filesystem walks
+- Explicit overrides in configuration allow developers to pin roots for specific languages
+- Exclusion patterns prevent detection from crossing into `node_modules` or other non-project directories
+
+## Desired Outcome Definition
+
+An agent accesses `packages/web/src/App.tsx` in a monorepo. Root detection walks up from `packages/web/src/` and finds `packages/web/tsconfig.json`. The TypeScript LSP server initializes with `packages/web` as its root, correctly resolving path aliases and dependencies. Later, the agent accesses `services/api/main.py`. Root detection finds `services/api/pyproject.toml` and initializes pyright with that root. Each server sees its own isolated project context.
+
+## Natural Language Functional Description
+
+### Root Markers Per Language
+
+Each language defines an ordered list of root marker files. Detection stops at the first marker found while walking up:
+
+| Language | Root Markers (priority order) |
+|----------|-------------------------------|
+| TypeScript/JavaScript | `tsconfig.json`, `jsconfig.json`, `package.json` |
+| Python | `pyproject.toml`, `setup.py`, `setup.cfg`, `requirements.txt`, `Pipfile` |
+| Rust | `Cargo.toml` |
+| Go | `go.mod` |
+| Java | `pom.xml`, `build.gradle`, `build.gradle.kts` |
+| C/C++ | `CMakeLists.txt`, `compile_commands.json`, `Makefile` |
+
+Custom languages define their markers in configuration via `rootMarkers` array.
+
+### Detection Algorithm
+
+Given a file path (e.g., `/repo/packages/web/src/components/Button.tsx`):
+
+1. Determine the file extension → map to language → get root markers list
+2. Start at the file's parent directory (`/repo/packages/web/src/components/`)
+3. Check if any root marker file exists in this directory
+4. If found, return this directory as the root
+5. If not found, move to the parent directory
+6. Repeat until a root marker is found or a stop condition is met
+7. Stop conditions: reaching filesystem root, encountering `.git` directory (use this as fallback root), encountering an excluded directory
+
+**Exclusion patterns:** The walk skips into but does not cross through: `node_modules`, `.git`, `vendor`, `__pycache__`, `.venv`, `venv`. These directories are never considered as potential roots.
+
+### Monorepo Support
+
+Multiple roots per language are fully supported. In a monorepo:
+
+```
+/repo
+├── packages/
+│   ├── web/          ← tsconfig.json here → root for web TS files
+│   │   └── src/
+│   └── shared/       ← tsconfig.json here → root for shared TS files
+│       └── src/
+├── services/
+│   └── api/          ← pyproject.toml here → root for Python files
+│       └── src/
+└── package.json      ← fallback root for JS files outside packages
+```
+
+Files in `packages/web/src/` resolve to `packages/web/`. Files in `packages/shared/src/` resolve to `packages/shared/`. Each may initialize a separate LSP server instance, or the server may support multi-root workspaces (LSP `workspace/workspaceFolders`).
+
+### Caching Strategy
+
+Root detection results are cached in a `filePath → detectedRoot` map, populated on first access and invalidated on config changes or root marker file creation/deletion. Directory-level caching ensures all files in a subtree reuse a resolved root without re-walking. The cache is not persisted across sessions.
+
+### Configuration Override and Fallback
+
+Developers can pin roots in `mia-code.json`: `{"lsp": {"python": {"root": "./services/api"}, "typescript": {"roots": ["./packages/web", "./packages/shared"]}}}`. When configured, automatic detection is skipped. Paths are relative to `mia-code.json`. If no root marker is found, fallback order is: nearest `.git` parent → session project root → file's parent directory.
+
+## Supporting Structures
+
+- **LSP Server Management (RISE-049)** uses detected roots for server initialization
+- **Instance State (RISE-003)** provides the session's default project root as fallback
+- **Structured Logging (RISE-007)** logs root detection decisions for debugging
+- **Namespace Module Pattern (RISE-004)** organizes root detection as a pure utility module
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Automatic Monorepo Handling:**
+A developer opens a session at the root of a monorepo with 12 packages. As the agent works across packages, each file triggers root detection. The TypeScript server initializes with multi-root workspace folders for `packages/web` and `packages/shared`. Path aliases like `@shared/utils` resolve correctly because each root has its own `tsconfig.json`.
+
+**Scenario 2 — Python Virtual Environment:**
+A Python project has `pyproject.toml` at `/repo/backend/`. The agent accesses `backend/src/api/routes.py`. Root detection finds `pyproject.toml` and sets the root to `/repo/backend/`. Pyright initializes with the correct `pythonPath` from the project's `.venv`, resolving all imports correctly.
+
+**Scenario 3 — Override for Non-Standard Layout:**
+A project has its TypeScript config at an unusual path: `config/tsconfig.base.json` is the real root config, but `package.json` exists at the repo root. The developer adds `"typescript": {"root": "."}` to `mia-code.json` to pin the root, preventing detection from choosing a nested `package.json` in a subdirectory.
+
+**Scenario 4 — New Project Bootstrap:**
+An agent creates a new Rust project with `cargo init`. Root detection cache has no entry for `.rs` files in this directory. On the next Rust file access, detection walks up, finds the new `Cargo.toml`, caches the result, and initializes rust-analyzer at the correct root — all automatic, no configuration needed.