439 lines
12 KiB
Markdown
439 lines
12 KiB
Markdown
# 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
|