@rethinkingstudio/agent-runner 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rethinking Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# @rethinkingstudio/agent-runner
+
+Starts your coding agent when a job lands on your [Doable](https://doable.rethinking.art)
+Agent Desk, so work you hand off from your phone gets picked up in seconds
+instead of waiting until you sit down and ask.
+
+MIT. It runs on your machine with access to your code — nobody should run a
+closed binary for that.
+
+## Why anything has to run locally
+
+MCP is pull-only, and `claude mcp add` registers a server without starting a
+process. But the deeper reason is simpler: **coding agents have no inbox.**
+Claude Code, Cursor, Codex — none of them can be told "start working" while
+idle. They are invoked, not addressed.
+
+So something local has to be able to *start* a session. This is that something,
+and it is deliberately dumb: it notices queued work and shells out. It holds no
+state and makes no decisions about the work.
+
+## Setting it up
+
+Ask your agent, in the directory the jobs are about:
+
+> Set up the Doable runner on this machine.
+
+It calls the `setup_runner` MCP tool, gets a command back, and runs it. You never
+touch a terminal. Or do it yourself:
+
+```
+npx -y @rethinkingstudio/agent-runner install --token dbl_… --cwd ~/code/app --name mac-studio
+```
+
+| | |
+|---|---|
+| `install` | Write settings, register a launchd (macOS) or systemd (Linux) service, start it |
+| `watch` | Run in the foreground instead |
+| `status` | What it is configured to do, and whether it is running |
+| `uninstall` | Stop and remove the service |
+
+Settings live in `~/.doable/runner.json`, mode 600 — outside any repo, because
+the token is a credential and `git add -A` should not be able to reach it.
+
+## The default tool list is narrow on purpose
+
+```
+mcp__doable__*,Read,Glob,Grep,WebFetch,WebSearch
+```
+
+No Write, no Edit, no Bash. These sessions run with nobody watching, so the
+default is what a research or writing job needs, and anything that changes files
+is something you opt into:
+
+```
+npx @rethinkingstudio/agent-runner install --tools "mcp__doable__*,Read,Edit,Write,Bash" …
+```
+
+Widen it once you are comfortable with what gets started here, not before.
+
+## Any agent, not just Claude Code
+
+The desk speaks MCP, so anything that speaks MCP can work it. `--exec` is a
+plain shell command, and the prompt arrives **on stdin and in `$DOABLE_PROMPT`**,
+because CLIs disagree about which they want and neither needs quoting.
+
+```
+npx @rethinkingstudio/agent-runner install --exec 'codex exec "$DOABLE_PROMPT"' …
+npx @rethinkingstudio/agent-runner install --exec 'my-agent --stdin' …
+```
+
+If your agent has no headless mode — a GUI-only assistant — this is not for you,
+and nothing is lost: connect it over MCP and work the desk by asking, which is
+the default mode anyway.
+
+## How it watches
+
+Long polling. `GET /api/agent/events` is held open for ~25s and answers the
+moment the desk moves, so latency is about a second while idle costs one parked
+HTTP request. Against a cron recipe that wakes a session every 30 minutes to
+find nothing, this is both faster and cheaper.
+
+The polling has not disappeared — it moved to the server, where a database read
+is cheap.
+
+## What it will not do
+
+- **Run two sessions at once.** The desk allows one job per machine; a second
+  would only be refused.
+- **Decide anything about the work.** It passes a fixed prompt and gets out of
+  the way. The guardrails — one job, report progress, obey an abort, never mark
+  anything done — live in that prompt and in the server's rules.
+- **Keep going on a revoked token.** A 401 exits rather than looping. Revoke a
+  machine from Account & agents in the app and it stops.
+
+## Turning it off
+
+```
+npx @rethinkingstudio/agent-runner uninstall
+rm ~/.doable/runner.json
+```
+
+Then revoke the machine in the app, which invalidates the token server-side.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@rethinkingstudio/agent-runner",
+  "version": "0.1.0",
+  "description": "Starts your coding agent when a job lands on your Doable Agent Desk.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "doable-agent-runner": "src/cli.mjs"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rethinking-studio/doable-agent-runner.git"
+  },
+  "keywords": [
+    "mcp",
+    "agent",
+    "claude",
+    "doable"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://doable.rethinking.art",
+  "bugs": {
+    "url": "https://github.com/Rethinking-studio/doable-agent-runner/issues"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+//
+//   doable-agent-runner install --token dbl_… --cwd ~/code/app --name mac-studio
+//   doable-agent-runner watch          run in the foreground
+//   doable-agent-runner status
+//   doable-agent-runner uninstall
+//
+// `install` is what the agent runs after calling setup_runner. Everything else
+// is for a human who wants to see or undo what it did.
+
+import { spawnSync } from "node:child_process";
+import { writeFileSync, unlinkSync, existsSync, mkdirSync, cpSync, rmSync } from "node:fs";
+import { homedir, hostname, platform } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as config from "./config.mjs";
+
+const LABEL = "art.rethinking.doable.runner";
+const HERE = fileURLToPath(new URL(".", import.meta.url));
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > -1 ? process.argv[i + 1] : fallback;
+}
+
+const command = process.argv[2] || "watch";
+
+switch (command) {
+  case "install":
+    install();
+    break;
+  case "watch":
+    await import("./watch.mjs");
+    break;
+  case "status":
+    status();
+    break;
+  case "uninstall":
+    uninstall();
+    break;
+  default:
+    console.log("Usage: doable-agent-runner <install|watch|status|uninstall>");
+    process.exit(1);
+}
+
+function install() {
+  const token = arg("token") || config.load().token;
+  if (!token) {
+    console.error("A token is required. Ask your agent to call setup_runner.");
+    process.exit(1);
+  }
+
+  const settings = {
+    token,
+    base: arg("base", config.DEFAULT_BASE),
+    cwd: arg("cwd", process.cwd()),
+    name: arg("name", hostname().replace(/\.local$/, "")),
+    // Deliberately narrow. These sessions run with nobody watching, so the
+    // default is what a research or writing job needs, and anything that
+    // changes files is opted into rather than assumed.
+    tools: arg("tools", "mcp__doable__*,Read,Glob,Grep,WebFetch,WebSearch"),
+    exec: arg("exec", ""),
+  };
+
+  const path = config.save(settings);
+  const runtime = installRuntime();
+  console.log(`Settings written to ${path}`);
+  console.log(`Machine name: ${settings.name}`);
+  console.log(`Working directory: ${settings.cwd}`);
+  console.log(`Tools the unattended session may use: ${settings.tools}`);
+  console.log(
+    "\nThat tool list is narrow on purpose — no Write, no Edit, no Bash. Re-run with\n" +
+      "--tools to widen it once you are comfortable with what gets started here."
+  );
+
+  platform() === "darwin" ? installLaunchd(runtime) : installSystemd(runtime);
+}
+
+/// Copies the runner somewhere stable and returns the entry point to point the
+/// service at. Without this the service would reference wherever the installer
+/// happened to run from — under npx, a cache directory with no guarantees.
+function installRuntime() {
+  if (HERE.startsWith(config.RUNTIME)) return join(config.RUNTIME, "cli.mjs");
+  rmSync(config.RUNTIME, { recursive: true, force: true });
+  mkdirSync(config.RUNTIME, { recursive: true });
+  cpSync(HERE, config.RUNTIME, { recursive: true });
+  return join(config.RUNTIME, "cli.mjs");
+}
+
+function installLaunchd(entry) {
+  const dir = join(homedir(), "Library", "LaunchAgents");
+  mkdirSync(dir, { recursive: true });
+  const plist = join(dir, `${LABEL}.plist`);
+  writeFileSync(
+    plist,
+    `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${process.execPath}</string>
+    <string>${entry}</string>
+    <string>watch</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <!-- The watch dies when the lid closes; launchd brings it back on wake. -->
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>/tmp/doable-runner.log</string>
+  <key>StandardErrorPath</key><string>/tmp/doable-runner.log</string>
+</dict>
+</plist>
+`
+  );
+  // launchd tears a job down asynchronously, so bootstrapping straight after a
+  // bootout races it and fails. Retry rather than reporting a failure the user
+  // would only have to work around by hand.
+  spawnSync("launchctl", ["bootout", `gui/${process.getuid()}/${LABEL}`], { stdio: "ignore" });
+  let r;
+  for (let attempt = 0; attempt < 5; attempt++) {
+    r = spawnSync("launchctl", ["bootstrap", `gui/${process.getuid()}`, plist], {
+      stdio: attempt === 4 ? "inherit" : "ignore",
+    });
+    if (r.status === 0) break;
+    spawnSync("sleep", ["1"]);
+  }
+  console.log(
+    r.status === 0
+      ? `\nRunning. Logs: /tmp/doable-runner.log`
+      : `\nWrote ${plist} but could not load it. Start it by hand:\n  launchctl bootstrap gui/$(id -u) ${plist}`
+  );
+}
+
+function installSystemd(entry) {
+  const dir = join(homedir(), ".config", "systemd", "user");
+  mkdirSync(dir, { recursive: true });
+  const unit = join(dir, "doable-runner.service");
+  writeFileSync(
+    unit,
+    `[Unit]
+Description=Doable Agent Desk runner
+
+[Service]
+ExecStart=${process.execPath} ${entry} watch
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+`
+  );
+  spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
+  const r = spawnSync("systemctl", ["--user", "enable", "--now", "doable-runner"], {
+    stdio: "inherit",
+  });
+  console.log(
+    r.status === 0
+      ? "\nRunning. Logs: journalctl --user -u doable-runner -f"
+      : `\nWrote ${unit} but could not start it:\n  systemctl --user enable --now doable-runner`
+  );
+}
+
+function status() {
+  const settings = config.load();
+  if (!settings.token) return console.log("Not set up. Ask your agent to call setup_runner.");
+  console.log(`Machine name : ${settings.name}`);
+  console.log(`Directory    : ${settings.cwd}`);
+  console.log(`Tools        : ${settings.tools}`);
+  console.log(`Starts       : ${settings.exec || "claude (default)"}`);
+  if (platform() === "darwin") {
+    spawnSync("launchctl", ["print", `gui/${process.getuid()}/${LABEL}`], { stdio: "inherit" });
+  } else {
+    spawnSync("systemctl", ["--user", "status", "doable-runner"], { stdio: "inherit" });
+  }
+}
+
+function uninstall() {
+  if (platform() === "darwin") {
+    spawnSync("launchctl", ["bootout", `gui/${process.getuid()}/${LABEL}`], { stdio: "ignore" });
+    const plist = join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+    if (existsSync(plist)) unlinkSync(plist);
+  } else {
+    spawnSync("systemctl", ["--user", "disable", "--now", "doable-runner"], { stdio: "ignore" });
+  }
+  rmSync(config.RUNTIME, { recursive: true, force: true });
+  console.log(
+    "Stopped and removed.\n" +
+      `Settings are still at ${config.FILE} — delete it to remove the token, and revoke\n` +
+      "this machine from Account & agents in the app."
+  );
+}

package/src/config.mjs

@@ -0,0 +1,33 @@
+// Where the runner keeps its token and settings. Deliberately outside any repo:
+// this is a credential, and it should not be somewhere a `git add -A` can reach.
+
+import { mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const DIR = join(homedir(), ".doable");
+export const FILE = join(DIR, "runner.json");
+/// Where `install` copies the runner to. The service must point at a path that
+/// outlives the installer: run through npx and the code sits in a cache
+/// directory that can be cleared at any time, which would leave a launchd job
+/// aimed at a file that no longer exists — failing silently, which is the worst
+/// way for a background process to fail.
+export const RUNTIME = join(DIR, "runner");
+
+export const DEFAULT_BASE = "https://doable.rethinking.art/api/agent";
+
+export function load() {
+  try {
+    return JSON.parse(readFileSync(FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+export function save(config) {
+  mkdirSync(DIR, { recursive: true });
+  writeFileSync(FILE, JSON.stringify(config, null, 2));
+  // The token lives in here.
+  chmodSync(FILE, 0o600);
+  return FILE;
+}

package/src/watch.mjs

@@ -0,0 +1,137 @@
+//
+// Watches the Agent Desk and starts a Claude Code session when work shows up.
+//
+// This is the piece that makes "hand it off from your phone and the machine
+// starts working" true. MCP is pull-only — the desk cannot reach into a laptop
+// and start anything — so something local has to be listening. This is that
+// something, and it is deliberately dumb: its whole job is to notice a queued
+// job and shell out. It holds no state and makes no decisions about the work.
+//
+// Idle cost is one parked HTTP request. Unlike a cron recipe it does not wake a
+// Claude session to discover there is nothing to do.
+//
+// The agent it starts is yours to choose — the desk speaks MCP, so anything
+// that speaks MCP can work it. `--exec` is a plain shell command; the prompt
+// arrives on stdin and in $DOABLE_PROMPT, so you can shape the invocation the
+// way your tool wants it.
+//
+// Settings come from ~/.doable/runner.json, written by `install`.
+
+import { spawn } from "node:child_process";
+import * as config from "./config.mjs";
+
+const settings = config.load();
+const BASE = settings.base || config.DEFAULT_BASE;
+const token = settings.token || process.env.DOABLE_TOKEN;
+const cwd = settings.cwd || process.cwd();
+const tools = settings.tools || "mcp__doable__*,Read,Glob,Grep,WebFetch,WebSearch";
+/// Defaults to Claude Code because that is what most people have, not because
+/// the desk needs it. Anything that speaks MCP can work this queue.
+const exec =
+  settings.exec ||
+  process.env.DOABLE_EXEC ||
+  `claude -p "$DOABLE_PROMPT" --allowedTools ${JSON.stringify(tools)}`;
+const PROMPT = `Check my Doable agent desk.
+
+Call list_jobs. If there is a queued job you can finish on this machine, claim
+exactly one, do the work, and submit the result.
+
+- Call report_progress every few minutes while working. If it ever returns
+  "aborted", stop immediately and submit nothing.
+- Read the workstream brief before starting. It is the context the job title
+  leaves out.
+- If a job was sent back, its feedback says what to fix. Read it.
+- If nothing is queued, or nothing here is something you can do on this machine,
+  say so and exit without claiming anything.`;
+
+if (!token) {
+  console.error("Not set up. Ask your agent to call setup_runner, then run `install`.");
+  process.exit(1);
+}
+
+const log = (...a) => console.log(new Date().toISOString(), ...a);
+
+/// True while a session is running. The desk allows one job per machine anyway,
+/// so starting a second session would only produce an agent that gets refused.
+let busy = false;
+
+function runSession() {
+  if (busy) return;
+  busy = true;
+  log("work on the desk — starting a session");
+  // Through a shell so `--exec` can be whatever the user's agent needs. The
+  // prompt is handed over twice — on stdin and in the environment — because
+  // CLIs disagree about which they prefer, and neither way needs quoting.
+  const child = spawn("/bin/sh", ["-c", exec], {
+    cwd,
+    env: { ...process.env, DOABLE_PROMPT: PROMPT },
+    stdio: ["pipe", "inherit", "inherit"],
+  });
+  child.stdin?.end(PROMPT);
+  child.on("exit", (code) => {
+    busy = false;
+    log(`session exited (${code})`);
+  });
+  child.on("error", (e) => {
+    busy = false;
+    log("could not start the agent:", e.message);
+  });
+}
+
+/// The OAuth handshake only tells the desk which software connected, so every
+/// machine running the same tool shows up under the same name. Saying which
+/// machine this is restores the point of the heartbeat.
+async function announce() {
+  try {
+    const res = await fetch(`${BASE}/agent/label`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ label: settings.name }),
+    });
+    if (res.ok) log(`named this machine ${(await res.json()).label}`);
+  } catch {
+    // Cosmetic. Never worth failing to start over.
+  }
+}
+
+let version = "";
+
+async function watch() {
+  for (;;) {
+    try {
+      const res = await fetch(`${BASE}/events?v=${encodeURIComponent(version)}`, {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+
+      if (res.status === 401) {
+        log("token rejected — reconnect the agent with `claude mcp add`");
+        process.exit(1);
+      }
+      if (!res.ok) {
+        log(`desk answered ${res.status}, retrying in 30s`);
+        await sleep(30_000);
+        continue;
+      }
+
+      const event = await res.json();
+      version = event.version;
+
+      // A timeout is the normal case: nothing moved, ask again.
+      if (!event.changed) continue;
+
+      const queued = event.desk?.queued ?? [];
+      if (queued.length) runSession();
+      else log("desk changed but nothing is queued");
+    } catch (e) {
+      // Sleep, laptop lid, flaky wifi — none of these deserve a crash.
+      log("watch failed:", e.message, "— retrying in 15s");
+      await sleep(15_000);
+    }
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+log(`watching ${BASE} — will run \`${exec}\` in ${cwd}`);
+await announce();
+watch();