@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,186 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/terminal.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Persistent PTY Sessions
4
+
5
+ English | [中文](terminal.zh.md)
6
+
7
+ Types shared by PTY backends, `ctx.terminals`, and the model-facing consumer. The [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) owns the rationale; this page records the cross-package vocabulary from [`packages/terminal/terminal/src/types.ts`](../../packages/terminal/terminal/src/types.ts).
8
+
9
+ ## Identity and readiness
10
+
11
+ `TerminalSessionId` is a service-minted branded id. Optional names are owner-local display metadata; authorization compares the exact owning `Agent`, not a name or guessed id.
12
+
13
+ `TerminalWaitReason` says why one send returned. It is independent from `TerminalSessionStatus`: silence or timeout may return while the top-level shell remains alive, while `session_exit` means that shell exited rather than an arbitrary foreground child.
14
+
15
+ ```ts type-equiv
16
+ /** Why one interactive send returned control to its caller. */
17
+ type TerminalWaitReason = 'stdin_read' | 'inferred_idle' | 'timeout' | 'session_exit'
18
+ ```
19
+
20
+ ```ts type-equiv
21
+ /** Top-level PTY process status, independent of a send's wait reason. */
22
+ type TerminalSessionStatus =
23
+ | { kind: 'running' }
24
+ | { kind: 'exited'; exitCode: number | null; signal: NodeJS.Signals | null }
25
+ ```
26
+
27
+ ## Backend and live session
28
+
29
+ A backend owns how one registered type starts and detects readiness. `TerminalSessionService` publishes the returned session only after setup succeeds, then owns id authorization and cleanup. A backend that cannot clean partial startup resources rejects with `TerminalBackendCleanupError`, allowing disposal to retain the cleanup failure without replacing the caller's cancellation reason. A backend session owns terminal state and captured-resource quiescence.
30
+
31
+ ```ts type-equiv
32
+ /** Replaceable provider for one PTY session type. */
33
+ interface TerminalBackend {
34
+ /** Stable type selected by {@link TerminalSpawnRequest.type}. */
35
+ readonly type: string
36
+ /** Create an unpublished session or reject after cleaning partial resources; cleanup failure uses {@link TerminalBackendCleanupError}. */
37
+ spawn(spec: TerminalBackendSpawnSpec): Promise<TerminalBackendSession>
38
+ }
39
+ ```
40
+
41
+ ```ts type-equiv
42
+ /** Backend-owned live session retained by {@link TerminalSessionService}. */
43
+ interface TerminalBackendSession {
44
+ /** Initial bounded terminal output returned from `terminal_open`. */
45
+ readonly motd: string
46
+ /** Top-level process id when one exists. */
47
+ readonly pid?: number
48
+ /** Start one exclusive send operation. */
49
+ startSend(request: TerminalSendRequest): TerminalSendOperation
50
+ /** Read one bounded page from retained scrollback. */
51
+ read(request: TerminalReadRequest): TerminalReadResult
52
+ /** Signal the verified foreground process group. */
53
+ signal(signal: TerminalSignal): Promise<TerminalSignalResult>
54
+ /** Observe top-level process status. */
55
+ status(): TerminalSessionStatus
56
+ /** Idempotently close the captured owned process tree and await quiescence. */
57
+ close(reason: string): Promise<void>
58
+ }
59
+ ```
60
+
61
+ ## Send and retained output
62
+
63
+ One live session accepts one active send. Its operation exposes a consuming output cursor for generic background jobs and one terminal result for a foreground caller. `TerminalReadResult` separately pages the bounded session scrollback.
64
+
65
+ ```ts type-equiv
66
+ /** Live backend-owned send; exactly one may be active per PTY session. */
67
+ interface TerminalSendOperation {
68
+ /** Resolves after readiness, timeout, cancellation, or top-level process exit. */
69
+ done: Promise<TerminalSendResult>
70
+ /** Consume output produced since the prior call. */
71
+ readOutput(): TerminalSendRead
72
+ /** Request `SIGINT`; returns false after the operation settled. */
73
+ cancel(): boolean
74
+ }
75
+ ```
76
+
77
+ ```ts type-equiv
78
+ /** Settled result for one foreground or background send. */
79
+ interface TerminalSendResult {
80
+ /** Bounded rendered terminal delta remaining at settlement. */
81
+ viewport: string
82
+ /** Why the wait returned; this does not imply arbitrary child-process exit. */
83
+ waitReason: TerminalWaitReason
84
+ /** Top-level session status observed at settlement. */
85
+ sessionStatus: TerminalSessionStatus
86
+ /** Whether output was dropped from the operation or retained scrollback. */
87
+ truncated: boolean
88
+ }
89
+ ```
90
+
91
+ ## Ownership and durability
92
+
93
+ `TerminalSessionService` attaches one awaited cleanup to the exact owner scope, rejects foreign operations, and keeps sessions alive across backend or tool-plugin reload. PTY state and raw bytes remain process-local. Model input and bounded returned output are durable through the existing `tool/call`, `tool/result`, and task-result paths rather than duplicate PTY session events.
94
+
95
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
96
+
97
+ <a id="cordis-surface"></a>
98
+
99
+ ## Cordis API
100
+
101
+ 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).
102
+
103
+ <a id="ctxterminals--terminalsessionservice"></a>
104
+
105
+ ### `ctx.terminals` - `TerminalSessionService`
106
+
107
+ In-process registry for replaceable PTY backends and exact-Agent sessions.
108
+
109
+ ```ts cordis-catalog
110
+ /**
111
+ * Register one backend type for this effect scope.
112
+ * @param backend - provider with a non-empty unique type.
113
+ * @returns disposer that removes exactly this contribution.
114
+ */
115
+ registerBackend(backend: TerminalBackend): () => void
116
+
117
+ /**
118
+ * List registered backend types in registration order.
119
+ * @returns fresh backend type names.
120
+ */
121
+ listBackends(): string[]
122
+
123
+ /**
124
+ * Create and publish one owner-scoped session after backend setup succeeds.
125
+ * @param owner - exact registered Agent that owns access and cleanup.
126
+ * @param request - backend type plus optional owner-local name and cwd.
127
+ * @param signal - cancellation of unpublished setup.
128
+ * @returns published identity, metadata, status, and MOTD.
129
+ */
130
+ async spawn(owner: Agent, request: TerminalSpawnRequest, signal?: AbortSignal): Promise<TerminalSpawnResult>
131
+
132
+ /**
133
+ * Test whether an exact owner has a published session or unpublished spawn.
134
+ * @param owner - exact live owner to inspect.
135
+ * @returns true across the entire spawn-to-close interval, with no publication gap.
136
+ */
137
+ hasOwnerActivity(owner: Agent): boolean
138
+
139
+ /**
140
+ * Start one exclusive interactive send.
141
+ * @param owner - exact session owner.
142
+ * @param id - target PTY identity.
143
+ * @param request - explicit text, submit behavior, and cancellation.
144
+ * @returns live operation handle for foreground await or task registration.
145
+ */
146
+ startSend(owner: Agent, id: TerminalSessionId, request: TerminalSendRequest): TerminalSendOperation
147
+
148
+ /**
149
+ * Read one bounded scrollback page from an owned session.
150
+ * @param owner - exact session owner.
151
+ * @param id - target PTY identity.
152
+ * @param request - optional newest-relative offset and line count.
153
+ * @returns bounded retained text and pagination metadata.
154
+ */
155
+ read(owner: Agent, id: TerminalSessionId, request: TerminalReadRequest = {}): TerminalReadResult
156
+
157
+ /**
158
+ * Deliver an allowed signal through an owned backend session.
159
+ * @param owner - exact session owner.
160
+ * @param id - target PTY identity.
161
+ * @param signal - allowed POSIX signal name.
162
+ * @returns delivered foreground process-group identity.
163
+ */
164
+ signal(owner: Agent, id: TerminalSessionId, signal: TerminalSignal): Promise<TerminalSignalResult>
165
+
166
+ /**
167
+ * Close one owned session and remove it only after quiescent backend cleanup.
168
+ * @param owner - exact session owner.
169
+ * @param id - target PTY identity.
170
+ * @param reason - diagnostic cleanup reason.
171
+ * @returns true for a newly closed session, false when the same close is already in flight.
172
+ */
173
+ async kill(owner: Agent, id: TerminalSessionId, reason: string = 'model request'): Promise<boolean>
174
+
175
+ /**
176
+ * List fresh snapshots for exactly one owner.
177
+ * @param owner - exact owner whose sessions are visible.
178
+ * @returns owner-visible snapshots in publication order.
179
+ */
180
+ list(owner: Agent): TerminalSessionSnapshot[]
181
+ ```
182
+
183
+ Types: [Agent](core.md)
184
+
185
+ Source: [`packages/terminal/terminal/src/index.ts`](../../packages/terminal/terminal/src/index.ts)
186
+ <!-- END GENERATED cordis-surface -->
@@ -0,0 +1,34 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/todo.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Todo
4
+
5
+ English | [中文](todo.zh.md)
6
+
7
+ The durable todo vocabulary owned by [`@deepseek-ai/dsh-tool-todo`](../../packages/todo/tool-todo/README.md). The model-facing tool replaces one agent session's whole list; the package also owns the event declaration, replay projection, and invariant companion. Tool behavior and configuration are on the [package README](../../packages/todo/tool-todo/README.md).
8
+
9
+ Source: [`packages/todo/tool-todo/src/types.ts`](../../packages/todo/tool-todo/src/types.ts)
10
+
11
+ ## `TodoItem` - one list entry
12
+
13
+ ```ts type-equiv
14
+ /**
15
+ * One entry in an agent's todo list - the unit of the `todo/write`
16
+ * whole-list snapshot declared by this package.
17
+ *
18
+ * Deliberately minimal: a human-readable `content` line and a three-state
19
+ * `status`. No id, priority, or `activeForm` - the list is replaced wholesale
20
+ * on every write (last-write-wins), so entries need no stable identity. The
21
+ * three statuses describe the complete portable lifecycle needed by model and
22
+ * UI consumers.
23
+ */
24
+ interface TodoItem {
25
+ /** What this task is - a short imperative line shown in the UI. */
26
+ content: string
27
+ /** Lifecycle state. `in_progress` marks a task being worked now; parallel work may mark several. */
28
+ status: 'pending' | 'in_progress' | 'completed'
29
+ }
30
+ ```
31
+
32
+ ## Durable event and invariant
33
+
34
+ The package declaration-merges `todo/write: { todos: TodoItem[] }` into `SessionEventMap`. The event is log-only and carries the complete replacement list; the generated [persistence catalog](../persistence-catalog.md#todowrite--log-only) records its declaration site. The package's invariant companion validates existing and newly announced sessions in one pass, then tracks committed turn boundaries incrementally so every live `todo/write` is checked before append without rescanning the log.
@@ -0,0 +1,108 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/token-meter.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Token Meter
4
+
5
+ English | [中文](token-meter.zh.md)
6
+
7
+ `@deepseek-ai/dsh-token-meter` exposes one detached replay snapshot for request pressure and positional surface pricing. `logRevision` is the number of durable events consumed for every field in the measurement.
8
+
9
+ Source: [`packages/llm/token-meter/src/types.ts`](../../packages/llm/token-meter/src/types.ts)
10
+
11
+ ## `TokenMeasurement`
12
+
13
+ ```ts type-equiv
14
+ /** Detached immutable request-pressure and surface snapshot at one consumed log revision. */
15
+ interface TokenMeasurement {
16
+ /** Number of durable events consumed; equal to the next unread event seq. */
17
+ readonly logRevision: SessionLogOffset
18
+ /** Provider or heuristic anchor used for this measurement. */
19
+ readonly baseline: TokenMeasurementBaseline
20
+ /** Signed repricing of current surface content relative to the baseline anchor. */
21
+ readonly surfaceDeltaTokens: number
22
+ /** Non-negative current request-and-response pressure. */
23
+ readonly totalTokens: number
24
+ /** Total route-priced request tokens across the current surface; equals the sum of the node prices. */
25
+ readonly surfaceTokens: number
26
+ /** Current surface nodes in positional head-to-tail order. */
27
+ readonly nodes: readonly TokenSurfaceNode[]
28
+ }
29
+ ```
30
+
31
+ Every measurement resolves the effective envelope's routed provider/model to that route's declared request-image pricing through `ctx.llm`, so image occurrences are priced as the visual tokens plus model-visible text the request actually sends; routes and compositions without declared pricing keep the fixed heuristic. `baseline.kind === 'usage'` means the latest successful provider call has the same canonical request envelope and its total is no lower than that call's full route-priced anchor. `estimated` means no reusable conservative usage anchor exists, so the service priced the complete envelope and surface itself. A later successful request replaces the earlier anchor; signed `surfaceDeltaTokens` preserves growth and shrinkage relative to a matching anchor, repricing both sides under the same route. `totalTokens` remains request-and-response pressure, while `surfaceTokens` is the surface-only route-priced total and equals the sum of the node prices.
32
+
33
+ ## `TokenSurfaceNode`
34
+
35
+ ```ts type-equiv
36
+ /** One token-priced node in the current ordered session surface. */
37
+ interface TokenSurfaceNode {
38
+ /** Durable sequence number of the surface event. */
39
+ readonly seq: SessionSeq
40
+ /**
41
+ * Request-pressure tokens for the exact message projected by this node under
42
+ * the measured route: image occurrences carry the route's declared visual
43
+ * price when the routed adapter declares one, and the fixed heuristic
44
+ * otherwise. Trigger, retention, and range selection all read this price.
45
+ */
46
+ readonly tokens: number
47
+ /**
48
+ * Fixed-heuristic tokens for the same message, independent of any route.
49
+ * The shadow-price protocol prices replacements with this value so the O(1)
50
+ * projection fold stays in agreement with its own appends.
51
+ */
52
+ readonly heuristicTokens: number
53
+ }
54
+ ```
55
+
56
+ Surface order is authoritative; replacement nodes can have higher durable seqs than later positional nodes. The snapshot is immutable and does not grow when the underlying replay fold advances.
57
+
58
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
59
+
60
+ <a id="cordis-surface"></a>
61
+
62
+ ## Cordis API
63
+
64
+ 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).
65
+
66
+ <a id="ctxtokenmeter--tokenmeter"></a>
67
+
68
+ ### `ctx.tokenMeter` - `TokenMeter`
69
+
70
+ Replay owner for one service-wide estimator and isolated per-session folds.
71
+
72
+ ```ts cordis-catalog
73
+ /**
74
+ * Measure current request pressure and surface through the durable tail.
75
+ *
76
+ * The effective envelope's routed provider/model selects the request-image
77
+ * pricing every node is priced under: a route whose adapter declares image
78
+ * pricing charges each retained image its visual tokens plus its
79
+ * model-visible text, while other routes keep the fixed heuristic. Provider
80
+ * usage is reused only when the latest successful call's canonical request
81
+ * envelope matches `requestHeader` and its total is no lower than that
82
+ * call's full route-priced anchor; otherwise the complete envelope and
83
+ * surface are repriced. The anchor includes all surface nodes immediately
84
+ * before the assistant message, including inputs admitted after step/start.
85
+ *
86
+ * `requestHeader` replaces the latest logged envelope for pressure and node
87
+ * pricing; the node set always describes the current session surface. Every
88
+ * call clones those positional nodes, so measurement is O(surface).
89
+ *
90
+ * @param session - session to replay through its current durable tail.
91
+ * @param requestHeader - optional effective request envelope replacing the latest logged header.
92
+ * @returns a detached deeply immutable pressure and surface measurement.
93
+ */
94
+ measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
95
+
96
+ /**
97
+ * Heuristically price one model-visible message (instance face of the pure
98
+ * `estimateMessage` export from `estimate.ts`).
99
+ * @param message - message to price without mutation.
100
+ * @returns content and role-framing tokens under the fixed service heuristic.
101
+ */
102
+ estimateMessage(message: Message): number
103
+ ```
104
+
105
+ Types: [EpochHeader](session.md) · [Message](llm-streaming.md) · [Session](session.md)
106
+
107
+ Source: [`packages/llm/token-meter/src/index.ts`](../../packages/llm/token-meter/src/index.ts)
108
+ <!-- END GENERATED cordis-surface -->