@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,532 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/filesystem.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Filesystem
4
+
5
+ English | [中文](filesystem.zh.md)
6
+
7
+ The optional filesystem capability has four parts: [dsh-fs](../../packages/fs/fs) owns `ctx.fs` and atomic text operations with optional guards, [dsh-fs-local](../../packages/fs/fs-local) implements local disk, [dsh-fs-observation-policy](../../packages/fs/fs-observation-policy) records observed presence or absence and adds freshness rules through events rather than a service, and [dsh-tool-fs](../../packages/fs/tool-fs) directly executes model-facing read/write/edit calls and renders windows. It is outside the agent-loop spine; alternate backends do not change policy or tool schemas.
8
+
9
+ `dsh-fs-observation-policy` is optional. Without it, the `FileSystem` Service Definition, a provider, and the `dsh-tool-fs` Consumer form the complete, unconstrained filesystem seam: `write` unconditionally creates or overwrites, and `edit` unconditionally replaces literal text. The policy plugin changes these operations by deciding the `fs/*` waterfalls. Removing it does not break the tool because the tool calls `ctx.fs` and dispatches events; it does not call policy methods. A deployment that loads `dsh-tool-fs` is expected to also load `dsh-fs-observation-policy` so the default behavior is read-before-write/edit.
10
+
11
+ Provider source: [`packages/fs/fs/src/types.ts`](../../packages/fs/fs/src/types.ts) and [`packages/fs/fs/src/index.ts`](../../packages/fs/fs/src/index.ts). Policy source: [`packages/fs/fs-observation-policy/src/types.ts`](../../packages/fs/fs-observation-policy/src/types.ts). Read-rendering source: [`packages/fs/tool-fs/src/read-render.ts`](../../packages/fs/tool-fs/src/read-render.ts).
12
+
13
+ ## Target identity and metadata (provider contract)
14
+
15
+ Every operation resolves a user-supplied path to an opaque backend target first. Consumers may display `displayPath`, but must not parse `targetKey` (a branded opaque id) or assume it is a local absolute path.
16
+
17
+ Consumers that share the filesystem's execution world obtain cross-capability coordinates through the provider instead of interpreting that identity: `processPath(target)` returns the canonical absolute path a subprocess can open, `processPathFromHostPath(hostPath)` maps an absolute harness-host file only when that execution world shares it, `fileUrl(target)` returns its provider-platform `file:` URI, and `contains(parent, child)` tests canonical identity or descendant containment.
18
+
19
+ ```ts type-equiv
20
+ /**
21
+ * A path resolved by a backend into a stable identity. `resolve()` produces
22
+ * this; every other operation takes it.
23
+ */
24
+ interface FsTarget {
25
+ /** Opaque key for stale guards and target lookup. */
26
+ targetKey: FsTargetKey
27
+ /**
28
+ * Path for model/UI-facing output. May be a local absolute path,
29
+ * workspace-relative path, or remote URI depending on the backend.
30
+ */
31
+ displayPath: string
32
+ }
33
+ ```
34
+
35
+ The backend owns file-version tokens - the freshness token a write/edit guards against. The policy plugin stores them for stale checks; consumers do not interpret them. Both ids are branded opaque strings.
36
+
37
+ ```ts type-equiv
38
+ /**
39
+ * Opaque key for stale guards and target lookup. The local backend uses a
40
+ * realpath-like string; a remote backend might use a workspace URI or file id.
41
+ * Consumers MUST NOT parse it or assume it is a local absolute path.
42
+ */
43
+ type FsTargetKey = Branded<'FsTargetKey'>
44
+ ```
45
+
46
+ ```ts type-equiv
47
+ /**
48
+ * Opaque file-version token - the freshness token a write/edit guards against.
49
+ * The local backend derives it from high-resolution stat identity and freshness
50
+ * fields; a remote backend might use a revision id. The policy layer records it
51
+ * for stale checks; consumers may display related metadata but MUST NOT
52
+ * interpret this token.
53
+ */
54
+ type FsVersion = Branded<'FsVersion'>
55
+ ```
56
+
57
+ `stat` returns metadata (never content), or `undefined` when the target is absent. `type` lets consumers reject directories and special files before reading, and `size` lets text consumers choose `readText` vs `streamText` without probing by failure. A text consumer applies its own retention ceiling while consuming `streamText`. Raw-byte consumers use `readBytes(target, signal, maxBytes)`; its required complete-content cap makes a known or discovered overflow fail with `FS_TOO_LARGE` instead of truncating or buffering without a bound.
58
+
59
+ ```ts type-equiv
60
+ /**
61
+ * Metadata about a target - what {@link FileSystem.stat} returns. Lets the
62
+ * policy layer reject directories/special files before reading and choose
63
+ * `readText` vs `streamText` from `size` without probing by failure. `version`
64
+ * is the freshness token. `undefined` from `stat` means the target is absent.
65
+ */
66
+ interface FsInfo {
67
+ /** Opaque freshness token of the target right now. */
68
+ version: FsVersion
69
+ /** Whether the target is a regular file, a directory, or something else. */
70
+ type: 'file' | 'directory' | 'other'
71
+ /** Byte size of a regular file, when the backend can report it. */
72
+ size?: number
73
+ }
74
+ ```
75
+
76
+ `lstat` is the path-level no-follow metadata primitive. It takes a path instead of an `FsTarget` because `resolve` intentionally follows symlinks to produce stable identity; consumers that need trust-boundary checks can call `lstat` first and reject `symlink` before resolving.
77
+
78
+ ```ts type-equiv
79
+ /**
80
+ * Metadata about a path without following the final path component when it is a
81
+ * symbolic link. Unlike {@link FsInfo}, this path-level probe can report
82
+ * `symlink` so consumers with trust-boundary rules can reject repository-owned
83
+ * links before resolving a target.
84
+ */
85
+ interface FsPathInfo {
86
+ /** Opaque freshness token of the path entry right now. */
87
+ version: FsVersion
88
+ /** Whether the path entry is a regular file, directory, symlink, or other. */
89
+ type: 'file' | 'directory' | 'symlink' | 'other'
90
+ /** Byte size of the path entry, when the backend can report it. */
91
+ size?: number
92
+ }
93
+ ```
94
+
95
+ `listDir` returns direct child entries in stable name order. Each entry carries the child basename, type, resolved target, and cheap metadata when the backend can report it. It must not read file contents, so `size` is only for regular files and `version` is metadata-derived. Broken or disappeared children may be returned as `other` without metadata; permission or backend I/O failures while listing or resolving child metadata fail the whole listing with `FS_PERMISSION_DENIED` or `FS_IO_ERROR`.
96
+
97
+ ```ts type-equiv
98
+ /**
99
+ * One direct child returned by {@link FileSystem.listDir}. Listing returns
100
+ * metadata and resolved targets only; it must not read file contents.
101
+ */
102
+ interface FsDirEntry {
103
+ /** Basename of the child inside the listed directory. */
104
+ name: string
105
+ /** Whether the child is a regular file, a directory, or something else. */
106
+ type: 'file' | 'directory' | 'other'
107
+ /** Resolved child target for follow-up operations. */
108
+ target: FsTarget
109
+ /** Opaque freshness token when the backend can report metadata cheaply. */
110
+ version?: FsVersion
111
+ /** Byte size of a regular file, when the backend can report it. */
112
+ size?: number
113
+ }
114
+ ```
115
+
116
+ ## Write and edit guards (provider contract)
117
+
118
+ Both `writeText` and `editText` take their version guard OPTIONALLY: omit it for an unconditional (bare-provider) mutation, supply it to guard. `writeText`'s guard is an `FsWriteIntent` - `createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`, including a target that appears after the provider's initial probe because publication itself must be no-replace; `replaceIfVersion` replaces only when the target exists at the observed version, else `FS_STALE_VERSION`. Omitting `expected` unconditionally creates-or-overwrites. The union itself carries only the two guarded intents; "no guard" is expressed by omission, so write and edit both use the same optional `expected` field.
119
+
120
+ ```ts type-equiv
121
+ /**
122
+ * Guarded write intent. `createIfAbsent` rejects an existing target with
123
+ * `FS_NOT_OBSERVED`; `replaceIfVersion` rejects absence or mismatch with
124
+ * `FS_STALE_VERSION`. Omitting the intent from `writeText` means unconditional
125
+ * create-or-overwrite, not a third union arm.
126
+ */
127
+ type FsWriteIntent =
128
+ | { kind: 'createIfAbsent' }
129
+ | { kind: 'replaceIfVersion'; version: FsVersion }
130
+ ```
131
+
132
+ ```ts type-equiv
133
+ /** Outcome of a full-file write. */
134
+ interface FsWriteOutcome {
135
+ /** Whether the write created a new file or replaced an existing one. */
136
+ operation: 'create' | 'update'
137
+ /** Opaque version of the file after the write. */
138
+ version: FsVersion
139
+ /**
140
+ * The file's content BEFORE the write, or `null` when the file did not exist
141
+ * (a create) or the backend declined a contextual basis (for example, a
142
+ * binary/non-UTF-8 prior file or either overwrite side reaching its exclusive limit).
143
+ * LF-normalized storage text (the diff basis), never a diff - a consumer
144
+ * computes the result-time contextual diff from `before`/`after` when
145
+ * `before` is present, else falls back to a whole-file diff.
146
+ */
147
+ before: string | null
148
+ /** The file's content AFTER the write, LF-normalized to share `before`'s diff basis. */
149
+ after: string
150
+ }
151
+ ```
152
+
153
+ `editText` is a provider-level mutation, not a `read` plus `write` composed elsewhere. When guarded it verifies the expected version BEFORE literal matching (so a stale edit reports `FS_STALE_VERSION`, not a match failure against newer content); unguarded it edits the current content. Either way it applies the replacement and writes atomically - keeping matching, line-ending handling, the stale check, and atomic replacement inside one mutation critical section - and a missing target reports `FS_STALE_VERSION` on both paths.
154
+
155
+ ```ts type-equiv
156
+ /** A literal-replacement edit request. */
157
+ interface FsEditRequest {
158
+ /** Literal non-empty text to replace. Must match exactly (after line-ending normalization). */
159
+ oldString: string
160
+ /** Literal replacement text. An empty string deletes the matched text. */
161
+ newString: string
162
+ /** Replace every match instead of requiring exactly one. */
163
+ replaceAll: boolean
164
+ }
165
+ ```
166
+
167
+ ```ts type-equiv
168
+ /** Outcome of a literal edit. */
169
+ interface FsEditOutcome {
170
+ /** Opaque version of the file after the edit. */
171
+ version: FsVersion
172
+ /**
173
+ * The file's content BEFORE the edit. Raw storage text (LF-normalized by the
174
+ * backend), never a diff - a consumer computes the result-time contextual diff
175
+ * (the applied hunk with context) from `before`/`after`.
176
+ */
177
+ before: string
178
+ /** The file's content AFTER the edit. */
179
+ after: string
180
+ }
181
+ ```
182
+
183
+ ## The fs policy events (provider contract vocabulary)
184
+
185
+ `dsh-fs` owns three events the tool dispatches and the policy plugin listens for, so the emitter (`dsh-tool-fs`) and the listener (`dsh-fs-observation-policy`) share a vocabulary without the emitter depending on the policy plugin. They carry only `dsh-fs` vocabulary plus an opaque `object` actor - no model-facing concepts and no agent/session owner structure.
186
+
187
+ `fs/write-intent` and `fs/edit-intent` are **single-slot decision waterfalls**: the tool dispatches each with a default thunk returning `undefined` (the bare provider), and a listener fully decides without calling `next()`. The slot is first-wins by registration order - the policy plugin owning it is a deployment convention, not an enforced invariant. `fs/observed` is a fire-and-forget recording event carrying an `FsObservation`: present at a version or confirmed absent. It is dispatched with a plain `ctx.emit`; its listener MUST be synchronous and side-effect-only, because the tool does NOT guard the emit - a throwing listener can replace a read error or surface as the tool's `isError` result after a mutation already succeeded. The generated [cordis surface](#cordis-surface) below shows the exact signatures.
188
+
189
+ ```ts type-equiv
190
+ /**
191
+ * One authoritative observation of a target. A present observation carries the
192
+ * version used by guarded replacement; an absent observation authorizes only a
193
+ * guarded create, never an edit.
194
+ */
195
+ type FsObservation =
196
+ | { readonly kind: 'present'; readonly version: FsVersion }
197
+ | { readonly kind: 'absent' }
198
+ ```
199
+
200
+ ## Execution context (policy plugin)
201
+
202
+ The policy plugin needs just enough execution context to derive the observed-state owner by narrowing the opaque `object` actor the `fs/*` events carry. `ToolExecution` has the required fields, so `dsh-tool-fs` passes its execution object through as the actor without making `dsh-fs-observation-policy` import the tool, agent, or session packages.
203
+
204
+ ```ts type-equiv
205
+ /**
206
+ * Minimal structural view of a tool execution the policy plugin needs to derive
207
+ * an observed-state owner. `@deepseek-ai/dsh-tools`' `ToolExecution` contains
208
+ * these fields, so the tool passes its `exec` straight through as the opaque
209
+ * `object` actor on the `fs/*` events; this plugin narrows that actor to
210
+ * `FsObservationActor` without importing `dsh-tools`, `dsh-agent`, or `dsh-session`.
211
+ *
212
+ * The owner is `agent.session` when present. It is treated as an opaque object
213
+ * identity (a `WeakMap` key); this package never reads any of its fields.
214
+ */
215
+ interface FsObservationActor {
216
+ /** The agent on whose behalf the call runs, when there is one. */
217
+ agent?: {
218
+ /** The session that owns observed-file state, used as an opaque key. */
219
+ session?: object
220
+ }
221
+ }
222
+ ```
223
+
224
+ ## Read outcome (consumer / read rendering)
225
+
226
+ A text read is bounded by line window, byte cap, and backend limits. After the byte cap is reached, scanning continues without retaining more lines so `totalLines` remains exact. The result the model-facing `read` tool renders is purely presentational; there is no `full`/`partial` view - authorization is freshness-based (the tool emits a present `fs/observed` directly with the stat's version), so any windowed read can authorize a later write/edit when the file is unchanged. A metadata miss emits an absent observation before the tool returns `FS_NOT_FOUND`, allowing a later guarded write to recreate an externally deleted target without authorizing edit. `dsh-tool-fs`, the executor that owns the read, implements read windowing and constructs this result; the policy plugin does not.
227
+
228
+ ```ts type-equiv
229
+ /** Outcome of a bounded text read - what {@link formatReadOutput} renders. */
230
+ interface FileReadOutcome {
231
+ /** 1-based first line requested. */
232
+ offset: number
233
+ /** Returned lines, already numbered. */
234
+ lines: FileTextLine[]
235
+ /** Exact total line count in the file. */
236
+ totalLines: number
237
+ /** Whether selected output hit the byte cap. */
238
+ truncatedByBytes?: true
239
+ }
240
+ ```
241
+
242
+ ## Observed-file state (policy plugin)
243
+
244
+ Observed state is a `WeakMap<owner, Map<targetKey, FsObservation>>` held inside the `dsh-fs-observation-policy` plugin. Missing map entry means unseen; `{ kind: 'absent' }` means a `read` or `str_replace_editor` `view`, `str_replace`, or `insert` metadata miss confirmed absence; `{ kind: 'present', version }` means a read, write, or edit observed that version. The write decision maps unseen and absent to `createIfAbsent`, while present maps to `replaceIfVersion`; the edit decision maps unseen to `FS_NOT_OBSERVED`, absent to `FS_NOT_FOUND`, and present to its version guard. The owner is derived from the event actor (normally `exec.agent.session`), treated as opaque and never read. Disposal drops everything (HMR safety), and the policy performs no filesystem I/O.
245
+
246
+ ## Error taxonomy (provider contract)
247
+
248
+ Filesystem failures use stable `FsErrorCode` strings carried by `FsError` (`HarnessError`). The tool registry preserves `{ name, code }` on error results, so retry, permission, and UI layers can branch without parsing text.
249
+
250
+ ```ts type-equiv
251
+ /**
252
+ * Stable, machine-routable codes for filesystem failures. Carried on
253
+ * {@link FsError}; the tool registry exposes `{ name, code }` on `isError`
254
+ * results so retry/permission/UI layers can branch without parsing messages.
255
+ */
256
+ type FsErrorCode =
257
+ | 'FS_NOT_FOUND'
258
+ | 'FS_NOT_DIRECTORY'
259
+ | 'FS_NOT_TEXT'
260
+ | 'FS_NOT_REGULAR_FILE'
261
+ | 'FS_TOO_LARGE'
262
+ | 'FS_PERMISSION_DENIED'
263
+ | 'FS_SANDBOX_DENIED'
264
+ | 'FS_IO_ERROR'
265
+ | 'FS_STALE_VERSION'
266
+ | 'FS_NOT_OBSERVED'
267
+ | 'FS_AMBIGUOUS_EDIT'
268
+ | 'FS_EDIT_NOT_FOUND'
269
+ | 'FS_ABORTED'
270
+ ```
271
+
272
+ `FS_NOT_DIRECTORY`, `FS_PERMISSION_DENIED`, and `FS_IO_ERROR` are used by directory listing to distinguish an existing non-directory target, a denied listing, and an unexpected backend I/O failure. `FS_SANDBOX_DENIED` is a POLICY refusal from a sandbox-enforcing backend (`dsh-fs-sandbox`) - the mode fence denied a write/edit - distinct from `FS_PERMISSION_DENIED` (the host kernel refusing). `FS_NOT_OBSERVED` means the policy plugin has no prior-observation record for this owner (or a `createIfAbsent` hit an existing file). `FS_NOT_FOUND` also represents an edit rejected from confirmed absence. `FS_STALE_VERSION` means the backend version no longer matches the observed one (or the provider itself receives an edit for a missing target). Freshness authorization has no partial/full distinction, so there is no `FS_PARTIAL_OBSERVATION`.
273
+
274
+ ## No timeouts on file IO
275
+
276
+ `read`/`write`/`edit` take **no** `timeoutMs`, and the provider contract arms no deadline - unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)) and the subprocess-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-tool-call-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most - a timeout could not force an in-progress `fsync`/`rename` to stop, so a `timeoutMs` here would be a deadline the seam cannot enforce, and an implicit default in the exact place explicit-over-implicit forbids. Cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
277
+
278
+ ## The service and the plugin
279
+
280
+ `FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `processPathFromHostPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `readBytes`, `listDir`, `writeText`, and `editText`. `dsh-fs-observation-policy` registers **no service** - it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls from unseen/absent/present state and records `FsObservation` values. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated [`ctx.fs` section](#ctxfs--filesystem-abstract-seam) below shows the exact signatures.
281
+
282
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
283
+
284
+ <a id="cordis-surface"></a>
285
+
286
+ ## Cordis API
287
+
288
+ 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).
289
+
290
+ <a id="ctxfs--filesystem-abstract-seam"></a>
291
+
292
+ ### `ctx.fs` - `FileSystem` (abstract seam)
293
+
294
+ Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.
295
+
296
+ ```ts cordis-catalog
297
+ /**
298
+ * Observe one file or a directory's direct entries in this provider's execution world.
299
+ * @param target - resolved file or directory, including an absent path to observe for creation.
300
+ * @param changed - invalidation callback; errors can be reported during or after initialization.
301
+ * @param signal - cancels watcher initialization; the caller closes an initialized watcher.
302
+ * @returns a promise resolving once observation is active, with an asynchronous close function.
303
+ * @throws when the provider does not support watching or cannot initialize the watcher.
304
+ */
305
+ watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>>
306
+
307
+ /**
308
+ * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a
309
+ * remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence
310
+ * async even though the local backend only normalizes + realpaths.
311
+ *
312
+ * @param path - the path to resolve; relative paths resolve against `opts.cwd`.
313
+ * @param opts - optional cwd override and cancellation signal.
314
+ * @returns the stable target; the same file yields the same `targetKey`.
315
+ */
316
+ abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>
317
+
318
+ /**
319
+ * Return the canonical absolute path a subprocess in this filesystem's
320
+ * execution world can open. The path is deliberately separate from
321
+ * {@link FsTarget.targetKey}: consumers may pass this value to another OS
322
+ * capability, but must continue treating the target key as opaque.
323
+ * @param target - the resolved target whose process path is required.
324
+ * @returns an absolute path in the backend's execution world.
325
+ */
326
+ abstract processPath(target: FsTarget): string
327
+
328
+ /**
329
+ * Map an absolute path from the harness host into this filesystem's
330
+ * execution world when both paths identify the same file. The base provider
331
+ * exposes no mapping; host-backed or explicitly shared backends override it.
332
+ * @param hostPath - absolute path in the harness host filesystem.
333
+ * @returns the process path for the same file, or undefined when this
334
+ * execution world cannot read that host file.
335
+ */
336
+ processPathFromHostPath(hostPath: string): string | undefined
337
+
338
+ /**
339
+ * Return the canonical `file:` URI for a target in this filesystem's
340
+ * execution world. Backends own URI encoding because the host platform may
341
+ * differ from the execution platform.
342
+ * @param target - the resolved target to encode.
343
+ * @returns the target's canonical file URI.
344
+ */
345
+ abstract fileUrl(target: FsTarget): string
346
+
347
+ /**
348
+ * Test canonical containment without exposing or parsing backend target
349
+ * keys. Both targets must come from this provider.
350
+ * @param parent - canonical directory target.
351
+ * @param child - canonical candidate target.
352
+ * @returns true when `child` is `parent` or a descendant of it.
353
+ */
354
+ abstract contains(parent: FsTarget, child: FsTarget): boolean
355
+
356
+ /**
357
+ * Return target metadata, or `undefined` when the target does not exist.
358
+ * @param target - the resolved target to stat.
359
+ * @param signal - aborts the metadata round-trip.
360
+ * @returns metadata only, never content; undefined for an absent target.
361
+ */
362
+ abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>
363
+
364
+ /**
365
+ * Return path metadata without following the final path component when it is a
366
+ * symbolic link. This is intentionally path-shaped, not target-shaped:
367
+ * {@link resolve} follows symlinks to produce the stable identity used by
368
+ * normal reads/writes, while `lstat` lets a consumer reject the path itself
369
+ * before that follow happens.
370
+ *
371
+ * `opts.cwd` follows {@link resolve}'s cwd rules. `undefined` means the path is
372
+ * absent.
373
+ * @param path - the path to inspect; relative paths resolve against `opts.cwd`.
374
+ * @param opts - `cwd` overrides the backend's default base for relative paths.
375
+ * @param signal - aborts the metadata round-trip.
376
+ * @returns metadata only, never content; undefined for an absent path.
377
+ */
378
+ abstract lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined>
379
+
380
+ /**
381
+ * Read the whole regular text file as a single decoded string.
382
+ * @param target - the resolved target to read.
383
+ * @param signal - aborts the read.
384
+ * @returns the full decoded UTF-8 content.
385
+ */
386
+ abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>
387
+
388
+ /**
389
+ * Stream the whole regular text file as decoded text chunks (same text
390
+ * semantics as {@link readText}, for large files). The backend owns
391
+ * cross-chunk UTF-8 decoding and binary rejection so the policy layer never
392
+ * touches raw bytes.
393
+ * @param target - the resolved target to read.
394
+ * @param signal - aborts the stream, including between chunks.
395
+ * @returns the chunk iterable, decoded and validated like {@link readText}.
396
+ */
397
+ abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>
398
+
399
+ /**
400
+ * Read the whole regular file as raw bytes with no decoding or binary
401
+ * rejection. The bound lives at this seam so a backend can never buffer an
402
+ * unbounded file: a target known or discovered to exceed `maxBytes` fails
403
+ * with `FS_TOO_LARGE` instead of returning a truncated result.
404
+ * @param target - the resolved target to read.
405
+ * @param signal - aborts the read.
406
+ * @param maxBytes - inclusive byte cap on the complete content.
407
+ * @returns the full raw content, at most `maxBytes` long.
408
+ */
409
+ abstract readBytes(target: FsTarget, signal: AbortSignal | undefined, maxBytes: number): Promise<Uint8Array>
410
+
411
+ /**
412
+ * Read one byte window of the regular file as raw bytes with no decoding or
413
+ * binary rejection: the bytes at `[offset, offset + length)`, shorter when
414
+ * the file ends inside the window and empty when `offset` lies at or past
415
+ * its end. The window is the bound here, not the file: a backend transfers
416
+ * at most `length` bytes of content beyond the prefix it skips to reach
417
+ * `offset` and never buffers the whole file, so the caller's cap on `length`
418
+ * is the guard against unbounded buffering.
419
+ * @param target - the resolved target to read.
420
+ * @param range - `offset`, the 0-based first byte, and `length`, the largest byte count; both non-negative integers.
421
+ * @param signal - aborts the read.
422
+ * @returns the window's bytes, at most `length` long.
423
+ */
424
+ abstract readByteRange(target: FsTarget, range: { offset: number; length: number }, signal?: AbortSignal): Promise<Uint8Array>
425
+
426
+ /**
427
+ * List direct children of a directory in stable name order. Returns resolved
428
+ * child targets plus cheap metadata only; never reads file contents.
429
+ * @param target - the resolved directory target.
430
+ * @param signal - aborts the listing.
431
+ * @returns one entry per direct child, in stable name order.
432
+ */
433
+ abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>
434
+
435
+ /**
436
+ * Atomically create or replace UTF-8 text. `expected` guards intent and
437
+ * staleness; omission allows unconditional overwrite.
438
+ * @param target - the resolved target to write.
439
+ * @param content - the full new file content.
440
+ * @param expected - the write intent guarding the write; omit for unconditional.
441
+ * @param signal - aborts before atomic publication takes effect.
442
+ * @param sandboxPolicy - the per-call mode and workspace root this write
443
+ * runs under; a sandboxing backend fences the write by it, the bare backend
444
+ * ignores it. Omit to leave the backend its own default.
445
+ * @returns the outcome, including the version the write produced.
446
+ */
447
+ abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsWriteOutcome>
448
+
449
+ /**
450
+ * Atomically edit literal text. When supplied, the version guard is checked
451
+ * before matching so stale content reports `FS_STALE_VERSION`; omission edits
452
+ * the current content without a freshness precondition.
453
+ * @param target - the resolved target to edit.
454
+ * @param edit - the literal search/replace request.
455
+ * @param expected - the version guard; omit for an unconditional edit.
456
+ * @param signal - aborts before atomic publication takes effect.
457
+ * @param sandboxPolicy - the per-call mode and workspace root this edit runs
458
+ * under; a sandboxing backend fences the edit by it, the bare backend
459
+ * ignores it. Omit to leave the backend its own default.
460
+ * @returns the outcome, including the version the edit produced.
461
+ */
462
+ abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsEditOutcome>
463
+ ```
464
+
465
+ Types: [SandboxExecutionPolicy](sandbox.md)
466
+
467
+ Source: [`packages/fs/fs/src/index.ts`](../../packages/fs/fs/src/index.ts)
468
+
469
+ <a id="fs-events"></a>
470
+
471
+ ### `fs/*` events
472
+
473
+ <a id="fsedit-intent--waterfall"></a>
474
+
475
+ #### `fs/edit-intent` - waterfall
476
+
477
+ Single-slot decision for the next FileSystem.editText. Calling `next()` yields an unconditional edit; the first returned guard wins.
478
+
479
+ ```ts cordis-catalog
480
+ /**
481
+ * Single-slot decision for the next {@link FileSystem.editText}. Calling
482
+ * `next()` yields an unconditional edit; the first returned guard wins.
483
+ * @param target - the resolved target about to be edited.
484
+ * @param actor - the opaque tool-execution context the decider keys off.
485
+ * @mode waterfall
486
+ */
487
+ 'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
488
+ ```
489
+
490
+ Source: [`packages/fs/fs/src/index.ts`](../../packages/fs/fs/src/index.ts)
491
+
492
+ <a id="fsobserved--emit"></a>
493
+
494
+ #### `fs/observed` - emit
495
+
496
+ Record an authoritative positive or negative observation. Listeners must be synchronous recorders: throws fail the tool call and returned promises are not awaited.
497
+
498
+ ```ts cordis-catalog
499
+ /**
500
+ * Record an authoritative positive or negative observation. Listeners must
501
+ * be synchronous recorders: throws fail the tool call and returned promises
502
+ * are not awaited.
503
+ * @param target - the target whose presence or absence was observed.
504
+ * @param observation - present with its version, or confirmed absent.
505
+ * @param actor - the observing tool-execution context; undefined records nothing useful.
506
+ * @mode emit
507
+ */
508
+ 'fs/observed'(target: FsTarget, observation: FsObservation, actor: object | undefined): void
509
+ ```
510
+
511
+ Source: [`packages/fs/fs/src/index.ts`](../../packages/fs/fs/src/index.ts)
512
+
513
+ <a id="fswrite-intent--waterfall"></a>
514
+
515
+ #### `fs/write-intent` - waterfall
516
+
517
+ Single-slot decision for the next FileSystem.writeText. Calling `next()` yields the bare provider's unconditional write; the first listener that returns an intent owns the decision rather than composing with peers.
518
+
519
+ ```ts cordis-catalog
520
+ /**
521
+ * Single-slot decision for the next {@link FileSystem.writeText}. Calling
522
+ * `next()` yields the bare provider's unconditional write; the first listener
523
+ * that returns an intent owns the decision rather than composing with peers.
524
+ * @param target - the resolved target about to be written.
525
+ * @param actor - the opaque tool-execution context the decider keys off.
526
+ * @mode waterfall
527
+ */
528
+ 'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
529
+ ```
530
+
531
+ Source: [`packages/fs/fs/src/index.ts`](../../packages/fs/fs/src/index.ts)
532
+ <!-- END GENERATED cordis-surface -->