@pikku/core 0.12.72 → 0.12.74

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 (811) hide show
  1. package/CHANGELOG.md +793 -0
  2. package/dist/crypto-utils.d.ts +30 -5
  3. package/dist/crypto-utils.js +146 -41
  4. package/dist/dev/hot-reload.js +11 -30
  5. package/dist/dev/module-runner.d.ts +3 -7
  6. package/dist/dev/module-runner.js +4 -10
  7. package/dist/dev/reload-meta.d.ts +8 -20
  8. package/dist/dev/reload-meta.js +9 -29
  9. package/dist/errors/error-handler.d.ts +5 -30
  10. package/dist/errors/error-handler.js +16 -32
  11. package/dist/errors/errors.d.ts +32 -151
  12. package/dist/errors/errors.js +55 -157
  13. package/dist/function/abort-scope.d.ts +47 -0
  14. package/dist/function/abort-scope.js +63 -0
  15. package/dist/function/function-runner.js +37 -32
  16. package/dist/function/functions.types.d.ts +44 -136
  17. package/dist/function/functions.types.js +0 -58
  18. package/dist/function/list.types.d.ts +12 -62
  19. package/dist/function/list.types.js +4 -25
  20. package/dist/handle-error.d.ts +0 -13
  21. package/dist/handle-error.js +0 -18
  22. package/dist/index.d.ts +5 -2
  23. package/dist/index.js +4 -1
  24. package/dist/middleware/auth-apikey.d.ts +3 -18
  25. package/dist/middleware/auth-apikey.js +0 -17
  26. package/dist/middleware/auth-bearer.d.ts +6 -41
  27. package/dist/middleware/auth-bearer.js +3 -40
  28. package/dist/middleware/auth-cookie.d.ts +5 -27
  29. package/dist/middleware/auth-cookie.js +2 -26
  30. package/dist/middleware/cors.d.ts +7 -34
  31. package/dist/middleware/cors.js +7 -34
  32. package/dist/middleware/remote-auth.d.ts +3 -1
  33. package/dist/middleware/remote-auth.js +3 -2
  34. package/dist/middleware/telemetry.d.ts +8 -33
  35. package/dist/middleware/telemetry.js +2 -31
  36. package/dist/middleware-runner.d.ts +4 -55
  37. package/dist/middleware-runner.js +5 -74
  38. package/dist/permissions.d.ts +3 -44
  39. package/dist/permissions.js +19 -71
  40. package/dist/pikku-request.d.ts +0 -6
  41. package/dist/pikku-request.js +0 -6
  42. package/dist/pikku-state.d.ts +0 -26
  43. package/dist/pikku-state.js +2 -30
  44. package/dist/remote.d.ts +3 -5
  45. package/dist/remote.js +8 -7
  46. package/dist/schema.d.ts +5 -39
  47. package/dist/schema.js +5 -39
  48. package/dist/scopes.d.ts +4 -23
  49. package/dist/scopes.js +7 -48
  50. package/dist/services/ai-agent-runner-service.d.ts +20 -0
  51. package/dist/services/ai-embedding-service.d.ts +2 -25
  52. package/dist/services/audit-service.js +1 -2
  53. package/dist/services/content-service.d.ts +1 -46
  54. package/dist/services/credential-service.d.ts +3 -40
  55. package/dist/services/deployment-service.d.ts +3 -9
  56. package/dist/services/gateway-service.d.ts +0 -15
  57. package/dist/services/http-personas.d.ts +80 -0
  58. package/dist/services/http-personas.js +233 -0
  59. package/dist/services/in-memory-queue-service.d.ts +0 -14
  60. package/dist/services/in-memory-queue-service.js +1 -15
  61. package/dist/services/in-memory-trigger-service.d.ts +0 -18
  62. package/dist/services/in-memory-trigger-service.js +1 -18
  63. package/dist/services/in-memory-workflow-service.d.ts +0 -16
  64. package/dist/services/in-memory-workflow-service.js +4 -33
  65. package/dist/services/index.d.ts +5 -6
  66. package/dist/services/index.js +2 -5
  67. package/dist/services/istanbul-coverage-service.d.ts +1 -5
  68. package/dist/services/istanbul-coverage-service.js +2 -8
  69. package/dist/services/jwt-service.d.ts +1 -16
  70. package/dist/services/local-content.d.ts +13 -2
  71. package/dist/services/local-content.js +40 -13
  72. package/dist/services/local-gateway-service.d.ts +0 -16
  73. package/dist/services/local-gateway-service.js +2 -17
  74. package/dist/services/local-secrets.d.ts +0 -4
  75. package/dist/services/local-secrets.js +0 -4
  76. package/dist/services/logger-console.d.ts +3 -7
  77. package/dist/services/logger-console.js +3 -7
  78. package/dist/services/logger.d.ts +2 -37
  79. package/dist/services/meta-service.d.ts +23 -26
  80. package/dist/services/meta-service.js +22 -36
  81. package/dist/services/personas-service.d.ts +134 -0
  82. package/dist/services/personas-service.js +40 -0
  83. package/dist/services/pikku-user-id.js +0 -4
  84. package/dist/services/queue-webhook-service.d.ts +2 -36
  85. package/dist/services/queue-webhook-service.js +9 -41
  86. package/dist/services/scheduler-service.d.ts +1 -50
  87. package/dist/services/scheduler-service.js +0 -10
  88. package/dist/services/schema-service.d.ts +1 -24
  89. package/dist/services/scope-service.d.ts +49 -34
  90. package/dist/services/scoped-secret-service.d.ts +0 -4
  91. package/dist/services/scoped-secret-service.js +0 -4
  92. package/dist/services/secret-host-binding.d.ts +8 -0
  93. package/dist/services/secret-host-binding.js +36 -0
  94. package/dist/services/secret-service.d.ts +5 -33
  95. package/dist/services/secretless.d.ts +6 -0
  96. package/dist/services/secretless.js +21 -0
  97. package/dist/services/stub-tracker.d.ts +7 -18
  98. package/dist/services/stub-tracker.js +8 -18
  99. package/dist/services/system-role-guard.d.ts +33 -0
  100. package/dist/services/system-role-guard.js +38 -0
  101. package/dist/services/trigger-service.d.ts +0 -12
  102. package/dist/services/typed-secret-service.d.ts +0 -7
  103. package/dist/services/typed-secret-service.js +1 -7
  104. package/dist/services/v8-coverage-service.d.ts +2 -3
  105. package/dist/services/v8-coverage-service.js +1 -2
  106. package/dist/services/variables-service.d.ts +1 -8
  107. package/dist/services/webhook-service.d.ts +19 -63
  108. package/dist/services/webhook-service.js +6 -20
  109. package/dist/services/workflow-service.d.ts +3 -15
  110. package/dist/testing/service-tests.js +0 -17
  111. package/dist/time-utils.d.ts +0 -16
  112. package/dist/time-utils.js +1 -19
  113. package/dist/types/core.types.d.ts +99 -219
  114. package/dist/types/core.types.js +0 -42
  115. package/dist/types/state.types.d.ts +4 -9
  116. package/dist/utils/hmac.d.ts +4 -10
  117. package/dist/utils/hmac.js +4 -10
  118. package/dist/utils/safe-fetch.d.ts +7 -35
  119. package/dist/utils/safe-fetch.js +13 -53
  120. package/dist/utils.d.ts +1 -6
  121. package/dist/utils.js +6 -15
  122. package/dist/wirings/actor-flow/actor-flow.types.d.ts +1 -34
  123. package/dist/wirings/actor-flow/index.d.ts +0 -9
  124. package/dist/wirings/actor-flow/run-conversation.d.ts +5 -5
  125. package/dist/wirings/actor-flow/run-conversation.js +14 -7
  126. package/dist/wirings/ai-agent/ai-agent-agui.d.ts +0 -5
  127. package/dist/wirings/ai-agent/ai-agent-agui.js +34 -12
  128. package/dist/wirings/ai-agent/ai-agent-helpers.d.ts +7 -0
  129. package/dist/wirings/ai-agent/ai-agent-helpers.js +7 -0
  130. package/dist/wirings/ai-agent/ai-agent-interrupt.d.ts +153 -0
  131. package/dist/wirings/ai-agent/ai-agent-interrupt.js +256 -0
  132. package/dist/wirings/ai-agent/ai-agent-memory.js +0 -2
  133. package/dist/wirings/ai-agent/ai-agent-model-config.d.ts +0 -9
  134. package/dist/wirings/ai-agent/ai-agent-model-config.js +1 -9
  135. package/dist/wirings/ai-agent/ai-agent-prepare.d.ts +10 -99
  136. package/dist/wirings/ai-agent/ai-agent-prepare.js +58 -131
  137. package/dist/wirings/ai-agent/ai-agent-registry.d.ts +2 -1
  138. package/dist/wirings/ai-agent/ai-agent-registry.js +5 -1
  139. package/dist/wirings/ai-agent/ai-agent-runner.js +49 -20
  140. package/dist/wirings/ai-agent/ai-agent-stream.d.ts +25 -2
  141. package/dist/wirings/ai-agent/ai-agent-stream.js +153 -63
  142. package/dist/wirings/ai-agent/ai-agent.types.d.ts +84 -4
  143. package/dist/wirings/ai-agent/index.d.ts +6 -4
  144. package/dist/wirings/ai-agent/index.js +5 -4
  145. package/dist/wirings/ai-agent/voice-input.d.ts +39 -1
  146. package/dist/wirings/ai-agent/voice-input.js +46 -3
  147. package/dist/wirings/ai-agent/voice-output.d.ts +54 -1
  148. package/dist/wirings/ai-agent/voice-output.js +153 -50
  149. package/dist/wirings/channel/channel-common.d.ts +7 -20
  150. package/dist/wirings/channel/channel-common.js +7 -21
  151. package/dist/wirings/channel/channel-handler.js +25 -6
  152. package/dist/wirings/channel/channel-host-rpc.d.ts +25 -0
  153. package/dist/wirings/channel/channel-host-rpc.js +38 -0
  154. package/dist/wirings/channel/channel-middleware-runner.d.ts +0 -12
  155. package/dist/wirings/channel/channel-middleware-runner.js +0 -12
  156. package/dist/wirings/channel/channel-rpc-registry.d.ts +31 -0
  157. package/dist/wirings/channel/channel-rpc-registry.js +89 -0
  158. package/dist/wirings/channel/channel-rpc-responder.d.ts +15 -0
  159. package/dist/wirings/channel/channel-rpc-responder.js +71 -0
  160. package/dist/wirings/channel/channel-rpc-service.d.ts +40 -0
  161. package/dist/wirings/channel/channel-rpc-service.js +106 -0
  162. package/dist/wirings/channel/channel-rpc-validators.d.ts +14 -0
  163. package/dist/wirings/channel/channel-rpc-validators.js +30 -0
  164. package/dist/wirings/channel/channel-rpc.d.ts +5 -0
  165. package/dist/wirings/channel/channel-rpc.js +5 -0
  166. package/dist/wirings/channel/channel-rpc.types.d.ts +90 -0
  167. package/dist/wirings/channel/channel-rpc.types.js +50 -0
  168. package/dist/wirings/channel/channel-runner.d.ts +0 -4
  169. package/dist/wirings/channel/channel-runner.js +0 -14
  170. package/dist/wirings/channel/channel-store.d.ts +0 -10
  171. package/dist/wirings/channel/channel.types.d.ts +12 -1
  172. package/dist/wirings/channel/define-channel-routes.d.ts +0 -20
  173. package/dist/wirings/channel/define-channel-routes.js +0 -20
  174. package/dist/wirings/channel/eventhub-service.d.ts +0 -18
  175. package/dist/wirings/channel/index.d.ts +4 -1
  176. package/dist/wirings/channel/index.js +2 -0
  177. package/dist/wirings/channel/local/local-channel-runner.js +3 -1
  178. package/dist/wirings/channel/local/local-eventhub-service.d.ts +0 -33
  179. package/dist/wirings/channel/local/local-eventhub-service.js +2 -36
  180. package/dist/wirings/channel/log-channels.d.ts +0 -4
  181. package/dist/wirings/channel/log-channels.js +0 -4
  182. package/dist/wirings/channel/pikku-abstract-channel-handler.js +6 -0
  183. package/dist/wirings/channel/serverless/serverless-channel-runner.js +2 -5
  184. package/dist/wirings/cli/channel/cli-approval.d.ts +41 -0
  185. package/dist/wirings/cli/channel/cli-approval.js +81 -0
  186. package/dist/wirings/cli/channel/cli-channel-runner.d.ts +0 -4
  187. package/dist/wirings/cli/channel/cli-channel-runner.js +3 -25
  188. package/dist/wirings/cli/channel/cli-raw-channel-runner.d.ts +47 -9
  189. package/dist/wirings/cli/channel/cli-raw-channel-runner.js +24 -16
  190. package/dist/wirings/cli/channel/cli-raw-client-runner.d.ts +20 -0
  191. package/dist/wirings/cli/channel/cli-raw-client-runner.js +121 -0
  192. package/dist/wirings/cli/channel/index.d.ts +4 -0
  193. package/dist/wirings/cli/channel/index.js +2 -0
  194. package/dist/wirings/cli/cli-runner.d.ts +20 -20
  195. package/dist/wirings/cli/cli-runner.js +28 -89
  196. package/dist/wirings/cli/cli.types.d.ts +14 -3
  197. package/dist/wirings/cli/command-parser.d.ts +1 -10
  198. package/dist/wirings/cli/command-parser.js +10 -87
  199. package/dist/wirings/cli/define-cli-commands.d.ts +1 -17
  200. package/dist/wirings/cli/define-cli-commands.js +1 -17
  201. package/dist/wirings/credential/credential.types.d.ts +0 -12
  202. package/dist/wirings/credential/define-credential.d.ts +48 -0
  203. package/dist/wirings/credential/define-credential.js +47 -0
  204. package/dist/wirings/credential/index.d.ts +1 -1
  205. package/dist/wirings/credential/index.js +1 -1
  206. package/dist/wirings/credential/validate-credential-definitions.d.ts +2 -4
  207. package/dist/wirings/gateway/gateway-runner.d.ts +1 -20
  208. package/dist/wirings/gateway/gateway-runner.js +8 -105
  209. package/dist/wirings/gateway/gateway.types.d.ts +7 -80
  210. package/dist/wirings/http/http-routes.d.ts +0 -63
  211. package/dist/wirings/http/http-routes.js +0 -63
  212. package/dist/wirings/http/http-runner.d.ts +0 -99
  213. package/dist/wirings/http/http-runner.js +9 -165
  214. package/dist/wirings/http/http.types.d.ts +14 -55
  215. package/dist/wirings/http/log-http-routes.d.ts +0 -4
  216. package/dist/wirings/http/log-http-routes.js +0 -4
  217. package/dist/wirings/http/pikku-fetch-http-request.d.ts +0 -40
  218. package/dist/wirings/http/pikku-fetch-http-request.js +0 -58
  219. package/dist/wirings/http/pikku-fetch-http-response.js +0 -3
  220. package/dist/wirings/http/routers/path-to-regex.js +2 -13
  221. package/dist/wirings/http/web-request.d.ts +0 -8
  222. package/dist/wirings/http/web-request.js +25 -17
  223. package/dist/wirings/mcp/mcp-runner.d.ts +1 -4
  224. package/dist/wirings/mcp/mcp-runner.js +1 -14
  225. package/dist/wirings/mcp/mcp.types.d.ts +2 -35
  226. package/dist/wirings/oauth2/oauth2.types.d.ts +0 -28
  227. package/dist/wirings/oauth2/oauth2.types.js +0 -3
  228. package/dist/wirings/persona/define-personas.d.ts +28 -0
  229. package/dist/wirings/persona/define-personas.js +27 -0
  230. package/dist/wirings/persona/index.d.ts +21 -0
  231. package/dist/wirings/persona/index.js +17 -0
  232. package/dist/wirings/persona/persona-email.d.ts +37 -0
  233. package/dist/wirings/persona/persona-email.js +69 -0
  234. package/dist/wirings/persona/persona-environments.d.ts +45 -0
  235. package/dist/wirings/persona/persona-environments.js +81 -0
  236. package/dist/wirings/persona/persona-mailbox.d.ts +101 -0
  237. package/dist/wirings/persona/persona-mailbox.js +53 -0
  238. package/dist/wirings/persona/persona.types.d.ts +125 -0
  239. package/dist/wirings/persona/persona.types.js +1 -0
  240. package/dist/wirings/persona/validate-personas.d.ts +53 -0
  241. package/dist/wirings/persona/validate-personas.js +94 -0
  242. package/dist/wirings/queue/index.d.ts +3 -0
  243. package/dist/wirings/queue/index.js +2 -3
  244. package/dist/wirings/queue/queue-identity.d.ts +28 -0
  245. package/dist/wirings/queue/queue-identity.js +102 -0
  246. package/dist/wirings/queue/queue-runner.d.ts +0 -19
  247. package/dist/wirings/queue/queue-runner.js +9 -30
  248. package/dist/wirings/queue/queue.types.d.ts +18 -89
  249. package/dist/wirings/queue/register-queue-helper.d.ts +0 -12
  250. package/dist/wirings/queue/register-queue-helper.js +0 -11
  251. package/dist/wirings/queue/signed-queue-service.d.ts +16 -0
  252. package/dist/wirings/queue/signed-queue-service.js +42 -0
  253. package/dist/wirings/queue/validate-worker-config.d.ts +2 -23
  254. package/dist/wirings/queue/validate-worker-config.js +0 -14
  255. package/dist/wirings/role/define-system-role.d.ts +32 -0
  256. package/dist/wirings/role/define-system-role.js +31 -0
  257. package/dist/wirings/role/index.d.ts +3 -0
  258. package/dist/wirings/role/index.js +2 -0
  259. package/dist/wirings/role/role.types.d.ts +43 -0
  260. package/dist/wirings/role/role.types.js +1 -0
  261. package/dist/wirings/role/validate-role-definitions.d.ts +21 -0
  262. package/dist/wirings/role/validate-role-definitions.js +71 -0
  263. package/dist/wirings/rpc/addon-runner.d.ts +0 -19
  264. package/dist/wirings/rpc/addon-runner.js +0 -51
  265. package/dist/wirings/rpc/remote-addon-auth.d.ts +1 -12
  266. package/dist/wirings/rpc/remote-addon-auth.js +1 -9
  267. package/dist/wirings/rpc/rpc-runner.d.ts +11 -18
  268. package/dist/wirings/rpc/rpc-runner.js +88 -105
  269. package/dist/wirings/rpc/rpc-types.d.ts +7 -6
  270. package/dist/wirings/rpc/wire-addon.d.ts +25 -0
  271. package/dist/wirings/rpc/wire-addon.js +62 -0
  272. package/dist/wirings/rpc/wire-remote-addon.d.ts +3 -28
  273. package/dist/wirings/rpc/wire-remote-addon.js +0 -8
  274. package/dist/wirings/scheduler/log-schedulers.d.ts +0 -4
  275. package/dist/wirings/scheduler/log-schedulers.js +0 -4
  276. package/dist/wirings/scheduler/scheduler-runner.d.ts +0 -1
  277. package/dist/wirings/scheduler/scheduler-runner.js +0 -1
  278. package/dist/wirings/scheduler/scheduler.types.d.ts +1 -14
  279. package/dist/wirings/scope/define-scope.d.ts +32 -0
  280. package/dist/wirings/scope/define-scope.js +31 -0
  281. package/dist/wirings/scope/index.d.ts +1 -1
  282. package/dist/wirings/scope/index.js +1 -1
  283. package/dist/wirings/scope/scope.types.d.ts +7 -9
  284. package/dist/wirings/scope/validate-scope-definitions.d.ts +2 -21
  285. package/dist/wirings/scope/validate-scope-definitions.js +3 -21
  286. package/dist/wirings/secret/index.d.ts +1 -1
  287. package/dist/wirings/secret/index.js +1 -1
  288. package/dist/wirings/secret/secret.types.d.ts +19 -15
  289. package/dist/wirings/secret/secret.types.js +1 -1
  290. package/dist/wirings/secret/validate-secret-definitions.d.ts +2 -4
  291. package/dist/wirings/trigger/trigger-runner.d.ts +0 -27
  292. package/dist/wirings/trigger/trigger-runner.js +1 -24
  293. package/dist/wirings/trigger/trigger.types.d.ts +1 -82
  294. package/dist/wirings/trigger/trigger.types.js +0 -34
  295. package/dist/wirings/variable/index.d.ts +1 -1
  296. package/dist/wirings/variable/index.js +1 -1
  297. package/dist/wirings/variable/validate-variable-definitions.d.ts +2 -4
  298. package/dist/wirings/variable/variable.types.d.ts +1 -13
  299. package/dist/wirings/variable/variable.types.js +1 -1
  300. package/dist/wirings/virtual-user/index.d.ts +27 -0
  301. package/dist/wirings/virtual-user/index.js +8 -0
  302. package/dist/wirings/virtual-user/run-virtual-user.d.ts +92 -0
  303. package/dist/wirings/virtual-user/run-virtual-user.js +478 -0
  304. package/dist/wirings/virtual-user/virtual-user-agents.d.ts +38 -0
  305. package/dist/wirings/virtual-user/virtual-user-agents.js +24 -0
  306. package/dist/wirings/virtual-user/virtual-user-catalogue.d.ts +92 -0
  307. package/dist/wirings/virtual-user/virtual-user-catalogue.js +134 -0
  308. package/dist/wirings/virtual-user/virtual-user-derive.d.ts +26 -0
  309. package/dist/wirings/virtual-user/virtual-user-derive.js +137 -0
  310. package/dist/wirings/virtual-user/virtual-user-dispositions.d.ts +79 -0
  311. package/dist/wirings/virtual-user/virtual-user-dispositions.js +128 -0
  312. package/dist/wirings/virtual-user/virtual-user-intents.d.ts +78 -0
  313. package/dist/wirings/virtual-user/virtual-user-intents.js +142 -0
  314. package/dist/wirings/virtual-user/virtual-user-rng.d.ts +24 -0
  315. package/dist/wirings/virtual-user/virtual-user-rng.js +44 -0
  316. package/dist/wirings/virtual-user/virtual-user-target.d.ts +21 -0
  317. package/dist/wirings/virtual-user/virtual-user-target.js +34 -0
  318. package/dist/wirings/virtual-user/virtual-user.types.d.ts +199 -0
  319. package/dist/wirings/virtual-user/virtual-user.types.js +8 -0
  320. package/dist/wirings/workflow/dsl/workflow-dsl.types.d.ts +5 -5
  321. package/dist/wirings/workflow/dsl/workflow-runner.d.ts +0 -4
  322. package/dist/wirings/workflow/dsl/workflow-runner.js +0 -4
  323. package/dist/wirings/workflow/feature.d.ts +0 -19
  324. package/dist/wirings/workflow/feature.js +0 -19
  325. package/dist/wirings/workflow/graph/graph-node.d.ts +0 -98
  326. package/dist/wirings/workflow/graph/graph-node.js +0 -34
  327. package/dist/wirings/workflow/graph/graph-runner.js +6 -41
  328. package/dist/wirings/workflow/graph/wire-workflow-graph.d.ts +0 -4
  329. package/dist/wirings/workflow/graph/workflow-graph.types.d.ts +0 -58
  330. package/dist/wirings/workflow/graph/workflow-graph.types.js +0 -6
  331. package/dist/wirings/workflow/index.d.ts +5 -7
  332. package/dist/wirings/workflow/index.js +3 -17
  333. package/dist/wirings/workflow/pikku-scenario-service.d.ts +87 -5
  334. package/dist/wirings/workflow/pikku-scenario-service.js +204 -42
  335. package/dist/wirings/workflow/pikku-workflow-service.d.ts +7 -459
  336. package/dist/wirings/workflow/pikku-workflow-service.js +58 -551
  337. package/dist/wirings/workflow/run-timeline.d.ts +0 -47
  338. package/dist/wirings/workflow/run-timeline.js +0 -22
  339. package/dist/wirings/workflow/scenario-cookie-jar.d.ts +0 -23
  340. package/dist/wirings/workflow/scenario-cookie-jar.js +0 -16
  341. package/dist/wirings/workflow/scenario-poll.d.ts +0 -15
  342. package/dist/wirings/workflow/scenario-poll.js +0 -12
  343. package/dist/wirings/workflow/scenario-prose.d.ts +0 -28
  344. package/dist/wirings/workflow/scenario-prose.js +0 -18
  345. package/dist/wirings/workflow/scenario-step-guards.d.ts +0 -13
  346. package/dist/wirings/workflow/scenario-step-guards.js +1 -14
  347. package/dist/wirings/workflow/scenario-step.types.d.ts +72 -6
  348. package/dist/wirings/workflow/scenario-step.types.js +5 -1
  349. package/dist/wirings/workflow/scenario-surface.d.ts +16 -0
  350. package/dist/wirings/workflow/scenario-surface.js +56 -0
  351. package/dist/wirings/workflow/workflow-invocation-id.d.ts +0 -18
  352. package/dist/wirings/workflow/workflow-invocation-id.js +2 -22
  353. package/dist/wirings/workflow/workflow-queue-workers.d.ts +0 -20
  354. package/dist/wirings/workflow/workflow-queue-workers.js +0 -19
  355. package/dist/wirings/workflow/workflow.types.d.ts +0 -197
  356. package/knowledge/decisions/index.md +19 -0
  357. package/knowledge/decisions/internals/a-secret-that-fails-to-decrypt-fails-the-whole-read.md +49 -0
  358. package/knowledge/decisions/internals/actor-flow-conversations-seed-a-hidden-kickoff-message.md +23 -0
  359. package/knowledge/decisions/internals/actor-flow-drives-the-target-through-a-transport-seam.md +24 -0
  360. package/knowledge/decisions/internals/actor-flow-verdicts-are-llm-self-evaluations.md +25 -0
  361. package/knowledge/decisions/internals/addon-package-roots-resolve-by-walking-node-module-search-paths.md +26 -0
  362. package/knowledge/decisions/internals/addon-singleton-services-are-cached-per-namespace-not-per-package.md +33 -0
  363. package/knowledge/decisions/internals/addon-workflow-names-are-prefixed-with-the-consumer-namespace.md +28 -0
  364. package/knowledge/decisions/internals/ai-agent-agui-bridge-obeys-the-client-ordering-contract.md +29 -0
  365. package/knowledge/decisions/internals/ai-agent-audio-chunks-carry-the-format-the-provider-returned.md +20 -0
  366. package/knowledge/decisions/internals/ai-agent-credential-suspensions-hide-the-tool-result.md +26 -0
  367. package/knowledge/decisions/internals/ai-agent-delegate-and-supervise-hide-different-text.md +26 -0
  368. package/knowledge/decisions/internals/ai-agent-llm-tool-arguments-have-nulls-stripped.md +23 -0
  369. package/knowledge/decisions/internals/ai-agent-model-config-stays-a-single-resolution-seam.md +25 -0
  370. package/knowledge/decisions/internals/ai-agent-onerror-hooks-cannot-change-the-failure.md +22 -0
  371. package/knowledge/decisions/internals/ai-agent-runner-methods-must-keep-their-receiver.md +22 -0
  372. package/knowledge/decisions/internals/ai-agent-stream-persistence-is-best-effort.md +27 -0
  373. package/knowledge/decisions/internals/ai-agent-sub-agents-inherit-the-parent-context-block.md +26 -0
  374. package/knowledge/decisions/internals/ai-agent-tool-execute-failures-are-logged-unconditionally.md +25 -0
  375. package/knowledge/decisions/internals/ai-agent-voice-input-transcribes-audio-parts-in-place.md +22 -0
  376. package/knowledge/decisions/internals/ai-agent-working-memory-is-persisted-only-when-valid.md +25 -0
  377. package/knowledge/decisions/internals/channel-message-handlers-accept-three-config-shapes.md +30 -0
  378. package/knowledge/decisions/internals/channel-middleware-caches-only-statically-resolved-middleware.md +31 -0
  379. package/knowledge/decisions/internals/channel-state-is-per-socket-session-state-is-per-user.md +29 -0
  380. package/knowledge/decisions/internals/channel-user-id-is-persisted-after-onconnect-middleware-runs.md +28 -0
  381. package/knowledge/decisions/internals/cli-option-names-are-camelcase-in-state-and-kebab-on-the-command-line.md +27 -0
  382. package/knowledge/decisions/internals/cli-parse-errors-are-routed-by-message-prefix.md +28 -0
  383. package/knowledge/decisions/internals/cli-stdout-is-reserved-for-machine-readable-output.md +34 -0
  384. package/knowledge/decisions/internals/cli-unknown-long-options-warn-instead-of-failing.md +29 -0
  385. package/knowledge/decisions/internals/core-data-classification-brand-is-an-optional-property.md +34 -0
  386. package/knowledge/decisions/internals/core-function-runner-restores-the-wire-fields-it-overwrites.md +44 -0
  387. package/knowledge/decisions/internals/core-hot-reload-merges-generated-meta-never-replaces-it.md +39 -0
  388. package/knowledge/decisions/internals/core-hot-reload-owns-its-module-registry.md +42 -0
  389. package/knowledge/decisions/internals/core-middleware-order-is-scope-then-priority.md +39 -0
  390. package/knowledge/decisions/internals/core-schema-defaults-apply-on-every-transport.md +43 -0
  391. package/knowledge/decisions/internals/core-scopes-are-an-and-gate-separate-from-permissions.md +38 -0
  392. package/knowledge/decisions/internals/core-state-is-a-global-map-written-only-at-registration-time.md +44 -0
  393. package/knowledge/decisions/internals/email-meta-is-read-uncached-because-codegen-rewrites-it-mid-session.md +27 -0
  394. package/knowledge/decisions/internals/gateway-adapters-resolve-lazily-and-are-promise-cached.md +32 -0
  395. package/knowledge/decisions/internals/gateway-webhook-challenges-echo-bytes-not-json.md +28 -0
  396. package/knowledge/decisions/internals/gateway-wiring-is-a-meta-wiring-over-http-and-channels.md +31 -0
  397. package/knowledge/decisions/internals/generated-src-paths-in-pikku-meta-are-absolute.md +26 -0
  398. package/knowledge/decisions/internals/http-request-bodies-are-read-once-and-shared.md +32 -0
  399. package/knowledge/decisions/internals/http-route-groups-cascade-config-in-a-fixed-order.md +28 -0
  400. package/knowledge/decisions/internals/http-router-matches-normalized-paths-but-returns-registered-ones.md +30 -0
  401. package/knowledge/decisions/internals/http-runner-logs-through-a-trace-scoped-logger-functions-do-not.md +26 -0
  402. package/knowledge/decisions/internals/http-set-cookie-headers-are-appended-never-joined.md +28 -0
  403. package/knowledge/decisions/internals/http-sse-streams-flush-headers-only-after-middleware.md +32 -0
  404. package/knowledge/decisions/internals/http-wiring-without-metadata-is-skipped-not-fatal.md +26 -0
  405. package/knowledge/decisions/internals/in-a-scenario-a-4xx-is-data-not-an-exception.md +25 -0
  406. package/knowledge/decisions/internals/in-memory-workflow-history-aliases-the-live-step-object.md +26 -0
  407. package/knowledge/decisions/internals/index.md +113 -0
  408. package/knowledge/decisions/internals/istanbul-statement-counts-attach-to-the-start-line-only.md +25 -0
  409. package/knowledge/decisions/internals/local-trigger-and-gateway-services-assume-a-single-process.md +26 -0
  410. package/knowledge/decisions/internals/node-only-builtins-are-imported-dynamically.md +24 -0
  411. package/knowledge/decisions/internals/queue-group-concurrency-keeps-one-shared-queue-fair.md +28 -0
  412. package/knowledge/decisions/internals/queue-jobs-always-carry-an-explicit-attempts-count.md +27 -0
  413. package/knowledge/decisions/internals/remote-addons-dispatch-over-http-instead-of-local-meta.md +31 -0
  414. package/knowledge/decisions/internals/rpc-names-resolve-through-package-scope-before-root.md +32 -0
  415. package/knowledge/decisions/internals/scenario-agent-calls-sign-in-on-401-only.md +27 -0
  416. package/knowledge/decisions/internals/scenario-meta-lives-apart-from-app-meta-but-merges-when-read-off-disk.md +26 -0
  417. package/knowledge/decisions/internals/scenario-steps-return-drained-response-records.md +27 -0
  418. package/knowledge/decisions/internals/scope-roots-may-be-co-declared-by-an-addon-and-its-host-app.md +30 -0
  419. package/knowledge/decisions/internals/serverless-channel-disconnect-must-tolerate-a-missing-channel.md +28 -0
  420. package/knowledge/decisions/internals/the-dev-queue-copies-prod-timing-and-serialization-semantics.md +30 -0
  421. package/knowledge/decisions/internals/the-embedding-model-is-pinned-per-service-and-doc-query-embedding-is-split.md +29 -0
  422. package/knowledge/decisions/internals/the-in-memory-workflow-service-is-inline-only-and-single-process.md +27 -0
  423. package/knowledge/decisions/internals/the-kek-salt-is-scoped-to-the-key-version.md +40 -0
  424. package/knowledge/decisions/internals/the-schema-service-is-never-stubbed.md +26 -0
  425. package/knowledge/decisions/internals/trigger-declaration-is-split-from-trigger-source.md +33 -0
  426. package/knowledge/decisions/internals/typed-secret-service-caches-for-the-process-lifetime.md +26 -0
  427. package/knowledge/decisions/internals/webhook-delivery-history-records-every-attempt-best-effort.md +26 -0
  428. package/knowledge/decisions/internals/webhook-service-collaborators-are-constructor-args-not-locator-lookups.md +25 -0
  429. package/knowledge/decisions/internals/whether-a-run-is-inline-is-read-from-the-run-record.md +58 -0
  430. package/knowledge/decisions/internals/workflow-approval-expiry-is-decided-from-a-recorded-deadline.md +34 -0
  431. package/knowledge/decisions/internals/workflow-core-never-imports-a-browser-driver.md +42 -0
  432. package/knowledge/decisions/internals/workflow-dsl-meta-separates-runtime-expressions-from-literals.md +38 -0
  433. package/knowledge/decisions/internals/workflow-features-resolve-scenarios-by-object-identity.md +29 -0
  434. package/knowledge/decisions/internals/workflow-graph-inline-and-queued-runs-share-one-planner.md +42 -0
  435. package/knowledge/decisions/internals/workflow-graph-node-notes-are-excluded-from-the-graph-hash.md +25 -0
  436. package/knowledge/decisions/internals/workflow-inline-runs-report-their-run-id-before-they-can-fail.md +29 -0
  437. package/knowledge/decisions/internals/workflow-invocation-id-is-the-dedupe-key-not-step-id.md +43 -0
  438. package/knowledge/decisions/internals/workflow-queued-step-dispatch-requires-an-explicit-opt-in.md +29 -0
  439. package/knowledge/decisions/internals/workflow-queues-are-per-workflow-by-default.md +42 -0
  440. package/knowledge/decisions/internals/workflow-repeated-step-names-get-an-ordinal-suffix.md +33 -0
  441. package/knowledge/decisions/internals/workflow-replay-reads-its-steps-once-and-caches-only-the-immutable-half.md +32 -0
  442. package/knowledge/decisions/internals/workflow-retries-are-owned-by-the-workflow-not-the-queue.md +31 -0
  443. package/knowledge/decisions/internals/workflow-run-capabilities-are-extensions-not-subclasses.md +39 -0
  444. package/knowledge/decisions/internals/workflow-run-mirror-is-never-a-source-of-truth.md +29 -0
  445. package/knowledge/decisions/internals/workflow-run-polling-backs-off-to-the-callers-ceiling.md +33 -0
  446. package/knowledge/decisions/internals/workflow-run-timeline-is-a-pure-fold-over-durable-history.md +37 -0
  447. package/knowledge/decisions/internals/workflow-scenario-assertions-never-retry-and-record-one-step.md +50 -0
  448. package/knowledge/decisions/internals/workflow-scenario-hooks-are-a-scenario-only-affordance.md +43 -0
  449. package/knowledge/decisions/internals/workflow-scenario-prose-is-rendered-from-typed-calls-not-parsed-from-english.md +32 -0
  450. package/knowledge/decisions/internals/workflow-scenario-quarantine-reason-lives-in-code.md +18 -0
  451. package/knowledge/decisions/internals/workflow-scenario-step-targets-are-string-literals-for-the-inspector.md +34 -0
  452. package/knowledge/decisions/internals/workflow-step-compensation-runs-as-its-own-durable-step.md +26 -0
  453. package/knowledge/decisions/internals/workflow-step-dispatch-failure-is-transient-not-a-run-failure.md +33 -0
  454. package/knowledge/decisions/internals/workflow-step-lock-is-held-only-to-claim-the-step.md +27 -0
  455. package/knowledge/decisions/internals/workflow-step-rpc-name-is-provenance-only.md +34 -0
  456. package/knowledge/decisions/internals/workflow-suspend-and-approval-reasons-are-durable-step-identities.md +38 -0
  457. package/knowledge/decisions/internals/workflow-suspended-runs-keep-their-in-process-context.md +30 -0
  458. package/knowledge/decisions/security/a-dropped-audit-write-is-always-logged.md +26 -0
  459. package/knowledge/decisions/security/actor-flow-missing-approval-decisions-default-to-denied.md +22 -0
  460. package/knowledge/decisions/security/actor-sign-in-is-proven-by-set-cookie-not-a-non-empty-jar.md +27 -0
  461. package/knowledge/decisions/security/actor-sign-in-only-works-for-actor-flagged-users.md +27 -0
  462. package/knowledge/decisions/security/addon-auth-and-tags-only-tighten.md +43 -0
  463. package/knowledge/decisions/security/addon-config-gates-apply-only-at-the-namespaced-rpc-boundary.md +52 -0
  464. package/knowledge/decisions/security/addon-scopes-are-resolved-where-the-function-runs.md +46 -0
  465. package/knowledge/decisions/security/ai-agent-approval-forwarding-requires-a-symbol-brand.md +27 -0
  466. package/knowledge/decisions/security/ai-agent-credential-requests-are-symbol-branded.md +37 -0
  467. package/knowledge/decisions/security/ai-agent-gate-requires-a-session-only-when-auth-is-true.md +31 -0
  468. package/knowledge/decisions/security/ai-agent-ownership-failures-never-echo-the-resource.md +23 -0
  469. package/knowledge/decisions/security/ai-agent-resume-re-runs-the-authorization-gate.md +22 -0
  470. package/knowledge/decisions/security/ai-agent-sessionless-deployments-have-no-thread-ownership.md +39 -0
  471. package/knowledge/decisions/security/ai-agent-thread-ownership-composes-the-session-principal.md +30 -0
  472. package/knowledge/decisions/security/ai-agent-tool-filtering-reads-the-live-function-config.md +24 -0
  473. package/knowledge/decisions/security/an-empty-owners-constraint-matches-nothing.md +30 -0
  474. package/knowledge/decisions/security/an-exposed-ungated-function-is-a-codegen-warning.md +49 -0
  475. package/knowledge/decisions/security/console-addon-privileged-functions-gate-themselves.md +76 -0
  476. package/knowledge/decisions/security/core-safe-fetch-blocks-ssrf-by-host-literal-not-dns.md +39 -0
  477. package/knowledge/decisions/security/core-secrets-use-a-per-secret-dek-wrapped-by-a-kek.md +37 -0
  478. package/knowledge/decisions/security/gateway-handlers-run-through-the-function-runner-gate.md +31 -0
  479. package/knowledge/decisions/security/gateway-middleware-sessions-must-be-bridged-onto-the-wire.md +30 -0
  480. package/knowledge/decisions/security/global-permissions-and-function-permissions-are-independent-gates.md +40 -0
  481. package/knowledge/decisions/security/http-error-detail-is-withheld-from-clients-in-production.md +33 -0
  482. package/knowledge/decisions/security/http-request-bodies-are-bounded-before-they-are-buffered.md +46 -0
  483. package/knowledge/decisions/security/index.md +55 -0
  484. package/knowledge/decisions/security/mcp-internal-error-details-are-double-gated-on-production.md +27 -0
  485. package/knowledge/decisions/security/passphrases-are-stretched-key-material-is-expanded.md +40 -0
  486. package/knowledge/decisions/security/permission-auth-filtering-requires-live-permission-functions.md +31 -0
  487. package/knowledge/decisions/security/pikku-carries-actor-scopes-as-data-and-the-app-grants-them.md +26 -0
  488. package/knowledge/decisions/security/queue-job-identities-are-signed-at-enqueue.md +69 -0
  489. package/knowledge/decisions/security/queue-jobs-carry-the-producers-pikku-user-id.md +39 -0
  490. package/knowledge/decisions/security/remote-addon-tokens-are-client-credentials-not-mesh-trust.md +34 -0
  491. package/knowledge/decisions/security/scaffold-features-are-authenticated-unless-opted-out.md +49 -0
  492. package/knowledge/decisions/security/scenario-step-functions-are-never-externally-invocable.md +30 -0
  493. package/knowledge/decisions/security/scope-resolution-happens-at-the-session-boundary-and-sync-never-deletes.md +28 -0
  494. package/knowledge/decisions/security/self-authentication-is-declared-not-detected.md +34 -0
  495. package/knowledge/decisions/security/signed-content-urls-bind-the-request-path.md +37 -0
  496. package/knowledge/decisions/security/webhook-bodies-are-signed-before-they-are-enqueued.md +25 -0
  497. package/knowledge/decisions/security/workflow-actor-steps-always-use-the-real-transport.md +34 -0
  498. package/knowledge/decisions/security/workflow-approval-payloads-are-validated-on-replay-inside-the-workflow.md +40 -0
  499. package/knowledge/decisions/security/workflow-queued-steps-rehydrate-their-session-from-the-run-wire.md +32 -0
  500. package/knowledge/decisions/security/workflow-scenario-sessions-are-isolated-per-actor-and-per-scenario.md +32 -0
  501. package/knowledge/decisions/security/workflow-scenario-steps-are-never-network-invocable.md +31 -0
  502. package/knowledge/index.md +24 -0
  503. package/knowledge/questions/index.md +15 -0
  504. package/package.json +4 -1
  505. package/run-tests.sh +0 -0
  506. package/src/crypto-utils.test.ts +460 -19
  507. package/src/crypto-utils.ts +283 -55
  508. package/src/data-classification.ts +1 -7
  509. package/src/dev/hot-reload.test.ts +0 -4
  510. package/src/dev/hot-reload.ts +11 -30
  511. package/src/dev/module-runner.ts +7 -32
  512. package/src/dev/reload-meta.ts +9 -29
  513. package/src/errors/error-handler.ts +20 -35
  514. package/src/errors/error.test.ts +30 -1
  515. package/src/errors/errors.ts +73 -157
  516. package/src/function/abort-scope.test.ts +97 -0
  517. package/src/function/abort-scope.ts +80 -0
  518. package/src/function/function-runner.test.ts +0 -7
  519. package/src/function/function-runner.ts +62 -32
  520. package/src/function/functions.types.ts +56 -136
  521. package/src/function/list.types.test.ts +3 -25
  522. package/src/function/list.types.ts +12 -62
  523. package/src/handle-error.ts +0 -18
  524. package/src/index.ts +60 -1
  525. package/src/middleware/auth-apikey.test.ts +0 -1
  526. package/src/middleware/auth-apikey.ts +0 -17
  527. package/src/middleware/auth-bearer.test.ts +0 -3
  528. package/src/middleware/auth-bearer.ts +3 -40
  529. package/src/middleware/auth-cookie.test.ts +0 -6
  530. package/src/middleware/auth-cookie.ts +2 -26
  531. package/src/middleware/cors.test.ts +34 -0
  532. package/src/middleware/cors.ts +12 -33
  533. package/src/middleware/remote-auth.test.ts +24 -9
  534. package/src/middleware/remote-auth.ts +10 -2
  535. package/src/middleware/telemetry.ts +2 -31
  536. package/src/middleware-runner.test.ts +0 -2
  537. package/src/middleware-runner.ts +5 -74
  538. package/src/permissions.test.ts +30 -0
  539. package/src/permissions.ts +24 -74
  540. package/src/pikku-request.ts +0 -6
  541. package/src/pikku-state.ts +2 -30
  542. package/src/production-barrels-stay-lean.test.ts +110 -0
  543. package/src/remote.test.ts +172 -0
  544. package/src/remote.ts +17 -7
  545. package/src/schema.ts +5 -39
  546. package/src/scopes.ts +7 -48
  547. package/src/services/ai-agent-runner-service.ts +20 -0
  548. package/src/services/ai-embedding-service.ts +3 -25
  549. package/src/services/audit-service.ts +1 -2
  550. package/src/services/content-service.ts +1 -46
  551. package/src/services/credential-service.ts +3 -40
  552. package/src/services/credential-wire-service.test.ts +0 -2
  553. package/src/services/deployment-service.ts +3 -9
  554. package/src/services/gateway-service.ts +0 -15
  555. package/src/services/{http-scenario-actors-converse.test.ts → http-personas-converse.test.ts} +38 -9
  556. package/src/services/{http-scenario-actors.test.ts → http-personas.test.ts} +39 -22
  557. package/src/services/{http-scenario-actors.ts → http-personas.ts} +85 -45
  558. package/src/services/in-memory-queue-service.ts +1 -15
  559. package/src/services/in-memory-trigger-service.ts +1 -18
  560. package/src/services/in-memory-workflow-service.test.ts +0 -13
  561. package/src/services/in-memory-workflow-service.ts +4 -38
  562. package/src/services/index.ts +20 -15
  563. package/src/services/istanbul-coverage-service.ts +2 -8
  564. package/src/services/jwt-service.ts +1 -16
  565. package/src/services/local-content.test.ts +159 -27
  566. package/src/services/local-content.ts +55 -23
  567. package/src/services/local-gateway-service.ts +2 -17
  568. package/src/services/local-secrets.ts +0 -4
  569. package/src/services/logger-console.test.ts +0 -1
  570. package/src/services/logger-console.ts +3 -7
  571. package/src/services/logger.ts +2 -37
  572. package/src/services/meta-service.test.ts +1 -5
  573. package/src/services/meta-service.ts +41 -61
  574. package/src/services/{scenario-actors-service.ts → personas-service.ts} +48 -43
  575. package/src/services/pikku-user-id.ts +0 -4
  576. package/src/services/queue-webhook-service.ts +9 -41
  577. package/src/services/scheduler-service.ts +1 -50
  578. package/src/services/schema-service.ts +1 -24
  579. package/src/services/scope-service.ts +50 -34
  580. package/src/services/scoped-secret-service.ts +0 -4
  581. package/src/services/secret-host-binding.test.ts +138 -0
  582. package/src/services/secret-host-binding.ts +51 -0
  583. package/src/services/secret-service.ts +5 -33
  584. package/src/services/secretless.test.ts +54 -0
  585. package/src/services/secretless.ts +29 -0
  586. package/src/services/stub-tracker.ts +8 -18
  587. package/src/services/system-role-guard.test.ts +93 -0
  588. package/src/services/system-role-guard.ts +71 -0
  589. package/src/services/trigger-service.ts +0 -12
  590. package/src/services/typed-secret-service.ts +1 -7
  591. package/src/services/v8-coverage-service.ts +3 -6
  592. package/src/services/variables-service.ts +1 -8
  593. package/src/services/webhook-service.ts +19 -63
  594. package/src/services/workflow-service.ts +3 -20
  595. package/src/testing/service-tests.ts +0 -26
  596. package/src/time-utils.ts +1 -19
  597. package/src/types/core.types.ts +116 -229
  598. package/src/types/state.types.ts +7 -9
  599. package/src/utils/hmac.ts +4 -10
  600. package/src/utils/safe-fetch.ts +13 -54
  601. package/src/utils.test.ts +11 -2
  602. package/src/utils.ts +6 -15
  603. package/src/wirings/actor-flow/actor-flow.types.ts +1 -34
  604. package/src/wirings/actor-flow/index.ts +0 -9
  605. package/src/wirings/actor-flow/run-conversation.test.ts +11 -6
  606. package/src/wirings/actor-flow/run-conversation.ts +19 -12
  607. package/src/wirings/ai-agent/ai-agent-agui.test.ts +75 -10
  608. package/src/wirings/ai-agent/ai-agent-agui.ts +36 -17
  609. package/src/wirings/ai-agent/ai-agent-helpers.ts +20 -0
  610. package/src/wirings/ai-agent/ai-agent-interrupt.test.ts +842 -0
  611. package/src/wirings/ai-agent/ai-agent-interrupt.ts +399 -0
  612. package/src/wirings/ai-agent/ai-agent-memory.ts +0 -2
  613. package/src/wirings/ai-agent/ai-agent-model-config.ts +1 -9
  614. package/src/wirings/ai-agent/ai-agent-prepare.test.ts +202 -31
  615. package/src/wirings/ai-agent/ai-agent-prepare.ts +82 -138
  616. package/src/wirings/ai-agent/ai-agent-registry.test.ts +191 -6
  617. package/src/wirings/ai-agent/ai-agent-registry.ts +18 -1
  618. package/src/wirings/ai-agent/ai-agent-resume-authorization.test.ts +0 -2
  619. package/src/wirings/ai-agent/ai-agent-runner.test.ts +11 -9
  620. package/src/wirings/ai-agent/ai-agent-runner.ts +67 -33
  621. package/src/wirings/ai-agent/ai-agent-stream.test.ts +205 -103
  622. package/src/wirings/ai-agent/ai-agent-stream.ts +192 -75
  623. package/src/wirings/ai-agent/ai-agent-thread-ownership.test.ts +301 -0
  624. package/src/wirings/ai-agent/ai-agent.types.ts +85 -4
  625. package/src/wirings/ai-agent/index.ts +35 -3
  626. package/src/wirings/ai-agent/voice-input.test.ts +72 -7
  627. package/src/wirings/ai-agent/voice-input.ts +48 -3
  628. package/src/wirings/ai-agent/voice-output.test.ts +422 -0
  629. package/src/wirings/ai-agent/voice-output.ts +216 -56
  630. package/src/wirings/channel/channel-common.ts +15 -20
  631. package/src/wirings/channel/channel-handler.test.ts +50 -0
  632. package/src/wirings/channel/channel-handler.ts +32 -11
  633. package/src/wirings/channel/channel-host-rpc.test.ts +150 -0
  634. package/src/wirings/channel/channel-host-rpc.ts +69 -0
  635. package/src/wirings/channel/channel-middleware-runner.test.ts +0 -1
  636. package/src/wirings/channel/channel-middleware-runner.ts +0 -12
  637. package/src/wirings/channel/channel-rpc-registry.ts +116 -0
  638. package/src/wirings/channel/channel-rpc-responder.ts +117 -0
  639. package/src/wirings/channel/channel-rpc-service.ts +146 -0
  640. package/src/wirings/channel/channel-rpc-validators.ts +65 -0
  641. package/src/wirings/channel/channel-rpc.test.ts +820 -0
  642. package/src/wirings/channel/channel-rpc.ts +5 -0
  643. package/src/wirings/channel/channel-rpc.types.ts +150 -0
  644. package/src/wirings/channel/channel-runner.ts +0 -14
  645. package/src/wirings/channel/channel-store.ts +0 -10
  646. package/src/wirings/channel/channel.types.ts +19 -8
  647. package/src/wirings/channel/define-channel-routes.ts +0 -20
  648. package/src/wirings/channel/eventhub-service.ts +0 -18
  649. package/src/wirings/channel/index.ts +35 -0
  650. package/src/wirings/channel/local/local-channel-handler.ts +3 -1
  651. package/src/wirings/channel/local/local-channel-runner.test.ts +0 -10
  652. package/src/wirings/channel/local/local-channel-runner.ts +3 -1
  653. package/src/wirings/channel/local/local-eventhub-service.test.ts +0 -13
  654. package/src/wirings/channel/local/local-eventhub-service.ts +2 -37
  655. package/src/wirings/channel/log-channels.ts +0 -4
  656. package/src/wirings/channel/pikku-abstract-channel-handler.test.ts +83 -2
  657. package/src/wirings/channel/pikku-abstract-channel-handler.ts +7 -0
  658. package/src/wirings/channel/serverless/serverless-channel-runner.ts +2 -5
  659. package/src/wirings/cli/channel/cli-approval.test.ts +177 -0
  660. package/src/wirings/cli/channel/cli-approval.ts +135 -0
  661. package/src/wirings/cli/channel/cli-channel-runner.ts +4 -26
  662. package/src/wirings/cli/channel/cli-raw-channel-runner.test.ts +169 -0
  663. package/src/wirings/cli/channel/cli-raw-channel-runner.ts +59 -16
  664. package/src/wirings/cli/channel/cli-raw-client-runner.test.ts +480 -0
  665. package/src/wirings/cli/channel/cli-raw-client-runner.ts +155 -0
  666. package/src/wirings/cli/channel/index.ts +9 -0
  667. package/src/wirings/cli/cli-runner.test.ts +0 -1
  668. package/src/wirings/cli/cli-runner.ts +46 -88
  669. package/src/wirings/cli/cli.types.ts +14 -3
  670. package/src/wirings/cli/command-parser.test.ts +0 -4
  671. package/src/wirings/cli/command-parser.ts +11 -91
  672. package/src/wirings/cli/define-cli-commands.ts +1 -17
  673. package/src/wirings/credential/credential.types.ts +0 -12
  674. package/src/wirings/credential/{wire-credential.ts → define-credential.ts} +7 -7
  675. package/src/wirings/credential/index.ts +1 -1
  676. package/src/wirings/credential/validate-credential-definitions.ts +2 -4
  677. package/src/wirings/gateway/gateway-runner.test.ts +1 -21
  678. package/src/wirings/gateway/gateway-runner.ts +8 -110
  679. package/src/wirings/gateway/gateway.types.ts +7 -80
  680. package/src/wirings/http/http-routes.test.ts +0 -3
  681. package/src/wirings/http/http-routes.ts +0 -86
  682. package/src/wirings/http/http-runner.test.ts +0 -1
  683. package/src/wirings/http/http-runner.ts +8 -167
  684. package/src/wirings/http/http.types.ts +15 -62
  685. package/src/wirings/http/log-http-routes.ts +0 -4
  686. package/src/wirings/http/pikku-fetch-http-request.test.ts +2 -10
  687. package/src/wirings/http/pikku-fetch-http-request.ts +0 -58
  688. package/src/wirings/http/pikku-fetch-http-response.test.ts +1 -1
  689. package/src/wirings/http/pikku-fetch-http-response.ts +0 -3
  690. package/src/wirings/http/routers/path-to-regex.test.ts +4 -17
  691. package/src/wirings/http/routers/path-to-regex.ts +2 -13
  692. package/src/wirings/http/web-request.test.ts +33 -2
  693. package/src/wirings/http/web-request.ts +30 -17
  694. package/src/wirings/mcp/mcp-endpoint-registry.test.ts +0 -1
  695. package/src/wirings/mcp/mcp-runner.ts +2 -17
  696. package/src/wirings/mcp/mcp.types.ts +7 -42
  697. package/src/wirings/oauth2/oauth2.types.ts +0 -30
  698. package/src/wirings/persona/define-personas.ts +29 -0
  699. package/src/wirings/persona/index.ts +62 -0
  700. package/src/wirings/persona/persona-email.ts +87 -0
  701. package/src/wirings/persona/persona-environments.test.ts +183 -0
  702. package/src/wirings/persona/persona-environments.ts +138 -0
  703. package/src/wirings/persona/persona-mailbox.ts +156 -0
  704. package/src/wirings/persona/persona.test.ts +220 -0
  705. package/src/wirings/persona/persona.types.ts +131 -0
  706. package/src/wirings/persona/validate-personas.ts +133 -0
  707. package/src/wirings/queue/index.ts +13 -3
  708. package/src/wirings/queue/queue-identity.test.ts +453 -0
  709. package/src/wirings/queue/queue-identity.ts +173 -0
  710. package/src/wirings/queue/queue-runner.ts +12 -31
  711. package/src/wirings/queue/queue.types.ts +19 -89
  712. package/src/wirings/queue/register-queue-helper.ts +0 -14
  713. package/src/wirings/queue/signed-queue-service.ts +59 -0
  714. package/src/wirings/queue/validate-worker-config.ts +2 -28
  715. package/src/wirings/role/define-system-role.ts +33 -0
  716. package/src/wirings/role/index.ts +13 -0
  717. package/src/wirings/role/role.test.ts +104 -0
  718. package/src/wirings/role/role.types.ts +47 -0
  719. package/src/wirings/role/validate-role-definitions.ts +93 -0
  720. package/src/wirings/rpc/addon-auth-tags.test.ts +223 -0
  721. package/src/wirings/rpc/addon-runner.ts +0 -56
  722. package/src/wirings/rpc/addon-scopes.test.ts +225 -0
  723. package/src/wirings/rpc/remote-addon-auth.ts +1 -13
  724. package/src/wirings/rpc/rpc-runner.test.ts +186 -2
  725. package/src/wirings/rpc/rpc-runner.ts +145 -127
  726. package/src/wirings/rpc/rpc-types.ts +11 -6
  727. package/src/wirings/rpc/wire-addon.test.ts +43 -1
  728. package/src/wirings/rpc/wire-addon.ts +99 -0
  729. package/src/wirings/rpc/wire-remote-addon.ts +9 -29
  730. package/src/wirings/scheduler/log-schedulers.ts +0 -4
  731. package/src/wirings/scheduler/scheduler-runner.test.ts +1 -8
  732. package/src/wirings/scheduler/scheduler-runner.ts +0 -2
  733. package/src/wirings/scheduler/scheduler.types.ts +1 -14
  734. package/src/wirings/scope/{wire-scope.ts → define-scope.ts} +5 -6
  735. package/src/wirings/scope/index.ts +1 -1
  736. package/src/wirings/scope/scope.test.ts +1 -2
  737. package/src/wirings/scope/scope.types.ts +7 -9
  738. package/src/wirings/scope/validate-scope-definitions.ts +3 -21
  739. package/src/wirings/secret/index.ts +1 -1
  740. package/src/wirings/secret/secret.types.ts +19 -15
  741. package/src/wirings/secret/validate-secret-definitions.ts +2 -4
  742. package/src/wirings/trigger/trigger-runner.ts +1 -27
  743. package/src/wirings/trigger/trigger.types.ts +1 -82
  744. package/src/wirings/variable/index.ts +1 -1
  745. package/src/wirings/variable/validate-variable-definitions.ts +2 -4
  746. package/src/wirings/variable/variable.types.ts +1 -13
  747. package/src/wirings/virtual-user/index.ts +76 -0
  748. package/src/wirings/virtual-user/run-virtual-user.test.ts +765 -0
  749. package/src/wirings/virtual-user/run-virtual-user.ts +671 -0
  750. package/src/wirings/virtual-user/virtual-user-agents.test.ts +65 -0
  751. package/src/wirings/virtual-user/virtual-user-agents.ts +57 -0
  752. package/src/wirings/virtual-user/virtual-user-catalogue.test.ts +215 -0
  753. package/src/wirings/virtual-user/virtual-user-catalogue.ts +184 -0
  754. package/src/wirings/virtual-user/virtual-user-derive.test.ts +398 -0
  755. package/src/wirings/virtual-user/virtual-user-derive.ts +173 -0
  756. package/src/wirings/virtual-user/virtual-user-dispositions.test.ts +63 -0
  757. package/src/wirings/virtual-user/virtual-user-dispositions.ts +213 -0
  758. package/src/wirings/virtual-user/virtual-user-intents.test.ts +208 -0
  759. package/src/wirings/virtual-user/virtual-user-intents.ts +185 -0
  760. package/src/wirings/virtual-user/virtual-user-rng.test.ts +72 -0
  761. package/src/wirings/virtual-user/virtual-user-rng.ts +50 -0
  762. package/src/wirings/virtual-user/virtual-user-target.ts +47 -0
  763. package/src/wirings/virtual-user/virtual-user.types.ts +219 -0
  764. package/src/wirings/workflow/dsl/workflow-dsl.types.ts +5 -4
  765. package/src/wirings/workflow/dsl/workflow-runner.ts +0 -4
  766. package/src/wirings/workflow/feature.ts +0 -19
  767. package/src/wirings/workflow/graph/graph-node.ts +0 -136
  768. package/src/wirings/workflow/graph/graph-runner.test.ts +20 -19
  769. package/src/wirings/workflow/graph/graph-runner.ts +6 -41
  770. package/src/wirings/workflow/graph/wire-workflow-graph.ts +0 -4
  771. package/src/wirings/workflow/graph/workflow-graph.types.ts +0 -58
  772. package/src/wirings/workflow/index.ts +10 -44
  773. package/src/wirings/workflow/pikku-scenario-service.ts +235 -52
  774. package/src/wirings/workflow/pikku-workflow-service.test.ts +0 -39
  775. package/src/wirings/workflow/pikku-workflow-service.ts +77 -674
  776. package/src/wirings/workflow/run-timeline.test.ts +7 -19
  777. package/src/wirings/workflow/run-timeline.ts +0 -56
  778. package/src/wirings/workflow/scenario-cookie-jar.test.ts +0 -1
  779. package/src/wirings/workflow/scenario-cookie-jar.ts +0 -25
  780. package/src/wirings/workflow/scenario-expectations.test.ts +2 -7
  781. package/src/wirings/workflow/scenario-hooks.test.ts +2 -7
  782. package/src/wirings/workflow/scenario-poll.test.ts +0 -2
  783. package/src/wirings/workflow/scenario-poll.ts +0 -15
  784. package/src/wirings/workflow/scenario-prose.ts +0 -28
  785. package/src/wirings/workflow/scenario-service.test.ts +2 -9
  786. package/src/wirings/workflow/scenario-step-guards.ts +1 -14
  787. package/src/wirings/workflow/scenario-step.test.ts +159 -14
  788. package/src/wirings/workflow/scenario-step.types.ts +82 -6
  789. package/src/wirings/workflow/scenario-surface.test.ts +145 -0
  790. package/src/wirings/workflow/scenario-surface.ts +71 -0
  791. package/src/wirings/workflow/workflow-dispatch-durability.test.ts +14 -15
  792. package/src/wirings/workflow/workflow-dispatch-payload.test.ts +0 -4
  793. package/src/wirings/workflow/workflow-inline-authority.test.ts +169 -0
  794. package/src/wirings/workflow/workflow-invocation-id.test.ts +0 -2
  795. package/src/wirings/workflow/workflow-invocation-id.ts +2 -22
  796. package/src/wirings/workflow/workflow-mirror.test.ts +0 -7
  797. package/src/wirings/workflow/workflow-on-error.test.ts +0 -9
  798. package/src/wirings/workflow/workflow-queue-workers.ts +0 -21
  799. package/src/wirings/workflow/workflow-replay-snapshot.test.ts +8 -7
  800. package/src/wirings/workflow/workflow-retry-policy.test.ts +0 -5
  801. package/src/wirings/workflow/workflow-run-context.test.ts +5 -10
  802. package/src/wirings/workflow/workflow-run-polling.test.ts +0 -5
  803. package/src/wirings/workflow/workflow-step-ordinal.test.ts +19 -4
  804. package/src/wirings/workflow/workflow-step-session.test.ts +0 -7
  805. package/src/wirings/workflow/workflow.types.ts +0 -203
  806. package/tsconfig.tsbuildinfo +1 -1
  807. package/src/middleware/timeout.ts +0 -22
  808. package/src/pikku-response.ts +0 -5
  809. package/src/wirings/mcp/mcp-endpoint-registry.test.d.ts +0 -1
  810. package/src/wirings/workflow/dsl/index.ts +0 -36
  811. package/src/wirings/workflow/graph/index.ts +0 -15
@@ -0,0 +1,50 @@
1
+ /**
2
+ * A seeded PRNG, so a run replays exactly.
3
+ *
4
+ * Reproducibility is the whole point: a virtual user that finds something has
5
+ * to be re-runnable into the same finding before it can be shrunk into a
6
+ * regression scenario. `Math.random` would make every finding a one-off story.
7
+ *
8
+ * mulberry32 — 32 bits of state, uniform enough for scheduling weights, and
9
+ * short enough to read.
10
+ */
11
+ export const createRng = (seed: number) => {
12
+ let state = seed >>> 0
13
+ const next = () => {
14
+ state = (state + 0x6d2b79f5) >>> 0
15
+ let t = state
16
+ t = Math.imul(t ^ (t >>> 15), t | 1)
17
+ t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
18
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296
19
+ }
20
+ return {
21
+ next,
22
+ /** True with probability `p`. */
23
+ chance: (p: number) => next() < p,
24
+ /** A uniform pick, or undefined for an empty list. */
25
+ pick: <T>(items: readonly T[]): T | undefined =>
26
+ items.length === 0 ? undefined : items[Math.floor(next() * items.length)],
27
+ /**
28
+ * A weighted pick over `[key, weight]` pairs. Zero-weight keys can never be
29
+ * drawn, which is how a disposition switches a move off entirely.
30
+ */
31
+ weighted: <K extends string>(
32
+ weights: Readonly<Record<K, number>>
33
+ ): K | undefined => {
34
+ const entries = (Object.entries(weights) as [K, number][]).filter(
35
+ ([, weight]) => weight > 0
36
+ )
37
+ const total = entries.reduce((sum, [, weight]) => sum + weight, 0)
38
+ if (total <= 0) return undefined
39
+ let roll = next() * total
40
+ for (const [key, weight] of entries) {
41
+ roll -= weight
42
+ if (roll <= 0) return key
43
+ }
44
+ return entries[entries.length - 1]?.[0]
45
+ },
46
+ }
47
+ }
48
+
49
+ /** The seeded generator the engine threads through a whole run. */
50
+ export type VirtualUserRng = ReturnType<typeof createRng>
@@ -0,0 +1,47 @@
1
+ import type { ScenarioPersona } from '../../services/personas-service.js'
2
+ import type { VirtualUserTarget } from './virtual-user.types.js'
3
+
4
+ export interface PersonaTargetOptions {
5
+ /** Model the persona uses for its side of a conversation with an agent. */
6
+ model?: string
7
+ /** Agents this user may talk to. Omit to leave `talkTo` unavailable. */
8
+ agents?: readonly string[]
9
+ }
10
+
11
+ /**
12
+ * Drive a virtual user through a signed-in persona.
13
+ *
14
+ * This is the only place the engine meets the network. A persona already signs
15
+ * in as a real user over the app's own auth, keeps its cookies, re-logs-in when
16
+ * a session expires mid-run and reports a status as data rather than throwing —
17
+ * everything a user imitating a user needs, and none of it worth building twice.
18
+ *
19
+ * `invokeRaw` rather than `invoke` matters: to a virtual user a 403 is not an
20
+ * error, it is the system saying no, which is information it should be allowed
21
+ * to act on.
22
+ */
23
+ export const personaVirtualUserTarget = (
24
+ persona: ScenarioPersona,
25
+ { model, agents }: PersonaTargetOptions = {}
26
+ ): VirtualUserTarget => ({
27
+ call: (rpcName, args) => persona.invokeRaw(rpcName, args),
28
+ talkTo: agents?.length
29
+ ? async (agent, task) => {
30
+ if (!agents.includes(agent)) {
31
+ return {
32
+ passed: false,
33
+ reasoning: `There is no assistant called '${agent}'.`,
34
+ transcript: [],
35
+ }
36
+ }
37
+ return persona.converse({
38
+ agent,
39
+ task,
40
+ // A user asking for something judges the answer by whether they got
41
+ // what they asked for. There is no separate criterion to hold it to.
42
+ evaluate: `The assistant did what was asked: ${task}`,
43
+ model,
44
+ })
45
+ }
46
+ : undefined,
47
+ })
@@ -0,0 +1,219 @@
1
+ import type { ScenarioHttpResponse } from '../../services/personas-service.js'
2
+ import type { ActorFlowVerdict } from '../actor-flow/actor-flow.types.js'
3
+
4
+ /**
5
+ * How a virtual user behaves, mechanically. A disposition changes the loop, the
6
+ * input generation, the memory and the oracle — anything that only changes how
7
+ * the user *talks* is persona prose (`ResolvedPersona.personality`) and does
8
+ * not belong here.
9
+ *
10
+ * - `realistic` — schema-first, goal-directed, plausible values (default).
11
+ * - `careless` — repeats, abandons, double-submits, boundary values.
12
+ * - `newcomer` — starts with empty memory and must discover everything.
13
+ * - `stale` — seeded from an earlier run's ids, some no longer valid.
14
+ * - `auditor` — pursues no goal; reads one truth from several places and compares.
15
+ * - `adversarial` — probes authorization and tenancy; a 2xx can be the finding.
16
+ * - `accountable` — pursues its goals for real; the only one production allows.
17
+ *
18
+ * `accountable` sits opposite `adversarial` on an *intent* axis — bad faith
19
+ * against good faith — where `careless` and `thorough` are a *care* axis. It is
20
+ * the one disposition whose actions carry consequences: no oracle, no rollback,
21
+ * and every call attributed to the persona in the audit log like anyone else's.
22
+ */
23
+ export type VirtualUserDisposition =
24
+ | 'realistic'
25
+ | 'careless'
26
+ | 'newcomer'
27
+ | 'stale'
28
+ | 'auditor'
29
+ | 'adversarial'
30
+ | 'accountable'
31
+
32
+ /**
33
+ * The one disposition a production environment accepts.
34
+ *
35
+ * Every other disposition exists to find out what the product does wrong, which
36
+ * is not a thing to do to real customers' data. Named here so the declaration
37
+ * check and the sign-in check cannot drift apart.
38
+ */
39
+ export const PRODUCTION_DISPOSITION: VirtualUserDisposition = 'accountable'
40
+
41
+ /**
42
+ * Hard caps the engine enforces itself. Anything the engine cannot count —
43
+ * money above all — belongs in {@link RunVirtualUserParams.stop} instead.
44
+ */
45
+ export interface VirtualUserBudget {
46
+ /** Model turns, including ones that produced no call. */
47
+ steps?: number
48
+ /** Non-read RPC calls. */
49
+ mutations?: number
50
+ /** Wall clock, as ms or a duration string (`'30m'`). */
51
+ duration?: number | string
52
+ }
53
+
54
+ /**
55
+ * The running count handed to {@link RunVirtualUserParams.stop}. Pikku collects
56
+ * it because only the engine sees every step; what it is *worth* is the app's,
57
+ * which is why no price or currency appears anywhere in core.
58
+ */
59
+ export interface VirtualUserTally {
60
+ steps: number
61
+ calls: number
62
+ mutations: number
63
+ tokensIn: number
64
+ tokensOut: number
65
+ model: string
66
+ elapsedMs: number
67
+ findings: number
68
+ }
69
+
70
+ /**
71
+ * One RPC as the virtual user sees it before reading its schema: enough to
72
+ * choose from, not enough to call with. The whole catalogue goes in the prompt,
73
+ * so this stays deliberately compact — a project with 430 RPCs renders to
74
+ * roughly 8k tokens, which is cheaper than any retrieval step and hides nothing.
75
+ */
76
+ export interface ApiCatalogueEntry {
77
+ name: string
78
+ /** Top-level input property names, for choosing between similar endpoints. */
79
+ inputKeys?: readonly string[]
80
+ /** Top-level output property names. */
81
+ outputKeys?: readonly string[]
82
+ description?: string
83
+ /**
84
+ * Whether the call only reads. `undefined` means nobody annotated it — which
85
+ * is not the same as safe, so the engine falls back to a name heuristic and
86
+ * reports how many entries it had to guess at.
87
+ */
88
+ readonly?: boolean
89
+ /** Declared by the app as needing a human's approval — denied by default. */
90
+ approvalRequired?: boolean
91
+ /**
92
+ * Scopes the session must hold to call this, all of them.
93
+ *
94
+ * Splits the catalogue in two: what a persona's roles entitle it to reach,
95
+ * and what they do not. Scopes rather than permission-function names because
96
+ * a scope is declared and checkable, whereas a permission is arbitrary code
97
+ * whose verdict nobody can predict without running it.
98
+ */
99
+ scopes?: readonly string[]
100
+ tags?: readonly string[]
101
+ /** JSON schema returned by `describe`, before the user may call. */
102
+ inputSchema?: Record<string, unknown>
103
+ outputSchema?: Record<string, unknown>
104
+ }
105
+
106
+ /**
107
+ * Where an intent comes from: a feature or scenario in the app's own words.
108
+ *
109
+ * Deliberately prose. The virtual user never receives the scenario's step graph
110
+ * — no rpc names, no `$ref` dataflow — because finding the API itself is the
111
+ * behaviour under test, and those graphs are a build-time artifact that no
112
+ * deployed stage carries.
113
+ */
114
+ export interface IntentSource {
115
+ id: string
116
+ title: string
117
+ description?: string
118
+ /** Step prose, as a person would be told it. Never rpc names. */
119
+ steps?: readonly string[]
120
+ tags?: readonly string[]
121
+ /** Persona ids this intent is available to. Empty means everyone. */
122
+ personas?: readonly string[]
123
+ }
124
+
125
+ /** Why the engine flagged something. */
126
+ export type VirtualUserFindingKind =
127
+ | 'server-error'
128
+ | 'transport-error'
129
+ | 'schema-violation'
130
+ | 'unexpected-success'
131
+ | 'custom'
132
+
133
+ /** Something worth a human's attention, found while imitating a user. */
134
+ export interface VirtualUserFinding {
135
+ kind: VirtualUserFindingKind
136
+ detail: string
137
+ rpcName?: string
138
+ status?: number
139
+ intentId?: string
140
+ /** Step index within the run, so the transcript can be replayed to here. */
141
+ step: number
142
+ }
143
+
144
+ /**
145
+ * The transport the virtual user acts through. HTTP in production (an
146
+ * `HttpPersona`), but the engine only sees this contract — which is what
147
+ * lets the whole loop be tested without a network.
148
+ */
149
+ export interface VirtualUserTarget {
150
+ /** Invoke an RPC as this user, reporting the status as data rather than throwing. */
151
+ call(rpcName: string, args: unknown): Promise<ScenarioHttpResponse>
152
+ /** Converse with an AI agent in persona. Omitted by apps that have no agents. */
153
+ talkTo?(agent: string, task: string): Promise<ActorFlowVerdict>
154
+ /** Send a fixture file. Omitted by apps with no upload surface. */
155
+ upload?(file: string): Promise<ScenarioHttpResponse>
156
+ }
157
+
158
+ /** What the model chose to do this turn. */
159
+ export type VirtualUserAction =
160
+ | { kind: 'describe'; rpcName: string }
161
+ | { kind: 'call'; rpcName: string; args?: unknown }
162
+ | { kind: 'talkTo'; agent: string; task: string }
163
+ | { kind: 'upload'; file: string }
164
+ | { kind: 'complete'; summary?: string }
165
+ | { kind: 'stuck'; reason?: string }
166
+
167
+ /** How an intent ended, or that it has not. */
168
+ export type IntentStatus =
169
+ | 'open'
170
+ | 'suspended'
171
+ | 'completed'
172
+ | 'abandoned'
173
+ | 'stuck'
174
+
175
+ /** One intent's life within a run. */
176
+ export interface IntentRecord {
177
+ id: string
178
+ sourceId: string
179
+ title: string
180
+ status: IntentStatus
181
+ /** Step indices at which this intent was the active one. */
182
+ steps: number[]
183
+ /** How many times it was put down and picked back up. */
184
+ suspensions: number
185
+ summary?: string
186
+ }
187
+
188
+ /** One turn: what the engine scheduled, what the model did, what came back. */
189
+ export interface StepRecord {
190
+ index: number
191
+ intentId?: string
192
+ action: VirtualUserAction | { kind: 'invalid'; detail: string }
193
+ status?: number
194
+ ok?: boolean
195
+ /** Truncated response text, so a run record stays readable. */
196
+ response?: string
197
+ findingKinds?: VirtualUserFindingKind[]
198
+ tokensIn: number
199
+ tokensOut: number
200
+ }
201
+
202
+ /** Everything a run produced. Seeded, so it replays. */
203
+ export interface VirtualUserRunResult {
204
+ seed: number
205
+ tally: VirtualUserTally
206
+ findings: VirtualUserFinding[]
207
+ intents: IntentRecord[]
208
+ steps: StepRecord[]
209
+ /** Ids and slugs the user saw, for seeding a later `stale` run. */
210
+ memory: Record<string, string>
211
+ /** Why the run ended. */
212
+ stoppedBy:
213
+ | 'no-intents'
214
+ | 'budget-steps'
215
+ | 'budget-mutations'
216
+ | 'budget-duration'
217
+ | 'stop-hook'
218
+ | 'exhausted'
219
+ }
@@ -6,10 +6,11 @@
6
6
  import type { StandardSchemaV1 } from '@standard-schema/spec'
7
7
 
8
8
  import type { WorkflowRun } from '../workflow.types.js'
9
- import type { ScenarioActor } from '../../../services/scenario-actors-service.js'
9
+ import type { ScenarioPersona } from '../../../services/personas-service.js'
10
10
  import type {
11
11
  ScenarioStepOptions,
12
12
  ScenarioStepPhase,
13
+ ScenarioSurface,
13
14
  } from '../scenario-step.types.js'
14
15
 
15
16
  /**
@@ -35,7 +36,7 @@ export interface WorkflowStepOptions {
35
36
  * internally — so auth middleware and permissions are exercised end-to-end.
36
37
  * The step is recorded durably like any RPC step.
37
38
  */
38
- actor?: ScenarioActor
39
+ actor?: ScenarioPersona
39
40
  // Future: timeout, failFast, priority
40
41
  }
41
42
 
@@ -221,8 +222,8 @@ export interface ScenarioStepMeta {
221
222
  options?: WorkflowStepOptions
222
223
  /** Scenario actor name this step runs as ({ actor: actors.x }) */
223
224
  actor?: string
224
- /** Mirrors the step function's `browser: true` declaration */
225
- browser?: boolean
225
+ /** Mirrors the surfaces the step function declares a binding for */
226
+ surfaces?: ScenarioSurface[]
226
227
  }
227
228
 
228
229
  /**
@@ -1,10 +1,6 @@
1
1
  import { pikkuState } from '../../../pikku-state.js'
2
2
  import { addFunction } from '../../../function/function-runner.js'
3
3
 
4
- /**
5
- * Add a workflow to the system
6
- * This is called by the generated workflow wirings
7
- */
8
4
  export const addWorkflow = (
9
5
  workflowName: string,
10
6
  workflowFunc: any,
@@ -5,10 +5,6 @@ import type {
5
5
  FeaturePlanEntry,
6
6
  } from './workflow.types.js'
7
7
 
8
- /**
9
- * Register a feature under the name it is exported as. Called from generated
10
- * wiring, the same way `addWorkflow` is.
11
- */
12
8
  export const addFeature = (
13
9
  featureId: string,
14
10
  feature: CoreFeature,
@@ -17,21 +13,6 @@ export const addFeature = (
17
13
  pikkuState(packageName, 'workflows', 'features').set(featureId, feature)
18
14
  }
19
15
 
20
- /**
21
- * Resolve every feature's scenario references back to the names their
22
- * scenarios are registered under.
23
- *
24
- * Matching is by **object identity**: `pikkuScenario` returns its config
25
- * verbatim and `addWorkflow` registers that same object, so a feature holding
26
- * the imported identifier holds the very object that was registered. Nothing
27
- * is matched by shape, by name, or by any other guess — which is also why a
28
- * scenario built inline inside a feature (and therefore never registered)
29
- * comes back as unresolved rather than silently running as something else.
30
- *
31
- * Entries are returned in declaration order, features in registration order.
32
- * A scenario's effective tags are its own plus the containing feature's, so
33
- * `--tags credential` selects through the feature.
34
- */
35
16
  export const resolveFeatureScenarios = (
36
17
  features: Map<string, CoreFeature>,
37
18
  registrations: Map<string, CoreWorkflow>
@@ -4,82 +4,11 @@ import type {
4
4
  RefValue,
5
5
  } from './workflow-graph.types.js'
6
6
 
7
- /**
8
- * Standard RPC handler interface (matches generated FlattenedRPCMap entries)
9
- */
10
7
  export interface RPCHandler<I = any, O = any> {
11
8
  input: I
12
9
  output: O
13
10
  }
14
11
 
15
- /**
16
- * Compute output types for all nodes based on their func (RPC name)
17
- */
18
- export type NodeOutputMap<
19
- Nodes extends Record<string, { func: string }>,
20
- RPCMap extends Record<string, RPCHandler>,
21
- > = {
22
- [K in keyof Nodes]: Nodes[K]['func'] extends keyof RPCMap
23
- ? RPCMap[Nodes[K]['func']]['output']
24
- : unknown
25
- }
26
-
27
- /**
28
- * Node definition with RPC name reference
29
- */
30
- export interface GraphNodeDef<
31
- RPCMap extends Record<string, RPCHandler>,
32
- NodeIds extends string = string,
33
- NodeOutputs extends Record<string, any> = Record<string, any>,
34
- > {
35
- /** RPC function name (must be a key in RPCMap) */
36
- func: keyof RPCMap & string
37
- /** Input mapping - reference outputs from other nodes with autocomplete */
38
- input?: (
39
- ref: <N extends keyof NodeOutputs & string>(
40
- nodeId: N,
41
- path: keyof NodeOutputs[N] & string
42
- ) => RefValue
43
- ) => Record<string, unknown>
44
- /** Next node(s) to execute */
45
- next?: NextConfig<NodeIds>
46
- /** Error handling - node(s) to execute on error */
47
- onError?: NodeIds | NodeIds[]
48
- /** Maximum retry attempts allowed (excludes the initial attempt) */
49
- retries?: number
50
- /** Delay between retries — milliseconds, duration string, or 'exponential' */
51
- retryDelay?: string | number
52
- }
53
-
54
- /**
55
- * Helper to create a type-safe graph definition with RPC autocomplete.
56
- * Pass node IDs as first type parameter for type-safe next/ref/output key completion.
57
- *
58
- * @example
59
- * ```typescript
60
- * // Import the typed graph from generated types
61
- * import { pikkuWorkflowGraph } from './.pikku/workflow/pikku-workflow-types.gen.js'
62
- *
63
- * export const myGraph = pikkuWorkflowGraph({
64
- * name: 'myWorkflow',
65
- * nodes: {
66
- * entry: 'createUserProfile', // autocompletes RPC names
67
- * sendWelcome: 'sendEmail',
68
- * },
69
- * config: {
70
- * entry: { next: 'sendWelcome' },
71
- * sendWelcome: {
72
- * input: (ref) => ({
73
- * to: ref('entry', 'email'), // 'entry' and 'email' both autocomplete
74
- * }),
75
- * },
76
- * },
77
- * })
78
- * ```
79
- */
80
- /**
81
- * Type to compute output types for all nodes based on their func mapping
82
- */
83
12
  type ComputeNodeOutputs<
84
13
  FuncMap extends Record<string, string>,
85
14
  RPCMap extends Record<string, RPCHandler>,
@@ -89,9 +18,6 @@ type ComputeNodeOutputs<
89
18
  : unknown
90
19
  }
91
20
 
92
- /**
93
- * Type to compute input types for all nodes based on their func mapping
94
- */
95
21
  type ComputeNodeInputs<
96
22
  FuncMap extends Record<string, string>,
97
23
  RPCMap extends Record<string, RPCHandler>,
@@ -101,15 +27,8 @@ type ComputeNodeInputs<
101
27
  : unknown
102
28
  }
103
29
 
104
- /**
105
- * Typed ref value - carries the type of the referenced field as a phantom type.
106
- * At runtime this is just RefValue, but TypeScript tracks the type T.
107
- */
108
30
  export type TypedRef<T> = RefValue & { __phantomType?: T }
109
31
 
110
- /**
111
- * Map input type fields to allow TypedRef of matching type as an alternative
112
- */
113
32
  type InputWithRefs<T> = {
114
33
  [K in keyof T]: T[K] | TypedRef<T[K]>
115
34
  }
@@ -126,7 +45,6 @@ export function createGraph<RPCMap extends Record<string, RPCHandler>>() {
126
45
  > => {
127
46
  type NodeIds = Extract<keyof FuncMap, string>
128
47
 
129
- // If no nodes provided, return just the funcMap converted to graph nodes
130
48
  if (!nodesOrBuilder) {
131
49
  const result: Record<string, GraphNodeConfig<string>> = {}
132
50
  for (const [nodeId, rpcName] of Object.entries(funcMap)) {
@@ -159,9 +77,6 @@ export function createGraph<RPCMap extends Record<string, RPCHandler>>() {
159
77
  }
160
78
  }
161
79
 
162
- /**
163
- * Type helper for node configuration map
164
- */
165
80
  type GraphNodeConfigMap<
166
81
  FuncMap extends Record<string, string>,
167
82
  RPCMap extends Record<string, RPCHandler>,
@@ -180,57 +95,6 @@ type GraphNodeConfigMap<
180
95
  onError?: Extract<keyof FuncMap, string> | Extract<keyof FuncMap, string>[]
181
96
  retries?: number
182
97
  retryDelay?: string | number
183
- /** Free-text node documentation. Non-semantic — excluded from graphHash. */
184
98
  notes?: string
185
99
  }
186
100
  }
187
-
188
- /**
189
- * Untyped graph for use without RPC map.
190
- * Pass node IDs as type parameter for type-safe next/ref, or omit for untyped usage.
191
- *
192
- * @example
193
- * ```typescript
194
- * // Typed usage - next and ref are type-checked
195
- * graph<'entry' | 'sendWelcome'>({
196
- * entry: { func: 'createUserProfile', next: 'sendWelcome' },
197
- * sendWelcome: { func: 'sendEmail', input: (ref) => ({ to: ref('entry', 'email') }) },
198
- * })
199
- *
200
- * // Untyped usage - no type checking on next/ref
201
- * graph({
202
- * entry: { func: 'createUserProfile', next: 'sendWelcome' },
203
- * sendWelcome: { func: 'sendEmail' },
204
- * })
205
- * ```
206
- */
207
- export function graph<NodeIds extends string = string>(
208
- nodes: Record<
209
- NodeIds,
210
- {
211
- func: string
212
- next?: NextConfig<NodeIds>
213
- input?: (
214
- ref: (nodeId: NodeIds, path: string) => RefValue
215
- ) => Record<string, unknown>
216
- onError?: NodeIds | NodeIds[]
217
- retries?: number
218
- retryDelay?: string | number
219
- }
220
- >
221
- ): Record<NodeIds, GraphNodeConfig<NodeIds>> {
222
- const result: Record<string, GraphNodeConfig<string>> = {}
223
-
224
- for (const [nodeId, def] of Object.entries(nodes) as [string, any][]) {
225
- result[nodeId] = {
226
- func: def.func,
227
- input: def.input as any,
228
- next: def.next,
229
- onError: def.onError,
230
- retries: def.retries,
231
- retryDelay: def.retryDelay,
232
- }
233
- }
234
-
235
- return result as Record<NodeIds, GraphNodeConfig<NodeIds>>
236
- }
@@ -258,8 +258,6 @@ describe('graph-runner bugs', () => {
258
258
  },
259
259
  } as any)
260
260
 
261
- // start → a, where a loops back through b once, then exits to c:
262
- // start → a --retry--> b → a --done--> c
263
261
  const meta: WorkflowRuntimeMeta = {
264
262
  name: 'testCyclicGraph',
265
263
  pikkuFuncId: 'testCyclicGraph',
@@ -274,11 +272,16 @@ describe('graph-runner bugs', () => {
274
272
  },
275
273
  }
276
274
 
277
- const runId = await ws.createRun('testCyclicGraph', {}, false, 'cyclic-hash', {
278
- type: 'test',
279
- })
275
+ const runId = await ws.createRun(
276
+ 'testCyclicGraph',
277
+ {},
278
+ false,
279
+ 'cyclic-hash',
280
+ {
281
+ type: 'test',
282
+ }
283
+ )
280
284
 
281
- // Succeed a queued step (taking an optional branch), then advance the graph.
282
285
  const advance = async (stepName: string, branch?: string) => {
283
286
  const step = await ws.getStepState(runId, stepName)
284
287
  await ws.setStepRunning(step.stepId)
@@ -287,15 +290,13 @@ describe('graph-runner bugs', () => {
287
290
  await continueGraph(ws, runId, 'testCyclicGraph', meta)
288
291
  }
289
292
 
290
- await continueGraph(ws, runId, 'testCyclicGraph', meta) // fire entry
293
+ await continueGraph(ws, runId, 'testCyclicGraph', meta)
291
294
  await advance('start')
292
- await advance('a', 'retry') // a → b (b reaches a, but first visit ⇒ bare 'b')
293
- await advance('b') // b → a revisit ⇒ a#1
294
- await advance('a#1', 'done') // a#1 → c (forward edge, terminal)
295
+ await advance('a', 'retry')
296
+ await advance('b')
297
+ await advance('a#1', 'done')
295
298
  await advance('c')
296
299
 
297
- // Each step records the predecessor it was reached from; the cyclic
298
- // revisit is a fresh ordinal instance (a#1) with its own provenance.
299
300
  assert.deepEqual(queued, [
300
301
  { stepName: 'start', fromStepName: undefined },
301
302
  { stepName: 'a', fromStepName: 'start' },
@@ -307,7 +308,6 @@ describe('graph-runner bugs', () => {
307
308
  const run = await ws.getRun(runId)
308
309
  assert.equal(run?.status, 'completed')
309
310
 
310
- // Reconstruct the walked path purely from the fromStepName chain.
311
311
  const instances = await ws.getStepInstances(runId)
312
312
  const from = new Map(instances.map((i) => [i.stepName, i.fromStepName]))
313
313
  const path: string[] = []
@@ -419,7 +419,6 @@ describe('graph-runner bugs', () => {
419
419
  test('inline graph revisits a cyclic node and records the walked path via fromStepName', async () => {
420
420
  const ws = new InMemoryWorkflowService()
421
421
 
422
- // attempt loops back to itself via `again` until it converges to `done`.
423
422
  const mockRpcService = {
424
423
  rpcWithWire: async (rpcName: string, _data: any, wire: any) => {
425
424
  if (rpcName === 'cyclicBegin') return { attempts: 3 }
@@ -464,7 +463,6 @@ describe('graph-runner bugs', () => {
464
463
  const run = await ws.getRun(runId)
465
464
  assert.equal(run?.status, 'completed')
466
465
 
467
- // The self-cycle produced three ordinal instances of `attempt`.
468
466
  const instances = await ws.getStepInstances(runId)
469
467
  const names = instances.map((i) => i.stepName).sort()
470
468
  assert.ok(
@@ -474,8 +472,6 @@ describe('graph-runner bugs', () => {
474
472
  `expected attempt/attempt#1/attempt#2, got ${JSON.stringify(names)}`
475
473
  )
476
474
 
477
- // Walk the fromStepName chain back from the terminal node — inline now
478
- // records provenance identical to the queued path.
479
475
  const from = new Map(instances.map((i) => [i.stepName, i.fromStepName]))
480
476
  const path: string[] = []
481
477
  let cursor: string | undefined = 'finish'
@@ -483,7 +479,13 @@ describe('graph-runner bugs', () => {
483
479
  path.unshift(cursor)
484
480
  cursor = from.get(cursor) ?? undefined
485
481
  }
486
- assert.deepEqual(path, ['begin', 'attempt', 'attempt#1', 'attempt#2', 'finish'])
482
+ assert.deepEqual(path, [
483
+ 'begin',
484
+ 'attempt',
485
+ 'attempt#1',
486
+ 'attempt#2',
487
+ 'finish',
488
+ ])
487
489
 
488
490
  delete metaState['testInlineCyclic']
489
491
  })
@@ -647,7 +649,6 @@ describe('graph-runner bugs', () => {
647
649
  },
648
650
  }
649
651
 
650
- // Set up queue service to verify nothing is queued
651
652
  let queued = false
652
653
  pikkuState(null, 'package', 'singletonServices', {
653
654
  queueService: {