@herbertgao/pi-extensions 2026.9.17 → 2026.9.19

package/node_modules/pi-mcp-adapter/errors.ts

@@ -1,364 +0,0 @@
-/**
- * Custom error types for MCP UI operations.
- * Provides structured errors with context and recovery hints.
- */
-
-export interface McpUiErrorContext {
-  server?: string;
-  tool?: string;
-  uri?: string;
-  session?: string;
-  [key: string]: unknown;
-}
-
-/**
- * Base error class for MCP UI errors.
- */
-export class McpUiError extends Error {
-  readonly code: string;
-  readonly context: McpUiErrorContext;
-  readonly recoveryHint: string | undefined;
-  readonly cause: Error | undefined;
-
-  constructor(
-    message: string,
-    options: {
-      code: string;
-      context?: McpUiErrorContext;
-      recoveryHint?: string;
-      cause?: Error;
-    }
-  ) {
-    super(message);
-    this.name = "McpUiError";
-    this.code = options.code;
-    this.context = options.context ?? {};
-    this.recoveryHint = options.recoveryHint;
-    this.cause = options.cause;
-
-    // Maintain proper stack trace
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, this.constructor);
-    }
-  }
-
-  toJSON(): Record<string, unknown> {
-    return {
-      name: this.name,
-      code: this.code,
-      message: this.message,
-      context: this.context,
-      recoveryHint: this.recoveryHint,
-      stack: this.stack,
-    };
-  }
-}
-
-/**
- * Error fetching a UI resource from the MCP server.
- */
-export class ResourceFetchError extends McpUiError {
-  constructor(
-    uri: string,
-    reason: string,
-    options?: { server?: string; cause?: Error }
-  ) {
-    super(`Failed to fetch UI resource "${uri}": ${reason}`, {
-      code: "RESOURCE_FETCH_ERROR",
-      context: { uri, ...(options?.server !== undefined ? { server: options.server } : {}) },
-      recoveryHint: "Check that the MCP server is connected and the resource URI is valid.",
-      ...(options?.cause !== undefined ? { cause: options.cause } : {}),
-    });
-    this.name = "ResourceFetchError";
-  }
-}
-
-/**
- * Error parsing or validating UI resource content.
- */
-export class ResourceParseError extends McpUiError {
-  constructor(
-    uri: string,
-    reason: string,
-    options?: { server?: string; mimeType?: string }
-  ) {
-    super(`Invalid UI resource "${uri}": ${reason}`, {
-      code: "RESOURCE_PARSE_ERROR",
-      context: {
-        uri,
-        ...(options?.server !== undefined ? { server: options.server } : {}),
-        ...(options?.mimeType !== undefined ? { mimeType: options.mimeType } : {}),
-      },
-      recoveryHint: "Ensure the resource returns valid HTML with the correct MIME type.",
-    });
-    this.name = "ResourceParseError";
-  }
-}
-
-/**
- * Error connecting to the AppBridge.
- */
-export class BridgeConnectionError extends McpUiError {
-  constructor(reason: string, options?: { session?: string; cause?: Error }) {
-    super(`AppBridge connection failed: ${reason}`, {
-      code: "BRIDGE_CONNECTION_ERROR",
-      context: options?.session !== undefined ? { session: options.session } : {},
-      recoveryHint: "Check browser console for detailed errors. The iframe may have failed to load.",
-      ...(options?.cause !== undefined ? { cause: options.cause } : {}),
-    });
-    this.name = "BridgeConnectionError";
-  }
-}
-
-/**
- * Error related to user consent for tool calls.
- */
-export class ConsentError extends McpUiError {
-  readonly denied: boolean;
-
-  constructor(
-    server: string,
-    options: { denied?: boolean; requiresApproval?: boolean }
-  ) {
-    const message = options.denied
-      ? `Tool calls for "${server}" were denied for this session`
-      : `Tool call approval required for "${server}"`;
-
-    super(message, {
-      code: options.denied ? "CONSENT_DENIED" : "CONSENT_REQUIRED",
-      context: { server },
-      recoveryHint: options.denied
-        ? "The user denied tool access. Start a new session to try again."
-        : "Prompt the user for consent before calling tools.",
-    });
-    this.name = "ConsentError";
-    this.denied = options.denied ?? false;
-  }
-}
-
-/**
- * Error with UI server session management.
- */
-export class SessionError extends McpUiError {
-  constructor(
-    reason: string,
-    options?: { session?: string; cause?: Error }
-  ) {
-    super(`Session error: ${reason}`, {
-      code: "SESSION_ERROR",
-      context: options?.session !== undefined ? { session: options.session } : {},
-      recoveryHint: "The session may have expired or been closed. Try opening the UI again.",
-      ...(options?.cause !== undefined ? { cause: options.cause } : {}),
-    });
-    this.name = "SessionError";
-  }
-}
-
-/**
- * Error starting or operating the UI server.
- */
-export class ServerError extends McpUiError {
-  constructor(
-    reason: string,
-    options?: { port?: number; cause?: Error }
-  ) {
-    super(`UI server error: ${reason}`, {
-      code: "SERVER_ERROR",
-      context: options?.port !== undefined ? { port: options.port } : {},
-      recoveryHint: "Check if the port is available. Another process may be using it.",
-      ...(options?.cause !== undefined ? { cause: options.cause } : {}),
-    });
-    this.name = "ServerError";
-  }
-}
-
-/**
- * Error communicating with the MCP server.
- */
-export class McpServerError extends McpUiError {
-  constructor(
-    server: string,
-    reason: string,
-    options?: { tool?: string; cause?: Error }
-  ) {
-    super(`MCP server "${server}" error: ${reason}`, {
-      code: "MCP_SERVER_ERROR",
-      context: { server, ...(options?.tool !== undefined ? { tool: options.tool } : {}) },
-      recoveryHint: "Check that the MCP server is running and responsive.",
-      ...(options?.cause !== undefined ? { cause: options.cause } : {}),
-    });
-    this.name = "McpServerError";
-  }
-}
-
-/**
- * Wrap an unknown error into an McpUiError.
- */
-export function wrapError(error: unknown, context?: McpUiErrorContext): McpUiError {
-  if (error instanceof McpUiError) {
-    // Merge contexts
-    return new McpUiError(error.message, {
-      code: error.code,
-      context: { ...error.context, ...context },
-      ...(error.recoveryHint !== undefined ? { recoveryHint: error.recoveryHint } : {}),
-      ...(error.cause !== undefined ? { cause: error.cause } : {}),
-    });
-  }
-
-  const cause = error instanceof Error ? error : undefined;
-  const message = error instanceof Error ? error.message : String(error);
-
-  return new McpUiError(message, {
-    code: "UNKNOWN_ERROR",
-    ...(context !== undefined ? { context } : {}),
-    ...(cause !== undefined ? { cause } : {}),
-  });
-}
-
-/**
- * Check if an error is a specific MCP UI error type.
- */
-export function isErrorCode(error: unknown, code: string): boolean {
-  return error instanceof McpUiError && error.code === code;
-}
-
-/**
- * Stable adapter error code for an SDK-native input_required result that the
- * current client cannot fulfil because its embedded-request handler is not
- * registered. The SDK keeps the request key/method in `SdkError.data`; this
- * adapter detail intentionally copies only bounded, actionable fields.
- */
-export const INPUT_REQUIRED_NEEDS_UI = "input_required_needs_ui" as const;
-
-export interface InputRequiredNeedsUiDetails {
-  error: typeof INPUT_REQUIRED_NEEDS_UI;
-  server: string;
-  tool?: string;
-  resourceUri?: string;
-  inputKey: string;
-  inputMethod: string;
-  message: string;
-}
-
-export interface InputRequiredIdentity {
-  server: string;
-  tool?: string;
-  resourceUri?: string;
-}
-
-const INPUT_REQUIRED_METHODS = new Set([
-  "elicitation/create",
-  "sampling/createMessage",
-]);
-const MAX_INPUT_REQUIRED_SERVER_LENGTH = 96;
-const MAX_INPUT_REQUIRED_TARGET_LENGTH = 160;
-const MAX_INPUT_REQUIRED_DETAIL_LENGTH = 128;
-
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-  return value !== null && typeof value === "object" && !Array.isArray(value)
-    ? value as Record<string, unknown>
-    : undefined;
-}
-
-function boundedText(value: unknown, maxLength: number): string | undefined {
-  if (typeof value !== "string" || value.length === 0) return undefined;
-  return value.length <= maxLength ? value : `${value.slice(0, maxLength - 1)}…`;
-}
-
-interface EmbeddedInputRequest {
-  inputKey: string;
-  inputMethod: string;
-  server?: string;
-  tool?: string;
-  resourceUri?: string;
-}
-
-function findEmbeddedInputRequest(error: unknown): EmbeddedInputRequest | undefined {
-  let current: unknown = error;
-  const seen = new Set<unknown>();
-  for (let depth = 0; depth < 8 && current !== undefined && current !== null; depth++) {
-    if (seen.has(current)) return undefined;
-    seen.add(current);
-    const record = asRecord(current);
-    if (!record) return undefined;
-
-    if (record.code === INPUT_REQUIRED_NEEDS_UI) {
-      const details = asRecord(record.details);
-      const inputKey = boundedText(details?.inputKey, MAX_INPUT_REQUIRED_DETAIL_LENGTH);
-      const inputMethod = boundedText(details?.inputMethod, MAX_INPUT_REQUIRED_DETAIL_LENGTH);
-      if (inputKey && inputMethod && INPUT_REQUIRED_METHODS.has(inputMethod)) {
-        const server = boundedText(details?.server, MAX_INPUT_REQUIRED_SERVER_LENGTH);
-        const tool = boundedText(details?.tool, MAX_INPUT_REQUIRED_TARGET_LENGTH);
-        const resourceUri = boundedText(details?.resourceUri, MAX_INPUT_REQUIRED_TARGET_LENGTH);
-        return {
-          inputKey,
-          inputMethod,
-          ...(server ? { server } : {}),
-          ...(tool ? { tool } : {}),
-          ...(resourceUri ? { resourceUri } : {}),
-        };
-      }
-    }
-
-    if (record.code === "CAPABILITY_NOT_SUPPORTED") {
-      const data = asRecord(record.data);
-      const inputKey = boundedText(data?.key, MAX_INPUT_REQUIRED_DETAIL_LENGTH);
-      const inputMethod = boundedText(data?.method, MAX_INPUT_REQUIRED_DETAIL_LENGTH);
-      if (inputKey && inputMethod && INPUT_REQUIRED_METHODS.has(inputMethod)) {
-        return { inputKey, inputMethod };
-      }
-    }
-
-    current = record.cause;
-  }
-  return undefined;
-}
-
-/**
- * Convert a missing embedded-input handler into an adapter-owned result
- * detail. Matching requires the SDK's typed code/data shape (or this module's
- * typed wrapper), rather than arbitrary error-message text.
- */
-export function getInputRequiredNeedsUiDetails(
-  error: unknown,
-  identity: InputRequiredIdentity,
-): InputRequiredNeedsUiDetails | undefined {
-  const request = findEmbeddedInputRequest(error);
-  if (!request) return undefined;
-
-  const server = boundedText(request.server ?? identity.server, MAX_INPUT_REQUIRED_SERVER_LENGTH) ?? "unknown";
-  const tool = boundedText(request.tool ?? identity.tool, MAX_INPUT_REQUIRED_TARGET_LENGTH);
-  const resourceUri = boundedText(request.resourceUri ?? identity.resourceUri, MAX_INPUT_REQUIRED_TARGET_LENGTH);
-  const target = resourceUri
-    ? `read resource "${resourceUri}"`
-    : tool
-      ? `call tool "${tool}"`
-      : "complete the MCP request";
-  const guidance = request.inputMethod === "elicitation/create"
-    ? "Run this call in an interactive Pi session with elicitation enabled, then retry."
-    : "Run this call in an interactive Pi session with the required MCP capability enabled, then retry.";
-  const message = `MCP server "${server}" requested input to ${target}, but this session has no handler for "${request.inputMethod}" (input "${request.inputKey}"). ${guidance}`;
-
-  return {
-    error: INPUT_REQUIRED_NEEDS_UI,
-    server,
-    ...(tool ? { tool } : {}),
-    ...(resourceUri ? { resourceUri } : {}),
-    inputKey: request.inputKey,
-    inputMethod: request.inputMethod,
-    message,
-  };
-}
-
-/** Error form used by UiResourceHandler so an outer tool call can preserve the classification. */
-export class InputRequiredNeedsUiError extends McpUiError {
-  constructor(readonly details: InputRequiredNeedsUiDetails, cause?: Error) {
-    super(details.message, {
-      code: INPUT_REQUIRED_NEEDS_UI,
-      context: { ...details },
-      recoveryHint: "Run this call in an interactive Pi session with the required MCP input handler enabled, then retry.",
-      ...(cause ? { cause } : {}),
-    });
-    this.name = "InputRequiredNeedsUiError";
-  }
-}

package/node_modules/pi-mcp-adapter/examples/jev-accessibility-loop.mjs

@@ -1,85 +0,0 @@
-const SAFE_OPERATIONS = new Set(["focus", "scroll"]);
-
-export async function runAccessibilityLoop(tools, jev, options) {
-  const { observePath, actionPath, goal, allowedOperations, sources, maxSteps, maxMs, maxEvaluations } = options;
-  if (typeof observePath !== "string" || !observePath || typeof actionPath !== "string" || !actionPath || typeof goal !== "string" || !goal
-    || !Array.isArray(allowedOperations) || allowedOperations.length === 0 || allowedOperations.some(operation => !SAFE_OPERATIONS.has(operation))) {
-    throw new Error("Exact tool paths, a goal, and non-destructive focus/scroll operations are required");
-  }
-  if (![maxSteps, maxMs, maxEvaluations].every(value => Number.isInteger(value) && value > 0)) {
-    throw new Error("Positive step, time, and evaluation budgets are required");
-  }
-  if (!Array.isArray(sources) || sources.length === 0 || sources.some(source => typeof source !== "string" || !source)) {
-    throw new Error("Explicit MCP sources are required for accessibility data");
-  }
-  const startedAt = Date.now();
-  let evaluations = 0;
-  let previousFingerprint;
-
-  const observe = async () => {
-    const result = await tools.call(observePath, {});
-    if (!result.ok) return { error: "observation-failed" };
-    const tree = result.data?.structuredContent;
-    if (!tree || typeof tree.observationId !== "string" || !tree.observationId || !Array.isArray(tree.nodes)) {
-      return { error: "needs-information" };
-    }
-    return { tree };
-  };
-
-  for (let step = 0; step < maxSteps; step += 1) {
-    if (Date.now() - startedAt >= maxMs) return { status: "stop", reason: "time-budget" };
-    const snapshot = await observe();
-    if (snapshot.error) return { status: snapshot.error === "needs-information" ? "needs-information" : "stop", reason: snapshot.error };
-    const fingerprint = JSON.stringify(snapshot.tree.nodes);
-    if (fingerprint === previousFingerprint) return { status: "stop", reason: "no-progress" };
-    previousFingerprint = fingerprint;
-
-    const actions = snapshot.tree.nodes.flatMap(node =>
-      (node && typeof node.id === "string" && node.id && Array.isArray(node.actions) ? node.actions : [])
-        .filter(operation => typeof operation === "string" && allowedOperations.includes(operation))
-        .map(operation => ({ target: node.id, operation })),
-    ).slice(0, 120).map((action, index) => ({ ...action, label: `a${index}` }));
-    if (actions.length === 0) return { status: "no-match" };
-    if (evaluations >= maxEvaluations) return { status: "stop", reason: "evaluation-budget" };
-    evaluations += 1;
-    const evaluation = await jev.evaluate({
-      state: { goal, observationId: snapshot.tree.observationId, nodes: snapshot.tree.nodes },
-      sources,
-      questions: {
-        next: {
-          type: "choice",
-          instructions: "Choose complete only when the observation proves the goal. Otherwise choose one safe action, none, or needsInformation.",
-          criteria: Object.fromEntries([
-            ...actions.map(action => [action.label, { target: action.target, operation: action.operation }]),
-            ["complete", "Goal is observably complete"],
-            ["none", "No matching safe action"],
-            ["needsInformation", "User information is required"],
-          ]),
-        },
-      },
-    });
-    if (!evaluation.ok) return { status: "stop", reason: evaluation.error.code };
-    const answer = evaluation.data.answers.next;
-    if (answer.type !== "choice" || answer.confidence < 0.85) return { status: "stop", reason: "uncertain" };
-    if (answer.choice === "complete") return { status: "complete", observationId: snapshot.tree.observationId };
-    if (answer.choice === "none") return { status: "no-match" };
-    if (answer.choice === "needsInformation") return { status: "needs-information" };
-    const selected = actions.find(action => action.label === answer.choice);
-    if (!selected) return { status: "stop", reason: "invalid-action" };
-
-    if (Date.now() - startedAt >= maxMs) return { status: "stop", reason: "time-budget" };
-    const fresh = await observe();
-    if (fresh.error || fresh.tree.observationId === snapshot.tree.observationId) return { status: "stop", reason: "stale-candidate" };
-    const target = fresh.tree.nodes.find(node => node.id === selected.target);
-    if (!target || !Array.isArray(target.actions) || !target.actions.includes(selected.operation)) {
-      return { status: "stop", reason: "stale-candidate" };
-    }
-    const acted = await tools.call(actionPath, {
-      operation: selected.operation,
-      target: selected.target,
-      observationId: fresh.tree.observationId,
-    });
-    if (!acted.ok) return { status: "stop", reason: "action-failed-or-uncertain" };
-  }
-  return { status: "stop", reason: "step-budget" };
-}

package/node_modules/pi-mcp-adapter/examples/jev-semantic-filter.mjs

@@ -1,34 +0,0 @@
-export async function filterIssuesForTriage(tools, jev) {
-  const found = await tools.search({
-    query: "list open customer issue reports",
-    server: "github",
-    searchMode: "semantic",
-    limit: 5,
-  });
-  const tool = found.items?.[0];
-  if (!tool) return { status: "no-match" };
-
-  const listed = await tools.call(tool.path, { state: "open", limit: 20 });
-  if (!listed.ok) return { status: "stop", error: listed.error };
-  const issues = listed.data?.structuredContent?.issues;
-  if (!Array.isArray(issues) || issues.length === 0) return { status: "no-match" };
-
-  const candidates = issues.slice(0, 20).map((issue, index) => ({
-    id: `issue${index}`,
-    title: String(issue.title ?? ""),
-    body: String(issue.body ?? "").slice(0, 2000),
-  }));
-  const questions = Object.fromEntries(candidates.flatMap(issue => [
-    [`relevant_${issue.id}`, { type: "noul", instructions: "Is this issue actionable and relevant?", criteria: { true: "Relevant", false: "Not relevant" } }],
-    [`regression_${issue.id}`, { type: "noul", instructions: "Does this issue contain evidence of a regression?", criteria: { true: "Regression", false: "No regression evidence" } }],
-  ]));
-  const evaluation = await jev.evaluate({ state: { candidates }, questions, sources: ["github"] });
-  if (!evaluation.ok) return { status: "stop", error: evaluation.error };
-
-  const useful = candidates.filter(issue => {
-    const relevant = evaluation.data.answers[`relevant_${issue.id}`];
-    const regression = evaluation.data.answers[`regression_${issue.id}`];
-    return relevant?.type === "noul" && regression?.type === "noul" && relevant.noul >= 0.8 && regression.noul >= 0.7;
-  });
-  return useful.length > 0 ? { status: "matched", issues: useful } : { status: "no-match" };
-}

package/node_modules/pi-mcp-adapter/failure-backoff.ts

@@ -1,23 +0,0 @@
-import type { McpExtensionState } from "./state.ts";
-
-export const FAILURE_BACKOFF_MS = 60 * 1000;
-
-export function getFailureAgeSeconds(state: McpExtensionState, serverName: string): number | null {
-  const failedAt = state.failureTracker.get(serverName);
-  if (!failedAt) return null;
-  const ageMs = Date.now() - failedAt;
-  if (ageMs > FAILURE_BACKOFF_MS) return null;
-  return Math.round(ageMs / 1000);
-}
-
-export function getFailureMessage(state: McpExtensionState, serverName: string): string | null {
-  if (getFailureAgeSeconds(state, serverName) === null) return null;
-  return state.failureMessages?.get(serverName) ?? null;
-}
-
-export function isServerInActiveFailureBackoff(state: McpExtensionState, serverName: string): boolean {
-  const connection = state.manager.getConnection(serverName);
-  return connection?.status !== "connected"
-    && connection?.status !== "needs-auth"
-    && getFailureAgeSeconds(state, serverName) !== null;
-}

package/node_modules/pi-mcp-adapter/glimpse-ui.ts

@@ -1,80 +0,0 @@
-import { existsSync } from "node:fs";
-import { execFileSync } from "node:child_process";
-import { join, dirname } from "node:path";
-import { platform } from "node:os";
-import { createRequire } from "node:module";
-
-let glimpseAvailable: boolean | null = null;
-let resolvedBinaryPath: string | null = null;
-
-export function isGlimpseAvailable(): boolean {
-  if (glimpseAvailable !== null) return glimpseAvailable;
-
-  if (platform() !== "darwin") {
-    glimpseAvailable = false;
-    return false;
-  }
-
-  resolvedBinaryPath = getGlimpseBinaryPath();
-  glimpseAvailable = resolvedBinaryPath !== null;
-  return glimpseAvailable;
-}
-
-function getGlimpseBinaryPath(): string | null {
-  if (process.env.GLIMPSE_BINARY && existsSync(process.env.GLIMPSE_BINARY)) {
-    return process.env.GLIMPSE_BINARY;
-  }
-
-  // Local node_modules
-  try {
-    const require = createRequire(import.meta.url);
-    const glimpseuiPath = require.resolve("glimpseui");
-    const binaryPath = join(dirname(glimpseuiPath), "glimpse");
-    if (existsSync(binaryPath)) return binaryPath;
-  } catch {}
-
-  // Global npm install
-  try {
-    const globalRoot = execFileSync("npm", ["root", "-g"], { encoding: "utf-8" }).trim();
-    const binaryPath = join(globalRoot, "glimpseui", "src", "glimpse");
-    if (existsSync(binaryPath)) return binaryPath;
-  } catch {}
-
-  return null;
-}
-
-export async function openGlimpseWindow(
-  html: string,
-  options: {
-    title: string;
-    width?: number;
-    height?: number;
-    onClosed: () => void;
-  },
-) {
-  const modulePath = resolvedBinaryPath
-    ? join(dirname(resolvedBinaryPath), "glimpse.mjs")
-    : "glimpseui";
-  const glimpse = await import(modulePath);
-
-  let active = true;
-  const win = glimpse.open(html, {
-    width: options.width ?? 900,
-    height: options.height ?? 700,
-    title: options.title,
-  });
-
-  win.on("closed", () => {
-    if (!active) return;
-    active = false;
-    options.onClosed();
-  });
-
-  return {
-    close: () => {
-      if (!active) return;
-      active = false;
-      win.close();
-    },
-  };
-}