@happyvertical/smrt-agents 0.49.2 → 0.49.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +22 -5
- package/dist/index.js +1 -1
- package/dist/manifest.json +631 -16
- package/dist/server/data-surface-actions.d.ts +36 -13
- package/dist/server/data-surface-actions.d.ts.map +1 -1
- package/dist/server/index.d.ts +5 -1
- package/dist/server/index.d.ts.map +1 -1
- package/dist/server/jobs-data-surface-action-queue.d.ts +33 -0
- package/dist/server/jobs-data-surface-action-queue.d.ts.map +1 -0
- package/dist/server/sql-data-surface-action-state.d.ts +60 -0
- package/dist/server/sql-data-surface-action-state.d.ts.map +1 -0
- package/dist/server.js +468 -20
- package/dist/server.js.map +1 -1
- package/dist/smrt-knowledge.json +165 -5
- package/package.json +14 -12
package/dist/smrt-knowledge.json
CHANGED
|
@@ -3,12 +3,12 @@
|
|
|
3
3
|
"sensitiveFieldsExcluded": true,
|
|
4
4
|
"generatedAt": "1970-01-01T00:00:00.000Z",
|
|
5
5
|
"packageName": "@happyvertical/smrt-agents",
|
|
6
|
-
"packageVersion": "0.49.
|
|
6
|
+
"packageVersion": "0.49.4",
|
|
7
7
|
"sourceManifestPath": "dist/manifest.json",
|
|
8
8
|
"agentDocPath": "AGENTS.md",
|
|
9
9
|
"sourceHashes": {
|
|
10
|
-
"manifest": "
|
|
11
|
-
"packageJson": "
|
|
10
|
+
"manifest": "27f679df16ee489a5714c3d8b55180e29a709f1fb3c58c0f8765d91646254718",
|
|
11
|
+
"packageJson": "9d2d2b70ae14eef3e730b64774dbb1ab4a04893eddffea20314b77d2bd2893b6",
|
|
12
12
|
"agents": "14f3cf361f649432fe871988e13c8382fed295d2bd16f47a4502433322a5d8ed"
|
|
13
13
|
},
|
|
14
14
|
"exports": [
|
|
@@ -27,6 +27,7 @@
|
|
|
27
27
|
"@happyvertical/files": "catalog:",
|
|
28
28
|
"@happyvertical/smrt-config": "workspace:*",
|
|
29
29
|
"@happyvertical/smrt-core": "workspace:*",
|
|
30
|
+
"@happyvertical/smrt-jobs": "workspace:*",
|
|
30
31
|
"@happyvertical/smrt-playbooks": "workspace:*",
|
|
31
32
|
"@happyvertical/smrt-reports": "workspace:*",
|
|
32
33
|
"@happyvertical/smrt-secrets": "workspace:*",
|
|
@@ -34,10 +35,10 @@
|
|
|
34
35
|
"@happyvertical/smrt-types": "workspace:*",
|
|
35
36
|
"@happyvertical/smrt-ui": "workspace:*",
|
|
36
37
|
"@happyvertical/smrt-users": "workspace:*",
|
|
38
|
+
"@happyvertical/sql": "catalog:",
|
|
37
39
|
"@happyvertical/utils": "catalog:",
|
|
38
40
|
"@happyvertical/logger": "catalog:",
|
|
39
41
|
"@happyvertical/smrt-vitest": "workspace:*",
|
|
40
|
-
"@happyvertical/sql": "catalog:",
|
|
41
42
|
"@sentry/node": "catalog:",
|
|
42
43
|
"@sveltejs/package": "^2.5.8",
|
|
43
44
|
"@sveltejs/vite-plugin-svelte": "^7.1.2",
|
|
@@ -54,6 +55,7 @@
|
|
|
54
55
|
"smrtDependencies": [
|
|
55
56
|
"@happyvertical/smrt-config",
|
|
56
57
|
"@happyvertical/smrt-core",
|
|
58
|
+
"@happyvertical/smrt-jobs",
|
|
57
59
|
"@happyvertical/smrt-playbooks",
|
|
58
60
|
"@happyvertical/smrt-reports",
|
|
59
61
|
"@happyvertical/smrt-secrets",
|
|
@@ -1529,6 +1531,164 @@
|
|
|
1529
1531
|
],
|
|
1530
1532
|
"tags": [],
|
|
1531
1533
|
"risks": []
|
|
1534
|
+
},
|
|
1535
|
+
{
|
|
1536
|
+
"name": "SmrtDataSurfaceActionTask",
|
|
1537
|
+
"qualifiedName": "@happyvertical/smrt-agents:SmrtDataSurfaceActionTask",
|
|
1538
|
+
"collection": "smrtdatasurfaceactiontasks",
|
|
1539
|
+
"tableName": "_smrt_data_surface_action_tasks",
|
|
1540
|
+
"packageName": "@happyvertical/smrt-agents",
|
|
1541
|
+
"extends": "SmrtObject",
|
|
1542
|
+
"fields": [
|
|
1543
|
+
{
|
|
1544
|
+
"name": "tenantId",
|
|
1545
|
+
"type": "text",
|
|
1546
|
+
"required": false,
|
|
1547
|
+
"columnType": "UUID"
|
|
1548
|
+
},
|
|
1549
|
+
{
|
|
1550
|
+
"name": "args",
|
|
1551
|
+
"type": "json",
|
|
1552
|
+
"required": true,
|
|
1553
|
+
"columnType": "JSON"
|
|
1554
|
+
}
|
|
1555
|
+
],
|
|
1556
|
+
"relationships": [],
|
|
1557
|
+
"methods": [
|
|
1558
|
+
"run"
|
|
1559
|
+
],
|
|
1560
|
+
"methodSignatures": [
|
|
1561
|
+
{
|
|
1562
|
+
"name": "run",
|
|
1563
|
+
"async": true,
|
|
1564
|
+
"params": [
|
|
1565
|
+
"args?: DataSurfaceActionJobArgs",
|
|
1566
|
+
"context?: JobExecutionContext"
|
|
1567
|
+
],
|
|
1568
|
+
"returns": "Promise<DataSurfaceActionResult>"
|
|
1569
|
+
}
|
|
1570
|
+
],
|
|
1571
|
+
"tenant": {
|
|
1572
|
+
"scoped": true,
|
|
1573
|
+
"mode": "optional",
|
|
1574
|
+
"field": "tenantId"
|
|
1575
|
+
},
|
|
1576
|
+
"conflictColumns": [
|
|
1577
|
+
"tenant_id",
|
|
1578
|
+
"slug",
|
|
1579
|
+
"context"
|
|
1580
|
+
],
|
|
1581
|
+
"surfaces": [],
|
|
1582
|
+
"withheldSurfaces": [
|
|
1583
|
+
{
|
|
1584
|
+
"kind": "api",
|
|
1585
|
+
"operation": "run",
|
|
1586
|
+
"code": "api-disabled",
|
|
1587
|
+
"reason": "api is disabled",
|
|
1588
|
+
"objectName": "@happyvertical/smrt-agents:SmrtDataSurfaceActionTask"
|
|
1589
|
+
}
|
|
1590
|
+
],
|
|
1591
|
+
"relationshipFeatures": [
|
|
1592
|
+
"uuidColumns"
|
|
1593
|
+
],
|
|
1594
|
+
"tags": [],
|
|
1595
|
+
"risks": []
|
|
1596
|
+
},
|
|
1597
|
+
{
|
|
1598
|
+
"name": "DataSurfaceActionTokenState",
|
|
1599
|
+
"qualifiedName": "@happyvertical/smrt-agents:DataSurfaceActionTokenState",
|
|
1600
|
+
"collection": "datasurfaceactiontokenstates",
|
|
1601
|
+
"tableName": "_smrt_data_surface_action_tokens",
|
|
1602
|
+
"packageName": "@happyvertical/smrt-agents",
|
|
1603
|
+
"extends": "SmrtObject",
|
|
1604
|
+
"fields": [
|
|
1605
|
+
{
|
|
1606
|
+
"name": "tokenHash",
|
|
1607
|
+
"type": "text",
|
|
1608
|
+
"required": true,
|
|
1609
|
+
"columnType": "TEXT"
|
|
1610
|
+
},
|
|
1611
|
+
{
|
|
1612
|
+
"name": "record",
|
|
1613
|
+
"type": "json",
|
|
1614
|
+
"required": true,
|
|
1615
|
+
"columnType": "JSON"
|
|
1616
|
+
},
|
|
1617
|
+
{
|
|
1618
|
+
"name": "consumedBy",
|
|
1619
|
+
"type": "text",
|
|
1620
|
+
"required": false,
|
|
1621
|
+
"columnType": "TEXT"
|
|
1622
|
+
}
|
|
1623
|
+
],
|
|
1624
|
+
"relationships": [],
|
|
1625
|
+
"methods": [],
|
|
1626
|
+
"surfaces": [],
|
|
1627
|
+
"relationshipFeatures": [
|
|
1628
|
+
"uuidColumns"
|
|
1629
|
+
],
|
|
1630
|
+
"tags": [],
|
|
1631
|
+
"risks": []
|
|
1632
|
+
},
|
|
1633
|
+
{
|
|
1634
|
+
"name": "DataSurfaceActionIdempotencyState",
|
|
1635
|
+
"qualifiedName": "@happyvertical/smrt-agents:DataSurfaceActionIdempotencyState",
|
|
1636
|
+
"collection": "datasurfaceactionidempotencystates",
|
|
1637
|
+
"tableName": "_smrt_data_surface_action_idempotency",
|
|
1638
|
+
"packageName": "@happyvertical/smrt-agents",
|
|
1639
|
+
"extends": "SmrtObject",
|
|
1640
|
+
"fields": [
|
|
1641
|
+
{
|
|
1642
|
+
"name": "keyHash",
|
|
1643
|
+
"type": "text",
|
|
1644
|
+
"required": true,
|
|
1645
|
+
"columnType": "TEXT"
|
|
1646
|
+
},
|
|
1647
|
+
{
|
|
1648
|
+
"name": "status",
|
|
1649
|
+
"type": "text",
|
|
1650
|
+
"required": true,
|
|
1651
|
+
"columnType": "TEXT"
|
|
1652
|
+
},
|
|
1653
|
+
{
|
|
1654
|
+
"name": "requestFingerprint",
|
|
1655
|
+
"type": "text",
|
|
1656
|
+
"required": true,
|
|
1657
|
+
"columnType": "TEXT"
|
|
1658
|
+
},
|
|
1659
|
+
{
|
|
1660
|
+
"name": "ownerHash",
|
|
1661
|
+
"type": "text",
|
|
1662
|
+
"required": false,
|
|
1663
|
+
"columnType": "TEXT"
|
|
1664
|
+
},
|
|
1665
|
+
{
|
|
1666
|
+
"name": "reservedAt",
|
|
1667
|
+
"type": "text",
|
|
1668
|
+
"required": false,
|
|
1669
|
+
"columnType": "TEXT"
|
|
1670
|
+
},
|
|
1671
|
+
{
|
|
1672
|
+
"name": "result",
|
|
1673
|
+
"type": "json",
|
|
1674
|
+
"required": false,
|
|
1675
|
+
"columnType": "JSON"
|
|
1676
|
+
},
|
|
1677
|
+
{
|
|
1678
|
+
"name": "recovery",
|
|
1679
|
+
"type": "json",
|
|
1680
|
+
"required": false,
|
|
1681
|
+
"columnType": "JSON"
|
|
1682
|
+
}
|
|
1683
|
+
],
|
|
1684
|
+
"relationships": [],
|
|
1685
|
+
"methods": [],
|
|
1686
|
+
"surfaces": [],
|
|
1687
|
+
"relationshipFeatures": [
|
|
1688
|
+
"uuidColumns"
|
|
1689
|
+
],
|
|
1690
|
+
"tags": [],
|
|
1691
|
+
"risks": []
|
|
1532
1692
|
}
|
|
1533
1693
|
],
|
|
1534
1694
|
"surfaces": [
|
|
@@ -2076,7 +2236,7 @@
|
|
|
2076
2236
|
"junctionCollections": 0,
|
|
2077
2237
|
"hierarchicalObjects": 0,
|
|
2078
2238
|
"polymorphicAssociations": 0,
|
|
2079
|
-
"uuidColumns":
|
|
2239
|
+
"uuidColumns": 18
|
|
2080
2240
|
},
|
|
2081
2241
|
"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## 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## AgentSchedule\n\nCron-based scheduling stored in `_smrt_agent_schedules`. Fields: `agentType`, `cron`, `method` (default: 'run'), `maxConcurrent`, `timeout`. Executed by ScheduleRunner from smrt-jobs.\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 with no snapshotting. 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.\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## 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/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"
|
|
2082
2242
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@happyvertical/smrt-agents",
|
|
3
|
-
"version": "0.49.
|
|
3
|
+
"version": "0.49.4",
|
|
4
4
|
"smrtJsdoc": "strict",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"smrtRawPrimitives": "strict",
|
|
@@ -59,20 +59,22 @@
|
|
|
59
59
|
"dependencies": {
|
|
60
60
|
"@happyvertical/ai": "^0.89.6",
|
|
61
61
|
"@happyvertical/files": "^0.89.6",
|
|
62
|
-
"@happyvertical/smrt-config": "0.49.
|
|
63
|
-
"@happyvertical/smrt-core": "0.49.
|
|
64
|
-
"@happyvertical/smrt-
|
|
65
|
-
"@happyvertical/smrt-
|
|
66
|
-
"@happyvertical/smrt-
|
|
67
|
-
"@happyvertical/smrt-
|
|
68
|
-
"@happyvertical/smrt-
|
|
69
|
-
"@happyvertical/smrt-
|
|
70
|
-
"@happyvertical/smrt-
|
|
62
|
+
"@happyvertical/smrt-config": "0.49.4",
|
|
63
|
+
"@happyvertical/smrt-core": "0.49.4",
|
|
64
|
+
"@happyvertical/smrt-jobs": "0.49.4",
|
|
65
|
+
"@happyvertical/smrt-playbooks": "0.49.4",
|
|
66
|
+
"@happyvertical/smrt-reports": "0.49.4",
|
|
67
|
+
"@happyvertical/smrt-secrets": "0.49.4",
|
|
68
|
+
"@happyvertical/smrt-tenancy": "0.49.4",
|
|
69
|
+
"@happyvertical/smrt-types": "0.49.4",
|
|
70
|
+
"@happyvertical/smrt-ui": "0.49.4",
|
|
71
|
+
"@happyvertical/smrt-users": "0.49.4",
|
|
72
|
+
"@happyvertical/sql": "^0.89.6",
|
|
71
73
|
"@happyvertical/utils": "^0.89.6"
|
|
72
74
|
},
|
|
73
75
|
"devDependencies": {
|
|
74
76
|
"@happyvertical/logger": "^0.89.6",
|
|
75
|
-
"@happyvertical/smrt-vitest": "0.49.
|
|
77
|
+
"@happyvertical/smrt-vitest": "0.49.4",
|
|
76
78
|
"@happyvertical/sql": "^0.89.6",
|
|
77
79
|
"@sentry/node": "^10.63.0",
|
|
78
80
|
"@sveltejs/package": "^2.5.8",
|
|
@@ -111,7 +113,7 @@
|
|
|
111
113
|
"typecheck": "tsc --noEmit && node ../../scripts/svelte-check-a11y.mjs --tsconfig ./tsconfig.svelte.json",
|
|
112
114
|
"test": "vitest run",
|
|
113
115
|
"test:watch": "vitest",
|
|
114
|
-
"test:postgres": "node ../../scripts/run-with-ci-postgres.mjs -- pnpm exec vitest run src/migrations/__tests__/agent-schedule-slugs-postgres.optional.test.ts",
|
|
116
|
+
"test:postgres": "node ../../scripts/run-with-ci-postgres.mjs -- pnpm exec vitest run src/migrations/__tests__/agent-schedule-slugs-postgres.optional.test.ts src/server/sql-data-surface-action-state-postgres.optional.test.ts",
|
|
115
117
|
"verify:pack": "node ../../scripts/verify-package-types-exports.js ."
|
|
116
118
|
}
|
|
117
119
|
}
|