@peakflo/agent-harness 0.2.6-rc.1 → 0.2.7-rc.1

package/dist/adapters/pi-adapter.js

@@ -157,6 +157,11 @@ function buildPiMcpConfigDocument(servers, onRename) {
             {
                 url: server.url,
                 headers: server.headers ?? {},
+                // Pi's default lazy mode registers a namespace tool only when it
+                // already has cached tool metadata. A new session has no cache for
+                // this URL, so the model can see fewer servers than the lease gave
+                // it. Eager mode lists tools before the first model prompt.
+                lifecycle: 'eager',
                 // The managed integrations gateway can wait for a cold pfMCP
                 // instance. Its own upstream deadline is 270 seconds, so Pi must
                 // wait long enough to receive the gateway's result or clear error.

package/dist/harness.d.ts

@@ -135,6 +135,8 @@ export declare class Harness {
     private readonly notifier;
     private readonly artifacts;
     private readonly tokens;
+    /** One state for all leased turns in this process; each turn gets a new runner. */
+    private readonly mcpCheckState;
     private readonly startedAt;
     private status;
     private tenantId;

package/dist/harness.js

@@ -112,6 +112,12 @@ class Harness {
     notifier;
     artifacts;
     tokens = new ports_default_1.SessionTokenInjector(null);
+    /** One state for all leased turns in this process; each turn gets a new runner. */
+    mcpCheckState = {
+        checked: new Map(),
+        failed: new Map(),
+        shownNotices: new Set()
+    };
     startedAt = Date.now();
     status = 'starting';
     tenantId = null;
@@ -1403,6 +1409,7 @@ class Harness {
          */
         const modelGateway = new model_gateway_1.SessionModelGateway();
         const runner = new session_runner_1.SessionRunner({
+            mcpCheckState: this.mcpCheckState,
             getAdapter: (backend) => {
                 const build = this.deps.getAdapter;
                 if (!build) {

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

@@ -0,0 +1,21 @@
+export interface UnavailableMcpServer {
+    name: string;
+    reason: string;
+    /** A cold integrations server may still connect through Pi after this check. */
+    keepConfigured?: boolean;
+}
+export interface FailedMcpCheck {
+    reason: string;
+    keepConfigured: boolean;
+    nextRetryAt: number;
+    backoffMs: number;
+}
+/**
+ * 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.
+ */
+export declare function verifyMcpServers(servers: Record<string, {
+    type: string;
+    url?: string;
+}>, signal?: AbortSignal, successful?: Map<string, number>, failed?: Map<string, FailedMcpCheck>): Promise<UnavailableMcpServer[]>;

package/dist/runtime/mcp-preflight.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyMcpServers = verifyMcpServers;
+const client_1 = require("@modelcontextprotocol/client");
+const SUCCESS_CACHE_TTL_MS = 5 * 60_000;
+const INITIAL_FAILURE_BACKOFF_MS = 15_000;
+const MAX_FAILURE_BACKOFF_MS = 2 * 60_000;
+const MAX_CACHE_ENTRIES = 1024;
+function safeHttpStatus(cause) {
+    let current = cause;
+    for (let depth = 0; depth < 4 && current instanceof Error; depth++) {
+        if (current instanceof client_1.SdkHttpError)
+            return current.status;
+        current = current.cause;
+    }
+    const match = String(cause).match(/^(?:Error:\s*)?HTTP\s+([45]\d\d)\b/i);
+    return match ? Number(match[1]) : null;
+}
+/**
+ * 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.
+ */
+async function verifyMcpServers(servers, signal, successful, failed) {
+    const results = await Promise.all(Object.entries(servers).map(async ([name, server]) => {
+        if (server.type !== 'http' || !server.url)
+            return null;
+        if (signal?.aborted)
+            throw new Error('MCP check was cancelled.');
+        const key = `${name}\n${server.url}`;
+        const checkedAt = successful?.get(key);
+        if (checkedAt !== undefined &&
+            Date.now() - checkedAt < SUCCESS_CACHE_TTL_MS)
+            return null;
+        const priorFailure = failed?.get(key);
+        if (priorFailure && Date.now() < priorFailure.nextRetryAt) {
+            return {
+                name,
+                reason: priorFailure.reason,
+                ...(priorFailure.keepConfigured ? { keepConfigured: true } : {})
+            };
+        }
+        let reason = 'connection or tool listing failed';
+        let status = null;
+        let timedOut = false;
+        // Each attempt has one shared connect+list deadline. A cold integrations
+        // server stays configured after a timeout; Pi has its own longer limit.
+        for (let attempt = 0; attempt < 2; attempt++) {
+            if (signal?.aborted)
+                throw new Error('MCP check was cancelled.');
+            const client = new client_1.Client({ name: 'peakflo-agent-harness-check', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } });
+            const deadline = AbortSignal.timeout(10_000);
+            const requestSignal = signal
+                ? AbortSignal.any([signal, deadline])
+                : 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 });
+                successful?.set(key, Date.now());
+                failed?.delete(key);
+                if (successful && successful.size > MAX_CACHE_ENTRIES) {
+                    successful.delete(successful.keys().next().value);
+                }
+                return null;
+            }
+            catch (cause) {
+                if (signal?.aborted)
+                    throw new Error('MCP check was cancelled.');
+                // SDK errors can include a URL or response body. Expose only an
+                // explicit HTTP status, never the raw error.
+                status = safeHttpStatus(cause);
+                timedOut = deadline.aborted;
+                reason = timedOut
+                    ? 'timed out'
+                    : status
+                        ? `HTTP ${status}`
+                        : 'connection or tool listing failed';
+                if (status &&
+                    status >= 400 &&
+                    status < 500 &&
+                    status !== 408 &&
+                    status !== 429)
+                    break;
+                // Do not spend another ten seconds probing a cold integrations
+                // server. Pi can still connect to it with its own 300-second limit.
+                if (name === 'integrations' && timedOut)
+                    break;
+            }
+            finally {
+                await client.close().catch(() => undefined);
+            }
+        }
+        const keepConfigured = name === 'integrations' &&
+            (timedOut ||
+                status === 408 ||
+                status === 429 ||
+                (status !== null && status >= 500));
+        const backoffMs = Math.min(priorFailure ? priorFailure.backoffMs * 2 : INITIAL_FAILURE_BACKOFF_MS, MAX_FAILURE_BACKOFF_MS);
+        // Access can change between turns. Recheck 4xx refusals immediately;
+        // only temporary failures use backoff.
+        if (timedOut ||
+            status === null ||
+            status === 408 ||
+            status === 429 ||
+            status >= 500) {
+            failed?.set(key, {
+                reason,
+                keepConfigured,
+                nextRetryAt: Date.now() + backoffMs,
+                backoffMs
+            });
+        }
+        else {
+            failed?.delete(key);
+        }
+        if (failed && failed.size > MAX_CACHE_ENTRIES) {
+            failed.delete(failed.keys().next().value);
+        }
+        return {
+            name,
+            reason,
+            ...(keepConfigured ? { keepConfigured: true } : {})
+        };
+    }));
+    return results.filter((result) => result !== null);
+}

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

@@ -24,6 +24,7 @@ import { ArtifactInspector, ConversationStore, EventSink, ModelMessageRecord, No
 import { LeaseResponse, LeasedTurnInput, ModelMessageInput, TranscriptPartInput, TurnMetadata } from '../types';
 import { KnowledgeToolHost, type KnowledgeControl } from './knowledge-tools';
 import { McpAuthProxy } from './mcp-auth-proxy';
+import { type FailedMcpCheck } from './mcp-preflight';
 export interface SessionRunnerDeps {
     /** Resolves a backend name from the lease to a working adapter. */
     getAdapter(backend: string): CodingAgentAdapter;
@@ -34,6 +35,8 @@ export interface SessionRunnerDeps {
      * consults a gateway, keep constructing a runner without one.
      */
     modelGateway?: SessionModelGateway;
+    /** Shared by the harness across disposable runners for leased turns. */
+    mcpCheckState?: McpCheckState;
     store: TranscriptStore;
     workspace: WorkspaceProvider;
     proxy: McpAuthProxy;
@@ -248,9 +251,15 @@ export declare function decodeQuestionAnswers(answer: string | undefined): Recor
  * Codex's "Allow" read as a denial.
  */
 export declare function isApprovingOptionId(optionId: string): boolean;
+export interface McpCheckState {
+    checked: Map<string, number>;
+    failed: Map<string, FailedMcpCheck>;
+    shownNotices: Set<string>;
+}
 export declare class SessionRunner {
     private readonly deps;
     private readonly logger;
+    private readonly mcpCheckState;
     /**
      * What the running turn needs in order to ANSWER a permission from outside
      * the turn's own call stack.

package/dist/runtime/session-runner.js

@@ -34,6 +34,7 @@ const attachments_1 = require("./attachments");
 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 permission_mode_1 = require("./permission-mode");
 const projection_1 = require("./projection");
 const space_files_1 = require("./space-files");
@@ -375,6 +376,7 @@ function resolveApproval(command, open) {
 class SessionRunner {
     deps;
     logger;
+    mcpCheckState;
     /**
      * What the running turn needs in order to ANSWER a permission from outside
      * the turn's own call stack.
@@ -565,6 +567,11 @@ class SessionRunner {
     constructor(deps) {
         this.deps = deps;
         this.logger = deps.logger ?? console;
+        this.mcpCheckState = deps.mcpCheckState ?? {
+            checked: new Map(),
+            failed: new Map(),
+            shownNotices: new Set()
+        };
     }
     /**
      * True while a permission prompt is outstanding. Read by the harness to
@@ -615,6 +622,7 @@ class SessionRunner {
          * files exist.
          */
         let turnContent = session.input.content;
+        let turnMcpNotice = null;
         this.turnParts = [];
         this.steerTurnGeneration++;
         this.steerAcknowledgementsClosed = false;
@@ -845,8 +853,46 @@ class SessionRunner {
                 });
                 knowledgeUrl = await this.deps.knowledge.host.endpointFor(session.sessionId);
             }
-            const config = this.buildSessionConfig(session, workspaceDir, secretToken, signal, knowledgeUrl);
+            const unavailableMcpServers = [];
+            const config = this.buildSessionConfig(session, workspaceDir, secretToken, signal, knowledgeUrl, unavailableMcpServers);
             config.coldStartLog = this.deps.coldStartLog;
+            const endMcpPreflight = coldStart.begin('mcp_preflight');
+            try {
+                unavailableMcpServers.push(...(await (0, mcp_preflight_1.verifyMcpServers)(config.mcpServers ?? {}, signal, this.mcpCheckState.checked, this.mcpCheckState.failed)));
+            }
+            finally {
+                endMcpPreflight();
+            }
+            for (const unavailable of unavailableMcpServers) {
+                if (!unavailable.keepConfigured) {
+                    delete config.mcpServers?.[unavailable.name];
+                }
+            }
+            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.`);
+            turnMcpNotice = modelNotices.length > 0 ? modelNotices.join('\n') : null;
+            const userNotices = unavailableMcpServers.flatMap(({ name }, index) => {
+                const key = `${session.sessionId}\n${name}`;
+                if (this.mcpCheckState.shownNotices.has(key))
+                    return [];
+                this.mcpCheckState.shownNotices.add(key);
+                if (this.mcpCheckState.shownNotices.size > 1024) {
+                    this.mcpCheckState.shownNotices.delete(this.mcpCheckState.shownNotices.values().next().value);
+                }
+                return [modelNotices[index]];
+            });
+            if (userNotices.length > 0) {
+                partsProduced += this.record(session.sessionId, [
+                    {
+                        id: `mcp-unavailable-${session.turnId}`,
+                        role: 'system',
+                        partType: 'text',
+                        content: userNotices.join('\n')
+                    }
+                ]);
+                await this.flush(session.sessionId, this.pending.splice(0), undefined, false);
+            }
             /*
              * REMEMBER THE CONVERSATION. This block is the fix for the defect that
              * made this a chat product that could not hold a conversation: the
@@ -1002,11 +1048,29 @@ class SessionRunner {
             const promptWithHostNote = turnNote
                 ? `${turnNote}\n\n${promptText}`
                 : promptText;
+            const promptParts = [
+                ...(turnMcpNotice
+                    ? [
+                        {
+                            type: 'text',
+                            text: `Tool access notice:\n${turnMcpNotice}`,
+                            role: 'system'
+                        }
+                    ]
+                    : []),
+                { type: 'text', text: promptWithHostNote, role: 'user' }
+            ];
+            // Pi, ACP, Claude Code, and Codex join parts with a newline. OpenCode
+            // keeps them separate. Accept echoes in either representation.
+            const sentPromptParts = promptParts
+                .filter((part) => part.type === 'text' && Boolean(part.text))
+                .map((part) => part.text);
+            const sentPromptTexts = [sentPromptParts.join('\n'), ...sentPromptParts];
             replayed = !resumed && memory.messages.length > 0;
             priorPartIdsForLog = priorPartIds;
             const endPrompt = coldStart.begin('model_prompt_send');
             try {
-                await adapter.sendPrompt(backendSessionId, [{ type: 'text', text: promptWithHostNote, role: 'user' }], config);
+                await adapter.sendPrompt(backendSessionId, promptParts, config);
             }
             finally {
                 endPrompt();
@@ -1044,7 +1108,7 @@ class SessionRunner {
             resumed ? priorPartIds : new Set(), 
             // THE PROMPT THIS RUNNER JUST SENT. Drain uses it to recognise the
             // backend's own echo of it — see `drain`.
-            promptWithHostNote, () => endFirstOutput(), () => endFirstIngest());
+            sentPromptTexts, () => endFirstOutput(), () => endFirstIngest());
             partsProduced = drained.parts;
             if (signal.aborted) {
                 stopReason = 'aborted';
@@ -1300,7 +1364,7 @@ class SessionRunner {
      * Both sides are trimmed first: a backend that strips a trailing newline
      * from the echoed text must not slip past the prefix check on that alone.
      */
-    isEchoOfTurnPrompt(part, sentPromptText) {
+    isEchoOfTurnPrompt(part, sentPromptTexts) {
         if (typeof part.role !== 'string' || part.role.toLowerCase() !== 'user') {
             return false;
         }
@@ -1310,7 +1374,7 @@ class SessionRunner {
         const echoed = text.trim();
         if (echoed.length === 0)
             return false;
-        return sentPromptText.trim().startsWith(echoed);
+        return sentPromptTexts.some((text) => text.trim().startsWith(echoed));
     }
     isExactSteerEcho(part, steeredPrompt) {
         if (typeof part.role !== 'string' || part.role.toLowerCase() !== 'user')
@@ -1345,7 +1409,7 @@ class SessionRunner {
      */
     async drain(adapter, backendSessionId, config, session, signal, alreadySeenPartIds = new Set(), 
     /** The exact text `sendPrompt` was given this turn, for echo filtering. */
-    sentPromptText = null, onFirstOutput, onFirstIngest) {
+    sentPromptTexts = null, onFirstOutput, onFirstIngest) {
         let providerError;
         let timedOut = false;
         let idleTimedOut = false;
@@ -1468,9 +1532,9 @@ class SessionRunner {
                  * be. Answers to questions travel a different wire (`respondTo*`) and
                  * are recorded by the answer path itself, with the `answer-…` part id.
                  */
-                const freshParts = sentPromptText && sentPromptText.length > 0
+                const freshParts = sentPromptTexts && sentPromptTexts.length > 0
                     ? parts.filter((part) => {
-                        if (this.isEchoOfTurnPrompt(part, sentPromptText))
+                        if (this.isEchoOfTurnPrompt(part, sentPromptTexts))
                             return false;
                         return !this.consumesSteerEcho(part);
                     })
@@ -2357,23 +2421,22 @@ class SessionRunner {
      * security perimeter and trusting it to filter its own tools is exactly
      * defect G2.
      */
-    buildSessionConfig(session, workspaceDir, secretToken, signal, knowledgeUrl = null) {
+    buildSessionConfig(session, workspaceDir, secretToken, signal, knowledgeUrl = null, unavailable = []) {
         const mcpServers = {};
         for (const server of session.agent.mcpServers) {
             const proxied = this.deps.proxy.registerTarget(server.url, server.name);
+            if (!proxied) {
+                unavailable.push({
+                    name: server.name,
+                    reason: 'local MCP proxy is unavailable'
+                });
+                continue;
+            }
             mcpServers[server.name] = {
                 name: server.name,
                 type: 'http',
-                // A null proxy URL means the proxy is not running. Falling back to the
-                // direct URL would put the session token in the backend's config, so
-                // the server is simply omitted instead — fewer tools is recoverable,
-                // a leaked token is not.
                 url: proxied
             };
-            if (!proxied) {
-                delete mcpServers[server.name];
-                this.logger.warn(`[SessionRunner] MCP server "${server.name}" omitted: proxy not running`);
-            }
         }
         /*
          * The knowledge server is on loopback with a per-session path secret, so it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peakflo/agent-harness",
-  "version": "0.2.6-rc.1",
+  "version": "0.2.7-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",
@@ -37,6 +37,7 @@
     "undici": "^7.21.0"
   },
   "dependencies": {
+    "@modelcontextprotocol/client": "2.0.0",
     "@peculiar/x509": "^2.1.0",
     "reflect-metadata": "^0.2.2"
   },