@zhin.js/core 1.5.16 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (334) hide show
  1. package/README.md +78 -195
  2. package/lib/ai-completion-contract.d.ts +135 -0
  3. package/lib/ai-completion-contract.js +69 -0
  4. package/lib/built/ai-access.d.ts +2 -21
  5. package/lib/built/ai-access.js +1 -46
  6. package/lib/built/ai-outbound/index.d.ts +0 -2
  7. package/lib/built/ai-outbound/index.js +0 -2
  8. package/lib/built/ai-outbound/prompt.d.ts +2 -0
  9. package/lib/built/ai-outbound/prompt.js +2 -0
  10. package/lib/built/ai-outbound/types.d.ts +1 -10
  11. package/lib/built/ai-trigger.d.ts +39 -78
  12. package/lib/built/ai-trigger.js +3 -254
  13. package/lib/built/common-adapter-tools.d.ts +21 -6
  14. package/lib/built/common-adapter-tools.js +28 -17
  15. package/lib/built/generic-segment-mapper.js +4 -1
  16. package/lib/built/html-segment-fallback.d.ts +6 -7
  17. package/lib/built/html-segment-fallback.js +1 -16
  18. package/lib/built/html-to-text.d.ts +0 -3
  19. package/lib/built/html-to-text.js +131 -40
  20. package/lib/built/interaction-messages.d.ts +1 -0
  21. package/lib/built/interaction-messages.js +30 -0
  22. package/lib/built/interactive-segments/action.d.ts +3 -4
  23. package/lib/built/interactive-segments/action.js +2 -5
  24. package/lib/built/interactive-segments/index.d.ts +0 -2
  25. package/lib/built/interactive-segments/index.js +0 -2
  26. package/lib/built/interactive-segments/keyboard-segment.d.ts +0 -1
  27. package/lib/built/interactive-segments/keyboard-segment.js +0 -1
  28. package/lib/built/interactive-segments/onebot-keyboard.d.ts +0 -1
  29. package/lib/built/interactive-segments/onebot-keyboard.js +0 -2
  30. package/lib/built/interactive-segments/resolve.d.ts +2 -3
  31. package/lib/built/interactive-segments/resolve.js +21 -14
  32. package/lib/built/interactive-segments/types.d.ts +2 -7
  33. package/lib/built/interactive-segments/types.js +22 -2
  34. package/lib/built/login-assist.d.ts +330 -25
  35. package/lib/built/login-assist.js +1156 -75
  36. package/lib/built/login-captcha.d.ts +62 -0
  37. package/lib/built/login-captcha.js +107 -0
  38. package/lib/built/message-enrich.d.ts +24 -27
  39. package/lib/built/message-enrich.js +53 -49
  40. package/lib/built/outbound-content-arrays.d.ts +4 -0
  41. package/lib/built/outbound-content-arrays.js +32 -0
  42. package/lib/built/outbound-media-trust.d.ts +46 -0
  43. package/lib/built/outbound-media-trust.js +245 -0
  44. package/lib/built/outbound-media-utils.d.ts +5 -3
  45. package/lib/built/outbound-media-utils.js +5 -3
  46. package/lib/built/readable-link.d.ts +4 -0
  47. package/lib/built/readable-link.js +32 -0
  48. package/lib/built/rich-segments/markdown-to-text.d.ts +1 -2
  49. package/lib/built/rich-segments/markdown-to-text.js +141 -17
  50. package/lib/built/roles.d.ts +141 -12
  51. package/lib/built/roles.js +253 -52
  52. package/lib/built/segment-contract/assert.js +8 -2
  53. package/lib/built/segment-contract/delivery.js +1 -0
  54. package/lib/built/segment-contract/index.d.ts +3 -3
  55. package/lib/built/segment-contract/index.js +2 -2
  56. package/lib/built/segment-contract/json-schema.d.ts +39 -5
  57. package/lib/built/segment-contract/json-schema.js +207 -24
  58. package/lib/built/segment-contract/preview.js +8 -1
  59. package/lib/built/segment-contract/text.js +1 -1
  60. package/lib/built/segment-contract/types.d.ts +2 -2
  61. package/lib/built/segment-contract/validate.d.ts +1553 -224
  62. package/lib/built/segment-contract/validate.js +39 -3
  63. package/lib/built/tool-access.d.ts +5 -0
  64. package/lib/built/tool-access.js +17 -0
  65. package/lib/built/user-interaction.d.ts +5 -4
  66. package/lib/built/user-interaction.js +64 -52
  67. package/lib/errors.d.ts +1 -18
  68. package/lib/errors.js +1 -26
  69. package/lib/feature/command-public-api.d.ts +5 -0
  70. package/lib/feature/command-public-api.js +5 -0
  71. package/lib/feature/command.d.ts +2 -0
  72. package/lib/feature/command.js +1 -0
  73. package/lib/feature/component.d.ts +1 -0
  74. package/lib/feature/component.js +1 -0
  75. package/lib/feature/handler.d.ts +13 -7
  76. package/lib/feature/handler.js +2 -1
  77. package/lib/feature/middleware-public-api.d.ts +6 -0
  78. package/lib/feature/middleware-public-api.js +6 -0
  79. package/lib/feature/middleware.d.ts +22 -2
  80. package/lib/feature/middleware.js +7 -2
  81. package/lib/im-scene.d.ts +4 -3
  82. package/lib/im-scene.js +9 -9
  83. package/lib/im-session-id.d.ts +20 -12
  84. package/lib/im-session-id.js +8 -8
  85. package/lib/index.d.ts +20 -48
  86. package/lib/index.js +15 -41
  87. package/lib/jsx/intrinsic-elements.d.ts +83 -0
  88. package/lib/jsx/message-renderer.d.ts +13 -0
  89. package/lib/jsx/message-renderer.js +128 -0
  90. package/lib/jsx/message-tags.d.ts +133 -0
  91. package/lib/jsx/message-tags.js +50 -0
  92. package/lib/jsx-dev-runtime.d.ts +2 -2
  93. package/lib/jsx-dev-runtime.js +1 -2
  94. package/lib/jsx-runtime.d.ts +2 -12
  95. package/lib/jsx-runtime.js +1 -10
  96. package/lib/jsx.d.ts +6 -30
  97. package/lib/jsx.js +3 -93
  98. package/lib/message.d.ts +0 -40
  99. package/lib/message.js +1 -27
  100. package/lib/models/system-log.d.ts +0 -2
  101. package/lib/models/system-log.js +1 -8
  102. package/lib/models/user.d.ts +0 -2
  103. package/lib/models/user.js +1 -7
  104. package/lib/notice.d.ts +38 -33
  105. package/lib/notice.js +23 -7
  106. package/lib/plugin-runtime/im/command-feedback.d.ts +59 -0
  107. package/lib/plugin-runtime/im/command-feedback.js +148 -0
  108. package/lib/plugin-runtime/im/contracts.d.ts +217 -32
  109. package/lib/plugin-runtime/im/contracts.js +141 -23
  110. package/lib/plugin-runtime/im/conversation-runtime.d.ts +42 -0
  111. package/lib/plugin-runtime/im/conversation-runtime.js +451 -0
  112. package/lib/plugin-runtime/im/endpoint-runtime.d.ts +112 -0
  113. package/lib/plugin-runtime/im/endpoint-runtime.js +434 -0
  114. package/lib/plugin-runtime/im/feature-gate.d.ts +21 -0
  115. package/lib/plugin-runtime/im/feature-gate.js +88 -0
  116. package/lib/plugin-runtime/im/host/component-host-installer.d.ts +2 -0
  117. package/lib/plugin-runtime/im/host/component-host-installer.js +14 -0
  118. package/lib/plugin-runtime/im/host/conversation-migration.d.ts +5 -0
  119. package/lib/plugin-runtime/im/host/conversation-migration.js +75 -0
  120. package/lib/plugin-runtime/im/host/database-config.d.ts +10 -0
  121. package/lib/plugin-runtime/im/host/database-config.js +152 -0
  122. package/lib/plugin-runtime/im/host/database-console-schema.d.ts +79 -0
  123. package/lib/plugin-runtime/im/host/database-console-schema.js +477 -0
  124. package/lib/plugin-runtime/im/host/database-console-sql.d.ts +66 -0
  125. package/lib/plugin-runtime/im/host/database-console-sql.js +459 -0
  126. package/lib/plugin-runtime/im/host/database-host-installer.d.ts +60 -0
  127. package/lib/plugin-runtime/im/host/database-host-installer.js +1166 -0
  128. package/lib/plugin-runtime/im/host/database-state.d.ts +9 -0
  129. package/lib/plugin-runtime/im/host/database-state.js +91 -0
  130. package/lib/plugin-runtime/im/host/index.d.ts +8 -0
  131. package/lib/plugin-runtime/im/host/index.js +8 -0
  132. package/lib/plugin-runtime/im/host/locale-host-installer.d.ts +3 -0
  133. package/lib/plugin-runtime/im/host/locale-host-installer.js +60 -0
  134. package/lib/plugin-runtime/im/host/outbound-host-installer.d.ts +8 -0
  135. package/lib/plugin-runtime/im/host/outbound-host-installer.js +153 -0
  136. package/lib/plugin-runtime/im/host/sender-enrichment.d.ts +34 -0
  137. package/lib/plugin-runtime/im/host/sender-enrichment.js +82 -0
  138. package/lib/plugin-runtime/im/im-runtime.d.ts +40 -111
  139. package/lib/plugin-runtime/im/im-runtime.js +235 -1059
  140. package/lib/plugin-runtime/im/inbound-dedup.d.ts +84 -0
  141. package/lib/plugin-runtime/im/inbound-dedup.js +322 -0
  142. package/lib/plugin-runtime/im/inbound-origin.d.ts +150 -0
  143. package/lib/plugin-runtime/im/inbound-origin.js +183 -0
  144. package/lib/plugin-runtime/im/inbound-runtime.d.ts +59 -0
  145. package/lib/plugin-runtime/im/inbound-runtime.js +478 -0
  146. package/lib/plugin-runtime/im/inbound-spine.d.ts +196 -0
  147. package/lib/plugin-runtime/im/inbound-spine.js +335 -0
  148. package/lib/plugin-runtime/im/index.d.ts +15 -4
  149. package/lib/plugin-runtime/im/index.js +11 -4
  150. package/lib/plugin-runtime/im/interaction-runtime.d.ts +50 -0
  151. package/lib/plugin-runtime/im/interaction-runtime.js +390 -0
  152. package/lib/plugin-runtime/im/interactive-router.d.ts +81 -0
  153. package/lib/plugin-runtime/im/interactive-router.js +382 -0
  154. package/lib/plugin-runtime/im/message-diagnostics.d.ts +70 -0
  155. package/lib/plugin-runtime/im/message-diagnostics.js +182 -0
  156. package/lib/plugin-runtime/im/message-dispatcher.d.ts +18 -4
  157. package/lib/plugin-runtime/im/message-dispatcher.js +138 -20
  158. package/lib/plugin-runtime/im/message-events.d.ts +85 -0
  159. package/lib/plugin-runtime/im/message-events.js +113 -0
  160. package/lib/plugin-runtime/im/outbound-delivery-runtime.d.ts +39 -0
  161. package/lib/plugin-runtime/im/outbound-delivery-runtime.js +450 -0
  162. package/lib/plugin-runtime/im/outbound-renderer.d.ts +52 -3
  163. package/lib/plugin-runtime/im/outbound-renderer.js +188 -8
  164. package/lib/plugin-runtime/im/outbound-segments.d.ts +29 -5
  165. package/lib/plugin-runtime/im/outbound-segments.js +130 -36
  166. package/lib/plugin-runtime/im/progressive-reply.d.ts +58 -0
  167. package/lib/plugin-runtime/im/progressive-reply.js +501 -0
  168. package/lib/plugin-runtime/im/public-api.d.ts +1 -1
  169. package/lib/request.d.ts +27 -36
  170. package/lib/request.js +14 -6
  171. package/lib/side-event/base.d.ts +64 -44
  172. package/lib/side-event/base.js +72 -19
  173. package/lib/side-event/index.d.ts +1 -1
  174. package/lib/side-event/index.js +1 -1
  175. package/lib/side-event/normalize.d.ts +7 -38
  176. package/lib/side-event/normalize.js +4 -109
  177. package/lib/side-event/scene-events.d.ts +40 -0
  178. package/lib/side-event/scene-events.js +147 -0
  179. package/lib/side-event/types.d.ts +4 -13
  180. package/lib/side-event/types.js +1 -55
  181. package/lib/system-event.d.ts +17 -12
  182. package/lib/system-event.js +8 -6
  183. package/lib/types.d.ts +23 -167
  184. package/lib/utils.d.ts +50 -33
  185. package/lib/utils.js +12 -185
  186. package/lib/venue/contracts.d.ts +21 -0
  187. package/lib/venue/contracts.js +3 -0
  188. package/lib/venue/floor-controller.d.ts +11 -0
  189. package/lib/venue/floor-controller.js +63 -0
  190. package/lib/venue/index.d.ts +13 -0
  191. package/lib/venue/index.js +11 -0
  192. package/lib/venue/membership-port.d.ts +23 -0
  193. package/lib/venue/membership-port.js +141 -0
  194. package/lib/venue/projector.d.ts +38 -0
  195. package/lib/venue/projector.js +45 -0
  196. package/lib/venue/registry.d.ts +16 -0
  197. package/lib/venue/registry.js +63 -0
  198. package/lib/venue/router.d.ts +19 -0
  199. package/lib/venue/router.js +101 -0
  200. package/lib/venue/send-limiter.d.ts +17 -0
  201. package/lib/venue/send-limiter.js +73 -0
  202. package/lib/venue/validator.d.ts +6 -0
  203. package/lib/venue/validator.js +160 -0
  204. package/package.json +24 -50
  205. package/lib/adapter.d.ts +0 -145
  206. package/lib/adapter.js +0 -377
  207. package/lib/built/adapter-process.d.ts +0 -58
  208. package/lib/built/adapter-process.js +0 -128
  209. package/lib/built/agent-preset.d.ts +0 -64
  210. package/lib/built/agent-preset.js +0 -79
  211. package/lib/built/ai-outbound/adapter-access.d.ts +0 -3
  212. package/lib/built/ai-outbound/adapter-access.js +0 -9
  213. package/lib/built/ai-outbound/extensions/qq-message.d.ts +0 -3
  214. package/lib/built/ai-outbound/extensions/qq-message.js +0 -23
  215. package/lib/built/authorization.d.ts +0 -10
  216. package/lib/built/authorization.js +0 -76
  217. package/lib/built/command.d.ts +0 -72
  218. package/lib/built/command.js +0 -105
  219. package/lib/built/component.d.ts +0 -67
  220. package/lib/built/component.js +0 -97
  221. package/lib/built/config.d.ts +0 -98
  222. package/lib/built/config.js +0 -372
  223. package/lib/built/connect-endpoint-instance.d.ts +0 -17
  224. package/lib/built/connect-endpoint-instance.js +0 -42
  225. package/lib/built/database.d.ts +0 -68
  226. package/lib/built/database.js +0 -106
  227. package/lib/built/dispatcher.d.ts +0 -141
  228. package/lib/built/dispatcher.js +0 -383
  229. package/lib/built/endpoint-commands.d.ts +0 -3
  230. package/lib/built/endpoint-commands.js +0 -99
  231. package/lib/built/endpoint-lifecycle-service.d.ts +0 -28
  232. package/lib/built/endpoint-lifecycle-service.js +0 -242
  233. package/lib/built/endpoint-lifecycle.d.ts +0 -27
  234. package/lib/built/endpoint-lifecycle.js +0 -36
  235. package/lib/built/endpoint-manager.d.ts +0 -34
  236. package/lib/built/html-renderer-loader.d.ts +0 -13
  237. package/lib/built/html-renderer-loader.js +0 -33
  238. package/lib/built/inbound-pipeline.d.ts +0 -37
  239. package/lib/built/inbound-pipeline.js +0 -63
  240. package/lib/built/inbound-runner.d.ts +0 -22
  241. package/lib/built/inbound-runner.js +0 -34
  242. package/lib/built/interactive-segment-contract.d.ts +0 -6
  243. package/lib/built/interactive-segment-contract.js +0 -9
  244. package/lib/built/interactive-segments/fallback-store.d.ts +0 -29
  245. package/lib/built/interactive-segments/fallback-store.js +0 -63
  246. package/lib/built/interactive-segments/handlers.d.ts +0 -16
  247. package/lib/built/interactive-segments/handlers.js +0 -74
  248. package/lib/built/introspection-format.d.ts +0 -10
  249. package/lib/built/introspection-format.js +0 -28
  250. package/lib/built/management-command-guard.d.ts +0 -15
  251. package/lib/built/management-command-guard.js +0 -25
  252. package/lib/built/message-filter.d.ts +0 -176
  253. package/lib/built/message-filter.js +0 -239
  254. package/lib/built/optional-peer-import.d.ts +0 -3
  255. package/lib/built/optional-peer-import.js +0 -33
  256. package/lib/built/outbound-media-contract.d.ts +0 -22
  257. package/lib/built/outbound-media-contract.js +0 -10
  258. package/lib/built/permission.d.ts +0 -51
  259. package/lib/built/permission.js +0 -99
  260. package/lib/built/permit-check.d.ts +0 -7
  261. package/lib/built/permit-check.js +0 -35
  262. package/lib/built/permit-parse.d.ts +0 -16
  263. package/lib/built/permit-parse.js +0 -32
  264. package/lib/built/platform-permit.d.ts +0 -20
  265. package/lib/built/platform-permit.js +0 -91
  266. package/lib/built/queue-im-field-contract.d.ts +0 -32
  267. package/lib/built/queue-im-field-contract.js +0 -67
  268. package/lib/built/rich-segments/adapter-policies.d.ts +0 -9
  269. package/lib/built/rich-segments/adapter-policies.js +0 -27
  270. package/lib/built/rich-segments/base.d.ts +0 -11
  271. package/lib/built/rich-segments/base.js +0 -24
  272. package/lib/built/rich-segments/builtins.d.ts +0 -4
  273. package/lib/built/rich-segments/builtins.js +0 -40
  274. package/lib/built/rich-segments/capabilities.d.ts +0 -6
  275. package/lib/built/rich-segments/capabilities.js +0 -38
  276. package/lib/built/rich-segments/html-segment.d.ts +0 -15
  277. package/lib/built/rich-segments/html-segment.js +0 -62
  278. package/lib/built/rich-segments/index.d.ts +0 -13
  279. package/lib/built/rich-segments/index.js +0 -13
  280. package/lib/built/rich-segments/markdown-segment.d.ts +0 -14
  281. package/lib/built/rich-segments/markdown-segment.js +0 -58
  282. package/lib/built/rich-segments/qrcode-segment.d.ts +0 -18
  283. package/lib/built/rich-segments/qrcode-segment.js +0 -73
  284. package/lib/built/rich-segments/registry.d.ts +0 -16
  285. package/lib/built/rich-segments/registry.js +0 -52
  286. package/lib/built/rich-segments/resolve.d.ts +0 -5
  287. package/lib/built/rich-segments/resolve.js +0 -87
  288. package/lib/built/rich-segments/tts-segment.d.ts +0 -13
  289. package/lib/built/rich-segments/tts-segment.js +0 -51
  290. package/lib/built/rich-segments/types.d.ts +0 -79
  291. package/lib/built/rich-segments/types.js +0 -17
  292. package/lib/built/runtime-io.d.ts +0 -9
  293. package/lib/built/runtime-io.js +0 -67
  294. package/lib/built/schedule.d.ts +0 -54
  295. package/lib/built/schedule.js +0 -112
  296. package/lib/built/schema-endpoint-manager.d.ts +0 -17
  297. package/lib/built/schema-endpoint-manager.js +0 -73
  298. package/lib/built/schema-feature.d.ts +0 -77
  299. package/lib/built/schema-feature.js +0 -130
  300. package/lib/built/skill.d.ts +0 -120
  301. package/lib/built/skill.js +0 -151
  302. package/lib/built/speech-loader.d.ts +0 -14
  303. package/lib/built/speech-loader.js +0 -32
  304. package/lib/built/tool.d.ts +0 -151
  305. package/lib/built/tool.js +0 -388
  306. package/lib/command.d.ts +0 -50
  307. package/lib/command.js +0 -106
  308. package/lib/component.d.ts +0 -26
  309. package/lib/component.js +0 -583
  310. package/lib/endpoint-capabilities.d.ts +0 -46
  311. package/lib/endpoint-capabilities.js +0 -55
  312. package/lib/endpoint.d.ts +0 -19
  313. package/lib/endpoint.js +0 -3
  314. package/lib/host-plugin-registry.d.ts +0 -8
  315. package/lib/host-plugin-registry.js +0 -12
  316. package/lib/plugin-context.d.ts +0 -27
  317. package/lib/plugin-context.js +0 -64
  318. package/lib/plugin-runtime/im/interactive.d.ts +0 -26
  319. package/lib/plugin-runtime/im/interactive.js +0 -46
  320. package/lib/plugin-runtime/im/login-assist-host.d.ts +0 -6
  321. package/lib/plugin-runtime/im/login-assist-host.js +0 -6
  322. package/lib/plugin-runtime/im/message-bus.d.ts +0 -38
  323. package/lib/plugin-runtime/im/message-bus.js +0 -40
  324. package/lib/plugin-runtime/im/service-tokens.d.ts +0 -18
  325. package/lib/plugin-runtime/im/service-tokens.js +0 -13
  326. package/lib/plugin.d.ts +0 -268
  327. package/lib/plugin.js +0 -583
  328. package/lib/schema-interaction.d.ts +0 -117
  329. package/lib/schema-interaction.js +0 -247
  330. package/lib/side-event/dispatch.d.ts +0 -15
  331. package/lib/side-event/dispatch.js +0 -140
  332. package/lib/tool-zod.d.ts +0 -43
  333. package/lib/tool-zod.js +0 -184
  334. /package/lib/{built/endpoint-manager.js → jsx/intrinsic-elements.js} +0 -0
@@ -0,0 +1,62 @@
1
+ /**
2
+ * Hosted captcha helper (ADR 0058 §验证引导与辅助材料). Pure and browser-safe: shared by the Console,
3
+ * SDKs and tests. No Node built-ins.
4
+ *
5
+ * The opener (Console) opens `${helperUrl}#${payload}` in a popup. The helper page runs on its own
6
+ * origin, loads the provider's captcha with `payload.q`, and on success posts
7
+ * `{ type: LOGIN_CAPTCHA_MESSAGE_TYPE, nonce, ticket, randstr }` to `window.opener` at `payload.o`.
8
+ * The opener accepts it only from the helper origin and with its own nonce.
9
+ */
10
+ /** `postMessage` type the helper page sends back. */
11
+ export declare const LOGIN_CAPTCHA_MESSAGE_TYPE: "zhin.login-assist.captcha";
12
+ /** Default hosted helper page (separate origin from any Console). */
13
+ export declare const DEFAULT_CAPTCHA_HELPER_URL = "https://zhin.js.org/login-assist/tcaptcha.html";
14
+ /** `media.captcha` of a slider challenge. */
15
+ export interface LoginCaptchaMedia {
16
+ readonly provider: 'tencent';
17
+ /** Query string of the platform's slider URL, verbatim. */
18
+ readonly query: string;
19
+ /** Overrides the default (or host-configured) helper page. */
20
+ readonly helperUrl?: string;
21
+ }
22
+ /** Fragment payload of the helper URL. */
23
+ export interface LoginCaptchaHelperPayload {
24
+ /** Provider query string. */
25
+ readonly q: string;
26
+ /** Opener nonce, echoed back. */
27
+ readonly n: string;
28
+ /** Opener origin, the only `postMessage` target. */
29
+ readonly o: string;
30
+ }
31
+ export interface BuildCaptchaHelperUrlInput {
32
+ readonly helperUrl?: string;
33
+ readonly query: string;
34
+ readonly nonce: string;
35
+ /** Origin of the opener (`location.origin`). */
36
+ readonly origin: string;
37
+ }
38
+ /**
39
+ * `${helperUrl}#${base64url(JSON {q, n, o})}`. The payload goes in the fragment so it never reaches
40
+ * a server log. Throws on a non-https helper (http only for localhost) or an invalid origin.
41
+ */
42
+ export declare function buildCaptchaHelperUrl(input: BuildCaptchaHelperUrlInput): string;
43
+ /** Decodes the fragment payload on the helper page (`location.hash`); `null` when malformed. */
44
+ export declare function parseCaptchaHelperPayload(hash: string): LoginCaptchaHelperPayload | null;
45
+ /**
46
+ * Accepts a helper `message` event only from `helperOrigin` and with the expected nonce.
47
+ * Returns the ticket and randstr, or `null`.
48
+ */
49
+ export declare function parseCaptchaHelperMessage(event: {
50
+ readonly origin: string;
51
+ readonly data: unknown;
52
+ }, expected: {
53
+ readonly helperOrigin: string;
54
+ readonly nonce: string;
55
+ }): {
56
+ readonly ticket: string;
57
+ readonly randstr: string;
58
+ } | null;
59
+ /** Origin of a helper URL (for `parseCaptchaHelperMessage`); `null` when invalid. */
60
+ export declare function captchaHelperOrigin(helperUrl?: string): string | null;
61
+ /** Whether a configured helper URL is usable (https, or http on localhost). */
62
+ export declare function isValidCaptchaHelperUrl(value: unknown): value is string;
@@ -0,0 +1,107 @@
1
+ /**
2
+ * Hosted captcha helper (ADR 0058 §验证引导与辅助材料). Pure and browser-safe: shared by the Console,
3
+ * SDKs and tests. No Node built-ins.
4
+ *
5
+ * The opener (Console) opens `${helperUrl}#${payload}` in a popup. The helper page runs on its own
6
+ * origin, loads the provider's captcha with `payload.q`, and on success posts
7
+ * `{ type: LOGIN_CAPTCHA_MESSAGE_TYPE, nonce, ticket, randstr }` to `window.opener` at `payload.o`.
8
+ * The opener accepts it only from the helper origin and with its own nonce.
9
+ */
10
+ /** `postMessage` type the helper page sends back. */
11
+ export const LOGIN_CAPTCHA_MESSAGE_TYPE = 'zhin.login-assist.captcha';
12
+ /** Default hosted helper page (separate origin from any Console). */
13
+ export const DEFAULT_CAPTCHA_HELPER_URL = 'https://zhin.js.org/login-assist/tcaptcha.html';
14
+ /**
15
+ * `${helperUrl}#${base64url(JSON {q, n, o})}`. The payload goes in the fragment so it never reaches
16
+ * a server log. Throws on a non-https helper (http only for localhost) or an invalid origin.
17
+ */
18
+ export function buildCaptchaHelperUrl(input) {
19
+ const helper = validHelperUrl(input.helperUrl ?? DEFAULT_CAPTCHA_HELPER_URL);
20
+ if (!helper)
21
+ throw new TypeError('captcha helper URL must be https (http only on localhost)');
22
+ const origin = validOrigin(input.origin);
23
+ if (!origin)
24
+ throw new TypeError('opener origin is invalid');
25
+ if (typeof input.nonce !== 'string' || input.nonce.length < 8)
26
+ throw new TypeError('nonce must have at least 8 characters');
27
+ const query = typeof input.query === 'string' ? input.query.replace(/^\?/u, '') : '';
28
+ if (!query)
29
+ throw new TypeError('captcha query is required');
30
+ helper.hash = encodeBase64Url(JSON.stringify({ q: query, n: input.nonce, o: origin }));
31
+ return helper.toString();
32
+ }
33
+ /** Decodes the fragment payload on the helper page (`location.hash`); `null` when malformed. */
34
+ export function parseCaptchaHelperPayload(hash) {
35
+ try {
36
+ const parsed = JSON.parse(decodeBase64Url(hash.replace(/^#/u, '')));
37
+ if (typeof parsed.q !== 'string' || !parsed.q || typeof parsed.n !== 'string' || !parsed.n)
38
+ return null;
39
+ const origin = typeof parsed.o === 'string' ? validOrigin(parsed.o) : null;
40
+ return origin ? Object.freeze({ q: parsed.q, n: parsed.n, o: origin }) : null;
41
+ }
42
+ catch {
43
+ return null;
44
+ }
45
+ }
46
+ /**
47
+ * Accepts a helper `message` event only from `helperOrigin` and with the expected nonce.
48
+ * Returns the ticket and randstr, or `null`.
49
+ */
50
+ export function parseCaptchaHelperMessage(event, expected) {
51
+ if (!event || event.origin !== expected.helperOrigin || !expected.nonce)
52
+ return null;
53
+ const data = event.data;
54
+ if (!data || typeof data !== 'object' || data.type !== LOGIN_CAPTCHA_MESSAGE_TYPE || data.nonce !== expected.nonce)
55
+ return null;
56
+ const ticket = typeof data.ticket === 'string' ? data.ticket.trim() : '';
57
+ const randstr = typeof data.randstr === 'string' ? data.randstr.trim() : '';
58
+ if (!ticket || /[\s,]/u.test(ticket) || /[\s,]/u.test(randstr) || ticket.length > 4096 || randstr.length > 256)
59
+ return null;
60
+ return Object.freeze({ ticket, randstr });
61
+ }
62
+ /** Origin of a helper URL (for `parseCaptchaHelperMessage`); `null` when invalid. */
63
+ export function captchaHelperOrigin(helperUrl = DEFAULT_CAPTCHA_HELPER_URL) {
64
+ return validHelperUrl(helperUrl)?.origin ?? null;
65
+ }
66
+ /** Whether a configured helper URL is usable (https, or http on localhost). */
67
+ export function isValidCaptchaHelperUrl(value) {
68
+ return typeof value === 'string' && validHelperUrl(value) !== null;
69
+ }
70
+ function validHelperUrl(value) {
71
+ try {
72
+ const url = new URL(value);
73
+ const local = url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '[::1]';
74
+ if (url.protocol !== 'https:' && !(url.protocol === 'http:' && local))
75
+ return null;
76
+ if (url.username || url.password)
77
+ return null;
78
+ url.hash = '';
79
+ return url;
80
+ }
81
+ catch {
82
+ return null;
83
+ }
84
+ }
85
+ function validOrigin(value) {
86
+ try {
87
+ const url = new URL(value);
88
+ if (url.protocol !== 'https:' && url.protocol !== 'http:')
89
+ return null;
90
+ return url.origin === value.replace(/\/$/u, '') ? url.origin : null;
91
+ }
92
+ catch {
93
+ return null;
94
+ }
95
+ }
96
+ function encodeBase64Url(text) {
97
+ const bytes = new TextEncoder().encode(text);
98
+ let binary = '';
99
+ for (const byte of bytes)
100
+ binary += String.fromCharCode(byte);
101
+ return btoa(binary).replace(/\+/gu, '-').replace(/\//gu, '_').replace(/=+$/u, '');
102
+ }
103
+ function decodeBase64Url(text) {
104
+ const base64 = text.replace(/-/gu, '+').replace(/_/gu, '/');
105
+ const binary = atob(base64 + '='.repeat((4 - (base64.length % 4)) % 4));
106
+ return new TextDecoder().decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
107
+ }
@@ -1,38 +1,35 @@
1
1
  /**
2
- * Message enrich — 入站鉴权快照与合成通讯上下文
2
+ * Message enrich — inbound authorization snapshots and synthetic communication context.
3
3
  */
4
- import type { Plugin } from '../plugin.js';
5
- import { Message, type MessageChannel } from '../message.js';
6
- import type { Adapters } from '../adapter.js';
7
- import type { SendContent } from '../types.js';
8
- import { type SenderRole } from './roles.js';
9
- /** Agent turn 可挂载在 Message 扩展字段上的元数据 */
4
+ import type { ConversationRef, DeliveryReceipt } from '@zhin.js/im-contract';
5
+ import { type Locale } from '@zhin.js/plugin-runtime';
6
+ import type { Message, MessageSenderRef, Segment, SendContent } from '../plugin-runtime/im/contracts.js';
7
+ import { type ChatRole } from './roles.js';
8
+ /** Agent turns may attach host-owned metadata to the canonical runtime message. */
10
9
  export type AgentTurnMessage = Message<{
11
10
  extra?: Record<string, unknown>;
12
11
  }>;
13
- export declare function senderRolesFromMessage(message: Message<any>): readonly SenderRole[];
14
12
  /**
15
- * 入站 enrich:写入 $sender.isMaster / isTrusted 快照(本 turn 只读)
13
+ * zhin chat roles of the sender in this conversation, expanded (`owner` → owner, admin, trusted);
14
+ * empty for ordinary users. Only the Runtime-set `sender.chatRole` counts (ADR 0056).
16
15
  */
17
- export declare function enrichMessageForAgent(plugin: Plugin, message: Message<any>): Message<any>;
16
+ export declare function chatRolesFromMessage(message: Pick<Message, 'sender'>): readonly ChatRole[];
18
17
  export interface SyntheticMessageInput {
19
- adapter: keyof Adapters | string;
20
- endpoint: string;
21
- sender: {
22
- id: string;
23
- name?: string;
24
- role?: string;
25
- isMaster?: boolean;
26
- isTrusted?: boolean;
27
- };
28
- channel: MessageChannel;
29
- id?: string;
30
- reply?: (content: SendContent, quote?: boolean | string) => Promise<string>;
18
+ locale?: Locale;
19
+ conversation: ConversationRef;
20
+ sender?: MessageSenderRef;
21
+ content?: string;
22
+ segments?: readonly Segment[];
23
+ messageId?: string;
24
+ generation?: number;
25
+ endpointId?: string;
26
+ clientAdapter?: string;
27
+ reply?: (content: SendContent) => Promise<DeliveryReceipt>;
31
28
  extra?: Record<string, unknown>;
32
29
  }
33
- /** cron / subagent / mission 等无真实入站时构造最小 Message */
30
+ /** Construct a canonical Message for cron, subagent, and mission turns without live ingress. */
34
31
  export declare function createSyntheticMessage(input: SyntheticMessageInput): AgentTurnMessage;
35
- /** hook context 中的 commMessage 字段(AIHookEvent.context) */
36
- export declare function commMessageFromHookContext(context: Record<string, unknown>): Message<any> | undefined;
37
- /** 兼容 tool parameters 上的 contextKey(endpointKey / sceneId / scope 等) */
38
- export declare function resolveContextKey(message: Message<any>, key: string): unknown;
32
+ /** Read a canonical communication message from an AI hook context. */
33
+ export declare function commMessageFromHookContext(context: Record<string, unknown>): Message | undefined;
34
+ /** Resolve tool context injection keys from the canonical Message contract. */
35
+ export declare function resolveContextKey(message: Message, key: string): unknown;
@@ -1,75 +1,79 @@
1
- import { Message } from '../message.js';
2
- import { hasSenderRole } from './roles.js';
3
- import { resolveSubjectRoles } from './authorization.js';
4
- function frameworkRolesFromSenderFlags(sender) {
5
- if (sender.isMaster)
6
- return ['master'];
7
- if (sender.isTrusted)
8
- return ['trusted'];
9
- return ['user'];
10
- }
11
- export function senderRolesFromMessage(message) {
12
- const sender = message.$sender;
13
- if (sender.isMaster !== undefined || sender.isTrusted !== undefined) {
14
- return frameworkRolesFromSenderFlags(sender);
15
- }
16
- return ['user'];
17
- }
1
+ import { resolveLocale } from '@zhin.js/plugin-runtime';
2
+ import { expandChatRole } from './roles.js';
3
+ import { segmentsToPlainText } from './segment-contract/text.js';
18
4
  /**
19
- * 入站 enrich:写入 $sender.isMaster / isTrusted 快照(本 turn 只读)
5
+ * zhin chat roles of the sender in this conversation, expanded (`owner` → owner, admin, trusted);
6
+ * empty for ordinary users. Only the Runtime-set `sender.chatRole` counts (ADR 0056).
20
7
  */
21
- export function enrichMessageForAgent(plugin, message) {
22
- const { roles } = resolveSubjectRoles(plugin.root ?? plugin, message);
23
- message.$sender.isMaster = hasSenderRole(roles, 'master');
24
- message.$sender.isTrusted = !message.$sender.isMaster && hasSenderRole(roles, 'trusted');
25
- return message;
8
+ export function chatRolesFromMessage(message) {
9
+ return expandChatRole(message.sender?.chatRole);
26
10
  }
27
- /** cron / subagent / mission 等无真实入站时构造最小 Message */
11
+ /** Construct a canonical Message for cron, subagent, and mission turns without live ingress. */
28
12
  export function createSyntheticMessage(input) {
29
- const id = input.id ?? `synthetic:${Date.now()}`;
30
- const reply = input.reply ?? (async () => id);
31
- return Message.from({ extra: input.extra }, {
32
- $id: id,
33
- $adapter: input.adapter,
34
- $endpoint: input.endpoint,
35
- $content: [],
36
- $sender: { ...input.sender },
13
+ const messageId = input.messageId ?? `synthetic:${Date.now()}`;
14
+ const unsupportedReply = async () => Object.freeze({
15
+ status: 'unsupported',
16
+ failure: Object.freeze({
17
+ code: 'synthetic_reply_unavailable',
18
+ message: 'Synthetic Message has no outbound delivery port',
19
+ retryable: false,
20
+ }),
21
+ });
22
+ const reply = input.reply ?? unsupportedReply;
23
+ const segments = input.segments ? Object.freeze([...input.segments]) : undefined;
24
+ const content = segments ? segmentsToPlainText(segments) : (input.content ?? '');
25
+ return Object.freeze({
26
+ locale: resolveLocale(input.locale),
27
+ formatCommand: () => undefined,
28
+ conversation: input.conversation,
29
+ content,
30
+ generation: input.generation ?? 0,
31
+ metadata: Object.freeze({}),
32
+ segments,
33
+ sender: input.sender,
34
+ message: Object.freeze({ conversation: input.conversation, id: messageId }),
35
+ endpointId: input.endpointId,
36
+ clientAdapter: input.clientAdapter,
37
+ id: messageId,
38
+ extra: input.extra,
39
+ get $client() {
40
+ throw new Error('Synthetic Message has no Endpoint Client context');
41
+ },
37
42
  $reply: reply,
38
- $recall: async () => { },
39
- $channel: input.channel,
40
- $timestamp: Date.now(),
41
- $raw: '',
43
+ $replyFrom: () => unsupportedReply(),
44
+ $sendTo: () => unsupportedReply(),
45
+ $replyToPrivate: () => unsupportedReply(),
46
+ $replyToGroup: () => unsupportedReply(),
47
+ $replyToChannel: () => unsupportedReply(),
42
48
  });
43
49
  }
44
- /** hook context 中的 commMessage 字段(AIHookEvent.context) */
50
+ /** Read a canonical communication message from an AI hook context. */
45
51
  export function commMessageFromHookContext(context) {
46
52
  const raw = context.commMessage;
47
- if (raw && typeof raw === 'object' && '$sender' in raw) {
53
+ if (raw && typeof raw === 'object' && 'conversation' in raw && 'content' in raw) {
48
54
  return raw;
49
55
  }
50
56
  return undefined;
51
57
  }
52
- /** 兼容 tool parameters 上的 contextKey(endpointKey / sceneId / scope 等) */
58
+ /** Resolve tool context injection keys from the canonical Message contract. */
53
59
  export function resolveContextKey(message, key) {
54
60
  switch (key) {
55
61
  case 'platform':
56
- return message.$adapter;
62
+ return message.clientAdapter ?? message.conversation.endpoint.adapter;
57
63
  case 'endpointKey':
58
- return message.$endpoint;
64
+ return message.endpointId ?? message.conversation.endpoint.id;
59
65
  case 'messageId':
60
- return message.$id;
66
+ return message.id;
61
67
  case 'sceneId':
62
- return message.$channel?.id ?? message.$sender.id;
68
+ return message.conversation.id ?? message.sender?.id;
63
69
  case 'senderId':
64
- return message.$sender.id;
70
+ return message.sender?.id;
65
71
  case 'scope':
66
- return message.$channel?.type ?? 'private';
72
+ return message.conversation.kind;
67
73
  default: {
68
- if (key in message) {
74
+ if (key in message)
69
75
  return message[key];
70
- }
71
- const extra = message.extra;
72
- return extra?.[key];
76
+ return message.extra?.[key];
73
77
  }
74
78
  }
75
79
  }
@@ -0,0 +1,4 @@
1
+ /** Independent structural budget; array nesting does not spend component recursion depth. */
2
+ export declare const MAX_OUTBOUND_ARRAY_DEPTH = 512;
3
+ /** Flatten untrusted authoring/native arrays without recursion or shared-reference false positives. */
4
+ export declare function flattenOutboundArray(values: readonly unknown[]): unknown[];
@@ -0,0 +1,32 @@
1
+ /** Independent structural budget; array nesting does not spend component recursion depth. */
2
+ export const MAX_OUTBOUND_ARRAY_DEPTH = 512;
3
+ /** Flatten untrusted authoring/native arrays without recursion or shared-reference false positives. */
4
+ export function flattenOutboundArray(values) {
5
+ const output = [];
6
+ const active = new Set([values]);
7
+ const frames = [{ values, index: 0 }];
8
+ while (frames.length) {
9
+ const frame = frames[frames.length - 1];
10
+ if (frame.index >= frame.values.length) {
11
+ active.delete(frame.values);
12
+ frames.pop();
13
+ continue;
14
+ }
15
+ const index = frame.index++;
16
+ // Array.flat skips holes, but explicit undefined must remain for validation.
17
+ if (!(index in frame.values))
18
+ continue;
19
+ const value = frame.values[index];
20
+ if (!Array.isArray(value)) {
21
+ output.push(value);
22
+ continue;
23
+ }
24
+ if (active.has(value))
25
+ throw new TypeError('Cyclic SendContent array');
26
+ if (frames.length >= MAX_OUTBOUND_ARRAY_DEPTH)
27
+ throw new RangeError('SendContent array depth exceeded 512');
28
+ active.add(value);
29
+ frames.push({ values: value, index: 0 });
30
+ }
31
+ return output;
32
+ }
@@ -0,0 +1,46 @@
1
+ import type { Locale } from '@zhin.js/plugin-runtime';
2
+ import type { ConversationRef } from '@zhin.js/im-contract';
3
+ import type { MediaRef } from './segment-contract/types.js';
4
+ /** Same ceiling as the Agent's attachment limit (25 MiB of decoded bytes). */
5
+ export declare const DEFAULT_UNTRUSTED_INLINE_MEDIA_BYTES = 26214400;
6
+ export type OutboundMediaRefusal = 'url_scheme' | 'inline_too_large' | 'inline_invalid' | 'host_path' | 'platform_ref_path' | 'nested_media' | 'raw_payload';
7
+ export interface OutboundMediaTrust {
8
+ /** Short source label for logs, e.g. `agent:reply`. Never a user value. */
9
+ readonly source: string;
10
+ /**
11
+ * Admit one local path (already decoded from a `file:` URL): return the canonical path that may be
12
+ * sent, or `undefined` to refuse. Absent: every untrusted local path is refused.
13
+ */
14
+ readonly authorizePath?: (path: string) => Promise<string | undefined> | string | undefined;
15
+ /** Inline (`base64` / `data:`) limit in decoded bytes; defaults to {@link DEFAULT_UNTRUSTED_INLINE_MEDIA_BYTES}. */
16
+ readonly maxInlineBytes?: number;
17
+ /** Language of the visible refusal notice. */
18
+ readonly locale?: Locale;
19
+ }
20
+ export type UntrustedMediaDecision = Readonly<{
21
+ allowed: true;
22
+ media: MediaRef;
23
+ }> | Readonly<{
24
+ allowed: false;
25
+ reason: OutboundMediaRefusal;
26
+ }>;
27
+ /**
28
+ * Mark a MediaRef that trusted code constructed (not copied from model output) so it passes the
29
+ * untrusted-source policy unchanged. Identity-based: a copy of the object is not trusted.
30
+ */
31
+ export declare function trustedMediaRef<T extends MediaRef>(media: T): T;
32
+ export declare function isTrustedMediaRef(media: unknown): boolean;
33
+ /** A platform file token, not something an SDK would resolve against the host filesystem. */
34
+ export declare function isPlatformFileToken(value: string): boolean;
35
+ /** Decide one MediaRef from an untrusted source. */
36
+ export declare function checkUntrustedMediaRef(media: MediaRef, trust: OutboundMediaTrust): Promise<UntrustedMediaDecision>;
37
+ export interface UntrustedOutboundContext {
38
+ readonly requester?: string;
39
+ readonly conversation?: ConversationRef;
40
+ }
41
+ /**
42
+ * Hold rendered untrusted content to the policy. Strings stay text; segments are canonicalized first
43
+ * (legacy `{ file }` / `{ path }` fields become `data.media`), `html` is reduced to text (a renderer
44
+ * could load local files), raw native payloads are refused.
45
+ */
46
+ export declare function enforceUntrustedOutbound(rendered: unknown, trust: OutboundMediaTrust, context?: UntrustedOutboundContext): Promise<unknown[]>;