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
hash	Ready	Preview	Sep 1, 2026 10:30am UTC
petrinaut	Ready	Preview	Sep 1, 2026 10:30am UTC
petrinaut-docs	Ready	Preview	Sep 1, 2026 10:30am UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Sep 1, 2026 10:30am UTC

[kostandinang]

• FE-1576: Ground Brunch interviews in the current Petrinaut net #9523
• 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 👈 (View in Graphite)
• main

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

[lunelson]

This is a clean split: Petrinaut gets a host control and one submission path, and provider/audio stay out. Sharing useChat between the keyboard and submitText is the right boundary for the rest of the stack.

One question on the public shape. fromComposerText plus the “exactly one pending mapped tool” rule in ai-assistant-panel.tsx (with target: "message" to opt out) reads like the brunch_ask interview turn, published as a generic Petrinaut contract. That’s fine if you expect other tools to need the same routing. If brunch_ask is the only caller, a narrower host API — complete this pending tool, or send a normal message — might age better than teaching every interactive tool how to parse composer text.

Approving as-is. Flagging it because this is the published seam the later PRs will be stuck with.

[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 feaefa5. Configure here.}

[kostandinang]

@lunelson Intentional: fromComposerText is the generic seam for any interactive tool that can map free text; brunch_ask is the first consumer.