@peakflo/agent-harness 0.0.0-stage → 0.2.2-rc.1

package/dist/capabilities.d.ts

@@ -0,0 +1,58 @@
+/**
+ * THE CAPABILITY PROBE.
+ *
+ * Ported from 20x `src/main/agent-installer/detect.js`, which has been probing
+ * these same binaries in production since long before this package existed.
+ * The detection logic — PATH repair, `--version`, the version-extracting
+ * regular expression, the swallow-everything failure mode — is reproduced
+ * rather than reinvented, because every line of it encodes a platform quirk
+ * somebody already hit.
+ *
+ * WHAT CHANGED IN THE PORT, and why:
+ *
+ * 1. It reports the WIRE shape (`RunnerCapabilities`) rather than the desktop's
+ *    installer-shaped record. The control plane routes work on this, so it must
+ *    speak the contract's vocabulary, not the installer's.
+ *
+ * 2. Probes run with a hard timeout and never reject. A capability probe that
+ *    can fail is a runner that can fail to register, and "docker is missing" is
+ *    not a reason to refuse to run an agent that does not need docker.
+ *
+ * 3. The result is NOT cached across calls. A host is upgraded in place — a
+ *    backend can be installed and docker can appear without the runner ever
+ *    restarting — which is exactly why the contract refreshes capabilities on
+ *    every heartbeat rather than trusting the registration snapshot.
+ */
+import { RunnerCapabilities } from './types';
+export interface ProbeResult {
+    installed: boolean;
+    version: string | null;
+}
+/**
+ * Run one command and pull a version out of its stdout. NEVER REJECTS.
+ *
+ * `shell: true` on Windows is load-bearing and not a style choice — without it
+ * `.cmd`/`.bat` wrappers, which is how npm installs binaries on Windows, do not
+ * resolve at all and every backend reports as missing.
+ */
+export declare function probe(command: string, args?: string[]): Promise<ProbeResult>;
+export interface ProbeCapabilitiesOptions {
+    /**
+     * How many sessions this host will run at once.
+     *
+     * DEFAULTS TO 1, and that default is a security position rather than a
+     * performance one: cross-session isolation on a shared customer VM is the
+     * customer's duty, and 1 is the only value that needs no such assumption.
+     */
+    maxConcurrentSessions?: number;
+    /** Free-form routing labels, e.g. ['eu-only', 'has-vpn']. */
+    labels?: string[];
+}
+/**
+ * Everything the control plane needs to decide whether to send work here.
+ *
+ * All probes run CONCURRENTLY. Serially this would cost six process spawns at
+ * up to 10s each on a host where nothing is installed, and it runs on every
+ * heartbeat.
+ */
+export declare function probeCapabilities(options?: ProbeCapabilitiesOptions): Promise<RunnerCapabilities>;

package/dist/capabilities.js

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * THE CAPABILITY PROBE.
+ *
+ * Ported from 20x `src/main/agent-installer/detect.js`, which has been probing
+ * these same binaries in production since long before this package existed.
+ * The detection logic — PATH repair, `--version`, the version-extracting
+ * regular expression, the swallow-everything failure mode — is reproduced
+ * rather than reinvented, because every line of it encodes a platform quirk
+ * somebody already hit.
+ *
+ * WHAT CHANGED IN THE PORT, and why:
+ *
+ * 1. It reports the WIRE shape (`RunnerCapabilities`) rather than the desktop's
+ *    installer-shaped record. The control plane routes work on this, so it must
+ *    speak the contract's vocabulary, not the installer's.
+ *
+ * 2. Probes run with a hard timeout and never reject. A capability probe that
+ *    can fail is a runner that can fail to register, and "docker is missing" is
+ *    not a reason to refuse to run an agent that does not need docker.
+ *
+ * 3. The result is NOT cached across calls. A host is upgraded in place — a
+ *    backend can be installed and docker can appear without the runner ever
+ *    restarting — which is exactly why the contract refreshes capabilities on
+ *    every heartbeat rather than trusting the registration snapshot.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.probe = probe;
+exports.probeCapabilities = probeCapabilities;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const version_1 = require("./version");
+const PROBE_TIMEOUT_MS = 10_000;
+/**
+ * The coding-agent backends this harness knows how to drive, and the command
+ * that reports each one's version.
+ *
+ * The NAMES are the contract's open backend vocabulary and must match what the
+ * control plane puts in `LeasedAgent.backend`. The COMMANDS are what 20x's
+ * installer already probes.
+ */
+const BACKEND_PROBES = [
+    { name: 'pi', command: 'pi' }
+];
+/**
+ * Put the well-known install directories on PATH before probing.
+ *
+ * Straight from detect.js. Without it a backend installed by its own installer
+ * is invisible until the process restarts — on the desktop that meant "restart
+ * the app after installing", and on a runner it would mean a host that silently
+ * reports a backend it actually has.
+ */
+function ensureAgentPaths() {
+    const home = (0, node_os_1.homedir)();
+    const sep = process.platform === 'win32' ? ';' : ':';
+    const segments = (process.env.PATH || '').split(sep);
+    const knownDirs = [
+        (0, node_path_1.join)(home, '.local', 'bin') // Linux binary installs
+    ];
+    for (const dir of knownDirs) {
+        if ((0, node_fs_1.existsSync)(dir) &&
+            !segments.includes(dir) &&
+            !segments.includes(`${dir}/`)) {
+            process.env.PATH = `${dir}${sep}${process.env.PATH}`;
+        }
+    }
+}
+/**
+ * Run one command and pull a version out of its stdout. NEVER REJECTS.
+ *
+ * `shell: true` on Windows is load-bearing and not a style choice — without it
+ * `.cmd`/`.bat` wrappers, which is how npm installs binaries on Windows, do not
+ * resolve at all and every backend reports as missing.
+ */
+function probe(command, args = ['--version']) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (result) => {
+            if (!settled) {
+                settled = true;
+                resolve(result);
+            }
+        };
+        try {
+            (0, node_child_process_1.execFile)(command, args, {
+                timeout: PROBE_TIMEOUT_MS,
+                shell: process.platform === 'win32',
+                windowsHide: true
+            }, (error, stdout) => {
+                if (error) {
+                    finish({ installed: false, version: null });
+                    return;
+                }
+                const raw = String(stdout).trim();
+                // Same expression as detect.js: pick the first version-like token, and
+                // fall back to the first line when a tool prints something exotic.
+                const match = raw.match(/(\d+\.\d+[\w.-]*)/);
+                finish({
+                    installed: true,
+                    version: match ? match[1] : raw.split('\n')[0] || null
+                });
+            });
+        }
+        catch {
+            // execFile can throw synchronously (EACCES on a non-executable path).
+            finish({ installed: false, version: null });
+        }
+    });
+}
+/**
+ * `os.hostname()` throws on some locked-down containers. A host that cannot
+ * name itself is still a perfectly good runner, so this must not be fatal.
+ */
+function safeHostname() {
+    try {
+        return (0, node_os_1.hostname)() || 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Everything the control plane needs to decide whether to send work here.
+ *
+ * All probes run CONCURRENTLY. Serially this would cost six process spawns at
+ * up to 10s each on a host where nothing is installed, and it runs on every
+ * heartbeat.
+ */
+async function probeCapabilities(options = {}) {
+    ensureAgentPaths();
+    const [git, docker, ...backendResults] = await Promise.all([
+        probe('git'),
+        probe('docker'),
+        ...BACKEND_PROBES.map((b) => probe(b.command))
+    ]);
+    const backends = BACKEND_PROBES.map((b, index) => ({
+        name: b.name,
+        result: backendResults[index]
+    }))
+        // Only INSTALLED backends are reported. A backend listed with a null
+        // version would be indistinguishable from one that is present but whose
+        // version could not be read, and the control plane routes on this list.
+        .filter((entry) => entry.result?.installed)
+        .map((entry) => ({ name: entry.name, version: entry.result.version }));
+    const sandboxToolsVersion = (0, version_1.getInstalledSandboxToolsVersion)();
+    return {
+        os: process.platform,
+        arch: process.arch,
+        harnessVersion: (0, version_1.getHarnessVersion)(),
+        ...(sandboxToolsVersion ? { sandboxToolsVersion } : {}),
+        nodeVersion: process.version,
+        hostname: safeHostname(),
+        backends,
+        git: git.installed,
+        docker: docker.installed,
+        maxConcurrentSessions: options.maxConcurrentSessions ?? 1,
+        labels: options.labels
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const adapters_1 = require("./adapters");
+const contract_1 = require("./contract");
+const credential_store_1 = require("./credential-store");
+const harness_1 = require("./harness");
+const options_1 = require("./options");
+const version_1 = require("./version");
+const USAGE = `pf-agent-harness — headless Peakflo coding-agent harness
+
+Usage:
+  pf-agent-harness start [options]
+  pf-agent-harness version
+
+Options:
+  --control-plane <url>         workflow-api base url (env PF_CONTROL_PLANE_URL)
+  --token <token>               enrolment token       (env PF_ENROLMENT_TOKEN)
+                                Omit it at a terminal and the runner opens your
+                                browser to sign in, then asks which organisation
+                                to join — the same shape 20x uses.
+  --login                       force the browser sign-in even without a TTY
+  --app-url <url>               where the web app lives (env PF_APP_URL);
+                                derived from --control-plane when omitted
+  --label <name>                runner name shown in the UI (env PF_RUNNER_LABEL,
+                                default this machine's hostname)
+  --health-port <port>          loopback health port  (env PF_HARNESS_HEALTH_PORT, default 7777)
+  --github-proxy-port <port>    loopback GitHub proxy (env PF_GITHUB_PROXY_PORT, default 7780)
+  --worktree-wip-commit <bool>  save dirty work in a WIP commit after each turn
+                                (env PF_WORKTREE_WIP_COMMIT; default true in
+                                 sandbox, false otherwise)
+  --heartbeat-interval-ms <ms>  heartbeat cadence, 1000-3600000
+                                (env PF_HARNESS_HEARTBEAT_INTERVAL_MS,
+                                 default 30000)
+  --degraded                    started from the warm fallback copy
+  --degraded-reason <text>      why the fallback was used
+  --workspace-root <path>       session workspaces    (env PF_WORKSPACE_ROOT;
+                                defaults under ~/.pf-agent-harness, or
+                                /var/pf/workspaces in a managed sandbox)
+  --runtime <mode>              sandbox | self-hosted | desktop
+                                (env PF_RUNNER_RUNTIME, default desktop)
+  --max-sessions <n>            concurrent sessions   (env PF_MAX_CONCURRENT_SESSIONS,
+                                default 10 for desktop/self-hosted; sandbox is configured by control plane)
+  --labels <a,b>                routing labels        (env PF_RUNNER_LABELS)
+
+In a managed sandbox pf-bootstrap supplies these through the environment, so
+the enrolment token never appears in /proc/<pid>/cmdline.
+`;
+/**
+ * Which adapter drives which backend.
+ *
+ * PI ONLY IN THIS BUILD, even though the legacy adapters remain exported for
+ * extracted and are exported from the package. The others are wired by a HOST
+ * that has verified their prerequisites: Claude Code needs
+ * `@anthropic-ai/claude-agent-sdk` (an optional dependency, absent from the
+ * sandbox image), and Codex and ACP need binaries the image does not ship.
+ * Advertising a backend the host cannot actually run would make the control
+ * plane route work to a runner that must then fail it.
+ */
+function resolveAdapter(backend, ports) {
+    if (backend === 'pi') {
+        // The adapter reads the per-turn gateway holder directly. If the lease has
+        // no model token SessionRunner refuses before this constructor is reached.
+        return new adapters_1.PiAdapter(ports.modelGateway);
+    }
+    throw new Error(`Backend "${backend}" is not wired in this build. ` +
+        'Only "pi" is available; the other adapters are exported for a ' +
+        'host to wire once it has verified their prerequisites.');
+}
+/**
+ * Read `--flag value` from argv. A tiny duplicate of the reader in options.ts,
+ * because the login decision has to be made BEFORE `parseOptions` runs — that
+ * is the very call that throws when the token is missing.
+ */
+function readOptionValue(argv, flag) {
+    // `--flag=value` FIRST. Without this, `--token=abc` matched no `--token`
+    // argument, so a runner started with a token at a terminal fell through to
+    // the browser sign-in — asking a human to authorise something they had
+    // already authorised, and burning the token they supplied.
+    const inline = argv.find((arg) => arg.startsWith(`--${flag}=`));
+    if (inline)
+        return inline.slice(`--${flag}=`.length) || undefined;
+    const index = argv.indexOf(`--${flag}`);
+    if (index === -1)
+        return undefined;
+    const value = argv[index + 1];
+    return value && !value.startsWith('--') ? value : undefined;
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const command = argv[0];
+    if (!command || command === 'help' || command === '--help') {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (command === 'version' || command === '--version') {
+        process.stdout.write(`${JSON.stringify({
+            harnessVersion: (0, version_1.getHarnessVersion)(),
+            nodeVersion: process.version,
+            piVersion: (0, version_1.getPiVersion)()
+        })}\n`);
+        return;
+    }
+    if (command !== 'start') {
+        process.stderr.write(`Unknown command: ${command}\n\n${USAGE}`);
+        process.exitCode = 2;
+        return;
+    }
+    /*
+     * NO TOKEN? OFFER TO SIGN IN, BUT ONLY WHERE THAT CAN POSSIBLY WORK.
+     *
+     * The interactive flow needs a human at a terminal and a browser on this
+     * machine. A managed sandbox has neither, and pf-bootstrap always supplies
+     * the token through the environment — so a sandbox missing its token must
+     * FAIL FAST with the original error rather than sit for ten minutes waiting
+     * for a browser that will never open. That would turn a loud, recyclable
+     * start-up failure into a silent hang, which is the worse of the two.
+     *
+     * Hence: only when stdin and stdout are both a TTY, or when `--login` asks
+     * for it explicitly.
+     */
+    const startArgs = argv.slice(1);
+    const wantsLogin = startArgs.includes('--login');
+    // `--token=x` counts as a token, hence readOptionValue rather than indexOf.
+    const hasToken = Boolean(readOptionValue(startArgs, 'token') ?? process.env.PF_ENROLMENT_TOKEN);
+    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    if (!hasToken && (wantsLogin || interactive)) {
+        const { enrolViaBrowser } = await Promise.resolve().then(() => __importStar(require('./enrol/browser-enrol')));
+        const token = await enrolViaBrowser({
+            controlPlaneUrl: readOptionValue(startArgs, 'control-plane') ??
+                process.env.PF_CONTROL_PLANE_URL ??
+                '',
+            runtime: readOptionValue(startArgs, 'runtime') ??
+                process.env.PF_RUNNER_RUNTIME ??
+                'desktop',
+            appUrl: readOptionValue(startArgs, 'app-url') ?? process.env.PF_APP_URL,
+            label: readOptionValue(startArgs, 'label') ?? process.env.PF_RUNNER_LABEL
+        });
+        // Handed on through the environment rather than argv, for the same reason
+        // pf-bootstrap does: argv is world-readable via /proc/<pid>/cmdline.
+        process.env.PF_ENROLMENT_TOKEN = token;
+    }
+    const options = (0, options_1.parseOptions)(startArgs, process.env);
+    const handedOffCredential = (0, credential_store_1.takeHandedOffCredential)(process.env);
+    const harness = new harness_1.Harness(options, {
+        getAdapter: (backend, ports) => resolveAdapter(backend, ports),
+        ...(handedOffCredential
+            ? { credentialStore: new credential_store_1.MemoryCredentialStore(handedOffCredential) }
+            : {}),
+        onUpgradeRequested: (request) => {
+            if (typeof process.send === 'function') {
+                process.send({ type: 'pf-harness-upgrade', ...request });
+            }
+        }
+    });
+    let shuttingDown = false;
+    const shutdown = (signal) => {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
+        process.stderr.write(`Received ${signal}, shutting down\n`);
+        void harness.stop().then(() => process.exit(0));
+    };
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    await harness.start();
+    // BLOCK ON THE LEASE LOOP, and let it decide when the process is done.
+    //
+    // The Phase 0 skeleton relied on the health socket keeping the event loop
+    // alive, which meant nothing could ever end the process deliberately — a
+    // refused protocol version would have hung instead of exiting. `wait()`
+    // resolves on a clean drain and rejects when the control plane refused this
+    // build, so the exit code carries the reason.
+    try {
+        await harness.wait();
+    }
+    catch (error) {
+        if (error instanceof harness_1.UpgradeRequestedError) {
+            process.exit(contract_1.HARNESS_UPGRADE_EXIT_CODE);
+        }
+        throw error;
+    }
+}
+main().catch((error) => {
+    // process.exit, NOT process.exitCode. `exitCode` only takes effect when the
+    // event loop drains on its own, and a start-up failure can leave a listening
+    // socket or a pending timer behind, which would keep the process alive for
+    // ever. A sandbox that hangs is worse than one that dies: the control plane
+    // cannot recycle it, so the version gate would never take effect.
+    if (error instanceof options_1.OptionsError) {
+        process.stderr.write(`${error.message}\n\n${USAGE}`);
+        process.exit(2);
+    }
+    const message = error instanceof Error ? error.stack : String(error);
+    process.stderr.write(`pf-agent-harness failed to start:\n${message}\n`);
+    process.exit(1);
+});