stitchkit 0.36.0 → 0.37.0

package/dist/{index-kgga1n8d.js → index-s6yhmg1k.js}

@@ -1,7 +1,7 @@
 import {
   jsonSchemaFields,
   toJsonSchema
-} from "./index-0ed3bx43.js";
+} from "./index-frfyw9fa.js";
 import {
   isWithinDir
 } from "./index-x3fcszf8.js";
@@ -14,7 +14,7 @@ import {
   runWithRequestContext,
   safeJsonParse,
   validateHandlerOutput
-} from "./index-17rdjw68.js";
+} from "./index-e497hxcy.js";
 
 // src/tools/coerce.ts
 import { z } from "zod";
@@ -77,8 +77,325 @@ function coerceJsonArgs(args, schema) {
   return isRecord(coerced) ? coerced : args;
 }
 
+// src/tools/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 stableJson(value) {
+  if (Array.isArray(value))
+    return `[${value.map(stableJson).join(",")}]`;
+  if (!isRecord(value))
+    return JSON.stringify(value) ?? "undefined";
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+}
+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;
+}
+function typeNames(schema) {
+  if (typeof schema.type === "string")
+    return [schema.type];
+  if (Array.isArray(schema.type)) {
+    const values2 = schema.type.filter((value) => typeof value === "string");
+    if (values2.length === schema.type.length)
+      return values2;
+  }
+  const values = stringValues(schema);
+  if (values)
+    return ["string"];
+  if (typeof schema.const === "number")
+    return ["number"];
+  if (typeof schema.const === "boolean")
+    return ["boolean"];
+  return null;
+}
+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 === 1) {
+    const [only] = bases;
+    return only ? typeSchema(only, nullable) : {};
+  }
+  if ([...bases].every((name) => name === "integer" || name === "number")) {
+    return typeSchema("number", nullable);
+  }
+  return {};
+}
+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) => stableJson(schema) === stableJson(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/flatten.ts
-import { z as z3 } from "zod";
+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 stringValues2(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;
+}
+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) ? stringValues2(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/mount.ts
+import { z as z4 } from "zod";
 
 // src/tools/schema.ts
 import { z as z2 } from "zod";
@@ -131,300 +448,6 @@ function mergeSchemas(paramsSchema, inputSchema) {
   return paramsObject ? z2.intersection(paramsObject, inputSchema) : inputSchema;
 }
 
-// src/tools/flatten.ts
-function flattenDiscriminatedUnion(union) {
-  const discriminator = union.def.discriminator;
-  const allDiscValues = [];
-  const perKey = new Map;
-  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 discValues = stringLiteralOrEnumValues(opt.shape[discriminator]);
-    if (discValues === null) {
-      throw new Error(`flattenDiscriminatedUnion: discriminator '${discriminator}' must be a string z.literal() or z.enum()`);
-    }
-    allDiscValues.push(...discValues);
-    const label = discValues.join(" | ");
-    for (const [key, field] of Object.entries(opt.shape)) {
-      if (key === discriminator)
-        continue;
-      const entry = perKey.get(key) ?? { schemas: [], variants: [] };
-      entry.schemas.push(unwrapField(field));
-      entry.variants.push(label);
-      perKey.set(key, entry);
-    }
-  }
-  const uniqDisc = [...new Set(allDiscValues)];
-  const [firstLiteral, ...restLiterals] = uniqDisc;
-  if (firstLiteral === undefined) {
-    throw new Error("flattenDiscriminatedUnion: union has no options");
-  }
-  const shape = {
-    [discriminator]: z3.enum([firstLiteral, ...restLiterals])
-  };
-  for (const [key, entry] of perKey) {
-    const advertised = mergeCollidingFields(entry.schemas);
-    const hint = `Required if ${discriminator} = ${[...new Set(entry.variants)].join(" | ")}`;
-    shape[key] = z3.optional(advertised).describe(hint);
-  }
-  return withKeyPolicy(z3.object(shape), mergeVariantKeyPolicies(union.def.options));
-}
-function mergeVariantKeyPolicies(options) {
-  let strict = 0;
-  let counted = 0;
-  for (const option of options) {
-    const policy = option instanceof z3.ZodObject ? keyPolicyOf(option) : undefined;
-    if (policy !== undefined && !(policy instanceof z3.ZodNever))
-      return z3.unknown();
-    counted++;
-    if (policy instanceof z3.ZodNever)
-      strict++;
-  }
-  if (counted === 0 || strict === 0)
-    return;
-  return strict === counted ? z3.never() : z3.unknown();
-}
-function unwrapField(field) {
-  if (field instanceof z3.ZodOptional || field instanceof z3.ZodDefault) {
-    return unwrapField(field.unwrap());
-  }
-  return field;
-}
-function preserveDescription(from, to) {
-  return from.description === undefined ? to : to.describe(from.description);
-}
-function stringLiteralOrEnumValues(field) {
-  let raw = null;
-  if (field instanceof z3.ZodLiteral)
-    raw = field.def.values;
-  else if (field instanceof z3.ZodEnum)
-    raw = field.options;
-  if (raw === null)
-    return null;
-  const strings = raw.filter((v) => typeof v === "string");
-  return strings.length === raw.length ? strings : null;
-}
-function isFlattenableDU(union) {
-  const disc = union.def.discriminator;
-  if (union.def.options.length === 0)
-    return false;
-  for (const opt of union.def.options) {
-    if (!(opt instanceof z3.ZodObject))
-      return false;
-    if (stringLiteralOrEnumValues(opt.shape[disc]) === null)
-      return false;
-  }
-  return true;
-}
-function stripAnnotations(node) {
-  if (Array.isArray(node)) {
-    for (const item of node)
-      stripAnnotations(item);
-    return;
-  }
-  if (typeof node === "object" && node !== null) {
-    Reflect.deleteProperty(node, "description");
-    Reflect.deleteProperty(node, "default");
-    Reflect.deleteProperty(node, "$schema");
-    for (const value of Object.values(node))
-      stripAnnotations(value);
-  }
-}
-function hasInvisibleConstraint(schema) {
-  if (!(schema instanceof z3.ZodType))
-    return false;
-  const def = schema.def;
-  if (isRecord(def) && def.type !== "unknown" && def.type !== "any") {
-    if (normalizedJson(schema) === "{}")
-      return true;
-  }
-  if (schema instanceof z3.ZodCatch)
-    return true;
-  if (isRecord(def) && def.coerce === true)
-    return true;
-  if (isRecord(def) && Array.isArray(def.checks)) {
-    for (const check of def.checks) {
-      if (isInvisibleCheck(check))
-        return true;
-    }
-  }
-  if (schema instanceof z3.ZodOptional || schema instanceof z3.ZodNullable || schema instanceof z3.ZodDefault) {
-    return hasInvisibleConstraint(schema.unwrap());
-  }
-  if (schema instanceof z3.ZodPipe)
-    return true;
-  if (schema instanceof z3.ZodObject) {
-    return Object.values(schema.shape).some(hasInvisibleConstraint);
-  }
-  if (schema instanceof z3.ZodArray)
-    return hasInvisibleConstraint(schema.element);
-  if (schema instanceof z3.ZodUnion)
-    return schema.def.options.some(hasInvisibleConstraint);
-  if (schema instanceof z3.ZodRecord)
-    return hasInvisibleConstraint(schema.valueType);
-  if (schema instanceof z3.ZodIntersection) {
-    return hasInvisibleConstraint(schema.def.left) || hasInvisibleConstraint(schema.def.right);
-  }
-  return false;
-}
-var INVISIBLE_CHECK_KINDS = new Set(["custom", "overwrite"]);
-function acceptsMoreThanItsType(schema) {
-  if (!(schema instanceof z3.ZodType))
-    return false;
-  if (schema instanceof z3.ZodCatch)
-    return true;
-  if (isRecord(schema.def) && schema.def.coerce === true)
-    return true;
-  if (schema instanceof z3.ZodOptional || schema instanceof z3.ZodNullable || schema instanceof z3.ZodDefault) {
-    return acceptsMoreThanItsType(schema.unwrap());
-  }
-  if (schema instanceof z3.ZodPipe)
-    return acceptsMoreThanItsType(schema.def.in);
-  return false;
-}
-function isInvisibleCheck(check) {
-  if (!isRecord(check))
-    return false;
-  const inner = check._zod;
-  const def = isRecord(inner) ? inner.def : undefined;
-  const kind = isRecord(def) ? def.check : undefined;
-  return typeof kind === "string" && INVISIBLE_CHECK_KINDS.has(kind);
-}
-function projectToBaseType(schema) {
-  if (!(schema instanceof z3.ZodType))
-    return z3.unknown();
-  if (schema instanceof z3.ZodNullable) {
-    return z3.nullable(projectToBaseType(schema.unwrap()));
-  }
-  if (schema instanceof z3.ZodOptional || schema instanceof z3.ZodDefault) {
-    return projectToBaseType(schema.unwrap());
-  }
-  if (schema instanceof z3.ZodPipe)
-    return projectToBaseType(schema.def.in);
-  if (schema instanceof z3.ZodCatch)
-    return z3.unknown();
-  const coerces = isRecord(schema.def) && schema.def.coerce === true;
-  if (schema instanceof z3.ZodNumber)
-    return coerces ? z3.coerce.number() : z3.number();
-  if (schema instanceof z3.ZodString)
-    return coerces ? z3.coerce.string() : z3.string();
-  if (schema instanceof z3.ZodBoolean && coerces)
-    return z3.coerce.boolean();
-  if (schema instanceof z3.ZodEnum || schema instanceof z3.ZodLiteral) {
-    return stringLiteralOrEnumValues(schema) === null ? z3.unknown() : z3.string();
-  }
-  if (schema instanceof z3.ZodBoolean)
-    return z3.boolean();
-  if (schema instanceof z3.ZodArray)
-    return z3.array(z3.unknown());
-  if (schema instanceof z3.ZodObject)
-    return z3.looseObject({});
-  return z3.unknown();
-}
-function normalizedJson(schema) {
-  if (!(schema instanceof z3.ZodType))
-    return "{}";
-  const json = toJsonSchema(schema, "input", "any");
-  stripAnnotations(json);
-  return JSON.stringify(json);
-}
-function mergeCollidingFields(schemas) {
-  const distinct = new Map;
-  for (const schema of schemas) {
-    const key = normalizedJson(schema);
-    if (!distinct.has(key))
-      distinct.set(key, schema);
-  }
-  const values = [...distinct.values()];
-  const only = values[0];
-  if (values.length <= 1) {
-    if (only === undefined)
-      return z3.unknown();
-    if (schemas.length <= 1)
-      return only;
-    const hazards2 = schemas.map(acceptsMoreThanItsType);
-    if (hazards2.some(Boolean) && !hazards2.every(Boolean))
-      return z3.unknown();
-    if (schemas.some(hasInvisibleConstraint)) {
-      if (normalizedJson(only) === "{}")
-        return only;
-      return projectToBaseType(only);
-    }
-    return only;
-  }
-  const merged = [];
-  let allEnum = true;
-  for (const schema of values) {
-    const vals = stringLiteralOrEnumValues(schema);
-    if (vals === null) {
-      allEnum = false;
-      break;
-    }
-    merged.push(...vals);
-  }
-  if (allEnum) {
-    const uniq = [...new Set(merged)];
-    const [first2, ...rest] = uniq;
-    if (first2 !== undefined)
-      return z3.enum([first2, ...rest]);
-  }
-  const hazards = schemas.map(acceptsMoreThanItsType);
-  if (hazards.some(Boolean) && !hazards.every(Boolean))
-    return z3.unknown();
-  const projected = values.map(projectToBaseType);
-  const first = projected[0];
-  if (first !== undefined) {
-    const shape = normalizedJson(first);
-    if (shape !== "{}" && projected.every((p) => normalizedJson(p) === shape))
-      return first;
-  }
-  return z3.unknown();
-}
-function flattenUnionsDeep(schema) {
-  if (!(schema instanceof z3.ZodType))
-    return z3.unknown();
-  if (schema instanceof z3.ZodDiscriminatedUnion) {
-    if (!isFlattenableDU(schema))
-      return schema;
-    return preserveDescription(schema, flattenUnionsDeep(flattenDiscriminatedUnion(schema)));
-  }
-  if (schema instanceof z3.ZodObject) {
-    const shape = {};
-    for (const [key, field] of Object.entries(schema.shape)) {
-      shape[key] = flattenUnionsDeep(field);
-    }
-    return preserveDescription(schema, rebuildObject(schema, shape));
-  }
-  if (schema instanceof z3.ZodArray) {
-    return preserveDescription(schema, z3.array(flattenUnionsDeep(schema.element)));
-  }
-  if (schema instanceof z3.ZodUnion) {
-    const opts = schema.def.options.map((option) => flattenUnionsDeep(option));
-    const [a, b, ...rest] = opts;
-    return a && b ? preserveDescription(schema, z3.union([a, b, ...rest])) : schema;
-  }
-  if (schema instanceof z3.ZodRecord) {
-    return preserveDescription(schema, z3.record(schema.keyType, flattenUnionsDeep(schema.valueType)));
-  }
-  if (schema instanceof z3.ZodOptional) {
-    return preserveDescription(schema, z3.optional(flattenUnionsDeep(schema.unwrap())));
-  }
-  if (schema instanceof z3.ZodNullable) {
-    return preserveDescription(schema, z3.nullable(flattenUnionsDeep(schema.unwrap())));
-  }
-  if (schema instanceof z3.ZodDefault) {
-    return preserveDescription(schema, flattenUnionsDeep(schema.unwrap()).default(schema.def.defaultValue));
-  }
-  if (schema instanceof z3.ZodIntersection) {
-    return preserveDescription(schema, z3.intersection(flattenUnionsDeep(schema.def.left), flattenUnionsDeep(schema.def.right)));
-  }
-  return schema;
-}
-
-// src/tools/mount.ts
-import { z as z4 } from "zod";
-
 // src/tools/execute.ts
 function toolResultFromError(err) {
   const appErr = normalizeError(err);
@@ -435,40 +458,112 @@ function toolResultFromError(err) {
     ...appErr.hint && { hint: appErr.hint }
   };
 }
-async function executeToolMethod(method, toolName, rawArgs, context, hooks, lifecycle, coerceJson = false, onOutputStrip) {
+async function executeToolMethod(method, toolName, rawArgs, context, hooks, lifecycle, coerceJson = false, onOutputStrip, extension) {
+  return inToolCallContext({ source: context.source, toolName, method }, () => runToolMethod(method, toolName, rawArgs, context, hooks, lifecycle, coerceJson, onOutputStrip, extension));
+}
+function inToolCallContext(call, body) {
   const parent = getRequestContext();
-  if (!parent) {
-    return runToolMethod(method, toolName, rawArgs, context, hooks, lifecycle, coerceJson, onOutputStrip);
-  }
+  if (!parent)
+    return body();
   return runWithRequestContext({
     ...parent,
     trace: parent.trace,
     dimensions: parent.dimensions ? { ...parent.dimensions } : undefined,
     error: undefined,
-    source: context.source,
+    source: call.source,
     method: "TOOL",
-    path: `/${context.source}/${toolName}`,
-    serviceName: method.serviceName,
-    action: method.key
-  }, () => runToolMethod(method, toolName, rawArgs, context, hooks, lifecycle, coerceJson, onOutputStrip));
+    path: `/${call.source}/${call.toolName}`,
+    serviceName: call.method.serviceName,
+    action: call.method.key
+  }, body);
 }
-async function runToolMethod(method, toolName, rawArgs, context, hooks, lifecycle, coerceJson, onOutputStrip) {
+async function runToolMethod(method, toolName, rawArgs, context, hooks, lifecycle, coerceJson, onOutputStrip, extension) {
   const startedAt = Date.now();
+  let hookContext = context;
   const finish = async (result, thrown) => {
-    await hooks?.afterToolCall?.(toolName, rawArgs, result, Date.now() - startedAt, context, method, thrown);
+    await hooks?.afterToolCall?.({
+      toolName,
+      args: rawArgs,
+      result,
+      durationMs: Date.now() - startedAt,
+      context: hookContext,
+      endpoint: method,
+      ...thrown !== undefined && { error: thrown }
+    });
     return result;
   };
-  if (hooks?.beforeToolCall) {
+  let beforeRan = false;
+  const runBefore = async () => {
+    if (beforeRan || !hooks?.beforeToolCall)
+      return null;
+    beforeRan = true;
     try {
-      await hooks.beforeToolCall(toolName, rawArgs, context, method);
+      await hooks.beforeToolCall({
+        toolName,
+        args: rawArgs,
+        context: hookContext,
+        endpoint: method
+      });
+      return null;
     } catch (err) {
       return finish(toolResultFromError(err));
     }
+  };
+  const finishThrown = async (err) => {
+    const beforeFailure2 = await runBefore();
+    if (beforeFailure2)
+      return beforeFailure2;
+    if (hooks?.onToolError) {
+      try {
+        await hooks.onToolError({
+          toolName,
+          error: err,
+          context: hookContext,
+          endpoint: method
+        });
+      } catch (hookErr) {
+        console.error("[stitchkit] onToolError hook failed:", hookErr);
+      }
+    }
+    return finish(toolResultFromError(err), err);
+  };
+  let callArgs = rawArgs;
+  let callContext = context;
+  if (extension) {
+    const extensionKeys = new Set(Object.keys(extension.schema.shape));
+    const extensionArgs = Object.fromEntries(Object.entries(rawArgs).filter(([key]) => extensionKeys.has(key)));
+    let parsed;
+    try {
+      parsed = extension.schema.safeParse(extensionArgs);
+    } catch (err) {
+      return finishThrown(err);
+    }
+    if (!parsed.success) {
+      const beforeFailure2 = await runBefore();
+      if (beforeFailure2)
+        return beforeFailure2;
+      return finish({
+        ok: false,
+        code: "VALIDATION_ERROR",
+        details: { message: `Invalid tool extension: ${formatZodError(parsed.error)}` }
+      });
+    }
+    try {
+      const resolved = await extension.resolve({ ...rawArgs, ...parsed.data });
+      callContext = { ...context, ...resolved, source: context.source };
+      hookContext = callContext;
+      callArgs = Object.fromEntries(Object.entries(rawArgs).filter(([key]) => !extensionKeys.has(key)));
+    } catch (err) {
+      return finishThrown(err);
+    }
   }
+  const beforeFailure = await runBefore();
+  if (beforeFailure)
+    return beforeFailure;
   const paramKeys = new Set(objectShapeKeys(method.paramsSchema));
   let paramArgs = {};
   let inputArgs = {};
-  for (const [key, value] of Object.entries(rawArgs)) {
+  for (const [key, value] of Object.entries(callArgs)) {
     if (isUnsafeKey(key))
       continue;
     if (paramKeys.has(key))
@@ -482,7 +577,12 @@ async function runToolMethod(method, toolName, rawArgs, context, hooks, lifecycl
   }
   let params;
   if (method.paramsSchema) {
-    const result = method.paramsSchema.safeParse(paramArgs);
+    let result;
+    try {
+      result = method.paramsSchema.safeParse(paramArgs);
+    } catch (err) {
+      return finishThrown(err);
+    }
     if (!result.success) {
       return finish({
         ok: false,
@@ -494,7 +594,12 @@ async function runToolMethod(method, toolName, rawArgs, context, hooks, lifecycl
   }
   let input;
   if (method.inputSchema) {
-    const result = method.inputSchema.safeParse(inputArgs);
+    let result;
+    try {
+      result = method.inputSchema.safeParse(inputArgs);
+    } catch (err) {
+      return finishThrown(err);
+    }
     if (!result.success) {
       return finish({
         ok: false,
@@ -505,7 +610,12 @@ async function runToolMethod(method, toolName, rawArgs, context, hooks, lifecycl
     input = result.data;
   }
   try {
-    const ctx = { ...context, params, input, source: context.source };
+    const ctx = {
+      ...callContext,
+      params,
+      input,
+      source: context.source
+    };
     if (lifecycle?.beforeHandle) {
       await lifecycle.beforeHandle(ctx, method);
     }
@@ -529,14 +639,7 @@ async function runToolMethod(method, toolName, rawArgs, context, hooks, lifecycl
     const output = (data === undefined || data === null) && !method.outputSchema ? { status: "ok" } : data;
     return finish({ ok: true, data: output });
   } catch (err) {
-    if (hooks?.onToolError) {
-      try {
-        await hooks.onToolError(toolName, err, context, method);
-      } catch (hookErr) {
-        console.error("[stitchkit] onToolError hook failed:", hookErr);
-      }
-    }
-    return finish(toolResultFromError(err), err);
+    return finishThrown(err);
   }
 }
 
@@ -605,6 +708,121 @@ function assertUniqueToolName(name, taken, surface) {
   }
 }
 
+// src/tools/presentation.ts
+import { z as z3 } from "zod";
+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);
+}
+function rewriteLocalReferences(value, namespace) {
+  if (Array.isArray(value)) {
+    return value.map((child) => rewriteLocalReferences(child, namespace));
+  }
+  if (!isRecord(value))
+    return value;
+  const rewritten = {};
+  for (const [key, child] of Object.entries(value)) {
+    rewritten[key] = key === "$ref" && typeof child === "string" && child.startsWith("#") ? `#/definitions/${namespace}${child.slice(1)}` : rewriteLocalReferences(child, namespace);
+  }
+  return rewritten;
+}
+function namespaceLocalReferences(schema, namespace) {
+  if (!schema || !hasLocalReference(schema))
+    return schema;
+  const rewritten = rewriteLocalReferences(schema, namespace);
+  if (!isRecord(rewritten))
+    return schema;
+  return { ...rewritten, definitions: { [namespace]: rewritten } };
+}
+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 mergeObjectSchemas(left, right, rightOwnsUnknownKeys) {
+  const leftProperties = objectProperties(left);
+  const rightProperties = objectProperties(right);
+  if (!leftProperties || !rightProperties)
+    return { 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(z3.object(config.extendSchema), unrepresentable, flatten), "extend");
+    if (extra) {
+      presentation = mergeObjectSchemas(withoutDialect(extra), withoutDialect(presentation), true);
+    }
+  }
+  if (presentation.$schema === undefined) {
+    presentation = {
+      $schema: "http://json-schema.org/draft-07/schema#",
+      ...presentation
+    };
+  }
+  return freezeToolJsonSchema(presentation);
+}
+function isObjectPresentationSchema(schema) {
+  return schema.type === "object" && isRecord(schema.properties);
+}
+function presentationMetadata(schema) {
+  return withoutDialect(schema);
+}
+
 // src/tools/mount.ts
 function applyExtend(base, extra) {
   if (base instanceof z4.ZodObject) {
@@ -628,6 +846,8 @@ function collectTools(service, transport, config = {}) {
     }
     if (method.multipart)
       continue;
+    if (method.rawBody)
+      continue;
     if (method.rawResponse)
       continue;
     const name = method.toolName ?? toToolName(service.name, methodName);
@@ -637,22 +857,27 @@ function collectTools(service, transport, config = {}) {
       }
       assertToolName(name, service.name, methodName);
     }
-    const baseSchema = flattenUnionInput ? mergeSchemas(method.paramsSchema ? flattenUnionsDeep(method.paramsSchema) : undefined, method.inputSchema ? flattenUnionsDeep(method.inputSchema) : undefined) : mergeSchemas(method.paramsSchema, method.inputSchema);
     const shouldExtend = !!extend && (!extend.filter || extend.filter(service, method));
-    const schema = shouldExtend && extend ? applyExtend(baseSchema, extend.schema) : baseSchema;
-    tools.push({ method, name, schema, shouldExtend });
+    const baseArgumentSchema = mergeSchemas(method.paramsSchema, method.inputSchema);
+    const argumentSchema = shouldExtend && extend ? applyExtend(baseArgumentSchema, extend.schema) : baseArgumentSchema;
+    const presentationSchema = buildToolPresentationSchema({
+      paramsSchema: method.paramsSchema,
+      inputSchema: method.inputSchema,
+      extendSchema: shouldExtend ? extend?.schema : undefined,
+      flattenUnionInput,
+      unrepresentable: "any"
+    });
+    tools.push({ method, name, argumentSchema, presentationSchema, 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 = tool.shouldExtend && extendKeys ? Object.fromEntries(Object.entries(rawArgs).filter(([key]) => !extendKeys.has(key))) : rawArgs;
-    return executeToolMethod(tool.method, tool.name, cleanArgs, { ...config.context, ...extraContext, source: config.source }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true, config.onOutputStrip ? (paths) => config.onOutputStrip?.(tool.name, paths) : undefined);
+  const extension = config.extend ? {
+    schema: z4.object(config.extend.schema),
+    resolve: config.extend.resolve
+  } : undefined;
+  return async function runOneToolCall(tool, rawArgs) {
+    return executeToolMethod(tool.method, tool.name, rawArgs, { ...config.context, source: config.source }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true, config.onOutputStrip ? (paths) => config.onOutputStrip?.(tool.name, paths) : undefined, tool.shouldExtend ? extension : undefined);
   };
 }
 function formatToolError(result, toolName, errorHint) {
@@ -1224,7 +1449,7 @@ function renderCommandHelp(name, command, tool) {
   const lines = [tool.method.desc, "", `Usage: ${name} ${command} [args] [--flags]`, ""];
   let fields = [];
   try {
-    fields = jsonSchemaFields(toJsonSchema(tool.schema, "input"));
+    fields = jsonSchemaFields(tool.presentationSchema);
   } catch {
     lines.push("(arguments: pass a JSON object — this command has a complex schema)", "");
   }
@@ -1304,7 +1529,7 @@ async function createCli(config) {
 `);
     return exit(1);
   }
-  const { toolArgs, options } = parseCliArgs(commandArgv, tool.schema);
+  const { toolArgs, options } = parseCliArgs(commandArgv, tool.argumentSchema);
   if (options.help) {
     stdout(renderCommandHelp(config.name, command, tool));
     return exit(0);
@@ -1318,7 +1543,7 @@ async function createCli(config) {
   }
   const passthroughField = config.passthrough?.[command];
   if (passthroughField) {
-    collectPassthrough(toolArgs, passthroughField, objectShapeKeys(tool.schema));
+    collectPassthrough(toolArgs, passthroughField, objectShapeKeys(tool.argumentSchema));
   }
   if (options.dryRun) {
     stdout(`${JSON.stringify({ command, args: toolArgs }, null, 2)}
@@ -1364,11 +1589,7 @@ async function createCli(config) {
   return exit(exitCode);
 }
 function safeInputSchema(tool) {
-  try {
-    return toJsonSchema(tool.schema, "input");
-  } catch {
-    return {};
-  }
+  return tool.presentationSchema;
 }
 
-export { coerceJsonArgs, toolResultFromError, flattenDiscriminatedUnion, flattenUnionsDeep, assertToolName, assertUniqueToolName, collectTools, createToolRunner, formatToolError, fetchGuarded, readCapped, writeDownload, parseCliArgs, DEFAULT_EXIT_CODES, emitResult, pollUntil, pollUntilDone, createCli };
+export { coerceJsonArgs, toolResultFromError, executeToolMethod, assertToolName, assertUniqueToolName, flattenToolJsonSchema, buildToolPresentationSchema, isObjectPresentationSchema, presentationMetadata, collectTools, createToolRunner, formatToolError, fetchGuarded, readCapped, writeDownload, parseCliArgs, DEFAULT_EXIT_CODES, emitResult, pollUntil, pollUntilDone, createCli };