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

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');
+}

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

@@ -25,6 +25,7 @@ import { LeaseResponse, LeasedTurnInput, ModelMessageInput, TranscriptPartInput,
 import { KnowledgeToolHost, type KnowledgeControl } from './knowledge-tools';
 import { McpAuthProxy } from './mcp-auth-proxy';
 import { type FailedMcpCheck } from './mcp-preflight';
+import { type McpToolStore } from './mcp-tool-store';
 export declare function approvalTimeoutMs(value: string | undefined): number;
 export interface SessionRunnerDeps {
     /** Resolves a backend name from the lease to a working adapter. */
@@ -319,6 +320,12 @@ export interface McpCheckState {
     checked: Map<string, number>;
     failed: Map<string, FailedMcpCheck>;
     shownNotices: Set<string>;
+    /**
+     * Item 1(b): each session's last MCP tool listings, reused on a warm turn
+     * while the toolset fingerprint is unchanged. See `mcp-tool-store.ts`.
+     * Created on first use when a caller's state predates it.
+     */
+    toolsets?: McpToolStore;
 }
 export declare class SessionRunner {
     private readonly deps;
@@ -652,5 +659,23 @@ export declare class SessionRunner {
      * security perimeter and trusting it to filter its own tools is exactly
      * defect G2.
      */
+    /**
+     * The leased toolset as it enters the fingerprint: every server's name,
+     * upstream URL and allowlist, plus the knowledge server when bound.
+     */
+    private mcpToolsetMembers;
+    /**
+     * The listings the backend may seed from (item 4, and item 1(b) for stored
+     * ones). Only a server that is still configured and was listed at its
+     * current url is kept.
+     */
+    private mcpToolSnapshot;
+    /**
+     * One `mcp_tool_store` line per turn on the harness log. Server names only,
+     * no tool data. Not sent to the control plane: its cold-start endpoint
+     * accepts only `cold_start_step`/`cold_start_summary`, so it would be one
+     * refused request per turn.
+     */
+    private logMcpToolStore;
     private buildSessionConfig;
 }

package/dist/runtime/session-runner.js

@@ -40,6 +40,8 @@ const cold_start_steps_1 = require("./cold-start-steps");
 const conversation_1 = require("./conversation");
 const knowledge_tools_1 = require("./knowledge-tools");
 const mcp_preflight_1 = require("./mcp-preflight");
+const mcp_tool_store_1 = require("./mcp-tool-store");
+const mcp_toolset_1 = require("./mcp-toolset");
 const permission_mode_1 = require("./permission-mode");
 const projection_1 = require("./projection");
 const space_files_1 = require("./space-files");
@@ -83,6 +85,15 @@ function approvalTimeoutMs(value) {
  * transcripts are complete.
  */
 const IDLE_CONFIRMATIONS = 2;
+/**
+ * The pause before the CONFIRMING poll, for a backend whose IDLE is terminal
+ * (`CodingAgentAdapter.idleIsTerminal`). The confirmation is kept: a final
+ * poll after the backend reported IDLE is what picks up a part that landed
+ * between the previous poll and the status read. It just no longer waits a
+ * full `POLL_INTERVAL_MS`, which used to add ~2 s to the end of every turn.
+ * Any new part in that poll resets the count, exactly as before.
+ */
+const TERMINAL_IDLE_CONFIRM_MS = 250;
 /**
  * THE PRIMARY GUARD, per the LONG TURNS fix.
  *
@@ -728,6 +739,15 @@ class SessionRunner {
         let stopReason = 'completed';
         let error;
         let gatewaySpendBefore = null;
+        /**
+         * The start-of-turn `/key/info` read, in flight. Started next to the model
+         * catalogue and the workspace prepare instead of before them, and awaited
+         * just before `sendPrompt` — the first point this turn can spend — so the
+         * baseline is still taken before any model call.
+         */
+        let gatewaySpendBeforeRead = null;
+        /** The end-of-turn read, started when the drain ends. See `finally`. */
+        let gatewaySpendAfterRead = null;
         let repositoryStatuses = [];
         /** True when the backend session was resumed rather than created. */
         let resumed = false;
@@ -760,9 +780,12 @@ class SessionRunner {
             if (refusal)
                 throw new Error(refusal);
             if (session.agent.model.gatewayUrl && lease.modelToken) {
-                gatewaySpendBefore = await readGatewaySpend(session.agent.model.gatewayUrl, lease.modelToken);
-                if (gatewaySpendBefore === null)
-                    this.logger.warn(`[coding-agent] Gateway spend start unavailable for turn ${session.turnId}; this turn cannot be debited from gateway usage`);
+                // `readGatewaySpend` never rejects: a failure resolves to null.
+                gatewaySpendBeforeRead = readGatewaySpend(session.agent.model.gatewayUrl, lease.modelToken).then((spend) => {
+                    if (spend === null)
+                        this.logger.warn(`[coding-agent] Gateway spend start unavailable for turn ${session.turnId}; this turn cannot be debited from gateway usage`);
+                    return spend;
+                });
             }
             // The catalogue is advisory. Fetch it while the independent workspace
             // is prepared. Pi can start with the selected lease model while this
@@ -989,18 +1012,45 @@ class SessionRunner {
             const unavailableMcpServers = [];
             const config = this.buildSessionConfig(session, workspaceDir, secretToken, signal, knowledgeUrl, unavailableMcpServers);
             config.coldStartLog = this.deps.coldStartLog;
+            /*
+             * ITEM 1(b). A server whose stored listing is still valid for this
+             * toolset and this speaker is not checked again: its tools are seeded
+             * into Pi from the store, so this turn sends it no MCP request before
+             * the prompt. The gateway still checks every tool call.
+             */
+            const toolStore = (this.mcpCheckState.toolsets ??= new Map());
+            const toolsetMembers = this.mcpToolsetMembers(session, knowledgeUrl);
+            const toolScope = session.mcpToolScope
+                ? { tenantId: session.tenantId, mcpToolScope: session.mcpToolScope }
+                : null;
+            const reusePlan = (0, mcp_tool_store_1.planMcpToolReuse)(toolStore, session.sessionId, toolsetMembers, toolScope, config.mcpServers ?? {});
             const endMcpPreflight = coldStart.begin('mcp_preflight');
+            const mcpListings = new Map();
             try {
-                unavailableMcpServers.push(...(await (0, mcp_preflight_1.verifyMcpServers)(config.mcpServers ?? {}, signal, this.mcpCheckState.checked, this.mcpCheckState.failed)));
+                unavailableMcpServers.push(...(await (0, mcp_preflight_1.verifyMcpServers)(Object.fromEntries(Object.entries(config.mcpServers ?? {}).filter(([name]) => !(name in reusePlan.reused))), signal, this.mcpCheckState.checked, this.mcpCheckState.failed, mcpListings, reusePlan.relist)));
             }
             finally {
                 endMcpPreflight();
             }
+            const storedNow = (0, mcp_tool_store_1.rememberMcpToolListings)(toolStore, session.sessionId, toolsetMembers, toolScope, mcpListings);
+            for (const [name, listing] of Object.entries(reusePlan.reused)) {
+                mcpListings.set(name, listing);
+            }
             for (const unavailable of unavailableMcpServers) {
                 if (!unavailable.keepConfigured) {
                     delete config.mcpServers?.[unavailable.name];
                 }
             }
+            const toolsetFingerprint = (0, mcp_toolset_1.mcpToolsetFingerprint)(toolsetMembers, toolScope ?? { tenantId: session.tenantId });
+            config.mcpToolSnapshot = this.mcpToolSnapshot(toolsetFingerprint, config, mcpListings);
+            this.logMcpToolStore(session, {
+                fingerprint: toolsetFingerprint.slice(0, 12),
+                scoped: toolScope !== null,
+                reused: Object.keys(reusePlan.reused),
+                listed: [...mcpListings.keys()].filter((name) => !(name in reusePlan.reused)),
+                stored: storedNow,
+                dropped: reusePlan.dropped
+            });
             const modelNotices = unavailableMcpServers.map(({ name, reason, keepConfigured }) => keepConfigured
                 ? `MCP server "${name}" did not answer the check (${reason}). Its tools may become available later in this turn.`
                 : `MCP server "${name}" is unavailable (${reason}). Its tools cannot be used in this turn.`);
@@ -1201,6 +1251,9 @@ class SessionRunner {
             const sentPromptTexts = [sentPromptParts.join('\n'), ...sentPromptParts];
             replayed = !resumed && memory.messages.length > 0;
             priorPartIdsForLog = priorPartIds;
+            // The spend baseline must be read before the first model call.
+            if (gatewaySpendBeforeRead)
+                gatewaySpendBefore = await gatewaySpendBeforeRead;
             const endPrompt = coldStart.begin('model_prompt_send');
             try {
                 await adapter.sendPrompt(backendSessionId, promptParts, config);
@@ -1339,6 +1392,21 @@ class SessionRunner {
             ]);
         }
         finally {
+            /*
+             * THE END-OF-TURN SPEND READ STARTS NOW, NOT AFTER TEARDOWN.
+             *
+             * The drain is over, so the backend has made its last model call. The
+             * read used to be awaited serially after `stopServer`, adding its whole
+             * round trip (up to its 5 s timeout) to every turn before the final
+             * ingest. It now overlaps the rest of teardown and is awaited only where
+             * `costUsd` is needed, on the final ingest that meters the turn.
+             */
+            gatewaySpendAfterRead =
+                gatewaySpendBeforeRead &&
+                    session.agent.model.gatewayUrl &&
+                    lease.modelToken
+                    ? readGatewaySpend(session.agent.model.gatewayUrl, lease.modelToken)
+                    : null;
             release();
             this.deps.modelGateway?.revoke();
             /*
@@ -1410,10 +1478,11 @@ class SessionRunner {
              */
         }
         let costUsd;
-        if (gatewaySpendBefore !== null &&
-            session.agent.model.gatewayUrl &&
-            lease.modelToken) {
-            const spendAfter = await readGatewaySpend(session.agent.model.gatewayUrl, lease.modelToken);
+        // A turn that failed before `sendPrompt` never awaited the baseline.
+        if (gatewaySpendBeforeRead)
+            gatewaySpendBefore = await gatewaySpendBeforeRead;
+        if (gatewaySpendBefore !== null && gatewaySpendAfterRead) {
+            const spendAfter = await gatewaySpendAfterRead;
             if (spendAfter === null)
                 this.logger.warn(`[coding-agent] Gateway spend end unavailable for turn ${session.turnId}; this turn cannot be debited from gateway usage`);
             else
@@ -1886,7 +1955,9 @@ class SessionRunner {
                         wake = null;
                         resolveWait();
                     };
-                    timer.handle = setTimeout(finish, POLL_INTERVAL_MS);
+                    timer.handle = setTimeout(finish, idleSeen > 0 && adapter.idleIsTerminal === true
+                        ? TERMINAL_IDLE_CONFIRM_MS
+                        : POLL_INTERVAL_MS);
                     wake = finish;
                     signal.addEventListener('abort', finish, { once: true });
                 });
@@ -2682,6 +2753,59 @@ class SessionRunner {
      * security perimeter and trusting it to filter its own tools is exactly
      * defect G2.
      */
+    /**
+     * The leased toolset as it enters the fingerprint: every server's name,
+     * upstream URL and allowlist, plus the knowledge server when bound.
+     */
+    mcpToolsetMembers(session, knowledgeUrl) {
+        return [
+            ...session.agent.mcpServers.map((server) => ({
+                name: server.name,
+                url: server.url,
+                allowedTools: server.allowedTools
+            })),
+            ...(knowledgeUrl
+                ? [
+                    {
+                        name: knowledge_tools_1.KNOWLEDGE_SERVER_NAME,
+                        url: knowledgeUrl,
+                        allowedTools: null
+                    }
+                ]
+                : [])
+        ];
+    }
+    /**
+     * The listings the backend may seed from (item 4, and item 1(b) for stored
+     * ones). Only a server that is still configured and was listed at its
+     * current url is kept.
+     */
+    mcpToolSnapshot(fingerprint, config, listings) {
+        const servers = {};
+        for (const [name, listing] of listings) {
+            const configured = config.mcpServers?.[name];
+            if (configured?.type === 'http' && configured.url === listing.url) {
+                servers[name] = listing;
+            }
+        }
+        if (Object.keys(servers).length === 0)
+            return undefined;
+        return { fingerprint, servers };
+    }
+    /**
+     * One `mcp_tool_store` line per turn on the harness log. Server names only,
+     * no tool data. Not sent to the control plane: its cold-start endpoint
+     * accepts only `cold_start_step`/`cold_start_summary`, so it would be one
+     * refused request per turn.
+     */
+    logMcpToolStore(session, detail) {
+        this.logger.log(JSON.stringify({
+            event: 'mcp_tool_store',
+            sessionId: session.sessionId,
+            turnId: session.turnId,
+            ...detail
+        }));
+    }
     buildSessionConfig(session, workspaceDir, secretToken, signal, knowledgeUrl = null, unavailable = []) {
         const mcpServers = {};
         for (const server of session.agent.mcpServers) {

package/dist/types.d.ts

@@ -523,6 +523,14 @@ export interface LeasedSession {
     /** One lease is one TURN. A new turn on the same session is a new lease. */
     turnId: string;
     runtime: RunnerRuntime;
+    /**
+     * Opaque. Changes when the speaker or the Space whose live permissions the
+     * MCP gateway applies changes, so the tool catalogue may differ. The harness
+     * reuses a session's stored MCP tool listings on a later turn only while
+     * this is the same. Optional and additive: absent (an older control plane)
+     * means nothing is reused across turns.
+     */
+    mcpToolScope?: string;
     agent: LeasedAgent;
     input: LeasedTurnInput;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peakflo/agent-harness",
-  "version": "0.2.13",
+  "version": "0.2.14-rc.1",
   "description": "Headless Peakflo coding-agent harness. One codebase, three hosting modes: a Daytona cloud sandbox, a customer VM, and the 20x desktop.",
   "license": "MIT",
   "type": "commonjs",