stitchkit 0.31.0 → 0.33.0

package/dist/cli.js

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

package/dist/{index-zza375qp.js → index-enc7t99e.js}

@@ -1,6 +1,5 @@
-import {
-  isRecord
-} from "./index-c7nyw0yt.js";
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/contract/errors.ts
 var APP_ERROR_BRAND = Symbol.for("stitchkit.AppError");
@@ -77,6 +76,13 @@ function mergeMeta(contractMeta, endpointMeta) {
     return { ...contractMeta };
   return { ...contractMeta, ...endpointMeta };
 }
+// src/internal/typed.ts
+function typedEntries(value) {
+  return Object.entries(value);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 // src/contract/pagination.ts
 import { z } from "zod";
 
@@ -123,6 +129,15 @@ function errorCode(err) {
     return "VALIDATION_ERROR";
   return;
 }
+function recordedErrorMessage(code, envelopeMessage, thrown) {
+  if (code === "INTERNAL_SERVER_ERROR" && thrown !== undefined) {
+    if (thrown instanceof Error)
+      return thrown.message;
+    if (typeof thrown === "string")
+      return thrown;
+  }
+  return envelopeMessage;
+}
 function normalizeError(err) {
   if (AppError.is(err))
     return err;
@@ -169,11 +184,12 @@ function validateHandlerOutput(schema, data, onStripped) {
   };
 }
 
-// src/internal/within-dir.ts
-import { sep } from "node:path";
-function isWithinDir(root, target) {
-  const base = root.endsWith(sep) ? root.slice(0, -sep.length) : root;
-  return target === root || target === base || target.startsWith(base + sep);
+// src/internal/safe-json.ts
+function isUnsafeKey(key) {
+  return key === "__proto__";
+}
+function safeJsonParse(text) {
+  return JSON.parse(text, (key, value) => isUnsafeKey(key) ? undefined : value);
 }
 
-export { mergeMeta, AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, bytesToBase64Url, base64UrlToBytes, formatZodError, zodIssues, errorCode, normalizeError, validateHandlerOutput, isWithinDir };
+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 };

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

@@ -3,16 +3,16 @@ import {
   toJsonSchema
 } from "./index-0ed3bx43.js";
 import {
-  formatZodError,
-  isWithinDir,
-  normalizeError,
-  validateHandlerOutput
-} from "./index-zza375qp.js";
+  isWithinDir
+} from "./index-x3fcszf8.js";
 import {
+  formatZodError,
   isRecord,
   isUnsafeKey,
-  safeJsonParse
-} from "./index-c7nyw0yt.js";
+  normalizeError,
+  safeJsonParse,
+  validateHandlerOutput
+} from "./index-enc7t99e.js";
 
 // src/tools/coerce.ts
 import { z } from "zod";
@@ -348,8 +348,8 @@ function toolResultFromError(err) {
 }
 async function executeToolMethod(method, toolName, rawArgs, context, hooks, lifecycle, coerceJson = false, onOutputStrip) {
   const startedAt = Date.now();
-  const finish = async (result) => {
-    await hooks?.afterToolCall?.(toolName, rawArgs, result, Date.now() - startedAt, context, method);
+  const finish = async (result, thrown) => {
+    await hooks?.afterToolCall?.(toolName, rawArgs, result, Date.now() - startedAt, context, method, thrown);
     return result;
   };
   if (hooks?.beforeToolCall) {
@@ -430,7 +430,7 @@ async function executeToolMethod(method, toolName, rawArgs, context, hooks, life
         console.error("[stitchkit] onToolError hook failed:", hookErr);
       }
     }
-    return finish(toolResultFromError(err));
+    return finish(toolResultFromError(err), err);
   }
 }
 

package/dist/{index-3hsagjqf.js → index-k7ysesv0.js}

@@ -4,14 +4,8 @@ import {
   corsPreflightResponse
 } from "./index-czmqks7r.js";
 import {
-  AppError,
-  badRequest,
-  errorCode,
-  isWithinDir,
-  mergeMeta,
-  normalizeError,
-  validateHandlerOutput
-} from "./index-zza375qp.js";
+  isWithinDir
+} from "./index-x3fcszf8.js";
 import {
   extractIp,
   getClientInfo,
@@ -19,15 +13,23 @@ import {
   parseQueryParams,
   resolveSocketIp,
   resolveTraceId,
-  setRequestEndpoint
-} from "./index-9g9d6r1h.js";
+  setRequestEndpoint,
+  setRequestError
+} from "./index-wya8bkme.js";
 import {
+  AppError,
   __require,
+  badRequest,
+  errorCode,
   isRecord,
   isUnsafeKey,
+  mergeMeta,
+  normalizeError,
+  recordedErrorMessage,
   safeJsonParse,
-  typedEntries
-} from "./index-c7nyw0yt.js";
+  typedEntries,
+  validateHandlerOutput
+} from "./index-enc7t99e.js";
 
 // src/server/multipart.ts
 var DEFAULT_MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
@@ -646,10 +648,22 @@ function createHandler(config) {
       } catch {}
     };
     const respondError = async (err, errCtx, endpoint) => {
+      const recordFailure = (normalized) => {
+        if (getRequestContext()?.error !== undefined)
+          return;
+        const known = AppError.is(err) ? err : normalized;
+        const code = known?.code ?? errorCode(err) ?? "INTERNAL_SERVER_ERROR";
+        setRequestError({
+          code,
+          message: recordedErrorMessage(code, known?.message, err),
+          details: known?.details
+        });
+      };
       if (hooks?.onError) {
         try {
           const response = await hooks.onError(errCtx ?? buildErrorContext(req, url, traceId, clientIp), err, endpoint);
           if (response instanceof Response) {
+            recordFailure();
             const withCors = applyCors(response, cors, req);
             logDone(withCors.status, errorCode(err));
             return withCors;
@@ -657,6 +671,7 @@ function createHandler(config) {
         } catch {}
       }
       const appErr = normalizeError(err);
+      recordFailure(appErr);
       logDone(appErr.status, appErr.code);
       return json(appErr.toJSON(), appErr.status, cors, req);
     };

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

@@ -2,13 +2,11 @@ import {
   base64UrlToBytes,
   bytesToBase64Url,
   forbidden,
-  unauthorized
-} from "./index-zza375qp.js";
-import {
   isRecord,
   isUnsafeKey,
-  safeJsonParse
-} from "./index-c7nyw0yt.js";
+  safeJsonParse,
+  unauthorized
+} from "./index-enc7t99e.js";
 
 // src/server/middleware/cookies.ts
 function parseCookies(header) {

package/dist/{index-9g9d6r1h.js → index-wya8bkme.js}

@@ -1,7 +1,7 @@
 import {
   isRecord,
   isUnsafeKey
-} from "./index-c7nyw0yt.js";
+} from "./index-enc7t99e.js";
 
 // src/server/request.ts
 function generateTraceId() {

package/dist/index-x3fcszf8.js

@@ -0,0 +1,8 @@
+// src/internal/within-dir.ts
+import { sep } from "node:path";
+function isWithinDir(root, target) {
+  const base = root.endsWith(sep) ? root.slice(0, -sep.length) : root;
+  return target === root || target === base || target.startsWith(base + sep);
+}
+
+export { isWithinDir };

package/dist/internal/errors.d.ts

@@ -24,6 +24,21 @@ export declare function zodIssues(error: z.ZodError): ZodIssueSummary[];
  * produced elsewhere — a custom `onError` hook that returns its own `Response`.
  */
 export declare function errorCode(err: unknown): string | undefined;
+/**
+ * The message a **server-side record** should carry for a failure — an audit
+ * row, not a response.
+ *
+ * Normally the envelope's: it is truthful for an `AppError` or a `ZodError`, and
+ * it is what the caller was told, so the record and the response agree. The
+ * exception is the scrubbed one — an unexpected throw becomes
+ * `INTERNAL_SERVER_ERROR` / "Internal server error", which tells a later reader
+ * nothing at all, and there the raw message goes in instead.
+ *
+ * The line this holds is not "the framework never touches a raw message" but
+ * **"a raw message never crosses to the caller"**. Shared by the HTTP and tool
+ * paths so that line is one rule in one place. → ADR 0042.
+ */
+export declare function recordedErrorMessage(code: string, envelopeMessage: string | undefined, thrown: unknown): string | undefined;
 export declare function normalizeError(err: unknown): AppError;
 /**
  * Validate a handler's return value against the contract `output` schema. A

package/dist/internal/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAQvC,wBAAgB,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CAMxD;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,eAAe,EAAE,CAM9D;AAKD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI1D;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAgBrD;AA4BD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,EACb,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAe9D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAQvC,wBAAgB,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CAMxD;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,eAAe,EAAE,CAM9D;AAKD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI1D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,MAAM,EAAE,OAAO,GACd,MAAM,GAAG,SAAS,CAMpB;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAgBrD;AA4BD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,EACb,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAe9D"}

package/dist/node.js

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

package/dist/observability/audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/observability/audit.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,kBAAkB,CAAC;AAElE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAe,KAAK,eAAe,EAAmB,MAAM,YAAY,CAAC;AAGhF,oCAAoC;AACpC,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,iFAAiF;IACjF,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC;IAC1C,yEAAyE;IACzE,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,IAAI,EAAE,CAAC,CAAC,EACN,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,KACpD,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpD;;;OAGG;IACH,QAAQ,EAAE,aAAa,CAAC;CACzB;AAmBD,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CA6G9D"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/observability/audit.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,kBAAkB,CAAC;AAElE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAe,KAAK,eAAe,EAAmB,MAAM,YAAY,CAAC;AAGhF,oCAAoC;AACpC,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,iFAAiF;IACjF,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC;IAC1C,yEAAyE;IACzE,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,IAAI,EAAE,CAAC,CAAC,EACN,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,KACpD,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpD;;;OAGG;IACH,QAAQ,EAAE,aAAa,CAAC;CACzB;AA8BD,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CA6G9D"}

package/dist/observability/index.js

@@ -13,11 +13,12 @@ import {
   setRequestError,
   setRequestUser,
   wrapInRequestContext
-} from "../index-9g9d6r1h.js";
+} from "../index-wya8bkme.js";
 import {
   isRecord,
-  isUnsafeKey
-} from "../index-c7nyw0yt.js";
+  isUnsafeKey,
+  recordedErrorMessage
+} from "../index-enc7t99e.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;
@@ -109,6 +110,9 @@ function toolErrorMessage(result) {
   }
   return hint;
 }
+function auditErrorMessage(result, thrown) {
+  return recordedErrorMessage(result.code, toolErrorMessage(result), thrown);
+}
 function readString(value) {
   return typeof value === "string" ? value : undefined;
 }
@@ -169,7 +173,7 @@ function createAuditHook(config) {
     };
   };
   const toolCall = {
-    afterToolCall: (toolName, args, result, durationMs, context, endpoint) => {
+    afterToolCall: (toolName, args, result, durationMs, context, endpoint, thrown) => {
       const requestCtx = getRequestContext();
       const span = requestCtx ? childSpan(requestCtx.trace) : createTraceContext();
       const measure = result.ok ? measureSize(result.data) : { resultSize: null, responseBytes: 0 };
@@ -189,7 +193,7 @@ function createAuditHook(config) {
         statusCode: result.ok ? 200 : 400,
         durationMs,
         errorCode: result.ok ? undefined : result.code,
-        errorMessage: result.ok ? undefined : toolErrorMessage(result),
+        errorMessage: result.ok ? undefined : auditErrorMessage(result, thrown),
         ...!result.ok && result.details !== undefined && {
           errorDetail: sanitizePayload(result.details, sanitize)
         },

package/dist/server/create.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/server/create.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAEV,eAAe,EACf,YAAY,EACZ,aAAa,EAGd,MAAM,SAAS,CAAC;AAEjB,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,CA6XjE;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,uBAuBnD"}
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/server/create.ts"],"names":[],"mappings":"AA2CA,OAAO,KAAK,EAEV,eAAe,EACf,YAAY,EACZ,aAAa,EAGd,MAAM,SAAS,CAAC;AAEjB,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,CAoZjE;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,uBAuBnD"}

package/dist/server/index.js

@@ -10,7 +10,7 @@ import {
   socketIoLane,
   staticRoute,
   webSocketLane
-} from "../index-3hsagjqf.js";
+} from "../index-k7ysesv0.js";
 import {
   createAuthHook,
   createBearerResolver,
@@ -23,7 +23,7 @@ import {
   signJwt,
   verifyJwt,
   verifyPkce
-} from "../index-jvescqgr.js";
+} from "../index-nmq59nae.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS,
   DEFAULT_CORS_EXPOSE_HEADERS,
@@ -34,6 +34,17 @@ import {
   jsonSchemaFields,
   toJsonSchema
 } from "../index-0ed3bx43.js";
+import {
+  isWithinDir
+} from "../index-x3fcszf8.js";
+import {
+  extractIp,
+  generateTraceId,
+  getClientInfo,
+  getTraceId,
+  resolveSocketIp,
+  resolveTraceId
+} from "../index-wya8bkme.js";
 import {
   AppError,
   STITCH_ERROR_STATUS,
@@ -43,25 +54,14 @@ import {
   errorCode,
   forbidden,
   formatZodError,
+  isRecord,
   isStitchErrorCode,
-  isWithinDir,
   normalizeError,
   notFound,
   rateLimited,
   unauthorized,
   zodIssues
-} from "../index-zza375qp.js";
-import {
-  extractIp,
-  generateTraceId,
-  getClientInfo,
-  getTraceId,
-  resolveSocketIp,
-  resolveTraceId
-} from "../index-9g9d6r1h.js";
-import {
-  isRecord
-} from "../index-c7nyw0yt.js";
+} from "../index-enc7t99e.js";
 // src/server/swept-map.ts
 function createSweptMap(options) {
   const store = new Map;

package/dist/tools/execute.d.ts

@@ -15,7 +15,18 @@ export interface ToolCallContext {
 }
 export interface ToolCallHooks {
     beforeToolCall?: (toolName: string, args: Record<string, unknown>, context: ToolCallContext, endpoint: MethodDef) => void | Promise<void>;
-    afterToolCall?: (toolName: string, args: Record<string, unknown>, result: ToolResult, durationMs: number, context: ToolCallContext, endpoint: MethodDef) => void | Promise<void>;
+    /**
+     * Every finished call, success and failure alike — the record of the call.
+     *
+     * `error` is the value **as thrown**, present only when the call failed by
+     * throwing (never for an argument-validation failure, an output-schema
+     * mismatch or a `beforeToolCall` rejection — those never had a raw value).
+     * It is the same value `onToolError` receives, handed here too so a single
+     * hook can build one row that names the cause: the `result` alone cannot,
+     * because an unexpected throw is scrubbed to a bare `INTERNAL_SERVER_ERROR`.
+     * A six-parameter hook is unaffected.
+     */
+    afterToolCall?: (toolName: string, args: Record<string, unknown>, result: ToolResult, durationMs: number, context: ToolCallContext, endpoint: MethodDef, error?: unknown) => void | Promise<void>;
     /**
      * The handler path threw — the value **as thrown**, before it is normalised
      * into a `ToolResult`. The tool-side answer to HTTP's `hooks.onError`, and the

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,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,KAChB,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,CAmIrB"}
+{"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"}

package/dist/tools.js

@@ -2,7 +2,7 @@ import {
   inputIsQuery,
   signJwt,
   verifyPkce
-} from "./index-jvescqgr.js";
+} from "./index-nmq59nae.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS
 } from "./index-czmqks7r.js";
@@ -21,22 +21,22 @@ import {
   readCapped,
   toolResultFromError,
   writeDownload
-} from "./index-zj1s68tb.js";
+} from "./index-jr8vf7g8.js";
 import {
   toJsonSchema
 } from "./index-0ed3bx43.js";
 import {
-  AppError,
-  isWithinDir,
-  mergeMeta
-} from "./index-zza375qp.js";
+  isWithinDir
+} from "./index-x3fcszf8.js";
 import {
   getTraceId
-} from "./index-9g9d6r1h.js";
+} from "./index-wya8bkme.js";
 import {
+  AppError,
   isRecord,
+  mergeMeta,
   typedEntries
-} from "./index-c7nyw0yt.js";
+} from "./index-enc7t99e.js";
 
 // src/tools/agent.ts
 import { tool, zodSchema } from "ai";

package/llms-full.txt

@@ -2879,10 +2879,22 @@ import {
 } from 'stitchkit/observability'
 
 createAuthHook({ /* … */ inject: (ctx, user) => user && setRequestUser(user.id) })
-// in your onError hook:
+// only to override what the framework already recorded — see below:
 setRequestError({ code: err.code, message: err.message, details: err.issues })
 ```
 
+**The failure is recorded for you.** Every error travels one path inside the
+framework, and that path writes `{ code, message, details }` onto the context —
+so an audited failure names its cause whether or not you wrote an `onError`, and
+whether or not your `onError` returns its own `Response`. Where the envelope was
+scrubbed to `INTERNAL_SERVER_ERROR`, the row gets the **real** message rather than
+the placeholder; the caller still receives the scrubbed one. → ADR 0043
+
+`setRequestError` is therefore an **override**, not the wiring: call it when you
+want the row to say something other than what the framework derived (a domain
+code, a curated message, structured issues). The framework writes only when the
+context carries nothing yet, so your value always wins.
+
 **Endpoint identity is automatic.** The framework writes the matched operation's
 `(serviceName, action)` into the context at route-match, *before* validation — so
 `event.serviceName` / `event.action` are present on every event, including a
@@ -3024,9 +3036,10 @@ metric, a custom log line, anything that is not a full audit row.
 
 `afterHandle(ctx, result, endpoint)` runs after a handler returns;
 `onError(ctx, error, endpoint)` when one throws. `afterToolCall(toolName, args,
-result, durationMs, context)` runs after every tool call — success and error
-alike — carrying the tool name, the arguments, the result, the duration and the
-call context.
+result, durationMs, context, endpoint, error)` runs after every tool call —
+success and error alike — carrying the tool name, the arguments, the result, the
+duration, the call context, the endpoint identity, and (only when the call failed
+by throwing) the raw thrown value.
 
 ```ts
 createMcpHandler({
@@ -3086,35 +3099,43 @@ observe. (This is also why it lives on `ToolCallHooks` rather than being an
 `Response`, which a tool call has no use for, and a whole `createServer` hooks
 object must stay assignable to `ToolLifecycle`.)
 
-**`setRequestError` is the wrong sink here — mind which record you are filling.**
-It writes to the *request* context, and `createAuditHook`'s **tool** row does not
-read it: `errorCode` / `errorMessage` / `errorDetail` on a tool event come from
-the `ToolResult`, and only `userId` / `clientId` / `ipAddress` / `userAgent` /
-`dimensions` come from the context. So calling it in `onToolError` leaves the
-tool audit row exactly as scrubbed as before — and for MCP over HTTP it also
-writes the cause into the log line of the enclosing `/mcp` request, turning one
-incident into two records.
+**Do not reach for `setRequestError` here.** It writes to the *request* context,
+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.
 
-Route the cause to your own sink from `onToolError`, as above, and let the audit
-row stay the record of the *call*. If you want one row carrying both, correlate
-the two hooks yourself — key the cause by the call and read it back in
-`afterToolCall`:
+### One row that names the cause
 
-```ts
-const causes = new WeakMap<object, unknown>()
+You do not need to correlate the two hooks yourself. `afterToolCall` receives the
+same raw value as a **seventh parameter**, so one hook can build one record:
 
+```ts
 hooks: {
-  onToolError: (_tool, error, context) => { causes.set(context, error) },
-  afterToolCall: (toolName, _args, result, durationMs, context, endpoint) => {
-    void writeRow({ toolName, result, durationMs, cause: causes.get(context), endpoint })
+  afterToolCall: (toolName, args, result, durationMs, context, endpoint, error) => {
+    void writeRow({ toolName, result, durationMs, cause: error, endpoint })
   },
 }
 ```
 
-Every mount builds a fresh context object per call and hands the same reference
-to both hooks, so it is a safe key and nothing leaks. `setRequestError` remains
-right for the **HTTP** path, where the request *is* the record — see the fields
-section above.
+`error` is present only when the call failed by **throwing** — a
+validation failure or a `beforeToolCall` rejection leaves it `undefined`, because
+neither ever had a raw value to lose. The parameter is additive: a six-parameter
+hook written before it keeps compiling and keeps firing.
+
+`createAuditHook` uses it already. Where the envelope was scrubbed to
+`INTERNAL_SERVER_ERROR`, the row's `errorMessage` becomes the real message
+instead of the placeholder; a truthful envelope (a thrown `AppError`, a
+`ZodError`) is left alone, `errorCode` and `errorDetail` are untouched, and the
+stack is not written — that is `onToolError`'s job, for a tracker that wants it.
+The caller still receives the scrubbed envelope in every case: the raw text
+reaches your server-side record, never the response. → ADR 0042
+
+So the two hooks divide by **purpose**, not by capability — `onToolError` for a
+sink of your own (a tracker, a stack, an alert), `afterToolCall` for the record.
 
 ### Keying a row on (service, action)
 
@@ -3887,7 +3908,7 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `Toolkit` | _type_ | the context-pinned tool surface from `createToolkit` |
 | `ToolExtend` | _type_ | extra-args extension for `mountMcp` / `mountAgent` |
 | `ToolLifecycle` | _type_ | `beforeHandle` / `afterHandle` gate for tool calls — [guide](../guide/mcp-and-agents.md#guarding-tools--lifecycle) |
-| `ToolCallHooks` | _type_ | `beforeToolCall` / `afterToolCall` / `onToolError` observability hooks — the last carries the value **as thrown**, before normalisation scrubs an unexpected error to `INTERNAL_SERVER_ERROR` ([guide](../guide/observability.md#the-cause-behind-a-failed-tool-call)) |
+| `ToolCallHooks` | _type_ | `beforeToolCall` / `afterToolCall` / `onToolError` observability hooks — the raw thrown value reaches both of the last two (`afterToolCall`'s 7th parameter), because normalisation scrubs an unexpected error to `INTERNAL_SERVER_ERROR` ([guide](../guide/observability.md#the-cause-behind-a-failed-tool-call)) |
 | `ErrorHintFn` | _type_ | `(toolName, errorCode) => string \| null` — a per-tool recovery hint, shared by every mount |
 | `ToolResult` | _type_ | the result of one tool call |
 | `ToolCallContext` | _type_ | the context every tool hook receives — `{ source }` plus whatever the mount's `context` added |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.31.0",
+  "version": "0.33.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",
@@ -90,7 +90,8 @@
     "dev": "bun run build:js -- --watch",
     "prepublishOnly": "cp ../../README.md ./README.md && bun ../../scripts/gen-llms.ts && bun run build",
     "test": "bun test",
-    "smoke:node": "node scripts/node-smoke.mjs"
+    "smoke:node": "node scripts/node-smoke.mjs",
+    "consumer-lane": "bun scripts/consumer-lane/run.mjs"
   },
   "peerDependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.2",

package/dist/index-c7nyw0yt.js

@@ -1,20 +0,0 @@
-import { createRequire } from "node:module";
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
-// src/internal/typed.ts
-function typedEntries(value) {
-  return Object.entries(value);
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-// src/internal/safe-json.ts
-function isUnsafeKey(key) {
-  return key === "__proto__";
-}
-function safeJsonParse(text) {
-  return JSON.parse(text, (key, value) => isUnsafeKey(key) ? undefined : value);
-}
-
-export { __require, typedEntries, isRecord, isUnsafeKey, safeJsonParse };