Add Worker

Adding a worker to Agent Bridge

Agent Bridge dispatches work to local agent CLIs. This skill covers connecting a new one.

Two tiers. Establish which one you are in before writing anything, because tier 1 needs no code at all and is where most agents land.

Tier 0 — is there a programmatic interface?

Check, in order:

1. <cli> --help for an acp, agent, stdio, or serve subcommand.
2. The agent's source or package manifest for an agent-client-protocol dependency.
3. A non-interactive "print" mode that streams JSON and can resume a conversation by id.

If none of these exist, stop and tell the user. Agent Bridge integrates through real interfaces; GUI automation and computer use are not acceptable substitutes.

Tier 1 — config only, no code

A plain ACP server needs no source changes and no fork. Add a block to the user overlay at ~/.agent-bridge/agents.toml (%USERPROFILE%\.agent-bridge\agents.toml on Windows):

[agents.mycustom]
protocol = "acp"
command = ["mycustom-cli", "acp", "--yolo"]
revivable = true
idle_unload_sec = 900

Fields (all optional except protocol and command): fallback_commands (list of alternative argv lists), cwd, env (per-worker overlay), session_meta (extra params for session/new), revivable, idle_unload_sec, stall_timeout_sec, print_timeout.

Verify end to end before doing anything else:

list_agents        # the worker appears with available: true
dispatch_task      # agent="mycustom", cwd = an absolute scratch folder
wait_task          # loop until terminal
get_result         # text came back

Tier 1 gets you: spawn and handshake, session/new, prompting, streaming text, tool-call and workspace-diff file tracking, cancel, idle unload, transcripts, and session/load revive when revivable = true. Auto-approval works if the agent uses ACP requestPermission (Bridge picks allow-always) or accepts a yolo flag you put in command.

Go to tier 2 only if one of these is true:

Tier 2 — five-axis survey

Tier 2 edits Bridge's source, so it needs a git checkout of Agent Bridge. A uv tool install has no source tree to edit — clone the repo first, and expect to open a pull request rather than patching an installed package.

This is the only part that is genuinely different for every agent, and the only part you cannot template. Answer all five before editing source. Read the target agent's own source for its ACP handler and config-option construction; do not rely on blog posts or memory.

Axis 1 — launch and discovery. What argv runs headless? Is the product CLI actually the ACP server, or is the server a separate package? (One existing worker ships ACP as a different npm package than the product CLI, which is why it has a dedicated multi-step discovery routine.) Does it need a runtime like node to launch a script?

Axis 2 — auth. Product-level login, per-provider API keys, an external config file, or nothing? The decisive question is where an unauthenticated agent fails. If it only fails on the first prompt, the probe cannot see it: report auth state in the probe detail string, but never set available: false from it. A probe answers "is the command present", not "will a turn succeed". Any new environment variable must be added to both the bundled agents.toml [env] inherit list and DEFAULT_INHERIT_KEYS in config.py.

Axis 3 — session revival. Does it advertise session/load, session/resume, or neither? Does session/load replay the whole history as session/update notifications before it answers? If so it can outlast the handshake timeout on a long session — use resume. If revival is unsupported, set revivable = false.

Axis 4 — model and effort. Four sub-questions, each one changes code:

1. Where is it set? session/new _meta, process argv, session/set_config_option after the session exists, or only by respawning the process.
2. Does it stick? Verify on the real CLI. At least one existing worker accepts a model hint at session creation and then silently lands on its campaign default anyway, so Bridge has to re-send it afterwards. Documentation will not tell you this; only a real turn will.
3. Is the effort vocabulary global or per model? Per model is the common case. A static mapping table is then wrong on some models and wrong silently. Write an ordered preference list per Bridge effort level and pick the first value the live session actually advertises in its configOptions.
4. Does switching model reset effort? Usually yes. Clear the cached applied-effort whenever the applied model changes, or the next sync sees "already high", skips the call, and the turn quietly runs on the new model's default.

Two rules on failure behavior: an effort level that cannot be mapped is a warning, not a turn failure — the mismatch is Bridge's mapping problem and the turn should still run on the model's default. A model the coordinator named explicitly that the session rejects must fail the turn, with the real available options in the error; running silently on a different model means the coordinator reviews the work on a false premise.

Axis 5 — permissions and observability. Auto-approval via ACP requestPermission, an explicit mode switch, or a CLI flag? Is there an on-disk log that reveals which model actually ran, or can you only report what Bridge last set? And critically: what does a failed turn look like on the wire? One existing worker maps failures to stopReason: end_turn with empty text — identical to a clean no-op. Provoke a real failure (revoke the key, kill the network) and look. Anything a coordinator could misread belongs in the get_result hint for that agent.