FE-1576: Ground Brunch interviews in the current Petrinaut net

[kostandinang]

🌟 What is the purpose of this PR?

Let Brunch inspect the Petri net already visible in Petrinaut before answering or beginning an interview about the current model. Today typed and completed Voice input share one chat path, but the current Brunch agent does not expose Petrinaut's existing live-net client tool, so it asks users to upload or describe context the browser already has.

This is a read-only current-stack fix. The net snapshot returns as correlated machine evidence, never user speech, and Voice remains on the shared mounted chat submission path. It does not add canvas writes or establish the future FE-1574 transport topology.

🔗 Related links

• FE-1576 (internal)
• H-6800 (internal)
• FE-1574 (internal)
• #9512 — immediate stacked parent

🚫 Blocked by

• #9512 — this PR is stacked on its branch

🔍 What does this change?

• Adds a Flue wrapper for the canonical getLatestNetDefinition browser client tool and mounts it on the current Brunch agent.
• Requires a fresh read before answering requests about this/current/the existing net, including before the first interview question.
• Registers the tool as browser-executed so { title, definition, extensions } returns through the existing client-tool-result machine continuation.
• Extends the real /api/chat integration with the exact “Interview this Petri net. What does it do?” opening, fixture-grounded continuation, and retry/idempotency assertions.
• Adds and corrects the Petrinaut Voice Loom script so the demo preloads Site 1000, grounds the interview before Voice starts, enables transcription before pointing to visible text, and fits under five minutes.

🏗️ Agent notes

Imperative: Let Brunch inspect the live Petrinaut net before answering or beginning an interview about the current model.

Throughline: typed message or completed Voice transcript → shared useChat projection → Brunch requests getLatestNetDefinition → Petrinaut returns { title, definition, extensions } → correlated client-tool-result resumes the same conversation.

Proof: The production-path integration emits one browser-executed live-net call without providerExecuted, returns fixture state as machine evidence, emits fixture-specific text before the first brunch_ask, and retains one visible user admission under retries.

Constraints: Read only on net-referential turns; no snapshot cache; no Voice, OpenAI Realtime, TTS, or transport-metadata context path; no user-evidence fabrication; no canvas writes.

Fog-line: Prompt-guided on-demand reads are proven for the opening turn. A changed second snapshot and hard-reload behavior belong to the #9468-based browser Flue transport proof in FE-1574.

Stop or reorient: Do not port the app-local ChatAgent, Brunch /api/chat, direct Voice sends, or brunch_ask into FE-1574. Port only the canonical client-tool contract, SDCPN policy, and behavior tests.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• does not modify any publishable blocks or libraries, or modifications do not need publishing

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

⚠️ Known issues

• The current implementation uses the temporary app-local Brunch agent and /api/chat route. FE-1574 must reimplement only the portable client-tool behavior on its FE-1563: Establish Brunch elicitation skill boundaries #9468-based conversation route.
• The current integration proves opening-turn grounding; changed-snapshot refresh and hard-reload non-resubmission remain FE-1574 acceptance requirements.

🐾 Next steps

• Port the canonical tool contract into plugin-sdcpn during FE-1574.
• Register it through the generic browser Flue ChatTransport client-tool continuation with stable idempotency keys and canonical history hydration.

🛡 What tests cover this?

• yarn workspace @apps/brunch-agent test:unit — 43 tests
• Focused Petrinaut assistant-panel tests — 70 tests
• yarn workspace @apps/petrinaut-website test:unit src/main/app/voice-interview — 150 tests
• yarn workspace @apps/brunch-agent lint:tsc
• yarn workspace @apps/brunch-agent lint:eslint — 0 errors; 8 pre-existing warnings
• Focused oxfmt, editor diagnostics, and git diff --check

❓ How to test this?

1. Start the local Brunch/Petrinaut pair and preload a non-empty net.
2. Type Interview this Petri net. What does it do? in the Brunch-backed assistant panel.
3. Confirm Brunch inspects the visible net, describes model-specific facts, and asks a relevant first question instead of requesting an upload or description.
4. Start Voice and answer the question; confirm the finalized transcript continues through the same mounted conversation.
5. Reload the current page and confirm no duplicate user turn appears in the current-stack history.

📹 Demo

https://www.loom.com/share/2748986e56f44a3d9fa54c7c72cd7fd9

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hash	Ready	Preview	Sep 3, 2026 4:28pm UTC
petrinaut	Ready	Preview	Sep 3, 2026 4:28pm UTC
petrinaut-docs	Ready	Preview	Sep 3, 2026 4:28pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Sep 3, 2026 4:28pm UTC

[kostandinang]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• FE-1576: Ground Brunch interviews in the current Petrinaut net #9523 👈 (View in Graphite)
• H-6800: Improve Petrinaut Voice turn-taking and answer provenance #9512
• H-6763: Add temporary Brunch ask shim for Voice preview #9507
• H-6763: Submit only completed Voice transcripts as interview answers #9500
• FE-1570: Optimize spoken Brunch responses for Voice mode #9496
• H-6763: Integrate Voice mode into the AI assistant #9467
• H-6763: Migrate voice interviews to GPT-Realtime-2 #9399
• H-6763: Add the voice interview experience #9380
• H-6763: Improve voice preview reliability diagnostics #9378
• H-6763: Speak finalized Brunch responses with OpenAI #9357
• H-6763: Add OpenAI Realtime voice input to Brunch #9356
• H-6763: Add a generic Petrinaut composer submission API #9355
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

PR Summary

Medium Risk
Changes assistant prompting and the client-tool resume contract on the production chat path, though net access stays read-only and is covered by extended integration tests.

Overview
Brunch can now read the live canvas net before describing it or starting an interview, instead of asking users to re-upload or re-describe what Petrinaut already has.

The agent mounts a new browser-executed getLatestNetDefinition Flue tool (canonical name from petrinaut-core) that stops with { awaiting: client } and resumes on the existing client-tool-result path with { title, definition, extensions }. System prompts require that call for any “this/current/existing net” turn—including before the first brunch_ask—and tell the model not to claim the canvas is unavailable while the tool is callable.

/api/chat integration tests now open with Interview this Petri net. What does it do?, assert a non-providerExecuted net tool call, resume with a fixture snapshot, and check model-specific narration appears before the interview question. A new Voice Loom script doc aligns the demo: text kickoff → live-net grounding → then Voice.

^{Reviewed by Cursor Bugbot for commit f4476e6. Bugbot is set up for automated code reviews on this repo. Configure here.}