@unstable-dev/unmeshed-mcp 0.1.0

package/knowledge/steps/PARALLEL.md

@@ -0,0 +1,366 @@
+# Parallel Step Schema
+
+`PARALLEL` is a container step that runs multiple child step paths at the same
+time. Use it when one path does not depend on another path's result and both can
+progress independently.
+
+Example use case: fetch search results from two external sources concurrently,
+then merge both outputs in a later JavaScript step after the parallel children
+complete.
+
+Container steps can be nested. Use `LIST` children inside a `PARALLEL` step when
+one parallel path needs to run multiple steps sequentially.
+
+## Execution Semantics
+
+Unmeshed parallel steps do not immediately abandon all work when one parallel
+thread fails. The engine completes all parallel threads and then marks the
+parallel step/process failed if failure rules require it. This avoids leaving
+tasks hanging or partially complete.
+
+## Definition Input Schema
+
+The parallel paths are defined in `children`.
+
+The example runtime input may include `failIfAnyBranchFails`:
+
+```json
+{
+  "failIfAnyBranchFails": false
+}
+```
+
+`children` contains the steps or branch containers to run concurrently:
+
+```json
+{
+  "type": "PARALLEL",
+  "ref": "parallel_1",
+  "children": [
+    {
+      "type": "HTTP",
+      "ref": "http_1"
+    },
+    {
+      "type": "HTTP",
+      "ref": "http_2"
+    }
+  ],
+  "input": {
+    "failIfAnyBranchFails": false
+  }
+}
+```
+
+## Runtime Output Schema
+
+The PARALLEL container's own step output is usually an empty object:
+
+```json
+{}
+```
+
+Child steps produce their own outputs under their own refs. For example, HTTP
+children inside a PARALLEL still expose:
+
+```json
+{
+  "response": {
+    "randomId": "abb5ca43-3835-4dae-8556-b72aa4d42e64",
+    "counter": 2
+  },
+  "statusCode": 200
+}
+```
+
+In process run records, child steps are linked back to the PARALLEL by
+`parentId` and `parentRef`.
+
+```json
+{
+  "ref": "http_1",
+  "parentRef": "parallel_1",
+  "type": "HTTP",
+  "status": "COMPLETED"
+}
+```
+
+## Output Access Paths
+
+Use:
+- `steps.<child_ref>.output...` to access a child step's output directly.
+- `steps.<http_child_ref>.output.response` for a native HTTP child response body.
+- `steps.<javascript_child_ref>.output.result` for a JavaScript child result.
+- `steps.<python_child_ref>.output.result` for a Python child result.
+- `stepRecords[].parentRef` when debugging executed process data.
+
+Do not use:
+- `steps.<parallel_ref>.output.result`
+- `steps.<parallel_ref>.output.response`
+- `steps.<parallel_ref>.children.<child_ref>.output`
+- `steps.<parallel_ref>.output.<child_ref>`
+
+## Generation Rules
+
+- Use uppercase step type: `"PARALLEL"`.
+- Put independent child paths in `children`.
+- Use `input: { "failIfAnyBranchFails": false }` when matching the observed example behavior.
+- Children must be complete step definitions with the same required fields as top-level steps.
+- Child `ref` values must be unique across the whole workflow, not only inside the PARALLEL.
+- Use child `LIST` containers when a parallel branch requires multiple sequential steps.
+- Do not put dependent steps directly as sibling children if one needs another child's output.
+- Add a later merge/normalize step after PARALLEL if the workflow needs to combine child outputs.
+- Do not invent a special PARALLEL result wrapper for child outputs.
+- Later steps should reference child outputs by child refs directly.
+
+## Debugging Rules
+
+When debugging a PARALLEL:
+- Check the PARALLEL step record status first.
+- Inspect child step records whose `parentRef` equals the PARALLEL ref.
+- Inspect all failed child records, not only the first one.
+- Remember that Unmeshed completes all parallel children before failing the PARALLEL due to child failures.
+- Do not stop at the PARALLEL step's own `output: {}`; inspect child outputs.
+- If process-level output mirrors one child output, explain which child produced it.
+- Use child step type rules to interpret child outputs.
+
+Common failures:
+- Assistant tries to read child output from `steps.<parallel_ref>.output.result`.
+- A child step fails but the explanation only mentions the PARALLEL container.
+- A later step assumes child execution order inside PARALLEL.
+- A child depends on another child result even though they run concurrently.
+- Duplicate child refs collide with refs elsewhere in the workflow.
+- A multi-step parallel path is modeled as sibling children instead of a child `LIST`.
+
+## Minimal Process Definition Example
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "kebab-case-name",
+  "version": 1,
+  "type": "API_ORCHESTRATION",
+  "description": "Run two HTTP calls concurrently.",
+  "configuration": null,
+  "steps": [
+    {
+      "orgId": 1,
+      "namespace": "default",
+      "name": "parallel",
+      "type": "PARALLEL",
+      "ref": "parallel_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": "POST",
+            "url": "http://localhost:8080/api/test/post",
+            "headers": {
+              "Content-Type": "application/json",
+              "Accept": "application/json",
+              "Authorization": "Bearer {{secrets.test_token}}"
+            },
+            "params": {
+              "sampleKey": "sampleValue"
+            },
+            "body": {
+              "type": "json",
+              "content": {
+                "title": "foo",
+                "body": "bar",
+                "userId": 1
+              }
+            },
+            "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": {
+        "failIfAnyBranchFails": false
+      },
+      "output": null
+    }
+  ],
+  "defaultInput": null,
+  "defaultOutput": null,
+  "outputMapping": null,
+  "signature": null,
+  "metadata": null,
+  "tags": null,
+  "dependencies": null,
+  "dependents": null
+}
+```
+
+## Minimal Executed Step Records Example
+
+PARALLEL container step record:
+
+```json
+{
+  "id": 28800016,
+  "processId": 28800014,
+  "ref": "parallel_1",
+  "parentId": null,
+  "parentRef": null,
+  "namespace": "default",
+  "name": "parallel",
+  "type": "PARALLEL",
+  "status": "COMPLETED",
+  "input": {
+    "failIfAnyBranchFails": false,
+    "__currentExecutionStartTime": 1778183464807
+  },
+  "output": {},
+  "optional": false
+}
+```
+
+HTTP child step record:
+
+```json
+{
+  "id": 28800018,
+  "processId": 28800014,
+  "ref": "http_1",
+  "parentId": 28800016,
+  "parentRef": "parallel_1",
+  "namespace": "default",
+  "name": "http",
+  "type": "HTTP",
+  "status": "COMPLETED",
+  "output": {
+    "response": {
+      "counter": 2,
+      "randomId": "abb5ca43-3835-4dae-8556-b72aa4d42e64"
+    },
+    "statusCode": 200
+  },
+  "optional": false
+}
+```
+
+## Example: Merge Outputs After PARALLEL
+
+Use child refs directly in a later JavaScript step:
+
+```javascript
+(steps, context) => {
+  const getResult = steps.http_1.output.response || {};
+  const postResult = steps.http_2.output.response || {};
+  return {
+    getCounter: getResult.counter,
+    postCounter: postResult.counter,
+    randomIds: [getResult.randomId, postResult.randomId].filter(Boolean)
+  };
+}
+```
+

package/knowledge/steps/PYTHON.md

@@ -0,0 +1,206 @@
+# Python Step Schema
+
+`PYTHON` steps run inline Python inside a process definition. Use them for file
+I/O, base64 or binary handling, data transformation, validation, assertions,
+and Python-friendly utility logic.
+
+Python steps receive two default dictionary arguments:
+- `steps`: runtime data for the current step and previously executed steps.
+- `context`: runtime process context, including process id, input, state, and metadata.
+
+## Definition Input Schema
+
+```json
+{
+  "script": "# Do not change the parameters count, order, or types.\n# The parameter names must remain the same.\n# `steps` and `context` are Python dictionaries provided by default.\ndef main(steps, context):\n    return {\n        \"processId\": context.get(\"id\"),\n        \"currentStepId\": steps[\"__self\"][\"id\"],\n        \"statusMessage\": \"Process completed\",\n        \"isSuccessful\": True\n    }\n"
+}
+```
+
+## Runtime Output Schema
+
+The Python `main` function's returned value is stored in `output.result`.
+
+```json
+{
+  "result": {
+    "processId": 28800007,
+    "currentStepId": {
+      "ref": "python_1",
+      "processId": 28800007,
+      "id": 28800009
+    },
+    "statusMessage": "Process completed",
+    "isSuccessful": true
+  },
+  "logs": []
+}
+```
+
+Process-level output for a single Python-step workflow can mirror the Python
+step output:
+
+```json
+{
+  "result": {
+    "processId": 28800007,
+    "statusMessage": "Process completed",
+    "isSuccessful": true
+  },
+  "logs": []
+}
+```
+
+## Output Access Paths
+
+Use from later JavaScript/template steps:
+- `steps.<ref>.output.result` for the complete returned value.
+- `steps.<ref>.output.result.<field>` for returned object fields.
+- `steps.<ref>.output.logs` for captured logs.
+
+Use inside Python scripts:
+- `context.get("id")` for the process id.
+- `context.get("input", {}).get("<field>")` for process input fields.
+- `steps["__self"]["id"]` for the current step id object.
+- `steps["<ref>"]["output"]["result"]` for previous Python or JavaScript result output.
+- `steps["<http_ref>"]["output"]["response"]` for previous native HTTP response body.
+
+Do not use:
+- `steps.<ref>.output.response` for Python step output.
+- `steps.<ref>.output.results` for Python step output.
+- `steps.<ref>.output.<field>` for returned object fields.
+- `steps["<http_ref>"]["output"]["result"]` for native HTTP output.
+
+## Generation Rules
+
+- Use uppercase step type: `"PYTHON"`.
+- Put executable code in `input.script`.
+- Define exactly `def main(steps, context):`.
+- Do not change the parameter count, order, names, or expected dictionary types.
+- The script should explicitly `return` the value that later steps need.
+- Prefer returning a dictionary, even for one value, so later references are stable.
+- Use safe dictionary access with `.get()` when reading uncertain keys.
+- Read native HTTP responses from `steps["<http_ref>"]["output"]["response"]`, not `result`.
+- Read JavaScript or Python results from `steps["<ref>"]["output"]["result"]`.
+- Do not hardcode secrets or credentials in scripts.
+
+## Debugging Rules
+
+When a Python step fails:
+- Inspect the step record's `input.script`.
+- Confirm it defines `def main(steps, context):`.
+- Inspect the previous step outputs referenced by the script.
+- Verify dictionary paths against each referenced step type.
+- If the script reads an HTTP step with `["output"]["result"]`, explain that native HTTP uses `["output"]["response"]`.
+- If the script returns nothing, explain that `output.result` will be missing or null.
+- If process output is unexpected, compare process-level `output` with the Python step's `stepRecords[].output`.
+
+Common failures:
+- Missing `def main(steps, context):`.
+- Missing `return`.
+- Changing parameter names or order.
+- Referencing native HTTP output as `steps["<http_ref>"]["output"]["result"]`.
+- Assuming an upstream value is a list without checking `isinstance(value, list)`.
+- Returning a primitive when later steps expect object fields.
+- Key errors from direct dictionary indexing on optional data.
+
+## Minimal Process Definition Example
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "kebab-case-name",
+  "version": 1,
+  "type": "API_ORCHESTRATION",
+  "description": "Return process status fields from Python.",
+  "configuration": null,
+  "steps": [
+    {
+      "orgId": 1,
+      "namespace": "default",
+      "name": "python",
+      "type": "PYTHON",
+      "ref": "python_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": "# Do not change the parameters count, order, or types.\n# The parameter names must remain the same.\n# `steps` and `context` are Python dictionaries provided by default.\ndef main(steps, context):\n    return {\n        \"processId\": context.get(\"id\"),\n        \"currentStepId\": steps[\"__self\"][\"id\"],\n        \"statusMessage\": \"Process completed\",\n        \"isSuccessful\": True\n    }\n"
+      },
+      "output": null
+    }
+  ],
+  "defaultInput": null,
+  "defaultOutput": null,
+  "outputMapping": null,
+  "signature": null,
+  "metadata": null,
+  "tags": null,
+  "dependencies": null,
+  "dependents": null
+}
+```
+
+## Minimal Executed Step Example
+
+```json
+{
+  "id": 28800009,
+  "processId": 28800007,
+  "ref": "python_1",
+  "namespace": "default",
+  "name": "python",
+  "type": "PYTHON",
+  "status": "COMPLETED",
+  "input": {
+    "script": "# Do not change the parameters count, order, or types.\n# The parameter names must remain the same.\n# `steps` and `context` are Python dictionaries provided by default.\ndef main(steps, context):\n    return {\n        \"processId\": context.get(\"id\"),\n        \"currentStepId\": steps[\"__self\"][\"id\"],\n        \"statusMessage\": \"Process completed\",\n        \"isSuccessful\": True\n    }\n",
+    "__currentExecutionStartTime": 1778182855381
+  },
+  "output": {
+    "result": {
+      "currentStepId": {
+        "ref": "python_1",
+        "processId": 28800007,
+        "id": 28800009
+      },
+      "isSuccessful": true,
+      "processId": 28800007,
+      "statusMessage": "Process completed"
+    },
+    "logs": []
+  }
+}
+```
+
+## Example: Count Native HTTP Response Array
+
+Use this when a previous native `HTTP` step with ref `fetch_posts_1` returns an
+array response body:
+
+```python
+def main(steps, context):
+    posts = steps.get("fetch_posts_1", {}).get("output", {}).get("response", [])
+    return {
+        "count": len(posts) if isinstance(posts, list) else 0
+    }
+```
+