From 4e79442153cfd0951da06556cc7b06fe3eb0bed9 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 6 Oct 2026 09:07:26 +0000 Subject: [PATCH 1/2] docs(spec): App.defaultAgent names the agent route as the chat door, read by the console The docblock said the assistant chat endpoint resolves this agent from context.appName. The cloud AI runtime retired that route; the agent route is the one chat door and the console's surface resolver is the reader. actions-as-tools.mdx drops the retired route from its chat-route callout. Claude-Session: https://claude.ai/code/session_01T9u38rswFp5Rw8DswRUReJ Co-authored-by: Claude --- .../21968-spec-default-agent-chat-door.md | 13 +++++++++++++ content/docs/ai/actions-as-tools.mdx | 7 +++---- packages/spec/src/ui/app.zod.ts | 19 +++++++++++-------- 3 files changed, 27 insertions(+), 12 deletions(-) create mode 100644 .changeset/21968-spec-default-agent-chat-door.md diff --git a/.changeset/21968-spec-default-agent-chat-door.md b/.changeset/21968-spec-default-agent-chat-door.md new file mode 100644 index 00000000000..0f4420ba2b3 --- /dev/null +++ b/.changeset/21968-spec-default-agent-chat-door.md @@ -0,0 +1,13 @@ +--- +"@objectstack/spec": patch +--- + +`App.defaultAgent` docblock: the agent route is the one chat door, and the console is what reads the key. + +Clause-②: no + +- The docblock no longer says the assistant chat endpoint (`POST /api/v1/ai/assistant/chat`) resolves this agent from `context.appName`. That route, with `GET /api/v1/ai/assistant` and `GET /api/v1/ai/assistant/skills`, was retired in the cloud AI runtime (objectstack-ai/cloud#2621, objectstack-ai/cloud#2651), and no server route reads `defaultAgent`. +- It now says who does read it. The console's chat dock hands the active app's `defaultAgent` to its one surface-to-agent resolver, which honours only `ask` or `build` (legacy aliases included) and otherwise falls back to the surface default. The resolved agent is then called by name on `POST /api/v1/ai/agents/:agentName/chat`, where the path segment, not this key, selects the agent. +- The ADR-0063 surface-binding paragraph and the rule that only the two platform agents resolve are unchanged, as is the note that the bare `POST /api/v1/ai/chat` resolves no agent. +- The docs page `ai/actions-as-tools` lists the agent route as the only in-product chat route. +- ⛔ No schema, parse, `.describe()`, export, type or accept-set change. The docblock ships in the published `dist` type declarations, which is why this is a patch. diff --git a/content/docs/ai/actions-as-tools.mdx b/content/docs/ai/actions-as-tools.mdx index 714f3da8083..2841110e5cc 100644 --- a/content/docs/ai/actions-as-tools.mdx +++ b/content/docs/ai/actions-as-tools.mdx @@ -271,10 +271,9 @@ action into AI only when its logic is safe to run on behalf of anyone the capability gate admits. -**ObjectOS** — the in-product chat routes -(`/api/v1/ai/assistant/chat`, `/api/v1/ai/agents/:agentName/chat`) resolve the -authenticated principal from `req.user` — both cookie session -(`better-auth.session_token`) and Bearer token are handled — and forward it to +**ObjectOS** — the in-product chat route, `/api/v1/ai/agents/:agentName/chat`, +resolves the authenticated principal from `req.user` — both cookie session +(`better-auth.session_token`) and Bearer token are handled — and forwards it to `aiService.chatWithTools(...)` as `toolExecutionContext: { actor, conversationId, environmentId }`. That threads the same RLS context through the runtime's built-in data tools and its diff --git a/packages/spec/src/ui/app.zod.ts b/packages/spec/src/ui/app.zod.ts index 669509f0703..e6298052bbc 100644 --- a/packages/spec/src/ui/app.zod.ts +++ b/packages/spec/src/ui/app.zod.ts @@ -1655,15 +1655,18 @@ export const AppSchema = lazySchema(() => strictObject( /** * Default agent for this app's ambient chat surface. * - * 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 console's agent surfaces read this key; no server route does. The + * chat dock hands the active app's `defaultAgent` to the console's one + * surface→agent resolver (objectui `surfaceAgent.ts`, called from + * `ChatDock.tsx`), which honours it only when it names `ask` or `build` + * (legacy aliases included) and otherwise falls back to the surface + * default. The agent it resolves is then called by name on the agent route, + * `POST /api/v1/ai/agents/:agentName/chat` — the one chat door, where the + * `:agentName` path segment, not this key, selects the 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. + * The bare `POST /api/v1/ai/chat` route resolves no agent at all, so this + * key does not scope it either. Do not read this key as a guarantee over + * any 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 7f6089bd504e05ec21401abdedb7c280712bf00c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 6 Oct 2026 09:09:37 +0000 Subject: [PATCH 2/2] docs(changeset): state where the App.defaultAgent docblock ships, as measured Claude-Session: https://claude.ai/code/session_01T9u38rswFp5Rw8DswRUReJ Co-authored-by: Claude --- .changeset/21968-spec-default-agent-chat-door.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/21968-spec-default-agent-chat-door.md b/.changeset/21968-spec-default-agent-chat-door.md index 0f4420ba2b3..a835eda35c8 100644 --- a/.changeset/21968-spec-default-agent-chat-door.md +++ b/.changeset/21968-spec-default-agent-chat-door.md @@ -10,4 +10,4 @@ Clause-②: no - It now says who does read it. The console's chat dock hands the active app's `defaultAgent` to its one surface-to-agent resolver, which honours only `ask` or `build` (legacy aliases included) and otherwise falls back to the surface default. The resolved agent is then called by name on `POST /api/v1/ai/agents/:agentName/chat`, where the path segment, not this key, selects the agent. - The ADR-0063 surface-binding paragraph and the rule that only the two platform agents resolve are unchanged, as is the note that the bare `POST /api/v1/ai/chat` resolves no agent. - The docs page `ai/actions-as-tools` lists the agent route as the only in-product chat route. -- ⛔ No schema, parse, `.describe()`, export, type or accept-set change. The docblock ships in the published `dist` type declarations, which is why this is a patch. +- ⛔ No schema, parse, `.describe()`, export, type or accept-set change. The docblock ships in the published package, in the `dist/ui` and `dist/browser` JavaScript bundles and in the shipped `src/ui/app.zod.ts`, which is why this is a patch.