Uh oh!
There was an error while loading. Please reload this page.
fix(runtime): fall back Responses relay discovery to /v1 - #3797
Conversation
Astro-Han
left a comment
There was a problem hiding this comment.
I reviewed this head and found no blocking issues.
The relay base normalization now consistently heals bare roots to /v1 and strips trailing /responses at the endpoint, aligning probe, discovery, and send. Scoped only to openai-responses-compatible to avoid breaking built-in providers that serve both paths. Tests lock the five normalization cases.
No P0-P2. Checks on afb7b5d have no hosted report yet — not green.
简体中文
该头未发现阻断。5487df2 to
fb95dc1CompareAstro-Han
left a comment
There was a problem hiding this comment.
Thanks for working on the probe/discovery/send drift. I need to supersede my earlier review on afb7b5d: it missed the existing root-mounted custom-relay configuration described inline.
The single-base direction is sound, but choosing /v1 for every pathless custom relay is a product-contract change rather than a universally safe normalization. I’m leaving this as a P2 COMMENT—not a request for changes—but I would not approve until the intended compatibility behavior is explicit.
Exact head reviewed: fb95dc1a0f5136b5b1501e9123da01972fa31651. Hosted checks are green.
中文对照
需要纠正我在旧 head 上的结论：统一入口的方向正确，但把所有无路径 Relay 自动改成 /v1 会改变已有配置含义。这里定为 P2 Comment，不发 Request Changes，但建议先明确兼容契约再批准。
AI-assisted review: Codex traced the compatibility path and drafted this feedback; the maintainer verified the conclusion and severity.
| return baseUrl; | ||
| } | ||
| const basePath = stripTrailing(url.pathname).replace(/\/responses$/i, ''); | ||
| url.pathname = basePath === '' ? '/v1' : basePath; |
There was a problem hiding this comment.
[P2] Preserve or explicitly migrate the existing root-mounted relay contract
Thanks for centralizing the URL derivation. This line does more than normalize equivalent spellings, though: a pathless custom Responses relay previously meant /responses and /models at the configured root, while it now always means /v1/responses and /v1/models.
Root-mounted custom relays are a valid existing configuration, so this silently breaks them on the normal send/discovery path. Please either preserve root semantics and use a deterministic /v1 fallback, or make /v1 the explicit product contract with migration/UI/documentation and a regression showing the old shape is intentionally unsupported.
Because this changes the meaning of persisted user configuration, a Discussion establishing the contract would also be preferable to treating it as an implementation-only correction.
中文对照
这里不只是统一 URL 写法，而是把已有的“根路径提供 /responses 和 /models”配置重新解释成 /v1。这会直接破坏合法的现有自定义 Relay。建议保留根路径语义并确定性 fallback 到 /v1，或者明确迁移产品契约；这种行为变化最好先通过 Discussion 达成共识。
There was a problem hiding this comment.
Addressed in b8ff53a69 after rebasing onto the latest main.
The bare-root → /v1 rewrite is removed. A root-mounted relay remains authoritative for send, probe, and the first discovery request (/responses and /models). Only a 404 from that pathless root model route triggers one same-origin GET fallback to /v1/models; 401/network/invalid-response failures do not fall back, and POST requests are never replayed. Endpoint-form overrides still reduce to their API base for discovery.
Regression coverage now proves the existing root contract, the 404-only fallback, the authorization boundary, and unchanged DeepSeek root behavior. The PR title/body and verification notes have also been updated.
A root-mounted custom OpenAI Responses relay remains authoritative for send, probe, and discovery. When only its root /models route returns 404, retry discovery once at /v1/models; do not retry authorization failures or POST requests. Endpoint-form overrides still reduce to their API base before discovery, so /v1/responses discovers through /v1/models without changing persisted root semantics. Refs apache#3320 Generated-by: Claude Opus 5 Generated-by: OpenAI Codex (GPT-5.6)
fb95dc1 to
b8ff53aCompare
Summary
A custom OpenAI Responses relay configured with its host root can pass the connection probe at
<root>/responseswhile publishing its model catalog at/v1/models. Discovery previously stopped after<root>/modelsreturned 404, so the connection looked verified but its catalog never refreshed.This revision preserves the configured API base as the primary contract and adds a narrow discovery fallback:
<configured-base>/models./v1/modelsroute once.…/v1/responsesare reduced to their API base before deriving…/v1/models.http://relay.example:3000/responses/models, then/v1/modelsonly after 404https://relay.example/v1/v1/responses/v1/modelshttps://relay.example/v1/responses/v1/responses/v1/modelshttps://relay.example/relay/v1/relay/v1/responses/relay/v1/modelsFixes#3320
Compatibility and review response
This supersedes the earlier root →
/v1normalization and addresses the P2 compatibility review: persisted root-mounted relays continue to use/responsesand/modelsexactly as before. The fallback is provider-scoped toopenai-responses-compatible, same-origin, GET-only, 404-only, and attempted once. Built-in providers such as DeepSeek retain their unversioned root behavior.Regression coverage now locks:
/v1request;/modelsroute is absent falls back once to/v1/modelswhile probe/send stay at/responses;Verification
Passed:
npm --workspace @maka/core run buildnpm --workspace @maka/runtime run buildnode --test dist/__tests__/provider-conformance.test.js dist/__tests__/provider-contract-matrix.test.js dist/__tests__/responses-wire-contract.test.jsinpackages/runtime— 171 passed, 0 failednpx biome checkon the six touched source/test files — cleanThe full
npm --workspace @maka/runtime run test:distrun completed with 3 failures outside this PR's changed paths (3,129 passed, 13 skipped): two existing Responses-reasoning expectations andtool-catalog-derive.test.js, which currently cannot import the unexported@maka/core/tool-catalogsubpath. The changed relay suites are green.AI use
Select exactly one:
Tool(s) and scope: Claude Opus 5 performed the original investigation and implementation. OpenAI Codex (GPT-5.6) traced the compatibility path, replaced the root-rewriting behavior with the 404-only discovery fallback, added the compatibility/error-boundary regressions, rebased the branch, and updated this PR. The author owns the submission.
Checklist
Does this PR entail a change in behavior?