|
|
@@ -2,18 +2,18 @@
|
|
|
|
|
|
English | [中文](schedule.zh.md)
|
|
|
|
|
|
-Schedule owns durable reminders that return to the original live Session as ordinary later conversation turns. The [durable Schedule Agent Note](../../.agents/notes/implemented/feature/2026-08-05-durable-web-schedule.md) owns the persistence and lifecycle decisions, and [conversational delivery](../../.agents/notes/implemented/simplification/2026-08-09-conversational-schedule-delivery.md) owns the no-receipt boundary. This page records the durable and model-facing shapes from [`packages/schedule/tool-schedule/src/types.ts`](../../packages/schedule/tool-schedule/src/types.ts); the [package README](../../packages/schedule/tool-schedule/README.md) owns composition, tool behavior, and the exact reminder framing.
|
|
|
+Schedule owns durable reminders that return to the original live Session as ordinary later conversation turns. The [durable Schedule Agent Note](../../.agents/notes/implemented/feature/2026-08-05-durable-web-schedule.md) owns the persistence and lifecycle decisions, [conversational delivery](../../.agents/notes/implemented/simplification/2026-08-09-conversational-schedule-delivery.md) owns the no-receipt boundary, and the [explicit time-zone boundary](../../.agents/notes/implemented/simplification/2026-08-09-explicit-schedule-time-zone.md) owns browser-local interpretation. This page records the durable and model-facing shapes from [`packages/schedule/tool-schedule/src/types.ts`](../../packages/schedule/tool-schedule/src/types.ts); the [package README](../../packages/schedule/tool-schedule/README.md) owns composition, tool behavior, and the exact reminder framing.
|
|
|
|
|
|
## Durable records
|
|
|
|
|
|
-`ScheduleId` is a [branded id](core.md#branded-ids), unique and never reused within one Session. Version 1 initially supports a positive safe-integer `after_seconds` selector. Creation canonicalizes the selected target into a four-digit-year RFC 3339 UTC `scheduledAt`; the submitted delay remains in the record so list results explain the rule that produced it.
|
|
|
+`ScheduleId` is a [branded id](core.md#branded-ids), unique and never reused within one Session. Version 1 supports either a positive safe-integer `after_seconds` delay or an explicit absolute `at` target. Creation canonicalizes either selector into a four-digit-year RFC 3339 UTC `scheduledAt`; an `after` record retains its submitted delay, while an `at` record stores only the resulting instant.
|
|
|
|
|
|
```ts type-equiv
|
|
|
/** Durable one-shot reminder created from a positive delay. */
|
|
|
interface AfterScheduleRecord {
|
|
|
/** Session-local stable identity. */
|
|
|
readonly id: ScheduleId
|
|
|
- /** Rule discriminator; v1 supports only delayed one-shot reminders. */
|
|
|
+ /** Rule discriminator for a delayed one-shot reminder. */
|
|
|
readonly kind: 'after'
|
|
|
/** Trimmed reminder content supplied at creation. */
|
|
|
readonly prompt: string
|
|
|
@@ -24,11 +24,50 @@ interface AfterScheduleRecord {
|
|
|
}
|
|
|
```
|
|
|
|
|
|
+```ts type-equiv
|
|
|
+/** Durable one-shot reminder created from an absolute instant. */
|
|
|
+interface AtScheduleRecord {
|
|
|
+ /** Session-local stable identity. */
|
|
|
+ readonly id: ScheduleId
|
|
|
+ /** Rule discriminator for an absolute one-shot reminder. */
|
|
|
+ readonly kind: 'at'
|
|
|
+ /** Trimmed reminder content supplied at creation. */
|
|
|
+ readonly prompt: string
|
|
|
+ /** Four-digit-year RFC 3339 UTC target. */
|
|
|
+ readonly scheduledAt: string
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
```ts type-equiv
|
|
|
/** The v1 durable reminder record union. */
|
|
|
-type ScheduleRecord = AfterScheduleRecord
|
|
|
+type ScheduleRecord = AfterScheduleRecord | AtScheduleRecord
|
|
|
```
|
|
|
|
|
|
+## Absolute-time input
|
|
|
+
|
|
|
+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:
|
|
|
+
|
|
|
+```ts type-equiv
|
|
|
+/** Structured local-calendar input accepted by `schedule_create`. */
|
|
|
+interface LocalAtInput {
|
|
|
+ /** Four-digit ISO calendar date. */
|
|
|
+ readonly date: string
|
|
|
+ /** Local wall-clock time with optional one-to-three digit milliseconds. */
|
|
|
+ readonly time: string
|
|
|
+ /** Explicit UTC or IANA Area/Location zone. */
|
|
|
+ readonly time_zone: string
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+```ts type-equiv
|
|
|
+/** Absolute selector accepted by `schedule_create`. */
|
|
|
+type AtInput = string | LocalAtInput
|
|
|
+```
|
|
|
+
|
|
|
+The official Web overlay 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 provenance tells 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.
|
|
|
+
|
|
|
+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.
|
|
|
+
|
|
|
## Durable changes and replay
|
|
|
|
|
|
The version-1 `schedule/change` Session event is the only durable Schedule authority. Create stores the complete record. Delete and dispatch are terminal id-only transitions for one-shot reminders; dispatch means the follow-up was synchronously queued, not that a model answer succeeded or the user read it.
|
|
|
@@ -82,8 +121,8 @@ type ScheduleDeliveryMode = 'session-local'
|
|
|
```
|
|
|
|
|
|
```ts type-equiv
|
|
|
-/** Complete model-facing view of one active after reminder. */
|
|
|
-interface ScheduleView extends AfterScheduleRecord {
|
|
|
+/** Complete model-facing view of one active reminder. */
|
|
|
+type ScheduleView = ScheduleRecord & {
|
|
|
/** Whether the target remains in the future. */
|
|
|
readonly state: ScheduleState
|
|
|
/** Reminder delivery never leaves the owning session. */
|
|
|
@@ -91,7 +130,7 @@ interface ScheduleView extends AfterScheduleRecord {
|
|
|
}
|
|
|
```
|
|
|
|
|
|
-The generated [tool catalog](../tool-catalog.md#deepseek-aidsh-tool-schedule) owns the argument and result schemas for `schedule_create`, `schedule_list`, and `schedule_delete`. Management calls serialize with due work in one Agent-scoped queue. Every read or decision first waits for the shared Session persistence barrier; create and an actual delete wait again after appending. A barrier failure reports `persistence_uncertain` instead of guessing whether an eager write committed. The other stable error codes are `invalid_prompt`, `invalid_selector`, `invalid_rule`, `time_out_of_range`, `corrupt_schedule_log`, and `internal_error`.
|
|
|
+The generated [tool catalog](../tool-catalog.md#deepseek-aidsh-tool-schedule) owns the argument and result schemas for `schedule_create`, `schedule_list`, and `schedule_delete`. Management calls serialize with due work in one Agent-scoped queue. Every read or decision first waits for the shared Session persistence barrier; create and an actual delete wait again after appending. A barrier failure reports `persistence_uncertain` instead of guessing whether an eager write committed. The other stable error codes are `invalid_prompt`, `invalid_selector`, `invalid_rule`, `invalid_time_zone`, `not_future`, `time_out_of_range`, `corrupt_schedule_log`, and `internal_error`.
|
|
|
|
|
|
## Live delivery
|
|
|
|
Tianyi Cui