# VAULTMESH-CONSOLE-ENGINE.md

**Sovereign AI Agent Session Management**

> *Every coding session is a chapter in the Civilization Ledger.*

The Console Engine binds AI coding agents (OpenCode, Claude Code, CAI, custom agents) into the VaultMesh receipting system. Every session, command, file edit, tool call, approval, and git commit becomes a receipted event.

---

## 1. Engine Registration

| Property | Value |
|----------|-------|
| **Engine ID** | `engine:console` |
| **Name** | Console |
| **Scroll** | `Console` |
| **JSONL Path** | `receipts/console/console_events.jsonl` |
| **Root File** | `receipts/console/ROOT.console.txt` |
| **Authority** | AI agent session management, code operations, and sovereign development |
| **Status** | `active` |

### 1.1 Capabilities

```json
[
  "console_read",
  "console_write",
  "console_execute",
  "console_spawn",
  "file_read",
  "file_write",
  "bash_execute",
  "git_commit",
  "mcp_call"
]
```

---

## 2. Receipt Types

### 2.1 Receipt Schema

All Console receipts share a common envelope:

```json
{
  "ts": "2025-12-07T04:00:00Z",
  "engine_id": "engine:console",
  "type": "console_session_start",
  "session_id": "session-1765123456",
  "payload": { ... }
}
```

### 2.2 Receipt Type Definitions

| Type | Description | Payload Fields |
|------|-------------|----------------|
| `console_genesis` | Engine initialization marker | `note` |
| `console_session_start` | Agent session initiated | `agent_type`, `model_id`, `caller`, `project_path` |
| `console_session_end` | Agent session completed | `duration_ms`, `commands_executed`, `files_modified`, `exit_reason` |
| `console_command` | CLI command executed | `command`, `args_hash`, `exit_code`, `duration_ms` |
| `console_file_edit` | File modification via agent | `file_path`, `old_hash`, `new_hash`, `edit_type`, `lines_changed` |
| `console_tool_call` | Agent tool invocation | `tool_name`, `params_hash`, `result_hash`, `capability_used` |
| `console_approval` | Human approval for agent action | `action_type`, `approved`, `approver`, `reason` |
| `console_git_commit` | Git commit created by agent | `commit_hash`, `files_changed`, `message_hash`, `signed` |
| `console_agent_spawn` | Sub-agent spawned | `parent_session_id`, `child_session_id`, `agent_type`, `task_hash` |

---

## 3. Mapping to Eternal Pattern

### 3.1 Experience Layer (L1)

**Entrypoints:**
- `opencode --sovereign` — Launch sovereign OpenCode session
- `vm-console spawn <agent>` — Spawn a new agent session
- MCP tools (`console_session_list`, `console_spawn_agent`, etc.)
- Portal dashboard for session monitoring

**Intent Capture:**
```bash
# Sovereign OpenCode invocation
opencode --sovereign --project /root/work/vaultmesh

# With explicit identity
opencode --identity did:vm:agent:opencode-sovereign --capabilities console_write,file_edit
```

### 3.2 Engine Layer (L2)

**Session Contract:**

```json
{
  "contract_type": "console_session",
  "session_id": "session-1765123456",
  "agent_type": "opencode",
  "model_id": "claude-opus-4-5-20251101",
  "caller": "did:vm:human:karol",
  "project_path": "/root/work/vaultmesh",
  "capabilities_requested": [
    "file_read",
    "file_write",
    "bash_execute",
    "git_commit"
  ],
  "constraints": {
    "max_duration_minutes": 60,
    "max_files_modified": 50,
    "require_approval_for": ["git_push", "file_delete"],
    "sandbox_mode": false
  },
  "created_at": "2025-12-07T04:00:00Z"
}
```

This contract is captured as a `console_session_start` receipt payload.

**Session State (derived from receipts):**

```json
{
  "session_id": "session-1765123456",
  "status": "active",
  "started_at": "2025-12-07T04:00:00Z",
  "commands_executed": 23,
  "files_read": 15,
  "files_modified": 4,
  "tool_calls": 47,
  "approvals_requested": 1,
  "approvals_granted": 1,
  "current_task": "Implementing Console engine receipts",
  "git_commits": []
}
```

State is derived from receipts, not a primary source of truth.

### 3.3 Ledger Layer (L3)

**Receipt Flow:**

```
Session Start → Tool Calls → File Edits → Approvals → Git Commits → Session End
      ↓             ↓            ↓            ↓            ↓            ↓
   Receipt      Receipt      Receipt      Receipt      Receipt      Receipt
      ↓             ↓            ↓            ↓            ↓            ↓
      └─────────────┴────────────┴────────────┴────────────┴────────────┘
                                      ↓
                          console_events.jsonl
                                      ↓
                            ROOT.console.txt
                                      ↓
                           Guardian Anchor
```

---

## 4. Root File Format

`receipts/console/ROOT.console.txt`:

```
# VaultMesh Console Root
engine_id=engine:console
merkle_root=8a71c1c0b9c6...
events=128
updated_at=2025-12-07T05:30:00Z
```

| Field | Description |
|-------|-------------|
| `engine_id` | Fixed identifier (`engine:console`) |
| `merkle_root` | Hex-encoded Merkle root over line hashes |
| `events` | Number of receipts in `console_events.jsonl` |
| `updated_at` | ISO 8601 timestamp of last update |

---

## 5. DID Scheme

```
did:vm:agent:opencode-<session-id>   # Per-session agent identity
did:vm:agent:opencode-sovereign      # Persistent sovereign agent
did:vm:service:console-gateway       # MCP gateway service
```

For Phase 1, DIDs are treated as opaque strings. Full Identity engine integration comes later.

---

## 6. CLI Commands

```bash
# Session management
vm-console session list --status active
vm-console session show session-1765123456
vm-console session kill session-1765123456 --reason "Manual termination"

# Spawn agents
vm-console spawn opencode --task "Implement Treasury engine" --project /root/work/vaultmesh
vm-console spawn cai --task "Audit authentication flow" --capabilities offsec_read

# Approvals
vm-console approvals pending
vm-console approve action-12345 --reason "Looks safe"
vm-console reject action-12345 --reason "Too risky"

# History and audit
vm-console history --session session-1765123456
vm-console audit --date 2025-12-07 --agent-type opencode
vm-console receipts --scroll Console --limit 100
```

---

## 7. MCP Tools

### 7.1 Read-Only Tools

| Tool | Description |
|------|-------------|
| `console_session_list` | List active/completed sessions |
| `console_session_status` | Get detailed session status |
| `console_receipts_search` | Search Console scroll receipts |

### 7.2 Write Tools

| Tool | Capability Required | Description |
|------|---------------------|-------------|
| `console_spawn_agent` | `console_spawn` | Spawn a new agent session |
| `console_approve_action` | `console_approve` | Approve/reject pending action |

---

## 8. Python API

### 8.1 Emitting Receipts

```python
from engines.console.receipts import emit_console_receipt

# Session start
emit_console_receipt(
    "console_session_start",
    {
        "agent_type": "opencode",
        "model_id": "claude-opus-4-5",
        "caller": "did:vm:human:karol",
        "project_path": "/root/work/vaultmesh"
    },
    session_id="session-1765123456",
)

# File edit
emit_console_receipt(
    "console_file_edit",
    {
        "file_path": "engines/console/receipts.py",
        "old_hash": "blake3:abc123...",
        "new_hash": "blake3:def456...",
        "edit_type": "modify",
        "lines_changed": 42
    },
    session_id="session-1765123456",
)

# Session end
emit_console_receipt(
    "console_session_end",
    {
        "duration_ms": 3600000,
        "commands_executed": 47,
        "files_modified": 12,
        "exit_reason": "completed"
    },
    session_id="session-1765123456",
)
```

### 8.2 Reading Root Info

```python
from engines.console.receipts import get_emitter

emitter = get_emitter()
info = emitter.get_root_info()
print(f"Events: {info['events']}, Root: {info['merkle_root'][:16]}...")
```

---

## 9. HTTP Bridge

For OpenCode plugin integration, a FastAPI sidecar exposes the receipt emitter:

```python
# scripts/console_receipts_server.py
from fastapi import FastAPI
from pydantic import BaseModel
import uvicorn
from engines.console.receipts import emit_console_receipt, ReceiptType

app = FastAPI()

class ReceiptIn(BaseModel):
    type: ReceiptType
    session_id: str | None = None
    payload: dict

@app.post("/v1/console/receipt")
async def console_receipt(rec: ReceiptIn):
    record = emit_console_receipt(
        receipt_type=rec.type,
        payload=rec.payload,
        session_id=rec.session_id,
    )
    return {"ok": True, "record": record}

if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=9110)
```

---

## 10. OpenCode Plugin

The `@vaultmesh/opencode-plugin` hooks into OpenCode's lifecycle:

```typescript
export const VaultMeshConsolePlugin = async (ctx) => {
  const sessionId = await initSession(ctx);

  return {
    hooks: {
      onSessionStart: async () => { /* emit console_session_start */ },
      onSessionEnd: async (result) => { /* emit console_session_end */ },
      onToolCall: async (tool, params, result) => { /* emit console_tool_call */ },
      onFileEdit: async (path, oldContent, newContent) => { /* emit console_file_edit */ },
    },
    tool: {
      vm_anchor: tool({ /* trigger Guardian anchor */ }),
      vm_receipt_search: tool({ /* search Console receipts */ }),
      vm_identity: tool({ /* get session identity */ }),
    },
  };
};
```

---

## 11. Integration Points

### 11.1 Guardian

Console root is included in the ProofChain anchor cycle:

```python
# Guardian reads ROOT.console.txt alongside other scroll roots
roots = {
    "console": read_root("receipts/console/ROOT.console.txt"),
    "drills": read_root("ROOT.drills.txt"),
    # ... other scrolls
}
anchor_hash = compute_combined_root(roots)
```

### 11.2 Identity

Session DIDs resolve via the Identity engine:

```json
{
  "did": "did:vm:agent:opencode-session-1765123456",
  "type": "agent",
  "controller": "did:vm:human:karol",
  "capabilities": ["file_read", "file_write", "bash_execute"],
  "session_id": "session-1765123456",
  "expires_at": "2025-12-07T05:00:00Z"
}
```

### 11.3 Governance

Dangerous operations trigger constitutional compliance checks:

```python
async def check_before_execute(action: str, target: str):
    if action in DANGEROUS_OPERATIONS:
        result = await governance_engine.check_compliance(
            action=action,
            actor=current_session.identity,
            target=target,
        )
        if not result.compliant:
            raise ConstitutionalViolation(result.articles_violated)
```

---

## 12. Design Gate Checklist

| Question | Answer |
|----------|--------|
| Clear entrypoint? | ✅ `opencode --sovereign`, `vm-console spawn`, MCP tools |
| Contract produced? | ✅ Session contract in `console_session_start` payload |
| State object? | ✅ Derived session state from receipts |
| Receipts emitted? | ✅ 9 receipt types (including genesis) |
| Append-only JSONL? | ✅ `receipts/console/console_events.jsonl` |
| Merkle root? | ✅ `receipts/console/ROOT.console.txt` |
| Guardian anchor path? | ✅ Console root included in ProofChain |
| Query tool? | ✅ `vm-console`, MCP tools, Portal dashboard |

---

## 13. Future Extensions

### 13.1 Phase 2: Albedo 🜄

- OpenCode plugin integration
- HTTP bridge for receipt emission
- Real session tracking

### 13.2 Phase 3: Citrinitas 🜆

- `vm-console` CLI with full commands
- MCP server tools
- Session replay and audit

### 13.3 Phase 4: Rubedo 🜂

- Multi-agent orchestration
- Cross-session task continuity
- Federation support for remote agents
- Full Identity engine integration