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

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.`
+    };
+}

package/dist/runtime/session-runner.d.ts

@@ -174,6 +174,32 @@ export declare function qualifiedModelId(model: {
  * claiming otherwise would send the reader to the wrong place.
  */
 export declare function describeProviderError(error: string, qualifiedModel: string | undefined): string;
+/**
+ * A VENDOR HARNESS GETS NO GATEWAY AND NO GATEWAY KEY.
+ *
+ * Codex, Claude Code and Cursor run on the vendor sign-in that is already on
+ * the machine, as they do in 20x. The Peakflo model gateway has no part in
+ * such a turn, so everything about it is taken off the lease HERE, once,
+ * before anything reads it: no catalogue fetch with the key, no `peakflo`
+ * provider built, no gateway URL in the adapter's environment, and no key
+ * expiry watched.
+ *
+ * Done in the runner and not only on the control plane, because a control
+ * plane older than this change still sends both for every backend. The key
+ * must not reach a vendor CLI's process whatever the control plane's age.
+ */
+export declare function withoutGatewayForVendorBackend(lease: LeaseResponse): LeaseResponse;
+/**
+ * The model id as THIS backend understands it: `provider/model` for Pi, the
+ * vendor's own bare id for a vendor harness (see `vendorModelId`).
+ */
+export declare function backendModelId(agent: {
+    backend: string;
+    model: {
+        provider?: string | null;
+        model?: string | null;
+    };
+}): string | undefined;
 export declare function modelGatewayRefusal(lease: {
     modelToken?: string | null;
     session: {
@@ -338,7 +364,7 @@ export declare class SessionRunner {
      * control plane at all propagates, since that is the one thing the runner
      * cannot report through the control plane.
      */
-    run(lease: LeaseResponse, signal: AbortSignal): Promise<RunTurnResult>;
+    run(leased: LeaseResponse, signal: AbortSignal): Promise<RunTurnResult>;
     /**
      * Does this polled part merely mirror the prompt the runner itself sent?
      *

package/dist/runtime/session-runner.js

@@ -23,6 +23,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SessionRunner = void 0;
 exports.qualifiedModelId = qualifiedModelId;
 exports.describeProviderError = describeProviderError;
+exports.withoutGatewayForVendorBackend = withoutGatewayForVendorBackend;
+exports.backendModelId = backendModelId;
 exports.modelGatewayRefusal = modelGatewayRefusal;
 exports.permissionFingerprint = permissionFingerprint;
 exports.decodeQuestionAnswers = decodeQuestionAnswers;
@@ -30,6 +32,7 @@ exports.isApprovingOptionId = isApprovingOptionId;
 const node_crypto_1 = require("node:crypto");
 const model_gateway_1 = require("../adapters/model-gateway");
 const contract_1 = require("../contract");
+const vendor_backends_1 = require("../vendor-backends");
 const attachments_1 = require("./attachments");
 const cold_start_steps_1 = require("./cold-start-steps");
 const conversation_1 = require("./conversation");
@@ -156,6 +159,43 @@ function describeProviderError(error, qualifiedModel) {
         `to ${provider}, or choose a ${model_gateway_1.ENTERPRISE_AI_GATEWAY_PROVIDER_ID}/ model, ` +
         `which is credentialed for each turn.`);
 }
+/**
+ * A VENDOR HARNESS GETS NO GATEWAY AND NO GATEWAY KEY.
+ *
+ * Codex, Claude Code and Cursor run on the vendor sign-in that is already on
+ * the machine, as they do in 20x. The Peakflo model gateway has no part in
+ * such a turn, so everything about it is taken off the lease HERE, once,
+ * before anything reads it: no catalogue fetch with the key, no `peakflo`
+ * provider built, no gateway URL in the adapter's environment, and no key
+ * expiry watched.
+ *
+ * Done in the runner and not only on the control plane, because a control
+ * plane older than this change still sends both for every backend. The key
+ * must not reach a vendor CLI's process whatever the control plane's age.
+ */
+function withoutGatewayForVendorBackend(lease) {
+    const { agent } = lease.session;
+    if (!(0, vendor_backends_1.isVendorBackend)(agent.backend))
+        return lease;
+    return {
+        ...lease,
+        modelToken: '',
+        modelTokenExpiresAt: undefined,
+        session: {
+            ...lease.session,
+            agent: { ...agent, model: { ...agent.model, gatewayUrl: '' } }
+        }
+    };
+}
+/**
+ * The model id as THIS backend understands it: `provider/model` for Pi, the
+ * vendor's own bare id for a vendor harness (see `vendorModelId`).
+ */
+function backendModelId(agent) {
+    return (0, vendor_backends_1.isVendorBackend)(agent.backend)
+        ? (0, vendor_backends_1.vendorModelId)(agent.model, agent.backend)
+        : qualifiedModelId(agent.model);
+}
 function modelGatewayRefusal(lease) {
     const gatewayUrl = (lease.session.agent.model.gatewayUrl ?? '').trim();
     if (!gatewayUrl)
@@ -590,7 +630,8 @@ class SessionRunner {
      * control plane at all propagates, since that is the one thing the runner
      * cannot report through the control plane.
      */
-    async run(lease, signal) {
+    async run(leased, signal) {
+        const lease = withoutGatewayForVendorBackend(leased);
         const { session } = lease;
         const logColdStart = (line) => {
             this.logger.log(line);
@@ -1109,6 +1150,28 @@ class SessionRunner {
             // THE PROMPT THIS RUNNER JUST SENT. Drain uses it to recognise the
             // backend's own echo of it — see `drain`.
             sentPromptTexts, () => endFirstOutput(), () => endFirstIngest());
+            /*
+             * THE BACKEND MAY ONLY NOW KNOW ITS OWN SESSION ID.
+             *
+             * Claude Code is given a placeholder by `createSession` and learns the
+             * real session id from the first message of the stream; the adapter
+             * reports it on a part as `realSessionId`, and 20x re-keys the session
+             * when it sees one (`agent-manager.ts`, "REKEYED ... reason=
+             * adapter_provided_real_id"). The checkpoint must be that real id: the
+             * placeholder names no saved session, and resuming it fails with
+             * "session file does not exist" on every later turn.
+             *
+             * Within this turn the adapter answers to both ids, so only what is
+             * SAVED changes. A backend with nothing to say keeps the id it had.
+             */
+            const realBackendSessionId = adapter.checkpointSessionId?.(backendSessionId);
+            if (realBackendSessionId && realBackendSessionId !== backendSessionId) {
+                backendSessionId = realBackendSessionId;
+                this.deps.conversation?.setCheckpoint((0, conversation_1.conversationKey)(session), backendSessionId, session.agent.backend, {
+                    backendOwnerId: ownBackendInstanceId,
+                    permissionDecision: permissionFingerprint(session.agent.permissionMode)
+                });
+            }
             partsProduced = drained.parts;
             if (signal.aborted) {
                 stopReason = 'aborted';
@@ -1157,7 +1220,7 @@ class SessionRunner {
                     {
                         id: `error-${(0, node_crypto_1.randomUUID)()}`,
                         role: 'system',
-                        content: describeProviderError(error ?? String(drained.providerError), qualifiedModelId(session.agent.model)),
+                        content: describeProviderError(error ?? String(drained.providerError), backendModelId(session.agent)),
                         partType: 'error'
                     }
                 ]);
@@ -2463,7 +2526,7 @@ class SessionRunner {
             turnId: session.turnId,
             workspaceDir,
             devServerPolicy: session.agent.devServerPolicy,
-            model: qualifiedModelId(session.agent.model),
+            model: backendModelId(session.agent),
             systemPrompt: session.agent.systemPrompt ?? undefined,
             skills: session.agent.skills.map((skill) => ({
                 name: skill.name,

package/dist/store/conversation-store.js

@@ -27,6 +27,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MemoryConversationStore = exports.SqliteConversationStore = void 0;
 exports.openConversationStore = openConversationStore;
+const sqlite_store_1 = require("./sqlite-store");
 const SCHEMA = `
   CREATE TABLE IF NOT EXISTS model_messages (
     session_id TEXT NOT NULL,
@@ -292,6 +293,7 @@ function openConversationStore(path) {
         };
     }
     try {
+        (0, sqlite_store_1.ensureStoreDirectory)(path);
         const db = new sqlite.DatabaseSync(path);
         return { store: new SqliteConversationStore(db), durable: true };
     }

package/dist/store/sqlite-store.d.ts

@@ -106,6 +106,23 @@ export interface OpenStoreResult {
     /** Why durability was unavailable. Reported so a degraded fleet is visible. */
     reason?: string;
 }
+/**
+ * Make the directory a store file goes in, when it is not there yet.
+ *
+ * sqlite creates the FILE and never the directory: a `--workspace-root` that
+ * does not exist yet made every open fail with "unable to open database
+ * file", and the runner then ran in memory and reported itself degraded —
+ * for a path it was about to create anyway on the first session. Private
+ * mode, because the stores hold transcripts and the model's conversation.
+ *
+ * A directory that ALREADY EXISTS is left exactly as it is, its mode included:
+ * `mkdir` with `recursive` does not touch one, and changing the permissions
+ * of a directory somebody chose is not this function's call.
+ *
+ * Throws when the directory cannot be made; the caller turns that into the
+ * same visible memory fallback as any other open failure.
+ */
+export declare function ensureStoreDirectory(path: string): void;
 /**
  * Open the durable store, or say plainly why it could not be opened.
  *

package/dist/store/sqlite-store.js

@@ -32,7 +32,10 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MemoryTranscriptStore = exports.SqliteTranscriptStore = void 0;
+exports.ensureStoreDirectory = ensureStoreDirectory;
 exports.openTranscriptStore = openTranscriptStore;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 const SCHEMA = `
   CREATE TABLE IF NOT EXISTS transcript_parts (
     session_id TEXT NOT NULL,
@@ -309,6 +312,28 @@ class MemoryTranscriptStore {
     }
 }
 exports.MemoryTranscriptStore = MemoryTranscriptStore;
+/**
+ * Make the directory a store file goes in, when it is not there yet.
+ *
+ * sqlite creates the FILE and never the directory: a `--workspace-root` that
+ * does not exist yet made every open fail with "unable to open database
+ * file", and the runner then ran in memory and reported itself degraded —
+ * for a path it was about to create anyway on the first session. Private
+ * mode, because the stores hold transcripts and the model's conversation.
+ *
+ * A directory that ALREADY EXISTS is left exactly as it is, its mode included:
+ * `mkdir` with `recursive` does not touch one, and changing the permissions
+ * of a directory somebody chose is not this function's call.
+ *
+ * Throws when the directory cannot be made; the caller turns that into the
+ * same visible memory fallback as any other open failure.
+ */
+function ensureStoreDirectory(path) {
+    // sqlite's in-memory and temporary databases have no directory.
+    if (path === ':memory:' || path === '')
+        return;
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true, mode: 0o700 });
+}
 /**
  * Open the durable store, or say plainly why it could not be opened.
  *
@@ -333,6 +358,7 @@ function openTranscriptStore(path) {
         };
     }
     try {
+        ensureStoreDirectory(path);
         const db = new sqlite.DatabaseSync(path);
         return { store: new SqliteTranscriptStore(db), durable: true };
     }

package/dist/types.d.ts

@@ -283,8 +283,22 @@ export interface RunnerHarness {
      * account name or a token.
      */
     reason?: string;
+    /**
+     * The check of this harness DID NOT FINISH (it timed out), so `usable:
+     * false` here is not a statement about the harness. The runner checks again
+     * shortly. Only ever sent with `installed: true, usable: false`. A reader
+     * that does not know this field shows the entry as not usable with its
+     * reason, which says the same thing in words.
+     */
+    transient?: boolean;
     /** This runner can run a turn with it: it is also listed in `backends`. */
     runnable: boolean;
+    /**
+     * Why this runner cannot run a harness that is installed and signed in
+     * (for example the Claude Agent SDK is missing). A fixed sentence. Only
+     * sent with `usable: true, runnable: false`.
+     */
+    notRunnableReason?: string;
     models?: RunnerHarnessModel[];
     modelSource?: RunnerHarnessModelSource;
     /** ISO time of the discovery pass that first found this state. */

package/dist/vendor-backends.d.ts

@@ -0,0 +1,77 @@
+/**
+ * THE VENDOR HARNESSES THIS RUNNER CAN RUN: Codex, Claude Code, Cursor.
+ *
+ * "Vendor" because each one talks to its own vendor with the sign-in that is
+ * already on the machine — exactly as in 20x, where the same adapters run
+ * with no gateway and no key from the app. That is what separates them from
+ * Pi, which is credentialed for every turn from the lease:
+ *
+ *                      Pi                          Codex / Claude Code / Cursor
+ *   model credential   gateway key in the lease    the machine's own sign-in
+ *   model id           `provider/model`            the vendor's own bare id
+ *   where it runs      every runtime               desktop and self-hosted only
+ *
+ * WHICH ADAPTER, AS IN 20x `agent-manager.ts` `getAdapter`:
+ *   codex        -> CodexAppServerAdapter   (`codex app-server --stdio`)
+ *   claude-code  -> ClaudeCodeAdapter       (`@anthropic-ai/claude-agent-sdk`)
+ *   cursor       -> AcpAdapter('cursor')    (`cursor-agent acp`)
+ *
+ * NEVER IN A SANDBOX. A cloud sandbox has no vendor sign-in and must not be
+ * given one: no tenant vendor credential is placed on an untrusted host. It
+ * stays Pi-only.
+ */
+export declare const VENDOR_BACKENDS: readonly ["codex", "claude-code", "cursor"];
+export type VendorBackend = (typeof VENDOR_BACKENDS)[number];
+export declare function isVendorBackend(name: string): name is VendorBackend;
+/**
+ * The model id a vendor adapter is given, or undefined for "the harness's own
+ * default".
+ *
+ * An agent's model is stored as `{ provider, model }`. For a vendor harness the
+ * picker stores the HARNESS NAME as the provider (`codex` / `gpt-6-sol`), so a
+ * model that belongs to this harness is recognised by `provider === backend`
+ * and its bare id is what the adapter gets.
+ *
+ * ANY OTHER PROVIDER IS NOT PASSED ON. An agent switched from Pi to Codex can
+ * still carry `peakflo/gpt-4.1`; handing `gpt-4.1` to Codex would be a guess
+ * that the two vendors mean the same thing by a name. The harness then runs
+ * its own default model, which is what its CLI would do.
+ */
+export declare function vendorModelId(model: {
+    provider?: string | null;
+    model?: string | null;
+}, backend: string): string | undefined;
+export declare const CLAUDE_SDK_PACKAGE = "@anthropic-ai/claude-agent-sdk";
+/**
+ * Why a harness that is installed and signed in still cannot be run by this
+ * runner. Fixed sentences, like every other reason in the report.
+ */
+export declare const NOT_RUNNABLE_REASONS: {
+    readonly claudeSdkMissing: "The Claude Agent SDK is not installed. Run `npm install -g @anthropic-ai/claude-agent-sdk` on this machine.";
+    readonly sandbox: "A cloud sandbox runs Pi only.";
+};
+/**
+ * Directories to look for the SDK in, besides this package's own
+ * `node_modules`.
+ *
+ * WHY IT IS NOT SIMPLY A DEPENDENCY. In 20x the SDK ships inside the app. Here
+ * that would add its platform package — about 190 MB, a copy of the Claude
+ * binary — to EVERY install of the runner, the cloud sandbox included, for a
+ * harness most installs never use. The adapter already points the SDK at the
+ * `claude` the user installed, so only the SDK's own JavaScript is needed, and
+ * a machine that wants Claude Code installs it once, globally.
+ */
+export declare function claudeSdkSearchRoots(env?: NodeJS.ProcessEnv, execPath?: string): string[];
+/**
+ * Where the SDK can be loaded from, or null. Synchronous and cheap (a few
+ * file reads), so it can be asked on every capability report.
+ *
+ * `ownTree` is this package's own resolution, replaced in tests — this
+ * repository has the SDK as a dev dependency, so "not installed" could not be
+ * tested otherwise.
+ */
+export declare function resolveClaudeSdk(roots?: readonly string[], ownTree?: () => string): string | null;
+/** Import the SDK from wherever `resolveClaudeSdk` finds it. Throws when absent. */
+export declare function importClaudeSdk(): Promise<unknown>;
+/** Whether this runner can build an adapter for a vendor backend right now. */
+export declare function vendorBackendBlocker(backend: string, runtime: string): string | null;

package/dist/vendor-backends.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * THE VENDOR HARNESSES THIS RUNNER CAN RUN: Codex, Claude Code, Cursor.
+ *
+ * "Vendor" because each one talks to its own vendor with the sign-in that is
+ * already on the machine — exactly as in 20x, where the same adapters run
+ * with no gateway and no key from the app. That is what separates them from
+ * Pi, which is credentialed for every turn from the lease:
+ *
+ *                      Pi                          Codex / Claude Code / Cursor
+ *   model credential   gateway key in the lease    the machine's own sign-in
+ *   model id           `provider/model`            the vendor's own bare id
+ *   where it runs      every runtime               desktop and self-hosted only
+ *
+ * WHICH ADAPTER, AS IN 20x `agent-manager.ts` `getAdapter`:
+ *   codex        -> CodexAppServerAdapter   (`codex app-server --stdio`)
+ *   claude-code  -> ClaudeCodeAdapter       (`@anthropic-ai/claude-agent-sdk`)
+ *   cursor       -> AcpAdapter('cursor')    (`cursor-agent acp`)
+ *
+ * NEVER IN A SANDBOX. A cloud sandbox has no vendor sign-in and must not be
+ * given one: no tenant vendor credential is placed on an untrusted host. It
+ * stays Pi-only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOT_RUNNABLE_REASONS = exports.CLAUDE_SDK_PACKAGE = exports.VENDOR_BACKENDS = void 0;
+exports.isVendorBackend = isVendorBackend;
+exports.vendorModelId = vendorModelId;
+exports.claudeSdkSearchRoots = claudeSdkSearchRoots;
+exports.resolveClaudeSdk = resolveClaudeSdk;
+exports.importClaudeSdk = importClaudeSdk;
+exports.vendorBackendBlocker = vendorBackendBlocker;
+const node_fs_1 = require("node:fs");
+const node_module_1 = require("node:module");
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+exports.VENDOR_BACKENDS = ['codex', 'claude-code', 'cursor'];
+function isVendorBackend(name) {
+    return exports.VENDOR_BACKENDS.includes(name);
+}
+/**
+ * The model id a vendor adapter is given, or undefined for "the harness's own
+ * default".
+ *
+ * An agent's model is stored as `{ provider, model }`. For a vendor harness the
+ * picker stores the HARNESS NAME as the provider (`codex` / `gpt-6-sol`), so a
+ * model that belongs to this harness is recognised by `provider === backend`
+ * and its bare id is what the adapter gets.
+ *
+ * ANY OTHER PROVIDER IS NOT PASSED ON. An agent switched from Pi to Codex can
+ * still carry `peakflo/gpt-4.1`; handing `gpt-4.1` to Codex would be a guess
+ * that the two vendors mean the same thing by a name. The harness then runs
+ * its own default model, which is what its CLI would do.
+ */
+function vendorModelId(model, backend) {
+    const name = (model.model ?? '').trim();
+    const provider = (model.provider ?? '').trim();
+    return name && provider === backend ? name : undefined;
+}
+/* -------------------------------------------------------------------------- */
+/* The Claude Agent SDK                                                        */
+/* -------------------------------------------------------------------------- */
+exports.CLAUDE_SDK_PACKAGE = '@anthropic-ai/claude-agent-sdk';
+/**
+ * Why a harness that is installed and signed in still cannot be run by this
+ * runner. Fixed sentences, like every other reason in the report.
+ */
+exports.NOT_RUNNABLE_REASONS = {
+    claudeSdkMissing: 'The Claude Agent SDK is not installed. Run `npm install -g @anthropic-ai/claude-agent-sdk` on this machine.',
+    sandbox: 'A cloud sandbox runs Pi only.'
+};
+/**
+ * Directories to look for the SDK in, besides this package's own
+ * `node_modules`.
+ *
+ * WHY IT IS NOT SIMPLY A DEPENDENCY. In 20x the SDK ships inside the app. Here
+ * that would add its platform package — about 190 MB, a copy of the Claude
+ * binary — to EVERY install of the runner, the cloud sandbox included, for a
+ * harness most installs never use. The adapter already points the SDK at the
+ * `claude` the user installed, so only the SDK's own JavaScript is needed, and
+ * a machine that wants Claude Code installs it once, globally.
+ */
+function claudeSdkSearchRoots(env = process.env, execPath = process.execPath) {
+    const roots = [
+        env.PF_CLAUDE_AGENT_SDK_DIR,
+        // `npm install -g` beside the running node: <prefix>/lib/node_modules
+        (0, node_path_1.join)((0, node_path_1.dirname)((0, node_path_1.dirname)(execPath)), 'lib', 'node_modules'),
+        // Windows: <prefix>\node_modules
+        (0, node_path_1.join)((0, node_path_1.dirname)(execPath), 'node_modules'),
+        '/opt/homebrew/lib/node_modules',
+        '/usr/local/lib/node_modules'
+    ];
+    return [...new Set(roots.filter((root) => Boolean(root)))];
+}
+/** The file a package directory loads as, read from its own package.json. */
+function packageEntry(directory) {
+    try {
+        const manifest = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(directory, 'package.json'), 'utf8'));
+        const root = manifest.exports && typeof manifest.exports === 'object'
+            ? (manifest.exports['.'] ??
+                manifest.exports)
+            : manifest.exports;
+        const fromExports = typeof root === 'string'
+            ? root
+            : root && typeof root === 'object'
+                ? (root.import ??
+                    root.default)
+                : undefined;
+        const entry = [
+            fromExports,
+            manifest.module,
+            manifest.main,
+            'index.js'
+        ].find((candidate) => typeof candidate === 'string');
+        const file = entry ? (0, node_path_1.join)(directory, entry) : null;
+        return file && (0, node_fs_1.existsSync)(file) ? file : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Where the SDK can be loaded from, or null. Synchronous and cheap (a few
+ * file reads), so it can be asked on every capability report.
+ *
+ * `ownTree` is this package's own resolution, replaced in tests — this
+ * repository has the SDK as a dev dependency, so "not installed" could not be
+ * tested otherwise.
+ */
+function resolveClaudeSdk(roots = claudeSdkSearchRoots(), ownTree = () => (0, node_module_1.createRequire)(__filename).resolve(exports.CLAUDE_SDK_PACKAGE)) {
+    try {
+        return ownTree();
+    }
+    catch {
+        // Not in this package's own tree.
+    }
+    for (const root of roots) {
+        const entry = packageEntry((0, node_path_1.join)(root, exports.CLAUDE_SDK_PACKAGE));
+        if (entry)
+            return entry;
+    }
+    return null;
+}
+/** Import the SDK from wherever `resolveClaudeSdk` finds it. Throws when absent. */
+async function importClaudeSdk() {
+    const resolved = resolveClaudeSdk();
+    if (!resolved) {
+        throw new Error(exports.NOT_RUNNABLE_REASONS.claudeSdkMissing);
+    }
+    /*
+     * `new Function` keeps this a REAL dynamic import in the compiled CommonJS
+     * output. Written as `import(x)`, TypeScript turns it into `require(x)`,
+     * and the SDK is an ES module that `require` cannot load on every Node.
+     */
+    const dynamicImport = new Function('specifier', 'return import(specifier)');
+    return dynamicImport((0, node_url_1.pathToFileURL)(resolved).href);
+}
+/** Whether this runner can build an adapter for a vendor backend right now. */
+function vendorBackendBlocker(backend, runtime) {
+    if (!isVendorBackend(backend))
+        return null;
+    if (runtime === 'sandbox')
+        return exports.NOT_RUNNABLE_REASONS.sandbox;
+    if (backend === 'claude-code' && !resolveClaudeSdk()) {
+        return exports.NOT_RUNNABLE_REASONS.claudeSdkMissing;
+    }
+    return null;
+}

package/dist/version.d.ts

@@ -1,5 +1,7 @@
 /** The version of THIS package, as installed. */
 export declare function getHarnessVersion(): string;
+/** `engines.node` of THIS package (e.g. `>=22.19`), or null when unreadable. */
+export declare function getNodeFloor(): string | null;
 /**
  * The version of the SANDBOX TOOLS layer (gh, @peculiar/x509, ...) currently
  * installed, or null when nothing was ever synced — a self-hosted runner or