feat(workflow-executor): workflow executor package (rebased)

.github/workflows/build.yml

@@ -80,6 +80,7 @@ jobs:
           - plugin-aws-s3
           - plugin-export-advanced
           - plugin-flattener
+          - workflow-executor
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4

CLAUDE.md

@@ -104,6 +104,11 @@ yarn workspace @forestadmin/agent test
 5. Are edge cases handled?
 6. Is the naming clear and consistent?
 
+## Git Workflow
+
+The **main working branch** for workflow-executor development is `feat/prd-214-setup-workflow-executor-package`.
+All feature branches for this area should be based on and PRs targeted at this branch (not `main`).
+
 ## Linear Tickets
 
 ### MCP Setup

WORKFLOW-EXECUTOR-CONTRACT.md

@@ -0,0 +1,285 @@
+# Workflow Executor — Contract Types
+
+> Types exchanged between the **orchestrator (server)**, the **executor (agent-nodejs)**, and the **frontend**.
+> Last updated: 2026-03-26
+
+---
+
+## 1. Polling
+
+**`GET /liana/v1/workflow-step-executions/pending?runId=<runId>`**
+
+The executor polls for the current pending step of a run. The server must return **one object** (not an array), or `null` if the run is not found.
+
+```typescript
+interface StepUser {
+  id:              number;
+  email:           string;
+  firstName:       string;
+  lastName:        string;
+  team:            string;
+  renderingId:     number;
+  role:            string;
+  permissionLevel: string;
+  tags:            Record<string, string>;
+}
+
+interface PendingStepExecution {
+  runId:          string;
+  stepId:         string;
+  stepIndex:      number;
+  baseRecordRef:  RecordRef;
+  stepDefinition: StepDefinition;
+  previousSteps:  Step[];
+  user:           StepUser;  // identity of the user who initiated the step
+}
+```
+
+> **`null` response** → executor throws `RunNotFoundError` → HTTP 404 returned to caller.
+
+### CollectionSchema
+
+Schema of a collection, returned by the orchestrator via `GET /liana/v1/collections/:collectionName`. Used by the executor to resolve primary keys and action endpoints.
+
+```typescript
+interface CollectionSchema {
+  collectionName:        string;
+  collectionDisplayName: string;
+  primaryKeyFields:      string[];
+  fields:                FieldSchema[];
+  actions:               ActionSchema[];
+}
+
+interface FieldSchema {
+  fieldName:              string;
+  displayName:            string;
+  isRelationship:         boolean;
+  relationType?:          "BelongsTo" | "HasMany" | "HasOne";
+  relatedCollectionName?: string;
+}
+
+interface ActionSchema {
+  name:        string;
+  displayName: string;
+  endpoint:    string;  // route path used by the agent to execute the action
+}
+```
+
+### RecordRef
+
+Lightweight pointer to a specific record.
+
+```typescript
+interface RecordRef {
+  collectionName: string;
+  recordId:       Array<string | number>;
+  stepIndex:      number; // index of the workflow step that loaded this record
+}
+```
+
+### Step
+
+History entry for an already-executed step (used in `previousSteps`).
+
+```typescript
+interface Step {
+  stepDefinition: StepDefinition;
+  stepOutcome:    StepOutcome;
+}
+```
+
+### StepDefinition
+
+Discriminated union on `type`.
+
+```typescript
+type StepDefinition =
+  | ConditionStepDefinition
+  | RecordTaskStepDefinition
+  | McpTaskStepDefinition;
+
+interface ConditionStepDefinition {
+  type:          "condition";
+  options:       [string, ...string[]]; // at least one option required
+  prompt?:       string;
+  aiConfigName?: string;
+}
+
+interface RecordTaskStepDefinition {
+  type:                "read-record"
+                     | "update-record"
+                     | "trigger-action"
+                     | "load-related-record";
+  prompt?:             string;
+  aiConfigName?:       string;
+  automaticExecution?: boolean;
+}
+
+interface McpTaskStepDefinition {
+  type:                "mcp-task";
+  mcpServerId?:        string;
+  prompt?:             string;
+  aiConfigName?:       string;
+  automaticExecution?: boolean;
+}
+```
+
+### StepOutcome
+
+What the executor previously reported for each past step (used in `previousSteps`).
+
+```typescript
+type StepOutcome =
+  | ConditionStepOutcome
+  | RecordTaskStepOutcome
+  | McpTaskStepOutcome;
+
+interface ConditionStepOutcome {
+  type:            "condition";
+  stepId:          string;
+  stepIndex:       number;
+  status:          "success" | "error";
+  selectedOption?: string; // present when status = "success"
+  error?:          string; // present when status = "error"
+}
+
+interface RecordTaskStepOutcome {
+  type:      "record-task";
+  stepId:    string;
+  stepIndex: number;
+  status:    "success" | "error" | "awaiting-input";
+  error?:    string; // present when status = "error"
+}
+
+interface McpTaskStepOutcome {
+  type:      "mcp-task";
+  stepId:    string;
+  stepIndex: number;
+  status:    "success" | "error" | "awaiting-input";
+  error?:    string; // present when status = "error"
+}
+```
+
+---
+
+## 2. Step Result
+
+**`POST /liana/v1/workflow-step-executions/<runId>/complete`**
+
+After executing a step, the executor posts the outcome back to the server. The body is one of the `StepOutcome` shapes above.
+
+> **NEVER contains client data** (field values, AI reasoning, etc.) — those stay in the `RunStore` on the client side.
+
+---
+
+## 3. Pending Data
+
+Steps that require user input pause with `status: "awaiting-input"`. The executor writes its AI-selected data to `pendingData` in the RunStore. The frontend can then override fields and confirm via the pending-data endpoint.
+
+**`PATCH /runs/:runId/steps/:stepIndex/pending-data`**
+
+The frontend writes user overrides + confirmation to the executor HTTP server. Request bodies are validated per step type with strict Zod schemas — unknown fields are rejected with `400`.
+
+Once written, the frontend calls `POST /runs/:runId/trigger`. On the next execution, the executor reads `pendingData` from the RunStore and checks `userConfirmed`:
+- `undefined` → returns `awaiting-input` again (the step is not yet actionable)
+- `true` → execute the confirmed action
+- `false` → skip the step (mark as success)
+
+### update-record — user picks a field + value to write
+
+The executor writes the AI's field selection to `pendingData`. The frontend can override `value` and confirm.
+
+Stored in RunStore:
+```typescript
+interface UpdateRecordPendingData {
+  name:            string;  // technical field name (set by executor)
+  displayName:     string;  // label shown in the UI (set by executor)
+  value:           string;  // AI-proposed value; overridable by frontend
+  userConfirmed?:  boolean; // set by frontend via PATCH
+}
+```
+
+PATCH request body:
+```typescript
+{
+  userConfirmed: boolean;
+  value?:        string;  // optional override of AI-proposed value
+}
+```
+
+### trigger-action & mcp-task — user confirmation only
+
+The executor selects the action (or MCP tool) and writes `pendingData` to the RunStore. The frontend cannot override any executor-selected data — it only confirms or rejects.
+
+PATCH request body (same for both types):
+```typescript
+{
+  userConfirmed: boolean;
+}
+```
+
+### load-related-record — user picks the relation and/or the record
+
+The executor writes the AI's relation selection to `pendingData`. The frontend can override the relation, the selected record, or both.
+
+Stored in RunStore:
+```typescript
+interface LoadRelatedRecordPendingData {
+  name:             string;               // technical relation name
+  displayName:      string;               // label shown in the UI
+  suggestedFields?: string[];             // fields suggested for display (set by executor)
+  selectedRecordId: Array<string|number>; // AI's pick; overridable by frontend
+  userConfirmed?:   boolean;              // set by frontend via PATCH
+}
+```
+
+> `relatedCollectionName` is **not** stored in `pendingData` — the executor re-derives it from the `FieldSchema` at execution time using the (possibly overridden) relation `name`.
+
+PATCH request body:
+```typescript
+{
+  userConfirmed:    boolean;
+  name?:            string;                // override relation
+  displayName?:     string;                // override relation label
+  selectedRecordId?: Array<string|number>; // override selected record (min 1 element)
+}
+```
+
+### Responses
+
+| Status | Meaning |
+|---|---|
+| `204 No Content` | Pending data updated successfully |
+| `400` | Invalid body — type mismatch, unknown fields, or empty `selectedRecordId` |
+| `404` | Step not found, no `pendingData`, or step type does not support confirmation |
+
+---
+
+## Flow Summary
+
+```
+Orchestrator ──► GET pending?runId=X ──► Executor
+                                            │
+                                      executes step
+                                            │
+                            ┌───────────────┴───────────────┐
+                       needs input                      done
+                            │                              │
+                   status: awaiting-input          POST /complete
+                            │                         (StepOutcome)
+                            │
+              Executor writes pendingData
+              to RunStore (AI selection)
+                            │
+               Frontend reads pendingData
+              via GET /runs/:runId
+                            │
+              Frontend overrides + confirms
+              PATCH /runs/:runId/steps/:stepIndex/pending-data
+              { userConfirmed: true/false }  →  204
+                            │
+                  POST /runs/:runId/trigger
+                            │
+                      Executor resumes
+              (reads userConfirmed from pendingData)
+```

package.json

@@ -32,7 +32,7 @@
     "semantic-release-slack-bot": "^4.0.2",
     "ts-jest": "^29.0.4",
     "ts-node": "^10.9.1",
-    "typedoc": "^0.28.15",
+    "typedoc": "^0.28.18",
     "typescript": "^5.6.3"
   },
   "scripts": {
@@ -53,15 +53,12 @@
     "packages/*"
   ],
   "resolutions": {
-    "tar": "^7.5.8",
+    "tar": ">=7.5.11",
     "lerna/**/glob": ">=10.5.0",
     "micromatch": "^4.0.8",
     "semantic-release": "^25.0.0",
     "qs": ">=6.14.1",
     "lerna/js-yaml": "4.1.1",
-    "@lerna/create/js-yaml": "4.1.1",
-    "hono": ">=4.11.10",
-    "markdown-it": ">=14.1.1",
-    "@aws-sdk/xml-builder": ">=3.972.9"
+    "@lerna/create/js-yaml": "4.1.1"
   }
 }

packages/_example/package.json

@@ -29,7 +29,7 @@
     "pg": "^8.8.0",
     "reflect-metadata": "^0.1.13",
     "rxjs": "^7.8.0",
-    "sequelize": "^6.37.5",
+    "sequelize": "^6.37.8",
     "sqlite3": "^5.1.4",
     "superagent": "^10.3.0",
     "tedious": "^18.6.1"

packages/agent-client/CHANGELOG.md

@@ -1,3 +1,55 @@
+## @forestadmin/agent-client [1.4.18](https://github.com/ForestAdmin/agent-nodejs/compare/@forestadmin/agent-client@1.4.17...@forestadmin/agent-client@1.4.18) (2026-04-01)
+
+
+
+
+
+### Dependencies
+
+* **@forestadmin/forestadmin-client:** upgraded to 1.38.2
+
+## @forestadmin/agent-client [1.4.17](https://github.com/ForestAdmin/agent-nodejs/compare/@forestadmin/agent-client@1.4.16...@forestadmin/agent-client@1.4.17) (2026-03-31)
+
+
+
+
+
+### Dependencies
+
+* **@forestadmin/forestadmin-client:** upgraded to 1.38.1
+
+## @forestadmin/agent-client [1.4.16](https://github.com/ForestAdmin/agent-nodejs/compare/@forestadmin/agent-client@1.4.15...@forestadmin/agent-client@1.4.16) (2026-03-31)
+
+
+
+
+
+### Dependencies
+
+* **@forestadmin/datasource-toolkit:** upgraded to 1.53.1
+* **@forestadmin/forestadmin-client:** upgraded to 1.38.0
+
+## @forestadmin/agent-client [1.4.15](https://github.com/ForestAdmin/agent-nodejs/compare/@forestadmin/agent-client@1.4.14...@forestadmin/agent-client@1.4.15) (2026-03-31)
+
+
+
+
+
+### Dependencies
+
+* **@forestadmin/forestadmin-client:** upgraded to 1.37.19
+
+## @forestadmin/agent-client [1.4.14](https://github.com/ForestAdmin/agent-nodejs/compare/@forestadmin/agent-client@1.4.13...@forestadmin/agent-client@1.4.14) (2026-03-18)
+
+
+
+
+
+### Dependencies
+
+* **@forestadmin/datasource-toolkit:** upgraded to 1.53.0
+* **@forestadmin/forestadmin-client:** upgraded to 1.37.18
+
 ## @forestadmin/agent-client [1.4.13](https://github.com/ForestAdmin/agent-nodejs/compare/@forestadmin/agent-client@1.4.12...@forestadmin/agent-client@1.4.13) (2026-03-04)