@acryldev/plugin-context 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (284) hide show
  1. package/LICENSE +21 -0
  2. package/docs/README.md +160 -0
  3. package/docs/delivery/local-live.md +113 -0
  4. package/docs/delivery/marketplace.md +16 -0
  5. package/docs/docs.json +2836 -0
  6. package/docs/extending/agent-preset.md +37 -0
  7. package/docs/extending/chat-command.md +28 -0
  8. package/docs/extending/client-slot.md +135 -0
  9. package/docs/extending/config-schema.md +7 -0
  10. package/docs/extending/cordis-core.md +63 -0
  11. package/docs/extending/desktop-app.md +53 -0
  12. package/docs/extending/desktop-main.md +25 -0
  13. package/docs/extending/event-hook.md +14 -0
  14. package/docs/extending/host-route.md +33 -0
  15. package/docs/extending/llm-adapter.md +38 -0
  16. package/docs/extending/packaging.md +53 -0
  17. package/docs/extending/prompt-contribution.md +9 -0
  18. package/docs/extending/service.md +13 -0
  19. package/docs/extending/skill-provider.md +9 -0
  20. package/docs/extending/state-and-persistence.md +71 -0
  21. package/docs/extending/three-role-capability.md +33 -0
  22. package/docs/extending/tool-plugin.md +24 -0
  23. package/docs/extending/tui-command.md +8 -0
  24. package/docs/extending/tui-components.md +61 -0
  25. package/docs/extending/ui-branding.md +43 -0
  26. package/docs/extending/ui-components.md +56 -0
  27. package/docs/extending/ui-customization.md +41 -0
  28. package/docs/extending/ui-library.md +66 -0
  29. package/docs/extending/ui-theme.md +55 -0
  30. package/docs/extending/workspace-tab.md +50 -0
  31. package/docs/maps/events.md +108 -0
  32. package/docs/maps/mount-points.md +154 -0
  33. package/docs/maps/slot-contracts.md +3376 -0
  34. package/docs/maps/taxonomy.md +306 -0
  35. package/docs/maps/theme-tokens.md +115 -0
  36. package/docs/maps/ui-components.md +26 -0
  37. package/docs/reference/cookbook/adding-a-package.md +174 -0
  38. package/docs/reference/cookbook/adding-a-remote-api.md +199 -0
  39. package/docs/reference/cookbook/adding-a-settings-card.md +74 -0
  40. package/docs/reference/cookbook/adding-a-tool.md +103 -0
  41. package/docs/reference/cookbook/adding-an-llm-adapter.md +45 -0
  42. package/docs/reference/cookbook/extension-cookbook.md +134 -0
  43. package/docs/reference/cordis-api/context.md +366 -0
  44. package/docs/reference/cordis-api/events.md +209 -0
  45. package/docs/reference/cordis-api/fiber.md +377 -0
  46. package/docs/reference/cordis-api/inherited.md +40 -0
  47. package/docs/reference/cordis-api/registry.md +154 -0
  48. package/docs/reference/cordis-api/service.md +104 -0
  49. package/docs/reference/cordis-guides/cordis-usage-cheatsheet.md +167 -0
  50. package/docs/reference/cordis-guides/cordis_system_guide_for_coding_agents.md +4666 -0
  51. package/docs/reference/cordis-guides/development-canvas-plugin.md +109 -0
  52. package/docs/reference/cordis-guides/hello-world-plugin-guide.md +517 -0
  53. package/docs/reference/harness/agent-lifecycle.md +93 -0
  54. package/docs/reference/harness/architecture.md +168 -0
  55. package/docs/reference/harness/capability-seams.md +675 -0
  56. package/docs/reference/harness/config-catalog.md +4523 -0
  57. package/docs/reference/harness/cordis-primer.md +47 -0
  58. package/docs/reference/harness/defensive-patterns.md +35 -0
  59. package/docs/reference/harness/event-producer-consumer.md +111 -0
  60. package/docs/reference/harness/glossary.md +47 -0
  61. package/docs/reference/harness/tool-catalog.md +2721 -0
  62. package/docs/reference/harness/tool-execution-pipeline.md +67 -0
  63. package/docs/reference/subsystems/README.md +75 -0
  64. package/docs/reference/subsystems/agent-team.md +233 -0
  65. package/docs/reference/subsystems/approval.md +172 -0
  66. package/docs/reference/subsystems/attachment.md +363 -0
  67. package/docs/reference/subsystems/boot.md +324 -0
  68. package/docs/reference/subsystems/browser-use.md +69 -0
  69. package/docs/reference/subsystems/client-modules.md +186 -0
  70. package/docs/reference/subsystems/client-resources.md +94 -0
  71. package/docs/reference/subsystems/commands.md +225 -0
  72. package/docs/reference/subsystems/compaction.md +286 -0
  73. package/docs/reference/subsystems/computer-use.md +58 -0
  74. package/docs/reference/subsystems/conversation.md +287 -0
  75. package/docs/reference/subsystems/core.md +1107 -0
  76. package/docs/reference/subsystems/credentials.md +497 -0
  77. package/docs/reference/subsystems/deliverables.md +180 -0
  78. package/docs/reference/subsystems/extensions.md +386 -0
  79. package/docs/reference/subsystems/feedback.md +402 -0
  80. package/docs/reference/subsystems/filesystem.md +532 -0
  81. package/docs/reference/subsystems/goal.md +315 -0
  82. package/docs/reference/subsystems/invariants.md +90 -0
  83. package/docs/reference/subsystems/jobs.md +501 -0
  84. package/docs/reference/subsystems/llm-streaming.md +1131 -0
  85. package/docs/reference/subsystems/lsp.md +204 -0
  86. package/docs/reference/subsystems/mcp.md +141 -0
  87. package/docs/reference/subsystems/office-to-pdf.md +89 -0
  88. package/docs/reference/subsystems/otel.md +46 -0
  89. package/docs/reference/subsystems/permission-presets.md +169 -0
  90. package/docs/reference/subsystems/persistence.md +418 -0
  91. package/docs/reference/subsystems/plan.md +89 -0
  92. package/docs/reference/subsystems/product-telemetry.md +81 -0
  93. package/docs/reference/subsystems/ptc-runtime.md +234 -0
  94. package/docs/reference/subsystems/sandbox.md +223 -0
  95. package/docs/reference/subsystems/schedule.md +545 -0
  96. package/docs/reference/subsystems/scope.md +61 -0
  97. package/docs/reference/subsystems/session-projection.md +358 -0
  98. package/docs/reference/subsystems/session-query.md +511 -0
  99. package/docs/reference/subsystems/session-reference.md +226 -0
  100. package/docs/reference/subsystems/session-telemetry.md +214 -0
  101. package/docs/reference/subsystems/session-title.md +206 -0
  102. package/docs/reference/subsystems/session.md +1300 -0
  103. package/docs/reference/subsystems/settings.md +157 -0
  104. package/docs/reference/subsystems/shell.md +316 -0
  105. package/docs/reference/subsystems/sidebar-right.md +160 -0
  106. package/docs/reference/subsystems/skills.md +354 -0
  107. package/docs/reference/subsystems/slots.md +201 -0
  108. package/docs/reference/subsystems/spill.md +126 -0
  109. package/docs/reference/subsystems/ssh.md +137 -0
  110. package/docs/reference/subsystems/storage.md +262 -0
  111. package/docs/reference/subsystems/subagent.md +762 -0
  112. package/docs/reference/subsystems/subprocess.md +323 -0
  113. package/docs/reference/subsystems/system-prompt.md +226 -0
  114. package/docs/reference/subsystems/terminal.md +186 -0
  115. package/docs/reference/subsystems/todo.md +34 -0
  116. package/docs/reference/subsystems/token-meter.md +108 -0
  117. package/docs/reference/subsystems/tools.md +749 -0
  118. package/docs/reference/subsystems/typert.md +489 -0
  119. package/docs/reference/subsystems/user-questions.md +309 -0
  120. package/docs/reference/subsystems/voice-input.md +166 -0
  121. package/docs/reference/subsystems/web-client.md +102 -0
  122. package/docs/reference/subsystems/web-server.md +228 -0
  123. package/docs/reference/subsystems/web.md +208 -0
  124. package/docs/reference/subsystems/webhook.md +72 -0
  125. package/docs/reference/subsystems/workflow.md +280 -0
  126. package/docs/reference/subsystems/workspace.md +661 -0
  127. package/docs/start-here/blueprints.md +33 -0
  128. package/docs/start-here/this-runtime.md +84 -0
  129. package/docs/start-here/troubleshooting.md +29 -0
  130. package/docs/start-here/trust-and-safety.md +39 -0
  131. package/docs/start-here/verify-before-done.md +46 -0
  132. package/example-plugins/README.md +45 -0
  133. package/example-plugins/packages/agent-preset-reviewer/agent.cordis.yml +18 -0
  134. package/example-plugins/packages/agent-preset-reviewer/preset.yml +3 -0
  135. package/example-plugins/packages/capability-swap-consumer/cordis.patch.yml +3 -0
  136. package/example-plugins/packages/capability-swap-consumer/index.js +14 -0
  137. package/example-plugins/packages/capability-swap-consumer/package.json +25 -0
  138. package/example-plugins/packages/capability-swap-provider-loud/cordis.patch.yml +3 -0
  139. package/example-plugins/packages/capability-swap-provider-loud/index.js +20 -0
  140. package/example-plugins/packages/capability-swap-provider-loud/package.json +25 -0
  141. package/example-plugins/packages/capability-swap-provider-quiet/cordis.patch.yml +3 -0
  142. package/example-plugins/packages/capability-swap-provider-quiet/index.js +20 -0
  143. package/example-plugins/packages/capability-swap-provider-quiet/package.json +25 -0
  144. package/example-plugins/packages/chat-command-basic/cordis.patch.yml +3 -0
  145. package/example-plugins/packages/chat-command-basic/index.js +26 -0
  146. package/example-plugins/packages/chat-command-basic/package.json +25 -0
  147. package/example-plugins/packages/client-chat-message-action/client.js +46 -0
  148. package/example-plugins/packages/client-chat-message-action/cordis.patch.yml +3 -0
  149. package/example-plugins/packages/client-chat-message-action/index.js +9 -0
  150. package/example-plugins/packages/client-chat-message-action/package.json +31 -0
  151. package/example-plugins/packages/client-slot-header-action/client.js +57 -0
  152. package/example-plugins/packages/client-slot-header-action/cordis.patch.yml +3 -0
  153. package/example-plugins/packages/client-slot-header-action/index.js +13 -0
  154. package/example-plugins/packages/client-slot-header-action/package.json +31 -0
  155. package/example-plugins/packages/client-slot-sidebar-tab/client.js +57 -0
  156. package/example-plugins/packages/client-slot-sidebar-tab/cordis.patch.yml +3 -0
  157. package/example-plugins/packages/client-slot-sidebar-tab/index.js +9 -0
  158. package/example-plugins/packages/client-slot-sidebar-tab/package.json +32 -0
  159. package/example-plugins/packages/client-theme-override/client.js +52 -0
  160. package/example-plugins/packages/client-theme-override/cordis.patch.yml +3 -0
  161. package/example-plugins/packages/client-theme-override/index.js +9 -0
  162. package/example-plugins/packages/client-theme-override/package.json +30 -0
  163. package/example-plugins/packages/client-tool-view/client.js +47 -0
  164. package/example-plugins/packages/client-tool-view/cordis.patch.yml +3 -0
  165. package/example-plugins/packages/client-tool-view/index.js +24 -0
  166. package/example-plugins/packages/client-tool-view/package.json +34 -0
  167. package/example-plugins/packages/client-ui-components/client.js +77 -0
  168. package/example-plugins/packages/client-ui-components/cordis.patch.yml +3 -0
  169. package/example-plugins/packages/client-ui-components/index.js +9 -0
  170. package/example-plugins/packages/client-ui-components/package.json +31 -0
  171. package/example-plugins/packages/client-ui-library/client.js +715 -0
  172. package/example-plugins/packages/client-ui-library/cordis.patch.yml +3 -0
  173. package/example-plugins/packages/client-ui-library/index.js +9 -0
  174. package/example-plugins/packages/client-ui-library/package.json +37 -0
  175. package/example-plugins/packages/client-workspace-tab/client.js +72 -0
  176. package/example-plugins/packages/client-workspace-tab/cordis.patch.yml +3 -0
  177. package/example-plugins/packages/client-workspace-tab/index.js +9 -0
  178. package/example-plugins/packages/client-workspace-tab/package.json +30 -0
  179. package/example-plugins/packages/config-schema-basic/cordis.patch.yml +3 -0
  180. package/example-plugins/packages/config-schema-basic/index.js +19 -0
  181. package/example-plugins/packages/config-schema-basic/package.json +25 -0
  182. package/example-plugins/packages/desktop-main-profile-info/cordis.patch.yml +3 -0
  183. package/example-plugins/packages/desktop-main-profile-info/index.js +22 -0
  184. package/example-plugins/packages/desktop-main-profile-info/package.json +25 -0
  185. package/example-plugins/packages/event-hook-basic/cordis.patch.yml +3 -0
  186. package/example-plugins/packages/event-hook-basic/index.js +17 -0
  187. package/example-plugins/packages/event-hook-basic/package.json +22 -0
  188. package/example-plugins/packages/generated-capability-template/cordis.patch.yml +3 -0
  189. package/example-plugins/packages/generated-capability-template/index.js +16 -0
  190. package/example-plugins/packages/generated-capability-template/package.json +42 -0
  191. package/example-plugins/packages/host-route-basic/cordis.patch.yml +3 -0
  192. package/example-plugins/packages/host-route-basic/index.js +20 -0
  193. package/example-plugins/packages/host-route-basic/package.json +29 -0
  194. package/example-plugins/packages/lifecycle-function-basic/cordis.patch.yml +3 -0
  195. package/example-plugins/packages/lifecycle-function-basic/index.js +12 -0
  196. package/example-plugins/packages/lifecycle-function-basic/package.json +15 -0
  197. package/example-plugins/packages/lifecycle-function-hot-shim/cordis.patch.yml +3 -0
  198. package/example-plugins/packages/lifecycle-function-hot-shim/impl.js +5 -0
  199. package/example-plugins/packages/lifecycle-function-hot-shim/index.js +18 -0
  200. package/example-plugins/packages/lifecycle-function-hot-shim/package.json +23 -0
  201. package/example-plugins/packages/lifecycle-hooks-observer/cordis.patch.yml +3 -0
  202. package/example-plugins/packages/lifecycle-hooks-observer/index.js +23 -0
  203. package/example-plugins/packages/lifecycle-hooks-observer/package.json +22 -0
  204. package/example-plugins/packages/llm-adapter-echo/cordis.patch.yml +3 -0
  205. package/example-plugins/packages/llm-adapter-echo/index.js +42 -0
  206. package/example-plugins/packages/llm-adapter-echo/package.json +25 -0
  207. package/example-plugins/packages/prompt-assemble-hook/cordis.patch.yml +3 -0
  208. package/example-plugins/packages/prompt-assemble-hook/index.js +22 -0
  209. package/example-plugins/packages/prompt-assemble-hook/package.json +22 -0
  210. package/example-plugins/packages/prompt-contribution-basic/cordis.patch.yml +3 -0
  211. package/example-plugins/packages/prompt-contribution-basic/index.js +18 -0
  212. package/example-plugins/packages/prompt-contribution-basic/package.json +22 -0
  213. package/example-plugins/packages/service-consumer-greeter/cordis.patch.yml +3 -0
  214. package/example-plugins/packages/service-consumer-greeter/index.js +14 -0
  215. package/example-plugins/packages/service-consumer-greeter/package.json +22 -0
  216. package/example-plugins/packages/service-provider-greeter/cordis.patch.yml +3 -0
  217. package/example-plugins/packages/service-provider-greeter/index.js +22 -0
  218. package/example-plugins/packages/service-provider-greeter/package.json +25 -0
  219. package/example-plugins/packages/settings-section-basic/cordis.patch.yml +3 -0
  220. package/example-plugins/packages/settings-section-basic/index.js +34 -0
  221. package/example-plugins/packages/settings-section-basic/package.json +26 -0
  222. package/example-plugins/packages/skill-provider-basic/cordis.patch.yml +3 -0
  223. package/example-plugins/packages/skill-provider-basic/index.js +31 -0
  224. package/example-plugins/packages/skill-provider-basic/package.json +22 -0
  225. package/example-plugins/packages/state-host-store/client.js +57 -0
  226. package/example-plugins/packages/state-host-store/cordis.patch.yml +3 -0
  227. package/example-plugins/packages/state-host-store/index.js +90 -0
  228. package/example-plugins/packages/state-host-store/package.json +31 -0
  229. package/example-plugins/packages/state-workspace-file/cordis.patch.yml +3 -0
  230. package/example-plugins/packages/state-workspace-file/index.js +52 -0
  231. package/example-plugins/packages/state-workspace-file/package.json +25 -0
  232. package/example-plugins/packages/tool-basic/cordis.patch.yml +3 -0
  233. package/example-plugins/packages/tool-basic/index.js +25 -0
  234. package/example-plugins/packages/tool-basic/package.json +25 -0
  235. package/example-plugins/packages/tool-policy-hook/cordis.patch.yml +3 -0
  236. package/example-plugins/packages/tool-policy-hook/index.js +28 -0
  237. package/example-plugins/packages/tool-policy-hook/package.json +25 -0
  238. package/example-plugins/packages/tui-command-basic/cordis.patch.yml +3 -0
  239. package/example-plugins/packages/tui-command-basic/index.js +24 -0
  240. package/example-plugins/packages/tui-command-basic/package.json +22 -0
  241. package/example-plugins/packages/tui-overlay-themed/cordis.patch.yml +3 -0
  242. package/example-plugins/packages/tui-overlay-themed/index.js +65 -0
  243. package/example-plugins/packages/tui-overlay-themed/package.json +25 -0
  244. package/example-plugins/packages/tui-ui-library/cordis.patch.yml +3 -0
  245. package/example-plugins/packages/tui-ui-library/index.js +73 -0
  246. package/example-plugins/packages/tui-ui-library/package.json +29 -0
  247. package/example-plugins/packages/web-page-branding/cordis.patch.yml +3 -0
  248. package/example-plugins/packages/web-page-branding/index.js +31 -0
  249. package/example-plugins/packages/web-page-branding/package.json +22 -0
  250. package/example-plugins/scenarios.json +11 -0
  251. package/index.js +384 -0
  252. package/lib/blend-apply.js +107 -0
  253. package/lib/blend-capture.js +249 -0
  254. package/lib/blend-ledger.js +76 -0
  255. package/lib/contract.js +5 -0
  256. package/lib/install.js +516 -0
  257. package/lib/lookup.js +67 -0
  258. package/lib/manifest.js +56 -0
  259. package/lib/pack-root.js +22 -0
  260. package/lib/provenance.js +110 -0
  261. package/lib/publish.js +64 -0
  262. package/lib/reconcile.js +83 -0
  263. package/lib/router.js +55 -0
  264. package/lib/scopes.js +82 -0
  265. package/lib/skills.js +54 -0
  266. package/lib/stage.js +157 -0
  267. package/lib/verify.js +77 -0
  268. package/package.json +56 -3
  269. package/scripts/lib/indexes.mjs +45 -0
  270. package/scripts/lib/manifest.mjs +127 -0
  271. package/scripts/lib/maps.mjs +482 -0
  272. package/skills/acryl-add-provider-or-capability/SKILL.md +12 -0
  273. package/skills/acryl-add-ui/SKILL.md +18 -0
  274. package/skills/acryl-build-plugin/SKILL.md +21 -0
  275. package/skills/acryl-change-plugin/SKILL.md +16 -0
  276. package/skills/acryl-desktop-shell/SKILL.md +12 -0
  277. package/skills/acryl-diagnose-plugin/SKILL.md +10 -0
  278. package/skills/acryl-fix-plugin/SKILL.md +12 -0
  279. package/skills/acryl-improve-ui/SKILL.md +10 -0
  280. package/skills/acryl-remove-plugin/SKILL.md +11 -0
  281. package/skills/acryl-restyle-ui/SKILL.md +14 -0
  282. package/skills/acryl-share-plugin/SKILL.md +23 -0
  283. package/skills/acryl-tui-ui/SKILL.md +12 -0
  284. package/README.md +0 -3
@@ -0,0 +1,661 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/workspace.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Workspaces
4
+
5
+ English | [中文](workspace.zh.md)
6
+
7
+ A workspace is the persistent record of a directory the user works in: a stable id over a canonical path, a display title, and the ordered account of sessions that belong to it. The subsystem is one package ([dsh-workspace](../../packages/workspace/workspace), `ctx.workspaceRegistry`) - an optional host-side capability, not part of the agent-loop spine, and invisible to models (no tools, no prompt text, no session events). It stores its records through the [storage domain form](storage.md) and validates session membership against [`SessionHeader.cwd`](persistence.md#sessionheader--metadata-beside-the-log), so `storageDomain` and `sessionPersistence` are mandatory startup dependencies: an unavailable persistence peer leaves the plugin pending rather than being mistaken for an empty history. Design record: [domain KV storage Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md); bootstrap and GUI ordering: [Workspace UI product-flow Agent Note](../../.agents/notes/archived/feature/2026-07-25-workspace-ui-product-flow.md).
8
+
9
+ Source: [`packages/workspace/workspace/src/types.ts`](../../packages/workspace/workspace/src/types.ts)
10
+
11
+ ## Identity
12
+
13
+ ```ts type-equiv
14
+ /**
15
+ * Identifies one workspace record. A generated uuid, never the path: path
16
+ * normalization rewrites paths, and a reference anchor must stay stable.
17
+ */
18
+ type WorkspaceId = Branded<'WorkspaceId'>
19
+ ```
20
+
21
+ `WorkspaceId` is a [branded id](core.md#branded-ids). Path identity is separate: `realpathNormalize` (`fs.realpath`; trailing slashes, `..`, and symlinks resolved) is the one uniqueness canon - workspace paths are stored canonicalized, uniqueness is string equality of canonical paths (a symlink to an owned directory collides), and attach-time session cwd checks go through the same canon.
22
+
23
+ ## The workspace entity
24
+
25
+ Consumers see only the `Workspace` interface; the implementation stays package-private.
26
+
27
+ ```ts type-equiv
28
+ /**
29
+ * One workspace: a stable id over an existing directory, a display title, and
30
+ * an ordered candidate account of sessions. Membership requires both an id in
31
+ * that account and a session header whose canonical cwd equals the workspace
32
+ * path. Consumers only see this interface; the implementation stays private.
33
+ */
34
+ interface Workspace {
35
+ /** Stable record id (generated uuid). */
36
+ readonly id: WorkspaceId
37
+
38
+ /**
39
+ * Canonical directory path: the `fs.realpath` of the path given at create
40
+ * time (trailing slashes, `..`, and symlinks all resolved). Never rewritten
41
+ * afterwards, even when the directory disappears (see {@link status}).
42
+ */
43
+ readonly path: string
44
+
45
+ /** Display title. Defaults to the final path segment, or a filesystem root's own spelling; duplicates are allowed. */
46
+ readonly title: string
47
+
48
+ /** ISO-8601 creation instant, stamped at create and never rewritten. */
49
+ readonly createdAt: string
50
+
51
+ /** ISO-8601 instant of the last durable mutation (create counts as one). */
52
+ readonly updatedAt: string
53
+
54
+ /**
55
+ * Header-validated sessions in manually owned order: a new session is
56
+ * prepended at attach, explicit reordering goes through
57
+ * `insertSessionBefore`, and activity never reorders. The durable candidate
58
+ * account is filtered synchronously: missing headers, invalid cwd values,
59
+ * and canonical cwd mismatches are never returned. A subsequent workspace
60
+ * mutation prunes those filtered candidates durably.
61
+ */
62
+ readonly sessionIds: readonly SessionId[]
63
+
64
+ /**
65
+ * Replace the display title durably.
66
+ * @param title - New title; any string, duplicates across workspaces allowed.
67
+ * @returns resolution after durability.
68
+ */
69
+ setTitle(title: string): Promise<void>
70
+
71
+ /**
72
+ * Prepend a session to this workspace's candidate account. An already
73
+ * accounted id resolves without writing, aside from the durable
74
+ * filtered-candidate prune every accepted mutation performs. A new id's
75
+ * live or persisted
76
+ * header cwd must resolve to an existing directory equal to {@link path};
77
+ * unknown ids, missing or invalid cwd values, and mismatches reject without
78
+ * writing.
79
+ * @param sessionId - The session to record.
80
+ * @returns resolution after durability.
81
+ */
82
+ attachSession(sessionId: SessionId): Promise<void>
83
+
84
+ /**
85
+ * Move an accounted session within the manual order, DOM-insertBefore-like:
86
+ * with an anchor the session lands before it, without one it appends to the
87
+ * end. Only the moved id changes position. A session or anchor absent from
88
+ * the account rejects without writing; a move to the current position
89
+ * resolves without writing, aside from the durable filtered-candidate
90
+ * prune every accepted mutation performs; decided on the domain write
91
+ * chain.
92
+ * @param sessionId - The accounted session to move.
93
+ * @param beforeSessionId - Accounted anchor to insert before; omitted appends.
94
+ * @returns resolution after durability.
95
+ */
96
+ insertSessionBefore(sessionId: SessionId, beforeSessionId?: SessionId): Promise<void>
97
+
98
+ /**
99
+ * Remove a session from this workspace's account. Idempotent: an id not on
100
+ * the account resolves without writing, aside from the durable
101
+ * filtered-candidate prune every accepted mutation performs; decided on
102
+ * the domain write chain like attach. Never touches the session's own stored log.
103
+ * @param sessionId - The session to remove.
104
+ * @returns resolution after durability.
105
+ */
106
+ detachSession(sessionId: SessionId): Promise<void>
107
+
108
+ /**
109
+ * Live directory check, uncached: whether {@link path} currently exists and
110
+ * is a directory. A missing directory never mutates the record - the
111
+ * directory may only be temporarily moved.
112
+ * @returns `'ok'` when the directory exists, `'missing-dir'` otherwise.
113
+ */
114
+ status(): Promise<'ok' | 'missing-dir'>
115
+ }
116
+ ```
117
+
118
+ Ownership truth is the record's ordered `sessionIds`, never derived from session cwd - but membership requires both: an id on the account and a header whose canonical cwd equals the workspace path, so one session structurally belongs to at most one workspace. Failed writes reject (`insertSessionBefore` account errors as `WorkspaceMoveInvalidError`, storage failures as plain errors); every accepted mutation stamps `updatedAt` and durably prunes candidates that no longer pass the membership check.
119
+
120
+ ## The registry: `ctx.workspaceRegistry`
121
+
122
+ `WorkspaceRegistry` ([signatures](#ctxworkspaceregistry--workspaceregistry)) owns registration and resolution. `create(path, title?)` requires a fully qualified path, canonicalizes it, rejects a nonexistent path (the original `ENOENT`) or a non-directory, returns the existing entity unchanged when the canonical path is already owned, and otherwise creates a record with `title ?? defaultWorkspaceTitle(path)` prepended to the durable registry order (different canonical paths may share a display title, and a path with no final segment uses its root spelling). `get(id)` and the ordered `list()` are synchronous cache reads; `resolveByPath(path)` applies the same fully qualified realpath canon without creating. `delete(id)` removes only the registration, order entry, and session account - the directory, user files, live sessions, and persisted logs are never touched, so those sessions become Ungrouped ([decision](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)); unknown ids return `false`. Create and delete persist a pending-mutation marker before their two writes (record + order) can diverge; startup resolves exactly the marked mutation - by deleting the marked table row, which completes an interrupted delete and rolls back an interrupted create (the registration is re-creatable, so rollback is the safe direction) - and an unmarked order/table mismatch fails loud as corruption.
123
+
124
+ Sessions get their cwd at create time from whoever creates them, not from this registry - the API gateway resolves a new session's cwd from the chosen workspace's `path` (falling back to an explicit or default cwd), creates the session so the cwd lands in its immutable [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log), then calls `attachSession`, which re-validates that stored header cwd against the workspace path. On the first successful start, the registry bootstraps history from persisted headers alone (`id`, `cwd`, `createdAt` - never event bodies), grouping sessions with a valid canonical cwd into per-directory workspaces, newest first; the initialized marker is written last so an interrupted bootstrap resumes safely. The bootstrap is one-time: cwd-less legacy sessions stay Ungrouped, and sessions created afterwards join a workspace only through `attachSession`.
125
+
126
+ ## Default Workspace initialization
127
+
128
+ The controller's `initializeDefault` takes no request: it owns the fixed `default-workspace` directory name, resolves the Documents location, and asks the registry to initialize once. The registry accepts a directory resolver, derives the initial title from the requested directory's final segment rather than the canonical one, and commits the registration with its durable identity. No language reaches the Host - browser consumers label a Workspace still carrying that automatic title through the controller's `workspaceDisplayTitle`, so only the on-screen name follows the reader's language. [First-use behavior and configuration](../../packages/api/workspace-controller/README.md#first-use-workspace) describe reuse and failure handling.
129
+
130
+ ## Session pinning
131
+
132
+ The controller's [transport types](../../packages/api/workspace-controller/src/types.ts) define `WorkspacePinSessionRequest` and `WorkspaceUnpinSessionRequest`, each carrying one `sessionId`. Both operations return `WorkspacePinValue`: the complete `pinnedSessionIds` array of Session ids, most recently pinned first. Pinning requires a known, unarchived Session; unpinning an id that is not pinned succeeds without changing the set. Archiving removes the Session's pin in the same durable write, and unarchiving does not restore it.
133
+
134
+ ## Archive admission
135
+
136
+ Archiving is a registry-global durable set, and the registry refuses to hide running work behind it. The rule is a capability seam over two Host events the package declares and dispatches ([events](#workspace-events)): `workspace/session-activity` (waterfall) asks the composed providers what still runs for a Session, and `workspace/session-stop` (parallel) asks them to stop it. Each provider registers on the root like any listener, so the package knows no agent, job, or schedule vocabulary; the families are keys of a merge-extensible map.
137
+
138
+ ```ts type-equiv
139
+ /**
140
+ * Activity families a `workspace/session-activity` listener may report. This
141
+ * package declares none: each provider merges its own key from a module both
142
+ * its Host and Client faces import, so a consumer that renders the families
143
+ * sees exactly the keys its program compiled and falls through to a generic
144
+ * description for any other. The shipped providers merge `turn` (the Agent
145
+ * registry), `job` (the job registry seam), `subagent` (the Subagent
146
+ * runtime), and `schedule` (the Schedule plugin).
147
+ */
148
+ interface SessionActivityKindMap {}
149
+ ```
150
+
151
+ `SessionActivityKind` is `keyof SessionActivityKindMap`, so a program that compiled no provider sees no key at all. The shipped keys live in client-importable type modules: `turn` in the Agent registry's `types.ts`, `job` in the job registry seam's `view.ts`, `subagent` in the Subagent runtime's `control-types.ts`, `schedule` in the Schedule plugin's `types.ts`; a consumer that renders the families imports those modules for its cases and keeps a generic line for any other key. A provider answers the waterfall by prepending its `SessionActivity` entries to the result of `next()`; the registry's innermost callback returns an empty list, so a composition without providers archives freely.
152
+
153
+ ```ts type-equiv
154
+ /**
155
+ * One reason a session counts as active for archive admission. Families with
156
+ * per-item identity list their items so a caller can name what must stop.
157
+ */
158
+ interface SessionActivity {
159
+ readonly kind: SessionActivityKind
160
+ /** Active items of the family; absent for a family without per-item identity (`turn`). */
161
+ readonly items?: readonly SessionActivityItem[]
162
+ }
163
+ ```
164
+
165
+ `SessionActivityItem` carries the family-specific `id` (a session, job, or schedule id) and an optional display `label`. `archiveSession(sessionId)` asks the waterfall once, after the existence check, and rejects a non-empty answer with `WorkspaceActiveSessionError` (`sessionId`, `activity`) without writing; the controller maps it to the `workspace/session-active` error, whose details carry the same two fields. `archiveSession(sessionId, { stopActivity: true })` - the `ArchiveSessionOptions` field the transport request exposes as `stopActivity` - skips the check, writes the archive, then dispatches `workspace/session-stop`; a rejecting provider is logged and the archive stays, and the stopped work is never awaited to settlement. An already archived id neither asks nor stops. The shipped providers, what they stop, and the `agent/pre-step` gate that keeps an archived Session from running a model step are documented with the [registry package](../../packages/workspace/workspace/README.md#api-behavior); the decision record is the [archive-stops-running-work Agent Note](../../.agents/notes/implemented/feature/2026-09-21-archive-stops-running-session-work.md).
166
+
167
+ ## Consumers
168
+
169
+ [`dsh-workspace-controller`](../../packages/api/workspace-controller) serves workspace CRUD to GUI clients over `ctx.workspaceRegistry`, and [`dsh-session-controller`](../../packages/api/session-controller) performs the create-session-then-attach flow above. [dsh-agent-instructions](../../packages/context/agent-instructions) is **not** a consumer despite the name: it discovers AGENTS.md-style instruction files under an agent's own cwd and never touches `ctx.workspaceRegistry` - the shared word refers to the user's working directory, not to this registry's entities.
170
+
171
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
172
+
173
+ <a id="cordis-surface"></a>
174
+
175
+ ## Cordis API
176
+
177
+ 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).
178
+
179
+ <a id="ctxdirectorypicker--directorypicker-abstract-seam"></a>
180
+
181
+ ### `ctx.directoryPicker` - `DirectoryPicker` (abstract seam)
182
+
183
+ Abstract directory-picking service. Subclass, implement `capability()`, and load the subclass as a plugin - it registers as `ctx.directoryPicker` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). The capability object must be stable for the service lifetime: consumers may capture it across calls.
184
+
185
+ ```ts cordis-catalog
186
+ /**
187
+ * The backend's interaction capability.
188
+ * @returns the discriminated capability consumers switch on.
189
+ */
190
+ abstract capability(): DirectoryPickerCapability
191
+ ```
192
+
193
+ Source: [`packages/host/directory-picker/src/index.ts`](../../packages/host/directory-picker/src/index.ts)
194
+
195
+ <a id="ctxdirectorypickercontroller--directorypickercontroller"></a>
196
+
197
+ ### `ctx.directoryPickerController` - `DirectoryPickerController`
198
+
199
+ Host service backing the generated `ctx.remote.directoryPicker` namespace. The seam it exports is abstract and therefore never a Loader entry of its own, so this controller carries the wire verbs: one composed backend serves either the native chooser or the browse primitives, and a verb the composition cannot serve is refused rather than approximated.
200
+
201
+ ```ts cordis-catalog
202
+ /**
203
+ * Open the host's OS chooser for a Remote caller.
204
+ * @param signal - caller lifetime; abort terminates the chooser.
205
+ * @returns the chosen absolute path, or null when the operator cancels.
206
+ */
207
+ @Remote('pick') async pick(signal: AbortSignal): Promise<string | null>
208
+
209
+ /**
210
+ * List one directory level for a Remote caller's in-app browser.
211
+ * @param path - absolute directory to list; absent lists the home directory.
212
+ * @param signal - caller lifetime; abort stops the backend's scan instead of
213
+ * letting it outlive a disconnected caller.
214
+ * @returns the level's listing with its ancestry.
215
+ */
216
+ @Remote('list') async list(path: string | undefined, signal: AbortSignal): Promise<DirectoryListing>
217
+
218
+ /**
219
+ * Create one child directory for a Remote caller's in-app browser.
220
+ * @param path - absolute existing parent directory.
221
+ * @param name - single non-blank path segment.
222
+ * @returns the created directory's absolute path.
223
+ */
224
+ @Remote('createDirectory') async createDirectory(path: string, name: string): Promise<string>
225
+ ```
226
+
227
+ Source: [`packages/api/workspace-controller/src/directory-picker.ts`](../../packages/api/workspace-controller/src/directory-picker.ts)
228
+
229
+ <a id="ctxterminalcontroller--terminalcontroller"></a>
230
+
231
+ ### `ctx.terminalController` - `TerminalController`
232
+
233
+ Typed Remote control of transient Session-owned terminal processes.
234
+
235
+ ```ts cordis-catalog
236
+ /**
237
+ * Read the Session working directory and terminal limits without resolving a shell.
238
+ * @param agent - Session owner supplied by the Gateway.
239
+ * @param signal - request cancellation.
240
+ * @returns the Session workspace directory and terminal limits.
241
+ */
242
+ @Remote environment(agent: Agent, signal: AbortSignal): TerminalEnvironment
243
+
244
+ /**
245
+ * Discover installed shells in the Session's execution environment.
246
+ * @param agent - Session owner supplied by the Gateway.
247
+ * @param signal - request cancellation.
248
+ * @returns verified profiles, with the configured or system default first.
249
+ */
250
+ @Remote shells(agent: Agent, signal: AbortSignal): Promise<TerminalShell[]>
251
+
252
+ /**
253
+ * List retained terminals without resolving or activating an Agent.
254
+ * @param sessionId - displayed Session identity, including offline history.
255
+ * @returns terminals retained for this Host lifetime.
256
+ */
257
+ @Remote list(sessionId: SessionId): WebTerminalInfo[]
258
+
259
+ /**
260
+ * Allocate a user shell once for a caller-generated identity, without Agent sandbox or approval restrictions.
261
+ * @param agent - Session owner supplied by the Gateway.
262
+ * @param request - initial dimensions and idempotency identity.
263
+ * @param signal - allocation cancellation; committed terminals survive disconnection.
264
+ * @returns the existing or newly committed terminal.
265
+ */
266
+ @Remote async create(agent: Agent, request: TerminalCreateRequest, signal: AbortSignal): Promise<WebTerminalInfo>
267
+
268
+ /**
269
+ * Retain an existing terminal for a window without activating its Agent or taking input control.
270
+ * @param sessionId - owning Session identity, including an inactive saved layout.
271
+ * @param id - retained Host terminal identity.
272
+ * @param signal - physical Remote stream cancellation.
273
+ * @returns a hold acknowledgement followed by an open lifetime stream.
274
+ */
275
+ @Remote({ mode: 'stream' }) retain(sessionId: SessionId, id: WebTerminalId, signal: AbortSignal): AsyncIterable<TerminalRetentionFrame>
276
+
277
+ /**
278
+ * Attach to a terminal without binding its process lifetime to the transport.
279
+ * @param agent - Session owner supplied by the Gateway.
280
+ * @param id - terminal identity.
281
+ * @param attachmentId - new exclusive input attachment.
282
+ * @param signal - physical stream cancellation.
283
+ * @returns screen recovery followed by output and metadata changes.
284
+ */
285
+ @Remote({ mode: 'stream' }) follow(agent: Agent, id: WebTerminalId, attachmentId: TerminalAttachmentId, signal: AbortSignal): AsyncIterable<TerminalFrame>
286
+
287
+ /**
288
+ * Deliver raw input, including Tab completion and control characters.
289
+ * @param agent - Session owner supplied by the Gateway.
290
+ * @param id - terminal identity.
291
+ * @param attachmentId - current writable attachment.
292
+ * @param data - input bytes represented as UTF-8 text.
293
+ * @returns after provider input acceptance.
294
+ */
295
+ @Remote async write(agent: Agent, id: WebTerminalId, attachmentId: TerminalAttachmentId, data: string): Promise<void>
296
+
297
+ /**
298
+ * Update the dimensions of the PTY and recovery screen.
299
+ * @param agent - Session owner supplied by the Gateway.
300
+ * @param id - terminal identity.
301
+ * @param attachmentId - current writable attachment.
302
+ * @param cols - column count.
303
+ * @param rows - row count.
304
+ * @returns after the resize completes.
305
+ */
306
+ @Remote async resize(agent: Agent, id: WebTerminalId, attachmentId: TerminalAttachmentId, cols: number, rows: number): Promise<void>
307
+
308
+ /**
309
+ * Rename a terminal without changing its shell.
310
+ * @param agent - Session owner supplied by the Gateway.
311
+ * @param id - terminal identity.
312
+ * @param title - nonempty display title, at most 120 characters.
313
+ */
314
+ @Remote rename(agent: Agent, id: WebTerminalId, title: string): void
315
+
316
+ /**
317
+ * Close an identity to future creation and kill its process range; repeated closes succeed.
318
+ * @param agent - Session owner supplied by the Gateway.
319
+ * @param id - terminal identity.
320
+ * @returns after provider cleanup succeeds. A failure retains the terminal for retry.
321
+ */
322
+ @Remote async close(agent: Agent, id: WebTerminalId): Promise<void>
323
+ ```
324
+
325
+ Types: [Agent](core.md) · [SessionId](core.md)
326
+
327
+ Source: [`packages/api/terminal-controller/src/index.ts`](../../packages/api/terminal-controller/src/index.ts)
328
+
329
+ <a id="ctxworkspacecontroller--workspacecontroller"></a>
330
+
331
+ ### `ctx.workspaceController` - `WorkspaceController`
332
+
333
+ Host service backing the generated `ctx.remote.workspace` namespace.
334
+
335
+ ```ts cordis-catalog
336
+ /**
337
+ * Create or idempotently resolve one Workspace over an existing directory.
338
+ * @param request - directory path to register.
339
+ * @returns the Workspace and whether this call created it.
340
+ */
341
+ @Remote('create') create(request: WorkspaceCreateRequest): Promise<WorkspaceCreateValue>
342
+
343
+ /**
344
+ * Initialize or reuse the default Workspace during first-use startup. The
345
+ * directory name is fixed, so the Host never renames or relocates an
346
+ * existing default; its initial title is that same name, which browser
347
+ * consumers label in the reader's language.
348
+ * @param signal - caller lifetime; cancels native directory lookup.
349
+ * @returns the durable Workspace, or undefined when first-use initialization is ineligible; creates no Session or message.
350
+ */
351
+ @Remote('initializeDefault') async initializeDefault(signal: AbortSignal): Promise<WorkspaceValue | undefined>
352
+
353
+ /**
354
+ * Rename one Workspace to a unique non-blank title.
355
+ * @param request - Workspace identity and proposed title.
356
+ * @returns the updated Workspace projection.
357
+ */
358
+ @Remote('rename') rename(request: WorkspaceRenameRequest): Promise<WorkspaceValue>
359
+
360
+ /**
361
+ * Remove one Workspace registration while retaining files and Sessions.
362
+ * @param request - Workspace identity to remove.
363
+ * @returns deletion confirmation.
364
+ */
365
+ @Remote('delete') delete(request: WorkspaceDeleteRequest): Promise<WorkspaceDeleteValue>
366
+
367
+ /**
368
+ * Move one Workspace within the registry display order.
369
+ * @param request - moved Workspace and optional anchor.
370
+ * @returns the complete resulting Workspace order.
371
+ */
372
+ @Remote('insertBefore') insertBefore(request: WorkspaceInsertBeforeRequest): Promise<WorkspaceOrderValue>
373
+
374
+ /**
375
+ * Move one accounted Session within a Workspace.
376
+ * @param request - Workspace, Session, and optional anchor identities.
377
+ * @returns the updated Workspace projection.
378
+ */
379
+ @Remote('insertSessionBefore') insertSessionBefore(request: WorkspaceInsertSessionBeforeRequest): Promise<WorkspaceValue>
380
+
381
+ /**
382
+ * Hide one known Session from Workspace grouping surfaces.
383
+ * @param request - Session identity to archive.
384
+ * @returns the complete resulting archive set.
385
+ */
386
+ @Remote('archiveSession') archiveSession(request: WorkspaceArchiveSessionRequest): Promise<WorkspaceArchiveValue>
387
+
388
+ /**
389
+ * Restore one archived Session to Workspace grouping surfaces.
390
+ * @param request - Session identity to unarchive.
391
+ * @returns the complete resulting archive set.
392
+ */
393
+ @Remote('unarchiveSession') unarchiveSession(request: WorkspaceUnarchiveSessionRequest): Promise<WorkspaceArchiveValue>
394
+
395
+ /**
396
+ * Surface one known unarchived Session ahead of unpinned Sessions.
397
+ * @param request - Session identity to pin.
398
+ * @returns the complete resulting pin set, most recently pinned first.
399
+ */
400
+ @Remote('pinSession') pinSession(request: WorkspacePinSessionRequest): Promise<WorkspacePinValue>
401
+
402
+ /**
403
+ * Remove one Session's pin without changing its saved Session order.
404
+ * @param request - Session identity to unpin.
405
+ * @returns the complete resulting pin set, most recently pinned first.
406
+ */
407
+ @Remote('unpinSession') unpinSession(request: WorkspaceUnpinSessionRequest): Promise<WorkspacePinValue>
408
+
409
+ /**
410
+ * Stream a complete Workspace baseline followed by ordered increments.
411
+ * @param signal - generation cancellation.
412
+ * @returns baseline followed by ordered Workspace increments.
413
+ */
414
+ @Remote({ mode: 'stream' }) follow(signal: AbortSignal): AsyncIterable<WorkspaceFollowFrame>
415
+ ```
416
+
417
+ Source: [`packages/api/workspace-controller/src/index.ts`](../../packages/api/workspace-controller/src/index.ts)
418
+
419
+ <a id="ctxworkspacefiles--workspacefiles"></a>
420
+
421
+ ### `ctx.workspaceFiles` - `WorkspaceFiles`
422
+
423
+ Host Remote file reads and workspace directory observations over the composed filesystem.
424
+
425
+ ```ts cordis-catalog
426
+ /**
427
+ * Read one page of lines from a UTF-8 file readable by the filesystem backend.
428
+ * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
429
+ * @param path - absolute path or path relative to the workspace root; files outside it are allowed.
430
+ * @param range - the line window; omitted fields take the page defaults.
431
+ * @param signal - caller cancellation.
432
+ * @returns the page, the file's version at the stat before it, and whether it reaches the last line.
433
+ */
434
+ @Remote async read( workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceFileRange, signal: AbortSignal, ): Promise<WorkspaceFileText>
435
+
436
+ /**
437
+ * Read a complete regular file or one byte range without text decoding.
438
+ * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
439
+ * @param path - target path, absolute or workspace-relative; relative to the base file's directory when provided.
440
+ * @param options - optional base file and range; without a range the complete-file cap applies.
441
+ * @param signal - caller cancellation.
442
+ * @returns native bytes with the file's version and size at the preceding stat, byte offset, and EOF marker.
443
+ */
444
+ @Remote async readBytes( workspaceFileScope: WorkspaceFileScope, path: string, options: WorkspaceByteReadOptions, signal: AbortSignal, ): Promise<WorkspaceFileBytes>
445
+
446
+ /**
447
+ * Report one regular file's identity, version, and size without its content.
448
+ * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
449
+ * @param path - absolute path or path relative to the workspace root; files outside it are allowed.
450
+ * @param signal - caller cancellation.
451
+ * @returns the file's absolute path, current version, and byte size.
452
+ */
453
+ @Remote async stat(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise<WorkspaceFileStat>
454
+
455
+ /**
456
+ * List the direct children of one directory inside the Session's workspace.
457
+ * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
458
+ * @param path - workspace path, absolute or relative to the workspace root.
459
+ * @param signal - caller cancellation.
460
+ * @returns the directory's children in the backend's stable name order, bounded by the entry cap.
461
+ */
462
+ @Remote async list(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise<WorkspaceDirectoryListing>
463
+
464
+ /**
465
+ * Watch one file or a directory's direct entries in the Session's filesystem.
466
+ * Files use the backend's read authority; directories remain workspace-scoped.
467
+ * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
468
+ * @param path - target path; the Host determines its type and confines directories to the workspace.
469
+ * @param signal - generation cancellation.
470
+ * @returns `ready` once the target watch is active, then current metadata for queued and live invalidations.
471
+ * @throws RemoteError when watching is unavailable or a directory is outside the workspace.
472
+ */
473
+ @Remote({ mode: 'stream' }) changes(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame>
474
+ ```
475
+
476
+ Source: [`packages/api/workspace-files/src/index.ts`](../../packages/api/workspace-files/src/index.ts)
477
+
478
+ <a id="ctxworkspaceregistry--workspaceregistry"></a>
479
+
480
+ ### `ctx.workspaceRegistry` - `WorkspaceRegistry`
481
+
482
+ Durable workspace registry. Startup waits for `sessionPersistence`, builds one canonical-cwd header index, and completes the one-time history bootstrap before the service becomes active. The persistence dependency is mandatory so an unavailable peer can never be mistaken for an empty history and commit the initialized marker.
483
+
484
+ ```ts cordis-catalog
485
+ /**
486
+ * Create or reuse a workspace for an existing directory. The fully qualified
487
+ * path is canonicalized through `fs.realpath`; a relative, nonexistent, or
488
+ * non-directory path rejects. Repeated calls for the same canonical path
489
+ * return the existing entity without changing its title.
490
+ * A newly created workspace is prepended to the durable registry order.
491
+ * Different canonical paths may share a display title.
492
+ * @param path - Existing directory to own, in a fully qualified path spelling.
493
+ * @param title - Display title used only when a new record is created.
494
+ * @returns the existing or newly durable workspace.
495
+ */
496
+ async create(path: string, title?: string): Promise<Workspace>
497
+
498
+ /**
499
+ * Initialize the default Workspace only while both the registry and Session
500
+ * history are empty. Repeated requests reuse its durable identity; deleting
501
+ * that registration permanently disables automatic creation.
502
+ * @param resolveDirectory - resolve the absolute directory; called only for
503
+ * eligible creation, inside the registry mutation queue. Missing directories
504
+ * are created recursively before registration, and the initial title is the
505
+ * requested directory's own final segment - not the canonical one, so a
506
+ * symlink at that path does not retitle the Workspace after its target.
507
+ * After resolution, caller cancellation does not roll back creation or registration.
508
+ * @returns the initialized Workspace, or undefined when automatic creation is ineligible.
509
+ */
510
+ initializeDefault(resolveDirectory: () => Promise<string>): Promise<Workspace | undefined>
511
+
512
+ /**
513
+ * Look up a workspace by id.
514
+ * @param id - Workspace id.
515
+ * @returns the workspace, or `undefined` when unknown.
516
+ */
517
+ get(id: WorkspaceId): Workspace | undefined
518
+
519
+ /**
520
+ * Synchronous workspace projection in durable registry order. Every
521
+ * entity's `sessionIds` getter is already filtered by the startup/live
522
+ * canonical-cwd header index; this method performs no persistence reads.
523
+ * @returns a fresh ordered array of workspace entities.
524
+ */
525
+ list(): Workspace[]
526
+
527
+ /**
528
+ * Delete one workspace registration while retaining its directory and every
529
+ * session log. The durable order is updated before the table deletion; a
530
+ * failed table write restores the prior order and keeps the entity
531
+ * published. Unknown ids are an idempotent no-op for domain callers.
532
+ * @param id - Workspace registration to remove.
533
+ * @returns `true` when a record was deleted, `false` when it was unknown.
534
+ */
535
+ delete(id: WorkspaceId): Promise<boolean>
536
+
537
+ /**
538
+ * Move one workspace within the durable display order, DOM-insertBefore-like.
539
+ * With an anchor it lands before that workspace; without one it appends.
540
+ * @param id - Workspace to move.
541
+ * @param beforeId - Workspace anchor; omitted appends.
542
+ * @returns the complete committed workspace order.
543
+ */
544
+ insertBefore(id: WorkspaceId, beforeId?: WorkspaceId): Promise<readonly WorkspaceId[]>
545
+
546
+ /**
547
+ * Archive one session durably. The session must exist (live or in session
548
+ * persistence); its workspace accounting - or lack of one - is irrelevant.
549
+ * Without `stopActivity` the session must also be inactive: the
550
+ * `workspace/session-activity` waterfall is asked once, and any reported
551
+ * activity rejects with {@link WorkspaceActiveSessionError} before anything
552
+ * is written. With `stopActivity` the archive is written without an
553
+ * activity check, and the `workspace/session-stop` providers are then asked
554
+ * to stop the session's work: the durable archive set is what a provider's
555
+ * `agent/pre-step` gate reads, so every wake the stops induce is already
556
+ * blocked. Archiving drops the session's pin in the same durable write
557
+ * (pinning and archival are mutually exclusive). An already archived id
558
+ * resolves without writing, asking, or stopping.
559
+ * @param sessionId - The session to archive.
560
+ * @param options - Whether running work is stopped instead of refusing.
561
+ * @returns resolution after durability and, with `stopActivity`, after every stop request was issued.
562
+ */
563
+ archiveSession(sessionId: SessionId, options: ArchiveSessionOptions = {}): Promise<void>
564
+
565
+ /**
566
+ * Unarchive one session durably by dropping it from the registry-global
567
+ * archive set; the accounting slot was never touched, so the session
568
+ * returns to its recorded position. Unarchiving runs no session-existence
569
+ * check because removing an id cannot introduce an unknown one, so an
570
+ * entry whose session is gone still resolves. An id that is not archived
571
+ * resolves without writing.
572
+ * @param sessionId - The session to unarchive.
573
+ * @returns resolution after durability.
574
+ */
575
+ unarchiveSession(sessionId: SessionId): Promise<void>
576
+
577
+ /**
578
+ * Pin one session durably, prepending it to the registry-global pin set.
579
+ * The session must exist (live or in session persistence) and must not be
580
+ * archived. An already pinned id resolves without writing or reordering.
581
+ * @param sessionId - The session to pin.
582
+ * @returns resolution after durability.
583
+ */
584
+ pinSession(sessionId: SessionId): Promise<void>
585
+
586
+ /**
587
+ * Unpin one session durably by dropping it from the registry-global pin
588
+ * set. Unpinning runs no session-existence check because removing an id
589
+ * cannot introduce an unknown one, so an entry whose session is gone still
590
+ * resolves. An id that is not pinned resolves without writing.
591
+ * @param sessionId - The session to unpin.
592
+ * @returns resolution after durability.
593
+ */
594
+ unpinSession(sessionId: SessionId): Promise<void>
595
+
596
+ /**
597
+ * Resolve by canonical directory path without creating or mutating a
598
+ * workspace. A missing path rejects during `realpath`; an existing unowned
599
+ * directory returns `undefined`.
600
+ * @param path - Existing directory path in a fully qualified spelling.
601
+ * @returns the workspace owning the canonical path, when one exists.
602
+ */
603
+ async resolveByPath(path: string): Promise<Workspace | undefined>
604
+ ```
605
+
606
+ Types: [SessionId](core.md)
607
+
608
+ Source: [`packages/workspace/workspace/src/index.ts`](../../packages/workspace/workspace/src/index.ts)
609
+
610
+ <a id="workspace-events"></a>
611
+
612
+ ### `workspace/*` events
613
+
614
+ <a id="workspacesession-activity--waterfall"></a>
615
+
616
+ #### `workspace/session-activity` - waterfall
617
+
618
+ Ask the composed providers what still runs for a session before it is archived. A listener prepends its own SessionActivity entries to the result of `next()`; the registry's innermost callback returns an empty list, so a composition without providers archives freely. Any non-empty result refuses the archive without a write.
619
+
620
+ ```ts cordis-catalog
621
+ /**
622
+ * Ask the composed providers what still runs for a session before it is
623
+ * archived. A listener prepends its own {@link SessionActivity} entries to
624
+ * the result of `next()`; the registry's innermost callback returns an
625
+ * empty list, so a composition without providers archives freely. Any
626
+ * non-empty result refuses the archive without a write.
627
+ * @param request - the session about to be archived.
628
+ * @param next - delegate to the remaining providers.
629
+ * @mode waterfall
630
+ */
631
+ 'workspace/session-activity'( request: SessionActivityRequest, next: () => Promise<readonly SessionActivity[]>, ): Promise<readonly SessionActivity[]>
632
+ ```
633
+
634
+ Source: [`packages/workspace/workspace/src/index.ts`](../../packages/workspace/workspace/src/index.ts)
635
+
636
+ <a id="workspacesession-stop--parallel"></a>
637
+
638
+ #### `workspace/session-stop` - parallel
639
+
640
+ Stop a session's running work because the caller archived it with `stopActivity`; the archive set is durable when this dispatches. Each provider stops its own families - cancelling a turn, its subagent descendants, owned jobs, or active schedules - through the same cancel paths the user's own stop actions use, so the session log ends every open turn regularly and a later unarchive can continue the conversation. Listeners issue their stop requests without waiting for running work to settle; a listener may await its own durability barrier. A rejection is logged by the registry and does not undo the archive.
641
+
642
+ ```ts cordis-catalog
643
+ /**
644
+ * Stop a session's running work because the caller archived it with
645
+ * `stopActivity`; the archive set is durable when this dispatches. Each
646
+ * provider stops its own families - cancelling a turn, its subagent
647
+ * descendants, owned jobs, or active schedules - through the same cancel
648
+ * paths the user's own stop actions use, so the session log ends every
649
+ * open turn regularly and a later unarchive can continue the
650
+ * conversation. Listeners issue their stop requests without waiting for
651
+ * running work to settle; a listener may await its own durability
652
+ * barrier. A rejection is logged by the registry and does not undo the
653
+ * archive.
654
+ * @param request - the session being archived.
655
+ * @mode parallel
656
+ */
657
+ 'workspace/session-stop'(request: SessionActivityRequest): Promise<void> | void
658
+ ```
659
+
660
+ Source: [`packages/workspace/workspace/src/index.ts`](../../packages/workspace/workspace/src/index.ts)
661
+ <!-- END GENERATED cordis-surface -->