Skip to content

Latest commit

 

History

History
256 lines (221 loc) · 12.2 KB

cli.md

File metadata and controls

256 lines (221 loc) · 12.2 KB

Command-Line & Stdio Interface Reference

API Hub · Public API · Errors · Operations · Architecture

Complete normative reference for command-line arguments, environment variables, slash commands, and the bidirectional Stdio JSON-RPC protocol (v: 1) powering the CLI and AppKit native desktop client (native/).


1. CLI Usage & Flags

USAGE:
  heav3ns-micro [OPTIONS] [PROMPT]

Execution Modes & Subcommands

Flag / Subcommand Long Flag / Form Description
(none) (default) Starts an interactive pair-programming REPL session in the terminal.
context context [--json] Displays the visual Context & Prompt Inspector HUD (or JSON telemetry).
preview-request preview-request [--json] Emits the outbound RequestManifest (heav3ns.request_manifest/v1) byte breakdown & KV-cache pin status without calling a provider.
models models [--refresh] Lists or force-refreshes the live auto-updating model pricing & context-window catalog (~/.heav3ns/pricing_catalog.json).
receipts receipts [--json] Lists auditable TurnReceipt (heav3ns.receipt/v1) records from .heav3ns/receipts.jsonl.
doctor doctor Runs comprehensive diagnostic audit across credentials, SLA, and substrate.
init init Interactive credential and provider onboarding wizard.
demo demo Runs offline guided tour and substrate self-test.
-p --prompt <TEXT> Executes a single agent turn with the given prompt and exits (0 on success, 1 on failure, 130 on SIGINT cancellation).
(none) --flight / --benchmark-flight Runs the 5-scenario Agent Flight benchmark suite (FT-01..FT-05).
(none) --bench Runs substrate micro-benchmarks along with the flight suite.
(none) --smoke Executes deterministic runtime self-checks and smoke verification.
(none) --stdio Runs the headless newline-delimited JSON-RPC worker protocol over stdin/stdout.

Configuration Options

Flag Parameter Default Description
-m --model <NAME> gpt-5.6-terra Target LLM model name passed to provider requests.
(none) --provider <NAME> openai Protocol format: openai, anthropic, or gemini.
(none) --endpoint <URL> (official default) Custom API endpoint URL for self-hosted or proxy models.
(none) --cwd <DIR> . Sets the active workspace root directory.
(none) --desktop-worker false Enables full desktop IDE RPC dispatch mode for native/.
(none) --desktop-account <ACC> (none) Configures specific authenticated account context for desktop worker.
(none) --format <FMT> text Flight output format: text or json.
-o --output <PATH> (none) Writes the JSON flight benchmark report to a file.
-h --help (none) Displays usage instructions and exits.

2. Environment Variables

Variable Description Default
OPENAI_API_KEY Authentication bearer token for OpenAI provider calls. (none)
ANTHROPIC_API_KEY Authentication token for Anthropic Claude provider calls. (none)
GEMINI_API_KEY Authentication token for Google Gemini provider calls. (none)
DEEPSEEK_API_KEY Authentication token for DeepSeek provider calls. (none)
OPENROUTER_API_KEY Authentication token for OpenRouter provider calls. (none)
XAI_API_KEY Authentication token for xAI Grok provider calls. (none)
GROQ_API_KEY Authentication token for Groq provider calls. (none)
HEAV3NS_PRICING_TTL_SECS TTL duration in seconds for ~/.heav3ns/pricing_catalog.json cache before auto-refreshing. 43200 (12h)
HEAV3NS_OFFLINE_PRICING Set to 1 to disable all background network fetches to OpenRouter /models. (none)
HEAV3NS_MODEL_CATALOG_URL Custom endpoint URL override for fetching remote model metadata. https://openrouter.ai/api/v1/models
HEAV3NS_ARENA_CAPACITY_BYTES Override default 16-MiB arena capacity in bytes. 16777216
HEAV3NS_AUTHORITY Override execution authority (ReadOnly, WorkspaceWrite, etc.). WorkspaceWrite

3. Interactive Slash Commands (REPL Mode)

When running in interactive REPL mode, commands starting with / execute deterministic control routines without LLM inference:

Command Arguments Description
/help (none) Displays available commands and runtime shortcuts.
/status (none) Prints current session state, transcript length, context budget, and arena memory usage.
/context [json] Displays the visual 20-cell token bar HUD, KV-cache prefix fingerprint, and tool routing.
/prompt [prefix|compact|specialist|side|json] Inspects deterministic static prompt prefix, full prompt, or profile outputs.
/tools [NAME] Displays active core vs. on-demand specialist tools, unlocked tools, and token savings.
/compact [RATIO] Triggers deterministic transcript compaction (default threshold: 75%).
/clear (none) Clears active conversation memory while preserving VFS baseline.
/memory [KEY] [VAL] Inspects, sets, or lists entries in the persistent MemoryStore.
/vfs [diff|staged] Inspects staged virtual file system modifications.
/commit (none) Atomically flushes staged VFS edits to disk with conflict detection.
/skills (none) Ingests and lists available .agents/skills/ capabilities.
/rewind [TICKS] Performs $O(1)$ multi-state rewind using SlabBufferSnapshot.
/doctor (none) Executes architectural self-diagnostics, prompt hygiene, and health checks.
/cua (none) Inspects virtual display state and Set-of-Marks layout.
/browser (none) Inspects zero-trust browser session and DOM navigation state.
/vision [PATH] Inspects image metadata or generates synthetic test SVG/BMP assets.
/forge [CMD] Interacts with the evolutionary Skill DAG and Soul Drop Vault.
/soul (none) Inspects active SoulProfile axioms and operational directives.
/posture [ask|accept-edits|plan|auto|yolo|next] Inspects or steps the 5-stop ExecutionPosture dial without mutating KV-cached tool schemas.
/plan / /ask / /auto (none) Instant shortcuts to switch into Plan, Ask, or AutoReview execution posture.
/undo [--force] Undoes the last turn's file edits via WorkspaceSnapshotCas (WouldBlock-protected against post-turn manual edits).
/restore <SNAPSHOT_ID> Restores workspace files from a content-addressed CAS snapshot.
/diff (none) Renders positional LCS unified diffs across modified workspace files (works with or without Git).
/receipts [N] Displays recent TurnReceipt (heav3ns.receipt/v1) summaries, honest billing, and claim ceilings.
/preview-request [json] Inspects exact canonical outbound wire byte breakdown (heav3ns.request_manifest/v1).
/model [NAME|auto] Switches model (declaring an authorized KV-cache repin) or probes local Ollama via /model auto.
/legion [TASK] Classifies task into a 7-specialist topological swarm formation.

4. Stdio JSON-RPC Protocol Specification (v: 1)

When spawned with --stdio (and optionally --desktop-worker), heav3ns-micro acts as a deterministic JSON-RPC 2.0 host communicating over standard I/O.

Protocol Invariants

  1. Single-Line Framing: Every message is serialized as a single JSON object terminated by \n.
  2. Version Tagging: Every outbound frame emitted by heav3ns-micro includes "v": 1 as verified by ControlFrameReader.swift.
  3. Stderr Isolation: Diagnostic logs, traces, and panics are routed exclusively to stderr to prevent frame desynchronization on stdout.

Startup & Connection Handshake

Immediately upon launching, the worker outputs a ready event:

{"v": 1, "type": "connection", "state": "ready"}

The host client then performs an initialization call to negotiate capabilities:

Request (initialize)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "capabilities": [
      "conversations",
      "spider-check-v1",
      "runtime-state-v1",
      "task-continuation-v1",
      "project-repair-v1",
      "checkpoints-v1",
      "prompt-inspect-v1",
      "run-details",
      "queue-edit",
      "queue-remove"
    ]
  }
}

Response (initialize)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "1.0",
    "capabilities": [
      "conversations",
      "spider-check-v1",
      "runtime-state-v1",
      "task-continuation-v1",
      "project-repair-v1",
      "checkpoints-v1",
      "prompt-inspect-v1",
      "run-details",
      "queue-edit",
      "queue-remove"
    ],
    "workspace": "ws-1731099600",
    "session": "session-default"
  }
}

5. Desktop RPC Method Catalog

Context & Prompt Telemetry (context.inspect & prompt.inspect)

Inspects active token budgets, KV-cache prefix fingerprint, dynamic workspace facts, and tool routing breakdowns.

  • Request: {"jsonrpc": "2.0", "id": 2, "method": "context.inspect", "params": {}}
  • Result: {"profile": "standard", "modelName": "gpt-5.6-terra", "modelFamily": "openai_reasoning", "cachePrefixHash": "c88ab3c9", "activeTools": 15, "totalTools": 29, "governanceSources": ["SOUL.md"]}
  • Request: {"jsonrpc": "2.0", "id": 3, "method": "prompt.inspect", "params": {"view": "prefix"}}
  • Result: {"view": "prefix", "content": "..."}

Snapshot & Synchronization (snapshot)

Requests complete snapshot of workspace state, active runs, and transcript history.

  • Request: {"jsonrpc": "2.0", "id": 2, "method": "snapshot", "params": {}}
  • Result:
    {
      "workspace": "ws-1731099600",
      "session": "session-default",
      "runtime": "heav3ns-micro-0.1.0",
      "seq": 4,
      "runs": [
        {
          "id": "run-001",
          "state": "completed",
          "text": "Refactor memory store",
          "createdAt": 1731099600000,
          "activities": []
        }
      ]
    }

File Operations (files.*)

  • files.list: Returns recursive directory structure with file sizes and modification timestamps.
  • files.read: Reads UTF-8 source code with pagination parameters (offset, limit).
  • files.readBinary: Reads binary documents (PDF, PNG, CSV) returning Base64 chunks:
    {
      "path": "docs/architecture.pdf",
      "encoding": "base64",
      "chunkIndex": 0,
      "totalChunks": 1,
      "data": "JVBERi0xLjQKJeLjz9MKMSAwIG9ia..."
    }

Git & Working Tree Diffs (changes.read)

Returns unified diff representations of file modifications:

  • Params: {"path": "src/core/engine.rs", "staged": false}
  • Result: {"path": "src/core/engine.rs", "diff": "--- a/src/core/engine.rs\n+++ b/src/core/engine.rs\n@@ -10,3 +10,4 @@\n..."}

Spider Static Checks (spider.check)

Runs local static syntax checks, import resolution, and circular dependency checks:

  • Params: {"scope": "all"}
  • Result:
    {
      "status": "passed",
      "entropyScore": 0.0031,
      "findings": [],
      "files": ["src/lib.rs", "src/core/engine.rs"]
    }

Long-Term Memory Store (memory.*)

  • memory.list: Returns all persistent key-value facts for the workspace.
  • memory.save: Upserts a key-value memory entry with timestamp.
  • memory.remove: Deletes a memory entry by key.

Task Execution & Lifecycle (task.*)

  • task.submit: Submits a prompt for autonomous agent execution.
  • task.stop: Initiates immediate, safe cooperative cancellation of active work.
  • task.lookup: Queries unconfirmed submission status by UUID to safely prevent replays.

Swarm Orchestration (swarm.*)

  • swarm.plan: Generates a dependency-ordered multi-specialist formation graph.
  • swarm.next: Claims the next actionable specialist assignment.
  • swarm.report: Submits specialist completion evidence and marks downstream tasks ready.