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

package/dist/control-plane.js

@@ -114,15 +114,23 @@ class ControlPlaneClient {
     getRunnerId() {
         return this.runnerId;
     }
-    /** Diagnostics must never delay a turn. The caller handles any failure. */
-    async reportColdStart(line) {
+    /**
+     * 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.
+     */
+    async reportColdStartBatch(body) {
         if (!this.runnerId || !this.runnerCredential)
             return;
+        if (body.events.length === 0)
+            return;
         await this.send({
             method: 'POST',
             path: contract_1.ROUTES.coldStart(this.runnerId),
             token: this.runnerCredential,
-            body: JSON.parse(line),
+            body,
             timeoutMs: 2_000
         });
     }

package/dist/harness.d.ts

@@ -249,6 +249,8 @@ export declare class Harness {
     private readonly activeLeaseIds;
     /** Renewal workers that must receive a credential rotation in flight. */
     private readonly activeRenewals;
+    /** Cold-start timing buffered per running turn; sent once at turn end. */
+    private readonly coldStartBatches;
     /** commandIds already applied. `SessionCommand` is idempotent by contract. */
     private readonly appliedCommands;
     /** Prune lease-bound command IDs when their session turn ends. */
@@ -473,6 +475,7 @@ export declare class Harness {
     private observeSandboxToolsPin;
     /** Stop once. A failed install is then the supervisor's terminal decision. */
     private requestUpgrade;
+    private newColdStartBatch;
     /**
      * Run one leased turn.
      *

package/dist/harness.js

@@ -18,6 +18,7 @@ const health_1 = require("./health");
 const model_probe_1 = require("./model-probe");
 const ports_default_1 = require("./ports-default");
 const browser_takeover_1 = require("./runtime/browser-takeover");
+const cold_start_batch_1 = require("./runtime/cold-start-batch");
 const knowledge_tools_1 = require("./runtime/knowledge-tools");
 const lease_renewal_1 = require("./runtime/lease-renewal");
 const mcp_auth_proxy_1 = require("./runtime/mcp-auth-proxy");
@@ -200,7 +201,9 @@ class Harness {
     mcpCheckState = {
         checked: new Map(),
         failed: new Map(),
-        shownNotices: new Set()
+        shownNotices: new Set(),
+        // Item 1(b): per-session MCP tool listings, reused on warm turns.
+        toolsets: new Map()
     };
     startedAt = Date.now();
     status = 'starting';
@@ -265,6 +268,8 @@ class Harness {
     activeLeaseIds = new Map();
     /** Renewal workers that must receive a credential rotation in flight. */
     activeRenewals = new Set();
+    /** Cold-start timing buffered per running turn; sent once at turn end. */
+    coldStartBatches = new Set();
     /** commandIds already applied. `SessionCommand` is idempotent by contract. */
     appliedCommands = new Set();
     /** Prune lease-bound command IDs when their session turn ends. */
@@ -515,6 +520,11 @@ class Harness {
         for (const controller of this.active.values()) {
             controller.abort();
         }
+        // Send buffered turn timing while the credential is still valid.
+        // Deregistration below revokes it. Each send has a 2 s timeout.
+        const coldStarts = Array.from(this.coldStartBatches);
+        this.coldStartBatches.clear();
+        await Promise.all(coldStarts.map((batch) => batch.flush()));
         /*
          * A DURABLE RUNNER DOES NOT DEREGISTER.
          *
@@ -1565,7 +1575,9 @@ class Harness {
                 durationMs: Date.now() - pollStartedAt
             });
             log(leaseReceived);
-            void this.client.reportColdStart(leaseReceived).catch(() => undefined);
+            // Buffered, not sent: the whole turn's timing goes out as ONE request.
+            const coldStart = this.newColdStartBatch(lease);
+            coldStart.add(leaseReceived);
             this.observeHarnessPin(lease.harnessVersion);
             this.observeSandboxToolsPin(lease.sandboxToolsVersion);
             // Protocol 3 uses a short visibility window until the runner confirms
@@ -1593,10 +1605,12 @@ class Harness {
                 }
             }
             if (!leaseAcknowledged) {
+                this.coldStartBatches.delete(coldStart);
+                void coldStart.flush();
                 await sleep(LEASE_ERROR_BACKOFF_MS);
                 continue;
             }
-            void this.runLeasedTurn(lease);
+            void this.runLeasedTurn(lease, coldStart);
         }
         await this.stop();
     }
@@ -1680,6 +1694,11 @@ class Harness {
         this.fatal = new UpgradeRequestedError(harnessVersion);
         await this.stop({ preserveRegistration: true });
     }
+    newColdStartBatch(lease) {
+        const batch = new cold_start_batch_1.ColdStartBatch(lease.session.sessionId, lease.session.turnId, (body) => this.client.reportColdStartBatch(body));
+        this.coldStartBatches.add(batch);
+        return batch;
+    }
     /**
      * Run one leased turn.
      *
@@ -1688,7 +1707,7 @@ class Harness {
      * throws must not end the lease loop, or one bad session would take the whole
      * runner offline.
      */
-    async runLeasedTurn(lease) {
+    async runLeasedTurn(lease, coldStart = this.newColdStartBatch(lease)) {
         const { sessionId } = lease.session;
         // The exact loopback-proxy targets this session will reach. Keyed on these
         // urls, this session's MCP token cannot be overwritten or revoked by a
@@ -1852,9 +1871,7 @@ class Harness {
             secrets: this.secrets,
             events: this.events,
             telemetry: this.telemetry,
-            coldStartLog: (line) => {
-                void this.client.reportColdStart(line).catch(() => undefined);
-            },
+            coldStartLog: (line) => coldStart.add(line),
             notifier: this.notifier,
             artifacts: this.artifacts,
             conversation: this.conversation,
@@ -1938,6 +1955,10 @@ class Harness {
         finally {
             renewal.stop();
             this.activeRenewals.delete(renewal);
+            // ONE telemetry request for the whole turn, sent before the git
+            // preservation below so slow pushes do not delay it. Fire-and-forget.
+            this.coldStartBatches.delete(coldStart);
+            void coldStart.flush();
             let workProtected = true;
             if ((this.options.autoCommitDirtyWorktree ??
                 this.options.runtime === 'sandbox') &&

package/dist/runtime/cold-start-batch.d.ts

@@ -0,0 +1,36 @@
+/**
+ * One cold-start telemetry POST per turn instead of one per step.
+ *
+ * `ColdStartSteps` and the Pi adapter emit 13–15 timing lines per turn. Each
+ * used to become its own `POST /runners/:id/cold-start` (auth + turn lookup on
+ * the server every time). This buffer collects the lines for ONE turn and the
+ * harness sends them as a single batch when the turn ends, or when the
+ * harness stops. It is diagnostics only: it never throws, never blocks a turn
+ * and never retries.
+ */
+/** Events the control plane records. Anything else stays in the local log. */
+export declare const COLD_START_EVENTS: ReadonlySet<string>;
+/** Mirrors the server limit in `services/coding-agents/cold-start-telemetry.ts`. */
+export declare const COLD_START_BATCH_MAX_EVENTS = 64;
+export interface ColdStartBatchBody {
+    sessionId: string;
+    turnId: string;
+    events: Array<Record<string, unknown>>;
+}
+export declare class ColdStartBatch {
+    readonly sessionId: string;
+    readonly turnId: string;
+    private readonly send;
+    /** Lines that arrive after the turn-end flush are coalesced this long. */
+    private readonly lateFlushMs;
+    private events;
+    private flushed;
+    private lateTimer;
+    constructor(sessionId: string, turnId: string, send: (body: ColdStartBatchBody) => Promise<void>, 
+    /** Lines that arrive after the turn-end flush are coalesced this long. */
+    lateFlushMs?: number);
+    /** Buffer one JSON line from `ColdStartSteps`. Never throws. */
+    add(line: string): void;
+    /** Send everything buffered as ONE request. Resolves; never rejects. */
+    flush(): Promise<void>;
+}

package/dist/runtime/cold-start-batch.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * One cold-start telemetry POST per turn instead of one per step.
+ *
+ * `ColdStartSteps` and the Pi adapter emit 13–15 timing lines per turn. Each
+ * used to become its own `POST /runners/:id/cold-start` (auth + turn lookup on
+ * the server every time). This buffer collects the lines for ONE turn and the
+ * harness sends them as a single batch when the turn ends, or when the
+ * harness stops. It is diagnostics only: it never throws, never blocks a turn
+ * and never retries.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ColdStartBatch = exports.COLD_START_BATCH_MAX_EVENTS = exports.COLD_START_EVENTS = void 0;
+/** Events the control plane records. Anything else stays in the local log. */
+exports.COLD_START_EVENTS = new Set([
+    'cold_start_step',
+    'cold_start_summary',
+    'model_catalogue_deferred'
+]);
+/** Mirrors the server limit in `services/coding-agents/cold-start-telemetry.ts`. */
+exports.COLD_START_BATCH_MAX_EVENTS = 64;
+class ColdStartBatch {
+    sessionId;
+    turnId;
+    send;
+    lateFlushMs;
+    events = [];
+    flushed = false;
+    lateTimer = null;
+    constructor(sessionId, turnId, send, 
+    /** Lines that arrive after the turn-end flush are coalesced this long. */
+    lateFlushMs = 1_000) {
+        this.sessionId = sessionId;
+        this.turnId = turnId;
+        this.send = send;
+        this.lateFlushMs = lateFlushMs;
+    }
+    /** Buffer one JSON line from `ColdStartSteps`. Never throws. */
+    add(line) {
+        try {
+            const event = JSON.parse(line);
+            if (!event || typeof event !== 'object' || Array.isArray(event))
+                return;
+            const record = event;
+            if (typeof record.event !== 'string' ||
+                !exports.COLD_START_EVENTS.has(record.event) ||
+                record.sessionId !== this.sessionId ||
+                record.turnId !== this.turnId) {
+                return;
+            }
+            // The batch carries the ids once; per-event copies are redundant bytes.
+            const rest = { ...record };
+            delete rest.sessionId;
+            delete rest.turnId;
+            this.events.push(rest);
+            if (this.events.length >= exports.COLD_START_BATCH_MAX_EVENTS) {
+                void this.flush();
+            }
+            else if (this.flushed && !this.lateTimer) {
+                // A step that ends after the turn-end flush (rare) is still sent,
+                // coalesced with any others that follow it.
+                this.lateTimer = setTimeout(() => {
+                    this.lateTimer = null;
+                    void this.flush();
+                }, this.lateFlushMs);
+                this.lateTimer.unref?.();
+            }
+        }
+        catch {
+            // A diagnostic sink must never stop an agent turn.
+        }
+    }
+    /** Send everything buffered as ONE request. Resolves; never rejects. */
+    flush() {
+        this.flushed = true;
+        if (this.lateTimer) {
+            clearTimeout(this.lateTimer);
+            this.lateTimer = null;
+        }
+        if (this.events.length === 0)
+            return Promise.resolve();
+        const events = this.events;
+        this.events = [];
+        try {
+            return this.send({
+                sessionId: this.sessionId,
+                turnId: this.turnId,
+                events
+            }).catch(() => undefined);
+        }
+        catch {
+            return Promise.resolve();
+        }
+    }
+}
+exports.ColdStartBatch = ColdStartBatch;

package/dist/runtime/mcp-preflight.d.ts

@@ -1,3 +1,4 @@
+import type { McpServerToolListing } from './mcp-toolset';
 export interface UnavailableMcpServer {
     name: string;
     reason: string;
@@ -14,8 +15,21 @@ export interface FailedMcpCheck {
  * Check leased HTTP servers and use the caller's bounded, shared cache.
  * A successful check is only a startup hint. The gateway checks live access
  * on each tool call, even when a cached success skips this probe.
+ *
+ * When `listings` is given, a server that was probed keeps its `tools/list`
+ * result there (all pages: the client aggregates them when no cursor is
+ * passed), plus `resources/list` when the server advertises resources. The
+ * Pi backend seeds its MCP metadata cache from it, so Pi does not repeat the
+ * handshake on this turn. A server skipped by the success cache, or whose
+ * resource listing failed, has no listing.
  */
 export declare function verifyMcpServers(servers: Record<string, {
     type: string;
     url?: string;
-}>, signal?: AbortSignal, successful?: Map<string, number>, failed?: Map<string, FailedMcpCheck>): Promise<UnavailableMcpServer[]>;
+}>, signal?: AbortSignal, successful?: Map<string, number>, failed?: Map<string, FailedMcpCheck>, listings?: Map<string, McpServerToolListing>, 
+/**
+ * Servers to probe and list even inside the success-cache window: their
+ * stored listing is no longer valid (item 1(b)), so without a fresh one Pi
+ * would fall back to its own eager handshake.
+ */
+relist?: ReadonlySet<string>): Promise<UnavailableMcpServer[]>;

package/dist/runtime/mcp-preflight.js

@@ -16,12 +16,45 @@ function safeHttpStatus(cause) {
     const match = String(cause).match(/^(?:Error:\s*)?HTTP\s+([45]\d\d)\b/i);
     return match ? Number(match[1]) : null;
 }
+function toolListing(url, client, result, resources, resourcesAdvertised) {
+    const hints = result;
+    const instructions = client.getInstructions?.();
+    return {
+        url,
+        tools: (result.tools ?? []).filter((tool) => typeof tool?.name === 'string' && tool.name.length > 0),
+        resources,
+        resourcesAdvertised,
+        ...(typeof instructions === 'string' ? { instructions } : {}),
+        ...(typeof hints.ttlMs === 'number' &&
+            Number.isSafeInteger(hints.ttlMs) &&
+            hints.ttlMs >= 0
+            ? { ttlMs: hints.ttlMs }
+            : {}),
+        ...(hints.cacheScope === 'public' || hints.cacheScope === 'private'
+            ? { cacheScope: hints.cacheScope }
+            : {}),
+        listedAt: Date.now()
+    };
+}
 /**
  * Check leased HTTP servers and use the caller's bounded, shared cache.
  * A successful check is only a startup hint. The gateway checks live access
  * on each tool call, even when a cached success skips this probe.
+ *
+ * When `listings` is given, a server that was probed keeps its `tools/list`
+ * result there (all pages: the client aggregates them when no cursor is
+ * passed), plus `resources/list` when the server advertises resources. The
+ * Pi backend seeds its MCP metadata cache from it, so Pi does not repeat the
+ * handshake on this turn. A server skipped by the success cache, or whose
+ * resource listing failed, has no listing.
+ */
+async function verifyMcpServers(servers, signal, successful, failed, listings, 
+/**
+ * Servers to probe and list even inside the success-cache window: their
+ * stored listing is no longer valid (item 1(b)), so without a fresh one Pi
+ * would fall back to its own eager handshake.
  */
-async function verifyMcpServers(servers, signal, successful, failed) {
+relist) {
     const results = await Promise.all(Object.entries(servers).map(async ([name, server]) => {
         if (server.type !== 'http' || !server.url)
             return null;
@@ -30,6 +63,7 @@ async function verifyMcpServers(servers, signal, successful, failed) {
         const key = `${name}\n${server.url}`;
         const checkedAt = successful?.get(key);
         if (checkedAt !== undefined &&
+            !relist?.has(name) &&
             Date.now() - checkedAt < SUCCESS_CACHE_TTL_MS)
             return null;
         const priorFailure = failed?.get(key);
@@ -55,7 +89,25 @@ async function verifyMcpServers(servers, signal, successful, failed) {
                 : deadline;
             try {
                 await client.connect(new client_1.StreamableHTTPClientTransport(new URL(server.url)), { timeout: 10_000, signal: requestSignal });
-                await client.listTools({}, { timeout: 10_000, signal: requestSignal });
+                const listed = await client.listTools({}, { timeout: 10_000, signal: requestSignal });
+                if (listings) {
+                    const resourcesAdvertised = Boolean(client.getServerCapabilities?.()?.resources);
+                    let resources = [];
+                    if (resourcesAdvertised) {
+                        // Pi lists resources on connect. A seeded entry without them
+                        // would hide the server's `read_*` tools, so a failed resource
+                        // listing leaves the server unseeded (Pi then connects as before).
+                        resources = await client
+                            .listResources({}, { timeout: 10_000, signal: requestSignal })
+                            .then((result) => (result.resources ?? []))
+                            .catch(() => null);
+                        if (signal?.aborted)
+                            throw new Error('MCP check was cancelled.');
+                    }
+                    if (resources) {
+                        listings.set(name, toolListing(server.url, client, listed, resources, resourcesAdvertised));
+                    }
+                }
                 successful?.set(key, Date.now());
                 failed?.delete(key);
                 if (successful && successful.size > MAX_CACHE_ENTRIES) {

package/dist/runtime/mcp-tool-store.d.ts

@@ -0,0 +1,79 @@
+import { type McpServerToolListing, type McpToolsetMember } from './mcp-toolset';
+/**
+ * ITEM 1(b): THE PER-SESSION MCP TOOL STORE.
+ *
+ * Pi is started again on every turn. Without this store a warm turn cannot
+ * seed Pi's metadata cache: the 5-minute preflight success cache skips the
+ * probe, so nothing is listed, every server stays eager and Pi repeats the
+ * whole MCP handshake before the first prompt (~19.6 s on the baseline warm
+ * turn). The store keeps the last listing of each server per session and
+ * gives it back while the toolset is unchanged, so a warm turn sends no MCP
+ * request before the prompt.
+ *
+ * WHEN A LISTING IS REUSED. Only while all of these still hold:
+ * - the lease carries `mcpToolScope` (the speaker and the Space whose live
+ *   permissions the gateway applies). An older control plane does not send
+ *   it, and then nothing is reused, so a list never crosses speakers;
+ * - the scope is the one the listing was taken under. A different speaker in
+ *   a shared chat drops every stored listing of the session;
+ * - the server's own fingerprint (name, upstream URL, allowlist) is the same;
+ * - the server is still configured at the URL the listing was taken from;
+ * - the listing is younger than `MCP_TOOL_STORE_MAX_AGE_MS` and than the
+ *   server's own `ttlMs` hint. A `ttlMs: 0` listing (the workspace server
+ *   sends one) is never reused: that server is listed again by the preflight
+ *   on every turn, two requests in the 2026-07-28 era instead of Pi's four,
+ *   until the gateway declares a non-zero private ttl (PR follow-up).
+ *
+ * Any other server is checked by the preflight as before. A server that had a
+ * stored listing which is no longer valid is re-listed even inside the success
+ * cache window, so the changed server is seeded again rather than left eager.
+ *
+ * The store holds only tool metadata (names, descriptions, schemas) and never
+ * a token. It is advisory: the gateway still checks every `tools/call`.
+ */
+/**
+ * How long a stored listing may be reused. Longer than the 5-minute preflight
+ * success cache, so a turn a few minutes after the last one skips the
+ * preflight too (the baseline turn `91c442db` came 6 minutes after the one
+ * before it and spent 9.7 s in it). Short, because a catalogue change that is
+ * not in the lease (an app connected, or a grant revoked, for the same speaker)
+ * shows only after this; Pi also replaces the cached tools as soon as it
+ * connects to a server. A revoked tool can stay listed for up to this long,
+ * but the gateway refuses the call: a stale name, never extra access.
+ */
+export declare const MCP_TOOL_STORE_MAX_AGE_MS: number;
+interface StoredServer {
+    memberKey: string;
+    listing: McpServerToolListing;
+}
+interface StoredToolset {
+    scopeKey: string;
+    servers: Map<string, StoredServer>;
+}
+/** Shared by the harness across the per-turn runners, keyed by session id. */
+export type McpToolStore = Map<string, StoredToolset>;
+export type McpToolScope = Record<string, string>;
+export interface McpToolStorePlan {
+    /** Stored listings that this turn uses instead of a preflight. */
+    reused: Record<string, McpServerToolListing>;
+    /** Servers whose stored listing was dropped; list them again. */
+    relist: Set<string>;
+    /** Why each dropped listing was dropped (server names only). */
+    dropped: Record<string, string>;
+}
+/**
+ * Decide which servers this turn can take from the store. Drops every entry
+ * that is no longer valid, so a later turn cannot reuse it either.
+ */
+export declare function planMcpToolReuse(store: McpToolStore, sessionId: string, members: readonly McpToolsetMember[], scope: McpToolScope | null, configured: Readonly<Record<string, {
+    type: string;
+    url?: string;
+}>>, now?: number): McpToolStorePlan;
+/**
+ * Keep this turn's fresh listings for the next turn of the session. Nothing is
+ * kept without a scope. A `ttlMs: 0` listing is kept only as a marker: it is
+ * never reused, but the next turn knows to list that server again rather than
+ * leave it to Pi's eager handshake.
+ */
+export declare function rememberMcpToolListings(store: McpToolStore, sessionId: string, members: readonly McpToolsetMember[], scope: McpToolScope | null, listings: ReadonlyMap<string, McpServerToolListing>): string[];
+export {};

package/dist/runtime/mcp-tool-store.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP_TOOL_STORE_MAX_AGE_MS = void 0;
+exports.planMcpToolReuse = planMcpToolReuse;
+exports.rememberMcpToolListings = rememberMcpToolListings;
+const mcp_toolset_1 = require("./mcp-toolset");
+/**
+ * ITEM 1(b): THE PER-SESSION MCP TOOL STORE.
+ *
+ * Pi is started again on every turn. Without this store a warm turn cannot
+ * seed Pi's metadata cache: the 5-minute preflight success cache skips the
+ * probe, so nothing is listed, every server stays eager and Pi repeats the
+ * whole MCP handshake before the first prompt (~19.6 s on the baseline warm
+ * turn). The store keeps the last listing of each server per session and
+ * gives it back while the toolset is unchanged, so a warm turn sends no MCP
+ * request before the prompt.
+ *
+ * WHEN A LISTING IS REUSED. Only while all of these still hold:
+ * - the lease carries `mcpToolScope` (the speaker and the Space whose live
+ *   permissions the gateway applies). An older control plane does not send
+ *   it, and then nothing is reused, so a list never crosses speakers;
+ * - the scope is the one the listing was taken under. A different speaker in
+ *   a shared chat drops every stored listing of the session;
+ * - the server's own fingerprint (name, upstream URL, allowlist) is the same;
+ * - the server is still configured at the URL the listing was taken from;
+ * - the listing is younger than `MCP_TOOL_STORE_MAX_AGE_MS` and than the
+ *   server's own `ttlMs` hint. A `ttlMs: 0` listing (the workspace server
+ *   sends one) is never reused: that server is listed again by the preflight
+ *   on every turn, two requests in the 2026-07-28 era instead of Pi's four,
+ *   until the gateway declares a non-zero private ttl (PR follow-up).
+ *
+ * Any other server is checked by the preflight as before. A server that had a
+ * stored listing which is no longer valid is re-listed even inside the success
+ * cache window, so the changed server is seeded again rather than left eager.
+ *
+ * The store holds only tool metadata (names, descriptions, schemas) and never
+ * a token. It is advisory: the gateway still checks every `tools/call`.
+ */
+/**
+ * How long a stored listing may be reused. Longer than the 5-minute preflight
+ * success cache, so a turn a few minutes after the last one skips the
+ * preflight too (the baseline turn `91c442db` came 6 minutes after the one
+ * before it and spent 9.7 s in it). Short, because a catalogue change that is
+ * not in the lease (an app connected, or a grant revoked, for the same speaker)
+ * shows only after this; Pi also replaces the cached tools as soon as it
+ * connects to a server. A revoked tool can stay listed for up to this long,
+ * but the gateway refuses the call: a stale name, never extra access.
+ */
+exports.MCP_TOOL_STORE_MAX_AGE_MS = 15 * 60_000;
+const MAX_STORED_SESSIONS = 256;
+function memberKey(member) {
+    return (0, mcp_toolset_1.mcpToolsetFingerprint)([member]);
+}
+function scopeKeyOf(scope) {
+    return (0, mcp_toolset_1.mcpToolsetFingerprint)([], scope);
+}
+function reusableUntil(listing) {
+    const ttl = listing.ttlMs === undefined
+        ? exports.MCP_TOOL_STORE_MAX_AGE_MS
+        : Math.min(listing.ttlMs, exports.MCP_TOOL_STORE_MAX_AGE_MS);
+    return listing.listedAt + ttl;
+}
+/**
+ * Decide which servers this turn can take from the store. Drops every entry
+ * that is no longer valid, so a later turn cannot reuse it either.
+ */
+function planMcpToolReuse(store, sessionId, members, scope, configured, now = Date.now()) {
+    const plan = { reused: {}, relist: new Set(), dropped: {} };
+    const stored = store.get(sessionId);
+    if (!stored)
+        return plan;
+    const dropAll = (reason) => {
+        for (const name of stored.servers.keys()) {
+            plan.relist.add(name);
+            plan.dropped[name] = reason;
+        }
+        store.delete(sessionId);
+    };
+    if (!scope) {
+        dropAll('lease has no tool scope');
+        return plan;
+    }
+    if (stored.scopeKey !== scopeKeyOf(scope)) {
+        dropAll('speaker or space changed');
+        return plan;
+    }
+    const current = new Map(members.map((member) => [member.name, member]));
+    for (const [name, entry] of [...stored.servers]) {
+        const member = current.get(name);
+        let reason = null;
+        if (!member)
+            reason = 'server removed';
+        else if (entry.memberKey !== memberKey(member))
+            reason = 'server changed';
+        else if (configured[name]?.type !== 'http')
+            reason = 'server not configured';
+        else if (configured[name]?.url !== entry.listing.url)
+            reason = 'url changed';
+        else if (now >= reusableUntil(entry.listing))
+            reason =
+                entry.listing.ttlMs !== undefined &&
+                    entry.listing.ttlMs < exports.MCP_TOOL_STORE_MAX_AGE_MS
+                    ? 'server ttl'
+                    : 'expired';
+        if (reason) {
+            stored.servers.delete(name);
+            plan.dropped[name] = reason;
+            if (member)
+                plan.relist.add(name);
+            continue;
+        }
+        plan.reused[name] = entry.listing;
+    }
+    // A reuse counts as use: move the session to the newest end.
+    store.delete(sessionId);
+    if (stored.servers.size > 0)
+        store.set(sessionId, stored);
+    return plan;
+}
+/**
+ * Keep this turn's fresh listings for the next turn of the session. Nothing is
+ * kept without a scope. A `ttlMs: 0` listing is kept only as a marker: it is
+ * never reused, but the next turn knows to list that server again rather than
+ * leave it to Pi's eager handshake.
+ */
+function rememberMcpToolListings(store, sessionId, members, scope, listings) {
+    if (!scope)
+        return [];
+    const scopeKey = scopeKeyOf(scope);
+    let stored = store.get(sessionId);
+    if (!stored || stored.scopeKey !== scopeKey) {
+        stored = { scopeKey, servers: new Map() };
+    }
+    const current = new Map(members.map((member) => [member.name, member]));
+    const kept = [];
+    for (const [name, listing] of listings) {
+        const member = current.get(name);
+        if (!member)
+            continue;
+        stored.servers.set(name, { memberKey: memberKey(member), listing });
+        kept.push(name);
+    }
+    // Most recently used last, so the oldest session is evicted first.
+    store.delete(sessionId);
+    if (stored.servers.size > 0)
+        store.set(sessionId, stored);
+    while (store.size > MAX_STORED_SESSIONS) {
+        store.delete(store.keys().next().value);
+    }
+    return kept;
+}

package/dist/runtime/mcp-toolset.d.ts

@@ -0,0 +1,51 @@
+/**
+ * One MCP server's tool listing, taken by the harness preflight.
+ *
+ * The values are what the server returned for `tools/list` (all pages) and,
+ * when the server advertises resources, `resources/list`. They contain no
+ * credential: the per-turn MCP token is added by the loopback proxy and never
+ * appears in a URL, a header or a listing here.
+ */
+export interface McpServerToolListing {
+    /** The exact URL the listing was taken from (the loopback proxy URL). */
+    url: string;
+    tools: Array<Record<string, unknown> & {
+        name: string;
+    }>;
+    resources: Array<Record<string, unknown>>;
+    /** True when the server advertises the resources capability. */
+    resourcesAdvertised: boolean;
+    instructions?: string;
+    /** Server cache hints from the first `tools/list` page, when present. */
+    ttlMs?: number;
+    cacheScope?: 'public' | 'private';
+    listedAt: number;
+}
+/**
+ * The tool listings for one toolset, keyed by the harness server name.
+ *
+ * Item 4 uses this only within the turn that took it. Item 1(b) can keep one
+ * per session and reuse it on a later turn while `fingerprint` still matches.
+ */
+export interface McpToolsetSnapshot {
+    fingerprint: string;
+    servers: Record<string, McpServerToolListing>;
+}
+/** One leased server, as it enters the toolset fingerprint. */
+export interface McpToolsetMember {
+    name: string;
+    /** The upstream URL from the lease, not the loopback proxy URL. */
+    url: string;
+    /** `null` means every tool the server exposes. */
+    allowedTools: readonly string[] | null;
+}
+/**
+ * A stable hash of what decides a toolset: the server set, each server's URL
+ * and its allowlist, plus any caller scope (for example the speaker, the space
+ * and a permission version, once the lease carries them).
+ *
+ * A change to any input gives a different fingerprint, so a cached listing for
+ * the old toolset is not reused. Order does not matter. `allowedTools: null`
+ * (every tool) and `[]` (no tool) are different toolsets.
+ */
+export declare function mcpToolsetFingerprint(members: readonly McpToolsetMember[], scope?: Record<string, string | number | null | undefined>): string;