mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/023-session-summary-diffs.rispec.md

@@ -0,0 +1,165 @@
+# RISE-023: Session Summary Diffs
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/023-session-summary-diffs.rispec.md
+
+## Creative Intent
+
+mia-code automatically generates a concise summary of all file changes when a session ends or is archived. Developers see at a glance what the agent accomplished — files modified, lines added, lines deleted, and a diff-by-diff breakdown. The summary answers the question every developer asks after an agent session: "What exactly did it change?" Session summaries make agent work reviewable, auditable, and comparable.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- When a session ends, there is no summary of what changed
+- Developers must manually run `git diff` or review their version control to understand the agent's impact
+- If the session involved multiple rounds of edits to the same file, the intermediate states are invisible
+- There is no way to compare the productivity or scope of different sessions
+- Session listings show only metadata (time, model) — not outcomes
+- Code review of agent-assisted work requires reconstructing the timeline from git history
+
+**Desired State:**
+- Every session ending (close, archive, timeout) triggers automatic summary generation
+- The summary captures: total files modified, lines added, lines deleted, per-file breakdown
+- Diffs are computed between session start snapshot and current file state
+- Summary is stored in session metadata and visible in session listings
+- Summary generation leverages the snapshot system for accurate before/after comparison
+- Summaries are structured data, queryable and renderable in different formats
+
+## Desired Outcome Definition
+
+A developer works through a 30-message session modifying 8 files. When the session ends, a summary is automatically generated and stored. Running `/sessions` shows: "8 files changed, +142 -67." Viewing the session detail shows per-file breakdown with status (added/modified/deleted), line counts, and optional inline diffs.
+
+## Natural Language Functional Description
+
+### Summary Generation Trigger
+
+Summary generation occurs when:
+1. **Session archive:** user types `/archive` or session auto-archives after inactivity
+2. **Session close:** user exits mia-code with an active session
+3. **On demand:** user types `/summary` to generate or refresh the summary
+4. **Session share:** summary is computed as part of the share payload (RISE-022)
+
+### Summary Computation Process
+
+1. **Retrieve start snapshot:** find the earliest snapshot in the session's snapshot chain (RISE-021). If no snapshots exist (no file modifications), the summary is empty.
+
+2. **Compute current state:** read the current versions of all files that appear in any snapshot during the session.
+
+3. **Generate per-file diffs:** for each file that was touched:
+   - Compare the start-snapshot version to the current version
+   - Compute unified diff text
+   - Count additions and deletions
+   - Determine status: `added` (file didn't exist at start), `modified` (file changed), `deleted` (file no longer exists)
+
+4. **Aggregate statistics:**
+   - Total files changed
+   - Total lines added across all files
+   - Total lines deleted across all files
+   - Files grouped by status (added/modified/deleted)
+
+5. **Store summary** in the session record as structured metadata.
+
+### Summary Data Structure
+
+```json
+{
+  "summary": {
+    "generated_at": 1706000000000,
+    "total_files": 8,
+    "additions": 142,
+    "deletions": 67,
+    "files_added": 2,
+    "files_modified": 5,
+    "files_deleted": 1,
+    "diffs": [
+      {
+        "path": "src/auth.ts",
+        "status": "modified",
+        "additions": 35,
+        "deletions": 12,
+        "patch": "@@ -1,12 +1,35 @@\n-old line\n+new line\n..."
+      },
+      {
+        "path": "src/types.ts",
+        "status": "added",
+        "additions": 45,
+        "deletions": 0,
+        "patch": "@@ -0,0 +1,45 @@\n+export interface User {\n..."
+      },
+      {
+        "path": "src/legacy.ts",
+        "status": "deleted",
+        "additions": 0,
+        "deletions": 38,
+        "patch": "@@ -1,38 +0,0 @@\n-export class Legacy {\n..."
+      }
+    ]
+  }
+}
+```
+
+### Display in Session List
+
+The `/sessions` command includes summary data when available:
+
+```
+Sessions for /projects/myapp:
+  abc123  Fix auth middleware     2025-01-23 10:00  45 msgs  8 files  +142 -67
+  def456  Add user profile page  2025-01-24 09:00  20 msgs  3 files  +89 -5
+  ghi789  Refactor database      2025-01-25 14:00  60 msgs  12 files +203 -156
+```
+
+### Display in Session Detail
+
+The `/session abc123` command shows the full breakdown:
+
+```
+Session: Fix auth middleware (abc123)
+Started: 2025-01-23 10:00 | Messages: 45 | Model: claude-sonnet
+
+File Changes:
+  M src/auth.ts          +35 -12
+  M src/middleware.ts     +22 -8
+  M src/routes.ts        +15 -20
+  M src/utils.ts         +10 -5
+  M src/config.ts        +5 -2
+  A src/types.ts         +45
+  A src/validators.ts    +10
+  D src/legacy.ts        -38
+
+Total: 8 files | +142 -67
+```
+
+### Summary Without Snapshots
+
+If the snapshot system (RISE-021) is not available or no snapshots were taken:
+- Summary generation falls back to scanning session messages for tool calls that modified files
+- Additions and deletions are estimated from tool call arguments (edit content, file writes)
+- A flag `"estimated": true` is set in the summary metadata
+- The summary is less accurate but still useful
+
+### Incremental Summary
+
+During a long session, `/summary` can be called at any time to see a running summary. This computes the diff between the session start and the current state, without waiting for the session to end. Useful for mid-session progress checks.
+
+## Supporting Structures
+
+- **Session Revert/Snapshot (RISE-021)** provides the before-state for accurate diff computation
+- **Session Persistence (RISE-018)** stores summary metadata in the sessions table
+- **Session Sharing (RISE-022)** includes the summary in shared session views
+- **Structured Logging (RISE-007)** logs summary generation events and timing
+- **Named Error System (RISE-006)** provides SummaryGenerationError, SnapshotMissingError
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Daily Standup Review:**
+A developer starts their day by running `/sessions --since yesterday`. They see three sessions from the previous day with summary data: one session changed 5 files (+80 -20), another changed 12 files (+200 -150). The summaries give an instant overview of yesterday's agent-assisted work.
+
+**Scenario 2 — Code Review Preparation:**
+Before submitting a PR, the developer reviews the session summary to ensure the agent's changes are complete. The per-file breakdown shows `src/test.ts` was modified but `src/test.spec.ts` was not — reminding them to add tests.
+
+**Scenario 3 — Session Comparison:**
+Two forked sessions (RISE-020) explored different approaches. Their summaries show: fork A changed 3 files (+50 -10), fork B changed 8 files (+200 -90). The developer chooses fork A for its smaller, more focused changeset.
+
+**Scenario 4 — Team Metrics:**
+Over time, session summaries provide aggregate data: how many files does the agent typically modify per session? What's the ratio of additions to deletions? These metrics help teams calibrate their agent usage and identify sessions that may need human review.

package/rispecs/borrowed_from_opencode/024-child-sessions.rispec.md

@@ -0,0 +1,164 @@
+# RISE-024: Child Sessions
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/024-child-sessions.rispec.md
+
+## Creative Intent
+
+mia-code supports nested conversation branches where subagents and explicit user branches create child sessions within a parent context. A child session is a focused conversation with its own message history that inherits the parent's project context and flows results back when complete. This mirrors how developers naturally decompose work: a main task spawns subtasks, each with its own scope, and results roll up to the parent. The session tree becomes a map of how complex problems were decomposed and solved.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Subagent invocations (RISE-015) execute within the parent session's message history, creating noise
+- Long tool outputs from subagent work clutter the parent conversation
+- There is no isolation between the main task and delegated subtasks
+- When a subagent explores a tangent, all of its messages consume parent context window budget
+- No mechanism exists to track which parts of a session were "main work" vs "delegated exploration"
+- Subagent results are inlined as tool results, losing their conversational structure
+
+**Desired State:**
+- Subagent invocations create child sessions with `parent_id` linking back to the parent
+- Child sessions have their own message history, compaction, and snapshot chains
+- When a child completes, a summary of its results flows back to the parent as a single message
+- The parent's context window is preserved — only the child's result summary consumes tokens
+- Child sessions can themselves spawn children (bounded depth)
+- The full session tree is navigable and visualizable
+
+## Desired Outcome Definition
+
+The agent encounters a complex subtask (e.g., "research the best pagination library") and spawns a child session. The child session runs its own conversation with the research agent, evaluating options across 15 messages. When complete, the parent receives a single message: "Research complete: recommend cursor-based pagination using Prisma's built-in support." The parent's context window spent only 1 message instead of 15.
+
+## Natural Language Functional Description
+
+### Child Session Creation
+
+Child sessions are created by:
+1. **Subagent invocation (RISE-015):** when a subagent is delegated a task, a child session is automatically created
+2. **Explicit command:** `/branch [title]` creates a child of the current session
+3. **Programmatic:** `sessionDB.createChildSession(parentId, opts)` for API-driven creation
+
+The creation process:
+1. Create a new session row with `parent_id` set to the current session's ID
+2. Copy project context: `directory`, `project_id`, `version`
+3. Add an initial system message with the parent context: current task state, relevant files, active constraints
+4. If created by subagent: include the delegation prompt as the first user message
+5. Return the child session ID
+
+### Parent-Child Communication
+
+**Downward (parent → child):**
+- Initial context: project state, relevant files, task description
+- The child receives enough context to work independently
+- No ongoing message sync — the child operates autonomously
+
+**Upward (child → parent):**
+- When the child session completes (or is manually closed), a result message is generated
+- The result message is a structured summary: outcome, files changed, key findings
+- This message is inserted into the parent's message history as a `tool_result` part
+- The parent agent continues with full knowledge of what the child accomplished
+
+### Result Flow
+
+When a child session completes:
+1. Generate a session summary (RISE-023) capturing file changes
+2. Create a result summary: concise narrative of what was accomplished
+3. Insert into parent session as a message with parts:
+   ```json
+   {
+     "role": "system",
+     "parts": [
+       {
+         "type": "tool_result",
+         "title": "Child session: Research pagination library",
+         "content": "Evaluated 3 libraries. Recommend cursor-based pagination...",
+         "metadata": {
+           "child_session_id": "child-abc",
+           "message_count": 15,
+           "files_changed": 2,
+           "duration_ms": 45000
+         }
+       }
+     ]
+   }
+   ```
+4. Mark the child session as archived
+
+### Tree Navigation
+
+**`/sessions --tree`** shows the full hierarchy:
+```
+Session Tree for /projects/myapp:
+  ● implement-auth (active) — 30 messages
+    ├─ research-jwt-libs (complete) — 12 messages, 0 files
+    ├─ implement-middleware (complete) — 25 messages, 3 files
+    │   └─ fix-token-refresh (complete) — 8 messages, 1 file
+    └─ write-auth-tests (active) — 5 messages, 2 files
+```
+
+**`/children`** lists direct children of the current session:
+```
+Child sessions:
+  research-jwt-libs    complete  12 msgs  0 files
+  implement-middleware  complete  25 msgs  3 files  +89 -12
+  write-auth-tests     active    5 msgs   2 files  +34 -0
+```
+
+**`/parent`** navigates to the parent session.
+
+### Shared Resources
+
+Child sessions share with their parent:
+- **Project directory:** same working directory, same files
+- **Snapshot state (RISE-021):** children create their own snapshots but operate on the same filesystem
+- **Configuration:** model, permissions, and preferences inherited from parent
+
+Child sessions have independently:
+- **Message history:** completely separate conversation
+- **Compaction (RISE-019):** child sessions compact independently
+- **Context window:** each child has its own full context budget
+
+### Promotion
+
+**`/promote`** converts a child session into a top-level session:
+- Sets `parent_id` to null
+- Preserves all messages and history
+- The session no longer appears in the parent's tree
+- Useful when a "subtask" grows into its own significant body of work
+
+### Depth Limits
+
+- Maximum child depth: 5 levels (configurable via `sessions.maxChildDepth`)
+- Each level adds overhead for result flow — deep nesting is discouraged
+- Attempting to create a child beyond the limit produces a ChildDepthExceededError
+
+### Lifecycle
+
+Child session states:
+- `active` — currently receiving messages
+- `completing` — generating result summary for parent
+- `complete` — result has been sent to parent, session is archived
+- `abandoned` — child was closed without completing (no result flows to parent)
+
+## Supporting Structures
+
+- **Session Persistence (RISE-018)** provides `parent_id` column and session tree queries
+- **Subagent Task Delegation (RISE-015)** triggers child session creation for delegated work
+- **Session Summary Diffs (RISE-023)** generates the file change summary for completed children
+- **Session Compaction (RISE-019)** — each child compacts independently to manage its context
+- **Session Forking (RISE-020)** — forks and children both use `parent_id` but serve different purposes: forks diverge, children delegate
+- **Named Error System (RISE-006)** provides ChildDepthExceededError, ChildResultFlowError
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Parallel Research:**
+The agent needs to choose between three database options. It spawns three child sessions, each researching one option. All three complete with recommendations. The parent receives three concise result messages and makes an informed decision — without 45 messages of research cluttering the main conversation.
+
+**Scenario 2 — Delegated Bug Fix:**
+While building a feature, the agent encounters a failing test. It spawns a child session to investigate and fix the test. The child session resolves the issue in 8 messages. The parent receives: "Fixed test: missing mock for database connection. Modified test/db.spec.ts (+5 -2)." Feature development continues uninterrupted.
+
+**Scenario 3 — Human-Initiated Branch:**
+A developer types `/branch explore-caching` to create a focused subtask. They work with the agent on caching strategies in the child session. When satisfied, they close the child. The parent session receives the result and the developer continues the main task with caching decisions made.
+
+**Scenario 4 — Deep Decomposition:**
+A complex migration task spawns children for each subsystem: auth, billing, profiles. The auth child spawns its own child for token migration. The tree visualizes the entire decomposition, making the migration's structure visible and auditable.

package/rispecs/borrowed_from_opencode/025-session-title-generation.rispec.md

@@ -0,0 +1,162 @@
+# RISE-025: Session Title Generation
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/025-session-title-generation.rispec.md
+
+## Creative Intent
+
+mia-code automatically generates concise, descriptive titles for sessions so developers can identify and navigate their work at a glance. Instead of sessions labeled by timestamp or UUID, each session gets a human-readable title like "Fix JWT token refresh bug" or "Add user profile page." Titles are generated by a lightweight agent on the first user message, updated if scope shifts significantly, and manually overridable. The session list becomes a readable changelog of developer-agent interactions.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Sessions are identified only by UUID and timestamps — meaningless to human readers
+- The session list (`/sessions`) shows opaque identifiers that require opening each session to understand its purpose
+- Developers cannot quickly locate a past session without scrolling through all of them
+- No automated labeling exists — if a title field exists, it remains empty or requires manual entry
+- Finding "that session where I fixed the auth bug last Tuesday" requires opening multiple sessions
+
+**Desired State:**
+- Every session receives an automatic title within seconds of the first user message
+- Titles are concise (5-8 words), descriptive, and actionable
+- Title generation uses a lightweight, fast agent call — minimal latency and cost
+- Titles can be manually overridden via `/title` command
+- If the session's scope changes significantly, the title updates automatically
+- Session listings are immediately scannable and meaningful
+
+## Desired Outcome Definition
+
+A developer sends their first message: "The login page throws a 500 error when using Google OAuth." Within 2 seconds, the session title updates to "Fix Google OAuth login 500 error." The `/sessions` list shows this title alongside the session, making it instantly identifiable days later.
+
+## Natural Language Functional Description
+
+### Title Generation Trigger
+
+Title generation occurs when:
+1. **First user message:** the primary trigger — generates the initial title
+2. **Scope change detection:** after every Nth message (configurable, default: 15), the system checks if the session scope has shifted significantly
+3. **Manual override:** `/title <new title>` sets the title directly, disabling auto-updates
+
+### Title Agent
+
+The title generation uses a dedicated lightweight agent with a focused prompt:
+
+```
+You are a session title generator. Given the user's message(s) from a coding
+assistant session, generate a concise title that describes the session's purpose.
+
+Rules:
+- 5 to 8 words maximum
+- Use action verbs: "Fix", "Add", "Refactor", "Debug", "Implement", "Update"
+- Be specific: mention the feature, file, or system involved
+- No punctuation at the end
+- No articles at the start ("The", "A")
+
+Examples:
+- "Fix JWT token refresh race condition"
+- "Add pagination to user list API"
+- "Refactor database connection pooling"
+- "Debug memory leak in worker threads"
+- "Implement webhook retry with backoff"
+```
+
+The agent receives:
+- For initial title: the first user message
+- For scope change: the first user message plus the most recent 3 messages
+
+### Title Generation Process
+
+1. User sends first message in a new session
+2. After the message is stored, an async title generation task fires
+3. The title agent processes the message and returns a title string
+4. The title is stored in `sessions.title` via `sessionDB.updateSession(id, {title})`
+5. The UI updates to show the new title (via event bus if client-server architecture is active)
+
+Title generation is non-blocking — it runs asynchronously and does not delay the agent's response to the user's actual message.
+
+### Scope Change Detection
+
+Every 15 messages, the system compares the current conversation direction to the title:
+1. Extract the latest 3 messages (user + assistant)
+2. Send to the title agent with the current title and instruction: "Does this title still accurately describe the session? If the session has significantly changed focus, generate a new title. If it still fits, respond with 'KEEP'."
+3. If the agent returns a new title, update the session
+4. If "KEEP", do nothing
+
+Scope change detection is disabled when:
+- The title was manually set via `/title`
+- The session has been compacted (compaction summary may not reflect current direction)
+
+### Manual Override
+
+**`/title <new title>`** — sets the title manually:
+```
+/title Migrate database from MySQL to PostgreSQL
+```
+Response: "Session title updated to: Migrate database from MySQL to PostgreSQL"
+
+Manual titles set a `title_manual` flag in session metadata, preventing automatic updates.
+
+**`/title`** (no argument) — shows the current title and how it was generated:
+```
+Title: Fix Google OAuth login 500 error
+Generated: automatically from first message
+```
+
+### Title in Session Listings
+
+The `/sessions` command prominently displays titles:
+```
+Recent sessions:
+  abc123  Fix Google OAuth login 500 error     Jan 23 10:00  45 msgs  8 files
+  def456  Add user profile page with avatar    Jan 24 09:00  20 msgs  3 files
+  ghi789  Refactor database connection pool    Jan 25 14:00  60 msgs  12 files
+  jkl012  Debug CI pipeline timeout issues     Jan 26 11:00  15 msgs  0 files
+```
+
+### Model Selection for Title Agent
+
+The title agent uses the cheapest available model to minimize cost:
+- Default: the fastest/cheapest model configured in the system
+- Title generation typically consumes < 100 tokens
+- Cost per title generation should be negligible (< $0.001)
+- Model can be overridden via `titleGeneration.model` config
+
+### Configuration
+
+```json
+{
+  "titleGeneration": {
+    "enabled": true,
+    "model": "auto",
+    "scopeCheckInterval": 15,
+    "maxLength": 60
+  }
+}
+```
+
+- `enabled`: toggle title generation on/off
+- `model`: model to use, or `"auto"` for cheapest available
+- `scopeCheckInterval`: messages between scope change checks
+- `maxLength`: maximum character length for generated titles
+
+## Supporting Structures
+
+- **Session Persistence (RISE-018)** stores the title in the `sessions.title` column
+- **Agent Definition Config (RISE-010)** defines the title agent configuration
+- **Event Bus (RISE-002)** broadcasts title updates to connected clients
+- **Structured Logging (RISE-007)** logs title generation events and model usage
+- **Multi-Agent System (RISE-009)** provides the infrastructure for running the lightweight title agent
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Instant Identification:**
+A developer returns from lunch and runs `/sessions`. Instead of five UUIDs, they see: "Fix signup form validation," "Add dark mode toggle," "Debug WebSocket disconnects," "Refactor user service tests," "Update deployment config." They immediately find the session they want to continue.
+
+**Scenario 2 — Scope Change Detection:**
+A session starts as "Fix login page CSS" but the developer discovers the real issue is a backend API problem. After 15 messages of API debugging, the title updates to "Fix login API response format." The title reflects the actual work being done.
+
+**Scenario 3 — Team Session Review:**
+A team lead reviews shared sessions (RISE-022). Titles provide an instant overview of what each team member worked on with the agent, without opening every session. The titles serve as a natural activity log.
+
+**Scenario 4 — Search and Discovery:**
+In the future, session search can match against titles. A developer searching for "OAuth" finds their old session "Fix Google OAuth login 500 error" instantly, rather than searching through message content.