callman-core 1.28.0 → 1.28.1

package/dist/ai/prompts/scenarioNodeReference.js

@@ -0,0 +1,882 @@
+// Host-neutral scenario node reference (markdown) for clients that write
+// scenarios through the REST API or an MCP tool — NOT the in-app assistant's
+// system prompt (`buildScenarioSystemPrompt`), which demands a JSON-only reply,
+// teaches the builder's node envelope and refers to context only the desktop
+// sends (AVAILABLE CONNECTIONS, importRequestId).
+//
+// Every statement is checked against the two places that decide what a
+// scenario can be: the backend's save-time validation
+// (callman-backend/src/modules/scenario/scenario.validation.ts + scenario.graph.ts)
+// and this package's run engine (scenario-runner/*). Defaults, limits,
+// operators, Redis commands, contract rules and reserved labels are read from
+// the same runtime values the engine and the in-app prompt use, so they cannot
+// drift; the prose is kept in step by tests/scenario-node-reference.test.mjs.
+import { CONDITION_OPERATOR_META } from "../../scenario-runner/condition.js";
+import { DEFAULT_AI_MAX_TOKENS, DEFAULT_AI_TIMEOUT_MS, DEFAULT_FOREACH_MAX_ITERATIONS, DEFAULT_WS_CLOSE_CODE, DEFAULT_WS_CONNECT_TIMEOUT_MS, DEFAULT_WS_EXPECT_TIMEOUT_MS, MAX_AI_MAX_TOKENS, MAX_AI_PROMPT_LENGTH, MAX_AI_RESPONSE_EXAMPLE_LENGTH, MAX_AI_TIMEOUT_MS, MAX_END_LOOP_ITERATIONS, MAX_FOREACH_ITERATIONS, MAX_POLL_ATTEMPTS, MAX_WS_CONNECT_TIMEOUT_MS, MAX_WS_EXPECT_TIMEOUT_MS, MAX_WS_STEPS, MAX_WS_WAIT_DURATION_MS, } from "../../scenario-runner/graphTraversal.js";
+import { RESERVED_SCENARIO_LABELS } from "../../scenario-runner/labels.js";
+import { REDIS_COMMAND_SPECS } from "../../host/redis/redisService.js";
+import { RESERVED_LABEL_NAMES } from "../../script/scope.js";
+import { CONTRACT_RULES_SPEC } from "./fragments.js";
+import { defaultScenarioNodeConfig } from "./scenarioNodeDefaults.js";
+// Every node type the backend stores, in reading order. `satisfies` + the
+// exhaustiveness check below make a new ScenarioNodeType a compile error here
+// until it is documented.
+const NODE_TYPE_ORDER = [
+    "request",
+    "db",
+    "redis",
+    "kafka",
+    "condition",
+    "assertion",
+    "script",
+    "set-vars",
+    "poll",
+    "foreach",
+    "websocket",
+    "ai",
+    "wait",
+    "notification",
+    "aggregator",
+    "end",
+    "subscenario",
+    "scenario-ref",
+];
+const assertEveryTypeDocumented = true;
+void assertEveryTypeDocumented;
+// Built-in template/operand roots (condition.ts createRuntimeRoots,
+// templateResolver.ts buildScenarioTemplateValues). Node outputs share the
+// same namespace, so a node labelled with one of these and the root shadow
+// each other (which one wins differs between templates and rule operands).
+const BUILT_IN_ROOTS = [
+    "response",
+    "lastResponse",
+    "data",
+    "env",
+    "global",
+    "globals",
+    "db",
+    "redis",
+    "kafkaEvent",
+    "kafkaevent",
+];
+const code = (value) => `\`${value}\``;
+const KV_ROWS = "{key, value, enabled?}[]";
+const getPath = (source, path) => {
+    let current = source;
+    for (const segment of path.split(".")) {
+        if (current === null || typeof current !== "object" || Array.isArray(current)) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+};
+const formatDefault = (value) => {
+    if (value === undefined)
+        return "—";
+    const json = JSON.stringify(value);
+    return code(json.length <= 60 ? json : `${json.slice(0, 57)}…`);
+};
+const formatPolicyDefault = (policy) => {
+    const onFailure = getPath(policy, "onFailure");
+    if (typeof onFailure !== "string")
+        return "stop, no retry (engine)";
+    const retryEnabled = getPath(policy, "retry.enabled") === true;
+    return retryEnabled
+        ? `${onFailure}, retry ×${String(getPath(policy, "retry.maxAttempts"))} every ${String(getPath(policy, "retry.delayMs"))} ms`
+        : `${onFailure}, no retry`;
+};
+// Markdown table cells: a literal `|` would end the cell.
+const cell = (value) => value.replace(/\|/g, "\\|").replace(/\n/g, " ");
+const renderFieldTable = (node, defaults) => {
+    const rows = node.fields.map((field) => {
+        const shown = field.shownDefault ??
+            (field.field.includes("[]") ? "—" : formatDefault(getPath(defaults, field.field)));
+        return `| ${cell(code(field.field))} | ${cell(field.type)} | ${cell(shown)} | ${field.req ?? ""} | ${cell(field.notes ?? "")} |`;
+    });
+    if (node.type !== "condition") {
+        rows.push(`| ${code("executionPolicy")} | ExecutionPolicy | ${cell(formatPolicyDefault(getPath(defaults, "executionPolicy")))} |  | See Execution policy. |`);
+    }
+    return ["| Field | Type | Default | Req | Notes |", "| --- | --- | --- | --- | --- |", ...rows].join("\n");
+};
+// One line per example: models read it as well as a pretty-printed block,
+// at a fraction of the size.
+const renderExample = (example) => ["```json", JSON.stringify(example), "```"].join("\n");
+const unaryOperators = CONDITION_OPERATOR_META.filter((entry) => entry.isUnary).map((entry) => entry.value);
+const binaryOperators = CONDITION_OPERATOR_META.filter((entry) => !entry.isUnary).map((entry) => entry.value);
+const NODE_DOCS = [
+    {
+        type: "request",
+        summary: "One HTTP call.",
+        fields: [
+            { field: "method", type: "string", notes: "HTTP verb." },
+            {
+                field: "url",
+                type: "string (≤10000)",
+                req: "run",
+                notes: "Absolute URL; `{{…}}` allowed. Its own `?query` is used only when `query` has no enabled rows.",
+            },
+            {
+                field: "headers",
+                type: KV_ROWS,
+                notes: "Disabled rows are not sent. A Content-Type row beats the automatic one (formdata always uses the driver's multipart type).",
+            },
+            { field: "query", type: KV_ROWS },
+            { field: "body.mode", type: "none | raw | formdata | urlencoded" },
+            {
+                field: "body.raw",
+                type: "string",
+                notes: "mode raw. JSON text that still parses after templating is sent as JSON.",
+            },
+            {
+                field: "body.rawLanguage",
+                type: "json | xml | text | html",
+                notes: "With no Content-Type header, sets application/json, application/xml, text/plain or text/html (json when absent).",
+            },
+            {
+                field: "body.formEntries",
+                type: "{key, value, enabled?, type?, fixtureId?, fileName?}[]",
+                notes: 'formdata / urlencoded rows. A `type:"file"` row needs `fixtureId` (an uploaded workspace fixture file) — server runs fail it otherwise.',
+            },
+            { field: "auth.type", type: "none | bearer | basic | apikey | oauth2" },
+            {
+                field: "auth.bearerToken",
+                type: "string",
+                notes: "bearer → `Authorization: Bearer <token>`.",
+            },
+            {
+                field: "auth.basicUsername / auth.basicPassword",
+                type: "string",
+                shownDefault: '`""`',
+                notes: "basic → base64 `user:password`.",
+            },
+            {
+                field: "auth.apiKeyKey / auth.apiKeyValue",
+                type: "string",
+                shownDefault: '`""`',
+                notes: "apikey → sends `key: value`; skipped when the key is blank.",
+            },
+            { field: "auth.apiKeyLocation", type: "header | query" },
+            {
+                field: "auth.oauth2",
+                type: "{grantType, tokenUrl, clientId, clientSecret, scope, username, password, refreshToken, clientAuth, audience}",
+                notes: 'oauth2: when present ALL ten keys are required (send "" for unused ones); grantType client_credentials | password | refresh_token; clientAuth basic | body. The token is fetched (and cached) before the call and sent as a Bearer header. Without it, type oauth2 sends no Authorization.',
+            },
+            {
+                field: "preRequestScript / postResponseScript / testsScript",
+                type: "string",
+                shownDefault: '`""`',
+                notes: "`pm.*` scripts: before the call / after the response / assertions (`pm.test`).",
+            },
+            {
+                field: "contractAssertions",
+                type: "{id, path, enabled, rules, engine?, namespaces?}[] (≤200)",
+                notes: 'id, path, enabled and rules are required; `rules` needs ≥1 key (see Contract rules). `path` is a dot-path over the parsed body (`data.items[0].id`, `items[].id` = every element); with engine "xpath" it is an XPath over the raw XML and every prefix must be in `namespaces` {prefix: uri}.',
+            },
+            {
+                field: "expectedStatus",
+                type: "string (≤200)",
+                notes: 'Negative testing: `"201"`, `"4xx"`, `"200-299"`, `"200,204"`, templates allowed. When set the node passes iff the status matches (instead of 2xx/3xx); contract assertions and test scripts can still fail it.',
+            },
+            {
+                field: "responseSchema",
+                type: "JSON Schema object",
+                notes: "Validated against the response body; a mismatch fails the node.",
+            },
+            {
+                field: "clientCertificate",
+                type: "{enabled, format, pfxBase64?, certPem?, keyPem?, passphrase?, caPem?, rejectUnauthorized?}",
+                notes: 'mTLS. enabled and format ("pfx" | "pem") are required; pfx uses pfxBase64, pem uses certPem + keyPem. Server runs present the certificate whenever this object is set — omit it to send none.',
+            },
+            {
+                field: "soap",
+                type: "{enabled, version, action?, wsSecurity?}",
+                notes: 'version "1.1" | "1.2". Keep the full envelope in body.raw (rawLanguage "xml"); Content-Type/SOAPAction come from the version (a Content-Type header wins). wsSecurity {enabled, username, password, passwordType: text | digest} injects a UsernameToken at send time.',
+            },
+        ],
+        output: "`<Label>.status` (number), `<Label>.body.<path>`, `<Label>.headers`, `<Label>.text`, `<Label>.durationMs`. The most recent request is also `response.*`.",
+        example: {
+            id: "login",
+            type: "request",
+            label: "Login",
+            config: {
+                method: "POST",
+                url: "{{env.baseUrl}}/login",
+                body: {
+                    mode: "raw",
+                    raw: '{"user":"{{env.user}}","password":"{{env.password}}"}',
+                    rawLanguage: "json",
+                },
+                expectedStatus: "200",
+            },
+        },
+    },
+    {
+        type: "db",
+        summary: "One query on a workspace connection of type `database`.",
+        fields: [
+            {
+                field: "connectionId",
+                type: "string",
+                req: "run",
+                notes: '`""` = not chosen yet: saved, but the run fails.',
+            },
+            {
+                field: "query",
+                type: "string (1..100000)",
+                req: "yes",
+                notes: "Mongo: a JSON command-object string (`{\"collection\":\"orders\",\"operation\":\"findOne\",\"filter\":{…}}`); SQL: plain SQL. Per-engine details: the DB query reference. The default is a placeholder — always send your own.",
+            },
+            {
+                field: "params",
+                type: "string[] (≤200)",
+                notes: "Positional binds, template-resolved: `$1` (Postgres), `?` (MySQL), `@p1…` (SQL Server).",
+            },
+            {
+                field: "typedParams",
+                type: "{value, type?}[] (≤200)",
+                notes: "Wins over params. type auto | text | int | numeric | boolean | date | timestamp | json | null: null binds SQL NULL, boolean a real boolean, the rest stay strings (cast in SQL).",
+            },
+            {
+                field: "useSession",
+                type: "boolean",
+                notes: "Postgres only: join the run's shared session (scenario-level `dbSettings.transactionMode`: none | rollback | commit).",
+            },
+            {
+                field: "expectError",
+                type: "{sqlState?, messagePattern?}",
+                notes: "Negative test: the node passes only if the query FAILS with that SQLSTATE and/or a message matching the regex.",
+            },
+        ],
+        output: "`<Label>.rows`, `<Label>.rowCount`; the rows are also `db.result`.",
+        example: {
+            id: "check",
+            type: "db",
+            label: "CheckOrder",
+            config: {
+                connectionId: "<database connection id>",
+                query: "SELECT status FROM orders WHERE id = $1",
+                params: ["{{CreateOrder.body.id}}"],
+            },
+        },
+    },
+    {
+        type: "redis",
+        summary: "Redis commands on a workspace connection of type `redis`.",
+        fields: [
+            { field: "connectionId", type: "string", req: "run" },
+            {
+                field: "commands",
+                type: "string[] (≤1000, each non-empty)",
+                req: "run",
+                notes: `One command per entry, template-resolved. Supported: ${Object.keys(REDIS_COMMAND_SPECS).join(", ")}. \`SCAN pattern [count]\` returns {keys, count, truncated}. An empty list fails the run.`,
+            },
+        ],
+        output: "The reply (one command) or an array of replies, as `<Label>` and `redis.result`.",
+        example: {
+            id: "cache",
+            type: "redis",
+            label: "Cache",
+            config: {
+                connectionId: "<redis connection id>",
+                commands: ["GET order:{{CreateOrder.body.id}}"],
+            },
+        },
+    },
+    {
+        type: "kafka",
+        summary: "Consume (wait for a matching message) or publish, on a connection of type `kafka`.",
+        fields: [
+            { field: "connectionId", type: "string", req: "run" },
+            { field: "topic", type: "string (1..500)", req: "yes" },
+            { field: "mode", type: "consume | publish" },
+            { field: "matchMode", type: "regex | rules", notes: "consume." },
+            {
+                field: "rules",
+                type: "string[]",
+                notes: "consume. regex: rules[0] is a regex tested against the whole message. rules: every entry is ONE comparison `left op right` (op ==, !=, ===, !==, >, <, >=, <=, contains) and all must hold, e.g. `kafkaEvent.orderId == '{{CreateOrder.body.id}}'`. Empty = the first message captured.",
+            },
+            {
+                field: "publishValueFormat",
+                type: "json | raw",
+                notes: "publish. json fails the node when messageValue is not valid JSON after templating.",
+            },
+            { field: "messageKey", type: "string", notes: "publish." },
+            { field: "messageValue", type: "string (≤1000000)", notes: "publish payload, template-resolved." },
+            { field: "messageHeaders", type: KV_ROWS, notes: "publish." },
+        ],
+        output: "consume: the matched message — a JSON message's keys at the top level plus `meta` {value, text, key, partition, offset, timestamp, headers}; also `kafkaEvent.*`.",
+        example: {
+            id: "event",
+            type: "kafka",
+            label: "OrderCreated",
+            config: {
+                connectionId: "<kafka connection id>",
+                topic: "orders",
+                mode: "consume",
+                matchMode: "rules",
+                rules: ["kafkaEvent.orderId == '{{CreateOrder.body.id}}'"],
+            },
+        },
+    },
+    {
+        type: "condition",
+        summary: "The only branching node and the only node without `executionPolicy`. Needs exactly two outgoing edges: one `yes`, one `no`.",
+        fields: [
+            { field: "mode", type: "builder | expert" },
+            {
+                field: "rootGroup",
+                type: "Group",
+                shownDefault: "one rule: `response.status` equals `200`",
+                notes: "Evaluated in builder mode (see Rules and operands). Stored in both modes.",
+            },
+            {
+                field: "expertExpression",
+                type: "string | null",
+                notes: 'Used ONLY with `mode: "expert"` (ignored otherwise). Syntax below.',
+            },
+        ],
+        output: "Takes the `yes` or `no` edge.",
+        notes: [
+            "Expert syntax: operands are `{{path}}` tokens (a bare path is a parse error), 'single'- or \"double\"-quoted strings, numbers, true / false / null and [arrays]; operators ==, !=, ===, !==, >, <, >=, <=, contains, not contains, starts with, ends with, regex, in, not in, between, exists, not exists, is empty, not empty, is null, not null, contains row, set equals; combine with && / AND, || / OR and parentheses. Example: `{{Login.status}} == 200 && {{Login.body.token}} != ''`.",
+        ],
+        example: {
+            id: "ok",
+            type: "condition",
+            label: "LoggedIn",
+            config: {
+                mode: "builder",
+                rootGroup: {
+                    id: "g1",
+                    type: "group",
+                    operator: "AND",
+                    children: [
+                        {
+                            id: "r1",
+                            type: "rule",
+                            left: { mode: "runtime", valueType: "number", value: "Login.status" },
+                            operator: "equals",
+                            right: { mode: "literal", valueType: "number", value: 200 },
+                        },
+                    ],
+                },
+            },
+        },
+    },
+    {
+        type: "assertion",
+        summary: "Pass/fail checkpoint; does not branch (on failure the execution policy decides).",
+        fields: [
+            { field: "matchMode", type: "all | any" },
+            {
+                field: "checks",
+                type: "{id, name, enabled, rule}[] (≤1000)",
+                req: "run",
+                shownDefault: "one blank check",
+                notes: "id, name (may be \"\"), enabled and rule are required; `rule` is a full Rule. With no enabled check the node passes without testing anything — send at least one.",
+            },
+        ],
+        output: "`<Label>.passed`, `.passedCount`, `.failedCount`, `.checks[i]` {name, passed, message}.",
+        example: {
+            id: "verify",
+            type: "assertion",
+            label: "VerifyOrder",
+            config: {
+                checks: [
+                    {
+                        id: "c1",
+                        name: "total is 40",
+                        enabled: true,
+                        rule: {
+                            id: "c1r",
+                            type: "rule",
+                            left: { mode: "runtime", valueType: "number", value: "CreateOrder.body.total" },
+                            operator: "equals",
+                            right: { mode: "literal", valueType: "number", value: 40 },
+                        },
+                    },
+                ],
+            },
+        },
+    },
+    {
+        type: "script",
+        summary: "JavaScript in the `pm.*` sandbox.",
+        fields: [
+            {
+                field: "script",
+                type: "string (≤1000000)",
+                req: "run",
+                notes: "Its `return` value is the node's output. Can `pm.environment.set`, `pm.test`, `await pm.db.query(…)` / `pm.redis.command(…)`. Empty or invalid code fails the run.",
+            },
+            { field: "timeoutMs", type: "integer 1..60000", notes: "Also capped by the host's per-node timeout." },
+        ],
+        output: "The returned value (`<Label>.<key>` for an object).",
+        example: {
+            id: "calc",
+            type: "script",
+            label: "Totals",
+            config: { script: "const body = CreateOrder.body;\nreturn { total: body.total * 2 };" },
+        },
+    },
+    {
+        type: "set-vars",
+        summary: "Write environment/global variables without a script. Rows apply top to bottom (a row sees earlier rows' writes).",
+        fields: [
+            {
+                field: "assignments",
+                type: "Assignment[] (≤200)",
+                shownDefault: "one blank row",
+            },
+            { field: "assignments[].id / .key / .value", type: "string", req: "yes", notes: 'key and value are template-resolved; value may be "".' },
+            { field: "assignments[].scope", type: "environment | global", req: "yes" },
+            { field: "assignments[].enabled", type: "boolean", req: "yes" },
+            {
+                field: "assignments[].extractorType",
+                type: "template | jsonpath | regex",
+                notes: "jsonpath / regex: resolve `source` (a bare runtime path such as `CreateOrder.body`), then apply `expression` (JSONPath like `$.items[0].id`, or a JS regex source); `value` is ignored. Regex rows take `flags` (subset of gimsuy) and `group`; `select` first | all (all writes a JSON array). A failed extraction skips that write.",
+            },
+        ],
+        output: "`<Label>.environment` / `<Label>.globals` (what was written), `<Label>.extraction` for extractor rows.",
+        example: {
+            id: "save",
+            type: "set-vars",
+            label: "SaveOrderId",
+            config: {
+                assignments: [
+                    { id: "a1", scope: "environment", key: "orderId", value: "{{CreateOrder.body.id}}", enabled: true },
+                ],
+            },
+        },
+    },
+    {
+        type: "poll",
+        summary: "Repeat ONE embedded action until a condition passes or the budget runs out. Retry is forced off (the loop is the retry); a failing tick is retried, not fatal.",
+        fields: [
+            { field: "actionType", type: "request | db | redis | script" },
+            {
+                field: "request / db / redis / script",
+                type: "that node type's config",
+                req: "run",
+                shownDefault: "request: the request defaults",
+                notes: "The one matching actionType. Same fields as the standalone node.",
+            },
+            {
+                field: "successCondition",
+                type: "{mode, rootGroup, expertExpression?}",
+                shownDefault: "`response.status` equals `200`",
+                notes: "Evaluated after every successful tick. A tick publishes like the real node: request → `response.*`, db → `db.result` (rows), redis → `redis.result`; a script tick exposes only its variable writes (`env.*`, `global.*`).",
+            },
+            { field: "intervalMs", type: "integer 0..3600000" },
+            { field: "maxAttempts", type: `integer 1..${MAX_POLL_ATTEMPTS}` },
+            { field: "timeoutMs", type: "integer 1..86400000", notes: "Wall-clock cap." },
+            { field: "backoffMultiplier", type: "number 1..10", notes: "Exponential backoff on the interval." },
+            { field: "maxDelayMs", type: "integer 0..3600000", notes: "Backoff cap." },
+            { field: "onTimeout", type: "fail | continue", notes: "continue marks the node degraded and goes on." },
+        ],
+        output: "`<Label>.attempts`, `.elapsedMs`, `.timedOut`, `.conditionResult`, `.lastTickError`; the last tick's result as listed above.",
+        example: {
+            id: "wait-ready",
+            type: "poll",
+            label: "WaitReady",
+            config: {
+                actionType: "request",
+                request: { url: "{{env.baseUrl}}/orders/{{CreateOrder.body.id}}" },
+                successCondition: {
+                    mode: "expert",
+                    expertExpression: "{{response.body.status}} == 'READY'",
+                },
+                intervalMs: 2000,
+                maxAttempts: 15,
+            },
+        },
+    },
+    {
+        type: "foreach",
+        summary: "Run an embedded body graph once per item of an array.",
+        fields: [
+            {
+                field: "nodes / edges",
+                type: "stored node[] / stored edge[]",
+                shownDefault: "`[]`",
+                notes: "The body graph in the STORED form with complete configs (see Scenario shape) — no defaults are merged inside. Same graph rules; labels unique across the whole scenario.",
+            },
+            { field: "sourceMode", type: "path | inline" },
+            { field: "itemsPath", type: "string (≤2000)", req: "run", notes: "path mode: a bare runtime path to an array, e.g. `Users.body.items`." },
+            { field: "itemsInline", type: "string", req: "run", notes: "inline mode: JSON array text; templates resolve first." },
+            { field: "itemAlias", type: "string (≤100)", notes: "Extra root mirroring `{{item}}` (e.g. `user` → `{{user.id}}`). Not a reserved label." },
+            {
+                field: "maxIterations",
+                type: `integer 1..${MAX_FOREACH_ITERATIONS}`,
+                shownDefault: `${DEFAULT_FOREACH_MAX_ITERATIONS} (engine)`,
+            },
+            { field: "delayMs", type: "integer 0..3600000", notes: "Pause between items." },
+            { field: "onItemFailure", type: "stop | continue", notes: "continue: failed items degrade the run, the loop goes on." },
+            { field: "collectResults", type: "boolean" },
+        ],
+        output: "`<Label>.results[i].<ChildLabel>…`, `.itemCount`, `.processedCount`, `.truncated`, `.failedItems`. Inside the body: `{{item}}`, `{{each.index}}` (0-based), `{{each.iteration}}` (1-based), `{{each.total}}`, `{{each.remaining}}`, `{{eaches.<ForeachLabel>.iteration}}` for an outer loop.",
+        example: {
+            id: "each-user",
+            type: "foreach",
+            label: "EachUser",
+            config: {
+                sourceMode: "path",
+                itemsPath: "Users.body.items",
+                itemAlias: "user",
+                nodes: [
+                    {
+                        id: "get-user",
+                        type: "request",
+                        position: { x: 0, y: 0 },
+                        data: {
+                            label: "GetUser",
+                            config: {
+                                method: "GET",
+                                url: "{{env.baseUrl}}/users/{{user.id}}",
+                                headers: [],
+                                query: [],
+                                body: { mode: "none", raw: "", formEntries: [] },
+                            },
+                        },
+                    },
+                ],
+                edges: [],
+            },
+        },
+    },
+    {
+        type: "websocket",
+        summary: "One WebSocket conversation: connect, run the steps in order, close. Retry re-runs the whole conversation.",
+        fields: [
+            { field: "url", type: "string (≤2000)", req: "run", notes: "ws:// or wss://, template-resolved." },
+            { field: "headers", type: `${KV_ROWS} (≤100)` },
+            { field: "subprotocols", type: "string[] (≤20)" },
+            {
+                field: "connectTimeoutMs",
+                type: `integer 100..${MAX_WS_CONNECT_TIMEOUT_MS}`,
+                shownDefault: `${DEFAULT_WS_CONNECT_TIMEOUT_MS} (engine)`,
+            },
+            {
+                field: "steps",
+                type: `Step[] (≤${MAX_WS_STEPS})`,
+                notes: `{id, kind:"send", payload} sends one text frame; {id, kind:"expect", rules (1..50 Rules), timeoutMs? (100..${MAX_WS_EXPECT_TIMEOUT_MS}, default ${DEFAULT_WS_EXPECT_TIMEOUT_MS}), matchMode? all | any} waits for a matching frame — rule paths use \`ws.text\`, \`ws.json.<path>\`, \`ws.direction\`, \`ws.index\`; {id, kind:"wait", durationMs (0..${MAX_WS_WAIT_DURATION_MS})}. A timed-out expect fails the node.`,
+            },
+            { field: "closeCode", type: "integer 1000..4999", shownDefault: `${DEFAULT_WS_CLOSE_CODE} (engine)` },
+            { field: "rejectUnauthorized", type: "boolean", notes: "false accepts self-signed certificates." },
+        ],
+        output: "`<Label>.connected`, `.messages[i].text`, `.messageCount`, `.failedSteps`, `.closeCode`.",
+        example: {
+            id: "ws",
+            type: "websocket",
+            label: "Subscribe",
+            config: {
+                url: "wss://stream.example.com/orders",
+                steps: [
+                    { id: "s1", kind: "send", payload: '{"subscribe":"orders"}' },
+                    {
+                        id: "s2",
+                        kind: "expect",
+                        rules: [
+                            {
+                                id: "s2r",
+                                type: "rule",
+                                left: { mode: "runtime", valueType: "string", value: "ws.json.event" },
+                                operator: "equals",
+                                right: { mode: "literal", valueType: "string", value: "subscribed" },
+                            },
+                        ],
+                    },
+                ],
+            },
+        },
+    },
+    {
+        type: "ai",
+        summary: "One LLM call on a managed workspace connection of type `ai`.",
+        fields: [
+            {
+                field: "connectionId",
+                type: "string (1..200)",
+                req: "yes",
+                notes: "The default `\"\"` is rejected on save.",
+            },
+            {
+                field: "prompt",
+                type: `string (≤${MAX_AI_PROMPT_LENGTH})`,
+                req: "run",
+                notes: "Template-resolved; empty fails the run.",
+            },
+            {
+                field: "responseExample",
+                type: `string (≤${MAX_AI_RESPONSE_EXAMPLE_LENGTH})`,
+                req: "run",
+                notes: "A JSON OBJECT as text; its top-level keys are required in the reply (extra keys allowed).",
+            },
+            { field: "maxTokens", type: `integer 1..${MAX_AI_MAX_TOKENS}`, shownDefault: `${DEFAULT_AI_MAX_TOKENS} (engine)` },
+            { field: "timeoutMs", type: `integer 1000..${MAX_AI_TIMEOUT_MS}`, shownDefault: `${DEFAULT_AI_TIMEOUT_MS} (engine)` },
+        ],
+        output: "The parsed JSON reply: `<Label>.<exampleKey>`.",
+        example: {
+            id: "classify",
+            type: "ai",
+            label: "Classify",
+            config: {
+                connectionId: "<ai connection id>",
+                prompt: "Classify the sentiment of: {{GetReview.body.text}}",
+                responseExample: '{"sentiment":"positive","score":0.9}',
+            },
+        },
+    },
+    {
+        type: "wait",
+        summary: "Fixed delay.",
+        fields: [{ field: "durationMs", type: "integer 1..2147483647" }],
+        output: "`<Label>.configuredDurationMs`, `.actualDurationMs`, `.status`.",
+        example: { id: "pause", type: "wait", label: "Pause", config: { durationMs: 1000 } },
+    },
+    {
+        type: "notification",
+        summary: "Slack message through a workspace connection of type `notification`.",
+        fields: [
+            { field: "provider", type: '"slack"' },
+            { field: "connectionId", type: "string", req: "run" },
+            { field: "severity", type: "info | success | warning | error" },
+            {
+                field: "messageTemplate",
+                type: "string (≤100000)",
+                shownDefault: "a run-status line",
+                notes: "Template-resolved (node outputs, `{{workflow.name}}`, `{{workflow.__meta.status}}` …).",
+            },
+            { field: "channelOverride", type: "string (≤500)" },
+            { field: "continueOnFailure", type: "boolean", notes: "Overrides executionPolicy.onFailure (true = continue)." },
+            { field: "advanced.useRichBlocks", type: "boolean" },
+        ],
+        output: "The delivery result.",
+        example: {
+            id: "notify",
+            type: "notification",
+            label: "Notify",
+            config: {
+                connectionId: "<notification connection id>",
+                severity: "warning",
+                messageTemplate: "Order {{CreateOrder.body.id}} is not ready",
+            },
+        },
+    },
+    {
+        type: "aggregator",
+        summary: "Build one JSON object from earlier outputs.",
+        fields: [
+            {
+                field: "template",
+                type: "string (≤1000000)",
+                req: "run",
+                notes: "Must be valid JSON after templating (`{{Label.path}}` or `{Label.path}` tokens), else the run fails.",
+            },
+        ],
+        output: "The parsed object: `<Label>.<key>`.",
+        example: {
+            id: "summary",
+            type: "aggregator",
+            label: "Summary",
+            config: { template: '{"orderId":"{{CreateOrder.body.id}}","status":"{{CheckOrder.rows[0].status}}"}' },
+        },
+    },
+    {
+        type: "end",
+        summary: "Terminates a path; optionally loops back to an earlier node.",
+        fields: [
+            { field: "loop", type: "boolean" },
+            { field: "loopTargetNodeId", type: "string | null", req: "run", notes: "loop: the id of an earlier node to jump back to." },
+            {
+                field: "loopIterations",
+                type: `integer 1..${MAX_END_LOOP_ITERATIONS}`,
+                notes: "Re-entries: the looped section runs loopIterations + 1 times.",
+            },
+            { field: "loopDelayMs", type: "integer 0..600000" },
+            {
+                field: "loopExitRule",
+                type: "Rule | null",
+                notes: "Checked after each pass; TRUE stops the loop early and continues along the end node's outgoing edges. Loop roots: `loop.iteration` (1-based), `loop.index`, `loop.total`, `loop.remaining`.",
+            },
+        ],
+        output: "A snapshot of the run's outputs so far.",
+        example: {
+            id: "again",
+            type: "end",
+            label: "Repeat",
+            config: { loop: true, loopTargetNodeId: "login", loopIterations: 2, loopDelayMs: 500 },
+        },
+    },
+    {
+        type: "subscenario",
+        summary: "A group of nodes collapsed into one node (the builder's Group).",
+        fields: [
+            {
+                field: "nodes / edges",
+                type: "stored node[] / stored edge[]",
+                req: "yes",
+                shownDefault: "none",
+                notes: "Stored form, complete configs; no defaults are merged for this type. Same graph rules.",
+            },
+            {
+                field: "reusableGroupId / reusableSourceScenarioId / reusableSourceNodeId / ungroupSnapshot",
+                type: "app-managed",
+                shownDefault: "—",
+                notes: "Written by the builder; omit them.",
+            },
+        ],
+        output: "Its inner nodes publish under their own labels.",
+        example: {
+            id: "setup",
+            type: "subscenario",
+            label: "Setup",
+            config: {
+                nodes: [
+                    {
+                        id: "seed",
+                        type: "wait",
+                        position: { x: 0, y: 0 },
+                        data: { label: "Settle", config: { durationMs: 500 } },
+                    },
+                ],
+                edges: [],
+            },
+        },
+    },
+    {
+        type: "scenario-ref",
+        summary: "A reference to another scenario, embedded as a synced snapshot. Created by the app when a scenario is linked; the compact form cannot create or re-send one (in the stored form, send it back exactly as read).",
+        fields: [
+            { field: "referencedScenarioId", type: "string", req: "yes" },
+            { field: "referencedScenarioVersion", type: "integer | null", req: "yes" },
+            { field: "referencedScenarioName / lastSyncedAt", type: "string", req: "yes" },
+            { field: "nodes / edges", type: "stored node[] / stored edge[]", req: "yes", notes: "The referenced scenario's graph snapshot." },
+        ],
+        output: "Its inner nodes publish under their own labels.",
+        example: null,
+    },
+];
+const renderNodeSection = (node, defaultConfigFor) => {
+    let defaults = null;
+    try {
+        defaults = defaultConfigFor(node.type);
+    }
+    catch {
+        defaults = null;
+    }
+    return [
+        `### ${node.type}`,
+        node.summary,
+        "",
+        renderFieldTable(node, defaults),
+        "",
+        `Output: ${node.output}`,
+        ...(node.notes ?? []).flatMap((note) => ["", note]),
+        ...(node.example ? ["", renderExample(node.example)] : []),
+    ].join("\n");
+};
+/**
+ * The scenario node reference for API / MCP clients: the scenario shape, every
+ * node type's config fields (type, default, requirement, notes) with a minimal
+ * example, and the graph rules the server enforces.
+ */
+export const renderScenarioNodeReference = (options = {}) => {
+    const defaultConfigFor = options.defaultConfigFor ?? defaultScenarioNodeConfig;
+    const scriptReserved = [...RESERVED_LABEL_NAMES].filter((name) => ["pm", "env", "request", "response", "test", "expect", "workflow", "db", "kafka", "redis", "console"].includes(name));
+    return [
+        "# Scenario node reference",
+        "",
+        "A scenario is a directed graph: nodes do the work, edges decide what runs next. This reference is for clients that write scenarios through the API or an MCP tool; every rule below is what the server enforces on save or what the run engine does.",
+        "",
+        "## Scenario shape",
+        "",
+        "Compact form (what the MCP scenario tools take):",
+        "",
+        "```json",
+        JSON.stringify({
+            name: "Order flow",
+            description: "optional",
+            priority: "high",
+            nodes: [
+                { id: "login", type: "request", label: "Login", config: { method: "POST", url: "{{env.baseUrl}}/login" } },
+                { id: "done", type: "end", label: "Done" },
+            ],
+            edges: [{ source: "login", target: "done" }],
+            environments: [
+                { name: "Default", variables: [{ key: "baseUrl", value: "https://api.example.com" }] },
+            ],
+        }, null, 2),
+        "```",
+        "",
+        "- Node `{ id?, type, label?, config?, position? }`. `id` defaults to n1, n2, …; `position` is laid out when omitted.",
+        "- `config` is deep-merged over the type's defaults (the Default column): objects merge key by key, arrays and scalars replace the default whole. Send only what you change — but an array you send (headers, checks, steps, rules, assignments) must be complete.",
+        "- Edge `{ id?, source, target, type? }`, `type` = `default` (or omitted) | `yes` | `no` | `error`. Edges have no label.",
+        "- `priority`: critical | high | medium | low. `environments[].variables`: `{ key, value, enabled? }[]`.",
+        "- Stored form (the REST API, and the body of `foreach` / `subscenario` / `scenario-ref`): node `{ id, type, position: { x, y }, data: { label, config } }` with the COMPLETE config — nothing is merged — and edge `{ id, source, target, type? }` with a required `id`.",
+        "",
+        "Req column: **yes** = rejected on save without a real value; **run** = saved, but the run fails without it. Default \"(engine)\" = applied at run time when the field is absent.",
+        "",
+        "## Connections",
+        "",
+        "db, redis, kafka, notification and ai nodes run on a workspace connection: `config.connectionId` is the id of a connection of type `database`, `redis`, `kafka`, `notification` (Slack) or `ai` (managed). Use a real connection id from the workspace — never invent one. Only the ai node rejects an empty id on save; the others save with `\"\"` and fail when run.",
+        "",
+        "## Labels",
+        "",
+        "- `label` names a node's output: later nodes read `{{Label.path}}`. It is optional on save, but an unlabelled node's output cannot be referenced.",
+        "- Labels must be unique across the whole scenario, including foreach / subscenario bodies: a repeated label is overwritten by whichever node ran last.",
+        `- Reserved labels — the engine drops the output of a node labelled ${RESERVED_SCENARIO_LABELS.map(code).join(", ")}, so references to it resolve to empty without any error.`,
+        `- Avoid labels that are built-in roots — ${BUILT_IN_ROOTS.map(code).join(", ")} — the node and the root shadow each other.`,
+        `- Prefer identifier labels (\`Login\`, \`CreateOrder\`, \`check_db\`). Script nodes get a label as a global variable only when it is an identifier and not a sandbox name (${scriptReserved.map(code).join(", ")}, …).`,
+        "",
+        "## Templates and outputs",
+        "",
+        "- `{{env.KEY}}` / `{{global.KEY}}` read one scope; a bare `{{KEY}}` reads both (in scenario runs a global wins when both define KEY). `{{data.column}}` is the current dataset row.",
+        "- `{{Label.path}}` (or `{Label.path}`) reads an earlier node's output; arrays by index (`items[0].id`), no wildcards. `{{response.*}}` is the most recent request's response. Generators: `{{$randomUUID}}`, `{{$timestamp}}`, `{{random.email}}`, `{{counter}}`.",
+        "- Substitution is plain text — quote SQL strings yourself (`WHERE id = '{{userId}}'`). A missing value resolves to an empty string.",
+        "- A request's output: `<Label>.status` is the HTTP status (number). Read body fields through `<Label>.body.<path>`: top-level body keys are also spread onto the output, but `status`, `statusText`, `data`, `body`, `rawBody`, `text`, `headers`, `cookies`, `durationMs` are HTTP metadata and win over same-named body keys. `<Label>.data.<path>` reads a body's top-level `data`.",
+        "- Operand paths (rules, `foreach.itemsPath`, set-vars `source`) are BARE dotted paths without braces: `CreateOrder.body.total`, `CheckOrder.rows[0].status`.",
+        "",
+        "## Rules and operands",
+        "",
+        "Shared by condition, assertion, poll, websocket expect steps and `end.loopExitRule`.",
+        "",
+        "- Rule `{ id, type: \"rule\", left, operator, right? }` — `id` and `type: \"rule\"` are required; `right` is required unless the operator is unary.",
+        "- Group `{ id, type: \"group\", operator: \"AND\" | \"OR\", children: [Rule | Group, …] }` with at least one child.",
+        "- Operand `{ mode: \"runtime\" | \"literal\", valueType: \"string\" | \"number\" | \"boolean\" | \"null\" | \"array\", value, extract? }`. runtime: `value` is a bare path. literal: a JSON number for number, true/false for boolean, null for null, a JSON array for array.",
+        `- Binary operators: ${binaryOperators.join(", ")}. \`between\` takes [min, max]; \`in\` / \`not_in\` an array; \`regex\` a JS regex source; \`contains_row\` checks that an array of rows has one matching every key of an object (a JSON-object string literal or a runtime path); \`set_equals_unordered\` compares two arrays as multisets.`,
+        `- Unary operators (no \`right\`): ${unaryOperators.join(", ")}.`,
+        "- `extract` `{ type: \"jsonpath\" | \"regex\", expression, flags?, group?, select?: \"first\" | \"all\" }` is applied to the resolved value first; a failed extraction behaves as not-exists.",
+        "",
+        "Example: `{ \"id\": \"r1\", \"type\": \"rule\", \"left\": { \"mode\": \"runtime\", \"valueType\": \"number\", \"value\": \"CreateOrder.status\" }, \"operator\": \"equals\", \"right\": { \"mode\": \"literal\", \"valueType\": \"number\", \"value\": 201 } }`",
+        "",
+        "## Contract rules",
+        "",
+        CONTRACT_RULES_SPEC,
+        "",
+        "## Execution policy",
+        "",
+        "Every node except condition takes `executionPolicy: { onFailure: \"stop\" | \"continue\", retry: { enabled, maxAttempts (0..100), delayMs (0..3600000), backoffMultiplier? (1..10), maxDelayMs? (0..3600000) } }` — onFailure and retry.enabled / maxAttempts / delayMs are required when you send the stored form.",
+        "- `maxAttempts` counts every attempt (an enabled retry makes at least 2). Delay before retry n = min(maxDelayMs, delayMs × backoffMultiplier^(n−1)). No policy = stop, no retry.",
+        "- stop: a failure ends the run; continue: the run goes on along the normal edges.",
+        "- `error` edges from the failing node win over both: the run follows them instead of the normal edges (after the retries).",
+        "",
+        "## Node types",
+        "",
+        NODE_DOCS.map((node) => renderNodeSection(node, defaultConfigFor)).join("\n\n"),
+        "",
+        "## Graph rules",
+        "",
+        "Rejected on save:",
+        "- Node ids unique; edge ids unique; every edge's source and target is an existing node id.",
+        "- `yes` / `no` edges only leave a condition node; `error` edges only leave a non-condition node; omit `type` (or `default`) for normal flow.",
+        "- A condition node has exactly two outgoing edges: one `yes`, one `no`.",
+        "- At least one start node (a node with no incoming edge) and no cycles — loop with an end node's `loop` settings, never with a back edge.",
+        "- foreach / subscenario / scenario-ref bodies are checked with the same rules.",
+        "",
+        "Saved with a warning: more than one start node; nodes no start node reaches.",
+    ].join("\n");
+};
+// Exposed for tests: the node types the reference documents, in order.
+export const SCENARIO_NODE_REFERENCE_TYPES = NODE_TYPE_ORDER;
+//# sourceMappingURL=scenarioNodeReference.js.map