@humain/terminal 0.1.0 → 0.2.1

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

@@ -0,0 +1,187 @@
+import { createHash } from "node:crypto";
+import type { McpExtensionState } from "./state.ts";
+import type { ToolMetadata } from "./types.ts";
+import { logger } from "./logger.ts";
+import { stableStringify } from "./utils.ts";
+
+export const MCP_APPROVAL_CUSTOM_TYPE = "mcp-approval-v1";
+
+export type SessionApprovalEntry =
+  | {
+      version: 1;
+      kind: "tool";
+      decision: "allow_for_session";
+      serverName: string;
+      originalToolName: string;
+      definitionHash: string;
+      argsHash: string;
+    }
+  | {
+      version: 1;
+      kind: "iframe";
+      decision: "allow" | "deny";
+      serverName: string;
+    };
+
+export type SessionApprovalWriter = (record: SessionApprovalEntry) => void;
+
+const TOOL_APPROVAL_KEYS = [
+  "version",
+  "kind",
+  "decision",
+  "serverName",
+  "originalToolName",
+  "definitionHash",
+  "argsHash",
+] as const;
+const IFRAME_APPROVAL_KEYS = ["version", "kind", "decision", "serverName"] as const;
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+export function computeToolArgumentsHash(args: unknown): string {
+  return createHash("sha256").update(stableStringify(args ?? {})).digest("hex");
+}
+
+export function computeToolDefinitionHash(
+  toolMeta: Pick<ToolMetadata, "originalName" | "inputSchema" | "resourceUri" | "uiResourceUri">,
+): string {
+  return createHash("sha256").update(stableStringify({
+    originalName: toolMeta.originalName,
+    inputSchema: toolMeta.inputSchema ?? null,
+    resourceUri: toolMeta.resourceUri ?? null,
+    uiResourceUri: toolMeta.uiResourceUri ?? null,
+  })).digest("hex");
+}
+
+export function makeToolApprovalKey(
+  serverName: string,
+  originalToolName: string,
+  definitionHash: string,
+  argsHash: string,
+): string {
+  return `${serverName}\u0000${originalToolName}\u0000${definitionHash}\u0000${argsHash}`;
+}
+
+export function getToolApprovalIdentity(
+  serverName: string,
+  toolMeta: Pick<ToolMetadata, "originalName" | "inputSchema" | "resourceUri" | "uiResourceUri">,
+  args: unknown,
+): { definitionHash: string; argsHash: string; cacheKey: string } {
+  const definitionHash = computeToolDefinitionHash(toolMeta);
+  const argsHash = computeToolArgumentsHash(args);
+  return {
+    definitionHash,
+    argsHash,
+    cacheKey: makeToolApprovalKey(serverName, toolMeta.originalName, definitionHash, argsHash),
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  const actualKeys = Object.keys(value);
+  return actualKeys.length === keys.length && keys.every(key => Object.hasOwn(value, key));
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+function isSha256(value: unknown): value is string {
+  return typeof value === "string" && SHA256_HEX.test(value);
+}
+
+function isSessionApprovalEntry(value: unknown): value is SessionApprovalEntry {
+  if (!isRecord(value) || value.version !== 1 || !isNonEmptyString(value.serverName)) return false;
+
+  if (value.kind === "tool") {
+    return hasExactKeys(value, TOOL_APPROVAL_KEYS)
+      && value.decision === "allow_for_session"
+      && isNonEmptyString(value.originalToolName)
+      && isSha256(value.definitionHash)
+      && isSha256(value.argsHash);
+  }
+
+  if (value.kind === "iframe") {
+    return hasExactKeys(value, IFRAME_APPROVAL_KEYS)
+      && (value.decision === "allow" || value.decision === "deny");
+  }
+
+  return false;
+}
+
+function isApprovalCustomEntry(entry: unknown): entry is { type: "custom"; data?: unknown } {
+  return isRecord(entry)
+    && entry.type === "custom"
+    && entry.customType === MCP_APPROVAL_CUSTOM_TYPE;
+}
+
+export function createSessionApprovalWriter(
+  appendEntry: (customType: string, data?: unknown) => void,
+  canAppend: (() => boolean) | undefined = undefined,
+): SessionApprovalWriter {
+  return (record) => {
+    if (canAppend && !canAppend()) return;
+    try {
+      appendEntry(MCP_APPROVAL_CUSTOM_TYPE, record);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      logger.debug(`MCP: failed to persist session approval: ${detail}`);
+    }
+  };
+}
+
+export function rememberToolApproval(
+  state: McpExtensionState,
+  serverName: string,
+  toolMeta: Pick<ToolMetadata, "originalName" | "inputSchema" | "resourceUri" | "uiResourceUri">,
+  args: unknown,
+): void {
+  const { definitionHash, argsHash, cacheKey } = getToolApprovalIdentity(serverName, toolMeta, args);
+  const approvedToolCalls = state.approvedToolCalls ??= new Map<string, true>();
+  if (approvedToolCalls.has(cacheKey)) return;
+
+  approvedToolCalls.set(cacheKey, true);
+  const record: SessionApprovalEntry = {
+    version: 1,
+    kind: "tool",
+    decision: "allow_for_session",
+    serverName,
+    originalToolName: toolMeta.originalName,
+    definitionHash,
+    argsHash,
+  };
+  try {
+    state.persistSessionApproval?.(record);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    logger.debug(`MCP: session approval persistence callback failed: ${detail}`);
+  }
+}
+
+export function restoreSessionApprovalState(
+  state: McpExtensionState,
+  branchEntries: readonly unknown[],
+): void {
+  const approvedToolCalls = state.approvedToolCalls ??= new Map<string, true>();
+  approvedToolCalls.clear();
+  state.consentManager.clear();
+
+  for (const entry of branchEntries) {
+    if (!isApprovalCustomEntry(entry)) continue;
+    if (!isSessionApprovalEntry(entry.data)) continue;
+
+    if (entry.data.kind === "tool") {
+      approvedToolCalls.set(makeToolApprovalKey(
+        entry.data.serverName,
+        entry.data.originalToolName,
+        entry.data.definitionHash,
+        entry.data.argsHash,
+      ), true);
+      continue;
+    }
+
+    state.consentManager.restoreDecision(entry.data.serverName, entry.data.decision === "allow");
+  }
+}

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

@@ -30,10 +30,18 @@ return result.data;
 2. Inspect the exact returned path with `await tools.describe({ path })`.
 3. Call it with `tools.call(path, args)`.
 
+Descriptors include `inputTypeScript` (a compact parameter shape, or formatted schema fallback). When a compact shape would omit documented fields, `inputGuidance` preserves their descriptions, including formats and units. Undocumented inputs stay compact.
+
+When advertised by the server, `outputSchema` is the original JSON Schema and `outputSchemaTarget` is `"data.structuredContent"`: it describes structured output inside the successful `{ ok: true, data }` call envelope, not the envelope itself. Inspect this schema for result fields and constraints; unsupported constructs remain intact rather than being presented as an approximate TypeScript type. Both output fields are absent when no output schema is advertised. Discovery and cache refresh preserve these optional schemas; old cache entries gain them on the next server metadata refresh. Ordinary search results do not include schemas.
+
 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.
 
+On success, `data` may still be the raw MCP `CallToolResult` envelope rather than the domain payload. Check `data.structuredContent` for the fields your script expects; if they are absent, inspect text blocks in `data.content` too (some servers emit newline-delimited JSON). If neither shape is understood, return or emit the envelope for inspection instead of coercing it to `[]` or `{}`.
+
 `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.
+Successful intermediate data bypasses presentation truncation, summarization, and artifact spill until the script emits, logs, or returns it. A fixed, non-configurable **16 MiB cumulative UTF-8 JSON transfer budget per script** covers sequential and parallel calls. A result exceeding the remaining budget returns `{ ok: false, error: { code: "intermediate_result_too_large", message } }` with a failed call trace; rejected calls do not consume the budget, but upstream side effects may already have happened. Resource calls retain transformed text or `"(empty resource)"`; emitted, logged, or returned output and ordinary MCP calls remain guarded. This is not a memory limit: responses, serialization, copies, concurrency, and script values still allocate memory, and synchronous serialization can delay deadline handling.
+
+`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, 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

@@ -7,6 +7,7 @@ import type { ToolMetadata, PromptMetadata, McpConfig, UiSessionMessages, UiStre
 import type { UiResourceHandler } from "./ui-resource-handler.ts";
 import type { McpRuntimeOwner } from "./runtime-owner.ts";
 import type { McpOAuthRuntime } from "./mcp-auth-flow.ts";
+import type { SessionApprovalWriter } from "./session-approvals.ts";
 
 export interface CompletedUiSession {
   serverName: string;
@@ -32,6 +33,8 @@ export interface McpExtensionState {
   manager: McpServerManager;
   lifecycle: McpLifecycleManager;
   toolMetadata: Map<string, ToolMetadata[]>;
+  /** Number of tools currently registered directly with Pi, by server. */
+  directToolCounts: Map<string, number>;
   /** Resource counts retained separately because tool metadata includes resource tools. */
   resourceCounts: Map<string, number>;
   promptMetadata: Map<string, PromptMetadata[]>;
@@ -40,12 +43,18 @@ export interface McpExtensionState {
   serverInstructions: Map<string, string>;
   config: McpConfig;
   programmaticConfig?: boolean;
+  /** Install validations must not publish durable cache entries before config persistence. */
+  provisionalInstalls?: Set<string>;
   oauthRuntime: McpOAuthRuntime;
   authStorageOptions: AuthStorageOptions;
   failureTracker: Map<string, number>;
   failureMessages: Map<string, string>;
-  /** Session-only approvals keyed by server and original tool name. */
+  /** Session-only approvals keyed by server, tool definition, and arguments. */
   approvedToolCalls: Map<string, true>;
+  /** Optional active-session sink for approval decisions. */
+  persistSessionApproval?: SessionApprovalWriter;
+  /** Session manager used to reject stale session-tree contexts. */
+  sessionManager?: ExtensionContext["sessionManager"];
   /** Shared event bus used by permission extensions to broker MCP approvals. */
   approvalEvents?: ExtensionAPI["events"];
   uiResourceHandler: UiResourceHandler;

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

@@ -1,7 +1,8 @@
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import { abortable } from "./abort.ts";
 import { combineAbortSignals } from "./runtime-owner.ts";
 import type { McpExtensionState } from "./state.ts";
+import { getToolApprovalIdentity, rememberToolApproval } from "./session-approvals.ts";
 import {
   getToolNameCandidates,
   matchesToolPattern,
@@ -20,18 +21,6 @@ export type ToolCallApprovalResult =
   | { ok: true }
   | { ok: false; reason: "denied" | "approval_required_headless" };
 
-function stableStringify(value: unknown): string {
-  if (value === null || value === undefined || typeof value !== "object") {
-    const serialized = JSON.stringify(value);
-    return serialized === undefined ? "undefined" : serialized;
-  }
-  if (Array.isArray(value)) {
-    return `[${value.map(item => stableStringify(item)).join(",")}]`;
-  }
-  const object = value as Record<string, unknown>;
-  return `{${Object.keys(object).sort().map(key => `${JSON.stringify(key)}:${stableStringify(object[key])}`).join(",")}}`;
-}
-
 export function isToolCallApprovalRequired(
   config: McpConfig,
   serverName: string,
@@ -148,21 +137,20 @@ export async function ensureToolCallApproved(
   origin: McpToolApprovalOrigin = toolMeta.resourceUri ? "resource" : "proxy",
   approvalMetadata?: ReadonlyMap<string, readonly ToolMetadata[]>,
 ): Promise<ToolCallApprovalResult> {
-  const argsHash = createHash("sha256").update(stableStringify(args ?? {})).digest("hex");
-  const cacheKey = `${serverName}\u0000${toolMeta.originalName}\u0000${argsHash}`;
-  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);
+    rememberToolApproval(state, serverName, toolMeta, args);
     return { ok: true };
   }
   if (brokerDecision === "deny") return { ok: false, reason: "denied" };
 
+  const { cacheKey } = getToolApprovalIdentity(serverName, toolMeta, args);
+  const approvedToolCalls = state.approvedToolCalls ??= new Map<string, true>();
+  if (approvedToolCalls.has(cacheKey)) {
+    return { ok: true };
+  }
+
   if (!isToolCallApprovalRequired(state.config, serverName, toolMeta, approvalMetadata ?? state.toolMetadata)) {
     return { ok: true };
   }
@@ -188,7 +176,7 @@ export async function ensureToolCallApproved(
     return { ok: true };
   }
   if (decision === "Allow for session") {
-    approvedToolCalls.set(cacheKey, true);
+    rememberToolApproval(state, serverName, toolMeta, args);
     return { ok: true };
   }
   return { ok: false, reason: "denied" };

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

@@ -108,6 +108,7 @@ export function buildToolMetadata(
       originalName: tool.name,
       description: tool.description ?? "",
       ...(tool.inputSchema !== undefined ? { inputSchema: tool.inputSchema } : {}),
+      ...(tool.outputSchema !== undefined ? { outputSchema: tool.outputSchema } : {}),
       ...(uiResourceUri !== undefined ? { uiResourceUri } : {}),
       ...(uiVisibility !== undefined ? { uiVisibility } : {}),
       ...(uiStreamMode !== undefined ? { uiStreamMode } : {}),
@@ -159,6 +160,19 @@ export function findToolByName(metadata: ToolMetadata[] | undefined, toolName: s
   return metadata.find(m => m.name.replace(/-/g, "_") === normalized);
 }
 
+/** Whether the schema formatter has field descriptions worth showing beside a compact shape. */
+export function hasSchemaDescriptions(schema: unknown, includeRoot = false): boolean {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) return false;
+  const s = schema as Record<string, unknown>;
+  if (includeRoot && typeof s.description === "string" && s.description.length > 0) return true;
+  const hasNestedDescription = (child: unknown) => hasSchemaDescriptions(child, true);
+  if (s.properties && typeof s.properties === "object" && !Array.isArray(s.properties)
+    && Object.values(s.properties).some(hasNestedDescription)) return true;
+  return hasNestedDescription(s.items)
+    || (Array.isArray(s.anyOf) && s.anyOf.some(hasNestedDescription))
+    || (Array.isArray(s.oneOf) && s.oneOf.some(hasNestedDescription));
+}
+
 export function formatSchema(schema: unknown, indent = "  "): string {
   if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
     return `${indent}(no schema)`;

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

@@ -10,6 +10,7 @@ import type {
 import type { TextContent, ImageContent } from "@earendil-works/pi-ai";
 import type { UiStreamMode, UiStreamSummary } from "./ui-stream-types.ts";
 import type { UiToolVisibility } from "./ui-tool-visibility.ts";
+import { createHash } from "node:crypto";
 
 export type Transport = McpTransport;
 
@@ -38,6 +39,7 @@ export interface McpServerStatusSnapshot {
   readonly name: string;
   readonly status: McpServerRuntimeStatus;
   readonly toolCount: number;
+  readonly directToolCount: number;
   readonly resourceCount?: number;
   readonly failedAgoSeconds?: number;
   readonly disabled: boolean;
@@ -85,6 +87,7 @@ export interface McpTool {
   title?: SdkTool["title"];
   description?: SdkTool["description"];
   inputSchema?: SdkTool["inputSchema"]; // JSON Schema
+  outputSchema?: SdkTool["outputSchema"]; // JSON Schema for structuredContent
   _meta?: SdkTool["_meta"];
 }
 
@@ -386,13 +389,15 @@ export interface OAuthConfig {
   grantType?: "authorization_code" | "client_credentials";
   /** Pre-registered client ID (optional, dynamic registration used if not provided) */
   clientId?: string;
-  /** Client secret for confidential clients */
+  /** Client secret for confidential clients; requires an explicit clientId when clientMetadataUrl is set. */
   clientSecret?: string;
+  /** Operator-supplied public HTTPS Client ID Metadata Document URL (SEP-991); opt-in, with DCR remaining the default. */
+  clientMetadataUrl?: string;
   /** Requested OAuth scopes */
   scope?: string;
   /** Extra authorization URL parameters for provider-specific extensions. Flow-owned parameters cannot be overridden. */
   authorizationParams?: Record<string, string>;
-  /** Exact authorization-code redirect URI for pre-registered clients. HTTPS redirects use manual callback URL completion. */
+  /** Authorization-code redirect URI. Loopback URIs may use `{port}` for an OS-assigned port; HTTPS redirects use manual completion. */
   redirectUri?: string;
   /** Client display name for dynamic registration */
   clientName?: string;
@@ -426,9 +431,13 @@ export interface ServerEntry {
   /** Explicit rmcp-mux Unix-domain socket path. Mutually exclusive with command and url. */
   socket?: string;
   env?: Record<string, string>;
+  /** Inherit the adapter process environment for stdio servers. Defaults to true; false keeps SDK platform defaults plus explicit env overlays. */
+  inheritEnv?: boolean;
   cwd?: string;
   // HTTP fields
   url?: string;
+  /** PEM CA bundle replacing default roots for this HTTPS MCP origin only. */
+  caFile?: string;
   headers?: Record<string, string>;
   /** Add or replace HTTP headers by running a trusted command for each request. */
   requestHeadersCommand?: HttpRequestHeadersCommand;
@@ -456,7 +465,7 @@ export interface ServerEntry {
   // Resource handling
   exposeResources?: boolean;
   // Direct tool registration
-  directTools?: boolean | string[];
+  directTools?: boolean | string[] | "search";
   // Override settings.toolPrefix for this server.
   toolPrefix?: ToolPrefix;
   // Include/exclude specific MCP tools/resources by original or prefixed name
@@ -510,6 +519,32 @@ export interface McpOutputGuardSettings {
 
 // Settings
 export type ToolPrefix = "server" | "none" | "short" | "mcp";
+
+const ENCODED_SERVER_NAMESPACE_MARKER = "_mcpns_";
+// Provider tool-name limit (64 for Bedrock, Anthropic, OpenAI) minus the `mcp__` proxy prefix.
+const MAX_SERVER_NAMESPACE_LENGTH = 59;
+
+export function formatServerNamespace(serverName: string): string {
+  const normalized = serverName.replace(/-/g, "_");
+  const safe = /^[A-Za-z0-9_]*$/.test(normalized) && !normalized.startsWith(ENCODED_SERVER_NAMESPACE_MARKER);
+  const body = safe ? normalized : encodeServerNamespace(normalized);
+  const namespace = safe ? body : `${ENCODED_SERVER_NAMESPACE_MARKER}${body}`;
+  if (namespace.length <= MAX_SERVER_NAMESPACE_LENGTH) return namespace;
+  // Hash the ASCII encoding, not the raw name: lone surrogates and U+FFFD share UTF-8 bytes.
+  const digest = createHash("sha256").update(namespace, "utf8").digest("hex").slice(0, 16);
+  // `_h_` cannot start an encoded body: `h` is neither `_` nor a hexadecimal digit.
+  const hashPrefix = `${ENCODED_SERVER_NAMESPACE_MARKER}_h_`;
+  const head = body.slice(0, MAX_SERVER_NAMESPACE_LENGTH - hashPrefix.length - digest.length - 1);
+  return `${hashPrefix}${head}_${digest}`;
+}
+
+// `_` becomes `__`, so `__` and `_<hex>_` form a prefix code and the encoding stays injective.
+function encodeServerNamespace(name: string): string {
+  return Array.from(name, character => {
+    if (character === "_") return "__";
+    return /^[A-Za-z0-9]$/.test(character) ? character : `_${character.codePointAt(0)!.toString(16)}_`;
+  }).join("");
+}
 export type HostConfigDiscovery = "off" | "prompt" | "on";
 export type McpFooterStatus = "full" | "compact" | "off";
 
@@ -551,11 +586,13 @@ export interface McpSettings {
   notifyOnStartupConnect?: boolean;
   /** Discover detected host-specific MCP configs only when explicitly enabled. */
   hostConfigDiscovery?: HostConfigDiscovery;
+  /** Trusted HOME-contained roots from which to discover ancestor project configs. */
+  ancestorConfigRoots?: string[];
   /** Agent Plugin package directories to load MCP servers from. */
   agentPluginPaths?: string[];
   idleTimeout?: number; // minutes, default 10, 0 to disable
   requestTimeoutMs?: number; // milliseconds, overrides the SDK request timeout when > 0
-  directTools?: boolean;
+  directTools?: boolean | "search";
   /**
    * Validate direct-tool inputs against the advertised schema after recovering
    * one JSON string layer for object and array properties. Defaults to false.
@@ -603,6 +640,8 @@ export interface McpSettings {
    * instruction when unset.
    */
   authRequiredMessage?: string;
+  /** Explicitly use AES-256-GCM files keyed by PI_MCP_ADAPTER_OAUTH_FILE_KEY instead of the OS credential store. */
+  oauthCredentialStore?: "encrypted-file";
   /**
    * Legacy OAuth tokens.json import directory.
    * Relative paths are resolved from the project root (cwd).
@@ -616,11 +655,21 @@ export interface McpSettings {
   oauthDir?: string;
 }
 
+export interface ClaudePluginConfig {
+  /** Explicit local Claude plugin directory. File-based config resolves relative paths from the active project cwd; createMcpAdapter snapshots programmatic paths against process.cwd(). */
+  path: string;
+  /** Load the plugin's root .mcp.json as low-precedence MCP defaults. */
+  mcp?: boolean;
+  /** Expose the plugin's root skills/ directory to Pi resource discovery. */
+  skills?: boolean;
+}
+
 // Root config
 export interface McpConfig {
   mcpServers: Record<string, ServerEntry>;
   imports?: ImportKind[];
   settings?: McpSettings;
+  claudePlugins?: ClaudePluginConfig[];
 }
 
 export interface McpAdapterOptions {
@@ -639,6 +688,7 @@ export interface ToolMetadata {
   uiResourceUri?: string; // For app-enabled tools: the UI resource URI
   uiVisibility?: UiToolVisibility[];
   inputSchema?: unknown;  // JSON Schema for parameters (stored for describe/errors)
+  outputSchema?: unknown; // Server schema for structuredContent (stored for describe)
   uiStreamMode?: UiStreamMode;
 }
 
@@ -652,6 +702,8 @@ export interface PromptMetadata {
 }
 
 export interface DirectToolSpec {
+  /** Registered inactive; `mcp({ search })` activates it (directTools: "search"). */
+  lazy?: boolean;
   serverName: string;
   originalName: string;
   prefixedName: string;
@@ -677,6 +729,7 @@ export interface CachedTool {
   name: string;
   description?: string;
   inputSchema?: unknown;
+  outputSchema?: unknown;
   uiResourceUri?: string;
   uiVisibility?: UiToolVisibility[];
   uiStreamMode?: "eager" | "stream-first";

package/dist/humain/mcp-adapter/vendor/ui-server.ts

@@ -2,7 +2,7 @@ import http, { type IncomingMessage, type ServerResponse } from "node:http";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
-import { buildAllowAttribute } from "./ui-app-bridge-helpers.ts";
+import { buildAllowAttribute, getToolUiResourceUri } from "./ui-app-bridge-helpers.ts";
 import {
   type CallToolRequest,
   type CallToolResult,
@@ -11,11 +11,12 @@ import { ContentBlockSchema } from "@modelcontextprotocol/core";
 import type { ConsentManager } from "./consent-manager.ts";
 import { ServerError, wrapError } from "./errors.ts";
 import { formatAuthRequiredMessage, normalizeToolArguments } from "./utils.ts";
-import { buildHostHtmlTemplate, buildCspMetaContent } from "./host-html-template.ts";
+import { buildHostHtmlTemplate, buildSandboxResourceCsp } from "./host-html-template.ts";
 import {
   buildSandboxProxyCsp,
   buildSandboxProxyHtml,
   SANDBOX_PROXY_PATH,
+  SANDBOX_RESOURCE_PATH_PREFIX,
 } from "./sandbox-proxy-template.ts";
 import { logger } from "./logger.ts";
 import type { McpServerManager } from "./server-manager.ts";
@@ -85,7 +86,8 @@ export interface UiServerOptions {
 
 export async function startUiServer(options: UiServerOptions): Promise<UiServerHandle> {
   const sessionToken = options.sessionToken ?? randomUUID();
-  const uiResourceToken = randomUUID();
+  const sandboxResourcePath = `${SANDBOX_RESOURCE_PATH_PREFIX}${randomUUID()}`;
+  const resourceAllow = buildAllowAttribute(options.resource.meta.permissions);
   const log = logger.child({
     component: "UiServer",
     server: options.serverName,
@@ -316,8 +318,12 @@ export async function startUiServer(options: UiServerOptions): Promise<UiServerH
     try {
       const method = req.method || "GET";
       const hostHeader = req.headers.host;
-      const url = new URL(req.url || "/", `http://${hostHeader || "127.0.0.1"}`);
-      if (hostHeader !== undefined && !isAllowedHost(url.hostname)) {
+      if (!hostHeader) {
+        sendText(res, 400, "Missing host");
+        return;
+      }
+      const url = new URL(req.url || "/", `http://${hostHeader}`);
+      if (!isAllowedHost(url.hostname)) {
         sendText(res, 403, "Invalid host");
         return;
       }
@@ -346,12 +352,11 @@ export async function startUiServer(options: UiServerOptions): Promise<UiServerH
 
         const html = buildHostHtmlTemplate({
           sessionToken,
-          uiResourceToken,
           serverName: options.serverName,
           toolName: options.toolName,
           toolArgs: options.toolArgs,
           resource: options.resource,
-          allowAttribute: buildAllowAttribute(options.resource.meta.permissions),
+          allowAttribute: resourceAllow,
           requireToolConsent: options.consentManager.requiresPrompt(options.serverName),
           cacheToolConsent: options.consentManager.shouldCacheConsent(),
           hostContext,
@@ -391,20 +396,6 @@ export async function startUiServer(options: UiServerOptions): Promise<UiServerH
         return;
       }
 
-      if (method === "GET" && url.pathname === "/ui-app") {
-        if (!validateTokenQuery(url, uiResourceToken, res, "resource")) return;
-        touchHeartbeat();
-        // Enforce host metadata independently of where app HTML places its document head.
-        const cspContent = buildCspMetaContent(options.resource.meta.csp);
-        res.writeHead(200, {
-          "Content-Type": "text/html; charset=utf-8",
-          "Cache-Control": "no-store",
-          "Content-Security-Policy": cspContent,
-        });
-        res.end(options.resource.html);
-        return;
-      }
-
       if (method === "GET" && url.pathname === "/app-bridge.bundle.js") {
         // Serve the pre-bundled AppBridge module
         const bundlePath = path.join(import.meta.dirname, "app-bridge.bundle.js");
@@ -473,11 +464,18 @@ export async function startUiServer(options: UiServerOptions): Promise<UiServerH
           name: callParams.name,
           arguments: normalizedArguments,
         };
+        let uiResourceUri: string | undefined;
+        try {
+          uiResourceUri = getToolUiResourceUri({ _meta: toolDefinition._meta });
+        } catch {
+          // Preserve the endpoint's existing behavior for malformed declarations.
+        }
         const toolMeta = {
           name: callParams.name,
           originalName: callParams.name,
           description: toolDefinition?.description ?? "",
           ...(toolDefinition?.inputSchema !== undefined ? { inputSchema: toolDefinition.inputSchema } : {}),
+          ...(uiResourceUri !== undefined ? { uiResourceUri } : {}),
           ...(uiVisibility !== undefined ? { uiVisibility } : {}),
         };
         const approvalMetadata = new Map(options.state?.toolMetadata);
@@ -711,31 +709,41 @@ export async function startUiServer(options: UiServerOptions): Promise<UiServerH
         try {
           const method = req.method || "GET";
           const hostHeader = req.headers.host;
-          const url = new URL(req.url || "/", `http://${hostHeader || "127.0.0.1"}`);
-          if (hostHeader !== undefined && !isAllowedHost(url.hostname)) {
+          if (!hostHeader) {
+            sendText(res, 400, "Missing host");
+            return;
+          }
+          const url = new URL(req.url || "/", `http://${hostHeader}`);
+          if (!isAllowedHost(url.hostname)) {
             sendText(res, 403, "Invalid host");
             return;
           }
 
-          if (method === "HEAD" && url.pathname === SANDBOX_PROXY_PATH) {
+          if ((method === "GET" || method === "HEAD") && url.pathname === SANDBOX_PROXY_PATH) {
             res.writeHead(200, {
               "Content-Type": "text/html; charset=utf-8",
               "Cache-Control": "no-store",
               "Content-Security-Policy": buildSandboxProxyCsp(),
+              "Referrer-Policy": "no-referrer",
+              "X-Content-Type-Options": "nosniff",
             });
-            res.end();
+            res.end(method === "HEAD" ? undefined : buildSandboxProxyHtml({
+              parentOrigin,
+              resourcePath: sandboxResourcePath,
+              allowAttribute: resourceAllow,
+            }));
             return;
           }
 
-          if (method === "GET" && url.pathname === SANDBOX_PROXY_PATH) {
+          if ((method === "GET" || method === "HEAD") && url.pathname === sandboxResourcePath) {
             res.writeHead(200, {
               "Content-Type": "text/html; charset=utf-8",
               "Cache-Control": "no-store",
-              "Content-Security-Policy": buildSandboxProxyCsp(),
+              "Content-Security-Policy": buildSandboxResourceCsp(options.resource.meta.csp),
               "Referrer-Policy": "no-referrer",
               "X-Content-Type-Options": "nosniff",
             });
-            res.end(buildSandboxProxyHtml({ parentOrigin }));
+            res.end(method === "HEAD" ? undefined : options.resource.html);
             return;
           }