@sw4rm/js-sdk 0.4.0 → 0.6.0

package/dist/types/agentConfig.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Addresses for SW4RM services.
+ *
+ * All service endpoints with their default ports. Individual addresses
+ * can be overridden via environment variables or programmatic configuration.
+ */
+export interface Endpoints {
+    /** Router service address (default: http://localhost:50051) */
+    router: string;
+    /** Registry service address (default: http://localhost:50052) */
+    registry: string;
+    /** Scheduler service address (default: http://localhost:50053) */
+    scheduler: string;
+    /** Human-in-the-loop service address (default: http://localhost:50054) */
+    hitl: string;
+    /** Worktree service address (default: http://localhost:50055) */
+    worktree: string;
+    /** Tool execution service address (default: http://localhost:50056) */
+    tool: string;
+    /** Connector service address (default: http://localhost:50057) */
+    connector: string;
+    /** Negotiation service address (default: http://localhost:50058) */
+    negotiation: string;
+    /** Reasoning service address (default: http://localhost:50059) */
+    reasoning: string;
+    /** Logging service address (default: http://localhost:50060) */
+    logging: string;
+}
+/**
+ * Retry policy for unary gRPC calls.
+ *
+ * Controls exponential backoff behavior for transient failures.
+ */
+export interface RetryPolicy {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts: number;
+    /** Initial backoff delay in milliseconds (default: 200) */
+    initialBackoffMs: number;
+    /** Maximum backoff delay in milliseconds (default: 2000) */
+    maxBackoffMs: number;
+    /** Backoff multiplier for exponential backoff (default: 2) */
+    multiplier: number;
+}
+/**
+ * Agent runtime configuration.
+ *
+ * Complete configuration object for an SW4RM agent including:
+ * - Identity (agent_id, name, description)
+ * - Service endpoints
+ * - Timeouts and retry policies
+ * - Capabilities and metadata
+ */
+export interface AgentConfig {
+    /** Unique agent identifier */
+    agentId: string;
+    /** Human-readable agent name */
+    name: string;
+    /** Optional agent description */
+    description?: string;
+    /** Agent version (default: "0.1.0") */
+    version: string;
+    /** List of agent capabilities */
+    capabilities: string[];
+    /** Service endpoints configuration */
+    endpoints: Endpoints;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeoutMs: number;
+    /** Stream keepalive interval in milliseconds (default: 60000) */
+    streamKeepaliveMs: number;
+    /** Retry policy for unary calls */
+    retry: RetryPolicy;
+    /** Additional metadata key-value pairs */
+    metadata: Record<string, string>;
+    /** Communication class (0=UNSPECIFIED, 1=PRIVILEGED, 2=STANDARD, 3=BULK) */
+    communicationClass: number;
+    /** Supported modalities (e.g., ["application/json", "text/plain"]) */
+    modalitiesSupported: string[];
+    /** Reasoning connectors this agent can use */
+    reasoningConnectors: string[];
+    /** Optional public key for cryptographic operations */
+    publicKey?: Uint8Array;
+}
+/**
+ * Comprehensive SW4RM SDK configuration.
+ *
+ * Extended configuration object that includes all SDK settings:
+ * - Service endpoints
+ * - Timeouts and retry policies
+ * - Observability flags (metrics, tracing)
+ * - Feature flags
+ * - Logging configuration
+ */
+export interface SW4RMConfig {
+    /** Router service address */
+    routerAddr: string;
+    /** Registry service address */
+    registryAddr: string;
+    /** Default timeout for operations in milliseconds (default: 30000) */
+    defaultTimeoutMs: number;
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries: number;
+    /** Enable metrics collection and export (default: true) */
+    enableMetrics: boolean;
+    /** Enable distributed tracing (default: true) */
+    enableTracing: boolean;
+    /** Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO) */
+    logLevel: string;
+    /** Feature flag mappings (name -> value) */
+    featureFlags: Record<string, any>;
+}
+/**
+ * Get default endpoints with environment variable overrides.
+ *
+ * Environment variables supported:
+ * - SW4RM_ROUTER_ADDR
+ * - SW4RM_REGISTRY_ADDR
+ * - SW4RM_SCHEDULER_ADDR
+ * - SW4RM_HITL_ADDR
+ * - SW4RM_WORKTREE_ADDR
+ * - SW4RM_TOOL_ADDR
+ * - SW4RM_CONNECTOR_ADDR
+ * - SW4RM_NEGOTIATION_ADDR
+ * - SW4RM_REASONING_ADDR
+ * - SW4RM_LOGGING_ADDR
+ *
+ * @returns Endpoints configuration with env overrides applied
+ */
+export declare function defaultEndpoints(): Endpoints;
+/**
+ * Get default retry policy.
+ *
+ * @returns RetryPolicy with standard exponential backoff settings
+ */
+export declare function defaultRetryPolicy(): RetryPolicy;
+/**
+ * Create a default agent configuration.
+ *
+ * Provides sensible defaults for all fields. Applications should override
+ * at least agentId and name for production use.
+ *
+ * @param agentId - Optional agent ID (default: "agent-1")
+ * @param name - Optional agent name (default: "Agent")
+ * @returns AgentConfig with defaults populated
+ */
+export declare function defaultAgentConfig(agentId?: string, name?: string): AgentConfig;
+/**
+ * Load agent configuration from environment variables.
+ *
+ * Environment variables supported:
+ * - AGENT_ID: Agent identifier
+ * - AGENT_NAME: Agent name
+ * - AGENT_DESCRIPTION: Agent description
+ * - AGENT_VERSION: Agent version
+ * - AGENT_CAPABILITIES: Comma-separated list of capabilities
+ * - SW4RM_TIMEOUT_MS: Request timeout in milliseconds
+ * - SW4RM_STREAM_KEEPALIVE_MS: Stream keepalive in milliseconds
+ * - SW4RM_RETRY_MAX_ATTEMPTS: Maximum retry attempts
+ * - SW4RM_COMMUNICATION_CLASS: Communication class (0-3)
+ * - All endpoint environment variables (SW4RM_*_ADDR)
+ *
+ * @returns AgentConfig populated from environment
+ */
+export declare function loadConfigFromEnv(): AgentConfig;
+/**
+ * Create default SW4RMConfig with environment overrides.
+ *
+ * @returns SW4RMConfig with defaults and env overrides
+ */
+export declare function defaultSW4RMConfig(): SW4RMConfig;
+/**
+ * Load SW4RM configuration from file or environment.
+ *
+ * Configuration loading order (later sources override earlier ones):
+ * 1. Default values
+ * 2. Configuration file (if path provided)
+ * 3. Environment variables (SW4RM_* prefix)
+ *
+ * Supported file formats:
+ * - JSON (.json)
+ *
+ * @param configPath - Optional path to configuration file
+ * @returns SW4RMConfig instance
+ * @throws Error if file doesn't exist or is invalid JSON
+ *
+ * @example
+ * // Load from file and environment
+ * const config = loadConfig('/etc/sw4rm/config.json');
+ *
+ * @example
+ * // Load from environment only
+ * const config = loadConfig();
+ *
+ * Environment variables:
+ * - SW4RM_ROUTER_ADDR: Router service address
+ * - SW4RM_REGISTRY_ADDR: Registry service address
+ * - SW4RM_DEFAULT_TIMEOUT_MS: Default timeout in milliseconds
+ * - SW4RM_MAX_RETRIES: Maximum retry attempts
+ * - SW4RM_ENABLE_METRICS: Enable metrics collection (true/false)
+ * - SW4RM_ENABLE_TRACING: Enable tracing (true/false)
+ * - SW4RM_LOG_LEVEL: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+ */
+export declare function loadConfig(configPath?: string): SW4RMConfig;
+/**
+ * Get the global SW4RM configuration.
+ *
+ * Returns the singleton configuration instance. If no configuration has been
+ * loaded yet, creates a new one using environment variables.
+ *
+ * @returns Global SW4RMConfig instance
+ *
+ * @example
+ * const config = getConfig();
+ * console.log(`Router: ${config.routerAddr}`);
+ * console.log(`Metrics enabled: ${config.enableMetrics}`);
+ */
+export declare function getConfig(): SW4RMConfig;
+/**
+ * Set the global SW4RM configuration.
+ *
+ * This allows applications to programmatically configure the SDK
+ * instead of using files or environment variables.
+ *
+ * @param config - SW4RMConfig instance to set as global
+ *
+ * @example
+ * const config: SW4RMConfig = {
+ *   routerAddr: 'localhost:50051',
+ *   registryAddr: 'localhost:50052',
+ *   defaultTimeoutMs: 30000,
+ *   maxRetries: 3,
+ *   enableMetrics: false,
+ *   enableTracing: true,
+ *   logLevel: 'DEBUG',
+ *   featureFlags: {}
+ * };
+ * setConfig(config);
+ */
+export declare function setConfig(config: SW4RMConfig): void;
+/**
+ * Reset the global configuration (primarily for testing).
+ *
+ * Clears the singleton instance, forcing the next getConfig() call
+ * to reload from environment/defaults.
+ */
+export declare function resetConfig(): void;

package/dist/types/audit.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Represents a cryptographic or logical proof for an audit event.
+ */
+export interface AuditProof {
+    /** Unique identifier for this proof */
+    proof_id: string;
+    /** Type of proof (e.g., "simple_hash", "zk_proof", "signature") */
+    proof_type: string;
+    /** The actual proof data as bytes */
+    proof_data: Uint8Array;
+    /** Timestamp when the proof was created (HLC or unix ms) */
+    created_at: string;
+    /** Whether this proof has been verified */
+    verified: boolean;
+}
+/**
+ * Defines audit requirements for envelope processing.
+ */
+export interface AuditPolicy {
+    /** Unique identifier for this policy */
+    policy_id: string;
+    /** Whether proof is required for this policy */
+    require_proof: boolean;
+    /** Level of verification required (e.g., "none", "basic", "strict") */
+    verification_level: string;
+    /** How many days to retain audit records */
+    retention_days: number;
+}
+/**
+ * Represents a complete audit record for an envelope action.
+ */
+export interface AuditRecord {
+    /** Unique identifier for this audit record */
+    record_id: string;
+    /** The message_id of the envelope being audited */
+    envelope_id: string;
+    /** The action performed (e.g., "send", "receive", "process") */
+    action: string;
+    /** ID of the agent/component that performed the action */
+    actor_id: string;
+    /** When the action occurred (HLC or unix ms) */
+    timestamp: string;
+    /** Optional proof associated with this action */
+    proof?: AuditProof;
+}
+/**
+ * Envelope-like object for audit operations.
+ * This is a minimal interface that matches the expected envelope structure.
+ */
+export interface EnvelopeAuditable {
+    message_id?: string;
+    producer_id?: string;
+    payload?: Uint8Array;
+    audit_proof?: Uint8Array;
+    [key: string]: any;
+}
+/**
+ * Protocol defining the interface for audit implementations.
+ *
+ * Implementations can range from no-op (for development) to full
+ * ZK-proof based systems (for production).
+ */
+export interface Auditor {
+    /**
+     * Create a proof for an envelope action.
+     *
+     * @param envelope - The envelope to create proof for
+     * @param action - The action being performed (e.g., "send", "receive")
+     * @returns An AuditProof instance
+     */
+    createProof(envelope: EnvelopeAuditable, action: string): AuditProof;
+    /**
+     * Verify the validity of a proof.
+     *
+     * @param proof - The proof to verify
+     * @returns True if proof is valid, false otherwise
+     */
+    verifyProof(proof: AuditProof): boolean;
+    /**
+     * Record an audit event.
+     *
+     * @param envelope - The envelope being audited
+     * @param action - The action being performed
+     * @param proof - Optional proof to attach to the record
+     * @returns The created AuditRecord
+     */
+    record(envelope: EnvelopeAuditable, action: string, proof?: AuditProof): AuditRecord;
+    /**
+     * Query audit records for a specific envelope.
+     *
+     * @param envelope_id - The message_id of the envelope to query
+     * @returns List of AuditRecords for this envelope
+     */
+    query(envelope_id: string): AuditRecord[];
+}
+/**
+ * Compute SHA256 hash of an envelope.
+ *
+ * @param envelope - The envelope to hash
+ * @returns Hex-encoded SHA256 hash of the envelope
+ */
+export declare function computeEnvelopeHash(envelope: EnvelopeAuditable): string;
+/**
+ * Create a simple hash-based proof for an envelope.
+ *
+ * This is a basic proof mechanism suitable for testing and development.
+ * Production systems should use more sophisticated proof mechanisms
+ * (e.g., ZK-proofs, digital signatures).
+ *
+ * @param envelope - The envelope to create proof for
+ * @param actor_id - ID of the actor creating the proof
+ * @returns An AuditProof with simple hash-based proof
+ */
+export declare function createSimpleProof(envelope: EnvelopeAuditable, actor_id: string): AuditProof;
+/**
+ * Verify an audit proof against an envelope.
+ *
+ * @param envelope - The envelope to verify against
+ * @param proof - The proof to verify
+ * @returns True if proof is valid, false otherwise
+ */
+export declare function verifyAuditProof(envelope: EnvelopeAuditable, proof: AuditProof): boolean;
+/**
+ * No-op auditor that does nothing.
+ *
+ * Useful for development and when audit trail is not required.
+ */
+export declare class NoOpAuditor implements Auditor {
+    /**
+     * Create a minimal no-op proof.
+     *
+     * @param envelope - The envelope (ignored)
+     * @param action - The action (ignored)
+     * @returns A minimal no-op proof
+     */
+    createProof(envelope: EnvelopeAuditable, action: string): AuditProof;
+    /**
+     * Always returns true for no-op proofs.
+     *
+     * @param proof - The proof (ignored)
+     * @returns Always true
+     */
+    verifyProof(proof: AuditProof): boolean;
+    /**
+     * Create a minimal audit record without storing it.
+     *
+     * @param envelope - The envelope being audited
+     * @param action - The action being performed
+     * @param proof - Optional proof to attach
+     * @returns A minimal audit record
+     */
+    record(envelope: EnvelopeAuditable, action: string, proof?: AuditProof): AuditRecord;
+    /**
+     * Always returns empty array.
+     *
+     * @param envelope_id - The envelope ID (ignored)
+     * @returns Empty array
+     */
+    query(envelope_id: string): AuditRecord[];
+}
+/**
+ * In-memory auditor for testing and development.
+ *
+ * Stores audit records in memory and supports basic querying.
+ * Not suitable for production use.
+ */
+export declare class InMemoryAuditor implements Auditor {
+    private _records;
+    /**
+     * Initialize with empty record storage.
+     */
+    constructor();
+    /**
+     * Create a simple hash-based proof.
+     *
+     * @param envelope - The envelope to create proof for
+     * @param action - The action being performed
+     * @returns A simple hash-based proof
+     */
+    createProof(envelope: EnvelopeAuditable, action: string): AuditProof;
+    /**
+     * Verify a proof using the verification module.
+     *
+     * @param proof - The proof to verify
+     * @returns True if proof is valid, false otherwise
+     */
+    verifyProof(proof: AuditProof): boolean;
+    /**
+     * Create and store an audit record.
+     *
+     * @param envelope - The envelope being audited
+     * @param action - The action being performed
+     * @param proof - Optional proof to attach
+     * @returns The created audit record
+     */
+    record(envelope: EnvelopeAuditable, action: string, proof?: AuditProof): AuditRecord;
+    /**
+     * Query all audit records for a specific envelope.
+     *
+     * @param envelope_id - The message_id of the envelope to query
+     * @returns List of audit records for this envelope
+     */
+    query(envelope_id: string): AuditRecord[];
+    /**
+     * Get all audit records (useful for testing).
+     *
+     * @returns All audit records across all envelopes
+     */
+    getAllRecords(): AuditRecord[];
+    /**
+     * Clear all stored records (useful for testing).
+     */
+    clear(): void;
+}

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/clients/negotiationRoom.d.ts

@@ -10,7 +10,37 @@
  * - Coordinating the review process
  *
  * Based on SPEC_REQUESTS.md section 6.1.
+ *
+ * ## Concurrency Fix (v0.5.0)
+ *
+ * The client now uses a pluggable storage backend (NegotiationRoomStore) instead
+ * of instance-local storage. This enables multiple client instances to share
+ * state, which is essential for multi-agent deployments where producer, critic,
+ * and coordinator agents run in different processes or workers.
+ *
+ * ### Usage patterns
+ *
+ * 1. Single-process with shared default store (recommended):
+ * ```typescript
+ * const client1 = new NegotiationRoomClient();  // Uses shared default store
+ * const client2 = new NegotiationRoomClient();  // Same store, shared state
+ * ```
+ *
+ * 2. Explicit store sharing:
+ * ```typescript
+ * const store = new InMemoryNegotiationRoomStore();
+ * const producer = new NegotiationRoomClient({ store });
+ * const critic = new NegotiationRoomClient({ store });
+ * ```
+ *
+ * 3. File-based persistence (multi-process, requires colony):
+ * ```typescript
+ * import { JsonFileNegotiationRoomStore } from 'colony/stores/typescript/jsonFileStore';
+ * const store = new JsonFileNegotiationRoomStore("/path/to/storage");
+ * const client = new NegotiationRoomClient({ store });
+ * ```
  */
+import { NegotiationRoomStore } from './negotiationRoomStore.js';
 /**
  * Type of artifact being negotiated.
  *
@@ -146,6 +176,16 @@ export declare class NegotiationTimeoutError extends Error {
 export declare class NegotiationValidationError extends Error {
     constructor(message: string);
 }
+/**
+ * Configuration options for NegotiationRoomClient.
+ */
+export interface NegotiationRoomClientOptions {
+    /**
+     * Storage backend for proposals, votes, and decisions.
+     * If not provided, uses the shared default in-memory store.
+     */
+    store?: NegotiationRoomStore;
+}
 /**
  * Client for interacting with negotiation rooms.
  *
@@ -153,13 +193,49 @@ export declare class NegotiationValidationError extends Error {
  * review process. Producers submit proposals, critics submit votes,
  * and coordinators retrieve votes to make decisions.
  *
- * This is an in-memory implementation for Phase 2. Future phases
- * will integrate with persistent storage and gRPC services.
+ * This client uses a pluggable storage backend, enabling state sharing
+ * across multiple client instances. By default, all clients within the
+ * same process share a common in-memory store.
+ *
+ * @example
+ * ```typescript
+ * // Simple usage - all clients share default store
+ * const client = new NegotiationRoomClient();
+ *
+ * const proposal: NegotiationProposal = {
+ *   artifactType: ArtifactType.CODE,
+ *   artifactId: "code-123",
+ *   producerId: "agent-producer",
+ *   artifact: new TextEncoder().encode("def hello(): pass"),
+ *   artifactContentType: "text/x-python",
+ *   requestedCritics: ["critic-1", "critic-2"],
+ *   negotiationRoomId: "room-1"
+ * };
+ * const artifactId = await client.submitProposal(proposal);
+ * console.log(artifactId); // "code-123"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Explicit store sharing
+ * import { InMemoryNegotiationRoomStore } from './negotiationRoomStore';
+ *
+ * const store = new InMemoryNegotiationRoomStore();
+ * const producer = new NegotiationRoomClient({ store });
+ * const critic = new NegotiationRoomClient({ store });
+ *
+ * // Producer and critic now share state
+ * ```
  */
 export declare class NegotiationRoomClient {
-    private proposals;
-    private votes;
-    private decisions;
+    private readonly store;
+    /**
+     * Create a new negotiation room client.
+     *
+     * @param options - Configuration options. If no store is provided,
+     *                  uses the shared default in-memory store.
+     */
+    constructor(options?: NegotiationRoomClientOptions);
     /**
      * Submit an artifact proposal for multi-agent review.
      *