@sw4rm/js-sdk 0.5.0 → 0.6.0

package/dist/types/clients/handoff.d.ts

@@ -9,6 +9,7 @@
  *
  * Based on handoff.proto definitions.
  */
+import { ErrorCode } from '../internal/errorMapping.js';
 /**
  * Status of a handoff request.
  */
@@ -20,6 +21,33 @@ export declare enum HandoffStatus {
     COMPLETED = 4,
     EXPIRED = 5
 }
+export declare const DEFAULT_MAX_RETRIES_ON_OVERLOADED = 2;
+export declare const DEFAULT_INITIAL_BACKOFF_MS = 250;
+export declare const DEFAULT_BACKOFF_MULTIPLIER = 2;
+export declare const DEFAULT_MAX_BACKOFF_MS = 2000;
+export declare const DEFAULT_MAX_REDIRECTS = 0;
+/**
+ * SW4-004 budget envelope for cross-swarm delegation.
+ */
+export interface BudgetEnvelope {
+    tokenBudgetRemaining?: number;
+    wallTimeRemainingMs?: number;
+    /** Required for cross-swarm delegation. */
+    deadlineEpochMs: number;
+    currentDepth?: number;
+    maxDelegationDepth?: number;
+}
+/**
+ * SW4-004/SW4-005 delegation policy envelope.
+ */
+export interface SwarmDelegationPolicy {
+    maxRetriesOnOverloaded?: number;
+    initialBackoffMs?: number;
+    backoffMultiplier?: number;
+    maxBackoffMs?: number;
+    allowSpilloverRouting?: boolean;
+    maxRedirects?: number;
+}
 /**
  * A request to hand off work from one agent to another.
  *
@@ -43,6 +71,10 @@ export interface HandoffRequest {
     priority: number;
     /** Timeout in milliseconds for the handoff to be accepted */
     timeoutMs?: number;
+    /** SW4-004 budget envelope for cross-swarm handoff */
+    budget?: BudgetEnvelope;
+    /** SW4-004/SW4-005 delegation policy envelope */
+    delegationPolicy?: SwarmDelegationPolicy;
     /** Timestamp when the request was created (ISO-8601 string) */
     createdAt?: string;
 }
@@ -61,6 +93,17 @@ export interface HandoffResponse {
     acceptingAgent?: string;
     /** Reason for rejection (if not accepted) */
     rejectionReason?: string;
+    /** SW4-004/SW4-005 rejection code */
+    rejectionCode?: ErrorCode;
+    /** SW4-004 retry hint in milliseconds (for OVERLOADED) */
+    retryAfterMs?: number;
+    /** SW4-005 redirect target agent ID */
+    redirectToAgentId?: string;
+}
+export interface RejectHandoffOptions {
+    rejectionCode?: ErrorCode;
+    retryAfterMs?: number;
+    redirectToAgentId?: string;
 }
 /**
  * Error thrown when a handoff operation fails validation.
@@ -148,7 +191,7 @@ export declare class HandoffClient {
      * await client.rejectHandoff("handoff-123", "Agent at capacity");
      * ```
      */
-    rejectHandoff(handoffId: string, reason: string): Promise<void>;
+    rejectHandoff(handoffId: string, reason: string, options?: RejectHandoffOptions): Promise<void>;
     /**
      * Get all pending handoff requests for an agent.
      *

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-export declare const version = "0.5.0";
+export declare const version = "0.6.0";
 export * from './clients/router.js';
 export * from './clients/scheduler.js';
 export * from './clients/schedulerPolicy.js';
@@ -29,6 +29,9 @@ export * from './runtime/ackHelpers.js';
 export * from './runtime/activitySync.js';
 export * from './runtime/streams.js';
 export * from './runtime/negotiationEvents.js';
+export * from './runtime/delegation.js';
+export * from './runtime/cancellation.js';
+export * from './runtime/gateway.js';
 export * from './persistence/persistence.js';
 export * from './runtime/voting.js';
 export * from './runtime/policyStore.js';
@@ -50,3 +53,4 @@ export * from './secrets/resolver.js';
 export * from './secrets/backends/file.js';
 export * from './secrets/backends/keyring.js';
 export * from './secrets/factory.js';
+export * from './llm/index.js';

package/dist/types/internal/errorMapping.d.ts

@@ -15,6 +15,8 @@ export declare enum ErrorCode {
     TTL_EXPIRED = 13,
     DUPLICATE_DETECTED = 14,
     ALREADY_IN_PROGRESS = 15,
+    OVERLOADED = 16,
+    REDIRECT = 20,
     INTERNAL_ERROR = 99
 }
 export declare class Sw4rmError extends Error {

package/dist/types/llm/anthropic.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Anthropic LLM client for SW4RM agents.
+ *
+ * Thin wrapper around the Anthropic Messages REST API using native `fetch()`.
+ * Handles system-message normalization (Anthropic uses a top-level `system`
+ * param, not an in-band system message).
+ *
+ * Credentials (in order):
+ *   1. `apiKey` constructor parameter
+ *   2. `ANTHROPIC_API_KEY` environment variable
+ *   3. `~/.anthropic` file (plain text, one line)
+ *
+ * @module llm/anthropic
+ */
+import type { LlmClient, LlmResponse, QueryOptions } from './client.js';
+/** Options for constructing an AnthropicClient. */
+export interface AnthropicClientOptions {
+    /** API key override (takes precedence over env / dotfile). */
+    apiKey?: string;
+    /** Default model to use for queries. */
+    defaultModel?: string;
+    /** Request timeout in milliseconds. */
+    timeoutMs?: number;
+}
+/**
+ * LLM client for the Anthropic Messages API.
+ *
+ * Credentials are resolved from (in order):
+ *   1. `apiKey` constructor option
+ *   2. `ANTHROPIC_API_KEY` environment variable
+ *   3. `~/.anthropic` file (plain text, one line)
+ *
+ * Environment variables:
+ *   - `ANTHROPIC_API_KEY`: API key override
+ *   - `ANTHROPIC_DEFAULT_MODEL`: Default model override
+ */
+export declare class AnthropicClient implements LlmClient {
+    /** The resolved API key. */
+    readonly apiKey: string;
+    /** The default model used when none is specified per-call. */
+    readonly defaultModel: string;
+    private readonly timeoutMs;
+    private readonly rateLimiter;
+    constructor(opts?: AnthropicClientOptions);
+    /**
+     * Load API key from ~/.anthropic file.
+     *
+     * @returns The key string, or null if the file does not exist.
+     */
+    static loadKeyFile(): string | null;
+    private estimateTokens;
+    /**
+     * Map an HTTP error response to the appropriate LlmError subclass.
+     *
+     * @param status  - HTTP status code.
+     * @param body    - Parsed response body (if available).
+     * @param message - Raw error message.
+     */
+    private mapError;
+    /**
+     * Send a query to Anthropic and get a complete response.
+     *
+     * System prompts are sent via the top-level `system` parameter rather
+     * than as a system message in the messages array, per the Anthropic API
+     * specification.
+     *
+     * @param prompt - The user prompt/query.
+     * @param opts   - Optional query configuration.
+     * @returns LlmResponse with generated content and metadata.
+     */
+    query(prompt: string, opts?: QueryOptions): Promise<LlmResponse>;
+    /**
+     * Stream a query response chunk by chunk.
+     *
+     * Uses Server-Sent Events (SSE) streaming from the Anthropic API.
+     * System prompts are sent via the top-level `system` parameter.
+     *
+     * @param prompt - The user prompt/query.
+     * @param opts   - Optional query configuration.
+     * @yields Text chunks as they arrive from the API.
+     */
+    streamQuery(prompt: string, opts?: QueryOptions): AsyncGenerator<string>;
+}

package/dist/types/llm/client.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Abstract LLM client interface.
+ *
+ * This module provides the base interface for LLM clients used by SW4RM agents.
+ * Implementations can use Anthropic API directly, Groq API, or mock clients
+ * for testing.
+ *
+ * @module llm/client
+ */
+/** Response from an LLM API call. */
+export interface LlmResponse {
+    /** The generated text content. */
+    content: string;
+    /** The model that generated the response. */
+    model: string;
+    /** Token usage statistics (if available). */
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+    /** Additional response metadata. */
+    metadata?: Record<string, unknown>;
+}
+/** Options for LLM query calls. */
+export interface QueryOptions {
+    /** Optional system prompt for context. */
+    systemPrompt?: string;
+    /** Maximum tokens to generate (default 4096). */
+    maxTokens?: number;
+    /** Sampling temperature 0.0-2.0 (default 1.0). */
+    temperature?: number;
+    /** Override the default model. */
+    model?: string;
+}
+/**
+ * Abstract interface for LLM clients.
+ *
+ * All LLM client implementations must implement this interface.
+ * This allows SW4RM agents to be provider-agnostic.
+ *
+ * Implementations:
+ *   - GroqClient:      Uses Groq API directly (API key)
+ *   - AnthropicClient: Uses Anthropic API directly (API key)
+ *   - MockLlmClient:   For testing without API calls
+ */
+export interface LlmClient {
+    /**
+     * Send a query to the LLM and get a complete response.
+     *
+     * @param prompt - The user prompt/query to send.
+     * @param opts   - Optional query configuration.
+     * @returns LlmResponse with the generated content and metadata.
+     * @throws LlmError on API errors or failures.
+     * @throws LlmAuthenticationError on authentication failures.
+     * @throws LlmRateLimitError when rate limits are exceeded.
+     * @throws LlmTimeoutError when the request times out.
+     */
+    query(prompt: string, opts?: QueryOptions): Promise<LlmResponse>;
+    /**
+     * Stream a query response chunk by chunk.
+     *
+     * @param prompt - The user prompt/query to send.
+     * @param opts   - Optional query configuration.
+     * @yields Text chunks as they arrive from the API.
+     * @throws LlmError on API errors or failures.
+     */
+    streamQuery(prompt: string, opts?: QueryOptions): AsyncGenerator<string>;
+}
+/** Base exception for all LLM client errors. */
+export declare class LlmError extends Error {
+    constructor(message: string);
+}
+/**
+ * Raised when API authentication fails.
+ *
+ * Common causes:
+ *   - Invalid API key
+ *   - Expired credentials
+ *   - Missing credentials
+ */
+export declare class LlmAuthenticationError extends LlmError {
+    constructor(message: string);
+}
+/**
+ * Raised when API rate limits are exceeded.
+ *
+ * The caller should implement exponential backoff when handling this.
+ */
+export declare class LlmRateLimitError extends LlmError {
+    constructor(message: string);
+}
+/**
+ * Raised when an API request times out.
+ *
+ * Consider increasing the timeout or simplifying the prompt.
+ */
+export declare class LlmTimeoutError extends LlmError {
+    constructor(message: string);
+}
+/**
+ * Raised when the prompt exceeds the model's context length.
+ *
+ * Consider truncating the prompt or using a model with larger context.
+ */
+export declare class LlmContextLengthError extends LlmError {
+    constructor(message: string);
+}

package/dist/types/llm/factory.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Factory for creating LLM clients.
+ *
+ * Provides a simple way to create the appropriate LLM client based on
+ * environment configuration or explicit parameters.
+ *
+ * @module llm/factory
+ */
+import type { LlmClient } from './client.js';
+/** Options for the LLM client factory. */
+export interface CreateLlmClientOptions {
+    /**
+     * The type of client to create.
+     *
+     * Valid types: "groq", "anthropic", "mock".
+     *
+     * If not specified, reads from the `LLM_CLIENT_TYPE` environment variable.
+     * Defaults to "mock" if neither is set.
+     */
+    clientType?: string;
+    /**
+     * Default model to use for queries.
+     *
+     * If not specified, reads from the `LLM_DEFAULT_MODEL` environment variable.
+     * Falls back to each provider's default model.
+     */
+    model?: string;
+    /** API key override (passed to the provider constructor). */
+    apiKey?: string;
+    /** Request timeout in milliseconds (passed to the provider constructor). */
+    timeoutMs?: number;
+}
+/**
+ * Create an LLM client based on environment or explicit type.
+ *
+ * Resolution order for client type:
+ *   1. Explicit `clientType` option
+ *   2. `LLM_CLIENT_TYPE` environment variable
+ *   3. Default: "mock"
+ *
+ * Environment variables:
+ *   - `LLM_CLIENT_TYPE`: "groq", "anthropic", or "mock" (default: "mock")
+ *   - `LLM_DEFAULT_MODEL`: Default model override
+ *
+ * @param opts - Optional factory configuration.
+ * @returns An LlmClient instance of the requested type.
+ * @throws Error if an invalid client type is specified.
+ *
+ * @example
+ * ```typescript
+ * import { createLlmClient } from '@sw4rm/js-sdk';
+ *
+ * // Auto-detect from env (default: mock)
+ * const client = createLlmClient();
+ *
+ * // Explicit Groq client
+ * const groq = createLlmClient({ clientType: 'groq' });
+ *
+ * // Mock client for testing
+ * const mock = createLlmClient({ clientType: 'mock' });
+ *
+ * // Anthropic client with model override
+ * const claude = createLlmClient({
+ *   clientType: 'anthropic',
+ *   model: 'claude-sonnet-4-20250514',
+ * });
+ * ```
+ */
+export declare function createLlmClient(opts?: CreateLlmClientOptions): LlmClient;

package/dist/types/llm/groq.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Groq LLM client for SW4RM agents.
+ *
+ * Thin wrapper around the Groq REST API using native `fetch()`.
+ * No tool-calling or diagnostic mode -- just prompt in, text out,
+ * with rate limiting.
+ *
+ * Credentials (in order):
+ *   1. `apiKey` constructor parameter
+ *   2. `GROQ_API_KEY` environment variable
+ *   3. `~/.groq` file (plain text, one line)
+ *
+ * @module llm/groq
+ */
+import type { LlmClient, LlmResponse, QueryOptions } from './client.js';
+/** Options for constructing a GroqClient. */
+export interface GroqClientOptions {
+    /** API key override (takes precedence over env / dotfile). */
+    apiKey?: string;
+    /** Default model to use for queries. */
+    defaultModel?: string;
+    /** Request timeout in milliseconds. */
+    timeoutMs?: number;
+}
+/**
+ * LLM client for the Groq API (OpenAI-compatible chat completions).
+ *
+ * Credentials are resolved from (in order):
+ *   1. `apiKey` constructor option
+ *   2. `GROQ_API_KEY` environment variable
+ *   3. `~/.groq` file (plain text, one line)
+ *
+ * Environment variables:
+ *   - `GROQ_API_KEY`: API key override
+ *   - `GROQ_DEFAULT_MODEL`: Default model override
+ */
+export declare class GroqClient implements LlmClient {
+    /** The resolved API key. */
+    readonly apiKey: string;
+    /** The default model used when none is specified per-call. */
+    readonly defaultModel: string;
+    private readonly timeoutMs;
+    private readonly rateLimiter;
+    constructor(opts?: GroqClientOptions);
+    /**
+     * Load API key from ~/.groq file.
+     *
+     * @returns The key string, or null if the file does not exist.
+     */
+    static loadKeyFile(): string | null;
+    private estimateTokens;
+    private buildMessages;
+    /**
+     * Map an HTTP error response to the appropriate LlmError subclass.
+     *
+     * @param status  - HTTP status code.
+     * @param body    - Parsed response body (if available).
+     * @param message - Raw error message.
+     */
+    private mapError;
+    /**
+     * Send a query to Groq and get a complete response.
+     *
+     * @param prompt - The user prompt/query.
+     * @param opts   - Optional query configuration.
+     * @returns LlmResponse with generated content and metadata.
+     */
+    query(prompt: string, opts?: QueryOptions): Promise<LlmResponse>;
+    /**
+     * Stream a query response chunk by chunk.
+     *
+     * Uses Server-Sent Events (SSE) streaming from the Groq API.
+     *
+     * @param prompt - The user prompt/query.
+     * @param opts   - Optional query configuration.
+     * @yields Text chunks as they arrive from the API.
+     */
+    streamQuery(prompt: string, opts?: QueryOptions): AsyncGenerator<string>;
+}

package/dist/types/llm/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * SW4RM LLM -- LLM client abstraction for SW4RM agents.
+ *
+ * This module provides a unified interface for LLM interactions, supporting:
+ *   - Groq API (API key from ~/.groq or GROQ_API_KEY)
+ *   - Anthropic API (API key from ~/.anthropic or ANTHROPIC_API_KEY)
+ *   - Mock client for testing
+ *
+ * Usage:
+ * ```typescript
+ * import { createLlmClient } from '@sw4rm/js-sdk';
+ *
+ * // Create client via environment (LLM_CLIENT_TYPE=groq|anthropic|mock)
+ * const client = createLlmClient();
+ *
+ * // Or explicitly
+ * const client = createLlmClient({ clientType: 'groq' });
+ *
+ * // Query the LLM
+ * const response = await client.query(
+ *   'Analyze this task and suggest next steps',
+ *   { systemPrompt: 'You are a helpful task analysis agent.' },
+ * );
+ * console.log(response.content);
+ *
+ * // Stream responses
+ * for await (const chunk of client.streamQuery('Generate a report')) {
+ *   process.stdout.write(chunk);
+ * }
+ * ```
+ *
+ * @module llm
+ */
+export type { LlmClient, LlmResponse, QueryOptions } from './client.js';
+export { LlmError, LlmAuthenticationError, LlmRateLimitError, LlmTimeoutError, LlmContextLengthError, } from './client.js';
+export type { RateLimiterConfig } from './rateLimiter.js';
+export { buildRateLimiterConfig, TokenBucket, getGlobalRateLimiter, resetGlobalRateLimiter, } from './rateLimiter.js';
+export { MockLlmClient } from './mock.js';
+export type { MockCallRecord } from './mock.js';
+export { GroqClient } from './groq.js';
+export type { GroqClientOptions } from './groq.js';
+export { AnthropicClient } from './anthropic.js';
+export type { AnthropicClientOptions } from './anthropic.js';
+export { createLlmClient } from './factory.js';
+export type { CreateLlmClientOptions } from './factory.js';

package/dist/types/llm/mock.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Mock LLM client for testing.
+ *
+ * Provides deterministic responses without making actual API calls.
+ * Cycles through a canned response array and records call history.
+ *
+ * @module llm/mock
+ */
+import type { LlmClient, LlmResponse, QueryOptions } from './client.js';
+/** A recorded call entry from the mock client. */
+export interface MockCallRecord {
+    prompt: string;
+    systemPrompt?: string;
+    maxTokens: number;
+    temperature: number;
+    model: string;
+}
+/**
+ * Mock LLM client for testing without API calls.
+ *
+ * Returns configurable responses for testing purposes. If no responses are
+ * provided, returns a default echo of the prompt.
+ *
+ * @example
+ * ```typescript
+ * import { MockLlmClient } from '@sw4rm/js-sdk';
+ *
+ * // Simple usage -- returns echo of prompt
+ * const client = new MockLlmClient();
+ * const response = await client.query('Hello');
+ * console.log(response.content); // "Mock response to: Hello"
+ *
+ * // Custom responses (cycles)
+ * const client2 = new MockLlmClient({
+ *   responses: ['First response', 'Second response'],
+ * });
+ *
+ * // Custom response generator
+ * const client3 = new MockLlmClient({
+ *   responseGenerator: (prompt) => `Processed: ${prompt}`,
+ * });
+ * ```
+ */
+export declare class MockLlmClient implements LlmClient {
+    /** The model name returned in responses. */
+    readonly defaultModel: string;
+    private readonly responses;
+    private responseIndex;
+    private readonly responseGenerator;
+    private _callCount;
+    private readonly _callHistory;
+    constructor(opts?: {
+        /** Model name to return in responses. */
+        defaultModel?: string;
+        /** List of responses to return in order (cycles when exhausted). */
+        responses?: string[];
+        /** Function to generate responses from prompts. */
+        responseGenerator?: (prompt: string) => string;
+    });
+    /** Number of queries made to this client. */
+    get callCount(): number;
+    /** History of all calls made to this client. */
+    get callHistory(): readonly MockCallRecord[];
+    /** Reset call count, history, and response index. */
+    reset(): void;
+    /**
+     * Return a mock response.
+     *
+     * Priority for determining response content:
+     *   1. `responseGenerator` function (if provided)
+     *   2. `responses` array (cycles through entries)
+     *   3. Default echo: "Mock response to: <prompt>"
+     *
+     * @param prompt - The prompt (recorded in history).
+     * @param opts   - Optional query configuration (recorded in history).
+     * @returns LlmResponse with mock content.
+     */
+    query(prompt: string, opts?: QueryOptions): Promise<LlmResponse>;
+    /**
+     * Stream a mock response.
+     *
+     * Yields the response word by word to simulate streaming.
+     *
+     * @param prompt - The prompt (recorded in history).
+     * @param opts   - Optional query configuration.
+     * @yields Words from the mock response.
+     */
+    streamQuery(prompt: string, opts?: QueryOptions): AsyncGenerator<string>;
+}

package/dist/types/llm/rateLimiter.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Token bucket rate limiter for LLM API requests.
+ *
+ * Provides proactive rate limiting to avoid 429 errors. All LLM clients
+ * in the process share a global singleton bucket.
+ *
+ * Configuration via environment variables:
+ *   LLM_RATE_LIMIT_ENABLED:          "1" (default) or "0"
+ *   LLM_RATE_LIMIT_TOKENS_PER_MIN:   250000 (default, matches Groq free tier)
+ *   LLM_RATE_LIMIT_ADAPTIVE:         "1" (default) -- reduce budget on 429, recover on success
+ *   LLM_RATE_LIMIT_REDUCTION_FACTOR: 0.7
+ *   LLM_RATE_LIMIT_RECOVERY_FACTOR:  1.1
+ *   LLM_RATE_LIMIT_COOLDOWN_SECONDS: 30
+ *   LLM_RATE_LIMIT_RECOVERY_SUCCESS_THRESHOLD: 20
+ *
+ * @module llm/rateLimiter
+ */
+/** Configuration for the token bucket rate limiter. */
+export interface RateLimiterConfig {
+    /** Token budget per minute. */
+    tokensPerMinute: number;
+    /** Burst allowance multiplier (1.0 = no burst above budget). */
+    burstAllowance: number;
+    /** Minimum tokens assumed per request. */
+    minTokensPerRequest: number;
+    /** Maximum seconds to wait before throwing a timeout. */
+    maxWaitSeconds: number;
+    /** Whether the rate limiter is enabled at all. */
+    enabled: boolean;
+    /** Whether adaptive throttling is enabled. */
+    adaptiveEnabled: boolean;
+    /** Factor to multiply budget by after a 429 event. */
+    reductionFactor: number;
+    /** Factor to multiply budget by during recovery. */
+    recoveryFactor: number;
+    /** Seconds to wait after last 429 before allowing recovery. */
+    cooldownSeconds: number;
+    /** Number of consecutive successes required before recovery. */
+    successesForRecovery: number;
+}
+/** Build a RateLimiterConfig from environment variables and optional overrides. */
+export declare function buildRateLimiterConfig(overrides?: Partial<RateLimiterConfig>): RateLimiterConfig;
+/**
+ * Token bucket rate limiter with adaptive throttling.
+ *
+ * Refills tokens at a steady rate. When a 429 is reported via
+ * {@link recordRateLimit}, the budget is reduced. After enough successes
+ * and a cooldown period, the budget recovers.
+ */
+export declare class TokenBucket {
+    private readonly config;
+    private readonly baseTpm;
+    private currentTpm;
+    private readonly minTpm;
+    private tokens;
+    private lastRefill;
+    private lastRateLimitTime;
+    private successesSinceLimit;
+    constructor(config?: Partial<RateLimiterConfig>);
+    private refill;
+    private maybeRecover;
+    /**
+     * Acquire tokens, waiting if necessary.
+     *
+     * @param estimatedTokens - Estimated token count for the request.
+     * @returns Time spent waiting in milliseconds (0 if immediate).
+     * @throws Error if waiting exceeds {@link RateLimiterConfig.maxWaitSeconds}.
+     */
+    acquire(estimatedTokens: number): Promise<number>;
+    /**
+     * Record a 429 event -- adaptively reduce budget.
+     *
+     * Call this when the upstream API returns HTTP 429 or an equivalent
+     * rate-limit error.
+     */
+    recordRateLimit(): void;
+    /**
+     * Record a successful request for adaptive recovery.
+     *
+     * Call this after each successful API response.
+     */
+    recordSuccess(): void;
+    /** Current available token count. */
+    get availableTokens(): number;
+    /** Current tokens-per-minute budget (may be reduced after 429). */
+    get currentTokensPerMinute(): number;
+}
+/**
+ * Get or create the global rate limiter singleton.
+ *
+ * @param config - Optional configuration overrides (only used on first call).
+ * @returns The shared TokenBucket instance.
+ */
+export declare function getGlobalRateLimiter(config?: Partial<RateLimiterConfig>): TokenBucket;
+/**
+ * Reset the global rate limiter (for testing).
+ *
+ * Clears the singleton so the next call to {@link getGlobalRateLimiter}
+ * creates a fresh instance.
+ */
+export declare function resetGlobalRateLimiter(): void;