╔══════════════════════════════════════════════════════════════════╗
║  _  _                             ___        _                  ║
║ | || |__ _ _ _ _ _  ___ ______   | __|_ _ __| |_ ___ _ _ _  _  ║
║ | __ / _` | '_| ' \/ -_|_-<_-<  | _/ _` / _|  _/ _ \ '_| || | ║
║ |_||_\__,_|_| |_||_\___/__/__/  |_|\__,_\__|\__\___/_|  \_, | ║
║                                                          |__/  ║
╠══════════════════════════════════════════════════════════════════╣
║ 🏭 Profile-driven ACP agent — one binary, many roles           ║
║ https://github.com/xiwan/harness-factory                       ║
╚══════════════════════════════════════════════════════════════════╝

Lightweight ACP agent harness — single Go binary (~6MB), profile-driven tool activation, zero external dependencies.

acp-bridge (HTTP)
    │
    │  fork + stdin/stdout (ACP JSON-RPC)
    │  pass profile → activate tools + permissions
    ▼
harness-factory (single binary, ~6MB)
    │
    ├── fs       — read, write, list, search
    ├── git      — status, diff, log, show, commit, push
    ├── shell    — exec (allowlist/blocklist)
    ├── web      — fetch
    └── artifact — write, read, list (sandboxed `outputs/` for inter-agent exchange)

Same binary, different profiles → different agents (code reviewer, devops bot, research assistant).

10 profiles designed from tool combination permutations (fs/git/shell/web):

artifact tool is additionally activated on the five read-only-leaning profiles (reader, scout, reviewer, analyst, researcher) so they can hand data to downstream agents without gaining full fs.write. See Artifact tool below.

Each scenario is just a different profile on the same ~6MB binary. No new code, no new deployment — add a profile in config.yaml and go.

Profiles without fs.write can still produce output for the next agent in a pipeline via the artifact tool. It writes into a sandboxed <cwd>/outputs/ directory with a tighter safety envelope than free-form fs.write:

Lifecycle of outputs/ is the caller's responsibility — harness-factory never cleans it up. Bridges running a pipeline should either point each session at a shared cwd to stitch stages together, or tear down per-session scratch directories themselves.

# Build (stripped binary, ~6MB)
make build

# Version
./harness-factory --version

# List built-in profiles
./harness-factory --profiles

# List built-in models
./harness-factory --models

# Run with a specific profile
./harness-factory --profile pr-reviewer

# Run with a specific model
./harness-factory --profile reviewer --model claude-haiku

# Test (protocol only, no LiteLLM needed)
make test

# Test (full e2e, needs LiteLLM + .env)
cp .env.example .env
# edit .env with your tokens
make test-e2e

# One-shot run
bash scripts/run.sh "list files in /tmp"

# Interactive mode
bash scripts/run.sh

1. Bridge forks harness-factory
2. initialize → returns agent info + capabilities
3. session/new { cwd, profile } → activates tools per profile
4. session/prompt { prompt } → runs agent loop:
   • Calls LLM via LiteLLM (OpenAI-compatible API)
   • LLM requests tool calls → permission check → execute → return result
   • Sends session/update notifications (tool_call, tool_call_update, agent_message_chunk)
   • Loops until LLM says done or max_turns reached
5. Returns { sessionId, stopReason: "end_turn" }

Add to acp-bridge config.yaml:

agents:
  pr-reviewer:
    enabled: true
    mode: "acp"
    command: "harness-factory"
    acp_args: []
    working_dir: "/tmp"
    description: "Code review agent (harness-factory)"
    profile:
      tools:
        fs: { permissions: [read, list] }
        git: { permissions: [diff, log, show] }
        shell: { allowlist: [pytest, mypy, grep] }
      orchestration: free
      resources:
        timeout: 300s
        max_turns: 20
      agent:
        model: "bedrock/anthropic.claude-sonnet-4-6"
        system_prompt: "You are a code reviewer."
        temperature: 0.3

Bridge injects litellm_url and litellm_api_key automatically.

session/new responds with the actual model ID selected for this session, so the client never has to guess what auto or an alias expanded to:

{
  "sessionId": "sess_1234",
  "activated": {
    "tools": ["fs_read", "git_diff"],
    "toolCount": 2,
    "orchestration": "free",
    "resolvedModel": "bedrock/anthropic.claude-sonnet-4-6"
  }
}

• auto / empty → one of the registry models (randomly picked)
• alias (e.g. claude-sonnet) → expanded to its full ID
• full ID → passed through unchanged

If a model fails mid-session and falls back to the next one, harness-factory emits a session/update notification so the client can track the change:

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_1234",
    "update": {
      "sessionUpdate": "model_resolved",
      "model": "bedrock/deepseek.v3.2",
      "reason": "fallback"
    }
  }
}

reason is one of: fallback (primary failed), user_switch (natural-language switch mid-prompt). Clients that don't recognise model_resolved simply ignore the update — the extension is backward-compatible.

A mirrored stderr log is also emitted for scrapers: [MODEL_RESOLVED] model=<id> reason=<...>.

Full profile reference with all fields, types, and valid values → AGENT.md#profile-reference

{
  "tools": {
    "fs": { "permissions": ["read"] },
    "git": { "permissions": ["diff", "log"] },
    "shell": { "allowlist": ["pytest", "mypy"] }
  },
  "orchestration": "free",
  "resources": { "timeout": "300s", "max_turns": 20, "log_level": "info" },
  "agent": {
    "model": "bedrock/anthropic.claude-sonnet-4-6",
    "system_prompt": "You are a code reviewer...",
    "temperature": 0.3
  }
}

Two layers of protection:

• Exposure: LLM only sees activated tools (doesn't know others exist)
• Enforcement: Permission checker blocks any unauthorized tool call at runtime

cmd/harness-factory/main.go    — entry point, ACP JSON-RPC loop
internal/
  acp/          — stdin/stdout JSON-RPC transport
  profile/      — profile struct + permission queries
  permission/   — runtime tool call permission checker
  tools/        — registry + fs/git/shell/web implementations
  llm/          — LiteLLM HTTP client (OpenAI-compatible)
  agent/        — agent loop (LLM ↔ tool-use cycle)
  logger/       — structured stderr logging
  constraint/   — orchestration constraints (P1)
scripts/
  run.sh        — convenience launcher (one-shot + interactive)
test/
  main_test.go                — Go unit tests
  test_agent_compliance.sh    — ACP compliance + e2e test

harness-factory calls LLMs through LiteLLM proxy — any provider LiteLLM supports works out of the box:

Set the model field in your profile — harness-factory passes it directly to LiteLLM. Provider API keys are configured on the LiteLLM side, not in harness-factory.

7 representative Bedrock models built-in with alias support:

Features:

• Auto-selection: Default auto randomly picks a model from the registry
• Auto-fallback: If a model fails, automatically tries the next one until all exhausted
• Natural language switch: Say "use claude" or "换个模型" in your prompt to switch models mid-session
• Alias or full ID: Use claude-haiku or pass any full LiteLLM model ID directly

# List built-in models
./harness-factory --models

# Use a specific model alias
./harness-factory --profile reviewer --model claude-haiku

# Auto-select (default)
./harness-factory --profile reviewer

• Go 1.21+
• LiteLLM running (for agent loop / e2e tests)

See versions/ for version history.

• acp-bridge — HTTP gateway that forks and manages harness-factory instances
• ACP Protocol — Agent Client Protocol specification