@aliyunrds/ctxdb 1.0.8-beta.0 → 1.0.8-beta.1

package/dist/{chunk-AAZLOCVB.js → chunk-KYW76CL7.js}

@@ -3,1070 +3,1067 @@ import {
   DISTRIBUTION_MANIFEST
 } from "./chunk-R67JELM7.js";
 
-// src/lib/logger.ts
-import { appendFileSync, mkdirSync } from "fs";
+// src/lib/agents.ts
 import { homedir } from "os";
-import { dirname, join } from "path";
-function logPath() {
-  return join(homedir(), ".ctxdb", "logs", "ctxdb.log");
+import { delimiter, join, sep } from "path";
+import { accessSync, constants, existsSync, statSync } from "fs";
+var SUPPORTED_AGENTS = ["qoder", "qoderwork", "qwenwork", "codex", "claude", "opencode", "hermes", "workbuddy"];
+var SUPPORTED_AGENT_CHOICES = SUPPORTED_AGENTS.join("|");
+var AGENT_CHOICES = [...SUPPORTED_AGENTS, "default"].join("|");
+function isBuiltinAgent(v) {
+  return typeof v === "string" && SUPPORTED_AGENTS.includes(v);
 }
-var _enabled = null;
-function setDebug(enabled) {
-  _enabled = enabled;
+function isAgentSlug(v) {
+  return v === "default" || isBuiltinAgent(v);
 }
-function isDebug() {
-  return _enabled === true;
+var isAgent = isAgentSlug;
+function agentHomeDir(agent, home = homedir()) {
+  switch (agent) {
+    case "qoder":
+      return join(home, ".qoder");
+    case "qoderwork":
+      return join(home, ".qoderwork");
+    case "qwenwork":
+      return join(home, ".qwenwork");
+    case "codex":
+      return join(home, ".codex");
+    case "claude":
+      return join(home, ".claude");
+    case "opencode":
+      return join(home, ".config", "opencode");
+    case "hermes":
+      return join(home, ".hermes");
+    case "workbuddy":
+      return join(home, ".workbuddy");
+  }
 }
-function debug(tag, msg, data) {
-  if (_enabled !== true) return;
-  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);
-    line += `
-${s}`;
+var AGENT_VARIANT_HOMES = {
+  qoder: [".qoder-cn"],
+  qoderwork: [".qoderworkcn"],
+  qwenwork: [".qwenworkcn"]
+};
+function agentHomeDirs(agent, home = homedir()) {
+  const primary = agentHomeDir(agent, home);
+  const variants = (AGENT_VARIANT_HOMES[agent] ?? []).map(
+    (name) => join(home, name)
+  );
+  return [primary, ...variants];
+}
+function agentPlatformSupport(agent, platform = process.platform) {
+  if (agent === "hermes" && platform === "win32") {
+    return {
+      supported: false,
+      detail: "Hermes integration currently supports macOS/Linux only; Windows Hermes is not yet supported."
+    };
   }
-  line += "\n";
-  const p = logPath();
+  return { supported: true, detail: `${agent} is supported on ${platform}.` };
+}
+function inspectAgentHomes(agent, options = {}) {
+  const exists = options.exists ?? existsSyncAdapter;
+  const candidates = agentHomeDirs(agent, options.home);
+  const existing = candidates.filter(exists);
+  return { exists: existing.length > 0, existing, candidates };
+}
+function existsSyncAdapter(path) {
   try {
-    mkdirSync(dirname(p), { recursive: true });
-    appendFileSync(p, line, "utf-8");
+    return existsSync(path);
   } catch {
+    return false;
   }
 }
-
-// src/lib/package-version.ts
-import { readFileSync } from "fs";
-import { dirname as dirname2, join as join2 } from "path";
-import { fileURLToPath } from "url";
-var PACKAGE_NAMES = /* @__PURE__ */ new Set([
-  "@aliyunrds/ctxdb",
-  "@ali/ctxdb-internal"
-]);
-function findPackageIdentity() {
-  let dir = dirname2(fileURLToPath(import.meta.url));
-  for (let i = 0; i < 5; i++) {
-    try {
-      const pkg = JSON.parse(readFileSync(join2(dir, "package.json"), "utf-8"));
-      if (PACKAGE_NAMES.has(pkg.name) && typeof pkg.version === "string") {
-        return { name: pkg.name, version: pkg.version };
-      }
-    } catch {
-    }
-    dir = dirname2(dir);
+var EXECUTABLE_AGENT_NAMES = {
+  opencode: "opencode",
+  hermes: "hermes"
+};
+function isDirectoryAdapter(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
   }
-  return { name: "@aliyunrds/ctxdb", version: "0.0.0" };
 }
-var PACKAGE_IDENTITY = findPackageIdentity();
-var PACKAGE_NAME = PACKAGE_IDENTITY.name;
-var PACKAGE_VERSION = PACKAGE_IDENTITY.version;
-
-// src/lib/http-client.ts
-var DEFAULT_TIMEOUT_MS = 3e4;
-var CtxdbError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "CtxdbError";
+function isExecutableAdapter(path, platform) {
+  try {
+    if (!statSync(path).isFile()) return false;
+    if (platform !== "win32") accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
   }
-};
-var AuthError = class extends CtxdbError {
-  status = 401;
-  errorCode;
-  errorMessage;
-  data;
-  responseBody;
-  constructor(message = "Unauthorized (HTTP 401) \u2014 check api_key", fields = {}) {
-    super(message);
-    this.name = "AuthError";
-    this.errorCode = fields.errorCode;
-    this.errorMessage = fields.errorMessage;
-    this.data = fields.data;
-    this.responseBody = fields.responseBody;
+}
+function envValue(env, name, platform) {
+  if (env[name] !== void 0) return env[name];
+  if (platform !== "win32") return void 0;
+  const entry = Object.entries(env).find(([key]) => key.toLowerCase() === name.toLowerCase());
+  return entry?.[1];
+}
+function resolveAgentExecutable(command, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const isExecutable = options.isExecutable ?? isExecutableAdapter;
+  const pathValue = envValue(env, "PATH", platform) ?? "";
+  const pathSeparator = platform === "win32" ? ";" : delimiter;
+  const pathEntries = pathValue.split(pathSeparator).map((entry) => entry.trim().replace(/^"(.*)"$/, "$1")).filter(Boolean);
+  const suffixes = platform === "win32" ? (envValue(env, "PATHEXT", platform) ?? ".COM;.EXE;.BAT;.CMD").split(";").map((suffix) => suffix.trim()).filter(Boolean) : [""];
+  for (const directory of pathEntries) {
+    for (const suffix of suffixes) {
+      const candidate = join(directory, `${command}${suffix}`);
+      if (isExecutable(candidate, platform)) return candidate;
+    }
   }
-};
-var NotFoundError = class extends CtxdbError {
-  status = 404;
-  path;
-  errorCode;
-  errorMessage;
-  data;
-  responseBody;
-  constructor(path, fields = {}) {
-    super(`Not found: ${path}`);
-    this.name = "NotFoundError";
-    this.path = path;
-    this.errorCode = fields.errorCode;
-    this.errorMessage = fields.errorMessage;
-    this.data = fields.data;
-    this.responseBody = fields.responseBody;
+  return void 0;
+}
+function displayHomePath(home, path) {
+  if (path === home) return "~";
+  return path.startsWith(`${home}${sep}`) ? `~${path.slice(home.length)}` : path;
+}
+function detectInstalledAgents(options = {}) {
+  const home = options.home ?? homedir();
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const isDirectory = options.isDirectory ?? isDirectoryAdapter;
+  const observations = [];
+  for (const agent of SUPPORTED_AGENTS) {
+    const evidence = [];
+    for (const candidate of agentHomeDirs(agent, home)) {
+      if (isDirectory(candidate)) {
+        evidence.push({ kind: "home", value: displayHomePath(home, candidate) });
+      }
+    }
+    const executableName = EXECUTABLE_AGENT_NAMES[agent];
+    if (executableName) {
+      const executable = resolveAgentExecutable(executableName, {
+        platform,
+        env,
+        isExecutable: options.isExecutable
+      });
+      if (executable) {
+        evidence.push({ kind: "executable", value: executableName });
+      }
+    }
+    if (evidence.length === 0) {
+      observations.push({
+        agent,
+        selected: false,
+        reason: "not-detected",
+        evidence
+      });
+      continue;
+    }
+    const support = agentPlatformSupport(agent, platform);
+    if (!support.supported) {
+      observations.push({
+        agent,
+        selected: false,
+        reason: "unsupported-platform",
+        evidence,
+        detail: support.detail
+      });
+      continue;
+    }
+    observations.push({ agent, selected: true, reason: "detected", evidence });
   }
-};
-var APIError = class extends CtxdbError {
-  status = 400;
-  path;
-  detail;
-  errorCode;
-  errorMessage;
-  data;
-  responseBody;
-  constructor(path, detail, fields = {}) {
-    super(`API error at ${path}: ${detail}`);
-    this.name = "APIError";
-    this.path = path;
-    this.detail = detail;
-    this.errorCode = fields.errorCode;
-    this.errorMessage = fields.errorMessage;
-    this.data = fields.data;
-    this.responseBody = fields.responseBody;
-  }
-};
-var CtxdbHttpError = class extends CtxdbError {
-  status;
-  detail;
-  errorCode;
-  errorMessage;
-  data;
-  responseBody;
-  constructor(status, detail, fields = {}) {
-    super(`HTTP ${status}: ${detail}`);
-    this.name = "CtxdbHttpError";
-    this.status = status;
-    this.detail = detail;
-    this.errorCode = fields.errorCode;
-    this.errorMessage = fields.errorMessage;
-    this.data = fields.data;
-    this.responseBody = fields.responseBody;
+  return {
+    selected: observations.filter((item) => item.selected).map((item) => item.agent),
+    observations
+  };
+}
+function agentFromEnv(env = process.env) {
+  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" && isAgentSlug(argv[i + 1])) {
+      return { agent: argv[i + 1], fellBack: false };
+    }
+    if (tok.startsWith("--agent=")) {
+      const raw = tok.slice("--agent=".length);
+      if (isAgentSlug(raw)) return { agent: raw, fellBack: false };
+    }
   }
+  return { agent: agentFromEnv(env), fellBack: true };
+}
+
+// src/lib/config.ts
+import { readFileSync as readFileSync2, existsSync as existsSync4, unlinkSync as unlinkSync3 } from "fs";
+import { homedir as homedir3 } from "os";
+import { dirname as dirname3, join as join3 } from "path";
+
+// src/lib/secure-file.ts
+import {
+  chmodSync,
+  closeSync,
+  copyFileSync,
+  existsSync as existsSync2,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync
+} from "fs";
+import { randomBytes } from "crypto";
+import { dirname } from "path";
+var nodeSecureFileSystem = {
+  exists: existsSync2,
+  mkdir: (path, options) => {
+    mkdirSync(path, options);
+  },
+  chmod: chmodSync,
+  open: openSync,
+  write: (fd, data) => {
+    writeFileSync(fd, data);
+  },
+  fsync: fsyncSync,
+  close: closeSync,
+  copy: copyFileSync,
+  rename: renameSync,
+  unlink: unlinkSync
 };
-var HttpClient = class {
-  baseUrl;
-  apiKey;
-  timeoutMs;
-  userAgent;
-  extraHeaders;
-  fetchImpl;
-  authorizationProvider;
-  constructor(opts) {
-    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
-    if (!opts.apiKey && !opts.authorizationProvider) {
-      throw new Error("HttpClient requires apiKey or authorizationProvider");
-    }
-    this.apiKey = opts.apiKey ?? "";
-    this.authorizationProvider = opts.authorizationProvider;
-    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    this.userAgent = opts.userAgent ?? `ctxdb-cli/${PACKAGE_VERSION}`;
-    this.extraHeaders = { ...opts.extraHeaders ?? {} };
-    const f = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
-    this.fetchImpl = f;
-  }
-  async buildHeaders(authorization, contentType, requestHeaders = {}) {
-    const h = {
-      Authorization: `${authorization.scheme} ${authorization.value}`,
-      "User-Agent": this.userAgent,
-      Connection: "close",
-      ...this.extraHeaders,
-      ...requestHeaders
-    };
-    if (contentType) h["Content-Type"] = contentType;
-    return h;
+function configBackupPath(target) {
+  return `${target}.bak`;
+}
+function secureAtomicWrite(target, content, options = {}) {
+  const fs = options.fs ?? nodeSecureFileSystem;
+  const platform = options.platform ?? process.platform;
+  const posix = platform !== "win32";
+  const dir = dirname(target);
+  const backup = configBackupPath(target);
+  const suffix = options.tempSuffix ?? `${process.pid}.${randomBytes(6).toString("hex")}`;
+  const temp = `${target}.${suffix}.tmp`;
+  const hadTarget = fs.exists(target);
+  fs.mkdir(dir, { recursive: true, mode: 448 });
+  if (posix) {
+    fs.chmod(dir, 448);
+    if (hadTarget) fs.chmod(target, 384);
   }
-  async doRequest(method, path, init = {}) {
-    const authorization = this.authorizationProvider ? await this.authorizationProvider.resolve() : {
-      scheme: "Token",
-      value: this.apiKey,
-      baseUrl: this.baseUrl,
-      expiresAt: null
-    };
-    let url = `${authorization.baseUrl.replace(/\/+$/, "")}${path}`;
-    if (init.params) {
-      const qs = new URLSearchParams();
-      for (const [k, v] of Object.entries(init.params)) {
-        if (v !== void 0 && v !== null) qs.append(k, String(v));
+  let fd = null;
+  let tempExists = false;
+  try {
+    fd = fs.open(temp, "wx", 384);
+    tempExists = true;
+    fs.write(fd, Buffer.from(content, "utf-8"));
+    fs.fsync(fd);
+    fs.close(fd);
+    fd = null;
+    if (posix) fs.chmod(temp, 384);
+    if (hadTarget && options.backup !== false) {
+      if (platform === "win32") {
+        if (fs.exists(backup)) fs.unlink(backup);
+        fs.rename(target, backup);
+        try {
+          fs.rename(temp, target);
+          tempExists = false;
+        } catch (error) {
+          fs.rename(backup, target);
+          throw error;
+        }
+      } else {
+        fs.copy(target, backup);
+        fs.chmod(backup, 384);
+        fs.rename(temp, target);
+        tempExists = false;
       }
-      const s = qs.toString();
-      if (s) url = `${url}?${s}`;
-    }
-    const effectiveTimeout = init.timeoutMs ?? this.timeoutMs;
-    const dbg = isDebug();
-    let t0 = 0;
-    if (dbg) {
-      t0 = Date.now();
-      debug("http", `\u2192 ${method} ${url} (timeout=${effectiveTimeout}ms)`);
+    } else {
+      fs.rename(temp, target);
+      tempExists = false;
     }
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), effectiveTimeout);
-    try {
-      let resp;
+  } finally {
+    if (fd !== null) {
       try {
-        resp = await this.fetchImpl(url, {
-          method,
-          headers: await this.buildHeaders(
-            authorization,
-            init.contentType,
-            init.headers
-          ),
-          body: init.body,
-          signal: controller.signal
-        });
-      } catch (err) {
-        if (err?.name === "AbortError") {
-          if (dbg) debug("http", `\u2717 ${method} ${path} timeout after ${Date.now() - t0}ms`);
-          throw new CtxdbError(`request timeout after ${effectiveTimeout}ms: ${url}`);
-        }
-        if (dbg) debug("http", `\u2717 ${method} ${path} network error after ${Date.now() - t0}ms: ${err?.message ?? err}`);
-        throw new CtxdbError(`network error contacting ${url}: ${err?.message ?? err}`);
-      }
-      if (resp.status === 204) {
-        if (dbg) debug("http", `\u2190 ${method} ${path} 204 (${Date.now() - t0}ms)`);
-        return {};
+        fs.close(fd);
+      } catch {
       }
-      let text;
+    }
+    if (tempExists && fs.exists(temp)) {
       try {
-        text = await resp.text();
-      } catch (err) {
-        if (err?.name === "AbortError") {
-          if (dbg) debug("http", `\u2717 ${method} ${path} body-read timeout after ${Date.now() - t0}ms`);
-          throw new CtxdbError(`request timeout after ${effectiveTimeout}ms (body read): ${url}`);
-        }
-        if (dbg) debug("http", `\u2717 ${method} ${path} body-read error after ${Date.now() - t0}ms: ${err?.message ?? err}`);
-        throw new CtxdbError(`network error reading body from ${url}: ${err?.message ?? err}`);
-      }
-      if (!resp.ok) {
-        const parsedError = parseErrorResponse(text, `HTTP ${resp.status}`);
-        if (dbg) debug("http", `\u2190 ${method} ${path} ${resp.status} (${Date.now() - t0}ms) ${parsedError.detail}`);
-        if (resp.status === 401) {
-          throw new AuthError(void 0, parsedError);
-        }
-        if (resp.status === 404) {
-          throw new NotFoundError(path, parsedError);
-        }
-        if (resp.status === 400) {
-          throw new APIError(path, parsedError.detail, parsedError);
-        }
-        throw new CtxdbHttpError(resp.status, parsedError.detail, parsedError);
+        fs.unlink(temp);
+      } catch {
       }
-      if (dbg) debug("http", `\u2190 ${method} ${path} ${resp.status} (${Date.now() - t0}ms) body=${text.length}B`);
-      if (!text) return {};
-      return maybeJson(text);
-    } finally {
-      clearTimeout(timer);
     }
   }
-  // ---------- Convenience verbs ----------
-  get(path, params) {
-    return this.doRequest("GET", path, { params });
+}
+
+// src/lib/secrets.ts
+import { createHmac, randomBytes as randomBytes2 } from "crypto";
+var PROCESS_FINGERPRINT_KEY = randomBytes2(32);
+
+// src/credentials/local-credential-provider.ts
+import {
+  closeSync as closeSync2,
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync2,
+  openSync as openSync2,
+  readFileSync,
+  statSync as statSync2,
+  unlinkSync as unlinkSync2,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname2, join as join2 } from "path";
+import { setTimeout as delay } from "timers/promises";
+
+// src/credentials/types.ts
+var ACTIVE_CONTEXTDB_CREDENTIAL = "contextdb/active";
+
+// src/credentials/local-credential-provider.ts
+var DOCUMENT_VERSION = 1;
+var STALE_LOCK_MS = 10 * 60 * 1e3;
+function defaultCredentialsPath() {
+  return join2(homedir2(), ".ctxdb", "credentials.json");
+}
+function emptyDocument() {
+  return { version: DOCUMENT_VERSION, records: {} };
+}
+function normalizeOrigin(value, field) {
+  if (typeof value !== "string" || !value) {
+    throw new Error(`credentials: ${field} must be a non-empty URL`);
   }
-  postJson(path, body, params, options = {}) {
-    return this.doRequest("POST", path, {
-      body: JSON.stringify(body ?? {}),
-      contentType: "application/json",
-      params,
-      timeoutMs: options.timeoutMs,
-      headers: options.headers
-    });
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`credentials: ${field} must be a valid URL`);
   }
-  putJson(path, body, params, options = {}) {
-    return this.doRequest("PUT", path, {
-      body: JSON.stringify(body),
-      contentType: "application/json",
-      params,
-      timeoutMs: options.timeoutMs,
-      headers: options.headers
-    });
+  if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    throw new Error(`credentials: ${field} must be an HTTP(S) origin`);
   }
-  patchJson(path, body, params, options = {}) {
-    return this.doRequest("PATCH", path, {
-      body: JSON.stringify(body),
-      contentType: "application/json",
-      params,
-      timeoutMs: options.timeoutMs,
-      headers: options.headers
-    });
+  return url.toString().replace(/\/$/, "");
+}
+function parseRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("credentials: record must be an object");
   }
-  delete(path, params) {
-    return this.doRequest("DELETE", path, { params });
+  const raw = value;
+  if (raw.kind !== "api-key") {
+    throw new Error(`credentials: unsupported record kind ${String(raw.kind)}`);
   }
-  /**
-   * DELETE with a JSON body. ContextDB batch deletes use the
-   * `DELETE /v1/{resource}/batch` shape with an `{"ids": [...]}` body
-   * (server contract) — the plain `delete()` above only supports query
-   * params.
-   */
-  deleteJson(path, body, params, options = {}) {
-    return this.doRequest("DELETE", path, {
-      body: JSON.stringify(body),
-      contentType: "application/json",
-      params,
-      timeoutMs: options.timeoutMs,
-      headers: options.headers
-    });
+  const payload = raw.payload;
+  const metadata = raw.metadata;
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("credentials: api-key payload must be an object");
   }
-  /**
-   * POST multipart/form-data using runtime-native FormData.
-   *
-   * `fields` are appended as text values; `files` are appended as Blob
-   * with a filename. We intentionally do NOT pass a `Content-Type`
-   * header — when fetch sees a FormData body it sets the multipart
-   * boundary itself.
-   */
-  postMultipart(path, fields = {}, files = {}, options = {}) {
-    const fd = buildMultipartForm(fields, files);
-    return this.doRequest("POST", path, {
-      body: fd,
-      params: options.params,
-      timeoutMs: options.timeoutMs,
-      headers: options.headers
-    });
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+    throw new Error("credentials: api-key metadata must be an object");
   }
-  /** PUT multipart/form-data with the same runtime-owned boundary as POST. */
-  putMultipart(path, fields = {}, files = {}, options = {}) {
-    const fd = buildMultipartForm(fields, files);
-    return this.doRequest("PUT", path, {
-      body: fd,
-      params: options.params,
-      timeoutMs: options.timeoutMs,
-      headers: options.headers
-    });
+  const body = payload;
+  const meta = metadata;
+  if (typeof body.api_key !== "string" || !body.api_key) {
+    throw new Error("credentials: api_key must be a non-empty string");
   }
-};
-function buildMultipartForm(fields, files) {
-  const fd = new FormData();
-  for (const [name, value] of Object.entries(fields)) {
-    fd.append(name, value);
+  if (meta.authorization_method !== "browser-loopback" && meta.authorization_method !== "device-code") {
+    throw new Error("credentials: authorization_method is invalid");
   }
-  for (const [name, part] of Object.entries(files)) {
-    const blob = part.content instanceof Blob ? part.content : new Blob([part.content], { type: part.mimeType });
-    fd.append(name, blob, part.filename);
+  if (typeof meta.issued_at !== "string" || !Number.isFinite(Date.parse(meta.issued_at))) {
+    throw new Error("credentials: issued_at is invalid");
   }
-  return fd;
+  return {
+    kind: "api-key",
+    payload: {
+      apiKey: body.api_key,
+      baseUrl: normalizeOrigin(body.base_url, "base_url"),
+      loginServer: normalizeOrigin(body.login_server, "login_server")
+    },
+    metadata: {
+      authorizationMethod: meta.authorization_method,
+      issuedAt: meta.issued_at
+    }
+  };
 }
-function maybeJson(text) {
+function parseDocument(text) {
+  let raw;
   try {
-    return JSON.parse(text);
+    raw = JSON.parse(text);
   } catch {
-    return text;
+    throw new Error("credentials: credentials.json is not valid JSON");
   }
-}
-function parseErrorResponse(text, fallback) {
-  if (!text) return { detail: fallback };
-  let parsed;
-  try {
-    parsed = JSON.parse(text);
-  } catch {
-    return { detail: text || fallback, responseBody: text || void 0 };
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("credentials: document must be an object");
   }
-  if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-    const obj = parsed;
-    let detail = "";
-    for (const k of ["errorMessage", "detail", "message", "error"]) {
-      const v = obj[k];
-      if (typeof v === "string" && v) {
-        detail = v;
-        break;
-      }
-    }
-    const rawCode = obj.errorCode;
-    const numericCode = typeof rawCode === "number" ? rawCode : typeof rawCode === "string" && rawCode.trim() !== "" ? Number(rawCode) : void 0;
-    const errorCode = typeof numericCode === "number" && Number.isFinite(numericCode) ? numericCode : void 0;
-    const errorMessage = typeof obj.errorMessage === "string" && obj.errorMessage ? obj.errorMessage : void 0;
-    return {
-      detail: detail || JSON.stringify(parsed),
-      errorCode,
-      errorMessage,
-      data: Object.hasOwn(obj, "data") ? obj.data : void 0,
-      responseBody: parsed
-    };
+  const document = raw;
+  if (document.version !== DOCUMENT_VERSION) {
+    throw new Error(`credentials: unsupported document version ${String(document.version)}`);
   }
-  return { detail: String(parsed), responseBody: parsed };
+  if (!document.records || typeof document.records !== "object" || Array.isArray(document.records)) {
+    throw new Error("credentials: records must be an object");
+  }
+  const records = document.records;
+  const unknown = Object.keys(records).filter((key) => key !== ACTIVE_CONTEXTDB_CREDENTIAL);
+  if (unknown.length > 0) {
+    throw new Error(`credentials: unsupported record key ${unknown[0]}`);
+  }
+  const active = records[ACTIVE_CONTEXTDB_CREDENTIAL];
+  return {
+    version: DOCUMENT_VERSION,
+    records: active === void 0 ? {} : { [ACTIVE_CONTEXTDB_CREDENTIAL]: parseRecord(active) }
+  };
+}
+function assertOwnerOnly(path) {
+  if (process.platform === "win32" || !existsSync3(path)) return;
+  const mode = statSync2(path).mode & 511;
+  if ((mode & 63) !== 0) {
+    throw new Error(`credentials: ${path} must be owner-only (run chmod 600)`);
+  }
+}
+function readDocument(path) {
+  if (!existsSync3(path)) return emptyDocument();
+  assertOwnerOnly(path);
+  return parseDocument(readFileSync(path, "utf8"));
+}
+function readActiveCredentialSync(path = defaultCredentialsPath()) {
+  return readDocument(path).records[ACTIVE_CONTEXTDB_CREDENTIAL];
 }
 
-// src/lib/agents.ts
-import { homedir as homedir2 } from "os";
-import { delimiter, join as join3, sep } from "path";
-import { accessSync, constants, existsSync, statSync } from "fs";
-var SUPPORTED_AGENTS = ["qoder", "qoderwork", "qwenwork", "codex", "claude", "opencode", "hermes", "workbuddy"];
-function isBuiltinAgent(v) {
-  return typeof v === "string" && SUPPORTED_AGENTS.includes(v);
+// src/lib/config.ts
+import {
+  resolveDebugPolicy
+} from "@aliyunrds/ctxdb-shared";
+function defaultConfigPath() {
+  return join3(homedir3(), ".ctxdb", "ctxdb.json");
 }
-function isAgentSlug(v) {
-  return v === "default" || isBuiltinAgent(v);
+var DEFAULT_CONFIG_PATH = join3(homedir3(), ".ctxdb", "ctxdb.json");
+function configDir() {
+  return join3(homedir3(), ".ctxdb");
 }
-var isAgent = isAgentSlug;
-function agentHomeDir(agent, home = homedir2()) {
-  switch (agent) {
-    case "qoder":
-      return join3(home, ".qoder");
-    case "qoderwork":
-      return join3(home, ".qoderwork");
-    case "qwenwork":
-      return join3(home, ".qwenwork");
-    case "codex":
-      return join3(home, ".codex");
-    case "claude":
-      return join3(home, ".claude");
-    case "opencode":
-      return join3(home, ".config", "opencode");
-    case "hermes":
-      return join3(home, ".hermes");
-    case "workbuddy":
-      return join3(home, ".workbuddy");
-  }
+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);
 }
-var AGENT_VARIANT_HOMES = {
-  qoder: [".qoder-cn"],
-  qoderwork: [".qoderworkcn"],
-  qwenwork: [".qwenworkcn"]
-};
-function agentHomeDirs(agent, home = homedir2()) {
-  const primary = agentHomeDir(agent, home);
-  const variants = (AGENT_VARIANT_HOMES[agent] ?? []).map(
-    (name) => join3(home, name)
-  );
-  return [primary, ...variants];
+function resolveConfigAgent(options = {}, preloadedRaw) {
+  if (isAgentSlug(options.agent)) return options.agent;
+  return agentFromEnv(options.env);
 }
-function agentPlatformSupport(agent, platform = process.platform) {
-  if (agent === "hermes" && platform === "win32") {
-    return {
-      supported: false,
-      detail: "Hermes integration currently supports macOS/Linux only; Windows Hermes is not yet supported."
-    };
-  }
-  return { supported: true, detail: `${agent} is supported on ${platform}.` };
+function coerceInt(v, fallback) {
+  if (v === null || v === void 0 || v === "") return fallback;
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? Math.trunc(n) : fallback;
 }
-function inspectAgentHomes(agent, options = {}) {
-  const exists = options.exists ?? existsSyncAdapter;
-  const candidates = agentHomeDirs(agent, options.home);
-  const existing = candidates.filter(exists);
-  return { exists: existing.length > 0, existing, candidates };
+function coerceFloat(v, fallback) {
+  if (v === null || v === void 0 || v === "") return fallback;
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : fallback;
 }
-function existsSyncAdapter(path) {
-  try {
-    return existsSync(path);
-  } catch {
-    return false;
+function coerceBool(v, fallback) {
+  if (typeof v === "boolean") return v;
+  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;
 }
-var EXECUTABLE_AGENT_NAMES = {
-  opencode: "opencode",
-  hermes: "hermes"
-};
-function isDirectoryAdapter(path) {
+function readRaw(path) {
+  if (!existsSync4(path)) return {};
   try {
-    return statSync(path).isDirectory();
+    const parsed = JSON.parse(readFileSync2(path, "utf-8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
   } catch {
-    return false;
   }
+  return {};
 }
-function isExecutableAdapter(path, platform) {
-  try {
-    if (!statSync(path).isFile()) return false;
-    if (platform !== "win32") accessSync(path, constants.X_OK);
-    return true;
-  } catch {
-    return false;
+function agentRawFromFile(raw, agent) {
+  const agents = raw.agents;
+  if (agents && typeof agents === "object" && !Array.isArray(agents)) {
+    const candidate = agents[agent];
+    if (candidate && typeof candidate === "object" && !Array.isArray(candidate)) {
+      return candidate;
+    }
   }
+  return {};
 }
-function envValue(env, name, platform) {
-  if (env[name] !== void 0) return env[name];
-  if (platform !== "win32") return void 0;
-  const entry = Object.entries(env).find(([key]) => key.toLowerCase() === name.toLowerCase());
-  return entry?.[1];
+function isV2Schema(raw) {
+  if (Object.keys(raw).length === 0) return true;
+  return raw.version === 2 && raw.agents !== null && typeof raw.agents === "object" && !Array.isArray(raw.agents);
 }
-function resolveAgentExecutable(command, options = {}) {
-  const platform = options.platform ?? process.platform;
-  const env = options.env ?? process.env;
-  const isExecutable = options.isExecutable ?? isExecutableAdapter;
-  const pathValue = envValue(env, "PATH", platform) ?? "";
-  const pathSeparator = platform === "win32" ? ";" : delimiter;
-  const pathEntries = pathValue.split(pathSeparator).map((entry) => entry.trim().replace(/^"(.*)"$/, "$1")).filter(Boolean);
-  const suffixes = platform === "win32" ? (envValue(env, "PATHEXT", platform) ?? ".COM;.EXE;.BAT;.CMD").split(";").map((suffix) => suffix.trim()).filter(Boolean) : [""];
-  for (const directory of pathEntries) {
-    for (const suffix of suffixes) {
-      const candidate = join3(directory, `${command}${suffix}`);
-      if (isExecutable(candidate, platform)) return candidate;
-    }
-  }
-  return void 0;
+function configFromDisk(raw) {
+  const debugConfigured = coerceBool(raw.debug, false);
+  return applyDebugPolicy({
+    apiKey: typeof raw.api_key === "string" && raw.api_key ? raw.api_key : null,
+    baseUrl: typeof raw.base_url === "string" && raw.base_url ? String(raw.base_url).replace(/\/+$/, "") : DEFAULT_BASE_URL,
+    userId: typeof raw.user_id === "string" && raw.user_id ? raw.user_id : DEFAULT_USER_ID,
+    agentId: typeof raw.agent_id === "string" && raw.agent_id ? raw.agent_id : null,
+    appId: typeof raw.app_id === "string" && raw.app_id ? raw.app_id : null,
+    autoCapture: coerceBool(raw.auto_capture, true),
+    autoRecall: coerceBool(raw.auto_recall, true),
+    warmupRecall: coerceBool(raw.warmup_recall, false),
+    recallKnowledge: coerceBool(raw.recall_knowledge, false),
+    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: debugConfigured,
+    debugConfigured,
+    debugForced: false,
+    debugReason: null,
+    kbCatalogInjection: coerceKbCatalogInjection(raw.kb_catalog_injection)
+  });
 }
-function displayHomePath(home, path) {
-  if (path === home) return "~";
-  return path.startsWith(`${home}${sep}`) ? `~${path.slice(home.length)}` : path;
+function applyDebugPolicy(cfg) {
+  const policy = resolveDebugPolicy(cfg.debugConfigured, cfg.baseUrl);
+  cfg.debug = policy.debug;
+  cfg.debugConfigured = policy.debugConfigured;
+  cfg.debugForced = policy.debugForced;
+  cfg.debugReason = policy.debugReason;
+  return cfg;
 }
-function detectInstalledAgents(options = {}) {
-  const home = options.home ?? homedir2();
-  const platform = options.platform ?? process.platform;
+function applyEnv(cfg, env) {
+  if (env.CTXDB_API_KEY) cfg.apiKey = env.CTXDB_API_KEY;
+  if (env.CTXDB_BASE_URL) cfg.baseUrl = env.CTXDB_BASE_URL.replace(/\/+$/, "");
+  if (env.CTXDB_USER_ID) cfg.userId = env.CTXDB_USER_ID;
+  if (env.CTXDB_AGENT_ID) cfg.agentId = env.CTXDB_AGENT_ID;
+  if (env.CTXDB_APP_ID) cfg.appId = env.CTXDB_APP_ID;
+  return applyDebugPolicy(cfg);
+}
+function load(options = {}) {
+  const path = options.path ?? defaultConfigPath();
   const env = options.env ?? process.env;
-  const isDirectory = options.isDirectory ?? isDirectoryAdapter;
-  const observations = [];
-  for (const agent of SUPPORTED_AGENTS) {
-    const evidence = [];
-    for (const candidate of agentHomeDirs(agent, home)) {
-      if (isDirectory(candidate)) {
-        evidence.push({ kind: "home", value: displayHomePath(home, candidate) });
-      }
-    }
-    const executableName = EXECUTABLE_AGENT_NAMES[agent];
-    if (executableName) {
-      const executable = resolveAgentExecutable(executableName, {
-        platform,
-        env,
-        isExecutable: options.isExecutable
-      });
-      if (executable) {
-        evidence.push({ kind: "executable", value: executableName });
-      }
+  const raw = readRaw(path);
+  const agent = resolveConfigAgent({ ...options, path, env }, raw);
+  if (!isV2Schema(raw)) {
+    try {
+      process.stderr.write(
+        `[ctxdb] config schema invalid at ${path}, treating as first-time install
+`
+      );
+    } catch {
     }
-    if (evidence.length === 0) {
-      observations.push({
-        agent,
-        selected: false,
-        reason: "not-detected",
-        evidence
-      });
-      continue;
+    const cfg2 = configFromDisk({});
+    const managed2 = !DISTRIBUTION_MANIFEST.capabilities.managedCredentials || options.managedCredentials === false ? void 0 : readActiveCredentialSync(
+      options.credentialsPath ?? join3(dirname3(path), "credentials.json")
+    );
+    if (managed2) {
+      cfg2.apiKey = managed2.payload.apiKey;
+      cfg2.baseUrl = managed2.payload.baseUrl;
     }
-    const support = agentPlatformSupport(agent, platform);
-    if (!support.supported) {
-      observations.push({
-        agent,
-        selected: false,
-        reason: "unsupported-platform",
-        evidence,
-        detail: support.detail
-      });
-      continue;
+    return applyEnv(cfg2, 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;
+        }
+      }
     }
-    observations.push({ agent, selected: true, reason: "detected", evidence });
   }
+  const cfg = configFromDisk(agentRaw);
+  const managed = !DISTRIBUTION_MANIFEST.capabilities.managedCredentials || options.managedCredentials === false ? void 0 : readActiveCredentialSync(
+    options.credentialsPath ?? join3(dirname3(path), "credentials.json")
+  );
+  if (managed) {
+    cfg.apiKey = managed.payload.apiKey;
+    cfg.baseUrl = managed.payload.baseUrl;
+  }
+  return applyEnv(cfg, env);
+}
+function configToDisk(cfg) {
   return {
-    selected: observations.filter((item) => item.selected).map((item) => item.agent),
-    observations
+    api_key: cfg.apiKey,
+    base_url: cfg.baseUrl,
+    user_id: cfg.userId,
+    agent_id: cfg.agentId,
+    app_id: cfg.appId,
+    auto_capture: cfg.autoCapture,
+    auto_recall: cfg.autoRecall,
+    warmup_recall: cfg.warmupRecall,
+    recall_knowledge: cfg.recallKnowledge,
+    top_k: cfg.topK,
+    threshold: cfg.threshold,
+    knowledge_top_k: cfg.knowledgeTopK,
+    debug: cfg.debugConfigured,
+    kb_catalog_injection: cfg.kbCatalogInjection
   };
 }
-function agentFromEnv(env = process.env) {
-  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" && isAgentSlug(argv[i + 1])) {
-      return { agent: argv[i + 1], fellBack: false };
+function removeAgent(agent, path, options = {}) {
+  const target = path ?? defaultConfigPath();
+  if (!existsSync4(target)) {
+    return { removed: false, remainingAgents: [], fileDeleted: false };
+  }
+  const raw = readRaw(target);
+  if (!isV2Schema(raw) || !raw.agents || typeof raw.agents !== "object" || Array.isArray(raw.agents)) {
+    return { removed: false, remainingAgents: [], fileDeleted: false };
+  }
+  const agents = { ...raw.agents };
+  if (!(agent in agents)) {
+    return {
+      removed: false,
+      remainingAgents: Object.keys(agents),
+      fileDeleted: false
+    };
+  }
+  delete agents[agent];
+  const remaining = Object.keys(agents);
+  if (remaining.length === 0 && !options.keepEmptyShell) {
+    try {
+      unlinkSync3(target);
+      return { removed: true, remainingAgents: [], fileDeleted: true };
+    } catch {
     }
-    if (tok.startsWith("--agent=")) {
-      const raw = tok.slice("--agent=".length);
-      if (isAgentSlug(raw)) return { agent: raw, fellBack: false };
+  }
+  const onDisk = { ...raw, version: 2, agents };
+  delete onDisk.default_agent;
+  secureAtomicWrite(target, JSON.stringify(onDisk, null, 2) + "\n");
+  return { removed: true, remainingAgents: remaining, fileDeleted: false };
+}
+function save(cfg, path, options = {}) {
+  const target = path ?? defaultConfigPath();
+  const agent = resolveConfigAgent(options);
+  const raw = readRaw(target);
+  const validRaw = isV2Schema(raw) ? raw : {};
+  const existingAgents = validRaw.agents && typeof validRaw.agents === "object" && !Array.isArray(validRaw.agents) ? { ...validRaw.agents } : {};
+  const serialized = configToDisk(cfg);
+  if (options.omitApiKey) delete serialized.api_key;
+  const onDisk = {
+    ...validRaw,
+    version: 2,
+    agents: {
+      ...existingAgents,
+      [agent]: serialized
     }
+  };
+  delete onDisk.default_agent;
+  secureAtomicWrite(target, JSON.stringify(onDisk, null, 2) + "\n");
+}
+function configuredAgents(path) {
+  const target = path ?? defaultConfigPath();
+  const raw = readRaw(target);
+  if (!isV2Schema(raw) || !raw.agents || typeof raw.agents !== "object") return [];
+  return Object.keys(raw.agents).filter(isAgent);
+}
+function hasConfiguredAgent(agent, path) {
+  const raw = readRaw(path ?? defaultConfigPath());
+  if (!isV2Schema(raw) || !raw.agents || typeof raw.agents !== "object" || Array.isArray(raw.agents)) {
+    return false;
   }
-  return { agent: agentFromEnv(env), fellBack: true };
+  const profile = raw.agents[agent];
+  return Boolean(
+    profile && typeof profile === "object" && !Array.isArray(profile)
+  );
 }
-
-// src/lib/config.ts
-import { readFileSync as readFileSync3, existsSync as existsSync4, unlinkSync as unlinkSync3 } from "fs";
-import { homedir as homedir4 } from "os";
-import { dirname as dirname5, join as join5 } from "path";
-
-// src/lib/secure-file.ts
-import {
-  chmodSync,
-  closeSync,
-  copyFileSync,
-  existsSync as existsSync2,
-  fsyncSync,
-  mkdirSync as mkdirSync2,
-  openSync,
-  renameSync,
-  unlinkSync,
-  writeFileSync
-} from "fs";
-import { randomBytes } from "crypto";
-import { dirname as dirname3 } from "path";
-var nodeSecureFileSystem = {
-  exists: existsSync2,
-  mkdir: (path, options) => {
-    mkdirSync2(path, options);
-  },
-  chmod: chmodSync,
-  open: openSync,
-  write: (fd, data) => {
-    writeFileSync(fd, data);
-  },
-  fsync: fsyncSync,
-  close: closeSync,
-  copy: copyFileSync,
-  rename: renameSync,
-  unlink: unlinkSync
-};
-function configBackupPath(target) {
-  return `${target}.bak`;
-}
-function secureAtomicWrite(target, content, options = {}) {
-  const fs = options.fs ?? nodeSecureFileSystem;
-  const platform = options.platform ?? process.platform;
-  const posix = platform !== "win32";
-  const dir = dirname3(target);
-  const backup = configBackupPath(target);
-  const suffix = options.tempSuffix ?? `${process.pid}.${randomBytes(6).toString("hex")}`;
-  const temp = `${target}.${suffix}.tmp`;
-  const hadTarget = fs.exists(target);
-  fs.mkdir(dir, { recursive: true, mode: 448 });
-  if (posix) {
-    fs.chmod(dir, 448);
-    if (hadTarget) fs.chmod(target, 384);
+function updateConfiguredDebug(agent, configured, path) {
+  const target = path ?? defaultConfigPath();
+  const raw = readRaw(target);
+  if (!isV2Schema(raw) || !raw.agents || typeof raw.agents !== "object" || Array.isArray(raw.agents)) {
+    return false;
   }
-  let fd = null;
-  let tempExists = false;
-  try {
-    fd = fs.open(temp, "wx", 384);
-    tempExists = true;
-    fs.write(fd, Buffer.from(content, "utf-8"));
-    fs.fsync(fd);
-    fs.close(fd);
-    fd = null;
-    if (posix) fs.chmod(temp, 384);
-    if (hadTarget && options.backup !== false) {
-      if (platform === "win32") {
-        if (fs.exists(backup)) fs.unlink(backup);
-        fs.rename(target, backup);
-        try {
-          fs.rename(temp, target);
-          tempExists = false;
-        } catch (error) {
-          fs.rename(backup, target);
-          throw error;
-        }
-      } else {
-        fs.copy(target, backup);
-        fs.chmod(backup, 384);
-        fs.rename(temp, target);
-        tempExists = false;
-      }
-    } else {
-      fs.rename(temp, target);
-      tempExists = false;
-    }
-  } finally {
-    if (fd !== null) {
-      try {
-        fs.close(fd);
-      } catch {
-      }
-    }
-    if (tempExists && fs.exists(temp)) {
-      try {
-        fs.unlink(temp);
-      } catch {
-      }
-    }
+  const agents = { ...raw.agents };
+  const profile = agents[agent];
+  if (!profile || typeof profile !== "object" || Array.isArray(profile)) {
+    return false;
   }
+  agents[agent] = { ...profile, debug: configured };
+  secureAtomicWrite(
+    target,
+    JSON.stringify({ ...raw, agents }, null, 2) + "\n"
+  );
+  return true;
+}
+function writeInstalledPkgVersion(version, path) {
+  const target = path ?? defaultConfigPath();
+  const raw = readRaw(target);
+  const updated = { ...raw, installed_pkg_version: version };
+  secureAtomicWrite(target, JSON.stringify(updated, null, 2) + "\n");
 }
 
-// src/lib/secrets.ts
-import { createHmac, randomBytes as randomBytes2 } from "crypto";
-var PROCESS_FINGERPRINT_KEY = randomBytes2(32);
-
-// src/credentials/local-credential-provider.ts
-import {
-  closeSync as closeSync2,
-  existsSync as existsSync3,
-  mkdirSync as mkdirSync3,
-  openSync as openSync2,
-  readFileSync as readFileSync2,
-  statSync as statSync2,
-  unlinkSync as unlinkSync2,
-  writeFileSync as writeFileSync2
-} from "fs";
-import { homedir as homedir3 } from "os";
+// src/lib/logger.ts
+import { appendFileSync, mkdirSync as mkdirSync3 } from "fs";
+import { homedir as homedir4 } from "os";
 import { dirname as dirname4, join as join4 } from "path";
-import { setTimeout as delay } from "timers/promises";
-
-// src/credentials/types.ts
-var ACTIVE_CONTEXTDB_CREDENTIAL = "contextdb/active";
-
-// src/credentials/local-credential-provider.ts
-var DOCUMENT_VERSION = 1;
-var STALE_LOCK_MS = 10 * 60 * 1e3;
-function defaultCredentialsPath() {
-  return join4(homedir3(), ".ctxdb", "credentials.json");
+function logPath() {
+  return join4(homedir4(), ".ctxdb", "logs", "ctxdb.log");
 }
-function emptyDocument() {
-  return { version: DOCUMENT_VERSION, records: {} };
+var _enabled = null;
+function setDebug(enabled) {
+  _enabled = enabled;
 }
-function normalizeOrigin(value, field) {
-  if (typeof value !== "string" || !value) {
-    throw new Error(`credentials: ${field} must be a non-empty URL`);
+function isDebug() {
+  return _enabled === true;
+}
+function debug(tag, msg, data) {
+  if (_enabled !== true) return;
+  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);
+    line += `
+${s}`;
   }
-  let url;
+  line += "\n";
+  const p = logPath();
   try {
-    url = new URL(value);
+    mkdirSync3(dirname4(p), { recursive: true });
+    appendFileSync(p, line, "utf-8");
   } catch {
-    throw new Error(`credentials: ${field} must be a valid URL`);
   }
-  if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
-    throw new Error(`credentials: ${field} must be an HTTP(S) origin`);
+}
+
+// src/lib/package-version.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { dirname as dirname5, join as join5 } from "path";
+import { fileURLToPath } from "url";
+var PACKAGE_NAMES = /* @__PURE__ */ new Set([
+  "@aliyunrds/ctxdb",
+  "@ali/ctxdb-internal"
+]);
+function findPackageIdentity() {
+  let dir = dirname5(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 5; i++) {
+    try {
+      const pkg = JSON.parse(readFileSync3(join5(dir, "package.json"), "utf-8"));
+      if (PACKAGE_NAMES.has(pkg.name) && typeof pkg.version === "string") {
+        return { name: pkg.name, version: pkg.version };
+      }
+    } catch {
+    }
+    dir = dirname5(dir);
   }
-  return url.toString().replace(/\/$/, "");
+  return { name: "@aliyunrds/ctxdb", version: "0.0.0" };
 }
-function parseRecord(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error("credentials: record must be an object");
+var PACKAGE_IDENTITY = findPackageIdentity();
+var PACKAGE_NAME = PACKAGE_IDENTITY.name;
+var PACKAGE_VERSION = PACKAGE_IDENTITY.version;
+
+// src/lib/http-client.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var CtxdbError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CtxdbError";
   }
-  const raw = value;
-  if (raw.kind !== "api-key") {
-    throw new Error(`credentials: unsupported record kind ${String(raw.kind)}`);
+};
+var AuthError = class extends CtxdbError {
+  status = 401;
+  errorCode;
+  errorMessage;
+  data;
+  responseBody;
+  constructor(message = "Unauthorized (HTTP 401) \u2014 check api_key", fields = {}) {
+    super(message);
+    this.name = "AuthError";
+    this.errorCode = fields.errorCode;
+    this.errorMessage = fields.errorMessage;
+    this.data = fields.data;
+    this.responseBody = fields.responseBody;
   }
-  const payload = raw.payload;
-  const metadata = raw.metadata;
-  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
-    throw new Error("credentials: api-key payload must be an object");
+};
+var NotFoundError = class extends CtxdbError {
+  status = 404;
+  path;
+  errorCode;
+  errorMessage;
+  data;
+  responseBody;
+  constructor(path, fields = {}) {
+    super(`Not found: ${path}`);
+    this.name = "NotFoundError";
+    this.path = path;
+    this.errorCode = fields.errorCode;
+    this.errorMessage = fields.errorMessage;
+    this.data = fields.data;
+    this.responseBody = fields.responseBody;
   }
-  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
-    throw new Error("credentials: api-key metadata must be an object");
+};
+var APIError = class extends CtxdbError {
+  status = 400;
+  path;
+  detail;
+  errorCode;
+  errorMessage;
+  data;
+  responseBody;
+  constructor(path, detail, fields = {}) {
+    super(`API error at ${path}: ${detail}`);
+    this.name = "APIError";
+    this.path = path;
+    this.detail = detail;
+    this.errorCode = fields.errorCode;
+    this.errorMessage = fields.errorMessage;
+    this.data = fields.data;
+    this.responseBody = fields.responseBody;
   }
-  const body = payload;
-  const meta = metadata;
-  if (typeof body.api_key !== "string" || !body.api_key) {
-    throw new Error("credentials: api_key must be a non-empty string");
-  }
-  if (meta.authorization_method !== "browser-loopback" && meta.authorization_method !== "device-code") {
-    throw new Error("credentials: authorization_method is invalid");
-  }
-  if (typeof meta.issued_at !== "string" || !Number.isFinite(Date.parse(meta.issued_at))) {
-    throw new Error("credentials: issued_at is invalid");
+};
+var CtxdbHttpError = class extends CtxdbError {
+  status;
+  detail;
+  errorCode;
+  errorMessage;
+  data;
+  responseBody;
+  constructor(status, detail, fields = {}) {
+    super(`HTTP ${status}: ${detail}`);
+    this.name = "CtxdbHttpError";
+    this.status = status;
+    this.detail = detail;
+    this.errorCode = fields.errorCode;
+    this.errorMessage = fields.errorMessage;
+    this.data = fields.data;
+    this.responseBody = fields.responseBody;
   }
-  return {
-    kind: "api-key",
-    payload: {
-      apiKey: body.api_key,
-      baseUrl: normalizeOrigin(body.base_url, "base_url"),
-      loginServer: normalizeOrigin(body.login_server, "login_server")
-    },
-    metadata: {
-      authorizationMethod: meta.authorization_method,
-      issuedAt: meta.issued_at
+};
+var HttpClient = class {
+  baseUrl;
+  apiKey;
+  timeoutMs;
+  userAgent;
+  extraHeaders;
+  fetchImpl;
+  authorizationProvider;
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    if (!opts.apiKey && !opts.authorizationProvider) {
+      throw new Error("HttpClient requires apiKey or authorizationProvider");
     }
-  };
-}
-function parseDocument(text) {
-  let raw;
-  try {
-    raw = JSON.parse(text);
-  } catch {
-    throw new Error("credentials: credentials.json is not valid JSON");
-  }
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-    throw new Error("credentials: document must be an object");
-  }
-  const document = raw;
-  if (document.version !== DOCUMENT_VERSION) {
-    throw new Error(`credentials: unsupported document version ${String(document.version)}`);
-  }
-  if (!document.records || typeof document.records !== "object" || Array.isArray(document.records)) {
-    throw new Error("credentials: records must be an object");
-  }
-  const records = document.records;
-  const unknown = Object.keys(records).filter((key) => key !== ACTIVE_CONTEXTDB_CREDENTIAL);
-  if (unknown.length > 0) {
-    throw new Error(`credentials: unsupported record key ${unknown[0]}`);
-  }
-  const active = records[ACTIVE_CONTEXTDB_CREDENTIAL];
-  return {
-    version: DOCUMENT_VERSION,
-    records: active === void 0 ? {} : { [ACTIVE_CONTEXTDB_CREDENTIAL]: parseRecord(active) }
-  };
-}
-function assertOwnerOnly(path) {
-  if (process.platform === "win32" || !existsSync3(path)) return;
-  const mode = statSync2(path).mode & 511;
-  if ((mode & 63) !== 0) {
-    throw new Error(`credentials: ${path} must be owner-only (run chmod 600)`);
+    this.apiKey = opts.apiKey ?? "";
+    this.authorizationProvider = opts.authorizationProvider;
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.userAgent = opts.userAgent ?? `ctxdb-cli/${PACKAGE_VERSION}`;
+    this.extraHeaders = { ...opts.extraHeaders ?? {} };
+    const f = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.fetchImpl = f;
   }
-}
-function readDocument(path) {
-  if (!existsSync3(path)) return emptyDocument();
-  assertOwnerOnly(path);
-  return parseDocument(readFileSync2(path, "utf8"));
-}
-function readActiveCredentialSync(path = defaultCredentialsPath()) {
-  return readDocument(path).records[ACTIVE_CONTEXTDB_CREDENTIAL];
-}
-
-// src/lib/config.ts
-import {
-  resolveDebugPolicy
-} from "@aliyunrds/ctxdb-shared";
-function defaultConfigPath() {
-  return join5(homedir4(), ".ctxdb", "ctxdb.json");
-}
-var DEFAULT_CONFIG_PATH = join5(homedir4(), ".ctxdb", "ctxdb.json");
-function configDir() {
-  return join5(homedir4(), ".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 = {}, preloadedRaw) {
-  if (isAgentSlug(options.agent)) return options.agent;
-  return agentFromEnv(options.env);
-}
-function coerceInt(v, fallback) {
-  if (v === null || v === void 0 || v === "") return fallback;
-  const n = typeof v === "number" ? v : Number(v);
-  return Number.isFinite(n) ? Math.trunc(n) : fallback;
-}
-function coerceFloat(v, fallback) {
-  if (v === null || v === void 0 || v === "") return fallback;
-  const n = typeof v === "number" ? v : Number(v);
-  return Number.isFinite(n) ? n : fallback;
-}
-function coerceBool(v, fallback) {
-  if (typeof v === "boolean") return v;
-  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;
+  async buildHeaders(authorization, contentType, requestHeaders = {}) {
+    const h = {
+      Authorization: `${authorization.scheme} ${authorization.value}`,
+      "User-Agent": this.userAgent,
+      Connection: "close",
+      ...this.extraHeaders,
+      ...requestHeaders
+    };
+    if (contentType) h["Content-Type"] = contentType;
+    return h;
   }
-  return DEFAULT_KB_CATALOG_INJECTION;
-}
-function readRaw(path) {
-  if (!existsSync4(path)) return {};
-  try {
-    const parsed = JSON.parse(readFileSync3(path, "utf-8"));
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      return parsed;
+  async doRequest(method, path, init = {}) {
+    const authorization = this.authorizationProvider ? await this.authorizationProvider.resolve() : {
+      scheme: "Token",
+      value: this.apiKey,
+      baseUrl: this.baseUrl,
+      expiresAt: null
+    };
+    let url = `${authorization.baseUrl.replace(/\/+$/, "")}${path}`;
+    if (init.params) {
+      const qs = new URLSearchParams();
+      for (const [k, v] of Object.entries(init.params)) {
+        if (v !== void 0 && v !== null) qs.append(k, String(v));
+      }
+      const s = qs.toString();
+      if (s) url = `${url}?${s}`;
     }
-  } catch {
-  }
-  return {};
-}
-function agentRawFromFile(raw, agent) {
-  const agents = raw.agents;
-  if (agents && typeof agents === "object" && !Array.isArray(agents)) {
-    const candidate = agents[agent];
-    if (candidate && typeof candidate === "object" && !Array.isArray(candidate)) {
-      return candidate;
+    const effectiveTimeout = init.timeoutMs ?? this.timeoutMs;
+    const dbg = isDebug();
+    let t0 = 0;
+    if (dbg) {
+      t0 = Date.now();
+      debug("http", `\u2192 ${method} ${url} (timeout=${effectiveTimeout}ms)`);
     }
-  }
-  return {};
-}
-function isV2Schema(raw) {
-  if (Object.keys(raw).length === 0) return true;
-  return raw.version === 2 && raw.agents !== null && typeof raw.agents === "object" && !Array.isArray(raw.agents);
-}
-function configFromDisk(raw) {
-  const debugConfigured = coerceBool(raw.debug, false);
-  return applyDebugPolicy({
-    apiKey: typeof raw.api_key === "string" && raw.api_key ? raw.api_key : null,
-    baseUrl: typeof raw.base_url === "string" && raw.base_url ? String(raw.base_url).replace(/\/+$/, "") : DEFAULT_BASE_URL,
-    userId: typeof raw.user_id === "string" && raw.user_id ? raw.user_id : DEFAULT_USER_ID,
-    agentId: typeof raw.agent_id === "string" && raw.agent_id ? raw.agent_id : null,
-    appId: typeof raw.app_id === "string" && raw.app_id ? raw.app_id : null,
-    autoCapture: coerceBool(raw.auto_capture, true),
-    autoRecall: coerceBool(raw.auto_recall, true),
-    warmupRecall: coerceBool(raw.warmup_recall, false),
-    recallKnowledge: coerceBool(raw.recall_knowledge, false),
-    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: debugConfigured,
-    debugConfigured,
-    debugForced: false,
-    debugReason: null,
-    kbCatalogInjection: coerceKbCatalogInjection(raw.kb_catalog_injection)
-  });
-}
-function applyDebugPolicy(cfg) {
-  const policy = resolveDebugPolicy(cfg.debugConfigured, cfg.baseUrl);
-  cfg.debug = policy.debug;
-  cfg.debugConfigured = policy.debugConfigured;
-  cfg.debugForced = policy.debugForced;
-  cfg.debugReason = policy.debugReason;
-  return cfg;
-}
-function applyEnv(cfg, env) {
-  if (env.CTXDB_API_KEY) cfg.apiKey = env.CTXDB_API_KEY;
-  if (env.CTXDB_BASE_URL) cfg.baseUrl = env.CTXDB_BASE_URL.replace(/\/+$/, "");
-  if (env.CTXDB_USER_ID) cfg.userId = env.CTXDB_USER_ID;
-  if (env.CTXDB_AGENT_ID) cfg.agentId = env.CTXDB_AGENT_ID;
-  if (env.CTXDB_APP_ID) cfg.appId = env.CTXDB_APP_ID;
-  return applyDebugPolicy(cfg);
-}
-function load(options = {}) {
-  const path = options.path ?? defaultConfigPath();
-  const env = options.env ?? process.env;
-  const raw = readRaw(path);
-  const agent = resolveConfigAgent({ ...options, path, env }, raw);
-  if (!isV2Schema(raw)) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), effectiveTimeout);
     try {
-      process.stderr.write(
-        `[ctxdb] config schema invalid at ${path}, treating as first-time install
-`
-      );
-    } catch {
-    }
-    const cfg2 = configFromDisk({});
-    const managed2 = !DISTRIBUTION_MANIFEST.capabilities.managedCredentials || options.managedCredentials === false ? void 0 : readActiveCredentialSync(
-      options.credentialsPath ?? join5(dirname5(path), "credentials.json")
-    );
-    if (managed2) {
-      cfg2.apiKey = managed2.payload.apiKey;
-      cfg2.baseUrl = managed2.payload.baseUrl;
-    }
-    return applyEnv(cfg2, 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;
+      let resp;
+      try {
+        resp = await this.fetchImpl(url, {
+          method,
+          headers: await this.buildHeaders(
+            authorization,
+            init.contentType,
+            init.headers
+          ),
+          body: init.body,
+          signal: controller.signal
+        });
+      } catch (err) {
+        if (err?.name === "AbortError") {
+          if (dbg) debug("http", `\u2717 ${method} ${path} timeout after ${Date.now() - t0}ms`);
+          throw new CtxdbError(`request timeout after ${effectiveTimeout}ms: ${url}`);
+        }
+        if (dbg) debug("http", `\u2717 ${method} ${path} network error after ${Date.now() - t0}ms: ${err?.message ?? err}`);
+        throw new CtxdbError(`network error contacting ${url}: ${err?.message ?? err}`);
+      }
+      if (resp.status === 204) {
+        if (dbg) debug("http", `\u2190 ${method} ${path} 204 (${Date.now() - t0}ms)`);
+        return {};
+      }
+      let text;
+      try {
+        text = await resp.text();
+      } catch (err) {
+        if (err?.name === "AbortError") {
+          if (dbg) debug("http", `\u2717 ${method} ${path} body-read timeout after ${Date.now() - t0}ms`);
+          throw new CtxdbError(`request timeout after ${effectiveTimeout}ms (body read): ${url}`);
+        }
+        if (dbg) debug("http", `\u2717 ${method} ${path} body-read error after ${Date.now() - t0}ms: ${err?.message ?? err}`);
+        throw new CtxdbError(`network error reading body from ${url}: ${err?.message ?? err}`);
+      }
+      if (!resp.ok) {
+        const parsedError = parseErrorResponse(text, `HTTP ${resp.status}`);
+        if (dbg) debug("http", `\u2190 ${method} ${path} ${resp.status} (${Date.now() - t0}ms) ${parsedError.detail}`);
+        if (resp.status === 401) {
+          throw new AuthError(void 0, parsedError);
+        }
+        if (resp.status === 404) {
+          throw new NotFoundError(path, parsedError);
+        }
+        if (resp.status === 400) {
+          throw new APIError(path, parsedError.detail, parsedError);
         }
+        throw new CtxdbHttpError(resp.status, parsedError.detail, parsedError);
       }
+      if (dbg) debug("http", `\u2190 ${method} ${path} ${resp.status} (${Date.now() - t0}ms) body=${text.length}B`);
+      if (!text) return {};
+      return maybeJson(text);
+    } finally {
+      clearTimeout(timer);
     }
   }
-  const cfg = configFromDisk(agentRaw);
-  const managed = !DISTRIBUTION_MANIFEST.capabilities.managedCredentials || options.managedCredentials === false ? void 0 : readActiveCredentialSync(
-    options.credentialsPath ?? join5(dirname5(path), "credentials.json")
-  );
-  if (managed) {
-    cfg.apiKey = managed.payload.apiKey;
-    cfg.baseUrl = managed.payload.baseUrl;
+  // ---------- Convenience verbs ----------
+  get(path, params) {
+    return this.doRequest("GET", path, { params });
   }
-  return applyEnv(cfg, env);
-}
-function configToDisk(cfg) {
-  return {
-    api_key: cfg.apiKey,
-    base_url: cfg.baseUrl,
-    user_id: cfg.userId,
-    agent_id: cfg.agentId,
-    app_id: cfg.appId,
-    auto_capture: cfg.autoCapture,
-    auto_recall: cfg.autoRecall,
-    warmup_recall: cfg.warmupRecall,
-    recall_knowledge: cfg.recallKnowledge,
-    top_k: cfg.topK,
-    threshold: cfg.threshold,
-    knowledge_top_k: cfg.knowledgeTopK,
-    debug: cfg.debugConfigured,
-    kb_catalog_injection: cfg.kbCatalogInjection
-  };
-}
-function removeAgent(agent, path, options = {}) {
-  const target = path ?? defaultConfigPath();
-  if (!existsSync4(target)) {
-    return { removed: false, remainingAgents: [], fileDeleted: false };
+  postJson(path, body, params, options = {}) {
+    return this.doRequest("POST", path, {
+      body: JSON.stringify(body ?? {}),
+      contentType: "application/json",
+      params,
+      timeoutMs: options.timeoutMs,
+      headers: options.headers
+    });
   }
-  const raw = readRaw(target);
-  if (!isV2Schema(raw) || !raw.agents || typeof raw.agents !== "object" || Array.isArray(raw.agents)) {
-    return { removed: false, remainingAgents: [], fileDeleted: false };
+  putJson(path, body, params, options = {}) {
+    return this.doRequest("PUT", path, {
+      body: JSON.stringify(body),
+      contentType: "application/json",
+      params,
+      timeoutMs: options.timeoutMs,
+      headers: options.headers
+    });
   }
-  const agents = { ...raw.agents };
-  if (!(agent in agents)) {
-    return {
-      removed: false,
-      remainingAgents: Object.keys(agents),
-      fileDeleted: false
-    };
+  patchJson(path, body, params, options = {}) {
+    return this.doRequest("PATCH", path, {
+      body: JSON.stringify(body),
+      contentType: "application/json",
+      params,
+      timeoutMs: options.timeoutMs,
+      headers: options.headers
+    });
   }
-  delete agents[agent];
-  const remaining = Object.keys(agents);
-  if (remaining.length === 0 && !options.keepEmptyShell) {
-    try {
-      unlinkSync3(target);
-      return { removed: true, remainingAgents: [], fileDeleted: true };
-    } catch {
-    }
+  delete(path, params) {
+    return this.doRequest("DELETE", path, { params });
   }
-  const onDisk = { ...raw, version: 2, agents };
-  delete onDisk.default_agent;
-  secureAtomicWrite(target, JSON.stringify(onDisk, null, 2) + "\n");
-  return { removed: true, remainingAgents: remaining, fileDeleted: false };
-}
-function save(cfg, path, options = {}) {
-  const target = path ?? defaultConfigPath();
-  const agent = resolveConfigAgent(options);
-  const raw = readRaw(target);
-  const validRaw = isV2Schema(raw) ? raw : {};
-  const existingAgents = validRaw.agents && typeof validRaw.agents === "object" && !Array.isArray(validRaw.agents) ? { ...validRaw.agents } : {};
-  const serialized = configToDisk(cfg);
-  if (options.omitApiKey) delete serialized.api_key;
-  const onDisk = {
-    ...validRaw,
-    version: 2,
-    agents: {
-      ...existingAgents,
-      [agent]: serialized
-    }
-  };
-  delete onDisk.default_agent;
-  secureAtomicWrite(target, JSON.stringify(onDisk, null, 2) + "\n");
-}
-function configuredAgents(path) {
-  const target = path ?? defaultConfigPath();
-  const raw = readRaw(target);
-  if (!isV2Schema(raw) || !raw.agents || typeof raw.agents !== "object") return [];
-  return Object.keys(raw.agents).filter(isAgent);
+  /**
+   * DELETE with a JSON body. ContextDB batch deletes use the
+   * `DELETE /v1/{resource}/batch` shape with an `{"ids": [...]}` body
+   * (server contract) — the plain `delete()` above only supports query
+   * params.
+   */
+  deleteJson(path, body, params, options = {}) {
+    return this.doRequest("DELETE", path, {
+      body: JSON.stringify(body),
+      contentType: "application/json",
+      params,
+      timeoutMs: options.timeoutMs,
+      headers: options.headers
+    });
+  }
+  /**
+   * POST multipart/form-data using runtime-native FormData.
+   *
+   * `fields` are appended as text values; `files` are appended as Blob
+   * with a filename. We intentionally do NOT pass a `Content-Type`
+   * header — when fetch sees a FormData body it sets the multipart
+   * boundary itself.
+   */
+  postMultipart(path, fields = {}, files = {}, options = {}) {
+    const fd = buildMultipartForm(fields, files);
+    return this.doRequest("POST", path, {
+      body: fd,
+      params: options.params,
+      timeoutMs: options.timeoutMs,
+      headers: options.headers
+    });
+  }
+  /** PUT multipart/form-data with the same runtime-owned boundary as POST. */
+  putMultipart(path, fields = {}, files = {}, options = {}) {
+    const fd = buildMultipartForm(fields, files);
+    return this.doRequest("PUT", path, {
+      body: fd,
+      params: options.params,
+      timeoutMs: options.timeoutMs,
+      headers: options.headers
+    });
+  }
+};
+function buildMultipartForm(fields, files) {
+  const fd = new FormData();
+  for (const [name, value] of Object.entries(fields)) {
+    fd.append(name, value);
+  }
+  for (const [name, part] of Object.entries(files)) {
+    const blob = part.content instanceof Blob ? part.content : new Blob([part.content], { type: part.mimeType });
+    fd.append(name, blob, part.filename);
+  }
+  return fd;
 }
-function hasConfiguredAgent(agent, path) {
-  const raw = readRaw(path ?? defaultConfigPath());
-  if (!isV2Schema(raw) || !raw.agents || typeof raw.agents !== "object" || Array.isArray(raw.agents)) {
-    return false;
+function maybeJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
   }
-  const profile = raw.agents[agent];
-  return Boolean(
-    profile && typeof profile === "object" && !Array.isArray(profile)
-  );
 }
-function updateConfiguredDebug(agent, configured, path) {
-  const target = path ?? defaultConfigPath();
-  const raw = readRaw(target);
-  if (!isV2Schema(raw) || !raw.agents || typeof raw.agents !== "object" || Array.isArray(raw.agents)) {
-    return false;
+function parseErrorResponse(text, fallback) {
+  if (!text) return { detail: fallback };
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { detail: text || fallback, responseBody: text || void 0 };
   }
-  const agents = { ...raw.agents };
-  const profile = agents[agent];
-  if (!profile || typeof profile !== "object" || Array.isArray(profile)) {
-    return false;
+  if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+    const obj = parsed;
+    let detail = "";
+    for (const k of ["errorMessage", "detail", "message", "error"]) {
+      const v = obj[k];
+      if (typeof v === "string" && v) {
+        detail = v;
+        break;
+      }
+    }
+    const rawCode = obj.errorCode;
+    const numericCode = typeof rawCode === "number" ? rawCode : typeof rawCode === "string" && rawCode.trim() !== "" ? Number(rawCode) : void 0;
+    const errorCode = typeof numericCode === "number" && Number.isFinite(numericCode) ? numericCode : void 0;
+    const errorMessage = typeof obj.errorMessage === "string" && obj.errorMessage ? obj.errorMessage : void 0;
+    return {
+      detail: detail || JSON.stringify(parsed),
+      errorCode,
+      errorMessage,
+      data: Object.hasOwn(obj, "data") ? obj.data : void 0,
+      responseBody: parsed
+    };
   }
-  agents[agent] = { ...profile, debug: configured };
-  secureAtomicWrite(
-    target,
-    JSON.stringify({ ...raw, agents }, null, 2) + "\n"
-  );
-  return true;
-}
-function writeInstalledPkgVersion(version, path) {
-  const target = path ?? defaultConfigPath();
-  const raw = readRaw(target);
-  const updated = { ...raw, installed_pkg_version: version };
-  secureAtomicWrite(target, JSON.stringify(updated, null, 2) + "\n");
+  return { detail: String(parsed), responseBody: parsed };
 }
 
 export {
-  setDebug,
-  isDebug,
-  debug,
-  PACKAGE_NAME,
-  PACKAGE_VERSION,
-  CtxdbError,
-  HttpClient,
   SUPPORTED_AGENTS,
+  SUPPORTED_AGENT_CHOICES,
+  AGENT_CHOICES,
   isBuiltinAgent,
   isAgentSlug,
   agentHomeDir,
@@ -1086,5 +1083,12 @@ export {
   configuredAgents,
   hasConfiguredAgent,
   updateConfiguredDebug,
-  writeInstalledPkgVersion
+  writeInstalledPkgVersion,
+  setDebug,
+  isDebug,
+  debug,
+  PACKAGE_NAME,
+  PACKAGE_VERSION,
+  CtxdbError,
+  HttpClient
 };