@unstable-dev/unmeshed-mcp 0.1.0

package/knowledge/steps/SUB_PROCESS.md

@@ -0,0 +1,296 @@
+# Sub Process Step Schema
+
+`SUB_PROCESS` calls another process definition as a child process from the
+current workflow. Use it for modular workflow design, code reuse, composition,
+background work, and calling reusable API orchestration workflows.
+
+Subprocesses inherit authentication context from the parent process. User
+permissions, roles, and auth claims are preserved across the process boundary.
+
+## Definition Input Schema
+
+```json
+{
+  "processName": "count-posts",
+  "processVersion": 1,
+  "waitForCompletion": true,
+  "requestId": "optional-request-id",
+  "correlationId": "optional-correlation-id",
+  "input": {
+    "field": "value"
+  }
+}
+```
+
+Required:
+- `processName`: name of the process definition to execute.
+
+Optional:
+- `processVersion`: process definition version. If omitted, latest is used.
+- `waitForCompletion`: whether to wait for subprocess completion. Defaults to `true`.
+- `requestId`: custom child request id.
+- `correlationId`: custom child correlation id.
+- `input`: object passed to the subprocess.
+
+Minimal:
+
+```json
+{
+  "waitForCompletion": true,
+  "processName": "count-posts"
+}
+```
+
+## Runtime Output Schema
+
+Synchronous output with `waitForCompletion: true`:
+
+```json
+{
+  "subProcessCorrelationId": "bca83c12-ff4b-4260-832a-ab347cf8a360",
+  "subProcessRequestId": "eb21f023-a321-48e4-bcc1-5ff8be726af0",
+  "subProcessId": 28800033,
+  "subProcessOutput": {
+    "result": {
+      "count": 100
+    },
+    "logs": []
+  },
+  "__subProcessMetadata": {
+    "processName": "count-posts",
+    "waitForCompletion": true,
+    "processVersion": 1
+  }
+}
+```
+
+Possible failure output:
+
+```json
+{
+  "subProcessOutput": {
+    "error": "Error message from subprocess"
+  }
+}
+```
+
+Process not found:
+
+```json
+{
+  "error": "The selected sub process name count-posts does not exist in the namespace : default"
+}
+```
+
+## Execution Modes
+
+Synchronous execution, `waitForCompletion: true`:
+- The SUB_PROCESS step waits for the child process to complete.
+- Step remains `RUNNING` while the subprocess runs.
+- Step output includes final `subProcessOutput`.
+- Use this when later steps need the subprocess result.
+- This is the safer default for error handling.
+
+Asynchronous execution, `waitForCompletion: false`:
+- The SUB_PROCESS step starts the child process and immediately continues.
+- Step becomes `COMPLETED` after starting the subprocess.
+- Output contains subprocess metadata, but not the final result.
+- The subprocess continues running in the background.
+- Critical: the SUB_PROCESS step can be `COMPLETED` even if the child process later fails.
+- Use only for fire-and-forget/background operations where the parent does not need the result.
+
+## Status Handling
+
+| Subprocess status | SUB_PROCESS step status | Meaning |
+|-------------------|-------------------------|---------|
+| `COMPLETED` | `COMPLETED` | Child completed successfully |
+| `REVIEWED` | `COMPLETED` | Child completed and reviewed |
+| `TERMINATED` | `COMPLETED` | Child was terminated |
+| `RUNNING` | `RUNNING` | Child is still executing |
+| `FAILED` | `FAILED` | Child encountered an error |
+
+For `waitForCompletion: false`, the parent step completes after launch and does
+not reliably represent the final child status.
+
+## Output Access Paths
+
+Use:
+- `steps.<ref>.output.subProcessOutput` for the child process output.
+- `steps.<ref>.output.subProcessOutput.result` for a child script result object.
+- `steps.<ref>.output.subProcessOutput.result.<field>` for child result fields.
+- `steps.<ref>.output.subProcessId` for the child process id.
+- `steps.<ref>.output.subProcessRequestId` for the child request id.
+- `steps.<ref>.output.subProcessCorrelationId` for the child correlation id.
+- `steps.<ref>.output.__subProcessMetadata.processName` for the called process name.
+- `steps.<ref>.output.error` or `steps.<ref>.output.subProcessOutput.error` for errors.
+
+Do not use:
+- `steps.<ref>.output.result`
+- `steps.<ref>.output.response`
+- `steps.<ref>.output.processId`
+- `steps.<ref>.output.output`
+
+## Generation Rules
+
+- Use uppercase step type: `"SUB_PROCESS"`.
+- Put subprocess configuration in `input`.
+- Always include `processName`.
+- Prefer `waitForCompletion: true` unless the user explicitly wants fire-and-forget behavior.
+- Specify `processVersion` for production stability when the exact version matters.
+- Pass child input under `input.input`.
+- Use `{{ context.input.<field> }}` or `{{ steps.<ref>.output... }}` for dynamic child input values.
+- Do not use `children`; SUB_PROCESS is not a container in the parent definition.
+- Do not assume async subprocess success when `waitForCompletion: false`.
+- Avoid deep nested subprocess chains unless the user explicitly needs composition.
+
+## Debugging Rules
+
+When debugging a SUB_PROCESS:
+- Inspect the SUB_PROCESS step status.
+- Inspect `output.subProcessId` and fetch that child process run if deeper details are needed.
+- Inspect `output.subProcessOutput` for the child result or error.
+- Check `__subProcessMetadata.processName`, `processVersion`, and `waitForCompletion`.
+- If `waitForCompletion: false`, explain that parent completion only means the child was started.
+- If process name is not found, verify namespace and process definition name.
+- If child failed, debug the child process run using its own step records.
+
+Common failures:
+- Missing or wrong `processName`.
+- Assuming latest version is stable in production.
+- Using `waitForCompletion: false` when later steps need the child result.
+- Looking for output at `steps.<ref>.output.result` instead of `subProcessOutput`.
+- Not passing required child input under `input`.
+- Confusing parent process id with `subProcessId`.
+
+## Minimal Process Definition Example
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "kebab-case-name",
+  "version": 1,
+  "type": "API_ORCHESTRATION",
+  "description": "Call the count-posts subprocess.",
+  "configuration": null,
+  "steps": [
+    {
+      "orgId": 1,
+      "namespace": "default",
+      "name": "sub_process",
+      "type": "SUB_PROCESS",
+      "ref": "sub_process_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": {
+        "waitForCompletion": true,
+        "processName": "count-posts"
+      },
+      "output": null
+    }
+  ],
+  "defaultInput": null,
+  "defaultOutput": null,
+  "outputMapping": null,
+  "signature": null,
+  "metadata": null,
+  "tags": null,
+  "dependencies": null,
+  "dependents": null
+}
+```
+
+## Minimal Executed Step Example
+
+```json
+{
+  "id": 28800032,
+  "processId": 28800030,
+  "ref": "sub_process_1",
+  "namespace": "default",
+  "name": "sub_process",
+  "type": "SUB_PROCESS",
+  "status": "COMPLETED",
+  "input": {
+    "processName": "count-posts",
+    "waitForCompletion": true,
+    "__currentExecutionStartTime": 1778184434792
+  },
+  "output": {
+    "subProcessCorrelationId": "bca83c12-ff4b-4260-832a-ab347cf8a360",
+    "subProcessRequestId": "eb21f023-a321-48e4-bcc1-5ff8be726af0",
+    "subProcessId": 28800033,
+    "subProcessOutput": {
+      "result": {
+        "count": 100
+      },
+      "logs": []
+    },
+    "__subProcessMetadata": {
+      "processName": "count-posts",
+      "waitForCompletion": true,
+      "processVersion": 1
+    }
+  }
+}
+```
+
+## Basic Subprocess Call
+
+```json
+{
+  "processName": "getUserProfile",
+  "waitForCompletion": true,
+  "input": {
+    "userId": "{{ context.input.userId }}",
+    "includePreferences": true
+  }
+}
+```
+
+## Asynchronous Subprocess
+
+```json
+{
+  "processName": "emailNotification",
+  "waitForCompletion": false,
+  "input": {
+    "recipient": "{{ context.input.email }}",
+    "template": "welcome"
+  }
+}
+```
+
+## Dynamic Process Selection
+
+```json
+{
+  "processName": "{{ steps.decide_service.output.result.serviceName }}",
+  "processVersion": 2,
+  "waitForCompletion": true,
+  "input": {
+    "data": "{{ context.input.payload }}"
+  }
+}
+```
+

package/knowledge/steps/SWITCH.md

@@ -0,0 +1,369 @@
+# Switch Step Schema
+
+`SWITCH` is a container step that chooses one path from a list of alternatives.
+It evaluates JavaScript, expects the script to return a string case identifier,
+and maps that case to one of its child step refs using `responseMapping`.
+
+The possible cases are the SWITCH step's children. `responseMapping` maps case
+values to those child refs.
+
+## Definition Input Schema
+
+```json
+{
+  "script": "// (steps, context) will be provided as default inputs \n// return a string that maps to a targetRef in responseMapping\n(steps, context) => {\n  const result = context.input.case;\n  if (result === 1) return \"case1\";\n  return \"case2\";\n}\n",
+  "responseMapping": [
+    {
+      "targetRef": "http_1",
+      "value": "case1"
+    },
+    {
+      "targetRef": "http_2",
+      "value": "case2"
+    },
+    {
+      "targetRef": "fallback_step",
+      "defaultBranch": true
+    }
+  ]
+}
+```
+
+Required:
+- `script`: JavaScript function receiving `(steps, context)`.
+- `responseMapping`: array of case-to-child mappings.
+- Each non-default mapping needs `targetRef` and `value`.
+
+Optional:
+- One mapping can include `defaultBranch: true`.
+- `defaultBranch` is used when no `value` matches the script result.
+
+## Runtime Output Schema
+
+The SWITCH output stores the selected case string in `output.result`.
+
+```json
+{
+  "result": "case1",
+  "logs": []
+}
+```
+
+The selected child runs as a child step with `parentRef` set to the SWITCH ref.
+The selected child's output is stored under the child step's own output shape.
+
+```json
+{
+  "ref": "http_1",
+  "parentRef": "switch_1",
+  "type": "HTTP",
+  "output": {
+    "response": {
+      "counter": 5,
+      "randomId": "ce1c8c21-8bbb-4c9e-94ca-1193a66d6933"
+    },
+    "statusCode": 200
+  }
+}
+```
+
+## Output Access Paths
+
+Use:
+- `steps.<switch_ref>.output.result` for the selected case string.
+- `steps.<switch_ref>.output.logs` for captured logs.
+- `steps.<selected_child_ref>.output...` to access the selected child's output.
+- `steps.<http_child_ref>.output.response` for a selected native HTTP child response body.
+- `stepRecords[].parentRef` when debugging executed process data.
+
+Do not use:
+- `steps.<switch_ref>.output.response`
+- `steps.<switch_ref>.output.<child_ref>`
+- `steps.<switch_ref>.children.<child_ref>.output`
+- `steps.<switch_ref>.output.result.<field>` unless the case string is intentionally being treated as a string.
+
+## Generation Rules
+
+- Use uppercase step type: `"SWITCH"`.
+- Put JavaScript code in `input.script`.
+- The script must accept `(steps, context)`.
+- The script must return a string case identifier.
+- `responseMapping[].targetRef` must match a child step `ref`.
+- `responseMapping[].value` must match a possible script return value.
+- Add `defaultBranch: true` when the user needs a fallback path.
+- Child `ref` values must be unique across the whole workflow.
+- If a branch needs multiple sequential steps, use a child `LIST` and map the case to the LIST ref.
+- Do not return objects or booleans from the SWITCH script unless converting them to strings that match `responseMapping`.
+- Do not expect unselected children to run.
+
+## Debugging Rules
+
+When debugging a SWITCH:
+- Inspect `stepRecords[].output.result` to see which case was selected.
+- Confirm the selected case exists in `responseMapping`.
+- Confirm `targetRef` points to a child step of the SWITCH.
+- Inspect only the selected child step record for the executed path.
+- If no child ran, check whether the script return matched a mapping or default branch.
+- If process-level output mirrors a child output, explain which selected child produced it.
+- Use child step type rules to interpret the selected child output.
+
+Common failures:
+- SWITCH script returns a number/boolean/object instead of a string.
+- `responseMapping[].targetRef` does not match a child `ref`.
+- Script returns a value with no mapping and no default branch.
+- Assistant tries to read selected child output from `steps.<switch_ref>.output.response`.
+- A branch needs multiple steps but is modeled as multiple sibling children for one case instead of a child `LIST`.
+- Later steps assume both branches ran.
+
+## Minimal Process Definition Example
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "kebab-case-name",
+  "version": 1,
+  "type": "API_ORCHESTRATION",
+  "description": "Choose one HTTP branch based on input case.",
+  "configuration": null,
+  "steps": [
+    {
+      "orgId": 1,
+      "namespace": "default",
+      "name": "switch",
+      "type": "SWITCH",
+      "ref": "switch_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": [
+        {
+          "orgId": 1,
+          "namespace": "default",
+          "name": "http",
+          "type": "HTTP",
+          "ref": "http_2",
+          "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": "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
+        }
+      ],
+      "input": {
+        "script": "// (steps, context) will be provided as default inputs \n// return a string that maps to a targetRef in responseMapping\n(steps, context) => {\n  const result = context.input.case;\n  if (result === 1) return \"case1\";\n  return \"case2\";\n}\n",
+        "responseMapping": [
+          {
+            "targetRef": "http_1",
+            "value": "case1"
+          },
+          {
+            "targetRef": "http_2",
+            "value": "case2"
+          }
+        ]
+      },
+      "output": null
+    }
+  ],
+  "defaultInput": null,
+  "defaultOutput": null,
+  "outputMapping": null,
+  "signature": null,
+  "metadata": null,
+  "tags": null,
+  "dependencies": null,
+  "dependents": null
+}
+```
+
+## Minimal Executed Step Records Example
+
+SWITCH container step record:
+
+```json
+{
+  "id": 28800028,
+  "processId": 28800026,
+  "ref": "switch_1",
+  "parentId": null,
+  "parentRef": null,
+  "namespace": "default",
+  "name": "switch",
+  "type": "SWITCH",
+  "status": "COMPLETED",
+  "input": {
+    "responseMapping": [
+      {
+        "targetRef": "http_1",
+        "value": "case1"
+      },
+      {
+        "targetRef": "http_2",
+        "value": "case2"
+      }
+    ],
+    "script": "// (steps, context) will be provided as default inputs \n(steps, context) => {\n  const result = context.input.case;\n  if (result === 1) return \"case1\";\n  return \"case2\";\n}\n",
+    "__currentExecutionStartTime": 1778184170808
+  },
+  "output": {
+    "result": "case1",
+    "logs": []
+  }
+}
+```
+
+Selected HTTP child step record:
+
+```json
+{
+  "id": 28800029,
+  "processId": 28800026,
+  "ref": "http_1",
+  "parentId": 28800028,
+  "parentRef": "switch_1",
+  "namespace": "default",
+  "name": "http",
+  "type": "HTTP",
+  "status": "COMPLETED",
+  "output": {
+    "response": {
+      "counter": 5,
+      "randomId": "ce1c8c21-8bbb-4c9e-94ca-1193a66d6933"
+    },
+    "statusCode": 200
+  }
+}
+```
+
+## Example: Branch To LIST Children
+
+Use `LIST` children when a case needs multiple sequential steps:
+
+```json
+{
+  "responseMapping": [
+    {
+      "targetRef": "approved_path",
+      "value": "approved"
+    },
+    {
+      "targetRef": "rejected_path",
+      "value": "rejected"
+    },
+    {
+      "targetRef": "fallback_path",
+      "defaultBranch": true
+    }
+  ]
+}
+```
+