@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,482 @@
1
+ /**
2
+ * Generated maps for the pack (spec 037): the mount-point map (where a plugin can put things on CLI, Web and
3
+ * Desktop) and the plugin taxonomy (every row composed on any surface, classified by what it does). Both are
4
+ * derived from real sources so they cannot drift by hand: the slot contracts (`interface SlotMap`), the composed
5
+ * loader rows per surface (scripts/data/census-*.json) and each package's own source. Dev-time only: run through
6
+ * scripts/sync-corpus.mjs; the results are committed.
7
+ */
8
+ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
9
+ import { dirname, join, relative } from 'node:path'
10
+ import { providedServices } from '../../lib/contract.js'
11
+
12
+ const SKIP = new Set(['node_modules', 'lib', 'dist', '.git', 'tests', 'test', 'test-support'])
13
+
14
+ function walk(dir, depth, visit) {
15
+ if (depth < 0) return
16
+ let names
17
+ try { names = readdirSync(dir) } catch { return }
18
+ for (const name of names) {
19
+ if (SKIP.has(name) || name.startsWith('.')) continue
20
+ const full = join(dir, name)
21
+ let st
22
+ try { st = statSync(full) } catch { continue }
23
+ if (st.isDirectory()) walk(full, depth - 1, visit)
24
+ else visit(full, name)
25
+ }
26
+ }
27
+
28
+ /** name -> { dir, pkg, rel } for every package under the harness, plugins and apps. */
29
+ export function indexPackages(repo) {
30
+ const index = new Map()
31
+ for (const base of [join(repo, 'deepseek-harness/packages'), join(repo, 'plugins'), join(repo, 'apps'), join(repo, 'runtime')]) {
32
+ walk(base, 5, (file, name) => {
33
+ if (name !== 'package.json') return
34
+ try {
35
+ const pkg = JSON.parse(readFileSync(file, 'utf8'))
36
+ if (typeof pkg.name === 'string' && !index.has(pkg.name)) index.set(pkg.name, { dir: dirname(file), pkg, rel: relative(repo, dirname(file)) })
37
+ } catch { /* not a manifest */ }
38
+ })
39
+ }
40
+ return index
41
+ }
42
+
43
+ function sourceFiles(dir) {
44
+ const out = []
45
+ walk(join(dir, 'src'), 4, (file, name) => { if (/\.(ts|tsx|js|mjs)$/u.test(name) && !/\.(test|spec)\./u.test(name)) out.push(file) })
46
+ if (out.length === 0 && existsSync(join(dir, 'index.js'))) out.push(join(dir, 'index.js'))
47
+ return out
48
+ }
49
+
50
+ const read = file => { try { return readFileSync(file, 'utf8') } catch { return '' } }
51
+
52
+ // ---------------------------------------------------------------- slots
53
+
54
+ /** Every `interface SlotMap` entry declared in source: name, kind, scope, owner, first doc line, declaring package. */
55
+ export function collectSlots(repo, index) {
56
+ const slots = new Map()
57
+ const roots = [join(repo, 'deepseek-harness/packages/client'), join(repo, 'apps/acryl-desktop/src/client'), join(repo, 'plugins')]
58
+ const files = []
59
+ for (const root of roots) walk(root, 7, (file, name) => { if (/\.(ts|tsx)$/u.test(name) && !/\.(test|spec)\./u.test(name)) files.push(file) })
60
+ const packageOf = file => {
61
+ let best
62
+ for (const [name, info] of index) if (file.startsWith(`${info.dir}/`) && (!best || info.dir.length > best.dir.length)) best = { name, dir: info.dir }
63
+ return best?.name ?? 'unknown'
64
+ }
65
+ for (const file of files) {
66
+ const text = read(file)
67
+ const block = /interface SlotMap \{/gu
68
+ let m
69
+ while ((m = block.exec(text)) !== null) {
70
+ let depth = 1
71
+ let i = block.lastIndex
72
+ const start = i
73
+ while (i < text.length && depth > 0) { if (text[i] === '{') depth += 1; else if (text[i] === '}') depth -= 1; i += 1 }
74
+ const body = text.slice(start, i - 1)
75
+ const entry = /(?:\/\*\*([\s\S]*?)\*\/\s*)?'([A-Za-z0-9.\-]+)':\s*\{([\s\S]*?)\}(?=\s*(?:\/\*\*|'[A-Za-z0-9.\-]+':|$))/gu
76
+ let e
77
+ while ((e = entry.exec(body)) !== null) {
78
+ const doc = (e[1] ?? '').split('\n').map(l => l.replace(/^\s*\*?\s?/u, '').trim()).filter(Boolean)[0] ?? ''
79
+ const spec = e[3]
80
+ const kind = /kind:\s*'([a-z]+)'/u.exec(spec)?.[1]
81
+ const scope = /scope:\s*'([a-z-]+)'/u.exec(spec)?.[1]
82
+ const owner = /owner:\s*([A-Za-z_][\w<>,\s.[\]]*)/u.exec(spec)?.[1]?.trim().replace(/\s+/gu, ' ')
83
+ if (kind && !slots.has(e[2])) slots.set(e[2], { name: e[2], kind, scope, owner, doc: doc.replace(/\s+/gu, ' '), declaredBy: packageOf(file) })
84
+ }
85
+ }
86
+ }
87
+ // Who fills each slot: packages whose source registers or injects into it by literal name.
88
+ const fillers = new Map([...slots.keys()].map(k => [k, new Set()]))
89
+ for (const file of files) {
90
+ const text = read(file)
91
+ if (!/slots\.(register|inject)/u.test(text)) continue
92
+ for (const name of slots.keys()) if (text.includes(`'${name}'`)) fillers.get(name).add(packageOf(file))
93
+ }
94
+ for (const [name, set] of fillers) slots.get(name).filledBy = [...set].sort()
95
+ return [...slots.values()].sort((a, b) => a.name.localeCompare(b.name))
96
+ }
97
+
98
+ // ---------------------------------------------------------------- roles
99
+
100
+ const ROLE_RULES = [
101
+ ['tool', /tools\.register\(|defineTool\(/u],
102
+ ['chat-command', /commands\.register\(/u],
103
+ ['llm-adapter', /registerAdapter\(/u],
104
+ ['prompt-contribution', /systemPrompt\.(section|register|add)|registerSection\(|\.section\(\{/u],
105
+ ['skill-provider', /skills\.registerProvider|registerSkillProvider/u],
106
+ ['subagent-provider', /subagents\.register\(/u],
107
+ ['agent-preset', /agentPresets|dsh-agent-presets|persona/u],
108
+ ['settings-section', /settings\.installSection|registerSection\(.*settings|settings\.register/u],
109
+ ['host-route', /@Remote|\.route\(|registerRoute|webServer\./u],
110
+ ['event-hook', /ctx\.on\(|\.on\('[a-z]/u],
111
+ ['client-slot', /slots\.(register|inject)\(/u],
112
+ ['tui-command', /tuiCommands/u],
113
+ ['sandbox-or-terminal-backend', /sandbox|Sandbox|terminal\.register|spawnTerminal/u],
114
+ ['storage-or-persistence', /SessionStore|persistence|sqlite|\.jsonl|storage\.register/u],
115
+ ['schedule-job-workflow', /schedule\.|jobs\.|workflow|webhook/u],
116
+ ['protocol-bridge', /\bmcp\b|\bacp\b|\blsp\b|JSON-RPC/iu],
117
+ ]
118
+
119
+ function injectedServices(text) {
120
+ const m = /export const inject\s*=\s*(\[[^\]]*\]|\{[\s\S]*?\})/u.exec(text)
121
+ if (!m) return []
122
+ return [...m[1].matchAll(/'([A-Za-z0-9.\-_]+)'/gu)].map(x => x[1])
123
+ }
124
+
125
+ /** Primary taxonomy type, most specific first. */
126
+ const PRIMARY_ORDER = [
127
+ 'client-slot', 'tui-command', 'llm-adapter', 'tool', 'chat-command', 'skill-provider', 'prompt-contribution', 'subagent-provider', 'agent-preset',
128
+ 'settings-section', 'host-route', 'sandbox-or-terminal-backend', 'storage-or-persistence', 'schedule-job-workflow', 'protocol-bridge', 'event-hook',
129
+ ]
130
+
131
+ const DESKTOP_MAIN_ROWS = {
132
+ 'acryl-desktop/terminal': 'Desktop main-process integrated terminal (PTY) service.',
133
+ 'acryl-desktop/hello-world': 'Desktop hello-world sample plugin (reference for Desktop host plugins).',
134
+ 'acryl-desktop/diagnostics': 'Desktop diagnostics export and crash evidence.',
135
+ 'acryl-desktop/notifications': 'Desktop native OS notifications.',
136
+ 'acryl-desktop/pnpm': 'Desktop package-manager service (desktopPnpm): runs dsh/pnpm operations in the active profile.',
137
+ 'acryl-desktop/profiles': 'Desktop profile service (desktopProfiles): current profile, list, select, delete.',
138
+ 'acryl-desktop/updates': 'Desktop application update service.',
139
+ 'acryl-desktop/webserver': 'Desktop-owned web server host for the renderer.',
140
+ 'dsh-desktop-loader-smoke-plugin': 'Loader smoke-test plugin used by the Desktop boot verification.',
141
+ }
142
+
143
+ /** Name-pattern classification for the harness's own naming convention; the source scan is the fallback. */
144
+ const NAME_RULES = [
145
+ [/dsh-client-ui-|\/ui-|dsh-client-file-upload|dsh-client-resources|dsh-client-theme/u, 'client-slot'],
146
+ [/dsh-client-|dsh-typert-client/u, 'client-service'],
147
+ [/dsh-tool-/u, 'tool'],
148
+ [/dsh-command-/u, 'chat-command'],
149
+ [/dsh-llm-|llm-deepseek|llm-pi-ai/u, 'llm-adapter'],
150
+ [/dsh-subagent-/u, 'subagent-provider'],
151
+ [/dsh-agent-presets|dsh-persona/u, 'agent-preset'],
152
+ [/dsh-terminal|dsh-bash-sandbox|dsh-sandbox|dsh-subprocess|dsh-e2b/u, 'sandbox-or-terminal-backend'],
153
+ [/dsh-api-/u, 'host-route'],
154
+ [/dsh-session-log|dsh-storage|dsh-persistence|dsh-spill/u, 'storage-or-persistence'],
155
+ [/dsh-(schedule|jobs|workflow|webhook)/u, 'schedule-job-workflow'],
156
+ [/dsh-(mcp|acp|lsp)/u, 'protocol-bridge'],
157
+ [/dsh-(hooks|guard|approval)/u, 'event-hook'],
158
+ [/dsh-skill/u, 'skill-provider'],
159
+ ]
160
+
161
+ export function classifyRow(name, index, surfaces) {
162
+ if (DESKTOP_MAIN_ROWS[name]) return { name, package: name, rel: 'apps/acryl-desktop', description: DESKTOP_MAIN_ROWS[name], kind: 'host', roles: [], primary: 'desktop-main', provides: [], injects: [], surfaces }
163
+ // Sub-path rows (`pkg/feature`) belong to their package.
164
+ let info = index.get(name)
165
+ let lookup = name
166
+ if (!info && name.includes('/')) { const cut = name.slice(0, name.lastIndexOf('/')); if (index.has(cut)) { info = index.get(cut); lookup = cut } }
167
+ if (name.startsWith('cordis:') || name.startsWith('@deepseek-ai/cordis-plugin') || name === '@acryldev/cordis-plugin-market' && false) {
168
+ return { name, package: name, rel: 'core', description: 'Cordis loader infrastructure (entry groups, include, timer, HMR).', kind: 'core', roles: [], primary: 'core-infrastructure', provides: [], injects: [], surfaces }
169
+ }
170
+ if (!info) return { name, package: name, rel: '?', description: '(package not found in this checkout)', kind: 'unknown', roles: [], primary: 'unknown', provides: [], injects: [], surfaces }
171
+ const files = sourceFiles(info.dir)
172
+ const text = files.map(read).join('\n')
173
+ const roles = ROLE_RULES.filter(([, re]) => re.test(text)).map(([role]) => role)
174
+ const client = info.pkg.dsh?.client !== undefined || /client/u.test(info.rel) || /-client-/u.test(lookup)
175
+ let description = String(info.pkg.description ?? '').trim()
176
+ if (description === '') {
177
+ const readme = read(join(info.dir, 'README.md'))
178
+ description = /^description:\s*"?(.+?)"?\s*$/mu.exec(readme)?.[1] ?? ''
179
+ }
180
+ const provides = providedServices(text)
181
+ const injects = injectedServices(text)
182
+ let primary = NAME_RULES.find(([re]) => re.test(lookup))?.[1] ?? PRIMARY_ORDER.find(role => roles.includes(role))
183
+ if (!primary) primary = provides.length > 0 ? 'service-provider' : client ? 'client-service' : 'other'
184
+ return { name, package: name, rel: info.rel, description: description.replace(/\s+/gu, ' ').slice(0, 160), kind: client ? 'client' : 'host', roles, primary, provides: provides.slice(0, 6), injects: injects.slice(0, 8), surfaces }
185
+ }
186
+
187
+ // ---------------------------------------------------------------- data
188
+
189
+ export function loadRows(dataDir) {
190
+ const surfaces = new Map()
191
+ const add = (name, surface) => { if (!surfaces.has(name)) surfaces.set(name, new Set()); surfaces.get(name).add(surface) }
192
+ for (const entry of JSON.parse(readFileSync(join(dataDir, 'census-tui-web.json'), 'utf8'))) for (const row of entry.entries) add(row.name, entry.label)
193
+ for (const row of JSON.parse(readFileSync(join(dataDir, 'census-desktop.json'), 'utf8')).entries) add(row.id, 'desktop')
194
+ return surfaces
195
+ }
196
+
197
+ // ---------------------------------------------------------------- rendering
198
+
199
+ const cell = text => String(text ?? '').replaceAll('|', '\\|').replaceAll('\n', ' ')
200
+ const short = name => name.replace(/^@deepseek-ai\//u, '')
201
+ const surfaceMark = set => ['tui', 'web', 'desktop'].map(s => (set.has(s) ? s : '-')).join(' ')
202
+
203
+ export function renderMountPoints(slots, hostSeams) {
204
+ const web = slots
205
+ const lines = [
206
+ '# Mount points: where a plugin can put things, per surface',
207
+ '',
208
+ '<!-- Generated by scripts/sync-corpus.mjs from the SlotMap declarations in source. Do not edit. -->',
209
+ '',
210
+ 'ACRYL has three surfaces. A plugin has two halves: a **host** half (Node, `apply(ctx)`, all surfaces) and, for',
211
+ 'Web and Desktop, an optional **browser** half (`client.js`, slots). Pick the mount point first, then read its doc.',
212
+ '',
213
+ '## Which surface can show what',
214
+ '',
215
+ '| I want to add | CLI (terminal) | Web | Desktop |',
216
+ '| --- | --- | --- | --- |',
217
+ '| A visible UI element (button, panel, tab, card) | a **TUI command overlay** (`tuiCommands.register`, opened with a slash command) | a **client slot** (table below) | the same client slots as Web, plus the Desktop frame slots |',
218
+ '| A whole page or full-screen view | a full-screen overlay (`tuiCommands` without an `overlay` hint) | a header button opening a fixed `inset: 0` panel | the `desktop.main` frame slot (replaces the main surface) or the same panel |',
219
+ '| A model-callable tool | yes (`tools`) | yes | yes |',
220
+ '| A chat slash command | yes (`commands.register`) | yes | yes |',
221
+ '| Text in the system prompt, skills | yes | yes | yes |',
222
+ '| A new model provider | yes (`llm`) | yes | yes |',
223
+ '| A backend HTTP/RPC route | no web server | yes (`router` and `routerHttp`, or `connection` RPC) | yes |',
224
+ '| Native OS integration (menus, notifications, windows) | no | no | Desktop main only (`desktopProfiles`, `desktopPnpm`, Electron); not agent-authorable without the main-process API |',
225
+ '',
226
+ '## Host mount points (every surface unless noted)',
227
+ '',
228
+ '| Mount point | Service and call | What you contribute | Doc |',
229
+ '| --- | --- | --- | --- |',
230
+ ...hostSeams.map(s => `| ${cell(s.mount)} | ${cell(s.call)} | ${cell(s.what)} | ${cell(s.doc)} |`),
231
+ '',
232
+ '## CLI (terminal) presentation',
233
+ '',
234
+ 'The terminal has ONE plugin presentation seam: `ctx.get(\'tuiCommands\')?.register({ command: \'/name\', description, packageName, overlay?, open({ tui, close }) })`.',
235
+ '`open()` returns a real `pi-tui` `Component` shown as an overlay (full screen by default; pass `overlay: { width, anchor, margin }`',
236
+ 'for a compact popup). The command list refreshes live whenever a plugin registers or removes a command, so a newly installed command works without restarting the TUI. The built-in overlays (`/model`, `/plugins`, `/tools`, `/trajectory`, ...) are not replaceable. Everything else the CLI',
237
+ 'shows (chat, tool cards, status) is built in. Example: `example-plugins/packages/tui-command-basic/`; doc: `extending/tui-command.md`.',
238
+ '',
239
+ '## Web and Desktop: client slots',
240
+ '',
241
+ 'Declared in source as `interface SlotMap` and listed here from those declarations. **Kind**: `single` (one occupant, replaces),',
242
+ '`list` (many, ordered by `order`), `keyed` (one per `key`), `chain` (selector-routed). **Scope**: `root` (once for the app),',
243
+ '`session` (per open conversation), `session-maybe` (also present with no session). Register from `client.js` with',
244
+ '`ctx.slots.inject(name, () => ctx.slots.register({ name, id, order }, Component))` (see `extending/client-slot.md`). A slot whose',
245
+ 'owner props are non-trivial needs those props: read its entry in `maps/slot-contracts.md` (register options, exact props, taken keys, worked example) before using it. Verified',
246
+ 'working examples: `conversation.session.header.actions` (header-action) and `sidebar.right.pane.tab` (sidebar-tab).',
247
+ '',
248
+ `${web.length} slots:`,
249
+ '',
250
+ '| Slot | Kind | Scope | Owner props | Where / what | Declared by | Filled by (built-in) |',
251
+ '| --- | --- | --- | --- | --- | --- | --- |',
252
+ ...web.map(s => `| \`${s.name}\` | ${s.kind} | ${s.scope ?? ''} | ${cell(s.owner ?? '')} | ${cell(s.doc)} | ${cell(short(s.declaredBy))} | ${cell((s.filledBy ?? []).map(short).join(', '))} |`),
253
+ '',
254
+ 'Desktop adds its own frame slots (`desktop.main`, `sidebar`, `conversation`, `details`, `shell.overlay`) in advanced mode; they are',
255
+ 'in the table above from `apps/acryl-desktop/src/client/contracts.ts`. On Web these frame slots do not exist; the upstream slots do.',
256
+ '',
257
+ ]
258
+ return lines.join('\n')
259
+ }
260
+
261
+ export function renderTaxonomy(rows, typeGuide) {
262
+ const bySurface = s => rows.filter(r => r.surfaces.has(s)).length
263
+ const groups = new Map()
264
+ for (const row of rows) { if (!groups.has(row.primary)) groups.set(row.primary, []); groups.get(row.primary).push(row) }
265
+ const order = [...groups.keys()].sort((a, b) => groups.get(b).length - groups.get(a).length)
266
+ const lines = [
267
+ '# Plugin taxonomy: every row composed on any surface',
268
+ '',
269
+ '<!-- Generated by scripts/sync-corpus.mjs from the composed loader rows (scripts/data/census-*.json) and each package\'s own source. Do not edit. -->',
270
+ '',
271
+ `${rows.length} distinct plugin packages are composed across the three surfaces (CLI ${bySurface('tui')}, Web ${bySurface('web')}, Desktop ${bySurface('desktop')} rows).`,
272
+ 'Each is classified by what its source does (its **primary type**). The **surfaces** column reads `tui web desktop`, `-` where',
273
+ 'absent. "Host" runs in Node on the surface; "client" runs in the browser (Web and Desktop only).',
274
+ '',
275
+ '## How to read this for authoring',
276
+ '',
277
+ 'Find the type of thing you want to build, then read the doc and copy the example in the guide table. The plugins listed under',
278
+ 'that type are the real, shipped implementations to study (their source is in the repository; their contracts are in `reference/`).',
279
+ '',
280
+ '## Type guide: can an agent create one, and how',
281
+ '',
282
+ '| Type | Count | Can be authored as a local plugin? | Doc | Example | Notes |',
283
+ '| --- | --- | --- | --- | --- | --- |',
284
+ ...order.map(t => { const g = typeGuide[t] ?? { can: 'see notes', doc: '', example: '', notes: '' }; return `| ${t} | ${groups.get(t).length} | ${cell(g.can)} | ${cell(g.doc)} | ${cell(g.example)} | ${cell(g.notes)} |` }),
285
+ '',
286
+ ]
287
+ for (const type of order) {
288
+ lines.push(`## ${type} (${groups.get(type).length})`, '', '| Package | Kind | Surfaces (tui web desktop) | What it is | Provides | Needs |', '| --- | --- | --- | --- | --- | --- |')
289
+ for (const row of groups.get(type).sort((a, b) => a.name.localeCompare(b.name))) {
290
+ lines.push(`| ${cell(short(row.name))} | ${row.kind} | ${surfaceMark(row.surfaces)} | ${cell(row.description)} | ${cell(row.provides.join(', '))} | ${cell(row.injects.join(', '))} |`)
291
+ }
292
+ lines.push('')
293
+ }
294
+ return lines.join('\n')
295
+ }
296
+
297
+ // ---------------------------------------------------------------- theme tokens
298
+
299
+ /** Every `--dsw-alias-*` design token with its light and dark value, from the theme package's own stylesheet. */
300
+ export function collectThemeTokens(repo) {
301
+ const css = read(join(repo, 'deepseek-harness/packages/client/ui-theme/src/styles/design-platform.css'))
302
+ const blocks = [...css.matchAll(/^(body(?:\[data-ds-dark-theme\])?) \{([\s\S]*?)^\}/gmu)].map(m => ({ selector: m[1], body: m[2] }))
303
+ const parse = body => new Map([...body.matchAll(/^\s*(--dsw-alias-[a-z0-9-]+):\s*([^;]+);/gmu)].map(m => [m[1], m[2].trim()]))
304
+ const light = new Map()
305
+ const dark = new Map()
306
+ for (const block of blocks) {
307
+ const target = block.selector.includes('dark') ? dark : light
308
+ for (const [name, value] of parse(block.body)) target.set(name, value)
309
+ }
310
+ const names = [...new Set([...light.keys(), ...dark.keys()])].sort()
311
+ return names.map(name => ({ name, light: light.get(name) ?? '', dark: dark.get(name) ?? '' }))
312
+ }
313
+
314
+ export function renderThemeTokens(tokens) {
315
+ const lines = [
316
+ '# Theme tokens: every `--dsw-alias-*` design token (Web and Desktop)',
317
+ '',
318
+ '<!-- Generated by scripts/sync-corpus.mjs from the theme package stylesheet. Do not edit. -->',
319
+ '',
320
+ 'These are the CSS custom properties the app styles read. Override one with `ctx.theme.overrideTokens(sourceId, { \'--dsw-alias-brand-primary\': { light: \'#e8590c\', dark: \'#ff922b\' } })`',
321
+ 'in a client plugin (both modes are mandatory), or ship a whole theme with `ctx.theme.register({ id, colorScheme, tokens })`. See',
322
+ '`extending/ui-theme.md`. Values shown reference the static palette (`--dsw-static-*`) unless they are literal colors. Also overridable:',
323
+ '`--dsw-font-family` (UI font), `--dsh-content-font-size` (conversation text size, via `ctx.theme.setFontSize(px)`), corner and shadow',
324
+ 'tokens (`--dsw-shadow-*`, `--dsw-elevation-*`).',
325
+ '',
326
+ `${tokens.length} alias tokens:`,
327
+ '',
328
+ '| Token | Light | Dark |',
329
+ '| --- | --- | --- |',
330
+ ...tokens.map(t => `| \`${t.name}\` | ${cell(t.light)} | ${cell(t.dark)} |`),
331
+ '',
332
+ ]
333
+ return lines.join('\n')
334
+ }
335
+
336
+ // ---------------------------------------------------------------- component library
337
+
338
+ /** Value exports of the shared web UI primitives (what `require('@deepseek-ai/dsh-client-ui-primitives')` returns). */
339
+ export function collectPrimitiveExports(repo) {
340
+ const text = read(join(repo, 'deepseek-harness/packages/client/ui-primitives/src/index.ts'))
341
+ const names = new Set()
342
+ for (const m of text.matchAll(/^export \{([^}]*)\} from/gmu)) for (const n of m[1].split(',')) { const name = n.trim().split(/\s+as\s+/u).pop(); if (name) names.add(name) }
343
+ const iconsFile = read(join(repo, 'deepseek-harness/packages/client/ui-primitives/src/icons/index.tsx'))
344
+ const icons = [...iconsFile.matchAll(/export (?:function|const) (Icon[A-Za-z0-9]+)/gu)].map(m => m[1])
345
+ return { components: [...names].sort(), icons: icons.sort() }
346
+ }
347
+
348
+ export function renderUiComponents(prims, tui) {
349
+ return [
350
+ '# UI component libraries available today, per surface',
351
+ '',
352
+ '<!-- Generated by scripts/sync-corpus.mjs from the component packages\' own exports. Do not edit. -->',
353
+ '',
354
+ 'Build UI from these instead of hand-styling. They follow the theme (light, dark, your token overrides) and are keyboard-accessible.',
355
+ '',
356
+ '## Web and Desktop: `@deepseek-ai/dsh-client-ui-primitives`',
357
+ '',
358
+ 'In `client.js`: `const { Button, Modal } = require(\'@deepseek-ai/dsh-client-ui-primitives\')`, and declare the package in `package.json`',
359
+ '`dsh.client.inject` so it loads first. Verified in a real browser (example `client-ui-components`). Props for the common ones are in',
360
+ '`extending/ui-components.md`; for the rest read the package README in `reference/subsystems/client-modules.md` and its `src/<Name>.tsx`.',
361
+ '',
362
+ `${prims.components.length} exports:`,
363
+ '',
364
+ prims.components.map(n => `\`${n}\``).join(', '),
365
+ '',
366
+ `${prims.icons.length} icons (React components, e.g. \`IconFolderClose16\`): ${prims.icons.slice(0, 60).map(n => `\`${n}\``).join(', ')}${prims.icons.length > 60 ? ', ...' : ''}`,
367
+ '',
368
+ '## CLI: `@earendil-works/pi-tui`',
369
+ '',
370
+ tui,
371
+ '',
372
+ '## Gap',
373
+ '',
374
+ 'There is no single cross-surface component contract yet: the web primitives and the terminal components are separate stacks with',
375
+ 'separate tokens. That is the subject of spec 038 (`specs/038-ui-component-library`).',
376
+ '',
377
+ ].join('\n')
378
+ }
379
+
380
+ // ---------------------------------------------------------------- lifecycle events
381
+
382
+ /** Every event declared in an `interface Events` block (declare module '@deepseek-ai/cordis'): name, dispatch mode, first doc line, package. */
383
+ export function collectEvents(repo, index) {
384
+ const roots = [join(repo, 'deepseek-harness/packages'), join(repo, 'apps'), join(repo, 'plugins'), join(repo, 'runtime')]
385
+ const files = []
386
+ for (const root of roots) walk(root, 7, (file, name) => { if (/\.(ts|tsx)$/u.test(name) && !/\.(test|spec)\./u.test(name)) files.push(file) })
387
+ const packageOf = file => {
388
+ let best
389
+ for (const [name, info] of index) if (file.startsWith(`${info.dir}/`) && (!best || info.dir.length > best.dir.length)) best = { name, dir: info.dir }
390
+ return best?.name ?? 'unknown'
391
+ }
392
+ const events = new Map()
393
+ for (const file of files) {
394
+ const text = read(file)
395
+ const block = /interface Events \{/gu
396
+ let m
397
+ while ((m = block.exec(text)) !== null) {
398
+ let depth = 1
399
+ let i = block.lastIndex
400
+ const start = i
401
+ while (i < text.length && depth > 0) { if (text[i] === '{') depth += 1; else if (text[i] === '}') depth -= 1; i += 1 }
402
+ const body = text.slice(start, i - 1)
403
+ const entry = /(?:\/\*\*([\s\S]*?)\*\/\s*)?'([A-Za-z0-9:/._-]+)'\s*\(/gu
404
+ let e
405
+ while ((e = entry.exec(body)) !== null) {
406
+ const docLines = (e[1] ?? '').split('\n').map(l => l.replace(/^\s*\*?\s?/u, '').trim()).filter(Boolean)
407
+ const what = docLines.find(l => !l.startsWith('@')) ?? ''
408
+ const mode = /@mode\s+(\w+)/u.exec(e[1] ?? '')?.[1] ?? ''
409
+ if (!events.has(e[2])) events.set(e[2], { name: e[2], mode, what: what.replace(/\s+/gu, ' '), declaredBy: packageOf(file) })
410
+ }
411
+ }
412
+ }
413
+ return [...events.values()].sort((a, b) => a.name.localeCompare(b.name))
414
+ }
415
+
416
+ export function renderEvents(events) {
417
+ return [
418
+ '# Lifecycle events: where a plugin can hook the agent (Web, Desktop, CLI)',
419
+ '',
420
+ '<!-- Generated by scripts/sync-corpus.mjs from the `interface Events` declarations in source. Do not edit. -->',
421
+ '',
422
+ 'pi.dev lets an extension intercept input, prompt construction, context, the provider request, tool execution and session lifecycle. ACRYL',
423
+ 'gets the same reach from the harness event bus. Listen with `ctx.on(name, listener)` inside `ctx.effect` (so it leaves with the plugin).',
424
+ '**Dispatch modes**: `emit` (fire and forget), `parallel` (all run), `serial` and `bail` (in order until a value bails), `waterfall`',
425
+ '(around-middleware: `ctx.on(name, async (input, next) => { const result = await next(); return result })`; a listener that only observes MUST',
426
+ 'still call `next()` and return its result; the returned value is authoritative). Working example: `example-plugins/packages/prompt-assemble-hook/` (shapes',
427
+ 'the system prompt on `system-prompt/assemble`, the same hook `@acryldev/system-prompt` uses). Read `extending/event-hook.md` first.',
428
+ '',
429
+ `${events.length} events:`,
430
+ '',
431
+ '| Event | Mode | What | Declared by |',
432
+ '| --- | --- | --- | --- |',
433
+ ...events.map(e => `| \`${e.name}\` | ${e.mode} | ${cell(e.what)} | ${cell(short(e.declaredBy))} |`),
434
+ '',
435
+ ].join('\n')
436
+ }
437
+
438
+ // ---------------------------------------------------------------- slot contracts (from the harness's own client catalog)
439
+
440
+ const noDash = text => String(text ?? '').replaceAll('—', '-').replaceAll('–', '-')
441
+
442
+ /** Load the harness's generated client slot catalog (data only, TypeScript type-stripped by Node). */
443
+ export async function loadSlotCatalog(repo) {
444
+ const file = join(repo, 'deepseek-harness/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts')
445
+ if (!existsSync(file)) return undefined
446
+ const mod = await import(file)
447
+ return { notes: mod.CLIENT_NOTES ?? [], slots: mod.CLIENT_SLOT_API ?? [] }
448
+ }
449
+
450
+ export function renderSlotContracts(catalog) {
451
+ const out = [
452
+ '# Slot contracts: what each client slot needs, receives and already holds',
453
+ '',
454
+ '<!-- Generated by scripts/sync-corpus.mjs from deepseek-harness/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts (the harness\'s own catalog, which it also serves to the model as `cordis_inspect what:"client"`). Do not edit. -->',
455
+ '',
456
+ 'Use this with `maps/mount-points.md` when you fill a slot that needs more than `{ name, id, order }`. For each slot: the register options, the exact props',
457
+ 'your component receives, the keys already taken, and a worked example. The harness notes below were written for packages defined from a running page',
458
+ '(`cordis_define`), where nothing can be imported; an installed plugin with `dsh.client` CAN `require` the shared components (`extending/ui-components.md`).',
459
+ 'The `priority` rule and the "declare `inject: [\'slots\']`" rule apply to both.',
460
+ '',
461
+ '## Harness notes',
462
+ '',
463
+ ...catalog.notes.map(note => `- ${noDash(note).replace(/\n/gu, ' ')}`),
464
+ '',
465
+ `## The ${catalog.slots.length} slots`,
466
+ '',
467
+ ]
468
+ for (const slot of catalog.slots) {
469
+ out.push(`### \`${slot.key}\``, '', `Kind \`${slot.kind}\`, scope \`${slot.scope}\`. ${noDash(slot.summary)}`, '')
470
+ if (slot.doc && slot.doc.trim() !== slot.summary.trim()) out.push(noDash(slot.doc).trim(), '')
471
+ if (slot.registerOptions?.length) {
472
+ out.push('Register options:', '')
473
+ for (const o of slot.registerOptions) out.push(`- \`${o.name}\` (${o.requirement}, \`${cell(o.type)}\`): ${noDash(o.doc).replace(/\n/gu, ' ')}`)
474
+ out.push('')
475
+ }
476
+ if (slot.ownerProps?.length) out.push('Props your component receives:', '', '```ts', noDash(slot.ownerProps.join('\n\n')).trim(), '```', '')
477
+ if (slot.keyDomain) out.push(`Keys: ${noDash(slot.keyDomain)}`, '')
478
+ if (slot.occupants?.length) out.push(`Already occupied by: ${slot.occupants.map(o => noDash(o)).join('; ')}. Replace risk: \`${slot.replaceRisk}\`.`, '')
479
+ if (slot.example) out.push('Example:', '', '```js', noDash(slot.example).trim(), '```', '')
480
+ }
481
+ return out.join('\n')
482
+ }
@@ -0,0 +1,12 @@
1
+ ---
2
+ name: acryl-add-provider-or-capability
3
+ description: Use when the user wants a new model provider, a swappable capability, an agent preset or persona, or a Desktop profile feature.
4
+ ---
5
+ # Add a provider, capability, preset or profile feature
6
+
7
+ Pick by what is asked and read the doc and the example COMPLETELY first: a new model provider
8
+ {{pack}}/docs/extending/llm-adapter.md (example llm-adapter-echo); interchangeable implementations
9
+ {{pack}}/docs/extending/three-role-capability.md; an agent preset or persona {{pack}}/docs/extending/agent-preset.md;
10
+ profile, pnpm or live activation {{pack}}/docs/extending/desktop-main.md. If unsure which mechanism fits read
11
+ {{pack}}/docs/extending/cordis-core.md. Never put a secret in a package file or chat. Verify, install, and report the
12
+ status; say plainly what you could not verify (for example a provider that needs a real key).
@@ -0,0 +1,18 @@
1
+ ---
2
+ name: acryl-add-ui
3
+ description: Use when an ACRYL extension needs UI in the Web or Desktop app (a button, panel, sidebar tab, settings section, dashboard).
4
+ ---
5
+ # Add UI to ACRYL (web and desktop)
6
+
7
+ First read {{pack}}/docs/maps/mount-points.md to choose the mount point and check the surface: Web and Desktop use client
8
+ slots (header actions, sidebar tab, settings, composer, tool and message renderers, and on Desktop the `desktop.main` frame); the
9
+ CLI has only terminal overlays (`tuiCommands`, see {{pack}}/docs/extending/tui-command.md), so a UI request from a terminal user
10
+ means an overlay, not a slot. Then read {{pack}}/docs/extending/ui-components.md (build from the app's own Button, Modal, Input, Switch, Tag via require, not hand styles) and {{pack}}/docs/extending/client-slot.md completely, then the example
11
+ {{pack}}/example-plugins/packages/client-slot-header-action/ (index.js and client.js).
12
+
13
+ Key facts: the package has a host half (empty apply) and a browser half client.js exported as "./client" with
14
+ "dsh.client" in package.json. There is no build step: write client.js by hand inside the
15
+ window.__ModuleLoader__.load wrapper, use React.createElement (no JSX, no import), and pick a slot from the
16
+ table in the doc. Decide where state lives first ({{pack}}/docs/extending/state-and-persistence.md): localStorage is per browser and per surface (Web and Desktop never share it), so
17
+ when the data must be the same in both, or survive clearing the browser, keep it on the host behind an RPC channel (example state-host-store); tell the user which you chose. Deliver with acryl_install_plugin and
18
+ tell the user it is already live in their open conversation (no reload needed).
@@ -0,0 +1,21 @@
1
+ ---
2
+ name: acryl-build-plugin
3
+ description: Use when the user asks you to add a feature, tool, panel, command or integration to ACRYL itself (build a plugin or extension). The end-to-end workflow, from reading the docs to a live plugin.
4
+ ---
5
+ # Build an ACRYL extension
6
+
7
+ 1. Read {{pack}}/docs/start-here/this-runtime.md completely (contracts, delivery).
8
+ 2. Decide WHERE it mounts and on which surfaces: read {{pack}}/docs/maps/mount-points.md (CLI has terminal overlays; Web and Desktop have
9
+ client slots; tools, commands, prompts and skills work everywhere). Ask or check which surface the user is on
10
+ if it matters (the router and acryl_workspace_status help). For an unfamiliar kind of plugin see {{pack}}/docs/maps/taxonomy.md.
11
+ 3. Pick the plugin type(s) the feature needs and open the matching doc from {{pack}}/docs/README.md
12
+ (tool, service, event hook, config, prompt, client UI, host route, tui command). Read it completely and
13
+ follow its cross-references.
14
+ 4. Open the closest working example in {{pack}}/example-plugins/README.md and read every file of it. Copy it into a
15
+ NEW directory <workspace>/.acryl-extensions/<plugin-name>/ (outside the pack) and change it. Never guess a plugin's shape from memory.
16
+ 5. Write the package (package.json, cordis.patch.yml, index.js, and client.js for UI). Declare honestly in package.json: `"acryl": { "apiVersion": 1, "permissions": [...] }` (fs.read, fs.write, net, shell, secrets, ui); the human sees the permissions before a new extension is installed. Write it under `<workspace>/.acryl-extensions/<name>/` (this project) or `<ACRYL home>/extensions/<name>/` (all projects and surfaces on this home).
17
+ 6. Call the acryl_install_plugin tool with the ABSOLUTE path of that directory. Read its result. Fix the named cause and call it
18
+ again if it fails; it undoes failed installs.
19
+ 7. Tell the user what you built, whether it is live, and (for UI) that it is already visible in their open conversation, with no reload needed.
20
+ Do not claim it works before the tool result says so. You cannot publish to the marketplace; say what
21
+ remains if the user wants that.
@@ -0,0 +1,16 @@
1
+ ---
2
+ name: acryl-change-plugin
3
+ description: Use when the user asks you to change, fix, improve, restyle, extend or remove an extension or plugin that already exists in ACRYL.
4
+ ---
5
+ # Change, improve or remove an ACRYL plugin
6
+
7
+ 1. Call acryl_list_plugins to find the plugin and the source directory it was installed from. If it is not listed
8
+ the user may mean a built-in feature; say so instead of guessing.
9
+ 2. Read its files completely before editing, and the matching doc in {{pack}}/docs/README.md for the plugin type.
10
+ 3. Edit the source directory (never node_modules, never the pack). For UI changes edit client.js.
11
+ 4. Call acryl_install_plugin with the same directory: it updates in place, and host code changes take effect in the running
12
+ app automatically ("hostReload": "automatic"). Read the result: if it has a "warning" the plugin could not be staged for
13
+ automatic reload and host changes need an app restart ({{pack}}/docs/delivery/local-live.md); if it has a "next" note, tell
14
+ the user to reload. A change to "inject" or the Config schema also needs a restart.
15
+ 5. To remove a plugin call acryl_remove_plugin. Confirm with the user first if they did not clearly ask for it.
16
+ Report what changed and whether it is live; never claim it works without the tool result.
@@ -0,0 +1,12 @@
1
+ ---
2
+ name: acryl-desktop-shell
3
+ description: Use when the user asks about the Desktop (Electron) app itself: window chrome, title bar, app icon, tray, menu, installer name, or how the Desktop app is structured.
4
+ ---
5
+ # Desktop (Electron) shell
6
+
7
+ Read {{pack}}/docs/extending/desktop-app.md completely, then {{pack}}/docs/extending/ui-customization.md. The Desktop renderer is the same
8
+ client app as Web: theme, brand slots, slots and title text change live with a client plugin (ui-theme, ui-branding docs). The Electron
9
+ main process (window options, icon, tray, native menu, product name, installer) changes only by editing apps/acryl-desktop in the ACRYL
10
+ repository and rebuilding: name the exact file from the doc and only do it when working inside that repository. A packaged app is
11
+ read-only: say so and offer the live alternative. Never disable the sandbox or contextIsolation, never touch the user's real ~/.dsh or
12
+ ~/.acryl, and ask the user to look at visual changes.
@@ -0,0 +1,10 @@
1
+ ---
2
+ name: acryl-diagnose-plugin
3
+ description: Use when something you built misbehaves and the cause is unclear: PENDING, FAILED, invisible UI, stale code, doubled behavior after reload.
4
+ ---
5
+ # Diagnose a plugin methodically
6
+
7
+ Read {{pack}}/docs/start-here/troubleshooting.md, then {{pack}}/docs/reference/cordis-api/fiber.md if the state
8
+ machine matters. Order: (1) call acryl_list_plugins and read the install result you got, (2) run acryl_verify_plugin on
9
+ the source folder, (3) for UI add console.info('[<name>] ...') lines, ask the user to open the browser console and read what it shows, (4) change ONE thing, update with acryl_install_plugin, re-read the status. Never guess a state you have
10
+ not read from a tool result. If the same cause survives two fixes, stop and tell the user what you observed.
@@ -0,0 +1,12 @@
1
+ ---
2
+ name: acryl-fix-plugin
3
+ description: Use when a plugin you installed is PENDING, FAILED, not visible, or the acryl_install_plugin tool returned an error.
4
+ ---
5
+ # Fix a plugin that does not work
6
+
7
+ Read {{pack}}/docs/delivery/local-live.md (failure states) and {{pack}}/docs/start-here/verify-before-done.md.
8
+ Read the tool result's stage and message first: it is the real cause. PENDING means an inject names a service
9
+ nobody provides (provide it, never delete the inject). FAILED means apply() threw (read the error). Installed
10
+ but not live usually means exports lacks "./package.json". UI not visible means the page was not reloaded or
11
+ client.js failed to load (no JSX or import, wrapper id equal to the package name). Fix the cause, call the tool
12
+ again, and only then tell the user it works.
@@ -0,0 +1,10 @@
1
+ ---
2
+ name: acryl-improve-ui
3
+ description: Use when the user asks to improve, restyle, redesign, extend or fix the look of a UI plugin you or they already have (button, panel, sidebar tab, board).
4
+ ---
5
+ # Improve or change an existing UI plugin
6
+
7
+ Call acryl_list_plugins to find the package directory, then read its client.js completely and
8
+ {{pack}}/docs/extending/client-slot.md. Edit in place: keep the wrapper id, keep exports, keep the localStorage key so the
9
+ user's data survives. Prefer small edits over rewrites. Keep no-build rules (createElement, require, no JSX/import).
10
+ Run acryl_verify_plugin, then acryl_install_plugin again (it updates in place) and ask the user to look: it updates live, with no reload. Tell the user exactly what changed.
@@ -0,0 +1,11 @@
1
+ ---
2
+ name: acryl-remove-plugin
3
+ description: Use when the user asks to remove, delete, disable or undo an extension or UI element you or they installed.
4
+ ---
5
+ # Remove an extension
6
+
7
+ Call acryl_list_plugins to find the exact package name (never guess it). Call acryl_remove_plugin with that name: it
8
+ unmounts the plugin live and removes it from the profile. Client plugins vanish after a page or window reload: tell the
9
+ user. The source folder under .acryl-extensions/<name>/ is left in place so the user can reinstall it; delete it only if
10
+ they ask. Confirm with acryl_list_plugins that it is gone before saying so. If the user only wants it hidden for now,
11
+ say that removal keeps the sources.
@@ -0,0 +1,14 @@
1
+ ---
2
+ name: acryl-restyle-ui
3
+ description: Use when the user asks to change colors, fonts, theme, dark mode, logo, branding, name, favicon, tab title or the general look and feel of the Web or Desktop app.
4
+ ---
5
+ # Restyle or rebrand the Web or Desktop UI
6
+
7
+ Read {{pack}}/docs/extending/ui-customization.md first (what each surface allows and what is live), then
8
+ {{pack}}/docs/extending/ui-theme.md and {{pack}}/docs/extending/ui-branding.md, and the token names in
9
+ {{pack}}/docs/maps/theme-tokens.md. Components you add should use the shared library ({{pack}}/docs/extending/ui-components.md). Copy {{pack}}/example-plugins/packages/client-theme-override/ (and web-page-branding for the favicon and page
10
+ CSS) into <workspace>/.acryl-extensions/<name>/. Override tokens with BOTH light and dark values; keep contrast readable; never edit
11
+ node_modules or the app. The tab title is rewritten by the app at runtime: use the observer from the example. Verify, install with
12
+ acryl_install_plugin, and ask the user to look (it mounts live, no reload) and check light and dark. You cannot see the screen: say what you
13
+ changed and what you could not verify. Say plainly that upstream text (for example the testing notice) and, on Desktop, the app icon and
14
+ window chrome cannot be changed by a plugin.