@peakflo/agent-harness 0.2.8 → 0.2.9-rc.2

package/README.md

@@ -4,7 +4,9 @@ Run a Peakflo coding agent on your machine.
 
 ## Quick start
 
-Use Node.js 22.19 or newer and install Git. Install the Pi coding agent once:
+Use Node.js 22.19 or newer and install Git. The runner checks the Node.js
+version when it starts and stops with one line if it is older (see
+"Troubleshooting"). Install the Pi coding agent once:
 
 ```sh
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent
@@ -36,6 +38,70 @@ Optional flags include `--health-port <port>`, `--runtime <desktop|self-hosted>`
 `--workspace-root <path>`, and `--github-proxy-port <port>`. Run
 `npx @peakflo/agent-harness@rc --help` for the full list.
 
+## Harnesses found on your machine
+
+On a desktop or self-hosted machine the runner looks for Codex (`codex`),
+Claude Code (`claude`), Cursor (`cursor-agent`), Pi (`pi`) and OpenCode
+(`opencode`). For each one it reports whether it is installed, its version,
+whether it is signed in, and the models it offers. Peakflo shows this list in
+the agent editor and in the chat details.
+
+Finding a harness does not mean the runner can use it. The runner runs turns
+with Pi only; the other harnesses are shown as "Detected, not yet runnable by
+this runner".
+
+**When it looks.** Once after start, without delaying registration, and then
+every five minutes while no turn is running. A harness you install or sign in
+to later appears without a restart. At most two of these programs run at the
+same time.
+
+**A slow machine.** Some of these programs take several seconds to start. When
+one does not answer in time, Peakflo shows it as "Installed — check timed out,
+will retry", not as unavailable. The runner checks it again after 30 seconds,
+then 60, then 120, and after that with the normal five-minute pass. A state
+that was already known (signed in, or not signed in) is kept when a later
+check times out.
+
+**What it runs.** To do this the runner starts those programs, as your user,
+with `--version` and a status or model-list command. It looks in the absolute
+directories of your `PATH` and in the usual install directories
+(`~/.local/bin`, `~/.opencode/bin`, `/opt/homebrew/bin`, `/usr/local/bin`,
+`~/.npm-global/bin`, `~/.volta/bin`, `~/.bun/bin`, and the directory of the
+running `node`). Relative `PATH` entries are ignored. The programs are started
+without the runner's own `PF_*` variables, so they do not receive the
+enrolment token.
+
+**What it sends.** Names, versions, a signed-in yes/no with a fixed reason,
+and model names. It does not send file paths, account names, tokens, API keys
+or the content of credential files. Model names that look like an email
+address or a key are dropped; that check is a safety net, not a guarantee
+about what a third-party program prints.
+
+**Turning it off.** Start with `--no-harness-discovery`, or set
+`PF_HARNESS_DISCOVERY=0`. The runner then starts none of these programs and
+reports no list. Running turns with Pi is not affected.
+
+## Troubleshooting
+
+**`npx @peakflo/agent-harness` fails with a 404.** Your `~/.npmrc` maps the
+`@peakflo` scope to another registry (for example GitHub Packages). Name the
+public registry for this one command:
+
+```sh
+npx --@peakflo:registry=https://registry.npmjs.org @peakflo/agent-harness@latest start
+```
+
+**"pf-agent-harness needs Node.js 22.19 or newer".** Switch to a newer
+Node.js, for example `nvm install 22 && nvm use 22`, and start again. npm only
+prints an `EBADENGINE` warning for an older Node.js and installs anyway; the
+runner is what stops. The requirement comes from Pi, which the runner starts
+with the same Node.js. To start on an older Node.js at your own risk, set
+`PF_ALLOW_UNSUPPORTED_NODE=1`.
+
+**"Durable store unavailable, running in memory".** The runner could not
+create or open its database under `--workspace-root`. It creates that
+directory itself when it is missing, so check that the path is writable.
+
 ## Releasing
 
 `.github/scripts/agent-harness-release.mjs` publishes this package

package/dist/cli.js

@@ -38,6 +38,7 @@ const adapters_1 = require("./adapters");
 const contract_1 = require("./contract");
 const credential_store_1 = require("./credential-store");
 const harness_1 = require("./harness");
+const node_floor_1 = require("./node-floor");
 const options_1 = require("./options");
 const version_1 = require("./version");
 const USAGE = `pf-agent-harness — headless Peakflo coding-agent harness
@@ -75,6 +76,14 @@ Options:
   --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)
+  --no-harness-discovery        do not look for Codex, Claude Code, Cursor,
+                                Pi and OpenCode on this machine, and report
+                                none (env PF_HARNESS_DISCOVERY=0). On by
+                                default for desktop/self-hosted; never runs
+                                in a sandbox.
+
+Needs Node.js 22.19 or newer; start stops with one line on an older one.
+PF_ALLOW_UNSUPPORTED_NODE=1 starts anyway, at your own risk.
 
 In a managed sandbox pf-bootstrap supplies these through the environment, so
 the enrolment token never appears in /proc/<pid>/cmdline.
@@ -139,6 +148,26 @@ async function main() {
         process.exitCode = 2;
         return;
     }
+    /*
+     * THE NODE.JS FLOOR — checked first, before the browser sign-in, so nobody
+     * signs in and picks an organisation only to be told to change Node. See
+     * `node-floor.ts` for where the floor comes from and why a sandbox only
+     * warns.
+     */
+    const nodeFloor = (0, node_floor_1.checkNodeFloor)({
+        current: process.versions.node,
+        floor: (0, version_1.getNodeFloor)(),
+        runtime: readOptionValue(argv.slice(1), 'runtime') ??
+            process.env.PF_RUNNER_RUNTIME,
+        env: process.env
+    });
+    if (nodeFloor.action === 'refuse') {
+        process.stderr.write(`${nodeFloor.message}\n`);
+        process.exit(1);
+    }
+    if (nodeFloor.action === 'warn') {
+        process.stderr.write(`Warning: ${nodeFloor.message}\n`);
+    }
     /*
      * NO TOKEN? OFFER TO SIGN IN, BUT ONLY WHERE THAT CAN POSSIBLY WORK.
      *

package/dist/harness-discovery.d.ts

@@ -0,0 +1,173 @@
+/**
+ * HARNESS DISCOVERY — which coding harnesses are installed on this machine.
+ *
+ * Modelled on 20x, where the harness code came from:
+ *   - `src/main/agent-installer/detect.js` finds the binaries (`claude`,
+ *     `codex`, `cursor-agent`, `opencode`, `pi`) with `--version`, after it
+ *     puts the well-known install directories on PATH;
+ *   - `src/renderer/src/types/index.ts` holds the static model lists the 20x
+ *     agent form shows for Claude Code, Codex and Cursor.
+ *
+ * WHAT THIS IS NOT. It is not the list of backends this runner can run.
+ * `capabilities.backends` stays that list and the control plane routes on it.
+ * An entry here says "this CLI is on the machine", and `runnable` says whether
+ * the runner can also drive it. Detection never implies turn support.
+ *
+ * RULES THIS MODULE KEEPS:
+ *
+ * 1. NEVER THROWS, NEVER REJECTS. One broken CLI must not hide the others, so
+ *    every harness is probed on its own, inside its own try/catch and its own
+ *    deadline.
+ * 2. TIME-LIMITED. Each command has a timeout and each harness has a total
+ *    deadline. A CLI that hangs is killed and reported as timed out.
+ * 3. NO SECRETS LEAVE THIS FILE. Sign-in is decided from an exit code, one
+ *    boolean of a status reply, or the existence of an environment variable or
+ *    a file. No status text is kept. Every `reason` is a constant from
+ *    `REASONS` below, never something a CLI printed. Model ids and names are
+ *    the only CLI text that is reported, and each one is checked first.
+ * 4. NO GLOBAL SIDE EFFECTS. `process.env.PATH` is not changed; the search path
+ *    is local and is handed to each child process.
+ */
+import type { RunnerHarness, RunnerHarnessModel } from './types';
+/**
+ * One command: `--version`, a status check, or a model listing.
+ *
+ * MEASURED, NOT GUESSED. On the Mac where the first release candidate was
+ * tried, with two runners and other work going on, `cursor-agent --version`
+ * took 9.4 s cold and 3.7 s warm ALONE, and 6-10 s when five harnesses were
+ * probed at once; `opencode --version` took 3-5 s alone and 7-9 s beside the
+ * others. The first limit was 8 s, so both lost on a busy machine and were
+ * shown as broken. The limit is now well above the slowest start seen — and
+ * the pass no longer starts every CLI at once (`DISCOVERY_CONCURRENCY`),
+ * which is what made each of them slow.
+ */
+export declare const DISCOVERY_COMMAND_TIMEOUT_MS = 20000;
+/**
+ * The budget for finding out a harness's STATE: its version and whether it is
+ * signed in. The model listing is NOT inside this budget — it has one command
+ * timeout of its own and can never change the state (see `probeHarness`).
+ */
+export declare const DISCOVERY_HARNESS_TIMEOUT_MS = 45000;
+/**
+ * How many harnesses are probed at the same time. Each harness runs its
+ * commands one after another, so this is also the most CLI processes
+ * discovery ever has running. Two, not five: these CLIs are heavy to start
+ * (most are bundled Node programs), and five cold starts at once roughly
+ * doubled the start time of each on the test machine.
+ */
+export declare const DISCOVERY_CONCURRENCY = 2;
+/**
+ * Every sentence a `reason` can be. A closed set on purpose: text printed by a
+ * CLI can hold an account email or a key, and a constant cannot.
+ */
+export declare const REASONS: {
+    readonly notInstalled: "Not installed on this machine.";
+    readonly versionTimedOut: "Installed. The version check timed out and will be tried again.";
+    readonly versionFailed: "The version check failed.";
+    readonly discoveryTimedOut: "Installed. The check timed out and will be tried again.";
+    readonly discoveryFailed: "Discovery failed.";
+    readonly signInTimedOut: "Installed. The sign-in check timed out and will be tried again.";
+    readonly signInUnknown: "Sign-in could not be confirmed.";
+    readonly codexSignIn: "Not signed in. Run `codex login` on this machine.";
+    readonly claudeSignIn: "Not signed in. Run `claude auth login` on this machine.";
+    readonly cursorSignIn: "Not signed in. Run `cursor-agent login` on this machine.";
+};
+/** 20x `CLAUDE_MODELS`. Claude Code has no command that lists models. */
+export declare const CLAUDE_STATIC_MODELS: ReadonlyArray<RunnerHarnessModel>;
+/** 20x `CODEX_MODELS`. Used only when Codex's own model cache cannot be read. */
+export declare const CODEX_STATIC_MODELS: ReadonlyArray<RunnerHarnessModel>;
+/** 20x `CURSOR_MODELS`. Used only when `cursor-agent models` gives nothing. */
+export declare const CURSOR_STATIC_MODELS: ReadonlyArray<RunnerHarnessModel>;
+export interface DiscoveryExecResult {
+    /** Exit code, or null when the process did not exit by itself. */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+/** Everything that touches the machine. Replaced in tests. */
+export interface DiscoveryDeps {
+    /** Run one command. MUST NOT reject. */
+    exec(command: string, args: string[], timeoutMs: number): Promise<DiscoveryExecResult>;
+    /** Absolute path of a command, or null when it is not installed. */
+    resolveCommand(command: string): string | null;
+    realpath(path: string): string;
+    /** File text, or null when it cannot be read. */
+    readFile(path: string): string | null;
+    exists(path: string): boolean;
+    env: NodeJS.ProcessEnv;
+    home: string;
+    now(): Date;
+}
+export interface DiscoverHarnessesOptions {
+    /** Backend names this runner can run turns with (`capabilities.backends`). */
+    runnableBackends?: readonly string[];
+    commandTimeoutMs?: number;
+    harnessTimeoutMs?: number;
+    /** Harnesses probed at once. Defaults to `DISCOVERY_CONCURRENCY`. */
+    concurrency?: number;
+    /**
+     * Probe ONLY these harnesses and return only their entries. Used to check
+     * again the ones whose last check timed out, without starting the others.
+     */
+    only?: readonly string[];
+    deps?: Partial<DiscoveryDeps>;
+}
+/**
+ * Where to look for a harness binary: PATH first, then the directories the
+ * harness installers use. The well-known directories come from 20x
+ * `detect.js` (`ensureAgentPaths` and `getPiCommandCandidates`). The directory
+ * of the running `node` is added because a runner started by launchd or
+ * systemd has a short PATH, and an npm-installed CLI sits beside that `node`.
+ */
+export declare function discoverySearchPath(env: NodeJS.ProcessEnv, home: string, platform?: NodeJS.Platform): string[];
+/**
+ * The environment a harness CLI is started with.
+ *
+ * EVERY `PF_*` VARIABLE IS REMOVED. Those are this runner's own settings and
+ * include `PF_ENROLMENT_TOKEN`; a third-party CLI has no use for them and
+ * must not be handed them. The rest is kept, because each CLI finds its own
+ * login through it (`HOME`, `CODEX_HOME`, `ANTHROPIC_API_KEY`, ...).
+ */
+export declare function discoveryChildEnv(env: NodeJS.ProcessEnv, searchPath: readonly string[]): NodeJS.ProcessEnv;
+/**
+ * Keep only entries that look like a model. Anything that looks like a secret
+ * is dropped whole: a model list has no reason to hold one, so the safe
+ * reading of such a line is that it is not a model.
+ */
+export declare function sanitizeHarnessModels(models: ReadonlyArray<{
+    id: unknown;
+    name?: unknown;
+    default?: unknown;
+}>): RunnerHarnessModel[];
+/** The first version-like token, as 20x `detect.js` reads it. */
+export declare function parseVersion(output: string): string | null;
+export declare function saysSignedOut(text: string): boolean;
+/**
+ * Codex keeps the models its account can use in `models_cache.json`. This is a
+ * model cache, not a credential file; only `slug`, `display_name`,
+ * `visibility` and `priority` are read from it.
+ */
+export declare function parseCodexModelCache(text: string | null): RunnerHarnessModel[];
+/** The top-level `model = "..."` of `config.toml`. Nothing else is read. */
+export declare function parseCodexDefaultModel(text: string | null): string | null;
+/**
+ * `cursor-agent models` prints one `id - Name` line per model and marks the
+ * default with `(current, default)` or `(default)`.
+ */
+export declare function parseCursorModels(output: string): RunnerHarnessModel[];
+/** `opencode models` prints one `provider/model` id per line. */
+export declare function parseOpencodeModels(output: string): RunnerHarnessModel[];
+/** Every harness this build knows how to look for, in display order. */
+export declare const KNOWN_HARNESSES: ReadonlyArray<{
+    name: string;
+    label: string;
+}>;
+/**
+ * Look for every known harness. ALWAYS resolves, with one entry per known
+ * harness in a fixed order — a harness that is missing is reported as
+ * `installed: false`, so the reader can tell "not installed" from "this runner
+ * does not report harnesses". With `only`, just those harnesses are probed and
+ * returned.
+ */
+export declare function discoverHarnesses(options?: DiscoverHarnessesOptions): Promise<RunnerHarness[]>;