@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,134 @@
1
+ <!-- Synced from deepseek-harness:docs/cookbook/extension-cookbook.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Cookbook: extension plugin shapes
4
+
5
+ English | [中文](extension-cookbook.zh.md)
6
+
7
+ Reference patterns for harness extensions. The snippets omit imports and helper implementations and are not copy-paste-complete. For concrete authoring paths, see the [package checklist](adding-a-package.md), [first-tool tutorial](../user/develop/basic/tool.md), [tool reference](adding-a-tool.md), [LLM adapter guide](adding-an-llm-adapter.md), and [Session format version tutorial](adding-a-session-format-version.md); the [architecture](../architecture.md) owns the system and extension-point map.
8
+
9
+ ## A tool plugin
10
+
11
+ A tool registers on `ctx.tools`. The annotated `defineTool` example (typed `execute` arguments, result construction, the `run_in_background` pattern) lives in [adding-a-tool.md](adding-a-tool.md) - that guide is the source of truth for tool definitions. Raw JSON-Schema `ToolDefinition`s are also accepted by `ctx.tools.register()` directly (that is how MCP-sourced tools arrive); `defineTool` is the typed helper for first-party tools.
12
+
13
+ ## A hook plugin (permission-gate example)
14
+
15
+ This permission gate is one example of a hook plugin. It returns a typed decision from the `tools/pre-execute` gate to allow or deny a call; sandbox, permission, and plan-mode plugins can use this extension point. Hook plugins can intercept other extension points and are not inherently permission gates. A "native hook" is an ordinary Cordis plugin on an interception point; it needs no external protocol.
16
+
17
+ ```ts
18
+ import type { Context } from '@deepseek-ai/cordis'
19
+ import type { PreToolDecision, ToolExecution } from '@deepseek-ai/dsh-tools'
20
+
21
+ declare function isAllowed(exec: ToolExecution): Promise<boolean>
22
+
23
+ export const name = 'permission-gate'
24
+
25
+ export function apply(ctx: Context) {
26
+ ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
27
+ if (!(await isAllowed(exec))) {
28
+ return { kind: 'deny', reason: 'Denied by policy.' }
29
+ }
30
+ return next()
31
+ })
32
+ }
33
+ ```
34
+
35
+ This waterfall is the reorderable policy layer. Use `ctx.tools.guard()` when an invariant needs a monotonic final denial, `tools/execute` when a plugin must wrap the dispatch lifetime (timeouts/retries/metrics; only `exec.signal` is replaceable), `tools/post-execute` for explicit result transformation, and `tools/result` for contained observation of the immutable final outcome. The [adding-a-tool guide](adding-a-tool.md#execution-policy-and-observation) gives the selection rule.
36
+
37
+ ## A UI plugin
38
+
39
+ A UI plugin combines durable `session/event` records (Assistant settlements, turn/step boundaries, and tool activity) with transient `agent/assistant-stream` frames for live token presentation, and drives input back in via `agent.followup()` / `agent.steer()`. A browser plugin contributing a business row to the built-in Web Client instead registers a `ConversationNodeDefinition` and keyed Chat renderer; follow the [Conversation subsystem reference](../subsystems/conversation.md).
40
+
41
+ ```ts
42
+ import type { Context } from '@deepseek-ai/cordis'
43
+ import { brandString } from '@deepseek-ai/dsh-brand'
44
+ import { createUserMessage } from '@deepseek-ai/dsh-llm'
45
+ import type { SessionId } from '@deepseek-ai/dsh-session'
46
+
47
+ declare function render(text: string): void
48
+ declare function onUserInput(handler: (text: string) => void): void
49
+
50
+ export const name = 'my-ui'
51
+ export const inject = ['agents']
52
+
53
+ export function apply(ctx: Context) {
54
+ ctx.on('agent/assistant-stream', ({ frame }) => {
55
+ if (frame.type === 'chunk' && frame.chunk.type === 'text-delta') {
56
+ render(frame.chunk.text)
57
+ }
58
+ })
59
+ onUserInput(text => ctx.agents.get(brandString<SessionId>('client-session'))?.followup(createUserMessage({
60
+ content: [{ type: 'text', text }],
61
+ source: { kind: 'user' },
62
+ })))
63
+ }
64
+ ```
65
+
66
+ ## An external protocol driver
67
+
68
+ A *protocol driver* adapts a wire peer to `ctx.agents`; it may serve a UI or an automation client. A stdio driver owns stdout, creates or resumes agents through the factory, and maps protocol requests to `followup()` or `cancel()`. A low-level prompt request returns its durable enqueue receipt; it does not acquire a result by correlating `MessageId` with `turn/end`. Publish whole-agent status separately. An automation method may wait from its receipt through the next idle and summarize that explicitly owned interval, while a UI normally keeps observing the open-ended event stream. Tear agents down with `AgentHandle.dispose()` so disposal reaches quiescence.
69
+
70
+ [`packages/acp/acp`](../../packages/acp/acp) is the automation-only worked example: it exposes fresh text sessions over Agent Client Protocol JSON-RPC stdio, emits committed assistant text, and registers a one-shot machine permission answerer for agents it owns. Its [README](../../packages/acp/acp/README.md) defines the exact methods, event order, and lifecycle contract.
71
+
72
+ ```ts
73
+ import type { Context } from '@deepseek-ai/cordis'
74
+ import { expandAssistantStream } from '@deepseek-ai/dsh-llm'
75
+
76
+ export const name = 'my-protocol-bridge'
77
+ export const inject = ['agents', 'sessions', 'sessionPersistence']
78
+
79
+ export function apply(ctx: Context) {
80
+ // Publish every committed Assistant text delta to the client.
81
+ ctx.on('session/event', (_session, event) => {
82
+ if (event.type === 'assistant/message' || event.type === 'assistant/attempt') {
83
+ for (const { chunk } of expandAssistantStream(event.data.stream)) {
84
+ if (chunk.type === 'text-delta') {
85
+ // sendToClient({ kind: 'message_chunk', text: chunk.text })
86
+ }
87
+ }
88
+ }
89
+ })
90
+ // Inbound "prompt": create/resume an agent, feed it, and return its enqueue receipt.
91
+ // Whole-agent status is a separate notification; no turn end belongs to this prompt.
92
+ // Teardown reaches quiescence via AgentHandle.dispose() (stop + await exit).
93
+ }
94
+ ```
95
+
96
+ ## Runnable wirings
97
+
98
+ Shipped applications contribute profile layers through `packages/bundle/*/cordis.patch.yml`, and the product `dsh` launcher owns Web, ACP, SDK, and one-shot headless execution through named profiles. Optional user-facing overlays live under `apps/cli/config/examples/`; profile integration tests live under `apps/cli/tests/profiles/`, while package-specific Loader compositions stay with their package tests.
99
+
100
+ ## The feature → mechanism map
101
+
102
+ Every product feature maps to a listener on a documented extension point - the microkernel claim made checkable ([microkernel Agent Note](../../.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md)). No row modifies the loop.
103
+
104
+ `system-prompt/assemble` is an expert cooperative whole-assembly transform: its returned assembly is authoritative, so listener authors own preserving active PTC mode and structured-output protocol contributions. Prefer `ctx.tools.restrict()` for tool filtering that must stay aligned across presentation, lookup, and execution.
105
+
106
+ | Product feature | Plugin mechanism |
107
+ |---|---|
108
+ | Hook system (user + project level) | listeners on `agent/created`, `agent/pre-step`, `agent/request`, `tools/pre-execute`, `tools/post-execute`, and `agent/turn-stopping`; the waterfalls return typed decisions, while `agent/turn-stopping` may steer another step; the `dsh-hooks-claude-code` / `dsh-hooks-codex` bridges map hook config files onto these extension points |
109
+ | `/goal` | `ctx.goals` owns durable state, `dsh-goal-round-driver` schedules same-session rounds through the public `Agent`, and separate command/tool producers expose human/model control |
110
+ | `/loop` | on the `turn/end` session event, `followup()` the next iteration; or force-continue |
111
+ | Dynamic workflow | `ctx.workflowEngine` + the PTC workflow engine + the `workflow` tool; structured in-process children enforce output with scoped prompt/tool registrations, a monotonic tool guard, final `tools/result` commit (including enclosing `run_code`), and the structured-output execution's monotonic `concludeTurn()` marker |
112
+ | Queued + steering messages | core `Agent.followup()` / `Agent.steer()` |
113
+ | Context compaction (auto + manual) | the `ctx.compaction` seam + `dsh-compaction-basic`; automatic pressure runs on serial `agent/pre-step`, canonical overflow recovery runs on `agent/request-error`, and manual callers use the same compact service ([compaction Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)) |
114
+ | System prompt configurability | `ctx.systemPrompt.section()` with ordering and scope-local shadowing |
115
+ | AGENTS.md (root) | a section provider reading the file |
116
+ | AGENTS.md (subdir, on-touch) + file-change notices | `agent.inject()` from a watcher / tool-result listener |
117
+ | Built-in tools | `ctx.tools.register()`; schemas flow into the assembly automatically - the `dsh-tool-*` families (bash, fs, web, subagent, todo) are the shipped examples |
118
+ | ToolSearch / progressive disclosure | replace a scoped `ctx.tools.restrict()` registration as the visible set changes; the registry keeps presentation, lookup, and execution aligned |
119
+ | Tool deadline / retry / metrics | wrap core dispatch with `tools/execute`; a wrapper may replace `exec.signal`, delegate, and inspect the normalized result in one lexical lifetime |
120
+ | Final tool-result metrics / audit / capture | observe immutable authoritative outcomes with `tools/result`; use `tools/post-execute` instead only when the plugin must transform the result or attach context |
121
+ | Monotonic terminal turn policy | call `ToolExecution.concludeTurn()` from the successful terminal tool; later tool calls in the same response remain guardable, and the loop stops after the step |
122
+ | Subprocess sandbox (landlock / sandbox-exec) | use a `ctx.sandbox` backend through `dsh-bash-sandbox`; use `tools/pre-execute` for capability-level denial |
123
+ | Permission system / AskUserQuestion | return `ask` from `tools/pre-execute` and answer through `ctx.approval`; register a separate model-facing ask tool for ordinary user questions |
124
+ | Plan mode | [`@deepseek-ai/dsh-plan-mode`](../../packages/plan/plan-mode/README.md) - logged `plan/mode` state, the `plan:policy` guidance section, `/plan [message]` entry, `/plan off` direct exit, and the user-reviewed `exit_plan_mode` exit; enforcement stays on the independent sandbox/approval axes |
125
+ | Sub-agent delegation | the `ctx.subagents` provider registry (`dsh-subagent-spawn-in-process`/`dsh-subagent-fork-in-process`/`dsh-subagent-acp`/`dsh-subagent-codex`/`dsh-subagent-claude-code`/`dsh-subagent-dsh-sdk`) + `dsh-tool-subagent` exposing one configured provider to the model |
126
+ | MCP | one plugin per server: discover tools → `ctx.tools.register()` |
127
+ | Skills | section + tool registration; `inject()` skill content on invocation |
128
+ | Memory | section provider + tool |
129
+ | Scheduled tasks (cron) | a plugin registers model-callable scheduling tools; timer fires → `followup(…, {source: {kind: 'plugin', plugin: 'schedule'}})` when idle / `inject()` notification when busy |
130
+ | UI (GUI; CLI emits JSONL) | listen to `agent/assistant-stream` for live chunks and `session/event` for durable settlements, boundaries, and tool activity; input → `followup()` |
131
+ | Web Client Chat business node | register a `ConversationNodeDefinition` and `conversation.chat.node` keyed renderer |
132
+ | SessionTelemetryBackend / replayable trace | `session/event` → JSONL; replay = `sessions.create(id, { seed })` |
133
+ | Model adapters | `LlmAdapter` subclass via `registerAdapter` (`dsh-llm-deepseek`, `dsh-llm-pi-ai`) |
134
+ | Plugin hot-reload | every registration is a `ctx.effect` → vendored HMR just works |
@@ -0,0 +1,366 @@
1
+ <!-- Synced from deepseek-harness:docs/cordis-api/context.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
+ # Context
7
+
8
+ The context is the core Cordis object: every service, event, and lifecycle API is reached through `ctx`. Event methods are documented on [Events](events.md), effects and the current fiber on [Fiber](fiber.md), and plugin loading on [Registry](registry.md).
9
+
10
+ Root and child dependency containers for Cordis plugins.
11
+
12
+ A context is a proxy: normal property reads go through the service resolver, while `extend()`, `isolate()`, and `intercept()` create scoped child contexts without mutating their parent.
13
+
14
+ [Source](../../vendor/cordis/src/context.ts#L42)
15
+
16
+ ### ctx.extend(meta?)
17
+
18
+ ```ts cordis-catalog
19
+ /**
20
+ * Create a child context with extra metadata on top of the current scope.
21
+ *
22
+ * The child prototypally inherits every property of this context; own
23
+ * properties of `meta` shadow the inherited ones. The parent is not mutated.
24
+ *
25
+ * @param meta - own properties (including symbol keys) to define on the child.
26
+ * @returns a child context inheriting from this one.
27
+ */
28
+ extend(meta = {}): this
29
+ ```
30
+
31
+ Create a child context with extra metadata on top of the current scope.
32
+
33
+ The child prototypally inherits every property of this context; own properties of `meta` shadow the inherited ones. The parent is not mutated.
34
+
35
+ - `meta` - own properties (including symbol keys) to define on the child.
36
+
37
+ **Returns** a child context inheriting from this one.
38
+
39
+ [Source](../../vendor/cordis/src/context.ts#L99)
40
+
41
+ ### ctx.isolate(name, label?)
42
+
43
+ ```ts cordis-catalog
44
+ /**
45
+ * Create a child context with an independent service scope for `name`.
46
+ *
47
+ * Below the returned context, reads and writes of the service `name`
48
+ * resolve against the new label instead of the parent's, so a different
49
+ * implementation can be provided without affecting the parent scope.
50
+ * Passing the same `label` to two `isolate()` calls joins their scopes.
51
+ *
52
+ * @param name - the service name to isolate.
53
+ * @param label - scope label to join; defaults to a fresh unique symbol.
54
+ * @returns a child context whose `name` service resolves in the new scope.
55
+ */
56
+ isolate(name: string, label?: symbol)
57
+ ```
58
+
59
+ Create a child context with an independent service scope for `name`.
60
+
61
+ Below the returned context, reads and writes of the service `name` resolve against the new label instead of the parent's, so a different implementation can be provided without affecting the parent scope. Passing the same `label` to two `isolate()` calls joins their scopes.
62
+
63
+ - `name` - the service name to isolate.
64
+ - `label` - scope label to join; defaults to a fresh unique symbol.
65
+
66
+ **Returns** a child context whose `name` service resolves in the new scope.
67
+
68
+ [Source](../../vendor/cordis/src/context.ts#L121)
69
+
70
+ ### ctx.intercept(name, config)
71
+
72
+ ```ts cordis-catalog
73
+ /**
74
+ * Add service-specific intercept config for plugins started below this
75
+ * context.
76
+ *
77
+ * Plugins loaded under the returned context see `config` merged into the
78
+ * service's resolved config (ancestor entries first; see
79
+ * `Service[symbols.resolveConfig]`). The parent context is not affected.
80
+ *
81
+ * @param name - the service name whose config to intercept.
82
+ * @param config - the intercept config to merge for that service.
83
+ * @returns a child context carrying the additional intercept entry.
84
+ */
85
+ intercept<K extends InjectKey>(name: K, config: Context[K] extends { [symbols.config]: infer T } ? T : never): this
86
+ intercept(name: string, config: any): this
87
+ ```
88
+
89
+ Add service-specific intercept config for plugins started below this context.
90
+
91
+ Plugins loaded under the returned context see `config` merged into the service's resolved config (ancestor entries first; see `Service[symbols.resolveConfig]`). The parent context is not affected.
92
+
93
+ - `name` - the service name whose config to intercept.
94
+ - `config` - the intercept config to merge for that service.
95
+
96
+ **Returns** a child context carrying the additional intercept entry.
97
+
98
+ [Source](../../vendor/cordis/src/context.ts#L139)
99
+
100
+ ### ctx.root
101
+
102
+ ```ts cordis-catalog
103
+ /** The root context of the application (every child context shares it). @experimental */
104
+ root: this
105
+ ```
106
+
107
+ The root context of the application (every child context shares it). @experimental
108
+
109
+ [Source](../../vendor/cordis/src/context.ts#L22)
110
+
111
+ ### ctx.baseUrl
112
+
113
+ ```ts cordis-catalog
114
+ /** Base URL used to resolve relative plugin/module specifiers, if the runtime sets one. */
115
+ baseUrl?: string
116
+ ```
117
+
118
+ Base URL used to resolve relative plugin/module specifiers, if the runtime sets one.
119
+
120
+ [Source](../../vendor/cordis/src/context.ts#L24)
121
+
122
+ ### ctx.events
123
+
124
+ ```ts cordis-catalog
125
+ /** The event bus. Its methods are also mixed onto `ctx` (`ctx.on`, `ctx.emit`, ...). */
126
+ events: EventsService
127
+ ```
128
+
129
+ The event bus. Its methods are also mixed onto `ctx` (`ctx.on`, `ctx.emit`, ...).
130
+
131
+ [Source](../../vendor/cordis/src/context.ts#L26)
132
+
133
+ ### ctx.logger
134
+
135
+ ```ts cordis-catalog
136
+ /** The logging service. Call `ctx.logger(name)` for a named logger. */
137
+ logger: LoggerService
138
+ ```
139
+
140
+ The logging service. Call `ctx.logger(name)` for a named logger.
141
+
142
+ [Source](../../vendor/cordis/src/context.ts#L28)
143
+
144
+ ### ctx.reflect
145
+
146
+ ```ts cordis-catalog
147
+ /** The reflection layer backing the context proxy (`ctx.get`, `ctx.provide`, ...). */
148
+ reflect: ReflectService
149
+ ```
150
+
151
+ The reflection layer backing the context proxy (`ctx.get`, `ctx.provide`, ...).
152
+
153
+ [Source](../../vendor/cordis/src/context.ts#L30)
154
+
155
+ ### ctx.registry
156
+
157
+ ```ts cordis-catalog
158
+ /** The plugin registry. Its methods are mixed onto `ctx` (`ctx.plugin`, `ctx.inject`). */
159
+ registry: RegistryService
160
+ ```
161
+
162
+ The plugin registry. Its methods are mixed onto `ctx` (`ctx.plugin`, `ctx.inject`).
163
+
164
+ [Source](../../vendor/cordis/src/context.ts#L32)
165
+
166
+ ## Static members
167
+
168
+ ### Context.effect
169
+
170
+ ```ts cordis-catalog
171
+ /** Symbol key under which a disposer exposes its {@link EffectMeta} diagnostics tree. */
172
+ static readonly effect: unique symbol
173
+ ```
174
+
175
+ Symbol key under which a disposer exposes its EffectMeta diagnostics tree.
176
+
177
+ [Source](../../vendor/cordis/src/context.ts#L44)
178
+
179
+ ### Context.filter
180
+
181
+ ```ts cordis-catalog
182
+ /** Symbol key for a context's listener filter, consulted on every event dispatch. */
183
+ static readonly filter: unique symbol
184
+ ```
185
+
186
+ Symbol key for a context's listener filter, consulted on every event dispatch.
187
+
188
+ [Source](../../vendor/cordis/src/context.ts#L46)
189
+
190
+ ### Context.isolate
191
+
192
+ ```ts cordis-catalog
193
+ /** Symbol key of the isolation map (see the `Context[symbols.isolate]` property). */
194
+ static readonly isolate: unique symbol
195
+ ```
196
+
197
+ Symbol key of the isolation map (see the `Context[symbols.isolate]` property).
198
+
199
+ [Source](../../vendor/cordis/src/context.ts#L48)
200
+
201
+ ### Context.intercept
202
+
203
+ ```ts cordis-catalog
204
+ /** Symbol key of the intercept map (see the `Context[symbols.intercept]` property). */
205
+ static readonly intercept: unique symbol
206
+ ```
207
+
208
+ Symbol key of the intercept map (see the `Context[symbols.intercept]` property).
209
+
210
+ [Source](../../vendor/cordis/src/context.ts#L50)
211
+
212
+ ### Context.is(value)
213
+
214
+ ```ts cordis-catalog
215
+ /**
216
+ * Returns true for Cordis context proxies and context prototypes.
217
+ *
218
+ * Works across realms and across multiple copies of cordis, because the
219
+ * brand is keyed by a global symbol rather than by `instanceof`.
220
+ *
221
+ * @param value - the value to test.
222
+ * @returns `true` if `value` is a Cordis context, narrowing its type.
223
+ */
224
+ static is(value: any): value is Context
225
+ ```
226
+
227
+ Returns true for Cordis context proxies and context prototypes.
228
+
229
+ Works across realms and across multiple copies of cordis, because the brand is keyed by a global symbol rather than by `instanceof`.
230
+
231
+ - `value` - the value to test.
232
+
233
+ **Returns** `true` if `value` is a Cordis context, narrowing its type.
234
+
235
+ [Source](../../vendor/cordis/src/context.ts#L61)
236
+
237
+ ## Service store and mixins
238
+
239
+ ### ctx.get(name, strict?)
240
+
241
+ ```ts cordis-catalog
242
+ /**
243
+ * Read a service from the store without the inject requirement.
244
+ *
245
+ * @param name - the service name.
246
+ * @param strict - when `true` (default), only return implementations
247
+ * whose providing fiber is currently active.
248
+ * @returns the service value, or `undefined` when not (yet) provided.
249
+ */
250
+ get<K extends string & keyof this>(name: K, strict?: boolean): undefined | this[K]
251
+ get(name: string, strict?: boolean): any
252
+ ```
253
+
254
+ Read a service from the store without the inject requirement.
255
+
256
+ - `name` - the service name.
257
+ - `strict` - when `true` (default), only return implementations whose providing fiber is currently active.
258
+
259
+ **Returns** the service value, or `undefined` when not (yet) provided.
260
+
261
+ [Source](../../vendor/cordis/src/reflect.ts#L17)
262
+
263
+ ### ctx.set(name, value)
264
+
265
+ ```ts cordis-catalog
266
+ /**
267
+ * Overwrite a provided service's value.
268
+ *
269
+ * Only the fiber that provided the service may set it; setting an
270
+ * unprovided name throws.
271
+ *
272
+ * @param name - the service name.
273
+ * @param value - the new service value.
274
+ */
275
+ set<K extends string & keyof this>(name: K, value: undefined | this[K]): void
276
+ set(name: string, value: any): void
277
+ ```
278
+
279
+ Overwrite a provided service's value.
280
+
281
+ Only the fiber that provided the service may set it; setting an unprovided name throws.
282
+
283
+ - `name` - the service name.
284
+ - `value` - the new service value.
285
+
286
+ [Source](../../vendor/cordis/src/reflect.ts#L29)
287
+
288
+ ### ctx.provide(name, value)
289
+
290
+ ```ts cordis-catalog
291
+ /**
292
+ * Register a service implementation owned by the current fiber.
293
+ *
294
+ * The service becomes visible to dependents in the same isolation scope
295
+ * once the fiber is active; it is unregistered (waking dependents) when
296
+ * the returned disposer runs or the fiber unloads. Throws if the name is
297
+ * already provided in this scope or declared as an accessor.
298
+ *
299
+ * @param name - the service name.
300
+ * @param value - the service value.
301
+ * @returns a disposer that unregisters the service.
302
+ */
303
+ provide<K extends string & keyof this>(name: K, value: undefined | this[K]): () => void
304
+ provide(name: string, value?: any): () => void
305
+ ```
306
+
307
+ Register a service implementation owned by the current fiber.
308
+
309
+ The service becomes visible to dependents in the same isolation scope once the fiber is active; it is unregistered (waking dependents) when the returned disposer runs or the fiber unloads. Throws if the name is already provided in this scope or declared as an accessor.
310
+
311
+ - `name` - the service name.
312
+ - `value` - the service value.
313
+
314
+ **Returns** a disposer that unregisters the service.
315
+
316
+ [Source](../../vendor/cordis/src/reflect.ts#L44)
317
+
318
+ ### ctx.accessor(name, options)
319
+
320
+ ```ts cordis-catalog
321
+ /**
322
+ * Define a computed context property backed by get/set hooks.
323
+ *
324
+ * The accessor is removed when the current fiber unloads. Throws if the
325
+ * name is already declared.
326
+ *
327
+ * @param name - the context property name.
328
+ * @param options - the `get` hook and optional `set` hook.
329
+ */
330
+ accessor(name: string, options: Omit<Property.Accessor, 'type'>): void
331
+ ```
332
+
333
+ Define a computed context property backed by get/set hooks.
334
+
335
+ The accessor is removed when the current fiber unloads. Throws if the name is already declared.
336
+
337
+ - `name` - the context property name.
338
+ - `options` - the `get` hook and optional `set` hook.
339
+
340
+ [Source](../../vendor/cordis/src/reflect.ts#L56)
341
+
342
+ ### ctx.mixin(name, mixins)
343
+
344
+ ```ts cordis-catalog
345
+ /**
346
+ * Expose selected members of a service directly on `ctx`.
347
+ *
348
+ * Each mixed-in key becomes an accessor that forwards to the service
349
+ * (binding methods to it), so e.g. `ctx.on` forwards to `ctx.events.on`.
350
+ * Mixins are removed when the current fiber unloads.
351
+ *
352
+ * @param name - the context property holding the source service.
353
+ * @param mixins - keys to forward, or a source-key → ctx-key map.
354
+ */
355
+ mixin<K extends string & keyof this>(name: K, mixins: (keyof this & keyof this[K])[] | Dict<string>): void
356
+ mixin<T extends {}>(source: T, mixins: (keyof this & keyof T)[] | Dict<string>): void
357
+ ```
358
+
359
+ Expose selected members of a service directly on `ctx`.
360
+
361
+ Each mixed-in key becomes an accessor that forwards to the service (binding methods to it), so e.g. `ctx.on` forwards to `ctx.events.on`. Mixins are removed when the current fiber unloads.
362
+
363
+ - `name` - the context property holding the source service.
364
+ - `mixins` - keys to forward, or a source-key → ctx-key map.
365
+
366
+ [Source](../../vendor/cordis/src/reflect.ts#L67)