@mcp-abap-adt/llm-agent 25.0.0 → 27.0.1

package/dist/testing/rag-filter-conformance.js

@@ -0,0 +1,379 @@
+/**
+ * Conformance kit for the identity filter every `IRag` store must honour.
+ *
+ * `query(embedding, k, { ragFilter })` may carry `sessionId` and/or `userId`
+ * (the pipeline's `rag-query` stage sets them for `scope: 'session' | 'user'`).
+ * A store that ignores them lets one user's records surface in another
+ * user's context. The contract:
+ *
+ * - `ragFilter.sessionId` set → only records whose `metadata.sessionId`
+ *   equals it; a record without `sessionId` is excluded.
+ * - `ragFilter.userId` set → the same for `metadata.userId`.
+ * - both set → both must match; neither set → no identity filtering.
+ * - the filter applies BEFORE top-k: a filtered query still returns up to `k`
+ *   matching records.
+ *
+ * The same kit covers the other two filters every store applies:
+ *
+ * - `ragFilter.namespace` set → only records whose `metadata.namespace`
+ *   equals it; a record without `namespace` is excluded. Not set → records of
+ *   every namespace (for a store configured without a namespace of its own).
+ * - `metadata.ttl` (epoch seconds) in the past → the record is expired and
+ *   never returned; a future or absent `ttl` keeps it.
+ * - both apply BEFORE top-k too.
+ *
+ * Framework-agnostic: each case throws (`node:assert`) on a violation, so a
+ * store package runs them under its own test runner:
+ *
+ * ```ts
+ * for (const c of ragFilterConformanceCases) {
+ *   it(c.name, () => c.run(async () => new MyRag({ embedder: conformanceEmbedder() })));
+ * }
+ * ```
+ *
+ * Every case asks the factory for a FRESH, empty store and seeds it through
+ * `writer().upsertRaw`.
+ */
+import assert from 'node:assert/strict';
+/** Dimension of {@link conformanceEmbedder}'s vectors. */
+export const CONFORMANCE_EMBEDDING_DIM = 64;
+function tokens(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 1);
+}
+function hash(s) {
+    let h = 2166136261;
+    for (const ch of s) {
+        h ^= ch.charCodeAt(0);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+}
+/**
+ * Deterministic bag-of-words embedder: every token lands in one of
+ * {@link CONFORMANCE_EMBEDDING_DIM} buckets, and the vector is L2-normalised.
+ * Texts that share tokens are close; texts that share none are orthogonal —
+ * which the top-k case relies on, and which keeps the conformance texts far
+ * apart enough that no store's near-duplicate merge folds two records.
+ */
+export function conformanceEmbedder() {
+    return {
+        async embed(text) {
+            const v = new Array(CONFORMANCE_EMBEDDING_DIM).fill(0);
+            for (const t of tokens(text))
+                v[hash(t) % CONFORMANCE_EMBEDDING_DIM] += 1;
+            const norm = Math.sqrt(v.reduce((s, x) => s + x * x, 0));
+            // A zero vector breaks cosine distance in real backends.
+            if (norm === 0) {
+                v[0] = 1;
+                return { vector: v };
+            }
+            return { vector: v.map((x) => x / norm) };
+        },
+    };
+}
+async function seed(rag, records) {
+    const writer = rag.writer?.();
+    if (!writer)
+        throw new Error('store under test exposes no writer()');
+    for (const r of records) {
+        const res = await writer.upsertRaw(r.id, r.text, r.metadata);
+        if (!res.ok)
+            throw res.error;
+    }
+}
+async function queryIds(rag, text, k, ragFilter) {
+    const embedder = conformanceEmbedder();
+    const res = await rag.query({
+        text,
+        toVector: async () => (await embedder.embed(text)).vector,
+    }, k, ragFilter ? { ragFilter } : undefined);
+    if (!res.ok)
+        throw res.error;
+    return res.value.map((r) => String(r.metadata.id)).sort();
+}
+const Q = 'quarterly revenue forecast';
+export const ragFilterConformanceCases = [
+    {
+        name: 'sessionId filter isolates two sessions',
+        async run(makeStore) {
+            const rag = await makeStore();
+            await seed(rag, [
+                {
+                    id: 's1-a',
+                    text: 'alpha harbour lighthouse',
+                    metadata: { sessionId: 's1' },
+                },
+                {
+                    id: 's2-a',
+                    text: 'bravo mountain glacier',
+                    metadata: { sessionId: 's2' },
+                },
+            ]);
+            assert.deepEqual(await queryIds(rag, Q, 10, { sessionId: 's1' }), [
+                's1-a',
+            ]);
+            assert.deepEqual(await queryIds(rag, Q, 10, { sessionId: 's2' }), [
+                's2-a',
+            ]);
+        },
+    },
+    {
+        name: 'userId filter isolates two users',
+        async run(makeStore) {
+            const rag = await makeStore();
+            await seed(rag, [
+                {
+                    id: 'u1-a',
+                    text: 'charlie desert oasis',
+                    metadata: { userId: 'u1' },
+                },
+                { id: 'u2-a', text: 'delta forest canopy', metadata: { userId: 'u2' } },
+            ]);
+            assert.deepEqual(await queryIds(rag, Q, 10, { userId: 'u1' }), ['u1-a']);
+            assert.deepEqual(await queryIds(rag, Q, 10, { userId: 'u2' }), ['u2-a']);
+        },
+    },
+    {
+        name: 'sessionId and userId together must both match',
+        async run(makeStore) {
+            const rag = await makeStore();
+            await seed(rag, [
+                {
+                    id: 's1u1',
+                    text: 'echo river delta',
+                    metadata: { sessionId: 's1', userId: 'u1' },
+                },
+                {
+                    id: 's1u2',
+                    text: 'foxtrot volcano crater',
+                    metadata: { sessionId: 's1', userId: 'u2' },
+                },
+                {
+                    id: 's2u1',
+                    text: 'golf tundra permafrost',
+                    metadata: { sessionId: 's2', userId: 'u1' },
+                },
+            ]);
+            assert.deepEqual(await queryIds(rag, Q, 10, { sessionId: 's1', userId: 'u1' }), ['s1u1']);
+        },
+    },
+    {
+        name: 'no identity filter returns records of every session and user',
+        async run(makeStore) {
+            const rag = await makeStore();
+            await seed(rag, [
+                {
+                    id: 's1-a',
+                    text: 'hotel savanna acacia',
+                    metadata: { sessionId: 's1', userId: 'u1' },
+                },
+                {
+                    id: 's2-a',
+                    text: 'india reef coral',
+                    metadata: { sessionId: 's2', userId: 'u2' },
+                },
+            ]);
+            assert.deepEqual(await queryIds(rag, Q, 10), ['s1-a', 's2-a']);
+        },
+    },
+    {
+        name: 'a record without sessionId/userId is excluded under that filter',
+        async run(makeStore) {
+            const rag = await makeStore();
+            await seed(rag, [
+                {
+                    id: 'owned',
+                    text: 'juliet canyon mesa',
+                    metadata: { sessionId: 's1', userId: 'u1' },
+                },
+                { id: 'unowned', text: 'kilo prairie bison', metadata: {} },
+            ]);
+            assert.deepEqual(await queryIds(rag, Q, 10, { sessionId: 's1' }), [
+                'owned',
+            ]);
+            assert.deepEqual(await queryIds(rag, Q, 10, { userId: 'u1' }), ['owned']);
+        },
+    },
+    {
+        name: 'the filter applies before top-k: k counts only matching records',
+        async run(makeStore) {
+            const rag = await makeStore();
+            // The s2 records all share tokens with the query; the s1 record shares
+            // none, so an unfiltered top-1 is always an s2 record.
+            await seed(rag, [
+                {
+                    id: 's2-a',
+                    text: 'quarterly revenue forecast europe',
+                    metadata: { sessionId: 's2' },
+                },
+                {
+                    id: 's2-b',
+                    text: 'quarterly revenue forecast asia',
+                    metadata: { sessionId: 's2' },
+                },
+                {
+                    id: 's2-c',
+                    text: 'quarterly revenue forecast americas',
+                    metadata: { sessionId: 's2' },
+                },
+                {
+                    id: 's1-a',
+                    text: 'lima penguin iceberg',
+                    metadata: { sessionId: 's1' },
+                },
+            ]);
+            assert.deepEqual(await queryIds(rag, Q, 1, { sessionId: 's1' }), [
+                's1-a',
+            ]);
+        },
+    },
+    {
+        name: 'namespace filter returns only that namespace; none set returns all',
+        async run(makeStore) {
+            const rag = await makeStore();
+            await seed(rag, [
+                {
+                    id: 'ns-a',
+                    text: 'mike tundra reindeer',
+                    metadata: { namespace: 'a' },
+                },
+                {
+                    id: 'ns-b',
+                    text: 'november jungle parrot',
+                    metadata: { namespace: 'b' },
+                },
+                { id: 'ns-none', text: 'oscar steppe falcon', metadata: {} },
+            ]);
+            assert.deepEqual(await queryIds(rag, Q, 10, { namespace: 'a' }), [
+                'ns-a',
+            ]);
+            assert.deepEqual(await queryIds(rag, Q, 10, { namespace: 'b' }), [
+                'ns-b',
+            ]);
+            assert.deepEqual(await queryIds(rag, Q, 10), ['ns-a', 'ns-b', 'ns-none']);
+        },
+    },
+    {
+        name: 'the namespace filter applies before top-k',
+        async run(makeStore) {
+            const rag = await makeStore();
+            await seed(rag, [
+                {
+                    id: 'b-1',
+                    text: 'quarterly revenue forecast europe',
+                    metadata: { namespace: 'b' },
+                },
+                {
+                    id: 'b-2',
+                    text: 'quarterly revenue forecast asia',
+                    metadata: { namespace: 'b' },
+                },
+                {
+                    id: 'a-1',
+                    text: 'papa lagoon flamingo',
+                    metadata: { namespace: 'a' },
+                },
+            ]);
+            assert.deepEqual(await queryIds(rag, Q, 1, { namespace: 'a' }), ['a-1']);
+        },
+    },
+    {
+        name: 'an expired record (metadata.ttl in the past) is never returned',
+        async run(makeStore) {
+            const rag = await makeStore();
+            const now = Math.floor(Date.now() / 1000);
+            await seed(rag, [
+                {
+                    id: 'expired',
+                    text: 'quebec marsh heron',
+                    metadata: { ttl: now - 3600 },
+                },
+                {
+                    id: 'live',
+                    text: 'romeo cliff eagle',
+                    metadata: { ttl: now + 3600 },
+                },
+                { id: 'no-ttl', text: 'sierra dune lizard', metadata: {} },
+            ]);
+            assert.deepEqual(await queryIds(rag, Q, 10), ['live', 'no-ttl']);
+        },
+    },
+    {
+        name: 'a negative ttl is in the past, so the record is expired',
+        // A store that told "no ttl" apart from "ttl in the past" by `ttl >= 0`
+        // let ttl: -1 through as if it had none (found in Qdrant, PR #308).
+        async run(makeStore) {
+            const rag = await makeStore();
+            await seed(rag, [
+                { id: 'negative', text: 'tango reef octopus', metadata: { ttl: -1 } },
+                { id: 'no-ttl', text: 'uniform glade badger', metadata: {} },
+            ]);
+            assert.deepEqual(await queryIds(rag, Q, 10), ['no-ttl']);
+        },
+    },
+    {
+        name: 'expiry applies before top-k',
+        async run(makeStore) {
+            const rag = await makeStore();
+            const now = Math.floor(Date.now() / 1000);
+            await seed(rag, [
+                {
+                    id: 'old-1',
+                    text: 'quarterly revenue forecast europe',
+                    metadata: { ttl: now - 3600 },
+                },
+                {
+                    id: 'old-2',
+                    text: 'quarterly revenue forecast asia',
+                    metadata: { ttl: now - 3600 },
+                },
+                { id: 'fresh', text: 'tango pampas rhea', metadata: {} },
+            ]);
+            assert.deepEqual(await queryIds(rag, Q, 1), ['fresh']);
+        },
+    },
+    {
+        name: 'namespace, expiry and identity filters combine',
+        async run(makeStore) {
+            const rag = await makeStore();
+            const now = Math.floor(Date.now() / 1000);
+            await seed(rag, [
+                {
+                    id: 'a-live',
+                    text: 'uniform bayou alligator',
+                    metadata: { namespace: 'a', sessionId: 's1', ttl: now + 3600 },
+                },
+                {
+                    id: 'a-nottl',
+                    text: 'victor fjord seal',
+                    metadata: { namespace: 'a', sessionId: 's1' },
+                },
+                {
+                    id: 'a-expired',
+                    text: 'whiskey atoll turtle',
+                    metadata: { namespace: 'a', sessionId: 's1', ttl: now - 3600 },
+                },
+                {
+                    id: 'a-other-session',
+                    text: 'xray moor grouse',
+                    metadata: { namespace: 'a', sessionId: 's2' },
+                },
+                {
+                    id: 'b-nottl',
+                    text: 'yankee taiga lynx',
+                    metadata: { namespace: 'b', sessionId: 's1' },
+                },
+            ]);
+            assert.deepEqual(await queryIds(rag, Q, 10, { namespace: 'a', sessionId: 's1' }), ['a-live', 'a-nottl']);
+            assert.deepEqual(await queryIds(rag, Q, 10, { namespace: 'a' }), [
+                'a-live',
+                'a-nottl',
+                'a-other-session',
+            ]);
+        },
+    },
+];
+//# sourceMappingURL=rag-filter-conformance.js.map

package/dist/testing/rag-filter-conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag-filter-conformance.js","sourceRoot":"","sources":["../../src/testing/rag-filter-conformance.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -72,8 +72,17 @@ export interface LLMResponse {
     usage?: LlmUsage;
 }
 export interface LLMProviderConfig {
-    /** API key for authentication. Optional for providers with custom auth (e.g. SAP AI Core). */
-    apiKey?: string;
+    /**
+     * Which 429 gate this provider's calls share, when the default is not what you
+     * meant.
+     *
+     * A rate limit is per account, so by default two providers holding different
+     * credentials get separate gates — see `BaseLLMProvider.credentialScope`. Two
+     * providers wrapping the same account in separate credential objects also get
+     * separate gates, which is safe but loses the coordination; naming the same
+     * scope on both puts them back on one. Not a secret: a label you choose.
+     */
+    quotaScope?: string;
     baseURL?: string;
     model?: string;
     temperature?: number;

package/dist/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/llm-agent",
-  "version": "25.0.0",
+  "version": "27.0.1",
   "description": "Core interfaces, types, and lightweight default implementations for LLM agent orchestration.",
   "type": "module",
   "main": "dist/index.js",
@@ -10,6 +10,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./testing/rag-filter-conformance": {
+      "types": "./dist/testing/rag-filter-conformance.d.ts",
+      "import": "./dist/testing/rag-filter-conformance.js",
+      "default": "./dist/testing/rag-filter-conformance.js"
     }
   },
   "files": [
@@ -24,6 +29,8 @@
     "test": "node --import tsx/esm --test --test-reporter=spec 'src/**/*.test.ts'"
   },
   "dependencies": {
+    "@mcp-abap-adt/interfaces-auth": "^1.1.0",
+    "@mcp-abap-adt/interfaces-utils": "^1.0.0",
     "zod": "^4.5.4"
   },
   "license": "LGPL-3.0-only",

package/dist/interfaces/failure-strategy.d.ts

@@ -1,95 +0,0 @@
-/**
- * What a provider does when a call fails for a reason nobody named an interval
- * for: a `500`, a `502`, a dropped connection, a socket that answers nothing.
- *
- * The sibling of `IThrottleStrategy`, and deliberately not the same seam.
- * Throttling is the SERVER governing the pace: it returns `429`, it names a
- * delay in `Retry-After`, and the only honest thing to do is observe that
- * delay or report it. Here nobody names anything. A `502` says the request
- * failed; it says nothing at all about when the next one might work.
- *
- * So any waiting here rests on a number, and this library has none to give.
- * How long to wait, and how many times, depends on who is waiting at the other
- * end — a batch job and a caller on a sixty-second connection want opposite
- * things, and the difference is invisible from in here. The consumer decides,
- * the same way it decides about throttling.
- *
- * Two ship:
- *
- * - `ReportFailure` — never waits. The failure goes up as it arrived, and the
- *   caller decides. This is what happens when nothing is configured.
- * - `RetryWithBackoff` — the classic policy, with its numbers named by whoever
- *   constructs it rather than defaulted in here.
- */
-/** What the transport said, for a strategy to decide on. */
-export interface FailureContext {
-    /** HTTP status, when the failure carried one. */
-    status?: number;
-    /** Which attempt just failed. 1-based. */
-    attempt: number;
-    /** How long this call has already spent waiting between attempts. */
-    waitedMs: number;
-    /** Whether anything was already streamed to the caller before the failure. */
-    midStream: boolean;
-    /** The failure itself, for a strategy that needs to look closer. */
-    error: unknown;
-}
-/** Wait this long, then either try again or give up. */
-export interface FailureDecision {
-    waitMs: number;
-    retry: boolean;
-    /** Why, for the log and for the error the caller finally sees. */
-    reason?: string;
-}
-export interface IFailureStrategy {
-    readonly name: string;
-    decide(ctx: FailureContext): FailureDecision;
-}
-/**
- * Never retry. What happens when nothing is configured.
- *
- * The failure goes up untouched, and the caller — who knows whether anyone is
- * waiting on the other end, and whether the work is worth repeating — decides
- * whether to ask again.
- */
-export declare class ReportFailure implements IFailureStrategy {
-    readonly name = "report-failure";
-    decide(): FailureDecision;
-}
-/**
- * Try again a fixed number of times, doubling the wait each time.
- *
- * The policy this library used to install on everyone by default. It still
- * ships, because it is a reasonable thing to want; what changed is that its
- * numbers now belong to whoever writes them down. There are no defaults here
- * on purpose — a default would be this library guessing again, one layer in.
- *
- * `statuses` is the set worth repeating. A `500` or `502` is usually the
- * provider having a bad second; a `400` is the request itself, and repeating
- * it just fails again more slowly. A failure carrying no status is not
- * retried: without one there is nothing to tell a blip from a bug.
- *
- * `midStreamHints` opts into the harder case — a stream that failed after it
- * had already yielded. Retrying that replays the whole stream, so it happens
- * only for failures whose message matches one of these, and never by default.
- */
-export declare class RetryWithBackoff implements IFailureStrategy {
-    readonly name = "retry-with-backoff";
-    private readonly attempts;
-    private readonly firstWaitMs;
-    private readonly statuses;
-    private readonly midStreamHints;
-    constructor(options: {
-        /** How many times to try again after the first failure. */
-        attempts: number;
-        /** The first wait. Each subsequent one doubles it. */
-        firstWaitMs: number;
-        /** Statuses worth repeating. */
-        statuses: readonly number[];
-        /** Message fragments that make a mid-stream failure worth replaying. */
-        midStreamHints?: readonly string[];
-    });
-    decide({ status, attempt, midStream, error, }: FailureContext): FailureDecision;
-    private matchesHint;
-}
-//# sourceMappingURL=failure-strategy.d.ts.map

package/dist/interfaces/failure-strategy.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"failure-strategy.d.ts","sourceRoot":"","sources":["../../src/interfaces/failure-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,SAAS,EAAE,OAAO,CAAC;IACnB,oEAAoE;IACpE,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,GAAG,EAAE,cAAc,GAAG,eAAe,CAAC;CAC9C;AAED;;;;;;GAMG;AACH,qBAAa,aAAc,YAAW,gBAAgB;IACpD,QAAQ,CAAC,IAAI,oBAAoB;IAEjC,MAAM,IAAI,eAAe;CAG1B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,gBAAiB,YAAW,gBAAgB;IACvD,QAAQ,CAAC,IAAI,wBAAwB;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoB;gBAEvC,OAAO,EAAE;QACnB,2DAA2D;QAC3D,QAAQ,EAAE,MAAM,CAAC;QACjB,sDAAsD;QACtD,WAAW,EAAE,MAAM,CAAC;QACpB,gCAAgC;QAChC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;QAC5B,wEAAwE;QACxE,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KACpC;IAOD,MAAM,CAAC,EACL,MAAM,EACN,OAAO,EACP,SAAS,EACT,KAAK,GACN,EAAE,cAAc,GAAG,eAAe;IAuBnC,OAAO,CAAC,WAAW;CAKpB"}

package/dist/interfaces/failure-strategy.js

@@ -1,96 +0,0 @@
-/**
- * What a provider does when a call fails for a reason nobody named an interval
- * for: a `500`, a `502`, a dropped connection, a socket that answers nothing.
- *
- * The sibling of `IThrottleStrategy`, and deliberately not the same seam.
- * Throttling is the SERVER governing the pace: it returns `429`, it names a
- * delay in `Retry-After`, and the only honest thing to do is observe that
- * delay or report it. Here nobody names anything. A `502` says the request
- * failed; it says nothing at all about when the next one might work.
- *
- * So any waiting here rests on a number, and this library has none to give.
- * How long to wait, and how many times, depends on who is waiting at the other
- * end — a batch job and a caller on a sixty-second connection want opposite
- * things, and the difference is invisible from in here. The consumer decides,
- * the same way it decides about throttling.
- *
- * Two ship:
- *
- * - `ReportFailure` — never waits. The failure goes up as it arrived, and the
- *   caller decides. This is what happens when nothing is configured.
- * - `RetryWithBackoff` — the classic policy, with its numbers named by whoever
- *   constructs it rather than defaulted in here.
- */
-import { isRetryableStatus } from '../resilience/status.js';
-/**
- * Never retry. What happens when nothing is configured.
- *
- * The failure goes up untouched, and the caller — who knows whether anyone is
- * waiting on the other end, and whether the work is worth repeating — decides
- * whether to ask again.
- */
-export class ReportFailure {
-    name = 'report-failure';
-    decide() {
-        return { waitMs: 0, retry: false, reason: 'reported' };
-    }
-}
-/**
- * Try again a fixed number of times, doubling the wait each time.
- *
- * The policy this library used to install on everyone by default. It still
- * ships, because it is a reasonable thing to want; what changed is that its
- * numbers now belong to whoever writes them down. There are no defaults here
- * on purpose — a default would be this library guessing again, one layer in.
- *
- * `statuses` is the set worth repeating. A `500` or `502` is usually the
- * provider having a bad second; a `400` is the request itself, and repeating
- * it just fails again more slowly. A failure carrying no status is not
- * retried: without one there is nothing to tell a blip from a bug.
- *
- * `midStreamHints` opts into the harder case — a stream that failed after it
- * had already yielded. Retrying that replays the whole stream, so it happens
- * only for failures whose message matches one of these, and never by default.
- */
-export class RetryWithBackoff {
-    name = 'retry-with-backoff';
-    attempts;
-    firstWaitMs;
-    statuses;
-    midStreamHints;
-    constructor(options) {
-        this.attempts = options.attempts;
-        this.firstWaitMs = options.firstWaitMs;
-        this.statuses = new Set(options.statuses);
-        this.midStreamHints = options.midStreamHints ?? [];
-    }
-    decide({ status, attempt, midStream, error, }) {
-        if (attempt > this.attempts) {
-            return { waitMs: 0, retry: false, reason: 'attempts' };
-        }
-        const worthRepeating = midStream
-            ? this.matchesHint(error)
-            : status !== undefined
-                ? this.statuses.has(status)
-                : // No structured status: fall back to the shared word-boundary match on
-                    // the message, because every provider rewraps its transport error and
-                    // the status is often only in the prose by the time it reaches here.
-                    isRetryableStatus(error, [...this.statuses]);
-        if (!worthRepeating) {
-            return {
-                waitMs: 0,
-                retry: false,
-                reason: midStream ? 'mid-stream' : 'not-transient',
-            };
-        }
-        // attempt is 1-based, so the first retry waits exactly firstWaitMs.
-        return { waitMs: this.firstWaitMs * 2 ** (attempt - 1), retry: true };
-    }
-    matchesHint(error) {
-        if (this.midStreamHints.length === 0)
-            return false;
-        const message = error instanceof Error ? error.message : String(error);
-        return this.midStreamHints.some((hint) => message.includes(hint));
-    }
-}
-//# sourceMappingURL=failure-strategy.js.map

package/dist/interfaces/failure-strategy.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"failure-strategy.js","sourceRoot":"","sources":["../../src/interfaces/failure-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AA6B5D;;;;;;GAMG;AACH,MAAM,OAAO,aAAa;IACf,IAAI,GAAG,gBAAgB,CAAC;IAEjC,MAAM;QACJ,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IACzD,CAAC;CACF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,gBAAgB;IAClB,IAAI,GAAG,oBAAoB,CAAC;IACpB,QAAQ,CAAS;IACjB,WAAW,CAAS;IACpB,QAAQ,CAAsB;IAC9B,cAAc,CAAoB;IAEnD,YAAY,OASX;QACC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,QAAQ,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC1C,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,EAAE,CAAC;IACrD,CAAC;IAED,MAAM,CAAC,EACL,MAAM,EACN,OAAO,EACP,SAAS,EACT,KAAK,GACU;QACf,IAAI,OAAO,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5B,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;QACzD,CAAC;QACD,MAAM,cAAc,GAAG,SAAS;YAC9B,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;YACzB,CAAC,CAAC,MAAM,KAAK,SAAS;gBACpB,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC;gBAC3B,CAAC,CAAC,uEAAuE;oBACvE,sEAAsE;oBACtE,qEAAqE;oBACrE,iBAAiB,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;QACnD,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,OAAO;gBACL,MAAM,EAAE,CAAC;gBACT,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,eAAe;aACnD,CAAC;QACJ,CAAC;QACD,oEAAoE;QACpE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,WAAW,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACxE,CAAC;IAEO,WAAW,CAAC,KAAc;QAChC,IAAI,IAAI,CAAC,cAAc,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QACnD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IACpE,CAAC;CACF"}