@frankleeeee/flowy-runner 1.0.0

package/README.md

@@ -0,0 +1,130 @@
+# Flowy Runner
+
+`@frankleeeee/flowy-runner` connects a machine to Flowy and executes assigned tasks with supported local AI CLIs.
+
+## Requirements
+
+- Node.js 23+
+- one or more supported CLIs installed:
+  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) via `claude`
+  - [Codex](https://github.com/openai/codex) via `codex`
+
+## Install
+
+### From this repository
+
+```bash
+npm install
+npm run build --workspace=runner
+```
+
+### As the published npm package
+
+```bash
+npm install -g @frankleeeee/flowy-runner
+```
+
+## Usage
+
+Run the runner with:
+
+```bash
+flowy-runner --name <name> --url <hub-url> [options]
+```
+
+Example:
+
+```bash
+flowy-runner --name office-mac --url http://localhost:3001 --secret YOUR_SECRET
+```
+
+## Flags
+
+### Required
+
+| Flag | Description |
+|------|-------------|
+| `--name <name>` | Unique runner name |
+| `--url <url>` | Flowy backend URL |
+
+### Optional
+
+| Flag | Description |
+|------|-------------|
+| `--poll-interval <seconds>` | Poll interval in seconds. Default: `5` |
+| `--token <token>` | Reuse an existing runner token |
+| `--secret <secret>` | Registration secret if the server requires one |
+| `--device <info>` | Device info string. Default: hostname |
+
+## Behavior
+
+When the runner starts it will:
+
+1. detect available CLIs on the machine
+2. register with Flowy if it does not already have a saved token
+3. send heartbeats so it appears online
+4. poll for assigned tasks
+5. execute tasks using the selected provider
+6. stream the full CLI output back to Flowy
+
+Supported provider detection:
+
+- `claude` -> `claude-code`
+- `codex` -> `codex`
+
+## Execution
+
+Current task execution commands:
+
+| Provider | Command shape |
+|----------|---------------|
+| `claude-code` | `claude -p "<task prompt>" --tools all` |
+| `codex` | `codex exec "<task prompt>" --sandbox workspace-write --color never` |
+
+## Token persistence
+
+Runner tokens are stored at:
+
+```text
+~/.config/flowy/runner-<name>.json
+```
+
+If a runner token is rejected with `401`, the runner deletes the local token file so the next launch can register cleanly again.
+
+## Development
+
+From the `runner/` directory:
+
+```bash
+npm install
+npm run dev -- --name my-runner --url http://localhost:3001
+```
+
+Or from the repository root:
+
+```bash
+npm run dev --workspace=runner -- --name my-runner --url http://localhost:3001
+```
+
+## Build
+
+From the `runner/` directory:
+
+```bash
+npm run build
+```
+
+Or from the repository root:
+
+```bash
+npm run build --workspace=runner
+```
+
+## Publish
+
+This repo includes a GitHub Actions workflow for publishing `@frankleeeee/flowy-runner`.
+
+Trigger either of these:
+
+- push a tag like `flowy-runner-v1.2.3`
+- run the `Publish Flowy Runner` workflow manually with a version

package/dist/api.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RunnerApi = void 0;
+const axios_1 = __importDefault(require("axios"));
+class RunnerApi {
+    client;
+    token = '';
+    constructor(baseUrl) {
+        this.client = axios_1.default.create({ baseURL: baseUrl + '/api' });
+    }
+    setToken(token) {
+        this.token = token;
+        this.client.defaults.headers.common['Authorization'] = `Bearer ${token}`;
+    }
+    async register(name, aiProviders, deviceInfo, secret) {
+        const { data } = await this.client.post('/runners/register', {
+            name, aiProviders, deviceInfo, secret,
+        });
+        return data;
+    }
+    async heartbeat(aiProviders, lastCliScanAt) {
+        const { data } = await this.client.post('/runners/heartbeat', { aiProviders, lastCliScanAt });
+        return data;
+    }
+    async poll() {
+        const resp = await this.client.get('/runners/poll');
+        if (resp.status === 204)
+            return null;
+        return resp.data;
+    }
+    async pickTask(taskId) {
+        await this.client.post(`/runners/tasks/${taskId}/pick`);
+    }
+    async sendOutput(taskId, data) {
+        await this.client.post(`/runners/tasks/${taskId}/output`, { data });
+    }
+    async completeTask(taskId, success, data) {
+        await this.client.post(`/runners/tasks/${taskId}/complete`, { success, data });
+    }
+}
+exports.RunnerApi = RunnerApi;

package/dist/cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_1 = require("./config");
+const daemon_1 = require("./daemon");
+const config = (0, config_1.parseArgs)(process.argv);
+(0, daemon_1.startDaemon)(config).catch((err) => {
+    console.error('Fatal error:', err.message ?? err);
+    process.exit(1);
+});

package/dist/config.js

@@ -0,0 +1,117 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+exports.detectAvailableProviders = detectAvailableProviders;
+exports.saveToken = saveToken;
+exports.deleteToken = deleteToken;
+const os_1 = __importDefault(require("os"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const CONFIG_DIR = path_1.default.join(os_1.default.homedir(), '.config', 'flowy');
+const SUPPORTED_PROVIDERS = [
+    { id: 'claude-code', command: 'claude' },
+    { id: 'codex', command: 'codex' },
+];
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    let name = '';
+    let url = '';
+    let pollInterval = 5;
+    let token;
+    let secret;
+    let device = os_1.default.hostname();
+    for (let i = 0; i < args.length; i++) {
+        switch (args[i]) {
+            case '--name':
+                name = args[++i] ?? '';
+                break;
+            case '--url':
+                url = args[++i] ?? '';
+                break;
+            case '--poll-interval':
+                pollInterval = parseInt(args[++i] ?? '5', 10);
+                break;
+            case '--token':
+                token = args[++i];
+                break;
+            case '--secret':
+                secret = args[++i];
+                break;
+            case '--device':
+                device = args[++i] ?? os_1.default.hostname();
+                break;
+        }
+    }
+    if (!name || !url) {
+        console.error('Usage: flowy-runner --name <name> --url <backend-url> [options]');
+        console.error('');
+        console.error('Required:');
+        console.error('  --name          Runner name');
+        console.error('  --url           Backend URL (e.g. http://localhost:3001)');
+        console.error('');
+        console.error('Options:');
+        console.error('  --poll-interval Poll interval in seconds (default: 5)');
+        console.error('  --token         Existing runner token (skip registration)');
+        console.error('  --secret        Registration secret (required if server has one configured)');
+        console.error('  --device        Device info (default: hostname)');
+        process.exit(1);
+    }
+    // If no token provided, try to load from saved config
+    if (!token) {
+        token = loadToken(name);
+    }
+    const providers = detectAvailableProviders();
+    if (providers.length === 0) {
+        console.error('No supported AI CLIs were detected on this machine.');
+        console.error('Install one of: claude, codex');
+        process.exit(1);
+    }
+    return {
+        name,
+        url: url.replace(/\/$/, ''),
+        providers,
+        lastCliScanAt: new Date().toISOString(),
+        pollInterval,
+        token,
+        secret,
+        device,
+    };
+}
+function detectAvailableProviders() {
+    return SUPPORTED_PROVIDERS
+        .filter((provider) => isCommandAvailable(provider.command))
+        .map((provider) => provider.id);
+}
+function isCommandAvailable(command) {
+    const checker = process.platform === 'win32' ? 'where' : 'which';
+    const result = (0, child_process_1.spawnSync)(checker, [command], { stdio: 'ignore' });
+    return result.status === 0;
+}
+function loadToken(name) {
+    const file = path_1.default.join(CONFIG_DIR, `runner-${name}.json`);
+    try {
+        const data = JSON.parse(fs_1.default.readFileSync(file, 'utf-8'));
+        return data.token;
+    }
+    catch {
+        return undefined;
+    }
+}
+function saveToken(name, id, token) {
+    fs_1.default.mkdirSync(CONFIG_DIR, { recursive: true });
+    const file = path_1.default.join(CONFIG_DIR, `runner-${name}.json`);
+    fs_1.default.writeFileSync(file, JSON.stringify({ id, token }, null, 2));
+}
+function deleteToken(name) {
+    const file = path_1.default.join(CONFIG_DIR, `runner-${name}.json`);
+    try {
+        fs_1.default.unlinkSync(file);
+    }
+    catch {
+        // Ignore missing/unreadable token files.
+    }
+}

package/dist/daemon.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startDaemon = startDaemon;
+const api_1 = require("./api");
+const config_1 = require("./config");
+const executor_1 = require("./executor");
+async function startDaemon(config) {
+    const api = new api_1.RunnerApi(config.url);
+    let availableProviders = [...config.providers];
+    let lastCliScanAt = config.lastCliScanAt;
+    // ── Registration ────────────────────────────────────────────────────────
+    if (config.token) {
+        console.log(`Using existing token for runner "${config.name}"`);
+        api.setToken(config.token);
+    }
+    else {
+        console.log(`Registering runner "${config.name}" at ${config.url}...`);
+        const { id, token } = await api.register(config.name, availableProviders, config.device, config.secret);
+        api.setToken(token);
+        (0, config_1.saveToken)(config.name, id, token);
+        console.log(`Registered! Runner ID: ${id}`);
+        console.log(`Token saved to ~/.config/flowy/runner-${config.name}.json`);
+    }
+    let executing = false;
+    let killCurrent = null;
+    const handleInvalidToken = () => {
+        (0, config_1.deleteToken)(config.name);
+        console.error('Runner token rejected (401). Deleted local runner token; restart to register again.');
+        process.exit(1);
+    };
+    // ── Heartbeat ───────────────────────────────────────────────────────────
+    const heartbeat = async () => {
+        try {
+            const response = await api.heartbeat(availableProviders, lastCliScanAt);
+            if (response.refreshCli) {
+                availableProviders = (0, config_1.detectAvailableProviders)();
+                lastCliScanAt = new Date().toISOString();
+                console.log(`Refreshing available CLIs: ${availableProviders.join(', ') || '(none)'}`);
+                await api.heartbeat(availableProviders, lastCliScanAt);
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes('401')) {
+                handleInvalidToken();
+            }
+            console.warn('Heartbeat failed:', msg);
+        }
+    };
+    // Send initial heartbeat, then every 30 seconds
+    await heartbeat();
+    const heartbeatInterval = setInterval(heartbeat, 30_000);
+    // ── Polling ─────────────────────────────────────────────────────────────
+    const poll = async () => {
+        if (executing)
+            return;
+        try {
+            const task = await api.poll();
+            if (!task)
+                return;
+            console.log(`\nPicked up task: ${task.task_key} - ${task.title}`);
+            console.log(`  AI Provider: ${task.ai_provider}`);
+            console.log(`  Description: ${(task.description || task.title).slice(0, 100)}...`);
+            await api.pickTask(task.id);
+            executing = true;
+            const { promise, kill } = (0, executor_1.executeTask)(task, async (chunk) => {
+                try {
+                    await api.sendOutput(task.id, chunk);
+                }
+                catch (err) {
+                    console.warn('Failed to send output chunk:', err instanceof Error ? err.message : err);
+                }
+            });
+            killCurrent = kill;
+            const result = await promise;
+            killCurrent = null;
+            executing = false;
+            console.log(`\nTask ${task.task_key} ${result.success ? 'completed' : 'failed'}`);
+            await api.completeTask(task.id, result.success, result.sendOnComplete ? result.output : '');
+        }
+        catch (err) {
+            executing = false;
+            killCurrent = null;
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes('401')) {
+                handleInvalidToken();
+            }
+            console.error('Poll/execute error:', err instanceof Error ? err.message : err);
+        }
+    };
+    const pollInterval = setInterval(poll, config.pollInterval * 1000);
+    console.log(`\nRunner "${config.name}" is online and polling every ${config.pollInterval}s`);
+    console.log(`Providers: ${availableProviders.join(', ') || '(none)'}`);
+    console.log('Press Ctrl+C to stop.\n');
+    // ── Graceful Shutdown ───────────────────────────────────────────────────
+    const shutdown = async (signal) => {
+        console.log(`\nReceived ${signal}, shutting down...`);
+        clearInterval(heartbeatInterval);
+        clearInterval(pollInterval);
+        if (killCurrent) {
+            console.log('Killing running task...');
+            killCurrent();
+        }
+        // Give a moment for cleanup
+        setTimeout(() => process.exit(0), 500);
+    };
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+}

package/dist/executor.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeTask = executeTask;
+const child_process_1 = require("child_process");
+/** Build the CLI command + args for a given AI provider. */
+function buildCommand(aiProvider, prompt) {
+    switch (aiProvider) {
+        case 'claude-code':
+            return { cmd: 'claude', args: ['-p', prompt, "--tools", "all"], streamOutput: true };
+        case 'codex':
+            return {
+                cmd: 'codex',
+                args: ['exec', prompt, '--sandbox', 'workspace-write', '--color', 'never'],
+                streamOutput: true,
+            };
+        default:
+            throw new Error(`Unknown AI provider: ${aiProvider}`);
+    }
+}
+/**
+ * Execute a task using the specified AI CLI tool.
+ * Calls `onOutput` with buffered chunks every ~2 seconds.
+ * Returns when the process exits.
+ */
+function executeTask(task, onOutput) {
+    const { cmd, args, streamOutput } = buildCommand(task.ai_provider, task.description || task.title);
+    let child;
+    let fullOutput = '';
+    let buffer = '';
+    let flushTimer;
+    const promise = new Promise((resolve) => {
+        console.log(`  Spawning: ${cmd} ${args.join(' ')}`);
+        child = (0, child_process_1.spawn)(cmd, args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env },
+        });
+        const flush = () => {
+            if (streamOutput && buffer.length > 0) {
+                onOutput(buffer);
+                buffer = '';
+            }
+        };
+        flushTimer = setInterval(flush, 2000);
+        child.stdout?.on('data', (data) => {
+            const text = data.toString();
+            fullOutput += text;
+            buffer += text;
+        });
+        child.stderr?.on('data', (data) => {
+            const text = data.toString();
+            fullOutput += text;
+            buffer += text;
+        });
+        child.on('error', (err) => {
+            clearInterval(flushTimer);
+            flush();
+            fullOutput += `\n[Error: ${err.message}]`;
+            resolve({ success: false, output: fullOutput, sendOnComplete: true });
+        });
+        child.on('close', (code) => {
+            clearInterval(flushTimer);
+            flush();
+            const success = code === 0;
+            resolve({ success, output: fullOutput, sendOnComplete: !streamOutput || !success });
+        });
+    });
+    const kill = () => {
+        clearInterval(flushTimer);
+        child?.kill('SIGTERM');
+    };
+    return { promise, kill };
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@frankleeeee/flowy-runner",
+  "version": "1.0.0",
+  "private": false,
+  "bin": {
+    "flowy-runner": "./dist/cli.js"
+  },
+  "scripts": {
+    "dev": "ts-node-dev --respawn --transpile-only src/cli.ts --",
+    "build": "tsc",
+    "start": "node dist/cli.js"
+  },
+  "dependencies": {
+    "axios": "^1.6.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=23"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.4.3"
+  }
+}

package/src/api.ts

@@ -0,0 +1,46 @@
+import axios, { AxiosInstance } from 'axios';
+import { Task, RegisterResponse, HeartbeatResponse } from './types';
+
+export class RunnerApi {
+  private client: AxiosInstance;
+  private token: string = '';
+
+  constructor(baseUrl: string) {
+    this.client = axios.create({ baseURL: baseUrl + '/api' });
+  }
+
+  setToken(token: string): void {
+    this.token = token;
+    this.client.defaults.headers.common['Authorization'] = `Bearer ${token}`;
+  }
+
+  async register(name: string, aiProviders: string[], deviceInfo: string, secret?: string): Promise<RegisterResponse> {
+    const { data } = await this.client.post<RegisterResponse>('/runners/register', {
+      name, aiProviders, deviceInfo, secret,
+    });
+    return data;
+  }
+
+  async heartbeat(aiProviders: string[], lastCliScanAt?: string): Promise<HeartbeatResponse> {
+    const { data } = await this.client.post<HeartbeatResponse>('/runners/heartbeat', { aiProviders, lastCliScanAt });
+    return data;
+  }
+
+  async poll(): Promise<Task | null> {
+    const resp = await this.client.get('/runners/poll');
+    if (resp.status === 204) return null;
+    return resp.data;
+  }
+
+  async pickTask(taskId: string): Promise<void> {
+    await this.client.post(`/runners/tasks/${taskId}/pick`);
+  }
+
+  async sendOutput(taskId: string, data: string): Promise<void> {
+    await this.client.post(`/runners/tasks/${taskId}/output`, { data });
+  }
+
+  async completeTask(taskId: string, success: boolean, data?: string): Promise<void> {
+    await this.client.post(`/runners/tasks/${taskId}/complete`, { success, data });
+  }
+}

package/src/cli.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { parseArgs } from './config';
+import { startDaemon } from './daemon';
+
+const config = parseArgs(process.argv);
+
+startDaemon(config).catch((err) => {
+  console.error('Fatal error:', err.message ?? err);
+  process.exit(1);
+});

package/src/config.ts

@@ -0,0 +1,107 @@
+import os from 'os';
+import fs from 'fs';
+import path from 'path';
+import { spawnSync } from 'child_process';
+import { RunnerConfig } from './types';
+
+const CONFIG_DIR = path.join(os.homedir(), '.config', 'flowy');
+const SUPPORTED_PROVIDERS = [
+  { id: 'claude-code', command: 'claude' },
+  { id: 'codex', command: 'codex' },
+] as const;
+
+export function parseArgs(argv: string[]): RunnerConfig {
+  const args = argv.slice(2);
+  let name = '';
+  let url = '';
+  let pollInterval = 5;
+  let token: string | undefined;
+  let secret: string | undefined;
+  let device = os.hostname();
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '--name':    name = args[++i] ?? ''; break;
+      case '--url':     url = args[++i] ?? ''; break;
+      case '--poll-interval': pollInterval = parseInt(args[++i] ?? '5', 10); break;
+      case '--token':   token = args[++i]; break;
+      case '--secret':  secret = args[++i]; break;
+      case '--device':  device = args[++i] ?? os.hostname(); break;
+    }
+  }
+
+  if (!name || !url) {
+    console.error('Usage: flowy-runner --name <name> --url <backend-url> [options]');
+    console.error('');
+    console.error('Required:');
+    console.error('  --name          Runner name');
+    console.error('  --url           Backend URL (e.g. http://localhost:3001)');
+    console.error('');
+    console.error('Options:');
+    console.error('  --poll-interval Poll interval in seconds (default: 5)');
+    console.error('  --token         Existing runner token (skip registration)');
+    console.error('  --secret        Registration secret (required if server has one configured)');
+    console.error('  --device        Device info (default: hostname)');
+    process.exit(1);
+  }
+
+  // If no token provided, try to load from saved config
+  if (!token) {
+    token = loadToken(name);
+  }
+
+  const providers = detectAvailableProviders();
+  if (providers.length === 0) {
+    console.error('No supported AI CLIs were detected on this machine.');
+    console.error('Install one of: claude, codex');
+    process.exit(1);
+  }
+
+  return {
+    name,
+    url: url.replace(/\/$/, ''),
+    providers,
+    lastCliScanAt: new Date().toISOString(),
+    pollInterval,
+    token,
+    secret,
+    device,
+  };
+}
+
+export function detectAvailableProviders(): string[] {
+  return SUPPORTED_PROVIDERS
+    .filter((provider) => isCommandAvailable(provider.command))
+    .map((provider) => provider.id);
+}
+
+function isCommandAvailable(command: string): boolean {
+  const checker = process.platform === 'win32' ? 'where' : 'which';
+  const result = spawnSync(checker, [command], { stdio: 'ignore' });
+  return result.status === 0;
+}
+
+function loadToken(name: string): string | undefined {
+  const file = path.join(CONFIG_DIR, `runner-${name}.json`);
+  try {
+    const data = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    return data.token;
+  } catch {
+    return undefined;
+  }
+}
+
+export function saveToken(name: string, id: string, token: string): void {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  const file = path.join(CONFIG_DIR, `runner-${name}.json`);
+  fs.writeFileSync(file, JSON.stringify({ id, token }, null, 2));
+}
+
+export function deleteToken(name: string): void {
+  const file = path.join(CONFIG_DIR, `runner-${name}.json`);
+  try {
+    fs.unlinkSync(file);
+  } catch {
+    // Ignore missing/unreadable token files.
+  }
+}

package/src/daemon.ts

@@ -0,0 +1,122 @@
+import { RunnerConfig } from './types';
+import { RunnerApi } from './api';
+import { deleteToken, detectAvailableProviders, saveToken } from './config';
+import { executeTask } from './executor';
+
+export async function startDaemon(config: RunnerConfig): Promise<void> {
+  const api = new RunnerApi(config.url);
+  let availableProviders = [...config.providers];
+  let lastCliScanAt = config.lastCliScanAt;
+
+  // ── Registration ────────────────────────────────────────────────────────
+  if (config.token) {
+    console.log(`Using existing token for runner "${config.name}"`);
+    api.setToken(config.token);
+  } else {
+    console.log(`Registering runner "${config.name}" at ${config.url}...`);
+    const { id, token } = await api.register(config.name, availableProviders, config.device, config.secret);
+    api.setToken(token);
+    saveToken(config.name, id, token);
+    console.log(`Registered! Runner ID: ${id}`);
+    console.log(`Token saved to ~/.config/flowy/runner-${config.name}.json`);
+  }
+
+  let executing = false;
+  let killCurrent: (() => void) | null = null;
+
+  const handleInvalidToken = () => {
+    deleteToken(config.name);
+    console.error('Runner token rejected (401). Deleted local runner token; restart to register again.');
+    process.exit(1);
+  };
+
+  // ── Heartbeat ───────────────────────────────────────────────────────────
+  const heartbeat = async () => {
+    try {
+      const response = await api.heartbeat(availableProviders, lastCliScanAt);
+      if (response.refreshCli) {
+        availableProviders = detectAvailableProviders();
+        lastCliScanAt = new Date().toISOString();
+        console.log(`Refreshing available CLIs: ${availableProviders.join(', ') || '(none)'}`);
+        await api.heartbeat(availableProviders, lastCliScanAt);
+      }
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes('401')) {
+        handleInvalidToken();
+      }
+      console.warn('Heartbeat failed:', msg);
+    }
+  };
+
+  // Send initial heartbeat, then every 30 seconds
+  await heartbeat();
+  const heartbeatInterval = setInterval(heartbeat, 30_000);
+
+  // ── Polling ─────────────────────────────────────────────────────────────
+  const poll = async () => {
+    if (executing) return;
+
+    try {
+      const task = await api.poll();
+      if (!task) return;
+
+      console.log(`\nPicked up task: ${task.task_key} - ${task.title}`);
+      console.log(`  AI Provider: ${task.ai_provider}`);
+      console.log(`  Description: ${(task.description || task.title).slice(0, 100)}...`);
+
+      await api.pickTask(task.id);
+      executing = true;
+
+      const { promise, kill } = executeTask(task, async (chunk) => {
+        try {
+          await api.sendOutput(task.id, chunk);
+        } catch (err) {
+          console.warn('Failed to send output chunk:', err instanceof Error ? err.message : err);
+        }
+      });
+
+      killCurrent = kill;
+
+      const result = await promise;
+      killCurrent = null;
+      executing = false;
+
+      console.log(`\nTask ${task.task_key} ${result.success ? 'completed' : 'failed'}`);
+      await api.completeTask(task.id, result.success, result.sendOnComplete ? result.output : '');
+
+    } catch (err) {
+      executing = false;
+      killCurrent = null;
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes('401')) {
+        handleInvalidToken();
+      }
+      console.error('Poll/execute error:', err instanceof Error ? err.message : err);
+    }
+  };
+
+  const pollInterval = setInterval(poll, config.pollInterval * 1000);
+
+  console.log(`\nRunner "${config.name}" is online and polling every ${config.pollInterval}s`);
+  console.log(`Providers: ${availableProviders.join(', ') || '(none)'}`);
+  console.log('Press Ctrl+C to stop.\n');
+
+  // ── Graceful Shutdown ───────────────────────────────────────────────────
+  const shutdown = async (signal: string) => {
+    console.log(`\nReceived ${signal}, shutting down...`);
+    clearInterval(heartbeatInterval);
+    clearInterval(pollInterval);
+
+    if (killCurrent) {
+      console.log('Killing running task...');
+      killCurrent();
+    }
+
+    // Give a moment for cleanup
+    setTimeout(() => process.exit(0), 500);
+  };
+
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+}

package/src/executor.ts

@@ -0,0 +1,96 @@
+import { spawn, ChildProcess } from 'child_process';
+import { Task } from './types';
+
+export interface ExecutionResult {
+  success: boolean;
+  output: string;
+  sendOnComplete: boolean;
+}
+
+/** Build the CLI command + args for a given AI provider. */
+function buildCommand(aiProvider: string, prompt: string): {
+  cmd: string;
+  args: string[];
+  streamOutput: boolean;
+} {
+  switch (aiProvider) {
+    case 'claude-code':
+      return { cmd: 'claude', args: ['-p', prompt, "--tools", "all"], streamOutput: true };
+    case 'codex':
+      return {
+        cmd: 'codex',
+        args: ['exec', prompt, '--sandbox', 'workspace-write', '--color', 'never'],
+        streamOutput: true,
+      };
+    default:
+      throw new Error(`Unknown AI provider: ${aiProvider}`);
+  }
+}
+
+/**
+ * Execute a task using the specified AI CLI tool.
+ * Calls `onOutput` with buffered chunks every ~2 seconds.
+ * Returns when the process exits.
+ */
+export function executeTask(
+  task: Task,
+  onOutput: (chunk: string) => void,
+): { promise: Promise<ExecutionResult>; kill: () => void } {
+  const { cmd, args, streamOutput } = buildCommand(task.ai_provider!, task.description || task.title);
+
+  let child: ChildProcess;
+  let fullOutput = '';
+  let buffer = '';
+  let flushTimer: ReturnType<typeof setInterval>;
+
+  const promise = new Promise<ExecutionResult>((resolve) => {
+    console.log(`  Spawning: ${cmd} ${args.join(' ')}`);
+
+    child = spawn(cmd, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env },
+    });
+
+    const flush = () => {
+      if (streamOutput && buffer.length > 0) {
+        onOutput(buffer);
+        buffer = '';
+      }
+    };
+
+    flushTimer = setInterval(flush, 2000);
+
+    child.stdout?.on('data', (data: Buffer) => {
+      const text = data.toString();
+      fullOutput += text;
+      buffer += text;
+    });
+
+    child.stderr?.on('data', (data: Buffer) => {
+      const text = data.toString();
+      fullOutput += text;
+      buffer += text;
+    });
+
+    child.on('error', (err) => {
+      clearInterval(flushTimer);
+      flush();
+      fullOutput += `\n[Error: ${err.message}]`;
+      resolve({ success: false, output: fullOutput, sendOnComplete: true });
+    });
+
+    child.on('close', (code) => {
+      clearInterval(flushTimer);
+      flush();
+      const success = code === 0;
+      resolve({ success, output: fullOutput, sendOnComplete: !streamOutput || !success });
+    });
+  });
+
+  const kill = () => {
+    clearInterval(flushTimer!);
+    child?.kill('SIGTERM');
+  };
+
+  return { promise, kill };
+}

package/src/types.ts

@@ -0,0 +1,40 @@
+export interface RunnerConfig {
+  name: string;
+  url: string;
+  providers: string[];
+  lastCliScanAt: string;
+  pollInterval: number;  // seconds
+  token?: string;
+  secret?: string;
+  device: string;
+}
+
+export interface Task {
+  id: string;
+  project_id: string;
+  task_number: number;
+  task_key: string;
+  title: string;
+  description: string;
+  status: string;
+  priority: string;
+  runner_id: string | null;
+  ai_provider: string | null;
+  labels: string;
+  output: string | null;
+  started_at: string | null;
+  completed_at: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface RegisterResponse {
+  id: string;
+  token: string;
+}
+
+export interface HeartbeatResponse {
+  ok: boolean;
+  status: string;
+  refreshCli?: boolean;
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}