@acryldev/plugin-context 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (284) hide show
  1. package/LICENSE +21 -0
  2. package/docs/README.md +160 -0
  3. package/docs/delivery/local-live.md +113 -0
  4. package/docs/delivery/marketplace.md +16 -0
  5. package/docs/docs.json +2836 -0
  6. package/docs/extending/agent-preset.md +37 -0
  7. package/docs/extending/chat-command.md +28 -0
  8. package/docs/extending/client-slot.md +135 -0
  9. package/docs/extending/config-schema.md +7 -0
  10. package/docs/extending/cordis-core.md +63 -0
  11. package/docs/extending/desktop-app.md +53 -0
  12. package/docs/extending/desktop-main.md +25 -0
  13. package/docs/extending/event-hook.md +14 -0
  14. package/docs/extending/host-route.md +33 -0
  15. package/docs/extending/llm-adapter.md +38 -0
  16. package/docs/extending/packaging.md +53 -0
  17. package/docs/extending/prompt-contribution.md +9 -0
  18. package/docs/extending/service.md +13 -0
  19. package/docs/extending/skill-provider.md +9 -0
  20. package/docs/extending/state-and-persistence.md +71 -0
  21. package/docs/extending/three-role-capability.md +33 -0
  22. package/docs/extending/tool-plugin.md +24 -0
  23. package/docs/extending/tui-command.md +8 -0
  24. package/docs/extending/tui-components.md +61 -0
  25. package/docs/extending/ui-branding.md +43 -0
  26. package/docs/extending/ui-components.md +56 -0
  27. package/docs/extending/ui-customization.md +41 -0
  28. package/docs/extending/ui-library.md +66 -0
  29. package/docs/extending/ui-theme.md +55 -0
  30. package/docs/extending/workspace-tab.md +50 -0
  31. package/docs/maps/events.md +108 -0
  32. package/docs/maps/mount-points.md +154 -0
  33. package/docs/maps/slot-contracts.md +3376 -0
  34. package/docs/maps/taxonomy.md +306 -0
  35. package/docs/maps/theme-tokens.md +115 -0
  36. package/docs/maps/ui-components.md +26 -0
  37. package/docs/reference/cookbook/adding-a-package.md +174 -0
  38. package/docs/reference/cookbook/adding-a-remote-api.md +199 -0
  39. package/docs/reference/cookbook/adding-a-settings-card.md +74 -0
  40. package/docs/reference/cookbook/adding-a-tool.md +103 -0
  41. package/docs/reference/cookbook/adding-an-llm-adapter.md +45 -0
  42. package/docs/reference/cookbook/extension-cookbook.md +134 -0
  43. package/docs/reference/cordis-api/context.md +366 -0
  44. package/docs/reference/cordis-api/events.md +209 -0
  45. package/docs/reference/cordis-api/fiber.md +377 -0
  46. package/docs/reference/cordis-api/inherited.md +40 -0
  47. package/docs/reference/cordis-api/registry.md +154 -0
  48. package/docs/reference/cordis-api/service.md +104 -0
  49. package/docs/reference/cordis-guides/cordis-usage-cheatsheet.md +167 -0
  50. package/docs/reference/cordis-guides/cordis_system_guide_for_coding_agents.md +4666 -0
  51. package/docs/reference/cordis-guides/development-canvas-plugin.md +109 -0
  52. package/docs/reference/cordis-guides/hello-world-plugin-guide.md +517 -0
  53. package/docs/reference/harness/agent-lifecycle.md +93 -0
  54. package/docs/reference/harness/architecture.md +168 -0
  55. package/docs/reference/harness/capability-seams.md +675 -0
  56. package/docs/reference/harness/config-catalog.md +4523 -0
  57. package/docs/reference/harness/cordis-primer.md +47 -0
  58. package/docs/reference/harness/defensive-patterns.md +35 -0
  59. package/docs/reference/harness/event-producer-consumer.md +111 -0
  60. package/docs/reference/harness/glossary.md +47 -0
  61. package/docs/reference/harness/tool-catalog.md +2721 -0
  62. package/docs/reference/harness/tool-execution-pipeline.md +67 -0
  63. package/docs/reference/subsystems/README.md +75 -0
  64. package/docs/reference/subsystems/agent-team.md +233 -0
  65. package/docs/reference/subsystems/approval.md +172 -0
  66. package/docs/reference/subsystems/attachment.md +363 -0
  67. package/docs/reference/subsystems/boot.md +324 -0
  68. package/docs/reference/subsystems/browser-use.md +69 -0
  69. package/docs/reference/subsystems/client-modules.md +186 -0
  70. package/docs/reference/subsystems/client-resources.md +94 -0
  71. package/docs/reference/subsystems/commands.md +225 -0
  72. package/docs/reference/subsystems/compaction.md +286 -0
  73. package/docs/reference/subsystems/computer-use.md +58 -0
  74. package/docs/reference/subsystems/conversation.md +287 -0
  75. package/docs/reference/subsystems/core.md +1107 -0
  76. package/docs/reference/subsystems/credentials.md +497 -0
  77. package/docs/reference/subsystems/deliverables.md +180 -0
  78. package/docs/reference/subsystems/extensions.md +386 -0
  79. package/docs/reference/subsystems/feedback.md +402 -0
  80. package/docs/reference/subsystems/filesystem.md +532 -0
  81. package/docs/reference/subsystems/goal.md +315 -0
  82. package/docs/reference/subsystems/invariants.md +90 -0
  83. package/docs/reference/subsystems/jobs.md +501 -0
  84. package/docs/reference/subsystems/llm-streaming.md +1131 -0
  85. package/docs/reference/subsystems/lsp.md +204 -0
  86. package/docs/reference/subsystems/mcp.md +141 -0
  87. package/docs/reference/subsystems/office-to-pdf.md +89 -0
  88. package/docs/reference/subsystems/otel.md +46 -0
  89. package/docs/reference/subsystems/permission-presets.md +169 -0
  90. package/docs/reference/subsystems/persistence.md +418 -0
  91. package/docs/reference/subsystems/plan.md +89 -0
  92. package/docs/reference/subsystems/product-telemetry.md +81 -0
  93. package/docs/reference/subsystems/ptc-runtime.md +234 -0
  94. package/docs/reference/subsystems/sandbox.md +223 -0
  95. package/docs/reference/subsystems/schedule.md +545 -0
  96. package/docs/reference/subsystems/scope.md +61 -0
  97. package/docs/reference/subsystems/session-projection.md +358 -0
  98. package/docs/reference/subsystems/session-query.md +511 -0
  99. package/docs/reference/subsystems/session-reference.md +226 -0
  100. package/docs/reference/subsystems/session-telemetry.md +214 -0
  101. package/docs/reference/subsystems/session-title.md +206 -0
  102. package/docs/reference/subsystems/session.md +1300 -0
  103. package/docs/reference/subsystems/settings.md +157 -0
  104. package/docs/reference/subsystems/shell.md +316 -0
  105. package/docs/reference/subsystems/sidebar-right.md +160 -0
  106. package/docs/reference/subsystems/skills.md +354 -0
  107. package/docs/reference/subsystems/slots.md +201 -0
  108. package/docs/reference/subsystems/spill.md +126 -0
  109. package/docs/reference/subsystems/ssh.md +137 -0
  110. package/docs/reference/subsystems/storage.md +262 -0
  111. package/docs/reference/subsystems/subagent.md +762 -0
  112. package/docs/reference/subsystems/subprocess.md +323 -0
  113. package/docs/reference/subsystems/system-prompt.md +226 -0
  114. package/docs/reference/subsystems/terminal.md +186 -0
  115. package/docs/reference/subsystems/todo.md +34 -0
  116. package/docs/reference/subsystems/token-meter.md +108 -0
  117. package/docs/reference/subsystems/tools.md +749 -0
  118. package/docs/reference/subsystems/typert.md +489 -0
  119. package/docs/reference/subsystems/user-questions.md +309 -0
  120. package/docs/reference/subsystems/voice-input.md +166 -0
  121. package/docs/reference/subsystems/web-client.md +102 -0
  122. package/docs/reference/subsystems/web-server.md +228 -0
  123. package/docs/reference/subsystems/web.md +208 -0
  124. package/docs/reference/subsystems/webhook.md +72 -0
  125. package/docs/reference/subsystems/workflow.md +280 -0
  126. package/docs/reference/subsystems/workspace.md +661 -0
  127. package/docs/start-here/blueprints.md +33 -0
  128. package/docs/start-here/this-runtime.md +84 -0
  129. package/docs/start-here/troubleshooting.md +29 -0
  130. package/docs/start-here/trust-and-safety.md +39 -0
  131. package/docs/start-here/verify-before-done.md +46 -0
  132. package/example-plugins/README.md +45 -0
  133. package/example-plugins/packages/agent-preset-reviewer/agent.cordis.yml +18 -0
  134. package/example-plugins/packages/agent-preset-reviewer/preset.yml +3 -0
  135. package/example-plugins/packages/capability-swap-consumer/cordis.patch.yml +3 -0
  136. package/example-plugins/packages/capability-swap-consumer/index.js +14 -0
  137. package/example-plugins/packages/capability-swap-consumer/package.json +25 -0
  138. package/example-plugins/packages/capability-swap-provider-loud/cordis.patch.yml +3 -0
  139. package/example-plugins/packages/capability-swap-provider-loud/index.js +20 -0
  140. package/example-plugins/packages/capability-swap-provider-loud/package.json +25 -0
  141. package/example-plugins/packages/capability-swap-provider-quiet/cordis.patch.yml +3 -0
  142. package/example-plugins/packages/capability-swap-provider-quiet/index.js +20 -0
  143. package/example-plugins/packages/capability-swap-provider-quiet/package.json +25 -0
  144. package/example-plugins/packages/chat-command-basic/cordis.patch.yml +3 -0
  145. package/example-plugins/packages/chat-command-basic/index.js +26 -0
  146. package/example-plugins/packages/chat-command-basic/package.json +25 -0
  147. package/example-plugins/packages/client-chat-message-action/client.js +46 -0
  148. package/example-plugins/packages/client-chat-message-action/cordis.patch.yml +3 -0
  149. package/example-plugins/packages/client-chat-message-action/index.js +9 -0
  150. package/example-plugins/packages/client-chat-message-action/package.json +31 -0
  151. package/example-plugins/packages/client-slot-header-action/client.js +57 -0
  152. package/example-plugins/packages/client-slot-header-action/cordis.patch.yml +3 -0
  153. package/example-plugins/packages/client-slot-header-action/index.js +13 -0
  154. package/example-plugins/packages/client-slot-header-action/package.json +31 -0
  155. package/example-plugins/packages/client-slot-sidebar-tab/client.js +57 -0
  156. package/example-plugins/packages/client-slot-sidebar-tab/cordis.patch.yml +3 -0
  157. package/example-plugins/packages/client-slot-sidebar-tab/index.js +9 -0
  158. package/example-plugins/packages/client-slot-sidebar-tab/package.json +32 -0
  159. package/example-plugins/packages/client-theme-override/client.js +52 -0
  160. package/example-plugins/packages/client-theme-override/cordis.patch.yml +3 -0
  161. package/example-plugins/packages/client-theme-override/index.js +9 -0
  162. package/example-plugins/packages/client-theme-override/package.json +30 -0
  163. package/example-plugins/packages/client-tool-view/client.js +47 -0
  164. package/example-plugins/packages/client-tool-view/cordis.patch.yml +3 -0
  165. package/example-plugins/packages/client-tool-view/index.js +24 -0
  166. package/example-plugins/packages/client-tool-view/package.json +34 -0
  167. package/example-plugins/packages/client-ui-components/client.js +77 -0
  168. package/example-plugins/packages/client-ui-components/cordis.patch.yml +3 -0
  169. package/example-plugins/packages/client-ui-components/index.js +9 -0
  170. package/example-plugins/packages/client-ui-components/package.json +31 -0
  171. package/example-plugins/packages/client-ui-library/client.js +715 -0
  172. package/example-plugins/packages/client-ui-library/cordis.patch.yml +3 -0
  173. package/example-plugins/packages/client-ui-library/index.js +9 -0
  174. package/example-plugins/packages/client-ui-library/package.json +37 -0
  175. package/example-plugins/packages/client-workspace-tab/client.js +72 -0
  176. package/example-plugins/packages/client-workspace-tab/cordis.patch.yml +3 -0
  177. package/example-plugins/packages/client-workspace-tab/index.js +9 -0
  178. package/example-plugins/packages/client-workspace-tab/package.json +30 -0
  179. package/example-plugins/packages/config-schema-basic/cordis.patch.yml +3 -0
  180. package/example-plugins/packages/config-schema-basic/index.js +19 -0
  181. package/example-plugins/packages/config-schema-basic/package.json +25 -0
  182. package/example-plugins/packages/desktop-main-profile-info/cordis.patch.yml +3 -0
  183. package/example-plugins/packages/desktop-main-profile-info/index.js +22 -0
  184. package/example-plugins/packages/desktop-main-profile-info/package.json +25 -0
  185. package/example-plugins/packages/event-hook-basic/cordis.patch.yml +3 -0
  186. package/example-plugins/packages/event-hook-basic/index.js +17 -0
  187. package/example-plugins/packages/event-hook-basic/package.json +22 -0
  188. package/example-plugins/packages/generated-capability-template/cordis.patch.yml +3 -0
  189. package/example-plugins/packages/generated-capability-template/index.js +16 -0
  190. package/example-plugins/packages/generated-capability-template/package.json +42 -0
  191. package/example-plugins/packages/host-route-basic/cordis.patch.yml +3 -0
  192. package/example-plugins/packages/host-route-basic/index.js +20 -0
  193. package/example-plugins/packages/host-route-basic/package.json +29 -0
  194. package/example-plugins/packages/lifecycle-function-basic/cordis.patch.yml +3 -0
  195. package/example-plugins/packages/lifecycle-function-basic/index.js +12 -0
  196. package/example-plugins/packages/lifecycle-function-basic/package.json +15 -0
  197. package/example-plugins/packages/lifecycle-function-hot-shim/cordis.patch.yml +3 -0
  198. package/example-plugins/packages/lifecycle-function-hot-shim/impl.js +5 -0
  199. package/example-plugins/packages/lifecycle-function-hot-shim/index.js +18 -0
  200. package/example-plugins/packages/lifecycle-function-hot-shim/package.json +23 -0
  201. package/example-plugins/packages/lifecycle-hooks-observer/cordis.patch.yml +3 -0
  202. package/example-plugins/packages/lifecycle-hooks-observer/index.js +23 -0
  203. package/example-plugins/packages/lifecycle-hooks-observer/package.json +22 -0
  204. package/example-plugins/packages/llm-adapter-echo/cordis.patch.yml +3 -0
  205. package/example-plugins/packages/llm-adapter-echo/index.js +42 -0
  206. package/example-plugins/packages/llm-adapter-echo/package.json +25 -0
  207. package/example-plugins/packages/prompt-assemble-hook/cordis.patch.yml +3 -0
  208. package/example-plugins/packages/prompt-assemble-hook/index.js +22 -0
  209. package/example-plugins/packages/prompt-assemble-hook/package.json +22 -0
  210. package/example-plugins/packages/prompt-contribution-basic/cordis.patch.yml +3 -0
  211. package/example-plugins/packages/prompt-contribution-basic/index.js +18 -0
  212. package/example-plugins/packages/prompt-contribution-basic/package.json +22 -0
  213. package/example-plugins/packages/service-consumer-greeter/cordis.patch.yml +3 -0
  214. package/example-plugins/packages/service-consumer-greeter/index.js +14 -0
  215. package/example-plugins/packages/service-consumer-greeter/package.json +22 -0
  216. package/example-plugins/packages/service-provider-greeter/cordis.patch.yml +3 -0
  217. package/example-plugins/packages/service-provider-greeter/index.js +22 -0
  218. package/example-plugins/packages/service-provider-greeter/package.json +25 -0
  219. package/example-plugins/packages/settings-section-basic/cordis.patch.yml +3 -0
  220. package/example-plugins/packages/settings-section-basic/index.js +34 -0
  221. package/example-plugins/packages/settings-section-basic/package.json +26 -0
  222. package/example-plugins/packages/skill-provider-basic/cordis.patch.yml +3 -0
  223. package/example-plugins/packages/skill-provider-basic/index.js +31 -0
  224. package/example-plugins/packages/skill-provider-basic/package.json +22 -0
  225. package/example-plugins/packages/state-host-store/client.js +57 -0
  226. package/example-plugins/packages/state-host-store/cordis.patch.yml +3 -0
  227. package/example-plugins/packages/state-host-store/index.js +90 -0
  228. package/example-plugins/packages/state-host-store/package.json +31 -0
  229. package/example-plugins/packages/state-workspace-file/cordis.patch.yml +3 -0
  230. package/example-plugins/packages/state-workspace-file/index.js +52 -0
  231. package/example-plugins/packages/state-workspace-file/package.json +25 -0
  232. package/example-plugins/packages/tool-basic/cordis.patch.yml +3 -0
  233. package/example-plugins/packages/tool-basic/index.js +25 -0
  234. package/example-plugins/packages/tool-basic/package.json +25 -0
  235. package/example-plugins/packages/tool-policy-hook/cordis.patch.yml +3 -0
  236. package/example-plugins/packages/tool-policy-hook/index.js +28 -0
  237. package/example-plugins/packages/tool-policy-hook/package.json +25 -0
  238. package/example-plugins/packages/tui-command-basic/cordis.patch.yml +3 -0
  239. package/example-plugins/packages/tui-command-basic/index.js +24 -0
  240. package/example-plugins/packages/tui-command-basic/package.json +22 -0
  241. package/example-plugins/packages/tui-overlay-themed/cordis.patch.yml +3 -0
  242. package/example-plugins/packages/tui-overlay-themed/index.js +65 -0
  243. package/example-plugins/packages/tui-overlay-themed/package.json +25 -0
  244. package/example-plugins/packages/tui-ui-library/cordis.patch.yml +3 -0
  245. package/example-plugins/packages/tui-ui-library/index.js +73 -0
  246. package/example-plugins/packages/tui-ui-library/package.json +29 -0
  247. package/example-plugins/packages/web-page-branding/cordis.patch.yml +3 -0
  248. package/example-plugins/packages/web-page-branding/index.js +31 -0
  249. package/example-plugins/packages/web-page-branding/package.json +22 -0
  250. package/example-plugins/scenarios.json +11 -0
  251. package/index.js +384 -0
  252. package/lib/blend-apply.js +107 -0
  253. package/lib/blend-capture.js +249 -0
  254. package/lib/blend-ledger.js +76 -0
  255. package/lib/contract.js +5 -0
  256. package/lib/install.js +516 -0
  257. package/lib/lookup.js +67 -0
  258. package/lib/manifest.js +56 -0
  259. package/lib/pack-root.js +22 -0
  260. package/lib/provenance.js +110 -0
  261. package/lib/publish.js +64 -0
  262. package/lib/reconcile.js +83 -0
  263. package/lib/router.js +55 -0
  264. package/lib/scopes.js +82 -0
  265. package/lib/skills.js +54 -0
  266. package/lib/stage.js +157 -0
  267. package/lib/verify.js +77 -0
  268. package/package.json +56 -3
  269. package/scripts/lib/indexes.mjs +45 -0
  270. package/scripts/lib/manifest.mjs +127 -0
  271. package/scripts/lib/maps.mjs +482 -0
  272. package/skills/acryl-add-provider-or-capability/SKILL.md +12 -0
  273. package/skills/acryl-add-ui/SKILL.md +18 -0
  274. package/skills/acryl-build-plugin/SKILL.md +21 -0
  275. package/skills/acryl-change-plugin/SKILL.md +16 -0
  276. package/skills/acryl-desktop-shell/SKILL.md +12 -0
  277. package/skills/acryl-diagnose-plugin/SKILL.md +10 -0
  278. package/skills/acryl-fix-plugin/SKILL.md +12 -0
  279. package/skills/acryl-improve-ui/SKILL.md +10 -0
  280. package/skills/acryl-remove-plugin/SKILL.md +11 -0
  281. package/skills/acryl-restyle-ui/SKILL.md +14 -0
  282. package/skills/acryl-share-plugin/SKILL.md +23 -0
  283. package/skills/acryl-tui-ui/SKILL.md +12 -0
  284. package/README.md +0 -3
@@ -0,0 +1,154 @@
1
+ <!-- Synced from deepseek-harness:docs/cordis-api/registry.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ <!-- Generated by scripts/gen-cordis-catalog.ts - do not edit by hand.
4
+ Run `pnpm run gen-cordis-catalog` to regenerate. -->
5
+
6
+ # Registry
7
+
8
+ Plugin loading and dependency injection.
9
+
10
+ ### ctx.inject(deps, callback)
11
+
12
+ ```ts cordis-catalog
13
+ /**
14
+ * Run a callback once the requested services are available.
15
+ *
16
+ * Shorthand for `ctx.plugin({ inject, apply: callback })`: the callback
17
+ * is unloaded and re-run whenever a required service changes.
18
+ *
19
+ * @param deps - required services, as an array or a name → config map.
20
+ * @param callback - plugin body called with `(ctx, config)`.
21
+ * @returns the fiber; awaiting it settles once loading finished.
22
+ */
23
+ inject(deps: Inject, callback: Plugin.Function<void>): Fiber & PromiseLike<Fiber>
24
+ ```
25
+
26
+ Run a callback once the requested services are available.
27
+
28
+ Shorthand for `ctx.plugin({ inject, apply: callback })`: the callback is unloaded and re-run whenever a required service changes.
29
+
30
+ - `deps` - required services, as an array or a name → config map.
31
+ - `callback` - plugin body called with `(ctx, config)`.
32
+
33
+ **Returns** the fiber; awaiting it settles once loading finished.
34
+
35
+ [Source](../../vendor/cordis/src/registry.ts#L176)
36
+
37
+ ### ctx.plugin(plugin, ...args)
38
+
39
+ ```ts cordis-catalog
40
+ /**
41
+ * Load a plugin in the current context.
42
+ *
43
+ * @param plugin - a function, class, or `{ apply }` object plugin.
44
+ * @param args - the plugin config, validated against its `Config` schema.
45
+ * @returns the fiber; awaiting it settles once loading finished
46
+ * (rejecting on config or startup errors).
47
+ */
48
+ plugin<P extends Plugin>(plugin: P, ...args: Spread<GetPluginConfig<P>>): Fiber & PromiseLike<Fiber>
49
+ ```
50
+
51
+ Load a plugin in the current context.
52
+
53
+ - `plugin` - a function, class, or `{ apply }` object plugin.
54
+ - `args` - the plugin config, validated against its `Config` schema.
55
+
56
+ **Returns** the fiber; awaiting it settles once loading finished (rejecting on config or startup errors).
57
+
58
+ [Source](../../vendor/cordis/src/registry.ts#L185)
59
+
60
+ ## Plugin
61
+
62
+ Supported plugin entrypoint shapes.
63
+
64
+ ```ts cordis-catalog
65
+ /** Supported plugin entrypoint shapes. */
66
+ type Plugin<T = any> =
67
+ | Plugin.Function<T>
68
+ | Plugin.Constructor<T>
69
+ | Plugin.Object<T>
70
+
71
+ /** Types associated with plugin entrypoints and runtime records. */
72
+ namespace Plugin {
73
+ /** Shared metadata understood by the plugin registry and related tooling. */
74
+ export interface Base<T = any> {
75
+ /** Display name used for fiber diagnostics and logger names. */
76
+ name?: string
77
+ /** Standard-schema validator applied to config before the plugin starts. */
78
+ Config?: StandardSchemaV1<any, T>
79
+ /** Services the plugin requires; it only loads while all are available. */
80
+ inject?: Inject
81
+ /** Service name(s) the plugin provides (read by `Service` and by loaders). */
82
+ provide?: string | string[]
83
+ /** Service names whose intercept config the plugin declares it consumes. */
84
+ intercept?: Dict<boolean>
85
+ }
86
+
87
+ export interface Transform<S, T> {
88
+ /** Marks the transform object as a schema/config transform. */
89
+ schema?: true
90
+ /** Convert user-facing config to runtime config. */
91
+ Config: (config: S) => T
92
+ }
93
+
94
+ /** Function plugin called with `(ctx, config)`. */
95
+ export interface Function<T = any> extends Base<T> {
96
+ (ctx: Context, config: T): any
97
+ }
98
+
99
+ /** Class plugin constructed with `(ctx, config)`. */
100
+ export interface Constructor<T = any> extends Base<T> {
101
+ new (ctx: Context, config: T): any
102
+ }
103
+
104
+ /** Object plugin with an `apply(ctx, config)` method. */
105
+ export interface Object<T = any> extends Base<T> {
106
+ apply(ctx: Context, config: T): any
107
+ }
108
+
109
+ /** Mutable registry record shared by all fibers of one plugin callback. */
110
+ export interface Runtime {
111
+ /** Display name copied from the first registered plugin shape. */
112
+ name?: string
113
+ /** Every live fiber of this plugin (one per `ctx.plugin()` call). */
114
+ fibers: DisposableList<Fiber>
115
+ /** The executable entrypoint all fibers share (registry identity key). */
116
+ callback: globalThis.Function
117
+ /** Standard-schema validator applied to each fiber's config. */
118
+ Config?: StandardSchemaV1
119
+ }
120
+ }
121
+ ```
122
+
123
+ [Source](../../vendor/cordis/src/registry.ts#L92)
124
+
125
+ ## Inject
126
+
127
+ Service dependency declaration accepted by plugins and the `@Inject` decorator.
128
+
129
+ Array form requests services without intercept config. Object form maps each service name to optional intercept config for the plugin context.
130
+
131
+ ```ts cordis-catalog
132
+ /**
133
+ * Service dependency declaration accepted by plugins and the `@Inject`
134
+ * decorator.
135
+ *
136
+ * Array form requests services without intercept config. Object form maps each
137
+ * service name to optional intercept config for the plugin context.
138
+ */
139
+ type Inject<M = Dict> = (keyof M)[] | { [K in keyof M]?: M[K] }
140
+
141
+ /** Utilities for normalizing plugin dependency declarations. */
142
+ namespace Inject {
143
+ /**
144
+ * Convert array/object/class-inherited inject metadata into a plain map.
145
+ *
146
+ * @param inject - the declaration to normalize; `null`/`undefined` add nothing.
147
+ * @param result - the map to fill (service name → intercept config or `null`).
148
+ * @returns `result`.
149
+ */
150
+ export function resolve(inject: Inject | null | undefined, result: Dict = Object.create(null))
151
+ }
152
+ ```
153
+
154
+ [Source](../../vendor/cordis/src/registry.ts#L19)
@@ -0,0 +1,104 @@
1
+ <!-- Synced from deepseek-harness:docs/cordis-api/service.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ <!-- Generated by scripts/gen-cordis-catalog.ts - do not edit by hand.
4
+ Run `pnpm run gen-cordis-catalog` to regenerate. -->
5
+
6
+ # Service
7
+
8
+ The base class for context services. A subclass loaded as a plugin registers itself as `ctx.<name>`.
9
+
10
+ Base class for services that expose a named API on `ctx`.
11
+
12
+ Subclasses call `super(ctx, name)` from their constructor. The service is registered immediately and is automatically removed with the owning fiber.
13
+
14
+ [Source](../../vendor/cordis/src/service.ts#L11)
15
+
16
+ ### service.name
17
+
18
+ ```ts cordis-catalog
19
+ /** The service name this instance is registered under. */
20
+ public name!: string
21
+ ```
22
+
23
+ The service name this instance is registered under.
24
+
25
+ [Source](../../vendor/cordis/src/service.ts#L30)
26
+
27
+ ## Static members
28
+
29
+ ### Service.init
30
+
31
+ ```ts cordis-catalog
32
+ /** Symbol key of an instance method run after construction (class plugins). */
33
+ static readonly init: unique symbol
34
+ ```
35
+
36
+ Symbol key of an instance method run after construction (class plugins).
37
+
38
+ [Source](../../vendor/cordis/src/service.ts#L13)
39
+
40
+ ### Service.check
41
+
42
+ ```ts cordis-catalog
43
+ /** Symbol key of the availability predicate passed to `ctx.provide()`. */
44
+ static readonly check: unique symbol
45
+ ```
46
+
47
+ Symbol key of the availability predicate passed to `ctx.provide()`.
48
+
49
+ [Source](../../vendor/cordis/src/service.ts#L15)
50
+
51
+ ### Service.config
52
+
53
+ ```ts cordis-catalog
54
+ /** Symbol key of the phantom intercept-config type parameter. */
55
+ static readonly config: unique symbol
56
+ ```
57
+
58
+ Symbol key of the phantom intercept-config type parameter.
59
+
60
+ [Source](../../vendor/cordis/src/service.ts#L17)
61
+
62
+ ### Service.invoke
63
+
64
+ ```ts cordis-catalog
65
+ /** Symbol key of the call body making a service callable (e.g. `ctx.logger()`). */
66
+ static readonly invoke: unique symbol
67
+ ```
68
+
69
+ Symbol key of the call body making a service callable (e.g. `ctx.logger()`).
70
+
71
+ [Source](../../vendor/cordis/src/service.ts#L19)
72
+
73
+ ### Service.extend
74
+
75
+ ```ts cordis-catalog
76
+ /** Symbol key of the helper deriving an extended service instance. */
77
+ static readonly extend: unique symbol
78
+ ```
79
+
80
+ Symbol key of the helper deriving an extended service instance.
81
+
82
+ [Source](../../vendor/cordis/src/service.ts#L21)
83
+
84
+ ### Service.tracker
85
+
86
+ ```ts cordis-catalog
87
+ /** Symbol key of the tracker metadata used for context tracing. */
88
+ static readonly tracker: unique symbol
89
+ ```
90
+
91
+ Symbol key of the tracker metadata used for context tracing.
92
+
93
+ [Source](../../vendor/cordis/src/service.ts#L23)
94
+
95
+ ### Service.resolveConfig
96
+
97
+ ```ts cordis-catalog
98
+ /** Symbol key of the intercept-config resolution helper below. */
99
+ static readonly resolveConfig: unique symbol
100
+ ```
101
+
102
+ Symbol key of the intercept-config resolution helper below.
103
+
104
+ [Source](../../vendor/cordis/src/service.ts#L25)
@@ -0,0 +1,167 @@
1
+ <!-- Synced from acryl:docs/cordis/cordis-usage-cheatsheet.md @ 79fc28c108. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Cordis usage cheatsheet (source-validated)
4
+
5
+ > **Purpose:** one condensed, operationally-accurate page for building on Cordis / DeepSeek
6
+ > Harness in this repo. Distils `docs/cordis/` + `docs/cordisplugins/` and **validates them
7
+ > against the vendored source**, so implementers don't trip on doc-vs-source drift.
8
+ >
9
+ > **Authority:** the pinned `deepseek-harness/` submodule. The vendored framework is
10
+ > `@deepseek-ai/cordis` **4.0.1** (a re-scoped ESM-first fork of upstream `cordis`), flat at
11
+ > `deepseek-harness/vendor/cordis/src`. The **generated** reference API docs live at
12
+ > `deepseek-harness/docs/cordis-api/*` (context/events/fiber/registry/service/inherited) -
13
+ > note `vendor/cordis/README.md` links to `docs/api/core.md` etc. which are **stale and do not
14
+ > exist**; use `docs/cordis-api/*`.
15
+ >
16
+ > The repo rule (AGENTS.md) requires reading `docs/cordis/cordis_system_guide_for_coding_agents.md`
17
+ > (the long handbook) before changing a plugin/service/tool. Treat this cheatsheet as the fast
18
+ > entry point; the handbook and `docs/cordis-api/*` are the full contract.
19
+
20
+ ---
21
+
22
+ ## 1. The kernel model
23
+
24
+ Cordis is a **meta-framework**: it knows nothing about LLMs, agents, tools, sessions, or shell.
25
+ DeepSeek Harness supplies those as domain services. The product is a **plugin tree** - every
26
+ capability above a tiny trusted substrate is a replaceable plugin.
27
+
28
+ | Piece | What it is | Key facts |
29
+ |---|---|---|
30
+ | **`Context`** | Scoped capability environment: DI container + service locator + event bus + effect owner + lifecycle scope. Proxy-backed. | `extend`/`isolate`/`intercept` are **class methods**; most `ctx.*` members are **mixed-in accessors** installed at root boot via `ReflectService.mixin`. Don't create random root `Context`s (each root is a second dependency universe). |
31
+ | **Service** | A named capability on `ctx` (`ctx.tools`, `ctx.llm`, `ctx.shell`). | `class X extends Service { constructor(ctx){ super(ctx,'name') } }` **provides at runtime**; `declare module 'cordis' { interface Context { name } }` is **compile-time only**. |
32
+ | **`inject`** | Live dependency contract. | `export const inject = ['tools']` is a **hard requirement** - the fiber stays `PENDING` until every named service exists. Not a load-order hint. Provider identity change reactivates consumers. |
33
+ | **Events** | Typed event bus. | 5 dispatch modes: `emit` (sync, no await), `parallel` (`Promise.allSettled`), `serial` (in order until bail), `bail` (first bail value), `waterfall` (compose; veto = **don't call `next()`**). |
34
+ | **Fiber** | One mounted plugin instance; the lifecycle unit. | States `PENDING → LOADING → ACTIVE → FAILED → UNLOADING → DISPOSED`. `PENDING` is valid (missing hard dep), not an error. `ACTIVE` = `apply` called. |
35
+ | **Effects** | Reversible ownership. | Registration = effect = ownership. Every resource is acquired inside **one owning `ctx.effect()`** and released by its disposer (LIFO, single-shot). A leak is an architecture bug. |
36
+ | **Loader** | `cordis.yml`/bundle/patch rows → live plugin tree. | Applies normalized `EntryOptions[]` to an `Entry` tree (`EntryGroup.update`/`Entry.create`); it does **not** parse YAML (the `include` plugin does). HMR is a plugin, requires `--expose-internals`, and is transactional. |
37
+
38
+ ## 2. The plugin contract
39
+
40
+ A plugin module exports, in order of common use:
41
+
42
+ ```ts
43
+ export const name = 'my-plugin' // stable id; MUST match the Loader row
44
+ export const inject = ['tools'] // hard deps (the fiber PENDINGs on them)
45
+ export const Config = /* sync StandardSchemaV1 */ // optional, validated before apply
46
+ export function apply(ctx, config?) { /* register capabilities, all effect-owned */ }
47
+ ```
48
+
49
+ - **Shapes:** function plugin (default, lifecycle only) → object plugin (structured) → `Service` class (only when the plugin **provides** a named service). Prefer function until you need to provide a service.
50
+ - **Config:** a **StandardSchemaV1, synchronous** schema (see §4 correction 1). Cordis validates the row config and fills defaults before `apply` - do NOT export a plain object.
51
+ - **Registration chain:**
52
+ ```
53
+ profile → dsh.profile.bundles → bundle.dsh.bundle.patch → cordis.patch.yml
54
+ → Loader row (name = package name or absolute module path)
55
+ → import module → Cordis calls apply(ctx)
56
+ ```
57
+ Desktop uses the **same** Loader/bundle contracts but inserts its own layer per generation.
58
+ - **Disposal rule:** every resource inside one owning `ctx.effect()`; stable Loader `id`s; config is **replaced**, not deep-merged; a provider change unloads + reactivates consumers driven by service availability, never YAML row order.
59
+
60
+ ## 3. Harness Tool contract (source: `AGENTS.md`, not `docs/cordisplugins/`)
61
+
62
+ A **Harness Tool** is a cordis consumer of `ctx.tools`, not a Cordis primitive:
63
+
64
+ ```ts
65
+ export const inject = ['tools']
66
+ export function apply(ctx, config) {
67
+ ctx.tools.register(defineTool({
68
+ name, description,
69
+ parameters: { /* ValueSchemaSpec */ },
70
+ output: { schema: /* ValueSchemaSpec */, render(args, value) { return [{ type: 'text', text }] } },
71
+ async execute(args, exec) { /* observe exec.signal; return the canonical value */ },
72
+ }))
73
+ // registration is effect-owned → disposed with the Fiber
74
+ }
75
+ ```
76
+
77
+ Contract requirements: canonical typed output split into `output.schema` (machine, lossless JSON)
78
+ and `output.render` (model-facing `ContentBlock[]`); honour `exec.signal`; traverse the tool
79
+ policy/event pipeline; no `output` declaration → `register` throws a `TypeError`. Effect-owned so
80
+ it disappears when its Fiber unloads.
81
+
82
+ ## 4. Source corrections (doc-vs-source drift - rely on the source)
83
+
84
+ These materially affect an implementation; validate against the vendored source, not the
85
+ handbook wording.
86
+
87
+ 1. **`Config` uses sync StandardSchema, not schemastery.** Core `resolveConfig` calls
88
+ `Config['~standard'].validate(config)` and **throws `TypeError('Async config validation is
89
+ not supported')`** for promise-yielding schemas (`vendor/cordis/src/fiber.ts:53-55`).
90
+ Schemastery `z.object` is used only for loader/timer/hmr *option* schemas, not plugin `Config`.
91
+ 2. **`ctx.timer`, `ctx.hmr`, `ctx.loader` are NOT on core.** They exist only when their plugin is
92
+ loaded. Never assume them without an `inject` dependency. `ctx.hmr` throws unless the process
93
+ was launched with `--expose-internals`.
94
+ 3. **`ctx.root` is `@experimental`**; **`ctx.baseUrl` is optional and loader-set** (core leaves it
95
+ `undefined`). Don't rely on them in a plugin.
96
+ 4. **`parallel` mislabels its dispatch mode as `'emit'`** in the `internal/dispatch` diagnostic
97
+ (`events.ts` calls `dispatch('emit', …)` internally) - a real nuance if a plugin branches on mode.
98
+ 5. **`FiberState` enum order is `PENDING, LOADING, ACTIVE, FAILED, DISPOSED, UNLOADING`**
99
+ (`DISPOSED=4`, `UNLOADING=5`) - differs from the JSDoc narrative order.
100
+ 6. **Real generated API docs are `deepseek-harness/docs/cordis-api/*`.** The
101
+ `vendor/cordis/README.md` links (`docs/api/core.md`, `docs/guides/loader-config.md`, …) are
102
+ stale and do not exist.
103
+ 7. **Vendored `@deepseek-ai/cordis` is 4.0.1** (ESM-first fork). The vendor manifest table's
104
+ `4.0.0-rc.7` is the *upstream* reference; the actual package/json in-tree is 4.0.1.
105
+
106
+ ## 5. Six-part mini-design (required before any new service seam)
107
+
108
+ Per `AGENTS.md`, write these before creating a service/tool/provider/event seam:
109
+
110
+ 1. **Capability and plugin boundary** - what domain owns it and why it needs independent
111
+ lifecycle/config/replacement.
112
+ 2. **Provides and consumes** - services/tools/events/durable facts; hard `inject` requirements and
113
+ intentional optional `ctx.get()` deps.
114
+ 3. **Effects and disposal** - every activation-owned resource, its disposer, cleanup order,
115
+ cancellation, quiescence.
116
+ 4. **Configuration and composition** - validated runtime schema, stable Loader row ids,
117
+ scopes/isolation, provider-replacement behavior.
118
+ 5. **Events and durability** - dispatch mode, explicit waterfall `next()` semantics, which
119
+ replay-critical facts live in durable session state.
120
+ 6. **Verification** - real Loader activation + PENDING/reactivation, provider replacement,
121
+ disposal, repeated mount/reload, leak checks.
122
+
123
+ ## 6. Worked pattern (what a correct ACRYL plugin looks like)
124
+
125
+ The shipped `acryl_workspace_status` (`@acryldev/harness-runtime/src/plugin-acryl-workspace-status.ts`)
126
+ follows this exactly: `inject: ['tools']`, `ctx.tools.register(defineTool({...}))` with
127
+ `output.schema`/`render` and `exec.signal`, auto-mounted on the booted `ctx.tools` seam, and
128
+ effect-owned so it disposes with its Fiber. For a **resource-owning** plugin, use the pattern:
129
+
130
+ ```ts
131
+ export const inject = ['someService']
132
+ export function apply(ctx, config) {
133
+ ctx.effect(() => {
134
+ const handle = startResource(config) // or ctx.on(...), ctx.tools.register(...)
135
+ return () => handle.stop() // sequential, idempotent disposer
136
+ }, 'my-plugin: resource')
137
+ // optional-on-this-profile capability: use ctx.get('optionalService') instead of inject
138
+ }
139
+ ```
140
+
141
+ ## 6b. Where plugins run - the three ACRYL surface kinds
142
+
143
+ Don't conflate "surface" with "thin consumer." ACRYL has three UI surfaces with different
144
+ relationships to the runtime:
145
+
146
+ - **TUI (`acryl-cli`)** - an **in-process** pi-tui agent surface, adapted from
147
+ `tomowang/dsh-tui` (`@tomowang/dsh-tui` 0.7.0 @ `f7663341`, `@earendil-works/pi-tui`
148
+ 0.84.2). It boots the runtime directly (`startDirectHost()` + `createAcrylSessionBridge()`)
149
+ and reads/writes `ctx` in-process - it is a rich agent UI, **not** an RPC client. It has
150
+ GUI-feature-parity overlays (`/model /presets /trajectory /tools /context /plugins /goal
151
+ /plan /compact` + approvals). DSH's `apps/cli` is only the `dsh` **launcher** and is **not**
152
+ the model for this.
153
+ - **Web (`acryl-web`)** - the browser renderer is a **separate client Cordis app** consuming
154
+ host services over typed RPC (typert) + `dsh-client-connection`; the Node host boots the
155
+ runtime in-process.
156
+ - **Desktop (`acryl-desktop`)** - Electron main boots the runtime; the renderer is the same
157
+ client shell over `file://` + IPC (not HTTP). It should NOT re-roll its own renderer.
158
+
159
+ See `docs/acryl/tomowang-dsh-tui-provenance.md` and the roadmap's M1 for the TUI origin.
160
+
161
+ ## 7. Reference pointers
162
+
163
+ - Long handbook: `docs/cordis/cordis_system_guide_for_coding_agents.md`
164
+ - Generated API: `deepseek-harness/docs/cordis-api/{context,events,fiber,registry,service,inherited}.md`
165
+ - Vendor source: `deepseek-harness/vendor/cordis/src/` (core), `vendor/loader/src/`, `vendor/include/src/`
166
+ - Plugin authoring: `docs/cordisplugins/` (hello-world, development-canvas)
167
+ - Tool contract + mini-design + fiber states: repo `AGENTS.md` → "Cordis development protocol"