orbit-runner 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +69 -0
- package/dist/index.js +1445 -0
- package/package.json +37 -0
package/README.md
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# orbit-runner
|
|
2
|
+
|
|
3
|
+
Turn **agent-ready** Orbit tasks into headless Claude Code sessions on your own
|
|
4
|
+
Claude subscription — no Anthropic API key. Flag a task in Orbit and the runner
|
|
5
|
+
picks it up, spins up a session in an isolated git worktree, and streams the
|
|
6
|
+
work back to Orbit's Agents and Orchestration pages.
|
|
7
|
+
|
|
8
|
+
Published to npm as `orbit-runner`. One command to set up:
|
|
9
|
+
|
|
10
|
+
```sh
|
|
11
|
+
bunx orbit-runner init # or: npm i -g orbit-runner && orbit-runner init
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
`init` verifies your key, maps your Orbit projects to local repos, and — unless
|
|
15
|
+
you pass `--no-plugin` — sets up the Orbit plugin + MCP in your interactive
|
|
16
|
+
Claude Code (user scope), so `/orbit:tasks` and the workflow skill are available
|
|
17
|
+
everywhere. Pass the key non-interactively with `--key`, or let the Orbit web
|
|
18
|
+
app hand you the full line from **Settings → Agents → Add runner**.
|
|
19
|
+
|
|
20
|
+
## Commands
|
|
21
|
+
|
|
22
|
+
| Command | What it does |
|
|
23
|
+
| --- | --- |
|
|
24
|
+
| `init` | Interactive setup: key, project→repo map, and (opt-out) Claude Code wiring. `--key <key>`, `--no-plugin`. |
|
|
25
|
+
| `doctor` | Check the environment: `claude` present, config valid, key works, repos trusted + allowlisted. |
|
|
26
|
+
| `start` | Start the daemon. `--project`, `--foreground`, `--follow`, `--model`, `--effort`. |
|
|
27
|
+
| `stop` / `status` / `logs` | Manage and observe running instances. |
|
|
28
|
+
|
|
29
|
+
The URL is fixed (`https://api.orbitagents.dev`); set `ORBIT_API_URL` only for
|
|
30
|
+
local development against a dev API.
|
|
31
|
+
|
|
32
|
+
## How it works
|
|
33
|
+
|
|
34
|
+
- **Discovery** — polls `get_next_task` per mapped project: the highest-priority
|
|
35
|
+
agent-ready, unclaimed, unblocked, conflict-free task.
|
|
36
|
+
- **Isolation** — creates a git worktree on `orbit/<task>` off `origin/HEAD`, so
|
|
37
|
+
Orbit's GitHub integration links the branch and PR to the task.
|
|
38
|
+
- **Self-contained sessions** — spawns `claude -p … --mcp-config … --strict-mcp-config`,
|
|
39
|
+
so each session gets Orbit's MCP tools without relying on any global install.
|
|
40
|
+
- **Presence** — POSTs `/api/runner/heartbeat` (`@orbit/shared`'s
|
|
41
|
+
`runnerHeartbeatSchema`) so the fleet strip shows slots, status, and pauses.
|
|
42
|
+
- **Usage limits** — pauses new dispatch until the reported reset, leaving
|
|
43
|
+
running sessions alone.
|
|
44
|
+
|
|
45
|
+
## Config
|
|
46
|
+
|
|
47
|
+
`~/.config/orbit-runner/config.json` (same format as the reference Python
|
|
48
|
+
runner, so existing files keep working). Managed by `init`; edit by hand for
|
|
49
|
+
advanced fields (`max_slots`, `poll_interval_seconds`, per-project `model`/
|
|
50
|
+
`effort`, alternate `repos`).
|
|
51
|
+
|
|
52
|
+
## Development
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
bun run dev -- doctor # run the CLI from source
|
|
56
|
+
bun run typecheck
|
|
57
|
+
bun run build # bundle to dist/ (bundles @orbit/shared)
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
> **Status:** `init`, `doctor`, the Orbit client, and the dispatch daemon
|
|
61
|
+
> (`start`/`stop`/`status`/`logs`, including background daemonization, worktree
|
|
62
|
+
> isolation, heartbeats, and usage-limit pauses) are implemented. Ported from
|
|
63
|
+
> `scripts/orbit-runner/orbit-runner.py` in
|
|
64
|
+
> [rafaelszago/orbit-plugin](https://github.com/rafaelszago/orbit-plugin), with
|
|
65
|
+
> two additions: sessions are handed Orbit's MCP inline
|
|
66
|
+
> (`--mcp-config … --strict-mcp-config`) so they need no global install, and the
|
|
67
|
+
> runner reports presence to the fleet strip. Not yet ported: `service install`
|
|
68
|
+
> (launchd/systemd) for start-at-login, and a `--config` flag for alternate
|
|
69
|
+
> config paths.
|