stitchkit 0.45.0 → 0.47.0

package/dist/tools.js

@@ -2,10 +2,10 @@ import {
   inputIsQuery,
   signJwt,
   verifyPkce
-} from "./index-36f1xkdb.js";
+} from "./index-nrytvb30.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS
-} from "./index-6jypn22c.js";
+} from "./index-r1qp4rve.js";
 import {
   assertToolName,
   assertUniqueToolName,
@@ -26,13 +26,15 @@ import {
   toolErrorFromResult,
   toolResultFromError,
   writeDownload
-} from "./index-mvjyq9h9.js";
+} from "./index-kp8xamqp.js";
 import {
+  isWithinDir,
+  realPathWithinDir,
   toJsonSchema
-} from "./index-frfyw9fa.js";
+} from "./index-yxpe3phd.js";
 import {
-  isWithinDir
-} from "./index-x3fcszf8.js";
+  redact
+} from "./index-8ekq6res.js";
 import {
   AppError,
   getRequestContext,
@@ -43,7 +45,7 @@ import {
   resolvePropagationContext,
   runWithRequestContext,
   typedEntries
-} from "./index-yh0p5ddn.js";
+} from "./index-ee621cmy.js";
 
 // src/tools/agent.ts
 import { jsonSchema, tool } from "ai";
@@ -452,7 +454,11 @@ async function runRoundFailure(tool2, rawArgs, runTool, context, code, message)
     }
   }, rawArgs, context);
 }
-function validatePolicy(tool2, policy, maxRounds) {
+function validateMcpRoundPolicy(tool2, policy, runtime) {
+  if (!runtime?.stateConfigured) {
+    throw new Error(`[stitchkit] MCP tool "${tool2.name}" declares inputRequired but no multiRound.state key is configured`);
+  }
+  const { maxRounds } = runtime;
   if (!Number.isInteger(maxRounds) || maxRounds < 1) {
     throw new Error("[stitchkit] multiRound.serving.maxRounds must be a positive integer");
   }
@@ -485,7 +491,10 @@ async function resolveMcpRound(options) {
   if (!options.runtime) {
     throw new Error(`[stitchkit] MCP tool "${options.tool.name}" declares inputRequired but no multiRound.state key is configured`);
   }
-  validatePolicy(options.tool, policy, options.runtime.maxRounds);
+  validateMcpRoundPolicy(options.tool, policy, {
+    stateConfigured: true,
+    maxRounds: options.runtime.maxRounds
+  });
   const requests = policy.inputRequired;
   const state = options.context.mcpReq.requestState();
   const digest = await argumentsDigest(options.rawArgs);
@@ -599,104 +608,6 @@ async function resolveMcpRound(options) {
   };
 }
 
-// src/tools/mcp-trace.ts
-import {
-  BAGGAGE_META_KEY,
-  TRACEPARENT_META_KEY,
-  TRACESTATE_META_KEY
-} from "@modelcontextprotocol/server";
-function runInMcpRequestContext(context, toolName, body) {
-  const ambient = getRequestContext();
-  const metadata = context.mcpReq._meta;
-  const propagation = metadata ? {
-    traceparent: metadata[TRACEPARENT_META_KEY],
-    tracestate: metadata[TRACESTATE_META_KEY],
-    baggage: metadata[BAGGAGE_META_KEY]
-  } : undefined;
-  const request = {
-    ...ambient ?? {
-      source: "mcp",
-      method: "MCP",
-      path: `/mcp/${toolName}`,
-      startedAt: process.hrtime.bigint()
-    },
-    trace: resolvePropagationContext(propagation, ambient?.trace),
-    source: "mcp",
-    method: "MCP",
-    path: `/mcp/${toolName}`,
-    startedAt: process.hrtime.bigint(),
-    dimensions: ambient?.dimensions ? { ...ambient.dimensions } : undefined,
-    error: undefined
-  };
-  return runWithRequestContext(request, body);
-}
-
-// src/tools/native-mcp.ts
-import {
-  isCallToolResult
-} from "@modelcontextprotocol/server";
-import { z } from "zod";
-function mountPreparedRuntimeMcp(server, tools, config) {
-  for (const { definition, descriptor } of tools) {
-    const { mountable } = descriptor;
-    const toolConfig = {
-      description: definition.description,
-      inputSchema: z.looseObject({}).meta(presentationMetadata(descriptor.inputSchema))
-    };
-    if (descriptor.outputSchema)
-      toolConfig.outputSchema = descriptor.outputSchema;
-    if (definition.annotations)
-      toolConfig.annotations = definition.annotations;
-    if (definition.ui) {
-      toolConfig._meta = {
-        ui: definition.ui,
-        "ui/resourceUri": definition.ui.resourceUri
-      };
-    }
-    server.registerTool(definition.name, toolConfig, async (rawArgs, mcpContext) => runInMcpRequestContext(mcpContext, definition.name, async () => {
-      const args = isRecord(rawArgs) ? rawArgs : {};
-      const runTool = (tool2, toolArgs, roundContext) => executeToolMethod(tool2.method, definition.name, toolArgs, { ...config.context, ...roundContext, source: "mcp" }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true, config.onOutputStrip ? (paths) => config.onOutputStrip?.(definition.name, paths) : undefined);
-      const round = await resolveMcpRound({
-        tool: mountable,
-        rawArgs: args,
-        context: mcpContext,
-        policy: mountable.method.mcp,
-        runtime: config.multiRoundRuntime,
-        runTool,
-        formatFailure: (result) => config.formatResult(result, "none", definition.name)
-      });
-      if (round.kind === "response")
-        return round.response;
-      if (!definition.present?.mcp) {
-        const result = await runTool(mountable, args, round.context);
-        return config.formatResult(result, descriptor.outputMode, definition.name);
-      }
-      const presentedResult = await executeToolMethod(mountable.method, definition.name, args, { ...config.context, ...round.context, source: "mcp" }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true, config.onOutputStrip ? (paths) => config.onOutputStrip?.(definition.name, paths) : undefined, undefined, async (data) => {
-        const presented = await definition.present?.mcp?.(data);
-        if (!presented) {
-          throw new AppError("INTERNAL_SERVER_ERROR", "Runtime MCP presenter did not return a result", 500);
-        }
-        if ("structuredContent" in presented || "isError" in presented) {
-          throw new AppError("INTERNAL_SERVER_ERROR", "Runtime MCP presenter cannot set framework-owned structuredContent or isError", 500);
-        }
-        const structured = config.formatResult({ ok: true, data }, descriptor.outputMode, definition.name).structuredContent;
-        const response = structured === undefined ? presented : { ...presented, structuredContent: structured };
-        if (!isCallToolResult(response)) {
-          throw new AppError("INTERNAL_SERVER_ERROR", "Runtime MCP presenter returned an invalid CallToolResult", 500);
-        }
-        return response;
-      });
-      if (!presentedResult.ok) {
-        return config.formatResult(presentedResult, "none", definition.name);
-      }
-      if (!isCallToolResult(presentedResult.data)) {
-        throw new Error("[stitchkit] Runtime MCP presenter invariant failed");
-      }
-      return presentedResult.data;
-    }));
-  }
-}
-
 // src/tools/portable-formats.ts
 var PORTABLE_JSON_SCHEMA_FORMATS = new Set([
   "date",
@@ -854,7 +765,7 @@ function findUntypedProperties(schema, prefix = "") {
   return found;
 }
 
-// src/tools/mcp.ts
+// src/tools/mcp-prepare.ts
 function textBlock(text) {
   return [{ type: "text", text }];
 }
@@ -862,9 +773,15 @@ function formatMcpResult(result, mode, toolName, errorHint) {
   if (result.ok) {
     if (mode === "none")
       return { content: [] };
-    const serialized = JSON.stringify(result.data, null, 2);
+    let serialized;
+    try {
+      serialized = JSON.stringify(result.data, null, 2);
+    } catch {
+      serialized = undefined;
+    }
     if (serialized === undefined) {
-      throw new Error(`[stitchkit] MCP tool "${toolName ?? "unknown"}" produced a non-JSON output`);
+      const safe = redact(result.data, { sensitiveKeys: /(?!)/ });
+      return { content: textBlock(JSON.stringify(safe, null, 2)), structuredContent: safe };
     }
     return { content: textBlock(serialized), structuredContent: result.data };
   }
@@ -907,6 +824,9 @@ function prepareMcpTool(mountable, config, validation, logger, failures, seen) {
   const policy = validation.policy ?? "throw";
   assertUniqueToolName(mountable.name, seen.has(mountable.name), "MCP tool name");
   seen.add(mountable.name);
+  if (mountable.method.mcp) {
+    validateMcpRoundPolicy(mountable, mountable.method.mcp, config.multiRound);
+  }
   let inputJsonSchema;
   try {
     inputJsonSchema = buildToolPresentationSchema({
@@ -998,7 +918,8 @@ function prepareMcpServerSurface(surface, config = {}) {
   const contractTools = prepareMcpTools(contractMountables, config);
   const runtimeDescriptors = prepareMcpTools(runtimeMountables, {
     schemaValidation: config.schemaValidation,
-    logger: config.logger
+    logger: config.logger,
+    multiRound: config.multiRound
   });
   const descriptorsByName = new Map(runtimeDescriptors.map((descriptor) => [descriptor.mountable.name, descriptor]));
   const runtimeTools = [];
@@ -1009,6 +930,106 @@ function prepareMcpServerSurface(surface, config = {}) {
   }
   return Object.freeze({ contractTools, runtimeTools: Object.freeze(runtimeTools) });
 }
+
+// src/tools/mcp-trace.ts
+import {
+  BAGGAGE_META_KEY,
+  TRACEPARENT_META_KEY,
+  TRACESTATE_META_KEY
+} from "@modelcontextprotocol/server";
+function runInMcpRequestContext(context, toolName, body) {
+  const ambient = getRequestContext();
+  const metadata = context.mcpReq._meta;
+  const propagation = metadata ? {
+    traceparent: metadata[TRACEPARENT_META_KEY],
+    tracestate: metadata[TRACESTATE_META_KEY],
+    baggage: metadata[BAGGAGE_META_KEY]
+  } : undefined;
+  const request = {
+    ...ambient ?? {
+      source: "mcp",
+      method: "MCP",
+      path: `/mcp/${toolName}`,
+      startedAt: process.hrtime.bigint()
+    },
+    trace: resolvePropagationContext(propagation, ambient?.trace),
+    source: "mcp",
+    method: "MCP",
+    path: `/mcp/${toolName}`,
+    startedAt: process.hrtime.bigint(),
+    dimensions: ambient?.dimensions ? { ...ambient.dimensions } : undefined,
+    error: undefined
+  };
+  return runWithRequestContext(request, body);
+}
+
+// src/tools/native-mcp.ts
+import {
+  isCallToolResult
+} from "@modelcontextprotocol/server";
+import { z } from "zod";
+function mountPreparedRuntimeMcp(server, tools, config) {
+  for (const { definition, descriptor } of tools) {
+    const { mountable } = descriptor;
+    const toolConfig = {
+      description: definition.description,
+      inputSchema: z.looseObject({}).meta(presentationMetadata(descriptor.inputSchema))
+    };
+    if (descriptor.outputSchema)
+      toolConfig.outputSchema = descriptor.outputSchema;
+    if (definition.annotations)
+      toolConfig.annotations = definition.annotations;
+    if (definition.ui) {
+      toolConfig._meta = {
+        ui: definition.ui,
+        "ui/resourceUri": definition.ui.resourceUri
+      };
+    }
+    server.registerTool(definition.name, toolConfig, async (rawArgs, mcpContext) => runInMcpRequestContext(mcpContext, definition.name, async () => {
+      const args = isRecord(rawArgs) ? rawArgs : {};
+      const runTool = (tool2, toolArgs, roundContext) => executeToolMethod(tool2.method, definition.name, toolArgs, { ...config.context, ...roundContext, source: "mcp" }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true, config.onOutputStrip ? (paths) => config.onOutputStrip?.(definition.name, paths) : undefined);
+      const round = await resolveMcpRound({
+        tool: mountable,
+        rawArgs: args,
+        context: mcpContext,
+        policy: mountable.method.mcp,
+        runtime: config.multiRoundRuntime,
+        runTool,
+        formatFailure: (result) => config.formatResult(result, "none", definition.name)
+      });
+      if (round.kind === "response")
+        return round.response;
+      if (!definition.present?.mcp) {
+        const result = await runTool(mountable, args, round.context);
+        return config.formatResult(result, descriptor.outputMode, definition.name);
+      }
+      const presentedResult = await executeToolMethod(mountable.method, definition.name, args, { ...config.context, ...round.context, source: "mcp" }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true, config.onOutputStrip ? (paths) => config.onOutputStrip?.(definition.name, paths) : undefined, undefined, async (data) => {
+        const presented = await definition.present?.mcp?.(data);
+        if (!presented) {
+          throw new AppError("INTERNAL_SERVER_ERROR", "Runtime MCP presenter did not return a result", 500);
+        }
+        if ("structuredContent" in presented || "isError" in presented) {
+          throw new AppError("INTERNAL_SERVER_ERROR", "Runtime MCP presenter cannot set framework-owned structuredContent or isError", 500);
+        }
+        const structured = config.formatResult({ ok: true, data }, descriptor.outputMode, definition.name).structuredContent;
+        const response = structured === undefined ? presented : { ...presented, structuredContent: structured };
+        if (!isCallToolResult(response)) {
+          throw new AppError("INTERNAL_SERVER_ERROR", "Runtime MCP presenter returned an invalid CallToolResult", 500);
+        }
+        return response;
+      });
+      if (!presentedResult.ok) {
+        return config.formatResult(presentedResult, "none", definition.name);
+      }
+      if (!isCallToolResult(presentedResult.data)) {
+        throw new Error("[stitchkit] Runtime MCP presenter invariant failed");
+      }
+      return presentedResult.data;
+    }));
+  }
+}
+
+// src/tools/mcp.ts
 function validateMcpSchemas(config) {
   prepareMcpSurface(config.services, {
     extend: config.extend,
@@ -1096,7 +1117,11 @@ function buildMcpServer(config, auth) {
     extend: config.extend,
     flattenUnionInput: config.flattenUnionInput,
     schemaValidation: config.schemaValidation,
-    logger: config.logger
+    logger: config.logger,
+    multiRound: {
+      stateConfigured: config.multiRound !== undefined,
+      maxRounds: config.multiRound?.serving?.maxRounds ?? 10
+    }
   });
   return buildMcpServerFromPrepared(config, auth, prepared);
 }
@@ -1182,6 +1207,8 @@ function mountMcpResource(server, resource) {
 import {
   createMcpHandler as createSdkMcpHandler,
   hostHeaderValidationResponse,
+  localhostAllowedHostnames,
+  localhostAllowedOrigins,
   originValidationResponse
 } from "@modelcontextprotocol/server";
 
@@ -1229,28 +1256,25 @@ function oauthProtectedResourceRoute(config) {
 function jsonRpcError(code, message, status, headers) {
   return Response.json({ jsonrpc: "2.0", error: { code, message }, id: null }, { status, headers });
 }
-function defaultHostRejection(request) {
-  const host = request.headers.get("host");
-  if (!host || host === new URL(request.url).host)
+function hostValidationResponse(request, allowedHosts) {
+  if (request.headers.has("host")) {
+    return hostHeaderValidationResponse(request, [...allowedHosts]);
+  }
+  const hostname = new URL(request.url).hostname;
+  if (allowedHosts.includes(hostname))
     return;
   return jsonRpcError(-32000, "Invalid Host header", 403);
 }
-function defaultOriginRejection(request) {
-  const origin = request.headers.get("origin");
-  if (!origin)
-    return;
-  try {
-    if (new URL(origin).origin === new URL(request.url).origin)
-      return;
-  } catch {}
-  return jsonRpcError(-32000, "Invalid Origin header", 403);
-}
 function prepareStaticSurface(config) {
   const preparation = {
     logger: config.logger,
     extend: config.extend,
     flattenUnionInput: config.flattenUnionInput,
-    schemaValidation: config.schemaValidation
+    schemaValidation: config.schemaValidation,
+    multiRound: {
+      stateConfigured: config.multiRound !== undefined,
+      maxRounds: config.multiRound?.serving?.maxRounds ?? 10
+    }
   };
   if (config.surfaces && config.selectSurface) {
     const preparedByKey = new Map;
@@ -1317,10 +1341,12 @@ function createMcpHandler(config) {
       if (closed) {
         return observeRejection(request, jsonRpcError(-32000, "MCP handler is closed", 503));
       }
-      const hostRejection = config.security?.allowedHosts ? hostHeaderValidationResponse(request, [...config.security.allowedHosts]) : defaultHostRejection(request);
+      const allowedHosts = config.security?.allowedHosts ?? localhostAllowedHostnames();
+      const hostRejection = hostValidationResponse(request, allowedHosts);
       if (hostRejection)
         return observeRejection(request, hostRejection);
-      const originRejection = config.security?.allowedOrigins ? originValidationResponse(request, [...config.security.allowedOrigins]) : defaultOriginRejection(request);
+      const allowedOrigins = config.security?.allowedOrigins ?? localhostAllowedOrigins();
+      const originRejection = originValidationResponse(request, [...allowedOrigins]);
       if (originRejection)
         return observeRejection(request, originRejection);
       const auth = await Promise.race([
@@ -1330,7 +1356,7 @@ function createMcpHandler(config) {
       if (closed) {
         return observeRejection(request, jsonRpcError(-32000, "MCP handler is closed", 503));
       }
-      if (auth === null)
+      if (auth == null)
         return observeRejection(request, unauthorized());
       const authCarrier = {
         token: "",
@@ -1370,7 +1396,7 @@ async function createStdioMcpServer(config) {
   });
 }
 // src/tools/mount-download.ts
-import { basename, extname, join } from "node:path";
+import { basename, extname, resolve } from "node:path";
 import { z as z3 } from "zod";
 
 // src/tools/native-result.ts
@@ -1419,7 +1445,9 @@ function mountDownload(server, config) {
       const url = await config.resolveUrl(args);
       if (!url)
         return textResult("Nothing to download.", true);
-      const res = await fetchGuarded(new URL(url), config.allowPrivateHosts ?? false);
+      const res = await fetchGuarded(new URL(url), config.allowPrivateHosts ?? false, {
+        timeoutMs: config.timeoutMs
+      });
       if (!res.ok)
         return textResult(`Download failed: HTTP ${res.status}`, true);
       const mimeType = (res.headers.get("content-type") ?? "").split(";")[0]?.trim() || "application/octet-stream";
@@ -1432,8 +1460,8 @@ function mountDownload(server, config) {
       const buffer = await readCapped(res, max);
       if (!buffer)
         return textResult(`Download failed: file exceeds the ${max}-byte cap`, true);
-      const dir = config.dirFromArgs?.(args) ?? config.defaultDir;
-      const filePath = join(dir, `${baseNameFor(url)}${extensionFor(url, mimeType)}`);
+      const dir = resolve(config.dirFromArgs?.(args) ?? config.defaultDir);
+      const filePath = resolve(dir, `${baseNameFor(url)}${extensionFor(url, mimeType)}`);
       await writeDownload(dir, filePath, buffer);
       return textResult(JSON.stringify({ path: filePath, size: buffer.length, mimeType }, null, 2));
     } catch (err) {
@@ -1557,6 +1585,13 @@ function assertCimdClientId(clientId) {
   }
   return url;
 }
+function parseAgeSeconds(headers) {
+  const raw = headers.get("age");
+  if (raw === null)
+    return 0;
+  const first = raw.split(",")[0]?.trim() ?? "";
+  return /^\d+$/.test(first) ? Number(first) : 0;
+}
 function responseFreshness(headers, policy, now) {
   const maxTtl = policy.maxTtlMs ?? 3600000;
   const cacheControl = headers.get("cache-control") ?? "";
@@ -1566,26 +1601,28 @@ function responseFreshness(headers, policy, now) {
   if (/(?:^|,)\s*no-cache\s*(?:,|$)/i.test(cacheControl)) {
     return { freshnessMs: 0, store: true };
   }
-  const maxAge = cacheControl.match(/(?:^|,)\s*max-age=(\d+)/i)?.[1];
+  const maxAge = cacheControl.match(/(?:^|,)\s*max-age=([^,\s]*)/i)?.[1];
   if (maxAge !== undefined) {
-    const age = Number(headers.get("age") ?? 0);
+    if (!/^\d+$/.test(maxAge))
+      return { freshnessMs: 0, store: true };
+    const age = parseAgeSeconds(headers);
     return {
       freshnessMs: Math.max(0, Math.min(maxTtl, (Number(maxAge) - age) * 1000)),
       store: true
     };
   }
   const expires = headers.get("expires");
-  if (expires) {
+  if (expires !== null) {
     const expiresAt = Date.parse(expires);
-    if (Number.isFinite(expiresAt)) {
-      const dateAt = Date.parse(headers.get("date") ?? "");
-      const ageMs = Number(headers.get("age") ?? 0) * 1000;
-      const lifetime = Number.isFinite(dateAt) ? expiresAt - dateAt : expiresAt - now;
-      return {
-        freshnessMs: Math.max(0, Math.min(maxTtl, lifetime - ageMs)),
-        store: true
-      };
-    }
+    if (!Number.isFinite(expiresAt))
+      return { freshnessMs: 0, store: true };
+    const dateAt = Date.parse(headers.get("date") ?? "");
+    const ageMs = parseAgeSeconds(headers) * 1000;
+    const lifetime = Number.isFinite(dateAt) ? expiresAt - dateAt : expiresAt - now;
+    return {
+      freshnessMs: Math.max(0, Math.min(maxTtl, lifetime - ageMs)),
+      store: true
+    };
   }
   return { freshnessMs: Math.min(maxTtl, policy.defaultTtlMs ?? 300000), store: true };
 }
@@ -1617,10 +1654,21 @@ function isJsonContentType(value) {
 function createCimdResolver(options) {
   const policy = options.cache ?? {};
   const now = options.now ?? Date.now;
-  const cache = new Map;
+  const positives = new Map;
+  const negatives = new Map;
   const inflight = new Map;
   const maxEntries = policy.maxEntries ?? 256;
+  const maxResolutions = policy.maxResolutions ?? 120;
+  const maxResolutionsPerClient = policy.maxResolutionsPerClient ?? 10;
+  const resolutionWindowMs = policy.resolutionWindowMs ?? 60000;
+  let resolutionWindowStartedAt = now();
+  let resolutionsInWindow = 0;
+  const clientWindows = new Map;
+  const CLIENT_WINDOW_CAP = 4096;
   assertPositiveInteger("cimd.cache.maxEntries", maxEntries);
+  assertPositiveInteger("cimd.cache.maxResolutions", maxResolutions);
+  assertPositiveInteger("cimd.cache.maxResolutionsPerClient", maxResolutionsPerClient);
+  assertPositiveInteger("cimd.cache.resolutionWindowMs", resolutionWindowMs);
   assertNonNegativeInteger("cimd.cache.defaultTtlMs", policy.defaultTtlMs ?? 300000);
   assertNonNegativeInteger("cimd.cache.maxTtlMs", policy.maxTtlMs ?? 3600000);
   assertNonNegativeInteger("cimd.cache.negativeTtlMs", policy.negativeTtlMs ?? 1e4);
@@ -1629,19 +1677,35 @@ function createCimdResolver(options) {
       options.onCacheEvent?.(event);
     } catch {}
   };
-  const touch = (key, value) => {
-    cache.delete(key);
-    cache.set(key, value);
-    while (cache.size > maxEntries) {
-      const oldest = cache.keys().next().value;
+  const readCache = (key) => positives.get(key) ?? negatives.get(key);
+  const trimOldest = (pool) => {
+    while (pool.size > maxEntries) {
+      const oldest = pool.keys().next().value;
       if (oldest === undefined)
         break;
-      cache.delete(oldest);
+      pool.delete(oldest);
     }
   };
+  const touch = (key, value) => {
+    if (value.ok) {
+      negatives.delete(key);
+      positives.delete(key);
+      positives.set(key, value);
+      trimOldest(positives);
+    } else {
+      positives.delete(key);
+      negatives.delete(key);
+      negatives.set(key, value);
+      trimOldest(negatives);
+    }
+  };
+  const dropCache = (key) => {
+    positives.delete(key);
+    negatives.delete(key);
+  };
   const resolveOne = async (clientId) => {
     const url = assertCimdClientId(clientId);
-    const cached = cache.get(clientId);
+    const cached = readCache(clientId);
     if (cached && cached.expiresAt > now()) {
       touch(clientId, cached);
       if (cached.ok) {
@@ -1652,17 +1716,40 @@ function createCimdResolver(options) {
       throw new Error(cached.message);
     }
     emit({ clientId, status: "miss" });
+    const currentTime = now();
+    if (currentTime - resolutionWindowStartedAt >= resolutionWindowMs) {
+      resolutionWindowStartedAt = currentTime;
+      resolutionsInWindow = 0;
+    }
+    let clientWindow = clientWindows.get(clientId);
+    if (!clientWindow || currentTime - clientWindow.startedAt >= resolutionWindowMs) {
+      clientWindow = { startedAt: currentTime, count: 0 };
+      clientWindows.delete(clientId);
+      clientWindows.set(clientId, clientWindow);
+      while (clientWindows.size > CLIENT_WINDOW_CAP) {
+        const oldest = clientWindows.keys().next().value;
+        if (oldest === undefined)
+          break;
+        clientWindows.delete(oldest);
+      }
+    }
+    if (clientWindow.count >= maxResolutionsPerClient) {
+      throw new Error("CIMD metadata resolution rate limit exceeded for this client_id");
+    }
+    if (resolutionsInWindow >= maxResolutions) {
+      throw new Error("CIMD metadata resolution rate limit exceeded");
+    }
+    clientWindow.count += 1;
+    resolutionsInWindow += 1;
     const conditionalHeaders = {};
     if (cached?.ok && cached.etag)
       conditionalHeaders["if-none-match"] = cached.etag;
     if (cached?.ok && cached.lastModified) {
       conditionalHeaders["if-modified-since"] = cached.lastModified;
     }
-    let cacheFailure = true;
     try {
       const response = await options.fetcher.fetch(url, conditionalHeaders);
       const freshness = responseFreshness(response.headers, policy, now());
-      cacheFailure = freshness.store;
       if (response.status === 304 && cached?.ok) {
         const refreshed = {
           ...cached,
@@ -1671,7 +1758,7 @@ function createCimdResolver(options) {
         if (freshness.store)
           touch(clientId, refreshed);
         else
-          cache.delete(clientId);
+          dropCache(clientId);
         emit({ clientId, status: "revalidated", freshnessMs: freshness.freshnessMs });
         return refreshed.client;
       }
@@ -1691,7 +1778,7 @@ function createCimdResolver(options) {
         throw new Error("CIMD redirect_uris contains a URI forbidden for the application type");
       }
       const client = toRegisteredClient(metadata);
-      if (freshness.store) {
+      if (freshness.store && Number.isFinite(freshness.freshnessMs)) {
         touch(clientId, {
           ok: true,
           client,
@@ -1704,18 +1791,16 @@ function createCimdResolver(options) {
           }
         });
       } else {
-        cache.delete(clientId);
+        dropCache(clientId);
       }
       return client;
     } catch (error) {
       const message = error instanceof Error ? error.message : "CIMD metadata resolution failed";
-      if (cacheFailure) {
-        touch(clientId, {
-          ok: false,
-          message,
-          expiresAt: now() + (policy.negativeTtlMs ?? 1e4)
-        });
-      }
+      touch(clientId, {
+        ok: false,
+        message,
+        expiresAt: now() + (policy.negativeTtlMs ?? 1e4)
+      });
       throw error;
     }
   };
@@ -1967,6 +2052,9 @@ function mountOAuthProvider(config) {
       const result = await config.authorizeUser(req, authRequest);
       if (result instanceof Response)
         return result;
+      if (!Array.isArray(result.approvedScopes) || !result.approvedScopes.every((scope2) => typeof scope2 === "string")) {
+        throw new Error("authorizeUser must return approvedScopes as an array of strings");
+      }
       const approvedScopes = [...new Set(result.approvedScopes)];
       if (approvedScopes.some((approvedScope2) => !requestedScopes.includes(approvedScope2) || config.scopesSupported !== undefined && !supportedScopes.has(approvedScope2))) {
         throw new Error("authorizeUser approvedScopes must be a subset of requested scopes");
@@ -2070,6 +2158,63 @@ function mountOAuthProvider(config) {
   };
   return dcrEnabled ? [metadataRoute, registerRoute, authorizeRoute, tokenRoute] : [metadataRoute, authorizeRoute, tokenRoute];
 }
+// src/browser/cancellation.ts
+class RequestCancellationError extends Error {
+  cause;
+  constructor(cause) {
+    super(cause === "caller" ? "Request was aborted" : "Request timed out");
+    this.cause = cause;
+    this.name = "RequestCancellationError";
+  }
+}
+function createRequestCancellation(caller, timeoutMs) {
+  if (!caller && timeoutMs === undefined) {
+    return { signal: undefined, run: (operation) => operation() };
+  }
+  const controller = new AbortController;
+  let cause;
+  let timer;
+  const abortFromCaller = () => {
+    if (cause)
+      return;
+    cause = "caller";
+    controller.abort(caller?.reason);
+  };
+  if (caller?.aborted)
+    abortFromCaller();
+  else
+    caller?.addEventListener("abort", abortFromCaller, { once: true });
+  if (timeoutMs !== undefined) {
+    timer = setTimeout(() => {
+      if (cause)
+        return;
+      cause = "timeout";
+      controller.abort(new DOMException("Request timed out", "TimeoutError"));
+    }, timeoutMs);
+  }
+  return {
+    signal: controller.signal,
+    async run(operation) {
+      try {
+        if (cause === "caller")
+          throw cancellationError(cause);
+        return await operation(controller.signal);
+      } catch (error) {
+        if (cause)
+          throw cancellationError(cause);
+        throw error;
+      } finally {
+        if (timer !== undefined)
+          clearTimeout(timer);
+        caller?.removeEventListener("abort", abortFromCaller);
+      }
+    }
+  };
+}
+function cancellationError(cause) {
+  return new RequestCancellationError(cause);
+}
+
 // src/browser/client-multipart.ts
 function isFileDescriptor(value) {
   return typeof value === "object" && value !== null && !(value instanceof Blob) && "uri" in value && typeof value.uri === "string" && "name" in value && typeof value.name === "string" && "type" in value && typeof value.type === "string";
@@ -2088,6 +2233,35 @@ function appendFormFields(formData, values, skipKeys) {
     formData.append(key, typeof value === "string" ? value : JSON.stringify(value));
   }
 }
+function buildMultipartForm(descriptor, values) {
+  const formData = new FormData;
+  const fileFields = new Set(Object.keys(descriptor.files));
+  for (const [field, policy] of Object.entries(descriptor.files)) {
+    const value = values[field];
+    if (value === undefined) {
+      if (policy.required !== false)
+        throw new Error(`Missing multipart file field: ${field}`);
+      continue;
+    }
+    if (policy.multiple === true) {
+      if (!Array.isArray(value) || value.length === 0) {
+        throw new Error(`Multipart file field "${field}" must be a non-empty array`);
+      }
+      for (const file of value) {
+        if (!isMultipartFile(file)) {
+          throw new Error(`Invalid multipart file field: ${field}`);
+        }
+        appendMultipartFile(formData, field, file);
+      }
+      continue;
+    }
+    if (!isMultipartFile(value))
+      throw new Error(`Invalid multipart file field: ${field}`);
+    appendMultipartFile(formData, field, value);
+  }
+  appendFormFields(formData, values, fileFields);
+  return formData;
+}
 
 // src/browser/client-url.ts
 function isParamArray(value) {
@@ -2291,95 +2465,108 @@ function setClientMethod(target, key, method) {
 function createHttpMethod(endpoint, prefix, client, config) {
   const httpMethod = endpoint.method.toLowerCase();
   return (...args) => {
-    const firstArg = args[0] ?? {};
+    const { requestArgs: firstArg, options } = splitClientCall(endpoint, args, config);
     const plan = planClientRequest(endpoint, prefix, firstArg, config);
     if (endpoint.multipart) {
-      const file = firstArg[endpoint.multipart];
-      if (!isMultipartFile(file)) {
-        throw new Error(`Missing multipart file field: ${endpoint.multipart}`);
-      }
       if (httpMethod === "get" || httpMethod === "head" || httpMethod === "delete") {
         throw new Error(`Multipart endpoint ${endpoint.method} ${endpoint.path} must be POST / PUT / PATCH`);
       }
-      const formData = new FormData;
-      appendMultipartFile(formData, endpoint.multipart, file);
-      appendFormFields(formData, plan.remainingArgs, new Set([endpoint.multipart]));
-      return withOutput(endpoint, client[httpMethod](plan.relativeUrl, formData, withTimeout(undefined, endpoint)));
+      const formData = buildMultipartForm(endpoint.multipart, plan.remainingArgs);
+      return withOutput(endpoint, client[httpMethod](plan.relativeUrl, formData, withTimeout(options, endpoint)));
     }
     if (httpMethod === "get" || httpMethod === "head") {
-      return withOutput(endpoint, client[httpMethod](plan.relativeUrl, withTimeout(undefined, endpoint)));
+      return withOutput(endpoint, client[httpMethod](plan.relativeUrl, withTimeout(options, endpoint)));
     }
     if (httpMethod === "delete") {
-      return withOutput(endpoint, client.delete(plan.relativeUrl, withTimeout(undefined, endpoint)));
+      return withOutput(endpoint, client.delete(plan.relativeUrl, withTimeout(options, endpoint)));
     }
-    return withOutput(endpoint, client[httpMethod](plan.relativeUrl, Object.keys(plan.remainingArgs).length > 0 ? plan.remainingArgs : undefined, withTimeout(undefined, endpoint)));
+    return withOutput(endpoint, client[httpMethod](plan.relativeUrl, Object.keys(plan.remainingArgs).length > 0 ? plan.remainingArgs : undefined, withTimeout(options, endpoint)));
   };
 }
 function createFetchMethod(endpoint, prefix, config, contractConfig) {
-  return async (args) => {
-    const plan = planClientRequest(endpoint, prefix, args ?? {}, contractConfig);
+  return async (...callArgs) => {
+    const { requestArgs, options } = splitClientCall(endpoint, callArgs, contractConfig);
+    const plan = planClientRequest(endpoint, prefix, requestArgs, contractConfig);
     const url = joinClientBaseUrl(config.baseUrl, plan.relativeUrl);
     const headers = {
       Accept: "application/json",
       ...typeof config.headers === "function" ? config.headers() : config.headers
     };
-    const signal = endpoint.timeout !== undefined ? AbortSignal.timeout(endpoint.timeout) : undefined;
-    const hasBody = endpoint.method !== "GET" && endpoint.method !== "HEAD" && endpoint.method !== "DELETE" && !endpoint.multipart && endpoint.input && args;
+    const cancellation = createRequestCancellation(options?.signal, endpoint.timeout ?? config.timeout ?? 30000);
+    const hasBody = endpoint.method !== "GET" && endpoint.method !== "HEAD" && endpoint.method !== "DELETE" && !endpoint.multipart && endpoint.input && Object.keys(plan.remainingArgs).length > 0;
     if (hasBody)
       headers["Content-Type"] = "application/json";
-    if (endpoint.multipart && args) {
-      const file = args[endpoint.multipart];
-      if (!isMultipartFile(file)) {
-        throw new Error(`Missing multipart file field: ${endpoint.multipart}`);
-      }
-      const formData = new FormData;
-      appendMultipartFile(formData, endpoint.multipart, file);
-      appendFormFields(formData, plan.remainingArgs, new Set([endpoint.multipart]));
-      const res2 = await fetch(url, {
-        method: endpoint.method,
-        headers,
-        credentials: config.credentials,
-        body: formData,
-        signal
-      });
-      if (!res2.ok) {
-        await throwForErrorResponse(res2, config, null);
-      }
-      if (endpoint.rawResponse)
-        return res2;
-      if (!endpoint.output) {
-        const text = await res2.text();
-        if (text.length > 0) {
-          throw new Error("Server returned data for an endpoint with no output contract");
+    try {
+      return await cancellation.run(async (signal) => {
+        const body = endpoint.multipart ? buildMultipartForm(endpoint.multipart, plan.remainingArgs) : hasBody ? JSON.stringify(plan.remainingArgs) : undefined;
+        const res = await fetch(url, {
+          method: endpoint.method,
+          headers,
+          credentials: config.credentials,
+          signal,
+          ...body !== undefined && { body }
+        });
+        if (!res.ok) {
+          await throwForErrorResponse(res, config, { error: res.statusText });
         }
-        return;
-      }
-      return endpoint.output.parse(await res2.json());
-    }
-    const res = await fetch(url, {
-      method: endpoint.method,
-      headers,
-      credentials: config.credentials,
-      signal,
-      ...hasBody && {
-        body: JSON.stringify(plan.remainingArgs)
-      }
-    });
-    if (!res.ok) {
-      await throwForErrorResponse(res, config, { error: res.statusText });
-    }
-    if (endpoint.rawResponse)
-      return res;
-    if (!endpoint.output) {
-      const text = await res.text();
-      if (text.length > 0) {
-        throw new Error("Server returned data for an endpoint with no output contract");
+        if (endpoint.rawResponse)
+          return res;
+        if (!endpoint.output) {
+          const text = await res.text();
+          if (text.length > 0) {
+            throw new Error("Server returned data for an endpoint with no output contract");
+          }
+          return;
+        }
+        return endpoint.output.parse(await res.json());
+      });
+    } catch (error) {
+      if (error instanceof RequestCancellationError) {
+        throw new ApiError(error.cause === "caller" ? "REQUEST_ABORTED" : "REQUEST_TIMEOUT", 0, undefined, error.message);
       }
-      return;
+      if (ApiError.is(error))
+        throw error;
+      const message = error instanceof Error ? error.message : undefined;
+      throw new ApiError("UNKNOWN_ERROR", 0, message ? { message } : undefined, message);
     }
-    return endpoint.output.parse(await res.json());
   };
 }
+function endpointHasArguments(endpoint) {
+  return Boolean(endpoint.params || endpoint.input || endpoint.multipart);
+}
+function splitClientCall(endpoint, args, contractConfig) {
+  const hasScopedArguments = (contractConfig?.stripPrefixKeys?.length ?? 0) > 0;
+  if (!endpointHasArguments(endpoint) && !hasScopedArguments) {
+    return {
+      requestArgs: {},
+      options: readClientRequestOptions(args[0])
+    };
+  }
+  const requestArgs = args[0];
+  if (requestArgs !== undefined && !isRecord(requestArgs)) {
+    throw new TypeError("Endpoint arguments must be an object");
+  }
+  return {
+    requestArgs: requestArgs ?? {},
+    options: readClientRequestOptions(args[1])
+  };
+}
+function readClientRequestOptions(value) {
+  if (value === undefined)
+    return;
+  if (!isRecord(value))
+    throw new TypeError("Client request options must be an object");
+  const signal = value.signal;
+  if (signal === undefined)
+    return {};
+  if (!isAbortSignal(signal)) {
+    throw new TypeError("Client request signal must be an AbortSignal");
+  }
+  return { signal };
+}
+function isAbortSignal(value) {
+  return typeof value === "object" && value !== null && "aborted" in value && typeof value.aborted === "boolean" && "addEventListener" in value && typeof value.addEventListener === "function" && "removeEventListener" in value && typeof value.removeEventListener === "function";
+}
 async function throwForErrorResponse(res, config, fallbackBody) {
   const body = await res.json().catch(() => fallbackBody);
   config.onError?.(res.status, body);
@@ -2453,7 +2640,7 @@ function implementRemote(contract, http, options) {
 }
 // src/tools/tool-logger.ts
 function createToolLogger(config = {}) {
-  const log = config.log ?? ((line) => console.info(line));
+  const log = config.log ?? ((line) => console.error(line));
   return {
     afterToolCall: ({ toolName, result, durationMs, context, endpoint }) => {
       const record = {
@@ -2551,10 +2738,11 @@ function summarizeTransports(surface) {
   };
 }
 // src/tools/view-file.ts
-import { readFile, realpath, stat } from "node:fs/promises";
-import { extname as extname2, resolve } from "node:path";
+import { readFile, stat } from "node:fs/promises";
+import { extname as extname2, resolve as resolve2 } from "node:path";
 import { z as z7 } from "zod";
 var MAX_INLINE_BYTES = 20 * 1024 * 1024;
+var MAX_VIEW_FILES = 20;
 var EXT_MIME = {
   ".png": "image/png",
   ".jpg": "image/jpeg",
@@ -2569,22 +2757,28 @@ var EXT_MIME = {
   ".webm": "video/webm",
   ".mov": "video/quicktime"
 };
-async function fetchSource(pathOrUrl, options) {
+async function fetchSource(pathOrUrl, options, maxBytes) {
   const extMime = EXT_MIME[extname2(pathOrUrl).toLowerCase()];
   if (pathOrUrl.startsWith("http://") || pathOrUrl.startsWith("https://")) {
     const url = new URL(pathOrUrl);
-    const res = await fetchGuarded(url, options.allowPrivateHosts ?? false);
+    const res = await fetchGuarded(url, options.allowPrivateHosts ?? false, {
+      timeoutMs: options.timeoutMs
+    });
     if (!res.ok)
       throw new Error(`HTTP ${res.status}`);
     const headerMime = (res.headers.get("content-type") ?? "").split(";")[0]?.trim() ?? "";
     const mimeType = headerMime || extMime || "application/octet-stream";
+    if (mimeType.startsWith("video/")) {
+      await res.body?.cancel();
+      return { video: true, mimeType, bytesRead: 0 };
+    }
     const declared = Number(res.headers.get("content-length") ?? 0);
-    if (declared > MAX_INLINE_BYTES) {
+    if (declared > maxBytes) {
       await res.body?.cancel();
-      return { tooLarge: true, mimeType };
+      return { tooLarge: true, mimeType, bytesRead: 0 };
     }
-    const buffer = await readCapped(res, MAX_INLINE_BYTES);
-    return buffer ? { buffer, mimeType } : { tooLarge: true, mimeType };
+    const buffer2 = await readCapped(res, maxBytes);
+    return buffer2 ? { buffer: buffer2, mimeType, bytesRead: buffer2.length } : { tooLarge: true, mimeType, bytesRead: maxBytes };
   }
   if (!options.baseDir) {
     throw new Error("local file paths are disabled — set baseDir to allow them");
@@ -2592,76 +2786,109 @@ async function fetchSource(pathOrUrl, options) {
   if (!extMime) {
     throw new Error("refusing to read a non-media file");
   }
-  const root = resolve(options.baseDir);
-  const target = resolve(root, pathOrUrl);
+  const root = resolve2(options.baseDir);
+  const target = resolve2(root, pathOrUrl);
   if (!isWithinDir(root, target)) {
     throw new Error("path escapes the allowed directory");
   }
-  const realTarget = await realpath(target).catch(() => null);
-  if (realTarget === null)
-    throw new Error("file not found");
-  const realRoot = await realpath(root).catch(() => root);
-  if (!isWithinDir(realRoot, realTarget)) {
+  const realTarget = await realPathWithinDir(root, target);
+  if (realTarget === null) {
     throw new Error("path escapes the allowed directory");
   }
   const info = await stat(realTarget).catch(() => null);
   if (!info?.isFile())
     throw new Error("file not found");
-  if (info.size > MAX_INLINE_BYTES)
-    return { tooLarge: true, mimeType: extMime };
-  return { buffer: await readFile(realTarget), mimeType: extMime };
+  if (info.size > maxBytes)
+    return { tooLarge: true, mimeType: extMime, bytesRead: 0 };
+  const buffer = await readFile(realTarget);
+  return { buffer, mimeType: extMime, bytesRead: buffer.length };
 }
-async function resolveMedia(pathOrUrl, options = {}) {
+async function resolveMediaWithinBudget(pathOrUrl, options, maxBytes) {
+  if (maxBytes <= 0) {
+    return {
+      content: [
+        { type: "text", text: `[media] total inline budget exhausted — ${pathOrUrl}` }
+      ],
+      bytes: 0
+    };
+  }
   const extMime = EXT_MIME[extname2(pathOrUrl).toLowerCase()];
   if (extMime?.startsWith("video/")) {
-    return [{ type: "text", text: `[video] ${extMime} — ${pathOrUrl}` }];
+    return {
+      content: [{ type: "text", text: `[video] ${extMime} — ${pathOrUrl}` }],
+      bytes: 0
+    };
+  }
+  const result = await fetchSource(pathOrUrl, options, maxBytes);
+  if ("video" in result) {
+    return {
+      content: [{ type: "text", text: `[video] ${result.mimeType} — ${pathOrUrl}` }],
+      bytes: result.bytesRead
+    };
   }
-  const result = await fetchSource(pathOrUrl, options);
   if ("tooLarge" in result) {
-    return [{ type: "text", text: `[${result.mimeType}] too large to inline — ${pathOrUrl}` }];
+    return {
+      content: [
+        { type: "text", text: `[${result.mimeType}] too large to inline — ${pathOrUrl}` }
+      ],
+      bytes: result.bytesRead
+    };
   }
   const { buffer, mimeType } = result;
   const sizeKb = (buffer.length / 1024).toFixed(0);
-  if (mimeType.startsWith("video/")) {
-    return [{ type: "text", text: `[video] ${mimeType}, ${sizeKb}KB — ${pathOrUrl}` }];
-  }
   if (mimeType.startsWith("image/")) {
-    return [
-      {
-        type: "image",
-        data: buffer.toString("base64"),
-        mimeType,
-        annotations: { audience: ["user", "assistant"], priority: 0.9 }
-      },
-      { type: "text", text: `[image] ${mimeType}, ${sizeKb}KB` }
-    ];
+    return {
+      content: [
+        {
+          type: "image",
+          data: buffer.toString("base64"),
+          mimeType,
+          annotations: { audience: ["user", "assistant"], priority: 0.9 }
+        },
+        { type: "text", text: `[image] ${mimeType}, ${sizeKb}KB` }
+      ],
+      bytes: buffer.length
+    };
   }
   if (mimeType.startsWith("audio/")) {
-    return [
-      {
-        type: "audio",
-        data: buffer.toString("base64"),
-        mimeType,
-        annotations: { audience: ["user", "assistant"], priority: 0.9 }
-      },
-      { type: "text", text: `[audio] ${mimeType}, ${sizeKb}KB` }
-    ];
+    return {
+      content: [
+        {
+          type: "audio",
+          data: buffer.toString("base64"),
+          mimeType,
+          annotations: { audience: ["user", "assistant"], priority: 0.9 }
+        },
+        { type: "text", text: `[audio] ${mimeType}, ${sizeKb}KB` }
+      ],
+      bytes: buffer.length
+    };
   }
-  return [{ type: "text", text: `[${mimeType}] ${sizeKb}KB — ${pathOrUrl}` }];
+  return {
+    content: [{ type: "text", text: `[${mimeType}] ${sizeKb}KB — ${pathOrUrl}` }],
+    bytes: buffer.length
+  };
+}
+async function resolveMedia(pathOrUrl, options = {}) {
+  return (await resolveMediaWithinBudget(pathOrUrl, options, MAX_INLINE_BYTES)).content;
 }
+var ViewFileInputSchema = z7.object({
+  paths: z7.union([z7.string(), z7.array(z7.string()).max(MAX_VIEW_FILES)]).describe("Media URL(s) or file path(s) to view")
+});
 function mountViewFile(server, options = {}) {
   server.registerTool("view_file", {
     description: "View media (image, audio, video) by URL or local path — returns it as content you can SEE / HEAR. Pass several paths to view multiple files at once. Use it on a generation `output` url to inspect the result.",
-    inputSchema: {
-      paths: z7.union([z7.string(), z7.array(z7.string())]).describe("Media URL(s) or file path(s) to view")
-    },
+    inputSchema: ViewFileInputSchema.shape,
     annotations: { title: "View Media", readOnlyHint: true, idempotentHint: true }
   }, async (args) => {
     const list = Array.isArray(args.paths) ? args.paths : [args.paths];
     const content = [];
+    let remainingBytes = MAX_INLINE_BYTES;
     for (const pathOrUrl of list) {
       try {
-        content.push(...await resolveMedia(pathOrUrl, options));
+        const resolved = await resolveMediaWithinBudget(pathOrUrl, options, remainingBytes);
+        remainingBytes -= resolved.bytes;
+        content.push(...resolved.content);
       } catch (err) {
         content.push({
           type: "text",