1/**

2 * Durable and model-facing Schedule value types.

3 * @module @deepseek-ai/dsh-schedule

4 */

5

6import type { SessionId } from '@deepseek-ai/dsh-session/types'

7import type { MessageId } from '@deepseek-ai/dsh-llm/brand'

8import type { Branded } from '@deepseek-ai/dsh-brand'

9import type {} from '@deepseek-ai/dsh-session/types'

10// Type-only: the Workspace registry's archive-admission family map this plugin merges `schedule` into.

11import type {} from '@deepseek-ai/dsh-workspace/types'

12

13/** Stable globally unique reminder identity. */

14export type ScheduleId = Branded<'ScheduleId'>

15

16/** Durable one-shot reminder created from a positive delay. */

17export interface AfterScheduleRecord {

18 /** Globally unique task identity. */

19 readonly id: ScheduleId

20 /** Rule discriminator for a delayed one-shot reminder. */

21 readonly kind: 'after'

22 /** Required stored task name; already trimmed, non-empty, and at most 120 characters. */

23 readonly title: string

24 /** Trimmed reminder content supplied at creation. */

25 readonly prompt: string

26 /** Positive safe-integer delay accepted at creation. */

27 readonly afterSeconds: number

28 /** Four-digit-year RFC 3339 UTC target. */

29 readonly scheduledAt: string

30}

31

32/** Durable one-shot reminder created from an absolute instant. */

33export 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/** Durable fixed-rate reminder aligned to creation or its most recent interval edit. */

47export interface EveryScheduleRecord {

48 /** Globally unique task identity. */

49 readonly id: ScheduleId

50 /** Rule discriminator for a fixed-rate recurring reminder. */

51 readonly kind: 'every'

52 /** Required stored task name; already trimmed, non-empty, and at most 120 characters. */

53 readonly title: string

54 /** Trimmed reminder content supplied at creation. */

55 readonly prompt: string

56 /** Fixed safe-integer interval, never below one minute. */

57 readonly everySeconds: number

58 /** Next anchor-aligned occurrence while active, or final occurrence when inactive. */

59 readonly scheduledAt: string

60}

61

62/** Durable daily wall-clock reminder; gaps skip a date and overlaps use the earlier instant. */

63export interface DailyScheduleRecord {

64 /** Globally unique task identity. */

65 readonly id: ScheduleId

66 /** Rule discriminator for a daily wall-clock reminder. */

67 readonly kind: 'daily'

68 /** Required stored task name; already trimmed, non-empty, and at most 120 characters. */

69 readonly title: string

70 /** Trimmed reminder content supplied at creation. */

71 readonly prompt: string

72 /** Local time normalized to HH:mm:ss.SSS. */

73 readonly time: string

74 /** Explicit IANA zone; equivalent timing edits retain the stored spelling. */

75 readonly timeZone: string

76 /** Committed next UTC instant while active, or final occurrence when inactive. */

77 readonly scheduledAt: string

78}

79

80/** Durable weekly wall-clock reminder; gaps skip a date and overlaps use the earlier instant. */

81export interface WeeklyScheduleRecord {

82 /** Globally unique task identity. */

83 readonly id: ScheduleId

84 /** Rule discriminator for a weekly wall-clock reminder. */

85 readonly kind: 'weekly'

86 /** Required stored task name; already trimmed, non-empty, and at most 120 characters. */

87 readonly title: string

88 /** Trimmed reminder content supplied at creation. */

89 readonly prompt: string

90 /** Local time normalized to HH:mm:ss.SSS. */

91 readonly time: string

92 /** Explicit canonical IANA zone; equivalent timing edits retain the stored spelling. */

93 readonly timeZone: string

94 /** Unique ascending ISO weekdays, Monday 1 through Sunday 7. */

95 readonly weekdays: number[]

96 /** Committed next UTC instant while active, or final occurrence when inactive. */

97 readonly scheduledAt: string

98}

99

100/** Durable cron wall-clock reminder; gaps skip a date and overlaps use the earlier instant. */

101export interface CronScheduleRecord {

102 /** Globally unique task identity. */

103 readonly id: ScheduleId

104 /** Rule discriminator for a five-field cron wall-clock reminder. */

105 readonly kind: 'cron'

106 /** Required stored task name; already trimmed, non-empty, and at most 120 characters. */

107 readonly title: string

108 /** Trimmed reminder content supplied at creation. */

109 readonly prompt: string

110 /** Canonical five-field cron expression: minute hour day-of-month month day-of-week. */

111 readonly expression: string

112 /** Explicit IANA zone; equivalent timing edits retain the stored spelling. */

113 readonly timeZone: string

114 /** Committed next UTC instant while active, or final occurrence when inactive. */

115 readonly scheduledAt: string

116}

117

118/** Daily local-time selector accepted by creation and timing edits. */

119export interface DailyInput {

120 /** Local HH:mm:ss time with optional one-to-three fractional digits. */

121 readonly time: string

122 /** Explicit UTC or IANA Area/Location zone. */

123 readonly time_zone: string

124}

125

126/** Weekly local-time and weekday selector accepted by creation and timing edits. */

127export interface WeeklyInput {

128 /** Local HH:mm:ss time with optional one-to-three fractional digits. */

129 readonly time: string

130 /** Explicit UTC or IANA Area/Location zone. */

131 readonly time_zone: string

132 /** Non-empty ISO weekday set, Monday 1 through Sunday 7, without repetitions. */

133 readonly weekdays: number[]

134}

135

136/** Five-field cron selector accepted by creation and timing edits. */

137export interface CronInput {

138 /** Five-field Vixie cron expression: minute hour day-of-month month day-of-week. */

139 readonly expression: string

140 /** Explicit UTC or IANA Area/Location zone. */

141 readonly time_zone: string

142}

143

144/** Structured local-calendar input accepted by creation and timing edits. */

145export interface LocalAtInput {

146 /** Four-digit ISO calendar date. */

147 readonly date: string

148 /** Local wall-clock time with optional one-to-three digit milliseconds. */

149 readonly time: string

150 /** Explicit UTC or IANA Area/Location zone. */

151 readonly time_zone: string

152}

153

154/** Absolute selector accepted by creation and timing edits. */

155export type AtInput = string | LocalAtInput

156

157/** One-shot task variants. */

158export type OneShotScheduleRecord = AfterScheduleRecord | AtScheduleRecord

159

160/** One-shot delay persisted by a version-1 Session event, without the later `title`. */

161export interface LegacyAfterScheduleRecord extends Omit<AfterScheduleRecord, 'title'> {

162 /** Stored task name; absent in an event written before titles existed. */

163 readonly title?: string

164}

165

166/** Absolute one-shot persisted by a version-1 Session event, without the later `title`. */

167export interface LegacyAtScheduleRecord extends Omit<AtScheduleRecord, 'title'> {

168 /** Stored task name; absent in an event written before titles existed. */

169 readonly title?: string

170}

171

172/** Fixed-rate reminder persisted by a version-1 Session event, without the later `title`. */

173export interface LegacyEveryScheduleRecord extends Omit<EveryScheduleRecord, 'title'> {

174 /** Stored task name; absent in an event written before titles existed. */

175 readonly title?: string

176}

177

178/**

179 * Frozen Session event and fold vocabulary; daily rules belong only to Host storage.

180 *

181 * A version-1 event written before titles existed persists no `title` member, so

182 * `after`, `at`, and `every` decode without one and stay readable. The Host task

183 * record requires the member and never persists a record without it.

184 */

185export type LegacyScheduleRecord =

186 | LegacyAfterScheduleRecord

187 | LegacyAtScheduleRecord

188 | LegacyEveryScheduleRecord

189

190/** Recurring Host task variants. */

191export type RecurringScheduleRecord = EveryScheduleRecord | DailyScheduleRecord | WeeklyScheduleRecord | CronScheduleRecord

192

193/** Reminder rule and target, stored with its original Session binding. */

194export type ScheduleRecord = OneShotScheduleRecord | RecurringScheduleRecord

195

196/** Durable Session inbox delivery acknowledgment, not model execution completion. */

197export interface ScheduleDeliveryReceipt {

198 /** Canonical UTC target of the delivered occurrence. */

199 readonly scheduledAt: string

200 /** Canonical UTC time sampled after Session persistence acknowledged delivery. */

201 readonly deliveredAt: string

202 /** Identity of the delivered message, shared by tasks in one recurring batch. */

203 readonly messageId: MessageId

204}

205

206/** Saved inbox delivery with its immutable sent prompt when recorded by this Host. */

207export interface ScheduleDeliveryRecord extends ScheduleDeliveryReceipt {

208 /** Prompt sent for this occurrence; unavailable for legacy receipts. */

209 readonly prompt?: string

210}

211

212/** Browser-safe retained reminder with its original Session binding. */

213export type ScheduleCatalogEntry = ScheduleRecord & {

214 /** Session receiving this reminder when it becomes due. */

215 readonly sessionId: SessionId

216 /** Inactive reminders remain visible but never schedule another delivery. */

217 readonly status: 'active' | 'inactive'

218 /** Most recent durably acknowledged inbox delivery, when available. */

219 readonly lastDelivery?: ScheduleDeliveryReceipt

220}

221

222/** Creates one durable reminder record. */

223export interface ScheduleCreateChange {

224 readonly version: 1

225 readonly operation: 'create'

226 readonly schedule: LegacyScheduleRecord

227}

228

229/** Deletes one currently active reminder. */

230export interface ScheduleDeleteChange {

231 readonly version: 1

232 readonly operation: 'delete'

233 readonly id: ScheduleId

234}

235

236/** Records that one active one-shot reminder entered the durable dispatch history. */

237export interface OneShotScheduleDispatchChange {

238 readonly version: 1

239 readonly operation: 'dispatch'

240 readonly id: ScheduleId

241}

242

243/** Records one fixed-rate decision and advances directly past missed occurrences. */

244export interface EveryScheduleDispatchChange {

245 readonly version: 1

246 readonly operation: 'dispatch'

247 readonly id: ScheduleId

248 /** Wall-clock decision time used to select the latest due occurrence. */

249 readonly acceptedAt: string

250}

251

252/** Durable dispatch shapes supported by the current rule set. */

253export type ScheduleDispatchChange = OneShotScheduleDispatchChange | EveryScheduleDispatchChange

254

255/** Strict version-1 durable Schedule mutation union. */

256export type ScheduleChange = ScheduleCreateChange | ScheduleDeleteChange | ScheduleDispatchChange

257

258/** Current delivery timing derived from the durable record and wall clock. */

259export type ScheduleState = 'scheduled' | 'overdue'

260

261/** Host-driven delivery resumes the original Session when needed. */

262export type ScheduleDeliveryMode = 'host'

263

264/** Complete model-facing view of one active reminder. */

265export type ScheduleView = ScheduleRecord & {

266 /** Whether the target remains in the future. */

267 readonly state: ScheduleState

268 /** Reminder delivery never leaves the owning session. */

269 readonly deliveryMode: ScheduleDeliveryMode

270}

271

272/** Stable error returned for an empty, over-long, or untrimmed reminder prompt or title. */

273export interface InvalidPromptError {

274 readonly code: 'invalid_prompt'

275 readonly message: string

276}

277

278/** Stable error returned for a missing, conflicting, or unsupported rule selector. */

279export interface InvalidSelectorError {

280 readonly code: 'invalid_selector'

281 readonly message: string

282}

283

284/** Stable error returned for an invalid rule or management argument. */

285export interface InvalidRuleError {

286 readonly code: 'invalid_rule'

287 readonly message: string

288}

289

290/** Stable error returned for an invalid or unsupported IANA time zone. */

291export interface InvalidTimeZoneError {

292 readonly code: 'invalid_time_zone'

293 readonly message: string

294}

295

296/** Stable error returned when an absolute target is not strictly future. */

297export interface NotFutureError {

298 readonly code: 'not_future'

299 readonly message: string

300}

301

302/** Stable error returned when the computed instant cannot use a four-digit UTC year. */

303export interface TimeOutOfRangeError {

304 readonly code: 'time_out_of_range'

305 readonly message: string

306}

307

308/** Stable error returned when a fixed-rate rule runs more often than supported. */

309export interface FrequencyTooHighError {

310 readonly code: 'frequency_too_high'

311 readonly message: string

312}

313

314/** Stable error returned when the target Session belongs to subagent routing, which never receives reminder delivery. */

315export interface SubagentSessionError {

316 readonly code: 'subagent_session'

317 readonly message: string

318}

319

320/** Stable fallback that does not disclose an internal exception. */

321export interface InternalScheduleError {

322 readonly code: 'internal_error'

323 readonly message: string

324}

325

326/** Closed v1 Schedule management error union. */

327export type ScheduleToolError =

328 | InvalidPromptError

329 | InvalidSelectorError

330 | InvalidRuleError

331 | InvalidTimeZoneError

332 | NotFutureError

333 | TimeOutOfRangeError

334 | FrequencyTooHighError

335 | SubagentSessionError

336 | InternalScheduleError

337

338/** Canonical `schedule_create` value. */

339export type ScheduleCreateValue = ScheduleView | ScheduleToolError

340

341/** Canonical `schedule_list` value. */

342export type ScheduleListValue = ScheduleView[] | ScheduleToolError

343

344/** Successful `schedule_delete` value, including the non-mutating not-found result. */

345export type ScheduleDeleteResult =

346 | { readonly id: ScheduleId; readonly deleted: true }

347 | { readonly id: ScheduleId; readonly deleted: false; readonly code: 'schedule_not_found' }

348

349/** Canonical `schedule_delete` value. */

350export type ScheduleDeleteValue = ScheduleDeleteResult | ScheduleToolError

351

352declare module '@deepseek-ai/dsh-workspace/types' {

353 interface SessionActivityKindMap {

354 /** A scheduled follow-up for this session is still active. */

355 schedule: true

356 }

357}

358

359declare module '@deepseek-ai/dsh-session/types' {

360 interface SessionEventMap {

361 /**

362 * Versioned Schedule mutation. The owning package validates the complete

363 * session-local transition stream before accepting a candidate event.

364 */

365 'schedule/change': ScheduleChange

366 }

367}

368

369/** Reminder creation selector, shared by the model consumer and Host service. */

370export interface ScheduleCreateRequest {

371 /** Non-empty reminder text. */

372 prompt: string

373 /** Required task name of at most 120 characters, non-empty after trimming; names the card, detail heading, and task lists. */

374 title: string

375 /** Relative one-shot delay in seconds. */

376 after_seconds?: number

377 /** Absolute one-shot target. */

378 at?: AtInput

379 /** Fixed recurrence interval in seconds. */

380 every_seconds?: number

381 /** Daily wall-clock time in an explicit IANA zone. */

382 daily?: DailyInput

383 /** Weekly wall-clock time and explicit ISO weekday set in an IANA zone. */

384 weekly?: WeeklyInput

385 /** Five-field cron expression evaluated in an explicit IANA zone. */

386 cron?: CronInput

387}

388

389/** Session-scoped task list, without Agent activation. */

390export interface ScheduleListRequest {

391 /** Original Session binding. */

392 sessionId: SessionId

393}

394

395/** Delete request identifying a task within its original Session binding. */

396export interface ScheduleDeleteRequest extends ScheduleListRequest {

397 /** Task to remove. */

398 id: ScheduleId

399}

400

401/** Timing-only edit; it may select a different recurrence kind than the stored record, and one-shot targets use an absolute `at`. */

402export type ScheduleTimingChange =

403 | { readonly kind: 'at'; readonly at: AtInput }

404 | { readonly kind: 'every'; readonly every_seconds: number }

405 | { readonly kind: 'daily'; readonly daily: DailyInput }

406 | { readonly kind: 'weekly'; readonly weekly: WeeklyInput }

407 | { readonly kind: 'cron'; readonly cron: CronInput }

408

409/** Replacement task name and instruction carried by one compare-and-update request. */

410export interface ScheduleUpdateContent {

411 /** Task name of at most 120 characters, non-empty after trimming; omitted keeps the stored name. */

412 readonly title?: string

413 /** Reminder instruction, non-empty after trimming; omitted keeps the stored instruction. */

414 readonly prompt?: string

415}

416

417/** Compare-and-update request within the original Session binding. */

418export interface ScheduleUpdateRequest extends ScheduleDeleteRequest, ScheduleUpdateContent {

419 /** Complete record observed when editing began, including the committed target. */

420 readonly expected: ScheduleRecord

421 /** New timing; its kind may differ from the stored record's kind, and an omitted value keeps the committed target. */

422 readonly change?: ScheduleTimingChange

423}

424

425/** Non-mutating compare-and-update outcome: unknown, inactive, or changed since the read. */

426export interface ScheduleUpdateMiss {

427 readonly id: ScheduleId

428 readonly updated: false

429 readonly code: 'schedule_not_found' | 'schedule_ended' | 'schedule_conflict'

430}

431

432/** Successful current record, non-mutating lookup/conflict failure, or invalid name/instruction/timing. */

433export type ScheduleUpdateResult =

434 | { readonly id: ScheduleId; readonly updated: boolean; readonly record: ScheduleRecord }

435 | ScheduleUpdateMiss

436 | ScheduleToolError

437

438/** Canonical `schedule_update` value: the committed record as a view, or the non-mutating lookup/conflict result. */

439export type ScheduleUpdateValue = ScheduleView | ScheduleUpdateMiss | ScheduleToolError

440

441/** Explicitly bounded saved-delivery query within one Session binding. */

442export interface ScheduleDeliveryHistoryRequest extends ScheduleDeleteRequest {

443 /** Required safe-integer page size from 1 through 100. */

444 limit: number

445 /** Message identity of the oldest entry in the previous page; excluded from this page. */

446 before?: MessageId

447}

448

449/** Configured limits applied when appending one task's delivery receipt. */

450export interface DeliveryRetentionBounds {

451 /** Retained window in days, measured back from the acknowledgment being appended. */

452 readonly days: number

453 /** Maximum retained records per task; the newest survive. */

454 readonly records: number

455}

456

457/** Newest-first saved deliveries, or a non-mutating task/cursor lookup failure. */

458export type ScheduleDeliveryHistoryResult =

459 | {

460 readonly id: ScheduleId

461 readonly records: ScheduleDeliveryRecord[]

462 /** Whether earlier delivery records may be unavailable; missing receipts are never reconstructed. */

463 readonly earlierRecordsUnavailable: boolean

464 /** True only after an append removed saved records; absent legacy evidence is false. */

465 readonly earlierRecordsPruned: boolean

466 /** Current Host retention configuration, also used by the delivery writer. */

467 readonly retention: DeliveryRetentionBounds

468 /** Oldest returned message identity, present only when older saved records remain. */

469 readonly nextBefore?: MessageId

470 }

471 | { readonly id: ScheduleId; readonly code: 'schedule_not_found' | 'delivery_cursor_not_found' }

472

473declare module '@deepseek-ai/cordis' {

474 interface Events {

475 /** Durable task set changed; clients refetch global task and Session-active catalogs.

476 * @mode emit

477 */

478 'schedule/changed'(): void

479 }

480}