H-6763: Add a generic Petrinaut composer submission API

[kostandinang]

🌟 What is the purpose of this PR?

Add a provider-neutral API for controls embedded in Petrinaut's AI composer. A host can submit finalized text—voice transcripts are the first consumer—through the same AI SDK conversation and correlated interactive-tool path used by keyboard submissions.

This PR deliberately contains no OpenAI, audio, or Brunch-specific runtime code.

🔗 Related links

• Linear: H-6763 (internal)
• Stack: #9346 → H-6763: Add a generic Petrinaut composer submission API #9355 → #9356 → #9357
• #9297 is historical evidence only and is unchanged.

🚫 Blocked by

• #9345
• #9346

🔍 What does this change?

• Adds renderComposerControl, allowing an application-owned control to render beside the Petrinaut composer.
• Gives that control the effective AI SDK conversation ID, current messages/status, and stable submitText and stop callbacks.
  • The ID is the exact useChat ID, whether supplied by the host or generated by the SDK.
  • Stable callbacks use the latest committed conversation after an ID change rather than targeting the previous chat.
• Routes keyboard and host-submitted text through one submission function and one useChat instance.
  • Supplied user-message IDs remain stable across transport retries.
  • target: "message" explicitly submits a normal message without consuming a pending tool, which supports later correction turns.
• Extends interactive tools with an optional schema-validated fromComposerText mapper.
  • One eligible unresolved tool is completed through its existing correlated tool call.
  • Unknown or unmapped tools fall back to a normal message.
  • Multiple eligible tools fail visibly instead of guessing.
  • Duplicate tool submissions are suppressed.
• Records the ownership boundary in ADR-0009, Brunch steering/strategy records, and the Petrinaut integration specification: Petrinaut owns the generic composer seam; applications own provider integrations; Brunch remains provider-free.
• Updates the Petrinaut user guide/changelog and adds the required npm changeset.

Stack record: direct base 359afceabaac841b8e6d88f877e5daaf92026528; #9345 head 146d7895d41eaf7092571ff36b4b08bba7cc18ed; #9346 head 359afceabaac841b8e6d88f877e5daaf92026528.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• modifies an npm-publishable library and I have added a changeset file(s)

📜 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

The existing AI-assistant guide has no screenshot for this surface, so no screenshot is made stale.

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

The changes in this PR:

• do not affect the execution graph

⚠️ Known issues

• The inherited Brunch docs-index check remains 6/7 because FE-1506: Show captures and completion while a panel elicitation runs #9346 references ADR-0008, which exists only in the parallel prerequisite stack. This PR does not duplicate that ADR.
• This PR exposes an integration seam only; it adds no microphone or speech UI. Those are scoped to H-6763: Add OpenAI Realtime voice input to Brunch #9356 and H-6763: Speak finalized Brunch responses with OpenAI #9357.

🐾 Next steps

• H-6763: Add OpenAI Realtime voice input to Brunch #9356 adds disabled-by-default OpenAI Realtime transcription in the Petrinaut website.
• H-6763: Speak finalized Brunch responses with OpenAI #9357 adds exact canonical OpenAI speech playback.
• Voice PR4 remains blocked on the production authentication, quota, telemetry, recovery, completion, and projection contracts.

🛡 What tests cover this?

ai-assistant-panel.test.tsx, ai-assistant-contents.test.tsx, and the interactive-tool registry tests cover effective/generated conversation identity, callback freshness, shared keyboard/control submission, stable IDs, mapping validation, correlated tool output, ambiguity, duplicate suppression, explicit message targeting, and stop behavior.

Validation run

yarn workspace @hashintel/petrinaut test:unit --run
yarn workspace @hashintel/petrinaut lint:eslint
yarn workspace @hashintel/petrinaut lint:tsc
yarn workspace @hashintel/petrinaut build
yarn workspace @apps/petrinaut-website test:unit
yarn workspace @apps/petrinaut-website lint:eslint
yarn workspace @apps/petrinaut-website lint:tsc
yarn workspace @apps/petrinaut-website build
yarn workspace @hashintel/brunch-agent-transport-aisdk test:unit
yarn workspace @hashintel/brunch-agent-transport-aisdk lint:eslint
yarn workspace @hashintel/brunch-agent-transport-aisdk lint:tsc
yarn workspace @hashintel/brunch-agent-transport-aisdk build
yarn workspace @apps/brunch-agent test:unit
yarn workspace @apps/brunch-agent lint:eslint
yarn workspace @apps/brunch-agent lint:tsc
yarn workspace @apps/brunch-agent build
yarn workspace @local/petrinaut-arch-docs lint:arch-docs
yarn oxfmt --check apps/petrinaut-website apps/brunch-agent libs/@hashintel/petrinaut libs/@hashintel/brunch-agent

Results: 214 Petrinaut tests, 4 website tests, 12 transport tests, and 35 Brunch tests passed. Lint, typecheck, build, formatting, and architecture-doc checks passed. Transport emitted 4 inherited no-await-in-loop warnings and Brunch emitted 12 inherited warnings.

The direct-base no-ElevenLabs audit and git diff --check passed. No package, lockfile, environment, or deployment configuration changed. No provider credential check applies to this PR.

❓ How to test this?

1. Run yarn workspace @hashintel/petrinaut test:unit --run src/ui/views/Editor/panels/ai-assistant-panel.test.tsx.
2. Confirm keyboard and host-control submissions use the same chat ID and preserve a supplied message ID.
3. Confirm one mapped pending tool receives correlated output, ambiguous mappings fail, and target: "message" leaves a pending tool untouched.

📹 Demo

Not applicable: this PR adds a host integration API without a new standalone user experience.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 31, 2026 7:54pm
petrinaut	Ready	Preview	Aug 31, 2026 7:54pm
petrinaut-docs	Ready	Preview	Aug 31, 2026 7:54pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 31, 2026 7:54pm

[kostandinang]

• 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 👈 (View in Graphite)
• main

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

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e15b65f. Configure here.}

[cursor]

Chips answer pending mapped tools

Medium Severity

Review prompt chips now go through submitText with default target: "auto". If a mapped interactive tool is pending, a chip such as Suggest improvements or Explain this model completes that tool instead of sending the review prompt. REVIEW_CHIPS stay visible on a non-empty net after the conversation has started, so this happens as soon as a host registers fromComposerText.

 

^{Reviewed by Cursor Bugbot for commit e15b65f. Configure here.}