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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
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.jsnew file mode 100644index 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.mdindex 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.jsindex 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.mdindex 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 previousInheritance 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 themanual create-run route. The wrapper owns the complete async handler lifetime,