@happyvertical/smrt-agents 0.30.0

package/dist/agent.d.ts

@@ -0,0 +1,545 @@
+import { Logger } from '@happyvertical/logger';
+import { ConfigResolver, DispatchBus, DispatchMetadata, SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+import { AgentAIOptions } from './ai-config.js';
+import { AgentWithInterestsOptions, InterestOptions, InterestResult } from './interests.js';
+import { AgentStatusType } from './types.js';
+import { AgentAdminRoute, AgentUISlots } from './ui.js';
+/**
+ * Agent constructor options
+ */
+export interface AgentOptions extends SmrtObjectOptions, AgentWithInterestsOptions {
+    /**
+     * Optional AI configuration for this agent.
+     *
+     * When `apiKey` is omitted, the runtime can resolve provider credentials from
+     * tenant secrets based on the active tenant context.
+     */
+    ai?: AgentAIOptions;
+    /**
+     * Suppress all log output (useful for CLI --json mode)
+     * When true, creates a no-op logger that discards all messages
+     */
+    silent?: boolean;
+    /**
+     * Opt into process-level SIGTERM/SIGINT handling for this instance.
+     *
+     * Host runtimes should generally own process lifecycle; this remains available
+     * for single-agent CLIs and scripts that explicitly want it. Do not enable
+     * this for multiple agents in the same process unless the host coordinates
+     * shutdown itself; the first handler to finish exits the process.
+     */
+    manageProcessSignals?: boolean;
+}
+/**
+ * Base Agent class for building autonomous actors in the SMRT ecosystem
+ *
+ * Agents are SmrtObjects that perform specific tasks with:
+ * - Status tracking (idle, initializing, running, error, shutdown)
+ * - Configuration management via @have/config
+ * - Structured logging via @happyvertical/logger
+ * - Lifecycle hooks (initialize, validate, run, shutdown)
+ * - Optional process signal handling for graceful shutdown
+ *
+ * Agents can define their own properties for state management - since they extend
+ * SmrtObject, any properties defined will be automatically persisted to the database.
+ *
+ * **Important**: Extending classes must add the `@smrt()` decorator themselves
+ * to configure CLI/API/MCP exposure.
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from '@have/agents';
+ * import { getModuleConfig } from '@have/config';
+ * import { smrt } from '@happyvertical/smrt-core';
+ *
+ * @smrt()
+ * class MyAgent extends Agent {
+ *   protected config = getModuleConfig('my-agent', {
+ *     cronSchedule: '0 2 * * *',
+ *     maxRetries: 3
+ *   });
+ *
+ *   // Define your own state properties (automatically persisted)
+ *   lastCrawl: Date | null = null;
+ *   itemsProcessed: number = 0;
+ *
+ *   async validate(): Promise<void> {
+ *     if (!this.config.cronSchedule) {
+ *       throw new Error('cronSchedule is required');
+ *     }
+ *   }
+ *
+ *   async run(): Promise<void> {
+ *     // Agent logic here
+ *     this.itemsProcessed = 42;
+ *     this.lastCrawl = new Date();
+ *     await this.save(); // Persist state
+ *   }
+ * }
+ *
+ * const agent = new MyAgent({ name: 'my-agent' });
+ * await agent.execute();
+ * ```
+ */
+export declare abstract class Agent extends SmrtObject {
+    /**
+     * Tenant ID for multi-tenant isolation
+     * Nullable to support both tenant-scoped and global agents
+     */
+    tenantId: string | null;
+    /**
+     * UI slots this agent supports for admin panels
+     *
+     * Subclasses override this to declare their admin UI slots.
+     * Each slot can be implemented by a Svelte component.
+     *
+     * @example
+     * ```typescript
+     * static override uiSlots: AgentUISlots = {
+     *   sources: {
+     *     id: 'sources',
+     *     label: 'News Sources',
+     *     description: 'Configure scrapers and data sources',
+     *     icon: 'database',
+     *     order: 1,
+     *   },
+     *   settings: {
+     *     id: 'settings',
+     *     label: 'Agent Settings',
+     *     description: 'Configure agent behavior',
+     *     icon: 'settings',
+     *     order: 2,
+     *   },
+     * };
+     * ```
+     */
+    static uiSlots: AgentUISlots;
+    /**
+     * Admin routes this agent provides
+     *
+     * Subclasses override this to declare admin route metadata.
+     * The vitePluginAgentRoutes Vite plugin reads these from the manifest
+     * and registers them so host applications can discover and render them.
+     *
+     * @example
+     * ```typescript
+     * static override adminRoutes: AgentAdminRoute[] = [
+     *   { path: 'sources', component: 'SourcesPanel', load: 'loadSources' },
+     *   { path: 'sources/[sourceId]', component: 'SourceDetail', load: 'loadSourceDetail' },
+     * ];
+     * ```
+     */
+    static adminRoutes: AgentAdminRoute[];
+    /**
+     * Signal types this agent subscribes to by default
+     *
+     * These are seedable defaults — on `initialize()`, the agent checks the
+     * database first and only creates subscriptions that don't already exist.
+     * The database is the runtime source of truth, allowing users to customize
+     * subscriptions per-tenant via the dashboard without code changes.
+     *
+     * When declared, `execute()` will automatically call `processDispatches()`
+     * before `run()`, so handler agents don't need to manually poll.
+     * Override `handleDispatch()` to process incoming dispatches.
+     *
+     * @example
+     * ```typescript
+     * @smrt({ agent: { icon: 'mail', tier: 'standard' } })
+     * class EmailHandler extends Agent {
+     *   static override signalSubscriptions = ['email.received', 'email.bounced'];
+     *
+     *   async handleDispatch(payload: unknown, metadata: DispatchMetadata) {
+     *     // Called automatically during execute() for each pending dispatch
+     *   }
+     *
+     *   async run() { ... }
+     * }
+     * ```
+     */
+    static signalSubscriptions: string[];
+    /**
+     * Execute-time resolvers for `agent_config` fields that should be computed
+     * lazily rather than snapshotted at sync time.
+     *
+     * Each entry is keyed by the agent_config field it produces. The runtime
+     * (see {@link resolveLazyConfig}) calls every resolver and overlays the
+     * results on top of the persisted config before constructing the agent.
+     * That means env-derived values like asset storage paths, S3 buckets, AI
+     * provider keys, or tenant-scoped DB URLs stay live: rotating an env var
+     * is reflected on the next scheduled run without rewriting the schedule
+     * row.
+     *
+     * Resolvers may be sync or async. Returning `undefined` or `null` leaves
+     * the persisted value in place — both are treated as "no overlay" so the
+     * common `() => process.env.X ?? null` pattern is safe and won't clobber
+     * a snapshotted value when the env var is unset. Throwing falls back to
+     * the persisted value (or to whatever
+     * {@link ResolveLazyConfigOptions.onError} dictates).
+     *
+     * @example
+     * ```typescript
+     * class Praeco extends Agent {
+     *   static override configResolvers = {
+     *     assetStorage: () => resolveSharedAssetStorage(),
+     *     aiKey: async () => loadAIKeyFromSecretsManager(),
+     *   };
+     * }
+     * ```
+     */
+    static configResolvers: Record<string, ConfigResolver>;
+    /**
+     * Current agent status
+     */
+    status: AgentStatusType;
+    /**
+     * Structured logger instance
+     * Created with agent's class name as context
+     */
+    protected logger: Logger;
+    /**
+     * Agent configuration
+     * Must be defined by extending classes using getModuleConfig()
+     *
+     * @example
+     * ```typescript
+     * protected config = getModuleConfig('my-agent', {
+     *   cronSchedule: '0 0 * * *',
+     *   maxRetries: 3
+     * });
+     * ```
+     */
+    protected abstract config: unknown;
+    /**
+     * Signal handlers for graceful shutdown
+     */
+    private signalHandlers;
+    /**
+     * Cached DispatchBus instance for inter-agent communication
+     */
+    private _dispatch;
+    /**
+     * Creates a new Agent instance
+     *
+     * @param options - Configuration options including identifiers and metadata
+     */
+    constructor(options?: AgentOptions);
+    /**
+     * Interest configuration for this agent
+     * Lazily accessed from options on first interesting() call
+     */
+    protected get interests(): InterestOptions | undefined;
+    /**
+     * Canonical agent type for persistence and dispatch routing.
+     */
+    protected getAgentTypeName(): string;
+    /**
+     * Human-readable class name for logs and UI.
+     */
+    protected getAgentClassName(): string;
+    /**
+     * Get UI slot definitions for this agent instance
+     *
+     * Returns the static uiSlots defined on the agent's class.
+     * Used by host applications to discover available admin panels.
+     *
+     * @example
+     * ```typescript
+     * const slots = agent.getUISlots();
+     * for (const [slotId, slot] of Object.entries(slots)) {
+     *   console.log(`${slot.label}: ${slot.description}`);
+     * }
+     * ```
+     */
+    getUISlots(): AgentUISlots;
+    /**
+     * Load all database-persisted configs for this agent
+     *
+     * Returns a Map of slotId → configData for all saved configurations.
+     * Use getMergedConfig() to get file + db merged config for a slot.
+     *
+     * @returns Map of slotId to config data
+     *
+     * @example
+     * ```typescript
+     * const configs = await agent.loadConfigs();
+     * const sources = configs.get('sources');
+     * ```
+     */
+    loadConfigs(): Promise<Map<string, any>>;
+    /**
+     * Save config for a specific UI slot to the database
+     *
+     * Persists configuration data that can be modified by admin panels.
+     * Use this when the user saves changes in an admin UI.
+     *
+     * @param slotId - The UI slot ID (e.g., 'sources', 'settings')
+     * @param data - Configuration data to save
+     *
+     * @example
+     * ```typescript
+     * await agent.saveSlotConfig('sources', {
+     *   scrapers: ['civicweb', 'govstack'],
+     *   refreshInterval: 3600
+     * });
+     * ```
+     */
+    saveSlotConfig(slotId: string, data: Record<string, any>): Promise<void>;
+    /**
+     * Get merged config for a slot (file-based + database)
+     *
+     * Priority order (highest to lowest):
+     * 1. Database-persisted config (from saveSlotConfig)
+     * 2. File-based config (from getModuleConfig)
+     * 3. Agent class defaults
+     *
+     * @param slotId - The UI slot ID
+     * @returns Merged configuration object
+     *
+     * @example
+     * ```typescript
+     * const sourcesConfig = await agent.getMergedConfig('sources');
+     * // Returns file config merged with any db overrides
+     * ```
+     */
+    getMergedConfig(slotId: string): Promise<any>;
+    /**
+     * Export all config for this agent (for static site generation)
+     *
+     * Merges file-based and database configs, then optionally sanitizes
+     * to remove secrets. Use this before building a static site.
+     *
+     * @param options - Export options
+     * @param options.includeSecrets - If true, includes API keys and secrets (default: false)
+     * @returns Merged configuration object
+     *
+     * @example
+     * ```typescript
+     * // Export for static build (secrets filtered)
+     * const config = await agent.exportConfig();
+     *
+     * // Export with secrets (for secure environments)
+     * const fullConfig = await agent.exportConfig({ includeSecrets: true });
+     * ```
+     */
+    exportConfig(options?: {
+        includeSecrets?: boolean;
+    }): Promise<any>;
+    /**
+     * Get the DispatchBus for inter-agent communication
+     *
+     * Creates a DispatchBus lazily on first access. Requires database configuration.
+     *
+     * @example
+     * ```typescript
+     * // Emit a dispatch to other agents
+     * await this.dispatch.emit('campaign.completed', {
+     *   campaignId: '123',
+     *   revenue: 5000
+     * }, { source: this.constructor.name });
+     *
+     * // Subscribe to dispatches
+     * await this.dispatch.subscribe({
+     *   signalType: 'campaign.*',
+     *   subscriber: this.constructor.name
+     * });
+     * ```
+     *
+     * @throws Error if database is not configured
+     */
+    getDispatch(): Promise<DispatchBus>;
+    /**
+     * Handle incoming dispatches
+     *
+     * Override this method to process dispatches targeted at this agent.
+     * Called when process() is invoked for this agent's subscriber name.
+     *
+     * @param payload - Dispatch payload data
+     * @param metadata - Dispatch metadata including type, source, and timing
+     *
+     * @example
+     * ```typescript
+     * async handleDispatch(payload: unknown, metadata: DispatchMetadata): Promise<void> {
+     *   if (metadata.type === 'campaign.completed') {
+     *     const data = payload as { campaignId: string; revenue: number };
+     *     await this.recordRevenue(data.campaignId, data.revenue);
+     *   }
+     * }
+     * ```
+     */
+    handleDispatch(_payload: unknown, _metadata: DispatchMetadata): Promise<void>;
+    /**
+     * Process pending dispatches for this agent
+     *
+     * Finds and processes all pending dispatches that match this agent's subscriptions.
+     * Uses handleDispatch() to process each dispatch.
+     *
+     * @returns Number of dispatches processed
+     *
+     * @example
+     * ```typescript
+     * // In your run() method
+     * const processed = await this.processDispatches();
+     * this.logger.info(`Processed ${processed} dispatches`);
+     * ```
+     */
+    processDispatches(): Promise<number>;
+    /**
+     * Initialize the agent
+     * Sets status to 'initializing' and sets up signal handlers
+     *
+     * Override to perform setup after construction, but always call super.initialize()
+     *
+     * @example
+     * ```typescript
+     * async initialize(): Promise<void> {
+     *   await super.initialize();
+     *   // Custom initialization logic
+     * }
+     * ```
+     */
+    initialize(): Promise<this>;
+    /**
+     * Set up signal handlers for graceful shutdown
+     * Handles SIGTERM and SIGINT for single-agent processes that explicitly opt in.
+     */
+    private setupSignalHandlers;
+    /**
+     * Migrate legacy simple-name dispatch subscribers to the canonical agent type.
+     *
+     * Older releases used `this.constructor.name` directly for subscriber IDs.
+     * That collides across packages and leaves fan-out dispatches targeted at the
+     * wrong subscriber once qualified names are available.
+     */
+    private migrateLegacyDispatchSubscriptions;
+    /**
+     * Clean up signal handlers
+     */
+    private cleanupSignalHandlers;
+    /**
+     * Validate configuration and dependencies
+     * Override to check agent-specific requirements
+     *
+     * @throws Error if validation fails
+     *
+     * @example
+     * ```typescript
+     * async validate(): Promise<void> {
+     *   if (!this.config.apiKey) {
+     *     throw new Error('API key is required');
+     *   }
+     * }
+     * ```
+     */
+    validate(): Promise<void>;
+    /**
+     * Main agent logic
+     * Must be implemented by extending class
+     *
+     * Update this.lastRun.itemsProcessed to track work done
+     *
+     * @example
+     * ```typescript
+     * async run(): Promise<void> {
+     *   this.logger.info('Starting agent work');
+     *   let processed = 0;
+     *
+     *   for (const item of items) {
+     *     await this.processItem(item);
+     *     processed++;
+     *   }
+     *
+     *   this.lastRun.itemsProcessed = processed;
+     *   this.logger.info(`Processed ${processed} items`);
+     * }
+     * ```
+     */
+    abstract run(): Promise<void>;
+    /**
+     * Cleanup and shutdown
+     * Override to perform graceful shutdown
+     *
+     * Always call super.shutdown() to clean up signal handlers
+     *
+     * @example
+     * ```typescript
+     * async shutdown(): Promise<void> {
+     *   this.logger.info('Cleaning up resources');
+     *   await this.cleanup();
+     *   await super.shutdown();
+     * }
+     * ```
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Execute agent with lifecycle management
+     *
+     * Runs the full lifecycle:
+     * 1. initialize() — seeds signal subscriptions if declared
+     * 2. validate()
+     * 3. processDispatches() — auto-processes pending dispatches if subscriptions exist
+     * 4. run()
+     *
+     * Note: handleDispatch() callbacks may fire before run() is entered.
+     *
+     * On error:
+     * 1. Sets status to 'error'
+     * 2. Logs error
+     * 3. Re-throws error
+     *
+     * @example
+     * ```typescript
+     * const agent = new MyAgent({ name: 'my-agent' });
+     *
+     * try {
+     *   await agent.execute();
+     *   console.log('Agent completed successfully');
+     * } catch (error) {
+     *   console.error('Agent failed:', error);
+     * }
+     * ```
+     */
+    execute(): Promise<void>;
+    /**
+     * Query objects this agent is interested in
+     *
+     * Returns items from all configured object types, filtered and sorted
+     * according to interest configuration. If handlers are defined on filters,
+     * they are called for each matched item and the result is included.
+     *
+     * @returns Array of { type, data, name?, handled? } results
+     * @throws Error if no interests are configured
+     *
+     * @example
+     * ```typescript
+     * const items = await this.interesting();
+     * for (const { type, data, name, handled } of items) {
+     *   console.log(`Processing ${type} from "${name}": action=${handled?.action}`);
+     * }
+     * ```
+     */
+    interesting(): Promise<InterestResult[]>;
+    /**
+     * Query a single object type based on interest config
+     *
+     * Supports both single filter and array of filters.
+     * Each filter can use standard SDK filters OR custom query function.
+     * Returns InterestResult[] with handler results included.
+     */
+    private queryInterestingObjects;
+    /**
+     * Normalize ObjectInterestConfig to array format
+     */
+    private normalizeInterestConfig;
+    /**
+     * Query a single interest filter
+     *
+     * Uses collection.query() for custom query functions,
+     * or collection.list() for standard SDK filters.
+     */
+    private queryInterestFilter;
+    /**
+     * Sort results by field(s) across all types
+     */
+    private sortResults;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

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

package/dist/ai-config.d.ts

@@ -0,0 +1,27 @@
+import { AIClientOptions } from '@happyvertical/ai';
+import { DatabaseInterface } from '@happyvertical/sql';
+export type AgentAISecretFallback = 'none' | 'ancestors';
+export interface AgentAIOptions extends AIClientOptions {
+    /**
+     * Secret name to resolve for the provider API key.
+     *
+     * When omitted, the agent runtime falls back to a provider-specific default
+     * for known providers such as Gemini, OpenAI, and Anthropic.
+     */
+    apiKeySecretName?: string;
+    /**
+     * Whether to fall back to ancestor tenants when the current tenant does not
+     * define the requested secret.
+     *
+     * Defaults to `'ancestors'`.
+     */
+    apiKeySecretFallback?: AgentAISecretFallback;
+}
+interface ResolveAgentAIOptionsInput {
+    aiConfig: AgentAIOptions | undefined;
+    db: DatabaseInterface | null | undefined;
+    tenantId?: string | null;
+}
+export declare function resolveAgentAIOptions(input: ResolveAgentAIOptionsInput): Promise<AIClientOptions | undefined>;
+export {};
+//# sourceMappingURL=ai-config.d.ts.map

package/dist/ai-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-config.d.ts","sourceRoot":"","sources":["../src/ai-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAIzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,WAAW,CAAC;AAEzD,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,qBAAqB,CAAC;CAC9C;AAED,UAAU,0BAA0B;IAClC,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAC;IACrC,EAAE,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAmID,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAsCtC"}