@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,749 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/tools.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Tools
4
+
5
+ English | [中文](tools.zh.md)
6
+
7
+ The tool pipeline of [dsh-tools](../../packages/core/tools). [core.md](core.md) introduces `ToolDefinition` as the pipeline-authoring type shared by the core packages; the model-facing [`ToolSchema`](llm-streaming.md#the-model-request-and-result) wire type is declared with the model request. This page documents every `ToolDefinition` field, the typed schema DSL that builds it, the guarded execution types, and the UI-presentation types.
8
+
9
+ Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts) · [`packages/core/tools/src/schema.ts`](../../packages/core/tools/src/schema.ts) · [`packages/core/tools/src/presentation.ts`](../../packages/core/tools/src/presentation.ts)
10
+
11
+ ## `ToolDefinition` - a registered tool
12
+
13
+ A `ToolSchema` (the model-facing fields) plus a mandatory canonical output declaration, the `execute` function, host-only scheduler metadata, an optional final-content callback, and optional UI presenters. The registry holds these; the loop dispatches calls through them. The registry's `schemas()` builds the model-facing `ToolSchema[]` by an explicit allowlist - `output`/`execute`/`projectContent`/`finalizeContent`/`timeoutMs`/`isConcurrencySafe`/`presentCall`/`presentResult` must never leak into a model request.
14
+
15
+ ```ts type-equiv
16
+ /** Tool-owned canonical output contract used after the body returns a JSON value. */
17
+ interface ToolOutputDefinition {
18
+ /** Raw supported JSON Schema enforced against every successful canonical value. */
19
+ readonly schema: JsonSchemaNode
20
+ /** Pure projection from validated arguments and value to Native/model content. */
21
+ render(args: unknown, value: JsonValue): ContentBlock[]
22
+ /** Pure replayable presentation projection, computed only for top-level calls. */
23
+ presentationMeta?(args: unknown, value: JsonValue): JsonValue
24
+ }
25
+ ```
26
+
27
+ ```ts type-equiv
28
+ /** A registered tool: its schema plus the execution function. */
29
+ interface ToolDefinition extends ToolSchema {
30
+ /** Mandatory canonical output declaration. */
31
+ readonly output: ToolOutputDefinition
32
+ /**
33
+ * Run one accepted call and return only its canonical lossless-JSON value.
34
+ * Async work must observe or forward `exec.signal` and settle only after its
35
+ * owned work reaches quiescence. The registry preserves caller cancellation
36
+ * through around-dispatch signal replacement and does not abandon this
37
+ * promise, but it cannot hard-kill same-process code.
38
+ * @param args - losslessly snapshotted, frozen model arguments.
39
+ * @param exec - execution identity, cancellation signal, and context deferral.
40
+ * @returns the canonical value declared by `output.schema`.
41
+ */
42
+ execute(args: unknown, exec: ToolRunContext): Promise<unknown>
43
+ /**
44
+ * Install execution-prepared content before `tools/post-execute` policies.
45
+ * The callback is captured when the call starts and runs once for a
46
+ * normalized outcome entering post-execute. Policy replacements remain
47
+ * authoritative; pipeline failures that bypass post-execute skip projection.
48
+ * @param exec - immutable execution identity and arguments.
49
+ * @param result - normalized result before post-execute policy.
50
+ * @returns replacement content, or undefined to preserve the renderer output.
51
+ */
52
+ projectContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined
53
+ /**
54
+ * Synchronous last-mile transform for model-facing content. The registry
55
+ * snapshots this callback when execution starts and invokes it exactly once
56
+ * for every normalized outcome, including pipeline failures that bypass
57
+ * `tools/post-execute`, immediately before lossless materialization.
58
+ * Returning `undefined` preserves the content; every other result field
59
+ * remains registry-owned. The callback must be total and must not throw.
60
+ * @param exec - immutable execution identity and arguments.
61
+ * @param result - complete normalized outcome before materialization.
62
+ * @returns replacement content, or `undefined` to preserve it.
63
+ */
64
+ finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined
65
+ /**
66
+ * Cooperative tool-call timeout budget in milliseconds. Omit for no deadline.
67
+ * Enforced by `@deepseek-ai/dsh-tool-call-timeout-policy` (a `tools/execute` wrapper); it
68
+ * is NEVER sent to the model - `schemas()` whitelists only name/description/
69
+ * parameters. Declaring it asserts this tool forwards `exec.signal` to a
70
+ * cooperative implementation that can reach quiescence when the signal aborts.
71
+ */
72
+ timeoutMs?: number
73
+ /**
74
+ * Pure synchronous classifier for overlap with sibling tool calls. Only
75
+ * `true` opts in; omission, exceptions, non-`true` returns, and invalid
76
+ * `defineTool` arguments are exclusive. This metadata is never model-visible.
77
+ *
78
+ * Opted-in executions must not mutate parent-owned state. Shared state must
79
+ * tolerate concurrent dispatch; recorder races are permitted only when they
80
+ * commute or fail closed. See the
81
+ * [parallel-tool-call Agent Note](../../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)
82
+ * for the full contract.
83
+ * @param args - parsed arguments; `defineTool` validates before calling.
84
+ * @returns Whether this call may join a parallel group.
85
+ */
86
+ isConcurrencySafe?(args: unknown): boolean
87
+ /**
88
+ * Optional: how to present the PENDING state of one call in a UI, derived from
89
+ * the call's `args` (parsed arguments, `unknown` - the tool validates/narrows
90
+ * its own input). Returns a {@link ToolCallView} (a `card`-tagged render intent),
91
+ * or `undefined` (or omit the method) to fall back to a generic presentation
92
+ * (title = tool name, raw args as input). Pure and side-effect-free: a UI may
93
+ * call it during live streaming AND a session-log replay, so it must depend
94
+ * only on `args`.
95
+ */
96
+ presentCall?(args: unknown): ToolCallView | undefined
97
+ /**
98
+ * Optional: how to present the COMPLETED state, given the same `args` and the
99
+ * durable result projection (`content`, failure state, and optional `meta`). Returns a
100
+ * {@link ToolResultView}, or `undefined` (or omit the method) to keep the
101
+ * pending title and render the raw result content. Pure and side-effect-free
102
+ * for the same replay reason.
103
+ */
104
+ presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined
105
+ }
106
+ ```
107
+
108
+ `execute` receives `args: unknown` - a raw `ToolDefinition` validates its own input. First-party tools don't write that by hand; they use `defineTool`, which validates and narrows the arguments, infers the body return from `output.schema`, and types both output projectors. `finalizeContent` deliberately receives the immutable execution instead of typed arguments because invalid-input and outer pipeline failures reach it too; it may enforce a tool-owned content bound while preserving `isError`, canonical value, structured error identity, deferred contexts, and presentation metadata.
109
+
110
+ ## The unified JSON-value schema DSL
111
+
112
+ Plugin authors use one vocabulary for typed parameters and typed output values. `ValueSchemaSpec` supports `string`, `number`, `integer`, `boolean`, `null`, `array`, `object`, author-only `json`, and exact-one `oneOf`; scalar `enum` and `const` values must match their node type. An explicit object node always declares `additionalProperties: true | false`. Parameter definitions remain an implicit open object property map, with `required: true` attached to each required property.
113
+
114
+ Source: [`packages/core/tools/src/schema.ts`](../../packages/core/tools/src/schema.ts)
115
+
116
+ ```ts type-equiv
117
+ /** One author-facing schema for any lossless JSON value root. */
118
+ type ValueSchemaSpec =
119
+ | StringValueSchemaSpec
120
+ | NumberValueSchemaSpec
121
+ | IntegerValueSchemaSpec
122
+ | BooleanValueSchemaSpec
123
+ | NullValueSchemaSpec
124
+ | ArrayValueSchemaSpec
125
+ | ObjectValueSchemaSpec
126
+ | JsonValueSchemaSpec
127
+ | OneOfValueSchemaSpec
128
+ ```
129
+
130
+ ```ts type-equiv
131
+ /** One implicit parameter-root property, optionally required. */
132
+ type ParameterPropertySpec = ValueSchemaSpec & { required?: true }
133
+ ```
134
+
135
+ ```ts type-equiv
136
+ /**
137
+ * Tool parameter schema. The map itself is an implicit open object root;
138
+ * requiredness remains a per-property `required: true` annotation.
139
+ */
140
+ type ParameterSchemaSpec = {
141
+ [key: string]: ParameterPropertySpec
142
+ [key: symbol]: never
143
+ }
144
+ ```
145
+
146
+ `{ type: 'json' }` infers `JsonValue` and compiles to an annotation-only unconstrained raw schema. Output roots can be objects, arrays, scalars, or null. `InferValue<S>` honors literal constraints and object openness through 16 container levels, then falls back to `JsonValue` instead of exhausting TypeScript's type-instantiation stack. `InferArgs<P>` turns per-property requiredness into required and optional string keys:
147
+
148
+ ```ts type-equiv
149
+ /**
150
+ * Infer the TypeScript value accepted by an author-facing value schema. Exact
151
+ * inference is bounded to 16 container levels, then falls back to `JsonValue`.
152
+ */
153
+ type InferValue<S> = InferValueAt<S, []>
154
+ ```
155
+
156
+ ```ts type-equiv
157
+ /** Infer the TypeScript argument object for an implicit parameter schema. */
158
+ type InferArgs<S> = InferProperties<S, []>
159
+ ```
160
+
161
+ `defineTool({ name, description, parameters, output, execute, … })` ties parameter inference to `parameterSchemaSpecToJsonSchema()` and `validateArgs()`, and ties `execute`/`render`/`presentationMeta` to `InferValue<OutputSchema>`. Schema records contain only own enumerable string keys, and schema arrays are dense intrinsic arrays, so inference, compilation, and validation observe the same declaration. Inference stays exact through 16 container levels and then widens to `JsonValue`; runtime validation keeps walking the complete schema. `valueSchemaSpecToJsonSchema()` compiles output declarations through the same enforced raw subset. A parameter mismatch throws `ToolArgsError` (`INVALID_ARGS`); an invalid body or post-policy value throws `ToolOutputError` (`INVALID_TOOL_OUTPUT`). Both use the normal tool-error path. Raw JSON Schema remains open by default; unsupported keywords reject instead of being accepted without enforcement.
162
+
163
+ Registration is a trusted same-process contract. The registry borrows the typed definition as readonly input, requires `output`, validates its raw schema, and checks semantic requirements such as a positive finite `timeoutMs`; `schemas()` constructs the model-facing projection when building a request, so execution and presentation share one resolved definition without leaking callbacks onto the wire.
164
+
165
+ ## `ToolRestriction` - one scope's live filter over what it inherits
166
+
167
+ `ToolRestriction` applies to the tools a scope inherits: the deployment-global layer plus every ancestor scope on its chain. The registry compiles readonly names into private sets, intersects multiple restrictions, then overlays the scope's OWN registrations, which stay exempt so a delegated child keeps the tools it answers through. A deny-only filter admits later unlisted inherited tools, while an allow-list excludes them.
168
+
169
+ ```ts type-equiv
170
+ /**
171
+ * Per-scope filter over global tools. Restrictions intersect and do not affect
172
+ * scoped registrations or the reserved PTC mode transport.
173
+ */
174
+ interface ToolRestriction {
175
+ /** Global tool names that stay visible; everything else is removed. */
176
+ readonly allow?: readonly string[]
177
+ /** Global tool names removed from visibility. */
178
+ readonly deny?: readonly string[]
179
+ }
180
+ ```
181
+
182
+ ## Execution: extensible waterfalls plus monotonic policy
183
+
184
+ `ctx.tools.execute()` accepts a caller-owned `ToolExecutionInput` with a required readonly `signal`, materializes its parsed JSON arguments once into a pipeline-owned `ToolExecution`, and runs that call through `tools/pre-execute` (the reorderable allow/deny/ask waterfall) → registered monotonic guards → `tools/execute` (around-dispatch wrappers) → `projectContent` → `tools/post-execute` (inspect/replace the result) → optional definition-owned `finalizeContent` → `tools/result` (the immutable authoritative outcome). Only the `tools/execute` view may replace the required signal. The outcome is a `ToolExecutionResult`.
185
+
186
+ ```ts type-equiv
187
+ /** Opaque call identity that permits correlation without exposing mutable execution state. */
188
+ type ToolExecutionToken = symbol & { readonly [toolExecutionTokenBrand]: true }
189
+ ```
190
+
191
+ ```ts type-equiv
192
+ /**
193
+ * Caller-supplied description of one tool call. {@link ToolRuntime.execute}
194
+ * adds the registry-owned token to form a pipeline {@link ToolExecution};
195
+ * callers do not choose that token.
196
+ */
197
+ interface ToolExecutionInput {
198
+ readonly callId: ToolCallId
199
+ /**
200
+ * Root model-requested call owning this execution tree. Callers omit it for
201
+ * a root execution; nested dispatchers propagate the enclosing value.
202
+ */
203
+ readonly rootCallId?: ToolCallId
204
+ readonly name: string
205
+ /** Binding-time tool schema for a PTC inner call; frozen by its producer and never logged. */
206
+ readonly schema?: ToolSchema
207
+ /** Losslessly JSON-serializable parsed arguments (tools validate their own schema). */
208
+ readonly arguments: unknown
209
+ /** The agent on whose behalf the call runs (set by the agent loop). */
210
+ readonly agent?: Agent
211
+ /**
212
+ * Opaque token of the enclosing transport execution, when one exists. PTC
213
+ * mode sets this on SDK sub-dispatches so commit-style observers can wait for
214
+ * the outer `run_code` outcome without receiving its live mutable execution.
215
+ * The token also marks the call as a transport sub-dispatch rather than a
216
+ * model-direct call: under `mode: 'ptc'`, only calls WITH a parent may
217
+ * execute a native tool name - a model-direct call (no parent) is denied as
218
+ * `UNKNOWN_TOOL` before the policy pipeline. See {@link ToolRuntime.execute}.
219
+ */
220
+ readonly parent?: ToolExecutionToken
221
+ /** Required caller-owned cancellation for this invocation. */
222
+ readonly signal: AbortSignal
223
+ }
224
+ ```
225
+
226
+ A tool body receives the runtime extension. `deferContext()` attaches context to the execution's own result - the composite-tool nested-dispatch channel, also usable by a leaf tool minting a plugin-sourced instruction - without injecting inside the still-open outer call.
227
+
228
+ ```ts type-equiv
229
+ /**
230
+ * Runtime context handed to a tool implementation after the registry has
231
+ * accepted a {@link ToolExecution}. {@link deferContext} attaches context to
232
+ * this execution's own result - a composite tool ferries nested-dispatch
233
+ * context back to the outer result, and a leaf tool may mint a fresh
234
+ * plugin-sourced instruction; the loop appends it only after the
235
+ * `tool/result`.
236
+ */
237
+ interface ToolRunContext extends ToolExecution {
238
+ /**
239
+ * Defer one context - typically a nested-dispatch context ferried by a
240
+ * composite tool, or a fresh plugin-sourced instruction - until this tool's
241
+ * final result reaches the agent loop. Contexts retain their individual
242
+ * source and metadata and are emitted in call order.
243
+ */
244
+ deferContext(context: UserMessage): void
245
+ /**
246
+ * Mark a successful final result as terminal for the current agent turn.
247
+ * The marker rides this execution's own result (`concludesTurn` exists only
248
+ * on {@link ToolExecutionSuccess}); a composite that dispatches nested
249
+ * calls forwards it from the nested result, exactly like
250
+ * `additionalContexts`, so only an authoritative nested success can
251
+ * conclude the enclosing run.
252
+ */
253
+ concludeTurn(): void
254
+ }
255
+ ```
256
+
257
+ The agent loop asks the registry for each pending call's execution mode and uses it to form exclusive barriers and rolling-pool parallel runs:
258
+
259
+ ```ts type-equiv
260
+ /**
261
+ * Scheduling mode for one pending call. `parallel` may overlap with siblings;
262
+ * `exclusive` runs alone and forms an ordering barrier.
263
+ */
264
+ type ToolExecutionMode =
265
+ | { kind: 'parallel' }
266
+ | { kind: 'exclusive' }
267
+ ```
268
+
269
+ PTC bindings freeze their ToolSchema at construction and pass it through the scheduler into `ToolExecution.schema`; it is transient execution metadata. Before policy, each actually started sub-dispatch records only pairing ids, name, and normalized arguments. Neither start nor settle events serialize description, parameters, or schema. The bridge later exposes the settled call to the `tools/ptc-dispatch-log` waterfall, which may change the durable content copy while preserving the program value, model-visible outer result, and structured failure identity:
270
+
271
+ ```ts type-equiv
272
+ /**
273
+ * One settled `run_code` sub-dispatch about to be logged, as seen by the
274
+ * `tools/ptc-dispatch-log` waterfall: the parent execution (session owner,
275
+ * outer call identity), the sub-call identity, and the outcome whose durable
276
+ * copy a listener may reshape. `content` is the RENDERED result projection
277
+ * (what a native `tool/result` would carry) - the program itself received
278
+ * the structured `value` (or just the error message on failure); only the
279
+ * `tool/ptc-dispatch` event's copy changes.
280
+ */
281
+ interface PtcDispatchLog {
282
+ /** The outer `run_code` execution. */
283
+ readonly exec: ToolExecution
284
+ /** The calling agent (the scope routing key and the spill owner), when the outer call has one. */
285
+ readonly agent?: Agent
286
+ /** Opaque sub-call id; new calls use `<parent>:ptc:<n>`. */
287
+ readonly subCallId: ToolCallId
288
+ /** The dispatched sub-tool name. */
289
+ readonly name: string
290
+ /** Whether the sub-call settled as an error. */
291
+ readonly isError: boolean
292
+ /** The sub-call's complete model-facing content (the settle event's default payload). */
293
+ readonly content: ContentBlock[]
294
+ }
295
+ ```
296
+
297
+ ```ts type-equiv
298
+ /**
299
+ * One pending tool call inside the registry pipeline. Parsed arguments cross
300
+ * one lossless-JSON materialization boundary before policy and are deep-frozen;
301
+ * call identity, the caller signal, and the registry-assigned {@link token} are
302
+ * readonly. The registry freezes the complete object before `tools/result`
303
+ * observers run.
304
+ */
305
+ interface ToolExecution extends ToolExecutionInput {
306
+ /** Root model-requested call, resolved for every root and nested execution. */
307
+ readonly rootCallId: ToolCallId
308
+ /** Registry-assigned identity shared with nested calls only as their opaque `parent` token. */
309
+ readonly token: ToolExecutionToken
310
+ }
311
+ ```
312
+
313
+ ```ts type-equiv
314
+ /**
315
+ * Around-dispatch view of a {@link ToolExecution}. A `tools/execute` wrapper
316
+ * may replace the signal for its delegated lifetime, but it cannot remove it.
317
+ * The registry fuses every replacement with the captured caller signal.
318
+ */
319
+ interface ToolDispatchExecution extends Omit<ToolExecution, 'signal'> {
320
+ /** Cancellation signal visible to the next wrapper or tool body. */
321
+ signal: AbortSignal
322
+ }
323
+ ```
324
+
325
+ `ToolExecutionToken` is an opaque runtime `Symbol` used only for identity comparison. Before policy, `execute()` materializes and freezes arguments, rejects non-JSON input, and assigns the token. Identity fields, the required caller signal, and the optional parent token remain readonly. A `ToolDispatchExecution` wrapper may replace but not remove the signal; the registry re-fuses the caller signal before invoking the body. Final observers receive the frozen execution identity.
326
+
327
+ A `ToolGuard` is scope-aware final pre-dispatch policy. Its return type deliberately has no allow result: `undefined` preserves the waterfall decision, while a returned reason can only reduce permission, so a later listener cannot undo it.
328
+
329
+ ```ts type-equiv
330
+ /**
331
+ * A monotonic execution guard evaluated after every `tools/pre-execute`
332
+ * listener and before the tool body. Returning a reason denies the call;
333
+ * returning `undefined` leaves it unchanged. Because guards have no allow
334
+ * result, listener ordering cannot turn a denial back into permission.
335
+ * @param execution - the identity-protected call after extensible pre-execute policy completed.
336
+ * @returns a final denial reason, or `undefined` to leave the call allowed.
337
+ */
338
+ type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined
339
+ ```
340
+
341
+ ```ts type-equiv
342
+ /** Canonical failure detail; internal routing information remains optional. */
343
+ interface ToolFailure {
344
+ /** Human-readable failure message without the Native `Error: ` envelope. */
345
+ message: string
346
+ /** Internal error class/code used by policy and durable diagnostics. */
347
+ info?: ToolErrorInfo
348
+ }
349
+ ```
350
+
351
+ ```ts type-equiv
352
+ /** Successful canonical tool execution, including its Native/model projection. */
353
+ interface ToolExecutionSuccess {
354
+ readonly isError: false
355
+ /** Execution-local canonical value; deliberately omitted from durable events. */
356
+ readonly value: JsonValue
357
+ readonly content: ContentBlock[]
358
+ readonly error?: never
359
+ readonly meta?: JsonValue
360
+ readonly additionalContexts?: UserMessage[]
361
+ /** The agent loop stops after committing this successful result batch. */
362
+ readonly concludesTurn?: true
363
+ }
364
+ ```
365
+
366
+ ```ts type-equiv
367
+ /** Failed canonical tool execution; failures never carry a successful value. */
368
+ interface ToolExecutionFailure {
369
+ readonly isError: true
370
+ readonly error: ToolFailure
371
+ readonly value?: never
372
+ readonly content: ContentBlock[]
373
+ readonly meta?: JsonValue
374
+ readonly additionalContexts?: UserMessage[]
375
+ readonly concludesTurn?: never
376
+ }
377
+ ```
378
+
379
+ ```ts type-equiv
380
+ /** The discriminated, execution-local outcome of one tool call. */
381
+ type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure
382
+ ```
383
+
384
+ ```ts type-equiv
385
+ /** Structured error metadata for a failed tool call (alongside the model-facing text). */
386
+ interface ToolErrorInfo {
387
+ name: string
388
+ code: string
389
+ /** Optional raw user-facing detail; durable projections preserve it but model-facing content does not include it. */
390
+ reason?: string
391
+ }
392
+ ```
393
+
394
+ The result carries only the outcome. Call identity remains on the immutable `ToolExecution` that accompanies it through every hook and on the durable `tool/call` / `tool/result` session events, so wrappers cannot create a second, disagreeing identity. The canonical `value` is execution-local: the loop persists only `content`, `error`, and `meta`, while `tool/ptc-dispatch` stores the sub-call's rendered `content`, `isError`, and optional structured `error`. Replay reproduces presentation but cannot reconstruct canonical intermediate values. Optional `ToolErrorInfo.reason` retains raw user-facing detail without adding it to model-facing content.
395
+
396
+ On success the registry snapshots and validates the body value, freezes it, and invokes the pure renderer plus the optional top-level-call metadata projector. It separately materializes the durable presentation fields immediately before `tools/result`; an invalid value, renderer/projector failure, or non-JSON presentation becomes a JSON-safe `isError`. The final live observer therefore sees the exact execution-local value beside fields safe for the later durable append.
397
+
398
+ Before final content, the registry materializes the candidate result; a failure in content, structured error, additional context, or presentation metadata becomes a JSON-safe `isError` result that still reaches `finalizeContent`. The registry invokes that callback exactly once, then materializes and freezes the accepted result immediately before `tools/result`, so the observed live outcome is safe for the later durable `tool/result` append.
399
+
400
+ Each interception waterfall returns a typed **Decision** (the idiom shared with the `agent/*` waterfalls). `tools/pre-execute` listeners receive `(exec, next)` and return a `PreToolDecision`; `tools/execute` wrappers return a `ToolExecutionResult`; `tools/post-execute` listeners receive `(exec, result, next)` and return a `PostToolDecision`:
401
+
402
+ ```ts type-equiv
403
+ /**
404
+ * Pre-dispatch decision. `allow` runs the call; `deny` materializes its
405
+ * model-facing reason and optional structured error identity; `cancel` selects
406
+ * the canonical cancellation result without presenting a policy denial; `ask`
407
+ * runs only after an approval service returns `allowed-once` and otherwise
408
+ * denies; its `reason` is the audited approval reason and its optional
409
+ * `displayReason` is the localized prompt text. Input rewriting is excluded because arguments are already logged and
410
+ * presented.
411
+ */
412
+ type PreToolDecision =
413
+ | { kind: 'allow' }
414
+ | { kind: 'deny'; reason: string; info?: ToolErrorInfo }
415
+ | { kind: 'cancel' }
416
+ | { kind: 'ask'; reason?: string; displayReason?: { readonly en: string; readonly [locale: string]: string } }
417
+ ```
418
+
419
+ ```ts type-equiv
420
+ /**
421
+ * Post-dispatch decision: accept, replace one projection, attach context for the
422
+ * next request, or block by turning corrective feedback into an error result.
423
+ */
424
+ type PostToolDecision =
425
+ | { kind: 'accept'; content?: ContentBlock[]; value?: never; additionalContexts?: UserMessage[] }
426
+ | { kind: 'accept'; value: JsonValue; content?: never; additionalContexts?: UserMessage[] }
427
+ | { kind: 'block'; feedback: ContentBlock[]; additionalContexts?: UserMessage[] }
428
+ ```
429
+
430
+ Call `next()` for the default or return a decision to short-circuit. Pre-policy may deny or ask; only `allowed-once` proceeds, while a non-grant, missing approval channel or service, or agent-less request becomes a denial. A deny may attach structured identity and user-facing detail without changing its model-facing reason. Guards may still impose a final denial. Arguments cannot be rewritten because history, audit, UI, and execution must agree.
431
+
432
+ Post-policy may replace either content or value, never both. Content replacement preserves the canonical value and existing metadata; value replacement is revalidated and recomputes content/metadata; a block removes the value and becomes an `isError` containing corrective feedback. Content replacement is presentation policy, not confidentiality policy: a listener that must hide the programmatic value blocks or replaces it. `tools/result` receives the frozen execution and result after normalization; observers cannot transform them, and observer failures are contained. Unknown and throwing tools both become structured errors (`ToolNotFoundError` maps to `UNKNOWN_TOOL`), so the call fails without ending the turn.
433
+
434
+ ## The enforced raw JSON Schema subset
435
+
436
+ Raw schemas from subagents, workflows, MCP, and dynamic registrations use the wire-level counterpart of the author DSL. `assertSupportedJsonSchema()` accepts any JSON root, `validateJsonSchemaValue()` enforces it, and `JsonSchemaError` reports every unsupported or malformed schema path. The empty annotation-only node means unconstrained lossless JSON. `oneOf` requires at least two branches and a value must match exactly one. Consumers that still require an object root call `assertObjectJsonSchema()` and carry `ObjectJsonSchema`; this is how subagent/workflow caller-defined structured output remains object-rooted without restricting the shared vocabulary.
437
+
438
+ ```ts type-equiv
439
+ /** Scalar JSON values supported by `enum` and `const`. */
440
+ type JsonSchemaScalar = string | number | boolean | null
441
+ ```
442
+
443
+ ```ts type-equiv
444
+ /** Single-type keywords accepted by the enforced subset. */
445
+ type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'
446
+ ```
447
+
448
+ ```ts type-equiv
449
+ /**
450
+ * One raw JSON Schema node in the enforced subset. The optional fields express
451
+ * the external wire schema; {@link assertSupportedJsonSchema} rejects invalid
452
+ * combinations before a caller treats the node as trusted.
453
+ */
454
+ interface JsonSchemaNode {
455
+ /** Omit with no constraints for any JSON value, or use `oneOf`. */
456
+ type?: JsonSchemaType
457
+ /** Exactly one branch must validate; at least two branches are required. */
458
+ oneOf?: JsonSchemaNode[]
459
+ /** Nested property schemas (`type: 'object'` only). */
460
+ properties?: Record<string, JsonSchemaNode>
461
+ /** Required property names; each must appear in `properties`. */
462
+ required?: string[]
463
+ /** `false` rejects undeclared keys; absent/`true` follows JSON Schema's open default. */
464
+ additionalProperties?: boolean
465
+ /** Item schema (`type: 'array'` only); absent accepts any JSON item. */
466
+ items?: JsonSchemaNode
467
+ /** Allowed values for a scalar node. */
468
+ enum?: JsonSchemaScalar[]
469
+ /** The single allowed value for a scalar node. */
470
+ const?: JsonSchemaScalar
471
+ /** Annotation, ignored for validation. */
472
+ description?: string
473
+ /** Annotation, ignored for validation. */
474
+ title?: string
475
+ /** Annotation, ignored for validation but required to be lossless JSON. */
476
+ default?: JsonValue
477
+ /** Annotation, ignored for validation but required to be lossless JSON. */
478
+ examples?: JsonValue
479
+ }
480
+ ```
481
+
482
+ ```ts type-equiv
483
+ /** A consumer-constrained object-rooted schema. */
484
+ type ObjectJsonSchema = JsonSchemaNode & { type: 'object' }
485
+ ```
486
+
487
+ ## Tool-presentation UI vocabulary
488
+
489
+ How a tool wants its call shown in a UI (an editor tool-call card, a CLI log line), provider-neutral so a tool describes itself without depending on any client protocol. `presentCall`/`presentResult` return a **`card`-tagged render intent** - a discriminated union a UI bridge switches on:
490
+
491
+ - `ToolCallView` (pending): `{ card: 'generic', title, kind?, rawInput?, content?, locations? }` (the default card; `locations` is `{ path, line? }[]` files the call reads/modifies, for editor follow-along), `{ card: 'terminal', title, description?, cwd? }` (a shell command → a terminal card), or `{ card: 'diff', title, diffs, locations? }` (a file create/modify → an inline diff card; `diffs` is `{ path, oldText, newText }[]`, `oldText: null` for a new file).
492
+ - `ToolResultView` (completed): `{ card: 'generic', title?, content? }`, `{ card: 'terminal', title?, output?, exitCode?, signal? }` (the captured run output + exit; a capable UI shows an exit-status pill, while another may derive a fenced ` ```console ` fallback), `{ card: 'diff', title?, diffs }` (a completed file mutation → the change to show, typically the applied hunks with context lines computed from the before/after content, or a whole-file diff when there is no before-image), `{ card: 'search', shape, title?, truncated, total, … }` (a completed discovery search → grouped-by-file matches for `shape: 'matches'` (grep) or a flat path list for `shape: 'paths'` (glob); `truncated`/`total` report whether the inline result was capped so a UI never presents a partial result as complete; the view carries no result text - a UI without a search card falls back to the raw result content), `{ card: 'read', title?, path, offset, lines, totalLines, lang?, content? }` (a completed file read → a line-numbered, optionally syntax-highlighted code view; `offset` is the 1-based first line the window requested, kept even when `lines` is empty; `lang` is a language hint from the extension, and `content` is the envelope-stripped text a UI without read support falls back to), or `{ card: 'web', kind: 'search' | 'fetch', title?, … }` (a completed web retrieval; `kind: 'search'` carries the structured `sources`/`answer?`/`truncated`, `kind: 'fetch'` carries `url`/`statusCode`/`truncated`, and a UI without the `web` capability falls back to the raw result content - the body is not duplicated into the view). Completed views replace pending views, so mutation tools return a diff result even when it duplicates the call-time snippet; a search and a web retrieval have no `card` call-time analogue (their pending state stays a generic card, since the structured result exists only after `execute`).
493
+
494
+ `ToolCallKind` (`'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other'`) picks an icon on a generic card. `FileLocation` (`{ path, line? }`), `FileDiff` (`{ path, oldText, newText }`), and `ReadFileLine` (`{ number, text }`, one 1-based numbered line of a read window) are the shared file-card vocabulary. The design is pinned in [the render-intent-union Agent Note](../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md); host/client runtimes project this neutral vocabulary into their own views.
495
+
496
+ The full presentation field docs live in [`packages/core/tools/src/presentation.ts`](../../packages/core/tools/src/presentation.ts). The `bash` schema and executor are on [shell.md](shell.md); generic background controls are on [jobs.md](jobs.md).
497
+
498
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
499
+
500
+ <a id="cordis-surface"></a>
501
+
502
+ ## Cordis API
503
+
504
+ 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).
505
+
506
+ <a id="ctxtools--toolruntime"></a>
507
+
508
+ ### `ctx.tools` - `ToolRuntime`
509
+
510
+ Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.
511
+
512
+ ```ts cordis-catalog
513
+ /**
514
+ * Present the calling scope's tools in `mode` instead of the deployment
515
+ * default. Nearest scope on the chain wins, so a preset's standing
516
+ * declaration covers every agent joined under it.
517
+ *
518
+ * Scoped only, and one declaration per scope: this is how an agent preset
519
+ * composes PTC mode agents beside native ones in the same process, and a
520
+ * process-global override would be the `mode` config field instead.
521
+ * @param mode - the presentation the covered agents' models see.
522
+ * @returns the exact disposer that restores the deployment default.
523
+ */
524
+ presentAs(mode: ToolPresentationMode): () => void
525
+
526
+ /**
527
+ * Register globally or in the calling agent scope. Scoped tools shadow
528
+ * globals; duplicates within one layer and the reserved `run_code` name fail.
529
+ * @param definition - tool schema, execution, and optional finalization/presentation callbacks.
530
+ * @returns the exact disposer that unregisters the tool.
531
+ */
532
+ register(definition: ToolDefinition): () => void
533
+
534
+ /**
535
+ * Restrict global tools for the calling agent scope. Empty filters, unknown
536
+ * names, scope-local names, and reserved transport names fail. Restrictions
537
+ * intersect; scoped registrations remain visible.
538
+ * @param filter - global-tool mask: `allow` (keep only) and/or `deny` (remove).
539
+ * @returns the exact disposer that lifts this restriction.
540
+ */
541
+ restrict(filter: ToolRestriction): () => void
542
+
543
+ /**
544
+ * Register a monotonic guard after the extensible `tools/pre-execute`
545
+ * waterfall. A plain-context guard applies globally; one registered through
546
+ * `agent.ctx` applies only to that agent. Any matching guard may deny by
547
+ * returning a reason, while no guard can force-allow a call another guard
548
+ * denied. The exact effect disposer is returned for ordered ownership and
549
+ * HMR cleanup.
550
+ * @param guard - synchronous check; a returned string denies the execution.
551
+ * @returns the exact disposer that unregisters the guard.
552
+ */
553
+ guard(guard: ToolGuard): () => void
554
+
555
+ /**
556
+ * Look up a tool as one scope sees it (scoped
557
+ * shadows global; a restricted-away global reads as absent). Presenters pass
558
+ * the calling agent so the rendered card matches the definition that
559
+ * actually executed.
560
+ * @param name - the tool name as registered.
561
+ * @param scope - the viewing scope (the agent); omitted = the global view.
562
+ * @returns the definition the scope resolves, or undefined when none is visible.
563
+ */
564
+ get(name: string, scope?: ScopeKey): ToolDefinition | undefined
565
+
566
+ /**
567
+ * Project visible definitions onto the allowlisted model-facing schema fields,
568
+ * excluding execution and presentation callbacks.
569
+ * @param scope - the viewing scope (the agent); omitted = the global view.
570
+ * @returns one deep-cloned schema per visible tool.
571
+ */
572
+ schemas(scope?: ScopeKey): ToolSchema[]
573
+
574
+ /**
575
+ * Classify a pending call through the caller's visible tool definition. Only
576
+ * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or
577
+ * throwing classifiers are exclusive.
578
+ * @param exec - call name, parsed arguments, and optional agent scope.
579
+ * @returns the fail-closed scheduling mode.
580
+ */
581
+ executionMode(exec: ToolExecutionInput): ToolExecutionMode
582
+
583
+ /**
584
+ * Execute through pre-policy, guards, around-dispatch, post-policy,
585
+ * definition-owned content finalization, and final notification. Tool and
586
+ * listener failures resolve as materialized error results; an invisible tool
587
+ * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen
588
+ * snapshot final observers receive. Cancellation
589
+ * arriving after entry and before final result materialization skips a
590
+ * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a
591
+ * successful started outcome with `ABORTED`; already-started work is still
592
+ * drained and may retain a tool-owned structured error.
593
+ * @param exec - the typed same-process call input. The registry assigns its
594
+ * correlation token before policy begins.
595
+ * @returns the materialized final result.
596
+ */
597
+ async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
598
+ ```
599
+
600
+ Types: [ScopeKey](scope.md)
601
+
602
+ Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
603
+
604
+ <a id="tools-events"></a>
605
+
606
+ ### `tools/*` events
607
+
608
+ <a id="toolschange--emit"></a>
609
+
610
+ #### `tools/change` - emit
611
+
612
+ A tool was registered or unregistered, or a scoped restriction changed (the available tool set changed - possibly for one scope only). An UNFILTERED registry-subject notification, deliberately not scope-filtered dispatch: a global change concerns every agent's next assembly, so a scoped listener subscribing here sees every change, not just its own scope's.
613
+
614
+ ```ts cordis-catalog
615
+ /**
616
+ * A tool was registered or unregistered, or a scoped restriction changed
617
+ * (the available tool set changed - possibly for one scope only). An
618
+ * UNFILTERED registry-subject notification, deliberately not scope-filtered
619
+ * dispatch: a global change concerns every agent's next assembly, so a
620
+ * scoped listener subscribing here sees every change, not just its own
621
+ * scope's.
622
+ * @mode emit
623
+ */
624
+ 'tools/change'(): void
625
+ ```
626
+
627
+ Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
628
+
629
+ <a id="toolsexecute--waterfall"></a>
630
+
631
+ #### `tools/execute` - waterfall
632
+
633
+ Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a normalized result; wrappers may change only `exec.signal`, while call identity remains immutable. The registry re-fuses the original caller signal before the body, so replacement cannot detach caller cancellation; wrappers must still restore their signal and reach quiescence. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
634
+
635
+ ```ts cordis-catalog
636
+ /**
637
+ * Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns
638
+ * a normalized result; wrappers may change only `exec.signal`, while call
639
+ * identity remains immutable. The registry re-fuses the original caller
640
+ * signal before the body, so replacement cannot detach caller cancellation;
641
+ * wrappers must still restore their signal and reach quiescence.
642
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
643
+ * @param exec - the allowed call about to dispatch (name, parsed arguments, caller agent, signal).
644
+ * @mode waterfall
645
+ */
646
+ 'tools/execute'(this: Scoped<ToolRuntime>, exec: ToolDispatchExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>
647
+ ```
648
+
649
+ Types: [Scoped](scope.md)
650
+
651
+ Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
652
+
653
+ <a id="toolspost-execute--waterfall"></a>
654
+
655
+ #### `tools/post-execute` - waterfall
656
+
657
+ Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts it unchanged; thrown tools still reach this waterfall as errors. Async listeners must observe `exec.signal`; after they settle, caller cancellation replaces only a successful accepted outcome with the code selected by whether the tool body was invoked. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
658
+
659
+ ```ts cordis-catalog
660
+ /**
661
+ * Accept, replace, enrich, or block a normalized dispatch result. `next()`
662
+ * accepts it unchanged; thrown tools still reach this waterfall as errors. Async
663
+ * listeners must observe `exec.signal`; after they settle, caller
664
+ * cancellation replaces only a successful accepted outcome with the code
665
+ * selected by whether the tool body was invoked.
666
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
667
+ * @param exec - the call that just ran (name, parsed arguments, caller agent).
668
+ * @param result - the dispatch outcome a listener may accept, replace, or block.
669
+ * @mode waterfall
670
+ */
671
+ 'tools/post-execute'(this: Scoped<ToolRuntime>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>
672
+ ```
673
+
674
+ Types: [Scoped](scope.md)
675
+
676
+ Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
677
+
678
+ <a id="toolspre-execute--waterfall"></a>
679
+
680
+ #### `tools/pre-execute` - waterfall
681
+
682
+ Allow, deny, cancel, or ask before dispatch. `next()` delegates to allow; `cancel` selects the canonical pre-dispatch cancellation result, and missing approval support turns `ask` into denial. Async gates must observe `exec.signal`; the registry rechecks cancellation after they settle but never abandons their promise. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
683
+
684
+ ```ts cordis-catalog
685
+ /**
686
+ * Allow, deny, cancel, or ask before dispatch. `next()` delegates to allow;
687
+ * `cancel` selects the canonical pre-dispatch cancellation result, and missing
688
+ * approval support turns `ask` into denial. Async gates must observe
689
+ * `exec.signal`; the registry rechecks cancellation after they settle but
690
+ * never abandons their promise.
691
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
692
+ * @param exec - the pending call (name, parsed arguments, caller agent).
693
+ * @mode waterfall
694
+ */
695
+ 'tools/pre-execute'(this: Scoped<ToolRuntime>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>
696
+ ```
697
+
698
+ Types: [Scoped](scope.md)
699
+
700
+ Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
701
+
702
+ <a id="toolsptc-dispatch-log--waterfall"></a>
703
+
704
+ #### `tools/ptc-dispatch-log` - waterfall
705
+
706
+ Allow a listener to replace content in the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bridge appends its `tool/ptc-dispatch` event. `next()` keeps the content unchanged; a listener may return replacement blocks (e.g. the spill policy's preview + locator for an oversized text result). Only the logged copy is affected - the program already received the complete value, and the model sees neither. A throwing listener is contained: the bridge falls back to logging the original settled content. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's dispatches.
707
+
708
+ ```ts cordis-catalog
709
+ /**
710
+ * Allow a listener to replace content in the DURABLE LOG COPY of one
711
+ * `run_code` sub-dispatch outcome before the bridge appends its
712
+ * `tool/ptc-dispatch` event. `next()` keeps the
713
+ * content unchanged; a listener may return replacement blocks (e.g. the
714
+ * spill policy's preview + locator for an oversized text result). Only the
715
+ * logged copy is affected - the program already received the complete
716
+ * value, and the model sees neither. A throwing listener is contained:
717
+ * the bridge falls back to logging the original settled content.
718
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's dispatches.
719
+ * @param dispatch - the parent execution, sub-call identity, and the settled content to log.
720
+ * @mode waterfall
721
+ */
722
+ 'tools/ptc-dispatch-log'(this: Scoped<ToolRuntime>, dispatch: PtcDispatchLog, next: () => Promise<ContentBlock[]>): Promise<ContentBlock[]>
723
+ ```
724
+
725
+ Types: [ContentBlock](llm-streaming.md) · [Scoped](scope.md)
726
+
727
+ Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
728
+
729
+ <a id="toolsresult--emit"></a>
730
+
731
+ #### `tools/result` - emit
732
+
733
+ Observe the frozen, lossless-JSON final outcome. Listener failures are contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
734
+
735
+ ```ts cordis-catalog
736
+ /**
737
+ * Observe the frozen, lossless-JSON final outcome. Listener failures are contained.
738
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
739
+ * @param exec - the execution object that traversed the pipeline.
740
+ * @param result - a deep-frozen snapshot of the final returned result.
741
+ * @mode emit
742
+ */
743
+ 'tools/result'(this: Scoped<ToolRuntime>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): undefined
744
+ ```
745
+
746
+ Types: [Scoped](scope.md)
747
+
748
+ Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
749
+ <!-- END GENERATED cordis-surface -->