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

package/README.md

@@ -36,6 +36,41 @@ 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.
+
+**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.
+
 ## Releasing
 
 `.github/scripts/agent-harness-release.mjs` publishes this package

package/dist/cli.js

@@ -75,6 +75,11 @@ 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.
 
 In a managed sandbox pf-bootstrap supplies these through the environment, so
 the enrolment token never appears in /proc/<pid>/cmdline.

package/dist/harness-discovery.d.ts

@@ -0,0 +1,142 @@
+/**
+ * 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. */
+export declare const DISCOVERY_COMMAND_TIMEOUT_MS = 8000;
+/** Everything for one harness. Harnesses run concurrently, so this is also the bound for the whole pass. */
+export declare const DISCOVERY_HARNESS_TIMEOUT_MS = 20000;
+/**
+ * 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: "The version check timed out.";
+    readonly versionFailed: "The version check failed.";
+    readonly discoveryTimedOut: "Discovery timed out.";
+    readonly discoveryFailed: "Discovery failed.";
+    readonly signInTimedOut: "The sign-in check timed out.";
+    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;
+    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".
+ */
+export declare function discoverHarnesses(options?: DiscoverHarnessesOptions): Promise<RunnerHarness[]>;