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

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)
@@ -727,9 +775,12 @@ therefore checks the value it is about to return at any depth, and
727
775
  the piece.
728
776
 
729
777
  **The secrets key is not optional in production.** Unset, `loadKey` generates
730
- `./.ph/secrets.key` — relative to the working directory, like the bundle cache
731
- and the attachment staging dir. A host whose working directory does not survive
732
- a restart would come back with a new key, so the store guards against it:
778
+ `.ph/secrets.key` in the same `.ph` tree as the bundle cache and the attachment
779
+ folders: the working directory's, or the one `PH_USER_DATA_DIR` moves it to. A
780
+ tree with no key takes a copy of one left in the working directory, as a
781
+ desktop shell's stores from before it moved are encrypted with that. A host
782
+ whose tree does not survive a restart would come back with a new key, so the
783
+ store guards against it:
733
784
 
734
785
  - A host passes `secretsKeyFile: false` when its database outlives the working
735
786
  directory, and the store then requires `PH_WORKFLOWS_SECRETS_MASTER_KEY`
@@ -872,6 +923,58 @@ step returns. Directories a crashed host left behind are swept at startup.
872
923
  after the same check.
873
924
  - **Time.** Staging and ingest count against the step's timeout.
874
925
 
926
+ ## Sub-flows
927
+
928
+ Activepieces' `@activepieces/piece-subflows` runs unmodified (the editor pins
929
+ `0.7.0` and lists its blocks under Core): the **Callable Flow** trigger
930
+ ("Callable workflow"), **Call Flow** ("Call workflow") and **Return Response**
931
+ ("Return response"). Stream CSV to Subflows is not offered.
932
+
933
+ - `ctx.flows.list` answers with the Callable Flow workflows of every drive
934
+ the calling workflow is in, itself included, that the reader may read: the
935
+ design-time caller, else the calling workflow's run user (with no run user,
936
+ none while auth enforcement is on). They come as Activepieces
937
+ `PopulatedFlow` records: `id` and `externalId` are the workflow id,
938
+ `status` is `ENABLED` only for an enabled, published workflow,
939
+ `version.displayName` is its name and `version.trigger.settings` is its
940
+ runnable trigger (`pieceName`, `pieceVersion`, `triggerName`, and its
941
+ config as `input`). A workflow in no drive can list only itself. Steps, trigger hooks (but `test` and `onDisable`)
942
+ and design-time options get it; `blockOptions` takes the edited
943
+ `workflowId` for the last.
944
+ - `ctx.server.apiUrl` is `http://reactor.invalid`, an origin that is never on
945
+ the network. The worker's global `fetch` hands a request to it to the host
946
+ over the call channel, so a sub-flow call needs no public URL, no egress
947
+ rule and no replica routing, and only a run of this reactor can make one.
948
+ Another HTTP client fails to resolve it. `publicUrl` is the origin of
949
+ `waitpointBaseUrl` when there is one; `server.token` throws.
950
+ - The host origin serves `POST /v1/webhooks/<workflowId>` (Call Flow) and
951
+ `POST /v1/waitpoints/<token>` (Return Response); anything else is 404. A
952
+ call is refused unless the target is listed for the caller (404) and is
953
+ enabled with the Callable Flow trigger (409), or when its
954
+ `ap-parent-run-id` names another run (403). It goes through the trigger's
955
+ `run` hook and journals the callee's run, answering `{ runId }`.
956
+ - Call Flow's callback is a resume URL on the host origin, minted without
957
+ `waitpointBaseUrl`, so Return Response resumes the caller in process. A
958
+ callback on `waitpointBaseUrl` this host minted is mapped to the host
959
+ origin too. A response no pending waitpoint takes
960
+ answers `{ status: "gone", discarded: true }` and Return Response fails.
961
+ Switchboard's public resume route adds `discarded` to its JSON answers too.
962
+ - The callee's run records its caller (`parent_run_id`) and, when the caller
963
+ asked to fail on failure (Wait for Response), the waitpoint it waits on
964
+ (`parent_waitpoint_id`). A callee that ends `FAILED`, `CANCELLED` or
965
+ `INDETERMINATE` resolves that waitpoint with
966
+ `{ status: "error", data: { message, runId } }`, so Call Flow throws and the
967
+ caller fails. A callee that succeeds without Return Response leaves the
968
+ caller waiting until its waitpoint expires, as upstream.
969
+ - A Callable Flow trigger arms without a public webhook endpoint and is never
970
+ polled. Its workflow's public webhook URL answers 401: it is called only by
971
+ runs of this reactor.
972
+ - A trigger's `onStart` runs once per run, before its first step, with the
973
+ run's id as `ctx.run.id` and the trigger item as `payload`; it fails the run
974
+ when it throws. A rerun or a resumed leg does not run it, so a rerun called
975
+ run answers no caller. A trigger without one, or with `createTrigger`'s no-op
976
+ default, is not called.
977
+
875
978
  ## Known missing features
876
979
 
877
980
  This is what a piece can declare or call that this engine does not run. It is tracked in
@@ -913,7 +1016,8 @@ releases what an earlier enable registered. The reason reads
913
1016
  either fails or fires a spurious run (#3090).
914
1017
  - `setSchedule({ cronExpression })` is run as a fixed interval; wall-clock
915
1018
  time and timezone are lost.
916
- - `onStart` is never called. The trigger context's `server` is a throwing stub.
1019
+ - A trigger hook's `server` is the host origin (see Sub-flows), except in
1020
+ `test` and `onDisable`, where it throws.
917
1021
  - Outside a delivery a hook's `payload` is `undefined`; upstream passes `{}`
918
1022
  (#3090).
919
1023
  - A webhook payload carries no raw body, and its signature headers
@@ -997,7 +1101,7 @@ releases what an earlier enable registered. The reason reads
997
1101
  operations. This is not the reactor's own rebuild (keyframes, upgrade
998
1102
  transitions); when the result does not hash to the pin, the leg fails.
999
1103
  - A WEBHOOK waitpoint needs the host's `waitpointBaseUrl`; without it
1000
- `createWaitpoint({ type: "WEBHOOK" })` throws.
1104
+ `createWaitpoint({ type: "WEBHOOK" })` throws, except in Call Flow.
1001
1105
  - A resumed run reads steps journaled before it waited from the journal: a
1002
1106
  truncated or redacted output is unavailable to later steps, and a document
1003
1107
  output is its reference, not the document.
@@ -1025,7 +1129,9 @@ releases what an earlier enable registered. The reason reads
1025
1129
  - The deprecated `generateResumeUrl` links to the waitpoint the step's
1026
1130
  deprecated `run.pause` creates (one link per step). A step that pauses some
1027
1131
  other way, or that already made a waitpoint, leaves that link dead.
1028
- - `connections.get`, `tags`, `server`, `agent` and `flows.list` throw.
1132
+ - `connections.get`, `tags`, `agent` and `server.token` throw. `server` and
1133
+ `flows.list` are served as described in Sub-flows; a single-step test gets
1134
+ neither.
1029
1135
  - `ctx.store` checks the key length on `put` only; `get` and `delete` of an
1030
1136
  over-long key answer as if it were absent.
1031
1137
  - `flows.current.version.id` is a constant. `project.id` is `reactor` on
@@ -1085,7 +1191,7 @@ A case this engine is known to fail runs as `it.fails` and names the issue that
1085
1191
  fixes it; never edit those files by hand. To regenerate them:
1086
1192
 
1087
1193
  ```sh
1088
- pnpm --filter @powerhousedao/pieces-framework sync-upstream -- --tag 0.92.3 --from <activepieces checkout>
1194
+ pnpm --filter @powerhousedao/pieces-framework sync-upstream -- --tag d078d47750b53c13b837b2bec86b0402b4bff94f --from <activepieces checkout>
1089
1195
  ```
1090
1196
 
1091
1197
  ## 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;
@@ -19877,6 +19916,7 @@ export declare class WorkflowRuntimeService {
19877
19916
  fire(workflowId: string, triggerPayload?: unknown, triggerKind?: string, resume?: RunResume, ctx?: WorkflowCaller, enqueuedRunId?: string): Promise<PersistedRunResult>;
19878
19917
  private runFired;
19879
19918
  private executeLeg;
19919
+ private journalFinish;
19880
19920
  private endUnheldWait;
19881
19921
  private readonly runGate;
19882
19922
  private readonly unsettledFirings;
@@ -19932,6 +19972,22 @@ export declare class WorkflowRuntimeService {
19932
19972
  private applyFailureMode;
19933
19973
  rerun(runId: string, ctx?: WorkflowCaller): Promise<PersistedRunResult>;
19934
19974
  private rereads;
19975
+ private flowsPort;
19976
+ private resumeBaseUrl;
19977
+ private drivesOf;
19978
+ private callableWorkflowIds;
19979
+ private callableFlow;
19980
+ /** `ctx.flows.list`, as Activepieces' PopulatedFlow records: the Callable
19981
+ * Flow workflows the caller (else the calling workflow's run user) reads. */
19982
+ listFlows(workflowId: string, externalIds?: string[], ctx?: WorkflowCaller): Promise<{
19983
+ data: PopulatedFlow[];
19984
+ }>;
19985
+ private flowReader;
19986
+ private hostRequest;
19987
+ private flowCallableFrom;
19988
+ private dispatchSubflow;
19989
+ private startPieceTrigger;
19990
+ private endSubflow;
19935
19991
  private readonly resuming;
19936
19992
  private readonly definitionHashes;
19937
19993
  /** Our hash of the runnable definition: computed once per published version. */
@@ -20099,6 +20155,12 @@ interface AcquireSingletonOptions {
20099
20155
  * is only logged.
20100
20156
  */
20101
20157
  selfFence?: boolean;
20158
+ /**
20159
+ * The journal is embedded and this process has it open, so nobody else can
20160
+ * be alive behind the lease: a restart takes back its own at once. Waiting
20161
+ * for the heartbeat to go stale is for a holder that might still be running.
20162
+ */
20163
+ exclusive?: boolean;
20102
20164
  env?: Record<string, string | undefined>;
20103
20165
  }
20104
20166
  /**