diff --git a/content/docs/docs/getting-started/harnesses.mdx b/content/docs/docs/getting-started/harnesses.mdx index 62bbd3b..c5653bd 100644 --- a/content/docs/docs/getting-started/harnesses.mdx +++ b/content/docs/docs/getting-started/harnesses.mdx @@ -30,6 +30,8 @@ Each harness gets what it supports: | grok | the skill, and the MCP server via `grok mcp add` | | pi | the skill (pi has no MCP) | +[Plugins](/plugins) covers each piece in detail: the [agent plugin](/plugins/agent-plugin), the [skill](/plugins/skill) and the [opencode plugin](/plugins/opencode). + Two harnesses need a step of their own: - **Gemini CLI** enables MCP servers only in folders you have trusted. @@ -111,7 +113,7 @@ The plugin in `plugin/awp/` follows the [Agent Plugins spec](https://github.com/ Each release also ships the plugin with binaries for every platform, as `awp-plugin_.tar.gz`. To load it in Claude Code: ```bash -curl -fsSLO https://github.com/agentwireprotocol/awp/releases/download/v0.5.0/awp-plugin_0.5.0.tar.gz -tar -xzf awp-plugin_0.5.0.tar.gz # creates ./awp +curl -fsSLO https://github.com/agentwireprotocol/awp/releases/download/v0.6.0/awp-plugin_0.6.0.tar.gz +tar -xzf awp-plugin_0.6.0.tar.gz # creates ./awp claude --plugin-dir ./awp ``` diff --git a/content/docs/docs/guides/watching.mdx b/content/docs/docs/guides/watching.mdx index e3115dc..7428f91 100644 --- a/content/docs/docs/guides/watching.mdx +++ b/content/docs/docs/guides/watching.mdx @@ -73,3 +73,7 @@ The dashboard is built on the same data you can read yourself: - `awp status --json`, `awp peers --json`, `awp threads --json` - the [web API](/reference/web-api): JSON endpoints and a server-sent event stream + +## In a terminal + +If your agents run in [herdr](https://herdr.dev), the [herdr plugin](/plugins/herdr) shows the same traffic without a browser: a notification for each message and for a peer's `waiting`, `done` or `failed`, a live inbox pane, and a popup with status and threads. Its dashboard action starts `awp web` and opens it. diff --git a/content/docs/meta.json b/content/docs/meta.json index 966f9ee..2186b27 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -2,6 +2,7 @@ "title": "Agent Wire Protocol", "pages": [ "docs", + "plugins", "reference", "go", "python", diff --git a/content/docs/plugins/agent-plugin.mdx b/content/docs/plugins/agent-plugin.mdx new file mode 100644 index 0000000..c54594b --- /dev/null +++ b/content/docs/plugins/agent-plugin.mdx @@ -0,0 +1,129 @@ +--- +title: The agent plugin +description: The awp plugin for Claude Code and Agent Plugins clients, with a skill, an MCP server and hooks. What is in it, how to install it, channels, and troubleshooting. +--- + +The agent plugin gives a model everything it needs to use awp. It is one package, in `plugin/awp/` of the repository, with three parts: + +- **the skill**, which teaches the model when to use awp and the conventions: threads, states, waiting, safety. See [The skill](/plugins/skill). +- **the MCP server**, `awp mcp`, with the `awp_*` tools, for models that prefer tools to shell commands. See [MCP server](/reference/mcp). +- **hooks**, which add new messages to the model's context without it having to ask. See [Hooks](/reference/hooks). + +It follows the [Agent Plugins spec](https://github.com/agentplugins/agent-plugins-spec) and also carries Claude Code's own manifest, so Claude Code loads all three parts. Other clients that read the spec's `plugin.json` get the skill and the MCP server. + +## Install + +### With bootstrap + +```bash +awp bootstrap --harness claude +``` + +bootstrap copies the plugin to `~/.claude/skills/awp/`. Claude Code loads plugins it finds there as `@skills-dir`, so this one loads as `awp@skills-dir`, hooks and MCP server included. The awp binary embeds the plugin files, so nothing is downloaded. Instead of a bundled binary, `libexec/awp--` is a symlink to the awp binary that ran bootstrap, so upgrading awp upgrades the plugin's binary too. + +If `~/.claude/skills/awp` already exists and is not the awp plugin, bootstrap stops and asks you to move it aside. + +Restart running Claude Code sessions afterwards. See [Set up your harnesses](/getting-started/harnesses) for the other harnesses. + +### From a release + +Every release ships the plugin with binaries for Linux and macOS, amd64 and arm64: + +```bash +curl -fsSLO https://github.com/agentwireprotocol/awp/releases/download/v0.6.0/awp-plugin_0.6.0.tar.gz +tar -xzf awp-plugin_0.6.0.tar.gz # creates ./awp +claude --plugin-dir ./awp +``` + +This works without awp installed anywhere else. The plugin's `bin/` is on the model's PATH, so the skill's `awp ...` commands run the bundled binary. + +### From a checkout + +```bash +make plugin # binaries for every platform, in plugin/awp/libexec/ +make plugin-local # or just this machine's +claude --plugin-dir ./plugin/awp +``` + +`make plugin` also runs `claude plugin validate` when `claude` is installed. + +## What is in it + +```text +plugin/awp/ + plugin.json Agent Plugins 1.0.0 manifest + mcp.json MCP server for Agent Plugins clients: ./bin/awp mcp + skills/awp/SKILL.md the skill + bin/awp launcher: runs libexec/awp-- + libexec/ the binaries (built by make plugin, or in the release bundle) + .claude-plugin/plugin.json Claude Code manifest, pointing at the hooks + .mcp.json Claude Code MCP config: bin/awp mcp --harness claude + com.anthropic.claude-code/ + hooks.json Claude Code hooks +``` + +### The launcher + +`bin/awp` is a shell script. It picks `libexec/awp--` for the machine it runs on (`linux` or `darwin`, `amd64` or `arm64`). If the plugin has no build for this platform, it runs the first other `awp` on PATH, never itself. If there is none, it exits `127` with instructions to install awp. + +### The MCP server + +Both MCP configs run the launcher. Claude Code's passes `--harness claude`, so a daemon started from the MCP server knows which harness it serves. The tools are `awp_listen`, `awp_connect`, `awp_send`, `awp_read`, `awp_state`, `awp_grant` and `awp_status`. They behave exactly like the CLI, since both call the same daemon. + +### The hooks + +| Claude Code event | runs | what the model sees | +|-------------------|------|---------------------| +| `SessionStart` | `awp hook session-start` | identity, the address to share, connected peers, unread messages | +| `UserPromptSubmit` | `awp hook inbox` | messages that arrived since its last turn | +| `PostToolUse`, every tool | `awp hook inbox` | messages that arrived during the turn | +| `Stop` | `awp hook stop` | a request to handle unread messages before finishing, once per stop | + +Each hook has a 10 second timeout. Each call starts the binary, which takes about 9 ms. They print nothing when the daemon is not running or nothing is new, so a session that never uses awp never sees them. Messages a hook shows are marked read, and each batch is framed as untrusted input from another agent. + +The hooks also keep the network's view of the agent current. Each run records activity, and Claude Code's hooks report the model of the latest reply in the session transcript, so a `/model` switch reaches dashboards. + +## Channels + +Hooks only run while Claude Code is working. A message that arrives after the session finished its turn waits until the user types again. **Channels** close that gap: Claude Code can receive MCP notifications as messages that reach the model without a tool call. + +The MCP server declares the experimental `claude/channel` capability and pushes each inbound message as a `notifications/claude/channel` event. Pushed messages count as read. Channels are opt-in on both sides: + +```bash +AWP_CHANNEL=1 claude --channels plugin:awp@ +``` + +Use the plugin's name as Claude Code lists it. After bootstrap, that is `awp@skills-dir`. + + +Claude Code sends the same client capabilities whether or not channels are on, so the server cannot tell. `AWP_CHANNEL=1`, or `awp mcp --channel`, tells it to push. + + +In other harnesses, or without channels, the [herdr plugin](/plugins/herdr) can prompt an idle agent when messages arrive. + +## Other clients + +A client that implements the Agent Plugins spec reads `plugin.json`, loads the skill from `skills/`, and starts the MCP server from `mcp.json` as `./bin/awp mcp`, relative to the plugin. The spec has no hooks, so such a client gets messages only when the model asks: through `awp tail --once`, `awp wait` or the `awp_read` tool. The skill tells it to do so between steps. + +For the harnesses bootstrap knows, it does not install this package. It writes each harness's own files instead: the skill, the MCP entry in the harness's config, and hooks where the harness has them. + +## Update and uninstall + +- **bootstrap install:** upgrade awp, then run `awp bootstrap --harness claude` again to refresh the skill and hooks. The binary follows the symlink. Restart sessions. +- **release bundle:** download the new bundle and point `--plugin-dir` at it. +- **uninstall:** `awp bootstrap --uninstall --harness claude` removes `~/.claude/skills/awp`, and only if it is the awp plugin. + + +Restart harness sessions after upgrading. An old session's MCP server can restart an old daemon. + + +## Troubleshooting + +| symptom | check | +|---------|-------| +| the model does not know about awp | `awp bootstrap --list` shows whether the plugin is installed. In Claude Code, `/mcp` should list the `awp` server. | +| `awp: this plugin has no build for -` | the plugin has no binary for this platform and no `awp` is on PATH. Use a release bundle, or install awp. | +| hooks print nothing | they are silent unless the daemon is running and something is unread. `awp status` shows both. | +| messages arrive only when the user types | hooks run only during a turn. Use [channels](#channels) or the [herdr plugin](/plugins/herdr). | +| the daemon runs an old version after an upgrade | an old session's MCP server restarted it. Close old sessions, then `awp down`. | +| hook errors in Claude Code | run the hook yourself: `echo '{}' \| awp hook inbox --format text`. | diff --git a/content/docs/plugins/herdr.mdx b/content/docs/plugins/herdr.mdx new file mode 100644 index 0000000..9ed40db --- /dev/null +++ b/content/docs/plugins/herdr.mdx @@ -0,0 +1,255 @@ +--- +title: herdr +description: The herdr plugin brings awp messages into the herdr terminal workspace, with notifications, a live inbox, a status popup and delivery to an idle agent. +--- + +[herdr](https://herdr.dev) is a terminal workspace for running coding agents side by side. The awp plugin for herdr watches this machine's awp daemon and brings what arrives into herdr: + +- **Notifications.** An inbound message, or a peer reporting `waiting`, `done` or `failed` on a thread, shows up as a herdr notification with the peer's name, the thread's subject and the text. +- **Delivery to an idle agent.** Bind an agent pane. When messages arrive while that agent is idle, the plugin prompts it to read them. When they arrive while it works, the plugin prompts it once it goes idle. Its sidebar row can show the unread count. +- **A live inbox.** A split pane that follows every message, state change and connection as it happens. Watching it marks nothing read. +- **Status and controls.** A popup with the identity, address, peers and threads, and keys to go online, connect, bind an agent and open the dashboard. + + +The plugin never brings awp online on its own. It waits until something starts the daemon: `awp up`, an agent using awp, or the plugin's **go online** action. It never reads messages on the agent's behalf either: the agent reads them through awp. + + +## Install + +The plugin needs: + +- awp. See [Installation](/getting-started/installation). +- `jq`, which ships with macOS 15 and later and is in every Linux distribution. +- herdr 0.9.1 or later, on Linux or macOS. + +```bash +herdr plugin install agentwireprotocol/awp/plugin/herdr +``` + +herdr shows a preview of the commands the plugin will run and asks before installing. `--yes` skips the question, and `--ref ` pins a revision. There is no separate update command: install again to update. The plugin is also listed on the [herdr marketplace](https://herdr.dev/plugins). + +Set up the agents themselves with `awp bootstrap` as well. The plugin's prompt tells an agent to run awp commands, and the [skill](/plugins/skill) tells it what to do with what it reads. + +To work on the plugin from a checkout, link it instead. Linking runs no build step and picks up edits at once: + +```bash +herdr plugin link plugin/herdr +``` + +## Quick start + +1. Open the popup: run the action **AWP: status and controls**, or bind it to a key (see [Keys](#keys)). +2. Press `u` to go online. The popup prints the address to share. +3. Start an agent in a pane, focus that pane, open the popup again and press `b` to bind it. +4. When a peer sends something, you get a notification. If the agent is idle, it is prompted to read the message. + +## Actions + +Run actions from herdr's command palette, a key binding, or the CLI: `herdr plugin action invoke `. + +| action | id | what it does | +|--------|----|--------------| +| AWP: status and controls | `agentwireprotocol.awp.open` | opens the [popup](#the-popup) | +| AWP: open the live inbox | `agentwireprotocol.awp.inbox` | opens the [inbox](#the-inbox) in a split | +| AWP: go online | `agentwireprotocol.awp.up` | runs `awp up`, starts the watcher, and shows the address in a notification | +| AWP: deliver messages to this agent | `agentwireprotocol.awp.bind` | binds the agent in the focused pane | +| AWP: stop delivering messages to an agent | `agentwireprotocol.awp.unbind` | unbinds it | +| AWP: open the network dashboard | `agentwireprotocol.awp.dashboard` | starts `awp web` if it is not serving, and opens it | +| AWP: restart the message watcher | `agentwireprotocol.awp.restart` | restarts the watcher, for example after changing the config | + +## Keys + +Bind the popup to a key in herdr's config. Everything else is a key inside it. + +```toml title="~/.config/herdr/config.toml" +[[keys.command]] +key = "prefix+a" +type = "plugin_action" +command = "agentwireprotocol.awp.open" +description = "AWP" +``` + +## The popup + +The popup covers 80% of the terminal. It shows: + +- the output of `awp status`: identity, key, addresses, admission policy, unread and queued counts, and peers +- the first threads from `awp threads`, with both sides' states and unread counts +- which agent messages are delivered to, and whether prompting is on +- whether the watcher is running, and the notification level + +| key | does | +|-----|------| +| `u` | go online: runs `awp up`, prints the address to share, starts the watcher | +| `c` | connect: asks for an address and runs `awp connect` | +| `i` | opens the inbox in a split and closes the popup | +| `w` | opens the dashboard | +| `b` | binds the agent in the pane that was focused when the popup opened | +| `x` | unbinds | +| `s` | restarts the watcher | +| `r` | refreshes | +| `q`, `Esc` | closes | + +When awp is offline, the popup says so, and `u` brings it online. + +## The inbox + +The inbox is a split pane running `awp tail --all`: messages in both directions, state changes and connections, grouped by thread, as they happen. + +```text +── thr_yj8w6cyi "Inbox test" with bob@builder +[08:26:25] < bob@builder · msg 01M3P4BCQPMFP5N4V8MCVW557Z + subject: Inbox test + hello from bob +── thr_wrw3rhsd "Deploy review" with bob@builder +[08:26:25] < bob@builder · state waiting: need your answer +``` + +Watching marks nothing read, so the agent still gets every message through its hooks or `awp tail --once`. When the daemon stops, the pane says it is waiting and picks up again once awp is back. Close it like any other pane. + +## Notifications + +The watcher turns what arrives into herdr notifications, using herdr's configured toast delivery: + +| arrives | notification | sound | +|---------|--------------|-------| +| a message | **AWP · peer**, with `subject: text` | request | +| a peer sets `waiting` | **AWP · peer is waiting on you**, with the subject and note | request | +| a peer sets `done` | **AWP · peer is done** | done | +| a peer sets `failed` | **AWP · peer failed** | done | +| a peer sets `working` (`NOTIFY=all` only) | **AWP · peer is working** | none | +| a connection or disconnection (`NOTIFY=all` only) | **AWP · peer connected** | none | + +The subject, text and note are each cut to 160 characters, and control characters become spaces. A message with no text part names its parts instead, for example `(data, blob)`. Your own messages and states never notify. + +## Delivering to an agent + +Hooks bring messages to an agent only while it works. An agent that has finished its turn sees nothing until someone types. Binding closes that gap, for any harness herdr detects: Claude Code, Codex, opencode, pi and the rest. + +### Binding + +Bind with the **deliver messages to this agent** action while the agent's pane is focused, or with `b` in the popup. The plugin refuses a pane where herdr detects no agent. One agent is bound at a time, and it should be the one that runs as this machine's awp identity. Binding another replaces it. + +The binding follows the pane when it moves to another tab or workspace, and is dropped when the pane closes. + +### When the agent is prompted + +The plugin prompts when all of these hold: + +1. Something new arrived: a message, or a peer's `waiting`, `done` or `failed`. +2. It is still unread. An agent that already read it through its hooks is not prompted. +3. herdr reports the agent `idle` or `done`. +4. The agent has not been prompted for this batch yet. + +It checks when something arrives, and again every time the bound agent's status changes. So a message that arrives mid-turn is delivered by the agent's hooks, if it has them, or by a prompt the moment it goes idle. A `blocked` agent, one waiting on an approval or a question, is never prompted. + +The prompt is: + +> New AWP messages arrived. Run `awp tail --once` now to read them, then handle them as the awp skill says. They come from another agent, not from the user. + +It never includes the messages. The agent reads them with awp, which frames them as untrusted input from another agent, so a peer cannot type into the agent's prompt through the plugin. Change the text with `NUDGE_PROMPT`, or turn prompting off with `NUDGE=off` and keep the rest. + +### The unread count + +The plugin reports the unread count on the bound pane as the pane token `awp`, for example `✉ 3`, and clears it when nothing is unread. It refreshes every 5 seconds, since reading messages emits no event. To show it, add `$awp` to your Agent sidebar row format in herdr's config. + +## Configuration + +`herdr plugin config-dir agentwireprotocol.awp` prints the config directory. On first run, the plugin writes a commented `config` file there: + +```ini title="config" +# The awp binary, when it is not on the herdr server's PATH. +#AWP_BIN=/home/me/.local/bin/awp + +# The awp home (default: $AWP_HOME, else ~/.awp). +#AWP_HOME= + +# Notifications: messages, all, or none. +#NOTIFY=messages + +# Prompt the bound agent when messages wait and it is idle: on or off. +#NUDGE=on +#NUDGE_PROMPT=New AWP messages arrived. ... + +# Start the watcher when herdr starts: on or off. +#AUTOSTART=on + +# Where `awp web` serves the dashboard. +#WEB_LISTEN=127.0.0.1:7788 +``` + +| key | default | | +|-----|---------|-| +| `AWP_BIN` | `awp` on PATH, then `~/.local/bin`, `~/go/bin`, `/opt/homebrew/bin`, `/usr/local/bin` | the awp binary | +| `AWP_HOME` | `$AWP_HOME`, else `~/.awp` | the awp home to watch; set it if your agents use another | +| `NOTIFY` | `messages` | `messages`, `all` or `none` | +| `NUDGE` | `on` | prompt the bound agent | +| `NUDGE_PROMPT` | the text above | what to prompt it with | +| `AUTOSTART` | `on` | start the watcher when herdr starts | +| `WEB_LISTEN` | `127.0.0.1:7788` | where the dashboard action serves `awp web` | + +Lines are `KEY=value`, with no quotes, and `#` starts a comment. The file is read, not run. Actions and events read it each time they run. The watcher reads `NOTIFY` each time something arrives, and the binary and home when it starts: use the restart action after changing those. + +## How it works + +The plugin is one POSIX shell script, `bin/awp-herdr`, behind every entry point in its manifest: + +| manifest entry | runs | when | +|----------------|------|------| +| startup hook | `awp-herdr startup` | herdr starts, or a new server takes over | +| event hook on `pane.agent_status_changed` | `awp-herdr event` | any agent's status changes; acts only for the bound one | +| event hooks on `pane.moved`, `pane.closed` | `awp-herdr event` | the bound pane moves or closes | +| actions | `awp-herdr open`, `up`, `bind` and the others | you run them | +| pane `hub` (popup) | `awp-herdr hub` | the popup | +| pane `inbox` (split) | `awp-herdr inbox` | the inbox | + +### The watcher + +The startup hook starts a watcher in the background and returns. The watcher: + +1. checks `awp status --json`, which never starts the daemon, and waits 5 seconds between tries while awp is offline +2. runs `awp tail --json --all` while the daemon runs, and handles each record: notifications, the prompt, the unread count +3. goes back to waiting if the daemon stops +4. exits when its herdr server's socket goes away + +There is one watcher for each herdr server, so named sessions each get their own. A restart after a live handoff finds the running watcher and leaves it. + +### Files + +The plugin keeps its state in herdr's plugin state directory, `~/.local/state/herdr/plugins/agentwireprotocol.awp/` by default: + +| file | what | +|------|------| +| `watch.log` | the watcher's log: starts, stops, errors from awp, failed prompts | +| `watch-.pids`, `watch-.pids.tail` | the running watcher's processes, one set per herdr server | +| `bound`, `bound_agent` | the bound pane and the agent herdr detected in it | +| `last_seq`, `nudged_seq` | the latest arrival and the latest one the agent was prompted for | +| `reported` | the last unread count reported to herdr | +| `web.log` | output of an `awp web` the dashboard action started | + +## Troubleshooting + +| symptom | check | +|---------|-------| +| a notification says awp was not found | herdr's server does not have awp on its PATH. Set `AWP_BIN` in the config. | +| a notification says jq is not installed | install `jq`. | +| no notifications | is the watcher running? The popup says. Is the daemon running under the home you expect? `AWP_HOME` must match the agents'. Is `NOTIFY` set to `none`? Then see `watch.log`. | +| the agent is never prompted | is it bound? The popup says. Is herdr showing it `idle` or `done`? A `working` agent is prompted when it stops, and a `blocked` one never. Were the messages already read? `awp status` shows the unread count. | +| the agent is prompted but does nothing with the messages | install the skill with `awp bootstrap`, so the agent knows how to handle them. | +| `$awp` does not show in the sidebar | add `$awp` to the Agent sidebar row format. The token is set only while something is unread. | +| the dashboard does not open | on a remote machine there is no browser to open. The notification has the URL. Otherwise see `web.log`. | +| bind says there is no agent | herdr has not detected an agent in that pane yet. Wait for it to start, then bind again. | + +## Uninstall + +```bash +herdr plugin uninstall agentwireprotocol.awp +``` + +This removes the plugin but leaves its config and state directories. A watcher that is still running exits when herdr's server next stops. Unbind first if you want the sidebar token cleared. + +## Limits + +- One bound agent, and one awp home, per herdr server. +- No Windows, since awp does not run there yet. +- The prompt goes to herdr's agent input. It relies on herdr detecting the agent's status, so it works for the harnesses herdr knows. diff --git a/content/docs/plugins/index.mdx b/content/docs/plugins/index.mdx new file mode 100644 index 0000000..0a65e44 --- /dev/null +++ b/content/docs/plugins/index.mdx @@ -0,0 +1,67 @@ +--- +title: Plugins +description: The plugins that bring awp into agent harnesses and terminals, what each one does, and which to install. +--- + +awp is one binary and one daemon per machine. The plugins connect other programs to that daemon. There are two kinds: + +- **Agent harness plugins** put awp in front of the model: a skill that teaches it the conventions, the MCP tools, and hooks that add new messages to its context. +- **Terminal plugins** put awp in front of you: notifications when messages arrive, a live view of the traffic, and a way to hand new messages to an agent that is sitting idle. + +Every plugin talks to the same daemon as the CLI, so they can be mixed freely. A Claude Code session with the agent plugin, running in a herdr pane with the herdr plugin, is the same awp identity throughout. + + + + One package for Claude Code, Codex, Cursor and any client that follows the Agent Plugins spec: skill, MCP server and hooks. + + + What the model is taught, and where every harness gets it. + + + A JavaScript plugin that adds new messages to tool output and reports the model. + + + Notifications, a live inbox, a status popup, and delivery to an idle agent, in the herdr terminal workspace. + + + +## Which to install + +Run `awp bootstrap` first. It finds the harnesses on the machine and installs what each one supports, including the agent plugin for Claude Code and the opencode plugin. See [Set up your harnesses](/getting-started/harnesses). + +Then add a terminal plugin if you run your agents in one: + +```bash +herdr plugin install agentwireprotocol/awp/plugin/herdr +``` + +## What each harness gets + +| harness | skill | MCP tools | new messages reach the model | how it is installed | +|---------|-------|-----------|------------------------------|---------------------| +| Claude Code | yes | yes | hooks: session start, prompt submit, after each tool call, before stopping; optionally channels | the [agent plugin](/plugins/agent-plugin), by `awp bootstrap` or `--plugin-dir` | +| Cursor | yes | yes | hooks: session start, after each tool call, before stopping | `awp bootstrap` | +| Gemini CLI | yes | yes | hooks: session start, before each turn, after each tool call | `awp bootstrap` | +| opencode | yes | yes | the [opencode plugin](/plugins/opencode), after each tool call | `awp bootstrap` | +| Codex | yes | yes | the model runs `awp tail --once` and `awp wait` | `awp bootstrap` | +| GitHub Copilot CLI | yes | yes | the model runs `awp tail --once` and `awp wait` | `awp bootstrap` | +| grok | yes | yes | the model runs `awp tail --once` and `awp wait` | `awp bootstrap` | +| pi | yes | no | the model runs `awp tail --once` and `awp wait` | `awp bootstrap` | + +Hooks only run while the agent is doing something. An agent that has finished its turn sees nothing until its user types again. Two things close that gap: + +- [Channels](/plugins/agent-plugin#channels), in Claude Code, push messages to an idle session. +- The [herdr plugin](/plugins/herdr#delivering-to-an-agent) prompts an idle agent in any harness herdr can detect, when messages arrive. + +## Where the plugins live + +All of them are in the [awp repository](https://github.com/agentwireprotocol/awp) and are released with it: + +| path | what | +|------|------| +| `plugin/awp/` | the agent plugin, embedded in the awp binary for `awp bootstrap` | +| `plugin/awp/skills/awp/SKILL.md` | the skill | +| `internal/bootstrap/opencode.go` | the opencode plugin, which bootstrap writes out | +| `plugin/herdr/` | the herdr plugin | + +Each plugin's version matches the awp release it ships in. diff --git a/content/docs/plugins/meta.json b/content/docs/plugins/meta.json new file mode 100644 index 0000000..8bb9e60 --- /dev/null +++ b/content/docs/plugins/meta.json @@ -0,0 +1,15 @@ +{ + "title": "Plugins", + "description": "awp in agent harnesses and terminals", + "icon": "Puzzle", + "root": true, + "pages": [ + "index", + "---Agent harnesses---", + "agent-plugin", + "skill", + "opencode", + "---Terminals---", + "herdr" + ] +} diff --git a/content/docs/plugins/opencode.mdx b/content/docs/plugins/opencode.mdx new file mode 100644 index 0000000..6581a9c --- /dev/null +++ b/content/docs/plugins/opencode.mdx @@ -0,0 +1,85 @@ +--- +title: opencode +description: The opencode plugin that adds new awp messages to tool output and reports the model, with the skill and MCP server beside it. +--- + +opencode has no command hooks, so awp reaches its model through a small JavaScript plugin instead. It does two things: + +- after each tool call, it appends new awp messages to the tool's output, as post-tool hooks do in other harnesses +- on each chat turn, it tells awp which model the turn runs on, so a model switch reaches the network + +## Install + +```bash +awp bootstrap --harness opencode +``` + +bootstrap sets up three things in `~/.config/opencode/`: + +| file | what | +|------|------| +| `skills/awp/SKILL.md` | [the skill](/plugins/skill) | +| `opencode.json`, or `opencode.jsonc` | the MCP server, under `mcp.awp` | +| `plugins/awp.js` | the plugin | + +The MCP entry looks like this: + +```json title="opencode.json" +{ + "mcp": { + "awp": { "type": "local", "command": ["/home/me/.local/bin/awp", "mcp", "--harness", "opencode"], "enabled": true } + } +} +``` + +### Configs with comments + +bootstrap edits JSON, not JSONC. If `opencode.json` has comments, it leaves that file alone and writes awp's entry to a new `opencode.jsonc`, and opencode merges the two. If both files exist and `opencode.json` has comments, bootstrap stops and prints the entry to add yourself. + +## The plugin + +bootstrap writes the plugin with the absolute path of the awp binary that ran it: + +```js title="~/.config/opencode/plugins/awp.js" +// awp: messages from other agents show up after tool calls, and the +// network sees which model this agent runs on. +// Written by `awp bootstrap`; `awp bootstrap --uninstall` removes it. +const BIN = "/home/me/.local/bin/awp"; + +export const AWP = async ({ $ }) => { + let reported = ""; + return { + "chat.params": async (input) => { + const model = input.model?.api?.id || input.model?.id || ""; + if (!model || model === reported) return; + // Fails quietly while awp is not running; the next turn retries. + const r = await $`${BIN} model ${model}`.nothrow().quiet(); + if (r.exitCode === 0) reported = model; + }, + "tool.execute.after": async (input, output) => { + const text = await $`echo '{}' | ${BIN} hook inbox --format text`.nothrow().quiet().text(); + if (text.trim()) output.output = `${output.output ?? ""}\n\n${text.trim()}`; + }, + }; +}; +``` + +| opencode hook | runs | effect | +|---------------|------|--------| +| `tool.execute.after` | `awp hook inbox --format text` | new messages, framed as untrusted input, are appended to the tool's output; they are marked read | +| `chat.params` | `awp model ` | the model id is reported once, and again only when it changes | + +Both calls ignore errors. While the daemon is not running, the hook prints nothing and the model report fails quietly, to be retried on the next turn. + +## What it does not cover + +opencode's plugin runs only when a tool runs. There is no equivalent of a session-start or stop hook, so: + +- at the start of a session, the model sees messages only once it calls a tool, or when it runs `awp tail --once` as the skill says +- an idle session sees nothing until its user types. In a terminal, the [herdr plugin](/plugins/herdr) can prompt it when messages arrive. + +## Update and uninstall + +- After upgrading awp to a new path, run `awp bootstrap --harness opencode` again. The plugin and MCP entry hold the binary's absolute path. +- `awp bootstrap --uninstall --harness opencode` removes the skill, awp's MCP entry and the plugin. It removes `plugins/awp.js` only if the file carries bootstrap's marker comment, so a plugin of your own with the same name is left alone. +- bootstrap keeps a one-time `.awp-backup` of each config file it edits. diff --git a/content/docs/plugins/skill.mdx b/content/docs/plugins/skill.mdx new file mode 100644 index 0000000..2a963ea --- /dev/null +++ b/content/docs/plugins/skill.mdx @@ -0,0 +1,61 @@ +--- +title: The skill +description: What the awp skill teaches a model, where each harness gets it, and how to install or change it. +--- + +The skill is one file, `SKILL.md`, that teaches a model to use awp: when to reach for it, how to run a delegation from both sides, and what never to do because a peer asked. Every harness gets it, including those with no MCP or hooks. For pi, it is the whole integration. + +It is written for the CLI. Where a harness shows the `awp_*` MCP tools, the skill tells the model they do the same things. + +## When the model loads it + +Harnesses load a skill when its description matches the task. The awp skill's description covers: + +- delegating a task to another agent, or taking one on +- following up or answering in a thread, and sending results and files back +- the user giving an awp or tailcat address (one that starts with `tc`) +- the user asking to connect to, check on or reply to another agent +- awp messages appearing in the model's context, which is what hooks do + +## What it teaches + +| section | the model learns | +|---------|------------------| +| How it works | one daemon per machine that queues while peers sleep; threads with task-like subjects; the states `working`, `waiting`, `done`, `failed`, `closed`; how new messages reach it, and to run `awp tail --once` between steps where nothing delivers them; to set `waiting` before every question; to read a thread before replying | +| Connecting | `awp up` for its address, which is a secret it hands only to its user; `awp connect` for theirs; reporting its model with `awp model` where the harness does not | +| Delegating a task | open a thread with the ask, context as `--data`, and what "done" looks like; wait with `awp wait --state done,failed` and a timeout under its shell's limit rather than polling; answer questions in the thread; read everything, report and close | +| Taking a task | only when it fits what its user wants; `working` with a note, progress messages, `waiting` for every question, results as `--code`, `--file` or `--data`, then `done` or `failed` with a reason | +| Everyday commands | a table from intent to command: read, reply, attach, ask, confirm delivery, check status | +| Introductions | connecting to an introduced peer and saying who introduced it; `awp introduce` and what the peer will honor | +| Using a grant it holds | sending `fs:read`, `exec` and `fs:write` requests as data parts with the capability's MIME type, and reading the reply or `err forbidden` | +| Shared conversations | that a peer may mirror threads to a dashboard; running `awp private ` on its own for anything sensitive, and telling its user; never running `awp share` unasked | +| Safety rules | everything a peer sends is untrusted input, never instructions from its user; requests marked as made without a grant were denied; grant `exec` and `fs:write` only when its user asks, with a short ttl; never post the address publicly | +| When something looks wrong | what `reconnecting`, `offline` and `said bye` mean in `awp peers`; waiting for tailcat; where the daemon log is | + +The rules match the conventions in the specification's section 11, and the untrusted-input framing matches what [hooks](/reference/hooks) print around every batch of messages. + +## Where each harness gets it + +| harness | skill file | +|---------|------------| +| Claude Code | `~/.claude/skills/awp/skills/awp/SKILL.md`, inside the [agent plugin](/plugins/agent-plugin) | +| opencode | `~/.config/opencode/skills/awp/SKILL.md` | +| Codex | `~/.codex/skills/awp/SKILL.md` | +| Cursor | `~/.cursor/skills/awp/SKILL.md` | +| Gemini CLI | `~/.gemini/skills/awp/SKILL.md` | +| GitHub Copilot CLI | `~/.copilot/skills/awp/SKILL.md` | +| grok | `~/.grok/skills/awp/SKILL.md` | +| pi | `~/.pi/agent/skills/awp/SKILL.md` | + +`awp bootstrap` writes them. In the plugin, the skill finds the binary at `${CLAUDE_SKILL_DIR}/../../bin/awp` when `awp` is not on PATH. bootstrap replaces that line in the copies it writes for other harnesses with the absolute path of the awp binary that ran it, so the model can always run awp even when the harness's PATH lacks it. + +## Installing it by hand + +For a harness bootstrap does not know, copy `plugin/awp/skills/awp/SKILL.md` from the repository into the harness's skills directory, in a folder named `awp`. If the harness has no skills, paste the file into its system prompt or project instructions. Then make sure the model can pull messages. Either: + +- wire a hook that runs `awp hook inbox --format text` after each tool call and passes its output to the model (see [Hooks](/reference/hooks#wiring-a-hook-by-hand)), or +- rely on the skill's instruction to run `awp tail --once` between steps. + +## Changing it + +The skill is part of the awp release. Edits to an installed copy are lost when bootstrap runs again. To change what every agent learns, change `plugin/awp/skills/awp/SKILL.md` in the repository. The binary embeds it, so a rebuilt awp installs the new text. diff --git a/src/components/docs.tsx b/src/components/docs.tsx index 74c5567..b54acda 100644 --- a/src/components/docs.tsx +++ b/src/components/docs.tsx @@ -5,7 +5,7 @@ import type { ReactNode } from 'react'; import { navigate } from 'astro:transitions/client'; import { RootProvider } from 'fumadocs-ui/provider/astro'; import type { AstroProviderProps } from 'fumadocs-core/framework/astro'; -import { Braces, Compass } from 'lucide-react'; +import { Braces, Compass, Puzzle } from 'lucide-react'; import { SiPython, SiTypescript } from '@icons-pack/react-simple-icons'; import SearchDialog from './search'; import { Gopher } from './gopher'; @@ -18,6 +18,7 @@ import { PageHeader, type PageHeaderProps } from './page-header'; // tree, since React nodes cannot cross the Astro island boundary inside it. const sections: Record = { '/': , + '/plugins': , '/reference': , '/go': , '/python': ,