@sw4rm/js-sdk 0.4.0 → 0.6.0

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;

package/dist/types/persistentActivityBuffer.d.ts

@@ -0,0 +1,94 @@
+import { EnvelopeState } from './constants/index.js';
+export interface EnvelopeRecord {
+    message_id: string;
+    direction: 'in' | 'out';
+    envelope: Record<string, unknown>;
+    ts_ms: number;
+    ack_stage: number;
+    error_code: number;
+    ack_note: string;
+}
+export interface PersistenceBackend {
+    load(): {
+        records: Record<string, EnvelopeRecord>;
+        order: string[];
+    };
+    save(records: Record<string, EnvelopeRecord>, order: string[]): void;
+    clear(): void;
+}
+/**
+ * JSON file persistence backend.
+ */
+export declare class JSONFilePersistence implements PersistenceBackend {
+    private filePath;
+    constructor(filePath?: string);
+    load(): {
+        records: Record<string, EnvelopeRecord>;
+        order: string[];
+    };
+    save(records: Record<string, EnvelopeRecord>, order: string[]): void;
+    clear(): void;
+}
+/**
+ * Persistent Activity Buffer with Three-ID model support.
+ *
+ * Tracks inbound/outbound envelopes by message_id and records ACK progression.
+ * Supports multiple persistence backends (JSON file, etc.) and provides
+ * reconciliation on startup to restore previous state.
+ *
+ * When the buffer is full, new records are REJECTED with BufferFullError
+ * per spec compliance (not silently pruned).
+ */
+export declare class PersistentActivityBuffer {
+    private byId;
+    private byIdempotencyToken;
+    private order;
+    private maxItems;
+    private persistence;
+    private dedupWindowS;
+    private dirty;
+    constructor(opts?: {
+        maxItems?: number;
+        persistence?: PersistenceBackend;
+        dedupWindowS?: number;
+    });
+    private loadFromPersistence;
+    private saveToPersistence;
+    private checkCapacity;
+    private cleanupExpiredDedupEntries;
+    /**
+     * Record an incoming envelope. Throws BufferFullError if buffer is at capacity.
+     */
+    recordIncoming(envelope: Record<string, unknown>): EnvelopeRecord;
+    /**
+     * Record an outgoing envelope. Throws BufferFullError if buffer is at capacity.
+     */
+    recordOutgoing(envelope: Record<string, unknown>): EnvelopeRecord;
+    /**
+     * Process an ACK for a previously recorded message.
+     */
+    ack(ackMsg: {
+        ack_for_message_id: string;
+        ack_stage?: number;
+        error_code?: number;
+        note?: string;
+    }): EnvelopeRecord | undefined;
+    /** Get record by message ID. */
+    get(messageId: string): EnvelopeRecord | undefined;
+    /** Get record by idempotency token (for deduplication). */
+    getByIdempotencyToken(token: string): EnvelopeRecord | undefined;
+    /** Get all un-ACKed records. */
+    unacked(): EnvelopeRecord[];
+    /** Get N most recent records. */
+    recent(n?: number): EnvelopeRecord[];
+    /** Update envelope state for a message. */
+    updateState(messageId: string, newState: EnvelopeState): EnvelopeRecord | undefined;
+    /** Return unacked outgoing messages for reconciliation. */
+    reconcile(): EnvelopeRecord[];
+    /** Force save to persistence. */
+    flush(): void;
+    /** Clear all records. */
+    clear(): void;
+    /** Get the count of records. */
+    get size(): number;
+}

package/dist/types/runtime/cancellation.d.ts

@@ -0,0 +1,41 @@
+import { ErrorCode } from '../internal/errorMapping.js';
+export declare const MIN_GRACE_PERIOD_MS = 5000;
+export type CancellationMetadataValue = string | number | boolean | null;
+export type CancellationMetadata = Record<string, CancellationMetadataValue>;
+export interface CancelDelegationRequest {
+    correlationId: string;
+    reason?: string;
+    gracePeriodMs?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface CancelDelegationResponse {
+    acknowledged: boolean;
+    correlationId: string;
+    gracePeriodMs: number;
+    message: string;
+    metadata: CancellationMetadata;
+}
+export interface CancellationFlag {
+    cancelled: boolean;
+    gracePeriodMs: number;
+    cancelTimeMs: number;
+    metadata: CancellationMetadata;
+}
+export interface CancellationManagerOptions {
+    nowMsFn?: () => number;
+}
+export declare class CancellationValidationError extends Error {
+    constructor(message: string);
+}
+export declare class CancellationManager {
+    readonly childDelegations: Map<string, Set<string>>;
+    readonly cancellationFlags: Map<string, CancellationFlag>;
+    private readonly nowMs;
+    constructor(options?: CancellationManagerOptions);
+    registerChildDelegation(parentCorrelationId: string, childCorrelationId: string): void;
+    handleCancelDelegation(cancel: CancelDelegationRequest): CancelDelegationResponse;
+    isCancelled(correlationId: string): boolean;
+    isGraceExpired(correlationId: string, nowMs?: number): boolean;
+    forcedPreemptionErrorCode(correlationId: string, nowMs?: number): ErrorCode;
+    collectForcedPreemptions(correlationIds: Iterable<string>, nowMs?: number): Set<string>;
+}

package/dist/types/runtime/delegation.d.ts

@@ -0,0 +1,20 @@
+import { type BudgetEnvelope, type HandoffRequest, type HandoffResponse, type SwarmDelegationPolicy } from '../clients/handoff.js';
+export declare const RETRY_AFTER_JITTER_RATIO = 0.2;
+export declare const DEFAULT_EFFECTIVE_MAX_REDIRECTS = 2;
+export interface DelegateToSwarmOptions {
+    sendHandoffFn: (request: HandoffRequest) => Promise<HandoffResponse> | HandoffResponse;
+    fromAgent: string;
+    toAgent: string;
+    reason: string;
+    budget: BudgetEnvelope;
+    delegationPolicy?: SwarmDelegationPolicy;
+    requestId?: string;
+    contextSnapshot?: Uint8Array;
+    capabilitiesRequired?: string[];
+    priority?: number;
+    timeoutMs?: number;
+    nowMsFn?: () => number;
+    sleepMsFn?: (milliseconds: number) => Promise<void> | void;
+    randUniformFn?: (low: number, high: number) => number;
+}
+export declare function delegateToSwarm(options: DelegateToSwarmOptions): Promise<HandoffResponse>;