stitchkit 0.0.1 → 0.2.0

package/dist/tools.js

@@ -0,0 +1,837 @@
+import {
+  createClient
+} from "./index-5sxnvwb1.js";
+import {
+  isRecord
+} from "./index-809wc1tt.js";
+import {
+  formatZodError,
+  normalizeError
+} from "./index-a35v22fh.js";
+import"./index-kckky6zw.js";
+
+// src/tools/agent.ts
+import { tool, zodSchema } from "ai";
+
+// src/tools/schema.ts
+import { z } from "zod";
+function objectShapeKeys(schema) {
+  return schema instanceof z.ZodObject ? Object.keys(schema.shape) : [];
+}
+function mergeSchemas(paramsSchema, inputSchema) {
+  if (paramsSchema && !(paramsSchema instanceof z.ZodObject)) {
+    throw new Error("Tool params schema must be a z.object()");
+  }
+  const paramsObject = paramsSchema instanceof z.ZodObject ? paramsSchema : undefined;
+  if (!inputSchema) {
+    return paramsObject ?? z.object({});
+  }
+  if (inputSchema instanceof z.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 z.object({ ...paramsObject?.shape ?? {}, ...inputSchema.shape });
+  }
+  return paramsObject ? z.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) {
+  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);
+  }
+  const paramKeys = new Set(objectShapeKeys(method.paramsSchema));
+  const paramArgs = {};
+  const inputArgs = {};
+  for (const [key, value] of Object.entries(rawArgs)) {
+    if (paramKeys.has(key))
+      paramArgs[key] = value;
+    else
+      inputArgs[key] = value;
+  }
+  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 parsed = method.outputSchema.safeParse(data);
+      if (!parsed.success) {
+        return finish({
+          ok: false,
+          code: "INTERNAL_SERVER_ERROR",
+          details: {
+            message: `Handler output does not match the contract: ${formatZodError(parsed.error)}`
+          }
+        });
+      }
+      data = parsed.data;
+    }
+    const output = data === undefined || data === null ? { 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/coerce.ts
+import { z as z2 } from "zod";
+function needsJsonCoercion(field) {
+  if (field instanceof z2.ZodArray || field instanceof z2.ZodObject)
+    return true;
+  if (field instanceof z2.ZodOptional || field instanceof z2.ZodNullable || field instanceof z2.ZodDefault) {
+    return needsJsonCoercion(field.unwrap());
+  }
+  return false;
+}
+var jsonCoerce = (val) => {
+  if (typeof val !== "string")
+    return val;
+  try {
+    return JSON.parse(val);
+  } catch {
+    return val;
+  }
+};
+function withJsonCoercion(schema) {
+  const shape = schema.shape;
+  const coerced = {};
+  for (const key of Object.keys(shape)) {
+    const field = shape[key];
+    if (!field || !needsJsonCoercion(field)) {
+      if (field)
+        coerced[key] = field;
+      continue;
+    }
+    let inner = field;
+    const wrappers = [];
+    while (inner instanceof z2.ZodOptional || inner instanceof z2.ZodNullable) {
+      wrappers.push(inner instanceof z2.ZodOptional ? "optional" : "nullable");
+      inner = inner.unwrap();
+    }
+    let result = z2.preprocess(jsonCoerce, inner);
+    for (const wrapper of wrappers.reverse()) {
+      result = wrapper === "optional" ? z2.optional(result) : z2.nullable(result);
+    }
+    coerced[key] = result;
+  }
+  return z2.object(coerced);
+}
+
+// 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 instanceof z3.ZodType ? field.describe(hint) : field;
+  }
+  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, coerceJsonArgs = true, 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);
+    }
+    if (coerceJsonArgs && baseSchema instanceof z4.ZodObject) {
+      baseSchema = withJsonCoercion(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);
+  };
+}
+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 = {};
+  const runTool = createToolRunner({
+    source: "agent",
+    extend: config.extend,
+    context: config.context,
+    hooks: config.hooks,
+    lifecycle: config.lifecycle,
+    errorHint: config.errorHint
+  });
+  for (const service of serviceList) {
+    for (const mountable of collectTools(service, "AGENT", {
+      extend: config.extend,
+      coerceJsonArgs: config.coerceJsonArgs,
+      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) => ({
+    name: t.name,
+    description: t.method.desc,
+    inputSchema: toJsonSchema(t.schema, "input")
+  }));
+}
+// src/tools/mcp.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z as z6 } from "zod";
+function textBlock(text) {
+  return [{ type: "text", text }];
+}
+function formatMcpResult(result, mode, toolName, errorHint) {
+  if (result.ok) {
+    const content = textBlock(JSON.stringify(result.data, null, 2));
+    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, 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,
+    lifecycle: config.lifecycle,
+    errorHint: config.errorHint
+  });
+  const seen = new Set;
+  const failures = [];
+  for (const service of serviceList) {
+    for (const mountable of collectTools(service, "MCP", {
+      extend: config.extend,
+      coerceJsonArgs: config.coerceJsonArgs,
+      flattenUnionInput: config.flattenUnionInput
+    })) {
+      const prepared = prepareMcpTool(mountable, policy, config.logger, failures, seen);
+      if (!prepared)
+        continue;
+      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, args);
+          return formatMcpResult(result, prepared.outputMode, mountable.name, config.errorHint);
+        } catch (err) {
+          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,
+    lifecycle: config.lifecycle,
+    onIncompatibleSchema: config.onIncompatibleSchema,
+    logger: config.logger,
+    coerceJsonArgs: config.coerceJsonArgs,
+    flattenUnionInput: config.flattenUnionInput,
+    errorHint: config.errorHint
+  });
+  config.nativeTools?.(server);
+  return server;
+}
+// src/tools/mcp-handler.ts
+import { randomUUID } from "node:crypto";
+import {
+  WebStandardStreamableHTTPServerTransport
+} from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+var EVENT_TTL_MS = 10 * 60 * 1000;
+var SESSION_TTL_MS = 30 * 60 * 1000;
+
+class InMemoryEventStore {
+  events = new Map;
+  counter = 0;
+  async storeEvent(streamId, message) {
+    const eventId = String(++this.counter);
+    this.events.set(eventId, { streamId, message, timestamp: Date.now() });
+    return eventId;
+  }
+  async getStreamIdForEventId(eventId) {
+    return this.events.get(eventId)?.streamId;
+  }
+  async replayEventsAfter(lastEventId, { send }) {
+    const anchor = this.events.get(lastEventId);
+    if (!anchor)
+      return "";
+    const lastIdNum = Number(lastEventId);
+    for (const [eventId, event] of this.events) {
+      if (event.streamId === anchor.streamId && Number(eventId) > lastIdNum) {
+        await send(eventId, event.message);
+      }
+    }
+    return anchor.streamId;
+  }
+  cleanup() {
+    const cutoff = Date.now() - EVENT_TTL_MS;
+    for (const [eventId, event] of this.events) {
+      if (event.timestamp < cutoff)
+        this.events.delete(eventId);
+    }
+  }
+}
+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;
+  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;
+        });
+      }
+    }
+  }, EVENT_TTL_MS).unref();
+  return async (req) => {
+    const auth = await config.auth(req);
+    if (!auth) {
+      return jsonRpcError(-32001, "Authorization required", 401);
+    }
+    const sessionId = req.headers.get("mcp-session-id");
+    if (sessionId) {
+      const existing = sessions.get(sessionId);
+      if (!existing) {
+        return jsonRpcError(-32001, "Session not found", 404);
+      }
+      existing.lastSeen = Date.now();
+      if (req.method === "GET") {
+        existing.transport.closeStandaloneSSEStream();
+      }
+      return existing.transport.handleRequest(req);
+    }
+    const newSessionId = randomUUID();
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      sessionIdGenerator: () => newSessionId,
+      eventStore
+    });
+    const server = buildMcpServer(config, auth);
+    sessions.set(newSessionId, { transport, server, lastSeen: Date.now() });
+    transport.onclose = () => {
+      sessions.delete(newSessionId);
+    };
+    await server.connect(transport);
+    return transport.handleRequest(req);
+  };
+}
+// src/tools/mcp-stdio.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+async function createStdioMcpServer(config) {
+  const auth = await config.auth;
+  const server = buildMcpServer(config, auth);
+  await server.connect(new StdioServerTransport);
+  return server;
+}
+// src/tools/remote.ts
+function toArgs(ctx) {
+  const { params, input } = ctx;
+  return {
+    ...isRecord(params) ? params : {},
+    ...isRecord(input) ? input : {}
+  };
+}
+function implementRemote(contract, http, options) {
+  const client = createClient(contract, http);
+  const groupScope = contract.meta.scope ?? "public";
+  const methods = {};
+  for (const [key, endpoint] of Object.entries(contract.endpoints)) {
+    methods[key] = {
+      method: endpoint.method,
+      path: endpoint.path,
+      desc: endpoint.desc,
+      toolName: "toolName" in endpoint ? endpoint.toolName : undefined,
+      expose: endpoint.expose,
+      scope: endpoint.scope ?? groupScope,
+      paramsSchema: endpoint.params,
+      inputSchema: endpoint.input,
+      outputSchema: endpoint.output,
+      multipart: endpoint.multipart,
+      handler: async (ctx) => {
+        const call = client[key];
+        if (!call) {
+          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);
+      }
+    };
+  }
+  return {
+    name: contract.meta.prefix,
+    prefix: contract.meta.prefix,
+    scope: groupScope,
+    methods
+  };
+}
+// 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, sep } from "node:path";
+import { z as z7 } from "zod";
+var MAX_INLINE_BYTES = 20 * 1024 * 1024;
+var EXT_MIME = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".ogg": "audio/ogg",
+  ".m4a": "audio/mp4",
+  ".mp4": "video/mp4",
+  ".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 (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 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()];
+  if (pathOrUrl.startsWith("http://") || pathOrUrl.startsWith("https://")) {
+    const url = new URL(pathOrUrl);
+    if (!options.allowPrivateHosts)
+      await assertPublicUrl(url);
+    const res = await fetch(url);
+    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 declared = Number(res.headers.get("content-length") ?? 0);
+    if (declared > MAX_INLINE_BYTES) {
+      await res.body?.cancel();
+      return { tooLarge: true, mimeType: mimeType2 };
+    }
+    const buffer = await readCapped(res, MAX_INLINE_BYTES);
+    return buffer ? { buffer, mimeType: mimeType2 } : { tooLarge: true, mimeType: mimeType2 };
+  }
+  if (!options.baseDir) {
+    throw new Error("local file paths are disabled — set baseDir to allow them");
+  }
+  const root = resolve(options.baseDir);
+  const target = resolve(root, pathOrUrl);
+  if (target !== root && !target.startsWith(root + sep)) {
+    throw new Error("path escapes the allowed directory");
+  }
+  const info = await stat(target).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 };
+}
+async function resolveMedia(pathOrUrl, options = {}) {
+  const extMime = EXT_MIME[extname(pathOrUrl).toLowerCase()];
+  if (extMime?.startsWith("video/")) {
+    return [{ type: "text", text: `[video] ${extMime} — ${pathOrUrl}` }];
+  }
+  const result = await fetchSource(pathOrUrl, options);
+  if ("tooLarge" in result) {
+    return [{ type: "text", text: `[${result.mimeType}] too large to inline — ${pathOrUrl}` }];
+  }
+  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 },
+      { type: "text", text: `[image] ${mimeType}, ${sizeKb}KB` }
+    ];
+  }
+  if (mimeType.startsWith("audio/")) {
+    return [
+      { type: "audio", data: buffer.toString("base64"), mimeType },
+      { type: "text", text: `[audio] ${mimeType}, ${sizeKb}KB` }
+    ];
+  }
+  return [{ type: "text", text: `[${mimeType}] ${sizeKb}KB — ${pathOrUrl}` }];
+}
+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")
+    }
+  }, async (args) => {
+    const list = Array.isArray(args.paths) ? args.paths : [args.paths];
+    const content = [];
+    for (const pathOrUrl of list) {
+      try {
+        content.push(...await resolveMedia(pathOrUrl, options));
+      } catch (err) {
+        content.push({
+          type: "text",
+          text: `[${pathOrUrl}] Error: ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+    }
+    return { content };
+  });
+}
+export {
+  withJsonCoercion,
+  validateMcpSchemas,
+  resolveMedia,
+  mountViewFile,
+  mountMcp,
+  mountAgent,
+  implementRemote,
+  flattenDiscriminatedUnion,
+  createStdioMcpServer,
+  createMcpHandler,
+  collectTools,
+  buildToolManifest,
+  buildMcpServer
+};