@npm-questionpro/agent-orchestrator-worker

Standalone Node 24 daemon that registers with the BootstrapAI Valhalla orchestration worker plane, heartbeats, claims work items, runs them in a local git worktree via Cursor CLI, executes rig checks, and reports completion.

Quick start (target repo from this monorepo)

Each profile uses start-worker-<app>.env (gitignored). Example app name: field.

cd packages/agent-orchestrator-worker
cp start-worker-field.env.example start-worker-field.env
# Edit RIG_IDS (Valhalla rig UUID) and RIG_LOCAL_PATH (clone of target repo)
./start-worker.sh field
# or: APP=field ./start-worker.sh

Add more profiles by copying the example to start-worker-<app>.env and running ./start-worker.sh <app>.

Install (target repo or worker host)

npm install -g @npm-questionpro/agent-orchestrator-worker
# or one-off:
npx @npm-questionpro/agent-orchestrator-worker

The CLI binary is valhalla-worker. From the monorepo during development:

npm run dev -w agent-orchestrator-worker

Requirements

• Node.js >= 24
• Git installed and available on PATH
• A clone of the target repo at RIG_LOCAL_PATH (the rig's local checkout)

Environment variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | ORCHESTRATION_API_URL | yes | — | Base API URL including /api prefix (e.g. http://localhost:3000/api) | | ORCHESTRATION_WORKER_KEY | yes | — | Shared worker secret; sent as x-orchestration-worker-key | | ORG_ID | yes | — | Organization id this worker serves | | RIG_IDS | yes | — | Comma-separated rig UUIDs from Valhalla → Rigs → Details (not repo name or URL) | | RIG_LOCAL_PATH | yes | — | Absolute path to the local git checkout for the rig | | WORKER_NAME | no | polecat-<pid> | Display name registered with the orchestration plane | | RUNTIME | no | local | local or cloud | | MAX_CONCURRENCY | no | 1 | Max concurrent work items for this worker | | HEARTBEAT_INTERVAL_MS | no | 15000 | Heartbeat interval in milliseconds | | CLAIM_WAIT_MS | no | 30000 | Long-poll wait for POST .../claim | | POLECAT_EXECUTOR | no | cursor-cli | cursor-cli (Cursor Agent) or echo (placeholder) | | CURSOR_AGENT_BIN | no | agent | Path to Cursor CLI binary | | CURSOR_AGENT_MODEL | no | — | Optional model slug (e.g. from agent models) | | CURSOR_AGENT_TIMEOUT_MS | no | 600000 | Max wall time per bead (10 min) | | CURSOR_AGENT_OUTPUT_FORMAT | no | stream-json | stream-json (live) or text (final only) | | CHECK_COMMAND_TIMEOUT_MS | no | 600000 | Max wall time per rig check command (10 min) | | POLECAT_TRACE | no | 1 | Set 0 to disable [trace] logs |

Cursor CLI executor

Local polecats run beads via Cursor Agent CLI in the git worktree:

agent --print --force --trust --approve-mcps --workspace <worktree> \
  --output-format stream-json --stream-partial-output "<prompt>"

Install the CLI:

curl https://cursor.com/install -fsS | bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
agent login   # or set CURSOR_API_KEY

Use POLECAT_EXECUTOR=echo only for dry runs without Cursor installed.

Worker logs mirror Cursor agent stdout/stderr live in the terminal (npm run dev -w agent-orchestrator-worker), plus rig check command output.

Output: Default stream-json streams agent/tool events live to the worker terminal and Valhalla UI. text format only prints the final answer when the agent finishes (looks like "nothing happens" for long runs).

Trace: [trace] lines show spawn, first stdout/stderr, each stream event, and API progress saves. Disable with POLECAT_TRACE=0.

Scripts

npm install
npm run dev -w agent-orchestrator-worker
npm run build -w agent-orchestrator-worker
npm run start -w agent-orchestrator-worker

Boot loop

1. POST /orchestration/workers/register
2. Heartbeat every 15s (POST /orchestration/workers/:id/heartbeat)
3. Claim loop: POST /orchestration/workers/:id/claim?waitMs=30000
4. On item: create git worktree at {RIG_LOCAL_PATH}/hooks/{workItemId} on branch valhalla/{bead-prefix}, run Cursor CLI, run rig check commands, push branch to origin, complete or fail, cleanup worktree on success

Executor modes

| Mode | Env | Use case | |------|-----|----------| | cursor-cli (default) | POLECAT_EXECUTOR=cursor-cli | Real bead execution via Cursor Agent CLI | | echo | POLECAT_EXECUTOR=echo | Dry runs without Cursor installed |

Implementation: src/local-executor.ts → src/cursor-cli-executor.ts. For programmatic SDK usage in the API, see backends/api/src/modules/coding-agents/domain/services/cursor-sdk.service.ts.

Example

export ORCHESTRATION_API_URL=http://localhost:3000/api
export ORCHESTRATION_WORKER_KEY=dev-worker-secret
export ORG_ID=75
export RIG_IDS=00000000-0000-0000-0000-000000000001
export RIG_LOCAL_PATH=/path/to/repo
valhalla-worker

Publish (maintainers)

From the monorepo root (requires npm login as @npm-questionpro publisher):

npm run build -w agent-orchestrator-worker
npm publish -w agent-orchestrator-worker