@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,94 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/client-resources.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Client Resources
4
+
5
+ English | [中文](client-resources.zh.md)
6
+
7
+ The client resource model turns an address into live data for any Web Client component. [`dsh-client-resources`](../../packages/client/resources/README.md) provides the `ctx.resources` service and the `useResource` global standard hook; a package that owns a kind of content registers one **provider** for its **protocol**, and a component reads the content's current state by **address** without importing the owner's runtime. The right Sidebar's tabs are the model's first consumer ([Right Sidebar](sidebar-right.md)); the decision record is the [client resource model Agent Note](../../.agents/notes/implemented/architecture/2026-09-05-client-resource-model.md).
8
+
9
+ This page is the developer reference: how to write an address, how to register a provider, how to read a resource, what the states and failures mean, and how the model holds and releases a resource.
10
+
11
+ ## Addresses
12
+
13
+ A resource address is a `dsh-resource://<type>/…` URL. The host names the protocol and must be a key of `ResourceProtocolMap`; the path is the protocol's own, and its owner percent-encodes each segment. A protocol that needs a scope puts it in the path: the `file` protocol's addresses read `dsh-resource://file/session/<sessionId>/<path>`, where path is workspace-relative or absolute with its leading slashes preserved, built with `fileAddressFor(sessionId, cwd, path)` and read back with `parseFileAddress(address)` from [`dsh-util-workspace-path`](../../packages/util/workspace-path/README.md). The model itself reads only the scheme and the host: `protocolOf(address)` returns the lower-cased host of a `dsh-resource://` URL and `undefined` for anything else. Addresses under any other scheme - the Sidebar's `sidebar://guide` - name no resource and read as `none`.
14
+
15
+ | Address | Protocol key | Reads as |
16
+ |---|---|---|
17
+ | `dsh-resource://file/session/s1/notes/a.md` | `file` | the metadata of `notes/a.md` under session `s1`'s workspace root, when the `file` provider is registered |
18
+ | `dsh-resource://file/absolute/home/me/notes.md` | `file` | parseable but fails with `workspace-file/unknown-workspace`: no authorizing Session, and neither current nor Tab Session is borrowed |
19
+ | `DSH-RESOURCE://File/session/s1/a` | `file` | a distinct record: addresses compare as strings, and `openResource` accepts only the canonical lower-case spelling that `fileAddressFor` emits |
20
+ | `dsh-resource://subagentchat/session/c1?parent=p1&mode=continuable` | `subagentchat` | an addressed subagent Conversation whose value owns a `SessionReference` until the resource closes |
21
+ | `sidebar://guide` | - | `none`: a navigation address |
22
+ | `/home/me/notes.md` | - | `none`: not a URL |
23
+
24
+ ## Registering a provider
25
+
26
+ The owner of a protocol declares its value type on `ResourceProtocolMap` and registers one provider inside its own `ctx.effect`, so the protocol lives exactly as long as the plugin ([provide a protocol](../../packages/client/resources/README.md#provide-a-protocol)). `open(address, { signal })` returns a stream of `RemoteResult` frames - the current state first, then one frame per change - and must stop when `signal` aborts. A failure is an `ok: false` frame carrying a `RemoteFailure`; a throw inside the stream is a programming error and is not caught.
27
+
28
+ ```ts ignore-check
29
+ import type { Context } from '@deepseek-ai/cordis'
30
+ import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
31
+ import type {} from '@deepseek-ai/dsh-client-resources/client'
32
+
33
+ interface NoteView { readonly title: string; readonly updatedAt: string }
34
+
35
+ declare module '@deepseek-ai/dsh-client-ui-slots' {
36
+ interface ResourceProtocolMap { note: NoteView }
37
+ }
38
+
39
+ export const inject = ['resources', 'remote']
40
+
41
+ export function apply(ctx: Context): void {
42
+ ctx.effect(() => ctx.resources.register<'note'>({
43
+ protocol: 'note',
44
+ async *open(address, { signal }): AsyncIterable<RemoteResult<NoteView>> {
45
+ const id = new URL(address).pathname.slice(1)
46
+ yield await ctx.remote.notes.read(id, signal)
47
+ for await (const change of ctx.remote.notes.follow(id, signal)) yield change
48
+ },
49
+ }), 'my-notes: note resource provider')
50
+ }
51
+ ```
52
+
53
+ A protocol has exactly one provider; a second registration throws. Registering while addresses of the protocol are already held opens their streams at once; disposing the provider ends those streams and the addresses read `none` until a provider returns.
54
+
55
+ ## Reading a resource
56
+
57
+ Every slot component receives `useResource` in its props, whatever its scope ([Slots](slots.md)). `useResource<P>(address)` names the protocol as the type argument and returns the address's current snapshot; subscribing is what holds the resource open, and a component that mounts while another holder keeps the resource alive reads the latest value at once without reopening the stream ([read a resource](../../packages/client/resources/README.md#read-a-resource)).
58
+
59
+ | `status` | Meaning | `value` | `failure` |
60
+ |---|---|---|---|
61
+ | `none` | No provider is registered for the address's protocol, or the address is not a resource address | `undefined` | `undefined` |
62
+ | `loading` | The provider's stream is open and has not yielded yet | `undefined` | `undefined` |
63
+ | `live` | The latest frame succeeded | the latest `ok` value | `undefined` |
64
+ | `failed` | The latest frame reported a failure | the last `ok` value, kept | the frame's `RemoteFailure` |
65
+
66
+ ```tsx ignore-check
67
+ import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
68
+ import type {} from '@deepseek-ai/dsh-api-workspace-files/client'
69
+
70
+ type Props = PropsRuntime<'sidebar.right.pane.tab'>
71
+
72
+ export function FileHeader({ useTabInfo, useResource, t }: Props) {
73
+ const { tab } = useTabInfo()
74
+ const meta = useResource<'file'>(tab.contentId)
75
+ if (meta.status === 'failed') return <p role="alert">{t('failed', { code: meta.failure.code })}</p>
76
+ return (
77
+ <header>
78
+ {tab.title}
79
+ </header>
80
+ )
81
+ }
82
+ ```
83
+
84
+ A consumer presents `failed` itself: the model keeps the last value beside the failure so a body can show stale content with a notice rather than a blank, and the next `ok` frame clears the failure. Nothing in the model produces user-visible text.
85
+
86
+ ## Holding and releasing
87
+
88
+ A resource is alive while it has a holder: a subscribed `useResource`, or a pin. `ctx.resources.pin(address, signal)` keeps a resource open without subscribing until `signal` aborts, and an already-aborted signal pins nothing; the right Sidebar pins every open tab record's address for the record's life, so switching tabs unmounts a body without closing its stream. The first holder opens the provider's stream; the last release aborts it, discards the value, and returns the snapshot to `loading` (provider present) or `none` (absent). A frame the provider yields after that release is dropped, and the iterator is returned. `ctx.resources.source(address)` is the bare observable behind the hook, reference-stable per address, for callers outside React; reading its snapshot does not hold the resource ([lifecycle](../../packages/client/resources/README.md#lifecycle)).
89
+
90
+ Most streams carry metadata rather than content. The `file` provider's value is `WorkspaceFileStat { absolutePath, version, bytes? }`: the first frame comes from Host `stat`, and later observations update the version. A consumer reads content through the Workspace Files Remote namespace; Preview owns refresh independently per tab ([`dsh-api-workspace-files`](../../packages/api/workspace-files/README.md)). The `subagentchat` provider retains the addressed Session and yields its `SessionReference`, then releases that reference when the resource signal aborts.
91
+
92
+ ## Limits
93
+
94
+ Records live for the page lifetime: an address's record stays after its last holder leaves, holding no stream and no value, so memory grows with the number of distinct addresses ever read. A provider that ignores `signal` keeps running until its next frame. The failure type is the Remote face's `RemoteFailure`, so a provider whose source is not a Remote call mints one. A misspelled protocol or a malformed address reads as `none` with no other diagnostic.
@@ -0,0 +1,225 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/commands.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Human Commands
4
+
5
+ English | [中文](commands.zh.md)
6
+
7
+ The human-command registry service from [`dsh-commands`](../../packages/interaction/commands). Interactive adapters use it to discover and directly execute plugin-owned commands for an exact agent without creating a model message. The [command Agent Note](../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md) owns dispatch and lifecycle rationale; the [package README](../../packages/interaction/commands/README.md) owns composition and limitations.
8
+
9
+ Source: [`packages/interaction/commands/src/index.ts`](../../packages/interaction/commands/src/index.ts)
10
+
11
+ ## Input metadata
12
+
13
+ The service exposes one optional unstructured-input descriptor: a hint plus an attachment-acceptance flag. Command availability follows plugin composition: every adapter consuming the registry sees every effective definition.
14
+
15
+ ```ts type-equiv
16
+ /** Immutable metadata for a command's optional unstructured input. */
17
+ interface CommandInputDescriptor {
18
+ /** Placeholder shown before the user supplies free-form input. */
19
+ readonly hint: string
20
+ /**
21
+ * Whether composer attachments may accompany an invocation. Absent or
22
+ * false = the executor rejects an invocation carrying attachments and capable
23
+ * composers refuse the submission before dispatch. A declaring command's
24
+ * handler receives the admitted durable blocks and owns every further
25
+ * grammar decision, including rejecting sub-commands that cannot use them.
26
+ */
27
+ readonly attachments?: boolean
28
+ }
29
+ ```
30
+
31
+ ## Definition
32
+
33
+ `CommandDefinition` is the plugin-authored registration. The registry validates and freezes a detached effective definition.
34
+
35
+ ```ts type-equiv
36
+ /** Plugin-owned command registration. */
37
+ interface CommandDefinition {
38
+ /** Stable plugin-owned identity; absent for definitions without identity-based client behavior. */
39
+ readonly definitionId?: CommandDefinitionId
40
+ /** Lowercase command name without the leading slash. */
41
+ readonly name: string
42
+ /** Human-readable summary used in discovery UI. */
43
+ readonly description: string
44
+ /** Optional free-form input hint advertised to capable clients. */
45
+ readonly input?: CommandInputDescriptor
46
+ /**
47
+ * Whether `command/run` records `rawInput`. Defaults to true. A command
48
+ * whose domain event owns the payload sets this false to avoid duplicating
49
+ * that payload in the session log.
50
+ */
51
+ readonly recordInput?: boolean
52
+ /** Execute against the receiving agent without sending the command to the model. */
53
+ readonly handler: (invocation: CommandInvocation) => CommandResult | Promise<CommandResult>
54
+ }
55
+ ```
56
+
57
+ ## Invocation and result
58
+
59
+ The adapter owns cancellation and passes the exact target agent. `rawInput` begins immediately after the parsed name and retains the adapter-delivered separator and suffix. Results are direct UI outcomes, not tool results or session events.
60
+
61
+ ```ts type-equiv
62
+ /** Invocation passed to one registered command handler. */
63
+ interface CommandInvocation {
64
+ /** Pairing id already written to this invocation's `command/run` event. */
65
+ readonly commandId: CommandId
66
+ /** Exact agent whose UI received the command. */
67
+ readonly agent: Agent
68
+ /** Exact text following the registered command name, including separator whitespace. */
69
+ readonly rawInput: string
70
+ /**
71
+ * Durably admitted image and file blocks accompanying this invocation, in submission
72
+ * order; empty unless the definition declares `input.attachments`. The handler
73
+ * owns their model-visible use - the registry never schedules them itself -
74
+ * and a handler whose grammar cannot use them in this invocation returns an
75
+ * error so the dispatching composer retains the originals.
76
+ */
77
+ readonly attachments: readonly (ImageBlock | FileBlock)[]
78
+ /** Cancellation signal owned by the dispatching UI request. */
79
+ readonly signal: AbortSignal
80
+ }
81
+ ```
82
+
83
+ ```ts type-equiv
84
+ /** Expected command outcome rendered directly by the dispatching UI. */
85
+ type CommandResult =
86
+ | {
87
+ readonly kind: 'success'
88
+ readonly text?: string
89
+ /** Earlier authoritative domain event that owns a richer presentation. */
90
+ readonly sourceEventSeq?: SessionSeq
91
+ }
92
+ | { readonly kind: 'error'; readonly text: string }
93
+ ```
94
+
95
+ `sourceEventSeq` is optional and success-only. When present, it names an earlier non-command event in the receiving session log; `command/done` persists the same reference so a client can combine the command lifecycle with that domain projection without parsing `text` or relying on adjacent rows.
96
+
97
+ ## Discovery and parsing views
98
+
99
+ Adapters receive handler-free immutable descriptors after scope resolution. `parseCommand()` returns `ParsedCommand` before registry resolution; syntax-valid input can still name an unavailable command.
100
+
101
+ ```ts type-equiv
102
+ /** Handler-free immutable command view returned to UI adapters. */
103
+ interface CommandDescriptor {
104
+ /** Stable plugin-owned identity; absent for definitions without identity-based client behavior. */
105
+ readonly definitionId?: CommandDefinitionId
106
+ /** Lowercase command name without the leading slash. */
107
+ readonly name: string
108
+ /** Human-readable summary used in discovery UI. */
109
+ readonly description: string
110
+ /** Optional free-form input hint advertised to capable clients. */
111
+ readonly input?: CommandInputDescriptor
112
+ }
113
+ ```
114
+
115
+ ```ts type-equiv
116
+ /** Syntactically valid slash command before registry resolution. */
117
+ interface ParsedCommand {
118
+ /** Lowercase command name without the leading slash. */
119
+ readonly name: string
120
+ /** Exact text following the command name. */
121
+ readonly rawInput: string
122
+ }
123
+ ```
124
+
125
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
126
+
127
+ <a id="cordis-surface"></a>
128
+
129
+ ## Cordis API
130
+
131
+ 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).
132
+
133
+ <a id="ctxcommands--commandruntime"></a>
134
+
135
+ ### `ctx.commands` - `CommandRuntime`
136
+
137
+ Human-command registry. Plain-context definitions are global; definitions registered through a command-injected child of an agent context shadow globals for that agent.
138
+
139
+ ```ts cordis-catalog
140
+ /**
141
+ * Register a global or calling-agent-scoped command.
142
+ * @param definition - discovery metadata and direct UI handler.
143
+ * @returns the exact effect disposer that unregisters this definition.
144
+ */
145
+ register(definition: CommandDefinition): () => void
146
+
147
+ /**
148
+ * Register the sole authority that resolves staged file receipts for command submissions.
149
+ * @param resolver - Session-aware receipt resolver.
150
+ * @returns disposer that removes this exact resolver.
151
+ */
152
+ registerFileReceiptResolver(resolver: CommandFileReceiptResolver): () => void
153
+
154
+ /**
155
+ * List the effective immutable command descriptors for one agent.
156
+ * @param agent - exact receiving agent and scoped-layer key.
157
+ * @returns name-sorted descriptors after scoped shadowing.
158
+ */
159
+ @Remote list(agent: Agent): readonly CommandDescriptor[]
160
+
161
+ /**
162
+ * Resolve one effective command definition.
163
+ * @param agent - exact receiving agent and scoped-layer key.
164
+ * @param name - command name without a slash.
165
+ * @returns the scoped shadow or global definition.
166
+ */
167
+ find(agent: Agent, name: string): CommandDefinition | undefined
168
+
169
+ /**
170
+ * Parse and execute a known command without sending it to the model.
171
+ *
172
+ * A resolved command's lifecycle is logged: `command/run` is appended
173
+ * before the handler is invoked and `command/done` after settlement (a
174
+ * thrown or aborted handler settles as `kind: 'error'`). Both are direct
175
+ * log-only appends - no turn wraps them, and persistence drains them at
176
+ * ordinary checkpoints. Admission misses (syntax or unknown name) log
177
+ * nothing - they never entered a handler. A `command/run` append failure
178
+ * fails the execution loud; a `command/done` append failure on the
179
+ * handler-failure path is contained so the handler's own error stays the
180
+ * reported failure.
181
+ *
182
+ * Attachment admission is enforced here, not in the composer: attachments sent to a
183
+ * command that does not declare `input.attachments`, an absent attachment store,
184
+ * and an exceeded image limit each settle as an error result before
185
+ * the handler runs. Validation rejection starts no attachment writes;
186
+ * a storage failure can leave only unreachable content-addressed objects
187
+ * for deferred collection.
188
+ *
189
+ * @param agent - exact receiving agent.
190
+ * @param line - complete slash-command line.
191
+ * @param submittedAttachments - encoded images and staged file receipts accompanying the line,
192
+ * in submission order; empty for a plain invocation.
193
+ * @param signal - cancellation signal owned by the UI request.
194
+ * @returns the settled execution (result + lifecycle pairing id), or
195
+ * `undefined` when syntax or name does not resolve.
196
+ */
197
+ @Remote async execute( agent: Agent, line: string, submittedAttachments: readonly CommandSubmitAttachment[], signal: AbortSignal, ): Promise<CommandExecution | undefined>
198
+ ```
199
+
200
+ Types: [Agent](core.md)
201
+
202
+ Source: [`packages/interaction/commands/src/index.ts`](../../packages/interaction/commands/src/index.ts)
203
+
204
+ <a id="commands-events"></a>
205
+
206
+ ### `commands/*` events
207
+
208
+ <a id="commandschange--emit"></a>
209
+
210
+ #### `commands/change` - emit
211
+
212
+ A command was registered or unregistered. This is an unfiltered registry notification because a global or scoped change may affect any UI view. Observer failures are contained and cannot veto the registry mutation.
213
+
214
+ ```ts cordis-catalog
215
+ /**
216
+ * A command was registered or unregistered. This is an unfiltered registry
217
+ * notification because a global or scoped change may affect any UI view.
218
+ * Observer failures are contained and cannot veto the registry mutation.
219
+ * @mode emit
220
+ */
221
+ 'commands/change'(): void
222
+ ```
223
+
224
+ Source: [`packages/interaction/commands/src/types.ts`](../../packages/interaction/commands/src/types.ts)
225
+ <!-- END GENERATED cordis-surface -->
@@ -0,0 +1,286 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/compaction.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Compaction
4
+
5
+ English | [中文](compaction.zh.md)
6
+
7
+ The compaction seam - a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) split like bash: Service Definition ([dsh-compaction](../../packages/compaction/compaction), `ctx.compaction`), Service Provider (a backend such as [dsh-compaction-basic](../../packages/compaction/compaction-basic)), and human Consumer ([dsh-command-compact](../../packages/compaction/command-compact)). Compaction is **one optional capability**, not part of the agent-loop spine - so its vocabulary lives here, not in [core.md](core.md). A tokenizer- or template-based backend is a sibling package implementing the same interface. Unlike bash, the interface necessarily depends on `dsh-session` and `dsh-llm`: its verbs act on an agent-owned `Session`, and its durable summary event uses the `ContentBlock` vocabulary (see the [compaction capability-seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)).
8
+
9
+ Source: [`packages/compaction/compaction/src/types.ts`](../../packages/compaction/compaction/src/types.ts)
10
+
11
+ ## The `compaction/*` session events
12
+
13
+ Compaction extends [`SessionEventMap`](session.md) with three event types via declaration merging. All three are **log-only** - they record the lock, summary, selected range, shadowed event seqs, token count, and model call without joining the surface. `SurfaceEventType` is deliberately NOT extended (only message-producing events reach the model), so the summary itself rides on a separate `user/message` with `surfaceOp: { op: 'replace', startSeq, endSeq }` - the only surface mutation performed by summary compaction. The [Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) owns the rationale for reusing `user/message`.
14
+
15
+ | Event | Payload | Role |
16
+ |---|---|---|
17
+ | `compaction/start` | `{ turn }` | acquires the log-recorded lock; a number identifies the open automatic turn, while `null` identifies a standalone manual attempt |
18
+ | `compaction/summary` | `{ summary, rawOutput?, llmStreamCall?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | the safe summary projection, optional complete provider output and usage, an `llmStreamCall: true` marker when producing the result consumed exactly one call through this context's `ctx.llm.stream()` (which requires complete `rawOutput`), the shadowed surface-boundary pair (`start`/`end` seqs - a position span, not a numeric interval), the shadowed seqs in surface order, the estimated token count, and the summarize call's envelope (`provider`, `model`, plus its generation cap when one applied) - logged so the one-shot request is reconstructable from log + code (the reconstructability Agent Note); unmarked `rawOutput` does not identify the call path |
19
+ | `compaction/end` | `{ turn, error? }` | releases the lock with the same numeric-or-null owner (`error` records an unsuccessful attempt) |
20
+
21
+ The lock brackets the **whole** operation: `compaction/start` is appended first, then summarization, the `compaction/summary` record, and the `user/message` replacement all land, and only then `compaction/end`. Releasing the lock last turns a crash mid-operation into a detectable orphaned lock (a `compaction/start` with no matching `compaction/end`) rather than a `compaction/end` that falsely claims compaction finished.
22
+
23
+ The markers are lock time points, not an exclusive container. An unrelated idle injection can appear between a standalone manual start and end while summarization is pending. The manual path revalidates only its selected positional span, so that injected context survives after the replacement checkpoint. A live unmatched start blocks every entry point; an unmatched start before a newer `session/end-seed` is stale evidence from a prior lifecycle and is ignored.
24
+
25
+ These variants are merged inside a `declare module '@deepseek-ai/dsh-session/types'` block, so - unlike the top-level types on the other subsystem pages - they are not pasted as a drift-checked ` ```ts type-equiv ` block (the `verify-type-equiv` extractor matches only top-level declarations by name). The payload table above is the catalog entry; follow the source link for the authoritative fields.
26
+
27
+ <a id="image-offload"></a>
28
+ ## Image offload
29
+
30
+ `compaction-image-offload` owns the `image/offload` declaration and its pure message projection. Each target identifies a current input node and exact depth-first image occurrences. The event preserves node and message identities and carries no `surfaceOp`. The [package README](../../packages/compaction/compaction-image-offload/README.md) owns recovery policy, registration, and detached replay.
31
+
32
+ ```ts type-equiv
33
+ /** Exact input-image occurrences selected by one durable offload decision. */
34
+ interface ImageOffloadTarget {
35
+ /** Current message-producing event containing these occurrences. */
36
+ seq: SessionSeq
37
+ /** Zero-based depth-first image indexes within the immutable message. */
38
+ imageIndexes: number[]
39
+ }
40
+ ```
41
+
42
+ ## `CompactionResult`
43
+
44
+ What a successful compaction returns to its caller: the bookkeeping-event seqs, safe summary projection, shadowed range and seqs, and estimated token count.
45
+
46
+ ```ts type-equiv
47
+ /** Result of a successful compaction operation. */
48
+ interface CompactionResult {
49
+ /** Stable identity shared by this compaction's complete durable lifecycle. */
50
+ compactionId: CompactionId
51
+ /** Human command that initiated this compaction, when it was manual. */
52
+ sourceCommandId?: CommandId
53
+ /** The seq of the appended `compaction/start` event. */
54
+ startSeq: SessionSeq
55
+ /** The seq of the appended `compaction/summary` event. */
56
+ summarySeq: SessionSeq
57
+ /** The seq of the appended `compaction/end` event. */
58
+ endSeq: SessionSeq
59
+ /** The summary content blocks produced by the backend. */
60
+ summary: ContentBlock[]
61
+ /**
62
+ * The surface-boundary pair that was shadowed: the seqs of the first
63
+ * (`start`) and last (`end`) surface nodes of the replaced range. A
64
+ * surface-POSITION span, not a numeric seq interval - after a prior replace
65
+ * lands a fresh high-seq summary node at an older range's position, `start`
66
+ * can be GREATER than `end`. {@link CompactionResult.shadowedSeqs} is the
67
+ * authoritative set of shadowed nodes, in surface order.
68
+ */
69
+ shadowedRange: { start: SessionSeq; end: SessionSeq }
70
+ /** The seqs of all shadowed surface nodes, in surface order. */
71
+ shadowedSeqs: SessionSeq[]
72
+ /** Estimated token count of the shadowed content. */
73
+ shadowedTokenCount: number
74
+ }
75
+ ```
76
+
77
+ ## The service
78
+
79
+ Automatic callers state why policy is running; implementations may treat confirmed overflow more aggressively than ordinary pressure.
80
+
81
+ ```ts type-equiv
82
+ /** Why automatic policy is asking a backend to consider compaction. */
83
+ type CompactionTrigger = 'pressure' | 'context-overflow'
84
+ ```
85
+
86
+ `CompactionEngine` exposes `compactIfNeeded(agent, trigger, signal)` for automatic `pressure` or `context-overflow` policy, `compactNow(agent, signal)` for one useful idle-session reduction even below pressure, and `compactRegion(...)` for an explicit inclusive surface range. `compactNow()` runs as agent maintenance between turns, returns `null` without writing when no useful range exists, records a standalone `turn: null` bracket before summarization, and flushes a closed attempt before later queued prompts may derive from the new surface. Every backend creates its replacement `user/message` source with `compactCheckpointSource(compactionId, sourceCommandId?)`; client and wire consumers import that constructor, `CompactionCheckpointSource`, and `isCompactCheckpointSource()` from the cordis-free `@deepseek-ai/dsh-compaction/checkpoint` subpath, while the package root re-exports them for host consumers. The required transaction identity correlates the replacement checkpoint, while the predicate keeps recognition independent of any one backend. Implementations must forward the supplied signal to summarization. The seam owns no pricing API: the singleton [`ctx.tokenMeter`](token-meter.md) directly owns estimation and replay, while `dsh-compaction-basic` owns retention, event sequencing, routed summarization calls, and their configuration.
87
+
88
+ Expected manual failures use `ManualCompactionErrorCode`:
89
+
90
+ ```ts type-equiv
91
+ /** Expected failure classes for an explicit idle-session compaction request. */
92
+ type ManualCompactionErrorCode =
93
+ | 'busy'
94
+ | 'cancelled'
95
+ | 'changed'
96
+ | 'summary'
97
+ | 'commit'
98
+ | 'persistence'
99
+ ```
100
+
101
+ `changed` and `summary` close and persist the failed attempt without a summary replacement; image omissions recorded during recovery remain effective. `commit` may follow partial mutation; `persistence` means the in-memory bracket closed but its flush failed. Cancellation remains separate and throws the exact abort reason after required cleanup.
102
+
103
+ Pressure compaction runs at the `agent/pre-step` waterfall before request derivation. Once pressure or canonical overflow qualifies, compaction-basic invokes optional [`ctx.toolResultPruner`](../../packages/compaction/compaction-tool-result-pruner/README.md) before range selection, remeasures through `ctx.tokenMeter`, and can advance the surface without a summary. Failed-request recovery runs through `agent/request-error` after the failed step closes and returns a retry action only when the surface replacement generation advances, even if later summary work throws after pruning; cancellation still wins. Region boundaries preserve tool-call/result pairing but not whole turns, allowing early closed steps of one oversized turn to compact. `dsh-compaction-basic` owns thresholds, retained-tail policy, overflow caps, and failure handling.
104
+
105
+ The Service Definition exports `toolPairingBalancedBefore(session, seq)` and `toolPairingBalancedAfter(session, seq)` for the tool-call/result pairing checks before and after a seq. Both validate current surface membership and reject missing seqs and orphan results; the [package contract](../../packages/compaction/compaction/README.md#tool-pairing-boundaries) defines their cache behavior.
106
+
107
+ ## Tool-result pruning outcomes
108
+
109
+ The optional tool-result pruning service reports each durable content replacement and the aggregate Unicode-code-point reduction. Its public result types live in [`compaction-tool-result-pruner/src/types.ts`](../../packages/compaction/compaction-tool-result-pruner/src/types.ts).
110
+
111
+ ```ts type-equiv
112
+ /** Cited source event and size accounting for one landed surface replacement. */
113
+ interface PrunedEntry {
114
+ /** Full-fidelity tool-result event shadowed by the replacement. */
115
+ readonly originalSeq: SessionSeq
116
+ /** Newly appended pruned tool-result event. */
117
+ readonly replacementSeq: SessionSeq
118
+ /** Tool call shared by the original and replacement. */
119
+ readonly callId: ToolCallId
120
+ /** Original text size in Unicode code points. */
121
+ readonly charsBefore: number
122
+ /** Replacement text size in Unicode code points. */
123
+ readonly charsAfter: number
124
+ }
125
+ ```
126
+
127
+ ```ts type-equiv
128
+ /** Aggregate outcome of one stable-surface pruning pass. */
129
+ interface PruneResult {
130
+ /** Replacements in the snapshotted surface order. */
131
+ readonly pruned: readonly PrunedEntry[]
132
+ /** Total Unicode code points removed across replacements. */
133
+ readonly charsRemoved: number
134
+ }
135
+ ```
136
+
137
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
138
+
139
+ <a id="cordis-surface"></a>
140
+
141
+ ## Cordis API
142
+
143
+ 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).
144
+
145
+ <a id="ctxcompaction--compactionengine-abstract-seam"></a>
146
+
147
+ ### `ctx.compaction` - `CompactionEngine` (abstract seam)
148
+
149
+ Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses compactCheckpointSource with the transaction identity so consumers recognize and correlate it independently of the backend. Load one implementation per context as `ctx.compaction`.
150
+
151
+ ```ts cordis-catalog
152
+ /**
153
+ * Consider automatic compaction for one explicit trigger. Pressure policy
154
+ * uses the latest durable routed request, while context-overflow policy may
155
+ * force a useful balanced reduction even below the normal threshold. Return
156
+ * `null` when no safe range can be compacted. A single oversized retained
157
+ * unit or request envelope cannot be repaired through surface compaction.
158
+ *
159
+ * @param agent - agent context owning the session surface and routing options.
160
+ * @param trigger - normal pressure or provider-confirmed context overflow.
161
+ * @param signal - cancellation signal; model-backed implementations must forward it.
162
+ * @returns the compaction result, or `null` if no compaction was needed.
163
+ */
164
+ abstract compactIfNeeded( agent: CompactionAgentContext, trigger: CompactionTrigger, signal: AbortSignal, ): Promise<CompactionResult | null>
165
+
166
+ /**
167
+ * Explicitly compact useful history even below automatic pressure thresholds.
168
+ * Implementations synchronously start an idle task before any asynchronous
169
+ * work, select a useful range without writing on a no-op, then
170
+ * append a standalone `compaction/start` before summarization. That durable
171
+ * marker is the compaction lock until one `compaction/end` attempt. Later waking
172
+ * prompts remain accepted in FIFO order and start only after the optional
173
+ * durability checkpoint and idle-task settlement. Context injected while the
174
+ * summary runs may sit between the marker pair; only the selected span must
175
+ * remain stable.
176
+ *
177
+ * @param agent - idle agent whose durable history should be compacted.
178
+ * @param signal - cancellation scoped to this compaction request.
179
+ * @param sourceCommandId - initiating command identity for a manual compaction.
180
+ * @returns the compaction result, or `null` when no safe useful range exists.
181
+ * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,
182
+ * changed-span, summarization/shrink, commit-stage, or persistence failures;
183
+ * an aborted request preserves its exact abort reason. Failed attempts remain
184
+ * visible in the log.
185
+ */
186
+ abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, sourceCommandId?: CommandId, ): Promise<CompactionResult | null>
187
+
188
+ /**
189
+ * Forcibly compact a range of surface nodes into a single summary node.
190
+ * `start` and `end` name an inclusive span by surface position, not numeric seq
191
+ * order; replacements can make visible seqs non-monotonic. Both edges must be
192
+ * balanced so assistant tool calls remain paired with their results. A model-
193
+ * backed implementation forwards cancellation and rejects active, missing,
194
+ * reversed, or unbalanced ranges. The target session is `agent.session`.
195
+ * Its replacement user message must use {@link compactCheckpointSource} with
196
+ * the transaction's `CompactionId`.
197
+ * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
198
+ * for the edge checks.
199
+ *
200
+ * @param start - first surface seq, inclusive.
201
+ * @param end - last surface seq, inclusive.
202
+ * @param agent - context whose session is mutated and whose routing options guide summarization.
203
+ * @param signal - optional cancellation; model-backed implementations must forward it.
204
+ * @throws when compaction is active or the range is missing, reversed, or unbalanced.
205
+ * @returns the appended event seqs, summary, replaced range, and token accounting.
206
+ */
207
+ abstract compactRegion( start: SessionSeq, end: SessionSeq, agent: CompactionAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
208
+ ```
209
+
210
+ Types: [CommandId](commands.md) · [SessionSeq](session.md)
211
+
212
+ Source: [`packages/compaction/compaction/src/index.ts`](../../packages/compaction/compaction/src/index.ts)
213
+
214
+ <a id="ctxtoolresultpruner--toolresultpruner"></a>
215
+
216
+ ### `ctx.toolResultPruner` - `ToolResultPruner`
217
+
218
+ Deterministic head/middle/tail pruning for current tool-result surface nodes.
219
+
220
+ ```ts cordis-catalog
221
+ /**
222
+ * Measure text content in Unicode code points; non-text blocks cost zero.
223
+ * @param blocks - tool-result content to measure.
224
+ * @returns total Unicode code points across text blocks.
225
+ */
226
+ measureContent(blocks: readonly ContentBlock[]): number
227
+
228
+ /**
229
+ * Replace an over-budget text middle while retaining rich-block order.
230
+ * Text slicing is by Unicode code point, not UTF-16 code unit, so a retained
231
+ * boundary cannot split a surrogate pair. Grapheme clusters may still split.
232
+ * @param blocks - original tool-result content.
233
+ * @returns pruned content, or `null` when the text is within budget.
234
+ */
235
+ pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
236
+
237
+ /**
238
+ * Prune every over-budget tool result from one stable current-surface snapshot.
239
+ * Each replacement preserves the complete event data except for `content`,
240
+ * cites the shadowed node so replay can recover the replacement input, and is
241
+ * immediately preceded by a `compaction/prune` shadow-price event pricing the
242
+ * shadowed node through the injected token meter, so pure consumers can
243
+ * subtract it without per-node state.
244
+ * @param session - session whose current surface is rewritten.
245
+ * @returns landed replacements and aggregate Unicode-code-point savings.
246
+ * @throws when the session rejects a replacement; replacements committed
247
+ * earlier in the pass remain durable.
248
+ */
249
+ pruneSession(session: Session): PruneResult
250
+ ```
251
+
252
+ Types: [ContentBlock](llm-streaming.md) · [Session](session.md)
253
+
254
+ Source: [`packages/compaction/compaction-tool-result-pruner/src/index.ts`](../../packages/compaction/compaction-tool-result-pruner/src/index.ts)
255
+
256
+ <a id="compaction-events"></a>
257
+
258
+ ### `compaction/*` events
259
+
260
+ <a id="compactionsummary-error--waterfall"></a>
261
+
262
+ #### `compaction/summary-error` - waterfall
263
+
264
+ Recover a failed summary request by synchronously recording a durable change to its selected input. Return true only after making progress; the provider re-derives and re-prices the selection before retrying. Call next() when the failure cannot be recovered. Decisions survive a later summary failure or cancellation.
265
+
266
+ ```ts cordis-catalog
267
+ /**
268
+ * Recover a failed summary request by synchronously recording a durable
269
+ * change to its selected input. Return true only after making progress;
270
+ * the provider re-derives and re-prices the selection before retrying.
271
+ * Call next() when the failure cannot be recovered. Decisions survive a
272
+ * later summary failure or cancellation.
273
+ * @param payload.session - session containing the selected input.
274
+ * @param payload.sourceEventSeqs - selected message events in request order.
275
+ * @param payload.error - failure thrown by the summarizer.
276
+ * @param payload.signal - optional compaction cancellation signal.
277
+ * @param next - delegate to the next recovery listener.
278
+ * @mode waterfall
279
+ */
280
+ 'compaction/summary-error'(payload: { session: Session; sourceEventSeqs: readonly SessionSeq[]; error: unknown; signal?: AbortSignal }, next: () => boolean): boolean
281
+ ```
282
+
283
+ Types: [Session](session.md) · [SessionSeq](session.md)
284
+
285
+ Source: [`packages/compaction/compaction/src/index.ts`](../../packages/compaction/compaction/src/index.ts)
286
+ <!-- END GENERATED cordis-surface -->