@hexabot-ai/agentic 3.5.0 → 3.6.0-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.
- package/README.md +12 -3
- package/dist/cjs/action/abstract-action.js +51 -35
- package/dist/cjs/bindings/base-binding.js +229 -211
- package/dist/cjs/checkpoint.js +1 -1
- package/dist/cjs/context.js +2 -3
- package/dist/cjs/dsl.types.js +44 -90
- package/dist/cjs/errors.js +13 -1
- package/dist/cjs/index.js +3 -1
- package/dist/cjs/resume-payload.js +11 -1
- package/dist/cjs/runner-runtime-control.js +39 -27
- package/dist/cjs/step-executors/conditional-executor.js +2 -7
- package/dist/cjs/step-executors/loop-executor.js +14 -28
- package/dist/cjs/step-executors/parallel-executor.js +14 -25
- package/dist/cjs/step-executors/scope.js +25 -0
- package/dist/cjs/step-executors/skip-helpers.js +26 -34
- package/dist/cjs/step-executors/task-executor.js +58 -69
- package/dist/cjs/utils/flow-steps.js +41 -0
- package/dist/cjs/utils/naming.js +10 -10
- package/dist/cjs/utils/object-path.js +51 -0
- package/dist/cjs/utils/timeout.js +16 -39
- package/dist/cjs/validation-issue.js +14 -1
- package/dist/cjs/workflow-compiler.js +52 -96
- package/dist/cjs/workflow-fingerprint.js +22 -11
- package/dist/cjs/workflow-runner.js +19 -25
- package/dist/cjs/workflow-values.js +9 -7
- package/dist/cjs/workflow.js +44 -103
- package/dist/esm/action/abstract-action.js +51 -35
- package/dist/esm/bindings/base-binding.js +229 -211
- package/dist/esm/checkpoint.js +2 -2
- package/dist/esm/context.js +2 -3
- package/dist/esm/dsl.types.js +42 -88
- package/dist/esm/errors.js +11 -0
- package/dist/esm/index.js +2 -2
- package/dist/esm/resume-payload.js +10 -1
- package/dist/esm/runner-runtime-control.js +39 -27
- package/dist/esm/step-executors/conditional-executor.js +2 -7
- package/dist/esm/step-executors/loop-executor.js +14 -28
- package/dist/esm/step-executors/parallel-executor.js +14 -25
- package/dist/esm/step-executors/scope.js +21 -0
- package/dist/esm/step-executors/skip-helpers.js +27 -35
- package/dist/esm/step-executors/task-executor.js +58 -69
- package/dist/esm/utils/flow-steps.js +37 -0
- package/dist/esm/utils/naming.js +9 -9
- package/dist/esm/utils/object-path.js +46 -0
- package/dist/esm/utils/timeout.js +16 -39
- package/dist/esm/validation-issue.js +11 -0
- package/dist/esm/workflow-compiler.js +50 -95
- package/dist/esm/workflow-fingerprint.js +22 -11
- package/dist/esm/workflow-runner.js +21 -27
- package/dist/esm/workflow-values.js +7 -6
- package/dist/esm/workflow.js +43 -103
- package/dist/types/action/abstract-action.d.ts +7 -1
- package/dist/types/action/abstract-action.d.ts.map +1 -1
- package/dist/types/bindings/base-binding.d.ts +10 -0
- package/dist/types/bindings/base-binding.d.ts.map +1 -1
- package/dist/types/context.d.ts +2 -3
- package/dist/types/context.d.ts.map +1 -1
- package/dist/types/dsl.types.d.ts +7 -12
- package/dist/types/dsl.types.d.ts.map +1 -1
- package/dist/types/errors.d.ts +9 -0
- package/dist/types/errors.d.ts.map +1 -1
- package/dist/types/index.d.ts +2 -2
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/resume-payload.d.ts +7 -0
- package/dist/types/resume-payload.d.ts.map +1 -1
- package/dist/types/runner-runtime-control.d.ts.map +1 -1
- package/dist/types/step-executors/conditional-executor.d.ts.map +1 -1
- package/dist/types/step-executors/loop-executor.d.ts +2 -4
- package/dist/types/step-executors/loop-executor.d.ts.map +1 -1
- package/dist/types/step-executors/parallel-executor.d.ts.map +1 -1
- package/dist/types/step-executors/scope.d.ts +12 -0
- package/dist/types/step-executors/scope.d.ts.map +1 -0
- package/dist/types/step-executors/skip-helpers.d.ts +2 -8
- package/dist/types/step-executors/skip-helpers.d.ts.map +1 -1
- package/dist/types/step-executors/task-executor.d.ts.map +1 -1
- package/dist/types/utils/flow-steps.d.ts +16 -0
- package/dist/types/utils/flow-steps.d.ts.map +1 -0
- package/dist/types/utils/naming.d.ts +7 -7
- package/dist/types/utils/naming.d.ts.map +1 -1
- package/dist/types/utils/object-path.d.ts +11 -0
- package/dist/types/utils/object-path.d.ts.map +1 -0
- package/dist/types/utils/timeout.d.ts.map +1 -1
- package/dist/types/validation-issue.d.ts +13 -0
- package/dist/types/validation-issue.d.ts.map +1 -1
- package/dist/types/workflow-compiler.d.ts +15 -1
- package/dist/types/workflow-compiler.d.ts.map +1 -1
- package/dist/types/workflow-fingerprint.d.ts.map +1 -1
- package/dist/types/workflow-runner.d.ts +2 -0
- package/dist/types/workflow-runner.d.ts.map +1 -1
- package/dist/types/workflow-values.d.ts +2 -0
- package/dist/types/workflow-values.d.ts.map +1 -1
- package/dist/types/workflow.d.ts +2 -1
- package/dist/types/workflow.d.ts.map +1 -1
- package/examples/defs-bindings-agent/actions/ai-agent.ts +5 -3
- package/examples/defs-bindings-agent/actions/{caculate-score.ts → calculate-score.ts} +8 -8
- package/examples/defs-bindings-agent/actions/index.ts +2 -2
- package/examples/defs-bindings-agent/workflow.yml +2 -2
- package/examples/full/workflow.yml +20 -15
- package/examples/suspend-resume/workflow.yml +6 -3
- package/package.json +8 -5
- package/src/__tests__/checkpoint.test.ts +6 -1
- package/src/__tests__/resume-payload.test.ts +29 -0
- package/src/__tests__/test-helpers.ts +1 -1
- package/src/__tests__/validation.test.ts +330 -0
- package/src/__tests__/workflow-compiler.test.ts +278 -3
- package/src/__tests__/workflow-definition-path.test.ts +2 -0
- package/src/__tests__/workflow-fingerprint.test.ts +65 -0
- package/src/__tests__/workflow-runner.test.ts +280 -5
- package/src/__tests__/workflow-values.test.ts +13 -0
- package/src/__tests__/workflow.test.ts +4 -2
- package/src/action/__tests__/abstract-action-timing.test.ts +92 -0
- package/src/action/abstract-action.ts +67 -40
- package/src/bindings/base-binding.test.ts +470 -0
- package/src/bindings/base-binding.ts +344 -267
- package/src/checkpoint.ts +2 -4
- package/src/context.ts +2 -3
- package/src/dsl.types.ts +75 -154
- package/src/errors.ts +15 -0
- package/src/index.ts +2 -0
- package/src/resume-payload.ts +13 -3
- package/src/runner-runtime-control.ts +52 -29
- package/src/step-executors/conditional-executor.ts +3 -7
- package/src/step-executors/loop-executor.test.ts +55 -0
- package/src/step-executors/loop-executor.ts +16 -50
- package/src/step-executors/parallel-executor.ts +14 -37
- package/src/step-executors/scope.ts +30 -0
- package/src/step-executors/skip-helpers.test.ts +133 -0
- package/src/step-executors/skip-helpers.ts +43 -76
- package/src/step-executors/task-executor.test.ts +130 -1
- package/src/step-executors/task-executor.ts +109 -79
- package/src/utils/flow-steps.test.ts +121 -0
- package/src/utils/flow-steps.ts +62 -0
- package/src/utils/naming.test.ts +50 -0
- package/src/utils/naming.ts +11 -11
- package/src/utils/object-path.test.ts +70 -0
- package/src/utils/object-path.ts +67 -0
- package/src/utils/timeout.test.ts +152 -0
- package/src/utils/timeout.ts +26 -44
- package/src/validation-issue.test.ts +70 -0
- package/src/validation-issue.ts +27 -0
- package/src/workflow-compiler.ts +118 -180
- package/src/workflow-fingerprint.ts +23 -12
- package/src/workflow-runner.ts +28 -27
- package/src/workflow-values.ts +9 -7
- package/src/workflow.ts +58 -140
|
@@ -10,6 +10,7 @@ import {
|
|
|
10
10
|
type TaskFrame,
|
|
11
11
|
type WaitInfo,
|
|
12
12
|
} from '../checkpoint';
|
|
13
|
+
import type { StepExecutionRecord } from '../context';
|
|
13
14
|
import {
|
|
14
15
|
createLinkedAbortController,
|
|
15
16
|
getAbortReason,
|
|
@@ -25,14 +26,10 @@ import type {
|
|
|
25
26
|
} from '../runner-runtime-control';
|
|
26
27
|
import { cloneAsJson, cloneValue } from '../utils/clone';
|
|
27
28
|
import type { StepInfo } from '../workflow-event-emitter';
|
|
28
|
-
import type {
|
|
29
|
-
CompiledTask,
|
|
30
|
-
EvaluationScope,
|
|
31
|
-
ExecutionState,
|
|
32
|
-
TaskStep,
|
|
33
|
-
} from '../workflow-types';
|
|
29
|
+
import type { CompiledTask, ExecutionState, TaskStep } from '../workflow-types';
|
|
34
30
|
import { evaluateMapping } from '../workflow-values';
|
|
35
31
|
|
|
32
|
+
import { buildEvaluationScope } from './scope';
|
|
36
33
|
import type { StepExecutorEnv } from './types';
|
|
37
34
|
|
|
38
35
|
type TaskProgressOutcome =
|
|
@@ -75,38 +72,18 @@ export async function executeTaskStep(
|
|
|
75
72
|
}
|
|
76
73
|
|
|
77
74
|
const stepInfo = env.buildInstanceStepInfo(step, state.iterationStack);
|
|
78
|
-
|
|
79
|
-
const error = getAbortReason(env.signal);
|
|
80
|
-
recordTaskCancellation(env, stepInfo, error, frame?.wait);
|
|
81
|
-
throw error;
|
|
82
|
-
}
|
|
75
|
+
throwIfCancelled(env, stepInfo, frame);
|
|
83
76
|
|
|
84
77
|
// Resumed bodies reuse the inputs they first ran with: re-evaluating could
|
|
85
78
|
// differ, e.g. when an expression depends on the event that woke the run.
|
|
86
79
|
const inputs = frame
|
|
87
80
|
? cloneValue(frame.inputs)
|
|
88
|
-
: await evaluateMapping(task.inputs,
|
|
89
|
-
|
|
90
|
-
const error = getAbortReason(env.signal);
|
|
91
|
-
recordTaskCancellation(env, stepInfo, error, frame?.wait);
|
|
92
|
-
throw error;
|
|
93
|
-
}
|
|
81
|
+
: await evaluateMapping(task.inputs, buildEvaluationScope(env, state));
|
|
82
|
+
throwIfCancelled(env, stepInfo, frame);
|
|
94
83
|
// Kept apart from the object the body gets, so that a body changing its
|
|
95
84
|
// inputs cannot change the inputs every later pass replays.
|
|
96
85
|
const recordedInputs = frame ? frame.inputs : copyInputs(inputs);
|
|
97
86
|
const resumeData = frame ? env.resolutions.get(frame.wait.waitId) : undefined;
|
|
98
|
-
const seed: StepReplaySeed | undefined = frame
|
|
99
|
-
? {
|
|
100
|
-
awaitResults: {
|
|
101
|
-
...readRecordedResults(frame.awaitResults),
|
|
102
|
-
[frame.wait.suspendKey]: resumeData,
|
|
103
|
-
},
|
|
104
|
-
expected: {
|
|
105
|
-
suspendKey: frame.wait.suspendKey,
|
|
106
|
-
reason: frame.wait.reason,
|
|
107
|
-
},
|
|
108
|
-
}
|
|
109
|
-
: undefined;
|
|
110
87
|
const stepExecution = env.recordStepExecution(stepInfo, {
|
|
111
88
|
action: task.actionName,
|
|
112
89
|
status: 'running',
|
|
@@ -116,7 +93,9 @@ export async function executeTaskStep(
|
|
|
116
93
|
input: inputs,
|
|
117
94
|
context: { before: env.context.snapshot() },
|
|
118
95
|
});
|
|
119
|
-
env.runtime.beginStep(stepInfo, {
|
|
96
|
+
env.runtime.beginStep(stepInfo, {
|
|
97
|
+
seed: frame ? buildReplaySeed(frame, resumeData) : undefined,
|
|
98
|
+
});
|
|
120
99
|
env.markSnapshot(stepInfo, 'running');
|
|
121
100
|
if (frame) {
|
|
122
101
|
env.emit('hook:step:resumed', {
|
|
@@ -219,15 +198,39 @@ const copyInputs = (
|
|
|
219
198
|
return inputs;
|
|
220
199
|
}
|
|
221
200
|
};
|
|
222
|
-
|
|
201
|
+
/**
|
|
202
|
+
* Record the task cancelled and throw when the run was aborted before its
|
|
203
|
+
* body started.
|
|
204
|
+
*/
|
|
205
|
+
const throwIfCancelled = (
|
|
223
206
|
env: StepExecutorEnv,
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
207
|
+
stepInfo: StepInfo,
|
|
208
|
+
frame?: TaskFrame,
|
|
209
|
+
): void => {
|
|
210
|
+
if (!env.signal.aborted) {
|
|
211
|
+
return;
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
const error = getAbortReason(env.signal);
|
|
215
|
+
recordTaskCancellation(env, stepInfo, error, frame?.wait);
|
|
216
|
+
throw error;
|
|
217
|
+
};
|
|
218
|
+
/**
|
|
219
|
+
* Seed a resumed body with every answer it already got, including the one
|
|
220
|
+
* this pass resolved, and the suspension it is expected to reach again.
|
|
221
|
+
*/
|
|
222
|
+
const buildReplaySeed = (
|
|
223
|
+
frame: TaskFrame,
|
|
224
|
+
resumeData: unknown,
|
|
225
|
+
): StepReplaySeed => ({
|
|
226
|
+
awaitResults: {
|
|
227
|
+
...readRecordedResults(frame.awaitResults),
|
|
228
|
+
[frame.wait.suspendKey]: resumeData,
|
|
229
|
+
},
|
|
230
|
+
expected: {
|
|
231
|
+
suspendKey: frame.wait.suspendKey,
|
|
232
|
+
reason: frame.wait.reason,
|
|
233
|
+
},
|
|
231
234
|
});
|
|
232
235
|
const waitForTaskProgress = async (
|
|
233
236
|
signal: AbortSignal,
|
|
@@ -273,13 +276,9 @@ const completeTask = async (
|
|
|
273
276
|
result: unknown,
|
|
274
277
|
) => {
|
|
275
278
|
await env.captureTaskOutput(task, state, result);
|
|
276
|
-
const stepExecution = env
|
|
277
|
-
status: 'completed',
|
|
278
|
-
endedAt: Date.now(),
|
|
279
|
+
const stepExecution = endStepExecution(env, stepInfo, 'completed', {
|
|
279
280
|
output: result,
|
|
280
|
-
context: { after: env.context.snapshot() },
|
|
281
281
|
});
|
|
282
|
-
env.markSnapshot(stepInfo, 'completed');
|
|
283
282
|
env.emit('hook:step:success', {
|
|
284
283
|
runId: env.runId,
|
|
285
284
|
step: stepInfo,
|
|
@@ -302,13 +301,13 @@ const suspendTask = (
|
|
|
302
301
|
...(request.accepts ? { accepts: request.accepts } : {}),
|
|
303
302
|
...(request.payloadOptional ? { payloadOptional: true } : {}),
|
|
304
303
|
};
|
|
305
|
-
const stepExecution =
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
304
|
+
const stepExecution = endStepExecution(
|
|
305
|
+
env,
|
|
306
|
+
stepInfo,
|
|
307
|
+
'suspended',
|
|
308
|
+
{ reason: request.reason },
|
|
309
|
+
request.reason,
|
|
310
|
+
);
|
|
312
311
|
env.emit('hook:step:suspended', {
|
|
313
312
|
runId: env.runId,
|
|
314
313
|
step: stepInfo,
|
|
@@ -347,13 +346,13 @@ const keepWaiting = (
|
|
|
347
346
|
frame: TaskFrame,
|
|
348
347
|
error: WorkflowResumeRejectedError,
|
|
349
348
|
): TaskFrame => {
|
|
350
|
-
const stepExecution =
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
349
|
+
const stepExecution = endStepExecution(
|
|
350
|
+
env,
|
|
351
|
+
stepInfo,
|
|
352
|
+
'suspended',
|
|
353
|
+
{ reason: frame.wait.reason },
|
|
354
|
+
frame.wait.reason,
|
|
355
|
+
);
|
|
357
356
|
env.emit('hook:step:resume_rejected', {
|
|
358
357
|
runId: env.runId,
|
|
359
358
|
step: stepInfo,
|
|
@@ -370,14 +369,12 @@ const recordTaskFailure = (
|
|
|
370
369
|
stepInfo: StepInfo,
|
|
371
370
|
error: unknown,
|
|
372
371
|
) => {
|
|
373
|
-
const
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
error
|
|
378
|
-
|
|
379
|
-
});
|
|
380
|
-
env.markSnapshot(stepInfo, 'failed', normalizeErrorMessage(error));
|
|
372
|
+
const stepExecution = endStepExecutionWithError(
|
|
373
|
+
env,
|
|
374
|
+
stepInfo,
|
|
375
|
+
'failed',
|
|
376
|
+
error,
|
|
377
|
+
);
|
|
381
378
|
env.emit('hook:step:error', {
|
|
382
379
|
runId: env.runId,
|
|
383
380
|
step: stepInfo,
|
|
@@ -395,14 +392,12 @@ const recordTaskCancellation = (
|
|
|
395
392
|
error: unknown,
|
|
396
393
|
wait?: WaitInfo,
|
|
397
394
|
) => {
|
|
398
|
-
const
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
error
|
|
403
|
-
|
|
404
|
-
});
|
|
405
|
-
env.markSnapshot(stepInfo, 'cancelled', normalizeErrorMessage(error));
|
|
395
|
+
const stepExecution = endStepExecutionWithError(
|
|
396
|
+
env,
|
|
397
|
+
stepInfo,
|
|
398
|
+
'cancelled',
|
|
399
|
+
error,
|
|
400
|
+
);
|
|
406
401
|
env.emit('hook:step:cancelled', {
|
|
407
402
|
runId: env.runId,
|
|
408
403
|
step: stepInfo,
|
|
@@ -411,9 +406,44 @@ const recordTaskCancellation = (
|
|
|
411
406
|
...(wait ? { wait } : {}),
|
|
412
407
|
});
|
|
413
408
|
};
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
409
|
+
/**
|
|
410
|
+
* Close the step's execution record with the status the step ended (or
|
|
411
|
+
* paused) with, and mirror that status on its snapshot.
|
|
412
|
+
*
|
|
413
|
+
* @returns The updated execution record, for the event announcing it.
|
|
414
|
+
*/
|
|
415
|
+
const endStepExecution = (
|
|
416
|
+
env: StepExecutorEnv,
|
|
417
|
+
stepInfo: StepInfo,
|
|
418
|
+
status: 'completed' | 'suspended' | 'failed' | 'cancelled',
|
|
419
|
+
details: Pick<StepExecutionRecord, 'output' | 'reason' | 'error'>,
|
|
420
|
+
snapshotReason?: string,
|
|
421
|
+
): StepExecutionRecord => {
|
|
422
|
+
const stepExecution = env.recordStepExecution(stepInfo, {
|
|
423
|
+
status,
|
|
424
|
+
endedAt: Date.now(),
|
|
425
|
+
...details,
|
|
426
|
+
context: { after: env.context.snapshot() },
|
|
427
|
+
});
|
|
428
|
+
env.markSnapshot(stepInfo, status, snapshotReason);
|
|
429
|
+
|
|
430
|
+
return stepExecution;
|
|
431
|
+
};
|
|
432
|
+
const endStepExecutionWithError = (
|
|
433
|
+
env: StepExecutorEnv,
|
|
434
|
+
stepInfo: StepInfo,
|
|
435
|
+
status: 'failed' | 'cancelled',
|
|
436
|
+
error: unknown,
|
|
437
|
+
): StepExecutionRecord =>
|
|
438
|
+
endStepExecution(
|
|
439
|
+
env,
|
|
440
|
+
stepInfo,
|
|
441
|
+
status,
|
|
442
|
+
{
|
|
443
|
+
error:
|
|
444
|
+
error instanceof Error
|
|
445
|
+
? { message: error.message, stack: error.stack }
|
|
446
|
+
: { message: String(error) },
|
|
447
|
+
},
|
|
448
|
+
error instanceof Error ? error.message : String(error),
|
|
449
|
+
);
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Hexabot — Fair Core License (FCL-1.0-ALv2)
|
|
3
|
+
* Copyright (c) 2026 Hexastack.
|
|
4
|
+
* Full terms: see LICENSE.md.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import type { FlowStep } from '../dsl.types';
|
|
8
|
+
|
|
9
|
+
import { collectTaskReferences } from './flow-steps';
|
|
10
|
+
|
|
11
|
+
describe('collectTaskReferences', () => {
|
|
12
|
+
it('lists the task references of every nested step list, in flow order', () => {
|
|
13
|
+
const flow: FlowStep[] = [
|
|
14
|
+
{ do: 'first' },
|
|
15
|
+
{
|
|
16
|
+
parallel: {
|
|
17
|
+
steps: [
|
|
18
|
+
{ do: 'second' },
|
|
19
|
+
{
|
|
20
|
+
conditional: {
|
|
21
|
+
when: [
|
|
22
|
+
{ condition: '=true', steps: [{ do: 'third' }] },
|
|
23
|
+
{
|
|
24
|
+
else: true,
|
|
25
|
+
steps: [
|
|
26
|
+
{
|
|
27
|
+
loop: {
|
|
28
|
+
type: 'while',
|
|
29
|
+
while: '=false',
|
|
30
|
+
steps: [{ do: 'fourth' }, { do: 'first' }],
|
|
31
|
+
},
|
|
32
|
+
},
|
|
33
|
+
],
|
|
34
|
+
},
|
|
35
|
+
],
|
|
36
|
+
},
|
|
37
|
+
},
|
|
38
|
+
],
|
|
39
|
+
},
|
|
40
|
+
},
|
|
41
|
+
];
|
|
42
|
+
|
|
43
|
+
expect(collectTaskReferences(flow)).toEqual([
|
|
44
|
+
{ taskId: 'first', path: ['flow', 0, 'do'] },
|
|
45
|
+
{ taskId: 'second', path: ['flow', 1, 'parallel', 'steps', 0, 'do'] },
|
|
46
|
+
{
|
|
47
|
+
taskId: 'third',
|
|
48
|
+
path: [
|
|
49
|
+
'flow',
|
|
50
|
+
1,
|
|
51
|
+
'parallel',
|
|
52
|
+
'steps',
|
|
53
|
+
1,
|
|
54
|
+
'conditional',
|
|
55
|
+
'when',
|
|
56
|
+
0,
|
|
57
|
+
'steps',
|
|
58
|
+
0,
|
|
59
|
+
'do',
|
|
60
|
+
],
|
|
61
|
+
},
|
|
62
|
+
{
|
|
63
|
+
taskId: 'fourth',
|
|
64
|
+
path: [
|
|
65
|
+
'flow',
|
|
66
|
+
1,
|
|
67
|
+
'parallel',
|
|
68
|
+
'steps',
|
|
69
|
+
1,
|
|
70
|
+
'conditional',
|
|
71
|
+
'when',
|
|
72
|
+
1,
|
|
73
|
+
'steps',
|
|
74
|
+
0,
|
|
75
|
+
'loop',
|
|
76
|
+
'steps',
|
|
77
|
+
0,
|
|
78
|
+
'do',
|
|
79
|
+
],
|
|
80
|
+
},
|
|
81
|
+
{
|
|
82
|
+
taskId: 'first',
|
|
83
|
+
path: [
|
|
84
|
+
'flow',
|
|
85
|
+
1,
|
|
86
|
+
'parallel',
|
|
87
|
+
'steps',
|
|
88
|
+
1,
|
|
89
|
+
'conditional',
|
|
90
|
+
'when',
|
|
91
|
+
1,
|
|
92
|
+
'steps',
|
|
93
|
+
0,
|
|
94
|
+
'loop',
|
|
95
|
+
'steps',
|
|
96
|
+
1,
|
|
97
|
+
'do',
|
|
98
|
+
],
|
|
99
|
+
},
|
|
100
|
+
]);
|
|
101
|
+
});
|
|
102
|
+
|
|
103
|
+
it('locates references under the given base path', () => {
|
|
104
|
+
expect(collectTaskReferences([{ do: 'task' }], ['defs', 'x'])).toEqual([
|
|
105
|
+
{ taskId: 'task', path: ['defs', 'x', 0, 'do'] },
|
|
106
|
+
]);
|
|
107
|
+
});
|
|
108
|
+
|
|
109
|
+
it('finds no reference in empty or unknown steps', () => {
|
|
110
|
+
expect(collectTaskReferences([])).toEqual([]);
|
|
111
|
+
expect(
|
|
112
|
+
collectTaskReferences([{ unknown: {} } as unknown as FlowStep]),
|
|
113
|
+
).toEqual([]);
|
|
114
|
+
expect(
|
|
115
|
+
collectTaskReferences([
|
|
116
|
+
{ parallel: { steps: [] } },
|
|
117
|
+
{ loop: { type: 'while', while: '=false', steps: [] } },
|
|
118
|
+
]),
|
|
119
|
+
).toEqual([]);
|
|
120
|
+
});
|
|
121
|
+
});
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Hexabot — Fair Core License (FCL-1.0-ALv2)
|
|
3
|
+
* Copyright (c) 2026 Hexastack.
|
|
4
|
+
* Full terms: see LICENSE.md.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import type { FlowStep } from '../dsl.types';
|
|
8
|
+
|
|
9
|
+
type DefinitionPath = Array<string | number>;
|
|
10
|
+
|
|
11
|
+
/** A `do` step: the task it runs, and where the reference sits. */
|
|
12
|
+
export type TaskReference = {
|
|
13
|
+
taskId: string;
|
|
14
|
+
path: DefinitionPath;
|
|
15
|
+
};
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* The step lists nested in a flow step, each with its path relative to the
|
|
19
|
+
* step: one for `parallel` and `loop`, one per branch for `conditional`.
|
|
20
|
+
*/
|
|
21
|
+
const nestedStepLists = (
|
|
22
|
+
step: FlowStep,
|
|
23
|
+
): Array<{ steps: FlowStep[]; path: DefinitionPath }> => {
|
|
24
|
+
if ('parallel' in step) {
|
|
25
|
+
return [{ steps: step.parallel.steps, path: ['parallel', 'steps'] }];
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
if ('conditional' in step) {
|
|
29
|
+
return step.conditional.when.map((branch, branchIndex) => ({
|
|
30
|
+
steps: branch.steps,
|
|
31
|
+
path: ['conditional', 'when', branchIndex, 'steps'],
|
|
32
|
+
}));
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
if ('loop' in step) {
|
|
36
|
+
return [{ steps: step.loop.steps, path: ['loop', 'steps'] }];
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
return [];
|
|
40
|
+
};
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* List every task reference of a flow, depth first, in flow order.
|
|
44
|
+
*
|
|
45
|
+
* @param steps The flow, or a nested step list.
|
|
46
|
+
* @param basePath Path of `steps` inside the workflow definition.
|
|
47
|
+
*/
|
|
48
|
+
export const collectTaskReferences = (
|
|
49
|
+
steps: FlowStep[],
|
|
50
|
+
basePath: DefinitionPath = ['flow'],
|
|
51
|
+
): TaskReference[] =>
|
|
52
|
+
steps.flatMap((step, index) => {
|
|
53
|
+
const stepPath = [...basePath, index];
|
|
54
|
+
|
|
55
|
+
if ('do' in step) {
|
|
56
|
+
return [{ taskId: step.do, path: [...stepPath, 'do'] }];
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
return nestedStepLists(step).flatMap(({ steps: nested, path }) =>
|
|
60
|
+
collectTaskReferences(nested, [...stepPath, ...path]),
|
|
61
|
+
);
|
|
62
|
+
});
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Hexabot — Fair Core License (FCL-1.0-ALv2)
|
|
3
|
+
* Copyright (c) 2026 Hexastack.
|
|
4
|
+
* Full terms: see LICENSE.md.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { assertSnakeCaseName, isSnakeCaseName, toSnakeCase } from './naming';
|
|
8
|
+
|
|
9
|
+
describe('isSnakeCaseName', () => {
|
|
10
|
+
it.each(['send', 'send_email', 'step_2', 'v2_api'])('accepts %s', (name) => {
|
|
11
|
+
expect(isSnakeCaseName(name)).toBe(true);
|
|
12
|
+
});
|
|
13
|
+
|
|
14
|
+
it.each([
|
|
15
|
+
'',
|
|
16
|
+
'Send',
|
|
17
|
+
'send-email',
|
|
18
|
+
'send__email',
|
|
19
|
+
'_send',
|
|
20
|
+
'send_',
|
|
21
|
+
'send email',
|
|
22
|
+
])('refuses "%s"', (name) => {
|
|
23
|
+
expect(isSnakeCaseName(name)).toBe(false);
|
|
24
|
+
});
|
|
25
|
+
});
|
|
26
|
+
|
|
27
|
+
describe('assertSnakeCaseName', () => {
|
|
28
|
+
it('accepts a single word', () => {
|
|
29
|
+
expect(() => assertSnakeCaseName('send', 'action')).not.toThrow();
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
it('names the entity and the rule it breaks', () => {
|
|
33
|
+
expect(() => assertSnakeCaseName('sendEmail', 'action')).toThrow(
|
|
34
|
+
'action name must be snake_case (lowercase letters and digits separated by single underscores). Received: "sendEmail"',
|
|
35
|
+
);
|
|
36
|
+
});
|
|
37
|
+
});
|
|
38
|
+
|
|
39
|
+
describe('toSnakeCase', () => {
|
|
40
|
+
it.each([
|
|
41
|
+
['sendEmail', 'send_email'],
|
|
42
|
+
['Send Email!', 'send_email'],
|
|
43
|
+
[' --send--email-- ', 'send_email'],
|
|
44
|
+
['HTTPRequest2xx', 'httprequest2xx'],
|
|
45
|
+
['already_snake', 'already_snake'],
|
|
46
|
+
['', ''],
|
|
47
|
+
])('turns "%s" into "%s"', (input, expected) => {
|
|
48
|
+
expect(toSnakeCase(input)).toBe(expected);
|
|
49
|
+
});
|
|
50
|
+
});
|
package/src/utils/naming.ts
CHANGED
|
@@ -8,6 +8,15 @@ export const SNAKE_CASE_REGEX = /^[a-z0-9]+(?:_[a-z0-9]+)*$/;
|
|
|
8
8
|
|
|
9
9
|
export type WorkflowEntity = 'action' | 'workflow' | 'predicate';
|
|
10
10
|
|
|
11
|
+
/**
|
|
12
|
+
* Checks whether the provided string is snake_case compliant.
|
|
13
|
+
*
|
|
14
|
+
* @param value - Text to evaluate.
|
|
15
|
+
* @returns `true` when the value is snake_case; otherwise `false`.
|
|
16
|
+
*/
|
|
17
|
+
export const isSnakeCaseName = (value: string): boolean =>
|
|
18
|
+
SNAKE_CASE_REGEX.test(value);
|
|
19
|
+
|
|
11
20
|
/**
|
|
12
21
|
* Verifies that names follow the snake_case convention required by the system.
|
|
13
22
|
*
|
|
@@ -19,22 +28,13 @@ export function assertSnakeCaseName(
|
|
|
19
28
|
name: string,
|
|
20
29
|
entity: WorkflowEntity,
|
|
21
30
|
): void {
|
|
22
|
-
if (!
|
|
31
|
+
if (!isSnakeCaseName(name)) {
|
|
23
32
|
throw new Error(
|
|
24
|
-
`${entity} name must be snake_case
|
|
33
|
+
`${entity} name must be snake_case (lowercase letters and digits separated by single underscores). Received: "${name}"`,
|
|
25
34
|
);
|
|
26
35
|
}
|
|
27
36
|
}
|
|
28
37
|
|
|
29
|
-
/**
|
|
30
|
-
* Checks whether the provided string is snake_case compliant.
|
|
31
|
-
*
|
|
32
|
-
* @param value - Text to evaluate.
|
|
33
|
-
* @returns `true` when the value is snake_case; otherwise `false`.
|
|
34
|
-
*/
|
|
35
|
-
export const isSnakeCaseName = (value: string): boolean =>
|
|
36
|
-
SNAKE_CASE_REGEX.test(value);
|
|
37
|
-
|
|
38
38
|
/**
|
|
39
39
|
* Converts arbitrary text into snake_case for use in workflow entities.
|
|
40
40
|
*
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Hexabot — Fair Core License (FCL-1.0-ALv2)
|
|
3
|
+
* Copyright (c) 2026 Hexastack.
|
|
4
|
+
* Full terms: see LICENSE.md.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { getValueAtPath, setValueAtPath } from './object-path';
|
|
8
|
+
|
|
9
|
+
describe('getValueAtPath', () => {
|
|
10
|
+
const value = { flow: [{ do: 'first' }, { loop: { steps: ['x'] } }] };
|
|
11
|
+
|
|
12
|
+
it('reads nested object keys and array indexes', () => {
|
|
13
|
+
expect(getValueAtPath(value, ['flow', 1, 'loop', 'steps', 0])).toBe('x');
|
|
14
|
+
expect(getValueAtPath(value, [])).toBe(value);
|
|
15
|
+
});
|
|
16
|
+
|
|
17
|
+
it('reads nothing past null, undefined or a primitive', () => {
|
|
18
|
+
expect(getValueAtPath({ flow: null }, ['flow', 0])).toBeUndefined();
|
|
19
|
+
expect(getValueAtPath({}, ['flow', 0])).toBeUndefined();
|
|
20
|
+
expect(getValueAtPath({ name: 'run' }, ['name', 'length'])).toBeUndefined();
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
it('reads array items by number only', () => {
|
|
24
|
+
expect(getValueAtPath(value, ['flow', '0'])).toBeUndefined();
|
|
25
|
+
expect(getValueAtPath(value, ['flow', 'length'])).toBeUndefined();
|
|
26
|
+
});
|
|
27
|
+
|
|
28
|
+
it('reads object keys given as numbers', () => {
|
|
29
|
+
expect(getValueAtPath({ 1: 'one' }, [1])).toBe('one');
|
|
30
|
+
});
|
|
31
|
+
});
|
|
32
|
+
|
|
33
|
+
describe('setValueAtPath', () => {
|
|
34
|
+
it('copies every container on the path and leaves the input untouched', () => {
|
|
35
|
+
const value = { flow: [{ do: 'first' }, { do: 'second' }], outputs: {} };
|
|
36
|
+
const next = setValueAtPath(value, ['flow', 1, 'do'], 'renamed');
|
|
37
|
+
|
|
38
|
+
expect(next).toEqual({
|
|
39
|
+
flow: [{ do: 'first' }, { do: 'renamed' }],
|
|
40
|
+
outputs: {},
|
|
41
|
+
});
|
|
42
|
+
expect(value.flow[1].do).toBe('second');
|
|
43
|
+
expect(next.flow).not.toBe(value.flow);
|
|
44
|
+
expect(next.flow[0]).toBe(value.flow[0]);
|
|
45
|
+
expect(next.outputs).toBe(value.outputs);
|
|
46
|
+
});
|
|
47
|
+
|
|
48
|
+
it('replaces the whole value for an empty path', () => {
|
|
49
|
+
expect(setValueAtPath({ a: 1 }, [], 'next')).toBe('next');
|
|
50
|
+
});
|
|
51
|
+
|
|
52
|
+
it('sets a missing last key but creates no missing container', () => {
|
|
53
|
+
expect(setValueAtPath({}, ['defs'], { task: {} })).toEqual({
|
|
54
|
+
defs: { task: {} },
|
|
55
|
+
});
|
|
56
|
+
expect(setValueAtPath({}, ['defs', 'task'], { kind: 'task' })).toEqual({
|
|
57
|
+
defs: undefined,
|
|
58
|
+
});
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
it('returns the value as is when the path does not fit it', () => {
|
|
62
|
+
const list = ['a'];
|
|
63
|
+
|
|
64
|
+
expect(setValueAtPath(list, ['0'], 'b')).toBe(list);
|
|
65
|
+
expect(setValueAtPath('text', ['length'], 1)).toBe('text');
|
|
66
|
+
expect(setValueAtPath({ name: null }, ['name', 'first'], 'x')).toEqual({
|
|
67
|
+
name: null,
|
|
68
|
+
});
|
|
69
|
+
});
|
|
70
|
+
});
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Hexabot — Fair Core License (FCL-1.0-ALv2)
|
|
3
|
+
* Copyright (c) 2026 Hexastack.
|
|
4
|
+
* Full terms: see LICENSE.md.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Read a nested value. Array segments must be numbers; a path that leaves
|
|
9
|
+
* the value resolves to `undefined`.
|
|
10
|
+
*/
|
|
11
|
+
export const getValueAtPath = (
|
|
12
|
+
value: unknown,
|
|
13
|
+
path: ReadonlyArray<string | number>,
|
|
14
|
+
): unknown =>
|
|
15
|
+
path.reduce<unknown>((acc, key) => {
|
|
16
|
+
if (acc === null || acc === undefined) {
|
|
17
|
+
return undefined;
|
|
18
|
+
}
|
|
19
|
+
if (Array.isArray(acc)) {
|
|
20
|
+
return typeof key === 'number' ? acc[key] : undefined;
|
|
21
|
+
}
|
|
22
|
+
if (typeof acc === 'object') {
|
|
23
|
+
return (acc as Record<string, unknown>)[String(key)];
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
return undefined;
|
|
27
|
+
}, value);
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* Copy a value with one nested value replaced; the input is left untouched.
|
|
31
|
+
* A path that does not fit the value returns it as is.
|
|
32
|
+
*/
|
|
33
|
+
export const setValueAtPath = <T>(
|
|
34
|
+
value: T,
|
|
35
|
+
path: ReadonlyArray<string | number>,
|
|
36
|
+
nextValue: unknown,
|
|
37
|
+
): T => {
|
|
38
|
+
if (path.length === 0) {
|
|
39
|
+
return nextValue as T;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
const [key, ...rest] = path;
|
|
43
|
+
|
|
44
|
+
if (Array.isArray(value)) {
|
|
45
|
+
if (typeof key !== 'number') {
|
|
46
|
+
return value;
|
|
47
|
+
}
|
|
48
|
+
const nextArray = [...value];
|
|
49
|
+
|
|
50
|
+
nextArray[key] = setValueAtPath(value[key], rest, nextValue);
|
|
51
|
+
|
|
52
|
+
return nextArray as unknown as T;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
if (value && typeof value === 'object') {
|
|
56
|
+
return {
|
|
57
|
+
...(value as Record<string, unknown>),
|
|
58
|
+
[String(key)]: setValueAtPath(
|
|
59
|
+
(value as Record<string, unknown>)[String(key)],
|
|
60
|
+
rest,
|
|
61
|
+
nextValue,
|
|
62
|
+
),
|
|
63
|
+
} as T;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
return value;
|
|
67
|
+
};
|