Merge origin/main into claude/issue-21922-meta-read-declines-code-datasource-row

Claude-Session: https://claude.ai/code/session_017ErfyP2Rx7XWHJA27QjyUi
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.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 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.

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.
 
 <Callout type="info">
-**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

packages/spec/src/api/plugin-rest-api.handler-status-retirement.test.ts

@@ -70,7 +70,7 @@ const WELL_FORMED = {
 
 const PRESCRIPTION = /`RestApiEndpoint\.handlerStatus`.*was removed.*17/s;
 
-describe('[#13823] RestApiEndpoint.handlerStatus retirement', () => {
+describe('RestApiEndpoint.handlerStatus retirement', () => {
   // All three former values, INCLUDING the documented default: the old
   // docblock's `@default 'implemented'` was prose only — the key never carried
   // a Zod `.default()`, so no built artifact materialised it and there is no
@@ -156,7 +156,7 @@ describe('[#13823] RestApiEndpoint.handlerStatus retirement', () => {
   });
 });
 
-describe('[#13823] api/HandlerStatus + api/RouteCoverage{Entry,Report} def retirement', () => {
+describe('api/HandlerStatus + api/RouteCoverage{Entry,Report} def retirement', () => {
   /** The 6 names the three retired defs exported (3 schema consts + 3 types). */
   const RETIRED_NAMES = [
     'HandlerStatusSchema',
@@ -176,7 +176,7 @@ describe('[#13823] api/HandlerStatus + api/RouteCoverage{Entry,Report} def retir
 
     // ── ABSENCE (every entry, not just ./api) ─────────────────────────────
     for (const name of RETIRED_NAMES) {
-      expect(holdersOf(name), `${name} must have zero holders after #13823`).toEqual([]);
+      expect(holdersOf(name), `${name} must have zero holders after its retirement`).toEqual([]);
     }
 
     // ── SURVIVAL ──────────────────────────────────────────────────────────
@@ -205,7 +205,7 @@ describe('[#13823] api/HandlerStatus + api/RouteCoverage{Entry,Report} def retir
   });
 });
 
-describe('[#13823] ADR-0087 registration', () => {
+describe('handlerStatus retirement — ADR-0087 registration', () => {
   it('declares the tombstoned key and the three removed defs under major 18, with the D3 entry', () => {
     expect(RETIRED_KEYS_BY_MAJOR[18]).toContain('api/RestApiEndpoint:handlerStatus');
     for (const def of ['api/HandlerStatus', 'api/RouteCoverageEntry', 'api/RouteCoverageReport']) {

packages/spec/src/api/plugin-rest-api.schema-refs.test.ts

@@ -53,7 +53,7 @@ function resolvesToZodSchema(name: string): boolean {
   return !!candidate && typeof (candidate as { safeParse?: unknown }).safeParse === 'function';
 }
 
-describe('#3899 — catalog schema references resolve and sit on the right methods', () => {
+describe('catalog schema references resolve and sit on the right methods', () => {
   it('every requestSchema names a Zod schema exported from @objectstack/spec/api', () => {
     for (const ep of allEndpoints()) {
       if (!ep.requestSchema) continue;
@@ -87,7 +87,7 @@ describe('#3899 — catalog schema references resolve and sit on the right metho
     }
   });
 
-  it('at least the routes wired in #3899 still declare their request schemas', () => {
+  it('at least the routes wired to the request-schema gate still declare their request schemas', () => {
     // Anti-erosion floor: the gate above is vacuous if declarations are simply
     // deleted. These five are validated at their mounted routes.
     const declared = new Map(

packages/spec/src/api/plugin-rest-api.test.ts

@@ -541,7 +541,7 @@ describe('plugin-rest-api.zod', () => {
       expect(paths).not.toContain('/preferences');
     });
 
-    it('declares no AI routes — this table cannot vouch for a Cloud/EE surface (#3718)', () => {
+    it('declares no AI routes — this table cannot vouch for a Cloud/EE surface', () => {
       // DEFAULT_AI_ROUTES used to sit here declaring `/nlq`, `/suggest` and
       // `/insights`, and this test asserted its shape — three endpoints no repo
       // has ever mounted, checked for `toHaveLength(3)`. Shape is not
@@ -691,7 +691,7 @@ describe('plugin-rest-api.zod', () => {
 // than a bare unrecognized-key error, and the value survives at the same
 // magnitude. Asserting the message, not just `.toThrow()`: a bare throw stays
 // green when the schema throws for some unrelated reason.
-describe('RestApiEndpoint / RestApiPluginConfig durations carry their unit (#15677)', () => {
+describe('RestApiEndpoint / RestApiPluginConfig durations carry their unit in the key name', () => {
   const endpoint = {
     method: 'GET' as const, path: '/api/v1/discovery',
     handler: 'getDiscovery', category: 'discovery' as const,