@acryldev/plugin-context 0.0.0-stage → 0.1.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 (284) hide show
  1. package/LICENSE +21 -0
  2. package/docs/README.md +160 -0
  3. package/docs/delivery/local-live.md +113 -0
  4. package/docs/delivery/marketplace.md +16 -0
  5. package/docs/docs.json +2836 -0
  6. package/docs/extending/agent-preset.md +37 -0
  7. package/docs/extending/chat-command.md +28 -0
  8. package/docs/extending/client-slot.md +135 -0
  9. package/docs/extending/config-schema.md +7 -0
  10. package/docs/extending/cordis-core.md +63 -0
  11. package/docs/extending/desktop-app.md +53 -0
  12. package/docs/extending/desktop-main.md +25 -0
  13. package/docs/extending/event-hook.md +14 -0
  14. package/docs/extending/host-route.md +33 -0
  15. package/docs/extending/llm-adapter.md +38 -0
  16. package/docs/extending/packaging.md +53 -0
  17. package/docs/extending/prompt-contribution.md +9 -0
  18. package/docs/extending/service.md +13 -0
  19. package/docs/extending/skill-provider.md +9 -0
  20. package/docs/extending/state-and-persistence.md +71 -0
  21. package/docs/extending/three-role-capability.md +33 -0
  22. package/docs/extending/tool-plugin.md +24 -0
  23. package/docs/extending/tui-command.md +8 -0
  24. package/docs/extending/tui-components.md +61 -0
  25. package/docs/extending/ui-branding.md +43 -0
  26. package/docs/extending/ui-components.md +56 -0
  27. package/docs/extending/ui-customization.md +41 -0
  28. package/docs/extending/ui-library.md +66 -0
  29. package/docs/extending/ui-theme.md +55 -0
  30. package/docs/extending/workspace-tab.md +50 -0
  31. package/docs/maps/events.md +108 -0
  32. package/docs/maps/mount-points.md +154 -0
  33. package/docs/maps/slot-contracts.md +3376 -0
  34. package/docs/maps/taxonomy.md +306 -0
  35. package/docs/maps/theme-tokens.md +115 -0
  36. package/docs/maps/ui-components.md +26 -0
  37. package/docs/reference/cookbook/adding-a-package.md +174 -0
  38. package/docs/reference/cookbook/adding-a-remote-api.md +199 -0
  39. package/docs/reference/cookbook/adding-a-settings-card.md +74 -0
  40. package/docs/reference/cookbook/adding-a-tool.md +103 -0
  41. package/docs/reference/cookbook/adding-an-llm-adapter.md +45 -0
  42. package/docs/reference/cookbook/extension-cookbook.md +134 -0
  43. package/docs/reference/cordis-api/context.md +366 -0
  44. package/docs/reference/cordis-api/events.md +209 -0
  45. package/docs/reference/cordis-api/fiber.md +377 -0
  46. package/docs/reference/cordis-api/inherited.md +40 -0
  47. package/docs/reference/cordis-api/registry.md +154 -0
  48. package/docs/reference/cordis-api/service.md +104 -0
  49. package/docs/reference/cordis-guides/cordis-usage-cheatsheet.md +167 -0
  50. package/docs/reference/cordis-guides/cordis_system_guide_for_coding_agents.md +4666 -0
  51. package/docs/reference/cordis-guides/development-canvas-plugin.md +109 -0
  52. package/docs/reference/cordis-guides/hello-world-plugin-guide.md +517 -0
  53. package/docs/reference/harness/agent-lifecycle.md +93 -0
  54. package/docs/reference/harness/architecture.md +168 -0
  55. package/docs/reference/harness/capability-seams.md +675 -0
  56. package/docs/reference/harness/config-catalog.md +4523 -0
  57. package/docs/reference/harness/cordis-primer.md +47 -0
  58. package/docs/reference/harness/defensive-patterns.md +35 -0
  59. package/docs/reference/harness/event-producer-consumer.md +111 -0
  60. package/docs/reference/harness/glossary.md +47 -0
  61. package/docs/reference/harness/tool-catalog.md +2721 -0
  62. package/docs/reference/harness/tool-execution-pipeline.md +67 -0
  63. package/docs/reference/subsystems/README.md +75 -0
  64. package/docs/reference/subsystems/agent-team.md +233 -0
  65. package/docs/reference/subsystems/approval.md +172 -0
  66. package/docs/reference/subsystems/attachment.md +363 -0
  67. package/docs/reference/subsystems/boot.md +324 -0
  68. package/docs/reference/subsystems/browser-use.md +69 -0
  69. package/docs/reference/subsystems/client-modules.md +186 -0
  70. package/docs/reference/subsystems/client-resources.md +94 -0
  71. package/docs/reference/subsystems/commands.md +225 -0
  72. package/docs/reference/subsystems/compaction.md +286 -0
  73. package/docs/reference/subsystems/computer-use.md +58 -0
  74. package/docs/reference/subsystems/conversation.md +287 -0
  75. package/docs/reference/subsystems/core.md +1107 -0
  76. package/docs/reference/subsystems/credentials.md +497 -0
  77. package/docs/reference/subsystems/deliverables.md +180 -0
  78. package/docs/reference/subsystems/extensions.md +386 -0
  79. package/docs/reference/subsystems/feedback.md +402 -0
  80. package/docs/reference/subsystems/filesystem.md +532 -0
  81. package/docs/reference/subsystems/goal.md +315 -0
  82. package/docs/reference/subsystems/invariants.md +90 -0
  83. package/docs/reference/subsystems/jobs.md +501 -0
  84. package/docs/reference/subsystems/llm-streaming.md +1131 -0
  85. package/docs/reference/subsystems/lsp.md +204 -0
  86. package/docs/reference/subsystems/mcp.md +141 -0
  87. package/docs/reference/subsystems/office-to-pdf.md +89 -0
  88. package/docs/reference/subsystems/otel.md +46 -0
  89. package/docs/reference/subsystems/permission-presets.md +169 -0
  90. package/docs/reference/subsystems/persistence.md +418 -0
  91. package/docs/reference/subsystems/plan.md +89 -0
  92. package/docs/reference/subsystems/product-telemetry.md +81 -0
  93. package/docs/reference/subsystems/ptc-runtime.md +234 -0
  94. package/docs/reference/subsystems/sandbox.md +223 -0
  95. package/docs/reference/subsystems/schedule.md +545 -0
  96. package/docs/reference/subsystems/scope.md +61 -0
  97. package/docs/reference/subsystems/session-projection.md +358 -0
  98. package/docs/reference/subsystems/session-query.md +511 -0
  99. package/docs/reference/subsystems/session-reference.md +226 -0
  100. package/docs/reference/subsystems/session-telemetry.md +214 -0
  101. package/docs/reference/subsystems/session-title.md +206 -0
  102. package/docs/reference/subsystems/session.md +1300 -0
  103. package/docs/reference/subsystems/settings.md +157 -0
  104. package/docs/reference/subsystems/shell.md +316 -0
  105. package/docs/reference/subsystems/sidebar-right.md +160 -0
  106. package/docs/reference/subsystems/skills.md +354 -0
  107. package/docs/reference/subsystems/slots.md +201 -0
  108. package/docs/reference/subsystems/spill.md +126 -0
  109. package/docs/reference/subsystems/ssh.md +137 -0
  110. package/docs/reference/subsystems/storage.md +262 -0
  111. package/docs/reference/subsystems/subagent.md +762 -0
  112. package/docs/reference/subsystems/subprocess.md +323 -0
  113. package/docs/reference/subsystems/system-prompt.md +226 -0
  114. package/docs/reference/subsystems/terminal.md +186 -0
  115. package/docs/reference/subsystems/todo.md +34 -0
  116. package/docs/reference/subsystems/token-meter.md +108 -0
  117. package/docs/reference/subsystems/tools.md +749 -0
  118. package/docs/reference/subsystems/typert.md +489 -0
  119. package/docs/reference/subsystems/user-questions.md +309 -0
  120. package/docs/reference/subsystems/voice-input.md +166 -0
  121. package/docs/reference/subsystems/web-client.md +102 -0
  122. package/docs/reference/subsystems/web-server.md +228 -0
  123. package/docs/reference/subsystems/web.md +208 -0
  124. package/docs/reference/subsystems/webhook.md +72 -0
  125. package/docs/reference/subsystems/workflow.md +280 -0
  126. package/docs/reference/subsystems/workspace.md +661 -0
  127. package/docs/start-here/blueprints.md +33 -0
  128. package/docs/start-here/this-runtime.md +84 -0
  129. package/docs/start-here/troubleshooting.md +29 -0
  130. package/docs/start-here/trust-and-safety.md +39 -0
  131. package/docs/start-here/verify-before-done.md +46 -0
  132. package/example-plugins/README.md +45 -0
  133. package/example-plugins/packages/agent-preset-reviewer/agent.cordis.yml +18 -0
  134. package/example-plugins/packages/agent-preset-reviewer/preset.yml +3 -0
  135. package/example-plugins/packages/capability-swap-consumer/cordis.patch.yml +3 -0
  136. package/example-plugins/packages/capability-swap-consumer/index.js +14 -0
  137. package/example-plugins/packages/capability-swap-consumer/package.json +25 -0
  138. package/example-plugins/packages/capability-swap-provider-loud/cordis.patch.yml +3 -0
  139. package/example-plugins/packages/capability-swap-provider-loud/index.js +20 -0
  140. package/example-plugins/packages/capability-swap-provider-loud/package.json +25 -0
  141. package/example-plugins/packages/capability-swap-provider-quiet/cordis.patch.yml +3 -0
  142. package/example-plugins/packages/capability-swap-provider-quiet/index.js +20 -0
  143. package/example-plugins/packages/capability-swap-provider-quiet/package.json +25 -0
  144. package/example-plugins/packages/chat-command-basic/cordis.patch.yml +3 -0
  145. package/example-plugins/packages/chat-command-basic/index.js +26 -0
  146. package/example-plugins/packages/chat-command-basic/package.json +25 -0
  147. package/example-plugins/packages/client-chat-message-action/client.js +46 -0
  148. package/example-plugins/packages/client-chat-message-action/cordis.patch.yml +3 -0
  149. package/example-plugins/packages/client-chat-message-action/index.js +9 -0
  150. package/example-plugins/packages/client-chat-message-action/package.json +31 -0
  151. package/example-plugins/packages/client-slot-header-action/client.js +57 -0
  152. package/example-plugins/packages/client-slot-header-action/cordis.patch.yml +3 -0
  153. package/example-plugins/packages/client-slot-header-action/index.js +13 -0
  154. package/example-plugins/packages/client-slot-header-action/package.json +31 -0
  155. package/example-plugins/packages/client-slot-sidebar-tab/client.js +57 -0
  156. package/example-plugins/packages/client-slot-sidebar-tab/cordis.patch.yml +3 -0
  157. package/example-plugins/packages/client-slot-sidebar-tab/index.js +9 -0
  158. package/example-plugins/packages/client-slot-sidebar-tab/package.json +32 -0
  159. package/example-plugins/packages/client-theme-override/client.js +52 -0
  160. package/example-plugins/packages/client-theme-override/cordis.patch.yml +3 -0
  161. package/example-plugins/packages/client-theme-override/index.js +9 -0
  162. package/example-plugins/packages/client-theme-override/package.json +30 -0
  163. package/example-plugins/packages/client-tool-view/client.js +47 -0
  164. package/example-plugins/packages/client-tool-view/cordis.patch.yml +3 -0
  165. package/example-plugins/packages/client-tool-view/index.js +24 -0
  166. package/example-plugins/packages/client-tool-view/package.json +34 -0
  167. package/example-plugins/packages/client-ui-components/client.js +77 -0
  168. package/example-plugins/packages/client-ui-components/cordis.patch.yml +3 -0
  169. package/example-plugins/packages/client-ui-components/index.js +9 -0
  170. package/example-plugins/packages/client-ui-components/package.json +31 -0
  171. package/example-plugins/packages/client-ui-library/client.js +715 -0
  172. package/example-plugins/packages/client-ui-library/cordis.patch.yml +3 -0
  173. package/example-plugins/packages/client-ui-library/index.js +9 -0
  174. package/example-plugins/packages/client-ui-library/package.json +37 -0
  175. package/example-plugins/packages/client-workspace-tab/client.js +72 -0
  176. package/example-plugins/packages/client-workspace-tab/cordis.patch.yml +3 -0
  177. package/example-plugins/packages/client-workspace-tab/index.js +9 -0
  178. package/example-plugins/packages/client-workspace-tab/package.json +30 -0
  179. package/example-plugins/packages/config-schema-basic/cordis.patch.yml +3 -0
  180. package/example-plugins/packages/config-schema-basic/index.js +19 -0
  181. package/example-plugins/packages/config-schema-basic/package.json +25 -0
  182. package/example-plugins/packages/desktop-main-profile-info/cordis.patch.yml +3 -0
  183. package/example-plugins/packages/desktop-main-profile-info/index.js +22 -0
  184. package/example-plugins/packages/desktop-main-profile-info/package.json +25 -0
  185. package/example-plugins/packages/event-hook-basic/cordis.patch.yml +3 -0
  186. package/example-plugins/packages/event-hook-basic/index.js +17 -0
  187. package/example-plugins/packages/event-hook-basic/package.json +22 -0
  188. package/example-plugins/packages/generated-capability-template/cordis.patch.yml +3 -0
  189. package/example-plugins/packages/generated-capability-template/index.js +16 -0
  190. package/example-plugins/packages/generated-capability-template/package.json +42 -0
  191. package/example-plugins/packages/host-route-basic/cordis.patch.yml +3 -0
  192. package/example-plugins/packages/host-route-basic/index.js +20 -0
  193. package/example-plugins/packages/host-route-basic/package.json +29 -0
  194. package/example-plugins/packages/lifecycle-function-basic/cordis.patch.yml +3 -0
  195. package/example-plugins/packages/lifecycle-function-basic/index.js +12 -0
  196. package/example-plugins/packages/lifecycle-function-basic/package.json +15 -0
  197. package/example-plugins/packages/lifecycle-function-hot-shim/cordis.patch.yml +3 -0
  198. package/example-plugins/packages/lifecycle-function-hot-shim/impl.js +5 -0
  199. package/example-plugins/packages/lifecycle-function-hot-shim/index.js +18 -0
  200. package/example-plugins/packages/lifecycle-function-hot-shim/package.json +23 -0
  201. package/example-plugins/packages/lifecycle-hooks-observer/cordis.patch.yml +3 -0
  202. package/example-plugins/packages/lifecycle-hooks-observer/index.js +23 -0
  203. package/example-plugins/packages/lifecycle-hooks-observer/package.json +22 -0
  204. package/example-plugins/packages/llm-adapter-echo/cordis.patch.yml +3 -0
  205. package/example-plugins/packages/llm-adapter-echo/index.js +42 -0
  206. package/example-plugins/packages/llm-adapter-echo/package.json +25 -0
  207. package/example-plugins/packages/prompt-assemble-hook/cordis.patch.yml +3 -0
  208. package/example-plugins/packages/prompt-assemble-hook/index.js +22 -0
  209. package/example-plugins/packages/prompt-assemble-hook/package.json +22 -0
  210. package/example-plugins/packages/prompt-contribution-basic/cordis.patch.yml +3 -0
  211. package/example-plugins/packages/prompt-contribution-basic/index.js +18 -0
  212. package/example-plugins/packages/prompt-contribution-basic/package.json +22 -0
  213. package/example-plugins/packages/service-consumer-greeter/cordis.patch.yml +3 -0
  214. package/example-plugins/packages/service-consumer-greeter/index.js +14 -0
  215. package/example-plugins/packages/service-consumer-greeter/package.json +22 -0
  216. package/example-plugins/packages/service-provider-greeter/cordis.patch.yml +3 -0
  217. package/example-plugins/packages/service-provider-greeter/index.js +22 -0
  218. package/example-plugins/packages/service-provider-greeter/package.json +25 -0
  219. package/example-plugins/packages/settings-section-basic/cordis.patch.yml +3 -0
  220. package/example-plugins/packages/settings-section-basic/index.js +34 -0
  221. package/example-plugins/packages/settings-section-basic/package.json +26 -0
  222. package/example-plugins/packages/skill-provider-basic/cordis.patch.yml +3 -0
  223. package/example-plugins/packages/skill-provider-basic/index.js +31 -0
  224. package/example-plugins/packages/skill-provider-basic/package.json +22 -0
  225. package/example-plugins/packages/state-host-store/client.js +57 -0
  226. package/example-plugins/packages/state-host-store/cordis.patch.yml +3 -0
  227. package/example-plugins/packages/state-host-store/index.js +90 -0
  228. package/example-plugins/packages/state-host-store/package.json +31 -0
  229. package/example-plugins/packages/state-workspace-file/cordis.patch.yml +3 -0
  230. package/example-plugins/packages/state-workspace-file/index.js +52 -0
  231. package/example-plugins/packages/state-workspace-file/package.json +25 -0
  232. package/example-plugins/packages/tool-basic/cordis.patch.yml +3 -0
  233. package/example-plugins/packages/tool-basic/index.js +25 -0
  234. package/example-plugins/packages/tool-basic/package.json +25 -0
  235. package/example-plugins/packages/tool-policy-hook/cordis.patch.yml +3 -0
  236. package/example-plugins/packages/tool-policy-hook/index.js +28 -0
  237. package/example-plugins/packages/tool-policy-hook/package.json +25 -0
  238. package/example-plugins/packages/tui-command-basic/cordis.patch.yml +3 -0
  239. package/example-plugins/packages/tui-command-basic/index.js +24 -0
  240. package/example-plugins/packages/tui-command-basic/package.json +22 -0
  241. package/example-plugins/packages/tui-overlay-themed/cordis.patch.yml +3 -0
  242. package/example-plugins/packages/tui-overlay-themed/index.js +65 -0
  243. package/example-plugins/packages/tui-overlay-themed/package.json +25 -0
  244. package/example-plugins/packages/tui-ui-library/cordis.patch.yml +3 -0
  245. package/example-plugins/packages/tui-ui-library/index.js +73 -0
  246. package/example-plugins/packages/tui-ui-library/package.json +29 -0
  247. package/example-plugins/packages/web-page-branding/cordis.patch.yml +3 -0
  248. package/example-plugins/packages/web-page-branding/index.js +31 -0
  249. package/example-plugins/packages/web-page-branding/package.json +22 -0
  250. package/example-plugins/scenarios.json +11 -0
  251. package/index.js +384 -0
  252. package/lib/blend-apply.js +107 -0
  253. package/lib/blend-capture.js +249 -0
  254. package/lib/blend-ledger.js +76 -0
  255. package/lib/contract.js +5 -0
  256. package/lib/install.js +516 -0
  257. package/lib/lookup.js +67 -0
  258. package/lib/manifest.js +56 -0
  259. package/lib/pack-root.js +22 -0
  260. package/lib/provenance.js +110 -0
  261. package/lib/publish.js +64 -0
  262. package/lib/reconcile.js +83 -0
  263. package/lib/router.js +55 -0
  264. package/lib/scopes.js +82 -0
  265. package/lib/skills.js +54 -0
  266. package/lib/stage.js +157 -0
  267. package/lib/verify.js +77 -0
  268. package/package.json +56 -3
  269. package/scripts/lib/indexes.mjs +45 -0
  270. package/scripts/lib/manifest.mjs +127 -0
  271. package/scripts/lib/maps.mjs +482 -0
  272. package/skills/acryl-add-provider-or-capability/SKILL.md +12 -0
  273. package/skills/acryl-add-ui/SKILL.md +18 -0
  274. package/skills/acryl-build-plugin/SKILL.md +21 -0
  275. package/skills/acryl-change-plugin/SKILL.md +16 -0
  276. package/skills/acryl-desktop-shell/SKILL.md +12 -0
  277. package/skills/acryl-diagnose-plugin/SKILL.md +10 -0
  278. package/skills/acryl-fix-plugin/SKILL.md +12 -0
  279. package/skills/acryl-improve-ui/SKILL.md +10 -0
  280. package/skills/acryl-remove-plugin/SKILL.md +11 -0
  281. package/skills/acryl-restyle-ui/SKILL.md +14 -0
  282. package/skills/acryl-share-plugin/SKILL.md +23 -0
  283. package/skills/acryl-tui-ui/SKILL.md +12 -0
  284. package/README.md +0 -3
@@ -0,0 +1,228 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/web-server.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # HTTP Server
4
+
5
+ English | [中文](web-server.zh.md)
6
+
7
+ [dsh-host-webserver](../../packages/host/webserver) is the browser HTTP carrier for the GUI host: a single `node:http` plugin providing `ctx.webServer`, a named-route registry, optional gzip response compression, index.html transform callbacks, and one fallback handler that a plugin may claim. It is not part of the agent loop and not a capability seam; it knows no harness concepts, and another plugin registers every feature route, including the `/api` bridge, plugin bundles, and the HMR event stream ([layering note](../../.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md)). It serves browsers only: Electron loads the built files over `file://` and sends fetch requests through an IPC bridge instead of this server.
8
+
9
+ Source: [`packages/host/webserver/src/index.ts`](../../packages/host/webserver/src/index.ts)
10
+
11
+ ## Routes
12
+
13
+ ```ts type-equiv
14
+ /** Route match kind: 'exact' matches the pathname verbatim; 'prefix' p matches p and p/<anything>. */
15
+ type WebRouteKind = 'exact' | 'prefix'
16
+ ```
17
+
18
+ ```ts type-equiv
19
+ /** One named route registration. */
20
+ interface WebRoute {
21
+ kind: WebRouteKind
22
+ /** Absolute pathname, no trailing slash. */
23
+ path: string
24
+ /** Owns the full response lifecycle (may hold the response open, e.g. SSE). */
25
+ handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
26
+ }
27
+ ```
28
+
29
+ Match order is fixed: exact table first, then longest matching prefix, then the registered fallback. Registration order carries no request-facing semantics - named routes are composed to be disjoint, and the fallback seat answers anything no named route claims; one owner only, a second registration throws. The shipped Web composition claims the seat with [`dsh-host-frontend-static`](../../packages/host/frontend-static/src/index.ts), the SPA dist server with locked semantics: Connection authenticates the dist root and configured index before their HTML is read; non-index assets remain public; non-GET/HEAD is 405, traversal outside the dist root is 403, existing files are served directly, absent or non-file targets are empty 404 responses, and unknown extensions ship as octet-stream.
30
+
31
+ ## Config
32
+
33
+ ```ts type-equiv
34
+ /** Web server listen and response-compression config. */
35
+ interface Config {
36
+ /** Listen host; the two supported values are loopback and all-interfaces. */
37
+ host: '127.0.0.1' | '0.0.0.0'
38
+ /** Listen port; zero requests an OS-assigned port. */
39
+ port: number
40
+ /** Response compression for socket-backed HTTP requests. @default 'none' */
41
+ compression?: 'none' | 'gzip'
42
+ /** Gzip DEFLATE level from 0 through 9. @default 1 */
43
+ compressionLevel?: number
44
+ /** Minimum known response length eligible for gzip; unknown-length streams are eligible. @default 1024 */
45
+ compressionThresholdBytes?: number
46
+ }
47
+ ```
48
+
49
+ `host` accepts only `127.0.0.1` (default posture) and `0.0.0.0` (deliberate network exposure). The carrier itself owns no TLS, authentication, or Origin policy, so a non-loopback bind exposes the server unless the composition supplies those controls. `compression` defaults to `none`; the shipped Web bundle selects gzip level 1 with a 1024-byte threshold. The shipped `dsh web` command selects loopback and rejects `--host 0.0.0.0`; its Connection plugin supplies Host/Origin checks plus browser-session authentication for every Host API route and stream. Other compositions own their bind and route-authentication policy. The dist location is an assembly fact of the frontend plugin that claims the seat.
50
+
51
+ ## The service
52
+
53
+ `WebServer` (`ctx.webServer`) listens immediately on activation; a listen failure (EADDRINUSE…) rejects initialization, and the boot process reports the failed fiber. `register(route)` adds one named route and returns its disposer; a duplicate `(kind, path)` throws because route patterns are a composition-level contract and a collision is a misconfiguration. Gzip wraps eligible socket-backed responses inside the server, so route handlers retain direct `ServerResponse` ownership and no response-writing API is added to the service. Existing content encodings, `Cache-Control: no-transform`, ranges, SSE, ZIP, and the packaged `.gz` Worker image remain identity responses. `collectIndexInjections()` gathers structured `IndexInjection` rows over one `webserver/index-inject` emit, and `renderIndex(html)` renders them into successful root and configured index responses before applying the raw `tapIndex(transform)` escape-hatch transforms in registration order; [dsh-client-modules](../../packages/client/modules) answers the event with the boot manifest rows. `port` reads the listening port, including the port assigned by the OS when `config.port` is 0.
54
+
55
+ A request whose handling throws (a malformed %-escape hitting `decodeURIComponent`, a client dropping mid-body) is logged as a warning and answered 400 - or the socket destroyed when headers are already out - never a process exit. Disposal pairs `close()` with `closeAllConnections()` because a handler may hold its response open (SSE) and such connections never end on their own; without the force-close, teardown would hang. The package never prints: the URL line belongs to the shell. Per-package operational detail, including the dev-mode bundle watch pipeline, stays in the [README](../../packages/host/webserver/README.md).
56
+
57
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
58
+
59
+ <a id="cordis-surface"></a>
60
+
61
+ ## Cordis API
62
+
63
+ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) - the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
64
+
65
+ <a id="ctxconnection--hostconnectionhandle"></a>
66
+
67
+ ### `ctx.connection` - `HostConnectionHandle`
68
+
69
+ Host `ctx.connection` members consumed by transport-independent adapters.
70
+
71
+ ```ts cordis-catalog
72
+ /**
73
+ * Compose exact Fetch routes and the shared-channel RPC interceptor.
74
+ * @param channel - shared channel mounted by Connection.
75
+ * @returns Fetch handler for trusted, authenticated requests.
76
+ */
77
+ createSharedFetchHandler(channel: '/api'): ConnectionFetchHandler
78
+
79
+ /**
80
+ * Apply Connection's Host/Origin checks and browser authentication to
81
+ * another Web route.
82
+ * @param request - request headers from the HTTP or upgrade request.
83
+ * @returns rejection status, or undefined when the route may accept the request.
84
+ */
85
+ requestRejection(request: ConnectionTrustRequest): ConnectionRequestRejection
86
+
87
+ /**
88
+ * Admit one request: it passes {@link requestRejection} and speaks for the
89
+ * operator, or it is refused with that status.
90
+ * @param request - request headers from the HTTP or upgrade request.
91
+ * @returns the operator Peer, or the rejection status.
92
+ */
93
+ admit(request: ConnectionTrustRequest): PeerAdmission
94
+
95
+ /**
96
+ * Authenticate one frontend index request, owning a token redirect or 401.
97
+ * @param request - root or configured-index HTTP request.
98
+ * @param response - response owned when the result is false.
99
+ * @returns true only when the frontend may serve index.html.
100
+ */
101
+ authorizeIndex(request: ConnectionIndexRequest, response: ConnectionIndexResponse): boolean
102
+
103
+ /**
104
+ * Add the fresh process token to an ordinary Web application URL.
105
+ * @param baseUrl - clean application URL whose authority and mount are preserved.
106
+ * @returns tokenized URL for initial login; a mount proxy strips its prefix before {@link authorizeIndex}.
107
+ */
108
+ authenticatedUrl(baseUrl: string): string
109
+ ```
110
+
111
+ Source: [`packages/client/connection/src/rpc.ts`](../../packages/client/connection/src/rpc.ts)
112
+
113
+ <a id="ctxwebserver--webserver"></a>
114
+
115
+ ### `ctx.webServer` - `WebServer`
116
+
117
+ The browser HTTP carrier service. Activation listens immediately. Route registration order does not affect requests because configured named routes must be distinct, and the fallback handler answers anything not yet claimed during startup with 404 until its owner registers. A listen failure rejects initialization, and the boot process reports the failed fiber.
118
+
119
+ ```ts cordis-catalog
120
+ /**
121
+ * Register a named route. Duplicate (kind, path) throws - route patterns are
122
+ * a composition-level contract, so a collision is a misconfiguration.
123
+ * @param route - kind, path, and the owning handler.
124
+ * @returns the disposer removing the route.
125
+ */
126
+ register(route: WebRoute): () => void
127
+
128
+ /**
129
+ * Register an exact-path HTTP upgrade route. Duplicate paths throw because
130
+ * one socket can have only one protocol owner.
131
+ * @param route - pathname and handler owning negotiation plus socket use.
132
+ * @returns the disposer removing the route.
133
+ */
134
+ registerUpgrade(route: WebUpgradeRoute): () => void
135
+
136
+ /**
137
+ * Claim the fallback seat: the handler answering every request no named
138
+ * route matches (the SPA dist server in the shipped Web composition). One
139
+ * owner only - a second registration throws, because two fallbacks cannot
140
+ * compose.
141
+ * @param handler - owns the full response lifecycle of unmatched requests.
142
+ * @returns the disposer releasing the seat.
143
+ */
144
+ registerFallback(handler: WebRoute['handler']): () => void
145
+
146
+ /**
147
+ * Register a raw-HTML index transform, the escape hatch for markup no
148
+ * {@link IndexInjection} row expresses: {@link renderIndex} applies taps in
149
+ * registration order after rendering the structured rows.
150
+ * @param transform - pure html-to-html function.
151
+ * @returns the disposer removing the transform.
152
+ */
153
+ tapIndex(transform: (html: string) => string): () => void
154
+
155
+ /**
156
+ * Run an index.html body through the registered taps in registration order
157
+ * - called by the fallback owner on every index response it renders.
158
+ * @param html - the raw index.html body.
159
+ * @returns the transformed body.
160
+ */
161
+ applyIndexTaps(html: string): string
162
+
163
+ /**
164
+ * Gather the structured injection table: one `webserver/index-inject` emit,
165
+ * every subscriber pushes its current rows. Fresh per call, so subscribers
166
+ * read live state (module graph, theme preference) at emit time.
167
+ * @returns rows in subscriber activation order.
168
+ */
169
+ collectIndexInjections(): IndexInjection[]
170
+
171
+ /**
172
+ * Render one index.html body: the structured injection table first, then
173
+ * the raw `tapIndex` transforms over the result.
174
+ * @param html - the raw index.html body.
175
+ * @returns the transformed body.
176
+ */
177
+ renderIndex(html: string): string
178
+ ```
179
+
180
+ Source: [`packages/host/webserver/src/index.ts`](../../packages/host/webserver/src/index.ts)
181
+
182
+ <a id="connection-events"></a>
183
+
184
+ ### `connection/*` events
185
+
186
+ <a id="connectionrequest--waterfall"></a>
187
+
188
+ #### `connection/request` - waterfall
189
+
190
+ Admit or wrap an authenticated shared API request, including body transfer. Existing requests continue when a listener refuses subsequent requests.
191
+
192
+ ```ts cordis-catalog
193
+ /**
194
+ * Admit or wrap an authenticated shared API request, including body transfer.
195
+ * Existing requests continue when a listener refuses subsequent requests.
196
+ * @param request - Authenticated incoming HTTP request.
197
+ * @param response - Response owned until the delegated bridge settles.
198
+ * @param next - Delegate to the next listener or the shared API bridge.
199
+ * @mode waterfall
200
+ */
201
+ 'connection/request'(request: IncomingMessage, response: ServerResponse, next: () => Promise<void>): Promise<void>
202
+ ```
203
+
204
+ Source: [`packages/client/connection/src/index.ts`](../../packages/client/connection/src/index.ts)
205
+
206
+ <a id="webserver-events"></a>
207
+
208
+ ### `webserver/*` events
209
+
210
+ <a id="webserverindex-inject--emit"></a>
211
+
212
+ #### `webserver/index-inject` - emit
213
+
214
+ Collect the structured index injection table. Emitted on every index render and every worker boot-payload request; listeners push their current rows, so a row's data is read fresh at emit time.
215
+
216
+ ```ts cordis-catalog
217
+ /**
218
+ * Collect the structured index injection table. Emitted on every index
219
+ * render and every worker boot-payload request; listeners push their
220
+ * current rows, so a row's data is read fresh at emit time.
221
+ * @param table - Mutable row table; listeners append in activation order.
222
+ * @mode emit
223
+ */
224
+ 'webserver/index-inject'(table: IndexInjection[]): void
225
+ ```
226
+
227
+ Source: [`packages/host/webserver/src/index.ts`](../../packages/host/webserver/src/index.ts)
228
+ <!-- END GENERATED cordis-surface -->
@@ -0,0 +1,208 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/web.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Web Access
4
+
5
+ English | [中文](web.zh.md)
6
+
7
+ The web access seam - a [capability seam](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) that spans **two operations** (search and fetch) on one `ctx.web` service, split across packages: Service Definition ([dsh-web](../../packages/web/web), `ctx.web` + the provider registries), Service Providers ([dsh-web-search-exa](../../packages/web/web-search-exa), [dsh-web-search-perplexity](../../packages/web/web-search-perplexity), [dsh-web-search-deepseek](../../packages/web/web-search-deepseek), [dsh-web-fetch-http](../../packages/web/web-fetch-http)), and Consumer ([dsh-tool-web](../../packages/web/tool-web), the `web_search`/`web_fetch` tool schemas). Web is **one optional capability**, not part of the agent-loop spine - so its vocabulary lives here, not in [core.md](core.md). A search-provider swap does not change how the model asks for a query, and a fetch-provider swap does not change how the model asks for a URL.
8
+
9
+ Source: [`packages/web/web/src/types.ts`](../../packages/web/web/src/types.ts)
10
+
11
+ ## Why one capability has two operations
12
+
13
+ Search and fetch share no request schema and no business logic, but they are deliberately one `ctx.web` middle layer: one provider-selection policy owner, one abort/error vocabulary, and one product-facing "how this harness reaches the web" configuration API. The cost is the parallel `searchX`/`fetchX` method pairs on the service; that parallelism is intentional, not a missed extraction. Providers register **capabilities** (a `WebSearchProvider` or `WebFetchProvider`), not tools; the model-facing names, schemas, prompt guidance, and presentation all live in the single `dsh-tool-web` consumer.
14
+
15
+ ## Search request and result
16
+
17
+ Each seam request carries exactly one `query`. The `dsh-tool-web` consumer accepts a required `queries` array and fans it out into separate seam requests; a one-item array performs one search. `maxResults` is a consumer-owned bound (`dsh-tool-web`'s `searchMaxResults` config, default `8`) passed through the seam and enforced on the way back - if a provider over-returns, the seam truncates `sources[]` and sets `truncated`.
18
+
19
+ ```ts type-equiv
20
+ /**
21
+ * What one search-capable backend is asked to search. Each request carries one
22
+ * query; a consumer may issue several requests. `maxResults` is a
23
+ * `dsh-tool-web`-layer bound passed through unchanged and enforced on the way
24
+ * back by the seam (see {@link WebSearchResult}).
25
+ */
26
+ interface WebSearchRequest {
27
+ readonly query: string
28
+ /**
29
+ * Upper bound on returned sources; the seam truncates to it. Omitted = no
30
+ * bound. `dsh-tool-web` always sets it. A provider whose API supports a
31
+ * result-count control (Exa's `numResults`) should apply it at the request
32
+ * layer as a cost/latency optimization; the seam enforces the bound
33
+ * regardless.
34
+ */
35
+ readonly maxResults?: number
36
+ }
37
+ ```
38
+
39
+ ```ts type-equiv
40
+ /**
41
+ * Normalized search outcome. `content` is optional provider-generated answer
42
+ * text or summary (Exa and DeepSeek return none; Perplexity returns a
43
+ * generated answer).
44
+ * `sources[]` is the portable citation shape. `truncated` is set by the seam
45
+ * when it cut `sources[]` down to `maxResults`.
46
+ */
47
+ interface WebSearchResult {
48
+ /** Optional provider-generated answer text, search context, or summary. */
49
+ readonly content?: string
50
+ /** Citeable sources, already truncated to the request's `maxResults`. */
51
+ readonly sources: readonly WebSearchSource[]
52
+ /** True when the seam dropped sources to honor `maxResults`. */
53
+ readonly truncated: boolean
54
+ }
55
+ ```
56
+
57
+ ```ts type-equiv
58
+ /**
59
+ * One citeable source. A source always has a URL; `title`, `snippet`, and
60
+ * `publishedAt` are optional because not every provider returns them - forcing
61
+ * adapters to invent them would make the seam lie (Perplexity citations may be
62
+ * URL-only). `dsh-tool-web` renders `title ?? hostname(url)` for display.
63
+ */
64
+ interface WebSearchSource {
65
+ readonly url: string
66
+ readonly title?: string
67
+ readonly snippet?: string
68
+ /** Publication/crawl timestamp as a provider-supplied ISO-8601 string. */
69
+ readonly publishedAt?: string
70
+ }
71
+ ```
72
+
73
+ ## Fetch request and result
74
+
75
+ ```ts type-equiv
76
+ /**
77
+ * What one fetch-capable backend is asked to retrieve. The request deliberately
78
+ * omits timeout, format, prompt, and extraction controls: cancellation is a
79
+ * direct execution argument, while presentation and higher-level LLM concerns
80
+ * belong outside safe retrieval.
81
+ */
82
+ interface WebFetchRequest {
83
+ readonly url: string
84
+ }
85
+ ```
86
+
87
+ HTTP status is part of the fetched resource state, not automatically a failure: a successful network fetch of a `404`/`500` returns a `WebFetchResult` with the status code and a bounded decoded body. `url` is the final URL after allowed redirects. `WebError` is reserved for failures to safely retrieve or represent the resource.
88
+
89
+ ```ts type-equiv
90
+ /**
91
+ * Normalized fetch outcome. A successful network fetch of a non-2xx response is
92
+ * a result, not an error: the status code is part of the fetched resource
93
+ * state. {@link WebError} is reserved for failures to safely retrieve or
94
+ * represent the resource.
95
+ */
96
+ interface WebFetchResult {
97
+ /** The final URL after allowed redirects (the request URL is in the request). */
98
+ readonly url: string
99
+ /** HTTP status code of the fetched response. */
100
+ readonly statusCode: number
101
+ /** Decoded body, classified by content kind. */
102
+ readonly body: WebFetchBody
103
+ /** True when the provider capped the decoded body. */
104
+ readonly truncated: boolean
105
+ }
106
+ ```
107
+
108
+ ```ts type-equiv
109
+ /**
110
+ * The decoded body of a fetched resource. A CLOSED discriminated union owned by
111
+ * `dsh-web`: the provider decodes the kind and `dsh-tool-web` renders it, so a
112
+ * new kind is a coordinated change across known packages, not a plugin
113
+ * extension. Consumers `switch` on `kind` ending in `default: assertNever(...)`
114
+ * so adding a kind breaks compilation at every consumer until handled. Each arm
115
+ * stays its own object literal even where fields coincide, so an arm can gain
116
+ * fields the others lack.
117
+ */
118
+ type WebFetchBody =
119
+ | { readonly kind: 'html'; readonly content: string }
120
+ | { readonly kind: 'text'; readonly content: string }
121
+ ```
122
+
123
+ ## Provider availability
124
+
125
+ A provider's `available(): boolean` is a cheap LOCAL check (credential presence, parseable config) and **must not make network calls**. It is an input to execution-time selection, not a health system: `search()`/`fetch()` read it to pick a usable provider, and a selection failure surfaces as the structured `WebError` the caller routes on - which carries the branchable detail (the missing id or ambiguous candidate set) in its code and message.
126
+
127
+ Selection never depends on registration, config, or HMR order: a capability has an explicit provider id (config `searchProvider`/`fetchProvider`, or the matching env var feeding the same field), or auto-selects when exactly one usable provider is registered; multiple usable providers with no configured id is `WEB_PROVIDER_AMBIGUOUS`, not first-wins.
128
+
129
+ ## Fetch network policy
130
+
131
+ The shipped Cordis, Code, and Standard presets expose `web_fetch` in every sandbox and approval mode without per-call confirmation. File sandbox presets do not govern Web network access. A deployment that needs confirmation must add a `tools/pre-execute` policy or disable fetch.
132
+
133
+ The HTTP provider resolves each actual request, rejects non-public answers including private IPv4 reached through the active DNS64 prefix, pins the validated address set, and repeats enforcement for each same-origin redirect. A cross-origin redirect requires a new tool call and fresh public-address validation. These checks prevent SSRF access to non-public destinations but do not stop a model from sending data to a public URL.
134
+
135
+ ## Errors
136
+
137
+ `WebError extends HarnessError` ([core.md](core.md) error taxonomy) with a `code: string` (open, like every other seam's error - `LlmError`, `SubagentError`), not a closed union: a provider may raise its own codes without editing `dsh-web`, and consumers must tolerate an unknown code. The codes split by owner. Seam-neutral codes are raised by the shared `WebRuntime` contract: `WEB_PROVIDER_UNAVAILABLE`, `WEB_PROVIDER_CONFIGURED_MISSING`, `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`, `WEB_PROVIDER_AMBIGUOUS`, `WEB_DUPLICATE_PROVIDER` (a registration-time programming error, the analogue of `LlmRuntime`'s `DUPLICATE_ADAPTER`), `WEB_ABORTED`, and `WEB_PROVIDER_ERROR` (the catch-all for a provider's own failure surfaced through the seam, including network/transport failure - DNS, connection refused, TLS). Fetch-transport codes are owned by the `dsh-web-fetch-http` implementation and a different fetch backend need not raise them: `WEB_INVALID_URL`, `WEB_BLOCKED_URL`, `WEB_REDIRECT_BLOCKED`, `WEB_FETCH_TOO_LARGE`, `WEB_FETCH_TIMEOUT`, `WEB_UNSUPPORTED_CONTENT_TYPE`.
138
+
139
+ ## The service
140
+
141
+ `WebRuntime` registers search and fetch providers, rejects duplicate ids with `WEB_DUPLICATE_PROVIDER`, and resolves providers at execution time with structured selection errors. The local fetch backend accepts only HTTP(S), rejects credentials, resolves each hostname once, rejects any answer set containing a non-public IPv4 or IPv6 destination or an active-prefix NAT64 translation to non-public IPv4, pins the request connection to the validated addresses, repeats those checks for every same-origin redirect hop, caps redirects, bytes, characters, and time, and decodes the body; the tool owns presentation.
142
+
143
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
144
+
145
+ <a id="cordis-surface"></a>
146
+
147
+ ## Cordis API
148
+
149
+ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) - the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
150
+
151
+ <a id="ctxweb--webruntime"></a>
152
+
153
+ ### `ctx.web` - `WebRuntime`
154
+
155
+ The web access service. Registered as `ctx.web` (one instance per context).
156
+
157
+ Selection semantics (resolved at execution time, never order-dependent):
158
+
159
+ - A configured id that is registered and `available()` → that provider.
160
+ - A configured id not registered → `WEB_PROVIDER_CONFIGURED_MISSING`.
161
+ - A configured id registered but unavailable → `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`.
162
+ - No id configured, exactly one registered usable provider → that provider.
163
+ - No id configured, multiple usable providers → `WEB_PROVIDER_AMBIGUOUS`.
164
+ - No id configured, no usable provider → `WEB_PROVIDER_UNAVAILABLE`.
165
+
166
+ ```ts cordis-catalog
167
+ /**
168
+ * Register a search provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
169
+ * if its id is already registered for search. Returns a disposer; disposed
170
+ * with the calling fiber.
171
+ * @param provider - the provider; its `id` is the registry key.
172
+ * @returns the disposer that unregisters the provider.
173
+ */
174
+ registerSearchProvider(provider: WebSearchProvider): () => void
175
+
176
+ /**
177
+ * Register a fetch provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
178
+ * if its id is already registered for fetch. Returns a disposer; disposed
179
+ * with the calling fiber.
180
+ * @param provider - the provider; its `id` is the registry key.
181
+ * @returns the disposer that unregisters the provider.
182
+ */
183
+ registerFetchProvider(provider: WebFetchProvider): () => void
184
+
185
+ /**
186
+ * Run one search through the selected provider. Resolves the provider at call
187
+ * time with the selection rules above; throws {@link WebError} when the
188
+ * capability cannot run. The seam enforces `request.maxResults` on the result:
189
+ * if the provider over-returns, `sources[]` is truncated and `truncated` set.
190
+ * @param request - the query and optional result limit.
191
+ * @param signal - optional cancellation signal forwarded to the provider.
192
+ * @returns the provider's results, capped to `request.maxResults`.
193
+ */
194
+ async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>
195
+
196
+ /**
197
+ * Retrieve one URL through the selected provider. Resolves the provider at
198
+ * call time with the selection rules above; throws {@link WebError} when the
199
+ * capability cannot run. A non-2xx response is a result, not a throw.
200
+ * @param request - the URL plus retrieval options.
201
+ * @param signal - optional cancellation signal forwarded to the provider.
202
+ * @returns the retrieval outcome; non-2xx responses resolve descriptively.
203
+ */
204
+ async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>
205
+ ```
206
+
207
+ Source: [`packages/web/web/src/index.ts`](../../packages/web/web/src/index.ts)
208
+ <!-- END GENERATED cordis-surface -->
@@ -0,0 +1,72 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/webhook.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Webhook runtime
4
+
5
+ English | [中文](webhook.zh.md)
6
+
7
+ The Webhook subsystem turns authenticated external deliveries into optional ordinary root Sessions. Provider adapters own authentication and generic JSON intake; trusted programmatic rules own conditions and external calls; `ctx.webhookRuntime` owns callback lifetime plus Workspace-backed Session creation. The [implemented decision](../../.agents/notes/implemented/feature/2026-08-22-fire-and-forget-webhook-sessions.md) records why the runtime keeps no delivery or completion state.
8
+
9
+ ## Shared values
10
+
11
+ `WebhookRuleId`, `WebhookSourceId`, and `WebhookDeliveryId` are opaque strings. A delivery id records the provider's identifier only: the runtime neither stores nor deduplicates it.
12
+
13
+ `WebhookEventMap` is merge-extensible by provider kind. `WebhookEventOf<K>` selects a known provider event and otherwise admits generic lossless JSON, allowing an out-of-tree adapter without changing the runtime package.
14
+
15
+ `VerifiedWebhookDelivery<K>` contains `kind`, configured `source`, provider `deliveryId`, normalized `event`, and non-negative safe-integer `receivedAt`. The runtime validates, detaches, and freezes the entire value before dispatching it to more than one rule.
16
+
17
+ `WebhookRule<K>` contains a unique id, provider kind, and `run(delivery, signal)`. The callback may execute arbitrary trusted code. It returns `null` or one `WebhookSessionRequest`, and it must observe the signal for asynchronous work that should stop when the registration unloads.
18
+
19
+ `WebhookSessionRequest` requires an absolute `workspacePath`, title, text prompt, agent preset, and permission preset. Optional `model` names an explicit provider/model route plus optional output-token cap and uses that adapter's reasoning default. Omission snapshots the complete current deployment selection, including reasoning effort, until the first request records its durable header.
20
+
21
+ ## Fire-and-forget dispatch
22
+
23
+ `dispatch()` snapshots the matching rules, schedules each independently, and returns before any callback settles. Throws and rejections are contained per rule. Registration disposal removes the rule before aborting and draining its active calls, so no later delivery can enter code that is unloading.
24
+
25
+ The runtime has no queue, retry, deduplication, execution status, crash replay, Agent-status listener, or completion result. Repeated delivery may create repeated Sessions. The only active-operation table is private teardown bookkeeping and disappears with the process.
26
+
27
+ ## Session creation
28
+
29
+ A non-null result is snapshotted before asynchronous preflight. The runtime validates permission and agent presets, resolves or creates the canonical Workspace, creates an Agent whose Session cwd equals the Workspace path, mounts the selected agent preset before publication, and durably attaches the Session before applying permission, title, and the initial follow-up.
30
+
31
+ The follow-up is a normal durable user-role message with `source.kind: "webhook"` and the provider, source, delivery, and rule identifiers. Its accepted inbox insertion commits the webhook operation. The runtime does not specially flush or wait for the turn; ordinary Session persistence and Agent lifecycle apply afterward.
32
+
33
+ Failed attachment disposes the new Agent before a prompt exists. A failure between attachment and prompt admission attempts Workspace detach and Agent disposal without replacing the original error. A Workspace automatically created during preflight remains because another concurrent caller may already use it.
34
+
35
+ ## GitHub adapter
36
+
37
+ `@deepseek-ai/dsh-webhook-github` registers an exact route on an injected WebServer, resolves its credential reference for each request, verifies the untouched `application/json` body before parsing, and returns `202` immediately after in-memory dispatch. Its normalized event guarantees a signed lossless-JSON object; rules validate the event-specific fields they consume.
38
+
39
+ The [GitHub review guide](../user/guide/github-review.md) mounts this route on an isolated second WebServer so exposing webhook ingress does not expose the browser API.
40
+
41
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
42
+
43
+ <a id="cordis-surface"></a>
44
+
45
+ ## Cordis API
46
+
47
+ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) - the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
48
+
49
+ <a id="ctxwebhookruntime--webhookruntime"></a>
50
+
51
+ ### `ctx.webhookRuntime` - `WebhookRuntime`
52
+
53
+ Fire-and-forget rule runtime. Session creation is the only built-in action.
54
+
55
+ ```ts cordis-catalog
56
+ /**
57
+ * Register one trusted programmatic rule.
58
+ * @param rule - unique id, provider kind, and arbitrary callback.
59
+ * @returns awaitable effect disposer that aborts and drains this rule's active callbacks.
60
+ */
61
+ register<K extends string>(rule: WebhookRule<K>): () => Promise<void>
62
+
63
+ /**
64
+ * Start every currently matching rule and return before any callback settles.
65
+ * @param delivery - authenticated provider data; snapshotted before dispatch.
66
+ * @throws synchronously when the runtime is closing or the delivery is malformed.
67
+ */
68
+ dispatch<K extends string>(delivery: VerifiedWebhookDelivery<K>): void
69
+ ```
70
+
71
+ Source: [`packages/webhook/webhook/src/index.ts`](../../packages/webhook/webhook/src/index.ts)
72
+ <!-- END GENERATED cordis-surface -->