@unstable-dev/unmeshed-mcp 0.1.0

package/knowledge/step-definition.schema.md

@@ -0,0 +1,140 @@
+# Step Definition Schema
+
+Every Unmeshed step must follow this shared structure.
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "step_name",
+  "type": "HTTP",
+  "ref": "unique_step_ref",
+  "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": {},
+  "output": null
+}
+```
+
+Rules:
+- `type` must be a valid Unmeshed step type.
+- `ref` must be unique and should be stable because later steps reference it.
+- `children` is `[]` for non-container steps.
+- Container steps such as `LIST`, `PARALLEL`, `FOREACH`, `WHILE`, and `SWITCH` may contain child steps.
+- `input` must match the selected step type's schema.
+- `configuration` must include the full standard block unless a backend-specific exception is documented.
+- Do not put runtime outputs in the definition-time `output` field; keep it `null`.
+- `preExecutionScript` - use this for run a Script before actual task executes ,The output of the script would be overridden as steps input keys during runtime. We call this as Scripted input too
+- `scriptLanguage` - Available script languages are JAVASCRIPT/PYTHON. By default it is Javascript
+- `constructInputFromScript` - always enable this Flag while running preExecutionScript, otherwise it won't work.
+
+
+## Pre-Execution Script
+
+A **preExecutionScript** lets you run custom logic *before* a step's main task executes.
+The script's return value is merged into the step's `input`, so downstream logic (and the step itself) sees those keys as if they were part of the original input. We also call this **Scripted Input**.
+
+### How to enable
+
+| Field | Required value | Purpose |
+|---|---|---|
+| `preExecutionScript` | The script source code (string) | The code to run |
+| `constructInputFromScript` | `true` | **Must** be `true`, otherwise the script is ignored |
+| `scriptLanguage` | `"JAVASCRIPT"` or `"PYTHON"` | Defaults to `JAVASCRIPT` if omitted |
+
+### Implicit parameters
+
+Every pre-execution script receives two implicit arguments:
+
+| Parameter | Type | Description |
+|---|---|---|
+| `steps` | object / dict | A map keyed by step `ref`. `steps.__self` (JS) or `steps["__self"]` (Python) is the current step's metadata, including its `id`, `processId`, and `ref`. Other completed steps are accessible by their ref. |
+| `context` | object / dict | The current process execution context. `context.id` (JS) / `context.get("id")` (Python) gives the `processId`. Also contains `input`, `state`, etc. |
+
+### Return value
+
+The script **must return a JSON-serialisable object (dict/map)**.
+Each key in the returned object is merged into the step's `input` before the step runs.
+Any `console.log` (JS) or `print` (Python) calls are captured in the `preExecutionScriptLogs` array that is also added to the step input/output automatically.
+
+### JavaScript example
+
+```javascript
+// (steps, context) will be provided as default inputs
+(steps, context) => {
+    console.log("Hello World !!")
+    console.log("Hello World 2 !!")
+    return {
+        "processId" : context.id,
+        "currentStepId" : steps.__self.id,
+    }
+}
+```
+
+### Python example
+
+```python
+# Do not change the parameters count, order, or types.
+# `steps` and `context` are Python dictionaries provided by default.
+def main(steps, context):
+    print("Hello World !!")
+    print("Hello World 2 !!")
+    return {
+        "processId": context.get("id"),
+        "currentStepId": steps["__self"]["id"],
+        "statusMessage": "Process completed",
+        "isSuccessful": True
+    }
+```
+
+### What the step input looks like at runtime
+
+After the script runs, the step's `input` will contain:
+
+1. All keys returned by the script (e.g. `processId`, `currentStepId`, `statusMessage`, `isSuccessful`).
+2. `preExecutionScriptLogs` — an array of `{ "log": "...", "time": 0 }` objects capturing every `console.log` / `print` call.
+3. `__currentExecutionStartTime` — epoch-millis timestamp injected automatically by the engine.
+
+Example runtime step input (Python step):
+
+```json
+{
+  "processId": 593065015,
+  "currentStepId": { "ref": "noop_1_copy", "processId": 593065015, "id": 593065018 },
+  "statusMessage": "Process completed",
+  "isSuccessful": true,
+  "preExecutionScriptLogs": [
+    { "log": "Hello World !!", "time": 0 },
+    { "log": "Hello World 2 !!", "time": 0 }
+  ],
+  "__currentExecutionStartTime": 1778220339534
+}
+```
+
+### Rules
+
+- Always set `constructInputFromScript: true` when providing a `preExecutionScript`.
+- The script must be self-contained — no external imports or network calls.
+- Python scripts must define a `main(steps, context)` function; the engine calls `main`.
+- JavaScript scripts must be an arrow/anonymous function that accepts `(steps, context)`.
+- Return only JSON-serialisable types (strings, numbers, booleans, lists, maps). Do not return classes or functions.

package/knowledge/step-output-paths.md

@@ -0,0 +1,45 @@
+# Step Output Path Contract
+
+Always reference a previous step according to the producer step type.
+
+| Producer step type | Runtime output path |
+|--------------------|---------------------|
+| `HTTP` | `steps.<ref>.output.response` for parsed response body; `steps.<ref>.output.statusCode` for HTTP status |
+| `JQ` | `steps.<ref>.output.result` for the jq result |
+| `JAVASCRIPT` | `steps.<ref>.output.result` for the returned value; `steps.<ref>.output.logs` for captured logs |
+| `PYTHON` | `steps.<ref>.output.result` for the returned value; `steps.<ref>.output.logs` for captured logs |
+| `FLOW_GATEWAY` | `steps.<ref>.output.result` for the selected control-flow case string; `steps.<ref>.output.logs` for script logs |
+| `NOOP` | `steps.<ref>.output.<field>` |
+| `SEND_RESPONSE` | Usually `steps.<ref>.output` is `{}` on success; inspect process-level output for the returned payload; inspect `steps.<ref>.output.error` only for step failure |
+| `LIST` | Usually `steps.<ref>.output` is `{}`; reference child step outputs directly by child `ref` |
+| `PARALLEL` | Usually `steps.<ref>.output` is `{}`; reference child step outputs directly by child `ref` |
+| `FOREACH` | Usually `steps.<ref>.output` is `{}`; iteration child outputs use `steps["<child_ref>[<index>]"].output` |
+| `WHILE` | `steps.<ref>.output.result` for final condition result; `steps.<ref>.output.iteration` for final iteration count |
+| `WAIT` | `steps.<ref>.output.result.waitUntil` for the resume timestamp; `steps.<ref>.output.__waitStartedAt` for wait start |
+| `SWITCH` | `steps.<ref>.output.result` for the selected case string; selected child output is under the child `ref` |
+| `SUB_PROCESS` | `steps.<ref>.output.subProcessOutput` for child output; `steps.<ref>.output.subProcessId` for child process id |
+| `EXIT` | `steps.<ref>.output.__exitStatus`, `steps.<ref>.output.__exitReason`, and `steps.<ref>.output.message` |
+| `WORKER` | `steps.<ref>.output.<field>` directly from the external worker result |
+| `PERSISTED_STATE` | `steps.<ref>.output.result` |
+| `INTEGRATION` | Integration-specific; commonly `steps.<ref>.output.result` or `steps.<ref>.output.results` |
+
+Validation rules:
+- Never use `steps.<http_ref>.output.result` for a native `HTTP` step.
+- Never use `steps.<http_ref>.output.results` for a native `HTTP` step.
+- Never use `steps.<jq_ref>.output.response` for a `JQ` step.
+- Never use `steps.<javascript_ref>.output.response` for a `JAVASCRIPT` step.
+- Never use `steps.<python_ref>.output.response` for a `PYTHON` step.
+- Never expect `FLOW_GATEWAY` output to contain the chosen branch payload; it only stores the selected case string and logs.
+- Never expect `SEND_RESPONSE` to expose the successful response payload under `steps.<send_response_ref>.output.result`; it mutates process-level output instead.
+- Never expect a `LIST` step to wrap child outputs under `steps.<list_ref>.output.result`.
+- Never expect a `PARALLEL` step to wrap child outputs under `steps.<parallel_ref>.output.result`.
+- Never create a `WAIT` script that omits `waitUntil`.
+- Never expect a `SWITCH` step to return the selected child output; it returns the selected case string.
+- Never use `steps.<sub_process_ref>.output.result` for subprocess output; use `subProcessOutput`.
+- Never expect an `EXIT` step to continue later sibling steps after it exits the process.
+- Never assume `WORKER` output is wrapped in `output.result`; worker result object fields are exposed directly.
+- Never read FOREACH child output as plain `steps.<child_ref>.output` after the loop; use indexed refs like `steps["<child_ref>[0]"].output`.
+- Never create a `WHILE` script without a clear false condition; avoid endless loops.
+- Never wrap NOOP output in `output.result`; NOOP input fields are copied directly to output.
+- When an `HTTP` response is an array, use `steps.<http_ref>.output.response.length`.
+- Before saving a generated workflow, check every `steps.<ref>.output...` reference against the referenced step's type.

package/knowledge/steps/DECISION_ENGINE.md

@@ -0,0 +1,248 @@
+# DECISION_ENGINE Step Schema
+
+`DECISION_ENGINE` evaluates a row of input values against a named decision table
+(rule engine) and returns the matching output columns. Use it for rule-based
+routing, classification, or lookup where the rules live in a managed table.
+
+## Definition Input Schema
+
+```json
+{
+  "decisionRuleStrategy": "FIRST_MATCH",
+  "decisionTable": "clothes-decision-table",
+  "decisionContext": {
+    "clothes": "tshirt"
+  },
+  "decisionTableVersion": "",
+  "decisionOutputColumns": [
+    "fabric"
+  ]
+}
+```
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `decisionRuleStrategy` | string | Yes | `"FIRST_MATCH"` — return the first matching rule. `"ALL_MATCH"` — return every matching rule. |
+| `decisionTable` | string | Yes | Name of the decision table configured in Unmeshed. |
+| `decisionContext` | object | Yes | Key-value pairs whose keys must match input column names in the decision table. Values can be literals or `{{...}}` template expressions. |
+| `decisionTableVersion` | string | No | Specific version of the table. Leave as `""` to use the latest version. |
+| `decisionOutputColumns` | string[] | Yes | List of output column names to return from the matched rule(s). |
+
+## Runtime Output Schema
+
+### FIRST_MATCH output
+
+`result` is a **single object** containing the output columns from the first matched rule.
+
+```json
+{
+  "result": {
+    "fabric": "Cotton"
+  },
+  "__evaluatedConditions": [
+    {
+      "input": "clothes",
+      "value": "tshirt",
+      "conditionsMatched": ["tshirt"]
+    }
+  ],
+  "decisionTableVersion": 1,
+  "decisionTable": "clothes-decision-table",
+  "decisionRuleStrategy": "FIRST_MATCH"
+}
+```
+
+### ALL_MATCH output
+
+`result` is an **array of objects** — one per matched rule.
+
+```json
+{
+  "result": [
+    {
+      "fabric": "Cotton"
+    }
+  ],
+  "__evaluatedConditions": [
+    {
+      "input": "clothes",
+      "value": "tshirt",
+      "conditionsMatched": ["tshirt"]
+    }
+  ],
+  "decisionTableVersion": 1,
+  "decisionTable": "clothes-decision-table",
+  "decisionRuleStrategy": "ALL_MATCH"
+}
+```
+
+## Output Access Paths
+
+Use:
+- `steps.<ref>.output.result.<column>` — output column value (FIRST_MATCH).
+- `steps.<ref>.output.result[0].<column>` — first matched row (ALL_MATCH).
+- `steps.<ref>.output.result` — full result object/array.
+- `steps.<ref>.output.__evaluatedConditions` — which conditions matched (debugging).
+- `steps.<ref>.output.decisionTableVersion` — resolved version of the table that was evaluated.
+- `steps.<ref>.output.decisionRuleStrategy` — the strategy that was used.
+
+Do not use:
+- `steps.<ref>.output.response` — DECISION_ENGINE does not wrap in `response`.
+- `steps.<ref>.output.results` — the key is `result`, not `results`.
+
+## Generation Rules
+
+- Use uppercase step type: `"DECISION_ENGINE"`.
+- Use `children: []`; DECISION_ENGINE is not a container.
+- `decisionContext` keys **must match** input column names in the decision table exactly.
+- Use `FIRST_MATCH` for single-result lookups and routing decisions.
+- Use `ALL_MATCH` when multiple rules may apply and all results are needed.
+- Always provide at least one entry in `decisionOutputColumns`.
+- `decisionTableVersion` can be `""` (latest) or a specific version number as a string.
+- Context values support `{{...}}` template expressions (e.g. `"{{ steps.classify.output.result.category }}"`).
+- Do not invent `script`, `url`, or HTTP-style fields for DECISION_ENGINE.
+- The decision table itself must already exist in Unmeshed; the assistant cannot create tables.
+
+## Debugging Rules
+
+When debugging a DECISION_ENGINE step:
+- Check `__evaluatedConditions` to see which input columns matched and what they matched against.
+- If `result` is `null` or empty, no rules matched — verify `decisionContext` values against the table rows.
+- Confirm `decisionContext` keys match table column names exactly (case-sensitive).
+- Confirm `decisionOutputColumns` lists valid output column names from the table.
+- If the wrong rule matched, inspect `conditionsMatched` in `__evaluatedConditions` to understand why.
+
+Common failures:
+- Mismatched column name in `decisionContext` vs the decision table definition.
+- Using `ALL_MATCH` and accessing `result.<column>` instead of `result[0].<column>`.
+- Using `FIRST_MATCH` and treating `result` as an array.
+- Leaving `decisionOutputColumns` empty, which returns no output columns.
+- Expecting the output under `response` or `results` instead of `result`.
+
+## Minimal Process Definition Example
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "decision-table-test",
+  "version": 1,
+  "type": "API_ORCHESTRATION",
+  "description": "Route based on a decision table lookup.",
+  "configuration": null,
+  "steps": [
+    {
+      "orgId": 1,
+      "namespace": "default",
+      "name": "decision_engine",
+      "type": "DECISION_ENGINE",
+      "ref": "decision_engine_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": {
+        "decisionRuleStrategy": "FIRST_MATCH",
+        "decisionTable": "clothes-decision-table",
+        "decisionContext": {
+          "clothes": "tshirt"
+        },
+        "decisionTableVersion": "",
+        "decisionOutputColumns": [
+          "fabric"
+        ]
+      },
+      "output": null
+    }
+  ],
+  "defaultInput": null,
+  "defaultOutput": null,
+  "outputMapping": null,
+  "signature": null,
+  "metadata": null,
+  "tags": null,
+  "dependencies": null,
+  "dependents": null
+}
+```
+
+## Minimal Executed Step Example
+
+```json
+{
+  "id": 593076335,
+  "processId": 593076333,
+  "ref": "decision_engine_1",
+  "namespace": "default",
+  "name": "decision_engine",
+  "type": "DECISION_ENGINE",
+  "status": "COMPLETED",
+  "input": {
+    "decisionOutputColumns": ["fabric"],
+    "decisionTableVersion": "",
+    "__currentExecutionStartTime": 1778221367327,
+    "decisionContext": {
+      "clothes": "tshirt"
+    },
+    "decisionTable": "clothes-decision-table",
+    "decisionRuleStrategy": "FIRST_MATCH"
+  },
+  "output": {
+    "result": {
+      "fabric": "Cotton"
+    },
+    "__evaluatedConditions": [
+      {
+        "input": "clothes",
+        "value": "tshirt",
+        "conditionsMatched": ["tshirt"]
+      }
+    ],
+    "decisionTableVersion": 1,
+    "decisionTable": "clothes-decision-table",
+    "decisionRuleStrategy": "FIRST_MATCH"
+  }
+}
+```
+
+## Example: Reading DECISION_ENGINE Output
+
+### FIRST_MATCH — single result
+
+```javascript
+(steps, context) => {
+  return {
+    fabric: steps.decision_engine_1.output.result.fabric
+  };
+}
+```
+
+### ALL_MATCH — iterate over matches
+
+```javascript
+(steps, context) => {
+  const matches = steps.decision_engine_1.output.result;
+  return {
+    allFabrics: matches.map(m => m.fabric),
+    matchCount: matches.length
+  };
+}
+```