@powerhousedao/reactor-workflow 6.2.3-dev.88 → 6.2.3-dev.89

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 CHANGED
@@ -324,7 +324,8 @@ action at another version is the same block.
324
324
  ### The core piece
325
325
 
326
326
  The engine's own blocks are the built-in piece `@powerhousedao/piece-core`, in
327
- `src/pieces/core/`. Its actions are `branch`, `assert`, `delay`,
327
+ `src/pieces/core/`. Its actions are `branch`, `router`, `loop` ("Loop on
328
+ items"), `assert`, `delay`,
328
329
  `approval` ("Request approval"), `stop` ("Stop run") and `waitForWebhook`
329
330
  ("Respond and wait for webhook"); its triggers are
330
331
  `manual`, `schedule` and `webhook`. It is written with `createPiece`,
@@ -341,6 +342,36 @@ The engine's own blocks are the built-in piece `@powerhousedao/piece-core`, in
341
342
  - `branch` and `assert` run through `ActivepiecesBlockExecutor` like any piece
342
343
  action, with the same resolution and journaling. `branch` leaves on `true`
343
344
  or `false` by its result.
345
+ - `router` is Activepieces' Router, first match wins. Its `branches` prop is a
346
+ list; each item has an optional `name` and one condition of the same shape
347
+ and semantics as `branch` (`left`, `operator`, `right`, `caseSensitive`).
348
+ Its ports follow its config: `branch_1` … `branch_N`, then `otherwise` when
349
+ no branch holds, and `error` (`stepPorts` and `routerPorts` in
350
+ `@powerhousedao/pieces-framework/workflow`; the editor labels them with the
351
+ branch names, else "Branch N", and "Otherwise"). It outputs
352
+ `{ branch, index }`: the matched branch's name and 1-based index, both
353
+ `null` for `otherwise`. Every branch resolves before any is tested, so a
354
+ missing reference fails the step unless that branch's operator is an
355
+ existence test. An operand of the wrong type fails it naming the branch.
356
+ - `loop` is Activepieces' Loop on Items. Its `items` must resolve to a list;
357
+ anything else fails the step. Its ports are `next`, `each` and `error`. Its
358
+ body is every step reachable from its `each` edges, and must be closed: a
359
+ body step reached from outside the body, or a body step with an edge back
360
+ to the loop, fails the run before any step runs, naming the step. The
361
+ coordinator runs the body once per item, in order,
362
+ each iteration from fresh records and edge decisions; body steps read
363
+ `{{steps.<loop>.output.item}}` and `.index` (from 1). Then the loop takes
364
+ `next` with the output `{ item, index, count, iterations }`, where
365
+ `iterations` is `[{ index, item, steps: { <key>: output } }]`, kept while
366
+ the row stays under 240 KiB of UTF-8 (`iterationsTruncated` past it), and
367
+ `item` and `index` are the last item's. The row is redacted with every body
368
+ step's connection secrets too. Zero items skip the body. After the loop each
369
+ body step's scope entry and record are its last iteration's. A body step
370
+ failing with no `error` edge fails the loop and the run. Loops nest. A
371
+ step that waits inside a body fails the run: `Step "<key>" cannot wait
372
+ inside a loop yet`. A core wait, or Call Flow with Wait for Response, is
373
+ refused before it runs; any other piece that pauses is refused after it
374
+ ran, so its side effects stand.
344
375
  - `delay` ("Delay for" an amount and unit, or "Delay until" a date) suspends
345
376
  the run on a `DELAY` waitpoint and outputs `{ resumedAt }`; a time already
346
377
  past does not wait. `approval` suspends it on a WEBHOOK waitpoint of kind
@@ -442,6 +473,23 @@ passes over the `steps` array in order until a pass changes nothing:
442
473
  - **Never reached.** A step in a cycle, or fed by an edge from a step that does
443
474
  not exist, is skipped when the run ends. So is every step not yet reached
444
475
  when a step fails with no `error` edge taken.
476
+ - **Loop bodies.** The steps a loop's `each` edges reach are left out of the
477
+ outer passes. The loop step walks them by the same rules once per item,
478
+ then decides its own edges on `next`. Each iteration journals its body
479
+ steps under the path `<loop>[<i>]/<step>` (nested loops concatenate,
480
+ `i` from 1); once a top-level loop ends, the loop's row, then each body
481
+ step's last-iteration row under its own id, follow (`step_execution` is
482
+ unique per `(run_id, step_path)`). Run detail reads the first 1000
483
+ iteration rows and the total; run listings read none. Resume carry reads
484
+ only the rows under a step's own id; a resume carries a finished loop
485
+ with its body.
486
+ - **Loop reruns.** A rerun runs every loop again, and replays its
487
+ iterations step by step from the rows under their paths. An iteration
488
+ replays only while its item, as the loop row journaled it, is unchanged;
489
+ a body step replays by the same rules as a top-level one (same key and
490
+ hash, SUCCEEDED or REPLAYED, a read re-runs). The loop row's config hash
491
+ covers its body's steps and edges, so a rewired body, or a loop row
492
+ truncated past the payload cap, runs every iteration again.
445
493
 
446
494
  Which port a step takes changes which steps run, never the order steps are
447
495
  reached in. The studio's step outline (`stepOutline` in the workflow editor)
@@ -872,6 +920,58 @@ step returns. Directories a crashed host left behind are swept at startup.
872
920
  after the same check.
873
921
  - **Time.** Staging and ingest count against the step's timeout.
874
922
 
923
+ ## Sub-flows
924
+
925
+ Activepieces' `@activepieces/piece-subflows` runs unmodified (the editor pins
926
+ `0.7.0` and lists its blocks under Core): the **Callable Flow** trigger
927
+ ("Callable workflow"), **Call Flow** ("Call workflow") and **Return Response**
928
+ ("Return response"). Stream CSV to Subflows is not offered.
929
+
930
+ - `ctx.flows.list` answers with the Callable Flow workflows of every drive
931
+ the calling workflow is in, itself included, that the reader may read: the
932
+ design-time caller, else the calling workflow's run user (with no run user,
933
+ none while auth enforcement is on). They come as Activepieces
934
+ `PopulatedFlow` records: `id` and `externalId` are the workflow id,
935
+ `status` is `ENABLED` only for an enabled, published workflow,
936
+ `version.displayName` is its name and `version.trigger.settings` is its
937
+ runnable trigger (`pieceName`, `pieceVersion`, `triggerName`, and its
938
+ config as `input`). A workflow in no drive can list only itself. Steps, trigger hooks (but `test` and `onDisable`)
939
+ and design-time options get it; `blockOptions` takes the edited
940
+ `workflowId` for the last.
941
+ - `ctx.server.apiUrl` is `http://reactor.invalid`, an origin that is never on
942
+ the network. The worker's global `fetch` hands a request to it to the host
943
+ over the call channel, so a sub-flow call needs no public URL, no egress
944
+ rule and no replica routing, and only a run of this reactor can make one.
945
+ Another HTTP client fails to resolve it. `publicUrl` is the origin of
946
+ `waitpointBaseUrl` when there is one; `server.token` throws.
947
+ - The host origin serves `POST /v1/webhooks/<workflowId>` (Call Flow) and
948
+ `POST /v1/waitpoints/<token>` (Return Response); anything else is 404. A
949
+ call is refused unless the target is listed for the caller (404) and is
950
+ enabled with the Callable Flow trigger (409), or when its
951
+ `ap-parent-run-id` names another run (403). It goes through the trigger's
952
+ `run` hook and journals the callee's run, answering `{ runId }`.
953
+ - Call Flow's callback is a resume URL on the host origin, minted without
954
+ `waitpointBaseUrl`, so Return Response resumes the caller in process. A
955
+ callback on `waitpointBaseUrl` this host minted is mapped to the host
956
+ origin too. A response no pending waitpoint takes
957
+ answers `{ status: "gone", discarded: true }` and Return Response fails.
958
+ Switchboard's public resume route adds `discarded` to its JSON answers too.
959
+ - The callee's run records its caller (`parent_run_id`) and, when the caller
960
+ asked to fail on failure (Wait for Response), the waitpoint it waits on
961
+ (`parent_waitpoint_id`). A callee that ends `FAILED`, `CANCELLED` or
962
+ `INDETERMINATE` resolves that waitpoint with
963
+ `{ status: "error", data: { message, runId } }`, so Call Flow throws and the
964
+ caller fails. A callee that succeeds without Return Response leaves the
965
+ caller waiting until its waitpoint expires, as upstream.
966
+ - A Callable Flow trigger arms without a public webhook endpoint and is never
967
+ polled. Its workflow's public webhook URL answers 401: it is called only by
968
+ runs of this reactor.
969
+ - A trigger's `onStart` runs once per run, before its first step, with the
970
+ run's id as `ctx.run.id` and the trigger item as `payload`; it fails the run
971
+ when it throws. A rerun or a resumed leg does not run it, so a rerun called
972
+ run answers no caller. A trigger without one, or with `createTrigger`'s no-op
973
+ default, is not called.
974
+
875
975
  ## Known missing features
876
976
 
877
977
  This is what a piece can declare or call that this engine does not run. It is tracked in
@@ -913,7 +1013,8 @@ releases what an earlier enable registered. The reason reads
913
1013
  either fails or fires a spurious run (#3090).
914
1014
  - `setSchedule({ cronExpression })` is run as a fixed interval; wall-clock
915
1015
  time and timezone are lost.
916
- - `onStart` is never called. The trigger context's `server` is a throwing stub.
1016
+ - A trigger hook's `server` is the host origin (see Sub-flows), except in
1017
+ `test` and `onDisable`, where it throws.
917
1018
  - Outside a delivery a hook's `payload` is `undefined`; upstream passes `{}`
918
1019
  (#3090).
919
1020
  - A webhook payload carries no raw body, and its signature headers
@@ -997,7 +1098,7 @@ releases what an earlier enable registered. The reason reads
997
1098
  operations. This is not the reactor's own rebuild (keyframes, upgrade
998
1099
  transitions); when the result does not hash to the pin, the leg fails.
999
1100
  - A WEBHOOK waitpoint needs the host's `waitpointBaseUrl`; without it
1000
- `createWaitpoint({ type: "WEBHOOK" })` throws.
1101
+ `createWaitpoint({ type: "WEBHOOK" })` throws, except in Call Flow.
1001
1102
  - A resumed run reads steps journaled before it waited from the journal: a
1002
1103
  truncated or redacted output is unavailable to later steps, and a document
1003
1104
  output is its reference, not the document.
@@ -1025,7 +1126,9 @@ releases what an earlier enable registered. The reason reads
1025
1126
  - The deprecated `generateResumeUrl` links to the waitpoint the step's
1026
1127
  deprecated `run.pause` creates (one link per step). A step that pauses some
1027
1128
  other way, or that already made a waitpoint, leaves that link dead.
1028
- - `connections.get`, `tags`, `server`, `agent` and `flows.list` throw.
1129
+ - `connections.get`, `tags`, `agent` and `server.token` throw. `server` and
1130
+ `flows.list` are served as described in Sub-flows; a single-step test gets
1131
+ neither.
1029
1132
  - `ctx.store` checks the key length on `put` only; `get` and `delete` of an
1030
1133
  over-long key answer as if it were absent.
1031
1134
  - `flows.current.version.id` is a constant. `project.id` is `reactor` on
@@ -1085,7 +1188,7 @@ A case this engine is known to fail runs as `it.fails` and names the issue that
1085
1188
  fixes it; never edit those files by hand. To regenerate them:
1086
1189
 
1087
1190
  ```sh
1088
- pnpm --filter @powerhousedao/pieces-framework sync-upstream -- --tag 0.92.3 --from <activepieces checkout>
1191
+ pnpm --filter @powerhousedao/pieces-framework sync-upstream -- --tag d078d47750b53c13b837b2bec86b0402b4bff94f --from <activepieces checkout>
1089
1192
  ```
1090
1193
 
1091
1194
  ## Design documents
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { C as PropertySettingDef, E as ReactorTap, F as BlockMatch, I as BlockResolution, L as PieceOrigin, M as EgressPolicy, T as WorkflowRunResult, b as WorkflowTelemetry, f as SecretStat, g as ModelManifestSource, h as IPieceWorker, i as ReplayedStep, k as PieceResolver, l as ConnectionRequest, n as packagePieces, p as SecretStore, r as CORE_PIECE_NAME, s as AttachmentPort, t as PieceRegistry, v as PieceWorkerResult, w as StepExecutionRecord, x as WorkflowTelemetryOptions, y as TELEMETRY_SCOPE } from "./piece-registry-C1Pc0hD6.js";
1
+ import { A as PieceResolver, C as FlowsPort, D as ReactorTap, E as WorkflowRunResult, I as BlockMatch, L as BlockResolution, N as EgressPolicy, R as PieceOrigin, T as StepExecutionRecord, b as WorkflowTelemetry, f as SecretStat, g as ModelManifestSource, h as IPieceWorker, i as ReplayedStep, l as ConnectionRequest, n as packagePieces, p as SecretStore, r as CORE_PIECE_NAME, s as AttachmentPort, t as PieceRegistry, v as PieceWorkerResult, w as PropertySettingDef, x as WorkflowTelemetryOptions, y as TELEMETRY_SCOPE } from "./piece-registry-dvS95c3E.js";
2
2
  import { ActionBase, IndexQueryRequest, IndexQueryResult, TriggerBase } from "@powerhousedao/pieces-framework";
3
3
  import { ILogger, OperationWithContext } from "document-model";
4
4
  import "@powerhousedao/pieces-framework/workflow";
@@ -18932,6 +18932,7 @@ interface StepExecutionRow {
18932
18932
  run_id: string;
18933
18933
  ordinal: number;
18934
18934
  step_id: string;
18935
+ step_path: string;
18935
18936
  step_key: string;
18936
18937
  piece_name: string;
18937
18938
  block_name: string;
@@ -19044,6 +19045,8 @@ interface WorkflowRuntimeDB {
19044
19045
  definition_op_index: NullableColumn<number>;
19045
19046
  definition_scope_hash: NullableColumn<string>;
19046
19047
  waiting_on: NullableColumn<string>;
19048
+ parent_run_id: NullableColumn<string>;
19049
+ parent_waitpoint_id: NullableColumn<string>;
19047
19050
  };
19048
19051
  waitpoint: WaitpointRow;
19049
19052
  step_execution: StepExecutionRow;
@@ -19091,6 +19094,11 @@ interface EnqueueRunOptions {
19091
19094
  workflowId: string;
19092
19095
  triggerKind: string;
19093
19096
  triggerPayload?: unknown;
19097
+ parent?: RunParent;
19098
+ }
19099
+ interface RunParent {
19100
+ runId: string;
19101
+ waitpointId: string | null;
19094
19102
  }
19095
19103
  interface StartRunOptions {
19096
19104
  workflowId: string;
@@ -19104,6 +19112,7 @@ declare class WorkflowRunStore {
19104
19112
  private readonly db;
19105
19113
  private readonly unmigrated;
19106
19114
  private readonly runsInFlight;
19115
+ orphanedRunIds: string[];
19107
19116
  private readonly journaledSteps;
19108
19117
  private readonly pausingRuns;
19109
19118
  private readonly resumedLegs;
@@ -19199,6 +19208,7 @@ declare class WorkflowRunStore {
19199
19208
  attempts: number;
19200
19209
  }): Promise<string>;
19201
19210
  private insertPendingRun;
19211
+ getRunParent(runId: string): Promise<RunParent | undefined>;
19202
19212
  beginRun(runId: string, details: {
19203
19213
  workflowName: string;
19204
19214
  workflowVersion: number;
@@ -19215,7 +19225,11 @@ declare class WorkflowRunStore {
19215
19225
  failRun(runId: string, error: string, errorName?: string): Promise<string[]>;
19216
19226
  listRuns(workflowId?: string | string[], limit?: number, options?: ListRunsOptions): Promise<RunRow[]>;
19217
19227
  getRun(id: string): Promise<RunRow | undefined>;
19218
- getSteps(runId: string): Promise<StepExecutionRow[]>;
19228
+ getSteps(runId: string, options?: {
19229
+ withIterations?: boolean;
19230
+ iterationLimit?: number;
19231
+ }): Promise<StepExecutionRow[]>;
19232
+ countIterations(runId: string): Promise<number>;
19219
19233
  getStepsForRuns(runIds: string[], options?: {
19220
19234
  withData?: boolean;
19221
19235
  }): Promise<Map<string, StepExecutionRow[]>>;
@@ -19298,6 +19312,26 @@ declare class WorkflowRunStore {
19298
19312
  deletePieceStore(scope: string, scopeKey: string): Promise<void>;
19299
19313
  }
19300
19314
  //#endregion
19315
+ //#region src/reactor/subflows.d.ts
19316
+ interface PopulatedFlow {
19317
+ id: string;
19318
+ externalId: string;
19319
+ status: "ENABLED" | "DISABLED";
19320
+ version: {
19321
+ id: string;
19322
+ displayName: string;
19323
+ trigger: {
19324
+ type: "PIECE_TRIGGER" | "EMPTY";
19325
+ settings: {
19326
+ pieceName?: string;
19327
+ pieceVersion?: string;
19328
+ triggerName?: string;
19329
+ input: Record<string, unknown>;
19330
+ };
19331
+ };
19332
+ };
19333
+ }
19334
+ //#endregion
19301
19335
  //#region src/reactor/park-state.d.ts
19302
19336
  declare class ParkState {
19303
19337
  private readonly load;
@@ -19357,6 +19391,7 @@ interface TriggerSupervisorOptions {
19357
19391
  defaultIntervalMs?: number;
19358
19392
  hookTimeoutMs?: number;
19359
19393
  webhookUrlFor?: (workflowId: string) => Promise<string | undefined>;
19394
+ flowsFor?: (workflowId: string, runId?: string) => FlowsPort | undefined;
19360
19395
  reconcileIntervalMs?: number;
19361
19396
  now?: () => Date;
19362
19397
  }
@@ -19421,7 +19456,9 @@ declare class TriggerSupervisor {
19421
19456
  }): Promise<unknown>;
19422
19457
  private dropTestPartitions;
19423
19458
  handshake(binding: PieceTriggerBinding, payload: unknown): Promise<PieceWorkerResult>;
19424
- deliverWebhook(workflowId: string, payload: unknown): Promise<void>;
19459
+ deliverWebhook(workflowId: string, payload: unknown, parent?: RunParent): Promise<string[]>;
19460
+ pieceBinding(workflowId: string): PieceTriggerBinding | undefined;
19461
+ onStart(binding: PieceTriggerBinding, runId: string, payload: unknown): Promise<PieceWorkerResult>;
19425
19462
  private cursorRewind;
19426
19463
  private hook;
19427
19464
  private reactorFor;
@@ -19546,6 +19583,7 @@ type PersistedRunResult = WorkflowRunResult & {
19546
19583
  };
19547
19584
  type RunResume = {
19548
19585
  completedSteps: Map<string, ReplayedStep>;
19586
+ loopItems: Map<string, unknown[]>;
19549
19587
  rerunOf: string;
19550
19588
  };
19551
19589
  interface ConnectionSummary {
@@ -19561,10 +19599,10 @@ interface ConnectionCheckResult {
19561
19599
  detail: string | null;
19562
19600
  accountLabel: string | null;
19563
19601
  }
19564
- /** A journal row with the steps that belong to it, as the subgraph serves it. */
19565
19602
  interface RunRecord {
19566
19603
  row: RunRow;
19567
19604
  steps: StepExecutionRow[];
19605
+ iterationsTotal?: number;
19568
19606
  }
19569
19607
  interface RunsArgs {
19570
19608
  workflowId?: string;
@@ -19814,6 +19852,7 @@ export declare class WorkflowRuntimeService {
19814
19852
  private pieceDescriptor;
19815
19853
  private describe;
19816
19854
  driveWorkflowIds(driveId: string, ctx?: WorkflowCaller): Promise<string[]>;
19855
+ private workflowNodeIds;
19817
19856
  runs(args: RunsArgs, ctx?: WorkflowCaller): Promise<RunRecord[]>;
19818
19857
  runsPage(args: RunsPageArgs, ctx?: WorkflowCaller): Promise<RunPage>;
19819
19858
  private listRunsPage;
@@ -19858,7 +19897,7 @@ export declare class WorkflowRuntimeService {
19858
19897
  private assertCanReadDocument;
19859
19898
  private assertCanReadWorkflow;
19860
19899
  private assertCanWriteDocument;
19861
- blockOptions(block: BlockRef, propName: string, input?: unknown, connectionId?: string, ctx?: WorkflowCaller, searchValue?: string, reactorConnectionId?: string): Promise<unknown>;
19900
+ blockOptions(block: BlockRef, propName: string, input?: unknown, connectionId?: string, ctx?: WorkflowCaller, searchValue?: string, reactorConnectionId?: string, editedWorkflowId?: string): Promise<unknown>;
19862
19901
  blockOutputTree(block: BlockRef, config?: unknown): Promise<OutputTree>;
19863
19902
  private stateFields;
19864
19903
  private operationInputFields;
@@ -19932,6 +19971,22 @@ export declare class WorkflowRuntimeService {
19932
19971
  private applyFailureMode;
19933
19972
  rerun(runId: string, ctx?: WorkflowCaller): Promise<PersistedRunResult>;
19934
19973
  private rereads;
19974
+ private flowsPort;
19975
+ private resumeBaseUrl;
19976
+ private drivesOf;
19977
+ private callableWorkflowIds;
19978
+ private callableFlow;
19979
+ /** `ctx.flows.list`, as Activepieces' PopulatedFlow records: the Callable
19980
+ * Flow workflows the caller (else the calling workflow's run user) reads. */
19981
+ listFlows(workflowId: string, externalIds?: string[], ctx?: WorkflowCaller): Promise<{
19982
+ data: PopulatedFlow[];
19983
+ }>;
19984
+ private flowReader;
19985
+ private hostRequest;
19986
+ private flowCallableFrom;
19987
+ private dispatchSubflow;
19988
+ private startPieceTrigger;
19989
+ private endSubflow;
19935
19990
  private readonly resuming;
19936
19991
  private readonly definitionHashes;
19937
19992
  /** Our hash of the runnable definition: computed once per published version. */