@itsaplan/runner 0.6.0 → 0.7.0

package/README.md

@@ -11,6 +11,7 @@ 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).
 
@@ -107,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
 {
@@ -120,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
 {
@@ -144,12 +144,11 @@ 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
 
@@ -157,8 +156,8 @@ By default the runner polls the instance for tasks. With `listen`, the instance
 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, and the chat is equally fast with it: a chat
-claim waits on the server until a message comes.
+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
@@ -243,23 +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                                 |
-| `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`                 |
+| `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:
 
@@ -274,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.
@@ -290,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:
 
@@ -314,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
 
@@ -348,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. `listen` needs 1.6.0.
+- **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.

package/dist/cli.js

@@ -40,12 +40,20 @@ class Client {
     const body = await res.json();
     return body.run;
   }
-  async heartbeat(runId) {
-    await this.post(`/agent-runs/${runId}/heartbeat`);
+  async heartbeat(runId, attempt) {
+    await this.post(`/agent-runs/${runId}/heartbeat`, attempt == null ? undefined : { attempt });
   }
   async report(runId, result) {
     await this.post(`/agent-runs/${runId}/result`, result);
   }
+  async runEvents(run, offset, events, sessionId) {
+    await this.post(`/agent-runs/${run.id}/events`, {
+      attempt: run.attempts,
+      offset,
+      events,
+      ...sessionId && { sessionId }
+    });
+  }
   async claimChat() {
     const res = await this.post("/agent-chats/claim", undefined, CHAT_CLAIM_TIMEOUT_MS);
     const body = await res.json();
@@ -114,7 +122,7 @@ var PRESETS = {
       "json",
       ...sessionId ? ["--session", sessionId] : []
     ],
-    tail: []
+    tail: ["--"]
   },
   antigravity: {
     bin: "agy",
@@ -146,7 +154,7 @@ var PRESETS = {
   pi: {
     bin: "pi",
     outputFormat: "pi-json",
-    promptVia: "arg",
+    promptVia: "stdin",
     systemPromptFlag: "--append-system-prompt",
     head: (sessionId) => [
       "-p",
@@ -168,7 +176,7 @@ var PRESETS = {
       "--auto-approve",
       ...sessionId ? ["--resume", sessionId] : []
     ],
-    tail: []
+    tail: ["--"]
   }
 };
 var PRESET_NAMES = Object.keys(PRESETS);
@@ -538,6 +546,8 @@ class AnswerStream {
   closedToolCalls = new Set;
   sawPartialText = false;
   sawAnyText = false;
+  segment = "";
+  lastSegment = "";
   sending = Promise.resolve();
   usage;
   constructor(format, threadId, runId, send) {
@@ -564,6 +574,9 @@ class AnswerStream {
   startedSession() {
     return this.sessionId;
   }
+  answer() {
+    return (this.segment.trim() ? this.segment : this.lastSegment).trim();
+  }
   contextUsage() {
     return this.usage.value();
   }
@@ -612,6 +625,7 @@ class AnswerStream {
       return;
     this.sawAnyText = true;
     this.text += text;
+    this.segment += text;
     if (this.text.length >= FLUSH_CHARS)
       this.drainText();
   }
@@ -774,15 +788,36 @@ class AnswerStream {
       return;
     }
     const item = message.item;
-    if (message.type !== "item.completed" || !item)
+    if (!item)
       return;
-    if (item.type === "agent_message" && item.text) {
+    if (message.type === "item.completed" && 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 ?? "");
+    if (!item.id || !["command_execution", "mcp_tool_call", "file_change", "web_search"].includes(item.type ?? ""))
+      return;
+    if (!["item.started", "item.completed"].includes(message.type ?? ""))
+      return;
+    if (!this.openToolCalls.has(item.id)) {
+      this.openToolCalls.add(item.id);
+      const name = item.type === "command_execution" ? "shell" : item.tool ?? item.type ?? "tool";
+      const args = item.command ?? JSON.stringify(item.arguments ?? item.changes ?? { query: item.query });
+      this.pushToolCall(item.id, name, args);
+    }
+    if (message.type === "item.completed" && !this.closedToolCalls.has(item.id)) {
+      this.closedToolCalls.add(item.id);
+      let result = item.aggregated_output;
+      if (result == null || item.status === "failed" || item.exit_code != null && item.exit_code !== 0) {
+        result = JSON.stringify({
+          status: item.status,
+          exitCode: item.exit_code,
+          output: item.aggregated_output,
+          result: item.result,
+          error: item.error,
+          changes: item.changes
+        });
+      }
+      this.pushToolResult(item.id, result);
     }
   }
   readOpencodeLine(message) {
@@ -860,10 +895,17 @@ class AnswerStream {
   }
   pushToolCall(toolCallId, toolCallName, args) {
     this.drainText();
+    this.closeSegment();
     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 });
   }
+  closeSegment() {
+    if (this.segment.trim())
+      this.lastSegment = this.segment;
+    this.segment = "";
+  }
   pushToolResult(toolCallId, content) {
     this.drainText();
+    this.closeSegment();
     this.queued.push({
       type: "TOOL_CALL_RESULT",
       messageId: this.messageId,
@@ -1138,6 +1180,78 @@ async function answer(config, client, message, stop) {
   await client.chatResult(message.id, { status: "failed", error, usage: stream.contextUsage() });
 }
 
+// src/run.ts
+async function runTask(config, client, run) {
+  let offset = 0;
+  const stream = new AnswerStream(config.outputFormat, `run-${run.id}`, String(run.id), async (events) => {
+    if (!run.traceEvents)
+      return;
+    const session = config.outputFormat === "codex-jsonl" ? stream.startedSession() : null;
+    const sessionId = session && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(session) ? session : undefined;
+    for (let start = 0;start < events.length; start += 200) {
+      const batch = events.slice(start, start + 200);
+      await client.runEvents(run, offset + start, batch, sessionId);
+    }
+    offset += events.length;
+  });
+  const usage = new UsageReader(config.outputFormat);
+  const timer = setInterval(() => {
+    stream.flush().catch(() => {});
+  }, 500);
+  try {
+    const outcome = await execute(config, {
+      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)
+      }
+    }, {
+      onData: (chunk) => {
+        usage.write(chunk);
+        stream.write(chunk);
+      }
+    });
+    clearInterval(timer);
+    usage.end();
+    try {
+      if (outcome.status === "success")
+        await stream.finish(outcome.output);
+      else
+        await stream.fail(outcome.error ?? "The command failed", outcome.output);
+    } catch (error) {
+      if (!isTransientEventError(error))
+        throw error;
+      try {
+        await stream.flush();
+      } catch (retryError) {
+        if (!isTransientEventError(retryError))
+          throw retryError;
+        console.error(`Run ${run.id}: trace upload failed; reporting the command result: ${String(retryError)}`);
+      }
+    }
+    const output = config.outputFormat === "text" ? outcome.output : stream.answer();
+    await client.report(run.id, {
+      ...outcome,
+      output,
+      ...run.traceEvents && { attempt: run.attempts },
+      usage: usage.value()
+    });
+    return outcome;
+  } finally {
+    clearInterval(timer);
+  }
+}
+function isTransientEventError(error) {
+  if (error instanceof RequestError) {
+    return error.status === 408 || error.status === 429 || error.status >= 500;
+  }
+  return error instanceof TypeError || error instanceof Error && ["AbortError", "TimeoutError"].includes(error.name);
+}
+
 // src/tasks.ts
 var HEARTBEAT_MS = 60000;
 async function withHeartbeat(log, beat, work) {
@@ -1150,32 +1264,20 @@ async function withHeartbeat(log, beat, 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 handleRun(config, client, log, run) {
   const label = run.issueIdentifier ?? `run ${run.id}`;
   log(`${label}: started (${run.trigger})`);
   try {
-    const usage = new UsageReader(config.outputFormat);
-    const outcome = await withHeartbeat(log, () => client.heartbeat(run.id), execute(config, taskOf(run), { onData: (chunk) => usage.write(chunk) }));
-    usage.end();
-    await client.report(run.id, { ...outcome, usage: usage.value() });
+    const outcome = await withHeartbeat(log, () => client.heartbeat(run.id, run.traceEvents ? run.attempts : undefined), runTask(config, client, run));
     log(`${label}: ${outcome.status}${outcome.error ? ` — ${outcome.error}` : ""}`);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log(`${label}: runner error — ${message}`);
-    await client.report(run.id, { status: "failed", error: message }).catch(() => {});
+    await client.report(run.id, {
+      status: "failed",
+      error: message,
+      ...run.traceEvents && { attempt: run.attempts }
+    }).catch(() => {});
   }
 }
 async function handleChat(config, client, log, message) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itsaplan/runner",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Runs an Itsaplan external agent's queued tasks and answers its chat on your own machine",
   "keywords": [
     "itsaplan",