stitchkit 0.91.0 → 0.91.1

package/CHANGELOG.md

@@ -15,6 +15,24 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.91.1] — 2026-09-22
+
+### Fixed
+
+- **A refusal relayed from a discovered MCP tool no longer says "retryable" for
+  everything.** `mcpToolFailure` rebuilt the remote's refusal with a constant
+  502 and read neither `retryable` nor `_hint` off the envelope it had just
+  parsed. 502 is a retryable class, so the status-derived answer was `true` for
+  every relayed failure there has ever been — `NOT_FOUND` included, and a model
+  reading it calls the missing thing again. That is the exact opposite of what
+  the field was added for in 0.91.0. Both fields are now carried as the remote
+  sent them: `retryable` only when it is a boolean, `_hint` only when it is a
+  string, so `0` or `'false'` stays undeclared rather than being coerced into a
+  decision. The status stays 502 in both branches — the failure did happen
+  upstream, and a declared `retryable` wins over it anyway. A remote that
+  declares nothing is unchanged, and the unstructured branch
+  (`UPSTREAM_TOOL_ERROR`) has nothing to declare and keeps the 502 default.
+
 ## [0.91.0] — 2026-09-22
 
 ### ⚠️ Breaking changes

package/dist/tools/connections/index.js

@@ -543,7 +543,7 @@ function mcpToolFailure(toolName, result) {
   if (isRecord(payload) && typeof payload.error === "string") {
     const details = isRecord(payload.details) ? payload.details : undefined;
     const message = typeof details?.message === "string" ? details.message : payload.error;
-    return new AppError(payload.error, message, 502, details);
+    return new AppError(payload.error, message, 502, details, typeof payload._hint === "string" ? payload._hint : undefined, undefined, typeof payload.retryable === "boolean" ? payload.retryable : undefined);
   }
   return new AppError(UPSTREAM_TOOL_ERROR, `External MCP tool "${toolName}" returned an error`, 502, payload === undefined ? undefined : { upstream: payload });
 }

package/dist/tools/connections/mcp-envelope.d.ts

@@ -34,11 +34,21 @@ export declare const UPSTREAM_TOOL_ERROR = "UPSTREAM_TOOL_ERROR";
  * it printed a code frame of the framework bundle before the JSON failure and
  * was then scrubbed to a bare `INTERNAL_SERVER_ERROR`.
  *
- * A structured `{ error, details }` body is the remote contract's own refusal
- * and is relayed as one. Anything else keeps the framework's sentence and
- * carries what the server did send — reporting less than we have is not caution.
+ * A structured `{ error, retryable, details, _hint }` body is the remote
+ * contract's own refusal and is relayed as one — every field of it. Anything
+ * else keeps the framework's sentence and carries what the server did send —
+ * reporting less than we have is not caution.
+ *
  * The status is 502 either way: whatever the code says, the failure happened
- * upstream, and a consumer re-serving it over HTTP should say so.
+ * upstream, and a consumer re-serving it over HTTP should say so. That constant
+ * is exactly why `retryable` has to be carried rather than re-derived. 502 is a
+ * retryable class, so a status-derived answer says `true` for every relayed
+ * refusal there has ever been — `NOT_FOUND` included, and a model reading it
+ * calls the missing thing again. The remote already decided, declared or
+ * derived from its own status, and its answer is the one that means something:
+ * it is the only side that knows whether repeating the call could work. `_hint`
+ * rides along for the same reason — it is the remote's instruction for what to
+ * do instead, and dropping it leaves the model with a refusal and no next move.
  */
 export declare function mcpToolFailure(toolName: string, result: unknown): AppError;
 //# sourceMappingURL=mcp-envelope.d.ts.map

package/dist/tools/connections/mcp-envelope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-envelope.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/mcp-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAIjD,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAaxD;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,QAAQ,CAa1E"}
+{"version":3,"file":"mcp-envelope.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/mcp-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAIjD,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAaxD;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,QAAQ,CAwB1E"}

package/llms-full.txt

@@ -6110,6 +6110,15 @@ const signals = bindProcessSignals(app, {
 await app.start()
 ```
 
+**Bind before you start, and the order is load-bearing.** Reading it the other way
+round — start serving, then arrange for shutdown — leaves a window between the
+first accepted request and the first listener, and a supervisor that sends
+`SIGTERM` inside that window kills the process outright: exit 143, no shutdown
+chain, no `onComplete`, nothing drained. The window is small and opens exactly
+when the machine is busiest, which is when a supervisor is most likely to be
+restarting something. `bindProcessSignals` does not start anything, so there is
+no cost to binding first.
+
 The exact resource callbacks are typed by their public configuration. The
 important ownership rule is stable: the application decides what the
 database/server/provider objects are and how they are configured; Stitchkit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.91.0",
+  "version": "0.91.1",
   "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",