@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,37 @@
1
+ # Agent presets and personas
2
+
3
+ Use this to give sessions a different composition (tools, prompt sections, skills) or a different identity:
4
+ a read-only reviewer, a minimal two-tool agent, a domain specialist.
5
+
6
+ Example (a directory, not an npm package): `../example-plugins/packages/agent-preset-reviewer/`.
7
+
8
+ ## What a preset is
9
+
10
+ A directory `<id>/` with:
11
+
12
+ - `agent.cordis.yml`: a list of Loader rows naming the plugins this preset's sessions run, with their config.
13
+ The `@deepseek-ai/dsh-persona` row sets the identity: `prefix` is the system prompt text, `complete: true`
14
+ makes it the WHOLE prompt (nothing else is added), `includeRuntimeContext: false` drops the runtime snapshot.
15
+ - `preset.yml`: `name`, `description`, `order` (display).
16
+
17
+ The picker reads presets from the shipped root and from `<dshHome>/.agent-presets/<id>/` (the `user` root; `<id>`
18
+ must match `[a-z0-9][a-z0-9-]*`). A preset that cannot load is listed with the reason, not hidden.
19
+
20
+ ## Rules
21
+
22
+ - **Start from a copy**: the shipped presets (`minimal`, `standard`, `ptc`, `cordis`) are the working reference.
23
+ Authoring in the product is copy-then-edit; a copy never grants more than its source listed.
24
+ - A preset grants the capabilities of the plugins it names: treat it as trusted configuration and keep the plugin
25
+ list minimal (a reviewer persona should not list write tools).
26
+ - A running session keeps its preset; only a session with no messages can switch. Tell the user to start a new
27
+ session to try it.
28
+ - A subagent joins its parent's composition.
29
+ - The default preset is a setting (`agent-presets.default`), applied to sessions created afterwards.
30
+
31
+ ## Verification status
32
+
33
+ The example's structure is copied from the shipped `minimal` preset, but the pack tests do not boot a session on
34
+ it. After writing one, ask the user to open the preset picker, start a new session on it and confirm the persona.
35
+
36
+ Details: `reference/subsystems/subagent.md`, `reference/subsystems/agent-team.md`,
37
+ `reference/subsystems/permission-presets.md`, `reference/harness/agent-lifecycle.md`.
@@ -0,0 +1,28 @@
1
+ # Chat slash commands
2
+
3
+ Use this to give the user a `/command` in the chat that runs on the host WITHOUT calling the model: reload something,
4
+ export a file, toggle a mode, show a status. It works on all three surfaces (CLI, Web, Desktop).
5
+
6
+ Working example: `../example-plugins/packages/chat-command-basic/` (read it fully).
7
+
8
+ ```js
9
+ export const name = 'my-commands'
10
+ export const inject = ['commands']
11
+ export function apply(ctx) {
12
+ ctx.effect(function* () {
13
+ yield ctx.commands.register({
14
+ name: 'hello-example', description: 'Say hello',
15
+ async handler(invocation) { return { kind: 'success', text: `Hello, ${invocation.rawInput.trim() || 'world'}!` } },
16
+ })
17
+ }, 'my-commands: /hello-example')
18
+ }
19
+ ```
20
+
21
+ - The handler returns `{ kind: 'success' | 'error', text }`; the text is shown to the user, not sent to the model.
22
+ - `invocation.rawInput` is the text after the command; `invocation.signal` aborts a long handler; `invocation.agent` is the
23
+ session's agent. Register inside `ctx.effect` so the command leaves with the plugin.
24
+ - Names are unique per session; a name already taken by a built-in wins, so pick a distinctive one.
25
+ - Do not use it for output the model must see (use a tool), and do not confuse it with `tuiCommands`, which opens a terminal
26
+ overlay (`extending/tui-command.md`).
27
+ - The pack's own `/reload` is a real, tested example: `../index.js`.
28
+ - Contract: `reference/subsystems/commands.md`. Where it appears in each surface: `maps/mount-points.md`.
@@ -0,0 +1,135 @@
1
+ # Client slot plugins: add UI to the Web and Desktop app
2
+
3
+ Use this to add a button, a panel, a tab or a settings section to the app (a kanban
4
+ board, a notes panel, a dashboard). Works on **web** and **desktop**; the terminal UI
5
+ has no client slots (see `tui-command.md`).
6
+
7
+ BEFORE hand-styling anything read `ui-components.md`: the app's own themed Button, Modal, Input, Switch, Tag and more can be `require`d
8
+ (verified in a browser), so the UI matches the app with no CSS.
9
+
10
+ For a slot beyond the header action, read its entry in `../maps/slot-contracts.md` (register options, the props your component receives, taken keys, a worked
11
+ example). A custom card for one of your own tools: `../example-plugins/packages/client-tool-view/`.
12
+
13
+ Working example, copy from it: `../example-plugins/packages/client-slot-header-action/`
14
+ (read `index.js` and `client.js` completely).
15
+
16
+ ## The two halves
17
+
18
+ A UI plugin is one package with a **host half** and a **browser half**:
19
+
20
+ - Host half `index.js`: named exports `name` and an **empty** `apply()`. It only gives the
21
+ Loader a row.
22
+ - Browser half `client.js`, exported as `"./client"`. It is discovered because
23
+ `package.json` has `"dsh": { "client": { "inject": [...], "platform": "web" } }`.
24
+
25
+ `package.json` needs (see the example): `"exports"` with `"."`, `"./client"` and
26
+ `"./package.json"`; `"files"` listing `index.js`, `client.js`, `cordis.patch.yml`;
27
+ `"dsh": { "bundle": { "patch": "./cordis.patch.yml" }, "client": { "inject": ["@deepseek-ai/dsh-client-ui-renderer", "@deepseek-ai/dsh-client-ui-conversation"], "platform": "web" } }`.
28
+ `dsh.client.inject` lists the client packages that must load first; use the ones that
29
+ declare the slot you fill (the conversation package for header slots, the sidebar
30
+ package for sidebar slots).
31
+
32
+ ## You have no build step. Write the bundle by hand
33
+
34
+ There is no bundler in the agent's loop, so `client.js` is hand-written CommonJS inside
35
+ the exact wrapper the repo's build adds:
36
+
37
+ ```js
38
+ window.__ModuleLoader__.load({ id: '<your package name>', factory: (require) => {
39
+ var module = { exports: {} }; var exports = module.exports;
40
+ const React = require('react') // provided by the app
41
+ const ReactDOM = require('react-dom') // provided by the app
42
+ // ...components using React.createElement (NO JSX: there is no compiler)...
43
+ exports.inject = ['slots']
44
+ exports.apply = function apply(ctx) {
45
+ ctx.slots.inject('<slot name>', () =>
46
+ ctx.slots.register({ name: '<slot name>', id: '<unique id>', order: 60 }, MyComponent))
47
+ }
48
+ return module.exports; } });
49
+ ```
50
+
51
+ `id` in the wrapper must equal the package name. `require` only serves the modules the
52
+ app exposes (`react`, `react/jsx-runtime`, `react-dom`, `@deepseek-ai/cordis` and the
53
+ `@deepseek-ai/dsh-client-*` packages); do not import anything else, and do not use `import`.
54
+ Styling: inline `style` objects, or inject one `<style>` element in `apply` and remove it in a
55
+ `ctx.effect` disposer.
56
+
57
+ ## Slots you can fill
58
+
59
+ | Slot | Where it renders | Kind |
60
+ | --- | --- | --- |
61
+ | `conversation.session.header.actions` | top bar of a conversation, next to the title | list (use `order`) |
62
+ | `conversation.session.header.utilities` | top bar, right-aligned utilities | list |
63
+ | `sidebar.right.pane.tab` | a tab in the right sidebar (two stages: register the tab TYPE in `ctx.sidebarRightTabs`, then the BODY in this keyed slot; see `client-slot-sidebar-tab`) | keyed (`key` = the type id) |
64
+ | `plugins.item` | a card in the Plugins page's Official group, for a plugin with a Host settings namespace; register it through `ctx.configForms.whileServed` so it exists exactly while the Host serves the namespace (see `reference/cookbook/adding-a-settings-card.md`; no verified example) | list (`id`, `label`, `order`) |
65
+
66
+ For a first version use the header action plus a floating panel opened by the button
67
+ (the example): it needs no other props. Register with `{ name, id, order }`.
68
+
69
+ ## A sidebar tab, or a docked or full-screen view
70
+
71
+ **Native sidebar tab (verified example)**: `../example-plugins/packages/client-slot-sidebar-tab/`. Copy its `client.js`.
72
+ Two stages, both inside `ctx.effect(...)`: (1) `ctx.sidebarRightTabs.register({ id, kind, title: () => 'Todo',
73
+ guide: [{ order, title, description }] })` declares the tab type and puts an entry on the sidebar's "new tab" page;
74
+ (2) `ctx.slots.inject('sidebar.right.pane.tab', () => ctx.slots.register({ name: 'sidebar.right.pane.tab', key: id },
75
+ Body))` registers the body. `inject` is `['slots', 'sidebarRightTabs']` and the package needs `dsh.client.inject`
76
+ to include `@deepseek-ai/dsh-client-ui-sidebar-right`. After install and a page reload the user opens the sidebar's
77
+ new-tab page and picks the entry. This example is loaded and applied in a real browser without errors; its body
78
+ rendering inside an open session is the part to confirm with the user, so say so.
79
+
80
+ **Docked or full view (most robust)**: keep the header-action button from `client-slot-header-action` and change
81
+ the panel it opens. A docked side panel is `position: 'fixed', top: 0, right: 0, height: '100vh', width: 420,
82
+ zIndex: 9999`; a full view is `inset: 0`. Give it a title bar with a close button. Use this when the native tab
83
+ strip is not required, or as the fallback if the sidebar tab does not show.
84
+
85
+ Exact registration reference: `reference/subsystems/sidebar-right.md` and `reference/subsystems/slots.md`.
86
+
87
+ ## Chat messages and turns
88
+
89
+ Extend how the conversation looks around messages with the ADDITIVE seams, not by replacing renderers. `conversation.chat.assistant-actions` (a list: an action under
90
+ each finished assistant message, props `{ messageId }`; example `../example-plugins/packages/client-chat-message-action/`) and `conversation.chat.turnTail` (a chain with a
91
+ `select(owner)` router that renders before a completed turn's action row). `conversation.chat.node` renders every message kind, and every kind is already owned by a shipped
92
+ renderer, so registering there replaces it (a takeover): use it only when the user asks to change how a whole message kind looks, and read `../maps/slot-contracts.md` first.
93
+ The same holds for `tool.call.toolview`: a key you own (your own tool) is additive, a shipped tool's key is a takeover.
94
+
95
+ ## Keyboard shortcuts
96
+
97
+ The Web and Desktop client has no plugin shortcut registry (only built-in behavior such as the sidebar toggle). A plugin owns a guarded `keydown`
98
+ listener: see the `useEffect` in `../example-plugins/packages/client-ui-components/client.js` (Cmd/Ctrl+Shift+K toggles its modal; verified in a real browser).
99
+ Rules: use a modifier combination, never a bare key; ignore the event when `event.defaultPrevented` or while the user types in an input, textarea or
100
+ editable element; call `preventDefault()` only when you act on it; remove the listener in the effect cleanup. Two plugins can collide on a combination:
101
+ say which one you chose. Desktop's native menu accelerators live in the Electron main process (`desktop-app.md`) and are not plugin-changeable.
102
+
103
+ ## Persisting state
104
+
105
+ The example keeps state in `localStorage`. That survives reloads in ONE browser only: Web and Desktop each have their own copy, and clearing site data wipes it. For state
106
+ shared across surfaces, kept on the host, or visible to the agent, read `state-and-persistence.md` (host file behind an RPC channel, workspace file, settings) and
107
+ start from `../example-plugins/packages/state-host-store/`.
108
+
109
+ ## Getting it live
110
+
111
+ Deliver with the `acryl_install_plugin` tool (`../delivery/local-live.md`). The host row is live
112
+ immediately; the browser part appears after the page (Web) or window (Desktop) reloads, and the
113
+ tool result tells you so. Say that to the user.
114
+
115
+ ## Building something like a kanban board
116
+
117
+ Copy the example and change the component: columns as arrays in state, cards as objects with
118
+ an id, move a card by updating state and saving to `localStorage`, render columns with
119
+ `React.createElement`. Keep it in one `client.js`. Choose the slot by what the user asked: a
120
+ top-bar button and panel is the simplest; a right-sidebar tab uses the `client-slot-sidebar-tab` pattern.
121
+
122
+ ## Debugging in the browser
123
+
124
+ Put a `console.info('[<package>] ...')` at the top of `client.js` and in `apply`. Open the browser console
125
+ (reload first): if the module line appears the bundle loaded and `require('react')` works; if the `apply` line
126
+ appears the slot registration ran. Nothing logged means the bundle did not load (check the wrapper `id`, no
127
+ JSX, no `import`, and that `package.json` has `dsh.client` and `exports["./client"]`). The example does this.
128
+
129
+ ## Common mistakes
130
+
131
+ - JSX or `import` in `client.js` (no compiler): the bundle fails to load. Use `createElement`
132
+ and `require`.
133
+ - Wrapper `id` different from the package name.
134
+ - `exports` missing `"./client"` or `"./package.json"`: the install tool reports it.
135
+ - Forgetting the empty host `apply()`: there is then no row to mount.
@@ -0,0 +1,7 @@
1
+ # Plugin configuration
2
+
3
+ Example: `../example-plugins/packages/config-schema-basic/`. Export a Schemastery `Config`
4
+ (`import Schema from '@deepseek-ai/schemastery'`, add it as a dependency). The Loader validates
5
+ config and fills defaults **before** `apply` runs, so a bad config fails the whole mount and
6
+ nothing is half-applied. Do not export a plain object. Config is replaced, not deep-merged.
7
+ A row's config lives in its Loader row; mount with a config, and a schema error names the field.
@@ -0,0 +1,63 @@
1
+ # Cordis building blocks: what exists and where it is documented
2
+
3
+ Read this when you are unsure which Cordis or harness mechanism to use, or want the exact contract of
4
+ one. Paths below are relative to the docs folder (`docs/`); every one exists in this pack.
5
+
6
+ ## The model in ten lines
7
+
8
+ - A **plugin** is a module exporting `name`, optionally `inject` and `Config`, and `apply(ctx, config)`.
9
+ - A **Fiber** is one mounted plugin instance. States: `PENDING` (a hard `inject` dependency is missing: healthy,
10
+ waiting), `LOADING`, `ACTIVE` (`apply` ran), `FAILED` (real error), `UNLOADING`, `DISPOSED`.
11
+ - `inject: ['x']` is a **hard** dependency: the fiber stays PENDING until service `x` exists and remounts when
12
+ its provider changes. `ctx.get('x')` is an **optional** dependency, read at call time (never captured at apply).
13
+ - A **Service** is a named capability on `ctx`: `class X extends Service { constructor(ctx) { super(ctx, 'x') } }`.
14
+ - An **effect** (`ctx.effect(() => { ...acquire; return () => release })`) owns every resource; registrations
15
+ (`ctx.tools.register`, `ctx.on`, ...) are effects, so they disappear when the fiber unloads. A leak is a bug.
16
+ - **Events**: `ctx.emit` / `ctx.parallel` / `ctx.serial` / `ctx.bail` / `ctx.waterfall`; listen with `ctx.on`.
17
+ A waterfall listener that only observes MUST still call `next()`.
18
+ - **Config** is a synchronous StandardSchema (a Schemastery object works), validated before `apply`.
19
+ - The **Loader** turns rows (`cordis.patch.yml` inserts, profile bundles) into mounted fibers. `id` is the stable
20
+ row identity; `name` is the module.
21
+ - **Scope**: `ctx.isolate(...)`, `ctx.intercept(...)` and `ctx.extend(...)` derive a child context (class methods).
22
+ `ctx.timer`, `ctx.hmr` and `ctx.loader` exist only when their plugin is loaded.
23
+ - Everything domain-specific (tools, llm, skills, slots, commands, settings, sessions) is a harness **service**
24
+ built on this, not core Cordis.
25
+
26
+ ## Which doc to read for what you are building
27
+
28
+ | You want to add | Read first | Then the reference |
29
+ | --- | --- | --- |
30
+ | A model-callable tool | `extending/tool-plugin.md` | `reference/cookbook/adding-a-tool.md`, `reference/subsystems/tools.md`, `reference/harness/tool-execution-pipeline.md` |
31
+ | A service others depend on | `extending/service.md` | `reference/cordis-api/service.md`, `reference/cordis-api/registry.md` |
32
+ | A capability with swappable providers | `extending/three-role-capability.md` | `reference/harness/capability-seams.md` |
33
+ | An event listener or interceptor | `extending/event-hook.md` | `reference/cordis-api/events.md`, `reference/harness/event-producer-consumer.md` |
34
+ | Validated configuration | `extending/config-schema.md` | `reference/harness/config-catalog.md`, `reference/subsystems/settings.md` |
35
+ | A system-prompt section | `extending/prompt-contribution.md` | `reference/subsystems/system-prompt.md` |
36
+ | A skill or skill provider | `extending/skill-provider.md` | `reference/subsystems/skills.md` |
37
+ | A chat slash command (all surfaces) | `extending/chat-command.md` | `reference/subsystems/commands.md` |
38
+ | A terminal overlay (CLI only) | `extending/tui-command.md` | `maps/mount-points.md` |
39
+ | Where something can mount, per surface | `maps/mount-points.md` | `maps/slot-contracts.md`, `reference/subsystems/slots.md` |
40
+ | Hooking the agent lifecycle (prompt, request, stream, session) | `maps/events.md` | `example-plugins/packages/prompt-assemble-hook/`, `lifecycle-hooks-observer/` |
41
+ | The full list of plugin types and shipped plugins | `maps/taxonomy.md` | `reference/harness/architecture.md` |
42
+ | A new model provider | `extending/llm-adapter.md` | `reference/cookbook/adding-an-llm-adapter.md`, `reference/subsystems/llm-streaming.md` |
43
+ | An agent preset or persona | `extending/agent-preset.md` | `reference/subsystems/subagent.md`, `reference/subsystems/agent-team.md` |
44
+ | A backend HTTP/RPC route | `extending/host-route.md` | `reference/cookbook/adding-a-remote-api.md`, `reference/subsystems/web-server.md` |
45
+ | UI: button, panel, sidebar tab, settings card | `extending/client-slot.md` | `reference/subsystems/slots.md`, `reference/subsystems/client-modules.md`, `reference/subsystems/sidebar-right.md`, `reference/cookbook/adding-a-settings-card.md` |
46
+ | Desktop-only host features (profiles, pnpm, live activation) | `extending/desktop-main.md` | `reference/cordis-guides/hello-world-plugin-guide.md` |
47
+ | Shipping or generating a package | `extending/packaging.md` | `reference/cookbook/adding-a-package.md` |
48
+ | Something is PENDING or FAILED | `start-here/troubleshooting.md` | `reference/cordis-api/fiber.md` |
49
+
50
+ ## When you need the whole picture
51
+
52
+ `reference/cordis-guides/cordis_system_guide_for_coding_agents.md` is the long handbook,
53
+ `reference/cordis-guides/cordis-usage-cheatsheet.md` the short source-validated version,
54
+ `reference/harness/cordis-primer.md` and `reference/harness/glossary.md` the vocabulary,
55
+ and `reference/harness/defensive-patterns.md` the failure-handling idioms. The reference docs were copied from the
56
+ repository and may link to paths that do not exist here; use the table above instead of following those links.
57
+
58
+ ## Design before you code (for a new seam)
59
+
60
+ Before adding a new service, tool or event seam write down: the capability boundary; what it provides and
61
+ consumes; every effect and its disposer; configuration and stable row ids; the event dispatch mode; and how you
62
+ will verify it (real mount, PENDING then ACTIVE, provider swap, dispose, remount). For a small plugin one
63
+ sentence each is enough.
@@ -0,0 +1,53 @@
1
+ # The Desktop (Electron) app: structure, and what a plugin can and cannot change
2
+
3
+ Source: `apps/acryl-desktop` in the ACRYL repository. Read this before promising any Desktop change.
4
+
5
+ ## Two halves
6
+
7
+ - **Main process (Node, Electron).** Boots the ACRYL runtime, owns the window, the native menu, notifications, the tray, the
8
+ installer identity and updates. Files (all under `apps/acryl-desktop/`): `src/main.ts` (boot, `PRODUCT_NAME = 'ACRYL'`),
9
+ `src/electron-shell-generation.ts` (creates the `BrowserWindow`), `src/window-options.ts` (window chrome per mode and
10
+ platform), `src/native-menu.ts`, `src/notifications.ts`, `src/desktop-*.ts` and `src/profile*.ts`, `src/pnpm.ts` services (`desktopProfiles`, `desktopPnpm`, plugins,
11
+ market, terminal), `src/tray-*.ts`, `src/update-*.ts`, `build/` (icons: `app-icon.png`, `app-icon-mac.png`, `tray-icon*.png`, logos), and the
12
+ `package.json` `build` section (electron-builder: `appId` `dev.acryl.desktop`, `productName` `ACRYL`, icons, targets).
13
+ - **Renderer (the web client app).** The SAME React client app as Web, loaded from the Desktop-owned local web server into the
14
+ window (`src/client/*` adds Desktop-only pieces: `AdvancedFrame.tsx`, `advanced-shell.ts`, `theme-presenter.ts`,
15
+ `layout-service.ts`, the Desktop settings tabs, `styles.ts` and `desktop-settings-styles.ts` which hold CSS in TypeScript).
16
+
17
+ ## Presentation modes
18
+
19
+ - **compatibility**: the stock DSH web UI inside a native window.
20
+ - **advanced**: the ACRYL frame: a translucent native window (macOS vibrancy `sidebar`, hidden inset title bar with traffic lights;
21
+ Windows Mica with a title bar overlay), the ACRYL sidebar, main surface and details panel. It exposes frame slots:
22
+ `desktop.main` (replaceable main surface), `sidebar`, `conversation`, `details`, `shell.overlay` (see
23
+ `../maps/mount-points.md`). Advanced mode is supported on macOS and Windows.
24
+
25
+ ## What a plugin can change (live, in an installed app)
26
+
27
+ Everything in the renderer that Web can change, identically: theme tokens and fonts (`ui-theme.md`), brand slots and the tab or
28
+ window title text (`ui-branding.md`), client slots including the Desktop frame slots, host services, tools, commands. The
29
+ theme presenter applies the resolved tokens to the document body, and dark mode follows `nativeTheme`.
30
+ The Desktop-only host services (`desktopProfiles`, `desktopPnpm`, `livePluginActivation`) are in `desktop-main.md`.
31
+
32
+ ## What needs a source change and a rebuild (COLD)
33
+
34
+ | Change | Where |
35
+ | --- | --- |
36
+ | App icon, tray icon, logos in the installer | `build/*.png`, `package.json` build `icon` entries |
37
+ | Product name, app id, installer name | `package.json` `build` (`appId`, `productName`), `src/main.ts` `PRODUCT_NAME` |
38
+ | Title bar, vibrancy or Mica, window size, minimum size, traffic light position | `src/window-options.ts` (`advancedWindowOptions`, `compatibilityWindowOptions`) |
39
+ | Native menu items and shortcuts | `src/native-menu.ts` |
40
+ | The Desktop-only frame layout and settings tabs | `src/client/AdvancedFrame.tsx`, `src/client/desktop-settings*.ts(x)` |
41
+ | Notifications, tray icons and locale, updates | `src/notifications.ts`, `src/tray-icons.ts`, `src/tray-locale.ts`, `src/updates.ts`, `src/update-*.ts` |
42
+
43
+ These are only possible when you are working inside the ACRYL repository. To try one: `corepack pnpm run dev` (an isolated
44
+ development app with its own home, `~/.acryl-dev`), reload after client changes, and restart after main-process changes. Run the
45
+ Desktop tests (`apps/acryl-desktop`, `vitest run`). A packaged app is read-only: `app.asar` cannot be edited, so an agent in an
46
+ installed app can only use the live plugin changes above. Say that plainly.
47
+
48
+ ## Safety
49
+
50
+ - Never disable the sandbox or `contextIsolation`, never enable `nodeIntegration`, in `webPreferences`.
51
+ - Never touch the user's real `~/.dsh` or `~/.acryl`; use a temporary home for experiments.
52
+ - A visual change cannot be seen by you: ask the user to look.
53
+ - Reference: `reference/cordis-guides/hello-world-plugin-guide.md`, `reference/cordis-guides/development-canvas-plugin.md`.
@@ -0,0 +1,25 @@
1
+ # Profile and install services (Desktop main and the compatibility subset)
2
+
3
+ Use this when a plugin needs to know which profile is active, run a package operation in it, or activate another
4
+ plugin without a restart. These are Host services, not browser code.
5
+
6
+ Working example: `../example-plugins/packages/desktop-main-profile-info/`.
7
+
8
+ | Service | Where | What you get |
9
+ | --- | --- | --- |
10
+ | `desktopProfiles` | all surfaces (Desktop full, Web and CLI a subset) | `current` = `{ name, dir }` on every surface. Desktop also has `list()`, `create(name)`, `select(name)` (requests a restart), `canDelete(name)`, `delete(name)` |
11
+ | `desktopPnpm` | all surfaces | `runPlugin(args)` runs `dsh plugin ...` in the active profile and returns a handle: `stdout`, `stderr` (streams), `done` (`{ exitCode }`), `cancel()`. Desktop refuses `runPlugin(['add'])`; `run([...])` (generic pnpm) works there |
12
+ | `livePluginActivation` | all surfaces | `activate(name)`, `deactivate(name)`, `setEnabled(name, on)`, `statusOf(name)`: mount or unmount an installed plugin live |
13
+
14
+ ## Rules
15
+
16
+ - Feature-test members that only Desktop has (`typeof profiles.list === 'function'`) before calling them.
17
+ - Declare `inject: ['desktopProfiles']` when the plugin is meaningless without it, or read
18
+ `ctx.get('desktopProfiles')` at call time when it is optional. Never capture these at apply time (they can be
19
+ provided after your plugin mounts: the documented ordering trap).
20
+ - Never write into another profile's directory, and never touch the user's real home from a test. Use a temporary
21
+ `DSH_HOME`.
22
+ - `select()` restarts the app: only do it because the user asked.
23
+ - This pack's own install tool (`acryl_install_plugin`) is built on these three services; read
24
+ `../lib/install.js` for a real, tested usage, and `reference/cordis-guides/hello-world-plugin-guide.md` for the
25
+ Desktop plugin walkthrough.
@@ -0,0 +1,14 @@
1
+ # Events: listen, emit, intercept
2
+
3
+ Example: `../example-plugins/packages/event-hook-basic/`.
4
+
5
+ `ctx.on(name, fn)` listens and Cordis removes it when the plugin unloads; `ctx.emit(name, ...args)`
6
+ broadcasts synchronously. Dispatch modes: `emit` (fire and forget), `parallel` (await all),
7
+ `serial` (in order until a value bails), `bail` (sync serial), `waterfall` (around-middleware:
8
+ `ctx.on(name, async (input, next) => ...)`). **A waterfall listener that only observes MUST call
9
+ `next()`**, otherwise it swallows the downstream default. Use services for calls and events for
10
+ observation or interception. Facts that must survive a restart belong in durable session state,
11
+ not in a Cordis event.
12
+
13
+ Every lifecycle event (prompt construction, the provider request, streaming, session events) is listed in `../maps/events.md`. Working example of a
14
+ waterfall hook on prompt construction: `../example-plugins/packages/prompt-assemble-hook/`.
@@ -0,0 +1,33 @@
1
+ # Host routes: an HTTP API for a web/desktop plugin
2
+
3
+ Example: `../example-plugins/packages/host-route-basic/`. Build your routes as one app and serve it on the framework's router:
4
+
5
+ ```js
6
+ import { Acryl } from 'acrylblends'
7
+ export const inject = ['router', 'routerHttp']
8
+ export function apply(ctx) {
9
+ const app = new Acryl()
10
+ app.get('/api/my-plugin/hello', c => c.text('ok'))
11
+ ctx.router.route('/', app) // the routes, owned by this plugin
12
+ ctx.routerHttp.mount('/api/my-plugin') // the one prefix the web server hands to the router
13
+ }
14
+ ```
15
+
16
+ - One prefix per plugin, `/api/<plugin>`, and every route under it. Two plugins cannot mount the same prefix.
17
+ - No `ctx.effect` and no disposer: the routes and the mount belong to the plugin and leave when it unloads (a request still running is
18
+ ended within a short grace).
19
+ - `package.json`: `acrylblends` under `peerDependencies` (the app provides it; under `dependencies` the install is refused), and
20
+ `"dsh": { "requiresAcrylPackages": ["@acryldev/blends/cordis/router", "@acryldev/blends/cordis/router-http"] }` so an installed plugin resolves the
21
+ app's own copy.
22
+ - The router comes from the app's `framework-kit` row (every built-in Blueprint has it). In an app without it, the install mounts each module
23
+ `requiresAcrylPackages` names while the app runs, shares it with any other plugin that names it, and removes it with the last of them;
24
+ the next start composes it again for as long as such a plugin is installed.
25
+ - Web and desktop only (tui has no web server). A client bundle can `fetch` the route to share state with the host and with other devices.
26
+ - The handler gets a context `c`: `c.req.json()`, `c.req.query('x')`, `c.req.header('origin')`, and answers with `c.json(value, status)`,
27
+ `c.text(...)` or `c.body(...)`. Validate every input; the route is reachable by the page and by any program on the machine unless you
28
+ check the caller.
29
+
30
+ To persist data behind a route, prefer exact RPC routes under `/api` (`connection.fetch.register`, answered in the RPC envelope) over a plain route,
31
+ and read `state-and-persistence.md` first: it lists every place a plugin can keep state and the mistakes that break an RPC route (result envelope,
32
+ rpcId, payload); those routes sit behind the app's browser authentication. `connection.rpc.handle` works in ACRYL only (stock DSH's connection row
33
+ lacks `webServer`). Example: `../example-plugins/packages/state-host-store/`.
@@ -0,0 +1,38 @@
1
+ # LLM adapters: connect a new model provider
2
+
3
+ Use this to add a provider route (a new hosted API, a local server, a wrapper). Working example:
4
+ `../example-plugins/packages/llm-adapter-echo/` (a network-free adapter that shows the whole contract; read it fully).
5
+ The complete contract: `reference/cookbook/adding-an-llm-adapter.md` and `reference/subsystems/llm-streaming.md`.
6
+
7
+ ## The shape
8
+
9
+ ```js
10
+ import { LlmAdapter } from '@deepseek-ai/dsh-llm'
11
+ class MyAdapter extends LlmAdapter { async * stream(options) { /* yield StreamChunks */ } }
12
+ export const name = 'my-llm'
13
+ export const inject = ['llm']
14
+ export function apply(ctx) { ctx.llm.registerAdapter(['my-provider'], new MyAdapter()) }
15
+ ```
16
+
17
+ Registration is effect-based (released on dispose or reload). One adapter per provider route: a duplicate
18
+ throws. `options.provider` picks the adapter and `options.model` is the provider's model id.
19
+
20
+ ## Stream protocol (obligations)
21
+
22
+ Chunk order for a text answer: `block-start {index, blockType:'text'}`, one or more `text-delta {index, text}`,
23
+ `block-end {index, block:{type:'text', text}}`, then `usage {usage:{inputTokens, outputTokens}}`, then
24
+ `finish {reason:{kind:'stop'}}`. Emit `usage` BEFORE `finish` and nothing AFTER `finish`.
25
+
26
+ - Tool calls stream as `tool-call-delta {index, id, name?, argumentsDelta}` where `argumentsDelta` is a raw JSON
27
+ string fragment; close with `block-end` and finish with `{kind:'tool-calls'}`.
28
+ - Reasoning text uses `reasoning-delta`.
29
+ - Honor `options.signal` (pass it to fetch). Never swallow an abort.
30
+ - Errors: THROW from `stream()` with `LlmError` and a stable code, or end with `finish {kind:'error'|'aborted', failure}`.
31
+ - Secrets come from validated `Config` with env fallbacks, never from a file read in code; never log a key.
32
+ - Every provider HTTP request must carry `attributionHeaders()` from `@deepseek-ai/dsh-llm`.
33
+ - Optional overrides: `providerInfo`, `listModels`, `resolveModel` (context window, reasoning efforts).
34
+
35
+ ## Verify
36
+
37
+ Mount it, then check `ctx.llm` has the route. To exercise it without a network, run one `stream()` call in a
38
+ throwaway script and check the chunk order. Ask the user to pick the provider in Settings to try it for real.
@@ -0,0 +1,53 @@
1
+ # Packaging a plugin, and generated capabilities
2
+
3
+ Example: `../example-plugins/packages/generated-capability-template/`.
4
+
5
+ Every plugin ships as an npm package:
6
+
7
+ 1. `package.json`: `type: module`, `exports` with `"."` (and `"./client"` for UI) **and
8
+ `"./package.json"`**, `files` including everything referenced, and
9
+ `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`.
10
+ 2. `cordis.patch.yml`: `- insert: [{ id: <stable-id>, name: <package name> }]`.
11
+ 3. Dependencies the code imports (`@deepseek-ai/dsh-tools`, `@deepseek-ai/schemastery`, ...).
12
+
13
+ For a package meant to be shared or published add `"keywords": ["acryl-package"]`, a GitHub
14
+ `repository`, a `license`, and `"acryl": { "schemaVersion": 1, "artifacts": { "plugins": ["./index.js"] } }`
15
+ (artifact kinds: plugins, extensions (an older name kept by the manifest format), adapters, skills, workflows, blueprints, stemcells; paths relative,
16
+ no `..`). Only the marketplace catalog reads these.
17
+
18
+ A **generated capability** (written by the agent) also records, in the entry file header: what it does,
19
+ its permissions (network, filesystem, shell, secrets; least privilege), who generated it and from which
20
+ examples, and its mutation class: HOT (a remount is enough), WARM (needs a generation restart) or COLD
21
+ (a native swap). The agent only delivers HOT and WARM; it tells the user about COLD.
22
+
23
+ ## Manifest fields for local plugins
24
+
25
+ Add to the `acryl` block of `package.json` (created for the marketplace catalog, see `../delivery/marketplace.md`):
26
+
27
+ ```json
28
+ "acryl": { "schemaVersion": 1, "artifacts": { "plugins": ["./index.js"] }, "apiVersion": 1, "permissions": ["fs.write", "ui"] }
29
+ ```
30
+
31
+ `apiVersion` is the ACRYL plugin API the code was written against (currently 1); a plugin that needs a newer one is refused with a message that says so. `permissions` are drawn from
32
+ `fs.read`, `fs.write`, `net`, `shell`, `secrets`, `ui`; an unknown word is a lint error so a typo cannot pass as declared. They are shown to the human before a new plugin is installed
33
+ (`/reload`), and `acryl_install_plugin` returns them. Declare honestly: they are not enforced by a sandbox, they inform the human's decision.
34
+
35
+
36
+ ## Generated fields: the service contract and slots
37
+
38
+ Three more fields of the `acryl` block are written from the code, never by hand: `requires` (each side's `inject`: the services the app must
39
+ provide), `provides` (services the plugin registers) and `slots` (UI places it declares with `children: { 'name': { kind } }` and fills with
40
+ `slots.register({ name })` or `slots.inject(name)`). `acryl_prepare_publish` and sharing write them; a catalog shows from them which apps run
41
+ the plugin and where it appears, and a pull refuses to install a plugin whose required host services the app lacks.
42
+
43
+ ```json
44
+ "acryl": { "requires": { "host": ["connection", "dshHomePath"], "client": ["slots"] }, "provides": { "host": [] }, "slots": { "offers": [], "fills": ["sidebar.footer.action"] } }
45
+ ```
46
+
47
+ Prefer a service stock DSH also provides (`dshHomePath` for a data folder) over an ACRYL-only one, so the plugin runs in both apps.
48
+
49
+ ## Saving, sharing and pulling
50
+
51
+ A plugin's name may have levels separated by dots (`@owner/my-app.sidebar.date-filter`, lowercase, hyphens inside a level). The user saves,
52
+ shares and pulls with `/plugin save | share | pull` in the chat or `acryl plugin save | share | pull` on the command line; these send their
53
+ work or install code, so they are the user's to type. A fix is a new version (`/plugin version patch <name>`): a released version never changes.
@@ -0,0 +1,9 @@
1
+ # Prompt contributions
2
+
3
+ Example: `../example-plugins/packages/prompt-contribution-basic/`.
4
+
5
+ `ctx.systemPrompt.section({ name, order, text })` adds a section and returns its disposer (wrap in
6
+ `ctx.effect`). `text` may be a string or a function of the assembly context. Sections sort by
7
+ `order` (tools 1000-2900, SDK 5000, deliverables 9000, local paths 10000+). Names must be unique in a
8
+ scope. Keep text **static** so it stays in the cacheable prompt prefix; per-session facts belong in a
9
+ `PromptContext` (durable snapshot). Reference: `reference/subsystems/system-prompt.md`.
@@ -0,0 +1,13 @@
1
+ # Services: provide a capability, consume it
2
+
3
+ Examples: `../example-plugins/packages/service-provider-greeter/`, `service-consumer-greeter/`.
4
+
5
+ - **Provide**: `class X extends Service { constructor(ctx) { super(ctx, 'name') } }` and export it
6
+ as `apply` (`export { X as apply }`). Import `Service` from `@deepseek-ai/cordis`.
7
+ - **Require (hard)**: `export const inject = ['name']`. The fiber is `PENDING` until something
8
+ provides `name`, then goes `ACTIVE` by itself, whatever the mount order. `PENDING` is healthy.
9
+ - **Optional**: `ctx.get('name')` and handle `undefined`; never `PENDING`.
10
+ - Depend on the service **name**, never on a concrete provider. To swap an implementation, mount
11
+ another provider of the same name (three-role design: definition, provider, consumer).
12
+ - A `Service` instance's `this.ctx` is its construction scope, not the caller's: do not read
13
+ `this.ctx.loader` or `this.ctx.fiber` inside its methods.
@@ -0,0 +1,9 @@
1
+ # Skills: on-demand instructions
2
+
3
+ Example: `../example-plugins/packages/skill-provider-basic/`. A skill is a name and description that sit in
4
+ the agent's context, with the full body loaded only when needed. Register a provider:
5
+ `ctx.skills.registerProvider(() => provider)` where `provider = { name, list(), get(candidate) }`.
6
+ `list()` returns candidates (`name` kebab-case, `description`, `invocation`, `provider`, `source`,
7
+ `rank`); `get()` returns the definition with `content`. Simplest for a project: put
8
+ `<name>/SKILL.md` under `.dsh/skills` or `.agents/skills`; a plugin provider is for shipping skills
9
+ with a package. Reference: `reference/subsystems/skills.md`.
@@ -0,0 +1,71 @@
1
+ # State and persistence: where a plugin keeps its data
2
+
3
+ Pick where the data lives BEFORE writing the plugin. Every option below is available; they differ in who can see the data, what survives, and
4
+ which surfaces they work on. If the user did not say, choose from the table and tell them the trade-off in one sentence.
5
+
6
+ | Option | Lives in | Survives | Shared between | Agent can read it | Surfaces | Example |
7
+ | --- | --- | --- | --- | --- | --- | --- |
8
+ | Browser `localStorage` | one browser origin | reload, restart (NOT clearing site data) | nothing: Web and Desktop each have their own | no | web, desktop | `client-slot.header-action`, `ui-components.shared-primitives` |
9
+ | Host file behind an RPC channel | `<DSH home>/plugin-data/<plugin>/` | everything, incl. clearing the browser | every window, browser and surface using the same ACRYL home | only through your own tool | web, desktop | `state.host-store` |
10
+ | Workspace file | `<workspace>/.acryl/` (any file) | everything; can be committed to git | everyone using that project | yes, with its normal file tools | tui, web, desktop | `state.workspace-file` |
11
+ | User settings | the user settings document | everything | every surface using the same DSH home | through settings | tui, web, desktop | `settings-section.basic` |
12
+ | Harness storage domains (`ctx.storageDomain`) | a routed storage backend | everything | per backend routing | no | tui, web, desktop | none (see below) |
13
+ | In memory (a variable in `apply`) | the running process | until the app restarts or the plugin reloads | the process | no | all | any example |
14
+
15
+ ## Choosing
16
+
17
+ - A UI preference or a scratch list that only matters in this browser: `localStorage`. Simplest. Tell the user it is per browser and per surface.
18
+ - Data the user expects to see the same in Web AND Desktop, or that must survive clearing the browser: a host file behind an RPC channel.
19
+ - Notes, todos or decisions that belong to a project and that the agent should read and write: a workspace file (plain Markdown or JSON).
20
+ - A few named options the user edits (a toggle, a limit, a default): a settings section, not a data file.
21
+ - Never keep secrets in `localStorage` or in a workspace file (it can be committed). Use a settings field marked `.role('secret')`.
22
+
23
+ ## Host file behind RPC routes on `/api` (`state.host-store`)
24
+
25
+ Host half: `inject = ['connection', 'dshHomePath']`, then one `ctx.connection.fetch.register({ path: '/api/<plugin>/<endpoint>', methods: ['POST'],
26
+ requestBody: 'buffered', fetch })` per endpoint, answering the RPC envelope. Client half: `inject = ['slots', 'connection']`, then
27
+ `ctx.connection.rpc.call('/api', '<plugin>/<endpoint>', payload)`. The routes sit behind connection's browser authentication and Host/Origin
28
+ checks, unlike a plain router route (see `host-route.md`), and they work in stock DSH as well as in ACRYL.
29
+
30
+ Do not use `ctx.connection.rpc.handle(channel, ...)` for a plugin meant for both apps: stock DSH's `connection` row does not declare `webServer`,
31
+ so a third-party channel fails there with `cannot get property "webServer" without inject` (measured on DSH 0.2.0-rc.2, spec 044 S11). ACRYL
32
+ patches that row, so the same plugin would work in ACRYL only.
33
+
34
+ Facts measured while building the example (each one cost a failed run):
35
+
36
+ - The request a route receives is `{ type: 'client-request', rpcId, method, payload }`; answer `Response.json({ type: 'server-response', rpcId, result })`
37
+ with the same `rpcId`, or the client throws `rpcId mismatch`.
38
+ - `result` MUST be the result envelope: `{ ok: true, value }` or `{ ok: false, error: { code, message, details } }`. Any other shape (for example
39
+ `{ notes }` or `{ error: 'x' }`) is rejected as `connection: invalid server-response result`.
40
+ - `rpc.call` resolves to that same envelope. Unwrap it once in the client (`ok === false` -> throw `error.message`); rendering `result.error` directly
41
+ crashes React (error #31: an object is not a valid child) and the whole slot disappears.
42
+ - Always send an object payload (`call(endpoint, payload ?? {})`). `undefined` is dropped by JSON and the host answers `invalid client-request message`.
43
+ - A route path is exact and lives under `/api`; two plugins cannot register the same path, so prefix it with the plugin name.
44
+ - Get the data directory with `ctx.get('dshHomePath')('plugin-data', <plugin name>)` and declare `dshHomePath` in `inject`; never fall back to
45
+ `homedir()` or a hard-coded `~/.acryl` (a test or second app instance would write into the user's real home). Web and Desktop dev runs use
46
+ different homes (`~/.acryl`, `~/.acryl-dev`), so two surfaces share the file only when they run against the same home.
47
+ - Write atomically (temp file, then rename), validate every input (the page can send anything), and cap sizes.
48
+
49
+ ## Workspace file (`state.workspace-file`)
50
+
51
+ The session's workspace is `exec.agent.session.header.cwd` inside a tool's `execute(args, exec)`. Append-only files (one line per note) are safe when
52
+ two sessions write at once; whole-file rewrites are not. Refuse to guess a directory when the session has no workspace. The file is normal project
53
+ content: the user sees it, git can track it, and the agent can read it with its usual file tools, so no tool is needed to READ it, only to write.
54
+
55
+ ## Settings (`settings-section.basic`)
56
+
57
+ `ctx.settings.installSection(ctx, NAMESPACE, Config, config, { validate, setSource, onChange })` inside `ctx.inject(['settings'], ...)`. Read the value
58
+ through the `setSource` function on every use; never cache it. See `config-schema.md`.
59
+
60
+ ## Harness storage domains (`ctx.storageDomain`)
61
+
62
+ The harness's own persistence hub (`../reference/subsystems/storage.md`): a domain is declared with `defineDomain` (zod schemas, a version, tables) and
63
+ opened with `ctx.storageDomain.open(spec)`; reads are synchronous from memory, writes are queued and drained, and a `domain/changed` event fires. It
64
+ is what the harness uses for session projections. There is no example in this pack: it needs a dependency on the harness storage-domain package and
65
+ it was not verified from a user plugin. Prefer the options above unless the user needs versioned, schema-checked tables; if you use it, verify with
66
+ `acryl_verify_plugin` and a real run before saying it works.
67
+
68
+ ## Related
69
+
70
+ Host routes: `host-route.md`. Client slots and `localStorage` UI: `client-slot.md`, `ui-components.md`. Session persistence in the harness:
71
+ `../reference/subsystems/persistence.md`.