docs-next typecheck fails on main: braintrust 3.33.0 pins @types/react 18

[EmersonBraun]

What happened?

pnpm --filter @agentskit/docs-next lint (which is gen-ask-context.mjs && tsc --noEmit) exits 2 on main at f9e3ef70:

components/docs/ask-widget.tsx(373,326): error TS2322: Type 'string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | Promise<...>' is not assignable to type 'ReactNode'.
components/showcase/live.tsx(41,20): error TS2345: Argument of type '() => Promise<{ default: ComponentType; }>' is not assignable to parameter of type 'DynamicOptions<{}> | Loader<{}>'.

Both come from two copies of @types/react meeting in one program. The trace spells it out:

Type 'React.Context<any>' is not assignable to type 'import(".../@types+react@18.3.31/node_modules/@types/react/index").Context<any>'
  Type 'ReactElement<unknown, string | JSXElementConstructor<any>>' is not assignable to type 'ReactNode'
    Property 'children' is missing in type 'ReactElement<...>' but required in type 'ReactPortal'

apps/docs-next itself declares and resolves @types/react@19.2.17 correctly. The 18.x copy arrives transitively.

Root cause

braintrust@3.33.0 declares @types/react: 18.3.31 as a direct dependency. pnpm-lock.yaml:

braintrust@3.33.0(@aws-sdk/credential-provider-web-identity@3.972.77)(zod@4.6.5):
  dependencies:
    '@next/env': 14.2.35
    '@types/react': 18.3.31

This is new. #1608 bumped braintrust 3.21.0 → 3.33.0, and 3.21.0 had no @types/react dependency at all — verified by diffing the lockfile at 363d043d (before #1608) against main.

Why CI did not catch it

No workflow runs root pnpm lint, docs:typecheck or docs:build. Lint, Test, Build in ci.yml runs pnpm --filter "./packages/*" lint, which excludes apps/*.

It does block people: .husky/pre-push runs pnpm check:quality-gates && pnpm lint && pnpm build, so any push from a checkout of main fails the hook. HUSKY=0 bypasses it, which is how #1607 was pushed.

A partial fix, measured

Adding one override to pnpm-workspace.yaml:

overrides:
  "@types/react": "19.2.17"

removes the 18.x copy entirely (zero @types/react@18 entries in the regenerated lockfile) and clears both errors above. It is not sufficient on its own — with the types unified, two errors that the mismatch had been masking surface:

components/docs/ask-widget.tsx(156,7): error TS7006: Parameter 'message' implicitly has an 'any' type.
components/docs/ask-widget.tsx(170,7): error TS7006: Parameter 'message' implicitly has an 'any' type.

So the work is: unify @types/react, then give those two handlers explicit parameter types. I reverted both the override and the regenerated lockfile after measuring; nothing from this investigation is committed.

Steps to reproduce

git checkout main            # f9e3ef70 or later
pnpm install --frozen-lockfile
pnpm --filter @agentskit/docs-next lint

Expected behavior

pnpm lint passes on main, and a dependency bump that breaks an app's typecheck fails in CI rather than in a contributor's pre-push hook. Worth considering alongside the fix: add the app typecheck (docs:typecheck, or root pnpm lint) to ci.yml, since the pre-push hook is currently the only thing that runs it and it is bypassable.

Context

Found while moving the @agentskit/doc-bridge pin to 1.10.1 in #1607. It is unrelated to that change — the two failing files are untouched by it, @types/react@18.3.31 was already in main's lockfile, and apps/docs-next's importer block in the lockfile is byte-identical to main's.