@noosphere/agent-core 0.1.0-alpha.9 → 0.2.0-alpha.1

package/dist/index.d.ts

@@ -2,7 +2,10 @@ import { EventEmitter } from 'events';
 import { Provider, Contract } from 'ethers';
 import { WalletManager } from '@noosphere/crypto';
 export { KeystoreInfo, KeystoreManager, NoosphereKeystore, PaymentWalletInfo, WalletManager } from '@noosphere/crypto';
+import { RegistryManager } from '@noosphere/registry';
 export { RegistryConfig, ContainerMetadata as RegistryContainerMetadata, RegistryManager, VerifierMetadata as RegistryVerifierMetadata } from '@noosphere/registry';
+import { PayloadData } from '@noosphere/contracts';
+export { InputType, PayloadData } from '@noosphere/contracts';
 
 interface Commitment {
     requestId: string;
@@ -239,7 +242,10 @@ declare class ContainerManager {
     private persistentContainers;
     private containerPorts;
     constructor();
-    runContainer(container: ContainerMetadata, input: string, timeout?: number): Promise<ContainerExecutionResult>;
+    runContainer(container: ContainerMetadata, input: string, timeout?: number, // 3 minutes default
+    connectionRetries?: number, // Retry up to 5 times for connection issues
+    connectionRetryDelayMs?: number): Promise<ContainerExecutionResult>;
+    private sleep;
     private collectContainerResult;
     private pullImage;
     private waitForContainer;
@@ -417,8 +423,8 @@ interface ComputeDeliveredEvent {
     redundancy: number;
     feeAmount: string;
     feeToken: string;
-    input: string;
-    output: string;
+    input: string | PayloadData;
+    output: string | PayloadData;
     txHash: string;
     blockNumber: number;
     gasUsed: bigint;
@@ -453,15 +459,29 @@ interface CheckpointData {
     blockHash?: string;
     blockTimestamp?: number;
 }
+interface RetryableEvent {
+    requestId: string;
+    subscriptionId: number;
+    interval: number;
+    containerId: string;
+    retryCount: number;
+}
+interface ContainerExecutionConfig {
+    timeout?: number;
+    connectionRetries?: number;
+    connectionRetryDelayMs?: number;
+}
 interface NoosphereAgentOptions {
     config: AgentConfig;
     routerAbi?: any[];
     coordinatorAbi?: any[];
     getContainer?: (containerId: string) => ContainerMetadata | undefined;
     containers?: Map<string, ContainerMetadata>;
+    registryManager?: RegistryManager;
     walletManager?: WalletManager;
     paymentWallet?: string;
     schedulerConfig?: Partial<SchedulerConfig>;
+    containerConfig?: ContainerExecutionConfig;
     onRequestStarted?: (event: RequestStartedCallbackEvent) => void;
     onRequestProcessing?: (requestId: string) => void;
     onRequestSkipped?: (requestId: string, reason: string) => void;
@@ -471,6 +491,12 @@ interface NoosphereAgentOptions {
     isRequestProcessed?: (requestId: string) => boolean;
     loadCheckpoint?: () => CheckpointData | undefined;
     saveCheckpoint?: (checkpoint: CheckpointData) => void;
+    maxRetries?: number;
+    retryIntervalMs?: number;
+    getRetryableEvents?: (maxRetries: number) => RetryableEvent[];
+    resetEventForRetry?: (requestId: string) => void;
+    healthCheckIntervalMs?: number;
+    payloadEncoder?: (content: string) => Promise<PayloadData>;
 }
 declare class NoosphereAgent {
     private options;
@@ -488,6 +514,15 @@ declare class NoosphereAgent {
     private paymentWallet?;
     private isRunning;
     private processingRequests;
+    private retryTimer?;
+    private healthCheckTimer?;
+    private maxRetries;
+    private retryIntervalMs;
+    private healthCheckIntervalMs;
+    private containerTimeout;
+    private containerConnectionRetries;
+    private containerConnectionRetryDelayMs;
+    private payloadEncoder?;
     constructor(options: NoosphereAgentOptions);
     /**
      * Initialize NoosphereAgent from config.json (RECOMMENDED)
@@ -510,10 +545,34 @@ declare class NoosphereAgent {
      */
     static fromKeystore(keystorePath: string, password: string, options: Omit<NoosphereAgentOptions, 'walletManager'>): Promise<NoosphereAgent>;
     start(): Promise<void>;
+    /**
+     * Start the retry timer for failed requests
+     */
+    private startRetryTimer;
+    /**
+     * Start the health check timer for registry validation
+     */
+    private startHealthCheck;
+    /**
+     * Perform health check - verify registry has containers and reload if necessary
+     */
+    private performHealthCheck;
+    /**
+     * Process retryable failed events (with throttling to avoid rate limits)
+     */
+    private processRetries;
     /**
      * Convert registry ContainerMetadata to agent-core ContainerMetadata
      */
     private convertRegistryContainer;
+    /**
+     * Get container metadata from available sources
+     * Returns undefined if container is not supported by this agent
+     *
+     * NOTE: Only checks config-defined sources (callback and containers map).
+     * Registry is NOT used here - we only process containers explicitly configured.
+     */
+    private getContainerMetadata;
     private handleRequest;
     /**
      * Self-coordination: Calculate priority and wait
@@ -543,6 +602,51 @@ declare class NoosphereAgent {
     getScheduler(): SchedulerService;
 }
 
+/**
+ * Utility class for PayloadData creation and encoding
+ */
+declare class PayloadUtils {
+    /**
+     * Create PayloadData from content with data: URI scheme (inline)
+     * Best for small payloads (<1KB)
+     * @param content - The content to embed
+     * @returns PayloadData with contentHash and data: URI
+     */
+    static fromInlineData(content: string): PayloadData;
+    /**
+     * Create PayloadData from content with external URI
+     * Best for large payloads that are stored externally
+     * @param content - The original content (for hash computation)
+     * @param uri - The external URI (ipfs://, https://, ar://, etc.)
+     * @returns PayloadData with contentHash and URI
+     */
+    static fromExternalUri(content: string, uri: string): PayloadData;
+    /**
+     * Create PayloadData from pre-computed hash and URI
+     * @param contentHash - Pre-computed keccak256 hash of content
+     * @param uri - The URI (empty for inline, or external URI)
+     * @returns PayloadData
+     */
+    static fromHashAndUri(contentHash: string, uri: string): PayloadData;
+    /**
+     * Create empty PayloadData (no content)
+     * @returns PayloadData with zero hash and empty URI
+     */
+    static empty(): PayloadData;
+    /**
+     * Compute content hash using keccak256
+     * @param content - Content string to hash
+     * @returns bytes32 hash string
+     */
+    static computeHash(content: string): string;
+    /**
+     * Verify that content matches the hash in PayloadData
+     * @param payload - PayloadData to verify
+     * @param content - Content to verify against
+     * @returns true if content hash matches
+     */
+    static verifyContent(payload: PayloadData, content: string): boolean;
+}
 declare class CommitmentUtils {
     /**
      * Calculate commitment hash
@@ -597,4 +701,431 @@ declare class ConfigLoader {
     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 };
+/**
+ * Payload Storage Interface
+ *
+ * Defines the contract for storage providers that can upload/download payload data.
+ * Implementations: IpfsStorage, ArweaveStorage, HttpStorage, etc.
+ */
+/**
+ * Storage provider configuration
+ */
+interface StorageConfig {
+    /** API endpoint URL */
+    apiUrl?: string;
+    /** Gateway URL for fetching content */
+    gateway?: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** API secret for authentication */
+    apiSecret?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Upload result containing the URI and metadata
+ */
+interface UploadResult {
+    /** Full URI (e.g., "ipfs://Qm...", "ar://...") */
+    uri: string;
+    /** Content identifier (CID for IPFS, txId for Arweave) */
+    contentId: string;
+    /** Size of uploaded content in bytes */
+    size: number;
+}
+/**
+ * Storage provider interface
+ */
+interface IPayloadStorage {
+    /**
+     * Upload content to storage
+     * @param content - Content to upload (string or Buffer)
+     * @returns Upload result with URI
+     */
+    upload(content: string | Buffer): Promise<UploadResult>;
+    /**
+     * Download content from storage
+     * @param uri - Full URI (e.g., "ipfs://Qm...")
+     * @returns Downloaded content as string
+     */
+    download(uri: string): Promise<string>;
+    /**
+     * Check if the storage provider is configured and available
+     * @returns true if storage is ready to use
+     */
+    isConfigured(): boolean;
+    /**
+     * Get the URI scheme this storage provider handles
+     * @returns Scheme string (e.g., "ipfs", "ar", "https")
+     */
+    getScheme(): string;
+}
+
+/**
+ * IPFS Storage Provider
+ *
+ * Supports both local IPFS nodes and Pinata API for pinning.
+ *
+ * @example
+ * ```typescript
+ * // Local IPFS node
+ * const storage = new IpfsStorage({
+ *   apiUrl: 'http://localhost:5001',
+ *   gateway: 'http://localhost:8080/ipfs/'
+ * });
+ *
+ * // Pinata
+ * const storage = new IpfsStorage({
+ *   apiUrl: 'https://api.pinata.cloud',
+ *   apiKey: 'your-api-key',
+ *   apiSecret: 'your-api-secret',
+ *   gateway: 'https://gateway.pinata.cloud/ipfs/'
+ * });
+ *
+ * const result = await storage.upload('Hello, IPFS!');
+ * console.log(result.uri); // "ipfs://Qm..."
+ * ```
+ */
+
+/**
+ * IPFS-specific configuration
+ */
+interface IpfsStorageConfig extends StorageConfig {
+    /** IPFS API URL (default: http://localhost:5001) */
+    apiUrl?: string;
+    /** IPFS Gateway URL (default: http://localhost:8080/ipfs/) */
+    gateway?: string;
+    /** Pinata API key (required for Pinata) */
+    apiKey?: string;
+    /** Pinata API secret (required for Pinata) */
+    apiSecret?: string;
+}
+declare class IpfsStorage implements IPayloadStorage {
+    private apiUrl;
+    private gateway;
+    private apiKey?;
+    private apiSecret?;
+    private timeout;
+    private isLocalNode;
+    constructor(config?: IpfsStorageConfig);
+    getScheme(): string;
+    isConfigured(): boolean;
+    upload(content: string | Buffer): Promise<UploadResult>;
+    private uploadToLocalNode;
+    private uploadToPinata;
+    download(uri: string): Promise<string>;
+    /**
+     * Extract CID from IPFS URI
+     */
+    private extractCid;
+    /**
+     * Get the gateway URL for a given CID
+     */
+    getGatewayUrl(cidOrUri: string): string;
+}
+
+/**
+ * Data URI Storage Provider
+ *
+ * Handles inline data using data: URI scheme (RFC 2397).
+ * Used for small payloads that can be embedded directly.
+ *
+ * @example
+ * ```typescript
+ * const storage = new DataUriStorage();
+ * const result = await storage.upload('{"action":"ping"}');
+ * console.log(result.uri);
+ * // "data:application/json;base64,eyJhY3Rpb24iOiJwaW5nIn0="
+ * ```
+ */
+
+interface DataUriStorageConfig {
+    /** MIME type for the data (default: application/json) */
+    mimeType?: string;
+}
+declare class DataUriStorage implements IPayloadStorage {
+    private mimeType;
+    constructor(config?: DataUriStorageConfig);
+    getScheme(): string;
+    isConfigured(): boolean;
+    upload(content: string | Buffer): Promise<UploadResult>;
+    download(uri: string): Promise<string>;
+}
+
+/**
+ * HTTP/HTTPS Storage Provider
+ *
+ * Handles fetching content from HTTP/HTTPS URLs.
+ * Upload is not supported - use a dedicated storage service instead.
+ *
+ * @example
+ * ```typescript
+ * const storage = new HttpStorage();
+ * const content = await storage.download('https://api.example.com/data/123');
+ * ```
+ */
+
+interface HttpStorageConfig {
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Default headers to include in requests */
+    headers?: Record<string, string>;
+}
+declare class HttpStorage implements IPayloadStorage {
+    private timeout;
+    private headers;
+    constructor(config?: HttpStorageConfig);
+    getScheme(): string;
+    isConfigured(): boolean;
+    upload(_content: string | Buffer): Promise<UploadResult>;
+    download(uri: string): Promise<string>;
+}
+
+/**
+ * S3-Compatible Storage Provider
+ *
+ * Supports AWS S3, Cloudflare R2, MinIO, and other S3-compatible storage services.
+ * Uses the AWS SDK v3 for S3 operations.
+ *
+ * @example
+ * ```typescript
+ * // Cloudflare R2
+ * const storage = new S3Storage({
+ *   endpoint: 'https://xxx.r2.cloudflarestorage.com',
+ *   bucket: 'my-bucket',
+ *   region: 'auto',
+ *   accessKeyId: 'your-access-key',
+ *   secretAccessKey: 'your-secret-key',
+ *   publicUrlBase: 'https://pub-xxx.r2.dev'
+ * });
+ *
+ * // AWS S3
+ * const storage = new S3Storage({
+ *   bucket: 'my-bucket',
+ *   region: 'us-east-1',
+ *   accessKeyId: 'your-access-key',
+ *   secretAccessKey: 'your-secret-key',
+ *   publicUrlBase: 'https://my-bucket.s3.us-east-1.amazonaws.com'
+ * });
+ *
+ * // MinIO (local)
+ * const storage = new S3Storage({
+ *   endpoint: 'http://localhost:9000',
+ *   bucket: 'my-bucket',
+ *   region: 'us-east-1',
+ *   accessKeyId: 'minioadmin',
+ *   secretAccessKey: 'minioadmin',
+ *   publicUrlBase: 'http://localhost:9000/my-bucket',
+ *   forcePathStyle: true
+ * });
+ *
+ * const result = await storage.upload('Hello, S3!');
+ * console.log(result.uri); // "https://pub-xxx.r2.dev/abc123.json"
+ * ```
+ */
+
+/**
+ * S3-compatible storage configuration
+ */
+interface S3StorageConfig {
+    /** S3-compatible endpoint URL (required for R2/MinIO, optional for AWS S3) */
+    endpoint?: string;
+    /** Bucket name */
+    bucket: string;
+    /** AWS region (default: 'auto' for R2, 'us-east-1' for others) */
+    region?: string;
+    /** Access key ID */
+    accessKeyId: string;
+    /** Secret access key */
+    secretAccessKey: string;
+    /**
+     * Public URL base for generating accessible URLs
+     * e.g., "https://pub-xxx.r2.dev" or "https://cdn.example.com"
+     */
+    publicUrlBase: string;
+    /**
+     * Key prefix for organizing files
+     * e.g., "noosphere/outputs/"
+     */
+    keyPrefix?: string;
+    /**
+     * Use path-style URLs (required for MinIO)
+     * Default: false (uses virtual-hosted style)
+     */
+    forcePathStyle?: boolean;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Content type for uploaded files (default: 'application/json') */
+    contentType?: string;
+}
+declare class S3Storage implements IPayloadStorage {
+    private config;
+    private client;
+    private PutObjectCommandClass;
+    private initialized;
+    private initError;
+    constructor(config: S3StorageConfig);
+    /**
+     * Lazily initialize the S3 client
+     * This allows the class to be instantiated even if @aws-sdk/client-s3 is not installed
+     */
+    private initClient;
+    getScheme(): string;
+    isConfigured(): boolean;
+    /**
+     * Generate a unique key for the content based on its hash
+     */
+    private generateKey;
+    upload(content: string | Buffer): Promise<UploadResult>;
+    download(uri: string): Promise<string>;
+    /**
+     * Get the public URL for a given key
+     */
+    getPublicUrl(key: string): string;
+}
+
+/**
+ * PayloadResolver - Unified Payload Resolution
+ *
+ * Resolves PayloadData to actual content by:
+ * 1. Detecting URI scheme (data:, ipfs://, https://, ar://)
+ * 2. Fetching content from appropriate storage
+ * 3. Verifying content hash for integrity
+ *
+ * Also handles encoding output as PayloadData with automatic
+ * storage selection based on content size.
+ *
+ * @example
+ * ```typescript
+ * const resolver = new PayloadResolver({
+ *   ipfs: { gateway: 'http://localhost:8080/ipfs/' },
+ *   uploadThreshold: 1024,
+ *   defaultStorage: 'ipfs'
+ * });
+ *
+ * // Resolve input from PayloadData
+ * const content = await resolver.resolve(payloadData);
+ *
+ * // Encode output as PayloadData (auto-uploads if large)
+ * const outputPayload = await resolver.encode(outputContent);
+ * ```
+ */
+
+/**
+ * Supported URI schemes
+ */
+declare enum PayloadScheme {
+    DATA = "data",
+    IPFS = "ipfs",
+    HTTPS = "https",
+    HTTP = "http",
+    ARWEAVE = "ar",
+    CHAIN = "chain"
+}
+/**
+ * PayloadResolver configuration
+ */
+interface PayloadResolverConfig {
+    /** IPFS storage configuration */
+    ipfs?: IpfsStorageConfig;
+    /** S3-compatible storage configuration (R2, S3, MinIO) */
+    s3?: S3StorageConfig;
+    /** Arweave gateway URL */
+    arweaveGateway?: string;
+    /** Size threshold for auto-upload (bytes, default: 1024) */
+    uploadThreshold?: number;
+    /** Default storage for large payloads ('ipfs' | 's3' | 'data') */
+    defaultStorage?: 'ipfs' | 's3' | 'data';
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Resolved payload result
+ */
+interface ResolvedPayload {
+    /** Actual content string */
+    content: string;
+    /** Original PayloadData */
+    payload: PayloadData;
+    /** Detected scheme */
+    scheme: PayloadScheme;
+    /** Whether content hash was verified */
+    verified: boolean;
+}
+declare class PayloadResolver {
+    private ipfsStorage;
+    private s3Storage;
+    private dataUriStorage;
+    private httpStorage;
+    private uploadThreshold;
+    private defaultStorage;
+    private arweaveGateway;
+    constructor(config?: PayloadResolverConfig);
+    /**
+     * Detect URI scheme from PayloadData
+     */
+    detectScheme(payload: PayloadData): PayloadScheme;
+    /**
+     * Resolve PayloadData to actual content
+     *
+     * @param payload - PayloadData to resolve
+     * @param verifyHash - Whether to verify content hash (default: true)
+     * @returns Resolved content and metadata
+     */
+    resolve(payload: PayloadData, verifyHash?: boolean): Promise<ResolvedPayload>;
+    /**
+     * Resolve Arweave URI
+     */
+    private resolveArweave;
+    /**
+     * Encode content as PayloadData
+     *
+     * Automatically uploads to external storage if content exceeds threshold.
+     *
+     * @param content - Content to encode
+     * @param options - Encoding options
+     * @returns PayloadData ready for on-chain submission
+     */
+    encode(content: string, options?: {
+        forceUpload?: boolean;
+        storage?: 'ipfs' | 's3' | 'data';
+    }): Promise<PayloadData>;
+    /**
+     * Create empty PayloadData
+     */
+    createEmpty(): PayloadData;
+    /**
+     * Verify content matches PayloadData hash
+     */
+    verifyContent(payload: PayloadData, content: string): boolean;
+    /**
+     * Get the configured IPFS storage instance
+     */
+    getIpfsStorage(): IpfsStorage;
+    /**
+     * Get the configured S3 storage instance
+     */
+    getS3Storage(): S3Storage | null;
+    /**
+     * Check if IPFS is configured
+     */
+    isIpfsConfigured(): boolean;
+    /**
+     * Check if S3 is configured
+     */
+    isS3Configured(): boolean;
+    /**
+     * Get the default storage type
+     */
+    getDefaultStorage(): 'ipfs' | 's3' | 'data';
+    /**
+     * Serialize PayloadData for database storage
+     */
+    serialize(payload: PayloadData): string;
+    /**
+     * Deserialize PayloadData from database storage
+     */
+    deserialize(serialized: string): PayloadData;
+}
+
+export { type AgentConfig, type CheckpointData$1 as CheckpointData, type Commitment, type CommitmentSuccessCallbackEvent, type CommitmentSuccessEvent, CommitmentUtils, type ComputeDeliveredEvent, type ComputeSubscription, ConfigLoader, type ContainerConfig, type ContainerExecutionConfig, ContainerManager, type ContainerMetadata, DataUriStorage, type DataUriStorageConfig, EventMonitor, FulfillResult, HttpStorage, type HttpStorageConfig, type IPayloadStorage, IpfsStorage, type IpfsStorageConfig, NoosphereAgent, type NoosphereAgentConfig, PayloadResolver, type PayloadResolverConfig, PayloadScheme, PayloadUtils, type Payment, type ProofVerificationRequest, RequestIdUtils, type RequestStartedCallbackEvent, type RequestStartedEvent, type ResolvedPayload, type RetryableEvent, S3Storage, type S3StorageConfig, SchedulerService, type StorageConfig, type UploadResult, type VerifierMetadata };