@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,501 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/jobs.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Background Job Runtime
4
+
5
+ English | [中文](jobs.zh.md)
6
+
7
+ Types shared by long-running producers, `ctx.jobs`, and job controls. The [seam consolidation Agent Note](../../.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.md) owns the current design and the [runtime Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) its origin; this page records the exact fields and variants from [`packages/jobs/jobs/src/types.ts`](../../packages/jobs/jobs/src/types.ts) and the client-safe [`view.ts`](../../packages/jobs/jobs/src/view.ts) leaf.
8
+
9
+ ## Ids and status
10
+
11
+ `JobId` is a [branded id](core.md#branded-ids) generated as `<kind>-N`. Access control relies on owner authorization, not id secrecy. `JobKind` derives from a merge-extensible map; the registry treats kinds as opaque id namespaces.
12
+
13
+ ```ts type-equiv
14
+ /**
15
+ * Producer-defined job kinds. Plugins extend this map by declaration merging;
16
+ * the registry treats every value as an opaque id namespace.
17
+ */
18
+ interface JobKindMap {
19
+ bash: 'bash'
20
+ subagent: 'subagent'
21
+ }
22
+ ```
23
+
24
+ `JobStatus` is `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`; producer-specific facts belong in `JobView.progress` while the job runs and in `JobView.detail` once it settled.
25
+
26
+ ## Producer contract
27
+
28
+ A `JobSpec` declares identity, the owning session, optional pull `output` sources, and a starter. The runtime finishes preflight before calling `run()` with the job's `JobHandle` and commits without a later failable step. Producers own execution resources; the runtime owns identity, access, lifecycle state, and the output ring.
29
+
30
+ ```ts type-equiv
31
+ /**
32
+ * Producer declaration passed to {@link JobRegistry.start}. The runtime
33
+ * preflights access and cleanup before invoking {@link run}; the producer owns
34
+ * execution resources while the runtime owns identity, lifecycle state, and
35
+ * the output ring.
36
+ */
37
+ interface JobSpec {
38
+ /** Producer kind - also the id prefix (`bash`, `subagent`, …). */
39
+ kind: JobKind
40
+ /** One-line model-facing label (the command; the delegation description). */
41
+ label: string
42
+ /**
43
+ * Owning session. Access is fenced by it, and the owner's live Agent must be
44
+ * the one currently registered under that id: its disposal cancels and
45
+ * awaits the job. Omitting the owner creates an unowned job, open to any
46
+ * caller until service disposal.
47
+ */
48
+ owner?: SessionId
49
+ /**
50
+ * Optional UTF-8 byte cap for each complete model-facing completion notice or
51
+ * output read, including controller status metadata. Independent of ring
52
+ * retention: it bounds the consuming model surface, never observers.
53
+ */
54
+ outputLimitBytes?: number
55
+ /**
56
+ * Pull sources the registry pumps into the ring at its own cadence.
57
+ * Producers that narrate their own progress use {@link JobHandle.append}
58
+ * instead; a job may use both.
59
+ */
60
+ output?: readonly JobOutputSource[]
61
+ /**
62
+ * Start the work after preflight and synchronously return its hooks. Called
63
+ * once with the job's producer face; a throw leaves nothing registered (the
64
+ * spent ordinal is skipped), and the producer must clean up any partially
65
+ * started resources.
66
+ * @param job - the issued id plus the ring append and progress writers.
67
+ */
68
+ run(job: JobHandle): JobHooks
69
+ }
70
+ ```
71
+
72
+ ```ts type-equiv
73
+ /**
74
+ * Producer face of one registered job, handed to {@link JobSpec.run} and
75
+ * valid for the job's whole life. All methods are synchronous. Writes staged
76
+ * inside the starter call are retained and become visible with the
77
+ * registration commit; after settlement - the producer's own outcome, a kill,
78
+ * or a registry-forced teardown end - writes log and drop instead of
79
+ * throwing, so a producer's trailing flush cannot break its own teardown path.
80
+ */
81
+ interface JobHandle {
82
+ /** The registry-issued id (`<kind>-N`). */
83
+ readonly id: JobId
84
+ /**
85
+ * Append one chunk to the output ring. Offsets advance by the chunk's UTF-8
86
+ * byte length; an empty chunk is dropped without waking observers.
87
+ * @param text - the chunk text, exactly as produced.
88
+ * @param options - stream label and gap marker.
89
+ */
90
+ append(text: string, options?: JobAppendOptions): void
91
+ /**
92
+ * Replace the live progress line (`3/10`, the current phase). Settlement
93
+ * clears it; the terminal reason travels in {@link JobOutcome.detail}.
94
+ * @param line - the new progress line.
95
+ */
96
+ updateProgress(line: string): void
97
+ }
98
+ ```
99
+
100
+ `JobHooks.done` resolves after the producer releases its resources, not merely when work finishes. A job whose result is a value rather than a stream - a subagent's report, a workflow's rendered result - returns it as `JobOutcome.result`; the model's first read after settlement carries it once.
101
+
102
+ ```ts type-equiv
103
+ /** Hooks through which the runtime controls and observes producer work. */
104
+ interface JobHooks {
105
+ /**
106
+ * Request termination. Must be synchronous, idempotent, and eventually settle
107
+ * {@link done}; throws propagate. The optional reason is forwarded verbatim.
108
+ */
109
+ cancel(reason?: string): void
110
+ /**
111
+ * Resolves after the producer releases its resources, not merely when work
112
+ * finishes. Must not reject; the runtime converts a rejection to `failed`.
113
+ * If teardown cancellation throws, the runtime may force-fail only the
114
+ * registry record without claiming that the work stopped.
115
+ */
116
+ done: Promise<JobOutcome>
117
+ }
118
+ ```
119
+
120
+ ```ts type-equiv
121
+ /** Terminal result supplied by a producer through {@link JobHooks.done}. */
122
+ interface JobOutcome {
123
+ /** How the job ended: finished (`completed`), cancelled (`killed`), or broke (`failed`). */
124
+ status: 'completed' | 'killed' | 'failed'
125
+ /**
126
+ * Terminal reason rendered into status lines (`exit code: 3`, `max-tokens`).
127
+ * When the job settles `killed` after a {@link JobRegistry.kill} with a
128
+ * reason, the registry appends that reason.
129
+ */
130
+ detail?: string
131
+ /**
132
+ * Return value for jobs whose result is a value rather than a stream (a
133
+ * workflow's rendered result, a subagent's report). The output ring carries
134
+ * the stream; this is handed out once by the model's next {@link JobRegistry.read}.
135
+ */
136
+ result?: string
137
+ }
138
+ ```
139
+
140
+ A pull source hands the registry a non-consuming offset reader - the subprocess `readFrom` family. The registry pumps every source at its own cadence (`pumpPollMs` on `dsh-jobs-local`) and drains it once more before settlement closes the ring, so producers fold nothing into `done`.
141
+
142
+ ```ts type-equiv
143
+ /**
144
+ * A pull source the registry pumps into the job's output ring - the subprocess
145
+ * `readFrom` family. The registry owns the cadence and drains every source one
146
+ * last time before settlement closes the ring, so a producer folds nothing
147
+ * into its `done`.
148
+ */
149
+ interface JobOutputSource {
150
+ /** Stream label attached to every chunk this source yields. */
151
+ channel?: JobChannel
152
+ /**
153
+ * Read everything captured since `fromByte` without consuming it.
154
+ * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 first).
155
+ * @returns the delta text, the next offset, the lossy flag, and the spill path the source currently keeps.
156
+ */
157
+ read(fromByte: number): JobSourceRead
158
+ }
159
+ ```
160
+
161
+ ```ts type-equiv
162
+ /** One incremental read from a {@link JobOutputSource}. */
163
+ interface JobSourceRead {
164
+ /** Text captured since the requested offset (the whole retained tail when lossy). */
165
+ text: string
166
+ /** Whole-stream offset to resume from on the next read. */
167
+ nextOffset: number
168
+ /** True when the requested offset slid out of the source's retained window. */
169
+ lossy: boolean
170
+ /**
171
+ * Host path of a file holding the complete stream, when the source
172
+ * currently keeps an intact one. Reported on every read, so the registry
173
+ * tracks it as source metadata: a later read without it withdraws the file.
174
+ */
175
+ spillPath?: string
176
+ }
177
+ ```
178
+
179
+ ## The output ring
180
+
181
+ Every job owns one bounded ring. Pull sources are pumped into it and `JobHandle.append` pushes land whole; the model consumes the ring through a registry-kept cursor (`JobRegistry.read`), any number of observers read it at absolute byte offsets (`JobRegistry.readAt`), and neither disturbs the other. `JobChannel` labels `stdout`, `stderr`, and `log`; `log` is producer narration that reaches observers only, never the model's consuming read. Settlement ends the stream and trims retention to the settled cap - the ring has no separate lifecycle. The spill file a pull source keeps is job metadata (`JobView.output.spillPaths`, refreshed by every pump read), not per-chunk metadata, so the model's dropped-output notice names it after the ring evicted the bytes and even after the gap chunk itself is gone. Browsers reach the roster and the ring through `job.list` and `job.follow`, the Remote streams of [`dsh-api-job-controller`](../../packages/api/job-controller/README.md), whose frames are listed under its Cordis API section below.
182
+
183
+ ```ts type-equiv
184
+ /** One chunk of a job's output ring: absolute offset, text, channel, and loss marker. */
185
+ interface JobChunk {
186
+ /** Absolute offset of the chunk's first byte; offsets never move once assigned. */
187
+ readonly at: number
188
+ /** Chunk text exactly as appended (possibly tail-trimmed by retention). */
189
+ readonly text: string
190
+ /** Stream label, when the producer supplied one. */
191
+ readonly channel?: JobChannel
192
+ /** Bytes immediately before this chunk were lost, at the producer or to retention. */
193
+ readonly gapBefore?: true
194
+ }
195
+ ```
196
+
197
+ ```ts type-equiv
198
+ /** Result of one non-consuming {@link JobRegistry.readAt}. */
199
+ interface JobOutputRead {
200
+ /** Retained chunks overlapping `[from, total)`, in offset order. */
201
+ chunks: readonly JobChunk[]
202
+ /**
203
+ * Offset to resume from - the ring's current `total`. Always a chunk
204
+ * boundary: appends land whole and trimming only advances chunk starts, and
205
+ * consumers concatenate `chunks` under that assumption, so a provider
206
+ * serving partial chunks would silently duplicate text.
207
+ */
208
+ next: number
209
+ /** True when `from` fell below the oldest retained byte, so bytes are missing before `chunks`. */
210
+ lossy: boolean
211
+ }
212
+ ```
213
+
214
+ ## Consumer views
215
+
216
+ `JobView` is the one projection every reader consumes: the model tools, the browser roster, and the observation stream. `owner` carries the session id that fences access; the registry resolves the live `Agent` behind it for lifecycle cleanup and never hands the object out. `progress` is the producer's live line and is cleared at settlement; `detail` is the terminal reason, with a recorded kill reason merged in.
217
+
218
+ ```ts type-equiv
219
+ /**
220
+ * Read-only projection of one job - a fresh object per call, never live
221
+ * registry state. The model tools, the browser roster, and the observation
222
+ * stream all consume this one shape.
223
+ */
224
+ interface JobView {
225
+ /** The registry-issued id (`<kind>-N`). */
226
+ readonly id: JobId
227
+ /**
228
+ * The producer kind the job was registered with: a Host-registered
229
+ * `JobKind`, carried as an open string because a browser bundle or a Remote
230
+ * codec sees only the `JobKindMap` merges its own program compiles.
231
+ */
232
+ readonly kind: string
233
+ /** The producer-supplied one-line label. */
234
+ readonly label: string
235
+ /** Owning session; absent for an unowned job, which every caller can see. */
236
+ readonly owner?: SessionId
237
+ /** Producer-owned cap for complete model-facing notices and reads, in UTF-8 bytes. */
238
+ readonly outputLimitBytes?: number
239
+ /** Current lifecycle state. */
240
+ readonly status: JobStatus
241
+ /** The producer's live progress line (`3/10`, the current phase); cleared at settlement. */
242
+ readonly progress?: string
243
+ /** Terminal reason (`exit code: 3`); a recorded kill reason is merged in. */
244
+ readonly detail?: string
245
+ /** Epoch ms when the job was registered. */
246
+ readonly startedAt: number
247
+ /** Epoch ms when the job settled; absent while live. */
248
+ readonly finishedAt?: number
249
+ /**
250
+ * The output ring's absolute coordinates and the complete-stream files
251
+ * behind it. `total` is the offset the next chunk starts at (0 while
252
+ * nothing was written); `earliest` is the oldest retained byte, greater
253
+ * than zero exactly when retention dropped the head. `spillPaths` lists the
254
+ * spill files the job's pull sources currently keep, in source order and
255
+ * deduplicated, and is absent while no source keeps one: it outlives any
256
+ * chunk, so a reader below `earliest` can still name where the bytes went.
257
+ */
258
+ readonly output: { readonly total: number; readonly earliest: number; readonly spillPaths?: readonly string[] }
259
+ }
260
+ ```
261
+
262
+ `JobRegistry.list`, `get`, `read`, `readAt`, `kill`, and `wait` each accept the caller’s `SessionId`; omitting it permits only unowned jobs, while a session may also access its own jobs.
263
+
264
+ ```ts type-equiv
265
+ /** Output and post-read state returned by the consuming {@link JobRegistry.read}. */
266
+ interface JobRead {
267
+ /** Ring chunks appended since the model cursor, in offset order; every channel included. */
268
+ chunks: readonly JobChunk[]
269
+ /** True when the cursor fell below the oldest retained byte, so bytes are missing before `chunks`. */
270
+ lossy: boolean
271
+ /** The producer's {@link JobOutcome.result}, handed out by the first read after settlement only. */
272
+ result?: string
273
+ /** The job's state at read time. */
274
+ job: JobView
275
+ }
276
+ ```
277
+
278
+ ## Events
279
+
280
+ The registry announces every commit through one filtered stream. Lifecycle events carry the projection after the commit they announce; `settled` names its cause so a completion reporter can skip a teardown; `output` carries only the id and the new total, so observers read from their own cursor and the registry never pushes payloads.
281
+
282
+ ```ts type-equiv
283
+ /**
284
+ * One lifecycle or output event. Lifecycle events carry the job's projection
285
+ * after the commit they announce; `output` carries only the id and the new
286
+ * total, so an observer schedules a {@link JobRegistry.readAt} from its own
287
+ * cursor and the registry never pushes payloads.
288
+ */
289
+ type JobEvent =
290
+ | {
291
+ /** Registration commit, progress line change, stopping transition, or removal from the visible set. */
292
+ readonly type: 'registered' | 'progress' | 'stopping' | 'removed'
293
+ readonly job: JobView
294
+ }
295
+ | {
296
+ readonly type: 'settled'
297
+ readonly job: JobView
298
+ readonly cause: JobSettleCause
299
+ /**
300
+ * Whether this settlement released a live {@link JobRegistry.wait}. That
301
+ * waiter's caller receives the terminal projection as its own result, so
302
+ * a completion reporter treats an awaited settlement as already delivered
303
+ * and reports only the unawaited ones. A wait that timed out or was
304
+ * aborted before the settlement does not count.
305
+ */
306
+ readonly awaited: boolean
307
+ }
308
+ | {
309
+ readonly type: 'output'
310
+ readonly id: JobId
311
+ /** Owning session, absent for an unowned job. */
312
+ readonly owner?: SessionId
313
+ /** The ring's total after the append (or at settlement, which ends the stream). */
314
+ readonly total: number
315
+ }
316
+ ```
317
+
318
+ ```ts type-equiv
319
+ /**
320
+ * Who a subscription hears about. `{ owner }` delivers that session's jobs
321
+ * plus every unowned job (the set that session can see). `{ owners: 'scope' }`
322
+ * delivers the owners composed under the subscribing context - one registry
323
+ * serves every composition in the process, and a mount under one preset must
324
+ * not hear another preset's agents. `{ owners: 'all' }` delivers everything.
325
+ */
326
+ type JobEventFilter =
327
+ | { readonly owner: SessionId }
328
+ | { readonly owners: 'all' | 'scope' }
329
+ ```
330
+
331
+ ## Service behavior
332
+
333
+ The abstract [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition specifies atomic `start`, caller-scoped `list`, `get`, consuming `read`, non-consuming `readAt`, `kill`, and bounded `wait`, the filtered `events` stream, and `attachController`; [`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) is the process-local Service Provider. Authorization compares owner sessions; owner cleanup and admission use the live `Agent` registered under the owner session when the job starts. The local provider's positive-safe-integer `maxConcurrentJobsPerOwner` config defaults to `10` and counts `running` plus `stopping` records per exact owner, with one shared bucket for unowned jobs; terminal producer settlement releases capacity; `retainBytes` (default 262144) and `settledRetainBytes` (default 16384) bound each ring's live and settled retention, and `pumpPollMs` (default 150) is the pull cadence. See [`dsh-jobs`](../../packages/jobs/jobs/README.md) for the Service Definition contract, [`dsh-jobs-local`](../../packages/jobs/jobs-local/README.md) for the registry lifecycle and admission policy, and [`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.md) for the model-facing Consumer.
334
+
335
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
336
+
337
+ <a id="cordis-surface"></a>
338
+
339
+ ## Cordis API
340
+
341
+ 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).
342
+
343
+ <a id="ctxjobcontroller--jobcontroller"></a>
344
+
345
+ ### `ctx.jobController` - `JobController`
346
+
347
+ Host service backing the generated `ctx.remote.job` namespace.
348
+
349
+ ```ts cordis-catalog
350
+ /**
351
+ * Stream the jobs one session can see - its own plus every unowned job -
352
+ * as whole-set frames: one on open, then one after each coalesced burst of
353
+ * lifecycle commits. The stream has no natural end; the carrier closes it.
354
+ * @param request - the session whose visible set to mirror.
355
+ * @param signal - cancellation owned by the Remote stream carrier.
356
+ * @returns the roster frames.
357
+ */
358
+ @Remote({ mode: 'stream' }) list(request: JobListRequest, signal: AbortSignal): AsyncIterable<JobListFrame>
359
+
360
+ /**
361
+ * Stream one job's retained output from an absolute byte offset, then its
362
+ * terminal projection once settled and drained. Non-consuming: the
363
+ * model-facing cursor and notice state never observe these reads. The
364
+ * request's session is the fenced read's caller; the registry rejects a
365
+ * job the session cannot see and an unknown job.
366
+ * @param request - target job, owning session, and optional resume offset.
367
+ * @param signal - cancellation owned by the Remote stream carrier.
368
+ * @returns anchor, coalesced output frames, and the terminal status.
369
+ */
370
+ @Remote({ mode: 'stream' }) follow(request: JobFollowRequest, signal: AbortSignal): AsyncIterable<JobFollowFrame>
371
+
372
+ /**
373
+ * Kill one background job on a human's behalf. The request's session is
374
+ * the fenced read's caller, so the job must be one that session can see:
375
+ * the registry's owner fence is the only access rule, and a child session's
376
+ * own jobs are killable from its list like any other. The kill records
377
+ * `cancelled by the user` as its reason; it is not one the model requested,
378
+ * so the owning agent still receives the completion notice, and a shell
379
+ * tool waiting on that job reads the reason in its own result.
380
+ * @param request - Session whose job list carries the job, and the job id.
381
+ * @returns the registry's admission of the kill request.
382
+ */
383
+ @Remote('kill') kill(request: JobKillRequest): JobKillValue
384
+ ```
385
+
386
+ Source: [`packages/api/job-controller/src/index.ts`](../../packages/api/job-controller/src/index.ts)
387
+
388
+ <a id="ctxjobs--jobregistry-abstract-seam"></a>
389
+
390
+ ### `ctx.jobs` - `JobRegistry` (abstract seam)
391
+
392
+ Abstract background job registry. Subclass, implement the abstract members, and load the subclass as a plugin - it registers as `ctx.jobs` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
393
+
394
+ Implementations must honor these semantics:
395
+
396
+ - Registrations outlive producer and controller fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record. Such settlements announce `cause: 'teardown'`, because a job whose owner is being destroyed has no reader left.
397
+ - Owned-job access is fenced by the owner's session id. Ids are predictable, so authorization - not secrecy - is the boundary.
398
+ - Settlement is first-wins: one terminal record, released waiters, then one round of contained event delivery, even against a late producer outcome. The `settled` event follows every released waiter and reports whether it released one (`awaited`), so a completion reporter can skip settlements a waiting caller already collected.
399
+ - A settled record stays listed until its owner's disposal, service disposal, or an explicit remove by a caller that collected the terminal state itself and never handed the id out.
400
+ - start refuses work while no attached job controller serves the spec's owner, so a producer cannot start work that owner cannot collect or stop. One registry serves every composition in the process, so this question - and event delivery under `{ owners: 'scope' }` - is owner-relative rather than process-wide: registrations made from an unscoped context serve every owner, and registrations made under an agent composition's scope serve exactly the agents composed under it.
401
+ - Every job owns one output ring. Pull sources named by the spec are pumped by the registry and drained once more before settlement; pushed appends land whole. The model's consuming cursor and observers' absolute offsets read the same bytes and never disturb each other.
402
+ - Ring retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement trims retention to the settled cap and ends the stream; the ring has no separate lifecycle.
403
+
404
+ ```ts cordis-catalog
405
+ /**
406
+ * Preflight access, validation, owner cleanup, and implementation-owned
407
+ * admission before starting and atomically registering work. Any preflight
408
+ * rejection leaves no job id or execution resource. A throwing starter
409
+ * leaves nothing registered; after it returns, registration cannot fail.
410
+ * @param spec - job identity, owner, output sources, and synchronous starter.
411
+ * @returns the registry-issued `<kind>-N` id.
412
+ */
413
+ abstract start(spec: JobSpec): JobId
414
+
415
+ /**
416
+ * List caller-owned and unowned jobs in registration order.
417
+ * @param caller - reading session; omission sees only unowned jobs.
418
+ * @returns fresh projections.
419
+ */
420
+ abstract list(caller?: SessionId): JobView[]
421
+
422
+ /**
423
+ * Project one job without changing its cursor. Throws for an unknown or
424
+ * foreign job.
425
+ * @param id - job to look up.
426
+ * @param caller - reading session checked against the owner.
427
+ * @returns a fresh projection.
428
+ */
429
+ abstract get(id: JobId, caller?: SessionId): JobView
430
+
431
+ /**
432
+ * Consume the ring from the model cursor and advance it to the current
433
+ * total. After settlement the first read also carries the producer's
434
+ * result. Throws for an unknown or foreign job.
435
+ * @param id - job to read.
436
+ * @param caller - reading session checked against the owner.
437
+ * @returns the chunks since the cursor, the lossy flag, the result once, and the post-read projection.
438
+ */
439
+ abstract read(id: JobId, caller?: SessionId): JobRead
440
+
441
+ /**
442
+ * Read retained ring output without moving the model cursor. Resume with
443
+ * a previous read's `next`; an offset inside a retained chunk returns the
444
+ * whole chunk (its `at` may precede `from`). Throws for a negative or
445
+ * non-integer offset, or an unknown or foreign job.
446
+ * @param id - job to read.
447
+ * @param from - absolute byte offset to read from (0 for the retained head).
448
+ * @param caller - reading session checked against the owner.
449
+ * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag.
450
+ */
451
+ abstract readAt(id: JobId, from: number, caller?: SessionId): JobOutputRead
452
+
453
+ /**
454
+ * Request cancellation, then mark the job stopping. A producer throw
455
+ * propagates without changing job state. A supplied reason is merged into
456
+ * terminal `detail` when the job settles `killed`. Throws for an unknown
457
+ * or foreign job.
458
+ * @param id - job to cancel.
459
+ * @param caller - killing session checked against the owner.
460
+ * @param reason - cancellation reason forwarded verbatim to the producer.
461
+ * @returns `requested` for live work, otherwise `already-finished`.
462
+ */
463
+ abstract kill(id: JobId, caller?: SessionId, reason?: string): 'requested' | 'already-finished'
464
+
465
+ /**
466
+ * Wait for settlement or timeout without cancelling the job. Caller abort
467
+ * rejects only while the job is live; after settlement the terminal
468
+ * projection wins. Rejects for an invalid timeout or an unknown or foreign
469
+ * job.
470
+ * @param id - job to wait for.
471
+ * @param timeoutMs - positive finite wait bound in milliseconds.
472
+ * @param caller - waiting session checked against the owner.
473
+ * @param signal - optional cancellation of the wait itself.
474
+ * @returns projection at settlement or timeout.
475
+ */
476
+ abstract wait(id: JobId, timeoutMs: number, caller?: SessionId, signal?: AbortSignal): Promise<JobView>
477
+
478
+ /**
479
+ * Drop one settled job's record from the visible set and announce
480
+ * `removed`. For a caller that collected the terminal state through its own
481
+ * {@link wait} and never handed the id to the model, such as a shell tool's
482
+ * foreground call. Throws for a job that is still live, unknown, or foreign.
483
+ * @param id - settled job to drop.
484
+ * @param caller - removing session checked against the owner.
485
+ */
486
+ abstract remove(id: JobId, caller?: SessionId): void
487
+
488
+ /**
489
+ * Attach an effect-scoped controller that can read and stop jobs. It serves the
490
+ * owners its registering context's scope covers, and {@link start} refuses an
491
+ * owner no attached controller serves.
492
+ * @param name - diagnostic label; duplicate names remain independent.
493
+ * @returns disposer that detaches this controller.
494
+ */
495
+ abstract attachController(name: string): () => void
496
+ ```
497
+
498
+ Types: [SessionId](core.md)
499
+
500
+ Source: [`packages/jobs/jobs/src/index.ts`](../../packages/jobs/jobs/src/index.ts)
501
+ <!-- END GENERATED cordis-surface -->