evolcore 0.0.49 → 0.0.51

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 (514) hide show
  1. package/CHANGELOG.md +103 -3
  2. package/bin/ec-build.mjs +60 -0
  3. package/bin/ecmsg.js +64 -57
  4. package/dist/ability/caller/authorization.js +21 -0
  5. package/dist/ability/caller/command.js +173 -0
  6. package/dist/ability/caller/contract.js +117 -0
  7. package/dist/ability/caller/credential-files.js +132 -0
  8. package/dist/ability/caller/daemon.js +183 -0
  9. package/dist/ability/caller/schema-view.js +157 -0
  10. package/dist/ability/caller/service.js +519 -0
  11. package/dist/ability/command-contract.js +5 -0
  12. package/dist/ability/daemon.js +5 -1
  13. package/dist/ability/interop-v1.js +156 -106
  14. package/dist/ability/management.js +1 -0
  15. package/dist/agent-template/jobs.js +79 -3
  16. package/dist/agent-template/runtime.js +459 -47
  17. package/dist/agent-template/service.js +1242 -198
  18. package/dist/agent-template/share.js +103 -0
  19. package/dist/agent-template/tool-runner.js +25 -0
  20. package/dist/agent-template/types.js +10 -2
  21. package/dist/agents/claude/availability.js +94 -0
  22. package/dist/agents/claude/capability-provider.js +154 -0
  23. package/dist/agents/claude/index.js +145 -0
  24. package/dist/agents/{claude-runner.js → claude/runner.js} +78 -166
  25. package/dist/agents/claude/session-file-adapter.js +246 -0
  26. package/dist/agents/codex/app-server-client.js +90 -10
  27. package/dist/agents/codex/availability.js +164 -0
  28. package/dist/agents/codex/capability-provider.js +138 -0
  29. package/dist/agents/codex/cli.js +38 -0
  30. package/dist/agents/codex/index.js +345 -0
  31. package/dist/agents/codex/mcp-elicitation.js +135 -0
  32. package/dist/agents/{codex-runner.js → codex/runner.js} +652 -383
  33. package/dist/agents/codex/session-file-adapter.js +834 -0
  34. package/dist/agents/dsh/availability.js +28 -0
  35. package/dist/agents/dsh/capability-provider.js +56 -0
  36. package/dist/agents/dsh/desktop-locations.ps1 +66 -0
  37. package/dist/agents/dsh/desktop-probe.cjs +37 -0
  38. package/dist/agents/dsh/index.js +98 -0
  39. package/dist/agents/dsh/installation.js +400 -0
  40. package/dist/agents/dsh/resources.js +755 -0
  41. package/dist/agents/dsh/runner.js +1183 -0
  42. package/dist/agents/dsh/runtime/README.md +243 -0
  43. package/dist/agents/dsh/runtime/authorization.js +23 -0
  44. package/dist/agents/dsh/runtime/bridge.js +837 -0
  45. package/dist/agents/dsh/runtime/config.js +271 -0
  46. package/dist/agents/dsh/runtime/entry.js +229 -0
  47. package/dist/agents/dsh/runtime/session-inspector.js +340 -0
  48. package/dist/agents/dsh/runtime/tool-policy.js +49 -0
  49. package/dist/agents/dsh/session-file-adapter.js +145 -0
  50. package/dist/agents/ecagent/index.js +215 -0
  51. package/dist/agents/{ecagent-runner.js → ecagent/runner.js} +592 -106
  52. package/dist/agents/ecagent/session-file-adapter.js +134 -0
  53. package/dist/agents/gemini/index.js +96 -0
  54. package/dist/agents/{gemini-runner.js → gemini/runner.js} +18 -23
  55. package/dist/{core/session/adapters/gemini-session-file-adapter.js → agents/gemini/session-file-adapter.js} +2 -2
  56. package/dist/aun/ability-device-routing.js +11 -17
  57. package/dist/aun/aid/agentmd.js +27 -1
  58. package/dist/aun/aid/control-aid.js +52 -32
  59. package/dist/aun/aid/managed-operation.js +6 -4
  60. package/dist/aun/group/invite-service.js +7 -37
  61. package/dist/aun/group/operations.js +6 -0
  62. package/dist/aun/menu/client.js +1 -1
  63. package/dist/aun/msg/history.js +1 -1
  64. package/dist/aun/msg/managed-operation.js +93 -21
  65. package/dist/aun/msg/mention-schema.js +1 -1
  66. package/dist/aun/msg/p2p.js +32 -4
  67. package/dist/aun/msg/upload.js +126 -3
  68. package/dist/aun/service-proxy.js +1 -1
  69. package/dist/aun/storage/index.js +242 -0
  70. package/dist/build-identity.json +1 -1
  71. package/dist/channels/aun.js +698 -213
  72. package/dist/channels/daemon.js +3 -2
  73. package/dist/channels/dingtalk.js +1 -1
  74. package/dist/channels/feishu.js +9 -9
  75. package/dist/channels/qqbot.js +1 -1
  76. package/dist/channels/wechat.js +2 -2
  77. package/dist/channels/wecom.js +1 -1
  78. package/dist/claude-gateway/agent-registration.js +389 -0
  79. package/dist/claude-gateway/binding.js +96 -0
  80. package/dist/claude-gateway/inbox.js +138 -0
  81. package/dist/claude-gateway/index.js +125 -0
  82. package/dist/claude-gateway/listing.js +330 -0
  83. package/dist/claude-gateway/router.js +328 -0
  84. package/dist/claude-gateway/sessions.js +128 -0
  85. package/dist/claude-gateway/terminal.js +250 -0
  86. package/dist/claude-gateway/transcript.js +272 -0
  87. package/dist/claude-gateway/types.js +14 -0
  88. package/dist/cli/ability-command.js +45 -0
  89. package/dist/cli/ability-output.js +182 -0
  90. package/dist/cli/agent-command.js +21 -2
  91. package/dist/cli/agent-create.js +197 -56
  92. package/dist/cli/agent-template.js +400 -27
  93. package/dist/cli/agent.js +105 -11
  94. package/dist/cli/aun-commands.js +237 -123
  95. package/dist/cli/bench.js +5 -2
  96. package/dist/cli/config.js +22 -6
  97. package/dist/cli/daemon-commands.js +283 -109
  98. package/dist/cli/data-command.js +1 -1
  99. package/dist/cli/debug-mode.js +9 -0
  100. package/dist/cli/directory.js +1 -2
  101. package/dist/cli/ecmsg-gateway.js +64 -26
  102. package/dist/cli/fs-command.js +67 -39
  103. package/dist/cli/index.js +45 -12
  104. package/dist/cli/init.js +161 -90
  105. package/dist/cli/managed-command-guard.js +3 -0
  106. package/dist/cli/menu-client.js +32 -7
  107. package/dist/cli/model.js +1 -1
  108. package/dist/cli/pay-command.js +30 -0
  109. package/dist/cli/provider-command.js +6 -2
  110. package/dist/cli/restart-monitor.js +4 -4
  111. package/dist/cli/services-command.js +35 -10
  112. package/dist/cli/skill-command.js +4 -4
  113. package/dist/cli/task-context.js +24 -14
  114. package/dist/cli/team-workspace-command.js +50 -52
  115. package/dist/cli/thread-command.js +81 -14
  116. package/dist/cli/trigger-command.js +47 -12
  117. package/dist/cli/watch-logs.js +2 -1
  118. package/dist/config/access-policy.js +16 -3
  119. package/dist/config/boot-log.js +3 -0
  120. package/dist/config/builtin-role-templates.js +1 -1
  121. package/dist/config/config-field-policy.js +26 -13
  122. package/dist/config/config-manager.js +113 -52
  123. package/dist/config/config-operation-service.js +22 -1
  124. package/dist/config/gateway-config.js +29 -44
  125. package/dist/config/invoke-ipc-service.js +1 -1
  126. package/dist/config/owner-config.js +5 -19
  127. package/dist/config/peer-book-store.js +2 -3
  128. package/dist/config/peer-book.js +2 -2
  129. package/dist/config/peer-role-resolver.js +3 -9
  130. package/dist/config/provider-identity-migration.js +24 -105
  131. package/dist/config/provider-ipc-service.js +13 -3
  132. package/dist/config/provider-local-sync.js +4 -1
  133. package/dist/config/provider-menu-request.js +21 -3
  134. package/dist/config/provider-templates.js +1 -1
  135. package/dist/config/providers-config.js +138 -31
  136. package/dist/config/providers-import.js +3 -3
  137. package/dist/config/providers-management.js +109 -118
  138. package/dist/config/resolved-config-op.js +1 -42
  139. package/dist/config/schema-migration.js +254 -15
  140. package/dist/config/schema-registry.js +53 -8
  141. package/dist/config-store.js +1343 -63
  142. package/dist/core/{agent-application-service.js → agent/agent-application-service.js} +228 -9
  143. package/dist/core/{agent-create-status.js → agent/agent-create-status.js} +112 -4
  144. package/dist/core/{agent-creation-claim.js → agent/agent-creation-claim.js} +3 -3
  145. package/dist/core/{agent-ipc-registration.js → agent/agent-ipc-registration.js} +119 -25
  146. package/dist/core/{agent-reload-coordinator.js → agent/agent-reload-coordinator.js} +65 -0
  147. package/dist/core/{agent-runtime.js → agent/agent-runtime.js} +249 -79
  148. package/dist/core/{evolagent-registry.js → agent/evolagent-registry.js} +23 -18
  149. package/dist/core/{evolagent.js → agent/evolagent.js} +11 -11
  150. package/dist/core/auth/agent-delegation.js +15 -8
  151. package/dist/core/auth/delegation-authorization.js +28 -0
  152. package/dist/core/auth/operation-authorizer.js +20 -2
  153. package/dist/core/auth/operation-catalog.js +80 -8
  154. package/dist/core/baseagent/baseagent-availability.js +197 -0
  155. package/dist/core/baseagent/baseagent-capability-adapter.js +288 -0
  156. package/dist/core/baseagent/baseagent-config-shared.js +56 -0
  157. package/dist/core/baseagent/baseagent-identity.js +68 -0
  158. package/dist/core/{baseagent-loader.js → baseagent/baseagent-loader.js} +89 -6
  159. package/dist/core/baseagent/baseagent-model-defaults.js +26 -0
  160. package/dist/core/baseagent/baseagent-plugin-descriptor.js +357 -0
  161. package/dist/core/baseagent/baseagent-plugin-loader.js +367 -0
  162. package/dist/core/baseagent/baseagent.js +157 -0
  163. package/dist/{agents → core/baseagent}/runner-types.js +36 -4
  164. package/dist/core/capability/capability-manager.js +91 -33
  165. package/dist/core/capability/providers/claude-capability-provider.js +2 -154
  166. package/dist/core/capability/providers/codex-capability-provider.js +2 -136
  167. package/dist/core/{channel-loader.js → channel/channel-loader.js} +226 -38
  168. package/dist/core/{channel-runtime.js → channel/channel-runtime.js} +21 -19
  169. package/dist/core/command/agent-control.js +80 -17
  170. package/dist/core/command/agent-template-menu.js +23 -10
  171. package/dist/core/command/agentmd-menu-request.js +19 -8
  172. package/dist/core/command/agentmd-menu.js +14 -5
  173. package/dist/core/command/cli-intent-parser.js +15 -0
  174. package/dist/core/command/command-handler.js +127 -57
  175. package/dist/core/command/context-policy-menu.js +122 -0
  176. package/dist/core/command/data-root-resolver.js +157 -20
  177. package/dist/core/command/memory-slash.js +6 -6
  178. package/dist/core/command/menu-catalog.js +95 -19
  179. package/dist/core/command/menu-file-path.js +70 -0
  180. package/dist/core/command/menu-handler.js +392 -93
  181. package/dist/core/command/menu-protocol.js +47 -8
  182. package/dist/core/command/menu-query-batch.js +9 -5
  183. package/dist/core/command/private-mention-menu.js +71 -0
  184. package/dist/core/command/provider-menu.js +7 -11
  185. package/dist/core/command/role-menu.js +1 -1
  186. package/dist/core/command/skill-slash.js +17 -5
  187. package/dist/core/command/slash-gate.js +2 -4
  188. package/dist/core/command/slash-handler.js +143 -121
  189. package/dist/core/command/team-workspace-bootstrap.js +2 -1
  190. package/dist/core/command/team-workspace-team.js +3 -3
  191. package/dist/core/command/topic-slash.js +16 -10
  192. package/dist/core/{daemon-bootstrap.js → daemon/daemon-bootstrap.js} +14 -18
  193. package/dist/core/{daemon-control.js → daemon/daemon-control.js} +48 -21
  194. package/dist/core/{daemon-lifecycle.js → daemon/daemon-lifecycle.js} +28 -20
  195. package/dist/core/{host-snapshot.js → daemon/host-snapshot.js} +10 -5
  196. package/dist/core/{ipc-registration.js → daemon/ipc-registration.js} +101 -37
  197. package/dist/core/{lifecycle-notice.js → daemon/lifecycle-notice.js} +4 -5
  198. package/dist/core/file-integrity/store.js +1 -1
  199. package/dist/core/handoff/ipc-registration.js +3 -3
  200. package/dist/core/handoff/runtime.js +2 -2
  201. package/dist/{agents → core/inference}/request-identity.js +2 -2
  202. package/dist/core/inference/text-inference.js +4 -4
  203. package/dist/core/{bootstrap-messages.js → initialization/bootstrap-messages.js} +10 -10
  204. package/dist/core/{bootstrap-service.js → initialization/bootstrap-service.js} +24 -23
  205. package/dist/core/initialization/service.js +57 -9
  206. package/dist/core/invoke/executors/media.js +1 -1
  207. package/dist/core/invoke/executors/text.js +1 -1
  208. package/dist/core/memory/consolidation-context.js +3 -2
  209. package/dist/core/memory/consolidation-trigger.js +9 -3
  210. package/dist/core/memory/consolidation.js +39 -68
  211. package/dist/core/memory/memory-admin.js +6 -6
  212. package/dist/core/memory/memory-writer.js +1 -1
  213. package/dist/core/memory/relation-idle-monitor.js +1 -1
  214. package/dist/core/message/aun-ipc-sender.js +204 -88
  215. package/dist/core/message/aun-request-registry.js +44 -5
  216. package/dist/core/message/auto-mention-gate.js +1 -1
  217. package/dist/core/message/contact-admission.js +1 -1
  218. package/dist/core/message/im-renderer.js +19 -0
  219. package/dist/core/{interaction-router.js → message/interaction-router.js} +131 -1
  220. package/dist/core/message/items-formatter.js +5 -5
  221. package/dist/core/message/message-admission.js +1 -1
  222. package/dist/core/message/message-bridge.js +239 -59
  223. package/dist/core/message/message-log.js +8 -0
  224. package/dist/core/message/message-queue.js +88 -7
  225. package/dist/core/message/message-utils.js +1 -1
  226. package/dist/core/message/peer-mode.js +16 -5
  227. package/dist/core/message/response-engine.js +351 -152
  228. package/dist/core/message/send-options.js +44 -7
  229. package/dist/core/message/send-routing.js +55 -115
  230. package/dist/core/message/stream-idle-monitor.js +1 -1
  231. package/dist/core/{data-migration.js → migration/data-migration.js} +29 -1
  232. package/dist/core/model/catalog-service.js +29 -8
  233. package/dist/core/model/model-capabilities.js +88 -0
  234. package/dist/core/model/model-catalog.js +18 -7
  235. package/dist/core/model/model-diagnostics.js +4 -4
  236. package/dist/core/ownership/owner-resolver.js +107 -101
  237. package/dist/core/{pack-auth.js → pack/pack-auth.js} +34 -3
  238. package/dist/core/{pack-install.js → pack/pack-install.js} +95 -17
  239. package/dist/core/permission/approval-gateway.js +9 -18
  240. package/dist/core/permission/ec-command-parser.js +242 -82
  241. package/dist/core/permission/managed-file.js +234 -0
  242. package/dist/core/permission/protected-paths.js +120 -9
  243. package/dist/core/permission/sandbox-runtime.js +267 -3
  244. package/dist/core/permission/services-path-acl.js +9 -2
  245. package/dist/core/permission/session-path-grants.js +1 -1
  246. package/dist/core/permission/shell-environment.js +15 -1
  247. package/dist/core/permission/tool-policy.js +21 -9
  248. package/dist/core/plugin/plugin-lifecycle.js +442 -0
  249. package/dist/core/session/adapters/claude-session-file-adapter.js +2 -242
  250. package/dist/core/session/adapters/codex-session-file-adapter.js +2 -562
  251. package/dist/core/session/adapters/ecagent-session-file-adapter.js +2 -134
  252. package/dist/core/{background-session → session/background}/session-cleanup.js +2 -2
  253. package/dist/core/{background-session → session/background}/types.js +1 -1
  254. package/dist/core/session/session-file-health.js +2 -272
  255. package/dist/core/session/session-idle-monitor.js +1 -1
  256. package/dist/core/session/session-manager.js +76 -12
  257. package/dist/core/session/session-mapper.js +16 -0
  258. package/dist/core/session/session-terminal.js +185 -0
  259. package/dist/core/session/session-title.js +8 -11
  260. package/dist/core/{system-session → session/system}/memory.js +43 -9
  261. package/dist/core/{system-session → session/system}/registry.js +1 -1
  262. package/dist/core/{system-session → session/system}/types.js +1 -1
  263. package/dist/core/skill/index-generator.js +3 -3
  264. package/dist/core/skill/switch-resolver.js +3 -0
  265. package/dist/core/task/task-activity-store.js +112 -0
  266. package/dist/core/task/task-recovery-service.js +2 -2
  267. package/dist/core/thread/command-parser.js +4 -1
  268. package/dist/core/thread/ipc-operation.js +6 -4
  269. package/dist/core/thread/thread-operation.js +27 -11
  270. package/dist/core/thread/thread-route.js +5 -3
  271. package/dist/core/thread/thread-service.js +307 -58
  272. package/dist/core/thread/topic-id.js +52 -2
  273. package/dist/core/thread/types.js +15 -1
  274. package/dist/directory/{owner-directory-admission.js → admission.js} +3 -3
  275. package/dist/directory/{owner-directory-cache.js → cache.js} +90 -8
  276. package/dist/directory/{owner-directory-markdown.js → markdown.js} +2 -2
  277. package/dist/directory/{owner-directory-query-operation.js → query-operation.js} +83 -9
  278. package/dist/directory/{owner-directory-search.js → search.js} +50 -2
  279. package/dist/directory/{owner-directory-store.js → store.js} +2 -2
  280. package/dist/eck/kit-renderer.js +3 -2
  281. package/dist/eck/manifest-engine.js +64 -2
  282. package/dist/eck/message-renderer.js +35 -0
  283. package/dist/ecweb/basic-settings-service.js +12 -10
  284. package/dist/{contracts → ecweb/contracts}/ecweb-service-protocol.js +2 -1
  285. package/dist/ecweb/dsh-native-service.js +413 -0
  286. package/dist/ecweb/providers-service.js +5 -3
  287. package/dist/ecweb/runtime/lifecycle.js +1 -1
  288. package/dist/ecweb/runtime/supervisor.js +1 -1
  289. package/dist/event-center/center-config.js +2 -2
  290. package/dist/event-center/dispatcher.js +1 -1
  291. package/dist/event-center/ipc-operation.js +12 -3
  292. package/dist/event-center/pack-loader.js +2 -2
  293. package/dist/event-center/registry.js +6 -6
  294. package/dist/event-center/runtime.js +2 -2
  295. package/dist/index.js +181 -77
  296. package/dist/ipc.js +161 -12
  297. package/dist/outputs/authorization.js +27 -0
  298. package/dist/outputs/events.js +10 -1
  299. package/dist/outputs/panel-cards.js +960 -0
  300. package/dist/paths.js +60 -1
  301. package/dist/pay/command.js +38 -0
  302. package/dist/pay/protocol.js +136 -0
  303. package/dist/pay/runtime.js +196 -0
  304. package/dist/pay/service.js +384 -0
  305. package/dist/pay/store.js +81 -0
  306. package/dist/response-system/engines/v1/proactive-flow.js +30 -3
  307. package/dist/services/dispatcher.js +25 -7
  308. package/dist/services/host/main.js +397 -0
  309. package/dist/services/host/protocol.js +125 -0
  310. package/dist/services/host/resident.js +347 -0
  311. package/dist/services/host-client.js +398 -0
  312. package/dist/services/host-deploy.js +180 -0
  313. package/dist/services/host-launch.js +117 -0
  314. package/dist/services/host-recycle.js +208 -0
  315. package/dist/services/host-runtime.js +841 -0
  316. package/dist/services/idempotency.js +44 -86
  317. package/dist/services/index-generator.js +4 -3
  318. package/dist/services/index.js +258 -36
  319. package/dist/services/ipc-operation.js +503 -78
  320. package/dist/services/pack-manager.js +2 -2
  321. package/dist/services/router.js +43 -3
  322. package/dist/services/script-runner.js +541 -100
  323. package/dist/services/service-payload.js +28 -1
  324. package/dist/services/validation.js +136 -5
  325. package/dist/stats/context-usage.js +110 -0
  326. package/dist/stats/model-resolver.js +103 -17
  327. package/dist/stats/query.js +5 -0
  328. package/dist/trigger/application-service.js +9 -6
  329. package/dist/trigger/authorization.js +36 -33
  330. package/dist/trigger/ipc-service.js +4 -4
  331. package/dist/trigger/local-files.js +8 -166
  332. package/dist/trigger/manager.js +2 -2
  333. package/dist/trigger/parser.js +48 -0
  334. package/dist/trigger/scheduler.js +35 -13
  335. package/dist/trigger/script-executor.js +21 -0
  336. package/dist/trigger/script-sandbox.js +77 -232
  337. package/dist/trigger/system-definitions.js +25 -0
  338. package/dist/trigger/validation.js +1 -1
  339. package/dist/utils/aid-bind.js +3 -0
  340. package/dist/utils/atomic-write.js +88 -1
  341. package/dist/utils/cross-platform.js +4 -42
  342. package/dist/utils/error-dict.json +22 -1
  343. package/dist/utils/error-utils.js +193 -6
  344. package/dist/utils/evolcore-version.js +2 -2
  345. package/dist/utils/host-info.js +74 -1
  346. package/dist/utils/logger.js +5 -3
  347. package/dist/utils/media-cache.js +284 -42
  348. package/dist/utils/restart-safety.js +14 -1
  349. package/dist/utils/startup-trace.js +20 -4
  350. package/dist/utils/system-memory.js +113 -25
  351. package/dist/utils/systemd-lifecycle.js +154 -0
  352. package/dist/utils/welcome.js +64 -20
  353. package/dist/utils/windows-shell-trust.js +7 -3
  354. package/ecagent/README.md +35 -0
  355. package/ecagent/dist/agent-loop.js +80 -30
  356. package/ecagent/dist/harness/env/nodejs.d.ts +16 -0
  357. package/ecagent/dist/harness/env/nodejs.js +49 -20
  358. package/ecagent/dist/harness/messages.js +3 -2
  359. package/ecagent/dist/harness/types.d.ts +1 -0
  360. package/ecagent/dist/runtime/types.d.ts +2 -0
  361. package/ecagent/dist/runtime/utils/validation.d.ts +7 -1
  362. package/ecagent/dist/runtime/utils/validation.js +42 -0
  363. package/ecagent/dist/types.d.ts +2 -0
  364. package/kits/docs/INDEX.md +3 -2
  365. package/kits/docs/aun/AUN/346/266/210/346/201/257/347/261/273/345/236/213/344/270/216/345/261/236/346/200/247.md +1 -0
  366. package/kits/docs/channels/aun.md +1 -1
  367. package/kits/docs/channels/feishu.md +1 -1
  368. package/kits/docs/evolcore/INDEX.md +13 -9
  369. package/kits/docs/evolcore/agent-create.md +2 -0
  370. package/kits/docs/evolcore/agent.md +133 -11
  371. package/kits/docs/evolcore/aid.md +39 -6
  372. package/kits/docs/evolcore/config.md +95 -1
  373. package/kits/docs/evolcore/ctl.md +2 -1
  374. package/kits/docs/evolcore/ec-capabilities.md +7 -10
  375. package/kits/docs/evolcore/ecweb-lifecycle.md +5 -1
  376. package/kits/docs/evolcore/event.md +1 -1
  377. package/kits/docs/evolcore/fs.md +49 -3
  378. package/kits/docs/evolcore/group.md +5 -4
  379. package/kits/docs/evolcore/memory-consolidation.md +1 -1
  380. package/kits/docs/evolcore/memory-tags.md +2 -0
  381. package/kits/docs/evolcore/menu-client.md +3 -3
  382. package/kits/docs/evolcore/menu-protocol.md +31 -2
  383. package/kits/docs/evolcore/model.md +12 -1
  384. package/kits/docs/evolcore/msg.md +96 -36
  385. package/kits/docs/evolcore/pay.md +22 -0
  386. package/kits/docs/evolcore/plugin.md +74 -0
  387. package/kits/docs/evolcore/provider.md +29 -2
  388. package/kits/docs/evolcore/rpc.md +2 -2
  389. package/kits/docs/evolcore/services.md +46 -18
  390. package/kits/docs/evolcore/skill.md +17 -1
  391. package/kits/docs/evolcore/stats.md +5 -0
  392. package/kits/docs/evolcore/storage.md +22 -0
  393. package/kits/docs/evolcore/thread-chain.md +20 -9
  394. package/kits/docs/evolcore/tool-authorization.md +14 -0
  395. package/kits/docs/evolcore/trigger.md +89 -13
  396. package/kits/docs/identity/AID_PROFILE_SPEC.md +1 -1
  397. package/kits/docs/venues/feishu-group.md +3 -2
  398. package/kits/docs/venues/feishu-private.md +3 -2
  399. package/kits/rules/01-overview.md +11 -32
  400. package/kits/rules/02-navigation.md +20 -6
  401. package/kits/rules/06-channel.md +20 -4
  402. package/kits/schemas/_meta.json +42 -5
  403. package/kits/schemas/agent-config.schema.21.json +974 -0
  404. package/kits/schemas/agent-config.schema.22.json +977 -0
  405. package/kits/schemas/agent-config.schema.23.json +974 -0
  406. package/kits/schemas/agent-config.schema.24.json +986 -0
  407. package/kits/schemas/agent-config.schema.25.json +986 -0
  408. package/kits/schemas/daemon.schema.10.json +373 -0
  409. package/kits/schemas/daemon.schema.11.json +487 -0
  410. package/kits/schemas/daemon.schema.12.json +505 -0
  411. package/kits/schemas/daemon.schema.9.json +12 -0
  412. package/kits/schemas/defaults.schema.7.json +472 -0
  413. package/kits/schemas/defaults.schema.8.json +484 -0
  414. package/kits/schemas/providers.schema.1.json +1 -1
  415. package/kits/schemas/providers.schema.2.json +1 -1
  416. package/kits/schemas/providers.schema.3.json +26 -4
  417. package/kits/schemas/relation-config.schema.13.json +289 -0
  418. package/kits/skills/.switches.json +17 -1
  419. package/kits/skills/ability/SKILL.md +395 -33
  420. package/kits/skills/ability/STRUCTURE.md +338 -0
  421. package/kits/skills/ability/references/cli.md +208 -0
  422. package/kits/skills/ability/references/development.md +107 -37
  423. package/kits/skills/ability/references/management.md +106 -46
  424. package/kits/skills/ability/references/runtime-protocol.md +65 -63
  425. package/kits/skills/agent-output-cards/SKILL.md +80 -37
  426. package/kits/skills/agent-output-cards/examples/html-surface.json +11 -0
  427. package/kits/skills/agent-output-cards/examples/meeting-followups.json +16 -0
  428. package/kits/skills/agent-output-cards/examples/meeting-latest.json +24 -0
  429. package/kits/skills/agent-output-cards/examples/project-metrics.json +16 -0
  430. package/kits/skills/agent-output-cards/examples/quick-links.json +18 -0
  431. package/kits/skills/agent-output-cards/examples/surface.html +8 -0
  432. package/kits/skills/agent-template-project/SKILL.md +51 -0
  433. package/kits/skills/agent-template-project/references/01-collect-and-pack.md +174 -0
  434. package/kits/skills/agent-template-project/references/02-upload-and-share.md +109 -0
  435. package/kits/skills/agent-template-project/references/03-download-and-install.md +189 -0
  436. package/kits/skills/agent-template-project/references/04-upgrade-and-recovery.md +74 -0
  437. package/kits/skills/agent-template-project/references/05-publish-to-platform.md +62 -0
  438. package/kits/skills/ec-group/SKILL.md +8 -6
  439. package/kits/skills/ec-group/TASK.md +186 -0
  440. package/kits/skills/ec-group/WORKLOG.md +180 -0
  441. package/kits/skills/ec-group-collaboration/SKILL.md +5 -5
  442. package/kits/skills/ec-identity/SKILL.md +9 -6
  443. package/kits/skills/ec-pay/SKILL.md +223 -0
  444. package/kits/skills/ec-provider/SKILL.md +6 -6
  445. package/kits/skills/{ec-service-proxy → ec-proxy}/SKILL.md +8 -5
  446. package/kits/skills/ec-service-call/SKILL.md +138 -0
  447. package/kits/skills/ec-service-pack/SKILL.md +277 -0
  448. package/kits/skills/ec-skill/SKILL.md +25 -9
  449. package/kits/skills/ec-skill/scripts/cli.mjs +7 -7
  450. package/kits/skills/ec-skill/scripts/skill.mjs +55 -41
  451. package/kits/skills/ec-skill/scripts/template/SKILL.md.tmpl +9 -0
  452. package/kits/skills/ec-trigger/SKILL.md +3 -3
  453. package/kits/skills/personal-assistant/SKILL.md +22 -22
  454. package/kits/skills/personal-assistant/references/03-data-flow-and-gaps.md +1 -1
  455. package/kits/skills/scrapling-article-fetch/SKILL.md +5 -5
  456. package/kits/skills/thread-ops/SKILL.md +19 -9
  457. package/kits/skills/wechat-article-media-download/SKILL.md +2 -2
  458. package/kits/skills/wechat-article-reader/SKILL.md +2 -2
  459. package/kits/templates/memory-consolidation/notes.md +2 -2
  460. package/kits/templates/memory-consolidation/workflow.md +46 -0
  461. package/kits/templates/system-fragments/channel.md +13 -4
  462. package/kits/templates/system-fragments/commands.md +5 -4
  463. package/kits/templates/system-fragments/personal-assistant.md +2 -2
  464. package/kits/templates/system-fragments/reply.md +15 -9
  465. package/kits/templates/system-fragments/session.md +2 -2
  466. package/kits/templates/system-fragments/thread.md +30 -127
  467. package/kits/templates/system-fragments/venue.md +16 -0
  468. package/package.json +7 -7
  469. package/scripts/agent-template/index.mjs +7 -1
  470. package/scripts/agent-template/inspect.mjs +99 -39
  471. package/scripts/agent-template/overlay.mjs +126 -2
  472. package/scripts/agent-template/shared/common.mjs +49 -5
  473. package/scripts/agent-template/shared/plan.mjs +4 -2
  474. package/scripts/agent-template/shared/service-packs.mjs +104 -0
  475. package/scripts/agent-template/shared/team-schema.json +468 -39
  476. package/scripts/agent-template/shared/template-contract.mjs +93 -51
  477. package/scripts/agent-template/shared/template-package.mjs +225 -44
  478. package/scripts/agent-template/shared/template-runtime.mjs +137 -15
  479. package/scripts/agent-template/shared/template.mjs +31 -8
  480. package/scripts/agent-template/team-pack.mjs +528 -56
  481. package/scripts/agent-template/team-preview.mjs +102 -9
  482. package/scripts/aid-batch/identity-batch.mjs +1 -1
  483. package/dist/agents/baseagent-availability.js +0 -152
  484. package/dist/agents/baseagent.js +0 -750
  485. package/dist/agents/codex/catalog.js +0 -80
  486. package/dist/agents/ecagent-plugin-lazy.js +0 -41
  487. package/dist/agents/tool-time-context.js +0 -55
  488. package/dist/core/legacy-rename.js +0 -41
  489. package/dist/core/plugin-lifecycle.js +0 -137
  490. package/dist/core/rate-window.js +0 -53
  491. package/dist/core/runner-reload-transaction.js +0 -60
  492. package/dist/core/runtime-lock.js +0 -90
  493. package/dist/core/soul.js +0 -66
  494. package/dist/core/system-session/grants.js +0 -40
  495. package/dist/directory/owner-directory-agentmd-sync.js +0 -89
  496. package/dist/directory/owner-directory-request-operation.js +0 -79
  497. package/dist/directory/owner-directory-text.js +0 -60
  498. package/kits/docs/aun/ABILITY_CALLING.md +0 -280
  499. package/kits/docs/evolcore/ability.md +0 -185
  500. package/kits/skills/ability/references/calling.md +0 -56
  501. package/kits/skills/ability/references/contract-checklist.md +0 -37
  502. package/kits/skills/ability/references/recovery.md +0 -27
  503. /package/dist/{core/capability/providers/gemini-capability-provider.js → agents/gemini/capability-provider.js} +0 -0
  504. /package/dist/core/{system-channels.js → channel/system-channels.js} +0 -0
  505. /package/dist/core/{daemon-file-cache.js → daemon/daemon-file-cache.js} +0 -0
  506. /package/dist/core/{event-bus.js → event/event-bus.js} +0 -0
  507. /package/dist/core/{event-catalog.js → event/event-catalog.js} +0 -0
  508. /package/dist/core/{pack-ledger.js → pack/pack-ledger.js} +0 -0
  509. /package/dist/directory/{owner-directory-identity.js → identity.js} +0 -0
  510. /package/dist/directory/{owner-directory-policy.js → policy.js} +0 -0
  511. /package/dist/directory/{owner-directory-remarks.js → remarks.js} +0 -0
  512. /package/dist/directory/{owner-directory-scope.js → scope.js} +0 -0
  513. /package/dist/{contracts → ecweb/contracts}/ecweb-instance.js +0 -0
  514. /package/kits/templates/{bootstrap-welcome.md → bootstrap-intro.md} +0 -0
@@ -0,0 +1,960 @@
1
+ import crypto from 'node:crypto';
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
4
+ import { resolveEffective } from '../config/config-manager.js';
5
+ import { DataRootError } from '../core/command/team-workspace-store.js';
6
+ import { agentConfig, agentDataDir, resolvePaths } from '../paths.js';
7
+ import { resolveProjectDefaultPath } from '../utils/project-path.js';
8
+ import { atomicRemove, atomicWriteJson } from '../utils/atomic-write.js';
9
+ import { authorizeOutput, currentOutputOwner } from './authorization.js';
10
+ import { ownerResolver, OWNERSHIP_AUTHORIZATION_MAX_AGE_MS } from '../core/ownership/owner-resolver.js';
11
+ export const PANEL_CARDS_EVENT = 'team.panel-cards.changed';
12
+ export const PANEL_CARDS_TYPES = ['snapshot', 'list', 'detail', 'changes']
13
+ .map(action => `services.panel-cards.${action}`);
14
+ export const isPanelCardsType = (type) => PANEL_CARDS_TYPES.includes(type);
15
+ const ID = /^[a-z0-9][a-z0-9._-]{0,63}$/;
16
+ const AID = /^[a-z0-9][a-z0-9._-]{1,255}$/;
17
+ const MAX_CARDS = 100;
18
+ const MAX_CARD_BYTES = 32 * 1024;
19
+ const MAX_RESPONSE_BYTES = 256 * 1024;
20
+ const MAX_PAGE = 20;
21
+ const MAX_RESOURCE_BYTES = 32 * 1024 * 1024;
22
+ const MAX_INLINE_HTML_BYTES = 32 * 1024;
23
+ const VERSION = /^[a-f0-9]{24}$/;
24
+ const SPANS = new Set(['1x1', '1x2', '1x3', '2x1', '2x2', '2x3']);
25
+ const NODE_TYPES = new Set(['column', 'section', 'heading', 'text', 'image', 'metric', 'list', 'status', 'progress', 'chart', 'cover', 'shortcutGroup', 'timeline', 'divider', 'avatarGroup', 'html']);
26
+ const TONES = new Set(['neutral', 'accent', 'success', 'warning', 'danger']);
27
+ const ICONS = new Set(['calendar', 'chat', 'check', 'file', 'folder', 'group', 'link', 'meeting', 'task']);
28
+ async function authorizePanelCardWrite(aid, ownerAid) {
29
+ const view = await ownerResolver.refresh(aid, { maxAgeMs: OWNERSHIP_AUTHORIZATION_MAX_AGE_MS, source: 'panel-cards.publish', allowTransient: false });
30
+ if (view.authorizationStatus !== 'verified' || view.ownerAid !== ownerAid || view.refreshFailure?.fallbackUsed || (view.validUntil ?? 0) <= Date.now()) {
31
+ fail('PANEL_CARDS_FORBIDDEN', 'Current verified Owner authorization is required to publish panel cards');
32
+ }
33
+ return view.revision;
34
+ }
35
+ let panelCardsNotificationsAvailable = () => false;
36
+ export function setPanelCardsNotificationsAvailable(available = () => false) {
37
+ panelCardsNotificationsAvailable = available;
38
+ }
39
+ const panelServices = new Map();
40
+ let panelChangePublisher = async () => false;
41
+ export function setPanelCardChangePublisher(publish) {
42
+ panelChangePublisher = publish ?? (async () => false);
43
+ }
44
+ const locks = new Map();
45
+ async function withLock(key, action) {
46
+ const previous = locks.get(key) ?? Promise.resolve();
47
+ let release;
48
+ const current = new Promise(resolve => { release = resolve; });
49
+ locks.set(key, current);
50
+ await previous;
51
+ try {
52
+ return await action();
53
+ }
54
+ finally {
55
+ release();
56
+ if (locks.get(key) === current)
57
+ locks.delete(key);
58
+ }
59
+ }
60
+ function fail(code, message) { throw new DataRootError(code, message); }
61
+ function digest(value, length = 24) { return crypto.createHash('sha256').update(JSON.stringify(value) ?? 'undefined').digest('hex').slice(0, length); }
62
+ function token() { return crypto.randomBytes(18).toString('base64url'); }
63
+ function isInside(root, target) {
64
+ const relative = path.relative(root, target);
65
+ return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
66
+ }
67
+ function safeRelative(value) {
68
+ return typeof value === 'string' && value.length > 0 && value.length <= 2048 && !value.includes('\\') && !value.includes(':')
69
+ && !/[\x00-\x1f\x7f]/.test(value) && value.split('/').every(part => !!part && part !== '.' && part !== '..' && !part.startsWith('.'));
70
+ }
71
+ function object(value, field) {
72
+ if (!value || typeof value !== 'object' || Array.isArray(value))
73
+ fail('INVALID_CARD', `${field} must be an object`);
74
+ return value;
75
+ }
76
+ function onlyKeys(value, allowed, field) {
77
+ const unsupported = Object.keys(value).find(key => !allowed.includes(key));
78
+ if (unsupported)
79
+ fail('INVALID_CARD', `${field}.${unsupported} is not supported`);
80
+ }
81
+ function validateNode(value, depth = 0, counter = { value: 0 }) {
82
+ if (depth > 6 || ++counter.value > 120)
83
+ fail('CARD_LIMIT', 'body exceeds the node or nesting limit');
84
+ const node = object(value, 'body');
85
+ const type = node.type;
86
+ if (typeof type !== 'string' || !NODE_TYPES.has(type))
87
+ fail('INVALID_CARD', 'body.type is unsupported');
88
+ const fields = ['type', 'tone', 'text', 'label', 'value', 'unit', 'resourceId', 'icon', 'progress', 'items', 'points', 'children', 'alt'];
89
+ onlyKeys(node, fields, 'body');
90
+ if (node.tone !== undefined && !TONES.has(String(node.tone)))
91
+ fail('INVALID_CARD', 'body.tone is unsupported');
92
+ for (const key of ['text', 'label', 'value', 'unit', 'resourceId', 'icon', 'alt']) {
93
+ const valueAtKey = node[key];
94
+ if (valueAtKey !== undefined && (typeof valueAtKey !== 'string' || valueAtKey.length > (key === 'text' ? 2000 : 240)))
95
+ fail('CARD_LIMIT', `body.${key} is invalid or too long`);
96
+ }
97
+ if (node.icon !== undefined && !ICONS.has(String(node.icon)))
98
+ fail('INVALID_CARD', 'body.icon is unsupported');
99
+ if (node.items !== undefined && (!Array.isArray(node.items) || node.items.length > 16 || node.items.some(item => typeof item !== 'string' || item.length < 1 || item.length > 240)))
100
+ fail('CARD_LIMIT', 'body.items exceeds the list limit');
101
+ if (node.points !== undefined && (!Array.isArray(node.points) || node.points.length < 2 || node.points.length > 12 || node.points.some(point => typeof point !== 'number' || !Number.isFinite(point) || point < -1000 || point > 1000)))
102
+ fail('CARD_LIMIT', 'body.points exceeds the chart limit');
103
+ if (node.progress !== undefined && (typeof node.progress !== 'number' || !Number.isFinite(node.progress) || node.progress < 0 || node.progress > 1))
104
+ fail('INVALID_CARD', 'body.progress must be between zero and one');
105
+ if (node.children !== undefined && (!Array.isArray(node.children) || node.children.length > 64))
106
+ fail('CARD_LIMIT', 'body.children is invalid');
107
+ if (['column', 'section'].includes(type) && (!Array.isArray(node.children) || node.children.length === 0))
108
+ fail('INVALID_CARD', `${type} requires children`);
109
+ if (['heading', 'text', 'status'].includes(type) && (typeof node.text !== 'string' || node.text.length === 0))
110
+ fail('INVALID_CARD', `${type} requires text`);
111
+ if (['image', 'cover', 'html'].includes(type) && typeof node.resourceId !== 'string')
112
+ fail('INVALID_CARD', `${type} requires resourceId`);
113
+ if (type === 'html' && depth !== 0)
114
+ fail('INVALID_CARD', 'html must be the complete card body');
115
+ if (type === 'metric' && (typeof node.label !== 'string' || typeof node.value !== 'string'))
116
+ fail('INVALID_CARD', 'metric requires label and value');
117
+ if (['list', 'shortcutGroup', 'timeline', 'avatarGroup'].includes(type) && (!Array.isArray(node.items) || node.items.length === 0))
118
+ fail('INVALID_CARD', `${type} requires items`);
119
+ if (type === 'progress' && typeof node.progress !== 'number')
120
+ fail('INVALID_CARD', 'progress requires a value');
121
+ if (type === 'chart' && !Array.isArray(node.points))
122
+ fail('INVALID_CARD', 'chart requires points');
123
+ return { ...node, ...(Array.isArray(node.children) ? { children: node.children.map(child => validateNode(child, depth + 1, counter)) } : {}) };
124
+ }
125
+ export function validatePanelCardDraft(value) {
126
+ const draft = object(value, 'card');
127
+ onlyKeys(draft, ['schemaVersion', 'catalog', 'id', 'title', 'summary', 'span', 'theme', 'resources', 'body', 'actions'], 'card');
128
+ if (draft.schemaVersion !== 1 || draft.catalog !== 'evol.cards.v1' || typeof draft.id !== 'string' || !ID.test(draft.id))
129
+ fail('INVALID_CARD', 'schemaVersion, catalog or id is invalid');
130
+ if (typeof draft.title !== 'string' || !draft.title.trim() || draft.title.length > 160 || /[\x00-\x1f\x7f]/.test(draft.title))
131
+ fail('INVALID_CARD', 'title must contain 1 to 160 characters');
132
+ if (draft.summary !== undefined && (typeof draft.summary !== 'string' || draft.summary.length > 640 || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(draft.summary)))
133
+ fail('CARD_LIMIT', 'summary is limited to 640 characters');
134
+ const span = object(draft.span, 'span');
135
+ onlyKeys(span, ['w', 'h'], 'span');
136
+ if (!Number.isInteger(span.w) || !Number.isInteger(span.h) || !SPANS.has(`${span.w}x${span.h}`))
137
+ fail('INVALID_CARD', 'span is not in the supported catalog');
138
+ if (typeof draft.theme !== 'string' || !TONES.has(draft.theme))
139
+ fail('INVALID_CARD', 'theme is not in the supported catalog');
140
+ const resources = Object.create(null);
141
+ if (draft.resources !== undefined) {
142
+ const rawResources = object(draft.resources, 'resources');
143
+ if (Object.keys(rawResources).length > 12)
144
+ fail('CARD_LIMIT', 'at most 12 resources are allowed');
145
+ for (const [resourceId, raw] of Object.entries(rawResources)) {
146
+ if (!ID.test(resourceId))
147
+ fail('INVALID_CARD', `resources.${resourceId} has an invalid id`);
148
+ const resource = object(raw, `resources.${resourceId}`);
149
+ onlyKeys(resource, ['path', 'kind'], `resources.${resourceId}`);
150
+ if (!safeRelative(resource.path) || !['image', 'file'].includes(String(resource.kind)))
151
+ fail('INVALID_CARD', `resources.${resourceId} path or kind is invalid`);
152
+ resources[resourceId] = { path: resource.path, kind: resource.kind };
153
+ }
154
+ }
155
+ const body = validateNode(draft.body);
156
+ const usedResources = new Set();
157
+ const collect = (node) => { if (typeof node.resourceId === 'string')
158
+ usedResources.add(node.resourceId); for (const child of node.children ?? [])
159
+ collect(child); };
160
+ collect(body);
161
+ for (const resourceId of usedResources)
162
+ if (!resources[resourceId])
163
+ fail('INVALID_CARD', `body references unknown resource ${resourceId}`);
164
+ if (body.type === 'html') {
165
+ const surface = resources[String(body.resourceId)];
166
+ if (surface?.kind !== 'file' || !/\.html?$/i.test(surface.path))
167
+ fail('INVALID_CARD', 'html requires an HTML file resource');
168
+ }
169
+ const actions = [];
170
+ if (draft.actions !== undefined) {
171
+ if (!Array.isArray(draft.actions) || draft.actions.length > 8)
172
+ fail('CARD_LIMIT', 'at most 8 actions are allowed');
173
+ const seen = new Set();
174
+ for (const raw of draft.actions) {
175
+ const action = object(raw, 'actions');
176
+ onlyKeys(action, ['id', 'type', 'label', 'resource', 'taskId'], 'actions');
177
+ if (typeof action.id !== 'string' || !ID.test(action.id) || seen.has(action.id) || typeof action.label !== 'string' || !action.label.trim() || action.label.length > 80)
178
+ fail('INVALID_CARD', 'action id or label is invalid');
179
+ seen.add(action.id);
180
+ if (!['openFile', 'openChat', 'openDirectory', 'openTask'].includes(String(action.type)))
181
+ fail('INVALID_CARD', 'action type is unsupported');
182
+ if (action.type === 'openFile' && (typeof action.resource !== 'string' || !resources[action.resource]))
183
+ fail('INVALID_CARD', 'openFile must reference a declared resource');
184
+ if (action.type === 'openTask' && (typeof action.taskId !== 'string' || !/^[A-Za-z0-9._:-]{1,128}$/.test(action.taskId)))
185
+ fail('INVALID_CARD', 'openTask requires a bounded taskId');
186
+ if (action.type === 'openChat' && (action.resource !== undefined || action.taskId !== undefined))
187
+ fail('INVALID_CARD', 'openChat does not accept targets');
188
+ if (action.type === 'openDirectory' && (action.resource !== undefined || action.taskId !== undefined))
189
+ fail('INVALID_CARD', 'openDirectory does not accept targets');
190
+ actions.push(action);
191
+ }
192
+ }
193
+ const normalized = {
194
+ schemaVersion: 1, catalog: 'evol.cards.v1', id: draft.id,
195
+ title: draft.title.trim(), ...(typeof draft.summary === 'string' ? { summary: draft.summary.trim() } : {}),
196
+ span: { w: span.w, h: span.h }, theme: draft.theme,
197
+ ...(Object.keys(resources).length ? { resources } : {}), body, ...(actions.length ? { actions } : {}),
198
+ };
199
+ if (Buffer.byteLength(JSON.stringify(normalized)) > MAX_CARD_BYTES)
200
+ fail('CARD_LIMIT', `card descriptor exceeds ${MAX_CARD_BYTES} bytes`);
201
+ return normalized;
202
+ }
203
+ function stateFile(aid, custom) {
204
+ if (!AID.test(aid))
205
+ fail('INVALID_ARGUMENT', 'source AID is invalid');
206
+ return custom?.(aid) ?? path.join(agentDataDir(aid), 'panel-cards', 'state.json');
207
+ }
208
+ function emptyState() { return { schemaVersion: 1, sequence: 0, scopes: {}, cards: {} }; }
209
+ function readState(file) {
210
+ try {
211
+ const value = JSON.parse(fs.readFileSync(file, 'utf8'));
212
+ if (value.schemaVersion !== 1 || !Number.isSafeInteger(value.sequence) || !value.scopes || !value.cards)
213
+ throw new Error('invalid state');
214
+ return value;
215
+ }
216
+ catch (error) {
217
+ if (error.code === 'ENOENT')
218
+ return emptyState();
219
+ fail('PANEL_CARDS_STATE_INVALID', 'Panel card lifecycle metadata is unavailable');
220
+ }
221
+ }
222
+ function saveState(file, state) {
223
+ fs.mkdirSync(path.dirname(file), { recursive: true });
224
+ atomicWriteJson(file, state);
225
+ }
226
+ function assertDirectory(parent, name, create) {
227
+ const target = path.join(parent, name);
228
+ if (!fs.existsSync(target) && create)
229
+ fs.mkdirSync(target);
230
+ const stat = fs.lstatSync(target, { throwIfNoEntry: false });
231
+ if (!stat)
232
+ return target;
233
+ if (stat.isSymbolicLink() || !stat.isDirectory())
234
+ fail('PROJECT_UNAVAILABLE', 'Project output path must be a real directory');
235
+ const real = fs.realpathSync(target);
236
+ if (!isInside(fs.realpathSync(parent), real))
237
+ fail('PROJECT_UNAVAILABLE', 'Project output path escaped its parent');
238
+ return real;
239
+ }
240
+ function projectRootFor(aid) {
241
+ const effective = resolveEffective({ self: aid }, { cache: false });
242
+ const configured = resolveProjectDefaultPath(effective.projects?.defaultPath);
243
+ if (!configured)
244
+ fail('PROJECT_UNAVAILABLE', 'Agent projects.defaultPath must be explicitly configured');
245
+ let root;
246
+ try {
247
+ root = fs.realpathSync.native(configured);
248
+ }
249
+ catch {
250
+ fail('PROJECT_UNAVAILABLE', 'Agent projects.defaultPath is unavailable');
251
+ }
252
+ if (!fs.statSync(root).isDirectory())
253
+ fail('PROJECT_UNAVAILABLE', 'Agent projects.defaultPath is not a directory');
254
+ return root;
255
+ }
256
+ function resolveProjectRoot(aid, options) {
257
+ try {
258
+ const configured = options.projectRoot?.(aid) ?? projectRootFor(aid);
259
+ const root = fs.realpathSync.native(configured);
260
+ if (!fs.statSync(root).isDirectory())
261
+ fail('PROJECT_UNAVAILABLE', 'Agent projects.defaultPath is not a directory');
262
+ return root;
263
+ }
264
+ catch (error) {
265
+ if (error instanceof DataRootError)
266
+ throw error;
267
+ fail('PROJECT_UNAVAILABLE', 'Agent projects.defaultPath is unavailable');
268
+ }
269
+ }
270
+ function currentProjectRoot(aid, options, state, file) {
271
+ try {
272
+ return resolveProjectRoot(aid, options);
273
+ }
274
+ catch (error) {
275
+ if (state.activeBinding) {
276
+ delete state.activeBinding;
277
+ saveState(file, state);
278
+ }
279
+ throw error;
280
+ }
281
+ }
282
+ function ensureContext(aid, root, state, file, create) {
283
+ const stats = fs.statSync(root);
284
+ const identity = crypto.createHash('sha256').update(`${root}\0${stats.dev}\0${stats.ino}`).digest('hex');
285
+ let scope = state.scopes[identity];
286
+ if (!scope) {
287
+ scope = { identity, scopeId: token() };
288
+ state.scopes[identity] = scope;
289
+ }
290
+ // The scope is stable on return to a project. A new activation invalidates
291
+ // any operation or file root issued during its previous activation.
292
+ if (state.activeBinding?.scopeId !== scope.scopeId) {
293
+ state.activeBinding = { scopeId: scope.scopeId, revision: token() };
294
+ saveState(file, state);
295
+ }
296
+ const outputRoot = assertDirectory(root, '.output', create);
297
+ const sourceRoot = fs.existsSync(outputRoot) ? assertDirectory(outputRoot, aid, create) : path.join(outputRoot, aid);
298
+ const cardsRoot = fs.existsSync(outputRoot) ? assertDirectory(outputRoot, '.cards', create) : path.join(outputRoot, '.cards');
299
+ const descriptorRoot = fs.existsSync(cardsRoot) ? assertDirectory(cardsRoot, aid, create) : path.join(cardsRoot, aid);
300
+ return { projectRoot: root, outputRoot, sourceRoot, descriptorRoot, scopeId: scope.scopeId, bindingRevision: state.activeBinding.revision, available: fs.existsSync(sourceRoot) && fs.existsSync(descriptorRoot) };
301
+ }
302
+ export function panelResourceVersion(stat) {
303
+ return digest([stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs]);
304
+ }
305
+ function resolveResource(sourceRoot, relative, checkExists = true) {
306
+ if (!safeRelative(relative))
307
+ fail('INVALID_CARD', 'resource path must be relative to this Agent .output partition');
308
+ let cursor = sourceRoot;
309
+ const base = fs.realpathSync(sourceRoot);
310
+ const parts = relative.split('/');
311
+ for (const part of parts) {
312
+ cursor = path.join(cursor, part);
313
+ const stat = fs.lstatSync(cursor, { throwIfNoEntry: false });
314
+ if (!stat && !checkExists)
315
+ return { absolute: cursor, version: '', size: 0 };
316
+ if (!stat || stat.isSymbolicLink())
317
+ fail('CARD_RESOURCE_INVALID', `resource is missing or linked: ${relative}`);
318
+ const real = fs.realpathSync(cursor);
319
+ if (!isInside(base, real))
320
+ fail('CARD_RESOURCE_INVALID', 'resource escaped its Agent partition');
321
+ if (part !== parts.at(-1) && !stat.isDirectory())
322
+ fail('CARD_RESOURCE_INVALID', 'resource parent is not a directory');
323
+ }
324
+ const stat = fs.statSync(cursor);
325
+ if (!stat.isFile() || stat.size > MAX_RESOURCE_BYTES)
326
+ fail('CARD_RESOURCE_INVALID', 'resource must be a regular file below the size limit');
327
+ return { absolute: cursor, version: panelResourceVersion(stat), size: stat.size };
328
+ }
329
+ export function inspectPanelCardProject(aid, options = {}) {
330
+ const file = stateFile(aid, options.stateRoot);
331
+ const state = readState(file);
332
+ const root = currentProjectRoot(aid, options, state, file);
333
+ const context = ensureContext(aid, root, state, file, false);
334
+ return {
335
+ protocol: 'evol.panel-cards', protocolVersion: 1, catalog: panelCardsCatalog,
336
+ projectState: context.available ? 'ready' : 'empty', scopeId: context.scopeId,
337
+ bindingRevision: context.bindingRevision,
338
+ };
339
+ }
340
+ export function validatePanelCardResources(aid, value, options = {}) {
341
+ const draft = validatePanelCardDraft(value);
342
+ const file = stateFile(aid, options.stateRoot);
343
+ const state = readState(file);
344
+ const root = currentProjectRoot(aid, options, state, file);
345
+ const context = ensureContext(aid, root, state, file, false);
346
+ if (Object.keys(draft.resources ?? {}).length > 0 && !fs.existsSync(context.sourceRoot)) {
347
+ fail('PROJECT_UNAVAILABLE', 'The Agent .output partition is required to validate card resources');
348
+ }
349
+ let resourceBytes = 0;
350
+ for (const resource of Object.values(draft.resources ?? {})) {
351
+ const resolved = resolveResource(context.sourceRoot, resource.path);
352
+ if (draft.body.type === 'html' && resource === draft.resources?.[String(draft.body.resourceId)] && resolved.size > 256 * 1024)
353
+ fail('CARD_LIMIT', 'HTML surfaces are limited to 256 KiB');
354
+ resourceBytes += resolved.size;
355
+ }
356
+ if (resourceBytes > 64 * 1024 * 1024)
357
+ fail('CARD_LIMIT', 'total resource size exceeds 64 MiB');
358
+ return { ok: true, id: draft.id, scopeId: context.scopeId, bindingRevision: context.bindingRevision, capabilityVersion: 'evol.panel-cards/1', resourceBytes };
359
+ }
360
+ function assertCurrentBinding(aid, options, context, file) {
361
+ const state = readState(file);
362
+ const root = currentProjectRoot(aid, options, state, file);
363
+ const current = ensureContext(aid, root, state, file, false);
364
+ if (current.bindingRevision !== context.bindingRevision ||
365
+ (options.expectedBindingRevision !== undefined && options.expectedBindingRevision !== current.bindingRevision)) {
366
+ fail('PROJECT_CHANGED', 'Agent project binding changed during the card operation');
367
+ }
368
+ }
369
+ function descriptorPath(context, id) { return path.join(context.descriptorRoot, `${id}.json`); }
370
+ function scopeCards(state, scopeId) {
371
+ return state.cards[scopeId] = Object.assign(Object.create(null), state.cards[scopeId]);
372
+ }
373
+ function readDescriptor(context, id, record, aid) {
374
+ const file = descriptorPath(context, id);
375
+ try {
376
+ const stat = fs.lstatSync(file);
377
+ if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_CARD_BYTES + 1024)
378
+ return undefined;
379
+ const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
380
+ const { sourceAid, scopeId, incarnation, contentVersion, sequence, updatedAt, ...draftRaw } = raw;
381
+ const draft = validatePanelCardDraft(draftRaw);
382
+ if (draft.id !== id || sourceAid !== aid || scopeId !== context.scopeId || incarnation !== record.incarnation || contentVersion !== record.contentVersion || sequence !== record.sequence || record.deleted || record.sha256 !== digest(raw, record.sha256?.length))
383
+ return undefined;
384
+ const resources = Object.create(null);
385
+ for (const [key, value] of Object.entries(draft.resources ?? {})) {
386
+ const item = value;
387
+ const resolved = resolveResource(context.sourceRoot, item.path);
388
+ resources[key] = { ...item, version: resolved.version, size: resolved.size };
389
+ }
390
+ return { protocol: 'evol.panel-cards', protocolVersion: 1, ...draft, sourceAid: aid, scopeId: context.scopeId, incarnation, contentVersion, sequence, updatedAt, resources };
391
+ }
392
+ catch {
393
+ return undefined;
394
+ }
395
+ }
396
+ function readInlineHtml(context, card, version) {
397
+ const draft = card;
398
+ const resource = draft.resources?.[String(draft.body?.resourceId)];
399
+ if (draft.body?.type !== 'html' || resource?.kind !== 'file') {
400
+ fail('NOT_FOUND', 'HTML surface is unavailable');
401
+ }
402
+ const resolved = resolveResource(context.sourceRoot, resource.path);
403
+ if (resolved.version !== version)
404
+ fail('RESOURCE_EXPIRED', 'HTML surface changed');
405
+ if (resolved.size > MAX_INLINE_HTML_BYTES)
406
+ fail('CARD_LIMIT', 'HTML surface requires file transfer');
407
+ const fd = fs.openSync(resolved.absolute, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
408
+ try {
409
+ if (panelResourceVersion(fs.fstatSync(fd)) !== version) {
410
+ fail('RESOURCE_EXPIRED', 'HTML surface changed');
411
+ }
412
+ const bytes = Buffer.alloc(resolved.size);
413
+ if (fs.readSync(fd, bytes, 0, bytes.length, 0) !== bytes.length ||
414
+ panelResourceVersion(fs.fstatSync(fd)) !== version ||
415
+ resolveResource(context.sourceRoot, resource.path).version !== version) {
416
+ fail('RESOURCE_EXPIRED', 'HTML surface changed');
417
+ }
418
+ return bytes.toString('base64');
419
+ }
420
+ finally {
421
+ fs.closeSync(fd);
422
+ }
423
+ }
424
+ function committedRecord(card) {
425
+ return {
426
+ incarnation: String(card.incarnation), contentVersion: String(card.contentVersion),
427
+ sequence: Number(card.sequence), updatedAt: Number(card.updatedAt),
428
+ title: String(card.title), span: card.span, sha256: digest(card, 64),
429
+ };
430
+ }
431
+ function unavailableCard(context, aid, id, record) {
432
+ return {
433
+ protocol: 'evol.panel-cards', protocolVersion: 1, catalog: 'evol.cards.v1',
434
+ schemaVersion: 1, sourceAid: aid, scopeId: context.scopeId, id,
435
+ incarnation: record.incarnation, contentVersion: record.contentVersion,
436
+ sequence: record.sequence, updatedAt: record.updatedAt ?? 0,
437
+ title: record.title ?? id, span: record.span ?? { w: 1, h: 1 },
438
+ theme: 'neutral', availability: 'unavailable',
439
+ };
440
+ }
441
+ function recover(file, state, context) {
442
+ const pending = state.pendingByScope?.[context.scopeId] ??
443
+ (state.pending?.scopeId === context.scopeId ? state.pending : undefined);
444
+ if (!pending)
445
+ return;
446
+ const cards = scopeCards(state, pending.scopeId);
447
+ const target = descriptorPath(context, pending.id);
448
+ if (pending.operation === 'publish' && pending.card) {
449
+ atomicWriteJson(target, pending.card);
450
+ const card = pending.card;
451
+ cards[pending.id] = committedRecord(card);
452
+ }
453
+ else {
454
+ atomicRemove(target);
455
+ const previous = cards[pending.id];
456
+ if (previous)
457
+ cards[pending.id] = { ...previous, deleted: true, sequence: pending.sequence ?? state.sequence };
458
+ }
459
+ if (state.pending?.scopeId === context.scopeId)
460
+ delete state.pending;
461
+ delete state.pendingByScope?.[context.scopeId];
462
+ saveState(file, state);
463
+ }
464
+ export async function publishPanelCard(aid, value, options = {}) {
465
+ const draft = validatePanelCardDraft(value);
466
+ const file = stateFile(aid, options.stateRoot);
467
+ const authorize = async () => { if (options.ownerAid)
468
+ await (options.authorizeWrite ?? authorizePanelCardWrite)(aid, options.ownerAid); };
469
+ return withLock(file, async () => {
470
+ await authorize();
471
+ const state = readState(file);
472
+ const canonicalRoot = currentProjectRoot(aid, options, state, file);
473
+ const context = ensureContext(aid, canonicalRoot, state, file, true);
474
+ if (options.expectedBindingRevision !== undefined && options.expectedBindingRevision !== context.bindingRevision) {
475
+ fail('PROJECT_CHANGED', 'Agent project binding changed before the card operation');
476
+ }
477
+ recover(file, state, context);
478
+ let totalResourceBytes = 0;
479
+ for (const [id, resource] of Object.entries(draft.resources ?? {})) {
480
+ const resolved = resolveResource(context.sourceRoot, resource.path);
481
+ if (draft.body.type === 'html' && id === draft.body.resourceId && resolved.size > 256 * 1024)
482
+ fail('CARD_LIMIT', 'HTML surfaces are limited to 256 KiB');
483
+ totalResourceBytes += resolved.size;
484
+ }
485
+ if (totalResourceBytes > 64 * 1024 * 1024)
486
+ fail('CARD_LIMIT', 'total resource size exceeds 64 MiB');
487
+ const cards = scopeCards(state, context.scopeId);
488
+ const activeCount = Object.values(cards).filter(record => !record.deleted).length;
489
+ if ((!cards[draft.id] || cards[draft.id]?.deleted) && activeCount >= MAX_CARDS)
490
+ fail('CARD_LIMIT', `at most ${MAX_CARDS} cards are allowed per project scope`);
491
+ const previous = cards[draft.id];
492
+ const contentVersion = digest(draft);
493
+ const currentVersion = previous && !previous.deleted ? previous.contentVersion : undefined;
494
+ if (currentVersion !== contentVersion && (options.expectedContentVersion !== undefined || currentVersion && options.requireExpectedVersion)
495
+ && options.expectedContentVersion !== (currentVersion ?? 'new')) {
496
+ fail('VERSION_CONFLICT', 'Card contentVersion does not match the current published version');
497
+ }
498
+ const incarnation = previous && !previous.deleted ? previous.incarnation : token();
499
+ if (previous && !previous.deleted && previous.contentVersion === contentVersion) {
500
+ const existing = readDescriptor(context, draft.id, previous, aid);
501
+ if (existing)
502
+ return { ok: true, committed: true, changed: false, card: existing, notified: false };
503
+ }
504
+ const sequence = ++state.sequence;
505
+ const published = { ...draft, sourceAid: aid, scopeId: context.scopeId, incarnation, contentVersion, sequence, updatedAt: Date.now() };
506
+ await authorize();
507
+ assertCurrentBinding(aid, options, context, file);
508
+ (state.pendingByScope ??= {})[context.scopeId] = { operation: 'publish', scopeId: context.scopeId, sequence, id: draft.id, card: published };
509
+ saveState(file, state);
510
+ atomicWriteJson(descriptorPath(context, draft.id), published);
511
+ cards[draft.id] = committedRecord(published);
512
+ delete state.pendingByScope?.[context.scopeId];
513
+ saveState(file, state);
514
+ const card = readDescriptor(context, draft.id, cards[draft.id], aid);
515
+ return { ok: true, committed: true, changed: true, card: card ?? unavailableCard(context, aid, draft.id, cards[draft.id]), notified: false };
516
+ });
517
+ }
518
+ export async function removePanelCard(aid, id, options = {}) {
519
+ if (!ID.test(id))
520
+ fail('INVALID_ARGUMENT', 'card id is invalid');
521
+ const file = stateFile(aid, options.stateRoot);
522
+ const authorize = async () => { if (options.ownerAid)
523
+ await (options.authorizeWrite ?? authorizePanelCardWrite)(aid, options.ownerAid); };
524
+ return withLock(file, async () => {
525
+ await authorize();
526
+ const state = readState(file);
527
+ const context = ensureContext(aid, currentProjectRoot(aid, options, state, file), state, file, true);
528
+ if (options.expectedBindingRevision !== undefined && options.expectedBindingRevision !== context.bindingRevision) {
529
+ fail('PROJECT_CHANGED', 'Agent project binding changed before the card operation');
530
+ }
531
+ recover(file, state, context);
532
+ const cards = scopeCards(state, context.scopeId);
533
+ const record = cards[id];
534
+ if (record && !record.deleted && (options.expectedContentVersion !== undefined || options.requireExpectedVersion) && options.expectedContentVersion !== record.contentVersion) {
535
+ fail('VERSION_CONFLICT', 'Card contentVersion does not match the current published version');
536
+ }
537
+ if (!record || record.deleted)
538
+ return { ok: true, id, removed: false, scopeId: context.scopeId, sequence: state.sequence };
539
+ state.sequence++;
540
+ (state.pendingByScope ??= {})[context.scopeId] = { operation: 'remove', scopeId: context.scopeId, sequence: state.sequence, id };
541
+ await authorize();
542
+ assertCurrentBinding(aid, options, context, file);
543
+ saveState(file, state);
544
+ atomicRemove(descriptorPath(context, id));
545
+ cards[id] = { ...record, deleted: true, sequence: state.sequence };
546
+ delete state.pendingByScope?.[context.scopeId];
547
+ saveState(file, state);
548
+ return { ok: true, committed: true, id, removed: true, scopeId: context.scopeId, sequence: state.sequence };
549
+ });
550
+ }
551
+ export class PanelCardsService {
552
+ aid;
553
+ options;
554
+ closed = false;
555
+ watchers = [];
556
+ configWatchers = [];
557
+ watchSignature;
558
+ refreshTimer;
559
+ currentCursor;
560
+ lastNotifiedCursor;
561
+ currentScope;
562
+ scheduleWatchRefresh = () => {
563
+ if (this.closed || this.refreshTimer)
564
+ return;
565
+ this.refreshTimer = setTimeout(() => {
566
+ this.refreshTimer = undefined;
567
+ const cursor = this.currentCursor;
568
+ void this.notifyChange().catch(async (error) => {
569
+ if (this.closed || !(error instanceof DataRootError) || error.code !== 'PROJECT_UNAVAILABLE')
570
+ return;
571
+ const scopeId = this.currentScope;
572
+ this.currentCursor = undefined;
573
+ if (!cursor || !scopeId)
574
+ return;
575
+ try {
576
+ await panelChangePublisher(this.aid, { sourceAid: this.aid, scopeId, revision: 'unavailable' });
577
+ }
578
+ catch { /* A reconnect or a new read will reconcile the source. */ }
579
+ });
580
+ }, 200);
581
+ this.refreshTimer.unref();
582
+ };
583
+ watchConfig() {
584
+ if (this.options.projectRoot || this.closed || this.configWatchers.length > 0)
585
+ return;
586
+ for (const file of new Set([agentConfig(this.aid), resolvePaths().defaultsConfig])) {
587
+ try {
588
+ const watcher = fs.watch(path.dirname(file), { persistent: false }, (_event, name) => {
589
+ if (!name || name === path.basename(file))
590
+ this.scheduleWatchRefresh();
591
+ });
592
+ watcher.on('error', () => {
593
+ watcher.close();
594
+ this.configWatchers = this.configWatchers.filter(item => item !== watcher);
595
+ this.scheduleWatchRefresh();
596
+ });
597
+ this.configWatchers.push(watcher);
598
+ }
599
+ catch { /* A subsequent authorized query will retry the watcher. */ }
600
+ }
601
+ }
602
+ watch(context) {
603
+ if (this.options.projectRoot || this.closed)
604
+ return;
605
+ const roots = [[path.dirname(context.projectRoot), false], [context.projectRoot, false], [context.outputRoot, false],
606
+ [path.dirname(context.descriptorRoot), false], [context.sourceRoot, true], [context.descriptorRoot, false]];
607
+ const signature = JSON.stringify(roots.map(([directory]) => {
608
+ const stat = fs.statSync(directory, { throwIfNoEntry: false });
609
+ return [directory, stat?.dev, stat?.ino];
610
+ }));
611
+ if (signature === this.watchSignature)
612
+ return;
613
+ this.stopWatching();
614
+ this.watchSignature = signature;
615
+ for (const [directory, recursive] of new Map(roots)) {
616
+ if (!fs.existsSync(directory))
617
+ continue;
618
+ try {
619
+ const watcher = fs.watch(directory, { persistent: false, recursive }, (_event, filename) => {
620
+ if (directory !== context.projectRoot && directory === path.dirname(context.projectRoot)
621
+ && filename && filename !== path.basename(context.projectRoot))
622
+ return;
623
+ if (directory === context.projectRoot && filename && filename !== '.output')
624
+ return;
625
+ if (directory === context.outputRoot && filename && filename !== this.aid && filename !== '.cards')
626
+ return;
627
+ if (directory === path.dirname(context.descriptorRoot) && filename && filename !== this.aid)
628
+ return;
629
+ this.scheduleWatchRefresh();
630
+ });
631
+ watcher.on('error', () => { this.watchSignature = undefined; this.scheduleWatchRefresh(); });
632
+ this.watchers.push(watcher);
633
+ }
634
+ catch { /* Reconciliation still occurs on every authorized query. */ }
635
+ }
636
+ }
637
+ stopWatching() {
638
+ this.watchSignature = undefined;
639
+ for (const watcher of this.watchers)
640
+ watcher.close();
641
+ this.watchers = [];
642
+ }
643
+ epochs = new Map();
644
+ projections = new Map();
645
+ requests = new Map();
646
+ constructor(aid, options = {}) {
647
+ this.aid = aid;
648
+ this.options = options;
649
+ if (!options.stateRoot && !options.projectRoot)
650
+ panelServices.set(aid, this);
651
+ }
652
+ async notifyChange(force = false) {
653
+ const projection = await this.query('projection', {});
654
+ const { sourceAid, scopeId, revision, cursor } = projection;
655
+ let notified = false;
656
+ if (force || this.lastNotifiedCursor !== cursor) {
657
+ try {
658
+ notified = await panelChangePublisher(this.aid, { sourceAid, scopeId, revision, cursor });
659
+ if (notified && this.currentCursor === cursor)
660
+ this.lastNotifiedCursor = String(cursor);
661
+ }
662
+ catch { /* The committed projection remains queryable when the Bus is unavailable. */ }
663
+ }
664
+ return { revision: String(revision), cursor: String(cursor), notified };
665
+ }
666
+ async authorize(message) {
667
+ if (this.closed)
668
+ fail('PANEL_CARDS_UNAVAILABLE', 'Panel cards service is closed');
669
+ return (this.options.authorize ?? authorizeOutput)(this.aid, message.fromAid);
670
+ }
671
+ async handle(message) {
672
+ if (!isPanelCardsType(message.type))
673
+ fail('UNKNOWN_TYPE', 'Unknown panel card query');
674
+ const generation = await this.authorize(message);
675
+ const ensure = () => {
676
+ if (this.closed || !(this.options.current ?? currentOutputOwner)(this.aid, message.fromAid, generation))
677
+ fail('PANEL_CARDS_FORBIDDEN', 'Panel card authorization changed');
678
+ };
679
+ ensure();
680
+ const raw = message.payload.data;
681
+ const data = object(raw, 'data');
682
+ const action = message.type.split('.').at(-1);
683
+ const allowed = { snapshot: ['protocolVersion', 'limit', 'knownRevision'], list: ['protocolVersion', 'limit', 'pageCursor'], detail: ['protocolVersion', 'id', 'htmlVersion', 'bindingEpoch'], changes: ['protocolVersion', 'cursor'] };
684
+ if (data.protocolVersion !== 1 || Object.keys(data).some(key => !allowed[action].includes(key)))
685
+ fail('INVALID_ARGUMENT', 'Unsupported panel card query parameters');
686
+ if (action === 'detail' && (typeof data.id !== 'string' || !ID.test(data.id)))
687
+ fail('INVALID_ARGUMENT', 'Invalid card id');
688
+ if (data.htmlVersion !== undefined || data.bindingEpoch !== undefined) {
689
+ if (!message.encrypted)
690
+ fail('ENCRYPTION_REQUIRED', 'HTML preview requires encryption');
691
+ if (typeof data.htmlVersion !== 'string' || !VERSION.test(data.htmlVersion) ||
692
+ typeof data.bindingEpoch !== 'string' || !/^[A-Za-z0-9_-]{20,32}$/.test(data.bindingEpoch)) {
693
+ fail('INVALID_ARGUMENT', 'Invalid HTML preview version');
694
+ }
695
+ }
696
+ if (action === 'changes' && (typeof data.cursor !== 'string' || data.cursor.length > 128))
697
+ fail('INVALID_ARGUMENT', 'A bounded changes cursor is required');
698
+ if (data.limit !== undefined && (!Number.isSafeInteger(data.limit) || Number(data.limit) < 1 || Number(data.limit) > MAX_PAGE))
699
+ fail('INVALID_ARGUMENT', `page limit must be between 1 and ${MAX_PAGE}`);
700
+ const fingerprint = JSON.stringify([message.type, data]);
701
+ const requestKey = `${generation}:${message.fromAid}:${message.requestId}`;
702
+ const previous = this.requests.get(requestKey);
703
+ if (previous && previous.until > Date.now() && previous.fingerprint !== fingerprint) {
704
+ fail('REQUEST_ID_CONFLICT', 'request_id was reused');
705
+ }
706
+ this.requests.set(requestKey, { until: Date.now() + 30_000, fingerprint });
707
+ while (this.requests.size > 32)
708
+ this.requests.delete(this.requests.keys().next().value);
709
+ const result = await this.query(action, data);
710
+ ensure();
711
+ if (Buffer.byteLength(JSON.stringify(result)) > MAX_RESPONSE_BYTES)
712
+ fail('CARD_LIMIT', 'Panel card response exceeds 256 KiB');
713
+ return result;
714
+ }
715
+ async query(action, data) {
716
+ const file = stateFile(this.aid, this.options.stateRoot);
717
+ return withLock(file, () => {
718
+ if (this.closed)
719
+ fail('PANEL_CARDS_UNAVAILABLE', 'Panel cards service is closed');
720
+ this.watchConfig();
721
+ const state = readState(file);
722
+ const root = currentProjectRoot(this.aid, this.options, state, file);
723
+ const context = ensureContext(this.aid, root, state, file, false);
724
+ const prior = this.epochs.get(this.aid);
725
+ const epoch = prior?.root === context.bindingRevision ? prior.epoch : token();
726
+ if (prior?.epoch !== epoch)
727
+ this.projections.clear();
728
+ this.epochs.set(this.aid, { root: context.bindingRevision, epoch });
729
+ recover(file, state, context);
730
+ const records = scopeCards(state, context.scopeId);
731
+ const next = new Map();
732
+ for (const [id, record] of Object.entries(records)) {
733
+ if (record.deleted)
734
+ continue;
735
+ const card = context.available ? readDescriptor(context, id, record, this.aid) : undefined;
736
+ next.set(id, card ?? unavailableCard(context, this.aid, id, record));
737
+ }
738
+ const revision = digest([context.scopeId, ...next.values()]);
739
+ const projectionKey = `${context.scopeId}:${epoch}`;
740
+ let projection = this.projections.get(projectionKey);
741
+ if (!projection) {
742
+ projection = { epoch, sequence: 0, revision: '', cards: new Map(), log: [] };
743
+ this.projections.set(projectionKey, projection);
744
+ }
745
+ if (revision !== projection.revision) {
746
+ const upserts = [...next].filter(([id, card]) => digest(projection.cards.get(id)) !== digest(card)).map(([id]) => id);
747
+ const deletes = [...projection.cards.keys()].filter(id => !next.has(id));
748
+ const sequence = Math.max(state.sequence, projection.sequence + 1);
749
+ projection.sequence = sequence;
750
+ projection.revision = revision;
751
+ projection.cards = next;
752
+ projection.log.push({ sequence, upserts, deletes });
753
+ while (projection.log.length > 64)
754
+ projection.log.shift();
755
+ }
756
+ const cursor = `${epoch}.${projection.sequence}`;
757
+ this.currentCursor = cursor;
758
+ this.lastNotifiedCursor ??= cursor;
759
+ this.currentScope = context.scopeId;
760
+ this.watch(context);
761
+ const notifications = this.options.notifications?.() ?? panelCardsNotificationsAvailable(this.aid);
762
+ const base = { protocol: 'evol.panel-cards', protocolVersion: 1, catalog: 'evol.cards.v1', sourceAid: this.aid, scopeId: context.scopeId, bindingEpoch: epoch, revision, cursor, generatedAt: Date.now(), sourceState: context.available ? 'ready' : 'empty', notifications: notifications ? { busAid: this.aid, event: PANEL_CARDS_EVENT } : null };
763
+ if (action === 'projection')
764
+ return base;
765
+ if (action === 'detail') {
766
+ const card = next.get(data.id);
767
+ if (!card)
768
+ fail('NOT_FOUND', 'Panel card is unavailable');
769
+ if (typeof data.htmlVersion === 'string') {
770
+ if (data.bindingEpoch !== epoch)
771
+ fail('RESOURCE_EXPIRED', 'Panel binding changed');
772
+ return { ...base, items: [card], nextCursor: null, htmlBase64: readInlineHtml(context, card, data.htmlVersion) };
773
+ }
774
+ return { ...base, items: [card], nextCursor: null };
775
+ }
776
+ if (action === 'changes') {
777
+ const match = /^([A-Za-z0-9_-]{20,32})\.(\d+)$/.exec(data.cursor);
778
+ const sequence = match ? Number(match[2]) : -1;
779
+ const rows = projection.log.filter(row => row.sequence > sequence);
780
+ let reset = !match || match[1] !== epoch || sequence > projection.sequence || sequence < (projection.log[0]?.sequence ?? 1) - 1;
781
+ const ids = [...new Set(rows.flatMap(row => row.upserts))];
782
+ const deletes = [...new Set(rows.flatMap(row => row.deletes))].filter(id => !next.has(id));
783
+ const items = ids.flatMap(id => next.has(id) ? [next.get(id)] : []);
784
+ const delta = { ...base, items, deletes, reset: false, nextCursor: null };
785
+ reset ||= items.length > MAX_PAGE || Buffer.byteLength(JSON.stringify(delta)) > MAX_RESPONSE_BYTES;
786
+ return reset ? { ...delta, items: [], deletes: [], reset: true } : delta;
787
+ }
788
+ const limit = Number(data.limit ?? MAX_PAGE);
789
+ let offset = 0;
790
+ if (data.pageCursor !== undefined) {
791
+ try {
792
+ const page = JSON.parse(Buffer.from(String(data.pageCursor), 'base64url').toString());
793
+ if (page.epoch !== epoch || page.revision !== revision || !Number.isSafeInteger(page.offset) || Number(page.offset) < 0 || Number(page.offset) > MAX_CARDS)
794
+ throw new Error();
795
+ offset = Number(page.offset);
796
+ }
797
+ catch {
798
+ fail('INDEX_CHANGED', 'Restart panel card pagination');
799
+ }
800
+ }
801
+ const all = [...next.values()].sort((a, b) => Number(b.updatedAt) - Number(a.updatedAt) || String(a.id).localeCompare(String(b.id)));
802
+ const items = [];
803
+ let budget = MAX_RESPONSE_BYTES - 2048;
804
+ for (const card of all.slice(offset, offset + limit)) {
805
+ budget -= Buffer.byteLength(JSON.stringify(card)) + 1;
806
+ if (budget < 0)
807
+ break;
808
+ items.push(card);
809
+ }
810
+ const result = { ...base, items, nextCursor: offset + items.length < all.length ? Buffer.from(JSON.stringify({ epoch, revision, offset: offset + items.length })).toString('base64url') : null };
811
+ if (action === 'snapshot' && data.knownRevision === revision) {
812
+ result.items = [];
813
+ result.nextCursor = null;
814
+ result.notModified = true;
815
+ }
816
+ return result;
817
+ });
818
+ }
819
+ close() {
820
+ this.closed = true;
821
+ if (this.refreshTimer)
822
+ clearTimeout(this.refreshTimer);
823
+ for (const watcher of this.configWatchers)
824
+ watcher.close();
825
+ this.configWatchers = [];
826
+ this.stopWatching();
827
+ if (panelServices.get(this.aid) === this)
828
+ panelServices.delete(this.aid);
829
+ this.requests.clear();
830
+ this.projections.clear();
831
+ this.epochs.clear();
832
+ }
833
+ }
834
+ export async function executePanelCardsCommand(request, triggerOwner) {
835
+ const { context, isCurrent } = request;
836
+ const [action, ...args] = request.argv;
837
+ const aid = context.selfAid;
838
+ const background = context.executionSource === 'trigger' || !!context.causation?.trigger?.path.length;
839
+ const getActor = async () => background ? triggerOwner(context)
840
+ : context.channel === 'aun' && context.chatType === 'private' && context.peerRole === 'owner'
841
+ && context.peerId ? { owner: context.peerId, revision: 'private' } : undefined;
842
+ const actor = await getActor();
843
+ if (!aid || !actor || !isCurrent())
844
+ fail('NOT_ALLOWED', 'Panel cards require a current Owner session or authorized Trigger');
845
+ const write = action === 'publish' || action === 'remove';
846
+ if (write && (!context.permissionMode || context.permissionMode === 'readonly'))
847
+ fail('NOT_ALLOWED', 'Task cannot change panel cards');
848
+ const actions = {
849
+ catalog: [], schema: [], validate: ['--file'], publish: ['--file', '--expected-version'],
850
+ remove: ['--id', '--expected-version'],
851
+ };
852
+ if (!action || !Object.hasOwn(actions, action))
853
+ fail('INVALID_ARGUMENT', 'Unknown panel card command');
854
+ const flags = new Map();
855
+ for (let i = 0; i < args.length; i += 2) {
856
+ const key = args[i];
857
+ const value = args[i + 1];
858
+ if (!value || !actions[action].includes(key) || flags.has(key))
859
+ fail('INVALID_ARGUMENT', 'Invalid panel card command flags');
860
+ flags.set(key, value);
861
+ }
862
+ if ((action === 'publish' || action === 'validate') && !flags.has('--file'))
863
+ fail('INVALID_ARGUMENT', '--file is required');
864
+ if (action === 'remove' && !flags.has('--id'))
865
+ fail('INVALID_ARGUMENT', '--id is required');
866
+ const expected = flags.get('--expected-version');
867
+ if (expected && expected !== 'new' && !/^[a-f0-9]{24}$/.test(expected))
868
+ fail('INVALID_ARGUMENT', 'Invalid expected contentVersion');
869
+ const ownerRevision = await authorizePanelCardWrite(aid, actor.owner);
870
+ const assertCurrentActor = async (revision) => {
871
+ const latest = await getActor();
872
+ if (revision !== ownerRevision || !isCurrent() || latest?.revision !== actor.revision || latest.owner !== actor.owner) {
873
+ fail('NOT_ALLOWED', 'Panel card authorization changed');
874
+ }
875
+ };
876
+ await assertCurrentActor(ownerRevision);
877
+ const authorize = async () => assertCurrentActor(await authorizePanelCardWrite(aid, actor.owner));
878
+ const capabilityVersion = 'evol.panel-cards/1';
879
+ if (action === 'schema')
880
+ return { ok: true, capabilityVersion, catalog: panelCardsCatalog, draft: panelCardsExample };
881
+ if (action === 'catalog')
882
+ return { ok: true, capabilityVersion, ...inspectPanelCardProject(aid) };
883
+ const draft = action === 'remove' ? undefined : validatePanelCardDraft(request.draft);
884
+ if (action === 'validate')
885
+ return { ...validatePanelCardResources(aid, draft), draft, capabilityVersion };
886
+ const root = resolveProjectRoot(aid, {});
887
+ let taskProject;
888
+ try {
889
+ if (context.projectPath)
890
+ taskProject = fs.realpathSync.native(context.projectPath);
891
+ }
892
+ catch {
893
+ fail('PROJECT_CHANGED', 'Task project is unavailable');
894
+ }
895
+ if (taskProject !== root)
896
+ fail('PROJECT_CHANGED', 'Start the task in the Agent current default project');
897
+ const binding = inspectPanelCardProject(aid);
898
+ const options = { ownerAid: actor.owner, authorizeWrite: authorize, expectedContentVersion: expected,
899
+ expectedBindingRevision: binding.bindingRevision, requireExpectedVersion: true };
900
+ const receipt = action === 'publish'
901
+ ? await publishPanelCard(aid, draft, options)
902
+ : await removePanelCard(aid, flags.get('--id'), options);
903
+ const service = panelServices.get(aid);
904
+ if (service) {
905
+ try {
906
+ const changed = receipt.changed === true || receipt.removed === true;
907
+ const projection = await service.notifyChange(changed);
908
+ return { ...receipt, ...projection, projectionRevision: projection.revision, capabilityVersion };
909
+ }
910
+ catch { /* The binding may have changed after the successful disk commit. */ }
911
+ }
912
+ return { ...receipt, notified: false, capabilityVersion };
913
+ }
914
+ const panelCardsExample = {
915
+ schemaVersion: 1, catalog: 'evol.cards.v1', id: 'meeting.latest', title: 'Latest meeting',
916
+ span: { w: 2, h: 2 }, theme: 'accent', body: { type: 'heading', text: 'Meeting notes' },
917
+ actions: [{ id: 'open-chat', type: 'openChat', label: 'Open chat' }],
918
+ };
919
+ export function panelCardsRequestSchema(type) {
920
+ const action = type.split('.').at(-1);
921
+ const properties = { protocolVersion: { const: 1 } };
922
+ const required = ['protocolVersion'];
923
+ if (action === 'snapshot' || action === 'list')
924
+ Object.assign(properties, { limit: { type: 'integer', minimum: 1, maximum: MAX_PAGE }, ...(action === 'snapshot' ? { knownRevision: { type: 'string', maxLength: 128 } } : { pageCursor: { type: 'string', maxLength: 512 } }) });
925
+ if (action === 'detail') {
926
+ properties.id = { type: 'string', pattern: '^[a-z0-9][a-z0-9._-]{0,63}$' };
927
+ properties.htmlVersion = { type: 'string', pattern: VERSION.source };
928
+ properties.bindingEpoch = { type: 'string', pattern: '^[A-Za-z0-9_-]{20,32}$' };
929
+ required.push('id');
930
+ }
931
+ if (action === 'changes') {
932
+ properties.cursor = { type: 'string', maxLength: 128 };
933
+ required.push('cursor');
934
+ }
935
+ return { type: 'object', additionalProperties: false, required: ['type', 'request_id', 'data'], properties: { type: { const: type }, request_id: { type: 'string', minLength: 1, maxLength: 128 }, data: { type: 'object', additionalProperties: false, required, properties } } };
936
+ }
937
+ export function panelCardsResponseSchema() {
938
+ return {
939
+ type: 'object', additionalProperties: false,
940
+ required: ['protocol', 'protocolVersion', 'catalog', 'sourceAid', 'scopeId', 'bindingEpoch', 'revision', 'cursor', 'generatedAt', 'sourceState', 'notifications', 'items', 'nextCursor'],
941
+ properties: {
942
+ protocol: { const: 'evol.panel-cards' }, protocolVersion: { const: 1 }, catalog: { const: 'evol.cards.v1' },
943
+ sourceAid: { type: 'string', minLength: 3, maxLength: 256 }, scopeId: { type: 'string', minLength: 16, maxLength: 64 },
944
+ bindingEpoch: { type: 'string', minLength: 16, maxLength: 64 }, revision: { type: 'string', pattern: '^[a-f0-9]{24}$' },
945
+ cursor: { type: 'string', maxLength: 128 }, generatedAt: { type: 'integer', minimum: 0 }, sourceState: { enum: ['ready', 'empty'] },
946
+ notifications: { anyOf: [{ type: 'null' }, { type: 'object', additionalProperties: false, required: ['busAid', 'event'], properties: { busAid: { type: 'string' }, event: { const: PANEL_CARDS_EVENT } } }] },
947
+ items: { type: 'array', maxItems: MAX_PAGE, items: { type: 'object' } },
948
+ nextCursor: { anyOf: [{ type: 'null' }, { type: 'string', maxLength: 512 }] },
949
+ htmlBase64: { type: 'string', maxLength: Math.ceil(MAX_INLINE_HTML_BYTES / 3) * 4 },
950
+ reset: { type: 'boolean' }, deletes: { type: 'array', maxItems: MAX_CARDS, items: { type: 'string', pattern: '^[a-z0-9][a-z0-9._-]{0,63}$' } }, notModified: { type: 'boolean' },
951
+ },
952
+ };
953
+ }
954
+ export const panelCardsCatalog = {
955
+ protocol: 'evol.panel-cards', protocolVersion: 1, catalog: 'evol.cards.v1',
956
+ spans: [{ w: 1, h: 1 }, { w: 1, h: 2 }, { w: 1, h: 3 }, { w: 2, h: 1 }, { w: 2, h: 2 }, { w: 2, h: 3 }],
957
+ themes: [...TONES], components: [...NODE_TYPES], icons: [...ICONS], actions: ['openFile', 'openChat', 'openDirectory', 'openTask'],
958
+ html: { body: { type: 'html', resourceId: 'surface' }, resourceKind: 'file', extensions: ['.html', '.htm'], scripts: false, network: false, inlineCss: true, inlineSvg: true, dataImages: true },
959
+ limits: { cardBytes: MAX_CARD_BYTES, htmlBytes: 256 * 1024, cardsPerScope: MAX_CARDS, nodes: 120, depth: 6, listItems: 16, resources: 12, actions: 8, resourceBytes: MAX_RESOURCE_BYTES },
960
+ };