coaia-visualizer 1.6.3 → 1.6.4

package/rispecs/accountability-responsibility.rispec.md

@@ -0,0 +1,110 @@
+# RISPEC: Accountability & Responsibility Rendering in coaia-visualizer
+
+> How the visualizer displays accountability and responsibility distinctions in Structural Tension Charts
+
+## 🎯 What This Enables Users to Create
+
+- Visual clarity on who holds accountability for chart outcomes
+- Inline responsibility attribution on action steps
+- Delegation chain awareness across chart hierarchies
+- Filtered views by responsible entity type (human / AI / pair)
+
+## Current Reality
+
+`coaia-visualizer` renders STCs from coaia-narrative JSONL. It shows chart components (desired outcome, current reality, action steps), telescoping navigation, and completion status. There is no visual representation of:
+- Who is accountable for a chart's desired outcome
+- Who is responsible for each action step
+- The delegation chain between them
+
+## Desired Result
+
+The visualizer renders accountability and responsibility as first-class visual elements:
+- **Chart header**: shows the accountable entity with a distinct badge
+- **Action steps**: show responsible entity/entities inline
+- **Delegation view**: optional view showing the accountability→responsibility chain
+
+## UI Components
+
+### Chart Header — Accountability Badge
+
+```
+┌─────────────────────────────────────────┐
+│ 🎯 Deploy PDE across all variants      │
+│ ◉ Accountable: jgi (human)             │
+│ Due: 2026-03-21                         │
+└─────────────────────────────────────────┘
+```
+
+- `◉` icon distinguishes accountability from responsibility
+- Color-coded by `accountableEntityType`: human (blue), ai_companion (purple), team_lead (green)
+- Click to view accountability context
+
+### Action Steps — Responsibility Indicators
+
+```
+□ Audit mcp-pde implementation          → mia, sub-agent:south
+□ Update coaia-pde stc-mapper           → mia
+■ Research IAIP reference format        → sub-agent:south ✓ completedBy: south-3
+```
+
+- Responsible entities shown inline, right-aligned
+- `pair` type shows both entities with a link icon
+- Completed steps show `completedBy` if different from responsible
+
+### Delegation Chain View (Optional Panel)
+
+```
+jgi (accountable)
+├── delegates → mia (NORTH actions)
+├── delegates → sub-agent:south (SOUTH actions)
+├── co-holds → jgi + miette (WEST actions)
+└── retains → jgi (EAST actions)
+```
+
+### Filter/Group Controls
+
+- Filter action steps by responsible entity
+- Group by responsibility type (human / AI / pair)
+- Highlight items where responsibility ≠ completed-by (delegation shift)
+
+## Schema Consumption
+
+Reads from Entity.metadata:
+
+```typescript
+// Chart entity
+metadata.accountability?.accountableEntity
+metadata.accountability?.accountableEntityType
+metadata.accountability?.accountabilityContext
+
+// Action step entity
+metadata.responsibility?.responsibleEntities
+metadata.responsibility?.responsibilityType
+metadata.responsibility?.delegatedFrom
+metadata.assignedTo  // backward compat fallback
+```
+
+## Backward Compatibility
+
+When `accountability` / `responsibility` fields are absent:
+- Chart header shows no accountability badge (no default assumption)
+- Action steps show no responsibility indicator
+- Existing charts render identically to current behavior
+
+## Dependency
+
+- Canonical schema: `coaia-narrative/rispecs/accountability-responsibility-distinction.rispec.md`
+- Data source: coaia-narrative JSONL with Entity.metadata extensions
+
+## Priority
+
+Medium — rendering follows schema. Implement after coaia-narrative schema extension is merged.
+
+---
+
+## 🔗 Related Components
+
+- [chart-visualization-hierarchy.spec.md](./chart-visualization-hierarchy.spec.md) — ChartDetail/ChartDetailEditable host accountability badges in header
+- [chart-editing-workflow.spec.md](./chart-editing-workflow.spec.md) — EditActionStep would need responsibility indicator integration
+- [jsonl-parsing-data-types.spec.md](./jsonl-parsing-data-types.spec.md) — EntityRecord metadata extensions for accountability/responsibility fields
+- [api-mcp-interface.spec.md](./api-mcp-interface.spec.md) — API routes would need to support accountability/responsibility updates

package/rispecs/api-mcp-interface.spec.md

@@ -0,0 +1,287 @@
+# API & MCP Interface
+## RISE Specification for REST API, MCP Server, and Agent Access Patterns
+
+**Component Purpose**: Provide complete programmatic access to structural tension chart operations via REST API endpoints and a 15-tool MCP server, enabling AI agents and external tools to create, read, update, and delete charts with the same fidelity as the web UI.
+
+**Source Files**: `app/api/**/*.ts`, `mcp/src/index.ts`, `mcp/src/tools/index.ts`, `mcp/src/api-client.ts`, `lib/api-auth.ts`
+
+---
+
+## 🎯 What This Component Enables Users to Create
+
+- AI agent workflows that manage structural tension charts programmatically
+- Automated chart creation from Claude, GPT, or any MCP-compatible agent
+- External tool integrations via standard REST API calls
+- Secure multi-user access with token-based authentication
+- Live data synchronization between web UI and agent sessions
+
+---
+
+## 🌊 Structural Tension Dynamics
+
+### Current Reality
+coaia-narrative stores data as JSONL files on disk. Without an API layer, agents must read/write files directly, parse JSONL manually, and implement their own chart assembly logic. The MCP protocol exists but needs a server that maps chart operations to tool definitions.
+
+### Desired Result
+A complete API surface where:
+- 6 REST route groups expose all chart operations
+- 15 MCP tools provide agent-native access
+- Bearer token authentication protects all mutating endpoints
+- Every write operation creates a timestamped backup
+- Response formats are consistent (JSON with error/success patterns)
+
+### Natural Resolution
+The REST API implements chart operations using `ChartEditor` and JSONL parsing. The MCP server wraps the REST API via `CoaiaVisualizerClient`, translating tool calls into HTTP requests. Both share the same authentication layer.
+
+---
+
+## 📋 Authentication (`lib/api-auth.ts`)
+
+### Token Resolution
+```
+1. Check COAIAN_API_TOKEN environment variable
+2. If set → use as API token
+3. If not set → generate random 64-char hex token (crypto.randomBytes(32))
+4. Cache generated token for process lifetime
+5. Log generated token to console with warning (development convenience)
+```
+
+### Request Validation
+```typescript
+validateApiToken(request: NextRequest): boolean
+  1. Extract Authorization header
+  2. Match regex /^Bearer\s+(.+)$/
+  3. Compare extracted token against getApiToken()
+  4. Return true only if match
+```
+
+### Middleware Pattern
+```typescript
+withAuth(handler): wrappedHandler
+  1. Call validateApiToken(request)
+  2. If invalid → return 401 { error: "Unauthorized" }
+  3. If valid → delegate to handler(request, context)
+```
+
+### Response Helpers
+- `successResponse(data, status=200)` → `NextResponse.json(data, { status })`
+- `errorResponse(message, status=400)` → `NextResponse.json({ error: message }, { status })`
+- `unauthorizedResponse()` → 401 with explanation message
+
+---
+
+## 📋 REST API Routes
+
+### GET /api/charts — List Charts
+**Auth**: Required (withAuth)  
+**Query Params**:
+- `level` — Filter by chart depth (number)
+- `rootOnly` — Return only level-0 charts (boolean)
+
+**Response**: `{ charts: Chart[], total: number, memoryPath: string }`
+
+### POST /api/charts — Create Chart
+**Auth**: Required (withAuth)  
+**Body**:
+```json
+{
+  "desiredOutcome": "string (required)",
+  "currentReality": "string (required)",
+  "dueDate": "ISO date string (optional)",
+  "parentChartId": "string (optional, for sub-charts)"
+}
+```
+**Behavior**:
+1. Generate new chart_N ID (max existing + 1)
+2. Create 3 entities: chart, desired_outcome, current_reality
+3. Create 3 relations: contains (×2), creates_tension_with
+4. If parentChartId: create parent→child contains relation
+5. Create timestamped backup of existing file
+6. Write updated JSONL
+
+**Response**: `{ chartId: string, message: string, backup: string }`
+
+### GET /api/charts/[id] — Get Chart
+**Auth**: Required  
+**Response**: Full Chart object with all properties
+
+### POST /api/charts/[id] — Update Chart
+**Auth**: Required  
+**Body**: Object with one or more update operations:
+
+| Operation | Fields | Effect |
+|:---|:---|:---|
+| `updateDesiredOutcome` | `{ text: string }` | Replace desired outcome |
+| `addCurrentRealityObservation` | `{ observation: string }` | Add observation |
+| `updateCurrentReality` | `{ observations: string[] }` | Replace observations |
+| `updateCurrentRealityObservation` | `{ index, text }` | Update specific observation |
+| `deleteCurrentRealityObservation` | `{ index }` | Remove observation |
+| `addActionStep` | `{ title, currentReality, dueDate? }` | Create telescoped action |
+| `updateActionStep` | `{ actionName, description }` | Update action text |
+| `toggleActionCompletion` | `{ actionName }` | Toggle done status |
+| `markActionComplete` | `{ actionStepName }` | Complete + update parent |
+| `updateActionProgress` | `{ actionStepName, observation, updateReality? }` | Add progress |
+| `updateActionDueDate` | `{ actionName, dueDate }` | Change action date |
+| `deleteActionStep` | `{ actionName }` | Remove action |
+| `createTelescopedChart` | `{ actionName }` | Convert action to sub-chart |
+| `updateDueDate` | `{ dueDate }` | Change chart date |
+
+**Response**: `{ chart: Chart, updates: string[], backup: string, message: string }`
+
+### DELETE /api/charts/[id] — Delete Chart
+**Auth**: Required  
+**Behavior**: Recursively deletes chart + all sub-charts, their entities, and all related relations  
+**Response**: `{ message: string, deletedEntities: string[], backup: string }`
+
+### GET /api/charts/search — Search Charts
+**Auth**: Required  
+**Query Params**:
+- `q` — Text search (case-insensitive, searches outcomes/reality/actions)
+- `level` — Filter by depth
+- `completed` — Boolean: all actions done?
+- `hasActions` — Boolean: has action steps?
+
+**Response**: `{ charts: Chart[], total: number, query: { q, level, completed, hasActions } }`
+
+### GET /api/jsonl — Read Memory File
+**Auth**: Not required  
+**Dependency**: Requires `COAIAV_MEMORY_PATH` environment variable to locate the JSONL file on disk  
+**Filename Resolution**: Uses `COAIAV_MEMORY_DISPLAY_NAME` if set, otherwise falls back to `path.basename(COAIAV_MEMORY_PATH)`. This preserves the original filename when Docker remaps paths to `/data/memory.jsonl`.  
+**Response**: `{ content: string, filename: string, path: string }`
+
+### POST /api/jsonl — Write Memory File
+**Auth**: Not required  
+**Body**: `{ content: string }`  
+**Behavior**: Creates timestamped backup, writes new content  
+**Response**: `{ success: true, backupPath: string }`
+
+### GET /api/watch — File Statistics
+**Auth**: Not required  
+**Response**: `{ lastModified: number, beatCount: number, fileSize: number, totalRecords: number }`  
+**Purpose**: Support live polling for file change detection
+
+### GET /api/audio/[filename] — Serve Audio
+**Auth**: Not required  
+**Security**: Only serves `.mp3` files from `COAIAV_AUDIO_DIR`  
+**Response**: Binary MP3 with 1-year cache header  
+
+---
+
+## 📋 MCP Server (`mcp/`)
+
+### Configuration
+- **Transport**: stdio (standard input/output)
+- **API Base URL**: `COAIAV_API_URL` env var (default fallback: `http://localhost:3000`)
+- **Token**: `COAIAN_API_TOKEN` env var (required — server refuses to start without it)
+
+### 15 MCP Tools
+
+| # | Tool Name | Required Args | Optional Args | Maps To |
+|:---|:---|:---|:---|:---|
+| 1 | `list_charts` | — | level, rootOnly | GET /api/charts |
+| 2 | `get_chart` | chartId | — | GET /api/charts/{id} |
+| 3 | `create_chart` | desiredOutcome, currentReality | dueDate, parentChartId | POST /api/charts |
+| 4 | `update_chart` | chartId | desiredOutcome, currentReality, dueDate | POST /api/charts/{id} |
+| 5 | `add_action_step` | parentChartId, actionStepTitle, currentReality | dueDate | POST /api/charts/{id} |
+| 6 | `update_action_step` | chartId, actionName, description | — | POST /api/charts/{id} |
+| 7 | `mark_action_complete` | chartId, actionStepName | — | POST /api/charts/{id} |
+| 8 | `update_action_progress` | chartId, actionStepName, progressObservation | updateCurrentReality | POST /api/charts/{id} |
+| 9 | `update_current_reality` | chartId, newObservations | — | POST /api/charts/{id} |
+| 10 | `toggle_action_completion` | chartId, actionName | — | POST /api/charts/{id} |
+| 11 | `delete_action_step` | chartId, actionName | — | POST /api/charts/{id} |
+| 12 | `create_telescoped_chart` | chartId, actionName | — | POST /api/charts/{id} |
+| 13 | `delete_chart` | chartId | — | DELETE /api/charts/{id} |
+| 14 | `search_charts` | — | query, level, completed, hasActions | GET /api/charts/search |
+| 15 | `get_chart_progress` | chartId | — | GET /api/charts/{id} + compute |
+
+### Tool Response Format
+```json
+{
+  "content": [{ "type": "text", "text": "JSON string of response data" }],
+  "isError": false
+}
+```
+Error responses set `isError: true` with error message in text field.
+
+### CoaiaVisualizerClient (`mcp/src/api-client.ts`)
+HTTP wrapper class used by the MCP server.
+
+> **Note**: The client uses a simplified `Chart` type (plain objects, not full `EntityRecord` instances). Entity names returned by the API may differ from those used internally by `ChartEditor` (e.g., API route params use `chartId` while ChartEditor methods reference `chart.chartEntity.name`).
+
+```typescript
+class CoaiaVisualizerClient {
+  constructor(config: { baseUrl: string, token: string })
+  
+  listCharts(options?): Promise<Chart[]>
+  getChart(id: string): Promise<Chart>
+  createChart(data): Promise<{ chartId: string }>
+  updateChart(id, updates): Promise<Chart>
+  createTelescopedChart(chartId, actionName): Promise<Chart>
+  deleteChart(id): Promise<void>
+  searchCharts(query): Promise<Chart[]>
+  getChartProgress(chart): number       // Local computation
+  getChartSummary(chart): string        // Local computation (100 char truncate)
+}
+```
+
+---
+
+## 📋 Agent Access Scenario
+
+### Claude Desktop Configuration
+```json
+{
+  "mcpServers": {
+    "coaia-visualizer": {
+      "command": "node",
+      "args": ["path/to/mcp/dist/index.js"],
+      "env": {
+        "COAIAN_API_TOKEN": "your-token-here",
+        "COAIAV_API_URL": "http://localhost:3000"
+      }
+    }
+  }
+}
+```
+
+### Typical Agent Session
+```
+1. Agent calls list_charts → gets all chart summaries
+2. Agent calls get_chart(chartId) → gets full detail
+3. Agent calls update_current_reality → adds new observations
+4. Agent calls add_action_step → creates telescoped sub-chart
+5. Agent calls mark_action_complete → action done + parent updated
+6. Agent calls get_chart_progress → checks advancement percentage
+```
+
+---
+
+## ✅ Quality Criteria
+
+✅ **API Completeness**
+- Every operation available in the web UI is also available via API
+- 15 MCP tools cover all chart lifecycle operations
+- Search supports text, level, completion, and action filters
+
+✅ **Authentication Security**
+- All chart mutation endpoints require Bearer token
+- Token from environment variable or auto-generated
+- Consistent 401 response for unauthorized requests
+
+✅ **Data Safety**
+- Timestamped backup created before every write
+- Recursive deletion handles sub-chart cascades
+- Error responses include descriptive messages
+
+✅ **Agent Ergonomics**
+- All responses are JSON (parseable by agents)
+- Tool descriptions include required/optional parameter documentation
+- MCP tools use JSON Schema inputSchema for parameter validation
+
+---
+
+## 🔗 Related Components
+
+- [chart-editing-workflow.spec.md](./chart-editing-workflow.spec.md) — ChartEditor class used by API routes
+- [jsonl-parsing-data-types.spec.md](./jsonl-parsing-data-types.spec.md) — types shared between API and client
+- [cli-mode.spec.md](./cli-mode.spec.md) — CLI starts the server that API routes run on