@fitchmultz/pi-mcp-adapter 5.0.0 → 6.0.0

package/resource-tools.ts

@@ -1,4 +1,39 @@
-// resource-tools.ts - MCP resource name utilities
+import type { McpExtensionState } from "./state.ts";
+import { isServerDisabled, isToolAllowed, resolveToolPrefix, type McpOperationContext, type McpToolCallIdentity } from "./types.ts";
+import { executeCall, prepareMcpConnection } from "./proxy-modes.ts";
+import { paginate } from "./search-ranking.ts";
+import { throwIfAborted } from "./abort.ts";
+import { combineAbortSignals } from "./runtime-owner.ts";
+
+export async function executeResourceList(state: McpExtensionState, server: string, limit = 12, offset = 0, signal?: AbortSignal) {
+  throwIfAborted(combineAbortSignals(state.owner?.signal, signal));
+  const definition = state.config.mcpServers[server];
+  if (!definition || isServerDisabled(definition)) {
+    return { content: [{ type: "text" as const, text: `Server "${server}" is ${definition ? "disabled" : "not configured"}.` }], details: { mode: "resources", server, error: definition ? "server_disabled" : "server_not_found" } };
+  }
+  if (!state.toolMetadata.has(server) || state.manager.getConnection(server)?.status === "connected") {
+    const prepared = await prepareMcpConnection(state, server, signal);
+    if (prepared.error) return prepared.error;
+  }
+  const prefix = resolveToolPrefix(definition, state.config.settings?.toolPrefix);
+  const page = paginate((state.toolMetadata.get(server) ?? [])
+    .filter(tool => tool.resourceUri !== undefined && definition.exposeResources !== false
+      && isToolAllowed(tool.originalName, server, prefix, definition.includeTools, definition.excludeTools))
+    .map(tool => tool.resourceDescriptor ?? { uri: tool.resourceUri!, description: tool.description }), offset, limit);
+  return { content: [{ type: "text" as const, text: JSON.stringify({ server, ...page }, null, 2) }], details: { mode: "resources", server, ...page } };
+}
+
+export async function executeResourceRead(
+  state: McpExtensionState,
+  server: string,
+  uri: string,
+  signal?: AbortSignal,
+  identity: McpToolCallIdentity = {},
+  beforeDispatch?: (signal: AbortSignal | undefined, operation: McpOperationContext) => Promise<void>,
+  raw = false,
+) {
+  return executeCall(state, uri, {}, server, undefined, signal, identity, beforeDispatch, { resourceUri: uri, raw });
+}
 
 export function resourceNameToToolName(name: string): string {
   let result = name

package/sampling-handler.ts

@@ -65,6 +65,9 @@ export async function handleSamplingRequest(
   );
   throwIfAborted(signal);
 
+  const supportsTemperature = model.compat && "supportsTemperature" in model.compat
+    ? model.compat.supportsTemperature !== false
+    : !(model.id === "gpt-6-astra" && (model.api === "openai-responses" || model.api === "openai-codex-responses"));
   const result = await options.modelRegistry.complete(
     model,
     {
@@ -73,7 +76,7 @@ export async function handleSamplingRequest(
     },
     {
       maxTokens: params.maxTokens,
-      ...(params.temperature !== undefined ? { temperature: params.temperature } : {}),
+      ...(supportsTemperature && params.temperature !== undefined ? { temperature: params.temperature } : {}),
       ...(params.metadata !== undefined ? { metadata: params.metadata as Record<string, unknown> } : {}),
       ...(signal ? { signal } : {}),
     },

package/scripts/build-app-bridge.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { build } from "esbuild";
+
+await build({
+  stdin: {
+    contents: 'export { AppBridge, PostMessageTransport } from "@modelcontextprotocol/ext-apps/app-bridge";',
+    resolveDir: process.cwd(),
+  },
+  bundle: true,
+  platform: "browser",
+  format: "esm",
+  target: "es2022",
+  minify: true,
+  outfile: process.argv[2] ?? "app-bridge.bundle.js",
+});

package/scripts/build.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * Purpose: Produce the compiled runtime files that the Pi extension manifest loads.
- * Responsibilities: Run TypeScript emit into a staging directory, copy runtime assets
+ * Responsibilities: Run TypeScript emit and bundle the browser bridge into staging, copy runtime assets
  * that modules resolve as dist-relative siblings, then atomically swap it into dist/
  * so a failed TypeScript emit never destroys a previously working dist.
  * Usage: `npm run build`; also invoked by scripts/prepare.mjs during install lifecycles.
@@ -25,7 +25,7 @@ const RENAME_RETRY_MS = 50;
 const tscPath = join(process.cwd(), "node_modules", "typescript", "bin", "tsc");
 // Runtime siblings resolved relative to the compiled module directory
 // (mcp-auth.ts, mcp-code.ts, ui-server.ts).
-const RUNTIME_ASSETS = ["mcp-keyring-helper.cjs", "mcp-script-worker.mjs", "app-bridge.bundle.js"];
+const RUNTIME_ASSETS = ["mcp-keyring-helper.cjs", "mcp-script-worker.mjs"];
 
 async function discardStaging(path) {
 	try {
@@ -75,6 +75,7 @@ async function compileToStaging(cwd, stagingDir) {
 		);
 		if (stdout) process.stdout.write(stdout);
 		if (stderr) process.stderr.write(stderr);
+		await execFile(process.execPath, [join(cwd, "scripts", "build-app-bridge.mjs"), join(stagingDir, "app-bridge.bundle.js")], { cwd });
 		for (const asset of RUNTIME_ASSETS) await copyFile(join(cwd, asset), join(stagingDir, asset));
 	} catch (error) {
 		if (error?.stdout) process.stdout.write(error.stdout);

package/scripts/prepare.mjs

@@ -20,6 +20,7 @@ const execFile = promisify(execFileCallback);
 // several @earendil-works packages expose import-only "exports" maps and throw
 // ERR_PACKAGE_PATH_NOT_EXPORTED even when installed.
 const REQUIRED_SOURCE_BUILD_MODULES = [
+	"esbuild",
 	"typescript",
 	"typebox",
 	"@earendil-works/pi-ai",

package/search-ranking.ts

@@ -1,23 +1,11 @@
+import MiniSearch, { type SearchOptions } from "minisearch";
 import type { McpExtensionState } from "./state.ts";
 import type { ToolMetadata } from "./types.ts";
-import { getServerPrefix, isServerDisabled, resolveToolPrefix } from "./types.ts";
+import { getServerPrefix, isServerDisabled, isToolAllowed, resolveToolPrefix } from "./types.ts";
 
-/**
- * Shortest field token allowed to stem-match a longer query token.
- * Real descriptions tokenize possessives into single letters ("project's" -> ["project", "s"]),
- * which would otherwise make every query starting with that letter a match.
- */
-const MIN_STEM_LENGTH = 4;
 export const MAX_PAGE_SIZE = 100;
 export const MAX_TOOL_NAME_LENGTH = 512;
 
-const FIELD_WEIGHTS = {
-  name: 12,
-  originalName: 10,
-  server: 8,
-  description: 5,
-} as const;
-
 export interface RankedToolMatch {
   server: string;
   tool: ToolMetadata;
@@ -31,76 +19,78 @@ export function normalizeSearchText(value: string): string {
     .toLowerCase();
 }
 
-export function tokenize(value: string): string[] {
-  return normalizeSearchText(value).split(/[^a-z0-9]+/).filter(Boolean);
+function schemaSearchText(schema: unknown): string {
+  if (!schema || typeof schema !== "object") return "";
+  if (Array.isArray(schema)) return schema.map(schemaSearchText).join(" ");
+  return Object.entries(schema).flatMap(([key, value]) => {
+    if ((key === "description" || key === "title" || key === "const") && typeof value === "string") return value;
+    if (key === "enum" && Array.isArray(value)) return value.filter(item => typeof item === "string");
+    if (key === "properties" && value && typeof value === "object") return [Object.keys(value).join(" "), schemaSearchText(value)];
+    return schemaSearchText(value);
+  }).join(" ");
 }
 
-export function scoreToolMatch(tool: ToolMetadata, server: string, query: string): number | null {
-  const normalizedQuery = normalizeSearchText(query).trim();
-  const queryTokens = tokenize(query);
-  if (queryTokens.length === 0) return null;
-
-  const fields = {
-    name: normalizeSearchText(tool.name),
-    originalName: normalizeSearchText(tool.originalName),
-    server: normalizeSearchText(server),
-    description: normalizeSearchText(tool.description),
-  };
-  let score = 0;
-  let phraseMatched = false;
-  let wholeFieldExact = false;
-  const matchedTokens = new Set<string>();
+interface SearchDocument {
+  id: number;
+  server: string;
+  tool: ToolMetadata;
+  name: string;
+  originalName: string;
+  description: string;
+  schema: string;
+}
 
-  for (const [field, value] of Object.entries(fields) as Array<[keyof typeof FIELD_WEIGHTS, string]>) {
-    const weight = FIELD_WEIGHTS[field];
-    const fieldTokens = tokenize(value);
-    if (value === normalizedQuery) {
-      score += weight * 14;
-      phraseMatched = true;
-      wholeFieldExact = true;
-    } else if (value.startsWith(normalizedQuery)) {
-      score += weight * 9;
-      phraseMatched = true;
-    } else if (value.includes(normalizedQuery)) {
-      score += weight * 6;
-      phraseMatched = true;
-    }
+const indexes = new WeakMap<McpExtensionState, {
+  metadata: Map<string, ToolMetadata[]>;
+  index: MiniSearch<SearchDocument>;
+}>();
+
+function getIndex(state: McpExtensionState): MiniSearch<SearchDocument> {
+  const cached = indexes.get(state);
+  // Catalog publishers replace each server's metadata array on discovery/reconnect.
+  if (cached && cached.metadata.size === state.toolMetadata.size
+    && [...state.toolMetadata].every(([server, metadata]) => cached.metadata.get(server) === metadata)) {
+    return cached.index;
+  }
 
-    for (const token of queryTokens) {
-      if (fieldTokens.includes(token)) {
-        score += weight * 4;
-        matchedTokens.add(token);
-      } else if (fieldTokens.some(fieldToken => fieldToken.startsWith(token) || (fieldToken.length >= MIN_STEM_LENGTH && token.startsWith(fieldToken)))) {
-        score += weight * 2;
-        matchedTokens.add(token);
-      } else if (value.includes(token)) {
-        score += weight;
-        matchedTokens.add(token);
-      }
+  const index = new MiniSearch<SearchDocument>({
+    fields: ["name", "originalName", "description", "schema"],
+    storeFields: ["server", "tool"],
+    searchOptions: { fields: ["name", "description", "schema"], boost: { name: 2, description: 1, schema: 1 }, prefix: true },
+  });
+  let id = 0;
+  for (const [server, tools] of state.toolMetadata) {
+    for (const tool of tools) {
+      if (tool.resourceUri !== undefined) continue;
+      index.add({
+        id: id++, server, tool,
+        name: normalizeSearchText(tool.name),
+        originalName: normalizeSearchText(tool.originalName),
+        description: normalizeSearchText([tool.title, tool.description].filter(Boolean).join(" ")),
+        schema: normalizeSearchText(schemaSearchText(tool.inputSchema)),
+      });
     }
   }
+  indexes.set(state, { metadata: new Map(state.toolMetadata), index });
+  return index;
+}
 
-  const coverage = matchedTokens.size / queryTokens.length;
-  if (!phraseMatched && (queryTokens.length <= 2 ? coverage !== 1 : coverage < 0.6)) return null;
-
-  score += coverage === 1 ? 25 : Math.round(coverage * 10);
-  const firstQueryToken = queryTokens[0];
-  if (firstQueryToken !== undefined && tokenize(fields.name).includes(firstQueryToken)) score += 8;
-  if (wholeFieldExact) score += 20;
-  return score;
+function searchCatalog(state: McpExtensionState, query: string, server?: string, options?: SearchOptions): RankedToolMatch[] {
+  return getIndex(state).search(normalizeSearchText(query), {
+    ...options,
+    filter: result => {
+      if (server && result.server !== server) return false;
+      const definition = state.config.mcpServers[result.server];
+      if (!definition || isServerDisabled(definition)) return false;
+      const prefix = resolveToolPrefix(definition, state.config.settings?.toolPrefix);
+      return isToolAllowed(result.tool.originalName, result.server, prefix, definition.includeTools, definition.excludeTools);
+    },
+  }).map(({ server, tool, score }) => ({ server, tool, score }))
+    .sort((a, b) => b.score - a.score || a.tool.name.localeCompare(b.tool.name));
 }
 
 export function rankToolMatches(state: McpExtensionState, query: string, server?: string): RankedToolMatch[] {
-  const matches: RankedToolMatch[] = [];
-  for (const [serverName, metadata] of state.toolMetadata.entries()) {
-    if (server && serverName !== server) continue;
-    if (isServerDisabled(state.config.mcpServers[serverName])) continue;
-    for (const tool of metadata) {
-      const score = scoreToolMatch(tool, serverName, query);
-      if (score !== null) matches.push({ server: serverName, tool, score });
-    }
-  }
-  return matches.sort((a, b) => b.score - a.score || a.tool.name.localeCompare(b.tool.name));
+  return searchCatalog(state, query, server);
 }
 
 export function paginate<T>(items: T[], offset: number, limit: number): { items: T[]; total: number; hasMore: boolean; nextOffset: number | null } {
@@ -117,40 +107,6 @@ export function paginate<T>(items: T[], offset: number, limit: number): { items:
   };
 }
 
-function editDistance(a: string, b: string, maxDistance: number): number {
-  if (Math.abs(a.length - b.length) > maxDistance) return maxDistance + 1;
-  let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
-  for (let i = 1; i <= a.length; i++) {
-    const current = [i];
-    let rowMin = i;
-    for (let j = 1; j <= b.length; j++) {
-      current[j] = Math.min(
-        current[j - 1]! + 1,
-        previous[j]! + 1,
-        previous[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
-      );
-      rowMin = Math.min(rowMin, current[j]!);
-    }
-    if (rowMin > maxDistance) return maxDistance + 1;
-    previous = current;
-  }
-  return previous[b.length]!;
-}
-
-function rankClosest(tools: ToolMetadata[], query: string, limit: number, candidateName: (tool: ToolMetadata) => string): string[] {
-  const normalizedQuery = normalizeSearchText(query).replace(/\s+/g, "_");
-  const maxDistance = Math.max(2, Math.floor(normalizedQuery.length * 0.2));
-  return tools
-    .map(tool => ({
-      tool,
-      distance: editDistance(normalizedQuery, normalizeSearchText(candidateName(tool)).replace(/\s+/g, "_"), maxDistance),
-    }))
-    .filter(({ distance }) => distance <= maxDistance)
-    .sort((a, b) => a.distance - b.distance || a.tool.name.localeCompare(b.tool.name))
-    .slice(0, limit)
-    .map(({ tool }) => tool.name);
-}
-
 export function rankSuggestions(state: McpExtensionState, name: string, limit: number, server?: string): string[] {
   if (name.length > MAX_TOOL_NAME_LENGTH) return [];
 
@@ -165,32 +121,12 @@ export function rankSuggestions(state: McpExtensionState, name: string, limit: n
       Boolean(candidate.prefix) && name.startsWith(`${candidate.prefix}_`))
     .sort((a, b) => b.prefix.length - a.prefix.length)[0];
   const matchedServer = server ?? inferred?.server;
-  if (!matchedServer) {
-    const tools = [...state.toolMetadata.entries()]
-      .filter(([candidateServer]) => !isServerDisabled(state.config.mcpServers[candidateServer]))
-      .flatMap(([, metadata]) => metadata);
-    const closest = rankClosest(tools, name, limit, tool => tool.name);
-    return closest.length > 0 ? closest : rankToolMatches(state, name).slice(0, limit).map(match => match.tool.name);
-  }
-
-  const definition = state.config.mcpServers[matchedServer];
-  if (!definition || isServerDisabled(definition)) return [];
-  const prefix = inferred?.prefix ?? getServerPrefix(matchedServer, resolveToolPrefix(definition, globalPrefix));
+  const definition = matchedServer ? state.config.mcpServers[matchedServer] : undefined;
+  if (matchedServer && (!definition || isServerDisabled(definition))) return [];
+  const prefix = inferred?.prefix ?? (matchedServer ? getServerPrefix(matchedServer, resolveToolPrefix(definition, globalPrefix)) : "");
   const query = prefix && name.startsWith(`${prefix}_`) ? name.slice(prefix.length + 1) : name;
-  const tools = state.toolMetadata.get(matchedServer) ?? [];
-  const closest = rankClosest(tools, query, limit, tool => tool.originalName);
-  if (closest.length > 0) return closest;
-
-  const queryTokens = tokenize(query);
-  const tokenMatches = rankToolMatches(state, query, matchedServer)
-    .filter(({ tool }) => {
-      const candidateTokens = tokenize(tool.originalName);
-      return queryTokens.every(token => candidateTokens.some(candidate =>
-        candidate === token
-        || candidate.startsWith(token)
-        || (candidate.length >= MIN_STEM_LENGTH && token.startsWith(candidate))));
-    })
-    .slice(0, limit)
-    .map(match => match.tool.name);
-  return tokenMatches.length > 0 || !server ? tokenMatches : rankSuggestions(state, name, limit);
+  const suggestions = searchCatalog(state, query, matchedServer, {
+    fields: [matchedServer ? "originalName" : "name"], combineWith: "AND", fuzzy: 2,
+  }).slice(0, limit).map(match => match.tool.name);
+  return suggestions.length > 0 || !server ? suggestions : rankSuggestions(state, name, limit);
 }

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/state.ts

@@ -34,7 +34,7 @@ export interface McpExtensionState {
   manager: McpServerManager;
   lifecycle: McpLifecycleManager;
   toolMetadata: Map<string, ToolMetadata[]>;
-  /** Resource counts retained separately because tool metadata includes resource tools. */
+  /** Native resource counts, separate from callable tools. */
   resourceCounts: Map<string, number>;
   promptMetadata: Map<string, PromptMetadata[]>;
   /** Servers whose prompt inventory came from successful live discovery. */