vm-core/docs/VAULTMESH-CONSOLE-ENGINE.md

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

[
  "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:

{
  "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:

# 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:

{
  "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):

{
  "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

# 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

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

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:

# 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:

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:

# 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:

{
  "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:

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