@itsaplan/runner 0.5.3 → 0.7.0

package/README.md

@@ -11,6 +11,9 @@ This package runs such agents on your own machine — one, or several at once.
   Pi, and Oh My Pi (`omp`). Each preset sets the unattended flags and the session resume.
 - Runs your own `command` instead, if you prefer. The command takes the task on stdin.
 - Answers the agent's chat. Sends the text and the tool calls while the CLI prints them.
+- Sends the messages and the tool calls of a queued run to the issue while the run works.
+- Receives the tasks on a port instead of polling, for an agent whose Connection is
+  Endpoint. See [Receiving tasks on a port](#receiving-tasks-on-a-port).
 
 ## Quick start
 
@@ -105,9 +108,8 @@ on stdin. The runner keeps no session for it, because it does not know how to re
 
 ## Several agents on one runner
 
-One key is one agent. A runner set up the way you want it can serve several of them at
-once: it polls for each key on its own, and every agent uses the coding agent, the working
-directory and the arguments the file already gives.
+One key is one agent. One runner can serve several agents. It polls for each key
+separately, and every agent uses the `agent`, `cwd` and `args` from the file.
 
 ```json
 {
@@ -118,13 +120,13 @@ directory and the arguments the file already gives.
 }
 ```
 
-Nothing else changes: the runner gives each command its own `ITSAPLAN_API_KEY`, so the one
-MCP config in that folder works for all of them.
+The runner gives each command its own `ITSAPLAN_API_KEY`, so one MCP config in that
+folder works for all agents.
 
-Use `agents` instead of `apiKeys` where an agent needs something of its own. A field an
-entry sets replaces the shared one, and it inherits every field it leaves out, except its
-`apiKey`, which every entry sets itself. `name` is what the runner's log lines call that
-agent; without it they number the agents `#1`, `#2` in the order of the file.
+Use `agents` instead of `apiKeys` when an agent needs its own settings. Each entry sets
+its own `apiKey`. The other fields that an entry sets replace the shared ones, and the
+entry inherits the rest. `name` is the agent's label in the log. Without it, the log
+numbers the agents `#1`, `#2` in the order of the file.
 
 ```json
 {
@@ -142,12 +144,91 @@ agent; without it they number the agents `#1`, `#2` in the order of the file.
 }
 ```
 
-`concurrency` counts per agent and per feed, so a runner with three agents at
-`concurrency: 2` can have six queued runs in flight and six chat answers alongside them,
-each one a coding agent CLI of its own. The environment variables and the command-line
-options describe every agent at once; an entry has priority over them.
+`concurrency` counts per agent and per feed. A runner with three agents at
+`concurrency: 2` can run six queued runs and six chat answers at once, each in its own
+CLI process.
 
-An agent whose key the instance refuses stops on its own, and the others keep working.
+If the instance refuses the key of an agent, that agent stops. The other agents continue.
+
+## Receiving tasks on a port
+
+By default the runner polls the instance for tasks. With `listen`, the instance sends each
+task to the runner when the task is created. The runner then does not poll.
+
+Use `listen` for a runner on a server that the instance can reach. On a laptop behind a
+router, use polling. Polling needs no setup. The chat is as fast with polling, because a
+chat claim waits on the server until a message comes.
+
+**1.** In the agent's settings, open Connection and select Endpoint. Enter the public
+HTTPS address of the runner's port (see [Reaching the port](#reaching-the-port)), and
+save. Copy the signing secret.
+
+**2.** Add `listen` and `signingSecret` to `itsaplan-runner.json`:
+
+```json
+{
+  "url": "https://plan.example.com",
+  "apiKey": "the agent's key",
+  "agent": "claude",
+  "listen": 4000,
+  "signingSecret": "whsec_…"
+}
+```
+
+**3.** Start the runner. It logs `listening on port 4000`. In the agent's settings, click
+Send test. The result must be `200`.
+
+The runner answers each task immediately. Then it runs the task as it runs a polled task,
+with the same command, heartbeats and result. The rules for a request:
+
+- The runner accepts only a `POST` request signed with the secret of one of its agents.
+- It refuses a request whose signature time is more than five minutes from its clock.
+- If the instance sends a task again while the task runs, the runner does not start it a
+  second time.
+
+Several agents can use one port. The runner identifies the agent by the secret, so each
+agent needs its own `signingSecret`. Put the agents in `agents`:
+
+```json
+{
+  "url": "https://plan.example.com",
+  "agent": "claude",
+  "listen": 4000,
+  "agents": [
+    { "apiKey": "the first agent's key", "signingSecret": "whsec_first…" },
+    { "apiKey": "the second agent's key", "signingSecret": "whsec_second…" }
+  ]
+}
+```
+
+In the same file, the runner polls for each agent that has no `listen`.
+
+### Reaching the port
+
+The runner serves plain HTTP. In production, the instance requires HTTPS. Put a tunnel or a
+reverse proxy in front of the port:
+
+- **Reverse proxy** on a server with a domain. Caddy gets the certificate automatically:
+
+  ```
+  runner.example.com {
+    reverse_proxy localhost:4000
+  }
+  ```
+
+- **Cloudflare Tunnel.** `cloudflared tunnel --url http://localhost:4000` prints a
+  `trycloudflare.com` address. The address changes each time the tunnel starts, and then
+  you must change the agent's URL too. A named tunnel on your own domain keeps the same
+  address.
+- **ngrok.** `ngrok http 4000`. A static domain in your ngrok account keeps the same
+  address.
+- **Tailscale Funnel.** `tailscale funnel 4000` publishes the port at the machine's
+  `ts.net` address.
+
+On a private network without a tunnel, add the runner's host to `SSRF_ALLOWED_HOSTS` on
+the instance. That host must also use HTTPS. When `NODE_ENV` on the instance is not
+`production` or `test`, the instance also accepts `http://` and private addresses, for
+example `http://localhost:4000`.
 
 ## Settings
 
@@ -161,21 +242,23 @@ npx -y @itsaplan/runner /path/to/config.json
 The environment variables have priority over the file. The command-line options have
 priority over both. An `agents` entry has priority over all three, for the fields it sets.
 
-| Field            | Environment variable        | Default            | What it does                                                       |
-| ---------------- | --------------------------- | ------------------ | ------------------------------------------------------------------ |
-| `url`            | `ITSAPLAN_URL`              | required           | Your Itsaplan instance                                             |
-| `apiKey`         | `ITSAPLAN_API_KEY`          | required           | The external agent's key. Replaced by `apiKeys` or `agents`        |
-| `apiKeys`        |                             | —                  | Several keys, all with these settings. Not with `agents`           |
+| Field            | Environment variable        | Default            | What it does                                                           |
+| ---------------- | --------------------------- | ------------------ | ---------------------------------------------------------------------- |
+| `url`            | `ITSAPLAN_URL`              | required           | Your Itsaplan instance                                                 |
+| `apiKey`         | `ITSAPLAN_API_KEY`          | required           | The external agent's key. Replaced by `apiKeys` or `agents`            |
+| `apiKeys`        |                             | —                  | Several keys, all with these settings. Not with `agents`               |
 | `agents`         |                             | —                  | Several agents, each with its own key and settings. Not with `apiKeys` |
-| `agent`          | `ITSAPLAN_AGENT`            | —                  | The coding agent to run                                            |
-| `args`           |                             | `[]`               | Arguments added after the preset's                                 |
-| `command`        | `ITSAPLAN_COMMAND`          | —                  | Your own command, instead of `agent`                               |
-| `cwd`            | `ITSAPLAN_CWD`              | where you start it | Working directory for the command                                  |
-| `env`            |                             | `{}`               | Extra variables for the command                                    |
-| `concurrency`    | `ITSAPLAN_CONCURRENCY`      | `1`                | Tasks at once, per agent. Queued runs and chat answers count apart |
-| `pollIntervalMs` | `ITSAPLAN_POLL_INTERVAL_MS` | `3000`             | Wait after an empty queue. Minimum 1000                            |
-| `timeoutMs`      | `ITSAPLAN_TIMEOUT_MS`       | `1800000`          | Time before the runner stops a task                                |
-| `outputFormat`   | `ITSAPLAN_OUTPUT_FORMAT`    | the preset's       | How the runner reads a chat answer                                 |
+| `agent`          | `ITSAPLAN_AGENT`            | —                  | The coding agent to run                                                |
+| `args`           |                             | `[]`               | Arguments added after the preset's                                     |
+| `command`        | `ITSAPLAN_COMMAND`          | —                  | Your own command, instead of `agent`                                   |
+| `cwd`            | `ITSAPLAN_CWD`              | where you start it | Working directory for the command                                      |
+| `env`            |                             | `{}`               | Extra variables for the command                                        |
+| `concurrency`    | `ITSAPLAN_CONCURRENCY`      | `1`                | Tasks at once, per agent. Queued runs and chat answers count apart     |
+| `pollIntervalMs` | `ITSAPLAN_POLL_INTERVAL_MS` | `3000`             | Wait after an empty queue. Minimum 1000                                |
+| `timeoutMs`      | `ITSAPLAN_TIMEOUT_MS`       | `1800000`          | Time before the runner stops a task                                    |
+| `outputFormat`   | `ITSAPLAN_OUTPUT_FORMAT`    | the preset's       | How the runner reads the output. See [The output](#the-output)         |
+| `listen`         | `ITSAPLAN_LISTEN`           | —                  | Port that receives the tasks. The runner does not poll for the agent   |
+| `signingSecret`  | `ITSAPLAN_SIGNING_SECRET`   | —                  | The agent's signing secret. Required with `listen`                     |
 
 Set `agent` or `command`. With the environment you need no file at all:
 
@@ -190,8 +273,8 @@ npx -y @itsaplan/runner --agent claude
 
 The server writes the task text. The text states what occurred, what to do, and to post
 the result as a comment on the issue. Your own `command` receives the text on **stdin**. A
-preset gives it to its CLI in the way that CLI accepts it: on stdin for `claude` and
-`codex`, as an argument for `antigravity`, `copilot`, `opencode`, `pi` and `omp`.
+preset gives it to its CLI in the way that CLI accepts it: on stdin for `claude`, `codex`
+and `pi`, as an argument for `antigravity`, `copilot`, `opencode` and `omp`.
 
 The agent reads all other data through the MCP server at `$ITSAPLAN_URL/mcp`. The agent
 sends `$ITSAPLAN_API_KEY` as a bearer token, and acts as its own user with its role.
@@ -206,12 +289,11 @@ Every run holds these variables:
 | `ITSAPLAN_API_KEY`       | the agent's key, for the API and the MCP server                             |
 | `ITSAPLAN_TRIGGER`       | `mention`, `delegation`, `field`, `schedule`, `manual`, `status`, or `chat` |
 | `ITSAPLAN_SYSTEM_PROMPT` | the context of the run, for a command that takes a system prompt            |
-| `ITSAPLAN_TIMEOUT_MS` | the effective task timeout in milliseconds, including per-agent overrides |
+| `ITSAPLAN_TIMEOUT_MS`    | the task timeout in milliseconds                                            |
 
-Custom commands can read `ITSAPLAN_TIMEOUT_MS` to configure their own execution timeout.
-The runner supplies the resolved `timeoutMs`, overriding any inherited value or value in
-`env`. Its timer starts when the command is spawned, so startup and waiting inside the
-command count toward the same limit.
+A command can read `ITSAPLAN_TIMEOUT_MS` to set its own timeout. The value is the
+`timeoutMs` of that agent, and it replaces a value from the environment or from `env`.
+The time starts when the command starts.
 
 A queued run adds three more:
 
@@ -230,25 +312,46 @@ A chat message adds three others in their place, and `ITSAPLAN_TRIGGER` is `chat
 | `ITSAPLAN_SESSION_ID` | the coding agent's session to resume. Empty for the first message |
 
 The task text of a chat message includes the conversation, unless a session holds it. See
-Sessions below.
+[Sessions](#sessions).
 
-### The result
+## The output
 
-Exit code `0` is a success. Any other code is a failure. The end of stderr then becomes
-the error. Stdout becomes the run's output in both cases.
+Exit code `0` is a success. Any other code is a failure, and the end of stderr becomes the
+error.
 
-## Chat
-
-The runner streams the answer to the chat while the command runs. It reports the tool
-calls with the answer. `outputFormat` tells the runner how to read the output:
+`outputFormat` tells the runner how to read stdout:
 
-- `text` — all the output is the answer.
+- `text` — all of stdout is the answer.
 - `claude-stream-json`, `codex-jsonl`, `opencode-json`, `antigravity-stream-json`,
   `copilot-json`, `pi-json` — the event stream of that CLI. `pi` and `omp` both use
-  `pi-json`.
+  `pi-json`. The runner reads the text and the tool calls from it.
 
 A preset sets `outputFormat` for you. Set it yourself only with your own `command`. If the
-output does not agree with the format, the runner sends the output as plain text.
+output does not agree with the format, the runner uses the output as plain text.
+
+A queued run reports one answer as its output. With an event stream format, the answer is
+the text that the agent wrote after its last tool call.
+
+### Run transcripts
+
+While a queued run works, the runner sends the agent's messages and tool calls to the
+instance. The issue shows them as the run's transcript.
+
+- The tool calls need an event stream format. With `text`, the transcript holds only the
+  output.
+- With `codex-jsonl`, the run shows an **Open in Codex** link. The link opens the session
+  only where that session is: in the Codex app of the viewer, or on a connected host. The
+  link does not copy the session.
+- The instance keeps up to 2,000 events or 1 MB for each attempt, and marks a transcript
+  that it cut. The cut does not change the result of the run.
+- If the last upload fails with a network or server error, the runner tries it one more
+  time. Then it reports the result of the command, even with an incomplete transcript.
+  Any other refusal fails the run.
+
+## Chat
+
+The runner streams the answer to the chat while the command runs. It sends the tool calls
+with the answer.
 
 ### Sessions
 
@@ -264,8 +367,7 @@ Without a session the server sends the last 20 messages of the conversation as p
 ## Requirements
 
 - **Node 20 or later.**
-- **An It's a Plan instance 0.10.0 or later.** The chat needs 0.11.0. An older instance
-  gives the runner only the queued runs.
+- **An It's a Plan instance 1.7.0 or later.**
 - **An external agent in your project.** The runner authenticates with its API key.
 - **The coding agent, installed and signed in on the same machine.** The runner starts the
   CLI as you, but it cannot sign in for you.