@unstable-dev/unmeshed-mcp 0.1.0

package/knowledge/steps/UPDATE_STEP.md

@@ -0,0 +1,257 @@
+# UPDATE_STEP Step Schema
+
+`UPDATE_STEP` programmatically updates the status and output of a step in another
+(or the same) running workflow. Use it for cross-workflow coordination, external
+callback completion, human-task completion, or any scenario where one workflow
+needs to unblock or modify a step in another workflow.
+
+The step supports multiple matching strategies to locate the target step(s) and
+will optionally poll/wait until the target becomes available.
+
+## Definition Input Schema
+
+```json
+{
+  "inputMatchType": "BY_PROCESS_ID_REF",
+  "processId": 0,
+  "ref": "step_ref_to_update",
+  "correlationId": "",
+  "requestId": "",
+  "completionToken": "",
+  "stepId": 0,
+  "output": {},
+  "stepStatus": "COMPLETED",
+  "maxWaitSeconds": 86400,
+  "maxProcessContexts": 1,
+  "processName": "",
+  "allowCompletionWithoutMatch": false
+}
+```
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `inputMatchType` | string | Yes | — | How to find the target step. See match types below. |
+| `ref` | string | Conditional | — | The step `ref` in the target process to update. Required for all match types except `BY_STEP_ID` and `BY_COMPLETION_TOKEN`. |
+| `processId` | long | Conditional | `0` | Target process runtime ID. Required when `inputMatchType` is `BY_PROCESS_ID_REF`. |
+| `correlationId` | string | Conditional | — | Correlation ID to match. Required when `inputMatchType` is `BY_CORRELATION_ID_REF`. |
+| `requestId` | string | Conditional | — | Request ID to match. Required when `inputMatchType` is `BY_REQUEST_ID_REF`. |
+| `completionToken` | string | Conditional | — | Completion token to match. Required when `inputMatchType` is `BY_COMPLETION_TOKEN`. |
+| `stepId` | long | Conditional | `0` | Direct step ID to update. Required when `inputMatchType` is `BY_STEP_ID`. |
+| `output` | object | No | `{}` | Key-value pairs to merge into the target step's output. |
+| `stepStatus` | string | No | `"COMPLETED"` | Status to set on the target step. Valid values: `COMPLETED`, `FAILED`, `RUNNING`. |
+| `maxWaitSeconds` | long | No | `86400` (24h) | Max time to wait for the target step to become available before failing. |
+| `maxProcessContexts` | int | No | `1` | Max number of matching process contexts to update (for correlation/request ID matching). |
+| `processName` | string | Conditional | — | Process definition name. Required for `BY_CORRELATION_ID_REF` and `BY_REQUEST_ID_REF`. |
+| `allowCompletionWithoutMatch` | boolean | No | `false` | When `true` and `BY_COMPLETION_TOKEN` finds no matches, the step completes successfully instead of failing. |
+
+## Input Match Types
+
+| Match Type | Finds target by | Required fields |
+|---|---|---|
+| `BY_PROCESS_ID_REF` | Runtime process ID + step ref | `processId`, `ref` |
+| `BY_CORRELATION_ID_REF` | Correlation ID + step ref | `correlationId`, `ref`, `processName` |
+| `BY_REQUEST_ID_REF` | Request ID + step ref | `requestId`, `ref`, `processName` |
+| `BY_STEP_ID` | Direct step runtime ID | `stepId` |
+| `BY_COMPLETION_TOKEN` | Completion token | `completionToken` |
+
+## Runtime Output Schema
+
+### Successful update
+
+```json
+{
+  "__updateStepResults": {
+    "593084539:593084557": "Updated to: COMPLETED"
+  },
+  "__updateStepMetadata": [
+    {
+      "matchedExecutionStepId": 593084557,
+      "matchedExecutionProcessId": 593084539,
+      "updatedStatus": "COMPLETED",
+      "updatedStepRef": "wait_step_1",
+      "matchedExecutionProcessName": "my-workflow",
+      "matchedExecutionProcessVersion": 1
+    }
+  ]
+}
+```
+
+### No match found (within wait period)
+
+```json
+{
+  "__updateStepResults": {},
+  "error": "No qualified steps found within the wait period of 86400 seconds."
+}
+```
+
+### Unqualified steps (already completed/cancelled)
+
+```json
+{
+  "__updateStepResults": {
+    "593084539:593084557": "Step status not updatable: COMPLETED"
+  }
+}
+```
+
+## Output Access Paths
+
+Use:
+- `steps.<ref>.output.__updateStepResults` — map of `"processId:stepId"` → status message for each matched step.
+- `steps.<ref>.output.__updateStepMetadata` — array of metadata objects with details about each updated step.
+- `steps.<ref>.output.__updateStepMetadata[0].matchedExecutionProcessId` — the process ID that was updated.
+- `steps.<ref>.output.__updateStepMetadata[0].matchedExecutionStepId` — the step ID that was updated.
+- `steps.<ref>.output.__updateStepMetadata[0].updatedStatus` — the status set on the target step.
+- `steps.<ref>.output.error` — error message if the update failed.
+
+Do not use:
+- `steps.<ref>.output.result` — UPDATE_STEP does not wrap in `result`.
+- `steps.<ref>.output.response` — UPDATE_STEP does not have a `response` wrapper.
+
+## Generation Rules
+
+- Use uppercase step type: `"UPDATE_STEP"`.
+- Use `children: []`; UPDATE_STEP is not a container.
+- `inputMatchType` must be one of: `BY_PROCESS_ID_REF`, `BY_CORRELATION_ID_REF`, `BY_REQUEST_ID_REF`, `BY_STEP_ID`, `BY_COMPLETION_TOKEN`.
+- `stepStatus` must be `COMPLETED`, `FAILED`, or `RUNNING`. Defaults to `COMPLETED` if omitted.
+- `output` is optional — use it to inject data into the target step's output (e.g. results from an external callback).
+- `maxWaitSeconds` controls how long the step polls before giving up. Default is 24 hours (86400). The engine polls every 30 seconds.
+- Target steps must be in an updatable status (e.g. `SCHEDULED`, `RUNNING`). Already `COMPLETED`/`FAILED`/`CANCELLED` steps cannot be updated.
+- When using `BY_CORRELATION_ID_REF` or `BY_REQUEST_ID_REF`, `processName` is required to scope the search.
+- `maxProcessContexts` limits how many matching processes are updated (default 1).
+- Do not use UPDATE_STEP to update steps in the same process instance (use `__statePut` or data flow instead).
+
+## Debugging Rules
+
+When debugging an UPDATE_STEP:
+- Check `__updateStepResults` to see which steps were updated and which were rejected.
+- If a step shows "Step status not updatable", the target step has already completed or been cancelled.
+- If `error` says "No qualified steps found within the wait period", the target step never became available — verify the target workflow is running and the step ref/IDs are correct.
+- Check `__repeatCount` in the output to see how many polling attempts were made.
+- If using `BY_COMPLETION_TOKEN` with no matches, set `allowCompletionWithoutMatch: true` to avoid failures.
+
+Common failures:
+- Wrong `inputMatchType` for the use case.
+- Missing required fields for the chosen match type (e.g. `processId` missing for `BY_PROCESS_ID_REF`).
+- Target step already in a terminal status (`COMPLETED`, `FAILED`, `CANCELLED`).
+- Wrong `ref` or `processName` — these are case-sensitive.
+- Setting `stepStatus` to an invalid value (only `COMPLETED`, `FAILED`, `RUNNING` are accepted).
+- Using `maxWaitSeconds: 0` and the target step isn't ready yet — the step fails immediately.
+
+## Minimal Process Definition Example
+
+### Update by process ID + ref
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "update-step-example",
+  "version": 1,
+  "type": "API_ORCHESTRATION",
+  "description": "Complete a waiting step in another workflow.",
+  "configuration": null,
+  "steps": [
+    {
+      "orgId": 1,
+      "namespace": "default",
+      "name": "update_step",
+      "type": "UPDATE_STEP",
+      "ref": "update_step_1",
+      "optional": false,
+      "createdBy": "system",
+      "updatedBy": "system",
+      "description": null,
+      "label": null,
+      "created": 1700000000000,
+      "updated": 1700000000000,
+      "configuration": {
+        "errorPolicyName": null,
+        "useCache": false,
+        "cacheKey": null,
+        "cacheTimeoutSeconds": 0,
+        "stream": false,
+        "streamAllStatuses": false,
+        "preExecutionScript": null,
+        "constructInputFromScript": false,
+        "scriptLanguage": null,
+        "jqTransformer": null,
+        "rateLimitMaxRequests": 0,
+        "rateLimitWindowSeconds": 0
+      },
+      "children": [],
+      "input": {
+        "inputMatchType": "BY_PROCESS_ID_REF",
+        "processId": 593084539,
+        "ref": "wait_step_1",
+        "output": {
+          "callbackResult": "approved",
+          "approvedBy": "admin@example.com"
+        },
+        "stepStatus": "COMPLETED",
+        "maxWaitSeconds": 300
+      },
+      "output": null
+    }
+  ],
+  "defaultInput": null,
+  "defaultOutput": null,
+  "outputMapping": null,
+  "signature": null,
+  "metadata": null,
+  "tags": null,
+  "dependencies": null,
+  "dependents": null
+}
+```
+
+### Update by correlation ID
+
+```json
+{
+  "input": {
+    "inputMatchType": "BY_CORRELATION_ID_REF",
+    "correlationId": "order-12345",
+    "processName": "order-processor",
+    "ref": "approval_wait",
+    "output": { "approved": true },
+    "stepStatus": "COMPLETED",
+    "maxWaitSeconds": 60,
+    "maxProcessContexts": 1
+  }
+}
+```
+
+### Update by completion token
+
+```json
+{
+  "input": {
+    "inputMatchType": "BY_COMPLETION_TOKEN",
+    "completionToken": "tok_abc123",
+    "output": { "result": "callback-data" },
+    "stepStatus": "COMPLETED",
+    "allowCompletionWithoutMatch": false
+  }
+}
+```
+
+## Common Pattern: External Callback Completion
+
+A WAIT step in workflow A pauses until an external system calls back.
+Workflow B (triggered by the callback) uses UPDATE_STEP to unblock workflow A:
+
+```
+Workflow A:  HTTP (send request) → WAIT (paused, waiting for callback)
+                                        ↑
+Workflow B:  [triggered by callback] → UPDATE_STEP (completes the WAIT step in A with callback data)
+```
+
+## Common Pattern: Human Task Approval
+
+```
+Workflow:  INTEGRATION (send approval email with link) → WAIT (paused)
+                                                              ↑
+Approval workflow:  [triggered by link click] → UPDATE_STEP (BY_COMPLETION_TOKEN, completes WAIT)
+```

package/knowledge/steps/WAIT.md

@@ -0,0 +1,218 @@
+# Wait Step Schema
+
+`WAIT` pauses process execution until a specific timestamp. Use it when a
+business process needs to wait between steps, delay retries, or resume after a
+time calculated from runtime data.
+
+Wait timing is configured with JavaScript. When the WAIT step starts, Unmeshed
+evaluates the script and uses its returned `waitUntil` value as the resume time.
+
+## Definition Input Schema
+
+```json
+{
+  "script": "\n(steps, context) => {\n  return {\n    \"waitUntil\": steps.__self.startTime + (3 * 1000)\n  };\n}\n",
+  "completionToken": "",
+  "validateUpdate": false,
+  "enableTrigger": false
+}
+```
+
+Required:
+- `script`: JavaScript function receiving `(steps, context)`.
+- Script return value must include `waitUntil`.
+- `waitUntil` must be an epoch timestamp in milliseconds.
+
+Optional/observed:
+- `completionToken`: string, often `""`.
+- `validateUpdate`: boolean.
+- `enableTrigger`: boolean.
+
+## Runtime Output Schema
+
+```json
+{
+  "result": {
+    "waitUntil": 1778183695557
+  },
+  "__waitStartedAt": 1778183692557,
+  "logs": []
+}
+```
+
+`schedule` on the executed step record is usually the same timestamp as
+`output.result.waitUntil`.
+
+```json
+{
+  "start": 1778183692557,
+  "schedule": 1778183695557,
+  "output": {
+    "result": {
+      "waitUntil": 1778183695557
+    },
+    "__waitStartedAt": 1778183692557,
+    "logs": []
+  }
+}
+```
+
+## Output Access Paths
+
+Use:
+- `steps.<ref>.output.result.waitUntil` for the timestamp when execution resumes.
+- `steps.<ref>.output.__waitStartedAt` for the timestamp when the wait started.
+- `steps.<ref>.output.logs` for captured logs.
+- `steps.__self.startTime` inside the WAIT script for this wait instance's start time.
+
+Do not use:
+- `steps.<ref>.output.response`
+- `steps.<ref>.output.statusCode`
+- `steps.<ref>.output.waitUntil`
+- a WAIT script return value without `waitUntil`
+
+## Generation Rules
+
+- Use uppercase step type: `"WAIT"`.
+- Put JavaScript code in `input.script`.
+- The script must accept `(steps, context)`.
+- The script must return an object with `waitUntil`.
+- `waitUntil` must be epoch milliseconds, not seconds.
+- Use `steps.__self.startTime` for relative waits because it works inside loops.
+- Use `Date.now()` only when the desired behavior is based on current wall-clock time.
+- Use `completionToken: ""`, `validateUpdate: false`, and `enableTrigger: false` unless the user specifically needs external completion/update behavior.
+- Keep `children: []`; WAIT is not a container.
+
+## Debugging Rules
+
+When a WAIT step fails or behaves unexpectedly:
+- Inspect `input.script`.
+- Confirm the script returns `{ waitUntil: <epochMillis> }`.
+- Confirm `waitUntil` is in milliseconds, not seconds.
+- Compare `output.result.waitUntil`, `output.__waitStartedAt`, `start`, and `schedule`.
+- If the process appears stuck, check whether `schedule` is in the future.
+- If a wait ran too long or too short, compute `waitUntil - __waitStartedAt`.
+- If the script uses upstream step data, validate those output paths against the source step type.
+
+Common failures:
+- Missing `waitUntil`.
+- Returning seconds instead of milliseconds.
+- Returning a date string instead of epoch milliseconds.
+- Using `steps.<wait_ref>.output.waitUntil` instead of `steps.<wait_ref>.output.result.waitUntil`.
+- Using `steps.__self.start` instead of the observed `steps.__self.startTime` in the wait script.
+- Forgetting that the execution list can show multiple runs/polls for one WAIT step.
+
+## Minimal Process Definition Example
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "kebab-case-name",
+  "version": 1,
+  "type": "API_ORCHESTRATION",
+  "description": "Wait for three seconds.",
+  "configuration": null,
+  "steps": [
+    {
+      "orgId": 1,
+      "namespace": "default",
+      "name": "wait",
+      "type": "WAIT",
+      "ref": "wait_1",
+      "optional": false,
+      "createdBy": "system",
+      "updatedBy": "system",
+      "description": null,
+      "label": null,
+      "created": 1700000000000,
+      "updated": 1700000000000,
+      "configuration": {
+        "errorPolicyName": null,
+        "useCache": false,
+        "cacheKey": null,
+        "cacheTimeoutSeconds": 0,
+        "stream": false,
+        "streamAllStatuses": false,
+        "preExecutionScript": null,
+        "constructInputFromScript": false,
+        "scriptLanguage": null,
+        "jqTransformer": null,
+        "rateLimitMaxRequests": 0,
+        "rateLimitWindowSeconds": 0
+      },
+      "children": [],
+      "input": {
+        "script": "\n(steps, context) => {\n  return {\n    \"waitUntil\": steps.__self.startTime + (3 * 1000)\n  };\n}\n",
+        "completionToken": "",
+        "validateUpdate": false,
+        "enableTrigger": false
+      },
+      "output": null
+    }
+  ],
+  "defaultInput": null,
+  "defaultOutput": null,
+  "outputMapping": null,
+  "signature": null,
+  "metadata": null,
+  "tags": null,
+  "dependencies": null,
+  "dependents": null
+}
+```
+
+## Minimal Executed Step Example
+
+```json
+{
+  "id": 28800021,
+  "processId": 28800019,
+  "ref": "wait_1",
+  "namespace": "default",
+  "name": "wait",
+  "type": "WAIT",
+  "status": "COMPLETED",
+  "input": {
+    "completionToken": "",
+    "enableTrigger": false,
+    "__currentExecutionStartTime": 1778183692557,
+    "script": "\n(steps, context) => {\n  return {\n    \"waitUntil\": steps.__self.startTime + (3 * 1000)\n  };\n}\n",
+    "validateUpdate": false
+  },
+  "output": {
+    "result": {
+      "waitUntil": 1778183695557
+    },
+    "__waitStartedAt": 1778183692557,
+    "logs": []
+  },
+  "start": 1778183692557,
+  "schedule": 1778183695557,
+  "executionList": [
+    {
+      "id": 0,
+      "scheduled": 1778183695557,
+      "polled": 1778183695558,
+      "start": 1778183692557,
+      "updated": 1778183695601,
+      "executor": "server-1",
+      "ref": "wait_1",
+      "runs": 2,
+      "output": {}
+    }
+  ]
+}
+```
+
+## Example: Wait Until A Time From Input
+
+```javascript
+(steps, context) => {
+  const delayMs = Number(context.input.delayMs || 0);
+  return {
+    waitUntil: steps.__self.startTime + delayMs
+  };
+}
+```
+