@fitchmultz/pi-mcp-adapter 5.0.0 → 7.0.0

package/dist/types.d.ts

@@ -13,6 +13,8 @@ export interface McpServerStatusSnapshot {
     readonly name: string;
     readonly status: McpServerRuntimeStatus;
     readonly toolCount: number;
+    /** False means the server has not been discovered, rather than an empty inventory. */
+    readonly catalogKnown?: boolean;
     readonly resourceCount?: number;
     readonly failedAgoSeconds?: number;
     readonly disabled: boolean;
@@ -30,21 +32,10 @@ type SdkTool = ListToolsResult["tools"][number];
 type SdkResource = ListResourcesResult["resources"][number];
 type SdkPrompt = ListPromptsResult["prompts"][number];
 type SdkPromptArgument = NonNullable<SdkPrompt["arguments"]>[number];
-export interface McpTool {
-    name: SdkTool["name"];
-    title?: SdkTool["title"];
-    description?: SdkTool["description"];
+export interface McpTool extends Omit<SdkTool, "inputSchema"> {
     inputSchema?: SdkTool["inputSchema"];
-    annotations?: SdkTool["annotations"];
-    _meta?: SdkTool["_meta"];
-}
-export interface McpResource {
-    uri: SdkResource["uri"];
-    name: SdkResource["name"];
-    description?: SdkResource["description"];
-    mimeType?: SdkResource["mimeType"];
-    _meta?: SdkResource["_meta"];
 }
+export type McpResource = SdkResource;
 export interface McpPromptArgument {
     name: SdkPromptArgument["name"];
     description?: SdkPromptArgument["description"];
@@ -327,7 +318,7 @@ export interface McpSettings {
     /** Freeze direct-tool registration after the initial sync. Automatic metadata updates
      * (reconnects, lazy-connect, tool-list-changed) won't rebuild the system prompt,
      * preserving the prompt-cache prefix. The agent rediscovers explicitly via
-     * mcp({ connect: "server" }). Default: false. */
+     * mcp({ action: "connect", server: "server" }). Default: false. */
     freezeDirectTools?: boolean;
     autoAuth?: boolean;
     sampling?: boolean;
@@ -411,15 +402,14 @@ export interface McpAdapterOptions {
     onToolCall?: (event: McpToolCallEvent) => Promise<void>;
 }
 export type ServerDefinition = ServerEntry;
-export interface ToolMetadata {
+export interface ToolMetadata extends Omit<McpTool, "name" | "description"> {
     name: string;
     originalName: string;
     description: string;
     resourceUri?: string;
+    resourceDescriptor?: McpResource;
     uiResourceUri?: string;
     uiVisibility?: UiToolVisibility[];
-    inputSchema?: unknown;
-    annotations?: McpTool["annotations"];
     uiStreamMode?: UiStreamMode;
 }
 export interface PromptMetadata {
@@ -430,16 +420,9 @@ export interface PromptMetadata {
     description: string;
     arguments: McpPromptArgument[];
 }
-export interface DirectToolSpec {
+export interface DirectToolSpec extends Omit<ToolMetadata, "name"> {
     serverName: string;
-    originalName: string;
     prefixedName: string;
-    description: string;
-    inputSchema?: unknown;
-    annotations?: McpTool["annotations"];
-    resourceUri?: string;
-    uiResourceUri?: string;
-    uiStreamMode?: UiStreamMode;
 }
 export interface ServerProvenance {
     path: string;
@@ -450,20 +433,12 @@ export interface McpAuthResult {
     ok: boolean;
     message?: string;
 }
-export interface CachedTool {
-    name: string;
-    description?: string;
-    inputSchema?: unknown;
-    annotations?: McpTool["annotations"];
+export interface CachedTool extends McpTool {
     uiResourceUri?: string;
     uiVisibility?: UiToolVisibility[];
-    uiStreamMode?: "eager" | "stream-first";
-}
-export interface CachedResource {
-    uri: string;
-    name: string;
-    description?: string;
+    uiStreamMode?: UiStreamMode;
 }
+export type CachedResource = McpResource;
 export interface CachedPrompt {
     name: string;
     title?: string;

package/dist/ui-resource-handler.d.ts

@@ -7,10 +7,10 @@ interface ReadUiResourceOptions {
     onNeedsAuth?: SessionRecoveryDeps["onNeedsAuth"];
 }
 export declare class UiResourceHandler {
+    private log;
     private manager;
     private config;
-    private log;
-    constructor(manager: McpServerManager, config?: McpConfig | undefined);
+    constructor(manager: McpServerManager, config?: McpConfig);
     readUiResource(serverName: string, uri: string, options?: ReadUiResourceOptions): Promise<UiResourceContent>;
     private getListResourceMeta;
 }

package/dist/ui-resource-handler.js

@@ -4,10 +4,10 @@ import { logger } from "./logger.js";
 import { SessionRecoveryAuthRequiredError, withSessionRecovery } from "./session-recovery.js";
 import { isServerDisabled } from "./types.js";
 export class UiResourceHandler {
+    log = logger.child({ component: "UiResourceHandler" });
     manager;
     config;
-    log = logger.child({ component: "UiResourceHandler" });
-    constructor(manager, config = undefined) {
+    constructor(manager, config) {
         this.manager = manager;
         this.config = config;
     }

package/dist/ui-server.js

@@ -1,4 +1,4 @@
-import http from "node:http";
+import http, {} from "node:http";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
@@ -10,7 +10,7 @@ import { logger } from "./logger.js";
 import { SessionRecoveryAuthRequiredError, withSessionRecovery } from "./session-recovery.js";
 import { ensureToolCallApproved, isToolCallApprovalRequired } from "./tool-approval.js";
 import { extractUiToolVisibility, isUiToolCallableByApp } from "./ui-tool-visibility.js";
-import { createUiModelContextUpdate, extractUiPromptText, getVisualizationStreamEnvelope, isServerDisabled, } from "./types.js";
+import { createUiModelContextUpdate, extractUiPromptText, getVisualizationStreamEnvelope, isServerDisabled, isToolAllowed, resolveToolPrefix, } from "./types.js";
 const MAX_BODY_SIZE = 2 * 1024 * 1024;
 const ABANDONED_GRACE_MS = 60_000;
 const WATCHDOG_INTERVAL_MS = 5_000;
@@ -299,9 +299,10 @@ export async function startUiServer(options) {
                     sendJson(res, 503, { ok: false, error: `Server "${options.serverName}" is disabled` });
                     return;
                 }
+                const definition = options.config?.mcpServers[options.serverName] ?? connection.definition;
                 const toolDefinitions = Array.isArray(connection.tools) ? connection.tools : [];
                 const toolDefinition = toolDefinitions.find((tool) => tool.name === callParams.name);
-                if (!toolDefinition) {
+                if (!toolDefinition || !isToolAllowed(callParams.name, options.serverName, resolveToolPrefix(definition, options.config?.settings?.toolPrefix), definition?.includeTools, definition?.excludeTools)) {
                     sendJson(res, 403, { ok: false, error: `MCP tool "${callParams.name}" is not callable by apps` });
                     return;
                 }

package/dist/ui-stream-types.d.ts

@@ -10,17 +10,17 @@ export declare const uiStreamModeSchema: z.ZodEnum<{
 }>;
 export type UiStreamMode = z.infer<typeof uiStreamModeSchema>;
 export declare const visualizationStreamPhaseSchema: z.ZodEnum<{
-    shell: "shell";
-    narrative: "narrative";
-    structure: "structure";
     detail: "detail";
+    narrative: "narrative";
     settled: "settled";
+    shell: "shell";
+    structure: "structure";
 }>;
 export type VisualizationStreamPhase = z.infer<typeof visualizationStreamPhaseSchema>;
 export declare const visualizationStreamFrameTypeSchema: z.ZodEnum<{
-    patch: "patch";
     checkpoint: "checkpoint";
     final: "final";
+    patch: "patch";
 }>;
 export type VisualizationStreamFrameType = z.infer<typeof visualizationStreamFrameTypeSchema>;
 export declare const visualizationStreamStatusSchema: z.ZodEnum<{
@@ -42,16 +42,16 @@ export declare const visualizationStreamEnvelopeSchema: z.ZodObject<{
     streamId: z.ZodString;
     sequence: z.ZodNumber;
     frameType: z.ZodEnum<{
-        patch: "patch";
         checkpoint: "checkpoint";
         final: "final";
+        patch: "patch";
     }>;
     phase: z.ZodEnum<{
-        shell: "shell";
-        narrative: "narrative";
-        structure: "structure";
         detail: "detail";
+        narrative: "narrative";
         settled: "settled";
+        shell: "shell";
+        structure: "structure";
     }>;
     status: z.ZodEnum<{
         error: "error";

package/dist/unix-socket-transport.d.ts

@@ -2,12 +2,12 @@ import type { Transport } from "@modelcontextprotocol/client";
 import type { JSONRPCMessage } from "@modelcontextprotocol/client";
 /** MCP JSONL transport for an explicitly configured Unix-domain socket. */
 export declare class UnixSocketClientTransport implements Transport {
-    private readonly socketPath;
     private socket;
     private readonly readBuffer;
     onclose?: () => void;
     onerror?: (error: Error) => void;
     onmessage?: (message: JSONRPCMessage) => void;
+    private readonly socketPath;
     constructor(socketPath: string);
     start(): Promise<void>;
     close(): Promise<void>;

package/dist/unix-socket-transport.js

@@ -2,12 +2,12 @@ import { createConnection } from "node:net";
 import { ReadBuffer, serializeMessage } from "@modelcontextprotocol/client";
 /** MCP JSONL transport for an explicitly configured Unix-domain socket. */
 export class UnixSocketClientTransport {
-    socketPath;
     socket;
     readBuffer = new ReadBuffer();
     onclose;
     onerror;
     onmessage;
+    socketPath;
     constructor(socketPath) {
         this.socketPath = socketPath;
     }

package/dist/utils.d.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { McpConfig, ServerEntry } from "./types.ts";
+export declare const ADAPTER_VERSION: string;
 export declare function normalizeRequestTimeoutMs(timeoutMs: number | undefined): number | undefined;
 export declare function openUrl(pi: ExtensionAPI, url: string, browser?: string, signal?: AbortSignal): Promise<void>;
 export declare function openPath(pi: ExtensionAPI, targetPath: string): Promise<void>;

package/dist/utils.js

@@ -1,6 +1,20 @@
 import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { join } from "node:path";
+function readAdapterVersion() {
+    // Source modules sit beside package.json; compiled modules sit one level down in dist/.
+    for (const path of ["./package.json", "../package.json"]) {
+        try {
+            const manifest = JSON.parse(readFileSync(new URL(path, import.meta.url), "utf8"));
+            if (manifest.name === "@fitchmultz/pi-mcp-adapter" && typeof manifest.version === "string")
+                return manifest.version;
+        }
+        catch { }
+    }
+    return "0.0.0";
+}
+export const ADAPTER_VERSION = readAdapterVersion();
 export function normalizeRequestTimeoutMs(timeoutMs) {
     return typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0
         ? timeoutMs
@@ -246,11 +260,9 @@ export function truncateAtWord(text, target) {
     return truncated + "...";
 }
 export function normalizeDirectToolInputSchema(schema) {
-    const inputSchema = schema && typeof schema === "object" && !Array.isArray(schema)
-        ? schema
+    return schema && typeof schema === "object" && !Array.isArray(schema)
+        ? structuredClone(schema)
         : { type: "object", properties: {} };
-    const { $schema, additionalProperties, ...normalized } = inputSchema;
-    return normalized;
 }
 export function formatAuthRequiredMessage(config, serverName, defaultMessage) {
     const template = config.settings?.authRequiredMessage;

package/package.json

@@ -1,42 +1,44 @@
 {
   "name": "@fitchmultz/pi-mcp-adapter",
-  "version": "5.0.0",
+  "version": "7.0.0",
   "description": "Fitch's independently maintained MCP adapter for Pi coding agent",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./index.ts",
-      "default": "./index.ts"
+      "default": "./dist/index.js"
     },
     "./types": {
       "types": "./dist/types.d.ts",
-      "import": "./types.ts",
-      "default": "./types.ts"
+      "default": "./dist/types.js"
     }
   },
   "license": "MIT",
   "author": "Mitch Fultz",
-  "contributors": ["Nico Bailon"],
+  "contributors": [
+    "Nico Bailon"
+  ],
   "homepage": "https://github.com/fitchmultz/pi-mcp-adapter",
   "bugs": "https://github.com/fitchmultz/pi-mcp-adapter/issues",
-  "publishConfig": { "access": "public" },
+  "publishConfig": {
+    "access": "public"
+  },
   "engines": {
-    "node": ">=22.19.0"
+    "node": ">=24.0.0"
   },
   "bin": {
     "fitch-mcp-adapter": "cli.js"
   },
   "scripts": {
     "build": "node ./scripts/build.mjs",
+    "build:bridge": "node ./scripts/build-app-bridge.mjs",
     "prepare": "node ./scripts/prepare.mjs",
+    "check:compat": "node scripts/compat-host.mjs && npm run build && npm run typecheck && vitest run --exclude __tests__/interactive-visualizer-server.test.ts && npm run test:oauth && node scripts/compat-package-smoke.mjs",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
+    "test": "vitest run && npm run test:oauth",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "test:oauth": "PI_MCP_ADAPTER_TEST_AUTH_STORE=memory node --import tsx --test --test-concurrency=1 mcp-auth.test.ts mcp-auth-flow.test.ts mcp-callback-server.test.ts mcp-oauth-provider.test.ts",
-    "test:oauth-provider": "PI_MCP_ADAPTER_TEST_AUTH_STORE=memory node --import tsx --test mcp-oauth-provider.test.ts",
+    "test:oauth": "PI_MCP_ADAPTER_TEST_AUTH_STORE=memory node --test --test-concurrency=1 mcp-auth.test.ts mcp-auth-flow.test.ts mcp-callback-server.test.ts mcp-oauth-provider.test.ts",
     "test:conformance": "bash conformance/run.sh"
   },
   "repository": {
@@ -65,92 +67,31 @@
   },
   "files": [
     "dist",
-    "docs/client-metadata.json",
-    "scripts/build.mjs",
-    "scripts/prepare.mjs",
-    "tsconfig.build.json",
-    "tsconfig.json",
     "cli.js",
-    "agent-dir.ts",
-    "legacy-migration.ts",
-    "index.ts",
-    "error-signal.ts",
-    "state.ts",
-    "utils.ts",
-    "abort.ts",
-    "runtime-owner.ts",
-    "checkpoint.ts",
-    "tool-metadata.ts",
-    "ts-shape.ts",
-    "search-ranking.ts",
-    "tool-approval.ts",
-    "init.ts",
-    "ui-session.ts",
-    "proxy-modes.ts",
-    "direct-tools.ts",
-    "commands.ts",
-    "prompts.ts",
-    "onboarding-state.ts",
-    "mcp-setup-panel.ts",
-    "types.ts",
-    "ui-stream-types.ts",
-    "ui-tool-visibility.ts",
-    "config.ts",
-    "server-manager.ts",
-    "unix-socket-transport.ts",
-    "session-recovery.ts",
-    "sampling-handler.ts",
-    "elicitation-handler.ts",
-    "tool-registrar.ts",
-    "tool-result-renderer.ts",
-    "mcp-output-guard.ts",
-    "mcp-code.ts",
-    "mcp-script-worker.mjs",
-    "resource-tools.ts",
-    "lifecycle.ts",
-    "mcp-status.ts",
-    "metadata-cache.ts",
-    "host-html-template.ts",
-    "ui-resource-handler.ts",
-    "consent-manager.ts",
-    "ui-server.ts",
-    "glimpse-ui.ts",
-    "npx-resolver.ts",
-    "mcp-auth.ts",
-    "mcp-keyring-helper.cjs",
-    "mcp-oauth-provider.ts",
-    "mcp-callback-server.ts",
-    "mcp-auth-flow.ts",
-    "mcp-panel.ts",
-    "panel-keys.ts",
-    "mcp-trace.ts",
-    "logger.ts",
-    "app-bridge.bundle.js",
-    "banner.png",
     "skills",
+    "docs/client-metadata.json",
     "README.md",
     "OAUTH.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "dependencies": {
-    "@modelcontextprotocol/client": "2.0.0",
-    "@modelcontextprotocol/core": "2.0.0",
-    "@modelcontextprotocol/ext-apps": "^1.7.5",
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "@napi-rs/keyring": "^1.3.0",
-    "cross-spawn": "^7.0.6",
-    "open": "^10.2.0",
-    "smol-toml": "^1.8.0",
-    "strip-json-comments": "^5.0.3",
-    "zod": "^3.25.0 || ^4.0.0"
+    "@modelcontextprotocol/client": "2.1.0",
+    "@modelcontextprotocol/core": "2.1.0",
+    "@modelcontextprotocol/ext-apps": "2.0.0",
+    "@napi-rs/keyring": "2.1.0",
+    "cross-spawn": "7.0.6",
+    "minisearch": "7.2.0",
+    "open": "11.0.4",
+    "smol-toml": "1.9.0",
+    "strip-json-comments": "5.0.3",
+    "zod": "4.6.5"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
-    "typebox": "*",
-    "zod": "^3.25.0 || ^4.0.0"
+    "typebox": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-ai": {
@@ -167,16 +108,16 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.84.0",
-    "@earendil-works/pi-coding-agent": "0.84.0",
-    "@earendil-works/pi-tui": "0.84.0",
-    "@modelcontextprotocol/conformance": "0.1.16",
-    "@modelcontextprotocol/server": "2.0.0",
+    "@earendil-works/pi-ai": "0.87.1",
+    "@earendil-works/pi-coding-agent": "0.87.1",
+    "@earendil-works/pi-tui": "0.87.1",
+    "@modelcontextprotocol/server": "2.1.0",
     "@types/cross-spawn": "6.0.6",
-    "@types/node": "20.19.43",
-    "tsx": "^4.21.0",
-    "typebox": "1.3.7",
-    "typescript": "5.9.3",
-    "vitest": "^3.0.0"
-  }
+    "@types/node": "24.19.0",
+    "esbuild": "0.28.2",
+    "typebox": "1.3.34",
+    "typescript": "7.0.2",
+    "vitest": "5.0.2"
+  },
+  "packageManager": "npm@12.1.0"
 }

package/skills/mcp-scripting/SKILL.md

@@ -1,38 +1,85 @@
 ---
 name: mcp-scripting
-description: Write mcp_script JavaScript for discovering, inspecting, and calling MCP tools.
+description: Write mcp_script JavaScript for discovering, inspecting, and calling MCP tools, resources, and saved results.
 ---
 
 # MCP scripting
 
-For multi-call MCP work, write ordinary JavaScript with loops, filtering, chaining, fan-out, or other logic between calls. Run that source with `mcp_script`; it is the primary MCP orchestration surface. For a single MCP search, describe, status check, auth action, or tool call, use `mcp` instead.
+Use `mcp_script` for MCP calls with loops, filtering, chaining, fan-out, or other logic between calls. Pass ordinary JavaScript as its `code` argument. For a single call, use an already loaded typed tool. Use `mcp_search({ query, server?, limit?, offset? })` to discover and load typed tools for the next request, or explicit `mcp` actions for gateway-only workflows. Discovery never executes a search hit.
 
-Write the source naturally, then pass it as `mcp_script`'s `code` argument:
+## Discover, inspect, then call
 
 ```js
-const { items } = await tools.search({ query: "search issues", server: "github" });
-const candidate = items[0];
-if (!candidate) return { error: "No matching tool" };
+const found = await tools.search({ query: "search issues", server: "github" });
+if (found.error) return found;
+emit(found.coverage);
+for (const item of found.items) {
+  emit(await tools.describe({ path: item.path, server: item.server }));
+}
+```
+
+Read the returned descriptors and choose the tool that matches the task. Do not call the first ranked hit without checking its identity and schema. In a subsequent script, use its exact returned path and schema-correct arguments:
+
+```js
+const results = [];
+for (const query of ["is:open label:bug", "is:open label:docs"]) {
+  const result = await tools.call("github_search_issues", { query });
+  if (!result.ok) return result;
+  results.push({ query, data: result.data });
+}
+return results;
+```
+
+## API and return shapes
+
+- `await tools.search({ query, server?, limit?, offset? })` returns `{ items, total, hasMore, nextOffset, coverage }`. Items carry `path`, `name`, `server`, optional `description`, and `score`. Discovery failures return `{ error, coverage }`. Script search defaults to **12** items, maximum **100**, with zero-based item offsets. The separate `mcp_search` loader defaults to **5**.
+- `coverage` is `{ complete, knownServers, unknownServers }`. Global search covers known catalogs without starting every lazy server. Select an uncached server to discover it. Script search does not activate typed tools.
+- `await tools.describe({ path, server? })` returns the complete tool descriptor with `path`, `server`, original `name`, and all server-supplied fields, including `inputSchema`, `outputSchema`, `title`, `annotations`, and `_meta` when present. It never substitutes `inputTypeScript`. Failures return `{ path, error: { code, message, suggestions? } }`. Supply `server` to disambiguate a name.
+- `await tools.call(path, args, server?)` returns `{ ok: true, data, resultRef? }` or `{ ok: false, error: { code, message, ... }, data?, resultRef? }`. `data` is the **raw MCP result**, including raw error-result data when available. Tools usually return `{ content, structuredContent?, isError?, ... }`; resource reads return `{ contents, ... }`.
+- If a flat path is ambiguous, call `tools.call(descriptor.name, args, descriptor.server)` with the exact original name and server returned by describe.
+- `await tools.resources({ server, limit?, offset? })` returns `{ mode: "resources", server, items, total, hasMore, nextOffset }`, or `{ error: { code, message } }`. Items preserve resource descriptors, including the exact `uri`, name, title, MIME type, description, icons, and `_meta` when supplied; pages default to 12, maximum 100.
+- `await tools.readResource({ server, uri })` returns the same call envelope as `tools.call`, with raw resource contents in `data.contents`. Resources are separate from typed functions. Legacy `read_<resource>` call aliases remain compatible, but prefer this URI-based API.
+- `await tools.readResult({ ref, path?, fields?, offset?, limit? })` returns `{ content, details }`, not a call envelope. `content` contains readback text; `details` contains `ref`, `offset`, `nextOffset`, `totalCharacters`, and the selected `path` when supplied. Failures contain `details.error` and `details.message`.
+- `emit(value)` adds model-visible output before the final `return`; `console` output is captured too.
+
+Treat `structuredContent` as structured data even alongside text or image blocks. Only parse a text block as JSON when the server documents that format. Handle `ok: false`: ordinary failed calls do not stop a script automatically. A call-capture failure stops dependent work. An ambiguous outcome requires provider readback before considering another write; never blindly repeat a call or rerun its whole script.
 
-const details = await tools.describe({ path: candidate.path });
-if (details.error) return details;
+## Saved-result readback
 
-const result = await tools.call(details.path, { query: "is:open label:bug" });
-if (!result.ok) return result;
-emit({ tool: details.path, completed: true });
-return result.data?.structuredContent ?? result.data;
+Structured, media, resource, oversized, and extra-field results retain a raw artifact with a model-visible result reference. Small plain-text-only results stay inline. To inspect an existing reference without another MCP call:
+
+```js
+const page = await tools.readResult({
+  ref: "/returned/result/path",
+  path: "/structuredContent/rows",
+  fields: ["id", "title"],
+  offset: 0,
+  limit: 12000,
+});
+return page;
+```
+
+`path` is an RFC 6901 JSON Pointer. `fields` retains immediate keys on the selected object or every object in a selected array. Selection precedes paging. `offset` and `limit` are **zero-based character positions in the selected, pretty-printed JSON**, not rows, lines, or bytes. The default limit is 12,000 characters; output byte/line caps still apply. Continue with `details.nextOffset` until it is `null`. References must identify existing adapter artifacts in the host's output directory. Readback never re-calls the server and is not a general filesystem API.
+
+Gateway equivalents require explicit actions:
+
+```js
+mcp({ action: "search", query: "search issues", server: "github" })
+mcp({ action: "describe", tool: "github_search_issues" })
+mcp({ action: "call", tool: "github_search_issues", args: { query: "is:open" } })
+mcp({ action: "resources", server: "docs" })
+mcp({ action: "read-resource", server: "docs", uri: "docs://guide" })
+mcp({ action: "read-result", ref: "/returned/result/path", path: "/structuredContent" })
 ```
 
-## Workflow
+Gateway search returns schemas without activating functions; use it when only `mcp` is allowed. New gateway calls use object `args`. Optional v5 mode fields and JSON-string arguments are only a stored-call ingress compatibility path.
 
-1. Find candidate tools with `await tools.search({ query, server?, limit?, offset? })`. `limit` defaults to 12 and is capped at 100.
-2. Inspect the exact returned path with `await tools.describe({ path })`. Arguments are described by `inputTypeScript` when representable, otherwise by the original JSON Schema in `inputSchema`; only one is included.
-3. Call it with `tools.call(path, args)`.
+## Execution rules
 
-Calls resolve to `{ ok: true, data }` or `{ ok: false, error }`; handle failed calls instead of expecting them to stop the script. Successful `data` is the raw MCP result: tool calls usually return `{ content, structuredContent? }`, while resource reads return `{ contents }`. Prefer `structuredContent` when present, and only parse a text block when that server documents JSON text. `emit(value)` adds user-visible output before the final `return` value. `console` output is captured too.
+`tools` is a non-enumerable proxy: `Object.keys(tools)` throws. Use `tools.search` for discovery. Known flat paths support `tools.github_search_issues(args)` or `tools["server_tool-name"](args)`. Proxy API and promise/serialization names are reserved (`search`, `describe`, `call`, `resources`, `listResources`, `readResource`, `readResult`, `then`, `catch`, `finally`, `toJSON`, `toString`, `valueOf`); use `tools.call("exact-path", args)` for collisions.
 
-`tools` is a non-enumerable proxy: `Object.keys(tools)` throws. Always use `tools.search` for discovery. When a known flat path is a valid identifier, direct calls such as `tools.github_search_issues(args)` are supported; use bracket syntax for hyphenated names: `tools["server_tool-name"](args)`. `search`, `call`, `describe`, and promise/serialization names (`then`, `catch`, `finally`, `toJSON`, `toString`, `valueOf`) are reserved on the proxy; if a flat path collides with one, call it via `tools.call("exact-path", args)`.
+Await every operation, including all promises started with `Promise.all`, before returning. Calls use the shared authentication, approval, filtering, cancellation, and capture path. Resources honor `exposeResources` and include/exclude policy. Raw results are cloned into the worker before model-facing rendering; reduce them before emitting to avoid unnecessary context. Result details include a concise search/describe/call trace and saved-result references.
 
-`tools.search` and `tools.describe` are asynchronous and must be awaited. The default script timeout is 30 seconds unless the SDK host overrides or disables it (see the registered `timeoutMs` description); explicit per-script timeouts still apply, and the worker is terminated on timeout or cancellation, including for infinite loops. Every invocation still uses normal lazy connection, authentication, output guarding, and approval gates. Raw call results are cloned into the worker so scripts can reduce them before the model-facing guard; request scoped data instead of unnecessarily large payloads. Result details contain a concise `calls` trace with every search, describe, and call operation; each entry includes its query or path, outcome, and duration.
+The default overall script timeout is 30 seconds unless the host overrides or disables it; an explicit per-script `timeoutMs` wins. Individual MCP request deadlines still apply. The local worker terminates on timeout or cancellation, including infinite loops. This is trusted agent-authored local orchestration, not provider-native programmatic tool calling or an isolation boundary; Codex native PTC is not implied.
 
-Use plain JavaScript loops and Promise utilities for composition. The sandbox has no Node, filesystem, or network globals such as `process`, `Buffer`, or `fetch`. Fluent helpers such as `tools.find(...).one()`, `tools.parallel(...)`, and `tools.retry(...)` are not provided.
+The worker exposes no Node, filesystem, or network globals such as `process`, `Buffer`, or `fetch`. Use normal JavaScript loops and Promise utilities; fluent helpers such as `tools.find(...).one()`, `tools.parallel(...)`, and `tools.retry(...)` do not exist. Run Pi in an isolated environment if you need isolation.

package/abort.ts

@@ -1,34 +0,0 @@
-export function throwIfAborted(signal?: AbortSignal): void {
-  if (!signal?.aborted) return;
-  throw signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason ?? "MCP request aborted"));
-}
-
-export async function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
-  if (!signal) return promise;
-  throwIfAborted(signal);
-  return await new Promise<T>((resolve, reject) => {
-    let settled = false;
-    const cleanup = () => signal.removeEventListener("abort", onAbort);
-    const onAbort = () => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      reject(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason ?? "MCP request aborted")));
-    };
-    signal.addEventListener("abort", onAbort, { once: true });
-    promise.then(
-      value => {
-        if (settled) return;
-        settled = true;
-        cleanup();
-        resolve(value);
-      },
-      error => {
-        if (settled) return;
-        settled = true;
-        cleanup();
-        reject(error);
-      },
-    );
-  });
-}

package/agent-dir.ts

@@ -1,24 +0,0 @@
-import { homedir } from "node:os";
-import { join, resolve } from "node:path";
-
-export function getAgentDir(): string {
-  const configured = process.env.PI_CODING_AGENT_DIR?.trim();
-  if (!configured) {
-    return join(homedir(), ".pi", "agent");
-  }
-  if (configured === "~") {
-    return homedir();
-  }
-  if (configured.startsWith("~/")) {
-    return resolve(homedir(), configured.slice(2));
-  }
-  return resolve(configured);
-}
-
-export function getAgentPath(...segments: string[]): string {
-  return join(getAgentDir(), ...segments);
-}
-
-export function getAdapterPath(...segments: string[]): string {
-  return getAgentPath("fitch-mcp-adapter", ...segments);
-}