@thinkingai/ae-cli 6.1.18 → 6.1.20

package/dist/te-kb-WYQWHFSC.js

@@ -0,0 +1,1732 @@
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
+import {
+  kbApi,
+  kbUpload
+} from "./chunk-VXNMYUXU.js";
+import {
+  TeAgentApiError
+} from "./chunk-BBEFP4SB.js";
+import {
+  CapabilityGatewayError
+} from "./chunk-QJQZH5GQ.js";
+import {
+  printError
+} from "./chunk-CZU3V3DQ.js";
+import "./chunk-Y74WTIKJ.js";
+import "./chunk-ATSM5XAW.js";
+import "./chunk-WZ6YVQSF.js";
+import {
+  CliValidationError,
+  PermissionError
+} from "./chunk-4P355ZWB.js";
+
+// src/commands/te-kb/add.ts
+import { promises as fs } from "fs";
+import * as path from "path";
+import TurndownService from "turndown";
+
+// src/commands/te-kb/target-scope.ts
+function getExternalKnowledgeBaseTargetScope(ctx) {
+  const scope = ctx.str("scope").trim();
+  if (!scope) return void 0;
+  if (scope === "personal" || scope === "company") return scope;
+  throw new CliValidationError(
+    `Invalid --scope: ${scope}. Must be one of: personal | company`
+  );
+}
+
+// src/commands/te-kb/add.ts
+var API_PATH = "/agent/api/external/knowledge-bases/sources/upload";
+var SUPPORTED_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".zip",
+  ".md",
+  ".markdown",
+  ".txt",
+  ".csv",
+  ".pdf",
+  ".doc",
+  ".docx",
+  ".xls",
+  ".xlsx",
+  ".ppt",
+  ".pptx",
+  ".jpg",
+  ".jpeg",
+  ".png",
+  ".gif",
+  ".webp",
+  ".bmp",
+  ".svg"
+]);
+function normalizeFilesInput(raw) {
+  if (!Array.isArray(raw)) {
+    throw new Error(`--files must be a JSON array of strings, e.g. '["./a.md","./docs","https://example.com/page"]'`);
+  }
+  const items = [];
+  for (const v of raw) {
+    if (typeof v !== "string") {
+      throw new Error(`--files entries must be strings (got: ${JSON.stringify(v)})`);
+    }
+    const trimmed = v.trim();
+    if (trimmed) items.push(trimmed);
+  }
+  return items;
+}
+function isUrl(s) {
+  return /^https?:\/\//i.test(s);
+}
+function classifyInput(item) {
+  return isUrl(item) ? "url" : "path";
+}
+function sanitizeFilename(name) {
+  const cleaned = name.replace(/[\\/:*?"<>|\s]+/g, "-").replace(/^-+|-+$/g, "");
+  return cleaned || "document";
+}
+function getMimeType(filename) {
+  const ext = path.extname(filename).toLowerCase();
+  switch (ext) {
+    case ".zip":
+      return "application/zip";
+    case ".md":
+    case ".markdown":
+      return "text/markdown";
+    case ".txt":
+      return "text/plain";
+    case ".csv":
+      return "text/csv";
+    case ".pdf":
+      return "application/pdf";
+    case ".doc":
+      return "application/msword";
+    case ".docx":
+      return "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+    case ".xls":
+      return "application/vnd.ms-excel";
+    case ".xlsx":
+      return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+    case ".ppt":
+      return "application/vnd.ms-powerpoint";
+    case ".pptx":
+      return "application/vnd.openxmlformats-officedocument.presentationml.presentation";
+    case ".jpg":
+    case ".jpeg":
+      return "image/jpeg";
+    case ".png":
+      return "image/png";
+    case ".gif":
+      return "image/gif";
+    case ".webp":
+      return "image/webp";
+    case ".bmp":
+      return "image/bmp";
+    case ".svg":
+      return "image/svg+xml";
+    default:
+      return "application/octet-stream";
+  }
+}
+async function readLocalFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (!SUPPORTED_EXTENSIONS.has(ext)) {
+    throw new Error(`Unsupported file extension (${ext || "none"}): ${filePath}`);
+  }
+  const content = await fs.readFile(filePath);
+  const filename = path.basename(filePath);
+  return { filename, content, mimeType: getMimeType(filename), origin: "file", source: filePath };
+}
+async function readDirectory(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const ext = path.extname(entry.name).toLowerCase();
+    if (!SUPPORTED_EXTENSIONS.has(ext)) continue;
+    const full = path.join(dir, entry.name);
+    const content = await fs.readFile(full);
+    files.push({ filename: entry.name, content, mimeType: getMimeType(entry.name), origin: "dir", source: full });
+  }
+  if (files.length === 0) {
+    throw new Error(`No supported files found in directory: ${dir}`);
+  }
+  return files;
+}
+function deriveFilenameFromUrl(rawUrl) {
+  try {
+    const u = new URL(rawUrl);
+    const lastSeg = u.pathname.split("/").filter(Boolean).pop();
+    const base = lastSeg ? lastSeg.replace(/\.[^.]+$/, "") : u.hostname;
+    return `${sanitizeFilename(base)}.md`;
+  } catch {
+    return `${sanitizeFilename(rawUrl)}.md`;
+  }
+}
+async function fetchAsMarkdown(rawUrl) {
+  const resp = await fetch(rawUrl);
+  if (!resp.ok) {
+    throw new Error(`Failed to fetch ${rawUrl}: HTTP ${resp.status}`);
+  }
+  const html = await resp.text();
+  const turndown = new TurndownService({ headingStyle: "atx", codeBlockStyle: "fenced" });
+  const markdown = turndown.turndown(html);
+  return {
+    filename: deriveFilenameFromUrl(rawUrl),
+    content: markdown,
+    mimeType: "text/markdown",
+    origin: "url",
+    source: rawUrl
+  };
+}
+async function resolveLocalPath(p) {
+  const abs = path.resolve(p);
+  let stat;
+  try {
+    stat = await fs.stat(abs);
+  } catch {
+    throw new Error(`Path not found: ${p}`);
+  }
+  if (stat.isDirectory()) {
+    return readDirectory(abs);
+  }
+  if (stat.isFile()) {
+    return [await readLocalFile(abs)];
+  }
+  throw new Error(`Unsupported path (not file or directory): ${p}`);
+}
+async function collectFiles(ctx) {
+  const items = normalizeFilesInput(ctx.json("files"));
+  if (items.length === 0) {
+    throw new Error("--files must contain at least one entry");
+  }
+  const collected = [];
+  for (const item of items) {
+    if (classifyInput(item) === "url") {
+      collected.push(await fetchAsMarkdown(item));
+    } else {
+      collected.push(...await resolveLocalPath(item));
+    }
+  }
+  if (collected.length === 0) {
+    throw new Error("No supported files collected from the given inputs");
+  }
+  return dedupeByFilename(collected);
+}
+function dedupeByFilename(files) {
+  const used = /* @__PURE__ */ new Map();
+  return files.map((f) => {
+    const count = used.get(f.filename) ?? 0;
+    used.set(f.filename, count + 1);
+    if (count === 0) return f;
+    const ext = path.extname(f.filename);
+    const stem = f.filename.slice(0, f.filename.length - ext.length);
+    return { ...f, filename: `${stem}-${count}${ext}` };
+  });
+}
+function buildForm(name, scope, files) {
+  const form = new FormData();
+  form.append("name", name);
+  if (scope) form.append("scope", scope);
+  for (const f of files) {
+    form.append("files", new Blob([f.content], { type: f.mimeType }), f.filename);
+  }
+  return form;
+}
+var add = {
+  service: "kb",
+  command: "+add",
+  description: "Upload sources to a knowledge. --files accepts a JSON array; each entry can be a supported file path, a directory path (supported files inside, non-recursive), or an http(s) URL (HTML auto-converted to markdown).",
+  flags: [
+    { name: "name", type: "string", required: true, desc: "Knowledge base name" },
+    { name: "scope", type: "string", required: false, desc: "Exact knowledge base scope: personal | company (omit for personal \u2192 company fallback)" },
+    {
+      name: "files",
+      type: "json",
+      required: true,
+      desc: `JSON array of strings. Each entry can be a supported file path, a directory path, or an http(s) URL. Example: '["./a.md","./docs","https://example.com/page"]'`
+    }
+  ],
+  risk: "write",
+  validate: (ctx) => {
+    getExternalKnowledgeBaseTargetScope(ctx);
+    normalizeFilesInput(ctx.json("files"));
+  },
+  dryRun: (ctx) => {
+    const items = normalizeFilesInput(ctx.json("files"));
+    const body = {
+      name: ctx.str("name")
+    };
+    const scope = getExternalKnowledgeBaseTargetScope(ctx);
+    if (scope) body.scope = scope;
+    body.files = items.map((item) => ({ value: item, type: classifyInput(item) }));
+    body.contentType = "multipart/form-data";
+    return {
+      method: "POST",
+      url: `${ctx.host().replace(/\/$/, "")}${API_PATH}`,
+      body
+    };
+  },
+  execute: async (ctx) => {
+    const name = ctx.str("name");
+    const scope = getExternalKnowledgeBaseTargetScope(ctx);
+    const files = await collectFiles(ctx);
+    const form = buildForm(name, scope, files);
+    const result = await kbUpload(ctx, API_PATH, form);
+    return {
+      uploaded: files.map((f) => ({ filename: f.filename, origin: f.origin, source: f.source })),
+      result
+    };
+  }
+};
+
+// src/commands/te-kb/compile.ts
+var API_PATH2 = "/agent/api/external/knowledge-bases/compile";
+var VALID_MODES = /* @__PURE__ */ new Set(["incremental", "full"]);
+function getMode(ctx) {
+  const mode = ctx.str("mode") || "incremental";
+  if (!VALID_MODES.has(mode)) {
+    throw new Error(`Invalid --mode: ${mode}. Must be one of: incremental | full`);
+  }
+  return mode;
+}
+function buildBody(ctx) {
+  const body = {
+    name: ctx.str("name"),
+    mode: getMode(ctx)
+  };
+  const scope = getExternalKnowledgeBaseTargetScope(ctx);
+  if (scope) body.scope = scope;
+  const model = ctx.str("model");
+  if (model) body.model = model;
+  return body;
+}
+var compile = {
+  service: "kb",
+  command: "+compile",
+  description: "Compile a knowledge.",
+  flags: [
+    { name: "name", type: "string", required: true, desc: "Knowledge base name" },
+    { name: "mode", type: "string", required: false, default: "incremental", desc: "Compile mode: incremental | full (default: incremental)" },
+    { name: "scope", type: "string", required: false, desc: "Exact knowledge base scope: personal | company (omit for personal \u2192 company fallback)" },
+    { name: "model", type: "string", required: false, desc: "Optional model reference: Model.id, legacy modelId, or modelId::scope" }
+  ],
+  risk: "write",
+  validate: (ctx) => {
+    getMode(ctx);
+    getExternalKnowledgeBaseTargetScope(ctx);
+  },
+  dryRun: (ctx) => ({
+    method: "POST",
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH2}`,
+    body: buildBody(ctx)
+  }),
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH2, {}, buildBody(ctx))
+};
+
+// src/commands/te-kb/remove.ts
+var API_PATH3 = "/agent/api/external/knowledge-bases";
+function buildBody2(ctx) {
+  const body = { name: ctx.str("name") };
+  const scope = getExternalKnowledgeBaseTargetScope(ctx);
+  if (scope) body.scope = scope;
+  return body;
+}
+var remove = {
+  service: "kb",
+  command: "+remove",
+  description: "Delete an entire knowledge.",
+  flags: [
+    { name: "name", type: "string", required: true, desc: "Knowledge base name to delete" },
+    { name: "scope", type: "string", required: false, desc: "Exact knowledge base scope: personal | company (omit for personal \u2192 company fallback)" }
+  ],
+  risk: "high-risk-write",
+  validate: (ctx) => {
+    getExternalKnowledgeBaseTargetScope(ctx);
+  },
+  dryRun: (ctx) => ({
+    method: "DELETE",
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH3}`,
+    body: buildBody2(ctx)
+  }),
+  execute: async (ctx) => kbApi(ctx, "DELETE", API_PATH3, {}, buildBody2(ctx))
+};
+
+// src/commands/te-kb/create.ts
+var API_PATH4 = "/agent/api/external/knowledge-bases/create";
+var VALID_SCOPES = /* @__PURE__ */ new Set(["personal", "company"]);
+function getScope(ctx) {
+  const scope = ctx.str("scope") || "company";
+  validateScope(scope);
+  return scope;
+}
+function validateScope(scope) {
+  if (!VALID_SCOPES.has(scope)) {
+    throw new Error(`Invalid --scope: ${scope}. Must be one of: personal | company`);
+  }
+}
+function normalizeTags(raw) {
+  if (raw === void 0 || raw === null) return void 0;
+  if (!Array.isArray(raw)) {
+    throw new Error(`--tags must be a JSON array of strings, e.g. '["t1","t2"]'`);
+  }
+  const tags = [];
+  for (const v of raw) {
+    if (typeof v !== "string") {
+      throw new Error(`--tags entries must be strings (got: ${JSON.stringify(v)})`);
+    }
+    const t = v.trim();
+    if (t) tags.push(t);
+  }
+  return tags;
+}
+function buildBody3(ctx) {
+  const body = {
+    scope: getScope(ctx),
+    name: ctx.str("name")
+  };
+  const description = ctx.str("description");
+  if (description) body.description = description;
+  const tags = normalizeTags(ctx.json("tags"));
+  if (tags && tags.length > 0) body.tags = tags;
+  const projectId = ctx.str("project-id");
+  if (projectId) body.projectId = projectId;
+  const projectName = ctx.str("project-name");
+  if (projectName) body.projectName = projectName;
+  return body;
+}
+var create = {
+  service: "kb",
+  command: "+new",
+  description: "Create a new knowledge.",
+  flags: [
+    { name: "scope", type: "string", required: false, default: "company", desc: "Knowledge base scope: personal | company (default: company)" },
+    { name: "name", type: "string", required: true, desc: "Knowledge base name (\u226430 chars, unique per scope)" },
+    { name: "description", type: "string", required: false, desc: "Optional description (\u2264200 chars)" },
+    { name: "tags", type: "json", required: false, desc: `Optional JSON array of tags (max 2, each \u226415 chars). Example: '["t1","t2"]'` },
+    { name: "project-id", type: "string", required: false, desc: "Optional project ID to bind" },
+    { name: "project-name", type: "string", required: false, desc: "Optional project display name" }
+  ],
+  risk: "write",
+  validate: (ctx) => {
+    getScope(ctx);
+    normalizeTags(ctx.json("tags"));
+  },
+  dryRun: (ctx) => ({
+    method: "POST",
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH4}`,
+    body: buildBody3(ctx)
+  }),
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH4, {}, buildBody3(ctx))
+};
+
+// src/commands/te-kb/rm-source.ts
+var API_PATH5 = "/agent/api/external/knowledge-bases/sources";
+function sourceSelector(ctx) {
+  const id = ctx.str("id").trim();
+  if (id) return { id };
+  const displayName = ctx.str("display-name").trim();
+  if (displayName) return { displayName };
+  throw new CliValidationError("One of --id or --display-name is required.");
+}
+function buildBody4(ctx) {
+  const body = {
+    name: ctx.str("name")
+  };
+  const scope = getExternalKnowledgeBaseTargetScope(ctx);
+  if (scope) body.scope = scope;
+  return { ...body, ...sourceSelector(ctx) };
+}
+var rmSource = {
+  service: "kb",
+  command: "+rm-source",
+  description: "Delete one source from a knowledge base by ID or exact display name.",
+  flags: [
+    { name: "name", type: "string", required: true, desc: "Knowledge base name (looked up personal \u2192 company)" },
+    { name: "scope", type: "string", required: false, desc: "Exact knowledge base scope: personal | company (omit for personal \u2192 company fallback)" },
+    { name: "id", type: "string", required: false, desc: "Source ID copied from +list-sources (preferred)" },
+    { name: "display-name", type: "string", required: false, desc: "Exact source display name for legacy compatibility" }
+  ],
+  risk: "high-risk-write",
+  validate: (ctx) => {
+    getExternalKnowledgeBaseTargetScope(ctx);
+    sourceSelector(ctx);
+  },
+  dryRun: (ctx) => ({
+    method: "DELETE",
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH5}`,
+    body: buildBody4(ctx)
+  }),
+  execute: async (ctx) => kbApi(ctx, "DELETE", API_PATH5, {}, buildBody4(ctx), {
+    preserveErrorMetadata: true
+  })
+};
+
+// src/commands/te-kb/schema.ts
+var API_PATH6 = "/agent/api/external/knowledge-bases/schema";
+function buildBody5(ctx) {
+  const body = {
+    name: ctx.str("name")
+  };
+  const scope = getExternalKnowledgeBaseTargetScope(ctx);
+  if (scope) body.scope = scope;
+  if (ctx.bool("force")) body.force = true;
+  const model = ctx.str("model");
+  if (model) body.model = model;
+  const customInstructions = ctx.str("custom-instructions");
+  if (customInstructions) body.customInstructions = customInstructions;
+  return body;
+}
+async function executeSchema(ctx, api = kbApi) {
+  return api(ctx, "POST", API_PATH6, {}, buildBody5(ctx), {
+    preserveBusinessErrorCode: true
+  });
+}
+var schema = {
+  service: "kb",
+  command: "+schema",
+  description: "Generate the compile schema for a knowledge base via POST /agent/api/external/knowledge-bases/schema.",
+  flags: [
+    { name: "name", type: "string", required: true, desc: "Knowledge base name (looked up personal \u2192 company)" },
+    { name: "scope", type: "string", required: false, desc: "Exact knowledge base scope: personal | company (omit for personal \u2192 company fallback)" },
+    { name: "force", type: "boolean", required: false, desc: "Preempt generation even when status is `generating` (use only for stuck recovery)" },
+    { name: "model", type: "string", required: false, desc: "Optional model reference: Model.id, legacy modelId, or modelId::scope" },
+    {
+      name: "custom-instructions",
+      type: "string",
+      required: false,
+      sensitive: true,
+      desc: "Optional per-run instructions for generating this knowledge base schema"
+    }
+  ],
+  risk: "write",
+  validate: (ctx) => {
+    getExternalKnowledgeBaseTargetScope(ctx);
+  },
+  dryRun: (ctx) => ({
+    method: "POST",
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH6}`,
+    body: buildBody5(ctx)
+  }),
+  execute: executeSchema
+};
+
+// src/commands/te-kb/status.ts
+var API_PATH7 = "/agent/api/external/knowledge-bases/status";
+function buildBody6(ctx) {
+  const body = {
+    name: ctx.str("name")
+  };
+  const scope = getExternalKnowledgeBaseTargetScope(ctx);
+  if (scope) body.scope = scope;
+  return body;
+}
+var status = {
+  service: "kb",
+  command: "+status",
+  description: "Query knowledge base status.",
+  flags: [
+    { name: "name", type: "string", required: true, desc: "Knowledge base name" },
+    { name: "scope", type: "string", required: false, desc: "Exact knowledge base scope: personal | company (omit for personal \u2192 company fallback)" }
+  ],
+  risk: "read",
+  validate: (ctx) => {
+    getExternalKnowledgeBaseTargetScope(ctx);
+  },
+  dryRun: (ctx) => ({
+    method: "POST",
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH7}`,
+    body: buildBody6(ctx)
+  }),
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH7, {}, buildBody6(ctx))
+};
+
+// src/commands/te-kb/kb-index.ts
+var API_PATH8 = "/agent/api/external/knowledge-bases/index";
+function buildBody7(ctx) {
+  const body = {};
+  const sources = ctx.json("sources");
+  if (sources) body.sources = sources;
+  const locale = ctx.str("locale");
+  if (locale) body.locale = locale;
+  return body;
+}
+var kbIndex = {
+  service: "kb",
+  command: "+index",
+  description: "List accessible knowledge bases and their index.md navigation maps via POST /agent/api/external/knowledge-bases/index. Call this first to see the layout, then use +grep to locate and +read to open pages.",
+  flags: [
+    {
+      name: "sources",
+      type: "json",
+      required: false,
+      desc: 'Optional JSON array of knowledge base refs to scope the index, e.g. [{"scope":"company","name":"engineering-handbook"}]. Omit to list all accessible knowledge bases.'
+    },
+    { name: "locale", type: "string", required: false, desc: "Optional locale: zh | en | ja | ko" }
+  ],
+  risk: "read",
+  dryRun: (ctx) => ({
+    method: "POST",
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH8}`,
+    body: buildBody7(ctx)
+  }),
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH8, {}, buildBody7(ctx))
+};
+
+// src/commands/te-kb/kb-list.ts
+var API_PATH9 = "/agent/api/external/knowledge-bases/list";
+var DEFAULT_BUILD_STATUS = "compiled";
+var VALID_BUILD_STATUSES = ["idle", "pending", "compiling", "compiled", "failed"];
+function getBuildStatus(ctx) {
+  return ctx.str("build-status") || DEFAULT_BUILD_STATUS;
+}
+function validateBuildStatus(ctx) {
+  const value = ctx.str("build-status");
+  if (value && !VALID_BUILD_STATUSES.includes(value)) {
+    printError(
+      "validation",
+      `Invalid --build-status: ${value}. Valid values: ${VALID_BUILD_STATUSES.join(" | ")} (omit to default to ${DEFAULT_BUILD_STATUS}).`
+    );
+    process.exit(1);
+  }
+}
+function buildBody8(ctx) {
+  const body = {
+    buildStatus: getBuildStatus(ctx)
+  };
+  const locale = ctx.str("locale");
+  if (locale) body.locale = locale;
+  return body;
+}
+var kbList = {
+  service: "kb",
+  command: "+list",
+  description: "List accessible knowledge bases via POST /agent/api/external/knowledge-bases/list. Filters by buildStatus (default: compiled). Returns KB metadata including buildStatus, without index.md navigation maps.",
+  flags: [
+    {
+      name: "build-status",
+      type: "string",
+      required: false,
+      default: DEFAULT_BUILD_STATUS,
+      desc: `Filter by knowledge base build status: ${VALID_BUILD_STATUSES.join(" | ")} (default: ${DEFAULT_BUILD_STATUS} when omitted)`
+    },
+    { name: "locale", type: "string", required: false, desc: "Optional locale: zh | en | ja | ko" }
+  ],
+  risk: "read",
+  validate: (ctx) => {
+    validateBuildStatus(ctx);
+  },
+  dryRun: (ctx) => ({
+    method: "POST",
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH9}`,
+    body: buildBody8(ctx)
+  }),
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH9, {}, buildBody8(ctx))
+};
+
+// src/commands/te-kb/list-sources.ts
+var API_PATH10 = "/agent/api/external/knowledge-bases/sources";
+var MAX_KNOWLEDGE_BASE_NAME_LENGTH = 200;
+function knowledgeBaseName(ctx) {
+  return ctx.str("name").trim();
+}
+function buildUrl(ctx) {
+  const url2 = new URL(`${ctx.host().replace(/\/$/, "")}${API_PATH10}`);
+  url2.searchParams.set("name", knowledgeBaseName(ctx));
+  const scope = getExternalKnowledgeBaseTargetScope(ctx);
+  if (scope) url2.searchParams.set("scope", scope);
+  return url2.toString();
+}
+var listSources = {
+  service: "kb",
+  command: "+list-sources",
+  description: "List source metadata for a knowledge base via GET /agent/api/external/knowledge-bases/sources?name=<name>. Copy the stable source ID from this output before using +rm-source. Preserves deletionProjection, pendingDeletions (null means undetermined), and separate cleanup state.",
+  flags: [
+    {
+      name: "name",
+      type: "string",
+      required: true,
+      minLength: 1,
+      maxLength: MAX_KNOWLEDGE_BASE_NAME_LENGTH,
+      desc: "Knowledge base name"
+    },
+    {
+      name: "scope",
+      type: "string",
+      required: false,
+      desc: "Exact knowledge base scope: personal | company (omit for personal \u2192 company fallback)"
+    }
+  ],
+  risk: "read",
+  validate: (ctx) => {
+    const name = knowledgeBaseName(ctx);
+    if (!name) {
+      throw new CliValidationError("Invalid --name: must be non-empty.");
+    }
+    if (name.length > MAX_KNOWLEDGE_BASE_NAME_LENGTH) {
+      throw new CliValidationError(
+        `Invalid --name length: ${name.length}. Must be at most ${MAX_KNOWLEDGE_BASE_NAME_LENGTH} characters.`
+      );
+    }
+    getExternalKnowledgeBaseTargetScope(ctx);
+  },
+  dryRun: (ctx) => ({
+    method: "GET",
+    url: buildUrl(ctx)
+  }),
+  execute: async (ctx) => {
+    const params = { name: knowledgeBaseName(ctx) };
+    const scope = getExternalKnowledgeBaseTargetScope(ctx);
+    if (scope) params.scope = scope;
+    return kbApi(ctx, "GET", API_PATH10, params, void 0, {
+      preserveErrorMetadata: true,
+      retryUnauthorized: true
+    });
+  }
+};
+
+// src/commands/te-kb/kb-grep.ts
+var API_PATH11 = "/agent/api/external/knowledge-bases/grep";
+function buildBody9(ctx) {
+  const body = {
+    query: ctx.str("query"),
+    sources: ctx.json("sources"),
+    paths: ctx.json("paths")
+  };
+  const topK = ctx.optionalNum("top-k");
+  if (topK !== void 0) body.topK = topK;
+  const locale = ctx.str("locale");
+  if (locale) body.locale = locale;
+  return body;
+}
+var kbGrep = {
+  service: "kb",
+  command: "+grep",
+  description: "Keyword-search knowledge base pages via POST /agent/api/external/knowledge-bases/grep. Returns a page-level results array: one entry per page with hitCount (full match count), pageKind (content/catalog), up to 4 sections previews (breadcrumb, sectionStartLine/sectionEndLine, text excerpt) and moreSections. Copy --paths from +index (wiki pages, module catalog pages, or subdirectories); read the matched section range with +read.",
+  flags: [
+    {
+      name: "query",
+      type: "string",
+      required: true,
+      alias: "q",
+      desc: "Keywords to search across the knowledge bases"
+    },
+    {
+      name: "sources",
+      type: "json",
+      required: true,
+      desc: 'JSON array of knowledge base refs, e.g. [{"scope":"company","name":"engineering-handbook"}]'
+    },
+    {
+      name: "paths",
+      type: "json",
+      required: true,
+      desc: 'JSON array of wiki pages or subdirectories copied from +index, e.g. ["wiki/sandbox.md"] or ["wiki/guides"]'
+    },
+    { name: "top-k", type: "number", required: false, min: 1, max: 50, desc: "Max number of pages to return (1-50, default 10)" },
+    { name: "locale", type: "string", required: false, desc: "Optional locale: zh | en | ja | ko" }
+  ],
+  risk: "read",
+  dryRun: (ctx) => ({
+    method: "POST",
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH11}`,
+    body: buildBody9(ctx)
+  }),
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH11, {}, buildBody9(ctx))
+};
+
+// src/commands/te-kb/kb-read.ts
+var API_PATH12 = "/agent/api/external/knowledge-bases/read";
+var VALID_EXPAND_MODES = /* @__PURE__ */ new Set(["block", "none"]);
+var MAX_READ_LIMIT = 2e3;
+function readExpand(ctx) {
+  const expand = ctx.str("expand").trim();
+  if (!expand) return void 0;
+  if (!VALID_EXPAND_MODES.has(expand)) {
+    throw new CliValidationError(
+      `Invalid --expand: ${expand}. Must be one of: block | none`
+    );
+  }
+  return expand;
+}
+function readLimit(ctx) {
+  const limit = ctx.optionalNum("limit");
+  if (limit === void 0) return void 0;
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAX_READ_LIMIT) {
+    throw new CliValidationError(
+      `Invalid --limit: ${limit}. Must be an integer from 1 to ${MAX_READ_LIMIT}`
+    );
+  }
+  return limit;
+}
+function buildBody10(ctx) {
+  const body = {
+    source: ctx.json("source"),
+    path: ctx.str("path")
+  };
+  const offset = ctx.optionalNum("offset");
+  if (offset !== void 0) body.offset = offset;
+  const limit = ctx.optionalNum("limit");
+  if (limit !== void 0) body.limit = limit;
+  const expand = readExpand(ctx);
+  if (expand) body.expand = expand;
+  if (ctx.bool("outline")) body.outline = true;
+  const locale = ctx.str("locale");
+  if (locale) body.locale = locale;
+  return body;
+}
+var kbRead = {
+  service: "kb",
+  command: "+read",
+  description: "Read a full knowledge base page (or a line window) via POST /agent/api/external/knowledge-bases/read. Use after +index / +grep locate a candidate page. Pass --outline to get only the page heading tree (no content) and pick a section to read.",
+  flags: [
+    {
+      name: "source",
+      type: "json",
+      required: true,
+      desc: 'Knowledge base ref pointing to exactly one base, e.g. {"scope":"company","name":"engineering-handbook"}'
+    },
+    {
+      name: "path",
+      type: "string",
+      required: true,
+      desc: "Page path relative to the knowledge base root, e.g. wiki/concepts/data-model.md or index.md"
+    },
+    { name: "offset", type: "number", required: false, min: 1, desc: "Start line (1-based integer). Omit to read from the beginning." },
+    { name: "limit", type: "number", required: false, min: 1, max: MAX_READ_LIMIT, desc: "Max number of lines to return (1-2000)." },
+    { name: "expand", type: "string", required: false, desc: "Read-window expansion mode: block | none (omit for the server default: block)" },
+    {
+      name: "outline",
+      type: "boolean",
+      required: false,
+      desc: "Return only the page outline (headings with line numbers), no content. Use it to decide which section to read on long pages."
+    },
+    { name: "locale", type: "string", required: false, desc: "Optional locale: zh | en | ja | ko" }
+  ],
+  risk: "read",
+  validate: (ctx) => {
+    const offset = ctx.optionalNum("offset");
+    if (offset !== void 0 && !Number.isInteger(offset)) {
+      throw new CliValidationError("--offset must be an integer.");
+    }
+    readLimit(ctx);
+    readExpand(ctx);
+  },
+  dryRun: (ctx) => ({
+    method: "POST",
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH12}`,
+    body: buildBody10(ctx)
+  }),
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH12, {}, buildBody10(ctx))
+};
+
+// src/commands/te-kb/ask-shared.ts
+var ASK_API_PATH = "/agent/api/external/knowledge-bases/ask";
+var ASK_POLL_INTERVAL_MS = 5e3;
+var ASK_POLL_TIMEOUT_MS = 10 * 60 * 1e3;
+var ASK_MAX_TRANSIENT_POLL_FAILURES = 3;
+function isTransientAskPollError(error) {
+  if (error instanceof PermissionError) return false;
+  if (error instanceof TypeError) return true;
+  if (!(error instanceof Error)) return false;
+  if (/KB MCP token auth failed|unauthorized|Invalid access token/i.test(error.message)) {
+    return false;
+  }
+  return /fetch|network|socket|ECONNRESET|ETIMEDOUT|EAI_AGAIN|ENOTFOUND|timeout/i.test(
+    error.message
+  );
+}
+async function pollUntilSettled(getStatus, executionId, options = {}) {
+  const intervalMs = options.intervalMs ?? ASK_POLL_INTERVAL_MS;
+  const timeoutMs = options.timeoutMs ?? ASK_POLL_TIMEOUT_MS;
+  const maxTransientFailures = options.maxTransientFailures ?? ASK_MAX_TRANSIENT_POLL_FAILURES;
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms)));
+  const startTime = now();
+  let transientFailures = 0;
+  while (true) {
+    const elapsed = now() - startTime;
+    if (elapsed > timeoutMs) {
+      throw new Error(
+        `Ask execution timeout after ${Math.floor(elapsed / 1e3)} seconds (executionId: ${executionId})`
+      );
+    }
+    let response;
+    try {
+      response = await getStatus(executionId);
+      transientFailures = 0;
+    } catch (err) {
+      if (!isTransientAskPollError(err) || ++transientFailures >= maxTransientFailures) {
+        throw err;
+      }
+      await sleep(intervalMs);
+      continue;
+    }
+    if (response.status !== "running") {
+      return response;
+    }
+    await sleep(intervalMs);
+  }
+}
+function transformCompletedResponse(response) {
+  const result = {
+    executionId: response.executionId,
+    answer: response.answer ?? "",
+    sources: response.sources ?? []
+  };
+  if (response.modelId !== void 0) result.modelId = response.modelId;
+  if (response.modelUsage !== void 0) result.modelUsage = response.modelUsage;
+  if (response.toolCallCount !== void 0) result.toolCallCount = response.toolCallCount;
+  return result;
+}
+
+// src/commands/te-kb/ask.ts
+var VALID_LOCALES = /* @__PURE__ */ new Set(["zh", "en", "ja", "ko"]);
+var MIN_QUESTION_LEN = 1;
+var MAX_QUESTION_LEN = 2e3;
+function validateQuestion(question) {
+  const len = question.length;
+  if (len < MIN_QUESTION_LEN || len > MAX_QUESTION_LEN) {
+    throw new Error(
+      `Invalid --question length: ${len}. Must be between ${MIN_QUESTION_LEN} and ${MAX_QUESTION_LEN} characters.`
+    );
+  }
+}
+function validateLocale(locale) {
+  if (locale && !VALID_LOCALES.has(locale)) {
+    throw new Error(`Invalid --locale: ${locale}. Must be one of: zh | en | ja | ko`);
+  }
+}
+function buildBody11(ctx) {
+  const body = {
+    question: ctx.str("question")
+  };
+  const sources = ctx.json("sources");
+  if (sources) body.sources = sources;
+  const modelId = ctx.str("model-id");
+  if (modelId) body.modelId = modelId;
+  const locale = ctx.str("locale");
+  if (locale) body.locale = locale;
+  return body;
+}
+var ask = {
+  service: "kb",
+  command: "+ask",
+  description: "Ask knowledge bases via LLM-powered retrieval (POST /agent/api/external/knowledge-bases/ask). Consumes platform tokens. Prefer +index -> +grep -> +read for deterministic, token-free lookup. By default, polls for completion; use --no-wait to return immediately with executionId.",
+  flags: [
+    {
+      name: "question",
+      type: "string",
+      required: true,
+      alias: "q",
+      desc: "Natural-language question (1-2000 characters). Required."
+    },
+    {
+      name: "sources",
+      type: "json",
+      required: false,
+      desc: 'Optional JSON array of knowledge base refs to scope the search, e.g. [{"scope":"company","name":"engineering-handbook"}]. Omit to search all accessible knowledge bases.'
+    },
+    {
+      name: "model-id",
+      type: "string",
+      required: false,
+      desc: "Optional LLM model ID (e.g. claude-sonnet-4-6). Omit to use the platform default model."
+    },
+    { name: "locale", type: "string", required: false, desc: "Optional locale: zh | en | ja | ko" },
+    {
+      name: "no-wait",
+      type: "boolean",
+      required: false,
+      desc: "Return immediately after submission with executionId, without polling for completion."
+    }
+  ],
+  risk: "read",
+  validate: (ctx) => {
+    validateQuestion(ctx.str("question"));
+    validateLocale(ctx.str("locale"));
+  },
+  dryRun: (ctx) => ({
+    method: "POST",
+    url: `${ctx.host().replace(/\/$/, "")}${ASK_API_PATH}`,
+    body: buildBody11(ctx)
+  }),
+  execute: async (ctx) => {
+    const noWait = ctx.bool("no-wait");
+    const submitResponse = await kbApi(ctx, "POST", ASK_API_PATH, {}, buildBody11(ctx));
+    if (!submitResponse.executionId) {
+      throw new Error("Invalid submit response: missing executionId");
+    }
+    const executionId = submitResponse.executionId;
+    if (noWait) {
+      return {
+        executionId,
+        status: submitResponse.status
+      };
+    }
+    const finalResponse = await pollUntilSettled(
+      (id) => kbApi(ctx, "GET", ASK_API_PATH, { executionId: id }),
+      executionId
+    );
+    if (finalResponse.status === "completed") {
+      return transformCompletedResponse(finalResponse);
+    }
+    if (finalResponse.status === "failed") {
+      const code = finalResponse.error?.code || "provider_failed";
+      const message = finalResponse.error?.message || "Ask execution failed";
+      throw new TeAgentApiError(
+        `${message} (executionId: ${finalResponse.executionId})`,
+        200,
+        code,
+        finalResponse
+      );
+    }
+    throw new Error(`Unexpected execution status: ${finalResponse.status}`);
+  }
+};
+
+// src/commands/te-kb/ask-status.ts
+var MAX_EXECUTION_ID_LEN = 64;
+function executionIdFrom(ctx) {
+  return ctx.str("execution-id").trim();
+}
+var askStatus = {
+  service: "kb",
+  command: "+ask-status",
+  description: "Query the status of an in-progress or completed knowledge base ask execution (GET /agent/api/external/knowledge-bases/ask?executionId=<id>). Does not poll; returns the current state.",
+  flags: [
+    {
+      name: "execution-id",
+      type: "string",
+      required: true,
+      minLength: 1,
+      maxLength: MAX_EXECUTION_ID_LEN,
+      desc: "The execution ID returned by kb +ask submission."
+    }
+  ],
+  risk: "read",
+  validate: (ctx) => {
+    const executionId = executionIdFrom(ctx);
+    if (!executionId) {
+      throw new Error("Invalid --execution-id: must be non-empty.");
+    }
+    if (executionId.length > MAX_EXECUTION_ID_LEN) {
+      throw new Error(
+        `Invalid --execution-id length: ${executionId.length}. Must be at most ${MAX_EXECUTION_ID_LEN} characters.`
+      );
+    }
+  },
+  dryRun: (ctx) => ({
+    method: "GET",
+    url: `${ctx.host().replace(/\/$/, "")}${ASK_API_PATH}?executionId=${encodeURIComponent(executionIdFrom(ctx))}`
+  }),
+  execute: async (ctx) => {
+    const executionId = executionIdFrom(ctx);
+    return await kbApi(ctx, "GET", ASK_API_PATH, { executionId });
+  }
+};
+
+// src/commands/te-kb/url.ts
+var API_PATH13 = "/agent/api/external/knowledge-bases/sources/url";
+function validateUrl(url2) {
+  if (!/^https?:\/\//i.test(url2)) {
+    throw new Error(`Invalid --url: ${url2}. Must be an http(s) URL`);
+  }
+}
+function buildBody12(ctx) {
+  const body = {
+    name: ctx.str("name"),
+    url: ctx.str("url")
+  };
+  const scope = getExternalKnowledgeBaseTargetScope(ctx);
+  if (scope) body.scope = scope;
+  const displayName = ctx.str("display-name");
+  if (displayName) body.displayName = displayName;
+  const parseInstruction = ctx.str("parse-instruction");
+  if (parseInstruction) body.parseInstruction = parseInstruction;
+  return body;
+}
+var url = {
+  service: "kb",
+  command: "+url",
+  description: "Upload a URL source to a knowledge base.",
+  flags: [
+    { name: "name", type: "string", required: true, desc: "Knowledge base name" },
+    { name: "scope", type: "string", required: false, desc: "Exact knowledge base scope: personal | company (omit for personal \u2192 company fallback)" },
+    { name: "url", type: "string", required: true, desc: "Source URL to upload" },
+    { name: "display-name", type: "string", required: false, desc: "Optional display name for the URL source" },
+    { name: "parse-instruction", type: "string", required: false, desc: "Optional parsing instruction for the URL source; ignored for Lark/Feishu doc URLs (the server applies its own Feishu parsing)" }
+  ],
+  risk: "write",
+  validate: (ctx) => {
+    getExternalKnowledgeBaseTargetScope(ctx);
+    validateUrl(ctx.str("url"));
+  },
+  dryRun: (ctx) => ({
+    method: "POST",
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH13}`,
+    body: buildBody12(ctx)
+  }),
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH13, {}, buildBody12(ctx))
+};
+
+// src/commands/te-kb/import.ts
+import { promises as fs2 } from "fs";
+import path2 from "path";
+var API_PATH14 = "/agent/api/external/knowledge-bases/import";
+var MAX_SNAPSHOT_ARCHIVE_BYTES = 50 * 1024 * 1024;
+var VALID_SCOPES2 = /* @__PURE__ */ new Set(["personal", "company"]);
+function getScope2(ctx) {
+  const scope = ctx.str("scope") || "personal";
+  if (!VALID_SCOPES2.has(scope)) {
+    throw new CliValidationError("Invalid --scope. Must be one of: personal | company", {
+      location: { field: "scope" }
+    });
+  }
+  return scope;
+}
+function normalizeTags2(raw) {
+  if (raw === void 0 || raw === null) return [];
+  if (!Array.isArray(raw)) {
+    throw new Error(
+      `--tags must be a JSON array of strings, e.g. '["docs","product"]'`
+    );
+  }
+  const tags = [];
+  for (const value of raw) {
+    if (typeof value !== "string") {
+      throw new Error(
+        `--tags entries must be strings (got: ${JSON.stringify(value)})`
+      );
+    }
+    const tag = value.trim();
+    if (tag && !tags.includes(tag)) tags.push(tag);
+  }
+  if (tags.length > 2) throw new Error("--tags accepts at most 2 unique tags");
+  if (tags.some((tag) => tag.length > 15)) {
+    throw new Error("--tags entries must be at most 15 characters");
+  }
+  return tags;
+}
+function validateArchivePath(filePath) {
+  if (path2.extname(filePath).toLocaleLowerCase("en-US") !== ".zip") {
+    throw new Error("--file must point to a .zip archive");
+  }
+}
+async function readArchive(filePath) {
+  validateArchivePath(filePath);
+  const absolutePath = path2.resolve(filePath);
+  let stat;
+  try {
+    stat = await fs2.stat(absolutePath);
+  } catch {
+    throw new Error(`File not found: ${filePath}`);
+  }
+  if (!stat.isFile())
+    throw new Error(`--file must point to a file: ${filePath}`);
+  if (stat.size === 0) throw new Error(`ZIP archive is empty: ${filePath}`);
+  if (stat.size > MAX_SNAPSHOT_ARCHIVE_BYTES) {
+    throw new Error("--file must not exceed 50 MB");
+  }
+  return { absolutePath, bytes: await fs2.readFile(absolutePath) };
+}
+function appendOptionalFields(ctx, form) {
+  const description = ctx.str("description").trim();
+  if (description) form.append("description", description);
+  for (const tag of normalizeTags2(ctx.json("tags"))) form.append("tags", tag);
+  const projectId = ctx.str("project-id").trim();
+  if (projectId) form.append("projectId", projectId);
+}
+var importSnapshot = {
+  service: "kb",
+  command: "+import",
+  description: "Import a compiled Markdown ZIP snapshot as a personal or company read-only knowledge base.",
+  flags: [
+    {
+      name: "scope",
+      type: "string",
+      required: false,
+      default: "personal",
+      desc: "Target scope: personal | company (default: personal)"
+    },
+    {
+      name: "file",
+      type: "string",
+      required: true,
+      desc: "Local .zip snapshot containing root index.md and wiki/**/*.md"
+    },
+    {
+      name: "name",
+      type: "string",
+      required: true,
+      maxLength: 30,
+      desc: "Knowledge base name (max 30 characters)"
+    },
+    {
+      name: "description",
+      type: "string",
+      required: false,
+      maxLength: 200,
+      desc: "Optional description (max 200 characters)"
+    },
+    {
+      name: "tags",
+      type: "json",
+      required: false,
+      desc: "Optional JSON array of tags (max 2, each max 15 characters)"
+    },
+    {
+      name: "project-id",
+      type: "string",
+      required: false,
+      maxLength: 128,
+      desc: "Optional project ID to bind"
+    }
+  ],
+  risk: "write",
+  validate: (ctx) => {
+    getScope2(ctx);
+    validateArchivePath(ctx.str("file"));
+    normalizeTags2(ctx.json("tags"));
+  },
+  execute: async (ctx) => {
+    const archive = await readArchive(ctx.str("file"));
+    const form = new FormData();
+    form.append(
+      "file",
+      new Blob([Uint8Array.from(archive.bytes)], { type: "application/zip" }),
+      path2.basename(archive.absolutePath)
+    );
+    form.append("name", ctx.str("name").trim());
+    form.append("scope", getScope2(ctx));
+    appendOptionalFields(ctx, form);
+    try {
+      return await kbUpload(
+        ctx,
+        API_PATH14,
+        form,
+        { scope: getScope2(ctx) },
+        { preserveErrorMetadata: true, retryUnauthorized: true }
+      );
+    } catch (error) {
+      const hint = "If a requestId was returned, run ae-cli kb +import-status --request-id <requestId>; otherwise run ae-cli kb +list before retrying the same name.";
+      if (error instanceof CapabilityGatewayError) {
+        throw new CapabilityGatewayError(
+          `${error.message} ${hint}`,
+          error.code,
+          error.httpStatus,
+          error.hint ?? hint,
+          error.meta
+        );
+      }
+      if (error instanceof Error) {
+        if (error.constructor === Error) {
+          throw new CapabilityGatewayError(`${error.message} ${hint}`, void 0, void 0, hint);
+        }
+        error.message = `${error.message} ${hint}`;
+        throw error;
+      }
+      throw new Error(`${String(error)} ${hint}`);
+    }
+  }
+};
+
+// src/commands/te-kb/import-status.ts
+var API_PATH15 = "/agent/api/external/knowledge-bases/import";
+var MAX_REQUEST_ID_LENGTH = 191;
+function requestIdFrom(ctx) {
+  return ctx.str("request-id").trim();
+}
+var importStatus = {
+  service: "kb",
+  command: "+import-status",
+  description: "Query one asynchronous knowledge-base snapshot import by its request ID without polling.",
+  flags: [
+    {
+      name: "request-id",
+      type: "string",
+      required: true,
+      minLength: 1,
+      maxLength: MAX_REQUEST_ID_LENGTH,
+      desc: "The requestId returned by kb +import."
+    }
+  ],
+  risk: "read",
+  validate: (ctx) => {
+    const requestId = requestIdFrom(ctx);
+    if (!requestId) throw new Error("Invalid --request-id: must be non-empty.");
+    if (requestId.length > MAX_REQUEST_ID_LENGTH) {
+      throw new Error(
+        `Invalid --request-id length: ${requestId.length}. Must be at most ${MAX_REQUEST_ID_LENGTH} characters.`
+      );
+    }
+  },
+  dryRun: (ctx) => ({
+    method: "GET",
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH15}?requestId=${encodeURIComponent(requestIdFrom(ctx))}`
+  }),
+  execute: async (ctx) => {
+    const hint = "Verify the request ID and that the server supports kb +import-status. Do not retry the import until its status is known.";
+    try {
+      return await kbApi(
+        ctx,
+        "GET",
+        API_PATH15,
+        { requestId: requestIdFrom(ctx) },
+        void 0,
+        { preserveErrorMetadata: true }
+      );
+    } catch (error) {
+      if (error instanceof PermissionError) {
+        throw new PermissionError(error.message, error.code, error.hint ?? hint);
+      }
+      if (error instanceof CapabilityGatewayError) {
+        if (error.hint) throw error;
+        throw new CapabilityGatewayError(
+          error.message,
+          error.code,
+          error.httpStatus,
+          hint,
+          error.meta
+        );
+      }
+      if (error instanceof Error) {
+        if (error.constructor === Error) {
+          throw new CapabilityGatewayError(error.message, void 0, void 0, hint);
+        }
+        throw error;
+      }
+      throw error;
+    }
+  }
+};
+
+// src/commands/te-kb/source-directory.ts
+import { promises as fs3 } from "fs";
+import path3 from "path";
+var sourceFlags = [
+  { name: "name", type: "string", required: true, desc: "Knowledge base name (personal then company)" },
+  { name: "id", type: "string", required: true, desc: "ZIP source ID copied from +list-sources" }
+];
+var pathFlag = { name: "path", type: "string", required: true, desc: "Exact path relative to the ZIP source root" };
+var revisionFlag = {
+  name: "expected-revision",
+  type: "number",
+  required: true,
+  min: 1,
+  desc: "Revision returned by +source-ls; a conflict requires a fresh read and explicit retry"
+};
+var apiOptions = { preserveErrorMetadata: true, retryUnauthorized: true };
+var maxFileBytes = 50 * 1024 * 1024;
+function validateIdentity(ctx) {
+  for (const [flag, max] of [["name", 200], ["id", 191]]) {
+    const value = ctx.str(flag).trim();
+    if (!value || value.length > max) throw new CliValidationError(`Invalid --${flag}.`);
+  }
+}
+function relativePath(ctx, allowRoot = false) {
+  const value = ctx.str("path");
+  if (allowRoot && value === "") return value;
+  if (!value || value.length > 1024 || /[\\\x00-\x1f\x7f]/.test(value) || /^[A-Za-z]:/.test(value) || value.split("/").some((part) => !part || part === "." || part === "..")) {
+    throw new CliValidationError("--path must be a normalized relative path inside the ZIP source.");
+  }
+  return value;
+}
+function validateMutation(ctx) {
+  validateIdentity(ctx);
+  relativePath(ctx);
+  if (!Number.isSafeInteger(ctx.num("expected-revision")) || ctx.num("expected-revision") < 1) {
+    throw new CliValidationError("--expected-revision must be a positive safe integer.");
+  }
+}
+function endpoint(ctx, suffix = "directory") {
+  return `/agent/api/external/knowledge-bases/sources/${encodeURIComponent(ctx.str("id").trim())}/${suffix}`;
+}
+function query(ctx) {
+  return { name: ctx.str("name").trim(), path: ctx.str("path") };
+}
+function preview(ctx, method, suffix = "directory", body) {
+  return { method, url: `${ctx.host().replace(/\/$/, "")}${endpoint(ctx, suffix)}`, ...body ? { body } : { params: query(ctx) } };
+}
+function mutationBody(ctx, operation) {
+  return { name: ctx.str("name").trim(), expectedRevision: ctx.num("expected-revision"), operations: [operation] };
+}
+var sourceLs = {
+  service: "kb",
+  command: "+source-ls",
+  risk: "read",
+  description: "List one ZIP source directory, its revision, and changes since successful compilation.",
+  flags: [
+    ...sourceFlags,
+    { ...pathFlag, required: false, default: "" },
+    { name: "cursor", type: "string", desc: "Opaque nextCursor returned by the previous page" },
+    { name: "limit", type: "number", default: 100, min: 1, max: 200, desc: "Page size (1-200)" }
+  ],
+  validate: (ctx) => {
+    validateIdentity(ctx);
+    relativePath(ctx, true);
+    if (!Number.isInteger(ctx.num("limit")) || ctx.num("limit") < 1 || ctx.num("limit") > 200) {
+      throw new CliValidationError("--limit must be an integer from 1 to 200.");
+    }
+  },
+  dryRun: (ctx) => ({ ...preview(ctx, "GET"), params: { ...query(ctx), limit: ctx.num("limit"), ...ctx.str("cursor") ? { cursor: ctx.str("cursor") } : {} } }),
+  execute: (ctx) => kbApi(ctx, "GET", endpoint(ctx), {
+    ...query(ctx),
+    limit: ctx.num("limit"),
+    ...ctx.str("cursor") ? { cursor: ctx.str("cursor") } : {}
+  }, void 0, apiOptions)
+};
+var sourceRead = {
+  service: "kb",
+  command: "+source-read",
+  risk: "read",
+  description: "Read a ZIP source file as UTF-8/base64 or save its original bytes to a new local file.",
+  flags: [
+    ...sourceFlags,
+    pathFlag,
+    { name: "encoding", type: "string", default: "utf8", desc: "JSON content encoding: utf8 or base64 (ignored with --output)" },
+    { name: "output", type: "string", desc: "Save original bytes to this local path; existing files are never overwritten" }
+  ],
+  validate: (ctx) => {
+    validateIdentity(ctx);
+    relativePath(ctx);
+    if (!["utf8", "base64"].includes(ctx.str("encoding"))) throw new CliValidationError("--encoding must be utf8 or base64.");
+  },
+  dryRun: (ctx) => preview(ctx, "GET", "raw"),
+  execute: async (ctx) => {
+    const result = await kbApi(ctx, "GET", endpoint(ctx, "raw"), query(ctx), void 0, { ...apiOptions, responseType: "bytes" });
+    const bytes = Buffer.from(result.bytes);
+    const metadata = { path: ctx.str("path"), sizeBytes: bytes.length, contentType: result.contentType };
+    if (ctx.str("output")) {
+      const output = path3.resolve(ctx.str("output"));
+      await fs3.writeFile(output, bytes, { flag: "wx" });
+      return { ...metadata, output };
+    }
+    if (ctx.str("encoding") === "base64") return { ...metadata, encoding: "base64", content: bytes.toString("base64") };
+    try {
+      return { ...metadata, encoding: "utf8", content: new TextDecoder("utf-8", { fatal: true }).decode(bytes) };
+    } catch {
+      throw new CliValidationError("This file is not UTF-8. Use --encoding base64 or --output.");
+    }
+  }
+};
+async function fileOperation(ctx, dryRun) {
+  const file = path3.resolve(ctx.str("file"));
+  const handle = await fs3.open(file, "r");
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size > maxFileBytes) throw new CliValidationError("--file must be a regular file of at most 50 MB.");
+    const action = ctx.str("action");
+    const content = dryRun ? void 0 : await handle.readFile();
+    if (content && content.length > maxFileBytes) throw new CliValidationError("--file exceeds 50 MB.");
+    return {
+      action,
+      path: ctx.str("path"),
+      ...action === "replace" ? { confirmed: true } : {},
+      ...dryRun ? { file, sizeBytes: stat.size, contentBase64: "<redacted>" } : { contentBase64: content.toString("base64") }
+    };
+  } finally {
+    await handle.close();
+  }
+}
+var sourcePut = {
+  service: "kb",
+  command: "+source-put",
+  risk: "write",
+  description: "Add or explicitly replace one file at an exact ZIP-relative path using a checked revision.",
+  flags: [
+    ...sourceFlags,
+    pathFlag,
+    revisionFlag,
+    { name: "file", type: "string", required: true, desc: "Local file to upload (at most 50 MB)" },
+    { name: "action", type: "string", default: "add", desc: "add rejects an existing path; replace explicitly overwrites an existing file" }
+  ],
+  validate: (ctx) => {
+    validateMutation(ctx);
+    if (!ctx.str("file").trim()) throw new CliValidationError("--file must be non-empty.");
+    if (!["add", "replace"].includes(ctx.str("action"))) throw new CliValidationError("--action must be add or replace.");
+  },
+  dryRun: async (ctx) => preview(ctx, "POST", "directory", mutationBody(ctx, await fileOperation(ctx, true))),
+  execute: async (ctx) => kbApi(ctx, "POST", endpoint(ctx), {}, mutationBody(ctx, await fileOperation(ctx, false)), apiOptions)
+};
+function deleteOperation(ctx) {
+  return { action: "delete", path: ctx.str("path"), confirmed: true, ...ctx.bool("recursive") ? { recursive: true } : {} };
+}
+var sourceRm = {
+  service: "kb",
+  command: "+source-rm",
+  risk: "high-risk-write",
+  description: "Delete one ZIP child file or recursively delete one directory; keeps the parent source.",
+  flags: [
+    ...sourceFlags,
+    pathFlag,
+    revisionFlag,
+    { name: "recursive", type: "boolean", desc: "Explicitly allow recursive directory deletion" }
+  ],
+  validate: validateMutation,
+  dryRun: (ctx) => preview(ctx, "POST", "directory", mutationBody(ctx, deleteOperation(ctx))),
+  execute: (ctx) => kbApi(ctx, "POST", endpoint(ctx), {}, mutationBody(ctx, deleteOperation(ctx)), apiOptions)
+};
+
+// src/commands/te-kb/version-management.ts
+import { promises as fs4 } from "fs";
+import path4 from "path";
+var API = "/agent/api/external/knowledge-bases/versions";
+var apiOptions2 = { preserveErrorMetadata: true, retryUnauthorized: true };
+var targetFlags = [
+  { name: "name", type: "string", required: true, minLength: 1, maxLength: 200, desc: "Exact knowledge base name copied from +list" },
+  { name: "scope", type: "string", desc: "Exact personal or company scope; omit for personal then company lookup" }
+];
+var versionFlag = { name: "version", type: "number", required: true, min: 1, max: 2147483647, desc: "Historical version number from +versions, without the v prefix" };
+var sourceFlag = { name: "id", type: "string", required: true, minLength: 1, maxLength: 191, desc: "Stable historical source ID copied from +version-sources" };
+var pagingFlags = [
+  { name: "cursor", type: "string", desc: "nextCursor from the previous page; omit for the first page" },
+  { name: "limit", type: "number", default: 100, min: 1, max: 200, desc: "Page size from 1 to 200" }
+];
+var pathFlag2 = { name: "path", type: "string", desc: "Exact path relative to the historical source directory" };
+function positiveInteger(ctx, flag) {
+  const value = ctx.num(flag);
+  if (!Number.isSafeInteger(value) || value < 1 || value > 2147483647) throw new CliValidationError(`--${flag} must be a positive integer no greater than 2147483647.`);
+  return value;
+}
+function validateTarget(ctx) {
+  const name = ctx.str("name").trim();
+  if (!name || name.length > 200) throw new CliValidationError("--name must contain 1 to 200 characters.");
+  getExternalKnowledgeBaseTargetScope(ctx);
+}
+function validateVersion(ctx) {
+  validateTarget(ctx);
+  positiveInteger(ctx, "version");
+}
+function validateSource(ctx) {
+  validateVersion(ctx);
+  const id = ctx.str("id").trim();
+  if (!id || id.length > 191) throw new CliValidationError("--id must contain 1 to 191 characters.");
+}
+function validatePage(ctx) {
+  const limit = ctx.num("limit");
+  if (!Number.isInteger(limit) || limit < 1 || limit > 200) throw new CliValidationError("--limit must be an integer from 1 to 200.");
+  if (ctx.str("cursor").length > 500) throw new CliValidationError("--cursor must be at most 500 characters.");
+}
+function validatePath(ctx, required = false) {
+  const value = ctx.str("path");
+  if (!value && !required) return;
+  if (!value || value.length > 500 || /[\\\x00-\x1f\x7f]/.test(value) || /^[A-Za-z]:/.test(value) || value.split("/").some((part) => !part || part === "." || part === "..")) {
+    throw new CliValidationError("--path must be a normalized relative path inside the historical source.");
+  }
+}
+function query2(ctx) {
+  const scope = getExternalKnowledgeBaseTargetScope(ctx);
+  return { name: ctx.str("name").trim(), ...scope ? { scope } : {} };
+}
+function pageQuery(ctx) {
+  return { ...query2(ctx), limit: ctx.num("limit"), ...ctx.str("cursor") ? { cursor: ctx.str("cursor") } : {} };
+}
+function versionEndpoint(ctx, suffix = "") {
+  return `${API}/${positiveInteger(ctx, "version")}${suffix}`;
+}
+function sourceEndpoint(ctx, action) {
+  return versionEndpoint(ctx, `/sources/${encodeURIComponent(ctx.str("id").trim())}/${action}`);
+}
+function preview2(ctx, endpoint2, params, body) {
+  return { method: body ? "POST" : "GET", url: `${ctx.host().replace(/\/$/, "")}${endpoint2}`, params, ...body ? { body } : {} };
+}
+var versions = {
+  service: "kb",
+  command: "+versions",
+  risk: "read",
+  description: "List immutable published versions and the latest version ID, one page at a time.",
+  flags: [...targetFlags, ...pagingFlags],
+  validate: (ctx) => {
+    validateTarget(ctx);
+    validatePage(ctx);
+    if (ctx.str("cursor") && (!/^[1-9][0-9]*$/.test(ctx.str("cursor")) || Number(ctx.str("cursor")) > 2147483647)) throw new CliValidationError("--cursor must be a version number returned as nextCursor.");
+  },
+  dryRun: (ctx) => preview2(ctx, API, pageQuery(ctx)),
+  execute: (ctx) => kbApi(ctx, "GET", API, pageQuery(ctx), void 0, apiOptions2)
+};
+var versionShow = {
+  service: "kb",
+  command: "+version-show",
+  risk: "read",
+  description: "Read one published version summary without reading current sources.",
+  flags: [...targetFlags, versionFlag],
+  validate: validateVersion,
+  dryRun: (ctx) => preview2(ctx, versionEndpoint(ctx), query2(ctx)),
+  execute: (ctx) => kbApi(ctx, "GET", versionEndpoint(ctx), query2(ctx), void 0, apiOptions2)
+};
+var versionSources = {
+  service: "kb",
+  command: "+version-sources",
+  risk: "read",
+  description: "List historical sources and stable IDs from one immutable version.",
+  flags: [...targetFlags, versionFlag, ...pagingFlags, { name: "source-type", type: "string", desc: "Optional source type filter: file | url | zip" }],
+  validate: (ctx) => {
+    validateVersion(ctx);
+    validatePage(ctx);
+    if (ctx.str("source-type") && !["file", "url", "zip"].includes(ctx.str("source-type"))) throw new CliValidationError("--source-type must be file, url, or zip.");
+  },
+  dryRun: (ctx) => preview2(ctx, versionEndpoint(ctx, "/sources"), { ...pageQuery(ctx), ...ctx.str("source-type") ? { sourceType: ctx.str("source-type") } : {} }),
+  execute: (ctx) => kbApi(ctx, "GET", versionEndpoint(ctx, "/sources"), { ...pageQuery(ctx), ...ctx.str("source-type") ? { sourceType: ctx.str("source-type") } : {} }, void 0, apiOptions2)
+};
+var versionDiff = {
+  service: "kb",
+  command: "+version-diff",
+  risk: "read",
+  description: "Compare historical source additions, deletions, content, and metadata between two versions.",
+  flags: [...targetFlags, { ...versionFlag, name: "from", desc: "Before version number" }, { ...versionFlag, name: "to", desc: "After version number" }],
+  validate: (ctx) => {
+    validateTarget(ctx);
+    positiveInteger(ctx, "from");
+    positiveInteger(ctx, "to");
+  },
+  dryRun: (ctx) => preview2(ctx, `${API}/compare`, { ...query2(ctx), from: ctx.num("from"), to: ctx.num("to") }),
+  execute: (ctx) => kbApi(ctx, "GET", `${API}/compare`, { ...query2(ctx), from: ctx.num("from"), to: ctx.num("to") }, void 0, apiOptions2)
+};
+var versionTree = {
+  service: "kb",
+  command: "+version-tree",
+  risk: "read",
+  description: "List a historical ZIP or URL source directory without changing current files.",
+  flags: [...targetFlags, versionFlag, sourceFlag, pathFlag2, ...pagingFlags],
+  validate: (ctx) => {
+    validateSource(ctx);
+    validatePath(ctx);
+    validatePage(ctx);
+  },
+  dryRun: (ctx) => preview2(ctx, sourceEndpoint(ctx, "tree"), { ...pageQuery(ctx), path: ctx.str("path") }),
+  execute: (ctx) => kbApi(ctx, "GET", sourceEndpoint(ctx, "tree"), { ...pageQuery(ctx), path: ctx.str("path") }, void 0, apiOptions2)
+};
+var versionRead = {
+  service: "kb",
+  command: "+version-read",
+  risk: "read",
+  description: "Preview one historical directory child file; unsupported or oversized files return metadata only.",
+  flags: [...targetFlags, versionFlag, sourceFlag, { ...pathFlag2, required: true }],
+  validate: (ctx) => {
+    validateSource(ctx);
+    validatePath(ctx, true);
+  },
+  dryRun: (ctx) => preview2(ctx, sourceEndpoint(ctx, "file"), { ...query2(ctx), path: ctx.str("path") }),
+  execute: (ctx) => kbApi(ctx, "GET", sourceEndpoint(ctx, "file"), { ...query2(ctx), path: ctx.str("path") }, void 0, apiOptions2)
+};
+var versionDownload = {
+  service: "kb",
+  command: "+version-download",
+  risk: "read",
+  description: "Download one ordinary historical file source to a new local file. ZIP/URL directories cannot be downloaded.",
+  flags: [...targetFlags, versionFlag, sourceFlag, { name: "output", type: "string", required: true, desc: "New local output path; existing files are never overwritten" }],
+  validate: (ctx) => {
+    validateSource(ctx);
+    if (!ctx.str("output").trim()) throw new CliValidationError("--output is required.");
+  },
+  dryRun: (ctx) => ({ ...preview2(ctx, sourceEndpoint(ctx, "raw"), query2(ctx)), output: path4.resolve(ctx.str("output")) }),
+  execute: async (ctx) => {
+    const result = await kbApi(ctx, "GET", sourceEndpoint(ctx, "raw"), query2(ctx), void 0, { ...apiOptions2, responseType: "bytes" });
+    const output = path4.resolve(ctx.str("output"));
+    const bytes = Buffer.from(result.bytes);
+    await fs4.writeFile(output, bytes, { flag: "wx" });
+    return { versionNumber: ctx.num("version"), sourceId: ctx.str("id").trim(), sizeBytes: String(bytes.length), output };
+  }
+};
+function rollbackBody(ctx) {
+  return { requestId: ctx.str("request-id"), expectedLatestVersionId: ctx.str("expected-latest-version-id") };
+}
+var rollback = {
+  service: "kb",
+  command: "+rollback",
+  risk: "high-risk-write",
+  description: "Restore an earlier version as a new publication. Replace target-source drafts, delete other compiled sources, and preserve unpublished additions. Reuse request-id on network retries.",
+  flags: [
+    ...targetFlags,
+    versionFlag,
+    { name: "request-id", type: "string", required: true, maxLength: 191, desc: "Caller-generated stable ASCII request ID; reuse exactly for retries of this logical operation" },
+    { name: "expected-latest-version-id", type: "string", required: true, maxLength: 191, desc: "latestVersionId returned by +versions; conflicts require fresh discovery and a new intentional request" }
+  ],
+  validate: (ctx) => {
+    validateVersion(ctx);
+    if (!/^[A-Za-z0-9_-]{1,191}$/.test(ctx.str("request-id"))) throw new CliValidationError("--request-id must contain 1-191 ASCII letters, digits, underscores, or hyphens.");
+    const latest = ctx.str("expected-latest-version-id");
+    if (!latest || latest.length > 191) throw new CliValidationError("--expected-latest-version-id must contain 1 to 191 characters.");
+  },
+  dryRun: (ctx) => preview2(ctx, versionEndpoint(ctx, "/rollback"), query2(ctx), rollbackBody(ctx)),
+  execute: (ctx) => kbApi(ctx, "POST", versionEndpoint(ctx, "/rollback"), query2(ctx), rollbackBody(ctx), apiOptions2)
+};
+var rollbackStatus = {
+  service: "kb",
+  command: "+rollback-status",
+  risk: "read",
+  description: "Read one persisted rollback operation without polling. A running operation with errorCode requires administrator review; never retry it as a new write.",
+  flags: [...targetFlags, { name: "operation-id", type: "string", required: true, minLength: 1, maxLength: 191, desc: "operationId returned by +rollback" }],
+  validate: (ctx) => {
+    validateTarget(ctx);
+    if (!ctx.str("operation-id").trim() || ctx.str("operation-id").length > 191) throw new CliValidationError("--operation-id must contain 1 to 191 characters.");
+  },
+  dryRun: (ctx) => preview2(ctx, `${API}/operations/${encodeURIComponent(ctx.str("operation-id").trim())}`, query2(ctx)),
+  execute: (ctx) => kbApi(ctx, "GET", `${API}/operations/${encodeURIComponent(ctx.str("operation-id").trim())}`, query2(ctx), void 0, apiOptions2)
+};
+
+// src/commands/te-kb/index.ts
+var commands = [
+  versions,
+  versionShow,
+  versionSources,
+  versionDiff,
+  versionTree,
+  versionRead,
+  versionDownload,
+  rollback,
+  rollbackStatus,
+  sourceLs,
+  sourceRead,
+  sourcePut,
+  sourceRm,
+  ask,
+  askStatus,
+  add,
+  url,
+  compile,
+  remove,
+  create,
+  listSources,
+  rmSource,
+  schema,
+  status,
+  kbList,
+  kbIndex,
+  kbGrep,
+  kbRead,
+  importSnapshot,
+  importStatus
+];
+var te_kb_default = commands;
+export {
+  add,
+  ask,
+  askStatus,
+  compile,
+  create,
+  te_kb_default as default,
+  importSnapshot,
+  importStatus,
+  kbGrep,
+  kbIndex,
+  kbList,
+  kbRead,
+  listSources,
+  remove,
+  rmSource,
+  rollback,
+  rollbackStatus,
+  schema,
+  sourceLs,
+  sourcePut,
+  sourceRead,
+  sourceRm,
+  status,
+  url,
+  versionDiff,
+  versionDownload,
+  versionRead,
+  versionShow,
+  versionSources,
+  versionTree,
+  versions
+};