@unstable-dev/unmeshed-mcp 0.1.0

package/knowledge/steps/DEPENDSON.md

@@ -0,0 +1,296 @@
+# DEPENDSON Step Schema
+
+`DEPENDSON` pauses the current workflow branch until an external condition is met —
+either a specific **process** has reached a target status, or a specific **step**
+within a process has reached a target status. The engine polls at a configurable
+interval until the dependency is satisfied or the step is cancelled.
+
+Use it for cross-workflow synchronisation, fan-out/fan-in patterns, or waiting for
+a sibling parallel branch's step to complete before proceeding.
+
+## Definition Input Schema
+
+```json
+{
+  "dependsOnStatement": "STEP('process-def-name', 'step-ref', 'COMPLETED')",
+  "intervalSeconds": 10
+}
+```
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `dependsOnStatement` | string | Yes | An SQL-style expression describing the dependency condition. See syntax below. |
+| `intervalSeconds` | integer | Yes | How often (in seconds) the engine re-evaluates the condition. |
+
+## Dependency Statement Syntax
+
+Two functions are available, and they can be combined with `AND` / `OR` operators.
+
+### PROCESS function
+
+Wait for an entire process (by definition name) to reach a status.
+
+```
+PROCESS('process-def-name', 'STATUS')
+```
+
+### STEP function
+
+Wait for a specific step (by ref) inside a process (by definition name) to reach a status.
+
+```
+STEP('process-def-name', 'step-ref-name', 'STATUS')
+```
+
+### Combining conditions
+
+Use `AND`, `OR`, and parentheses to build compound expressions.
+
+```
+(PROCESS('process-def-name', 'COMPLETED')
+OR
+PROCESS('process-def-name', 'TERMINATED')
+OR
+PROCESS('process-def-name', 'FAILED'))
+AND
+STEP('process-def-name', 'step-ref-name', 'COMPLETED')
+```
+
+### Common statuses
+
+`COMPLETED`, `FAILED`, `TERMINATED`, `CANCELLED`
+
+## Runtime Output Schema
+
+```json
+{
+  "__repeatConditionMatched": true,
+  "__dependsOnOutput": {
+    "result": true,
+    "evaluation": "step in process 7_dependson_parallel_test and ref new_http_1 should be COMPLETED, result COMPLETED",
+    "evaluatedDependencies": [
+      {
+        "conditionMet": true,
+        "condition": "STEP('7_dependson_parallel_test','new_http_1','COMPLETED')",
+        "actualStatus": "COMPLETED",
+        "processName": "7_dependson_parallel_test",
+        "stepRef": "new_http_1",
+        "matchedExecutionId": 593081549,
+        "matchedExecutionProcessId": 593080545,
+        "matchedExecutionProcessVersion": 1,
+        "expectedStatus": "COMPLETED",
+        "type": "STEP",
+        "matchedExecutionProcessName": "7_dependson_parallel_test"
+      }
+    ]
+  },
+  "__dependsOnMetadata": {
+    "evaluatedDependencies": [...]
+  }
+}
+```
+
+When the condition is **not met** (e.g. the target process/step doesn't exist yet or hasn't reached the expected status):
+
+```json
+{
+  "__repeatConditionMatched": false,
+  "__repeatCount": 1,
+  "__updatedKeySchedule": 1778222111362,
+  "__dependsOnOutput": {
+    "result": false,
+    "evaluation": "Unexpected error, will retry: Unable to find the record 1 automated_tests name",
+    "evaluatedDependencies": []
+  }
+}
+```
+
+## Output Access Paths
+
+Use:
+- `steps.<ref>.output.__repeatConditionMatched` — `true` if the dependency was satisfied, `false` if cancelled/timed-out before match.
+- `steps.<ref>.output.__dependsOnOutput.result` — `true` / `false` boolean result.
+- `steps.<ref>.output.__dependsOnOutput.evaluation` — human-readable description of what was checked.
+- `steps.<ref>.output.__dependsOnOutput.evaluatedDependencies` — array of per-condition details.
+- `steps.<ref>.output.__dependsOnOutput.evaluatedDependencies[0].conditionMet` — whether that specific condition matched.
+- `steps.<ref>.output.__dependsOnOutput.evaluatedDependencies[0].actualStatus` — the actual status found.
+
+Do not use:
+- `steps.<ref>.output.result` — the result is nested inside `__dependsOnOutput`.
+- `steps.<ref>.output.response` — DEPENDSON does not have a `response` wrapper.
+
+## Generation Rules
+
+- Use uppercase step type: `"DEPENDSON"`.
+- Use `children: []`; DEPENDSON is not a container.
+- `dependsOnStatement` must use the exact syntax: `STEP('name', 'ref', 'STATUS')` or `PROCESS('name', 'STATUS')`.
+- String values inside the statement use **single quotes**.
+- Combine multiple conditions with `AND` / `OR` and parentheses for grouping.
+- `intervalSeconds` controls polling frequency — lower values mean faster detection but higher load.
+- DEPENDSON is commonly used inside a PARALLEL branch to wait for a sibling branch's step to finish.
+- The process name in the statement refers to the **process definition name** (not a runtime process ID).
+- The step ref in the statement refers to the step's `ref` field in the process definition.
+- DEPENDSON can reference steps/processes in the **same** workflow (cross-branch sync) or in **other** workflows.
+
+## Debugging Rules
+
+When debugging a DEPENDSON step:
+- Check `__repeatConditionMatched` — if `false`, the dependency was never satisfied before the step was cancelled or the workflow ended.
+- Inspect `__dependsOnOutput.evaluation` for a human-readable explanation.
+- Look at `evaluatedDependencies` to see each condition individually — check `conditionMet`, `actualStatus`, and `expectedStatus`.
+- If `evaluation` says "Unable to find the record", the referenced process name or step ref does not exist or hasn't run yet.
+- Check `__repeatCount` to see how many polling attempts were made.
+
+Common failures:
+- Wrong process definition name in the statement (case-sensitive, must match exactly).
+- Wrong step ref in the statement.
+- Expecting `output.result` instead of `output.__dependsOnOutput.result`.
+- DEPENDSON waiting forever because the referenced step/process never reaches the expected status — always pair with a timeout strategy (e.g. `optional: true` on the parent PARALLEL, or a FAIL step in a sibling branch).
+- Using double quotes inside the statement instead of single quotes.
+
+## Minimal Process Definition Example
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "dependson-example",
+  "version": 1,
+  "type": "API_ORCHESTRATION",
+  "description": "Wait for a step in another process to complete.",
+  "configuration": null,
+  "steps": [
+    {
+      "orgId": 1,
+      "namespace": "default",
+      "name": "new_dependson",
+      "type": "DEPENDSON",
+      "ref": "dependson_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": {
+        "dependsOnStatement": "STEP('my-workflow', 'http_step_1', 'COMPLETED')",
+        "intervalSeconds": 10
+      },
+      "output": null
+    }
+  ],
+  "defaultInput": null,
+  "defaultOutput": null,
+  "outputMapping": null,
+  "signature": null,
+  "metadata": null,
+  "tags": null,
+  "dependencies": null,
+  "dependents": null
+}
+```
+
+## Minimal Executed Step Example
+
+```json
+{
+  "id": 593085064,
+  "processId": 593084539,
+  "ref": "new_dependson_2",
+  "namespace": "automated_tests",
+  "name": "new_dependson",
+  "type": "DEPENDSON",
+  "status": "COMPLETED",
+  "input": {
+    "__currentExecutionStartTime": 1778222100956,
+    "dependsOnStatement": "STEP('7_dependson_parallel_test', 'new_http_1', 'COMPLETED')",
+    "intervalSeconds": 10
+  },
+  "output": {
+    "__repeatConditionMatched": true,
+    "__dependsOnOutput": {
+      "result": true,
+      "evaluation": "step in process 7_dependson_parallel_test and ref new_http_1 should be COMPLETED, result COMPLETED",
+      "evaluatedDependencies": [
+        {
+          "conditionMet": true,
+          "condition": "STEP('7_dependson_parallel_test','new_http_1','COMPLETED')",
+          "actualStatus": "COMPLETED",
+          "processName": "7_dependson_parallel_test",
+          "stepRef": "new_http_1",
+          "expectedStatus": "COMPLETED",
+          "type": "STEP"
+        }
+      ]
+    }
+  }
+}
+```
+
+## Example: Checking DEPENDSON Result in a Later Step
+
+```javascript
+(steps, context) => {
+  // Check if the dependency was satisfied
+  if (steps.dependson_1.output.__dependsOnOutput.result === false) {
+    throw Error("Dependency was not satisfied");
+  }
+
+  // Check if condition was matched before cancellation
+  if (steps.dependson_1.output.__repeatConditionMatched !== true) {
+    throw Error("DEPENDSON was cancelled before matching");
+  }
+
+  return {
+    dependencyMet: true,
+    actualStatus: steps.dependson_1.output.__dependsOnOutput.evaluatedDependencies[0].actualStatus
+  };
+}
+```
+
+## Common Pattern: Cross-Branch Synchronisation in PARALLEL
+
+Use DEPENDSON inside one PARALLEL branch to wait for a step in a sibling branch:
+
+```
+PARALLEL
+├── LIST (branch A)
+│   ├── WAIT (1s delay)
+│   └── HTTP (new_http_1)      ← this step must complete first
+└── LIST (branch B)
+    ├── WAIT (0.5s delay)
+    └── DEPENDSON              ← waits for new_http_1 in the same workflow
+        input.dependsOnStatement: "STEP('my-workflow', 'new_http_1', 'COMPLETED')"
+```
+
+## Statement Syntax Reference
+
+```
+# Wait for a process to complete
+PROCESS('order-processor', 'COMPLETED')
+
+# Wait for a step in a process to complete
+STEP('order-processor', 'validate_order', 'COMPLETED')
+
+# Wait for a process to reach any terminal state
+PROCESS('order-processor', 'COMPLETED') OR PROCESS('order-processor', 'FAILED')
+
+# Compound: process done AND a specific step done
+PROCESS('order-processor', 'COMPLETED') AND STEP('order-processor', 'notify_step', 'COMPLETED')
+```

package/knowledge/steps/EXIT.md

@@ -0,0 +1,220 @@
+# Exit Step Schema
+
+`EXIT` stops the current process intentionally with a chosen process status and
+message. Use it in branching workflows when a path should terminate the process
+cleanly, for example after validation, approval/denial, or a business rule that
+means no further steps should run.
+
+Use `FAIL` for hard failure scenarios where the process should fail directly.
+Use `EXIT` when the workflow author wants to choose the final status.
+
+## Definition Input Schema
+
+```json
+{
+  "message": "Exit message",
+  "status": "COMPLETED"
+}
+```
+
+Optional/observed:
+- `message`: textual explanation of why the process exited.
+- `status`: process status to exit with, for example `COMPLETED` or `FAILED`.
+
+## Runtime Output Schema
+
+The EXIT output mirrors the exit reason/status in runtime-specific fields.
+
+```json
+{
+  "__exitReason": "Exit message",
+  "__exitStatus": "COMPLETED",
+  "message": "Exit message"
+}
+```
+
+The process status is configured from the EXIT input `status`.
+
+## Output Access Paths
+
+Use:
+- `steps.<ref>.output.__exitStatus` for the status used to exit.
+- `steps.<ref>.output.__exitReason` for the exit reason.
+- `steps.<ref>.output.message` for the user-facing message.
+
+Do not use:
+- `steps.<ref>.output.result`
+- `steps.<ref>.output.response`
+- `steps.<ref>.output.status`
+
+## Generation Rules
+
+- Use uppercase step type: `"EXIT"`.
+- Use `children: []`; EXIT is not a container.
+- Put `message` and `status` in `input`.
+- Choose `status` deliberately based on the business outcome.
+- Use `COMPLETED` when the workflow is intentionally ending successfully.
+- Use `FAILED` when the workflow should intentionally end as failed.
+- In complex branches, place EXIT inside the branch that should stop the process.
+- Do not place important later sibling steps after an EXIT if they must run.
+- Use dynamic templating in `message` only when needed and supported by the surrounding context.
+
+## Debugging Rules
+
+When debugging an EXIT:
+- Inspect the EXIT step record's `input.status`.
+- Inspect `output.__exitStatus` and process-level `status`.
+- Inspect `output.__exitReason` and `output.message`.
+- If later steps did not run, check whether EXIT intentionally stopped the process.
+- If the process completed unexpectedly, check whether EXIT used `status: "COMPLETED"`.
+- If the process failed intentionally, check whether EXIT used `status: "FAILED"`.
+
+Common failures:
+- Using EXIT where FAIL is more appropriate for an unrecoverable technical error.
+- Setting `status: "COMPLETED"` in a failure branch.
+- Expecting steps after EXIT to continue.
+- Looking for `output.result` instead of `__exitStatus`/`__exitReason`.
+- Forgetting to include a clear message for end users.
+
+## Minimal Process Definition Example
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "kebab-case-name",
+  "version": 1,
+  "type": "API_ORCHESTRATION",
+  "description": "Call HTTP and then exit intentionally.",
+  "configuration": null,
+  "steps": [
+    {
+      "orgId": 1,
+      "namespace": "default",
+      "name": "http",
+      "type": "HTTP",
+      "ref": "http_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": {
+        "method": "GET",
+        "url": "http://localhost:8080/api/test/get",
+        "headers": {
+          "Content-Type": "application/json",
+          "Accept": "application/json",
+          "Authorization": "Bearer {{secrets.test_token}}"
+        },
+        "params": {
+          "sampleKey": "sampleValue"
+        },
+        "repeatUntilEnabled": null,
+        "repeatUntilCondition": {
+          "script": "(steps, context) => {\n  return steps.__self.output.response.counter === 100;\n}"
+        },
+        "repeatIntervalSeconds": null,
+        "maxRepeatCount": null,
+        "includeFullResponseString": false,
+        "noEncode": false,
+        "extraLongTimeouts": false
+      },
+      "output": null
+    },
+    {
+      "orgId": 1,
+      "namespace": "default",
+      "name": "exit",
+      "type": "EXIT",
+      "ref": "exit_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": {
+        "message": "Exit message",
+        "status": "COMPLETED"
+      },
+      "output": null
+    }
+  ],
+  "defaultInput": null,
+  "defaultOutput": null,
+  "outputMapping": null,
+  "signature": null,
+  "metadata": null,
+  "tags": null,
+  "dependencies": null,
+  "dependents": null
+}
+```
+
+## Minimal Executed Step Example
+
+```json
+{
+  "id": 28800040,
+  "processId": 28800037,
+  "ref": "exit_1",
+  "namespace": "default",
+  "name": "exit",
+  "type": "EXIT",
+  "status": "COMPLETED",
+  "input": {
+    "message": "Exit message",
+    "__currentExecutionStartTime": 1778184661988,
+    "status": "COMPLETED"
+  },
+  "output": {
+    "__exitReason": "Exit message",
+    "__exitStatus": "COMPLETED",
+    "message": "Exit message"
+  }
+}
+```
+
+## Example: Validation Branch Exit
+
+```json
+{
+  "message": "Required customer email is missing.",
+  "status": "FAILED"
+}
+```
+