stitchkit 0.3.0 → 0.4.0

package/dist/tools.js

@@ -1,314 +1,42 @@
 import {
+  ApiError,
   createClient
-} from "./index-4kz3aqpx.js";
+} from "./index-78q1qm7v.js";
 import {
-  isWithinDir
-} from "./index-q6ja2qwq.js";
+  coerceJsonArgs,
+  collectTools,
+  createCli,
+  createToolRunner,
+  fetchGuarded,
+  flattenDiscriminatedUnion,
+  formatToolError,
+  pollUntil,
+  readCapped,
+  toolResultFromError
+} from "./index-0ma1eqv4.js";
 import {
-  formatZodError,
-  normalizeError,
-  validateHandlerOutput
-} from "./index-0t460v7k.js";
-import"./index-kckky6zw.js";
+  signJwt,
+  verifyPkce
+} from "./index-1cf8jkhf.js";
+import"./index-48ffdxgk.js";
+import {
+  toJsonSchema
+} from "./index-0ed3bx43.js";
+import {
+  isWithinDir
+} from "./index-x3fcszf8.js";
+import"./index-vhdvv00d.js";
 import {
-  isUnsafeKey,
-  safeJsonParse
-} from "./index-kzfs85xp.js";
+  AppError
+} from "./index-afzt3nmx.js";
+import"./index-kzfs85xp.js";
 import {
   isRecord
 } from "./index-809wc1tt.js";
+import"./index-37x76zdn.js";
 
 // src/tools/agent.ts
 import { tool, zodSchema } from "ai";
-
-// src/tools/coerce.ts
-import { z } from "zod";
-function needsJsonCoercion(field) {
-  if (field instanceof z.ZodArray || field instanceof z.ZodObject)
-    return true;
-  if (field instanceof z.ZodOptional || field instanceof z.ZodNullable || field instanceof z.ZodDefault) {
-    return needsJsonCoercion(field.unwrap());
-  }
-  return false;
-}
-function coerceJsonArgs(args, schema) {
-  if (!(schema instanceof z.ZodObject))
-    return args;
-  const shape = schema.shape;
-  const out = {};
-  for (const [key, value] of Object.entries(args)) {
-    const field = shape[key];
-    if (field && needsJsonCoercion(field) && typeof value === "string") {
-      try {
-        out[key] = safeJsonParse(value);
-        continue;
-      } catch {}
-    }
-    out[key] = value;
-  }
-  return out;
-}
-
-// src/tools/schema.ts
-import { z as z2 } from "zod";
-function objectShapeKeys(schema) {
-  return schema instanceof z2.ZodObject ? Object.keys(schema.shape) : [];
-}
-function mergeSchemas(paramsSchema, inputSchema) {
-  if (paramsSchema && !(paramsSchema instanceof z2.ZodObject)) {
-    throw new Error("Tool params schema must be a z.object()");
-  }
-  const paramsObject = paramsSchema instanceof z2.ZodObject ? paramsSchema : undefined;
-  if (!inputSchema) {
-    return paramsObject ?? z2.object({});
-  }
-  if (inputSchema instanceof z2.ZodObject) {
-    if (paramsObject) {
-      const conflicts = Object.keys(paramsObject.shape).filter((key) => (key in inputSchema.shape));
-      if (conflicts.length > 0) {
-        throw new Error(`Schema merge conflict: ${conflicts.join(", ")} appear in both params and input`);
-      }
-    }
-    return z2.object({ ...paramsObject?.shape ?? {}, ...inputSchema.shape });
-  }
-  return paramsObject ? z2.intersection(paramsObject, inputSchema) : inputSchema;
-}
-
-// src/tools/execute.ts
-function toolResultFromError(err) {
-  const appErr = normalizeError(err);
-  return {
-    ok: false,
-    code: appErr.code,
-    details: appErr.details ?? { message: appErr.message },
-    ...appErr.hint && { hint: appErr.hint }
-  };
-}
-async function executeToolMethod(method, toolName, rawArgs, context, hooks, lifecycle, coerceJson = false) {
-  const startedAt = Date.now();
-  const finish = async (result) => {
-    await hooks?.afterToolCall?.(toolName, rawArgs, result, Date.now() - startedAt, context);
-    return result;
-  };
-  if (hooks?.beforeToolCall) {
-    try {
-      await hooks.beforeToolCall(toolName, rawArgs, context);
-    } catch (err) {
-      return finish(toolResultFromError(err));
-    }
-  }
-  const paramKeys = new Set(objectShapeKeys(method.paramsSchema));
-  let paramArgs = {};
-  let inputArgs = {};
-  for (const [key, value] of Object.entries(rawArgs)) {
-    if (isUnsafeKey(key))
-      continue;
-    if (paramKeys.has(key))
-      paramArgs[key] = value;
-    else
-      inputArgs[key] = value;
-  }
-  if (coerceJson) {
-    paramArgs = coerceJsonArgs(paramArgs, method.paramsSchema);
-    inputArgs = coerceJsonArgs(inputArgs, method.inputSchema);
-  }
-  let params;
-  if (method.paramsSchema) {
-    const result = method.paramsSchema.safeParse(paramArgs);
-    if (!result.success) {
-      return finish({
-        ok: false,
-        code: "VALIDATION_ERROR",
-        details: { message: `Invalid params: ${formatZodError(result.error)}` }
-      });
-    }
-    params = result.data;
-  }
-  let input;
-  if (method.inputSchema) {
-    const result = method.inputSchema.safeParse(inputArgs);
-    if (!result.success) {
-      return finish({
-        ok: false,
-        code: "VALIDATION_ERROR",
-        details: { message: `Invalid input: ${formatZodError(result.error)}` }
-      });
-    }
-    input = result.data;
-  }
-  try {
-    const ctx = { ...context, params, input, source: context.source };
-    if (lifecycle?.beforeHandle) {
-      await lifecycle.beforeHandle(ctx, method);
-    }
-    let data = await method.handler(ctx);
-    if (lifecycle?.afterHandle) {
-      const transformed = await lifecycle.afterHandle(ctx, data, method);
-      if (transformed !== undefined)
-        data = transformed;
-    }
-    if (method.outputSchema) {
-      const checked = validateHandlerOutput(method.outputSchema, data);
-      if (!checked.ok) {
-        return finish({
-          ok: false,
-          code: "INTERNAL_SERVER_ERROR",
-          details: { message: checked.message }
-        });
-      }
-      data = checked.data;
-    }
-    const output = (data === undefined || data === null) && !method.outputSchema ? { status: "ok" } : data;
-    return finish({ ok: true, data: output });
-  } catch (err) {
-    return finish(toolResultFromError(err));
-  }
-}
-
-// src/tools/mount.ts
-import { z as z4 } from "zod";
-
-// src/tools/flatten.ts
-import { z as z3 } from "zod";
-function flattenDiscriminatedUnion(union) {
-  const discriminator = union.def.discriminator;
-  const literalValues = [];
-  const fieldToVariants = new Map;
-  const fieldSchemas = {};
-  for (const opt of union.def.options) {
-    if (!(opt instanceof z3.ZodObject)) {
-      throw new Error(`flattenDiscriminatedUnion: variant for discriminator '${discriminator}' is not a ZodObject`);
-    }
-    const discField = opt.shape[discriminator];
-    if (!(discField instanceof z3.ZodLiteral)) {
-      throw new Error(`flattenDiscriminatedUnion: discriminator field '${discriminator}' must be z.literal()`);
-    }
-    const [literalValue] = discField.def.values;
-    if (typeof literalValue !== "string") {
-      throw new Error("flattenDiscriminatedUnion: discriminator literal must be a string");
-    }
-    literalValues.push(literalValue);
-    for (const [key, field] of Object.entries(opt.shape)) {
-      if (key === discriminator)
-        continue;
-      const variants = fieldToVariants.get(key) ?? [];
-      variants.push(literalValue);
-      fieldToVariants.set(key, variants);
-      if (!(key in fieldSchemas)) {
-        fieldSchemas[key] = field instanceof z3.ZodOptional ? field : z3.optional(field);
-      }
-    }
-  }
-  const [firstLiteral, ...restLiterals] = literalValues;
-  if (!firstLiteral) {
-    throw new Error("flattenDiscriminatedUnion: union has no options");
-  }
-  const shape = {
-    [discriminator]: z3.enum([firstLiteral, ...restLiterals])
-  };
-  for (const [key, field] of Object.entries(fieldSchemas)) {
-    const variants = fieldToVariants.get(key) ?? [];
-    const hint = `Required if ${discriminator} = ${variants.join(" | ")}`;
-    shape[key] = field.describe(hint);
-  }
-  return z3.object(shape);
-}
-
-// src/tools/names.ts
-var SINGULAR_EXCEPTIONS = new Set([
-  "analytics",
-  "status",
-  "stats",
-  "settings",
-  "media",
-  "progress",
-  "news"
-]);
-function singularize(name) {
-  if (SINGULAR_EXCEPTIONS.has(name))
-    return name;
-  if (name.endsWith("ies"))
-    return `${name.slice(0, -3)}y`;
-  if (name.endsWith("s") && !name.endsWith("ss"))
-    return name.slice(0, -1);
-  return name;
-}
-function toToolName(serviceName, methodName) {
-  const normalized = serviceName.replace(/-/g, "_");
-  const singular = singularize(normalized);
-  if (methodName === "list")
-    return `list_${normalized}`;
-  if (methodName === "get")
-    return `get_${singular}`;
-  if (methodName === "create")
-    return `create_${singular}`;
-  if (methodName === "update")
-    return `update_${singular}`;
-  if (methodName === "delete")
-    return `delete_${singular}`;
-  const snake = methodName.replace(/([A-Z])/g, "_$1").toLowerCase();
-  return `${snake}_${singular}`.replace(/^_/, "");
-}
-
-// src/tools/mount.ts
-function applyExtend(base, extra) {
-  if (base instanceof z4.ZodObject) {
-    const conflicts = Object.keys(extra).filter((key) => (key in base.shape));
-    if (conflicts.length > 0) {
-      throw new Error(`Tool extend conflict: ${conflicts.join(", ")} already declared by the contract`);
-    }
-    return z4.object({ ...extra, ...base.shape });
-  }
-  return z4.intersection(z4.object(extra), base);
-}
-function collectTools(service, transport, config = {}) {
-  const { extend, flattenUnionInput = false } = config;
-  const tools = [];
-  for (const [methodName, method] of Object.entries(service.methods)) {
-    if (method.expose && !method.expose.includes(transport))
-      continue;
-    if (method.multipart)
-      continue;
-    const name = method.toolName ?? toToolName(service.name, methodName);
-    let baseSchema = mergeSchemas(method.paramsSchema, method.inputSchema);
-    if (flattenUnionInput && baseSchema instanceof z4.ZodDiscriminatedUnion) {
-      baseSchema = flattenDiscriminatedUnion(baseSchema);
-    }
-    const shouldExtend = !!extend && (!extend.filter || extend.filter(service, method));
-    const schema = shouldExtend && extend ? applyExtend(baseSchema, extend.schema) : baseSchema;
-    tools.push({ method, name, schema, shouldExtend });
-  }
-  return tools;
-}
-function createToolRunner(config) {
-  const extendKeys = config.extend ? new Set(Object.keys(config.extend.schema)) : null;
-  return async (tool, rawArgs) => {
-    let extraContext = {};
-    if (tool.shouldExtend && config.extend) {
-      extraContext = await config.extend.resolve(rawArgs);
-    }
-    const cleanArgs = extendKeys ? Object.fromEntries(Object.entries(rawArgs).filter(([key]) => !extendKeys.has(key))) : rawArgs;
-    return executeToolMethod(tool.method, tool.name, cleanArgs, { ...config.context, ...extraContext, source: config.source }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true);
-  };
-}
-function formatToolError(result, toolName, errorHint) {
-  const err = { error: result.code };
-  if (result.details)
-    err.details = result.details;
-  const hints = [];
-  if (result.hint)
-    hints.push(result.hint);
-  if (errorHint && toolName) {
-    const global = errorHint(toolName, result.code);
-    if (global)
-      hints.push(global);
-  }
-  if (hints.length > 0)
-    err._hint = hints.join(" ");
-  return err;
-}
-
-// src/tools/agent.ts
 function mountAgent(services, config = {}) {
   const serviceList = Array.isArray(services) ? services : [services];
   const tools = {};
@@ -348,17 +76,6 @@ function mountAgent(services, config = {}) {
   }
   return tools;
 }
-// src/tools/json-schema.ts
-import { z as z5 } from "zod";
-function toJsonSchema(schema, io) {
-  return z5.toJSONSchema(schema, {
-    io,
-    target: "draft-2020-12",
-    unrepresentable: "throw",
-    cycles: "ref"
-  });
-}
-
 // src/tools/manifest.ts
 function buildToolManifest(tools) {
   return tools.map((t) => {
@@ -373,7 +90,31 @@ function buildToolManifest(tools) {
 }
 // src/tools/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z as z6 } from "zod";
+import { z } from "zod";
+
+// src/tools/mcp-app.ts
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+var RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+var EXT_APPS_BUNDLE_PLACEHOLDER = "/*__EXT_APPS_BUNDLE__*/";
+var require2 = createRequire(import.meta.url);
+function inlineMcpAppBundle(html) {
+  if (!html.includes(EXT_APPS_BUNDLE_PLACEHOLDER))
+    return html;
+  let bundlePath;
+  try {
+    bundlePath = require2.resolve("@modelcontextprotocol/ext-apps/app-with-deps");
+  } catch {
+    throw new Error("[stitchkit] inlineMcpAppBundle: '@modelcontextprotocol/ext-apps' is not installed. " + "Add it as a dependency to serve MCP App widgets.");
+  }
+  const bundle = readFileSync(bundlePath, "utf8").replace(/export\{([^}]+)\};?\s*$/, (_match, body) => `globalThis.ExtApps={${body.split(",").map((pair) => {
+    const [local, exported] = pair.split(" as ").map((s) => s.trim());
+    return `${exported ?? local}:${local}`;
+  }).join(",")}};`);
+  return html.replace(EXT_APPS_BUNDLE_PLACEHOLDER, () => bundle);
+}
+
+// src/tools/mcp.ts
 function textBlock(text) {
   return [{ type: "text", text }];
 }
@@ -404,10 +145,10 @@ function probeSchema(schema, io) {
 function resolveOutputSchema(outputSchema) {
   if (!outputSchema)
     return null;
-  if (outputSchema instanceof z6.ZodObject) {
+  if (outputSchema instanceof z.ZodObject) {
     return { schema: outputSchema, mode: "direct" };
   }
-  return { schema: z6.object({ result: outputSchema }), mode: "wrapped" };
+  return { schema: z.object({ result: outputSchema }), mode: "wrapped" };
 }
 function reportIncompatible(message, policy, logger, failures) {
   if (policy === "throw") {
@@ -431,7 +172,7 @@ function prepareMcpTool(mountable, policy, logger, failures, seen) {
     throw new Error(`Duplicate MCP tool name "${mountable.name}" across mounted services`);
   }
   seen.add(mountable.name);
-  if (!(mountable.schema instanceof z6.ZodObject)) {
+  if (!(mountable.schema instanceof z.ZodObject)) {
     reportIncompatible(`MCP tool "${mountable.name}" — input must be an object schema; a union, discriminated union or scalar cannot be an MCP tool input (flatten it in the contract, or drop MCP from \`expose\`)`, policy, logger, failures);
     return null;
   }
@@ -485,6 +226,15 @@ function mountMcp(mcpServer, services, config = {}) {
       const toolConfig = { description: mountable.method.desc, inputSchema: mountable.schema };
       if (prepared.outputSchema)
         toolConfig.outputSchema = prepared.outputSchema;
+      if (mountable.method.annotations) {
+        toolConfig.annotations = mountable.method.annotations;
+      }
+      if (mountable.method.ui) {
+        toolConfig._meta = {
+          ui: mountable.method.ui,
+          "ui/resourceUri": mountable.method.ui.resourceUri
+        };
+      }
       mcpServer.registerTool(mountable.name, toolConfig, async (rawArgs) => {
         const args = isRecord(rawArgs) ? rawArgs : {};
         try {
@@ -513,13 +263,70 @@ function buildMcpServer(config, auth) {
     errorHint: config.errorHint
   });
   config.nativeTools?.(server);
+  for (const resource of config.resources ?? []) {
+    mountMcpResource(server, resource);
+  }
   return server;
 }
+function mountMcpResource(server, resource) {
+  server.registerResource(resource.name, resource.uri, { mimeType: resource.mimeType ?? RESOURCE_MIME_TYPE }, async () => ({
+    contents: [
+      {
+        uri: resource.uri,
+        mimeType: resource.mimeType ?? RESOURCE_MIME_TYPE,
+        text: await resource.read(),
+        ...resource.ui && { _meta: { ui: resource.ui } }
+      }
+    ]
+  }));
+}
 // src/tools/mcp-handler.ts
 import { randomUUID } from "node:crypto";
 import {
   WebStandardStreamableHTTPServerTransport
 } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+
+// src/tools/oauth-metadata.ts
+var PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource";
+function metadataPath(resource) {
+  const { pathname } = new URL(resource);
+  return pathname === "/" ? PROTECTED_RESOURCE_PATH : `${PROTECTED_RESOURCE_PATH}${pathname}`;
+}
+function protectedResourceMetadataUrl(resource) {
+  return `${new URL(resource).origin}${metadataPath(resource)}`;
+}
+function wwwAuthenticateHeader(resource) {
+  return `Bearer resource_metadata="${protectedResourceMetadataUrl(resource)}"`;
+}
+var PUBLIC_CORS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, OPTIONS",
+  "Access-Control-Allow-Headers": "Authorization, Content-Type"
+};
+function oauthProtectedResourceRoute(config) {
+  const body = JSON.stringify({
+    resource: config.resource,
+    authorization_servers: config.authorizationServers,
+    ...config.scopesSupported && { scopes_supported: config.scopesSupported },
+    bearer_methods_supported: ["header"]
+  });
+  return {
+    method: "ALL",
+    path: metadataPath(config.resource),
+    handler: (req) => {
+      if (req.method === "OPTIONS")
+        return new Response(null, { status: 204, headers: PUBLIC_CORS });
+      if (req.method !== "GET")
+        return new Response("Method Not Allowed", { status: 405 });
+      return new Response(body, {
+        status: 200,
+        headers: { "Content-Type": "application/json", ...PUBLIC_CORS }
+      });
+    }
+  };
+}
+
+// src/tools/mcp-handler.ts
 var EVENT_TTL_MS = 10 * 60 * 1000;
 var SESSION_TTL_MS = 30 * 60 * 1000;
 var SWEEP_INTERVAL_MS = 60 * 1000;
@@ -562,13 +369,31 @@ class InMemoryEventStore {
     }
   }
 }
-function jsonRpcError(code, message, status) {
-  return Response.json({ jsonrpc: "2.0", error: { code, message }, id: null }, { status });
+function jsonRpcError(code, message, status, headers) {
+  return Response.json({ jsonrpc: "2.0", error: { code, message }, id: null }, { status, headers });
 }
 function createMcpHandler(config) {
   if (Array.isArray(config.services)) {
     validateMcpSchemas(config.services, config.onIncompatibleSchema, config.logger);
   }
+  const unauthorized = () => {
+    const headers = config.protectedResource ? { "WWW-Authenticate": wwwAuthenticateHeader(config.protectedResource.resource) } : undefined;
+    return jsonRpcError(-32001, "Authorization required", 401, headers);
+  };
+  if (config.stateless) {
+    return async (req) => {
+      const auth = await config.auth(req);
+      if (!auth)
+        return unauthorized();
+      const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true
+      });
+      const server = buildMcpServer(config, auth);
+      await server.connect(transport);
+      return transport.handleRequest(req);
+    };
+  }
   const eventStore = new InMemoryEventStore;
   const sessions = new Map;
   const closeTransport = (transport) => {
@@ -588,9 +413,8 @@ function createMcpHandler(config) {
   }, SWEEP_INTERVAL_MS).unref();
   return async (req) => {
     const auth = await config.auth(req);
-    if (!auth) {
-      return jsonRpcError(-32001, "Authorization required", 401);
-    }
+    if (!auth)
+      return unauthorized();
     const sessionId = req.headers.get("mcp-session-id");
     if (sessionId) {
       const existing = sessions.get(sessionId);
@@ -641,6 +465,376 @@ async function createStdioMcpServer(config) {
   await server.connect(new StdioServerTransport);
   return server;
 }
+// src/tools/mount-download.ts
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+
+// src/tools/native-result.ts
+function textResult(text, isError = false) {
+  const content = [{ type: "text", text }];
+  return isError ? { content, isError: true } : { content };
+}
+
+// src/tools/mount-download.ts
+var DEFAULT_MAX_BYTES = 100 * 1024 * 1024;
+var MIME_EXT = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/webp": ".webp",
+  "image/gif": ".gif",
+  "video/mp4": ".mp4",
+  "video/webm": ".webm",
+  "audio/mpeg": ".mp3",
+  "audio/wav": ".wav",
+  "audio/ogg": ".ogg"
+};
+function extensionFor(url, mime) {
+  if (MIME_EXT[mime])
+    return MIME_EXT[mime];
+  try {
+    const ext = extname(new URL(url).pathname).toLowerCase();
+    if (ext)
+      return ext;
+  } catch {}
+  return ".bin";
+}
+function baseNameFor(url) {
+  try {
+    const path = new URL(url).pathname;
+    return (basename(path, extname(path)) || "download").slice(0, 60);
+  } catch {
+    return "download";
+  }
+}
+function mountDownload(server, config) {
+  server.registerTool(config.name ?? "download", { description: config.description, inputSchema: config.inputSchema }, async (rawArgs) => {
+    const args = isRecord(rawArgs) ? rawArgs : {};
+    try {
+      const url = await config.resolveUrl(args);
+      if (!url)
+        return textResult("Nothing to download.", true);
+      const res = await fetchGuarded(new URL(url), config.allowPrivateHosts ?? false);
+      if (!res.ok)
+        return textResult(`Download failed: HTTP ${res.status}`, true);
+      const mimeType = (res.headers.get("content-type") ?? "").split(";")[0]?.trim() || "application/octet-stream";
+      const max = config.maxBytes ?? DEFAULT_MAX_BYTES;
+      const declared = Number(res.headers.get("content-length") ?? 0);
+      if (declared > max) {
+        await res.body?.cancel();
+        return textResult(`Download failed: file exceeds the ${max}-byte cap`, true);
+      }
+      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;
+      await mkdir(dir, { recursive: true });
+      const filePath = join(dir, `${baseNameFor(url)}${extensionFor(url, mimeType)}`);
+      await writeFile(filePath, buffer);
+      return textResult(JSON.stringify({ path: filePath, size: buffer.length, mimeType }, null, 2));
+    } catch (err) {
+      return textResult(`Download failed: ${err instanceof Error ? err.message : String(err)}`, true);
+    }
+  });
+}
+// src/tools/mount-upload.ts
+import { z as z2 } from "zod";
+function mountUpload(server, config) {
+  server.registerTool(config.name ?? "upload", {
+    description: config.description,
+    inputSchema: { path: z2.string().describe("Path to a local file on this machine") }
+  }, async (rawArgs) => {
+    const args = isRecord(rawArgs) ? rawArgs : {};
+    const path = typeof args.path === "string" ? args.path : "";
+    if (!path)
+      return textResult("Provide `path`.", true);
+    try {
+      const uploaded = await config.upload(path);
+      return textResult(JSON.stringify(uploaded ?? null, null, 2));
+    } catch (err) {
+      return textResult(`Upload failed: ${err instanceof Error ? err.message : String(err)}`, true);
+    }
+  });
+}
+// src/tools/mount-wait.ts
+function mountWait(server, config) {
+  server.registerTool(config.name ?? "wait", { description: config.description, inputSchema: config.inputSchema }, async (rawArgs) => {
+    const args = isRecord(rawArgs) ? rawArgs : {};
+    try {
+      const { state, timedOut } = await pollUntil({
+        poll: () => config.poll(args),
+        done: config.done,
+        backoff: config.backoff,
+        timeoutSec: config.timeoutFromArgs?.(args) ?? config.defaultTimeout
+      });
+      const rendered = config.render ? config.render(state, timedOut) : { text: JSON.stringify(state, null, 2), isError: timedOut };
+      return textResult(rendered.text, rendered.isError);
+    } catch (err) {
+      return textResult(`Wait failed: ${err instanceof Error ? err.message : String(err)}`, true);
+    }
+  });
+}
+// src/tools/oauth-provider.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+var PUBLIC_CORS2 = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+  "Access-Control-Allow-Headers": "Authorization, Content-Type"
+};
+var AS_METADATA_PATH = "/.well-known/oauth-authorization-server";
+var AUTH_CODE_TTL_MS = 60000;
+function json(body, status = 200, extraHeaders) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json", ...PUBLIC_CORS2, ...extraHeaders }
+  });
+}
+function oauthError(error, description, status = 400) {
+  return json({ error, error_description: description }, status);
+}
+function isHttpUri(value) {
+  try {
+    const url = new URL(value);
+    if (url.protocol === "https:")
+      return true;
+    if (url.protocol !== "http:")
+      return false;
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    return host === "127.0.0.1" || host === "::1" || host === "localhost";
+  } catch {
+    return false;
+  }
+}
+function redirectWith(uri, params) {
+  const url = new URL(uri);
+  for (const [key, value] of Object.entries(params))
+    url.searchParams.set(key, value);
+  return new Response(null, { status: 302, headers: { Location: url.toString() } });
+}
+async function readForm(req) {
+  const contentType = req.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    const body = await req.json().catch(() => null);
+    const params = new URLSearchParams;
+    if (isRecord(body)) {
+      for (const [key, value] of Object.entries(body)) {
+        if (typeof value === "string")
+          params.set(key, value);
+      }
+    }
+    return params;
+  }
+  return new URLSearchParams(await req.text());
+}
+function mountOAuthProvider(config) {
+  const base = config.basePath ?? "/oauth";
+  const ttl = config.accessTokenTtlSec ?? 3600;
+  const registerPath = `${base}/register`;
+  const authorizePath = `${base}/authorize`;
+  const tokenPath = `${base}/token`;
+  const metadataRoute = {
+    method: "ALL",
+    path: AS_METADATA_PATH,
+    handler: (req) => {
+      if (req.method === "OPTIONS")
+        return new Response(null, { status: 204, headers: PUBLIC_CORS2 });
+      return json({
+        issuer: config.issuer,
+        authorization_endpoint: `${config.issuer}${authorizePath}`,
+        token_endpoint: `${config.issuer}${tokenPath}`,
+        registration_endpoint: `${config.issuer}${registerPath}`,
+        response_types_supported: ["code"],
+        grant_types_supported: config.refreshTokens ? ["authorization_code", "refresh_token"] : ["authorization_code"],
+        code_challenge_methods_supported: ["S256"],
+        token_endpoint_auth_methods_supported: ["none"],
+        ...config.scopesSupported && { scopes_supported: config.scopesSupported }
+      });
+    }
+  };
+  const registerRoute = {
+    method: "ALL",
+    path: registerPath,
+    handler: async (req) => {
+      if (req.method === "OPTIONS")
+        return new Response(null, { status: 204, headers: PUBLIC_CORS2 });
+      if (req.method !== "POST")
+        return oauthError("invalid_request", "POST required", 405);
+      const meta = await req.json().catch(() => null);
+      if (!isRecord(meta)) {
+        return oauthError("invalid_client_metadata", "Body must be a JSON object");
+      }
+      const redirectUris = meta.redirect_uris;
+      if (!Array.isArray(redirectUris) || redirectUris.length === 0 || !redirectUris.every((u) => typeof u === "string" && isHttpUri(u))) {
+        return oauthError("invalid_redirect_uri", "redirect_uris must be a non-empty array of absolute https URLs (http is allowed only on a loopback host)");
+      }
+      const client = await config.clients.register({
+        redirectUris,
+        clientName: typeof meta.client_name === "string" ? meta.client_name : undefined,
+        tokenEndpointAuthMethod: typeof meta.token_endpoint_auth_method === "string" ? meta.token_endpoint_auth_method : undefined
+      });
+      return json({
+        client_id: client.clientId,
+        redirect_uris: client.redirectUris,
+        token_endpoint_auth_method: "none",
+        grant_types: config.refreshTokens ? ["authorization_code", "refresh_token"] : ["authorization_code"],
+        response_types: ["code"],
+        ...client.clientName && { client_name: client.clientName }
+      }, 201);
+    }
+  };
+  const authorizeRoute = {
+    method: "ALL",
+    path: authorizePath,
+    handler: async (req) => {
+      if (req.method === "OPTIONS")
+        return new Response(null, { status: 204, headers: PUBLIC_CORS2 });
+      const url = new URL(req.url);
+      const p = url.searchParams;
+      const clientId = p.get("client_id");
+      const redirectUri = p.get("redirect_uri");
+      const responseType = p.get("response_type");
+      const codeChallenge = p.get("code_challenge");
+      const codeChallengeMethod = p.get("code_challenge_method") ?? "S256";
+      const resource = p.get("resource");
+      const scope = p.get("scope") ?? undefined;
+      const state = p.get("state") ?? undefined;
+      if (!clientId || !redirectUri) {
+        return oauthError("invalid_request", "client_id and redirect_uri are required");
+      }
+      const client = await config.clients.get(clientId);
+      if (!client)
+        return oauthError("invalid_client", "Unknown client_id", 401);
+      if (!client.redirectUris.includes(redirectUri)) {
+        return oauthError("invalid_request", "redirect_uri does not match a registered URI");
+      }
+      if (responseType !== "code") {
+        return redirectWith(redirectUri, {
+          error: "unsupported_response_type",
+          ...state && { state }
+        });
+      }
+      if (!codeChallenge || codeChallengeMethod !== "S256") {
+        return redirectWith(redirectUri, {
+          error: "invalid_request",
+          error_description: "PKCE S256 code_challenge is required",
+          ...state && { state }
+        });
+      }
+      if (!resource) {
+        return redirectWith(redirectUri, {
+          error: "invalid_target",
+          error_description: "resource parameter is required",
+          ...state && { state }
+        });
+      }
+      if (resource !== config.resource) {
+        return redirectWith(redirectUri, {
+          error: "invalid_target",
+          error_description: "resource is not served by this authorization server",
+          ...state && { state }
+        });
+      }
+      const authRequest = { clientId, redirectUri, scope, resource, state };
+      const result = await config.authorizeUser(req, authRequest);
+      if (result instanceof Response)
+        return result;
+      const code = randomUUID2();
+      await config.codes.save(code, {
+        clientId,
+        redirectUri,
+        codeChallenge,
+        codeChallengeMethod: "S256",
+        resource,
+        scope,
+        userId: result.userId,
+        expiresAt: Date.now() + AUTH_CODE_TTL_MS
+      });
+      return redirectWith(redirectUri, { code, ...state && { state } });
+    }
+  };
+  const issueAccessToken = (userId, audience, clientId, scope) => signJwt({ scope, client_id: clientId }, config.signingSecret, {
+    issuer: config.issuer,
+    audience,
+    subject: userId,
+    expiresInSec: ttl
+  });
+  const tokenRoute = {
+    method: "ALL",
+    path: tokenPath,
+    handler: async (req) => {
+      if (req.method === "OPTIONS")
+        return new Response(null, { status: 204, headers: PUBLIC_CORS2 });
+      if (req.method !== "POST")
+        return oauthError("invalid_request", "POST required", 405);
+      const form = await readForm(req);
+      const grantType = form.get("grant_type");
+      if (grantType === "authorization_code") {
+        const code = form.get("code");
+        const verifier = form.get("code_verifier");
+        const redirectUri = form.get("redirect_uri");
+        const clientId = form.get("client_id");
+        if (!code || !verifier || !redirectUri || !clientId) {
+          return oauthError("invalid_request", "code, code_verifier, redirect_uri, client_id required");
+        }
+        const data = await config.codes.take(code);
+        if (!data)
+          return oauthError("invalid_grant", "Unknown or used authorization code");
+        if (data.expiresAt < Date.now())
+          return oauthError("invalid_grant", "Authorization code expired");
+        if (data.clientId !== clientId)
+          return oauthError("invalid_grant", "client_id mismatch");
+        if (data.redirectUri !== redirectUri)
+          return oauthError("invalid_grant", "redirect_uri mismatch");
+        if (!await verifyPkce(verifier, data.codeChallenge)) {
+          return oauthError("invalid_grant", "PKCE verification failed");
+        }
+        const accessToken = await issueAccessToken(data.userId, data.resource, data.clientId, data.scope);
+        let refreshToken;
+        if (config.refreshTokens) {
+          refreshToken = randomUUID2();
+          await config.refreshTokens.save(refreshToken, {
+            clientId: data.clientId,
+            resource: data.resource,
+            scope: data.scope,
+            userId: data.userId
+          });
+        }
+        return json({
+          access_token: accessToken,
+          token_type: "Bearer",
+          expires_in: ttl,
+          ...data.scope && { scope: data.scope },
+          ...refreshToken && { refresh_token: refreshToken }
+        });
+      }
+      if (grantType === "refresh_token") {
+        if (!config.refreshTokens) {
+          return oauthError("unsupported_grant_type", "refresh_token grant is not enabled");
+        }
+        const token = form.get("refresh_token");
+        const clientId = form.get("client_id");
+        if (!token || !clientId)
+          return oauthError("invalid_request", "refresh_token and client_id required");
+        const data = await config.refreshTokens.take(token);
+        if (!data)
+          return oauthError("invalid_grant", "Unknown or used refresh token");
+        if (data.clientId !== clientId)
+          return oauthError("invalid_grant", "client_id mismatch");
+        const accessToken = await issueAccessToken(data.userId, data.resource, data.clientId, data.scope);
+        const newRefresh = randomUUID2();
+        await config.refreshTokens.save(newRefresh, data);
+        return json({
+          access_token: accessToken,
+          token_type: "Bearer",
+          expires_in: ttl,
+          ...data.scope && { scope: data.scope },
+          refresh_token: newRefresh
+        });
+      }
+      return oauthError("unsupported_grant_type", `Unsupported grant_type: ${grantType ?? "none"}`);
+    }
+  };
+  return [metadataRoute, registerRoute, authorizeRoute, tokenRoute];
+}
 // src/tools/remote.ts
 function toArgs(ctx) {
   const { params, input } = ctx;
@@ -660,6 +854,8 @@ function implementRemote(contract, http, options) {
       desc: endpoint.desc,
       toolName: "toolName" in endpoint ? endpoint.toolName : undefined,
       expose: endpoint.expose,
+      ui: "ui" in endpoint ? endpoint.ui : undefined,
+      annotations: "annotations" in endpoint ? endpoint.annotations : undefined,
       scope: endpoint.scope ?? groupScope,
       paramsSchema: endpoint.params,
       inputSchema: endpoint.input,
@@ -671,7 +867,15 @@ function implementRemote(contract, http, options) {
           throw new Error(`implementRemote: endpoint "${key}" is not exposed over HTTP`);
         }
         const args = toArgs(ctx);
-        return call(options?.transformArgs ? await options.transformArgs(key, args) : args);
+        const finalArgs = options?.transformArgs ? await options.transformArgs(key, args) : args;
+        try {
+          return await call(finalArgs);
+        } catch (err) {
+          if (ApiError.is(err)) {
+            throw new AppError(err.code, err.message, err.status, isRecord(err.details) ? err.details : undefined, err.hint);
+          }
+          throw err;
+        }
       }
     };
   }
@@ -682,14 +886,21 @@ function implementRemote(contract, http, options) {
     methods
   };
 }
+// src/tools/toolkit.ts
+function createToolkit() {
+  return {
+    mountMcp: (server, services, config) => mountMcp(server, services, config),
+    mountAgent: (services, config) => mountAgent(services, config),
+    buildMcpServer: (config, auth) => buildMcpServer(config, auth),
+    createMcpHandler: (config) => createMcpHandler(config),
+    createStdioMcpServer: (config) => createStdioMcpServer(config),
+    createCli: (config) => createCli(config)
+  };
+}
 // src/tools/view-file.ts
-import { lookup } from "node:dns/promises";
-import { readFile, stat } from "node:fs/promises";
-import { isIP } from "node:net";
-import { extname, resolve } from "node:path";
-import { z as z7 } from "zod";
-var NUMERIC_HOST = /^(0x[0-9a-f]+|[0-9.]+)$/i;
-var MAX_REDIRECTS = 5;
+import { readFile, realpath, stat } from "node:fs/promises";
+import { extname as extname2, resolve } from "node:path";
+import { z as z3 } from "zod";
 var MAX_INLINE_BYTES = 20 * 1024 * 1024;
 var EXT_MIME = {
   ".png": "image/png",
@@ -705,120 +916,50 @@ var EXT_MIME = {
   ".webm": "video/webm",
   ".mov": "video/quicktime"
 };
-function isPrivateIp(ip) {
-  const family = isIP(ip);
-  if (family === 4) {
-    const [a, b] = ip.split(".").map(Number);
-    if (a === undefined || b === undefined)
-      return true;
-    return a === 0 || a === 10 || a === 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a === 100 && b >= 64 && b <= 127;
-  }
-  if (family === 6) {
-    const lower = ip.toLowerCase();
-    if (lower === "::1" || lower === "::")
-      return true;
-    if (lower.startsWith("fe8") || lower.startsWith("fe9") || lower.startsWith("fea") || lower.startsWith("feb") || lower.startsWith("fc") || lower.startsWith("fd")) {
-      return true;
-    }
-    const mapped = lower.match(/::ffff:(\d+\.\d+\.\d+\.\d+)$/);
-    return mapped?.[1] ? isPrivateIp(mapped[1]) : false;
-  }
-  return false;
-}
-async function assertPublicUrl(url) {
-  const host = url.hostname.replace(/^\[|\]$/g, "");
-  if (isIP(host)) {
-    if (isPrivateIp(host))
-      throw new Error("refusing to fetch a private address");
-    return;
-  }
-  if (NUMERIC_HOST.test(host)) {
-    throw new Error("refusing to fetch a non-canonical numeric host");
-  }
-  if (host === "localhost" || host.endsWith(".local") || host.endsWith(".internal")) {
-    throw new Error("refusing to fetch an internal host");
-  }
-  const records = await lookup(host, { all: true });
-  for (const record of records) {
-    if (isPrivateIp(record.address)) {
-      throw new Error("refusing to fetch a host that resolves to a private address");
-    }
-  }
-}
-async function fetchGuarded(start, allowPrivate) {
-  let url = start;
-  for (let hop = 0;hop <= MAX_REDIRECTS; hop++) {
-    if (!allowPrivate)
-      await assertPublicUrl(url);
-    const res = await fetch(url, { redirect: "manual" });
-    if (res.status < 300 || res.status >= 400)
-      return res;
-    const location = res.headers.get("location");
-    if (!location)
-      return res;
-    await res.body?.cancel();
-    url = new URL(location, url);
-  }
-  throw new Error("too many redirects");
-}
-async function readCapped(res, max) {
-  const reader = res.body?.getReader();
-  if (!reader)
-    return Buffer.alloc(0);
-  const chunks = [];
-  let total = 0;
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done)
-        break;
-      total += value.length;
-      if (total > max) {
-        await reader.cancel();
-        return null;
-      }
-      chunks.push(value);
-    }
-  } finally {
-    reader.releaseLock();
-  }
-  return Buffer.concat(chunks);
-}
 async function fetchSource(pathOrUrl, options) {
-  const extMime = EXT_MIME[extname(pathOrUrl).toLowerCase()];
+  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);
     if (!res.ok)
       throw new Error(`HTTP ${res.status}`);
     const headerMime = (res.headers.get("content-type") ?? "").split(";")[0]?.trim() ?? "";
-    const mimeType2 = headerMime || extMime || "application/octet-stream";
+    const mimeType = headerMime || extMime || "application/octet-stream";
     const declared = Number(res.headers.get("content-length") ?? 0);
     if (declared > MAX_INLINE_BYTES) {
       await res.body?.cancel();
-      return { tooLarge: true, mimeType: mimeType2 };
+      return { tooLarge: true, mimeType };
     }
     const buffer = await readCapped(res, MAX_INLINE_BYTES);
-    return buffer ? { buffer, mimeType: mimeType2 } : { tooLarge: true, mimeType: mimeType2 };
+    return buffer ? { buffer, mimeType } : { tooLarge: true, mimeType };
   }
   if (!options.baseDir) {
     throw new Error("local file paths are disabled — set baseDir to allow them");
   }
+  if (!extMime) {
+    throw new Error("refusing to read a non-media file");
+  }
   const root = resolve(options.baseDir);
   const target = resolve(root, pathOrUrl);
   if (!isWithinDir(root, target)) {
     throw new Error("path escapes the allowed directory");
   }
-  const info = await stat(target).catch(() => null);
+  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)) {
+    throw new Error("path escapes the allowed directory");
+  }
+  const info = await stat(realTarget).catch(() => null);
   if (!info?.isFile())
     throw new Error("file not found");
-  const mimeType = extMime ?? "application/octet-stream";
   if (info.size > MAX_INLINE_BYTES)
-    return { tooLarge: true, mimeType };
-  return { buffer: await readFile(target), mimeType };
+    return { tooLarge: true, mimeType: extMime };
+  return { buffer: await readFile(realTarget), mimeType: extMime };
 }
 async function resolveMedia(pathOrUrl, options = {}) {
-  const extMime = EXT_MIME[extname(pathOrUrl).toLowerCase()];
+  const extMime = EXT_MIME[extname2(pathOrUrl).toLowerCase()];
   if (extMime?.startsWith("video/")) {
     return [{ type: "text", text: `[video] ${extMime} — ${pathOrUrl}` }];
   }
@@ -833,13 +974,23 @@ async function resolveMedia(pathOrUrl, options = {}) {
   }
   if (mimeType.startsWith("image/")) {
     return [
-      { type: "image", data: buffer.toString("base64"), mimeType },
+      {
+        type: "image",
+        data: buffer.toString("base64"),
+        mimeType,
+        annotations: { audience: ["user", "assistant"], priority: 0.9 }
+      },
       { type: "text", text: `[image] ${mimeType}, ${sizeKb}KB` }
     ];
   }
   if (mimeType.startsWith("audio/")) {
     return [
-      { type: "audio", data: buffer.toString("base64"), mimeType },
+      {
+        type: "audio",
+        data: buffer.toString("base64"),
+        mimeType,
+        annotations: { audience: ["user", "assistant"], priority: 0.9 }
+      },
       { type: "text", text: `[audio] ${mimeType}, ${sizeKb}KB` }
     ];
   }
@@ -849,8 +1000,9 @@ 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")
-    }
+      paths: z3.union([z3.string(), z3.array(z3.string())]).describe("Media URL(s) or file path(s) to view")
+    },
+    annotations: { title: "View Media", readOnlyHint: true, idempotentHint: true }
   }, async (args) => {
     const list = Array.isArray(args.paths) ? args.paths : [args.paths];
     const content = [];
@@ -868,17 +1020,31 @@ function mountViewFile(server, options = {}) {
   });
 }
 export {
+  wwwAuthenticateHeader,
   validateMcpSchemas,
   resolveMedia,
+  protectedResourceMetadataUrl,
+  oauthProtectedResourceRoute,
+  mountWait,
   mountViewFile,
+  mountUpload,
+  mountOAuthProvider,
+  mountMcpResource,
   mountMcp,
+  mountDownload,
   mountAgent,
+  inlineMcpAppBundle,
   implementRemote,
   flattenDiscriminatedUnion,
+  createToolkit,
   createStdioMcpServer,
   createMcpHandler,
+  createCli,
   collectTools,
   coerceJsonArgs,
   buildToolManifest,
-  buildMcpServer
+  buildMcpServer,
+  RESOURCE_MIME_TYPE,
+  PROTECTED_RESOURCE_PATH,
+  EXT_APPS_BUNDLE_PLACEHOLDER
 };