@happyvertical/smrt-agents 0.57.46 → 0.57.47

package/dist/smrt-knowledge.json

@@ -3,14 +3,15 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-agents",
-  "packageVersion": "0.57.46",
+  "packageVersion": "0.57.47",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "4cdc82528733a05d675b2ec4441919b187466ef37d60a432d3e9d567009f411d",
-    "packageJson": "8b8c47d7f2e9f4dc6f2cd231a8b96bafec8f619fa75b00d73fa01d86fa97e67b",
-    "agents": "fad20bbcbe6e9caf1aa86cc3aaf23d2e63da30f8f1c6eb663f3bee80a94b84cf",
+    "manifest": "a455b6a7d8694175b6e9dd3828c0541fb00891bb9cf26455e29ac2de069fba42",
+    "packageJson": "5266918c008dfeaa6472c263ec4ac303281d29e6d53e9a1f65ca4009ee3d5561",
+    "agents": "5986624bedc258c46270f39f8b3e1c45971218951dedac289ad9fcd70eebee64",
     "moduleDoc:agents/data-surface-discovery.md": "3ea5cfbb629258b19d4bc2c7cba333e7d30a7e149c4e46a78748524d8da17563",
+    "moduleDoc:agents/lazy-config.md": "f4bb02ee228e2cf43b4680e71a15732ed2e19eadcc38223be775f3e421fcb05c",
     "moduleDoc:agents/data-surface-denials.md": "543ec991ae6651af4677b7b29762750c75e1c200e32f1a3ce1938f982fd78116"
   },
   "exports": [
@@ -1160,6 +1161,164 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "SmrtDataSurfaceActionTask",
+      "qualifiedName": "@happyvertical/smrt-agents:SmrtDataSurfaceActionTask",
+      "collection": "smrtdatasurfaceactiontasks",
+      "tableName": "_smrt_data_surface_action_tasks",
+      "packageName": "@happyvertical/smrt-agents",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "args",
+          "type": "json",
+          "required": true,
+          "columnType": "JSON"
+        }
+      ],
+      "relationships": [],
+      "methods": [
+        "run"
+      ],
+      "methodSignatures": [
+        {
+          "name": "run",
+          "async": true,
+          "params": [
+            "args?: DataSurfaceActionJobArgs",
+            "context?: JobExecutionContext"
+          ],
+          "returns": "Promise<DataSurfaceActionResult>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "optional",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "run",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-agents:SmrtDataSurfaceActionTask"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "DataSurfaceActionTokenState",
+      "qualifiedName": "@happyvertical/smrt-agents:DataSurfaceActionTokenState",
+      "collection": "datasurfaceactiontokenstates",
+      "tableName": "_smrt_data_surface_action_tokens",
+      "packageName": "@happyvertical/smrt-agents",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tokenHash",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "record",
+          "type": "json",
+          "required": true,
+          "columnType": "JSON"
+        },
+        {
+          "name": "consumedBy",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "DataSurfaceActionIdempotencyState",
+      "qualifiedName": "@happyvertical/smrt-agents:DataSurfaceActionIdempotencyState",
+      "collection": "datasurfaceactionidempotencystates",
+      "tableName": "_smrt_data_surface_action_idempotency",
+      "packageName": "@happyvertical/smrt-agents",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "keyHash",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "requestFingerprint",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "ownerHash",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "reservedAt",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "result",
+          "type": "json",
+          "required": false,
+          "columnType": "JSON"
+        },
+        {
+          "name": "recovery",
+          "type": "json",
+          "required": false,
+          "columnType": "JSON"
+        }
+      ],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "TenantAgent",
       "qualifiedName": "@happyvertical/smrt-agents:TenantAgent",
@@ -1403,164 +1562,6 @@
       ],
       "tags": [],
       "risks": []
-    },
-    {
-      "name": "SmrtDataSurfaceActionTask",
-      "qualifiedName": "@happyvertical/smrt-agents:SmrtDataSurfaceActionTask",
-      "collection": "smrtdatasurfaceactiontasks",
-      "tableName": "_smrt_data_surface_action_tasks",
-      "packageName": "@happyvertical/smrt-agents",
-      "extends": "SmrtObject",
-      "fields": [
-        {
-          "name": "tenantId",
-          "type": "text",
-          "required": false,
-          "columnType": "UUID"
-        },
-        {
-          "name": "args",
-          "type": "json",
-          "required": true,
-          "columnType": "JSON"
-        }
-      ],
-      "relationships": [],
-      "methods": [
-        "run"
-      ],
-      "methodSignatures": [
-        {
-          "name": "run",
-          "async": true,
-          "params": [
-            "args?: DataSurfaceActionJobArgs",
-            "context?: JobExecutionContext"
-          ],
-          "returns": "Promise<DataSurfaceActionResult>"
-        }
-      ],
-      "tenant": {
-        "scoped": true,
-        "mode": "optional",
-        "field": "tenantId"
-      },
-      "conflictColumns": [
-        "tenant_id",
-        "slug",
-        "context"
-      ],
-      "surfaces": [],
-      "withheldSurfaces": [
-        {
-          "kind": "api",
-          "operation": "run",
-          "code": "api-disabled",
-          "reason": "api is disabled",
-          "objectName": "@happyvertical/smrt-agents:SmrtDataSurfaceActionTask"
-        }
-      ],
-      "relationshipFeatures": [
-        "uuidColumns"
-      ],
-      "tags": [],
-      "risks": []
-    },
-    {
-      "name": "DataSurfaceActionTokenState",
-      "qualifiedName": "@happyvertical/smrt-agents:DataSurfaceActionTokenState",
-      "collection": "datasurfaceactiontokenstates",
-      "tableName": "_smrt_data_surface_action_tokens",
-      "packageName": "@happyvertical/smrt-agents",
-      "extends": "SmrtObject",
-      "fields": [
-        {
-          "name": "tokenHash",
-          "type": "text",
-          "required": true,
-          "columnType": "TEXT"
-        },
-        {
-          "name": "record",
-          "type": "json",
-          "required": true,
-          "columnType": "JSON"
-        },
-        {
-          "name": "consumedBy",
-          "type": "text",
-          "required": false,
-          "columnType": "TEXT"
-        }
-      ],
-      "relationships": [],
-      "methods": [],
-      "surfaces": [],
-      "relationshipFeatures": [
-        "uuidColumns"
-      ],
-      "tags": [],
-      "risks": []
-    },
-    {
-      "name": "DataSurfaceActionIdempotencyState",
-      "qualifiedName": "@happyvertical/smrt-agents:DataSurfaceActionIdempotencyState",
-      "collection": "datasurfaceactionidempotencystates",
-      "tableName": "_smrt_data_surface_action_idempotency",
-      "packageName": "@happyvertical/smrt-agents",
-      "extends": "SmrtObject",
-      "fields": [
-        {
-          "name": "keyHash",
-          "type": "text",
-          "required": true,
-          "columnType": "TEXT"
-        },
-        {
-          "name": "status",
-          "type": "text",
-          "required": true,
-          "columnType": "TEXT"
-        },
-        {
-          "name": "requestFingerprint",
-          "type": "text",
-          "required": true,
-          "columnType": "TEXT"
-        },
-        {
-          "name": "ownerHash",
-          "type": "text",
-          "required": false,
-          "columnType": "TEXT"
-        },
-        {
-          "name": "reservedAt",
-          "type": "text",
-          "required": false,
-          "columnType": "TEXT"
-        },
-        {
-          "name": "result",
-          "type": "json",
-          "required": false,
-          "columnType": "JSON"
-        },
-        {
-          "name": "recovery",
-          "type": "json",
-          "required": false,
-          "columnType": "JSON"
-        }
-      ],
-      "relationships": [],
-      "methods": [],
-      "surfaces": [],
-      "relationshipFeatures": [
-        "uuidColumns"
-      ],
-      "tags": [],
-      "risks": []
     }
   ],
   "surfaces": [
@@ -1856,13 +1857,18 @@
     "polymorphicAssociations": 0,
     "uuidColumns": 18
   },
-  "agentDoc": "# @happyvertical/smrt-agents\n\nAgent framework for autonomous actors with inter-agent messaging, interest-based object discovery, scheduling, and multi-tenant bindings.\n\n## Modules\n\n| Module | Contract |\n| --- | --- |\n| [Data-surface discovery](agents/data-surface-discovery.md) | Summary discovery, row-count hints, allowed values, `id`/request aliases |\n\n## Agent Lifecycle\n\n`initialize()` → `validate()` → `run()` → `shutdown()`\n\n- Extend `Agent` (which extends `SmrtObject`) and implement `run()`\n- Status tracking: `idle → initializing → running → error/shutdown`\n- `execute()` runs the full lifecycle automatically\n- Process signal handling is opt-in via `manageProcessSignals: true` and is intended for single-agent processes\n\n## DispatchBus — Inter-Agent Communication\n\nAgents communicate via persistent async messaging through core's DispatchBus:\n\n```typescript\n// Emitting (in any agent)\nconst bus = await this.getDispatch();\nawait bus.emit('campaign.completed', { campaignId: '123' }, { source: 'Suasor' });\n\n// Subscribing (in receiving agent)\nasync handleDispatch(payload: unknown, metadata: DispatchMetadata): Promise<void> {\n  if (metadata.type === 'campaign.completed') await this.recordRevenue(payload);\n}\nasync run() { await this.processDispatches(); } // processes via handleDispatch()\n```\n\nCLI: `smrt dispatch:list`, `dispatch:process --subscriber Fiscus`, `dispatch:retry`, `dispatch:cleanup`\n\n## Interests — Object Discovery\n\nAgents query objects they care about via declarative filters:\n\n```typescript\nconstructor(options) {\n  super({ ...options, interests: {\n    objects: { Meeting: { filter: { status: 'upcoming' }, handler: async (m) => ({ action: 'recap' }) } },\n    qualify: async (items) => items.filter(/* AI-based post-filter */),\n  }});\n}\nasync run() { for (const { type, data } of await this.interesting()) { ... } }\n```\n\n## Configuration\n\n- **File-based**: `getModuleConfig('agent-name', defaults)` from `smrt.config.ts`\n- **DB-persisted**: `saveSlotConfig(slotId, data)` for UI overrides. Persona-backed\n  agents use `AgentOptions.personaId` as the durable config owner; legacy agents\n  use the saved Agent row id.\n- **Merged**: `getMergedConfig('slotId')` — DB overrides file config\n- **UI slots**: `static uiSlots` declares admin panels (id, label, icon, order,\n  `scope`, optional versioned `settingsSchema`). Without a registered custom\n  component, `AgentSettingsForm` renders that schema.\n\n## TenantAgent — Multi-Tenant Bindings\n\nJunction table (`tenant_agents`) binding agents to tenants with permission overrides and hierarchy resolution:\n- Explicit binding: row exists for tenant (source: 'explicit')\n- Inherited: walks up tenant hierarchy (source: 'inherited')\n- Permissions: manifest defaults merged with per-tenant overrides\n\n### Config owner id and the #1092 key repair\n\nA binding with no Agent row owns slot configs under\n`tenantAgentConfigOwnerId(tenantId, type)` = `<tenant>:<canonical type>`\n(`serializeResolvedAgent()` uses it). Seeders and schedule sync must compose it\nwith the helper. Rows keyed `<tenant>:<Class>` (pre-#1092) or bindings under a\nbare/renamed type are moved by `repairTenantAgentConfigKeys(db, { aliases,\napply })` (`src/migrations/tenant-agent-config-keys.ts`): dry run by default,\ncounted totals, blocked rows (two spellings of one binding/slot) refuse the\napply, one transaction with a ledger and a post-check; idempotent. Register the\nhost's agent classes (or pass `aliases`) before running it.\n\n## Create entries\n\n`static createEntries: AgentCreateEntry[]` (literal array; the scanner captures\nit into `agent.createEntries`) lets an agent contribute \"create\" options: `id`,\n`type`, `format`, `label`, `description`, `icon`, `route` (relative to the\nhost base path), `order`, `availability` (`permission`, `accessLevels`,\n`requires`). `SerializedAgent.createEntries` carries them;\n`resolveAgentCreateEntries(agents, { basePath, accessLevel, capabilities })`\nfrom `./ui` filters, builds `href`, and sorts. Non-relative routes are dropped.\n\n## AgentSchedule\n\nCron-based scheduling stored in `_smrt_agent_schedules`. Fields: `agentType`, `cron`, `timezone` (IANA, default `UTC`; blank → `UTC`), `method` (default: 'run'), `maxConcurrent`, `timeout`. Executed by ScheduleRunner from smrt-jobs. `calculateNextRun()` and the runner re-arm share smrt-jobs' `getNextCronDate(cron, timezone)`, so both evaluate the cron in the row's zone, DST-correct (#3859); an unknown zone sets `status: 'error'` with the parser message in `lastError`.\n\n## Lazy agent_config Resolution (issue #1161)\n\nPersisted `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:\n\n1. **`$env` sentinels in persisted config** — register a global resolver and reference it from the JSON:\n\n   ```ts\n   import { registerConfigResolver } from '@happyvertical/smrt-agents';\n   registerConfigResolver('sharedAssetStorage', () => resolveSharedAssetStorage());\n   // persisted: { \"assetStorage\": { \"$env\": \"sharedAssetStorage\" } }\n   ```\n\n2. **`static configResolvers` on the agent class** — declarative, discoverable via the class itself:\n\n   ```ts\n   class Praeco extends Agent {\n     static override configResolvers = {\n       assetStorage: () => resolveSharedAssetStorage(),\n     };\n   }\n   ```\n\nThe 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.\n\n## Learning Trait (issue #1886) — opt-in\n\nAny agent can opt into a confidence-scored **recall-before / capture-after** loop backed by core's `LearningMemory` (over `_smrt_contexts` + `_smrt_embeddings`). **Off by default** — a non-opted agent behaves byte-for-byte as today; the lifecycle's learning branches are never entered.\n\n```typescript\n@smrt()\nclass InvoiceAgent extends Agent {\n  static override learning = true; // or { minConfidence: 0.8, scope: 'invoices', ... }\n  protected config = {};\n\n  async run() {\n    // recall-before-run already populated `recalledMemories` (confidence >= floor)\n    const cached = this.recalledMemories.find((m) => m.key === this.docUrl);\n    const strategy = cached?.value ?? (await this.generateStrategy());\n\n    // stage the episode; the lifecycle reinforces it after run()\n    this.stageLearning({ scope: this.learningScope(), key: this.docUrl, value: strategy });\n\n    // a validated failure decays the memory without throwing\n    if (!ok) this.reportLearningOutcome({ success: false, error: 'no match' });\n  }\n}\n```\n\n- **`capture` semantics** (`LearningMemory`): success strengthens `confidence` toward 1.0 and increments `success_count`; failure decays toward `failureConfidence` (0.3) and increments `failure_count`. A single failure drops a confident memory below the reuse floor (0.7), so recall stops returning it. Refreshes `last_used_at`; honours `expires_at` and optional time-decay.\n- **Memory isolation**: bound to `(agentType, agentInstanceId)` as `(owner_class, owner_id)`, so two tenants on the same agent class never share memory. `tenantId` is threaded into the optional semantic-search `where`.\n- **Seams to override**: `learningScope()`, `recallForRun(memory)`, `captureForRun(memory, outcome)`, `getLearningSemanticSearch()`. Helpers for `run()`: `stageLearning(episode)`, `reportLearningOutcome(outcome)`, `getLearningMemory()`, and the `recalledMemories` field.\n- **Config**: `static learning: boolean | AgentLearningConfig` — `{ enabled?, scope?, minConfidence?, successConfidence?, failureConfidence?, reinforcement?, decayHalfLifeMs? }`. `LearningMemory` and its types are re-exported from `@happyvertical/smrt-core`.\n\n## Multi-Instance Agents (issue #1890) — opt-in\n\n`static multiInstance = false` by default: a class is a **singleton** (the N=1 case) and is byte-for-byte unchanged — one dispatch subscriber keyed by the agent type, one memory scope, class-wide interests. Set `static multiInstance = true` to run N durable instances (personas, from `@happyvertical/smrt-personas`) of one class per tenant, each independent.\n\nThe framework provides only the per-instance **identity**; a package scopes its own dispatch/interests to the instance's config by overriding the seams.\n\n- **`AgentOptions.personaId`** — durable persona/settings identity, including\n  the default persona. Independent from execution instance identity.\n- **`AgentOptions.instanceKey`** — the durable execution-instance key (typically\n  the persona id, but null for the default persona). Honored **only** when\n  `multiInstance` is true, so passing it to a non-opted agent is a no-op.\n- **`getInstanceKey()`** → the key, or `null` for a singleton (opt-in off, or no key).\n- **`getDispatchSubscriber()`** → `` `${agentType}#${key}` `` for a multi-instance agent, the bare `agentType` for a singleton. Used everywhere the agent subscribes/seeds/processes, so each instance has its own subscription rows and pending-dispatch queue — two instances never compete for or double-process each other's dispatches. Composed by the exported `instanceScopedSubscriber(agentType, key)`.\n- **`learningScope()`** — suffixed with `#<key>` for a multi-instance agent, so instances learn independently (singleton scope unchanged).\n- **Seams to override** (both default to singleton behavior):\n  - `resolveSignalSubscriptions()` — derive **instance-scoped** signal types from the instance config so an emit meant for one instance only matches its subscription.\n  - `instanceInterestFilter()` — an `ObjectFilter` AND-merged (as the base layer) into every `interesting()` query so instances partition the objects they process.\n\nThe **`default` persona reuses the singleton identity** (a `null` key), which is what makes the singleton→multi upgrade non-destructive — see `@happyvertical/smrt-personas` (`personaInstanceKey`, `upgradeSingletonToDefaultPersona`).\n\n## Principal Execution (issue #1888)\n\n`executeAsPrincipal(options, fn)` runs agent work **AS a persona's bound user**, reusing the existing RBAC cascade: permissions resolve live unless the caller passes an explicit `permissions` snapshot, which the run then carries as `run.permissionSnapshot`. `agents.invoke` propagates that snapshot as the `DelegationEnvelope.permissions` ceiling, and `executeDelegatedInvocation` runs the worker with ceiling ∩ live grants, so a narrowed run cannot widen through delegation and a tampered persisted ceiling cannot exceed live RBAC (#2978). It publishes `(user_id, tenant_id, permissions[])` onto the DB session (Postgres RLS then bounds every query per-`(table, action)` and per-tenant) and hands `fn` a `PrincipalRun` whose `assertToolAllowed()` / `assertOperation()` enforce the persona tool ceiling and the RLS-off catalog gate. Effective authority = **bound-user RBAC ∩ agent-class ceiling ∩ persona `allowedTools`**. Actions audit as on-behalf-of the originating user via a `PrincipalAuditSink`.\n\n## Data Surface Read Tools (issue #2447)\n\n`createDataSurfaceTools()` produces the `data.discover`, `data.inspect`, and\n`data.query` `PrincipalTool`s consumed through chat's `extraTools` seam. The\ncaller supplies a server-owned surface catalog and executor; the tools copy\n`userId`, `tenantId`, database, and permissions only from the live\n`PrincipalRun`. Discovery and inspection first assert the collection's read\ncatalog permission and omit denied surfaces/fields. Query requests and results\nare normalized with the core bounded data-query protocol, including projection,\ncursor/page, row/byte, fingerprint, freshness, total, and truncation rules.\nSensitive/read-permission fields are removed from descriptors, and\n`DataSurfaceField` policy metadata is stripped before the core schema validator.\nExecutor-provided paginated rows retain their order and are validated with a\nstable identity tie-breaker (including type-aware numeric/date comparisons),\nwhile internal sort keys are stripped when they were not requested in the\nprojection. Execution has a bounded deadline; public executor/result failures\nuse stable generic errors while optional `onFailure` telemetry receives the\nauthenticated/delegated principal and detailed server-side error. Hidden field\nrequest failures also use a stable public error. Tool arguments never contain\nprincipal or tenant authority. `data.query` takes `{surfaceId, request}` or the\nflat form; a key beside `request` (a misplaced `filter`) is a 400\n`DataSurfaceRequestError` (`DATA_QUERY_ARGUMENTS_UNEXPECTED`), never silently\ndropped (#4378). A `surfaceId` nested in `request` (or a `query` wrapper) is\nlifted; two different ids are `DATA_QUERY_SURFACE_ID_CONFLICT`, none is\n`DATA_QUERY_SURFACE_ID_REQUIRED` (400s, not denials). Every request error ends with a one-line valid example for\nthe surface (placeholders only, no caller values).\nNull tests (#4448): the SMRT collection adapter (and content's mirror) adds\n`isNull`/`isNotNull` to a field's `filterOperators` when its manifest column is\nneither `notNull` nor the primary key (`nullableColumnFieldIds`,\n`NULL_TEST_FILTER_OPERATORS`), lowered to `{ field: null }` / `{ 'field !=':\nnull }`; JSON fields stay unfilterable, and a null test on a UUID column skips\nthe id-value check. A rejected filter that looks like a null test on a field\ndeclaring `isNull` (`eq`/`ne` with `null`, `\"null\"`, `\"\"` or `[]`; a `not` naming\n`field`; an `exists`-style kind/operator) gets a hint naming `isNull`/\n`isNotNull` with that field, and the valid example uses it; polarity follows\n`ne` and enclosing `not`s. Grammar: [core data-query](../core/agents/data-query.md#null-tests-4448).\nRefusals (#4387: action-specific denials, the `{ action }` catalog argument,\n`onDenied`, audit `denied` entries, missing executors):\n[agents/data-surface-denials.md](agents/data-surface-denials.md).\n\n\n## Playbook Preflight (issue #2590)\n\n`createPlaybookPreflightTool()` produces the `playbooks.preflight`\n`PrincipalTool`. It resolves a playbook through the caller's own layer chain on\nthe `server` plane and reports a per-step verdict from the two predicates\n`PrincipalRun` already exposes — `isToolAllowed(tool)` and `assertOperation`\n(which evaluates the catalog permission without performing the operation). It\nexecutes nothing.\n\n**Advisory only: preflight predicts, it never grants.** Name gates entry;\ndecomposition gates every step. Preflight computes that intersection ahead of\ntime and replaces neither gate, so a permission revoked between the prediction\nand the execution still denies at execution — proven in\n`playbook-preflight.test.ts`, which lets a cached `allow` stand and shows\n`assertOperation` refusing anyway.\n\n- Step → gating tool slug and permission collection are seams (`toolSlug`,\n  `collection`), defaulting to the registered collection slug for the step's\n  qualified model (`playbookStepToolSlug` / `playbookStepCollection`).\n- The cache partition key comes from the **live run context**, never the tool\n  arguments, so one principal's prediction can never be served to another.\n- An unknown key and an unauthorized key return the same uniform unavailable\n  report — the tool is not an enumeration oracle.\n- `filterPlaybooksByPreflight()` hides playbooks a caller could not run from a\n  listing. It is a listing convenience and **never** load-bearing for\n  authorization; a key it lets through is still authorized step by step.\n\n## Report Data-Surface Tools (issue #2462)\n\n`createReportDataSurfaceTools()` maps server-owned report definitions into the\ngeneric `data.discover`, `data.inspect`, and `data.query` catalog, and adds\nprincipal-bound `reports.query`, `reports.refresh`, `reports.drilldown`, and\n`reports.export` tools. It reuses the reports package's materialized-query,\nlifecycle, drilldown, and snapshot contracts rather than reimplementing them.\nReport ids, collections, query seams, browser delivery, background queues, and\naction hosts come only from the configured server catalog; tool arguments never\ncarry principal, tenant, or report-constructor authority.\n\n- Generic discovery excludes sensitive and permission-gated report columns.\n- Discovered report fields retain safe `kind`, `filterScope`, and capability\n  metadata, while the surface reports its available actions and lifecycle\n  freshness support. Actions are filtered by the current tool allow-list and\n  effective permissions. This lets agents distinguish dimensions/buckets\n  (`where`) from measures (`having`) without exposing hidden columns or\n  authority.\n- Silent reads do not change browser state; visible reads require a host-bound\n  acknowledgement whose post-command revision is not older than the requested\n  compare-and-swap revision; background requests contain no principal or tenant\n  payload.\n- Read results request the tenant-safe report lifecycle whenever an\n  authenticated database is available, so `freshness` and the redacted\n  lifecycle state cover stale and lock-skipped materializations.\n- Refresh and export use app-owned action hosts for live authorization and\n  auditing. Export captures an opaque immutable snapshot and preserves the\n  reports package's preview/confirmation protocol.\n- Drilldown re-reads a single accessible materialized row before it builds the\n  inherited source query, so callers cannot inject row values from another\n  tenant.\n\n## Agent Orchestration (issue #1892) — invoke-agent + principal delegation\n\nA conversational (orchestrator) agent can invoke worker agents with **principal delegation**. This is *not* a new engine — it is a standard `invoke-agent` tool plus a completion-dispatch convention on top of `executeAsPrincipal` + the DispatchBus.\n\n```typescript\nimport { createInvokeAgentTool, rootDelegationEnvelope } from '@happyvertical/smrt-agents';\n\nconst tool = createInvokeAgentTool({\n  db,\n  parentEnvelope: rootDelegationEnvelope({ runAsUserId, tenantId, onBehalfOfUserId }),\n  worker: async ({ run, agentClass, task }) => runWorker(run, agentClass, task),\n});\n// Offered through the chat tool loop as an `extraTools` entry, gated by the\n// persona's allowedTools like any other tool (slug: 'agents.invoke').\n```\n\n- **`DelegationEnvelope`** carries the **immutable principal** (`runAsUserId` + `tenantId` + originating `onBehalfOfUserId`) and a bounded `depth`. `deriveDelegationEnvelope()` copies the principal verbatim and asserts `depth <= MAX_DELEGATION_DEPTH` (3) — a worker cannot invoke a further worker under a broader principal (`PrincipalWideningError` / `DelegationDepthExceededError`).\n- **`createInvokeAgentTool()`** → a `PrincipalTool` whose handler derives the child envelope with the principal taken **from the live run context, never the tool args**, so the invoke-agent tool is structurally immune to principal widening.\n- **`executeDelegatedInvocation()`** runs the worker via `executeAsPrincipal` under that same principal and emits a correlated `agent.completed` dispatch; **`surfaceAgentCompletions(bus, correlationId)`** reads it back into the conversation.\n- **Transports** (pluggable): the default `inlineInvokeAgentTransport` runs the worker in-process (completion surfaces in the same turn); `createDispatchInvokeTransport(bus)` emits an `agent.invoke` signal a worker processes via `processAgentInvocations()` (async). A job-queue transport (enqueue on the `agents` queue) is a consumer-supplied `InvokeAgentTransport` — orchestration never hard-depends on `@happyvertical/smrt-jobs`, which sits *below* agents in the dependency graph.\n\n## Server Entry Points Stay Svelte-Free (issue #2924)\n\n`SmrtDataSurfaceActionTask`, `DataSurfaceActionTokenState`, and\n`DataSurfaceActionIdempotencyState` stamp `@happyvertical/smrt-agents/server`\nas their manifest `importPath`, so core's consumer plugin emits that specifier\nverbatim into a consumer's generated `.smrt/register.js` — which the `smrt` CLI\nloads with a bare `import()` under plain Node for `db:migrate`. **No module\nreachable from `./server` (or from the package root, or `./vite`) may import a\nSvelte component barrel.** A Vite build of the same graph succeeds, so this\nregresses silently and then breaks `db:migrate` for every object in the\nconsuming app, not just this package's.\n\n- Import shared data-surface protocol limits from the Svelte-free\n  `@happyvertical/smrt-ui/data-surface`, never `@happyvertical/smrt-ui/data`\n  (a component barrel that re-exports `.svelte` files).\n- `src/server/__tests__/node-entry-loadability.integration.test.ts` imports\n  every server-side subpath in a fresh plain-Node process; it needs a built\n  `dist/` (turbo's `test` task supplies it).\n- `scripts/verify-manifest-exports.mjs` fails a publish when any **non-root**\n  manifest `importPath` is unloadable under plain Node. A bundler-only *root*\n  barrel is still only a warning.\n\n## Key Files\n\n| File | Purpose |\n|------|---------|\n| `src/agent.ts` | Base Agent class — lifecycle, dispatch, interests, config, opt-in learning trait, multi-instance identity |\n| `src/execute-as-principal.ts` | `executeAsPrincipal` / `PrincipalRun` — run agent work as a persona's bound user (#1888) |\n| `src/report-data-surface.ts` | Principal-bound report discovery, query, lifecycle, drilldown, and export tools (#2462) |\n| `src/smrt-collection-data-surface.ts` | `createSmrtCollectionDataSurfaceDefinition()` — generic registry-driven `SmrtObject` collection to `DataSurfaceDefinition` adapter, with field-policy redaction (schema overrides included), class-aware tenant scope, DNF filter/scope lowering, deny-all short-circuit, query-bound opaque cursors, and offset/cursor paging; hydrated row values are serialized to JSON scalars at the adapter boundary — a `Date`/date-only/zoneless-UTC `datetime` becomes an ISO-8601 UTC instant, a `bigint` a safe number, and a non-scalar value on a scalar descriptor its JSON string — so a populated datetime column no longer fails the whole result; callers must keep `maxPageLimit` <= the collection's own row-limit cap (#2905, follow-up #2912, #2933) |\n| `src/delegation.ts` | `DelegationEnvelope` — immutable principal + bounded delegation depth (#1892) |\n| `src/invoke-agent.ts` | `invoke-agent` tool, worker executor, completion-dispatch convention, transports (#1892) |\n| `src/playbook-preflight.ts` | `playbooks.preflight` PrincipalTool — advisory per-step verdicts, never a grant (#2590) |\n| `src/learning.ts` | `AgentLearningConfig` + `resolveAgentLearning()` declaration normalisation |\n| `src/schedule.ts` | AgentSchedule model — cron, execution tracking |\n| `src/tenant-agent.ts` | TenantAgent — junction table, hierarchical resolution |\n| `src/interests.ts` | Interest filter types and configuration |\n| `src/config.ts` | File + DB config management, UI slots |\n",
+  "agentDoc": "# @happyvertical/smrt-agents\n\nAgent framework for autonomous actors with inter-agent messaging, interest-based object discovery, scheduling, and multi-tenant bindings.\n\n## Modules\n\n| Module | Contract |\n| --- | --- |\n| [Data-surface discovery](agents/data-surface-discovery.md) | Summary discovery, row-count hints, allowed values, `id`/request aliases |\n| [Lazy agent_config](agents/lazy-config.md) | `$env` sentinels, class `configResolvers`, resolver context and precedence (#1161, #2806) |\n\n## Agent Lifecycle\n\n`initialize()` → `validate()` → `run()` → `shutdown()`\n\n- Extend `Agent` (which extends `SmrtObject`) and implement `run()`\n- Status tracking: `idle → initializing → running → error/shutdown`\n- `execute()` runs the full lifecycle automatically\n- Process signal handling is opt-in via `manageProcessSignals: true` and is intended for single-agent processes\n\n## DispatchBus — Inter-Agent Communication\n\nAgents communicate via persistent async messaging through core's DispatchBus:\n\n```typescript\n// Emitting (in any agent)\nconst bus = await this.getDispatch();\nawait bus.emit('campaign.completed', { campaignId: '123' }, { source: 'Suasor' });\n\n// Subscribing (in receiving agent)\nasync handleDispatch(payload: unknown, metadata: DispatchMetadata): Promise<void> {\n  if (metadata.type === 'campaign.completed') await this.recordRevenue(payload);\n}\nasync run() { await this.processDispatches(); } // processes via handleDispatch()\n```\n\nCLI: `smrt dispatch:list`, `dispatch:process --subscriber Fiscus`, `dispatch:retry`, `dispatch:cleanup`\n\n## Interests — Object Discovery\n\nAgents query objects they care about via declarative filters:\n\n```typescript\nconstructor(options) {\n  super({ ...options, interests: {\n    objects: { Meeting: { filter: { status: 'upcoming' }, handler: async (m) => ({ action: 'recap' }) } },\n    qualify: async (items) => items.filter(/* AI-based post-filter */),\n  }});\n}\nasync run() { for (const { type, data } of await this.interesting()) { ... } }\n```\n\n## Configuration\n\n- **File-based**: `getModuleConfig('agent-name', defaults)` from `smrt.config.ts`\n- **DB-persisted**: `saveSlotConfig(slotId, data)` for UI overrides. Persona-backed\n  agents use `AgentOptions.personaId` as the durable config owner; legacy agents\n  use the saved Agent row id.\n- **Merged**: `getMergedConfig('slotId')` — DB overrides file config\n- **UI slots**: `static uiSlots` declares admin panels (id, label, icon, order,\n  `scope`, optional versioned `settingsSchema`). Without a registered custom\n  component, `AgentSettingsForm` renders that schema.\n\n## TenantAgent — Multi-Tenant Bindings\n\nJunction table (`tenant_agents`) binding agents to tenants with permission overrides and hierarchy resolution:\n- Explicit binding: row exists for tenant (source: 'explicit')\n- Inherited: walks up tenant hierarchy (source: 'inherited')\n- Permissions: manifest defaults merged with per-tenant overrides\n\n### Config owner id and the #1092 key repair\n\nA binding with no Agent row owns slot configs under\n`tenantAgentConfigOwnerId(tenantId, type)` = `<tenant>:<canonical type>`\n(`serializeResolvedAgent()` uses it). Seeders and schedule sync must compose it\nwith the helper. Rows keyed `<tenant>:<Class>` (pre-#1092) or bindings under a\nbare/renamed type are moved by `repairTenantAgentConfigKeys(db, { aliases,\napply })` (`src/migrations/tenant-agent-config-keys.ts`): dry run by default,\ncounted totals, blocked rows (two spellings of one binding/slot) refuse the\napply, one transaction with a ledger and a post-check; idempotent. Register the\nhost's agent classes (or pass `aliases`) before running it.\n\n## Create entries\n\n`static createEntries: AgentCreateEntry[]` (literal array; the scanner captures\nit into `agent.createEntries`) lets an agent contribute \"create\" options: `id`,\n`type`, `format`, `label`, `description`, `icon`, `route` (relative to the\nhost base path), `order`, `availability` (`permission`, `accessLevels`,\n`requires`). `SerializedAgent.createEntries` carries them;\n`resolveAgentCreateEntries(agents, { basePath, accessLevel, capabilities })`\nfrom `./ui` filters, builds `href`, and sorts. Non-relative routes are dropped.\n\n## AgentSchedule\n\nCron-based scheduling stored in `_smrt_agent_schedules`. Fields: `agentType`, `cron`, `timezone` (IANA, default `UTC`; blank → `UTC`), `method` (default: 'run'), `maxConcurrent`, `timeout`. Executed by ScheduleRunner from smrt-jobs. `calculateNextRun()` and the runner re-arm share smrt-jobs' `getNextCronDate(cron, timezone)`, so both evaluate the cron in the row's zone, DST-correct (#3859); an unknown zone sets `status: 'error'` with the parser message in `lastError`.\n\n## Lazy agent_config Resolution (issue #1161)\n\n`$env` sentinels and `static configResolvers` re-resolve persisted `agent_config` at execute time. Resolvers receive the instance's identity and its own persisted value (#2806). Keep a per-agent credential with `preferPersisted()`, and never select an agent by scanning the tenant's rows. See [agents/lazy-config.md](agents/lazy-config.md).\n\n## Learning Trait (issue #1886) — opt-in\n\nAny agent can opt into a confidence-scored **recall-before / capture-after** loop backed by core's `LearningMemory` (over `_smrt_contexts` + `_smrt_embeddings`). **Off by default** — a non-opted agent behaves byte-for-byte as today; the lifecycle's learning branches are never entered.\n\n```typescript\n@smrt()\nclass InvoiceAgent extends Agent {\n  static override learning = true; // or { minConfidence: 0.8, scope: 'invoices', ... }\n  protected config = {};\n\n  async run() {\n    // recall-before-run already populated `recalledMemories` (confidence >= floor)\n    const cached = this.recalledMemories.find((m) => m.key === this.docUrl);\n    const strategy = cached?.value ?? (await this.generateStrategy());\n\n    // stage the episode; the lifecycle reinforces it after run()\n    this.stageLearning({ scope: this.learningScope(), key: this.docUrl, value: strategy });\n\n    // a validated failure decays the memory without throwing\n    if (!ok) this.reportLearningOutcome({ success: false, error: 'no match' });\n  }\n}\n```\n\n- **`capture` semantics** (`LearningMemory`): success strengthens `confidence` toward 1.0 and increments `success_count`; failure decays toward `failureConfidence` (0.3) and increments `failure_count`. A single failure drops a confident memory below the reuse floor (0.7), so recall stops returning it. Refreshes `last_used_at`; honours `expires_at` and optional time-decay.\n- **Memory isolation**: bound to `(agentType, agentInstanceId)` as `(owner_class, owner_id)`, so two tenants on the same agent class never share memory. `tenantId` is threaded into the optional semantic-search `where`.\n- **Seams to override**: `learningScope()`, `recallForRun(memory)`, `captureForRun(memory, outcome)`, `getLearningSemanticSearch()`. Helpers for `run()`: `stageLearning(episode)`, `reportLearningOutcome(outcome)`, `getLearningMemory()`, and the `recalledMemories` field.\n- **Config**: `static learning: boolean | AgentLearningConfig` — `{ enabled?, scope?, minConfidence?, successConfidence?, failureConfidence?, reinforcement?, decayHalfLifeMs? }`. `LearningMemory` and its types are re-exported from `@happyvertical/smrt-core`.\n\n## Multi-Instance Agents (issue #1890) — opt-in\n\n`static multiInstance = false` by default: a class is a **singleton** (the N=1 case) and is byte-for-byte unchanged — one dispatch subscriber keyed by the agent type, one memory scope, class-wide interests. Set `static multiInstance = true` to run N durable instances (personas, from `@happyvertical/smrt-personas`) of one class per tenant, each independent.\n\nThe framework provides only the per-instance **identity**; a package scopes its own dispatch/interests to the instance's config by overriding the seams.\n\n- **`AgentOptions.personaId`** — durable persona/settings identity, including\n  the default persona. Independent from execution instance identity.\n- **`AgentOptions.instanceKey`** — the durable execution-instance key (typically\n  the persona id, but null for the default persona). Honored **only** when\n  `multiInstance` is true, so passing it to a non-opted agent is a no-op.\n- **`getInstanceKey()`** → the key, or `null` for a singleton (opt-in off, or no key).\n- **`getDispatchSubscriber()`** → `` `${agentType}#${key}` `` for a multi-instance agent, the bare `agentType` for a singleton. Used everywhere the agent subscribes/seeds/processes, so each instance has its own subscription rows and pending-dispatch queue — two instances never compete for or double-process each other's dispatches. Composed by the exported `instanceScopedSubscriber(agentType, key)`.\n- **`learningScope()`** — suffixed with `#<key>` for a multi-instance agent, so instances learn independently (singleton scope unchanged).\n- **Seams to override** (both default to singleton behavior):\n  - `resolveSignalSubscriptions()` — derive **instance-scoped** signal types from the instance config so an emit meant for one instance only matches its subscription.\n  - `instanceInterestFilter()` — an `ObjectFilter` AND-merged (as the base layer) into every `interesting()` query so instances partition the objects they process.\n\nThe **`default` persona reuses the singleton identity** (a `null` key), which is what makes the singleton→multi upgrade non-destructive — see `@happyvertical/smrt-personas` (`personaInstanceKey`, `upgradeSingletonToDefaultPersona`).\n\n## Principal Execution (issue #1888)\n\n`executeAsPrincipal(options, fn)` runs agent work **AS a persona's bound user**, reusing the existing RBAC cascade: permissions resolve live unless the caller passes an explicit `permissions` snapshot, which the run then carries as `run.permissionSnapshot`. `agents.invoke` propagates that snapshot as the `DelegationEnvelope.permissions` ceiling, and `executeDelegatedInvocation` runs the worker with ceiling ∩ live grants, so a narrowed run cannot widen through delegation and a tampered persisted ceiling cannot exceed live RBAC (#2978). It publishes `(user_id, tenant_id, permissions[])` onto the DB session (Postgres RLS then bounds every query per-`(table, action)` and per-tenant) and hands `fn` a `PrincipalRun` whose `assertToolAllowed()` / `assertOperation()` enforce the persona tool ceiling and the RLS-off catalog gate. Effective authority = **bound-user RBAC ∩ agent-class ceiling ∩ persona `allowedTools`**. Actions audit as on-behalf-of the originating user via a `PrincipalAuditSink`.\n\n## Data Surface Read Tools (issue #2447)\n\n`createDataSurfaceTools()` produces the `data.discover`, `data.inspect`, and\n`data.query` `PrincipalTool`s consumed through chat's `extraTools` seam. The\ncaller supplies a server-owned surface catalog and executor; the tools copy\n`userId`, `tenantId`, database, and permissions only from the live\n`PrincipalRun`. Discovery and inspection first assert the collection's read\ncatalog permission and omit denied surfaces/fields. Query requests and results\nare normalized with the core bounded data-query protocol, including projection,\ncursor/page, row/byte, fingerprint, freshness, total, and truncation rules.\nSensitive/read-permission fields are removed from descriptors, and\n`DataSurfaceField` policy metadata is stripped before the core schema validator.\nExecutor-provided paginated rows retain their order and are validated with a\nstable identity tie-breaker (including type-aware numeric/date comparisons),\nwhile internal sort keys are stripped when they were not requested in the\nprojection. Execution has a bounded deadline; public executor/result failures\nuse stable generic errors while optional `onFailure` telemetry receives the\nauthenticated/delegated principal and detailed server-side error. Hidden field\nrequest failures also use a stable public error. Tool arguments never contain\nprincipal or tenant authority. `data.query` takes `{surfaceId, request}` or the\nflat form; a key beside `request` (a misplaced `filter`) is a 400\n`DataSurfaceRequestError` (`DATA_QUERY_ARGUMENTS_UNEXPECTED`), never silently\ndropped (#4378). A `surfaceId` nested in `request` (or a `query` wrapper) is\nlifted; two different ids are `DATA_QUERY_SURFACE_ID_CONFLICT`, none is\n`DATA_QUERY_SURFACE_ID_REQUIRED` (400s, not denials). Every request error ends with a one-line valid example for\nthe surface (placeholders only, no caller values).\nNull tests (#4448): the SMRT collection adapter (and content's mirror) adds\n`isNull`/`isNotNull` to a field's `filterOperators` when its manifest column is\nneither `notNull` nor the primary key (`nullableColumnFieldIds`,\n`NULL_TEST_FILTER_OPERATORS`), lowered to `{ field: null }` / `{ 'field !=':\nnull }`; JSON fields stay unfilterable, and a null test on a UUID column skips\nthe id-value check. A rejected filter that looks like a null test on a field\ndeclaring `isNull` (`eq`/`ne` with `null`, `\"null\"`, `\"\"` or `[]`; a `not` naming\n`field`; an `exists`-style kind/operator) gets a hint naming `isNull`/\n`isNotNull` with that field, and the valid example uses it; polarity follows\n`ne` and enclosing `not`s. Grammar: [core data-query](../core/agents/data-query.md#null-tests-4448).\nRefusals (#4387: action-specific denials, the `{ action }` catalog argument,\n`onDenied`, audit `denied` entries, missing executors):\n[agents/data-surface-denials.md](agents/data-surface-denials.md).\n\n\n## Playbook Preflight (issue #2590)\n\n`createPlaybookPreflightTool()` produces the `playbooks.preflight`\n`PrincipalTool`. It resolves a playbook through the caller's own layer chain on\nthe `server` plane and reports a per-step verdict from the two predicates\n`PrincipalRun` already exposes — `isToolAllowed(tool)` and `assertOperation`\n(which evaluates the catalog permission without performing the operation). It\nexecutes nothing.\n\n**Advisory only: preflight predicts, it never grants.** Name gates entry;\ndecomposition gates every step. Preflight computes that intersection ahead of\ntime and replaces neither gate, so a permission revoked between the prediction\nand the execution still denies at execution — proven in\n`playbook-preflight.test.ts`, which lets a cached `allow` stand and shows\n`assertOperation` refusing anyway.\n\n- Step → gating tool slug and permission collection are seams (`toolSlug`,\n  `collection`), defaulting to the registered collection slug for the step's\n  qualified model (`playbookStepToolSlug` / `playbookStepCollection`).\n- The cache partition key comes from the **live run context**, never the tool\n  arguments, so one principal's prediction can never be served to another.\n- An unknown key and an unauthorized key return the same uniform unavailable\n  report — the tool is not an enumeration oracle.\n- `filterPlaybooksByPreflight()` hides playbooks a caller could not run from a\n  listing. It is a listing convenience and **never** load-bearing for\n  authorization; a key it lets through is still authorized step by step.\n\n## Report Data-Surface Tools (issue #2462)\n\n`createReportDataSurfaceTools()` maps server-owned report definitions into the\ngeneric `data.discover`, `data.inspect`, and `data.query` catalog, and adds\nprincipal-bound `reports.query`, `reports.refresh`, `reports.drilldown`, and\n`reports.export` tools. It reuses the reports package's materialized-query,\nlifecycle, drilldown, and snapshot contracts rather than reimplementing them.\nReport ids, collections, query seams, browser delivery, background queues, and\naction hosts come only from the configured server catalog; tool arguments never\ncarry principal, tenant, or report-constructor authority.\n\n- Generic discovery excludes sensitive and permission-gated report columns.\n- Discovered report fields retain safe `kind`, `filterScope`, and capability\n  metadata, while the surface reports its available actions and lifecycle\n  freshness support. Actions are filtered by the current tool allow-list and\n  effective permissions. This lets agents distinguish dimensions/buckets\n  (`where`) from measures (`having`) without exposing hidden columns or\n  authority.\n- Silent reads do not change browser state; visible reads require a host-bound\n  acknowledgement whose post-command revision is not older than the requested\n  compare-and-swap revision; background requests contain no principal or tenant\n  payload.\n- Read results request the tenant-safe report lifecycle whenever an\n  authenticated database is available, so `freshness` and the redacted\n  lifecycle state cover stale and lock-skipped materializations.\n- Refresh and export use app-owned action hosts for live authorization and\n  auditing. Export captures an opaque immutable snapshot and preserves the\n  reports package's preview/confirmation protocol.\n- Drilldown re-reads a single accessible materialized row before it builds the\n  inherited source query, so callers cannot inject row values from another\n  tenant.\n\n## Agent Orchestration (issue #1892) — invoke-agent + principal delegation\n\nA conversational (orchestrator) agent can invoke worker agents with **principal delegation**. This is *not* a new engine — it is a standard `invoke-agent` tool plus a completion-dispatch convention on top of `executeAsPrincipal` + the DispatchBus.\n\n```typescript\nimport { createInvokeAgentTool, rootDelegationEnvelope } from '@happyvertical/smrt-agents';\n\nconst tool = createInvokeAgentTool({\n  db,\n  parentEnvelope: rootDelegationEnvelope({ runAsUserId, tenantId, onBehalfOfUserId }),\n  worker: async ({ run, agentClass, task }) => runWorker(run, agentClass, task),\n});\n// Offered through the chat tool loop as an `extraTools` entry, gated by the\n// persona's allowedTools like any other tool (slug: 'agents.invoke').\n```\n\n- **`DelegationEnvelope`** carries the **immutable principal** (`runAsUserId` + `tenantId` + originating `onBehalfOfUserId`) and a bounded `depth`. `deriveDelegationEnvelope()` copies the principal verbatim and asserts `depth <= MAX_DELEGATION_DEPTH` (3) — a worker cannot invoke a further worker under a broader principal (`PrincipalWideningError` / `DelegationDepthExceededError`).\n- **`createInvokeAgentTool()`** → a `PrincipalTool` whose handler derives the child envelope with the principal taken **from the live run context, never the tool args**, so the invoke-agent tool is structurally immune to principal widening.\n- **`executeDelegatedInvocation()`** runs the worker via `executeAsPrincipal` under that same principal and emits a correlated `agent.completed` dispatch; **`surfaceAgentCompletions(bus, correlationId)`** reads it back into the conversation.\n- **Transports** (pluggable): the default `inlineInvokeAgentTransport` runs the worker in-process (completion surfaces in the same turn); `createDispatchInvokeTransport(bus)` emits an `agent.invoke` signal a worker processes via `processAgentInvocations()` (async). A job-queue transport (enqueue on the `agents` queue) is a consumer-supplied `InvokeAgentTransport` — orchestration never hard-depends on `@happyvertical/smrt-jobs`, which sits *below* agents in the dependency graph.\n\n## Server Entry Points Stay Svelte-Free (issue #2924)\n\n`SmrtDataSurfaceActionTask`, `DataSurfaceActionTokenState`, and\n`DataSurfaceActionIdempotencyState` stamp `@happyvertical/smrt-agents/server`\nas their manifest `importPath`, so core's consumer plugin emits that specifier\nverbatim into a consumer's generated `.smrt/register.js` — which the `smrt` CLI\nloads with a bare `import()` under plain Node for `db:migrate`. **No module\nreachable from `./server` (or from the package root, or `./vite`) may import a\nSvelte component barrel.** A Vite build of the same graph succeeds, so this\nregresses silently and then breaks `db:migrate` for every object in the\nconsuming app, not just this package's.\n\n- Import shared data-surface protocol limits from the Svelte-free\n  `@happyvertical/smrt-ui/data-surface`, never `@happyvertical/smrt-ui/data`\n  (a component barrel that re-exports `.svelte` files).\n- `src/server/__tests__/node-entry-loadability.integration.test.ts` imports\n  every server-side subpath in a fresh plain-Node process; it needs a built\n  `dist/` (turbo's `test` task supplies it).\n- `scripts/verify-manifest-exports.mjs` fails a publish when any **non-root**\n  manifest `importPath` is unloadable under plain Node. A bundler-only *root*\n  barrel is still only a warning.\n\n## Key Files\n\n| File | Purpose |\n|------|---------|\n| `src/agent.ts` | Base Agent class — lifecycle, dispatch, interests, config, opt-in learning trait, multi-instance identity |\n| `src/execute-as-principal.ts` | `executeAsPrincipal` / `PrincipalRun` — run agent work as a persona's bound user (#1888) |\n| `src/report-data-surface.ts` | Principal-bound report discovery, query, lifecycle, drilldown, and export tools (#2462) |\n| `src/smrt-collection-data-surface.ts` | `createSmrtCollectionDataSurfaceDefinition()` — generic registry-driven `SmrtObject` collection to `DataSurfaceDefinition` adapter, with field-policy redaction (schema overrides included), class-aware tenant scope, DNF filter/scope lowering, deny-all short-circuit, query-bound opaque cursors, and offset/cursor paging; hydrated row values are serialized to JSON scalars at the adapter boundary — a `Date`/date-only/zoneless-UTC `datetime` becomes an ISO-8601 UTC instant, a `bigint` a safe number, and a non-scalar value on a scalar descriptor its JSON string — so a populated datetime column no longer fails the whole result; callers must keep `maxPageLimit` <= the collection's own row-limit cap (#2905, follow-up #2912, #2933) |\n| `src/delegation.ts` | `DelegationEnvelope` — immutable principal + bounded delegation depth (#1892) |\n| `src/invoke-agent.ts` | `invoke-agent` tool, worker executor, completion-dispatch convention, transports (#1892) |\n| `src/playbook-preflight.ts` | `playbooks.preflight` PrincipalTool — advisory per-step verdicts, never a grant (#2590) |\n| `src/learning.ts` | `AgentLearningConfig` + `resolveAgentLearning()` declaration normalisation |\n| `src/schedule.ts` | AgentSchedule model — cron, execution tracking |\n| `src/tenant-agent.ts` | TenantAgent — junction table, hierarchical resolution |\n| `src/interests.ts` | Interest filter types and configuration |\n| `src/config.ts` | File + DB config management, UI slots |\n",
   "moduleDocs": [
     {
       "path": "agents/data-surface-discovery.md",
       "module": "data-surface-discovery",
       "content": "# Data-surface discovery metadata\n\nModule reference for `packages/agents/AGENTS.md`.\n\n## Allowed field values (#4381)\n\nDeclared field `values` (#4381; contract in core\n[data-query.md](../../core/agents/data-query.md)) appear on `data.inspect` and\n`data.discover` field descriptors with an explicit `valuesEnforced` flag; for\nan enforced set an undeclared `eq`/`ne`/`in`/`notIn` value fails as a\n`DataSurfaceRequestError` (`reason` `DATA_QUERY_VALUE_NOT_ALLOWED`) naming the\nallowed values. Enum-derived smrt-collection values are advisory unless the\nhost sets `enforceDerivedValues`.\n\n## Summary discovery and row-count hints (#4329)\n\n`discoverDetail: 'summary'` (#4329; default `'full'`) makes `data.discover`\nreturn only `id` (repeated as `surfaceId`, the argument name `data.inspect`\nand `data.query` take, #4507), a cleaned `label`, the description's first non-empty line\nbounded to 160 chars, and `rowCountHint`, with a discover tool description\npointing to `data.inspect`. Without a `rowCountHint`, full discovery and\n`data.inspect` are byte-identical to before; a valid hint is added to both.\nThe catalog/RBAC gates, including identity-field denial, run the same in both\nmodes; query is unaffected. Summary mode assumes the persona may call\n`data.inspect`: a host granting discover and query without inspect keeps full.\n`DataSurfaceDefinition.rowCountHint` is host-supplied and never queried:\n`normalizeDataSurfaceRowCountHint()` accepts a non-negative safe integer or a\ntrimmed label of at most 32 chars with something visible and no Cc/Cf/Zl/Zp\ncharacters, and omits anything else. Every reader of the surface sees the\nsame hint, so it must be a coarse static label, never a tenant- or\nprincipal-specific count; the description's first line is model-facing and\nmust carry no secrets or instructions.\n\n## Argument names and request aliases (#4507, #4505)\n\n`data.inspect`'s `surfaceId` is described (\"The id data.discover lists for the\nsurface\", `DATA_INSPECT_TOOL_PARAMETERS`) and named in its tool description;\nsummary discovery repeats `id` as `surfaceId`. `placeSurfaceId` takes a lone\ntop-level `id` string as `surfaceId` when no `surfaceId` is given and nothing\nelse sits beside it (inspect: no other key; query: only `request` or its\n`query` wrapper, never the flat form, where `id` may be a field). Every other\n`id` is ignored and the existing `DATA_QUERY_SURFACE_ID_*` errors apply.\n\nInside `request` (or the flat form), `data.query` maps SQL-ish aliases before\nvalidation when the canonical key is absent: `select`→`projection` (array or\ncomma-separated string), `where`→`filter`, `orderBy`→`sort` (`\"field desc\"`\nstrings, comma lists, or a `{ field }` object; direction defaults to `asc`),\nand `limit`/`offset`→`page.limit`/`page.offset` (merged into a `page` that\nlacks them). Mapped values are validated exactly as if written canonically.\nAn alias beside its canonical key stays in place and fails as an unsupported\nkey; the error names the canonical key. Beside `request` at the top level an\nalias is `DATA_QUERY_ARGUMENTS_UNEXPECTED` (\"move limit inside request\"). The\nrequest schema's property descriptions name the aliases.\n"
     },
+    {
+      "path": "agents/lazy-config.md",
+      "module": "lazy-config",
+      "content": "# Lazy agent_config resolution (#1161, #2806)\n\nPersisted `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:\n\n1. **`$env` sentinels in persisted config** — register a global resolver and reference it from the JSON:\n\n   ```ts\n   import { registerConfigResolver } from '@happyvertical/smrt-agents';\n   registerConfigResolver('sharedAssetStorage', () => resolveSharedAssetStorage());\n   // persisted: { \"assetStorage\": { \"$env\": \"sharedAssetStorage\" } }\n   ```\n\n2. **`static configResolvers` on the agent class** — declarative, discoverable via the class itself:\n\n   ```ts\n   class Praeco extends Agent {\n     static override configResolvers = {\n       assetStorage: () => resolveSharedAssetStorage(),\n     };\n   }\n   ```\n\nThe 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.\n\n**Resolver context and precedence (#2806).** Every resolver receives a frozen `ConfigResolverContext`. It holds this instance's `agentId` (the job's `objectId`), canonical `agentClass`, `tenantId`, `scheduleId` and `jobId`. Class resolvers also get the instance's own persisted value for the key (`persisted`, `hasPersisted`); sentinel resolvers get the value's `path`. Precedence:\n1. a non-null resolver result;\n2. the persisted value, kept on `undefined` / `null`;\n3. absent.\n\nA deployment fallback that must not clobber an agent's own value, such as its provider credential, uses `preferPersisted(fallback)` or returns `undefined` when `context.hasPersisted`. Never select an agent by scanning the tenant's `agent_configs` rows: with several agents of one class per tenant, that leaks one agent's credential to another. Use `context.agentId`. Zero-argument resolvers remain valid.\n\nCaveats:\n- `scheduleId` is echoed from job args without verification, so never key a per-agent value on it.\n- `persisted` is neither copied nor deep-frozen. Treat it as read-only.\n- Only `undefined` / `null` count as absent for `preferPersisted`. A present but empty value such as `{}` is kept.\n"
+    },
     {
       "path": "agents/data-surface-denials.md",
       "module": "data-surface-denials",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-agents",
-  "version": "0.57.46",
+  "version": "0.57.47",
   "smrtJsdoc": "strict",
   "type": "module",
   "smrtRawPrimitives": "strict",
@@ -58,25 +58,25 @@
     }
   },
   "dependencies": {
-    "@happyvertical/ai": "^0.111.0",
-    "@happyvertical/files": "^0.111.0",
-    "@happyvertical/logger": "^0.111.0",
-    "@happyvertical/smrt-config": "0.57.46",
-    "@happyvertical/smrt-core": "0.57.46",
-    "@happyvertical/smrt-jobs": "0.57.46",
-    "@happyvertical/smrt-playbooks": "0.57.46",
-    "@happyvertical/smrt-reports": "0.57.46",
-    "@happyvertical/smrt-secrets": "0.57.46",
-    "@happyvertical/smrt-tenancy": "0.57.46",
-    "@happyvertical/smrt-types": "0.57.46",
-    "@happyvertical/smrt-ui": "0.57.46",
-    "@happyvertical/smrt-users": "0.57.46",
-    "@happyvertical/sql": "^0.111.0",
-    "@happyvertical/utils": "^0.111.0"
+    "@happyvertical/ai": "^0.111.3",
+    "@happyvertical/files": "^0.111.3",
+    "@happyvertical/logger": "^0.111.3",
+    "@happyvertical/smrt-config": "0.57.47",
+    "@happyvertical/smrt-core": "0.57.47",
+    "@happyvertical/smrt-jobs": "0.57.47",
+    "@happyvertical/smrt-playbooks": "0.57.47",
+    "@happyvertical/smrt-reports": "0.57.47",
+    "@happyvertical/smrt-secrets": "0.57.47",
+    "@happyvertical/smrt-tenancy": "0.57.47",
+    "@happyvertical/smrt-types": "0.57.47",
+    "@happyvertical/smrt-ui": "0.57.47",
+    "@happyvertical/smrt-users": "0.57.47",
+    "@happyvertical/sql": "^0.111.3",
+    "@happyvertical/utils": "^0.111.3"
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.57.46",
-    "@happyvertical/sql": "^0.111.0",
+    "@happyvertical/smrt-vitest": "0.57.47",
+    "@happyvertical/sql": "^0.111.3",
     "@sentry/node": "^10.75.0",
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.3.0",