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

package/dist/runtime/credential-proxy.js

@@ -0,0 +1,230 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CREDENTIAL_PROXY_ENV_KEYS = exports.CREDENTIAL_PROXY_TOKEN_REDACTION = exports.CREDENTIAL_PROXY_HEALTH_TIMEOUT_MS = exports.CREDENTIAL_PROXY_CA_BUNDLE_FILE = void 0;
+exports.probeLoopbackPort = probeLoopbackPort;
+exports.githubProxyPort = githubProxyPort;
+exports.credentialProxyEnvironment = credentialProxyEnvironment;
+exports.redactCredentialProxyToken = redactCredentialProxyToken;
+exports.redactCredentialProxyTokenDeep = redactCredentialProxyTokenDeep;
+/**
+ * THE AGENT'S ROUTE TO THE SANDBOX CREDENTIAL PROXY.
+ *
+ * The credential proxy runs in the ROOT sandbox broker, not in this process.
+ * It holds every real credential value; the harness never does. That is not a
+ * style choice: the harness and the agent it spawns share one uid (1500), so
+ * anything in the harness's memory or `/proc/<pid>/environ` is readable by the
+ * agent. The only thing the harness ever handles is the lease's
+ * `credentialProxy` descriptor — a loopback port, a CA path, and a token that
+ * is bound to tenant/session/turn/sandbox and is NOT a credential value.
+ *
+ * What this module does with it, and nothing more:
+ *   - decide whether the proxy is usable for THIS turn (sandbox runtime, Pi or
+ *     OpenCode backend, port answers within 1 s, CA readable), and
+ *   - if so, layer the proxy variables over the turn's existing environment.
+ *
+ * Any failed check returns the input environment UNCHANGED, plus one log line
+ * carrying the sessionId and a reason code. The token is never logged.
+ */
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_net_1 = require("node:net");
+const node_path_1 = require("node:path");
+const github_proxy_certificates_1 = require("../github-proxy-certificates");
+const github_workspace_1 = require("../github-workspace");
+const vendor_backends_1 = require("../vendor-backends");
+exports.CREDENTIAL_PROXY_CA_BUNDLE_FILE = '.pf-credential-proxy-ca.pem';
+exports.CREDENTIAL_PROXY_HEALTH_TIMEOUT_MS = 1_000;
+exports.CREDENTIAL_PROXY_TOKEN_REDACTION = '[credential-proxy-token]';
+/** Every key this module may add or replace. Nothing else is ever touched. */
+exports.CREDENTIAL_PROXY_ENV_KEYS = [
+    'HTTPS_PROXY',
+    'https_proxy',
+    'HTTP_PROXY',
+    'http_proxy',
+    'NO_PROXY',
+    'no_proxy',
+    'SSL_CERT_FILE',
+    'CURL_CA_BUNDLE',
+    'NODE_EXTRA_CA_CERTS',
+    'GIT_SSL_CAINFO',
+    'REQUESTS_CA_BUNDLE',
+    'PF_CREDENTIAL_PROXY'
+];
+/*
+ * The token lands in the userinfo of a proxy URL, so it must need no
+ * percent-encoding. The contract format `pfcp_<b64url>.<b64url>` satisfies
+ * this; anything else is refused rather than silently mangled.
+ */
+const TOKEN_SHAPE = /^[A-Za-z0-9._~-]{1,2048}$/;
+/** TCP connect to 127.0.0.1:port; true when it connects within the timeout. */
+function probeLoopbackPort(port, timeoutMs = exports.CREDENTIAL_PROXY_HEALTH_TIMEOUT_MS) {
+    return new Promise((resolvePromise) => {
+        const socket = (0, node_net_1.connect)({ host: '127.0.0.1', port });
+        let settled = false;
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolvePromise(ok);
+        };
+        // Covers the connect phase too: no SYN-ACK within the window -> 'timeout'.
+        socket.setTimeout(timeoutMs);
+        socket.once('timeout', () => finish(false));
+        socket.once('connect', () => finish(true));
+        socket.once('error', () => finish(false));
+    });
+}
+function validDescriptor(descriptor) {
+    return (typeof descriptor === 'object' &&
+        descriptor !== null &&
+        Number.isInteger(descriptor.port) &&
+        descriptor.port > 0 &&
+        descriptor.port < 65_536 &&
+        typeof descriptor.token === 'string' &&
+        TOKEN_SHAPE.test(descriptor.token) &&
+        typeof descriptor.caPath === 'string' &&
+        descriptor.caPath.length > 0);
+}
+/** The GitHub proxy's loopback port, read off the env GitHub already built. */
+function githubProxyPort(environment) {
+    const value = environment?.HTTPS_PROXY ?? environment?.https_proxy;
+    if (!value)
+        return null;
+    try {
+        const url = new URL(value);
+        if (url.hostname !== '127.0.0.1' || url.username)
+            return null;
+        const port = Number(url.port);
+        return Number.isInteger(port) && port > 0 ? port : null;
+    }
+    catch {
+        return null;
+    }
+}
+function withNewline(contents) {
+    return contents.length === 0 || contents.at(-1) === 0x0a
+        ? contents
+        : Buffer.concat([contents, Buffer.from('\n')]);
+}
+/**
+ * System trust + GitHub proxy CA (if any) + credential proxy CA.
+ *
+ * The GitHub bundle, when the turn has one, already IS "ambient roots + Node's
+ * public roots + GitHub CA" (see `createGitHubProxyCertificates`), so it is
+ * the base as-is. Without it the base is built the same way GitHub builds it.
+ */
+async function writeMergedBundle(input, credentialCa) {
+    const path = (0, node_path_1.join)((0, node_path_1.resolve)(input.sessionDir), exports.CREDENTIAL_PROXY_CA_BUNDLE_FILE);
+    const githubBundle = input.environment?.SSL_CERT_FILE;
+    let base;
+    if (githubBundle && (0, node_path_1.resolve)(githubBundle) !== path) {
+        base = [withNewline(await (0, promises_1.readFile)(githubBundle))];
+    }
+    else {
+        base = [
+            ...(await (0, github_proxy_certificates_1.ambientCaCertificates)(input.ambientEnvironment ?? process.env, path)),
+            Buffer.from((0, github_proxy_certificates_1.publicRootCertificates)())
+        ];
+    }
+    const temporary = `${path}.${(0, node_crypto_1.randomUUID)()}.tmp`;
+    await (0, promises_1.writeFile)(temporary, Buffer.concat([...base, withNewline(credentialCa)]), {
+        mode: 0o644
+    });
+    await (0, promises_1.chmod)(temporary, 0o644);
+    await (0, promises_1.rename)(temporary, path);
+    return path;
+}
+async function credentialProxyEnvironment(input) {
+    const unchanged = (reason) => {
+        // A self-hosted/desktop turn without the field is the normal case there,
+        // not a degradation; it stays silent. Everything else is one line.
+        if (!(reason === 'runtime_not_sandbox' && !input.descriptor)) {
+            input.logger.warn(`[CredentialProxy] credential proxy unavailable sessionId=${input.sessionId} reason=${reason}`);
+        }
+        return { environment: input.environment, token: null, reason };
+    };
+    // Defence in depth: the API never sends the field off-sandbox, and even if
+    // it did, a runner on a user's machine must not route through it.
+    if (input.harnessRuntime !== 'sandbox' || input.sessionRuntime !== 'sandbox')
+        return unchanged('runtime_not_sandbox');
+    if (!input.descriptor)
+        return unchanged('not_offered');
+    // A vendor CLI gets only an allowlisted env (vendor-environment.ts); it is
+    // not a supported credential-proxy client.
+    if ((0, vendor_backends_1.isVendorBackend)(input.backend))
+        return unchanged('vendor_backend');
+    const descriptor = input.descriptor;
+    if (!validDescriptor(descriptor))
+        return unchanged('invalid_descriptor');
+    if (!(await probeLoopbackPort(descriptor.port)))
+        return unchanged('health_check_failed');
+    let credentialCa;
+    try {
+        credentialCa = await (0, promises_1.readFile)(descriptor.caPath);
+    }
+    catch {
+        return unchanged('ca_unreadable');
+    }
+    if (!credentialCa.includes('-----BEGIN CERTIFICATE-----'))
+        return unchanged('ca_unreadable');
+    let bundle;
+    try {
+        bundle = await writeMergedBundle(input, credentialCa);
+    }
+    catch {
+        return unchanged('bundle_write_failed');
+    }
+    const base = input.environment ?? {};
+    // The cred proxy is the FIRST hop. When the turn has a GitHub proxy, the
+    // broker chains GitHub traffic to it; the password slot says where.
+    const chainPort = githubProxyPort(base) ?? 0;
+    const proxy = `http://${descriptor.token}:${chainPort}@127.0.0.1:${descriptor.port}`;
+    const noProxy = base.NO_PROXY ??
+        base.no_proxy ??
+        [
+            ...new Set([
+                '127.0.0.1',
+                'localhost',
+                ...(0, github_workspace_1.directHostnames)(input.directUrls)
+            ])
+        ].join(',');
+    return {
+        environment: {
+            ...base,
+            HTTPS_PROXY: proxy,
+            https_proxy: proxy,
+            HTTP_PROXY: proxy,
+            http_proxy: proxy,
+            NO_PROXY: noProxy,
+            no_proxy: noProxy,
+            SSL_CERT_FILE: bundle,
+            CURL_CA_BUNDLE: bundle,
+            NODE_EXTRA_CA_CERTS: bundle,
+            GIT_SSL_CAINFO: bundle,
+            REQUESTS_CA_BUNDLE: bundle,
+            PF_CREDENTIAL_PROXY: '1'
+        },
+        token: descriptor.token,
+        reason: null
+    };
+}
+/** Replace every occurrence of `token` in a string. No-op without a token. */
+function redactCredentialProxyToken(text, token) {
+    return token
+        ? text.split(token).join(exports.CREDENTIAL_PROXY_TOKEN_REDACTION)
+        : text;
+}
+/**
+ * Same, for a JSON-shaped value (transcript parts, turn metadata). The token
+ * alphabet needs no JSON escaping, so a string split over the serialised form
+ * finds every occurrence in every nested string.
+ */
+function redactCredentialProxyTokenDeep(value, token) {
+    if (!token || value === undefined)
+        return value;
+    const serialised = JSON.stringify(value);
+    if (!serialised.includes(token))
+        return value;
+    return JSON.parse(redactCredentialProxyToken(serialised, token));
+}

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;

package/dist/runtime/mcp-toolset.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpToolsetFingerprint = mcpToolsetFingerprint;
+const crypto_1 = require("crypto");
+function stableJson(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value) ?? 'null';
+    }
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record)
+        .filter((key) => record[key] !== undefined)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
+        .join(',')}}`;
+}
+/**
+ * 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.
+ */
+function mcpToolsetFingerprint(members, scope = {}) {
+    const servers = [...members]
+        .map((member) => ({
+        name: member.name,
+        url: member.url,
+        allowedTools: member.allowedTools === null
+            ? null
+            : [...new Set(member.allowedTools)].sort()
+    }))
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return (0, crypto_1.createHash)('sha256')
+        .update(stableJson({ version: 1, servers, scope }))
+        .digest('hex');
+}