stitchkit 0.31.0 → 0.32.0

package/dist/cli.js

@@ -4,7 +4,7 @@ import {
   emitResult,
   parseCliArgs,
   pollUntilDone
-} from "./index-zj1s68tb.js";
+} from "./index-36qnfzxe.js";
 import"./index-0ed3bx43.js";
 import"./index-zza375qp.js";
 import"./index-c7nyw0yt.js";

package/dist/{index-zj1s68tb.js → index-36qnfzxe.js}

@@ -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/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":"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;AAyCD,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CA6G9D"}

package/dist/observability/index.js

@@ -109,6 +109,15 @@ function toolErrorMessage(result) {
   }
   return hint;
 }
+function auditErrorMessage(result, thrown) {
+  if (result.code === "INTERNAL_SERVER_ERROR" && thrown !== undefined) {
+    if (thrown instanceof Error)
+      return thrown.message;
+    if (typeof thrown === "string")
+      return thrown;
+  }
+  return toolErrorMessage(result);
+}
 function readString(value) {
   return typeof value === "string" ? value : undefined;
 }
@@ -169,7 +178,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 +198,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/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

@@ -21,7 +21,7 @@ import {
   readCapped,
   toolResultFromError,
   writeDownload
-} from "./index-zj1s68tb.js";
+} from "./index-36qnfzxe.js";
 import {
   toJsonSchema
 } from "./index-0ed3bx43.js";

package/llms-full.txt

@@ -3024,9 +3024,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 +3087,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 +3896,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.32.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",