@unstable-dev/unmeshed-mcp 0.1.0

package/knowledge/steps/FOREACH.md

@@ -0,0 +1,250 @@
+# ForEach Step Schema
+
+`FOREACH` is a container step that iterates over an array and runs its child
+steps for each item. Use it when the workflow needs to perform the same work for
+each element in a list.
+
+Each iteration exposes loop variables for child step inputs:
+- `{{foreach.index }}`: zero-based iteration index.
+- `{{foreach.value }}`: current item value.
+
+## Definition Input Schema
+
+```json
+{
+  "inputArray": [1, 2, 3],
+  "concurrency": 1
+}
+```
+
+Required/observed:
+- `inputArray`: array of items to iterate over.
+- `concurrency`: number of iterations that may run concurrently.
+
+The children array of a FOREACH step accepts exactly one direct child step.
+If multiple operations are required for each iteration, wrap them inside a single child LIST step.
+Defining more than one direct child under FOREACH.children is invalid. For Complex Logic Always use `SUB_PROCESS` 
+as a Child.
+
+```json
+{
+  "type": "FOREACH",
+  "ref": "foreach_1",
+  "children": [
+    {
+      "type": "HTTP",
+      "ref": "http_1"
+    }
+  ],
+  "input": {
+    "inputArray": [1, 2, 3],
+    "concurrency": 1
+  }
+}
+```
+
+## Runtime Output Schema
+
+The FOREACH container's own step output is usually an empty object:
+
+```json
+{}
+```
+
+Each child step produces output for each iteration under an indexed ref. For a
+child HTTP step with ref `http_1`, outputs are accessed like:
+
+```javascript
+steps["http_1[0]"].output
+steps["http_1[1]"].output
+steps["http_1[2]"].output
+```
+
+Native HTTP child output keeps the HTTP output shape per iteration:
+
+```json
+{
+  "response": {
+    "counter": 1,
+    "randomId": "..."
+  },
+  "statusCode": 200
+}
+```
+
+## Output Access Paths
+
+Use inside child input templates:
+- `{{foreach.index }}` for the current zero-based index.
+- `{{foreach.value }}` for the current item value.
+
+Use after FOREACH completes:
+- `steps["<child_ref>[0]"].output` for the first iteration child output.
+- `steps["<child_ref>[1]"].output` for the second iteration child output.
+- `steps["<http_child_ref>[0]"].output.response` for native HTTP response body from iteration 0.
+- `steps["<javascript_child_ref>[0]"].output.result` for JavaScript result from iteration 0.
+- `steps["<python_child_ref>[0]"].output.result` for Python result from iteration 0.
+
+Do not use after the loop:
+- `steps.<foreach_ref>.output.result`
+- `steps.<foreach_ref>.output.response`
+- `steps.<foreach_ref>.output.<child_ref>`
+- `steps.<child_ref>.output` when reading iteration output after FOREACH; use indexed refs instead.
+
+## Generation Rules
+
+- Use uppercase step type: `"FOREACH"`.
+- Put loop body steps in `children`.
+- Provide `input.inputArray`.
+- Provide `input.concurrency`.
+- Use `concurrency: 1` when order/rate limiting matters.
+- Increase `concurrency` only when iterations are independent and safe to run concurrently.
+- Use `{{foreach.index }}` and `{{foreach.value }}` in child step inputs when the current item/index is needed.
+- Child `ref` values must be unique across the whole workflow definition.
+- After the loop, collect child results using indexed refs like `steps["http_1[0]"].output`.
+- If each iteration needs multiple sequential steps, put a `LIST` as the FOREACH child/body.
+
+## Debugging Rules
+
+When debugging a FOREACH:
+- Inspect `input.inputArray` to confirm the expected items.
+- Inspect `input.concurrency` to understand scheduling/concurrency behavior.
+- Inspect child step records for each iteration.
+- Use indexed refs to reason about per-iteration child outputs.
+- If only some iterations failed, identify the failing index and current `foreach.value`.
+- Do not stop at the FOREACH container's own `output: {}`; inspect iteration child outputs.
+
+Common failures:
+- Missing or non-array `inputArray`.
+- Referencing `foreach.value` outside a FOREACH child input/script context.
+- Reading post-loop results from `steps.http_1.output` instead of `steps["http_1[0]"].output`.
+- Setting concurrency too high for rate-limited external APIs.
+- Assuming results are a single aggregated array when they are exposed as indexed child refs.
+- Child refs collide with refs elsewhere in the workflow.
+
+## Minimal Process Definition Example
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "kebab-case-name",
+  "version": 1,
+  "type": "API_ORCHESTRATION",
+  "description": "Call an HTTP endpoint for each input item.",
+  "configuration": null,
+  "steps": [
+    {
+      "orgId": 1,
+      "namespace": "default",
+      "name": "foreach",
+      "type": "FOREACH",
+      "ref": "foreach_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_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",
+              "index": "{{foreach.index }}",
+              "value": "{{foreach.value }}"
+            },
+            "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": {
+        "inputArray": [1, 2, 3],
+        "concurrency": 1
+      },
+      "output": null
+    }
+  ],
+  "defaultInput": null,
+  "defaultOutput": null,
+  "outputMapping": null,
+  "signature": null,
+  "metadata": null,
+  "tags": null,
+  "dependencies": null,
+  "dependents": null
+}
+```
+
+## Example: Collect FOREACH Results
+
+Use indexed child refs in a later JavaScript step:
+
+```javascript
+(steps, context) => {
+  const outputs = [];
+  for (let i = 0; i < 3; i += 1) {
+    outputs.push(steps[`http_1[${i}]`].output.response);
+  }
+  return { outputs };
+}
+```
+

package/knowledge/steps/HTTP.md

@@ -0,0 +1,183 @@
+# HTTP Step Schema
+
+Native `HTTP` steps call REST endpoints directly from a process definition.
+Use `HTTP` when the workflow needs a direct request with standard method, URL,
+headers, query params, optional JSON body, and optional polling.
+
+This is different from an `INTEGRATION` step whose `input.type` may be `http`.
+Native HTTP step type is uppercase: `"type": "HTTP"`.
+
+## Definition Input Schema
+
+GET request:
+
+```json
+{
+  "method": "GET",
+  "url": "https://api.example.com/resource",
+  "headers": {
+    "Accept": "application/json"
+  },
+  "params": {},
+  "repeatUntilEnabled": null,
+  "repeatUntilCondition": { "script": "(steps, context) => { return false; }" },
+  "repeatIntervalSeconds": null,
+  "maxRepeatCount": null,
+  "includeFullResponseString": false,
+  "noEncode": false,
+  "extraLongTimeouts": false
+}
+```
+
+POST, PUT, PATCH, or DELETE request with JSON body:
+
+```json
+{
+  "method": "POST",
+  "url": "https://api.example.com/resource",
+  "headers": {
+    "Content-Type": "application/json",
+    "Accept": "application/json"
+  },
+  "params": {},
+  "body": {
+    "type": "json",
+    "content": {
+      "field": "value"
+    }
+  },
+  "repeatUntilEnabled": null,
+  "repeatUntilCondition": { "script": "(steps, context) => { return false; }" },
+  "repeatIntervalSeconds": null,
+  "maxRepeatCount": null,
+  "includeFullResponseString": false,
+  "noEncode": false,
+  "extraLongTimeouts": false
+}
+```
+
+## Runtime Output Schema
+
+Native HTTP stores the parsed response body in `output.response`.
+
+```json
+{
+  "response": {},
+  "statusCode": 200
+}
+```
+
+If the endpoint returns an array, `response` is the array:
+
+```json
+{
+  "response": [
+    { "id": 1 },
+    { "id": 2 }
+  ],
+  "statusCode": 200
+}
+```
+
+## Output Access Paths
+
+Use:
+- `steps.<ref>.output.response` for the full parsed response body.
+- `steps.<ref>.output.response.<field>` for object response fields.
+- `steps.<ref>.output.response.length` for array response count.
+- `steps.<ref>.output.statusCode` for HTTP status code.
+
+Do not use:
+- `steps.<ref>.output.result`
+- `steps.<ref>.output.results`
+- `steps.<ref>.output.status`
+
+## Generation Rules
+
+- Use uppercase step type: `"HTTP"`.
+- Use `params: {}` even when there are no query parameters.
+- Omit `body` for normal GET requests.
+- Use `body: { "type": "json", "content": { ... } }` for JSON request bodies.
+- Use `{{variables.<name>}}` for environment-specific URLs or config.
+- Use `{{secrets.<name>}}` for tokens, API keys, and credentials.
+- Never hardcode credentials.
+- For non-polling requests, set `repeatUntilEnabled`, `repeatIntervalSeconds`, and `maxRepeatCount` to `null`.
+- If `repeatUntilEnabled` is `true`, provide a safe `repeatUntilCondition.script` using optional chaining.
+- When `configuration.jqTransformer` is set, the HTTP output is replaced with `output.transformed`. The pre-JQ-transform output is omitted by default; set input `includePreJqTransformOutput: true` only when the raw step output should also be stored as `output.preJqTransformOutput`.
+
+## Debugging Rules
+
+When a later step fails after an HTTP step:
+- Inspect `steps.<http_ref>.output.response` first.
+- Check whether the response is an object or array.
+- Check `steps.<http_ref>.output.statusCode`.
+- If a script reads `steps.<http_ref>.output.result`, explain that native HTTP uses `output.response`.
+- If the HTTP step failed, summarize the status code and response body if available.
+
+Common failures:
+- JavaScript step reads `output.result` instead of `output.response`.
+- Script assumes response is an array but endpoint returned an object.
+- Script assumes response is an object but endpoint returned an array.
+- Missing `Content-Type: application/json` for JSON body requests.
+- Token was hardcoded instead of using `{{secrets.<name>}}`.
+
+## Minimal Example: Count Posts
+
+HTTP step:
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "fetch_posts",
+  "type": "HTTP",
+  "ref": "fetch_posts_1",
+  "optional": false,
+  "createdBy": "system",
+  "updatedBy": "system",
+  "description": "Fetch posts from JSONPlaceholder.",
+  "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": "https://jsonplaceholder.typicode.com/posts",
+    "headers": {
+      "Accept": "application/json"
+    },
+    "params": {},
+    "repeatUntilEnabled": null,
+    "repeatUntilCondition": { "script": "(steps, context) => { return false; }" },
+    "repeatIntervalSeconds": null,
+    "maxRepeatCount": null,
+    "includeFullResponseString": false,
+    "noEncode": false,
+    "extraLongTimeouts": false
+  },
+  "output": null
+}
+```
+
+JavaScript step after it:
+
+```javascript
+(steps, context) => {
+  const posts = steps.fetch_posts_1.output.response || [];
+  return { count: Array.isArray(posts) ? posts.length : 0 };
+}
+```

package/knowledge/steps/JAVASCRIPT.md

@@ -0,0 +1,192 @@
+# JavaScript Step Schema
+
+`JAVASCRIPT` steps run inline JavaScript inside a process definition. Use them
+for data mapping, transformation, validation, assertions, branching helpers,
+and small deterministic calculations.
+
+JavaScript steps receive two default inputs:
+- `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": "// (steps, context) will be provided as default inputs \n(steps, context) => {\n  return {\n    \"processId\": context.id,\n    \"currentStepId\": steps.__self.id\n  };\n}"
+}
+```
+
+## Runtime Output Schema
+
+The JavaScript function's returned value is stored in `output.result`.
+
+```json
+{
+  "result": {
+    "processId": 28800004,
+    "currentStepId": {
+      "ref": "javascript_1",
+      "processId": 28800004,
+      "id": 28800006
+    }
+  },
+  "logs": []
+}
+```
+
+Process-level output for a single JavaScript-step workflow can mirror the
+JavaScript step output:
+
+```json
+{
+  "result": {
+    "processId": 28800004
+  },
+  "logs": []
+}
+```
+
+## Output Access Paths
+
+Use:
+- `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.
+- `steps.__self.id` inside the running script for the current step id object.
+- `context.id` inside the running script for the process id.
+- `context.input.<field>` inside the running script for process input.
+
+Do not use:
+- `steps.<ref>.output.response`
+- `steps.<ref>.output.results`
+- `steps.<ref>.output.<field>` for returned object fields
+
+## Generation Rules
+
+- Use uppercase step type: `"JAVASCRIPT"`.
+- Put executable code in `input.script`.
+- The script must be an arrow function or function-like JavaScript body that accepts `(steps, context)`.
+- The script should explicitly `return` the value that later steps need.
+- Prefer returning an object, even for one value, so later references are stable.
+- Keep scripts deterministic and side-effect free.
+- Use JavaScript optional chaining when reading uncertain upstream outputs.
+- Read native HTTP responses from `steps.<http_ref>.output.response`, not `output.result`.
+- Read JavaScript or Python results from `steps.<ref>.output.result`.
+- Do not hardcode secrets or credentials in scripts.
+
+## Debugging Rules
+
+When a JavaScript step fails:
+- Inspect the step record's `input.script`.
+- Inspect the previous step outputs referenced by the script.
+- Verify output 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 JavaScript step's `stepRecords[].output`.
+
+Common failures:
+- Missing `return`.
+- Referencing native HTTP output as `steps.<http_ref>.output.result`.
+- Assuming an upstream value is an array without checking `Array.isArray`.
+- Returning a primitive when later steps expect object fields.
+- Syntax errors from trailing commas in environments that do not support them.
+- Accessing `steps.<ref>.output.result.<field>` when the previous JavaScript step returned a primitive.
+
+## Minimal Process Definition Example
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "kebab-case-name",
+  "version": 1,
+  "type": "API_ORCHESTRATION",
+  "description": "Return process and current step ids.",
+  "configuration": null,
+  "steps": [
+    {
+      "orgId": 1,
+      "namespace": "default",
+      "name": "javascript",
+      "type": "JAVASCRIPT",
+      "ref": "javascript_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": "// (steps, context) will be provided as default inputs \n(steps, context) => {\n  return {\n    \"processId\": context.id,\n    \"currentStepId\": steps.__self.id\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": 28800006,
+  "processId": 28800004,
+  "ref": "javascript_1",
+  "namespace": "default",
+  "name": "javascript",
+  "type": "JAVASCRIPT",
+  "status": "COMPLETED",
+  "input": {
+    "script": "// (steps, context) will be provided as default inputs \n(steps, context) => {\n  return {\n    \"processId\": context.id,\n    \"currentStepId\": steps.__self.id\n  };\n}",
+    "__currentExecutionStartTime": 1778182609428
+  },
+  "output": {
+    "result": {
+      "currentStepId": {
+        "ref": "javascript_1",
+        "processId": 28800004,
+        "id": 28800006
+      },
+      "processId": 28800004
+    },
+    "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:
+
+```javascript
+(steps, context) => {
+  const posts = steps.fetch_posts_1.output.response || [];
+  return { count: Array.isArray(posts) ? posts.length : 0 };
+}
+```
+