@aliyunrds/ctxdb 1.0.2 → 1.0.4

package/README.md

@@ -1,6 +1,6 @@
 # @aliyunrds/ctxdb
 
-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.
+Unified access layer for RDS ContextDatabase. One `ctxdb` CLI (memory + KB ops), one `setup` installer (`--agent <…>` for one hooks/skills integration, `--all` for every detected integration, bare for CLI-only), per-agent SKILL.md — supports multiple code agents from a single package.
 
 | Agent | Hooks | Skill install path | Skill style |
 |---|---|---|---|
@@ -15,6 +15,87 @@ Config and logs live under `~/.ctxdb/`. `~/.ctxdb/ctxdb.json` is one file, but r
 
 ## Install
 
+### Recommended: console-generated installer command
+
+The customer console supplies the selected Agent and API key to one of two
+standalone public files. Replace `<public-oss-url>` with the release-owned OSS
+base URL:
+
+```sh
+# macOS / Linux
+curl -fsSL <public-oss-url>/install.sh | \
+  bash -s -- --agent codex --api-key 'ctxdb-...'
+```
+
+```powershell
+# Windows PowerShell
+& ([ScriptBlock]::Create((irm '<public-oss-url>/install.ps1'))) `
+  -Agent codex -ApiKey 'ctxdb-...'
+```
+
+Windows Command Prompt uses the same `install.ps1`; there is no third CMD
+artifact:
+
+```bat
+powershell.exe -NoProfile -Command "& ([ScriptBlock]::Create((irm '<public-oss-url>/install.ps1'))) -Agent 'codex' -ApiKey 'ctxdb-...'"
+```
+
+`--agent openclaw` / `-Agent openclaw` takes a dedicated plugin flow instead
+of `ctxdb setup`: the installer requires an existing `openclaw` CLI, runs
+`openclaw plugins install openclaw_memory_rds_ctxdb`, `openclaw plugins
+enable openclaw_memory_rds_ctxdb`, and `openclaw ctxdb init --api-key <key>`,
+then prints `openclaw gateway restart` for the user to run. It never installs
+Node.js, npm packages, or the ctxdb CLI on this path.
+
+An agent-readable manual, `bootstrap/install.md`, is published alongside the
+scripts. A customer's coding agent can be pointed at its public URL to run the
+same four-stage flow by hand under the same safety boundaries (used when the
+scripts are unavailable or blocked by local policy).
+
+The installer shows four stages: check runtime, install the CLI, configure the
+Agent, and verify the connection. It requires Node.js 20 or newer and the npm
+executable shipped beside that exact Node.js runtime. If Node.js is absent, it
+can offer one reviewed Node.js 22 action after explicit confirmation. If an
+existing Node.js is old, broken, or missing its sibling npm, it stops with
+upgrade/repair guidance and does not install another private runtime.
+
+The API key is passed directly to `ctxdb setup` and stored in
+`~/.ctxdb/ctxdb.json`; installer-controlled output redacts the complete value.
+The generated command itself contains the key, so treat it as a credential and
+follow the local shell-history policy. The installer never retries with sudo,
+silently elevates, or edits a shell/PowerShell profile. If the npm global prefix
+is not writable, it uses a user-only prefix and prints one PATH follow-up.
+
+Immediately before setup, the installer saves an opaque, private temporary copy
+of `~/.ctxdb/ctxdb.json`. If setup fails, it prints the original setup
+diagnostic, restores the previous config exactly, or removes the incomplete new
+config when none existed before. Hooks, plugins, and skills may already have
+changed; fix the reported cause and rerun the same command to repair them. A
+later `status` failure does not roll back a setup that already succeeded.
+
+Add `--dry-run` on macOS/Linux or `-DryRun` on Windows to preview the same four
+stages without prompting, installing Node.js or ctxdb, writing a prefix probe,
+or running setup/status:
+
+```sh
+curl -fsSL <public-oss-url>/install.sh | \
+  bash -s -- --agent codex --api-key 'ctxdb-...' --dry-run
+```
+
+```powershell
+& ([ScriptBlock]::Create((irm '<public-oss-url>/install.ps1'))) `
+  -Agent codex -ApiKey 'ctxdb-...' -DryRun
+```
+
+Dry run still validates the required parameters and inspects the local runtime,
+but it does not contact the npm registry or validate the API key, connectivity,
+or Agent integration. Its output always redacts the supplied key.
+
+For review-first installation, download the matching file, verify its published
+SHA-256, inspect it, and run the local copy with the same parameters.
+
+### Manual setup and local configuration management
+
 ```sh
 npm install -g @aliyunrds/ctxdb
 
@@ -31,6 +112,9 @@ ctxdb setup --agent opencode --api-key ctxdb-...
 # Hermes (pre_llm_call recall/warmup + post_llm_call capture + skill; macOS/Linux)
 ctxdb setup --agent hermes --api-key ctxdb-...
 
+# Detect and configure every supported Agent already used on this host.
+ctxdb setup --all --api-key ctxdb-...
+
 # --base-url defaults to https://context-database.aliyuncs.com (public prod).
 #   Pass --base-url <host> only if you target a different deployment
 #   (e.g., a pre / staging host, or a self-hosted instance).
@@ -39,7 +123,42 @@ ctxdb setup --agent hermes --api-key ctxdb-...
 #   sharing the same workspace (see "Configuration" below).
 
 # Verify
-ctxdb status --json
+ctxdb status --agent codex --json
+ctxdb status --all --json
+```
+
+`setup --all` and `status --all` use one read-only detector and return Agents in
+`SUPPORTED_AGENTS` order. Qoder/QoderWork/Codex/Claude require an existing
+primary or supported variant home. OpenCode and Hermes are selected when their
+home exists or their canonical executable is discoverable on PATH. Detection
+does not create files, does not use an existing ctxdb profile as evidence, and
+never selects `default` or OpenClaw. If nothing is detected, the command exits
+non-zero and asks the user to install/start an Agent once or use explicit
+`--agent <name>`.
+
+When `ctxdb setup --all` is invoked without `--api-key`, the CLI snapshots each
+selected Agent's effective configuration before any setup write. Credential
+priority is `--api-key`, `CTXDB_API_KEY`, the Agent profile, then the `default`
+profile. This means a key already configured on `agents.default` is reused for
+detected Agents that do not have their own key. An Agent with no effective key
+is reported failed without stopping later Agents. Supplying one explicit key
+applies it to every selected Agent. Batch output includes per-Agent results and
+one deduplicated uninstall-order hint, including after a partial failure.
+
+The same two commands cover later management without a separate wizard:
+
+```sh
+# Add another Agent
+ctxdb setup --agent claude --api-key 'ctxdb-...'
+
+# Repair hooks/plugin/skills using the Agent's stored configuration
+ctxdb setup --agent codex
+
+# Replace only this Agent's API key
+ctxdb setup --agent codex --api-key 'ctxdb-new-...'
+
+# Inspect current local/configuration/connectivity state
+ctxdb status --agent codex --json
 ```
 
 Setup first checks that the target agent home exists (`~/.qoder`, `~/.qoderwork`, `~/.codex`, or `~/.claude`). If the directory is missing, install or start that agent once before running `ctxdb setup --agent <name>`. OpenCode and Hermes are config-dir style: setup creates `~/.config/opencode` / `~/.hermes` when they are missing.
@@ -52,7 +171,7 @@ Hermes owns this security allowlist, so ctxdb only checks it and never writes ap
 hermes --accept-hooks chat
 ```
 
-This command opens an interactive chat. After Hermes starts, exit the chat and rerun `ctxdb setup --agent hermes`; the allowlist check should then pass.
+This command opens an interactive chat. After Hermes starts, exit the chat and rerun `ctxdb setup --agent hermes`; the allowlist check should then pass. Finally, restart any running Hermes CLI or gateway process so it reloads `config.yaml` and registers the hooks. The public bootstrap installer preserves the hooks in this allowlist-pending state and reports these commands as required follow-up instead of rolling the integration back.
 
 The two ctxdb events are `pre_llm_call` and `post_llm_call`. `ctxdb status --agent hermes` also verifies their exact `(event, command)` pairs and reports the specific missing approval.
 
@@ -70,6 +189,16 @@ ctxdb update --agent codex
 ctxdb update --no-self-update
 ```
 
+For npm-installed copies, eligible interactive `ctxdb` commands also schedule a detached version check at most once every 24 hours. The command never waits for npm: a newly discovered release can be shown only on a later invocation. A successful command may append this hint to stderr:
+
+```text
+ctxdb: update available v1.0.2 → v1.1.0; run `ctxdb update`.
+```
+
+The same release is mentioned at most once every 24 hours. Failed registry checks retry with a one-hour exponential backoff capped at six hours. Checks and hints are suppressed for JSON output, non-interactive stderr, CI, `ctxdb update` / `ctxdb upgrade`, and non-npm layouts. Set `CTXDB_DISABLE_UPDATE_CHECK=1` to opt out completely.
+
+The notifier only reads/writes `~/.ctxdb/cache/version-check.json`; it never installs a package or changes agent setup. Updating remains an explicit `ctxdb update` action.
+
 The existing `--self-update` flag remains accepted for compatibility, but is no longer required. If the npm version check, global install, or setup pass fails, ctxdb prints the manual recovery commands:
 
 ```sh
@@ -99,7 +228,7 @@ For **hermes**, `ctxdb setup --agent hermes` writes two shell hooks under `~/.he
 
 ## CLI
 
-`ctxdb` ships 18 subcommands:
+`ctxdb` ships grouped non-interactive commands:
 
 - **Top-level**: `setup` / `status` / `ping` / `uninstall` / `update` (`upgrade` alias)
 - **Memory**: `memory add|search|list|get|update|delete`
@@ -107,13 +236,53 @@ For **hermes**, `ctxdb setup --agent hermes` writes two shell hooks under `~/.he
 
 See `ctxdb --help`.
 
-`setup` without `--agent` writes `agents.default` in `~/.ctxdb/ctxdb.json` (CLI-only, no hooks or skills); with `--agent <qoder|qoderwork|codex|claude|opencode|hermes>` it writes agent config and installs hooks/plugins + 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`.
+`setup` without `--agent` writes `agents.default` in `~/.ctxdb/ctxdb.json` (CLI-only, no hooks or skills); with `--agent <qoder|qoderwork|codex|claude|opencode|hermes>` it writes agent config and installs hooks/plugins + skills for that harness. Rerunning it repairs integration artifacts and may replace the selected Agent's API key. 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
 memory ("记住 / 请记忆 / 原文记下"); without `--no-infer` the server may
 rewrite, merge, or skip details.
 
+### KB upload completion mode
+
+**Breaking change:** `kb upload-text` and `kb upload-file` now return as soon
+as the service accepts the document. The returned document may still have
+`ingest_status: "processing"`; acceptance does not mean ingestion succeeded.
+
+- Add `--wait` when a script needs the previous behavior: poll until ingestion
+  succeeds, fails, or reaches the existing command timeout.
+- Existing `--no-wait` calls remain valid and behave like the new default.
+- `--wait` and `--no-wait` cannot be combined.
+
+Scripts that relied on implicit terminal polling must migrate to:
+
+```sh
+ctxdb kb upload-text <kb-name> <doc-name> --text="<body>" --wait
+ctxdb kb upload-file <kb-name> <local-path> --wait
+```
+
+### KB file upload policy and large files
+
+`kb upload-file` does not maintain a client-side format allowlist or file-size
+table. It validates only that the local path exists, is a readable regular
+file, then lets the service decide whether the format, per-type size, quota,
+and logical document identity are acceptable. Unknown extensions are sent as
+`application/octet-stream`.
+
+File bytes are streamed from disk with a known multipart size; the CLI does
+not read the complete file into a Buffer. It always attempts the ordinary
+upload endpoint first. If the service returns the dedicated
+`KNOWLEDGE_DIRECT_UPLOAD_REQUIRES_CHUNK` error (`errorCode=6001`) or an
+unstructured HTTP 413, the CLI resolves the KB ID and automatically uses the
+chunk init/part/complete protocol. `--doc-name` and `--file-path` have the same
+logical meaning in both modes.
+
+The first chunk-routing release intentionally sends init, each part, and
+complete only once. It does not automatically retry timeout, connection-loss,
+or response-loss failures because the service cannot yet prove that those
+operations are idempotent. Failures before complete trigger a best-effort
+abort; ambiguous complete failures are returned to the caller.
+
 `kb search <query> [--kb=name1,name2] [--top-k=N] [--threshold=F]` is the
 agent-driven KB recall path — calls `POST /v1/knowledge/query` directly
 (distinct from `memory search --knowledge`, which is a memory + KB hybrid

package/dist/chunk-3PFMHU3C.js

@@ -0,0 +1,442 @@
+#!/usr/bin/env node
+import {
+  CtxdbError
+} from "./chunk-JFTKYEVN.js";
+
+// src/lib/kb.ts
+import {
+  accessSync,
+  constants as fsConstants,
+  existsSync,
+  openAsBlob,
+  statSync
+} from "fs";
+import { basename, extname } from "path";
+import { homedir } from "os";
+import { resolve } from "path";
+import {
+  buildNormalizedGraphContext,
+  extractKnowledgeBaseIds,
+  extractKnowledgeChunkContent,
+  extractKnowledgeChunkSourceLabel,
+  extractKnowledgeChunkTags,
+  partitionKnowledgeChunks
+} from "@aliyunrds/ctxdb-shared";
+var KB_COLLECTION = "/v1/knowledge/knowledge_bases";
+var KB_DETAIL = "/v1/knowledge/knowledge_bases/detail";
+var DOCUMENTS = "/v1/knowledge/documents";
+var FILES = "/v1/knowledge/files";
+var DOCUMENT_DETAIL = "/v1/knowledge/documents/detail";
+var CHUNK_INIT = "/v1/knowledge/files/init-upload";
+var CHUNK_PART = "/v1/knowledge/files/chunks";
+var CHUNK_COMPLETE = "/v1/knowledge/files/complete";
+var CHUNK_ABORT = "/v1/knowledge/files/abort";
+var DEFAULT_POLL_INTERVAL_MS = 1500;
+var DEFAULT_INGEST_TIMEOUT_MS = 3e4;
+var DEFAULT_FILE_INGEST_TIMEOUT_MS = 6e4;
+var DEFAULT_FILE_UPLOAD_TIMEOUT_MS = 2 * 60 * 60 * 1e3;
+var DIRECT_UPLOAD_REQUIRES_CHUNK_ERROR_CODE = 6001;
+var MIME_BY_EXT = {
+  ".pdf": "application/pdf",
+  ".txt": "text/plain",
+  ".md": "text/markdown",
+  ".markdown": "text/markdown",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".doc": "application/msword",
+  ".ppt": "application/vnd.ms-powerpoint",
+  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  ".xls": "application/vnd.ms-excel",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".epub": "application/epub+zip",
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".json": "application/json",
+  ".csv": "text/csv",
+  ".xml": "application/xml",
+  ".rtf": "application/rtf",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".bmp": "image/bmp",
+  ".webp": "image/webp",
+  ".tiff": "image/tiff",
+  ".tif": "image/tiff",
+  ".svg": "image/svg+xml",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".flac": "audio/flac",
+  ".ogg": "audio/ogg",
+  ".m4a": "audio/mp4",
+  ".aac": "audio/aac",
+  ".wma": "audio/x-ms-wma",
+  ".mp4": "video/mp4",
+  ".avi": "video/x-msvideo",
+  ".mov": "video/quicktime",
+  ".mkv": "video/x-matroska",
+  ".webm": "video/webm",
+  ".flv": "video/x-flv",
+  ".wmv": "video/x-ms-wmv",
+  ".3gp": "video/3gpp",
+  ".mpeg": "video/mpeg",
+  ".mpg": "video/mpeg"
+};
+async function listKnowledgeBases(client) {
+  const resp = await client.get(KB_COLLECTION);
+  if (Array.isArray(resp)) return resp;
+  if (resp && typeof resp === "object") {
+    const o = resp;
+    return o.knowledge_bases ?? o.results ?? [];
+  }
+  return [];
+}
+async function createKb(client, kbName, description = "") {
+  return client.postJson(KB_COLLECTION, { name: kbName, description: description || "" });
+}
+async function uploadText(client, kbName, docName, text, mimeType = "text/plain", filePath) {
+  const body = {
+    knowledge_base_name: kbName,
+    name: docName,
+    text,
+    mime_type: mimeType
+  };
+  if (filePath !== void 0 && filePath !== "") body.file_path = filePath;
+  return client.postJson(DOCUMENTS, body);
+}
+async function uploadFile(client, kbName, localPath, options = {}) {
+  const expanded = expandHome(localPath);
+  if (!existsSync(expanded)) throw new Error(`file not found: ${expanded}`);
+  const stat = statSync(expanded);
+  if (!stat.isFile()) throw new Error(`not a file: ${expanded}`);
+  try {
+    accessSync(expanded, fsConstants.R_OK);
+  } catch (error) {
+    throw new Error(
+      `file is not readable: ${expanded}${error?.message ? ` (${error.message})` : ""}`
+    );
+  }
+  const filename = basename(expanded);
+  const docName = options.docName ?? filename;
+  const mime = guessMime(expanded);
+  const content = await openAsBlob(expanded, { type: mime });
+  const fields = {
+    knowledge_base_name: kbName,
+    name: docName
+  };
+  if (options.filePath !== void 0 && options.filePath !== "") {
+    fields.file_path = options.filePath;
+  }
+  const timeoutMs = options.timeoutMs ?? DEFAULT_FILE_UPLOAD_TIMEOUT_MS;
+  try {
+    return await client.postMultipart(
+      FILES,
+      fields,
+      { file: { filename, content, mimeType: mime } },
+      { timeoutMs }
+    );
+  } catch (error) {
+    if (!shouldFallbackToChunk(error)) throw error;
+  }
+  return uploadFileInChunks(client, {
+    kbName,
+    filename,
+    docName,
+    filePath: options.filePath,
+    mime,
+    content,
+    fileSize: stat.size,
+    timeoutMs
+  });
+}
+async function uploadFileInChunks(client, options) {
+  const kb = await client.get(KB_DETAIL, {
+    knowledge_base_name: options.kbName
+  });
+  const knowledgeBaseId = readRequiredString(kb, "id", "knowledge base detail");
+  const initParams = {
+    knowledge_base_id: knowledgeBaseId,
+    file_name: options.filename,
+    name: options.docName,
+    mime_type: options.mime
+  };
+  if (options.filePath !== void 0 && options.filePath !== "") {
+    initParams.file_path = options.filePath;
+  }
+  const initResponse = await client.postJson(
+    CHUNK_INIT,
+    {},
+    initParams,
+    { timeoutMs: options.timeoutMs }
+  );
+  const init = unwrapBox(initResponse, "chunk init");
+  const uploadTicket = readRequiredString(
+    init,
+    "upload_ticket",
+    "chunk init"
+  );
+  const documentId = readRequiredString(init, "document_id", "chunk init");
+  const chunkSize = readRequiredPositiveInteger(
+    init,
+    "chunk_size",
+    "chunk init"
+  );
+  let completeStarted = false;
+  try {
+    if (options.fileSize <= 0) {
+      throw new CtxdbError("chunk upload requires a non-empty file");
+    }
+    const parts = [];
+    let partNumber = 1;
+    for (let offset = 0; offset < options.fileSize; offset += chunkSize) {
+      const end = Math.min(offset + chunkSize, options.fileSize);
+      const partBlob = options.content.slice(offset, end, options.mime);
+      const partResponse = await client.postMultipart(
+        CHUNK_PART,
+        {},
+        {
+          data: {
+            filename: options.filename,
+            content: partBlob,
+            mimeType: options.mime
+          }
+        },
+        {
+          timeoutMs: options.timeoutMs,
+          headers: { "X-Upload-Ticket": uploadTicket },
+          params: { part_number: partNumber }
+        }
+      );
+      const part = unwrapBox(partResponse, `chunk part ${partNumber}`);
+      const returnedPartNumber = readRequiredPositiveInteger(
+        part,
+        "part_number",
+        `chunk part ${partNumber}`
+      );
+      if (returnedPartNumber !== partNumber) {
+        throw new CtxdbError(
+          `chunk part ${partNumber} returned mismatched part_number ${returnedPartNumber}`
+        );
+      }
+      parts.push({
+        part_number: returnedPartNumber,
+        etag: readRequiredString(
+          part,
+          "etag",
+          `chunk part ${partNumber}`
+        )
+      });
+      partNumber += 1;
+    }
+    completeStarted = true;
+    const completeResponse = await client.postJson(
+      CHUNK_COMPLETE,
+      { parts },
+      void 0,
+      {
+        timeoutMs: options.timeoutMs,
+        headers: { "X-Upload-Ticket": uploadTicket }
+      }
+    );
+    const completed = unwrapBox(completeResponse, "chunk complete");
+    const completedDocumentId = readRequiredString(
+      completed,
+      "document_id",
+      "chunk complete"
+    );
+    if (completedDocumentId !== documentId) {
+      throw new CtxdbError(
+        `chunk complete returned mismatched document_id ${completedDocumentId}`
+      );
+    }
+    return getDocument(client, options.kbName, documentId);
+  } catch (error) {
+    if (!completeStarted) {
+      try {
+        await client.postJson(
+          CHUNK_ABORT,
+          {},
+          void 0,
+          {
+            timeoutMs: options.timeoutMs,
+            headers: { "X-Upload-Ticket": uploadTicket }
+          }
+        );
+      } catch {
+      }
+    }
+    throw error;
+  }
+}
+function shouldFallbackToChunk(error) {
+  if (!error || typeof error !== "object") return false;
+  const candidate = error;
+  if (candidate.errorCode === DIRECT_UPLOAD_REQUIRES_CHUNK_ERROR_CODE) {
+    return true;
+  }
+  if (candidate.status !== 413 || candidate.errorCode !== void 0) {
+    return false;
+  }
+  if (typeof candidate.errorMessage === "string" && candidate.errorMessage.trim() !== "") {
+    return false;
+  }
+  const body = candidate.responseBody;
+  if (body && typeof body === "object" && !Array.isArray(body)) {
+    const fields = body;
+    if (["errorCode", "errorMessage", "detail", "message", "error"].some((field) => Object.hasOwn(fields, field))) {
+      return false;
+    }
+  }
+  return true;
+}
+function unwrapBox(response, operation) {
+  if (!response || typeof response !== "object" || Array.isArray(response)) {
+    throw new CtxdbError(`${operation} returned an invalid response`);
+  }
+  const box = response;
+  if (typeof box.errorCode === "number" && box.errorCode !== 0) {
+    const message = typeof box.errorMessage === "string" && box.errorMessage ? box.errorMessage : `errorCode=${box.errorCode}`;
+    throw new CtxdbError(`${operation} failed: ${message}`);
+  }
+  if (!box.data || typeof box.data !== "object" || Array.isArray(box.data)) {
+    throw new CtxdbError(`${operation} returned no data`);
+  }
+  return box.data;
+}
+function readRequiredString(value, field, source) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new CtxdbError(`${source} returned an invalid response`);
+  }
+  const result = value[field];
+  if (typeof result !== "string" || result.trim() === "") {
+    throw new CtxdbError(`${source} returned invalid ${field}`);
+  }
+  return result;
+}
+function readRequiredPositiveInteger(value, field, source) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new CtxdbError(`${source} returned an invalid response`);
+  }
+  const result = value[field];
+  if (typeof result !== "number" || !Number.isSafeInteger(result) || result <= 0) {
+    throw new CtxdbError(`${source} returned invalid ${field}`);
+  }
+  return result;
+}
+function guessMime(path) {
+  const ext = extname(path).toLowerCase();
+  if (ext in MIME_BY_EXT) return MIME_BY_EXT[ext];
+  return "application/octet-stream";
+}
+async function getDocument(client, kbName, docId) {
+  return client.get(DOCUMENT_DETAIL, {
+    knowledge_base_name: kbName,
+    document_id: docId
+  });
+}
+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;
+    return o.documents ?? o.results ?? [];
+  }
+  return [];
+}
+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, kbName, docId);
+  let timedOut = false;
+  while (ingestInFlight(doc)) {
+    if (now() >= deadline) {
+      timedOut = true;
+      break;
+    }
+    await sleep(intervalMs);
+    try {
+      doc = await getDocument(client, kbName, docId);
+    } catch {
+      break;
+    }
+  }
+  if (doc && typeof doc === "object") {
+    return { ...doc, _pollingTimedOut: timedOut };
+  }
+  return { _pollingTimedOut: timedOut };
+}
+function ingestInFlight(doc) {
+  if (!doc || typeof doc !== "object") return false;
+  const status = doc.ingest_status;
+  return status === "processing" || status === "pending" || status === "in_progress";
+}
+function expandHome(p) {
+  if (p.startsWith("~/") || p === "~") {
+    return resolve(homedir(), p.slice(2));
+  }
+  return resolve(p);
+}
+function compactChunk(raw) {
+  const c = raw ?? {};
+  const content = extractKnowledgeChunkContent(raw);
+  const doc_name = extractKnowledgeChunkSourceLabel(raw);
+  const kb_id = extractKnowledgeBaseIds(raw)[0] ?? "";
+  const docIdRaw = c.doc_id;
+  const scoreRaw = c.similarity ?? c.rerank_score;
+  const tags = extractKnowledgeChunkTags(raw);
+  const out = {
+    content,
+    doc_name,
+    kb_id,
+    score: typeof scoreRaw === "number" ? scoreRaw : 0
+  };
+  if (typeof docIdRaw === "string" && docIdRaw.length > 0) {
+    out.doc_id = docIdRaw;
+  }
+  if (tags.length > 0) {
+    out.tags = tags;
+  }
+  return out;
+}
+function projectKbQueryResponse(raw, projectChunk, options = {}) {
+  if (!raw || typeof raw !== "object") return { chunks: [] };
+  const r = raw;
+  const chunksIn = Array.isArray(r.chunks) ? r.chunks : [];
+  const { graphChunks, documentChunks } = partitionKnowledgeChunks(chunksIn);
+  const graphContext = buildNormalizedGraphContext(graphChunks, {
+    verbose: options.verboseGraph
+  });
+  const out = {
+    chunks: documentChunks.map(projectChunk)
+  };
+  if (typeof r.total === "number") out.total = r.total;
+  if (graphContext) out.graph_context = graphContext;
+  return out;
+}
+function compactKbQueryResponse(raw) {
+  return projectKbQueryResponse(raw, compactChunk, { verboseGraph: true });
+}
+function minimalChunk(raw) {
+  const c = compactChunk(raw);
+  return { content: c.content, score: c.score };
+}
+function minimalKbQueryResponse(raw) {
+  return projectKbQueryResponse(raw, minimalChunk);
+}
+
+export {
+  DEFAULT_INGEST_TIMEOUT_MS,
+  DEFAULT_FILE_INGEST_TIMEOUT_MS,
+  DEFAULT_FILE_UPLOAD_TIMEOUT_MS,
+  listKnowledgeBases,
+  createKb,
+  uploadText,
+  uploadFile,
+  getDocument,
+  listDocuments,
+  pollIngest,
+  compactKbQueryResponse,
+  minimalKbQueryResponse
+};