@aliyunrds/ctxdb 0.0.5 → 0.0.8-beta.1

package/README.md

@@ -1,6 +1,6 @@
 # @aliyunrds/ctxdb
 
-Unified access layer for RDS ContextDatabase. One `ctxdb` CLI (memory + KB ops), one `setup --agent <…>` installer, per-agent SKILL.md — supports multiple code agents from a single package.
+Unified access layer for RDS ContextDatabase. One `ctxdb` CLI (memory + KB ops), one `setup` installer (`--agent <…>` for hooks/skills, bare for CLI-only), per-agent SKILL.md — supports multiple code agents from a single package.
 
 | Agent | Hooks | Skill install path | Skill style |
 |---|---|---|---|
@@ -59,7 +59,7 @@ Implementation note: qoder/Claude consume the JSON `hookSpecificOutput.additiona
 
 See `ctxdb --help`.
 
-`setup` mandates `--agent <qoder|codex|claude>` because it mutates that agent's hooks/skills. Memory and KB commands also accept `--agent <name>` so agents use their own config section; when omitted, `CTXDB_AGENT` wins, otherwise `qoder` is used for backward compatibility. `uninstall` without `--agent` loops every supported agent; with `--agent <name>` it targets just that one. `teardown` is an alias for `uninstall`.
+`setup` without `--agent` writes `agents.default` in `~/.ctxdb/ctxdb.json` (CLI-only, no hooks or skills); with `--agent <qoder|codex|claude>` it writes agent config and installs hooks + skills for that harness. Memory and KB commands also accept `--agent <name>` so agents use their own config section; when omitted, `CTXDB_AGENT` env wins, otherwise `agents.default` is used. `uninstall` without `--agent` loops every supported agent; with `--agent <name>` it targets just that one. `teardown` is an alias for `uninstall`.
 
 `memory add … --no-infer` stores the text verbatim (skips server-side LLM
 fact-extraction). Use it when the user explicitly asks for a verbatim
@@ -100,7 +100,7 @@ Lives at `~/.ctxdb/ctxdb.json` (co-located with logs at `~/.ctxdb/logs/`). Schem
 }
 ```
 
-Agent selection is driven by `--agent <qoder|codex|claude>` on every CLI invocation, falling back to `CTXDB_AGENT` env, then to `qoder`. There is no `default_agent` field — older installs that have one written get it dropped on the next save.
+Agent selection is driven by `--agent <qoder|codex|claude|default>` on every CLI invocation, falling back to `CTXDB_AGENT` env, then to `default`. There is no `default_agent` field — older installs that have one written get it dropped on the next save.
 
 Field reference:
 

package/dist/{chunk-HAUTENYD.js → chunk-6S5RJYBC.js}

@@ -1,7 +1,4 @@
 #!/usr/bin/env node
-import {
-  NotFoundError
-} from "./chunk-QSSNPN3M.js";
 
 // src/lib/kb.ts
 import { readFileSync, existsSync, statSync } from "fs";
@@ -12,16 +9,6 @@ var KB_COLLECTION = "/v1/knowledge/knowledge_bases";
 var DOCUMENTS = "/v1/knowledge/documents";
 var FILES = "/v1/knowledge/files";
 var DOCUMENT_DETAIL = "/v1/knowledge/documents/detail";
-async function tryNewThenLegacy(newPath, newCall, legacyCall) {
-  try {
-    return await newCall();
-  } catch (err) {
-    if (err instanceof NotFoundError && err.path === newPath) {
-      return legacyCall();
-    }
-    throw err;
-  }
-}
 var DEFAULT_POLL_INTERVAL_MS = 1500;
 var DEFAULT_INGEST_TIMEOUT_MS = 3e4;
 var DEFAULT_FILE_INGEST_TIMEOUT_MS = 6e4;
@@ -48,40 +35,20 @@ async function listKnowledgeBases(client) {
   }
   return [];
 }
-async function findKb(client, kbNameOrId) {
-  for (const kb of await listKnowledgeBases(client)) {
-    if (!kb || typeof kb !== "object") continue;
-    if (kb.name === kbNameOrId || kb.id === kbNameOrId) return kb;
-  }
-  return null;
-}
 async function createKb(client, kbName, description = "") {
   return client.postJson(KB_COLLECTION, { name: kbName, description: description || "" });
 }
-async function findOrCreateKb(client, kbName, description = "") {
-  const existing = await findKb(client, kbName);
-  if (existing) return { kb: existing, created: false };
-  const created = await createKb(client, kbName, description);
-  return { kb: created, created: true };
-}
-async function uploadText(client, kbId, docName, text, mimeType = "text/plain", filePath) {
+async function uploadText(client, kbName, docName, text, mimeType = "text/plain", filePath) {
   const body = {
-    knowledge_base_id: kbId,
+    knowledge_base_name: kbName,
     name: docName,
     text,
     mime_type: mimeType
   };
   if (filePath !== void 0 && filePath !== "") body.file_path = filePath;
-  return tryNewThenLegacy(
-    DOCUMENTS,
-    () => client.postJson(DOCUMENTS, body),
-    () => {
-      const { knowledge_base_id: _drop, ...legacyBody } = body;
-      return client.postJson(`${KB_COLLECTION}/${encodeURIComponent(kbId)}/documents`, legacyBody);
-    }
-  );
+  return client.postJson(DOCUMENTS, body);
 }
-async function uploadFile(client, kbId, localPath, options = {}) {
+async function uploadFile(client, kbName, localPath, options = {}) {
   const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
   const expanded = expandHome(localPath);
   if (!existsSync(expanded)) throw new Error(`file not found: ${expanded}`);
@@ -97,30 +64,17 @@ async function uploadFile(client, kbId, localPath, options = {}) {
   const content = readFileSync(expanded);
   const mime = guessMime(expanded);
   const fields = {
-    knowledge_base_id: kbId,
+    knowledge_base_name: kbName,
     name: docName
   };
   if (options.filePath !== void 0 && options.filePath !== "") {
     fields.file_path = options.filePath;
   }
-  const uploadOpts = { timeoutMs: options.timeoutMs };
-  return tryNewThenLegacy(
+  return client.postMultipart(
     FILES,
-    () => client.postMultipart(
-      FILES,
-      fields,
-      { file: { filename, content, mimeType: mime } },
-      uploadOpts
-    ),
-    () => {
-      const { knowledge_base_id: _drop, ...legacyFields } = fields;
-      return client.postMultipart(
-        `${KB_COLLECTION}/${encodeURIComponent(kbId)}/files`,
-        legacyFields,
-        { file: { filename, content, mimeType: mime } },
-        uploadOpts
-      );
-    }
+    fields,
+    { file: { filename, content, mimeType: mime } },
+    { timeoutMs: options.timeoutMs }
   );
 }
 function guessMime(path) {
@@ -128,24 +82,14 @@ function guessMime(path) {
   if (ext in MIME_BY_EXT) return MIME_BY_EXT[ext];
   return "application/octet-stream";
 }
-async function getDocument(client, kbId, docId) {
-  return tryNewThenLegacy(
-    DOCUMENT_DETAIL,
-    () => client.get(DOCUMENT_DETAIL, {
-      knowledge_base_id: kbId,
-      document_id: docId
-    }),
-    () => client.get(
-      `${KB_COLLECTION}/${encodeURIComponent(kbId)}/documents/${encodeURIComponent(docId)}`
-    )
-  );
+async function getDocument(client, kbName, docId) {
+  return client.get(DOCUMENT_DETAIL, {
+    knowledge_base_name: kbName,
+    document_id: docId
+  });
 }
-async function listDocuments(client, kbId) {
-  const resp = await tryNewThenLegacy(
-    DOCUMENTS,
-    () => client.get(DOCUMENTS, { knowledge_base_id: kbId }),
-    () => client.get(`${KB_COLLECTION}/${encodeURIComponent(kbId)}/documents`)
-  );
+async function listDocuments(client, kbName) {
+  const resp = await client.get(DOCUMENTS, { knowledge_base_name: kbName });
   if (Array.isArray(resp)) return resp;
   if (resp && typeof resp === "object") {
     const o = resp;
@@ -153,13 +97,13 @@ async function listDocuments(client, kbId) {
   }
   return [];
 }
-async function pollIngest(client, kbId, docId, options = {}) {
+async function pollIngest(client, kbName, docId, options = {}) {
   const timeoutMs = options.timeoutMs ?? DEFAULT_INGEST_TIMEOUT_MS;
   const intervalMs = options.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
   const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   const now = options.now ?? (() => performance.now());
   const deadline = now() + timeoutMs;
-  let doc = await getDocument(client, kbId, docId);
+  let doc = await getDocument(client, kbName, docId);
   let timedOut = false;
   while (ingestInFlight(doc)) {
     if (now() >= deadline) {
@@ -168,7 +112,7 @@ async function pollIngest(client, kbId, docId, options = {}) {
     }
     await sleep(intervalMs);
     try {
-      doc = await getDocument(client, kbId, docId);
+      doc = await getDocument(client, kbName, docId);
     } catch {
       break;
     }
@@ -241,8 +185,7 @@ export {
   DEFAULT_INGEST_TIMEOUT_MS,
   DEFAULT_FILE_INGEST_TIMEOUT_MS,
   listKnowledgeBases,
-  findKb,
-  findOrCreateKb,
+  createKb,
   uploadText,
   uploadFile,
   getDocument,

package/dist/{chunk-7NOXAU2X.js → chunk-C62I23HL.js}

@@ -1,7 +1,15 @@
 #!/usr/bin/env node
+import {
+  listKnowledgeBases
+} from "./chunk-6S5RJYBC.js";
+import {
+  isConnectionError,
+  resetCircuit,
+  tripCircuit
+} from "./chunk-KEQMJ6IO.js";
 import {
   CtxdbError
-} from "./chunk-QSSNPN3M.js";
+} from "./chunk-U3T5O6NX.js";
 
 // src/lib/recall-orchestrator.ts
 import {
@@ -83,7 +91,7 @@ var EMPTY = {
   memoryCount: 0,
   knowledgeChunkCount: 0
 };
-async function recallTurn(prompt, cfg, client) {
+async function recallTurn(prompt, cfg, client, agent = "default") {
   if (!prompt.trim()) return { ...EMPTY, reason: "empty_prompt" };
   if (!cfg.apiKey || !cfg.baseUrl) {
     return { ...EMPTY, reason: "config_incomplete" };
@@ -101,8 +109,10 @@ async function recallTurn(prompt, cfg, client) {
   let resp;
   try {
     resp = await client.postJson("/v3/memories/search/", body);
+    resetCircuit(agent);
   } catch (err) {
     const msg = err instanceof CtxdbError ? err.message : String(err);
+    if (isConnectionError(err)) tripCircuit(agent, cfg.baseUrl, msg);
     return { ...EMPTY, reason: `http_error: ${msg}` };
   }
   if (!resp || typeof resp !== "object") {
@@ -131,6 +141,34 @@ async function recallTurn(prompt, cfg, client) {
   };
 }
 
+// src/lib/kb-catalog.ts
+function sanitizeKeyEntities(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const e of raw) {
+    if (typeof e !== "string") continue;
+    const cleaned = e.replace(/\s+/g, " ").trim();
+    if (cleaned.length > 0) out.push(cleaned);
+  }
+  return out;
+}
+async function fetchKbCatalogBlock(client, agent) {
+  const kbs = await listKnowledgeBases(client);
+  const active = kbs.filter((kb) => kb.status === "active");
+  if (active.length === 0) return "";
+  const lines = active.map((kb) => {
+    const ents = sanitizeKeyEntities(kb.key_entities);
+    return ents.length > 0 ? `\xB7 ${kb.name}: ${ents.join(", ")}` : `\xB7 ${kb.name}`;
+  });
+  return [
+    "<available-knowledge-bases>",
+    `When you identify that relevant information may exist in the knowledge bases below, you MUST run \`ctxdb kb search "<query>" --kb=<name> --agent=${agent}\` with targeted keywords after initial analysis to supplement and correct your approach. Knowledge bases:`,
+    ...lines,
+    "</available-knowledge-bases>"
+  ].join("\n");
+}
+
 export {
-  recallTurn
+  recallTurn,
+  fetchKbCatalogBlock
 };

package/dist/chunk-KEQMJ6IO.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import {
+  configDir
+} from "./chunk-U3T5O6NX.js";
+
+// src/lib/circuit.ts
+import { statSync, writeFileSync, unlinkSync, mkdirSync, readdirSync, readFileSync } from "fs";
+import { join } from "path";
+var CIRCUIT_DIR_NAME = "circuit";
+var COOLDOWN_MS = 6e4;
+function circuitDir() {
+  const dir = join(configDir(), CIRCUIT_DIR_NAME);
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch {
+  }
+  return dir;
+}
+function circuitPath(agent) {
+  return join(circuitDir(), `${agent}.circuit`);
+}
+function isCircuitOpen(agent, baseUrl) {
+  const own = checkFile(circuitPath(agent), baseUrl);
+  if (own) return true;
+  try {
+    for (const f of readdirSync(circuitDir())) {
+      if (!f.endsWith(".circuit") || f === `${agent}.circuit`) continue;
+      if (checkFile(join(circuitDir(), f), baseUrl)) return true;
+    }
+  } catch {
+  }
+  return false;
+}
+function checkFile(path, baseUrl) {
+  try {
+    const st = statSync(path);
+    if (Date.now() - st.mtimeMs > COOLDOWN_MS) return false;
+    const line = readFileSync(path, "utf-8").split("\n")[0] || "";
+    return line.startsWith(baseUrl);
+  } catch {
+    return false;
+  }
+}
+function tripCircuit(agent, baseUrl, reason) {
+  try {
+    writeFileSync(circuitPath(agent), `${baseUrl}|${reason}|${(/* @__PURE__ */ new Date()).toISOString()}
+`);
+  } catch {
+  }
+}
+function resetCircuit(agent) {
+  try {
+    unlinkSync(circuitPath(agent));
+  } catch {
+  }
+}
+function isConnectionError(err) {
+  if (!err || typeof err !== "object") return false;
+  if (err.name === "CtxdbHttpError") return false;
+  const msg = err.message ?? "";
+  return /timeout|ECONNREFUSED|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH|network error/i.test(msg);
+}
+
+export {
+  isCircuitOpen,
+  tripCircuit,
+  resetCircuit,
+  isConnectionError
+};

package/dist/{chunk-QSSNPN3M.js → chunk-U3T5O6NX.js}

@@ -16,7 +16,14 @@ function isDebug() {
 }
 function debug(tag, msg, data) {
   if (_enabled !== true) return;
-  const ts = (/* @__PURE__ */ new Date()).toISOString();
+  const now = /* @__PURE__ */ new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  const ms = String(now.getMilliseconds()).padStart(3, "0");
+  const tz = -now.getTimezoneOffset();
+  const tzSign = tz >= 0 ? "+" : "-";
+  const tzH = pad(Math.floor(Math.abs(tz) / 60));
+  const tzM = pad(Math.abs(tz) % 60);
+  const ts = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}T${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}.${ms}${tzSign}${tzH}:${tzM}`;
   let line = `${ts} [${tag}] ${msg}`;
   if (data !== void 0) {
     const s = typeof data === "string" ? data : JSON.stringify(data, null, 2);
@@ -251,9 +258,13 @@ function extractErrorDetail(text, fallback) {
 import { homedir as homedir2 } from "os";
 import { join as join3 } from "path";
 var SUPPORTED_AGENTS = ["qoder", "codex", "claude"];
-function isAgent(v) {
+function isBuiltinAgent(v) {
   return typeof v === "string" && SUPPORTED_AGENTS.includes(v);
 }
+function isAgentSlug(v) {
+  return v === "default" || isBuiltinAgent(v);
+}
+var isAgent = isAgentSlug;
 function agentHomeDir(agent) {
   switch (agent) {
     case "qoder":
@@ -265,17 +276,17 @@ function agentHomeDir(agent) {
   }
 }
 function agentFromEnv(env = process.env) {
-  return isAgent(env.CTXDB_AGENT) ? env.CTXDB_AGENT : "qoder";
+  return isAgentSlug(env.CTXDB_AGENT) ? env.CTXDB_AGENT : "default";
 }
 function agentFromArgvWithFallback(argv = process.argv.slice(2), env = process.env) {
   for (let i = 0; i < argv.length; i++) {
     const tok = argv[i];
-    if (tok === "--agent" && isAgent(argv[i + 1])) {
+    if (tok === "--agent" && isAgentSlug(argv[i + 1])) {
       return { agent: argv[i + 1], fellBack: false };
     }
     if (tok.startsWith("--agent=")) {
       const raw = tok.slice("--agent=".length);
-      if (isAgent(raw)) return { agent: raw, fellBack: false };
+      if (isAgentSlug(raw)) return { agent: raw, fellBack: false };
     }
   }
   return { agent: agentFromEnv(env), fellBack: true };
@@ -289,16 +300,20 @@ function defaultConfigPath() {
   return join4(homedir3(), ".ctxdb", "ctxdb.json");
 }
 var DEFAULT_CONFIG_PATH = join4(homedir3(), ".ctxdb", "ctxdb.json");
+function configDir() {
+  return join4(homedir3(), ".ctxdb");
+}
 var DEFAULT_BASE_URL = "https://context-database.aliyuncs.com";
 var DEFAULT_USER_ID = "default";
 var DEFAULT_TOP_K = 5;
 var DEFAULT_THRESHOLD = 0.4;
 var DEFAULT_KNOWLEDGE_TOP_K = 6;
+var DEFAULT_KB_CATALOG_INJECTION = "session_start";
 function isComplete(cfg) {
   return Boolean(cfg.apiKey && cfg.baseUrl);
 }
-function resolveConfigAgent(options = {}) {
-  if (isAgent(options.agent)) return options.agent;
+function resolveConfigAgent(options = {}, preloadedRaw) {
+  if (isAgentSlug(options.agent)) return options.agent;
   return agentFromEnv(options.env);
 }
 function coerceInt(v, fallback) {
@@ -316,6 +331,12 @@ function coerceBool(v, fallback) {
   if (v === void 0 || v === null) return fallback;
   return Boolean(v);
 }
+function coerceKbCatalogInjection(v) {
+  if (v === "session_start" || v === "user_prompt_submit" || v === "off") {
+    return v;
+  }
+  return DEFAULT_KB_CATALOG_INJECTION;
+}
 function readRaw(path) {
   if (!existsSync(path)) return {};
   try {
@@ -353,7 +374,8 @@ function configFromDisk(raw) {
     topK: coerceInt(raw.top_k, DEFAULT_TOP_K),
     threshold: coerceFloat(raw.threshold, DEFAULT_THRESHOLD),
     knowledgeTopK: coerceInt(raw.knowledge_top_k, DEFAULT_KNOWLEDGE_TOP_K),
-    debug: coerceBool(raw.debug, false)
+    debug: coerceBool(raw.debug, false),
+    kbCatalogInjection: coerceKbCatalogInjection(raw.kb_catalog_injection)
   };
 }
 function applyEnv(cfg, env) {
@@ -365,8 +387,8 @@ function applyEnv(cfg, env) {
 function load(options = {}) {
   const path = options.path ?? defaultConfigPath();
   const env = options.env ?? process.env;
-  const agent = resolveConfigAgent({ agent: options.agent, env });
   const raw = readRaw(path);
+  const agent = resolveConfigAgent({ ...options, path, env }, raw);
   if (!isV2Schema(raw)) {
     try {
       process.stderr.write(
@@ -377,7 +399,18 @@ function load(options = {}) {
     }
     return applyEnv(configFromDisk({}), env);
   }
-  return applyEnv(configFromDisk(agentRawFromFile(raw, agent)), env);
+  const agentRaw = agentRawFromFile(raw, agent);
+  if (agent !== "default") {
+    const defaultRaw = agentRawFromFile(raw, "default");
+    if (Object.keys(defaultRaw).length > 0) {
+      for (const [k, v] of Object.entries(defaultRaw)) {
+        if (!(k in agentRaw)) {
+          agentRaw[k] = v;
+        }
+      }
+    }
+  }
+  return applyEnv(configFromDisk(agentRaw), env);
 }
 function configToDisk(cfg) {
   return {
@@ -391,7 +424,8 @@ function configToDisk(cfg) {
     top_k: cfg.topK,
     threshold: cfg.threshold,
     knowledge_top_k: cfg.knowledgeTopK,
-    debug: cfg.debug
+    debug: cfg.debug,
+    kb_catalog_injection: cfg.kbCatalogInjection
   };
 }
 function removeAgent(agent, path, options = {}) {
@@ -446,23 +480,32 @@ function configuredAgents(path) {
   if (!isV2Schema(raw) || !raw.agents || typeof raw.agents !== "object") return [];
   return Object.keys(raw.agents).filter(isAgent);
 }
+function writeInstalledPkgVersion(version, path) {
+  const target = path ?? defaultConfigPath();
+  const raw = readRaw(target);
+  const updated = { ...raw, installed_pkg_version: version };
+  mkdirSync2(dirname3(target), { recursive: true });
+  writeFileSync(target, JSON.stringify(updated, null, 2) + "\n", "utf-8");
+}
 
 export {
   setDebug,
   debug,
   CtxdbError,
-  NotFoundError,
   HttpClient,
   SUPPORTED_AGENTS,
-  isAgent,
+  isBuiltinAgent,
+  isAgentSlug,
   agentHomeDir,
   agentFromEnv,
   agentFromArgvWithFallback,
+  configDir,
   DEFAULT_BASE_URL,
   DEFAULT_USER_ID,
   isComplete,
   load,
   removeAgent,
   save,
-  configuredAgents
+  configuredAgents,
+  writeInstalledPkgVersion
 };