@sw4rm/js-sdk 0.4.0 → 0.6.0

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

@@ -0,0 +1,155 @@
+/**
+ * Negotiation Room storage backend abstraction.
+ *
+ * This module provides a pluggable storage layer for NegotiationRoomClient,
+ * enabling shared state across multiple client instances.
+ *
+ * The key insight is that NegotiationRoomClient previously used instance-local
+ * storage (private Maps), which broke multi-instance deployments. By extracting
+ * storage into a separate abstraction that can be shared, we enable:
+ *
+ * 1. Multiple client instances sharing the same storage
+ * 2. Producer/Critic/Coordinator agents in different processes sharing state
+ * 3. Future gRPC integration where the server becomes the source of truth
+ *
+ * For persistent storage backends (JSON file, Redis, PostgreSQL), see the
+ * colony/stores module which provides optional persistence implementations.
+ *
+ * Based on the PolicyStore pattern established in policyStore.ts.
+ */
+import { NegotiationProposal, NegotiationVote, NegotiationDecision } from './negotiationRoom.js';
+/**
+ * Error thrown when a negotiation room store operation fails.
+ */
+export declare class NegotiationRoomStoreError extends Error {
+    constructor(message: string);
+}
+/**
+ * Interface defining the contract for negotiation room storage backends.
+ *
+ * All storage implementations must support these operations for proposals,
+ * votes, and decisions. This follows the same pattern as PolicyStore,
+ * enabling pluggable backends ranging from in-memory to file-based to gRPC-based.
+ */
+export interface NegotiationRoomStore {
+    /**
+     * Check if a proposal exists for the given artifact_id.
+     *
+     * @param artifactId - Unique identifier for the artifact
+     * @returns True if a proposal exists, false otherwise
+     */
+    hasProposal(artifactId: string): Promise<boolean>;
+    /**
+     * Retrieve a proposal by artifact_id.
+     *
+     * @param artifactId - Unique identifier for the artifact
+     * @returns The proposal if found, null otherwise
+     */
+    getProposal(artifactId: string): Promise<NegotiationProposal | null>;
+    /**
+     * Save a proposal to storage.
+     *
+     * @param proposal - The proposal to save
+     * @throws NegotiationRoomStoreError if a proposal with the same artifact_id already exists
+     */
+    saveProposal(proposal: NegotiationProposal): Promise<void>;
+    /**
+     * List all proposals, optionally filtered by negotiation room.
+     *
+     * @param negotiationRoomId - If provided, only return proposals for this room
+     * @returns List of proposals matching the filter criteria
+     */
+    listProposals(negotiationRoomId?: string): Promise<NegotiationProposal[]>;
+    /**
+     * Retrieve all votes for a specific artifact.
+     *
+     * @param artifactId - The identifier of the artifact
+     * @returns List of all votes for the artifact (empty array if no votes)
+     */
+    getVotes(artifactId: string): Promise<NegotiationVote[]>;
+    /**
+     * Add a vote for an artifact.
+     *
+     * @param vote - The vote to add
+     * @throws NegotiationRoomStoreError if the critic has already voted for this artifact
+     */
+    addVote(vote: NegotiationVote): Promise<void>;
+    /**
+     * Retrieve the decision for an artifact.
+     *
+     * @param artifactId - The identifier of the artifact
+     * @returns The decision if available, null otherwise
+     */
+    getDecision(artifactId: string): Promise<NegotiationDecision | null>;
+    /**
+     * Save a decision for an artifact.
+     *
+     * @param decision - The decision to save
+     * @throws NegotiationRoomStoreError if a decision already exists for this artifact
+     */
+    saveDecision(decision: NegotiationDecision): Promise<void>;
+}
+/**
+ * In-memory implementation of NegotiationRoomStore.
+ *
+ * Stores proposals, votes, and decisions in memory. Data is lost when the
+ * process terminates. Suitable for testing and single-process deployments.
+ *
+ * Thread-safety: JavaScript is single-threaded, but async operations are
+ * properly sequenced.
+ *
+ * @example
+ * ```typescript
+ * // Create a single shared store
+ * const sharedStore = new InMemoryNegotiationRoomStore();
+ *
+ * // Pass to multiple clients
+ * const producerClient = new NegotiationRoomClient({ store: sharedStore });
+ * const criticClient = new NegotiationRoomClient({ store: sharedStore });
+ * const coordinatorClient = new NegotiationRoomClient({ store: sharedStore });
+ *
+ * // Now all clients share the same state
+ * ```
+ */
+export declare class InMemoryNegotiationRoomStore implements NegotiationRoomStore {
+    private proposals;
+    private votes;
+    private decisions;
+    hasProposal(artifactId: string): Promise<boolean>;
+    getProposal(artifactId: string): Promise<NegotiationProposal | null>;
+    saveProposal(proposal: NegotiationProposal): Promise<void>;
+    listProposals(negotiationRoomId?: string): Promise<NegotiationProposal[]>;
+    getVotes(artifactId: string): Promise<NegotiationVote[]>;
+    addVote(vote: NegotiationVote): Promise<void>;
+    getDecision(artifactId: string): Promise<NegotiationDecision | null>;
+    saveDecision(decision: NegotiationDecision): Promise<void>;
+}
+/**
+ * Get the default shared in-memory store.
+ *
+ * This provides a convenient way to share state across multiple
+ * NegotiationRoomClient instances within the same process without
+ * explicitly passing a store instance.
+ *
+ * @returns The default shared InMemoryNegotiationRoomStore instance
+ *
+ * @example
+ * ```typescript
+ * // All clients automatically share the same store
+ * const client1 = new NegotiationRoomClient();  // Uses default store
+ * const client2 = new NegotiationRoomClient();  // Uses same default store
+ *
+ * // Equivalent to:
+ * const store = getDefaultStore();
+ * const client1 = new NegotiationRoomClient({ store });
+ * const client2 = new NegotiationRoomClient({ store });
+ * ```
+ */
+export declare function getDefaultStore(): InMemoryNegotiationRoomStore;
+/**
+ * Reset the default store (primarily for testing).
+ *
+ * This clears the default store singleton, causing a new store
+ * to be created on the next call to getDefaultStore().
+ */
+export declare function resetDefaultStore(): void;

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

@@ -290,6 +290,21 @@ export declare class WorkflowClient {
      * Check if a workflow instance is complete and update its status.
      */
     private checkWorkflowCompletion;
+    /**
+     * Resume a workflow by marking a node as completed and advancing dependents.
+     *
+     * Implements the ResumeWorkflow RPC (spec §17.7 MUST). Marks the specified
+     * node as COMPLETED, updates workflow data if provided, then transitions
+     * dependent nodes from PENDING to READY when all their dependencies are met.
+     *
+     * @param instanceId - The ID of the workflow instance
+     * @param nodeId - The ID of the node to mark as completed
+     * @param workflowData - Optional updated workflow data (JSON string)
+     * @param metadata - Optional metadata for the resume operation
+     * @returns The updated workflow instance
+     * @throws WorkflowValidationError if the instance or node does not exist
+     */
+    resumeWorkflow(instanceId: string, nodeId: string, workflowData?: string, metadata?: Record<string, string>): Promise<WorkflowInstance>;
     /**
      * Update the shared workflow data.
      *

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

@@ -0,0 +1,100 @@
+export { ErrorCode } from '../internal/errorMapping.js';
+export { MessageType } from '../internal/envelope.js';
+/**
+ * CommunicationClass constants (spec section 7.3).
+ */
+export declare enum CommunicationClass {
+    COMM_CLASS_UNSPECIFIED = 0,
+    PRIVILEGED = 1,
+    STANDARD = 2,
+    BULK = 3
+}
+/**
+ * DebateIntensity constants (spec section 17).
+ */
+export declare enum DebateIntensity {
+    DEBATE_INTENSITY_UNSPECIFIED = 0,
+    LOWEST = 1,
+    LOW = 2,
+    MEDIUM = 3,
+    HIGH = 4,
+    HIGHEST = 5
+}
+/**
+ * HitlReasonType constants (spec section 15).
+ */
+export declare enum HitlReasonType {
+    HITL_REASON_UNSPECIFIED = 0,
+    CONFLICT = 1,
+    SECURITY_APPROVAL = 2,
+    TASK_ESCALATION = 3,
+    MANUAL_OVERRIDE = 4,
+    WORKTREE_OVERRIDE = 5,
+    DEBATE_DEADLOCK = 6,
+    TOOL_PRIVILEGE_ESCALATION = 7,
+    CONNECTOR_APPROVAL = 8
+}
+/**
+ * AgentState constants (spec section 8).
+ * Re-exported from agentState.ts for convenience.
+ */
+export { AgentState } from '../runtime/agentState.js';
+/**
+ * AckStage constants.
+ */
+export declare enum AckStage {
+    ACK_STAGE_UNSPECIFIED = 0,
+    RECEIVED = 1,
+    READ = 2,
+    FULFILLED = 3,
+    REJECTED = 4,
+    FAILED = 5,
+    TIMED_OUT = 6
+}
+/**
+ * EnvelopeState lifecycle constants.
+ *
+ * Tracks the lifecycle of an envelope through the system:
+ * SENT -> RECEIVED -> READ -> FULFILLED/REJECTED/FAILED/TIMED_OUT
+ */
+export declare enum EnvelopeState {
+    ENVELOPE_STATE_UNSPECIFIED = 0,
+    SENT = 1,
+    RECEIVED = 2,
+    READ = 3,
+    FULFILLED = 4,
+    REJECTED = 5,
+    FAILED = 6,
+    TIMED_OUT = 7
+}
+/**
+ * WorktreeState constants (spec section 16).
+ */
+export declare enum WorktreeStateEnum {
+    WORKTREE_STATE_UNSPECIFIED = 0,
+    UNBOUND = 1,
+    BOUND_HOME = 2,
+    SWITCH_PENDING = 3,
+    BOUND_NON_HOME = 4,
+    BIND_FAILED = 5
+}
+/**
+ * Default timeout for acknowledgement in milliseconds.
+ */
+export declare const DEFAULT_ACK_TIMEOUT_MS = 10000;
+/**
+ * Deduplication window in seconds.
+ */
+export declare const DEDUP_WINDOW_S = 3600;
+/**
+ * Check if an envelope state is terminal (no further transitions expected).
+ *
+ * Terminal states: FULFILLED, REJECTED, FAILED, TIMED_OUT
+ */
+export declare function isTerminalEnvelopeState(state: EnvelopeState): boolean;
+/**
+ * Update the state of an envelope object.
+ */
+export declare function updateEnvelopeState<T extends {
+    state?: number;
+}>(envelope: T, newState: EnvelopeState): T;

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-export declare const version = "0.4.0";
+export declare const version = "0.6.0";
 export * from './clients/router.js';
 export * from './clients/scheduler.js';
 export * from './clients/schedulerPolicy.js';
@@ -12,32 +12,40 @@ export * from './clients/reasoning.js';
 export * from './clients/connector.js';
 export * from './clients/registry.js';
 export * from './clients/negotiationRoom.js';
+export * from './clients/negotiationRoomStore.js';
 export * from './clients/handoff.js';
 export * from './clients/workflow.js';
 export { buildEnvelope, type EnvelopeBuilt, type EnvelopeInput, nowTimestamp, type Timestamp, } from './internal/envelope.js';
 export * from './internal/errorMapping.js';
-export * from './internal/baseClient.js';
+export { ClientOptions, BaseClient, } from './internal/baseClient.js';
 export * from './internal/time.js';
 export * from './internal/interceptors.js';
 export * from './internal/worktreeState.js';
 export * from './internal/worktreePolicy.js';
 export * from './internal/runtime/activityBuffer.js';
-export * from './internal/runtime/ackLifecycle.js';
-export * from './internal/runtime/messageProcessor.js';
+export { AckState, ACKLifecycleManager, } from './internal/runtime/ackLifecycle.js';
+export { EnvelopeLike, MessageProcessor, } from './internal/runtime/messageProcessor.js';
 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';
-export * from './runtime/agentState.js';
+export { AgentState, isValidTransition, getValidTransitions, type AgentLifecycleHooks, AgentStateMachine, } from './runtime/agentState.js';
 export * from './internal/ids.js';
 export * from './internal/idempotency.js';
 export * from './runtime/persistenceAdapter.js';
 export * from './internal/errorMapper.js';
 export * from './internal/ack.js';
 export * from './internal/control.js';
+export { CommunicationClass, DebateIntensity, HitlReasonType, AckStage, EnvelopeState, WorktreeStateEnum, DEFAULT_ACK_TIMEOUT_MS, DEDUP_WINDOW_S, isTerminalEnvelopeState, updateEnvelopeState, MessageType, } from './constants/index.js';
+export * from './audit.js';
+export * from './agentConfig.js';
+export { type EnvelopeRecord, PersistentActivityBuffer, } from './persistentActivityBuffer.js';
 export * from './secrets/types.js';
 export * from './secrets/errors.js';
 export * from './secrets/backend.js';
@@ -45,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/baseClient.d.ts

@@ -25,6 +25,12 @@ export declare class BaseClient {
     protected readonly interceptors: InterceptorChain;
     protected readonly errorMapper: ErrorCodeMapper;
     constructor(opts: ClientOptions);
+    /**
+     * Resolves the protos directory, checking multiple locations:
+     * 1. npm package: ./protos relative to package root
+     * 2. Monorepo dev: ../../../../protos relative to this file
+     */
+    private resolveProtosDir;
     protected channelCredentials(): grpc.ChannelCredentials;
     protected metadata(base?: grpc.Metadata): grpc.Metadata;
     protected deadlineFromNow(): Date;

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

@@ -30,6 +30,10 @@ export interface EnvelopeInput {
     hlc_timestamp?: string;
     ttl_ms?: number;
     timestamp?: Date;
+    state?: number;
+    effective_policy_id?: string;
+    audit_proof?: Uint8Array;
+    audit_policy_id?: string;
 }
 export interface EnvelopeBuilt {
     message_id: string;
@@ -47,7 +51,19 @@ export interface EnvelopeBuilt {
     ttl_ms?: number;
     timestamp: Timestamp;
     payload?: Uint8Array;
+    state: number;
+    effective_policy_id: string;
+    audit_proof: Uint8Array;
+    audit_policy_id: string;
 }
 export declare function nowTimestamp(date?: Date): Timestamp;
+/**
+ * Generate a stub HLC timestamp in the canonical format `HLC:<wall>:<logical>:<node>`.
+ *
+ * Per spec section 4, the HLC format combines wall-clock time (Unix microseconds),
+ * a logical counter (always 0 in this stub), and a node identifier (hostname).
+ * Full HLC implementations should increment the logical counter on concurrent
+ * events within the same microsecond.
+ */
 export declare function nowHlcStub(date?: Date): string;
 export declare function buildEnvelope(input: EnvelopeInput): EnvelopeBuilt;

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

@@ -13,6 +13,10 @@ export declare enum ErrorCode {
     PARTIAL_DELIVERY = 11,
     FORCED_PREEMPTION = 12,
     TTL_EXPIRED = 13,
+    DUPLICATE_DETECTED = 14,
+    ALREADY_IN_PROGRESS = 15,
+    OVERLOADED = 16,
+    REDIRECT = 20,
     INTERNAL_ERROR = 99
 }
 export declare class Sw4rmError extends Error {
@@ -24,4 +28,116 @@ export declare class Sw4rmError extends Error {
         details?: string;
     });
 }
+/**
+ * Thrown when input validation fails.
+ * Default error code: VALIDATION_ERROR
+ */
+export declare class ValidationError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when an operation times out.
+ * Default error code: ACK_TIMEOUT
+ */
+export declare class TimeoutError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when an invalid state transition is attempted.
+ * Default error code: INTERNAL_ERROR
+ */
+export declare class StateTransitionError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when negotiation fails.
+ * Default error code: INTERNAL_ERROR
+ */
+export declare class NegotiationError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when the activity buffer is full.
+ * Default error code: BUFFER_FULL
+ */
+export declare class BufferFullError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when no route to destination exists.
+ * Default error code: NO_ROUTE
+ */
+export declare class RouteError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when permission is denied.
+ * Default error code: PERMISSION_DENIED
+ */
+export declare class PermissionError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when a duplicate request is detected.
+ * Default error code: DUPLICATE_DETECTED
+ */
+export declare class DuplicateDetectedError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when an agent is forcibly preempted by the scheduler.
+ * Default error code: FORCED_PREEMPTION
+ */
+export declare class PreemptionError extends Sw4rmError {
+    readonly agentId: string;
+    readonly reason: string;
+    constructor(agentId: string, reason: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when a worktree operation fails (bind, switch, etc.).
+ * Default error code: INTERNAL_ERROR
+ */
+export declare class WorktreeError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when an action violates a configured policy.
+ * Default error code: PERMISSION_DENIED
+ */
+export declare class PolicyViolationError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
 export declare function mapGrpcStatusToErrorCode(status: number): ErrorCode;

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

@@ -1,14 +1,74 @@
 export type WorktreeState = 'UNBOUND' | 'BOUND_HOME' | 'SWITCH_PENDING' | 'BOUND_NON_HOME' | 'BIND_FAILED';
+/**
+ * Check if a worktree state transition is valid.
+ */
+export declare function isValidWorktreeTransition(from: WorktreeState, to: WorktreeState): boolean;
+export declare class WorktreeTransitionError extends Error {
+    readonly fromState: WorktreeState;
+    readonly toState: WorktreeState;
+    constructor(from: WorktreeState, to: WorktreeState);
+}
+/**
+ * Persistent worktree state machine with full spec §16 support.
+ *
+ * Supports SWITCH_PENDING approval flow with TTL on BOUND_NON_HOME.
+ */
 export declare class PersistentWorktreeState {
     private state;
     private repoId?;
     private worktreeId?;
+    private homeRepoId?;
+    private homeWorktreeId?;
+    private switchTtlMs?;
+    private switchTimer?;
+    /**
+     * Transition to a new state with validation.
+     * @throws WorktreeTransitionError if transition is invalid
+     */
+    private transitionTo;
+    /**
+     * Bind to a home worktree (UNBOUND -> BOUND_HOME or BIND_FAILED -> BOUND_HOME).
+     */
     bind(repoId: string, worktreeId: string): void;
+    /**
+     * Handle bind failure (UNBOUND -> BIND_FAILED).
+     */
+    bindFailed(): void;
+    /**
+     * Unbind from current worktree.
+     */
     unbind(): void;
+    /**
+     * Request switch to a non-home worktree (BOUND_HOME -> SWITCH_PENDING).
+     * Requires approval or rejection before taking effect.
+     */
+    requestSwitch(targetRepoId: string, targetWorktreeId: string): void;
+    /**
+     * Approve a pending switch (SWITCH_PENDING -> BOUND_NON_HOME).
+     * @param ttlMs - Time-to-live in milliseconds before auto-reverting to BOUND_HOME
+     */
+    approveSwitch(ttlMs?: number): void;
+    /**
+     * Reject a pending switch (SWITCH_PENDING -> BOUND_HOME).
+     */
+    rejectSwitch(): void;
+    /**
+     * Revert from non-home to home worktree (BOUND_NON_HOME -> BOUND_HOME).
+     * Called on TTL expiry or explicit revoke.
+     */
+    revertToHome(): void;
+    /**
+     * Reset from BIND_FAILED to UNBOUND for retry.
+     */
+    resetFromFailed(): void;
+    private clearSwitchTimer;
     setState(state: WorktreeState): void;
     current(): {
         state: WorktreeState;
         repo_id: string | undefined;
         worktree_id: string | undefined;
+        home_repo_id: string | undefined;
+        home_worktree_id: string | undefined;
+        switch_ttl_ms: number | undefined;
     };
 }

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>;
+}