agentfootprint 11.4.0 → 12.0.0

package/dist/types/mcp/callLifetime.d.ts

@@ -15,36 +15,79 @@
  *      the call. The link is undone when the call settles: the SDK keeps its
  *      abort listener on the signal it was given, and a link that outlived the
  *      call would cancel a request that had already finished.
- *   2. ITS TICKET is issued, when the call carries the run's evidence port and
- *      the connection has a ledger, keyed by the request's params object.
+ *   2. ITS MARKER is issued when the connection has a ledger, with its ticket
+ *      when the call carries the run's evidence port: a library-private string
+ *      in the request's `_meta` (`callMarker.ts`), which ties the request to
+ *      the call even when the SDK copies the params, and which the transport
+ *      takes out before anything is sent.
  *   3. ITS SETTLING ENDS ITS SERIES. However `callTool` settles — answered,
  *      failed, or given up by the SDK (its own timeout) — a retry series still
  *      sending the request is cut there and then, inside the call: it files
  *      `cancelled` before the call's result is read, and sends nothing more.
+ *   4. ITS VERDICT REACHES ITS RECORD. A series that has ended waits for the
+ *      call to settle before it files, because only the call can say whether
+ *      the answer completed — a 200 can carry a tool error. The call leaves its
+ *      verdict in the request's shared replay facts (`replay.ts` ·
+ *      `RequestReplay`) before it settles the series' wait.
+ *   5. "MAY HAVE RUN" IS RAISED HERE — footprintjs's law, under the
+ *      `'app-authorized'` policy (`replay.ts` · `RequestReplay`, its
+ *      `uncertain`). A received refusal or error is preserved: a 429, a 503,
+ *      a JSON-RPC or tool error — or a chain in which every attempt received
+ *      one — keeps the server's error as it came, its effect still `unknown`.
+ *      A call that genuinely lacked an answer somewhere — an attempt with no
+ *      response at all, or a request the HTTP layer accepted whose JSON-RPC
+ *      answer never came — and then fails, fails with footprintjs's
+ *      `UnknownEffectError`, its final error (a later refusal's, or the
+ *      timeout) as the `cause`: that error alone would read as "failed, try
+ *      again". A call that completes returns normally. Under `'compatibility'`
+ *      the caller sees the error it always did; the record still says the
+ *      effect is unknown. A cancellation never raises it: a call its caller
+ *      cancelled ends with the caller's reason, as it always did.
  *
- * In dev mode, a ticket that no request was bound to by the time the call
- * settled, when a `tools/call` request DID go out, is named once per connection: the SDK copied
- * the params, so the call's attempts could not be matched to it. Its
- * cancellation still reached the request (1, and the ledger's own watch on
- * `notifications/cancelled`).
+ * In dev mode, a ticket that no request was matched to by the time the call
+ * settled, when a `tools/call` request DID go out, is named once per
+ * connection: the SDK rebuilt the params without the marker, so the call's
+ * attempts could not be matched to it. Its cancellation still reached the
+ * request (1, and the ledger's own watch on `notifications/cancelled`). Under
+ * `'app-authorized'` such a request is never sent at all
+ * (`replayUnavailable.ts`).
  */
+import type { CallVerdict } from './replay.js';
 import type { RequestLedger } from './requestLedger.js';
-/** A call that has been opened: the signal its SDK request runs under, and how to close it. */
-export interface OpenCall {
+/** A call that has been opened: the params to send, the signal its SDK request runs under, and how to close it. */
+export interface OpenCall<P extends object = object> {
+    /**
+     * What to hand the SDK: the call's params, with its private marker in
+     * `_meta` when a ledger watches the connection (`callMarker.ts`). The
+     * transport takes the marker out again: the server never sees it.
+     */
+    readonly params: P;
     /** What cancels the SDK request — absent when nothing can. */
     readonly signal?: AbortSignal;
-    /** The call settled: undo the link, cut a series still sending, check the ticket was bound. */
-    close(): void;
+    /**
+     * The call failed with `error` (`verdict` says how far it got): the error it
+     * fails with — `error` itself, or, under `'app-authorized'`, footprintjs's
+     * `UnknownEffectError` with `error` as its `cause` when the call genuinely
+     * lacked an answer somewhere (see 5 above).
+     */
+    failed(error: unknown, verdict: CallVerdict): unknown;
+    /**
+     * The call settled with `verdict`: leave it for the record, settle it in the
+     * ledger (its answer is no longer awaited), undo the link, cut a series
+     * still sending, check its request was matched.
+     */
+    close(verdict: CallVerdict): void;
 }
 /**
  * Open one call.
  *
- * @param params the request's params object — the SDK hands this very object to
- *   the transport, which is how the ledger knows the request is this call's.
+ * @param params the request's params. The call sends them marked
+ *   (`OpenCall.params`): the marker, not the object, is how the ledger knows
+ *   the request is this call's — it survives an SDK that copies the params.
  * @param ctx the call's context: its signal, and the run's evidence port if any.
  * @param clientSignal the client's own `signal` (`McpClientOptions.signal`).
  * @param ledger the connection's ledger, when the library built its transport.
  * @param server the client's name, for the dev-mode note.
  */
-export declare function openCall(params: object, ctx: unknown, clientSignal: AbortSignal | undefined, ledger: RequestLedger | undefined, server: string): OpenCall;
+export declare function openCall<P extends object>(params: P, ctx: unknown, clientSignal: AbortSignal | undefined, ledger: RequestLedger | undefined, server: string): OpenCall<P>;
 //# sourceMappingURL=callLifetime.d.ts.map

package/dist/types/mcp/callLifetime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"callLifetime.d.ts","sourceRoot":"","sources":["../../../src/mcp/callLifetime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,oBAAoB,CAAC;AAEvE,+FAA+F;AAC/F,MAAM,WAAW,QAAQ;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,+FAA+F;IAC/F,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,OAAO,EACZ,YAAY,EAAE,WAAW,GAAG,SAAS,EACrC,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,MAAM,EAAE,MAAM,GACb,QAAQ,CAsBV"}
+{"version":3,"file":"callLifetime.d.ts","sourceRoot":"","sources":["../../../src/mcp/callLifetime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAOH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,oBAAoB,CAAC;AAEvE,mHAAmH;AACnH,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACjD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC;IACtD;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EACvC,MAAM,EAAE,CAAC,EACT,GAAG,EAAE,OAAO,EACZ,YAAY,EAAE,WAAW,GAAG,SAAS,EACrC,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,MAAM,EAAE,MAAM,GACb,QAAQ,CAAC,CAAC,CAAC,CA0Cb"}

package/dist/types/mcp/callMarker.d.ts

@@ -0,0 +1,44 @@
+/**
+ * callMarker — a library-private marker that ties one MCP tool call to the one
+ * request the SDK sends for it, whatever the SDK copies on the way.
+ *
+ * Pattern: mark at the call, take at the transport.
+ * Role:    The correlation hop of the request ledger (`requestLedger.ts`). The
+ *          call puts its marker in the request's own `_meta` bag
+ *          (`markParams`); the MCP SDK carries `_meta` through to the
+ *          transport — the very object, or a copy of it (`structuredClone`, a
+ *          spread) — and the ledger's watched `send` takes the marker out again
+ *          (`takeMarker`) before the transport serializes the request. The
+ *          server receives the bytes it always did: the marker never leaves the
+ *          client.
+ *
+ * An object's identity does not survive a copy; a string inside it does. So an
+ * SDK that copies the params still delivers the marker, and the request is
+ * matched to its call by the call's own word, never by guessing from content
+ * (two calls with the same arguments are the case content matching gets wrong).
+ * An SDK that rebuilds the params and drops `_meta` delivers nothing: the
+ * request then matches no call, and the ledger says so (`requestLedger.ts`).
+ */
+/** The `_meta` key the marker rides under. Never sent: `takeMarker` removes it. */
+export declare const CALL_MARKER_KEY = "agentfootprint/call-ref";
+/**
+ * `params` with `marker` added to its `_meta` bag: a new object, with every
+ * other key in its place; `params` itself is not changed. A `_meta` that was
+ * absent is added, after the other keys, so `takeMarker` can remove it whole.
+ */
+export declare function markParams<P extends object>(params: P, marker: string): P;
+/** What `takeMarker` found: the marker, when the message carried one, and the message to send. */
+export interface TakenMarker {
+    readonly marker?: string;
+    /** The message without the marker, or the message itself when it carried none. */
+    readonly message: unknown;
+}
+/**
+ * The marker a JSON-RPC message carries in `params._meta`, and the message
+ * without it. The message is never changed in place: the SDK's object stays
+ * the SDK's. Without the marker, the params are what they were before
+ * `markParams`: a `_meta` the marker alone filled is removed, and any other
+ * entry, the SDK's own included, keeps its place.
+ */
+export declare function takeMarker(message: unknown): TakenMarker;
+//# sourceMappingURL=callMarker.d.ts.map

package/dist/types/mcp/callMarker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callMarker.d.ts","sourceRoot":"","sources":["../../../src/mcp/callMarker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,mFAAmF;AACnF,eAAO,MAAM,eAAe,4BAA4B,CAAC;AAEzD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,CAAC,CAGzE;AAED,kGAAkG;AAClG,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAsBxD"}

package/dist/types/mcp/index.d.ts

@@ -11,5 +11,7 @@ export { mockMcpClient, type MockMcpClientOptions, type MockMcpTool } from './mo
 export { gatewayTransport, GatewayAuthorizationRequiredError, type GatewayTransportOptions, } from './gatewayTransport.js';
 export { retryingFetch } from './throttleRetry.js';
 export type { RetryOnThrottle, ThrottleFetch, ThrottleRetryInfo, ThrottleRetryOptions, } from './throttleRetry.js';
+export type { McpReplayDeduplication, McpReplayKind, McpReplayOptions, McpReplayPolicy, McpReplayTool, } from './replay.js';
+export { McpReplayUnavailableError, type McpReplayUnavailableReason } from './replayUnavailable.js';
 export type { McpCallToolResult, McpClient, McpClientOptions, McpConnection, McpConnectionOptions, McpSdk, McpGatewayTransport, McpHttpTransport, McpStdioTransport, McpTransport, McpSdkClient, McpServeOptions, McpServeHandle, McpServeTransport, McpHttpServeTransport, McpStdioServeTransport, McpSdkServer, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/mcp/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAChG,OAAO,EACL,gBAAgB,EAChB,iCAAiC,EACjC,KAAK,uBAAuB,GAC7B,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EACV,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,oBAAoB,EACpB,MAAM,EACN,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,GACb,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAChG,OAAO,EACL,gBAAgB,EAChB,iCAAiC,EACjC,KAAK,uBAAuB,GAC7B,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EACV,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EACV,sBAAsB,EACtB,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,aAAa,GACd,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,yBAAyB,EAAE,KAAK,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACpG,YAAY,EACV,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,oBAAoB,EACpB,MAAM,EACN,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/types/mcp/mcpClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcpClient.d.ts","sourceRoot":"","sources":["../../../src/mcp/mcpClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAEhB,oBAAoB,EAKrB,MAAM,YAAY,CAAC;AAoBpB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,oBAAoB,GAAG,OAAO,CAAC,SAAS,CAAC,CAmDjG"}
+{"version":3,"file":"mcpClient.d.ts","sourceRoot":"","sources":["../../../src/mcp/mcpClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAKH,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAEhB,oBAAoB,EAKrB,MAAM,YAAY,CAAC;AAiCpB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,oBAAoB,GAAG,OAAO,CAAC,SAAS,CAAC,CA8DjG"}

package/dist/types/mcp/replay.d.ts

@@ -0,0 +1,292 @@
+/**
+ * replay — who may send an MCP tool call again, and what is known of what each
+ * attempt did: two facts, decided apart and recorded apart.
+ *
+ * Pattern: a declaration read once + one permission rule + one accumulator.
+ * Role:    Layer-3 tool transport. `mcpClient({ replay })` reads the app's
+ *          declaration (`replayDeclarationOf`) when the client is built. The
+ *          call's retry series (`throttleRetry.ts` · `Series`) asks `permit`
+ *          before every repeat and records the answer beside the attempt;
+ *          `SeriesKnowledge` carries what is known of the series' effect from
+ *          one attempt to the next.
+ *
+ * ── THE LAW ──────────────────────────────────────────────────────────────────
+ * PERMISSION to repeat comes only from the app: the (server, tool) pairs it
+ * declares — the server is the client the declaration is given to — and the
+ * failure kinds each tool may be repeated on. Never from the model, a tool's
+ * description or a server's annotations (`readOnlyHint`): nothing here reads
+ * them. It is configuration, read once when the client is built — never a
+ * per-call question.
+ *
+ * KNOWLEDGE of whether an attempt ran comes only from the record and from an
+ * established service guarantee. No reply this library reads is one. A 429 is
+ * not: RFC 6585 §4 defines it as rate limiting, and `Retry-After` says when to
+ * ask again, not that asking is safe. AgentCore Runtime's session-busy body is
+ * not either: AWS documents a retryable conflict while a session starts or
+ * stops, and the body is matched by its code and words, which a server behind
+ * the runtime can send after it ran the call. So every attempt that was sent
+ * and did not complete is `unknown`; `none` is only a request never sent. A
+ * vendor's own SDK may retry its own 429s because the vendor documents its own
+ * service; a generic MCP client cannot assume that of an arbitrary server.
+ *
+ * Neither is read from the other: a permission never makes an effect known,
+ * and an effect never grants a permission.
+ *
+ * ── WHAT A REPEAT IS ─────────────────────────────────────────────────────────
+ * The same validated, authorized request sent again: the same body — the same
+ * arguments — to the same server, in the same session, as the same identity.
+ * Nothing is re-planned. A credential the library vends, or a signature, is
+ * made afresh for each attempt (signatures expire), for that same identity.
+ *
+ * ── THE POLICIES ─────────────────────────────────────────────────────────────
+ *   'compatibility' — the default, kept in 12.0: today's behaviour by name. A
+ *       429 is repeated for every tool, on the ASSUMPTION that the server
+ *       refused it before running it. Each such repeat records that
+ *       assumption; the attempt's effect stays `unknown`, and the caller sees
+ *       the error it always did. It gains none of the strict policy's
+ *       guarantees: it never establishes that answers are seen or that
+ *       requests are matched to their calls.
+ *   'app-authorized' — opt-in, by name only: a 429 or a network failure is
+ *       repeated only when the app's entry for the tool names it. What the
+ *       caller sees follows footprintjs's law
+ *       (`RequestReplay` · `uncertain`, `callLifetime.ts`): a received refusal
+ *       or error keeps the server's error as it came, its effect still
+ *       `unknown`; a call that genuinely lacked an answer somewhere — an
+ *       attempt with no response, or a request accepted over HTTP whose
+ *       JSON-RPC answer never came — and then fails, fails with
+ *       `UnknownEffectError`, its final error the cause. That needs each
+ *       request matched to its call and each answer seen; a connection that
+ *       cannot give both refuses the tool call before its request is sent
+ *       (`replayUnavailable.ts`), so the contract never silently weakens. It
+ *       never falls back to 'compatibility', and nothing chooses it from the
+ *       transport.
+ *
+ * Under both, the adapter the app chose retries its own refusal within the
+ * budget — AgentCore's session-busy reply — as the ADAPTER's policy, on an
+ * assumption it records the same way (`permission: { by: 'adapter', assumes }`),
+ * never as evidence. And THE SIDE-EFFECT GUARD holds: a tool the app declares
+ * as making changes is never repeated automatically unless the server is
+ * declared to deduplicate by an idempotency key the call carries —
+ * footprintjs's law, a retry of an effect without a key can apply it twice. A
+ * key protects only when the server uses it; the library cannot check that.
+ *
+ * The protocol's own requests (`initialize`, `tools/list`, notifications) run
+ * no tool. The declaration does not govern them, and a 429 on one is asked
+ * again under both policies, as it always was. They file no record.
+ */
+import type { ToolRequestEffect, ToolRequestPermission, ToolRequestReason, ToolRequestReplayKind } from '../events/payloads.js';
+/**
+ * Which rule decides whether a tool call is sent again after a refusal or a
+ * failure. `'compatibility'` is the default, kept in 12.0: it keeps its stated
+ * retry assumption and gains none of the strict guarantees. `'app-authorized'`
+ * applies only when written, and never falls back to `'compatibility'`.
+ */
+export type McpReplayPolicy = 'app-authorized' | 'compatibility';
+/**
+ * A failure kind the app may declare a tool repeatable on: HTTP 429
+ * (`'throttle'`), or a request that failed in transport without an answer
+ * (`'network'`, footprintjs's category: a dropped or refused connection, or a
+ * timeout raised below the retry series). Either may have run on the server, so
+ * a repeat after it leaves the call's effect `unknown`.
+ */
+export type McpReplayKind = ToolRequestReplayKind;
+/** One tool's entry in {@link McpReplayOptions.tools}. */
+export interface McpReplayTool {
+    /**
+     * The failure kinds this tool may be sent again on. Default: none. Under
+     * `'compatibility'` a 429 is repeated without it, recorded as an assumption;
+     * under `'app-authorized'` only what is named here is repeated.
+     */
+    readonly on?: readonly McpReplayKind[];
+    /**
+     * `true` — this tool makes changes. It is then never sent again
+     * automatically, under either policy, unless the server is declared to
+     * deduplicate (`deduplicates`) and the call carries the key.
+     */
+    readonly changes?: boolean;
+}
+/**
+ * How the server deduplicates a tool call: by an idempotency key the call
+ * carries in the named argument. Declare it only when the server does; a key
+ * protects only when the server uses it.
+ */
+export interface McpReplayDeduplication {
+    /**
+     * The argument that carries the key — present as a non-empty string in the
+     * call for a repeat to be allowed. Set it in your code (a `toolMiddleware`
+     * that writes it from the call), never from what the model wrote: a key the
+     * model reuses for a different operation makes the server drop that one.
+     */
+    readonly argument: string;
+}
+/**
+ * The app's replay declaration for one MCP server — its client. Read once when
+ * the client is built; a field it does not know is refused there, so a
+ * misspelled `changes` cannot quietly switch the side-effect guard off.
+ */
+export interface McpReplayOptions {
+    /**
+     * Default `'compatibility'`, in 12.0 as in 11.x. An explicit
+     * `'app-authorized'` never falls back to it.
+     */
+    readonly policy?: McpReplayPolicy;
+    /** The tools of this server, by the name the server lists them under. */
+    readonly tools?: Readonly<Record<string, McpReplayTool>>;
+    /** The server deduplicates by an idempotency key the call carries. */
+    readonly deduplicates?: McpReplayDeduplication;
+}
+interface ToolEntry {
+    readonly on: ReadonlySet<McpReplayKind>;
+    readonly changes: boolean;
+}
+/** @internal A declaration, read and checked once. */
+export interface ReplayDeclaration {
+    readonly policy: McpReplayPolicy;
+    readonly tools: ReadonlyMap<string, ToolEntry>;
+    /** The argument the server deduplicates by, when it is declared to. */
+    readonly keyArgument?: string;
+}
+/** @internal No declaration: the compatibility policy, no tool named. */
+export declare const COMPATIBILITY: ReplayDeclaration;
+/**
+ * @internal `options` read as a declaration — `undefined` is the compatibility
+ * policy with nothing named.
+ *
+ * @throws TypeError naming the field, never echoing a value, for anything the
+ *   rule cannot mean: an unknown field, a policy or kind it does not know, an
+ *   argument name that is not one.
+ */
+export declare function replayDeclarationOf(options: unknown, where: string): ReplayDeclaration;
+/**
+ * @internal Whether the declaration needs a retry series even with the 429
+ * rule off (`retryOnThrottle: false`): a tool declared repeatable on
+ * `'network'`, or the `'app-authorized'` policy — its record and its "may have
+ * run" rest on the series.
+ */
+export declare function needsSeries(declaration: ReplayDeclaration): boolean;
+/**
+ * @internal One request, as the permission rule needs it: the protocol's own,
+ * or a `tools/call` — its tool when the body names one, and whether its
+ * arguments carry the key the server deduplicates by.
+ */
+export type ReplayTarget = {
+    readonly kind: 'protocol';
+} | {
+    readonly kind: 'tool';
+    readonly name?: string;
+    readonly keyCarried: boolean;
+};
+/**
+ * @internal `body` — the request exactly as it will be sent — read as a
+ * target. A declaration that names nothing under `'compatibility'` decides the
+ * same for every request, so its bodies are never parsed.
+ */
+export declare function replayTargetOf(body: unknown, declaration: ReplayDeclaration): ReplayTarget;
+/** @internal A failure the series met, as the permission rule reads it. */
+export interface MetFailure {
+    /** A refusal a rule recognised (`throttle`, `session-busy`), or a request that failed in transport. */
+    readonly kind: 'throttle' | 'session-busy' | 'network';
+    /**
+     * What the adapter that recognised this refusal assumes in retrying it, as
+     * its own policy — set on its rule. Never evidence of the attempt's effect.
+     */
+    readonly assumes?: 'refused-before-execution';
+}
+/** @internal Why the series did not ask again, by the rule. */
+export type ReplayDeclined = Extract<ToolRequestReason, 'not-retryable' | 'not-permitted' | 'changes-without-key'>;
+/**
+ * @internal The rule's answer: ask again, with what allowed it — absent for a
+ * protocol request, which has no record — or not, and why.
+ */
+export type ReplayDecision = {
+    readonly repeat: true;
+    readonly permission?: ToolRequestPermission;
+} | {
+    readonly repeat: false;
+    readonly declined: ReplayDeclined;
+};
+/** @internal A thrown failure the rule can read: footprintjs's `network` category, or nothing. */
+export declare function thrownFailure(error: unknown): MetFailure | undefined;
+/**
+ * @internal THE rule: may the series send `target` again after `failure`?
+ * Asked before every repeat; the budget is asked after it.
+ */
+export declare function permit(declaration: ReplayDeclaration, target: ReplayTarget, failure: MetFailure): ReplayDecision;
+/**
+ * @internal What is known of a whole series' effect, one attempt at a time.
+ * Uncertainty survives: once any attempt is `unknown`, the series is, whatever
+ * later attempts show — a proven refusal does not resolve it, and a success
+ * does not prove the operation happened only once. Evidence that something ran
+ * (`applied`) is never erased by a later failure.
+ */
+export declare class SeriesKnowledge {
+    private unknown;
+    private applied;
+    note(effect: ToolRequestEffect): void;
+    get effect(): ToolRequestEffect;
+}
+/** @internal How `callTool` settled, as the call reads it. */
+export type CallVerdict = 'completed' | 'tool-error' | 'failed';
+/**
+ * @internal One `tools/call` request's replay facts, shared by the series that
+ * sends it, the ledger that watches its answer, and the call that waits for it
+ * — the ledger hands all three the same object (`requestLedger.ts`).
+ *
+ * TWO LAYERS, KEPT APART. The series sees HTTP: whether an attempt got a
+ * response at all, and the status of the one it delivered. A response is not
+ * the MCP call's answer — a 202, or a stream, can be accepted and never carry
+ * it — so the ledger watches the connection's incoming messages for the
+ * JSON-RPC response to THIS request's id. And "its effect is unknown" is not
+ * "it lacked an answer": a received 429 or error is an answer whose effect is
+ * unknown.
+ *
+ * Each fact is written once, by its owner: the series (what it sent, whether an
+ * attempt lacked any response, what it delivered, the policy), the ledger (the
+ * logical answer), the call (how it settled).
+ */
+export declare class RequestReplay {
+    readonly id: string | number;
+    private requests;
+    private appAuthorized;
+    private attemptUnanswered;
+    private delivered;
+    private logical;
+    private settled;
+    private failedAsMayHaveRun;
+    /**
+     * @param id the request's JSON-RPC id, how its answer is found.
+     * @param watched whether the connection's incoming messages are observed —
+     *   without that, the logical layer is unknown and never decides anything.
+     */
+    constructor(id: string | number, watched: boolean);
+    /** The series sent the request once more. */
+    sentOne(): void;
+    /** The series runs under the `'app-authorized'` policy. */
+    appAuthorizedPolicy(): void;
+    /**
+     * The series: an attempt genuinely lacked an answer — no response arrived
+     * (a lost connection, a timeout, a cut). A received refusal is never this.
+     */
+    noAnswer(): void;
+    /** The series handed the MCP SDK a response with this status. */
+    deliveredStatus(status: number): void;
+    /** The ledger: the JSON-RPC response to this request's id arrived. */
+    answered(): void;
+    /** The call settled; `mayHaveRun` when it failed as "may have run". The first word stands. */
+    settle(verdict: CallVerdict, mayHaveRun: boolean): void;
+    get sent(): number;
+    /**
+     * Under `'app-authorized'`, a call that does not complete fails as "may have
+     * run" when the call genuinely lacked an answer somewhere: an attempt got no
+     * response, or the HTTP layer accepted the request (a 2xx) and the JSON-RPC
+     * response never came. A chain of received refusals and errors is an answer
+     * throughout: it keeps the server's error.
+     */
+    get uncertain(): boolean;
+    /** The HTTP layer took the request (2xx), and the logical answer never arrived. */
+    private get acceptedWithoutAnswer();
+    get verdict(): CallVerdict | undefined;
+    get mayHaveRun(): boolean;
+}
+export {};
+//# sourceMappingURL=replay.d.ts.map

package/dist/types/mcp/replay.d.ts.map

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

package/dist/types/mcp/replayUnavailable.d.ts

@@ -0,0 +1,69 @@
+/**
+ * replayUnavailable — when a connection cannot keep the `'app-authorized'`
+ * contract, a tool call under it is refused BEFORE its request is sent, and the
+ * error says why.
+ *
+ * Pattern: a readiness rule + one typed refusal.
+ * Role:    Under `'app-authorized'`, a call that genuinely lacked an answer and
+ *          then fails is raised as "may have run" (`callLifetime.ts`). That
+ *          rests on two things the library must ESTABLISH for every call,
+ *          never assume:
+ *
+ *   1. ITS REQUEST IS MATCHED to the call, by the call's private marker, taken
+ *      at the transport's `send` (`callMarker.ts`, `requestLedger.ts`).
+ *      - `'requests-unwatched'`: the library cannot watch this transport's
+ *        `send` at all (stdio, or a transport that refuses the wrap).
+ *      - `'request-unmatched'`: a request reached `send` without its call's
+ *        marker (an SDK that rebuilt the params and dropped `_meta`), so it
+ *        cannot be tied to any call. Checked on every `tools/call`, so a match
+ *        lost after the connection initialized is refused too.
+ *   2. ITS ANSWER IS SEEN: the JSON-RPC response to the request's id, read as
+ *      it arrives. This is checked once the connection is initialized: the
+ *      `initialize` answer must have passed the library's observer.
+ *      - `'answers-unobserved'`: it did not. An MCP SDK whose `connect`
+ *        REPLACES the transport's `onmessage` handler instead of keeping it
+ *        leaves the observer out. SDK 1.10's `Protocol.connect` does, when
+ *        run; reading the source finds the same through 1.13. The rule tests
+ *        the behaviour, never a version number.
+ *
+ * Without either, a request the server accepted and never answered would reach
+ * the caller as a plain timeout: the strict contract, silently weakened. So the
+ * tool call is refused instead, and its request is not sent. Only tool
+ * invocations (`tools/call`) are refused: connecting (`initialize`) and listing
+ * tools ran before them and may already have reached the server (on `stdio`,
+ * the server process has started). The policy never falls back to
+ * `'compatibility'`, and a refused request is never sent again to recover its
+ * match. `'compatibility'` asks none of this and keeps its behaviour.
+ */
+/** Why a call under `'app-authorized'` was refused before it was sent. */
+export type McpReplayUnavailableReason = 'requests-unwatched' | 'answers-unobserved' | 'request-unmatched';
+/**
+ * A tool call refused before its request was sent, because this connection
+ * cannot keep the `'app-authorized'` replay contract (`reason`). The tool
+ * request never reached the server; connecting and listing tools may have.
+ * Names the server and the tool, never an argument.
+ */
+export declare class McpReplayUnavailableError extends Error {
+    readonly reason: McpReplayUnavailableReason;
+    readonly server: string;
+    readonly tool: string;
+    readonly code: "ERR_MCP_REPLAY_UNAVAILABLE";
+    /**
+     * This tool request was not sent: the refusal came before it left the
+     * client. It says nothing of the connection: `initialize` and `tools/list`
+     * ran before it, and on `stdio` the server process was started.
+     */
+    readonly sent: false;
+    constructor(reason: McpReplayUnavailableReason, server: string, tool: string);
+}
+/**
+ * Why a connection cannot take a call under `'app-authorized'` before anything
+ * is sent — `undefined` when it can. `ledger` is the connection's request
+ * ledger: absent when the library could not watch the transport's requests.
+ * A request that reaches the transport without its marker is refused there, by
+ * the ledger (`'request-unmatched'`).
+ */
+export declare function unavailableBeforeSending(ledger: {
+    readonly answersObserved: boolean;
+} | undefined): McpReplayUnavailableReason | undefined;
+//# sourceMappingURL=replayUnavailable.d.ts.map

package/dist/types/mcp/replayUnavailable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replayUnavailable.d.ts","sourceRoot":"","sources":["../../../src/mcp/replayUnavailable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,0EAA0E;AAC1E,MAAM,MAAM,0BAA0B,GAClC,oBAAoB,GACpB,oBAAoB,GACpB,mBAAmB,CAAC;AAcxB;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAUhD,QAAQ,CAAC,MAAM,EAAE,0BAA0B;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM;IAXvB,QAAQ,CAAC,IAAI,+BAAyC;IACtD;;;;OAIG;IACH,QAAQ,CAAC,IAAI,QAAkB;gBAGpB,MAAM,EAAE,0BAA0B,EAClC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM;CASxB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE;IAAE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,GACxD,0BAA0B,GAAG,SAAS,CAIxC"}