FE-1437: Move brunch-agent into hashintel/hash with its history

[lunelson]

🌟 What is the purpose of this PR?

Brunch — the elicitation-agent harness developed to date in the standalone brunch-lite repository — moves into hashintel/hash, which becomes its sole writable home. This branch imports the standalone history, renames the package family to @hashintel/brunch-agent* under libs/@hashintel/brunch-agent/ (application at apps/brunch-agent), and adopts the HASH toolchain (Yarn/Turbo, Biome, Vitest) in place of Bun.

🔗 Related links

• FE-1437: Move brunch-agent into hashintel/hash with its history (internal)
• Execution plan: libs/@hashintel/brunch-agent/docs/planning/_shared/hash-monorepo-import-plan.md
• Decision record: libs/@hashintel/brunch-agent/docs/adr/0004-in-petrinaut-staging-and-the-monorepo-import.md
• Standalone repository frozen at 43a0022918861846344b96a32cb94f92e2ee96ae (read-only reference)

🚫 Blocked by

Nothing — the import gates (FE-1434/FE-1435 spike verdicts, standalone review stack) all landed before the cutover.

🔍 What does this change?

Adds the Brunch package family as five new workspaces: the substrate-independent harness (@hashintel/brunch-agent), the Flue binding, the AI SDK transport, the Gherkin target plugin, and the application at apps/brunch-agent. It also lands the first slice of the Petrinaut website integration — a generic interactive-tool extension point in @hashintel/petrinaut (with changeset) and an app-level Brunch ask tool in apps/petrinaut-website — which the trimmed FE-1440 builds on. Boundary rules survive as enforced tests: plugins depend only on the harness, transports never on a binding, @hashintel/petrinaut stays Brunch-agnostic, and applications are the only Brunch–Petrinaut meeting point.

🏗️ Agent notes

Final physical shape

hash/
├── apps/
│   └── brunch-agent/                 # runnable composition application
│
└── libs/@hashintel/brunch-agent/     # Brunch context root; not a workspace
    ├── CONTEXT.md
    ├── AGENTS.md / CLAUDE.md
    ├── docs/
    ├── scripts/
    └── packages/
        ├── core/
        ├── binding-flue/
        ├── transport-aisdk/
        └── plugin-gherkin/

The existing root workspace globs, apps/** and libs/**, already discover these nested packages. No new root workspace rule or context-root package.json was needed.

Package identities and dependency graph

The standalone names became HASH-native:

• @brunch/core → @hashintel/brunch-agent
• @brunch/binding-flue → @hashintel/brunch-agent-binding-flue
• @brunch/transport-aisdk → @hashintel/brunch-agent-transport-aisdk
• @brunch/plugin-gherkin → @hashintel/brunch-agent-plugin-gherkin
• @brunch/dev → @apps/brunch-agent

plugin-gherkin ───────┐
                      ▼
                 brunch-agent core
                    ▲       ▲
                    │       │
          binding-flue   transport-aisdk
              │               │
              ▼               ▼
         Flue substrate     AI SDK wire

apps/brunch-agent → composes all four

The planned invariants remain:

• Core knows no Flue or other substrate.
• Plugins depend only on core.
• The binding joins core to Flue, but never owns plugins.
• The transport joins core to the AI SDK wire format.
• Only the app composes the full system.
• apps/brunch-agent remains independent of Petrinaut packages; apps/petrinaut-website is the Brunch/Petrinaut meeting point.

All packages are private, use 0.0.0-private, carry the HASH license, use workspace:* internally, and have versions reconciled through the HASH lockfile and constraints.

Toolchain rewiring

The largest incidental adaptation was removing the standalone Bun toolchain.

• Bun workspace discovery → root Yarn workspaces.
• Bun task orchestration → Turbo package tasks.
• bun:test → Vitest.
• Bun.spawn → a shared Node child-process helper.
• Bun.file → Node fs APIs.
• Bun.spawnSync → Node child_process.
• Bun script execution → Node's type-stripping mode where scripts remain TypeScript.
• Standalone root TypeScript/Bun/Oxfmt/CI configuration was retired.

Each workspace now exposes HASH-shaped tasks:

• build
• lint:eslint
• lint:tsc
• test:unit
• app-specific dev tasks where appropriate

TypeScript configuration was split per package, using strict bundler resolution, tsgo, explicit Node/DOM types, and explicit .ts extensions where Node executes source directly.

Build reshaping

Each library became an independently built Vite ESM library:

• Core emits main, client-tools, storage, and testing entry points.
• Binding, plugin, and transport each emit standalone ESM output.
• The transport additionally emits its browser-safe client-tools entry point.
• External dependencies remain external rather than being bundled.
• Sourcemaps are emitted.
• The app separately builds its server and browser client.

An attempted declaration-bundling setup exposed incompatibilities with Brunch's Valibot value/type same-name pattern. The resulting private-package contract is therefore deliberately:

types   → src/*.ts
runtime → dist/*.js

That preserved type ownership without forcing changes to the domain schemas merely to satisfy a declaration bundler.

The app also gained a dedicated vitest.config.ts: loading its full Vite/Flue configuration under Vitest caused the Flue build plugin to execute in an incompatible SSR context.

Test ownership reshaping

The old repository-level tests were distributed according to what they govern:

• Package unit tests live with each package.
• Family-wide architecture tests live under core/test/architecture/.
• App integration, runtime, and built-artifact tests live under apps/brunch-agent/test/.
• The transport's pure wire tests remain with the transport.
• Its server composition test moved to the app because it exercises transport + binding + host.
• Transport fixtures moved alongside the transport.
• Baseline-runner and documentation-governance tests became architecture tests.

The architecture scanner was rewritten for the new topology. It discovers:

• all children of libs/@hashintel/brunch-agent/packages/;
• the separate apps/brunch-agent workspace.

Its dependency proof also changed. Bun's isolated installation allowed tests to assert that forbidden packages physically could not resolve. HASH's Yarn linker may hoist dependencies, so that would have become a false proof. The replacement checks:

• declared runtime dependencies;
• actual authored imports;
• package-role naming;
• source coverage;
• absence of forbidden substrate imports.

Documentation and agent-context reshaping

The nested directory became a true domain context:

• CONTEXT.md remains the canonical Brunch glossary.
• AGENTS.md and CLAUDE.md were rewritten for operation inside HASH.
• App-level guidance points back to the context root.
• docs/spec.md remains authoritative.
• Completed elicitation planning moved under docs/history/.
• Living planning, ADRs, references, baseline material, and scripts stayed locally available.
• The documentation index and boundary-test paths were updated.
• Git workflow guidance was adapted to HASH.
• Baseline and Linear scripts are exposed through package commands despite the context root having no manifest.

Import-process adaptations

The Git history was imported in four deliberately separate stages:

1. Import the frozen standalone ancestry.
2. Format files while they still occupied the import path.
3. Mechanically move them to final HASH paths.
4. Rewrite manifests, runtime APIs, tests, and lockfile for HASH.

That unusual order was discovered during execution:

• Moving manifests too early caused Yarn's pre-commit validation to reject an intermediate workspace state.
• Moving unformatted files caused HASH formatting hooks to obscure the mechanical rename.
• Formatting before moving preserved a legible path-only move commit.

Post-review follow-ups

The review follow-ups:

• add package-level turbo.json files so build outputs and dependency builds are explicit;
• restore scoped ignores for .flue/, .data-wipe-me/, and documentation drafts;
• repair relative links after documentation relocation;
• add a test preventing future internal documentation-link rot;
• keep core-owned boundary gates intact where migration tests proved them;
• retain source-type/runtime-dist exports rather than adopting declaration bundling that breaks merged schema/type exports.

Petrinaut integration

The imported transport is wired into the Petrinaut demo without coupling the Brunch application to Petrinaut:

• Petrinaut accepts host-owned interactive tools through an opaque registry capability.
• The website supplies a typed inline brunch_ask widget.
• Brunch and Petrinaut share the canonical ask input/output contracts.
• AI SDK continuation accepts the real browser tool-brunch_ask payload shape.
• Assistant message identity is preserved across ask/answer continuation.
• The end-to-end chat path was verified in local development without duplicate questions or continuation errors.
• The unrelated Brunch Actual-mode fixture remains outside this integration.

Type ownership

The host-tool extension preserves source-of-truth typing:

• Brunch ask input/output types are inferred from canonical Valibot schemas.
• The website imports those contracts and parsers instead of recreating them with local Zod schemas.
• Petrinaut's built-in tool submissions retain their concrete types.
• Auto-layout decisions are distinct from persisted results.
• Heterogeneous host tools erase their private generics only inside an opaque capability.
• Remaining unknown values are confined to genuine runtime boundaries such as raw AI SDK dynamic-tool data.

Post-import branch state

• Import gates re-verified on the final tip: workspace constraints pass with no Brunch exemptions; build, lint, typecheck, and 173 unit tests green across the five workspaces (core 114, binding-flue 16, transport-aisdk 11, plugin-gherkin 2, app 30); boundary tests including a mutation proof (an injected illegal import fails exactly the intended gate); hermetic faux-provider runtime POST test; no Bun residue; git log --follow/blame continuity into pre-import commits.
• The imported subtree is byte-identical to the frozen brunch-lite tree at the import commit.
• Post-import commits on the branch: docs/tense settlement after the cutover, the FE-1440 trim record, the PR-template guidance integration, the Petrinaut changeset, and the switch of the Brunch stacking convention from gh stack to Graphite (matching HASH's repo-wide Graphite use).
• Known environmental issue unrelated to this branch: tsx cannot create its IPC pipe on the dev machine (listen EPERM), breaking @hashintel/ds-components#codegen locally; no branch commit touches ds-components.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

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

@hashintel/petrinaut gains the interactive-tool extension point (patch changeset); the imported Brunch packages are all private.

📜 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

Brunch context, architecture, planning, and operating documentation were updated for HASH, and the Petrinaut AI assistant guide documents host-specific interactive widgets.

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

The changes in this PR:

• affected the execution graph, and the turbo.json files have been updated to reflect this

⚠️ Known issues

• Squash-merging (the repo convention) collapses the imported history into one commit on main; the full standalone history remains preserved on this branch and in the PR record, and the standalone repository stays available read-only at the frozen SHA.
• Screenshots showing the Petrinaut AI chat flow should be refreshed to include the inline Brunch question widget.

🐾 Next steps

• FE-1440 (trimmed): the elicitor mode in apps/petrinaut-website — mode switch, browser identifier bootstrap, remote transport swap
• FE-1438 client-tool round-trip and FE-1439 private durable sessions, now advanced in this repository
• FE-1441: deployment of the remote Brunch server
• Add or refresh the Petrinaut chat-flow screenshot

🛡 What tests cover this?

• Brunch package unit, architecture, runtime-entrypoint, and built-artifact tests.
• Transport ask/reply continuation tests using the browser payload shape.
• Petrinaut interactive registry and auto-layout widget tests.
• TypeScript and ESLint checks across the Brunch packages, Petrinaut library, and Petrinaut website.
• Vite builds for the application and affected libraries.
• Petrinaut architecture-document lint.

The final focused verification completed 23/23 Turbo tasks. Brunch core completed 114/114 tests.

❓ How to test this?

1. Run:

   turbo run build test:unit lint:tsc lint:eslint \
     --filter '@hashintel/brunch-agent' \
     --filter '@hashintel/brunch-agent-transport-aisdk' \
     --filter '@hashintel/petrinaut' \
     --filter '@apps/petrinaut-website'

2. Run:

   yarn workspace @local/petrinaut-arch-docs lint:arch-docs

3. Start the Brunch agent and Petrinaut website development servers.

4. Open the Petrinaut local-storage demo and send an elicitation prompt.

5. Confirm the inline Brunch question renders, accepts an answer, and continues the same assistant message without errors or duplication.

📹 Demo

The local browser flow has been manually verified. A refreshed screenshot should be added before merge.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 24, 2026 4:27pm
hashdotdesign-tokens	Ready	Preview	Aug 24, 2026 4:27pm
petrinaut	Ready	Preview	Aug 24, 2026 4:27pm
petrinaut-docs	Ready	Preview	Aug 24, 2026 4:27pm

[lunelson]

• FE-1507: Move the repertoire into core behind a guarded prompts subpath #9349 : 2 dependent PRs (#9355 , #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 👈 (View in Graphite)
• main

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 60.10%. Comparing base (357589c) to head (27fa5c5).
⚠️ Report is 10 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9274      +/-   ##
==========================================
+ Coverage   59.71%   60.10%   +0.39%     
==========================================
  Files        1423     1314     -109     
  Lines      138862   132988    -5874     
  Branches     6572     6190     -382     
==========================================
- Hits        82915    79933    -2982     
+ Misses      54881    52034    -2847     
+ Partials     1066     1021      -45     

Flag	Coverage Δ
apps.hash-ai-worker-py	?
apps.hash-ai-worker-ts	1.99% <ø> (ø)
apps.hash-api	14.66% <ø> (ø)
backend-integration-tests	?
blockprotocol.type-system	40.84% <ø> (ø)
deer	?
error-stack	?
local.claude-hooks	0.00% <ø> (ø)
local.harpc-client	51.49% <ø> (ø)
local.hash-backend-utils	3.27% <ø> (ø)
local.hash-graph-sdk	10.02% <ø> (ø)
local.hash-isomorphic-utils	12.22% <ø> (ø)
local.hash-subgraph	?
rust.antsi	2.36% <ø> (ø)
rust.deer	?
rust.error-stack	90.81% <ø> (ø)
rust.harpc-codec	84.70% <ø> (ø)
rust.harpc-net	96.23% <ø> (+0.01%)	⬆️
rust.harpc-tower	67.03% <ø> (ø)
rust.harpc-types	0.00% <ø> (ø)
rust.harpc-wire-protocol	92.23% <ø> (ø)
rust.hash-codec	72.76% <ø> (ø)
rust.hash-graph-api	11.00% <ø> (+3.50%)	⬆️
rust.hash-graph-authentication	91.78% <ø> (+7.81%)	⬆️
rust.hash-graph-authorization	62.59% <ø> (ø)
rust.hash-graph-embeddings	91.88% <ø> (ø)
rust.hash-graph-postgres-store	29.33% <ø> (ø)
rust.hash-graph-store	46.78% <ø> (ø)
rust.hash-graph-temporal-versioning	47.95% <ø> (ø)
rust.hash-graph-types	0.00% <ø> (ø)
rust.hash-graph-validation	84.71% <ø> (ø)
rust.hashql-ast	89.63% <ø> (ø)
rust.hashql-compiletest	28.39% <ø> (ø)
rust.hashql-core	78.98% <ø> (ø)
rust.hashql-diagnostics	72.51% <ø> (ø)
rust.hashql-eval	79.82% <ø> (ø)
rust.hashql-hir	89.09% <ø> (ø)
rust.hashql-mir	87.92% <ø> (ø)
rust.hashql-syntax-jexpr	94.04% <ø> (ø)
rust.sarif	?
sarif	?
tests.hash-backend-integration	?
unit-tests	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[codspeed-hq]

Merging this PR will not alter performance

✅ 98 untouched benchmarks

---

_{Comparing ln/fe-1437-hash-monorepo-import (27fa5c5) with main (ab96828)¹}

Footnotes

1. No successful run was found on main (e95df9a) during the generation of this report, so ab96828 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[cursor]

PR Summary

High Risk
Adds a remote elicitation server, conversation storage, and a Petrinaut chat transport with CORS, request validation, and tool-reply admission. It also changes CI prune behavior for Brunch jobs.

Overview
Imports the Brunch elicitation harness into HASH as the native home: a context root under libs/@hashintel/brunch-agent, four private packages (core, Flue binding, AI SDK transport, Gherkin plugin), and apps/brunch-agent as the remote Flue server. The family is Yarn/Turbo/Vitest-shaped, with architecture tests that keep plugins on the harness only, transports binding-free, and Brunch–Petrinaut composition in applications.

The app mounts a Gherkin elicitor, durable SQLite conversations, a local capture store, and /api/chat that streams Petrinaut-compatible AI SDK events—including brunch_ask suspend/return with history-backed admission. petrinaut:dev proxies the real panel without editing HASH’s tracked website.

Petrinaut gains a host-owned interactive-tool registry (patch changeset). The local-storage demo registers an inline brunch_ask widget using the transport’s client-tool contracts. CI prune now copies Brunch context files and the app only when @hashintel/brunch-agent is the requested scope, so sibling jobs do not pull that fixture.

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