@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,315 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/goal.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Same-session goals
4
+
5
+ English | [中文](goal.zh.md)
6
+
7
+ Types shared by the event-sourced goal service and its policy consumers. The [goal-domain Agent Note](../../.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md) owns the persistence and activation decisions; this page records the exact fields and variants from [`packages/goal/goal/src/types.ts`](../../packages/goal/goal/src/types.ts).
8
+
9
+ ## Identity and lifecycle
10
+
11
+ `GoalId` is a [branded id](core.md#branded-ids). A caller mutates one exact revision through `GoalRef`; every accepted durable mutation increments the revision.
12
+
13
+ ```ts type-equiv
14
+ /** Compare-and-set identity for one exact goal revision. */
15
+ interface GoalRef {
16
+ /** Stable goal identity. */
17
+ readonly id: GoalId
18
+ /** Positive revision; every durable mutation increments it. */
19
+ readonly revision: number
20
+ }
21
+ ```
22
+
23
+ The durable phase answers what happened to the objective. Process-local activation separately answers whether a continuation consumer may start another round.
24
+
25
+ ```ts type-equiv
26
+ /** Durable continuation phase. Activation is process-local and separate. */
27
+ type GoalPhase =
28
+ | 'active'
29
+ | 'paused'
30
+ | 'blocked'
31
+ | 'complete'
32
+ ```
33
+
34
+ Blocking is the single durable stopped-by-a-problem state. Its policy-owned reason carries a stable lower-kebab-case code for routing and a free-form explanation for humans and models.
35
+
36
+ ```ts type-equiv
37
+ /** Machine-routable and human-readable explanation for a blocked goal. */
38
+ interface GoalBlockReason {
39
+ /** Stable lower-kebab-case classification chosen by the blocking policy. */
40
+ readonly code: string
41
+ /** Non-empty explanation shown to humans and models. */
42
+ readonly message: string
43
+ }
44
+ ```
45
+
46
+ ```ts type-equiv
47
+ /** Full durable state written by every non-clear goal mutation. */
48
+ interface GoalSnapshot extends GoalRef {
49
+ /** Human-requested completion objective. */
50
+ readonly objective: string
51
+ /** Durable lifecycle phase. */
52
+ readonly phase: GoalPhase
53
+ /** Present exactly while `phase` is `blocked`. */
54
+ readonly blockedReason?: GoalBlockReason
55
+ /** Total admitted goal-round cap. */
56
+ readonly maxGoalRounds: number
57
+ }
58
+ ```
59
+
60
+ ```ts type-equiv
61
+ /** Current goal projection, including values derived from the session log. */
62
+ interface GoalView extends GoalSnapshot {
63
+ /** Highest admitted round number for this goal. */
64
+ readonly roundsStarted: number
65
+ /** Epoch milliseconds of the create mutation. */
66
+ readonly createdAt: number
67
+ /** Epoch milliseconds of the latest mutation. */
68
+ readonly updatedAt: number
69
+ /** Process-local continuation eligibility; never persisted. */
70
+ readonly activation: GoalActivation
71
+ }
72
+ ```
73
+
74
+ The service also publishes process-local activation edges without changing durable state; clients consume this event for live status.
75
+
76
+ ```ts type-equiv
77
+ /** Live process-local activation update forwarded to UI clients. */
78
+ interface GoalActivationChanged {
79
+ /** Session whose live goal activation changed. */
80
+ readonly sessionId: SessionId
81
+ /** Current exact activation, absent when no goal is current. */
82
+ readonly goal?: {
83
+ /** Exact current goal identity. */
84
+ readonly id: GoalId
85
+ /** Exact current goal revision. */
86
+ readonly revision: number
87
+ /** Current process-local continuation state. */
88
+ readonly activation: GoalActivation
89
+ }
90
+ }
91
+ ```
92
+
93
+ ## Durable changes
94
+
95
+ Every mutation is a durable `goal/change` session event whose payload is either a complete post-mutation snapshot or a clear tombstone. The strict fold and persisted projection derive lifecycle state only from these events; inbox mutations do not affect goal state.
96
+
97
+ ```ts type-equiv
98
+ /** Full-snapshot goal mutation committed by a durable `goal/change` event. */
99
+ interface GoalSnapshotChangeMeta {
100
+ readonly kind: 'goal/change'
101
+ readonly version: 1
102
+ readonly operation: Exclude<GoalOperation, 'clear'>
103
+ readonly goal: GoalSnapshot
104
+ readonly roundsStarted: number
105
+ readonly createdAt: number
106
+ readonly updatedAt: number
107
+ }
108
+ ```
109
+
110
+ ```ts type-equiv
111
+ /** Tombstone retained when the current goal is cleared. */
112
+ interface GoalClearChangeMeta {
113
+ readonly kind: 'goal/change'
114
+ readonly version: 1
115
+ readonly operation: 'clear'
116
+ readonly cleared: GoalRef
117
+ readonly clearedAt: number
118
+ }
119
+ ```
120
+
121
+ A continuation consumer attributes each admitted user-message turn with a positive, sequential round number and the current revision; only these admitted `user/message` events advance `roundsStarted`. Replay rejects non-positive rounds, gaps, stale revisions, stopped phases, and cap overflow.
122
+
123
+ ```ts type-equiv
124
+ /** Message attribution for admitted continuation rounds. */
125
+ interface GoalMessageSource {
126
+ readonly kind: 'goal'
127
+ readonly goalId: GoalId
128
+ readonly revision: number
129
+ /** Positive admitted continuation round. */
130
+ readonly round: number
131
+ }
132
+ ```
133
+
134
+ ## Requests and notifications
135
+
136
+ Creation separates caller omission from the deployment choice, which `create()` resolves internally. An edit is a partial replacement whose runtime validator requires at least one field. Every mutation notification carries the accepted operation and exact revision; clear omits `goal`.
137
+
138
+ ```ts type-equiv
139
+ /** Input whose omitted round cap is resolved by the service configuration. */
140
+ interface CreateGoalRequest {
141
+ readonly objective: string
142
+ readonly maxGoalRounds?: number
143
+ }
144
+ ```
145
+
146
+ ```ts type-equiv
147
+ /** Fields changed by an edit; at least one must be present. */
148
+ interface EditGoalRequest {
149
+ readonly objective?: string
150
+ readonly maxGoalRounds?: number
151
+ }
152
+ ```
153
+
154
+ ```ts type-equiv
155
+ /** Live notification after one durable goal mutation commits. */
156
+ interface GoalChanged {
157
+ readonly operation: GoalOperation
158
+ readonly ref: GoalRef
159
+ /** Absent for a clear tombstone. */
160
+ readonly goal?: GoalView
161
+ }
162
+ ```
163
+
164
+ ## Service behavior
165
+
166
+ [`GoalService`](../../packages/goal/goal/src/index.ts) resolves creation defaults, reads strict replay from the optionally registered `goal` projection, enforces exact-live-agent identity and compare-and-set mutations, and emits contained `goal/changed` notifications. Its first dependent access fails if the projection registry or key is absent. The package [README](../../packages/goal/goal/README.md) defines the callable API and model-visible contract.
167
+
168
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
169
+
170
+ <a id="cordis-surface"></a>
171
+
172
+ ## Cordis API
173
+
174
+ 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).
175
+
176
+ <a id="ctxgoals--goalservice"></a>
177
+
178
+ ### `ctx.goals` - `GoalService`
179
+
180
+ Goal service (`ctx.goals`) backed exclusively by the owning session log.
181
+
182
+ ```ts cordis-catalog
183
+ /**
184
+ * Read the current goal for one exact live agent.
185
+ * @param agent - owning live agent.
186
+ * @returns a fresh view or `undefined` when no goal is current.
187
+ * @throws {@link GoalError} when the agent is not the registry's live instance.
188
+ */
189
+ @Remote('get') get(agent: Agent): GoalView | undefined
190
+
191
+ /**
192
+ * Remove process-local continuation authority without changing durable goal
193
+ * phase or revision. Lifecycle owners use this before unloading a driver;
194
+ * a later human-authorized {@link resume} records the new activation edge.
195
+ * @param agent - owning live agent.
196
+ * @returns a fresh disarmed view, or `undefined` when no goal is current.
197
+ */
198
+ disarm(agent: Agent): GoalView | undefined
199
+
200
+ /**
201
+ * Create and arm a goal. A completed goal may be replaced; every other
202
+ * current phase must be cleared or resumed instead.
203
+ * @param agent - owning live agent.
204
+ * @param request - objective and optional round cap.
205
+ * @returns the created live view.
206
+ */
207
+ create(agent: Agent, request: CreateGoalRequest): GoalView
208
+
209
+ /**
210
+ * Edit objective and/or round cap without changing phase.
211
+ * @param agent - owning live agent.
212
+ * @param ref - expected current revision.
213
+ * @param request - at least one replacement field.
214
+ * @returns the edited view.
215
+ */
216
+ @Remote('edit') edit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView
217
+
218
+ /**
219
+ * Pause an active goal and disarm automatic continuation.
220
+ * @param agent - owning live agent.
221
+ * @param ref - expected current revision.
222
+ * @returns the paused view.
223
+ */
224
+ @Remote('pause') pause(agent: Agent, ref: GoalRef): GoalView
225
+
226
+ /**
227
+ * Resume and arm a stopped goal, or rearm an active goal after a
228
+ * session-start edge, while its round budget still has capacity.
229
+ * @param agent - owning live agent.
230
+ * @param ref - expected current revision.
231
+ * @returns the active view.
232
+ */
233
+ @Remote('resume') resume(agent: Agent, ref: GoalRef): GoalView
234
+
235
+ /**
236
+ * Mark a current non-complete goal complete and disarm it.
237
+ * @param agent - owning live agent.
238
+ * @param ref - expected current revision.
239
+ * @returns the completed view.
240
+ */
241
+ @Remote('complete') complete(agent: Agent, ref: GoalRef): GoalView
242
+
243
+ /**
244
+ * Mark an active goal blocked and disarm it.
245
+ * @param agent - owning live agent.
246
+ * @param ref - expected current revision.
247
+ * @param reason - policy-owned stable code and human-readable explanation.
248
+ * @returns the blocked view with its durable reason.
249
+ */
250
+ block(agent: Agent, ref: GoalRef, reason: GoalBlockReason): GoalView
251
+
252
+ /**
253
+ * Clear the current goal while retaining a durable tombstone and history.
254
+ * @param agent - owning live agent.
255
+ * @param ref - expected current revision.
256
+ * @returns the tombstone ref whose revision is one past the cleared snapshot.
257
+ */
258
+ @Remote('clear') clear(agent: Agent, ref: GoalRef): GoalRef
259
+
260
+ /**
261
+ * Create one Goal through the remote boundary.
262
+ * @param agent - exact live Agent resolved from the wire identity.
263
+ * @param request - objective and optional round cap.
264
+ * @returns the created Goal identity.
265
+ */
266
+ @Remote('create') remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult
267
+ ```
268
+
269
+ Types: [Agent](core.md)
270
+
271
+ Source: [`packages/goal/goal/src/index.ts`](../../packages/goal/goal/src/index.ts)
272
+
273
+ <a id="goal-events"></a>
274
+
275
+ ### `goal/*` events
276
+
277
+ <a id="goalactivation-changed--emit"></a>
278
+
279
+ #### `goal/activation-changed` - emit
280
+
281
+ Process-local goal activation changed for one session.
282
+
283
+ ```ts cordis-catalog
284
+ /**
285
+ * Process-local goal activation changed for one session.
286
+ * @mode emit
287
+ * @param payload - session id and the exact current goal activation, or no goal after a clear.
288
+ */
289
+ 'goal/activation-changed'(payload: GoalActivationChanged): void
290
+ ```
291
+
292
+ Source: [`packages/goal/goal/src/types.ts`](../../packages/goal/goal/src/types.ts)
293
+
294
+ <a id="goalchanged--emit"></a>
295
+
296
+ #### `goal/changed` - emit
297
+
298
+ Goal mutation accepted by one live agent. The matching `goal/change` session event has already committed. Listener failures are contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
299
+
300
+ ```ts cordis-catalog
301
+ /**
302
+ * Goal mutation accepted by one live agent. The matching `goal/change`
303
+ * session event has already committed. Listener failures are contained.
304
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
305
+ * @param payload.agent - agent whose session owns the goal.
306
+ * @param payload.change - fresh current projection or clear tombstone.
307
+ * @mode emit
308
+ */
309
+ 'goal/changed'(this: import('@deepseek-ai/dsh-scope').Scoped<Agent>, payload: { agent: Agent; change: GoalChanged }): void
310
+ ```
311
+
312
+ Types: [Agent](core.md) · [Scoped](scope.md)
313
+
314
+ Source: [`packages/goal/goal/src/domain.ts`](../../packages/goal/goal/src/domain.ts)
315
+ <!-- END GENERATED cordis-surface -->
@@ -0,0 +1,90 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/invariants.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Runtime Invariants
4
+
5
+ English | [中文](invariants.zh.md)
6
+
7
+ [dsh-invariants](../../packages/runtime-diagnostics/invariants) is the configurable registry service (`ctx.invariants`) for package-owned runtime invariant checks. It is one support-group package, not a three-package capability seam, and not part of the agent-loop spine: the registry owns selection, name reservation, child-fiber lifecycle, and package-attributed failure, while every workspace package publishes a `./invariant` companion plugin that registers checks under its exact npm package name. What a check may assert - authoritative event streams or mutable data, never service or method presence - is the runtime-invariants convention in [AGENTS.md](../../AGENTS.md#conventions).
8
+
9
+ Source: [`packages/runtime-diagnostics/invariants/src/index.ts`](../../packages/runtime-diagnostics/invariants/src/index.ts)
10
+
11
+ ## Selection
12
+
13
+ ```ts type-equiv
14
+ /** Runtime invariant selection configured on the service plugin. */
15
+ interface Config {
16
+ /** Global switch; defaults to `true`. */
17
+ readonly enabled?: boolean
18
+ /** Case-sensitive JavaScript regex sources that admit package names; empty admits all. */
19
+ readonly package_allowlist?: string[]
20
+ /** Case-sensitive JavaScript regex sources that exclude package names after allowlist matching. */
21
+ readonly package_blocklist?: string[]
22
+ }
23
+ ```
24
+
25
+ A package is selected when the service is enabled, the allowlist is empty or at least one pattern matches its full npm name, and no blocklist pattern matches - a blocklist match overrides an allowlist match. Entries compile with `new RegExp(source)`: matching is unanchored unless the source supplies `^` and `$`, and `/pattern/flags` syntax is not parsed. Validation fails loud at service startup: a blank, whitespace-padded, duplicate, or invalid entry throws instead of being skipped. A valid pattern may match no currently loaded package, so later loading and HMR stay deterministic; filters are fixed for the service lifetime ([README](../../packages/runtime-diagnostics/invariants/README.md)).
26
+
27
+ ## The installer
28
+
29
+ ```ts type-equiv
30
+ /**
31
+ * Throw a package-attributed invariant failure.
32
+ * @param message - violated package contract without the standard prefix.
33
+ * @returns never because reporting a violation throws.
34
+ */
35
+ type InvariantFailure = (message: string) => never
36
+ ```
37
+
38
+ ```ts type-equiv
39
+ /** Install one package's checks into the registration's child context. */
40
+ interface InvariantInstaller {
41
+ /**
42
+ * Install the package contribution.
43
+ * @param ctx - child context owned by this invariant registration.
44
+ * @param fail - reporter bound to the registering package name.
45
+ * @returns nothing, or a promise settling after asynchronous checks finish.
46
+ */
47
+ (ctx: Context, fail: InvariantFailure): void | Promise<void>
48
+ /** Services the child installer fiber may access. */
49
+ readonly inject?: Inject
50
+ }
51
+ ```
52
+
53
+ An enabled installer runs in a dedicated child Cordis fiber; `installer.inject` declares the services that fiber may access, and synchronous or asynchronous installer completion is joined before the registration succeeds. `fail(message)` throws `InvariantError` - `extends Error` with stable `code: 'INVARIANT'`, the owning `packageName`, and a message prefixed `invariant violated by "<package>": …` - so a violation is attributable without the registry importing any product package.
54
+
55
+ ## The service
56
+
57
+ `ctx.invariants.register(packageName, installer)` reserves one active registration for the full npm package name and returns its effect-scoped disposer. The reservation holds even when filters keep the installer inactive, so two plugins can never silently claim the same package name; a duplicate, blank, or whitespace-containing name throws. An installer failure disposes the child fiber and releases the reservation atomically. The service owns every registration fiber while the returned disposer also belongs to the companion fiber: unloading either side removes listeners, trace state, and the reservation, so a companion can reload and register the same name again without retained state.
58
+
59
+ ## The companion contract
60
+
61
+ Every workspace package owns a `./invariant` companion ([package contract](../../packages/AGENTS.md)); publication and registration are exhaustive, but assertions are deliberately not synthetic. A companion installs a check only when its package owns an observable event or mutable-data relationship; otherwise it exports an empty installer whose leading comment starts `No runtime invariant:` and explains, package-specifically, why nothing is checkable. `pnpm run verify-package-invariants` mechanically rejects generated markers, unexplained empty installers, non-empty installers that omit or ignore the reporter, incorrect registration names, and incomplete export, publication, dependency, or bundle wiring ([mechanical-rule Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)). The catalog of executable companions and the standard composition live in the [package README](../../packages/runtime-diagnostics/invariants/README.md).
62
+
63
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
64
+
65
+ <a id="cordis-surface"></a>
66
+
67
+ ## Cordis API
68
+
69
+ 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).
70
+
71
+ <a id="ctxinvariants--invariantregistry"></a>
72
+
73
+ ### `ctx.invariants` - `InvariantRegistry`
74
+
75
+ Package-owned invariant registry with global and regex-based selection.
76
+
77
+ ```ts cordis-catalog
78
+ /**
79
+ * Register one package's invariant installer. The package name is reserved
80
+ * even when filtering disables its checks. Enabled installers run in a child
81
+ * fiber; failure disposes that fiber and releases the reservation.
82
+ * @param packageName - full npm package name that owns the contribution.
83
+ * @param installer - listener or startup-check installer for the child context.
84
+ * @returns an effect-scoped disposer for the registration.
85
+ */
86
+ register(packageName: string, installer: InvariantInstaller): () => void
87
+ ```
88
+
89
+ Source: [`packages/runtime-diagnostics/invariants/src/index.ts`](../../packages/runtime-diagnostics/invariants/src/index.ts)
90
+ <!-- END GENERATED cordis-surface -->