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

package/README.md

@@ -46,9 +46,26 @@ Claude Code (`claude`), Cursor (`cursor-agent`), Pi (`pi`) and OpenCode
 whether it is signed in, and the models it offers. Peakflo shows this list in
 the agent editor and in the chat details.
 
-Finding a harness does not mean the runner can use it. The runner runs turns
-with Pi only; the other harnesses are shown as "Detected, not yet runnable by
-this runner".
+**Which ones the runner can run.** Pi always. On a desktop or self-hosted
+machine also Codex, Claude Code and Cursor, each for as long as it is
+installed and signed in on that machine — the runner uses that sign-in, as you
+do when you run the tool yourself. An agent in Peakflo can then be given that
+harness and one of its models. OpenCode is listed and cannot be run yet. A
+cloud sandbox runs Pi only.
+
+- These turns use your own Codex, Claude or Cursor account. They do not go
+  through the Peakflo model gateway and are not metered by Peakflo.
+- When you sign out of a harness, or remove it, the runner stops taking work
+  for it after its next check.
+- What the runner brings and what it expects, the same split as the 20x app:
+  it brings the Claude Agent SDK (a dependency of this package, installed with
+  it); it expects the tools themselves — `codex`, `claude`, `cursor-agent` —
+  to be installed and signed in on the machine. The SDK includes a copy of the
+  Claude binary for your platform, which is most of this package's install
+  size (about 260 MB installed).
+- Each turn starts the harness's own program and stops it when the turn ends.
+  The conversation continues from the session the harness saved on this
+  machine.
 
 **When it looks.** Once after start, without delaying registration, and then
 every five minutes while no turn is running. A harness you install or sign in

package/dist/adapter-resolver.d.ts

@@ -0,0 +1,61 @@
+import { type CodingAgentAdapter } from './adapters';
+import type { AdapterPorts } from './harness';
+/**
+ * Give a vendor adapter the one thing the runner asks of a backend at the end
+ * of a turn: `stopServer()`.
+ *
+ * ONE PROCESS PER TURN, as for Pi. In 20x an adapter lives as long as the app
+ * and its CLI process stays up between messages. Here every turn is a new
+ * lease with its own MCP token, the runner may be handed the same chat by a
+ * control plane that last ran it elsewhere, and nothing may be left running
+ * when no turn is. So the process a turn started is stopped when the turn
+ * ends, and the next turn resumes the vendor's own saved session by its
+ * checkpoint (Codex thread id, Claude session id, Cursor ACP session id) —
+ * the path these adapters already have for "the app was restarted".
+ *
+ * Leaving the process up is not merely wasteful: `codex app-server` keeps the
+ * thread open for writing, and the next turn's `thread/resume` from a second
+ * process is refused with "already has an active writer".
+ *
+ * The session ids are recorded here, from what `createSession` returned and
+ * `resumeSession` was given, rather than read out of the adapter's private
+ * state. `destroySession` is the adapters' own teardown and does not delete
+ * the vendor's saved session.
+ */
+/** How long the end of a turn waits for one vendor session to stop. */
+export declare const STOP_TIMEOUT_MS = 5000;
+export declare function stopAtTurnEnd<T extends CodingAgentAdapter>(adapter: T, instanceId?: string | null, options?: {
+    /**
+     * The adapter numbers its parts from 1 in every process
+     * (`agent-response-1`). See `pollMessages` below.
+     */
+    partIdsRestartEveryProcess?: boolean;
+}): T;
+/**
+ * A random id for THIS runner's vendor sessions, written once into the
+ * runner's own state directory (never into a vendor's). Survives a restart;
+ * two runners never share one. Null when it cannot be written, which keeps
+ * the older behaviour (try to resume, fall back to replay).
+ */
+export declare function vendorInstanceId(stateDir: string): string | null;
+/**
+ * Which adapter drives which backend — the same table as 20x
+ * `agent-manager.ts` `getAdapter`.
+ *
+ * Pi on every runtime. Codex, Claude Code and Cursor on a desktop or
+ * self-hosted runner only: they use the vendor sign-in that is already on the
+ * machine, and a cloud sandbox has none and must not be given one.
+ *
+ * A NEW ADAPTER FOR EVERY TURN, for every backend, stopped when the turn
+ * ends (`stopAtTurnEnd`). This is where the runner differs from 20x, which
+ * keeps one adapter per harness for the life of the app.
+ *
+ * Advertising a backend the host cannot run makes the control plane route
+ * work to a runner that must then fail it, so `capabilities.backends` lists a
+ * vendor backend only while discovery says it is installed and signed in (see
+ * `Harness.vendorBackendsFor`). This function is the last line: it refuses
+ * anything that should not have been leased here.
+ */
+export declare function createAdapterResolver(runtime: string, 
+/** The runner's own state directory (its workspace root). */
+stateDir?: string): (backend: string, ports: AdapterPorts) => CodingAgentAdapter;

package/dist/adapter-resolver.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STOP_TIMEOUT_MS = void 0;
+exports.stopAtTurnEnd = stopAtTurnEnd;
+exports.vendorInstanceId = vendorInstanceId;
+exports.createAdapterResolver = createAdapterResolver;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const adapters_1 = require("./adapters");
+const vendor_backends_1 = require("./vendor-backends");
+/**
+ * Hand the vendor CLI the workspace by its REAL path.
+ *
+ * Claude Code files a session under a directory named after the real path of
+ * its working directory, and the adapter looks for that file under the path it
+ * was given. With a workspace root that goes through a symlink (on macOS
+ * `/tmp` is one, to `/private/tmp`) the two differ, the session file is "not
+ * found", and every turn replays instead of resuming. Seen for real while
+ * proving this change. Changed in place: the same config object is passed to
+ * every later call of the turn.
+ */
+function setRealWorkspacePath(config) {
+    try {
+        config.workspaceDir = (0, node_fs_1.realpathSync)(config.workspaceDir);
+    }
+    catch {
+        // Not there yet, or unreadable: keep the path as given.
+    }
+}
+/**
+ * Give a vendor adapter the one thing the runner asks of a backend at the end
+ * of a turn: `stopServer()`.
+ *
+ * ONE PROCESS PER TURN, as for Pi. In 20x an adapter lives as long as the app
+ * and its CLI process stays up between messages. Here every turn is a new
+ * lease with its own MCP token, the runner may be handed the same chat by a
+ * control plane that last ran it elsewhere, and nothing may be left running
+ * when no turn is. So the process a turn started is stopped when the turn
+ * ends, and the next turn resumes the vendor's own saved session by its
+ * checkpoint (Codex thread id, Claude session id, Cursor ACP session id) —
+ * the path these adapters already have for "the app was restarted".
+ *
+ * Leaving the process up is not merely wasteful: `codex app-server` keeps the
+ * thread open for writing, and the next turn's `thread/resume` from a second
+ * process is refused with "already has an active writer".
+ *
+ * The session ids are recorded here, from what `createSession` returned and
+ * `resumeSession` was given, rather than read out of the adapter's private
+ * state. `destroySession` is the adapters' own teardown and does not delete
+ * the vendor's saved session.
+ */
+/** How long the end of a turn waits for one vendor session to stop. */
+exports.STOP_TIMEOUT_MS = 5_000;
+function stopAtTurnEnd(adapter, instanceId, options = {}) {
+    if (instanceId) {
+        /*
+         * WHOSE CHECKPOINT IS IT. A vendor session lives on the machine that made
+         * it (`~/.codex`, `~/.claude`, Cursor's own store). A chat that is leased
+         * to another runner next carries a checkpoint that means nothing there;
+         * with this id the runner sees that at once and replays the conversation,
+         * instead of asking the vendor CLI for a session it never had.
+         */
+        adapter.backendInstanceId =
+            () => instanceId;
+    }
+    const started = new Map();
+    const realIds = new Map();
+    const createSession = adapter.createSession.bind(adapter);
+    const resumeSession = adapter.resumeSession.bind(adapter);
+    adapter.createSession = async (config) => {
+        setRealWorkspacePath(config);
+        const id = await createSession(config);
+        started.set(id, config);
+        return id;
+    };
+    adapter.resumeSession = async (sessionId, config) => {
+        // Recorded BEFORE the call: a resume that fails half-way may already have
+        // started the process.
+        setRealWorkspacePath(config);
+        started.set(sessionId, config);
+        return resumeSession(sessionId, config);
+    };
+    /*
+     * A PART WITH NO ROLE IS THE ASSISTANT'S — the rule 20x applies where it
+     * reads these adapters' parts (`agent-manager.ts`: `part.role || 'assistant'`).
+     * The Claude Code adapter sends the model's own text with no role at all and
+     * relies on that. The runner's projection reads a missing role as `system`,
+     * which is right for Pi and would show Claude's whole answer as a system
+     * notice. So the 20x default is applied here, for these adapters only.
+     */
+    /*
+     * PART IDS THAT START AGAIN IN EVERY PROCESS ARE MADE UNIQUE PER TURN.
+     *
+     * The ACP adapter names the answer of a turn `agent-response-<n>`, counting
+     * from 1 in each process. In 20x one process serves the whole conversation,
+     * so the numbers keep growing. Here each turn has its own process, so every
+     * turn's answer was `agent-response-1` and the transcript — which stores a
+     * part by its id — replaced the previous turn's answer with the new one.
+     * Seen for real with Cursor: two turns, one answer left.
+     *
+     * The id is prefixed with the turn id on its way out. The adapter keeps
+     * working in its own ids: it is given its own "already seen" sets, because
+     * the runner's hold the prefixed ids and the adapter compares against the
+     * ids it produces. After a resume the adapter has already dropped the
+     * replayed history from its buffer, so only this turn's parts come through.
+     */
+    const ownSeen = {
+        messages: new Set(),
+        parts: new Set(),
+        lengths: new Map()
+    };
+    const pollMessages = adapter.pollMessages.bind(adapter);
+    adapter.pollMessages = async (...args) => {
+        const scoped = options.partIdsRestartEveryProcess === true;
+        const turnId = args[4]?.turnId;
+        const parts = scoped
+            ? await pollMessages(args[0], ownSeen.messages, ownSeen.parts, ownSeen.lengths, args[4])
+            : await pollMessages(...args);
+        for (const part of parts) {
+            if (scoped && turnId && part.id)
+                part.id = `${turnId}:${part.id}`;
+            if (!part.role)
+                part.role = adapters_1.MessageRole.ASSISTANT;
+            // The id the vendor gave the session, when it differs from the one
+            // `createSession` returned. See `checkpointSessionId` below.
+            if (part.realSessionId)
+                realIds.set(args[0], part.realSessionId);
+        }
+        return parts;
+    };
+    /*
+     * The session id to SAVE for the next turn. Claude Code's real id arrives on
+     * a part of the stream; 20x re-keys its session when it sees one. The runner
+     * asks here at the end of the turn and saves the real id as the checkpoint.
+     */
+    adapter.checkpointSessionId = (sessionId) => realIds.get(sessionId);
+    adapter.stopServer =
+        async () => {
+            for (const [sessionId, config] of started) {
+                try {
+                    // BOUNDED. This runs between a turn's last part and the release of
+                    // its lease; a vendor CLI that will not die must not hold that up.
+                    await Promise.race([
+                        adapter.destroySession(sessionId, config),
+                        new Promise((resolve) => {
+                            const timer = setTimeout(resolve, exports.STOP_TIMEOUT_MS);
+                            timer.unref();
+                        })
+                    ]);
+                }
+                catch {
+                    // Teardown is best-effort; the next id still gets its turn.
+                }
+            }
+            started.clear();
+        };
+    return adapter;
+}
+/**
+ * A random id for THIS runner's vendor sessions, written once into the
+ * runner's own state directory (never into a vendor's). Survives a restart;
+ * two runners never share one. Null when it cannot be written, which keeps
+ * the older behaviour (try to resume, fall back to replay).
+ */
+function vendorInstanceId(stateDir) {
+    const marker = (0, node_path_1.join)(stateDir, '.pf-vendor-instance-id');
+    try {
+        const existing = (0, node_fs_1.readFileSync)(marker, 'utf8').trim();
+        if (existing)
+            return existing;
+    }
+    catch {
+        // Not written yet.
+    }
+    try {
+        const id = (0, node_crypto_1.randomUUID)();
+        (0, node_fs_1.mkdirSync)(stateDir, { recursive: true, mode: 0o700 });
+        (0, node_fs_1.writeFileSync)(marker, `${id}\n`, { mode: 0o600, flag: 'wx' });
+        return id;
+    }
+    catch {
+        try {
+            // Lost a race with another start: read what the winner wrote.
+            return (0, node_fs_1.readFileSync)(marker, 'utf8').trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Which adapter drives which backend — the same table as 20x
+ * `agent-manager.ts` `getAdapter`.
+ *
+ * Pi on every runtime. Codex, Claude Code and Cursor on a desktop or
+ * self-hosted runner only: they use the vendor sign-in that is already on the
+ * machine, and a cloud sandbox has none and must not be given one.
+ *
+ * A NEW ADAPTER FOR EVERY TURN, for every backend, stopped when the turn
+ * ends (`stopAtTurnEnd`). This is where the runner differs from 20x, which
+ * keeps one adapter per harness for the life of the app.
+ *
+ * Advertising a backend the host cannot run makes the control plane route
+ * work to a runner that must then fail it, so `capabilities.backends` lists a
+ * vendor backend only while discovery says it is installed and signed in (see
+ * `Harness.vendorBackendsFor`). This function is the last line: it refuses
+ * anything that should not have been leased here.
+ */
+function createAdapterResolver(runtime, 
+/** The runner's own state directory (its workspace root). */
+stateDir) {
+    const instanceId = stateDir ? vendorInstanceId(stateDir) : null;
+    const build = (backend) => {
+        switch (backend) {
+            case 'codex':
+                return new adapters_1.CodexAppServerAdapter();
+            case 'claude-code':
+                return new adapters_1.ClaudeCodeAdapter();
+            case 'cursor':
+                return new adapters_1.AcpAdapter('cursor');
+            default:
+                throw new Error(`No adapter for backend "${backend}".`);
+        }
+    };
+    return (backend, ports) => {
+        if (backend === 'pi') {
+            // The adapter reads the per-turn gateway holder directly. If the lease
+            // has no model token SessionRunner refuses before this is reached.
+            return new adapters_1.PiAdapter(ports.modelGateway);
+        }
+        if ((0, vendor_backends_1.isVendorBackend)(backend)) {
+            const blocker = (0, vendor_backends_1.vendorBackendBlocker)(backend, runtime);
+            if (blocker) {
+                throw new Error(`Backend "${backend}" cannot run here. ${blocker}`);
+            }
+            return stopAtTurnEnd(build(backend), instanceId ? `${backend}:${instanceId}` : null, { partIdsRestartEveryProcess: backend === 'cursor' });
+        }
+        throw new Error(`Backend "${backend}" is not wired in this build. ` +
+            'Available: pi, and on a desktop or self-hosted runner codex, ' +
+            'claude-code and cursor.');
+    };
+}

package/dist/cli.js

@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-const adapters_1 = require("./adapters");
+const adapter_resolver_1 = require("./adapter-resolver");
 const contract_1 = require("./contract");
 const credential_store_1 = require("./credential-store");
 const harness_1 = require("./harness");
@@ -88,27 +88,6 @@ PF_ALLOW_UNSUPPORTED_NODE=1 starts anyway, at your own risk.
 In a managed sandbox pf-bootstrap supplies these through the environment, so
 the enrolment token never appears in /proc/<pid>/cmdline.
 `;
-/**
- * Which adapter drives which backend.
- *
- * PI ONLY IN THIS BUILD, even though the legacy adapters remain exported for
- * extracted and are exported from the package. The others are wired by a HOST
- * that has verified their prerequisites: Claude Code needs
- * `@anthropic-ai/claude-agent-sdk` (an optional dependency, absent from the
- * sandbox image), and Codex and ACP need binaries the image does not ship.
- * Advertising a backend the host cannot actually run would make the control
- * plane route work to a runner that must then fail it.
- */
-function resolveAdapter(backend, ports) {
-    if (backend === 'pi') {
-        // The adapter reads the per-turn gateway holder directly. If the lease has
-        // no model token SessionRunner refuses before this constructor is reached.
-        return new adapters_1.PiAdapter(ports.modelGateway);
-    }
-    throw new Error(`Backend "${backend}" is not wired in this build. ` +
-        'Only "pi" is available; the other adapters are exported for a ' +
-        'host to wire once it has verified their prerequisites.');
-}
 /**
  * Read `--flag value` from argv. A tiny duplicate of the reader in options.ts,
  * because the login decision has to be made BEFORE `parseOptions` runs — that
@@ -204,6 +183,7 @@ async function main() {
     }
     const options = (0, options_1.parseOptions)(startArgs, process.env);
     const handedOffCredential = (0, credential_store_1.takeHandedOffCredential)(process.env);
+    const resolveAdapter = (0, adapter_resolver_1.createAdapterResolver)(options.runtime, options.workspaceRoot);
     const harness = new harness_1.Harness(options, {
         getAdapter: (backend, ports) => resolveAdapter(backend, ports),
         ...(handedOffCredential

package/dist/harness.d.ts

@@ -123,6 +123,11 @@ export interface HarnessDeps {
     approvalRenewIntervalMs?: number;
     /** Injected in tests. */
     clientFactory?: (url: string) => ControlPlaneClient;
+    /**
+     * Why a vendor backend cannot be run here, or null. Injected in tests;
+     * defaults to `vendorBackendBlocker` (sandbox, or the Claude SDK missing).
+     */
+    vendorBackendBlocker?: (backend: string, runtime: string) => string | null;
     /** Injected in tests; defaults to the real `discoverHarnesses`. */
     discoverHarnesses?: (options: DiscoverHarnessesOptions) => Promise<RunnerHarness[]>;
 }
@@ -359,6 +364,25 @@ export declare class Harness {
      * the same reason — one source, so the two lists cannot disagree.
      */
     private applyHarnessReport;
+    /**
+     * Add Codex, Claude Code and Cursor to `backends` — the list work is routed
+     * on — for exactly as long as each is INSTALLED AND SIGNED IN.
+     *
+     * This is the gate that turns "detected" into "runnable", so it is strict:
+     *
+     *   - only from a discovery report, which a sandbox never has;
+     *   - only a harness whose check SETTLED as usable. A check that timed out
+     *     with no earlier answer is not enough to take work on;
+     *   - only when this runner was given adapters at all, and has what the
+     *     adapter needs (Claude Code needs the Claude Agent SDK).
+     *
+     * Recomputed for every capability report from the cached discovery pass, so
+     * a harness that is signed out, or uninstalled, leaves `backends` with the
+     * report that follows the pass which noticed. Nothing is remembered here.
+     *
+     * Returns why each harness that is usable was still NOT added, for the UI.
+     */
+    private addVendorBackends;
     private harnessDiscoveryEnabled;
     /**
      * Whether to start a discovery pass on this heartbeat.

package/dist/harness.js

@@ -22,6 +22,7 @@ const mcp_auth_proxy_1 = require("./runtime/mcp-auth-proxy");
 const session_runner_1 = require("./runtime/session-runner");
 const conversation_store_1 = require("./store/conversation-store");
 const sqlite_store_1 = require("./store/sqlite-store");
+const vendor_backends_1 = require("./vendor-backends");
 const version_1 = require("./version");
 /** Backoff after a lease poll fails, so an unreachable control plane is not hammered. */
 const LEASE_ERROR_BACKOFF_MS = 5_000;
@@ -763,7 +764,10 @@ class Harness {
      * `force` re-probes regardless of age (used at start-up). Never rejects.
      */
     async refreshModelCatalog(force = false) {
-        const backends = this.capabilities?.backends ?? [];
+        // A vendor harness's models come from discovery, not from this probe:
+        // asking its adapter would start `codex app-server` or `cursor-agent acp`
+        // just to list models that are already known.
+        const backends = (this.capabilities?.backends ?? []).filter((backend) => !(0, vendor_backends_1.isVendorBackend)(backend.name));
         const build = this.deps.getAdapter;
         if (!build || backends.length === 0) {
             this.modelCatalog = null;
@@ -941,10 +945,16 @@ class Harness {
         if (!this.harnessReport) {
             return;
         }
+        const blocked = this.addVendorBackends(capabilities);
         const harnesses = this.harnessReport.map((harness) => {
             const backend = capabilities.backends.find((candidate) => candidate.name === harness.name);
             if (!backend) {
-                return { ...harness, runnable: false };
+                const reason = blocked.get(harness.name);
+                return {
+                    ...harness,
+                    runnable: false,
+                    ...(reason ? { notRunnableReason: reason } : {})
+                };
             }
             /*
              * A HARNESS THIS RUNNER RUNS IS NEVER SHOWN WORSE THAN `backends` SAYS.
@@ -990,6 +1000,55 @@ class Harness {
             exports.HARNESS_DISCOVERY_FEATURE
         ];
     }
+    /**
+     * Add Codex, Claude Code and Cursor to `backends` — the list work is routed
+     * on — for exactly as long as each is INSTALLED AND SIGNED IN.
+     *
+     * This is the gate that turns "detected" into "runnable", so it is strict:
+     *
+     *   - only from a discovery report, which a sandbox never has;
+     *   - only a harness whose check SETTLED as usable. A check that timed out
+     *     with no earlier answer is not enough to take work on;
+     *   - only when this runner was given adapters at all, and has what the
+     *     adapter needs (Claude Code needs the Claude Agent SDK).
+     *
+     * Recomputed for every capability report from the cached discovery pass, so
+     * a harness that is signed out, or uninstalled, leaves `backends` with the
+     * report that follows the pass which noticed. Nothing is remembered here.
+     *
+     * Returns why each harness that is usable was still NOT added, for the UI.
+     */
+    addVendorBackends(capabilities) {
+        const blocked = new Map();
+        if (!this.harnessReport || !this.deps.getAdapter)
+            return blocked;
+        const blocker = this.deps.vendorBackendBlocker ?? vendor_backends_1.vendorBackendBlocker;
+        for (const harness of this.harnessReport) {
+            if (!(0, vendor_backends_1.isVendorBackend)(harness.name))
+                continue;
+            if (!harness.installed || !harness.usable)
+                continue;
+            if (capabilities.backends.some((b) => b.name === harness.name))
+                continue;
+            const reason = blocker(harness.name, this.options.runtime);
+            if (reason) {
+                blocked.set(harness.name, reason);
+                continue;
+            }
+            /*
+             * NAME AND VERSION ONLY. The harness's models are already in
+             * `harnesses[]`, which is sent once and then by digest. Repeating them
+             * here put them back into every heartbeat: about 15 KB each time on a
+             * machine with Cursor's 200 models, seen on the first release candidate
+             * that had this.
+             */
+            capabilities.backends.push({
+                name: harness.name,
+                version: harness.version ?? null
+            });
+        }
+        return blocked;
+    }
     harnessDiscoveryEnabled() {
         return (this.options.runtime !== 'sandbox' &&
             this.options.harnessDiscovery !== false);

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/types.d.ts

@@ -293,6 +293,12 @@ export interface RunnerHarness {
     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,69 @@
+/**
+ * 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 that ships with this runner could not be loaded. Reinstall the runner.";
+    readonly sandbox: "A cloud sandbox runs Pi only.";
+};
+/**
+ * Where the SDK is, or null.
+ *
+ * THE SDK IS A DEPENDENCY OF THIS PACKAGE, as it is of the 20x app: installing
+ * the runner installs it, and nothing else has to be done on the machine. So
+ * it is looked for in one place, this package's own dependency tree.
+ *
+ * Null is still possible and still handled, because "declared" is not
+ * "present": an install that was interrupted, pruned, or made with
+ * dependencies left out has no SDK. Claude Code is then reported as not
+ * runnable, with a reason, instead of being routed a turn it must fail.
+ *
+ * `ownTree` is replaced in tests, which could not otherwise see "missing".
+ */
+export declare function resolveClaudeSdk(ownTree?: () => string): string | null;
+/** 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,98 @@
+"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.resolveClaudeSdk = resolveClaudeSdk;
+exports.vendorBackendBlocker = vendorBackendBlocker;
+const node_module_1 = require("node:module");
+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 that ships with this runner could not be loaded. Reinstall the runner.',
+    sandbox: 'A cloud sandbox runs Pi only.'
+};
+/**
+ * Where the SDK is, or null.
+ *
+ * THE SDK IS A DEPENDENCY OF THIS PACKAGE, as it is of the 20x app: installing
+ * the runner installs it, and nothing else has to be done on the machine. So
+ * it is looked for in one place, this package's own dependency tree.
+ *
+ * Null is still possible and still handled, because "declared" is not
+ * "present": an install that was interrupted, pruned, or made with
+ * dependencies left out has no SDK. Claude Code is then reported as not
+ * runnable, with a reason, instead of being routed a turn it must fail.
+ *
+ * `ownTree` is replaced in tests, which could not otherwise see "missing".
+ */
+function resolveClaudeSdk(ownTree = () => (0, node_module_1.createRequire)(__filename).resolve(exports.CLAUDE_SDK_PACKAGE)) {
+    try {
+        return ownTree();
+    }
+    catch {
+        return null;
+    }
+}
+/** 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peakflo/agent-harness",
-  "version": "0.2.9-rc.2",
+  "version": "0.2.9-rc.4",
   "description": "Headless Peakflo coding-agent harness. One codebase, three hosting modes: a Daytona cloud sandbox, a customer VM, and the 20x desktop.",
   "license": "MIT",
   "type": "commonjs",
@@ -29,7 +29,6 @@
     "test": "jest"
   },
   "devDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.195",
     "@opencode-ai/sdk": "^1.15.13",
     "@types/node": "^22.10.0",
     "tsx": "^4.19.3",
@@ -37,6 +36,7 @@
     "undici": "^7.21.0"
   },
   "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.258",
     "@modelcontextprotocol/client": "2.0.0",
     "@peculiar/x509": "^2.1.0",
     "reflect-metadata": "^0.2.2"