Output

greatVibeAgent Design Document

Version 1.0 | 2026-01-05 | Status: Draft

Executive Summary
Agent Overview & Purpose
Provider Plugin Architecture
Target Development Environments
Permissions & Guardrails System
Authentication, Authorization & Accounting (AAA)
Configuration Management
Networking Architecture
Session Management & Playback
Connection Management & Recovery
Failover & Disaster Recovery
Multi-Agent Architecture
Security Model
Configuration Parameters Reference
API Contract
greatVibe.local Security Model

1. Executive Summary

greatVibeAgent is a cross-platform AI agent binary written in Go that serves as the execution layer for the greatVibe platform. It connects TO the hub (not the other way around), executes AI-powered development tasks, and maintains session state locally.

Core Value Proposition

Provider Agnostic: Support multiple AI providers through unified plugin architecture
Cross-Platform: Single binary deployment for Linux, macOS, Windows
Resilient: Local state storage survives hub restarts, network failures
Secure: Sandboxed execution, credential isolation, audit logging
Scalable: Multiple agents per hub, hub-and-spoke architecture

Key Architectural Decisions

Decision	Rationale
Go Language	Goroutines for parallelism, single binary, cross-compile
Agent-Initiated Connections	Restart resilience, firewall-friendly, NAT traversal
SQLite + JSONL Storage	No external dependencies, Claude-readable, fast
WebSocket Bidirectional	Real-time events, overcome SSE limitations
Provider Plugins	Extensible, vendor-neutral, future-proof

2. Agent Overview & Purpose

2.1 What is greatVibeAgent?

greatVibeAgent is the execution engine of the greatVibe platform. It:

Receives work assignments from the hub (prompts, tasks, flows)
Executes AI provider calls (Claude, OpenAI, Gemini, etc.)
Performs file system operations, git commands, and tool calls
Streams results back to the hub in real-time
Maintains complete session history locally for replay

2.2 Agent-Hub Relationship

┌─────────────────────────────────────────────────────────────────┐
│                    GREATVIBE HUB                                │
│                                                                 │
│   Work Queue │ Agent Registry │ Session Channels │ State Store  │
│                                                                 │
└──────────────────────────────┬──────────────────────────────────┘
                               │
           agents connect TO hub (not the other way)
                               │
       ┌───────────────────────┼───────────────────────┐
       │                       │                       │
       ▼                       ▼                       ▼
┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│ gvAgent     │         │ gvAgent     │         │ gvAgent     │
│ (Linux)     │         │ (Windows)   │         │ (postgres)  │
│             │         │             │         │             │
│ Local       │         │ Local       │         │ Local       │
│ Session     │         │ Session     │         │ Session     │
│ Storage     │         │ Storage     │         │ Storage     │
└─────────────┘         └─────────────┘         └─────────────┘

2.3 Problems Solved

Problem	Solution
Hub restart loses session state	Agent stores all session data locally
Vendor lock-in to single AI provider	Provider plugin architecture
Different OS/platform requirements	Cross-compiled Go binary
CLI permission prompts block automation	Declarative guardrails system
Unreliable network connections	Local execution + eventual sync
No replay/audit capability	JSONL event journal with checksums

3. Provider Plugin Architecture

3.1 Design Philosophy

Providers are statically compiled plugins (not dynamic loading) for security and simplicity. Each provider implements a common interface but may have different capabilities.

3.2 Provider Interface

// Go interface for all providers
type Provider interface {
    // Identity
    ID() string           // "claude", "openai", etc.
    Name() string         // "Claude" for display
    Type() ProviderType   // CLI, API, or VLM
    
    // Capabilities
    Capabilities() Capabilities
    Models() []ModelInfo
    
    // Lifecycle
    Initialize(config ProviderConfig) error
    IsAvailable() bool
    Shutdown() error
    
    // Execution
    Chat(ctx context.Context, req ChatRequest) *ChatStream
    Execute(ctx context.Context, req ExecuteRequest) *ExecuteStream
}

type ProviderType int
const (
    ProviderTypeCLI ProviderType = iota  // Claude CLI, Codex CLI
    ProviderTypeAPI                       // Claude API, OpenAI API
    ProviderTypeVLM                       // Vision LLMs (Gemini, etc.)
    ProviderTypeLocal                     // VLLM, SGLang, Ollama
)

type Capabilities struct {
    ToolUse       bool    // Can call tools (Read, Edit, Bash)
    Vision        bool    // Can process images
    Streaming     bool    // Supports streaming responses
    PromptCache   bool    // Supports prompt caching
    CodeExec      bool    // Can execute arbitrary code
    MaxContext    int     // Maximum context window
}

3.3 Supported Providers

Provider	Type	Tools	Vision	Use Cases	Priority
Claude CLI	CLI	✅ Full	✅	Vibe coding, full automation	P0
Claude API	API	⚠️ MCP only	✅	Quick Turn, chat	P0
OpenAI API	API	⚠️ Functions	✅	Chat, alternatives	P1
Codex CLI	CLI	✅ Full	❌	OpenAI with tool access	P1
Google Gemini	API	⚠️ Limited	✅	Vision tasks, multimodal	P1
Google VLM	VLM	❌	✅✅	Image analysis, OCR	P2
OpenWebUI LLMs	Local	❌	Varies	Self-hosted, privacy	P2
OpenWebUI VLMs	Local	❌	✅	Local vision processing	P2
VLLM	Local	❌	Varies	High-throughput local	P3
SGLang	Local	❌	Varies	Structured generation	P3

3.4 Provider-Specific Implementations

3.4.1 Claude CLI Provider

// ClaudeCLI wraps the claude CLI binary for full tool access
type ClaudeCLIProvider struct {
    binaryPath  string          // Path to claude binary
    workingDir  string          // Default working directory
    guardrails  *GuardrailsConfig// Permission rules
    sessionID   string          // For --resume
}

// Execute runs a full Claude session with tools
func (c *ClaudeCLIProvider) Execute(ctx context.Context, req ExecuteRequest) *ExecuteStream {
    args := []string{"--output-format", "stream-json"}
    
    if c.sessionID != "" {
        args = append(args, "--resume", c.sessionID)
    }
    
    // Apply guardrails (NOT --dangerously-skip-permissions)
    if c.guardrails != nil {
        args = append(args, c.guardrails.ToArgs()...)
    }
    
    args = append(args, req.Prompt)
    
    cmd := exec.CommandContext(ctx, c.binaryPath, args...)
    // ... spawn and stream
}

3.4.2 Claude API Provider

// ClaudeAPI for direct API calls (chat, Quick Turn)
type ClaudeAPIProvider struct {
    apiKey       string
    model        string
    cacheEnabled bool          // Prompt caching for cost savings
}

func (c *ClaudeAPIProvider) Chat(ctx context.Context, req ChatRequest) *ChatStream {
    // Uses Messages API with streaming
    // Applies prompt caching for ~90% cost reduction
}

3.4.3 OpenAI / Codex CLI Provider

// CodexCLI wraps OpenAI's Codex CLI for tool access
type CodexCLIProvider struct {
    binaryPath  string          // Path to codex binary
    apiKey      string          // OpenAI API key
    guardrails  *GuardrailsConfig
}

// OpenAIAPI for direct GPT API calls
type OpenAIAPIProvider struct {
    apiKey   string
    baseURL  string  // For Azure OpenAI compatibility
    model    string
}

3.4.4 Local Model Providers (VLLM, SGLang, OpenWebUI)

// LocalProvider for self-hosted models
type LocalProvider struct {
    endpoint    string    // http://localhost:8000/v1
    apiStyle    string    // "openai", "vllm", "sglang"
    model       string    // Model name/ID
    gpuMemory   int       // GPU memory available (for batching)
}

// Supports OpenAI-compatible API for easy integration
func (p *LocalProvider) Chat(ctx context.Context, req ChatRequest) *ChatStream {
    // POST to /v1/chat/completions (OpenAI-compatible)
}

3.5 Provider Selection Logic

// Route requests to appropriate provider
func SelectProvider(req Request, available []Provider) Provider {
    switch {
    case req.RequiresTools:
        // Must use CLI provider (Claude or Codex)
        return firstWithCapability(available, CapToolUse)
    case req.HasImages:
        // Need vision capability
        return firstWithCapability(available, CapVision)
    case req.IsQuickTurn:
        // Prefer API for speed, fallback to CLI
        return preferAPIProvider(available)
    default:
        return defaultProvider(available)
    }
}

4. Target Development Environments

4.1 Platform Support Matrix

Platform	Arch	Priority	Status	Notes
AWS Linux (AL2023)	x64, ARM64	P0	Primary target	Production workloads
Ubuntu 22.04+	x64, ARM64	P0	Primary target	Development servers
macOS 13+	Intel, Apple Silicon	P1	Planned	Developer workstations
RHEL/CentOS 9+	x64	P1	Planned	Enterprise Linux
Windows 10/11	x64	P2	Planned	Native Windows dev
Android Studio	Via plugin	P3	Future	Mobile development
Xcode iOS	Via plugin	P3	Future	iOS development

4.2 Platform-Specific Considerations

AWS Linux / Ubuntu

Binary: gvagent-linux-amd64, gvagent-linux-arm64
Installation: curl -fsSL https://install.greatvibe.ai | sh
Service: systemd unit file for daemon mode
Data dir: /var/lib/gvagent/ or ~/.gvagent/
Claude CLI: Auto-detect or configure path

macOS

Binary: gvagent-darwin-amd64, gvagent-darwin-arm64
Installation: Homebrew tap or direct download
Service: launchd plist for daemon mode
Data dir: ~/Library/Application Support/gvagent/
Code signing: Required for Gatekeeper

Windows

Binary: gvagent-windows-amd64.exe
Installation: MSI installer or scoop/winget
Service: Windows Service (NSSM or native)
Data dir: %APPDATA%\gvagent\
Shell: PowerShell adapter for Bash tools

IDE Integration (Android Studio, Xcode)

Architecture: Agent runs as external process, IDE plugin communicates via localhost API
Protocol: Same WebSocket/REST API as browser clients
Features: Context injection (current file, selection), tool results inline

4.3 Build Matrix

# Cross-compile targets in Makefile
PLATFORMS := \
    linux/amd64 \
    linux/arm64 \
    darwin/amd64 \
    darwin/arm64 \
    windows/amd64

# Build all platforms
$ make release

# Output:
dist/
├── gvagent-linux-amd64
├── gvagent-linux-arm64
├── gvagent-darwin-amd64
├── gvagent-darwin-arm64
└── gvagent-windows-amd64.exe

5. Permissions & Guardrails System

5.1 The Problem with Current Approach

⚠️ Current konsole/konui uses --dangerously-skip-permissions

This grants Claude unrestricted access to the file system, shell, and network. In a multi-user or production environment, this is unacceptable. The agent needs fine-grained, declarative permission controls.

5.2 Guardrails Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    GUARDRAILS ENGINE                            │
│                                                                 │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐           │
│  │ Path Rules  │   │ Cmd Rules   │   │ Net Rules   │           │
│  │             │   │             │   │             │           │
│  │ allow: []   │   │ allow: []   │   │ allow: []   │           │
│  │ deny: []    │   │ deny: []    │   │ deny: []    │           │
│  │ readonly: []│   │ require: [] │   │ block: []   │           │
│  └──────┬──────┘   └──────┬──────┘   └──────┬──────┘           │
│         │                 │                 │                  │
│         └────────────────┬┴─────────────────┘                  │
│                          │                                     │
│                   ┌──────┴──────┐                              │
│                   │  Evaluator  │                              │
│                   └──────┬──────┘                              │
│                          │                                     │
│              ALLOW / DENY / PROMPT                           │
└──────────────────────────┼──────────────────────────────────────┘
                           │
                           ▼
                    Tool Execution

5.3 Guardrails Configuration

// guardrails.yaml
version: "1.0"
name: "production-agent"

filesystem:
  # Allowed read/write paths (glob patterns)
  allow:
    - "/konnectvol/**"           # Project directory
    - "/tmp/gvagent-*"          # Temp files
  
  # Explicitly denied paths
  deny:
    - "/etc/passwd"
    - "/etc/shadow"
    - "**/.env"                 # Never read/write .env files
    - "**/secrets/**"
    - "**/*.pem"
    - "**/*.key"
  
  # Read-only paths
  readonly:
    - "/usr/**"
    - "/bin/**"

commands:
  # Allowed commands (with optional args patterns)
  allow:
    - "git:*"                   # All git commands
    - "deno:*"
    - "npm:*"
    - "curl:*"
    - "ls:*"
    - "cat:*"
    - "head:*"
    - "tail:*"
  
  # Denied commands (never execute)
  deny:
    - "rm:-rf /*"              # Prevent catastrophic deletes
    - "sudo:*"                  # No sudo
    - "chmod:777 *"
    - "curl:* | sh"            # No pipe to shell
  
  # Commands requiring confirmation
  require_confirmation:
    - "git:push *"
    - "git:reset --hard *"
    - "rm:-r *"

network:
  # Allowed outbound connections
  allow:
    - "api.anthropic.com:443"
    - "api.openai.com:443"
    - "*.webflow.com:443"
    - "github.com:443"
  
  # Blocked destinations
  deny:
    - "169.254.169.254:*"      # AWS metadata service
    - "localhost:22"            # No SSH tunneling

limits:
  max_file_size_mb: 10          # Max file write size
  max_command_duration_s: 300  # 5 minute timeout
  max_concurrent_tools: 5
  max_tool_calls_per_turn: 100

5.4 Permission Evaluation Flow

func (g *Guardrails) Evaluate(tool ToolCall) (Decision, error) {
    // 1. Check explicit deny rules (highest priority)
    if g.matchesDenyRule(tool) {
        return DecisionDeny, ErrForbiddenByPolicy
    }
    
    // 2. Check explicit allow rules
    if g.matchesAllowRule(tool) {
        // 3. Check if requires confirmation
        if g.requiresConfirmation(tool) {
            return DecisionPrompt, nil
        }
        return DecisionAllow, nil
    }
    
    // 4. Default deny (fail-safe)
    return DecisionDeny, ErrNotExplicitlyAllowed
}

5.5 Provider-Specific Guardrails

Provider	Guardrail Mechanism	Notes
Claude CLI	--allowedTools, --disallowedTools, hooks	Native permission system
Codex CLI	--approval-mode, sandbox config	Similar to Claude
API Providers	Agent-side enforcement	No native tools, guardrails prevent injection

6. Authentication, Authorization & Accounting (AAA)

6.1 Two Deployment Models

Aspect	greatVibe.local	greatVibe.ai (Cloud)
Users	Single user / small team	Multi-tenant organizations
Authentication	Local passwords, API keys	SSO (SAML, OIDC), MFA
Authorization	Role-based (admin/user)	RBAC + ABAC, org policies
Accounting	Local logs, token tracking	Full audit trail, billing integration
Credentials	Local keychain/file	Vault integration

6.2 greatVibe.local Authentication

// Local authentication flow
┌─────────────┐     API Key      ┌─────────────┐
│   Browser   │ ────────────────►│   Hub       │
│   (konui)   │                  │   (local)   │
└─────────────┘                  └──────┬──────┘
                                        │
                     Session Token      │
                     (JWT, 24h TTL)     │
                                        ▼
                                 ┌─────────────┐
                                 │   Agent     │
                                 │             │
                                 │ validates   │
                                 │ hub-signed  │
                                 │ tokens      │
                                 └─────────────┘

Authentication Methods (Local)

Password + Session: User logs in with password, gets JWT
API Key: Long-lived key for automation/scripts
Agent Token: Agent presents token from hub to execute

6.3 greatVibe.ai Authentication

// Cloud authentication flow
┌─────────────┐     OIDC/SAML    ┌─────────────┐
│   Browser   │ ────────────────►│   IdP       │
│             │                  │ (Okta/Auth0)│
└──────┬──────┘                  └──────┬──────┘
       │                                │
       │  ID Token                      │
       ▼                                │
┌─────────────┐                         │
│   Hub       │◄────────────────────────┘
│   (cloud)   │   Verified Identity
└──────┬──────┘
       │ Organization Scope
       │ + Role Assignment
       ▼
┌─────────────┐
│   Agent     │  Hub-signed session token
└─────────────┘  with org_id, user_id, roles

6.4 Authorization Model

type Role string
const (
    RoleAdmin   Role = "admin"   // Full access, manage users/agents
    RoleDev     Role = "dev"     // Create/execute flows, sessions
    RoleViewer  Role = "viewer"  // Read-only access
    RoleAgent   Role = "agent"   // Machine identity for agents
)

type Permission string
const (
    PermSessionCreate   Permission = "session:create"
    PermSessionRead     Permission = "session:read"
    PermSessionExecute  Permission = "session:execute"
    PermFlowCreate      Permission = "flow:create"
    PermFlowApprove     Permission = "flow:approve"
    PermAgentRegister   Permission = "agent:register"
    PermAdminUsers      Permission = "admin:users"
    PermAdminConfig     Permission = "admin:config"
)

6.5 Accounting & Audit Trail

// Audit log entry (append-only JSONL)
type AuditEntry struct {
    Timestamp   time.Time       `json:"ts"`
    EventID     string          `json:"event_id"`
    Actor       string          `json:"actor"`      // user_id or agent_id
    ActorType   string          `json:"actor_type"` // "user", "agent", "system"
    Action      string          `json:"action"`
    Resource    string          `json:"resource"`
    ResourceID  string          `json:"resource_id"`
    Result      string          `json:"result"`     // "success", "denied", "error"
    Details     json.RawMessage `json:"details"`
    IPAddress   string          `json:"ip"`
    UserAgent   string          `json:"ua"`
}

// Token usage tracking
type UsageRecord struct {
    TurnID        string  `json:"turn_id"`
    SessionID     string  `json:"session_id"`
    Provider      string  `json:"provider"`
    Model         string  `json:"model"`
    InputTokens   int64   `json:"input_tokens"`
    OutputTokens  int64   `json:"output_tokens"`
    CacheRead     int64   `json:"cache_read"`
    CacheWrite    int64   `json:"cache_write"`
    CostUSD       float64 `json:"cost_usd"`
    DurationMs    int64   `json:"duration_ms"`
}

7. Configuration Management

7.1 Configuration Sources (Priority Order)

Environment Variables (highest priority) — for container/cloud deployments
Local Config File — gvagent.yaml in data directory
Hub-Pushed Config — central management via hub
Built-in Defaults (lowest priority)

7.2 Static Configuration File

# ~/.gvagent/gvagent.yaml

agent:
  id: "agent-prod-01"           # Unique agent identifier
  name: "Production Agent 1"    # Display name
  tags:
    - "production"
    - "linux"
    - "us-west-2"

hub:
  url: "wss://greatvibe.ai/agent"
  token_file: "~/.gvagent/hub-token"
  reconnect_delay_ms: 5000
  max_reconnect_attempts: -1   # Infinite

providers:
  default: "claude-cli"
  
  claude-cli:
    enabled: true
    binary_path: "/usr/local/bin/claude"
    guardrails_file: "~/.gvagent/guardrails.yaml"
  
  claude-api:
    enabled: true
    api_key_env: "ANTHROPIC_API_KEY"
    model: "claude-sonnet-4-20250514"
    prompt_cache_enabled: true
  
  openai-api:
    enabled: false
    api_key_env: "OPENAI_API_KEY"
    model: "gpt-4o"

storage:
  data_dir: "~/.gvagent/data"
  session_db: "sessions.db"
  event_journal_dir: "events/"
  max_journal_size_mb: 100

logging:
  level: "info"
  format: "json"
  output: "~/.gvagent/logs/agent.log"
  rotate_size_mb: 50
  retain_days: 30

limits:
  max_turn_duration_ms: 900000  # 15 minutes
  max_tool_calls_per_turn: 200
  idle_timeout_ms: 600000       # 10 minutes
  max_concurrent_sessions: 5

7.3 Hub Push/Pull Configuration

// Hub → Agent config push (WebSocket message)
{
  "type": "config_update",
  "version": 42,
  "config": {
    "guardrails": { ... },
    "providers": { ... },
    "limits": { ... }
  },
  "signature": "hub-signed-hash"
}

// Agent → Hub config request
{
  "type": "config_request",
  "current_version": 41
}

7.4 Configuration Validation

func ValidateConfig(cfg *Config) error {
    // Required fields
    if cfg.Agent.ID == "" {
        return errors.New("agent.id is required")
    }
    if cfg.Hub.URL == "" {
        return errors.New("hub.url is required")
    }
    
    // At least one provider must be enabled
    if !anyProviderEnabled(cfg.Providers) {
        return errors.New("at least one provider must be enabled")
    }
    
    // Validate paths exist
    if cfg.Providers.ClaudeCLI.Enabled {
        if _, err := os.Stat(cfg.Providers.ClaudeCLI.BinaryPath); err != nil {
            return fmt.Errorf("claude binary not found: %s", cfg.Providers.ClaudeCLI.BinaryPath)
        }
    }
    
    return nil
}

8. Networking Architecture

8.1 Network Topology

┌──────────────────────────────────────────────────────────────────────────┐
│                           INTERNET                                      │
└───────────────────────────────┬──────────────────────────────────────────┘
                                │
                   ┌────────────┴────────────┐
                   │   CloudFlare DNS        │
                   │   greatvibe.ai → ALB    │
                   │   *.greatvibe.ai → ALB  │
                   └────────────┬────────────┘
                                │
┌───────────────────────────────┴───────────────────────────────────────────┐
│                           AWS VPC                                        │
│                                                                           │
│   ┌────────────────────────────────────────────────────────────────┐      │
│   │                    Application Load Balancer                   │      │
│   │                                                                │      │
│   │   HTTPS :443 ──► Target Group (Hub EC2 instances)              │      │
│   │   WSS   :443 ──► Target Group (Agent WebSocket)                │      │
│   │                                                                │      │
│   └────────────────────────────────┬───────────────────────────────┘      │
│                                    │                                      │
│              ┌─────────────────────┼─────────────────────┐                │
│              │                     │                     │                │
│              ▼                     ▼                     ▼                │
│     ┌─────────────┐       ┌─────────────┐       ┌─────────────┐           │
│     │  Hub EC2 1  │       │  Hub EC2 2  │       │  Hub EC2 3  │           │
│     │  (primary)  │◄─────►│  (replica)  │◄─────►│  (replica)  │           │
│     └──────┬──────┘       └─────────────┘       └─────────────┘           │
│            │                                                              │
│            │  RDS PostgreSQL (state sync)                                 │
│            │  ElastiCache Redis (pub/sub, sessions)                       │
│            ▼                                                              │
│     ┌─────────────────────────────────────────────────────────────┐       │
│     │                    RDS / ElastiCache                       │       │
│     └─────────────────────────────────────────────────────────────┘       │
│                                                                           │
└───────────────────────────────────────────────────────────────────────────┘
                                │
       ┌────────────────────────┼────────────────────────┐
       │                        │                        │
       ▼                        ▼                        ▼
┌─────────────┐          ┌─────────────┐          ┌─────────────┐
│  gvAgent    │          │  gvAgent    │          │  gvAgent    │
│  (on-prem)  │          │  (AWS EC2)  │          │  (macOS)    │
│             │          │             │          │             │
│  WSS ──────►│──────────│─────────────│──────────│◄─── WSS     │
└─────────────┘          └─────────────┘          └─────────────┘

8.2 DNS Configuration

Domain	Type	Target	Purpose
greatvibe.ai	A/AAAA	CloudFlare proxy → ALB	Main hub UI
api.greatvibe.ai	A/AAAA	CloudFlare proxy → ALB	REST API
ws.greatvibe.ai	A/AAAA	Direct to ALB (no proxy)	Agent WebSocket
*.greatvibe.ai	CNAME	greatvibe.ai	Subdomains

8.3 WebSocket Protocol

// Agent → Hub WebSocket connection
wss://ws.greatvibe.ai/agent/connect
  ?agent_id=agent-prod-01
  &token=eyJhbGciOi...
  &version=1.2.3

// Message envelope
{
  "id": "msg_abc123",        // Message ID for ack/retry
  "type": "event_type",      // See message types below
  "ts": "2026-01-05T04:00:00Z",
  "data": { ... }            // Type-specific payload
}

// Message types: Agent → Hub
- register          // Initial registration with capabilities
- heartbeat         // Keep-alive (every 30s)
- event             // Session event (turn_started, tool_call, etc.)
- status            // Agent status update
- replay_response   // Response to replay request

// Message types: Hub → Agent
- registered        // Registration confirmed
- work              // Work assignment (prompt, flow)
- stop              // Stop current work
- replay_request    // Request session history
- config_update     // Push new configuration
- ping              // Health check

8.4 API Endpoints

Endpoint	Method	Auth	Description
/api/v1/agents	GET	User	List registered agents
/api/v1/agents/:id	GET	User	Get agent details + status
/api/v1/sessions	POST	User	Create session (assigns to agent)
/api/v1/sessions/:id	GET	User	Get session state
/api/v1/sessions/:id/prompt	POST	User	Send prompt (returns event stream)
/api/v1/sessions/:id/events	GET	User	Get events from seq N
/api/v1/flows	GET/POST	User	List/create flows
/agent/connect	WebSocket	Agent	Agent registration + events
/session/:id/subscribe	WebSocket	User	Real-time session events

8.5 CloudFlare Workers (Edge Functions)

// Edge functions for latency-sensitive operations

// Worker: auth-edge
// Validates JWT at edge, reduces origin load

// Worker: rate-limit
// Per-IP and per-org rate limiting

// Worker: quick-turn-cache
// Cache common quick-turn responses

9. Session Management & Playback

9.1 Session Lifecycle

┌─────────┐   create    ┌─────────┐   prompt    ┌─────────┐
│  null   │───────────►│  idle   │───────────►│ working │
└─────────┘             └────┬────┘             └────┬────┘
                             │                       │
                        timeout/                turn_complete
                        archive                      │
                             │                       │
                             ▼                       ▼
                        ┌─────────┐             ┌─────────┐
                        │archived │◄────────────│  idle   │
                        └─────────┘   archive   └─────────┘

9.2 Agent-Side Session Storage

~/.gvagent/data/
├── sessions.db                 # SQLite - session metadata
│
├── events/
│   ├── sess_abc123.jsonl      # Event journal for session
│   ├── sess_def456.jsonl
│   └── sess_ghi789.jsonl
│
└── artifacts/
    └── sess_abc123/
        ├── output_001.html    # Generated outputs
        └── report_002.json

Sessions Database Schema

CREATE TABLE sessions (
    id              TEXT PRIMARY KEY,
    flow_id         TEXT,
    provider_id     TEXT NOT NULL,
    model           TEXT NOT NULL,
    working_dir     TEXT NOT NULL,
    status          TEXT NOT NULL,  -- idle, working, archived
    claude_session  TEXT,           -- For CLI --resume
    turn_count      INTEGER DEFAULT 0,
    last_seq        INTEGER DEFAULT 0,
    created_at      TEXT NOT NULL,
    updated_at      TEXT NOT NULL,
    metadata        TEXT            -- JSON blob
);

CREATE TABLE turns (
    id              TEXT PRIMARY KEY,
    session_id      TEXT NOT NULL,
    sequence        INTEGER NOT NULL,
    prompt          TEXT NOT NULL,
    status          TEXT NOT NULL,
    start_seq       INTEGER,        -- First event seq
    end_seq         INTEGER,        -- Last event seq
    created_at      TEXT NOT NULL,
    completed_at    TEXT,
    metrics         TEXT,           -- JSON: tokens, cost, duration
    FOREIGN KEY (session_id) REFERENCES sessions(id)
);

9.3 Event Journal Format

// sess_abc123.jsonl - append-only event journal
{"seq":1,"ts":"2026-01-05T04:00:00Z","type":"session_started","data":{"provider":"claude-cli","model":"claude-opus-4"}}
{"seq":2,"ts":"2026-01-05T04:00:01Z","type":"turn_started","data":{"turn_id":"turn_001","prompt":"Add authentication"}}
{"seq":3,"ts":"2026-01-05T04:00:02Z","type":"turn_text","data":{"turn_id":"turn_001","content":"I'll help you add authentication..."}}
{"seq":4,"ts":"2026-01-05T04:00:03Z","type":"tool_call","data":{"turn_id":"turn_001","tool":"Read","input":{"file_path":"/src/auth.ts"}}}
{"seq":5,"ts":"2026-01-05T04:00:04Z","type":"tool_result","data":{"turn_id":"turn_001","tool":"Read","output":"...","duration_ms":50}}
{"seq":6,"ts":"2026-01-05T04:00:10Z","type":"turn_completed","data":{"turn_id":"turn_001","metrics":{"input_tokens":1500,"output_tokens":2000,"cost_usd":0.05}}}

9.4 Session Replay Protocol

// Hub requests replay (e.g., new viewer joins)
{
  "type": "replay_request",
  "session_id": "sess_abc123",
  "from_seq": 0,          // Start from beginning
  "to_seq": -1            // To latest (-1 = all)
}

// Agent streams events back
{
  "type": "replay_response",
  "session_id": "sess_abc123",
  "events": [
    {"seq":1,"ts":"...","type":"session_started",...},
    {"seq":2,"ts":"...","type":"turn_started",...},
    ...
  ],
  "is_complete": true,
  "total_events": 150
}

// For large sessions, chunked replay
{
  "type": "replay_response",
  "session_id": "sess_abc123",
  "events": [...],        // 100 events per chunk
  "is_complete": false,
  "next_seq": 101
}

9.5 Multi-Viewer Support

// Browser subscribes to session
WebSocket: wss://greatvibe.ai/session/sess_abc123/subscribe
  ?token=user_jwt
  &from_seq=0         // Catch up from beginning

// Hub forwards events from agent to all viewers
Agent ──event──► Hub ──broadcast──► Viewer 1
                      ──broadcast──► Viewer 2
                      ──broadcast──► Viewer 3

// Late-joining viewer catches up via replay
Viewer 3 ──subscribe(from_seq=0)──► Hub
         ◄──replay(seq 1-150)────────
         ◄──live events (seq 151+)───

10. Connection Management & Recovery

10.1 Connection States

┌─────────────┐   connect    ┌─────────────┐   registered   ┌─────────────┐
│ disconnected│─────────────►│ connecting  │──────────────►│ connected   │
└──────┬──────┘              └──────┬──────┘               └──────┬──────┘
       │                            │                             │
       │    reconnect               │ timeout/error         disconnect
       │    (with backoff)          │                             │
       │                            ▼                             │
       │                     ┌─────────────┐                      │
       └─────────────────────│ reconnecting│◄─────────────────────┘
                             └─────────────┘

10.2 Reconnection Strategy

type ReconnectConfig struct {
    InitialDelay    time.Duration  // 1 second
    MaxDelay        time.Duration  // 5 minutes
    Multiplier      float64        // 2.0 (exponential backoff)
    Jitter          float64        // 0.1 (10% random jitter)
    MaxAttempts     int            // -1 (infinite)
}

// Reconnect sequence:
// Attempt 1: 1s
// Attempt 2: 2s + jitter
// Attempt 3: 4s + jitter
// Attempt 4: 8s + jitter
// ...
// Attempt N: min(2^N, 300s) + jitter

10.3 Work Preservation

// Agent continues working during disconnection
// Events are queued locally, synced on reconnect

type EventQueue struct {
    events      []Event       // Pending events to sync
    lastSyncSeq int64         // Last seq confirmed by hub
    maxQueueSize int          // 10000 events max
}

// On reconnect:
// 1. Agent reports last_sync_seq
// 2. Hub requests missing events (if any)
// 3. Agent sends queued events
// 4. Normal operation resumes

10.4 Heartbeat & Health

// Agent sends heartbeat every 30 seconds
{
  "type": "heartbeat",
  "ts": "2026-01-05T04:00:00Z",
  "status": {
    "active_sessions": 2,
    "pending_events": 0,
    "cpu_percent": 15,
    "memory_mb": 256
  }
}

// Hub responds with pong
{
  "type": "pong",
  "ts": "2026-01-05T04:00:00Z"
}

// No heartbeat for 90s → Hub marks agent offline
// No pong for 90s → Agent reconnects

11. Failover & Disaster Recovery

11.1 Same-Node Agent Failover

Goal: If an agent crashes, a supervisor restarts it and work resumes automatically.

// systemd unit file for agent
[Unit]
Description=greatVibeAgent
After=network.target

[Service]
Type=simple
User=gvagent
ExecStart=/usr/local/bin/gvagent
Restart=always
RestartSec=5
WatchdogSec=60

[Install]
WantedBy=multi-user.target

Recovery Flow

Agent process crashes
systemd restarts agent within 5 seconds
Agent reads sessions.db — finds active sessions
Agent reconnects to hub with same agent_id
Hub re-routes pending work to reconnected agent
Agent resumes in-progress turns from last checkpoint

11.2 Hub Failover (Cloud)

// Multi-AZ deployment with ALB health checks

┌─────────────────────────────────────────────────────────────────┐
│                    Application Load Balancer                    │
│                    (health check: /health)                      │
└───────────────────────────┬─────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
        ▼                   ▼                   ▼
   ┌─────────┐         ┌─────────┐         ┌─────────┐
   │ Hub AZ-a │         │ Hub AZ-b │         │ Hub AZ-c │
   │ (active)│◄───────►│ (active)│◄───────►│ (active)│
   └────┬────┘         └────┬────┘         └────┬────┘
        │                   │                   │
        └───────────────────┼───────────────────┘
                            │
                            ▼
              ┌──────────────────────────┐
              │  RDS Multi-AZ (primary)  │
              │  + Read Replicas          │
              └──────────────────────────┘

11.3 Data Durability

Component	Storage	Durability	Backup
Agent sessions	Local SQLite + JSONL	Disk durability	Optional S3 sync
Hub metadata	RDS PostgreSQL	99.99999999%	Daily snapshots
Session channels	ElastiCache Redis	In-memory	Reconstructable
Audit logs	S3 + Glacier	99.999999999%	7-year retention

11.4 Disaster Recovery Targets

Metric	Target	Mechanism
RTO (Recovery Time Objective)	< 5 minutes	Auto-restart, ALB failover
RPO (Recovery Point Objective)	0 (no data loss)	Agent has source of truth
Agent uptime	99.9%	systemd watchdog
Hub uptime (cloud)	99.9%	Multi-AZ, auto-scaling

12. Multi-Agent Architecture

12.1 Hub and Spoke Model

                         ┌───────────────────────────┐
                         │      HUB (Central)        │
                         │                           │
                         │   ┌─────────────────┐     │
                         │   │   Work Queue    │     │
                         │   │   ┌───┬───┬───┐ │     │
                         │   │   │ W │ W │ W │ │     │
                         │   │   └───┴───┴───┘ │     │
                         │   └────────┬────────┘     │
                         │            │              │
                         │   ┌────────┴────────┐     │
                         │   │  Agent Registry │     │
                         │   │  ┌────┬────┬────┐    │
                         │   │  │A1  │A2  │A3  │    │
                         │   │  └────┴────┴────┘    │
                         │   └─────────────────┘     │
                         └─────────────┬─────────────┘
                                       │
         ┌─────────────────────────────┼─────────────────────────────┐
         │                             │                             │
         ▼                             ▼                             ▼
  ┌─────────────┐               ┌─────────────┐               ┌─────────────┐
  │ Agent A1    │               │ Agent A2    │               │ Agent A3    │
  │ US-West     │               │ US-East     │               │ EU-West     │
  │             │               │             │               │             │
  │ Capabilities│               │ Capabilities│               │ Capabilities│
  │ - Claude    │               │ - Claude    │               │ - Claude    │
  │ - Postgres  │               │ - OpenAI    │               │ - K8s       │
  └─────────────┘               └─────────────┘               └─────────────┘

12.2 Work Assignment Algorithm

func (h *Hub) AssignWork(work Work) (Agent, error) {
    // 1. Filter by required capabilities
    candidates := h.filterByCapabilities(work.RequiredCapabilities)
    if len(candidates) == 0 {
        return nil, ErrNoCapableAgent
    }
    
    // 2. Filter by affinity (same session should go to same agent)
    if work.SessionID != "" {
        if agent := h.getSessionAgent(work.SessionID); agent != nil {
            return agent, nil
        }
    }
    
    // 3. Load balancing: pick least loaded agent
    return h.leastLoaded(candidates), nil
}

12.3 Point-to-Point Agent Communication

Future capability: Agents can communicate directly for specialized tasks (e.g., database agent triggers K8s agent for scaling).

// Agent-to-agent via hub relay
Agent A1 ──request──► Hub ──forward──► Agent A3
         ◄──response───     ◄──response───

// Example: Database backup trigger K8s scale-down
{
  "type": "agent_request",
  "from": "agent-postgres-01",
  "to": "agent-k8s-01",
  "action": "scale_replicas",
  "data": {
    "deployment": "api-server",
    "replicas": 0,
    "reason": "database maintenance"
  }
}

13. Security Model

13.1 Credential Storage

Credential Type	Local Storage	Cloud Storage
Hub connection token	File (0600 perms)	AWS Secrets Manager
Provider API keys	Env vars or keychain	AWS Secrets Manager
User session tokens	Hub-managed (SQLite)	ElastiCache + RDS
Encryption keys	OS keychain	AWS KMS

13.2 Provider Credential Flow

// Option 1: Agent-local credentials
Agent ──reads──► ~/.gvagent/providers/claude.env (ANTHROPIC_API_KEY)
      ──calls──► api.anthropic.com

// Option 2: Hub-managed credentials (more secure)
Agent ──request──► Hub ──fetch──► Secrets Manager
      ◄──encrypted key────
      ──decrypt with agent key──► use for session
      ──clear after use────────►

13.3 Token Lifecycle

type Token struct {
    ID          string    // UUID
    Type        string    // "user", "agent", "api"
    Subject     string    // user_id or agent_id
    Scopes      []string  // Permissions
    IssuedAt    time.Time
    ExpiresAt   time.Time
    RevokedAt   *time.Time // nil if not revoked
}

// Token TTLs
// User session: 24 hours (refresh with activity)
// Agent token: 1 year (or until revoked)
// API key: No expiry (explicit revocation)

13.4 Security Boundaries

┌─────────────────────────────────────────────────────────────────┐
│                      UNTRUSTED ZONE                            │
│                                                                 │
│   ┌─────────────┐         ┌─────────────┐                       │
│   │   Browser   │         │   AI API    │                       │
│   │  (user's)   │         │  Response   │                       │
│   └──────┬──────┘         └──────┬──────┘                       │
│          │                       │                              │
└──────────┼───────────────────────┼──────────────────────────────┘
           │                       │
           ▼                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                      TRUST BOUNDARY                            │
│                                                                 │
│   Authentication │ Authorization │ Input Validation             │
│                                                                 │
└──────────────────────────────────────────────────────────────────┘
           │                       │
           ▼                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                      TRUSTED ZONE                              │
│                                                                 │
│   ┌─────────────┐         ┌─────────────┐                       │
│   │     Hub     │◄───────►│    Agent    │                       │
│   │             │         │             │                       │
│   │ Signed msgs │         │ Guardrails  │                       │
│   │ Audit logs  │         │ Sandbox     │                       │
│   └─────────────┘         └─────────────┘                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

13.5 Threat Mitigations

Threat	Mitigation
Prompt injection via AI	Guardrails block dangerous operations regardless of AI output
Credential theft	Credentials in env vars or keychain, never in config files
Unauthorized agent	Agent tokens are hub-signed, verified on every request
Session hijacking	Tokens bound to IP, short TTL, activity-based refresh
Data exfiltration	Network guardrails limit outbound connections
Privilege escalation	Agent runs as unprivileged user, no sudo in guardrails

14. Configuration Parameters Reference

14.1 Environment Variables

Variable	Default	Description
GVAGENT_ID	hostname	Unique agent identifier
GVAGENT_HUB_URL	-	Hub WebSocket URL (required)
GVAGENT_TOKEN	-	Hub authentication token
GVAGENT_DATA_DIR	~/.gvagent	Data directory
GVAGENT_LOG_LEVEL	info	debug, info, warn, error
GVAGENT_LOG_FORMAT	json	json or text
ANTHROPIC_API_KEY	-	Claude API key
OPENAI_API_KEY	-	OpenAI API key
GVAGENT_CLAUDE_BINARY	/usr/local/bin/claude	Path to Claude CLI
GVAGENT_CODEX_BINARY	/usr/local/bin/codex	Path to Codex CLI

14.2 Safety Limits

Parameter	Default	Description
max_turn_duration_ms	900000	15 minutes hard limit per turn
max_tool_calls_per_turn	200	Prevent runaway tool loops
idle_timeout_ms	600000	10 minutes no activity → stop
max_concurrent_sessions	5	Sessions per agent
max_output_tokens	16384	Per API call
max_file_write_mb	10	Max file size for writes

15. API Contract with greatVibe Platform

15.1 Agent Registration

// Agent → Hub: Registration message
{
  "type": "register",
  "agent_id": "agent-prod-01",
  "version": "1.2.3",
  "capabilities": {
    "providers": ["claude-cli", "claude-api", "openai-api"],
    "tools": ["read", "edit", "bash", "glob", "grep"],
    "max_concurrent_sessions": 5
  },
  "system_info": {
    "os": "linux",
    "arch": "amd64",
    "hostname": "prod-server-01",
    "cpu_cores": 8,
    "memory_gb": 32
  },
  "token": "eyJhbGciOi..."
}

// Hub → Agent: Registration confirmed
{
  "type": "registered",
  "hub_version": "2.0.1",
  "config_version": 42,
  "features": ["prompt_cache", "multi_viewer"]
}

15.2 Work Assignment

// Hub → Agent: Work assignment
{
  "type": "work",
  "work_id": "work_xyz789",
  "session_id": "sess_abc123",
  "flow_id": "flow_def456",
  "turn_id": "turn_001",
  "prompt": "Add user authentication to the API",
  "attachments": [],
  "config": {
    "provider": "claude-cli",
    "model": "claude-opus-4",
    "working_dir": "/konnectvol"
  },
  "user": {
    "id": "user_johnathon",
    "name": "Johnathon"
  }
}

// Agent → Hub: Work accepted
{
  "type": "work_accepted",
  "work_id": "work_xyz789"
}

15.3 Event Streaming

// Agent → Hub: Session events (real-time)

// Turn started
{"type":"event","session_id":"sess_abc123","seq":1,"event":{"type":"turn_started","turn_id":"turn_001"}}

// Text chunk (streaming)
{"type":"event","session_id":"sess_abc123","seq":2,"event":{"type":"turn_text","turn_id":"turn_001","content":"I'll help you..."}}

// Tool call
{"type":"event","session_id":"sess_abc123","seq":3,"event":{"type":"tool_call","turn_id":"turn_001","tool":"Read","input":{"file_path":"/src/auth.ts"}}}

// Tool result
{"type":"event","session_id":"sess_abc123","seq":4,"event":{"type":"tool_result","turn_id":"turn_001","tool":"Read","summary":"Read 150 lines from /src/auth.ts"}}

// Turn completed
{"type":"event","session_id":"sess_abc123","seq":5,"event":{"type":"turn_completed","turn_id":"turn_001","metrics":{"input_tokens":1500,"output_tokens":2000,"cost_usd":0.05,"duration_ms":15000}}}

15.4 Error Handling

// Error codes
const (
    ErrCodeInvalidToken    = "INVALID_TOKEN"
    ErrCodeAgentOffline    = "AGENT_OFFLINE"
    ErrCodeSessionNotFound = "SESSION_NOT_FOUND"
    ErrCodeProviderError   = "PROVIDER_ERROR"
    ErrCodeGuardrailDeny   = "GUARDRAIL_DENIED"
    ErrCodeRateLimited     = "RATE_LIMITED"
    ErrCodeTurnTimeout     = "TURN_TIMEOUT"
)

// Error event
{
  "type": "event",
  "session_id": "sess_abc123",
  "seq": 10,
  "event": {
    "type": "turn_failed",
    "turn_id": "turn_001",
    "error": {
      "code": "PROVIDER_ERROR",
      "message": "Claude API returned 429: Rate limited",
      "retryable": true,
      "retry_after_ms": 60000
    }
  }
}

16. greatVibe.local Security Model

16.1 Trust Model

greatVibe.local is designed for trusted environments — your own machine or private network. It assumes the operator has full control and trusts the agent.

┌─────────────────────────────────────────────────────────────────┐
│                    TRUST BOUNDARY: Your Machine                │
│                                                                 │
│   ┌─────────────┐         ┌─────────────┐                       │
│   │ greatVibe   │◄───────►│  gvAgent    │                       │
│   │ .local hub  │ loopback│             │                       │
│   │             │ (127.0) │  Claude CLI │                       │
│   │ Port 8666   │         │  Tools      │                       │
│   └─────────────┘         └─────────────┘                       │
│                                                                 │
│   No external network access required for hub ↔ agent           │
└─────────────────────────────────────────────────────────────────┘
           │
           │ HTTPS (user browser)
           ▼
┌─────────────────────────────────────────────────────────────────┐
│                    NETWORK BOUNDARY                            │
│                                                                 │
│   - Password/API key authentication                             │
│   - TLS encryption (self-signed or Let's Encrypt)               │
│   - Optional: Cloudflare Tunnel for remote access               │
└─────────────────────────────────────────────────────────────────┘

16.2 Local Security Checklist

Control	Default	Recommendation
Hub binding	127.0.0.1	Keep localhost unless remote needed
Authentication	Password	Use strong password or API key
TLS	Optional	Enable for remote access
Guardrails	Permissive	Customize for your project
Agent user	Current user	Run as dedicated user if multi-user
Data dir perms	0700	Ensure only owner can access

16.3 Remote Access Options

Method	Security Level	Use Case
localhost only	Highest	Solo dev on same machine
SSH tunnel	High	Remote access via SSH
Cloudflare Tunnel	Medium-High	Zero-config remote access
Direct expose + TLS	Medium	LAN access for team

Appendix A: Implementation Roadmap

Phase 1: Core Agent (P0)

Go project setup, WebSocket client
SQLite session store, JSONL event journal
Claude CLI provider with guardrails
Hub connection and work assignment

Phase 2: Additional Providers (P1)

Claude API provider (Quick Turn)
OpenAI API provider
Codex CLI provider
Google Gemini provider

Phase 3: Local Models (P2)

OpenWebUI integration
VLLM support
SGLang support

Phase 4: IDE Integrations (P3)

VS Code extension
Android Studio plugin
Xcode plugin

Document Summary

This design document defines the comprehensive architecture for greatVibeAgent — a cross-platform Go binary that serves as the execution layer for the greatVibe AI development platform. It covers provider plugins for Claude, OpenAI, Gemini, and local models; target platforms from AWS Linux to Xcode; a declarative guardrails system to replace dangerous open permissions; full AAA (authentication, authorization, accounting) for both local and cloud deployments; configuration management with hub push/pull; networking architecture with WebSockets, AWS ALB, and CloudFlare; session management with SQLite and JSONL event journals; connection recovery and failover; multi-agent hub-and-spoke architecture; comprehensive security model; and the complete API contract with the greatVibe platform.

What's Next?

Choose an action:

Quick Actions

Original Request

No layout configured

Details

Type General

Status Completed

Scope vibetools

Tags agentarchitecturedesignsecuritynetworking

Created 5 Jan 2026, 6:12 pm

Updated 5 Jan 2026, 6:12 pm

Timing

⏱️ 584.3s

9 tools

● TTFE 1% ● Thinking 98% ● Tools 1%

Created By claude

Raw Data

{
  "id": "91385dc8-c48a-40cd-b5e4-517758608dcb",
  "type": "general",
  "status": "completed",
  "title": "greatVibeAgent Design Document v1.0",
  "description": "Comprehensive design document for the cross-platform Go agent with provider plugins, security, and networking architecture",
  "context": {
    "output": "<div style=\"background:#1e1e1e;color:#e0e0e0;padding:24px;border-radius:8px;font-family:'Consolas','Monaco',monospace;max-width:100%;overflow-x:auto;\">\n\n<h1 style=\"font-family:sans-serif;color:#fff;margin:0 0 8px 0;font-size:2rem;\">greatVibeAgent Design Document</h1>\n<p style=\"color:#9ca3af;margin:0 0 24px 0;font-family:sans-serif;\">Version 1.0 | 2026-01-05 | Status: Draft</p>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:24px;\">\n<h2 style=\"color:#98c379;margin:0 0 12px 0;font-family:sans-serif;\">Table of Contents</h2>\n<ol style=\"color:#61afef;margin:0;padding-left:20px;line-height:2;\">\n<li>Executive Summary</li>\n<li>Agent Overview & Purpose</li>\n<li>Provider Plugin Architecture</li>\n<li>Target Development Environments</li>\n<li>Permissions & Guardrails System</li>\n<li>Authentication, Authorization & Accounting (AAA)</li>\n<li>Configuration Management</li>\n<li>Networking Architecture</li>\n<li>Session Management & Playback</li>\n<li>Connection Management & Recovery</li>\n<li>Failover & Disaster Recovery</li>\n<li>Multi-Agent Architecture</li>\n<li>Security Model</li>\n<li>Configuration Parameters Reference</li>\n<li>API Contract</li>\n<li>greatVibe.local Security Model</li>\n</ol>\n</div>\n\n<hr style=\"border:none;border-top:1px solid #444;margin:32px 0;\">\n\n<!-- SECTION 1: EXECUTIVE SUMMARY -->\n<h2 style=\"font-family:sans-serif;color:#fff;margin:32px 0 16px 0;border-bottom:2px solid #98c379;padding-bottom:8px;\">1. Executive Summary</h2>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<p style=\"color:#e0e0e0;margin:0;line-height:1.8;\">greatVibeAgent is a <span style=\"color:#98c379;font-weight:bold;\">cross-platform AI agent binary</span> written in Go that serves as the execution layer for the greatVibe platform. It connects TO the hub (not the other way around), executes AI-powered development tasks, and maintains session state locally.</p>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">Core Value Proposition</h3>\n<ul style=\"color:#e0e0e0;line-height:2;\">\n<li><span style=\"color:#e5c07b;\">Provider Agnostic:</span> Support multiple AI providers through unified plugin architecture</li>\n<li><span style=\"color:#e5c07b;\">Cross-Platform:</span> Single binary deployment for Linux, macOS, Windows</li>\n<li><span style=\"color:#e5c07b;\">Resilient:</span> Local state storage survives hub restarts, network failures</li>\n<li><span style=\"color:#e5c07b;\">Secure:</span> Sandboxed execution, credential isolation, audit logging</li>\n<li><span style=\"color:#e5c07b;\">Scalable:</span> Multiple agents per hub, hub-and-spoke architecture</li>\n</ul>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">Key Architectural Decisions</h3>\n<table style=\"width:100%;border-collapse:collapse;margin:12px 0;\">\n<tr style=\"background:#3d3d3d;\">\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Decision</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Rationale</th>\n</tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">Go Language</td><td style=\"padding:10px;border:1px solid #555;\">Goroutines for parallelism, single binary, cross-compile</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">Agent-Initiated Connections</td><td style=\"padding:10px;border:1px solid #555;\">Restart resilience, firewall-friendly, NAT traversal</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">SQLite + JSONL Storage</td><td style=\"padding:10px;border:1px solid #555;\">No external dependencies, Claude-readable, fast</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">WebSocket Bidirectional</td><td style=\"padding:10px;border:1px solid #555;\">Real-time events, overcome SSE limitations</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">Provider Plugins</td><td style=\"padding:10px;border:1px solid #555;\">Extensible, vendor-neutral, future-proof</td></tr>\n</table>\n\n<hr style=\"border:none;border-top:1px solid #444;margin:32px 0;\">\n\n<!-- SECTION 2: AGENT OVERVIEW -->\n<h2 style=\"font-family:sans-serif;color:#fff;margin:32px 0 16px 0;border-bottom:2px solid #98c379;padding-bottom:8px;\">2. Agent Overview & Purpose</h2>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">2.1 What is greatVibeAgent?</h3>\n<p style=\"color:#e0e0e0;line-height:1.8;\">greatVibeAgent is the <strong>execution engine</strong> of the greatVibe platform. It:</p>\n\n<ul style=\"color:#e0e0e0;line-height:2;\">\n<li>Receives work assignments from the hub (prompts, tasks, flows)</li>\n<li>Executes AI provider calls (Claude, OpenAI, Gemini, etc.)</li>\n<li>Performs file system operations, git commands, and tool calls</li>\n<li>Streams results back to the hub in real-time</li>\n<li>Maintains complete session history locally for replay</li>\n</ul>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">2.2 Agent-Hub Relationship</h3>\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;color:#e0e0e0;\">\n┌─────────────────────────────────────────────────────────────────┐\n│                    GREATVIBE HUB                                │\n│                                                                 │\n│   Work Queue │ Agent Registry │ Session Channels │ State Store  │\n│                                                                 │\n└──────────────────────────────┬──────────────────────────────────┘\n                               │\n           <span style=\"color:#98c379;\">agents connect TO hub (not the other way)</span>\n                               │\n       ┌───────────────────────┼───────────────────────┐\n       │                       │                       │\n       ▼                       ▼                       ▼\n┌─────────────┐         ┌─────────────┐         ┌─────────────┐\n│ <span style=\"color:#61afef;\">gvAgent</span>     │         │ <span style=\"color:#61afef;\">gvAgent</span>     │         │ <span style=\"color:#c678dd;\">gvAgent</span>     │\n│ <span style=\"color:#7f848e;\">(Linux)</span>     │         │ <span style=\"color:#7f848e;\">(Windows)</span>   │         │ <span style=\"color:#7f848e;\">(postgres)</span>  │\n│             │         │             │         │             │\n│ <span style=\"color:#e5c07b;\">Local</span>       │         │ <span style=\"color:#e5c07b;\">Local</span>       │         │ <span style=\"color:#e5c07b;\">Local</span>       │\n│ <span style=\"color:#e5c07b;\">Session</span>     │         │ <span style=\"color:#e5c07b;\">Session</span>     │         │ <span style=\"color:#e5c07b;\">Session</span>     │\n│ <span style=\"color:#e5c07b;\">Storage</span>     │         │ <span style=\"color:#e5c07b;\">Storage</span>     │         │ <span style=\"color:#e5c07b;\">Storage</span>     │\n└─────────────┘         └─────────────┘         └─────────────┘\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">2.3 Problems Solved</h3>\n<table style=\"width:100%;border-collapse:collapse;margin:12px 0;\">\n<tr style=\"background:#3d3d3d;\">\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Problem</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Solution</th>\n</tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Hub restart loses session state</td><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">Agent stores all session data locally</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Vendor lock-in to single AI provider</td><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">Provider plugin architecture</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Different OS/platform requirements</td><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">Cross-compiled Go binary</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">CLI permission prompts block automation</td><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">Declarative guardrails system</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Unreliable network connections</td><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">Local execution + eventual sync</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">No replay/audit capability</td><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">JSONL event journal with checksums</td></tr>\n</table>\n\n<hr style=\"border:none;border-top:1px solid #444;margin:32px 0;\">\n\n<!-- SECTION 3: PROVIDER PLUGINS -->\n<h2 style=\"font-family:sans-serif;color:#fff;margin:32px 0 16px 0;border-bottom:2px solid #98c379;padding-bottom:8px;\">3. Provider Plugin Architecture</h2>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">3.1 Design Philosophy</h3>\n<p style=\"color:#e0e0e0;line-height:1.8;\">Providers are <strong>statically compiled plugins</strong> (not dynamic loading) for security and simplicity. Each provider implements a common interface but may have different capabilities.</p>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">3.2 Provider Interface</h3>\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#c678dd;\">// Go interface for all providers</span>\n<span style=\"color:#e5c07b;\">type</span> Provider <span style=\"color:#e5c07b;\">interface</span> {\n    <span style=\"color:#7f848e;\">// Identity</span>\n    <span style=\"color:#61afef;\">ID()</span> <span style=\"color:#e5c07b;\">string</span>           <span style=\"color:#7f848e;\">// \"claude\", \"openai\", etc.</span>\n    <span style=\"color:#61afef;\">Name()</span> <span style=\"color:#e5c07b;\">string</span>         <span style=\"color:#7f848e;\">// \"Claude\" for display</span>\n    <span style=\"color:#61afef;\">Type()</span> ProviderType   <span style=\"color:#7f848e;\">// CLI, API, or VLM</span>\n    \n    <span style=\"color:#7f848e;\">// Capabilities</span>\n    <span style=\"color:#61afef;\">Capabilities()</span> Capabilities\n    <span style=\"color:#61afef;\">Models()</span> []ModelInfo\n    \n    <span style=\"color:#7f848e;\">// Lifecycle</span>\n    <span style=\"color:#61afef;\">Initialize(</span>config ProviderConfig<span style=\"color:#61afef;\">)</span> <span style=\"color:#e5c07b;\">error</span>\n    <span style=\"color:#61afef;\">IsAvailable()</span> <span style=\"color:#e5c07b;\">bool</span>\n    <span style=\"color:#61afef;\">Shutdown()</span> <span style=\"color:#e5c07b;\">error</span>\n    \n    <span style=\"color:#7f848e;\">// Execution</span>\n    <span style=\"color:#61afef;\">Chat(</span>ctx context.Context, req ChatRequest<span style=\"color:#61afef;\">)</span> <span style=\"color:#e5c07b;\">*</span>ChatStream\n    <span style=\"color:#61afef;\">Execute(</span>ctx context.Context, req ExecuteRequest<span style=\"color:#61afef;\">)</span> <span style=\"color:#e5c07b;\">*</span>ExecuteStream\n}\n\n<span style=\"color:#e5c07b;\">type</span> ProviderType <span style=\"color:#e5c07b;\">int</span>\n<span style=\"color:#e5c07b;\">const</span> (\n    ProviderTypeCLI ProviderType = <span style=\"color:#d19a66;\">iota</span>  <span style=\"color:#7f848e;\">// Claude CLI, Codex CLI</span>\n    ProviderTypeAPI                       <span style=\"color:#7f848e;\">// Claude API, OpenAI API</span>\n    ProviderTypeVLM                       <span style=\"color:#7f848e;\">// Vision LLMs (Gemini, etc.)</span>\n    ProviderTypeLocal                     <span style=\"color:#7f848e;\">// VLLM, SGLang, Ollama</span>\n)\n\n<span style=\"color:#e5c07b;\">type</span> Capabilities <span style=\"color:#e5c07b;\">struct</span> {\n    ToolUse       <span style=\"color:#e5c07b;\">bool</span>    <span style=\"color:#7f848e;\">// Can call tools (Read, Edit, Bash)</span>\n    Vision        <span style=\"color:#e5c07b;\">bool</span>    <span style=\"color:#7f848e;\">// Can process images</span>\n    Streaming     <span style=\"color:#e5c07b;\">bool</span>    <span style=\"color:#7f848e;\">// Supports streaming responses</span>\n    PromptCache   <span style=\"color:#e5c07b;\">bool</span>    <span style=\"color:#7f848e;\">// Supports prompt caching</span>\n    CodeExec      <span style=\"color:#e5c07b;\">bool</span>    <span style=\"color:#7f848e;\">// Can execute arbitrary code</span>\n    MaxContext    <span style=\"color:#e5c07b;\">int</span>     <span style=\"color:#7f848e;\">// Maximum context window</span>\n}\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">3.3 Supported Providers</h3>\n\n<table style=\"width:100%;border-collapse:collapse;margin:12px 0;font-size:0.9em;\">\n<tr style=\"background:#3d3d3d;\">\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Provider</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Type</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Tools</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Vision</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Use Cases</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Priority</th>\n</tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">Claude CLI</td><td style=\"padding:10px;border:1px solid #555;\">CLI</td><td style=\"padding:10px;border:1px solid #555;\">✅ Full</td><td style=\"padding:10px;border:1px solid #555;\">✅</td><td style=\"padding:10px;border:1px solid #555;\">Vibe coding, full automation</td><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">P0</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">Claude API</td><td style=\"padding:10px;border:1px solid #555;\">API</td><td style=\"padding:10px;border:1px solid #555;\">⚠️ MCP only</td><td style=\"padding:10px;border:1px solid #555;\">✅</td><td style=\"padding:10px;border:1px solid #555;\">Quick Turn, chat</td><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">P0</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#61afef;\">OpenAI API</td><td style=\"padding:10px;border:1px solid #555;\">API</td><td style=\"padding:10px;border:1px solid #555;\">⚠️ Functions</td><td style=\"padding:10px;border:1px solid #555;\">✅</td><td style=\"padding:10px;border:1px solid #555;\">Chat, alternatives</td><td style=\"padding:10px;border:1px solid #555;color:#61afef;\">P1</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#61afef;\">Codex CLI</td><td style=\"padding:10px;border:1px solid #555;\">CLI</td><td style=\"padding:10px;border:1px solid #555;\">✅ Full</td><td style=\"padding:10px;border:1px solid #555;\">❌</td><td style=\"padding:10px;border:1px solid #555;\">OpenAI with tool access</td><td style=\"padding:10px;border:1px solid #555;color:#61afef;\">P1</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#61afef;\">Google Gemini</td><td style=\"padding:10px;border:1px solid #555;\">API</td><td style=\"padding:10px;border:1px solid #555;\">⚠️ Limited</td><td style=\"padding:10px;border:1px solid #555;\">✅</td><td style=\"padding:10px;border:1px solid #555;\">Vision tasks, multimodal</td><td style=\"padding:10px;border:1px solid #555;color:#61afef;\">P1</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#e5c07b;\">Google VLM</td><td style=\"padding:10px;border:1px solid #555;\">VLM</td><td style=\"padding:10px;border:1px solid #555;\">❌</td><td style=\"padding:10px;border:1px solid #555;\">✅✅</td><td style=\"padding:10px;border:1px solid #555;\">Image analysis, OCR</td><td style=\"padding:10px;border:1px solid #555;color:#e5c07b;\">P2</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#e5c07b;\">OpenWebUI LLMs</td><td style=\"padding:10px;border:1px solid #555;\">Local</td><td style=\"padding:10px;border:1px solid #555;\">❌</td><td style=\"padding:10px;border:1px solid #555;\">Varies</td><td style=\"padding:10px;border:1px solid #555;\">Self-hosted, privacy</td><td style=\"padding:10px;border:1px solid #555;color:#e5c07b;\">P2</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#e5c07b;\">OpenWebUI VLMs</td><td style=\"padding:10px;border:1px solid #555;\">Local</td><td style=\"padding:10px;border:1px solid #555;\">❌</td><td style=\"padding:10px;border:1px solid #555;\">✅</td><td style=\"padding:10px;border:1px solid #555;\">Local vision processing</td><td style=\"padding:10px;border:1px solid #555;color:#e5c07b;\">P2</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#c678dd;\">VLLM</td><td style=\"padding:10px;border:1px solid #555;\">Local</td><td style=\"padding:10px;border:1px solid #555;\">❌</td><td style=\"padding:10px;border:1px solid #555;\">Varies</td><td style=\"padding:10px;border:1px solid #555;\">High-throughput local</td><td style=\"padding:10px;border:1px solid #555;color:#c678dd;\">P3</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#c678dd;\">SGLang</td><td style=\"padding:10px;border:1px solid #555;\">Local</td><td style=\"padding:10px;border:1px solid #555;\">❌</td><td style=\"padding:10px;border:1px solid #555;\">Varies</td><td style=\"padding:10px;border:1px solid #555;\">Structured generation</td><td style=\"padding:10px;border:1px solid #555;color:#c678dd;\">P3</td></tr>\n</table>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">3.4 Provider-Specific Implementations</h3>\n\n<h4 style=\"font-family:sans-serif;color:#e5c07b;margin:16px 0 8px 0;\">3.4.1 Claude CLI Provider</h4>\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// ClaudeCLI wraps the claude CLI binary for full tool access</span>\n<span style=\"color:#e5c07b;\">type</span> ClaudeCLIProvider <span style=\"color:#e5c07b;\">struct</span> {\n    binaryPath  <span style=\"color:#e5c07b;\">string</span>          <span style=\"color:#7f848e;\">// Path to claude binary</span>\n    workingDir  <span style=\"color:#e5c07b;\">string</span>          <span style=\"color:#7f848e;\">// Default working directory</span>\n    guardrails  *GuardrailsConfig<span style=\"color:#7f848e;\">// Permission rules</span>\n    sessionID   <span style=\"color:#e5c07b;\">string</span>          <span style=\"color:#7f848e;\">// For --resume</span>\n}\n\n<span style=\"color:#7f848e;\">// Execute runs a full Claude session with tools</span>\n<span style=\"color:#e5c07b;\">func</span> (c *ClaudeCLIProvider) <span style=\"color:#61afef;\">Execute</span>(ctx context.Context, req ExecuteRequest) *ExecuteStream {\n    args := []<span style=\"color:#e5c07b;\">string</span>{\"--output-format\", \"stream-json\"}\n    \n    <span style=\"color:#c678dd;\">if</span> c.sessionID != \"\" {\n        args = <span style=\"color:#61afef;\">append</span>(args, \"--resume\", c.sessionID)\n    }\n    \n    <span style=\"color:#7f848e;\">// Apply guardrails (NOT --dangerously-skip-permissions)</span>\n    <span style=\"color:#c678dd;\">if</span> c.guardrails != nil {\n        args = <span style=\"color:#61afef;\">append</span>(args, c.guardrails.<span style=\"color:#61afef;\">ToArgs</span>()...)\n    }\n    \n    args = <span style=\"color:#61afef;\">append</span>(args, req.Prompt)\n    \n    cmd := exec.<span style=\"color:#61afef;\">CommandContext</span>(ctx, c.binaryPath, args...)\n    <span style=\"color:#7f848e;\">// ... spawn and stream</span>\n}\n</pre>\n\n<h4 style=\"font-family:sans-serif;color:#e5c07b;margin:16px 0 8px 0;\">3.4.2 Claude API Provider</h4>\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// ClaudeAPI for direct API calls (chat, Quick Turn)</span>\n<span style=\"color:#e5c07b;\">type</span> ClaudeAPIProvider <span style=\"color:#e5c07b;\">struct</span> {\n    apiKey       <span style=\"color:#e5c07b;\">string</span>\n    model        <span style=\"color:#e5c07b;\">string</span>\n    cacheEnabled <span style=\"color:#e5c07b;\">bool</span>          <span style=\"color:#7f848e;\">// Prompt caching for cost savings</span>\n}\n\n<span style=\"color:#e5c07b;\">func</span> (c *ClaudeAPIProvider) <span style=\"color:#61afef;\">Chat</span>(ctx context.Context, req ChatRequest) *ChatStream {\n    <span style=\"color:#7f848e;\">// Uses Messages API with streaming</span>\n    <span style=\"color:#7f848e;\">// Applies prompt caching for ~90% cost reduction</span>\n}\n</pre>\n\n<h4 style=\"font-family:sans-serif;color:#e5c07b;margin:16px 0 8px 0;\">3.4.3 OpenAI / Codex CLI Provider</h4>\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// CodexCLI wraps OpenAI's Codex CLI for tool access</span>\n<span style=\"color:#e5c07b;\">type</span> CodexCLIProvider <span style=\"color:#e5c07b;\">struct</span> {\n    binaryPath  <span style=\"color:#e5c07b;\">string</span>          <span style=\"color:#7f848e;\">// Path to codex binary</span>\n    apiKey      <span style=\"color:#e5c07b;\">string</span>          <span style=\"color:#7f848e;\">// OpenAI API key</span>\n    guardrails  *GuardrailsConfig\n}\n\n<span style=\"color:#7f848e;\">// OpenAIAPI for direct GPT API calls</span>\n<span style=\"color:#e5c07b;\">type</span> OpenAIAPIProvider <span style=\"color:#e5c07b;\">struct</span> {\n    apiKey   <span style=\"color:#e5c07b;\">string</span>\n    baseURL  <span style=\"color:#e5c07b;\">string</span>  <span style=\"color:#7f848e;\">// For Azure OpenAI compatibility</span>\n    model    <span style=\"color:#e5c07b;\">string</span>\n}\n</pre>\n\n<h4 style=\"font-family:sans-serif;color:#e5c07b;margin:16px 0 8px 0;\">3.4.4 Local Model Providers (VLLM, SGLang, OpenWebUI)</h4>\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// LocalProvider for self-hosted models</span>\n<span style=\"color:#e5c07b;\">type</span> LocalProvider <span style=\"color:#e5c07b;\">struct</span> {\n    endpoint    <span style=\"color:#e5c07b;\">string</span>    <span style=\"color:#7f848e;\">// http://localhost:8000/v1</span>\n    apiStyle    <span style=\"color:#e5c07b;\">string</span>    <span style=\"color:#7f848e;\">// \"openai\", \"vllm\", \"sglang\"</span>\n    model       <span style=\"color:#e5c07b;\">string</span>    <span style=\"color:#7f848e;\">// Model name/ID</span>\n    gpuMemory   <span style=\"color:#e5c07b;\">int</span>       <span style=\"color:#7f848e;\">// GPU memory available (for batching)</span>\n}\n\n<span style=\"color:#7f848e;\">// Supports OpenAI-compatible API for easy integration</span>\n<span style=\"color:#e5c07b;\">func</span> (p *LocalProvider) <span style=\"color:#61afef;\">Chat</span>(ctx context.Context, req ChatRequest) *ChatStream {\n    <span style=\"color:#7f848e;\">// POST to /v1/chat/completions (OpenAI-compatible)</span>\n}\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">3.5 Provider Selection Logic</h3>\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// Route requests to appropriate provider</span>\n<span style=\"color:#e5c07b;\">func</span> <span style=\"color:#61afef;\">SelectProvider</span>(req Request, available []Provider) Provider {\n    <span style=\"color:#c678dd;\">switch</span> {\n    <span style=\"color:#c678dd;\">case</span> req.RequiresTools:\n        <span style=\"color:#7f848e;\">// Must use CLI provider (Claude or Codex)</span>\n        <span style=\"color:#c678dd;\">return</span> <span style=\"color:#61afef;\">firstWithCapability</span>(available, CapToolUse)\n    <span style=\"color:#c678dd;\">case</span> req.HasImages:\n        <span style=\"color:#7f848e;\">// Need vision capability</span>\n        <span style=\"color:#c678dd;\">return</span> <span style=\"color:#61afef;\">firstWithCapability</span>(available, CapVision)\n    <span style=\"color:#c678dd;\">case</span> req.IsQuickTurn:\n        <span style=\"color:#7f848e;\">// Prefer API for speed, fallback to CLI</span>\n        <span style=\"color:#c678dd;\">return</span> <span style=\"color:#61afef;\">preferAPIProvider</span>(available)\n    <span style=\"color:#c678dd;\">default</span>:\n        <span style=\"color:#c678dd;\">return</span> <span style=\"color:#61afef;\">defaultProvider</span>(available)\n    }\n}\n</pre>\n\n<hr style=\"border:none;border-top:1px solid #444;margin:32px 0;\">\n\n<!-- SECTION 4: TARGET ENVIRONMENTS -->\n<h2 style=\"font-family:sans-serif;color:#fff;margin:32px 0 16px 0;border-bottom:2px solid #98c379;padding-bottom:8px;\">4. Target Development Environments</h2>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">4.1 Platform Support Matrix</h3>\n\n<table style=\"width:100%;border-collapse:collapse;margin:12px 0;\">\n<tr style=\"background:#3d3d3d;\">\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Platform</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Arch</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Priority</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Status</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Notes</th>\n</tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">AWS Linux (AL2023)</td><td style=\"padding:10px;border:1px solid #555;\">x64, ARM64</td><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">P0</td><td style=\"padding:10px;border:1px solid #555;\">Primary target</td><td style=\"padding:10px;border:1px solid #555;\">Production workloads</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">Ubuntu 22.04+</td><td style=\"padding:10px;border:1px solid #555;\">x64, ARM64</td><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">P0</td><td style=\"padding:10px;border:1px solid #555;\">Primary target</td><td style=\"padding:10px;border:1px solid #555;\">Development servers</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#61afef;\">macOS 13+</td><td style=\"padding:10px;border:1px solid #555;\">Intel, Apple Silicon</td><td style=\"padding:10px;border:1px solid #555;color:#61afef;\">P1</td><td style=\"padding:10px;border:1px solid #555;\">Planned</td><td style=\"padding:10px;border:1px solid #555;\">Developer workstations</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#61afef;\">RHEL/CentOS 9+</td><td style=\"padding:10px;border:1px solid #555;\">x64</td><td style=\"padding:10px;border:1px solid #555;color:#61afef;\">P1</td><td style=\"padding:10px;border:1px solid #555;\">Planned</td><td style=\"padding:10px;border:1px solid #555;\">Enterprise Linux</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#e5c07b;\">Windows 10/11</td><td style=\"padding:10px;border:1px solid #555;\">x64</td><td style=\"padding:10px;border:1px solid #555;color:#e5c07b;\">P2</td><td style=\"padding:10px;border:1px solid #555;\">Planned</td><td style=\"padding:10px;border:1px solid #555;\">Native Windows dev</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#c678dd;\">Android Studio</td><td style=\"padding:10px;border:1px solid #555;\">Via plugin</td><td style=\"padding:10px;border:1px solid #555;color:#c678dd;\">P3</td><td style=\"padding:10px;border:1px solid #555;\">Future</td><td style=\"padding:10px;border:1px solid #555;\">Mobile development</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#c678dd;\">Xcode iOS</td><td style=\"padding:10px;border:1px solid #555;\">Via plugin</td><td style=\"padding:10px;border:1px solid #555;color:#c678dd;\">P3</td><td style=\"padding:10px;border:1px solid #555;\">Future</td><td style=\"padding:10px;border:1px solid #555;\">iOS development</td></tr>\n</table>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">4.2 Platform-Specific Considerations</h3>\n\n<h4 style=\"font-family:sans-serif;color:#e5c07b;margin:16px 0 8px 0;\">AWS Linux / Ubuntu</h4>\n<ul style=\"color:#e0e0e0;line-height:2;\">\n<li><strong>Binary:</strong> <code>gvagent-linux-amd64</code>, <code>gvagent-linux-arm64</code></li>\n<li><strong>Installation:</strong> <code>curl -fsSL https://install.greatvibe.ai | sh</code></li>\n<li><strong>Service:</strong> systemd unit file for daemon mode</li>\n<li><strong>Data dir:</strong> <code>/var/lib/gvagent/</code> or <code>~/.gvagent/</code></li>\n<li><strong>Claude CLI:</strong> Auto-detect or configure path</li>\n</ul>\n\n<h4 style=\"font-family:sans-serif;color:#e5c07b;margin:16px 0 8px 0;\">macOS</h4>\n<ul style=\"color:#e0e0e0;line-height:2;\">\n<li><strong>Binary:</strong> <code>gvagent-darwin-amd64</code>, <code>gvagent-darwin-arm64</code></li>\n<li><strong>Installation:</strong> Homebrew tap or direct download</li>\n<li><strong>Service:</strong> launchd plist for daemon mode</li>\n<li><strong>Data dir:</strong> <code>~/Library/Application Support/gvagent/</code></li>\n<li><strong>Code signing:</strong> Required for Gatekeeper</li>\n</ul>\n\n<h4 style=\"font-family:sans-serif;color:#e5c07b;margin:16px 0 8px 0;\">Windows</h4>\n<ul style=\"color:#e0e0e0;line-height:2;\">\n<li><strong>Binary:</strong> <code>gvagent-windows-amd64.exe</code></li>\n<li><strong>Installation:</strong> MSI installer or scoop/winget</li>\n<li><strong>Service:</strong> Windows Service (NSSM or native)</li>\n<li><strong>Data dir:</strong> <code>%APPDATA%\\gvagent\\</code></li>\n<li><strong>Shell:</strong> PowerShell adapter for Bash tools</li>\n</ul>\n\n<h4 style=\"font-family:sans-serif;color:#e5c07b;margin:16px 0 8px 0;\">IDE Integration (Android Studio, Xcode)</h4>\n<ul style=\"color:#e0e0e0;line-height:2;\">\n<li><strong>Architecture:</strong> Agent runs as external process, IDE plugin communicates via localhost API</li>\n<li><strong>Protocol:</strong> Same WebSocket/REST API as browser clients</li>\n<li><strong>Features:</strong> Context injection (current file, selection), tool results inline</li>\n</ul>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">4.3 Build Matrix</h3>\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\"># Cross-compile targets in Makefile</span>\n<span style=\"color:#e5c07b;\">PLATFORMS</span> := \\\n    linux/amd64 \\\n    linux/arm64 \\\n    darwin/amd64 \\\n    darwin/arm64 \\\n    windows/amd64\n\n<span style=\"color:#7f848e;\"># Build all platforms</span>\n$ make release\n\n<span style=\"color:#7f848e;\"># Output:</span>\n<span style=\"color:#98c379;\">dist/</span>\n├── gvagent-linux-amd64\n├── gvagent-linux-arm64\n├── gvagent-darwin-amd64\n├── gvagent-darwin-arm64\n└── gvagent-windows-amd64.exe\n</pre>\n\n<hr style=\"border:none;border-top:1px solid #444;margin:32px 0;\">\n\n<!-- SECTION 5: PERMISSIONS & GUARDRAILS -->\n<h2 style=\"font-family:sans-serif;color:#fff;margin:32px 0 16px 0;border-bottom:2px solid #98c379;padding-bottom:8px;\">5. Permissions & Guardrails System</h2>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">5.1 The Problem with Current Approach</h3>\n<div style=\"background:#4a3030;padding:16px;border-radius:6px;margin-bottom:16px;border-left:4px solid #e06c75;\">\n<p style=\"color:#e5c07b;margin:0 0 8px 0;font-weight:bold;\">⚠️ Current konsole/konui uses --dangerously-skip-permissions</p>\n<p style=\"color:#e0e0e0;margin:0;\">This grants Claude <strong>unrestricted</strong> access to the file system, shell, and network. In a multi-user or production environment, this is unacceptable. The agent needs fine-grained, declarative permission controls.</p>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">5.2 Guardrails Architecture</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n┌─────────────────────────────────────────────────────────────────┐\n│                    GUARDRAILS ENGINE                            │\n│                                                                 │\n│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐           │\n│  │ <span style=\"color:#98c379;\">Path Rules</span>  │   │ <span style=\"color:#61afef;\">Cmd Rules</span>   │   │ <span style=\"color:#e5c07b;\">Net Rules</span>   │           │\n│  │             │   │             │   │             │           │\n│  │ allow: []   │   │ allow: []   │   │ allow: []   │           │\n│  │ deny: []    │   │ deny: []    │   │ deny: []    │           │\n│  │ readonly: []│   │ require: [] │   │ block: []   │           │\n│  └──────┬──────┘   └──────┬──────┘   └──────┬──────┘           │\n│         │                 │                 │                  │\n│         └────────────────┬┴─────────────────┘                  │\n│                          │                                     │\n│                   ┌──────┴──────┐                              │\n│                   │  Evaluator  │                              │\n│                   └──────┬──────┘                              │\n│                          │                                     │\n│              <span style=\"color:#98c379;\">ALLOW</span> / <span style=\"color:#e06c75;\">DENY</span> / <span style=\"color:#e5c07b;\">PROMPT</span>                           │\n└──────────────────────────┼──────────────────────────────────────┘\n                           │\n                           ▼\n                    Tool Execution\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">5.3 Guardrails Configuration</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// guardrails.yaml</span>\n<span style=\"color:#e5c07b;\">version</span>: <span style=\"color:#98c379;\">\"1.0\"</span>\n<span style=\"color:#e5c07b;\">name</span>: <span style=\"color:#98c379;\">\"production-agent\"</span>\n\n<span style=\"color:#e5c07b;\">filesystem</span>:\n  <span style=\"color:#7f848e;\"># Allowed read/write paths (glob patterns)</span>\n  <span style=\"color:#61afef;\">allow</span>:\n    - <span style=\"color:#98c379;\">\"/konnectvol/**\"</span>           <span style=\"color:#7f848e;\"># Project directory</span>\n    - <span style=\"color:#98c379;\">\"/tmp/gvagent-*\"</span>          <span style=\"color:#7f848e;\"># Temp files</span>\n  \n  <span style=\"color:#7f848e;\"># Explicitly denied paths</span>\n  <span style=\"color:#e06c75;\">deny</span>:\n    - <span style=\"color:#98c379;\">\"/etc/passwd\"</span>\n    - <span style=\"color:#98c379;\">\"/etc/shadow\"</span>\n    - <span style=\"color:#98c379;\">\"**/.env\"</span>                 <span style=\"color:#7f848e;\"># Never read/write .env files</span>\n    - <span style=\"color:#98c379;\">\"**/secrets/**\"</span>\n    - <span style=\"color:#98c379;\">\"**/*.pem\"</span>\n    - <span style=\"color:#98c379;\">\"**/*.key\"</span>\n  \n  <span style=\"color:#7f848e;\"># Read-only paths</span>\n  <span style=\"color:#e5c07b;\">readonly</span>:\n    - <span style=\"color:#98c379;\">\"/usr/**\"</span>\n    - <span style=\"color:#98c379;\">\"/bin/**\"</span>\n\n<span style=\"color:#e5c07b;\">commands</span>:\n  <span style=\"color:#7f848e;\"># Allowed commands (with optional args patterns)</span>\n  <span style=\"color:#61afef;\">allow</span>:\n    - <span style=\"color:#98c379;\">\"git:*\"</span>                   <span style=\"color:#7f848e;\"># All git commands</span>\n    - <span style=\"color:#98c379;\">\"deno:*\"</span>\n    - <span style=\"color:#98c379;\">\"npm:*\"</span>\n    - <span style=\"color:#98c379;\">\"curl:*\"</span>\n    - <span style=\"color:#98c379;\">\"ls:*\"</span>\n    - <span style=\"color:#98c379;\">\"cat:*\"</span>\n    - <span style=\"color:#98c379;\">\"head:*\"</span>\n    - <span style=\"color:#98c379;\">\"tail:*\"</span>\n  \n  <span style=\"color:#7f848e;\"># Denied commands (never execute)</span>\n  <span style=\"color:#e06c75;\">deny</span>:\n    - <span style=\"color:#98c379;\">\"rm:-rf /*\"</span>              <span style=\"color:#7f848e;\"># Prevent catastrophic deletes</span>\n    - <span style=\"color:#98c379;\">\"sudo:*\"</span>                  <span style=\"color:#7f848e;\"># No sudo</span>\n    - <span style=\"color:#98c379;\">\"chmod:777 *\"</span>\n    - <span style=\"color:#98c379;\">\"curl:* | sh\"</span>            <span style=\"color:#7f848e;\"># No pipe to shell</span>\n  \n  <span style=\"color:#7f848e;\"># Commands requiring confirmation</span>\n  <span style=\"color:#e5c07b;\">require_confirmation</span>:\n    - <span style=\"color:#98c379;\">\"git:push *\"</span>\n    - <span style=\"color:#98c379;\">\"git:reset --hard *\"</span>\n    - <span style=\"color:#98c379;\">\"rm:-r *\"</span>\n\n<span style=\"color:#e5c07b;\">network</span>:\n  <span style=\"color:#7f848e;\"># Allowed outbound connections</span>\n  <span style=\"color:#61afef;\">allow</span>:\n    - <span style=\"color:#98c379;\">\"api.anthropic.com:443\"</span>\n    - <span style=\"color:#98c379;\">\"api.openai.com:443\"</span>\n    - <span style=\"color:#98c379;\">\"*.webflow.com:443\"</span>\n    - <span style=\"color:#98c379;\">\"github.com:443\"</span>\n  \n  <span style=\"color:#7f848e;\"># Blocked destinations</span>\n  <span style=\"color:#e06c75;\">deny</span>:\n    - <span style=\"color:#98c379;\">\"169.254.169.254:*\"</span>      <span style=\"color:#7f848e;\"># AWS metadata service</span>\n    - <span style=\"color:#98c379;\">\"localhost:22\"</span>            <span style=\"color:#7f848e;\"># No SSH tunneling</span>\n\n<span style=\"color:#e5c07b;\">limits</span>:\n  <span style=\"color:#61afef;\">max_file_size_mb</span>: <span style=\"color:#d19a66;\">10</span>          <span style=\"color:#7f848e;\"># Max file write size</span>\n  <span style=\"color:#61afef;\">max_command_duration_s</span>: <span style=\"color:#d19a66;\">300</span>  <span style=\"color:#7f848e;\"># 5 minute timeout</span>\n  <span style=\"color:#61afef;\">max_concurrent_tools</span>: <span style=\"color:#d19a66;\">5</span>\n  <span style=\"color:#61afef;\">max_tool_calls_per_turn</span>: <span style=\"color:#d19a66;\">100</span>\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">5.4 Permission Evaluation Flow</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#e5c07b;\">func</span> (g *Guardrails) <span style=\"color:#61afef;\">Evaluate</span>(tool ToolCall) (Decision, <span style=\"color:#e5c07b;\">error</span>) {\n    <span style=\"color:#7f848e;\">// 1. Check explicit deny rules (highest priority)</span>\n    <span style=\"color:#c678dd;\">if</span> g.<span style=\"color:#61afef;\">matchesDenyRule</span>(tool) {\n        <span style=\"color:#c678dd;\">return</span> DecisionDeny, ErrForbiddenByPolicy\n    }\n    \n    <span style=\"color:#7f848e;\">// 2. Check explicit allow rules</span>\n    <span style=\"color:#c678dd;\">if</span> g.<span style=\"color:#61afef;\">matchesAllowRule</span>(tool) {\n        <span style=\"color:#7f848e;\">// 3. Check if requires confirmation</span>\n        <span style=\"color:#c678dd;\">if</span> g.<span style=\"color:#61afef;\">requiresConfirmation</span>(tool) {\n            <span style=\"color:#c678dd;\">return</span> DecisionPrompt, <span style=\"color:#d19a66;\">nil</span>\n        }\n        <span style=\"color:#c678dd;\">return</span> DecisionAllow, <span style=\"color:#d19a66;\">nil</span>\n    }\n    \n    <span style=\"color:#7f848e;\">// 4. Default deny (fail-safe)</span>\n    <span style=\"color:#c678dd;\">return</span> DecisionDeny, ErrNotExplicitlyAllowed\n}\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">5.5 Provider-Specific Guardrails</h3>\n\n<table style=\"width:100%;border-collapse:collapse;margin:12px 0;\">\n<tr style=\"background:#3d3d3d;\">\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Provider</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Guardrail Mechanism</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Notes</th>\n</tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">Claude CLI</td><td style=\"padding:10px;border:1px solid #555;\">--allowedTools, --disallowedTools, hooks</td><td style=\"padding:10px;border:1px solid #555;\">Native permission system</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">Codex CLI</td><td style=\"padding:10px;border:1px solid #555;\">--approval-mode, sandbox config</td><td style=\"padding:10px;border:1px solid #555;\">Similar to Claude</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#61afef;\">API Providers</td><td style=\"padding:10px;border:1px solid #555;\">Agent-side enforcement</td><td style=\"padding:10px;border:1px solid #555;\">No native tools, guardrails prevent injection</td></tr>\n</table>\n\n<hr style=\"border:none;border-top:1px solid #444;margin:32px 0;\">\n\n<!-- SECTION 6: AAA -->\n<h2 style=\"font-family:sans-serif;color:#fff;margin:32px 0 16px 0;border-bottom:2px solid #98c379;padding-bottom:8px;\">6. Authentication, Authorization & Accounting (AAA)</h2>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">6.1 Two Deployment Models</h3>\n\n<table style=\"width:100%;border-collapse:collapse;margin:12px 0;\">\n<tr style=\"background:#3d3d3d;\">\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Aspect</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">greatVibe.local</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">greatVibe.ai (Cloud)</th>\n</tr>\n<tr><td style=\"padding:10px;border:1px solid #555;font-weight:bold;\">Users</td><td style=\"padding:10px;border:1px solid #555;\">Single user / small team</td><td style=\"padding:10px;border:1px solid #555;\">Multi-tenant organizations</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;font-weight:bold;\">Authentication</td><td style=\"padding:10px;border:1px solid #555;\">Local passwords, API keys</td><td style=\"padding:10px;border:1px solid #555;\">SSO (SAML, OIDC), MFA</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;font-weight:bold;\">Authorization</td><td style=\"padding:10px;border:1px solid #555;\">Role-based (admin/user)</td><td style=\"padding:10px;border:1px solid #555;\">RBAC + ABAC, org policies</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;font-weight:bold;\">Accounting</td><td style=\"padding:10px;border:1px solid #555;\">Local logs, token tracking</td><td style=\"padding:10px;border:1px solid #555;\">Full audit trail, billing integration</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;font-weight:bold;\">Credentials</td><td style=\"padding:10px;border:1px solid #555;\">Local keychain/file</td><td style=\"padding:10px;border:1px solid #555;\">Vault integration</td></tr>\n</table>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">6.2 greatVibe.local Authentication</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// Local authentication flow</span>\n┌─────────────┐     API Key      ┌─────────────┐\n│   Browser   │ ────────────────►│   Hub       │\n│   (konui)   │                  │   (local)   │\n└─────────────┘                  └──────┬──────┘\n                                        │\n                     Session Token      │\n                     (JWT, 24h TTL)     │\n                                        ▼\n                                 ┌─────────────┐\n                                 │   Agent     │\n                                 │             │\n                                 │ validates   │\n                                 │ hub-signed  │\n                                 │ tokens      │\n                                 └─────────────┘\n</pre>\n\n<h4 style=\"font-family:sans-serif;color:#e5c07b;margin:16px 0 8px 0;\">Authentication Methods (Local)</h4>\n<ol style=\"color:#e0e0e0;line-height:2;\">\n<li><strong>Password + Session:</strong> User logs in with password, gets JWT</li>\n<li><strong>API Key:</strong> Long-lived key for automation/scripts</li>\n<li><strong>Agent Token:</strong> Agent presents token from hub to execute</li>\n</ol>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">6.3 greatVibe.ai Authentication</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// Cloud authentication flow</span>\n┌─────────────┐     OIDC/SAML    ┌─────────────┐\n│   Browser   │ ────────────────►│   IdP       │\n│             │                  │ (Okta/Auth0)│\n└──────┬──────┘                  └──────┬──────┘\n       │                                │\n       │  ID Token                      │\n       ▼                                │\n┌─────────────┐                         │\n│   Hub       │◄────────────────────────┘\n│   (cloud)   │   Verified Identity\n└──────┬──────┘\n       │ Organization Scope\n       │ + Role Assignment\n       ▼\n┌─────────────┐\n│   Agent     │  Hub-signed session token\n└─────────────┘  with org_id, user_id, roles\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">6.4 Authorization Model</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#e5c07b;\">type</span> Role <span style=\"color:#e5c07b;\">string</span>\n<span style=\"color:#e5c07b;\">const</span> (\n    RoleAdmin   Role = <span style=\"color:#98c379;\">\"admin\"</span>   <span style=\"color:#7f848e;\">// Full access, manage users/agents</span>\n    RoleDev     Role = <span style=\"color:#98c379;\">\"dev\"</span>     <span style=\"color:#7f848e;\">// Create/execute flows, sessions</span>\n    RoleViewer  Role = <span style=\"color:#98c379;\">\"viewer\"</span>  <span style=\"color:#7f848e;\">// Read-only access</span>\n    RoleAgent   Role = <span style=\"color:#98c379;\">\"agent\"</span>   <span style=\"color:#7f848e;\">// Machine identity for agents</span>\n)\n\n<span style=\"color:#e5c07b;\">type</span> Permission <span style=\"color:#e5c07b;\">string</span>\n<span style=\"color:#e5c07b;\">const</span> (\n    PermSessionCreate   Permission = <span style=\"color:#98c379;\">\"session:create\"</span>\n    PermSessionRead     Permission = <span style=\"color:#98c379;\">\"session:read\"</span>\n    PermSessionExecute  Permission = <span style=\"color:#98c379;\">\"session:execute\"</span>\n    PermFlowCreate      Permission = <span style=\"color:#98c379;\">\"flow:create\"</span>\n    PermFlowApprove     Permission = <span style=\"color:#98c379;\">\"flow:approve\"</span>\n    PermAgentRegister   Permission = <span style=\"color:#98c379;\">\"agent:register\"</span>\n    PermAdminUsers      Permission = <span style=\"color:#98c379;\">\"admin:users\"</span>\n    PermAdminConfig     Permission = <span style=\"color:#98c379;\">\"admin:config\"</span>\n)\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">6.5 Accounting & Audit Trail</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// Audit log entry (append-only JSONL)</span>\n<span style=\"color:#e5c07b;\">type</span> AuditEntry <span style=\"color:#e5c07b;\">struct</span> {\n    Timestamp   time.Time       <span style=\"color:#98c379;\">`json:\"ts\"`</span>\n    EventID     <span style=\"color:#e5c07b;\">string</span>          <span style=\"color:#98c379;\">`json:\"event_id\"`</span>\n    Actor       <span style=\"color:#e5c07b;\">string</span>          <span style=\"color:#98c379;\">`json:\"actor\"`</span>      <span style=\"color:#7f848e;\">// user_id or agent_id</span>\n    ActorType   <span style=\"color:#e5c07b;\">string</span>          <span style=\"color:#98c379;\">`json:\"actor_type\"`</span> <span style=\"color:#7f848e;\">// \"user\", \"agent\", \"system\"</span>\n    Action      <span style=\"color:#e5c07b;\">string</span>          <span style=\"color:#98c379;\">`json:\"action\"`</span>\n    Resource    <span style=\"color:#e5c07b;\">string</span>          <span style=\"color:#98c379;\">`json:\"resource\"`</span>\n    ResourceID  <span style=\"color:#e5c07b;\">string</span>          <span style=\"color:#98c379;\">`json:\"resource_id\"`</span>\n    Result      <span style=\"color:#e5c07b;\">string</span>          <span style=\"color:#98c379;\">`json:\"result\"`</span>     <span style=\"color:#7f848e;\">// \"success\", \"denied\", \"error\"</span>\n    Details     json.RawMessage <span style=\"color:#98c379;\">`json:\"details\"`</span>\n    IPAddress   <span style=\"color:#e5c07b;\">string</span>          <span style=\"color:#98c379;\">`json:\"ip\"`</span>\n    UserAgent   <span style=\"color:#e5c07b;\">string</span>          <span style=\"color:#98c379;\">`json:\"ua\"`</span>\n}\n\n<span style=\"color:#7f848e;\">// Token usage tracking</span>\n<span style=\"color:#e5c07b;\">type</span> UsageRecord <span style=\"color:#e5c07b;\">struct</span> {\n    TurnID        <span style=\"color:#e5c07b;\">string</span>  <span style=\"color:#98c379;\">`json:\"turn_id\"`</span>\n    SessionID     <span style=\"color:#e5c07b;\">string</span>  <span style=\"color:#98c379;\">`json:\"session_id\"`</span>\n    Provider      <span style=\"color:#e5c07b;\">string</span>  <span style=\"color:#98c379;\">`json:\"provider\"`</span>\n    Model         <span style=\"color:#e5c07b;\">string</span>  <span style=\"color:#98c379;\">`json:\"model\"`</span>\n    InputTokens   <span style=\"color:#e5c07b;\">int64</span>   <span style=\"color:#98c379;\">`json:\"input_tokens\"`</span>\n    OutputTokens  <span style=\"color:#e5c07b;\">int64</span>   <span style=\"color:#98c379;\">`json:\"output_tokens\"`</span>\n    CacheRead     <span style=\"color:#e5c07b;\">int64</span>   <span style=\"color:#98c379;\">`json:\"cache_read\"`</span>\n    CacheWrite    <span style=\"color:#e5c07b;\">int64</span>   <span style=\"color:#98c379;\">`json:\"cache_write\"`</span>\n    CostUSD       <span style=\"color:#e5c07b;\">float64</span> <span style=\"color:#98c379;\">`json:\"cost_usd\"`</span>\n    DurationMs    <span style=\"color:#e5c07b;\">int64</span>   <span style=\"color:#98c379;\">`json:\"duration_ms\"`</span>\n}\n</pre>\n\n<hr style=\"border:none;border-top:1px solid #444;margin:32px 0;\">\n\n<!-- SECTION 7: CONFIGURATION MANAGEMENT -->\n<h2 style=\"font-family:sans-serif;color:#fff;margin:32px 0 16px 0;border-bottom:2px solid #98c379;padding-bottom:8px;\">7. Configuration Management</h2>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">7.1 Configuration Sources (Priority Order)</h3>\n\n<ol style=\"color:#e0e0e0;line-height:2;\">\n<li><strong>Environment Variables</strong> (highest priority) — for container/cloud deployments</li>\n<li><strong>Local Config File</strong> — <code>gvagent.yaml</code> in data directory</li>\n<li><strong>Hub-Pushed Config</strong> — central management via hub</li>\n<li><strong>Built-in Defaults</strong> (lowest priority)</li>\n</ol>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">7.2 Static Configuration File</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\"># ~/.gvagent/gvagent.yaml</span>\n\n<span style=\"color:#e5c07b;\">agent</span>:\n  <span style=\"color:#61afef;\">id</span>: <span style=\"color:#98c379;\">\"agent-prod-01\"</span>           <span style=\"color:#7f848e;\"># Unique agent identifier</span>\n  <span style=\"color:#61afef;\">name</span>: <span style=\"color:#98c379;\">\"Production Agent 1\"</span>    <span style=\"color:#7f848e;\"># Display name</span>\n  <span style=\"color:#61afef;\">tags</span>:\n    - <span style=\"color:#98c379;\">\"production\"</span>\n    - <span style=\"color:#98c379;\">\"linux\"</span>\n    - <span style=\"color:#98c379;\">\"us-west-2\"</span>\n\n<span style=\"color:#e5c07b;\">hub</span>:\n  <span style=\"color:#61afef;\">url</span>: <span style=\"color:#98c379;\">\"wss://greatvibe.ai/agent\"</span>\n  <span style=\"color:#61afef;\">token_file</span>: <span style=\"color:#98c379;\">\"~/.gvagent/hub-token\"</span>\n  <span style=\"color:#61afef;\">reconnect_delay_ms</span>: <span style=\"color:#d19a66;\">5000</span>\n  <span style=\"color:#61afef;\">max_reconnect_attempts</span>: <span style=\"color:#d19a66;\">-1</span>   <span style=\"color:#7f848e;\"># Infinite</span>\n\n<span style=\"color:#e5c07b;\">providers</span>:\n  <span style=\"color:#61afef;\">default</span>: <span style=\"color:#98c379;\">\"claude-cli\"</span>\n  \n  <span style=\"color:#61afef;\">claude-cli</span>:\n    <span style=\"color:#e5c07b;\">enabled</span>: <span style=\"color:#d19a66;\">true</span>\n    <span style=\"color:#e5c07b;\">binary_path</span>: <span style=\"color:#98c379;\">\"/usr/local/bin/claude\"</span>\n    <span style=\"color:#e5c07b;\">guardrails_file</span>: <span style=\"color:#98c379;\">\"~/.gvagent/guardrails.yaml\"</span>\n  \n  <span style=\"color:#61afef;\">claude-api</span>:\n    <span style=\"color:#e5c07b;\">enabled</span>: <span style=\"color:#d19a66;\">true</span>\n    <span style=\"color:#e5c07b;\">api_key_env</span>: <span style=\"color:#98c379;\">\"ANTHROPIC_API_KEY\"</span>\n    <span style=\"color:#e5c07b;\">model</span>: <span style=\"color:#98c379;\">\"claude-sonnet-4-20250514\"</span>\n    <span style=\"color:#e5c07b;\">prompt_cache_enabled</span>: <span style=\"color:#d19a66;\">true</span>\n  \n  <span style=\"color:#61afef;\">openai-api</span>:\n    <span style=\"color:#e5c07b;\">enabled</span>: <span style=\"color:#d19a66;\">false</span>\n    <span style=\"color:#e5c07b;\">api_key_env</span>: <span style=\"color:#98c379;\">\"OPENAI_API_KEY\"</span>\n    <span style=\"color:#e5c07b;\">model</span>: <span style=\"color:#98c379;\">\"gpt-4o\"</span>\n\n<span style=\"color:#e5c07b;\">storage</span>:\n  <span style=\"color:#61afef;\">data_dir</span>: <span style=\"color:#98c379;\">\"~/.gvagent/data\"</span>\n  <span style=\"color:#61afef;\">session_db</span>: <span style=\"color:#98c379;\">\"sessions.db\"</span>\n  <span style=\"color:#61afef;\">event_journal_dir</span>: <span style=\"color:#98c379;\">\"events/\"</span>\n  <span style=\"color:#61afef;\">max_journal_size_mb</span>: <span style=\"color:#d19a66;\">100</span>\n\n<span style=\"color:#e5c07b;\">logging</span>:\n  <span style=\"color:#61afef;\">level</span>: <span style=\"color:#98c379;\">\"info\"</span>\n  <span style=\"color:#61afef;\">format</span>: <span style=\"color:#98c379;\">\"json\"</span>\n  <span style=\"color:#61afef;\">output</span>: <span style=\"color:#98c379;\">\"~/.gvagent/logs/agent.log\"</span>\n  <span style=\"color:#61afef;\">rotate_size_mb</span>: <span style=\"color:#d19a66;\">50</span>\n  <span style=\"color:#61afef;\">retain_days</span>: <span style=\"color:#d19a66;\">30</span>\n\n<span style=\"color:#e5c07b;\">limits</span>:\n  <span style=\"color:#61afef;\">max_turn_duration_ms</span>: <span style=\"color:#d19a66;\">900000</span>  <span style=\"color:#7f848e;\"># 15 minutes</span>\n  <span style=\"color:#61afef;\">max_tool_calls_per_turn</span>: <span style=\"color:#d19a66;\">200</span>\n  <span style=\"color:#61afef;\">idle_timeout_ms</span>: <span style=\"color:#d19a66;\">600000</span>       <span style=\"color:#7f848e;\"># 10 minutes</span>\n  <span style=\"color:#61afef;\">max_concurrent_sessions</span>: <span style=\"color:#d19a66;\">5</span>\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">7.3 Hub Push/Pull Configuration</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// Hub → Agent config push (WebSocket message)</span>\n{\n  <span style=\"color:#98c379;\">\"type\"</span>: <span style=\"color:#98c379;\">\"config_update\"</span>,\n  <span style=\"color:#98c379;\">\"version\"</span>: <span style=\"color:#d19a66;\">42</span>,\n  <span style=\"color:#98c379;\">\"config\"</span>: {\n    <span style=\"color:#98c379;\">\"guardrails\"</span>: { ... },\n    <span style=\"color:#98c379;\">\"providers\"</span>: { ... },\n    <span style=\"color:#98c379;\">\"limits\"</span>: { ... }\n  },\n  <span style=\"color:#98c379;\">\"signature\"</span>: <span style=\"color:#98c379;\">\"hub-signed-hash\"</span>\n}\n\n<span style=\"color:#7f848e;\">// Agent → Hub config request</span>\n{\n  <span style=\"color:#98c379;\">\"type\"</span>: <span style=\"color:#98c379;\">\"config_request\"</span>,\n  <span style=\"color:#98c379;\">\"current_version\"</span>: <span style=\"color:#d19a66;\">41</span>\n}\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">7.4 Configuration Validation</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#e5c07b;\">func</span> <span style=\"color:#61afef;\">ValidateConfig</span>(cfg *Config) <span style=\"color:#e5c07b;\">error</span> {\n    <span style=\"color:#7f848e;\">// Required fields</span>\n    <span style=\"color:#c678dd;\">if</span> cfg.Agent.ID == \"\" {\n        <span style=\"color:#c678dd;\">return</span> errors.<span style=\"color:#61afef;\">New</span>(<span style=\"color:#98c379;\">\"agent.id is required\"</span>)\n    }\n    <span style=\"color:#c678dd;\">if</span> cfg.Hub.URL == \"\" {\n        <span style=\"color:#c678dd;\">return</span> errors.<span style=\"color:#61afef;\">New</span>(<span style=\"color:#98c379;\">\"hub.url is required\"</span>)\n    }\n    \n    <span style=\"color:#7f848e;\">// At least one provider must be enabled</span>\n    <span style=\"color:#c678dd;\">if</span> !<span style=\"color:#61afef;\">anyProviderEnabled</span>(cfg.Providers) {\n        <span style=\"color:#c678dd;\">return</span> errors.<span style=\"color:#61afef;\">New</span>(<span style=\"color:#98c379;\">\"at least one provider must be enabled\"</span>)\n    }\n    \n    <span style=\"color:#7f848e;\">// Validate paths exist</span>\n    <span style=\"color:#c678dd;\">if</span> cfg.Providers.ClaudeCLI.Enabled {\n        <span style=\"color:#c678dd;\">if</span> _, err := os.<span style=\"color:#61afef;\">Stat</span>(cfg.Providers.ClaudeCLI.BinaryPath); err != <span style=\"color:#d19a66;\">nil</span> {\n            <span style=\"color:#c678dd;\">return</span> fmt.<span style=\"color:#61afef;\">Errorf</span>(<span style=\"color:#98c379;\">\"claude binary not found: %s\"</span>, cfg.Providers.ClaudeCLI.BinaryPath)\n        }\n    }\n    \n    <span style=\"color:#c678dd;\">return</span> <span style=\"color:#d19a66;\">nil</span>\n}\n</pre>\n\n<hr style=\"border:none;border-top:1px solid #444;margin:32px 0;\">\n\n<!-- SECTION 8: NETWORKING -->\n<h2 style=\"font-family:sans-serif;color:#fff;margin:32px 0 16px 0;border-bottom:2px solid #98c379;padding-bottom:8px;\">8. Networking Architecture</h2>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">8.1 Network Topology</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n┌──────────────────────────────────────────────────────────────────────────┐\n│                           <span style=\"color:#98c379;\">INTERNET</span>                                      │\n└───────────────────────────────┬──────────────────────────────────────────┘\n                                │\n                   ┌────────────┴────────────┐\n                   │   <span style=\"color:#61afef;\">CloudFlare DNS</span>        │\n                   │   greatvibe.ai → ALB    │\n                   │   *.greatvibe.ai → ALB  │\n                   └────────────┬────────────┘\n                                │\n┌───────────────────────────────┴───────────────────────────────────────────┐\n│                           <span style=\"color:#e5c07b;\">AWS VPC</span>                                        │\n│                                                                           │\n│   ┌────────────────────────────────────────────────────────────────┐      │\n│   │                    <span style=\"color:#98c379;\">Application Load Balancer</span>                   │      │\n│   │                                                                │      │\n│   │   HTTPS :443 ──► Target Group (Hub EC2 instances)              │      │\n│   │   WSS   :443 ──► Target Group (Agent WebSocket)                │      │\n│   │                                                                │      │\n│   └────────────────────────────────┬───────────────────────────────┘      │\n│                                    │                                      │\n│              ┌─────────────────────┼─────────────────────┐                │\n│              │                     │                     │                │\n│              ▼                     ▼                     ▼                │\n│     ┌─────────────┐       ┌─────────────┐       ┌─────────────┐           │\n│     │  <span style=\"color:#61afef;\">Hub EC2 1</span>  │       │  <span style=\"color:#61afef;\">Hub EC2 2</span>  │       │  <span style=\"color:#61afef;\">Hub EC2 3</span>  │           │\n│     │  (primary)  │◄─────►│  (replica)  │◄─────►│  (replica)  │           │\n│     └──────┬──────┘       └─────────────┘       └─────────────┘           │\n│            │                                                              │\n│            │  RDS PostgreSQL (state sync)                                 │\n│            │  ElastiCache Redis (pub/sub, sessions)                       │\n│            ▼                                                              │\n│     ┌─────────────────────────────────────────────────────────────┐       │\n│     │                    <span style=\"color:#c678dd;\">RDS / ElastiCache</span>                       │       │\n│     └─────────────────────────────────────────────────────────────┘       │\n│                                                                           │\n└───────────────────────────────────────────────────────────────────────────┘\n                                │\n       ┌────────────────────────┼────────────────────────┐\n       │                        │                        │\n       ▼                        ▼                        ▼\n┌─────────────┐          ┌─────────────┐          ┌─────────────┐\n│  <span style=\"color:#98c379;\">gvAgent</span>    │          │  <span style=\"color:#98c379;\">gvAgent</span>    │          │  <span style=\"color:#98c379;\">gvAgent</span>    │\n│  (on-prem)  │          │  (AWS EC2)  │          │  (macOS)    │\n│             │          │             │          │             │\n│  WSS ──────►│──────────│─────────────│──────────│◄─── WSS     │\n└─────────────┘          └─────────────┘          └─────────────┘\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">8.2 DNS Configuration</h3>\n\n<table style=\"width:100%;border-collapse:collapse;margin:12px 0;\">\n<tr style=\"background:#3d3d3d;\">\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Domain</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Type</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Target</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Purpose</th>\n</tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">greatvibe.ai</td><td style=\"padding:10px;border:1px solid #555;\">A/AAAA</td><td style=\"padding:10px;border:1px solid #555;\">CloudFlare proxy → ALB</td><td style=\"padding:10px;border:1px solid #555;\">Main hub UI</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">api.greatvibe.ai</td><td style=\"padding:10px;border:1px solid #555;\">A/AAAA</td><td style=\"padding:10px;border:1px solid #555;\">CloudFlare proxy → ALB</td><td style=\"padding:10px;border:1px solid #555;\">REST API</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">ws.greatvibe.ai</td><td style=\"padding:10px;border:1px solid #555;\">A/AAAA</td><td style=\"padding:10px;border:1px solid #555;\">Direct to ALB (no proxy)</td><td style=\"padding:10px;border:1px solid #555;\">Agent WebSocket</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">*.greatvibe.ai</td><td style=\"padding:10px;border:1px solid #555;\">CNAME</td><td style=\"padding:10px;border:1px solid #555;\">greatvibe.ai</td><td style=\"padding:10px;border:1px solid #555;\">Subdomains</td></tr>\n</table>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">8.3 WebSocket Protocol</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// Agent → Hub WebSocket connection</span>\nwss://ws.greatvibe.ai/agent/connect\n  ?agent_id=<span style=\"color:#98c379;\">agent-prod-01</span>\n  &token=<span style=\"color:#98c379;\">eyJhbGciOi...</span>\n  &version=<span style=\"color:#98c379;\">1.2.3</span>\n\n<span style=\"color:#7f848e;\">// Message envelope</span>\n{\n  <span style=\"color:#98c379;\">\"id\"</span>: <span style=\"color:#98c379;\">\"msg_abc123\"</span>,        <span style=\"color:#7f848e;\">// Message ID for ack/retry</span>\n  <span style=\"color:#98c379;\">\"type\"</span>: <span style=\"color:#98c379;\">\"event_type\"</span>,      <span style=\"color:#7f848e;\">// See message types below</span>\n  <span style=\"color:#98c379;\">\"ts\"</span>: <span style=\"color:#98c379;\">\"2026-01-05T04:00:00Z\"</span>,\n  <span style=\"color:#98c379;\">\"data\"</span>: { ... }            <span style=\"color:#7f848e;\">// Type-specific payload</span>\n}\n\n<span style=\"color:#7f848e;\">// Message types: Agent → Hub</span>\n- <span style=\"color:#98c379;\">register</span>          <span style=\"color:#7f848e;\">// Initial registration with capabilities</span>\n- <span style=\"color:#98c379;\">heartbeat</span>         <span style=\"color:#7f848e;\">// Keep-alive (every 30s)</span>\n- <span style=\"color:#98c379;\">event</span>             <span style=\"color:#7f848e;\">// Session event (turn_started, tool_call, etc.)</span>\n- <span style=\"color:#98c379;\">status</span>            <span style=\"color:#7f848e;\">// Agent status update</span>\n- <span style=\"color:#98c379;\">replay_response</span>   <span style=\"color:#7f848e;\">// Response to replay request</span>\n\n<span style=\"color:#7f848e;\">// Message types: Hub → Agent</span>\n- <span style=\"color:#98c379;\">registered</span>        <span style=\"color:#7f848e;\">// Registration confirmed</span>\n- <span style=\"color:#98c379;\">work</span>              <span style=\"color:#7f848e;\">// Work assignment (prompt, flow)</span>\n- <span style=\"color:#98c379;\">stop</span>              <span style=\"color:#7f848e;\">// Stop current work</span>\n- <span style=\"color:#98c379;\">replay_request</span>    <span style=\"color:#7f848e;\">// Request session history</span>\n- <span style=\"color:#98c379;\">config_update</span>     <span style=\"color:#7f848e;\">// Push new configuration</span>\n- <span style=\"color:#98c379;\">ping</span>              <span style=\"color:#7f848e;\">// Health check</span>\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">8.4 API Endpoints</h3>\n\n<table style=\"width:100%;border-collapse:collapse;margin:12px 0;font-size:0.9em;\">\n<tr style=\"background:#3d3d3d;\">\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Endpoint</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Method</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Auth</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Description</th>\n</tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">/api/v1/agents</td><td style=\"padding:10px;border:1px solid #555;\">GET</td><td style=\"padding:10px;border:1px solid #555;\">User</td><td style=\"padding:10px;border:1px solid #555;\">List registered agents</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">/api/v1/agents/:id</td><td style=\"padding:10px;border:1px solid #555;\">GET</td><td style=\"padding:10px;border:1px solid #555;\">User</td><td style=\"padding:10px;border:1px solid #555;\">Get agent details + status</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">/api/v1/sessions</td><td style=\"padding:10px;border:1px solid #555;\">POST</td><td style=\"padding:10px;border:1px solid #555;\">User</td><td style=\"padding:10px;border:1px solid #555;\">Create session (assigns to agent)</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">/api/v1/sessions/:id</td><td style=\"padding:10px;border:1px solid #555;\">GET</td><td style=\"padding:10px;border:1px solid #555;\">User</td><td style=\"padding:10px;border:1px solid #555;\">Get session state</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">/api/v1/sessions/:id/prompt</td><td style=\"padding:10px;border:1px solid #555;\">POST</td><td style=\"padding:10px;border:1px solid #555;\">User</td><td style=\"padding:10px;border:1px solid #555;\">Send prompt (returns event stream)</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">/api/v1/sessions/:id/events</td><td style=\"padding:10px;border:1px solid #555;\">GET</td><td style=\"padding:10px;border:1px solid #555;\">User</td><td style=\"padding:10px;border:1px solid #555;\">Get events from seq N</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">/api/v1/flows</td><td style=\"padding:10px;border:1px solid #555;\">GET/POST</td><td style=\"padding:10px;border:1px solid #555;\">User</td><td style=\"padding:10px;border:1px solid #555;\">List/create flows</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#61afef;\">/agent/connect</td><td style=\"padding:10px;border:1px solid #555;\">WebSocket</td><td style=\"padding:10px;border:1px solid #555;\">Agent</td><td style=\"padding:10px;border:1px solid #555;\">Agent registration + events</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#61afef;\">/session/:id/subscribe</td><td style=\"padding:10px;border:1px solid #555;\">WebSocket</td><td style=\"padding:10px;border:1px solid #555;\">User</td><td style=\"padding:10px;border:1px solid #555;\">Real-time session events</td></tr>\n</table>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">8.5 CloudFlare Workers (Edge Functions)</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// Edge functions for latency-sensitive operations</span>\n\n<span style=\"color:#98c379;\">// Worker: auth-edge</span>\n<span style=\"color:#7f848e;\">// Validates JWT at edge, reduces origin load</span>\n\n<span style=\"color:#98c379;\">// Worker: rate-limit</span>\n<span style=\"color:#7f848e;\">// Per-IP and per-org rate limiting</span>\n\n<span style=\"color:#98c379;\">// Worker: quick-turn-cache</span>\n<span style=\"color:#7f848e;\">// Cache common quick-turn responses</span>\n</pre>\n\n<hr style=\"border:none;border-top:1px solid #444;margin:32px 0;\">\n\n<!-- SECTION 9: SESSION MANAGEMENT -->\n<h2 style=\"font-family:sans-serif;color:#fff;margin:32px 0 16px 0;border-bottom:2px solid #98c379;padding-bottom:8px;\">9. Session Management & Playback</h2>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">9.1 Session Lifecycle</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n┌─────────┐   create    ┌─────────┐   prompt    ┌─────────┐\n│  <span style=\"color:#7f848e;\">null</span>   │───────────►│  <span style=\"color:#61afef;\">idle</span>   │───────────►│ <span style=\"color:#e5c07b;\">working</span> │\n└─────────┘             └────┬────┘             └────┬────┘\n                             │                       │\n                        timeout/                turn_complete\n                        archive                      │\n                             │                       │\n                             ▼                       ▼\n                        ┌─────────┐             ┌─────────┐\n                        │<span style=\"color:#c678dd;\">archived</span> │◄────────────│  <span style=\"color:#61afef;\">idle</span>   │\n                        └─────────┘   archive   └─────────┘\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">9.2 Agent-Side Session Storage</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#98c379;\">~/.gvagent/data/</span>\n├── <span style=\"color:#e5c07b;\">sessions.db</span>                 <span style=\"color:#7f848e;\"># SQLite - session metadata</span>\n│\n├── <span style=\"color:#61afef;\">events/</span>\n│   ├── sess_abc123.jsonl      <span style=\"color:#7f848e;\"># Event journal for session</span>\n│   ├── sess_def456.jsonl\n│   └── sess_ghi789.jsonl\n│\n└── <span style=\"color:#c678dd;\">artifacts/</span>\n    └── sess_abc123/\n        ├── output_001.html    <span style=\"color:#7f848e;\"># Generated outputs</span>\n        └── report_002.json\n</pre>\n\n<h4 style=\"font-family:sans-serif;color:#e5c07b;margin:16px 0 8px 0;\">Sessions Database Schema</h4>\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#c678dd;\">CREATE TABLE</span> sessions (\n    id              TEXT PRIMARY KEY,\n    flow_id         TEXT,\n    provider_id     TEXT NOT NULL,\n    model           TEXT NOT NULL,\n    working_dir     TEXT NOT NULL,\n    status          TEXT NOT NULL,  <span style=\"color:#7f848e;\">-- idle, working, archived</span>\n    claude_session  TEXT,           <span style=\"color:#7f848e;\">-- For CLI --resume</span>\n    turn_count      INTEGER DEFAULT 0,\n    last_seq        INTEGER DEFAULT 0,\n    created_at      TEXT NOT NULL,\n    updated_at      TEXT NOT NULL,\n    metadata        TEXT            <span style=\"color:#7f848e;\">-- JSON blob</span>\n);\n\n<span style=\"color:#c678dd;\">CREATE TABLE</span> turns (\n    id              TEXT PRIMARY KEY,\n    session_id      TEXT NOT NULL,\n    sequence        INTEGER NOT NULL,\n    prompt          TEXT NOT NULL,\n    status          TEXT NOT NULL,\n    start_seq       INTEGER,        <span style=\"color:#7f848e;\">-- First event seq</span>\n    end_seq         INTEGER,        <span style=\"color:#7f848e;\">-- Last event seq</span>\n    created_at      TEXT NOT NULL,\n    completed_at    TEXT,\n    metrics         TEXT,           <span style=\"color:#7f848e;\">-- JSON: tokens, cost, duration</span>\n    FOREIGN KEY (session_id) REFERENCES sessions(id)\n);\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">9.3 Event Journal Format</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// sess_abc123.jsonl - append-only event journal</span>\n{\"seq\":1,\"ts\":\"2026-01-05T04:00:00Z\",\"type\":\"session_started\",\"data\":{\"provider\":\"claude-cli\",\"model\":\"claude-opus-4\"}}\n{\"seq\":2,\"ts\":\"2026-01-05T04:00:01Z\",\"type\":\"turn_started\",\"data\":{\"turn_id\":\"turn_001\",\"prompt\":\"Add authentication\"}}\n{\"seq\":3,\"ts\":\"2026-01-05T04:00:02Z\",\"type\":\"turn_text\",\"data\":{\"turn_id\":\"turn_001\",\"content\":\"I'll help you add authentication...\"}}\n{\"seq\":4,\"ts\":\"2026-01-05T04:00:03Z\",\"type\":\"tool_call\",\"data\":{\"turn_id\":\"turn_001\",\"tool\":\"Read\",\"input\":{\"file_path\":\"/src/auth.ts\"}}}\n{\"seq\":5,\"ts\":\"2026-01-05T04:00:04Z\",\"type\":\"tool_result\",\"data\":{\"turn_id\":\"turn_001\",\"tool\":\"Read\",\"output\":\"...\",\"duration_ms\":50}}\n{\"seq\":6,\"ts\":\"2026-01-05T04:00:10Z\",\"type\":\"turn_completed\",\"data\":{\"turn_id\":\"turn_001\",\"metrics\":{\"input_tokens\":1500,\"output_tokens\":2000,\"cost_usd\":0.05}}}\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">9.4 Session Replay Protocol</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// Hub requests replay (e.g., new viewer joins)</span>\n{\n  \"type\": \"replay_request\",\n  \"session_id\": \"sess_abc123\",\n  \"from_seq\": 0,          <span style=\"color:#7f848e;\">// Start from beginning</span>\n  \"to_seq\": -1            <span style=\"color:#7f848e;\">// To latest (-1 = all)</span>\n}\n\n<span style=\"color:#7f848e;\">// Agent streams events back</span>\n{\n  \"type\": \"replay_response\",\n  \"session_id\": \"sess_abc123\",\n  \"events\": [\n    {\"seq\":1,\"ts\":\"...\",\"type\":\"session_started\",...},\n    {\"seq\":2,\"ts\":\"...\",\"type\":\"turn_started\",...},\n    ...\n  ],\n  \"is_complete\": true,\n  \"total_events\": 150\n}\n\n<span style=\"color:#7f848e;\">// For large sessions, chunked replay</span>\n{\n  \"type\": \"replay_response\",\n  \"session_id\": \"sess_abc123\",\n  \"events\": [...],        <span style=\"color:#7f848e;\">// 100 events per chunk</span>\n  \"is_complete\": false,\n  \"next_seq\": 101\n}\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">9.5 Multi-Viewer Support</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// Browser subscribes to session</span>\nWebSocket: wss://greatvibe.ai/session/sess_abc123/subscribe\n  ?token=user_jwt\n  &from_seq=0         <span style=\"color:#7f848e;\">// Catch up from beginning</span>\n\n<span style=\"color:#7f848e;\">// Hub forwards events from agent to all viewers</span>\n<span style=\"color:#98c379;\">Agent</span> ──event──► <span style=\"color:#61afef;\">Hub</span> ──broadcast──► <span style=\"color:#e5c07b;\">Viewer 1</span>\n                      ──broadcast──► <span style=\"color:#e5c07b;\">Viewer 2</span>\n                      ──broadcast──► <span style=\"color:#e5c07b;\">Viewer 3</span>\n\n<span style=\"color:#7f848e;\">// Late-joining viewer catches up via replay</span>\n<span style=\"color:#e5c07b;\">Viewer 3</span> ──subscribe(from_seq=0)──► <span style=\"color:#61afef;\">Hub</span>\n         ◄──replay(seq 1-150)────────\n         ◄──live events (seq 151+)───\n</pre>\n\n<hr style=\"border:none;border-top:1px solid #444;margin:32px 0;\">\n\n<!-- SECTION 10: CONNECTION MANAGEMENT -->\n<h2 style=\"font-family:sans-serif;color:#fff;margin:32px 0 16px 0;border-bottom:2px solid #98c379;padding-bottom:8px;\">10. Connection Management & Recovery</h2>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">10.1 Connection States</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n┌─────────────┐   connect    ┌─────────────┐   registered   ┌─────────────┐\n│ <span style=\"color:#7f848e;\">disconnected</span>│─────────────►│ <span style=\"color:#e5c07b;\">connecting</span>  │──────────────►│ <span style=\"color:#98c379;\">connected</span>   │\n└──────┬──────┘              └──────┬──────┘               └──────┬──────┘\n       │                            │                             │\n       │    reconnect               │ timeout/error         disconnect\n       │    (with backoff)          │                             │\n       │                            ▼                             │\n       │                     ┌─────────────┐                      │\n       └─────────────────────│ <span style=\"color:#e06c75;\">reconnecting</span>│◄─────────────────────┘\n                             └─────────────┘\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">10.2 Reconnection Strategy</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#e5c07b;\">type</span> ReconnectConfig <span style=\"color:#e5c07b;\">struct</span> {\n    InitialDelay    time.Duration  <span style=\"color:#7f848e;\">// 1 second</span>\n    MaxDelay        time.Duration  <span style=\"color:#7f848e;\">// 5 minutes</span>\n    Multiplier      <span style=\"color:#e5c07b;\">float64</span>        <span style=\"color:#7f848e;\">// 2.0 (exponential backoff)</span>\n    Jitter          <span style=\"color:#e5c07b;\">float64</span>        <span style=\"color:#7f848e;\">// 0.1 (10% random jitter)</span>\n    MaxAttempts     <span style=\"color:#e5c07b;\">int</span>            <span style=\"color:#7f848e;\">// -1 (infinite)</span>\n}\n\n<span style=\"color:#7f848e;\">// Reconnect sequence:</span>\n<span style=\"color:#7f848e;\">// Attempt 1: 1s</span>\n<span style=\"color:#7f848e;\">// Attempt 2: 2s + jitter</span>\n<span style=\"color:#7f848e;\">// Attempt 3: 4s + jitter</span>\n<span style=\"color:#7f848e;\">// Attempt 4: 8s + jitter</span>\n<span style=\"color:#7f848e;\">// ...</span>\n<span style=\"color:#7f848e;\">// Attempt N: min(2^N, 300s) + jitter</span>\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">10.3 Work Preservation</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// Agent continues working during disconnection</span>\n<span style=\"color:#7f848e;\">// Events are queued locally, synced on reconnect</span>\n\n<span style=\"color:#e5c07b;\">type</span> EventQueue <span style=\"color:#e5c07b;\">struct</span> {\n    events      []Event       <span style=\"color:#7f848e;\">// Pending events to sync</span>\n    lastSyncSeq <span style=\"color:#e5c07b;\">int64</span>         <span style=\"color:#7f848e;\">// Last seq confirmed by hub</span>\n    maxQueueSize <span style=\"color:#e5c07b;\">int</span>          <span style=\"color:#7f848e;\">// 10000 events max</span>\n}\n\n<span style=\"color:#7f848e;\">// On reconnect:</span>\n<span style=\"color:#7f848e;\">// 1. Agent reports last_sync_seq</span>\n<span style=\"color:#7f848e;\">// 2. Hub requests missing events (if any)</span>\n<span style=\"color:#7f848e;\">// 3. Agent sends queued events</span>\n<span style=\"color:#7f848e;\">// 4. Normal operation resumes</span>\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">10.4 Heartbeat & Health</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// Agent sends heartbeat every 30 seconds</span>\n{\n  \"type\": \"heartbeat\",\n  \"ts\": \"2026-01-05T04:00:00Z\",\n  \"status\": {\n    \"active_sessions\": 2,\n    \"pending_events\": 0,\n    \"cpu_percent\": 15,\n    \"memory_mb\": 256\n  }\n}\n\n<span style=\"color:#7f848e;\">// Hub responds with pong</span>\n{\n  \"type\": \"pong\",\n  \"ts\": \"2026-01-05T04:00:00Z\"\n}\n\n<span style=\"color:#7f848e;\">// No heartbeat for 90s → Hub marks agent offline</span>\n<span style=\"color:#7f848e;\">// No pong for 90s → Agent reconnects</span>\n</pre>\n\n<hr style=\"border:none;border-top:1px solid #444;margin:32px 0;\">\n\n<!-- SECTION 11: FAILOVER & DR -->\n<h2 style=\"font-family:sans-serif;color:#fff;margin:32px 0 16px 0;border-bottom:2px solid #98c379;padding-bottom:8px;\">11. Failover & Disaster Recovery</h2>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">11.1 Same-Node Agent Failover</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<p style=\"color:#e0e0e0;margin:0 0 12px 0;\"><strong>Goal:</strong> If an agent crashes, a supervisor restarts it and work resumes automatically.</p>\n</div>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// systemd unit file for agent</span>\n[Unit]\nDescription=greatVibeAgent\nAfter=network.target\n\n[Service]\nType=simple\nUser=gvagent\nExecStart=/usr/local/bin/gvagent\nRestart=always\nRestartSec=5\nWatchdogSec=60\n\n[Install]\nWantedBy=multi-user.target\n</pre>\n\n<h4 style=\"font-family:sans-serif;color:#e5c07b;margin:16px 0 8px 0;\">Recovery Flow</h4>\n<ol style=\"color:#e0e0e0;line-height:2;\">\n<li>Agent process crashes</li>\n<li>systemd restarts agent within 5 seconds</li>\n<li>Agent reads sessions.db — finds active sessions</li>\n<li>Agent reconnects to hub with same agent_id</li>\n<li>Hub re-routes pending work to reconnected agent</li>\n<li>Agent resumes in-progress turns from last checkpoint</li>\n</ol>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">11.2 Hub Failover (Cloud)</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// Multi-AZ deployment with ALB health checks</span>\n\n┌─────────────────────────────────────────────────────────────────┐\n│                    Application Load Balancer                    │\n│                    (health check: /health)                      │\n└───────────────────────────┬─────────────────────────────────────┘\n                            │\n        ┌───────────────────┼───────────────────┐\n        │                   │                   │\n        ▼                   ▼                   ▼\n   ┌─────────┐         ┌─────────┐         ┌─────────┐\n   │ <span style=\"color:#98c379;\">Hub AZ-a</span> │         │ <span style=\"color:#98c379;\">Hub AZ-b</span> │         │ <span style=\"color:#98c379;\">Hub AZ-c</span> │\n   │ (active)│◄───────►│ (active)│◄───────►│ (active)│\n   └────┬────┘         └────┬────┘         └────┬────┘\n        │                   │                   │\n        └───────────────────┼───────────────────┘\n                            │\n                            ▼\n              ┌──────────────────────────┐\n              │  <span style=\"color:#61afef;\">RDS Multi-AZ (primary)</span>  │\n              │  <span style=\"color:#7f848e;\">+ Read Replicas</span>          │\n              └──────────────────────────┘\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">11.3 Data Durability</h3>\n\n<table style=\"width:100%;border-collapse:collapse;margin:12px 0;\">\n<tr style=\"background:#3d3d3d;\">\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Component</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Storage</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Durability</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Backup</th>\n</tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Agent sessions</td><td style=\"padding:10px;border:1px solid #555;\">Local SQLite + JSONL</td><td style=\"padding:10px;border:1px solid #555;\">Disk durability</td><td style=\"padding:10px;border:1px solid #555;\">Optional S3 sync</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Hub metadata</td><td style=\"padding:10px;border:1px solid #555;\">RDS PostgreSQL</td><td style=\"padding:10px;border:1px solid #555;\">99.99999999%</td><td style=\"padding:10px;border:1px solid #555;\">Daily snapshots</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Session channels</td><td style=\"padding:10px;border:1px solid #555;\">ElastiCache Redis</td><td style=\"padding:10px;border:1px solid #555;\">In-memory</td><td style=\"padding:10px;border:1px solid #555;\">Reconstructable</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Audit logs</td><td style=\"padding:10px;border:1px solid #555;\">S3 + Glacier</td><td style=\"padding:10px;border:1px solid #555;\">99.999999999%</td><td style=\"padding:10px;border:1px solid #555;\">7-year retention</td></tr>\n</table>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">11.4 Disaster Recovery Targets</h3>\n\n<table style=\"width:100%;border-collapse:collapse;margin:12px 0;\">\n<tr style=\"background:#3d3d3d;\">\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Metric</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Target</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Mechanism</th>\n</tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">RTO (Recovery Time Objective)</td><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">< 5 minutes</td><td style=\"padding:10px;border:1px solid #555;\">Auto-restart, ALB failover</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">RPO (Recovery Point Objective)</td><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">0 (no data loss)</td><td style=\"padding:10px;border:1px solid #555;\">Agent has source of truth</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Agent uptime</td><td style=\"padding:10px;border:1px solid #555;\">99.9%</td><td style=\"padding:10px;border:1px solid #555;\">systemd watchdog</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Hub uptime (cloud)</td><td style=\"padding:10px;border:1px solid #555;\">99.9%</td><td style=\"padding:10px;border:1px solid #555;\">Multi-AZ, auto-scaling</td></tr>\n</table>\n\n<hr style=\"border:none;border-top:1px solid #444;margin:32px 0;\">\n\n<!-- SECTION 12: MULTI-AGENT ARCHITECTURE -->\n<h2 style=\"font-family:sans-serif;color:#fff;margin:32px 0 16px 0;border-bottom:2px solid #98c379;padding-bottom:8px;\">12. Multi-Agent Architecture</h2>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">12.1 Hub and Spoke Model</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n                         ┌───────────────────────────┐\n                         │      <span style=\"color:#98c379;\">HUB (Central)</span>        │\n                         │                           │\n                         │   ┌─────────────────┐     │\n                         │   │   Work Queue    │     │\n                         │   │   ┌───┬───┬───┐ │     │\n                         │   │   │ W │ W │ W │ │     │\n                         │   │   └───┴───┴───┘ │     │\n                         │   └────────┬────────┘     │\n                         │            │              │\n                         │   ┌────────┴────────┐     │\n                         │   │  Agent Registry │     │\n                         │   │  ┌────┬────┬────┐    │\n                         │   │  │A1  │A2  │A3  │    │\n                         │   │  └────┴────┴────┘    │\n                         │   └─────────────────┘     │\n                         └─────────────┬─────────────┘\n                                       │\n         ┌─────────────────────────────┼─────────────────────────────┐\n         │                             │                             │\n         ▼                             ▼                             ▼\n  ┌─────────────┐               ┌─────────────┐               ┌─────────────┐\n  │ <span style=\"color:#98c379;\">Agent A1</span>    │               │ <span style=\"color:#61afef;\">Agent A2</span>    │               │ <span style=\"color:#c678dd;\">Agent A3</span>    │\n  │ <span style=\"color:#7f848e;\">US-West</span>     │               │ <span style=\"color:#7f848e;\">US-East</span>     │               │ <span style=\"color:#7f848e;\">EU-West</span>     │\n  │             │               │             │               │             │\n  │ Capabilities│               │ Capabilities│               │ Capabilities│\n  │ - Claude    │               │ - Claude    │               │ - Claude    │\n  │ - Postgres  │               │ - OpenAI    │               │ - K8s       │\n  └─────────────┘               └─────────────┘               └─────────────┘\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">12.2 Work Assignment Algorithm</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#e5c07b;\">func</span> (h *Hub) <span style=\"color:#61afef;\">AssignWork</span>(work Work) (Agent, <span style=\"color:#e5c07b;\">error</span>) {\n    <span style=\"color:#7f848e;\">// 1. Filter by required capabilities</span>\n    candidates := h.<span style=\"color:#61afef;\">filterByCapabilities</span>(work.RequiredCapabilities)\n    <span style=\"color:#c678dd;\">if</span> <span style=\"color:#61afef;\">len</span>(candidates) == 0 {\n        <span style=\"color:#c678dd;\">return</span> <span style=\"color:#d19a66;\">nil</span>, ErrNoCapableAgent\n    }\n    \n    <span style=\"color:#7f848e;\">// 2. Filter by affinity (same session should go to same agent)</span>\n    <span style=\"color:#c678dd;\">if</span> work.SessionID != \"\" {\n        <span style=\"color:#c678dd;\">if</span> agent := h.<span style=\"color:#61afef;\">getSessionAgent</span>(work.SessionID); agent != <span style=\"color:#d19a66;\">nil</span> {\n            <span style=\"color:#c678dd;\">return</span> agent, <span style=\"color:#d19a66;\">nil</span>\n        }\n    }\n    \n    <span style=\"color:#7f848e;\">// 3. Load balancing: pick least loaded agent</span>\n    <span style=\"color:#c678dd;\">return</span> h.<span style=\"color:#61afef;\">leastLoaded</span>(candidates), <span style=\"color:#d19a66;\">nil</span>\n}\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">12.3 Point-to-Point Agent Communication</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<p style=\"color:#e0e0e0;margin:0;\"><strong>Future capability:</strong> Agents can communicate directly for specialized tasks (e.g., database agent triggers K8s agent for scaling).</p>\n</div>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// Agent-to-agent via hub relay</span>\n<span style=\"color:#98c379;\">Agent A1</span> ──request──► <span style=\"color:#61afef;\">Hub</span> ──forward──► <span style=\"color:#c678dd;\">Agent A3</span>\n         ◄──response───     ◄──response───\n\n<span style=\"color:#7f848e;\">// Example: Database backup trigger K8s scale-down</span>\n{\n  \"type\": \"agent_request\",\n  \"from\": \"agent-postgres-01\",\n  \"to\": \"agent-k8s-01\",\n  \"action\": \"scale_replicas\",\n  \"data\": {\n    \"deployment\": \"api-server\",\n    \"replicas\": 0,\n    \"reason\": \"database maintenance\"\n  }\n}\n</pre>\n\n<hr style=\"border:none;border-top:1px solid #444;margin:32px 0;\">\n\n<!-- SECTION 13: SECURITY MODEL -->\n<h2 style=\"font-family:sans-serif;color:#fff;margin:32px 0 16px 0;border-bottom:2px solid #98c379;padding-bottom:8px;\">13. Security Model</h2>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">13.1 Credential Storage</h3>\n\n<table style=\"width:100%;border-collapse:collapse;margin:12px 0;\">\n<tr style=\"background:#3d3d3d;\">\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Credential Type</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Local Storage</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Cloud Storage</th>\n</tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Hub connection token</td><td style=\"padding:10px;border:1px solid #555;\">File (0600 perms)</td><td style=\"padding:10px;border:1px solid #555;\">AWS Secrets Manager</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Provider API keys</td><td style=\"padding:10px;border:1px solid #555;\">Env vars or keychain</td><td style=\"padding:10px;border:1px solid #555;\">AWS Secrets Manager</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">User session tokens</td><td style=\"padding:10px;border:1px solid #555;\">Hub-managed (SQLite)</td><td style=\"padding:10px;border:1px solid #555;\">ElastiCache + RDS</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Encryption keys</td><td style=\"padding:10px;border:1px solid #555;\">OS keychain</td><td style=\"padding:10px;border:1px solid #555;\">AWS KMS</td></tr>\n</table>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">13.2 Provider Credential Flow</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// Option 1: Agent-local credentials</span>\n<span style=\"color:#98c379;\">Agent</span> ──reads──► <span style=\"color:#e5c07b;\">~/.gvagent/providers/claude.env</span> (ANTHROPIC_API_KEY)\n      ──calls──► <span style=\"color:#61afef;\">api.anthropic.com</span>\n\n<span style=\"color:#7f848e;\">// Option 2: Hub-managed credentials (more secure)</span>\n<span style=\"color:#98c379;\">Agent</span> ──request──► <span style=\"color:#61afef;\">Hub</span> ──fetch──► <span style=\"color:#c678dd;\">Secrets Manager</span>\n      ◄──encrypted key────\n      ──decrypt with agent key──► <span style=\"color:#e5c07b;\">use for session</span>\n      ──clear after use────────►\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">13.3 Token Lifecycle</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#e5c07b;\">type</span> Token <span style=\"color:#e5c07b;\">struct</span> {\n    ID          <span style=\"color:#e5c07b;\">string</span>    <span style=\"color:#7f848e;\">// UUID</span>\n    Type        <span style=\"color:#e5c07b;\">string</span>    <span style=\"color:#7f848e;\">// \"user\", \"agent\", \"api\"</span>\n    Subject     <span style=\"color:#e5c07b;\">string</span>    <span style=\"color:#7f848e;\">// user_id or agent_id</span>\n    Scopes      []<span style=\"color:#e5c07b;\">string</span>  <span style=\"color:#7f848e;\">// Permissions</span>\n    IssuedAt    time.Time\n    ExpiresAt   time.Time\n    RevokedAt   *time.Time <span style=\"color:#7f848e;\">// nil if not revoked</span>\n}\n\n<span style=\"color:#7f848e;\">// Token TTLs</span>\n<span style=\"color:#7f848e;\">// User session: 24 hours (refresh with activity)</span>\n<span style=\"color:#7f848e;\">// Agent token: 1 year (or until revoked)</span>\n<span style=\"color:#7f848e;\">// API key: No expiry (explicit revocation)</span>\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">13.4 Security Boundaries</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n┌─────────────────────────────────────────────────────────────────┐\n│                      <span style=\"color:#e06c75;\">UNTRUSTED ZONE</span>                            │\n│                                                                 │\n│   ┌─────────────┐         ┌─────────────┐                       │\n│   │   Browser   │         │   AI API    │                       │\n│   │  (user's)   │         │  Response   │                       │\n│   └──────┬──────┘         └──────┬──────┘                       │\n│          │                       │                              │\n└──────────┼───────────────────────┼──────────────────────────────┘\n           │                       │\n           ▼                       ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                      <span style=\"color:#e5c07b;\">TRUST BOUNDARY</span>                            │\n│                                                                 │\n│   Authentication │ Authorization │ Input Validation             │\n│                                                                 │\n└──────────────────────────────────────────────────────────────────┘\n           │                       │\n           ▼                       ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                      <span style=\"color:#98c379;\">TRUSTED ZONE</span>                              │\n│                                                                 │\n│   ┌─────────────┐         ┌─────────────┐                       │\n│   │     Hub     │◄───────►│    Agent    │                       │\n│   │             │         │             │                       │\n│   │ Signed msgs │         │ Guardrails  │                       │\n│   │ Audit logs  │         │ Sandbox     │                       │\n│   └─────────────┘         └─────────────┘                       │\n│                                                                 │\n└─────────────────────────────────────────────────────────────────┘\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">13.5 Threat Mitigations</h3>\n\n<table style=\"width:100%;border-collapse:collapse;margin:12px 0;font-size:0.9em;\">\n<tr style=\"background:#3d3d3d;\">\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Threat</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Mitigation</th>\n</tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Prompt injection via AI</td><td style=\"padding:10px;border:1px solid #555;\">Guardrails block dangerous operations regardless of AI output</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Credential theft</td><td style=\"padding:10px;border:1px solid #555;\">Credentials in env vars or keychain, never in config files</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Unauthorized agent</td><td style=\"padding:10px;border:1px solid #555;\">Agent tokens are hub-signed, verified on every request</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Session hijacking</td><td style=\"padding:10px;border:1px solid #555;\">Tokens bound to IP, short TTL, activity-based refresh</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Data exfiltration</td><td style=\"padding:10px;border:1px solid #555;\">Network guardrails limit outbound connections</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Privilege escalation</td><td style=\"padding:10px;border:1px solid #555;\">Agent runs as unprivileged user, no sudo in guardrails</td></tr>\n</table>\n\n<hr style=\"border:none;border-top:1px solid #444;margin:32px 0;\">\n\n<!-- SECTION 14: CONFIG PARAMS -->\n<h2 style=\"font-family:sans-serif;color:#fff;margin:32px 0 16px 0;border-bottom:2px solid #98c379;padding-bottom:8px;\">14. Configuration Parameters Reference</h2>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">14.1 Environment Variables</h3>\n\n<table style=\"width:100%;border-collapse:collapse;margin:12px 0;font-size:0.85em;\">\n<tr style=\"background:#3d3d3d;\">\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Variable</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Default</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Description</th>\n</tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">GVAGENT_ID</td><td style=\"padding:10px;border:1px solid #555;\">hostname</td><td style=\"padding:10px;border:1px solid #555;\">Unique agent identifier</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">GVAGENT_HUB_URL</td><td style=\"padding:10px;border:1px solid #555;\">-</td><td style=\"padding:10px;border:1px solid #555;\">Hub WebSocket URL (required)</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">GVAGENT_TOKEN</td><td style=\"padding:10px;border:1px solid #555;\">-</td><td style=\"padding:10px;border:1px solid #555;\">Hub authentication token</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">GVAGENT_DATA_DIR</td><td style=\"padding:10px;border:1px solid #555;\">~/.gvagent</td><td style=\"padding:10px;border:1px solid #555;\">Data directory</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#61afef;\">GVAGENT_LOG_LEVEL</td><td style=\"padding:10px;border:1px solid #555;\">info</td><td style=\"padding:10px;border:1px solid #555;\">debug, info, warn, error</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#61afef;\">GVAGENT_LOG_FORMAT</td><td style=\"padding:10px;border:1px solid #555;\">json</td><td style=\"padding:10px;border:1px solid #555;\">json or text</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#e5c07b;\">ANTHROPIC_API_KEY</td><td style=\"padding:10px;border:1px solid #555;\">-</td><td style=\"padding:10px;border:1px solid #555;\">Claude API key</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#e5c07b;\">OPENAI_API_KEY</td><td style=\"padding:10px;border:1px solid #555;\">-</td><td style=\"padding:10px;border:1px solid #555;\">OpenAI API key</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#c678dd;\">GVAGENT_CLAUDE_BINARY</td><td style=\"padding:10px;border:1px solid #555;\">/usr/local/bin/claude</td><td style=\"padding:10px;border:1px solid #555;\">Path to Claude CLI</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;color:#c678dd;\">GVAGENT_CODEX_BINARY</td><td style=\"padding:10px;border:1px solid #555;\">/usr/local/bin/codex</td><td style=\"padding:10px;border:1px solid #555;\">Path to Codex CLI</td></tr>\n</table>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">14.2 Safety Limits</h3>\n\n<table style=\"width:100%;border-collapse:collapse;margin:12px 0;\">\n<tr style=\"background:#3d3d3d;\">\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Parameter</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Default</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Description</th>\n</tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">max_turn_duration_ms</td><td style=\"padding:10px;border:1px solid #555;\">900000</td><td style=\"padding:10px;border:1px solid #555;\">15 minutes hard limit per turn</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">max_tool_calls_per_turn</td><td style=\"padding:10px;border:1px solid #555;\">200</td><td style=\"padding:10px;border:1px solid #555;\">Prevent runaway tool loops</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">idle_timeout_ms</td><td style=\"padding:10px;border:1px solid #555;\">600000</td><td style=\"padding:10px;border:1px solid #555;\">10 minutes no activity → stop</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">max_concurrent_sessions</td><td style=\"padding:10px;border:1px solid #555;\">5</td><td style=\"padding:10px;border:1px solid #555;\">Sessions per agent</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">max_output_tokens</td><td style=\"padding:10px;border:1px solid #555;\">16384</td><td style=\"padding:10px;border:1px solid #555;\">Per API call</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">max_file_write_mb</td><td style=\"padding:10px;border:1px solid #555;\">10</td><td style=\"padding:10px;border:1px solid #555;\">Max file size for writes</td></tr>\n</table>\n\n<hr style=\"border:none;border-top:1px solid #444;margin:32px 0;\">\n\n<!-- SECTION 15: API CONTRACT -->\n<h2 style=\"font-family:sans-serif;color:#fff;margin:32px 0 16px 0;border-bottom:2px solid #98c379;padding-bottom:8px;\">15. API Contract with greatVibe Platform</h2>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">15.1 Agent Registration</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// Agent → Hub: Registration message</span>\n{\n  \"type\": \"register\",\n  \"agent_id\": \"agent-prod-01\",\n  \"version\": \"1.2.3\",\n  \"capabilities\": {\n    \"providers\": [\"claude-cli\", \"claude-api\", \"openai-api\"],\n    \"tools\": [\"read\", \"edit\", \"bash\", \"glob\", \"grep\"],\n    \"max_concurrent_sessions\": 5\n  },\n  \"system_info\": {\n    \"os\": \"linux\",\n    \"arch\": \"amd64\",\n    \"hostname\": \"prod-server-01\",\n    \"cpu_cores\": 8,\n    \"memory_gb\": 32\n  },\n  \"token\": \"eyJhbGciOi...\"\n}\n\n<span style=\"color:#7f848e;\">// Hub → Agent: Registration confirmed</span>\n{\n  \"type\": \"registered\",\n  \"hub_version\": \"2.0.1\",\n  \"config_version\": 42,\n  \"features\": [\"prompt_cache\", \"multi_viewer\"]\n}\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">15.2 Work Assignment</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// Hub → Agent: Work assignment</span>\n{\n  \"type\": \"work\",\n  \"work_id\": \"work_xyz789\",\n  \"session_id\": \"sess_abc123\",\n  \"flow_id\": \"flow_def456\",\n  \"turn_id\": \"turn_001\",\n  \"prompt\": \"Add user authentication to the API\",\n  \"attachments\": [],\n  \"config\": {\n    \"provider\": \"claude-cli\",\n    \"model\": \"claude-opus-4\",\n    \"working_dir\": \"/konnectvol\"\n  },\n  \"user\": {\n    \"id\": \"user_johnathon\",\n    \"name\": \"Johnathon\"\n  }\n}\n\n<span style=\"color:#7f848e;\">// Agent → Hub: Work accepted</span>\n{\n  \"type\": \"work_accepted\",\n  \"work_id\": \"work_xyz789\"\n}\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">15.3 Event Streaming</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// Agent → Hub: Session events (real-time)</span>\n\n<span style=\"color:#7f848e;\">// Turn started</span>\n{\"type\":\"event\",\"session_id\":\"sess_abc123\",\"seq\":1,\"event\":{\"type\":\"turn_started\",\"turn_id\":\"turn_001\"}}\n\n<span style=\"color:#7f848e;\">// Text chunk (streaming)</span>\n{\"type\":\"event\",\"session_id\":\"sess_abc123\",\"seq\":2,\"event\":{\"type\":\"turn_text\",\"turn_id\":\"turn_001\",\"content\":\"I'll help you...\"}}\n\n<span style=\"color:#7f848e;\">// Tool call</span>\n{\"type\":\"event\",\"session_id\":\"sess_abc123\",\"seq\":3,\"event\":{\"type\":\"tool_call\",\"turn_id\":\"turn_001\",\"tool\":\"Read\",\"input\":{\"file_path\":\"/src/auth.ts\"}}}\n\n<span style=\"color:#7f848e;\">// Tool result</span>\n{\"type\":\"event\",\"session_id\":\"sess_abc123\",\"seq\":4,\"event\":{\"type\":\"tool_result\",\"turn_id\":\"turn_001\",\"tool\":\"Read\",\"summary\":\"Read 150 lines from /src/auth.ts\"}}\n\n<span style=\"color:#7f848e;\">// Turn completed</span>\n{\"type\":\"event\",\"session_id\":\"sess_abc123\",\"seq\":5,\"event\":{\"type\":\"turn_completed\",\"turn_id\":\"turn_001\",\"metrics\":{\"input_tokens\":1500,\"output_tokens\":2000,\"cost_usd\":0.05,\"duration_ms\":15000}}}\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">15.4 Error Handling</h3>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\">// Error codes</span>\n<span style=\"color:#e5c07b;\">const</span> (\n    ErrCodeInvalidToken    = <span style=\"color:#98c379;\">\"INVALID_TOKEN\"</span>\n    ErrCodeAgentOffline    = <span style=\"color:#98c379;\">\"AGENT_OFFLINE\"</span>\n    ErrCodeSessionNotFound = <span style=\"color:#98c379;\">\"SESSION_NOT_FOUND\"</span>\n    ErrCodeProviderError   = <span style=\"color:#98c379;\">\"PROVIDER_ERROR\"</span>\n    ErrCodeGuardrailDeny   = <span style=\"color:#98c379;\">\"GUARDRAIL_DENIED\"</span>\n    ErrCodeRateLimited     = <span style=\"color:#98c379;\">\"RATE_LIMITED\"</span>\n    ErrCodeTurnTimeout     = <span style=\"color:#98c379;\">\"TURN_TIMEOUT\"</span>\n)\n\n<span style=\"color:#7f848e;\">// Error event</span>\n{\n  \"type\": \"event\",\n  \"session_id\": \"sess_abc123\",\n  \"seq\": 10,\n  \"event\": {\n    \"type\": \"turn_failed\",\n    \"turn_id\": \"turn_001\",\n    \"error\": {\n      \"code\": \"PROVIDER_ERROR\",\n      \"message\": \"Claude API returned 429: Rate limited\",\n      \"retryable\": true,\n      \"retry_after_ms\": 60000\n    }\n  }\n}\n</pre>\n\n<hr style=\"border:none;border-top:1px solid #444;margin:32px 0;\">\n\n<!-- SECTION 16: GREATVIBE.LOCAL SECURITY -->\n<h2 style=\"font-family:sans-serif;color:#fff;margin:32px 0 16px 0;border-bottom:2px solid #98c379;padding-bottom:8px;\">16. greatVibe.local Security Model</h2>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">16.1 Trust Model</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<p style=\"color:#e0e0e0;margin:0;\"><strong>greatVibe.local</strong> is designed for <strong>trusted environments</strong> — your own machine or private network. It assumes the operator has full control and trusts the agent.</p>\n</div>\n\n<pre style=\"background:#3d3d3d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n┌─────────────────────────────────────────────────────────────────┐\n│                    <span style=\"color:#98c379;\">TRUST BOUNDARY: Your Machine</span>                │\n│                                                                 │\n│   ┌─────────────┐         ┌─────────────┐                       │\n│   │ greatVibe   │◄───────►│  gvAgent    │                       │\n│   │ .local hub  │ loopback│             │                       │\n│   │             │ (127.0) │  Claude CLI │                       │\n│   │ Port 8666   │         │  Tools      │                       │\n│   └─────────────┘         └─────────────┘                       │\n│                                                                 │\n│   <span style=\"color:#7f848e;\">No external network access required for hub ↔ agent</span>           │\n└─────────────────────────────────────────────────────────────────┘\n           │\n           │ HTTPS (user browser)\n           ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                    <span style=\"color:#e5c07b;\">NETWORK BOUNDARY</span>                            │\n│                                                                 │\n│   - Password/API key authentication                             │\n│   - TLS encryption (self-signed or Let's Encrypt)               │\n│   - Optional: Cloudflare Tunnel for remote access               │\n└─────────────────────────────────────────────────────────────────┘\n</pre>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">16.2 Local Security Checklist</h3>\n\n<table style=\"width:100%;border-collapse:collapse;margin:12px 0;\">\n<tr style=\"background:#3d3d3d;\">\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Control</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Default</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Recommendation</th>\n</tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Hub binding</td><td style=\"padding:10px;border:1px solid #555;\">127.0.0.1</td><td style=\"padding:10px;border:1px solid #555;\">Keep localhost unless remote needed</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Authentication</td><td style=\"padding:10px;border:1px solid #555;\">Password</td><td style=\"padding:10px;border:1px solid #555;\">Use strong password or API key</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">TLS</td><td style=\"padding:10px;border:1px solid #555;\">Optional</td><td style=\"padding:10px;border:1px solid #555;\">Enable for remote access</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Guardrails</td><td style=\"padding:10px;border:1px solid #555;\">Permissive</td><td style=\"padding:10px;border:1px solid #555;\">Customize for your project</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Agent user</td><td style=\"padding:10px;border:1px solid #555;\">Current user</td><td style=\"padding:10px;border:1px solid #555;\">Run as dedicated user if multi-user</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Data dir perms</td><td style=\"padding:10px;border:1px solid #555;\">0700</td><td style=\"padding:10px;border:1px solid #555;\">Ensure only owner can access</td></tr>\n</table>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">16.3 Remote Access Options</h3>\n\n<table style=\"width:100%;border-collapse:collapse;margin:12px 0;\">\n<tr style=\"background:#3d3d3d;\">\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Method</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Security Level</th>\n<th style=\"text-align:left;padding:10px;color:#fff;border:1px solid #555;\">Use Case</th>\n</tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">localhost only</td><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">Highest</td><td style=\"padding:10px;border:1px solid #555;\">Solo dev on same machine</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">SSH tunnel</td><td style=\"padding:10px;border:1px solid #555;color:#98c379;\">High</td><td style=\"padding:10px;border:1px solid #555;\">Remote access via SSH</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Cloudflare Tunnel</td><td style=\"padding:10px;border:1px solid #555;color:#61afef;\">Medium-High</td><td style=\"padding:10px;border:1px solid #555;\">Zero-config remote access</td></tr>\n<tr><td style=\"padding:10px;border:1px solid #555;\">Direct expose + TLS</td><td style=\"padding:10px;border:1px solid #555;color:#e5c07b;\">Medium</td><td style=\"padding:10px;border:1px solid #555;\">LAN access for team</td></tr>\n</table>\n\n<hr style=\"border:none;border-top:1px solid #444;margin:32px 0;\">\n\n<!-- APPENDIX -->\n<h2 style=\"font-family:sans-serif;color:#fff;margin:32px 0 16px 0;border-bottom:2px solid #c678dd;padding-bottom:8px;\">Appendix A: Implementation Roadmap</h2>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">Phase 1: Core Agent (P0)</h3>\n<ul style=\"color:#e0e0e0;line-height:2;\">\n<li>Go project setup, WebSocket client</li>\n<li>SQLite session store, JSONL event journal</li>\n<li>Claude CLI provider with guardrails</li>\n<li>Hub connection and work assignment</li>\n</ul>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">Phase 2: Additional Providers (P1)</h3>\n<ul style=\"color:#e0e0e0;line-height:2;\">\n<li>Claude API provider (Quick Turn)</li>\n<li>OpenAI API provider</li>\n<li>Codex CLI provider</li>\n<li>Google Gemini provider</li>\n</ul>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">Phase 3: Local Models (P2)</h3>\n<ul style=\"color:#e0e0e0;line-height:2;\">\n<li>OpenWebUI integration</li>\n<li>VLLM support</li>\n<li>SGLang support</li>\n</ul>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:24px 0 12px 0;\">Phase 4: IDE Integrations (P3)</h3>\n<ul style=\"color:#e0e0e0;line-height:2;\">\n<li>VS Code extension</li>\n<li>Android Studio plugin</li>\n<li>Xcode plugin</li>\n</ul>\n\n<hr style=\"border:none;border-top:1px solid #444;margin:32px 0;\">\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-top:24px;\">\n<h3 style=\"color:#fff;margin:0 0 12px 0;font-family:sans-serif;\">Document Summary</h3>\n<p style=\"color:#9ca3af;margin:0;line-height:1.8;\">This design document defines the comprehensive architecture for <strong>greatVibeAgent</strong> — a cross-platform Go binary that serves as the execution layer for the greatVibe AI development platform. It covers provider plugins for Claude, OpenAI, Gemini, and local models; target platforms from AWS Linux to Xcode; a declarative guardrails system to replace dangerous open permissions; full AAA (authentication, authorization, accounting) for both local and cloud deployments; configuration management with hub push/pull; networking architecture with WebSockets, AWS ALB, and CloudFlare; session management with SQLite and JSONL event journals; connection recovery and failover; multi-agent hub-and-spoke architecture; comprehensive security model; and the complete API contract with the greatVibe platform.</p>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-top:16px;\">\n<h4 style=\"margin:0 0 8px 0;color:#fff;font-family:sans-serif;\">What's Next?</h4>\n<p style=\"color:#9ca3af;margin:0 0 12px 0;\">Choose an action:</p>\n</div>\n\n</div>",
    "choices": [
      {
        "label": "Save to file",
        "value": "Save this design document to /konnectvol/gv/docs/gvAgentDesign.md as a permanent reference",
        "primary": true
      },
      {
        "label": "Start implementation",
        "value": "Initialize the Go project structure for greatVibeAgent based on this design"
      },
      {
        "label": "Review providers",
        "value": "Deep dive into any specific provider implementation (Claude CLI, OpenAI, local models)"
      },
      {
        "label": "Refine guardrails",
        "value": "Expand the guardrails configuration with more detailed examples and edge cases"
      }
    ],
    "requestedAt": "2026-01-05T09:30:00Z",
    "requestId": "d3bcd3f0-4a09-4c38-a0ac-a155e5adad4d",
    "turnTiming": {
      "totalMs": 584254,
      "ttfeMs": 4729,
      "thinkingMs": 572347,
      "toolExecutionMs": 7177,
      "toolCallCount": 9,
      "thinkingPct": 98,
      "toolsPct": 1,
      "ttfePct": 1
    }
  },
  "createdBy": "claude",
  "createdAt": "2026-01-05T08:12:30.449Z",
  "updatedAt": "2026-01-05T08:12:47.827Z",
  "requestId": "d3bcd3f0-4a09-4c38-a0ac-a155e5adad4d",
  "scope": "vibetools",
  "tags": [
    "agent",
    "architecture",
    "design",
    "security",
    "networking"
  ],
  "targetUser": "claude"
}