digital-workers 2.1.1 → 2.3.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 (197) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +136 -180
  3. package/dist/actions.d.ts.map +1 -1
  4. package/dist/actions.js +34 -21
  5. package/dist/actions.js.map +1 -1
  6. package/dist/agent-comms.d.ts +438 -0
  7. package/dist/agent-comms.d.ts.map +1 -0
  8. package/dist/agent-comms.js +677 -0
  9. package/dist/agent-comms.js.map +1 -0
  10. package/dist/approve.d.ts +40 -8
  11. package/dist/approve.d.ts.map +1 -1
  12. package/dist/approve.js +86 -20
  13. package/dist/approve.js.map +1 -1
  14. package/dist/ask.d.ts +38 -7
  15. package/dist/ask.d.ts.map +1 -1
  16. package/dist/ask.js +85 -25
  17. package/dist/ask.js.map +1 -1
  18. package/dist/browse.d.ts +223 -0
  19. package/dist/browse.d.ts.map +1 -0
  20. package/dist/browse.js +392 -0
  21. package/dist/browse.js.map +1 -0
  22. package/dist/capability-tiers.d.ts +230 -0
  23. package/dist/capability-tiers.d.ts.map +1 -0
  24. package/dist/capability-tiers.js +388 -0
  25. package/dist/capability-tiers.js.map +1 -0
  26. package/dist/cascade-context.d.ts +523 -0
  27. package/dist/cascade-context.d.ts.map +1 -0
  28. package/dist/cascade-context.js +494 -0
  29. package/dist/cascade-context.js.map +1 -0
  30. package/dist/client.d.ts +162 -0
  31. package/dist/client.d.ts.map +1 -0
  32. package/dist/client.js +64 -0
  33. package/dist/client.js.map +1 -0
  34. package/dist/decide.d.ts +42 -6
  35. package/dist/decide.d.ts.map +1 -1
  36. package/dist/decide.js +54 -11
  37. package/dist/decide.js.map +1 -1
  38. package/dist/do.d.ts +36 -7
  39. package/dist/do.d.ts.map +1 -1
  40. package/dist/do.js +82 -39
  41. package/dist/do.js.map +1 -1
  42. package/dist/error-escalation.d.ts +416 -0
  43. package/dist/error-escalation.d.ts.map +1 -0
  44. package/dist/error-escalation.js +656 -0
  45. package/dist/error-escalation.js.map +1 -0
  46. package/dist/generate.d.ts +48 -7
  47. package/dist/generate.d.ts.map +1 -1
  48. package/dist/generate.js +49 -8
  49. package/dist/generate.js.map +1 -1
  50. package/dist/goals.d.ts +10 -9
  51. package/dist/goals.d.ts.map +1 -1
  52. package/dist/goals.js +30 -24
  53. package/dist/goals.js.map +1 -1
  54. package/dist/image.d.ts +189 -0
  55. package/dist/image.d.ts.map +1 -0
  56. package/dist/image.js +528 -0
  57. package/dist/image.js.map +1 -0
  58. package/dist/index.d.ts +59 -2
  59. package/dist/index.d.ts.map +1 -1
  60. package/dist/index.js +92 -2
  61. package/dist/index.js.map +1 -1
  62. package/dist/is.d.ts +45 -10
  63. package/dist/is.d.ts.map +1 -1
  64. package/dist/is.js +56 -21
  65. package/dist/is.js.map +1 -1
  66. package/dist/kpis.d.ts +24 -15
  67. package/dist/kpis.d.ts.map +1 -1
  68. package/dist/kpis.js +16 -14
  69. package/dist/kpis.js.map +1 -1
  70. package/dist/load-balancing.d.ts +395 -0
  71. package/dist/load-balancing.d.ts.map +1 -0
  72. package/dist/load-balancing.js +991 -0
  73. package/dist/load-balancing.js.map +1 -0
  74. package/dist/logger.d.ts +76 -0
  75. package/dist/logger.d.ts.map +1 -0
  76. package/dist/logger.js +39 -0
  77. package/dist/logger.js.map +1 -0
  78. package/dist/notify.d.ts +38 -9
  79. package/dist/notify.d.ts.map +1 -1
  80. package/dist/notify.js +72 -17
  81. package/dist/notify.js.map +1 -1
  82. package/dist/role.d.ts +5 -4
  83. package/dist/role.d.ts.map +1 -1
  84. package/dist/role.js +13 -10
  85. package/dist/role.js.map +1 -1
  86. package/dist/runtime.d.ts +310 -0
  87. package/dist/runtime.d.ts.map +1 -0
  88. package/dist/runtime.js +510 -0
  89. package/dist/runtime.js.map +1 -0
  90. package/dist/team.d.ts +11 -6
  91. package/dist/team.d.ts.map +1 -1
  92. package/dist/team.js +22 -15
  93. package/dist/team.js.map +1 -1
  94. package/dist/transports/email.d.ts +318 -0
  95. package/dist/transports/email.d.ts.map +1 -0
  96. package/dist/transports/email.js +779 -0
  97. package/dist/transports/email.js.map +1 -0
  98. package/dist/transports/slack.d.ts +515 -0
  99. package/dist/transports/slack.d.ts.map +1 -0
  100. package/dist/transports/slack.js +844 -0
  101. package/dist/transports/slack.js.map +1 -0
  102. package/dist/transports.d.ts.map +1 -1
  103. package/dist/transports.js +44 -25
  104. package/dist/transports.js.map +1 -1
  105. package/dist/types.d.ts +149 -19
  106. package/dist/types.d.ts.map +1 -1
  107. package/dist/types.js +6 -0
  108. package/dist/types.js.map +1 -1
  109. package/dist/utils/id.d.ts +19 -0
  110. package/dist/utils/id.d.ts.map +1 -0
  111. package/dist/utils/id.js +21 -0
  112. package/dist/utils/id.js.map +1 -0
  113. package/dist/video.d.ts +203 -0
  114. package/dist/video.d.ts.map +1 -0
  115. package/dist/video.js +528 -0
  116. package/dist/video.js.map +1 -0
  117. package/dist/worker.d.ts +343 -0
  118. package/dist/worker.d.ts.map +1 -0
  119. package/dist/worker.js +698 -0
  120. package/dist/worker.js.map +1 -0
  121. package/package.json +24 -5
  122. package/src/actions.ts +48 -38
  123. package/src/agent-comms.ts +1200 -0
  124. package/src/approve.ts +91 -20
  125. package/src/ask.ts +99 -25
  126. package/src/browse.ts +627 -0
  127. package/src/capability-tiers.ts +545 -0
  128. package/src/cascade-context.ts +648 -0
  129. package/src/client.ts +221 -0
  130. package/src/decide.ts +81 -35
  131. package/src/do.ts +98 -52
  132. package/src/error-escalation.ts +1123 -0
  133. package/src/generate.ts +52 -18
  134. package/src/goals.ts +36 -27
  135. package/src/image.ts +816 -0
  136. package/src/index.ts +410 -2
  137. package/src/is.ts +59 -25
  138. package/src/kpis.ts +41 -36
  139. package/src/load-balancing.ts +1467 -0
  140. package/src/logger.ts +93 -0
  141. package/src/notify.ts +78 -17
  142. package/src/role.ts +30 -20
  143. package/src/runtime.ts +796 -0
  144. package/src/team.ts +24 -19
  145. package/src/transports/email.ts +1160 -0
  146. package/src/transports/slack.ts +1320 -0
  147. package/src/transports.ts +58 -43
  148. package/src/types.ts +182 -46
  149. package/src/utils/id.ts +21 -0
  150. package/src/video.ts +906 -0
  151. package/src/worker.ts +1007 -0
  152. package/test/agent-comms.test.ts +1397 -0
  153. package/test/approve.test.ts +305 -0
  154. package/test/ask.test.ts +274 -0
  155. package/test/browse.test.ts +361 -0
  156. package/test/capability-tiers.test.ts +631 -0
  157. package/test/cascade-context.test.ts +692 -0
  158. package/test/decide.test.ts +252 -0
  159. package/test/do.test.ts +144 -0
  160. package/test/error-escalation.test.ts +1205 -0
  161. package/test/error-logging.test.ts +357 -0
  162. package/test/generate.test.ts +319 -0
  163. package/test/image.test.ts +398 -0
  164. package/test/is.test.ts +287 -0
  165. package/test/load-balancing-safety.test.ts +404 -0
  166. package/test/load-balancing-thread-safety.test.ts +464 -0
  167. package/test/load-balancing.test.ts +1145 -0
  168. package/test/notify.test.ts +434 -0
  169. package/test/primitives.test.ts +320 -0
  170. package/test/runtime-integration.test.ts +892 -0
  171. package/test/transports/crypto.test.ts +230 -0
  172. package/test/transports/email.test.ts +866 -0
  173. package/test/transports/id-generation.test.ts +91 -0
  174. package/test/transports/slack.test.ts +760 -0
  175. package/test/type-safety.test.ts +834 -0
  176. package/test/types.test.ts +95 -2
  177. package/test/video.test.ts +530 -0
  178. package/test/worker.test.ts +1433 -0
  179. package/tsconfig.json +4 -1
  180. package/vitest.config.ts +42 -0
  181. package/wrangler.jsonc +36 -0
  182. package/.turbo/turbo-build.log +0 -5
  183. package/src/actions.js +0 -436
  184. package/src/approve.js +0 -234
  185. package/src/ask.js +0 -226
  186. package/src/decide.js +0 -244
  187. package/src/do.js +0 -227
  188. package/src/generate.js +0 -298
  189. package/src/goals.js +0 -205
  190. package/src/index.js +0 -68
  191. package/src/is.js +0 -317
  192. package/src/kpis.js +0 -270
  193. package/src/notify.js +0 -219
  194. package/src/role.js +0 -110
  195. package/src/team.js +0 -130
  196. package/src/transports.js +0 -357
  197. package/src/types.js +0 -71
@@ -0,0 +1,523 @@
1
+ /**
2
+ * Type-safe cascade context schema for agent coordination
3
+ *
4
+ * Provides structured data flow and coordination between agents in multi-agent
5
+ * workflows. Enables type-safe context propagation, validation, enrichment,
6
+ * and serialization for distributed agent systems.
7
+ *
8
+ * @packageDocumentation
9
+ */
10
+ import { z } from 'zod';
11
+ /**
12
+ * Agent tier levels for cascade hierarchies
13
+ *
14
+ * - coordinator: Orchestrates multiple agents, highest level
15
+ * - supervisor: Manages worker agents, handles escalation
16
+ * - worker: Executes standard tasks
17
+ * - specialist: Handles domain-specific tasks
18
+ * - executor: Low-level task execution
19
+ */
20
+ export declare const AgentTierSchema: z.ZodEnum<["coordinator", "supervisor", "worker", "specialist", "executor"]>;
21
+ export type AgentTier = z.infer<typeof AgentTierSchema>;
22
+ /**
23
+ * Version tracking for context evolution and debugging
24
+ */
25
+ export declare const ContextVersionSchema: z.ZodObject<{
26
+ major: z.ZodNumber;
27
+ minor: z.ZodNumber;
28
+ patch: z.ZodNumber;
29
+ timestamp: z.ZodDate;
30
+ hash: z.ZodOptional<z.ZodString>;
31
+ }, "strip", z.ZodTypeAny, {
32
+ major: number;
33
+ minor: number;
34
+ patch: number;
35
+ timestamp: Date;
36
+ hash?: string | undefined;
37
+ }, {
38
+ major: number;
39
+ minor: number;
40
+ patch: number;
41
+ timestamp: Date;
42
+ hash?: string | undefined;
43
+ }>;
44
+ export type ContextVersion = z.infer<typeof ContextVersionSchema>;
45
+ /**
46
+ * Reference to an agent with tier information
47
+ */
48
+ export declare const AgentRefSchema: z.ZodObject<{
49
+ id: z.ZodString;
50
+ tier: z.ZodEnum<["coordinator", "supervisor", "worker", "specialist", "executor"]>;
51
+ name: z.ZodOptional<z.ZodString>;
52
+ capabilities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
53
+ }, "strip", z.ZodTypeAny, {
54
+ tier: "worker" | "coordinator" | "supervisor" | "specialist" | "executor";
55
+ id: string;
56
+ name?: string | undefined;
57
+ capabilities?: string[] | undefined;
58
+ }, {
59
+ tier: "worker" | "coordinator" | "supervisor" | "specialist" | "executor";
60
+ id: string;
61
+ name?: string | undefined;
62
+ capabilities?: string[] | undefined;
63
+ }>;
64
+ export type AgentRef = z.infer<typeof AgentRefSchema>;
65
+ export declare const TaskPrioritySchema: z.ZodEnum<["critical", "high", "normal", "low"]>;
66
+ export type TaskPriority = z.infer<typeof TaskPrioritySchema>;
67
+ export declare const TaskInfoSchema: z.ZodObject<{
68
+ id: z.ZodString;
69
+ type: z.ZodString;
70
+ priority: z.ZodEnum<["critical", "high", "normal", "low"]>;
71
+ description: z.ZodString;
72
+ deadline: z.ZodOptional<z.ZodDate>;
73
+ parentTaskId: z.ZodOptional<z.ZodString>;
74
+ }, "strip", z.ZodTypeAny, {
75
+ description: string;
76
+ priority: "low" | "normal" | "high" | "critical";
77
+ id: string;
78
+ type: string;
79
+ deadline?: Date | undefined;
80
+ parentTaskId?: string | undefined;
81
+ }, {
82
+ description: string;
83
+ priority: "low" | "normal" | "high" | "critical";
84
+ id: string;
85
+ type: string;
86
+ deadline?: Date | undefined;
87
+ parentTaskId?: string | undefined;
88
+ }>;
89
+ export type TaskInfo = z.infer<typeof TaskInfoSchema>;
90
+ export declare const ExecutionPhaseSchema: z.ZodEnum<["planning", "execution", "validation", "escalation", "completed", "failed"]>;
91
+ export type ExecutionPhase = z.infer<typeof ExecutionPhaseSchema>;
92
+ export declare const ExecutionStateSchema: z.ZodObject<{
93
+ phase: z.ZodEnum<["planning", "execution", "validation", "escalation", "completed", "failed"]>;
94
+ startedAt: z.ZodDate;
95
+ completedAt: z.ZodOptional<z.ZodDate>;
96
+ attempts: z.ZodNumber;
97
+ lastError: z.ZodOptional<z.ZodString>;
98
+ escalatedFrom: z.ZodOptional<z.ZodString>;
99
+ }, "strip", z.ZodTypeAny, {
100
+ phase: "completed" | "failed" | "validation" | "planning" | "execution" | "escalation";
101
+ startedAt: Date;
102
+ attempts: number;
103
+ completedAt?: Date | undefined;
104
+ lastError?: string | undefined;
105
+ escalatedFrom?: string | undefined;
106
+ }, {
107
+ phase: "completed" | "failed" | "validation" | "planning" | "execution" | "escalation";
108
+ startedAt: Date;
109
+ attempts: number;
110
+ completedAt?: Date | undefined;
111
+ lastError?: string | undefined;
112
+ escalatedFrom?: string | undefined;
113
+ }>;
114
+ export type ExecutionState = z.infer<typeof ExecutionStateSchema>;
115
+ export declare const TraceEntrySchema: z.ZodObject<{
116
+ agentId: z.ZodString;
117
+ tier: z.ZodEnum<["coordinator", "supervisor", "worker", "specialist", "executor"]>;
118
+ timestamp: z.ZodDate;
119
+ action: z.ZodString;
120
+ input: z.ZodOptional<z.ZodUnknown>;
121
+ output: z.ZodOptional<z.ZodUnknown>;
122
+ duration: z.ZodOptional<z.ZodNumber>;
123
+ error: z.ZodOptional<z.ZodString>;
124
+ }, "strip", z.ZodTypeAny, {
125
+ tier: "worker" | "coordinator" | "supervisor" | "specialist" | "executor";
126
+ agentId: string;
127
+ action: string;
128
+ timestamp: Date;
129
+ error?: string | undefined;
130
+ duration?: number | undefined;
131
+ input?: unknown;
132
+ output?: unknown;
133
+ }, {
134
+ tier: "worker" | "coordinator" | "supervisor" | "specialist" | "executor";
135
+ agentId: string;
136
+ action: string;
137
+ timestamp: Date;
138
+ error?: string | undefined;
139
+ duration?: number | undefined;
140
+ input?: unknown;
141
+ output?: unknown;
142
+ }>;
143
+ export type TraceEntry = z.infer<typeof TraceEntrySchema>;
144
+ /**
145
+ * Main cascade context schema for agent coordination
146
+ *
147
+ * Contains all information needed for agents to coordinate in a cascade:
148
+ * - Identity: Context ID and version
149
+ * - Agents: Origin and current agent references
150
+ * - Task: Task information and priority
151
+ * - State: Current execution state
152
+ * - Data: Task-specific payload
153
+ * - Trace: Execution history for debugging
154
+ * - Metadata: Extension point for custom data
155
+ */
156
+ export declare const AgentCascadeContextSchema: z.ZodObject<{
157
+ id: z.ZodString;
158
+ version: z.ZodObject<{
159
+ major: z.ZodNumber;
160
+ minor: z.ZodNumber;
161
+ patch: z.ZodNumber;
162
+ timestamp: z.ZodDate;
163
+ hash: z.ZodOptional<z.ZodString>;
164
+ }, "strip", z.ZodTypeAny, {
165
+ major: number;
166
+ minor: number;
167
+ patch: number;
168
+ timestamp: Date;
169
+ hash?: string | undefined;
170
+ }, {
171
+ major: number;
172
+ minor: number;
173
+ patch: number;
174
+ timestamp: Date;
175
+ hash?: string | undefined;
176
+ }>;
177
+ originAgent: z.ZodObject<{
178
+ id: z.ZodString;
179
+ tier: z.ZodEnum<["coordinator", "supervisor", "worker", "specialist", "executor"]>;
180
+ name: z.ZodOptional<z.ZodString>;
181
+ capabilities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
182
+ }, "strip", z.ZodTypeAny, {
183
+ tier: "worker" | "coordinator" | "supervisor" | "specialist" | "executor";
184
+ id: string;
185
+ name?: string | undefined;
186
+ capabilities?: string[] | undefined;
187
+ }, {
188
+ tier: "worker" | "coordinator" | "supervisor" | "specialist" | "executor";
189
+ id: string;
190
+ name?: string | undefined;
191
+ capabilities?: string[] | undefined;
192
+ }>;
193
+ currentAgent: z.ZodObject<{
194
+ id: z.ZodString;
195
+ tier: z.ZodEnum<["coordinator", "supervisor", "worker", "specialist", "executor"]>;
196
+ name: z.ZodOptional<z.ZodString>;
197
+ capabilities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
198
+ }, "strip", z.ZodTypeAny, {
199
+ tier: "worker" | "coordinator" | "supervisor" | "specialist" | "executor";
200
+ id: string;
201
+ name?: string | undefined;
202
+ capabilities?: string[] | undefined;
203
+ }, {
204
+ tier: "worker" | "coordinator" | "supervisor" | "specialist" | "executor";
205
+ id: string;
206
+ name?: string | undefined;
207
+ capabilities?: string[] | undefined;
208
+ }>;
209
+ task: z.ZodObject<{
210
+ id: z.ZodString;
211
+ type: z.ZodString;
212
+ priority: z.ZodEnum<["critical", "high", "normal", "low"]>;
213
+ description: z.ZodString;
214
+ deadline: z.ZodOptional<z.ZodDate>;
215
+ parentTaskId: z.ZodOptional<z.ZodString>;
216
+ }, "strip", z.ZodTypeAny, {
217
+ description: string;
218
+ priority: "low" | "normal" | "high" | "critical";
219
+ id: string;
220
+ type: string;
221
+ deadline?: Date | undefined;
222
+ parentTaskId?: string | undefined;
223
+ }, {
224
+ description: string;
225
+ priority: "low" | "normal" | "high" | "critical";
226
+ id: string;
227
+ type: string;
228
+ deadline?: Date | undefined;
229
+ parentTaskId?: string | undefined;
230
+ }>;
231
+ state: z.ZodObject<{
232
+ phase: z.ZodEnum<["planning", "execution", "validation", "escalation", "completed", "failed"]>;
233
+ startedAt: z.ZodDate;
234
+ completedAt: z.ZodOptional<z.ZodDate>;
235
+ attempts: z.ZodNumber;
236
+ lastError: z.ZodOptional<z.ZodString>;
237
+ escalatedFrom: z.ZodOptional<z.ZodString>;
238
+ }, "strip", z.ZodTypeAny, {
239
+ phase: "completed" | "failed" | "validation" | "planning" | "execution" | "escalation";
240
+ startedAt: Date;
241
+ attempts: number;
242
+ completedAt?: Date | undefined;
243
+ lastError?: string | undefined;
244
+ escalatedFrom?: string | undefined;
245
+ }, {
246
+ phase: "completed" | "failed" | "validation" | "planning" | "execution" | "escalation";
247
+ startedAt: Date;
248
+ attempts: number;
249
+ completedAt?: Date | undefined;
250
+ lastError?: string | undefined;
251
+ escalatedFrom?: string | undefined;
252
+ }>;
253
+ data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
254
+ trace: z.ZodArray<z.ZodObject<{
255
+ agentId: z.ZodString;
256
+ tier: z.ZodEnum<["coordinator", "supervisor", "worker", "specialist", "executor"]>;
257
+ timestamp: z.ZodDate;
258
+ action: z.ZodString;
259
+ input: z.ZodOptional<z.ZodUnknown>;
260
+ output: z.ZodOptional<z.ZodUnknown>;
261
+ duration: z.ZodOptional<z.ZodNumber>;
262
+ error: z.ZodOptional<z.ZodString>;
263
+ }, "strip", z.ZodTypeAny, {
264
+ tier: "worker" | "coordinator" | "supervisor" | "specialist" | "executor";
265
+ agentId: string;
266
+ action: string;
267
+ timestamp: Date;
268
+ error?: string | undefined;
269
+ duration?: number | undefined;
270
+ input?: unknown;
271
+ output?: unknown;
272
+ }, {
273
+ tier: "worker" | "coordinator" | "supervisor" | "specialist" | "executor";
274
+ agentId: string;
275
+ action: string;
276
+ timestamp: Date;
277
+ error?: string | undefined;
278
+ duration?: number | undefined;
279
+ input?: unknown;
280
+ output?: unknown;
281
+ }>, "many">;
282
+ metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
283
+ }, "strip", z.ZodTypeAny, {
284
+ task: {
285
+ description: string;
286
+ priority: "low" | "normal" | "high" | "critical";
287
+ id: string;
288
+ type: string;
289
+ deadline?: Date | undefined;
290
+ parentTaskId?: string | undefined;
291
+ };
292
+ id: string;
293
+ version: {
294
+ major: number;
295
+ minor: number;
296
+ patch: number;
297
+ timestamp: Date;
298
+ hash?: string | undefined;
299
+ };
300
+ originAgent: {
301
+ tier: "worker" | "coordinator" | "supervisor" | "specialist" | "executor";
302
+ id: string;
303
+ name?: string | undefined;
304
+ capabilities?: string[] | undefined;
305
+ };
306
+ currentAgent: {
307
+ tier: "worker" | "coordinator" | "supervisor" | "specialist" | "executor";
308
+ id: string;
309
+ name?: string | undefined;
310
+ capabilities?: string[] | undefined;
311
+ };
312
+ state: {
313
+ phase: "completed" | "failed" | "validation" | "planning" | "execution" | "escalation";
314
+ startedAt: Date;
315
+ attempts: number;
316
+ completedAt?: Date | undefined;
317
+ lastError?: string | undefined;
318
+ escalatedFrom?: string | undefined;
319
+ };
320
+ trace: {
321
+ tier: "worker" | "coordinator" | "supervisor" | "specialist" | "executor";
322
+ agentId: string;
323
+ action: string;
324
+ timestamp: Date;
325
+ error?: string | undefined;
326
+ duration?: number | undefined;
327
+ input?: unknown;
328
+ output?: unknown;
329
+ }[];
330
+ metadata?: Record<string, unknown> | undefined;
331
+ data?: Record<string, unknown> | undefined;
332
+ }, {
333
+ task: {
334
+ description: string;
335
+ priority: "low" | "normal" | "high" | "critical";
336
+ id: string;
337
+ type: string;
338
+ deadline?: Date | undefined;
339
+ parentTaskId?: string | undefined;
340
+ };
341
+ id: string;
342
+ version: {
343
+ major: number;
344
+ minor: number;
345
+ patch: number;
346
+ timestamp: Date;
347
+ hash?: string | undefined;
348
+ };
349
+ originAgent: {
350
+ tier: "worker" | "coordinator" | "supervisor" | "specialist" | "executor";
351
+ id: string;
352
+ name?: string | undefined;
353
+ capabilities?: string[] | undefined;
354
+ };
355
+ currentAgent: {
356
+ tier: "worker" | "coordinator" | "supervisor" | "specialist" | "executor";
357
+ id: string;
358
+ name?: string | undefined;
359
+ capabilities?: string[] | undefined;
360
+ };
361
+ state: {
362
+ phase: "completed" | "failed" | "validation" | "planning" | "execution" | "escalation";
363
+ startedAt: Date;
364
+ attempts: number;
365
+ completedAt?: Date | undefined;
366
+ lastError?: string | undefined;
367
+ escalatedFrom?: string | undefined;
368
+ };
369
+ trace: {
370
+ tier: "worker" | "coordinator" | "supervisor" | "specialist" | "executor";
371
+ agentId: string;
372
+ action: string;
373
+ timestamp: Date;
374
+ error?: string | undefined;
375
+ duration?: number | undefined;
376
+ input?: unknown;
377
+ output?: unknown;
378
+ }[];
379
+ metadata?: Record<string, unknown> | undefined;
380
+ data?: Record<string, unknown> | undefined;
381
+ }>;
382
+ export type AgentCascadeContext = z.infer<typeof AgentCascadeContextSchema>;
383
+ /**
384
+ * Data added by an agent during context propagation
385
+ */
386
+ export interface ContextEnrichment {
387
+ agentId: string;
388
+ tier: AgentTier;
389
+ timestamp: Date;
390
+ data: Record<string, unknown>;
391
+ action?: string;
392
+ }
393
+ /**
394
+ * Result of context validation
395
+ */
396
+ export interface ValidationResult {
397
+ success: boolean;
398
+ data?: AgentCascadeContext;
399
+ errors?: Array<{
400
+ path: (string | number)[];
401
+ message: string;
402
+ code: string;
403
+ }>;
404
+ }
405
+ export interface ContextChange {
406
+ path: (string | number)[];
407
+ oldValue: unknown;
408
+ newValue: unknown;
409
+ type: 'added' | 'removed' | 'modified';
410
+ }
411
+ export interface ContextDiff {
412
+ changes: ContextChange[];
413
+ fromVersion: ContextVersion;
414
+ toVersion: ContextVersion;
415
+ }
416
+ /**
417
+ * Validate a cascade context against the schema
418
+ *
419
+ * @param context - The context to validate
420
+ * @returns Validation result with success flag and errors if any
421
+ *
422
+ * @example
423
+ * ```ts
424
+ * const result = validateContext(context)
425
+ * if (!result.success) {
426
+ * console.error('Invalid context:', result.errors)
427
+ * }
428
+ * ```
429
+ */
430
+ export declare function validateContext(context: unknown): ValidationResult;
431
+ /**
432
+ * Create a new context version
433
+ *
434
+ * @param options - Optional version numbers
435
+ * @returns A new ContextVersion
436
+ */
437
+ export declare function createContextVersion(options?: Partial<Pick<ContextVersion, 'major' | 'minor' | 'patch'>>): ContextVersion;
438
+ /**
439
+ * Create a new cascade context
440
+ *
441
+ * @param options - Context creation options
442
+ * @returns A new AgentCascadeContext
443
+ *
444
+ * @example
445
+ * ```ts
446
+ * const context = createCascadeContext({
447
+ * originAgent: { id: 'coordinator', tier: 'coordinator', name: 'Main' },
448
+ * task: { id: 'task_1', type: 'analysis', priority: 'normal', description: 'Analyze data' },
449
+ * })
450
+ * ```
451
+ */
452
+ export declare function createCascadeContext(options: {
453
+ originAgent: AgentRef;
454
+ task: TaskInfo;
455
+ data?: Record<string, unknown>;
456
+ metadata?: Record<string, unknown>;
457
+ }): AgentCascadeContext;
458
+ /**
459
+ * Enrich a context with data from an agent
460
+ *
461
+ * Creates a new context with:
462
+ * - Merged data from the enrichment
463
+ * - Updated currentAgent to the enriching agent
464
+ * - Incremented version patch
465
+ * - Added trace entry
466
+ *
467
+ * @param context - The original context
468
+ * @param enrichment - The enrichment data
469
+ * @returns A new enriched context (original is unchanged)
470
+ *
471
+ * @example
472
+ * ```ts
473
+ * const enriched = enrichContext(context, {
474
+ * agentId: 'worker_1',
475
+ * tier: 'worker',
476
+ * timestamp: new Date(),
477
+ * data: { analysisResult: 'approved' },
478
+ * })
479
+ * ```
480
+ */
481
+ export declare function enrichContext(context: AgentCascadeContext, enrichment: ContextEnrichment): AgentCascadeContext;
482
+ /**
483
+ * Serialize a cascade context to JSON string
484
+ *
485
+ * Handles Date objects by converting them to ISO strings.
486
+ *
487
+ * @param context - The context to serialize
488
+ * @returns JSON string representation
489
+ */
490
+ export declare function serializeContext(context: AgentCascadeContext): string;
491
+ /**
492
+ * Deserialize a JSON string to a cascade context
493
+ *
494
+ * Validates the deserialized data and restores Date objects.
495
+ *
496
+ * @param json - JSON string to deserialize
497
+ * @returns The deserialized and validated context
498
+ * @throws Error if JSON is invalid or context validation fails
499
+ */
500
+ export declare function deserializeContext(json: string): AgentCascadeContext;
501
+ /**
502
+ * Merge two cascade contexts
503
+ *
504
+ * Combines contexts preferring the newer version:
505
+ * - Takes version, state from the newer context
506
+ * - Deep merges data objects
507
+ * - Concatenates trace arrays
508
+ * - Merges metadata
509
+ *
510
+ * @param ctx1 - First context
511
+ * @param ctx2 - Second context
512
+ * @returns Merged context
513
+ */
514
+ export declare function mergeContexts(ctx1: AgentCascadeContext, ctx2: AgentCascadeContext): AgentCascadeContext;
515
+ /**
516
+ * Compare two contexts and return the differences
517
+ *
518
+ * @param ctx1 - Original context
519
+ * @param ctx2 - Modified context
520
+ * @returns Diff object with list of changes
521
+ */
522
+ export declare function diffContexts(ctx1: AgentCascadeContext, ctx2: AgentCascadeContext): ContextDiff;
523
+ //# sourceMappingURL=cascade-context.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cascade-context.d.ts","sourceRoot":"","sources":["../src/cascade-context.ts"],"names":[],"mappings":"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"}