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 27, 2026 12:41pm
petrinaut	Ready	Preview	Aug 27, 2026 12:41pm
petrinaut-docs	Ready	Preview	Aug 27, 2026 12:41pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 27, 2026 12:41pm

[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

• 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)
• FE-1507: Move the repertoire into core behind a guarded prompts subpath #9349 : 1 other dependent PR (#9381 )
• FE-1431: Build the plugin authoring surface (cycle two) #9348
• FE-1505: Time each interviewer turn by purpose #9347
• FE-1506: Show captures and completion while a panel elicitation runs #9346
• FE-1504: Run the process-model elicitor from the Petrinaut panel on one owned document #9345
• FE-1431: Build the plugin authoring surface #9337
• FE-1406: Audit the harness-teaching lineage and propose the fixed-key plugin contract (ADR-0007) #9327
• FE-1497: Build the controller read path and the SDCPN plugin package #9325
• FE-1404: Run condition 3 as the walking skeleton #9322
• FE-1403: Assemble and test the CPS interview guidance #9321
• FE-1402: Define and rehearse the elicitation completion contract #9320
• FE-1407: Catalogue elicitor failures that published measures miss #9319
• FE-1480: Project and realize a CPS model as a Petrinaut SDCPN #9313
• FE-1495: Prevent Brunch TypeScript contracts from drifting #9312
• FE-1494: Keep Brunch strategy and control records coherent #9311
• FE-1437: Move brunch-agent into hashintel/hash with its history #9274
• main

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

[cursor]

PR Summary

Medium Risk
Changes central AI assistant submission and pending interactive-tool correlation; mistakes could mis-route user text or break ask flows, though behavior is heavily unit-tested.

Overview
Adds a provider-neutral seam so embedders can render a control beside the Petrinaut AI composer and submit finalized text through the same useChat conversation as keyboard input—intended for voice transcripts in follow-up PRs, with no OpenAI or audio runtime in this change.

@hashintel/petrinaut gains optional conversationId, renderComposerControl, and a context with stable submitText / stop, messages, and status. One submitText path handles chips, Enter, and host input (trim, busy checks, stable message IDs). Interactive tools may opt into schema-validated fromComposerText so a single pending mapped tool completes via correlated tool output; ambiguous mappings error, unmapped tools become normal messages, and target: "message" forces a separate user message for corrections. The composer form only submits from the send button so untyped host buttons do not post the draft.

Docs and governance record the boundary in ADR-0009, S-012, the Petrinaut integration attach contract (fourth seam: composer submission), steering/index updates, user guide, changeset, and changelog.

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

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