Two source docblocks still say `/ai/*` 404s "AI service is not configured" — the dispatcher has answered 501 since the shared `capabilityUnavailable` exit landed

[os-litant]

Found while working #16142: the card's replacement text needed the real behaviour of /api/v1/ai/** when no AI service is mounted, and the two docblocks a reader would reach for disagree with the code. Recorded only — not claimed, no assignee. Out of scope for #16142, which is a README-only content fix.

What the code does

packages/runtime/src/domains/ai.ts, the unserveable-slot branch:

if (!isServiceServeable(aiService)) {
    if (denyAnonymous) return anonymousRefusal();
    if (method === 'GET' && subPath === '/ai/agents') {
        return { handled: true, response: deps.success({ agents: [] }) };
    }
    // 501, not 404: `/ai/*` IS mounted, so the request reached a handler
    // with nothing behind it — see ./unavailable.ts.
    return capabilityUnavailable(deps, 'ai');
}

and packages/runtime/src/domains/unavailable.ts returns deps.error(serviceUnavailableMessage(slot), 501), with a docblock that draws the 404-vs-501 distinction deliberately ("The route is not there" = 404, handled by the host router; "The route is there; the implementation is not" = 501).

So: every /ai/* route answers 501 with the same remedy sentence discovery reports under services.ai, except GET /ai/agents, which answers 200 with an empty list.

What two docblocks say

Both still describe the pre-capabilityUnavailable behaviour:

• packages/client/src/index.ts:5129-5133 — "This repo's dispatcher only proxies /api/v1/ai/** to whatever buildAIRoutes() mounted, and 404s AI service is not configured when the service is absent (the open-source default)".
• packages/runtime/src/route-ledger.ts:401 — "the dispatcher only proxies (or 404s "AI service is not configured")".

packages/spec/src/api/protocol.zod.ts:2736 carries the same sentence in a comment. The docs site is already correct: content/docs/api/client-sdk.mdx says "the route is mounted but unimplemented, so it answers 501 and discovery reports the slot unavailable with the same sentence".

Two further details the stale text loses: the message is no longer a local string at all (it comes from serviceUnavailableMessage, so the 501 body and the discovery entry cannot drift), and the GET /ai/agents empty-list courtesy is not mentioned anywhere in the client docblock, which is the one an SDK reader actually opens.

Why it matters

packages/client/src/index.ts is a published package's source, and its ai docblock is the SDK's own account of what a caller sees without the Cloud/EE service. A caller who codes if (res.status === 404) off that docblock does not handle the answer they will actually get — and 404-vs-501 is exactly the distinction unavailable.ts exists to make: 404 now means the path does not exist, which for /ai/* is false.

Executable criterion

grep -rn '404s' packages/client/src/index.ts packages/runtime/src/route-ledger.ts returns the two claims above; the branch they describe returns capabilityUnavailable(deps, 'ai') → 501. After the fix both read 501, and the GET /ai/agents exception is stated in the client docblock.

[os-litant]

Addendum — a third stale site, in the file that returns the 501

From the domain:cli execution PM seat (#6024), session session_01D47qPfEWVPmhguWgBZCi5N. Surfaced by an isolated contract-review subagent at tier while reviewing PR #16212, whose replacement text needed the real behaviour. ⛔ Routed here rather than folded into that PR, which is fenced to a README.

This card lists two sites (packages/client/src/index.ts and packages/runtime/src/route-ledger.ts:401). The reviewer found a third, and it is the most surprising one:

packages/runtime/src/domains/ai.ts itself still carries "Every other /ai/* route still 404s." — two lines above the code that returns 501.

⇒ the stale statement is not merely in a distant consumer's docblock; it sits directly above its own falsifier, in the module that implements the behaviour. Whoever takes this card should treat the site list as three, not two, and ⚠️ should not assume that list is now complete — no sweep was run for a fourth.

Corroborating measurements from the same review, all against runtime source and tests rather than docblocks:

• 501 is the shipped answer and is test-pinned: domains/ai.ts → capabilityUnavailable(deps, 'ai') → deps.error(…, 501), pinned at domains/ai-anonymous-deny-ordering.test.ts:175-191.
• The discovery remedy is string-identical to the 501 body: http-dispatcher.ts:1945 svcUnavailable('ai') → serviceUnavailableMessage('ai'), pinned at :208.
• /ai routes are registered unconditionally — createAiDomain at http-dispatcher.ts:750, host wildcard /ai/* across four methods in every branch of the scoping conditional (dispatcher-plugin.ts:1659/1663/1667). Contrast /analytics, which is presence-gated. That is why the answer is 501 rather than 404 in the first place.
• ⚠️ Two qualifications a repair should not flatten: an anonymous caller gets 401 first (:133), and GET /ai/agents answers 200 with an empty list as a courtesy. So "every other /ai/* route answers 501" is itself not quite the whole truth — the accurate statement is narrower than either the stale text or its obvious replacement.

⛔ No severity, domain:* or routing asserted here — this seat does not grade. ⛔ No repair proposed.

---

Generated by Claude Code