Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

docs: fix PATCH→PUT for cos config and providers; guard endpoint methods in docs (#11853)

[._.]/ Adam Eivy759c8e11ced9
diff --git a/docs/doc-endpoint-methods.test.js b/docs/doc-endpoint-methods.test.js
new file mode 100644
index 0000000000..9f4f76e663
--- /dev/null
+++ b/docs/doc-endpoint-methods.test.js
@@ -0,0 +1,123 @@
+/**
+ * Method guard for `METHOD /api/...` mentions outside docs/API.md.
+ *
+ * `api-doc.test.js` guards API.md's tables, but feature docs and instruction
+ * files name endpoints in prose too, and nothing checked those. Two of them
+ * told callers to `PATCH /api/cos/config` and `PATCH /api/providers/:id`, which
+ * only accept PUT — a script following the doc got a 404.
+ *
+ * Only single-method mentions are checked. Slash shorthand (`GET/PUT /api/x`)
+ * and brace/glob placeholders (`/api/{id}`, `/api/x/*`) are not parseable as
+ * one operation, so they are skipped rather than guessed at. A mention that
+ * deliberately records a removed or proposed endpoint goes in
+ * `DELIBERATE_NON_ROUTES` with its reason.
+ */
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { describe, expect, it } from 'vitest';
+import { buildApiRouteCatalog } from '../server/lib/apiRouteGraph.js';
+
+const DOCS_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(DOCS_DIR, '..');
+
+const mdIn = (dir) => readdirSync(join(REPO_ROOT, dir))
+ .filter((name) => name.endsWith('.md'))
+ .map((name) => `${dir}/${name}`);
+
+const DOC_FILES = [
+ ...mdIn('docs').filter((file) => file !== 'docs/API.md'),
+ ...mdIn('docs/features'),
+ 'AGENTS.md',
+ 'server/AGENTS.md',
+ 'client/src/AGENTS.md',
+ 'client/src/components/dashboard/AGENTS.md',
+ 'server/lib/aiToolkit/AGENTS.md',
+ 'server/lib/README.md',
+ 'client/src/lib/README.md',
+ 'client/src/hooks/README.md',
+ 'client/src/utils/README.md',
+ 'client/src/services/README.md',
+].filter((file) => existsSync(join(REPO_ROOT, file)));
+
+/** Records that name an endpoint which does not (or does not yet) exist, on purpose. */
+const DELIBERATE_NON_ROUTES = [
+ { file: 'docs/features/eidoverse.md', method: 'GET', path: '/api/eidoverse/world/contributions', reason: 'recorded as a removed endpoint' },
+ { file: 'docs/features/openclaw-operator-chat.md', method: 'POST', path: '/api/openclaw/sessions', reason: 'proposed but not built' },
+ { file: 'docs/features/openclaw-operator-chat.md', method: 'GET', path: '/api/openclaw/jobs', reason: 'proposed but not built' },
+ { file: 'docs/features/openclaw-operator-chat.md', method: 'GET', path: '/api/openclaw/subagents', reason: 'proposed but not built' },
+ { file: 'docs/features/openclaw-operator-chat.md', method: 'POST', path: '/api/openclaw/context/compose', reason: 'proposed but not built' },
+];
+
+const MENTION = /(?<![\w/])(GET|POST|PUT|PATCH|DELETE)(\s*\/\s*(?:GET|POST|PUT|PATCH|DELETE))*\s+`?(\/api\/[^\s`<>]+)/g;
+
+/** Same positional param comparison as api-doc.test.js: renaming a param is not observable. */
+const normalizePath = (path) => path
+ .replace(/[?#].*$/, '')
+ .replace(/:[A-Za-z0-9_]+/g, ':param')
+ .replace(/\/+$/, '') || '/';
+
+const PLACEHOLDER = /[*{}[\]]/;
+
+export const findMentions = (file, text) => {
+ const mentions = [];
+ text.split('\n').forEach((line, i) => {
+ for (const match of line.matchAll(MENTION)) {
+ const path = match[3].replace(/[).,;:\]]+$/, '');
+ if (match[2] || PLACEHOLDER.test(path)) continue;
+ mentions.push({ file, line: i + 1, method: match[1], path });
+ }
+ });
+ return mentions;
+};
+
+const CATALOG = buildApiRouteCatalog({ repoRoot: REPO_ROOT });
+const live = new Set(CATALOG.routes.map(({ method, path }) => `${method} ${normalizePath(path)}`));
+const isRoutable = ({ method, path }) => live.has(`${method} ${normalizePath(path)}`);
+
+const mentions = DOC_FILES.flatMap((file) => findMentions(file, readFileSync(join(REPO_ROOT, file), 'utf8')));
+const isAllowed = (m) => DELIBERATE_NON_ROUTES.some((a) => a.file === m.file && a.method === m.method && a.path === m.path);
+
+describe('endpoint mentions outside API.md name a route the server mounts', () => {
+ it('parses a meaningful number of mentions', () => {
+ // A regex that silently matches nothing would pass every assertion below.
+ expect(mentions.length).toBeGreaterThan(50);
+ expect(CATALOG.routes.length).toBeGreaterThan(500);
+ });
+
+ it('names no method/path pair that no router declares', () => {
+ const drift = mentions
+ .filter((m) => !isRoutable(m) && !isAllowed(m))
+ .map((m) => `${m.file}:${m.line} ${m.method} ${m.path}`);
+ expect(drift, [
+ 'These docs name a method/path no router declares. Fix the mention, or — if the doc deliberately',
+ 'records a removed/proposed endpoint — add it to DELIBERATE_NON_ROUTES with a reason.',
+ 'The live inventory is GET /api/api-docs/catalog.json (or buildApiRouteCatalog()).',
+ ].join('\n')).toEqual([]);
+ });
+
+ it('keeps every allowlist entry honest', () => {
+ const stale = DELIBERATE_NON_ROUTES.flatMap((a) => {
+ if (!a.reason) return [`${a.file} ${a.method} ${a.path}: missing reason`];
+ if (isRoutable(a)) return [`${a.file} ${a.method} ${a.path}: now routable — drop the entry`];
+ if (!mentions.some((m) => isAllowed(m) && m.file === a.file && m.method === a.method && m.path === a.path)) {
+ return [`${a.file} ${a.method} ${a.path}: mention no longer present — drop the entry`];
+ }
+ return [];
+ });
+ expect(stale).toEqual([]);
+ });
+
+ it('skips slash shorthand and brace/glob placeholders', () => {
+ const text = 'x `GET/PUT/DELETE /api/foo` y `GET /api/foo/{id}` z `POST /api/foo/*` `PATCH /api/foo/bar`';
+ expect(findMentions('f.md', text)).toEqual([{ file: 'f.md', line: 1, method: 'PATCH', path: '/api/foo/bar' }]);
+ });
+
+ it('reports a wrong verb with file:line', () => {
+ const line = 'writes through `PATCH /api/cos/config` only';
+ const [m] = findMentions('docs/features/chief-of-staff.md', `a\n${line}`);
+ expect(m).toMatchObject({ file: 'docs/features/chief-of-staff.md', line: 2, method: 'PATCH', path: '/api/cos/config' });
+ expect(isRoutable(m)).toBe(false);
+ expect(isRoutable({ method: 'PUT', path: '/api/cos/config' })).toBe(true);
+ });
+});
diff --git a/docs/features/chief-of-staff.md b/docs/features/chief-of-staff.md
index 61f81bb40b..6866c84b39 100644
--- a/docs/features/chief-of-staff.md
+++ b/docs/features/chief-of-staff.md
@@ -236,7 +236,7 @@ Nothing picks a tier automatically — not the description, priority, context si
### Temporary thinking sessions in the Mind UI
-Saved alternates are managed in **Mind → Models** (`/cos/mind?panel=models`). Adding, editing, previewing, or removing a preset writes only `persistentMindThinkingPresets` through `PATCH /api/cos/config` — it never starts a turn, never resumes a paused mind, never infers, and never downloads a model. A list PATCH replaces the whole array, because a merge cannot express "remove this one entry" and would resurrect a deleted preset.
+Saved alternates are managed in **Mind → Models** (`/cos/mind?panel=models`). Adding, editing, previewing, or removing a preset writes only `persistentMindThinkingPresets` through `PUT /api/cos/config` — it never starts a turn, never resumes a paused mind, never infers, and never downloads a model. Sending the list replaces the whole array (PUT merges top-level keys only), because a merge cannot express "remove this one entry" and would resurrect a deleted preset.
The composer's **Send with another model** picker arms one preset for the **next single message**, and nothing else:
diff --git a/scripts/ci-test-plan.js b/scripts/ci-test-plan.js
index 152dd7dc3a..3747f97ee6 100644
--- a/scripts/ci-test-plan.js
+++ b/scripts/ci-test-plan.js
@@ -276,6 +276,7 @@ export const ALWAYS_RUN_TESTS = [
// otherwise merge green.
'docs/api-doc.test.js',
'docs/auth-public-paths-doc.test.js',
+ 'docs/doc-endpoint-methods.test.js',
'docs/docs-index.test.js',
'docs/deps-doc.test.js',
'docs/features/product-surfaces.test.js',
diff --git a/server/lib/aiToolkit/AGENTS.md b/server/lib/aiToolkit/AGENTS.md
index ab17c57a38..5ba12a1b8f 100644
--- a/server/lib/aiToolkit/AGENTS.md
+++ b/server/lib/aiToolkit/AGENTS.md
@@ -22,7 +22,7 @@ The AI provider/runner/prompt toolkit is vendored in-tree here. (It was previous
Inheritance mirrors `withGatewayApiKey`: a gateway-backed wrapper with no policy of its own takes the sibling gateway record's, resolved on read into `modelAccessEffective` / `modelAccessSource` — two derived field names, not the persisted `modelAccess`, because that one IS in `providerSchema` and a client echoing a GET back on a PUT would pin the inherited value forever. Composition order against `withGatewayApiKey` is load-bearing (that helper attaches the key NON-enumerably, so a spread after it drops the credential). A write response carries the resolution forward from the read the route already performed (`withResolvedModelAccess`) rather than re-reading — several suites drive those routes with a service double whose `getProviderById` answers a different fixture. Glob matching is a hand-rolled iterative matcher, not a translated RegExp: the patterns are user input (`*a*a*a*b` backtracks exponentially), and a translation would have to re-inline the escape `server/lib/textUtils.test.js` forbids — which this directory cannot import its way out of. Contract and field list: `docs/MODEL_ACCESS.md`.
-**Provider-service extension point.** `createProviderService` / `createAIToolkit` accept `onProvidersSaved(data)`, invoked after every SUCCESSFUL `providers.json` write with the data that landed. PortOS injects it in `server/services/bootstrap.js` to keep its machine-local provider connection graph (`server/services/providerGraph.js`, #6367) reconciled with a file that a legacy `PATCH /api/providers/:id`, a model refresh, a migration or a downgraded release may also write. The hook is deliberately non-fatal: the write already landed and the cache already reflects it, and callers include boot warmups and schedulers with no `next(err)` to bubble to, so a throwing hook is logged and swallowed. Pair it with `applyProviderPatches(patches)`, which applies partial updates to SEVERAL named records in ONE write and — unlike `updateProvider` — performs no sibling fan-out, because a projection must touch exactly the routes it named and no conventional neighbour.
+**Provider-service extension point.** `createProviderService` / `createAIToolkit` accept `onProvidersSaved(data)`, invoked after every SUCCESSFUL `providers.json` write with the data that landed. PortOS injects it in `server/services/bootstrap.js` to keep its machine-local provider connection graph (`server/services/providerGraph.js`, #6367) reconciled with a file that a direct `PUT /api/providers/:id`, a model refresh, a migration or a downgraded release may also write. The hook is deliberately non-fatal: the write already landed and the cache already reflects it, and callers include boot warmups and schedulers with no `next(err)` to bubble to, so a throwing hook is logged and swallowed. Pair it with `applyProviderPatches(patches)`, which applies partial updates to SEVERAL named records in ONE write and — unlike `updateProvider` — performs no sibling fan-out, because a projection must touch exactly the routes it named and no conventional neighbour.
**Host run admission.** `createAIToolkit` accepts `withRunAdmission(handler)` for the
manual create-run route. The wrapper owns the complete async handler lifetime,