@numa-tech/numa 1.20.3 → 1.20.4

package/dist/kb/commands.js

@@ -0,0 +1,121 @@
+import process from "node:process";
+import { KbClient } from "./client.js";
+import { loadKbConfig } from "./config.js";
+import { KbError, sanitizeKbOutput } from "./errors.js";
+import { uploadToKb, downloadFromKb, waitForTask } from "./transfers.js";
+import { KB_COMMAND_CATALOG } from "./catalog.js";
+export { KB_COMMAND_CATALOG };
+function integer(value, name, max) {
+    if (!/^\d+$/u.test(value) || Number(value) < 1 || Number(value) > max) {
+        throw new KbError(`${name} 必须是 1-${max} 的整数。`, "kb_input_invalid");
+    }
+    return Number(value);
+}
+function taskKind(id, kind) {
+    if (kind !== undefined && kind !== "archive" && kind !== "batch") {
+        throw new KbError("--kind 必须是 archive 或 batch。", "kb_input_invalid");
+    }
+    return kind ?? (id.startsWith("ext_") ? "batch" : "archive");
+}
+async function interruptible(work) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    process.once("SIGINT", abort);
+    process.once("SIGTERM", abort);
+    try {
+        return await work(controller.signal);
+    }
+    finally {
+        process.removeListener("SIGINT", abort);
+        process.removeListener("SIGTERM", abort);
+    }
+}
+export function registerKbCommands(program, dependencies = {}) {
+    const client = async () => dependencies.clientFactory?.() ?? new KbClient(await loadKbConfig());
+    const output = (value) => (dependencies.write ?? ((text) => process.stdout.write(text)))(`${JSON.stringify({ ok: true, data: sanitizeKbOutput(value) }, null, 2)}\n`);
+    // Only explicit progress fields are rendered; tickets and response payloads never reach stderr.
+    const progress = (value) => {
+        if (!value || typeof value !== "object")
+            return;
+        const item = value;
+        const parts = [];
+        if (typeof item.phase === "string" && /^[a-z_-]{1,40}$/u.test(item.phase))
+            parts.push(item.phase);
+        if (typeof item.transferred === "number" && Number.isFinite(item.transferred))
+            parts.push(`${item.transferred} bytes`);
+        if (parts.length)
+            (dependencies.writeProgress ?? ((text) => process.stderr.write(text)))(`${parts.join(" ")}\n`);
+    };
+    const kb = program.command("kb").description("知识库检索、原件传输和入库任务；通过 KB REST API 复用 OSS 传输")
+        .addHelpText("after", "\n配置：Profile services.kb 或 NUMA_KB_BASE_URL；NUMA_KB_API_KEY / NUMA_KB_API_KEY_FILE。\n默认使用 Numa Keycloak 登录，NUMA_KB_AUTH_MODE=api-key 可显式选择仅 API Key 的部署。\n");
+    const collections = kb.command("collections").description("当前身份可见的知识库");
+    collections.command("list").description("列出知识库").action(async () => output(await (await client()).listCollections()));
+    collections.command("create").description("创建私有任务知识库")
+        .requiredOption("--name <name>", "知识库名称")
+        .option("--description <text>", "知识库说明")
+        .action(async (options) => {
+        if (!options.name.trim() || options.name.length > 50)
+            throw new KbError("名称须为 1-50 个字符。", "kb_input_invalid");
+        output(await (await client()).createCollection({ name: options.name, description: options.description }));
+    });
+    kb.command("search <query>").description("检索文档内容与来源")
+        .requiredOption("--collection-id <id>", "目标知识库 ID")
+        .option("--top-k <number>", "返回片段数 1-10", "5")
+        .option("--min-score <number>", "最低相关度 0-1", "0")
+        .action(async (query, options) => {
+        const top = integer(options.topK, "--top-k", 10);
+        const score = Number(options.minScore);
+        if (!query.trim() || !options.minScore.trim() || !Number.isFinite(score) || score < 0 || score > 1) {
+            throw new KbError("查询不能为空，--min-score 须为 0-1。", "kb_input_invalid");
+        }
+        output(await (await client()).search({ query, collection_id: options.collectionId, top_k: top, min_score: score }));
+    });
+    kb.command("upload <path>").description("上传普通文件或递归目录，并提交入库；支持文件级恢复")
+        .requiredOption("--collection-id <id>", "目标知识库 ID")
+        .option("--state-file <path>", "本地私有恢复记录，自动生成时在结果中返回")
+        .option("--resume", "使用既有恢复记录继续；须同时指定 --state-file")
+        .option("--batch-size <number>", "每批文件数 1-50", "50")
+        .option("--concurrency <number>", "同时传输文件数 1-10", "3")
+        .option("--wait", "等待解析入库完成")
+        .option("--timeout <seconds>", "等待入库的最长秒数", "600")
+        .action(async (path, options) => {
+        const batchSize = integer(options.batchSize, "--batch-size", 50);
+        const concurrency = integer(options.concurrency, "--concurrency", 10);
+        const timeoutMs = integer(options.timeout, "--timeout", 86_400) * 1000;
+        if (options.resume && !options.stateFile)
+            throw new KbError("--resume 必须同时指定 --state-file。", "kb_input_invalid");
+        const api = await client();
+        output(await interruptible(signal => (dependencies.upload ?? uploadToKb)(api, {
+            path, collectionId: options.collectionId, stateFile: options.stateFile, resume: options.resume,
+            batchSize, concurrency, wait: options.wait, timeoutMs, signal, onProgress: progress,
+        })));
+    });
+    kb.command("download <document-id>").description("下载已授权原件，校验后保存；不覆盖现有文件")
+        .requiredOption("--output <path>", "保存到指定文件路径")
+        .action(async (documentId, options) => {
+        const api = await client();
+        output(await interruptible(signal => (dependencies.download ?? downloadFromKb)(api, {
+            documentId, output: options.output, signal, onProgress: progress,
+        })));
+    });
+    const tasks = kb.command("tasks").description("查看和重试解析入库任务");
+    tasks.command("status <task-id>").description("查询任务及逐文件结果")
+        .option("--kind <kind>", "archive 或 batch；ext_ 前缀默认 batch")
+        .option("--wait", "等待终态；失败、部分失败或需要处理冲突时返回非零退出码")
+        .option("--timeout <seconds>", "最长等待秒数", "600")
+        .action(async (id, options) => {
+        const kind = taskKind(id, options.kind);
+        const timeoutMs = integer(options.timeout, "--timeout", 86_400) * 1000;
+        const api = await client();
+        output(options.wait
+            ? await interruptible(signal => (dependencies.wait ?? waitForTask)(api, id, { kind, timeoutMs, signal }))
+            : await api.getTask(id, kind));
+    });
+    tasks.command("retry <task-id>").description("显式重试可恢复的失败入库项")
+        .option("--kind <kind>", "archive 或 batch；ext_ 前缀默认 batch")
+        .action(async (id, options) => {
+        const kind = taskKind(id, options.kind);
+        output(await (await client()).retryTask(id, kind));
+    });
+}
+//# sourceMappingURL=commands.js.map

package/dist/kb/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../src/kb/commands.ts"],"names":[],"mappings":"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"}

package/dist/kb/config.d.ts

@@ -0,0 +1,15 @@
+import { type AuthConfig } from "../config.js";
+export interface KbConfig {
+    baseUrl: string;
+    apiKey: string;
+    authMode: "keycloak" | "api-key";
+    auth?: AuthConfig;
+    tenantHeader?: {
+        name: string;
+        value: string;
+    };
+}
+export declare function validateKbBaseUrl(value: string): string;
+export declare function loadKbConfig(): Promise<KbConfig>;
+/** Uses the same governed authority and token cache as KB requests, without requiring a KB API key. */
+export declare function loadKbAuthConfig(): AuthConfig;

package/dist/kb/config.js

@@ -0,0 +1,76 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { appConfigDirectory } from "../app-config.js";
+import { loadConfig } from "../config.js";
+import { requireProfileService } from "../platform-profile.js";
+import { KbError } from "./errors.js";
+export function validateKbBaseUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new KbError("KB base URL is invalid.", "kb_config_invalid");
+    }
+    const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    if ((url.protocol !== "https:" && !(url.protocol === "http:" && local)) || url.username || url.password || url.search || url.hash) {
+        throw new KbError("KB base URL must use HTTPS without credentials, query or fragment (loopback HTTP allowed).", "kb_config_invalid");
+    }
+    return url.toString().replace(/\/+$/u, "");
+}
+export async function loadKbConfig() {
+    const selected = requireProfileService("kb");
+    const explicit = process.env.NUMA_KB_BASE_URL?.trim();
+    const base = selected?.service.baseUrl ?? explicit;
+    if (!base)
+        throw new KbError("Configure services.kb in the platform profile or NUMA_KB_BASE_URL.", "kb_config_missing");
+    const baseUrl = validateKbBaseUrl(base);
+    if (selected && explicit && validateKbBaseUrl(explicit) !== baseUrl) {
+        throw new KbError("NUMA_KB_BASE_URL cannot override the profile KB service.", "kb_config_invalid");
+    }
+    const mode = process.env.NUMA_KB_AUTH_MODE?.trim() || "keycloak";
+    if (mode !== "keycloak" && mode !== "api-key")
+        throw new KbError("NUMA_KB_AUTH_MODE must be keycloak or api-key.", "kb_config_invalid");
+    const keyEnv = process.env.NUMA_KB_API_KEY;
+    const keyFile = process.env.NUMA_KB_API_KEY_FILE;
+    if (keyEnv !== undefined && keyFile !== undefined)
+        throw new KbError("Set only one of NUMA_KB_API_KEY and NUMA_KB_API_KEY_FILE.", "kb_config_invalid");
+    let apiKey = keyEnv?.trim();
+    if (keyFile) {
+        try {
+            apiKey = (await readFile(keyFile, "utf8")).trim();
+        }
+        catch {
+            throw new KbError("Cannot read NUMA_KB_API_KEY_FILE.", "kb_config_invalid");
+        }
+    }
+    if (!apiKey || /[\u0000-\u0020\u007f]/u.test(apiKey))
+        throw new KbError("A valid KB API key is required.", "kb_config_missing");
+    const auth = mode === "keycloak" ? loadKbAuthConfig() : undefined;
+    return { baseUrl, apiKey, authMode: mode, auth,
+        ...(selected ? { tenantHeader: { name: selected.profile.tenant.headerName, value: selected.profile.tenant.id } } : {}) };
+}
+/** Uses the same governed authority and token cache as KB requests, without requiring a KB API key. */
+export function loadKbAuthConfig() {
+    const selected = requireProfileService("kb");
+    const explicit = process.env.NUMA_KB_BASE_URL?.trim();
+    const base = selected?.service.baseUrl ?? explicit;
+    if (!base)
+        throw new KbError("Configure services.kb or NUMA_KB_BASE_URL.", "kb_config_missing");
+    const baseUrl = validateKbBaseUrl(base);
+    if (selected && explicit && validateKbBaseUrl(explicit) !== baseUrl)
+        throw new KbError("NUMA_KB_BASE_URL cannot override the profile KB service.", "kb_config_invalid");
+    let auth = loadConfig("kb");
+    if (selected) {
+        // Older profiles allow global overrides in loadConfig; KB always honors its declared authority.
+        const clientId = auth.authenticationMode === "client_credentials" ? auth.clientId : selected.authority.clientId;
+        const tokenKey = createHash("sha256").update(`${selected.authority.issuer}\0${clientId}\0${selected.profile.tenant.id}\0${selected.service.audience}`).digest("hex").slice(0, 24);
+        auth = { ...auth, discoveryUrl: selected.authority.discoveryUrl, issuerUrl: selected.authority.issuer,
+            clientId, resourceAudience: selected.service.audience, profileTenantId: selected.profile.tenant.id,
+            tokenFile: join(appConfigDirectory(), `keycloak-token-${tokenKey}.json`),
+            scope: auth.authenticationMode === "client_credentials" ? auth.scope : selected.authority.scopes.join(" ") };
+    }
+    return { ...auth, backendBaseUrl: baseUrl };
+}
+//# sourceMappingURL=config.js.map

package/dist/kb/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/kb/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAmB,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAUtC,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QAAC,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,MAAM,IAAI,OAAO,CAAC,yBAAyB,EAAE,mBAAmB,CAAC,CAAC;IAAC,CAAC;IAC1G,MAAM,KAAK,GAAG,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACzE,IAAI,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QAClI,MAAM,IAAI,OAAO,CAAC,4FAA4F,EAAE,mBAAmB,CAAC,CAAC;IACvI,CAAC;IACD,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,MAAM,QAAQ,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,IAAI,EAAE,CAAC;IACtD,MAAM,IAAI,GAAG,QAAQ,EAAE,OAAO,CAAC,OAAO,IAAI,QAAQ,CAAC;IACnD,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,OAAO,CAAC,oEAAoE,EAAE,mBAAmB,CAAC,CAAC;IACxH,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,QAAQ,IAAI,QAAQ,IAAI,iBAAiB,CAAC,QAAQ,CAAC,KAAK,OAAO,EAAE,CAAC;QACpE,MAAM,IAAI,OAAO,CAAC,0DAA0D,EAAE,mBAAmB,CAAC,CAAC;IACrG,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,IAAI,EAAE,IAAI,UAAU,CAAC;IACjE,IAAI,IAAI,KAAK,UAAU,IAAI,IAAI,KAAK,SAAS;QAAE,MAAM,IAAI,OAAO,CAAC,gDAAgD,EAAE,mBAAmB,CAAC,CAAC;IACxI,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAC3C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;IACjD,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS;QAAE,MAAM,IAAI,OAAO,CAAC,2DAA2D,EAAE,mBAAmB,CAAC,CAAC;IACvJ,IAAI,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,CAAC;IAC5B,IAAI,OAAO,EAAE,CAAC;QACZ,IAAI,CAAC;YAAC,MAAM,GAAG,CAAC,MAAM,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAAC,CAAC;QAC1D,MAAM,CAAC;YAAC,MAAM,IAAI,OAAO,CAAC,mCAAmC,EAAE,mBAAmB,CAAC,CAAC;QAAC,CAAC;IACxF,CAAC;IACD,IAAI,CAAC,MAAM,IAAI,wBAAwB,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,OAAO,CAAC,iCAAiC,EAAE,mBAAmB,CAAC,CAAC;IAChI,MAAM,IAAI,GAAG,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAClE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI;QAC5C,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC7H,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,gBAAgB;IAC9B,MAAM,QAAQ,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,IAAI,EAAE,CAAC;IACtD,MAAM,IAAI,GAAG,QAAQ,EAAE,OAAO,CAAC,OAAO,IAAI,QAAQ,CAAC;IACnD,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,OAAO,CAAC,4CAA4C,EAAE,mBAAmB,CAAC,CAAC;IAChG,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,QAAQ,IAAI,QAAQ,IAAI,iBAAiB,CAAC,QAAQ,CAAC,KAAK,OAAO;QAAE,MAAM,IAAI,OAAO,CAAC,0DAA0D,EAAE,mBAAmB,CAAC,CAAC;IACxK,IAAI,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,QAAQ,EAAE,CAAC;QACb,gGAAgG;QAChG,MAAM,QAAQ,GAAG,IAAI,CAAC,kBAAkB,KAAK,oBAAoB,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC;QAChH,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,SAAS,CAAC,MAAM,KAAK,QAAQ,KAAK,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,KAAK,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAClL,IAAI,GAAG,EAAE,GAAG,IAAI,EAAE,YAAY,EAAE,QAAQ,CAAC,SAAS,CAAC,YAAY,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,CAAC,MAAM;YACnG,QAAQ,EAAE,gBAAgB,EAAE,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,eAAe,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;YAClG,SAAS,EAAE,IAAI,CAAC,kBAAkB,EAAE,EAAE,kBAAkB,QAAQ,OAAO,CAAC;YACxE,KAAK,EAAE,IAAI,CAAC,kBAAkB,KAAK,oBAAoB,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IACjH,CAAC;IACD,OAAO,EAAE,GAAG,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC;AAC9C,CAAC"}

package/dist/kb/errors.d.ts

@@ -0,0 +1,9 @@
+/** Only locally generated messages belong here; never interpolate remote response bodies. */
+export declare class KbError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, status?: number | undefined, details?: Record<string, unknown> | undefined);
+}
+/** Output-only projection. Transport code must keep using the original ticket. */
+export declare function sanitizeKbOutput(value: unknown): unknown;

package/dist/kb/errors.js

@@ -0,0 +1,31 @@
+/** Only locally generated messages belong here; never interpolate remote response bodies. */
+export class KbError extends Error {
+    code;
+    status;
+    details;
+    constructor(message, code, status, details) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.details = details;
+        this.name = "KbError";
+    }
+}
+const secretKey = /(?:authorization|api.?key|access.?token|refresh.?token|id.?token|secret|password|cookie|credential|signature|ticket|^token$|^upload$|^headers$)/iu;
+const urlKey = /(?:url|uri)$/iu;
+/** Output-only projection. Transport code must keep using the original ticket. */
+export function sanitizeKbOutput(value) {
+    if (Array.isArray(value))
+        return value.map(sanitizeKbOutput);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).filter(([key]) => !secretKey.test(key) && !urlKey.test(key))
+            .map(([key, item]) => [key, sanitizeKbOutput(item)]));
+    }
+    if (typeof value === "string") {
+        return value.replace(/https?:\/\/[^\s<>"']+/giu, "[redacted URL]")
+            .replace(/\bBearer\s+[^\s,;]+/giu, "Bearer [redacted]")
+            .replace(/((?:api[-_ ]?key|access[-_ ]?token|refresh[-_ ]?token|password|secret)\s*[:=]\s*)[^\s,;]+/giu, "$1[redacted]");
+    }
+    return value;
+}
+//# sourceMappingURL=errors.js.map

package/dist/kb/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/kb/errors.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,MAAM,OAAO,OAAQ,SAAQ,KAAK;IACM,IAAI;IAAmB,MAAM;IAAoB,OAAO;IAA9F,YAAY,OAAe,EAAW,IAAY,EAAW,MAAe,EAAW,OAAiC;QACtH,KAAK,CAAC,OAAO,CAAC,CAAC;oBADqB,IAAI;sBAAmB,MAAM;uBAAoB,OAAO;QAE5F,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC;IACxB,CAAC;CACF;AAED,MAAM,SAAS,GAAG,mJAAmJ,CAAC;AACtK,MAAM,MAAM,GAAG,gBAAgB,CAAC;AAEhC,kFAAkF;AAClF,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC7D,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;aACzG,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC,OAAO,CAAC,0BAA0B,EAAE,gBAAgB,CAAC;aAC/D,OAAO,CAAC,wBAAwB,EAAE,mBAAmB,CAAC;aACtD,OAAO,CAAC,8FAA8F,EAAE,cAAc,CAAC,CAAC;IAC7H,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/kb/transfers.d.ts

@@ -0,0 +1,67 @@
+import type { BeginUploadRequest, DirectUploadSession, UploadSession, DownloadTicket, ProxyUploadRequest, KbTask, TaskKind } from './types.js';
+export interface KbTransferClient {
+    readonly binding: string;
+    beginUpload(input: BeginUploadRequest): Promise<UploadSession>;
+    getUpload(sessionId: string, renew?: boolean): Promise<DirectUploadSession>;
+    completeUpload(sessionId: string): Promise<DirectUploadSession>;
+    proxyUpload(input: ProxyUploadRequest): Promise<KbTask>;
+    downloadTicket(documentId: string): Promise<DownloadTicket>;
+    downloadProxy(ticket: DownloadTicket, signal?: AbortSignal): Promise<Response>;
+    getTask(taskId: string, kind?: TaskKind): Promise<KbTask>;
+}
+export interface TransferProgress {
+    phase: string;
+    filename?: string;
+    transferred?: number;
+    total?: number;
+    taskId?: string;
+    status?: string;
+}
+export interface UploadInput {
+    path: string;
+    collectionId: string;
+    stateFile?: string;
+    resume?: boolean;
+    batchSize?: number;
+    concurrency?: number;
+    wait?: boolean;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    onProgress?: (progress: TransferProgress) => void;
+}
+export interface TransferDependencies {
+    fetchImpl?: typeof fetch;
+    stateRoot?: string;
+    pollIntervalMs?: number;
+    transferTimeoutMs?: number;
+}
+export declare function uploadToKb(client: KbTransferClient, input: UploadInput, deps?: TransferDependencies): Promise<{
+    state_file: string;
+    collection_id: string;
+    files: number;
+    batches: {
+        batch_id: string;
+        kind: TaskKind;
+        status: string;
+    }[];
+    tasks?: KbTask[];
+}>;
+export interface WaitOptions {
+    kind?: TaskKind;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    pollIntervalMs?: number;
+    onProgress?: (progress: TransferProgress) => void;
+}
+export declare function waitForTask(client: Pick<KbTransferClient, 'getTask'>, taskId: string, options?: WaitOptions): Promise<KbTask>;
+export declare function downloadFromKb(client: Pick<KbTransferClient, 'downloadTicket' | 'downloadProxy'>, input: {
+    documentId: string;
+    output: string;
+    signal?: AbortSignal;
+    onProgress?: (progress: TransferProgress) => void;
+}, deps?: TransferDependencies): Promise<{
+    output: string;
+    size_bytes: number;
+    sha256: string;
+    document_id: string;
+}>;

package/dist/kb/transfers.js

@@ -0,0 +1,257 @@
+import { lstat, readdir } from 'node:fs/promises';
+import { basename, join, relative, resolve, isAbsolute } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash, randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { runTransferPool } from '../oss/transfer-pool.js';
+import { digestFile, putSignedFile, downloadSignedFile, rejectSymlinks, SignedTransferError } from '../oss/signed-url-transfers.js';
+import { KbError } from './errors.js';
+import { lockUploadState, readUploadState, writeUploadState } from './upload-state.js';
+const fail = (message, code = 'kb_input_invalid', details) => new KbError(message, code, undefined, details);
+async function scan(path, signal) {
+    const paths = [];
+    async function walk(current) {
+        signal?.throwIfAborted();
+        await rejectSymlinks(current);
+        const stat = await lstat(current);
+        if (stat.isDirectory()) {
+            for (const name of (await readdir(current)).sort())
+                await walk(join(current, name));
+        }
+        else if (stat.isFile())
+            paths.push(current);
+        else
+            throw fail('Only regular files and directories are accepted.');
+    }
+    await walk(resolve(path));
+    if (!paths.length)
+        throw fail('Upload directory has no files.');
+    const names = new Set(), result = [];
+    for (const path of paths.sort()) {
+        const filename = basename(path);
+        if (filename.length > 255 || /[\u0000-\u001f\u007f]/u.test(filename))
+            throw fail('Upload filename is invalid.');
+        if (names.has(filename))
+            throw fail('Upload contains duplicate filenames; use separate uploads for each directory.');
+        names.add(filename);
+        result.push({ ...await digestFile(path, signal), filename, content_type: 'application/octet-stream' });
+    }
+    return result;
+}
+function batches(files, batchSize) {
+    const result = [];
+    let indexes = [], bytes = 0;
+    function flush() { if (indexes.length)
+        result.push({ requestId: `numa-kb-${randomUUID()}`, fileIndexes: indexes }); indexes = []; bytes = 0; }
+    files.forEach((file, index) => { if (indexes.length >= batchSize || bytes + file.size_bytes > 1024 ** 3)
+        flush(); indexes.push(index); bytes += file.size_bytes; });
+    flush();
+    return result;
+}
+function verifySession(session, batch, state) {
+    if (session.collection_id !== state.collectionId || session.request_id !== batch.requestId || (batch.sessionId && session.session_id !== batch.sessionId) || (batch.batchId && session.batch_id !== batch.batchId) || session.files.length !== batch.fileIndexes.length)
+        throw fail('Upload session does not match the saved request.', 'kb_protocol_error');
+    const filenames = new Set();
+    for (const remote of session.files) {
+        const local = batch.fileIndexes.map(index => state.files[index]).find(file => file.filename === remote.filename);
+        if (!local || filenames.has(remote.filename) || remote.size_bytes !== local.size_bytes || remote.sha256 !== local.sha256 || remote.content_md5 !== local.content_md5 || remote.content_type !== local.content_type)
+            throw fail('Upload session content does not match the local manifest.', 'kb_protocol_error');
+        filenames.add(remote.filename);
+    }
+    if (session.status !== 'uploading' && session.status !== 'submitted')
+        throw fail('Upload session has expired or was cancelled; start a new upload with a new state file.', 'kb_session_unavailable');
+}
+export async function uploadToKb(client, input, deps = {}) {
+    const sourcePath = resolve(input.path), batchSize = input.batchSize ?? 50, concurrency = input.concurrency ?? 3;
+    if (!input.collectionId.trim() || !Number.isInteger(batchSize) || batchSize < 1 || batchSize > 50 || !Number.isInteger(concurrency) || concurrency < 1 || concurrency > 32)
+        throw fail('Batch size must be 1–50 and concurrency 1–32.');
+    const key = createHash('sha256').update(JSON.stringify([client.binding, input.collectionId, sourcePath])).digest('hex');
+    const stateFile = resolve(input.stateFile ?? join(deps.stateRoot ?? join(homedir(), '.numa', 'kb', 'uploads'), `${key}.json`));
+    const child = relative(sourcePath, stateFile);
+    if (!child || (!child.startsWith('..') && !isAbsolute(child)))
+        throw fail('Upload state must be outside the uploaded source path.');
+    const release = await lockUploadState(stateFile);
+    try {
+        input.signal?.throwIfAborted();
+        input.onProgress?.({ phase: 'scanning' });
+        const files = await scan(sourcePath, input.signal);
+        let state;
+        if (input.resume) {
+            state = await readUploadState(stateFile);
+            if (state.binding !== client.binding || state.collectionId !== input.collectionId || state.sourcePath !== sourcePath)
+                throw fail('Saved upload belongs to a different KB target or identity.', 'kb_state_binding_mismatch');
+            if (state.files.length !== files.length || state.files.some((saved, index) => { const current = files[index]; return saved.path !== current.path || saved.filename !== current.filename || saved.size_bytes !== current.size_bytes || saved.sha256 !== current.sha256 || saved.content_md5 !== current.content_md5 || saved.content_type !== current.content_type; }))
+                throw fail('Upload source differs from the saved manifest.', 'kb_source_changed');
+            if (state.batches.some(batch => batch.fileIndexes.reduce((sum, index) => sum + files[index].size_bytes, 0) > 1024 ** 3))
+                throw fail('Saved upload batch exceeds the size limit.', 'kb_state_invalid');
+        }
+        else {
+            try {
+                await lstat(stateFile);
+                throw fail('Upload state already exists; use --resume or choose a new --state-file.', 'kb_state_exists');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            state = { version: 1, binding: client.binding, collectionId: input.collectionId, sourcePath, files, batches: batches(files, batchSize) };
+            await writeUploadState(stateFile, state);
+        }
+        for (const batch of state.batches) {
+            input.signal?.throwIfAborted();
+            if (batch.submitted)
+                continue;
+            const locals = batch.fileIndexes.map(index => state.files[index]);
+            let session = batch.sessionId ? await client.getUpload(batch.sessionId, true) : batch.transport === 'proxy' ? { transport: 'proxy' } : await client.beginUpload({ collection_id: state.collectionId, request_id: batch.requestId, files: locals.map(({ path: _path, ...metadata }) => metadata) });
+            input.signal?.throwIfAborted();
+            if (session.transport === 'proxy') {
+                batch.transport = 'proxy';
+                await writeUploadState(stateFile, state);
+                // Verify immediately before handing files to the multipart adapter.
+                for (const file of locals)
+                    if ((await digestFile(file.path, input.signal)).sha256 !== file.sha256)
+                        throw fail('Upload source changed.', 'kb_source_changed');
+                const task = await client.proxyUpload({ collectionId: state.collectionId, requestId: batch.requestId, files: locals.map(file => ({ path: file.path, filename: file.filename })), signal: input.signal });
+                batch.batchId = task.batch_id;
+                batch.submitted = true;
+                await writeUploadState(stateFile, state);
+                for (const file of locals)
+                    if ((await digestFile(file.path, input.signal)).sha256 !== file.sha256)
+                        throw fail('Upload source changed during proxy upload.', 'kb_source_changed');
+                continue;
+            }
+            verifySession(session, batch, state);
+            batch.transport = 'direct';
+            batch.sessionId = session.session_id;
+            batch.batchId = session.batch_id;
+            await writeUploadState(stateFile, state);
+            if (session.status !== 'submitted') {
+                const current = session;
+                await runTransferPool(current.files, concurrency, async (remote) => {
+                    const local = locals.find(file => file.filename === remote.filename);
+                    if (remote.object_uploaded) {
+                        input.onProgress?.({ phase: 'uploaded', filename: local.filename, transferred: local.size_bytes, total: local.size_bytes });
+                        return;
+                    }
+                    if (!remote.upload)
+                        throw fail('Upload ticket is missing.', 'kb_protocol_error');
+                    try {
+                        await putSignedFile(remote.upload, local, { signal: input.signal, fetchImpl: deps.fetchImpl, timeoutMs: deps.transferTimeoutMs, onProgress: (transferred, total) => input.onProgress?.({ phase: 'uploading', filename: local.filename, transferred, total: total ?? undefined }) });
+                    }
+                    catch (error) {
+                        if (input.signal?.aborted || (error instanceof SignedTransferError && error.code !== 'kb_transfer_failed'))
+                            throw error;
+                        // A PUT response may be lost after the object was stored. Read before retrying.
+                        const renewed = await client.getUpload(current.session_id, true);
+                        verifySession(renewed, batch, state);
+                        const item = renewed.files.find(file => file.file_id === remote.file_id);
+                        if (item?.object_uploaded || renewed.status === 'submitted')
+                            return;
+                        if (!item?.upload)
+                            throw error;
+                        await putSignedFile(item.upload, local, { signal: input.signal, fetchImpl: deps.fetchImpl, timeoutMs: deps.transferTimeoutMs });
+                    }
+                }, input.signal);
+                // Covers skipped objects and changes between hashing and upload completion.
+                for (const file of locals)
+                    if ((await digestFile(file.path, input.signal)).sha256 !== file.sha256)
+                        throw fail('Upload source changed.', 'kb_source_changed');
+                input.signal?.throwIfAborted();
+                session = await client.completeUpload(current.session_id);
+                verifySession(session, batch, state);
+                if (session.status !== 'submitted')
+                    throw fail('Upload completion did not submit a task.', 'kb_protocol_error');
+            }
+            batch.submitted = true;
+            await writeUploadState(stateFile, state);
+        }
+        const submitted = state.batches.map(batch => ({ batch_id: batch.batchId, kind: (batch.transport === 'proxy' ? 'batch' : 'archive'), status: 'submitted' }));
+        const tasks = [];
+        const waitDeadline = Date.now() + (input.timeoutMs ?? 10 * 60_000);
+        if (input.wait)
+            for (const batch of submitted) {
+                const remaining = waitDeadline - Date.now();
+                if (remaining <= 0)
+                    throw fail('Timed out waiting for KB tasks; query the saved task IDs.', 'kb_task_timeout', { batches: submitted });
+                tasks.push(await waitForTask(client, batch.batch_id, { kind: batch.kind, timeoutMs: remaining, signal: input.signal, onProgress: input.onProgress, pollIntervalMs: deps.pollIntervalMs }));
+            }
+        return { state_file: stateFile, collection_id: state.collectionId, files: state.files.length, batches: submitted, ...(input.wait ? { tasks } : {}) };
+    }
+    catch (error) {
+        if (input.signal?.aborted)
+            throw fail('Upload interrupted; submission may have completed. Resume with the saved state to reconcile it.', 'kb_aborted', { state_file: stateFile });
+        if (error instanceof KbError)
+            throw new KbError(error.message, error.code, error.status, { ...error.details, state_file: stateFile });
+        if (error instanceof SignedTransferError)
+            throw fail(error.message, error.code, { state_file: stateFile });
+        throw fail('Upload interrupted; resume with the saved state.', 'kb_transfer_failed', { state_file: stateFile });
+    }
+    finally {
+        await release();
+    }
+}
+export async function waitForTask(client, taskId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10 * 60_000, interval = options.pollIntervalMs ?? 1000;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || !Number.isFinite(interval) || interval < 1)
+        throw fail('Task timeout and polling interval must be positive.');
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        if (options.signal?.aborted)
+            throw fail('Task wait interrupted.', 'kb_aborted', { task_id: taskId });
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            throw fail('Timed out waiting for KB task; query the task again.', 'kb_task_timeout', { task_id: taskId, kind: options.kind ?? 'archive' });
+        // The control client has its own HTTP deadline; race bounds even injected/hung clients.
+        let timer;
+        let removeAbort;
+        const timeout = new Promise((_, reject) => { timer = setTimeout(() => reject(fail('Timed out waiting for KB task; query the task again.', 'kb_task_timeout', { task_id: taskId })), remaining); });
+        const abort = new Promise((_, reject) => { const handler = () => reject(fail('Task wait interrupted.', 'kb_aborted', { task_id: taskId })); options.signal?.addEventListener('abort', handler, { once: true }); removeAbort = () => options.signal?.removeEventListener('abort', handler); });
+        let task;
+        try {
+            task = await Promise.race([client.getTask(taskId, options.kind), timeout, abort]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            removeAbort?.();
+        }
+        const raw = typeof task.task_status === 'string' ? task.task_status : task.status;
+        const fileStates = task.files?.map(file => String(file.status));
+        const active = Number(task.pending_count ?? 0) > 0 || Number(task.processing_count ?? 0) > 0 || fileStates?.some(status => ['pending', 'processing'].includes(status));
+        const blocked = raw === 'needs_resolution' || (!active && fileStates?.some(status => status === 'needs_resolution'));
+        const cancelled = raw === 'cancelled' || (!active && fileStates?.length && fileStates.some(status => status === 'cancelled'));
+        options.onProgress?.({ phase: 'waiting', taskId, status: raw });
+        if (blocked)
+            throw fail('KB task needs conflict resolution.', 'kb_task_needs_resolution', { task_id: taskId, task });
+        if (cancelled || raw === 'failed' || (raw === 'partial_failed' && !active) || (['completed', 'archived'].includes(raw) && Number(task.failed_count ?? 0) > 0))
+            throw fail('KB task did not complete successfully.', 'kb_task_failed', { task_id: taskId, task });
+        if (['completed', 'archived'].includes(raw))
+            return task;
+        try {
+            await delay(Math.min(interval, Math.max(1, deadline - Date.now())), undefined, { signal: options.signal });
+        }
+        catch (error) {
+            if (options.signal?.aborted)
+                throw fail('Task wait interrupted.', 'kb_aborted', { task_id: taskId });
+            throw error;
+        }
+    }
+}
+export async function downloadFromKb(client, input, deps = {}) {
+    try {
+        input.signal?.throwIfAborted();
+        const ticket = await client.downloadTicket(input.documentId);
+        const result = await downloadSignedFile(ticket, input.output, { signal: input.signal, fetchImpl: deps.fetchImpl, timeoutMs: deps.transferTimeoutMs, response: ticket.transport === 'proxy' ? signal => client.downloadProxy(ticket, signal) : undefined, onProgress: (transferred, total) => input.onProgress?.({ phase: 'downloading', filename: ticket.filename, transferred, total: total ?? undefined }) });
+        return { document_id: input.documentId, ...result };
+    }
+    catch (error) {
+        if (input.signal?.aborted)
+            throw fail('Download interrupted.', 'kb_aborted');
+        if (error instanceof KbError)
+            throw error;
+        if (error instanceof SignedTransferError)
+            throw fail(error.message, error.code);
+        throw fail('Download failed.', 'kb_transfer_failed');
+    }
+}
+//# sourceMappingURL=transfers.js.map