stitchkit 0.90.8 → 0.91.1

package/CHANGELOG.md

@@ -15,6 +15,99 @@ 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
+
+- **`STITCH_ERROR_STATUS` gained `NOT_IMPLEMENTED` (501).** An exhaustive error
+  vocabulary must name it; without the row `defineErrors({ mapping: { exhaustive:
+  true } })` stops compiling and then throws at startup. The code is thrown only
+  by the new dev-only `onMissingHandler: 'stub'` policy, and it is registered
+  rather than thrown ad hoc on purpose: the framework must not emit a code its
+  own registry does not know, or the code travels in stitchkit's spelling past
+  every consumer `codeMap`.
+  `// before: map: { …, WAIT_TIMEOUT: 'timeout' }` →
+  `// after:  map: { …, NOT_IMPLEMENTED: 'not_implemented', WAIT_TIMEOUT: 'timeout' }`
+
+**Who must act:** any consumer declaring an exhaustive error vocabulary. Nobody
+else: every other change in this release is additive.
+
+### Added
+
+- **`beforeToolCall` may return replacement arguments.** The pipeline was
+  asymmetric: `lifecycle.afterHandle` could already transform the output, while
+  the only way to affect the input was to throw — so expanding a reference into a
+  value *before* validation had nowhere to stand. A returned record replaces the
+  arguments and is validated by the contract schema like any other input. Only a
+  plain object is read as a replacement: `undefined`, `null`, a `Map` from a
+  one-line `audit.set(...)`, the number a `push` returns — everything an existing
+  hook already returns — keeps today's behaviour byte for byte. `afterToolCall` reports
+  the caller's arguments as `args` and the replacement as `effectiveArgs`, so a
+  rewrite is visible as a rewrite rather than by overwriting the evidence.
+- **The model-facing tool refusal carries `retryable`.** One bit decides the
+  model's next move — wait and retry, fix the input, or stop — and until now it
+  was read off the code NAME. It is resolved on the failure itself, declared or
+  derived from the status of the normalized error, so an application's own
+  `status: 429` is retryable exactly like the framework's and the answer survives
+  a process hop; `ErrorDefinition` may declare `retryable` where the status class
+  is wrong in either direction. The rule is deliberately not "any `5xx`":
+  `REALTIME_CONTRACT_VIOLATION` and `STREAM_ITEM_INVALID` are 500 and
+  deterministic. `isRetryableStatus` is exported. The field is on **every**
+  failed tool envelope — the CLI's JSON error and the MCP error text block gained
+  a key; the HTTP envelope did not.
+- **`toolCallId` travels as ordinary tool-call context.** A consumer running its
+  own agent loop already received the outcome of every call through
+  `afterToolCall` — with no way to say which call it belonged to, so it
+  reconstructed the answer from serialized text instead. One consumer measured
+  five places asking "did this call fail" and getting five different answers.
+  `AgentToolError` and `isAgentToolError` are now exported too, so the failure can
+  be brand-checked instead of parsed.
+- **`mountAgent({ durability })` — restartable tool bodies without
+  `agent-runtime`, engine included.** `step` / `sleep` / `waitFor` appear in the
+  handler context. The `ToolDurability` port is what a body sees; the engine,
+  `createLocalStepDurability`, now ships from `stitchkit/tools` beside it, with
+  `StepDurabilityLedger` and the ledger's row types — an application supplies two
+  methods over storage it already has and gets replay, absolute deadlines,
+  park/deliver and decode refusal instead of writing them. The engine is
+  self-contained, and a build check over the real chunk graph holds that the
+  runtime proper never follows it into `stitchkit/tools`.
+- **`onMissingHandler: 'stub'` for every binding form.** A contract endpoint with
+  no handler is mounted as a `501` refusal instead of taking the whole application
+  down. For one measured situation: a dev stand under a file watcher, where adding
+  an endpoint is two edits by construction and the editor saves one file at a
+  time, so the stand is down between them for everyone using it. Both save orders
+  are covered — a contract ahead of its handler and a handler ahead of its
+  contract. `'throw'` remains the default and the only production answer, and the
+  compile-time exactness check is untouched.
+
+- **A string bound for one key, wherever it sits.** `redact` / `sanitizePayload`
+  take `maxStringLengthByKey` and `createBoundedLogger` takes
+  `bounds.stringLengthByKey`. One bound for the whole record cut an error's
+  stack from the bottom — where the consumer's own frames are; now the ceiling
+  for `stack` alone can be raised. Keyed by name, not path, because the same
+  field sits at the top of one record and under `errorDetail` in the next. The
+  byte ceiling keeps the last word.
+
+→ ADR 0187.
+
 ## [0.90.8] — 2026-09-21
 
 ### Added

package/dist/agent-runtime-coding-tools.js

@@ -3,16 +3,16 @@ import {
   AgentCodingToolLimitsSchema,
   AgentCodingToolPathAuthorizationSchema,
   createAgentCodingTools
-} from "./index-3yqgj323.js";
+} from "./index-qjeyx5t2.js";
 import"./index-bn2cjajt.js";
-import"./index-gte38nbm.js";
-import"./index-nrqg8tks.js";
+import"./index-qmy6zq75.js";
+import"./index-0a349c33.js";
 import"./index-rxfy4cq7.js";
 import"./index-6k1937bx.js";
 import"./index-8z9we758.js";
 import"./index-fenaekmk.js";
 import"./index-cby4ar3v.js";
-import"./index-scs3f1eg.js";
+import"./index-2vtcmrj9.js";
 import"./index-kzfs85xp.js";
 import"./index-77fekveh.js";
 export {

package/dist/agent-runtime-harness.js

@@ -6,7 +6,7 @@ import {
   composeAgentPrompt,
   createAgentRuntime,
   createAgentRuntimeEventSink
-} from "./index-4yktadec.js";
+} from "./index-bx6yq2m4.js";
 import"./index-p13mwz16.js";
 import"./index-y64k3s0h.js";
 import {
@@ -18,12 +18,12 @@ import"./index-wnfk50r0.js";
 import {
   walkContainedFiles
 } from "./index-bn2cjajt.js";
-import"./index-7rkhw9ec.js";
-import"./index-1ft2wrv0.js";
+import"./index-kw9t5ayn.js";
+import"./index-mqhjmadk.js";
 import"./index-vsbzgd7b.js";
 import"./index-f9mb610r.js";
-import"./index-42f33bzd.js";
-import"./index-nrqg8tks.js";
+import"./index-13cjtmrw.js";
+import"./index-0a349c33.js";
 import"./index-rxfy4cq7.js";
 import"./index-6k1937bx.js";
 import"./index-zcgf3gqf.js";
@@ -33,7 +33,7 @@ import {
 } from "./index-8z9we758.js";
 import"./index-fenaekmk.js";
 import"./index-cby4ar3v.js";
-import"./index-scs3f1eg.js";
+import"./index-2vtcmrj9.js";
 import"./index-kzfs85xp.js";
 import"./index-77fekveh.js";
 

package/dist/agent-runtime-sandbox.js

@@ -1,19 +1,19 @@
 import {
   createAgentCodingTools
-} from "./index-3yqgj323.js";
+} from "./index-qjeyx5t2.js";
 import"./index-bn2cjajt.js";
 import {
   codingRefusal,
   missingSandboxRestrictions,
   probeAgentProcessSandbox
-} from "./index-gte38nbm.js";
-import"./index-nrqg8tks.js";
+} from "./index-qmy6zq75.js";
+import"./index-0a349c33.js";
 import"./index-rxfy4cq7.js";
 import"./index-6k1937bx.js";
 import"./index-8z9we758.js";
 import"./index-fenaekmk.js";
 import"./index-cby4ar3v.js";
-import"./index-scs3f1eg.js";
+import"./index-2vtcmrj9.js";
 import"./index-kzfs85xp.js";
 import"./index-77fekveh.js";
 

package/dist/agent-runtime.js

@@ -3,12 +3,6 @@ import {
   AgentProviderStreamCutError,
   AgentRuntimeConflictError,
   AgentTokenCountSchema,
-  DURABILITY_STEP_EVENT_KIND,
-  ParkAbortedError,
-  ParkRecordDecodeError,
-  StepAbortedError,
-  StepResultDecodeError,
-  StepResultNotSerializableError,
   agentGoalStateSlot,
   agentTodoStateSlot,
   classifyProviderFailure,
@@ -18,7 +12,6 @@ import {
   createAgentSessionCoordinator,
   createAgentStateSlotStore,
   createAgentToolFenceLifecycle,
-  createLocalStepDurability,
   deferredToolCatalog,
   defineStateSlot,
   isToolResultFailure,
@@ -31,7 +24,7 @@ import {
   renderAgentStateSlots,
   repairedSearchCall,
   selectAgentHistory
-} from "./index-4yktadec.js";
+} from "./index-bx6yq2m4.js";
 import"./index-p13mwz16.js";
 import {
   AgentAdmissionEventSchema,
@@ -165,19 +158,27 @@ import {
   probeAgentProcessSandbox,
   recordAgentSandboxProbe,
   refuseUnknownSpillReference
-} from "./index-gte38nbm.js";
+} from "./index-qmy6zq75.js";
 import {
   buildToolManifest,
   mountAgent
-} from "./index-p48nc8g9.js";
-import"./index-7rkhw9ec.js";
-import"./index-w58rfj2d.js";
-import"./index-dggfq62w.js";
-import"./index-1ft2wrv0.js";
+} from "./index-f4p4b8f6.js";
+import {
+  DURABILITY_STEP_EVENT_KIND,
+  ParkAbortedError,
+  ParkRecordDecodeError,
+  StepAbortedError,
+  StepResultDecodeError,
+  StepResultNotSerializableError,
+  createLocalStepDurability
+} from "./index-kw9t5ayn.js";
+import"./index-qrbdq8jk.js";
+import"./index-1qvdwnp2.js";
+import"./index-mqhjmadk.js";
 import"./index-vsbzgd7b.js";
 import"./index-f9mb610r.js";
-import"./index-42f33bzd.js";
-import"./index-nrqg8tks.js";
+import"./index-13cjtmrw.js";
+import"./index-0a349c33.js";
 import"./index-rxfy4cq7.js";
 import"./index-6k1937bx.js";
 import {
@@ -190,7 +191,7 @@ import {
 } from "./index-8z9we758.js";
 import"./index-fenaekmk.js";
 import"./index-cby4ar3v.js";
-import"./index-scs3f1eg.js";
+import"./index-2vtcmrj9.js";
 import"./index-kzfs85xp.js";
 import {
   executableAgentRuntimeTools

package/dist/application-grammy.js

@@ -3,7 +3,7 @@ import {
 } from "./index-2k4yrqkc.js";
 import {
   AppError
-} from "./index-scs3f1eg.js";
+} from "./index-2vtcmrj9.js";
 
 // src/application/grammy.ts
 import { Context } from "grammy";

package/dist/application.js

@@ -36,7 +36,7 @@ import {
   ApplicationShutdownBudgetSchema,
   ApplicationShutdownOptionsSchema,
   createApplication
-} from "./index-zkcqhxx8.js";
+} from "./index-a11g2kry.js";
 import {
   ApplicationAdmissionSnapshotSchema,
   ApplicationHealthSchema,
@@ -82,12 +82,12 @@ import {
 } from "./index-7gnkny4z.js";
 import {
   measureSize
-} from "./index-xbppf54a.js";
+} from "./index-6kyksz9y.js";
 import {
   argumentsDigest,
   stableValue
 } from "./index-a916km3r.js";
-import"./index-scs3f1eg.js";
+import"./index-2vtcmrj9.js";
 import"./index-kzfs85xp.js";
 import"./index-77fekveh.js";
 // src/application/admission.ts

package/dist/cli.js

@@ -11,15 +11,15 @@ import {
   readCapped,
   renderCliView,
   routeCliArgv
-} from "./index-mthq65vn.js";
+} from "./index-ya611vx3.js";
 import"./index-sbdmyz75.js";
-import"./index-w58rfj2d.js";
-import"./index-dggfq62w.js";
-import"./index-1ft2wrv0.js";
+import"./index-qrbdq8jk.js";
+import"./index-1qvdwnp2.js";
+import"./index-mqhjmadk.js";
 import"./index-vsbzgd7b.js";
 import"./index-f9mb610r.js";
-import"./index-42f33bzd.js";
-import"./index-nrqg8tks.js";
+import"./index-13cjtmrw.js";
+import"./index-0a349c33.js";
 import"./index-rxfy4cq7.js";
 import"./index-6k1937bx.js";
 import"./index-zcgf3gqf.js";
@@ -31,7 +31,7 @@ import"./index-fenaekmk.js";
 import"./index-cby4ar3v.js";
 import {
   AppError
-} from "./index-scs3f1eg.js";
+} from "./index-2vtcmrj9.js";
 import {
   safeJsonParse
 } from "./index-kzfs85xp.js";

package/dist/contract/errors-factory.d.ts

@@ -35,10 +35,22 @@ export type ErrorDetailsSchema = z.ZodObject | z.ZodOptional<z.ZodObject>;
 export type ErrorDefinition = {
     readonly status: number;
     readonly message?: string;
+    readonly retryable?: boolean;
     readonly details?: never;
 } | {
     readonly status: number;
     readonly message?: string;
+    /**
+     * Whether repeating the call could succeed, when the status class gets it
+     * wrong. Omitted, it is derived from `status`.
+     *
+     * This is where ADR 0077 refused to put `hint`, and the reason does not
+     * apply: a hint DECLARED here would concatenate with the surface-wide
+     * `ErrorHintFn` and repeat itself on every instance of the code. A
+     * boolean has nothing to concatenate with — it is one fact about the
+     * code, stated once, in the same place its status is stated.
+     */
+    readonly retryable?: boolean;
     readonly details: ErrorDetailsSchema;
 };
 export type ErrorDefinitions = Record<string, ErrorDefinition>;

package/dist/contract/errors-factory.d.ts.map

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

package/dist/contract/errors.d.ts

@@ -32,13 +32,35 @@ export declare class AppError<TCode extends string = string, TDetails extends Re
      * logs/observability — deliberately NOT part of `toJSON()`'s envelope.
      */
     readonly traceId?: string | undefined;
+    /**
+     * Whether repeating this call could succeed, when the error declares it.
+     *
+     * Metadata, like `traceId`, and for the same reason: it is not part of
+     * `toJSON()`'s HTTP envelope. It exists for the MODEL-facing tool envelope,
+     * where the next move — wait and retry, fix the input, or stop — is the
+     * whole decision a refusal has to support. Left `undefined`, the class is
+     * derived from `status`; declared, it wins, for the domain failure whose
+     * status says one thing and whose truth is the other.
+     */
+    readonly retryable?: boolean | undefined;
     constructor(code: TCode, message?: string, status?: number, details?: TDetails | undefined, hint?: string | undefined, 
     /**
      * Transport trace id (`x-request-id`) preserved across the
      * `ApiError → AppError` conversion in `implementRemote`. Metadata for
      * logs/observability — deliberately NOT part of `toJSON()`'s envelope.
      */
-    traceId?: string | undefined);
+    traceId?: string | undefined, 
+    /**
+     * Whether repeating this call could succeed, when the error declares it.
+     *
+     * Metadata, like `traceId`, and for the same reason: it is not part of
+     * `toJSON()`'s HTTP envelope. It exists for the MODEL-facing tool envelope,
+     * where the next move — wait and retry, fix the input, or stop — is the
+     * whole decision a refusal has to support. Left `undefined`, the class is
+     * derived from `status`; declared, it wins, for the domain failure whose
+     * status says one thing and whose truth is the other.
+     */
+    retryable?: boolean | undefined);
     static is(err: unknown): err is AppError;
     toJSON(): ErrorEnvelope;
 }
@@ -83,6 +105,7 @@ export declare const STITCH_ERROR_STATUS: {
     REALTIME_CONTRACT_VIOLATION: number;
     APPLICATION_NOT_ACCEPTING: number;
     GRAMMY_WEBHOOK_NOT_ACCEPTING: number;
+    NOT_IMPLEMENTED: number;
     WAIT_TIMEOUT: number;
     WAIT_FAILED: number;
     DOWNLOAD_NOT_FOUND: number;
@@ -97,6 +120,17 @@ export declare const STITCH_ERROR_STATUS: {
     SPILL_REFERENCE_UNKNOWN: number;
     INTERNAL_SERVER_ERROR: number;
 };
+/**
+ * Whether a status class means "the same call could work later".
+ *
+ * Deliberately not "any 5xx". `REALTIME_CONTRACT_VIOLATION`,
+ * `STREAM_ITEM_INVALID` and `FRAME_TOO_LARGE` are all 500 and all deterministic
+ * — the same call fails the same way every time, and telling a model to retry
+ * them buys nothing but billed turns. 408 and 504 are timeouts, 429 is a rate
+ * limit, 502 and 503 are an upstream that may return; those are the ones where
+ * waiting is a strategy rather than a hope.
+ */
+export declare function isRetryableStatus(status: number): boolean;
 /** A code stitchkit itself emits — derived from `STITCH_ERROR_STATUS` (no dup). */
 export type StitchErrorCode = keyof typeof STITCH_ERROR_STATUS;
 /** Type guard — is `code` one of stitchkit's own error codes? */

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/contract/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE;QACL,2CAA2C;QAC3C,IAAI,EAAE,MAAM,CAAC;QACb,8BAA8B;QAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,gCAAgC;QAChC,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,0BAA0B;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAcD;;;;GAIG;AACH,qBAAa,QAAQ,CACnB,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAC1F,SAAQ,KAAK;aAEK,IAAI,EAAE,KAAK;aAEX,MAAM,EAAE,MAAM;aACd,OAAO,CAAC,EAAE,QAAQ;aAClB,IAAI,CAAC,EAAE,MAAM;IAC7B;;;;OAIG;aACa,OAAO,CAAC,EAAE,MAAM;IAXlC,YACkB,IAAI,EAAE,KAAK,EAC3B,OAAO,CAAC,EAAE,MAAM,EACA,MAAM,GAAE,MAAY,EACpB,OAAO,CAAC,EAAE,QAAQ,YAAA,EAClB,IAAI,CAAC,EAAE,MAAM,YAAA;IAC7B;;;;OAIG;IACa,OAAO,CAAC,EAAE,MAAM,YAAA,EAQjC;IAED,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,QAAQ,CAEvC;IAED,MAAM,IAAI,aAAa,CAStB;CACF;AAED,qCAAqC;AACrC,wBAAgB,QAAQ,CAAC,OAAO,SAAc,GAAG,KAAK,CAErD;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAEpF;AAED,wCAAwC;AACxC,wBAAgB,YAAY,CAAC,OAAO,SAAiB,GAAG,KAAK,CAE5D;AAED,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,OAAO,SAAc,GAAG,KAAK,CAEtD;AAED,0EAA0E;AAC1E,wBAAgB,QAAQ,CAAC,OAAO,SAAa,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAEvF;AAED,wCAAwC;AACxC,wBAAgB,WAAW,CAAC,OAAO,SAAsB,GAAG,KAAK,CAEhE;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CE,CAAC;AAEnC,mFAAmF;AACnF,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,mBAAmB,CAAC;AAE/D,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,eAAe,CAEvE;AAED,+FAA+F;AAC/F,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,KAAK,CAOP"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/contract/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE;QACL,2CAA2C;QAC3C,IAAI,EAAE,MAAM,CAAC;QACb,8BAA8B;QAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,gCAAgC;QAChC,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,0BAA0B;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAcD;;;;GAIG;AACH,qBAAa,QAAQ,CACnB,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAC1F,SAAQ,KAAK;aAEK,IAAI,EAAE,KAAK;aAEX,MAAM,EAAE,MAAM;aACd,OAAO,CAAC,EAAE,QAAQ;aAClB,IAAI,CAAC,EAAE,MAAM;IAC7B;;;;OAIG;aACa,OAAO,CAAC,EAAE,MAAM;IAChC;;;;;;;;;OASG;aACa,SAAS,CAAC,EAAE,OAAO;IAtBrC,YACkB,IAAI,EAAE,KAAK,EAC3B,OAAO,CAAC,EAAE,MAAM,EACA,MAAM,GAAE,MAAY,EACpB,OAAO,CAAC,EAAE,QAAQ,YAAA,EAClB,IAAI,CAAC,EAAE,MAAM,YAAA;IAC7B;;;;OAIG;IACa,OAAO,CAAC,EAAE,MAAM,YAAA;IAChC;;;;;;;;;OASG;IACa,SAAS,CAAC,EAAE,OAAO,YAAA,EAQpC;IAED,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,QAAQ,CAEvC;IAED,MAAM,IAAI,aAAa,CAStB;CACF;AAED,qCAAqC;AACrC,wBAAgB,QAAQ,CAAC,OAAO,SAAc,GAAG,KAAK,CAErD;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAEpF;AAED,wCAAwC;AACxC,wBAAgB,YAAY,CAAC,OAAO,SAAiB,GAAG,KAAK,CAE5D;AAED,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,OAAO,SAAc,GAAG,KAAK,CAEtD;AAED,0EAA0E;AAC1E,wBAAgB,QAAQ,CAAC,OAAO,SAAa,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAEvF;AAED,wCAAwC;AACxC,wBAAgB,WAAW,CAAC,OAAO,SAAsB,GAAG,KAAK,CAEhE;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoDE,CAAC;AAEnC;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAIzD;AAED,mFAAmF;AACnF,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,mBAAmB,CAAC;AAE/D,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,eAAe,CAEvE;AAED,+FAA+F;AAC/F,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,KAAK,CAOP"}

package/dist/contract/index.d.ts

@@ -1,5 +1,5 @@
 export { ALL_TRANSPORTS, type BodyHttpSuccessStatus, type ClientRequestOptions, type ContractDef, type ContractMeta, type ContractStreamCompletion, type ContractStreamFraming, defineContract, type EndpointDef, type EndpointFn, type EndpointMcpInputRequired, type EndpointMcpPolicy, type EndpointResponseMeta, type EndpointStreamDescriptor, type EndpointToolAnnotations, type EndpointUiMeta, type FileDescriptor, type HandlerContext, type HeadEndpointDef, type HttpMethod, type HttpSuccessStatus, type McpCallContext, type McpClientInfo, type McpRoundOutcome, type MultipartBufferedFiles, type MultipartDescriptor, type MultipartFile, type MultipartFilePolicy, type PathParams, type ResponseMetadata, type RuntimeContext, type ScopedEndpointFn, type ScopedHttpClient, type ScopedUrlBuilder, type ScopedUrlFn, type StreamFinalLinePolicy, type Transport, type TransportSource, type TypedClient, type TypedHttpClient, type TypedUrlBuilder, } from './define.js';
-export { AppError, appError, badRequest, conflict, type ErrorEnvelope, forbidden, isStitchErrorCode, notFound, rateLimited, STITCH_ERROR_STATUS, type StitchErrorCode, unauthorized, } from './errors.js';
+export { AppError, appError, badRequest, conflict, type ErrorEnvelope, forbidden, isRetryableStatus, isStitchErrorCode, notFound, rateLimited, STITCH_ERROR_STATUS, type StitchErrorCode, unauthorized, } from './errors.js';
 export { type DefinedAppError, type DefinedErrors, defineErrors, type ErrorDefinition, type ErrorDefinitions, type ErrorDetailsOutput, type ErrorDetailsSchema, type ErrorFactories, type ErrorFactory, type ErrorFactoryArguments, type ErrorVocabularyCode, type ErrorVocabularyMapping, type FrozenErrorDefinitions, type VocabularyCodeMap, } from './errors-factory.js';
 export { type ContractFactoryConfig, type ContractFactoryToolExposure, createContractFactory, type ExplicitScopedDefineContract, type ExplicitToolExposureEndpoints, type FactoryScopedEndpoint, type ScopedContractDef, type ScopedDefineContract, } from './factory.js';
 export { type ManagedFilePath, ManagedFilePathSchema, type ManagedFileRef, ManagedFileRefSchema, } from './file-ref.js';

package/dist/contract/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,KAAK,aAAa,EAClB,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,qBAAqB,EACrB,KAAK,4BAA4B,EACjC,KAAK,6BAA6B,EAClC,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,GAC1B,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,cAAc,EACnB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,KAAK,SAAS,EACd,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,mCAAmC,GACpC,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,KAAK,aAAa,EAClB,SAAS,EACT,iBAAiB,EACjB,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,qBAAqB,EACrB,KAAK,4BAA4B,EACjC,KAAK,6BAA6B,EAClC,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,GAC1B,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,cAAc,EACnB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,KAAK,SAAS,EACd,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,mCAAmC,GACpC,MAAM,UAAU,CAAC"}

package/dist/contract/index.js

@@ -8,7 +8,7 @@ import {
   defineErrors,
   encodeCursor,
   paginatedSchema
-} from "../index-nrqg8tks.js";
+} from "../index-0a349c33.js";
 import"../index-rxfy4cq7.js";
 import {
   ManagedFilePathSchema,
@@ -21,11 +21,12 @@ import {
   badRequest,
   conflict,
   forbidden,
+  isRetryableStatus,
   isStitchErrorCode,
   notFound,
   rateLimited,
   unauthorized
-} from "../index-scs3f1eg.js";
+} from "../index-2vtcmrj9.js";
 import"../index-kzfs85xp.js";
 import"../index-77fekveh.js";
 export {
@@ -34,6 +35,7 @@ export {
   paginatedSchema,
   notFound,
   isStitchErrorCode,
+  isRetryableStatus,
   forbidden,
   encodeCursor,
   defineErrors,

package/dist/{index-nrqg8tks.js → index-0a349c33.js}

@@ -6,7 +6,7 @@ import {
   AppError,
   STITCH_ERROR_STATUS,
   isStitchErrorCode
-} from "./index-scs3f1eg.js";
+} from "./index-2vtcmrj9.js";
 import {
   isUnsafeKey
 } from "./index-kzfs85xp.js";
@@ -346,10 +346,10 @@ function defineErrors(source, mapping) {
         if ("details" in options) {
           throw new Error(`[stitchkit] Error "${name}" does not declare details`);
         }
-        return new AppError(name, message, definition.status, undefined, options.hint);
+        return new AppError(name, message, definition.status, undefined, options.hint, undefined, definition.retryable);
       }
       const details = definition.details.parse(options.details);
-      return new AppError(name, message, definition.status, details, options.hint);
+      return new AppError(name, message, definition.status, details, options.hint, undefined, definition.retryable);
     };
   });
   Object.freeze(errors);

package/dist/{index-adj0pc9r.js → index-137jjs4v.js}

@@ -3,7 +3,7 @@ import {
   inputIsQuery,
   parseSSE,
   readBoundedUtf8Lines
-} from "./index-zjze12x8.js";
+} from "./index-b971qjes.js";
 import {
   ApiError,
   RequestCancellationError,
@@ -16,7 +16,7 @@ import {
   ContractStreamFrameSchema,
   DEFAULT_CONTRACT_STREAM_FRAME_BYTES,
   parseTrailingWildcard
-} from "./index-nrqg8tks.js";
+} from "./index-0a349c33.js";
 import {
   isRecord,
   mapObject,

package/dist/{index-42f33bzd.js → index-13cjtmrw.js}

@@ -1,6 +1,6 @@
 import {
   AppError
-} from "./index-scs3f1eg.js";
+} from "./index-2vtcmrj9.js";
 import {
   isRecord
 } from "./index-77fekveh.js";

package/dist/{index-qd8gs6nf.js → index-13e1k7v9.js}

@@ -4,10 +4,10 @@ import {
 } from "./index-2qzskm8h.js";
 import {
   zodIssues
-} from "./index-42f33bzd.js";
+} from "./index-13cjtmrw.js";
 import {
   AppError
-} from "./index-scs3f1eg.js";
+} from "./index-2vtcmrj9.js";
 
 // src/realtime/rejected-frame.ts
 var REALTIME_REJECTION_KEY = "@stitchkit/realtime-rejected";

package/dist/{index-dggfq62w.js → index-1qvdwnp2.js}

@@ -1,12 +1,16 @@
 import {
-  executeToolMethod
-} from "./index-1ft2wrv0.js";
+  executeToolMethod,
+  toolErrorFromResult
+} from "./index-mqhjmadk.js";
 import {
   assertToolExtensionCompatible,
   mergeSchemas,
   projectToolSurface,
   rebuildObject
 } from "./index-fenaekmk.js";
+import {
+  isRetryableStatus
+} from "./index-2vtcmrj9.js";
 
 // src/tools/mount.ts
 import { z } from "zod";
@@ -54,7 +58,10 @@ function createToolRunner(config) {
   };
 }
 function formatToolError(result, toolName, errorHint) {
-  const err = { error: result.code };
+  const err = {
+    error: result.code,
+    retryable: result.retryable ?? isRetryableStatus(toolErrorFromResult(result).status)
+  };
   if (result.details)
     err.details = result.details;
   const hints = [];

package/dist/{index-scs3f1eg.js → index-2vtcmrj9.js}

@@ -7,13 +7,15 @@ class AppError extends Error {
   details;
   hint;
   traceId;
-  constructor(code, message, status = 500, details, hint, traceId) {
+  retryable;
+  constructor(code, message, status = 500, details, hint, traceId, retryable) {
     super(message ?? code);
     this.code = code;
     this.status = status;
     this.details = details;
     this.hint = hint;
     this.traceId = traceId;
+    this.retryable = retryable;
     this.name = "AppError";
     Object.defineProperty(this, APP_ERROR_BRAND, { value: true });
   }
@@ -68,6 +70,7 @@ var STITCH_ERROR_STATUS = {
   REALTIME_CONTRACT_VIOLATION: 500,
   APPLICATION_NOT_ACCEPTING: 503,
   GRAMMY_WEBHOOK_NOT_ACCEPTING: 503,
+  NOT_IMPLEMENTED: 501,
   WAIT_TIMEOUT: 408,
   WAIT_FAILED: 409,
   DOWNLOAD_NOT_FOUND: 404,
@@ -82,6 +85,9 @@ var STITCH_ERROR_STATUS = {
   SPILL_REFERENCE_UNKNOWN: 404,
   INTERNAL_SERVER_ERROR: 500
 };
+function isRetryableStatus(status) {
+  return status === 408 || status === 429 || status === 502 || status === 503 || status === 504;
+}
 function isStitchErrorCode(code) {
   return Object.hasOwn(STITCH_ERROR_STATUS, code);
 }
@@ -89,4 +95,4 @@ function appError(code, message, details) {
   throw new AppError(code, message, isStitchErrorCode(code) ? STITCH_ERROR_STATUS[code] : 500, details);
 }
 
-export { AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError };
+export { AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isRetryableStatus, isStitchErrorCode, appError };