stitchkit 0.34.0 → 0.36.0

package/dist/cli.js

@@ -4,10 +4,10 @@ import {
   emitResult,
   parseCliArgs,
   pollUntilDone
-} from "./index-jr8vf7g8.js";
+} from "./index-kgga1n8d.js";
 import"./index-0ed3bx43.js";
 import"./index-x3fcszf8.js";
-import"./index-enc7t99e.js";
+import"./index-17rdjw68.js";
 export {
   pollUntilDone,
   parseCliArgs,

package/dist/{index-enc7t99e.js → index-17rdjw68.js}

@@ -192,4 +192,149 @@ function safeJsonParse(text) {
   return JSON.parse(text, (key, value) => isUnsafeKey(key) ? undefined : value);
 }
 
-export { __require, mergeMeta, AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, typedEntries, isRecord, bytesToBase64Url, base64UrlToBytes, formatZodError, zodIssues, errorCode, recordedErrorMessage, normalizeError, validateHandlerOutput, isUnsafeKey, safeJsonParse };
+// src/server/request.ts
+function generateTraceId() {
+  return `${Date.now().toString(36)}-${crypto.randomUUID().slice(0, 8)}`;
+}
+function resolveTraceId(req) {
+  const header = req.headers.get("x-request-id") ?? req.headers.get("x-trace-id");
+  const trimmed = header?.trim();
+  if (trimmed && trimmed.length <= 128 && /^[\w.-]+$/.test(trimmed)) {
+    return trimmed;
+  }
+  return generateTraceId();
+}
+function resolveSocketIp(req, server) {
+  if (typeof server === "object" && server !== null && "requestIP" in server && typeof server.requestIP === "function") {
+    const addr = server.requestIP(req);
+    if (isRecord(addr) && typeof addr.address === "string" && addr.address) {
+      return addr.address;
+    }
+  }
+  if ("ip" in req && typeof req.ip === "string" && req.ip)
+    return req.ip;
+  return;
+}
+function extractIp(req, options = {}) {
+  if (options.trustProxy) {
+    const forwarded = req.headers.get("x-forwarded-for");
+    if (forwarded)
+      return (forwarded.split(",")[0] ?? "").trim().replace(/^::ffff:/, "");
+    const realIp = req.headers.get("x-real-ip");
+    if (realIp)
+      return realIp.trim().replace(/^::ffff:/, "");
+  }
+  return (options.socketIp ?? "").replace(/^::ffff:/, "");
+}
+function getClientInfo(req, options = {}) {
+  return {
+    ipAddress: extractIp(req, options) || undefined,
+    userAgent: req.headers.get("user-agent") ?? undefined
+  };
+}
+function parseQueryParams(url) {
+  const query = {};
+  for (const key of new Set(url.searchParams.keys())) {
+    if (isUnsafeKey(key))
+      continue;
+    const values = url.searchParams.getAll(key);
+    const [first] = values;
+    query[key] = values.length === 1 && first !== undefined ? first : values;
+  }
+  return query;
+}
+
+// src/observability/trace.ts
+var TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/i;
+function randomHex(bytes) {
+  const arr = new Uint8Array(bytes);
+  crypto.getRandomValues(arr);
+  let hex = "";
+  for (const byte of arr)
+    hex += byte.toString(16).padStart(2, "0");
+  return hex;
+}
+function createTraceContext() {
+  return { traceId: randomHex(16), spanId: randomHex(8) };
+}
+function parseTraceparent(header) {
+  if (!header)
+    return null;
+  const match = TRACEPARENT_RE.exec(header.trim());
+  if (!match?.[1] || !match[2])
+    return null;
+  const traceId = match[1].toLowerCase();
+  const parentSpanId = match[2].toLowerCase();
+  if (/^0+$/.test(traceId) || /^0+$/.test(parentSpanId))
+    return null;
+  return { traceId, spanId: randomHex(8), parentSpanId };
+}
+function formatTraceparent(ctx) {
+  return `00-${ctx.traceId}-${ctx.spanId}-01`;
+}
+function resolveTraceContext(req) {
+  return parseTraceparent(req.headers.get("traceparent")) ?? createTraceContext();
+}
+function childSpan(parent) {
+  return {
+    traceId: parent.traceId,
+    spanId: randomHex(8),
+    parentSpanId: parent.spanId
+  };
+}
+
+// src/observability/context.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+var storage = new AsyncLocalStorage;
+function runWithRequestContext(ctx, fn) {
+  return storage.run(ctx, fn);
+}
+function getRequestContext() {
+  return storage.getStore();
+}
+function getTraceId() {
+  return storage.getStore()?.trace.traceId;
+}
+function getUserId() {
+  return storage.getStore()?.userId;
+}
+function setRequestUser(userId) {
+  const ctx = storage.getStore();
+  if (ctx)
+    ctx.userId = userId;
+}
+function setRequestEndpoint(serviceName, action) {
+  const ctx = storage.getStore();
+  if (ctx) {
+    ctx.serviceName = serviceName;
+    ctx.action = action;
+  }
+}
+function setRequestDimensions(dimensions) {
+  const ctx = storage.getStore();
+  if (ctx)
+    ctx.dimensions = { ...ctx.dimensions, ...dimensions };
+}
+function setRequestError(error) {
+  const ctx = storage.getStore();
+  if (ctx)
+    ctx.error = error;
+}
+function wrapInRequestContext(handler, options = {}) {
+  return (req, server) => {
+    const ctx = {
+      trace: resolveTraceContext(req),
+      source: "http",
+      method: req.method,
+      path: new URL(req.url, "http://localhost").pathname,
+      startedAt: process.hrtime.bigint(),
+      ...getClientInfo(req, {
+        trustProxy: options.trustProxy,
+        socketIp: resolveSocketIp(req, server)
+      })
+    };
+    return runWithRequestContext(ctx, () => handler(req, server));
+  };
+}
+
+export { __require, mergeMeta, AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, typedEntries, isRecord, bytesToBase64Url, base64UrlToBytes, formatZodError, zodIssues, errorCode, recordedErrorMessage, normalizeError, validateHandlerOutput, isUnsafeKey, safeJsonParse, generateTraceId, resolveTraceId, resolveSocketIp, extractIp, getClientInfo, parseQueryParams, createTraceContext, parseTraceparent, formatTraceparent, resolveTraceContext, childSpan, runWithRequestContext, getRequestContext, getTraceId, getUserId, setRequestUser, setRequestEndpoint, setRequestDimensions, setRequestError, wrapInRequestContext };

package/dist/{index-nmq59nae.js → index-bx49hskg.js}

@@ -6,7 +6,7 @@ import {
   isUnsafeKey,
   safeJsonParse,
   unauthorized
-} from "./index-enc7t99e.js";
+} from "./index-17rdjw68.js";
 
 // src/server/middleware/cookies.ts
 function parseCookies(header) {

package/dist/{index-k7ysesv0.js → index-dvrn81q4.js}

@@ -6,30 +6,28 @@ import {
 import {
   isWithinDir
 } from "./index-x3fcszf8.js";
-import {
-  extractIp,
-  getClientInfo,
-  getRequestContext,
-  parseQueryParams,
-  resolveSocketIp,
-  resolveTraceId,
-  setRequestEndpoint,
-  setRequestError
-} from "./index-wya8bkme.js";
 import {
   AppError,
   __require,
   badRequest,
   errorCode,
+  extractIp,
+  getClientInfo,
+  getRequestContext,
   isRecord,
   isUnsafeKey,
   mergeMeta,
   normalizeError,
+  parseQueryParams,
   recordedErrorMessage,
+  resolveSocketIp,
+  resolveTraceId,
   safeJsonParse,
+  setRequestEndpoint,
+  setRequestError,
   typedEntries,
   validateHandlerOutput
-} from "./index-enc7t99e.js";
+} from "./index-17rdjw68.js";
 
 // src/server/multipart.ts
 var DEFAULT_MAX_UPLOAD_BYTES = 25 * 1024 * 1024;

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

@@ -7,12 +7,14 @@ import {
 } from "./index-x3fcszf8.js";
 import {
   formatZodError,
+  getRequestContext,
   isRecord,
   isUnsafeKey,
   normalizeError,
+  runWithRequestContext,
   safeJsonParse,
   validateHandlerOutput
-} from "./index-enc7t99e.js";
+} from "./index-17rdjw68.js";
 
 // src/tools/coerce.ts
 import { z } from "zod";
@@ -229,30 +231,97 @@ function stripAnnotations(node) {
       stripAnnotations(value);
   }
 }
-function hasChecks(schema) {
+function hasInvisibleConstraint(schema) {
   if (!(schema instanceof z3.ZodType))
     return false;
   const def = schema.def;
-  if (isRecord(def) && Array.isArray(def.checks) && def.checks.length > 0)
+  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 hasChecks(schema.unwrap());
+    return hasInvisibleConstraint(schema.unwrap());
   }
   if (schema instanceof z3.ZodPipe)
-    return hasChecks(schema.def.in) || hasChecks(schema.def.out);
-  if (schema instanceof z3.ZodObject)
-    return Object.values(schema.shape).some(hasChecks);
+    return true;
+  if (schema instanceof z3.ZodObject) {
+    return Object.values(schema.shape).some(hasInvisibleConstraint);
+  }
   if (schema instanceof z3.ZodArray)
-    return hasChecks(schema.element);
+    return hasInvisibleConstraint(schema.element);
   if (schema instanceof z3.ZodUnion)
-    return schema.def.options.some(hasChecks);
+    return schema.def.options.some(hasInvisibleConstraint);
   if (schema instanceof z3.ZodRecord)
-    return hasChecks(schema.valueType);
+    return hasInvisibleConstraint(schema.valueType);
   if (schema instanceof z3.ZodIntersection) {
-    return hasChecks(schema.def.left) || hasChecks(schema.def.right);
+    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 "{}";
@@ -272,7 +341,17 @@ function mergeCollidingFields(schemas) {
   if (values.length <= 1) {
     if (only === undefined)
       return z3.unknown();
-    return schemas.length > 1 && hasChecks(only) ? z3.unknown() : only;
+    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;
@@ -286,9 +365,19 @@ function mergeCollidingFields(schemas) {
   }
   if (allEnum) {
     const uniq = [...new Set(merged)];
-    const [first, ...rest] = uniq;
-    if (first !== undefined)
-      return z3.enum([first, ...rest]);
+    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();
 }
@@ -347,6 +436,23 @@ function toolResultFromError(err) {
   };
 }
 async function executeToolMethod(method, toolName, rawArgs, context, hooks, lifecycle, coerceJson = false, onOutputStrip) {
+  const parent = getRequestContext();
+  if (!parent) {
+    return runToolMethod(method, toolName, rawArgs, context, hooks, lifecycle, coerceJson, onOutputStrip);
+  }
+  return runWithRequestContext({
+    ...parent,
+    trace: parent.trace,
+    dimensions: parent.dimensions ? { ...parent.dimensions } : undefined,
+    error: undefined,
+    source: context.source,
+    method: "TOOL",
+    path: `/${context.source}/${toolName}`,
+    serviceName: method.serviceName,
+    action: method.key
+  }, () => runToolMethod(method, toolName, rawArgs, context, hooks, lifecycle, coerceJson, onOutputStrip));
+}
+async function runToolMethod(method, toolName, rawArgs, context, hooks, lifecycle, coerceJson, onOutputStrip) {
   const startedAt = Date.now();
   const finish = async (result, thrown) => {
     await hooks?.afterToolCall?.(toolName, rawArgs, result, Date.now() - startedAt, context, method, thrown);

package/dist/node.js

@@ -3,10 +3,9 @@ import {
   createImplement,
   createSocketIOServer,
   implement
-} from "./index-k7ysesv0.js";
+} from "./index-dvrn81q4.js";
 import"./index-czmqks7r.js";
 import"./index-x3fcszf8.js";
-import"./index-wya8bkme.js";
 import {
   AppError,
   appError,
@@ -16,7 +15,7 @@ import {
   notFound,
   rateLimited,
   unauthorized
-} from "./index-enc7t99e.js";
+} from "./index-17rdjw68.js";
 // src/server/node.ts
 import { serve } from "srvx";
 async function serveNode(config) {

package/dist/observability/index.js

@@ -5,7 +5,10 @@ import {
   getRequestContext,
   getTraceId,
   getUserId,
+  isRecord,
+  isUnsafeKey,
   parseTraceparent,
+  recordedErrorMessage,
   resolveTraceContext,
   runWithRequestContext,
   setRequestDimensions,
@@ -13,12 +16,7 @@ import {
   setRequestError,
   setRequestUser,
   wrapInRequestContext
-} from "../index-wya8bkme.js";
-import {
-  isRecord,
-  isUnsafeKey,
-  recordedErrorMessage
-} from "../index-enc7t99e.js";
+} from "../index-17rdjw68.js";
 
 // src/observability/sanitize.ts
 var DEFAULT_SENSITIVE_KEYS = /(password|passwd|pwd|secret|token|apikey|api[-_ ]?key|auth|authorization|bearer|session|cookie|init[-_ ]?data|credential|private[-_ ]?key)/i;

package/dist/server/index.js

@@ -10,7 +10,7 @@ import {
   socketIoLane,
   staticRoute,
   webSocketLane
-} from "../index-k7ysesv0.js";
+} from "../index-dvrn81q4.js";
 import {
   createAuthHook,
   createBearerResolver,
@@ -23,7 +23,7 @@ import {
   signJwt,
   verifyJwt,
   verifyPkce
-} from "../index-nmq59nae.js";
+} from "../index-bx49hskg.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS,
   DEFAULT_CORS_EXPOSE_HEADERS,
@@ -37,14 +37,6 @@ import {
 import {
   isWithinDir
 } from "../index-x3fcszf8.js";
-import {
-  extractIp,
-  generateTraceId,
-  getClientInfo,
-  getTraceId,
-  resolveSocketIp,
-  resolveTraceId
-} from "../index-wya8bkme.js";
 import {
   AppError,
   STITCH_ERROR_STATUS,
@@ -52,16 +44,22 @@ import {
   badRequest,
   conflict,
   errorCode,
+  extractIp,
   forbidden,
   formatZodError,
+  generateTraceId,
+  getClientInfo,
+  getTraceId,
   isRecord,
   isStitchErrorCode,
   normalizeError,
   notFound,
   rateLimited,
+  resolveSocketIp,
+  resolveTraceId,
   unauthorized,
   zodIssues
-} from "../index-enc7t99e.js";
+} from "../index-17rdjw68.js";
 // src/server/swept-map.ts
 function createSweptMap(options) {
   const store = new Map;

package/dist/tools/execute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/tools/execute.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC3B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,eAAe,CAAC;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,CACf,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,SAAS,KAChB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,CACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,SAAS,EACnB,KAAK,CAAC,EAAE,OAAO,KACZ,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,WAAW,CAAC,EAAE,CACZ,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,SAAS,KAChB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;AAEjF;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClF,0DAA0D;IAC1D,WAAW,CAAC,EAAE,CACZ,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,SAAS,KAChB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAQpF;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,eAAe,EACxB,KAAK,CAAC,EAAE,aAAa,EACrB,SAAS,CAAC,EAAE,aAAa,EACzB,UAAU,UAAQ,EAClB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,GACxC,OAAO,CAAC,UAAU,CAAC,CAwIrB"}
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/tools/execute.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAInE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC3B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,eAAe,CAAC;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,CACf,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,SAAS,KAChB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,CACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,SAAS,EACnB,KAAK,CAAC,EAAE,OAAO,KACZ,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,WAAW,CAAC,EAAE,CACZ,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,SAAS,KAChB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;AAEjF;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClF,0DAA0D;IAC1D,WAAW,CAAC,EAAE,CACZ,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,SAAS,KAChB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAQpF;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,eAAe,EACxB,KAAK,CAAC,EAAE,aAAa,EACrB,SAAS,CAAC,EAAE,aAAa,EACzB,UAAU,UAAQ,EAClB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,GACxC,OAAO,CAAC,UAAU,CAAC,CAuDrB"}

package/dist/tools/flatten.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../../src/tools/flatten.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,CAAC,CAAC,qBAAqB,GAC7B,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAiD5B;AAsKD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,OAAO,CAqDpE"}
+{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../../src/tools/flatten.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,CAAC,CAAC,qBAAqB,GAC7B,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAiD5B;AA6TD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,OAAO,CAqDpE"}

package/dist/tools/mcp.d.ts

@@ -48,6 +48,15 @@ export interface McpMountConfig {
 export declare function validateMcpSchemas(services: ServiceDef[], onIncompatibleSchema?: IncompatibleSchemaPolicy, logger?: StitchLogger, options?: {
     extend?: ToolExtend;
     flattenUnionInput?: boolean;
+    /**
+     * Also fail a tool whose advertised schema has a property with no type
+     * information — nothing for a model to obey. Off by default because a
+     * contract may legitimately declare `z.unknown()`; `allowUntyped` lists the
+     * dotted paths that are deliberate, and anything else is a finding. → ADR 0044.
+     */
+    requireTypedProperties?: boolean;
+    /** Dotted paths (`tool.property`) that are deliberately unconstrained. */
+    allowUntyped?: readonly string[];
 }): void;
 export declare function mountMcp(mcpServer: McpServer, services: ServiceDef | ServiceDef[], config?: McpMountConfig): void;
 /**

package/dist/tools/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/tools/mcp.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/tools/mcp.ts"],"names":[],"mappings":"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"}

package/dist/tools/untyped-properties.d.ts

@@ -0,0 +1,17 @@
+/** One property the model would be shown with no idea what it is. */
+export interface UntypedProperty {
+    /** Dotted path from the tool's argument root, e.g. `operations.partIndex`. */
+    path: string;
+    /** Its `description`, when it has one — usually the only clue present. */
+    description?: string;
+}
+/**
+ * Every property in a JSON Schema that carries no type information, deep.
+ *
+ * Walks `properties`, `items`, `additionalProperties`, `$defs` / `definitions`
+ * and the `allOf` / `anyOf` / `oneOf` branches — an intersection root emits
+ * `allOf` with no root `properties` at all, so reading the top level alone would
+ * inspect nothing and pass.
+ */
+export declare function findUntypedProperties(schema: unknown, prefix?: string): UntypedProperty[];
+//# sourceMappingURL=untyped-properties.d.ts.map

package/dist/tools/untyped-properties.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"untyped-properties.d.ts","sourceRoot":"","sources":["../../src/tools/untyped-properties.ts"],"names":[],"mappings":"AAkBA,qEAAqE;AACrE,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AASD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,SAAK,GAAG,eAAe,EAAE,CA+DrF"}

package/dist/tools.d.ts

@@ -22,5 +22,6 @@ export { type ImplementRemoteOptions, implementRemote } from './tools/remote';
 export { createToolLogger, type ToolCallRecord, type ToolLoggerConfig, } from './tools/tool-logger';
 export { createToolkit, type Toolkit } from './tools/toolkit';
 export { summarizeTransports, type TransportCounts, type TransportSummary, } from './tools/transports';
+export { findUntypedProperties, type UntypedProperty } from './tools/untyped-properties';
 export { type McpAnnotations, type McpMediaContent, mountViewFile, resolveMedia, type ViewFileOptions, } from './tools/view-file';
 //# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,YAAY,EACV,WAAW,EACX,eAAe,EACf,aAAa,EACb,aAAa,EACb,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EACL,cAAc,EACd,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,QAAQ,EACR,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,EACL,KAAK,kBAAkB,EACvB,YAAY,EACZ,KAAK,aAAa,EAClB,KAAK,UAAU,GAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,kBAAkB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,KAAK,uBAAuB,EAC5B,4BAA4B,EAC5B,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,gBAAgB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,KAAK,sBAAsB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,EACL,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EACL,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,aAAa,EACb,YAAY,EACZ,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,YAAY,EACV,WAAW,EACX,eAAe,EACf,aAAa,EACb,aAAa,EACb,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EACL,cAAc,EACd,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,QAAQ,EACR,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,EACL,KAAK,kBAAkB,EACvB,YAAY,EACZ,KAAK,aAAa,EAClB,KAAK,UAAU,GAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,kBAAkB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,KAAK,uBAAuB,EAC5B,4BAA4B,EAC5B,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,gBAAgB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,KAAK,sBAAsB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,EACL,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EACL,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,4BAA4B,CAAC;AACzF,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,aAAa,EACb,YAAY,EACZ,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC"}

package/dist/tools.js

@@ -2,7 +2,7 @@ import {
   inputIsQuery,
   signJwt,
   verifyPkce
-} from "./index-nmq59nae.js";
+} from "./index-bx49hskg.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS
 } from "./index-czmqks7r.js";
@@ -21,22 +21,20 @@ import {
   readCapped,
   toolResultFromError,
   writeDownload
-} from "./index-jr8vf7g8.js";
+} from "./index-kgga1n8d.js";
 import {
   toJsonSchema
 } from "./index-0ed3bx43.js";
 import {
   isWithinDir
 } from "./index-x3fcszf8.js";
-import {
-  getTraceId
-} from "./index-wya8bkme.js";
 import {
   AppError,
+  getTraceId,
   isRecord,
   mergeMeta,
   typedEntries
-} from "./index-enc7t99e.js";
+} from "./index-17rdjw68.js";
 
 // src/tools/agent.ts
 import { tool, zodSchema } from "ai";
@@ -139,6 +137,77 @@ function inlineMcpAppBundle(html) {
   return html.replace(EXT_APPS_BUNDLE_PLACEHOLDER, () => bundle);
 }
 
+// src/tools/untyped-properties.ts
+var TYPE_KEYWORDS = ["type", "enum", "const", "anyOf", "oneOf", "allOf", "$ref", "not"];
+function saysWhatItIs(schema) {
+  return TYPE_KEYWORDS.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/mcp.ts
 function textBlock(text) {
   return [{ type: "text", text }];
@@ -187,7 +256,7 @@ function reportIncompatible(message, policy, logger, failures) {
 }
 function throwIfFailures(failures) {
   if (failures.length > 0) {
-    throw new Error(`[stitchkit] ${failures.length} MCP tool(s) have an incompatible schema:
+    throw new Error(`[stitchkit] ${failures.length} problem(s) with MCP tool schemas:
  - ${failures.join(`
  - `)}`);
   }
@@ -217,9 +286,19 @@ function prepareMcpTool(mountable, policy, logger, failures, seen) {
 function validateMcpSchemas(services, onIncompatibleSchema = "throw", logger, options) {
   const seen = new Set;
   const failures = [];
+  const allowed = new Set(options?.allowUntyped ?? []);
   for (const service of services) {
     for (const mountable of collectTools(service, "MCP", options)) {
-      prepareMcpTool(mountable, onIncompatibleSchema, logger, failures, seen);
+      const prepared = prepareMcpTool(mountable, onIncompatibleSchema, logger, failures, seen);
+      if (!prepared || !options?.requireTypedProperties)
+        continue;
+      for (const untyped of findUntypedProperties(toJsonSchema(mountable.schema, "input"))) {
+        const path = `${mountable.name}.${untyped.path}`;
+        if (allowed.has(path))
+          continue;
+        const clue = untyped.description ? ` (only a description: "${untyped.description}")` : "";
+        reportIncompatible(`MCP tool "${mountable.name}" — property "${untyped.path}" carries no type, enum or $ref${clue}. ` + "A model is given no way to know what to send. Widen the contract, or list it in `allowUntyped` if it is deliberately free-form.", onIncompatibleSchema === "skip" ? "warn" : onIncompatibleSchema, logger, failures);
+      }
     }
   }
   throwIfFailures(failures);
@@ -1410,6 +1489,7 @@ export {
   implementRemote,
   flattenUnionsDeep,
   flattenDiscriminatedUnion,
+  findUntypedProperties,
   createToolkit,
   createToolLogger,
   createStdioMcpServer,

package/llms-full.txt

@@ -1524,6 +1524,30 @@ cannot become a tool. `onIncompatibleSchema` decides what happens:
 `validateMcpSchemas(services)` runs the same check on its own — useful in a
 startup assertion or a test.
 
+#### Is every property actually usable by a model?
+
+A tool schema is the only instruction a model gets about the shape of its
+arguments. A property that carries a `description` and no `type` / `enum` /
+`anyOf` / `$ref` tells it nothing — and nothing fails: the schema converts, the
+mount succeeds, the tool is advertised, and the model then guesses, retrying the
+same wrong guess because the error does not say what the right one would be.
+
+```ts
+validateMcpSchemas(services, 'throw', logger, {
+  flattenUnionInput: true,          // mirror the live mount
+  requireTypedProperties: true,
+  allowUntyped: ['docs_create.payload'],   // deliberately free-form
+})
+```
+
+Off by default, because a contract may legitimately declare `z.unknown()`.
+`allowUntyped` takes dotted `tool.property` paths — an entry there is a decision,
+anything else is a finding. Pass the **same** `extend` / `flattenUnionInput` the
+mount uses, or the check vets a different document than the one advertised.
+
+`findUntypedProperties(jsonSchema)` is the same walk, exported on its own if you
+want to assert on a schema you built elsewhere.
+
 ### Discriminated unions for weaker models — `flattenUnionInput`
 
 A discriminated union in a tool's input becomes a JSON Schema `oneOf` / `anyOf`.
@@ -1533,6 +1557,15 @@ the field or mangle its strings. Set `flattenUnionInput: true` (on
 union as a **single flat object** instead — the discriminator becomes an enum and
 each variant's fields become optional with a `Required if <disc> = …` hint.
 
+**A field several variants declare keeps its type.** Flattening puts every
+variant's fields side by side, so a key two variants share has to be advertised
+as one thing. Where they agree, that is what you get; where they disagree — a
+`.refine()` only one of them carries, two different bounds on the same number, an
+enum against a free string — the *constraint* is dropped and the **type** is not.
+A field that is a number in every variant is advertised as a number, not as a
+bare description. Only genuinely different kinds (a string in one variant, a
+number in another) fall back to unconstrained. → ADR 0044
+
 It is **deep**: unions are flattened at every depth — top level, object fields,
 array items, and through `optional` / `nullable` / `default` / intersection
 wrappers — so no `oneOf` survives anywhere (e.g. a `content.parts[]` that is an
@@ -2879,6 +2912,8 @@ import {
 } from 'stitchkit/observability'
 
 createAuthHook({ /* … */ inject: (ctx, user) => user && setRequestUser(user.id) })
+// ↑ on the HTTP path. Inside a tool call this writes to that call's own context
+//   (→ ADR 0045); a tool row takes its identity from the mount's `context`.
 // only to override what the framework already recorded — see below:
 setRequestError({ code: err.code, message: err.message, details: err.issues })
 ```
@@ -2907,6 +2942,12 @@ meaning to (→ ADR 0021). Resolve it cheaply from `ctx.params` / headers in
 `ctx.req` are available there) and it lands on `event.dimensions` for the request
 either way, so your sink reads it as a column instead of re-parsing the path:
 
+> **On the tool path it lands on that call's own event, not the request's.** The
+> same hooks object is assignable to `ToolLifecycle`, so this recipe is the one
+> people apply to tools — and since ADR 0045 each tool call runs in its own
+> context. Read the value off the tool row (`event.toolName != null`); both rows
+> carry the same `traceId`.
+
 ```ts
 // beforeHandle (success) and onError (failure) alike:
 const projectId = ctx.req?.headers.get('x-project') ?? String(ctx.params?.projectId ?? '')
@@ -3103,10 +3144,10 @@ object must stay assignable to `ToolLifecycle`.)
 which `createAuditHook`'s **tool** row does not read: a tool event takes
 `errorCode` / `errorMessage` / `errorDetail` from the `ToolResult`, and only
 identity and `dimensions` from the context. Calling it in `onToolError` would
-leave the tool row exactly as scrubbed as before — and for MCP over HTTP it would
-also write the cause into the log line of the enclosing `/mcp` request, turning
-one incident into two records. It is right for the **HTTP** path, where the
-request *is* the record.
+leave the tool row exactly as scrubbed as before. It is right for the **HTTP**
+path, where the request *is* the record. (Since ADR 0045 a tool call runs in its
+own context, so it can no longer write into the enclosing `/mcp` request's row
+either — the call is simply not where that helper belongs.)
 
 ### One row that names the cause
 
@@ -3921,6 +3962,8 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `ViewFileOptions` | _type_ | options for `mountViewFile` |
 | `McpAnnotations` | _type_ | MCP annotations on a media result |
 | `CollectToolsConfig` | _type_ | options for `collectTools` |
+| `findUntypedProperties` | function | every property in a JSON Schema with no `type`/`enum`/`$ref` — what a model is shown and cannot obey ([guide](../guide/mcp-and-agents.md)) |
+| `UntypedProperty` | _type_ | one such property — `{ path, description? }` |
 | `ToolNameEntry` | _type_ | one `listToolNames` row — `{ name, service, method, transports }` |
 | `IncompatibleSchemaPolicy` | _type_ | `'throw' \| 'skip' \| 'warn'` |
 | `McpMediaContent` | _type_ | a multimodal MCP content item |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",

package/dist/index-wya8bkme.js

@@ -1,151 +0,0 @@
-import {
-  isRecord,
-  isUnsafeKey
-} from "./index-enc7t99e.js";
-
-// src/server/request.ts
-function generateTraceId() {
-  return `${Date.now().toString(36)}-${crypto.randomUUID().slice(0, 8)}`;
-}
-function resolveTraceId(req) {
-  const header = req.headers.get("x-request-id") ?? req.headers.get("x-trace-id");
-  const trimmed = header?.trim();
-  if (trimmed && trimmed.length <= 128 && /^[\w.-]+$/.test(trimmed)) {
-    return trimmed;
-  }
-  return generateTraceId();
-}
-function resolveSocketIp(req, server) {
-  if (typeof server === "object" && server !== null && "requestIP" in server && typeof server.requestIP === "function") {
-    const addr = server.requestIP(req);
-    if (isRecord(addr) && typeof addr.address === "string" && addr.address) {
-      return addr.address;
-    }
-  }
-  if ("ip" in req && typeof req.ip === "string" && req.ip)
-    return req.ip;
-  return;
-}
-function extractIp(req, options = {}) {
-  if (options.trustProxy) {
-    const forwarded = req.headers.get("x-forwarded-for");
-    if (forwarded)
-      return (forwarded.split(",")[0] ?? "").trim().replace(/^::ffff:/, "");
-    const realIp = req.headers.get("x-real-ip");
-    if (realIp)
-      return realIp.trim().replace(/^::ffff:/, "");
-  }
-  return (options.socketIp ?? "").replace(/^::ffff:/, "");
-}
-function getClientInfo(req, options = {}) {
-  return {
-    ipAddress: extractIp(req, options) || undefined,
-    userAgent: req.headers.get("user-agent") ?? undefined
-  };
-}
-function parseQueryParams(url) {
-  const query = {};
-  for (const key of new Set(url.searchParams.keys())) {
-    if (isUnsafeKey(key))
-      continue;
-    const values = url.searchParams.getAll(key);
-    const [first] = values;
-    query[key] = values.length === 1 && first !== undefined ? first : values;
-  }
-  return query;
-}
-
-// src/observability/trace.ts
-var TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/i;
-function randomHex(bytes) {
-  const arr = new Uint8Array(bytes);
-  crypto.getRandomValues(arr);
-  let hex = "";
-  for (const byte of arr)
-    hex += byte.toString(16).padStart(2, "0");
-  return hex;
-}
-function createTraceContext() {
-  return { traceId: randomHex(16), spanId: randomHex(8) };
-}
-function parseTraceparent(header) {
-  if (!header)
-    return null;
-  const match = TRACEPARENT_RE.exec(header.trim());
-  if (!match?.[1] || !match[2])
-    return null;
-  const traceId = match[1].toLowerCase();
-  const parentSpanId = match[2].toLowerCase();
-  if (/^0+$/.test(traceId) || /^0+$/.test(parentSpanId))
-    return null;
-  return { traceId, spanId: randomHex(8), parentSpanId };
-}
-function formatTraceparent(ctx) {
-  return `00-${ctx.traceId}-${ctx.spanId}-01`;
-}
-function resolveTraceContext(req) {
-  return parseTraceparent(req.headers.get("traceparent")) ?? createTraceContext();
-}
-function childSpan(parent) {
-  return {
-    traceId: parent.traceId,
-    spanId: randomHex(8),
-    parentSpanId: parent.spanId
-  };
-}
-
-// src/observability/context.ts
-import { AsyncLocalStorage } from "node:async_hooks";
-var storage = new AsyncLocalStorage;
-function runWithRequestContext(ctx, fn) {
-  return storage.run(ctx, fn);
-}
-function getRequestContext() {
-  return storage.getStore();
-}
-function getTraceId() {
-  return storage.getStore()?.trace.traceId;
-}
-function getUserId() {
-  return storage.getStore()?.userId;
-}
-function setRequestUser(userId) {
-  const ctx = storage.getStore();
-  if (ctx)
-    ctx.userId = userId;
-}
-function setRequestEndpoint(serviceName, action) {
-  const ctx = storage.getStore();
-  if (ctx) {
-    ctx.serviceName = serviceName;
-    ctx.action = action;
-  }
-}
-function setRequestDimensions(dimensions) {
-  const ctx = storage.getStore();
-  if (ctx)
-    ctx.dimensions = { ...ctx.dimensions, ...dimensions };
-}
-function setRequestError(error) {
-  const ctx = storage.getStore();
-  if (ctx)
-    ctx.error = error;
-}
-function wrapInRequestContext(handler, options = {}) {
-  return (req, server) => {
-    const ctx = {
-      trace: resolveTraceContext(req),
-      source: "http",
-      method: req.method,
-      path: new URL(req.url, "http://localhost").pathname,
-      startedAt: process.hrtime.bigint(),
-      ...getClientInfo(req, {
-        trustProxy: options.trustProxy,
-        socketIp: resolveSocketIp(req, server)
-      })
-    };
-    return runWithRequestContext(ctx, () => handler(req, server));
-  };
-}
-
-export { generateTraceId, resolveTraceId, resolveSocketIp, extractIp, getClientInfo, parseQueryParams, createTraceContext, parseTraceparent, formatTraceparent, resolveTraceContext, childSpan, runWithRequestContext, getRequestContext, getTraceId, getUserId, setRequestUser, setRequestEndpoint, setRequestDimensions, setRequestError, wrapInRequestContext };