@peakflo/agent-harness 0.2.13 → 0.2.14-rc.1

package/dist/adapters/coding-agent-adapter.d.ts

@@ -7,6 +7,7 @@
  * CHANGED: imports only — `../../shared/reasoning-effort` ->
  * `../shared/reasoning-effort`. Source formatting (no semicolons) preserved.
  */
+import type { McpToolsetSnapshot } from '../runtime/mcp-toolset';
 import type { ReasoningEffort } from '../shared/reasoning-effort';
 export declare enum SessionStatusType {
     IDLE = "idle",
@@ -61,6 +62,12 @@ export interface SessionConfig {
     tools?: Record<string, boolean>;
     promptAbort?: AbortController;
     mcpServers?: Record<string, McpServerConfig>;
+    /**
+     * Tool listings the harness preflight took for `mcpServers` on this turn.
+     * A backend may use them to skip its own MCP tool listing; a listing applies
+     * only while its `url` equals the server's url here. Contains no credential.
+     */
+    mcpToolSnapshot?: McpToolsetSnapshot;
     /** Claude Code auth method: 'subscription' (OAuth/Pro/Max) or 'api_key' (pay-per-use). Defaults to 'subscription'. */
     authMethod?: 'subscription' | 'api_key';
     permissionMode?: 'ask' | 'allow';
@@ -192,6 +199,18 @@ export interface CodingAgentAdapter {
      * Get current session status
      */
     getStatus(sessionId: string, config: SessionConfig): Promise<SessionStatus>;
+    /**
+     * OPTIONAL. `true` when this backend reports IDLE only once the whole turn
+     * has settled (never between tool calls) and buffers every part of the turn
+     * BEFORE it reports that IDLE.
+     *
+     * The runner still needs two consecutive quiet polls to end a turn, but for
+     * such a backend the confirming poll runs after a short pause instead of the
+     * normal poll interval, so the turn ends a few hundred milliseconds after the
+     * last part rather than ~2 s later. Leave unset (the safe default) for a
+     * backend whose status can flip to IDLE between tool rounds.
+     */
+    readonly idleIsTerminal?: boolean;
     /**
      * Get new messages since last poll
      * @param seenMessageIds Set of message IDs already processed

package/dist/adapters/pi-adapter.d.ts

@@ -6,6 +6,7 @@
  */
 import type { CodingAgentAdapter, MessagePart, SessionConfig, SessionMessage, SessionStatus } from './coding-agent-adapter';
 import { type ModelGatewayConfigSource } from './model-gateway';
+import { type PiMetadataCacheApi } from './pi-mcp-cache-seed';
 export declare const PI_DEV_SERVER_POLICY_ENV = "PF_DEV_SERVER_POLICY_FILE";
 /**
  * Most model providers cap function/tool `name` at 64 characters. Pi forwards
@@ -43,13 +44,28 @@ export declare function withProviderNameLimitHint(error: string): string;
  * Providers commonly reject the entire request when any tool exceeds 64
  * characters, before the model can call a tool.
  */
-export declare function buildPiMcpConfigDocument(servers: NonNullable<SessionConfig['mcpServers']>, onRename?: (name: string, slug: string) => void): Record<string, unknown>;
+export declare function buildPiMcpConfigDocument(servers: NonNullable<SessionConfig['mcpServers']>, onRename?: (name: string, slug: string) => void, options?: {
+    /**
+     * Harness server names whose tools are already in Pi's metadata cache.
+     * Only these may be lazy; see `pi-mcp-cache-seed.ts`.
+     */
+    lazyServers?: ReadonlySet<string>;
+    /** Receives the Pi key chosen for each harness server name. */
+    slugs?: Map<string, string>;
+}): Record<string, unknown>;
 export declare const PI_PERMISSION_EXTENSION_SOURCE: string;
 export declare class PiAdapter implements CodingAgentAdapter {
     private modelGateway;
     private sessions;
     private piExecutablePath;
     onDataAvailable?: (sessionId: string) => void;
+    /**
+     * Pi's status is BUSY from `sendPrompt` until `agent_settled`, which Pi
+     * emits once after the whole agent loop (every tool round) has finished and
+     * after the turn's message events, so IDLE here means the turn is over and
+     * its parts are already buffered. See `CodingAgentAdapter.idleIsTerminal`.
+     */
+    readonly idleIsTerminal = true;
     constructor(modelGateway: ModelGatewayConfigSource);
     private agentDirectory;
     /** Identity of the Pi session store that can honour native session files. */
@@ -62,6 +78,15 @@ export declare class PiAdapter implements CodingAgentAdapter {
      * value only to the child process.
      */
     private installPeakfloGateway;
+    /** Replaceable in tests; the real loader needs the installed adapter. */
+    protected loadMcpCacheApi: (agentDir: string) => PiMetadataCacheApi | null;
+    /**
+     * Item 4: write the harness preflight's tool listings into Pi's metadata
+     * cache, so Pi does not repeat initialize + tools/list for those servers on
+     * this turn. Returns the harness server names that were seeded; only these
+     * may be lazy. Any failure seeds nothing and keeps every server eager.
+     */
+    private seedMcpMetadataCache;
     private buildMcpConfig;
     private installPermissionExtension;
     private processEnv;
@@ -83,6 +108,7 @@ export declare class PiAdapter implements CodingAgentAdapter {
     private splitModel;
     private applySelection;
     private spawnSession;
+    private startPiProcess;
     createSession(config: SessionConfig): Promise<string>;
     resumeSession(sessionId: string, config: SessionConfig): Promise<SessionMessage[]>;
     private attachProcess;

package/dist/adapters/pi-adapter.js

@@ -21,6 +21,7 @@ const string_decoder_1 = require("string_decoder");
 const util_1 = require("util");
 const coding_agent_adapter_1 = require("./coding-agent-adapter");
 const model_gateway_1 = require("./model-gateway");
+const pi_mcp_cache_seed_1 = require("./pi-mcp-cache-seed");
 const vendor_environment_1 = require("./vendor-environment");
 const browser_takeover_1 = require("../runtime/browser-takeover");
 const cold_start_steps_1 = require("../runtime/cold-start-steps");
@@ -32,6 +33,33 @@ const MINIMUM_PI_VERSION = [0, 80, 5];
 const PI_PERMISSION_MODE_ENV = 'PEAKFLO_PI_PERMISSION_MODE';
 exports.PI_DEV_SERVER_POLICY_ENV = 'PF_DEV_SERVER_POLICY_FILE';
 const TERMINAL_ERROR_SETTLE_GRACE_MS = 1_000;
+/**
+ * How long a SIGTERMed Pi gets to exit before its process group is SIGKILLed.
+ * An upper bound, not a fixed wait: `terminateProcess` returns as soon as the
+ * child's `exit` event fires.
+ */
+const PI_TERMINATE_GRACE_MS = 1_000;
+/**
+ * Resolves when `child` exits or after `timeoutMs`, whichever comes first.
+ * `true` means the exit was observed. Already-exited children resolve at once.
+ */
+function waitForExit(child, timeoutMs) {
+    if (child.exitCode !== null || child.signalCode != null) {
+        return Promise.resolve(true);
+    }
+    return new Promise((resolve) => {
+        const wait = {};
+        const onExit = () => {
+            clearTimeout(wait.timer);
+            resolve(true);
+        };
+        wait.timer = setTimeout(() => {
+            child.removeListener('exit', onExit);
+            resolve(false);
+        }, timeoutMs);
+        child.once('exit', onExit);
+    });
+}
 // A tool may be silent for the full progress-guard window. Turn finalization
 // has its own short bound; this timer protects an active turn with no echo.
 const STEER_CONSUMPTION_TIMEOUT_MS = 20 * 60_000;
@@ -139,12 +167,13 @@ function withProviderNameLimitHint(error) {
  * Providers commonly reject the entire request when any tool exceeds 64
  * characters, before the model can call a tool.
  */
-function buildPiMcpConfigDocument(servers, onRename) {
+function buildPiMcpConfigDocument(servers, onRename, options = {}) {
     const usedSlugs = new Set();
     const mcpServers = Object.fromEntries(Object.entries(servers).map(([name, server]) => {
         const slug = sanitizePiMcpServerName(name, usedSlugs);
         if (slug !== name)
             onRename?.(name, slug);
+        options.slugs?.set(name, slug);
         if (server.type === 'stdio') {
             return [
                 slug,
@@ -164,7 +193,10 @@ function buildPiMcpConfigDocument(servers, onRename) {
                 // already has cached tool metadata. A new session has no cache for
                 // this URL, so the model can see fewer servers than the lease gave
                 // it. Eager mode lists tools before the first model prompt.
-                lifecycle: 'eager',
+                // A server whose preflight listing was seeded into Pi's cache is
+                // lazy: Pi registers it from the cache and connects only when the
+                // model calls one of its tools.
+                lifecycle: options.lazyServers?.has(name) ? 'lazy' : 'eager',
                 // The managed integrations gateway can wait for a cold pfMCP
                 // instance. Its own upstream deadline is 270 seconds, so Pi must
                 // wait long enough to receive the gateway's result or clear error.
@@ -275,6 +307,13 @@ class PiAdapter {
     sessions = new Map();
     piExecutablePath = null;
     onDataAvailable;
+    /**
+     * Pi's status is BUSY from `sendPrompt` until `agent_settled`, which Pi
+     * emits once after the whole agent loop (every tool round) has finished and
+     * after the turn's message events, so IDLE here means the turn is over and
+     * its parts are already buffered. See `CodingAgentAdapter.idleIsTerminal`.
+     */
+    idleIsTerminal = true;
     constructor(modelGateway) {
         this.modelGateway = modelGateway;
     }
@@ -389,7 +428,98 @@ class PiAdapter {
         (0, fs_1.chmodSync)(modelsPath, 0o600);
         return { apiKey: gateway.apiKey, providerModels: gateway.models ?? [] };
     }
-    buildMcpConfig(config) {
+    /** Replaceable in tests; the real loader needs the installed adapter. */
+    loadMcpCacheApi = pi_mcp_cache_seed_1.loadPiMetadataCacheApi;
+    /**
+     * Item 4: write the harness preflight's tool listings into Pi's metadata
+     * cache, so Pi does not repeat initialize + tools/list for those servers on
+     * this turn. Returns the harness server names that were seeded; only these
+     * may be lazy. Any failure seeds nothing and keeps every server eager.
+     */
+    seedMcpMetadataCache(config, document, slugs, seedOwner) {
+        const snapshot = config.mcpToolSnapshot;
+        const lazy = new Set();
+        if (!snapshot || !config.mcpServers)
+            return lazy;
+        const definitions = (document.mcpServers ?? {});
+        const skipped = {};
+        const candidates = [];
+        for (const [name, server] of Object.entries(config.mcpServers)) {
+            const slug = slugs.get(name) ?? name;
+            const definition = definitions[slug];
+            if (server.type === 'stdio' || !definition) {
+                skipped[slug] = 'not an http server';
+                continue;
+            }
+            const listing = snapshot.servers[name];
+            const refusal = (0, pi_mcp_cache_seed_1.piSeedRefusal)(definition, listing);
+            if (refusal || !listing) {
+                skipped[slug] = refusal ?? 'no preflight listing';
+                continue;
+            }
+            candidates.push({ name, slug, definition, listing });
+        }
+        let seeded = [];
+        // `cold_start_step` is one of the two event names the control-plane
+        // cold-start endpoint accepts (workflow-api handlers/runners.ts). Its
+        // presence in Cloud Logging shows this turn seeded Pi's cache.
+        const endSeed = candidates.length > 0 && config.turnId
+            ? new cold_start_steps_1.ColdStartSteps(config.taskId, config.turnId, (line) => {
+                console.log(line);
+                config.coldStartLog?.(line);
+            }).begin('pi_mcp_cache_seed')
+            : undefined;
+        if (candidates.length > 0) {
+            const agentDir = this.agentDirectory();
+            const api = this.loadMcpCacheApi(agentDir);
+            if (!api) {
+                for (const { slug } of candidates)
+                    skipped[slug] = 'pi-mcp-adapter cache module unavailable';
+            }
+            else {
+                // Another live session must not have the same slug with another
+                // hash: both share mcp-cache.json. See `claimPiMcpSlugs`.
+                const hashes = new Map();
+                for (const [slug, definition] of Object.entries(definitions)) {
+                    if (typeof definition?.url !== 'string')
+                        continue;
+                    try {
+                        hashes.set(slug, api.computeServerHash(JSON.parse(JSON.stringify(definition))));
+                    }
+                    catch {
+                        // Unhashable: it cannot be seeded either.
+                    }
+                }
+                const conflicts = (0, pi_mcp_cache_seed_1.claimPiMcpSlugs)(agentDir, seedOwner, hashes);
+                for (let index = candidates.length - 1; index >= 0; index--) {
+                    const { slug } = candidates[index];
+                    if (conflicts.has(slug)) {
+                        skipped[slug] = 'slug in use by a concurrent session';
+                        candidates.splice(index, 1);
+                    }
+                }
+                seeded = (0, pi_mcp_cache_seed_1.seedPiMcpMetadataCache)(agentDir, api, candidates);
+                for (const { name, slug } of candidates) {
+                    if (seeded.includes(slug))
+                        lazy.add(name);
+                    else
+                        skipped[slug] = 'cache write failed';
+                }
+            }
+        }
+        endSeed?.();
+        // The per-server detail goes to the harness log only: the control-plane
+        // endpoint refuses any other event name with a 400.
+        console.log(JSON.stringify({
+            event: 'pi_mcp_cache_seed',
+            sessionId: config.taskId,
+            turnId: config.turnId,
+            seeded,
+            eager: skipped
+        }));
+        return lazy;
+    }
+    buildMcpConfig(config, seedOwner) {
         if (!config.mcpServers || Object.keys(config.mcpServers).length === 0)
             return undefined;
         const dir = (0, path_1.join)((0, os_1.homedir)(), '.pf-agent-harness', 'pi-mcp');
@@ -398,9 +528,19 @@ class PiAdapter {
         // Pi forwards MCP tools to the model as <server>_<tool> names, which most
         // providers cap at 64 characters. Sanitize server keys so a long display
         // name (e.g. "[Workflo] Organisation Workspace") cannot overflow the limit.
-        const document = buildPiMcpConfigDocument(config.mcpServers, (name, slug) => {
+        const slugs = new Map();
+        const onRename = (name, slug) => {
             console.warn(`[PiAdapter] Renamed MCP server "${name}" to "${slug}" to fit the provider 64-char tool name limit`);
+        };
+        let document = buildPiMcpConfigDocument(config.mcpServers, onRename, {
+            slugs
         });
+        const lazyServers = this.seedMcpMetadataCache(config, document, slugs, seedOwner);
+        if (lazyServers.size > 0) {
+            document = buildPiMcpConfigDocument(config.mcpServers, undefined, {
+                lazyServers
+            });
+        }
         (0, fs_1.writeFileSync)(path, `${JSON.stringify(document, null, 2)}\n`, {
             mode: 0o600
         });
@@ -562,6 +702,18 @@ class PiAdapter {
         }
     }
     async spawnSession(config, resumeId) {
+        // The slugs this process seeds are held until it stops (destroySession),
+        // or released here when it never starts.
+        const seedOwner = (0, crypto_1.randomUUID)();
+        try {
+            return await this.startPiProcess(config, seedOwner, resumeId);
+        }
+        catch (error) {
+            (0, pi_mcp_cache_seed_1.releasePiMcpSlugs)(this.agentDirectory(), seedOwner);
+            throw error;
+        }
+    }
+    async startPiProcess(config, seedOwner, resumeId) {
         const steps = config.turnId
             ? new cold_start_steps_1.ColdStartSteps(config.taskId, config.turnId, (line) => {
                 console.log(line);
@@ -571,7 +723,7 @@ class PiAdapter {
         const executable = await this.findPiExecutable();
         const gateway = this.installPeakfloGateway();
         const endMcpConfig = steps?.begin('mcp_config_write');
-        const mcpConfigPath = this.buildMcpConfig(config);
+        const mcpConfigPath = this.buildMcpConfig(config, seedOwner);
         endMcpConfig?.();
         const endSkills = steps?.begin('skills_install');
         const skills = this.buildSkillFiles(config);
@@ -617,6 +769,7 @@ class PiAdapter {
         const tempId = resumeId || (0, crypto_1.randomUUID)();
         const session = this.createSessionState(tempId, child, config, mcpConfigPath, skills.directory);
         session.devServerPolicyPath = devServerPolicyPath;
+        session.mcpSeedOwner = seedOwner;
         this.sessions.set(tempId, session);
         this.attachProcess(session);
         try {
@@ -679,6 +832,11 @@ class PiAdapter {
             this.onDataAvailable?.(session.id);
         });
         session.process.on('exit', (code, signal) => {
+            // A Pi process that has exited no longer writes mcp-cache.json, so its
+            // slugs are free even if destroySession is never reached.
+            if (session.mcpSeedOwner) {
+                (0, pi_mcp_cache_seed_1.releasePiMcpSlugs)(this.agentDirectory(), session.mcpSeedOwner);
+            }
             if (!session.closing && session.status === 'busy') {
                 session.status = 'error';
                 session.lastError = `Pi exited before the turn completed (${signal || `code ${code}`})`;
@@ -1491,7 +1649,10 @@ class PiAdapter {
             session.process.kill();
             return;
         }
-        await new Promise((resolve) => setTimeout(resolve, 1_000));
+        // Wait for Pi to exit, up to the grace period, instead of always sleeping
+        // the whole second: this runs at the end of every turn, before the final
+        // ingest, and Pi normally exits on SIGTERM in a few milliseconds.
+        await waitForExit(session.process, PI_TERMINATE_GRACE_MS);
         if (session.process.exitCode !== null)
             return;
         try {
@@ -1520,6 +1681,9 @@ class PiAdapter {
         session.pendingUiRequests.clear();
         await this.terminateProcess(session);
         this.sessions.delete(sessionId);
+        if (session.mcpSeedOwner) {
+            (0, pi_mcp_cache_seed_1.releasePiMcpSlugs)(this.agentDirectory(), session.mcpSeedOwner);
+        }
         if (session.mcpConfigPath && (0, fs_1.existsSync)(session.mcpConfigPath)) {
             (0, fs_1.unlinkSync)(session.mcpConfigPath);
         }

package/dist/adapters/pi-mcp-cache-seed.d.ts

@@ -0,0 +1,66 @@
+import type { McpServerToolListing } from '../runtime/mcp-toolset';
+/**
+ * Seed pi-mcp-adapter's metadata cache from the harness MCP preflight (item 4).
+ *
+ * WHAT pi-mcp-adapter 2.33.0 SUPPORTS (read from its published source):
+ * - `<agentDir>/mcp-cache.json`, `{ version: 1, servers: { <server>: entry } }`
+ *   (metadata-cache.ts). An entry is valid while `configHash` equals
+ *   `computeServerHash(definition)` and it is less than 7 days old, or less
+ *   than its `ttlMs`. The hash covers url and headers, not `lifecycle`.
+ * - At startup (init.ts) every server with a valid entry gets its tools from
+ *   the cache. Only `eager` and `keep-alive` servers connect at startup,
+ *   unless the cache FILE is missing: then every server connects.
+ * - A `lazy` server (the default) with a valid entry is registered from the
+ *   cache and connects only when the model first calls one of its tools. A
+ *   lazy server WITHOUT a valid entry gets no tools at all, so a server may be
+ *   lazy only when this module wrote a valid entry for it.
+ * - The namespace proxy tool for a server is re-derived from the cache file on
+ *   every tool-surface sync, so a seeded entry must stay valid for the turn.
+ *
+ * The hash and the serialisers come from the installed adapter itself
+ * (`pi-mcp-adapter/metadata-cache`, a public export), so the seeded entry is
+ * exactly what Pi would write. If the module cannot be loaded, nothing is
+ * seeded and every server stays eager, which is the previous behaviour.
+ *
+ * The file holds tool names, descriptions and schemas, and a hash of the
+ * server definition. Pi already writes the same data there after each eager
+ * connect. It never holds a token: the per-turn MCP token is added by the
+ * loopback proxy and is not in the Pi definition.
+ */
+export interface PiMetadataCacheApi {
+    computeServerHash(definition: Record<string, unknown>): string;
+    serializeTools(tools: unknown[]): unknown[];
+    serializeResources(resources: unknown[]): unknown[];
+}
+export declare const PI_MCP_CACHE_FILE = "mcp-cache.json";
+/** Where `pi install npm:pi-mcp-adapter@x` puts the adapter (Dockerfile). */
+export declare function piMcpAdapterDirectory(agentDir: string): string;
+/**
+ * Load the installed adapter's cache helpers. The module is ESM; Node 22.12+
+ * (the harness floor is 22.19) loads it with `require`.
+ */
+export declare function loadPiMetadataCacheApi(agentDir: string): PiMetadataCacheApi | null;
+/** Why a server cannot be seeded, or `null` when it can. */
+export declare function piSeedRefusal(definition: Record<string, unknown>, listing: McpServerToolListing | undefined): string | null;
+interface SeedCandidate {
+    /** The Pi server key (the sanitised slug). */
+    slug: string;
+    definition: Record<string, unknown>;
+    listing: McpServerToolListing;
+}
+/**
+ * Write valid entries for `candidates` into `<agentDir>/mcp-cache.json`,
+ * merging with the entries already there (as Pi does). Returns the slugs that
+ * were written; the caller must keep every other server eager.
+ */
+export declare function seedPiMcpMetadataCache(agentDir: string, api: PiMetadataCacheApi, candidates: readonly SeedCandidate[]): string[];
+/**
+ * Register `hashes` (slug -> config hash) for one live Pi process and return
+ * the slugs another live process holds with a different hash. Every slug is
+ * registered, also a conflicting one, because Pi writes an eager server's
+ * entry itself after it connects.
+ */
+export declare function claimPiMcpSlugs(agentDir: string, owner: string, hashes: ReadonlyMap<string, string>): Set<string>;
+/** Forget one Pi process's slugs, when it stops or fails to start. */
+export declare function releasePiMcpSlugs(agentDir: string, owner: string): void;
+export {};

package/dist/adapters/pi-mcp-cache-seed.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PI_MCP_CACHE_FILE = void 0;
+exports.piMcpAdapterDirectory = piMcpAdapterDirectory;
+exports.loadPiMetadataCacheApi = loadPiMetadataCacheApi;
+exports.piSeedRefusal = piSeedRefusal;
+exports.seedPiMcpMetadataCache = seedPiMcpMetadataCache;
+exports.claimPiMcpSlugs = claimPiMcpSlugs;
+exports.releasePiMcpSlugs = releasePiMcpSlugs;
+const fs_1 = require("fs");
+const path_1 = require("path");
+exports.PI_MCP_CACHE_FILE = 'mcp-cache.json';
+const PI_MCP_CACHE_VERSION = 1;
+/*
+ * SERVER CACHE HINTS (`ttlMs`, `cacheScope`) ARE NOT WRITTEN TO PI'S FILE.
+ *
+ * Measured: the harness preflight negotiates protocol 2026-07-28 and receives
+ * the workspace server's `tools/list` hint `ttlMs: 0, cacheScope: 'private'`.
+ * Pi 0.85.1 + pi-mcp-adapter 2.33.0 connect in the legacy era, never receive
+ * it, and write their own entry with no ttl. An entry with `ttlMs: 0` is
+ * invalid to Pi at once, which would leave a lazy server with no tools, and a
+ * short ttl would expire it during the turn.
+ *
+ * So the seeded entry is what Pi itself writes, and the harness honours the
+ * hint where it decides freshness: a listing is used for the turn that took it
+ * (as Pi's own eager connect would), and the per-session tool store reuses it
+ * on a later turn only while it is younger than its `ttlMs`. See
+ * `runtime/mcp-tool-store.ts`.
+ */
+const apiCache = new Map();
+/** Where `pi install npm:pi-mcp-adapter@x` puts the adapter (Dockerfile). */
+function piMcpAdapterDirectory(agentDir) {
+    return (0, path_1.join)(agentDir, 'npm', 'node_modules', 'pi-mcp-adapter');
+}
+/**
+ * Load the installed adapter's cache helpers. The module is ESM; Node 22.12+
+ * (the harness floor is 22.19) loads it with `require`.
+ */
+function loadPiMetadataCacheApi(agentDir) {
+    const modulePath = (0, path_1.join)(piMcpAdapterDirectory(agentDir), 'dist', 'metadata-cache.js');
+    if (apiCache.has(modulePath))
+        return apiCache.get(modulePath) ?? null;
+    let api = null;
+    try {
+        if ((0, fs_1.existsSync)(modulePath)) {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const loaded = require(modulePath);
+            if (typeof loaded.computeServerHash === 'function' &&
+                typeof loaded.serializeTools === 'function' &&
+                typeof loaded.serializeResources === 'function') {
+                api = loaded;
+            }
+        }
+    }
+    catch {
+        api = null;
+    }
+    apiCache.set(modulePath, api);
+    return api;
+}
+/** Why a server cannot be seeded, or `null` when it can. */
+function piSeedRefusal(definition, listing) {
+    if (!listing)
+        return 'no preflight listing';
+    if (typeof definition.url !== 'string' || definition.url !== listing.url)
+        return 'url changed';
+    // Pi interpolates `${VAR}` and `!command` in urls and headers inside its own
+    // process. Seed only definitions with nothing to interpolate.
+    if (definition.url.includes('$'))
+        return 'url uses interpolation';
+    const headers = definition.headers;
+    if (headers !== undefined &&
+        (typeof headers !== 'object' ||
+            headers === null ||
+            Object.keys(headers).length > 0))
+        return 'server has headers';
+    return null;
+}
+/**
+ * Write valid entries for `candidates` into `<agentDir>/mcp-cache.json`,
+ * merging with the entries already there (as Pi does). Returns the slugs that
+ * were written; the caller must keep every other server eager.
+ */
+function seedPiMcpMetadataCache(agentDir, api, candidates) {
+    const entries = {};
+    for (const { slug, definition, listing } of candidates) {
+        try {
+            // Hash the definition as Pi reads it: from JSON.
+            const parsed = JSON.parse(JSON.stringify(definition));
+            entries[slug] = {
+                configHash: api.computeServerHash(parsed),
+                tools: api.serializeTools(listing.tools),
+                resources: api.serializeResources(listing.resources),
+                ...(listing.instructions !== undefined
+                    ? { instructions: listing.instructions }
+                    : {}),
+                cachedAt: listing.listedAt
+            };
+        }
+        catch {
+            // This server stays eager.
+        }
+    }
+    const slugs = Object.keys(entries);
+    if (slugs.length === 0)
+        return [];
+    const path = (0, path_1.join)(agentDir, exports.PI_MCP_CACHE_FILE);
+    let servers = {};
+    try {
+        const existing = JSON.parse((0, fs_1.readFileSync)(path, 'utf8'));
+        if (existing?.version === PI_MCP_CACHE_VERSION &&
+            existing.servers &&
+            typeof existing.servers === 'object') {
+            servers = existing.servers;
+        }
+    }
+    catch {
+        // Missing or unreadable: start a new file, as Pi does.
+    }
+    try {
+        (0, fs_1.mkdirSync)(agentDir, { recursive: true });
+        const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+        (0, fs_1.writeFileSync)(temporaryPath, JSON.stringify({
+            version: PI_MCP_CACHE_VERSION,
+            servers: { ...servers, ...entries }
+        }), { mode: 0o600 });
+        (0, fs_1.chmodSync)(temporaryPath, 0o600);
+        (0, fs_1.renameSync)(temporaryPath, path);
+    }
+    catch {
+        return [];
+    }
+    return slugs;
+}
+/*
+ * CONCURRENT SESSIONS SHARE ONE CACHE FILE (item 1(b), #2112 open risk).
+ *
+ * Every Pi process of this harness uses the same `<agentDir>/mcp-cache.json`,
+ * keyed by server slug, and re-reads it on every tool-surface sync. The
+ * loopback URL differs per session, so two live sessions with the same slug
+ * have different config hashes. If both were seeded, the second write would
+ * make the first session's entry invalid and its lazy server would lose its
+ * tools in the middle of a turn.
+ *
+ * The file cannot be split without a per-session agent directory (Pi's
+ * settings, extension install and auth all live there), so this registry
+ * serialises the conflict instead: a turn seeds a slug only when no other
+ * live Pi process of this harness holds that slug with a different hash. A
+ * conflicting server stays eager for that turn, which is the previous
+ * behaviour. The registry is per agent directory and per harness process; the
+ * sandbox runs one session at a time, so it only matters on a desktop runner
+ * with several sessions.
+ */
+const liveSlugs = new Map();
+/**
+ * Register `hashes` (slug -> config hash) for one live Pi process and return
+ * the slugs another live process holds with a different hash. Every slug is
+ * registered, also a conflicting one, because Pi writes an eager server's
+ * entry itself after it connects.
+ */
+function claimPiMcpSlugs(agentDir, owner, hashes) {
+    let owners = liveSlugs.get(agentDir);
+    if (!owners) {
+        owners = new Map();
+        liveSlugs.set(agentDir, owners);
+    }
+    const conflicts = new Set();
+    for (const [other, slugs] of owners) {
+        if (other === owner)
+            continue;
+        for (const [slug, hash] of hashes) {
+            const held = slugs.get(slug);
+            if (held !== undefined && held !== hash)
+                conflicts.add(slug);
+        }
+    }
+    owners.set(owner, new Map(hashes));
+    return conflicts;
+}
+/** Forget one Pi process's slugs, when it stops or fails to start. */
+function releasePiMcpSlugs(agentDir, owner) {
+    const owners = liveSlugs.get(agentDir);
+    if (!owners)
+        return;
+    owners.delete(owner);
+    if (owners.size === 0)
+        liveSlugs.delete(agentDir);
+}

package/dist/contract.d.ts

@@ -178,7 +178,7 @@ export declare const ROUTES: {
     readonly register: () => string;
     /** Bearer: runner credential. 30s period. */
     readonly heartbeat: (runnerId: string) => string;
-    /** Bearer: runner credential. Best-effort timing event; no transcript data. */
+    /** Bearer: runner credential. Best-effort timing events of one turn, batched; no transcript data. */
     readonly coldStart: (runnerId: string) => string;
     /**
      * Bearer: runner credential. Bounded long-poll: 204 idle, 200 with work.

package/dist/contract.js

@@ -215,7 +215,7 @@ exports.ROUTES = {
     register: () => '/api/runners/register',
     /** Bearer: runner credential. 30s period. */
     heartbeat: (runnerId) => `/api/runners/${encodeURIComponent(runnerId)}/heartbeat`,
-    /** Bearer: runner credential. Best-effort timing event; no transcript data. */
+    /** Bearer: runner credential. Best-effort timing events of one turn, batched; no transcript data. */
     coldStart: (runnerId) => `/api/runners/${encodeURIComponent(runnerId)}/cold-start`,
     /**
      * Bearer: runner credential. Bounded long-poll: 204 idle, 200 with work.

package/dist/control-plane.d.ts

@@ -1,3 +1,4 @@
+import type { ColdStartBatchBody } from './runtime/cold-start-batch';
 import { ControlPlaneErrorBody, CredentialRotateResponse, DeregisterResponse, IngestRequest, IngestResponse, KnowledgeDownloadResponse, KnowledgeFilesResponse, LeaseRenewResponse, LeaseResponse, RunnerCapabilities, RunnerHeartbeatResponse, RunnerRegisterResponse, RunnerRuntime, RunnerStatus, SessionHistoryResponse } from './types';
 export declare class ControlPlaneError extends Error {
     readonly status: number;
@@ -81,8 +82,14 @@ export declare class ControlPlaneClient {
     /** Used only for a private IPC handoff to the baked sandbox supervisor. */
     getRunnerCredential(): string | null;
     getRunnerId(): string | null;
-    /** Diagnostics must never delay a turn. The caller handles any failure. */
-    reportColdStart(line: string): Promise<void>;
+    /**
+     * All cold-start timing events of one turn in ONE request. Diagnostics
+     * must never delay a turn; the caller handles any failure.
+     *
+     * This replaced one POST per step. The control plane accepts both shapes,
+     * so an older harness on an existing sandbox keeps working.
+     */
+    reportColdStartBatch(body: ColdStartBatchBody): Promise<void>;
     /**
      * Give the lease-renewal worker the minimum information it needs.
      *