From 777832df5686f3ac7eb967908236e919cd77b0fa Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 21 Aug 2026 05:51:55 +0000 Subject: [PATCH 1/2] docs(spec,client): stop documenting bare POST /ai/chat as agent-resolved Both docblocks asserted runtime behaviour that does not exist: the bare chat route loads no agent and never reads context.appName. The default-agent resolution chain is driven by the assistant chat route. Refs #10510 --- packages/client/src/index.ts | 11 +++++++---- packages/spec/src/ui/app.zod.ts | 12 +++++++++--- 2 files changed, 16 insertions(+), 7 deletions(-) diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts index cb07bae1c1..238244f548 100644 --- a/packages/client/src/index.ts +++ b/packages/client/src/index.ts @@ -4240,10 +4240,13 @@ export class ObjectStackClient { /** * Named agents. * - * `/ai/chat` talks to the environment's default agent; these talk to one - * you name. Both routes have been mounted since long before this namespace - * existed — `objectui` hand-built their URLs in five places because the SDK - * offered nothing to call (#3718). + * These are the only SDK methods that reach an agent. `POST /ai/chat` + * (`ai.chat` / `ai.chatStream`) is a raw chat plane that resolves no agent + * at all — it loads none, so nothing about that call is scoped by an + * agent's skills. Read it as agent-less, never as "the environment's + * default agent". Both routes have been mounted since long before this + * namespace existed — `objectui` hand-built their URLs in five places + * because the SDK offered nothing to call (#3718). */ agents: { /** diff --git a/packages/spec/src/ui/app.zod.ts b/packages/spec/src/ui/app.zod.ts index 022c6fa007..38fb366ca9 100644 --- a/packages/spec/src/ui/app.zod.ts +++ b/packages/spec/src/ui/app.zod.ts @@ -1500,9 +1500,15 @@ export const AppSchema = lazySchema(() => strictObject( /** * Default agent for this app's ambient chat surface. * - * 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. + * When set, the assistant chat endpoint (`POST /api/v1/ai/assistant/chat`) + * resolves this agent for a call carrying `context.appName`, without the + * user having to pick from a list — that route is what drives the + * resolution chain (explicit agent > `defaultAgent` of the named app > + * first active agent). + * + * The bare `POST /api/v1/ai/chat` route is NOT part of that chain: it + * resolves no agent and never reads `context.appName`, so this key does not + * scope it. Do not read this key as a guarantee over that endpoint. * * ADR-0063 §1/§2 — this is a SURFACE-BINDING knob, not a custom-agent * slot: the resolvable values are the two platform agents (`ask` for a From 954e1430266679fbf819be0ec559a5dfa0abbc09 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 21 Aug 2026 06:18:16 +0000 Subject: [PATCH 2/2] chore(changeset): patch note for the ai/chat doc correction Refs #10510 --- .changeset/ai-chat-not-agent-resolved.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 .changeset/ai-chat-not-agent-resolved.md diff --git a/.changeset/ai-chat-not-agent-resolved.md b/.changeset/ai-chat-not-agent-resolved.md new file mode 100644 index 0000000000..f27a2ced9d --- /dev/null +++ b/.changeset/ai-chat-not-agent-resolved.md @@ -0,0 +1,20 @@ +--- +"@objectstack/spec": patch +"@objectstack/client": patch +--- + +Stop documenting bare `POST /api/v1/ai/chat` as agent-resolved (#10510). Two +shipped docblocks described a resolution step the route does not perform: +`client.ai.agents` claimed `/ai/chat` "talks to the environment's default +agent", and `App.defaultAgent` claimed that endpoint auto-resolves the app's +agent from `context.appName`. The bare route loads no agent and never reads +`context.appName`; the default-agent chain (explicit > `defaultAgent` of the +named app > first active) is driven by the assistant chat endpoint, +`POST /api/v1/ai/assistant/chat`, and `client.ai.agents.chat()` is the only SDK +method that reaches an agent at all. + +Both sites read as a security-relevant scoping guarantee — an agent-resolved +endpoint would have its tool offer scoped by that agent's skills (ADR-0063 +§1/§5) — so a reader auditing "which endpoints are surface-scoped?" from these +declarations got the wrong answer at both. Documentation text only: no schema +key, no parse behaviour and no runtime path changes.