agentfootprint 11.1.1 → 11.2.0

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

@@ -1,5 +1,6 @@
 /**
- * throttleRetry — when an MCP server says "too many requests", wait and ask again.
+ * throttleRetry — when an MCP server refuses a request before running it, wait
+ * and ask again.
  *
  * ── Why this exists ──────────────────────────────────────────────────────────
  * Managed MCP gateways enforce per-principal rate limits. A throttled
@@ -43,6 +44,43 @@
  * that would have died during the wait is simply never the one reused. The
  * gateway secrecy invariant is untouched: each attempt vends, applies, drops.
  *
+ * ── The loop is footprintjs's attempt runner, one series per call ────────────
+ * Each call runs ONE `attempt()` series (footprintjs, used as it ships). Its
+ * runner makes an attempt record per try; they stay inside this module for
+ * now — only `onRetry`, before each wait, reaches a caller. An attempt sends
+ * the request once, and an attempt that got a RESPONSE is not an operation
+ * that succeeded: a 503 is delivered as the answer it was, never retried.
+ * A response a rule's decision recognises is thrown as a refusal that names
+ * its kind, and the policy's `retryOn` accepts those refusals and nothing
+ * else — so a 5xx, a dropped connection or a timeout ends the series on the
+ * attempt it happened in, as it always did. When the
+ * series ends on a refusal (attempts spent, a ceiling reached, no time left),
+ * the refusal's response is delivered as the server sent it: the caller sees
+ * the 429, never an error of ours.
+ *
+ * ── A fetch that already retries is JOINED, never wrapped ────────────────────
+ * A transport whose own fetch runs a series (AgentCore Runtime's session-busy
+ * retry) says how to rebuild itself with one more rule (`joinableRetry`).
+ * `retryingFetch` over such a fetch — what `mcpClient` applies to every http
+ * transport — adds its 429 rule to THAT series instead of starting a second
+ * one around it. One series means one attempt count, one waiting total and one
+ * deadline per call, by construction: the layers can never multiply requests.
+ * The series' FIRST rule holds the call's budget — its `maxAttempts`,
+ * `maxWaitMs` and `maxElapsedMs` bound every attempt and wait, whatever the
+ * reason. A rule that joins keeps its own values as limits on its own kind:
+ * they can stop its retries sooner, never make the call longer.
+ *
+ * ── The wait: a stated one wins, whole ───────────────────────────────────────
+ * Each retry's wait is `statedWaitFirst(retry-after, exponentialBackoff({ …,
+ * maxDelayMs }))`: the server's `Retry-After` when it sent one, else our
+ * jittered backoff, whose CEILING is capped at `maxDelayMs` before the draw
+ * (so capped waits keep their jitter). The cap is on the SCHEDULE only —
+ * never on a stated wait — so the footprintjs policy's `maxBackoffMs`,
+ * which would cut every wait and send the request again before the server
+ * said it may, is left unset. A stated wait too long for `maxWaitMs` or the
+ * deadline is never shortened either: the series stops, and the 429 is
+ * delivered as the server sent it.
+ *
  * Pattern: Decorator over `fetch`. Role: Layer-3 tool transport.
  */
 /**
@@ -54,22 +92,50 @@
  * supplies fewer.
  */
 export type ThrottleFetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * Which refusal a retry answers: HTTP 429 (`'throttle'`), or AgentCore
+ * Runtime's "session operation in progress" (`'session-busy'`).
+ */
+export type RetryKind = 'throttle' | 'session-busy';
 /** Reported to {@link ThrottleRetryOptions.onRetry} before each wait. */
 export interface ThrottleRetryInfo {
+    /** Which refusal this retry answers. */
+    readonly kind: RetryKind;
     /** The attempt about to START. `2` is the first retry. */
     readonly attempt: number;
-    /** Ceiling in force for this call, including the first attempt. */
+    /** Ceiling in force for this refusal, including the first attempt. */
     readonly maxAttempts: number;
     /** How long we are about to wait, in milliseconds. */
     readonly waitMs: number;
     /** What the server's `Retry-After` asked for, when it sent one. Absent
      *  means the wait below is our own jittered backoff. */
     readonly retryAfterMs?: number;
-    /** The endpoint being retried. Carries no credential: the URL is the URL
-     *  the transport was built with, never a signed or tokenised variant. */
+    /**
+     * The ORIGIN of the endpoint being retried — scheme, host and port, nothing
+     * else. Never its path, user info (`user:pass@`), query or fragment: a
+     * token, a credential or a customer id can ride in any of them. The empty
+     * string when the URL has no origin (a relative one).
+     */
     readonly url: string;
+    /**
+     * The {@link ThrottleRetryOptions.endpointLabel} you declared for this
+     * endpoint — absent when you declared none. Never derived from the URL.
+     */
+    readonly endpoint?: string;
 }
-/** Fine-tuning for {@link McpClientOptions.retryOnThrottle}. */
+/**
+ * Fine-tuning for {@link McpClientOptions.retryOnThrottle}, and — with its own
+ * defaults — for `agentCoreRuntimeMcpTransport`'s `retry`. The defaults below
+ * are `retryOnThrottle`'s.
+ *
+ * Every limit here is the CALL's — unless this retry joins a series a
+ * transport already runs (an AgentCore Runtime transport under `mcpClient`).
+ * Then the transport's own values are the call's limits, and these limit only
+ * the 429 retries inside them: each can stop a 429 retry sooner (a 429 is
+ * retried only while the call has made fewer attempts than `maxAttempts`, has
+ * waited less than `maxWaitMs`, …), never make the call longer. The deadline
+ * that cuts a request in flight is the transport's `maxElapsedMs`.
+ */
 export interface ThrottleRetryOptions {
     /** Total attempts including the first. Default 3. Minimum 1. */
     readonly maxAttempts?: number;
@@ -84,15 +150,62 @@ export interface ThrottleRetryOptions {
      */
     readonly maxWaitMs?: number;
     /**
-     * Called before each wait. The per-attempt visibility hook, matching the
-     * contract `withRetry` and `withCredentialRetry` already use — a decorator
-     * at a transport boundary reports to its consumer, and emits no events of
-     * its own.
+     * A deadline for the whole call, in milliseconds from its start — requests
+     * included, not just waits. A wait that would end past it is never begun
+     * (the refusal is delivered at once), and a request still waiting for its
+     * answer when it passes is cut: the call fails with the deadline's error.
+     * Default: none — `maxWaitMs` is the default rail.
+     */
+    readonly maxElapsedMs?: number;
+    /**
+     * The ceiling of the first wait our own backoff draws, in milliseconds, when
+     * the server stated none. Default 200.
+     */
+    readonly baseDelayMs?: number;
+    /** How much each backoff ceiling grows over the last. Default 2. At least 1. */
+    readonly multiplier?: number;
+    /**
+     * How a backoff wait is drawn below its ceiling: `'equal'` (the default)
+     * waits between half the ceiling and all of it, `'full'` anywhere from zero
+     * up to it, `'none'` exactly it. Jitter is what keeps clients refused at the
+     * same moment from asking again at the same moment.
+     */
+    readonly jitter?: 'none' | 'equal' | 'full';
+    /**
+     * The most one of OUR backoff waits may last, in milliseconds. Default: none.
+     *
+     * It caps the scheduled wait's ceiling before the jittered draw, so capped
+     * waits still spread between half the cap and the cap. It never caps a
+     * server's `Retry-After` — unlike footprintjs's `RetryPolicy.maxBackoffMs`,
+     * which caps every wait. A stated wait is waited whole; asking sooner than
+     * the server said would only spend an attempt on a refusal it announced.
+     */
+    readonly maxDelayMs?: number;
+    /**
+     * A name for this endpoint, declared by you, that `onRetry` reports as
+     * `endpoint` — so a log line can say which server was retried without
+     * carrying any part of its URL past the origin. 1–128 characters, none of
+     * them control characters. Absent, `onRetry` has no `endpoint` field; the
+     * library never makes one up from the URL.
+     */
+    readonly endpointLabel?: string;
+    /**
+     * A notification before each wait — and, today, the ONLY retry report a
+     * caller gets. It is told the refusal's kind, the attempt about to start,
+     * the wait, the endpoint's origin and the label you declared for it
+     * (`endpointLabel`) — never the URL's path, the request's
+     * arguments or the server's answer. The series' final outcome and the
+     * attempt records footprintjs's runner makes for each try are NOT passed on
+     * yet. The contract matches what `withRetry` and `withCredentialRetry`
+     * already use: a decorator at a transport boundary reports to its consumer,
+     * and emits no events of its own.
      *
      * A retried call is not invisible without this: the wait lands inside the
      * tool's `stream.tool_end` `durationMs`, and an exhausted retry still
      * reaches the model with `error: true`. This hook is what turns "that call
      * was slow" into "that call was throttled twice".
+     *
+     * A throw from it is isolated: the call goes on as if it had returned.
      */
     readonly onRetry?: (info: ThrottleRetryInfo) => void;
 }
@@ -123,12 +236,66 @@ export interface RetryVerdict {
  * AgentCore Runtime's documented "session operation in progress" refusal,
  * which lives with that vendor's adapter (`adapters/mcp/agentcoreRuntime/`).
  * Each stays ONE small function, so a retry has exactly one place it is
- * decided — and one place to route it when retries are written down as
- * attempts.
+ * decided — and each attempt is written down as one footprintjs attempt
+ * record.
+ */
+export type RetryDecision = (response: Response, 
+/**
+ * The request's signal. It fires when the caller cancels or the call's
+ * deadline passes; a decision that reads the body must stop reading then,
+ * and release what it read from.
  */
-export type RetryDecision = (response: Response) => RetryVerdict | undefined | Promise<RetryVerdict | undefined>;
+signal?: AbortSignal) => RetryVerdict | undefined | Promise<RetryVerdict | undefined>;
 /** HTTP 429, with the server's own `Retry-After` when it sent one. */
 export declare function throttled(response: Response): RetryVerdict | undefined;
+/**
+ * @internal What a rule's options fall back to. `Infinity` means none: no
+ * deadline (`maxElapsedMs`), no cap on the scheduled wait (`maxDelayMs`).
+ */
+export interface RetryDefaults {
+    readonly maxAttempts: number;
+    readonly maxWaitMs: number;
+    readonly maxElapsedMs: number;
+    readonly baseDelayMs: number;
+    readonly multiplier: number;
+    readonly jitter: 'none' | 'equal' | 'full';
+    readonly maxDelayMs: number;
+}
+/**
+ * `retryOnThrottle`'s defaults — unchanged since 8.11.0: 3 attempts, a 200 ms
+ * backoff doubling with equal jitter (100–200 ms, then 200–400 ms), never more
+ * than 10 s of waiting in total. No deadline and no cap on one wait.
+ */
+export declare const THROTTLE_RETRY_DEFAULTS: RetryDefaults;
+/**
+ * @internal One refusal a series may retry: the decision that recognises it,
+ * the kind it reports as, and the limits and backoff it retries by.
+ */
+export interface RetryRule {
+    readonly kind: RetryKind;
+    readonly decide: RetryDecision;
+    /** Total attempts while this refusal is the reason to go on. ≥ 1; `Infinity` is no count. */
+    readonly maxAttempts: number;
+    readonly maxWaitMs: number;
+    readonly maxElapsedMs: number;
+    readonly maxDelayMs: number;
+    readonly baseDelayMs: number;
+    readonly multiplier: number;
+    readonly jitter: 'none' | 'equal' | 'full';
+    /** The caller's own name for the endpoint, reported as `endpoint`. */
+    readonly endpointLabel?: string;
+    readonly onRetry?: (info: ThrottleRetryInfo) => void;
+}
+/**
+ * @internal A rule from a caller's options — `undefined` when retry is off
+ * (`false`). An option field left out, or set to `undefined`, takes its
+ * default. `maxAttempts` and `maxWaitMs` keep the clamps they always had (below
+ * 1 reads as 1, below 0 as 0).
+ *
+ * @throws TypeError, when the rule is BUILT, for a value the schedule cannot
+ *   mean — named by option, never echoing a value that is not a number.
+ */
+export declare function retryRule(kind: RetryKind, decide: RetryDecision, config: RetryOnThrottle | undefined, defaults: RetryDefaults, where: string): RetryRule | undefined;
 /**
  * Wrap a `fetch` so HTTP 429 responses are retried, honouring `Retry-After`.
  *
@@ -136,6 +303,10 @@ export declare function throttled(response: Response): RetryVerdict | undefined;
  * so a transport that passed no custom fetch keeps passing none and its
  * behaviour is byte-identical to before this existed.
  *
+ * When `inner` already runs a retry series of its own (an AgentCore Runtime
+ * transport's fetch), the 429 rule JOINS that series rather than wrapping it,
+ * so the two can never multiply requests — see the module note.
+ *
  * ── Why this is public ───────────────────────────────────────────────────────
  * `mcpClient({ transport })` applies it for you, ON by default. `mcpClient({
  * connection })` cannot: the library builds no transport on that arm, so there
@@ -157,26 +328,25 @@ export declare function throttled(response: Response): RetryVerdict | undefined;
  * @param inner the fetch to wrap. `undefined` means the global `fetch`,
  *   resolved at CALL time so a later polyfill still wins.
  * @param config `true` / `undefined` for the defaults, `false` to get `inner`
- *   back unchanged, or an object to tune the ceilings.
+ *   back unchanged, or an object to tune the ceilings and the backoff.
+ * @throws TypeError when an option is outside its range — here, when the fetch
+ *   is built, never at the first call.
  */
 export declare function retryingFetch(inner: ThrottleFetch | undefined, config: RetryOnThrottle | undefined): ThrottleFetch | undefined;
 /**
- * The bounded loop itself, asking `decide` of every response.
- *
- * {@link retryingFetch} is this loop asking {@link throttled}. A vendor adapter
- * whose service documents a refusal of its own — one made before anything ran —
- * passes its decision here instead of writing a second loop, so the ceilings,
- * the `Retry-After` rail, the replay check, the abort and the `onRetry` report
- * stay one implementation.
- *
- * `decide` is asked only when a retry could actually follow — attempts left, a
- * body that can be sent again, no abort — so a decision that has to read the
- * response pays for that only when its answer can matter.
- *
- * @internal Public to adapters, not to the door: the decision is the vendor's
- *   fact, and each one is reviewed against the license on {@link RetryDecision}.
+ * @internal Declare that `fetch` runs its retries in ONE series, and how to
+ * rebuild it with one more rule in that same series. `retryingFetch` joins such
+ * a fetch instead of wrapping it. A transport whose public fetch wraps its
+ * series (a session applied around it, its answers rewritten after it) uses
+ * this so the rule lands INSIDE that wrapping.
+ */
+export declare function joinableRetry(fetch: ThrottleFetch, join: (rule: RetryRule) => ThrottleFetch): ThrottleFetch;
+/**
+ * @internal The one series per call over `inner`, asking `rules` in order —
+ * `inner` itself when there are none. The first rule holds the call's budget;
+ * see the module note. The result is joinable.
  */
-export declare function retryingFetchWhen(inner: ThrottleFetch | undefined, config: RetryOnThrottle | undefined, decide: RetryDecision): ThrottleFetch | undefined;
+export declare function retryingFetchFor(inner: ThrottleFetch, rules: readonly RetryRule[]): ThrottleFetch;
 /**
  * `Retry-After` in either legal form: delta-seconds (`"2"`) or an HTTP-date
  * (`"Wed, 21 Oct 2026 07:28:00 GMT"`). Anything else is treated as absent so a

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

@@ -1 +1 @@
-{"version":3,"file":"throttleRetry.d.ts","sourceRoot":"","sources":["../../../src/mcp/throttleRetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAIH;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAI3F,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;4DACwD;IACxD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;6EACyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,gEAAgE;AAChE,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,IAAI,CAAC;CACtD;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,oBAAoB,CAAC;AA4B7D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,QAAQ,EAAE,QAAQ,KACf,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;AAElE,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,YAAY,GAAG,SAAS,CAItE;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,aAAa,GAAG,SAAS,EAChC,MAAM,EAAE,eAAe,GAAG,SAAS,GAClC,aAAa,GAAG,SAAS,CAE3B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,aAAa,GAAG,SAAS,EAChC,MAAM,EAAE,eAAe,GAAG,SAAS,EACnC,MAAM,EAAE,aAAa,GACpB,aAAa,GAAG,SAAS,CA2C3B;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAOpF"}
+{"version":3,"file":"throttleRetry.d.ts","sourceRoot":"","sources":["../../../src/mcp/throttleRetry.ts"],"names":[],"mappings":"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"}

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

@@ -180,11 +180,13 @@ export interface McpClientOptions {
      * What happens when the server says "too many requests" (HTTP 429). New in
      * 8.11.0, and **on by default**.
      *
-     * Default: retry up to 3 times, waiting as long as the server's
-     * `Retry-After` header asks (and, when it sends none, a jittered backoff),
-     * never longer than 10 seconds of waiting in total across one call. Set
-     * `false` to let a throttled call fail immediately, or pass an object to
-     * tune the ceilings and to learn when it happens:
+     * Default: up to 3 attempts, waiting as long as the server's `Retry-After`
+     * header asks (and, when it sends none, a backoff of 200 ms doubling, with
+     * equal jitter), never longer than 10 seconds of waiting in total across one
+     * call. Set `false` to let a throttled call fail immediately, or pass an
+     * object to tune the ceilings and the backoff (`baseDelayMs`, `multiplier`,
+     * `jitter`, `maxDelayMs`, a `maxElapsedMs` deadline) and to learn when it
+     * happens:
      *
      * ```ts
      * const gateway = await mcpClient({
@@ -192,12 +194,19 @@ export interface McpClientOptions {
      *   transport: gatewayTransport({ url, credentials }),
      *   retryOnThrottle: {
      *     maxAttempts: 5,
-     *     onRetry: ({ attempt, waitMs, retryAfterMs }) =>
-     *       log.warn({ attempt, waitMs, retryAfterMs }, 'gateway throttled'),
+     *     onRetry: ({ kind, attempt, waitMs, retryAfterMs }) =>
+     *       log.warn({ kind, attempt, waitMs, retryAfterMs }, 'gateway throttled'),
      *   },
      * });
      * ```
      *
+     * Each call is ONE retry series (footprintjs's attempt runner). When the
+     * transport's own fetch already retries — `agentCoreRuntimeMcpTransport`'s
+     * session-busy retry — this 429 retry joins that series instead of wrapping
+     * it: one attempt count, one waiting total and one deadline per call, with
+     * the transport's `retry` values as the call's overall limits and these as
+     * limits on the 429 retries inside them.
+     *
      * **Why this is on by default.** A 429 is a *pre-execution rejection* — the
      * rate limiter refused the request at the edge and the server never ran the
      * tool, so a retry cannot double-execute anything. That is not true of a

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

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

package/dist/types/strategies/attach.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../../../src/strategies/attach.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAe,MAAM,yBAAyB,CAAC;AAG5E,OAAO,KAAK,EAEV,qBAAqB,EACrB,YAAY,EAEZ,kBAAkB,EAElB,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EAEf,MAAM,YAAY,CAAC;AAOpB,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,sDAAsD,CAAC;AAwZ9D,MAAM,WAAW,0BAA2B,SAAQ,qBAAqB;IACvE;;;;;;;;;;;;;;;;;4EAiBwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAC3C;AAQD,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,eAAe,EAC3B,IAAI,GAAE,0BAA+B,GACpC,mBAAmB,CAwCrB;AAID,MAAM,WAAW,iBAAkB,SAAQ,qBAAqB;IAC9D,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,eAAe,EAC3B,IAAI,GAAE,iBAAsB,GAC3B,cAAc,CAgEhB;AAID,MAAM,WAAW,uBAAwB,SAAQ,qBAAqB;IACpE,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC;;0CAEsC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;IACrC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAgBD,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,eAAe,EAC3B,IAAI,EAAE,uBAAuB,GAC5B,cAAc,CAwChB"}
+{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../../../src/strategies/attach.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAe,MAAM,yBAAyB,CAAC;AAG5E,OAAO,KAAK,EAEV,qBAAqB,EACrB,YAAY,EAEZ,kBAAkB,EAElB,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EAEf,MAAM,YAAY,CAAC;AAQpB,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,sDAAsD,CAAC;AA0Z9D,MAAM,WAAW,0BAA2B,SAAQ,qBAAqB;IACvE;;;;;;;;;;;;;;;;;4EAiBwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAC3C;AAQD,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,eAAe,EAC3B,IAAI,GAAE,0BAA+B,GACpC,mBAAmB,CAwCrB;AAID,MAAM,WAAW,iBAAkB,SAAQ,qBAAqB;IAC9D,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,eAAe,EAC3B,IAAI,GAAE,iBAAsB,GAC3B,cAAc,CAgEhB;AAID,MAAM,WAAW,uBAAwB,SAAQ,qBAAqB;IACpE,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC;;0CAEsC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;IACrC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAgBD,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,eAAe,EAC3B,IAAI,EAAE,uBAAuB,GAC5B,cAAc,CAwChB"}

package/dist/types/strategies/flushDeadline.d.ts

@@ -0,0 +1,48 @@
+/**
+ * strategies/flushDeadline — flush a handle, stop waiting at a deadline, and
+ * name the strategy that did not finish.
+ *
+ * A sink's `flush()` waits for its own in-flight delivery. One that never
+ * settles — a hung network mount under `appendFile`, a network call with no
+ * timeout — would hold a shutdown forever, and a slow one for as long as it is
+ * slow. The deadline belongs to the caller that must finish,
+ * `RunnerBase · shutdown`, never to the sink: nothing can cancel an in-flight
+ * write, and pretending otherwise would be worse than saying we stopped
+ * waiting (the `withinBound` law in hosting/standingAgent.ts).
+ *
+ * A missed deadline is REPORTED, through the stuck strategy's own `_onError`
+ * (the console when it has none), and names it — the same rule as every
+ * delivery failure: telemetry that fails invisibly is indistinguishable from
+ * telemetry that works. A deadline cannot tell a slow delivery from a stuck
+ * one, so the report says both.
+ */
+import type { BaseStrategy, StrategyHandle } from './types.js';
+/** How long `shutdown()` waits for each handle's flush unless told otherwise:
+ *  30 s, the same number footprintjs's `drainObservers` uses as its default. */
+export declare const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30000;
+/** Remember the strategy behind a handle. Called once, where the handle is
+ *  built (`strategies/attach.ts · makeStrategyHandle`). */
+export declare function rememberStrategyOf(handle: object, strategy: BaseStrategy): void;
+/** The deadline a `shutdown({ timeoutMs })` asked for. Throws a `TypeError`
+ *  when it is not a positive number of milliseconds — called from the async
+ *  `shutdown()`, so its caller sees a REJECTED promise, never a sync throw.
+ *
+ *  The refusal names the field and the shape it takes, NEVER the value: a
+ *  value of the wrong type can be anything a caller had at hand, and an error
+ *  message is copied into logs, reports and traces. */
+export declare function shutdownTimeoutOf(timeoutMs: number | undefined): number;
+/**
+ * Flush one handle, but wait no longer than `timeoutMs`. On a missed deadline
+ * the strategy is reported by name and this resolves `'stuck'`; its flush
+ * keeps running — it is not, and cannot be, cancelled.
+ *
+ * The deadline is armed by `lib/longTimeout.ts · setLongTimeout`: `Infinity`
+ * arms no timer at all, and a finite deadline of ANY length fires when asked —
+ * past the ~24.8 days one host timer holds, it is waited in chained chunks,
+ * never dropped and never fired after 1 ms. Whatever is armed is cleared as
+ * soon as the flush settles, so a healthy shutdown leaves no timer behind.
+ * It is NOT unref'd: it is bounded, and it is what lets the code after
+ * `await agent.shutdown()` run when the stuck write holds nothing else open.
+ */
+export declare function flushWithinDeadline(handle: StrategyHandle, timeoutMs: number): Promise<'flushed' | 'stuck'>;
+//# sourceMappingURL=flushDeadline.d.ts.map

package/dist/types/strategies/flushDeadline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flushDeadline.d.ts","sourceRoot":"","sources":["../../../src/strategies/flushDeadline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE/D;gFACgF;AAChF,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAMlD;2DAC2D;AAC3D,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAE/E;AAED;;;;;;uDAMuD;AACvD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAQvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,CAa9B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "11.1.1",
+  "version": "11.2.0",
   "description": "The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.",
   "license": "MIT",
   "type": "commonjs",
@@ -395,7 +395,7 @@
     "@modelcontextprotocol/sdk": "*",
     "@opentelemetry/api": "*",
     "@yarflam/potion-base-8m": "*",
-    "footprintjs": "^9.47.0 || ^10.0.0",
+    "footprintjs": "^10.6.0",
     "google-auth-library": "*",
     "ioredis": "*",
     "jose": "*",