@itsaplan/runner 0.1.0 → 0.2.1

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2026 VIBE DEV SPACE LLC
+   Copyright 2026 Andrii Poluosmak
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -1,267 +1,218 @@
 # @itsaplan/runner
 
-[It's a Plan](https://itsaplan.dev) is self-hosted, open-source project management and
-issue tracking where AI agents work like teammates: they have a role, permissions, and
-issues assigned to them.
+[It's a Plan](https://itsaplan.dev) is a self-hosted, open-source issue tracker. An AI
+agent in it is a project member: it has a role, permissions, and its own issues.
 
-This package runs the tasks of one such agent on your own machine. It takes one queued
-task at a time, passes it to a command you choose, and sends the result back. The
-command is yours: Claude Code, Codex, a shell script, anything that reads stdin.
+This package runs one such agent on your own machine.
+
+- Polls your instance for the agent's queued runs. Runs each one with a coding agent CLI.
+  Reports the result.
+- Has presets for Claude Code, Codex, opencode, Gemini CLI and GitHub Copilot CLI. 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.
 
 ## Quick start
 
-**1. Get the agent's key.** In your project: Settings, AI agents, create one of kind
-External. The key is shown once, at creation.
+**1. Get the agent's key.** In your project, go to Settings, AI agents. Create an agent
+of kind External. The key appears one time only, at creation.
+
+**2. Enable MCP** for the project, in Settings, MCP Server. MCP is off by default. The
+agent reads the issue and writes its result through it.
 
-**2. Write `itsaplan-runner.json`** in the folder you want the agent to work in:
+**3. Give the coding agent the address of that server.** Claude Code reads `.mcp.json`
+from the folder it runs in. For the other four CLIs, see
+[Coding agent setup](https://github.com/croffasia/itsaplan/blob/main/docs/runner.md).
 
 ```json
 {
-  "url": "http://localhost:3000",
-  "apiKey": "the key you just copied",
-  "command": "claude -p"
+  "mcpServers": {
+    "itsaplan": {
+      "type": "http",
+      "url": "http://localhost:3000/mcp",
+      "headers": { "Authorization": "Bearer ${ITSAPLAN_API_KEY}" }
+    }
+  }
 }
 ```
 
-**3. Start it:**
-
-```bash
-npx -y @itsaplan/runner
-```
+The runner sets `ITSAPLAN_API_KEY` for the command that it starts. The key thus stays in
+one file.
 
-The agent goes online in the project within a few seconds. Delegate an issue to it or
-mention it in a comment, and the task lands in your terminal.
+**4. Write `itsaplan-runner.json`** in the same folder:
 
-`Ctrl-C` stops the runner once the tasks in flight are done. Anything still queued
-waits for the next runner.
-
-## Settings
-
-The runner reads `./itsaplan-runner.json`, or the path you give it as an argument or in
-`ITSAPLAN_RUNNER_CONFIG`:
-
-```bash
-npx -y @itsaplan/runner /path/to/config.json
+```json
+{
+  "url": "http://localhost:3000",
+  "apiKey": "the key you just copied",
+  "agent": "claude"
+}
 ```
 
-Environment variables win over the file:
-
-| Field            | Environment variable        | Default            | What it does                        |
-| ---------------- | --------------------------- | ------------------ | ----------------------------------- |
-| `url`            | `ITSAPLAN_URL`              | required           | Your Itsaplan instance              |
-| `apiKey`         | `ITSAPLAN_API_KEY`          | required           | The external agent's key            |
-| `command`        | `ITSAPLAN_COMMAND`          | required           | The command that handles one task   |
-| `cwd`            | `ITSAPLAN_CWD`              | where you start it | Working directory for the command   |
-| `env`            |                             | `{}`               | Extra variables for the command     |
-| `concurrency`    | `ITSAPLAN_CONCURRENCY`      | `1`                | How many tasks may run at once      |
-| `pollIntervalMs` | `ITSAPLAN_POLL_INTERVAL_MS` | `3000`             | Wait after an empty queue, at least 1000 |
-| `timeoutMs`      | `ITSAPLAN_TIMEOUT_MS`       | `1800000`          | When a task is killed as stuck      |
-
-Which is how the key stays out of any file:
+**5. Start it:**
 
 ```bash
-export ITSAPLAN_API_KEY=…
 npx -y @itsaplan/runner
 ```
 
-## What your command receives
-
-The task text arrives on **stdin**. The rest of the run arrives in the environment:
+The project shows the agent as online in a few seconds. Delegate an issue to the agent,
+or mention it in a comment. The task then starts in your terminal.
 
-| Variable                 | What it holds                                          |
-| ------------------------ | ------------------------------------------------------ |
-| `ITSAPLAN_URL`           | the instance the task came from                        |
-| `ITSAPLAN_API_KEY`       | the agent's key, for the API and the MCP server        |
-| `ITSAPLAN_RUN_ID`        | the run's id                                           |
-| `ITSAPLAN_TRIGGER`       | `mention`, `delegation`, `schedule`, or `manual`       |
-| `ITSAPLAN_SYSTEM_PROMPT` | context about the run, for commands that take a system prompt |
-| `ITSAPLAN_ISSUE`         | the issue key, e.g. `MKT-42` (empty when there is none) |
-| `ITSAPLAN_ISSUE_ID`      | the issue's numeric id                                 |
+## Which coding agent
 
-The task on stdin is written by the server: what happened, what to do, and to post the
-result as a comment on the issue. The agent reads everything else through the MCP
-server at `$ITSAPLAN_URL/mcp`, with `$ITSAPLAN_API_KEY` as a bearer token, acting as
-its own user under its role. Enable MCP in the project settings.
+`agent` names a CLI that the runner knows. The runner then builds the command itself: the
+flags for an unattended run, and the session resume.
 
-Exit code `0` is a success, anything else a failure with the tail of stderr as the
-error. Stdout becomes the run's output either way.
+| Agent      | Runs                     | Keeps a chat session |
+| ---------- | ------------------------ | -------------------- |
+| `claude`   | Claude Code              | yes                  |
+| `codex`    | Codex CLI                | yes                  |
+| `opencode` | opencode                 | yes                  |
+| `gemini`   | Gemini CLI               | no                   |
+| `copilot`  | GitHub Copilot CLI       | no                   |
 
-## Claude Code
+Each preset needs the CLI's own MCP config.
+[Coding agent setup](https://github.com/croffasia/itsaplan/blob/main/docs/runner.md) holds
+that file, and the notes for each CLI.
 
-`mcp.json`, next to the runner config:
+`--agent` on the command line has priority over the file. The runner appends the
+arguments after `--` to the ones from the preset:
 
-```json
-{
-  "mcpServers": {
-    "itsaplan": {
-      "type": "http",
-      "url": "http://localhost:3000/mcp",
-      "headers": { "Authorization": "Bearer ${ITSAPLAN_API_KEY}" }
-    }
-  }
-}
+```bash
+npx -y @itsaplan/runner --agent claude -- --model opus
 ```
 
-`itsaplan-runner.json`:
+Write the same arguments in the file if a service manager starts the runner:
 
 ```json
 {
   "url": "http://localhost:3000",
   "apiKey": "the key you copied on creation",
-  "command": "claude -p --mcp-config ./mcp.json --append-system-prompt \"$ITSAPLAN_SYSTEM_PROMPT\" --permission-mode auto --output-format text",
-  "cwd": "/Users/me/work/my-repo"
+  "agent": "claude",
+  "cwd": "/Users/me/work/my-repo",
+  "args": ["--model", "opus"]
 }
 ```
 
-- `--mcp-config` adds this instance's server on top of what the machine already has,
-  so your own MCP servers, skills, and memory stay in the run. Drop it if the server is
-  already in the repository's `.mcp.json` or was added with `claude mcp add`.
-- `--permission-mode auto` covers permissions: nobody is there to answer a prompt, so a
-  classifier reviews each action instead, MCP tool calls included.
+Your arguments come after the preset's own. A repeated flag thus replaces its value.
 
-## Codex
+`command` replaces the preset with your own shell command. The command receives the task
+on stdin. The runner keeps no session for it, because it does not know how to resume one.
 
-Codex reads its MCP servers from `~/.codex/config.toml`, and `bearer_token_env_var`
-takes the key from the environment the runner already sets:
+## Settings
+
+The runner reads `./itsaplan-runner.json`. For a different file, give the path as an
+argument or in `ITSAPLAN_RUNNER_CONFIG`:
 
-```toml
-[mcp_servers.itsaplan]
-url = "http://localhost:3000/mcp"
-bearer_token_env_var = "ITSAPLAN_API_KEY"
+```bash
+npx -y @itsaplan/runner /path/to/config.json
 ```
 
-`itsaplan-runner.json`:
+The environment variables have priority over the file. The command-line options have
+priority over both.
 
-```json
-{
-  "url": "http://localhost:3000",
-  "apiKey": "the key you copied on creation",
-  "command": "printf '%s\\n\\n%s' \"$ITSAPLAN_SYSTEM_PROMPT\" \"$(cat)\" | codex exec --sandbox workspace-write --skip-git-repo-check -",
-  "cwd": "/path/to/working-dir"
-}
+| Field            | Environment variable        | Default            | What it does                        |
+| ---------------- | --------------------------- | ------------------ | ----------------------------------- |
+| `url`            | `ITSAPLAN_URL`              | required           | Your Itsaplan instance              |
+| `apiKey`         | `ITSAPLAN_API_KEY`          | required           | The external agent's key            |
+| `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. 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 |
+
+Set `agent` or `command`. With the environment you need no file at all:
+
+```bash
+export ITSAPLAN_API_KEY=…
+npx -y @itsaplan/runner --agent claude
 ```
 
-- Codex has no system-prompt flag, so `printf` puts the system prompt in front of the
-  task, and the trailing `-` tells Codex to read all of it from stdin.
-- `--sandbox workspace-write` bounds what it may change: writes stay inside the working
-  directory.
-- `--skip-git-repo-check` is only needed when that directory is not a git repository.
+## What the coding agent receives
 
-## Gemini CLI
+### The task text
 
-`.gemini/settings.json` in the working directory. Gemini expands `$VARS` in it, so the
-key comes from the environment, and `trust` skips the tool confirmation a headless run
-cannot answer:
+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 `gemini`, `copilot` and `opencode`.
 
-```json
-{
-  "mcpServers": {
-    "itsaplan": {
-      "httpUrl": "http://localhost:3000/mcp",
-      "headers": { "Authorization": "Bearer $ITSAPLAN_API_KEY" },
-      "trust": true
-    }
-  }
-}
-```
+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.
 
-`itsaplan-runner.json`:
+### The environment
 
-```json
-{
-  "url": "http://localhost:3000",
-  "apiKey": "the key you copied on creation",
-  "command": "printf '%s\\n\\n%s' \"$ITSAPLAN_SYSTEM_PROMPT\" \"$(cat)\" | gemini --approval-mode yolo",
-  "cwd": "/path/to/working-dir"
-}
-```
+Every run holds these variables:
 
-- Gemini has no system-prompt flag either, and reads the piped prompt on stdin, so the
-  command is shaped like the Codex one.
-- `--approval-mode yolo` approves every tool call, which a headless run needs.
-  `auto_edit` is the narrower option: file edits only.
+| Variable                 | What it holds                                                    |
+| ------------------------ | ---------------------------------------------------------------- |
+| `ITSAPLAN_URL`           | the instance that sent the task                                  |
+| `ITSAPLAN_API_KEY`       | the agent's key, for the API and the MCP server                  |
+| `ITSAPLAN_TRIGGER`       | `mention`, `delegation`, `schedule`, `manual`, or `chat`         |
+| `ITSAPLAN_SYSTEM_PROMPT` | the context of the run, for a command that takes a system prompt |
 
-## GitHub Copilot CLI
+A queued run adds three more:
 
-`.mcp.json` in the working directory. Copilot's headers take no variable
-interpolation, so the key goes in as it stands:
+| Variable            | What it holds                                                   |
+| ------------------- | --------------------------------------------------------------- |
+| `ITSAPLAN_RUN_ID`   | the run's id                                                    |
+| `ITSAPLAN_ISSUE`    | the issue key, for example `MKT-42`. Empty if there is no issue |
+| `ITSAPLAN_ISSUE_ID` | the numeric id of the issue. Empty if there is no issue         |
 
-```json
-{
-  "mcpServers": {
-    "itsaplan": {
-      "type": "http",
-      "url": "http://localhost:3000/mcp",
-      "headers": { "Authorization": "Bearer the-agent-key" },
-      "tools": ["*"]
-    }
-  }
-}
-```
+A chat message adds three others in their place, and `ITSAPLAN_TRIGGER` is `chat`:
 
-`itsaplan-runner.json`:
+| Variable               | What it holds                                                   |
+| ---------------------- | ---------------------------------------------------------------- |
+| `ITSAPLAN_THREAD_ID`   | the conversation's id                                            |
+| `ITSAPLAN_MESSAGE_ID`  | the id of the message to answer                                  |
+| `ITSAPLAN_SESSION_ID`  | the coding agent's session to resume. Empty for the first message |
 
-```json
-{
-  "url": "http://localhost:3000",
-  "apiKey": "the key you copied on creation",
-  "command": "copilot -p \"$(printf '%s\\n\\n%s' \"$ITSAPLAN_SYSTEM_PROMPT\" \"$(cat)\")\" --allow-all-tools --no-ask-user",
-  "cwd": "/path/to/working-dir"
-}
-```
+The task text of a chat message includes the conversation, unless a session holds it. See
+Sessions below.
 
-- Copilot takes neither a system-prompt flag nor a prompt on stdin, so both go in as
-  one `-p` argument.
-- `--allow-all-tools` and `--no-ask-user` keep it from waiting for an approval it
-  cannot get.
+### The result
 
-## opencode
+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.
 
-`opencode.json` in the working directory. opencode interpolates `{env:VAR}`, so the key
-stays out of the file:
+## Chat
 
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "model": "anthropic/claude-sonnet-5",
-  "mcp": {
-    "itsaplan": {
-      "type": "remote",
-      "url": "http://localhost:3000/mcp",
-      "enabled": true,
-      "headers": { "Authorization": "Bearer {env:ITSAPLAN_API_KEY}" }
-    }
-  }
-}
-```
+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:
 
-`itsaplan-runner.json`:
+- `text` — all the output is the answer.
+- `claude-stream-json`, `codex-jsonl`, `opencode-json` — the event stream of that CLI.
 
-```json
-{
-  "url": "http://localhost:3000",
-  "apiKey": "the key you copied on creation",
-  "command": "opencode run \"$(printf '%s\\n\\n%s' \"$ITSAPLAN_SYSTEM_PROMPT\" \"$(cat)\")\"",
-  "cwd": "/path/to/working-dir"
-}
-```
+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.
 
-- `opencode run` takes the prompt as an argument and never reads stdin, so the task is
-  passed the same way as with Copilot.
-- Pin `model` as `provider/model`. opencode is provider agnostic, and without that key
-  a run falls back to whatever model was picked interactively last. `opencode auth
-  login` is what makes a provider available in the first place.
+### Sessions
 
-## Requirements
+Each conversation resumes one session of the coding agent, which keeps its full context.
+Without a session the server sends the last 20 messages of the conversation as plain text.
+
+- The chat header shows the session id. Run `claude --resume <id>` in the runner's working
+  directory to open the same session in your terminal.
+- `gemini` and `copilot` keep no session: neither one reports the id of a session that
+  starts non-interactively.
+- A session stays on the machine that started it. If you delete its files or move the
+  runner, the answers fail. Start a new chat then.
 
-Node 20 or newer, an It's a Plan instance on 0.10.0 or newer, and an **external** agent in
-your project. Its API key is what the runner authenticates with.
+## Requirements
 
-The coding agent you point the runner at has to be installed and signed in on the same
-machine — the runner starts it as you and cannot sign in for you.
+- **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 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.
 
-On macOS and Linux there is nothing else to it. The runner hands every task to `sh -c`,
-so the commands in this file are POSIX shell.
+macOS and Linux need nothing else. The runner starts a preset directly, so its arguments
+need no quotes. Your own `command` goes to `sh -c`, so write it as POSIX shell.
 
 Windows needs WSL2, because `cmd.exe` and PowerShell have no `sh`:
 
@@ -269,16 +220,14 @@ Windows needs WSL2, because `cmd.exe` and PowerShell have no `sh`:
 wsl --install     # installs Ubuntu, then reboot
 ```
 
-Everything after that happens inside WSL: Node, the coding agent, the config file, and
-`npx -y @itsaplan/runner`. Two things worth knowing there:
+Do everything else in WSL: Node, the coding agent, the config file, and the runner.
 
-- Keep the working directory in the WSL file system (`~/work/repo`) rather than under
-  `/mnt/c/...`. File access across that boundary is slow enough to notice on a repo.
-- An instance running on the Windows host is reachable from WSL2 as
-  `http://localhost:3000`.
+- Keep the working directory in the WSL file system (`~/work/repo`), not under
+  `/mnt/c/...`. Access between the two file systems is slow.
+- An instance on the Windows host is available at `http://localhost:3000`.
 
 ## License
 
-Copyright © 2026 VIBE DEV SPACE LLC.
+Copyright © 2026 Andrii Poluosmak.
 
 [Apache-2.0](LICENSE).

package/dist/cli.js

@@ -3,52 +3,353 @@
 // src/cli.ts
 import { setTimeout as sleep } from "node:timers/promises";
 
-// src/client.ts
-var REQUEST_TIMEOUT_MS = 30000;
+// src/agui.ts
+var FLUSH_CHARS = 1500;
+var DELTA_LIMIT = 12000;
+var TOOL_TEXT_LIMIT = 32000;
 
-class RequestError extends Error {
-  status;
-  constructor(status, message) {
-    super(message);
-    this.status = status;
+class AnswerStream {
+  format;
+  threadId;
+  runId;
+  send;
+  messageId;
+  queued = [];
+  text = "";
+  started = false;
+  line = "";
+  sessionId = null;
+  openTextPart = "";
+  openToolCalls = new Set;
+  closedToolCalls = new Set;
+  sawPartialText = false;
+  sawAnyText = false;
+  sending = Promise.resolve();
+  constructor(format, threadId, runId, send) {
+    this.format = format;
+    this.threadId = threadId;
+    this.runId = runId;
+    this.send = send;
+    this.messageId = `msg-${runId}`;
+    this.queued.push({ type: "RUN_STARTED", threadId, runId });
   }
-}
-
-class Client {
-  config;
-  constructor(config) {
-    this.config = config;
+  write(chunk) {
+    if (this.format === "text") {
+      this.appendText(chunk);
+      return;
+    }
+    this.line += chunk;
+    const lines = this.line.split(`
+`);
+    this.line = lines.pop() ?? "";
+    for (const line of lines)
+      this.readLine(line);
   }
-  async post(path, body) {
-    const res = await fetch(`${this.config.url}${path}`, {
-      method: "POST",
-      headers: {
-        "x-api-key": this.config.apiKey,
-        ...body === undefined ? {} : { "content-type": "application/json" }
-      },
-      body: body === undefined ? undefined : JSON.stringify(body),
-      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
-    });
-    if (!res.ok) {
-      throw new RequestError(res.status, `POST ${path} failed with ${res.status}: ${(await res.text()).slice(0, 200)}`);
+  startedSession() {
+    return this.sessionId;
+  }
+  async flush() {
+    const sending = this.sending.catch(() => {}).then(() => this.sendQueued());
+    this.sending = sending.catch(() => {});
+    return sending;
+  }
+  async sendQueued() {
+    this.drainText();
+    if (this.queued.length === 0)
+      return;
+    const batch = this.queued;
+    this.queued = [];
+    try {
+      await this.send(batch);
+    } catch (err) {
+      this.queued.unshift(...batch);
+      throw err;
     }
-    return res;
   }
-  async claim() {
-    const res = await this.post("/agent-runs/claim");
-    const body = await res.json();
-    return body.run;
+  async finish(fallback) {
+    this.closeText(fallback);
+    this.queued.push({ type: "RUN_FINISHED", threadId: this.threadId, runId: this.runId });
+    await this.flush();
   }
-  async heartbeat(runId) {
-    await this.post(`/agent-runs/${runId}/heartbeat`);
+  async fail(message, fallback = "") {
+    this.closeText(fallback);
+    this.queued.push({ type: "RUN_ERROR", message });
+    await this.flush();
   }
-  async report(runId, result) {
-    await this.post(`/agent-runs/${runId}/result`, result);
+  closeText(fallback) {
+    if (this.line) {
+      this.readLine(this.line);
+      this.line = "";
+    }
+    if (!this.sawAnyText && fallback)
+      this.appendText(fallback);
+    this.drainText();
+    if (this.started)
+      this.queued.push({ type: "TEXT_MESSAGE_END", messageId: this.messageId });
+    this.started = false;
+  }
+  appendText(text) {
+    if (!text)
+      return;
+    this.sawAnyText = true;
+    this.text += text;
+    if (this.text.length >= FLUSH_CHARS)
+      this.drainText();
+  }
+  drainText() {
+    if (this.text.length === 0)
+      return;
+    if (!this.started) {
+      this.started = true;
+      this.queued.push({
+        type: "TEXT_MESSAGE_START",
+        messageId: this.messageId,
+        role: "assistant"
+      });
+    }
+    while (this.text.length > 0) {
+      const delta = this.text.slice(0, DELTA_LIMIT);
+      this.text = this.text.slice(DELTA_LIMIT);
+      this.queued.push({ type: "TEXT_MESSAGE_CONTENT", messageId: this.messageId, delta });
+    }
+  }
+  readLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+      return;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      this.appendText(`${trimmed}
+`);
+      return;
+    }
+    if (!parsed || typeof parsed !== "object")
+      return;
+    switch (this.format) {
+      case "claude-stream-json":
+        this.readClaudeLine(parsed);
+        break;
+      case "codex-jsonl":
+        this.readCodexLine(parsed);
+        break;
+      case "opencode-json":
+        this.readOpencodeLine(parsed);
+        break;
+    }
+  }
+  readCodexLine(message) {
+    if (message.type === "thread.started" && message.thread_id) {
+      this.sessionId ??= message.thread_id;
+      return;
+    }
+    const item = message.item;
+    if (message.type !== "item.completed" || !item)
+      return;
+    if (item.type === "agent_message" && item.text) {
+      this.appendText(item.text);
+      return;
+    }
+    if (item.type === "command_execution" && item.id) {
+      this.pushToolCall(item.id, "shell", item.command ?? "");
+      this.pushToolResult(item.id, item.aggregated_output ?? "");
+    }
+  }
+  readOpencodeLine(message) {
+    if (message.sessionID)
+      this.sessionId ??= message.sessionID;
+    const part = message.part;
+    if (!part)
+      return;
+    if (part.type === "text" && part.text) {
+      const grown = part.text.startsWith(this.openTextPart) ? part.text.slice(this.openTextPart.length) : part.text;
+      this.openTextPart = part.text;
+      this.appendText(grown);
+      return;
+    }
+    if (part.type !== "tool" || !part.callID)
+      return;
+    if (!this.openToolCalls.has(part.callID)) {
+      this.openToolCalls.add(part.callID);
+      this.pushToolCall(part.callID, part.tool ?? "tool", JSON.stringify(part.state?.input ?? {}));
+    }
+    if (this.closedToolCalls.has(part.callID))
+      return;
+    const state = part.state;
+    const result = state?.status === "completed" ? state.output : state?.status === "error" ? state.error : null;
+    if (typeof result !== "string")
+      return;
+    this.closedToolCalls.add(part.callID);
+    this.pushToolResult(part.callID, result);
+  }
+  readClaudeLine(message) {
+    if (message.session_id)
+      this.sessionId ??= message.session_id;
+    switch (message.type) {
+      case "stream_event":
+        this.readPartial(message.event);
+        break;
+      case "assistant":
+        this.readAssistant(message.message?.content ?? []);
+        break;
+      case "user":
+        this.readToolResults(message.message?.content ?? []);
+        break;
+      case "result":
+        if (!this.sawAnyText && typeof message.result === "string")
+          this.appendText(message.result);
+        break;
+    }
+  }
+  readPartial(event) {
+    if (event?.type !== "content_block_delta")
+      return;
+    if (event.delta?.type === "text_delta" && event.delta.text) {
+      this.sawPartialText = true;
+      this.appendText(event.delta.text);
+    }
+  }
+  readAssistant(content) {
+    for (const block of content) {
+      if (block.type === "text" && block.text && !this.sawPartialText) {
+        this.appendText(block.text);
+      }
+      if (block.type === "tool_use" && block.id) {
+        this.pushToolCall(block.id, block.name ?? "tool", JSON.stringify(block.input ?? {}));
+      }
+    }
+  }
+  readToolResults(content) {
+    for (const block of content) {
+      if (block.type !== "tool_result" || !block.tool_use_id)
+        continue;
+      this.pushToolResult(block.tool_use_id, textOfResult(block.content));
+    }
+  }
+  pushToolCall(toolCallId, toolCallName, args) {
+    this.drainText();
+    this.queued.push({ type: "TOOL_CALL_START", toolCallId, toolCallName, parentMessageId: this.messageId }, { type: "TOOL_CALL_ARGS", toolCallId, delta: tail(args, TOOL_TEXT_LIMIT) }, { type: "TOOL_CALL_END", toolCallId });
+  }
+  pushToolResult(toolCallId, content) {
+    this.drainText();
+    this.queued.push({
+      type: "TOOL_CALL_RESULT",
+      messageId: this.messageId,
+      toolCallId,
+      content: tail(content, TOOL_TEXT_LIMIT)
+    });
   }
 }
+function tail(text, limit) {
+  return text.length <= limit ? text : `…${text.slice(-limit)}`;
+}
+function textOfResult(content) {
+  if (typeof content === "string")
+    return content;
+  if (Array.isArray(content)) {
+    return content.map((part) => typeof part === "object" && part && ("text" in part) ? String(part.text) : "").join("");
+  }
+  return "";
+}
+
+// src/execute.ts
+import { spawn } from "node:child_process";
 
 // src/config.ts
 import { readFile } from "node:fs/promises";
+
+// src/presets.ts
+var PRESETS = {
+  claude: {
+    bin: "claude",
+    outputFormat: "claude-stream-json",
+    sessions: true,
+    promptVia: "stdin",
+    systemPromptFlag: "--append-system-prompt",
+    head: (sessionId) => [
+      "-p",
+      ...sessionId ? ["--resume", sessionId] : [],
+      "--output-format",
+      "stream-json",
+      "--include-partial-messages",
+      "--verbose",
+      "--permission-mode",
+      "auto"
+    ],
+    tail: []
+  },
+  codex: {
+    bin: "codex",
+    outputFormat: "codex-jsonl",
+    sessions: true,
+    promptVia: "stdin",
+    head: (sessionId) => [
+      ...sessionId ? ["exec", "resume", sessionId] : ["exec"],
+      "--json",
+      "-c",
+      'sandbox_mode="workspace-write"'
+    ],
+    tail: ["-"]
+  },
+  opencode: {
+    bin: "opencode",
+    outputFormat: "opencode-json",
+    sessions: true,
+    promptVia: "arg",
+    head: (sessionId) => [
+      "run",
+      "--format",
+      "json",
+      ...sessionId ? ["--session", sessionId] : []
+    ],
+    tail: []
+  },
+  gemini: {
+    bin: "gemini",
+    outputFormat: "text",
+    sessions: false,
+    promptVia: "arg",
+    head: () => ["--approval-mode", "yolo"],
+    tail: ["-p"]
+  },
+  copilot: {
+    bin: "copilot",
+    outputFormat: "text",
+    sessions: false,
+    promptVia: "arg",
+    head: () => ["--allow-all-tools", "--no-ask-user"],
+    tail: ["-p"]
+  }
+};
+var PRESET_NAMES = Object.keys(PRESETS);
+function isPresetName(value) {
+  return value in PRESETS;
+}
+function presetPrompt(preset, systemPrompt, prompt) {
+  if (preset.systemPromptFlag || !systemPrompt)
+    return prompt;
+  return `${systemPrompt}
+
+${prompt}`;
+}
+function presetArgv(preset, sessionId, systemPrompt, extraArgs, prompt) {
+  return [
+    ...preset.head(preset.sessions ? sessionId : null),
+    ...preset.systemPromptFlag && systemPrompt ? [preset.systemPromptFlag, systemPrompt] : [],
+    ...extraArgs,
+    ...preset.tail,
+    ...preset.promptVia === "arg" ? [presetPrompt(preset, systemPrompt, prompt)] : []
+  ];
+}
+
+// src/config.ts
+var OUTPUT_FORMATS = ["text", "claude-stream-json", "codex-jsonl", "opencode-json"];
+function presetOf(config) {
+  if (config.command || !config.agent)
+    return;
+  return PRESETS[config.agent];
+}
 var DEFAULTS = {
   concurrency: 1,
   pollIntervalMs: 3000,
@@ -59,6 +360,33 @@ function intFrom(value, fallback) {
   const parsed = typeof value === "string" ? Number.parseInt(value, 10) : value;
   return typeof parsed === "number" && Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }
+function outputFormatFrom(value, preset) {
+  const name = typeof value === "string" ? value.trim() : "";
+  if (!name)
+    return preset?.outputFormat ?? "text";
+  const format = OUTPUT_FORMATS.find((candidate) => candidate === name);
+  if (!format) {
+    throw new Error(`outputFormat must be one of ${OUTPUT_FORMATS.join(", ")}`);
+  }
+  return format;
+}
+function agentFrom(value) {
+  const name = typeof value === "string" ? value.trim() : "";
+  if (!name)
+    return;
+  if (!isPresetName(name)) {
+    throw new Error(`agent must be one of ${PRESET_NAMES.join(", ")}`);
+  }
+  return name;
+}
+function argsFrom(value) {
+  if (value === undefined)
+    return [];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error("args must be an array of strings");
+  }
+  return value;
+}
 function required(value, field) {
   const text = typeof value === "string" ? value.trim() : "";
   if (!text)
@@ -80,39 +408,42 @@ async function readConfigFile(path) {
     throw new Error(`${path} is not valid JSON`);
   }
 }
-async function loadConfig(path) {
+async function loadConfig(path, overrides = {}) {
   const raw = await readConfigFile(path);
   const env = process.env;
+  const agent = agentFrom(overrides.agent ?? env.ITSAPLAN_AGENT ?? raw.agent);
+  const command = (env.ITSAPLAN_COMMAND ?? raw.command)?.trim() || undefined;
+  if (!agent && !command) {
+    throw new Error(`set either agent (one of ${PRESET_NAMES.join(", ")}) or command in the config file or the environment`);
+  }
   return {
     url: required(env.ITSAPLAN_URL ?? raw.url, "url").replace(/\/+$/, ""),
     apiKey: required(env.ITSAPLAN_API_KEY ?? raw.apiKey, "apiKey"),
-    command: required(env.ITSAPLAN_COMMAND ?? raw.command, "command"),
+    agent,
+    command,
+    args: [...argsFrom(raw.args), ...overrides.args ?? []],
     cwd: (env.ITSAPLAN_CWD ?? raw.cwd)?.replace(/^~/, env.HOME ?? "~"),
     env: raw.env ?? {},
     concurrency: intFrom(env.ITSAPLAN_CONCURRENCY ?? raw.concurrency, DEFAULTS.concurrency),
     pollIntervalMs: Math.max(intFrom(env.ITSAPLAN_POLL_INTERVAL_MS ?? raw.pollIntervalMs, DEFAULTS.pollIntervalMs), MIN_POLL_INTERVAL_MS),
-    timeoutMs: intFrom(env.ITSAPLAN_TIMEOUT_MS ?? raw.timeoutMs, DEFAULTS.timeoutMs)
+    timeoutMs: intFrom(env.ITSAPLAN_TIMEOUT_MS ?? raw.timeoutMs, DEFAULTS.timeoutMs),
+    outputFormat: outputFormatFrom(env.ITSAPLAN_OUTPUT_FORMAT ?? raw.outputFormat, presetOf({ agent, command }))
   };
 }
 
 // src/execute.ts
-import { spawn } from "node:child_process";
 var OUTPUT_LIMIT = 8000;
 var ERROR_LIMIT = 400;
-function tail(text, limit) {
+function tail2(text, limit) {
   return text.length <= limit ? text : `…${text.slice(-limit)}`;
 }
-function childEnv(config, run) {
+function childEnv(config, task) {
   return {
     ...process.env,
     ...config.env,
     ITSAPLAN_URL: config.url,
     ITSAPLAN_API_KEY: config.apiKey,
-    ITSAPLAN_RUN_ID: String(run.id),
-    ITSAPLAN_TRIGGER: run.trigger,
-    ITSAPLAN_SYSTEM_PROMPT: run.systemPrompt,
-    ITSAPLAN_ISSUE: run.issueIdentifier ?? "",
-    ITSAPLAN_ISSUE_ID: run.issueId == null ? "" : String(run.issueId)
+    ...task.env
   };
 }
 function killGroup(pid) {
@@ -120,10 +451,27 @@ function killGroup(pid) {
     process.kill(-pid, "SIGKILL");
   } catch {}
 }
-async function execute(config, run) {
-  const child = spawn("sh", ["-c", config.command], {
+function spawnArgs(config, preset, task) {
+  if (!preset)
+    return ["sh", ["-c", config.command ?? ""]];
+  return [
+    preset.bin,
+    presetArgv(preset, task.sessionId ?? null, task.systemPrompt, config.args, task.prompt)
+  ];
+}
+function stdinText(preset, task) {
+  if (!preset)
+    return task.prompt;
+  if (preset.promptVia === "arg")
+    return "";
+  return presetPrompt(preset, task.systemPrompt, task.prompt);
+}
+async function execute(config, task, onData) {
+  const preset = presetOf(config);
+  const [bin, args] = spawnArgs(config, preset, task);
+  const child = spawn(bin, args, {
     cwd: config.cwd,
-    env: childEnv(config, run),
+    env: childEnv(config, task),
     detached: true
   });
   let timedOut = false;
@@ -137,13 +485,14 @@ async function execute(config, run) {
   child.stdout.setEncoding("utf8");
   child.stderr.setEncoding("utf8");
   child.stdout.on("data", (chunk) => {
-    stdout = tail(stdout + chunk, OUTPUT_LIMIT);
+    stdout = tail2(stdout + chunk, OUTPUT_LIMIT);
+    onData?.(chunk);
   });
   child.stderr.on("data", (chunk) => {
-    stderr = tail(stderr + chunk, ERROR_LIMIT);
+    stderr = tail2(stderr + chunk, ERROR_LIMIT);
   });
   child.stdin.on("error", () => {});
-  child.stdin.end(run.prompt);
+  child.stdin.end(stdinText(preset, task));
   const exited = new Promise((resolve, reject) => {
     child.on("error", reject);
     child.on("close", (exitCode, exitSignal) => resolve({ code: exitCode, signal: exitSignal }));
@@ -167,14 +516,112 @@ async function execute(config, run) {
   };
 }
 
+// src/chat.ts
+var FLUSH_MS = 500;
+async function answer(config, client, message) {
+  let reported = message.sessionId !== null;
+  const stream = new AnswerStream(config.outputFormat, message.threadId, String(message.id), (events) => {
+    const started = reported ? undefined : stream.startedSession() ?? undefined;
+    if (started)
+      reported = true;
+    return client.chatEvents(message.id, events, started);
+  });
+  const flushing = setInterval(() => {
+    stream.flush().catch(() => {});
+  }, FLUSH_MS);
+  const outcome = await execute(config, {
+    prompt: message.prompt,
+    systemPrompt: message.systemPrompt,
+    sessionId: message.sessionId,
+    env: {
+      ITSAPLAN_TRIGGER: "chat",
+      ITSAPLAN_SYSTEM_PROMPT: message.systemPrompt,
+      ITSAPLAN_THREAD_ID: message.threadId,
+      ITSAPLAN_MESSAGE_ID: String(message.id),
+      ITSAPLAN_SESSION_ID: message.sessionId ?? ""
+    }
+  }, (chunk) => stream.write(chunk)).finally(() => clearInterval(flushing));
+  if (outcome.status === "success") {
+    await stream.finish(outcome.output);
+    await client.chatResult(message.id, { status: "success" });
+    return;
+  }
+  const error = outcome.error ?? "The command failed";
+  await stream.fail(error, outcome.output);
+  await client.chatResult(message.id, { status: "failed", error });
+}
+
+// src/client.ts
+var REQUEST_TIMEOUT_MS = 30000;
+var CHAT_CLAIM_TIMEOUT_MS = 35000;
+
+class RequestError extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+  }
+}
+
+class Client {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  async post(path, body, timeoutMs = REQUEST_TIMEOUT_MS) {
+    const res = await fetch(`${this.config.url}${path}`, {
+      method: "POST",
+      headers: {
+        "x-api-key": this.config.apiKey,
+        ...body === undefined ? {} : { "content-type": "application/json" }
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!res.ok) {
+      throw new RequestError(res.status, `POST ${path} failed with ${res.status}: ${(await res.text()).slice(0, 200)}`);
+    }
+    return res;
+  }
+  async claim() {
+    const res = await this.post("/agent-runs/claim");
+    const body = await res.json();
+    return body.run;
+  }
+  async heartbeat(runId) {
+    await this.post(`/agent-runs/${runId}/heartbeat`);
+  }
+  async report(runId, result) {
+    await this.post(`/agent-runs/${runId}/result`, result);
+  }
+  async claimChat() {
+    const res = await this.post("/agent-chats/claim", undefined, CHAT_CLAIM_TIMEOUT_MS);
+    const body = await res.json();
+    return body.message;
+  }
+  async chatEvents(messageId, events, sessionId) {
+    await this.post(`/agent-chats/${messageId}/events`, {
+      events,
+      ...sessionId && { sessionId }
+    });
+  }
+  async chatHeartbeat(messageId) {
+    await this.post(`/agent-chats/${messageId}/heartbeat`);
+  }
+  async chatResult(messageId, result) {
+    await this.post(`/agent-chats/${messageId}/result`, result);
+  }
+}
+
 // src/cli.ts
 var HEARTBEAT_MS = 60000;
+var ERROR_BACKOFF_MS = 5000;
 function log(message) {
   console.log(`[itsaplan-runner] ${message}`);
 }
-async function withHeartbeat(client, runId, work) {
+async function withHeartbeat(beat, work) {
   const timer = setInterval(() => {
-    client.heartbeat(runId).catch((err) => log(`heartbeat failed: ${String(err)}`));
+    beat().catch((err) => log(`heartbeat failed: ${String(err)}`));
   }, HEARTBEAT_MS);
   try {
     return await work;
@@ -182,11 +629,24 @@ async function withHeartbeat(client, runId, work) {
     clearInterval(timer);
   }
 }
+function taskOf(run) {
+  return {
+    prompt: run.prompt,
+    systemPrompt: run.systemPrompt,
+    env: {
+      ITSAPLAN_RUN_ID: String(run.id),
+      ITSAPLAN_TRIGGER: run.trigger,
+      ITSAPLAN_SYSTEM_PROMPT: run.systemPrompt,
+      ITSAPLAN_ISSUE: run.issueIdentifier ?? "",
+      ITSAPLAN_ISSUE_ID: run.issueId == null ? "" : String(run.issueId)
+    }
+  };
+}
 async function handle(config, client, run) {
   const label = run.issueIdentifier ?? `run ${run.id}`;
   log(`${label}: started (${run.trigger})`);
   try {
-    const outcome = await withHeartbeat(client, run.id, execute(config, run));
+    const outcome = await withHeartbeat(() => client.heartbeat(run.id), execute(config, taskOf(run)));
     await client.report(run.id, outcome);
     log(`${label}: ${outcome.status}${outcome.error ? ` — ${outcome.error}` : ""}`);
   } catch (err) {
@@ -195,45 +655,106 @@ async function handle(config, client, run) {
     await client.report(run.id, { status: "failed", error: message }).catch(() => {});
   }
 }
-async function main() {
-  const configPath = process.argv[2] ?? process.env.ITSAPLAN_RUNNER_CONFIG ?? "./itsaplan-runner.json";
-  const config = await loadConfig(configPath);
-  const client = new Client(config);
-  const active = new Set;
-  let stopping = false;
-  for (const signal of ["SIGINT", "SIGTERM"]) {
-    process.on(signal, () => {
-      if (stopping) {
-        log("quitting now — the commands in flight keep running, their runs are retried");
-        process.exit(1);
-      }
-      stopping = true;
-      log("stopping — finishing the tasks in flight, press again to quit now");
-    });
+async function handleChat(config, client, message) {
+  log(`chat ${message.id}: answering`);
+  try {
+    await withHeartbeat(() => client.chatHeartbeat(message.id), answer(config, client, message));
+    log(`chat ${message.id}: answered`);
+  } catch (err) {
+    const text = err instanceof Error ? err.message : String(err);
+    log(`chat ${message.id}: runner error — ${text}`);
+    await client.chatResult(message.id, { status: "failed", error: text }).catch(() => {});
   }
-  log(`polling ${config.url} every ${config.pollIntervalMs}ms, up to ${config.concurrency} at once`);
-  while (!stopping) {
-    if (active.size >= config.concurrency) {
+}
+async function drain(state, concurrency, take, run, onEmpty) {
+  const active = new Set;
+  let done = false;
+  while (!state.stopping && !done) {
+    if (active.size >= concurrency) {
       await Promise.race(active);
       continue;
     }
-    let run = null;
+    let item = null;
     try {
-      run = await client.claim();
+      item = await take();
     } catch (err) {
       if (err instanceof RequestError && (err.status === 401 || err.status === 403))
         throw err;
       log(`claim failed: ${String(err)}`);
+      await sleep(ERROR_BACKOFF_MS);
+      continue;
     }
-    if (!run) {
-      await sleep(config.pollIntervalMs);
+    if (!item) {
+      done = !await onEmpty();
       continue;
     }
-    const task = handle(config, client, run).finally(() => active.delete(task));
+    const task = run(item).finally(() => active.delete(task));
     active.add(task);
   }
   await Promise.all(active);
 }
+function parseArgv(argv) {
+  const parsed = { args: [] };
+  for (let i = 0;i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--") {
+      parsed.args = argv.slice(i + 1);
+      break;
+    }
+    if (arg === "--agent") {
+      const value = argv[++i];
+      if (value === undefined)
+        throw new Error("--agent needs a value");
+      parsed.agent = value;
+      continue;
+    }
+    if (arg.startsWith("--agent=")) {
+      parsed.agent = arg.slice("--agent=".length);
+      continue;
+    }
+    if (arg.startsWith("-"))
+      throw new Error(`unknown option ${arg}`);
+    parsed.configPath ??= arg;
+  }
+  return parsed;
+}
+async function main() {
+  const cli = parseArgv(process.argv.slice(2));
+  const configPath = cli.configPath ?? process.env.ITSAPLAN_RUNNER_CONFIG ?? "./itsaplan-runner.json";
+  const config = await loadConfig(configPath, { agent: cli.agent, args: cli.args });
+  const client = new Client(config);
+  const state = { stopping: false };
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.on(signal, () => {
+      if (state.stopping) {
+        log("quitting now — the commands in flight keep running, their runs are retried");
+        process.exit(1);
+      }
+      state.stopping = true;
+      log("stopping — finishing the tasks in flight, press again to quit now");
+    });
+  }
+  log(`running ${config.agent ?? "the configured command"}, polling ${config.url} every ` + `${config.pollIntervalMs}ms, up to ${config.concurrency} at once`);
+  let chatSupported = true;
+  await Promise.all([
+    drain(state, config.concurrency, () => client.claim(), (run) => handle(config, client, run), async () => {
+      await sleep(config.pollIntervalMs);
+      return true;
+    }),
+    drain(state, config.concurrency, async () => {
+      try {
+        return await client.claimChat();
+      } catch (err) {
+        if (err instanceof RequestError && err.status === 404) {
+          log("this instance has no chat feed — only queued runs will be answered");
+          chatSupported = false;
+          return null;
+        }
+        throw err;
+      }
+    }, (message) => handleChat(config, client, message), () => Promise.resolve(chatSupported))
+  ]);
+}
 main().catch((err) => {
   console.error(`[itsaplan-runner] ${err instanceof Error ? err.message : String(err)}`);
   process.exit(1);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@itsaplan/runner",
-  "version": "0.1.0",
-  "description": "Runs an Itsaplan external agent's queued tasks on your own machine",
+  "version": "0.2.1",
+  "description": "Runs an Itsaplan external agent's queued tasks and answers its chat on your own machine",
   "keywords": [
     "itsaplan",
     "ai-agents",
@@ -45,10 +45,12 @@
     "build": "bun build src/cli.ts --target=node --outfile dist/cli.js",
     "prepublishOnly": "bun run build",
     "lint": "eslint .",
-    "typecheck": "tsc --noEmit"
+    "test": "bun test",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json"
   },
   "devDependencies": {
     "@repo/eslint-config": "workspace:*",
+    "@types/bun": "latest",
     "@types/node": "^26.2.0",
     "eslint": "^9.39.0",
     "typescript": "^6.0.3"