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

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

@@ -21,10 +21,11 @@
 import type { CodingAgentAdapter } from '../adapters';
 import { SessionModelGateway } from '../adapters/model-gateway';
 import { ArtifactInspector, ConversationStore, EventSink, ModelMessageRecord, Notifier, SecretProvider, Telemetry, TranscriptStore, WorkspaceProvider } from '../ports';
-import { LeaseResponse, LeasedTurnInput, ModelMessageInput, TranscriptPartInput, TurnMetadata } from '../types';
+import { LeaseResponse, LeasedTurnInput, ModelMessageInput, RunnerRuntime, TranscriptPartInput, TurnMetadata } from '../types';
 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. */
@@ -46,6 +47,13 @@ export interface SessionRunnerDeps {
     telemetry: Telemetry;
     /** Send a structured timing event to the control plane without waiting. */
     coldStartLog?: (line: string) => void;
+    /**
+     * The HARNESS's own runtime. Only `sandbox` may route the agent through the
+     * credential proxy, whatever the lease says; absent means "not sandbox".
+     */
+    runtime?: RunnerRuntime;
+    /** Harness-level hosts the agent reaches directly (the control plane). */
+    directUrls?: string[];
     notifier: Notifier;
     artifacts: ArtifactInspector;
     /**
@@ -319,6 +327,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;
@@ -399,6 +413,12 @@ export declare class SessionRunner {
     private browserPauseStartedAt;
     /** When the last browser pause ended; the idle clock restarts from here. */
     private browserPauseEndedAt;
+    /**
+     * The credential-proxy token in force for this turn, kept ONLY so it can be
+     * scrubbed from everything this runner sends or logs. Not a credential
+     * value (see `LeaseResponse.credentialProxy`); null when the proxy is off.
+     */
+    private credentialProxyToken;
     constructor(deps: SessionRunnerDeps);
     /**
      * True while a permission prompt is outstanding. Read by the harness to
@@ -636,6 +656,8 @@ export declare class SessionRunner {
      * old Space's copies. Never throws; a failed sync is logged and the turn runs.
      */
     private syncSpaceFilesForTurn;
+    /** URLs this session's agent reaches without a proxy. */
+    private sessionDirectUrls;
     /**
      * Build the backend's session config.
      *
@@ -652,5 +674,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

@@ -38,8 +38,11 @@ const vendor_backends_1 = require("../vendor-backends");
 const attachments_1 = require("./attachments");
 const cold_start_steps_1 = require("./cold-start-steps");
 const conversation_1 = require("./conversation");
+const credential_proxy_1 = require("./credential-proxy");
 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 +86,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.
  *
@@ -646,6 +658,12 @@ class SessionRunner {
     browserPauseStartedAt = null;
     /** When the last browser pause ended; the idle clock restarts from here. */
     browserPauseEndedAt = null;
+    /**
+     * The credential-proxy token in force for this turn, kept ONLY so it can be
+     * scrubbed from everything this runner sends or logs. Not a credential
+     * value (see `LeaseResponse.credentialProxy`); null when the proxy is off.
+     */
+    credentialProxyToken = null;
     constructor(deps) {
         this.deps = deps;
         this.logger = deps.logger ?? console;
@@ -713,7 +731,9 @@ class SessionRunner {
     async run(leased, signal) {
         const lease = withoutGatewayForVendorBackend(leased);
         const { session } = lease;
-        const logColdStart = (line) => {
+        this.credentialProxyToken = null;
+        const logColdStart = (raw) => {
+            const line = (0, credential_proxy_1.redactCredentialProxyToken)(raw, this.credentialProxyToken);
             this.logger.log(line);
             this.deps.coldStartLog?.(line);
         };
@@ -728,6 +748,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 +789,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 +1021,66 @@ class SessionRunner {
             const unavailableMcpServers = [];
             const config = this.buildSessionConfig(session, workspaceDir, secretToken, signal, knowledgeUrl, unavailableMcpServers);
             config.coldStartLog = this.deps.coldStartLog;
+            /*
+             * THE CREDENTIAL PROXY. Layered over the env built above only when the
+             * lease offers it, the runner is a sandbox, and the broker answers; any
+             * failed check leaves `config.environment` exactly as it was.
+             */
+            const credentialProxy = await (0, credential_proxy_1.credentialProxyEnvironment)({
+                harnessRuntime: this.deps.runtime,
+                sessionRuntime: session.runtime,
+                backend: session.agent.backend,
+                sessionId: session.sessionId,
+                sessionDir: workspaceDir,
+                descriptor: lease.credentialProxy,
+                environment: config.environment,
+                directUrls: [
+                    ...(this.deps.directUrls ?? []),
+                    ...this.sessionDirectUrls(session, knowledgeUrl)
+                ],
+                logger: this.logger
+            });
+            config.environment = credentialProxy.environment;
+            this.credentialProxyToken = credentialProxy.token;
+            /*
+             * 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 +1281,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 +1422,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 +1508,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 +1985,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 });
                 });
@@ -2396,9 +2497,14 @@ class SessionRunner {
         if (chunks.length === 0) {
             chunks.push([]);
         }
+        // The agent can echo its own env (`env`, a failing curl) into a tool
+        // result; the credential-proxy token must not reach the transcript.
+        const token = this.credentialProxyToken;
         for (let i = 0; i < chunks.length; i += 1) {
             const isLast = i === chunks.length - 1;
-            await this.deps.ingest(sessionId, chunks[i], isLast ? turn : undefined, isLast ? final : false, isLast ? modelMessages : undefined);
+            await this.deps.ingest(sessionId, (0, credential_proxy_1.redactCredentialProxyTokenDeep)(chunks[i], token), isLast ? (0, credential_proxy_1.redactCredentialProxyTokenDeep)(turn, token) : undefined, isLast ? final : false, isLast
+                ? (0, credential_proxy_1.redactCredentialProxyTokenDeep)(modelMessages, token)
+                : undefined);
         }
     }
     /* ---------------------------------------------------------------- */
@@ -2666,6 +2772,14 @@ class SessionRunner {
             this.logger.warn(`[SessionRunner] Space files sync failed: ${(error instanceof Error ? error.message : String(error)).replace(/https?:\/\/\S+/gi, '<url>')}`);
         }
     }
+    /** URLs this session's agent reaches without a proxy. */
+    sessionDirectUrls(session, knowledgeUrl) {
+        return [
+            session.agent.model.gatewayUrl ?? '',
+            ...session.agent.mcpServers.map((server) => server.url),
+            ...(knowledgeUrl ? [knowledgeUrl] : [])
+        ];
+    }
     /**
      * Build the backend's session config.
      *
@@ -2682,6 +2796,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) {
@@ -2735,11 +2902,7 @@ class SessionRunner {
             secretBrokerPort: brokerPort ?? undefined,
             secretSessionToken: secretToken ?? undefined,
             secretShellPath: this.deps.secrets.writeShellWrapper() ?? undefined,
-            environment: this.deps.workspace.getEnvironment?.(session.sessionId, [
-                session.agent.model.gatewayUrl ?? '',
-                ...session.agent.mcpServers.map((server) => server.url),
-                ...(knowledgeUrl ? [knowledgeUrl] : [])
-            ]),
+            environment: this.deps.workspace.getEnvironment?.(session.sessionId, this.sessionDirectUrls(session, knowledgeUrl)),
             /*
              * DEFECT G1, THE OTHER HALF.
              *

package/dist/types.d.ts

@@ -516,6 +516,28 @@ export interface LeaseResponse {
     modelTokenExpiresAt?: string;
     /** In-memory only. It is never passed through a process environment. */
     githubCredential?: LeasedGitHubCredential;
+    /**
+     * Where the agent reaches the sandbox CREDENTIAL PROXY for this turn.
+     *
+     * NOT A SECRET VALUE. The real credential values live only in the root
+     * sandbox broker that runs the proxy; the harness (same uid as the agent)
+     * never holds one. `token` is a capability bound to tenant, session, turn
+     * and sandbox, which the agent presents to the proxy as the proxy URL's
+     * username. It is still never logged.
+     *
+     * ADDITIVE AND OPTIONAL (no protocol bump). Sent only for `sandbox` leases;
+     * the harness also refuses it on any other runtime and health-checks the
+     * port before using it. See `runtime/credential-proxy.ts`.
+     */
+    credentialProxy?: LeasedCredentialProxy;
+}
+export interface LeasedCredentialProxy {
+    /** Loopback port of the broker's proxy, e.g. 7790. */
+    port: number;
+    /** `pfcp_<b64url payload>.<b64url hmac>` — a bound capability, not a credential. */
+    token: string;
+    /** Public CA certificate (PEM) the proxy signs leaves with. */
+    caPath: string;
 }
 export interface LeasedSession {
     sessionId: string;
@@ -523,6 +545,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.2",
   "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",