@founderos/runner 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Paperclip AI
+
+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,175 @@
+# @founderos/runner
+
+Local execution runner for [FounderOS](https://founderos.fly.dev). Polls the FounderOS cloud for queued AI-agent jobs, spawns the `claude` CLI under your existing Claude Pro subscription, streams events back, and reports completion.
+
+> **Why this exists.** FounderOS runs as a hosted control plane, but the actual LLM execution happens on _your_ machine — under _your_ authed CLI session and _your_ subscription billing. The cloud never sees your Anthropic API keys; it just enqueues work and reads back the events. See [ADR-011](https://github.com/founderos-ai/founderos/blob/main/docs/adr/011-byo-runner.md) for the full rationale.
+
+## Quickstart
+
+No install required — `npx` runs the runner directly:
+
+```bash
+npx @founderos/runner start \
+  --token=fos_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
+  --server-url=https://founderos.fly.dev
+```
+
+### Windows (PowerShell)
+
+```powershell
+npx @founderos/runner start --token=fos_xxx --server-url=https://founderos.fly.dev
+```
+
+> **Common typo:** `npm install -g @founderos/` (with a trailing slash, no
+> package name) makes npm look for a local `@founderos\package.json` and
+> fail with `ENOENT`. The package name is `@founderos/runner` — and you
+> don't actually need to install it globally; `npx` is enough.
+
+### Prerequisites
+
+- **Node.js ≥ 20** — `node --version` to check.
+- **`claude` CLI** installed and authenticated — `claude --version` should work in your shell. If you use a different LLM CLI, the multi-CLI dispatcher (PHASE-S7, in progress) will support Codex, Gemini, OpenCode, Pi, and Cursor.
+
+### Get a token
+
+Issue a runner token from the FounderOS dashboard → Settings → Runner Tokens. The plaintext is shown **once** at issuance — store it in a password manager. Tokens are scoped to a single company; revoke from the dashboard whenever a machine is decommissioned.
+
+## Install (optional)
+
+For long-running setups (a dedicated runner machine, a service file), install the binary globally instead of using `npx`:
+
+```bash
+npm install -g @founderos/runner
+founderos-runner start --token=fos_xxx --server-url=https://founderos.fly.dev
+```
+
+## Configuration reference
+
+Every option can be set via flag OR environment variable. Flags override env vars when both are present.
+
+| Flag | Env var | Required | Default | Notes |
+|---|---|---|---|---|
+| `--token=<...>` | `FOUNDEROS_RUNNER_TOKEN` | yes | — | Bearer token (`fos_<32 chars>`) |
+| `--server-url=<...>` | `FOUNDEROS_RUNNER_URL` | yes | — | e.g. `https://founderos.fly.dev` |
+| `--claude-bin=<...>` | `FOUNDEROS_CLAUDE_BIN` | no | `claude` | Override if `claude` isn't on `PATH` |
+| `--timeout-sec=<n>` | `FOUNDEROS_RUNNER_TIMEOUT_SEC` | no | `600` | Per-job hard ceiling, 1..3600 |
+| `--log-level=<...>` | `FOUNDEROS_RUNNER_LOG_LEVEL` | no | `info` | `debug` \| `info` \| `warn` \| `error` |
+
+### Env-var form (macOS/Linux shells, scripts, systemd unit files)
+
+```bash
+export FOUNDEROS_RUNNER_URL=https://founderos.fly.dev
+export FOUNDEROS_RUNNER_TOKEN=fos_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+founderos-runner start
+```
+
+Output:
+
+```
+[info ] founderos-runner v0.1.0 starting {"serverUrl":"https://founderos.fly.dev","claudeBin":"claude"}
+[info ] got job {"jobId":"...","agent":"Sarah"}
+[info ] job completed {"jobId":"...","status":"completed","exitCode":0}
+```
+
+The process loops until you `^C` it; SIGINT/SIGTERM finishes the current job before exiting.
+
+## Run as a service (macOS)
+
+```bash
+# ~/Library/LaunchAgents/dev.founderos.runner.plist
+cat > ~/Library/LaunchAgents/dev.founderos.runner.plist <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>dev.founderos.runner</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/bin/founderos-runner</string>
+    <string>start</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>FOUNDEROS_RUNNER_URL</key><string>https://founderos.fly.dev</string>
+    <key>FOUNDEROS_RUNNER_TOKEN</key><string>fos_...</string>
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+</dict>
+</plist>
+EOF
+launchctl load ~/Library/LaunchAgents/dev.founderos.runner.plist
+```
+
+## Run as a service (Windows, NSSM)
+
+Windows ships no equivalent to launchd / systemd, but [NSSM](https://nssm.cc) wraps any executable as a service:
+
+```powershell
+# After `npm install -g @founderos/runner`
+nssm install FounderOSRunner "C:\Program Files\nodejs\founderos-runner.cmd"
+nssm set FounderOSRunner AppParameters "start --token=fos_xxx --server-url=https://founderos.fly.dev"
+nssm set FounderOSRunner Start SERVICE_AUTO_START
+nssm start FounderOSRunner
+```
+
+## Run as a service (Linux, systemd)
+
+```ini
+# /etc/systemd/system/founderos-runner.service
+[Unit]
+Description=FounderOS local runner
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=/usr/local/bin/founderos-runner start
+Restart=always
+Environment="FOUNDEROS_RUNNER_URL=https://founderos.fly.dev"
+Environment="FOUNDEROS_RUNNER_TOKEN=fos_..."
+User=YOUR_USER
+
+[Install]
+WantedBy=default.target
+```
+
+## What does the runner do, exactly?
+
+1. **Long-poll** `GET /api/runner/jobs/next` (≤ 30 s) for queued work.
+2. **Atomic claim** `POST /api/runner/jobs/:id/claim` — the cloud transitions the job from `queued` → `claimed` in a single SQL `UPDATE…WHERE status='queued'`. Multiple runners polling the same token race; the lowest-latency one wins.
+3. **Spawn** `claude --print --output-format stream-json --verbose` with the prompt on stdin. If the cloud passed `--resume sessionId`, it threads through.
+4. **Stream events** — every line of stream-json (assistant messages, tool uses, tool results, the final result) is parsed and POSTed in 50 ms / 32-event batches to `POST /api/runner/jobs/:id/events`.
+5. **Complete** — when claude exits, post the exit code, total cost (parsed from the `result` event), `sessionId` (for `--resume` next time), and CLI version to `POST /api/runner/jobs/:id/complete`.
+
+## Security
+
+- Token is hashed at rest server-side (sha256). Constant-time compare on every request.
+- Tokens scope to a single company. A token issued for company A cannot read jobs for company B.
+- Plaintext tokens are never logged. Audit-log entries store an 8-char preview only.
+- Revoke from the dashboard whenever a machine is decommissioned; revoked tokens get a 401 on the next request.
+
+See the [runner threat model](https://github.com/founderos-ai/founderos/blob/main/docs/security/runner-threat-model.md).
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `npm error code ENOENT` ... `@founderos\package.json` | Trailing slash typo (`npm install -g @founderos/`) | Use `npx @founderos/runner start --token=...` |
+| `config error: FOUNDEROS_RUNNER_TOKEN is required` | No token passed | Add `--token=fos_...` or set `FOUNDEROS_RUNNER_TOKEN` |
+| `config error: ... must match fos_<32 alphanumeric>` | Token format wrong | Re-issue a fresh token from the dashboard |
+| `unknown or malformed flag(s): --token` | Flag without value (`--token` not `--token=fos_...`) | Use `--token=fos_xxx` form |
+| `claude: command not found` (during a job) | `claude` CLI not on `PATH` | Install Claude Code, or pass `--claude-bin=/full/path/to/claude` |
+| 401 Unauthorized on every request | Token revoked or expired | Re-issue from dashboard → Settings → Runner Tokens |
+
+For anything else, the runner emits structured `[debug]` logs when `--log-level=debug` is set — open an issue with the relevant log lines.
+
+## Local development
+
+```bash
+pnpm install
+pnpm --filter @founderos/runner test     # unit tests, no live spawn
+pnpm --filter @founderos/runner build    # tsc → dist/
+```
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Typed HTTP client for the four runner-side endpoints in
+ * docs/api/runner-openapi.yaml. Uses Node's built-in fetch (Node 20+).
+ *
+ * Idempotency:
+ *   - /events POST is server-side append-only; the runner is responsible for
+ *     not re-sending the same eventId on retry. We track sent eventIds per
+ *     job in memory; only retry on 5xx (network errors).
+ *   - /complete is server-rejected on double-submit (409). We swallow the 409
+ *     gracefully so a crashed-and-restarted runner that already completed a
+ *     job before crashing doesn't loop on it.
+ */
+import type { RunnerConfig } from "./config.js";
+export interface JobDescriptor {
+    jobId: string;
+    agentId: string;
+    agentName: string;
+    createdAt: string;
+}
+/**
+ * Adapter type carried from the cloud through to the runner.
+ *
+ * S7.0.1 — kept as a plain string union here (NOT `AgentAdapterType` from
+ * `@founderos/shared`) so the runner package can stay free of the shared
+ * deep dep. The DB CHECK constraint at migration 0105 + the cloud-side
+ * Zod schema enforce validity before this field reaches the runner.
+ *
+ * Default fallback: "claude_local". Pre-S7 rows that wrote "byo_runner"
+ * still map to claude via the dispatcher's legacy-fallback path.
+ */
+export type RunnerAdapterType = "claude_local" | "codex_local" | "gemini_local" | "opencode_local" | "pi_local" | "cursor_local" | "openclaw_gateway" | "hermes_local" | "byo_runner" | "process" | "http" | (string & {});
+export interface JobPayload {
+    jobId: string;
+    agentId: string;
+    agentName?: string;
+    prompt: string;
+    sessionId: string | null;
+    runtimeConfig: {
+        model?: string | null;
+        maxTurns?: number | null;
+        timeoutSec?: number;
+        instructionsFileContent?: string | null;
+        [k: string]: unknown;
+    };
+    promptHash: string;
+    /**
+     * S7.0.1 — adapter type the runner should dispatch on. Server returns
+     * this from the claim API (`server/src/routes/runner.ts:303`). May be
+     * absent on responses from a pre-S7.0.1 server build — defaults to
+     * "claude_local" at the consumer.
+     */
+    adapterType?: RunnerAdapterType;
+    addDirs?: string[];
+}
+export type RunnerEventKind = "stdout_line" | "stderr_line" | "claude_message" | "claude_tool_use" | "claude_tool_result" | "claude_result";
+export interface RunnerEvent {
+    eventId: string;
+    kind: RunnerEventKind;
+    ts: string;
+    payload?: Record<string, unknown> | string;
+}
+export interface CompletionBody {
+    status: "completed" | "failed" | "cancelled";
+    exitCode: number;
+    signal?: string | null;
+    elapsedSec?: number;
+    costMicros?: number;
+    sessionId?: string | null;
+    cliVersion?: string;
+    errorMessage?: string | null;
+}
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string, message?: string);
+}
+/** Generate a runner-side event id. Exposed so the spawner can stamp events
+ *  before they reach the API client. */
+export declare function makeEventId(): string;
+export declare class RunnerApiClient {
+    private readonly config;
+    private readonly fetchImpl;
+    constructor(config: RunnerConfig, fetchImpl?: typeof fetch);
+    private url;
+    private headers;
+    /**
+     * Long-poll for the next claimable job. Server holds the connection up to
+     * 30s. Returns:
+     *   - { kind: "job", job } on a hit
+     *   - { kind: "empty" } on 204 timeout (caller re-polls)
+     *   - throws ApiError on non-2xx
+     */
+    getNext(signal?: AbortSignal): Promise<{
+        kind: "job";
+        job: JobDescriptor;
+    } | {
+        kind: "empty";
+    }>;
+    /**
+     * Atomic claim. Returns:
+     *   - { kind: "claimed", payload } on success
+     *   - { kind: "lost" } on 409 (race lost)
+     *   - { kind: "gone" } on 404 (cancelled / unknown)
+     *   - throws ApiError on other non-2xx
+     */
+    claim(jobId: string): Promise<{
+        kind: "claimed";
+        payload: JobPayload;
+    } | {
+        kind: "lost";
+    } | {
+        kind: "gone";
+    }>;
+    /**
+     * Append a batch of events. Caller batches with a 50ms / 32-event window.
+     * Idempotent on eventId; the server doesn't dedup but does reject when the
+     * job is in a terminal state (409). We retry on 5xx + network errors with
+     * a small backoff; on 409 we surface the terminal state to the caller so
+     * it can stop spawning.
+     */
+    appendEvents(jobId: string, events: RunnerEvent[]): Promise<{
+        kind: "ok";
+    } | {
+        kind: "terminal";
+    }>;
+    /**
+     * Mark the job terminal. 409 (already terminal) is swallowed — the runner
+     * may have crashed mid-complete and the cloud already accepted the prior
+     * call. We log + move on rather than spinning forever.
+     */
+    complete(jobId: string, body: CompletionBody): Promise<{
+        kind: "ok";
+    } | {
+        kind: "already_terminal";
+    }>;
+}
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/api.js

@@ -0,0 +1,148 @@
+/**
+ * Typed HTTP client for the four runner-side endpoints in
+ * docs/api/runner-openapi.yaml. Uses Node's built-in fetch (Node 20+).
+ *
+ * Idempotency:
+ *   - /events POST is server-side append-only; the runner is responsible for
+ *     not re-sending the same eventId on retry. We track sent eventIds per
+ *     job in memory; only retry on 5xx (network errors).
+ *   - /complete is server-rejected on double-submit (409). We swallow the 409
+ *     gracefully so a crashed-and-restarted runner that already completed a
+ *     job before crashing doesn't loop on it.
+ */
+import { randomUUID } from "node:crypto";
+import { setTimeout as sleep } from "node:timers/promises";
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(status, body, message) {
+        super(message ?? `API ${status}: ${body.slice(0, 200)}`);
+        this.status = status;
+        this.body = body;
+        this.name = "ApiError";
+    }
+}
+/** Generate a runner-side event id. Exposed so the spawner can stamp events
+ *  before they reach the API client. */
+export function makeEventId() {
+    return randomUUID();
+}
+export class RunnerApiClient {
+    config;
+    fetchImpl;
+    constructor(config, fetchImpl = fetch) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+    }
+    url(path) {
+        return `${this.config.serverUrl}${path}`;
+    }
+    headers(extra) {
+        return {
+            authorization: `Bearer ${this.config.token}`,
+            "user-agent": "founderos-runner",
+            ...(extra ?? {}),
+        };
+    }
+    /**
+     * Long-poll for the next claimable job. Server holds the connection up to
+     * 30s. Returns:
+     *   - { kind: "job", job } on a hit
+     *   - { kind: "empty" } on 204 timeout (caller re-polls)
+     *   - throws ApiError on non-2xx
+     */
+    async getNext(signal) {
+        const res = await this.fetchImpl(this.url("/api/runner/jobs/next"), {
+            method: "GET",
+            headers: this.headers(),
+            signal,
+        });
+        if (res.status === 204)
+            return { kind: "empty" };
+        if (!res.ok) {
+            throw new ApiError(res.status, await res.text().catch(() => ""));
+        }
+        const job = (await res.json());
+        return { kind: "job", job };
+    }
+    /**
+     * Atomic claim. Returns:
+     *   - { kind: "claimed", payload } on success
+     *   - { kind: "lost" } on 409 (race lost)
+     *   - { kind: "gone" } on 404 (cancelled / unknown)
+     *   - throws ApiError on other non-2xx
+     */
+    async claim(jobId) {
+        const res = await this.fetchImpl(this.url(`/api/runner/jobs/${jobId}/claim`), {
+            method: "POST",
+            headers: this.headers({ "content-type": "application/json" }),
+        });
+        if (res.status === 409)
+            return { kind: "lost" };
+        if (res.status === 404)
+            return { kind: "gone" };
+        if (!res.ok) {
+            throw new ApiError(res.status, await res.text().catch(() => ""));
+        }
+        const payload = (await res.json());
+        return { kind: "claimed", payload };
+    }
+    /**
+     * Append a batch of events. Caller batches with a 50ms / 32-event window.
+     * Idempotent on eventId; the server doesn't dedup but does reject when the
+     * job is in a terminal state (409). We retry on 5xx + network errors with
+     * a small backoff; on 409 we surface the terminal state to the caller so
+     * it can stop spawning.
+     */
+    async appendEvents(jobId, events) {
+        if (events.length === 0)
+            return { kind: "ok" };
+        const body = JSON.stringify({ events });
+        const headers = this.headers({ "content-type": "application/json" });
+        const maxAttempts = 4;
+        let lastErr;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                const res = await this.fetchImpl(this.url(`/api/runner/jobs/${jobId}/events`), {
+                    method: "POST",
+                    headers,
+                    body,
+                });
+                if (res.status === 204)
+                    return { kind: "ok" };
+                if (res.status === 409)
+                    return { kind: "terminal" };
+                if (res.status >= 500) {
+                    lastErr = new ApiError(res.status, await res.text().catch(() => ""));
+                }
+                else {
+                    throw new ApiError(res.status, await res.text().catch(() => ""));
+                }
+            }
+            catch (err) {
+                lastErr = err;
+            }
+            // 100ms, 300ms, 700ms backoff between retries.
+            await sleep(100 * (attempt * attempt));
+        }
+        throw lastErr instanceof Error ? lastErr : new Error("appendEvents: unreachable");
+    }
+    /**
+     * Mark the job terminal. 409 (already terminal) is swallowed — the runner
+     * may have crashed mid-complete and the cloud already accepted the prior
+     * call. We log + move on rather than spinning forever.
+     */
+    async complete(jobId, body) {
+        const res = await this.fetchImpl(this.url(`/api/runner/jobs/${jobId}/complete`), {
+            method: "POST",
+            headers: this.headers({ "content-type": "application/json" }),
+            body: JSON.stringify(body),
+        });
+        if (res.status === 204)
+            return { kind: "ok" };
+        if (res.status === 409)
+            return { kind: "already_terminal" };
+        throw new ApiError(res.status, await res.text().catch(() => ""));
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * `founderos-runner` CLI entry. Supports a single command:
+ *
+ *   founderos-runner start [--token=...] [--server-url=...] [--claude-bin=...]
+ *                          [--timeout-sec=N] [--log-level=info]
+ *   founderos-runner --version
+ *   founderos-runner --help
+ *
+ * Flags override the matching FOUNDEROS_* environment variables. Both
+ * forms are supported because Windows PowerShell users find env-var
+ * setup awkward (`$env:FOUNDEROS_RUNNER_TOKEN="..."` vs `--token=...`),
+ * and macOS/Linux users in shell scripts often prefer env vars.
+ */
+import { type RunnerConfigOverrides } from "./config.js";
+/**
+ * Parse `--key=value` and `--key value` flag forms. Returns parsed
+ * overrides + any unknown args (which we treat as errors today).
+ *
+ * Argv shape: caller has already stripped node + script + the "start"
+ * subcommand. Only flag tokens remain.
+ */
+export declare function parseFlags(argv: string[]): {
+    overrides: RunnerConfigOverrides;
+    unknown: string[];
+};
+export declare function main(argv?: string[]): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAiC,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAwCxF;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAC1C,SAAS,EAAE,qBAAqB,CAAC;IACjC,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAuDA;AAED,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAqClF"}