@uipath/skills 1.195.0

package/skills/uipath-maestro-flow/references/shared/node-output-wiring.md

@@ -0,0 +1,138 @@
+# Wiring Node Outputs to Downstream Inputs
+
+How to reference one node's output (or any `$vars.*` value) from another node's input fields. This is the **single source of truth** for `=js:` expression rules in `.flow` JSON. All node-type plugins (connector, http, script, decision, end, etc.) defer to this file.
+
+> **Read this before** writing any field that needs to reference a previous node's output, a workflow variable, or any other `$vars.*` / `$metadata.*` value. Skipping `=js:` is the #1 cause of "the value at runtime was the literal string `vars.X.output.Id`" failures (MST-9107).
+
+---
+
+## The Rule (one sentence)
+
+**Any string that references `$vars.*`, `$metadata.*`, or `$self.*` MUST start with `=js:`. Otherwise it is a literal string at runtime.**
+
+---
+
+## What Goes Wrong Without `=js:`
+
+The Flow runtime serializes string fields into BPMN. The serializer rewrites the canvas-form tokens (`$vars` → `vars`) **whether or not the `=js:` prefix is present**. This means a missing prefix is silent — `flow validate` passes, the file looks plausible, but at runtime the BPMN engine sees a plain string and never evaluates it.
+
+Three failure modes observed in agent-generated `.flow` files:
+
+| What the agent wrote | What ships to runtime | Result |
+|---|---|---|
+| `"nodes.createEntityRecord1.output.Id"` | `"nodes.createEntityRecord1.output.Id"` | Literal string — invented `nodes.` prefix has no meaning. |
+| `"$vars.createEntityRecord1.output.Id"` | `"vars.createEntityRecord1.output.Id"` | Literal string — `$vars` rewritten to `vars` but no `=js:` so never evaluated. |
+| `"=js:$vars.createEntityRecord1.output.Id"` | `"=js:vars.createEntityRecord1.output.Id"` | Evaluates correctly. |
+
+**There is no "nodes.X.output.Y" syntax.** Variable references always use `$vars.*`.
+
+---
+
+## The Canonical Pattern
+
+```
+"=js:$vars.<sourceNodeId>.output.<field>"
+```
+
+- `<sourceNodeId>` — the `id` value of the node that produces the output
+- `output` — the literal string `output` (the standard output port; use `error` for errors)
+- `<field>` — the field path within the output object
+
+### Examples
+
+| What you want | Expression |
+|---|---|
+| The whole output object | `=js:$vars.fetchUser1.output` |
+| One field from a single-record output | `=js:$vars.createEntityRecord1.output.Id` |
+| A field from the first record of a query result (array) | `=js:$vars.queryEntityRecords1.output[0].Id` |
+| Filter on a value from a previous node | `=js:$vars.fetchUser1.output.id === $vars.input.userId` |
+| A static value (no variables) | `"HDFC Bank"` (no prefix needed) |
+| A built-in metadata value | `=js:$metadata.instanceId` |
+| A literal that contains a variable | `` =js:`Hello ${$vars.userName}` `` |
+
+---
+
+## Where the Rule Applies
+
+`=js:` is **required** in every field below when the value references `$vars`, `$metadata`, or `$self`:
+
+| Node / context | Field | Required `=js:`? |
+|---|---|---|
+| **Connector activity nodes** (`uipath.connector.<connector-key>.<activity>`) | `inputs.detail.bodyParameters.*` (all values) | **YES** |
+| | `inputs.detail.queryParameters.*` (all values) | **YES** |
+| | `inputs.detail.pathParameters.*` (all values) | **YES** |
+| **Managed HTTP** (`core.action.http.v2`) | `inputs.detail.bodyParameters.url` / `headers` / `query` / `body` — both manual and connector mode store dynamic fields here in the `.flow` JSON, regardless of how the CLI's `--detail` flag accepts them at the top level | **YES** |
+| **Custom HTTP** (`core.action.http`) | `inputs.url` / `headers` / `body` / `queryParams` (deprecated; prefer `core.action.http.v2`) | **YES** |
+| **HTTP branches** | `inputs.branches[].conditionExpression` | **NO** — already JS, do not prefix |
+| **Decision** (`core.logic.decision`) | `inputs.expression` | **NO** — already JS, do not prefix |
+| **Switch** (`core.logic.switch`) | `inputs.cases[].expression` | **NO** — already JS, do not prefix |
+| **End nodes** (`core.control.end`) | `outputs.<varId>.source` | **YES** |
+| **Variable updates** | `variables.variableUpdates.<nodeId>[].expression` | **YES** (the CLI auto-prefixes if missing, but write it explicitly) |
+| **Loop nodes** (`core.logic.loop`) | `inputs.collection` | **YES** |
+| **Subflow nodes** (`core.subflow`) | `inputs.<inputId>.source` | **YES** |
+| **Script nodes** (`core.action.script`) | `inputs.script` body — `$vars.*` is read inside JS, no `=js:` wrapping | **NO** — the body is already JS |
+| **Inline-agent prompt** (`uipath.agent.autonomous` `agent.json` `messages[].content`) | Tokens reference upstream flow nodes directly: `{{ $vars.<flowNodeId>.output[.<field>] }}` (spaced braces). Mirror in `contentTokens[]` as `{ "type": "variable", "rawString": " $vars.<flowNodeId>.output[.<field>] " }` — `rawString` must include leading and trailing space. Never `{{input.<id>}}` and never bare `{{name}}`. | **NO** — `{{ ... }}` tokens, not `=js:`. See [author/references/plugins/inline-agent/impl.md § Wiring Flow Variables into Agent Prompts](../author/references/plugins/inline-agent/impl.md#wiring-flow-variables-into-agent-prompts). |
+
+**Rule of thumb:** If the field is *value-typed* (anything other than a hardcoded condition), `=js:` is required for `$vars`/`$metadata`/`$self` references. The two condition fields (Decision, Switch) and the script body are the only exceptions — they are always parsed as JS regardless.
+
+---
+
+## Connector Node Wiring — Quick Reference
+
+For connector nodes (`uipath.connector.*`), the most common wiring patterns:
+
+```jsonc
+"inputs": {
+  "detail": {
+    "method": "POST",
+    "endpoint": "/v2/{entityName}/UpdateEntityRecord",
+    "pathParameters": {
+      "entityName": "BankDetails"
+    },
+    "queryParameters": {
+      "recordId": "=js:$vars.createEntityRecord1.output.Id",
+      "expansionLevel": "3"
+    },
+    "bodyParameters": {
+      "BankName": "HDFC Bank",
+      "AccountId": "=js:$vars.queryAccounts1.output[0].Id",
+      "Notes": "=js:`Created from flow run ${$metadata.instanceId}`"
+    }
+  }
+}
+```
+
+- **Static values** (`"HDFC Bank"`, `"3"`) — no prefix, written as plain JSON values.
+- **Variable references** (`$vars.X.output.Y`) — **always** wrap with `=js:`.
+- **Mixed strings** (template literals) — wrap the whole expression in `=js:` and use JS template literal syntax with `${ }`.
+
+Plugin-specific path fields are not value fields. **Always** follow the plugin reference when it says a field stores a path string. Notable exception: Transform `inputs.collection` must be a path such as `"$vars.orders.output.items"`, without `=js:`.
+
+---
+
+## Anti-Patterns (Never Write These)
+
+1. **Never invent a `nodes.X.output.Y` syntax.** It does not exist. All variable references use `$vars`.
+2. **Never write `$vars.X.output.Y` without `=js:`** in an expression value field. The `$vars→vars` rewrite happens regardless of prefix, leaving you with a literal string `"vars.X.output.Y"` at runtime — looks like an expression, isn't one. For plugin path fields such as Transform `inputs.collection`, use the plugin-specific path format instead.
+3. **Never wrap conditions** (Decision, Switch, HTTP branch) in `=js:`. Those are parsed as JS automatically.
+4. **Never use `{ }` template interpolation in connector or HTTP activity inputs.** The flow-layer template runner skips these fields. The `$` is stripped and `{vars.X}` ships literally to the IS runtime. Use `=js:` and JS template literals (`` `…${$vars.X}…` ``) instead.
+5. **Never quote `=js:` itself in an expression.** `"=js:$vars.X"` is correct. `"\"=js:$vars.X\""` is a string containing the prefix.
+
+---
+
+## Why The Engine Works This Way
+
+The flow-workbench serializer (`expression-transform.ts`) walks every string in node data and rewrites `$vars` → `vars` so the BPMN runtime sees engine-form tokens. It does **not** check for the `=js:` prefix when doing this rewrite — the prefix is what tells the BPMN engine to actually evaluate the result as JavaScript. Without it, the BPMN engine treats the string as a literal value and binds it to the activity input as-is.
+
+For variable updates only, `bpmn-moddle.ts` has a fallback (`ensureJsPrefix`) that warns and auto-prefixes. There is **no equivalent fallback for connector/HTTP activity inputs** — values pass through verbatim. Always include `=js:` explicitly.
+
+---
+
+## Validation Tip
+
+When debugging a flow whose output is the literal string `vars.X.output.Y` (or `nodes.X.output.Y`, or any other unevaluated expression) instead of the expected value:
+
+1. Open the `.flow` file
+2. Search for the literal token in the failed field — `grep '"vars\.' <project>.flow` or `grep '"\$vars\.' <project>.flow`
+3. For each match in `bodyParameters`, `queryParameters`, `pathParameters`, end-node `source`, or any value field, prepend `=js:`
+4. Re-run `uip maestro flow validate` and re-debug

package/skills/uipath-maestro-flow/references/shared/ux-narration-and-todos.md

@@ -0,0 +1,150 @@
+# UX — Narration and Todos
+
+Two **opt-in** rules govern how this skill communicates with the user during work. They are **off by default** — the agent works quietly. Engage them only when the user requests narration / progress tracking or signals a preference for verbosity. When engaged, they apply across every capability (Author, Operate, Diagnose, Evaluate), every journey, and every action type (`uip` CLI, shell builtins, Read/Write/Edit, Glob/Grep).
+
+> Inherits from [SKILL.md](../../SKILL.md). The rules below are the canonical source — capability indexes and journey docs reference this file.
+
+## When to engage
+
+Engage narration + todos when **any** of these hold:
+
+- User explicitly asks: "narrate", "walk me through it", "show your steps", "keep a todo list", "track progress", "tell me what you're doing", "verbose", "be detailed", "explain as you go".
+- User expresses a standing preference for verbosity (in-session, or via a recalled memory / preference).
+- User asks a question that only makes sense with running commentary ("what are you doing right now?", "where are we?").
+
+**Default — silent mode.** When none of the above hold, do the work quietly. Surface only: decisions (`AskUserQuestion`), failures, consent gates (`flow debug`), and the final result. No per-step narration line; no user-facing `TodoWrite` list. The agent MAY still keep todos privately on large journeys for its own tracking, but it is not required and is not a user-facing contract.
+
+## The two rules
+
+These apply **only once engaged** (see When to engage):
+
+1. **Narrate every logical step in plain English** — one short line before each step explaining what the agent is doing and why, in terms of the user's request. The user should never need to know `bash`, `uip` flags, or `.flow` JSON internals to follow along.
+2. **Maintain a granular `TodoWrite` list** for any journey above the trivial threshold — one todo per logical step, kept current as work proceeds. Standard journeys typically land at 10+ items; complex flows go higher. The count emerges from the journey's actual logical steps — do not target a number.
+
+## What is a "logical step"
+
+A logical step is the smallest user-meaningful **outcome** — usually 1–5 actions across any mix of tools grouped under one intent.
+
+| Step intent | Actions inside |
+| --- | --- |
+| Discover and add the Slack node | `registry search` + `registry get` + `flow node add` + Edit to wire outputs |
+| Confirm project layout | `ls` + `cat <project>.flow` + `Glob` for nested files |
+| Update a script body | `Read` of `.flow` + `Edit` on the script node's `inputs.code` |
+| Validate the flow | `flow validate` (one call, but still a step) |
+| Triage a fault | `instance asset` + `incident list` + `incident get` |
+
+Bash plumbing inside a step is invisible to the user — the step's narration line covers it.
+
+## Narration cadence
+
+| Situation | Rule |
+| --- | --- |
+| Start of a logical step | **Narrate.** One short line, plain English, user terms. |
+| Multiple actions within the same step | No additional narration — the step's opening line covers them |
+| Step transitions (one outcome done, next starting) | Narrate the next step |
+| Decision point | Brief one-liner before `AskUserQuestion` ("This decision affects which connection binding I generate — choose one:") |
+| Failure / retry | Always narrate — explain what failed and what's being tried next. Failures surface even in silent mode. |
+| Trivial probe (`uip --version`, repeated `login status` in same minute) | Skip |
+| Non-`uip` shell commands (`ls`, `cat`, `mkdir`, `cd`) used as plumbing inside a step | Skip — covered by the step's opening narration |
+| File reads/edits inside a step | Skip — covered by the step's opening narration |
+
+## Narration line format
+
+- **Length:** ≤ ~15 words. Single sentence or fragment.
+- **Voice:** system voice. Not first person ("I'm checking…" → "Checking…").
+- **Terms:** user terms. "looking up the Slack node schema" — not "running `registry get core.action.slack.send`".
+- **Carry information:** every line tells the user something they couldn't have inferred from the prior line. No ceremony, no recap of flags or JSON paths.
+- **Reference user intent when scope is non-obvious.** "Adding the Slack node" beats "Adding a node"; "Editing the flow JSON to wire the new variable" beats "Editing the file".
+
+## Phrasing register
+
+Reference table — adapt to context. Add subject (what's being acted on) when scope is ambiguous.
+
+| Logical step | Narration |
+| --- | --- |
+| Login probe | "Checking whether you're logged in to the UiPath tenant…" |
+| Solution scaffold | "Scaffolding a new solution at `<path>` so the Flow project has a parent." |
+| Flow init | "Initializing the Flow project. This creates the `.flow` file you'll edit." |
+| Verify project layout | "Confirming the solution/project layout is correct before continuing." |
+| Registry discovery | "Looking up `<node-type>` in the registry so I can wire its inputs correctly…" |
+| Node add (multi-step) | "Adding the `<node-type>` node and copying its registry definition into the file…" |
+| Edit flow JSON | "Editing the flow JSON to add the `<thing>`." |
+| Edge wiring | "Wiring `<from>` → `<to>` so data flows in the right order." |
+| Variable mapping | "Mapping output variables on the End node — every reachable End needs them." |
+| Script body update | "Updating the script body in the `<nodeId>` node." |
+| Resource refresh | "Syncing connection and resource declarations into the solution before upload…" |
+| Validate | "Running validate. This catches missing edges, bad expressions, and wiring mistakes." |
+| Format | "Formatting the layout. Studio Web renders nodes correctly only after format normalizes their sizes." |
+| Studio Web upload | "Pushing to Studio Web. This is the safe path — no execution, just the visual editor." |
+| Pack for Orchestrator | "Packing the solution for Orchestrator deploy…" |
+| Orchestrator publish | "Publishing the package to Orchestrator…" |
+| Debug consent | "Running debug end-to-end. Real systems will be hit (emails sent, Slack posts, API calls)." |
+| Process run | "Triggering the deployed process now…" |
+| Job status | "Checking the job's current status…" |
+| Job traces | "Pulling traces — verbose execution timeline." |
+| Instance pause | "Pausing the running instance…" |
+| Instance resume | "Resuming the instance from where it paused…" |
+| Instance cancel | "Cancelling the instance…" |
+| Instance retry | "Retrying the faulted instance from the last successful checkpoint…" |
+| Incident fetch | "Fetching the incident record — this is the structured error report from the failed run." |
+| Variable inspection | "Reading the runtime variable state at the moment of failure…" |
+| Flow correlation | "Mapping the faulting element ID back to a node in your `.flow` file…" |
+| Traces (last resort) | "Pulling traces. Last resort — the previous steps weren't enough." |
+
+## Threshold for `TodoWrite`
+
+This table applies only once narration/todos are engaged (see [When to engage](#when-to-engage)). In silent mode there is no user-facing narration or todo list regardless of journey size.
+
+| Journey size | Narration | TodoWrite |
+| --- | --- | --- |
+| Single edit (1–2 actions, no decisions) | Yes — 1 line | No |
+| Small edit (3–5 actions or 1 decision) | Yes — line per logical step | Optional, agent's call |
+| Standard journey (greenfield, brownfield with multiple nodes, ship, run, full diagnose) | Yes — line per logical step | **Required** — granular |
+| Complex flow (10+ nodes, multiple resource bindings, planning phase) | Yes — denser cadence | **Required** — granular, with sub-todos |
+
+## Todo granularity
+
+A todo is a **state-changing outcome the user cares about**. One logical step ≈ one todo. Multiple actions across multiple tools can map to one todo.
+
+**Counts as a todo:**
+- Solution scaffolded
+- Flow project initialized
+- Node added and wired
+- Edges connected
+- Variables defined and mapped
+- Validate green
+- Format applied
+- Resources refreshed
+- Uploaded to Studio Web
+- Incident fetched and read
+- Root cause classified
+
+**Does NOT count as a todo (invisible plumbing):**
+- Single `registry get` for schema lookup
+- `ls` / `cat` / `Glob` to confirm a path
+- Reading a file before editing it
+- Re-running the same `validate` after a one-character fix (same todo, just not yet checked)
+- Parsing JSON output
+
+## Pivot rules
+
+If the user redirects scope mid-journey ("skip the connector — use HTTP instead"):
+
+1. Narrate the pivot — "Switching from connector to HTTP node. Updating todos."
+2. Update `TodoWrite`:
+   - Mark obsolete in-flight todos as cancelled and drop them from the list.
+   - Insert new todos for the new direction at the right spot.
+   - Leave completed todos in place — they're history, not work.
+3. Continue from the new in-progress todo.
+
+## Anti-patterns
+
+- **Never narrate every command.** "Running `registry search`… running `registry get`… running `flow node add`…" — three lines for one logical step is noise. One step, one line.
+- **Never narrate every Read/Edit.** Reading the `.flow` before editing it is plumbing. The step's opening line covers it.
+- **Never recap flag-level or JSON-structure-level detail.** The user does not care that you used `--output json` or that `inputs.detail.bodyParameters` is the field name. Speak in user terms.
+- **Never narrate or spin up a user-facing todo list when the user hasn't asked for verbosity.** Silent by default. Surfacing every step unprompted is noise.
+- **When engaged, never skip narration on a step transition.** Silent transitions leave the user lost.
+- **Never create a todo per bash call.** Todos are user-meaningful outcomes, not the agent's internal action log.
+- **When engaged, never skip `TodoWrite` on a standard journey.** Above the trivial threshold, the granular list is mandatory.
+- **Never use first-person filler.** "Let me…", "I'll go ahead and…", "I'm going to…" — drop. Lead with the verb.
+- **Never repeat the prior line's content.** If the previous narration said "Adding the Slack node and wiring its inputs", the next line is *not* "Adding the Slack node now" — it's the next step.