fix(uipath-maestro-flow): correct inline-agent canonical shape (MST-9263)

[tmatup]

Summary

• Investigation report (docs/investigations/maestro-flow-python-script-gap.md) tracing why an AI agent reached for python3 <<'EOF' heredocs while authoring a .flow for an inline-agent demo.
• New "Edit Tooling" subsection in editing-operations-json.md blessing python3 / jq heredocs as the sanctioned mechanic for structural Direct-JSON mutations (since the CLI has no node update command — see MST-9303).
• New "Repair Recipes" section in inline-agent/impl.md covering the two scenarios that don't have a CLI shortcut today: replacing a definitions[] entry, and resolving the [REQUIRED_FIELD] systemPrompt validator error.
• Corrected canonical shape in inline-agent/impl.md: UUID at inputs.source (canonical post-flow-core-0.2.50), with model.source documented as a legacy fallback. Drops the verbose model block from the JSON example since BPMN type / serviceType / version / context all come from the definition.

Background

MST-9263. Updated diagnosis: https://uipath.atlassian.net/browse/MST-9263?focusedCommentId=3886871

Commits (in order)

• 49bc27fb — initial investigation report and root-cause writeup.
• 9aa783bb — first attempt at skill fix; based on an incomplete diagnosis that prescribed inserting placeholder strings into inputs.systemPrompt / inputs.userPrompt. Actively harmful — the storage bridge in flow-workbench's packages/services/src/agent-storage/agent-fields.ts round-trips between the node and agent.json.messages[], so placeholders would have overwritten real prompts on the next save.
• 2625e1ab — reverted the harmful guidance and prescribed model.source as canonical. Wrong direction; model.source is the LEGACY shape.
• d6a3034c — corrects the canonical/legacy framing per reviewer feedback. JSON example now uses inputs.source (canonical post-flow-core-0.2.50). Drops the verbose model block from the example. Notes prose, "Add the node via CLI", Debug-table, Repair Recipe, and "What NOT to Do" all flipped to teach inputs.source as canonical and model.source as legacy fallback. The node add CLI quirk (still writes model.source today) is now flagged with a pointer to MST-9308.

Kept the full commit history rather than squashing so the audit trail of corrections is preserved.

Test plan

• All → cross-references in the modified files resolve to existing anchors (verified with grep -n)
• No orphaned references after removing the harmful "Insert validator placeholders" recipe
• JSON example in inline-agent/impl.md matches the canonical shape (UUID at inputs.source, no model block on instance) — confirmed against canvas behavior at flow-workbench serialization/uipath-extension.ts:417-420
• Run hooks/validate-skill-descriptions.sh if the description field changed (it didn't — only body content)

Out of scope

The CLI fix (read both source keys + enrich validator error) lives on inline-agent-source-key-MST-9263 in ~/root/cli (UiPath/cli#1513). The flow-workbench docstring + regression tests live on the same branch in ~/root/flow-workbench (UiPath/flow-workbench#1339). Skill-side: this PR. Five strategic follow-ups filed under epic MST-8796 (MST-9303 / 9304 / 9306 / 9307 / 9308).

[github-actions]

Claude finished @tmatup's task in 3m 14s —— View job

---

PR Review: fix(uipath-maestro-flow): correct inline-agent canonical shape (MST-9263)

• Gather review criteria and project conventions
• Read full diff and existing PR conversation
• Read each changed file in full context
• Verify relative links resolve
• Check for cross-skill references, secrets, and CODEOWNERS
• Post review findings

---

Summary

Adds an investigation report tracing why an agent reached for python3 heredocs while authoring a .flow, then fixes the root causes: a new "Edit Tooling" section in editing-operations-json.md blessing python3/jq as sanctioned mechanics for structural JSON mutations, and corrected canonical shape + repair recipes in inline-agent/impl.md (UUID at inputs.source, not model.source).

Change-by-Change Review

1. .gitignore — .worktrees/ entry

Severity: OK

Single-line addition ignoring .worktrees/ for local investigation worktrees. Clean.

2. docs/investigations/maestro-flow-python-script-gap.md (new file, 138 lines)

Severity: Low

Thorough investigation report with clear evidence tables, categorized Python script usage, and actionable diagnosis. Well-structured. Two minor observations:

• Line 12: Reference to editing-operations-cli.md:158 uses a line-number pointer. Line numbers are fragile across future edits. The reference from impl.md:200 does the same thing. These will silently go stale if the CLI doc is reorganized. Since this is an investigation report (not agent-facing skill content), this is cosmetic — but worth noting.
• Lines 24, 87, 93, 120: References to uipath-agents references ("Agent crossed into uipath-agents references"). This is an investigation report under docs/, not under skills/, so the cross-skill-reference rule does not apply. OK.

3. skills/uipath-maestro-flow/references/author/references/editing-operations-json.md — Edit Tooling section

Severity: Low

Good addition. The four-mechanic table (lines 45–50) is clear and prescriptive. The canonical heredoc recipe (lines 57–68) is copy-paste ready with <FILE>, <NODE_TYPE>, <FIELD>, <VALUE> placeholders in the correct <UPPER_SNAKE_CASE> style. The jq examples (lines 77–79) are concise.

One observation:

• Line 43 (editing-operations-json.md:43): "see editing-operations-cli.md line 158" — line-number pointer to another file. If editing-operations-cli.md is reorganized, this goes stale. Consider linking to the section heading anchor instead (e.g., editing-operations-cli.md#update-node-inputs-expression-script-body-label-etc). Severity: Low.

4. skills/uipath-maestro-flow/references/author/references/plugins/inline-agent/impl.md — canonical shape + repair recipes

Severity: Medium (one item), rest OK

This is the most substantial change. The corrections are well-grounded (canonical inputs.source post-flow-core-0.2.50, model.source as legacy fallback, storage bridge round-trip explanation). Specific observations:

• Line 76 (impl.md:76): Dense paragraph explaining --source, model.source legacy shape, node-service.ts:535-545, inputs.source canonical, MST-9308 tracking. This is accurate and important, but it's a lot of context packed into one paragraph following a code block. An agent reading this sequentially after the CLI command will parse it, but it's borderline. The cross-reference to internal source (node-service.ts:535-545) is useful context for reviewers but not actionable for an agent — agents can't open flow-workbench source. Severity: Low — the information is correct and the agent doesn't need to act on the source reference.

• Line 192 (impl.md:192, Debug table row): The [REQUIRED_FIELD] systemPrompt row is very long — a single table cell spanning ~400 characters. This is the most critical fix in the PR (the root cause from the investigation) and it reads correctly, but the density may cause an agent to miss the key instruction ("Do not insert placeholder strings"). The bolded Do not helps, but consider whether this deserves its own subsection rather than being buried in a table cell. That said, the Repair Recipes section below (line 223) covers the same scenario with a dedicated heading and step-by-step instructions, which mitigates this. Severity: Low.

• Line 200 (impl.md:200): "see editing-operations-cli.md line 158" — same line-number fragility noted above. Severity: Low.

• Lines 198–275 (Repair Recipes section): Well-structured with two concrete recipes. The "Replace a definition entry" recipe (lines 206–219) is copy-paste ready. The "Resolve [REQUIRED_FIELD]" recipe (lines 223–275) has a clear 3-step diagnostic flow with code blocks for each check. The migration recipe (lines 255–269) for moving from model.source to inputs.source is a nice touch.

• Medium concern — Reference Pointer Discipline (impl.md:200 vs editing-operations-json.md:52-68): The Repair Recipes section references the canonical heredoc pattern from editing-operations-json.md#edit-tooling (correct), but then each recipe includes its own complete python3 heredoc block. The editing-operations-json.md Edit Tooling section also has a generic heredoc recipe. These are not duplicates in the strict sense — the generic recipe shows the pattern, while the impl.md recipes are specialized instantiations with inline-agent-specific logic (matching on uipath.agent.autonomous, popping model.source, etc.). This is acceptable — the recipes are domain-specific enough to justify their own blocks. But if the canonical heredoc shape changes (e.g., indent=2 → something else), five code blocks across two files need updating. Severity: Medium.

What's Missing

• No new test tasks. This PR substantially changes the inline-agent authoring guidance (new canonical source key, new repair recipes, new edit tooling section). No new or updated test tasks in tests/tasks/uipath-maestro-flow/ cover the updated behavior (e.g., a task that exercises inline-agent creation with inputs.source and validates the repair recipe flow). Existing tests may still pass, but the new guidance paths are untested. Severity: Medium.

Area Ratings

Area	Status	Notes
Frontmatter	OK	No frontmatter changes in this PR
E2E Tests	Issue	No test tasks for updated inline-agent guidance (Medium)
Skill Body	OK	SKILL.md not changed
References & Assets	Issue	Line-number pointers fragile (Low); moderate heredoc recipe duplication across files (Medium)
Repo Hygiene	OK	CODEOWNERS already covers path; no secrets; .gitignore addition clean; investigation doc in docs/ is fine

Issues for Manual Review

• Domain accuracy of the inputs.source vs model.source framing. The PR claims inputs.source is canonical post-flow-core-0.2.50 and model.source is legacy. This is sourced from canvas behavior at serialization/uipath-extension.ts:417-420 and node-service.ts:535-545. An automated reviewer cannot verify these source references — a domain expert should confirm the canonical/legacy framing is correct for the current product state.
• Validator hydration behavior. The Debug table and Repair Recipe assert that flow validate hydrates inputs.systemPrompt/inputs.userPrompt from agent.json.messages[] when the source UUID is correctly set. The investigation report says the opposite happened in the observed session (validator rejected with REQUIRED_FIELD). The PR's explanation is that hydration short-circuits when the source key is missing or agent.json has empty content — a domain expert should confirm this hydration contract is accurately described.
• Storage bridge round-trip claim. Line 192 and line 275 warn that inserting placeholders into inputs.systemPrompt/userPrompt will corrupt agent.json via the storage bridge. This is the key anti-pattern fix from the investigation. The claim is sourced from agent-fields.ts — domain expert should verify.

Conclusion

The PR is well-researched and the corrections to the canonical inline-agent shape are clearly grounded in the investigation. The Edit Tooling section in editing-operations-json.md fills a real gap. The repair recipes in impl.md are prescriptive and copy-paste ready.

Two actionable items:

1. Medium: Consider adding a smoke or integration test task that exercises inline-agent node creation with the updated inputs.source canonical shape — the new guidance paths are significant enough to warrant coverage.
2. Medium: The heredoc recipe pattern appears in 5 code blocks across 2 files. If the canonical shape changes, all need updating. The cross-reference from impl.md to editing-operations-json.md#edit-tooling partially mitigates this, but the specialized recipes don't inherit from the generic one — they're standalone copies.

The Low-severity line-number pointer fragility (line 158) is a minor nit — anchor links would be more durable but aren't blocking.

Overall: the PR improves the skill materially. The domain-accuracy questions in "Issues for Manual Review" should be confirmed by a domain expert before merge.

[tmatup]

Review Response

Triaged the bot review (#issuecomment-4361587553). Fixes pushed in 81a58a4; remaining items kept with reasoning below.

1. Line-number pointer to editing-operations-cli.md:158 — docs/investigations/maestro-flow-python-script-gap.md:12, editing-operations-json.md:43, inline-agent/impl.md:200

Fixed in 81a58a4. All three sites now link to the section anchor #update-node-inputs-expression-script-body-label-etc instead of a line number, so the references survive future reorganization of editing-operations-cli.md.

2. Dense paragraph after node add block — inline-agent/impl.md:76

Fixed in 81a58a4. Dropped the internal node-service.ts:535-545 citation and MST-9308 ticket reference (neither is actionable for an agent reading this file). Kept the canonical-vs-legacy framing and made the recommended write location bold.

3. Long [REQUIRED_FIELD] systemPrompt table cell — inline-agent/impl.md:192

Keeping current implementation — the table row is the index entry; the dedicated Resolve a [REQUIRED_FIELD] systemPrompt is required validator error recipe at impl.md:223 is the deep dive. The two are deliberately layered: a Cause/Fix table for fast lookup, plus a structured 3-step subsection for agents that need the procedure. Promoting the table row out of the table would break the Debug table's uniform shape.

4. Heredoc recipe duplicated across 5 code blocks in 2 files

Keeping current implementation — the editing-operations-json.md block is the generic template; the four inline-agent/impl.md blocks are domain-specialized instantiations (matching on uipath.agent.autonomous, popping model.source, splicing definitions[]). They are structurally similar but semantically distinct: the agent copy-pastes the specialized recipe and substitutes one placeholder, instead of fetching the generic recipe and figuring out the inline-agent-specific guards. For agent-facing recipe content, copy-paste readiness outranks DRY. If the canonical heredoc shape ever changes, the migration cost is updating five small blocks — acceptable given the recipes are stable.

5. No new test tasks for updated inline-agent guidance

Keeping current implementation — existing coverage at tests/tasks/uipath-agents/inline_in_flow/inline_in_flow.yaml exercises the inline-agent-in-flow lifecycle end-to-end (uip agent init --inline-in-flow, uip solution project add, uip agent validate --inline-in-flow). This PR does not change product behavior — it corrects documentation about the canonical inputs.source write location and adds repair recipes for failure modes the existing test does not exercise. New repair-recipe tests would require fixtures that intentionally produce the failure conditions (missing source key, empty agent.json.messages[]); that scope belongs to a follow-up rather than this corrective PR.

6. Domain-accuracy questions — inputs.source vs model.source framing, validator hydration behavior, storage bridge round-trip claim

Keeping current implementation — these claims are sourced from the investigation that produced this PR (docs/investigations/maestro-flow-python-script-gap.md). The investigation observed the validator behavior directly (REQUIRED_FIELD on missing source key) and traced the dual-key shape from canvas serialization vs. CLI node add. The framing is consistent with the linked PRs MST-9263 / MST-9308.

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

[tmatup]

Review Response (round 2)

Triaged 7 inline comments from @rockymadden and @cotovanu-cristian. Fixes pushed in 16e80359; remaining items kept with reasoning below.

1. Investigation file should be removed pre-merge — docs/investigations/maestro-flow-python-script-gap.md (flagged by both reviewers)

Fixed in 16e80359. Removed the file. The investigation was ephemeral diagnosis context that produced this PR; it doesn't belong on main.

2. inputs.source vs model.source framing — inline-agent/impl.md:76, 103, 133, 192, 227, 279, 282

Fixed in 16e80359. After re-reading the workbench manifest reference @cotovanu-cristian linked (uipath-agent-autonomous/v1.0.0.ts:227-228 declares model: { source: true }), my "canonical post-flow-core-0.2.50" framing was forward-looking, not present-state. Reframed across all six sites:

• flow validate accepts both inputs.source and model.source.
• Skill convention writes inputs.source (matching what planning.md and shared/file-format.md already document).
• The CLI and the current canvas write model.source per the workbench manifest.
• The unification is a planned follow-up.

The recommendation for direct-JSON authoring stays at inputs.source to preserve the skill convention. Open to flipping it to model.source if @cotovanu-cristian would rather the skill match the runtime exactly today.

3. Version-specific framing in agent prompt — inline-agent/impl.md

Fixed in 16e80359. Dropped "canonical post-flow-core-0.2.50" from all six sites; replaced with neutral "skill convention" wording. Also dropped the residual MST-9308 Jira reference in What NOT to Do, consistent with the earlier round-1 cleanup.

4. agent.json.projectId ambiguous notation — inline-agent/impl.md:21, 133, 195

Fixed in 16e80359. Reworded to "the projectId field inside agent.json" everywhere the bare-dotted notation could be read as a path expression. Other JSON-path-style references in the file (agent.json.messages[], etc.) keep brackets/subscripts that make them unambiguous.

5. ## Edit Tooling section in editing-operations-json.md — does it contradict Write/Edit guidance? (@rockymadden)

Keeping current implementation — but happy to sync. SKILL.md only declares Bash, Read, Write, Edit, Glob, Grep as the allowed tool surface — there's no prescriptive rule against python3 heredocs, and editing-operations-json.md is the canonical place to prescribe mechanic-by-operation. The new section addresses a fourth operation class (structural mutation of nested fields) where Write is lossy on large flows and Edit's exact-match constraint breaks on whitespace drift in nested JSON. The intent is additive, not a replacement.

If you'd rather the table be narrower — e.g., drop the Edit / Write rows so it only blesses the heredoc + jq patterns — that's a small follow-up. Let me know which framing you prefer.

---

Nits (none outstanding). Investigation file removed; canonical/legacy framing reconciled with workbench reality; agent.json notation disambiguated; version-specific framing dropped.

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

[tmatup]

Review Response (round 3)

Triaged @andreibalas-uipath's inline comment on inline-agent/impl.md:21. Fix pushed in a92481a.

1. CLI now writes inputs.source and drops the model block — inline-agent/impl.md:21, plus all sites that referenced the dual-key divergence

Fixed in a92481a. UiPath/cli#1364 (merged 2026-05-05) makes --source write the projectId UUID to inputs.source and drop the model block entirely on inline-agent instances, matching Studio Web's persisted form. The pre-#1364 dual-key framing across six sites in impl.md (CLI section, JSON Structure intro, Notes bullets, Debug row, Repair Recipe step 1, What NOT to Do bullets) was describing a divergence that no longer exists. Reframed:

• inputs.source is the single canonical write site (CLI, Studio Web, direct-JSON authoring).
• model.source is documented only as a legacy fallback for older .flow files — validator still hydrates from there, no new authoring writes it.
• "No model block on the instance" is unconditional (was: "no full model block; CLI writes minimal { source }").
• Repair Recipe step 1 points first at uip maestro flow node add ... --source <UUID>; the legacy model.source → inputs.source migration recipe is retained for old flows.

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com