stitchkit 0.93.0 → 0.94.1

package/dist/index-np4m8hd3.js

@@ -0,0 +1,1205 @@
+import {
+  toJsonSchema
+} from "./index-eqqvgdb3.js";
+import {
+  validateDeclaredOutput
+} from "./index-znfs20ss.js";
+import {
+  AppError
+} from "./index-2vtcmrj9.js";
+import {
+  serializeCanonicalJson
+} from "./index-k5hsfc3j.js";
+import {
+  isRecord
+} from "./index-hffjpmq9.js";
+
+// src/tools/schema/portable-formats.ts
+var PORTABLE_JSON_SCHEMA_FORMATS = new Set([
+  "date",
+  "time",
+  "date-time",
+  "duration",
+  "uri",
+  "uri-reference",
+  "uri-template",
+  "email",
+  "hostname",
+  "ipv4",
+  "ipv6",
+  "regex",
+  "uuid",
+  "json-pointer",
+  "relative-json-pointer"
+]);
+function propertyPath(prefix, property) {
+  return prefix ? `${prefix}.${property}` : property;
+}
+function keywordPath(prefix, keyword) {
+  if (prefix && keyword.startsWith("["))
+    return `${prefix}${keyword}`;
+  return prefix ? `${prefix}.${keyword}` : keyword;
+}
+function findNonPortableFormats(schema, allowFormats = []) {
+  const allowed = new Set([...PORTABLE_JSON_SCHEMA_FORMATS, ...allowFormats]);
+  const found = [];
+  const pending = [{ value: schema, path: "" }];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (!current || !isRecord(current.value))
+      continue;
+    const format = current.value.format;
+    if (typeof format === "string" && !allowed.has(format)) {
+      found.push({ path: current.path || "(root)", format });
+    }
+    const properties = current.value.properties;
+    if (isRecord(properties)) {
+      for (const [key, value] of Object.entries(properties)) {
+        pending.push({ value, path: propertyPath(current.path, key) });
+      }
+    }
+    for (const mapKey of ["$defs", "definitions", "patternProperties", "dependentSchemas"]) {
+      const entries = current.value[mapKey];
+      if (!isRecord(entries))
+        continue;
+      for (const [key, value] of Object.entries(entries)) {
+        pending.push({ value, path: keywordPath(current.path, `${mapKey}.${key}`) });
+      }
+    }
+    const directChildren = [
+      ["items", "[]"],
+      ["contains", "contains"],
+      ["additionalProperties", "*"],
+      ["unevaluatedProperties", "*"],
+      ["propertyNames", "propertyNames"],
+      ["not", "not"],
+      ["if", "if"],
+      ["then", "then"],
+      ["else", "else"]
+    ];
+    for (const [keyword, segment] of directChildren) {
+      const child = current.value[keyword];
+      if (isRecord(child)) {
+        pending.push({ value: child, path: keywordPath(current.path, segment) });
+      }
+      if (Array.isArray(child)) {
+        child.forEach((value, index) => {
+          pending.push({ value, path: keywordPath(current.path, `${segment}[${index}]`) });
+        });
+      }
+    }
+    for (const keyword of ["prefixItems", "allOf", "anyOf", "oneOf"]) {
+      const branches = current.value[keyword];
+      if (!Array.isArray(branches))
+        continue;
+      branches.forEach((value, index) => {
+        pending.push({ value, path: keywordPath(current.path, `${keyword}[${index}]`) });
+      });
+    }
+  }
+  return found.sort((left, right) => left.path.localeCompare(right.path) || left.format.localeCompare(right.format));
+}
+
+// src/tools/schema/flatten-join.ts
+var ANNOTATION_KEYS = new Set(["$schema", "default", "description", "examples", "title"]);
+var TYPE_KEYWORDS = {
+  array: [
+    "contains",
+    "items",
+    "maxContains",
+    "maxItems",
+    "minContains",
+    "minItems",
+    "prefixItems",
+    "uniqueItems"
+  ],
+  integer: ["exclusiveMaximum", "exclusiveMinimum", "maximum", "minimum", "multipleOf"],
+  number: ["exclusiveMaximum", "exclusiveMinimum", "maximum", "minimum", "multipleOf"],
+  object: [
+    "additionalProperties",
+    "dependentRequired",
+    "dependentSchemas",
+    "maxProperties",
+    "minProperties",
+    "patternProperties",
+    "properties",
+    "propertyNames",
+    "required"
+  ],
+  string: [
+    "contentEncoding",
+    "contentMediaType",
+    "format",
+    "maxLength",
+    "minLength",
+    "pattern"
+  ]
+};
+function nullableProjection(schema) {
+  if (!Array.isArray(schema.anyOf) || schema.anyOf.length !== 2)
+    return schema;
+  const branches = schema.anyOf.filter(isRecord);
+  if (branches.length !== 2)
+    return schema;
+  const nullBranch = branches.find((branch) => branch.type === "null");
+  const value = branches.find((branch) => typeof branch.type === "string" && branch.type !== "null");
+  if (!nullBranch || !value || Object.keys(nullBranch).some((key) => key !== "type")) {
+    return schema;
+  }
+  const type = value.type;
+  if (typeof type !== "string")
+    return schema;
+  const projected = { type: [type, "null"] };
+  for (const key of [...ANNOTATION_KEYS, ...TYPE_KEYWORDS[type] ?? []]) {
+    if (value[key] !== undefined)
+      projected[key] = value[key];
+    else if (schema[key] !== undefined)
+      projected[key] = schema[key];
+  }
+  if (value.const !== undefined)
+    projected.enum = [value.const, null];
+  else if (Array.isArray(value.enum))
+    projected.enum = [...value.enum, null];
+  return projected;
+}
+function withoutAnnotations(schema) {
+  const result = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (!ANNOTATION_KEYS.has(key))
+      result[key] = value;
+  }
+  return result;
+}
+function stringValues(schema) {
+  if (typeof schema.const === "string")
+    return [schema.const];
+  if (!Array.isArray(schema.enum))
+    return null;
+  const values = schema.enum.filter((value) => typeof value === "string");
+  return values.length === schema.enum.length ? values : null;
+}
+var JSON_SCHEMA_TYPE_ORDER = [
+  "string",
+  "number",
+  "integer",
+  "boolean",
+  "object",
+  "array",
+  "null"
+];
+function jsonSchemaType(value) {
+  switch (value) {
+    case "array":
+    case "boolean":
+    case "integer":
+    case "null":
+    case "number":
+    case "object":
+    case "string":
+      return value;
+    default:
+      return null;
+  }
+}
+function valueType(value) {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "array";
+  if (isRecord(value))
+    return "object";
+  if (typeof value === "string")
+    return "string";
+  if (typeof value === "number")
+    return "number";
+  if (typeof value === "boolean")
+    return "boolean";
+  return null;
+}
+function normalizeTypes(types) {
+  const normalized = new Set(types);
+  if (normalized.has("number"))
+    normalized.delete("integer");
+  return JSON_SCHEMA_TYPE_ORDER.filter((type) => normalized.has(type));
+}
+function combinedBranchTypes(schema) {
+  for (const keyword of ["oneOf", "anyOf"]) {
+    const value = schema[keyword];
+    if (!Array.isArray(value) || value.length === 0)
+      continue;
+    const collected = [];
+    for (const branch of value) {
+      if (!isRecord(branch))
+        return null;
+      const types = typeNames(branch);
+      if (!types)
+        return null;
+      collected.push(...types);
+    }
+    return normalizeTypes(collected);
+  }
+  return null;
+}
+function typeNames(schema) {
+  const direct = jsonSchemaType(schema.type);
+  if (direct)
+    return [direct];
+  if (Array.isArray(schema.type)) {
+    const values = [];
+    for (const value of schema.type) {
+      const type = jsonSchemaType(value);
+      if (!type)
+        return null;
+      values.push(type);
+    }
+    return values.length > 0 ? normalizeTypes(values) : null;
+  }
+  if (schema.const !== undefined) {
+    const type = valueType(schema.const);
+    return type ? [type] : null;
+  }
+  if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+    const values = [];
+    for (const value of schema.enum) {
+      const type = valueType(value);
+      if (!type)
+        return null;
+      values.push(type);
+    }
+    return normalizeTypes(values);
+  }
+  return combinedBranchTypes(schema);
+}
+function typeSchema(type, nullable) {
+  const schema = { type: nullable ? [type, "null"] : type };
+  if (type === "array")
+    schema.items = {};
+  if (type === "object")
+    schema.additionalProperties = {};
+  return schema;
+}
+function commonBaseType(schemas) {
+  const names = schemas.map(typeNames);
+  if (names.some((value) => value === null))
+    return {};
+  let nullable = false;
+  const bases = new Set;
+  for (const branch of names) {
+    if (!branch)
+      return {};
+    for (const name of branch) {
+      if (name === "null")
+        nullable = true;
+      else
+        bases.add(name);
+    }
+  }
+  if (bases.size === 0)
+    return nullable ? { type: "null" } : {};
+  if (bases.size === 1) {
+    const [only] = bases;
+    return only ? typeSchema(only, nullable) : {};
+  }
+  if ([...bases].every((name) => name === "integer" || name === "number")) {
+    return typeSchema("number", nullable);
+  }
+  const types = normalizeTypes(nullable ? [...bases, "null"] : bases);
+  return types.length > 0 ? { type: types } : {};
+}
+function mergePropertySchemas(properties) {
+  const schemas = properties.map((property) => nullableProjection(property.schema));
+  const structural = schemas.map(withoutAnnotations);
+  const [first] = structural;
+  let merged;
+  if (first && structural.every((schema) => serializeCanonicalJson(schema) === serializeCanonicalJson(first))) {
+    merged = structuredClone(first);
+  } else {
+    const values = schemas.map(stringValues);
+    const allStrings = values.every((value) => value !== null);
+    merged = allStrings ? { type: "string", enum: [...new Set(values.flatMap((value) => value ?? []))] } : commonBaseType(schemas);
+  }
+  const descriptions = [
+    ...new Set(schemas.map((schema) => schema.description).filter((value) => typeof value === "string"))
+  ];
+  if (descriptions.length === 1)
+    merged.description = descriptions[0];
+  return merged;
+}
+
+// src/tools/schema/flatten.ts
+function rebuild(value) {
+  if (Array.isArray(value))
+    return value.map(rebuild);
+  if (!isRecord(value))
+    return value;
+  const node = {};
+  for (const [key, child] of Object.entries(value))
+    node[key] = rebuild(child);
+  return flattenNode(node);
+}
+function objectVariants(node) {
+  if (!Array.isArray(node.oneOf) || node.oneOf.length < 2)
+    return null;
+  const variants = node.oneOf.filter(isRecord);
+  if (variants.length !== node.oneOf.length)
+    return null;
+  if (variants.some((variant) => variant.type !== "object" || !isRecord(variant.properties))) {
+    return null;
+  }
+  return variants;
+}
+function findDiscriminator(variants) {
+  const [first] = variants;
+  if (!first || !isRecord(first.properties))
+    return null;
+  for (const key of Object.keys(first.properties).sort()) {
+    const values = [];
+    const seen = new Set;
+    let valid = true;
+    for (const variant of variants) {
+      if (!requiredKeys(variant).has(key)) {
+        valid = false;
+        break;
+      }
+      const properties = variant.properties;
+      const field = isRecord(properties) ? properties[key] : undefined;
+      const branchValues = isRecord(field) ? stringValues(field) : null;
+      if (!branchValues || branchValues.length === 0) {
+        valid = false;
+        break;
+      }
+      for (const value of branchValues) {
+        if (seen.has(value)) {
+          valid = false;
+          break;
+        }
+        seen.add(value);
+      }
+      if (!valid)
+        break;
+      values.push(branchValues);
+    }
+    if (valid)
+      return { key, values };
+  }
+  return null;
+}
+function requiredKeys(variant) {
+  if (!Array.isArray(variant.required))
+    return new Set;
+  return new Set(variant.required.filter((key) => typeof key === "string"));
+}
+function appendHint(schema, hint) {
+  const description = typeof schema.description === "string" ? schema.description : undefined;
+  return { ...schema, description: description ? `${description} ${hint}` : hint };
+}
+function flattenNode(node) {
+  const variants = objectVariants(node);
+  if (!variants)
+    return node;
+  const discriminator = findDiscriminator(variants);
+  if (!discriminator)
+    return node;
+  const perKey = new Map;
+  for (let index = 0;index < variants.length; index++) {
+    const variant = variants[index];
+    if (!variant)
+      continue;
+    const labels = discriminator.values[index] ?? [];
+    const required2 = requiredKeys(variant);
+    if (!isRecord(variant.properties))
+      continue;
+    for (const [key, rawSchema] of Object.entries(variant.properties)) {
+      if (key === discriminator.key || !isRecord(rawSchema))
+        continue;
+      const entries = perKey.get(key) ?? [];
+      entries.push({ schema: rawSchema, labels, required: required2.has(key) });
+      perKey.set(key, entries);
+    }
+  }
+  const discriminatorProperties = [];
+  for (let index = 0;index < variants.length; index++) {
+    const variant = variants[index];
+    if (!variant || !isRecord(variant.properties))
+      continue;
+    const schema = variant.properties[discriminator.key];
+    if (!isRecord(schema))
+      continue;
+    discriminatorProperties.push({
+      schema,
+      labels: discriminator.values[index] ?? [],
+      required: true
+    });
+  }
+  const properties = {
+    [discriminator.key]: mergePropertySchemas(discriminatorProperties)
+  };
+  const required = [discriminator.key];
+  for (const [key, entries] of perKey) {
+    let merged = mergePropertySchemas(entries);
+    const requiredEverywhere = entries.length === variants.length && entries.every((entry) => entry.required);
+    if (requiredEverywhere) {
+      required.push(key);
+    } else {
+      const requiredLabels = entries.filter((entry) => entry.required).flatMap((entry) => entry.labels);
+      const presentLabels = entries.flatMap((entry) => entry.labels);
+      const labels = requiredLabels.length > 0 ? requiredLabels : presentLabels;
+      const verb = requiredLabels.length > 0 ? "Required" : "Available";
+      merged = appendHint(merged, `${verb} if ${discriminator.key} = ${[...new Set(labels)].join(" | ")}`);
+    }
+    properties[key] = merged;
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(node)) {
+    if (key !== "oneOf" && key !== "anyOf" && key !== "properties" && key !== "required") {
+      result[key] = value;
+    }
+  }
+  result.type = "object";
+  result.properties = properties;
+  result.required = required;
+  result.additionalProperties = variants.every((variant) => variant.additionalProperties === false) ? false : {};
+  return result;
+}
+function flattenToolJsonSchema(schema) {
+  const result = rebuild(schema);
+  return isRecord(result) ? result : {};
+}
+function freezeToolJsonSchema(schema) {
+  for (const value of Object.values(schema))
+    freezeJsonValue(value);
+  return Object.freeze(schema);
+}
+function freezeJsonValue(value) {
+  if (Array.isArray(value)) {
+    for (const item of value)
+      freezeJsonValue(item);
+    Object.freeze(value);
+  } else if (isRecord(value)) {
+    freezeToolJsonSchema(value);
+  }
+}
+
+// src/tools/schema/untyped-properties.ts
+var TYPE_KEYWORDS2 = ["type", "enum", "const", "anyOf", "oneOf", "allOf", "$ref", "not"];
+function saysWhatItIs(schema) {
+  return TYPE_KEYWORDS2.some((keyword) => schema[keyword] !== undefined);
+}
+function findUntypedProperties(schema, prefix = "") {
+  if (!isRecord(schema))
+    return [];
+  const found = [];
+  const properties = schema.properties;
+  if (isRecord(properties)) {
+    for (const [key, value] of Object.entries(properties)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      if (isRecord(value)) {
+        if (!saysWhatItIs(value)) {
+          const description = value.description;
+          found.push({
+            path,
+            ...typeof description === "string" && { description }
+          });
+        }
+        found.push(...findUntypedProperties(value, path));
+      }
+    }
+  }
+  for (const key of ["items", "additionalProperties"]) {
+    const child = schema[key];
+    if (isRecord(child))
+      found.push(...findUntypedProperties(child, prefix));
+    if (Array.isArray(child)) {
+      for (const entry of child) {
+        if (isRecord(entry))
+          found.push(...findUntypedProperties(entry, prefix));
+      }
+    }
+  }
+  for (const key of ["prefixItems"]) {
+    const child = schema[key];
+    if (Array.isArray(child)) {
+      for (const entry of child) {
+        if (isRecord(entry))
+          found.push(...findUntypedProperties(entry, prefix));
+      }
+    }
+  }
+  const patterned = schema.patternProperties;
+  if (isRecord(patterned)) {
+    for (const value of Object.values(patterned)) {
+      if (isRecord(value))
+        found.push(...findUntypedProperties(value, prefix));
+    }
+  }
+  for (const key of ["$defs", "definitions"]) {
+    const container = schema[key];
+    if (!isRecord(container))
+      continue;
+    for (const definition of Object.values(container)) {
+      if (isRecord(definition))
+        found.push(...findUntypedProperties(definition, prefix));
+    }
+  }
+  for (const key of ["allOf", "anyOf", "oneOf"]) {
+    const branches = schema[key];
+    if (Array.isArray(branches)) {
+      for (const branch of branches)
+        found.push(...findUntypedProperties(branch, prefix));
+    }
+  }
+  return found;
+}
+
+// src/tools/internal/tool-view.ts
+function toolSurfaceOutputSchema(operation) {
+  if (!operation.outputSchema)
+    return;
+  return operation.toolView?.output ?? operation.outputSchema;
+}
+function applyToolViewDefaults(inputArgs, defaults) {
+  if (!defaults)
+    return inputArgs;
+  const filled = { ...inputArgs };
+  for (const [key, value] of Object.entries(defaults)) {
+    if (filled[key] === undefined)
+      filled[key] = structuredClone(value);
+  }
+  return filled;
+}
+function projectToolView(options) {
+  const { view } = options;
+  let projected = options.full;
+  if (view.project) {
+    try {
+      projected = Reflect.apply(view.project, undefined, [options.full, options.call]);
+    } catch (error) {
+      const failure = new AppError("INTERNAL_SERVER_ERROR", `${options.operation} toolView.project threw`, 500);
+      failure.cause = error;
+      throw failure;
+    }
+    if (isRecord(projected) && typeof projected.then === "function") {
+      Promise.resolve(projected).catch(() => {
+        return;
+      });
+      throw new AppError("INTERNAL_SERVER_ERROR", `${options.operation} toolView.project returned a Promise — it must be synchronous`, 500);
+    }
+    if (projected === undefined) {
+      return {
+        ok: false,
+        message: `${options.operation} toolView.project returned undefined`
+      };
+    }
+  }
+  const checked = validateDeclaredOutput(view.output ?? options.fullSchema, projected, view.project ? options.onStripped : undefined);
+  if (!checked.ok) {
+    return { ok: false, message: `${options.operation} toolView: ${checked.message}` };
+  }
+  return checked;
+}
+
+// src/tools/schema/schema.ts
+import { z } from "zod";
+function objectShapeKeys(schema) {
+  return schema instanceof z.ZodObject ? Object.keys(schema.shape) : [];
+}
+function keyPolicyOf(schema) {
+  return schema.def.catchall;
+}
+function rebuildObject(source, shape) {
+  return withKeyPolicy(z.object(shape), keyPolicyOf(source));
+}
+function withKeyPolicy(object, policy) {
+  if (policy === undefined)
+    return object;
+  return object.catchall(representable(policy));
+}
+function representable(policy) {
+  if (policy instanceof z.ZodNever || policy instanceof z.ZodUnknown)
+    return policy;
+  if (!(policy instanceof z.ZodType))
+    return z.unknown();
+  try {
+    toJsonSchema(policy, "input");
+    return policy;
+  } catch {
+    return z.unknown();
+  }
+}
+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 rebuildObject(inputSchema, {
+      ...paramsObject?.shape ?? {},
+      ...inputSchema.shape
+    });
+  }
+  return paramsObject ? z.intersection(paramsObject, inputSchema) : inputSchema;
+}
+
+// src/tools/names.ts
+var SINGULAR_EXCEPTIONS = new Set([
+  "analytics",
+  "status",
+  "stats",
+  "settings",
+  "media",
+  "progress",
+  "news"
+]);
+var TOOL_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+function normalizeService(value) {
+  return value.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+function normalizeMethod(value) {
+  return value.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+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 singularizeTail(name) {
+  const cut = name.lastIndexOf("_");
+  if (cut === -1)
+    return singularize(name);
+  return `${name.slice(0, cut + 1)}${singularize(name.slice(cut + 1))}`;
+}
+function hasUsableChars(value) {
+  return /[a-zA-Z0-9]/.test(value);
+}
+function assertToolName(name, serviceName, key) {
+  const where = `service "${serviceName}", method "${key}"`;
+  if (!TOOL_NAME_RE.test(name)) {
+    const why = name.length > 64 ? `is ${name.length} characters (max 64) — set an explicit \`tool.name\`` : "must match [a-zA-Z0-9_-]";
+    throw new Error(`Tool name "${name}" (${where}) ${why}`);
+  }
+}
+function toToolName(serviceName, methodName) {
+  const normalized = normalizeService(serviceName);
+  const singular = singularizeTail(normalized);
+  const method = normalizeMethod(methodName);
+  if (method === "list")
+    return `list_${normalized}`;
+  if (method === "get")
+    return `get_${singular}`;
+  if (method === "create")
+    return `create_${singular}`;
+  if (method === "update")
+    return `update_${singular}`;
+  if (method === "delete")
+    return `delete_${singular}`;
+  const snake = method.replace(/([A-Z])/g, "_$1").toLowerCase();
+  return `${snake}_${singular}`.replace(/^_/, "");
+}
+function assertUniqueToolName(name, taken, surface) {
+  if (taken) {
+    throw new Error(`Duplicate ${surface} "${name}" across mounted operations`);
+  }
+}
+
+// src/tools/schema/presentation.ts
+import { z as z2 } from "zod";
+
+// src/json-schema/dialect.ts
+var DRAFT_07_MARKER = "draft-07";
+var DRAFT_07_KEYWORD = "definitions";
+var DEFS_KEYWORD = "$defs";
+function declaresDraft07(dialect) {
+  return typeof dialect === "string" && dialect.includes(DRAFT_07_MARKER);
+}
+function rewriteDefinitionPointers(value) {
+  if (Array.isArray(value))
+    return value.map(rewriteDefinitionPointers);
+  if (!isRecord(value))
+    return value;
+  const rewritten = {};
+  for (const [key, child] of Object.entries(value)) {
+    rewritten[key] = key === "$ref" && typeof child === "string" && child.startsWith(`#/${DRAFT_07_KEYWORD}/`) ? `#/${DEFS_KEYWORD}/${child.slice(`#/${DRAFT_07_KEYWORD}/`.length)}` : rewriteDefinitionPointers(child);
+  }
+  return rewritten;
+}
+function withDefsDialect(schema) {
+  const definitions = schema[DRAFT_07_KEYWORD];
+  if (!isRecord(definitions) || DEFS_KEYWORD in schema)
+    return schema;
+  const rewritten = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (key === DRAFT_07_KEYWORD)
+      continue;
+    rewritten[key] = rewriteDefinitionPointers(value);
+  }
+  rewritten[DEFS_KEYWORD] = rewriteDefinitionPointers(definitions);
+  return rewritten;
+}
+
+// src/tools/schema/presentation.ts
+function withoutDialect(schema) {
+  const result = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (key !== "$schema")
+      result[key] = value;
+  }
+  return result;
+}
+function hasLocalReference(value) {
+  if (Array.isArray(value))
+    return value.some(hasLocalReference);
+  if (!isRecord(value))
+    return false;
+  if (typeof value.$ref === "string" && value.$ref.startsWith("#"))
+    return true;
+  return Object.values(value).some(hasLocalReference);
+}
+var NAMESPACE_SEPARATOR = "__";
+var DEFINITION_KEYWORDS = ["definitions", "$defs"];
+function rewriteReference(reference, namespace, targets) {
+  if (reference === "#" || reference === "#/") {
+    targets.rootReferenced = true;
+    return `#/definitions/${namespace}`;
+  }
+  const segments = reference.slice(2).split("/");
+  const [keyword, name, ...rest] = segments;
+  if (keyword !== undefined && name !== undefined && DEFINITION_KEYWORDS.includes(keyword)) {
+    const renamed = `${namespace}${NAMESPACE_SEPARATOR}${name}`;
+    return ["#", "definitions", renamed, ...rest].join("/");
+  }
+  targets.rootReferenced = true;
+  return `#/definitions/${namespace}/${segments.join("/")}`;
+}
+function rewriteLocalReferences(value, namespace, targets) {
+  if (Array.isArray(value)) {
+    return value.map((child) => rewriteLocalReferences(child, namespace, targets));
+  }
+  if (!isRecord(value))
+    return value;
+  const rewritten = {};
+  for (const [key, child] of Object.entries(value)) {
+    rewritten[key] = key === "$ref" && typeof child === "string" && child.startsWith("#") ? rewriteReference(child, namespace, targets) : rewriteLocalReferences(child, namespace, targets);
+  }
+  return rewritten;
+}
+function namespaceLocalReferences(schema, namespace) {
+  if (!schema || !hasLocalReference(schema))
+    return schema;
+  const targets = { rootReferenced: false };
+  const rewritten = rewriteLocalReferences(schema, namespace, targets);
+  if (!isRecord(rewritten))
+    return schema;
+  const definitions = {};
+  const body = {};
+  for (const [key, value] of Object.entries(rewritten)) {
+    if (DEFINITION_KEYWORDS.includes(key)) {
+      if (isRecord(value)) {
+        for (const [name, definition] of Object.entries(value)) {
+          definitions[`${namespace}${NAMESPACE_SEPARATOR}${name}`] = definition;
+        }
+      }
+      continue;
+    }
+    body[key] = value;
+  }
+  if (targets.rootReferenced)
+    definitions[namespace] = withoutDialect(body);
+  if (Object.keys(definitions).length === 0)
+    return body;
+  return { ...body, definitions };
+}
+function objectProperties(schema) {
+  return schema.type === "object" && isRecord(schema.properties) ? schema.properties : null;
+}
+function requiredKeys2(schema) {
+  return Array.isArray(schema.required) ? schema.required.filter((key) => typeof key === "string") : [];
+}
+function hoistDefinitions(schema) {
+  const branches = Array.isArray(schema.allOf) ? schema.allOf : [];
+  const definitions = {};
+  const lifted = branches.map((branch) => {
+    if (!isRecord(branch) || !isRecord(branch.definitions))
+      return branch;
+    Object.assign(definitions, branch.definitions);
+    const rest = {};
+    for (const [key, value] of Object.entries(branch)) {
+      if (key !== "definitions")
+        rest[key] = value;
+    }
+    return rest;
+  });
+  if (Object.keys(definitions).length === 0)
+    return schema;
+  return { ...schema, allOf: lifted, definitions };
+}
+function mergeObjectSchemas(left, right, rightOwnsUnknownKeys) {
+  const leftProperties = objectProperties(left);
+  const rightProperties = objectProperties(right);
+  if (!leftProperties || !rightProperties)
+    return hoistDefinitions({ allOf: [left, right] });
+  const conflicts = Object.keys(leftProperties).filter((key) => (key in rightProperties));
+  if (conflicts.length > 0) {
+    throw new Error(`Schema merge conflict: ${conflicts.join(", ")} appear in both params and input`);
+  }
+  const merged = {
+    type: "object",
+    properties: { ...leftProperties, ...rightProperties },
+    required: [...new Set([...requiredKeys2(left), ...requiredKeys2(right)])]
+  };
+  const leftDefinitions = isRecord(left.definitions) ? left.definitions : {};
+  const rightDefinitions = isRecord(right.definitions) ? right.definitions : {};
+  const definitions = { ...leftDefinitions, ...rightDefinitions };
+  if (Object.keys(definitions).length > 0)
+    merged.definitions = definitions;
+  const unknownKeys = rightOwnsUnknownKeys ? right.additionalProperties : left.additionalProperties;
+  if (unknownKeys !== undefined)
+    merged.additionalProperties = unknownKeys;
+  return merged;
+}
+function schemaFromZod(schema, unrepresentable, flatten) {
+  if (!schema)
+    return;
+  const json = toJsonSchema(schema, "input", unrepresentable, "draft-07");
+  return flatten ? flattenToolJsonSchema(json) : json;
+}
+function buildToolPresentationSchema(config) {
+  const unrepresentable = config.unrepresentable ?? "any";
+  const flatten = config.flattenUnionInput ?? false;
+  const params = namespaceLocalReferences(schemaFromZod(config.paramsSchema, unrepresentable, flatten), "params");
+  const input = namespaceLocalReferences(schemaFromZod(config.inputSchema, unrepresentable, flatten), "input");
+  let presentation;
+  if (params && input) {
+    presentation = mergeObjectSchemas(withoutDialect(params), withoutDialect(input), true);
+  } else if (input) {
+    presentation = input;
+  } else if (params) {
+    presentation = params;
+  } else {
+    presentation = {
+      $schema: "http://json-schema.org/draft-07/schema#",
+      type: "object",
+      properties: {}
+    };
+  }
+  if (config.extendSchema) {
+    const extra = namespaceLocalReferences(schemaFromZod(z2.object(config.extendSchema), unrepresentable, flatten), "extend");
+    if (extra) {
+      presentation = mergeObjectSchemas(withoutDialect(extra), withoutDialect(presentation), true);
+    }
+  }
+  if (config.defaults)
+    presentation = withToolDefaults(presentation, config.defaults);
+  if (presentation.$schema === undefined) {
+    presentation = {
+      $schema: "http://json-schema.org/draft-07/schema#",
+      ...presentation
+    };
+  }
+  return freezeToolJsonSchema(presentation);
+}
+function withToolDefaults(schema, defaults) {
+  const properties = objectProperties(schema);
+  if (!properties)
+    return schema;
+  const keys = Object.keys(defaults).filter((key) => isRecord(properties[key]));
+  if (keys.length === 0)
+    return schema;
+  const nextProperties = { ...properties };
+  for (const key of keys) {
+    const property = properties[key];
+    if (!isRecord(property))
+      continue;
+    const value = structuredClone(defaults[key]);
+    nextProperties[key] = typeof property.$ref === "string" ? { allOf: [property], default: value } : { ...property, default: value };
+  }
+  const required = requiredKeys2(schema).filter((key) => !keys.includes(key));
+  const next = { ...schema, properties: nextProperties };
+  if (Array.isArray(schema.required))
+    next.required = required;
+  return next;
+}
+function isObjectPresentationSchema(schema) {
+  return schema.type === "object" && isRecord(schema.properties);
+}
+function presentationMetadata(schema) {
+  return withDefsDialect(withoutDialect(schema));
+}
+
+// src/tools/internal/surface-projector.ts
+import { z as z3 } from "zod";
+
+// src/tools/mcp/round-policy.ts
+function staticInputRounds(policy) {
+  return Array.isArray(policy.inputRequired) ? policy.inputRequired : undefined;
+}
+function validateMcpRoundPolicy(tool, policy, runtime) {
+  if (!runtime?.stateConfigured) {
+    throw new Error(`[stitchkit] MCP tool "${tool.name}" declares inputRequired but no multiRound.state key is configured`);
+  }
+  const { maxRounds } = runtime;
+  if (!Number.isInteger(maxRounds) || maxRounds < 1) {
+    throw new Error("[stitchkit] multiRound.serving.maxRounds must be a positive integer");
+  }
+  const declared = staticInputRounds(policy);
+  if (!declared)
+    return;
+  if (declared.length === 0) {
+    throw new Error(`[stitchkit] MCP tool "${tool.name}" must declare at least one input round`);
+  }
+  assertRoundShape(tool, declared, maxRounds);
+}
+function validateResolvedInputRounds(tool, resolved, maxRounds) {
+  assertRoundShape(tool, resolved, maxRounds);
+}
+function assertRoundShape(tool, rounds, maxRounds) {
+  if (rounds.length > maxRounds) {
+    throw new Error(`[stitchkit] MCP tool "${tool.name}" declares ${rounds.length} input rounds, exceeding maxRounds ${maxRounds}`);
+  }
+  const keys = new Set;
+  for (const request of rounds) {
+    if (keys.has(request.key)) {
+      throw new Error(`[stitchkit] MCP tool "${tool.name}" declares duplicate input key "${request.key}"`);
+    }
+    keys.add(request.key);
+  }
+}
+
+// src/tools/internal/surface-projector.ts
+function assertToolExtensionCompatible(base, extra) {
+  if (!(base instanceof z3.ZodObject))
+    return;
+  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`);
+  }
+}
+function projectRuntimeTool(definition, assertName = true) {
+  if (assertName) {
+    assertProjectedName(definition.name, definition.identity.serviceName, definition.identity.action, "MCP", false);
+  }
+  return {
+    kind: "runtime",
+    source: definition,
+    serviceName: definition.identity.serviceName,
+    action: definition.identity.action,
+    name: definition.name,
+    presentationSchema: buildToolPresentationSchema({
+      inputSchema: definition.input,
+      unrepresentable: "any"
+    }),
+    shouldExtend: false,
+    ...definition.mcp !== undefined && { mcp: definition.mcp }
+  };
+}
+function projectedRuntimeToolSupports(definition, transport) {
+  if (definition.transports?.length === 0) {
+    throw new Error(`Runtime tool "${definition.name}" must expose at least one transport`);
+  }
+  return definition.transports ? definition.transports.includes(transport) : transport !== "CLI";
+}
+function duplicateLabel(transport) {
+  if (transport === "MCP")
+    return "MCP tool name";
+  if (transport === "AGENT")
+    return "agent tool name";
+  return "CLI command";
+}
+function assertProjectedName(name, serviceName, action, transport, derived) {
+  if (transport === "CLI")
+    return;
+  if (derived && !hasUsableChars(serviceName)) {
+    throw new Error(`Service prefix "${serviceName}" (method "${action}") has no characters usable in a tool name — set an explicit \`tool.name\` or rename the prefix`);
+  }
+  assertToolName(name, serviceName, action);
+}
+function projectToolSurface(surface, transport, config = {}) {
+  const projected = [];
+  const names = new Set;
+  const origins = new Map;
+  const append = (tool) => {
+    if (config.assertUniqueNames ?? true) {
+      if (names.has(tool.name)) {
+        const previous = origins.get(tool.name) ?? "unknown";
+        const current = `${tool.serviceName}.${tool.action}`;
+        throw new Error(`Duplicate ${duplicateLabel(transport)} "${tool.name}" across mounted operations: ${previous}, ${current}`);
+      }
+      assertUniqueToolName(tool.name, false, duplicateLabel(transport));
+    }
+    names.add(tool.name);
+    origins.set(tool.name, `${tool.serviceName}.${tool.action}`);
+    projected.push(tool);
+  };
+  for (const service of surface.services ?? []) {
+    for (const [methodName, method] of Object.entries(service.methods)) {
+      if (transport === "CLI") {
+        if (!method.expose?.includes("CLI"))
+          continue;
+      } else if (method.expose && !method.expose.includes(transport)) {
+        continue;
+      }
+      if (method.multipart || method.rawBody || method.responseMeta || method.rawResponse) {
+        continue;
+      }
+      const name = method.toolName ?? toToolName(service.name, methodName);
+      if (config.assertNames ?? true) {
+        assertProjectedName(name, service.name, methodName, transport, !method.toolName);
+      }
+      const shouldExtend = transport !== "CLI" && config.extend !== undefined && (!config.extend.filter || config.extend.filter(service, method));
+      if (shouldExtend && config.extend) {
+        assertToolExtensionCompatible(mergeSchemas(method.paramsSchema, method.inputSchema), config.extend.schema);
+      }
+      append({
+        kind: "contract",
+        source: method,
+        serviceName: method.serviceName,
+        action: method.key,
+        name,
+        presentationSchema: buildToolPresentationSchema({
+          paramsSchema: method.paramsSchema,
+          inputSchema: method.inputSchema,
+          defaults: method.toolView?.defaults,
+          extendSchema: shouldExtend ? config.extend?.schema : undefined,
+          flattenUnionInput: config.flattenUnionInput,
+          unrepresentable: "any"
+        }),
+        shouldExtend,
+        ...method.mcp !== undefined && { mcp: method.mcp }
+      });
+    }
+  }
+  for (const definition of surface.runtimeTools ?? []) {
+    if (!projectedRuntimeToolSupports(definition, transport))
+      continue;
+    if (config.assertNames ?? true) {
+      assertProjectedName(definition.name, definition.identity.serviceName, definition.identity.action, transport, false);
+    }
+    append(projectRuntimeTool(definition, false));
+  }
+  return projected;
+}
+function mcpProjectionCandidate(tool) {
+  if (tool.kind === "contract") {
+    return {
+      tool,
+      name: tool.name,
+      ...tool.source.paramsSchema !== undefined && {
+        paramsSchema: tool.source.paramsSchema
+      },
+      ...tool.source.inputSchema !== undefined && {
+        inputSchema: tool.source.inputSchema
+      },
+      ...tool.source.toolView?.defaults !== undefined && {
+        inputDefaults: tool.source.toolView.defaults
+      },
+      ...toolSurfaceOutputSchema(tool.source) !== undefined && {
+        outputSchema: toolSurfaceOutputSchema(tool.source)
+      },
+      shouldExtend: tool.shouldExtend,
+      ...tool.mcp !== undefined && { mcp: tool.mcp }
+    };
+  }
+  return {
+    tool,
+    name: tool.name,
+    inputSchema: tool.source.input,
+    ...tool.source.output !== undefined && { outputSchema: tool.source.output },
+    shouldExtend: false,
+    ...tool.mcp !== undefined && { mcp: tool.mcp }
+  };
+}
+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 prepareProjectedMcpTools(tools, config = {}) {
+  const policy = config.schemaValidation?.policy ?? "throw";
+  const failures = [];
+  const prepared = [];
+  const names = new Set;
+  for (const tool of tools) {
+    assertUniqueToolName(tool.name, names.has(tool.name), "MCP tool name");
+    names.add(tool.name);
+    if (tool.mcp)
+      validateMcpRoundPolicy(tool, tool.mcp, config.multiRound);
+    let inputSchema;
+    try {
+      inputSchema = buildToolPresentationSchema({
+        paramsSchema: tool.paramsSchema,
+        inputSchema: tool.inputSchema,
+        extendSchema: tool.shouldExtend && config.extend ? config.extend.schema : undefined,
+        flattenUnionInput: config.flattenUnionInput,
+        unrepresentable: "throw",
+        defaults: tool.inputDefaults
+      });
+    } catch (error) {
+      reportIncompatible(`MCP tool "${tool.name}" — input schema is not JSON Schema-compatible: ${error instanceof Error ? error.message : String(error)}`, policy, config.logger, failures);
+      continue;
+    }
+    if (!isObjectPresentationSchema(inputSchema)) {
+      reportIncompatible(`MCP tool "${tool.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, config.logger, failures);
+      continue;
+    }
+    if (config.schemaValidation?.requireTypedProperties) {
+      const allowed = new Set(config.schemaValidation.allowUntyped ?? []);
+      for (const untyped of findUntypedProperties(inputSchema)) {
+        const path = `${tool.name}.${untyped.path}`;
+        if (allowed.has(path))
+          continue;
+        const clue = untyped.description ? ` (only a description: "${untyped.description}")` : "";
+        reportIncompatible(`MCP tool "${tool.name}" — input property "${untyped.path}" carries no type, enum or $ref${clue}. A model is given no way to know what to send. Use \`z.json()\` for an arbitrary JSON value; use \`allowUntyped\` only when the presentation value is genuinely not representable as JSON Schema.`, policy === "skip" ? "warn" : policy, config.logger, failures);
+      }
+    }
+    if (config.schemaValidation?.requirePortableFormats) {
+      for (const finding of findNonPortableFormats(inputSchema, config.schemaValidation.allowFormats)) {
+        reportIncompatible(`MCP tool "${tool.name}" — input property "${finding.path}" uses non-portable JSON Schema format "${finding.format}". Use a portable pattern/schema, or list the format in \`allowFormats\` only when every MCP client supports it.`, policy === "skip" ? "warn" : policy, config.logger, failures);
+      }
+    }
+    const outputSchema = tool.outputSchema;
+    let compatibleOutput;
+    if (outputSchema) {
+      try {
+        const output = toJsonSchema(outputSchema, "output");
+        compatibleOutput = outputSchema;
+        if (config.schemaValidation?.requirePortableFormats) {
+          for (const finding of findNonPortableFormats(output, config.schemaValidation.allowFormats)) {
+            reportIncompatible(`MCP tool "${tool.name}" — output property "${finding.path}" uses non-portable JSON Schema format "${finding.format}". Use a portable pattern/schema, or list the format in \`allowFormats\` only when every MCP client supports it.`, policy === "skip" ? "warn" : policy, config.logger, failures);
+          }
+        }
+      } catch (error) {
+        reportIncompatible(`MCP tool "${tool.name}" — output schema is not JSON Schema-compatible: ${error instanceof Error ? error.message : String(error)}`, policy, config.logger, failures);
+      }
+    }
+    prepared.push({
+      tool: tool.tool,
+      inputSchema,
+      ...compatibleOutput !== undefined && { outputSchema: compatibleOutput }
+    });
+  }
+  if (failures.length > 0) {
+    throw new Error(`[stitchkit] ${failures.length} problem(s) with MCP tool schemas:
+ - ${failures.join(`
+ - `)}`);
+  }
+  return prepared;
+}
+
+export { toolSurfaceOutputSchema, applyToolViewDefaults, projectToolView, objectShapeKeys, rebuildObject, mergeSchemas, staticInputRounds, validateMcpRoundPolicy, validateResolvedInputRounds, assertToolName, assertUniqueToolName, PORTABLE_JSON_SCHEMA_FORMATS, findNonPortableFormats, declaresDraft07, withDefsDialect, flattenToolJsonSchema, buildToolPresentationSchema, presentationMetadata, findUntypedProperties, assertToolExtensionCompatible, projectRuntimeTool, projectToolSurface, mcpProjectionCandidate, prepareProjectedMcpTools };