@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,363 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/attachment.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Durable Attachments
4
+
5
+ English | [中文](attachment.zh.md)
6
+
7
+ The attachment seam separates binary image and generic-file ownership from the session log. A producer gives bytes to [`ctx.attachments`](#ctxattachments--attachmentstore-abstract-seam); the service publishes an immutable content-addressed reference only after the object is durable. Session events and model-visible attachment blocks contain that reference and metadata, never a browser object URL, host temporary path, provider URL, or base64 payload. The independent [`ctx.fileUploads`](#ctxfileuploads--fileuploads) service binds browser file transfers and staged receipts to the receiving Agent.
8
+
9
+ Unsent browser drafts may stay in memory and native clients may stage them in operating-system temporary storage. Browser generic files become durable before they receive a staged prompt receipt. Once the host accepts a user message, its images move below `<DSH_HOME>/attachments/v1` before the user event is appended. Structured model image output follows the same persist-before-event rule.
10
+
11
+ Source: [`packages/attachment/attachment/src/types.ts`](../../packages/attachment/attachment/src/types.ts)
12
+
13
+ ## Identity and verified metadata
14
+
15
+ `AttachmentId` is a branded opaque string. The local backend currently emits `sha256:<digest>`, but consumers must neither parse that representation nor derive a filesystem path from it. A consumer may ask the attachment provider for its object location through `imageHostPath()`, then must use the current execution filesystem to decide whether model tools can read that host path.
16
+
17
+ ```ts type-equiv
18
+ /** Raster image formats accepted by the version-one attachment path. */
19
+ type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif'
20
+ ```
21
+
22
+ ```ts type-equiv
23
+ /** Durable, serializable reference to one immutable normalized image. */
24
+ interface ImageAttachmentRef {
25
+ /** Opaque storage identifier; never a filesystem path or bearer URL. */
26
+ attachmentId: AttachmentId
27
+ /** Media type verified from the stored bytes. */
28
+ mediaType: ImageMediaType
29
+ /** Exact encoded byte length. */
30
+ bytes: number
31
+ /** Intrinsic encoded width in pixels. */
32
+ width: number
33
+ /** Intrinsic encoded height in pixels. */
34
+ height: number
35
+ /** Optional display name stripped of local path information. */
36
+ name?: string
37
+ /**
38
+ * Input dimensions after applying EXIF orientation and before normalization
39
+ * scaling. Present only when normalization reduced the image.
40
+ */
41
+ originalDimensions?: {
42
+ width: number
43
+ height: number
44
+ }
45
+ }
46
+ ```
47
+
48
+ ```ts type-equiv
49
+ /** Deployment-resolved limits used by upload admission and request buffering. */
50
+ interface ImageAttachmentLimits {
51
+ maxImageBytes: number
52
+ maxImagesPerMessage: number
53
+ maxMessageImageBytes: number
54
+ maxImagePixels: number
55
+ /** Maximum intrinsic width and maximum intrinsic height in pixels for one image. */
56
+ maxImageDimension: number
57
+ mediaTypes: readonly ImageMediaType[]
58
+ }
59
+ ```
60
+
61
+ The local backend admits at most 20 images and 200 MiB of encoded source data per message. One source may use up to 20 MiB, 64,000,000 pixels, and 8192 pixels on either side. These source limits precede the independent normalization stage, which limits the long edge to 2048 pixels and encoded data to 4 MiB by default.
62
+
63
+ The reference records intrinsic dimensions and encoded length so clients can lay out history without decoding first, while every authoritative read still re-checks digest, media signature, dimensions, and metadata against the object.
64
+
65
+ ## Commit and verified-read payloads
66
+
67
+ ```ts type-equiv
68
+ /**
69
+ * Browser-submitted prompt content accepted by Host prompt endpoints; the
70
+ * accepting Host promotes image parts to durable references through
71
+ * `ctx.attachments.admitPromptContent()` before any message is created, so a wire caller can
72
+ * never cite an attachment it did not upload.
73
+ */
74
+ type PromptContentPart =
75
+ | { readonly type: 'text'; readonly text: string }
76
+ | {
77
+ readonly type: 'image'
78
+ readonly mediaType: ImageMediaType
79
+ readonly data: string
80
+ readonly name?: string
81
+ }
82
+ ```
83
+
84
+ ```ts type-equiv
85
+ /** Host prompt content whose file receipts are resolved and whose image bytes await admission. */
86
+ type AttachmentAdmissionPart =
87
+ | PromptContentPart
88
+ | { readonly type: 'file'; readonly attachment: FileAttachmentRef }
89
+ ```
90
+
91
+ ```ts type-equiv
92
+ /** Host-admitted prompt content with every attachment represented by its durable reference. */
93
+ type AdmittedPromptContentPart =
94
+ | { readonly type: 'text'; readonly text: string }
95
+ | { readonly type: 'image'; readonly attachment: ImageAttachmentRef }
96
+ | { readonly type: 'file'; readonly attachment: FileAttachmentRef }
97
+ ```
98
+
99
+ ```ts type-equiv
100
+ /** Base64-encoded image upload accompanying one wire request. */
101
+ interface EncodedImageAttachment {
102
+ /** Declared media type, verified against the decoded bytes during admission. */
103
+ mediaType: ImageMediaType
104
+ /** Canonical base64 encoding of the image bytes. */
105
+ data: string
106
+ /** Optional display name; it is never interpreted as a path. */
107
+ name?: string
108
+ }
109
+ ```
110
+
111
+ ```ts type-equiv
112
+ /** Request to validate and durably commit one image. */
113
+ interface SaveImageAttachment {
114
+ data: Uint8Array
115
+ /** Caller-declared media type, checked against fully decoded bytes. */
116
+ mediaType: ImageMediaType
117
+ /** Optional browser/provider display name; it is never interpreted as a path. */
118
+ name?: string
119
+ }
120
+ ```
121
+
122
+ ```ts type-equiv
123
+ /** Stored image bytes returned after reference and digest verification. */
124
+ interface StoredImageAttachment {
125
+ ref: ImageAttachmentRef
126
+ data: Uint8Array
127
+ }
128
+ ```
129
+
130
+ ```ts type-equiv
131
+ /** Deterministic request-image target selected by one exact model route for one attachment. */
132
+ interface ImageRequestTarget {
133
+ /** Target width in pixels; a target above the source keeps the source width. */
134
+ width: number
135
+ /** Target height in pixels; a target above the source keeps the source height. */
136
+ height: number
137
+ /** Encoded-byte target before base64 expansion or Files API upload; the smallest quality-ladder output is kept when no quality fits. */
138
+ maxBytes: number
139
+ }
140
+ ```
141
+
142
+ ```ts type-equiv
143
+ /** Integer width and height of one projected image. */
144
+ interface ProjectedDimensions {
145
+ width: number
146
+ height: number
147
+ }
148
+ ```
149
+
150
+ ```ts type-equiv
151
+ /** Cached request version derived from one provider-independent normalized attachment. */
152
+ interface RequestImageAttachment {
153
+ /** Cache and upload-index key over the attachment id, policy, and fixed encoder parameters. */
154
+ variantId: ImageVariantId
155
+ /** Durable normalized attachment from which this request version was derived. */
156
+ attachment: ImageAttachmentRef
157
+ /** Encoded request bytes. */
158
+ data: Uint8Array
159
+ mediaType: ImageMediaType
160
+ bytes: number
161
+ width: number
162
+ height: number
163
+ /** Provider-compatible sample depth proven after request encoding. */
164
+ depth: 'uchar'
165
+ /** Provider-compatible color space proven after request encoding. */
166
+ space: 'srgb'
167
+ /** Whether the encoded request version retains an alpha channel. */
168
+ hasAlpha: boolean
169
+ }
170
+ ```
171
+
172
+ `saveImage()` prepares and atomically commits a provider-independent normalized attachment before returning its `ImageAttachmentRef`. `saveImages()` prepares every validated attachment once before publishing the batch, so validation rejection leaves no partial objects and publication does not repeat decoding or quality selection. `admitPromptContent()` accepts the complete ordered Host prompt after file receipt resolution, replaces base64 image uploads with durable references, and passes durable file references unchanged. `admitEncodedImages()` supports other wire entries and delegates count, aggregate-byte, and ordered batch admission to `saveImages()`. `admitEncodedFile()` gives encoded protocol adapters the same service-owned canonical-base64 admission, and `isAttachmentError()` lets those adapters recognize stable attachment failures without importing implementation helpers. `readImage()` verifies a normalized attachment from an authorized session path. `imageHostPath()` exposes only the provider-owned host object location; it does not decide whether the current tool execution world can read it. `readImageRequest()` derives and caches one deterministic request version at an exact route-chosen target size and encoded-byte target. That version contains encoded bytes and metadata but no execution-world path. New entries are fully decoded before publication, while cache hits use a bounded metadata probe. Callers use `Promise.all` over the singular method when they need an ordered batch. The local implementation lazily encodes preferred candidates, singleflights equal request identities, lets each waiter cancel independently, stops shared work when no waiter remains, and bounds all transforms with its instance-level limiter, which defaults to two simultaneous transformations. The service is retention-neutral: resumed and forked sessions may share objects, so reference-aware garbage collection is deferred rather than tied to one session's deletion.
173
+
174
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
175
+
176
+ <a id="cordis-surface"></a>
177
+
178
+ ## Cordis API
179
+
180
+ 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).
181
+
182
+ <a id="ctxattachments--attachmentstore-abstract-seam"></a>
183
+
184
+ ### `ctx.attachments` - `AttachmentStore` (abstract seam)
185
+
186
+ Immutable binary attachment service. Implementations validate bytes before publishing a reference.
187
+
188
+ ```ts cordis-catalog
189
+ /**
190
+ * Validate one image without persisting it.
191
+ * Batch callers validate every member before saving any member.
192
+ * @param input - encoded bytes, declared media type, and optional display name.
193
+ * @returns completion after the encoded raster has been fully decoded.
194
+ */
195
+ abstract validateImage(input: SaveImageAttachment): Promise<void>
196
+
197
+ /**
198
+ * Validate and durably commit one ordered image batch.
199
+ * @param inputs - encoded images in owning-message order.
200
+ * @returns durable normalized attachment references in the same order after every member succeeds.
201
+ */
202
+ async saveImages(inputs: readonly SaveImageAttachment[]): Promise<readonly ImageAttachmentRef[]>
203
+
204
+ /**
205
+ * Admit one Host prompt and replace each uploaded image with its durable reference.
206
+ * Text and durable file references pass through unchanged. A prompt without image parts performs no storage operation.
207
+ * @param content - prompt parts in message order after file receipt resolution.
208
+ * @returns admitted prompt parts in the same order as `content`.
209
+ * @throws AttachmentError when the image batch is refused.
210
+ */
211
+ async admitPromptContent( content: readonly AttachmentAdmissionPart[], ): Promise<AdmittedPromptContentPart[]>
212
+
213
+ /**
214
+ * Decode and durably commit one canonical base64 file upload.
215
+ * @param input - canonical base64 bytes and optional display name.
216
+ * @returns the durable content-addressed file reference.
217
+ * @throws AttachmentError when the encoding or storage operation is refused.
218
+ */
219
+ admitEncodedFile(input: EncodedFileAttachment): Promise<FileAttachmentRef>
220
+
221
+ /**
222
+ * Identify a failure emitted by this attachment capability by its stable code.
223
+ * @param error - value caught from an attachment operation.
224
+ * @returns whether the value is an attachment failure.
225
+ */
226
+ isAttachmentError(error: unknown): error is AttachmentError
227
+
228
+ /**
229
+ * Validate and durably commit one image before its owning session event is appended.
230
+ * The returned reference describes the persisted normalized image. When
231
+ * normalization reduces the raster, its `originalDimensions` records the
232
+ * orientation-applied input dimensions.
233
+ * @param input - encoded bytes, declared media type, and optional display name.
234
+ * @returns the durable content-addressed normalized image reference.
235
+ */
236
+ abstract saveImage(input: SaveImageAttachment): Promise<ImageAttachmentRef>
237
+
238
+ /**
239
+ * Read one image and verify that bytes still match the recorded reference.
240
+ * @param ref - durable reference from the session log.
241
+ * @param signal - optional cancellation for backend read and verification work.
242
+ * @returns the verified bytes and normalized attachment reference.
243
+ * @throws the signal reason when aborted, or a storage error when verification fails.
244
+ */
245
+ abstract readImage(ref: ImageAttachmentRef, signal?: AbortSignal): Promise<StoredImageAttachment>
246
+
247
+ /**
248
+ * Locate the provider-owned normalized object in the harness host filesystem.
249
+ * @param ref - durable normalized attachment reference.
250
+ * @returns an absolute host path, or undefined when this backend is not host-file-backed.
251
+ * @throws an AttachmentError when the durable reference is invalid.
252
+ */
253
+ imageHostPath(ref: ImageAttachmentRef): string | undefined
254
+
255
+ /**
256
+ * Durably commit one file byte-for-byte before its owning session event is
257
+ * appended. Files carry no admission limits: any byte content and length is
258
+ * accepted, and the stored object is the exact submitted bytes. Backends
259
+ * without verbatim file storage keep this default rejection.
260
+ * @param input - exact bytes and optional display name.
261
+ * @returns the durable content-addressed file reference.
262
+ */
263
+ saveFile(input: SaveFileAttachment): Promise<FileAttachmentRef>
264
+
265
+ /**
266
+ * Durably commit one file byte-for-byte from bounded chunks. Providers must
267
+ * apply backpressure and must not collect the complete file in memory.
268
+ * Backends without streamed verbatim storage keep this default rejection.
269
+ * @param input - ordered exact bytes, optional cancellation, and display name.
270
+ * @returns the durable content-addressed file reference.
271
+ */
272
+ saveFileStream(input: SaveFileStreamAttachment): Promise<FileAttachmentRef>
273
+
274
+ /**
275
+ * Read and verify one verbatim stored file as bounded chunks. Providers must
276
+ * not collect the complete file in memory. Backends without verbatim file
277
+ * reads keep this default rejection.
278
+ * @param ref - durable reference from the session log.
279
+ * @param signal - optional cancellation for backend reads and verification work.
280
+ * @returns exact file bytes in order; integrity failures reject the iteration.
281
+ */
282
+ async *readFileStream( ref: FileAttachmentRef, signal?: AbortSignal, ): AsyncIterable<Uint8Array>
283
+
284
+ /**
285
+ * Locate the verbatim stored file object in the harness host filesystem.
286
+ * @param ref - durable file reference.
287
+ * @returns an absolute host path, or undefined when this backend is not host-file-backed.
288
+ * @throws an AttachmentError when the durable reference is invalid.
289
+ */
290
+ fileHostPath(ref: FileAttachmentRef): string | undefined
291
+
292
+ /**
293
+ * Generate or read one deterministic model-request version from the stored normalized image.
294
+ * @param ref - durable provider-independent normalized attachment reference.
295
+ * @param target - route-chosen dimensions and byte target; an unmet byte target yields the smallest ladder output.
296
+ * @param signal - optional cancellation.
297
+ * @returns request bytes and the cache/upload identity covering every transform input.
298
+ */
299
+ readImageRequest( ref: ImageAttachmentRef, target: ImageRequestTarget, signal?: AbortSignal, ): Promise<RequestImageAttachment>
300
+ ```
301
+
302
+ Source: [`packages/attachment/attachment/src/index.ts`](../../packages/attachment/attachment/src/index.ts)
303
+
304
+ <a id="ctxfileuploads--fileuploads"></a>
305
+
306
+ ### `ctx.fileUploads` - `FileUploads`
307
+
308
+ Host service owning upload storage and Agent-scoped staged receipts.
309
+
310
+ ```ts cordis-catalog
311
+ /**
312
+ * Register the ordinary-Session resolver used when a raw upload addresses a cold Session.
313
+ * @param resolve - resolver that returns the exact live Agent or throws a Remote error.
314
+ * @returns disposer removing this resolver.
315
+ */
316
+ registerAgentResolver(resolve: AgentResolver): () => void
317
+
318
+ /**
319
+ * Persist one encoded upload and stage it under the Agent receiver selected by Typert.
320
+ * @param agent - receiving Agent resolved from the Remote Agent scope.
321
+ * @param request - canonical base64 bytes and optional display name.
322
+ * @param signal - caller cancellation before storage begins.
323
+ * @returns the staged receipt and durable file reference.
324
+ */
325
+ @Remote('upload') upload(agent: Agent, request: EncodedFileUploadRequest, signal: AbortSignal): Promise<FileUploadValue>
326
+
327
+ /**
328
+ * Persist raw chunks for one Session without aggregating the upload.
329
+ * @param request - Session identity, ordered bytes, cancellation, and optional display name.
330
+ * @returns the staged receipt and durable file reference.
331
+ */
332
+ async uploadStream(request: { readonly sessionId: SessionId readonly data: AsyncIterable<Uint8Array> readonly signal?: AbortSignal readonly name?: string }): Promise<FileUploadValue>
333
+
334
+ /**
335
+ * Resolve one staged receipt inside its receiving Agent scope.
336
+ * @param agent - receiving Agent.
337
+ * @param receiptId - opaque receipt minted for one completed upload.
338
+ * @returns durable file reference, or `undefined` for an unknown or foreign receipt.
339
+ */
340
+ resolve(agent: Agent, receiptId: FileUploadReceiptId): FileAttachmentRef | undefined
341
+
342
+ /**
343
+ * Bind receipts while one prompt enters an Agent inbox.
344
+ * Disposal restores every prior binding unless the caller commits successful delivery.
345
+ * @param agent - receiving Agent.
346
+ * @param receiptIds - distinct staged receipts referenced by the prompt.
347
+ * @param requestId - prompt identity later observed in queue or history.
348
+ * @returns binding kept after commit until queue or history observation retires its receipts.
349
+ */
350
+ bindPrompt( agent: Agent, receiptIds: readonly FileUploadReceiptId[], requestId: string, ): PromptFileBinding
351
+
352
+ /**
353
+ * Retire every receipt accepted by one removed queue occurrence.
354
+ * @param agent - receiving Agent.
355
+ * @param requestId - prompt identity carried by the queue occurrence.
356
+ */
357
+ retirePrompt(agent: Agent, requestId: string): void
358
+ ```
359
+
360
+ Types: [Agent](core.md) · [SessionId](core.md)
361
+
362
+ Source: [`packages/client/file-upload/src/index.ts`](../../packages/client/file-upload/src/index.ts)
363
+ <!-- END GENERATED cordis-surface -->