@strands-agents/sdk 1.0.0-rc.5 → 1.1.0

package/dist/src/retry/__tests__/default-model-retry-strategy.test.js

@@ -0,0 +1,225 @@
+// Tests use vi.useFakeTimers() so the internal `await sleep(...)` never waits
+// real wall time — timers are advanced manually with vi.advanceTimersByTimeAsync.
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { DefaultModelRetryStrategy } from '../default-model-retry-strategy.js';
+import { ModelRetryStrategy } from '../model-retry-strategy.js';
+import { ConstantBackoff } from '../backoff-strategy.js';
+import { AfterModelCallEvent } from '../../hooks/events.js';
+import { ModelThrottledError } from '../../errors.js';
+import { createMockAgent, invokeTrackedHook } from '../../__fixtures__/agent-helpers.js';
+function makeErrorEvent(agent, error, attemptCount) {
+    return new AfterModelCallEvent({ agent, model: {}, attemptCount, error, invocationState: {} });
+}
+describe('DefaultModelRetryStrategy', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    it('registers an AfterModelCallEvent hook', () => {
+        const strategy = new DefaultModelRetryStrategy();
+        const agent = createMockAgent();
+        strategy.initAgent(agent);
+        const types = agent.trackedHooks.map((h) => h.eventType);
+        expect(types).toContain(AfterModelCallEvent);
+    });
+    it('exposes the plugin name', () => {
+        expect(new DefaultModelRetryStrategy().name).toBe('strands:default-model-retry-strategy');
+    });
+    it('is a ModelRetryStrategy', () => {
+        expect(new DefaultModelRetryStrategy()).toBeInstanceOf(ModelRetryStrategy);
+    });
+    it('rejects maxAttempts below 1', () => {
+        expect(() => new DefaultModelRetryStrategy({ maxAttempts: 0 })).toThrow(/maxAttempts/);
+    });
+    it('sets retry=true on ModelThrottledError and sleeps for the configured delay', async () => {
+        const strategy = new DefaultModelRetryStrategy({
+            maxAttempts: 3,
+            backoff: new ConstantBackoff({ delayMs: 500 }),
+        });
+        const agent = createMockAgent();
+        strategy.initAgent(agent);
+        const event = makeErrorEvent(agent, new ModelThrottledError('rate limited'), 1);
+        const pending = invokeTrackedHook(agent, event);
+        // Before the timer advances, the hook is still awaiting sleep — retry not yet set.
+        await vi.advanceTimersByTimeAsync(499);
+        expect(event.retry).toBeUndefined();
+        await vi.advanceTimersByTimeAsync(1);
+        await pending;
+        expect(event.retry).toBe(true);
+    });
+    it('does not retry non-retryable errors', async () => {
+        const strategy = new DefaultModelRetryStrategy({
+            backoff: new ConstantBackoff({ delayMs: 10 }),
+        });
+        const agent = createMockAgent();
+        strategy.initAgent(agent);
+        const event = makeErrorEvent(agent, new Error('boom'), 1);
+        await invokeTrackedHook(agent, event);
+        expect(event.retry).toBeUndefined();
+    });
+    it('stops retrying once maxAttempts is reached', async () => {
+        const strategy = new DefaultModelRetryStrategy({
+            maxAttempts: 3,
+            backoff: new ConstantBackoff({ delayMs: 1 }),
+        });
+        const agent = createMockAgent();
+        strategy.initAgent(agent);
+        // Attempt 1 → retry
+        const e1 = makeErrorEvent(agent, new ModelThrottledError('x'), 1);
+        const p1 = invokeTrackedHook(agent, e1);
+        await vi.advanceTimersByTimeAsync(1);
+        await p1;
+        expect(e1.retry).toBe(true);
+        // Attempt 2 → retry
+        const e2 = makeErrorEvent(agent, new ModelThrottledError('x'), 2);
+        const p2 = invokeTrackedHook(agent, e2);
+        await vi.advanceTimersByTimeAsync(1);
+        await p2;
+        expect(e2.retry).toBe(true);
+        // Attempt 3 → at max, should not retry
+        const e3 = makeErrorEvent(agent, new ModelThrottledError('x'), 3);
+        await invokeTrackedHook(agent, e3);
+        expect(e3.retry).toBeUndefined();
+    });
+    it('skips work if another hook already requested retry', async () => {
+        const strategy = new DefaultModelRetryStrategy({
+            maxAttempts: 5,
+            backoff: new ConstantBackoff({ delayMs: 1000 }),
+        });
+        const agent = createMockAgent();
+        strategy.initAgent(agent);
+        const event = makeErrorEvent(agent, new ModelThrottledError('x'), 1);
+        event.retry = true;
+        // Should return immediately with no sleep — if it tried to sleep we'd see
+        // hung test state; resolving without advancing timers proves the skip.
+        await invokeTrackedHook(agent, event);
+        expect(event.retry).toBe(true);
+    });
+    it('clears backoff state at the start of each new turn', async () => {
+        // The strategy resets state on `attemptCount === 1` regardless of how
+        // the prior turn ended. This exercises that: a turn racks up a retry
+        // (lastDelayMs = 5), then the next turn's first attempt must see a
+        // fresh BackoffContext (no lastDelayMs).
+        const nextDelay = vi.fn().mockReturnValue(5);
+        const backoff = { nextDelay };
+        const strategy = new DefaultModelRetryStrategy({ maxAttempts: 5, backoff });
+        const agent = createMockAgent();
+        strategy.initAgent(agent);
+        // Turn 1 → fail → lastDelayMs gets set to 5.
+        const e1 = makeErrorEvent(agent, new ModelThrottledError('x'), 1);
+        const p1 = invokeTrackedHook(agent, e1);
+        await vi.advanceTimersByTimeAsync(5);
+        await p1;
+        // Turn 2 → fail on first attempt → should see no lastDelayMs.
+        const e2 = makeErrorEvent(agent, new ModelThrottledError('x'), 1);
+        const p2 = invokeTrackedHook(agent, e2);
+        await vi.advanceTimersByTimeAsync(5);
+        await p2;
+        expect(nextDelay.mock.calls[1][0]).toEqual({
+            attempt: 1,
+            elapsedMs: expect.any(Number),
+        });
+    });
+    it('passes BackoffContext with attempt and lastDelayMs to the backoff strategy', async () => {
+        const nextDelay = vi.fn().mockReturnValue(5);
+        const backoff = { nextDelay };
+        const strategy = new DefaultModelRetryStrategy({ maxAttempts: 5, backoff });
+        const agent = createMockAgent();
+        strategy.initAgent(agent);
+        const e1 = makeErrorEvent(agent, new ModelThrottledError('x'), 1);
+        const p1 = invokeTrackedHook(agent, e1);
+        await vi.advanceTimersByTimeAsync(5);
+        await p1;
+        expect(nextDelay).toHaveBeenCalledTimes(1);
+        expect(nextDelay.mock.calls[0][0]).toEqual({
+            attempt: 1,
+            elapsedMs: expect.any(Number),
+        });
+        const e2 = makeErrorEvent(agent, new ModelThrottledError('x'), 2);
+        const p2 = invokeTrackedHook(agent, e2);
+        await vi.advanceTimersByTimeAsync(5);
+        await p2;
+        expect(nextDelay).toHaveBeenCalledTimes(2);
+        expect(nextDelay.mock.calls[1][0]).toEqual({
+            attempt: 2,
+            elapsedMs: expect.any(Number),
+            lastDelayMs: 5,
+        });
+    });
+    it('clears per-turn state on attempt 1 even when a prior hook already set event.retry', async () => {
+        // Regression: onFirstModelAttempt must fire before the event.retry short-circuit.
+        // Otherwise state from a prior turn leaks into the new turn's BackoffContext.
+        const nextDelay = vi.fn().mockReturnValue(5);
+        const backoff = { nextDelay };
+        const strategy = new DefaultModelRetryStrategy({ maxAttempts: 5, backoff });
+        const agent = createMockAgent();
+        strategy.initAgent(agent);
+        // Turn 1 → fail → lastDelayMs gets set to 5.
+        const e1 = makeErrorEvent(agent, new ModelThrottledError('x'), 1);
+        const p1 = invokeTrackedHook(agent, e1);
+        await vi.advanceTimersByTimeAsync(5);
+        await p1;
+        // Turn 2 → attempt 1 → another hook already set retry=true before us.
+        // We should still clear state (onFirstModelAttempt runs first), even though
+        // we short-circuit and don't call computeRetryDecision.
+        const e2 = makeErrorEvent(agent, new ModelThrottledError('x'), 1);
+        e2.retry = true;
+        await invokeTrackedHook(agent, e2);
+        // Turn 2 → attempt 2 → backoff should see no lastDelayMs from turn 1.
+        const e3 = makeErrorEvent(agent, new ModelThrottledError('x'), 2);
+        const p3 = invokeTrackedHook(agent, e3);
+        await vi.advanceTimersByTimeAsync(5);
+        await p3;
+        // Second call is turn 2 attempt 2; must not carry turn 1's lastDelayMs.
+        expect(nextDelay.mock.calls[1][0]).toEqual({
+            attempt: 2,
+            elapsedMs: expect.any(Number),
+        });
+    });
+    it('lets subclasses expand the retryable set by overriding isRetryable', async () => {
+        class CustomError extends Error {
+        }
+        class PermissiveStrategy extends DefaultModelRetryStrategy {
+            name = 'test:permissive';
+            isRetryable(error) {
+                return super.isRetryable(error) || error instanceof CustomError;
+            }
+        }
+        const strategy = new PermissiveStrategy({
+            maxAttempts: 3,
+            backoff: new ConstantBackoff({ delayMs: 10 }),
+        });
+        const agent = createMockAgent();
+        strategy.initAgent(agent);
+        const event = makeErrorEvent(agent, new CustomError('custom'), 1);
+        const pending = invokeTrackedHook(agent, event);
+        await vi.advanceTimersByTimeAsync(10);
+        await pending;
+        expect(event.retry).toBe(true);
+    });
+    it('short-circuits without retry when computeRetryDecision returns retry:false for a non-max reason', async () => {
+        // Exercises the computeRetryDecision "return { retry: false }" branch that
+        // isn't about maxAttempts. A subclass declines to retry a specific error
+        // instance even though the classifier said it was retryable in principle.
+        class PickyStrategy extends DefaultModelRetryStrategy {
+            name = 'test:picky';
+            computeRetryDecision(event) {
+                if (event.error.message === 'skip')
+                    return { retry: false };
+                return super.computeRetryDecision(event);
+            }
+        }
+        const strategy = new PickyStrategy({
+            maxAttempts: 5,
+            backoff: new ConstantBackoff({ delayMs: 10 }),
+        });
+        const agent = createMockAgent();
+        strategy.initAgent(agent);
+        const event = makeErrorEvent(agent, new ModelThrottledError('skip'), 1);
+        await invokeTrackedHook(agent, event);
+        expect(event.retry).toBeUndefined();
+    });
+});
+//# sourceMappingURL=default-model-retry-strategy.test.js.map

package/dist/src/retry/__tests__/default-model-retry-strategy.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-model-retry-strategy.test.js","sourceRoot":"","sources":["../../../../src/retry/__tests__/default-model-retry-strategy.test.ts"],"names":[],"mappings":"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"}

package/dist/src/retry/backoff-strategy.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Backoff strategies for computing delay between retry attempts.
+ *
+ * A `BackoffStrategy` is pure delay math: given a `BackoffContext`, it returns
+ * how long to wait before the next attempt. Policy concerns — whether to retry,
+ * whether to honor a server-provided `Retry-After` hint, max attempts, total
+ * time budgets — live in the retry orchestration layer, not here.
+ */
+/**
+ * Context passed to a {@link BackoffStrategy} for each retry decision.
+ *
+ * Treated as an open, additive-only contract: new optional fields may be added
+ * over time, but existing fields will not be removed or repurposed.
+ */
+export interface BackoffContext {
+    /** 1-based index of the attempt that just failed. Must be \>= 1. */
+    attempt: number;
+    /** Total milliseconds elapsed since the first attempt started. */
+    elapsedMs: number;
+    /** Previously computed delay, if any. Absent before the first retry. */
+    lastDelayMs?: number;
+}
+/**
+ * Computes the delay before the next retry attempt.
+ */
+export interface BackoffStrategy {
+    /**
+     * Returns the delay in milliseconds before the next attempt.
+     *
+     * Must be a non-negative finite number. Implementations should treat
+     * `ctx.attempt < 1` as a programmer error.
+     */
+    nextDelay(ctx: BackoffContext): number;
+}
+/**
+ * Supported jitter modes.
+ *
+ * - `none`: return the raw delay unchanged
+ * - `full`: uniform random in `[0, raw]`
+ * - `equal`: `raw/2 + uniform(0, raw/2)` (half fixed, half random)
+ * - `decorrelated`: `uniform(baseMs, lastDelayMs * 3)`, capped at `maxMs`;
+ *   falls back to `full` on the first retry when `lastDelayMs` is unavailable
+ *
+ * For jitter outside these modes, implement {@link BackoffStrategy} directly.
+ */
+export type JitterKind = 'none' | 'full' | 'equal' | 'decorrelated';
+/**
+ * Options for {@link ConstantBackoff}.
+ */
+export interface ConstantBackoffOptions {
+    /** Delay in ms returned for every retry. Default 1000. */
+    delayMs?: number;
+}
+/**
+ * Constant backoff: returns the same delay for every retry.
+ */
+export declare class ConstantBackoff implements BackoffStrategy {
+    private readonly _delayMs;
+    constructor(opts?: ConstantBackoffOptions);
+    nextDelay(ctx: BackoffContext): number;
+}
+/**
+ * Options for {@link LinearBackoff}.
+ */
+export interface LinearBackoffOptions {
+    /** Base delay in ms. Delay grows as `baseMs * attempt`. Default 1000. */
+    baseMs?: number;
+    /** Upper bound applied before jitter. Default 30_000. */
+    maxMs?: number;
+    /** Jitter mode. Default 'full'. */
+    jitter?: JitterKind;
+}
+/**
+ * Linear backoff: delay grows as `baseMs * attempt`, capped at `maxMs`, then jittered.
+ */
+export declare class LinearBackoff implements BackoffStrategy {
+    private readonly _baseMs;
+    private readonly _maxMs;
+    private readonly _jitter;
+    constructor(opts?: LinearBackoffOptions);
+    nextDelay(ctx: BackoffContext): number;
+}
+/**
+ * Options for {@link ExponentialBackoff}.
+ */
+export interface ExponentialBackoffOptions {
+    /** Base delay in ms. Delay grows as `baseMs * multiplier^(attempt-1)`. Default 1000. */
+    baseMs?: number;
+    /** Upper bound applied before jitter. Default 30_000. */
+    maxMs?: number;
+    /** Growth factor per attempt. Default 2. */
+    multiplier?: number;
+    /** Jitter mode. Default 'full'. */
+    jitter?: JitterKind;
+}
+/**
+ * Exponential backoff: delay grows as `baseMs * multiplier^(attempt-1)`,
+ * capped at `maxMs`, then jittered.
+ */
+export declare class ExponentialBackoff implements BackoffStrategy {
+    private readonly _baseMs;
+    private readonly _maxMs;
+    private readonly _multiplier;
+    private readonly _jitter;
+    constructor(opts?: ExponentialBackoffOptions);
+    nextDelay(ctx: BackoffContext): number;
+}
+//# sourceMappingURL=backoff-strategy.d.ts.map

package/dist/src/retry/backoff-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff-strategy.d.ts","sourceRoot":"","sources":["../../../src/retry/backoff-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAA;IACf,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAA;IACjB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAAA;CACvC;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,cAAc,CAAA;AAQnE;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,qBAAa,eAAgB,YAAW,eAAe;IACrD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;gBAErB,IAAI,GAAE,sBAA2B;IAI7C,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM;CAIvC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mCAAmC;IACnC,MAAM,CAAC,EAAE,UAAU,CAAA;CACpB;AAED;;GAEG;AACH,qBAAa,aAAc,YAAW,eAAe;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;gBAExB,IAAI,GAAE,oBAAyB;IAM3C,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM;CAKvC;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mCAAmC;IACnC,MAAM,CAAC,EAAE,UAAU,CAAA;CACpB;AAED;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,eAAe;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;gBAExB,IAAI,GAAE,yBAA8B;IAOhD,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM;CAKvC"}

package/dist/src/retry/backoff-strategy.js

@@ -0,0 +1,86 @@
+/**
+ * Backoff strategies for computing delay between retry attempts.
+ *
+ * A `BackoffStrategy` is pure delay math: given a `BackoffContext`, it returns
+ * how long to wait before the next attempt. Policy concerns — whether to retry,
+ * whether to honor a server-provided `Retry-After` hint, max attempts, total
+ * time budgets — live in the retry orchestration layer, not here.
+ */
+function validateAttempt(attempt, className) {
+    if (!Number.isInteger(attempt) || attempt < 1) {
+        throw new Error(`${className}: attempt must be an integer >= 1 (got ${attempt})`);
+    }
+}
+/**
+ * Constant backoff: returns the same delay for every retry.
+ */
+export class ConstantBackoff {
+    _delayMs;
+    constructor(opts = {}) {
+        this._delayMs = opts.delayMs ?? 1000;
+    }
+    nextDelay(ctx) {
+        validateAttempt(ctx.attempt, 'ConstantBackoff');
+        return this._delayMs;
+    }
+}
+/**
+ * Linear backoff: delay grows as `baseMs * attempt`, capped at `maxMs`, then jittered.
+ */
+export class LinearBackoff {
+    _baseMs;
+    _maxMs;
+    _jitter;
+    constructor(opts = {}) {
+        this._baseMs = opts.baseMs ?? 1000;
+        this._maxMs = opts.maxMs ?? 30_000;
+        this._jitter = opts.jitter ?? 'full';
+    }
+    nextDelay(ctx) {
+        validateAttempt(ctx.attempt, 'LinearBackoff');
+        const raw = Math.min(this._maxMs, this._baseMs * ctx.attempt);
+        return jitter(raw, this._jitter, this._baseMs, this._maxMs, ctx.lastDelayMs);
+    }
+}
+/**
+ * Exponential backoff: delay grows as `baseMs * multiplier^(attempt-1)`,
+ * capped at `maxMs`, then jittered.
+ */
+export class ExponentialBackoff {
+    _baseMs;
+    _maxMs;
+    _multiplier;
+    _jitter;
+    constructor(opts = {}) {
+        this._baseMs = opts.baseMs ?? 1000;
+        this._maxMs = opts.maxMs ?? 30_000;
+        this._multiplier = opts.multiplier ?? 2;
+        this._jitter = opts.jitter ?? 'full';
+    }
+    nextDelay(ctx) {
+        validateAttempt(ctx.attempt, 'ExponentialBackoff');
+        const raw = Math.min(this._maxMs, this._baseMs * this._multiplier ** (ctx.attempt - 1));
+        return jitter(raw, this._jitter, this._baseMs, this._maxMs, ctx.lastDelayMs);
+    }
+}
+function jitter(raw, kind, baseMs, maxMs, lastDelayMs) {
+    switch (kind) {
+        case 'none':
+            return raw;
+        case 'full':
+            return Math.random() * raw;
+        case 'equal':
+            return raw / 2 + Math.random() * (raw / 2);
+        case 'decorrelated': {
+            if (lastDelayMs === undefined) {
+                return Math.random() * raw;
+            }
+            // Standard decorrelated jitter: uniform(baseMs, min(maxMs, lastDelay * 3)).
+            // The max() guards against the degenerate case where maxMs < baseMs,
+            // which would otherwise produce an inverted range.
+            const upper = Math.max(baseMs, Math.min(maxMs, lastDelayMs * 3));
+            return baseMs + Math.random() * (upper - baseMs);
+        }
+    }
+}
+//# sourceMappingURL=backoff-strategy.js.map

package/dist/src/retry/backoff-strategy.js.map

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

package/dist/src/retry/default-model-retry-strategy.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Default concrete retry strategy for model invocations.
+ *
+ * Implements {@link ModelRetryStrategy.computeRetryDecision} to retry failed model
+ * calls classified by {@link isRetryable}, bounded by `maxAttempts`, with
+ * delays computed by the configured {@link BackoffStrategy}.
+ *
+ * The attempt counter lives on {@link AfterModelCallEvent.attemptCount},
+ * maintained by the agent loop. This strategy only keeps per-turn backoff
+ * state (first-failure timestamp, last delay), which is cleared in
+ * {@link onFirstModelAttempt}.
+ */
+import type { AfterModelCallEvent } from '../hooks/events.js';
+import type { BackoffStrategy } from './backoff-strategy.js';
+import { ModelRetryStrategy } from './model-retry-strategy.js';
+import type { RetryDecision } from './retry-strategy.js';
+/**
+ * Options for {@link DefaultModelRetryStrategy}.
+ */
+export interface DefaultModelRetryStrategyOptions {
+    /**
+     * Total model attempts before giving up and re-raising the error.
+     * Must be \>= 1. Default {@link DEFAULT_MAX_ATTEMPTS}.
+     */
+    maxAttempts?: number;
+    /**
+     * Backoff used to compute the delay between retries.
+     * Default: `new ExponentialBackoff({ baseMs: DEFAULT_BACKOFF_BASE_MS, maxMs: DEFAULT_BACKOFF_MAX_MS })`.
+     */
+    backoff?: BackoffStrategy;
+}
+/**
+ * Retries failed model calls classified by the SDK as retryable.
+ *
+ * Today, only {@link ModelThrottledError} is treated as retryable — subclass
+ * and override {@link isRetryable} to expand or narrow that set without
+ * reimplementing the rest of the retry policy.
+ *
+ * State is per-turn: backoff timing state resets in {@link onFirstModelAttempt},
+ * which the base class calls when `event.attemptCount === 1`. The attempt
+ * counter itself is owned by the agent loop and read off
+ * {@link AfterModelCallEvent.attemptCount}.
+ *
+ * Hook precedence: {@link AfterModelCallEvent} fires hooks in reverse registration
+ * order, so user-registered hooks run before this strategy. If a user hook sets
+ * `event.retry = true` first, the base class returns early and does not stack
+ * additional backoff on top.
+ *
+ * Sharing: a given instance tracks its own backoff state and must not be shared
+ * across multiple agents. Create a separate instance per agent.
+ *
+ * @example
+ * ```ts
+ * const agent = new Agent({
+ *   model,
+ *   retryStrategy: new DefaultModelRetryStrategy({ maxAttempts: 4 }),
+ * })
+ * ```
+ */
+export declare class DefaultModelRetryStrategy extends ModelRetryStrategy {
+    readonly name: string;
+    private readonly _maxAttempts;
+    private readonly _backoff;
+    private _lastDelayMs;
+    private _firstFailureAt;
+    constructor(opts?: DefaultModelRetryStrategyOptions);
+    /**
+     * Whether `error` should be retried. Override to extend or narrow the
+     * retryable set (e.g. to also retry transient 5xx errors).
+     */
+    protected isRetryable(error: Error): boolean;
+    protected computeRetryDecision(event: AfterModelCallEvent): RetryDecision;
+    protected onFirstModelAttempt(): void;
+    private _buildContext;
+}
+//# sourceMappingURL=default-model-retry-strategy.d.ts.map

package/dist/src/retry/default-model-retry-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-model-retry-strategy.d.ts","sourceRoot":"","sources":["../../../src/retry/default-model-retry-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAG7D,OAAO,KAAK,EAAkB,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAE5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAMxD;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,eAAe,CAAA;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,yBAA0B,SAAQ,kBAAkB;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAyC;IAE9D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAE1C,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,eAAe,CAAoB;gBAE/B,IAAI,GAAE,gCAAqC;IAWvD;;;OAGG;IACH,SAAS,CAAC,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;cAIzB,oBAAoB,CAAC,KAAK,EAAE,mBAAmB,GAAG,aAAa;cA4B/D,mBAAmB,IAAI,IAAI;IAK9C,OAAO,CAAC,aAAa;CAUtB"}

package/dist/src/retry/default-model-retry-strategy.js

@@ -0,0 +1,104 @@
+/**
+ * Default concrete retry strategy for model invocations.
+ *
+ * Implements {@link ModelRetryStrategy.computeRetryDecision} to retry failed model
+ * calls classified by {@link isRetryable}, bounded by `maxAttempts`, with
+ * delays computed by the configured {@link BackoffStrategy}.
+ *
+ * The attempt counter lives on {@link AfterModelCallEvent.attemptCount},
+ * maintained by the agent loop. This strategy only keeps per-turn backoff
+ * state (first-failure timestamp, last delay), which is cleared in
+ * {@link onFirstModelAttempt}.
+ */
+import { ModelThrottledError } from '../errors.js';
+import { logger } from '../logging/logger.js';
+import { ExponentialBackoff } from './backoff-strategy.js';
+import { ModelRetryStrategy } from './model-retry-strategy.js';
+const DEFAULT_MAX_ATTEMPTS = 6;
+const DEFAULT_BACKOFF_BASE_MS = 4_000;
+const DEFAULT_BACKOFF_MAX_MS = 240_000;
+/**
+ * Retries failed model calls classified by the SDK as retryable.
+ *
+ * Today, only {@link ModelThrottledError} is treated as retryable — subclass
+ * and override {@link isRetryable} to expand or narrow that set without
+ * reimplementing the rest of the retry policy.
+ *
+ * State is per-turn: backoff timing state resets in {@link onFirstModelAttempt},
+ * which the base class calls when `event.attemptCount === 1`. The attempt
+ * counter itself is owned by the agent loop and read off
+ * {@link AfterModelCallEvent.attemptCount}.
+ *
+ * Hook precedence: {@link AfterModelCallEvent} fires hooks in reverse registration
+ * order, so user-registered hooks run before this strategy. If a user hook sets
+ * `event.retry = true` first, the base class returns early and does not stack
+ * additional backoff on top.
+ *
+ * Sharing: a given instance tracks its own backoff state and must not be shared
+ * across multiple agents. Create a separate instance per agent.
+ *
+ * @example
+ * ```ts
+ * const agent = new Agent({
+ *   model,
+ *   retryStrategy: new DefaultModelRetryStrategy({ maxAttempts: 4 }),
+ * })
+ * ```
+ */
+export class DefaultModelRetryStrategy extends ModelRetryStrategy {
+    name = 'strands:default-model-retry-strategy';
+    _maxAttempts;
+    _backoff;
+    _lastDelayMs;
+    _firstFailureAt;
+    constructor(opts = {}) {
+        super();
+        const maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+        if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+            throw new Error(`DefaultModelRetryStrategy: maxAttempts must be an integer >= 1 (got ${maxAttempts})`);
+        }
+        this._maxAttempts = maxAttempts;
+        this._backoff =
+            opts.backoff ?? new ExponentialBackoff({ baseMs: DEFAULT_BACKOFF_BASE_MS, maxMs: DEFAULT_BACKOFF_MAX_MS });
+    }
+    /**
+     * Whether `error` should be retried. Override to extend or narrow the
+     * retryable set (e.g. to also retry transient 5xx errors).
+     */
+    isRetryable(error) {
+        return error instanceof ModelThrottledError;
+    }
+    computeRetryDecision(event) {
+        const error = event.error;
+        if (error === undefined || !this.isRetryable(error)) {
+            return { retry: false };
+        }
+        if (event.attemptCount >= this._maxAttempts) {
+            logger.debug(`attempt_count=<${event.attemptCount}> max_attempts=<${this._maxAttempts}> | max retry attempts reached`);
+            return { retry: false };
+        }
+        if (this._firstFailureAt === undefined) {
+            this._firstFailureAt = Date.now();
+        }
+        const waitMs = this._backoff.nextDelay(this._buildContext(event.attemptCount));
+        logger.debug(`retry_delay_ms=<${waitMs}> attempt_count=<${event.attemptCount}> max_attempts=<${this._maxAttempts}> ` +
+            `| retryable model error, delaying before retry`);
+        this._lastDelayMs = waitMs;
+        return { retry: true, waitMs };
+    }
+    onFirstModelAttempt() {
+        this._lastDelayMs = undefined;
+        this._firstFailureAt = undefined;
+    }
+    _buildContext(attemptCount) {
+        const ctx = {
+            attempt: attemptCount,
+            elapsedMs: this._firstFailureAt === undefined ? 0 : Date.now() - this._firstFailureAt,
+        };
+        if (this._lastDelayMs !== undefined) {
+            ctx.lastDelayMs = this._lastDelayMs;
+        }
+        return ctx;
+    }
+}
+//# sourceMappingURL=default-model-retry-strategy.js.map

package/dist/src/retry/default-model-retry-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-model-retry-strategy.js","sourceRoot":"","sources":["../../../src/retry/default-model-retry-strategy.ts"],"names":[],"mappings":"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"}

package/dist/src/retry/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Retry utilities.
+ */
+export { type BackoffContext, type BackoffStrategy, type JitterKind, type ConstantBackoffOptions, type LinearBackoffOptions, type ExponentialBackoffOptions, ConstantBackoff, LinearBackoff, ExponentialBackoff, } from './backoff-strategy.js';
+export { ModelRetryStrategy } from './model-retry-strategy.js';
+export { DefaultModelRetryStrategy, type DefaultModelRetryStrategyOptions } from './default-model-retry-strategy.js';
+export type { RetryStrategy, RetryDecision } from './retry-strategy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/retry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/retry/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,eAAe,EACf,aAAa,EACb,kBAAkB,GACnB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAE9D,OAAO,EAAE,yBAAyB,EAAE,KAAK,gCAAgC,EAAE,MAAM,mCAAmC,CAAA;AAEpH,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA"}