@uipath/skills 1.204.0 → 1.204.1

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

@@ -0,0 +1,86 @@
+# Wiring Node Outputs to Downstream Inputs
+
+Use this reference whenever a `.flow` JSON field references a previous node output, workflow variable, or `$metadata.*` / `$self.*`. It is the source of truth for `=js:` expressions; node-type plugins defer to it.
+
+## Core rule
+
+In value-typed fields, every `$vars.*`, `$metadata.*`, or `$self.*` reference must start with `=js:`. Otherwise, runtime treats the rewritten value as a literal. A missing prefix is silent: the serializer rewrites `$vars`→`vars` with or without `=js:`, so `flow validate` passes and the file looks plausible, but at runtime the BPMN engine sees a plain string and never evaluates it.
+
+Use `$vars.<sourceNodeId>.output.<field>`—never `nodes.X.output.Y`. `<sourceNodeId>` is the producing node's `id`; `output` is the standard output port (`error` is the error port); `<field>` is the output path.
+
+```text
+=js:$vars.fetchUser1.output
+=js:$vars.createRecord1.output.Id
+=js:$vars.queryRecords1.output[0].Id
+=js:$vars.fetchUser1.output.id === $vars.input.userId
+=js:$metadata.instanceId
+=js:`Hello ${$vars.userName}`
+```
+
+Static values do not need `=js:`. For mixed strings, use `=js:` with JavaScript template literals and `${}`.
+
+## Where `=js:` applies
+
+| Context | Field | Rule |
+|---|---|---|
+| Connector activity nodes (`uipath.connector.<connector-key>.<activity>`) | `inputs.detail.bodyParameters.*`, `queryParameters.*`, `pathParameters.*` | **YES** |
+| Managed HTTP (`core.action.http.v2`) | `inputs.detail.bodyParameters.url`, `headers`, `query`, `body` | **YES**; dynamic fields are stored here in `.flow` JSON in both manual and connector mode, regardless of how the CLI `--detail` flag accepts them at the top level |
+| Custom HTTP (`core.action.http`) | `inputs.url`, `headers`, `body`, `queryParams` | **YES**; deprecated, prefer `core.action.http.v2` |
+| HTTP branches | `inputs.branches[].conditionExpression` | **NO**; already JS |
+| Decision (`core.logic.decision`) | `inputs.expression` | **NO**; already JS |
+| Switch (`core.logic.switch`) | `inputs.cases[].expression` | **NO**; already JS |
+| End nodes (`core.control.end`) | `outputs.<varId>.source` | **YES** |
+| Variable updates | `variables.variableUpdates.<nodeId>[].expression` | **NO**; use `{ "type": "jsExpression", "expression": "<bare JS>", "fieldType": "<target variable type>" }`. A `=js:` string fails `flow validate` at the 1.9→1.10 migration. See [variables-and-expressions.md § Variable Updates](variables-and-expressions.md#variable-updates-variableupdates). |
+| Loop nodes (`core.logic.loop`) | `inputs.collection` | **YES** |
+| Subflow nodes (`core.subflow`) | `inputs.<inputId>.source` | **YES** |
+| Script nodes (`core.action.script`) | `inputs.script` body | **NO**; the body is already JS and reads `$vars.*` directly |
+| **Chat `conversationId`** (`uipath.conversational.*` nodes) | `inputs.conversationId` — a structured binding object to the trigger's only output, `$vars.<conversationTriggerId>.output.conversationId`. send-message also needs `exchangeId`, which is `conversationContext.latestExchangeId` on the wait node — there is no `output.exchangeId`. | **NO** — the expression sits unprefixed inside the object's `expression` field. See [conversational-agent/impl.md § Node JSON](../author/plugins/conversational-agent/impl.md#node-json). |
+| **Chat `conversationalAgentSettings`** (`uipath.agent.conversational`, `uipath.core.agent.*` when conversational) | `inputs.conversationalAgentSettings` — five structured binding objects: `context` plus the `conversationId`, `exchangeId`, `messages` and `userSettings` derived from it. All five must be written when authoring from the CLI. | **NO** — the expression sits unprefixed inside each object's `expression` field. See [conversational-agent/impl.md § The `conversationalAgentSettings` Wiring Rule](../author/plugins/conversational-agent/impl.md#the-conversationalagentsettings-wiring-rule). |
+| **Voice `callContext`** (`uipath.agent.voice`, `uipath.conversational.voice.end-call`) | `inputs.callContext` — a structured binding object `{ "type": "jsExpression", "expression": "$vars.<originNodeId>.output.callContext", "fieldType": ... }`, never a bare string. `fieldType` is `"object"` on the voice agent and `"string"` on the end-call node. | **NO** — the expression sits unprefixed inside the object's `expression` field. See [author/plugins/inline-voice-agent/impl.md § The `callContext` wiring rule](../author/plugins/inline-voice-agent/impl.md#the-callcontext-wiring-rule). |
+| **Inline-agent prompt** (`uipath.agent.autonomous` / `uipath.agent.voice` `agent.json` `messages[].content`) | Tokens use the flattened delivery key, never the flow expression: `{{input.<flowNodeId>__output__<field>}}`. The key is delivered by the node's `inputs.agentInputVariables[]` binding (`=$vars.<flowNodeId>.output.<field>`) and declared in `inputSchema.properties`. Mirror in `contentTokens[]` as `{ "type": "variable", "rawString": "input.<flowNodeId>__output__<field>" }` — `rawString` is brace-free with no added spaces, and `uip agent refresh` regenerates it, so never hand-author it. **Never a raw `{{ $vars.… }}`** (nothing rewrites agent.json prompt text — the model receives it literally) and never a bare `{{name}}`. | **NO** — `{{ ... }}` tokens, not `=js:`. See [author/plugins/inline-agent/impl.md § Wiring Flow Variables into Agent Prompts](../author/plugins/inline-agent/impl.md#wiring-flow-variables-into-agent-prompts). Encoding note: a read `agent.json` may use the flat `__` input keys or a newer nested (dotted-key) form — author flat, read both (see the impl.md encoding note). |
+
+Do not add `=js:` to Decision, Switch, or HTTP branch conditions, script bodies, variable-update expressions, or inline-agent tokens; these formats are parsed separately.
+
+## Connector and HTTP wiring
+
+```jsonc
+"inputs": {
+  "detail": {
+    "method": "POST",
+    "endpoint": "/v2/{entityName}/UpdateEntityRecord",
+    "pathParameters": { "entityName": "Entity" },
+    "queryParameters": {
+      "recordId": "=js:$vars.createRecord1.output.Id",
+      "expansionLevel": "3"
+    },
+    "bodyParameters": {
+      "Name": "static-value",
+      "AccountId": "=js:$vars.queryAccounts1.output[0].Id",
+      "Notes": "=js:`Created from flow run ${$metadata.instanceId}`"
+    }
+  }
+}
+```
+
+Plugin-specific path fields are not value fields; follow the plugin reference. In particular, Transform `inputs.collection` must be a path such as `"$vars.orders.output.items"`, without `=js:`.
+
+## Never do this
+
+1. **Never invent `nodes.X.output.Y`;** use `$vars` references.
+2. **Never write `$vars.X.output.Y` without `=js:`** in an expression value field. The `$vars→vars` rewrite still occurs, producing a literal. Use the plugin-specific format for path fields such as Transform `inputs.collection`.
+3. **Never wrap Decision, Switch, or HTTP branch conditions in `=js:`.** They already parse JS.
+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:` with JS template literals instead.
+5. **Never quote `=js:` itself in an expression.** `"=js:$vars.X"` is correct; `"\"=js:$vars.X\""` is a string containing the prefix.
+
+## Runtime and migration behavior
+
+`expression-transform.ts` rewrites `$vars` → `vars` in every node-data string, whether or not `=js:` is present. The prefix tells the BPMN engine to evaluate the result; without it, the rewritten value remains literal. `bpmn-moddle.ts` has an `ensureJsPrefix` fallback only for variable updates. Connector and HTTP activity inputs have no equivalent fallback, so write `=js:` explicitly.
+
+## Validation
+
+When a flow outputs literal `vars.X.output.Y`, `nodes.X.output.Y`, or another unevaluated expression:
+
+1. Open the `.flow` file.
+2. Search for the token: `grep '"vars\.' <project>.flow` or `grep '"\$vars\.' <project>.flow`.
+3. In `bodyParameters`, `queryParameters`, `pathParameters`, end-node `source`, and other value fields, prepend `=js:` to each variable reference.
+4. Run `uip maestro flow validate` and re-debug.

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

@@ -0,0 +1,113 @@
+# UX — Narration and Todos
+
+Two **opt-in** rules govern communication during work. They are **off by default**. Engage them when the user requests narration/progress tracking or signals a verbosity preference. Once engaged, they apply across every capability (Author, Operate, Diagnose, Evaluate), journey, and action type (`uip` CLI, shell builtins, Read/Write/Edit, Glob/Grep).
+
+> Inherits from [SKILL.md](../../SKILL.md). These rules are canonical; capability indexes and journey docs reference this file.
+
+## When to engage
+
+Engage narration and todos if any condition holds:
+
+- The user explicitly asks to narrate, show steps, keep a todo list, track progress, explain as work proceeds, be verbose, or be detailed.
+- The user has a standing verbosity preference in-session or in recalled memory.
+- The user asks a question requiring running commentary, such as what is happening or where work stands.
+
+Otherwise use **silent mode**: work quietly and surface only decisions, failures, consent gates (`flow debug`), and the final result. Do not provide per-step narration or a user-facing todo list. Private todos remain optional for large journeys.
+
+## The two rules
+
+Once engaged:
+
+1. **Narrate every logical step in plain English.** Give one short line before each step explaining what is being done and why in user terms; do not require knowledge of `bash`, `uip` flags, or `.flow` JSON.
+2. **Maintain a granular progress list** for every journey above the trivial threshold: one todo per logical step, kept current. Standard journeys usually have 10+ items; complex flows have more. Do not target a count; derive it from the actual steps.
+
+### Logical steps
+
+A logical step is the smallest user-meaningful outcome, usually 1–5 actions grouped by intent across tools. Examples include discovering and adding a node, confirming project layout, updating a script body, validating a flow, or triaging a fault. Bash plumbing inside a step is covered by its narration.
+
+## Narration cadence
+
+| Situation | Rule |
+|---|---|
+| Start of logical step | Narrate one short line in plain English. |
+| Multiple actions within a step | Do not add narration. |
+| Step transition | Narrate the next step. |
+| Decision point | Give a brief line before asking the user; explain the decision's consequence. |
+| Failure/retry | Always narrate what failed and what will be tried next, even in silent mode. |
+| Trivial probe (`uip --version`, repeated `login status` in the same minute) | Skip. |
+| Non-`uip` shell plumbing (`ls`, `cat`, `mkdir`, `cd`) | Skip; the step line covers it. |
+| File reads/edits inside a step | Skip; the step line covers them. |
+
+## Narration lines
+
+Keep each line to approximately 15 words or fewer, as one sentence or fragment. Use system voice, not first person. Use user terms rather than commands, flags, or JSON internals. State the actual subject when scope is ambiguous, convey new information, and avoid ceremony, recaps, and repetition.
+
+Use or adapt these patterns:
+
+| 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 | "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." |
+
+## Progress-list threshold
+
+This applies only when narration/todos are engaged. In silent mode, journey size never creates a user-facing list.
+
+| Journey | Narration | Progress list |
+|---|---|---|
+| Single edit: 1–2 actions, no decisions | One line | None |
+| Small edit: 3–5 actions or one decision | One line per step | Optional |
+| Standard: greenfield, multi-node brownfield, ship, or full diagnose | One line per step | Required and granular |
+| Complex: 10+ nodes, multiple resource bindings, or planning phase | Denser cadence | Required, granular, with sub-todos |
+
+## Todo rules
+
+A todo represents a state-changing outcome the user cares about; roughly one logical step. Multiple tool actions may form one todo.
+
+Valid todos include: solution scaffolded; Flow project created; 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.
+
+Do not create todos for registry lookup, `ls`/`cat`/`Glob` path checks, pre-edit reads, parsing JSON, or rerunning the same `validate` after a one-character fix. Keep such plumbing invisible.
+
+## Pivots
+
+When scope changes:
+
+1. Narrate the pivot, for example: "Switching from connector to HTTP node. Updating todos."
+2. Mark obsolete in-flight todos cancelled and remove them; insert todos for the new direction in the correct position; retain completed todos as history.
+3. Continue with the new in-progress todo.
+
+## Anti-patterns
+
+- Never narrate every command, Read, Edit, or shell action; narrate logical outcomes.
+- Never recap flags or JSON structure.
+- Never show narration or a user-facing todo list without an engagement trigger.
+- When engaged, never omit narration at a step transition or the required list for a standard journey.
+- Never create a todo per bash call.
+- Never use first-person filler such as "Let me", "I'll go ahead", or "I'm going to".
+- Never repeat the previous narration; move to the next logical step.