@itsaplan/runner 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 VIBE DEV SPACE LLC
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,284 @@
+# @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.
+
+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.
+
+## 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.
+
+**2. Write `itsaplan-runner.json`** in the folder you want the agent to work in:
+
+```json
+{
+  "url": "http://localhost:3000",
+  "apiKey": "the key you just copied",
+  "command": "claude -p"
+}
+```
+
+**3. Start it:**
+
+```bash
+npx -y @itsaplan/runner
+```
+
+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.
+
+`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
+```
+
+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:
+
+```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:
+
+| 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                                 |
+
+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.
+
+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.
+
+## Claude Code
+
+`mcp.json`, next to the runner config:
+
+```json
+{
+  "mcpServers": {
+    "itsaplan": {
+      "type": "http",
+      "url": "http://localhost:3000/mcp",
+      "headers": { "Authorization": "Bearer ${ITSAPLAN_API_KEY}" }
+    }
+  }
+}
+```
+
+`itsaplan-runner.json`:
+
+```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"
+}
+```
+
+- `--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.
+
+## Codex
+
+Codex reads its MCP servers from `~/.codex/config.toml`, and `bearer_token_env_var`
+takes the key from the environment the runner already sets:
+
+```toml
+[mcp_servers.itsaplan]
+url = "http://localhost:3000/mcp"
+bearer_token_env_var = "ITSAPLAN_API_KEY"
+```
+
+`itsaplan-runner.json`:
+
+```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"
+}
+```
+
+- 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.
+
+## Gemini CLI
+
+`.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:
+
+```json
+{
+  "mcpServers": {
+    "itsaplan": {
+      "httpUrl": "http://localhost:3000/mcp",
+      "headers": { "Authorization": "Bearer $ITSAPLAN_API_KEY" },
+      "trust": true
+    }
+  }
+}
+```
+
+`itsaplan-runner.json`:
+
+```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"
+}
+```
+
+- 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.
+
+## GitHub Copilot CLI
+
+`.mcp.json` in the working directory. Copilot's headers take no variable
+interpolation, so the key goes in as it stands:
+
+```json
+{
+  "mcpServers": {
+    "itsaplan": {
+      "type": "http",
+      "url": "http://localhost:3000/mcp",
+      "headers": { "Authorization": "Bearer the-agent-key" },
+      "tools": ["*"]
+    }
+  }
+}
+```
+
+`itsaplan-runner.json`:
+
+```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"
+}
+```
+
+- 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.
+
+## opencode
+
+`opencode.json` in the working directory. opencode interpolates `{env:VAR}`, so the key
+stays out of the file:
+
+```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}" }
+    }
+  }
+}
+```
+
+`itsaplan-runner.json`:
+
+```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"
+}
+```
+
+- `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.
+
+## Requirements
+
+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.
+
+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.
+
+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.
+
+Windows needs WSL2, because `cmd.exe` and PowerShell have no `sh`:
+
+```powershell
+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:
+
+- 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`.
+
+## License
+
+Copyright © 2026 VIBE DEV SPACE LLC.
+
+[Apache-2.0](LICENSE).

package/dist/cli.js

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { setTimeout as sleep } from "node:timers/promises";
+
+// src/client.ts
+var REQUEST_TIMEOUT_MS = 30000;
+
+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) {
+    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)}`);
+    }
+    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);
+  }
+}
+
+// src/config.ts
+import { readFile } from "node:fs/promises";
+var DEFAULTS = {
+  concurrency: 1,
+  pollIntervalMs: 3000,
+  timeoutMs: 30 * 60 * 1000
+};
+var MIN_POLL_INTERVAL_MS = 1000;
+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 required(value, field) {
+  const text = typeof value === "string" ? value.trim() : "";
+  if (!text)
+    throw new Error(`${field} is required — set it in the config file or the environment`);
+  return text;
+}
+async function readConfigFile(path) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return {};
+    throw err;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${path} is not valid JSON`);
+  }
+}
+async function loadConfig(path) {
+  const raw = await readConfigFile(path);
+  const env = process.env;
+  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"),
+    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)
+  };
+}
+
+// src/execute.ts
+import { spawn } from "node:child_process";
+var OUTPUT_LIMIT = 8000;
+var ERROR_LIMIT = 400;
+function tail(text, limit) {
+  return text.length <= limit ? text : `…${text.slice(-limit)}`;
+}
+function childEnv(config, run) {
+  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)
+  };
+}
+function killGroup(pid) {
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch {}
+}
+async function execute(config, run) {
+  const child = spawn("sh", ["-c", config.command], {
+    cwd: config.cwd,
+    env: childEnv(config, run),
+    detached: true
+  });
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    if (child.pid !== undefined)
+      killGroup(child.pid);
+  }, config.timeoutMs);
+  let stdout = "";
+  let stderr = "";
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+  child.stdout.on("data", (chunk) => {
+    stdout = tail(stdout + chunk, OUTPUT_LIMIT);
+  });
+  child.stderr.on("data", (chunk) => {
+    stderr = tail(stderr + chunk, ERROR_LIMIT);
+  });
+  child.stdin.on("error", () => {});
+  child.stdin.end(run.prompt);
+  const exited = new Promise((resolve, reject) => {
+    child.on("error", reject);
+    child.on("close", (exitCode, exitSignal) => resolve({ code: exitCode, signal: exitSignal }));
+  });
+  let code;
+  let signal;
+  try {
+    ({ code, signal } = await exited);
+  } finally {
+    clearTimeout(timer);
+  }
+  const output = stdout.trim();
+  if (code === 0)
+    return { status: "success", output };
+  if (timedOut)
+    return { status: "failed", output, error: `Timed out after ${config.timeoutMs}ms` };
+  return {
+    status: "failed",
+    output,
+    error: stderr.trim() || (signal ? `Command killed by ${signal}` : `Command exited with ${code}`)
+  };
+}
+
+// src/cli.ts
+var HEARTBEAT_MS = 60000;
+function log(message) {
+  console.log(`[itsaplan-runner] ${message}`);
+}
+async function withHeartbeat(client, runId, work) {
+  const timer = setInterval(() => {
+    client.heartbeat(runId).catch((err) => log(`heartbeat failed: ${String(err)}`));
+  }, HEARTBEAT_MS);
+  try {
+    return await work;
+  } finally {
+    clearInterval(timer);
+  }
+}
+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));
+    await client.report(run.id, outcome);
+    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(() => {});
+  }
+}
+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");
+    });
+  }
+  log(`polling ${config.url} every ${config.pollIntervalMs}ms, up to ${config.concurrency} at once`);
+  while (!stopping) {
+    if (active.size >= config.concurrency) {
+      await Promise.race(active);
+      continue;
+    }
+    let run = null;
+    try {
+      run = await client.claim();
+    } catch (err) {
+      if (err instanceof RequestError && (err.status === 401 || err.status === 403))
+        throw err;
+      log(`claim failed: ${String(err)}`);
+    }
+    if (!run) {
+      await sleep(config.pollIntervalMs);
+      continue;
+    }
+    const task = handle(config, client, run).finally(() => active.delete(task));
+    active.add(task);
+  }
+  await Promise.all(active);
+}
+main().catch((err) => {
+  console.error(`[itsaplan-runner] ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@itsaplan/runner",
+  "version": "0.1.0",
+  "description": "Runs an Itsaplan external agent's queued tasks on your own machine",
+  "keywords": [
+    "itsaplan",
+    "ai-agents",
+    "agentic",
+    "agent",
+    "runner",
+    "cli",
+    "self-hosted",
+    "open-source",
+    "project-management",
+    "issue-tracker",
+    "jira-alternative",
+    "linear-alternative",
+    "claude-code",
+    "codex",
+    "gemini-cli",
+    "opencode"
+  ],
+  "homepage": "https://github.com/croffasia/itsaplan/tree/main/packages/runner#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/croffasia/itsaplan.git",
+    "directory": "packages/runner"
+  },
+  "bugs": "https://github.com/croffasia/itsaplan/issues",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "itsaplan-runner": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build src/cli.ts --target=node --outfile dist/cli.js",
+    "prepublishOnly": "bun run build",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "workspace:*",
+    "@types/node": "^26.2.0",
+    "eslint": "^9.39.0",
+    "typescript": "^6.0.3"
+  }
+}