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

package/dist/harness.d.ts

@@ -2,8 +2,41 @@ import type { CodingAgentAdapter } from './adapters';
 import { SessionModelGateway } from './adapters/model-gateway';
 import { ControlPlaneClient } from './control-plane';
 import { CredentialStore } from './credential-store';
+import { type DiscoverHarnessesOptions } from './harness-discovery';
 import { ArtifactInspector, EventSink, Notifier, SecretProvider, Telemetry, ConversationStore, TranscriptStore, WorkspaceProvider } from './ports';
-import { HarnessOptions, HealthReport } from './types';
+import { HarnessOptions, HealthReport, RunnerHarness } from './types';
+/**
+ * How often the installed harnesses are looked for again.
+ *
+ * Five minutes: short enough that a harness installed or signed in to after
+ * start shows up without a restart or a re-enrol, and long enough that the
+ * heartbeat (30 s) does not start a handful of CLIs every time. Between passes
+ * every heartbeat sends the cached answer.
+ */
+export declare const HARNESS_DISCOVERY_REFRESH_MS: number;
+/**
+ * How long after a pass the checks that TIMED OUT are tried again: three
+ * times, each wait twice the one before. See `scheduleHarnessRetry`.
+ */
+export declare const HARNESS_RETRY_DELAYS_MS: readonly number[];
+/**
+ * Put the result of a pass together with what was known before.
+ *
+ * KEEP THE LAST GOOD STATE. A check that timed out learnt nothing, so when
+ * the previous pass DID settle that harness (signed in, signed out, version
+ * failed) that answer stays. Only a harness with no settled answer yet is
+ * shown as "check timed out, will be tried again".
+ *
+ * A retry pass returns only the harnesses it probed; the others are kept.
+ */
+export declare function mergeHarnessReports(previous: readonly RunnerHarness[] | null, fresh: readonly RunnerHarness[]): RunnerHarness[];
+/** Listed in `capabilities.features` when `capabilities.harnesses` is sent. */
+export declare const HARNESS_DISCOVERY_FEATURE = "harnessDiscovery";
+/**
+ * A short tag for WHAT a harness list says, ignoring WHEN it was found.
+ * Two passes that found the same thing give the same tag.
+ */
+export declare function harnessContentKey(harnesses: readonly RunnerHarness[]): string;
 /**
  * The control plane refused this harness's PROTOCOL or VERSION. FINAL.
  *
@@ -90,6 +123,8 @@ export interface HarnessDeps {
     approvalRenewIntervalMs?: number;
     /** Injected in tests. */
     clientFactory?: (url: string) => ControlPlaneClient;
+    /** Injected in tests; defaults to the real `discoverHarnesses`. */
+    discoverHarnesses?: (options: DiscoverHarnessesOptions) => Promise<RunnerHarness[]>;
 }
 /**
  * THE HARNESS.
@@ -153,6 +188,27 @@ export declare class Harness {
     private modelCatalog;
     /** Epoch ms of the last successful (or attempted) model probe. */
     private modelProbeAt;
+    /**
+     * The harnesses found on this machine, from the last discovery pass.
+     *
+     * Cached for the same reason the model catalogue is: a pass starts several
+     * CLIs, and the heartbeat must not. NULL on a sandbox runner, which never
+     * runs discovery, and until the first pass has finished.
+     */
+    private harnessReport;
+    /** Epoch ms when the last discovery pass STARTED. Doubles as a cooldown. */
+    private harnessDiscoveryAt;
+    /** Epoch ms of the next retry of timed-out checks, or null when none is due. */
+    private harnessRetryAt;
+    /** Retries scheduled in a row. Back to 0 once nothing is waiting. */
+    private harnessRetryAttempts;
+    private harnessDiscoveryInFlight;
+    /**
+     * The `harnessesDigest` the control plane said it has stored, from its last
+     * heartbeat answer. Null until it says so, and for ever with an older
+     * control plane.
+     */
+    private ackedHarnessesDigest;
     /**
      * Empty gateway for the model probe. The probe builds a FRESH adapter and
      * must not read a live turn's credential; a null config is "no gateway",
@@ -272,6 +328,47 @@ export declare class Harness {
      * an empty-but-meaningful list) when the catalogue is empty.
      */
     private applyModelCatalog;
+    /**
+     * Look for the installed harnesses again and cache the answer.
+     *
+     * NEVER ON A SANDBOX. A cloud sandbox image ships exactly what the control
+     * plane put in it, so there is nothing to discover, and its capability
+     * report must stay what it was before this existed.
+     *
+     * Never rejects. One pass at a time: a second call while a pass is running
+     * returns the running one.
+     */
+    private refreshHarnessDiscovery;
+    /**
+     * After a pass: check again SOON when a check timed out, instead of leaving
+     * "timed out" on screen for a whole interval.
+     *
+     * Short and bounded: 30 s, then 60 s, then 120 s, and after that the normal
+     * five-minute pass takes over. A machine that is slow for good must not be
+     * probed for ever at a short interval. The counter starts again once
+     * nothing is waiting.
+     */
+    private scheduleHarnessRetry;
+    /**
+     * Attach the cached harness report to a capability report.
+     *
+     * `runnable` is decided HERE, against the backends of THIS report, and not
+     * taken from the cache: the backend list is re-probed on every heartbeat
+     * and the harness list only every few minutes, so a cached `runnable` could
+     * contradict `backends`. Pi's models are copied from its backend entry for
+     * the same reason — one source, so the two lists cannot disagree.
+     */
+    private applyHarnessReport;
+    private harnessDiscoveryEnabled;
+    /**
+     * Whether to start a discovery pass on this heartbeat.
+     *
+     * NEVER WHILE A TURN IS RUNNING — the same rule as `modelsNeedRefresh`. A
+     * pass starts up to a dozen CLI processes; a turn in progress should not
+     * compete with them for the machine, and nothing is lost by waiting: the
+     * next idle heartbeat starts the pass.
+     */
+    private harnessesNeedRefresh;
     /**
      * Whether the model catalogue needs a (rare) re-probe.
      *

package/dist/harness.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Harness = exports.UpgradeRequestedError = exports.VersionRefusedError = void 0;
+exports.Harness = exports.UpgradeRequestedError = exports.VersionRefusedError = exports.HARNESS_DISCOVERY_FEATURE = exports.HARNESS_RETRY_DELAYS_MS = exports.HARNESS_DISCOVERY_REFRESH_MS = void 0;
+exports.mergeHarnessReports = mergeHarnessReports;
+exports.harnessContentKey = harnessContentKey;
+const node_crypto_1 = require("node:crypto");
 const node_path_1 = require("node:path");
 const model_gateway_1 = require("./adapters/model-gateway");
 const capabilities_1 = require("./capabilities");
@@ -9,6 +12,7 @@ const control_plane_1 = require("./control-plane");
 const credential_store_1 = require("./credential-store");
 const github_command_guards_1 = require("./github-command-guards");
 const github_workspace_1 = require("./github-workspace");
+const harness_discovery_1 = require("./harness-discovery");
 const health_1 = require("./health");
 const model_probe_1 = require("./model-probe");
 const ports_default_1 = require("./ports-default");
@@ -29,6 +33,67 @@ const LEASE_MIN_EMPTY_POLL_MS = 250;
  * process. Every six hours is a bounded refresh of a slowly changing catalog.
  */
 const MODEL_PROBE_REFRESH_MS = 6 * 60 * 60 * 1000;
+/**
+ * How often the installed harnesses are looked for again.
+ *
+ * Five minutes: short enough that a harness installed or signed in to after
+ * start shows up without a restart or a re-enrol, and long enough that the
+ * heartbeat (30 s) does not start a handful of CLIs every time. Between passes
+ * every heartbeat sends the cached answer.
+ */
+exports.HARNESS_DISCOVERY_REFRESH_MS = 5 * 60 * 1000;
+/**
+ * How long after a pass the checks that TIMED OUT are tried again: three
+ * times, each wait twice the one before. See `scheduleHarnessRetry`.
+ */
+exports.HARNESS_RETRY_DELAYS_MS = [
+    30_000, 60_000, 120_000
+];
+/**
+ * Put the result of a pass together with what was known before.
+ *
+ * KEEP THE LAST GOOD STATE. A check that timed out learnt nothing, so when
+ * the previous pass DID settle that harness (signed in, signed out, version
+ * failed) that answer stays. Only a harness with no settled answer yet is
+ * shown as "check timed out, will be tried again".
+ *
+ * A retry pass returns only the harnesses it probed; the others are kept.
+ */
+function mergeHarnessReports(previous, fresh) {
+    if (!previous)
+        return [...fresh];
+    const before = new Map(previous.map((harness) => [harness.name, harness]));
+    const after = new Map(fresh.map((harness) => [harness.name, harness]));
+    const pick = (name) => {
+        const now = after.get(name);
+        const then = before.get(name);
+        if (!now)
+            return then;
+        return now.transient && then && then.installed && !then.transient
+            ? then
+            : now;
+    };
+    const names = [
+        ...previous.map((harness) => harness.name),
+        ...fresh.map((harness) => harness.name).filter((name) => !before.has(name))
+    ];
+    return names
+        .map(pick)
+        .filter((harness) => harness !== undefined);
+}
+/** Listed in `capabilities.features` when `capabilities.harnesses` is sent. */
+exports.HARNESS_DISCOVERY_FEATURE = 'harnessDiscovery';
+/**
+ * A short tag for WHAT a harness list says, ignoring WHEN it was found.
+ * Two passes that found the same thing give the same tag.
+ */
+function harnessContentKey(harnesses) {
+    const content = harnesses.map(({ detectedAt: _detectedAt, ...rest }) => rest);
+    return (0, node_crypto_1.createHash)('sha256')
+        .update(JSON.stringify(content))
+        .digest('hex')
+        .slice(0, 32);
+}
 /**
  * The control plane refused this harness's PROTOCOL or VERSION. FINAL.
  *
@@ -134,6 +199,27 @@ class Harness {
     modelCatalog = null;
     /** Epoch ms of the last successful (or attempted) model probe. */
     modelProbeAt = 0;
+    /**
+     * The harnesses found on this machine, from the last discovery pass.
+     *
+     * Cached for the same reason the model catalogue is: a pass starts several
+     * CLIs, and the heartbeat must not. NULL on a sandbox runner, which never
+     * runs discovery, and until the first pass has finished.
+     */
+    harnessReport = null;
+    /** Epoch ms when the last discovery pass STARTED. Doubles as a cooldown. */
+    harnessDiscoveryAt = 0;
+    /** Epoch ms of the next retry of timed-out checks, or null when none is due. */
+    harnessRetryAt = null;
+    /** Retries scheduled in a row. Back to 0 once nothing is waiting. */
+    harnessRetryAttempts = 0;
+    harnessDiscoveryInFlight = null;
+    /**
+     * The `harnessesDigest` the control plane said it has stored, from its last
+     * heartbeat answer. Null until it says so, and for ever with an older
+     * control plane.
+     */
+    ackedHarnessesDigest = null;
     /**
      * Empty gateway for the model probe. The probe builds a FRESH adapter and
      * must not read a live turn's credential; a null config is "no gateway",
@@ -298,6 +384,21 @@ class Harness {
          */
         await this.refreshModelCatalog(true);
         this.applyModelCatalog(this.capabilities);
+        /*
+         * STARTED, NEVER AWAITED. Registration must not wait for a third-party
+         * CLI, and a runner that is slow to register looks like a runner that did
+         * not come back. The report is attached to the first heartbeat after the
+         * pass has finished.
+         *
+         * STARTED HERE, AFTER THE MODEL PROBE, and not beside it. The first
+         * release candidate started both at once: the Pi discovery process and
+         * five harness CLIs all cold-starting together, on a machine that was
+         * also starting this very process through npx. Two harnesses lost their
+         * version check to that and were shown as broken for five minutes.
+         */
+        void this.refreshHarnessDiscovery();
+        // Attaches the report only if the pass has already finished.
+        this.applyHarnessReport(this.capabilities);
         log('Harness starting', {
             harnessVersion: (0, version_1.getHarnessVersion)(),
             healthPort: this.options.healthPort,
@@ -517,6 +618,10 @@ class Harness {
             if (response.heartbeatIntervalMs) {
                 this.heartbeatIntervalMs = response.heartbeatIntervalMs;
             }
+            this.ackedHarnessesDigest =
+                typeof response.harnessesDigest === 'string'
+                    ? response.harnessesDigest
+                    : null;
             this.observeHarnessPin(response.harnessVersion);
             this.observeSandboxToolsPin(response.sandboxToolsVersion);
             this.applyCommandsSafely(response.sessionCommands ?? []);
@@ -723,6 +828,190 @@ class Harness {
             }
         }
     }
+    /**
+     * Look for the installed harnesses again and cache the answer.
+     *
+     * NEVER ON A SANDBOX. A cloud sandbox image ships exactly what the control
+     * plane put in it, so there is nothing to discover, and its capability
+     * report must stay what it was before this existed.
+     *
+     * Never rejects. One pass at a time: a second call while a pass is running
+     * returns the running one.
+     */
+    refreshHarnessDiscovery() {
+        if (!this.harnessDiscoveryEnabled()) {
+            return Promise.resolve();
+        }
+        if (this.harnessDiscoveryInFlight) {
+            return this.harnessDiscoveryInFlight;
+        }
+        const now = Date.now();
+        /*
+         * A RETRY PASS probes only the harnesses whose last check timed out. A
+         * full pass, when one is due anyway, covers them too.
+         */
+        const fullPassDue = !this.harnessReport ||
+            now - this.harnessDiscoveryAt >= exports.HARNESS_DISCOVERY_REFRESH_MS;
+        const retryNames = (this.harnessReport ?? [])
+            .filter((harness) => harness.transient)
+            .map((harness) => harness.name);
+        const only = !fullPassDue && this.harnessRetryAt !== null && retryNames.length > 0
+            ? retryNames
+            : undefined;
+        if (!only) {
+            this.harnessDiscoveryAt = now;
+        }
+        this.harnessRetryAt = null;
+        const discover = this.deps.discoverHarnesses ?? harness_discovery_1.discoverHarnesses;
+        const pass = (async () => {
+            try {
+                const fresh = await discover({
+                    runnableBackends: (this.capabilities?.backends ?? []).map((backend) => backend.name),
+                    ...(only ? { only } : {})
+                });
+                const report = mergeHarnessReports(this.harnessReport, fresh);
+                // Same content as before: keep the OLD report, with its
+                // `detectedAt`. A pass that found nothing new must not look like a
+                // change, or the whole list would be sent again every five minutes.
+                if (!this.harnessReport ||
+                    harnessContentKey(report) !== harnessContentKey(this.harnessReport)) {
+                    this.harnessReport = report;
+                }
+                this.scheduleHarnessRetry(report);
+                log('Harnesses discovered', {
+                    installed: report
+                        .filter((harness) => harness.installed)
+                        .map((harness) => harness.name),
+                    usable: report
+                        .filter((harness) => harness.usable)
+                        .map((harness) => harness.name),
+                    // Named so a slow machine can be told from a broken harness in
+                    // the log: these are checked again, the others are settled.
+                    retrying: report
+                        .filter((harness) => harness.transient)
+                        .map((harness) => harness.name),
+                    ...(only ? { pass: 'retry' } : {})
+                });
+            }
+            catch {
+                // discoverHarnesses never rejects by construction. If a regression
+                // makes it reject, keep the last good answer instead of failing the
+                // start-up or the heartbeat.
+            }
+            finally {
+                this.harnessDiscoveryInFlight = null;
+            }
+        })();
+        this.harnessDiscoveryInFlight = pass;
+        return pass;
+    }
+    /**
+     * After a pass: check again SOON when a check timed out, instead of leaving
+     * "timed out" on screen for a whole interval.
+     *
+     * Short and bounded: 30 s, then 60 s, then 120 s, and after that the normal
+     * five-minute pass takes over. A machine that is slow for good must not be
+     * probed for ever at a short interval. The counter starts again once
+     * nothing is waiting.
+     */
+    scheduleHarnessRetry(report) {
+        if (!report.some((harness) => harness.transient)) {
+            this.harnessRetryAttempts = 0;
+            this.harnessRetryAt = null;
+            return;
+        }
+        const delay = exports.HARNESS_RETRY_DELAYS_MS[this.harnessRetryAttempts];
+        if (delay === undefined) {
+            this.harnessRetryAt = null;
+            return;
+        }
+        this.harnessRetryAttempts += 1;
+        this.harnessRetryAt = Date.now() + delay;
+    }
+    /**
+     * Attach the cached harness report to a capability report.
+     *
+     * `runnable` is decided HERE, against the backends of THIS report, and not
+     * taken from the cache: the backend list is re-probed on every heartbeat
+     * and the harness list only every few minutes, so a cached `runnable` could
+     * contradict `backends`. Pi's models are copied from its backend entry for
+     * the same reason — one source, so the two lists cannot disagree.
+     */
+    applyHarnessReport(capabilities) {
+        if (!this.harnessReport) {
+            return;
+        }
+        const harnesses = this.harnessReport.map((harness) => {
+            const backend = capabilities.backends.find((candidate) => candidate.name === harness.name);
+            if (!backend) {
+                return { ...harness, runnable: false };
+            }
+            /*
+             * A HARNESS THIS RUNNER RUNS IS NEVER SHOWN WORSE THAN `backends` SAYS.
+             *
+             * The backend probe runs on every heartbeat and is what work is routed
+             * on. The cached discovery pass is older and looks in other places, so
+             * on its own it could say "not installed" or "version check timed out"
+             * for a Pi that is running turns right now. Where the two disagree, the
+             * backend probe is right.
+             */
+            const entry = {
+                ...harness,
+                installed: true,
+                usable: true,
+                runnable: true,
+                version: backend.version ?? harness.version ?? null
+            };
+            delete entry.reason;
+            delete entry.transient;
+            if (!entry.models && backend.models && backend.models.length > 0) {
+                entry.models = backend.models.map(({ id, name }) => ({ id, name }));
+                entry.modelSource = 'backend';
+            }
+            return entry;
+        });
+        const digest = harnessContentKey(harnesses);
+        capabilities.harnessesDigest = digest;
+        /*
+         * THE LIST IS SENT ONLY WHEN THE CONTROL PLANE DOES NOT HAVE IT.
+         *
+         * It is about 20 KB on a machine with every harness, and it changes
+         * rarely. A control plane that understands the digest answers each
+         * heartbeat with the digest it has stored; while that equals ours, the
+         * list is left out and only the digest goes. An older control plane never
+         * answers with a digest, so it is sent the list every time — which it
+         * needs, because it replaces `capabilities` as a whole.
+         */
+        if (this.ackedHarnessesDigest !== digest) {
+            capabilities.harnesses = harnesses;
+        }
+        capabilities.features = [
+            ...(capabilities.features ?? []).filter((feature) => feature !== exports.HARNESS_DISCOVERY_FEATURE),
+            exports.HARNESS_DISCOVERY_FEATURE
+        ];
+    }
+    harnessDiscoveryEnabled() {
+        return (this.options.runtime !== 'sandbox' &&
+            this.options.harnessDiscovery !== false);
+    }
+    /**
+     * Whether to start a discovery pass on this heartbeat.
+     *
+     * NEVER WHILE A TURN IS RUNNING — the same rule as `modelsNeedRefresh`. A
+     * pass starts up to a dozen CLI processes; a turn in progress should not
+     * compete with them for the machine, and nothing is lost by waiting: the
+     * next idle heartbeat starts the pass.
+     */
+    harnessesNeedRefresh() {
+        if (!this.harnessDiscoveryEnabled() || this.active.size > 0) {
+            return false;
+        }
+        const now = Date.now();
+        if (this.harnessRetryAt !== null && now >= this.harnessRetryAt) {
+            return true;
+        }
+        return now - this.harnessDiscoveryAt >= exports.HARNESS_DISCOVERY_REFRESH_MS;
+    }
     /**
      * Whether the model catalogue needs a (rare) re-probe.
      *
@@ -765,7 +1054,13 @@ class Harness {
                 labels: this.options.labels
             });
             this.applyModelCatalog(capabilities);
+            this.applyHarnessReport(capabilities);
             this.capabilities = capabilities;
+            // Not awaited: the answer is attached to a LATER heartbeat. Only the
+            // cached report is ever sent, so a slow CLI cannot delay a heartbeat.
+            if (this.harnessesNeedRefresh()) {
+                void this.refreshHarnessDiscovery();
+            }
             /*
              * THE MODEL CATALOGUE IS NOT RE-PROBED HERE, EVER. Only the CLI probes
              * run on a heartbeat; Pi discovery starts an RPC process, and doing that
@@ -791,6 +1086,10 @@ class Harness {
             if (response.heartbeatIntervalMs) {
                 this.heartbeatIntervalMs = response.heartbeatIntervalMs;
             }
+            this.ackedHarnessesDigest =
+                typeof response.harnessesDigest === 'string'
+                    ? response.harnessesDigest
+                    : null;
             this.observeHarnessPin(response.harnessVersion);
             this.observeSandboxToolsPin(response.sandboxToolsVersion);
             this.applyCommandsSafely(response.sessionCommands ?? []);

package/dist/index.d.ts

@@ -24,6 +24,15 @@ export type { ProbeCapabilitiesOptions, ProbeResult } from './capabilities';
  */
 export { flattenProviderModels, probeBackendModels, probeModelCatalog } from './model-probe';
 export type { ModelCatalog, ModelProbeAdapterFactory, ProviderRecord } from './model-probe';
+/**
+ * Harness discovery — which coding harnesses (Codex, Claude Code, Cursor, Pi,
+ * OpenCode) are installed on this machine, whether each is signed in, and the
+ * models each offers. Reported as `capabilities.harnesses`, apart from
+ * `capabilities.backends`: finding a harness does not mean this runner can
+ * run a turn with it.
+ */
+export { discoverHarnesses, KNOWN_HARNESSES, DISCOVERY_COMMAND_TIMEOUT_MS, DISCOVERY_HARNESS_TIMEOUT_MS } from './harness-discovery';
+export type { DiscoverHarnessesOptions, DiscoveryDeps, DiscoveryExecResult } from './harness-discovery';
 export type { ArtifactInspector, EventSink, HarnessPorts, InspectedArtifact, Notifier, SecretProvider, StoredPart, StoredPartInput, TaskMcpProvider, TaskMcpScope, Telemetry, TokenInjector, TranscriptStore, WorkspaceProvider, WorkspaceRequest } from './ports';
 export { CompositeEventSink, DirectoryWorkspaceProvider, NoArtifactInspector, NoSecretProvider, NoopTelemetry, NullEventSink, ServerNotifier, SessionTokenInjector, StaticTaskMcpProvider } from './ports-default';
 export type { DirectoryWorkspaceOptions } from './ports-default';

package/dist/index.js

@@ -23,8 +23,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MIN_SUPPORTED_PROTOCOL_VERSION = exports.MAX_LEASE_WAIT_SECONDS = exports.MAX_INGEST_PART_BYTES = exports.MAX_INGEST_PARTS = exports.HARNESS_UPGRADE_EXIT_CODE = exports.FINAL_HTTP_STATUSES = exports.EPHEMERAL_PART_TYPES = exports.DEFAULT_MAX_ATTEMPTS = exports.DEFAULT_LEASE_WAIT_SECONDS = exports.DEFAULT_LEASE_TTL_MS = exports.DEFAULT_HEARTBEAT_INTERVAL_MS = exports.DEFAULT_BASE_DELAY_MS = exports.CONTRACT_ERROR_CODES = exports.openTranscriptStore = exports.SqliteTranscriptStore = exports.MemoryTranscriptStore = exports.writeToChildStdin = exports.isBenignStreamError = exports.guardStream = exports.guardChildStreams = exports.toIngestPart = exports.projectParts = exports.SessionRunner = exports.McpAuthProxy = exports.GitHubWorkspaceProvider = exports.StaticTaskMcpProvider = exports.SessionTokenInjector = exports.ServerNotifier = exports.NullEventSink = exports.NoopTelemetry = exports.NoSecretProvider = exports.NoArtifactInspector = exports.DirectoryWorkspaceProvider = exports.CompositeEventSink = exports.probeModelCatalog = exports.probeBackendModels = exports.flattenProviderModels = exports.probeCapabilities = exports.probe = exports.getPiVersion = exports.getHarnessVersion = exports.parseOptions = exports.OptionsError = exports.HealthServer = exports.ProtocolRefusedError = exports.ControlPlaneError = exports.ControlPlaneClient = exports.VersionRefusedError = exports.UpgradeRequestedError = exports.Harness = void 0;
-exports.isProtocolSupported = exports.isPersistablePart = exports.isFinalStatus = exports.isEphemeralPartType = exports.ingestPartByteLength = exports.ROUTES = exports.PROTOCOL_VERSION_HEADER = exports.PROTOCOL_VERSION = exports.PERSISTED_PART_TYPES = exports.MISSED_HEARTBEATS_BEFORE_OFFLINE = void 0;
+exports.HARNESS_UPGRADE_EXIT_CODE = exports.FINAL_HTTP_STATUSES = exports.EPHEMERAL_PART_TYPES = exports.DEFAULT_MAX_ATTEMPTS = exports.DEFAULT_LEASE_WAIT_SECONDS = exports.DEFAULT_LEASE_TTL_MS = exports.DEFAULT_HEARTBEAT_INTERVAL_MS = exports.DEFAULT_BASE_DELAY_MS = exports.CONTRACT_ERROR_CODES = exports.openTranscriptStore = exports.SqliteTranscriptStore = exports.MemoryTranscriptStore = exports.writeToChildStdin = exports.isBenignStreamError = exports.guardStream = exports.guardChildStreams = exports.toIngestPart = exports.projectParts = exports.SessionRunner = exports.McpAuthProxy = exports.GitHubWorkspaceProvider = exports.StaticTaskMcpProvider = exports.SessionTokenInjector = exports.ServerNotifier = exports.NullEventSink = exports.NoopTelemetry = exports.NoSecretProvider = exports.NoArtifactInspector = exports.DirectoryWorkspaceProvider = exports.CompositeEventSink = exports.DISCOVERY_HARNESS_TIMEOUT_MS = exports.DISCOVERY_COMMAND_TIMEOUT_MS = exports.KNOWN_HARNESSES = exports.discoverHarnesses = exports.probeModelCatalog = exports.probeBackendModels = exports.flattenProviderModels = exports.probeCapabilities = exports.probe = exports.getPiVersion = exports.getHarnessVersion = exports.parseOptions = exports.OptionsError = exports.HealthServer = exports.ProtocolRefusedError = exports.ControlPlaneError = exports.ControlPlaneClient = exports.VersionRefusedError = exports.UpgradeRequestedError = exports.Harness = void 0;
+exports.isProtocolSupported = exports.isPersistablePart = exports.isFinalStatus = exports.isEphemeralPartType = exports.ingestPartByteLength = exports.ROUTES = exports.PROTOCOL_VERSION_HEADER = exports.PROTOCOL_VERSION = exports.PERSISTED_PART_TYPES = exports.MISSED_HEARTBEATS_BEFORE_OFFLINE = exports.MIN_SUPPORTED_PROTOCOL_VERSION = exports.MAX_LEASE_WAIT_SECONDS = exports.MAX_INGEST_PART_BYTES = exports.MAX_INGEST_PARTS = void 0;
 /* ---- The process ---------------------------------------------------------- */
 var harness_1 = require("./harness");
 Object.defineProperty(exports, "Harness", { enumerable: true, get: function () { return harness_1.Harness; } });
@@ -55,6 +55,18 @@ var model_probe_1 = require("./model-probe");
 Object.defineProperty(exports, "flattenProviderModels", { enumerable: true, get: function () { return model_probe_1.flattenProviderModels; } });
 Object.defineProperty(exports, "probeBackendModels", { enumerable: true, get: function () { return model_probe_1.probeBackendModels; } });
 Object.defineProperty(exports, "probeModelCatalog", { enumerable: true, get: function () { return model_probe_1.probeModelCatalog; } });
+/**
+ * Harness discovery — which coding harnesses (Codex, Claude Code, Cursor, Pi,
+ * OpenCode) are installed on this machine, whether each is signed in, and the
+ * models each offers. Reported as `capabilities.harnesses`, apart from
+ * `capabilities.backends`: finding a harness does not mean this runner can
+ * run a turn with it.
+ */
+var harness_discovery_1 = require("./harness-discovery");
+Object.defineProperty(exports, "discoverHarnesses", { enumerable: true, get: function () { return harness_discovery_1.discoverHarnesses; } });
+Object.defineProperty(exports, "KNOWN_HARNESSES", { enumerable: true, get: function () { return harness_discovery_1.KNOWN_HARNESSES; } });
+Object.defineProperty(exports, "DISCOVERY_COMMAND_TIMEOUT_MS", { enumerable: true, get: function () { return harness_discovery_1.DISCOVERY_COMMAND_TIMEOUT_MS; } });
+Object.defineProperty(exports, "DISCOVERY_HARNESS_TIMEOUT_MS", { enumerable: true, get: function () { return harness_discovery_1.DISCOVERY_HARNESS_TIMEOUT_MS; } });
 var ports_default_1 = require("./ports-default");
 Object.defineProperty(exports, "CompositeEventSink", { enumerable: true, get: function () { return ports_default_1.CompositeEventSink; } });
 Object.defineProperty(exports, "DirectoryWorkspaceProvider", { enumerable: true, get: function () { return ports_default_1.DirectoryWorkspaceProvider; } });

package/dist/node-floor.d.ts

@@ -0,0 +1,46 @@
+/**
+ * THE NODE.JS FLOOR, CHECKED AT START.
+ *
+ * `package.json` says `engines.node: ">=22.19"`. npm treats that as advice: on
+ * an older Node it prints EBADENGINE and installs anyway, and `npx` then starts
+ * the runner as if nothing was wrong. So the floor was a line in a manifest
+ * that nothing enforced.
+ *
+ * WHERE THE FLOOR COMES FROM. Not from this package's own code — that needs
+ * `node:sqlite` without a flag (Node 22.13). It comes from Pi, the one backend
+ * this runner runs turns with: `@earendil-works/pi-coding-agent` declares
+ * `engines.node >=22.19.0`, and Pi's launcher is `#!/usr/bin/env node`, so Pi
+ * normally runs on the same Node as the runner. Pi 1.1.0 was seen to start on
+ * 22.14 (`--version`, `--list-models`), and nobody has shown that a full turn
+ * works there. An upstream requirement that is not proven false is kept.
+ *
+ * WHAT HAPPENS BELOW THE FLOOR. A desktop or self-hosted runner refuses to
+ * start, with one line that says what to do. `PF_ALLOW_UNSUPPORTED_NODE=1`
+ * starts it anyway, with a one-line warning, for someone who knows their
+ * setup works. A SANDBOX only warns: its Node is whatever the image was built
+ * with, nobody is at a terminal to read the line, and a refusal there would
+ * take a cloud runner out of service for a requirement of a tool the image
+ * already carries.
+ *
+ * PURE: no process state is read here, so every branch can be tested.
+ */
+/** Parse `22.19`, `v22.19.0`, `>=22.19` into numbers. Null when it is none of those. */
+export declare function parseNodeVersion(text: string): number[] | null;
+export declare function isNodeVersionAtLeast(current: string, floor: string): boolean;
+export type NodeFloorVerdict = {
+    action: 'start';
+} | {
+    action: 'warn';
+    message: string;
+} | {
+    action: 'refuse';
+    message: string;
+};
+export declare function checkNodeFloor(input: {
+    /** `process.versions.node`, e.g. `22.14.0`. */
+    current: string;
+    /** `engines.node` of this package, e.g. `>=22.19`. Null when unreadable. */
+    floor: string | null;
+    runtime: string | undefined;
+    env: NodeJS.ProcessEnv;
+}): NodeFloorVerdict;

package/dist/node-floor.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * THE NODE.JS FLOOR, CHECKED AT START.
+ *
+ * `package.json` says `engines.node: ">=22.19"`. npm treats that as advice: on
+ * an older Node it prints EBADENGINE and installs anyway, and `npx` then starts
+ * the runner as if nothing was wrong. So the floor was a line in a manifest
+ * that nothing enforced.
+ *
+ * WHERE THE FLOOR COMES FROM. Not from this package's own code — that needs
+ * `node:sqlite` without a flag (Node 22.13). It comes from Pi, the one backend
+ * this runner runs turns with: `@earendil-works/pi-coding-agent` declares
+ * `engines.node >=22.19.0`, and Pi's launcher is `#!/usr/bin/env node`, so Pi
+ * normally runs on the same Node as the runner. Pi 1.1.0 was seen to start on
+ * 22.14 (`--version`, `--list-models`), and nobody has shown that a full turn
+ * works there. An upstream requirement that is not proven false is kept.
+ *
+ * WHAT HAPPENS BELOW THE FLOOR. A desktop or self-hosted runner refuses to
+ * start, with one line that says what to do. `PF_ALLOW_UNSUPPORTED_NODE=1`
+ * starts it anyway, with a one-line warning, for someone who knows their
+ * setup works. A SANDBOX only warns: its Node is whatever the image was built
+ * with, nobody is at a terminal to read the line, and a refusal there would
+ * take a cloud runner out of service for a requirement of a tool the image
+ * already carries.
+ *
+ * PURE: no process state is read here, so every branch can be tested.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseNodeVersion = parseNodeVersion;
+exports.isNodeVersionAtLeast = isNodeVersionAtLeast;
+exports.checkNodeFloor = checkNodeFloor;
+/** Parse `22.19`, `v22.19.0`, `>=22.19` into numbers. Null when it is none of those. */
+function parseNodeVersion(text) {
+    const match = text.trim().match(/^(?:>=\s*)?v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+    if (!match)
+        return null;
+    return [match[1], match[2] ?? '0', match[3] ?? '0'].map(Number);
+}
+function isNodeVersionAtLeast(current, floor) {
+    const have = parseNodeVersion(current);
+    const need = parseNodeVersion(floor);
+    // A floor or a version that cannot be read is not a reason to refuse.
+    if (!have || !need)
+        return true;
+    for (let index = 0; index < 3; index++) {
+        if (have[index] > need[index])
+            return true;
+        if (have[index] < need[index])
+            return false;
+    }
+    return true;
+}
+function checkNodeFloor(input) {
+    if (!input.floor || isNodeVersionAtLeast(input.current, input.floor)) {
+        return { action: 'start' };
+    }
+    const need = (parseNodeVersion(input.floor) ?? []).slice(0, 2).join('.');
+    const problem = `pf-agent-harness needs Node.js ${need} or newer; this is Node.js ${input.current}.`;
+    const allowed = /^(1|true|yes|on)$/i.test((input.env.PF_ALLOW_UNSUPPORTED_NODE ?? '').trim());
+    if (allowed) {
+        return {
+            action: 'warn',
+            message: `${problem} Starting anyway because PF_ALLOW_UNSUPPORTED_NODE is set.`
+        };
+    }
+    if (input.runtime === 'sandbox') {
+        return {
+            action: 'warn',
+            message: `${problem} Starting anyway in a sandbox.`
+        };
+    }
+    return {
+        action: 'refuse',
+        message: `${problem} Switch to a newer Node.js (for example \`nvm install 22 && nvm use 22\`) and start again.`
+    };
+}