agentfootprint 2.9.0 → 2.10.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/core/Agent.js +113 -5
- package/dist/core/Agent.js.map +1 -1
- package/dist/core/outputFallback.js +156 -0
- package/dist/core/outputFallback.js.map +1 -0
- package/dist/esm/core/Agent.js +114 -6
- package/dist/esm/core/Agent.js.map +1 -1
- package/dist/esm/core/outputFallback.js +151 -0
- package/dist/esm/core/outputFallback.js.map +1 -0
- package/dist/esm/index.js.map +1 -1
- package/dist/esm/resilience/index.js +1 -0
- package/dist/esm/resilience/index.js.map +1 -1
- package/dist/esm/resilience/withCircuitBreaker.js +229 -0
- package/dist/esm/resilience/withCircuitBreaker.js.map +1 -0
- package/dist/index.js.map +1 -1
- package/dist/resilience/index.js +4 -1
- package/dist/resilience/index.js.map +1 -1
- package/dist/resilience/withCircuitBreaker.js +234 -0
- package/dist/resilience/withCircuitBreaker.js.map +1 -0
- package/dist/types/core/Agent.d.ts +63 -3
- package/dist/types/core/Agent.d.ts.map +1 -1
- package/dist/types/core/outputFallback.d.ts +140 -0
- package/dist/types/core/outputFallback.d.ts.map +1 -0
- package/dist/types/index.d.ts +1 -0
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/resilience/index.d.ts +1 -0
- package/dist/types/resilience/index.d.ts.map +1 -1
- package/dist/types/resilience/withCircuitBreaker.d.ts +114 -0
- package/dist/types/resilience/withCircuitBreaker.d.ts.map +1 -0
- package/package.json +1 -1
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAGL,KAAK,sBAAsB,EAC3B,KAAK,SAAS,EACd,KAAK,mBAAmB,EAExB,KAAK,UAAU,EACf,KAAK,eAAe,EAErB,MAAM,aAAa,CAAC;AAQrB,OAAO,KAAK,EAAe,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAOjF,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErE,OAAO,KAAK,EACV,WAAW,EAIX,iBAAiB,EACjB,YAAY,EACb,MAAM,sBAAsB,CAAC;AAgB9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AASlE,OAAO,KAAK,EAAmB,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAEnF,OAAO,
|
|
1
|
+
{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* outputFallback — 3-tier degradation for structured-output validation
|
|
3
|
+
* failures.
|
|
4
|
+
*
|
|
5
|
+
* Pairs with `outputSchema(parser)`. When the LLM's final answer
|
|
6
|
+
* fails schema validation (after the agent loop has done what it
|
|
7
|
+
* could), instead of throwing `OutputSchemaError` to the caller,
|
|
8
|
+
* the agent falls through:
|
|
9
|
+
*
|
|
10
|
+
* 1. **Primary** — LLM emitted schema-valid JSON. Caller gets the
|
|
11
|
+
* parsed value.
|
|
12
|
+
* 2. **Fallback** — `OutputSchemaError` thrown by the parser. The
|
|
13
|
+
* consumer-supplied async `fallback(error, raw)` runs; its
|
|
14
|
+
* return value is parsed against the same schema. If valid →
|
|
15
|
+
* caller gets it. If `fallback` itself throws OR its return
|
|
16
|
+
* value fails schema → tier 3.
|
|
17
|
+
* 3. **Canned** — static `canned` value (validated against the
|
|
18
|
+
* schema at builder time so it's guaranteed to satisfy). The
|
|
19
|
+
* agent NEVER throws when `canned` is set.
|
|
20
|
+
*
|
|
21
|
+
* Pattern: chain-of-responsibility (GoF) over typed degradation tiers.
|
|
22
|
+
* Same shape as `withRetry` / `withFallback` for LLM
|
|
23
|
+
* providers, but at the SCHEMA layer instead of the network
|
|
24
|
+
* layer.
|
|
25
|
+
*
|
|
26
|
+
* Role: Layer-6 (Agent) — terminal contract failure handler.
|
|
27
|
+
* Composable with `outputSchema` (which it supplements;
|
|
28
|
+
* one without the other is incoherent).
|
|
29
|
+
*
|
|
30
|
+
* @example
|
|
31
|
+
* ```ts
|
|
32
|
+
* import { z } from 'zod';
|
|
33
|
+
*
|
|
34
|
+
* const Refund = z.object({
|
|
35
|
+
* amount: z.number().nonnegative(),
|
|
36
|
+
* reason: z.string().min(1),
|
|
37
|
+
* });
|
|
38
|
+
*
|
|
39
|
+
* const agent = Agent.create({...})
|
|
40
|
+
* .system('You decide refund amounts.')
|
|
41
|
+
* .outputSchema(Refund)
|
|
42
|
+
* .outputFallback({
|
|
43
|
+
* // Tier 2: try a more permissive prompt; if it also fails,
|
|
44
|
+
* // escalate to a human.
|
|
45
|
+
* fallback: async (err, raw) => ({
|
|
46
|
+
* amount: 0,
|
|
47
|
+
* reason: `manual review required (LLM output: ${raw.slice(0, 200)})`,
|
|
48
|
+
* }),
|
|
49
|
+
* // Tier 3: guaranteed-valid safety net.
|
|
50
|
+
* canned: { amount: 0, reason: 'unable to process — please retry' },
|
|
51
|
+
* })
|
|
52
|
+
* .build();
|
|
53
|
+
*
|
|
54
|
+
* // Caller never sees OutputSchemaError; gets a typed Refund either way.
|
|
55
|
+
* const refund = await agent.runTyped({ message: '...' });
|
|
56
|
+
* ```
|
|
57
|
+
*
|
|
58
|
+
* Why this matters in production:
|
|
59
|
+
* - LLMs occasionally emit prose despite the system prompt asking
|
|
60
|
+
* for JSON ("Sure! Here's your refund: {...}").
|
|
61
|
+
* - Schema-violating outputs are bursty under model load (vendor
|
|
62
|
+
* A/B tests, model rollouts, content-filter trips).
|
|
63
|
+
* - A B2C agent that THROWS on every malformed output cascades
|
|
64
|
+
* into 5xx for the end user; the FAIL-OPEN pattern degrades
|
|
65
|
+
* gracefully and lets you triage offline.
|
|
66
|
+
*
|
|
67
|
+
* Two typed events fire so observability backends can alert on
|
|
68
|
+
* degradation:
|
|
69
|
+
* - `agentfootprint.resilience.output_fallback_triggered`
|
|
70
|
+
* (tier 2 fired)
|
|
71
|
+
* - `agentfootprint.resilience.output_canned_used`
|
|
72
|
+
* (tier 3 fired — fallback also failed; safety net engaged)
|
|
73
|
+
*/
|
|
74
|
+
import type { OutputSchemaError, OutputSchemaParser } from './outputSchema.js';
|
|
75
|
+
/**
|
|
76
|
+
* Tier-2 fallback function. Receives the original validation error +
|
|
77
|
+
* the raw LLM output; returns a value that the agent will then try
|
|
78
|
+
* to validate against the same schema.
|
|
79
|
+
*
|
|
80
|
+
* If this function throws, OR its return value fails schema, the
|
|
81
|
+
* agent falls through to the `canned` value (tier 3).
|
|
82
|
+
*/
|
|
83
|
+
export type OutputFallbackFn<T> = (error: OutputSchemaError, rawOutput: string) => Promise<T> | T;
|
|
84
|
+
export interface OutputFallbackOptions<T> {
|
|
85
|
+
/** Tier 2 — async function that produces a candidate value. May
|
|
86
|
+
* throw or return invalid data; the agent will fall through to
|
|
87
|
+
* `canned` if so. */
|
|
88
|
+
readonly fallback: OutputFallbackFn<T>;
|
|
89
|
+
/** Tier 3 — guaranteed-valid safety net. Validated against the
|
|
90
|
+
* schema at builder time (throws on mismatch — fail-fast on
|
|
91
|
+
* misconfig). When set, the agent NEVER throws on output-schema
|
|
92
|
+
* failure.
|
|
93
|
+
*
|
|
94
|
+
* When omitted, `fallback`-thrown errors propagate to the caller
|
|
95
|
+
* (consumer chooses fail-open vs fail-closed). */
|
|
96
|
+
readonly canned?: T;
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* Internal — the resolved fallback config stored on the Agent.
|
|
100
|
+
* Identical to public `OutputFallbackOptions` but with the parser
|
|
101
|
+
* + canned-validation results pre-computed.
|
|
102
|
+
*
|
|
103
|
+
* @internal
|
|
104
|
+
*/
|
|
105
|
+
export interface ResolvedOutputFallback<T> {
|
|
106
|
+
readonly fallback: OutputFallbackFn<T>;
|
|
107
|
+
readonly canned?: T;
|
|
108
|
+
/** True when `canned` was provided. Used by `apply…` to decide
|
|
109
|
+
* whether tier 3 exists at all. */
|
|
110
|
+
readonly hasCanned: boolean;
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* Validate the consumer-supplied `canned` value against the schema
|
|
114
|
+
* at builder time. Fail-fast on misconfig — a `canned` value that
|
|
115
|
+
* doesn't satisfy the schema would cascade into runtime errors
|
|
116
|
+
* AFTER the agent loop has already failed, which defeats the
|
|
117
|
+
* fail-open guarantee.
|
|
118
|
+
*
|
|
119
|
+
* Throws `TypeError` with a hint if validation fails.
|
|
120
|
+
*/
|
|
121
|
+
export declare function validateCannedAgainstSchema<T>(canned: T, parser: OutputSchemaParser<T>): void;
|
|
122
|
+
/**
|
|
123
|
+
* The 3-tier resolver. Called by `agent.parseOutput()` /
|
|
124
|
+
* `agent.runTyped()` when an `outputFallback` is configured. Replaces
|
|
125
|
+
* the bare-throw behavior of `applyOutputSchema()`.
|
|
126
|
+
*
|
|
127
|
+
* Returns the typed value from whichever tier wins. Emits typed
|
|
128
|
+
* events at every tier transition so observability backends can
|
|
129
|
+
* alert on degradation.
|
|
130
|
+
*
|
|
131
|
+
* @param raw — the LLM's original final-answer string
|
|
132
|
+
* @param parser — the outputSchema parser
|
|
133
|
+
* @param fallbackCfg — the resolved fallback configuration
|
|
134
|
+
* @param emit — agentfootprint dispatcher's `dispatch()` entry
|
|
135
|
+
* (typed via the runner; we accept a thin
|
|
136
|
+
* function so this module stays import-free of
|
|
137
|
+
* the dispatcher).
|
|
138
|
+
*/
|
|
139
|
+
export declare function applyOutputFallback<T>(raw: string, parser: OutputSchemaParser<T>, fallbackCfg: ResolvedOutputFallback<T>, emit: (eventType: string, payload: Record<string, unknown>) => void, primaryError: OutputSchemaError): Promise<T>;
|
|
140
|
+
//# sourceMappingURL=outputFallback.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"outputFallback.d.ts","sourceRoot":"","sources":["../../../src/core/outputFallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAI/E;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAElG,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC;;0BAEsB;IACtB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IACvC;;;;;;uDAMmD;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACpB;wCACoC;IACpC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAID;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,IAAI,CAU7F;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC7B,WAAW,EAAE,sBAAsB,CAAC,CAAC,CAAC,EACtC,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,EACnE,YAAY,EAAE,iBAAiB,GAC9B,OAAO,CAAC,CAAC,CAAC,CAqBZ"}
|
package/dist/types/index.d.ts
CHANGED
|
@@ -41,6 +41,7 @@ export { defaultThinkingTemplates, selectThinkingState, renderThinkingLine, type
|
|
|
41
41
|
export { LLMCall, LLMCallBuilder, type LLMCallInput, type LLMCallOptions, type LLMCallOutput, } from './core/LLMCall.js';
|
|
42
42
|
export { Agent, AgentBuilder, type AgentInput, type AgentOptions, type AgentOutput, } from './core/Agent.js';
|
|
43
43
|
export { OutputSchemaError, applyOutputSchema, buildDefaultInstruction, type OutputSchemaParser, type OutputSchemaOptions, } from './core/outputSchema.js';
|
|
44
|
+
export { type OutputFallbackOptions, type OutputFallbackFn } from './core/outputFallback.js';
|
|
44
45
|
export { flowchartAsTool, type FlowchartAsToolOptions, type FlowchartResultMapper, type FlowchartToolSnapshot, } from './core/flowchartAsTool.js';
|
|
45
46
|
export type { Tool, ToolExecutionContext, ToolRegistryEntry, DefineToolOptions, } from './core/tools.js';
|
|
46
47
|
export { defineTool } from './core/tools.js';
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
|
|
@@ -18,4 +18,5 @@
|
|
|
18
18
|
export { withRetry, type WithRetryOptions } from './withRetry.js';
|
|
19
19
|
export { withFallback, type WithFallbackOptions } from './withFallback.js';
|
|
20
20
|
export { fallbackProvider, type FallbackProviderOptions } from './fallbackProvider.js';
|
|
21
|
+
export { withCircuitBreaker, CircuitOpenError, type WithCircuitBreakerOptions, type CircuitState, } from './withCircuitBreaker.js';
|
|
21
22
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/resilience/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/resilience/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,yBAAyB,EAC9B,KAAK,YAAY,GAClB,MAAM,yBAAyB,CAAC"}
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* withCircuitBreaker — provider decorator that fails fast after N
|
|
3
|
+
* consecutive failures.
|
|
4
|
+
*
|
|
5
|
+
* Pattern: Circuit Breaker (Nygard, *Release It!*) — wraps an
|
|
6
|
+
* `LLMProvider` and tracks consecutive failures. After
|
|
7
|
+
* `failureThreshold` failures, the breaker OPENS and
|
|
8
|
+
* rejects all calls without invoking the wrapped provider.
|
|
9
|
+
* After `cooldownMs`, the breaker enters HALF-OPEN and
|
|
10
|
+
* allows probe calls; success closes the breaker, failure
|
|
11
|
+
* re-opens it.
|
|
12
|
+
*
|
|
13
|
+
* Role: Outer ring (Hexagonal). Composes with `withRetry` and
|
|
14
|
+
* `withFallback`:
|
|
15
|
+
*
|
|
16
|
+
* ```
|
|
17
|
+
* withFallback(
|
|
18
|
+
* withCircuitBreaker(anthropic(...)), // ← stop hammering on outage
|
|
19
|
+
* withCircuitBreaker(openai(...)),
|
|
20
|
+
* )
|
|
21
|
+
* ```
|
|
22
|
+
*
|
|
23
|
+
* When Anthropic 503s for the 5th time, the breaker opens
|
|
24
|
+
* and `complete()` throws `CircuitOpenError` immediately —
|
|
25
|
+
* no network round-trip — which `withFallback` then
|
|
26
|
+
* catches and routes to OpenAI. After 30 seconds the
|
|
27
|
+
* breaker probes Anthropic with a single call; if it
|
|
28
|
+
* succeeds, normal operation resumes.
|
|
29
|
+
*
|
|
30
|
+
* Why a circuit breaker on top of `withRetry`?
|
|
31
|
+
* - `withRetry` keeps hammering one provider with exponential
|
|
32
|
+
* backoff — it doesn't know the vendor is down.
|
|
33
|
+
* - During a multi-minute Anthropic outage, every request still
|
|
34
|
+
* burns 3 retries + backoff = ~3 sec of latency before failing
|
|
35
|
+
* to the fallback. Multiplied by your QPS, that's a lot of
|
|
36
|
+
* wasted time + tokens (some retries DO get billed).
|
|
37
|
+
* - The breaker says: "we just saw 5 failures in a row; stop
|
|
38
|
+
* calling for 30 seconds." Subsequent requests fail in <1ms,
|
|
39
|
+
* `withFallback` routes immediately to OpenAI.
|
|
40
|
+
*
|
|
41
|
+
* Three states:
|
|
42
|
+
*
|
|
43
|
+
* CLOSED ──[ N consecutive failures ]──► OPEN
|
|
44
|
+
* ▲ │
|
|
45
|
+
* │ │ [cooldownMs elapsed]
|
|
46
|
+
* │ ▼
|
|
47
|
+
* └──[ M probe successes ]──── HALF-OPEN
|
|
48
|
+
*
|
|
49
|
+
* HALF-OPEN ──[ probe failure ]──► OPEN (cooldown restarts)
|
|
50
|
+
*
|
|
51
|
+
* `stream()` is decorated identically. `name`/`flush`/`stop` pass
|
|
52
|
+
* through unchanged (the consumer's existing observability hooks
|
|
53
|
+
* still see the underlying provider's identity).
|
|
54
|
+
*
|
|
55
|
+
* **Scope: per-instance, NOT distributed.** Each `withCircuitBreaker(...)`
|
|
56
|
+
* call holds its own breaker state in process memory. If you run 100
|
|
57
|
+
* server replicas, each has its own independent breaker — one
|
|
58
|
+
* instance can be CLOSED while another is OPEN. This is intentional
|
|
59
|
+
* (no shared state means no Redis dependency, no SPOF, no
|
|
60
|
+
* partial-cluster-blast-radius surprises) and matches Hystrix's
|
|
61
|
+
* default behavior. For cluster-wide coordination, layer your own
|
|
62
|
+
* Redis-backed counter on top via the `onStateChange` hook +
|
|
63
|
+
* `shouldCount` predicate.
|
|
64
|
+
*/
|
|
65
|
+
import type { LLMProvider } from '../adapters/types.js';
|
|
66
|
+
export interface WithCircuitBreakerOptions {
|
|
67
|
+
/** Consecutive failures before the breaker OPENS. Default 5. */
|
|
68
|
+
readonly failureThreshold?: number;
|
|
69
|
+
/** How long the breaker stays OPEN before probing. Default 30s. */
|
|
70
|
+
readonly cooldownMs?: number;
|
|
71
|
+
/** Successes required in HALF-OPEN to fully CLOSE. Default 2. */
|
|
72
|
+
readonly halfOpenSuccessThreshold?: number;
|
|
73
|
+
/**
|
|
74
|
+
* Predicate — does this error count toward the threshold? Default:
|
|
75
|
+
* everything except AbortError counts. Override to ignore client
|
|
76
|
+
* errors (e.g., 4xx) so a malformed request doesn't trip the
|
|
77
|
+
* breaker for everyone.
|
|
78
|
+
*/
|
|
79
|
+
readonly shouldCount?: (error: unknown) => boolean;
|
|
80
|
+
/** Hook invoked on every state transition. Useful for emitting
|
|
81
|
+
* `agentfootprint.resilience.circuit_state_changed`. */
|
|
82
|
+
readonly onStateChange?: (state: CircuitState, reason: string) => void;
|
|
83
|
+
}
|
|
84
|
+
export type CircuitState = 'closed' | 'open' | 'half-open';
|
|
85
|
+
/**
|
|
86
|
+
* Thrown by the wrapped provider when the breaker is OPEN. Carries
|
|
87
|
+
* the underlying root-cause error from the most recent failure so
|
|
88
|
+
* consumers can observe what tripped the breaker.
|
|
89
|
+
*/
|
|
90
|
+
export declare class CircuitOpenError extends Error {
|
|
91
|
+
readonly code: "ERR_CIRCUIT_OPEN";
|
|
92
|
+
/** The error that tripped the breaker (or the most recent failure
|
|
93
|
+
* during HALF-OPEN that re-opened it). */
|
|
94
|
+
readonly cause: unknown;
|
|
95
|
+
/** Wall-clock timestamp at which the breaker may next probe. */
|
|
96
|
+
readonly retryAfter: number;
|
|
97
|
+
constructor(providerName: string, cause: unknown, retryAfter: number);
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Wrap a provider with a circuit breaker.
|
|
101
|
+
*
|
|
102
|
+
* @example
|
|
103
|
+
* ```ts
|
|
104
|
+
* import { anthropic, openai } from 'agentfootprint/llm-providers';
|
|
105
|
+
* import { withCircuitBreaker, withFallback } from 'agentfootprint/resilience';
|
|
106
|
+
*
|
|
107
|
+
* const provider = withFallback(
|
|
108
|
+
* withCircuitBreaker(anthropic({ apiKey }), { failureThreshold: 5, cooldownMs: 30_000 }),
|
|
109
|
+
* withCircuitBreaker(openai({ apiKey })),
|
|
110
|
+
* );
|
|
111
|
+
* ```
|
|
112
|
+
*/
|
|
113
|
+
export declare function withCircuitBreaker(inner: LLMProvider, options?: WithCircuitBreakerOptions): LLMProvider;
|
|
114
|
+
//# sourceMappingURL=withCircuitBreaker.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"withCircuitBreaker.d.ts","sourceRoot":"","sources":["../../../src/resilience/withCircuitBreaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH,OAAO,KAAK,EAAY,WAAW,EAA2B,MAAM,sBAAsB,CAAC;AAI3F,MAAM,WAAW,yBAAyB;IACxC,gEAAgE;IAChE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,mEAAmE;IACnE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IACnD;6DACyD;IACzD,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACxE;AAED,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAI3D;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,qBAA+B;IAC5C;+CAC2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,gEAAgE;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAChB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM;CAYrE;AAYD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,yBAA8B,GACtC,WAAW,CAsHb"}
|
package/package.json
CHANGED