@happyvertical/smrt-agents 0.30.0

package/AGENTS.md

@@ -0,0 +1,96 @@
+# @happyvertical/smrt-agents
+
+Agent framework for autonomous actors with inter-agent messaging, interest-based object discovery, scheduling, and multi-tenant bindings.
+
+## Agent Lifecycle
+
+`initialize()` → `validate()` → `run()` → `shutdown()`
+
+- Extend `Agent` (which extends `SmrtObject`) and implement `run()`
+- Status tracking: `idle → initializing → running → error/shutdown`
+- `execute()` runs the full lifecycle automatically
+- Process signal handling is opt-in via `manageProcessSignals: true` and is intended for single-agent processes
+
+## DispatchBus — Inter-Agent Communication
+
+Agents communicate via persistent async messaging through core's DispatchBus:
+
+```typescript
+// Emitting (in any agent)
+const bus = await this.getDispatch();
+await bus.emit('campaign.completed', { campaignId: '123' }, { source: 'Suasor' });
+
+// Subscribing (in receiving agent)
+async handleDispatch(payload: unknown, metadata: DispatchMetadata): Promise<void> {
+  if (metadata.type === 'campaign.completed') await this.recordRevenue(payload);
+}
+async run() { await this.processDispatches(); } // processes via handleDispatch()
+```
+
+CLI: `smrt dispatch:list`, `dispatch:process --subscriber Fiscus`, `dispatch:retry`, `dispatch:cleanup`
+
+## Interests — Object Discovery
+
+Agents query objects they care about via declarative filters:
+
+```typescript
+constructor(options) {
+  super({ ...options, interests: {
+    objects: { Meeting: { filter: { status: 'upcoming' }, handler: async (m) => ({ action: 'recap' }) } },
+    qualify: async (items) => items.filter(/* AI-based post-filter */),
+  }});
+}
+async run() { for (const { type, data } of await this.interesting()) { ... } }
+```
+
+## Configuration
+
+- **File-based**: `getModuleConfig('agent-name', defaults)` from `smrt.config.ts`
+- **DB-persisted**: `saveSlotConfig(slotId, data)` for UI overrides
+- **Merged**: `getMergedConfig('slotId')` — DB overrides file config
+- **UI slots**: `static uiSlots` declares admin panels (id, label, icon, order)
+
+## TenantAgent — Multi-Tenant Bindings
+
+Junction table (`tenant_agents`) binding agents to tenants with permission overrides and hierarchy resolution:
+- Explicit binding: row exists for tenant (source: 'explicit')
+- Inherited: walks up tenant hierarchy (source: 'inherited')
+- Permissions: manifest defaults merged with per-tenant overrides
+
+## AgentSchedule
+
+Cron-based scheduling stored in `_smrt_agent_schedules`. Fields: `agentType`, `cron`, `method` (default: 'run'), `maxConcurrent`, `timeout`. Executed by ScheduleRunner from smrt-jobs.
+
+## Lazy agent_config Resolution (issue #1161)
+
+Persisted `agent_config` snapshots env-derived values at sync time, so rotated env vars don't reach already-stored schedule rows. Two complementary mechanisms unfreeze them:
+
+1. **`$env` sentinels in persisted config** — register a global resolver and reference it from the JSON:
+
+   ```ts
+   import { registerConfigResolver } from '@happyvertical/smrt-agents';
+   registerConfigResolver('sharedAssetStorage', () => resolveSharedAssetStorage());
+   // persisted: { "assetStorage": { "$env": "sharedAssetStorage" } }
+   ```
+
+2. **`static configResolvers` on the agent class** — declarative, discoverable via the class itself:
+
+   ```ts
+   class Praeco extends Agent {
+     static override configResolvers = {
+       assetStorage: () => resolveSharedAssetStorage(),
+     };
+   }
+   ```
+
+The TaskRunner calls `resolveLazyConfig()` immediately before constructing the agent, so live values always win over snapshotted ones. Re-exported from `@happyvertical/smrt-core` (`resolveLazyConfig`, `registerConfigResolver`, `getClassConfigResolvers`, …) for cases where agents isn't on the import path.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/agent.ts` | Base Agent class — lifecycle, dispatch, interests, config |
+| `src/schedule.ts` | AgentSchedule model — cron, execution tracking |
+| `src/tenant-agent.ts` | TenantAgent — junction table, hierarchical resolution |
+| `src/interests.ts` | Interest filter types and configuration |
+| `src/config.ts` | File + DB config management, UI slots |

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# @happyvertical/smrt-agents
+
+Agent framework for building autonomous actors with lifecycle management, inter-agent messaging, interest-based discovery, scheduling, and multi-tenant bindings.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-agents
+```
+
+## Usage
+
+```typescript
+import { Agent, type AgentOptions } from '@happyvertical/smrt-agents';
+import { smrt } from '@happyvertical/smrt-core';
+import { getModuleConfig } from '@happyvertical/smrt-config';
+
+@smrt()
+class MyAgent extends Agent {
+  protected config = getModuleConfig('my-agent', {
+    cronSchedule: '0 2 * * *',
+    maxRetries: 3,
+  });
+
+  itemsProcessed: number = 0;
+
+  constructor(options: AgentOptions = {}) {
+    super({
+      ...options,
+      interests: {
+        objects: {
+          Meeting: { filter: { status: 'upcoming' } },
+          Document: { filter: { 'type in': ['agenda', 'minutes'] } },
+        },
+      },
+    });
+  }
+
+  async validate(): Promise<void> {
+    if (!this.config.cronSchedule) throw new Error('cronSchedule required');
+  }
+
+  async run(): Promise<void> {
+    const items = await this.interesting();
+    for (const { type, data } of items) {
+      this.logger.info(`Processing ${type}: ${data.id}`);
+    }
+    this.itemsProcessed = items.length;
+    await this.save();
+  }
+}
+
+const agent = new MyAgent({ name: 'my-agent' });
+await agent.execute(); // initialize() -> validate() -> run() -> shutdown()
+```
+
+If you are running a single-agent CLI or script and want built-in
+`SIGTERM`/`SIGINT` handling, pass `manageProcessSignals: true` to the
+constructor. Multi-agent hosts should leave that off and coordinate process
+shutdown themselves.
+
+## Scheduled Methods Vs Operator Actions
+
+Use scheduled agent methods for the regular, repeatable maintenance path: the
+work that should happen automatically every time the schedule fires. Keep those
+methods idempotent and safe to rerun.
+
+When operators need a composite catch-up or repair flow, expose that as an
+explicit method such as `forage()`, `backfill()`, or `rebuildIndex()` instead of
+overloading `run()` with manual-only behavior. Those operator actions can still
+be enqueued through `@happyvertical/smrt-jobs`, but they should remain distinct
+from the normal scheduled loop so it stays obvious which work is automatic and
+which work is an intentional intervention.
+
+## API
+
+### Main Export (`@happyvertical/smrt-agents`)
+
+| Export | Description |
+|--------|------------|
+| `Agent` | Base agent class with lifecycle and interests |
+| `AgentOptions` | Constructor options type |
+| `AgentStatusType` | Status enum: idle/initializing/running/error/shutdown |
+| `AgentConfig` | DB-persisted agent configuration model |
+| `AgentConfigCollection` | Collection for AgentConfig |
+| `AgentSchedule` | Cron-based schedule model (`_smrt_agent_schedules`) |
+| `AgentScheduleCollection` | Collection for AgentSchedule |
+| `ScheduleStatus` | Schedule status type |
+| `TenantAgent` | Agent-to-tenant junction with hierarchy resolution |
+| `TenantAgentCollection` | Collection for TenantAgent |
+| `TenantAgentStatus` | Tenant agent status type |
+| `ResolvedAgentAvailability` | Resolved availability after hierarchy walk |
+| `mergeFilters` | Combine interest filters |
+| `normalizeSort` | Normalize sort expressions |
+| `InterestOptions` | Interest configuration type |
+| `InterestFilter` | Filter definition type |
+| `InterestResult` | Discovery result type |
+| `ObjectInterestConfig` | Per-object interest config type |
+| `ObjectFilter` | Object filter type |
+| `InterestHandlerFn` | Interest handler function type |
+| `AsyncQualifierFn` | Async post-filter qualifier type |
+| `QueryFn` | Query function type |
+| `AgentWithInterestsOptions` | Agent options with interests |
+
+### UI Export (`@happyvertical/smrt-agents/ui`)
+
+| Export | Description |
+|--------|------------|
+| `AgentUIRegistry` | Singleton registry for agent admin panels |
+| `createUIRegistry` | Factory for UI registries |
+| `AgentUISlot` | UI slot definition type |
+| `AgentUISlots` | Map of UI slots |
+| `AgentAdminRoute` | Admin route metadata (path, component, load) |
+| `AgentAdminExport` | Agent admin module export shape |
+| `AgentAdminNavItem` | Navigation item for admin sidebar |
+| `AgentAdminRootProps` | Props for admin root component |
+| `AdminPanelBaseProps` | Props for admin panel components |
+| `AgentManifestInfo` | Agent manifest metadata |
+| `AgentRouteLoadContext` | Normalized SvelteKit load context |
+| `AgentRouteLoadFn` | Server load function type |
+| `AgentUIComponentRegistry` | Component registry type |
+| `ComponentType` | Generic component type |
+
+### Vite Export (`@happyvertical/smrt-agents/vite`)
+
+| Export | Description |
+|--------|------------|
+| `vitePluginAgentRoutes` | Vite plugin for `virtual:smrt-agent-registrations` |
+| `AgentRoutesPluginOptions` | Plugin options type |
+
+## Dependencies
+
+- `@happyvertical/smrt-core` -- ORM base classes
+- `@happyvertical/smrt-config` -- Configuration management
+- `@happyvertical/smrt-tenancy` -- Multi-tenant context
+- `@happyvertical/ai` -- AI client (SDK)
+- `@happyvertical/files` -- Filesystem utilities (SDK)
+- `@happyvertical/utils` -- Shared utilities (SDK)
+- Peer (optional): `@happyvertical/smrt-svelte`, `svelte`

package/dist/__smrt-register__.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=__smrt-register__.d.ts.map

package/dist/__smrt-register__.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"__smrt-register__.d.ts","sourceRoot":"","sources":["../src/__smrt-register__.ts"],"names":[],"mappings":""}