instar 0.28.113 → 0.28.115

package/dist/providers/costAwareRouting.d.ts

@@ -0,0 +1,134 @@
+/**
+ * CostAwareRoutingPolicy — implements the path-constraints §"Routing default"
+ * for Anthropic-bound traffic.
+ *
+ * Per `specs/provider-portability/04-anthropic-path-constraints.md`:
+ *
+ *   1. SDK credit path (`claude -p`) is PREFERRED when credits are available.
+ *      Drain the prepaid pot first — it's already paid for.
+ *   2. Subscription path (REPL pool) is the FLOOR. Always available, always
+ *      works (subject to Max session limits). Activates when the SDK pot
+ *      drops below the safety margin (default 10% of monthly total).
+ *   3. Raw API is never default. Not even in this policy.
+ *
+ * The policy is stateless from the caller's view: it takes the candidate
+ * list and a read function that returns the current SDK credit snapshot,
+ * and returns a decision. Quota state and counters live outside the policy.
+ *
+ * Composition: pair with the existing `RoutingPolicy` chain in
+ * `routing.ts` so this can defer to next-policy when no Anthropic
+ * candidate is in the running.
+ */
+import type { ProviderId } from './types.js';
+import type { ProviderAdapter, ResolveRequest } from './registry.js';
+import type { RoutingPolicy, RoutingDecision } from './routing.js';
+import type { AgentSdkCreditSnapshot } from './primitives/observability/usageMeterProvider.js';
+/**
+ * Default safety margin as a fraction of monthly credit. When the SDK pot's
+ * remaining balance is at or below `safetyMarginFraction * totalUsd`, new
+ * Anthropic work routes to the subscription floor instead of the SDK path.
+ *
+ * 0.10 (10%) per spec: preserves a buffer for high-priority work even
+ * after routine consumption has drained most of the pot.
+ */
+export declare const DEFAULT_SAFETY_MARGIN_FRACTION = 0.1;
+export interface CostAwareRoutingOptions {
+    /**
+     * Read the current SDK credit snapshot. The function returns null when
+     * the credit state is unknown (provider unreachable, fresh boot, etc.).
+     * Implementations typically wrap a UsageMeterProvider call.
+     */
+    readSdkCredit: () => Promise<AgentSdkCreditSnapshot | null>;
+    /**
+     * Adapter id that drains SDK credits (e.g. `anthropic-headless`,
+     * `claude -p` / `@anthropic-ai/claude-agent-sdk`).
+     */
+    sdkCreditAdapterId: ProviderId;
+    /**
+     * Adapter id that draws from the Max subscription (e.g.
+     * `anthropic-interactive-pool`, the REPL pool).
+     */
+    subscriptionAdapterId: ProviderId;
+    /**
+     * Safety margin as a fraction (0..1) of the SDK pot's totalUsd. When
+     * remaining balance is at or below this, switch new work to subscription.
+     * Default: 0.10.
+     */
+    safetyMarginFraction?: number;
+}
+export declare class CostAwareRoutingPolicy implements RoutingPolicy {
+    private readonly options;
+    private readonly safetyMarginFraction;
+    constructor(options: CostAwareRoutingOptions);
+    decide(candidates: ReadonlyArray<ProviderAdapter>, _request: ResolveRequest): Promise<RoutingDecision>;
+}
+/**
+ * A snapshot of cost / quota state, used by Phase 5b's TriggerGate to
+ * decide whether a "material shift" has occurred since the last cached
+ * routing pick was made.
+ *
+ * Today this carries SDK credit pot state. Future windows (subscription
+ * session budget, per-provider rate-limit headroom) extend this shape.
+ */
+export interface CostStateSnapshot {
+    /** ISO timestamp when this snapshot was captured. */
+    capturedAt: string;
+    /**
+     * SDK credit pot state, or null if not yet read / not available.
+     */
+    agentSdkCredit?: {
+        /** Remaining USD in the pot. */
+        remainingUsd: number;
+        /** Total USD for the billing period. */
+        totalUsd: number;
+        /** The threshold below which routing switches to subscription. */
+        safetyMarginUsd: number;
+        /** Whether remaining is at or below the margin. */
+        belowMargin: boolean;
+        /** Fraction of the pot consumed (0..1). */
+        consumedFraction: number;
+    } | null;
+}
+export interface CostStateTrackerOptions {
+    /** Source of SDK credit snapshots (typically a UsageMeterProvider wrapper). */
+    readSdkCredit: () => Promise<AgentSdkCreditSnapshot | null>;
+    /** Safety margin fraction (default: same as routing policy default). */
+    safetyMarginFraction?: number;
+    /**
+     * Threshold for "material" SDK-pot drift between snapshots, as a
+     * fraction of totalUsd. Drops larger than this since the cached snapshot
+     * count as material even when neither snapshot crossed the safety margin.
+     * Default: 0.25 (25% of the pot).
+     */
+    materialDriftFraction?: number;
+}
+/**
+ * Captures cost-state snapshots and detects "material" shifts between
+ * them. Used by Phase 5b to decide when a cached routing pick has gone
+ * stale even though the catalog hasn't changed.
+ */
+export declare class CostStateTracker {
+    private readonly options;
+    private readonly safetyMarginFraction;
+    private readonly materialDriftFraction;
+    constructor(options: CostStateTrackerOptions);
+    /** Read the current cost state snapshot. */
+    snapshot(): Promise<CostStateSnapshot>;
+    /**
+     * Compare two snapshots and decide whether a "material" shift has
+     * occurred. Material shifts include:
+     *
+     *   1. SDK pot crossed the safety margin (either direction) — flips
+     *      which adapter routine work routes to.
+     *   2. SDK pot dropped by more than `materialDriftFraction` of total
+     *      since the prior snapshot — big enough that a cached pick made
+     *      under more headroom may no longer be the right call.
+     *   3. State transitioned from unknown→known or known→unknown — the
+     *      observability surface itself shifted.
+     *
+     * Returns one of the human-readable reason strings, or null when no
+     * material shift detected.
+     */
+    isMaterialShift(prior: CostStateSnapshot, current: CostStateSnapshot): string | null;
+}
+//# sourceMappingURL=costAwareRouting.d.ts.map

package/dist/providers/costAwareRouting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"costAwareRouting.d.ts","sourceRoot":"","sources":["../../src/providers/costAwareRouting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kDAAkD,CAAC;AAE/F;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,MAAO,CAAC;AAEnD,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,aAAa,EAAE,MAAM,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;IAC5D;;;OAGG;IACH,kBAAkB,EAAE,UAAU,CAAC;IAC/B;;;OAGG;IACH,qBAAqB,EAAE,UAAU,CAAC;IAClC;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,qBAAa,sBAAuB,YAAW,aAAa;IAG9C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;gBAEjB,OAAO,EAAE,uBAAuB;IASvD,MAAM,CACV,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC,EAC1C,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,eAAe,CAAC;CA0D5B;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,cAAc,CAAC,EAAE;QACf,gCAAgC;QAChC,YAAY,EAAE,MAAM,CAAC;QACrB,wCAAwC;QACxC,QAAQ,EAAE,MAAM,CAAC;QACjB,kEAAkE;QAClE,eAAe,EAAE,MAAM,CAAC;QACxB,mDAAmD;QACnD,WAAW,EAAE,OAAO,CAAC;QACrB,2CAA2C;QAC3C,gBAAgB,EAAE,MAAM,CAAC;KAC1B,GAAG,IAAI,CAAC;CACV;AAED,MAAM,WAAW,uBAAuB;IACtC,+EAA+E;IAC/E,aAAa,EAAE,MAAM,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;IAC5D,wEAAwE;IACxE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,qBAAa,gBAAgB;IAIf,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAS;gBAElB,OAAO,EAAE,uBAAuB;IAK7D,4CAA4C;IACtC,QAAQ,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAyB5C;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI;CAwBrF"}

package/dist/providers/costAwareRouting.js

@@ -0,0 +1,169 @@
+/**
+ * CostAwareRoutingPolicy — implements the path-constraints §"Routing default"
+ * for Anthropic-bound traffic.
+ *
+ * Per `specs/provider-portability/04-anthropic-path-constraints.md`:
+ *
+ *   1. SDK credit path (`claude -p`) is PREFERRED when credits are available.
+ *      Drain the prepaid pot first — it's already paid for.
+ *   2. Subscription path (REPL pool) is the FLOOR. Always available, always
+ *      works (subject to Max session limits). Activates when the SDK pot
+ *      drops below the safety margin (default 10% of monthly total).
+ *   3. Raw API is never default. Not even in this policy.
+ *
+ * The policy is stateless from the caller's view: it takes the candidate
+ * list and a read function that returns the current SDK credit snapshot,
+ * and returns a decision. Quota state and counters live outside the policy.
+ *
+ * Composition: pair with the existing `RoutingPolicy` chain in
+ * `routing.ts` so this can defer to next-policy when no Anthropic
+ * candidate is in the running.
+ */
+/**
+ * Default safety margin as a fraction of monthly credit. When the SDK pot's
+ * remaining balance is at or below `safetyMarginFraction * totalUsd`, new
+ * Anthropic work routes to the subscription floor instead of the SDK path.
+ *
+ * 0.10 (10%) per spec: preserves a buffer for high-priority work even
+ * after routine consumption has drained most of the pot.
+ */
+export const DEFAULT_SAFETY_MARGIN_FRACTION = 0.10;
+export class CostAwareRoutingPolicy {
+    options;
+    safetyMarginFraction;
+    constructor(options) {
+        this.options = options;
+        this.safetyMarginFraction = options.safetyMarginFraction ?? DEFAULT_SAFETY_MARGIN_FRACTION;
+        if (this.safetyMarginFraction < 0 || this.safetyMarginFraction > 1) {
+            throw new Error(`CostAwareRoutingPolicy: safetyMarginFraction must be in [0,1], got ${this.safetyMarginFraction}`);
+        }
+    }
+    async decide(candidates, _request) {
+        const sdkCand = candidates.find((c) => c.id === this.options.sdkCreditAdapterId);
+        const subCand = candidates.find((c) => c.id === this.options.subscriptionAdapterId);
+        // Both Anthropic candidates available — the routine path. Decide on
+        // SDK pot state.
+        if (sdkCand && subCand) {
+            let snapshot = null;
+            try {
+                snapshot = await this.options.readSdkCredit();
+            }
+            catch {
+                // Treat read errors as "state unknown" — fall to the floor.
+                snapshot = null;
+            }
+            if (snapshot === null) {
+                return {
+                    chosen: subCand.id,
+                    reason: 'sdk-credit-state-unknown-fall-to-subscription-floor',
+                    fallbacks: [sdkCand.id],
+                };
+            }
+            const margin = this.safetyMarginFraction * snapshot.totalUsd;
+            if (snapshot.remainingUsd <= margin) {
+                return {
+                    chosen: subCand.id,
+                    reason: `sdk-credit-at-or-below-safety-margin `
+                        + `(remaining=$${snapshot.remainingUsd.toFixed(2)} <= margin=$${margin.toFixed(2)})`,
+                    fallbacks: [sdkCand.id],
+                };
+            }
+            return {
+                chosen: sdkCand.id,
+                reason: `sdk-credit-preferred `
+                    + `(remaining=$${snapshot.remainingUsd.toFixed(2)} > margin=$${margin.toFixed(2)})`,
+                fallbacks: [subCand.id],
+            };
+        }
+        // Only one Anthropic adapter in the candidate set — use it.
+        if (sdkCand) {
+            return { chosen: sdkCand.id, reason: 'only-sdk-candidate-available' };
+        }
+        if (subCand) {
+            return { chosen: subCand.id, reason: 'only-subscription-candidate-available' };
+        }
+        // Neither Anthropic candidate is in the running. Signal the chain by
+        // throwing — ChainPolicy will try the next policy. Calling code that
+        // uses this policy standalone should wrap in a ChainPolicy.
+        throw new Error('CostAwareRoutingPolicy: no Anthropic-stack candidate in resolve set; defer to next policy');
+    }
+}
+/**
+ * Captures cost-state snapshots and detects "material" shifts between
+ * them. Used by Phase 5b to decide when a cached routing pick has gone
+ * stale even though the catalog hasn't changed.
+ */
+export class CostStateTracker {
+    options;
+    safetyMarginFraction;
+    materialDriftFraction;
+    constructor(options) {
+        this.options = options;
+        this.safetyMarginFraction = options.safetyMarginFraction ?? DEFAULT_SAFETY_MARGIN_FRACTION;
+        this.materialDriftFraction = options.materialDriftFraction ?? 0.25;
+    }
+    /** Read the current cost state snapshot. */
+    async snapshot() {
+        let snapshot = null;
+        try {
+            snapshot = await this.options.readSdkCredit();
+        }
+        catch {
+            snapshot = null;
+        }
+        const result = { capturedAt: new Date().toISOString() };
+        if (snapshot !== null) {
+            const safetyMarginUsd = this.safetyMarginFraction * snapshot.totalUsd;
+            result.agentSdkCredit = {
+                remainingUsd: snapshot.remainingUsd,
+                totalUsd: snapshot.totalUsd,
+                safetyMarginUsd,
+                belowMargin: snapshot.remainingUsd <= safetyMarginUsd,
+                consumedFraction: snapshot.totalUsd > 0 ? 1 - snapshot.remainingUsd / snapshot.totalUsd : 0,
+            };
+        }
+        else {
+            result.agentSdkCredit = null;
+        }
+        return result;
+    }
+    /**
+     * Compare two snapshots and decide whether a "material" shift has
+     * occurred. Material shifts include:
+     *
+     *   1. SDK pot crossed the safety margin (either direction) — flips
+     *      which adapter routine work routes to.
+     *   2. SDK pot dropped by more than `materialDriftFraction` of total
+     *      since the prior snapshot — big enough that a cached pick made
+     *      under more headroom may no longer be the right call.
+     *   3. State transitioned from unknown→known or known→unknown — the
+     *      observability surface itself shifted.
+     *
+     * Returns one of the human-readable reason strings, or null when no
+     * material shift detected.
+     */
+    isMaterialShift(prior, current) {
+        const p = prior.agentSdkCredit;
+        const c = current.agentSdkCredit;
+        if (p === null && c !== null)
+            return 'sdk-credit-state-became-known';
+        if (p !== null && c === null)
+            return 'sdk-credit-state-became-unknown';
+        if (p === null && c === null)
+            return null;
+        // From here both are non-null.
+        if (p.belowMargin !== c.belowMargin) {
+            return c.belowMargin
+                ? 'sdk-credit-crossed-below-safety-margin'
+                : 'sdk-credit-recovered-above-safety-margin';
+        }
+        if (p.totalUsd > 0) {
+            const drift = (p.remainingUsd - c.remainingUsd) / p.totalUsd;
+            if (drift >= this.materialDriftFraction) {
+                return `sdk-credit-drift-${(drift * 100).toFixed(1)}pct-since-prior-snapshot`;
+            }
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=costAwareRouting.js.map

package/dist/providers/costAwareRouting.js.map

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

package/dist/providers/errors.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Error hierarchy for the provider portability substrate.
+ *
+ * Adapters normalize provider-native errors to this small set so application
+ * code can handle each category uniformly. The raw underlying error is always
+ * preserved in `cause` for adapter-specific diagnosis when needed.
+ *
+ * Pattern: catch the broadest class you can act on; re-throw what you can't.
+ *
+ *   try { ... }
+ *   catch (err) {
+ *     if (err instanceof QuotaError) { ... back off ... }
+ *     if (err instanceof TimeoutError) { ... retry with longer budget ... }
+ *     throw err;
+ *   }
+ */
+import type { ProviderId } from './types.js';
+/**
+ * Base class for all errors originating in the provider substrate.
+ *
+ * Wraps the raw provider error in `cause` and identifies which adapter
+ * raised it via `providerId`.
+ */
+export declare class ProviderError extends Error {
+    readonly providerId: ProviderId;
+    readonly cause?: unknown;
+    constructor(message: string, providerId: ProviderId, cause?: unknown);
+}
+/** Authentication failed — bad credentials, expired token, missing scope. */
+export declare class AuthError extends ProviderError {
+    constructor(message: string, providerId: ProviderId, cause?: unknown);
+}
+/**
+ * Quota exhausted — provider has refused based on usage limits.
+ *
+ * `retryAfterMs` indicates when retry MAY succeed (e.g., when the rate limit
+ * window resets). Adapters report this when known; callers must tolerate null.
+ */
+export declare class QuotaError extends ProviderError {
+    readonly retryAfterMs?: number;
+    readonly limitKind?: 'rate' | 'daily' | 'weekly' | 'monthly' | 'credit-pot' | 'unknown';
+    constructor(message: string, providerId: ProviderId, options?: {
+        retryAfterMs?: number;
+        limitKind?: QuotaError['limitKind'];
+        cause?: unknown;
+    });
+}
+/**
+ * Rate limit hit (a subset of QuotaError where the limit window is short and
+ * retry-after is typically known). Distinct class because callers often want
+ * fast retry for rate limits vs. back-off-substantially for daily/weekly.
+ */
+export declare class RateLimitError extends QuotaError {
+    constructor(message: string, providerId: ProviderId, options?: {
+        retryAfterMs?: number;
+        cause?: unknown;
+    });
+}
+/** Operation exceeded its time budget. */
+export declare class TimeoutError extends ProviderError {
+    readonly elapsedMs: number;
+    readonly budgetMs?: number;
+    constructor(message: string, providerId: ProviderId, elapsedMs: number, options?: {
+        budgetMs?: number;
+        cause?: unknown;
+    });
+}
+/** Network-layer failure — transport refused, connection reset, DNS, TLS. */
+export declare class NetworkError extends ProviderError {
+    constructor(message: string, providerId: ProviderId, cause?: unknown);
+}
+/**
+ * Caller-initiated abort via AbortSignal. Distinct from TimeoutError —
+ * AbortError means the consumer canceled, TimeoutError means the deadline
+ * passed.
+ */
+export declare class AbortError extends ProviderError {
+    constructor(message: string, providerId: ProviderId, cause?: unknown);
+}
+/**
+ * Requested capability not supported by this adapter. Thrown when an adapter
+ * is asked to perform an operation outside its declared `capabilities` set,
+ * or when an optional primitive method is called on an adapter that returns
+ * null for it.
+ */
+export declare class UnsupportedCapabilityError extends ProviderError {
+    readonly capability: string;
+    constructor(capability: string, providerId: ProviderId);
+}
+/**
+ * Catch-all for failures that don't fit the categories above. Adapters
+ * should prefer the specific classes when possible; this is for genuinely
+ * unexpected provider behavior.
+ */
+export declare class UnexpectedError extends ProviderError {
+    constructor(message: string, providerId: ProviderId, cause?: unknown);
+}
+export declare function isProviderError(err: unknown): err is ProviderError;
+export declare function isTransientError(err: unknown): boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/providers/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/providers/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,OAAO;CASrE;AAED,6EAA6E;AAC7E,qBAAa,SAAU,SAAQ,aAAa;gBAC9B,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,OAAO;CAKrE;AAED;;;;;GAKG;AACH,qBAAa,UAAW,SAAQ,aAAa;IAC3C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;gBAGtF,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAQhG;AAED;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,UAAU;gBAE1C,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAM3D;AAED,0CAA0C;AAC1C,qBAAa,YAAa,SAAQ,aAAa;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;gBAGzB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAQvD;AAED,6EAA6E;AAC7E,qBAAa,YAAa,SAAQ,aAAa;gBACjC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,OAAO;CAKrE;AAED;;;;GAIG;AACH,qBAAa,UAAW,SAAQ,aAAa;gBAC/B,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,OAAO;CAKrE;AAED;;;;;GAKG;AACH,qBAAa,0BAA2B,SAAQ,aAAa;IAC3D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU;CASvD;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,aAAa;gBACpC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,OAAO;CAKrE;AAID,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,aAAa,CAElE;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEtD"}

package/dist/providers/errors.js

@@ -0,0 +1,139 @@
+/**
+ * Error hierarchy for the provider portability substrate.
+ *
+ * Adapters normalize provider-native errors to this small set so application
+ * code can handle each category uniformly. The raw underlying error is always
+ * preserved in `cause` for adapter-specific diagnosis when needed.
+ *
+ * Pattern: catch the broadest class you can act on; re-throw what you can't.
+ *
+ *   try { ... }
+ *   catch (err) {
+ *     if (err instanceof QuotaError) { ... back off ... }
+ *     if (err instanceof TimeoutError) { ... retry with longer budget ... }
+ *     throw err;
+ *   }
+ */
+/**
+ * Base class for all errors originating in the provider substrate.
+ *
+ * Wraps the raw provider error in `cause` and identifies which adapter
+ * raised it via `providerId`.
+ */
+export class ProviderError extends Error {
+    providerId;
+    cause;
+    constructor(message, providerId, cause) {
+        super(message);
+        this.name = 'ProviderError';
+        this.providerId = providerId;
+        if (cause !== undefined) {
+            this.cause = cause;
+        }
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Authentication failed — bad credentials, expired token, missing scope. */
+export class AuthError extends ProviderError {
+    constructor(message, providerId, cause) {
+        super(message, providerId, cause);
+        this.name = 'AuthError';
+        Object.setPrototypeOf(this, AuthError.prototype);
+    }
+}
+/**
+ * Quota exhausted — provider has refused based on usage limits.
+ *
+ * `retryAfterMs` indicates when retry MAY succeed (e.g., when the rate limit
+ * window resets). Adapters report this when known; callers must tolerate null.
+ */
+export class QuotaError extends ProviderError {
+    retryAfterMs;
+    limitKind;
+    constructor(message, providerId, options = {}) {
+        super(message, providerId, options.cause);
+        this.name = 'QuotaError';
+        this.retryAfterMs = options.retryAfterMs;
+        this.limitKind = options.limitKind;
+        Object.setPrototypeOf(this, QuotaError.prototype);
+    }
+}
+/**
+ * Rate limit hit (a subset of QuotaError where the limit window is short and
+ * retry-after is typically known). Distinct class because callers often want
+ * fast retry for rate limits vs. back-off-substantially for daily/weekly.
+ */
+export class RateLimitError extends QuotaError {
+    constructor(message, providerId, options = {}) {
+        super(message, providerId, { ...options, limitKind: 'rate' });
+        this.name = 'RateLimitError';
+        Object.setPrototypeOf(this, RateLimitError.prototype);
+    }
+}
+/** Operation exceeded its time budget. */
+export class TimeoutError extends ProviderError {
+    elapsedMs;
+    budgetMs;
+    constructor(message, providerId, elapsedMs, options = {}) {
+        super(message, providerId, options.cause);
+        this.name = 'TimeoutError';
+        this.elapsedMs = elapsedMs;
+        this.budgetMs = options.budgetMs;
+        Object.setPrototypeOf(this, TimeoutError.prototype);
+    }
+}
+/** Network-layer failure — transport refused, connection reset, DNS, TLS. */
+export class NetworkError extends ProviderError {
+    constructor(message, providerId, cause) {
+        super(message, providerId, cause);
+        this.name = 'NetworkError';
+        Object.setPrototypeOf(this, NetworkError.prototype);
+    }
+}
+/**
+ * Caller-initiated abort via AbortSignal. Distinct from TimeoutError —
+ * AbortError means the consumer canceled, TimeoutError means the deadline
+ * passed.
+ */
+export class AbortError extends ProviderError {
+    constructor(message, providerId, cause) {
+        super(message, providerId, cause);
+        this.name = 'AbortError';
+        Object.setPrototypeOf(this, AbortError.prototype);
+    }
+}
+/**
+ * Requested capability not supported by this adapter. Thrown when an adapter
+ * is asked to perform an operation outside its declared `capabilities` set,
+ * or when an optional primitive method is called on an adapter that returns
+ * null for it.
+ */
+export class UnsupportedCapabilityError extends ProviderError {
+    capability;
+    constructor(capability, providerId) {
+        super(`Provider ${providerId} does not support capability '${capability}'`, providerId);
+        this.name = 'UnsupportedCapabilityError';
+        this.capability = capability;
+        Object.setPrototypeOf(this, UnsupportedCapabilityError.prototype);
+    }
+}
+/**
+ * Catch-all for failures that don't fit the categories above. Adapters
+ * should prefer the specific classes when possible; this is for genuinely
+ * unexpected provider behavior.
+ */
+export class UnexpectedError extends ProviderError {
+    constructor(message, providerId, cause) {
+        super(message, providerId, cause);
+        this.name = 'UnexpectedError';
+        Object.setPrototypeOf(this, UnexpectedError.prototype);
+    }
+}
+// ── Type guards ───────────────────────────────────────────────────────
+export function isProviderError(err) {
+    return err instanceof ProviderError;
+}
+export function isTransientError(err) {
+    return err instanceof NetworkError || err instanceof RateLimitError || err instanceof TimeoutError;
+}
+//# sourceMappingURL=errors.js.map

package/dist/providers/errors.js.map

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