@agirails/sdk 2.0.1-beta → 2.0.2

package/dist/level1/Agent.d.ts

@@ -0,0 +1,472 @@
+/**
+ * Agent - Standard API for AI agents
+ *
+ * Provides agent-level abstractions: lifecycle, service provision,
+ * job handling, events, and statistics.
+ *
+ * @packageDocumentation
+ */
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+import { ACTPClient } from '../ACTPClient';
+import { Job, JobHandler } from './types/Job';
+import { RequestOptions, RequestResult, NetworkOption } from './types/Options';
+import { PricingStrategy } from './pricing/PricingStrategy';
+/**
+ * Agent lifecycle states
+ */
+export type AgentStatus = 'idle' | 'starting' | 'running' | 'paused' | 'stopping' | 'stopped';
+/**
+ * Service filter configuration
+ */
+export interface ServiceFilter {
+    /**
+     * Minimum budget in USDC (e.g., 5.00 for $5)
+     */
+    minBudget?: number;
+    /**
+     * Maximum budget in USDC (e.g., 100.00 for $100)
+     */
+    maxBudget?: number;
+    /**
+     * Custom filter function
+     */
+    custom?: (job: Job) => boolean;
+}
+/**
+ * Service configuration
+ */
+export interface ServiceConfig {
+    /**
+     * Service name (e.g., 'translation', 'echo')
+     */
+    name: string;
+    /**
+     * Human-readable description
+     */
+    description?: string;
+    /**
+     * Pricing strategy (cost + margin model)
+     */
+    pricing?: PricingStrategy;
+    /**
+     * Service capabilities/tags
+     */
+    capabilities?: string[];
+    /**
+     * Job filter (function or filter config)
+     */
+    filter?: ServiceFilter | ((job: Job) => boolean);
+    /**
+     * Timeout per job (milliseconds)
+     */
+    timeout?: number;
+}
+/**
+ * Agent configuration
+ */
+export interface AgentConfig {
+    /**
+     * Agent name
+     */
+    name: string;
+    /**
+     * Agent description
+     */
+    description?: string;
+    /**
+     * Wallet configuration
+     */
+    wallet?: 'auto' | 'connect' | string | {
+        privateKey: string;
+    };
+    /**
+     * Network
+     */
+    network?: NetworkOption;
+    /**
+     * RPC URL for blockchain connection (required for testnet/mainnet)
+     *
+     * If not provided, defaults to public RPC from network config:
+     * - testnet: https://sepolia.base.org
+     * - mainnet: https://mainnet.base.org
+     *
+     * For production, consider using a dedicated RPC provider (Alchemy, Infura, etc.)
+     * for better reliability and rate limits.
+     *
+     * @example
+     * rpcUrl: 'https://base-sepolia.g.alchemy.com/v2/YOUR_API_KEY'
+     */
+    rpcUrl?: string;
+    /**
+     * State directory (mock mode only)
+     */
+    stateDirectory?: string;
+    /**
+     * Behavior configuration
+     */
+    behavior?: {
+        /**
+         * Auto-accept jobs
+         */
+        autoAccept?: boolean | ((job: Job) => boolean | Promise<boolean>);
+        /**
+         * Max concurrent jobs
+         */
+        concurrency?: number;
+        /**
+         * Retry configuration
+         */
+        retry?: {
+            attempts?: number;
+            delay?: number;
+            backoff?: 'linear' | 'exponential';
+        };
+    };
+    /**
+     * Persistence configuration
+     */
+    persistence?: {
+        enabled?: boolean;
+        path?: string;
+    };
+    /**
+     * Logging configuration
+     */
+    logging?: {
+        level?: 'debug' | 'info' | 'warn' | 'error';
+    };
+}
+/**
+ * Agent statistics
+ */
+export interface AgentStats {
+    jobsReceived: number;
+    jobsCompleted: number;
+    jobsFailed: number;
+    totalEarned: number;
+    totalSpent: number;
+    averageJobTime: number;
+    successRate: number;
+}
+/**
+ * Agent balance information
+ */
+export interface AgentBalance {
+    eth: string;
+    usdc: string;
+    locked: string;
+    pending: string;
+}
+/**
+ * Agent class - Standard API
+ *
+ * Represents an autonomous AI agent that can provide services,
+ * request services from other agents, and manage its lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const agent = new Agent({ name: 'Translator', network: 'mock' });
+ *
+ * agent.provide('translation', async (job, ctx) => {
+ *   ctx.progress(50, 'Translating...');
+ *   return { translated: translate(job.input.text) };
+ * });
+ *
+ * agent.on('payment:received', (amount) => {
+ *   console.log(`Earned ${amount} USDC!`);
+ * });
+ *
+ * await agent.start();
+ * ```
+ */
+export declare class Agent extends EventEmitter {
+    /**
+     * Agent name
+     */
+    readonly name: string;
+    /**
+     * Agent description
+     */
+    readonly description?: string;
+    /**
+     * Network the agent operates on
+     */
+    readonly network: NetworkOption;
+    /**
+     * Current agent status
+     */
+    private _status;
+    /**
+     * ACTP Client instance
+     */
+    private _client?;
+    /**
+     * Registered services
+     */
+    private services;
+    /**
+     * Active jobs
+     *
+     * SECURITY FIX (C-2): Changed from Map to LRUCache to prevent unbounded growth
+     * Maximum 1000 active jobs with LRU eviction
+     */
+    private activeJobs;
+    /**
+     * Processed job IDs (for deduplication)
+     *
+     * SECURITY FIX (C-1): Track jobs we've attempted to process
+     * This prevents race conditions where the same job is processed multiple times
+     * before the state transition completes
+     */
+    private processedJobs;
+    /**
+     * Processing locks (for atomic locking)
+     *
+     * SECURITY FIX (C-1): Mutex for job processing.
+     * When we see a job, we IMMEDIATELY add to this set (atomic in single-threaded JS).
+     * This prevents race conditions where two poll cycles both pass the processedJobs.has()
+     * check before either calls processedJobs.set().
+     */
+    private processingLocks;
+    /**
+     * Concurrency semaphore
+     *
+     * SECURITY FIX (MEDIUM-4): Limits concurrent job execution to prevent
+     * resource exhaustion (memory/CPU DoS). Uses behavior.concurrency setting.
+     */
+    private concurrencySemaphore;
+    /**
+     * Statistics
+     */
+    private _stats;
+    /**
+     * Cached balance (updated periodically during polling)
+     */
+    private _balance;
+    /**
+     * Configuration
+     */
+    private config;
+    /**
+     * Polling interval ID (for job polling)
+     */
+    private pollingIntervalId?;
+    /**
+     * Logger instance
+     */
+    private logger;
+    /**
+     * Creates a new Agent instance
+     *
+     * @param config - Agent configuration
+     */
+    constructor(config: AgentConfig);
+    /**
+     * Start the agent
+     *
+     * Initializes ACTP client and begins polling for jobs.
+     *
+     * @throws {AgentLifecycleError} If agent is not in idle or stopped state
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the agent
+     *
+     * Stops polling and waits for active jobs to complete.
+     */
+    stop(): Promise<void>;
+    /**
+     * Pause the agent
+     *
+     * Stops accepting new jobs but keeps active jobs running.
+     */
+    pause(): void;
+    /**
+     * Resume the agent
+     *
+     * Resumes accepting new jobs after being paused.
+     */
+    resume(): void;
+    /**
+     * Restart the agent
+     */
+    restart(): Promise<void>;
+    /**
+     * Register a service handler
+     *
+     * @param serviceOrConfig - Service name or full configuration
+     * @param handler - Job handler function
+     * @param options - Optional pricing/filter configuration
+     *
+     * @example
+     * ```typescript
+     * // Simple
+     * agent.provide('echo', async (job) => job.input);
+     *
+     * // With pricing
+     * agent.provide({
+     *   name: 'translation',
+     *   pricing: {
+     *     cost: { base: 0.5, perUnit: { unit: 'word', rate: 0.005 } },
+     *     margin: 0.40
+     *   }
+     * }, async (job, ctx) => {
+     *   // ... translation logic
+     * });
+     * ```
+     */
+    provide(serviceOrConfig: string | ServiceConfig, handler: JobHandler, options?: Partial<ServiceConfig>): this;
+    /**
+     * Request a service from another agent
+     *
+     * @param service - Service name
+     * @param options - Request options
+     * @returns Promise resolving to result
+     */
+    request(service: string, options: Omit<RequestOptions, 'network'>): Promise<RequestResult>;
+    /**
+     * Current agent status
+     */
+    get status(): AgentStatus;
+    /**
+     * Agent's Ethereum address
+     */
+    get address(): string;
+    /**
+     * Registered service names
+     */
+    get serviceNames(): string[];
+    /**
+     * Active jobs
+     *
+     * SECURITY FIX (N-2): Now uses LRUCache.values() iterator.
+     * Returns a snapshot of currently active jobs.
+     */
+    get jobs(): Job[];
+    /**
+     * Statistics
+     */
+    get stats(): AgentStats;
+    /**
+     * Get agent balance
+     *
+     * Returns current USDC balance plus locked/pending amounts from active transactions.
+     * Note: This is an async operation wrapped in a sync getter for convenience.
+     * For real-time balance, use getBalanceAsync() instead.
+     */
+    get balance(): AgentBalance;
+    /**
+     * Get agent balance asynchronously (real-time)
+     *
+     * @returns Promise resolving to current balance
+     */
+    getBalanceAsync(): Promise<AgentBalance>;
+    /**
+     * ACTP Client reference (for advanced usage)
+     */
+    get client(): ACTPClient | undefined;
+    /**
+     * Start polling for new jobs
+     */
+    private startPolling;
+    /**
+     * Stop polling
+     */
+    private stopPolling;
+    /**
+     * Poll for new jobs
+     *
+     * SECURITY FIXES:
+     * - C-1: Race condition prevention using processedJobs deduplication
+     * - C-2: Memory leak prevention using LRUCache
+     * - H-1: DoS prevention by filtering transactions before loading all
+     * - H-4: Authorization checks for state transitions
+     *
+     * Queries runtime for transactions where this agent is the provider
+     * and the transaction is in INITIATED state (awaiting acceptance).
+     * For each pending transaction, creates a Job object and invokes
+     * the appropriate service handler.
+     */
+    private pollForJobs;
+    /**
+     * Find service handler for a transaction
+     *
+     * SECURITY FIX (MEDIUM): Use exact field matching instead of substring search
+     * to prevent service routing spoofing attacks.
+     *
+     * Supports multiple formats (in priority order):
+     * 1. JSON: {"service":"name","input":...} - new structured format
+     * 2. Legacy: "service:name;input:..." - backward compatibility
+     * 3. Plain string exact match - simple service name
+     * 4. bytes32 hash - on-chain only (requires off-chain lookup)
+     */
+    private findServiceHandler;
+    /**
+     * Check if job should be auto-accepted
+     *
+     * SECURITY FIX (MVP): Added pricing strategy evaluation
+     * - Checks service-level filters (budget constraints)
+     * - Evaluates pricing strategy if configured
+     * - Only accepts jobs that meet pricing requirements
+     */
+    private shouldAutoAccept;
+    /**
+     * Create Job object from MockTransaction
+     */
+    private createJobFromTransaction;
+    /**
+     * Extract service name from transaction
+     *
+     * Supports multiple formats:
+     * 1. JSON: {"service":"name","input":...}
+     * 2. Legacy: "service:name;input:..."
+     * 3. Plain string (service name directly)
+     */
+    private extractServiceName;
+    /**
+     * Extract job input from transaction
+     *
+     * Supports multiple formats:
+     * 1. JSON: {"service":"name","input":{...}}
+     * 2. Legacy: "service:name;input:JSON"
+     */
+    private extractJobInput;
+    /**
+     * Extract metadata from transaction
+     */
+    private extractMetadata;
+    /**
+     * Convert amount string to number (USDC has 6 decimals)
+     */
+    private convertAmountToNumber;
+    /**
+     * Process a job by invoking the handler
+     *
+     * SECURITY FIX (C-2): Always cleanup activeJobs on completion/failure
+     * SECURITY FIX (MEDIUM-4): Uses semaphore to limit concurrent execution
+     */
+    private processJob;
+    /**
+     * Create JobContext for handler execution
+     */
+    private createJobContext;
+    /**
+     * Wait for active jobs to complete
+     */
+    private waitForActiveJobs;
+    /**
+     * Generate address based on wallet configuration
+     *
+     * SECURITY FIX (HIGH): For testnet/mainnet, MUST derive from private key.
+     * For mock mode, can use deterministic address for convenience.
+     */
+    private generateAddress;
+    /**
+     * Get private key from configuration
+     *
+     * SECURITY FIX (HIGH): Validate private key format before use
+     */
+    private getPrivateKey;
+}
+//# sourceMappingURL=Agent.d.ts.map

package/dist/level1/Agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../src/level1/Agent.ts"],"names":[],"mappings":"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"}