Two places document bare `POST /api/v1/ai/chat` as agent-resolved — it resolves no agent at all

[baozhoutao]

Found while verifying cloud#1487 (bare /ai/chat offered the full ToolRegistry). Two shipped declarations claim the bare chat endpoint resolves an agent. It does not — the route has no agent identity, which is precisely why AIService fell back to the whole tool registry for it.

Site 1 — packages/client/src/index.ts:4243 (client.ai.agents JSDoc):

/ai/chat talks to the environment's default agent; these talk to one you name.

The cloud route (packages/service-ai/src/routes/ai-routes.ts, POST /api/v1/ai/chat) loads no agent, consults no AgentRuntime, and binds no skills. client.ai.chat() reaches a raw, agent-less chat plane; client.ai.agents.chat() is the only SDK method that reaches an agent.

Site 2 — packages/spec/src/ui/app.zod.ts:1502-1504 (App.defaultAgent JSDoc):

When set, the ambient chat endpoint (POST /api/v1/ai/chat with context.appName) auto-resolves to this agent without the user having to pick from a list.

The bare route never reads context.appName. The app.defaultAgent resolution chain lives in AgentRuntime.resolveDefaultAgent (cloud packages/service-ai/src/agent-runtime.ts:519-540) and is driven by the assistant routes (assistant-routes.ts:171-179, "explicit > defaultAgent(app) > first active") — i.e. POST /api/v1/ai/assistant/chat, not POST /api/v1/ai/chat.

Why this is worth fixing rather than shrugging at. Both sites read as a security-relevant guarantee: if the bare endpoint were agent-resolved, its tool offer would be scoped by that agent's skills (ADR-0063 §1/§5, the property cloud#1480/PR #1485 restored). It is not, and the gap between the two claims and the implementation is what made the bare route the third door onto that leak. A reader auditing "which endpoints are surface-scoped?" from these declarations gets the wrong answer at both sites.

Two possible resolutions — this needs a decision, not just an edit:

• Correct the docs. Site 1 names the agent routes as the agent-bearing surface; site 2 names the ambient/assistant endpoint as the one that reads context.appName. Cheapest, and truthful today.
• Make the implementation match. Route the bare endpoint through the same default-agent chain the assistant route uses. That is a behaviour change for every bare-chat caller and belongs in the cloud repo; it would also supersede the capability gate cloud#1487 just landed.

Cross-refs: cloud#1487 (the fix that closed the tool leak on this route), cloud#1480 / cloud PR #1485 (the agent-scope fix these declarations describe), cloud#1015 (the sibling inert-permissions finding).

Filed unassigned by the cloud#1487 dev seat; recorded rather than fixed because it is out of that card's scope and lands in this repo.

[os-zhuang]

Triage: pm:queue, type Bug, routed domain:spec as a cross-domain single-PR exception (triage-designated per the exception path). Rationale: of the two sites, the schema JSDoc (packages/spec/src/ui/app.zod.ts App.defaultAgent) is spec-lane text by standing rule (everything touching packages/spec goes to the spec seat), and the second site (packages/client/src/index.ts JSDoc) is a one-sentence rider on the same fact — not worth a second card. Claim comment must declare the full file surface (both files, JSDoc-only).

Resolution direction, by standing rules rather than a fresh ruling: correct the docs — both sentences assert runtime behaviour that does not exist, and a doc claiming a security-relevant scoping guarantee that isn't enforced is exactly the declared≠enforced class this repo removes. The alternative ("make the bare endpoint agent-resolved") is a behaviour change for every bare-chat caller, lands in the cloud repo, and would supersede cloud#1487's just-landed gate — that is a Feature with no measured pull; if anyone wants it, it needs its own decision card, not this one. Text-only fix ⇒ no acceptance-face change ⇒ Clause-②: no expected.

Size/model suggestion: S (two JSDoc corrections), spec text tier.

---

Generated by Claude Code

[os-elon]

Claim: PM loop round 1
Session: session_01B4h3medzvhB9rpfoja9jcw
Branch: claude/issue-10510-ai-chat-doc-claims
Worktree: objectstack-issue-10510
Domain: domain:spec (cross-domain single-PR exception, triage-designated in the routing comment)
File surface: packages/spec/src/ui/app.zod.ts (App.defaultAgent JSDoc) + packages/client/src/index.ts (client.ai.agents JSDoc) — JSDoc text only, plus .changeset/ if the regenerated references artifacts require one (stop on breach; explain in the report)
Container & model: S text-tier, mode:subagent, model: opus (doc precision on a security-relevant claim — above sonnet floor, no Clause-② mandate); dispatch-gates run at claim time reports no path-derived mandate
Clause-②: no
Serial constraints cleared: targeted cross-domain in-flight check run against domain:cli (owner of packages/client): #10453 (cli contract tests), #10317 (create-objectstack templates), #10255 (federation route gate), #10244 (route-ledger/authz docs), #10340 (/meta org scope) — none touch packages/client/src/index.ts; zero spec-lane cards in flight; batch-mates #10485/#10492 file-disjoint. H17 trigger-file index: no hit.

---

Generated by Claude Code