stitchkit 0.1.0 → 0.3.0

package/dist/tools.js

@@ -1,11 +1,19 @@
 import {
   createClient
-} from "./index-5sxnvwb1.js";
+} from "./index-4kz3aqpx.js";
+import {
+  isWithinDir
+} from "./index-q6ja2qwq.js";
 import {
   formatZodError,
-  normalizeError
-} from "./index-gfzn1n4n.js";
-import"./index-7wfkbvss.js";
+  normalizeError,
+  validateHandlerOutput
+} from "./index-0t460v7k.js";
+import"./index-kckky6zw.js";
+import {
+  isUnsafeKey,
+  safeJsonParse
+} from "./index-kzfs85xp.js";
 import {
   isRecord
 } from "./index-809wc1tt.js";
@@ -13,22 +21,100 @@ import {
 // src/tools/agent.ts
 import { tool, zodSchema } from "ai";
 
-// src/tools/mount.ts
+// 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
-async function executeToolMethod(method, toolName, rawArgs, context, hooks) {
+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) {
-    await hooks.beforeToolCall(toolName, rawArgs, context);
+    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(rawArgs);
+    const result = method.paramsSchema.safeParse(paramArgs);
     if (!result.success) {
       return finish({
         ok: false,
@@ -40,7 +126,7 @@ async function executeToolMethod(method, toolName, rawArgs, context, hooks) {
   }
   let input;
   if (method.inputSchema) {
-    const result = method.inputSchema.safeParse(rawArgs);
+    const result = method.inputSchema.safeParse(inputArgs);
     if (!result.success) {
       return finish({
         ok: false,
@@ -51,120 +137,55 @@ async function executeToolMethod(method, toolName, rawArgs, context, hooks) {
     input = result.data;
   }
   try {
-    const ctx = { params, input, ...context };
-    const data = await method.handler(ctx);
-    const output = data === undefined || data === null ? { status: "ok" } : data;
-    return finish({ ok: true, data: output });
-  } catch (err) {
-    const appErr = normalizeError(err);
-    return finish({
-      ok: false,
-      code: appErr.code,
-      details: appErr.details ?? { message: appErr.message },
-      ...appErr.hint && { hint: appErr.hint }
-    });
-  }
-}
-
-// 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/schema.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;
-}
-var jsonCoerce = (val) => {
-  if (typeof val === "string") {
-    try {
-      return JSON.parse(val);
-    } catch {
-      return val;
+    const ctx = { ...context, params, input, source: context.source };
+    if (lifecycle?.beforeHandle) {
+      await lifecycle.beforeHandle(ctx, method);
     }
-  }
-  return val;
-};
-function withJsonCoercion(schema) {
-  const shape = schema.shape;
-  const coerced = {};
-  for (const [key, field] of Object.entries(shape)) {
-    if (!needsJsonCoercion(field)) {
-      coerced[key] = field;
-      continue;
+    let data = await method.handler(ctx);
+    if (lifecycle?.afterHandle) {
+      const transformed = await lifecycle.afterHandle(ctx, data, method);
+      if (transformed !== undefined)
+        data = transformed;
     }
-    let inner = field;
-    const wrappers = [];
-    while (inner instanceof z.ZodOptional || inner instanceof z.ZodNullable) {
-      if (inner instanceof z.ZodOptional) {
-        wrappers.push("optional");
-        inner = inner.unwrap();
-      } else {
-        wrappers.push("nullable");
-        inner = inner.unwrap();
+    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;
     }
-    let result = z.preprocess(jsonCoerce, inner);
-    for (const wrapper of wrappers.reverse()) {
-      result = wrapper === "optional" ? z.optional(result) : z.nullable(result);
-    }
-    coerced[key] = result;
+    const output = (data === undefined || data === null) && !method.outputSchema ? { status: "ok" } : data;
+    return finish({ ok: true, data: output });
+  } catch (err) {
+    return finish(toolResultFromError(err));
   }
-  return z.object(coerced);
 }
+
+// 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 z.ZodObject)) {
-      throw new Error(`flattenDiscriminatedUnion: option for discriminator '${discriminator}' is not a ZodObject`);
+    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 z.ZodLiteral)) {
+    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 (got ${typeof literalValue})`);
+      throw new Error("flattenDiscriminatedUnion: discriminator literal must be a string");
     }
     literalValues.push(literalValue);
     for (const [key, field] of Object.entries(opt.shape)) {
@@ -174,7 +195,7 @@ function flattenDiscriminatedUnion(union) {
       variants.push(literalValue);
       fieldToVariants.set(key, variants);
       if (!(key in fieldSchemas)) {
-        fieldSchemas[key] = field instanceof z.ZodOptional ? field : z.optional(field);
+        fieldSchemas[key] = field instanceof z3.ZodOptional ? field : z3.optional(field);
       }
     }
   }
@@ -183,32 +204,65 @@ function flattenDiscriminatedUnion(union) {
     throw new Error("flattenDiscriminatedUnion: union has no options");
   }
   const shape = {
-    [discriminator]: z.enum([firstLiteral, ...restLiterals])
+    [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 instanceof z.ZodType ? field.describe(hint) : field;
+    shape[key] = field.describe(hint);
   }
-  return z.object(shape);
+  return z3.object(shape);
 }
-function mergeSchemas(paramsSchema, inputSchema) {
-  const paramsShape = paramsSchema instanceof z.ZodObject ? paramsSchema.shape : {};
-  const inputShape = inputSchema instanceof z.ZodObject ? inputSchema.shape : inputSchema instanceof z.ZodDiscriminatedUnion ? flattenDiscriminatedUnion(inputSchema).shape : {};
-  const paramsKeys = Object.keys(paramsShape);
-  const inputKeys = new Set(Object.keys(inputShape));
-  const conflicts = paramsKeys.filter((k) => inputKeys.has(k));
-  if (conflicts.length > 0) {
-    throw new Error(`Schema merge conflict: ${conflicts.join(", ")} appear in both params and input`);
-  }
-  const merged = { ...paramsShape, ...inputShape };
-  if (Object.keys(merged).length === 0)
-    return z.object({});
-  return withJsonCoercion(z.object(merged));
+
+// 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 collectTools(service, transport, extend) {
+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))
@@ -216,9 +270,12 @@ function collectTools(service, transport, extend) {
     if (method.multipart)
       continue;
     const name = method.toolName ?? toToolName(service.name, methodName);
-    const baseSchema = mergeSchemas(method.paramsSchema, method.inputSchema);
+    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 ? z2.object({ ...extend?.schema, ...baseSchema.shape }) : baseSchema;
+    const schema = shouldExtend && extend ? applyExtend(baseSchema, extend.schema) : baseSchema;
     tools.push({ method, name, schema, shouldExtend });
   }
   return tools;
@@ -231,111 +288,230 @@ function createToolRunner(config) {
       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, { source: config.source, ...config.context, ...extraContext }, config.hooks);
+    return executeToolMethod(tool.method, tool.name, cleanArgs, { ...config.context, ...extraContext, source: config.source }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true);
   };
 }
-function formatToolError(result) {
+function formatToolError(result, toolName, errorHint) {
   const err = { error: result.code };
   if (result.details)
     err.details = result.details;
+  const hints = [];
   if (result.hint)
-    err._hint = 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 formatAgentResult(result) {
-  return result.ok ? result.data : formatToolError(result);
-}
-function mountAgent(service, config = {}) {
+function mountAgent(services, config = {}) {
+  const serviceList = Array.isArray(services) ? services : [services];
   const tools = {};
   const runTool = createToolRunner({
     source: "agent",
     extend: config.extend,
     context: config.context,
-    hooks: config.hooks
+    hooks: config.hooks,
+    lifecycle: config.lifecycle,
+    errorHint: config.errorHint,
+    coerceJsonArgs: config.coerceJsonArgs
   });
-  for (const mountable of collectTools(service, "AGENT", config.extend)) {
-    tools[mountable.name] = tool({
-      description: mountable.method.desc,
-      inputSchema: zodSchema(mountable.schema),
-      execute: async (rawArgs) => {
-        try {
-          const result = await runTool(mountable, rawArgs);
-          return formatAgentResult(result);
-        } catch (err) {
-          const appErr = normalizeError(err);
-          return { error: appErr.code, details: appErr.details };
-        }
+  for (const service of serviceList) {
+    for (const mountable of collectTools(service, "AGENT", {
+      extend: config.extend,
+      flattenUnionInput: config.flattenUnionInput
+    })) {
+      if (mountable.name in tools) {
+        throw new Error(`Duplicate agent tool name "${mountable.name}" across mounted services`);
       }
-    });
+      tools[mountable.name] = tool({
+        description: mountable.method.desc,
+        inputSchema: zodSchema(mountable.schema),
+        execute: async (rawArgs) => {
+          const args = isRecord(rawArgs) ? rawArgs : {};
+          try {
+            const result = await runTool(mountable, args);
+            if (result.ok)
+              return result.data;
+            return formatToolError(result, mountable.name, config.errorHint);
+          } catch (err) {
+            return formatToolError(toolResultFromError(err), mountable.name, config.errorHint);
+          }
+        }
+      });
+    }
   }
   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) => {
+    let inputSchema;
+    try {
+      inputSchema = toJsonSchema(t.schema, "input");
+    } catch {
+      inputSchema = {};
+    }
+    return { name: t.name, description: t.method.desc, inputSchema };
+  });
+}
 // src/tools/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z as z3 } from "zod";
+import { z as z6 } from "zod";
 function textBlock(text) {
   return [{ type: "text", text }];
 }
-function formatMcpResult(result, hasOutputSchema) {
+function formatMcpResult(result, mode, toolName, errorHint) {
   if (result.ok) {
     const content = textBlock(JSON.stringify(result.data, null, 2));
-    if (hasOutputSchema && isRecord(result.data)) {
+    if (mode === "wrapped") {
+      return { content, structuredContent: { result: result.data } };
+    }
+    if (mode === "direct" && isRecord(result.data)) {
       return { content, structuredContent: result.data };
     }
     return { content };
   }
   return {
-    content: textBlock(JSON.stringify(formatToolError(result), null, 2)),
+    content: textBlock(JSON.stringify(formatToolError(result, toolName, errorHint), null, 2)),
     isError: true
   };
 }
+function probeSchema(schema, io) {
+  try {
+    toJsonSchema(schema, io);
+    return null;
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+}
+function resolveOutputSchema(outputSchema) {
+  if (!outputSchema)
+    return null;
+  if (outputSchema instanceof z6.ZodObject) {
+    return { schema: outputSchema, mode: "direct" };
+  }
+  return { schema: z6.object({ result: outputSchema }), mode: "wrapped" };
+}
+function reportIncompatible(message, policy, logger, failures) {
+  if (policy === "throw") {
+    failures.push(message);
+  } else if (policy === "warn") {
+    if (logger)
+      logger.warn(`[stitchkit] ${message}`);
+    else
+      console.warn(`[stitchkit] ${message}`);
+  }
+}
+function throwIfFailures(failures) {
+  if (failures.length > 0) {
+    throw new Error(`[stitchkit] ${failures.length} MCP tool(s) have an incompatible schema:
+ - ${failures.join(`
+ - `)}`);
+  }
+}
+function prepareMcpTool(mountable, policy, logger, failures, seen) {
+  if (seen.has(mountable.name)) {
+    throw new Error(`Duplicate MCP tool name "${mountable.name}" across mounted services`);
+  }
+  seen.add(mountable.name);
+  if (!(mountable.schema instanceof z6.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;
+  }
+  const inputError = probeSchema(mountable.schema, "input");
+  if (inputError) {
+    reportIncompatible(`MCP tool "${mountable.name}" — input schema is not JSON Schema-compatible: ${inputError}`, policy, logger, failures);
+    return null;
+  }
+  const resolved = resolveOutputSchema(mountable.method.outputSchema);
+  if (!resolved)
+    return { outputMode: "none" };
+  const outputError = probeSchema(resolved.schema, "output");
+  if (outputError) {
+    reportIncompatible(`MCP tool "${mountable.name}" — output schema is not JSON Schema-compatible: ${outputError}`, policy, logger, failures);
+    return { outputMode: "none" };
+  }
+  return { outputSchema: resolved.schema, outputMode: resolved.mode };
+}
+function validateMcpSchemas(services, onIncompatibleSchema = "throw", logger) {
+  const seen = new Set;
+  const failures = [];
+  for (const service of services) {
+    for (const mountable of collectTools(service, "MCP", undefined)) {
+      prepareMcpTool(mountable, onIncompatibleSchema, logger, failures, seen);
+    }
+  }
+  throwIfFailures(failures);
+}
 function mountMcp(mcpServer, services, config = {}) {
   const serviceList = Array.isArray(services) ? services : [services];
+  const policy = config.onIncompatibleSchema ?? "throw";
   const runTool = createToolRunner({
     source: "mcp",
     extend: config.extend,
     context: config.context,
-    hooks: config.hooks
+    hooks: config.hooks,
+    lifecycle: config.lifecycle,
+    errorHint: config.errorHint,
+    coerceJsonArgs: config.coerceJsonArgs
   });
+  const seen = new Set;
+  const failures = [];
   for (const service of serviceList) {
-    for (const mountable of collectTools(service, "MCP", config.extend)) {
-      try {
-        z3.toJSONSchema(mountable.schema);
-      } catch (err) {
-        console.error(`[stitchkit] SKIPPING MCP tool "${mountable.name}" — schema not JSON Schema-compatible: ${err instanceof Error ? err.message : err}`);
+    for (const mountable of collectTools(service, "MCP", {
+      extend: config.extend,
+      flattenUnionInput: config.flattenUnionInput
+    })) {
+      const prepared = prepareMcpTool(mountable, policy, config.logger, failures, seen);
+      if (!prepared)
         continue;
-      }
-      let outputSchema;
-      if (mountable.method.outputSchema instanceof z3.ZodObject) {
-        try {
-          z3.toJSONSchema(mountable.method.outputSchema);
-          outputSchema = mountable.method.outputSchema;
-        } catch {
-          outputSchema = undefined;
-        }
-      }
-      const toolConfig = { description: mountable.method.desc, inputSchema: mountable.schema.shape };
-      if (outputSchema)
-        toolConfig.outputSchema = outputSchema.shape;
+      const toolConfig = { description: mountable.method.desc, inputSchema: mountable.schema };
+      if (prepared.outputSchema)
+        toolConfig.outputSchema = prepared.outputSchema;
       mcpServer.registerTool(mountable.name, toolConfig, async (rawArgs) => {
+        const args = isRecord(rawArgs) ? rawArgs : {};
         try {
-          const result = await runTool(mountable, rawArgs);
-          return formatMcpResult(result, outputSchema !== undefined);
+          const result = await runTool(mountable, args);
+          return formatMcpResult(result, prepared.outputMode, mountable.name, config.errorHint);
         } catch (err) {
-          const appErr = normalizeError(err);
-          return formatMcpResult({ ok: false, code: appErr.code, details: appErr.details }, false);
+          return formatMcpResult(toolResultFromError(err), "none", mountable.name, config.errorHint);
         }
       });
     }
   }
+  throwIfFailures(failures);
 }
 function buildMcpServer(config, auth) {
   const server = new McpServer(config.serverInfo, config.instructions ? { instructions: config.instructions } : undefined);
   const services = typeof config.services === "function" ? config.services(auth) : config.services;
   const context = config.context?.(auth);
-  mountMcp(server, services, { context, hooks: config.hooks });
+  mountMcp(server, services, {
+    context,
+    hooks: config.hooks,
+    lifecycle: config.lifecycle,
+    onIncompatibleSchema: config.onIncompatibleSchema,
+    logger: config.logger,
+    coerceJsonArgs: config.coerceJsonArgs,
+    flattenUnionInput: config.flattenUnionInput,
+    errorHint: config.errorHint
+  });
   config.nativeTools?.(server);
   return server;
 }
@@ -346,6 +522,9 @@ import {
 } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 var EVENT_TTL_MS = 10 * 60 * 1000;
 var SESSION_TTL_MS = 30 * 60 * 1000;
+var SWEEP_INTERVAL_MS = 60 * 1000;
+var MAX_EVENTS = 1e4;
+var MAX_SESSIONS = 1000;
 
 class InMemoryEventStore {
   events = new Map;
@@ -353,6 +532,11 @@ class InMemoryEventStore {
   async storeEvent(streamId, message) {
     const eventId = String(++this.counter);
     this.events.set(eventId, { streamId, message, timestamp: Date.now() });
+    if (this.events.size > MAX_EVENTS) {
+      const oldest = this.events.keys().next().value;
+      if (oldest !== undefined)
+        this.events.delete(oldest);
+    }
     return eventId;
   }
   async getStreamIdForEventId(eventId) {
@@ -382,20 +566,26 @@ function jsonRpcError(code, message, status) {
   return Response.json({ jsonrpc: "2.0", error: { code, message }, id: null }, { status });
 }
 function createMcpHandler(config) {
+  if (Array.isArray(config.services)) {
+    validateMcpSchemas(config.services, config.onIncompatibleSchema, config.logger);
+  }
   const eventStore = new InMemoryEventStore;
   const sessions = new Map;
+  const closeTransport = (transport) => {
+    transport.close().catch((err) => {
+      console.error("[stitchkit] MCP transport close failed:", err);
+    });
+  };
   setInterval(() => {
     eventStore.cleanup();
     const cutoff = Date.now() - SESSION_TTL_MS;
     for (const [id, session] of sessions) {
       if (session.lastSeen < cutoff) {
         sessions.delete(id);
-        session.transport.close().catch(() => {
-          return;
-        });
+        closeTransport(session.transport);
       }
     }
-  }, EVENT_TTL_MS).unref();
+  }, SWEEP_INTERVAL_MS).unref();
   return async (req) => {
     const auth = await config.auth(req);
     if (!auth) {
@@ -413,6 +603,22 @@ function createMcpHandler(config) {
       }
       return existing.transport.handleRequest(req);
     }
+    if (sessions.size >= MAX_SESSIONS) {
+      let oldestId;
+      let oldestSeen = Number.POSITIVE_INFINITY;
+      for (const [id, session] of sessions) {
+        if (session.lastSeen < oldestSeen) {
+          oldestSeen = session.lastSeen;
+          oldestId = id;
+        }
+      }
+      if (oldestId !== undefined) {
+        const evicted = sessions.get(oldestId);
+        sessions.delete(oldestId);
+        if (evicted)
+          closeTransport(evicted.transport);
+      }
+    }
     const newSessionId = randomUUID();
     const transport = new WebStandardStreamableHTTPServerTransport({
       sessionIdGenerator: () => newSessionId,
@@ -480,8 +686,10 @@ function implementRemote(contract, http, options) {
 import { lookup } from "node:dns/promises";
 import { readFile, stat } from "node:fs/promises";
 import { isIP } from "node:net";
-import { extname, resolve, sep } from "node:path";
-import { z as z4 } from "zod";
+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;
 var MAX_INLINE_BYTES = 20 * 1024 * 1024;
 var EXT_MIME = {
   ".png": "image/png",
@@ -524,6 +732,9 @@ async function assertPublicUrl(url) {
       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");
   }
@@ -534,6 +745,22 @@ async function assertPublicUrl(url) {
     }
   }
 }
+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)
@@ -561,9 +788,7 @@ async function fetchSource(pathOrUrl, options) {
   const extMime = EXT_MIME[extname(pathOrUrl).toLowerCase()];
   if (pathOrUrl.startsWith("http://") || pathOrUrl.startsWith("https://")) {
     const url = new URL(pathOrUrl);
-    if (!options.allowPrivateHosts)
-      await assertPublicUrl(url);
-    const res = await fetch(url);
+    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() ?? "";
@@ -581,7 +806,7 @@ async function fetchSource(pathOrUrl, options) {
   }
   const root = resolve(options.baseDir);
   const target = resolve(root, pathOrUrl);
-  if (target !== root && !target.startsWith(root + sep)) {
+  if (!isWithinDir(root, target)) {
     throw new Error("path escapes the allowed directory");
   }
   const info = await stat(target).catch(() => null);
@@ -624,7 +849,7 @@ 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: z4.union([z4.string(), z4.array(z4.string())]).describe("Media URL(s) or file path(s) to view")
+      paths: z7.union([z7.string(), z7.array(z7.string())]).describe("Media URL(s) or file path(s) to view")
     }
   }, async (args) => {
     const list = Array.isArray(args.paths) ? args.paths : [args.paths];
@@ -643,12 +868,17 @@ function mountViewFile(server, options = {}) {
   });
 }
 export {
+  validateMcpSchemas,
   resolveMedia,
   mountViewFile,
   mountMcp,
   mountAgent,
   implementRemote,
+  flattenDiscriminatedUnion,
   createStdioMcpServer,
   createMcpHandler,
+  collectTools,
+  coerceJsonArgs,
+  buildToolManifest,
   buildMcpServer
 };