@noosphere/agent-core 0.1.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,600 @@
+import { EventEmitter } from 'events';
+import { Provider, Contract } from 'ethers';
+import { WalletManager } from '@noosphere/crypto';
+export { KeystoreInfo, KeystoreManager, NoosphereKeystore, PaymentWalletInfo, WalletManager } from '@noosphere/crypto';
+export { RegistryConfig, ContainerMetadata as RegistryContainerMetadata, RegistryManager, VerifierMetadata as RegistryVerifierMetadata } from '@noosphere/registry';
+
+interface Commitment {
+    requestId: string;
+    subscriptionId: bigint;
+    containerId: string;
+    interval: number;
+    redundancy: number;
+    useDeliveryInbox: boolean;
+    feeToken: string;
+    feeAmount: bigint;
+    walletAddress: string;
+    verifier: string;
+    coordinator: string;
+}
+interface Payment {
+    recipient: string;
+    feeToken: string;
+    feeAmount: bigint;
+}
+interface ProofVerificationRequest {
+    subscriptionId: bigint;
+    interval: number;
+    submitterAddress: string;
+    escrowedAmount: bigint;
+}
+interface RequestStartedEvent {
+    requestId: string;
+    subscriptionId: bigint;
+    containerId: string;
+    interval: number;
+    redundancy: number;
+    useDeliveryInbox: boolean;
+    feeAmount: bigint;
+    feeToken: string;
+    verifier: string;
+    coordinator: string;
+    walletAddress: string;
+    blockNumber: number;
+}
+interface ComputeSubscription {
+    owner: string;
+    wallet: string;
+    containerId: string;
+    intervalSeconds: number;
+    maxExecutions: number;
+    redundancy: number;
+    feeToken: string;
+    feeAmount: bigint;
+    verifier: string;
+    routeId: string;
+    activeAt: number;
+    useDeliveryInbox: boolean;
+}
+interface AgentConfig {
+    rpcUrl: string;
+    wsRpcUrl?: string;
+    privateKey?: string;
+    routerAddress: string;
+    coordinatorAddress: string;
+    deploymentBlock?: number;
+    pollingInterval?: number;
+}
+interface NoosphereAgentConfig {
+    forwardStats?: boolean;
+    manageContainers?: boolean;
+    startupWait?: number;
+    agent?: {
+        name: string;
+        apiKey?: string;
+        email?: string;
+    };
+    server?: {
+        port: number;
+        rateLimit?: {
+            numRequests: number;
+            period: number;
+        };
+    };
+    hub?: {
+        register: boolean;
+        url: string;
+        keepAlive?: {
+            enabled: boolean;
+            intervalMs: number;
+            batchSize?: number;
+        };
+    };
+    chain: {
+        enabled: boolean;
+        rpcUrl: string;
+        wsRpcUrl?: string;
+        trailHeadBlocks?: number;
+        routerAddress: string;
+        coordinatorAddress?: string;
+        deploymentBlock?: number;
+        processingInterval?: number;
+        wallet: {
+            maxGasLimit?: number;
+            paymentAddress?: string;
+            allowedSimErrors?: string[];
+            keystore?: {
+                path: string;
+                password: string;
+                keys?: {
+                    eth?: string;
+                };
+            };
+        };
+        snapshotSync?: {
+            sleep?: number;
+            batchSize?: number;
+            startingSubId?: number;
+            syncPeriod?: number;
+        };
+        connection?: {
+            timeout?: number;
+            readTimeout?: number;
+            writeTimeout?: number;
+        };
+        gasConfig?: {
+            priceMultiplier?: number;
+            limitMultiplier?: number;
+        };
+    };
+    docker?: {
+        username?: string;
+        password?: string;
+    };
+    containers: ContainerConfig[];
+}
+interface ContainerConfig {
+    id: string;
+    image: string;
+    port?: string;
+    env?: Record<string, string>;
+    volumes?: string[];
+    verifierAddress?: string;
+    acceptedPayments?: Record<string, number>;
+}
+interface ContainerMetadata {
+    id: string;
+    name: string;
+    image: string;
+    tag?: string;
+    port?: string;
+    env?: Record<string, string>;
+    requirements?: {
+        memory?: string;
+        cpu?: number;
+        gpu?: boolean;
+    };
+    payments?: {
+        basePrice: string;
+        unit: string;
+        per: string;
+    };
+    verified?: boolean;
+}
+interface VerifierMetadata {
+    address: string;
+    name: string;
+    image: string;
+    tag?: string;
+}
+declare enum FulfillResult {
+    FULFILLED = 0,
+    INVALID_REQUEST_ID = 1,
+    INVALID_COMMITMENT = 2,
+    SUBSCRIPTION_BALANCE_INVARIANT_VIOLATION = 3,
+    INSUFFICIENT_SUBSCRIPTION_BALANCE = 4,
+    COST_EXCEEDS_COMMITMENT = 5
+}
+/**
+ * Event emitted when scheduler successfully prepares next interval
+ */
+interface CommitmentSuccessEvent {
+    subscriptionId: bigint;
+    interval: bigint;
+    txHash: string;
+    blockNumber: number;
+    gasUsed: string;
+    gasPrice: string;
+    gasCost: string;
+    requestStartedEvent?: RequestStartedEvent;
+}
+
+interface CheckpointData$1 {
+    blockNumber: number;
+    blockHash?: string;
+    blockTimestamp?: number;
+}
+interface EventMonitorOptions {
+    loadCheckpoint?: () => CheckpointData$1 | undefined;
+    saveCheckpoint?: (checkpoint: CheckpointData$1) => void;
+}
+declare class EventMonitor extends EventEmitter {
+    private config;
+    private routerAbi;
+    private coordinatorAbi;
+    private provider;
+    private router;
+    private coordinator;
+    private lastProcessedBlock;
+    private useWebSocket;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private isReconnecting;
+    private heartbeatInterval;
+    private lastEventTime;
+    private checkpointCallbacks?;
+    constructor(config: AgentConfig, routerAbi: any[], coordinatorAbi: any[], options?: EventMonitorOptions);
+    connect(): Promise<void>;
+    start(): Promise<void>;
+    private replayEvents;
+    private startWebSocketListening;
+    private startHeartbeat;
+    private replayMissedEvents;
+    private handleDisconnect;
+    private startPolling;
+    private processEvent;
+    private reconnect;
+    private saveCheckpoint;
+    stop(): Promise<void>;
+}
+
+interface ContainerExecutionResult {
+    output: string;
+    exitCode: number;
+    executionTime: number;
+}
+declare class ContainerManager {
+    private docker;
+    private runningContainers;
+    private persistentContainers;
+    private containerPorts;
+    constructor();
+    runContainer(container: ContainerMetadata, input: string, timeout?: number): Promise<ContainerExecutionResult>;
+    private collectContainerResult;
+    private pullImage;
+    private waitForContainer;
+    private timeout;
+    private parseMemory;
+    checkDockerAvailable(): Promise<boolean>;
+    getDockerInfo(): Promise<any>;
+    /**
+     * Cleanup all running containers
+     * Called when agent is shutting down
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Get number of running containers
+     */
+    getRunningContainerCount(): number;
+    /**
+     * Pre-pull container images and start persistent containers on startup
+     * This speeds up request handling by having containers ready
+     */
+    prepareContainers(containers: Map<string, ContainerMetadata>): Promise<void>;
+    /**
+     * Start a persistent container that stays running
+     */
+    private startPersistentContainer;
+    /**
+     * Stop and remove all persistent containers
+     */
+    stopPersistentContainers(): Promise<void>;
+}
+
+/**
+ * SchedulerService
+ *
+ * Manages periodic commitment generation for active subscriptions.
+ * Equivalent to Java's CommitmentGenerationService with cron scheduling.
+ */
+
+interface SubscriptionState {
+    subscriptionId: bigint;
+    routeId: string;
+    containerId: string;
+    client: string;
+    wallet: string;
+    activeAt: bigint;
+    intervalSeconds: bigint;
+    maxExecutions: bigint;
+    redundancy: number;
+    verifier?: string;
+    currentInterval: bigint;
+    lastProcessedAt: number;
+    pendingTx?: string;
+    txAttempts: number;
+}
+interface SchedulerConfig {
+    cronIntervalMs: number;
+    maxRetryAttempts: number;
+    syncPeriodMs: number;
+    loadCommittedIntervals?: () => string[];
+    saveCommittedInterval?: (key: string) => void;
+}
+declare class SchedulerService extends EventEmitter {
+    private provider;
+    private router;
+    private coordinator;
+    private agentWallet;
+    private subscriptions;
+    private committedIntervals;
+    private pendingTxs;
+    private intervalTimer?;
+    private syncTimer?;
+    private config;
+    private batchReader?;
+    private lastSyncedId;
+    private maxSubscriptionId?;
+    private getContainer?;
+    constructor(provider: Provider, router: Contract, coordinator: Contract, agentWallet: string, batchReaderAddress?: string, config?: Partial<SchedulerConfig>, getContainer?: (containerId: string) => any);
+    /**
+     * Start the scheduler service
+     */
+    start(): void;
+    /**
+     * Stop the scheduler service
+     */
+    stop(): void;
+    /**
+     * Track a new subscription
+     */
+    trackSubscription(subscription: Omit<SubscriptionState, 'currentInterval' | 'lastProcessedAt' | 'txAttempts'>): void;
+    /**
+     * Remove a subscription from tracking
+     */
+    untrackSubscription(subscriptionId: bigint): void;
+    /**
+     * Mark an interval as committed (for RequestStarted events)
+     * Also persists to storage if callback is configured
+     */
+    markIntervalCommitted(subscriptionId: bigint, interval: bigint): void;
+    /**
+     * Add to committed intervals set and persist to storage
+     */
+    private addCommittedInterval;
+    /**
+     * Main commitment generation loop (runs every cronIntervalMs)
+     * Equivalent to Java's CommitmentGenerationService.generateCommitment()
+     */
+    private generateCommitments;
+    /**
+     * Process all active subscriptions
+     */
+    private processActiveSubscriptions;
+    /**
+     * Check if subscription should be processed
+     */
+    private shouldProcess;
+    /**
+     * Check if interval already has commitments on-chain
+     */
+    private hasRequestCommitments;
+    /**
+     * Prepare next interval by calling coordinator contract
+     * Equivalent to Java's CoordinatorService.prepareNextInterval()
+     */
+    private prepareNextInterval;
+    /**
+     * Prune transactions that have failed
+     */
+    private pruneFailedTxs;
+    /**
+     * Sync subscriptions (placeholder for blockchain event listening)
+     */
+    /**
+     * Sync subscriptions from blockchain
+     * Reads subscriptions in batches and tracks active ones
+     */
+    private syncSubscriptions;
+    /**
+     * Check if subscription is currently active
+     */
+    private isSubscriptionActive;
+    /**
+     * Track subscription from ComputeSubscription config
+     * Returns true if subscription was tracked, false if skipped
+     */
+    private trackSubscriptionFromConfig;
+    /**
+     * Get request ID (hash of subscription ID and interval)
+     */
+    private getRequestId;
+    /**
+     * Get scheduler statistics
+     */
+    getStats(): {
+        totalSubscriptions: number;
+        activeSubscriptions: number;
+        committedIntervals: number;
+        pendingTransactions: number;
+    };
+    /**
+     * Get all tracked subscriptions
+     */
+    getSubscriptions(): SubscriptionState[];
+    /**
+     * Parse RequestStarted event from transaction receipt
+     * This allows the agent to process the event immediately without waiting for WebSocket
+     */
+    private parseRequestStartedFromReceipt;
+}
+
+interface ComputeDeliveredEvent {
+    requestId: string;
+    subscriptionId: number;
+    interval: number;
+    containerId: string;
+    redundancy: number;
+    feeAmount: string;
+    feeToken: string;
+    input: string;
+    output: string;
+    txHash: string;
+    blockNumber: number;
+    gasUsed: bigint;
+    gasPrice: bigint;
+}
+interface RequestStartedCallbackEvent {
+    requestId: string;
+    subscriptionId: number;
+    interval: number;
+    containerId: string;
+    redundancy: number;
+    feeAmount: string;
+    feeToken: string;
+    verifier: string;
+    walletAddress: string;
+    blockNumber: number;
+}
+/**
+ * Event data for commitment success (scheduler prepareNextInterval)
+ */
+interface CommitmentSuccessCallbackEvent {
+    subscriptionId: bigint;
+    interval: bigint;
+    txHash: string;
+    blockNumber: number;
+    gasUsed: string;
+    gasPrice: string;
+    gasCost: string;
+}
+interface CheckpointData {
+    blockNumber: number;
+    blockHash?: string;
+    blockTimestamp?: number;
+}
+interface NoosphereAgentOptions {
+    config: AgentConfig;
+    routerAbi?: any[];
+    coordinatorAbi?: any[];
+    getContainer?: (containerId: string) => ContainerMetadata | undefined;
+    containers?: Map<string, ContainerMetadata>;
+    walletManager?: WalletManager;
+    paymentWallet?: string;
+    schedulerConfig?: Partial<SchedulerConfig>;
+    onRequestStarted?: (event: RequestStartedCallbackEvent) => void;
+    onRequestProcessing?: (requestId: string) => void;
+    onRequestSkipped?: (requestId: string, reason: string) => void;
+    onRequestFailed?: (requestId: string, error: string) => void;
+    onComputeDelivered?: (event: ComputeDeliveredEvent) => void;
+    onCommitmentSuccess?: (event: CommitmentSuccessCallbackEvent) => void;
+    isRequestProcessed?: (requestId: string) => boolean;
+    loadCheckpoint?: () => CheckpointData | undefined;
+    saveCheckpoint?: (checkpoint: CheckpointData) => void;
+}
+declare class NoosphereAgent {
+    private options;
+    private eventMonitor;
+    private containerManager;
+    private scheduler;
+    private walletManager;
+    private registryManager;
+    private router;
+    private coordinator;
+    private provider;
+    private config;
+    private getContainer?;
+    private containers?;
+    private paymentWallet?;
+    private isRunning;
+    private processingRequests;
+    constructor(options: NoosphereAgentOptions);
+    /**
+     * Initialize NoosphereAgent from config.json (RECOMMENDED)
+     * This loads all configuration including containers from a config file
+     *
+     * @param configPath - Path to config.json file
+     * @param routerAbi - Router contract ABI (optional - defaults to ABIs.Router)
+     * @param coordinatorAbi - Coordinator contract ABI (optional - defaults to ABIs.Coordinator)
+     * @returns Initialized NoosphereAgent
+     */
+    static fromConfig(configPath: string, routerAbi?: any[], coordinatorAbi?: any[]): Promise<NoosphereAgent>;
+    /**
+     * Initialize NoosphereAgent from keystore (RECOMMENDED)
+     * This is the secure way to initialize an agent in production
+     *
+     * @param keystorePath - Path to keystore file
+     * @param password - Keystore password
+     * @param options - Agent configuration options
+     * @returns Initialized NoosphereAgent
+     */
+    static fromKeystore(keystorePath: string, password: string, options: Omit<NoosphereAgentOptions, 'walletManager'>): Promise<NoosphereAgent>;
+    start(): Promise<void>;
+    /**
+     * Convert registry ContainerMetadata to agent-core ContainerMetadata
+     */
+    private convertRegistryContainer;
+    private handleRequest;
+    /**
+     * Self-coordination: Calculate priority and wait
+     */
+    private waitForPriority;
+    /**
+     * Calculate deterministic priority for this agent and request
+     */
+    private calculatePriority;
+    stop(): Promise<void>;
+    getStatus(): {
+        running: boolean;
+        address: string;
+        scheduler: {
+            totalSubscriptions: number;
+            activeSubscriptions: number;
+            committedIntervals: number;
+            pendingTransactions: number;
+        };
+        containers: {
+            runningCount: number;
+        };
+    };
+    /**
+     * Get scheduler service (for advanced usage)
+     */
+    getScheduler(): SchedulerService;
+}
+
+declare class CommitmentUtils {
+    /**
+     * Calculate commitment hash
+     * Matches the keccak256(abi.encode(commitment)) in Solidity
+     */
+    static hash(commitment: Commitment): string;
+    /**
+     * Verify commitment hash matches expected value
+     */
+    static verify(commitment: Commitment, expectedHash: string): boolean;
+    /**
+     * Encode commitment data for reportComputeResult
+     * Returns ABI-encoded commitment struct
+     */
+    static encode(commitment: Commitment): string;
+    /**
+     * Create Commitment from RequestStartedEvent
+     */
+    static fromEvent(event: any, walletAddress: string): Commitment;
+}
+
+declare class RequestIdUtils {
+    /**
+     * Pack subscriptionId and interval into requestId
+     * Matches Solidity: keccak256(abi.encodePacked(subscriptionId, interval))
+     */
+    static pack(subscriptionId: bigint, interval: number): string;
+    /**
+     * Unpack requestId into subscriptionId and interval (if stored separately)
+     * Note: This is not possible from the hash alone - only for informational purposes
+     * In practice, subscriptionId and interval are stored in events
+     */
+    static format(requestId: string, subscriptionId: bigint, interval: number): string;
+}
+
+declare class ConfigLoader {
+    /**
+     * Load agent configuration from JSON file
+     */
+    static loadFromFile(configPath: string): NoosphereAgentConfig;
+    /**
+     * Convert ContainerConfig to ContainerMetadata format
+     */
+    static containerConfigToMetadata(containerConfig: NoosphereAgentConfig['containers'][0]): ContainerMetadata;
+    /**
+     * Get all containers from config as ContainerMetadata array
+     */
+    static getContainersFromConfig(config: NoosphereAgentConfig): Map<string, ContainerMetadata>;
+    /**
+     * Get container config by ID
+     */
+    static getContainerConfig(config: NoosphereAgentConfig, containerId: string): NoosphereAgentConfig['containers'][0] | undefined;
+}
+
+export { type AgentConfig, type CheckpointData$1 as CheckpointData, type Commitment, type CommitmentSuccessCallbackEvent, type CommitmentSuccessEvent, CommitmentUtils, type ComputeDeliveredEvent, type ComputeSubscription, ConfigLoader, type ContainerConfig, ContainerManager, type ContainerMetadata, EventMonitor, FulfillResult, NoosphereAgent, type NoosphereAgentConfig, type Payment, type ProofVerificationRequest, RequestIdUtils, type RequestStartedCallbackEvent, type RequestStartedEvent, SchedulerService, type VerifierMetadata };