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

package/dist/health.d.ts

@@ -0,0 +1,45 @@
+import { HealthReport } from './types';
+/**
+ * Health check for pf-bootstrap and for the Daytona liveness probe.
+ *
+ * SECURITY: bound to 127.0.0.1 ONLY. Nothing about the harness is reachable
+ * from outside the sandbox, and session users get no useful secret from it —
+ * the report deliberately carries no token.
+ *
+ * STOP MUST ACTUALLY CLOSE, and this is the reason `boundPort` and the socket
+ * tracking below exist. `server.close()` stops ACCEPTING connections but leaves
+ * any keep-alive connection open, and an open connection keeps the Node event
+ * loop alive — the exact class of bug Phase 0 hit, where a refused registration
+ * hung instead of exiting because a listening socket held the loop. `stop()`
+ * therefore destroys every tracked connection as well as closing the listener,
+ * so the process can end deliberately rather than only when a client happens to
+ * hang up.
+ */
+export declare class HealthServer {
+    private readonly port;
+    private readonly report;
+    private server;
+    /**
+     * The port the server actually bound to, RETAINED after `stop()`.
+     *
+     * With `port: 0` the OS chooses a free port, and a test — or an operator —
+     * needs to know which one to prove the socket is closed afterwards. Keeping it
+     * separate from `server` means it survives teardown.
+     */
+    private bound;
+    /** Live connections, tracked so `stop()` can destroy them. */
+    private readonly sockets;
+    constructor(port: number, report: () => HealthReport);
+    /** The actual bound port, or null before `start()`. Survives `stop()`. */
+    get boundPort(): number | null;
+    start(): Promise<void>;
+    /**
+     * A Daytona resume can briefly have two bootstraps: the snapshot entrypoint
+     * waking with the VM and the control plane's fresh-token push. The stale
+     * process may bind 7777 before its registration is refused. Retrying this
+     * one loopback bind lets the useful process take over as soon as that stale
+     * process exits, without weakening enrolment or running two ready harnesses.
+     */
+    private listenOnce;
+    stop(): Promise<void>;
+}

package/dist/health.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealthServer = void 0;
+const node_http_1 = require("node:http");
+const BIND_RETRY_INTERVAL_MS = 100;
+const BIND_RETRY_TIMEOUT_MS = 10_000;
+/**
+ * Health check for pf-bootstrap and for the Daytona liveness probe.
+ *
+ * SECURITY: bound to 127.0.0.1 ONLY. Nothing about the harness is reachable
+ * from outside the sandbox, and session users get no useful secret from it —
+ * the report deliberately carries no token.
+ *
+ * STOP MUST ACTUALLY CLOSE, and this is the reason `boundPort` and the socket
+ * tracking below exist. `server.close()` stops ACCEPTING connections but leaves
+ * any keep-alive connection open, and an open connection keeps the Node event
+ * loop alive — the exact class of bug Phase 0 hit, where a refused registration
+ * hung instead of exiting because a listening socket held the loop. `stop()`
+ * therefore destroys every tracked connection as well as closing the listener,
+ * so the process can end deliberately rather than only when a client happens to
+ * hang up.
+ */
+class HealthServer {
+    port;
+    report;
+    server = null;
+    /**
+     * The port the server actually bound to, RETAINED after `stop()`.
+     *
+     * With `port: 0` the OS chooses a free port, and a test — or an operator —
+     * needs to know which one to prove the socket is closed afterwards. Keeping it
+     * separate from `server` means it survives teardown.
+     */
+    bound = null;
+    /** Live connections, tracked so `stop()` can destroy them. */
+    sockets = new Set();
+    constructor(port, report) {
+        this.port = port;
+        this.report = report;
+    }
+    /** The actual bound port, or null before `start()`. Survives `stop()`. */
+    get boundPort() {
+        return this.bound;
+    }
+    async start() {
+        const deadline = Date.now() + BIND_RETRY_TIMEOUT_MS;
+        for (;;) {
+            try {
+                await this.listenOnce();
+                return;
+            }
+            catch (error) {
+                if (error?.code !== 'EADDRINUSE' ||
+                    Date.now() >= deadline) {
+                    throw error;
+                }
+                await new Promise((resolve) => setTimeout(resolve, BIND_RETRY_INTERVAL_MS));
+            }
+        }
+    }
+    /**
+     * A Daytona resume can briefly have two bootstraps: the snapshot entrypoint
+     * waking with the VM and the control plane's fresh-token push. The stale
+     * process may bind 7777 before its registration is refused. Retrying this
+     * one loopback bind lets the useful process take over as soon as that stale
+     * process exits, without weakening enrolment or running two ready harnesses.
+     */
+    async listenOnce() {
+        return new Promise((resolve, reject) => {
+            const server = (0, node_http_1.createServer)((req, res) => {
+                if (req.url !== '/health' && req.url !== '/healthz') {
+                    res.writeHead(404, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Not found' }));
+                    return;
+                }
+                const body = this.report();
+                // 'starting' is not yet healthy, so a probe waits rather than
+                // declaring the sandbox ready too early.
+                const code = body.status === 'ready' ? 200 : 503;
+                res.writeHead(code, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(body));
+            });
+            // Track every connection so teardown can force it closed. A default
+            // keep-alive client would otherwise keep the listener's underlying handle
+            // referenced past `close()`.
+            server.on('connection', (socket) => {
+                this.sockets.add(socket);
+                socket.on('close', () => this.sockets.delete(socket));
+            });
+            server.on('error', reject);
+            server.listen(this.port, '127.0.0.1', () => {
+                this.server = server;
+                const address = server.address();
+                this.bound = address ? address.port : this.port;
+                resolve();
+            });
+        });
+    }
+    async stop() {
+        const server = this.server;
+        if (!server) {
+            return;
+        }
+        this.server = null;
+        // Destroy in-flight connections FIRST, so `close()`'s callback is not left
+        // waiting on a keep-alive socket that never hangs up — which is precisely
+        // how a "stopped" harness stayed reachable and kept the event loop alive.
+        for (const socket of this.sockets) {
+            socket.destroy();
+        }
+        this.sockets.clear();
+        server.closeAllConnections?.();
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+}
+exports.HealthServer = HealthServer;

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @peakflo/agent-harness — the headless Peakflo coding-agent runtime.
+ *
+ * ONE CODEBASE, THREE HOSTING MODES: a Daytona cloud sandbox, a customer's own
+ * VM, and the 20x desktop. Nothing below asks which one it is running in. Where
+ * a host genuinely differs it supplies a PORT (see ./ports), and every port
+ * describes a CAPABILITY rather than an identity — the moment the runtime can
+ * ask "am I the desktop?", the three modes stop being the same program.
+ */
+export { Harness, UpgradeRequestedError, VersionRefusedError } from './harness';
+export type { HarnessDeps, HarnessUpgradeRequest } from './harness';
+export { ControlPlaneClient, ControlPlaneError, ProtocolRefusedError } from './control-plane';
+export type { ControlPlaneClientOptions, HeartbeatInput, RegisterInput } from './control-plane';
+export { HealthServer } from './health';
+export { OptionsError, parseOptions } from './options';
+export { getHarnessVersion, getPiVersion } from './version';
+export { probe, probeCapabilities } from './capabilities';
+export type { ProbeCapabilitiesOptions, ProbeResult } from './capabilities';
+/**
+ * Model catalogue probing — the harness half of the dynamic model picker.
+ * `flattenProviderModels` mirrors 20x's AgentForm flattening (array OR object
+ * map of `provider.models`); `probeModelCatalog` reads every installed
+ * backend's list into a per-backend + flat catalogue.
+ */
+export { flattenProviderModels, probeBackendModels, probeModelCatalog } from './model-probe';
+export type { ModelCatalog, ModelProbeAdapterFactory, ProviderRecord } from './model-probe';
+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';
+export { GitHubWorkspaceProvider } from './github-workspace';
+export type { GitHubWorkspaceOptions } from './github-workspace';
+export { McpAuthProxy } from './runtime/mcp-auth-proxy';
+export type { McpAuthProxyOptions } from './runtime/mcp-auth-proxy';
+export { SessionRunner } from './runtime/session-runner';
+export type { RunTurnResult, SessionRunnerDeps } from './runtime/session-runner';
+export { projectParts, toIngestPart } from './runtime/projection';
+export type { ProjectableMessagePart } from './runtime/projection';
+export { guardChildStreams, guardStream, isBenignStreamError, writeToChildStdin } from './runtime/child-stream-guards';
+export { MemoryTranscriptStore, SqliteTranscriptStore, openTranscriptStore } from './store/sqlite-store';
+export type { OpenStoreResult } from './store/sqlite-store';
+/**
+ * Extracted from 20x UNCHANGED — the whole `src/main/adapters/` directory had
+ * zero Electron imports, which is why the measurement put the extraction at two
+ * weeks rather than two months.
+ */
+export * from './adapters';
+/**
+ * The control plane imports these too. The predicates are pure and SHARED on
+ * purpose, so the two sides cannot disagree about what "supported", "final" or
+ * "ephemeral" means. A rule written twice is a rule that drifts.
+ */
+export { CONTRACT_ERROR_CODES, DEFAULT_BASE_DELAY_MS, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_LEASE_TTL_MS, DEFAULT_LEASE_WAIT_SECONDS, DEFAULT_MAX_ATTEMPTS, EPHEMERAL_PART_TYPES, FINAL_HTTP_STATUSES, HARNESS_UPGRADE_EXIT_CODE, MAX_INGEST_PARTS, MAX_INGEST_PART_BYTES, MAX_LEASE_WAIT_SECONDS, MIN_SUPPORTED_PROTOCOL_VERSION, MISSED_HEARTBEATS_BEFORE_OFFLINE, PERSISTED_PART_TYPES, PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER, ROUTES, ingestPartByteLength, isEphemeralPartType, isFinalStatus, isPersistablePart, isProtocolSupported } from './contract';
+export type { BootstrapRequest, BootstrapResponse, ControlPlaneErrorBody, CredentialRotateRequest, CredentialRotateResponse, DeregisterRequest, DeregisterResponse, HarnessOptions, HealthReport, IngestRejection, IngestRejectionReason, IngestRequest, IngestResponse, JsonValue, LeaseRenewRequest, LeaseRenewResponse, LeaseResponse, LeasedAgent, LeasedAttachment, LeasedLimits, LeasedMcpServer, LeasedModel, LeasedSession, LeasedSkill, LeasedTurnInput, LeasedWorkspace, LeasedGitHubCredential, LeasedGitHubRepository, ProtocolEnvelope, RunnerBackend, RunnerCapabilities, RunnerHeartbeatRequest, RunnerHeartbeatResponse, RunnerModel, RunnerRegisterRequest, RunnerRegisterResponse, RunnerRuntime, RunnerStatus, SessionCommand, TranscriptPart, TranscriptPartInput, TurnMetadata } from './types';

package/dist/index.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * @peakflo/agent-harness — the headless Peakflo coding-agent runtime.
+ *
+ * ONE CODEBASE, THREE HOSTING MODES: a Daytona cloud sandbox, a customer's own
+ * VM, and the 20x desktop. Nothing below asks which one it is running in. Where
+ * a host genuinely differs it supplies a PORT (see ./ports), and every port
+ * describes a CAPABILITY rather than an identity — the moment the runtime can
+ * ask "am I the desktop?", the three modes stop being the same program.
+ */
+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 __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;
+/* ---- The process ---------------------------------------------------------- */
+var harness_1 = require("./harness");
+Object.defineProperty(exports, "Harness", { enumerable: true, get: function () { return harness_1.Harness; } });
+Object.defineProperty(exports, "UpgradeRequestedError", { enumerable: true, get: function () { return harness_1.UpgradeRequestedError; } });
+Object.defineProperty(exports, "VersionRefusedError", { enumerable: true, get: function () { return harness_1.VersionRefusedError; } });
+var control_plane_1 = require("./control-plane");
+Object.defineProperty(exports, "ControlPlaneClient", { enumerable: true, get: function () { return control_plane_1.ControlPlaneClient; } });
+Object.defineProperty(exports, "ControlPlaneError", { enumerable: true, get: function () { return control_plane_1.ControlPlaneError; } });
+Object.defineProperty(exports, "ProtocolRefusedError", { enumerable: true, get: function () { return control_plane_1.ProtocolRefusedError; } });
+var health_1 = require("./health");
+Object.defineProperty(exports, "HealthServer", { enumerable: true, get: function () { return health_1.HealthServer; } });
+var options_1 = require("./options");
+Object.defineProperty(exports, "OptionsError", { enumerable: true, get: function () { return options_1.OptionsError; } });
+Object.defineProperty(exports, "parseOptions", { enumerable: true, get: function () { return options_1.parseOptions; } });
+var version_1 = require("./version");
+Object.defineProperty(exports, "getHarnessVersion", { enumerable: true, get: function () { return version_1.getHarnessVersion; } });
+Object.defineProperty(exports, "getPiVersion", { enumerable: true, get: function () { return version_1.getPiVersion; } });
+var capabilities_1 = require("./capabilities");
+Object.defineProperty(exports, "probe", { enumerable: true, get: function () { return capabilities_1.probe; } });
+Object.defineProperty(exports, "probeCapabilities", { enumerable: true, get: function () { return capabilities_1.probeCapabilities; } });
+/**
+ * Model catalogue probing — the harness half of the dynamic model picker.
+ * `flattenProviderModels` mirrors 20x's AgentForm flattening (array OR object
+ * map of `provider.models`); `probeModelCatalog` reads every installed
+ * backend's list into a per-backend + flat catalogue.
+ */
+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; } });
+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; } });
+Object.defineProperty(exports, "NoArtifactInspector", { enumerable: true, get: function () { return ports_default_1.NoArtifactInspector; } });
+Object.defineProperty(exports, "NoSecretProvider", { enumerable: true, get: function () { return ports_default_1.NoSecretProvider; } });
+Object.defineProperty(exports, "NoopTelemetry", { enumerable: true, get: function () { return ports_default_1.NoopTelemetry; } });
+Object.defineProperty(exports, "NullEventSink", { enumerable: true, get: function () { return ports_default_1.NullEventSink; } });
+Object.defineProperty(exports, "ServerNotifier", { enumerable: true, get: function () { return ports_default_1.ServerNotifier; } });
+Object.defineProperty(exports, "SessionTokenInjector", { enumerable: true, get: function () { return ports_default_1.SessionTokenInjector; } });
+Object.defineProperty(exports, "StaticTaskMcpProvider", { enumerable: true, get: function () { return ports_default_1.StaticTaskMcpProvider; } });
+var github_workspace_1 = require("./github-workspace");
+Object.defineProperty(exports, "GitHubWorkspaceProvider", { enumerable: true, get: function () { return github_workspace_1.GitHubWorkspaceProvider; } });
+/* ---- The runtime ---------------------------------------------------------- */
+var mcp_auth_proxy_1 = require("./runtime/mcp-auth-proxy");
+Object.defineProperty(exports, "McpAuthProxy", { enumerable: true, get: function () { return mcp_auth_proxy_1.McpAuthProxy; } });
+var session_runner_1 = require("./runtime/session-runner");
+Object.defineProperty(exports, "SessionRunner", { enumerable: true, get: function () { return session_runner_1.SessionRunner; } });
+var projection_1 = require("./runtime/projection");
+Object.defineProperty(exports, "projectParts", { enumerable: true, get: function () { return projection_1.projectParts; } });
+Object.defineProperty(exports, "toIngestPart", { enumerable: true, get: function () { return projection_1.toIngestPart; } });
+var child_stream_guards_1 = require("./runtime/child-stream-guards");
+Object.defineProperty(exports, "guardChildStreams", { enumerable: true, get: function () { return child_stream_guards_1.guardChildStreams; } });
+Object.defineProperty(exports, "guardStream", { enumerable: true, get: function () { return child_stream_guards_1.guardStream; } });
+Object.defineProperty(exports, "isBenignStreamError", { enumerable: true, get: function () { return child_stream_guards_1.isBenignStreamError; } });
+Object.defineProperty(exports, "writeToChildStdin", { enumerable: true, get: function () { return child_stream_guards_1.writeToChildStdin; } });
+var sqlite_store_1 = require("./store/sqlite-store");
+Object.defineProperty(exports, "MemoryTranscriptStore", { enumerable: true, get: function () { return sqlite_store_1.MemoryTranscriptStore; } });
+Object.defineProperty(exports, "SqliteTranscriptStore", { enumerable: true, get: function () { return sqlite_store_1.SqliteTranscriptStore; } });
+Object.defineProperty(exports, "openTranscriptStore", { enumerable: true, get: function () { return sqlite_store_1.openTranscriptStore; } });
+/* ---- The backends --------------------------------------------------------- */
+/**
+ * Extracted from 20x UNCHANGED — the whole `src/main/adapters/` directory had
+ * zero Electron imports, which is why the measurement put the extraction at two
+ * weeks rather than two months.
+ */
+__exportStar(require("./adapters"), exports);
+/* ---- The wire contract ---------------------------------------------------- */
+/**
+ * The control plane imports these too. The predicates are pure and SHARED on
+ * purpose, so the two sides cannot disagree about what "supported", "final" or
+ * "ephemeral" means. A rule written twice is a rule that drifts.
+ */
+var contract_1 = require("./contract");
+Object.defineProperty(exports, "CONTRACT_ERROR_CODES", { enumerable: true, get: function () { return contract_1.CONTRACT_ERROR_CODES; } });
+Object.defineProperty(exports, "DEFAULT_BASE_DELAY_MS", { enumerable: true, get: function () { return contract_1.DEFAULT_BASE_DELAY_MS; } });
+Object.defineProperty(exports, "DEFAULT_HEARTBEAT_INTERVAL_MS", { enumerable: true, get: function () { return contract_1.DEFAULT_HEARTBEAT_INTERVAL_MS; } });
+Object.defineProperty(exports, "DEFAULT_LEASE_TTL_MS", { enumerable: true, get: function () { return contract_1.DEFAULT_LEASE_TTL_MS; } });
+Object.defineProperty(exports, "DEFAULT_LEASE_WAIT_SECONDS", { enumerable: true, get: function () { return contract_1.DEFAULT_LEASE_WAIT_SECONDS; } });
+Object.defineProperty(exports, "DEFAULT_MAX_ATTEMPTS", { enumerable: true, get: function () { return contract_1.DEFAULT_MAX_ATTEMPTS; } });
+Object.defineProperty(exports, "EPHEMERAL_PART_TYPES", { enumerable: true, get: function () { return contract_1.EPHEMERAL_PART_TYPES; } });
+Object.defineProperty(exports, "FINAL_HTTP_STATUSES", { enumerable: true, get: function () { return contract_1.FINAL_HTTP_STATUSES; } });
+Object.defineProperty(exports, "HARNESS_UPGRADE_EXIT_CODE", { enumerable: true, get: function () { return contract_1.HARNESS_UPGRADE_EXIT_CODE; } });
+Object.defineProperty(exports, "MAX_INGEST_PARTS", { enumerable: true, get: function () { return contract_1.MAX_INGEST_PARTS; } });
+Object.defineProperty(exports, "MAX_INGEST_PART_BYTES", { enumerable: true, get: function () { return contract_1.MAX_INGEST_PART_BYTES; } });
+Object.defineProperty(exports, "MAX_LEASE_WAIT_SECONDS", { enumerable: true, get: function () { return contract_1.MAX_LEASE_WAIT_SECONDS; } });
+Object.defineProperty(exports, "MIN_SUPPORTED_PROTOCOL_VERSION", { enumerable: true, get: function () { return contract_1.MIN_SUPPORTED_PROTOCOL_VERSION; } });
+Object.defineProperty(exports, "MISSED_HEARTBEATS_BEFORE_OFFLINE", { enumerable: true, get: function () { return contract_1.MISSED_HEARTBEATS_BEFORE_OFFLINE; } });
+Object.defineProperty(exports, "PERSISTED_PART_TYPES", { enumerable: true, get: function () { return contract_1.PERSISTED_PART_TYPES; } });
+Object.defineProperty(exports, "PROTOCOL_VERSION", { enumerable: true, get: function () { return contract_1.PROTOCOL_VERSION; } });
+Object.defineProperty(exports, "PROTOCOL_VERSION_HEADER", { enumerable: true, get: function () { return contract_1.PROTOCOL_VERSION_HEADER; } });
+Object.defineProperty(exports, "ROUTES", { enumerable: true, get: function () { return contract_1.ROUTES; } });
+Object.defineProperty(exports, "ingestPartByteLength", { enumerable: true, get: function () { return contract_1.ingestPartByteLength; } });
+Object.defineProperty(exports, "isEphemeralPartType", { enumerable: true, get: function () { return contract_1.isEphemeralPartType; } });
+Object.defineProperty(exports, "isFinalStatus", { enumerable: true, get: function () { return contract_1.isFinalStatus; } });
+Object.defineProperty(exports, "isPersistablePart", { enumerable: true, get: function () { return contract_1.isPersistablePart; } });
+Object.defineProperty(exports, "isProtocolSupported", { enumerable: true, get: function () { return contract_1.isProtocolSupported; } });

package/dist/model-probe.d.ts

@@ -0,0 +1,96 @@
+/**
+ * THE MODEL PROBE — how a runner reports the models its backends can drive.
+ *
+ * This is the harness half of the same feature 20x already has. 20x's
+ * `AgentForm` asks its AgentManager to `getProviders()` and flattens the
+ * answer; the runner carries the answer in `RunnerCapabilities` so the
+ * workflow-builder control plane can render exactly what THIS machine offers —
+ * and nothing else, because model source follows the harness, not a union
+ * across runners.
+ *
+ * THREE RULES, TAKEN FROM THE TASK THAT BUILT THE 20x SIDE:
+ *
+ * 1. `provider.models` MAY BE AN ARRAY OR AN OBJECT MAP. The object form is how
+ *    custom providers (routerAI and similar) arrive, and `Array.isArray` alone
+ *    silently yields nothing for them. Both branches are handled, using
+ *    `Object.entries` exactly as 20x does so the map key serves as the model id
+ *    when the value carries none.
+ *
+ * 2. Model ids are namespaced by provider (`${provider.id}/${model.id}`), the
+ *    same prefix 20x applies. The gateway's own catalogue comes back with the
+ *    `peakflo` prefix, which is how a runner's list and the control-plane
+ *    gateway list agree on what "the same model" is.
+ *
+ * 3. DEGRADE HONESTLY, NEVER GUESS. A probe that fails (SDK absent, server
+ *    unreachable, adapter without a provider listing) returns null, which the
+ *    caller reports as "no models". The control plane and the UI already fall
+ *    back to the gateway list and then to free text, so an empty report is safe
+ *    and a wrong one is not.
+ *
+ * PROTECTING THE RUNNER FROM ITS OWN PROBE — the one that matters:
+ *
+ * Pi model discovery uses a short-lived no-session RPC process. This remains a
+ * START-UP/INTERVAL operation, never a per-heartbeat one: the harness caches
+ * the result and re-probes on a long interval or when Pi first appears.
+ */
+import type { CodingAgentAdapter } from './adapters/coding-agent-adapter';
+import type { RunnerBackend, RunnerModel } from './types';
+/**
+ * Build one adapter for probing. `buildAdapter` returns null when the host
+ * cannot wire this backend (unknown name, missing binary, an adapter that
+ * throws on the build) — a null is "no models", never an error.
+ */
+export type ModelProbeAdapterFactory = (backend: string) => CodingAgentAdapter | null;
+export interface ProviderRecord {
+    id: string;
+    name?: string;
+    models?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * FLATTEN PROVIDERS TO A MODEL LIST, THE WAY 20x DOES.
+ *
+ * Handles BOTH shapes of `provider.models`:
+ *   - an ARRAY of `{ id, name }` — the common case;
+ *   - an OBJECT MAP of `modelId -> { name }` — how custom providers arrive
+ *     (routerAI etc.), where the map's KEY is the authoritative id.
+ *
+ * Model ids are namespaced `provider.id/model[id]`; names read
+ * `provider.name - model.name|model id`.
+ */
+export declare function flattenProviderModels(providers: ProviderRecord[] | null | undefined): RunnerModel[];
+/**
+ * What a probe learned about one runner, at one point in time.
+ *
+ * `byBackend` is the per-`backend` model list; `flat` is the deduplicated
+ * union the control-plane picker reads directly. `attempted` records every
+ * backend we TRIED to probe — used by the harness to know when a new backend
+ * (installed after start) needs a re-probe without re-probing ones that have
+ * nothing to give.
+ */
+export interface ModelCatalog {
+    byBackend: Record<string, RunnerModel[]>;
+    flat: RunnerModel[];
+    attempted: string[];
+}
+/**
+ * Probe ONE backend for the models it can drive. Returns [] (never null) so a
+ * failed probe is indistinguishable to the caller from "this backend lists
+ * nothing".
+ *
+ * The probe builds a FRESH adapter via the factory (never reuses a turn's),
+ * asks for its provider listing and flattens it. Pi's `getProviders` closes its
+ * own no-session discovery process before returning.
+ */
+export declare function probeBackendModels(backendName: string, buildAdapter: ModelProbeAdapterFactory): Promise<RunnerModel[]>;
+/**
+ * Probe every installed backend and build the catalogue.
+ *
+ * NEVER REJECTS. Every individual backend failure degrades to an empty list
+ * for that backend; an entirely failing host yields a catalogue with no
+ * models, which is the honest answer.
+ *
+ * Sequential by construction. The published harness advertises only Pi, so
+ * the real bound is one 30-second probe and no shared-server race exists.
+ */
+export declare function probeModelCatalog(backends: RunnerBackend[], buildAdapter: ModelProbeAdapterFactory): Promise<ModelCatalog>;

package/dist/model-probe.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * THE MODEL PROBE — how a runner reports the models its backends can drive.
+ *
+ * This is the harness half of the same feature 20x already has. 20x's
+ * `AgentForm` asks its AgentManager to `getProviders()` and flattens the
+ * answer; the runner carries the answer in `RunnerCapabilities` so the
+ * workflow-builder control plane can render exactly what THIS machine offers —
+ * and nothing else, because model source follows the harness, not a union
+ * across runners.
+ *
+ * THREE RULES, TAKEN FROM THE TASK THAT BUILT THE 20x SIDE:
+ *
+ * 1. `provider.models` MAY BE AN ARRAY OR AN OBJECT MAP. The object form is how
+ *    custom providers (routerAI and similar) arrive, and `Array.isArray` alone
+ *    silently yields nothing for them. Both branches are handled, using
+ *    `Object.entries` exactly as 20x does so the map key serves as the model id
+ *    when the value carries none.
+ *
+ * 2. Model ids are namespaced by provider (`${provider.id}/${model.id}`), the
+ *    same prefix 20x applies. The gateway's own catalogue comes back with the
+ *    `peakflo` prefix, which is how a runner's list and the control-plane
+ *    gateway list agree on what "the same model" is.
+ *
+ * 3. DEGRADE HONESTLY, NEVER GUESS. A probe that fails (SDK absent, server
+ *    unreachable, adapter without a provider listing) returns null, which the
+ *    caller reports as "no models". The control plane and the UI already fall
+ *    back to the gateway list and then to free text, so an empty report is safe
+ *    and a wrong one is not.
+ *
+ * PROTECTING THE RUNNER FROM ITS OWN PROBE — the one that matters:
+ *
+ * Pi model discovery uses a short-lived no-session RPC process. This remains a
+ * START-UP/INTERVAL operation, never a per-heartbeat one: the harness caches
+ * the result and re-probes on a long interval or when Pi first appears.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flattenProviderModels = flattenProviderModels;
+exports.probeBackendModels = probeBackendModels;
+exports.probeModelCatalog = probeModelCatalog;
+const model_gateway_1 = require("./adapters/model-gateway");
+/**
+ * FLATTEN PROVIDERS TO A MODEL LIST, THE WAY 20x DOES.
+ *
+ * Handles BOTH shapes of `provider.models`:
+ *   - an ARRAY of `{ id, name }` — the common case;
+ *   - an OBJECT MAP of `modelId -> { name }` — how custom providers arrive
+ *     (routerAI etc.), where the map's KEY is the authoritative id.
+ *
+ * Model ids are namespaced `provider.id/model[id]`; names read
+ * `provider.name - model.name|model id`.
+ */
+function flattenProviderModels(providers) {
+    if (!Array.isArray(providers) || providers.length === 0) {
+        return [];
+    }
+    const out = [];
+    for (const provider of providers) {
+        if (!provider || typeof provider.id !== 'string')
+            continue;
+        /*
+         * NEVER REPORT THE GATEWAY PROVIDER ID AS THIS RUNNER'S OWN.
+         *
+         * That id belongs to the control plane. The harness REBUILDS it for every
+         * turn from the lease's gatewayUrl and per-turn key, so whatever a machine
+         * happens to have under the same name locally is overwritten before any
+         * model is called.
+         *
+         * Reporting it anyway offered models that could not run. This machine's
+         * local `peakflo` provider points at a different deployment and listed
+         * `vertex_ai/gemini-3-flash-preview`; the gateway the lease actually uses
+         * serves three models and not that one, so selecting it failed the turn
+         * with `Invalid model name passed in model=vertex_ai/gemini-3-flash-preview`.
+         * Two different providers were colliding under one prefix and the picker
+         * gave the user no way to tell them apart.
+         *
+         * The gateway's real catalogue reaches the UI on its own path, so dropping
+         * it here loses nothing and removes ids that cannot be called.
+         */
+        if (provider.id === model_gateway_1.ENTERPRISE_AI_GATEWAY_PROVIDER_ID)
+            continue;
+        const raw = provider.models;
+        if (!raw)
+            continue;
+        if (Array.isArray(raw)) {
+            for (const m of raw) {
+                const entry = m;
+                const id = typeof entry?.id === 'string' && entry.id.length > 0
+                    ? entry.id
+                    : null;
+                if (!id)
+                    continue;
+                out.push({
+                    id: `${provider.id}/${id}`,
+                    name: `${provider.name ?? provider.id} - ${typeof entry?.name === 'string' ? entry.name : id}`
+                });
+            }
+        }
+        else if (typeof raw === 'object') {
+            // Object form — model ids are the map KEYS; the value may carry a nicer
+            // name and (occasionally) its own id. 20x's Object.entries handling.
+            for (const [key, value] of Object.entries(raw)) {
+                const entry = value;
+                const modelId = typeof entry?.id === 'string' && entry.id ? entry.id : key;
+                if (!modelId)
+                    continue;
+                out.push({
+                    id: `${provider.id}/${modelId}`,
+                    name: `${provider.name ?? provider.id} - ${typeof entry?.name === 'string' ? entry.name : modelId}`
+                });
+            }
+        }
+    }
+    return out;
+}
+/** How long a single provider listing may take (includes a server cold start). */
+const MODEL_PROBE_TIMEOUT_MS = 30_000;
+async function withTimeout(promise, ms) {
+    let timer = null;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error('model probe timed out')), ms);
+            })
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Probe ONE backend for the models it can drive. Returns [] (never null) so a
+ * failed probe is indistinguishable to the caller from "this backend lists
+ * nothing".
+ *
+ * The probe builds a FRESH adapter via the factory (never reuses a turn's),
+ * asks for its provider listing and flattens it. Pi's `getProviders` closes its
+ * own no-session discovery process before returning.
+ */
+async function probeBackendModels(backendName, buildAdapter) {
+    let adapter = null;
+    try {
+        adapter = buildAdapter(backendName);
+        if (!adapter || typeof adapter.getProviders !== 'function') {
+            return [];
+        }
+        const result = await withTimeout(adapter.getProviders(), MODEL_PROBE_TIMEOUT_MS);
+        if (!result?.providers) {
+            return [];
+        }
+        return flattenProviderModels(result.providers);
+    }
+    catch {
+        // An adapter that throws is "this backend lists nothing here". NEVER a
+        // guess at what it might list, and never a reason to fail registration.
+        return [];
+    }
+}
+/**
+ * Probe every installed backend and build the catalogue.
+ *
+ * NEVER REJECTS. Every individual backend failure degrades to an empty list
+ * for that backend; an entirely failing host yields a catalogue with no
+ * models, which is the honest answer.
+ *
+ * Sequential by construction. The published harness advertises only Pi, so
+ * the real bound is one 30-second probe and no shared-server race exists.
+ */
+async function probeModelCatalog(backends, buildAdapter) {
+    const byBackend = {};
+    const attempted = [];
+    const flatById = new Map();
+    for (const backend of backends) {
+        if (!backend?.name)
+            continue;
+        attempted.push(backend.name);
+        const models = await probeBackendModels(backend.name, buildAdapter);
+        if (models.length === 0) {
+            continue;
+        }
+        byBackend[backend.name] = models;
+        for (const model of models) {
+            if (!flatById.has(model.id)) {
+                flatById.set(model.id, model);
+            }
+        }
+    }
+    return {
+        byBackend,
+        flat: [...flatById.values()],
+        attempted
+    };
+}

package/dist/options.d.ts

@@ -0,0 +1,15 @@
+import { HarnessOptions } from './types';
+export declare class OptionsError extends Error {
+}
+/**
+ * Flags win over environment variables, so a local developer can override a
+ * value that pf-bootstrap injected.
+ *
+ * NOTE ON THE ENROLMENT TOKEN: it is accepted on the command line for local
+ * development and self-hosted installs, which is what the design calls for.
+ * In a managed sandbox pf-bootstrap passes it through PF_ENROLMENT_TOKEN
+ * instead, so it never appears in the process arguments — /proc/<pid>/cmdline
+ * is world-readable, while /proc/<pid>/environ is readable only by the
+ * process owner.
+ */
+export declare function parseOptions(argv: string[], env: NodeJS.ProcessEnv): HarnessOptions;