@humain/terminal 0.0.2 → 0.0.3-beta.0

package/dist/humain/mcp-adapter/vendor/session-recovery.ts

@@ -0,0 +1,151 @@
+// session-recovery.ts
+//
+// Streamable HTTP session recovery.
+//
+// Per the MCP spec (Streamable HTTP transport):
+//   "When a client receives HTTP 404 in response to a request containing an
+//   Mcp-Session-Id, it MUST start a new session by sending a new
+//   InitializeRequest without a session ID attached."
+//
+// A 404 for a request that carried a session ID is therefore the spec's own
+// definition of "this session no longer exists" (e.g. the remote server
+// process restarted and lost its in-memory session table). Because the spec
+// requires the server to reject the request *before* processing it, retrying
+// the same call against a freshly initialized session cannot double-execute
+// the original request.
+//
+// This module intentionally does NOT:
+//   - match broad error messages without a prior session id
+//   - match generic HTTP 400 responses, which are ambiguous and can mean
+//     many things other than "your session is gone"
+//   - treat generic -32000/ConnectionClosed errors as session expiry
+//   - treat AbortError/cancellation as a session failure
+import { ProtocolError, SdkHttpError, UnauthorizedError } from "@modelcontextprotocol/client";
+import { logger } from "./logger.ts";
+import { throwIfAborted } from "./abort.ts";
+import { isServerDisabled, type McpConfig } from "./types.ts";
+import { supportsOAuth } from "./mcp-auth-flow.ts";
+import { invalidateAuthEntryCache } from "./mcp-auth.ts";
+import type { McpServerManager, ServerConnection } from "./server-manager.ts";
+
+/**
+ * True when `err` is a stale Streamable HTTP session signal for a request
+ * sent while carrying an `Mcp-Session-Id`: the spec's 404 transport
+ * response, or the narrowly-known `-32000 Server not initialized` protocol
+ * gate response some servers emit before dispatching to a handler.
+ *
+ * `hadSessionId` must reflect the transport's session id from *before* the
+ * call that produced `err` was made. Callers must capture it before the call
+ * rather than rely on catch-time transport state.
+ */
+const CONNECTION_CLOSED_PROTOCOL_CODE = -32000;
+const SERVER_NOT_INITIALIZED_MCP_MESSAGES = new Set([
+  "Server not initialized",
+  "Bad Request: Server not initialized",
+]);
+
+export function isTerminatedSession(err: unknown, hadSessionId: boolean): boolean {
+  if (!hadSessionId) return false;
+  if (err instanceof SdkHttpError) {
+    return err.status === 404
+      || (err.status === 400
+        && /"code"\s*:\s*-32000/.test(err.message)
+        && /"message"\s*:\s*"Bad Request: Server not initialized"/.test(err.message));
+  }
+  return err instanceof ProtocolError
+    && err.code === CONNECTION_CLOSED_PROTOCOL_CODE
+    && SERVER_NOT_INITIALIZED_MCP_MESSAGES.has(err.message);
+}
+
+function hasSessionId(connection: ServerConnection): boolean {
+  // Only StreamableHTTPClientTransport exposes `sessionId`; stdio/SSE
+  // transports (and test doubles that omit `transport` entirely) simply
+  // read as `undefined` here.
+  const transport = connection.transport as { sessionId?: string } | undefined;
+  return transport?.sessionId != null;
+}
+
+export class SessionRecoveryAuthRequiredError extends Error {
+  constructor(readonly serverName: string, readonly authMessage?: string) {
+    super(authMessage ?? `MCP server "${serverName}" requires OAuth authentication after reconnect.`);
+    this.name = "SessionRecoveryAuthRequiredError";
+  }
+}
+
+export interface SessionRecoveryDeps {
+  manager: McpServerManager;
+  config: McpConfig;
+  signal?: AbortSignal;
+  onNeedsAuth?: (serverName: string) => Promise<ServerConnection | undefined>;
+}
+
+/**
+ * Runs `fn` against the current connection for `serverName`. If it fails
+ * with a terminated Streamable HTTP session (see `isTerminatedSession`),
+ * reconnects exactly once via `McpServerManager.reconnect` (single-flight,
+ * identity-guarded — see server-manager.ts) and retries `fn` exactly once
+ * against the fresh connection.
+ *
+ * Any other failure — including a second failure after reconnecting, or the
+ * server having been removed from config in the meantime — propagates
+ * unchanged through the caller's existing error handling.
+ */
+export async function withSessionRecovery<T>(
+  deps: SessionRecoveryDeps,
+  serverName: string,
+  fn: (conn: ServerConnection) => Promise<T>,
+): Promise<T> {
+  if (isServerDisabled(deps.config.mcpServers[serverName])) {
+    throw new Error(`MCP server "${serverName}" is disabled`);
+  }
+  const connection = deps.manager.getConnection(serverName);
+  if (!connection) {
+    throw new Error(`Server "${serverName}" is not connected`);
+  }
+
+  const hadSessionId = hasSessionId(connection);
+
+  try {
+    return await fn(connection);
+  } catch (err) {
+    const definition = deps.config.mcpServers[serverName];
+    if (definition && supportsOAuth(definition)
+      && (err instanceof UnauthorizedError || (err instanceof SdkHttpError && err.status === 401))) {
+      invalidateAuthEntryCache(serverName);
+    }
+    if (!isTerminatedSession(err, hadSessionId)) {
+      throw err;
+    }
+
+    // Re-read the live definition rather than reusing the stale
+    // connection's definition, in case config changed since connect. If the
+    // server was removed from config in the meantime there is nothing to
+    // reconnect to, so surface the original error.
+    if (!definition) {
+      throw err;
+    }
+
+    throwIfAborted(deps.signal);
+    logger.debug(`MCP session for "${serverName}" expired; reconnecting`, {
+      server: serverName,
+    });
+    let freshConnection = deps.signal
+      ? await deps.manager.reconnect(serverName, definition, connection, deps.signal)
+      : await deps.manager.reconnect(serverName, definition, connection);
+    throwIfAborted(deps.signal);
+
+    if (freshConnection.status === "needs-auth") {
+      freshConnection = await deps.onNeedsAuth?.(serverName) ?? freshConnection;
+      throwIfAborted(deps.signal);
+    }
+
+    if (freshConnection.status === "needs-auth") {
+      throw new SessionRecoveryAuthRequiredError(serverName);
+    }
+    if (freshConnection.status !== "connected") {
+      throw err;
+    }
+
+    return fn(freshConnection);
+  }
+}

package/dist/humain/mcp-adapter/vendor/skills/mcp-scripting/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: mcp-scripting
+description: Write mcpScript JavaScript for discovering, inspecting, and calling MCP tools.
+---
+
+# 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 `mcpScript`; it is the primary MCP orchestration surface. For a single MCP search, describe, status check, auth action, or tool call, use `mcp` instead.
+
+Write the source naturally, then pass it as `mcpScript`'s `code` argument:
+
+```js
+const { items } = await tools.search({ query: "search issues", server: "github" });
+const candidate = items[0];
+if (!candidate) return { error: "No matching tool" };
+
+const details = await tools.describe({ path: candidate.path });
+if (details.error) return details;
+
+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;
+```
+
+## Workflow
+
+1. Find candidate tools with `await tools.search({ query, server?, limit?, offset? })`.
+2. Inspect the exact returned path with `await tools.describe({ path })`.
+3. Call it with `tools.call(path, args)`.
+
+Calls resolve to `{ ok: true, data }` or `{ ok: false, error }`; handle failed calls instead of expecting them to stop the script. `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. 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)`.
+
+`tools.search` and `tools.describe` are asynchronous and must be awaited. The default script timeout is 30 seconds; the worker is terminated at the deadline, including for infinite loops. Every invocation still uses normal lazy connection, authentication, output guarding, and approval gates. Result details contain a concise `calls` trace with every search, describe, and call operation; each entry includes its query or path, outcome, and duration.
+
+Use plain JavaScript loops and Promise utilities for composition. Fluent helpers such as `tools.find(...).one()`, `tools.parallel(...)`, and `tools.retry(...)` are not provided.

package/dist/humain/mcp-adapter/vendor/state.ts

@@ -0,0 +1,62 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ConsentManager } from "./consent-manager.ts";
+import type { McpLifecycleManager } from "./lifecycle.ts";
+import type { McpServerManager } from "./server-manager.ts";
+import type { AuthStorageOptions } from "./mcp-auth.ts";
+import type { ToolMetadata, PromptMetadata, McpConfig, UiSessionMessages, UiStreamSummary } from "./types.ts";
+import type { UiResourceHandler } from "./ui-resource-handler.ts";
+import type { UiServerHandle } from "./ui-server.ts";
+import type { McpRuntimeOwner } from "./runtime-owner.ts";
+import type { McpOAuthRuntime } from "./mcp-auth-flow.ts";
+import type { McpStatusEventBus } from "./mcp-status.ts";
+
+export interface CompletedUiSession {
+  serverName: string;
+  toolName: string;
+  completedAt: Date;
+  reason: string;
+  messages: UiSessionMessages;
+  stream?: UiStreamSummary;
+}
+
+export type SendMessageFn = (
+  message: {
+    customType: string;
+    content: Array<{ type: "text"; text: string }>;
+    display?: string;
+    details?: unknown;
+  },
+  options?: { triggerTurn?: boolean }
+) => void;
+
+export interface McpExtensionState {
+  owner: McpRuntimeOwner;
+  manager: McpServerManager;
+  lifecycle: McpLifecycleManager;
+  toolMetadata: Map<string, ToolMetadata[]>;
+  /** Resource counts retained separately because tool metadata includes resource tools. */
+  resourceCounts: Map<string, number>;
+  promptMetadata: Map<string, PromptMetadata[]>;
+  /** Servers whose prompt inventory came from successful live discovery. */
+  promptMetadataLive: Set<string>;
+  serverInstructions: Map<string, string>;
+  config: McpConfig;
+  programmaticConfig?: boolean;
+  oauthRuntime: McpOAuthRuntime;
+  authStorageOptions: AuthStorageOptions;
+  failureTracker: Map<string, number>;
+  failureMessages: Map<string, string>;
+  /** Session-only approvals keyed by server and original tool name. */
+  approvedToolCalls: Map<string, true>;
+  /** Shared event bus used by permission extensions to broker MCP approvals. */
+  approvalEvents?: ExtensionAPI["events"];
+  uiResourceHandler: UiResourceHandler;
+  consentManager: ConsentManager;
+  uiServer: UiServerHandle | null;
+  completedUiSessions: CompletedUiSession[];
+  openBrowser: (url: string) => Promise<void>;
+  ui?: ExtensionContext["ui"];
+  sendMessage?: SendMessageFn;
+  onToolMetadataUpdated?: (serverName: string, reason: string) => void | Promise<void>;
+  statusEvents?: McpStatusEventBus;
+}

package/dist/humain/mcp-adapter/vendor/tool-approval.ts

@@ -0,0 +1,182 @@
+import { randomUUID } from "node:crypto";
+import { abortable } from "./abort.ts";
+import { combineAbortSignals } from "./runtime-owner.ts";
+import type { McpExtensionState } from "./state.ts";
+import {
+  getToolNameCandidates,
+  matchesToolPattern,
+  resolveToolPrefix,
+  MCP_TOOL_APPROVAL_REQUEST_EVENT,
+  type McpConfig,
+  type McpToolApprovalDecision,
+  type McpToolApprovalHandler,
+  type McpToolApprovalOrigin,
+  type McpToolApprovalRequest,
+  type ToolMetadata,
+} from "./types.ts";
+import { sanitizeTerminalText } from "./utils.ts";
+
+export type ToolCallApprovalResult =
+  | { ok: true }
+  | { ok: false; reason: "denied" | "approval_required_headless" };
+
+export function isToolCallApprovalRequired(
+  config: McpConfig,
+  serverName: string,
+  toolMeta: Pick<ToolMetadata, "originalName">,
+  toolMetadata?: ReadonlyMap<string, readonly ToolMetadata[]>,
+): boolean {
+  const definition = config.mcpServers[serverName];
+  const serverApproval = definition?.approveTools;
+  const approval = serverApproval !== undefined ? serverApproval : config.settings?.approveTools;
+
+  if (approval === true) return true;
+  if (!Array.isArray(approval) || approval.length === 0) return false;
+
+  const prefix = resolveToolPrefix(definition, config.settings?.toolPrefix);
+  const currentCandidates = getToolNameCandidates(toolMeta.originalName, serverName, prefix, false);
+  if (serverApproval !== undefined) {
+    if (matchesToolPattern(currentCandidates, approval)) return true;
+    if (!toolMetadata) return matchesToolPattern(getToolNameCandidates(toolMeta.originalName, serverName, prefix), approval);
+    const legacyCandidates = getToolNameCandidates(toolMeta.originalName, serverName, prefix);
+    const legacyEmittedName = [...currentCandidates].find(candidate => candidate !== toolMeta.originalName)?.replace(/-/g, "_");
+    if (legacyEmittedName) legacyCandidates.add(legacyEmittedName);
+    for (const candidate of currentCandidates) legacyCandidates.delete(candidate);
+    const otherCurrentCandidates = new Set<string>();
+    for (const tool of toolMetadata.get(serverName) ?? []) {
+      for (const candidate of getToolNameCandidates(tool.originalName, serverName, prefix, false)) {
+        otherCurrentCandidates.add(candidate);
+      }
+    }
+    for (const candidate of currentCandidates) otherCurrentCandidates.delete(candidate);
+    return approval.some(pattern =>
+      matchesToolPattern(legacyCandidates, [pattern])
+      && !matchesToolPattern(otherCurrentCandidates, [pattern]),
+    );
+  }
+
+
+  if (matchesToolPattern(currentCandidates, approval)) return true;
+  if (!toolMetadata) return false;
+
+  const legacyCandidates = getToolNameCandidates(toolMeta.originalName, serverName, prefix);
+  const legacyEmittedName = [...currentCandidates].find(candidate => candidate !== toolMeta.originalName)?.replace(/-/g, "_");
+  if (legacyEmittedName) legacyCandidates.add(legacyEmittedName);
+  for (const candidate of currentCandidates) legacyCandidates.delete(candidate);
+  const otherCurrentCandidates = new Set<string>();
+  for (const [name, metadata] of toolMetadata) {
+    const otherPrefix = resolveToolPrefix(config.mcpServers[name], config.settings?.toolPrefix);
+    for (const tool of metadata) {
+      for (const candidate of getToolNameCandidates(tool.originalName, name, otherPrefix, false)) {
+        otherCurrentCandidates.add(candidate);
+      }
+    }
+  }
+  for (const candidate of currentCandidates) otherCurrentCandidates.delete(candidate);
+
+  return approval.some(pattern =>
+    matchesToolPattern(legacyCandidates, [pattern])
+    && !matchesToolPattern(otherCurrentCandidates, [pattern]),
+  );
+}
+
+function isMcpToolApprovalDecision(value: unknown): value is McpToolApprovalDecision {
+  return value === "allow_once"
+    || value === "allow_for_session"
+    || value === "deny"
+    || value === "abstain";
+}
+
+async function requestBrokerApproval(
+  state: McpExtensionState,
+  serverName: string,
+  toolMeta: ToolMetadata,
+  args: Record<string, unknown> | undefined,
+  origin: McpToolApprovalOrigin,
+  signal?: AbortSignal,
+): Promise<McpToolApprovalDecision> {
+  if (!state.approvalEvents) return "abstain";
+
+  let acceptingClaim = true;
+  let handler: McpToolApprovalHandler | undefined;
+  const request: McpToolApprovalRequest = {
+    requestId: randomUUID(),
+    serverName,
+    originalToolName: toolMeta.originalName,
+    prefixedToolName: toolMeta.name,
+    args: args ?? {},
+    origin,
+    ...(signal !== undefined ? { signal } : {}),
+    claim(candidate: McpToolApprovalHandler) {
+      if (!acceptingClaim || handler) return false;
+      handler = candidate;
+      return true;
+    },
+  };
+
+  state.approvalEvents.emit(MCP_TOOL_APPROVAL_REQUEST_EVENT, request);
+  acceptingClaim = false;
+  if (!handler) return "abstain";
+
+  try {
+    const decision = await abortable(Promise.resolve().then(handler), signal);
+    return isMcpToolApprovalDecision(decision) ? decision : "deny";
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    return "deny";
+  }
+}
+
+export async function ensureToolCallApproved(
+  state: McpExtensionState,
+  serverName: string,
+  toolMeta: ToolMetadata,
+  args: Record<string, unknown> | undefined,
+  signal?: AbortSignal,
+  origin: McpToolApprovalOrigin = toolMeta.resourceUri ? "resource" : "proxy",
+  approvalMetadata?: ReadonlyMap<string, readonly ToolMetadata[]>,
+): Promise<ToolCallApprovalResult> {
+  const cacheKey = `${serverName}\u0000${toolMeta.originalName}`;
+  const approvedToolCalls = state.approvedToolCalls ??= new Map<string, true>();
+  if (approvedToolCalls.has(cacheKey)) {
+    return { ok: true };
+  }
+
+  const brokerDecision = await requestBrokerApproval(state, serverName, toolMeta, args, origin, signal);
+  if (brokerDecision === "allow_once") return { ok: true };
+  if (brokerDecision === "allow_for_session") {
+    approvedToolCalls.set(cacheKey, true);
+    return { ok: true };
+  }
+  if (brokerDecision === "deny") return { ok: false, reason: "denied" };
+
+  if (!isToolCallApprovalRequired(state.config, serverName, toolMeta, approvalMetadata ?? state.toolMetadata)) {
+    return { ok: true };
+  }
+
+  if (!state.ui) {
+    return { ok: false, reason: "approval_required_headless" };
+  }
+
+  const json = JSON.stringify(args ?? {}, null, 2);
+  const sanitized = sanitizeTerminalText(json);
+  const preview = sanitized.length > 500 ? `${sanitized.slice(0, 500)}...` : sanitized;
+  const title = `MCP: ${sanitizeTerminalText(serverName)} wants to run ${sanitizeTerminalText(toolMeta.originalName)}`;
+  const ownedSignal = combineAbortSignals(state.owner?.signal, signal);
+  const decision = await abortable(
+    state.ui.select(
+      `${title}\n\nArguments:\n${preview}`,
+      ["Allow once", "Allow for session", "Deny"],
+    ),
+    ownedSignal,
+  );
+
+  if (decision === "Allow once") {
+    return { ok: true };
+  }
+  if (decision === "Allow for session") {
+    approvedToolCalls.set(cacheKey, true);
+    return { ok: true };
+  }
+  return { ok: false, reason: "denied" };
+}