@deepagents/experimental 6.1.0 → 7.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (129) hide show
  1. package/README.md +151 -10
  2. package/dist/coding-agent-reminders/types.d.ts.map +1 -1
  3. package/dist/index.js +3084 -1206
  4. package/dist/index.js.map +4 -4
  5. package/dist/providers/claude/index.d.ts +4 -0
  6. package/dist/providers/claude/index.d.ts.map +1 -0
  7. package/dist/providers/claude/index.js +196 -0
  8. package/dist/providers/claude/index.js.map +7 -0
  9. package/dist/providers/claude/local-credentials.d.ts +3 -0
  10. package/dist/providers/claude/local-credentials.d.ts.map +1 -0
  11. package/dist/providers/codex/generate-via-stream.d.ts +8 -0
  12. package/dist/providers/codex/generate-via-stream.d.ts.map +1 -0
  13. package/dist/providers/codex/index.d.ts +4 -0
  14. package/dist/providers/codex/index.d.ts.map +1 -0
  15. package/dist/providers/codex/index.js +358 -0
  16. package/dist/providers/codex/index.js.map +7 -0
  17. package/dist/providers/codex/local-credentials.d.ts +4 -0
  18. package/dist/providers/codex/local-credentials.d.ts.map +1 -0
  19. package/dist/providers/language-model-provider.d.ts +5 -0
  20. package/dist/providers/language-model-provider.d.ts.map +1 -0
  21. package/dist/zukhruf/agent.d.ts +17 -2
  22. package/dist/zukhruf/agent.d.ts.map +1 -1
  23. package/dist/zukhruf/collaboration/agent-tool-context.d.ts +2 -2
  24. package/dist/zukhruf/collaboration/agent-tool-context.d.ts.map +1 -1
  25. package/dist/zukhruf/collaboration/collaboration-tools.d.ts +1807 -3
  26. package/dist/zukhruf/collaboration/collaboration-tools.d.ts.map +1 -1
  27. package/dist/zukhruf/collaboration/spawn-agent.d.ts.map +1 -1
  28. package/dist/zukhruf/collaboration/wait-agent.d.ts.map +1 -1
  29. package/dist/zukhruf/control-plane/agent-control-plane.d.ts +6 -7
  30. package/dist/zukhruf/control-plane/agent-control-plane.d.ts.map +1 -1
  31. package/dist/zukhruf/control-plane/agent-declaration-registry.d.ts +1 -0
  32. package/dist/zukhruf/control-plane/agent-declaration-registry.d.ts.map +1 -1
  33. package/dist/zukhruf/control-plane/agent-status-projector.d.ts +6 -3
  34. package/dist/zukhruf/control-plane/agent-status-projector.d.ts.map +1 -1
  35. package/dist/zukhruf/control-plane/agent-thread.d.ts.map +1 -1
  36. package/dist/zukhruf/index.d.ts +7 -3
  37. package/dist/zukhruf/index.d.ts.map +1 -1
  38. package/dist/zukhruf/index.js +3085 -1207
  39. package/dist/zukhruf/index.js.map +4 -4
  40. package/dist/zukhruf/{multi-agent-v2-config.d.ts → multi-agent-config.d.ts} +14 -9
  41. package/dist/zukhruf/multi-agent-config.d.ts.map +1 -0
  42. package/dist/zukhruf/plugins/conversation-scheduling/conversation-scheduler.d.ts +76 -0
  43. package/dist/zukhruf/plugins/conversation-scheduling/conversation-scheduler.d.ts.map +1 -0
  44. package/dist/zukhruf/plugins/conversation-scheduling/index.d.ts +13 -0
  45. package/dist/zukhruf/plugins/conversation-scheduling/index.d.ts.map +1 -0
  46. package/dist/zukhruf/plugins/conversation-scheduling/index.js +999 -0
  47. package/dist/zukhruf/plugins/conversation-scheduling/index.js.map +7 -0
  48. package/dist/zukhruf/plugins/conversation-scheduling/pg-boss.wake-scheduler.d.ts +19 -0
  49. package/dist/zukhruf/plugins/conversation-scheduling/pg-boss.wake-scheduler.d.ts.map +1 -0
  50. package/dist/zukhruf/plugins/conversation-scheduling/tools.d.ts +1305 -0
  51. package/dist/zukhruf/plugins/conversation-scheduling/tools.d.ts.map +1 -0
  52. package/dist/zukhruf/plugins/conversation-scheduling/wake-scheduler.d.ts +12 -0
  53. package/dist/zukhruf/plugins/conversation-scheduling/wake-scheduler.d.ts.map +1 -0
  54. package/dist/zukhruf/plugins/http/index.d.ts +50 -0
  55. package/dist/zukhruf/plugins/http/index.d.ts.map +1 -0
  56. package/dist/zukhruf/plugins/http/index.js +618 -0
  57. package/dist/zukhruf/plugins/http/index.js.map +7 -0
  58. package/dist/zukhruf/plugins/http/parse.d.ts +3 -0
  59. package/dist/zukhruf/plugins/http/parse.d.ts.map +1 -0
  60. package/dist/zukhruf/plugins/http/validator.d.ts +64 -0
  61. package/dist/zukhruf/plugins/http/validator.d.ts.map +1 -0
  62. package/dist/zukhruf/plugins/mcp/index.d.ts +8 -0
  63. package/dist/zukhruf/plugins/mcp/index.d.ts.map +1 -0
  64. package/dist/zukhruf/plugins/mcp/index.js +25 -0
  65. package/dist/zukhruf/plugins/mcp/index.js.map +7 -0
  66. package/dist/zukhruf/plugins/schedules/http.d.ts +45 -0
  67. package/dist/zukhruf/plugins/schedules/http.d.ts.map +1 -0
  68. package/dist/zukhruf/plugins/schedules/http.js +528 -0
  69. package/dist/zukhruf/plugins/schedules/http.js.map +7 -0
  70. package/dist/zukhruf/plugins/schedules/index.d.ts +35 -0
  71. package/dist/zukhruf/plugins/schedules/index.d.ts.map +1 -0
  72. package/dist/zukhruf/plugins/schedules/index.js +1873 -0
  73. package/dist/zukhruf/plugins/schedules/index.js.map +7 -0
  74. package/dist/zukhruf/plugins/schedules/schedule-files.d.ts +6 -0
  75. package/dist/zukhruf/plugins/schedules/schedule-files.d.ts.map +1 -0
  76. package/dist/zukhruf/plugins/schedules/scheduled-tasks.d.ts +157 -0
  77. package/dist/zukhruf/plugins/schedules/scheduled-tasks.d.ts.map +1 -0
  78. package/dist/zukhruf/plugins/uploads/http.d.ts +27 -0
  79. package/dist/zukhruf/plugins/uploads/http.d.ts.map +1 -0
  80. package/dist/zukhruf/plugins/uploads/http.js +426 -0
  81. package/dist/zukhruf/plugins/uploads/http.js.map +7 -0
  82. package/dist/zukhruf/plugins/uploads/index.d.ts +73 -0
  83. package/dist/zukhruf/plugins/uploads/index.d.ts.map +1 -0
  84. package/dist/zukhruf/plugins/uploads/index.js +247 -0
  85. package/dist/zukhruf/plugins/uploads/index.js.map +7 -0
  86. package/dist/zukhruf/queue/pg-boss-notifications.d.ts +10 -0
  87. package/dist/zukhruf/queue/pg-boss-notifications.d.ts.map +1 -0
  88. package/dist/zukhruf/queue/pg-boss.turn-queue.d.ts +8 -11
  89. package/dist/zukhruf/queue/pg-boss.turn-queue.d.ts.map +1 -1
  90. package/dist/zukhruf/queue/turn-queue.d.ts +43 -38
  91. package/dist/zukhruf/queue/turn-queue.d.ts.map +1 -1
  92. package/dist/zukhruf/runtime/agent-runtime.d.ts +163 -43
  93. package/dist/zukhruf/runtime/agent-runtime.d.ts.map +1 -1
  94. package/dist/zukhruf/runtime/agent-turn-executor.d.ts +9 -2
  95. package/dist/zukhruf/runtime/agent-turn-executor.d.ts.map +1 -1
  96. package/dist/zukhruf/runtime/approval-controller.d.ts +10 -25
  97. package/dist/zukhruf/runtime/approval-controller.d.ts.map +1 -1
  98. package/dist/zukhruf/runtime/compaction.d.ts +47 -0
  99. package/dist/zukhruf/runtime/compaction.d.ts.map +1 -0
  100. package/dist/zukhruf/runtime/conversation-status/change-source.d.ts +19 -0
  101. package/dist/zukhruf/runtime/conversation-status/change-source.d.ts.map +1 -0
  102. package/dist/zukhruf/runtime/conversation-status/child-progress.d.ts +84 -0
  103. package/dist/zukhruf/runtime/conversation-status/child-progress.d.ts.map +1 -0
  104. package/dist/zukhruf/runtime/conversation-status/pg-boss-change-source.d.ts +22 -0
  105. package/dist/zukhruf/runtime/conversation-status/pg-boss-change-source.d.ts.map +1 -0
  106. package/dist/zukhruf/runtime/conversation-status/projector.d.ts +62 -0
  107. package/dist/zukhruf/runtime/conversation-status/projector.d.ts.map +1 -0
  108. package/dist/zukhruf/runtime/conversation-status/status-publishing-turn-queue.d.ts +20 -0
  109. package/dist/zukhruf/runtime/conversation-status/status-publishing-turn-queue.d.ts.map +1 -0
  110. package/dist/zukhruf/runtime/plugin/agent-skills.d.ts +22 -0
  111. package/dist/zukhruf/runtime/plugin/agent-skills.d.ts.map +1 -0
  112. package/dist/zukhruf/runtime/plugin/plugin-agents.d.ts +14 -0
  113. package/dist/zukhruf/runtime/plugin/plugin-agents.d.ts.map +1 -0
  114. package/dist/zukhruf/runtime/plugin/plugin-bindings.d.ts +8 -0
  115. package/dist/zukhruf/runtime/plugin/plugin-bindings.d.ts.map +1 -0
  116. package/dist/zukhruf/runtime/plugin/plugin-context-composition.d.ts +7 -0
  117. package/dist/zukhruf/runtime/plugin/plugin-context-composition.d.ts.map +1 -0
  118. package/dist/zukhruf/runtime/plugin/plugin-manager.d.ts +38 -0
  119. package/dist/zukhruf/runtime/plugin/plugin-manager.d.ts.map +1 -0
  120. package/dist/zukhruf/runtime/plugin/plugin-tool-composition.d.ts +10 -0
  121. package/dist/zukhruf/runtime/plugin/plugin-tool-composition.d.ts.map +1 -0
  122. package/dist/zukhruf/tool.d.ts +5 -1
  123. package/dist/zukhruf/tool.d.ts.map +1 -1
  124. package/package.json +74 -6
  125. package/dist/zukhruf/multi-agent-v2-config.d.ts.map +0 -1
  126. package/dist/zukhruf/runtime/agent-skills.d.ts +0 -9
  127. package/dist/zukhruf/runtime/agent-skills.d.ts.map +0 -1
  128. package/dist/zukhruf/runtime/approval-job-id.d.ts +0 -3
  129. package/dist/zukhruf/runtime/approval-job-id.d.ts.map +0 -1
@@ -0,0 +1,1873 @@
1
+ // packages/experimental/src/zukhruf/plugins/schedules/index.ts
2
+ import { isToolUIPart as isToolUIPart2 } from "ai";
3
+
4
+ // packages/experimental/src/zukhruf/runtime/agent-runtime.ts
5
+ import {
6
+ ContextEngine as ContextEngine5
7
+ } from "@deepagents/context";
8
+
9
+ // packages/experimental/src/zukhruf/control-plane/agent-control-plane.ts
10
+ import { v5 as uuidv54 } from "uuid";
11
+
12
+ // packages/experimental/src/zukhruf/control-plane/agent-directory.ts
13
+ import { v5 as uuidv5 } from "uuid";
14
+
15
+ // packages/experimental/src/zukhruf/control-plane/agent-history-forker.ts
16
+ import { validateUIMessages } from "ai";
17
+ import { v5 as uuidv52 } from "uuid";
18
+ import {
19
+ isSyntheticReminderMessage
20
+ } from "@deepagents/context";
21
+
22
+ // packages/experimental/src/zukhruf/control-plane/agent-status-projector.ts
23
+ import { isTextUIPart } from "ai";
24
+ import { z } from "zod";
25
+ import {
26
+ ContextEngine
27
+ } from "@deepagents/context";
28
+ var listedAgentStatusSchema = z.union([
29
+ z.enum(["pending_init", "running", "interrupted", "shutdown", "not_found"]),
30
+ z.object({ completed: z.string().nullable() }).strict(),
31
+ z.object({ errored: z.string() }).strict()
32
+ ]);
33
+ var listedAgentSchema = z.object({
34
+ agent_name: z.string(),
35
+ agent_status: listedAgentStatusSchema
36
+ }).strict();
37
+
38
+ // packages/experimental/src/zukhruf/control-plane/agent-turn-id.ts
39
+ import { v5 as uuidv53 } from "uuid";
40
+
41
+ // packages/experimental/src/zukhruf/runtime/agent-turn-executor.ts
42
+ import { experimental_codeModeTool } from "@ai-sdk/code-mode";
43
+ import {
44
+ jsonSchema,
45
+ tool
46
+ } from "ai";
47
+ import {
48
+ ContextEngine as ContextEngine2,
49
+ agent,
50
+ assistant,
51
+ chat,
52
+ role,
53
+ user
54
+ } from "@deepagents/context";
55
+ import { elementsSchema } from "@deepagents/elements";
56
+ import {
57
+ elementsFragment,
58
+ elementsStreamTransform
59
+ } from "@deepagents/elements/context";
60
+
61
+ // packages/experimental/src/zukhruf/runtime/compaction.ts
62
+ import {
63
+ asSchema,
64
+ modelMessageSchema as modelMessageSchema2
65
+ } from "ai";
66
+ import { z as z2 } from "zod";
67
+
68
+ // packages/compaction/dist/index.js
69
+ import {
70
+ generateText,
71
+ modelMessageSchema
72
+ } from "ai";
73
+
74
+ // packages/experimental/src/zukhruf/runtime/compaction.ts
75
+ var checkpointSchema = z2.object({
76
+ sourceCount: z2.number().int().positive(),
77
+ sourceHash: z2.string(),
78
+ replacement: z2.array(z2.unknown()).transform(
79
+ (messages) => messages.map((message) => modelMessageSchema2.parse(message))
80
+ )
81
+ });
82
+ var cacheObservationSchema = z2.object({
83
+ scope: z2.string(),
84
+ prefixLength: z2.number().int().nonnegative(),
85
+ prefixHash: z2.string(),
86
+ startedAt: z2.number().int().nonnegative(),
87
+ retentionMs: z2.number().int().positive().optional()
88
+ });
89
+ var inputUsageSchema = cacheObservationSchema.pick({ scope: true, prefixLength: true, prefixHash: true }).extend({ inputTokens: z2.number().int().nonnegative() });
90
+
91
+ // packages/experimental/src/zukhruf/runtime/plugin/agent-skills.ts
92
+ import {
93
+ parseFrontmatter,
94
+ skills
95
+ } from "@deepagents/context";
96
+
97
+ // packages/experimental/src/zukhruf/runtime/approval-controller.ts
98
+ import {
99
+ getToolName,
100
+ isToolUIPart
101
+ } from "ai";
102
+ import {
103
+ ContextEngine as ContextEngine3,
104
+ assistant as assistant2
105
+ } from "@deepagents/context";
106
+
107
+ // packages/experimental/src/zukhruf/runtime/conversation-status/projector.ts
108
+ import {
109
+ ContextEngine as ContextEngine4
110
+ } from "@deepagents/context";
111
+
112
+ // packages/experimental/src/zukhruf/runtime/conversation-status/child-progress.ts
113
+ import { z as z3 } from "zod";
114
+ var childActivitySchema = z3.object({
115
+ id: z3.string(),
116
+ type: z3.enum(["spawn", "message", "followup", "interrupt", "completion"]),
117
+ at: z3.number(),
118
+ actorPath: z3.string(),
119
+ targetPath: z3.string(),
120
+ streamId: z3.string(),
121
+ outcome: z3.enum(["completed", "failed", "cancelled"]).optional()
122
+ });
123
+ var childActivitiesSchema = z3.partialRecord(
124
+ childActivitySchema.shape.type,
125
+ childActivitySchema
126
+ );
127
+ var childActivityMetadataSchema = z3.looseObject({
128
+ childActivities: childActivitiesSchema.default({})
129
+ });
130
+
131
+ // packages/experimental/src/zukhruf/collaboration/interrupt-agent.ts
132
+ import { tool as tool2 } from "ai";
133
+ import { z as z4 } from "zod";
134
+ var interruptAgentInputSchema = z4.object({
135
+ target: z4.string().trim().min(1).describe(
136
+ "The canonical /root/... path, or a descendant-relative target name."
137
+ )
138
+ });
139
+ var interruptAgentOutputSchema = z4.object({ previous_status: listedAgentStatusSchema }).strict();
140
+ var interruptAgentTool = tool2({
141
+ description: "Interrupt an agent's current turn, if any, and return its previous status. The agent remains available for messages and follow-up tasks.",
142
+ inputSchema: interruptAgentInputSchema,
143
+ outputSchema: interruptAgentOutputSchema,
144
+ execute: async (input, { context }) => context.controlPlane.interruptAgent(context.actor, input)
145
+ });
146
+
147
+ // packages/experimental/src/zukhruf/collaboration/list-agents.ts
148
+ import { tool as tool3 } from "ai";
149
+ import { z as z5 } from "zod";
150
+ var listAgentsInputSchema = z5.object({
151
+ path_prefix: z5.string().trim().min(1).describe(
152
+ "Task-path prefix without a trailing slash. Omit to list the whole tree."
153
+ ).optional()
154
+ });
155
+ var listAgentsOutputSchema = z5.object({ agents: z5.array(listedAgentSchema) }).strict();
156
+ var listAgentsTool = tool3({
157
+ description: "List live agents in the current root thread tree. Optionally filter by task-path prefix.",
158
+ inputSchema: listAgentsInputSchema,
159
+ outputSchema: listAgentsOutputSchema,
160
+ execute: async ({ path_prefix }, { context }) => context.controlPlane.listAgents(context.actor, path_prefix)
161
+ });
162
+
163
+ // packages/experimental/src/zukhruf/collaboration/message-tools.ts
164
+ import { tool as tool4 } from "ai";
165
+ import { z as z6 } from "zod";
166
+ var agentMessageInputSchema = z6.object({
167
+ target: z6.string().trim().min(1).describe(
168
+ "The canonical /root/... path, or a descendant-relative target name."
169
+ ),
170
+ message: z6.string().trim().min(1).describe("The message or follow-up task.")
171
+ });
172
+ var sendMessageTool = tool4({
173
+ description: "Queue a message for another agent. Address siblings with their canonical /root/... path.",
174
+ inputSchema: agentMessageInputSchema,
175
+ execute: async (input, { context }) => {
176
+ await context.controlPlane.sendMessage(context.actor, input);
177
+ return "";
178
+ }
179
+ });
180
+ var followupTaskTool = tool4({
181
+ description: "Send a follow-up task to an existing non-root agent and wake its thread.",
182
+ inputSchema: agentMessageInputSchema,
183
+ execute: async (input, { context }) => {
184
+ await context.controlPlane.followupTask(context.actor, input);
185
+ return "";
186
+ }
187
+ });
188
+
189
+ // packages/experimental/src/zukhruf/collaboration/spawn-agent.ts
190
+ import { tool as tool5 } from "ai";
191
+ import { z as z7 } from "zod";
192
+
193
+ // packages/experimental/src/zukhruf/control-plane/fork-turns.ts
194
+ var forkTurnsError = "fork_turns must be `none`, `all`, or a positive integer string";
195
+ function parseForkTurns(value) {
196
+ const normalized = value.trim().toLowerCase();
197
+ if (normalized === "none" || normalized === "all") return normalized;
198
+ if (!/^\d+$/.test(normalized)) return void 0;
199
+ const turns = Number(normalized);
200
+ return Number.isSafeInteger(turns) && turns > 0 ? turns : void 0;
201
+ }
202
+
203
+ // packages/experimental/src/zukhruf/collaboration/spawn-agent.ts
204
+ var spawnAgentInputSchema = z7.object({
205
+ agent_type: z7.string().trim().min(1).describe("The name of one available subagent declaration."),
206
+ task_name: z7.string().trim().min(1).refine(
207
+ (value) => value !== "." && value !== ".." && !value.includes("/"),
208
+ "task_name must be one non-empty path segment"
209
+ ).describe("One path segment naming this independent agent task."),
210
+ message: z7.string().refine((value) => value.trim().length > 0, "message cannot be empty").describe("The initial task for the spawned agent."),
211
+ fork_turns: z7.string().trim().refine((value) => parseForkTurns(value) !== void 0, forkTurnsError).describe(
212
+ "Required number of parent turns to fork. Use `none`, `all`, or a positive integer string such as `3`."
213
+ )
214
+ });
215
+ var spawnAgentOutputSchema = z7.object({ task_name: z7.string() }).strict();
216
+
217
+ // packages/experimental/src/zukhruf/collaboration/wait-agent.ts
218
+ import { tool as tool6 } from "ai";
219
+ import { z as z8 } from "zod";
220
+ var waitAgentOutputSchema = z8.object({ message: z8.string(), timed_out: z8.boolean() }).strict();
221
+
222
+ // packages/experimental/src/zukhruf/runtime/plugin/plugin-agents.ts
223
+ import { parseFrontmatter as parseFrontmatter2, role as role2 } from "@deepagents/context";
224
+
225
+ // packages/experimental/src/zukhruf/runtime/agent-runtime.ts
226
+ var AgentPluginCapability = class {
227
+ name;
228
+ constructor(name) {
229
+ this.name = name;
230
+ }
231
+ bind(value) {
232
+ return { capability: this, value };
233
+ }
234
+ };
235
+
236
+ // packages/experimental/src/zukhruf/plugins/schedules/scheduled-tasks.ts
237
+ import { CronExpressionParser } from "cron-parser";
238
+ import { randomUUID } from "node:crypto";
239
+ import { isDeepStrictEqual } from "node:util";
240
+ import rrulePackage from "rrule";
241
+
242
+ // packages/experimental/src/zukhruf/queue/pg-boss-notifications.ts
243
+ import { EventEmitter, on } from "node:events";
244
+ async function pgBossNotifications(boss, channel, parse, signal) {
245
+ signal.throwIfAborted();
246
+ const db = boss.getDb();
247
+ const listen = db.listen?.bind(db);
248
+ if (!listen) {
249
+ throw new Error("pg-boss database does not support LISTEN");
250
+ }
251
+ const emitter = new EventEmitter();
252
+ const notifications = on(emitter, "notification", { signal });
253
+ let ready = false;
254
+ const handle = await listen(
255
+ channel,
256
+ (payload) => {
257
+ const value = parse(payload);
258
+ if (value !== void 0) {
259
+ emitter.emit("notification", { type: "change", value });
260
+ }
261
+ },
262
+ () => {
263
+ if (ready) emitter.emit("notification", { type: "reset" });
264
+ }
265
+ );
266
+ ready = true;
267
+ if (signal.aborted) {
268
+ await handle.close();
269
+ signal.throwIfAborted();
270
+ }
271
+ return {
272
+ async *[Symbol.asyncIterator]() {
273
+ try {
274
+ for await (const [notification] of notifications) {
275
+ yield notification;
276
+ }
277
+ } finally {
278
+ await handle.close();
279
+ }
280
+ }
281
+ };
282
+ }
283
+
284
+ // packages/experimental/src/zukhruf/plugins/schedules/scheduled-tasks.ts
285
+ var { rrulestr } = rrulePackage;
286
+ var SCHEDULE_CHANGES_CHANNEL = "zukhruf_schedule_changes";
287
+ var DDL = `
288
+ CREATE TABLE IF NOT EXISTS zukhruf_scheduled_tasks (
289
+ id uuid PRIMARY KEY,
290
+ owner_id text NOT NULL,
291
+ idempotency_key text NOT NULL,
292
+ name text NOT NULL,
293
+ prompt text NOT NULL,
294
+ recurrence text NOT NULL,
295
+ timezone text NOT NULL,
296
+ execution_config jsonb NOT NULL,
297
+ status text NOT NULL CHECK (status IN ('active', 'paused', 'completed', 'archived')),
298
+ generation integer NOT NULL,
299
+ next_run_at bigint,
300
+ next_wake_id uuid,
301
+ created_at bigint NOT NULL,
302
+ updated_at bigint NOT NULL,
303
+ archived_at bigint,
304
+ UNIQUE (owner_id, idempotency_key),
305
+ CHECK ((next_run_at IS NULL) = (next_wake_id IS NULL))
306
+ );
307
+
308
+ CREATE INDEX IF NOT EXISTS zukhruf_scheduled_tasks_owner
309
+ ON zukhruf_scheduled_tasks (owner_id, created_at, id);
310
+
311
+ CREATE TABLE IF NOT EXISTS zukhruf_scheduled_runs (
312
+ id uuid PRIMARY KEY,
313
+ task_id uuid NOT NULL REFERENCES zukhruf_scheduled_tasks(id) ON DELETE CASCADE,
314
+ owner_id text NOT NULL,
315
+ trigger text NOT NULL CHECK (trigger IN ('scheduled', 'manual')),
316
+ idempotency_key text,
317
+ occurrence_at bigint NOT NULL,
318
+ prompt text NOT NULL,
319
+ execution_config jsonb NOT NULL,
320
+ status text NOT NULL CHECK (status IN ('dispatching', 'running', 'completed', 'failed', 'cancelled')),
321
+ review_status text CHECK (review_status IN ('pending_review', 'reviewed', 'archived')),
322
+ external_execution_id text,
323
+ dispatch_job_id uuid NOT NULL,
324
+ reconciliation_job_id uuid,
325
+ next_check_at bigint,
326
+ started_at bigint,
327
+ finished_at bigint,
328
+ title text,
329
+ summary text,
330
+ error text,
331
+ created_at bigint NOT NULL,
332
+ updated_at bigint NOT NULL
333
+ );
334
+
335
+ CREATE UNIQUE INDEX IF NOT EXISTS zukhruf_scheduled_runs_occurrence
336
+ ON zukhruf_scheduled_runs (task_id, occurrence_at)
337
+ WHERE trigger = 'scheduled';
338
+
339
+ CREATE UNIQUE INDEX IF NOT EXISTS zukhruf_scheduled_runs_manual
340
+ ON zukhruf_scheduled_runs (task_id, idempotency_key)
341
+ WHERE trigger = 'manual';
342
+
343
+ CREATE INDEX IF NOT EXISTS zukhruf_scheduled_runs_task
344
+ ON zukhruf_scheduled_runs (owner_id, task_id, occurrence_at DESC, id);
345
+
346
+ CREATE INDEX IF NOT EXISTS zukhruf_scheduled_runs_pending_review
347
+ ON zukhruf_scheduled_runs (owner_id, finished_at DESC, id)
348
+ WHERE review_status = 'pending_review';
349
+
350
+ CREATE OR REPLACE FUNCTION zukhruf_publish_schedule_change()
351
+ RETURNS trigger AS $$
352
+ BEGIN
353
+ IF TG_TABLE_NAME = 'zukhruf_scheduled_tasks' THEN
354
+ PERFORM pg_notify(
355
+ '${SCHEDULE_CHANGES_CHANNEL}',
356
+ json_build_object(
357
+ 'resource', 'schedule-task',
358
+ 'ownerId', COALESCE(NEW.owner_id, OLD.owner_id),
359
+ 'id', COALESCE(NEW.id, OLD.id)
360
+ )::text
361
+ );
362
+ ELSE
363
+ PERFORM pg_notify(
364
+ '${SCHEDULE_CHANGES_CHANNEL}',
365
+ json_build_object(
366
+ 'resource', 'schedule-run',
367
+ 'ownerId', COALESCE(NEW.owner_id, OLD.owner_id),
368
+ 'id', COALESCE(NEW.id, OLD.id),
369
+ 'taskId', COALESCE(NEW.task_id, OLD.task_id)
370
+ )::text
371
+ );
372
+ END IF;
373
+ IF TG_OP = 'DELETE' THEN RETURN OLD; END IF;
374
+ RETURN NEW;
375
+ END;
376
+ $$ LANGUAGE plpgsql;
377
+
378
+ CREATE OR REPLACE TRIGGER zukhruf_scheduled_tasks_changed
379
+ AFTER INSERT OR UPDATE OR DELETE ON zukhruf_scheduled_tasks
380
+ FOR EACH ROW EXECUTE FUNCTION zukhruf_publish_schedule_change();
381
+
382
+ CREATE OR REPLACE TRIGGER zukhruf_scheduled_runs_changed
383
+ AFTER INSERT OR UPDATE OR DELETE ON zukhruf_scheduled_runs
384
+ FOR EACH ROW EXECUTE FUNCTION zukhruf_publish_schedule_change();
385
+ `;
386
+ var ScheduledTasksError = class extends Error {
387
+ name = "ScheduledTasksError";
388
+ code;
389
+ resource;
390
+ constructor(code, resource, message, options) {
391
+ super(message, options);
392
+ this.code = code;
393
+ this.resource = resource;
394
+ }
395
+ };
396
+ var ScheduledTasks = class {
397
+ #boss;
398
+ #database;
399
+ #executor;
400
+ #queue;
401
+ #queueOptions;
402
+ #reconciliationIntervalMs;
403
+ #transaction;
404
+ constructor(options) {
405
+ this.#queue = required(options.queue, "Scheduled Tasks queue");
406
+ if (!Number.isInteger(options.reconciliationIntervalMs) || options.reconciliationIntervalMs < 1) {
407
+ throw new Error(
408
+ "Scheduled Tasks reconciliation interval must be a positive integer"
409
+ );
410
+ }
411
+ this.#boss = options.boss;
412
+ this.#database = options.boss.getDb();
413
+ this.#executor = options.executor;
414
+ this.#queueOptions = options.queueOptions;
415
+ this.#reconciliationIntervalMs = options.reconciliationIntervalMs;
416
+ this.#transaction = options.transaction;
417
+ }
418
+ async initialize() {
419
+ await this.#database.executeSql(DDL);
420
+ if (this.#queueOptions) {
421
+ await this.#boss.createQueue(this.#queue, this.#queueOptions);
422
+ } else {
423
+ await this.#boss.createQueue(this.#queue);
424
+ }
425
+ await this.#boss.findJobs(this.#queue, { id: randomUUID() });
426
+ }
427
+ async subscribeChanges(ownerId, signal) {
428
+ const owner = required(ownerId, "Scheduled Task owner");
429
+ const notifications = await pgBossNotifications(
430
+ this.#boss,
431
+ SCHEDULE_CHANGES_CHANNEL,
432
+ parseScheduledChange,
433
+ signal
434
+ );
435
+ return {
436
+ async *[Symbol.asyncIterator]() {
437
+ for await (const notification of notifications) {
438
+ if (notification.type === "reset") {
439
+ yield notification;
440
+ } else if (notification.value.ownerId === owner) {
441
+ yield notification.value.change;
442
+ }
443
+ }
444
+ }
445
+ };
446
+ }
447
+ async create(ownerId, input) {
448
+ const owner = required(ownerId, "Scheduled Task owner");
449
+ const normalized = normalizeCreate(input);
450
+ const nextRunAt = nextOccurrence(
451
+ normalized.recurrence,
452
+ normalized.timezone,
453
+ Date.now()
454
+ );
455
+ if (nextRunAt === null) {
456
+ throw new ScheduledTasksError(
457
+ "invalid-input",
458
+ "task",
459
+ "Scheduled Task recurrence has no future occurrence"
460
+ );
461
+ }
462
+ return this.#transaction(async (database) => {
463
+ const existing = await this.#taskByKey(
464
+ database,
465
+ owner,
466
+ normalized.idempotencyKey
467
+ );
468
+ if (existing) {
469
+ assertSameTask(existing, normalized);
470
+ return existing;
471
+ }
472
+ const id = randomUUID();
473
+ const generation = 1;
474
+ const now = Date.now();
475
+ const wakeId = await this.#sendAt(
476
+ database,
477
+ {
478
+ kind: "occurrence",
479
+ ownerId: owner,
480
+ taskId: id,
481
+ occurrenceAt: nextRunAt,
482
+ generation
483
+ },
484
+ nextRunAt
485
+ );
486
+ const { rows } = await database.executeSql(
487
+ `INSERT INTO zukhruf_scheduled_tasks (
488
+ id, owner_id, idempotency_key, name, prompt, recurrence, timezone,
489
+ execution_config, status, generation, next_run_at, next_wake_id,
490
+ created_at, updated_at
491
+ ) VALUES (
492
+ $1, $2, $3, $4, $5, $6, $7, $8::jsonb,
493
+ 'active', $9, $10, $11, $12, $12
494
+ )
495
+ ON CONFLICT (owner_id, idempotency_key) DO NOTHING
496
+ RETURNING *`,
497
+ [
498
+ id,
499
+ owner,
500
+ normalized.idempotencyKey,
501
+ normalized.name,
502
+ normalized.prompt,
503
+ normalized.recurrence,
504
+ normalized.timezone,
505
+ normalized.executionConfigJson,
506
+ generation,
507
+ nextRunAt,
508
+ wakeId,
509
+ now
510
+ ]
511
+ );
512
+ const inserted = rows[0];
513
+ if (inserted) return toTask(inserted);
514
+ await this.#cancelJob(database, wakeId);
515
+ const concurrent = await this.#taskByKey(
516
+ database,
517
+ owner,
518
+ normalized.idempotencyKey
519
+ );
520
+ if (!concurrent) throw new Error("Scheduled Task create lost its row");
521
+ assertSameTask(concurrent, normalized);
522
+ return concurrent;
523
+ });
524
+ }
525
+ async get(ownerId, taskId) {
526
+ return this.#requiredTask(this.#database, ownerId, taskId, false);
527
+ }
528
+ async list(ownerId) {
529
+ const { rows } = await this.#database.executeSql(
530
+ `SELECT * FROM zukhruf_scheduled_tasks
531
+ WHERE owner_id = $1
532
+ ORDER BY created_at, id`,
533
+ [required(ownerId, "Scheduled Task owner")]
534
+ );
535
+ return rows.map(toTask);
536
+ }
537
+ async listRuns(ownerId, taskId) {
538
+ const { rows } = await this.#database.executeSql(
539
+ `SELECT * FROM zukhruf_scheduled_runs
540
+ WHERE owner_id = $1 AND task_id = $2
541
+ ORDER BY occurrence_at DESC, id`,
542
+ [
543
+ required(ownerId, "Scheduled Task owner"),
544
+ required(taskId, "Scheduled Task id")
545
+ ]
546
+ );
547
+ return rows.map(toRun);
548
+ }
549
+ async getRun(ownerId, runId) {
550
+ return this.#requiredRun(this.#database, ownerId, runId, false);
551
+ }
552
+ /**
553
+ * Owner-wide review queue. `review_status` is only written when a run reaches
554
+ * a terminal state, so pending runs are exactly the unreviewed terminal ones,
555
+ * including runs whose task has since been archived.
556
+ */
557
+ async listPendingReview(ownerId) {
558
+ const { rows } = await this.#database.executeSql(
559
+ `SELECT * FROM zukhruf_scheduled_runs
560
+ WHERE owner_id = $1 AND review_status = 'pending_review'
561
+ ORDER BY finished_at DESC, id`,
562
+ [required(ownerId, "Scheduled Task owner")]
563
+ );
564
+ return rows.map(toRun);
565
+ }
566
+ async pause(ownerId, taskId) {
567
+ return this.#transaction(async (database) => {
568
+ const task = await this.#requiredTask(database, ownerId, taskId, true);
569
+ if (task.status === "paused") return task;
570
+ if (task.status !== "active") {
571
+ throw new ScheduledTasksError(
572
+ "conflict",
573
+ "task",
574
+ `Scheduled Task "${task.id}" is ${task.status}`
575
+ );
576
+ }
577
+ const row = await this.#taskRow(database, task.id, task.ownerId, true);
578
+ if (!row) throw new Error(`Scheduled Task "${task.id}" was not found`);
579
+ if (row.next_wake_id) await this.#cancelJob(database, row.next_wake_id);
580
+ const now = Date.now();
581
+ const { rows } = await database.executeSql(
582
+ `UPDATE zukhruf_scheduled_tasks
583
+ SET status = 'paused', generation = generation + 1,
584
+ next_run_at = NULL, next_wake_id = NULL, updated_at = $1
585
+ WHERE id = $2 AND owner_id = $3
586
+ RETURNING *`,
587
+ [now, task.id, task.ownerId]
588
+ );
589
+ return toTask(requiredRow(rows, "pause"));
590
+ });
591
+ }
592
+ async resume(ownerId, taskId) {
593
+ return this.#transaction(async (database) => {
594
+ const task = await this.#requiredTask(database, ownerId, taskId, true);
595
+ if (task.status === "active") return task;
596
+ if (task.status === "archived") {
597
+ throw new ScheduledTasksError(
598
+ "conflict",
599
+ "task",
600
+ `Scheduled Task "${task.id}" is archived`
601
+ );
602
+ }
603
+ const nextRunAt = nextOccurrence(
604
+ task.recurrence,
605
+ task.timezone,
606
+ Date.now()
607
+ );
608
+ if (nextRunAt === null) {
609
+ throw new ScheduledTasksError(
610
+ "conflict",
611
+ "task",
612
+ "Scheduled Task recurrence has no future occurrence"
613
+ );
614
+ }
615
+ const generation = task.generation + 1;
616
+ const wakeId = await this.#sendAt(
617
+ database,
618
+ {
619
+ kind: "occurrence",
620
+ ownerId: task.ownerId,
621
+ taskId: task.id,
622
+ occurrenceAt: nextRunAt,
623
+ generation
624
+ },
625
+ nextRunAt
626
+ );
627
+ const { rows } = await database.executeSql(
628
+ `UPDATE zukhruf_scheduled_tasks
629
+ SET status = 'active', generation = $1, next_run_at = $2,
630
+ next_wake_id = $3, updated_at = $4
631
+ WHERE id = $5 AND owner_id = $6
632
+ RETURNING *`,
633
+ [generation, nextRunAt, wakeId, Date.now(), task.id, task.ownerId]
634
+ );
635
+ return toTask(requiredRow(rows, "resume"));
636
+ });
637
+ }
638
+ async update(ownerId, taskId, input) {
639
+ if (Object.values(input).every((value) => value === void 0)) {
640
+ throw new ScheduledTasksError(
641
+ "invalid-input",
642
+ "task",
643
+ "Scheduled Task update cannot be empty"
644
+ );
645
+ }
646
+ return this.#transaction(async (database) => {
647
+ const task = await this.#requiredTask(database, ownerId, taskId, true);
648
+ if (task.status === "archived") {
649
+ throw new ScheduledTasksError(
650
+ "conflict",
651
+ "task",
652
+ `Scheduled Task "${task.id}" is archived`
653
+ );
654
+ }
655
+ const row = await this.#taskRow(database, task.id, task.ownerId, true);
656
+ if (!row) throw new Error(`Scheduled Task "${task.id}" was not found`);
657
+ const name = input.name === void 0 ? task.name : required(input.name, "Scheduled Task name");
658
+ const prompt = input.prompt === void 0 ? task.prompt : required(input.prompt, "Scheduled Task prompt");
659
+ const timezone = input.timezone === void 0 ? task.timezone : validateTimezone(input.timezone);
660
+ const recurrence = input.recurrence === void 0 ? task.recurrence : required(input.recurrence, "Scheduled Task recurrence");
661
+ const executionConfig = input.executionConfig === void 0 ? task.executionConfig : input.executionConfig;
662
+ const executionConfigJson = serializeExecutionConfig(executionConfig);
663
+ const generation = task.generation + 1;
664
+ const candidate = nextOccurrence(recurrence, timezone, Date.now());
665
+ let status = task.status;
666
+ let nextRunAt = null;
667
+ let wakeId = null;
668
+ if (task.status === "active") {
669
+ status = candidate === null ? "completed" : "active";
670
+ nextRunAt = candidate;
671
+ if (candidate !== null) {
672
+ wakeId = await this.#sendAt(
673
+ database,
674
+ {
675
+ kind: "occurrence",
676
+ ownerId: task.ownerId,
677
+ taskId: task.id,
678
+ occurrenceAt: candidate,
679
+ generation
680
+ },
681
+ candidate
682
+ );
683
+ }
684
+ }
685
+ if (row.next_wake_id) await this.#cancelJob(database, row.next_wake_id);
686
+ const { rows } = await database.executeSql(
687
+ `UPDATE zukhruf_scheduled_tasks
688
+ SET name = $1, prompt = $2, recurrence = $3, timezone = $4,
689
+ execution_config = $5::jsonb, status = $6, generation = $7,
690
+ next_run_at = $8, next_wake_id = $9, updated_at = $10
691
+ WHERE id = $11 AND owner_id = $12
692
+ RETURNING *`,
693
+ [
694
+ name,
695
+ prompt,
696
+ recurrence,
697
+ timezone,
698
+ executionConfigJson,
699
+ status,
700
+ generation,
701
+ nextRunAt,
702
+ wakeId,
703
+ Date.now(),
704
+ task.id,
705
+ task.ownerId
706
+ ]
707
+ );
708
+ return toTask(requiredRow(rows, "update"));
709
+ });
710
+ }
711
+ async runNow(ownerId, taskId, idempotencyKey) {
712
+ const key = required(idempotencyKey, "Scheduled Run idempotency key");
713
+ return this.#transaction(async (database) => {
714
+ const task = await this.#requiredTask(database, ownerId, taskId, true);
715
+ if (task.status === "archived") {
716
+ throw new ScheduledTasksError(
717
+ "conflict",
718
+ "task",
719
+ `Scheduled Task "${task.id}" is archived`
720
+ );
721
+ }
722
+ const existing = await this.#manualRun(database, task.id, key);
723
+ if (existing) return existing;
724
+ const now = Date.now();
725
+ const runId = randomUUID();
726
+ const dispatchJobId = await this.#sendNow(database, {
727
+ kind: "dispatch",
728
+ ownerId: task.ownerId,
729
+ runId
730
+ });
731
+ const { rows } = await database.executeSql(
732
+ `INSERT INTO zukhruf_scheduled_runs (
733
+ id, task_id, owner_id, trigger, idempotency_key, occurrence_at,
734
+ prompt, execution_config, status, dispatch_job_id, created_at, updated_at
735
+ ) VALUES (
736
+ $1, $2, $3, 'manual', $4, $5, $6, $7::jsonb,
737
+ 'dispatching', $8, $5, $5
738
+ )
739
+ ON CONFLICT (task_id, idempotency_key) WHERE trigger = 'manual'
740
+ DO NOTHING
741
+ RETURNING *`,
742
+ [
743
+ runId,
744
+ task.id,
745
+ task.ownerId,
746
+ key,
747
+ now,
748
+ task.prompt,
749
+ serializeExecutionConfig(task.executionConfig),
750
+ dispatchJobId
751
+ ]
752
+ );
753
+ const inserted = rows[0];
754
+ if (inserted) return toRun(inserted);
755
+ await this.#cancelJob(database, dispatchJobId);
756
+ const concurrent = await this.#manualRun(database, task.id, key);
757
+ if (!concurrent) throw new Error("Scheduled Run create lost its row");
758
+ return concurrent;
759
+ });
760
+ }
761
+ async archive(ownerId, taskId) {
762
+ return this.#transaction(async (database) => {
763
+ const task = await this.#requiredTask(database, ownerId, taskId, true);
764
+ if (task.status === "archived") return task;
765
+ const row = await this.#taskRow(database, task.id, task.ownerId, true);
766
+ if (!row) throw new Error(`Scheduled Task "${task.id}" was not found`);
767
+ if (row.next_wake_id) await this.#cancelJob(database, row.next_wake_id);
768
+ const now = Date.now();
769
+ const { rows } = await database.executeSql(
770
+ `UPDATE zukhruf_scheduled_tasks
771
+ SET status = 'archived', generation = generation + 1,
772
+ next_run_at = NULL, next_wake_id = NULL,
773
+ archived_at = $1, updated_at = $1
774
+ WHERE id = $2 AND owner_id = $3
775
+ RETURNING *`,
776
+ [now, task.id, task.ownerId]
777
+ );
778
+ return toTask(requiredRow(rows, "archive"));
779
+ });
780
+ }
781
+ async purge(ownerId, taskId) {
782
+ await this.#transaction(async (database) => {
783
+ const task = await this.#requiredTask(database, ownerId, taskId, true);
784
+ if (task.status !== "archived") {
785
+ throw new ScheduledTasksError(
786
+ "conflict",
787
+ "task",
788
+ `Scheduled Task "${task.id}" must be archived before purge`
789
+ );
790
+ }
791
+ const { rows } = await database.executeSql(
792
+ `SELECT dispatch_job_id, reconciliation_job_id, status
793
+ FROM zukhruf_scheduled_runs
794
+ WHERE task_id = $1 AND owner_id = $2`,
795
+ [task.id, task.ownerId]
796
+ );
797
+ const runs = rows;
798
+ if (runs.some(
799
+ ({ status }) => status === "dispatching" || status === "running"
800
+ )) {
801
+ throw new ScheduledTasksError(
802
+ "conflict",
803
+ "task",
804
+ `Scheduled Task "${task.id}" has active runs`
805
+ );
806
+ }
807
+ const jobs = runs.flatMap(
808
+ ({ dispatch_job_id, reconciliation_job_id }) => reconciliation_job_id ? [dispatch_job_id, reconciliation_job_id] : [dispatch_job_id]
809
+ );
810
+ if (jobs.length > 0)
811
+ await this.#boss.cancel(this.#queue, jobs, { db: database });
812
+ await database.executeSql(
813
+ "DELETE FROM zukhruf_scheduled_tasks WHERE id = $1 AND owner_id = $2",
814
+ [task.id, task.ownerId]
815
+ );
816
+ });
817
+ }
818
+ async cancelRun(ownerId, runId) {
819
+ const run = await this.#requiredRun(this.#database, ownerId, runId, false);
820
+ if (isTerminal(run.status)) return run;
821
+ if (run.status === "dispatching") {
822
+ return this.#transaction(async (database) => {
823
+ const current = await this.#requiredRun(database, ownerId, runId, true);
824
+ if (current.status !== "dispatching") return current;
825
+ const row = await this.#runRow(
826
+ database,
827
+ current.id,
828
+ current.ownerId,
829
+ true
830
+ );
831
+ if (!row)
832
+ throw new Error(`Scheduled Run "${current.id}" was not found`);
833
+ await this.#cancelJob(database, row.dispatch_job_id);
834
+ return this.#finishCancelled(database, current);
835
+ });
836
+ }
837
+ if (!run.externalExecutionId) {
838
+ throw new ScheduledTasksError(
839
+ "conflict",
840
+ "run",
841
+ `Scheduled Run "${run.id}" has no external execution`
842
+ );
843
+ }
844
+ await this.#executor.cancel({
845
+ runId: run.id,
846
+ ownerId: run.ownerId,
847
+ executionId: run.externalExecutionId,
848
+ executionConfig: run.executionConfig
849
+ });
850
+ return this.#transaction(async (database) => {
851
+ const current = await this.#requiredRun(database, ownerId, runId, true);
852
+ if (current.status !== "running") return current;
853
+ const row = await this.#runRow(
854
+ database,
855
+ current.id,
856
+ current.ownerId,
857
+ true
858
+ );
859
+ if (!row) throw new Error(`Scheduled Run "${current.id}" was not found`);
860
+ if (row.reconciliation_job_id) {
861
+ await this.#cancelJob(database, row.reconciliation_job_id);
862
+ }
863
+ return this.#finishCancelled(database, current);
864
+ });
865
+ }
866
+ async markReviewed(ownerId, runId) {
867
+ return this.#setReviewStatus(ownerId, runId, "reviewed");
868
+ }
869
+ async archiveRun(ownerId, runId) {
870
+ return this.#setReviewStatus(ownerId, runId, "archived");
871
+ }
872
+ async work(options, waitForActive) {
873
+ const workOptions = { ...options, includeMetadata: true };
874
+ const workerId = await this.#boss.work(
875
+ this.#queue,
876
+ workOptions,
877
+ async (jobs) => {
878
+ await Promise.all(jobs.map((job) => this.#handle(job)));
879
+ }
880
+ );
881
+ return {
882
+ [Symbol.asyncDispose]: () => this.#boss.offWork(this.#queue, { id: workerId, wait: waitForActive })
883
+ };
884
+ }
885
+ async #handle(job) {
886
+ const data = validateJob(job.data);
887
+ if (data.kind === "occurrence") {
888
+ await this.#materialize(job.id, data);
889
+ } else if (data.kind === "dispatch") {
890
+ await this.#dispatch(job.id, data);
891
+ } else {
892
+ await this.#reconcile(job, data);
893
+ }
894
+ }
895
+ async #materialize(jobId, job) {
896
+ await this.#transaction(async (database) => {
897
+ const row = await this.#taskRow(database, job.taskId, job.ownerId, true);
898
+ if (!row || row.status !== "active" || Number(row.generation) !== job.generation || toMillis(row.next_run_at) !== job.occurrenceAt || row.next_wake_id !== jobId) {
899
+ return;
900
+ }
901
+ const task = toTask(row);
902
+ const now = Date.now();
903
+ const runId = randomUUID();
904
+ const dispatchJobId = await this.#sendNow(database, {
905
+ kind: "dispatch",
906
+ ownerId: task.ownerId,
907
+ runId
908
+ });
909
+ const { rows } = await database.executeSql(
910
+ `INSERT INTO zukhruf_scheduled_runs (
911
+ id, task_id, owner_id, trigger, occurrence_at, prompt,
912
+ execution_config, status, dispatch_job_id, created_at, updated_at
913
+ ) VALUES (
914
+ $1, $2, $3, 'scheduled', $4, $5, $6::jsonb,
915
+ 'dispatching', $7, $8, $8
916
+ )
917
+ ON CONFLICT (task_id, occurrence_at) WHERE trigger = 'scheduled'
918
+ DO NOTHING
919
+ RETURNING id`,
920
+ [
921
+ runId,
922
+ task.id,
923
+ task.ownerId,
924
+ job.occurrenceAt,
925
+ task.prompt,
926
+ serializeExecutionConfig(task.executionConfig),
927
+ dispatchJobId,
928
+ now
929
+ ]
930
+ );
931
+ if (!rows[0]) await this.#cancelJob(database, dispatchJobId);
932
+ const nextRunAt = nextOccurrence(
933
+ task.recurrence,
934
+ task.timezone,
935
+ Math.max(job.occurrenceAt, now)
936
+ );
937
+ let nextWakeId = null;
938
+ if (nextRunAt !== null) {
939
+ nextWakeId = await this.#sendAt(
940
+ database,
941
+ {
942
+ kind: "occurrence",
943
+ ownerId: task.ownerId,
944
+ taskId: task.id,
945
+ occurrenceAt: nextRunAt,
946
+ generation: task.generation
947
+ },
948
+ nextRunAt
949
+ );
950
+ }
951
+ await database.executeSql(
952
+ `UPDATE zukhruf_scheduled_tasks
953
+ SET status = $1, next_run_at = $2, next_wake_id = $3, updated_at = $4
954
+ WHERE id = $5 AND owner_id = $6`,
955
+ [
956
+ nextRunAt === null ? "completed" : "active",
957
+ nextRunAt,
958
+ nextWakeId,
959
+ now,
960
+ task.id,
961
+ task.ownerId
962
+ ]
963
+ );
964
+ });
965
+ }
966
+ async #dispatch(jobId, job) {
967
+ const row = await this.#runRow(
968
+ this.#database,
969
+ job.runId,
970
+ job.ownerId,
971
+ false
972
+ );
973
+ if (!row || row.status !== "dispatching" || row.dispatch_job_id !== jobId) {
974
+ return;
975
+ }
976
+ const run = toRun(row);
977
+ let executionId;
978
+ try {
979
+ const launched = await this.#executor.launch({
980
+ runId: run.id,
981
+ taskId: run.taskId,
982
+ ownerId: run.ownerId,
983
+ trigger: run.trigger,
984
+ occurrenceAt: run.occurrenceAt,
985
+ prompt: run.prompt,
986
+ executionConfig: run.executionConfig
987
+ });
988
+ executionId = required(
989
+ launched.executionId,
990
+ "Scheduled Run external execution id"
991
+ );
992
+ } catch (error) {
993
+ await this.#transaction(async (database) => {
994
+ const current = await this.#runRow(database, run.id, run.ownerId, true);
995
+ if (!current || current.status !== "dispatching" || current.dispatch_job_id !== jobId) {
996
+ return;
997
+ }
998
+ const now = Date.now();
999
+ await database.executeSql(
1000
+ `UPDATE zukhruf_scheduled_runs
1001
+ SET status = 'failed', review_status = 'pending_review',
1002
+ finished_at = $1, error = $2, updated_at = $1
1003
+ WHERE id = $3 AND owner_id = $4`,
1004
+ [now, errorMessage(error), run.id, run.ownerId]
1005
+ );
1006
+ });
1007
+ return;
1008
+ }
1009
+ const bound = await this.#transaction(async (database) => {
1010
+ const current = await this.#runRow(database, run.id, run.ownerId, true);
1011
+ if (!current || current.status !== "dispatching" || current.dispatch_job_id !== jobId) {
1012
+ return false;
1013
+ }
1014
+ const nextCheckAt = Date.now() + this.#reconciliationIntervalMs;
1015
+ const reconciliationJobId = await this.#sendAt(
1016
+ database,
1017
+ { kind: "reconcile", ownerId: run.ownerId, runId: run.id },
1018
+ nextCheckAt
1019
+ );
1020
+ await database.executeSql(
1021
+ `UPDATE zukhruf_scheduled_runs
1022
+ SET status = 'running', external_execution_id = $1,
1023
+ reconciliation_job_id = $2, next_check_at = $3,
1024
+ started_at = $4, updated_at = $4
1025
+ WHERE id = $5 AND owner_id = $6`,
1026
+ [
1027
+ executionId,
1028
+ reconciliationJobId,
1029
+ nextCheckAt,
1030
+ Date.now(),
1031
+ run.id,
1032
+ run.ownerId
1033
+ ]
1034
+ );
1035
+ return true;
1036
+ });
1037
+ if (!bound) {
1038
+ await this.#executor.cancel({
1039
+ runId: run.id,
1040
+ ownerId: run.ownerId,
1041
+ executionId,
1042
+ executionConfig: run.executionConfig
1043
+ });
1044
+ }
1045
+ }
1046
+ async #reconcile(job, data) {
1047
+ const row = await this.#runRow(
1048
+ this.#database,
1049
+ data.runId,
1050
+ data.ownerId,
1051
+ false
1052
+ );
1053
+ if (!row || row.status !== "running" || row.reconciliation_job_id !== job.id || !row.external_execution_id) {
1054
+ return;
1055
+ }
1056
+ const run = toRun(row);
1057
+ let observed;
1058
+ try {
1059
+ observed = await this.#executor.inspect({
1060
+ runId: run.id,
1061
+ ownerId: run.ownerId,
1062
+ executionId: row.external_execution_id,
1063
+ executionConfig: run.executionConfig
1064
+ });
1065
+ } catch (error) {
1066
+ if (job.retryCount < job.retryLimit) throw error;
1067
+ await this.#scheduleNextInspection(job.id, run);
1068
+ return;
1069
+ }
1070
+ if (observed.status === "queued" || observed.status === "running") {
1071
+ await this.#transaction(async (database) => {
1072
+ const current = await this.#runRow(database, run.id, run.ownerId, true);
1073
+ if (!current || current.status !== "running" || current.reconciliation_job_id !== job.id) {
1074
+ return;
1075
+ }
1076
+ const nextCheckAt = Date.now() + this.#reconciliationIntervalMs;
1077
+ const nextJobId = await this.#sendAt(
1078
+ database,
1079
+ { kind: "reconcile", ownerId: run.ownerId, runId: run.id },
1080
+ nextCheckAt
1081
+ );
1082
+ await database.executeSql(
1083
+ `UPDATE zukhruf_scheduled_runs
1084
+ SET reconciliation_job_id = $1, next_check_at = $2,
1085
+ started_at = COALESCE(started_at, $3), updated_at = $4
1086
+ WHERE id = $5 AND owner_id = $6`,
1087
+ [
1088
+ nextJobId,
1089
+ nextCheckAt,
1090
+ observed.startedAt,
1091
+ Date.now(),
1092
+ run.id,
1093
+ run.ownerId
1094
+ ]
1095
+ );
1096
+ });
1097
+ return;
1098
+ }
1099
+ const terminal = observed;
1100
+ await this.#transaction(async (database) => {
1101
+ const current = await this.#runRow(database, run.id, run.ownerId, true);
1102
+ if (!current || current.status !== "running" || current.reconciliation_job_id !== job.id) {
1103
+ return;
1104
+ }
1105
+ await database.executeSql(
1106
+ `UPDATE zukhruf_scheduled_runs
1107
+ SET status = $1, review_status = 'pending_review',
1108
+ reconciliation_job_id = NULL, next_check_at = NULL,
1109
+ started_at = COALESCE(started_at, $2), finished_at = $3,
1110
+ error = $4, title = $5, summary = $6, updated_at = $7
1111
+ WHERE id = $8 AND owner_id = $9`,
1112
+ [
1113
+ terminal.status,
1114
+ terminal.startedAt,
1115
+ terminal.finishedAt,
1116
+ terminal.error,
1117
+ terminal.title,
1118
+ terminal.summary,
1119
+ Date.now(),
1120
+ run.id,
1121
+ run.ownerId
1122
+ ]
1123
+ );
1124
+ });
1125
+ }
1126
+ async #scheduleNextInspection(jobId, run) {
1127
+ await this.#transaction(async (database) => {
1128
+ const current = await this.#runRow(database, run.id, run.ownerId, true);
1129
+ if (!current || current.status !== "running" || current.reconciliation_job_id !== jobId) {
1130
+ return;
1131
+ }
1132
+ const nextCheckAt = Date.now() + this.#reconciliationIntervalMs;
1133
+ const nextJobId = await this.#sendAt(
1134
+ database,
1135
+ { kind: "reconcile", ownerId: run.ownerId, runId: run.id },
1136
+ nextCheckAt
1137
+ );
1138
+ await database.executeSql(
1139
+ `UPDATE zukhruf_scheduled_runs
1140
+ SET reconciliation_job_id = $1, next_check_at = $2, updated_at = $3
1141
+ WHERE id = $4 AND owner_id = $5`,
1142
+ [nextJobId, nextCheckAt, Date.now(), run.id, run.ownerId]
1143
+ );
1144
+ });
1145
+ }
1146
+ async #setReviewStatus(ownerId, runId, reviewStatus) {
1147
+ return this.#transaction(async (database) => {
1148
+ const run = await this.#requiredRun(database, ownerId, runId, true);
1149
+ if (!isTerminal(run.status) || run.reviewStatus === null) {
1150
+ throw new ScheduledTasksError(
1151
+ "conflict",
1152
+ "run",
1153
+ `Scheduled Run "${run.id}" is not ready for review`
1154
+ );
1155
+ }
1156
+ if (run.reviewStatus === "archived") {
1157
+ if (reviewStatus === "archived") return run;
1158
+ throw new ScheduledTasksError(
1159
+ "conflict",
1160
+ "run",
1161
+ `Scheduled Run "${run.id}" is archived`
1162
+ );
1163
+ }
1164
+ const { rows } = await database.executeSql(
1165
+ `UPDATE zukhruf_scheduled_runs
1166
+ SET review_status = $1, updated_at = $2
1167
+ WHERE id = $3 AND owner_id = $4
1168
+ RETURNING *`,
1169
+ [reviewStatus, Date.now(), run.id, run.ownerId]
1170
+ );
1171
+ return toRun(requiredRow(rows, "review"));
1172
+ });
1173
+ }
1174
+ async #finishCancelled(database, run) {
1175
+ const now = Date.now();
1176
+ const { rows } = await database.executeSql(
1177
+ `UPDATE zukhruf_scheduled_runs
1178
+ SET status = 'cancelled', review_status = 'pending_review',
1179
+ reconciliation_job_id = NULL, next_check_at = NULL,
1180
+ finished_at = $1, updated_at = $1
1181
+ WHERE id = $2 AND owner_id = $3
1182
+ RETURNING *`,
1183
+ [now, run.id, run.ownerId]
1184
+ );
1185
+ return toRun(requiredRow(rows, "cancel"));
1186
+ }
1187
+ async #sendNow(database, data) {
1188
+ const id = await this.#boss.send(this.#queue, data, { db: database });
1189
+ if (!id) throw new Error("pg-boss did not persist Scheduled Tasks job");
1190
+ return id;
1191
+ }
1192
+ async #sendAt(database, data, runAt) {
1193
+ const id = await this.#boss.sendAfter(
1194
+ this.#queue,
1195
+ data,
1196
+ { db: database },
1197
+ new Date(runAt)
1198
+ );
1199
+ if (!id) throw new Error("pg-boss did not persist Scheduled Tasks job");
1200
+ return id;
1201
+ }
1202
+ async #cancelJob(database, id) {
1203
+ await this.#boss.cancel(this.#queue, id, { db: database });
1204
+ }
1205
+ async #requiredTask(database, ownerId, taskId, forUpdate) {
1206
+ const row = await this.#taskRow(
1207
+ database,
1208
+ required(taskId, "Scheduled Task id"),
1209
+ required(ownerId, "Scheduled Task owner"),
1210
+ forUpdate
1211
+ );
1212
+ if (!row) {
1213
+ throw new ScheduledTasksError(
1214
+ "not-found",
1215
+ "task",
1216
+ `Scheduled Task "${taskId}" was not found`
1217
+ );
1218
+ }
1219
+ return toTask(row);
1220
+ }
1221
+ async #taskRow(database, taskId, ownerId, forUpdate) {
1222
+ const { rows } = await database.executeSql(
1223
+ `SELECT * FROM zukhruf_scheduled_tasks
1224
+ WHERE id = $1 AND owner_id = $2${forUpdate ? " FOR UPDATE" : ""}`,
1225
+ [taskId, ownerId]
1226
+ );
1227
+ return rows[0];
1228
+ }
1229
+ async #taskByKey(database, ownerId, idempotencyKey) {
1230
+ const { rows } = await database.executeSql(
1231
+ `SELECT * FROM zukhruf_scheduled_tasks
1232
+ WHERE owner_id = $1 AND idempotency_key = $2`,
1233
+ [ownerId, idempotencyKey]
1234
+ );
1235
+ const row = rows[0];
1236
+ return row ? toTask(row) : void 0;
1237
+ }
1238
+ async #requiredRun(database, ownerId, runId, forUpdate) {
1239
+ const row = await this.#runRow(
1240
+ database,
1241
+ required(runId, "Scheduled Run id"),
1242
+ required(ownerId, "Scheduled Task owner"),
1243
+ forUpdate
1244
+ );
1245
+ if (!row) {
1246
+ throw new ScheduledTasksError(
1247
+ "not-found",
1248
+ "run",
1249
+ `Scheduled Run "${runId}" was not found`
1250
+ );
1251
+ }
1252
+ return toRun(row);
1253
+ }
1254
+ async #runRow(database, runId, ownerId, forUpdate) {
1255
+ const { rows } = await database.executeSql(
1256
+ `SELECT * FROM zukhruf_scheduled_runs
1257
+ WHERE id = $1 AND owner_id = $2${forUpdate ? " FOR UPDATE" : ""}`,
1258
+ [runId, ownerId]
1259
+ );
1260
+ return rows[0];
1261
+ }
1262
+ async #manualRun(database, taskId, idempotencyKey) {
1263
+ const { rows } = await database.executeSql(
1264
+ `SELECT * FROM zukhruf_scheduled_runs
1265
+ WHERE task_id = $1 AND trigger = 'manual' AND idempotency_key = $2`,
1266
+ [taskId, idempotencyKey]
1267
+ );
1268
+ const row = rows[0];
1269
+ return row ? toRun(row) : void 0;
1270
+ }
1271
+ };
1272
+ function normalizeCreate(input) {
1273
+ const timezone = validateTimezone(input.timezone);
1274
+ const recurrence = required(input.recurrence, "Scheduled Task recurrence");
1275
+ return {
1276
+ idempotencyKey: required(
1277
+ input.idempotencyKey,
1278
+ "Scheduled Task idempotency key"
1279
+ ),
1280
+ name: required(input.name, "Scheduled Task name"),
1281
+ prompt: required(input.prompt, "Scheduled Task prompt"),
1282
+ recurrence,
1283
+ timezone,
1284
+ executionConfig: input.executionConfig,
1285
+ executionConfigJson: serializeExecutionConfig(input.executionConfig)
1286
+ };
1287
+ }
1288
+ function serializeExecutionConfig(value) {
1289
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
1290
+ throw new ScheduledTasksError(
1291
+ "invalid-input",
1292
+ "task",
1293
+ "Scheduled Task execution config must be a JSON object"
1294
+ );
1295
+ }
1296
+ let json;
1297
+ try {
1298
+ json = JSON.stringify(value);
1299
+ } catch (error) {
1300
+ throw new ScheduledTasksError(
1301
+ "invalid-input",
1302
+ "task",
1303
+ "Scheduled Task execution config must be JSON",
1304
+ { cause: error }
1305
+ );
1306
+ }
1307
+ if (!json || !isDeepStrictEqual(JSON.parse(json), value)) {
1308
+ throw new ScheduledTasksError(
1309
+ "invalid-input",
1310
+ "task",
1311
+ "Scheduled Task execution config must be a JSON object"
1312
+ );
1313
+ }
1314
+ return json;
1315
+ }
1316
+ function assertSameTask(task, input) {
1317
+ if (task.name !== input.name || task.prompt !== input.prompt || task.recurrence !== input.recurrence || task.timezone !== input.timezone || !isDeepStrictEqual(task.executionConfig, input.executionConfig)) {
1318
+ throw new ScheduledTasksError(
1319
+ "conflict",
1320
+ "task",
1321
+ "Scheduled Task idempotency key was reused"
1322
+ );
1323
+ }
1324
+ }
1325
+ function required(value, label) {
1326
+ const normalized = value.trim();
1327
+ if (!normalized) throw new Error(`${label} cannot be empty`);
1328
+ return normalized;
1329
+ }
1330
+ function validateTimezone(value) {
1331
+ const timezone = required(value, "Scheduled Task timezone");
1332
+ try {
1333
+ new Intl.DateTimeFormat("en", { timeZone: timezone }).format();
1334
+ } catch {
1335
+ throw new ScheduledTasksError(
1336
+ "invalid-input",
1337
+ "task",
1338
+ `Scheduled Task timezone "${timezone}" is invalid`
1339
+ );
1340
+ }
1341
+ return timezone;
1342
+ }
1343
+ function nextOccurrence(source, timezone, after) {
1344
+ const recurrence = required(source, "Scheduled Task recurrence");
1345
+ const start = /^DTSTART(?:;TZID=([^:]+))?:(\S+)$/m.exec(recurrence);
1346
+ if (!start) {
1347
+ if (recurrence.split(/\s+/).length !== 5) {
1348
+ throw new ScheduledTasksError(
1349
+ "invalid-input",
1350
+ "task",
1351
+ "Scheduled Task recurrence must include DTSTART or contain exactly five cron fields"
1352
+ );
1353
+ }
1354
+ const endDate = new Date(after);
1355
+ endDate.setUTCFullYear(endDate.getUTCFullYear() + 1);
1356
+ try {
1357
+ return CronExpressionParser.parse(recurrence, {
1358
+ currentDate: new Date(after),
1359
+ endDate,
1360
+ tz: timezone
1361
+ }).next().getTime();
1362
+ } catch (cause) {
1363
+ throw new ScheduledTasksError(
1364
+ "invalid-input",
1365
+ "task",
1366
+ "Scheduled Task recurrence must be a valid five-field cron expression with a match in the next year",
1367
+ { cause }
1368
+ );
1369
+ }
1370
+ }
1371
+ const embeddedTimezone = start[1] ?? (start[2]?.endsWith("Z") ? "UTC" : null);
1372
+ if (embeddedTimezone !== timezone) {
1373
+ throw new ScheduledTasksError(
1374
+ "invalid-input",
1375
+ "task",
1376
+ `Scheduled Task recurrence DTSTART timezone must be "${timezone}"`
1377
+ );
1378
+ }
1379
+ let rule;
1380
+ try {
1381
+ rule = rrulestr(recurrence);
1382
+ } catch (error) {
1383
+ throw new ScheduledTasksError(
1384
+ "invalid-input",
1385
+ "task",
1386
+ "Scheduled Task recurrence is invalid",
1387
+ { cause: error }
1388
+ );
1389
+ }
1390
+ const cursor = new Date(after);
1391
+ const occurrence = rule.after(
1392
+ timezone === "UTC" ? cursor : instantToLocalWallTime(cursor),
1393
+ false
1394
+ );
1395
+ if (!occurrence) return null;
1396
+ return (timezone === "UTC" ? occurrence : localWallTimeToInstant(occurrence)).getTime();
1397
+ }
1398
+ function instantToLocalWallTime(instant) {
1399
+ return new Date(
1400
+ Date.UTC(
1401
+ instant.getFullYear(),
1402
+ instant.getMonth(),
1403
+ instant.getDate(),
1404
+ instant.getHours(),
1405
+ instant.getMinutes(),
1406
+ instant.getSeconds(),
1407
+ instant.getMilliseconds()
1408
+ )
1409
+ );
1410
+ }
1411
+ function localWallTimeToInstant(wallTime) {
1412
+ return new Date(
1413
+ wallTime.getUTCFullYear(),
1414
+ wallTime.getUTCMonth(),
1415
+ wallTime.getUTCDate(),
1416
+ wallTime.getUTCHours(),
1417
+ wallTime.getUTCMinutes(),
1418
+ wallTime.getUTCSeconds(),
1419
+ wallTime.getUTCMilliseconds()
1420
+ );
1421
+ }
1422
+ function validateJob(value) {
1423
+ if (!value || typeof value !== "object") {
1424
+ throw new Error("Scheduled Tasks job payload must be an object");
1425
+ }
1426
+ const job = value;
1427
+ if ((job.kind === "dispatch" || job.kind === "reconcile") && typeof job.ownerId === "string" && typeof job.runId === "string") {
1428
+ return job;
1429
+ }
1430
+ if (job.kind === "occurrence" && typeof job.ownerId === "string" && typeof job.taskId === "string" && typeof job.occurrenceAt === "number" && typeof job.generation === "number") {
1431
+ return job;
1432
+ }
1433
+ throw new Error("Scheduled Tasks job payload is invalid");
1434
+ }
1435
+ function parseScheduledChange(payload) {
1436
+ let value;
1437
+ try {
1438
+ value = JSON.parse(payload);
1439
+ } catch {
1440
+ return void 0;
1441
+ }
1442
+ if (typeof value !== "object" || value === null || !("resource" in value) || !("ownerId" in value) || !("id" in value) || typeof value.ownerId !== "string" || typeof value.id !== "string") {
1443
+ return void 0;
1444
+ }
1445
+ if (value.resource === "schedule-task") {
1446
+ return {
1447
+ ownerId: value.ownerId,
1448
+ change: { type: "change", resource: value.resource, id: value.id }
1449
+ };
1450
+ }
1451
+ if (value.resource === "schedule-run" && "taskId" in value && typeof value.taskId === "string") {
1452
+ return {
1453
+ ownerId: value.ownerId,
1454
+ change: {
1455
+ type: "change",
1456
+ resource: value.resource,
1457
+ id: value.id,
1458
+ taskId: value.taskId
1459
+ }
1460
+ };
1461
+ }
1462
+ return void 0;
1463
+ }
1464
+ function toTask(row) {
1465
+ return {
1466
+ id: row.id,
1467
+ ownerId: row.owner_id,
1468
+ idempotencyKey: row.idempotency_key,
1469
+ name: row.name,
1470
+ prompt: row.prompt,
1471
+ recurrence: row.recurrence,
1472
+ timezone: row.timezone,
1473
+ executionConfig: row.execution_config,
1474
+ status: row.status,
1475
+ generation: Number(row.generation),
1476
+ nextRunAt: toMillis(row.next_run_at),
1477
+ createdAt: Number(row.created_at),
1478
+ updatedAt: Number(row.updated_at),
1479
+ archivedAt: toMillis(row.archived_at)
1480
+ };
1481
+ }
1482
+ function toRun(row) {
1483
+ return {
1484
+ id: row.id,
1485
+ taskId: row.task_id,
1486
+ ownerId: row.owner_id,
1487
+ trigger: row.trigger,
1488
+ occurrenceAt: Number(row.occurrence_at),
1489
+ prompt: row.prompt,
1490
+ executionConfig: row.execution_config,
1491
+ status: row.status,
1492
+ reviewStatus: row.review_status,
1493
+ externalExecutionId: row.external_execution_id,
1494
+ startedAt: toMillis(row.started_at),
1495
+ finishedAt: toMillis(row.finished_at),
1496
+ title: row.title,
1497
+ summary: row.summary,
1498
+ error: row.error,
1499
+ createdAt: Number(row.created_at),
1500
+ updatedAt: Number(row.updated_at)
1501
+ };
1502
+ }
1503
+ function toMillis(value) {
1504
+ return value === null ? null : Number(value);
1505
+ }
1506
+ function requiredRow(rows, operation) {
1507
+ const row = rows[0];
1508
+ if (!row)
1509
+ throw new Error(`Scheduled Tasks ${operation} did not return a row`);
1510
+ return row;
1511
+ }
1512
+ function isTerminal(status) {
1513
+ return status === "completed" || status === "failed" || status === "cancelled";
1514
+ }
1515
+ function errorMessage(error) {
1516
+ return error instanceof Error ? error.message : String(error);
1517
+ }
1518
+
1519
+ // packages/experimental/src/zukhruf/plugins/schedules/schedule-files.ts
1520
+ import { readFile, readdir } from "node:fs/promises";
1521
+ import { basename, extname, join } from "node:path";
1522
+ import { fileURLToPath } from "node:url";
1523
+ import YAML from "yaml";
1524
+ import { z as z9 } from "zod";
1525
+ var FILE_KEY_PREFIX = "zukhruf:schedule-file:";
1526
+ var frontmatterSchema = z9.object({
1527
+ name: z9.string().trim().min(1).optional(),
1528
+ cron: z9.string().trim().min(1),
1529
+ timezone: z9.string().trim().min(1)
1530
+ }).strict();
1531
+ function scheduleFiles({
1532
+ directory,
1533
+ ownerId
1534
+ }) {
1535
+ return (scheduled) => syncScheduleFiles(directory, ownerId, scheduled);
1536
+ }
1537
+ async function syncScheduleFiles(directory, ownerId, scheduled) {
1538
+ const directoryPath = directory instanceof URL ? fileURLToPath(directory) : directory;
1539
+ const declarations = await Promise.all(
1540
+ (await readdir(directoryPath, {
1541
+ withFileTypes: true
1542
+ })).filter(
1543
+ (entry) => entry.isFile() && !entry.name.startsWith(".") && extname(entry.name) === ".md"
1544
+ ).toSorted((left, right) => left.name.localeCompare(right.name)).map(async (entry) => {
1545
+ try {
1546
+ const match = (await readFile(join(directoryPath, entry.name), "utf8")).match(/^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/);
1547
+ if (!match) throw new Error("missing or malformed frontmatter");
1548
+ const frontmatter = frontmatterSchema.parse(YAML.parse(match[1]));
1549
+ const prompt = match[2].trim();
1550
+ if (!prompt) throw new Error("prompt cannot be empty");
1551
+ return {
1552
+ idempotencyKey: `${FILE_KEY_PREFIX}${entry.name}`,
1553
+ name: frontmatter.name ?? basename(entry.name, extname(entry.name)),
1554
+ prompt,
1555
+ recurrence: frontmatter.cron,
1556
+ timezone: frontmatter.timezone,
1557
+ executionConfig: {}
1558
+ };
1559
+ } catch (cause) {
1560
+ throw new Error(`Invalid schedule declaration ${entry.name}`, {
1561
+ cause
1562
+ });
1563
+ }
1564
+ })
1565
+ );
1566
+ const existing = (await scheduled.list(ownerId)).filter(
1567
+ ({ idempotencyKey }) => idempotencyKey.startsWith(FILE_KEY_PREFIX)
1568
+ );
1569
+ const existingByKey = new Map(
1570
+ existing.map((task) => [task.idempotencyKey, task])
1571
+ );
1572
+ for (const declaration of declarations) {
1573
+ if (existingByKey.get(declaration.idempotencyKey)?.status === "archived") {
1574
+ throw new Error(
1575
+ `Schedule declaration ${declaration.idempotencyKey.slice(FILE_KEY_PREFIX.length)} is archived`
1576
+ );
1577
+ }
1578
+ }
1579
+ for (const declaration of declarations) {
1580
+ const current = existingByKey.get(declaration.idempotencyKey);
1581
+ if (!current) {
1582
+ await scheduled.create(ownerId, declaration);
1583
+ continue;
1584
+ }
1585
+ let task = current;
1586
+ if (task.name !== declaration.name || task.prompt !== declaration.prompt || task.recurrence !== declaration.recurrence || task.timezone !== declaration.timezone || Object.keys(task.executionConfig).length > 0) {
1587
+ task = await scheduled.update(ownerId, task.id, declaration);
1588
+ }
1589
+ if (task.status === "paused") await scheduled.resume(ownerId, task.id);
1590
+ }
1591
+ const present = new Set(
1592
+ declarations.map(({ idempotencyKey }) => idempotencyKey)
1593
+ );
1594
+ for (const task of existing) {
1595
+ if (task.status === "active" && !present.has(task.idempotencyKey)) {
1596
+ await scheduled.pause(ownerId, task.id);
1597
+ }
1598
+ }
1599
+ }
1600
+
1601
+ // packages/experimental/src/zukhruf/plugins/schedules/index.ts
1602
+ var SCHEDULED_TASK_ORIGIN = "scheduled-task";
1603
+ var schedulesCapabilities = {
1604
+ boss: new AgentPluginCapability("schedules.boss"),
1605
+ transaction: new AgentPluginCapability(
1606
+ "schedules.transaction"
1607
+ )
1608
+ };
1609
+ function schedules(options) {
1610
+ return {
1611
+ name: "schedules",
1612
+ capabilities: [
1613
+ schedulesCapabilities.boss,
1614
+ schedulesCapabilities.transaction
1615
+ ],
1616
+ create: (bindings) => new SchedulesPlugin({
1617
+ ...options,
1618
+ boss: bindings.get(schedulesCapabilities.boss),
1619
+ transaction: bindings.get(schedulesCapabilities.transaction)
1620
+ })
1621
+ };
1622
+ }
1623
+ var SchedulesPlugin = class {
1624
+ #scheduled;
1625
+ #sources;
1626
+ #workerOptions;
1627
+ #host;
1628
+ #initialization;
1629
+ constructor({
1630
+ sources,
1631
+ workerOptions,
1632
+ ...options
1633
+ }) {
1634
+ this.#sources = sources;
1635
+ this.#workerOptions = workerOptions;
1636
+ this.#scheduled = new ScheduledTasks({
1637
+ ...options,
1638
+ executor: {
1639
+ launch: (input) => this.#launch(input),
1640
+ inspect: (input) => this.#inspect(input),
1641
+ cancel: (input) => this.#cancel(input)
1642
+ }
1643
+ });
1644
+ }
1645
+ initialize(host) {
1646
+ this.#host = host;
1647
+ if (!this.#initialization) this.#initialization = this.#initialize();
1648
+ return this.#initialization;
1649
+ }
1650
+ work(host, waitForActive) {
1651
+ if (this.#host !== host) {
1652
+ throw new Error(
1653
+ "schedules plugin must be initialized before work starts"
1654
+ );
1655
+ }
1656
+ return this.#scheduled.work(this.#workerOptions, waitForActive);
1657
+ }
1658
+ async create(ownerId, input) {
1659
+ const executionConfig = normalizeExecutionConfig(input.executionConfig);
1660
+ await this.#assertTarget(ownerId, executionConfig);
1661
+ return this.#scheduled.create(ownerId, { ...input, executionConfig });
1662
+ }
1663
+ get(ownerId, taskId) {
1664
+ return this.#scheduled.get(ownerId, taskId);
1665
+ }
1666
+ list(ownerId) {
1667
+ return this.#scheduled.list(ownerId);
1668
+ }
1669
+ listRuns(ownerId, taskId) {
1670
+ return this.#scheduled.listRuns(ownerId, taskId);
1671
+ }
1672
+ getRun(ownerId, runId) {
1673
+ return this.#scheduled.getRun(ownerId, runId);
1674
+ }
1675
+ listPendingReview(ownerId) {
1676
+ return this.#scheduled.listPendingReview(ownerId);
1677
+ }
1678
+ subscribeChanges(ownerId, signal) {
1679
+ return this.#scheduled.subscribeChanges(ownerId, signal);
1680
+ }
1681
+ pause(ownerId, taskId) {
1682
+ return this.#scheduled.pause(ownerId, taskId);
1683
+ }
1684
+ resume(ownerId, taskId) {
1685
+ return this.#scheduled.resume(ownerId, taskId);
1686
+ }
1687
+ async update(ownerId, taskId, input) {
1688
+ if (input.executionConfig === void 0) {
1689
+ return this.#scheduled.update(ownerId, taskId, input);
1690
+ }
1691
+ const executionConfig = normalizeExecutionConfig(input.executionConfig);
1692
+ await this.#assertTarget(ownerId, executionConfig);
1693
+ return this.#scheduled.update(ownerId, taskId, {
1694
+ ...input,
1695
+ executionConfig
1696
+ });
1697
+ }
1698
+ runNow(ownerId, taskId, idempotencyKey) {
1699
+ return this.#scheduled.runNow(ownerId, taskId, idempotencyKey);
1700
+ }
1701
+ archive(ownerId, taskId) {
1702
+ return this.#scheduled.archive(ownerId, taskId);
1703
+ }
1704
+ purge(ownerId, taskId) {
1705
+ return this.#scheduled.purge(ownerId, taskId);
1706
+ }
1707
+ cancelRun(ownerId, runId) {
1708
+ return this.#scheduled.cancelRun(ownerId, runId);
1709
+ }
1710
+ markReviewed(ownerId, runId) {
1711
+ return this.#scheduled.markReviewed(ownerId, runId);
1712
+ }
1713
+ archiveRun(ownerId, runId) {
1714
+ return this.#scheduled.archiveRun(ownerId, runId);
1715
+ }
1716
+ async #initialize() {
1717
+ await this.#scheduled.initialize();
1718
+ if (!this.#sources) return;
1719
+ for (const source of this.#sources) await source(this);
1720
+ }
1721
+ async #launch({
1722
+ runId,
1723
+ taskId,
1724
+ ownerId,
1725
+ trigger,
1726
+ occurrenceAt,
1727
+ prompt,
1728
+ executionConfig
1729
+ }) {
1730
+ const host = this.#requiredHost();
1731
+ const conversation = executionConversation(runId, ownerId, executionConfig);
1732
+ if (executionConfig.target?.kind === "existing-conversation" && !await host.conversationExists(conversation)) {
1733
+ throw new Error(
1734
+ `Scheduled target conversation "${conversation.chatId}" was not found`
1735
+ );
1736
+ }
1737
+ const execution = await host.enqueue(conversation, {
1738
+ message: {
1739
+ id: runId,
1740
+ role: "user",
1741
+ parts: [{ type: "text", text: prompt }],
1742
+ metadata: {
1743
+ zukhruf: {
1744
+ origin: SCHEDULED_TASK_ORIGIN,
1745
+ scheduledTask: { taskId, runId, trigger, occurrenceAt }
1746
+ }
1747
+ }
1748
+ },
1749
+ trigger: "submit-message"
1750
+ });
1751
+ return { executionId: execution.id };
1752
+ }
1753
+ async #inspect({
1754
+ runId,
1755
+ ownerId,
1756
+ executionId,
1757
+ executionConfig
1758
+ }) {
1759
+ const observation = this.#requiredHost().observe(
1760
+ executionConversation(runId, ownerId, executionConfig)
1761
+ );
1762
+ const execution = await observation.status(executionId);
1763
+ if (!execution) {
1764
+ throw new Error(`Scheduled execution "${executionId}" was not found`);
1765
+ }
1766
+ if (execution.status === "queued" || execution.status === "running") {
1767
+ return { status: execution.status, startedAt: execution.startedAt };
1768
+ }
1769
+ if (execution.finishedAt === null) {
1770
+ throw new Error(
1771
+ `Scheduled execution "${executionId}" is terminal without a finish time`
1772
+ );
1773
+ }
1774
+ if (execution.status === "completed" && (await observation.engine.getMessages()).find(
1775
+ (message) => message.role === "assistant" && message.id === executionId
1776
+ )?.parts.some(
1777
+ (part) => isToolUIPart2(part) && part.state === "approval-requested"
1778
+ )) {
1779
+ return {
1780
+ status: "failed",
1781
+ startedAt: execution.startedAt,
1782
+ finishedAt: execution.finishedAt,
1783
+ error: "Scheduled execution requires interactive tool approval",
1784
+ title: null,
1785
+ summary: null
1786
+ };
1787
+ }
1788
+ return {
1789
+ status: execution.status,
1790
+ startedAt: execution.startedAt,
1791
+ finishedAt: execution.finishedAt,
1792
+ error: execution.error,
1793
+ title: null,
1794
+ summary: null
1795
+ };
1796
+ }
1797
+ async #cancel({
1798
+ runId,
1799
+ ownerId,
1800
+ executionId,
1801
+ executionConfig
1802
+ }) {
1803
+ await this.#requiredHost().observe(executionConversation(runId, ownerId, executionConfig)).cancel(executionId);
1804
+ }
1805
+ async #assertTarget(ownerId, executionConfig) {
1806
+ if (executionConfig.target?.kind !== "existing-conversation") return;
1807
+ const conversation = {
1808
+ chatId: executionConfig.target.chatId,
1809
+ userId: ownerId
1810
+ };
1811
+ if (await this.#requiredHost().conversationExists(conversation)) return;
1812
+ throw new ScheduledTasksError(
1813
+ "invalid-input",
1814
+ "task",
1815
+ `Scheduled target conversation "${conversation.chatId}" was not found`
1816
+ );
1817
+ }
1818
+ #requiredHost() {
1819
+ if (!this.#host) throw new Error("schedules plugin is not initialized");
1820
+ return this.#host;
1821
+ }
1822
+ };
1823
+ function executionConversation(runId, ownerId, executionConfig) {
1824
+ const normalized = normalizeExecutionConfig(executionConfig);
1825
+ return {
1826
+ chatId: normalized.target?.kind === "existing-conversation" ? normalized.target.chatId : runId,
1827
+ userId: ownerId
1828
+ };
1829
+ }
1830
+ function normalizeExecutionConfig(value) {
1831
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
1832
+ throw new ScheduledTasksError(
1833
+ "invalid-input",
1834
+ "task",
1835
+ "Schedule execution config must be an object"
1836
+ );
1837
+ }
1838
+ if (Object.keys(value).some((key) => key !== "target")) {
1839
+ throw new ScheduledTasksError(
1840
+ "invalid-input",
1841
+ "task",
1842
+ "Schedule execution config contains an unknown field"
1843
+ );
1844
+ }
1845
+ const { target } = value;
1846
+ if (!target || target.kind === "new-conversation") return {};
1847
+ if (target.kind !== "existing-conversation") {
1848
+ throw new ScheduledTasksError(
1849
+ "invalid-input",
1850
+ "task",
1851
+ "Schedule target kind is invalid"
1852
+ );
1853
+ }
1854
+ const chatId = target.chatId.trim();
1855
+ if (!chatId) {
1856
+ throw new ScheduledTasksError(
1857
+ "invalid-input",
1858
+ "task",
1859
+ "Schedule target chatId cannot be empty"
1860
+ );
1861
+ }
1862
+ return { target: { kind: "existing-conversation", chatId } };
1863
+ }
1864
+ export {
1865
+ SCHEDULED_TASK_ORIGIN,
1866
+ SCHEDULE_CHANGES_CHANNEL,
1867
+ ScheduledTasks,
1868
+ ScheduledTasksError,
1869
+ scheduleFiles,
1870
+ schedules,
1871
+ schedulesCapabilities
1872
+ };
1873
+ //# sourceMappingURL=index.js.map