[Fix] Brain queries lose expansion and synthesis through the helper gateway

[roomote-roomote]

​Opened on behalf of @daniel-lxs. Follow up by mentioning @roomote-roomote, in the web UI, or in Telegram.

What changed

Brain query expansion and synthesis can now use the bundled native OpenAI client through Roomote's helper gateway. Gateway-mode defaults use openai:roomote/helper so gbrain resolves the OpenAI recipe; the client sends the unchanged wire model roomote/helper.

The existing helper path now accepts non-streaming OpenAI Responses text requests and returns the completed Responses envelope. It preserves instructions, developer/assistant context, JSON-format requirements and output limits. Unsupported image/tool/previous-response inputs are rejected explicitly. Existing chat-completion requests and explicit operator model overrides retain their paths; helper failures return a generic error.

Why this change was made

The unqualified helper default cannot resolve a native provider recipe, silently reducing expansion to the original query. Qualifying the model exposes a second boundary: the pinned OpenAI adapter sends /v1/responses, while Roomote intercepted the helper sentinel only on /v1/chat/completions. That request was forwarded as an invalid provider model. The fix addresses both ends of the same request contract.

Impact

Native Brain expansion can return related queries and synthesis can parse helper output. Direct-provider defaults, explicit GBRAIN_MODEL / R_BRAIN_MODEL choices, embeddings and stored vectors remain unchanged. Text inference continues to call the existing tracked helper role and surface. No new model provider, credential, dependency, data migration or public control is introduced.

How it was tested

• Baseline on develop 35201fbf: actual Docker-pinned gbrain f49ca569232dbc0d8e0783d84606115e3bfe5ab1 makes zero HTTP calls with the unqualified default; qualified native expansion reaches the actual Hono gateway and receives controlled upstream HTTP 400. The new request regression also failed 400 versus 200 before implementation.
• Exact pushed head 6d324762ae9b83a17c4a1e440727178b1cb2953f: actual pinned native client over HTTP to the actual Hono handler parses original-plus-three expansion results and a synthesis answer from Responses envelopes; HTTP 200, two helper calls, zero upstream sentinel forwards. Gateway/provider resolution and the helper inference collaborator are controlled. This proves native protocol/application routing, not live model inference or durable accounting.
• Executed the actual entrypoint for ten boots across five gateway/direct/explicit-override profiles against disposable real Postgres. Default exports match, a second boot retains database data, and database/files are removed afterward. A controlled gbrain CLI sink stops at init; this is bootstrap/configuration/database-lifecycle proof, not a full gbrain service startup claim.
• 30 gateway request/adverse/compatibility tests, two image-configuration checks and 118 unchanged tracked-runtime/usage-contract tests passed. The latter use existing SDK/usage mocks; they are not a new real-accounting proof. API/monorepo fast types, fast lint, Knip, shell syntax, normal pre-push hooks and Mintlify validation/link checks passed. Precommit Judgement passed 12 judgments.
• Local deployment validation passed three script tests and six Compose shapes, then could not adapt Caddy because this sandbox has no Docker daemon. Hosted full CI passed, including deployment artifacts, Test, app image, backup/restore and upgrade checks. Exact-head automated review is clean with zero findings/threads. Worker-image matrix and Mintlify deployment are expected skips. Hosted Judgement is green by policy but explicitly incomplete with zero judgments in its log; precommit's 12 judgments are separate evidence, not full hosted semantic coverage. No hosted post-deployment recovery or live-provider parity is claimed. Browser proof is not applicable; no screenshots/video are embedded.

Checklist

• The PR title follows the repo convention: [Fix], [Feat], [Improve], [Refactor], [Docs], or [Chore] followed by a user-facing description
• This PR is small and scoped to one change
• pnpm lint and pnpm check-types pass locally — normal fast repository gates passed; full formatting-inclusive commands were not run
• I added tests or included a clear manual validation note above
• I removed secrets, tokens, private keys, and customer data from code, logs, and screenshots
• If this change should appear in the changelog, I ran pnpm changeset

Related PRs

• #3442 — Preserve explicit PR draft intent: independent reliability work from the same shift; neither PR depends on the other.
• #3445 — Bound controller shutdown while launches stall: independent controller reliability fix from the same shift.

[roomote-community]

No code issues found. See task

Reviewed all five changed files, the pinned gbrain provider-resolution and expansion contracts, helper request/response translation, authentication, and operator override paths. Current-head tests, lint, type checks, Knip, deployment-artifact validation, docs validation, and the app image build passed. No approval submitted.

_{Reviewed 6d32476}

[daniel-lxs]

Verified the pinned native Brain client through the actual HTTP gateway for expansion and synthesis with controlled inference, plus authentication and unsupported-input/error handling. Focused compatibility checks, deployment configuration validation and current CI pass at this head.