@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,157 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/settings.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Plugin Configuration Forms
4
+
5
+ English | [中文](settings.zh.md)
6
+
7
+ The [settings service](../../packages/settings/settings/README.md) projects volatile Config fields from active profile entries. The [configuration editor](../../packages/boot/config-editor/README.md) persists edits through Cordis patches. Business consumers read `.get()` on their own Config references.
8
+
9
+ ## Identity and values
10
+
11
+ A form namespace is the local id of a uniquely addressed entry in the active profile. Multiple plugin instances have separate forms when their entry ids differ. Ordinary fields are excluded. Descriptors carry resolved values, inherited values, explicit profile overrides, and an optimistic revision.
12
+
13
+ ## Edits
14
+
15
+ `update` merges submitted fields. `replace` resets live fields to inherited configuration before applying submitted fields. `mutate` addresses individual paths, preserving secrets absent from a client response. Every write validates the complete Config and refuses stale revisions before persistence.
16
+
17
+ `settings/document-updated` invalidates form descriptors after Loader configuration changes. It is a UI notification; consumers use `loader/volatile-update` only when they need to refresh registration facts.
18
+
19
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
20
+
21
+ <a id="cordis-surface"></a>
22
+
23
+ ## Cordis API
24
+
25
+ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) - the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
26
+
27
+ <a id="ctxsettings--settingsforms"></a>
28
+
29
+ ### `ctx.settings` - `SettingsForms`
30
+
31
+ Project Config schemas into forms and own optional instance-level UI policy.
32
+
33
+ ```ts cordis-catalog
34
+ /** Register the calling plugin instance's page policy without changing its Config.
35
+ * @param presentation Automatic-page policy for this instance; `auto` defaults to true.
36
+ * @param owner Plugin instance the policy belongs to; defaults to the calling fiber.
37
+ * @returns Disposer; register it with the calling plugin's effects.
38
+ * @throws If this instance already has a registered policy.
39
+ */
40
+ configure(presentation: { auto?: boolean }, owner: Fiber = this.ctx.fiber): () => void
41
+
42
+ /** Locate the profile patch for native editing.
43
+ * @returns The existing profile patch path.
44
+ */
45
+ prepareDocument(): Promise<string>
46
+
47
+ /** Read active plugin schemas and their live values.
48
+ * @param options Redaction required for remote callers.
49
+ * @returns Forms keyed by unique profile entry ids.
50
+ */
51
+ describe(options?: SettingsDescribeOptions): SettingsDescriptor[]
52
+
53
+ /** Merge editable fields into an entry's config.
54
+ * @param ns Profile entry id.
55
+ * @param patch Fields to merge.
56
+ * @param expectedRevision Revision returned by describe.
57
+ */
58
+ async update(ns: string, patch: object, expectedRevision?: number): Promise<void>
59
+
60
+ /** Reset all live fields, then set the supplied fields; ordinary config is preserved.
61
+ * @param ns Profile entry id.
62
+ * @param section Complete form values.
63
+ * @param expectedRevision Revision returned by describe.
64
+ */
65
+ async replace(ns: string, section: object, expectedRevision?: number): Promise<void>
66
+
67
+ /** Apply field edits without restating redacted secrets; unsetting an array index removes its element.
68
+ * @param ns Profile entry id.
69
+ * @param ops Ordered form edits.
70
+ * @param expectedRevision Revision returned by describe.
71
+ */
72
+ async mutate(ns: string, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>
73
+ ```
74
+
75
+ Source: [`packages/settings/settings/src/index.ts`](../../packages/settings/settings/src/index.ts)
76
+
77
+ <a id="ctxsettingscontroller--settingscontroller"></a>
78
+
79
+ ### `ctx.settingsController` - `SettingsController`
80
+
81
+ Host service backing the generated `ctx.remote.settings` namespace. Every remote read uses `redactSecrets: true`, so a `role('secret')` field cannot ride a response. Writes expose the settings service's merge, replacement, and path-addressed operations, and classify every provider refusal as `settings/conflict` or `settings/rejected` with the service's message.
82
+
83
+ ```ts cordis-catalog
84
+ /**
85
+ * Describe every registered namespace for a configuration page: redacted
86
+ * layered values plus the serialized schema the page renders its form from.
87
+ * @returns provider writability, local-document presence, and one view per namespace.
88
+ * @throws RemoteError when no settings provider is mounted.
89
+ */
90
+ @Remote describe(): SettingsDescribeValue
91
+
92
+ /**
93
+ * Merge a patch into one namespace's stored user section.
94
+ * @param ns - namespace key to write.
95
+ * @param patch - fields to merge into the user section.
96
+ * @param expectedRevision - revision the caller read; `undefined` writes unconditionally.
97
+ * @returns the namespace's redacted view after the write.
98
+ * @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
99
+ */
100
+ @Remote update( ns: string, patch: Record<string, JsonValue>, expectedRevision: number | undefined, ): Promise<SettingsNamespaceView>
101
+
102
+ /**
103
+ * Replace one namespace's stored user section wholesale.
104
+ * @param ns - namespace key to write.
105
+ * @param section - complete replacement user section.
106
+ * @param expectedRevision - revision the caller read; `undefined` writes unconditionally.
107
+ * @returns the namespace's redacted view after the write.
108
+ * @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
109
+ */
110
+ @Remote replace( ns: string, section: Record<string, JsonValue>, expectedRevision: number | undefined, ): Promise<SettingsNamespaceView>
111
+
112
+ /**
113
+ * Apply path-addressed edits to one namespace's user section, resolved against
114
+ * the section as stored rather than against whatever the caller last read,
115
+ * then answer with that namespace's new redacted view.
116
+ * @param ns - namespace key to write.
117
+ * @param ops - the edits to apply, in order.
118
+ * @param expectedRevision - revision the caller read; `undefined` writes unconditionally.
119
+ * @returns the namespace's redacted view after the write.
120
+ * @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
121
+ */
122
+ @Remote async mutate( ns: string, ops: SettingsPathOpView[], expectedRevision: number | undefined, ): Promise<SettingsNamespaceView>
123
+
124
+ /**
125
+ * Materialize the provider-owned settings document and open it in a native text editor.
126
+ * @param signal - caller lifetime; abort terminates preparation or the native command.
127
+ * @returns confirmation after the native opener accepts the document.
128
+ * @throws RemoteError when no document exists, preparation fails, or opening fails.
129
+ */
130
+ @Remote async openSettingsDocument(signal: AbortSignal): Promise<SettingsDocumentOpenValue>
131
+ ```
132
+
133
+ Source: [`packages/api/settings-controller/src/index.ts`](../../packages/api/settings-controller/src/index.ts)
134
+
135
+ <a id="settings-events"></a>
136
+
137
+ ### `settings/*` events
138
+
139
+ <a id="settingsdocument-updated--emit"></a>
140
+
141
+ #### `settings/document-updated` - emit
142
+
143
+ One profile entry's form values, availability, or page policy changed. Form clients re-read its schema, resolved values, and revision.
144
+
145
+ ```ts cordis-catalog
146
+ /**
147
+ * One profile entry's form values, availability, or page policy changed.
148
+ * Form clients re-read its schema, resolved values, and revision.
149
+ * @param ns Profile entry id.
150
+ * @param revision The entry's new revision.
151
+ * @mode emit
152
+ */
153
+ 'settings/document-updated'(ns: SettingsNamespace, revision: number): void
154
+ ```
155
+
156
+ Source: [`packages/settings/settings/src/types.ts`](../../packages/settings/settings/src/types.ts)
157
+ <!-- END GENERATED cordis-surface -->
@@ -0,0 +1,316 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/shell.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Shell Executor
4
+
5
+ English | [中文](shell.zh.md)
6
+
7
+ The shell execution seam uses [dsh-shell](../../packages/shell/shell) as its Service Definition on `ctx.shell`. The [shell package group](../../packages/shell/README.md) lists its Bash and PowerShell providers and model-facing Consumers. Generic background-job ids, ownership, and controls live in [jobs.md](jobs.md); this seam returns a process handle without job registration. Managed-range mechanics live behind the [subprocess seam](subprocess.md).
8
+
9
+ Source: [`packages/shell/shell/src/types.ts`](../../packages/shell/shell/src/types.ts)
10
+
11
+ ## Managed shell environment namespace
12
+
13
+ `DSH_*` variables are Harness-owned child-process facts. The model-facing bash tool collects them through `ctx.shellEnv` and passes them through `ShellExecRequest.dshEnv`; the subprocess service removes inherited `DSH_*` names before merging the current snapshot. The `DshEnvironmentKey`/`DshEnvironment` vocabulary is owned by the [subprocess seam](subprocess.md) and re-exported by `dsh-shell`.
14
+
15
+ ## Request vs. spec: the `resolve()` split
16
+
17
+ The seam separates the **model-/plugin-facing request** (optional `workdir`/`timeoutMs`/`stdoutMaxBytes`, filled from config or request policy) from the **fully-resolved spec** the executor acts on (those fields required). The tool layer calls `ctx.shell.resolve(request)` between them (the repo's "explicit > implicit at package boundaries" rule); a `ShellExecSpec` carries resolved values.
18
+
19
+ ```ts type-equiv
20
+ /**
21
+ * A caller's execution REQUEST: `workdir` and `timeoutMs` are optional and
22
+ * filled by {@link ShellExecutor.resolve} from the implementation's config.
23
+ * This is the model-/plugin-facing shape; pass it to `resolve()` to obtain a
24
+ * fully-resolved {@link ShellExecSpec}.
25
+ */
26
+ interface ShellExecRequest {
27
+ command: string
28
+ /** Working directory override (default: implementation-configured). */
29
+ workdir?: string | undefined
30
+ /** Timeout override in milliseconds (implementations cap it). */
31
+ timeoutMs?: number | undefined
32
+ /** Deadline policy at `timeoutMs` expiry (default `'kill'`). */
33
+ onExpiry?: ShellExpiryPolicy | undefined
34
+ /**
35
+ * Foreground stdout capture budget in bytes. Absent uses the executor's
36
+ * default output cap. Trusted in-process consumers use this when they must
37
+ * parse complete stdout up to their own bounded limit; the model-facing bash
38
+ * tool does not expose it as a parameter.
39
+ */
40
+ stdoutMaxBytes?: number | undefined
41
+ /** Abort signal - implementations kill the command when it fires, and treat a signal that is already aborted as fired. */
42
+ signal?: AbortSignal | undefined
43
+ /**
44
+ * Bytes to write to the command's stdin, then close it. Absent leaves stdin
45
+ * closed/empty (the default for model-driven tool calls). Set by in-process
46
+ * plugins (e.g. the hooks bridges, which write a hook command's JSON payload
47
+ * to its stdin); the model-facing bash tool does not expose it as a parameter
48
+ * (a model that needs stdin uses shell syntax like a heredoc or a pipe).
49
+ */
50
+ stdin?: string | undefined
51
+ /**
52
+ * Ordinary environment entries for the command, merged after the credential
53
+ * scrub. Managed facts belong in {@link dshEnv}, which merges after this
54
+ * map, so an entry here can never displace one. Set by in-process plugins
55
+ * (the hooks bridges set `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, …); the
56
+ * model-facing bash tool does not expose it as a parameter.
57
+ */
58
+ env?: Record<string, string> | undefined
59
+ /**
60
+ * Harness-owned `DSH_*` variables for this execution (typed to managed
61
+ * keys). Executors discard ambient `DSH_*` entries before merging this
62
+ * snapshot last, so an unavailable current fact cannot inherit a stale
63
+ * value from the harness process and a caller {@link env} entry cannot
64
+ * displace a managed one.
65
+ */
66
+ dshEnv?: DshEnvironment | undefined
67
+ /** Fully resolved per-call sandbox policy; sandboxing executors default it. */
68
+ sandboxPolicy?: SandboxExecutionPolicy | undefined
69
+ }
70
+ ```
71
+
72
+ ```ts type-equiv
73
+ /**
74
+ * A resolved execution spec. {@link ShellExecutor.resolve} fills and caps the
75
+ * required fields; under `onExpiry: 'none'` the resolved `timeoutMs` arms no
76
+ * timer and is only echoed into {@link ShellRunResult.timeoutMs}.
77
+ */
78
+ interface ShellExecSpec {
79
+ command: string
80
+ workdir: string
81
+ timeoutMs: number
82
+ /** Deadline policy at `timeoutMs` expiry ({@link ShellExecutor.resolve} defaults it to `'kill'`). */
83
+ onExpiry: ShellExpiryPolicy
84
+ /**
85
+ * Resolved stdout capture budget in bytes, applied to every execution's
86
+ * stdout; stderr keeps the executor's own output cap.
87
+ */
88
+ stdoutMaxBytes: number
89
+ /** Abort signal - implementations kill the command when it fires, and treat a signal that is already aborted as fired. */
90
+ signal?: AbortSignal | undefined
91
+ /** Bytes to write to stdin before closing it; absent means no stdin. */
92
+ stdin?: string | undefined
93
+ /**
94
+ * Ordinary environment entries carried through from
95
+ * {@link ShellExecRequest.env}; {@link dshEnv} still merges after them.
96
+ * OPTIONAL on the spec for the same reason as `stdin`: absent means no
97
+ * ordinary extra environment.
98
+ */
99
+ env?: Record<string, string> | undefined
100
+ /** Managed `DSH_*` snapshot (typed to managed keys); merges after {@link env}. */
101
+ dshEnv?: DshEnvironment | undefined
102
+ /** Resolved sandbox policy; ignored by executors that do not confine. */
103
+ sandboxPolicy: SandboxExecutionPolicy | undefined
104
+ }
105
+ ```
106
+
107
+ `stdin` and `env` are trusted in-process plugin inputs and are not exposed by `dsh-tool-bash`. The local executor scrubs ambient credentials before merging explicit caller-supplied env.
108
+
109
+ `stdoutMaxBytes` is also trusted-plugin-only. It lets a foreground consumer request complete stdout up to a bounded parser budget without changing stderr, background jobs, or the model-facing bash tool's ordinary output cap.
110
+
111
+ ## Foreground runs: `ShellRunResult`
112
+
113
+ The outcome of one completed (or killed) foreground run. Orthogonal outcomes are reported **independently** - a process can both time out AND exit 0 because it trapped the signal - so `timedOut`, `aborted`, `signal`, and `exitCode` are each their own field; a caller never reads a cut-short run as a clean success.
114
+
115
+ ```ts type-equiv
116
+ /** The outcome of a foreground run, including timeout during preparation. */
117
+ interface ShellRunResult {
118
+ /** Exit code; null when preparation expired or the process died from a signal. */
119
+ exitCode: number | null
120
+ /** Terminating signal, or null when none was reported, including preparation expiry. */
121
+ signal: NodeJS.Signals | null
122
+ /**
123
+ * True when the executor's own timeout was the FIRST cause to cut the command
124
+ * short. Mutually exclusive with {@link aborted}: one fused deadline drives
125
+ * both the timeout and the caller's cancellation, so a timeout and an abort
126
+ * racing before process close report the single first-abort cause, not both
127
+ * (see the [timeout-library Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)).
128
+ */
129
+ timedOut: boolean
130
+ /**
131
+ * True when the caller's `AbortSignal` was the FIRST cause to kill the command
132
+ * (and it was not the executor's own timeout). Mutually exclusive with
133
+ * {@link timedOut} - see there for the first-cause classification.
134
+ */
135
+ aborted: boolean
136
+ /** The effective timeout applied to this run (after defaulting/capping). */
137
+ timeoutMs: number
138
+ stdout: CollectedOutput
139
+ stderr: CollectedOutput
140
+ /** Sandbox execution facts, absent for an unsandboxed executor. */
141
+ sandbox?: ShellSandboxInfo
142
+ }
143
+ ```
144
+
145
+ Each stream is a `CollectedOutput` - the (possibly truncated) text plus recovery info; when truncated, `text` is the **tail** and the complete stream spills to a private file. The fields are owned by the [subprocess seam](subprocess.md) and re-exported by `dsh-shell`.
146
+
147
+ ## File sandbox: `ShellSandboxInfo`
148
+
149
+ A sandbox-consuming executor exposes its configured mode fallback through `ShellExecutor.sandboxMode`. The tool layer asks [`@deepseek-ai/dsh-sandbox-policy`](../../packages/sandbox/sandbox-policy/README.md) to resolve each calling session's durable `sandbox/mode` override and immutable cwd into `ShellExecRequest.sandboxPolicy`; a user-approved strictly wider call replaces only the mode. The mode/root/enforcement vocabulary is owned by the [`@deepseek-ai/dsh-sandbox` seam](sandbox.md); modes govern file effects only.
150
+
151
+ A sandboxed run reports its mode, conservative denial classification, and enforcement completeness. `runnerFailed` marks a sandbox runner failure before the command ran; foreground execution throws `SANDBOX_UNAVAILABLE`, while a settled background process has only its facts channel.
152
+
153
+ ```ts type-equiv
154
+ /**
155
+ * Sandbox facts for one run, present iff a sandboxing executor handled it.
156
+ * Facts are reported independently of process exit status so callers can
157
+ * distinguish command failures from policy denials and runner failures.
158
+ */
159
+ interface ShellSandboxInfo {
160
+ /** The mode the command actually ran under. */
161
+ mode: SandboxMode
162
+ /** Whether the sandbox denied a file operation. */
163
+ denied: boolean
164
+ /** How completely the selected runner enforced the requested mode. */
165
+ enforcement?: SandboxEnforcement
166
+ /** Whether the sandbox runner failed before the command could run. */
167
+ runnerFailed?: boolean
168
+ }
169
+ ```
170
+
171
+ The `SANDBOX_UNAVAILABLE` error code (owned by the [sandbox seam](sandbox.md)) is what the `ctx.sandbox` provider throws - and the executor propagates - when a confined mode has no usable backend. A selected runner refusing its profile reaches the same fail-closed foreground error; a settled background job records `runnerFailed`. The model receives denial/runner facts in results, learns the effective mode only when a denial marker names it, and can request a one-shot strictly wider retry through `sandbox_permissions` plus `justification`; `ctx.approval` must grant that exact call before anything executes. The complete policy and switching design is the [sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md).
172
+
173
+ ## Background processes: `ShellProcess`
174
+
175
+ `start()` resolves with a handle after asynchronous launch preparation; cancellation or preparation failure rejects before publication. The handle has no id or owner. `dsh-tool-bash` adapts it into `ctx.jobs.start()` hooks; the generic runtime then owns job identity and lifecycle. `done` resolves when the underlying process settles and never rejects; a subprocess provider rejection becomes a `killed` process with a stage-neutral error on stderr. Reads remain valid after settlement, and sandbox facts are stamped before `done` resolves.
176
+
177
+ ```ts type-equiv
178
+ /**
179
+ * A background process handle returned by {@link ShellExecutor.start}. It is the
180
+ * only access path; buffered output remains readable after exit. Composition
181
+ * teardown (the subprocess service's disposal) kills running processes and
182
+ * awaits {@link done}; an executor-only reload leaves them running.
183
+ */
184
+ interface ShellProcess {
185
+ /** Process lifecycle state (settled exactly once). */
186
+ status: ShellProcessStatus
187
+ /** Exit code once finished (null = killed by signal / still running). */
188
+ exitCode: number | null
189
+ /** Terminating signal name, when signal-killed. */
190
+ signal: NodeJS.Signals | null
191
+ /**
192
+ * Resolves when the underlying process settles (never rejects - provider
193
+ * rejection settles as `killed` with a stage-neutral error on stderr).
194
+ */
195
+ readonly done: Promise<void>
196
+ /** Sandbox facts, stamped once a confined process settles. */
197
+ sandbox?: ShellSandboxInfo
198
+ /**
199
+ * Read output produced since the previous read (consuming - consecutive
200
+ * reads never re-deliver). Reads that lost data flag `lossy` and point at
201
+ * full-stream spill files when available.
202
+ */
203
+ readOutput(): ShellProcessRead
204
+ /**
205
+ * Non-consuming offset readers over the same captured streams the consuming
206
+ * {@link readOutput} cursor drains, including the provider-failure note a
207
+ * rejected spawn leaves on stderr. Independent observers read here at their
208
+ * own offsets without stealing bytes from `readOutput`.
209
+ */
210
+ observed: ShellObservedStreams
211
+ /**
212
+ * Terminate the provider-managed range. Returns false when it had already finished
213
+ * (no-op); idempotent.
214
+ */
215
+ kill(): boolean
216
+ }
217
+ ```
218
+
219
+ `readOutput()` returns the incremental delta and spill recovery facts:
220
+
221
+ ```ts type-equiv
222
+ /** One incremental {@link ShellProcess.readOutput} read. */
223
+ interface ShellProcessRead {
224
+ /** Output produced since the previous read (stderr in a marked section). */
225
+ delta: string
226
+ /** True when truncation dropped unread bytes the delta cannot include. */
227
+ lossy: boolean
228
+ /** Full stdout spill file, when stdout truncation occurred and a safe path is available. */
229
+ stdoutSpillPath?: string
230
+ /** Full stderr spill file, when stderr truncation occurred and a safe path is available. */
231
+ stderrSpillPath?: string
232
+ }
233
+ ```
234
+
235
+ ## The service
236
+
237
+ `ShellExecutor` owns `resolve`, foreground `run`, background-process `start`, and the `sandboxMode` capability fact. `dsh-bash-local` owns command defaulting, timeout/abort classification, the terminal environment, and the background read merge; managed-range termination, bounded collectors, spill files, credential scrubbing, and disposal quiescence are the [subprocess service](subprocess.md)'s. `dsh-tool-bash` owns model-facing rendering and adapts background handles into the [generic job runtime](jobs.md). `dsh-shell` owns the shell tools' shared exit-status contract: the exported `parseExitStatus`/`ParsedExitStatus` inverts the `[exit code: N]` / `[killed by signal: X]` markers `dsh-tool-bash`'s `renderResult` and `dsh-tool-pwsh`'s `renderPwshResult` append, and both tools' `presentResult` use it to split the rendered text into the terminal card's output body and its exit-status pill.
238
+
239
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
240
+
241
+ <a id="cordis-surface"></a>
242
+
243
+ ## Cordis API
244
+
245
+ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) - the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
246
+
247
+ <a id="ctxshell--shellexecutor-abstract-seam"></a>
248
+
249
+ ### `ctx.shell` - `ShellExecutor` (abstract seam)
250
+
251
+ Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin - it registers as `ctx.shell` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
252
+
253
+ execute resolves with the process handle after preparation. "Foreground" is a property of what the caller awaits, not of the spawn - a caller that awaits ShellExecution.result ran the command in the foreground; one that keeps the handle ran it in the background. A caller that waits only for a while runs the command under `onExpiry: 'none'` and bounds its own wait; the handle stays valid after the caller stops waiting.
254
+
255
+ Implementations must honor these semantics:
256
+
257
+ - ShellExecution.result rejects only for infrastructure failures. Nonzero exits, timeout kills, and abort kills resolve with a descriptive result: first-cause `timedOut`/`aborted`, the spec's `timeoutMs` echoed.
258
+ - The handle is published after preparation. `done` settles at process close and never rejects; spawn failures settle as `killed` with the error on the read path, while `result()` carries the same failure as its rejection.
259
+ - `onExpiry: 'none'` arms no deadline; `'kill'` kills at expiry. Expiry during preparation returns a settled timed-out handle without output.
260
+ - ShellProcess.readOutput is incremental: consecutive reads never repeat output. Lossy reads report truncation and available spill files.
261
+ - A still-running process is stopped and awaited when its owning composition tears down. With the subprocess seam that boundary is `ctx.subprocess` disposal, so a process survives an executor-only reload.
262
+
263
+ ```ts cordis-catalog
264
+ /**
265
+ * Apply implementation-owned defaults and caps to a request before execution.
266
+ * @param request - the caller's request; omitted fields get this
267
+ * implementation's defaults, capped fields are clamped.
268
+ * @returns the fully-specified spec to hand to {@link execute}.
269
+ */
270
+ abstract resolve(request: ShellExecRequest): ShellExecSpec
271
+
272
+ /**
273
+ * Prepare and spawn the command under its resolved deadline.
274
+ * @param spec - a resolved spec from {@link resolve}, never a raw request.
275
+ * @returns the prepared handle, including its result projection;
276
+ * preparation timeout yields an already-settled handle with no output.
277
+ * @throws on preparation failure or caller cancellation before process publication.
278
+ */
279
+ abstract execute(spec: ShellExecSpec): Promise<ShellExecution>
280
+ ```
281
+
282
+ Source: [`packages/shell/shell/src/index.ts`](../../packages/shell/shell/src/index.ts)
283
+
284
+ <a id="ctxshellenv--shellenvregistry"></a>
285
+
286
+ ### `ctx.shellEnv` - `ShellEnvRegistry`
287
+
288
+ Registry (`ctx.shellEnv`) for trusted, per-execution `DSH_*` variables. The namespace is rebuilt for every model shell call: ambient `DSH_*` values are discarded by the executor, then the registry's current snapshot is injected. Built-in shell facts remain owned by the registry itself while plugins can register additional, enumerable facts with effect-scoped disposal.
289
+
290
+ ```ts cordis-catalog
291
+ /**
292
+ * Register one environment contributor. Names and keys are unique; built-in
293
+ * keys are reserved. Registration is disposed with the calling plugin fiber.
294
+ * @param contributor - declared key ownership and per-execution resolver.
295
+ * @returns the disposer that unregisters the contribution.
296
+ */
297
+ register(contributor: BashEnvContributor): () => void
298
+
299
+ /**
300
+ * Build the trusted `DSH_*` snapshot for one shell tool execution.
301
+ * @param execution - the current tool execution.
302
+ * @returns an immutable environment overlay containing built-ins and current contributions.
303
+ */
304
+ collect(execution: ToolExecution): DshEnvironment
305
+
306
+ /**
307
+ * Enumerate plugin-contributed variables without executing their resolvers.
308
+ * @returns declarations sorted by environment variable name.
309
+ */
310
+ list(): BashEnvVariableInfo[]
311
+ ```
312
+
313
+ Types: [DshEnvironment](subprocess.md) · [ToolExecution](tools.md)
314
+
315
+ Source: [`packages/shell/shell-env/src/index.ts`](../../packages/shell/shell-env/src/index.ts)
316
+ <!-- END GENERATED cordis-surface -->