@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,545 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/schedule.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Host-wide Schedule
4
+
5
+ English | [中文](schedule.zh.md)
6
+
7
+ Schedule stores reminders independently of Session activation and delivers them to their original Session. This page records the durable and model-facing types from [`types.ts`](../../packages/schedule/schedule/src/types.ts); the [package README](../../packages/schedule/schedule/README.md) owns composition and reminder framing.
8
+
9
+ ## Durable records
10
+
11
+ `ScheduleId` is a globally unique [branded id](core.md#branded-ids). The version-1 `schedule` storage domain owns a `tasks` table whose entries bind a `ScheduleRecord` to its original `sessionId`, with stored `status: 'active' | 'inactive'` and optional `lastDelivery`. Records lacking status normalize to `active` without scanning or recreating historical Sessions. Creation canonicalizes the target into RFC 3339 UTC `scheduledAt`; `after` retains the submitted delay, `every` retains its fixed interval, `daily` and `weekly` retain normalized local `time` and their explicit `timeZone`, and `cron` retains its canonical five-field `expression` and explicit `timeZone`. Daily, weekly, and cron decoding preserve the committed instant and stored zone spelling. The stored task record declares a required `title`, the short name the task surfaces show; creation requires it and never derives it from the instruction. No stored record may omit its title: a record whose `title` is missing, blank after trimming, untrimmed, or longer than 120 characters fails durable decoding with `ScheduleLogError`, and the schedule domain declares no backup-and-skip policy, so one such stored task rejects the whole domain open instead of being dropped. Only explicit deletion removes a task; previously physically deleted tasks are not restored or fabricated.
12
+
13
+ ```ts type-equiv
14
+ /** Durable one-shot reminder created from a positive delay. */
15
+ interface AfterScheduleRecord {
16
+ /** Globally unique task identity. */
17
+ readonly id: ScheduleId
18
+ /** Rule discriminator for a delayed one-shot reminder. */
19
+ readonly kind: 'after'
20
+ /** Required stored task name; already trimmed, non-empty, and at most 120 characters. */
21
+ readonly title: string
22
+ /** Trimmed reminder content supplied at creation. */
23
+ readonly prompt: string
24
+ /** Positive safe-integer delay accepted at creation. */
25
+ readonly afterSeconds: number
26
+ /** Four-digit-year RFC 3339 UTC target. */
27
+ readonly scheduledAt: string
28
+ }
29
+ ```
30
+
31
+ ```ts type-equiv
32
+ /** Durable one-shot reminder created from an absolute instant. */
33
+ interface AtScheduleRecord {
34
+ /** Globally unique task identity. */
35
+ readonly id: ScheduleId
36
+ /** Rule discriminator for an absolute one-shot reminder. */
37
+ readonly kind: 'at'
38
+ /** Required stored task name; already trimmed, non-empty, and at most 120 characters. */
39
+ readonly title: string
40
+ /** Trimmed reminder content supplied at creation. */
41
+ readonly prompt: string
42
+ /** Four-digit-year RFC 3339 UTC target. */
43
+ readonly scheduledAt: string
44
+ }
45
+ ```
46
+
47
+ ```ts type-equiv
48
+ /** Durable fixed-rate reminder aligned to creation or its most recent interval edit. */
49
+ interface EveryScheduleRecord {
50
+ /** Globally unique task identity. */
51
+ readonly id: ScheduleId
52
+ /** Rule discriminator for a fixed-rate recurring reminder. */
53
+ readonly kind: 'every'
54
+ /** Required stored task name; already trimmed, non-empty, and at most 120 characters. */
55
+ readonly title: string
56
+ /** Trimmed reminder content supplied at creation. */
57
+ readonly prompt: string
58
+ /** Fixed safe-integer interval, never below one minute. */
59
+ readonly everySeconds: number
60
+ /** Next anchor-aligned occurrence while active, or final occurrence when inactive. */
61
+ readonly scheduledAt: string
62
+ }
63
+ ```
64
+
65
+ ```ts type-equiv
66
+ /** Durable daily wall-clock reminder; gaps skip a date and overlaps use the earlier instant. */
67
+ interface DailyScheduleRecord {
68
+ /** Globally unique task identity. */
69
+ readonly id: ScheduleId
70
+ /** Rule discriminator for a daily wall-clock reminder. */
71
+ readonly kind: 'daily'
72
+ /** Required stored task name; already trimmed, non-empty, and at most 120 characters. */
73
+ readonly title: string
74
+ /** Trimmed reminder content supplied at creation. */
75
+ readonly prompt: string
76
+ /** Local time normalized to HH:mm:ss.SSS. */
77
+ readonly time: string
78
+ /** Explicit IANA zone; equivalent timing edits retain the stored spelling. */
79
+ readonly timeZone: string
80
+ /** Committed next UTC instant while active, or final occurrence when inactive. */
81
+ readonly scheduledAt: string
82
+ }
83
+ ```
84
+
85
+ ```ts type-equiv
86
+ /** One-shot task variants. */
87
+ type OneShotScheduleRecord = AfterScheduleRecord | AtScheduleRecord
88
+ ```
89
+
90
+ ```ts type-equiv
91
+ /** Recurring Host task variants. */
92
+ type RecurringScheduleRecord = EveryScheduleRecord | DailyScheduleRecord | WeeklyScheduleRecord | CronScheduleRecord
93
+ ```
94
+
95
+ ```ts type-equiv
96
+ /** Reminder rule and target, stored with its original Session binding. */
97
+ type ScheduleRecord = OneShotScheduleRecord | RecurringScheduleRecord
98
+ ```
99
+
100
+ ## Absolute-time input
101
+
102
+ The `at` selector is either a strict offset-bearing RFC 3339 string or an exact local-calendar object. The local form keeps its interpretation explicit at the tool boundary:
103
+
104
+ ```ts type-equiv
105
+ /** Structured local-calendar input accepted by creation and timing edits. */
106
+ interface LocalAtInput {
107
+ /** Four-digit ISO calendar date. */
108
+ readonly date: string
109
+ /** Local wall-clock time with optional one-to-three digit milliseconds. */
110
+ readonly time: string
111
+ /** Explicit UTC or IANA Area/Location zone. */
112
+ readonly time_zone: string
113
+ }
114
+ ```
115
+
116
+ ```ts type-equiv
117
+ /** Absolute selector accepted by creation and timing edits. */
118
+ type AtInput = string | LocalAtInput
119
+ ```
120
+
121
+ The shipped Web composition carries no `time-context` row; the optional experimental bundle `@deepseek-ai/dsh-experimental-schedule-bundle`, enabled from the Plugins page, inserts and mounts time-context, which samples the browser's IANA zone for every prompt. Time-context tells the model to interpret otherwise-unqualified natural-language dates and times in that request-local zone when the open turn has one unambiguous browser zone; mixed or missing browser-zone records tell the model to ask. That guidance is not a durable Session default: the model must still pass an offset in the string form or `time_zone` in the local form, and Schedule never reads browser, Session, process, or model context.
122
+
123
+ Schedule rejects invalid offsets and zones, offset-free strings, non-future targets, and local times inside daylight-saving gaps. A daylight-saving overlap chooses its first, earlier instant. Successful creation stores only canonical UTC `scheduledAt`, so replay never depends on ambient time-zone state.
124
+
125
+ <a id="daily-wall-clock-input"></a>
126
+ ## Daily wall-clock input
127
+
128
+ `daily` is one of the mutually exclusive creation selectors, alongside `after_seconds`, `at`, `every_seconds`, the weekly selector, and the cron selector. For example, `daily: { time: '23:00:00', time_zone: 'Asia/Shanghai' }` selects 23:00 in that zone on each eligible local date. The exact object has no date, offset, or interval field:
129
+
130
+ ```ts type-equiv
131
+ /** Daily local-time selector accepted by creation and timing edits. */
132
+ interface DailyInput {
133
+ /** Local HH:mm:ss time with optional one-to-three fractional digits. */
134
+ readonly time: string
135
+ /** Explicit UTC or IANA Area/Location zone. */
136
+ readonly time_zone: string
137
+ }
138
+ ```
139
+
140
+ Creation requires `HH:mm:ss` with optional one-to-three fractional digits, rejects leap seconds and `24:00`, canonicalizes the explicit IANA zone, and stores `time` as `HH:mm:ss.SSS`. The first `scheduledAt` is strictly after creation time. A nonexistent local time or entire date is skipped; an overlap selects the earlier instant once per local date. If that earlier instant has passed, the later duplicate is not eligible. Only UTC target years 0001-9999 are constrained; local dates at the UTC range edges may fall in year 0 or 10000.
141
+
142
+ A saved next target is a committed UTC instant. The Host decoder and restart preserve that instant without resolving it against time-zone rules again, and valid stored zone aliases remain readable when canonical names change. Subsequent targets use the Host's current IANA data. The next target must be both after the delivery decision and on a local date later than the selected occurrence's date. Creation fails with `time_out_of_range` when no future UTC target is representable.
143
+
144
+ ## Fixed-rate input and catch-up
145
+
146
+ `every_seconds` is a safe-integer interval of at least 60 seconds, aligned to creation time. It measures elapsed time, not daily wall-clock time: `every_seconds: 86400` cannot substitute for `daily` across offset changes. The protocol provides no shared cooldown or cross-record admission rule; the cron selector described below is wall-clock timing, not a fixed-rate interval.
147
+
148
+ When the Host starts with an overdue Every, Daily, Weekly, or Cron record, it sends only the latest due occurrence. Every advances to the first target aligned to its current interval anchor after the delivery decision; Daily, Weekly, and Cron follow the local-date rules above and below. Missed occurrences do not accumulate. If no next UTC target is representable, delivery retains the record as inactive with its latest receipt.
149
+
150
+ One-shots produce individual follow-ups. Recurring records due in the same scan for the same Session share one follow-up rendered by `renderRecurringReminderBatchFraming`, with one latest occurrence per record. The one-minute minimum applies only to fixed-rate intervals; delivery does not wait for the target Agent to become idle.
151
+
152
+ <a id="cron-wall-clock-input"></a>
153
+ ## Cron wall-clock input
154
+
155
+ `cron` is one of the mutually exclusive creation selectors. Its exact object carries only the strict five-field Vixie expression `minute hour day-of-month month day-of-week` and an explicit IANA zone, for example `cron: { expression: '*/15 9-17 * * 1-5', time_zone: 'Asia/Shanghai' }`. The field bounds are:
156
+
157
+ | Field | Accepted range | Notes |
158
+ |---|---|---|
159
+ | minute | 0-59 | |
160
+ | hour | 0-23 | |
161
+ | day-of-month | 1-31 | |
162
+ | month | 1-12 | |
163
+ | day-of-week | 0-7 | Both `0` and `7` mean Sunday. |
164
+
165
+ Every field accepts `*`, a single value, an `a-b` range, a `*/n` or `a-b/n` step with `n >= 1`, and a comma-separated list of those forms. Everything else is rejected with `invalid_rule` and a message naming the offending field: `L`, `W`, and `#` operators, `JAN`/`MON` names, `@daily`-style macros, six-field expressions with a seconds field, out-of-range values, inverted ranges, zero steps, and empty fields. Because the dialect has five fields, the smallest interval is one minute; sub-minute scheduling stays unsupported.
166
+
167
+ Creation canonicalizes the expression before storing it. Canonicalization expands each field into its matched value set and re-encodes that set deterministically: repeated values collapse, adjacent values and ranges merge, a uniform step is written as `a-b/n` or, for a field that started with `*`, as a star-step (`*` for every value, otherwise the widest star-step walk plus any remaining values), a step of `1` is dropped, and Sunday is written as `0`. A field that did not start with `*` never becomes a star-step. Preserving each field's star flag is what keeps the day-of-month/day-of-week rule below Vixie-faithful across the stored expression. The durable decoder rejects a stored expression that is not canonical.
168
+
169
+ The first target is the first strictly future instant whose local date and time in the zone match. It reuses the Daily and Weekly local-time resolution: a non-existent local time is skipped, and an ambiguous one takes the earlier occurrence once for that date. The committed UTC `scheduledAt` is never recomputed on restart.
170
+
171
+ Day-of-month and day-of-week follow Vixie semantics. A field is a star when its text starts with `*`, independently of the values it matches, so `*/1` and `*/2` are stars while `1-31` and `0-7` are restricted. When either field is a star, a local date matches only when both fields match; when neither is a star, it matches when either field matches.
172
+
173
+ Cron decoding preserves the committed instant and the stored zone spelling, and rejects a non-canonical stored expression. Cron belongs only to the current Host `ScheduleRecord`; the frozen historical Session decoder does not admit it.
174
+
175
+ ## Historical Session changes
176
+
177
+ Version-1 `schedule/change` events remain decodable as historical Session data. Their create, fold, and invariant types use `LegacyScheduleRecord`, which admits only After, At, and Every; Daily, Weekly, and Cron belong only to the current Host `ScheduleRecord`. The Host record decoder is separate from the frozen historical decoder. A create record written before titles existed carries no `title`, so the historical decoder admits that absent member while the Host decoder still requires it. Historical events do not populate the storage domain or schedule delivery. Existing reminders in these events require explicit recreation through `schedule_create`; no implicit Session migration or conversion of old `at` records occurs.
178
+
179
+ ```ts type-equiv
180
+ /**
181
+ * Frozen Session event and fold vocabulary; daily rules belong only to Host storage.
182
+ *
183
+ * A version-1 event written before titles existed persists no `title` member, so
184
+ * `after`, `at`, and `every` decode without one and stay readable. The Host task
185
+ * record requires the member and never persists a record without it.
186
+ */
187
+ type LegacyScheduleRecord =
188
+ | LegacyAfterScheduleRecord
189
+ | LegacyAtScheduleRecord
190
+ | LegacyEveryScheduleRecord
191
+ ```
192
+
193
+ ```ts type-equiv
194
+ /** Creates one durable reminder record. */
195
+ interface ScheduleCreateChange {
196
+ readonly version: 1
197
+ readonly operation: 'create'
198
+ readonly schedule: LegacyScheduleRecord
199
+ }
200
+ ```
201
+
202
+ ```ts type-equiv
203
+ /** Deletes one currently active reminder. */
204
+ interface ScheduleDeleteChange {
205
+ readonly version: 1
206
+ readonly operation: 'delete'
207
+ readonly id: ScheduleId
208
+ }
209
+ ```
210
+
211
+ ```ts type-equiv
212
+ /** Records that one active one-shot reminder entered the durable dispatch history. */
213
+ interface OneShotScheduleDispatchChange {
214
+ readonly version: 1
215
+ readonly operation: 'dispatch'
216
+ readonly id: ScheduleId
217
+ }
218
+ ```
219
+
220
+ ```ts type-equiv
221
+ /** Records one fixed-rate decision and advances directly past missed occurrences. */
222
+ interface EveryScheduleDispatchChange {
223
+ readonly version: 1
224
+ readonly operation: 'dispatch'
225
+ readonly id: ScheduleId
226
+ /** Wall-clock decision time used to select the latest due occurrence. */
227
+ readonly acceptedAt: string
228
+ }
229
+ ```
230
+
231
+ ```ts type-equiv
232
+ /** Durable dispatch shapes supported by the current rule set. */
233
+ type ScheduleDispatchChange = OneShotScheduleDispatchChange | EveryScheduleDispatchChange
234
+ ```
235
+
236
+ ```ts type-equiv
237
+ /** Strict version-1 durable Schedule mutation union. */
238
+ type ScheduleChange = ScheduleCreateChange | ScheduleDeleteChange | ScheduleDispatchChange
239
+ ```
240
+
241
+ The historical decoder and fold reject unknown versions, extra fields, reused ids, and invalid transitions. The event remains indexed in the [persistence catalog](../persistence-catalog.md#schedulechange--log-only). Session history is not the authority for active tasks.
242
+
243
+ ## Active views and management
244
+
245
+ Tool values combine the stored record with timing derived from the current wall clock. The Host restores the original Session when delivery requires it; listing and deleting tasks do not activate that Session.
246
+
247
+ ```ts type-equiv
248
+ /** Current delivery timing derived from the durable record and wall clock. */
249
+ type ScheduleState = 'scheduled' | 'overdue'
250
+ ```
251
+
252
+ ```ts type-equiv
253
+ /** Host-driven delivery resumes the original Session when needed. */
254
+ type ScheduleDeliveryMode = 'host'
255
+ ```
256
+
257
+ ```ts type-equiv
258
+ /** Complete model-facing view of one active reminder. */
259
+ type ScheduleView = ScheduleRecord & {
260
+ /** Whether the target remains in the future. */
261
+ readonly state: ScheduleState
262
+ /** Reminder delivery never leaves the owning session. */
263
+ readonly deliveryMode: ScheduleDeliveryMode
264
+ }
265
+ ```
266
+
267
+ The [tool catalog](../tool-catalog.md#deepseek-aidsh-schedule) owns schemas for `schedule_create`, `schedule_list`, `schedule_delete`, and `schedule_update`. Create, delete, and update acknowledge the storage-domain write. A Host-wide queue serializes these mutations against due delivery; deleting a task does not remove an already queued message. Model tools address the current Session, while the shared Host create, list, update, and delete methods accept an explicit Session binding. Creation requires a `title` that must be non-empty after trimming and at most 120 characters; a missing, blank, or over-long title is rejected with `invalid_prompt`, and creation never derives one from the instruction. Create and list views carry the stored `title` alongside the instruction, and a stored record whose `title` is missing or invalid is rejected at decode.
268
+
269
+ ```ts type-equiv
270
+ /** Reminder creation selector, shared by the model consumer and Host service. */
271
+ interface ScheduleCreateRequest {
272
+ /** Non-empty reminder text. */
273
+ prompt: string
274
+ /** Required task name of at most 120 characters, non-empty after trimming; names the card, detail heading, and task lists. */
275
+ title: string
276
+ /** Relative one-shot delay in seconds. */
277
+ after_seconds?: number
278
+ /** Absolute one-shot target. */
279
+ at?: AtInput
280
+ /** Fixed recurrence interval in seconds. */
281
+ every_seconds?: number
282
+ /** Daily wall-clock time in an explicit IANA zone. */
283
+ daily?: DailyInput
284
+ /** Weekly wall-clock time and explicit ISO weekday set in an IANA zone. */
285
+ weekly?: WeeklyInput
286
+ /** Five-field cron expression evaluated in an explicit IANA zone. */
287
+ cron?: CronInput
288
+ }
289
+ ```
290
+
291
+ ```ts type-equiv
292
+ /** Session-scoped task list, without Agent activation. */
293
+ interface ScheduleListRequest {
294
+ /** Original Session binding. */
295
+ sessionId: SessionId
296
+ }
297
+ ```
298
+
299
+ ```ts type-equiv
300
+ /** Delete request identifying a task within its original Session binding. */
301
+ interface ScheduleDeleteRequest extends ScheduleListRequest {
302
+ /** Task to remove. */
303
+ id: ScheduleId
304
+ }
305
+ ```
306
+
307
+ ```ts type-equiv
308
+ /** Successful `schedule_delete` value, including the non-mutating not-found result. */
309
+ type ScheduleDeleteResult =
310
+ | { readonly id: ScheduleId; readonly deleted: true }
311
+ | { readonly id: ScheduleId; readonly deleted: false; readonly code: 'schedule_not_found' }
312
+ ```
313
+
314
+ ## Web catalog
315
+
316
+ The Remote `schedule.catalog()` method returns active and inactive Host tasks with their original Session bindings, ordered by `scheduledAt` ascending and then lexicographically by `id`. It reads only the Schedule domain, without activating Sessions or reading their history. Browser consumers receive this browser-safe type:
317
+
318
+ ```ts type-equiv
319
+ /** Durable Session inbox delivery acknowledgment, not model execution completion. */
320
+ interface ScheduleDeliveryReceipt {
321
+ /** Canonical UTC target of the delivered occurrence. */
322
+ readonly scheduledAt: string
323
+ /** Canonical UTC time sampled after Session persistence acknowledged delivery. */
324
+ readonly deliveredAt: string
325
+ /** Identity of the delivered message, shared by tasks in one recurring batch. */
326
+ readonly messageId: MessageId
327
+ }
328
+ ```
329
+
330
+ ```ts type-equiv
331
+ /** Browser-safe retained reminder with its original Session binding. */
332
+ type ScheduleCatalogEntry = ScheduleRecord & {
333
+ /** Session receiving this reminder when it becomes due. */
334
+ readonly sessionId: SessionId
335
+ /** Inactive reminders remain visible but never schedule another delivery. */
336
+ readonly status: 'active' | 'inactive'
337
+ /** Most recent durably acknowledged inbox delivery, when available. */
338
+ readonly lastDelivery?: ScheduleDeliveryReceipt
339
+ }
340
+ ```
341
+
342
+ The Remote `schedule.list({ sessionId })`, model `schedule_list`, and Session-header catalog return only active tasks. A model view's derived timing `state` remains distinct from stored lifecycle `status`. Deletion uses `schedule.delete({ sessionId, id })` with the entry's original binding; a mismatched binding returns not found. Model tools supply the current Agent's Session, whereas the global user interface supplies the selected task's binding. The binding check alone does not establish caller authorization. The payload-free `schedule/changed` event invalidates client lists; reconnecting clients fetch current state again.
343
+
344
+ The shipped Web composition carries no `ui-schedule` row; the optional experimental bundle `@deepseek-ai/dsh-experimental-schedule-bundle`, enabled from the Plugins page, inserts and mounts `ui-schedule` with the Host capability. The [client package](../../packages/client/ui-schedule/README.md) owns the catalog, empty state, and deletion controls. The page separately filters all, active, and inactive tasks, retains inactive details and an original-Session control in the detail tab strip, and requires explicit confirmed deletion. Rules and Delivery records separate task settings from lazily paged saved receipts. Neither a receipt nor inactive status confirms model execution.
345
+
346
+ ## Timing edits
347
+
348
+ `schedule.update({ sessionId, id, expected, change })` edits an active task without activating its Session. `expected` is the complete observed `ScheduleRecord`, not a catalog entry with extra metadata. The Host compares it to the current record inside the same FIFO used by dispatch and deletion. Normal delivery can advance the target during editing; that stale snapshot returns `schedule_conflict` instead of overwriting the current rule. Missing or mismatched bindings return `schedule_not_found`, and inactive tasks return `schedule_ended`.
349
+
350
+ ```ts type-equiv
351
+ /** Timing-only edit; it may select a different recurrence kind than the stored record, and one-shot targets use an absolute `at`. */
352
+ type ScheduleTimingChange =
353
+ | { readonly kind: 'at'; readonly at: AtInput }
354
+ | { readonly kind: 'every'; readonly every_seconds: number }
355
+ | { readonly kind: 'daily'; readonly daily: DailyInput }
356
+ | { readonly kind: 'weekly'; readonly weekly: WeeklyInput }
357
+ | { readonly kind: 'cron'; readonly cron: CronInput }
358
+ ```
359
+
360
+ ```ts type-equiv
361
+ /** Compare-and-update request within the original Session binding. */
362
+ interface ScheduleUpdateRequest extends ScheduleDeleteRequest, ScheduleUpdateContent {
363
+ /** Complete record observed when editing began, including the committed target. */
364
+ readonly expected: ScheduleRecord
365
+ /** New timing; its kind may differ from the stored record's kind, and an omitted value keeps the committed target. */
366
+ readonly change?: ScheduleTimingChange
367
+ }
368
+ ```
369
+
370
+ ```ts type-equiv
371
+ /** Successful current record, non-mutating lookup/conflict failure, or invalid name/instruction/timing. */
372
+ type ScheduleUpdateResult =
373
+ | { readonly id: ScheduleId; readonly updated: boolean; readonly record: ScheduleRecord }
374
+ | ScheduleUpdateMiss
375
+ | ScheduleToolError
376
+ ```
377
+
378
+ A changed Daily rule computes its first strictly future target using the saved local time and zone semantics. A changed Cron rule canonicalizes its expression and computes its first strictly future target under the same local-date, gap, and earlier-overlap rules. A changed Every interval starts a new anchor at accepted save time plus that interval. An After or At task can receive a different absolute target as an At record with the same id. These operations preserve the stored `title`, the prompt, original Session binding, lifecycle status, and all saved receipts. A change may also select a different recurrence kind, which recomputes the target from the new rule with the same id, title, prompt, Session binding, status, and saved receipts. An equivalent normalized rule returns `updated: false` with its unchanged record; it does not rewrite storage, reset the target, or emit a change event. A differently spelled but equivalent Cron expression is such a no-op, because the comparison uses the canonical expression and the canonical zone.
379
+
380
+ Input validation uses existing timing errors. A changed absolute target must still be future when its FIFO slot runs. The successful task put precedes the change notification and timer recomputation. Storage and lifecycle failures reject; cancellation is checked after queue and initialization waits but cannot roll back an in-flight write. One-shot records retain a UTC instant rather than the editing form's IANA zone. Timing edits append no historical Session event: the model reaches the same in-place update through `schedule_update`, which compares the record it read with the stored one instead of deleting and recreating the task.
381
+
382
+ ## Saved delivery records
383
+
384
+ `schedule.history({ sessionId, id, limit })` reads saved receipts without activating a Session. The explicit limit is a safe integer from 1 through 100. Pages follow reverse append order, not wall-clock sorting; the optional message-id cursor excludes the oldest record from the preceding page. New arrivals do not shift that cursor. A missing task or wrong Session binding returns `schedule_not_found`; an unknown cursor returns `delivery_cursor_not_found`, not an empty successful page.
385
+
386
+ ```ts type-equiv
387
+ /** Saved inbox delivery with its immutable sent prompt when recorded by this Host. */
388
+ interface ScheduleDeliveryRecord extends ScheduleDeliveryReceipt {
389
+ /** Prompt sent for this occurrence; unavailable for legacy receipts. */
390
+ readonly prompt?: string
391
+ }
392
+ ```
393
+
394
+ ```ts type-equiv
395
+ /** Explicitly bounded saved-delivery query within one Session binding. */
396
+ interface ScheduleDeliveryHistoryRequest extends ScheduleDeleteRequest {
397
+ /** Required safe-integer page size from 1 through 100. */
398
+ limit: number
399
+ /** Message identity of the oldest entry in the previous page; excluded from this page. */
400
+ before?: MessageId
401
+ }
402
+ ```
403
+
404
+ ```ts type-equiv
405
+ /** Configured limits applied when appending one task's delivery receipt. */
406
+ interface DeliveryRetentionBounds {
407
+ /** Retained window in days, measured back from the acknowledgment being appended. */
408
+ readonly days: number
409
+ /** Maximum retained records per task; the newest survive. */
410
+ readonly records: number
411
+ }
412
+ ```
413
+
414
+ ```ts type-equiv
415
+ /** Newest-first saved deliveries, or a non-mutating task/cursor lookup failure. */
416
+ type ScheduleDeliveryHistoryResult =
417
+ | {
418
+ readonly id: ScheduleId
419
+ readonly records: ScheduleDeliveryRecord[]
420
+ /** Whether earlier delivery records may be unavailable; missing receipts are never reconstructed. */
421
+ readonly earlierRecordsUnavailable: boolean
422
+ /** True only after an append removed saved records; absent legacy evidence is false. */
423
+ readonly earlierRecordsPruned: boolean
424
+ /** Current Host retention configuration, also used by the delivery writer. */
425
+ readonly retention: DeliveryRetentionBounds
426
+ /** Oldest returned message identity, present only when older saved records remain. */
427
+ readonly nextBefore?: MessageId
428
+ }
429
+ | { readonly id: ScheduleId; readonly code: 'schedule_not_found' | 'delivery_cursor_not_found' }
430
+ ```
431
+
432
+ New tasks initialize an empty history. Older task rows without history expose only their existing latest receipt, mark earlier records unavailable, and are not rewritten by reads. Future acknowledgments preserve that receipt and append actual new receipts with instruction snapshots. Lost history and missing legacy instruction snapshots are never reconstructed. The same task-row write commits history, latest receipt, status, and next target; explicit task deletion stops future delivery, removes the task row together with its saved receipts, and takes it out of `list` and `catalog`; conversation messages are unaffected. Saved delivery records are pruned on append to the configured `deliveryHistoryDays` window, measured back from each receipt's `deliveredAt`, and to the `deliveryHistoryRecords` cap; the appended latest receipt always survives, and a pruned window marks earlier records unavailable. Pagination bounds returned record count rather than storage size or instruction bytes.
433
+
434
+ ## Host delivery
435
+
436
+ The Host reads persisted tasks at startup and sets its timer to the earliest active target. Inactive tasks remain queryable but never schedule another delivery. At delivery it resolves the original Session through the Session controller, including cold Sessions. After restoration it samples the wall clock again and excludes members that are no longer due after a rollback; those tasks retain their timer obligation. Neither a Goal nor a separate Run completion record participates in dispatch.
437
+
438
+ Plugin-sourced `followup()` synchronously appends the message to the Session inbox. After a successful Session flush, one task-record put appends a saved delivery with its instruction snapshot and stores the latest `ScheduleDeliveryReceipt` together with the one-shot's `inactive` status or the recurring task's next target and status. Recurring tasks in the same batch share the receipt's `messageId`; each receipt retains that task's delivered occurrence time. Delivery never steers or cancels the current turn and does not wait for model completion.
439
+
440
+ A failure to resolve the Session, enqueue the message, or confirm persistence leaves the task stored and reports a Host warning. A later management change or Host restart retries it. Session persistence and the task put are not atomic across stores. A crash after inbox persistence but before the task put can repeat delivery; the receipt does not close this gap. Schedule provides no model-result acknowledgement, execution cancellation, or external notification channel.
441
+
442
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
443
+
444
+ <a id="cordis-surface"></a>
445
+
446
+ ## Cordis API
447
+
448
+ 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).
449
+
450
+ <a id="ctxschedule--scheduleservice"></a>
451
+
452
+ ### `ctx.schedule` - `ScheduleService`
453
+
454
+ Shared management service; reads, deletion, and timing edits never activate a Session.
455
+
456
+ `sessionPersistence` is a load-order requirement rather than a directly called service: a delivery commits only when `ctx.sessions.flush()` reports that a `session/flush` listener participated, and the persistence backend providing this service is the plugin that registers that listener.
457
+
458
+ ```ts cordis-catalog
459
+ /**
460
+ * Create a reminder bound to the caller-selected Session without activating it.
461
+ *
462
+ * The request must supply a title; a missing, blank-after-trim, or over-long
463
+ * title rejects with `invalid_prompt` instead of deriving one from the prompt.
464
+ * The record is built from the clock reading taken before the request joins the
465
+ * serialized queue, so a create that waits behind a longer operation keeps its
466
+ * request-time anchor and may already be due when the queue reaches it.
467
+ * @param sessionId - Original Session receiving the reminder.
468
+ * @param request - Validated tool selector, required title, and reminder content.
469
+ * @param signal - Optional cancellation checked before persistence begins, including after FIFO waits.
470
+ * @returns The durably stored schedule. Cancellation does not roll back an in-flight write.
471
+ */
472
+ async create(sessionId: SessionId, request: ScheduleCreateRequest, signal?: AbortSignal): Promise<ScheduleRecord>
473
+
474
+ /**
475
+ * Read the selected Session's active tasks without resuming its Agent.
476
+ * @param request - Session whose task list is requested.
477
+ * @returns Persisted reminders in storage order.
478
+ */
479
+ @Remote('list') async list(request: ScheduleListRequest): Promise<ScheduleRecord[]>
480
+
481
+ /**
482
+ * Read all active and inactive Host reminders with their original Session bindings.
483
+ * A deleted reminder has no row, so it is absent here.
484
+ * Does not activate Sessions or read Session history.
485
+ * @returns Reminders ordered by scheduledAt ascending, then lexicographically by id.
486
+ */
487
+ @Remote('catalog') async catalog(): Promise<ScheduleCatalogEntry[]>
488
+
489
+ /**
490
+ * Read saved inbox deliveries without activating or reading the original Session.
491
+ * The task's own row supplies its binding, so its records stay readable through this lookup.
492
+ * @param request - Session binding, task identity, explicit limit, and optional exclusive message cursor.
493
+ * @returns Newest-first deliveries in append order, or a task/cursor lookup failure.
494
+ * @throws ScheduleInputError when limit is not a safe integer from 1 through 100.
495
+ */
496
+ @Remote('history') async history(request: ScheduleDeliveryHistoryRequest): Promise<ScheduleDeliveryHistoryResult>
497
+
498
+ /**
499
+ * Delete one task belonging to the selected Session, leaving queued messages intact.
500
+ *
501
+ * The row is removed: the task no longer schedules, leaves `list` and `catalog`, and its
502
+ * saved delivery records go with it.
503
+ * @param request - Session and exact task identity.
504
+ * @param signal - Optional cancellation checked before persistence begins, including after FIFO waits.
505
+ * @returns Whether that Session owned a deleted task. Cancellation does not roll back an in-flight write.
506
+ */
507
+ @Remote('delete') async delete(request: ScheduleDeleteRequest, signal?: AbortSignal): Promise<ScheduleDeleteResult>
508
+
509
+ /**
510
+ * Update the name, instruction, and timing of an active task within the original Session
511
+ * binding without activating the Session or changing saved deliveries.
512
+ *
513
+ * Each supplied field replaces its stored value; an omitted field keeps it. A name or
514
+ * instruction change alone does not reset the committed target.
515
+ * @param request - Task binding, complete observed record, and any combination of timing, name, and instruction.
516
+ * @param signal - Cancellation checked after domain readiness and FIFO waits, before persistence begins.
517
+ * @returns The committed record, unchanged record for a no-op, or a non-mutating input/lookup/conflict result.
518
+ * Storage and lifecycle failures reject; cancellation after a write starts does not roll it back.
519
+ */
520
+ @Remote('update') async update(request: ScheduleUpdateRequest, signal?: AbortSignal): Promise<ScheduleUpdateResult>
521
+ ```
522
+
523
+ Types: [SessionId](core.md)
524
+
525
+ Source: [`packages/schedule/schedule/src/index.ts`](../../packages/schedule/schedule/src/index.ts)
526
+
527
+ <a id="schedule-events"></a>
528
+
529
+ ### `schedule/*` events
530
+
531
+ <a id="schedulechanged--emit"></a>
532
+
533
+ #### `schedule/changed` - emit
534
+
535
+ Durable task set changed; clients refetch global task and Session-active catalogs.
536
+
537
+ ```ts cordis-catalog
538
+ /** Durable task set changed; clients refetch global task and Session-active catalogs.
539
+ * @mode emit
540
+ */
541
+ 'schedule/changed'(): void
542
+ ```
543
+
544
+ Source: [`packages/schedule/schedule/src/types.ts`](../../packages/schedule/schedule/src/types.ts)
545
+ <!-- END GENERATED cordis-surface -->
@@ -0,0 +1,61 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/scope.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Scoped Registration
4
+
5
+ English | [中文](scope.zh.md)
6
+
7
+ The [scope package](../../packages/core/scope) supplies the identity, carrier, and scoped-layer vocabulary that makes one registration context mean both per-agent visibility and shared lifetime ownership. It is a library primitive rather than a Cordis service; the [agent-scope runtime-design Agent Note](../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#scope-routing-one-opaque-key-selects-one-layer) owns the lifecycle rationale, and the package [README](../../packages/core/scope/README.md) owns the callable API and filtering semantics.
8
+
9
+ Sources: [`packages/core/scope/src/index.ts`](../../packages/core/scope/src/index.ts) and [`packages/core/scope/src/store.ts`](../../packages/core/scope/src/store.ts).
10
+
11
+ ## Identity and dispatch carrier
12
+
13
+ `ScopeKey` is an opaque object identity. The shipped loop uses the live `Agent` object as its own key, but the primitive never inspects the object.
14
+
15
+ ```ts type-equiv
16
+ /** An opaque, identity-compared scope key. */
17
+ type ScopeKey = object
18
+ ```
19
+
20
+ `Scoped<T>` is the compile-time brand on the opaque routing receiver returned by `scopeTarget(base, key)`. Scope-filtered event declarations require this carrier as their `this` type, while the real event subject remains an explicit argument.
21
+
22
+ ```ts type-equiv
23
+ /**
24
+ * A routing-only event receiver built by {@link scopeTarget}. The type
25
+ * parameter records the subject type for dispatch checking; the carrier does
26
+ * not expose the subject's properties. Event payloads carry the real subject.
27
+ */
28
+ type Scoped<T extends object> = object & { readonly [ScopedBrand]: T }
29
+ ```
30
+
31
+ ## Owned registration context
32
+
33
+ `Scope` pairs the tagged registration context with two teardown paths. `rawDispose` preserves the exact Cordis disposer identity needed by an ordered composite effect; `dispose()` is the public shared quiescence boundary for direct and racing callers.
34
+
35
+ ```ts type-equiv
36
+ /** A minted registration scope and its quiescent disposal boundaries. */
37
+ interface Scope {
38
+ /** Context through which scope-owned registrations are made. */
39
+ ctx: Context
40
+ /** Exact Cordis disposer, used when nesting this scope in an ordered composite effect. */
41
+ rawDispose: () => Promise<void> | void
42
+ /** Dispose every scope-owned registration; racing calls await the same completion. */
43
+ dispose(): Promise<void>
44
+ }
45
+ ```
46
+
47
+ ## Scoped registry layer
48
+
49
+ `ScopeLayer` represents one registry's complete contribution at the global or exact-scope level. A concrete layer may aggregate multiple named and anonymous tables; whole-layer emptiness lets `ScopedLayers` reclaim scoped state without discarding a sibling table.
50
+
51
+ ```ts type-equiv
52
+ /** One scope's aggregate contribution to a registry. */
53
+ interface ScopeLayer {
54
+ /** Whether every table in this layer is empty. */
55
+ isEmpty(): boolean
56
+ }
57
+ ```
58
+
59
+ `ScopedLayers<L>` owns the eager global layer and lazily created exact-scope layers. Reads do not create layers: `peek(undefined)` means no overlay, while `merge()` materializes insertion-ordered global named entries followed by scoped shadows. Registrations use one context for both visibility and Cordis effect ownership, collect one synchronous undo before optional notification, return Cordis's exact disposer, and reclaim a scoped layer only when its complete `ScopeLayer` is empty.
60
+
61
+ `NamedEntries<V>` supplies insertion-ordered lookup and live iteration with caller-owned duplicate errors. `AnonymousEntries<V>` gives every append a unique identity so equal values remain independent. Iteration stays live within one nonempty table generation; draining the table detaches existing iterators from later insertions. Both return idempotent exact-entry undos; the shared `EntryValues` implementation interface is not public.