@humain/terminal 0.0.3-beta.2 → 0.0.4-beta.1

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

@@ -1,10 +1,10 @@
 import type { AgentToolUpdateCallback, ExtensionAPI, ExtensionContext, ToolInfo } from "@earendil-works/pi-coding-agent";
 import type { McpExtensionState } from "./state.ts";
-import type { DirectToolSpec, McpAdapterOptions, McpConfig, PromptMetadata } from "./types.ts";
+import type { DirectToolSpec, McpAdapterOptions, McpConfig, PromptMetadata, ServerEntry } from "./types.ts";
 import type { McpOAuthRuntime } from "./mcp-auth-flow.ts";
 import { Type } from "typebox";
 import type { TSchema } from "typebox";
-import { showStatus, showTools, showPrompts, reconnectServer, reconnectServers, authenticateServer, logoutServer, openMcpAuthPanel, openMcpPanel, openMcpSetup } from "./commands.ts";
+import { showStatus, showTools, showPrompts, reconnectServer, reconnectServers, authenticateServer, logoutServer, manageBearerToken, openMcpAuthPanel, openMcpPanel, openMcpSetup } from "./commands.ts";
 import { cloneMcpConfig, loadMcpConfig, writeProjectServerDisabledOverride } from "./config.ts";
 import { buildProxyDescription, createDirectToolExecutor, getMissingConfiguredDirectToolServers, resolveDirectTools } from "./direct-tools.ts";
 import { flushMetadataCache, initializeMcp, updateStatusBar } from "./init.ts";
@@ -22,6 +22,7 @@ import { runMcpScript } from "./mcp-code.ts";
 import { cleanupMaterializedBinaryResources } from "./tool-registrar.ts";
 
 export type { McpAdapterOptions } from "./types.ts";
+export type { ServerEntry } from "./types.ts";
 export {
   MCP_STATUS_EVENT,
   MCP_STATUS_SNAPSHOT_VERSION,
@@ -38,6 +39,14 @@ export {
 const INIT_WAIT_TIMEOUT_MS = 30_000;
 const INIT_WAIT_TIMED_OUT: unique symbol = Symbol("init-wait-timed-out");
 
+export interface McpServerRegistration {
+  dispose(): Promise<void>;
+}
+
+// Routes runtime registrations to the adapter installed for a specific Pi
+// instance, so a process with several adapters cannot cross-register.
+const runtimeRegistrars = new WeakMap<ExtensionAPI, (name: string, definition: ServerEntry) => McpServerRegistration>();
+
 async function awaitWithTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T | typeof INIT_WAIT_TIMED_OUT> {
   let timer: ReturnType<typeof setTimeout> | undefined;
   try {
@@ -130,6 +139,19 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
   let proxyToolRegistered = false;
   let proxyToolDescription: string | null = null;
   let directToolsFrozen = false;
+  // Session/runtime scoped server registrations from other extensions. They
+  // survive session restarts within this install and die with the process.
+  const runtimeServers = new Map<string, ServerEntry>();
+
+  // Mirrors init's per-server lifecycle registration so runtime servers get
+  // idle cleanup and keep-alive health recovery like configured servers.
+  function attachRuntimeServerLifecycle(targetState: McpExtensionState, name: string, definition: ServerEntry): void {
+    const lifecycleMode = definition.lifecycle ?? "lazy";
+    const persistsAfterFirstSpawn = lifecycleMode === "eager" || lifecycleMode === "lazy-keep-alive";
+    const idleOverride = definition.idleTimeout ?? (persistsAfterFirstSpawn ? 0 : undefined);
+    targetState.lifecycle.registerServer(name, definition, idleOverride !== undefined ? { idleTimeout: idleOverride } : undefined);
+    if (lifecycleMode === "keep-alive") targetState.lifecycle.markKeepAlive(name, definition);
+  }
 
   // OMP remaps `typebox` to a host shim that historically lacked Type.Unsafe.
   // Prefer Unsafe when present (real TypeBox / fixed OMP shim); otherwise pass
@@ -282,6 +304,45 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
 
   registerPromptCommands(resolveCachedPrompts(earlyConfig));
 
+  runtimeRegistrars.set(pi, (name: string, definition: ServerEntry): McpServerRegistration => {
+    if (typeof name !== "string" || name.trim() === "") {
+      throw new Error("MCP server name must be a non-empty string");
+    }
+    if (typeof definition !== "object" || definition === null || Array.isArray(definition)) {
+      throw new Error(`MCP server definition for "${name}" must be an object`);
+    }
+    const effective = state?.config ?? earlyConfig;
+    if (runtimeServers.has(name) || Object.hasOwn(effective.mcpServers, name)) {
+      throw new Error(`MCP server "${name}" is already registered`);
+    }
+    // Runtime-registered servers are proxy-tool-only: direct tools are frozen
+    // at startup and must not be rebuilt for late registrations.
+    const entry: ServerEntry = { ...structuredClone(definition), directTools: false };
+    runtimeServers.set(name, entry);
+    const registeredState = state;
+    if (registeredState) {
+      registeredState.config.mcpServers[name] = entry;
+      attachRuntimeServerLifecycle(registeredState, name, entry);
+      syncToolSurface();
+      updateStatusBar(registeredState);
+    }
+    let disposed = false;
+    return {
+      dispose: async (): Promise<void> => {
+        if (disposed) return;
+        disposed = true;
+        runtimeServers.delete(name);
+        const currentState = state;
+        if (!currentState || currentState.config.mcpServers[name] !== entry) return;
+        delete currentState.config.mcpServers[name];
+        currentState.lifecycle.unregisterServer(name);
+        await currentState.manager.close(name);
+        syncToolSurface();
+        updateStatusBar(currentState);
+      },
+    };
+  });
+
   const getPiTools = (): ToolInfo[] => pi.getAllTools();
 
   pi.registerFlag("mcp-config", {
@@ -299,7 +360,6 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
           }
         : {}),
       oauthRuntime,
-      statusEvents: pi.events,
     });
     initPromise = promise;
 
@@ -314,6 +374,14 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       }
 
       state = nextState;
+      for (const [name, definition] of runtimeServers) {
+        if (Object.hasOwn(nextState.config.mcpServers, name)) {
+          console.error(`MCP: runtime-registered server "${name}" now collides with a configured server; keeping the configured server`);
+          continue;
+        }
+        nextState.config.mcpServers[name] = definition;
+        attachRuntimeServerLifecycle(nextState, name, definition);
+      }
       nextState.onToolMetadataUpdated = (_serverName, _reason) => {
         if (state !== nextState || !owner.isActive()) return;
         syncPromptCommands();
@@ -325,6 +393,9 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       };
       syncPromptCommands();
       syncToolSurface(ctx);
+      // A connected snapshot is readiness-like external state. Publish it only
+      // after Pi's model-facing direct-tool surface reflects live metadata.
+      nextState.statusEvents = pi.events;
       updateStatusBar(nextState);
       initPromise = null;
       if (earlyConfig.settings?.freezeDirectTools === true) {
@@ -417,6 +488,29 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     }
   });
 
+  pi.on("input", async () => {
+    const inputOwner = currentOwner;
+    if (!inputOwner?.isActive()) return;
+
+    if (!state && initPromise) {
+      try {
+        await awaitWithTimeout(initPromise, INIT_WAIT_TIMEOUT_MS);
+      } catch {
+        return;
+      }
+    }
+
+    const inputState = state;
+    if (!inputState || !inputOwner.isActive()) return;
+    try {
+      await inputState.lifecycle.ensureConverged(inputOwner.signal);
+    } catch (error) {
+      if (!isAbortError(error, inputOwner.signal)) {
+        logger.debug(`MCP: keep-alive convergence failed before input: ${formatTerminalError(error)}`);
+      }
+    }
+  });
+
   pi.on("session_shutdown", async () => {
     ++lifecycleGeneration;
     const currentState = state;
@@ -444,7 +538,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
   // Re-flag returned MCP tool failures so pi registers them as errors (see toolErrorOverride).
   pi.on("tool_result", (event) => toolErrorOverride(event.details));
 
-  pi.registerCommand("mcp", {
+  const registerMcpCommand = (commandName: string) => pi.registerCommand(commandName, {
     description: "Show MCP server status",
     getArgumentCompletions: (prefix: string) => {
       const normalized = prefix.trimStart();
@@ -456,6 +550,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
           { value: "prompts", label: "prompts — List all MCP prompts" },
           { value: "setup", label: "setup — Configure MCP servers" },
           { value: "logout", label: "logout — Clear server credentials" },
+          { value: "token", label: "token — Manage stored bearer tokens" },
           { value: "disable", label: "disable — Disable a server" },
           { value: "enable", label: "enable — Enable a server" },
           { value: "status", label: "status — Show server status" },
@@ -465,11 +560,27 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
 
       const [, subcommand, argumentPrefix] = argumentMatch;
       if (
-        (subcommand !== "reconnect" && subcommand !== "logout" && subcommand !== "disable" && subcommand !== "enable")
+        (subcommand !== "reconnect" && subcommand !== "logout" && subcommand !== "disable" && subcommand !== "enable" && subcommand !== "token")
         || argumentPrefix === undefined
         || !state
       ) return null;
 
+      if (subcommand === "token") {
+        const tokenMatch = argumentPrefix.trimStart().match(/^(set|remove|status)\s+(.*)$/);
+        if (!tokenMatch) {
+          const actions = ["set", "remove", "status"]
+            .filter(action => action.startsWith(argumentPrefix.trimStart()))
+            .map(action => ({ value: `token ${action} `, label: `${action} — Bearer token ${action}` }));
+          return actions.length > 0 ? actions : null;
+        }
+        const action = tokenMatch[1] ?? "";
+        const serverPrefix = tokenMatch[2] ?? "";
+        const servers = Object.keys(state.config.mcpServers)
+          .filter(serverName => serverName.startsWith(serverPrefix.trimStart()))
+          .map(serverName => ({ value: `token ${action} ${serverName}`, label: serverName }));
+        return servers.length > 0 ? servers : null;
+      }
+
       const servers = Object.keys(state.config.mcpServers)
         .filter((serverName) => serverName.startsWith(argumentPrefix.trimStart()))
         .map((serverName) => ({ value: `${subcommand} ${serverName}`, label: serverName }));
@@ -545,6 +656,21 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
           await logoutServer(serverName, state, commandCtx);
           break;
         }
+        case "token": {
+          const action = parts[1];
+          const serverName = parts.slice(2).join(" ");
+          if (action !== "set" && action !== "remove" && action !== "status") {
+            if (commandCtx.hasUI) commandCtx.ui?.notify("Usage: /mcp token set|remove|status <server>", "error");
+            return;
+          }
+          if (!serverName) {
+            if (commandCtx.hasUI) commandCtx.ui?.notify("Usage: /mcp token set|remove|status <server>", "error");
+            return;
+          }
+          commandOwner?.throwIfInactive();
+          await manageBearerToken(action, serverName, state, commandCtx);
+          break;
+        }
         case "disable":
         case "enable": {
           const serverName = rest;
@@ -595,6 +721,8 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       }
     },
   });
+  registerMcpCommand("mcp");
+  registerMcpCommand("pi-mcp");
 
   pi.registerCommand("mcp-auth", {
     description: "Authenticate with an MCP server (OAuth)",
@@ -737,12 +865,12 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         action?: string;
       }, signal: AbortSignal | undefined, _onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined, _ctx: ExtensionContext) {
         const executeOwner = currentOwner;
-        let parsedArgs: Record<string, unknown> | undefined;
-        if (params.args !== undefined && params.args !== "") {
+        const parseArgs = (value: string | Record<string, unknown> | undefined): Record<string, unknown> | undefined => {
+          if (value === undefined || value === "") return undefined;
           let args: unknown;
-          if (typeof params.args === "string") {
+          if (typeof value === "string") {
             try {
-              args = JSON.parse(params.args);
+              args = JSON.parse(value);
             } catch (error) {
               if (error instanceof SyntaxError) {
                 throw new Error(`Invalid args JSON: ${error.message}`, { cause: error });
@@ -750,14 +878,57 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
               throw error;
             }
           } else {
-            args = params.args;
+            args = value;
           }
 
           if (typeof args !== "object" || args === null || Array.isArray(args)) {
             const gotType = Array.isArray(args) ? "array" : args === null ? "null" : typeof args;
             throw new Error(`Invalid args: expected a JSON object, got ${gotType}`);
           }
-          parsedArgs = args as Record<string, unknown>;
+          return args as Record<string, unknown>;
+        };
+        const validateNestedGatewayParams = (value: Record<string, unknown>): typeof params => {
+          for (const key of ["tool", "connect", "describe", "instructions", "search", "server", "action"] as const) {
+            if (value[key] !== undefined && typeof value[key] !== "string") {
+              throw new Error(`Invalid nested gateway param \`${key}\`: expected string, got ${Array.isArray(value[key]) ? "array" : typeof value[key]}`);
+            }
+          }
+          for (const key of ["regex", "includeSchemas"] as const) {
+            if (value[key] !== undefined && typeof value[key] !== "boolean") {
+              throw new Error(`Invalid nested gateway param \`${key}\`: expected boolean, got ${Array.isArray(value[key]) ? "array" : typeof value[key]}`);
+            }
+          }
+          for (const key of ["limit", "offset"] as const) {
+            if (value[key] !== undefined && typeof value[key] !== "number") {
+              throw new Error(`Invalid nested gateway param \`${key}\`: expected number, got ${Array.isArray(value[key]) ? "array" : typeof value[key]}`);
+            }
+          }
+          const args = value.args;
+          if (args !== undefined && typeof args !== "string" && (typeof args !== "object" || args === null || Array.isArray(args))) {
+            throw new Error(`Invalid nested gateway param \`args\`: expected JSON object or JSON string, got ${Array.isArray(args) ? "array" : args === null ? "null" : typeof args}`);
+          }
+          return value as typeof params;
+        };
+        let parsedArgs = parseArgs(params.args);
+        let dispatchParams = params;
+        const hasGatewayMode = (value: typeof params): boolean =>
+          value.tool !== undefined
+          || value.connect !== undefined
+          || value.describe !== undefined
+          || value.instructions !== undefined
+          || value.search !== undefined
+          || value.server !== undefined
+          || value.action !== undefined;
+        if (!hasGatewayMode(params) && parsedArgs) {
+          const nestedParams = validateNestedGatewayParams(parsedArgs);
+          if (hasGatewayMode(nestedParams)) {
+            dispatchParams = nestedParams;
+            parsedArgs = parseArgs(nestedParams.args);
+          } else {
+            throw new Error("Gateway params were nested inside `args`; pass them top-level (for example, mcp({ search: \"...\" }) or mcp({ tool: \"...\", args: {} })).");
+          }
+        } else if (!hasGatewayMode(params) && params.args !== undefined) {
+          throw new Error("Gateway params were nested inside `args`; pass them top-level (for example, mcp({ search: \"...\" }) or mcp({ tool: \"...\", args: {} })).");
         }
 
         if (!state && initPromise) {
@@ -788,22 +959,22 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         }
         executeOwner?.throwIfInactive();
 
-        if (params.action === "ui-messages") {
+        if (dispatchParams.action === "ui-messages") {
           return executeUiMessages(state);
         }
-        if (params.action === "auth-start") {
-          if (!params.server) {
+        if (dispatchParams.action === "auth-start") {
+          if (!dispatchParams.server) {
             return {
               content: [{ type: "text" as const, text: "auth-start requires `server`. Example: mcp({ action: \"auth-start\", server: \"linear-server\" })" }],
               details: { mode: "auth-start", error: "missing_server" },
             };
           }
           return signal
-            ? executeAuthStart(state, params.server, signal)
-            : executeAuthStart(state, params.server);
+            ? executeAuthStart(state, dispatchParams.server, signal)
+            : executeAuthStart(state, dispatchParams.server);
         }
-        if (params.action === "auth-complete") {
-          if (!params.server) {
+        if (dispatchParams.action === "auth-complete") {
+          if (!dispatchParams.server) {
             return {
               content: [{ type: "text" as const, text: "auth-complete requires `server`." }],
               details: { mode: "auth-complete", error: "missing_server" },
@@ -817,28 +988,28 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
             };
           }
           return signal
-            ? executeAuthComplete(state, params.server, input, signal)
-            : executeAuthComplete(state, params.server, input);
+            ? executeAuthComplete(state, dispatchParams.server, input, signal)
+            : executeAuthComplete(state, dispatchParams.server, input);
         }
-        if (params.tool) {
-          return executeCall(state, params.tool, parsedArgs, params.server, getPiTools, signal);
+        if (dispatchParams.tool) {
+          return executeCall(state, dispatchParams.tool, parsedArgs, dispatchParams.server, getPiTools, signal);
         }
-        if (params.connect) {
-          const result = await executeConnect(state, params.connect, signal);
+        if (dispatchParams.connect) {
+          const result = await executeConnect(state, dispatchParams.connect, signal);
           syncToolSurface(_ctx as ExtensionContext);
           return result;
         }
-        if (params.describe) {
-          return executeDescribe(state, params.describe);
+        if (dispatchParams.describe) {
+          return executeDescribe(state, dispatchParams.describe);
         }
-        if (params.instructions) {
-          return executeInstructions(state, params.instructions);
+        if (dispatchParams.instructions) {
+          return executeInstructions(state, dispatchParams.instructions);
         }
-        if (params.search !== undefined) {
-          return executeSearch(state, params.search, params.regex, params.server, params.includeSchemas, params.limit, params.offset);
+        if (dispatchParams.search !== undefined) {
+          return executeSearch(state, dispatchParams.search, dispatchParams.regex, dispatchParams.server, dispatchParams.includeSchemas, dispatchParams.limit, dispatchParams.offset);
         }
-        if (params.server) {
-          return executeList(state, params.server);
+        if (dispatchParams.server) {
+          return executeList(state, dispatchParams.server);
         }
         return executeStatus(state);
       },
@@ -895,4 +1066,20 @@ export function createMcpAdapter(options: McpAdapterOptions = {}) {
   };
 }
 
+/**
+ * Register an MCP server with the adapter installed for this Pi instance.
+ * Registrations are session/runtime scoped and never persisted. Duplicate
+ * names fail closed. Registered servers are proxy-tool-only; their tools
+ * become visible at the next tool sync. To change a definition, dispose the
+ * registration and register again.
+ */
+export function registerMcpServer(options: { pi: ExtensionAPI; name: string; definition: ServerEntry }): McpServerRegistration {
+  const { pi, name, definition } = options;
+  const register = runtimeRegistrars.get(pi);
+  if (!register) {
+    throw new Error("pi-mcp-adapter is not installed for this Pi instance");
+  }
+  return register(name, definition);
+}
+
 export default createMcpAdapter();

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

@@ -1,12 +1,13 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { McpExtensionState } from "./state.ts";
-import { formatToolName, isServerDisabled, resolveToolPrefix, type McpAdapterOptions, type PromptMetadata, type ToolMetadata } from "./types.ts";
+import { formatToolName, isServerDisabled, resolveToolPrefix, type McpAdapterOptions, type PromptMetadata, type ToolMetadata, type ToolSelectorCandidateIndex } from "./types.ts";
 import { existsSync } from "node:fs";
 import { cloneMcpConfig, loadMcpConfig } from "./config.ts";
 import { ConsentManager } from "./consent-manager.ts";
 import { McpLifecycleManager } from "./lifecycle.ts";
 import {
   computeServerHash,
+  createCachedToolSelectorCandidateIndex,
   getMetadataCachePath,
   getMissingConfiguredDirectToolServers,
   isServerCacheValid,
@@ -179,8 +180,20 @@ export async function initializeMcp(
     },
     ...(ui !== undefined ? { ui } : {}),
     sendMessage: (message, options) => {
-      if (!owner.isActive()) return;
-      pi.sendMessage(message as unknown as Parameters<typeof pi.sendMessage>[0], options);
+      const deliver = () => {
+        if (!owner.isActive()) return;
+        pi.sendMessage(message as unknown as Parameters<typeof pi.sendMessage>[0], options);
+      };
+      if (!options?.triggerTurn) {
+        deliver();
+        return;
+      }
+      void lifecycle.ensureConverged(owner.signal).then(deliver, error => {
+        if (!owner.isActive() || isAbortError(error, owner.signal)) return;
+        const detail = error instanceof Error ? error.message : String(error);
+        logger.debug(`MCP: pre-turn keep-alive convergence failed: ${sanitizeTerminalText(detail)}`);
+        deliver();
+      });
     },
     ...(options.statusEvents !== undefined ? { statusEvents: options.statusEvents } : {}),
   };
@@ -227,6 +240,7 @@ export async function initializeMcp(
   }
 
   const prefix = config.settings?.toolPrefix ?? "server";
+  let cachedSelectorCandidateIndex: ToolSelectorCandidateIndex | undefined;
 
   for (const [name, definition] of serverEntries) {
     const lifecycleMode = definition.lifecycle ?? "lazy";
@@ -243,7 +257,13 @@ export async function initializeMcp(
 
     const cachedEntry = cache?.servers?.[name];
     if (cachedEntry && isServerCacheValid(cachedEntry, definition)) {
-      const metadata = reconstructToolMetadata(name, cachedEntry, prefix, definition, config.mcpServers, cache ?? undefined);
+      const hasToolFilters =
+        (Array.isArray(definition.includeTools) && definition.includeTools.length > 0) ||
+        (Array.isArray(definition.excludeTools) && definition.excludeTools.length > 0);
+      if (hasToolFilters && !cachedSelectorCandidateIndex && cache) {
+        cachedSelectorCandidateIndex = createCachedToolSelectorCandidateIndex(config.mcpServers, cache, prefix);
+      }
+      const metadata = reconstructToolMetadata(name, cachedEntry, prefix, definition, config.mcpServers, cache ?? undefined, cachedSelectorCandidateIndex);
       toolMetadata.set(name, metadata);
       if (Array.isArray(cachedEntry.resources)) {
         resourceCounts.set(name, cachedEntry.resources.length);
@@ -419,6 +439,18 @@ export async function initializeMcp(
     updateStatusBar(state);
   });
 
+  lifecycle.setHealthRestoredCallback((serverName) => {
+    if (!owner.isActive()) return;
+    clearFailure(state, serverName);
+    updateStatusBar(state);
+  });
+
+  lifecycle.setAuthRequiredCallback((serverName) => {
+    if (!owner.isActive()) return;
+    clearFailure(state, serverName);
+    updateStatusBar(state);
+  });
+
   lifecycle.setIdleShutdownCallback((serverName) => {
     if (!owner.isActive()) return;
     const idleMinutes = getEffectiveIdleTimeoutMinutes(state, serverName);