@happyvertical/smrt-agents 0.44.0 → 0.45.0

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.
Files changed (14) hide show
  1. package/AGENTS.md +28 -0
  2. package/dist/index.d.ts +1 -0
  3. package/dist/index.d.ts.map +1 -1
  4. package/dist/index.js +78 -3
  5. package/dist/index.js.map +1 -1
  6. package/dist/manifest.json +10 -543
  7. package/dist/playbook-preflight.d.ts +61 -0
  8. package/dist/playbook-preflight.d.ts.map +1 -0
  9. package/dist/server/data-surface-actions.d.ts +2 -0
  10. package/dist/server/data-surface-actions.d.ts.map +1 -1
  11. package/dist/server.js +6 -6
  12. package/dist/server.js.map +1 -1
  13. package/dist/smrt-knowledge.json +622 -339
  14. package/package.json +11 -10
package/dist/smrt-knowledge.json CHANGED
@@ -3,13 +3,13 @@
3
3
  "sensitiveFieldsExcluded": true,
4
4
  "generatedAt": "1970-01-01T00:00:00.000Z",
5
5
  "packageName": "@happyvertical/smrt-agents",
6
- "packageVersion": "0.44.0",
6
+ "packageVersion": "0.45.0",
7
7
  "sourceManifestPath": "dist/manifest.json",
8
8
  "agentDocPath": "AGENTS.md",
9
9
  "sourceHashes": {
10
- "manifest": "81e22d35ee28e9933a68beb5301bc45d97953086cd573a1f472c825e48214a08",
11
- "packageJson": "46261f34b93e1986a8279b4b48d8c09dd5e66e5ffbb102b4e115172ba9a6b57a",
12
- "agents": "6ce7da109ba71d3e767ee0091d7ac28528c422310f5031f46f65e93814ee0a86"
10
+ "manifest": "0ed3aac25a2ffd0b47b7f873ad635cd219e804a84d6914971f4285c93a64dd78",
11
+ "packageJson": "4513cb3d97c5dc7e5f4ab30f7badfff4dccdbd3f6597104b7192b2626d184f80",
12
+ "agents": "14f3cf361f649432fe871988e13c8382fed295d2bd16f47a4502433322a5d8ed"
13
13
  },
14
14
  "exports": [
15
15
  ".",
@@ -27,6 +27,7 @@
27
27
  "@happyvertical/files": "catalog:",
28
28
  "@happyvertical/smrt-config": "workspace:*",
29
29
  "@happyvertical/smrt-core": "workspace:*",
30
+ "@happyvertical/smrt-playbooks": "workspace:*",
30
31
  "@happyvertical/smrt-reports": "workspace:*",
31
32
  "@happyvertical/smrt-secrets": "workspace:*",
32
33
  "@happyvertical/smrt-tenancy": "workspace:*",
@@ -53,6 +54,7 @@
53
54
  "smrtDependencies": [
54
55
  "@happyvertical/smrt-config",
55
56
  "@happyvertical/smrt-core",
57
+ "@happyvertical/smrt-playbooks",
56
58
  "@happyvertical/smrt-reports",
57
59
  "@happyvertical/smrt-secrets",
58
60
  "@happyvertical/smrt-tenancy",
@@ -107,136 +109,30 @@
107
109
  ],
108
110
  "relationships": [],
109
111
  "methods": [
110
- "_setLoadedRelationship",
111
- "claimRevision",
112
- "classifyConstraintError",
113
- "clearEmbeddings",
114
- "delete",
115
- "describe",
116
- "destroy",
117
- "do",
118
112
  "execute",
119
- "executeToolCall",
120
113
  "exportConfig",
121
- "forget",
122
- "forgetScope",
123
- "generateEmbeddings",
124
- "getAiUsageSnapshot",
125
- "getAvailableTools",
126
114
  "getConfigOwnerId",
127
115
  "getDispatch",
128
116
  "getDispatchSubscriber",
129
- "getEmbedding",
130
- "getFields",
131
- "getId",
132
117
  "getInstanceKey",
133
118
  "getLearningMemory",
134
119
  "getMergedConfig",
135
- "getRelated",
136
- "getSavedId",
137
- "getSlug",
138
120
  "getUISlots",
139
121
  "handleDispatch",
140
- "hasStaleEmbeddings",
141
122
  "initialize",
142
123
  "interesting",
143
- "is",
144
- "isRelatedLoaded",
145
- "isSaved",
146
- "listAiUsage",
147
124
  "loadConfigs",
148
- "loadDataFromDb",
149
- "loadFromId",
150
- "loadFromSlug",
151
- "loadRelated",
152
- "loadRelatedMany",
153
- "markAsPersisted",
154
125
  "processDispatches",
155
- "recall",
156
- "recallAll",
157
- "remember",
158
- "requireInsertOnSave",
159
- "resetAiUsage",
160
- "save",
161
126
  "saveSlotConfig",
162
127
  "shutdown",
163
- "summarizeAiUsage",
164
- "toJSON",
165
- "toPlainObject",
166
- "toPublicJSON",
167
- "validate",
168
- "withDatabase",
169
- "withTransaction"
128
+ "validate"
170
129
  ],
171
130
  "methodSignatures": [
172
- {
173
- "name": "_setLoadedRelationship",
174
- "params": [
175
- "fieldName: string",
176
- "value: any"
177
- ],
178
- "returns": "void"
179
- },
180
- {
181
- "name": "claimRevision",
182
- "async": true,
183
- "params": [
184
- "expectedUpdatedAt: Date | string"
185
- ],
186
- "returns": "Promise"
187
- },
188
- {
189
- "name": "classifyConstraintError",
190
- "static": true,
191
- "params": [
192
- "message: string"
193
- ],
194
- "returns": "'unique' | 'not_null' | null"
195
- },
196
- {
197
- "name": "clearEmbeddings",
198
- "async": true,
199
- "returns": "Promise<void>"
200
- },
201
- {
202
- "name": "delete",
203
- "async": true,
204
- "returns": "Promise<void>"
205
- },
206
- {
207
- "name": "describe",
208
- "async": true,
209
- "params": [
210
- "options?: AiOperationOptions"
211
- ],
212
- "returns": "any"
213
- },
214
- {
215
- "name": "destroy",
216
- "returns": "void"
217
- },
218
- {
219
- "name": "do",
220
- "async": true,
221
- "params": [
222
- "instructions: string",
223
- "options?: AiOperationOptions"
224
- ],
225
- "returns": "any"
226
- },
227
131
  {
228
132
  "name": "execute",
229
133
  "async": true,
230
134
  "returns": "Promise<void>"
231
135
  },
232
- {
233
- "name": "executeToolCall",
234
- "async": true,
235
- "params": [
236
- "toolCall: ToolCall"
237
- ],
238
- "returns": "Promise<ToolCallResult>"
239
- },
240
136
  {
241
137
  "name": "exportConfig",
242
138
  "async": true,
@@ -245,38 +141,6 @@
245
141
  ],
246
142
  "returns": "Promise<Record<string>>"
247
143
  },
248
- {
249
- "name": "forget",
250
- "async": true,
251
- "params": [
252
- "options: object"
253
- ],
254
- "returns": "Promise<void>"
255
- },
256
- {
257
- "name": "forgetScope",
258
- "async": true,
259
- "params": [
260
- "options: object"
261
- ],
262
- "returns": "Promise<number>"
263
- },
264
- {
265
- "name": "generateEmbeddings",
266
- "async": true,
267
- "params": [
268
- "options?: GenerateEmbeddingsOptions"
269
- ],
270
- "returns": "Promise<void>"
271
- },
272
- {
273
- "name": "getAiUsageSnapshot",
274
- "returns": "AiUsageSnapshot | undefined"
275
- },
276
- {
277
- "name": "getAvailableTools",
278
- "returns": "AITool[]"
279
- },
280
144
  {
281
145
  "name": "getConfigOwnerId",
282
146
  "params": [
@@ -293,25 +157,6 @@
293
157
  "name": "getDispatchSubscriber",
294
158
  "returns": "string"
295
159
  },
296
- {
297
- "name": "getEmbedding",
298
- "async": true,
299
- "params": [
300
- "fieldName: string",
301
- "model?: string"
302
- ],
303
- "returns": "Promise<number[] | null>"
304
- },
305
- {
306
- "name": "getFields",
307
- "async": true,
308
- "returns": "Promise<any>"
309
- },
310
- {
311
- "name": "getId",
312
- "async": true,
313
- "returns": "any"
314
- },
315
160
  {
316
161
  "name": "getInstanceKey",
317
162
  "returns": "string | null"
@@ -328,25 +173,6 @@
328
173
  ],
329
174
  "returns": "Promise<Record<string>>"
330
175
  },
331
- {
332
- "name": "getRelated",
333
- "async": true,
334
- "params": [
335
- "fieldName: string",
336
- "opts?: LoadRelatedOptions"
337
- ],
338
- "returns": "Promise<any>"
339
- },
340
- {
341
- "name": "getSavedId",
342
- "async": true,
343
- "returns": "any"
344
- },
345
- {
346
- "name": "getSlug",
347
- "async": true,
348
- "returns": "any"
349
- },
350
176
  {
351
177
  "name": "getUISlots",
352
178
  "returns": "AgentUISlots"
@@ -360,11 +186,6 @@
360
186
  ],
361
187
  "returns": "Promise<void>"
362
188
  },
363
- {
364
- "name": "hasStaleEmbeddings",
365
- "async": true,
366
- "returns": "Promise<boolean>"
367
- },
368
189
  {
369
190
  "name": "initialize",
370
191
  "async": true,
@@ -375,125 +196,16 @@
375
196
  "async": true,
376
197
  "returns": "Promise<InterestResult[]>"
377
198
  },
378
- {
379
- "name": "is",
380
- "async": true,
381
- "params": [
382
- "criteria: string",
383
- "options?: AiOperationOptions"
384
- ],
385
- "returns": "any"
386
- },
387
- {
388
- "name": "isRelatedLoaded",
389
- "params": [
390
- "fieldName: string"
391
- ],
392
- "returns": "boolean"
393
- },
394
- {
395
- "name": "isSaved",
396
- "async": true,
397
- "returns": "any"
398
- },
399
- {
400
- "name": "listAiUsage",
401
- "async": true,
402
- "params": [
403
- "options?: AiUsageListOptions"
404
- ],
405
- "returns": "Promise<SmrtAiUsageRecord[]>"
406
- },
407
199
  {
408
200
  "name": "loadConfigs",
409
201
  "async": true,
410
202
  "returns": "Promise<Map<string, Record<string>>>"
411
203
  },
412
- {
413
- "name": "loadDataFromDb",
414
- "async": true,
415
- "params": [
416
- "data: Record<string>"
417
- ],
418
- "returns": "any"
419
- },
420
- {
421
- "name": "loadFromId",
422
- "async": true,
423
- "returns": "any"
424
- },
425
- {
426
- "name": "loadFromSlug",
427
- "async": true,
428
- "returns": "any"
429
- },
430
- {
431
- "name": "loadRelated",
432
- "async": true,
433
- "params": [
434
- "fieldName: string",
435
- "opts?: LoadRelatedOptions"
436
- ],
437
- "returns": "Promise<any>"
438
- },
439
- {
440
- "name": "loadRelatedMany",
441
- "async": true,
442
- "params": [
443
- "fieldName: string",
444
- "opts?: LoadRelatedOptions"
445
- ],
446
- "returns": "Promise<any[]>"
447
- },
448
- {
449
- "name": "markAsPersisted",
450
- "returns": "void"
451
- },
452
204
  {
453
205
  "name": "processDispatches",
454
206
  "async": true,
455
207
  "returns": "Promise<number>"
456
208
  },
457
- {
458
- "name": "recall",
459
- "async": true,
460
- "params": [
461
- "options: object"
462
- ],
463
- "returns": "Promise"
464
- },
465
- {
466
- "name": "recallAll",
467
- "async": true,
468
- "params": [
469
- "options?: object"
470
- ],
471
- "returns": "Promise<Map<string>>"
472
- },
473
- {
474
- "name": "remember",
475
- "async": true,
476
- "params": [
477
- "options: object"
478
- ],
479
- "returns": "Promise<void>"
480
- },
481
- {
482
- "name": "requireInsertOnSave",
483
- "returns": "void"
484
- },
485
- {
486
- "name": "resetAiUsage",
487
- "returns": "void"
488
- },
489
- {
490
- "name": "save",
491
- "async": true,
492
- "params": [
493
- "options?: SmrtSaveOptions"
494
- ],
495
- "returns": "any"
496
- },
497
209
  {
498
210
  "name": "saveSlotConfig",
499
211
  "async": true,
@@ -508,50 +220,10 @@
508
220
  "async": true,
509
221
  "returns": "Promise<void>"
510
222
  },
511
- {
512
- "name": "summarizeAiUsage",
513
- "async": true,
514
- "params": [
515
- "options?: AiUsageSummaryOptions"
516
- ],
517
- "returns": "Promise<Record<string, AiUsageStats>>"
518
- },
519
- {
520
- "name": "toJSON",
521
- "returns": "any"
522
- },
523
- {
524
- "name": "toPlainObject",
525
- "returns": "Record<string>"
526
- },
527
- {
528
- "name": "toPublicJSON",
529
- "params": [
530
- "options?: PublicJsonOptions"
531
- ],
532
- "returns": "Record<string>"
533
- },
534
223
  {
535
224
  "name": "validate",
536
225
  "async": true,
537
226
  "returns": "Promise<void>"
538
- },
539
- {
540
- "name": "withDatabase",
541
- "async": true,
542
- "params": [
543
- "db: DatabaseInterface",
544
- "operation: Function"
545
- ],
546
- "returns": "Promise<T>"
547
- },
548
- {
549
- "name": "withTransaction",
550
- "async": true,
551
- "params": [
552
- "operation: Function"
553
- ],
554
- "returns": "Promise<T>"
555
227
  }
556
228
  ],
557
229
  "tenant": {
@@ -743,6 +415,30 @@
743
415
  "operation": "delete",
744
416
  "objectName": "@happyvertical/smrt-agents:AgentConfig"
745
417
  },
418
+ {
419
+ "kind": "cli",
420
+ "name": "agentconfig_forAgent",
421
+ "operation": "forAgent",
422
+ "objectName": "@happyvertical/smrt-agents:AgentConfig"
423
+ },
424
+ {
425
+ "kind": "cli",
426
+ "name": "agentconfig_forAgents",
427
+ "operation": "forAgents",
428
+ "objectName": "@happyvertical/smrt-agents:AgentConfig"
429
+ },
430
+ {
431
+ "kind": "cli",
432
+ "name": "agentconfig_forSlot",
433
+ "operation": "forSlot",
434
+ "objectName": "@happyvertical/smrt-agents:AgentConfig"
435
+ },
436
+ {
437
+ "kind": "cli",
438
+ "name": "agentconfig_saveSlot",
439
+ "operation": "saveSlot",
440
+ "objectName": "@happyvertical/smrt-agents:AgentConfig"
441
+ },
746
442
  {
747
443
  "kind": "mcp",
748
444
  "name": "agentconfig_list",
@@ -799,7 +495,68 @@
799
495
  "returns": "Promise<AgentConfig[]>"
800
496
  }
801
497
  ],
802
- "surfaces": [],
498
+ "surfaces": [
499
+ {
500
+ "kind": "api",
501
+ "name": "agentconfigs.findByTenant",
502
+ "operation": "findByTenant",
503
+ "objectName": "@happyvertical/smrt-agents:AgentConfigCollection",
504
+ "path": "/agentconfigs/findByTenant",
505
+ "method": "POST"
506
+ },
507
+ {
508
+ "kind": "api",
509
+ "name": "agentconfigs.findGlobal",
510
+ "operation": "findGlobal",
511
+ "objectName": "@happyvertical/smrt-agents:AgentConfigCollection",
512
+ "path": "/agentconfigs/findGlobal",
513
+ "method": "POST"
514
+ },
515
+ {
516
+ "kind": "api",
517
+ "name": "agentconfigs.findWithGlobals",
518
+ "operation": "findWithGlobals",
519
+ "objectName": "@happyvertical/smrt-agents:AgentConfigCollection",
520
+ "path": "/agentconfigs/findWithGlobals",
521
+ "method": "POST"
522
+ },
523
+ {
524
+ "kind": "cli",
525
+ "name": "agentconfigcollection_findByTenant",
526
+ "operation": "findByTenant",
527
+ "objectName": "@happyvertical/smrt-agents:AgentConfigCollection"
528
+ },
529
+ {
530
+ "kind": "cli",
531
+ "name": "agentconfigcollection_findGlobal",
532
+ "operation": "findGlobal",
533
+ "objectName": "@happyvertical/smrt-agents:AgentConfigCollection"
534
+ },
535
+ {
536
+ "kind": "cli",
537
+ "name": "agentconfigcollection_findWithGlobals",
538
+ "operation": "findWithGlobals",
539
+ "objectName": "@happyvertical/smrt-agents:AgentConfigCollection"
540
+ },
541
+ {
542
+ "kind": "mcp",
543
+ "name": "agentconfigcollection_findbytenant",
544
+ "operation": "findByTenant",
545
+ "objectName": "@happyvertical/smrt-agents:AgentConfigCollection"
546
+ },
547
+ {
548
+ "kind": "mcp",
549
+ "name": "agentconfigcollection_findglobal",
550
+ "operation": "findGlobal",
551
+ "objectName": "@happyvertical/smrt-agents:AgentConfigCollection"
552
+ },
553
+ {
554
+ "kind": "mcp",
555
+ "name": "agentconfigcollection_findwithglobals",
556
+ "operation": "findWithGlobals",
557
+ "objectName": "@happyvertical/smrt-agents:AgentConfigCollection"
558
+ }
559
+ ],
803
560
  "relationshipFeatures": [
804
561
  "uuidColumns"
805
562
  ],
@@ -1143,7 +900,108 @@
1143
900
  "returns": "Promise<AgentSchedule[]>"
1144
901
  }
1145
902
  ],
1146
- "surfaces": [],
903
+ "surfaces": [
904
+ {
905
+ "kind": "api",
906
+ "name": "agentschedules.findByTenant",
907
+ "operation": "findByTenant",
908
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection",
909
+ "path": "/agentschedules/findByTenant",
910
+ "method": "POST"
911
+ },
912
+ {
913
+ "kind": "api",
914
+ "name": "agentschedules.findGlobal",
915
+ "operation": "findGlobal",
916
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection",
917
+ "path": "/agentschedules/findGlobal",
918
+ "method": "POST"
919
+ },
920
+ {
921
+ "kind": "api",
922
+ "name": "agentschedules.findWithGlobals",
923
+ "operation": "findWithGlobals",
924
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection",
925
+ "path": "/agentschedules/findWithGlobals",
926
+ "method": "POST"
927
+ },
928
+ {
929
+ "kind": "api",
930
+ "name": "agentschedules.listByStatus",
931
+ "operation": "listByStatus",
932
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection",
933
+ "path": "/agentschedules/listByStatus",
934
+ "method": "POST"
935
+ },
936
+ {
937
+ "kind": "api",
938
+ "name": "agentschedules.listByAgentType",
939
+ "operation": "listByAgentType",
940
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection",
941
+ "path": "/agentschedules/listByAgentType",
942
+ "method": "POST"
943
+ },
944
+ {
945
+ "kind": "cli",
946
+ "name": "agentschedulecollection_findByTenant",
947
+ "operation": "findByTenant",
948
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
949
+ },
950
+ {
951
+ "kind": "cli",
952
+ "name": "agentschedulecollection_findGlobal",
953
+ "operation": "findGlobal",
954
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
955
+ },
956
+ {
957
+ "kind": "cli",
958
+ "name": "agentschedulecollection_findWithGlobals",
959
+ "operation": "findWithGlobals",
960
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
961
+ },
962
+ {
963
+ "kind": "cli",
964
+ "name": "agentschedulecollection_listByStatus",
965
+ "operation": "listByStatus",
966
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
967
+ },
968
+ {
969
+ "kind": "cli",
970
+ "name": "agentschedulecollection_listByAgentType",
971
+ "operation": "listByAgentType",
972
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
973
+ },
974
+ {
975
+ "kind": "mcp",
976
+ "name": "agentschedulecollection_findbytenant",
977
+ "operation": "findByTenant",
978
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
979
+ },
980
+ {
981
+ "kind": "mcp",
982
+ "name": "agentschedulecollection_findglobal",
983
+ "operation": "findGlobal",
984
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
985
+ },
986
+ {
987
+ "kind": "mcp",
988
+ "name": "agentschedulecollection_findwithglobals",
989
+ "operation": "findWithGlobals",
990
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
991
+ },
992
+ {
993
+ "kind": "mcp",
994
+ "name": "agentschedulecollection_listbystatus",
995
+ "operation": "listByStatus",
996
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
997
+ },
998
+ {
999
+ "kind": "mcp",
1000
+ "name": "agentschedulecollection_listbyagenttype",
1001
+ "operation": "listByAgentType",
1002
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
1003
+ }
1004
+ ],
1147
1005
  "relationshipFeatures": [
1148
1006
  "uuidColumns"
1149
1007
  ],
@@ -1341,7 +1199,128 @@
1341
1199
  "returns": "Promise<TenantAgent>"
1342
1200
  }
1343
1201
  ],
1344
- "surfaces": [],
1202
+ "surfaces": [
1203
+ {
1204
+ "kind": "api",
1205
+ "name": "tenantagents.resolveForTenant",
1206
+ "operation": "resolveForTenant",
1207
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection",
1208
+ "path": "/tenantagents/resolveForTenant",
1209
+ "method": "POST"
1210
+ },
1211
+ {
1212
+ "kind": "api",
1213
+ "name": "tenantagents.enableAgent",
1214
+ "operation": "enableAgent",
1215
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection",
1216
+ "path": "/tenantagents/enableAgent",
1217
+ "method": "POST"
1218
+ },
1219
+ {
1220
+ "kind": "api",
1221
+ "name": "tenantagents.disableAgent",
1222
+ "operation": "disableAgent",
1223
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection",
1224
+ "path": "/tenantagents/disableAgent",
1225
+ "method": "POST"
1226
+ },
1227
+ {
1228
+ "kind": "api",
1229
+ "name": "tenantagents.clearOverride",
1230
+ "operation": "clearOverride",
1231
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection",
1232
+ "path": "/tenantagents/clearOverride",
1233
+ "method": "POST"
1234
+ },
1235
+ {
1236
+ "kind": "api",
1237
+ "name": "tenantagents.setPermissions",
1238
+ "operation": "setPermissions",
1239
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection",
1240
+ "path": "/tenantagents/setPermissions",
1241
+ "method": "POST"
1242
+ },
1243
+ {
1244
+ "kind": "api",
1245
+ "name": "tenantagents.findByTenantAndClass",
1246
+ "operation": "findByTenantAndClass",
1247
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection",
1248
+ "path": "/tenantagents/findByTenantAndClass",
1249
+ "method": "POST"
1250
+ },
1251
+ {
1252
+ "kind": "cli",
1253
+ "name": "tenantagentcollection_resolveForTenant",
1254
+ "operation": "resolveForTenant",
1255
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1256
+ },
1257
+ {
1258
+ "kind": "cli",
1259
+ "name": "tenantagentcollection_enableAgent",
1260
+ "operation": "enableAgent",
1261
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1262
+ },
1263
+ {
1264
+ "kind": "cli",
1265
+ "name": "tenantagentcollection_disableAgent",
1266
+ "operation": "disableAgent",
1267
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1268
+ },
1269
+ {
1270
+ "kind": "cli",
1271
+ "name": "tenantagentcollection_clearOverride",
1272
+ "operation": "clearOverride",
1273
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1274
+ },
1275
+ {
1276
+ "kind": "cli",
1277
+ "name": "tenantagentcollection_setPermissions",
1278
+ "operation": "setPermissions",
1279
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1280
+ },
1281
+ {
1282
+ "kind": "cli",
1283
+ "name": "tenantagentcollection_findByTenantAndClass",
1284
+ "operation": "findByTenantAndClass",
1285
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1286
+ },
1287
+ {
1288
+ "kind": "mcp",
1289
+ "name": "tenantagentcollection_resolvefortenant",
1290
+ "operation": "resolveForTenant",
1291
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1292
+ },
1293
+ {
1294
+ "kind": "mcp",
1295
+ "name": "tenantagentcollection_enableagent",
1296
+ "operation": "enableAgent",
1297
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1298
+ },
1299
+ {
1300
+ "kind": "mcp",
1301
+ "name": "tenantagentcollection_disableagent",
1302
+ "operation": "disableAgent",
1303
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1304
+ },
1305
+ {
1306
+ "kind": "mcp",
1307
+ "name": "tenantagentcollection_clearoverride",
1308
+ "operation": "clearOverride",
1309
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1310
+ },
1311
+ {
1312
+ "kind": "mcp",
1313
+ "name": "tenantagentcollection_setpermissions",
1314
+ "operation": "setPermissions",
1315
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1316
+ },
1317
+ {
1318
+ "kind": "mcp",
1319
+ "name": "tenantagentcollection_findbytenantandclass",
1320
+ "operation": "findByTenantAndClass",
1321
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1322
+ }
1323
+ ],
1345
1324
  "relationshipFeatures": [
1346
1325
  "uuidColumns"
1347
1326
  ],
@@ -1420,6 +1399,30 @@
1420
1399
  "operation": "delete",
1421
1400
  "objectName": "@happyvertical/smrt-agents:AgentConfig"
1422
1401
  },
1402
+ {
1403
+ "kind": "cli",
1404
+ "name": "agentconfig_forAgent",
1405
+ "operation": "forAgent",
1406
+ "objectName": "@happyvertical/smrt-agents:AgentConfig"
1407
+ },
1408
+ {
1409
+ "kind": "cli",
1410
+ "name": "agentconfig_forAgents",
1411
+ "operation": "forAgents",
1412
+ "objectName": "@happyvertical/smrt-agents:AgentConfig"
1413
+ },
1414
+ {
1415
+ "kind": "cli",
1416
+ "name": "agentconfig_forSlot",
1417
+ "operation": "forSlot",
1418
+ "objectName": "@happyvertical/smrt-agents:AgentConfig"
1419
+ },
1420
+ {
1421
+ "kind": "cli",
1422
+ "name": "agentconfig_saveSlot",
1423
+ "operation": "saveSlot",
1424
+ "objectName": "@happyvertical/smrt-agents:AgentConfig"
1425
+ },
1423
1426
  {
1424
1427
  "kind": "mcp",
1425
1428
  "name": "agentconfig_list",
@@ -1432,6 +1435,66 @@
1432
1435
  "operation": "get",
1433
1436
  "objectName": "@happyvertical/smrt-agents:AgentConfig"
1434
1437
  },
1438
+ {
1439
+ "kind": "api",
1440
+ "name": "agentconfigs.findByTenant",
1441
+ "operation": "findByTenant",
1442
+ "objectName": "@happyvertical/smrt-agents:AgentConfigCollection",
1443
+ "path": "/agentconfigs/findByTenant",
1444
+ "method": "POST"
1445
+ },
1446
+ {
1447
+ "kind": "api",
1448
+ "name": "agentconfigs.findGlobal",
1449
+ "operation": "findGlobal",
1450
+ "objectName": "@happyvertical/smrt-agents:AgentConfigCollection",
1451
+ "path": "/agentconfigs/findGlobal",
1452
+ "method": "POST"
1453
+ },
1454
+ {
1455
+ "kind": "api",
1456
+ "name": "agentconfigs.findWithGlobals",
1457
+ "operation": "findWithGlobals",
1458
+ "objectName": "@happyvertical/smrt-agents:AgentConfigCollection",
1459
+ "path": "/agentconfigs/findWithGlobals",
1460
+ "method": "POST"
1461
+ },
1462
+ {
1463
+ "kind": "cli",
1464
+ "name": "agentconfigcollection_findByTenant",
1465
+ "operation": "findByTenant",
1466
+ "objectName": "@happyvertical/smrt-agents:AgentConfigCollection"
1467
+ },
1468
+ {
1469
+ "kind": "cli",
1470
+ "name": "agentconfigcollection_findGlobal",
1471
+ "operation": "findGlobal",
1472
+ "objectName": "@happyvertical/smrt-agents:AgentConfigCollection"
1473
+ },
1474
+ {
1475
+ "kind": "cli",
1476
+ "name": "agentconfigcollection_findWithGlobals",
1477
+ "operation": "findWithGlobals",
1478
+ "objectName": "@happyvertical/smrt-agents:AgentConfigCollection"
1479
+ },
1480
+ {
1481
+ "kind": "mcp",
1482
+ "name": "agentconfigcollection_findbytenant",
1483
+ "operation": "findByTenant",
1484
+ "objectName": "@happyvertical/smrt-agents:AgentConfigCollection"
1485
+ },
1486
+ {
1487
+ "kind": "mcp",
1488
+ "name": "agentconfigcollection_findglobal",
1489
+ "operation": "findGlobal",
1490
+ "objectName": "@happyvertical/smrt-agents:AgentConfigCollection"
1491
+ },
1492
+ {
1493
+ "kind": "mcp",
1494
+ "name": "agentconfigcollection_findwithglobals",
1495
+ "operation": "findWithGlobals",
1496
+ "objectName": "@happyvertical/smrt-agents:AgentConfigCollection"
1497
+ },
1435
1498
  {
1436
1499
  "kind": "api",
1437
1500
  "name": "agentschedules.list",
@@ -1526,6 +1589,106 @@
1526
1589
  "operation": "get",
1527
1590
  "objectName": "@happyvertical/smrt-agents:AgentSchedule"
1528
1591
  },
1592
+ {
1593
+ "kind": "api",
1594
+ "name": "agentschedules.findByTenant",
1595
+ "operation": "findByTenant",
1596
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection",
1597
+ "path": "/agentschedules/findByTenant",
1598
+ "method": "POST"
1599
+ },
1600
+ {
1601
+ "kind": "api",
1602
+ "name": "agentschedules.findGlobal",
1603
+ "operation": "findGlobal",
1604
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection",
1605
+ "path": "/agentschedules/findGlobal",
1606
+ "method": "POST"
1607
+ },
1608
+ {
1609
+ "kind": "api",
1610
+ "name": "agentschedules.findWithGlobals",
1611
+ "operation": "findWithGlobals",
1612
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection",
1613
+ "path": "/agentschedules/findWithGlobals",
1614
+ "method": "POST"
1615
+ },
1616
+ {
1617
+ "kind": "api",
1618
+ "name": "agentschedules.listByStatus",
1619
+ "operation": "listByStatus",
1620
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection",
1621
+ "path": "/agentschedules/listByStatus",
1622
+ "method": "POST"
1623
+ },
1624
+ {
1625
+ "kind": "api",
1626
+ "name": "agentschedules.listByAgentType",
1627
+ "operation": "listByAgentType",
1628
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection",
1629
+ "path": "/agentschedules/listByAgentType",
1630
+ "method": "POST"
1631
+ },
1632
+ {
1633
+ "kind": "cli",
1634
+ "name": "agentschedulecollection_findByTenant",
1635
+ "operation": "findByTenant",
1636
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
1637
+ },
1638
+ {
1639
+ "kind": "cli",
1640
+ "name": "agentschedulecollection_findGlobal",
1641
+ "operation": "findGlobal",
1642
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
1643
+ },
1644
+ {
1645
+ "kind": "cli",
1646
+ "name": "agentschedulecollection_findWithGlobals",
1647
+ "operation": "findWithGlobals",
1648
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
1649
+ },
1650
+ {
1651
+ "kind": "cli",
1652
+ "name": "agentschedulecollection_listByStatus",
1653
+ "operation": "listByStatus",
1654
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
1655
+ },
1656
+ {
1657
+ "kind": "cli",
1658
+ "name": "agentschedulecollection_listByAgentType",
1659
+ "operation": "listByAgentType",
1660
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
1661
+ },
1662
+ {
1663
+ "kind": "mcp",
1664
+ "name": "agentschedulecollection_findbytenant",
1665
+ "operation": "findByTenant",
1666
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
1667
+ },
1668
+ {
1669
+ "kind": "mcp",
1670
+ "name": "agentschedulecollection_findglobal",
1671
+ "operation": "findGlobal",
1672
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
1673
+ },
1674
+ {
1675
+ "kind": "mcp",
1676
+ "name": "agentschedulecollection_findwithglobals",
1677
+ "operation": "findWithGlobals",
1678
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
1679
+ },
1680
+ {
1681
+ "kind": "mcp",
1682
+ "name": "agentschedulecollection_listbystatus",
1683
+ "operation": "listByStatus",
1684
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
1685
+ },
1686
+ {
1687
+ "kind": "mcp",
1688
+ "name": "agentschedulecollection_listbyagenttype",
1689
+ "operation": "listByAgentType",
1690
+ "objectName": "@happyvertical/smrt-agents:AgentScheduleCollection"
1691
+ },
1529
1692
  {
1530
1693
  "kind": "api",
1531
1694
  "name": "tenantagents.list",
@@ -1589,6 +1752,126 @@
1589
1752
  "name": "tenantagent_get",
1590
1753
  "operation": "get",
1591
1754
  "objectName": "@happyvertical/smrt-agents:TenantAgent"
1755
+ },
1756
+ {
1757
+ "kind": "api",
1758
+ "name": "tenantagents.resolveForTenant",
1759
+ "operation": "resolveForTenant",
1760
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection",
1761
+ "path": "/tenantagents/resolveForTenant",
1762
+ "method": "POST"
1763
+ },
1764
+ {
1765
+ "kind": "api",
1766
+ "name": "tenantagents.enableAgent",
1767
+ "operation": "enableAgent",
1768
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection",
1769
+ "path": "/tenantagents/enableAgent",
1770
+ "method": "POST"
1771
+ },
1772
+ {
1773
+ "kind": "api",
1774
+ "name": "tenantagents.disableAgent",
1775
+ "operation": "disableAgent",
1776
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection",
1777
+ "path": "/tenantagents/disableAgent",
1778
+ "method": "POST"
1779
+ },
1780
+ {
1781
+ "kind": "api",
1782
+ "name": "tenantagents.clearOverride",
1783
+ "operation": "clearOverride",
1784
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection",
1785
+ "path": "/tenantagents/clearOverride",
1786
+ "method": "POST"
1787
+ },
1788
+ {
1789
+ "kind": "api",
1790
+ "name": "tenantagents.setPermissions",
1791
+ "operation": "setPermissions",
1792
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection",
1793
+ "path": "/tenantagents/setPermissions",
1794
+ "method": "POST"
1795
+ },
1796
+ {
1797
+ "kind": "api",
1798
+ "name": "tenantagents.findByTenantAndClass",
1799
+ "operation": "findByTenantAndClass",
1800
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection",
1801
+ "path": "/tenantagents/findByTenantAndClass",
1802
+ "method": "POST"
1803
+ },
1804
+ {
1805
+ "kind": "cli",
1806
+ "name": "tenantagentcollection_resolveForTenant",
1807
+ "operation": "resolveForTenant",
1808
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1809
+ },
1810
+ {
1811
+ "kind": "cli",
1812
+ "name": "tenantagentcollection_enableAgent",
1813
+ "operation": "enableAgent",
1814
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1815
+ },
1816
+ {
1817
+ "kind": "cli",
1818
+ "name": "tenantagentcollection_disableAgent",
1819
+ "operation": "disableAgent",
1820
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1821
+ },
1822
+ {
1823
+ "kind": "cli",
1824
+ "name": "tenantagentcollection_clearOverride",
1825
+ "operation": "clearOverride",
1826
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1827
+ },
1828
+ {
1829
+ "kind": "cli",
1830
+ "name": "tenantagentcollection_setPermissions",
1831
+ "operation": "setPermissions",
1832
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1833
+ },
1834
+ {
1835
+ "kind": "cli",
1836
+ "name": "tenantagentcollection_findByTenantAndClass",
1837
+ "operation": "findByTenantAndClass",
1838
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1839
+ },
1840
+ {
1841
+ "kind": "mcp",
1842
+ "name": "tenantagentcollection_resolvefortenant",
1843
+ "operation": "resolveForTenant",
1844
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1845
+ },
1846
+ {
1847
+ "kind": "mcp",
1848
+ "name": "tenantagentcollection_enableagent",
1849
+ "operation": "enableAgent",
1850
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1851
+ },
1852
+ {
1853
+ "kind": "mcp",
1854
+ "name": "tenantagentcollection_disableagent",
1855
+ "operation": "disableAgent",
1856
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1857
+ },
1858
+ {
1859
+ "kind": "mcp",
1860
+ "name": "tenantagentcollection_clearoverride",
1861
+ "operation": "clearOverride",
1862
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1863
+ },
1864
+ {
1865
+ "kind": "mcp",
1866
+ "name": "tenantagentcollection_setpermissions",
1867
+ "operation": "setPermissions",
1868
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1869
+ },
1870
+ {
1871
+ "kind": "mcp",
1872
+ "name": "tenantagentcollection_findbytenantandclass",
1873
+ "operation": "findByTenantAndClass",
1874
+ "objectName": "@happyvertical/smrt-agents:TenantAgentCollection"
1592
1875
  }
1593
1876
  ],
1594
1877
  "prompts": [],
@@ -1600,5 +1883,5 @@
1600
1883
  "polymorphicAssociations": 0,
1601
1884
  "uuidColumns": 11
1602
1885
  },
1603
- "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## 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/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"
1886
+ "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"
1604
1887
  }