@aliyunrds/ctxdb 1.0.2 → 1.0.3

package/dist/cli/main.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import {
   DEFAULT_FILE_INGEST_TIMEOUT_MS,
+  DEFAULT_FILE_UPLOAD_TIMEOUT_MS,
   DEFAULT_INGEST_TIMEOUT_MS,
   compactKbQueryResponse,
   createKb,
@@ -11,7 +12,7 @@ import {
   pollIngest,
   uploadFile,
   uploadText
-} from "../chunk-UH7AJF6F.js";
+} from "../chunk-3PFMHU3C.js";
 import {
   DEFAULT_BASE_URL,
   DEFAULT_USER_ID,
@@ -21,7 +22,10 @@ import {
   agentFromEnv,
   agentHomeDir,
   agentHomeDirs,
+  agentPlatformSupport,
   configuredAgents,
+  detectInstalledAgents,
+  inspectAgentHomes,
   isAgentSlug,
   isBuiltinAgent,
   isComplete,
@@ -29,7 +33,12 @@ import {
   removeAgent,
   save,
   writeInstalledPkgVersion
-} from "../chunk-6FZL67GH.js";
+} from "../chunk-JFTKYEVN.js";
+import {
+  beginUpdateNotification,
+  completeUpdateNotification,
+  runSelfUpdate
+} from "../chunk-BQA7YSXT.js";
 
 // src/cli/util.ts
 var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
@@ -55,6 +64,8 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "all",
   // memory delete
   // kb
+  "wait",
+  // kb upload-text / upload-file
   "no-wait",
   // kb upload-text / upload-file
   "verbose",
@@ -125,7 +136,12 @@ function isSetupResult(v) {
 }
 function isUpgradeResult(v) {
   if (typeof v !== "object" || v === null) return false;
-  return "agents" in v && typeof v.agents === "object" && !("steps" in v);
+  return "agents" in v && typeof v.agents === "object" && !("steps" in v) && !("mode" in v);
+}
+function isMultiAgentResult(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const value = v;
+  return value.mode === "all" && (value.operation === "setup" || value.operation === "status") && typeof value.agents === "object" && value.agents !== null && Array.isArray(value.skipped) && typeof value.summary === "object" && value.summary !== null;
 }
 function isStatusResult(v) {
   if (typeof v !== "object" || v === null) return false;
@@ -158,6 +174,45 @@ function formatUpgradeResult(r) {
   }
   return lines.join("\n");
 }
+function formatMultiAgentResult(r) {
+  const lines = [];
+  const { selected, succeeded, failed, skipped } = r.summary;
+  lines.push(
+    `${r.ok ? CHECK : CROSS} ${BOLD}ctxdb ${r.operation} --all${RESET} ${r.ok ? "completed" : "failed"} ${DIM}(${selected} selected, ${succeeded} succeeded, ${failed} failed, ${skipped} skipped)${RESET}
+`
+  );
+  for (const [name, result] of Object.entries(r.agents)) {
+    const agentOk = r.operation === "setup" ? Boolean(result.ok) : Boolean(result.ok && result.connected);
+    lines.push(`  ${agentOk ? CHECK : CROSS} ${BOLD}${name}${RESET}`);
+    if (r.operation === "setup") {
+      for (const step of result.steps ?? []) {
+        const detail = step.detail ? `  ${DIM}${step.detail}${RESET}` : "";
+        lines.push(`      ${step.ok ? CHECK : CROSS} ${step.step}${detail}`);
+      }
+      for (const hint of result.hints ?? []) {
+        lines.push(`      ${DIM}hint${RESET}  ${hint}`);
+      }
+      continue;
+    }
+    lines.push(`      ${DIM}config${RESET}     ${result.ok ? "complete" : "incomplete"}`);
+    lines.push(`      ${DIM}connected${RESET}  ${result.connected ? "yes" : "no"}`);
+    if (result.hooks_node !== void 0) {
+      lines.push(`      ${DIM}hooks${RESET}      ${result.hooks_node}`);
+    }
+    if (result.ping_error) {
+      lines.push(`      ${DIM}ping_error${RESET} ${result.ping_error}`);
+    }
+  }
+  if (r.skipped.length > 0) {
+    lines.push("");
+    lines.push(`  ${DIM}skipped${RESET}`);
+    for (const item of r.skipped) {
+      const detail = item.detail ? ` \u2014 ${item.detail}` : "";
+      lines.push(`      ${item.agent}: ${item.reason}${detail}`);
+    }
+  }
+  return lines.join("\n");
+}
 function formatStatusResult(r) {
   const lines = [];
   const ok = r.connected ? CHECK : CROSS;
@@ -190,6 +245,8 @@ function formatStatusResult(r) {
 function printResult(value, json, command) {
   if (json) {
     process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+  } else if (isMultiAgentResult(value)) {
+    process.stdout.write(formatMultiAgentResult(value) + "\n");
   } else if (isUpgradeResult(value)) {
     process.stdout.write(formatUpgradeResult(value) + "\n");
   } else if (isSetupResult(value)) {
@@ -227,6 +284,9 @@ function fail(message, code = 1) {
   process.exit(code);
 }
 
+// src/cli/main.ts
+import { fileURLToPath as fileURLToPath2 } from "url";
+
 // src/setup/installer.ts
 import {
   readFileSync,
@@ -248,6 +308,10 @@ import { execFileSync } from "child_process";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 var UNINSTALL_NPM_HINT = "To also remove the npm binaries: `npm uninstall -g @aliyunrds/ctxdb @aliyunrds/ctxdb-shared`";
 var UNINSTALL_ORDER_HINT = "When you eventually want to uninstall: run `ctxdb uninstall --purge-all` FIRST, then `npm uninstall -g @aliyunrds/ctxdb @aliyunrds/ctxdb-shared`. (npm 7+ removed uninstall lifecycle hooks, so the order matters \u2014 otherwise agent settings.json hooks + ~/.ctxdb/ residue stay behind.)";
+var HERMES_RESTART_HINT = "Restart any running Hermes CLI or gateway process to load the registered hooks; Hermes registers shell hooks only at process startup.";
+var HERMES_ALLOWLIST_ACTION_HINT = "Next action [hermes-hook-allowlist]: run `hermes --accept-hooks chat`; after Hermes starts, exit the chat and rerun `ctxdb setup --agent hermes`, then restart any running Hermes CLI or gateway process.";
+var HERMES_WEBUI_GATEWAY_HINT = "Using hermes-webui? Its default legacy backend does not load Hermes shell hooks. Set `HERMES_WEBUI_CHAT_BACKEND=gateway` to route chat through Hermes Gateway; if the gateway requires authentication, also set `HERMES_WEBUI_GATEWAY_API_KEY`, then restart hermes-webui. Reference: https://github.com/nesquena/hermes-webui/blob/master/docs/advanced-chat-setup.md#gateway-backed-browser-chat";
+var NO_AGENTS_DETECTED_HINT = "No setup-compatible Agent detected. Install or start a supported Agent once, then rerun `ctxdb setup --all`; use `ctxdb setup --agent <name>` to target one explicitly.";
 function skillInstallRoot(agent) {
   switch (agent) {
     case "qoder":
@@ -579,8 +643,13 @@ async function runSetup(options) {
       }
     }
   }
-  const ok = steps.every((s) => s.ok);
+  const failedSteps = steps.filter((s) => !s.ok);
+  const ok = failedSteps.length === 0;
+  const actionRequired = agent === "hermes" && failedSteps.length === 1 && failedSteps[0]?.step === "check-hermes-hook-allowlist" ? "hermes-hook-allowlist" : void 0;
   const hints = ok ? [UNINSTALL_ORDER_HINT] : [];
+  if (actionRequired) {
+    hints.unshift(HERMES_ALLOWLIST_ACTION_HINT, HERMES_WEBUI_GATEWAY_HINT);
+  }
   if (ok && agent === "opencode") {
     hints.unshift(
       `OpenCode plugin shim: ${opencodeShimPath()}`,
@@ -589,10 +658,98 @@ async function runSetup(options) {
   }
   if (ok && agent === "hermes") {
     hints.unshift(
-      `Hermes shell hooks: ${hermesConfigPath()} \u2192 pre_llm_call + post_llm_call`
+      `Hermes shell hooks: ${hermesConfigPath()} \u2192 pre_llm_call + post_llm_call`,
+      HERMES_RESTART_HINT,
+      HERMES_WEBUI_GATEWAY_HINT
     );
   }
-  return { ok, steps, hints: hints.length > 0 ? hints : void 0 };
+  return {
+    ok,
+    steps,
+    actionRequired,
+    hints: hints.length > 0 ? hints : void 0
+  };
+}
+function skippedFromDetection(detection) {
+  return detection.observations.filter((item) => !item.selected).map((item) => ({
+    agent: item.agent,
+    reason: item.reason,
+    evidence: item.evidence,
+    ...item.detail ? { detail: item.detail } : {}
+  }));
+}
+function withoutSharedUninstallHint(result) {
+  const hints = result.hints?.filter((hint) => hint !== UNINSTALL_ORDER_HINT);
+  return {
+    ...result,
+    ...hints && hints.length > 0 ? { hints } : { hints: void 0 }
+  };
+}
+function missingApiKeyResult(agent) {
+  return {
+    ok: false,
+    steps: [{
+      step: "write-config",
+      ok: false,
+      detail: `${agent}: --api-key is required (won't write config without a valid API key)`
+    }]
+  };
+}
+async function runSetupAll(options = {}, dependencies = {}) {
+  const detect = dependencies.detect ?? detectInstalledAgents;
+  const loadConfig = dependencies.loadConfig ?? ((agent) => load({ agent }));
+  const setup2 = dependencies.setup ?? runSetup;
+  const detection = detect(options.detection);
+  const agents = {};
+  if (detection.selected.length === 0) {
+    return {
+      ok: false,
+      operation: "setup",
+      mode: "all",
+      agents,
+      skipped: skippedFromDetection(detection),
+      summary: { selected: 0, succeeded: 0, failed: 0, skipped: detection.observations.length },
+      hints: [NO_AGENTS_DETECTED_HINT]
+    };
+  }
+  const configSnapshot = /* @__PURE__ */ new Map();
+  for (const agent of detection.selected) {
+    configSnapshot.set(agent, loadConfig(agent));
+  }
+  for (const agent of detection.selected) {
+    const existing = configSnapshot.get(agent);
+    const apiKey = options.apiKey ?? existing.apiKey;
+    if (!apiKey) {
+      agents[agent] = missingApiKeyResult(agent);
+      continue;
+    }
+    agents[agent] = withoutSharedUninstallHint(await setup2({
+      agent,
+      apiKey,
+      baseUrl: options.baseUrl ?? existing.baseUrl,
+      userId: options.userId ?? existing.userId,
+      installSkill: options.installSkill,
+      validate: options.validate
+    }));
+  }
+  const results = Object.values(agents);
+  const succeeded = results.filter((result) => result.ok).length;
+  const failed = results.length - succeeded;
+  const skipped = skippedFromDetection(detection);
+  return {
+    ok: failed === 0,
+    operation: "setup",
+    mode: "all",
+    agents,
+    skipped,
+    summary: {
+      selected: results.length,
+      succeeded,
+      failed,
+      skipped: skipped.length
+    },
+    hints: [UNINSTALL_ORDER_HINT]
+  };
 }
 function runRemove(agent, options = {}) {
   const steps = [];
@@ -794,11 +951,12 @@ function runRemove(agent, options = {}) {
   return { ok: steps.every((s) => s.ok), steps };
 }
 function checkAgentHome(agent) {
-  if (agent === "hermes" && process.platform === "win32") {
+  const platform = agentPlatformSupport(agent);
+  if (!platform.supported) {
     return {
       step: "check-agent-home",
       ok: false,
-      detail: "hermes setup currently supports macOS/Linux only; Windows Hermes will be handled separately"
+      detail: platform.detail
     };
   }
   if (agent === "opencode" || agent === "hermes") {
@@ -814,7 +972,7 @@ function checkAgentHome(agent) {
       };
     }
   }
-  const dirs = agentHomeDirs(agent).filter((d) => existsSync(d));
+  const dirs = inspectAgentHomes(agent).existing;
   if (dirs.length === 0) {
     const primary = agentHomeDir(agent);
     return {
@@ -845,23 +1003,27 @@ function runTeardown(options = {}) {
   }
   if (purgeConfig) {
     const cfgPath = join(homedir(), ".ctxdb", "ctxdb.json");
-    if (existsSync(cfgPath)) {
-      try {
-        unlinkSync(cfgPath);
-        steps.push({ step: "purge-config", ok: true, detail: cfgPath });
-      } catch (err) {
-        steps.push({
-          step: "purge-config",
-          ok: false,
-          detail: `${cfgPath}: ${err?.message ?? String(err)}`
-        });
-      }
-    } else {
+    const ownedConfigFiles = [cfgPath, `${cfgPath}.bak`];
+    const existing = ownedConfigFiles.filter((path) => existsSync(path));
+    if (existing.length === 0) {
       steps.push({
         step: "purge-config",
         ok: true,
         detail: `nothing to remove (${cfgPath})`
       });
+    } else {
+      for (const path of existing) {
+        try {
+          unlinkSync(path);
+          steps.push({ step: "purge-config", ok: true, detail: path });
+        } catch (err) {
+          steps.push({
+            step: "purge-config",
+            ok: false,
+            detail: `${path}: ${err?.message ?? String(err)}`
+          });
+        }
+      }
     }
   }
   if (purgeLogs) {
@@ -1357,7 +1519,7 @@ function hermesAllowlistPath() {
 }
 function hermesHookApprovalHint(events = HERMES_HOOK_EVENTS) {
   const hookNames = events.map((event) => `\`${event}\``).join(" and ");
-  return `Approve the Hermes ctxdb hooks ${hookNames}: run \`hermes --accept-hooks chat\` once. This command opens an interactive chat; after Hermes starts, exit the chat, then rerun \`ctxdb setup --agent hermes\`.`;
+  return `Approve the Hermes ctxdb hooks ${hookNames}: run \`hermes --accept-hooks chat\` once. This command opens an interactive chat; after Hermes starts, exit the chat, rerun \`ctxdb setup --agent hermes\`, then restart any running Hermes CLI or gateway process.`;
 }
 function backupHermesConfig() {
   backupSettingsFile(hermesConfigPath());
@@ -1806,8 +1968,17 @@ async function runUpgrade(options = {}) {
 }
 
 // src/cli/top.ts
-async function status(args) {
-  const agent = agentFromFlags(args.flags);
+var STATUS_HELP = `ctxdb status \u2014 inspect configuration and connectivity
+
+USAGE
+  ctxdb status [--agent <qoder|qoderwork|codex|claude|opencode|hermes|default> | --all] [--json]
+
+FLAGS
+  --agent <name>  Inspect exactly one Agent profile
+  --all           Inspect every setup-compatible detected built-in Agent
+  --json          Machine-readable output
+`;
+async function inspectStatus(agent) {
   const cfg = load({ agent });
   const complete = isComplete(cfg);
   let connected = false;
@@ -1822,8 +1993,8 @@ async function status(args) {
     }
   }
   const hookHealth = isBuiltinAgent(agent) ? checkHookNodePaths(agent) : { installed: false, nodePaths: [], nodeOk: true, detail: "no hooks (default agent)" };
-  printResult(
-    {
+  return {
+    result: {
       ok: complete,
       agent,
       base_url: cfg.baseUrl,
@@ -1840,9 +2011,69 @@ async function status(args) {
       hooks_node_ok: hookHealth.nodeOk,
       version: PACKAGE_VERSION
     },
-    !!args.flags.json
-  );
-  return complete && connected ? 0 : 1;
+    success: complete && connected
+  };
+}
+function statusSkips(detection) {
+  return {
+    selected: detection.selected,
+    skipped: detection.observations.filter((item) => !item.selected).map((item) => ({
+      agent: item.agent,
+      reason: item.reason,
+      evidence: item.evidence,
+      ...item.detail ? { detail: item.detail } : {}
+    }))
+  };
+}
+async function statusAll(dependencies = {}) {
+  const detection = statusSkips((dependencies.detect ?? detectInstalledAgents)());
+  const inspect = dependencies.inspect ?? inspectStatus;
+  const agents = {};
+  let succeeded = 0;
+  for (const agent of detection.selected) {
+    const inspection = await inspect(agent);
+    agents[agent] = inspection.result;
+    if (inspection.success) succeeded += 1;
+  }
+  const failed = detection.selected.length - succeeded;
+  return {
+    ok: detection.selected.length > 0 && failed === 0,
+    operation: "status",
+    mode: "all",
+    agents,
+    skipped: detection.skipped,
+    summary: {
+      selected: detection.selected.length,
+      succeeded,
+      failed,
+      skipped: detection.skipped.length
+    },
+    ...detection.selected.length === 0 ? { hints: ["No setup-compatible Agent detected. Install or start one, then rerun `ctxdb status --all`."] } : {}
+  };
+}
+async function status(args) {
+  if (args.flags.help || args.flags.h) {
+    process.stdout.write(STATUS_HELP);
+    return 0;
+  }
+  if (args.flags.all === true) {
+    if (args.flags.agent !== void 0) {
+      process.stderr.write("cannot use --all and --agent together\n");
+      return 2;
+    }
+    const result = await statusAll();
+    printResult(result, !!args.flags.json);
+    if (!args.flags.json && result.hints) {
+      for (const hint of result.hints) process.stderr.write(`
+${hint}
+`);
+    }
+    return result.ok ? 0 : 1;
+  }
+  const agent = agentFromFlags(args.flags);
+  const inspection = await inspectStatus(agent);
+  printResult(inspection.result, !!args.flags.json);
+  return inspection.success ? 0 : 1;
 }
 async function ping(args) {
   const agent = agentFromFlags(args.flags);
@@ -1862,7 +2093,7 @@ async function ping(args) {
 var HELP = `ctxdb setup \u2014 configure an agent
 
 USAGE
-  ctxdb setup [--agent <qoder|qoderwork|codex|claude|opencode|hermes>]
+  ctxdb setup [--agent <qoder|qoderwork|codex|claude|opencode|hermes> | --all]
               [--api-key=K] [--base-url=URL] [--user-id=ID]
               [--no-install-skill] [--no-validate] [--json]
 
@@ -1871,13 +2102,20 @@ BEHAVIOR
                    no hooks or skills installed).
   With --agent     Writes agent config + installs hooks + skills for the
                    specified agent harness.
+                   Rerun for a new Agent, to repair integration files, or
+                   with --api-key <new-key> to replace that Agent's key.
+  With --all       Detects setup-compatible Agents on this host and runs the
+                   same setup lifecycle sequentially for each one. Successful
+                   Agents are preserved when another Agent fails.
   Hermes           Also verifies ~/.hermes/shell-hooks-allowlist.json.
                    Approve pre_llm_call + post_llm_call with
                    \`hermes --accept-hooks chat\`. It opens interactive chat;
-                   exit after Hermes starts, then rerun ctxdb setup.
+                   exit after Hermes starts, rerun ctxdb setup, then restart
+                   any running Hermes CLI/gateway process to load the hooks.
 
 FLAGS
   --agent <name>        Target agent (qoder|qoderwork|codex|claude|opencode|hermes)
+  --all                 Target every setup-compatible detected Agent
   --api-key <key>       API key (required on first setup)
   --base-url <url>      Server URL (default: https://context-database.aliyuncs.com)
   --user-id <id>        User bucket (default: "default")
@@ -1885,6 +2123,10 @@ FLAGS
   --no-validate         Skip connectivity ping after setup
   --json                Machine-readable JSON output
 `;
+var CODEX_HOOKS_TRUST_REMINDER = [
+  "codex hooks \u914D\u7F6E\u540E\uFF0C\u9700\u8981\u91CD\u542F Codex \u5BF9\u8BDD\uFF0C\u5728\u5F39\u51FA\u7684 hooks \u786E\u8BA4\u754C\u9762\u9009\u62E9\u63A5\u6536\u6240\u6709 hooks(\u94A9\u5B50)\u9009\u9879\u3002",
+  "\u5982\u679C\u4F7F\u7528\u7684\u662F Codex App \u684C\u9762\u7248\uFF0C\u64CD\u4F5C\u8DEF\u5F84\u662F\uFF1A\u5DE6\u4E0B\u89D2\u70B9\u51FB\u7528\u6237\u540D \u2192 \u70B9\u51FB\u8BBE\u7F6E \u2192 \u70B9\u51FB\u4FA7\u8FB9\u680F\u7684 Hooks\uFF08\u94A9\u5B50\uFF09\u2192 \u70B9\u51FB\u7528\u6237\u914D\u7F6E\uFF0C\u4FE1\u4EFB UserPromptSubmit \u548C SessionStart \u91CC\u7684 aliyunrds/ctxdb \u94A9\u5B50\u3002"
+].join("\n");
 function parseAgent(args) {
   const raw = args.flags.agent;
   if (raw === void 0) return "default";
@@ -1900,8 +2142,36 @@ async function setup(args) {
     process.stdout.write(HELP);
     return 0;
   }
-  const agent = parseAgent(args);
   const json = !!args.flags.json;
+  const all = args.flags.all === true;
+  if (all && args.flags.agent !== void 0) {
+    process.stderr.write("cannot use --all and --agent together\n");
+    return 2;
+  }
+  if (all) {
+    const result2 = await runSetupAll({
+      apiKey: typeof args.flags["api-key"] === "string" ? args.flags["api-key"] : void 0,
+      baseUrl: typeof args.flags["base-url"] === "string" ? args.flags["base-url"] : void 0,
+      userId: typeof args.flags["user-id"] === "string" ? args.flags["user-id"] : void 0,
+      installSkill: !args.flags["no-install-skill"],
+      validate: !args.flags["no-validate"]
+    });
+    printResult(result2, json);
+    if (!json && result2.hints) {
+      for (const hint of result2.hints) process.stderr.write(`
+${hint}
+`);
+    }
+    if (!json && result2.agents.codex?.ok) {
+      process.stderr.write(
+        `
+${dim(CODEX_HOOKS_TRUST_REMINDER)}
+`
+      );
+    }
+    return result2.ok ? 0 : 1;
+  }
+  const agent = parseAgent(args);
   if (agent === "default" && !json && !configuredAgents().includes("default")) {
     process.stderr.write(
       `hint: creating CLI-only "default" agent (no hooks/skills). Use --agent <claude|qoder|qoderwork|codex|opencode|hermes> for full setup.
@@ -1925,7 +2195,7 @@ ${h}
   if (!json && agent === "codex" && result.ok) {
     process.stderr.write(
       `
-${dim("codex hooks \u914D\u7F6E\u540E\uFF0C\u9700\u8981\u91CD\u542F Codex \u5BF9\u8BDD\uFF0C\u5728\u5F39\u51FA\u7684 hooks \u786E\u8BA4\u754C\u9762\u9009\u62E9\u63A5\u6536\u6240\u6709 hooks(\u94A9\u5B50)\u9009\u9879")}
+${dim(CODEX_HOOKS_TRUST_REMINDER)}
 `
     );
   }
@@ -1996,118 +2266,6 @@ ${h}
   return result.ok ? 0 : 1;
 }
 
-// src/lib/self-update.ts
-import { spawnSync } from "child_process";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import { dirname as dirname2 } from "path";
-import semver from "semver";
-var PACKAGE_NAME = "@aliyunrds/ctxdb";
-var NPM_VIEW_TIMEOUT_MS = 1e4;
-function npmCommand(platform = process.platform) {
-  return platform === "win32" ? "npm.cmd" : "npm";
-}
-function ctxdbCommand(platform = process.platform) {
-  return platform === "win32" ? "ctxdb.cmd" : "ctxdb";
-}
-function detectInstallMethod() {
-  const dir = dirname2(fileURLToPath2(import.meta.url));
-  return dir.includes("/node_modules/") || dir.includes("\\node_modules\\") ? "npm" : "unknown";
-}
-function checkLatestVersion(currentVersion) {
-  const result = spawnSync(npmCommand(), ["view", PACKAGE_NAME, "version"], {
-    encoding: "utf-8",
-    timeout: NPM_VIEW_TIMEOUT_MS,
-    stdio: ["ignore", "pipe", "pipe"],
-    shell: process.platform === "win32"
-  });
-  if (result.status !== 0 || !result.stdout?.trim()) {
-    return {
-      latest: null,
-      current: currentVersion,
-      isNewer: false,
-      error: spawnFailureMessage(result, "npm view")
-    };
-  }
-  const latest = result.stdout.trim();
-  return {
-    latest,
-    current: currentVersion,
-    isNewer: isNewerVersion(latest, currentVersion)
-  };
-}
-function spawnFailureMessage(result, commandLabel) {
-  const stderr = result.stderr?.toString().trim();
-  if (stderr) return stderr;
-  if (result.error) return `${commandLabel} failed: ${result.error.message}`;
-  if (result.signal) return `${commandLabel} terminated by signal ${result.signal}`;
-  return `${commandLabel} exited with code ${result.status}`;
-}
-function isNewerVersion(candidate, current) {
-  const candidateVersion = semver.valid(candidate);
-  const currentVersion = semver.valid(current);
-  return Boolean(
-    candidateVersion && currentVersion && semver.gt(candidateVersion, currentVersion)
-  );
-}
-function runSelfUpdate(currentVersion, passthroughArgs = [], options = {}) {
-  const method = options.installMethod ?? detectInstallMethod();
-  if (method !== "npm") {
-    return {
-      ok: false,
-      updated: false,
-      fromVersion: currentVersion,
-      error: "ctxdb was not installed via npm. Update manually with your package manager."
-    };
-  }
-  const check = checkLatestVersion(currentVersion);
-  if (check.error) {
-    return {
-      ok: false,
-      updated: false,
-      fromVersion: currentVersion,
-      error: `npm view failed: ${check.error}`
-    };
-  }
-  if (!check.isNewer) {
-    process.stderr.write(
-      `ctxdb: package already up to date (current v${currentVersion}, latest v${check.latest})
-`
-    );
-    return { ok: true, updated: false, fromVersion: currentVersion };
-  }
-  process.stderr.write(`ctxdb: updating ${PACKAGE_NAME} v${currentVersion} \u2192 v${check.latest}...
-`);
-  const install = spawnSync(npmCommand(), ["install", "-g", `${PACKAGE_NAME}@${check.latest}`], {
-    stdio: "inherit",
-    encoding: "utf-8",
-    shell: process.platform === "win32"
-  });
-  if (install.status !== 0) {
-    return {
-      ok: false,
-      updated: false,
-      fromVersion: currentVersion,
-      error: spawnFailureMessage(install, "npm install -g")
-    };
-  }
-  process.stderr.write(`ctxdb: package updated to v${check.latest}, running setup...
-`);
-  const setupArgs = ["update", "--no-self-update", ...passthroughArgs];
-  const refresh = spawnSync(ctxdbCommand(), setupArgs, {
-    stdio: "inherit",
-    encoding: "utf-8",
-    shell: process.platform === "win32"
-  });
-  return {
-    ok: refresh.status === 0,
-    updated: true,
-    fromVersion: currentVersion,
-    toVersion: check.latest,
-    error: refresh.status !== 0 ? spawnFailureMessage(refresh, "ctxdb setup") : void 0,
-    failureHandled: refresh.status !== null && refresh.status !== 0
-  };
-}
-
 // src/cli/upgrade.ts
 var HELP3 = `ctxdb upgrade \u2014 refresh skills + hooks
 
@@ -2396,18 +2554,28 @@ function parseMetadataFlags(raw) {
 }
 
 // src/cli/kb-cli.ts
+var UPLOAD_TEXT_USAGE = "usage: ctxdb kb upload-text <kb-name> <doc-name> --text=<body> [--file-path=<server-logical-path>] [--wait|--no-wait]";
+var UPLOAD_FILE_USAGE = "usage: ctxdb kb upload-file <kb-name> <local-path> [--doc-name=...] [--file-path=<server-logical-path>] [--wait|--no-wait]";
+function shouldWaitForIngest(args, usage) {
+  const waitRequested = args.flags.wait !== void 0;
+  const noWaitRequested = args.flags["no-wait"] !== void 0;
+  if (waitRequested && noWaitRequested) {
+    fail(`cannot use --wait and --no-wait together
+${usage}`, 2);
+  }
+  return waitRequested;
+}
 async function kbUploadText(args) {
+  const shouldWait = shouldWaitForIngest(args, UPLOAD_TEXT_USAGE);
   const [kbName, docName] = args.positional;
   const text = args.flags["text"];
   if (!kbName || !docName || typeof text !== "string") {
-    fail(
-      "usage: ctxdb kb upload-text <kb-name> <doc-name> --text=<body> [--file-path=<server-logical-path>] [--no-wait]"
-    );
+    fail(UPLOAD_TEXT_USAGE);
   }
   const ctx = buildContext(args);
   const filePath = typeof args.flags["file-path"] === "string" ? args.flags["file-path"] : void 0;
   const doc = await uploadText(ctx.client, kbName, docName, text, "text/plain", filePath);
-  if (args.flags["no-wait"]) {
+  if (!shouldWait) {
     printResult({ document: doc }, !!args.flags.json);
     return 0;
   }
@@ -2418,19 +2586,18 @@ async function kbUploadText(args) {
   return 0;
 }
 async function kbUploadFile(args) {
+  const shouldWait = shouldWaitForIngest(args, UPLOAD_FILE_USAGE);
   const [kbName, localPath] = args.positional;
   if (!kbName || !localPath) {
-    fail(
-      "usage: ctxdb kb upload-file <kb-name> <local-path> [--doc-name=...] [--file-path=<server-logical-path>] [--no-wait]"
-    );
+    fail(UPLOAD_FILE_USAGE);
   }
   const ctx = buildContext(args);
   const doc = await uploadFile(ctx.client, kbName, localPath, {
     docName: typeof args.flags["doc-name"] === "string" ? args.flags["doc-name"] : void 0,
     filePath: typeof args.flags["file-path"] === "string" ? args.flags["file-path"] : void 0,
-    timeoutMs: DEFAULT_FILE_INGEST_TIMEOUT_MS
+    timeoutMs: DEFAULT_FILE_UPLOAD_TIMEOUT_MS
   });
-  if (args.flags["no-wait"]) {
+  if (!shouldWait) {
     printResult({ document: doc }, !!args.flags.json);
     return 0;
   }
@@ -2510,7 +2677,7 @@ USAGE
   ctxdb <command> [args] [--flags]
 
 COMMANDS
-  setup [--agent <qoder|qoderwork|codex|claude|opencode|hermes>]
+  setup [--agent <qoder|qoderwork|codex|claude|opencode|hermes> | --all]
         [--api-key=K] [--base-url=URL] [--user-id=ID]
         [--no-install-skill] [--no-validate] [--json]
                                  Without --agent \u2192 writes agents.default (CLI-only, no hooks/skills)
@@ -2521,8 +2688,12 @@ COMMANDS
                                  OpenCode   \u2192 writes agents.opencode config + ~/.config/opencode/plugins/ctxdb.ts shim + skill
                                  Hermes     \u2192 writes agents.hermes config + ~/.hermes/config.yaml pre/post_llm_call hooks + skill
                                               Approve pre_llm_call + post_llm_call with \`hermes --accept-hooks chat\`
-                                              (opens interactive chat; exit after Hermes starts)
-  status [--agent <name>] [--json]
+                                              (exit chat, rerun setup, then restart any running Hermes CLI/gateway)
+                                 --all       \u2192 detects and configures every setup-compatible built-in Agent
+  status [--agent <name> | --all] [--json]
+                                 Inspect configuration, connectivity, and integration health.
+                                 --all inspects the same detected Agent set as setup --all.
+                                 Rerun setup to add/repair an Agent or replace its API key.
   ping [--agent <name>] [--json]
   uninstall [--agent <name>] [--purge-config] [--purge-logs] [--purge-all] [--json]
   teardown                       (alias for uninstall)
@@ -2551,9 +2722,12 @@ COMMANDS
 
   kb create <kb-name> [--description=<desc>] [--agent=<name>]
   kb upload-text <kb-name> <doc-name> --text=<body> [--agent=<name>]
-                 [--file-path=<server-logical-path>] [--no-wait]
+                 [--file-path=<server-logical-path>] [--wait|--no-wait]
   kb upload-file <kb-name> <local-path> [--agent=<name>] [--doc-name=...]
-                 [--file-path=<server-logical-path>] [--no-wait]
+                 [--file-path=<server-logical-path>] [--wait|--no-wait]
+                                 Uploads return immediately by default.
+                                 --wait polls for terminal ingest status.
+                                 --no-wait is a compatibility alias for the default.
   kb list [--agent=<name>]
   kb documents-list <kb-name> [--agent=<name>]
   kb document-get <kb-name> <doc-id> [--agent=<name>]
@@ -2580,6 +2754,10 @@ ENV VARS (override selected ~/.ctxdb/ctxdb.json agent config):
   CTXDB_AGENT  CTXDB_API_KEY  CTXDB_BASE_URL  CTXDB_USER_ID
   CTXDB_AGENT_ID  CTXDB_APP_ID
 
+UPDATE CHECK ENV VARS:
+  CTXDB_DISABLE_UPDATE_CHECK=1
+                              Disable background version checks and hints.
+
 HOOK ENV VARS:
   CTXDB_SKIP_HOOKS=TRUE       Hook/plugin entrypoints exit immediately.
                               Direct ctxdb CLI commands are unchanged.
@@ -2616,7 +2794,7 @@ var ROUTES = {
     search: kbSearch
   }
 };
-async function main(argv = process.argv.slice(2)) {
+async function dispatch(argv) {
   if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
     process.stdout.write(HELP5);
     return 0;
@@ -2660,6 +2838,15 @@ async function main(argv = process.argv.slice(2)) {
   }
   return Promise.resolve(handler(parseArgs(subRest)));
 }
+async function main(argv = process.argv.slice(2)) {
+  const notification = beginUpdateNotification(argv, {
+    currentVersion: PACKAGE_VERSION,
+    workerPath: fileURLToPath2(new URL("../workers/version-check.js", import.meta.url))
+  });
+  const code = await dispatch(argv);
+  completeUpdateNotification(notification, code);
+  return code;
+}
 main().then(
   (code) => {
     if (typeof code === "number") process.exitCode = code;