@agirails/sdk 2.0.1-beta → 2.0.2

package/src/level0/Provider.ts

@@ -0,0 +1,117 @@
+/**
+ * Provider - Return type of provide() function
+ *
+ * Provides control and observability for a running service provider.
+ *
+ * @packageDocumentation
+ */
+
+import { Job } from '../level1/types/Job';
+
+/**
+ * Provider status
+ */
+export type ProviderStatus = 'starting' | 'running' | 'paused' | 'stopped';
+
+/**
+ * Provider statistics
+ */
+export interface ProviderStats {
+  jobsCompleted: number;
+  jobsFailed: number;
+  totalEarned: number;
+  averageJobTime: number;
+}
+
+/**
+ * Provider balance
+ */
+export interface ProviderBalance {
+  eth: string;
+  usdc: string;
+}
+
+/**
+ * Provider interface
+ *
+ * Returned by provide() to control the provider lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const provider = provide('echo', async (job) => job.input);
+ *
+ * // Monitor events
+ * provider.on('job:received', (job) => {
+ *   console.log(`Received job: ${job.id}`);
+ * });
+ *
+ * provider.on('payment:received', (amount) => {
+ *   console.log(`Earned ${amount} USDC`);
+ * });
+ *
+ * // Control lifecycle
+ * provider.pause();  // Stop accepting new jobs
+ * provider.resume(); // Resume
+ * await provider.stop(); // Graceful shutdown
+ *
+ * // Check statistics
+ * console.log(`Completed: ${provider.stats.jobsCompleted}`);
+ * console.log(`Earned: $${provider.stats.totalEarned}`);
+ * ```
+ */
+export interface Provider {
+  /**
+   * Current status
+   */
+  status: ProviderStatus;
+
+  /**
+   * Provider's Ethereum address
+   */
+  address: string;
+
+  /**
+   * Balance information
+   */
+  balance: ProviderBalance;
+
+  /**
+   * Pause the provider
+   *
+   * Stops accepting new jobs but keeps running jobs active.
+   */
+  pause(): void;
+
+  /**
+   * Resume the provider
+   *
+   * Resumes accepting new jobs after pause.
+   */
+  resume(): void;
+
+  /**
+   * Stop the provider
+   *
+   * Gracefully shuts down, waiting for active jobs to complete.
+   */
+  stop(): Promise<void>;
+
+  /**
+   * Register event listener
+   *
+   * Supported events:
+   * - 'job:received': (job: Job) => void
+   * - 'job:completed': (job: Job, result: any) => void
+   * - 'job:failed': (job: Job, error: Error) => void
+   * - 'payment:received': (amount: number) => void
+   */
+  on(event: 'job:received', handler: (job: Job) => void): void;
+  on(event: 'job:completed', handler: (job: Job, result: any) => void): void;
+  on(event: 'job:failed', handler: (job: Job, error: Error) => void): void;
+  on(event: 'payment:received', handler: (amount: number) => void): void;
+
+  /**
+   * Statistics
+   */
+  stats: ProviderStats;
+}

package/src/level0/ServiceDirectory.ts

@@ -0,0 +1,131 @@
+/**
+ * ServiceDirectory - Hardcoded provider mapping for MVP
+ *
+ * In MVP, we use hardcoded service-to-provider mapping.
+ * In V2+, this will be replaced by on-chain AgentRegistry queries.
+ *
+ * @packageDocumentation
+ */
+
+import { validateServiceName, isValidAddress } from '../utils/security';
+
+/**
+ * In-memory service directory
+ *
+ * Maps service names to provider addresses.
+ * This is a singleton that can be updated by provide() calls.
+ *
+ * SECURITY FIXES:
+ * - H-5: Address validation to prevent poisoning
+ * - H-2: Service name validation
+ */
+class ServiceDirectory {
+  /**
+   * Service -> Provider address mapping
+   */
+  private directory = new Map<string, Set<string>>();
+
+  /**
+   * Register a provider for a service
+   *
+   * SECURITY FIX (H-5): Validate address format before registration
+   * SECURITY FIX (H-2): Validate service name
+   *
+   * @param service - Service name
+   * @param provider - Provider address
+   * @throws Error if service name or provider address is invalid
+   */
+  register(service: string, provider: string): void {
+    // SECURITY FIX (H-2): Validate service name
+    const validatedService = validateServiceName(service);
+
+    // SECURITY FIX (H-5): Validate Ethereum address format
+    if (!isValidAddress(provider)) {
+      throw new Error(
+        `Invalid provider address: "${provider}". Must be a valid Ethereum address (0x followed by 40 hex characters).`
+      );
+    }
+
+    if (!this.directory.has(validatedService)) {
+      this.directory.set(validatedService, new Set());
+    }
+
+    this.directory.get(validatedService)!.add(provider);
+  }
+
+  /**
+   * Unregister a provider from a service
+   *
+   * SECURITY FIX (H-5): Validate address format
+   * SECURITY FIX (H-2): Validate service name
+   *
+   * @param service - Service name
+   * @param provider - Provider address
+   */
+  unregister(service: string, provider: string): void {
+    // SECURITY FIX (H-2): Validate service name
+    const validatedService = validateServiceName(service);
+
+    // SECURITY FIX (H-5): Validate address format
+    if (!isValidAddress(provider)) {
+      throw new Error(`Invalid provider address: "${provider}"`);
+    }
+
+    const providers = this.directory.get(validatedService);
+    if (providers) {
+      providers.delete(provider);
+      if (providers.size === 0) {
+        this.directory.delete(validatedService);
+      }
+    }
+  }
+
+  /**
+   * Find providers for a service
+   *
+   * SECURITY FIX (H-2): Validate service name
+   *
+   * @param service - Service name
+   * @returns Array of provider addresses
+   */
+  findProviders(service: string): string[] {
+    // SECURITY FIX (H-2): Validate service name
+    try {
+      const validatedService = validateServiceName(service);
+      const providers = this.directory.get(validatedService);
+      return providers ? Array.from(providers) : [];
+    } catch (error) {
+      // If service name is invalid, return empty array instead of throwing
+      // This allows graceful degradation in search scenarios
+      return [];
+    }
+  }
+
+  /**
+   * Get all registered services
+   *
+   * @returns Array of service names
+   */
+  getServices(): string[] {
+    return Array.from(this.directory.keys());
+  }
+
+  /**
+   * Clear all registrations
+   */
+  clear(): void {
+    this.directory.clear();
+  }
+
+  /**
+   * Get directory size (for debugging)
+   */
+  get size(): number {
+    return this.directory.size;
+  }
+}
+
+/**
+ * Singleton instance
+ */
+export const serviceDirectory = new ServiceDirectory();

package/src/level0/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Basic API - Simple service provision and requests
+ *
+ * @packageDocumentation
+ */
+
+export { provide } from './provide';
+export { request } from './request';
+export { Provider, ProviderStatus, ProviderStats, ProviderBalance } from './Provider';
+export { serviceDirectory } from './ServiceDirectory';

package/src/level0/provide.ts

@@ -0,0 +1,131 @@
+/**
+ * provide() - Basic API for service providers
+ *
+ * The simplest way to provide a service on AGIRAILS.
+ * Just write a function, and AGIRAILS handles the rest.
+ *
+ * @packageDocumentation
+ */
+
+import { Agent } from '../level1/Agent';
+import { JobHandler } from '../level1/types/Job';
+import { ProvideOptions } from '../level1/types/Options';
+import { Provider } from './Provider';
+import { serviceDirectory } from './ServiceDirectory';
+
+/**
+ * Provide a service
+ *
+ * This is the simplest way to provide a service on AGIRAILS.
+ * You provide a service name and a handler function, and AGIRAILS
+ * takes care of wallet management, transactions, and payments.
+ *
+ * @param service - Service name (e.g., 'translation', 'echo')
+ * @param handler - Job handler function
+ * @param options - Optional configuration
+ * @returns Provider interface for lifecycle control
+ *
+ * @example
+ * ```typescript
+ * // Simplest example
+ * provide('echo', async (job) => {
+ *   return job.input;
+ * });
+ *
+ * // With filtering
+ * provide('translation', async (job) => {
+ *   const { text, from, to } = job.input;
+ *   return { translated: await translate(text, from, to) };
+ * }, {
+ *   filter: { minBudget: 5 },
+ *   network: 'testnet'
+ * });
+ *
+ * // With events
+ * const provider = provide('image-gen', async (job) => {
+ *   return { imageUrl: await generateImage(job.input.prompt) };
+ * });
+ *
+ * provider.on('payment:received', (amount) => {
+ *   console.log(`Earned ${amount} USDC!`);
+ * });
+ * ```
+ */
+export function provide(
+  service: string,
+  handler: JobHandler,
+  options?: ProvideOptions
+): Provider {
+  // Create an Agent instance under the hood
+  const agent = new Agent({
+    name: `Provider:${service}`,
+    description: `Auto-generated provider for ${service}`,
+    network: options?.network || 'mock',
+    wallet: options?.wallet,
+    stateDirectory: options?.stateDirectory,
+    rpcUrl: options?.rpcUrl,
+    behavior: {
+      autoAccept: options?.autoAccept ?? true,
+    },
+  });
+
+  // Register the service with filter options
+  agent.provide(
+    {
+      name: service,
+      filter: options?.filter,
+    },
+    handler
+  );
+
+  // Start the agent immediately (async)
+  agent.start().then(() => {
+    // Register in service directory after agent has started and has an address
+    serviceDirectory.register(service, agent.address);
+  }).catch((error) => {
+    console.error(`Failed to start provider for ${service}:`, error);
+  });
+
+  // Return Provider interface (adapter over Agent)
+  const provider: Provider = {
+    get status() {
+      return agent.status as any;
+    },
+
+    get address() {
+      return agent.address;
+    },
+
+    get balance() {
+      return agent.balance;
+    },
+
+    pause() {
+      agent.pause();
+    },
+
+    resume() {
+      agent.resume();
+    },
+
+    async stop() {
+      await agent.stop();
+      serviceDirectory.unregister(service, agent.address);
+    },
+
+    on(event: any, handler: any) {
+      agent.on(event, handler);
+    },
+
+    get stats() {
+      return {
+        jobsCompleted: agent.stats.jobsCompleted,
+        jobsFailed: agent.stats.jobsFailed,
+        totalEarned: agent.stats.totalEarned,
+        averageJobTime: agent.stats.averageJobTime,
+      };
+    },
+  };
+
+  return provider;
+}