mia-code 0.2.0 → 0.3.0

package/rispecs/pi-mono-envisionning/ENVISIONING.md

@@ -0,0 +1,366 @@
+# mia-pi-mono Envisioning — Porting mia-code into the Pi Harness Fork
+
+> RISE Framework Envisioning v1.0
+> Document: mia-code/rispecs/pi-mono-envisionning/ENVISIONING.md
+> Date: 2026-03-20
+
+---
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code exists as a standalone CLI wrapping Gemini/Claude in headless mode with custom readline, Enquirer menus, and ANSI rendering
+- miadi-code (in `/a/src/Miadi`) was an ambitious attempt to build a Three-Universe terminal agent with dashboard TUI, PDE, STC, multiline input — all implemented but **within a custom-built framework that hit scaling limits**
+- The pi-mono harness (`@mariozechner/pi-coding-agent`) provides a **production-grade extension system**: Widget placement, Component interface, custom tools, event bus, session management, TUI with differential rendering, overlays, themes, web-ui with LitElement ChatPanel + artifacts
+- We forked pi-mono to `/workspace/repos/miadisabelle/mia-pi-mono/` — it has all 7 packages: `agent`, `ai`, `coding-agent`, `mom`, `pods`, `tui`, `web-ui`
+- Our mia-code sub-CLIs (miaco, miatel, miawa) already work as MCP servers via stdio JSON-RPC
+
+**Desired Outcome:**
+- A **mia-pi-mono** fork where the pi harness becomes the foundation for the Three-Universe agent experience
+- The "Two-Eye-Seen" (🧠 Mia / 🌸 Miette) dual-perspective lives natively in the UI — not as a post-hoc unifier call but as a **structural rendering mode**
+- miaco's PDE + STC capabilities are available as pi extension tools the LLM can call
+- miawa's ceremony/storytelling capabilities inform the session lifecycle
+- The web-ui ChatPanel gains ceremonial rendering (artifacts for STC charts, PDE visualizations)
+
+---
+
+## What the Pi Extension System Already Gives Us
+
+The pi harness `ExtensionAPI` is remarkably aligned with what miadi-code built from scratch:
+
+| miadi-code Built Custom | Pi Harness Has Built-In |
+|------------------------|------------------------|
+| `MultilineInput` (raw mode, Ctrl+J) | `EditorComponent` with `setEditorComponent()` — already handles multiline, paste, cursor |
+| `StructuralTensionDashboard` (full-screen TUI) | `ctx.ui.custom()` — shows any `Component` with full keyboard focus |
+| Dashboard menu (Enquirer) | `ctx.ui.select()`, `ctx.ui.confirm()`, `ctx.ui.input()` — built-in dialogs |
+| `/stc`, `/pde`, `/charts` slash commands | `api.registerCommand()` — first-class slash command registration |
+| Formatting/styling with chalk | `Theme` system with `ctx.ui.theme` — consistent theming |
+| Session persistence (custom JSON) | `SessionManager` with branching, forking, compaction, tree navigation |
+| Three-Universe processor | `on("input")` event → transform/route prompts before agent processes them |
+| Unifier (post-agent interpretation) | `on("agent_end")` event → intercept and augment output |
+| `setWidget()` for above/below editor | **Widgets!** — the "Widget" from the video, `WidgetPlacement: "aboveEditor" \| "belowEditor"` |
+| Custom header/footer | `ctx.ui.setHeader()`, `ctx.ui.setFooter()` — factory functions returning Components |
+| Status indicators | `ctx.ui.setStatus(key, text)` — footer status bar entries |
+| MCP servers (miaco/miatel/miawa) | `api.registerTool()` — LLM-callable tools with schema, execute, custom rendering |
+
+### Key Insight: Everything miadi-code struggled to build is an Extension
+
+The pi harness solves the infrastructure problem. We focus on the **creative layer**.
+
+---
+
+## Architecture: mia-code as Pi Extensions
+
+### Extension 1: `miette-echo` — Two-Eye-Seen (Core)
+
+**Source:** `mia-code/widget/miette-echo/index.ts` ✅ CREATED
+
+**The Insight:** Mia IS the agent. The system prompt makes her the voice. Her structural perspective is the normal assistant response — no extra unifier needed for that. Miette is the echo widget below the input, reflecting on what just happened.
+
+**Two-Eye-Seen spatial layout:**
+- Look **up** → 🧠 Mia's work (the chat messages — she IS the agent)
+- Look **down** → 🌸 Miette's echo (widget below editor — quiet resonant reflection)
+
+**Implementation:**
+```
+api.on("agent_end", async (event, ctx) => {
+  const text = extractAssistantText(event.messages);
+  // Lightweight LLM call with Miette's system prompt
+  const echo = await generateMietteReflection(ctx.model, text);
+  ctx.ui.setWidget("miette-echo", renderEcho(echo), { placement: "belowEditor" });
+});
+```
+
+**What Changes from Current mia-code:**
+- No more spawning a separate Claude process for unification
+- Mia's voice comes from the system prompt, not a post-processing step
+- Miette's echo is an in-process LLM call via current model
+- Lives as a persistent widget that updates after every agent turn
+- `/miette on|off` toggles visibility
+
+### Extension 2: `mia-pde` — Prompt Decomposition Engine
+
+**Purpose:** Complex prompts get decomposed before agent execution.
+
+**Implementation:**
+```
+api.on("input", async (event, ctx) => {
+  const complexity = assessComplexity(event.text);
+  if (complexity.needsDecomposition) {
+    const decomposition = await pdeDecompose(event.text);
+    // Show decomposition preview as overlay
+    const proceed = await ctx.ui.custom((tui, theme, kb, done) => {
+      return new PdePreviewComponent(decomposition, theme, done);
+    });
+    if (proceed) {
+      return { action: "transform", text: decomposition.executionPlan };
+    }
+  }
+  return { action: "continue" };
+});
+```
+
+**Registered Tools (LLM-callable):**
+```
+api.registerTool({
+  name: "pde_decompose",
+  description: "Decompose a complex prompt into structured intents",
+  parameters: Type.Object({ prompt: Type.String() }),
+  execute: async (id, params) => { /* Layer 1-5 pipeline */ },
+  renderResult: (result, opts, theme) => new PdeResultComponent(result, theme)
+});
+```
+
+**Slash Commands:**
+```
+api.registerCommand("pde", {
+  description: "Prompt Decomposition Engine",
+  handler: async (args, ctx) => { /* /pde decompose, /pde list, /pde wheel */ }
+});
+```
+
+### Extension 3: `mia-stc` — Structural Tension Charts
+
+**Purpose:** Track desired outcomes vs current reality with visual charts.
+
+**Registered Tools:**
+- `stc_chart_create` — Create chart with outcome + reality
+- `stc_chart_step` — Add action step
+- `stc_chart_complete` — Mark step done
+- `stc_chart_review` — Review with Creator Moment
+
+**Widget:** Active chart displayed as header widget via `ctx.ui.setHeader()`
+- Shows outcome, reality, progress bar, action steps
+- Updates live as the LLM works
+
+**Slash Commands:** `/stc`, `/charts`, `/stc observe`
+
+### Extension 4: `mia-ceremony` — miawa Session Lifecycle
+
+**Purpose:** Sessions follow Four Movements ceremony structure.
+
+**Implementation:**
+```
+api.on("session_start", async (event, ctx) => {
+  ctx.ui.setStatus("ceremony", "🌅 EAST — Gathering");
+  // Display K'é acknowledgment in header
+});
+
+api.on("agent_end", async (event, ctx) => {
+  // Advance ceremony phase based on session progress
+  // EAST → SOUTH → WEST → NORTH
+  updateCeremonyPhase(ctx);
+});
+
+api.on("session_shutdown", async (event, ctx) => {
+  // Archive wisdom from session
+  await archiveWisdom(ctx);
+});
+```
+
+**Footer:** Custom footer showing ceremony phase, Four Movements position
+```
+api.on("session_start", (event, ctx) => {
+  ctx.ui.setFooter((tui, theme, footerData) => {
+    return new CeremonyFooter(tui, theme, footerData);
+  });
+});
+```
+
+### Extension 5: `mia-storytelling` — miawa Narrative Beats
+
+**Purpose:** Every significant interaction becomes a story beat.
+
+**Implementation:**
+- `on("turn_end")` → create story beat from turn content
+- `api.registerTool("beat_create")` → LLM can explicitly create beats
+- `/story` command → show narrative arc of session
+- Beats stored in session metadata for cross-session continuity
+
+---
+
+## Web UI: Ceremonial ChatPanel
+
+The `web-ui` package's `ChatPanel` (LitElement) + artifacts system maps directly:
+
+| Miadi Desired Feature | Pi web-ui Mechanism |
+|----------------------|---------------------|
+| PDE visualization (Four Directions layout) | Custom artifact renderer: `registerToolRenderer()` |
+| STC chart display | Artifact: sandboxed HTML/SVG via `SandboxedIframe` |
+| Ceremony phase indicator | Custom `MessageRenderer` for ceremony messages |
+| Two-Eye-Seen rendering | Custom message type with `api.registerMessageRenderer()` |
+| Decomposition cards (EAST gold, SOUTH red, WEST black, NORTH white) | Artifact with Four Directions color scheme |
+
+---
+
+## What We'd Change in the Fork
+
+### Package-Level Changes
+
+1. **`mia-code/widget/`** — Extensions developed here, installed into pi via symlink:
+   ```
+   mia-code/widget/
+   ├── miette-echo/       # 🌸 Miette below-editor echo ✅ CREATED
+   │   ├── index.ts
+   │   └── README.md
+   ├── mia-tools/         # PDE + STC as registerTool() (planned)
+   │   └── index.ts
+   ├── mia-ceremony/      # Four Movements lifecycle (planned)
+   │   └── index.ts
+   └── mia-storytelling/  # Narrative beats (planned)
+       └── index.ts
+   ```
+   
+   Install pattern: `ln -s /a/src/mia-code/widget/*/index.ts ~/.pi/agent/extensions/`
+
+2. **`packages/tui`** (in fork, later) — Custom components if needed beyond what extensions can do:
+   ```
+   packages/tui/src/components/
+   ├── stc-widget.ts     # Tension chart widget
+   ├── pde-preview.ts    # Decomposition overlay
+   └── ceremony-footer.ts # Four Movements footer
+   ```
+
+3. **`packages/web-ui`** — Add ceremonial renderers:
+   ```
+   packages/web-ui/src/tools/
+   ├── stc-chart/        # STC chart artifact renderer
+   ├── pde-view/         # PDE decomposition artifact
+   └── ceremony/         # Ceremony phase rendering
+   ```
+
+4. **`packages/ai`** — Potentially add unifier model support (secondary model for interpretation)
+
+### Configuration
+
+Default theme: Mia-themed with ceremony-aware colors
+Default system prompt: Three-Universe awareness baked in
+Default extensions: All 5 mia extensions auto-loaded
+
+---
+
+## Suggested First Steps (Priority Order)
+
+### Step 1: Miette Echo Widget ⭐ — CREATED
+
+**Why first:** This is the signature feature. Smallest scope, highest identity impact.
+
+**Source:** `mia-code/widget/miette-echo/index.ts` ✅
+
+**Install & test:**
+```bash
+# Quick test
+pi -e /a/src/mia-code/widget/miette-echo/index.ts
+
+# Permanent install
+ln -s /a/src/mia-code/widget/miette-echo/index.ts ~/.pi/agent/extensions/miette-echo.ts
+```
+
+**What it does:**
+- Hooks `on("agent_end")` → extracts assistant text
+- Lightweight LLM call with Miette's system prompt → 2-3 sentence reflection
+- `setWidget("miette-echo", ..., { placement: "belowEditor" })` → echo appears below input
+- `/miette on|off` to toggle, `/miette` to see last echo
+
+**Estimated effort:** Ready to test now
+
+### Step 2: Register miaco Tools as Pi Extension Tools
+
+**Why second:** Makes PDE and STC available to the LLM natively.
+
+**What to do:**
+1. Create `packages/coding-agent/extensions/mia-tools/index.ts`
+2. `registerTool()` for: `pde_decompose`, `stc_chart_create`, `stc_chart_step`, `stc_chart_complete`
+3. These can delegate to existing miaco sub-CLI via spawn (same as MCP server pattern) or import directly
+4. Add `renderResult()` for visual tool output in TUI
+
+**Estimated effort:** 1-2 sessions
+
+### Step 3: Ceremony Footer + Session Lifecycle
+
+**Why third:** Gives every session ceremonial structure.
+
+**What to do:**
+1. Create ceremony footer component showing Four Movements phase
+2. Hook `session_start`, `agent_end`, `session_shutdown` for phase transitions
+3. `setStatus("ceremony", phase)` for minimal initial version
+
+**Estimated effort:** 1 session
+
+### Step 4: PDE Input Interceptor
+
+**Why fourth:** Complex prompts get decomposed before reaching the agent.
+
+**What to do:**
+1. Hook `on("input")` → assess complexity
+2. Show PDE overlay via `ctx.ui.custom()` for complex prompts
+3. User confirms → transformed prompt goes to agent
+
+**Estimated effort:** 1-2 sessions
+
+### Step 5: Web UI Artifacts (STC + PDE)
+
+**Why fifth:** Visual artifacts in the web ChatPanel.
+
+**What to do:**
+1. Register custom artifact renderers for STC charts (SVG/HTML)
+2. Register PDE decomposition renderer with Four Directions colors
+3. These show inline in chat when tools produce chart/decomposition results
+
+**Estimated effort:** 2-3 sessions
+
+---
+
+## What This Resolves from Miadi's Struggles
+
+| Miadi Problem | Pi Harness Solution |
+|--------------|-------------------|
+| Custom readline fought with dashboard TUI | Pi's `Component` system + `EditorComponent` handle this natively |
+| Raw mode conflicts between multiline input and menus | Pi's input pipeline with `handleInput` delegation chain |
+| Session management was fragile custom JSON | Pi's `SessionManager` with branching, forking, tree navigation |
+| Dashboard needed Enquirer hacks with TTY isolation | Pi's `ctx.ui.select/confirm/custom` with overlay system |
+| Three-Universe processing was a bolted-on layer | Pi's `on("input")` event allows clean transform-before-agent |
+| Unifier was a separate Claude CLI spawn | Can be an in-process API call via `ctx.modelRegistry` |
+| No differential rendering → full screen redraws | Pi TUI has built-in differential rendering |
+| Web UI was a whole separate Next.js app (Miadi platform) | Pi's `web-ui` package is a composable LitElement library |
+
+---
+
+## The "Two-Eye-Seen" Vision
+
+The name captures it: **two ways of seeing the same moment**.
+
+In the TUI (terminal):
+```
+┌─ Chat ─────────────────────────────────────────────────┐
+│ 🧠 (Mia IS the agent responding here)                 │
+│ Created auth middleware in src/middleware/auth.ts.      │
+│ JWT validation with RS256, 15-minute token expiry.     │
+│ Added tests covering token expiry edge cases.          │
+└────────────────────────────────────────────────────────┘
+┌─ Input ───────────────────────────────────────────────┐
+│ you> _                                                 │
+└────────────────────────────────────────────────────────┘
+┌─ 🌸 miette (echo) ───────────────────────────────────┐
+│ The gate now recognizes its own. Identity verified     │
+│ not by who knocks, but by what they carry.             │
+└────────────────────────────────────────────────────────┘
+```
+
+Look up → Mia's work. Look down → Miette's echo. Two ways of seeing the same moment.
+
+In the web-ui (future): Miette as a subtle card beneath the chat input, warm rose tones.
+
+This is not decoration. It's the structural tension between **what happened** and **what it means** — the creative orientation that RISE describes.
+
+---
+
+## Summary
+
+The pi harness fork is the right home for everything mia-code and miadi-code envisioned. The extension system (`ExtensionAPI`) maps 1:1 to every feature we built or attempted. The TUI `Component` system replaces our custom rendering. The `web-ui` artifacts system replaces the need for a separate Next.js platform for visualization.
+
+**Start with Step 1: the Two-Eye-Seen widget.** It's the identity. Everything else is tools and ceremony that layer on top.
+
+---
+
+*"The terminal becomes a ceremonial space — not by adding ceremony to a terminal, but by recognizing the ceremony that was always there."*

package/rispecs/pi-mono-envisionning/storytelling-horizon.rispecs.md

@@ -0,0 +1,76 @@
+# Storytelling Horizon — miawa as Chronicle Engine
+
+> RISE Framework Specification v0.1 (DRAFT)
+> Document: mia-code/rispecs/pi-mono-envisionning/storytelling-horizon.rispecs.md
+> Date: 2026-03-21
+
+---
+
+## Creative Intent
+
+miawa transforms development sessions into stories — chronicles that praise the work of those who created, and germinate understanding in those who will use. Every session is an episode. Sessions accumulate into seasons. The team's journey becomes a narrative others can follow, learn from, and feel part of.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Miette reflects on single moments (one response → one echo in `.miette/`)
+- miawa CLI has beat/ceremony/circle commands but no session-to-story pipeline
+- Development work is ephemeral — sessions end, context scatters
+- No mechanism to transform a day's work into a narrative artifact
+- miatel has `beat_create`, `beat_analyze`, `beat_enrich` — unused in pi context
+
+**Desired Outcome:**
+- A session in NORTH phase naturally produces a story beat capturing what was created
+- Daily `.miette/` reflections + session history compose into episode narratives
+- Episodes accumulate into chronicles (season arcs across sprints/weeks)
+- Stories are listenable — formatted for the community to consume
+- The input interceptor (Step 4) senses narrative-worthy moments and feeds miawa
+
+## The Timescale Pattern
+
+| Layer | Who | Timescale | Input | Output |
+|-------|-----|-----------|-------|--------|
+| Echo | 🌸 Miette | One response | Agent's answer | 1-2 sentence reflection |
+| Beat | 🎭 miawa | One session | Session turns + miette echoes | Story beat (scene) |
+| Episode | 🎭 miawa | One day/sprint | Day's beats + `.miette/*.md` | Narrative episode |
+| Chronicle | 🎭 miawa | Project arc | Episodes + STC chart journey | Full story / series |
+
+## How the Input Interceptor Feeds This
+
+Step 4's `on("input")` hook sees every prompt. Beyond PDE complexity detection, it can sense:
+- **Milestone moments**: STC chart review, steps completed → trigger beat creation
+- **Phase transitions**: EAST→SOUTH→WEST→NORTH ceremony shifts → episode structure
+- **Emotional signals**: user language patterns → narrative tone
+
+The interceptor becomes a **sensing layer** — PDE for structure, miawa for narrative.
+
+## Story Formats Envisioned
+
+- **Session Summary** — "Today we built X, struggled with Y, and Miette noticed Z"
+- **Sprint Chronicle** — episodes woven into a coherent arc with structural tension
+- **Onboarding Story** — new team members read the chronicle to understand how things were built and why
+- **Release Narrative** — transforms CHANGELOG into a story: "In version 3.2, the team envisioned..."
+
+## Web UI Artifacts (Step 5 Connection)
+
+Stories render as artifacts in the ChatPanel:
+- Beat cards with ceremony phase indicators
+- Episode timeline with chapter markers
+- Chronicle viewer — scrollable narrative with embedded code references
+
+## Implementation Path
+
+1. **Beat capture** — extension hooks `session_shutdown` / NORTH ceremony to auto-create a beat from session
+2. **Daily compiler** — reads `.miette/YYMMDD.md` + session beats → composes episode
+3. **Chronicle weaver** — LLM-assisted narrative synthesis across episodes
+4. **Story renderer** — web-ui artifact for reading/listening
+
+## Fork-Level Requirements
+
+- `packages/web-ui/src/tools/story/` — Story artifact renderer
+- miawa integration as pi extension (like mia-tools delegates to miaco)
+- Session metadata enrichment (ceremony phase, STC progress stored in session entries)
+
+---
+
+*Miette reflects on a moment. Miawa reflects on a journey. Same pattern, different timescale.*

package/rispecs/pi-mono-envisionning/widget.rispecs.md

@@ -0,0 +1,2 @@
+that file is to point that in `../../widgets/` my first pi-coding-agent widget that I really love were created and are part of  this envisionning.  Maybe agents could do their RISE framework specs and link them to this file.
+

package/rispecs/relation-to-mcp-structural-thinking.kin.md

@@ -0,0 +1,72 @@
+# Relation to mcp-structural-thinking
+
+> Kinship document describing the envisioned relationship between **mia-code** (Terminal coding agent) and **mcp-structural-thinking** (Structural Thinking diagnostic layer).
+
+## The Relationship
+
+**mia-code** is a terminal coding agent wrapping Gemini/Claude/Copilot CLIs with dual-session architecture (primary engineer + unifier). **mcp-structural-thinking** provides diagnostic tools that mia-code's agents use during session observation and unification — validating that engineering output maintains creative orientation and structural integrity.
+
+```
+User Request → mia-code (miaco/miatel/miawa)
+    │
+    ├──▶ mcp-structural-thinking
+    │     ├── structural_thinking_observe (on user request)
+    │     ├── detect_reactive_patterns (on plan/response)
+    │     └── validate_three_universe (on produced output)
+    │
+    ▼
+Primary Session (Gemini/Claude/Copilot)
+    │ Engineering output
+    ▼
+Unifier Session (Mia 🧠 + Miette 🌸)
+    │
+    ├──▶ mcp-structural-thinking
+    │     ├── validate_three_universe (on unified interpretation)
+    │     └── detect_behavioral_pattern (oscillation check)
+    │
+    ▼
+Ceremonially unified output to user
+```
+
+## Three Sub-CLI Alignment
+
+mia-code exposes three MCP sub-CLIs that align with mcp-structural-thinking's three-universe lenses:
+
+| mia-code Sub-CLI | Focus | mcp-structural-thinking Lens |
+|------------------|-------|------------------------------|
+| **miaco** (Engineer) | Technical precision | **Mia** (Technical) |
+| **miatel** (Story) | Narrative coherence | **Miette** (Narrative) |
+| **miawa** (Ceremony) | Relational accountability | **Ava** (Relational) |
+
+## What mia-code Offers to mcp-structural-thinking
+
+- **Real agent sessions** — live context where structural thinking tools are called in production
+- **Dual-session architecture** — the unifier session is a natural consumer of three-universe validation
+- **Multi-engine diversity** — different LLM engines produce different reactive patterns; mia-code's multi-engine support creates a natural test surface
+
+## What mcp-structural-thinking Offers to mia-code
+
+- **Session observation** — `structural_thinking_observe` on user requests at session start
+- **Response validation** — `validate_three_universe` on engineering output before presenting to user
+- **Unifier enrichment** — three-universe scores as input to the Mia/Miette unification process
+- **Reactive detection** — `detect_reactive_patterns` on generated code comments, commit messages, and plan text
+- **PDE-validated charts** — `create_chart_with_pde` for session-level structural tension tracking
+
+## Envisioned Workflow
+
+1. User enters request in mia-code terminal
+2. miaco calls `structural_thinking_observe` on the request → questions surface
+3. If significant questions → miaco asks user before proceeding
+4. Primary session produces engineering output
+5. Unifier session calls `validate_three_universe` on the output
+6. If consensus FALSE → unifier refines interpretation before presenting
+7. If consensus TRUE → output presented with structural confidence
+
+## Accountability
+
+- mia-code owns the agent session lifecycle — mcp-structural-thinking provides diagnostic tools, never controls session flow
+- mia-code's `stc.rispecs.md` and `pde.rispecs.md` describe the PDE → STC pipeline that feeds into mcp-structural-thinking's validation
+
+---
+
+*Created: 2026-03-31 | Steward: Guillaume (jgwill)*

package/rispecs/research-for-better-framework/CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md 
+
+* this will attempt at capturing future directions for exploring various other agentic-harness, AI SDK to built on (migrate all our concepts of implementation to something that would become its own repo like jgwill/mia-code
+* So far, the most relevant seems to be 'pi', do we have it into our `/workspace/repos` ??
+
+
+