@visual-z/xeno 0.5.0 → 0.7.0

package/src/runtime/mcp-client.ts

@@ -0,0 +1,264 @@
+/** Standard MCP adapters reuse the existing integration owner; no business request is automatically replayed. */
+import { createHash } from "node:crypto";
+import { pathToFileURL } from "node:url";
+import { Client, StreamableHTTPClientTransport, UnauthorizedError, InsufficientScopeError, SdkError, SdkHttpError, SdkErrorCode, extractWWWAuthenticateParams,
+  type Tool, type Transport, type FetchLike, type ContentBlock, type JsonSchemaType } from "@modelcontextprotocol/client";
+import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/client/stdio";
+import { parseMcpServers, type McpServerConfig, type McpServers } from "../core/mcp-config.ts";
+import { isJsonValue, type JsonValue } from "../core/tool-contract.ts";
+import type { IntegrationFailureCode } from "../core/integration-health.ts";
+import { FileMcpCredentialsStore, type McpCredentialsStore } from "../store/mcp-credentials.ts";
+import type { ExtensionIntegration, IntegrationConnection, IntegrationFailure } from "./integrations.ts";
+import type { ExtensionToolResult } from "./extensions.ts";
+import { McpAuthRequired, McpOAuthProvider } from "./mcp-oauth.ts";
+import { MAX_WEB_RESPONSE_BYTES, type WebFetch } from "./web-http.ts";
+import { McpSchemaError, McpSchemas } from "./mcp-schema.ts";
+import { ToolFault } from "../core/tool-failure.ts";
+
+export interface McpServerStatus { name: string; transport: "stdio" | "http"; state: "ready" | "disabled" | IntegrationFailureCode; tools: number; diagnostic?: string }
+export interface McpManagerOptions { cwd: string; credentialsDirectory: string; credentialsStore?: McpCredentialsStore;
+  env?: Readonly<Record<string, string | undefined>>; fetch?: WebFetch }
+class McpFailure extends Error {
+  readonly code: IntegrationFailureCode;
+  constructor(code: IntegrationFailureCode) { super(`MCP ${code}`); this.name = "McpFailure"; this.code = code; }
+}
+function fault(error: unknown): IntegrationFailure {
+  const code = error instanceof McpFailure ? error.code : error instanceof McpAuthRequired || error instanceof UnauthorizedError || error instanceof InsufficientScopeError ? "auth_required"
+    : error instanceof SdkHttpError ? error.status === 401 || error.status === 403 ? "auth_required" : error.status === 429 ? "rate_limited" : error.status >= 500 ? "offline" : "protocol_error"
+    : error instanceof SdkError && error.code === SdkErrorCode.RequestTimeout ? "timeout" : "protocol_error";
+  return { kind: "integration_failure", code };
+}
+export function mcpToolName(server: string, name: string, kind = "tool"): string {
+  const digest = createHash("sha256").update(JSON.stringify([server, kind, name])).digest("hex").slice(0, 12);
+  return `mcp_${server.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 12)}_${name.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 20)}_${digest}`;
+}
+function integrationName(name: string) { return `mcp_${name.slice(0, 48)}_${createHash("sha256").update(name).digest("hex").slice(0, 8)}`; }
+function immutable<T>(value: T): T {
+  if (value && typeof value === "object") { for (const entry of Object.values(value)) immutable(entry); Object.freeze(value); }
+  return value;
+}
+function contentResult(content: readonly ContentBlock[], details: unknown, isError = false): ExtensionToolResult {
+  const mapped: ExtensionToolResult["content"] = [];
+  for (const item of content) {
+    if (item.type === "text") mapped.push({ type: "text", text: item.text });
+    else if (item.type === "image") mapped.push({ type: "image", data: item.data, mimeType: item.mimeType });
+    else if (item.type === "resource" && "text" in item.resource) mapped.push({ type: "text", text: `Resource URI: ${item.resource.uri}\n${item.resource.text}` });
+    else if (item.type === "resource_link") mapped.push({ type: "text", text: `Resource: ${item.name}\nURI: ${item.uri}${item.description ? `\n${item.description}` : ""}` });
+    else mapped.push({ type: "text", text: `MCP ${item.type} content retained in the structured result; direct presentation unavailable.` });
+  }
+  return { content: mapped, ...(isJsonValue(details) ? { details } : {}), ...(isError ? { isError: true } : {}) };
+}
+interface Opened { server: string; client: Client; transport: Transport; tools: readonly Tool[]; schemas: McpSchemas; catalog: string; dirty: boolean; close(): Promise<void> }
+/** A single manager belongs to one app/session generation. Disposing never starts a replacement connection. */
+export class McpManager {
+  private readonly servers: McpServers;
+  private readonly options: McpManagerOptions;
+  private readonly store: McpCredentialsStore;
+  private readonly lifetime = new AbortController();
+  private readonly opened = new Set<Opened>();
+  private readonly oauth = new Map<string, McpOAuthProvider>();
+  private readonly statuses = new Map<string, McpServerStatus>();
+  private readonly challenges = new Map<string, { resourceMetadataUrl?: URL; scope?: string }>();
+  private discovered = false;
+  private disposal: Promise<void> | undefined;
+  constructor(servers: McpServers, options: McpManagerOptions) {
+    this.servers = parseMcpServers(servers); this.options = options;
+    this.store = options.credentialsStore ?? new FileMcpCredentialsStore(options.credentialsDirectory);
+  }
+  private async provider(name: string, config: Extract<McpServerConfig, { transport: "http" }>) {
+    let provider = this.oauth.get(name);
+    if (!provider) {
+      provider = await McpOAuthProvider.create(config.url, typeof config.oauth === "object" ? config.oauth : {}, this.store, this.options.env ?? process.env);
+      this.oauth.set(name, provider);
+    }
+    const challenge = this.challenges.get(name);
+    if (challenge) provider.setChallenge(challenge.resourceMetadataUrl, challenge.scope);
+    return provider;
+  }
+  private fetch(signal: AbortSignal, timeoutMs: number): FetchLike {
+    return async (input, init) => {
+      // Protocol session retirement has its own bounded finalizer after business cancellation.
+      // DELETE cannot start a business operation and must survive the owner's aborted request signal.
+      const cleanup = init?.method === "DELETE", combined = cleanup ? new AbortController().signal
+        : AbortSignal.any([signal, this.lifetime.signal, ...(init?.signal ? [init.signal] : [])]), controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), cleanup ? Math.min(timeoutMs, 5_000) : timeoutMs);
+      try {
+        const response = await (this.options.fetch ?? fetch)(input, { ...init, signal: AbortSignal.any([combined, controller.signal]), redirect: "manual" });
+        // Buffer JSON replies with a streamed cap. SSE remains a stream, also counted before parsing any event.
+        if (!response.body) { clearTimeout(timer); return response; }
+        const reader = response.body.getReader(); let seen = 0;
+        const body = new ReadableStream<Uint8Array>({
+          async pull(output) {
+            try {
+              const next = await reader.read();
+              if (next.done) { clearTimeout(timer); reader.releaseLock(); output.close(); return; }
+              seen += next.value.byteLength;
+              if (seen > MAX_WEB_RESPONSE_BYTES) { clearTimeout(timer); await reader.cancel(); output.error(new McpFailure("protocol_error")); return; }
+              output.enqueue(next.value);
+            } catch { clearTimeout(timer); output.error(new McpFailure(controller.signal.aborted ? "timeout" : "offline")); }
+          }, async cancel() { clearTimeout(timer); await reader.cancel(); }
+        });
+        return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+      } catch (error) { clearTimeout(timer); if (error instanceof McpAuthRequired) throw error; throw new McpFailure(controller.signal.aborted ? "timeout" : "offline"); }
+    };
+  }
+  private async open(name: string, config: McpServerConfig, signal: AbortSignal): Promise<Opened> {
+    signal.throwIfAborted(); this.lifetime.signal.throwIfAborted();
+    const timeout = config.timeoutMs ?? 60_000;
+    const schemas = new McpSchemas();
+    const client = new Client({ name: "xeno", version: "0.5.0" }, { capabilities: { roots: { listChanged: false } },
+      versionNegotiation: { mode: "auto" }, inputRequired: { autoFulfill: false }, listMaxPages: 64, jsonSchemaValidator: schemas });
+    client.setRequestHandler("roots/list", async () => ({ roots: [{ uri: pathToFileURL(this.options.cwd).href, name: "workspace" }] }));
+    // Remote log notifications and stderr are deliberately not copied into logs: they can contain server secrets.
+    client.onerror = () => {};
+    const combined = AbortSignal.any([signal, this.lifetime.signal]);
+    let closingTransport = false;
+    let transport: Transport;
+    if (config.transport === "stdio") {
+      const env: Record<string, string> = { ...getDefaultEnvironment() };
+      for (const [key, value] of Object.entries(config.env ?? {})) env[key] = value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match: string, variable: string) => {
+        const found = (this.options.env ?? process.env)[variable]; if (found === undefined) throw new McpFailure("auth_required"); return found;
+      });
+      transport = new StdioClientTransport({ command: config.command, args: config.args ?? [], env, cwd: this.options.cwd, stderr: "ignore", maxBufferSize: MAX_WEB_RESPONSE_BYTES });
+    } else {
+      const headers = new Headers(config.headers), env = this.options.env ?? process.env, baseFetch = this.fetch(combined, timeout);
+      const fetcher: FetchLike = async (input, init) => {
+        const response = await baseFetch(input, init);
+        if (response.status === 401 || response.status === 403) {
+          const challenge = extractWWWAuthenticateParams(response);
+          this.challenges.set(name, { ...(challenge.resourceMetadataUrl ? { resourceMetadataUrl: challenge.resourceMetadataUrl } : {}), ...(challenge.scope ? { scope: challenge.scope } : {}) });
+        }
+        return response;
+      };
+      for (const [header, variable] of Object.entries(config.headersEnv ?? {})) {
+        const value = env[variable]; if (!value) throw new McpFailure("auth_required"); headers.set(header, value);
+      }
+      const provider = config.oauth ? await this.provider(name, config) : undefined;
+      if (config.bearerTokenEnv && !env[config.bearerTokenEnv]) throw new McpFailure("auth_required");
+      transport = new StreamableHTTPClientTransport(new URL(config.url), { requestInit: { headers, redirect: "manual" }, fetch: fetcher,
+        // A token-only provider has no onUnauthorized callback: the SDK cannot re-authorize and resend a business call.
+        ...((provider || config.bearerTokenEnv) ? { authProvider: { token: async () => provider ? closingTransport ? provider.tokens()?.access_token : await provider.token(fetcher) : env[config.bearerTokenEnv!] } } : {}),
+        onInsufficientScope: "throw", reconnectionOptions: { maxRetries: 0, initialReconnectionDelay: 1_000, maxReconnectionDelay: 30_000, reconnectionDelayGrowFactor: 1.5 } });
+    }
+    const cancel = () => { void transport.close(); };
+    let shuttingDown: Promise<void> | undefined;
+    const shutdown = () => shuttingDown ??= (async () => {
+      closingTransport = true;
+      try {
+        if (transport instanceof StreamableHTTPClientTransport) await transport.terminateSession();
+      } catch (error) { throw new McpFailure(fault(error).code); }
+      finally { await client.close(); }
+    })();
+    combined.addEventListener("abort", cancel, { once: true });
+    try {
+      await client.connect(transport, { signal: combined, timeout, maxTotalTimeout: timeout });
+      const discovered = await client.listTools(undefined, { signal: combined, timeout, cacheMode: "bypass" });
+      if (discovered.tools.length > 1_024) throw new McpFailure("protocol_error");
+      const names = new Set(discovered.tools.map(tool => tool.name));
+      if (names.size !== discovered.tools.length) throw new McpFailure("protocol_error");
+      const tools = immutable(structuredClone(discovered.tools));
+      for (const tool of tools) { schemas.validator(tool.inputSchema); if (tool.outputSchema) schemas.validator(tool.outputSchema); }
+      const opened: Opened = { server: name, client, transport, tools, schemas, catalog: JSON.stringify(tools), dirty: false,
+        close: async () => { combined.removeEventListener("abort", cancel); try { await shutdown(); } finally { this.opened.delete(opened); } } };
+      for (const method of ["notifications/tools/list_changed", "notifications/prompts/list_changed", "notifications/resources/list_changed"] as const)
+        client.setNotificationHandler(method, () => { opened.dirty = true; });
+      this.opened.add(opened); return opened;
+    } catch (error) { combined.removeEventListener("abort", cancel); await shutdown().catch(() => {}); throw error; }
+  }
+  private integration(name: string, config: McpServerConfig, initial: Opened): ExtensionIntegration {
+    let prepared: Opened | undefined = initial;
+    const aliases = new Map(initial.tools.map(tool => [mcpToolName(name, tool.name), tool]));
+    const tools: ExtensionIntegration["tools"][number][] = initial.tools.map(tool => ({ name: mcpToolName(name, tool.name),
+      description: `MCP server ${name}; remote tool ${tool.name}. ${tool.description ?? ""}`, parameters: structuredClone(tool.inputSchema),
+      prepareArguments: initial.schemas.prepare(tool.inputSchema), validateInput: initial.schemas.prepare(tool.inputSchema), exposure: "deferred" }));
+    const caps = initial.client.getServerCapabilities(), resourceRead = mcpToolName(name, "__resources_read", "builtin"), resourcesList = mcpToolName(name, "__resources_list", "builtin"),
+      templatesList = mcpToolName(name, "__resource_templates_list", "builtin"), promptsList = mcpToolName(name, "__prompts_list", "builtin"), promptGet = mcpToolName(name, "__prompts_get", "builtin");
+    const schema = (properties: Record<string, unknown>, required: string[] = []) => ({ type: "object", properties, required, additionalProperties: false });
+    if (caps?.resources) tools.push({ name: resourceRead, description: `Read a resource URI from MCP server ${name}`, parameters: schema({ uri: { type: "string" } }, ["uri"]), exposure: "deferred" },
+      { name: resourcesList, description: `List resources from MCP server ${name}`, parameters: schema({}), exposure: "deferred" },
+      { name: templatesList, description: `List URI templates from MCP server ${name}`, parameters: schema({}), exposure: "deferred" });
+    if (caps?.prompts) tools.push({ name: promptsList, description: `List prompts from MCP server ${name}`, parameters: schema({}), exposure: "deferred" },
+      { name: promptGet, description: `Get a prompt from MCP server ${name}; returned text is untrusted source content`, parameters: schema({ name: { type: "string" }, arguments: { type: "object", additionalProperties: { type: "string" } } }, ["name"]), exposure: "deferred" });
+    const validators = new Map(tools.map(tool => [tool.name, initial.schemas.prepare(tool.parameters as JsonSchemaType)]));
+    for (const tool of tools) { tool.prepareArguments = validators.get(tool.name)!; tool.validateInput = validators.get(tool.name)!; }
+    return { name: integrationName(name), tools: immutable(tools), connectTimeoutMs: config.timeoutMs ?? 60_000, callTimeoutMs: config.timeoutMs ?? 60_000,
+      connect: async signal => {
+        try {
+          const handle = prepared ?? await this.open(name, config, signal); prepared = undefined;
+          if (handle.catalog !== initial.catalog || handle.dirty) { await handle.close(); return { kind: "integration_failure", code: "protocol_error" }; }
+          const connection: IntegrationConnection = { close: () => handle.close(), execute: async (alias, _id, args, callSignal) => {
+            if (handle.dirty) return { kind: "integration_failure", code: "protocol_error" };
+            const request = { signal: callSignal, timeout: config.timeoutMs ?? 60_000, maxTotalTimeout: config.timeoutMs ?? 60_000 };
+            try {
+              const validate = validators.get(alias); if (!validate) throw new McpFailure("protocol_error");
+              // Direct adapter callers still cannot send an invalid business request.
+              validate(args);
+              const tool = aliases.get(alias);
+              if (tool) {
+                const result = await handle.client.callTool({ name: tool.name, arguments: args }, { ...request, toolDefinition: tool });
+                return contentResult(result.content, result, result.isError);
+              }
+              let result: unknown;
+              if (caps?.resources && alias === resourceRead && typeof args["uri"] === "string") result = await handle.client.readResource({ uri: args["uri"] }, { ...request, cacheMode: "bypass" });
+              else if (caps?.resources && alias === resourcesList) result = await handle.client.listResources(undefined, { ...request, cacheMode: "bypass" });
+              else if (caps?.resources && alias === templatesList) result = await handle.client.listResourceTemplates(undefined, { ...request, cacheMode: "bypass" });
+              else if (caps?.prompts && alias === promptsList) result = await handle.client.listPrompts(undefined, { ...request, cacheMode: "bypass" });
+              else if (caps?.prompts && alias === promptGet && typeof args["name"] === "string") {
+                const values = args["arguments"];
+                if (values !== undefined && (!values || typeof values !== "object" || Array.isArray(values) || Object.values(values).some(value => typeof value !== "string"))) throw new McpFailure("protocol_error");
+                result = await handle.client.getPrompt({ name: args["name"], ...(values ? { arguments: values as Record<string, string> } : {}) }, request);
+              } else throw new McpFailure("protocol_error");
+              return { content: [{ type: "text", text: JSON.stringify(result) }], ...(isJsonValue(result) ? { details: result } : {}) };
+            } catch (error) {
+              if (error instanceof ToolFault) return { isError: true, content: [{ type: "text", text: error.message }] };
+              const failure = fault(error);
+              this.statuses.set(name, { name, transport: config.transport, state: failure.code, tools: tools.length });
+              return failure;
+            }
+          } }; return connection;
+        } catch (error) { return fault(error); }
+      } };
+  }
+  async discover(signal?: AbortSignal): Promise<{ integrations: ExtensionIntegration[]; statuses: McpServerStatus[] }> {
+    // Registered generations keep ownership until disposal; rediscovery must never overlap their connections.
+    if (this.discovered) throw new McpFailure("protocol_error");
+    this.discovered = true;
+    const combined = AbortSignal.any([this.lifetime.signal, ...(signal ? [signal] : [])]), integrations: ExtensionIntegration[] = [];
+    for (const [name, config] of Object.entries(this.servers)) {
+      if (config.enabled === false) { this.statuses.set(name, { name, transport: config.transport, state: "disabled", tools: 0 }); continue; }
+      try {
+        const opened = await this.open(name, config, combined), definition = this.integration(name, config, opened);
+        if (definition.tools.length) integrations.push(definition);
+        this.statuses.set(name, { name, transport: config.transport, state: "ready", tools: definition.tools.length });
+      } catch (error) { this.statuses.set(name, { name, transport: config.transport, state: fault(error).code, tools: 0,
+        ...(error instanceof McpSchemaError ? { diagnostic: error.message } : {}) }); }
+    }
+    return { integrations, statuses: this.status() };
+  }
+  status(): McpServerStatus[] { return [...this.statuses.values()].map(status => ({ ...status })); }
+  async login(name: string, onAuthorizationUrl: (url: URL) => void | Promise<void>, signal?: AbortSignal): Promise<void> {
+    const config = this.servers[name];
+    if (!config || config.transport !== "http" || config.oauth === false || config.bearerTokenEnv) throw new McpAuthRequired();
+    const timeout = AbortSignal.timeout(300_000), combined = AbortSignal.any([timeout, this.lifetime.signal, ...(signal ? [signal] : [])]);
+    try { await (await this.provider(name, config)).login(onAuthorizationUrl, this.fetch(combined, 30_000), combined); }
+    catch { throw new McpAuthRequired(); }
+  }
+  async logout(name: string): Promise<void> {
+    const config = this.servers[name]; if (!config || config.transport !== "http") throw new McpAuthRequired();
+    await Promise.all([...this.opened].filter(handle => handle.server === name).map(handle => handle.close()));
+    await (await this.provider(name, config)).invalidateCredentials("all"); this.oauth.delete(name);
+    this.statuses.set(name, { name, transport: config.transport, state: "auth_required", tools: 0 });
+  }
+  dispose(): Promise<void> {
+    if (this.disposal) return this.disposal;
+    this.lifetime.abort();
+    return this.disposal = (async () => {
+      const results = await Promise.allSettled([...this.opened].map(opened => opened.close()));
+      const failure = results.find(result => result.status === "rejected");
+      if (failure?.status === "rejected") throw new McpFailure(fault(failure.reason).code);
+    })();
+  }
+}
+
+/** JsonValue is intentionally used only after validation; remote schema/result types never own evidence. */
+export function mcpStatusData(statuses: readonly McpServerStatus[]): JsonValue { return statuses.map(status => ({ ...status })); }

package/src/runtime/mcp-oauth.ts

@@ -0,0 +1,168 @@
+/** OAuth is a user-owned repair operation; the SDK owns discovery, PKCE and issuer/resource binding. */
+import { randomUUID } from "node:crypto";
+import { auth, checkResourceAllowed, resourceUrlFromServerUrl, StreamableHTTPClientTransport,
+  type OAuthClientProvider, type OAuthClientInformationContext, type StoredOAuthClientInformation, type StoredOAuthTokens,
+  type OAuthClientMetadata, type OAuthDiscoveryState, type FetchLike } from "@modelcontextprotocol/client";
+import type { McpOAuthConfig } from "../core/mcp-config.ts";
+import { isJsonValue } from "../core/tool-contract.ts";
+import type { McpCredentials, McpCredentialsStore } from "../store/mcp-credentials.ts";
+import { boundedResponseBytes } from "./web-http.ts";
+
+export class McpAuthRequired extends Error { constructor() { super("MCP authentication requires an explicit login"); this.name = "McpAuthRequired"; } }
+/** The SDK warns with OAuth error_description; normalize peer errors before they can reach its console path. */
+export function safeOAuthFetch(fetcher: FetchLike): FetchLike {
+  return async (input, init) => {
+    let response: Response;
+    try { response = await fetcher(input, init); } catch { throw new McpAuthRequired(); }
+    if (response.ok) return response;
+    let code = "server_error";
+    try {
+      const value: unknown = JSON.parse(new TextDecoder().decode(await boundedResponseBytes(response, 16 * 1024)));
+      if (value && typeof value === "object" && "error" in value && typeof value.error === "string"
+        && ["invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type", "invalid_scope", "access_denied", "server_error", "temporarily_unavailable"].includes(value.error)) code = value.error;
+    } catch { /* Unknown peer bodies contribute status only, never diagnostics containing secrets. */ }
+    return Response.json({ error: code, error_description: "OAuth request rejected" }, { status: response.status, headers: { "content-type": "application/json" } });
+  };
+}
+function savedClient(value: unknown): value is StoredOAuthClientInformation {
+  return !!value && typeof value === "object" && "client_id" in value && typeof value.client_id === "string";
+}
+function savedTokens(value: unknown): value is StoredOAuthTokens {
+  return !!value && typeof value === "object" && "access_token" in value && typeof value.access_token === "string"
+    && "token_type" in value && typeof value.token_type === "string";
+}
+/** A per-resource provider; discovery/verifier/state exist only during this owned process's login. */
+export class McpOAuthProvider implements OAuthClientProvider {
+  private readonly url: string;
+  private readonly config: McpOAuthConfig;
+  private readonly store: McpCredentialsStore;
+  private readonly env: Readonly<Record<string, string | undefined>>;
+  private credentials: McpCredentials;
+  private verifier: string | undefined;
+  private discovery: OAuthDiscoveryState | undefined;
+  private expectedState: string | undefined;
+  private redirect: ((url: URL) => void | Promise<void>) | undefined;
+  private refreshing: Promise<void> | undefined;
+  private resourceMetadataUrl: URL | undefined;
+  private challengedScope: string | undefined;
+  private constructor(url: string, config: McpOAuthConfig,
+    store: McpCredentialsStore, env: Readonly<Record<string, string | undefined>>, credentials?: McpCredentials) {
+    this.url = url; this.config = config; this.store = store; this.env = env;
+    this.credentials = credentials ?? { version: 1, serverUrl: url, redirectUrl: config.redirectUrl ?? "http://127.0.0.1:0/callback",
+      clients: {}, tokens: {}, expiresAt: {}, activeIssuer: null, ...(config.clientId ? { clientIdentity: config.clientId } : {}) };
+    if (config.redirectUrl) this.credentials.redirectUrl = config.redirectUrl;
+  }
+  static async create(url: string, config: McpOAuthConfig, store: McpCredentialsStore, env: Readonly<Record<string, string | undefined>>) {
+    return new McpOAuthProvider(url, config, store, env, await store.read(url, config.clientId));
+  }
+  get redirectUrl() { return this.credentials.redirectUrl; }
+  get clientMetadata(): OAuthClientMetadata {
+    return { client_name: "xeno", application_type: "native", redirect_uris: [this.redirectUrl], response_types: ["code"],
+      grant_types: ["authorization_code", "refresh_token"], token_endpoint_auth_method: this.config.clientSecretEnv ? "client_secret_basic" : "none",
+      ...(this.config.scope ? { scope: this.config.scope } : {}) };
+  }
+  clientInformation(ctx?: OAuthClientInformationContext): StoredOAuthClientInformation | undefined {
+    if (this.config.clientId) {
+      const secret = this.config.clientSecretEnv ? this.env[this.config.clientSecretEnv] : undefined;
+      if (this.config.clientSecretEnv && !secret) throw new McpAuthRequired();
+      return { client_id: this.config.clientId, ...(secret ? { client_secret: secret } : {}), ...(ctx ? { issuer: ctx.issuer } : {}) };
+    }
+    const value = ctx ? this.credentials.clients[ctx.issuer] : undefined;
+    return savedClient(value) ? value : undefined;
+  }
+  async saveClientInformation(info: StoredOAuthClientInformation, ctx?: OAuthClientInformationContext) {
+    const issuer = ctx?.issuer ?? info.issuer;
+    if (!issuer || !isJsonValue(info)) throw new McpAuthRequired();
+    this.credentials.clients[issuer] = info;
+    await this.store.write(this.credentials);
+  }
+  tokens(ctx?: OAuthClientInformationContext): StoredOAuthTokens | undefined {
+    const issuer = ctx?.issuer ?? this.credentials.activeIssuer, value = issuer ? this.credentials.tokens[issuer] : undefined;
+    return savedTokens(value) ? value : undefined;
+  }
+  async saveTokens(tokens: StoredOAuthTokens, ctx?: OAuthClientInformationContext) {
+    const issuer = ctx?.issuer ?? tokens.issuer;
+    if (!issuer || !isJsonValue(tokens)) throw new McpAuthRequired();
+    this.credentials.tokens[issuer] = tokens; this.credentials.activeIssuer = issuer;
+    if (tokens.expires_in !== undefined) this.credentials.expiresAt[issuer] = Date.now() + tokens.expires_in * 1_000;
+    else delete this.credentials.expiresAt[issuer];
+    await this.store.write(this.credentials);
+  }
+  state() { this.expectedState = randomUUID(); return this.expectedState; }
+  redirectToAuthorization(url: URL) {
+    if (!this.redirect) throw new McpAuthRequired();
+    return this.redirect(url);
+  }
+  saveCodeVerifier(verifier: string) { this.verifier = verifier; }
+  codeVerifier() { if (!this.verifier) throw new McpAuthRequired(); return this.verifier; }
+  saveDiscoveryState(state: OAuthDiscoveryState) { this.discovery = state; }
+  discoveryState() { return this.discovery; }
+  setChallenge(resourceMetadataUrl: URL | undefined, scope: string | undefined) {
+    this.resourceMetadataUrl = resourceMetadataUrl; this.challengedScope = scope; this.discovery = undefined;
+  }
+  private authOptions(fetcher: FetchLike) {
+    const scope = this.config.scope ?? this.challengedScope;
+    return { serverUrl: this.url, fetchFn: safeOAuthFetch(fetcher), ...(this.resourceMetadataUrl ? { resourceMetadataUrl: this.resourceMetadataUrl } : {}), ...(scope ? { scope } : {}) };
+  }
+  async validateResourceURL(serverUrl: string | URL, resource?: string) {
+    const expected = resourceUrlFromServerUrl(serverUrl);
+    if (resource && !checkResourceAllowed({ requestedResource: expected, configuredResource: resource })) throw new McpAuthRequired();
+    return expected;
+  }
+  async invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier" | "discovery") {
+    if (scope === "all" || scope === "client") this.credentials.clients = {};
+    if (scope === "all" || scope === "tokens") { this.credentials.tokens = {}; this.credentials.expiresAt = {}; this.credentials.activeIssuer = null; }
+    if (scope === "all" || scope === "verifier") this.verifier = undefined;
+    if (scope === "all" || scope === "discovery") this.discovery = undefined;
+    if (scope === "all") await this.store.remove(this.url, this.config.clientId); else await this.store.write(this.credentials);
+  }
+  async token(fetcher: FetchLike): Promise<string | undefined> {
+    const issuer = this.credentials.activeIssuer, expiresAt = issuer ? this.credentials.expiresAt[issuer] : undefined;
+    // Assumed 30s skew prevents sending a token that expires while the new request is in flight.
+    if (expiresAt !== undefined && expiresAt <= Date.now() + 30_000) {
+      if (!this.refreshing) {
+        this.refreshing = (async () => {
+          if (!this.tokens()?.refresh_token) { await this.invalidateCredentials("tokens"); throw new McpAuthRequired(); }
+          try { if (await auth(this, this.authOptions(fetcher)) !== "AUTHORIZED") throw new McpAuthRequired(); }
+          catch { await this.invalidateCredentials("tokens"); throw new McpAuthRequired(); }
+        })().finally(() => { this.refreshing = undefined; });
+      }
+      await this.refreshing;
+    }
+    return this.tokens()?.access_token;
+  }
+  async login(onAuthorizationUrl: (url: URL) => void | Promise<void>, fetcher: FetchLike, signal: AbortSignal): Promise<void> {
+    if (this.redirect) throw new McpAuthRequired();
+    signal.throwIfAborted();
+    const callback = new URL(this.redirectUrl);
+    let resolveCallback: (value: URLSearchParams) => void = () => {}, rejectCallback: (error: Error) => void = () => {};
+    const received = new Promise<URLSearchParams>((resolve, reject) => { resolveCallback = resolve; rejectCallback = reject; });
+    // Reject handlers are installed before starting auth; cancellation never leaves an unhandled callback promise.
+    void received.catch(() => {});
+    const server = Bun.serve({ hostname: "127.0.0.1", port: Number(callback.port), fetch: request => {
+      const current = new URL(request.url);
+      if (current.pathname !== callback.pathname) return new Response("Not found", { status: 404 });
+      if (request.method !== "GET" || !this.expectedState || current.searchParams.get("state") !== this.expectedState) return new Response("Invalid authorization state", { status: 400 });
+      if (current.searchParams.has("error") || !current.searchParams.get("code")) {
+        rejectCallback(new McpAuthRequired()); return new Response("Authorization was not completed", { status: 400 });
+      }
+      resolveCallback(current.searchParams); return new Response("Authorization received. Return to xeno.", { headers: { "content-type": "text/plain" } });
+    } });
+    const selected = new URL(callback.pathname, server.url).href;
+    if (selected !== this.credentials.redirectUrl && !this.config.clientId) this.credentials.clients = {};
+    this.credentials.redirectUrl = selected; this.redirect = onAuthorizationUrl;
+    const onAbort = () => rejectCallback(new McpAuthRequired());
+    signal.addEventListener("abort", onAbort, { once: true });
+    try {
+      const safeFetch = safeOAuthFetch(fetcher);
+      const result = await auth(this, this.authOptions(fetcher));
+      if (result === "AUTHORIZED") return;
+      const params = await received;
+      const transport = new StreamableHTTPClientTransport(new URL(this.url), { authProvider: this, fetch: safeFetch, onInsufficientScope: "throw" });
+      try { await transport.finishAuth(params); } finally { await transport.close(); }
+    } finally {
+      signal.removeEventListener("abort", onAbort); server.stop(true); this.redirect = undefined;
+      this.expectedState = undefined; this.verifier = undefined; this.discovery = undefined;
+    }
+  }
+}

package/src/runtime/mcp-schema.ts

@@ -0,0 +1,51 @@
+/** MCP 2025-11-25 defaults to 2020-12; validation never repairs the frozen invocation. */
+import { Ajv, type ValidateFunction } from "ajv";
+import { Ajv2019 } from "ajv/dist/2019.js";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { addFormats } from "@modelcontextprotocol/client/validators/ajv";
+import type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator } from "@modelcontextprotocol/client";
+import { NOT_STARTED, ToolFault } from "../core/tool-failure.ts";
+
+export class McpSchemaError extends Error {
+  constructor() { super("MCP schema is invalid or uses an unsupported dialect, reference, keyword or format; repair the server schema before reloading."); this.name = "McpSchemaError"; }
+}
+
+/** The official client's format package is bundled in its public validator entry; no extra dependency. */
+export class McpSchemas implements jsonSchemaValidator {
+  private readonly compiled = new Map<string, ValidateFunction>();
+  validator(schema: unknown): ValidateFunction {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema)) throw new McpSchemaError();
+    const key = JSON.stringify(schema), cached = this.compiled.get(key);
+    if (cached) return cached;
+    try {
+      const dialect = (schema as Record<string, unknown>)["$schema"];
+      const options = { strictSchema: true, strictNumbers: true, strictTypes: false, strictTuples: false, strictRequired: false,
+        validateFormats: true, coerceTypes: false, useDefaults: false, removeAdditional: false, allErrors: false, logger: false as const };
+      // Strict schema rejects unknown semantics, while strict style checks are disabled:
+      // valid JSON Schema need not spell out every tuple bound or repeat inherited types.
+      const ajv = dialect === undefined || dialect === "https://json-schema.org/draft/2020-12/schema" ? new Ajv2020(options)
+        : dialect === "https://json-schema.org/draft/2019-09/schema" ? new Ajv2019(options)
+        : dialect === "http://json-schema.org/draft-07/schema#" || dialect === "http://json-schema.org/draft-07/schema" ? new Ajv(options)
+        : undefined;
+      if (!ajv) throw new McpSchemaError();
+      addFormats(ajv);
+      // MCP's header annotation is interpreted by the official transport, not a validation constraint.
+      ajv.addKeyword({ keyword: "x-mcp-header", schemaType: "string", valid: true });
+      // Ajv validates this entire JSON schema; the assertion only bridges the SDK's wider wire type.
+      const validate = ajv.compile(structuredClone(schema) as JsonSchemaType);
+      this.compiled.set(key, validate); return validate;
+    } catch { throw new McpSchemaError(); }
+  }
+  getValidator<T>(schema: JsonSchemaType): JsonSchemaValidator<T> {
+    const validate = this.validator(schema);
+    return input => validate(input) ? { valid: true, data: input as T, errorMessage: undefined }
+      : { valid: false, data: undefined, errorMessage: "MCP structured output failed the advertised schema." };
+  }
+  prepare(schema: unknown): (input: unknown) => unknown {
+    const validate = this.validator(schema);
+    return input => {
+      if (!validate(input)) throw new ToolFault("invalid_input", "MCP arguments do not satisfy the complete advertised schema. Correct the input before calling the remote tool.", NOT_STARTED);
+      return input;
+    };
+  }
+}

package/src/runtime/oauth.ts

@@ -18,7 +18,7 @@ import { pollDeviceCode } from "./oauth-device.ts";
 import { parseDeviceAuthorization, parseOAuthTokens } from "../core/oauth-fields.ts";
 
 /** Matches package.json. Sent as User-Agent so the server can see who we are (D18). */
-export const XENO_VERSION = "0.5.0";
+export const XENO_VERSION = "0.7.0";
 
 /**
  * Minutes subtracted from server expiry so a request issued at the edge

package/src/runtime/openai-responses.ts

@@ -24,6 +24,7 @@ import { assertNever } from "../core/exhaustive.ts";
 import type { OnDelta, Provider, ProviderConfig, ToolSchema, Turn } from "./provider.ts";
 import { pushSse, HttpError, StreamError } from "./openai.ts";
 import { withRetry, DEFAULT_RETRY, type RetryPolicy } from "./retry.ts";
+import type { ProviderSendOptions } from "./provider-tool-policy.ts";
 
 /** What this adapter parks in a thinking block's raw: the reasoning item, whole. */
 interface ResponsesRaw { responses_item: Record<string, unknown> }
@@ -266,19 +267,20 @@ export class OpenAIResponsesProvider implements Provider {
     this.onRetry = options.onRetry;
   }
 
-  send(frozen: FrozenPrefix, messages: readonly Message[], node: number, signal?: AbortSignal, onDelta?: OnDelta): Promise<Turn> {
-    return withRetry(() => this.attempt(frozen, messages, node, signal, onDelta), this.retry, undefined,
+  send(frozen: FrozenPrefix, messages: readonly Message[], node: number, signal?: AbortSignal, onDelta?: OnDelta, options?: ProviderSendOptions): Promise<Turn> {
+    return withRetry(() => this.attempt(frozen, messages, node, signal, onDelta, options), this.retry, undefined,
       (attempt, delayMs, error) => { onDelta?.({ kind: "discard" }); onDelta?.({ kind: "retry", attempt, delayMs }); this.onRetry?.(attempt, delayMs, error); }, signal);
   }
 
-  private async attempt(frozen: FrozenPrefix, messages: readonly Message[], node: number, signal?: AbortSignal, onDelta?: OnDelta): Promise<Turn> {
+  private async attempt(frozen: FrozenPrefix, messages: readonly Message[], node: number, signal?: AbortSignal, onDelta?: OnDelta, options?: ProviderSendOptions): Promise<Turn> {
     const started = Date.now();
     const baseUrl = this.config.spec.baseUrl;
     if (baseUrl === undefined) throw new Error(`model ${this.config.spec.id} has no baseUrl to send to`);
     const init: RequestInit = {
       method: "POST",
       headers: { "content-type": "application/json", authorization: `Bearer ${this.apiKey}` },
-      body: JSON.stringify({ ...buildResponsesRequest(this.config, frozen, messages), stream: true }),
+      body: JSON.stringify({ ...buildResponsesRequest(this.config, frozen, messages), stream: true,
+        ...(options?.toolUse === "disabled" ? { tool_choice: "none" } : {}) }),
     };
     if (signal !== undefined) init.signal = signal;
     const response = await this.fetchImpl(`${baseUrl.replace(/\/$/, "")}/responses`, init);

package/src/runtime/openai.ts

@@ -26,6 +26,7 @@ import { assertNever } from "../core/exhaustive.ts";
 import type { Provider, ProviderConfig, Turn, ToolSchema, OnDelta } from "./provider.ts";
 import { DEFAULT_COMPAT, type Compat, type Effort, type ModelSpec } from "./model.ts";
 import { withRetry, DEFAULT_RETRY, type RetryPolicy } from "./retry.ts";
+import type { ProviderSendOptions } from "./provider-tool-policy.ts";
 
 /** One message as Chat Completions wants it. */
 export interface WireMessage {
@@ -48,6 +49,7 @@ export interface WireRequest {
   max_tokens?: number;
   max_completion_tokens?: number;
   tools?: unknown[];
+  tool_choice?: "none";
   thinking?: { type: "enabled" | "disabled" };
   reasoning_effort?: string;
 }
@@ -434,11 +436,12 @@ export class OpenAICompletionsProvider implements Provider {
     node: number,
     signal?: AbortSignal,
     onDelta?: OnDelta,
+    options?: ProviderSendOptions,
   ): Promise<Turn> {
     // The clock starts inside the retried request, so a reported duration is
     // one attempt rather than the sum of the ones that failed.
     return withRetry(
-      () => this.attempt(frozen, messages, node, signal, onDelta),
+      () => this.attempt(frozen, messages, node, signal, onDelta, options),
       this.retry,
       undefined,
       (attempt, delayMs, error) => {
@@ -456,6 +459,7 @@ export class OpenAICompletionsProvider implements Provider {
     node: number,
     signal?: AbortSignal,
     onDelta?: OnDelta,
+    options?: ProviderSendOptions,
   ): Promise<Turn> {
     const started = Date.now();
     const baseUrl = this.config.spec.baseUrl;
@@ -468,6 +472,7 @@ export class OpenAICompletionsProvider implements Provider {
       stream: true;
       stream_options?: { include_usage: true };
     } = { ...buildRequest(this.config, frozen, messages), stream: true };
+    if (options?.toolUse === "disabled") payload.tool_choice = "none";
     // Without include_usage an OpenAI-dialect stream never reports usage, and
     // the loop would treat the resulting zeros as a real prompt size. Servers
     // that 400 on the field opt out via Compat.supportsUsageInStreaming.

package/src/runtime/output-schema.ts

@@ -0,0 +1,26 @@
+/** Ajv owns JSON Schema semantics; validation never repairs model output (D11/D13). */
+import { Ajv } from "ajv";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { Ajv2019 } from "ajv/dist/2019.js";
+import { addFormats } from "@modelcontextprotocol/client/validators/ajv";
+
+export type OutputValidation = { ok: true; value: unknown } | { ok: false; error: string };
+export function outputValidator(schema: unknown): (text: string) => OutputValidation {
+  if (typeof schema !== "boolean" && (schema === null || typeof schema !== "object" || Array.isArray(schema))) throw Error("output schema must be a JSON Schema object or boolean");
+  const dialect = typeof schema === "object" && schema !== null && "$schema" in schema ? String(schema.$schema) : "";
+  const options = { allErrors: true, strictSchema: true, strictTypes: false, strictTuples: false, strictRequired: false, validateFormats: true,
+    coerceTypes: false, useDefaults: false, removeAdditional: false, logger: false as const };
+  const ajv = dialect === "https://json-schema.org/draft/2020-12/schema" ? new Ajv2020(options)
+    : dialect === "https://json-schema.org/draft/2019-09/schema" ? new Ajv2019(options)
+    : dialect === "" || dialect === "http://json-schema.org/draft-07/schema#" || dialect === "http://json-schema.org/draft-07/schema" ? new Ajv(options) : undefined;
+  if (!ajv) throw Error("unsupported output schema dialect");
+  // The approved MCP client exposes Ajv's standard formats; share them rather than silently ignoring formats.
+  addFormats(ajv);
+  const validate = ajv.compile(schema);
+  return text => {
+    let value: unknown;
+    try { value = JSON.parse(text); } catch { return { ok: false, error: "final output is not JSON" }; }
+    if (!validate(value)) return { ok: false, error: ajv.errorsText(validate.errors, { separator: "; " }).slice(0, 2048) };
+    return { ok: true, value };
+  };
+}