@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,1107 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/core.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Core
4
+
5
+ English | [中文](core.zh.md)
6
+
7
+ The **core** subsystem is [`packages/core`](../../packages/core/README.md) - the packages every composition boots: the event-sourced session log, system-prompt assembly, the tool registry, the agent types, and the concrete loop that drives them. This page explains what the `agent`/`agent-loop` pair declares - how an agent is created and owned, and the `Agent` handle's delivery, cancellation, and interception contracts - plus the two type patterns every subsystem follows. The group's dedicated pages and the rest of the folder are indexed in the [subsystems README](README.md).
8
+
9
+ ## The spine, package by package
10
+
11
+ A turn flows through the six packages in one loop: the driver in [`agent-loop`](../../packages/core/agent-loop) claims a queued prompt, opens a turn on the [session log](session.md) (`ctx.sessions`), assembles the request prefix through [system-prompt](system-prompt.md) (`ctx.systemPrompt`) and derives history from the log, streams the model response through the [LLM seam](llm-streaming.md), dispatches tool calls through the [tool registry](tools.md) (`ctx.tools`), and appends every model-visible fact back onto the log before the next step derives from it. The conversation vocabulary the loop moves - `Message`, `ContentBlock`, `StreamChunk`, the model request - is declared by [`packages/llm`](../../packages/llm/README.md) and documented on [llm-streaming.md](llm-streaming.md).
12
+
13
+ | Package | Owns | Page |
14
+ |---|---|---|
15
+ | `session/` | The append-only `SessionEvent` log and in-memory store - the single source of truth (`ctx.sessions`) | [session.md](session.md) |
16
+ | `system-prompt/` | Prompt-section and tool-schema assembly (`ctx.systemPrompt`) | [system-prompt.md](system-prompt.md) |
17
+ | `tools/` | The scoped tool registry and guarded execution pipeline (`ctx.tools`) | [tools.md](tools.md) |
18
+ | `agent/` | The `Agent` interface, live registry, initiator scope, and `agent/*` event vocabulary (`ctx.agents`) | this page |
19
+ | `agent-loop/` | The concrete driver implementing the public `Agent` contract (`ctx.agentLoop`) | this page |
20
+ | `scope/` | The scoped-registration primitive the registries and loop build per-agent scoping on | [scope.md](scope.md) |
21
+
22
+ `scope/` is the one non-service package: a dependency-free library (`createScope`/`scopeOf`/`scopeTarget`) that sits below `session/` and `system-prompt/` in the module graph precisely so they can consume it without a cycle. `agent-loop` is the one concrete implementation of the public `Agent` contract and lives here because it is the harness's default product loop; it runs each driver inside `ctx.agents.withInitiator()`. Extension plugins depend on `agent` - including when they need the initiating Agent - and never on `agent-loop` directly, so the loop stays swappable. [`dsh-base`](../../packages/bundle/base/README.md) is the default product composition, while [`dsh-sdk-minimal`](../../packages/bundle/sdk-minimal/README.md) declares a smaller standalone tree.
23
+
24
+ ## Creation and ownership
25
+
26
+ Consumers create agents through `ctx.agents` - `create()` builds a fresh session and agent under one caller-supplied `SessionId`, `resume()` loads a persisted session first - or declaratively through the loop's config entries. Programmatic creation returns the owner's handle:
27
+
28
+ Source: [`packages/core/agent/src/index.ts`](../../packages/core/agent/src/index.ts)
29
+
30
+ ```ts type-equiv
31
+ /**
32
+ * An owned agent plus its disposer, returned by {@link AgentRegistry.create} /
33
+ * {@link AgentRegistry.resume}. The disposer is a CAPABILITY: among consumers,
34
+ * only the holder can tear this agent down. The registered factory provider is
35
+ * also a structural owner because the scoped agent depends on that provider's
36
+ * service API; provider unload stops and drains every live handle it made.
37
+ * `dispose()` stops the loop, awaits its exit, unregisters the agent, removes
38
+ * its session from the store, and finally unwinds its scoped world.
39
+ *
40
+ * `ctx.agents.get(id)` still returns a bare {@link Agent} - the handle is
41
+ * exposed only to the consumer owner that created it; the structural provider
42
+ * reaches the same teardown internally. Config-created agents (the loop's own
43
+ * startup) are owned by the loop fiber and never need a handle.
44
+ */
45
+ interface AgentHandle {
46
+ agent: Agent
47
+ dispose(): Promise<void>
48
+ }
49
+ ```
50
+
51
+ `CreateAgentOptions` carries the shared identity and everything a fresh agent needs before publication: an optional live `parentAgent`, session metadata (`meta` - validated `cwd`, fork lineage, the `isSeeded` marker, origin classification, delegation depth, and `agentPreset`), the exact fork cut in sibling field `inheritedEventCount`, an optional `seed` replay prefix, per-agent `AgentOptions`, a creation-only cancellation `signal`, and `setup`. `ResumeAgentOptions` is the persisted-identity counterpart: `resumeSessionId`, `parentAgent`, `agentOptions`, `signal`, and `setup`. The `setup` callback (`AgentSetup`) receives `(agentCtx, agent)` while both ids are still unpublished: the context owns scoped registrations, while the explicit Agent supplies the exact child Session without a reverse property on the Context. Everything registered through `agentCtx` exists before `agent/created` and the first prompt assembly. Setup may return a synchronous commit invoked immediately before publication; a setup rejection, commit throw, or owner disposal rolls the transaction back without publishing either id.
52
+
53
+ `AgentFactory` is the creation interface behind the registry: the loop registers its factory via `ctx.agents.setFactory()`, so consumers use `ctx.agents` without depending on the concrete loop package. A runtime child creator sets `options.parentAgent`; the registry passes the options and caller Context to the factory without deriving one from the other. The exact `create`/`resume` signatures and rollback contracts are in the [generated section](#ctxagents--agentregistry) below.
54
+
55
+ ## The agent handle
56
+
57
+ `Agent` is the surface every plugin (UI, hooks, orchestrators) programs against; `ctx.agents.get(id)` returns it, and the [initiator scope](#initiating-agent) carries it. The concrete implementation is package-internal to dsh-agent-loop; nothing outside the loop depends on it. The unified `send` method exposes target and wakeup routing directly; `followup`, `steer`, and `inject` are fixed-preset aliases.
58
+
59
+ Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
60
+
61
+ ```ts type-equiv
62
+ /** Public live-agent handle; the runtime face augments its live capabilities. */
63
+ interface Agent {
64
+ /** Session-backed Agent identity. */
65
+ readonly id: SessionId
66
+ /** The provider route and model this agent's requests use. */
67
+ readonly options: AgentOptions
68
+ /** The live session this agent drives; its log is the durable source of truth. */
69
+ readonly session: Session
70
+ /** Agent-owned access to durable pending work. */
71
+ readonly inbox: Inbox
72
+ /** The current lifecycle state, mirrored on every `agent/status` transition. */
73
+ readonly status: AgentStatus
74
+ /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */
75
+ readonly ctx: Context
76
+
77
+ /**
78
+ * Clear queued and steering work - unless `keepInbox` - and abort the active
79
+ * turn or between-turn task. The first cause wins for that activity. With no
80
+ * active activity, cancellation is a no-op and does not arm later work.
81
+ * @param cause - the stable caller intent carried by the active operation signal.
82
+ * @param options - cancellation options; `keepInbox` preserves pending work.
83
+ */
84
+ cancel(cause: AgentCancelCause, options?: CancelOptions): void
85
+
86
+ /**
87
+ * Resolve after the current whole-agent activity reaches quiescence. This
88
+ * follows replacement work started before the observed driver retires,
89
+ * but does not identify the settlement of any particular message.
90
+ * @returns fulfillment after no active driver or maintenance task remains.
91
+ */
92
+ whenIdle(): Promise<void>
93
+
94
+ /**
95
+ * Run one non-turn maintenance task from the true idle phase. The task starts
96
+ * synchronously after claiming that phase; later waking input remains in the
97
+ * inbox until the task settles, while public status stays `idle`.
98
+ * `whenIdle()` follows both the task and any waking work released behind it.
99
+ * @param task - operation whose fulfillment or rejection is preserved, with a signal aborted by {@link cancel}.
100
+ * @throws synchronously when turn-driving or another maintenance task already owns the agent.
101
+ * @returns the task promise.
102
+ */
103
+ runMaintenance<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T>
104
+
105
+ /**
106
+ * Route identified input to an inbox boundary and optionally wake the driver.
107
+ * Waking input submitted after active cancellation is queued for the next
108
+ * turn and runs when the aborted activity converges to idle; a `disposed`
109
+ * cancel leaves it parked. A wake submitted while already idle always opens
110
+ * its turn boundary, even when its message is cleared before the driver
111
+ * claims ([cancel-convergence wake latch](../../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)).
112
+ * @param message - identified content and the source that supplied it.
113
+ * @param target - the preferred next-turn or next-step inbox boundary.
114
+ * @param wakeup - whether delivery may wake the driver.
115
+ */
116
+ send(message: UserMessage, target: InboxTarget, wakeup: boolean): void
117
+
118
+ /**
119
+ * Queue an ordinary follow-up turn and wake the driver. The item becomes the
120
+ * sole ordinary message of its own turn.
121
+ * @param message - identified prompt content and the source that supplied it.
122
+ */
123
+ followup(message: UserMessage): void
124
+
125
+ /**
126
+ * Submit steering for the nearest step. An idle driver starts a turn;
127
+ * a running driver consumes it at its next step boundary.
128
+ * A rejected step leaves steering parked in the inbox until the next
129
+ * wake; cancellation or disposal may discard pending steering.
130
+ * @param message - identified steering content and the source that supplied it.
131
+ */
132
+ steer(message: UserMessage): void
133
+
134
+ /**
135
+ * Queue model-facing context for the next pre-step without waking the
136
+ * driver. A running driver claims it at the nearest later step boundary;
137
+ * idle drivers leave it pending until follow-up or steering
138
+ * wakes them. It may miss a request whose pre-step already claimed its
139
+ * batch. Cancellation or disposal may discard pending context.
140
+ * @param message - identified injected context and the source that supplied it.
141
+ */
142
+ inject(message: UserMessage): void
143
+ }
144
+ ```
145
+
146
+ ```ts type-equiv
147
+ /**
148
+ * An agent's lifecycle state, emitted on every transition as `agent/status`:
149
+ * `idle` means no driver is active; `running` begins when waking input starts
150
+ * cancellable pre-step processing and lasts while the driver drains,
151
+ * closes, or checkpoints turns. Disposal removes the agent from its registry;
152
+ * it is not a third observable status.
153
+ */
154
+ type AgentStatus = 'idle' | 'running'
155
+ ```
156
+
157
+ ```ts type-equiv
158
+ /** One process-local live assistant streaming publication. */
159
+ type AssistantStreamFrame =
160
+ | {
161
+ readonly type: 'start'
162
+ readonly attemptId: LlmAttemptId
163
+ /** Monotone within one attached Agent lifecycle; replacement restarts at 1. */
164
+ readonly revision: number
165
+ readonly turn: number
166
+ readonly step: number
167
+ }
168
+ | {
169
+ readonly type: 'chunk'
170
+ readonly attemptId: LlmAttemptId
171
+ readonly revision: number
172
+ /** Dense zero-based position within the attempt. */
173
+ readonly index: number
174
+ /** Safe-integer timestamp reused by the durable embedded stream. */
175
+ readonly time: number
176
+ readonly chunk: StreamChunk
177
+ }
178
+ | {
179
+ readonly type: 'end'
180
+ readonly attemptId: LlmAttemptId
181
+ readonly revision: number
182
+ /** Number of chunk frames emitted by this attempt. */
183
+ readonly index: number
184
+ /** Durable settlement committed before this notification, or live abandonment without one. */
185
+ readonly outcome:
186
+ | {
187
+ readonly kind: 'committed'
188
+ readonly eventType: 'assistant/message' | 'assistant/attempt'
189
+ readonly seq: SessionSeq
190
+ }
191
+ | { readonly kind: 'abandoned' }
192
+ }
193
+ ```
194
+
195
+ `running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `followup()` returns no handle: its `MessageId` identifies durable inbox insertion, claim, and discard facts, not a later assistant output or turn ending. `whenIdle()` observes the whole agent, so callers may call a receipt-to-idle interval a run only when they explicitly own that interval ([decision](../../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)).
196
+
197
+ ```ts type-equiv
198
+ /** Merge-extensible agent creation options. Persona belongs to system-prompt sections. */
199
+ interface AgentOptions {
200
+ /** Provider route (must have a registered adapter at call time). */
201
+ provider?: string
202
+ /** Model id interpreted by the selected provider adapter. */
203
+ model?: string
204
+ /** Adapter-owned reasoning effort for the selected provider/model route. */
205
+ reasoningEffort?: ReasoningEffortId
206
+ /** Maximum output tokens for each conversation-model request. */
207
+ maxTokens?: number
208
+ }
209
+ ```
210
+
211
+ Dispatch requires `provider` and `model` after `agent/request`. An explicit `reasoningEffort` seeds the first request on that route; exact-model resolution validates it, while omission allows the adapter default to materialize. When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission allows the exact-model adapter default to materialize before the request header, or otherwise leaves provider behavior unchanged. An agent-scoped `deployment:persona-prefix` prompt section may shadow the global default persona.
212
+
213
+ The inbox is the delivery vocabulary - two ordered pending-message lists the agent owns as a durable projection:
214
+
215
+ ```ts type-equiv
216
+ /** Agent-owned access to pending work; concrete storage belongs to the driver. */
217
+ interface Inbox {
218
+ /** Prompts awaiting individual turns. */
219
+ readonly nextTurn: readonly UserMessage[]
220
+ /** Input awaiting the next step boundary. */
221
+ readonly nextStep: readonly UserMessage[]
222
+
223
+ /** Durably cancel all pending input, clearing next-step before next-turn. */
224
+ clear(): void
225
+
226
+ /**
227
+ * Append one message to a pending list.
228
+ * @param target - pending list to extend.
229
+ * @param message - message to append.
230
+ */
231
+ append(target: InboxTarget, message: UserMessage): void
232
+
233
+ /**
234
+ * Prepend one message to a pending list.
235
+ * @param target - pending list to extend.
236
+ * @param message - message to prepend.
237
+ */
238
+ prepend(target: InboxTarget, message: UserMessage): void
239
+
240
+ /**
241
+ * Replace one pending message in place.
242
+ * @param messageId - identity of the pending message to replace.
243
+ * @param newMessage - replacement message.
244
+ * @returns whether the message was still pending.
245
+ */
246
+ replace(messageId: MessageId, newMessage: UserMessage): boolean
247
+
248
+ /**
249
+ * Remove one pending message.
250
+ * @param messageId - identity of the pending message to remove.
251
+ * @returns whether the message was still pending.
252
+ */
253
+ remove(messageId: MessageId): boolean
254
+
255
+ /**
256
+ * Apply standard splice semantics and durably record the normalized result.
257
+ * @param target - pending list to mutate.
258
+ * @param start - splice position.
259
+ * @param deleteCount - maximum number of messages to remove.
260
+ * @param inserted - messages to insert at the resolved position.
261
+ * @returns messages removed by the splice.
262
+ */
263
+ splice(
264
+ target: InboxTarget,
265
+ start: number,
266
+ deleteCount: number,
267
+ inserted: UserMessage[],
268
+ ): UserMessage[]
269
+ }
270
+ ```
271
+
272
+ ```ts type-equiv
273
+ /** One of the two ordered pending-message lists owned by an agent. */
274
+ type InboxTarget = 'next-turn' | 'next-step'
275
+ ```
276
+
277
+ Every pending occurrence is its `UserMessage`; `MessageId` is the sole identity. The structural `Inbox` methods record normalized durable `agent/inbox/spliced` mutations and reject duplicate pending ids. `replace(messageId, newMessage)` and `remove(messageId)` locate the pending message across both lists; replacement may change identity and emits the old message as discarded followed by the new message as inserted. Ordinary removals and `clear()` are cancellations. At a step boundary, dsh-agent-loop's package-internal `ReactLoopInbox` removes the proposed batch - all `next-step` input plus, at a turn boundary, one `next-turn` message - through pure deletion splices without discarded notifications, then emits per-message claimed notifications. Loop-only pending detection and claiming are not part of `Agent.inbox`. The `AgentLoop` service registers the standard `inbox` projection before publishing its factory; its cell is the sole live state, and the same fold serves cold consumers even when no Agent exists. The fold rejects unsafe or out-of-range splice coordinates and duplicate identities across both lists, identifying malformed durable history by event seq. Consumers following one message use the exact `agent/inbox/inserted`, `claimed`, and `discarded` notifications.
278
+
279
+ Cancellation:
280
+
281
+ ```ts type-equiv
282
+ /** Options for {@link Agent.cancel}. */
283
+ interface CancelOptions {
284
+ /**
285
+ * Preserve queued and steering inbox items instead of discarding them. The
286
+ * active turn is still aborted, but un-started and pending work survives for a
287
+ * later turn and no canceled inbox splice is logged.
288
+ */
289
+ keepInbox?: boolean | undefined
290
+ }
291
+ ```
292
+
293
+ ```ts type-equiv
294
+ /** Why an active agent driver was cancelled. */
295
+ type AgentCancelCause =
296
+ | { readonly kind: 'user' }
297
+ | { readonly kind: 'parent' }
298
+ | { readonly kind: 'hook'; readonly reason: string }
299
+ | { readonly kind: 'disposed' }
300
+ ```
301
+
302
+ The cause is a TypeScript-enforced same-process input. An active cancellation holder exposes that same object as the runtime-only `AbortSignal.reason`; a signal grants cooperating listeners no classification authority. Durable `turn/end` records the outcome as `{ kind: 'aborted', reason: TurnEndCancelCause }`, so the cancel cause lands in the terminal result.
303
+
304
+ The [event taxonomy](../architecture.md#events) owns the `agent/*` lifecycle, checkpoint, and waterfall contracts. Turn and step boundaries are durable session events rather than agent emits.
305
+
306
+ ## Initiating Agent
307
+
308
+ The process-local initiator carried by `ctx.agents` is the exact `Agent` above, not a separate frame or copied identity. Ambient presence is neither liveness proof nor authorization; the [initiator-scope decision](../../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md) defines its lifetime and scope rules.
309
+
310
+ ## Interception decisions
311
+
312
+ Pre-step decisions use the same identified `UserMessage` type as durable user-role input. The entered batch is authoritative and preserves every message's `id` and `source`. Hook bridges map their native decision fields onto this typed result.
313
+
314
+ Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
315
+
316
+ `agent/pre-step` receives one payload carrying the exclusive claimed batch (`messages`), the proposed step's coordinates (`turn`, `step`), and the current turn's cancellation `signal`. The initial proposal runs inside an open turn before any step; a tool continuation may submit an empty claimed batch between steps:
317
+
318
+ It returns a `PreStepDecision`. Reject opens no step. Enter supplies the complete message batch appended after `step/start`; claimed messages omitted by the final decision remain removed, while input inserted after the claim stays pending:
319
+
320
+ ```ts type-equiv
321
+ /** Whether and with which messages the loop enters a proposed step. */
322
+ type PreStepDecision =
323
+ | { kind: 'reject' }
324
+ | {
325
+ kind: 'enter'
326
+ messages: UserMessage[]
327
+ /** Start a distinct model-message series before this step's admitted messages. */
328
+ startsRequestSeries?: true
329
+ }
330
+ ```
331
+
332
+ `agent/request-error` runs after a failed model step closes and before its turn closes. Listeners can repair durable state or await policy work while the failed turn's signal is still live. A handling listener returns `{ kind: 'retry' }` without calling `next()`; the default `undefined` leaves the failure terminal.
333
+
334
+ ```ts type-equiv
335
+ /** Action returned by a listener that owns model-request recovery. */
336
+ type RequestErrorAction = { kind: 'retry' } | undefined
337
+ ```
338
+
339
+ `agent/pre-step` is the only waterfall listener chain before request derivation. `agent/turn-stopping` runs when a turn has no tool or steering continuation, before one final steering drain.
340
+
341
+ `agent/created` carries a `SessionStartSource` (why the session lifecycle began; a bridge keys its SessionStart matcher on it):
342
+
343
+ ```ts type-equiv
344
+ /** Why a session lifecycle began; seeded creates are `startup`, while persisted loads are `resume`. */
345
+ type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
346
+ ```
347
+
348
+ ## Sessions
349
+
350
+ A `Session` is an **append-only log** of typed `SessionEvent`s - the single source of truth. The LLM message history is *derived* from the log (`deriveMessages()`), not stored separately. Every entry carries a monotonic `seq`, a `time`, and a `type`-discriminated `data` payload; surface variants may also list cited earlier events in `sourceEventSeqs` and carry a `surfaceOp`.
351
+
352
+ The `SessionEvent` envelope's exact conditional fields, the thirteen core event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `system/message`, `assistant/message`, `assistant/attempt`, `tool/call`, `tool/result`, `request/header`, `request/context`, `session/end-seed`), the `deriveMessages()` projection rules, the `TurnEndReason` reasons, and the execution-enclosure and standalone-event rules are on **[session.md](session.md)**. How the log is made durable - the `SessionPersistence` interface, JSONL provider, `session/flush` checkpoint, crash recovery, and `SessionHeader` - is on **[persistence.md](persistence.md)**.
353
+
354
+ ## `ToolDefinition`
355
+
356
+ The one pipeline-authoring type that is core: what every registered tool *is* - a model-facing `ToolSchema` plus an `execute` function and optional final-content and UI callbacks. A tool author rarely constructs it by hand (the `defineTool` DSL builds it with typed arguments), but it is the contract the registry holds and the loop dispatches through.
357
+
358
+ Its full fields, the `defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` typed schema DSL, the `ToolExecution`/`ToolExecutionResult` waterfall types, and the tool-presentation UI types are on **[tools.md](tools.md)**.
359
+
360
+ ## Repo-wide type patterns
361
+
362
+ Two patterns recur across every subsystem and are documented once, here.
363
+
364
+ <a id="the-map--derived-union-pattern"></a>
365
+
366
+ ### The `…Map → derived-union` pattern
367
+
368
+ Almost every extensible sum type in the harness follows one pattern: an interface keyed by a discriminant tag (the `…Map`), from which the union is derived with `keyof`. Plugins add variants by **declaration merging** - no edit to the owning package.
369
+
370
+ ```ts ignore-check
371
+ // The pattern, schematically:
372
+ interface ThingMap {
373
+ 'a': { kind: 'a'; /* … */ }
374
+ 'b': { kind: 'b'; /* … */ }
375
+ }
376
+ type ThingKind = keyof ThingMap // 'a' | 'b'
377
+ type Thing = ThingMap[keyof ThingMap] // the discriminated union
378
+
379
+ // A plugin extends it without touching the source package:
380
+ declare module '@deepseek-ai/dsh-llm' {
381
+ interface ThingMap {
382
+ 'c': { kind: 'c'; /* … */ }
383
+ }
384
+ }
385
+ ```
386
+
387
+ Five canonical maps use this pattern; a plugin author extends these:
388
+
389
+ | Map | Package | Derives | Catalog |
390
+ |---|---|---|---|
391
+ | `ContentBlockMap` | dsh-llm | `ContentBlock` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
392
+ | `MessageSourceMap` | dsh-llm | `MessageSource` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
393
+ | `FinishReasonMap` | dsh-llm | `FinishReason` | [llm-streaming.md](llm-streaming.md#the-model-request-and-result) |
394
+ | `TurnEndReasonMap` | dsh-session | `TurnEndReason` | [session.md](session.md) |
395
+ | `SessionEventMap` | dsh-session | `SessionEvent` | [session.md](session.md) |
396
+
397
+ Two large discriminated unions are the ones consumers `switch` over most: **`StreamChunk`** (the streaming protocol) and **`SessionEvent`** (the log entry). Per the repo convention, `switch` on the tag - don't chain `if`s - so each arm narrows and a typo'd tag fails to compile.
398
+
399
+ ### Branded IDs
400
+
401
+ IDs passed between packages are **branded** - structurally strings, but non-interchangeable at the type level (a `SessionId` cannot be passed where a `ToolCallId` is expected). Construction uses the shared `brandString<T>()` helper or an owner-defined validating factory; comparison, logging, and JSON behave as ordinary strings.
402
+
403
+ The `Branded<B>` primitive and stateless constructor live in [dsh-brand](../../packages/util/brand), which has no harness capability dependency. `brandString<T>()` applies a compile-time-only string brand.
404
+
405
+ Source: [`packages/util/brand/src/index.ts`](../../packages/util/brand/src/index.ts)
406
+
407
+ ```ts type-equiv
408
+ /** A string carrying a compile-time-only brand `B`. */
409
+ type Branded<B extends string> = string & { readonly [BRAND]: B }
410
+ ```
411
+
412
+ The two core IDs are `ToolCallId` (correlates a tool call with its result; dsh-llm) and `SessionId` (the shared live agent and durable session identity; dsh-session). Capability packages brand their own ids too, such as `JobId` in [jobs.md](jobs.md).
413
+
414
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
415
+
416
+ <a id="cordis-surface"></a>
417
+
418
+ ## Cordis API
419
+
420
+ 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).
421
+
422
+ <a id="ctxagentdefaultmodel--agentdefaultmodelconfig"></a>
423
+
424
+ ### `ctx.agentDefaultModel` - `AgentDefaultModelConfig`
425
+
426
+ Owns the default model selection independently of any Host or transport. Each operation reads the owning Config references.
427
+
428
+ ```ts cordis-catalog
429
+ /**
430
+ * Read the current default model selection.
431
+ * @returns a detached provider, model, and optional reasoning selection.
432
+ */
433
+ currentSelection(): ModelSelection
434
+
435
+ /**
436
+ * Save the complete default model selection. A deployment without a configuration
437
+ * editor keeps its composition entry. Saves commit in submission order; a failed
438
+ * save rejects its caller without blocking later saves.
439
+ * @param next - resolved selection accepted by an entry point.
440
+ * @returns fulfillment after the optional profile write settles.
441
+ */
442
+ async saveSelection(next: ModelSelection): Promise<void>
443
+ ```
444
+
445
+ Source: [`packages/core/agent-default-model/src/index.ts`](../../packages/core/agent-default-model/src/index.ts)
446
+
447
+ <a id="ctxagentloop--agentloop"></a>
448
+
449
+ ### `ctx.agentLoop` - `AgentLoop`
450
+
451
+ Concrete agent factory and driver service.
452
+
453
+ ```ts cordis-catalog
454
+ /**
455
+ * Create an agent and session under one caller-supplied identity, owned by
456
+ * the accessing fiber. Constructor-driven config calls mint a fresh combined
457
+ * id before entering this boundary. When a persistence backend is mounted,
458
+ * the session's durable identity and any seed are stored before publication.
459
+ * @param id - shared agent/session identity.
460
+ * @param options - concrete loop options.
461
+ * @param meta - optional fresh-session workspace metadata.
462
+ * @returns the published running agent.
463
+ */
464
+ async create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): Promise<Agent>
465
+
466
+ /**
467
+ * Create an owned agent on a caller-supplied session id.
468
+ * @param ownerCtx - caller context that structurally owns the lifecycle.
469
+ * @param options - identities, optional live parent, session seed/metadata, loop options, setup, and cancellation.
470
+ * @returns the published handle.
471
+ */
472
+ async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>
473
+
474
+ /**
475
+ * Resume an owned agent from the configured persistence service.
476
+ * @param ownerCtx - caller context that owns load, setup, and the live lifecycle.
477
+ * @param options - persisted identity, optional live parent, loop options, setup, and cancellation.
478
+ * @returns the published handle.
479
+ */
480
+ async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>
481
+ ```
482
+
483
+ Types: [SessionHeader](persistence.md)
484
+
485
+ Source: [`packages/core/agent-loop/src/index.ts`](../../packages/core/agent-loop/src/index.ts)
486
+
487
+ <a id="ctxagentpresets--agentpresetregistry"></a>
488
+
489
+ ### `ctx.agentPresets` - `AgentPresetRegistry`
490
+
491
+ Registry of YAML-declared presets and the revisions live Agents retain.
492
+
493
+ ```ts cordis-catalog
494
+ /** Register and eagerly load a definition; activation failure remains visible in the roster.
495
+ * @param definition Parsed configuration supplied by the declaring plugin.
496
+ * @returns Definition disposer after activation or its diagnostic settles; the declaring plugin owns it.
497
+ */
498
+ async register(definition: PresetDefinition): Promise<() => Promise<void>>
499
+
500
+ /** Read every declared preset, including activation failures.
501
+ * @returns Display metadata and loading diagnostics.
502
+ */
503
+ async list(): Promise<AgentPreset[]>
504
+
505
+ /** Read the selection roster.
506
+ * @returns Current presets, each marked when it is the default.
507
+ */
508
+ @Remote('list') async remoteExportList(): Promise<AgentPresetRoster>
509
+
510
+ /** Resolve an identity without starting an Agent.
511
+ * @param id Explicit preset or the current default.
512
+ * @returns Current metadata, including failure when activation failed.
513
+ */
514
+ async resolve(id?: string): Promise<AgentPreset>
515
+
516
+ /** Read one declaration's child plugin list as YAML, for viewing only.
517
+ * @param agentPreset Preset identity.
518
+ * @returns The declared composition beside its published metadata.
519
+ */
520
+ @Remote('read') readDocument(agentPreset: string): Promise<AgentPresetDocument>
521
+
522
+ /** Bind an unpublished Agent to the current preset revision.
523
+ * @param ctx Agent context from its setup callback.
524
+ * @param id Requested preset, or the default.
525
+ * @returns Bound preset identity.
526
+ */
527
+ async mount(ctx: Context, id?: string): Promise<AgentPreset>
528
+
529
+ /** Join a child to the exact revision retained by its parent.
530
+ * @param ctx Child Agent context.
531
+ * @param parent Parent Agent context.
532
+ * @returns Inherited preset id, or undefined in a preset-free composition.
533
+ */
534
+ composeFrom(ctx: Context, parent: Context): string | undefined
535
+
536
+ /** Read the preset a live Agent uses.
537
+ * @param ctx Agent context.
538
+ * @returns Its preset id, if bound.
539
+ */
540
+ composedPreset(ctx: Context): string | undefined
541
+
542
+ /** Read a service supplied inside an Agent's isolated preset group.
543
+ * @param agent Agent whose composition is queried.
544
+ * @param name Cordis service name.
545
+ * @returns The service, or undefined.
546
+ */
547
+ serviceFor<K extends string & keyof Context>(agent: { ctx: Context }, name: K): Context[K] | undefined
548
+
549
+ /** Rebind a blank Agent; the caller owns the blank-session check.
550
+ * @param ctx Agent context.
551
+ * @param id Requested preset.
552
+ * @returns The bound identity.
553
+ */
554
+ async recompose(ctx: Context, id: string): Promise<AgentPreset>
555
+
556
+ /** Select a preset before a session starts its first turn.
557
+ * @param agent Target Agent.
558
+ * @param agentPreset Requested identity.
559
+ * @returns Committed preset identity.
560
+ */
561
+ @Remote('select') async select(agent: Agent, agentPreset: string): Promise<string>
562
+
563
+ /** Read current registrations for cold transcript presentation.
564
+ * @param id Preset identity or the default.
565
+ * @returns A revision lease; dispose it after the scoped read completes.
566
+ */
567
+ async acquireScope(id?: string): Promise<{ key: ScopeKey } & AsyncDisposable>
568
+
569
+ /** Read plugin rows without creating an Agent.
570
+ * @returns Current declaration metadata and activation states.
571
+ */
572
+ compositionInventory(): Promise<AgentPresetComposition[]>
573
+ ```
574
+
575
+ Types: [ScopeKey](scope.md)
576
+
577
+ Source: [`packages/preset/agent-preset-registry/src/index.ts`](../../packages/preset/agent-preset-registry/src/index.ts)
578
+
579
+ <a id="ctxagents--agentregistry"></a>
580
+
581
+ ### `ctx.agents` - `AgentRegistry`
582
+
583
+ Agent service (`ctx.agents`): tracks live agents and carries the initiating Agent through one process-local asynchronous driver chain. Agent *creation* is provided by whichever plugin implements the AgentFactory (`@deepseek-ai/dsh-agent-loop`), registered via setFactory.
584
+
585
+ Initiator methods provide same-process causal attribution only. Ambient presence is neither liveness proof nor authorization; subjects and owners remain explicit, as does identity at worker, process, persistence, and wire boundaries. Returned Promise boundaries drain during teardown, except a nested lineage that starts an owning-fiber unload is excluded from its own drain.
586
+
587
+ ```ts cordis-catalog
588
+ /**
589
+ * Read the Agent that initiated the inherited asynchronous driver chain.
590
+ * Use this optional form for logging, tracing, metrics, or host attribution
591
+ * that also supports agentless calls. When a parent creates a child, setup
592
+ * reports the causal parent while the setup callback's Agent parameter
593
+ * identifies the child.
594
+ * @returns the inherited Agent, or `undefined` outside an initiator boundary
595
+ * and inside an explicit clearing boundary.
596
+ * @throws when this service instance has been disposed.
597
+ */
598
+ currentInitiator(): Agent | undefined
599
+
600
+ /**
601
+ * Read the initiating Agent and fail when no initiator boundary is active.
602
+ * Use this for private helpers contractually below a driver, or for a
603
+ * deployment-owned outbound request whose contract forbids agentless calls.
604
+ * Generic or direct-call paths use optional lookup or explicit request fields.
605
+ * @returns the inherited Agent.
606
+ * @throws when no initiator is active or this service instance has been disposed.
607
+ */
608
+ requireInitiator(): Agent
609
+
610
+ /**
611
+ * Run an operation with one exact Agent as its process-local initiator. The
612
+ * exact synchronous value or Promise returned by the operation is preserved.
613
+ * Custom drivers and test harnesses wrap their complete returned foreground
614
+ * lifetime.
615
+ * A queue or wire receiver may establish this boundary only after validating
616
+ * explicit identity and resolving the exact live Agent; this method does neither.
617
+ * Detached work remains owned by the subsystem that starts it.
618
+ * @param agent - initiating Agent to inherit; presence is neither liveness proof nor authorization.
619
+ * @param operation - synchronous or asynchronous operation to invoke.
620
+ * @returns the exact value returned by `operation`.
621
+ * @throws when the initiator scope is closing/disposed, or when `operation` throws.
622
+ */
623
+ withInitiator<T>(agent: Agent, operation: () => T): T
624
+
625
+ /**
626
+ * Run an operation inside a boundary that hides any inherited initiating
627
+ * Agent. The exact synchronous value or Promise is preserved.
628
+ * Use this while creating lazy shared timers, queue pumps, pool maintenance,
629
+ * watchers, or exporters so they do not inherit the first Agent that happens
630
+ * to initialize them. It clears only initiator attribution, not explicit
631
+ * fields, and does not own or drain detached resources.
632
+ * @param operation - synchronous or asynchronous operation to invoke without an initiator.
633
+ * @returns the exact value returned by `operation`.
634
+ * @throws when the initiator scope is closing/disposed, or when `operation` throws.
635
+ */
636
+ withoutInitiator<T>(operation: () => T): T
637
+
638
+ /**
639
+ * Register the agent-creation factory (the loop calls this on construction,
640
+ * effect-scoped). A traced Cordis service is canonicalized to its concrete
641
+ * target; each create/resume call is then traced through that caller's
642
+ * context so ownership follows the caller without stacking proxy layers.
643
+ * Throws if a factory is already registered. Returns the disposer; on
644
+ * dispose the factory slot is cleared.
645
+ * @param factory - the loop-owned factory {@link create}/{@link resume} delegate to.
646
+ * @returns the disposer that clears the factory slot. The exact
647
+ * Cordis effect disposer (single-shot): composite (generator) effects may
648
+ * yield it directly - exact identity nests the teardown in order.
649
+ */
650
+ setFactory(factory: AgentFactory): () => void
651
+
652
+ /**
653
+ * Create and publish a new agent through the registered factory.
654
+ * Distinct from {@link register} (which records an already-constructed
655
+ * agent): this constructs the agent and its session. Rejects if no factory is
656
+ * registered or creation/setup fails. The resolved {@link AgentHandle} lets
657
+ * the owner tear down exactly this agent.
658
+ * @param options - shared identity, optional live parent, session seed/metadata, and agent options.
659
+ * @returns the handle after setup, rollback-covered publication, and loop start complete.
660
+ */
661
+ async create(options: CreateAgentOptions): Promise<AgentHandle>
662
+
663
+ /**
664
+ * Load a persisted session and resume an agent on it through the registered
665
+ * factory. Rejects if no factory is registered; the factory rejects if
666
+ * session persistence is not configured or persistence/setup fails.
667
+ * @param options - persisted identity, optional live parent, configuration, and setup.
668
+ * @returns the handle after setup, rollback-covered publication, and loop start complete.
669
+ */
670
+ async resume(options: ResumeAgentOptions): Promise<AgentHandle>
671
+
672
+ /**
673
+ * Register a live agent with source `startup`. Rejects if the id is already registered or a
674
+ * serial `agent/created` listener fails. Emits `agent/disposed`
675
+ * when the calling fiber is disposed - both with the agent's scope carrier
676
+ * (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the
677
+ * emits are scope-filtered regardless of which context invoked `register`
678
+ * (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always
679
+ * requires passing the carrier). The entry is a runtime root; factory-backed
680
+ * creation uses `options.parentAgent` for child ownership. Await the registration before using the agent.
681
+ * @param agent - the already-constructed agent to record in the store.
682
+ * @returns the awaitable Cordis effect disposer (single-shot; a repeat call
683
+ * returns undefined without awaiting an in-flight teardown). Exact
684
+ * identity is load-bearing: a composite (generator) effect that owns a
685
+ * teardown ORDER - the agent factory's lifecycle chain - must yield THIS
686
+ * function so Cordis nests the unregistration at that yield position;
687
+ * yielding a wrapper would leave it disposing as a concurrent sibling on
688
+ * owner unload, unregistering the agent (and emitting `agent/disposed`)
689
+ * while its final turn is still draining.
690
+ */
691
+ register(agent: Agent): ReturnType<Context['effect']>
692
+
693
+ /**
694
+ * Insert an already-constructed agent without announcing it. This is the
695
+ * advanced ordered-lifecycle primitive used by the async agent factory: it
696
+ * first completes setup while the agent is unpublished, then assigns the
697
+ * returned detach closure into its pre-installed composite teardown before
698
+ * calling {@link announce}. Ordinary callers use {@link register}.
699
+ * @param agent - the prepared, unpublished agent.
700
+ * @param owner - explicitly supplied live runtime owner, or
701
+ * undefined for a top-level runtime root. This is runtime ownership, not
702
+ * the resumed session's durable parent lineage.
703
+ * @returns an idempotent closure that removes this exact entry and emits
704
+ * `agent/disposed` with listener failures contained. When called from a
705
+ * `agent/created` listener, removal and disposal wait until the serial
706
+ * creation dispatch settles.
707
+ */
708
+ enter(agent: Agent, owner: Agent | undefined): () => void
709
+
710
+ /**
711
+ * Announce an agent previously inserted with {@link enter}.
712
+ * @param agent - the live inserted agent to announce.
713
+ * @param source - fresh creation, resume, clear, or compaction source.
714
+ * @param signal - optional factory initialization cancellation signal passed to listeners.
715
+ * @returns completion of the serial creation listeners; a listener failure rejects.
716
+ * @throws if `agent` is not the exact live registry entry for its id, or its
717
+ * creation announcement already began (including a reentrant call from a
718
+ * creation listener).
719
+ */
720
+ async announce(agent: Agent, source: SessionStartSource, signal?: AbortSignal): Promise<void>
721
+
722
+ /**
723
+ * Look up a live agent.
724
+ * @param id - the shared agent/session id to look up.
725
+ * @returns the agent, or undefined when no live agent has that id.
726
+ */
727
+ get(id: SessionId): Agent | undefined
728
+
729
+ /**
730
+ * Test whether a live agent was created through one exact parent agent's
731
+ * scoped context. Runtime ownership is independent of durable session
732
+ * lineage and remains unambiguous when unrelated providers reuse an id.
733
+ * @param id - the candidate child agent's shared agent/session id.
734
+ * @param owner - the expected runtime creator agent.
735
+ * @returns true only while the exact child entry is live under that owner.
736
+ */
737
+ isOwnedBy(id: SessionId, owner: Agent): boolean
738
+
739
+ /**
740
+ * All live agents, in registration order.
741
+ * @returns a fresh array; mutating it does not affect the registry.
742
+ */
743
+ list(): Agent[]
744
+
745
+ /**
746
+ * All live top-level agents in registration order. A top-level agent was
747
+ * created without an owning agent context; durable session lineage does not
748
+ * affect this runtime relation, so a resumed fork may still be a root.
749
+ * @returns a fresh array; mutating it does not affect the registry.
750
+ */
751
+ roots(): Agent[]
752
+ ```
753
+
754
+ Source: [`packages/core/agent/src/index.ts`](../../packages/core/agent/src/index.ts)
755
+
756
+ <a id="agent-events"></a>
757
+
758
+ ### `agent/*` events
759
+
760
+ <a id="agentassistant-stream--emit"></a>
761
+
762
+ #### `agent/assistant-stream` - emit
763
+
764
+ Process-local assistant-stream publication. Chunk frames are transient; the loop appends one final v2 `assistant/message` or `assistant/attempt` with the same stream before a committed end frame.
765
+
766
+ ```ts cordis-catalog
767
+ /**
768
+ * Process-local assistant-stream publication. Chunk frames are transient;
769
+ * the loop appends one final v2 `assistant/message` or `assistant/attempt`
770
+ * with the same stream before a committed end frame.
771
+ * @param payload.agent - the agent whose attempt produced the frame.
772
+ * @param payload.frame - one ordered start, chunk, or end publication.
773
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
774
+ * @mode emit
775
+ */
776
+ 'agent/assistant-stream'(this: Scoped<Agent>, payload: { agent: Agent; frame: AssistantStreamFrame }): void
777
+ ```
778
+
779
+ Types: [Scoped](scope.md)
780
+
781
+ Source: [`packages/core/agent/src/runtime-types.ts`](../../packages/core/agent/src/runtime-types.ts)
782
+
783
+ <a id="agentcreated--serial"></a>
784
+
785
+ #### `agent/created` - serial
786
+
787
+ An entered agent is ready for per-agent initialization after factory setup. Listeners run in order and are awaited before creation resolves. AgentLoop holds queued input until all listeners finish. A throw or rejection fails creation and skips later listeners. Disposal retains the scope and session until dispatch settles; listeners must not await agent.whenIdle() or their own owner's disposal.
788
+
789
+ ```ts cordis-catalog
790
+ /**
791
+ * An entered agent is ready for per-agent initialization after factory setup.
792
+ * Listeners run in order and are awaited before creation resolves. AgentLoop
793
+ * holds queued input until all listeners finish. A throw or rejection fails
794
+ * creation and skips later listeners. Disposal retains the scope and session
795
+ * until dispatch settles; listeners must not await agent.whenIdle() or their
796
+ * own owner's disposal.
797
+ * @param payload.agent - the newly registered agent with its live session and completed setup.
798
+ * @param payload.source - fresh creation, resume, clear, or compaction source.
799
+ * @param payload.signal - factory initialization cancellation signal, when provided.
800
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
801
+ * @mode serial
802
+ */
803
+ 'agent/created'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource; signal?: AbortSignal }): undefined | Promise<undefined>
804
+ ```
805
+
806
+ Types: [Scoped](scope.md)
807
+
808
+ Source: [`packages/core/agent/src/runtime-types.ts`](../../packages/core/agent/src/runtime-types.ts)
809
+
810
+ <a id="agentdisposed--emit"></a>
811
+
812
+ #### `agent/disposed` - emit
813
+
814
+ An agent left the registry; AgentLoop emits this after driver quiescence and scoped-registration unwind, but before session detachment. Custom registry users own their driver-ordering contract.
815
+
816
+ ```ts cordis-catalog
817
+ /**
818
+ * An agent left the registry; AgentLoop emits this after driver quiescence
819
+ * and scoped-registration unwind, but before session detachment. Custom
820
+ * registry users own their driver-ordering contract.
821
+ * @param payload.agent - the exact agent removed from the registry.
822
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
823
+ * @mode emit
824
+ */
825
+ 'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
826
+ ```
827
+
828
+ Types: [Scoped](scope.md)
829
+
830
+ Source: [`packages/core/agent/src/runtime-types.ts`](../../packages/core/agent/src/runtime-types.ts)
831
+
832
+ <a id="agenterror--emit"></a>
833
+
834
+ #### `agent/error` - emit
835
+
836
+ A step or turn errored. The machine reports a failure here even when the error has no in-turn position for a durable record.
837
+
838
+ ```ts cordis-catalog
839
+ /**
840
+ * A step or turn errored. The machine reports a failure here even when
841
+ * the error has no in-turn position for a durable record.
842
+ * @param payload.agent - the agent whose turn errored.
843
+ * @param payload.turn - the turn in which the failure surfaced.
844
+ * @param payload.step - the step at which the failure surfaced.
845
+ * @param payload.error - the failure, verbatim.
846
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
847
+ * @mode emit
848
+ */
849
+ 'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
850
+ ```
851
+
852
+ Types: [Scoped](scope.md)
853
+
854
+ Source: [`packages/core/agent/src/runtime-types.ts`](../../packages/core/agent/src/runtime-types.ts)
855
+
856
+ <a id="agentinboxclaimed--emit"></a>
857
+
858
+ #### `agent/inbox/claimed` - emit
859
+
860
+ One message left the inbox inside its open turn. If the proposed step is rejected, the claimed message ends here: it is neither discarded nor re-emitted as a user/message, and the turn closes without a step.
861
+
862
+ ```ts cordis-catalog
863
+ /**
864
+ * One message left the inbox inside its open turn. If the proposed step
865
+ * is rejected, the claimed message ends here: it is neither discarded nor
866
+ * re-emitted as a user/message, and the turn closes without a step.
867
+ * @param payload.agent - the agent whose inbox changed.
868
+ * @param payload.message - the claimed message.
869
+ * @param payload.turn - the owning turn.
870
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
871
+ * @mode emit
872
+ */
873
+ 'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
874
+ ```
875
+
876
+ Types: [Scoped](scope.md) · [UserMessage](session.md)
877
+
878
+ Source: [`packages/core/agent/src/runtime-types.ts`](../../packages/core/agent/src/runtime-types.ts)
879
+
880
+ <a id="agentinboxdiscarded--emit"></a>
881
+
882
+ #### `agent/inbox/discarded` - emit
883
+
884
+ One message was discarded from the live inbox.
885
+
886
+ ```ts cordis-catalog
887
+ /**
888
+ * One message was discarded from the live inbox.
889
+ * @param payload.agent - the agent whose inbox changed.
890
+ * @param payload.message - the discarded message.
891
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
892
+ * @mode emit
893
+ */
894
+ 'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
895
+ ```
896
+
897
+ Types: [Scoped](scope.md) · [UserMessage](session.md)
898
+
899
+ Source: [`packages/core/agent/src/runtime-types.ts`](../../packages/core/agent/src/runtime-types.ts)
900
+
901
+ <a id="agentinboxinserted--emit"></a>
902
+
903
+ #### `agent/inbox/inserted` - emit
904
+
905
+ One message entered the live inbox.
906
+
907
+ ```ts cordis-catalog
908
+ /**
909
+ * One message entered the live inbox.
910
+ * @param payload.agent - the agent whose inbox changed.
911
+ * @param payload.message - the inserted message.
912
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
913
+ * @mode emit
914
+ */
915
+ 'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
916
+ ```
917
+
918
+ Types: [Scoped](scope.md) · [UserMessage](session.md)
919
+
920
+ Source: [`packages/core/agent/src/runtime-types.ts`](../../packages/core/agent/src/runtime-types.ts)
921
+
922
+ <a id="agentpre-step--waterfall"></a>
923
+
924
+ #### `agent/pre-step` - waterfall
925
+
926
+ Reject a proposed step or replace the messages that enter it. Calling `next()` preserves the current messages.
927
+
928
+ ```ts cordis-catalog
929
+ /**
930
+ * Reject a proposed step or replace the messages that enter it. Calling
931
+ * `next()` preserves the current messages.
932
+ * @param payload.agent - the agent proposing the step.
933
+ * @param payload.messages - messages removed from the inbox for this step.
934
+ * @param payload.turn - the turn that will own the step.
935
+ * @param payload.step - the step proposed by the loop.
936
+ * @param payload.signal - the current turn's cancellation signal.
937
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
938
+ * @mode waterfall
939
+ */
940
+ 'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
941
+ ```
942
+
943
+ Types: [Scoped](scope.md) · [UserMessage](session.md)
944
+
945
+ Source: [`packages/core/agent/src/runtime-types.ts`](../../packages/core/agent/src/runtime-types.ts)
946
+
947
+ <a id="agentrequest--waterfall"></a>
948
+
949
+ #### `agent/request` - waterfall
950
+
951
+ Replace the frozen call configuration. `await next()` yields the config the machine would use (agent options on the first request, the logged header afterwards); return a replacement to switch. On step admission, this runs after assembly and `step/start`, before the system prompt and accepted user batch are committed. Cancellation here or during subsequent `prepareCall()` resolution commits neither. The prepared call capability governs prompt admission. Model-visible content must use logged channels; this waterfall cannot mutate messages.
952
+
953
+ ```ts cordis-catalog
954
+ /**
955
+ * Replace the frozen call configuration. `await next()` yields the config
956
+ * the machine would use (agent options on the first request, the logged
957
+ * header afterwards); return a replacement to switch. On step admission,
958
+ * this runs after assembly and `step/start`, before the system prompt and
959
+ * accepted user batch are committed. Cancellation here or during subsequent
960
+ * `prepareCall()` resolution commits neither. The prepared call capability
961
+ * governs prompt admission. Model-visible content must use logged channels;
962
+ * this waterfall cannot mutate messages.
963
+ * @param payload.agent - the agent making the model call.
964
+ * @param payload.turn - the open turn number.
965
+ * @param payload.step - the step whose request this is.
966
+ * @param payload.signal - the current turn's explicit abort signal.
967
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
968
+ * @mode waterfall
969
+ */
970
+ 'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
971
+ ```
972
+
973
+ Types: [LlmCallConfig](llm-streaming.md) · [Scoped](scope.md)
974
+
975
+ Source: [`packages/core/agent/src/runtime-types.ts`](../../packages/core/agent/src/runtime-types.ts)
976
+
977
+ <a id="agentrequest-error--waterfall"></a>
978
+
979
+ #### `agent/request-error` - waterfall
980
+
981
+ Handle one failed model-request attempt before the loop retries or closes its step. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
982
+
983
+ ```ts cordis-catalog
984
+ /**
985
+ * Handle one failed model-request attempt before the loop retries or closes
986
+ * its step. A listener returns `{ kind: 'retry' }` without calling `next()`
987
+ * when it owns recovery, or calls `next()` to delegate. The default
988
+ * `undefined` leaves the failure terminal.
989
+ * @param payload.agent - the agent whose request failed.
990
+ * @param payload.turn - the turn containing the failed request.
991
+ * @param payload.step - the step containing the failed request attempt.
992
+ * @param payload.provider - the provider selected for the failed request.
993
+ * @param payload.failure - serializable facts normalized at the final adapter boundary.
994
+ * @param payload.retryPolicy - the policy of the adapter registration that served the failed request.
995
+ * @param payload.signal - the turn abort signal.
996
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
997
+ * @mode waterfall
998
+ */
999
+ 'agent/request-error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
1000
+ ```
1001
+
1002
+ Types: [LlmFailure](llm-streaming.md) · [ResolvedRetryPolicy](llm-streaming.md) · [Scoped](scope.md)
1003
+
1004
+ Source: [`packages/core/agent/src/runtime-types.ts`](../../packages/core/agent/src/runtime-types.ts)
1005
+
1006
+ <a id="agentstatus--emit"></a>
1007
+
1008
+ #### `agent/status` - emit
1009
+
1010
+ Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` synchronously after reserving cancellation; `idle` means no driver remains scheduled or active.
1011
+
1012
+ ```ts cordis-catalog
1013
+ /**
1014
+ * Agent status changed (`idle` ⇄ `running`). A waking delivery enters
1015
+ * `running` synchronously after reserving cancellation; `idle` means no
1016
+ * driver remains scheduled or active.
1017
+ * @param payload.agent - the agent whose status flipped.
1018
+ * @param payload.status - the status just entered (the transition's destination).
1019
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
1020
+ * @mode emit
1021
+ */
1022
+ 'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
1023
+ ```
1024
+
1025
+ Types: [Scoped](scope.md)
1026
+
1027
+ Source: [`packages/core/agent/src/runtime-types.ts`](../../packages/core/agent/src/runtime-types.ts)
1028
+
1029
+ <a id="agentturn-stopping--serial"></a>
1030
+
1031
+ #### `agent/turn-stopping` - serial
1032
+
1033
+ The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits - a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step. The conclusion never short-circuits already-submitted next-step work: same-step `additionalContexts` or racing steering still runs, and the turn closes only when that inbox drains.
1034
+
1035
+ ```ts cordis-catalog
1036
+ /**
1037
+ * The turn is about to close: the model owes no response (no live tool
1038
+ * calls, no fresh steering). Awaited before the boundary commits - a
1039
+ * listener that objects steers (`agent.steer(...)`) and the machine
1040
+ * re-reads its inbox: fresh steering runs another step, none closes the
1041
+ * turn. Data decides, so listener order cannot change the outcome. The
1042
+ * inverse control (stop a tool loop early) is data too: a tool result
1043
+ * carrying `concludesTurn` ends the turn at its step. The conclusion
1044
+ * never short-circuits already-submitted next-step work: same-step
1045
+ * `additionalContexts` or racing steering still runs, and the turn
1046
+ * closes only when that inbox drains.
1047
+ * @param payload.agent - the agent whose turn is at its stop boundary.
1048
+ * @param payload.turn - the turn about to close.
1049
+ * @param payload.signal - the current turn's explicit abort signal.
1050
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
1051
+ * @mode serial
1052
+ */
1053
+ 'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
1054
+ ```
1055
+
1056
+ Types: [Scoped](scope.md)
1057
+
1058
+ Source: [`packages/core/agent/src/runtime-types.ts`](../../packages/core/agent/src/runtime-types.ts)
1059
+
1060
+ <a id="agent-loop-events"></a>
1061
+
1062
+ ### `agent-loop/*` events
1063
+
1064
+ <a id="agent-loopconfig-start-failed--emit"></a>
1065
+
1066
+ #### `agent-loop/config-start-failed` - emit
1067
+
1068
+ A declarative agent entry failed before it could publish a live agent. Consumers that buffer work for the configured identity use this transient signal to reject that work instead of waiting forever. Normal factory teardown suppresses failures from the cancelled startup attempt.
1069
+
1070
+ ```ts cordis-catalog
1071
+ /**
1072
+ * A declarative agent entry failed before it could publish a live agent.
1073
+ * Consumers that buffer work for the configured identity use this
1074
+ * transient signal to reject that work instead of waiting forever. Normal
1075
+ * factory teardown suppresses failures from the cancelled startup attempt.
1076
+ * @param payload.sessionId - exact shared agent/session identity that failed startup.
1077
+ * @param payload.error - persistence, setup, or publication failure.
1078
+ * @mode emit
1079
+ */
1080
+ 'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
1081
+ ```
1082
+
1083
+ Source: [`packages/core/agent-loop/src/index.ts`](../../packages/core/agent-loop/src/index.ts)
1084
+
1085
+ <a id="agent-preset-events"></a>
1086
+
1087
+ ### `agent-preset/*` events
1088
+
1089
+ <a id="agent-presetselected--emit"></a>
1090
+
1091
+ #### `agent-preset/selected` - emit
1092
+
1093
+ One session committed a different agent preset to its durable log. Consumers invalidate only state derived from that session's composition.
1094
+
1095
+ ```ts cordis-catalog
1096
+ /**
1097
+ * One session committed a different agent preset to its durable log.
1098
+ * Consumers invalidate only state derived from that session's composition.
1099
+ * @mode emit
1100
+ * @param sessionId - the session whose composition changed.
1101
+ * @param agentPreset - the preset recorded by the committed selection.
1102
+ */
1103
+ 'agent-preset/selected'(sessionId: SessionId, agentPreset: string): void
1104
+ ```
1105
+
1106
+ Source: [`packages/preset/agent-preset-registry/src/types.ts`](../../packages/preset/agent-preset-registry/src/types.ts)
1107
+ <!-- END GENERATED cordis-surface -->