@unstable-dev/unmeshed-mcp 0.1.0

package/knowledge/steps/FAIL.md

@@ -0,0 +1,198 @@
+# FAIL Step Schema
+
+`FAIL` immediately fails the current workflow (or branch) with a given reason.
+It is the counterpart to `EXIT` — while `EXIT` can complete or fail a workflow,
+`FAIL` always produces a `FAILED` status. The step itself and the process both
+end in `FAILED`.
+
+Use it for explicit error paths inside SWITCH branches, guard clauses, or
+intentional test failures.
+
+## Definition Input Schema
+
+```json
+{
+  "reason": "Test Failure"
+}
+```
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `reason` | string | Yes | A human-readable message explaining why the workflow is being failed. Can be an empty string `""`. |
+
+## Runtime Output Schema
+
+```json
+{
+  "reason": "Test Failure"
+}
+```
+
+The output mirrors the input — the `reason` string is passed through as the step and process output.
+
+## Output Access Paths
+
+Use:
+- `steps.<ref>.output.reason` — the failure reason string.
+
+Do not use:
+- `steps.<ref>.output.result` — FAIL does not wrap output in `result`.
+- `steps.<ref>.output.response` — FAIL does not have a `response` wrapper.
+- `steps.<ref>.output.error` — the field is `reason`, not `error`.
+
+## Process-Level Effect
+
+When a FAIL step executes:
+- The step status becomes `FAILED`.
+- The parent container (LIST, PARALLEL branch) propagates the failure upward.
+- The entire process status becomes `FAILED`.
+- The process `output` contains `{ "reason": "..." }`.
+
+If the FAIL step is inside a PARALLEL branch with `failIfAnyBranchFails: true`,
+the other branches are cancelled and the PARALLEL step fails.
+
+If the FAIL step is inside an `optional: true` parent, the workflow continues
+past the failed section.
+
+## Generation Rules
+
+- Use uppercase step type: `"FAIL"`.
+- Use `children: []`; FAIL is not a container.
+- `reason` should be a descriptive string; it appears in the process output and logs.
+- Use FAIL inside SWITCH branches to terminate on error conditions.
+- Use FAIL inside PARALLEL branches to intentionally fail one path (e.g. timeout guards).
+- Do not confuse with `EXIT` — EXIT supports both `COMPLETED` and `FAILED` status and has a `message` field. FAIL always fails and uses `reason`.
+- Do not add `script`, `url`, or other fields — FAIL only takes `reason`.
+
+## Debugging Rules
+
+When debugging a FAIL step:
+- The step will always have `status: "FAILED"` — this is intentional, not an error.
+- Check `output.reason` for the failure message.
+- Trace upward: if the process failed, check whether it was due to a FAIL step by inspecting step records.
+- If used inside a PARALLEL with `failIfAnyBranchFails: true`, sibling branches will be `CANCELLED`.
+
+Common failures:
+- Forgetting that FAIL always fails — use `EXIT` with `status: "COMPLETED"` if you want a clean termination.
+- Using FAIL at the top level without `optional: true` on a parent — the entire process will fail.
+- Expecting FAIL output under `error` instead of `reason`.
+
+## Minimal Process Definition Example
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "fail-step",
+  "version": 1,
+  "type": "API_ORCHESTRATION",
+  "description": "Intentionally fail the workflow with a reason.",
+  "configuration": null,
+  "steps": [
+    {
+      "orgId": 1,
+      "namespace": "default",
+      "name": "fail",
+      "type": "FAIL",
+      "ref": "fail_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": {
+        "reason": "Test Failure"
+      },
+      "output": null
+    }
+  ],
+  "defaultInput": null,
+  "defaultOutput": null,
+  "outputMapping": null,
+  "signature": null,
+  "metadata": null,
+  "tags": null,
+  "dependencies": null,
+  "dependents": null
+}
+```
+
+## Minimal Executed Step Example
+
+```json
+{
+  "id": 593087238,
+  "processId": 593087236,
+  "ref": "fail_1",
+  "namespace": "default",
+  "name": "fail",
+  "type": "FAIL",
+  "status": "FAILED",
+  "input": {
+    "reason": "Test Failure",
+    "__currentExecutionStartTime": 1778222312325
+  },
+  "output": {
+    "reason": "Test Failure"
+  }
+}
+```
+
+## Example: FAIL Inside a SWITCH Branch
+
+```json
+{
+  "type": "SWITCH",
+  "ref": "guard_check",
+  "children": [
+    {
+      "type": "LIST",
+      "ref": "happy_path",
+      "children": [
+        { "type": "HTTP", "ref": "do_work", "..." : "..." }
+      ],
+      "input": {}
+    },
+    {
+      "type": "FAIL",
+      "ref": "error_path",
+      "input": { "reason": "Validation failed — missing required fields" },
+      "children": [],
+      "..." : "..."
+    }
+  ],
+  "input": {
+    "script": "(steps, context) => {\n  if (context.input.isValid) return 'ok';\n  return 'fail';\n}",
+    "responseMapping": [
+      { "targetRef": "happy_path", "value": "ok" },
+      { "targetRef": "error_path", "value": "fail" }
+    ]
+  }
+}
+```
+
+## Comparison: FAIL vs EXIT
+
+| | FAIL | EXIT |
+|---|---|---|
+| Step type | `"FAIL"` | `"EXIT"` |
+| Always fails? | Yes | No — supports `COMPLETED` or `FAILED` |
+| Input field | `reason` | `message` + `status` |
+| Use case | Error branches, guard failures, intentional test failures | Clean termination, early exit with success |

package/knowledge/steps/FLOW_GATEWAY.md

@@ -0,0 +1,405 @@
+# Flow Gateway Step Schema
+
+`FLOW_GATEWAY` is a script-driven control-flow step that changes which child
+step a parent `LIST` should run next. Use it when you want a `LIST` to behave
+like a jump table, loop, or branch controller based on runtime data.
+
+Unlike `SWITCH`, `FLOW_GATEWAY` does not directly run one of its own child
+branches. Instead, it updates the parent `LIST` control-flow pointer so the
+list continues from a specific child `ref`.
+
+From the engine source:
+- The step runs a JavaScript `input.script`.
+- The script result is converted to a string and stored in `output.result`.
+- That string is matched against `input.responseMapping`.
+- The first matching `targetRef` is written into the parent LIST's
+  `__currentStepRef`.
+- The parent step **must** be a `LIST`.
+- The parent LIST must be operating in control-flow mode for this step to make
+  practical sense.
+- The engine tracks control-flow iterations using `__ctfIteration` and
+  `__ctfTickets`.
+
+Important:
+- `FLOW_GATEWAY` is for internal branching/jumping within a parent `LIST`.
+- It can jump forward or backward to another child ref, so it can create
+  loop-like behavior.
+- It should normally be used inside a `LIST` with `input.controlFlow = true`.
+- Branches often end with `EXIT` to avoid unintentionally continuing into later
+  sibling steps.
+
+## Definition Input Schema
+
+```json
+{
+  "script": "// (steps, context) will be provided as default inputs \n(steps, context) => {\n  return steps.decision_js_1.output.result.nextRoute;\n}",
+  "responseMapping": [
+    {
+      "targetRef": "http_1",
+      "value": "retry_http"
+    },
+    {
+      "targetRef": "done_exit_1",
+      "value": "finish"
+    }
+  ],
+  "limitRuns": 10
+}
+```
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `script` | string | Yes | JavaScript that returns the case/control-flow result. |
+| `responseMapping` | array | Yes | List of case mappings from returned value to target child `ref`. |
+| `limitRuns` | number | No | Observed on the input model with default `10`, but see source note below. |
+
+### Response Mapping Shape
+
+Each `responseMapping` entry uses this structure:
+
+```json
+{
+  "targetRef": "done_exit_1",
+  "value": "finish",
+  "defaultBranch": false
+}
+```
+
+Fields:
+- `targetRef`: child step ref inside the same parent `LIST`.
+- `value`: script result to match exactly after string conversion.
+- `defaultBranch`: optional fallback branch when no explicit `value` matches.
+
+## Runtime Output Schema
+
+The flow gateway stores the selected case string and logs in its own step
+output:
+
+```json
+{
+  "result": "finish",
+  "logs": []
+}
+```
+
+But the real control-flow effect is on the parent `LIST` input, where the
+gateway updates:
+- `__currentStepRef`
+- `__ctfIteration`
+- `__ctfTickets`
+
+Those fields are implementation details, not something later steps should read
+directly in normal workflow design.
+
+## Output Access Paths
+
+Use:
+- `steps.<ref>.output.result` for the script result string chosen by the
+  gateway.
+- `steps.<ref>.output.logs` for captured script logs.
+
+Do not use:
+- `steps.<ref>.output.response`
+- `steps.<ref>.output.results`
+- `steps.<ref>.output.<field>` for case strings
+
+## Generation Rules
+
+- Use uppercase step type: `"FLOW_GATEWAY"`.
+- Use `children: []`; FLOW_GATEWAY is not a container step itself.
+- Place it under a parent `LIST`.
+- Prefer placing it under a parent LIST with `input.controlFlow = true`.
+- The script should return a value that maps cleanly to one `responseMapping`
+  case.
+- Map `targetRef` values to sibling child refs inside the same parent LIST.
+- Add a `defaultBranch` mapping when unmatched values are possible.
+- Use `EXIT` at the end of terminal branches when you want to stop the process
+  cleanly.
+- If using backward jumps, make sure there is a real exit condition.
+- Put the loop safety limit on the parent LIST as `input.limitRuns`.
+
+Observed source nuance:
+- `FlowGatewayInput` defines `limitRuns` with default `10`.
+- But `FlowGatewayRunnerActor` actually reads `limitRuns` from the **parent
+  LIST input** with fallback `500`.
+- For predictable behavior, set `limitRuns` on the parent LIST and do not rely
+  only on the FLOW_GATEWAY field.
+
+## Validation Rules
+
+From `FlowGatewayStepValidator`:
+- Duplicate non-default case values are rejected.
+- Templated values are normalized before duplicate checking, so `{{abc}}` and
+  `{{   abc   }}` count as the same case.
+- A `defaultBranch` entry is ignored in duplicate case checks.
+
+## Debugging Rules
+
+When debugging a FLOW_GATEWAY:
+- Inspect `input.script`.
+- Inspect `output.result` for the actual case string returned by the script.
+- Inspect `output.logs`.
+- Verify the step has a parent and that the parent type is `LIST`.
+- Verify the parent LIST is configured for control-flow usage.
+- Verify each `responseMapping.targetRef` points to a real child ref in the same
+  parent LIST.
+- If it loops unexpectedly, inspect the parent LIST `limitRuns` and the script's
+  exit condition.
+- If no mapping matches, check for a missing `defaultBranch`.
+
+Common failures:
+- Using FLOW_GATEWAY outside a parent `LIST`.
+- Expecting FLOW_GATEWAY to behave like `SWITCH`.
+- Returning a value not present in `responseMapping`.
+- Forgetting a default branch for unknown values.
+- Creating a backward jump with no exit condition.
+- Putting `limitRuns` only on the gateway input and assuming the runner will use
+  it.
+- Looking for branch payloads in `FLOW_GATEWAY` output instead of in the branch
+  step outputs.
+
+## Minimal Process Definition Example
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "flow-gateway-example",
+  "version": 1,
+  "type": "API_ORCHESTRATION",
+  "description": "Control-flow list with a flow gateway.",
+  "configuration": null,
+  "steps": [
+    {
+      "orgId": 1,
+      "namespace": "default",
+      "name": "control_flow_list",
+      "type": "LIST",
+      "ref": "list_1",
+      "optional": false,
+      "createdBy": "system",
+      "updatedBy": "system",
+      "description": "Parent LIST operating in control-flow mode.",
+      "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": [
+        {
+          "orgId": 1,
+          "namespace": "default",
+          "name": "flow_gateway",
+          "type": "FLOW_GATEWAY",
+          "ref": "flow_gateway_1",
+          "optional": false,
+          "createdBy": "system",
+          "updatedBy": "system",
+          "description": "Choose the next child step to run.",
+          "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": "// (steps, context) will be provided as default inputs \n(steps, context) => {\n  return String(context.input.decision || \"unknown\");\n}",
+            "responseMapping": [
+              {
+                "targetRef": "approved_exit_1",
+                "value": "approve"
+              },
+              {
+                "targetRef": "rejected_exit_1",
+                "value": "reject"
+              },
+              {
+                "targetRef": "unknown_exit_1",
+                "defaultBranch": true
+              }
+            ]
+          },
+          "output": null
+        },
+        {
+          "orgId": 1,
+          "namespace": "default",
+          "name": "approved_exit",
+          "type": "EXIT",
+          "ref": "approved_exit_1",
+          "optional": false,
+          "createdBy": "system",
+          "updatedBy": "system",
+          "description": "Approved path.",
+          "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": "Approved branch completed.",
+            "status": "COMPLETED"
+          },
+          "output": null
+        },
+        {
+          "orgId": 1,
+          "namespace": "default",
+          "name": "rejected_exit",
+          "type": "EXIT",
+          "ref": "rejected_exit_1",
+          "optional": false,
+          "createdBy": "system",
+          "updatedBy": "system",
+          "description": "Rejected path.",
+          "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": "Rejected branch completed.",
+            "status": "FAILED"
+          },
+          "output": null
+        },
+        {
+          "orgId": 1,
+          "namespace": "default",
+          "name": "unknown_exit",
+          "type": "EXIT",
+          "ref": "unknown_exit_1",
+          "optional": false,
+          "createdBy": "system",
+          "updatedBy": "system",
+          "description": "Fallback path.",
+          "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": "Unknown decision value.",
+            "status": "FAILED"
+          },
+          "output": null
+        }
+      ],
+      "input": {
+        "controlFlow": true,
+        "limitRuns": 10
+      },
+      "output": null
+    }
+  ],
+  "defaultInput": {
+    "decision": "approve"
+  },
+  "defaultOutput": null,
+  "outputMapping": null,
+  "signature": null,
+  "metadata": null,
+  "tags": null,
+  "dependencies": null,
+  "dependents": null
+}
+```
+
+## Minimal Executed Step Example
+
+```json
+{
+  "id": 30050099,
+  "processId": 30050097,
+  "ref": "flow_gateway_1",
+  "namespace": "default",
+  "name": "flow_gateway",
+  "type": "FLOW_GATEWAY",
+  "status": "COMPLETED",
+  "input": {
+    "script": "// (steps, context) will be provided as default inputs \n(steps, context) => {\n  return String(context.input.decision || \"unknown\");\n}",
+    "responseMapping": [
+      {
+        "targetRef": "approved_exit_1",
+        "value": "approve"
+      },
+      {
+        "targetRef": "rejected_exit_1",
+        "value": "reject"
+      },
+      {
+        "targetRef": "unknown_exit_1",
+        "defaultBranch": true
+      }
+    ],
+    "__currentExecutionStartTime": 1778619000000
+  },
+  "output": {
+    "result": "approve",
+    "logs": []
+  }
+}
+```