@sw4rm/js-sdk 0.3.0 → 0.5.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

@@ -0,0 +1,188 @@
+/**
+ * Handoff client for SW4RM.
+ *
+ * This module provides the HandoffClient for managing agent-to-agent task
+ * handoffs. The handoff pattern enables:
+ * - Graceful transfer of work between agents
+ * - Context preservation during handoff
+ * - Capability-based routing to appropriate agents
+ *
+ * Based on handoff.proto definitions.
+ */
+/**
+ * Status of a handoff request.
+ */
+export declare enum HandoffStatus {
+    HANDOFF_STATUS_UNSPECIFIED = 0,
+    PENDING = 1,
+    ACCEPTED = 2,
+    REJECTED = 3,
+    COMPLETED = 4,
+    EXPIRED = 5
+}
+/**
+ * A request to hand off work from one agent to another.
+ *
+ * Contains the context needed for the receiving agent to continue
+ * the work, including capability requirements and priority information.
+ */
+export interface HandoffRequest {
+    /** Unique identifier for this handoff request */
+    requestId: string;
+    /** Agent ID of the agent initiating the handoff */
+    fromAgent: string;
+    /** Agent ID of the target agent (or empty for capability-based routing) */
+    toAgent: string;
+    /** Human-readable reason for the handoff */
+    reason: string;
+    /** Serialized context snapshot for the receiving agent */
+    contextSnapshot: Uint8Array;
+    /** List of capabilities required by the receiving agent */
+    capabilitiesRequired: string[];
+    /** Priority level of the handoff (lower is higher priority) */
+    priority: number;
+    /** Timeout in milliseconds for the handoff to be accepted */
+    timeoutMs?: number;
+    /** Timestamp when the request was created (ISO-8601 string) */
+    createdAt?: string;
+}
+/**
+ * Response to a handoff request.
+ *
+ * Indicates whether the handoff was accepted and by whom, or provides
+ * a rejection reason.
+ */
+export interface HandoffResponse {
+    /** Identifier of the handoff request being responded to */
+    requestId: string;
+    /** Whether the handoff was accepted */
+    accepted: boolean;
+    /** Agent ID of the agent that accepted the handoff (if accepted) */
+    acceptingAgent?: string;
+    /** Reason for rejection (if not accepted) */
+    rejectionReason?: string;
+}
+/**
+ * Error thrown when a handoff operation fails validation.
+ */
+export declare class HandoffValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when a handoff operation times out.
+ */
+export declare class HandoffTimeoutError extends Error {
+    constructor(message: string);
+}
+/**
+ * Client for managing agent-to-agent handoffs.
+ *
+ * Enables agents to transfer work to other agents while preserving
+ * context and ensuring proper capability matching. This is an in-memory
+ * implementation for Phase 2; future phases will integrate with gRPC services.
+ */
+export declare class HandoffClient {
+    private requests;
+    private responses;
+    private pendingByAgent;
+    /**
+     * Request a handoff to another agent.
+     *
+     * Initiates a handoff request that the target agent can accept or reject.
+     * The request is stored and made available to the target agent via
+     * getPendingHandoffs().
+     *
+     * @param request - The handoff request containing context and requirements
+     * @returns The response once the handoff is accepted, rejected, or times out
+     * @throws HandoffValidationError if a request with the same ID already exists
+     *
+     * @example
+     * ```typescript
+     * const client = new HandoffClient();
+     * const request: HandoffRequest = {
+     *   requestId: "handoff-123",
+     *   fromAgent: "agent-a",
+     *   toAgent: "agent-b",
+     *   reason: "Capability mismatch",
+     *   contextSnapshot: new TextEncoder().encode('{"state": "in_progress"}'),
+     *   capabilitiesRequired: ["code_review"],
+     *   priority: 5
+     * };
+     * const response = await client.requestHandoff(request);
+     * ```
+     */
+    requestHandoff(request: HandoffRequest): Promise<HandoffResponse>;
+    /**
+     * Accept a pending handoff request.
+     *
+     * Called by the target agent to accept a handoff. After acceptance,
+     * the agent should process the context snapshot and continue the work.
+     *
+     * @param handoffId - The ID of the handoff request to accept
+     * @throws HandoffValidationError if no request exists with the given ID
+     * @throws HandoffValidationError if the request has already been responded to
+     *
+     * @example
+     * ```typescript
+     * // Get pending handoffs for this agent
+     * const pending = await client.getPendingHandoffs("agent-b");
+     * if (pending.length > 0) {
+     *   await client.acceptHandoff(pending[0].requestId);
+     * }
+     * ```
+     */
+    acceptHandoff(handoffId: string): Promise<void>;
+    /**
+     * Reject a pending handoff request.
+     *
+     * Called by the target agent to reject a handoff. A reason should be
+     * provided to help the originating agent determine next steps.
+     *
+     * @param handoffId - The ID of the handoff request to reject
+     * @param reason - Human-readable reason for the rejection
+     * @throws HandoffValidationError if no request exists with the given ID
+     * @throws HandoffValidationError if the request has already been responded to
+     *
+     * @example
+     * ```typescript
+     * await client.rejectHandoff("handoff-123", "Agent at capacity");
+     * ```
+     */
+    rejectHandoff(handoffId: string, reason: string): Promise<void>;
+    /**
+     * Get all pending handoff requests for an agent.
+     *
+     * Returns handoff requests that have been addressed to the specified
+     * agent and have not yet been accepted or rejected.
+     *
+     * @param agentId - The ID of the agent to get pending handoffs for
+     * @returns List of pending handoff requests for the agent
+     *
+     * @example
+     * ```typescript
+     * const pending = await client.getPendingHandoffs("agent-b");
+     * console.log(`${pending.length} pending handoffs`);
+     * for (const request of pending) {
+     *   console.log(`From ${request.fromAgent}: ${request.reason}`);
+     * }
+     * ```
+     */
+    getPendingHandoffs(agentId: string): Promise<HandoffRequest[]>;
+    /**
+     * Get the response for a handoff request.
+     *
+     * Returns the response if the handoff has been accepted, rejected, or
+     * timed out. Returns null if the handoff is still pending.
+     *
+     * @param handoffId - The ID of the handoff request
+     * @returns The handoff response if available, null otherwise
+     */
+    getHandoffResponse(handoffId: string): Promise<HandoffResponse | null>;
+    /**
+     * Get the original handoff request.
+     *
+     * @param handoffId - The ID of the handoff request
+     * @returns The handoff request if it exists, null otherwise
+     */
+    getHandoffRequest(handoffId: string): Promise<HandoffRequest | null>;
+}