@uipath/flow-tool 1.202.1 → 1.203.0-preview.160

package/dist/services/connector-binding-validator.d.ts

@@ -31,6 +31,7 @@ export declare const MANAGED_HTTP_NODE_TYPE = "core.action.http.v2";
 export interface ConnectorBindingNode {
     id: string;
     type: string;
+    typeVersion?: unknown;
     name?: unknown;
     display?: {
         label?: unknown;
@@ -43,6 +44,13 @@ export interface ConnectorBindingWorkflow {
     subflows?: Record<string, {
         nodes?: ConnectorBindingNode[];
     }>;
+    /**
+     * The flow's `definitions[]` list. Read only to skip the MCP check on a
+     * node whose definition already marks `toolName` required (the shared
+     * `schema-validation` rule reports that one — avoid a second, softer
+     * report for the same defect).
+     */
+    definitions?: unknown[];
 }
 export interface ConnectorBindingValidationOptions {
     /**
@@ -88,7 +96,8 @@ export interface ConnectorCatalog {
 export declare function loadConnectorCatalog(): Promise<ConnectorCatalog>;
 /**
  * Walk every node in the flow + every subflow and emit one issue per
- * unbound, connector-shaped Managed HTTP node. Scope mirrors
+ * unbound, connector-shaped Managed HTTP node — plus one per MCP "Run a Tool"
+ * node with no selected tool (UV-15018). Scope mirrors
  * `validateResourceBindings` so the new check stays consistent with the
  * §A4 binding-integrity pass already in `FlowValidateService`.
  */

package/dist/services/definitions-lookup.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The one lookup for a node's `definitions[]` entry, shared by every site
+ * that resolves a definition to WRITE to it or to act on its content
+ * (`patchOutputType` / `patchRequiredInputs` in connector-service, the
+ * toolName-required suppression in connector-binding-validator).
+ *
+ * `definitions[]` can legitimately hold two versions of one `nodeType`
+ * (schema-validation keys manifests by `nodeType:version`), so an unversioned
+ * lookup can resolve the wrong version's entry. The rules:
+ *
+ * - A node that carries a `typeVersion` resolves ONLY the entry with that
+ *   exact `version`. A node whose version has no entry resolves nothing —
+ *   it does not validate against any of the present entries either
+ *   (`validateDefinitionsPresent` reports it), and patching a different
+ *   version's entry would stamp this node's truth onto other nodes' schema.
+ * - A node with NO `typeVersion` (hand-authored flows, unit fixtures) falls
+ *   back to a SOLE `nodeType` match — never one of several versions picked
+ *   arbitrarily.
+ *
+ * Read-only display paths that prefer a best guess over nothing wrap this
+ * with a first-entry fallback (`findMatchingDefinition` in flow-eval-utils);
+ * write paths must not.
+ */
+export declare function findNodeDefinition(definitions: ReadonlyArray<unknown> | undefined, node: {
+    type?: string;
+    typeVersion?: unknown;
+}): Record<string, unknown> | undefined;

package/dist/services/flow-debug-service.d.ts

@@ -0,0 +1,290 @@
+/**
+ * Service for debugging Flow files.
+ *
+ * Converts a .flow file to BPMN XML, generates the required project files,
+ * begins a debug session in Orchestrator, creates a debug instance in PIMS,
+ * and polls for execution status.
+ */
+import type { Workflow } from "@uipath/flow-core";
+import type { BeginSessionResponse, DebugCallbacks, DebugInstanceResponse, DebugInstanceStatusResponse, DebugResult, DebugVariablesResponse, ElementExecution, StudioWebDebugConfig } from "@uipath/maestro-sdk";
+import { RuntimeProfile } from "@uipath/packager-tool-flow";
+import { type SolutionImportResponse } from "@uipath/solution-sdk";
+export type { BeginSessionResponse, DebugCallbacks, DebugInstanceResponse, DebugInstanceStatusResponse, DebugResult, DebugVariablesResponse, ElementExecution, SolutionImportResponse, StudioWebDebugConfig, };
+/**
+ * Canonical user-facing message + instructions surfaced when `flow debug`
+ * is run against a standalone Flow project (no enclosing `.uipx`).
+ *
+ * Exported so the command layer (and tests) can assert the exact envelope
+ * shape required by UiPath/cli#2023 without re-stringifying it.
+ */
+export declare const FLOW_DEBUG_MISSING_SOLUTION_MESSAGE = "Flow debug requires this Flow to be inside a solution.";
+export declare const FLOW_DEBUG_MISSING_SOLUTION_INSTRUCTIONS = "Create a solution wrapper and import this Flow before debugging: `uip solution init <name>` then `uip solution projects import <flow-dir>` from inside the solution directory, then re-run `uip maestro flow debug`.";
+/**
+ * Canonical user-facing message surfaced when the Flow project's directory
+ * is not listed in the enclosing solution's `.uipx` Projects[] manifest.
+ *
+ * Without this preflight, Studio Web rejects the upload with an opaque
+ *   `Import failed (400): The solution archive does not contain any valid projects.`
+ * (MST-10004). Failing locally with the project path + solution path is
+ * far more actionable.
+ */
+export declare const FLOW_DEBUG_UNREGISTERED_PROJECT_MESSAGE = "Flow project is not registered in the enclosing solution.";
+export declare const buildFlowDebugUnregisteredProjectInstructions: (projectDir: string, solutionFile: string) => string;
+/**
+ * Thrown by {@link FlowDebugService.executeProjectViaStudioWeb} when the
+ * Flow project is not enclosed by a `.uipx` solution wrapper.
+ *
+ * The command layer translates this into a `ValidationError` envelope
+ * (exit code 3) so users get an actionable, locally-generated diagnostic
+ * before any upload is attempted — fixing the opaque server-side 400
+ * tracked in UiPath/cli#2023.
+ */
+export declare class MissingSolutionWrapperError extends Error {
+    readonly instructions: string;
+    constructor(message?: string, instructions?: string);
+}
+/**
+ * Thrown by {@link FlowDebugService.executeProjectViaStudioWeb} when an
+ * enclosing `.uipx` solution wrapper exists but does not list the Flow
+ * project directory in its `Projects[]` manifest.
+ *
+ * The command layer translates this into a `ValidationError` envelope
+ * (exit code 3). This replaces the opaque server-side
+ *   `Import failed (400): The solution archive does not contain any valid projects.`
+ * surfaced from Studio Web (MST-10004) with a typed, locally-detected
+ * diagnostic that names the exact repair command.
+ */
+export declare class UnregisteredProjectError extends Error {
+    readonly instructions: string;
+    readonly projectDir: string;
+    readonly solutionFile: string;
+    constructor(projectDir: string, solutionFile: string);
+}
+/**
+ * What an upload-only run returns: the solution is on Studio Web and the
+ * designer URL is known, but no debug session or instance was created.
+ */
+export interface StudioWebUploadResult {
+    uploadedOnly: true;
+    solutionId: string;
+    studioWebUrl: string;
+}
+export declare const FLOW_DEBUG_INBOUND_VOICE_MESSAGE = "Inbound voice flows cannot be debugged from the CLI.";
+export declare const buildFlowDebugInboundVoiceInstructions: (triggerLabel: string) => string;
+/**
+ * Thrown when the flow starts from an incoming-call trigger. Only a real call
+ * to a published flow can raise one, so the run would never advance.
+ */
+export declare class InboundVoiceDebugError extends Error {
+    readonly instructions: string;
+    constructor(triggerLabel: string);
+}
+/**
+ * Reject a flow that starts from an incoming-call trigger. Keyed on the
+ * trigger, not on voice nodes: an outbound flow carries the same nodes.
+ */
+export declare function assertNotInboundVoiceFlow(workflow: {
+    nodes?: readonly unknown[];
+}): void;
+export declare class FlowDebugService {
+    private readonly fs;
+    constructor();
+    /**
+     * Pre-flight check: confirm the Flow project lives inside a `.uipx`
+     * solution wrapper by walking ancestor directories.
+     *
+     * Throws {@link MissingSolutionWrapperError} if no `.uipx` is found.
+     * Reuses {@link findNearestParentUipxFile} from `@uipath/solution-sdk`
+     * to share the ancestor-walk semantics with `uip solution projects import`.
+     *
+     * Returns the absolute path of the `.uipx` file when present so callers
+     * can log it without re-walking.
+     */
+    assertEnclosingSolution(projectPath: string): Promise<string>;
+    /**
+     * Pre-flight check: confirm the Flow project's directory is actually
+     * listed in the enclosing solution's `.uipx` `Projects[]` manifest.
+     *
+     * Throws {@link UnregisteredProjectError} when the manifest does not
+     * include the project. Comparison is canonicalized via `realpath()`
+     * so case-insensitive filesystems and symlinks don't yield false
+     * negatives.
+     *
+     * This is the local guard for MST-10004: without it, Studio Web
+     * silently accepts the upload and then rejects the import with an
+     * opaque `code:20001 / "The solution archive does not contain any
+     * valid projects."` HTTP 400. By failing locally, the agent (or
+     * human) gets the exact repair command (`uip solution projects add`)
+     * before any network I/O.
+     */
+    assertProjectRegisteredInSolution(projectPath: string, solutionFile: string): Promise<void>;
+    /**
+     * Read and parse a .flow file.
+     */
+    readFlowFile(flowFilePath: string): Promise<Workflow>;
+    /**
+     * Read a .bpmn file and return the raw XML string.
+     */
+    readBpmnFile(bpmnFilePath: string): Promise<string>;
+    /**
+     * Convert a Workflow to BPMN XML using @uipath/flow-converter.
+     *
+     * The inline-agent `Orchestrator.StartInlineAgentJob` activity's
+     * `entryPoint` must stay BARE (`<projectId>/agent.json`, no `content/`
+     * prefix). At debug time Orchestrator's debug-flow detector resolves the
+     * agent by matching the activity `entryPoint` against the
+     * `FpsProperties.debug.master.processes[].entryPointPath` entry, and that
+     * entry uses the bare path. A `content/`-prefixed activity entryPoint never
+     * matches, so the agent faults with `[170007]` "the job's associated
+     * process could not be found" (verified byte-for-byte against a working
+     * Studio Web debug capture, which also emits the bare path).
+     *
+     * We therefore do NOT call `setPublishIntentOnInlineAgents` here — that
+     * marks agents `__packageIntent = "Publish"`, which makes the converter
+     * emit the `content/`-prefixed form used by real publish/deploy. That form
+     * is wrong for a debug session.
+     */
+    convertToBpmn(workflow: Workflow, projectDir?: string): Promise<string>;
+    /**
+     * Reconstruct inline-agent `agentInputVariables` from each agent's
+     * `agent.json` `inputSchema` when the flow node leaves them empty.
+     *
+     * Studio Web keeps the input binding in the agent's `inputSchema` and rebuilds
+     * the node's `agentInputVariables` from it on load; the `.flow` it writes
+     * carries an empty `agentInputVariables`. The CLI converter derives the
+     * agent's `JobArguments` from `agentInputVariables` (it never reads
+     * `agent.json`), so an SW-authored flow would otherwise convert to an agent
+     * with empty input — works in SW, fails on `uip maestro flow debug`.
+     *
+     * We mirror SW: for each inline-agent node, read `<projectDir>/<source>/agent.json`
+     * and **reconcile** the node's `agentInputVariables` against the agent's
+     * `inputSchema.properties` — the contract the runtime actually binds. We
+     * *add* a derived entry for every schema input LEAF the node is missing and
+     * *preserve* every entry the node already declares, so a custom/divergent
+     * binding is never clobbered. Leaves are enumerated encoding-agnostically
+     * (MST-12020): a flat key (`<node>__output__<field>`) is one leaf; a NESTED
+     * schema's `x-uipath-container` trees are descended to their leaves — so an
+     * agent.json authored by a nested-flag canvas still reconciles per-field
+     * bindings instead of one un-navigable whole-container binding. Either way
+     * the derived id is the FLAT spelling (matching the packager's flat-healed
+     * prompt tokens), the binding is `=$vars.<node>.output.<field>`
+     * (`metadata`-rooted paths → `$metadata`), and "already declares" is
+     * checked on the CANONICAL dotted path so a flat and a nested spelling of
+     * the same input never produce a duplicate JobArgument.
+     *
+     * Reconciling (rather than only filling an empty list) also catches drift: an
+     * `agent.json` that gained an input the `.flow` node never re-wired would
+     * otherwise silently drop that input at debug. We therefore always read the
+     * agent.json. Best-effort — a missing/unreadable `agent.json` or absent
+     * `inputSchema` leaves the node as-is, and a node that already covers every
+     * schema key is left untouched (no spurious mutation).
+     */
+    private hydrateInlineAgentInputs;
+    /**
+     * Generate project files (operate.json, entry-points.json, bindings_v2.json,
+     * package-descriptor.json) into a temporary directory alongside the BPMN and .flow file.
+     */
+    generateProjectFiles(flowData: Workflow, bpmnXml: string, flowFileContent?: string, startEventId?: string, profile?: RuntimeProfile): Promise<string>;
+    /**
+     * Build a .uis solution package from the generated project files.
+     * Creates a solution wrapper, zips it into .uis format.
+     */
+    buildSolutionPackage(projectDir: string, projectName: string): Promise<string>;
+    private writeSingleProjectSolutionMetadata;
+    /**
+     * Build the `debug.master.processes` descriptors for every in-solution
+     * project so a flow-as-node callee's `Orchestrator.StartAgenticProcess`
+     * resolves the child — the same FpsProperties registry inline agents use,
+     * so no Orchestrator provisioning or deployed release is needed.
+     *
+     * Each descriptor pairs the Studio Web-minted `projectId` (from the upload
+     * result, matched by folder name) and the uploaded `solutionId` with the
+     * project's type + per-project entry point read from the staged solution.
+     * The lead Flow being debugged gets the exact BPMN + start node the session
+     * launches from; standalone Agent projects are skipped (inline agents are
+     * registered separately via `inlineAgents`).
+     */
+    private buildSolutionProjectDescriptors;
+    /**
+     * Compile a sibling flow project's `.flow` to BPMN + packaging artifacts
+     * in place inside its staged directory. Sibling flow projects are copied
+     * from the solution with only their `.flow` source; a flow-as-node call
+     * needs the compiled `.bpmn` (and bindings/manifests) in the package or the
+     * child job faults with 180003 (FileMissingInProjectArchive). Mirrors the
+     * artifact generation the lead flow already gets.
+     */
+    private generateSiblingFlowPackage;
+    /**
+     * Write a flow project's debug-package artifacts (`.flow`, compiled
+     * `.bpmn`, packaging manifests, resolved flow) into `projectDir`. Shared by
+     * the lead flow being debugged and each sibling flow-as-node callee so the
+     * conversion/packaging pipeline lives in one place. Returns the values the
+     * lead path needs downstream (entry points, start node, bpmn file name).
+     */
+    private writeFlowProjectPackage;
+    /** Map a raw `.uiproj` ProjectType to the BeginSession wire vocabulary. */
+    private toWireProjectType;
+    /**
+     * Normalize an entry point to the `debug.master` form: no leading slash,
+     * no `content/` prefix (e.g. `/Flow.bpmn#start` or
+     * `content/new.bpmn#manualTrigger1` → `Flow.bpmn#start` / `new.bpmn#manualTrigger1`).
+     */
+    private normalizeEntryPoint;
+    /** Read the first `entry-points.json` filePath in a project dir, or "". */
+    private readFirstEntryPointPath;
+    /**
+     * Derive an entry point from a project's compiled `.bpmn` start event,
+     * for projects whose `entry-points.json` is empty (ProcessOrchestration).
+     * Matches Studio Web's `/{bpmn}#{startEvent}` form (leading slash kept).
+     * Returns "" when no `.bpmn` is present.
+     */
+    private deriveEntryPointFromBpmn;
+    /** Read a project's `.uiproj` `ProjectType`, or undefined if unavailable. */
+    private readProjectTypeRaw;
+    /**
+     * Build a name→type map from the `.uipx` Projects array so
+     * {@link buildSolutionProjectDescriptors} can resolve the type for
+     * projects that have no `project.uiproj` (JS/TS Functions).
+     */
+    static buildProjectTypeMap(projects?: Array<{
+        ProjectRelativePath: string;
+        Type?: unknown;
+    }>): Map<string, string>;
+    /**
+     * Full Studio Web debug flow from a flow project directory:
+     * 1. Validate project directory has required files
+     * 2. Read .flow file + generate packaging artifacts on the fly
+     * 3. Build .uis solution package containing ALL projects in the solution
+     * 5. Upload/overwrite to Studio Web → get projectId + solutionId
+     * 6. Begin debug session in Orchestrator → get jobKey
+     * 7. Create debug instance in PIMS with solutionId + projectId
+     * 8. Poll PIMS debug-instances for completion
+     */
+    executeProjectViaStudioWeb(projectPath: string, config: StudioWebDebugConfig, callbacks?: DebugCallbacks, pollInterval?: number, options?: {
+        inputs?: Record<string, unknown>;
+        maxPolls?: number;
+        /**
+         * Upload the solution and stop. For a flow only a chat UI can drive,
+         * a debug instance would sit unused — and its message subscription
+         * would block the next run — so the CLI hands the user the designer
+         * URL instead of starting a session nobody can advance.
+         */
+        uploadOnly?: boolean;
+    }): Promise<DebugResult | StudioWebUploadResult>;
+    /**
+     * Full Studio Web debug flow:
+     * 1. Read .flow/.bpmn file
+     * 2. Convert to BPMN (if .flow)
+     * 3. Generate project files
+     * 4. Build .uis solution package
+     * 5. Upload to Studio Web → get projectId + solutionId
+     * 6. Begin debug session in Orchestrator → get jobKey
+     * 7. Create debug instance in PIMS with solutionId + projectId
+     * 8. Poll PIMS debug-instances for completion
+     */
+    executeViaStudioWeb(filePath: string, config: StudioWebDebugConfig, callbacks?: DebugCallbacks, pollInterval?: number, options?: {
+        inputs?: Record<string, unknown>;
+        keep?: boolean;
+        maxPolls?: number;
+    }): Promise<DebugResult>;
+}

package/dist/services/flow-eval-types.d.ts

@@ -1,6 +1,6 @@
-import type { Evaluation, EvaluationSet, Evaluator, EvaluationCriteria as SchemaEvaluationCriteria, Simulation } from "./flow-eval-schema/index.js";
+import type { Evaluation, EvaluationSet, Evaluator, EvaluationCriteria as SchemaEvaluationCriteria, Simulation, SimulationStrategy } from "./flow-eval-schema/index.js";
 export type EvaluationCriteria = SchemaEvaluationCriteria;
 export type FlowEvaluator = Evaluator;
 export type FlowEvaluation = Evaluation;
 export type FlowEvaluationSet = EvaluationSet;
-export type { Simulation };
+export type { Simulation, SimulationStrategy };

package/dist/services/flow-eval-utils.d.ts

@@ -1,3 +1,4 @@
+import type { StudioWebDebugConfig } from "./flow-debug-service.js";
 import { type EvaluatorTypeId } from "./flow-eval-schema/index.js";
 import type { EvaluationCriteria, FlowEvaluator } from "./flow-eval-types.js";
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
@@ -11,4 +12,32 @@ export declare function buildEvaluatorConfig(typeId: EvaluatorTypeId, options: {
     model?: string;
     prompt?: string;
 }): Record<string, unknown>;
+/**
+ * Resolves the current login status into a {@link StudioWebDebugConfig}.
+ * Throws if the login is missing any required field, including organizationName.
+ */
+export declare function resolveLoginConfig(): Promise<StudioWebDebugConfig>;
+/**
+ * Resolves the login fields needed by {@link FlowEvalRunApi} metadata calls.
+ * Does not require organizationName — only the base URL, org/tenant IDs,
+ * and auth token.
+ */
+export declare function resolveEvalApiConfig(): Promise<{
+    baseUrl: string;
+    organizationId: string;
+    tenantName: string;
+    tenantId: string;
+    authToken: string;
+}>;
+/**
+ * Finds the definition entry matching a node's type (and optionally version)
+ * from the flow's definitions array. Pure logic, no I/O.
+ *
+ * BEST-EFFORT read variant of `findNodeDefinition` (definitions-lookup.ts):
+ * when the strict lookup resolves nothing (several versions, none matching),
+ * this falls back to the first same-type entry — display/read paths prefer a
+ * best guess over nothing. Paths that WRITE to the definition (or suppress
+ * diagnostics based on it) must use the strict helper directly.
+ */
+export declare function findMatchingDefinition(nodeType: string, typeVersion: string | undefined, definitions: Array<Record<string, unknown>>): Record<string, unknown> | undefined;
 export declare function buildDefaultCriteria(evaluators: FlowEvaluator[], expectedOutput: Record<string, unknown> | undefined, searchText: string | undefined): Record<string, EvaluationCriteria | null | undefined>;

package/dist/services/flow-validate-service.d.ts

@@ -309,6 +309,45 @@ export declare class FlowValidateService {
      * `validateGlobalVariableUniqueness`.
      */
     private validateGlobalTriggerBindings;
+    /**
+     * Bare `$vars.<id>` read of a trigger-scoped input (UV-16316).
+     *
+     * When an `in` global declares a `triggerNodeId` that points at a real
+     * trigger node in this scope, the runtime surfaces that value ONLY under the
+     * trigger's output — `$vars.<triggerNodeId>.output.<id>`. A bare `$vars.<id>`
+     * read does not address the trigger input; it resolves today only because a
+     * `core.trigger.manual` node also emits a process-level input of the same
+     * name, so re-pointing the flow at a connector or scheduled trigger makes the
+     * bare read resolve to null and the flow faults or silently uses a wrong
+     * value.
+     *
+     * `--strict-expressions` already caught this through the expression type
+     * checker (the bare name is not on the `$vars` type for a trigger-scoped
+     * input), but plain `flow validate` — the default, and what the maestro-flow
+     * skill tells agents to run — returned Valid, so the silent-wrong-value path
+     * stayed open by default. This structural check moves that one rule into the
+     * default run; every other expression-type check stays behind
+     * `--strict-expressions`.
+     *
+     * Severity: `error` — the bare read addresses nothing the trigger produces,
+     * so the value is null or wrong; failing validation is the only way to close
+     * the default path. Scope-local, mirroring `validateGlobalTriggerBindings`.
+     * A global whose `triggerNodeId` is missing or points at a non-trigger is
+     * left to `validateGlobalTriggerBindings` / `validateUnboundInputGlobals`, so
+     * one fact is reported once.
+     *
+     * References come from `collectVarsRefs` (vars-reference-rule.ts), the same
+     * extraction `validateVarsReferences` uses, so this rule inherits its chain
+     * parser (dot form, bracket form and optional chaining all parse to the same
+     * segments), its comment stripping, its skip of the CLI-owned connector
+     * `inputs.detail.configuration` blob, and its walk of `variables.variableUpdates`.
+     * It parts company on one judgement: text that is not code. `collectVarsRefs`
+     * tags each reference with `inProse` and leaves the call to the caller;
+     * this rule drops those, because it reports a VALID id and "$vars.<id>" in
+     * a help string, a prompt or a regex is ordinary text, while a template
+     * interpolation (`${$vars.<id>}`) is code and stays a read.
+     */
+    private validateTriggerScopedBareVarReads;
     /**
      * Entry-point contract integrity for flow inputs (root-cause:
      * skill-flow-calculator).

package/dist/services/node-validators/connector-validator.d.ts

@@ -8,3 +8,11 @@ import type { FlowNodeValidator } from "./types.js";
  * pluggability was introduced.
  */
 export declare const connectorNodeValidator: FlowNodeValidator;
+/**
+ * The `essentialConfiguration` object inside the CLI-owned `=jsonString:`
+ * configuration blob, or `undefined` for a missing, malformed or non-object
+ * blob (`=jsonString:null` parses to `null`). The one parser behind every
+ * read of that blob in this file (and the connector-binding validator's MCP
+ * node identification).
+ */
+export declare function readEssentialConfiguration(detail: Record<string, unknown>): Record<string, unknown> | undefined;

package/dist/services/vars-reference-rule.d.ts

@@ -40,7 +40,14 @@
  *  3. the second segment is an output the producer declares (its instance
  *     `outputs` or its definition's `outputDefinition`), in every reference
  *     form — dot-form `=js:` inputs were left to the schema rule until it
- *     stopped running;
+ *     stopped running — EXCEPT a Decision's `matchedCase`/`matchedCaseId`
+ *     (flow-schema's `SYNTHETIC_GATEWAY_OUTPUT_KEYS`), which the registry
+ *     declares but the packed `inclusiveGateway` never populates, so a read is
+ *     always null at runtime and is flagged even though the name is declared
+ *     (UV-16500). Always an error, `outputs.*.source` included — see
+ *     `decisionUnpopulatedOutputIssue`. Switch shares this gap and is deferred
+ *     to a follow-up gated on the archive scan, not left out for lack of
+ *     evidence;
  *  4. an identifier read on an output the definition types as `array` — or
  *     a connector `output` whose `inputs.detail.inputMetadata.operation` is
  *     `list` (every configured list node carries it; the `definitions[]`
@@ -54,9 +61,11 @@
  *  5. an inline-agent input binding (`agentInputVariables[].binding`) names a
  *     node that runs on EVERY path to the agent — a parallel branch counts, an
  *     exclusive branch does not (`[400300]` is certain on the other arm).
- *     On agent bindings only this check and (4) run: their existence, ancestry
- *     and output-name checks are `validateAgentInputScopeRefs`'s (which also
- *     reads the agent.json schema keys), so one defect is reported once.
+ *     On agent bindings this check, (4) and the Decision `matchedCase*` half of
+ *     (3) run: their existence, ancestry and ordinary output-name checks are
+ *     `validateAgentInputScopeRefs`'s (which also reads the agent.json schema
+ *     keys), so one defect is reported once — but a Decision's declared-yet-
+ *     unpopulated output passes that check, so this rule owns it here too.
  *
  * Severity: a node INPUT that cannot resolve faults the node, so (1)–(5) are
  * errors there (`validateAgentInputScopeRefs`'s no-edge-path finding on an
@@ -70,13 +79,23 @@
  * (`$vars.x?.output` is `$vars.x.output`); an End's
  * `outputs.*.source` and variable updates evaluate leniently (an undefined
  * intermediate yields null — archived debug-graded passes carry such reads),
- * so every finding there is a warning.
+ * so every finding there is a warning — except the synthetic gateway outputs
+ * of (3), which are null on EVERY path rather than merely sometimes absent, so
+ * leniency there returns a wrong answer instead of faulting.
  *
  * JavaScript texts (a Script node's `inputs.script`, `=js:` strings and
  * `jsExpression` objects) are scanned with their `//` and `/* *\/` comments
  * removed, so a commented-out reference left behind by an edit is not a
  * finding. String and template literals are kept: `${$vars.x.y}` is evaluated,
- * and a plain string mentioning `$vars` is rare enough to accept.
+ * and a plain string mentioning `$vars` is rare enough to accept. THIS rule
+ * keeps accepting it — every finding it makes needs a reference that is
+ * already broken (an unknown root, a producer that runs later, an output name
+ * the producer does not declare), and a broken reference sitting in prose is
+ * rare on top of rare; the 9,016-flow archive scan below was graded with that
+ * behavior. The extraction does now tag such references (`ref.inProse`,
+ * see `collectVarsRefs`) for callers whose tolerance is lower —
+ * `validateTriggerScopedBareVarReads` fires on a perfectly valid id, where
+ * "$vars.<id>" in a help string is ordinary prose, so it drops them.
  *
  * Overlap with the expression type checker (`expression-validator.ts`, the
  * canvas's `@uipath/flow-expression-model`): it also reports an unresolved
@@ -144,13 +163,94 @@ export interface VarsRefOptions {
      */
     extraKnownRoots?: Iterable<string>;
 }
+type FlowNode = VarsRefFlow["nodes"][number];
+export interface VarsRef {
+    /** Chain segments after `$vars`, e.g. `["checkTemperature", "output", "matchedCaseId"]`. */
+    segments: string[];
+    /** Verbatim reference text as written (whitespace removed), for messages. */
+    text: string;
+    /**
+     * Indices of the segments read through `?.`. When segment k is undefined
+     * (a missing root, a node that has not run, an undeclared output), the
+     * fault happens at the NEXT read — `undefined.<k+1>` — so the read is
+     * undefined-safe exactly when segment k+1 is optional (`a?.b.c` still
+     * throws at `.c` when `a` is defined and `a.b` is not).
+     */
+    guarded: ReadonlySet<number>;
+    /**
+     * The reference sits in text the runtime never evaluates — quoted prose
+     * (`"mentions $vars.x"`), a regex pattern, or a block comment inside a
+     * `${…}` — so nothing reads it. A template interpolation itself is code,
+     * so `` `${$vars.x}` `` is false. Always false for a non-JavaScript field,
+     * where the whole value is the expression and there is no quoting to read.
+     */
+    inProse: boolean;
+}
+export interface ScannedJsText {
+    /** The source with its top-level comments removed. */
+    text: string;
+    /**
+     * Half-open `[start, end)` spans of `text` the runtime never evaluates as
+     * code: the inside of a `'…'`, `"…"` or backtick literal, a `/…/` regex
+     * pattern, and a block comment kept verbatim inside a `${…}`. A template
+     * literal's interpolations are otherwise NOT in here — they are live code,
+     * so `` `${$vars.x}` `` reads `$vars.x` and `"mentions $vars.x"` does not.
+     * Ranges are ascending and never overlap.
+     */
+    proseRanges: Array<[number, number]>;
+}
 /**
- * Remove `//` and `/* *\/` comments from JavaScript source, keeping string and
- * template literals verbatim (a `//` inside `'https://x'` is not a comment).
- * Regex literals are NOT tracked: a `//` inside one (`split(/\/\//)`) opens a
- * line comment and drops the rest of that line — a missed reference at worst,
- * never a false finding. Output length may differ from the input; only the
- * presence of references matters downstream.
+ * Strip comments and record which parts of the result are not live code.
+ *
+ * A `${…}` body is copied verbatim rather than stripped, which a spec pins —
+ * `` `a ${b // c} d` `` has no newline for its comment to end at, and consuming
+ * to end-of-input would eat the closing brace. Comments there are therefore
+ * TAGGED as prose instead of removed: a block comment by its delimiters, a line
+ * comment up to the newline or the `}` that closes the interpolation, whichever
+ * comes first. Nested string literals and regex patterns inside an interpolation
+ * are tagged too, so `` `${"$vars.x"}` `` is prose and `` `${$vars.x}` `` is a
+ * read. The one cost of stopping at `}`: a brace in such a comment ends the
+ * interpolation early, so code after it up to the closing backtick is tagged
+ * prose — a read there is missed. Rare, and it fails open.
+ */
+export declare function scanJsText(source: string): ScannedJsText;
+/** One authored `$vars` reference, with the node and field it was written in. */
+export interface VarsRefOccurrence {
+    nodeId: string;
+    /** Path inside the node, e.g. `inputs.script`, `outputs.summary.source`, `variableUpdates[0]`. */
+    fieldPath: string;
+    isAgentBinding: boolean;
+    /**
+     * The reference sits inside a larger expression rather than BEING the whole
+     * field value (`=js:$vars.x.output.issues` is not embedded; a Script body
+     * that mentions it is).
+     */
+    embedded: boolean;
+    ref: VarsRef;
+}
+/**
+ * Every `$vars` reference an author wrote on these nodes — the single
+ * extraction every `$vars` rule shares, so none of them re-derives "what counts
+ * as an authored expression".
+ *
+ * It walks the same fields as the rule below (node `inputs`, `outputs` and the
+ * node's entry in `variables.variableUpdates`), skips the CLI-owned connector
+ * `inputs.detail.configuration` blob (a serialized manifest, not an authored
+ * expression), strips `//` and `/* *\/` comments out of JavaScript texts, and
+ * parses each chain with `parseRefs` — so dot form, bracket form
+ * (`$vars['a']['b']`, `$vars["a.b"]`) and optional chaining all come back as
+ * the same `segments` array.
+ *
+ * Quoted text is kept, not dropped, and each reference is tagged with
+ * `ref.inProse` so a caller can decide for itself: a reference in
+ * prose (`"mentions $vars.x"`) is never read at runtime, but one in a template
+ * interpolation (`` `${$vars.x}` ``) is. Callers differ — see
+ * `validateVarsReferences` (keeps prose) and `validateTriggerScopedBareVarReads`
+ * (drops it).
+ *
+ * `updatesByNode` is `variables.variableUpdates` — a map of node id → the
+ * updates that node applies.
  */
-export declare function stripJsComments(source: string): string;
+export declare function collectVarsRefs(nodes: ReadonlyArray<FlowNode>, updatesByNode?: Record<string, unknown>): VarsRefOccurrence[];
 export declare function validateVarsReferences(flow: VarsRefFlow, options?: VarsRefOptions): ValidationIssue[];
+export {};

package/dist/{shared-utils-3cwmvxdc.js → shared-utils-wv356cvj.js}

@@ -6,7 +6,7 @@ import {
 } from "./packager-tool-eypvc2kv.js";
 import {
   readStdin
-} from "./packager-tool-m056vsmy.js";
+} from "./packager-tool-6k8s7pt9.js";
 import"./packager-tool-0v3s8r01.js";
 import"./packager-tool-1yh8g550.js";
 export {