Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
fix(doctor): read /health with credentials where the gateway gates it (#5088)
t0saki9b0ce3dea5d8
diff --git a/examples/claude-code-memory-plugin/scripts/shared/doctor-core.mjs b/examples/claude-code-memory-plugin/scripts/shared/doctor-core.mjsindex a24da5b29..c15a97ead 100644--- a/examples/claude-code-memory-plugin/scripts/shared/doctor-core.mjs+++ b/examples/claude-code-memory-plugin/scripts/shared/doctor-core.mjs@@ -504,6 +504,7 @@ export function serverErrorMessage(probe) {* Run the standard probe ladder against an OpenViking server.** health GET /health without credentials — reachability, version, auth_mode+ * (401/403 where a gateway authenticates ahead of OpenViking)* healthAuth GET /health with credentials — identity echo (account/user/role)* systemStatus GET /api/v1/system/status — first authenticated call the hooks make; real 401/403* fsLs GET /api/v1/fs/ls?uri=viking://~/memories — tenant-data authorization + resolved user space@@ -538,13 +539,28 @@ export async function probeOpenViking(conn, { timeoutMs = 5000, mcp = true } = {return out;}+/**+ * The /health answer the rest of the report should read. A gateway that+ * authenticates ahead of OpenViking (Cloud behind the Volcengine gateway)+ * answers the credential-less probe with 401/403 before the request reaches+ * the server, so version, auth_mode and identity all come from the+ * authenticated probe instead.+ */+export function effectiveHealthProbe(probes) {+ const health = probes?.health;+ const authed = probes?.healthAuth;+ if (health && !health.error && (health.status === 401 || health.status === 403)+ && authed?.ok && isObject(authed.json)) return authed;+ return health;+}+/*** Turn probe results into findings. `keyInfo` is describeApiKey(conn.apiKey).* Returns { authMode, version, identity } for callers that want to cross-check.*/export function assessProbes(report, probes, conn, keyInfo) {const summary = { authMode: "", version: "", identity: null, reachable: false, authOk: false };- const health = probes.health;+ let health = probes.health;if (!health) return summary;if (health.error) {@@ -553,6 +569,24 @@ export function assessProbes(report, probes, conn, keyInfo) {return summary;}summary.reachable = true;+ if (health.status === 401 || health.status === 403) {+ // The url is fine: something in front of OpenViking demands credentials on+ // /health itself. Read it with the key and carry on down the ladder.+ const authed = probes.healthAuth;+ if (authed?.ok && isObject(authed.json)) {+ report.info(`/health is authenticated at this deployment — without a key it answers ${health.status}, so the report reads it with the api key`);+ health = authed;+ } else if (!conn.apiKey && !conn.account && !conn.user) {+ report.fail(`GET /health → ${health.status} and no credentials are configured`, serverErrorMessage(health),+ "this deployment authenticates /health itself (OpenViking Cloud does); set api_key in ~/.openviking/ovcli.conf or OPENVIKING_API_KEY");+ return summary;+ } else {+ report.fail(`api key rejected on /health → ${authed?.status || health.status}`,+ `${serverErrorMessage(authed) || serverErrorMessage(health) || "(no message)"} — key ${keyInfo?.display || "?"}`,+ "this deployment authenticates /health itself and rejected this key; check it against the key issued for this deployment (OpenViking Cloud keys come from the Volcengine console)");+ return summary;+ }+ }if (health.status === 404) {report.fail(`GET /health → 404 at ${conn.baseUrl}`, "the url points at a web server, but not at an OpenViking API root","check for a missing path prefix (OpenViking Cloud needs /openviking) or a reverse proxy that does not forward /health");@@ -977,9 +1011,14 @@ export function findPortListener(port) {return out;}-export async function probeReady(baseUrl, { timeoutMs = 15000 } = {}) {+/**+ * `GET /ready`. `conn` is sent when there is one: deployments that gate+ * /health gate /ready the same way, and a self-hosted server ignores the+ * header.+ */+export async function probeReady(baseUrl, { timeoutMs = 15000, conn = null } = {}) {const base = String(baseUrl || "").replace(/\/+$/, "");- return httpProbe({ url: `${base}/ready`, timeoutMs: Math.max(timeoutMs, 15000) });+ return httpProbe({ url: `${base}/ready`, timeoutMs: Math.max(timeoutMs, 15000), headers: conn ? authHeaders(conn) : {} });}/** Flatten one `/ready` check (string or {status, checks}) into { ok, text }. */@@ -1049,9 +1088,11 @@ function urlHostPort(baseUrl) {/*** The "Server health" section. `health` is the /health probe already taken- * for the Connection section; `ovConf` is inspectJsonFile(<ov.conf path>).+ * for the Connection section (effectiveHealthProbe, so a gateway that gates+ * /health does not read as "the server never answered"); `conn` carries the+ * credentials /ready may also need; `ovConf` is inspectJsonFile(<ov.conf path>).*/-export async function checkServerHealth(report, { baseUrl, ovConf, health, offline = false, timeoutMs = 5000 } = {}) {+export async function checkServerHealth(report, { baseUrl, ovConf, health, conn = null, offline = false, timeoutMs = 5000 } = {}) {report.section("Server health");const answered = Boolean(health && !health.error && health.ok && isObject(health.json));const summary = { local: isLoopbackUrl(baseUrl), reachable: answered, ready: null, listener: null };@@ -1079,7 +1120,7 @@ export async function checkServerHealth(report, { baseUrl, ovConf, health, offliif (offline) report.info("skipped /ready (--offline)");else if (health?.json?.status === "pending_initialization") report.info("skipped /ready — the container has no config yet");else if (!answered) report.info("skipped /ready — the server did not answer /health");- else summary.ready = assessReady(report, await probeReady(baseUrl, { timeoutMs })).ready;+ else summary.ready = assessReady(report, await probeReady(baseUrl, { timeoutMs, conn })).ready;return summary;}@@ -1399,7 +1440,7 @@ export async function checkConnection(report, cfg, { keyInfo, peer, account = ""const probes = await probeOpenViking(conn, { timeoutMs: opts.timeoutMs });const summary = assessProbes(report, probes, { ...conn, account, user }, keyInfo);if (onSummary) onSummary(report, summary, cfg);- return { probes, summary };+ return { probes, summary, conn };}/**@@ -1420,7 +1461,7 @@ export async function runDoctor(host) {const workspace = checkWorkspace(report, { clientVersion: cfg.clientVersion });const identity = host.resolveIdentity(cfg);const connection = await checkConnection(report, cfg, { ...configInfo, ...identity }, opts, host);- const serverHealth = await checkServerHealth(report, { baseUrl: cfg.baseUrl, ovConf: configInfo.ovConf, health: connection?.probes?.health, offline: opts.offline, timeoutMs: opts.timeoutMs });+ const serverHealth = await checkServerHealth(report, { baseUrl: cfg.baseUrl, ovConf: configInfo.ovConf, health: effectiveHealthProbe(connection?.probes), conn: connection?.conn, offline: opts.offline, timeoutMs: opts.timeoutMs });host.checkActivity(report, cfg, connection);if (opts.json) {diff --git a/examples/claude-code-memory-plugin/skills/ov-memory-doctor/SKILL.md b/examples/claude-code-memory-plugin/skills/ov-memory-doctor/SKILL.mdindex abec61d5d..e4395ecdc 100644--- a/examples/claude-code-memory-plugin/skills/ov-memory-doctor/SKILL.md+++ b/examples/claude-code-memory-plugin/skills/ov-memory-doctor/SKILL.md@@ -26,8 +26,10 @@ three moving parts and each fails silently in its own way:and `OPENVIKING_*` environment variables, resolved as env → ovcli.conf →ov.conf → defaults. A malformed file reads as "no config", which silentlydisables the plugin; a stray env var silently overrides the file.-- **Connection** — `/health` answers 200 even with a bad key, so the statusline- can be green while every real request 401s.+- **Connection** — on a self-hosted server `/health` answers 200 even with a+ bad key, so the statusline can be green while every real request 401s. On+ OpenViking Cloud the gateway authenticates `/health` and `/ready` too, so+ the same probe answers 401 without a key and says nothing about the url.When the resolved url is loopback, the server runs on this machine and thedoctor adds a **Server health** section: whether anything listens on the@@ -81,6 +83,7 @@ Work top-down; fix the first ✗ and rerun before chasing the next.| `node is not on PATH` / node < 18 | Hooks and `.mcp.json` run the bare command `node`; GUI/IDE launches often lack nvm/volta shims | Put node on PATH for the launching environment, or set `PATH` in the `env` block of `~/.claude/settings.json`. || `server unreachable` (refused / dns / timeout / tls) | Wrong url/port, server down, DNS/VPN, private CA | Compare with `curl -sS <url>/health`. curl OK + doctor fails ⇒ proxy or CA issue (see Step 3). || `base URL ends with /api/v1` or `/mcp`, no scheme, `GET /health → 404` | url shape wrong (paths are concatenated bare); Cloud needs the `/openviking` prefix | Fix `url` to the API root. |+| `/health is authenticated at this deployment` (info) / `api key rejected on /health → 401` | OpenViking Cloud gates `/health` and `/ready` at the gateway, so the probe without a key 401s and says nothing about the url | The info line needs no fix — the report reads /health with the key instead. The ✗ means the gateway rejected this key: use one issued for that deployment (Cloud keys come from the Volcengine console). || `api key rejected` (200 from /health with no identity) then `system/status → 401 Invalid API Key` | Key invalid/revoked/for another deployment. A 3-segment key for a non-existent account looks identical. | Get the key re-issued; check no env var shadows ovcli.conf ("← env" in the Configuration section). || `using the ROOT api key` / `403 ROOT API keys cannot access tenant-scoped data APIs` | `api_key` fell through to `ov.conf server.root_api_key`, or the user pasted the root key | Create a user key (`POST /api/v1/admin/accounts/<account>/users` with the root key) and put it in ovcli.conf. || `server is in trusted mode and needs account + user` / 400 `Trusted mode requests must include…` | Server identity comes from headers | Set `account` and `user` in ovcli.conf. |@@ -116,7 +119,7 @@ space):```bashURL=<url>; KEY=<key>-curl -sS "$URL/health" # reachability, version, auth_mode+curl -sS "$URL/health" # reachability, version, auth_mode (401 on Cloud: the gateway gates /health)curl -sS -H "Authorization: Bearer $KEY" "$URL/health" # 200 without account_id/user_id/role ⇒ key invalidcurl -sS -w '\n%{http_code}\n' -H "Authorization: Bearer $KEY" "$URL/api/v1/system/status" # real 401/403```diff --git a/examples/codex-memory-plugin/scripts/shared/doctor-core.mjs b/examples/codex-memory-plugin/scripts/shared/doctor-core.mjsindex a24da5b29..c15a97ead 100644--- a/examples/codex-memory-plugin/scripts/shared/doctor-core.mjs+++ b/examples/codex-memory-plugin/scripts/shared/doctor-core.mjs@@ -504,6 +504,7 @@ export function serverErrorMessage(probe) {* Run the standard probe ladder against an OpenViking server.** health GET /health without credentials — reachability, version, auth_mode+ * (401/403 where a gateway authenticates ahead of OpenViking)* healthAuth GET /health with credentials — identity echo (account/user/role)* systemStatus GET /api/v1/system/status — first authenticated call the hooks make; real 401/403* fsLs GET /api/v1/fs/ls?uri=viking://~/memories — tenant-data authorization + resolved user space@@ -538,13 +539,28 @@ export async function probeOpenViking(conn, { timeoutMs = 5000, mcp = true } = {return out;}+/**+ * The /health answer the rest of the report should read. A gateway that+ * authenticates ahead of OpenViking (Cloud behind the Volcengine gateway)+ * answers the credential-less probe with 401/403 before the request reaches+ * the server, so version, auth_mode and identity all come from the+ * authenticated probe instead.+ */+export function effectiveHealthProbe(probes) {+ const health = probes?.health;+ const authed = probes?.healthAuth;+ if (health && !health.error && (health.status === 401 || health.status === 403)+ && authed?.ok && isObject(authed.json)) return authed;+ return health;+}+/*** Turn probe results into findings. `keyInfo` is describeApiKey(conn.apiKey).* Returns { authMode, version, identity } for callers that want to cross-check.*/export function assessProbes(report, probes, conn, keyInfo) {const summary = { authMode: "", version: "", identity: null, reachable: false, authOk: false };- const health = probes.health;+ let health = probes.health;if (!health) return summary;if (health.error) {@@ -553,6 +569,24 @@ export function assessProbes(report, probes, conn, keyInfo) {return summary;}summary.reachable = true;+ if (health.status === 401 || health.status === 403) {+ // The url is fine: something in front of OpenViking demands credentials on+ // /health itself. Read it with the key and carry on down the ladder.+ const authed = probes.healthAuth;+ if (authed?.ok && isObject(authed.json)) {+ report.info(`/health is authenticated at this deployment — without a key it answers ${health.status}, so the report reads it with the api key`);+ health = authed;+ } else if (!conn.apiKey && !conn.account && !conn.user) {+ report.fail(`GET /health → ${health.status} and no credentials are configured`, serverErrorMessage(health),+ "this deployment authenticates /health itself (OpenViking Cloud does); set api_key in ~/.openviking/ovcli.conf or OPENVIKING_API_KEY");+ return summary;+ } else {+ report.fail(`api key rejected on /health → ${authed?.status || health.status}`,+ `${serverErrorMessage(authed) || serverErrorMessage(health) || "(no message)"} — key ${keyInfo?.display || "?"}`,+ "this deployment authenticates /health itself and rejected this key; check it against the key issued for this deployment (OpenViking Cloud keys come from the Volcengine console)");+ return summary;+ }+ }if (health.status === 404) {report.fail(`GET /health → 404 at ${conn.baseUrl}`, "the url points at a web server, but not at an OpenViking API root","check for a missing path prefix (OpenViking Cloud needs /openviking) or a reverse proxy that does not forward /health");@@ -977,9 +1011,14 @@ export function findPortListener(port) {return out;}-export async function probeReady(baseUrl, { timeoutMs = 15000 } = {}) {+/**+ * `GET /ready`. `conn` is sent when there is one: deployments that gate+ * /health gate /ready the same way, and a self-hosted server ignores the+ * header.+ */+export async function probeReady(baseUrl, { timeoutMs = 15000, conn = null } = {}) {const base = String(baseUrl || "").replace(/\/+$/, "");- return httpProbe({ url: `${base}/ready`, timeoutMs: Math.max(timeoutMs, 15000) });+ return httpProbe({ url: `${base}/ready`, timeoutMs: Math.max(timeoutMs, 15000), headers: conn ? authHeaders(conn) : {} });}/** Flatten one `/ready` check (string or {status, checks}) into { ok, text }. */@@ -1049,9 +1088,11 @@ function urlHostPort(baseUrl) {/*** The "Server health" section. `health` is the /health probe already taken- * for the Connection section; `ovConf` is inspectJsonFile(<ov.conf path>).+ * for the Connection section (effectiveHealthProbe, so a gateway that gates+ * /health does not read as "the server never answered"); `conn` carries the+ * credentials /ready may also need; `ovConf` is inspectJsonFile(<ov.conf path>).*/-export async function checkServerHealth(report, { baseUrl, ovConf, health, offline = false, timeoutMs = 5000 } = {}) {+export async function checkServerHealth(report, { baseUrl, ovConf, health, conn = null, offline = false, timeoutMs = 5000 } = {}) {report.section("Server health");const answered = Boolean(health && !health.error && health.ok && isObject(health.json));const summary = { local: isLoopbackUrl(baseUrl), reachable: answered, ready: null, listener: null };@@ -1079,7 +1120,7 @@ export async function checkServerHealth(report, { baseUrl, ovConf, health, offliif (offline) report.info("skipped /ready (--offline)");else if (health?.json?.status === "pending_initialization") report.info("skipped /ready — the container has no config yet");else if (!answered) report.info("skipped /ready — the server did not answer /health");- else summary.ready = assessReady(report, await probeReady(baseUrl, { timeoutMs })).ready;+ else summary.ready = assessReady(report, await probeReady(baseUrl, { timeoutMs, conn })).ready;return summary;}@@ -1399,7 +1440,7 @@ export async function checkConnection(report, cfg, { keyInfo, peer, account = ""const probes = await probeOpenViking(conn, { timeoutMs: opts.timeoutMs });const summary = assessProbes(report, probes, { ...conn, account, user }, keyInfo);if (onSummary) onSummary(report, summary, cfg);- return { probes, summary };+ return { probes, summary, conn };}/**@@ -1420,7 +1461,7 @@ export async function runDoctor(host) {const workspace = checkWorkspace(report, { clientVersion: cfg.clientVersion });const identity = host.resolveIdentity(cfg);const connection = await checkConnection(report, cfg, { ...configInfo, ...identity }, opts, host);- const serverHealth = await checkServerHealth(report, { baseUrl: cfg.baseUrl, ovConf: configInfo.ovConf, health: connection?.probes?.health, offline: opts.offline, timeoutMs: opts.timeoutMs });+ const serverHealth = await checkServerHealth(report, { baseUrl: cfg.baseUrl, ovConf: configInfo.ovConf, health: effectiveHealthProbe(connection?.probes), conn: connection?.conn, offline: opts.offline, timeoutMs: opts.timeoutMs });host.checkActivity(report, cfg, connection);if (opts.json) {diff --git a/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.md b/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.mdindex 1386c3825..62be0acb0 100644--- a/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.md+++ b/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.md@@ -26,8 +26,10 @@ wrong on a user's machine, each silently:`OPENVIKING_*` environment variables. A malformed file reads as "no config"and the plugin silently falls back to `http://127.0.0.1:1933` with no key; astray env var silently overrides the file.-- **Connection** — `/health` answers 200 even with a bad key, so everything- can look reachable while every real request 401s.+- **Connection** — on a self-hosted server `/health` answers 200 even with a+ bad key, so everything can look reachable while every real request 401s. On+ OpenViking Cloud the gateway authenticates `/health` and `/ready` too, so+ the same probe answers 401 without a key and says nothing about the url.When the resolved url is loopback, the server runs on this machine and thedoctor adds a **Server health** section: whether anything listens on the@@ -91,6 +93,7 @@ Work top-down; fix the first ✗ and rerun before chasing the next.| `OPENVIKING_MEMORY_ENABLED has no effect` | That switch is Claude Code only | `OPENVIKING_AUTO_RECALL=0` / `OPENVIKING_AUTO_CAPTURE=0`, or `codex plugin remove`. || `server unreachable` (refused / dns / timeout / tls) | Wrong url/port, server down, DNS/VPN, private CA | Compare with `curl -sS <url>/health`; curl OK + doctor fails ⇒ proxy or CA issue (Step 3). || `base URL ends with /api/v1` or `/mcp`, no scheme, `GET /health → 404` | url shape wrong; Cloud needs the `/openviking` prefix | Fix `url` to the API root. |+| `/health is authenticated at this deployment` (info) / `api key rejected on /health → 401` | OpenViking Cloud gates `/health` and `/ready` at the gateway, so the probe without a key 401s and says nothing about the url | The info line needs no fix — the report reads /health with the key instead. The ✗ means the gateway rejected this key: use one issued for that deployment (Cloud keys come from the Volcengine console). || `api key rejected` then `system/status → 401 Invalid API Key` | Key invalid/revoked/for another deployment | Get the key re-issued; check nothing overrides ovcli.conf ("← env"). || `using the ROOT api key` / `403 ROOT API keys cannot access tenant-scoped data APIs` | `api_key` fell through to `ov.conf server.root_api_key`, or the root key was pasted | Use a user/admin key. || `plugin auth mode 'trusted' differs from the server's 'api_key'` | account/user set in ovcli.conf ⇒ the plugin sends identity headers, which an `api_key` server ignores; data lands under the key's identity | Remove account/user (or set `OPENVIKING_AUTH_MODE=api_key`), or use a key for that identity. |@@ -122,7 +125,7 @@ space):```bashURL=<url>; KEY=<key>-curl -sS "$URL/health" # reachability, version, auth_mode+curl -sS "$URL/health" # reachability, version, auth_mode (401 on Cloud: the gateway gates /health)curl -sS -H "Authorization: Bearer $KEY" "$URL/health" # 200 without account_id/user_id/role ⇒ key invalidcurl -sS -w '\n%{http_code}\n' -H "Authorization: Bearer $KEY" "$URL/api/v1/system/status" # real 401/403```diff --git a/examples/memory-plugin-shared/doctor-core.test.mjs b/examples/memory-plugin-shared/doctor-core.test.mjsindex 20f135fdc..ce68ddf59 100644--- a/examples/memory-plugin-shared/doctor-core.test.mjs+++ b/examples/memory-plugin-shared/doctor-core.test.mjs@@ -13,6 +13,7 @@ import {createReport,credentialSources,describeApiKey,+ effectiveHealthProbe,inspectJsonFile,lintBaseUrl,lintServerConf,@@ -110,6 +111,42 @@ test("assessProbes accepts an echoed identity and warns about root keys", () =>assert.ok(titles.some((t) => t.includes("differ from the key's identity")));});+test("assessProbes keeps going when the deployment authenticates /health itself", () => {+ const conn = { baseUrl: "https://api.vikingdb.cn-beijing.volces.com/openviking", apiKey: "k".repeat(64) };+ const health = { ok: false, status: 401, latencyMs: 40, json: { status: "error", error: { code: "AuthenticationError", message: "The API key in the request is missing or invalid." } } };+ const healthAuth = { ok: true, status: 200, latencyMs: 45, json: { status: "ok", version: "v0.4.17.3", auth_mode: "api_key", account_id: "default", user_id: "default", role: "admin" } };+ const report = createReport();+ const summary = assessProbes(report, { health, healthAuth, systemStatus: { ok: true, status: 200, json: { result: { user: "default" } } } }, conn, describeApiKey(conn.apiKey));+ assert.equal(summary.reachable, true);+ assert.equal(summary.authOk, true);+ assert.equal(summary.version, "v0.4.17.3");+ assert.equal(summary.authMode, "api_key");+ assert.deepEqual(report.problems(), []);+ assert.equal(report.exitCode(), 0);+ assert.equal(effectiveHealthProbe({ health, healthAuth }), healthAuth);+});++test("assessProbes blames the key when the authenticated /health is rejected too", () => {+ const conn = { baseUrl: "https://api.vikingdb.cn-beijing.volces.com/openviking", apiKey: "k".repeat(64) };+ const health = { ok: false, status: 401, latencyMs: 40, json: { status: "error", error: { message: "The API key in the request is missing or invalid." } } };+ const report = createReport();+ const summary = assessProbes(report, { health, healthAuth: { ...health } }, conn, describeApiKey(conn.apiKey));+ assert.equal(summary.reachable, true);+ assert.equal(summary.authOk, false);+ const titles = report.problems().map((p) => p.title);+ assert.ok(titles.some((t) => t.startsWith("api key rejected on /health")));+ assert.ok(!titles.some((t) => t.includes("not like OpenViking")));+ assert.equal(effectiveHealthProbe({ health, healthAuth: { ...health } }), health);+});++test("assessProbes names the missing key when a gated /health gets no credentials", () => {+ const report = createReport();+ const health = { ok: false, status: 401, latencyMs: 40, json: { status: "error", error: { message: "missing or invalid" } } };+ const summary = assessProbes(report, { health }, { baseUrl: "https://api.vikingdb.cn-beijing.volces.com/openviking" }, describeApiKey(""));+ assert.equal(summary.reachable, true);+ assert.match(report.render(), /no credentials are configured/);+});+test("assessProbes reports unreachable servers with the classified cause", () => {const report = createReport();assessProbes(report, { health: { ok: false, status: 0, error: "connect ECONNREFUSED", errorKind: "refused", errorHint: "connection refused" } }, { baseUrl: "http://127.0.0.1:1933" }, describeApiKey(""));diff --git a/examples/memory-plugin-shared/lib/doctor-core.mjs b/examples/memory-plugin-shared/lib/doctor-core.mjsindex 4c21b9f9c..4e39b0781 100644--- a/examples/memory-plugin-shared/lib/doctor-core.mjs+++ b/examples/memory-plugin-shared/lib/doctor-core.mjs@@ -503,6 +503,7 @@ export function serverErrorMessage(probe) {* Run the standard probe ladder against an OpenViking server.** health GET /health without credentials — reachability, version, auth_mode+ * (401/403 where a gateway authenticates ahead of OpenViking)* healthAuth GET /health with credentials — identity echo (account/user/role)* systemStatus GET /api/v1/system/status — first authenticated call the hooks make; real 401/403* fsLs GET /api/v1/fs/ls?uri=viking://~/memories — tenant-data authorization + resolved user space@@ -537,13 +538,28 @@ export async function probeOpenViking(conn, { timeoutMs = 5000, mcp = true } = {return out;}+/**+ * The /health answer the rest of the report should read. A gateway that+ * authenticates ahead of OpenViking (Cloud behind the Volcengine gateway)+ * answers the credential-less probe with 401/403 before the request reaches+ * the server, so version, auth_mode and identity all come from the+ * authenticated probe instead.+ */+export function effectiveHealthProbe(probes) {+ const health = probes?.health;+ const authed = probes?.healthAuth;+ if (health && !health.error && (health.status === 401 || health.status === 403)+ && authed?.ok && isObject(authed.json)) return authed;+ return health;+}+/*** Turn probe results into findings. `keyInfo` is describeApiKey(conn.apiKey).* Returns { authMode, version, identity } for callers that want to cross-check.*/export function assessProbes(report, probes, conn, keyInfo) {const summary = { authMode: "", version: "", identity: null, reachable: false, authOk: false };- const health = probes.health;+ let health = probes.health;if (!health) return summary;if (health.error) {@@ -552,6 +568,24 @@ export function assessProbes(report, probes, conn, keyInfo) {return summary;}summary.reachable = true;+ if (health.status === 401 || health.status === 403) {+ // The url is fine: something in front of OpenViking demands credentials on+ // /health itself. Read it with the key and carry on down the ladder.+ const authed = probes.healthAuth;+ if (authed?.ok && isObject(authed.json)) {+ report.info(`/health is authenticated at this deployment — without a key it answers ${health.status}, so the report reads it with the api key`);+ health = authed;+ } else if (!conn.apiKey && !conn.account && !conn.user) {+ report.fail(`GET /health → ${health.status} and no credentials are configured`, serverErrorMessage(health),+ "this deployment authenticates /health itself (OpenViking Cloud does); set api_key in ~/.openviking/ovcli.conf or OPENVIKING_API_KEY");+ return summary;+ } else {+ report.fail(`api key rejected on /health → ${authed?.status || health.status}`,+ `${serverErrorMessage(authed) || serverErrorMessage(health) || "(no message)"} — key ${keyInfo?.display || "?"}`,+ "this deployment authenticates /health itself and rejected this key; check it against the key issued for this deployment (OpenViking Cloud keys come from the Volcengine console)");+ return summary;+ }+ }if (health.status === 404) {report.fail(`GET /health → 404 at ${conn.baseUrl}`, "the url points at a web server, but not at an OpenViking API root","check for a missing path prefix (OpenViking Cloud needs /openviking) or a reverse proxy that does not forward /health");@@ -976,9 +1010,14 @@ export function findPortListener(port) {return out;}-export async function probeReady(baseUrl, { timeoutMs = 15000 } = {}) {+/**+ * `GET /ready`. `conn` is sent when there is one: deployments that gate+ * /health gate /ready the same way, and a self-hosted server ignores the+ * header.+ */+export async function probeReady(baseUrl, { timeoutMs = 15000, conn = null } = {}) {const base = String(baseUrl || "").replace(/\/+$/, "");- return httpProbe({ url: `${base}/ready`, timeoutMs: Math.max(timeoutMs, 15000) });+ return httpProbe({ url: `${base}/ready`, timeoutMs: Math.max(timeoutMs, 15000), headers: conn ? authHeaders(conn) : {} });}/** Flatten one `/ready` check (string or {status, checks}) into { ok, text }. */@@ -1048,9 +1087,11 @@ function urlHostPort(baseUrl) {/*** The "Server health" section. `health` is the /health probe already taken- * for the Connection section; `ovConf` is inspectJsonFile(<ov.conf path>).+ * for the Connection section (effectiveHealthProbe, so a gateway that gates+ * /health does not read as "the server never answered"); `conn` carries the+ * credentials /ready may also need; `ovConf` is inspectJsonFile(<ov.conf path>).*/-export async function checkServerHealth(report, { baseUrl, ovConf, health, offline = false, timeoutMs = 5000 } = {}) {+export async function checkServerHealth(report, { baseUrl, ovConf, health, conn = null, offline = false, timeoutMs = 5000 } = {}) {report.section("Server health");const answered = Boolean(health && !health.error && health.ok && isObject(health.json));const summary = { local: isLoopbackUrl(baseUrl), reachable: answered, ready: null, listener: null };@@ -1078,7 +1119,7 @@ export async function checkServerHealth(report, { baseUrl, ovConf, health, offliif (offline) report.info("skipped /ready (--offline)");else if (health?.json?.status === "pending_initialization") report.info("skipped /ready — the container has no config yet");else if (!answered) report.info("skipped /ready — the server did not answer /health");- else summary.ready = assessReady(report, await probeReady(baseUrl, { timeoutMs })).ready;+ else summary.ready = assessReady(report, await probeReady(baseUrl, { timeoutMs, conn })).ready;return summary;}@@ -1398,7 +1439,7 @@ export async function checkConnection(report, cfg, { keyInfo, peer, account = ""const probes = await probeOpenViking(conn, { timeoutMs: opts.timeoutMs });const summary = assessProbes(report, probes, { ...conn, account, user }, keyInfo);if (onSummary) onSummary(report, summary, cfg);- return { probes, summary };+ return { probes, summary, conn };}/**@@ -1419,7 +1460,7 @@ export async function runDoctor(host) {const workspace = checkWorkspace(report, { clientVersion: cfg.clientVersion });const identity = host.resolveIdentity(cfg);const connection = await checkConnection(report, cfg, { ...configInfo, ...identity }, opts, host);- const serverHealth = await checkServerHealth(report, { baseUrl: cfg.baseUrl, ovConf: configInfo.ovConf, health: connection?.probes?.health, offline: opts.offline, timeoutMs: opts.timeoutMs });+ const serverHealth = await checkServerHealth(report, { baseUrl: cfg.baseUrl, ovConf: configInfo.ovConf, health: effectiveHealthProbe(connection?.probes), conn: connection?.conn, offline: opts.offline, timeoutMs: opts.timeoutMs });host.checkActivity(report, cfg, connection);if (opts.json) {