@ai-sdk/harness-pi 1.0.63 → 1.0.65

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-pi",
-  "version": "1.0.63",
+  "version": "1.0.65",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -26,10 +26,12 @@
     }
   },
   "dependencies": {
+    "@earendil-works/pi-ai": "0.74.2",
     "@earendil-works/pi-coding-agent": "^0.80.10",
+    "pi-mcp-adapter": "2.12.1",
     "typebox": "^1.1.38",
-    "@ai-sdk/harness": "1.0.63",
-    "@ai-sdk/provider-utils": "5.0.24"
+    "@ai-sdk/provider-utils": "5.0.26",
+    "@ai-sdk/harness": "1.0.65"
   },
   "peerDependencies": {
     "zod": "^3.25.76 || ^4.1.8"

package/src/pi-harness.ts

@@ -4,6 +4,7 @@ import {
   type HarnessV1BuiltinTool,
 } from '@ai-sdk/harness';
 import { tool } from '@ai-sdk/provider-utils';
+import type { ExtensionFactory } from '@earendil-works/pi-coding-agent';
 import { z } from 'zod/v4';
 import type { PiAuthOptions } from './pi-auth';
 import { piResumeStateSchema } from './pi-resume-state';
@@ -40,6 +41,17 @@ export type PiHarnessSettings = {
    * model settings.
    */
   readonly agentDir?: string;
+  /**
+   * MCP server definitions keyed by server name. Each definition uses the
+   * underlying runtime's native MCP server configuration format.
+   */
+  readonly mcpServers?: Record<string, unknown>;
+  /**
+   * Trusted inline Pi extensions loaded for each harness session.
+   *
+   * Filesystem-discovered user and project extensions remain disabled.
+   */
+  readonly extensionFactories?: ReadonlyArray<ExtensionFactory>;
 };
 
 const PI_BUILTIN_TOOLS = {
@@ -144,6 +156,10 @@ export function createPi(
           ...(settings.thinkingLevel
             ? { thinkingLevel: settings.thinkingLevel }
             : {}),
+          ...(settings.mcpServers ? { mcpServers: settings.mcpServers } : {}),
+          ...(settings.extensionFactories
+            ? { extensionFactories: settings.extensionFactories }
+            : {}),
         },
         clientApp: PI_CLIENT_APP,
         isResume: lifecycleState != null,

package/src/pi-session.ts

@@ -8,6 +8,7 @@ import {
   SettingsManager,
   type AgentSession,
   type AgentToolResult,
+  type ExtensionFactory,
   type Skill,
   type ToolDefinition,
 } from '@earendil-works/pi-coding-agent';
@@ -63,6 +64,26 @@ import { syncHostWorkspaceFromSandbox } from './pi-workspace-mirror';
 
 const HARNESS_ID = 'pi';
 
+/*
+ * pi-mcp-adapter publishes TypeScript source as its package entry point. A
+ * non-literal specifier keeps the repository type-check focused on this
+ * package's compatibility boundary instead of compiling dependency internals.
+ */
+const PI_MCP_ADAPTER_PACKAGE: string = 'pi-mcp-adapter';
+
+type PiMcpAdapterModule = {
+  createMcpAdapter(options: {
+    config: {
+      mcpServers: Record<string, unknown>;
+      settings: {
+        directTools: boolean;
+        toolPrefix: string;
+        disableProxyTool: boolean;
+      };
+    };
+  }): ExtensionFactory;
+};
+
 /*
  * Pi runs in this Node process, not behind an attachable in-sandbox bridge.
  * During a tool approval pause the Pi turn is still alive and blocked on the
@@ -192,6 +213,8 @@ export interface PiSessionSettings {
   readonly auth?: PiAuthOptions;
   readonly model?: string;
   readonly thinkingLevel?: PiThinkingLevel;
+  readonly mcpServers?: Record<string, unknown>;
+  readonly extensionFactories?: ReadonlyArray<ExtensionFactory>;
 }
 
 export interface CreatePiSessionInput {
@@ -367,19 +390,69 @@ export async function createPiSession(
   // Resolve once: deterministic given the configured model. This is the Pi
   // `Model` object handed to `createAgentSession`.
   const resolvedModel = resolveModel(input.settings.model);
+  const mcpServers = resolvePiMcpServers({
+    mcpServers: input.settings.mcpServers,
+  });
+  const hasMcpServers = Object.keys(mcpServers).length > 0;
 
+  /*
+   * Configured MCP servers are served by an inline Pi extension, so they share
+   * the extension runtime with the caller-supplied factories: both are loaded
+   * by the resource loader below and both are subject to the reload handling
+   * that keeps the active runtime alive across resource-only reloads.
+   */
+  const extensionFactories: ExtensionFactory[] = [
+    ...(input.settings.extensionFactories ?? []),
+  ];
+  if (hasMcpServers) {
+    const { createMcpAdapter } = (await import(
+      PI_MCP_ADAPTER_PACKAGE
+    )) as PiMcpAdapterModule;
+    extensionFactories.push(
+      createMcpAdapter({
+        config: {
+          mcpServers,
+          settings: {
+            directTools: true,
+            toolPrefix: 'mcp',
+            disableProxyTool: true,
+          },
+        },
+      }),
+    );
+  }
+  const hasExtensionFactories = extensionFactories.length > 0;
+  let preserveExtensionsResult = false;
+  let currentExtensionsResult:
+    | ReturnType<DefaultResourceLoader['getExtensions']>
+    | undefined;
   const resourceLoader = new DefaultResourceLoader({
     cwd: sessionWorkDir,
     agentDir: hostAgentDir,
     settingsManager,
     appendSystemPromptOverride: () => [],
-    extensionFactories: [],
+    extensionFactories,
+    ...(hasExtensionFactories
+      ? {
+          // DefaultResourceLoader invokes inline factories on every reload.
+          // Resource-only reloads retain the active extension runtime, while a
+          // genuine Pi session rebuild is allowed to replace that runtime.
+          extensionsOverride: extensions => {
+            if (preserveExtensionsResult && currentExtensionsResult != null) {
+              return currentExtensionsResult;
+            }
+            currentExtensionsResult = extensions;
+            return extensions;
+          },
+        }
+      : {}),
     // Pi runs in the host process, so its default resource discovery reaches
     // the host developer's personal config (`~/.pi/agent/*`, `~/.agents/*`).
-    // The harness does not expose extensions, themes, or prompt templates, so
-    // disable those entirely — this also avoids loading and executing a host
-    // developer's personal Pi extensions inside the server process. Skills are
-    // kept but filtered to workspace project skills plus harness-provided
+    // The harness exposes only explicitly supplied inline extension factories;
+    // disable filesystem extension discovery entirely to avoid loading and
+    // executing a host developer's personal or project Pi extensions inside
+    // the server process. Themes and prompt templates stay disabled. Skills
+    // are kept but filtered to workspace project skills plus harness-provided
     // skills whose files live in sandbox HOME.
     noExtensions: true,
     noThemes: true,
@@ -396,6 +469,22 @@ export async function createPiSession(
   });
   await resourceLoader.reload();
 
+  async function reloadResourcesOnly(): Promise<void> {
+    if (!hasExtensionFactories) {
+      await resourceLoader.reload();
+      return;
+    }
+
+    const factories = extensionFactories.splice(0);
+    preserveExtensionsResult = true;
+    try {
+      await resourceLoader.reload();
+    } finally {
+      preserveExtensionsResult = false;
+      extensionFactories.push(...factories);
+    }
+  }
+
   // Per-session mutable state we hold across prompts.
   let piSession: AgentSession | undefined;
   let unsubscribe: (() => void) | undefined;
@@ -571,20 +660,38 @@ export async function createPiSession(
     };
   }
 
+  async function disposePiSession(): Promise<void> {
+    unsubscribe?.();
+    unsubscribe = undefined;
+
+    const session = piSession;
+    piSession = undefined;
+    if (!session) return;
+
+    if (hasMcpServers) {
+      await session.reload().catch(() => {});
+    }
+    session.dispose();
+  }
+
   async function rebuildPiSession(
     userTools: ReadonlyArray<HarnessV1ToolSpec>,
     isFirstBuild: boolean,
-  ): Promise<void> {
+  ): Promise<boolean> {
+    let resourcesReloaded = false;
     if (piSession) {
-      unsubscribe?.();
-      unsubscribe = undefined;
-      piSession.dispose();
-      piSession = undefined;
+      await disposePiSession();
       // Original adapter waits 25 ms here to let Pi's teardown microtasks
       // settle before the next createAgentSession. Port verbatim.
       // TODO(pi-0.77): verify the race still exists; original SDK had a
       // teardown microtask the host needed to wait on.
       await new Promise(resolve => setTimeout(resolve, 25));
+      if (hasExtensionFactories) {
+        // dispose() invalidates Pi's current extension runtime, so a replacement
+        // AgentSession needs factories to create a fresh runtime before build.
+        await resourceLoader.reload();
+        resourcesReloaded = true;
+      }
     }
 
     const { customTools, builtinNames } = buildToolDefinitions(userTools);
@@ -609,13 +716,18 @@ export async function createPiSession(
       settingsManager,
       resourceLoader,
       customTools,
-      tools: toolNames,
+      ...(hasMcpServers
+        ? { noTools: 'builtin' as const }
+        : { tools: toolNames }),
       ...(input.settings.thinkingLevel
         ? { thinkingLevel: input.settings.thinkingLevel }
         : {}),
       ...(resolvedModel ? { model: resolvedModel } : {}),
     });
     piSession = session;
+    if (hasMcpServers) {
+      await piSession.bindExtensions({ mode: 'print' });
+    }
 
     // Pick up the actual session file path so doStop can persist it. Pi
     // 0.77 emits `.jsonl` files; older builds used `.json`. Persist the
@@ -628,6 +740,7 @@ export async function createPiSession(
 
     translatorState = createPiTranslatorState({
       builtinToolNames: builtinNames,
+      hostToolNames: userTools.map(tool => tool.name),
       nativeToCommon: NATIVE_TO_COMMON,
     });
 
@@ -645,6 +758,7 @@ export async function createPiSession(
         // Other event types outside a turn have no consumer and are dropped.
       }
     });
+    return resourcesReloaded;
   }
 
   /*
@@ -665,12 +779,15 @@ export async function createPiSession(
     const userTools = turnOpts.tools;
     const signature = JSON.stringify(userTools.map(t => t.name).sort());
     const needsRebuild = piSession == null || signature !== lastToolsSignature;
+    let resourcesReloaded = false;
     if (needsRebuild) {
-      await rebuildPiSession(userTools, piSession == null);
+      resourcesReloaded = await rebuildPiSession(userTools, piSession == null);
       lastToolsSignature = signature;
     }
 
-    await resourceLoader.reload();
+    if (!resourcesReloaded) {
+      await reloadResourcesOnly();
+    }
     await syncHostWorkspaceFromSandbox({
       sandbox,
       sandboxWorkDir: input.sessionWorkDir,
@@ -682,6 +799,7 @@ export async function createPiSession(
     // session was built with.
     translatorState = createPiTranslatorState({
       builtinToolNames: [...PI_NATIVE_BUILTIN_NAMES],
+      hostToolNames: userTools.map(tool => tool.name),
       nativeToCommon: NATIVE_TO_COMMON,
     });
 
@@ -795,10 +913,7 @@ export async function createPiSession(
       }
     }
 
-    unsubscribe?.();
-    unsubscribe = undefined;
-    piSession?.dispose();
-    piSession = undefined;
+    await disposePiSession();
     workspaceVfs.unmount();
     await rm(hostRoot, { recursive: true, force: true });
 
@@ -884,10 +999,7 @@ export async function createPiSession(
       parkedPiSessions.delete(input.sessionId);
       settlePendingToolResults('Pi session stopped');
       settlePendingToolApprovals('Pi session stopped');
-      unsubscribe?.();
-      unsubscribe = undefined;
-      piSession?.dispose();
-      piSession = undefined;
+      await disposePiSession();
       workspaceVfs.unmount();
       await rm(hostRoot, { recursive: true, force: true });
     },
@@ -972,10 +1084,7 @@ export async function createPiSession(
       parkedPiSessions.delete(input.sessionId);
       settlePendingToolResults('Pi session suspended');
       settlePendingToolApprovals('Pi session suspended');
-      unsubscribe?.();
-      unsubscribe = undefined;
-      piSession?.dispose();
-      piSession = undefined;
+      await disposePiSession();
       workspaceVfs.unmount();
       await rm(hostRoot, { recursive: true, force: true });
 
@@ -991,6 +1100,22 @@ export async function createPiSession(
   return sessionImpl;
 }
 
+function resolvePiMcpServers({
+  mcpServers,
+}: {
+  mcpServers: Record<string, unknown> | undefined;
+}): Record<string, unknown> {
+  if (mcpServers == null) return {};
+  for (const [name, value] of Object.entries(mcpServers)) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+      throw new Error(
+        `Pi MCP server ${JSON.stringify(name)} must be configured with an object value.`,
+      );
+    }
+  }
+  return mcpServers;
+}
+
 /**
  * Whether a terminal error (string from Pi's event stream, or a thrown error)
  * is an abort — the expected result of `doSuspendTurn` aborting the in-flight

package/src/pi-translate.ts

@@ -1,5 +1,6 @@
 import { randomBytes } from 'node:crypto';
 import type { HarnessV1StreamPart } from '@ai-sdk/harness';
+import { secureJsonParse } from '@ai-sdk/provider-utils';
 import { extractAssistantText, type PiSessionEvent } from './pi-events';
 import { serializeToolOutput } from './pi-utils';
 
@@ -43,6 +44,7 @@ export interface PiTranslatorState {
    * the matching `tool_result`/`tool_execution_end` event is translated.
    */
   hostToolResults: Map<string, unknown>;
+  dynamicToolCallIds: Set<string>;
   /**
    * Names of tools that Pi executes natively (read/write/edit/bash/grep/
    * find/ls). `tool-call` events for these get `providerExecuted: true`
@@ -50,6 +52,7 @@ export interface PiTranslatorState {
    * tools are not in this set.
    */
   readonly builtinToolNames: ReadonlySet<string>;
+  readonly hostToolNames: ReadonlySet<string>;
   /**
    * Map of native tool name → common name. `find` → `glob`, etc. Pi emits
    * native names on its events; the wire `toolName` is the common name when
@@ -60,6 +63,7 @@ export interface PiTranslatorState {
 
 export interface PiTranslatorStateOptions {
   readonly builtinToolNames?: ReadonlyArray<string>;
+  readonly hostToolNames?: ReadonlyArray<string>;
   readonly nativeToCommon?:
     | ReadonlyMap<string, string>
     | Record<string, string>;
@@ -82,7 +86,9 @@ export function createPiTranslatorState(
     pendingStepToolCallIds: new Set(),
     stepOpen: false,
     hostToolResults: new Map(),
+    dynamicToolCallIds: new Set(),
     builtinToolNames: new Set(options.builtinToolNames ?? []),
+    hostToolNames: new Set(options.hostToolNames ?? []),
     nativeToCommonNameMap: map,
   };
 }
@@ -128,6 +134,15 @@ function unwrapPiToolResult(event: PiSessionEvent): never {
   return (event.result ?? event.content ?? null) as never;
 }
 
+function parseMcpToolResult(content: unknown): unknown {
+  if (typeof content !== 'string') return content;
+  try {
+    return secureJsonParse(content);
+  } catch {
+    return content;
+  }
+}
+
 function resolveToolName(
   state: PiTranslatorState,
   nativeName: string,
@@ -307,7 +322,11 @@ export function translatePiEvent(
       if (!event.toolCallId || !event.toolName) return [];
       const { wire, native } = resolveToolName(state, event.toolName);
       state.observedToolNames.set(event.toolCallId, wire);
-      const providerExecuted = state.builtinToolNames.has(native);
+      const isMcpTool =
+        !state.hostToolNames.has(native) &&
+        (native === 'mcp' || native.startsWith('mcp__'));
+      const providerExecuted = state.builtinToolNames.has(native) || isMcpTool;
+      if (isMcpTool) state.dynamicToolCallIds.add(event.toolCallId);
       const input = serializeToolOutput(event.args ?? event.input ?? {});
       return [
         {
@@ -317,6 +336,7 @@ export function translatePiEvent(
           input,
           ...(wire !== native ? { nativeName: native } : {}),
           ...(providerExecuted ? { providerExecuted: true } : {}),
+          ...(isMcpTool ? { dynamic: true } : {}),
         } as HarnessV1StreamPart,
       ];
     }
@@ -330,6 +350,7 @@ export function translatePiEvent(
         recordedName ??
         (nativeName ? resolveToolName(state, nativeName).wire : undefined);
       if (!wire) return [];
+      const dynamic = state.dynamicToolCallIds.delete(event.toolCallId);
       /*
        * Prefer the exact value the host submitted for user-registered tools
        * (see `hostToolResults`). Built-in tools, whose results Pi produces and
@@ -341,7 +362,9 @@ export function translatePiEvent(
             HarnessV1StreamPart,
             { type: 'tool-result' }
           >['result'])
-        : unwrapPiToolResult(event);
+        : dynamic
+          ? parseMcpToolResult(unwrapPiToolResult(event))
+          : unwrapPiToolResult(event);
       state.hostToolResults.delete(event.toolCallId);
       state.pendingStepToolCallIds.delete(event.toolCallId);
       return [
@@ -351,6 +374,7 @@ export function translatePiEvent(
           toolName: wire,
           result,
           ...(event.isError ? { isError: true } : {}),
+          ...(dynamic ? { dynamic: true } : {}),
         } as HarnessV1StreamPart,
         ...finishStep(state),
       ];