@acryldev/plugin-context 0.0.0-stage → 0.1.1

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/README.md +12 -2
  3. package/docs/README.md +160 -0
  4. package/docs/delivery/local-live.md +113 -0
  5. package/docs/delivery/marketplace.md +16 -0
  6. package/docs/docs.json +2836 -0
  7. package/docs/extending/agent-preset.md +37 -0
  8. package/docs/extending/chat-command.md +28 -0
  9. package/docs/extending/client-slot.md +135 -0
  10. package/docs/extending/config-schema.md +7 -0
  11. package/docs/extending/cordis-core.md +63 -0
  12. package/docs/extending/desktop-app.md +53 -0
  13. package/docs/extending/desktop-main.md +25 -0
  14. package/docs/extending/event-hook.md +14 -0
  15. package/docs/extending/host-route.md +33 -0
  16. package/docs/extending/llm-adapter.md +38 -0
  17. package/docs/extending/packaging.md +53 -0
  18. package/docs/extending/prompt-contribution.md +9 -0
  19. package/docs/extending/service.md +13 -0
  20. package/docs/extending/skill-provider.md +9 -0
  21. package/docs/extending/state-and-persistence.md +71 -0
  22. package/docs/extending/three-role-capability.md +33 -0
  23. package/docs/extending/tool-plugin.md +24 -0
  24. package/docs/extending/tui-command.md +8 -0
  25. package/docs/extending/tui-components.md +61 -0
  26. package/docs/extending/ui-branding.md +43 -0
  27. package/docs/extending/ui-components.md +56 -0
  28. package/docs/extending/ui-customization.md +41 -0
  29. package/docs/extending/ui-library.md +66 -0
  30. package/docs/extending/ui-theme.md +55 -0
  31. package/docs/extending/workspace-tab.md +50 -0
  32. package/docs/maps/events.md +108 -0
  33. package/docs/maps/mount-points.md +154 -0
  34. package/docs/maps/slot-contracts.md +3376 -0
  35. package/docs/maps/taxonomy.md +306 -0
  36. package/docs/maps/theme-tokens.md +115 -0
  37. package/docs/maps/ui-components.md +26 -0
  38. package/docs/reference/cookbook/adding-a-package.md +174 -0
  39. package/docs/reference/cookbook/adding-a-remote-api.md +199 -0
  40. package/docs/reference/cookbook/adding-a-settings-card.md +74 -0
  41. package/docs/reference/cookbook/adding-a-tool.md +103 -0
  42. package/docs/reference/cookbook/adding-an-llm-adapter.md +45 -0
  43. package/docs/reference/cookbook/extension-cookbook.md +134 -0
  44. package/docs/reference/cordis-api/context.md +366 -0
  45. package/docs/reference/cordis-api/events.md +209 -0
  46. package/docs/reference/cordis-api/fiber.md +377 -0
  47. package/docs/reference/cordis-api/inherited.md +40 -0
  48. package/docs/reference/cordis-api/registry.md +154 -0
  49. package/docs/reference/cordis-api/service.md +104 -0
  50. package/docs/reference/cordis-guides/cordis-usage-cheatsheet.md +167 -0
  51. package/docs/reference/cordis-guides/cordis_system_guide_for_coding_agents.md +4666 -0
  52. package/docs/reference/cordis-guides/development-canvas-plugin.md +109 -0
  53. package/docs/reference/cordis-guides/hello-world-plugin-guide.md +517 -0
  54. package/docs/reference/harness/agent-lifecycle.md +93 -0
  55. package/docs/reference/harness/architecture.md +168 -0
  56. package/docs/reference/harness/capability-seams.md +675 -0
  57. package/docs/reference/harness/config-catalog.md +4523 -0
  58. package/docs/reference/harness/cordis-primer.md +47 -0
  59. package/docs/reference/harness/defensive-patterns.md +35 -0
  60. package/docs/reference/harness/event-producer-consumer.md +111 -0
  61. package/docs/reference/harness/glossary.md +47 -0
  62. package/docs/reference/harness/tool-catalog.md +2721 -0
  63. package/docs/reference/harness/tool-execution-pipeline.md +67 -0
  64. package/docs/reference/subsystems/README.md +75 -0
  65. package/docs/reference/subsystems/agent-team.md +233 -0
  66. package/docs/reference/subsystems/approval.md +172 -0
  67. package/docs/reference/subsystems/attachment.md +363 -0
  68. package/docs/reference/subsystems/boot.md +324 -0
  69. package/docs/reference/subsystems/browser-use.md +69 -0
  70. package/docs/reference/subsystems/client-modules.md +186 -0
  71. package/docs/reference/subsystems/client-resources.md +94 -0
  72. package/docs/reference/subsystems/commands.md +225 -0
  73. package/docs/reference/subsystems/compaction.md +286 -0
  74. package/docs/reference/subsystems/computer-use.md +58 -0
  75. package/docs/reference/subsystems/conversation.md +287 -0
  76. package/docs/reference/subsystems/core.md +1107 -0
  77. package/docs/reference/subsystems/credentials.md +497 -0
  78. package/docs/reference/subsystems/deliverables.md +180 -0
  79. package/docs/reference/subsystems/extensions.md +386 -0
  80. package/docs/reference/subsystems/feedback.md +402 -0
  81. package/docs/reference/subsystems/filesystem.md +532 -0
  82. package/docs/reference/subsystems/goal.md +315 -0
  83. package/docs/reference/subsystems/invariants.md +90 -0
  84. package/docs/reference/subsystems/jobs.md +501 -0
  85. package/docs/reference/subsystems/llm-streaming.md +1131 -0
  86. package/docs/reference/subsystems/lsp.md +204 -0
  87. package/docs/reference/subsystems/mcp.md +141 -0
  88. package/docs/reference/subsystems/office-to-pdf.md +89 -0
  89. package/docs/reference/subsystems/otel.md +46 -0
  90. package/docs/reference/subsystems/permission-presets.md +169 -0
  91. package/docs/reference/subsystems/persistence.md +418 -0
  92. package/docs/reference/subsystems/plan.md +89 -0
  93. package/docs/reference/subsystems/product-telemetry.md +81 -0
  94. package/docs/reference/subsystems/ptc-runtime.md +234 -0
  95. package/docs/reference/subsystems/sandbox.md +223 -0
  96. package/docs/reference/subsystems/schedule.md +545 -0
  97. package/docs/reference/subsystems/scope.md +61 -0
  98. package/docs/reference/subsystems/session-projection.md +358 -0
  99. package/docs/reference/subsystems/session-query.md +511 -0
  100. package/docs/reference/subsystems/session-reference.md +226 -0
  101. package/docs/reference/subsystems/session-telemetry.md +214 -0
  102. package/docs/reference/subsystems/session-title.md +206 -0
  103. package/docs/reference/subsystems/session.md +1300 -0
  104. package/docs/reference/subsystems/settings.md +157 -0
  105. package/docs/reference/subsystems/shell.md +316 -0
  106. package/docs/reference/subsystems/sidebar-right.md +160 -0
  107. package/docs/reference/subsystems/skills.md +354 -0
  108. package/docs/reference/subsystems/slots.md +201 -0
  109. package/docs/reference/subsystems/spill.md +126 -0
  110. package/docs/reference/subsystems/ssh.md +137 -0
  111. package/docs/reference/subsystems/storage.md +262 -0
  112. package/docs/reference/subsystems/subagent.md +762 -0
  113. package/docs/reference/subsystems/subprocess.md +323 -0
  114. package/docs/reference/subsystems/system-prompt.md +226 -0
  115. package/docs/reference/subsystems/terminal.md +186 -0
  116. package/docs/reference/subsystems/todo.md +34 -0
  117. package/docs/reference/subsystems/token-meter.md +108 -0
  118. package/docs/reference/subsystems/tools.md +749 -0
  119. package/docs/reference/subsystems/typert.md +489 -0
  120. package/docs/reference/subsystems/user-questions.md +309 -0
  121. package/docs/reference/subsystems/voice-input.md +166 -0
  122. package/docs/reference/subsystems/web-client.md +102 -0
  123. package/docs/reference/subsystems/web-server.md +228 -0
  124. package/docs/reference/subsystems/web.md +208 -0
  125. package/docs/reference/subsystems/webhook.md +72 -0
  126. package/docs/reference/subsystems/workflow.md +280 -0
  127. package/docs/reference/subsystems/workspace.md +661 -0
  128. package/docs/start-here/blueprints.md +33 -0
  129. package/docs/start-here/this-runtime.md +84 -0
  130. package/docs/start-here/troubleshooting.md +29 -0
  131. package/docs/start-here/trust-and-safety.md +39 -0
  132. package/docs/start-here/verify-before-done.md +46 -0
  133. package/example-plugins/README.md +45 -0
  134. package/example-plugins/packages/agent-preset-reviewer/agent.cordis.yml +18 -0
  135. package/example-plugins/packages/agent-preset-reviewer/preset.yml +3 -0
  136. package/example-plugins/packages/capability-swap-consumer/cordis.patch.yml +3 -0
  137. package/example-plugins/packages/capability-swap-consumer/index.js +14 -0
  138. package/example-plugins/packages/capability-swap-consumer/package.json +25 -0
  139. package/example-plugins/packages/capability-swap-provider-loud/cordis.patch.yml +3 -0
  140. package/example-plugins/packages/capability-swap-provider-loud/index.js +20 -0
  141. package/example-plugins/packages/capability-swap-provider-loud/package.json +25 -0
  142. package/example-plugins/packages/capability-swap-provider-quiet/cordis.patch.yml +3 -0
  143. package/example-plugins/packages/capability-swap-provider-quiet/index.js +20 -0
  144. package/example-plugins/packages/capability-swap-provider-quiet/package.json +25 -0
  145. package/example-plugins/packages/chat-command-basic/cordis.patch.yml +3 -0
  146. package/example-plugins/packages/chat-command-basic/index.js +26 -0
  147. package/example-plugins/packages/chat-command-basic/package.json +25 -0
  148. package/example-plugins/packages/client-chat-message-action/client.js +46 -0
  149. package/example-plugins/packages/client-chat-message-action/cordis.patch.yml +3 -0
  150. package/example-plugins/packages/client-chat-message-action/index.js +9 -0
  151. package/example-plugins/packages/client-chat-message-action/package.json +31 -0
  152. package/example-plugins/packages/client-slot-header-action/client.js +57 -0
  153. package/example-plugins/packages/client-slot-header-action/cordis.patch.yml +3 -0
  154. package/example-plugins/packages/client-slot-header-action/index.js +13 -0
  155. package/example-plugins/packages/client-slot-header-action/package.json +31 -0
  156. package/example-plugins/packages/client-slot-sidebar-tab/client.js +57 -0
  157. package/example-plugins/packages/client-slot-sidebar-tab/cordis.patch.yml +3 -0
  158. package/example-plugins/packages/client-slot-sidebar-tab/index.js +9 -0
  159. package/example-plugins/packages/client-slot-sidebar-tab/package.json +32 -0
  160. package/example-plugins/packages/client-theme-override/client.js +52 -0
  161. package/example-plugins/packages/client-theme-override/cordis.patch.yml +3 -0
  162. package/example-plugins/packages/client-theme-override/index.js +9 -0
  163. package/example-plugins/packages/client-theme-override/package.json +30 -0
  164. package/example-plugins/packages/client-tool-view/client.js +47 -0
  165. package/example-plugins/packages/client-tool-view/cordis.patch.yml +3 -0
  166. package/example-plugins/packages/client-tool-view/index.js +24 -0
  167. package/example-plugins/packages/client-tool-view/package.json +34 -0
  168. package/example-plugins/packages/client-ui-components/client.js +77 -0
  169. package/example-plugins/packages/client-ui-components/cordis.patch.yml +3 -0
  170. package/example-plugins/packages/client-ui-components/index.js +9 -0
  171. package/example-plugins/packages/client-ui-components/package.json +31 -0
  172. package/example-plugins/packages/client-ui-library/client.js +715 -0
  173. package/example-plugins/packages/client-ui-library/cordis.patch.yml +3 -0
  174. package/example-plugins/packages/client-ui-library/index.js +9 -0
  175. package/example-plugins/packages/client-ui-library/package.json +37 -0
  176. package/example-plugins/packages/client-workspace-tab/client.js +72 -0
  177. package/example-plugins/packages/client-workspace-tab/cordis.patch.yml +3 -0
  178. package/example-plugins/packages/client-workspace-tab/index.js +9 -0
  179. package/example-plugins/packages/client-workspace-tab/package.json +30 -0
  180. package/example-plugins/packages/config-schema-basic/cordis.patch.yml +3 -0
  181. package/example-plugins/packages/config-schema-basic/index.js +19 -0
  182. package/example-plugins/packages/config-schema-basic/package.json +25 -0
  183. package/example-plugins/packages/desktop-main-profile-info/cordis.patch.yml +3 -0
  184. package/example-plugins/packages/desktop-main-profile-info/index.js +22 -0
  185. package/example-plugins/packages/desktop-main-profile-info/package.json +25 -0
  186. package/example-plugins/packages/event-hook-basic/cordis.patch.yml +3 -0
  187. package/example-plugins/packages/event-hook-basic/index.js +17 -0
  188. package/example-plugins/packages/event-hook-basic/package.json +22 -0
  189. package/example-plugins/packages/generated-capability-template/cordis.patch.yml +3 -0
  190. package/example-plugins/packages/generated-capability-template/index.js +16 -0
  191. package/example-plugins/packages/generated-capability-template/package.json +42 -0
  192. package/example-plugins/packages/host-route-basic/cordis.patch.yml +3 -0
  193. package/example-plugins/packages/host-route-basic/index.js +20 -0
  194. package/example-plugins/packages/host-route-basic/package.json +29 -0
  195. package/example-plugins/packages/lifecycle-function-basic/cordis.patch.yml +3 -0
  196. package/example-plugins/packages/lifecycle-function-basic/index.js +12 -0
  197. package/example-plugins/packages/lifecycle-function-basic/package.json +15 -0
  198. package/example-plugins/packages/lifecycle-function-hot-shim/cordis.patch.yml +3 -0
  199. package/example-plugins/packages/lifecycle-function-hot-shim/impl.js +5 -0
  200. package/example-plugins/packages/lifecycle-function-hot-shim/index.js +18 -0
  201. package/example-plugins/packages/lifecycle-function-hot-shim/package.json +23 -0
  202. package/example-plugins/packages/lifecycle-hooks-observer/cordis.patch.yml +3 -0
  203. package/example-plugins/packages/lifecycle-hooks-observer/index.js +23 -0
  204. package/example-plugins/packages/lifecycle-hooks-observer/package.json +22 -0
  205. package/example-plugins/packages/llm-adapter-echo/cordis.patch.yml +3 -0
  206. package/example-plugins/packages/llm-adapter-echo/index.js +42 -0
  207. package/example-plugins/packages/llm-adapter-echo/package.json +25 -0
  208. package/example-plugins/packages/prompt-assemble-hook/cordis.patch.yml +3 -0
  209. package/example-plugins/packages/prompt-assemble-hook/index.js +22 -0
  210. package/example-plugins/packages/prompt-assemble-hook/package.json +22 -0
  211. package/example-plugins/packages/prompt-contribution-basic/cordis.patch.yml +3 -0
  212. package/example-plugins/packages/prompt-contribution-basic/index.js +18 -0
  213. package/example-plugins/packages/prompt-contribution-basic/package.json +22 -0
  214. package/example-plugins/packages/service-consumer-greeter/cordis.patch.yml +3 -0
  215. package/example-plugins/packages/service-consumer-greeter/index.js +14 -0
  216. package/example-plugins/packages/service-consumer-greeter/package.json +22 -0
  217. package/example-plugins/packages/service-provider-greeter/cordis.patch.yml +3 -0
  218. package/example-plugins/packages/service-provider-greeter/index.js +22 -0
  219. package/example-plugins/packages/service-provider-greeter/package.json +25 -0
  220. package/example-plugins/packages/settings-section-basic/cordis.patch.yml +3 -0
  221. package/example-plugins/packages/settings-section-basic/index.js +34 -0
  222. package/example-plugins/packages/settings-section-basic/package.json +26 -0
  223. package/example-plugins/packages/skill-provider-basic/cordis.patch.yml +3 -0
  224. package/example-plugins/packages/skill-provider-basic/index.js +31 -0
  225. package/example-plugins/packages/skill-provider-basic/package.json +22 -0
  226. package/example-plugins/packages/state-host-store/client.js +57 -0
  227. package/example-plugins/packages/state-host-store/cordis.patch.yml +3 -0
  228. package/example-plugins/packages/state-host-store/index.js +90 -0
  229. package/example-plugins/packages/state-host-store/package.json +31 -0
  230. package/example-plugins/packages/state-workspace-file/cordis.patch.yml +3 -0
  231. package/example-plugins/packages/state-workspace-file/index.js +52 -0
  232. package/example-plugins/packages/state-workspace-file/package.json +25 -0
  233. package/example-plugins/packages/tool-basic/cordis.patch.yml +3 -0
  234. package/example-plugins/packages/tool-basic/index.js +25 -0
  235. package/example-plugins/packages/tool-basic/package.json +25 -0
  236. package/example-plugins/packages/tool-policy-hook/cordis.patch.yml +3 -0
  237. package/example-plugins/packages/tool-policy-hook/index.js +28 -0
  238. package/example-plugins/packages/tool-policy-hook/package.json +25 -0
  239. package/example-plugins/packages/tui-command-basic/cordis.patch.yml +3 -0
  240. package/example-plugins/packages/tui-command-basic/index.js +24 -0
  241. package/example-plugins/packages/tui-command-basic/package.json +22 -0
  242. package/example-plugins/packages/tui-overlay-themed/cordis.patch.yml +3 -0
  243. package/example-plugins/packages/tui-overlay-themed/index.js +65 -0
  244. package/example-plugins/packages/tui-overlay-themed/package.json +25 -0
  245. package/example-plugins/packages/tui-ui-library/cordis.patch.yml +3 -0
  246. package/example-plugins/packages/tui-ui-library/index.js +73 -0
  247. package/example-plugins/packages/tui-ui-library/package.json +29 -0
  248. package/example-plugins/packages/web-page-branding/cordis.patch.yml +3 -0
  249. package/example-plugins/packages/web-page-branding/index.js +31 -0
  250. package/example-plugins/packages/web-page-branding/package.json +22 -0
  251. package/example-plugins/scenarios.json +11 -0
  252. package/index.js +384 -0
  253. package/lib/blend-apply.js +107 -0
  254. package/lib/blend-capture.js +249 -0
  255. package/lib/blend-ledger.js +76 -0
  256. package/lib/contract.js +5 -0
  257. package/lib/install.js +516 -0
  258. package/lib/lookup.js +67 -0
  259. package/lib/manifest.js +56 -0
  260. package/lib/pack-root.js +22 -0
  261. package/lib/provenance.js +110 -0
  262. package/lib/publish.js +64 -0
  263. package/lib/reconcile.js +83 -0
  264. package/lib/router.js +55 -0
  265. package/lib/scopes.js +82 -0
  266. package/lib/skills.js +54 -0
  267. package/lib/stage.js +157 -0
  268. package/lib/verify.js +77 -0
  269. package/package.json +58 -3
  270. package/scripts/lib/indexes.mjs +45 -0
  271. package/scripts/lib/manifest.mjs +127 -0
  272. package/scripts/lib/maps.mjs +482 -0
  273. package/skills/acryl-add-provider-or-capability/SKILL.md +12 -0
  274. package/skills/acryl-add-ui/SKILL.md +18 -0
  275. package/skills/acryl-build-plugin/SKILL.md +21 -0
  276. package/skills/acryl-change-plugin/SKILL.md +16 -0
  277. package/skills/acryl-desktop-shell/SKILL.md +12 -0
  278. package/skills/acryl-diagnose-plugin/SKILL.md +10 -0
  279. package/skills/acryl-fix-plugin/SKILL.md +12 -0
  280. package/skills/acryl-improve-ui/SKILL.md +10 -0
  281. package/skills/acryl-remove-plugin/SKILL.md +11 -0
  282. package/skills/acryl-restyle-ui/SKILL.md +14 -0
  283. package/skills/acryl-share-plugin/SKILL.md +23 -0
  284. package/skills/acryl-tui-ui/SKILL.md +12 -0
@@ -0,0 +1,33 @@
1
+ # Three-role capability: definition, providers, consumers
2
+
3
+ Use this when several interchangeable implementations of one capability should exist (two storage backends, two
4
+ formatters) and other plugins must not care which one is mounted.
5
+
6
+ Working examples, copy from them (each is a real package):
7
+ `../example-plugins/packages/capability-swap-provider-loud/`, `capability-swap-provider-quiet/`, `capability-swap-consumer/`.
8
+
9
+ ## The three roles
10
+
11
+ 1. **Definition**: the service NAME and the method shape (the contract), written down in the provider headers
12
+ and in your doc. Here: service `speller`, `shout(text: string): string`. In a large product the definition is
13
+ its own package with types only; for a plugin you write, a documented name plus shape is enough.
14
+ 2. **Provider**: a `Service` subclass providing that name: `class X extends Service { constructor(ctx) { super(ctx, 'speller') } }`,
15
+ exported as `apply`. Only ONE provider of a name may be mounted at a time (a second is rejected), so a swap is
16
+ "disable one row, enable the other".
17
+ 3. **Consumer**: `export const inject = ['speller']`. It never imports or names a provider. While no provider is
18
+ mounted it is PENDING (healthy); when one appears it becomes ACTIVE; when the provider is swapped it remounts
19
+ against the new one without changes.
20
+
21
+ ## Swapping providers
22
+
23
+ Each provider package is a row (`cordis.patch.yml`). To swap, deactivate the old provider package and install or
24
+ activate the new one (the install tool updates in place; use the remove tool for the old one). The real-engine
25
+ test in the repository mounts loud, disposes it, mounts quiet, and checks the consumer stays ACTIVE and now
26
+ gets the quiet behavior.
27
+
28
+ ## Rules
29
+
30
+ - Depend on the NAME, never on a provider. Read optional capabilities with `ctx.get('name')` at call time.
31
+ - Keep the contract small and stable: adding a method is safe; changing one breaks every consumer.
32
+ - The provider owns its resources in effects so a swap releases them.
33
+ - More detail on why capabilities are split this way: `reference/harness/capability-seams.md`.
@@ -0,0 +1,24 @@
1
+ # Tool plugins: give the agent a new capability
2
+
3
+ A tool is a plugin that injects `tools` and registers a definition the model can call.
4
+ Example: `../example-plugins/packages/tool-basic/`.
5
+
6
+ ```js
7
+ import { defineTool } from '@deepseek-ai/dsh-tools'
8
+ export const name = 'my-tool'
9
+ export const inject = ['tools']
10
+ export function apply(ctx) {
11
+ ctx.tools.register(defineTool({
12
+ name: 'my_tool', description: 'What the model sees.',
13
+ parameters: { path: { type: 'string', required: true, description: '...' } },
14
+ output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
15
+ async execute(args, exec) { /* args are validated and typed; honor exec.signal */ return 'result' },
16
+ }))
17
+ }
18
+ ```
19
+
20
+ Rules: arguments are validated for you; `execute` returns one JSON-serializable value matching
21
+ `output.schema`; a throw becomes a tool error; cancel work when `exec.signal` aborts; keep
22
+ `presentCall`/`presentResult` (UI cards) pure. Registration is an effect: disposing the plugin
23
+ unregisters the tool. Full contract: `reference/cookbook/adding-a-tool.md`.
24
+ The package needs `@deepseek-ai/dsh-tools` as a dependency.
@@ -0,0 +1,8 @@
1
+ # Terminal (tui) commands
2
+
3
+ Example: `../example-plugins/packages/tui-command-basic/`. The CLI host provides `tuiCommands`; read it
4
+ with `ctx.get('tuiCommands')` (optional, absent on web and desktop, never `inject` it) and
5
+ `commands.register({ command: '/name', description, packageName, open({ tui, close }) => Component })`,
6
+ inside `ctx.effect` (it returns a disposer). A `Component` is a pi-tui object:
7
+ `render(width) => string[]`, `handleInput?(data)`, `invalidate()`. Name collisions never throw; they are
8
+ addressed as `/name:<package>`. Source: `apps/acryl-cli/src/tui/tui-commands-service.ts`.
@@ -0,0 +1,61 @@
1
+ # The terminal UI (CLI): pi-tui components, theming and branding
2
+
3
+ Working example, copy from it: `../example-plugins/packages/tui-overlay-themed/` (themed `SelectList` overlay; a test renders it at five widths
4
+ and checks no line overflows). Basic command registration: `../example-plugins/packages/tui-command-basic/` and `tui-command.md`.
5
+
6
+ ## What a plugin can do in the terminal
7
+
8
+ Exactly one presentation seam: `ctx.get('tuiCommands')?.register({ command: '/name', description, packageName, overlay?, open({ tui, close }) })`.
9
+ `open` returns a pi-tui `Component`. The overlay is full screen by default; pass `overlay: { width: '60%', anchor: 'center', margin: 2 }`
10
+ for a popup. The command list refreshes live when a plugin registers or removes a command, so a newly installed command works without restarting the TUI. The built-in overlays
11
+ (`/model`, `/plugins`, `/tools`, `/trajectory`, ...) and the chat view are not replaceable. Everything else works through tools,
12
+ commands (`ctx.commands`) and prompts, which have no visual design.
13
+
14
+ ## pi-tui in one page
15
+
16
+ `@earendil-works/pi-tui` (pinned by the CLI; list it as a dependency of your plugin) renders to native terminal scrollback. A
17
+ **Component** is `{ render(width): string[], handleInput?(keyData): void, invalidate(): void }`:
18
+
19
+ - `render(width)` returns one string per line. **No line may be wider than `width`** (visible columns, ANSI colors not counted).
20
+ Use `truncateToWidth(line, width)`, `wrapTextWithAnsi(text, width)` and `visibleWidth(text)` from pi-tui; never rely on `.length`.
21
+ - `handleInput(keyData)` receives raw key data; match with `matchesKey(data, Key.enter)`, `Key.escape`, `Key.up`, ...
22
+ - Built-ins: `Container` (children), `VStack`/`HStack` (layout), `Box` (padding, background), `Text`, `TruncatedText`, `Markdown`,
23
+ `SelectList` (choose from items; `onSelect`, `onCancel`), `SettingsList`, `Input`, `Editor` (multi-line), `ScrollView`,
24
+ `Loader`/`CancellableLoader`, `Spacer`, `Image`.
25
+ - Colors are functions `string -> string` that wrap ANSI escapes. The built-in components take theme objects of such functions
26
+ (`SelectListTheme`, `EditorTheme`, `MarkdownTheme`, `SettingsListTheme`).
27
+
28
+ ## Theming in the terminal
29
+
30
+ - The terminal owns its background and default foreground; color FOREGROUNDS for brand, state and emphasis only. Do not paint
31
+ panel backgrounds.
32
+ - Keep a semantic `PALETTE` (primary, secondary, muted, success, warning, error, info) in one object and build the theme
33
+ objects from it (the example does). Use 24-bit color (`\x1b[38;2;r;g;bm`); do not assume a light or dark terminal.
34
+ - The CLI's own palette is generated from the semantic role file `plugins/ui/contracts/tokens.json` (the same roles the web library uses) into
35
+ `apps/acryl-cli/src/tui/palette.generated.ts`, read through `apps/acryl-cli/src/tui/theme.ts` and adapted to pi-tui in `tui/piTheme.ts`. It has a dark and a
36
+ light palette for nine roles (dark: `primary #4F6BFE`, `secondary #38BDF8`, `accent #818CF8`, `reasoning #A855F7`, `success #34D399`, `warning #FBBF24`,
37
+ `error #F87171`, `info #4F6BFE`, `muted #94A3B8`). The palette follows the terminal: at startup ACRYL asks the terminal whether its background is light or dark and follows it when it changes;
38
+ `ACRYL_TUI_THEME=dark|light` pins it, `COLORFGBG` is the fallback, dark the default. A plugin reads it through the read-only `tuiTheme` service (`ctx.get('tuiTheme')`: `mode`, `hex(role)`, `color(role)`,
39
+ `onChange`) instead of carrying its own palette, and builds screens with the terminal UI library `@acryldev/ui-tui` (see `ui-library.md`).
40
+
41
+ ## Branding in the terminal (source change and rebuild)
42
+
43
+ Banner and wordmark: `apps/acryl-cli/src/tui/acrylMark.ts` (half-block art), `bannerText.ts`, `logoArt.generated.ts`, the mascot in
44
+ `apps/acryl-cli/src/yly/`, the palette in `tui/theme.ts`. Changing these means editing the repository and rebuilding
45
+ (`corepack pnpm run tui` runs the dev build). Only when working inside the ACRYL repository; an installed CLI cannot be restyled by a
46
+ plugin. Say that, and offer a themed overlay instead.
47
+
48
+ ## Keys in the terminal
49
+
50
+ An overlay receives keys through `handleInput(data)`: match with `matchesKey(data, Key.enter)`, `Key.escape`, `Key.up`, `Key.ctrl('k')`, and so on. Keys apply only
51
+ while your overlay is focused; there is no global shortcut registry for plugins in the CLI, and the built-in editor and overlay key bindings are not
52
+ plugin-changeable. Always handle Escape to close.
53
+
54
+ ## Rules
55
+
56
+ 1. Width safety first: test `render` at several widths (12, 24, 40, 80, 200). Wide characters (CJK, emoji) need `visibleWidth`.
57
+ 2. Handle Escape and Enter; always call `close()`; never leave the terminal in raw state.
58
+ 3. Keep overlays small and fast; no network in `render`.
59
+ 4. Do not write to stdout directly; return lines.
60
+ 5. State honestly that you could not see it: ask the user to run the command in a real terminal.
61
+ 6. Reference: `reference/subsystems/commands.md` (chat commands, a different seam), the pi-tui typings in `node_modules/@earendil-works/pi-tui/dist`.
@@ -0,0 +1,43 @@
1
+ # Branding: logo, name, tab title, favicon, page shell
2
+
3
+ Working examples: `../example-plugins/packages/web-page-branding/` (host: title, favicon, CSS row, verified against the real web server
4
+ in a test) and `../example-plugins/packages/client-theme-override/` (client: keeps a custom tab title, recolors). ACRYL's own brand is
5
+ `plugins/brand-client` in the repository (a reference, not something to edit from a plugin).
6
+
7
+ ## Layers of branding, from most to least pluggable
8
+
9
+ 1. **Brand slots (Web and Desktop client).** Three single-occupant slots hold the identity: `sidebar.brand.mark`,
10
+ `sidebar.brand.name`, `conversation.hero.brand.mark` (see `../maps/mount-points.md`). ACRYL's brand package occupies them. A
11
+ slot is single-occupant, so to show a different mark you must swap the brand package (the Loader row `ui-acryl` is disabled
12
+ or replaced), not register a second occupant. That is a profile composition change: tell the user; do not do it silently.
13
+ 2. **Colors and fonts.** `ui-theme.md`. The accent token is `--dsw-alias-brand-primary`.
14
+ 3. **Page shell (host).** The web server assembles `index.html`. Two seams, both usable from a host plugin:
15
+ - `ctx.on('webserver/index-inject', table => table.push(row))` with structured rows:
16
+ `{ kind: 'style', text }`, `{ kind: 'html', placement: 'head' | 'body', html }` (a `<link rel="icon">`),
17
+ `{ kind: 'global', name, value }`, `{ kind: 'script', placement, text }`, `{ kind: 'script-src', placement, src }`.
18
+ - `ctx.get('webServer')?.tapIndex(html => html)` a raw transform that runs after the rows.
19
+ Use them for the favicon, a pre-boot background (avoids a flash), and analytics-free tweaks. Reload the page to see them.
20
+ 4. **The tab and window TITLE.** The served `<title>` is only the pre-boot title. Once the app starts, the client rewrites
21
+ `document.title` from a locale string (`<session title> - <product>`) that a plugin cannot replace, overwriting the server's.
22
+ Keep your name with a `MutationObserver` on `document.head` that rewrites the product name; ACRYL's brand plugin does this
23
+ for "ACRYL" and the theme example does it for a custom name. The same code applies to the Desktop window title.
24
+ 5. **Upstream copy.** Text such as the "Internal Testing Notice" is upstream locale text in single-occupant dictionaries; it
25
+ cannot be replaced by a plugin.
26
+
27
+ ## Desktop native branding (NOT a plugin change)
28
+
29
+ The app icon, tray icon, product name (`ACRYL`), app id, installer, title bar style, window vibrancy (macOS) or Mica (Windows),
30
+ and the native menu live in the Electron main process and the build configuration. They change only by editing the ACRYL source
31
+ and rebuilding. See `desktop-app.md` for the exact files. An agent inside an installed app cannot do this: say so.
32
+
33
+ ## CLI branding (NOT a plugin change)
34
+
35
+ The terminal banner, the ACRYL wordmark (half-block art), the palette and the mascot are source files compiled into the CLI. See
36
+ `tui-components.md`. A plugin can only add its own overlays with its own palette.
37
+
38
+ ## Checklist
39
+
40
+ - Ask what to brand (name, mark, colors, font, favicon) and for which surfaces; explain what is live and what needs a rebuild.
41
+ - Keep assets small and local (an inline SVG data URL for a favicon; a bundled file for a font or logo); do not fetch remote assets.
42
+ - Both light and dark mode; readable contrast.
43
+ - Reload, then have the user confirm the tab title, the accent, the favicon and the sidebar.
@@ -0,0 +1,56 @@
1
+ # Ready-made UI components: build with the app's own library
2
+
3
+ > Start with the ACRYL UI library (`ui-library.md`): `@acryldev/ui` (Web and Desktop) and `@acryldev/ui-tui` (CLI) already combine the primitives below into cards, fields, settings rows, dropdowns, tabs and dialogs with
4
+ > the same names on every surface. This page lists the primitives underneath, for when the library has nothing that fits, and the example here (`client-ui-components`) shows them used directly.
5
+
6
+ Use this BEFORE hand-styling any UI. On Web and Desktop the app already ships a themed component library, and a plugin can use it
7
+ today. Working example (verified in a real browser: the modal, input, switch and buttons rendered themed):
8
+ `../example-plugins/packages/client-ui-components/` (read `client.js` and `package.json`). All component names: `../maps/ui-components.md`.
9
+
10
+ ## Web and Desktop: `@deepseek-ai/dsh-client-ui-primitives`
11
+
12
+ ```js
13
+ // client.js
14
+ const React = require('react')
15
+ const { Button, Modal, Input, Switch, Tag, Pill, Tooltip, Toast, Menu } = require('@deepseek-ai/dsh-client-ui-primitives')
16
+ ```
17
+
18
+ and in `package.json`: `"dsh": { "client": { "inject": ["@deepseek-ai/dsh-client-ui-primitives"], "platform": "web" } }` so it loads first.
19
+ No JSX (use `React.createElement`), no `import`. The components follow the theme, so your token overrides (`ui-theme.md`) restyle them too.
20
+
21
+ Props of the common ones (read from the source):
22
+
23
+ | Component | Props |
24
+ | --- | --- |
25
+ | `Button` | `variant?: 'primary' \| 'ghost' \| 'outline' \| 'toolbar'`, `size?: 'md' \| 'sm'`, `icon?`, `className?`, plus any `<button>` attribute (`onClick`, `title`, `disabled`) |
26
+ | `Input` | `icon?`, `className?`, plus any `<input>` attribute (`value`, `onChange`, `placeholder`, `onKeyDown`) |
27
+ | `Switch` | `checked: boolean`, `onChange(next: boolean)`, `label: string` (accessibility name, not drawn), `disabled?`, `title?` |
28
+ | `Tag` | `tone?` (default `'outline'`), `className?`, `children` (a small status label) |
29
+ | `Pill` | `active?`, `onClick?` (interactive when given), `children` |
30
+ | `Modal` | `open`, `onClose`, `title`, `closeLabel` (required unless `headless: true`), `description?`, `footer?`, `children`; closes on Escape; renders in a portal |
31
+ | `Toast` | `text`, `icon?`, `anchor?`, `holdMs?`, `onDone` (you unmount it in `onDone`) |
32
+ | `Tooltip` | `label: string \| () => string`, `side?`, `delayMs?`, `disabled?`, `children` (ONE element that can take a ref) |
33
+ | `Menu` | entries `{ label, onSelect }`, separators and labels (read `src/Menu.tsx` for the exact shape before using) |
34
+ | `MarkdownText`, `CodeBlock`, `DiffBlock`, `TerminalBlock`, `JsonTree` | render agent-style output; read their `src/*.tsx` props first |
35
+
36
+ If a component's props are not listed here, READ its source in the repository (`deepseek-harness/packages/client/ui-primitives/src/<Name>.tsx`)
37
+ or the reference doc; do not guess.
38
+
39
+ ## Which slot to put it in
40
+
41
+ Component libraries fill the same slots as any UI: `../maps/mount-points.md`. Two good first choices: `sidebar.footer.action`
42
+ (root-scoped: renders with or without an open session, receives `{ wide }`; the example) and `conversation.session.header.actions`
43
+ (per session, `client-slot.md`). For a Modal you do not need a slot for the panel itself: it portals to the body.
44
+
45
+ ## CLI
46
+
47
+ The terminal has its own components (pi-tui), documented in `tui-components.md`. There is no shared component contract between the web
48
+ and terminal stacks yet (spec 038 proposes one): build each surface's UI with its own library.
49
+
50
+ ## Rules
51
+
52
+ 1. Prefer these components over hand-written styles: consistent look, both color modes, accessible by default.
53
+ 2. Never import from the harness by file path or bundle your own React: use `require` of the module names above.
54
+ 3. Keep state in the plugin (localStorage or a host route), not in the components.
55
+ 4. Declare every package you `require` in `dsh.client.inject`, otherwise load order is not guaranteed.
56
+ 5. State that you could not see the result and ask the user to check it, in both light and dark.
@@ -0,0 +1,41 @@
1
+ # Changing how ACRYL looks: what you can change, on which surface, and how live
2
+
3
+ Read this first for any request about colors, fonts, branding, logo, layout, "look and feel" or "restyle". Then open the doc
4
+ in the last column. All facts here were checked against the source and, where marked, in a running app.
5
+
6
+ ## The three surfaces
7
+
8
+ - **Web** and **Desktop** render the SAME browser app (React). A client plugin (`client.js`, no build step) changes both
9
+ identically. Desktop wraps that app in an Electron shell (window chrome, icon, menu) that a plugin cannot change.
10
+ - **CLI** is a terminal app (pi-tui). Its look is compiled in; a plugin can add its own themed overlays but cannot restyle the
11
+ built-in screens.
12
+
13
+ ## What to change, where, and whether it is live
14
+
15
+ | I want to change | Web | Desktop | CLI | Live? | Read |
16
+ | --- | --- | --- | --- | --- | --- |
17
+ | Colors, surfaces, borders, accent | `ctx.theme.overrideTokens` (client) | same | not pluggable (compiled palette in `tui/theme.ts`) | reload page or window | `ui-theme.md`, `../maps/theme-tokens.md` |
18
+ | Fonts, text size | `--dsw-font-family` token, `ctx.theme.setFontSize` | same | terminal font is the user's terminal setting | reload | `ui-theme.md` |
19
+ | A whole named theme (user picks it) | `ctx.theme.register` | same | no | reload | `ui-theme.md` |
20
+ | Logo, brand name in sidebar and hero | client slots `sidebar.brand.mark` / `.name`, `conversation.hero.brand.mark` (single occupant: swap the brand package row) | same | wordmark and banner are source files (`acrylMark.ts`, `bannerText.ts`) | reload / rebuild | `ui-branding.md` |
21
+ | Browser tab title, favicon, page background before boot | host: `webserver/index-inject` rows and `tapIndex` | the window title is native (see below) | none | reload | `ui-branding.md` |
22
+ | Add a button, panel, tab, card | client slots, built from the shared components | same | a `tuiCommands` overlay built from pi-tui components | reload page or window (Web, Desktop); live in the TUI | `ui-components.md`, `client-slot.md`, `tui-components.md`, `../maps/mount-points.md` |
23
+ | Layout (sidebar, columns, main view) | slots (`sidebar`, `rightbar`, `conversation.view`) | plus the `desktop.main` frame slot | none | reload | `../maps/mount-points.md` |
24
+ | Window chrome, title bar, vibrancy, app icon, tray, native menu, installer name | no | Electron main process: source edit and rebuild | no | NOT live (rebuild) | `desktop-app.md` |
25
+ | Terminal palette, banner, mascot, built-in overlays | no | no | source edit and rebuild | NOT live (rebuild) | `tui-components.md` |
26
+
27
+ "Reload" means the user reloads the Web page or the Desktop window (Cmd/Ctrl+R). "Rebuild" means editing the ACRYL source
28
+ repository and rebuilding: only possible when you are working inside that repository; an installed app cannot be changed
29
+ that way, so say so and offer the live alternative.
30
+
31
+ ## Rules for restyling
32
+
33
+ 1. Prefer a token override over CSS: it survives upstream changes and respects light and dark mode. Provide BOTH modes.
34
+ 2. Never edit files inside `node_modules`, the harness, or the packaged app: they are overwritten and not yours.
35
+ 3. Keep the change in ONE plugin under `<workspace>/.acryl-plugins/<name>/` so it can be updated or removed as a unit.
36
+ 4. Check contrast: text on the new background must stay readable in both modes.
37
+ 5. After installing, the UI mounts live (no reload needed, except page-level changes outside the app UI); ask the user to look; you cannot see the screen. State what you changed and what you could
38
+ not verify.
39
+ 6. Known limit: some visible text ("Internal Testing Notice", some settings copy) is upstream locale text in
40
+ single-occupant dictionaries. A plugin cannot replace it; do not promise to.
41
+ 7. Never promise to change the CLI's built-in colors or the Desktop window chrome from a plugin. Say what is possible instead.
@@ -0,0 +1,66 @@
1
+ # ACRYL UI library (`@acryldev/ui`): build screens from ready components
2
+
3
+ **It is available; do not spend calls verifying it.** `@acryldev/ui` is composed as its own row on every Web and Desktop profile, the full product and the blank canvas alike, and the
4
+ serving app resolves `require('@acryldev/ui')` for any client bundle that lists it in `dsh.client.inject`. It is not in `@deepseek-ai/dsh-web-app`'s dependencies because it is a row, not a
5
+ dependency: searching the harness packages for it finds nothing and proves nothing. Confirm it with `acryl_list_plugins` (row `@acryldev/ui` ACTIVE), then build. Its `Calendar` (a month grid),
6
+ `Sheet`, `Modal`, `Tabs`, `Card` and `Field` cover most organizer-style screens; the header action or the sidebar footer action slot is the mount point for a first version.
7
+
8
+ Use this instead of hand-styling. It is a client-only package that every Web and Desktop profile carries; a client bundle requires it after listing it in `package.json`:
9
+
10
+ ```json
11
+ "dsh": { "client": { "inject": ["@acryldev/ui", "@deepseek-ai/dsh-client-ui-sidebar"], "platform": "web" } }
12
+ ```
13
+
14
+ ```js
15
+ const ui = require('@acryldev/ui') // then ui.Card, ui.Field, ui.SettingsRow ...
16
+ ```
17
+
18
+ Example: `../example-plugins/packages/client-ui-library/` (a gallery as a Settings page: every component, the color roles, a Settings-style form). Like every example in this pack it is
19
+ **opt-in**, not something a default profile carries: install it yourself with `acryl_install_plugin` (or copy it and run `/reload new`) when you want to browse the catalogue in a
20
+ running app, and remove it with `/reload remove-stale` (or `acryl_install_plugin` with `remove: true`) once you're done, the same as any other local plugin you're finished with. The
21
+ single source of truth for props and accessibility is `contracts/components.json` in the package (`plugins/ui/`); the semantic colors are `contracts/tokens.json`.
22
+
23
+ | Need | Use |
24
+ | --- | --- |
25
+ | Layout | `Stack` (row or column, gap `xs` to `lg`) |
26
+ | A grouped surface | `Card` (title, footer actions) |
27
+ | Text input with label, hint, error | `Field` (`onChange` receives the string) |
28
+ | On/off | `SwitchField` |
29
+ | A settings screen row | `SettingsRow` (label and description left, control right) |
30
+ | Dropdown | `SelectField` (built on the app's own Menu) |
31
+ | Few exclusive tiles (Light, Dark, System) | `Segmented` (a full-width row with its own `title`, like the app's Appearance picker; do not put it inside a `SettingsRow`) |
32
+ | Sections | `Tabs` (active panel as children) |
33
+ | Confirm or destructive action | `Dialog` (built on the app's Modal) |
34
+ | Nothing to show | `EmptyState` |
35
+ | Button, Tag, Pill, Toast, Modal, Tooltip | re-exported from the app's primitives |
36
+ | Register in the app | `settingsSection` (a Settings page), `footerAction`, `headerAction`, `sidebarTab` (slot helpers; the slot is waited for) |
37
+
38
+ Rules that keep it correct:
39
+
40
+ - The library follows light and dark by itself. For any color of your own use `ui.roles.<role>` (the app's own `var(--dsw-alias-*)` token, or for `accent` and `reasoning` the tokens the library registers with the theme service): `text`, `textMuted`, `textDimmed`, `surface`, `surfaceRaised`, `border`, `primary`,
41
+ `success`, `warning`, `error`, `info`, `accent`, `reasoning`. Never write a hex color in your own bundle.
42
+ - Interactive components name themselves: give `SelectField`, `Segmented` and `Tabs` a `label`. `Field` announces its error by itself.
43
+ - The client loader treats every module as a plugin: a pure library needs an (empty) `apply`; a consumer that fills a slot declares `inject = ['slots']`.
44
+
45
+ ## In the terminal (`@acryldev/ui-tui`)
46
+
47
+ The same component names exist for the CLI, built on pi-tui, and every one is width-safe (no line is ever wider than the terminal) and keyboard-driven. A terminal plugin imports the library
48
+ (it is made resolvable in the CLI profile) and hands it the CLI's palette service so colors follow the terminal's light or dark scheme:
49
+
50
+ ```js
51
+ import { createTuiUi } from '@acryldev/ui-tui'
52
+ export function apply(ctx) {
53
+ const ui = createTuiUi(ctx.get('tuiTheme')) // omit for the static dark palette; undefined outside the CLI
54
+ ctx.get('tuiCommands')?.register({ command: '/settings', description: 'Settings', packageName: 'my-plugin', overlay: { width: '70%' },
55
+ open: ({ close }) => ui.Card({ title: 'Settings', body: [ui.SettingsRow({ label: 'Theme', control: ui.Segmented({ options: [{ id: 'l', label: 'Light' }, { id: 'd', label: 'Dark' }], value: 'd' }) })] }) })
56
+ }
57
+ ```
58
+
59
+ Keys: arrows move a `Segmented`, `SelectField` or `Tabs`; space or enter toggles a `SwitchField`; `y`/enter and `n`/Esc answer a `Dialog`; Tab and Shift+Tab switch `Tabs`. `ctx.get('tuiTheme')` is read-only
60
+ (`mode`, `hex(role)`, `color(role)`, `onChange`); the mode is the user's (`ACRYL_TUI_THEME=dark|light`) or the terminal's, never a plugin's. Example: `../example-plugins/packages/tui-ui-library/` (`/gallery`).
61
+
62
+
63
+ ## Where the parts come from
64
+
65
+ The web components are copied from DSH's own source, not redrawn (`plugins/ui/registry-manifest.yml` lists the origin of each and `tests/library.spec.tsx` guards it): the Appearance tiles, the Permission pill and row layout, the tab strip, the plugin field controls and the card surface. They are built with CSS Modules the way DSH builds its own client, so
66
+ the styles are plugin-owned and follow the app's tokens. Only `EmptyState` and `Stack` are new, because DSH has no equivalent.
@@ -0,0 +1,55 @@
1
+ # Theme, colors and fonts for Web and Desktop (the client `theme` service)
2
+
3
+ Working example, copy from it: `../example-plugins/packages/client-theme-override/` (`client.js` and `index.js`). Verified in a real
4
+ browser: the accent color, the font, the tab title and the page background all changed.
5
+ Token names: `../maps/theme-tokens.md` (generated, every `--dsw-alias-*` with light and dark values).
6
+
7
+ ## How theming works
8
+
9
+ The app styles read CSS custom properties: `--dsw-alias-*` design tokens (backgrounds, borders, brand, buttons, labels, states),
10
+ `--dsw-font-family`, corner and shadow tokens. Two built-in themes exist, `light` and `dark`; the user's preference (`light`,
11
+ `dark` or `system`) picks one. The client `theme` service (`ctx.theme`) lets a plugin change tokens without a stylesheet. The
12
+ same service and presenter run on Web and Desktop, so the code is identical.
13
+
14
+ ## The API (inside `client.js`, `exports.inject = ['theme']`)
15
+
16
+ ```js
17
+ exports.inject = ['theme']
18
+ exports.apply = function apply(ctx) {
19
+ ctx.effect(() => ctx.theme.overrideTokens('my-plugin-id', {
20
+ '--dsw-alias-brand-primary': { light: '#e8590c', dark: '#ff922b' }, // BOTH modes are mandatory
21
+ '--dsw-font-family': { light: "Georgia, serif", dark: "Georgia, serif" },
22
+ }), 'my-plugin: token layer')
23
+ }
24
+ ```
25
+
26
+ - `ctx.theme.overrideTokens(sourceId, { token: { light, dark } })` stacks a layer over the active theme and returns a disposer.
27
+ One layer per `sourceId`: calling again replaces it. A bare string value throws a teaching error. Later layers win per token.
28
+ - `ctx.theme.register({ id, colorScheme: 'light' | 'dark', tokens: { '--token': 'value' } })` adds a selectable theme. Duplicate ids
29
+ throw. Selecting it (`ctx.theme.setTheme(id)`) changes the user's SAVED preference: only do that if they asked.
30
+ - `ctx.theme.setFontSize(px)` changes conversation text size (integer, within the allowed range) and is also a saved preference.
31
+ - `ctx.theme.getTheme()` returns the current snapshot (`preference`, `fontSize`, `active`, `themes`); the `theme/change` event
32
+ fires on every change. `ctx.theme.exportInspectTokens()` lists the documented tokens.
33
+ - Register inside `ctx.effect` so the layer is removed when the plugin is removed or updated, restoring the base theme.
34
+
35
+ ## Fonts
36
+
37
+ - Override `--dsw-font-family` with a CSS font-family list. System fonts need nothing else.
38
+ - A web font: add an `@font-face` `<style>` (from `client.js` with `document.head.appendChild`, or a host `webserver/index-inject`
39
+ `style` row, see `ui-branding.md`) and reference its family in the token. Use a locally bundled file or a font the user
40
+ provided; do not hotlink third-party fonts without saying so (privacy and offline use).
41
+ - Code and monospace text use their own tokens; check `../maps/theme-tokens.md` for the exact name before overriding.
42
+ - Content size: `ctx.theme.setFontSize`; the conversation scales from `--dsh-content-font-size`.
43
+
44
+ ## What this cannot do
45
+
46
+ - Rewrite component layout or markup (use slots, `../maps/mount-points.md`).
47
+ - Change the CLI (no theme service in the terminal; `tui-components.md`).
48
+ - Change Desktop window chrome (`desktop-app.md`).
49
+ - Replace upstream locale text (`ui-customization.md`, rule 6).
50
+
51
+ ## Verify
52
+
53
+ Install with `acryl_install_plugin` (it mounts live; one reload only if the user reports it missing), and have them check both light and dark. Add
54
+ `console.info('[<name>] ...')` at load and apply: the browser console shows whether the layer registered (the example does).
55
+ Reference: `reference/subsystems/client-modules.md`, `reference/subsystems/slots.md`; the service source is the `ui-theme` package.
@@ -0,0 +1,50 @@
1
+ # Workspace tab types: add a new kind of tab (whiteboard, board, viewer)
2
+
3
+ Use this when the user wants a new kind of TAB in the workspace (an Excalidraw-style whiteboard, a
4
+ kanban of their own, a log viewer, a diagram). Works on **web** and **desktop**. A tab type is a
5
+ plugin, so it can be turned on and off in Settings > Tabs, and it appears in the "+" menu and the
6
+ command palette.
7
+
8
+ Working example, copy from it: `../example-plugins/packages/client-workspace-tab/` (a whiteboard;
9
+ read `client.js` completely). The package shape is the one in `client-slot.md`: a host half
10
+ `index.js` with an empty `apply()`, a hand-written browser half `client.js`, no build step, no JSX.
11
+
12
+ ## The contract
13
+
14
+ Your browser half injects the `workspaceTabs` service and registers one type per tab kind:
15
+
16
+ ```js
17
+ exports.inject = ['workspaceTabs']
18
+ exports.apply = function apply(ctx) {
19
+ ctx.effect(() => ctx.workspaceTabs.register({
20
+ kind: 'acme.whiteboard', // owner.name: lowercase letters, digits, dashes; unique
21
+ label: 'Whiteboard', // shown in the + menu, 1 to 30 characters
22
+ description: 'One sentence for Settings > Tabs.',
23
+ glyph: '✎', // one or two characters shown on the tab
24
+ component: Whiteboard, // a React component
25
+ }), 'acme-whiteboard: tab type')
26
+ }
27
+ ```
28
+
29
+ `register` returns a disposer; return it from `ctx.effect` so the type disappears when the plugin
30
+ is disabled. It throws when the kind is malformed or already registered; the message names the rule.
31
+
32
+ Your component receives `{ tileId, title, state, setState, setTitle }`:
33
+
34
+ - `state` is the tab's saved state, **text** (use JSON), or `undefined` for a new tab.
35
+ - `setState(next)` replaces it; the workspace saves it with the tabs, at most 200,000 characters
36
+ (a longer value is ignored). Keep the state small: strokes, settings, not images.
37
+ - `setTitle(title)` renames the tab.
38
+
39
+ ## What the workspace guarantees
40
+
41
+ - A tab of your type is restored after a reload with its state.
42
+ - If your plugin is off or not installed when the tab is restored, the tab shows a note and **keeps
43
+ its state**; when the plugin returns, the content is back exactly as it was.
44
+ - Turning the type off in Settings > Tabs hides it from the menu and the palette; open tabs stay.
45
+
46
+ ## What it does not do
47
+
48
+ Your component runs in the app's page with the same access as any client plugin (there is no
49
+ sandbox), so install only plugins you trust. It cannot start terminals or read files by itself; for
50
+ that, add a Host route (`host-route.md`) and call it from the component.
@@ -0,0 +1,108 @@
1
+ # Lifecycle events: where a plugin can hook the agent (Web, Desktop, CLI)
2
+
3
+ <!-- Generated by scripts/sync-corpus.mjs from the `interface Events` declarations in source. Do not edit. -->
4
+
5
+ pi.dev lets an extension intercept input, prompt construction, context, the provider request, tool execution and session lifecycle. ACRYL
6
+ gets the same reach from the harness event bus. Listen with `ctx.on(name, listener)` inside `ctx.effect` (so it leaves with the plugin).
7
+ **Dispatch modes**: `emit` (fire and forget), `parallel` (all run), `serial` and `bail` (in order until a value bails), `waterfall`
8
+ (around-middleware: `ctx.on(name, async (input, next) => { const result = await next(); return result })`; a listener that only observes MUST
9
+ still call `next()` and return its result; the returned value is authoritative). Working example: `example-plugins/packages/prompt-assemble-hook/` (shapes
10
+ the system prompt on `system-prompt/assemble`, the same hook `@acryldev/system-prompt` uses). Read `extending/event-hook.md` first.
11
+
12
+ 93 events:
13
+
14
+ | Event | Mode | What | Declared by |
15
+ | --- | --- | --- | --- |
16
+ | `acryl/agent-runtime-status` | | | @acryldev/control |
17
+ | `acryl/operation-settled` | | | @acryldev/control |
18
+ | `acrylSettings/updated` | emit | Committed change to one registered namespace's resolved value, emitted after the file was written and never when | @acryldev/settings |
19
+ | `agent-loop/config-start-failed` | emit | A declarative agent entry failed before it could publish a live agent. | dsh-agent-loop |
20
+ | `agent-preset/selected` | emit | One session committed a different agent preset to its durable log. | dsh-agent-preset-registry |
21
+ | `agent/assistant-stream` | emit | Process-local assistant-stream publication. Chunk frames are transient; | dsh-agent |
22
+ | `agent/created` | serial | An entered agent is ready for per-agent initialization after factory setup. | dsh-agent |
23
+ | `agent/disposed` | emit | An agent left the registry; AgentLoop emits this after driver quiescence | dsh-agent |
24
+ | `agent/error` | emit | A step or turn errored. The machine reports a failure here even when | dsh-agent |
25
+ | `agent/inbox/claimed` | emit | One message left the inbox inside its open turn. If the proposed step | dsh-agent |
26
+ | `agent/inbox/discarded` | emit | One message was discarded from the live inbox. | dsh-agent |
27
+ | `agent/inbox/inserted` | emit | One message entered the live inbox. | dsh-agent |
28
+ | `agent/pre-step` | waterfall | Reject a proposed step or replace the messages that enter it. Calling | dsh-agent |
29
+ | `agent/request` | waterfall | Replace the frozen call configuration. `await next()` yields the config | dsh-agent |
30
+ | `agent/request-error` | waterfall | Handle one failed model-request attempt before the loop retries or closes | dsh-agent |
31
+ | `agent/status` | emit | Agent status changed (`idle` ⇄ `running`). A waking delivery enters | dsh-agent |
32
+ | `agent/turn-stopping` | serial | The turn is about to close: the model owes no response (no live tool | dsh-agent |
33
+ | `api-session/activity` | emit | One user-authored durable message advanced Session list activity. | dsh-api-session-controller |
34
+ | `api-session/added` | emit | A Session became visible or its Agent was created or disposed. | dsh-api-session-controller |
35
+ | `api-session/error` | emit | One Agent failed outside a durable turn position. | dsh-api-session-controller |
36
+ | `api-session/removed` | emit | A Session left the live Host registry. | dsh-api-session-controller |
37
+ | `api-session/status` | emit | One Agent changed running state. | dsh-api-session-controller |
38
+ | `app-boot/config-reload` | emit | Profile patches were reconciled into the running Loader tree: every entry update settled and no new | dsh-app-boot |
39
+ | `approval/request` | waterfall | Ask composed answerers for one decision. Return an outcome to claim the | dsh-user-approval |
40
+ | `authorization/settled` | emit | One authorization attempt has finished and released its key. Fires for | dsh-authorization |
41
+ | `command/executed` | emit | This browser client completed one admitted Host command execution. | dsh-client-ui-commands |
42
+ | `commands/change` | emit | A command was registered or unregistered. This is an unfiltered registry | dsh-commands |
43
+ | `compaction/summary-error` | waterfall | Recover a failed summary request by synchronously recording a durable | dsh-compaction |
44
+ | `connection/request` | waterfall | Admit or wrap an authenticated shared API request, including body transfer. | dsh-client-connection |
45
+ | `connection/reset` | emit | A connection generation was established. Wire-derived caches must | dsh-client-connection |
46
+ | `cordis/dynamic-package` | emit | One exact Plugin/Package activation is now live in the Host. | dsh-cordis-host-runner |
47
+ | `cordis/dynamic-retract` | emit | One exact activation was withdrawn. | dsh-cordis-host-runner |
48
+ | `cordis/inspect-query` | emit | Request a live read-only query from the Client inspect registry. | dsh-cordis-host-runner |
49
+ | `cordis/inspect-query-resolved` | emit | Notify every Client that an inspect query has settled or been cancelled. | dsh-cordis-host-runner |
50
+ | `cordis/request-run` | emit | A Client-bearing activation needs a browser page, and may require a user decision. | dsh-cordis-host-runner |
51
+ | `cordis/request-run-resolved` | emit | A pending Client activation request left the answerable state. | dsh-cordis-host-runner |
52
+ | `credentials/record-updated` | emit | Committed change to a stored credential record: a `modifyRecord` that | dsh-credentials |
53
+ | `credentials/reference-updated` | emit | Committed change to a provider-managed credential source: a `set`, an | dsh-credentials |
54
+ | `deepseek-account/model-sign-in-required` | emit | An account model request requires the user to sign in. | dsh-deepseek-account |
55
+ | `deepseek-account/session-expired` | emit | Server rejection removed the current account credential; this notification is not replayed. | dsh-deepseek-account |
56
+ | `deepseek-account/signed-out` | emit | Local grant removal has completed. | dsh-deepseek-account |
57
+ | `domain/changed` | emit | A domain record or the global singleton changed, emitted once per write | dsh-storage-domain |
58
+ | `feedback/committed` | parallel | Observe a durable cold feedback mutation without publishing a live Session. | dsh-message-feedback |
59
+ | `fs/edit-intent` | waterfall | Single-slot decision for the next {@link FileSystem.editText}. Calling | dsh-fs |
60
+ | `fs/observed` | emit | Record an authoritative positive or negative observation. Listeners must | dsh-fs |
61
+ | `fs/write-intent` | waterfall | Single-slot decision for the next {@link FileSystem.writeText}. Calling | dsh-fs |
62
+ | `goal/activation-changed` | emit | Process-local goal activation changed for one session. | dsh-goal |
63
+ | `goal/changed` | emit | Goal mutation accepted by one live agent. The matching `goal/change` | dsh-goal |
64
+ | `hmr/change` | emit | A watched file has no module or configuration handler. | dsh-hmr |
65
+ | `hmr/reload` | emit | Module replacements have finished loading. | dsh-hmr |
66
+ | `llm/adapters-updated` | emit | The provider topology changed: an adapter registered or unregistered | dsh-llm |
67
+ | `llm/stream` | waterfall | Waterfall around every streaming model call (retry, replay, routing). | dsh-llm |
68
+ | `locale/change` | emit | The active locale switched. Dictionary registrations do NOT emit this | dsh-client-locale |
69
+ | `permission-presets/catalog-changed` | emit | The selectable process catalog changed. Payload-free by design: | dsh-permission-presets |
70
+ | `plugin-manager/changed` | emit | The profile's plugins, bundles, or composition changed: a manager | dsh-plugin-manager |
71
+ | `plugin-manager/install-log` | emit | One chunk of a pnpm run's output, streamed as the run produces it. | dsh-plugin-manager |
72
+ | `plugin-manager/install-state` | emit | An installation moved between its Host phases. `installing` is announced once per registry the | dsh-plugin-manager |
73
+ | `schedule/changed` | emit | Durable task set changed; clients refetch global task and Session-active catalogs. | dsh-schedule |
74
+ | `session-telemetry/record` | waterfall | Transform one outbound record before it reaches the backend. This | dsh-session-telemetry |
75
+ | `session/created` | emit | Creation announcement during session publication. A synchronous throw vetoes and rolls | dsh-session |
76
+ | `session/disposed` | emit | Emitted once when an announced session leaves the store, including | dsh-session |
77
+ | `session/event` | emit | Post-commit, fire-and-forget append feed. The listener snapshot resolves | dsh-session |
78
+ | `session/flush` | parallel | Awaited parallel durability checkpoint: every listener runs and the | dsh-session |
79
+ | `settings/document-updated` | emit | One profile entry's form values, availability, or page policy changed. | dsh-settings |
80
+ | `skills/change` | emit | A skill provider, runtime contribution, or provider-backed catalog may | dsh-skill |
81
+ | `slash/input-begin-command` | bail | Claim a command token for the scoped input machine. | dsh-client-ui-conversation |
82
+ | `slash/input-consume-token` | bail | Consume a trigger token without inserting replacement content. | dsh-client-ui-conversation |
83
+ | `slash/input-insert-reference` | bail | Insert a structured reference into the scoped input machine. | dsh-client-ui-conversation |
84
+ | `slash/input-insert-text` | bail | Insert plain text into the scoped input machine. | dsh-client-ui-conversation |
85
+ | `slots/changed` | emit | An ordinary Slot declaration or entry registration set changed. Factory | dsh-client-ui-renderer |
86
+ | `subagent/end` | emit | A published child settled. Scope-filtered dispatch uses the same delegating | dsh-subagent |
87
+ | `subagent/provider-added` | emit | A provider became resolvable in the registry. | dsh-subagent |
88
+ | `subagent/provider-removed` | emit | A provider left the registry. Accepted runs remain holder-owned. | dsh-subagent |
89
+ | `subagent/start` | emit | A provider established a published child. For in-process providers, | dsh-subagent |
90
+ | `system-prompt/assemble` | waterfall | Expert waterfall over the assembled sections, contexts, tools, and variables. | dsh-system-prompt |
91
+ | `system-prompt/change` | emit | Emitted when any prompt provider changes. This registry notification is | dsh-system-prompt |
92
+ | `theme/change` | emit | Theme state changed (preference switched, registry updated, or the OS | dsh-client-ui-theme |
93
+ | `tools/change` | emit | A tool was registered or unregistered, or a scoped restriction changed | dsh-tools |
94
+ | `tools/execute` | waterfall | Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns | dsh-tools |
95
+ | `tools/post-execute` | waterfall | Accept, replace, enrich, or block a normalized dispatch result. `next()` | dsh-tools |
96
+ | `tools/pre-execute` | waterfall | Allow, deny, cancel, or ask before dispatch. `next()` delegates to allow; | dsh-tools |
97
+ | `tools/ptc-dispatch-log` | waterfall | Allow a listener to replace content in the DURABLE LOG COPY of one | dsh-tools |
98
+ | `tools/result` | emit | Observe the frozen, lossless-JSON final outcome. Listener failures are contained. | dsh-tools |
99
+ | `user-questions/request` | waterfall | Ask composed answerers for structured user input. Return an answer to | dsh-user-questions |
100
+ | `webserver/index-inject` | emit | Collect the structured index injection table. Emitted on every index | dsh-host-webserver |
101
+ | `workflow/agent-end` | emit | One `agent()` call settled (clean result, child failure, or run | dsh-workflow |
102
+ | `workflow/agent-start` | emit | One `agent()` call established a published child run. Paired with | dsh-workflow |
103
+ | `workflow/end` | emit | A workflow run settled (any stop reason). Fired when | dsh-workflow |
104
+ | `workflow/log` | emit | The script emitted a narration line (a `log(message)` call). | dsh-workflow |
105
+ | `workflow/phase` | emit | The script entered a phase (a `phase(title)` call) — progress grouping | dsh-workflow |
106
+ | `workflow/start` | emit | A workflow run started — the script's meta block validated, the body | dsh-workflow |
107
+ | `workspace/session-activity` | waterfall | Ask the composed providers what still runs for a session before it is | dsh-workspace |
108
+ | `workspace/session-stop` | parallel | Stop a session's running work because the caller archived it with | dsh-workspace |