Skip to content

README.md

Latest commit

 

History

History
165 lines (122 loc) · 8.62 KB

README.md

File metadata and controls

165 lines (122 loc) · 8.62 KB
Raw

Ambu: The OpenCode Agent Supervisor

Ambu: The Supervisor for OpenCode Coding Agents

OpenCode: Ready Ecosystem: OMO--Slim Memory: AMB Python: 3.10+ Tests License: MIT

Ambu (agentctl) is a small CLI for bounded, check-driven repair with OpenCode. It runs a user-supplied verification command, limits repair attempts, stops on repeated failures, and records each run. It is not a replacement for OMO/Slim orchestration, an operating-system sandbox, or a general-purpose acceptance judge.

What Ambu Does

Running autonomous coding agents in a repository often hits two key walls:

  1. Blind runaway loops: Agents hitting an environment bug or impossible constraint retry repeatedly, producing identical errors and burning quota.
  2. Missing verification boundaries: Agents report that a task is "done" without executing the project's test suite or verification commands.

Ambu wraps opencode run with bounded oversight: it dispatches tasks, executes your declared verification checks, enforces preflight policy gates, and stops when errors repeat.

Visual Demo: Anti-Loop Early Halt

When code changes fail to resolve an issue, Ambu hashes the normalized test failure output. If the identical blocker recurs, it halts early instead of burning rounds:

Ambu Anti-Loop Demo 

$ agentctl iterate coder "Fix auth token expiration" \
    --check "pytest tests/test_auth.py" \
    --max-rounds 5 \
    --max-same-failure 2
[Round 0] Evaluating initial check: pytest tests/test_auth.py
          FAIL: test_token_expiration (AssertionError: 401 != 200)
          Fingerprint: sha256:7f4a3b8c (gap: execution)
[Round 1] Dispatching OpenCode agent (fixer · grok-4.7-build-fast)...
          Workspace modified. Running verification check...
          FAIL: test_token_expiration (AssertionError: 401 != 200)
          Fingerprint: sha256:7f4a3b8c (seen 2x)
[HALT]    [ANTI-LOOP HALT] Identical blocker sha256:7f4a3b8c recurred 2 times.
          Status: BLOCKED (exit code 3) — Prevented 4 runaway rounds. Quota saved.

Core Capabilities

1. Smart Intent Routing (agentctl do)

Ambu uses word-boundary intent classification to route prompts to the right specialist station:

Prompt Intent Specialist Station Autonomy Responsibility
"Review database migrations for lock risks" oracle read_only Architectural audit & diagnosis
"Fix the broken auth login logic" fixer workspace_write Fast bug repair & patch
"Implement Stripe webhook billing endpoint" coder workspace_write Feature implementation
"Make navbar responsive with CSS layout" designer read_only UI/UX design & styling
"Find documentation for Upstash Redis" librarian read_only Docs & reference research
  • Negation Safety: "Do not fix this, just review why it broke" detects negation and suppresses write permissions.
  • Fail-Safe Fallback: Any ambiguity or tied score strictly defaults to safe read_only (oracle).

2. Evidence-Bound Iteration (agentctl iterate)

  • Output Normalization: Strips wall-clock timings (in 0.42s), ISO timestamps, memory addresses (0x7f...), PIDs, and temp directories while preserving exact test failure line numbers.
  • Gap Diagnosis: Categorizes failures into execution (code bugs), environment (missing dependencies), check_rubric (invalid test command), and transient (rate limits).
  • Artifact Verification (--eval-artifact): Verifies required output files exist and are non-empty before marking a task complete.

3. Policy Guardrails & Approvals

High-risk actions (git_push, deploy, secrets, global_config, destructive_delete) are blocked unless explicitly passed with --approve <capability>.

4. Evidence-Based Task Acceptance

run and iterate accept a supervisor-owned JSON acceptance contract, frozen before dispatch. Declare the required files or structured result, checks, and permission conditions for implementation, review, extraction, or research tasks:

agentctl run --acceptance-contract acceptance.json coder "Implement the requested change"
agentctl show <task_id> --json

Inspect acceptance_status independently of process status: exit zero or completed does not mean accepted. Checks are recorded by the supervisor; worker claims cannot pass them. A valid file may pass with empty stdout. Required denials fail acceptance; unclassified denials require review; optional denials remain evidence. Legacy records and new uncontracted run tasks stay unknown. Existing iterate check/artifact arguments synthesize a minimal contract. Process exit codes and approval policy are unchanged; callers must adopt the new acceptance fields.

See the contract schema and limitations and P1 verification evidence. Acceptance establishes only the declared criteria, not universal correctness or exhaustive review coverage.

Host compatibility controls

Hosts can restrict dispatch with model_routing.allowed_models and narrow it per invocation with RUNTIME_AGENTS_MODEL_ALLOWLIST (comma-separated local/... models). Restrictions require live model preflight; they never add fallback candidates. RUNTIME_AGENTS_EVENTS_JSONL selects an isolated event log.

The opt-in RUNTIME_AGENTS_DIAGNOSTIC_PROFILE=read_only selects the host-provided hcp-readonly-diagnostic OpenCode agent with --pure --format json; optional RUNTIME_AGENTS_DIAGNOSTIC_EVIDENCE supplies one --file argument. The host must already supply that agent and its permission policy. These flags are not an OS sandbox. See Steward compatibility decisions for prerequisites, checker-stop semantics, and the five-file patch assessment.

Ecosystem Integrations

  • oh-my-opencode-slim (OMO): Ambu's slim_bridge automatically inspects ~/.config/opencode/oh-my-opencode-slim.json, inheriting model assignments, reasoning variants (xhigh, max), and skill bindings with zero manual setup.
  • Agent Memory Bridge (AMB): Connects Ambu to durable memory. Pre-queries project gotchas before tasks, and shares discovered fixes across stations so no agent repeats a past mistake.
  • Michelin Kitchen Brigade Guide: Detailed breakdown of the Head Chef, Expeditor Pass, and station roles.
  • AMB Memory Integration Guide: Deep guide on auto-recall mechanics and shared incident logs.

Installation & Quickstart

git clone https://github.com/zzhang82/ambu-runtime-agents.git
cd ambu-runtime-agents
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
agentctl doctor

Essential Commands

# Natural language dispatch (auto-routes to oracle in read-only mode)
agentctl do "Review database schema for missing foreign key indexes"

# Code repair with automated test verification
agentctl do "Fix the broken user registration endpoint" --check "pytest tests/test_user.py"

# Bounded iteration with anti-loop protection (exit code 3 if repeated failure)
agentctl iterate coder "Fix billing calculation" --check "pytest" --max-same-failure 2

# Inspect guardrails and routing without running
agentctl do "Push commit to production remote" --dry-run --json

Looking for a hands-free OpenCode / Codex skill with automated milestone streaming and token spend telemetry? Check out ambu-skill.

Testing & License

Run the unit and integration tests:

python3 -m unittest discover -s tests

Released under the MIT License. Copyright © 2026 Frank Zhang.