@hexabot-ai/agentic 3.2.2 → 3.2.4-beta.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 (51) hide show
  1. package/dist/cjs/bindings/base-binding.js +98 -25
  2. package/dist/cjs/dsl.types.js +141 -34
  3. package/dist/cjs/index.js +3 -1
  4. package/dist/cjs/runner-runtime-control.js +12 -0
  5. package/dist/cjs/step-executors/parallel-executor.js +5 -0
  6. package/dist/cjs/validation-issue.js +10 -0
  7. package/dist/cjs/workflow-compiler.js +3 -2
  8. package/dist/cjs/workflow-values.js +9 -8
  9. package/dist/cjs/workflow.js +3 -2
  10. package/dist/esm/bindings/base-binding.js +98 -25
  11. package/dist/esm/dsl.types.js +141 -34
  12. package/dist/esm/index.js +1 -0
  13. package/dist/esm/runner-runtime-control.js +12 -0
  14. package/dist/esm/step-executors/parallel-executor.js +5 -0
  15. package/dist/esm/validation-issue.js +6 -0
  16. package/dist/esm/workflow-compiler.js +3 -2
  17. package/dist/esm/workflow-values.js +9 -8
  18. package/dist/esm/workflow.js +3 -2
  19. package/dist/types/bindings/base-binding.d.ts +2 -1
  20. package/dist/types/bindings/base-binding.d.ts.map +1 -1
  21. package/dist/types/context.d.ts +12 -0
  22. package/dist/types/context.d.ts.map +1 -1
  23. package/dist/types/dsl.types.d.ts +4 -1
  24. package/dist/types/dsl.types.d.ts.map +1 -1
  25. package/dist/types/index.d.ts +1 -0
  26. package/dist/types/index.d.ts.map +1 -1
  27. package/dist/types/runner-runtime-control.d.ts +1 -0
  28. package/dist/types/runner-runtime-control.d.ts.map +1 -1
  29. package/dist/types/validation-issue.d.ts +16 -0
  30. package/dist/types/validation-issue.d.ts.map +1 -0
  31. package/dist/types/workflow-compiler.d.ts.map +1 -1
  32. package/dist/types/workflow-types.d.ts +17 -2
  33. package/dist/types/workflow-types.d.ts.map +1 -1
  34. package/dist/types/workflow-values.d.ts +2 -8
  35. package/dist/types/workflow-values.d.ts.map +1 -1
  36. package/dist/types/workflow.d.ts.map +1 -1
  37. package/package.json +1 -1
  38. package/src/__tests__/validation.test.ts +235 -17
  39. package/src/__tests__/workflow-runner.test.ts +185 -0
  40. package/src/__tests__/workflow-values.test.ts +26 -0
  41. package/src/bindings/base-binding.ts +116 -62
  42. package/src/context.ts +12 -0
  43. package/src/dsl.types.ts +225 -40
  44. package/src/index.ts +6 -0
  45. package/src/runner-runtime-control.ts +15 -0
  46. package/src/step-executors/parallel-executor.ts +6 -0
  47. package/src/validation-issue.ts +38 -0
  48. package/src/workflow-compiler.ts +3 -2
  49. package/src/workflow-types.ts +34 -4
  50. package/src/workflow-values.ts +19 -20
  51. package/src/workflow.ts +3 -2
@@ -1341,6 +1341,191 @@ describe('WorkflowRunner', () => {
1341
1341
  }
1342
1342
  });
1343
1343
 
1344
+ it('lets actions skip side effects via hasRecordedResult when replaying a resumed step', async () => {
1345
+ const sideEffects: string[] = [];
1346
+ const spawnAction = defineAction<
1347
+ unknown,
1348
+ { reply: string },
1349
+ TestContext,
1350
+ Settings
1351
+ >({
1352
+ name: 'spawn_then_wait_action',
1353
+ inputSchema: z.any(),
1354
+ outputSchema: z.object({ reply: z.string() }),
1355
+ execute: async ({ context }) => {
1356
+ // Deterministic replay re-runs this body; the guard must prevent the
1357
+ // side effect from executing a second time.
1358
+ if (!context.workflow.hasRecordedResult()) {
1359
+ sideEffects.push('spawn');
1360
+ }
1361
+
1362
+ const resumeData = (await context.workflow.suspend({
1363
+ reason: 'awaiting_child_workflow',
1364
+ })) as { reply: string };
1365
+
1366
+ return { reply: resumeData.reply };
1367
+ },
1368
+ });
1369
+ const definition: WorkflowDefinition = {
1370
+ defs: createTaskDefs({
1371
+ wait_step: {
1372
+ action: 'spawn_then_wait_action',
1373
+ inputs: {},
1374
+ },
1375
+ }),
1376
+ flow: [{ do: 'wait_step' }],
1377
+ outputs: { reply: '=$output.wait_step.reply' },
1378
+ };
1379
+ const compiled = compileWorkflow(definition, {
1380
+ actions: { spawn_then_wait_action: spawnAction },
1381
+ });
1382
+ const runner = new WorkflowRunner(compiled);
1383
+ const startResult = await runner.start({
1384
+ inputData: {},
1385
+ context: new TestContext({}),
1386
+ });
1387
+
1388
+ expect(startResult.status).toBe('suspended');
1389
+ if (startResult.status !== 'suspended') {
1390
+ throw new Error('Workflow did not suspend as expected');
1391
+ }
1392
+
1393
+ expect(sideEffects).toEqual(['spawn']);
1394
+
1395
+ const runtimeState = runner.getState() as ExecutionState;
1396
+ const rebuilt = await WorkflowRunner.fromPersistedState(compiled, {
1397
+ state: {
1398
+ input: { ...runtimeState.input },
1399
+ output: { ...runtimeState.output },
1400
+ iteration: runtimeState.iteration,
1401
+ accumulator: runtimeState.accumulator,
1402
+ iterationStack: [...runtimeState.iterationStack],
1403
+ },
1404
+ context: new TestContext({}),
1405
+ snapshot: startResult.snapshot,
1406
+ suspension: {
1407
+ stepId: startResult.step.id,
1408
+ reason: startResult.reason ?? null,
1409
+ data: startResult.data,
1410
+ stepExecId: startResult.stepExecId,
1411
+ suspendIndex: startResult.suspendIndex,
1412
+ suspendKey: startResult.suspendKey,
1413
+ awaitResults: startResult.awaitResults,
1414
+ },
1415
+ });
1416
+ const resumeResult = await rebuilt.resume({
1417
+ resumeData: { reply: 'child-finished' },
1418
+ });
1419
+
1420
+ expect(resumeResult.status).toBe('finished');
1421
+ if (resumeResult.status === 'finished') {
1422
+ expect(resumeResult.output.reply).toBe('child-finished');
1423
+ }
1424
+
1425
+ // The side effect must not run a second time during deterministic replay.
1426
+ expect(sideEffects).toEqual(['spawn']);
1427
+ });
1428
+
1429
+ it('reports recorded results only for suspensions that will replay immediately', async () => {
1430
+ const observed: boolean[] = [];
1431
+ const multiSuspendAction = defineAction<
1432
+ unknown,
1433
+ { firstReply: string; secondReply: string },
1434
+ TestContext,
1435
+ Settings
1436
+ >({
1437
+ name: 'observing_multi_suspend_action',
1438
+ inputSchema: z.any(),
1439
+ outputSchema: z.object({
1440
+ firstReply: z.string(),
1441
+ secondReply: z.string(),
1442
+ }),
1443
+ execute: async ({ context }) => {
1444
+ observed.push(context.workflow.hasRecordedResult());
1445
+ const first = (await context.workflow.suspend({
1446
+ reason: 'first_pause',
1447
+ })) as { reply: string };
1448
+
1449
+ observed.push(context.workflow.hasRecordedResult());
1450
+ const second = (await context.workflow.suspend({
1451
+ reason: 'second_pause',
1452
+ })) as { reply: string };
1453
+
1454
+ return {
1455
+ firstReply: first.reply,
1456
+ secondReply: second.reply,
1457
+ };
1458
+ },
1459
+ });
1460
+ const definition: WorkflowDefinition = {
1461
+ defs: createTaskDefs({
1462
+ wait_step: {
1463
+ action: 'observing_multi_suspend_action',
1464
+ inputs: {},
1465
+ },
1466
+ }),
1467
+ flow: [{ do: 'wait_step' }],
1468
+ outputs: {
1469
+ firstReply: '=$output.wait_step.firstReply',
1470
+ secondReply: '=$output.wait_step.secondReply',
1471
+ },
1472
+ };
1473
+ const compiled = compileWorkflow(definition, {
1474
+ actions: { observing_multi_suspend_action: multiSuspendAction },
1475
+ });
1476
+ const runner = new WorkflowRunner(compiled);
1477
+ const firstSuspension = await runner.start({
1478
+ inputData: {},
1479
+ context: new TestContext({}),
1480
+ });
1481
+ expect(firstSuspension.status).toBe('suspended');
1482
+
1483
+ const secondSuspension = await runner.resume({
1484
+ resumeData: { reply: 'first-answer' },
1485
+ });
1486
+ expect(secondSuspension.status).toBe('suspended');
1487
+ if (secondSuspension.status !== 'suspended') {
1488
+ throw new Error('Workflow did not suspend on second await point');
1489
+ }
1490
+
1491
+ // In-memory execution never sees pre-recorded results.
1492
+ expect(observed).toEqual([false, false]);
1493
+
1494
+ const runtimeState = runner.getState() as ExecutionState;
1495
+ const rebuilt = await WorkflowRunner.fromPersistedState(compiled, {
1496
+ state: {
1497
+ input: { ...runtimeState.input },
1498
+ output: { ...runtimeState.output },
1499
+ iteration: runtimeState.iteration,
1500
+ accumulator: runtimeState.accumulator,
1501
+ iterationStack: [...runtimeState.iterationStack],
1502
+ },
1503
+ context: new TestContext({}),
1504
+ snapshot: secondSuspension.snapshot,
1505
+ suspension: {
1506
+ stepId: secondSuspension.step.id,
1507
+ reason: secondSuspension.reason ?? null,
1508
+ data: secondSuspension.data,
1509
+ stepExecId: secondSuspension.stepExecId,
1510
+ suspendIndex: secondSuspension.suspendIndex,
1511
+ suspendKey: secondSuspension.suspendKey,
1512
+ awaitResults: secondSuspension.awaitResults,
1513
+ },
1514
+ });
1515
+ const finalResult = await rebuilt.resume({
1516
+ resumeData: { reply: 'second-answer' },
1517
+ });
1518
+
1519
+ expect(finalResult.status).toBe('finished');
1520
+ if (finalResult.status === 'finished') {
1521
+ expect(finalResult.output.firstReply).toBe('first-answer');
1522
+ expect(finalResult.output.secondReply).toBe('second-answer');
1523
+ }
1524
+
1525
+ // During replay both suspensions have recorded results awaiting them.
1526
+ expect(observed).toEqual([false, false, true, true]);
1527
+ });
1528
+
1344
1529
  it('fails resume when replay suspension metadata does not match the workflow code path', async () => {
1345
1530
  const suspendAction = defineAction<
1346
1531
  unknown,
@@ -92,6 +92,32 @@ describe('workflow values', () => {
92
92
  });
93
93
  });
94
94
 
95
+ it('registers custom functions on nested expressions inside literal values', async () => {
96
+ const translate = jest.fn((key: string) => `translated:${key}`);
97
+ const mapping = {
98
+ payload: compileValue(
99
+ {
100
+ title: "=$t('Title')",
101
+ actions: ['=$t("Confirm")', { label: "=$t('Cancel')" }],
102
+ },
103
+ { jsonataFunctions: { t: translate } },
104
+ ),
105
+ };
106
+ const values = await evaluateMapping(mapping, {
107
+ input: {},
108
+ context: new TestContext().state,
109
+ output: {},
110
+ });
111
+
112
+ expect(values).toEqual({
113
+ payload: {
114
+ title: 'translated:Title',
115
+ actions: ['translated:Confirm', { label: 'translated:Cancel' }],
116
+ },
117
+ });
118
+ expect(translate).toHaveBeenCalledTimes(3);
119
+ });
120
+
95
121
  it('handles missing mappings and deep merges settings', async () => {
96
122
  await expect(
97
123
  evaluateMapping(undefined, {
@@ -6,6 +6,8 @@
6
6
 
7
7
  import { z, type ZodIssue } from 'zod';
8
8
 
9
+ import { type WorkflowValidationIssue } from '../validation-issue';
10
+
9
11
  const TASK_KIND = 'task';
10
12
 
11
13
  export type BindingKindSchema = z.ZodTypeAny;
@@ -87,7 +89,7 @@ export type ValidateAndResolveBindingsOptions = {
87
89
  };
88
90
 
89
91
  type BindingValidationResult = {
90
- errors: string[];
92
+ issues: WorkflowValidationIssue[];
91
93
  resolvedDefs: ResolvedBindingDefs;
92
94
  };
93
95
 
@@ -116,11 +118,26 @@ const hasBindingsConfigured = (workflow: BindingAwareWorkflowLike): boolean => {
116
118
 
117
119
  return hasNonTaskDefs || hasNestedBindings;
118
120
  };
119
- const formatZodIssues = (issues: ZodIssue[], prefix: string): string[] =>
120
- issues.map((issue) => {
121
+ const toBindingSettingsIssues = (
122
+ zodIssues: ZodIssue[],
123
+ defName: string,
124
+ ): WorkflowValidationIssue[] =>
125
+ zodIssues.map((issue) => {
121
126
  const path = issue.path.join('.') || '<root>';
122
127
 
123
- return `${prefix}.${path}: ${issue.message}`;
128
+ return {
129
+ code: 'binding_settings',
130
+ message: `defs.${defName}.settings.${path}: ${issue.message}`,
131
+ path: [
132
+ 'defs',
133
+ defName,
134
+ 'settings',
135
+ ...issue.path.filter(
136
+ (segment): segment is string | number =>
137
+ typeof segment === 'string' || typeof segment === 'number',
138
+ ),
139
+ ],
140
+ };
124
141
  });
125
142
  const collectDuplicateReferences = (refs: string[]): string[] => {
126
143
  const seen = new Set<string>();
@@ -155,8 +172,10 @@ const collectBindingRefs = (
155
172
 
156
173
  return refs;
157
174
  };
158
- const detectBindingCycles = (defs: Record<string, DefLike>): string[] => {
159
- const errors: string[] = [];
175
+ const detectBindingCycles = (
176
+ defs: Record<string, DefLike>,
177
+ ): WorkflowValidationIssue[] => {
178
+ const issues: WorkflowValidationIssue[] = [];
160
179
  const reportedCycles = new Set<string>();
161
180
  const states = new Map<string, 'visiting' | 'visited'>();
162
181
  const stack: string[] = [];
@@ -178,9 +197,11 @@ const detectBindingCycles = (defs: Record<string, DefLike>): string[] => {
178
197
 
179
198
  if (!reportedCycles.has(cycleKey)) {
180
199
  reportedCycles.add(cycleKey);
181
- errors.push(
182
- `defs.${defName}.bindings: Circular binding reference detected (${cyclePath.join(' -> ')}).`,
183
- );
200
+ issues.push({
201
+ code: 'binding_cycle',
202
+ message: `defs.${defName}.bindings: Circular binding reference detected (${cyclePath.join(' -> ')}).`,
203
+ path: ['defs', defName, 'bindings'],
204
+ });
184
205
  }
185
206
 
186
207
  return;
@@ -206,14 +227,23 @@ const detectBindingCycles = (defs: Record<string, DefLike>): string[] => {
206
227
  visit(defName);
207
228
  }
208
229
 
209
- return errors;
230
+ return issues;
210
231
  };
232
+ const missingActionIssue = (
233
+ defName: string,
234
+ actionName: string,
235
+ ): WorkflowValidationIssue => ({
236
+ code: 'missing_action',
237
+ message: `defs.${defName}.action: No action implementation provided for "${actionName}".`,
238
+ path: ['defs', defName, 'action'],
239
+ actionName,
240
+ });
211
241
  const resolveSupportedBindingKinds = (
212
242
  definition: DefLike,
213
243
  defName: string,
214
244
  kinds: BindingKindSchemas,
215
245
  actions: Record<string, BindingValidationActionMetadata> | undefined,
216
- errors: string[],
246
+ issues: WorkflowValidationIssue[],
217
247
  ): readonly string[] | null => {
218
248
  if (definition.action) {
219
249
  if (!actions) {
@@ -222,9 +252,7 @@ const resolveSupportedBindingKinds = (
222
252
 
223
253
  const action = actions[definition.action];
224
254
  if (!action) {
225
- errors.push(
226
- `defs.${defName}.action: No action implementation provided for "${definition.action}".`,
227
- );
255
+ issues.push(missingActionIssue(defName, definition.action));
228
256
 
229
257
  return [];
230
258
  }
@@ -243,7 +271,7 @@ export const validateAndResolveBindings = (
243
271
  workflow: BindingAwareWorkflowLike,
244
272
  options?: BindingKindSchemas | ValidateAndResolveBindingsOptions,
245
273
  ): BindingValidationResult => {
246
- const errors: string[] = [];
274
+ const issues: WorkflowValidationIssue[] = [];
247
275
  const resolvedDefs: ResolvedBindingDefs = {};
248
276
  const defs = workflow.defs ?? {};
249
277
  const resolvedOptions = resolveValidationOptions(options);
@@ -254,17 +282,17 @@ export const validateAndResolveBindings = (
254
282
  const parsedSettingsByDefName = new Map<string, unknown>();
255
283
 
256
284
  if (hasBindingUsage && kindNames.length === 0) {
257
- errors.push(
258
- 'Workflows that declare non-task defs or nested bindings require a non-empty "bindingKinds" registry.',
259
- );
285
+ issues.push({
286
+ code: 'binding_registry_required',
287
+ message:
288
+ 'Workflows that declare non-task defs or nested bindings require a non-empty "bindingKinds" registry.',
289
+ });
260
290
  }
261
291
 
262
292
  for (const [defName, defDefinition] of Object.entries(defs)) {
263
293
  if (defDefinition.kind === TASK_KIND) {
264
294
  if (defDefinition.action && actions && !actions[defDefinition.action]) {
265
- errors.push(
266
- `defs.${defName}.action: No action implementation provided for "${defDefinition.action}".`,
267
- );
295
+ issues.push(missingActionIssue(defName, defDefinition.action));
268
296
  }
269
297
  continue;
270
298
  }
@@ -272,38 +300,42 @@ export const validateAndResolveBindings = (
272
300
  const kindDefinition = kinds[defDefinition.kind];
273
301
 
274
302
  if (!kindDefinition) {
275
- errors.push(
276
- `defs.${defName}.kind: Unknown binding kind "${defDefinition.kind}".`,
277
- );
303
+ issues.push({
304
+ code: 'unknown_binding_kind',
305
+ message: `defs.${defName}.kind: Unknown binding kind "${defDefinition.kind}".`,
306
+ path: ['defs', defName, 'kind'],
307
+ bindingKind: defDefinition.kind,
308
+ });
278
309
  continue;
279
310
  }
280
311
 
281
312
  const actionPolicy = kindDefinition.actionPolicy ?? 'optional';
282
313
  if (actionPolicy === 'required' && !defDefinition.action) {
283
- errors.push(
284
- `defs.${defName}.action: Binding kind "${defDefinition.kind}" requires an action.`,
285
- );
314
+ issues.push({
315
+ code: 'action_required',
316
+ message: `defs.${defName}.action: Binding kind "${defDefinition.kind}" requires an action.`,
317
+ path: ['defs', defName, 'action'],
318
+ bindingKind: defDefinition.kind,
319
+ });
286
320
  }
287
321
  if (actionPolicy === 'forbidden' && defDefinition.action) {
288
- errors.push(
289
- `defs.${defName}.action: Binding kind "${defDefinition.kind}" does not allow action declarations.`,
290
- );
322
+ issues.push({
323
+ code: 'action_forbidden',
324
+ message: `defs.${defName}.action: Binding kind "${defDefinition.kind}" does not allow action declarations.`,
325
+ path: ['defs', defName, 'action'],
326
+ bindingKind: defDefinition.kind,
327
+ });
291
328
  }
292
329
  if (defDefinition.action && actions && !actions[defDefinition.action]) {
293
- errors.push(
294
- `defs.${defName}.action: No action implementation provided for "${defDefinition.action}".`,
295
- );
330
+ issues.push(missingActionIssue(defName, defDefinition.action));
296
331
  }
297
332
 
298
333
  const { schema } = kindDefinition;
299
334
  const parsedPayload = schema.safeParse(defDefinition.settings);
300
335
 
301
336
  if (!parsedPayload.success) {
302
- errors.push(
303
- ...formatZodIssues(
304
- parsedPayload.error.issues,
305
- `defs.${defName}.settings`,
306
- ),
337
+ issues.push(
338
+ ...toBindingSettingsIssues(parsedPayload.error.issues, defName),
307
339
  );
308
340
  continue;
309
341
  }
@@ -323,31 +355,41 @@ export const validateAndResolveBindings = (
323
355
  defName,
324
356
  kinds,
325
357
  actions,
326
- errors,
358
+ issues,
327
359
  );
328
360
  const shouldValidateSupportedKinds = Array.isArray(supportedKinds);
329
361
 
330
362
  for (const [bindingKind, bindingRefs] of Object.entries(defBindings)) {
363
+ const bindingPath = ['defs', defName, 'bindings', bindingKind];
331
364
  const kindDefinition = kinds[bindingKind];
332
365
 
333
366
  if (!kindDefinition) {
334
- errors.push(
335
- `defs.${defName}.bindings.${bindingKind}: Unknown binding kind "${bindingKind}".`,
336
- );
367
+ issues.push({
368
+ code: 'unknown_binding_kind',
369
+ message: `defs.${defName}.bindings.${bindingKind}: Unknown binding kind "${bindingKind}".`,
370
+ path: bindingPath,
371
+ bindingKind,
372
+ });
337
373
  continue;
338
374
  }
339
375
 
340
376
  const { multiple } = kindDefinition;
341
377
  if (multiple && !Array.isArray(bindingRefs)) {
342
- errors.push(
343
- `defs.${defName}.bindings.${bindingKind}: Expected an array of def references for binding kind "${bindingKind}".`,
344
- );
378
+ issues.push({
379
+ code: 'binding_ref',
380
+ message: `defs.${defName}.bindings.${bindingKind}: Expected an array of def references for binding kind "${bindingKind}".`,
381
+ path: bindingPath,
382
+ bindingKind,
383
+ });
345
384
  continue;
346
385
  }
347
386
  if (!multiple && typeof bindingRefs !== 'string') {
348
- errors.push(
349
- `defs.${defName}.bindings.${bindingKind}: Expected a single def reference string for binding kind "${bindingKind}".`,
350
- );
387
+ issues.push({
388
+ code: 'binding_ref',
389
+ message: `defs.${defName}.bindings.${bindingKind}: Expected a single def reference string for binding kind "${bindingKind}".`,
390
+ path: bindingPath,
391
+ bindingKind,
392
+ });
351
393
  continue;
352
394
  }
353
395
 
@@ -358,39 +400,51 @@ export const validateAndResolveBindings = (
358
400
  ) {
359
401
  const supportedKindsLabel =
360
402
  supportedKinds.length > 0 ? supportedKinds.join(', ') : '<none>';
361
- errors.push(
362
- `defs.${defName}.bindings.${bindingKind}: "${defDefinition.action ?? defDefinition.kind}" does not support binding kind "${bindingKind}". Supported binding kinds: ${supportedKindsLabel}.`,
363
- );
403
+ issues.push({
404
+ code: 'binding_unsupported',
405
+ message: `defs.${defName}.bindings.${bindingKind}: "${defDefinition.action ?? defDefinition.kind}" does not support binding kind "${bindingKind}". Supported binding kinds: ${supportedKindsLabel}.`,
406
+ path: bindingPath,
407
+ bindingKind,
408
+ });
364
409
  }
365
410
 
366
411
  const refs = toBindingRefs(bindingRefs);
367
412
  const duplicateRefs = collectDuplicateReferences(refs);
368
413
  if (duplicateRefs.length > 0) {
369
- errors.push(
370
- `defs.${defName}.bindings.${bindingKind}: Duplicate def reference(s): ${duplicateRefs.join(', ')}`,
371
- );
414
+ issues.push({
415
+ code: 'binding_ref',
416
+ message: `defs.${defName}.bindings.${bindingKind}: Duplicate def reference(s): ${duplicateRefs.join(', ')}`,
417
+ path: bindingPath,
418
+ bindingKind,
419
+ });
372
420
  }
373
421
 
374
422
  for (const ref of refs) {
375
423
  const definition = defs[ref];
376
424
 
377
425
  if (!definition) {
378
- errors.push(
379
- `defs.${defName}.bindings.${bindingKind}: Unknown def reference "${ref}".`,
380
- );
426
+ issues.push({
427
+ code: 'binding_ref',
428
+ message: `defs.${defName}.bindings.${bindingKind}: Unknown def reference "${ref}".`,
429
+ path: bindingPath,
430
+ bindingKind,
431
+ });
381
432
  continue;
382
433
  }
383
434
 
384
435
  if (definition.kind !== bindingKind) {
385
- errors.push(
386
- `defs.${defName}.bindings.${bindingKind}: Def "${ref}" has kind "${definition.kind}" and cannot be mounted as "${bindingKind}".`,
387
- );
436
+ issues.push({
437
+ code: 'binding_ref',
438
+ message: `defs.${defName}.bindings.${bindingKind}: Def "${ref}" has kind "${definition.kind}" and cannot be mounted as "${bindingKind}".`,
439
+ path: bindingPath,
440
+ bindingKind,
441
+ });
388
442
  }
389
443
  }
390
444
  }
391
445
  }
392
446
 
393
- errors.push(...detectBindingCycles(defs));
447
+ issues.push(...detectBindingCycles(defs));
394
448
 
395
449
  const inProgress = new Set<string>();
396
450
  const mountResolvedDef = (
@@ -447,7 +501,7 @@ export const validateAndResolveBindings = (
447
501
  mountResolvedDef(defName);
448
502
  }
449
503
 
450
- return { errors, resolvedDefs };
504
+ return { issues, resolvedDefs };
451
505
  };
452
506
 
453
507
  export const mountTaskBindings = (
package/src/context.ts CHANGED
@@ -99,6 +99,18 @@ export interface WorkflowRuntimeControl {
99
99
  * @returns Promise resolved with the data supplied to {@link resume}.
100
100
  */
101
101
  suspend<T = unknown>(options?: SuspensionOptions): Promise<T>;
102
+ /**
103
+ * Reports whether the next {@link suspend} call in the currently running
104
+ * action already has a recorded resume result. This happens during
105
+ * deterministic replay of a resumed step: the action body re-executes and
106
+ * `suspend()` resolves immediately with the recorded payload. Actions that
107
+ * perform side effects before suspending must skip those side effects when
108
+ * this returns `true`, otherwise they run once per resume.
109
+ *
110
+ * @param key - Optional user key matching the `key` passed to `suspend`.
111
+ * @returns `true` when the upcoming suspension resolves from a recorded result.
112
+ */
113
+ hasRecordedResult(key?: string): boolean;
102
114
  resume(data?: unknown): void;
103
115
  getSnapshot(): WorkflowSnapshot;
104
116
  }