@thinkingai/ae-cli 6.0.48-customer.1 → 6.0.48

package/dist/{te-kb-BUD6N3NI.js → te-kb-WYQWHFSC.js}

@@ -2,29 +2,43 @@ import { createRequire as __createRequire } from 'node:module'; const require =
 import {
   kbApi,
   kbUpload
-} from "./chunk-JYMGHGCE.js";
+} from "./chunk-VXNMYUXU.js";
 import {
-  printError
-} from "./chunk-KEWVSO64.js";
+  TeAgentApiError
+} from "./chunk-BBEFP4SB.js";
 import {
   CapabilityGatewayError
-} from "./chunk-GJXRF7Y6.js";
+} from "./chunk-QJQZH5GQ.js";
+import {
+  printError
+} from "./chunk-CZU3V3DQ.js";
 import "./chunk-Y74WTIKJ.js";
-import "./chunk-RWXIXOZG.js";
-import "./chunk-O6K2ODUE.js";
-import "./chunk-KZ6ZHF5J.js";
+import "./chunk-ATSM5XAW.js";
+import "./chunk-WZ6YVQSF.js";
 import {
   CliValidationError,
   PermissionError
-} from "./chunk-533JK3YX.js";
-import "./chunk-FR2EDAQM.js";
+} 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",
@@ -71,6 +85,8 @@ function sanitizeFilename(name) {
 function getMimeType(filename) {
   const ext = path.extname(filename).toLowerCase();
   switch (ext) {
+    case ".zip":
+      return "application/zip";
     case ".md":
     case ".markdown":
       return "text/markdown";
@@ -205,9 +221,10 @@ function dedupeByFilename(files) {
     return { ...f, filename: `${stem}-${count}${ext}` };
   });
 }
-function buildForm(name, files) {
+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);
   }
@@ -219,6 +236,7 @@ var 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",
@@ -228,24 +246,29 @@ var add = {
   ],
   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: {
-        name: ctx.str("name"),
-        files: items.map((item) => ({ value: item, type: classifyInput(item) })),
-        contentType: "multipart/form-data"
-      }
+      body
     };
   },
   execute: async (ctx) => {
     const name = ctx.str("name");
+    const scope = getExternalKnowledgeBaseTargetScope(ctx);
     const files = await collectFiles(ctx);
-    const form = buildForm(name, files);
+    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 })),
@@ -265,10 +288,15 @@ function getMode(ctx) {
   return mode;
 }
 function buildBody(ctx) {
-  return {
+  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",
@@ -276,11 +304,14 @@ var 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: "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",
@@ -293,16 +324,23 @@ var compile = {
 // src/commands/te-kb/remove.ts
 var API_PATH3 = "/agent/api/external/knowledge-bases";
 function buildBody2(ctx) {
-  return { name: ctx.str("name") };
+  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: "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}`,
@@ -389,10 +427,12 @@ function sourceSelector(ctx) {
   throw new CliValidationError("One of --id or --display-name is required.");
 }
 function buildBody4(ctx) {
-  return {
-    name: ctx.str("name"),
-    ...sourceSelector(ctx)
+  const body = {
+    name: ctx.str("name")
   };
+  const scope = getExternalKnowledgeBaseTargetScope(ctx);
+  if (scope) body.scope = scope;
+  return { ...body, ...sourceSelector(ctx) };
 }
 var rmSource = {
   service: "kb",
@@ -400,11 +440,13 @@ var rmSource = {
   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) => ({
@@ -413,8 +455,7 @@ var rmSource = {
     body: buildBody4(ctx)
   }),
   execute: async (ctx) => kbApi(ctx, "DELETE", API_PATH5, {}, buildBody4(ctx), {
-    preserveErrorMetadata: true,
-    retryUnauthorized: true
+    preserveErrorMetadata: true
   })
 };
 
@@ -424,6 +465,8 @@ 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;
@@ -442,8 +485,9 @@ var 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 displayName to use for schema generation" },
+    { name: "model", type: "string", required: false, desc: "Optional model reference: Model.id, legacy modelId, or modelId::scope" },
     {
       name: "custom-instructions",
       type: "string",
@@ -453,6 +497,9 @@ var schema = {
     }
   ],
   risk: "write",
+  validate: (ctx) => {
+    getExternalKnowledgeBaseTargetScope(ctx);
+  },
   dryRun: (ctx) => ({
     method: "POST",
     url: `${ctx.host().replace(/\/$/, "")}${API_PATH6}`,
@@ -464,18 +511,25 @@ var schema = {
 // src/commands/te-kb/status.ts
 var API_PATH7 = "/agent/api/external/knowledge-bases/status";
 function buildBody6(ctx) {
-  return {
+  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: "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}`,
@@ -576,12 +630,14 @@ function knowledgeBaseName(ctx) {
 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.",
+  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",
@@ -590,6 +646,12 @@ var listSources = {
       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",
@@ -603,19 +665,21 @@ var listSources = {
         `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) => kbApi(
-    ctx,
-    "GET",
-    API_PATH10,
-    { name: knowledgeBaseName(ctx) },
-    void 0,
-    { preserveErrorMetadata: true, retryUnauthorized: true }
-  )
+  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
@@ -626,8 +690,8 @@ function buildBody9(ctx) {
     sources: ctx.json("sources"),
     paths: ctx.json("paths")
   };
-  const topK = ctx.num("top-k");
-  if (topK) body.topK = topK;
+  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;
@@ -635,7 +699,7 @@ function buildBody9(ctx) {
 var kbGrep = {
   service: "kb",
   command: "+grep",
-  description: "Keyword-search knowledge base pages via POST /agent/api/external/knowledge-bases/grep. Returns matched lines with path, line number, breadcrumb, context snippet, and the section line range (sectionStartLine/sectionEndLine) of each hit. Copy --paths from +index (wiki pages or subdirectories). Use +read with the hit range to open the section.",
+  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",
@@ -656,7 +720,7 @@ var kbGrep = {
       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, desc: "Max number of hits to return (1-50, default 10)" },
+    { 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",
@@ -670,15 +734,39 @@ var kbGrep = {
 
 // 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.num("offset");
-  if (offset) body.offset = offset;
-  const limit = ctx.num("limit");
-  if (limit) body.limit = limit;
+  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;
@@ -701,8 +789,9 @@ var kbRead = {
       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, desc: "Start line (1-based). Omit to read from the beginning." },
-    { name: "limit", type: "number", required: false, desc: "Max number of lines to return (1-10000)." },
+    { 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",
@@ -712,6 +801,14 @@ var kbRead = {
     { 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}`,
@@ -777,21 +874,13 @@ function transformCompletedResponse(response) {
   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;
-  if (response.maxTurns !== void 0) result.maxTurns = response.maxTurns;
   return result;
 }
-function buildFailedMessage(response) {
-  const type = response.error?.type || "unknown";
-  const message = response.error?.message || "Ask execution failed";
-  return `[${type}] ${message} (executionId: ${response.executionId})`;
-}
 
 // 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;
-var MIN_MAX_TURNS = 1;
-var MAX_MAX_TURNS = 100;
 function validateQuestion(question) {
   const len = question.length;
   if (len < MIN_QUESTION_LEN || len > MAX_QUESTION_LEN) {
@@ -805,13 +894,6 @@ function validateLocale(locale) {
     throw new Error(`Invalid --locale: ${locale}. Must be one of: zh | en | ja | ko`);
   }
 }
-function validateMaxTurns(maxTurns) {
-  if (maxTurns !== 0 && (maxTurns < MIN_MAX_TURNS || maxTurns > MAX_MAX_TURNS)) {
-    throw new Error(
-      `Invalid --max-turns: ${maxTurns}. Must be between ${MIN_MAX_TURNS} and ${MAX_MAX_TURNS}.`
-    );
-  }
-}
 function buildBody11(ctx) {
   const body = {
     question: ctx.str("question")
@@ -820,8 +902,6 @@ function buildBody11(ctx) {
   if (sources) body.sources = sources;
   const modelId = ctx.str("model-id");
   if (modelId) body.modelId = modelId;
-  const maxTurns = ctx.num("max-turns");
-  if (maxTurns) body.maxTurns = maxTurns;
   const locale = ctx.str("locale");
   if (locale) body.locale = locale;
   return body;
@@ -850,12 +930,6 @@ var ask = {
       required: false,
       desc: "Optional LLM model ID (e.g. claude-sonnet-4-6). Omit to use the platform default model."
     },
-    {
-      name: "max-turns",
-      type: "number",
-      required: false,
-      desc: "Optional agent turn limit (1-100, default 50 on server when omitted)."
-    },
     { name: "locale", type: "string", required: false, desc: "Optional locale: zh | en | ja | ko" },
     {
       name: "no-wait",
@@ -868,7 +942,6 @@ var ask = {
   validate: (ctx) => {
     validateQuestion(ctx.str("question"));
     validateLocale(ctx.str("locale"));
-    validateMaxTurns(ctx.num("max-turns"));
   },
   dryRun: (ctx) => ({
     method: "POST",
@@ -896,7 +969,14 @@ var ask = {
       return transformCompletedResponse(finalResponse);
     }
     if (finalResponse.status === "failed") {
-      throw new Error(buildFailedMessage(finalResponse));
+      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}`);
   }
@@ -955,6 +1035,8 @@ function buildBody12(ctx) {
     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");
@@ -967,12 +1049,14 @@ var 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) => ({
@@ -988,6 +1072,16 @@ 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)) {
@@ -1043,8 +1137,15 @@ function appendOptionalFields(ctx, form) {
 var importSnapshot = {
   service: "kb",
   command: "+import",
-  description: "Import a compiled Markdown ZIP snapshot as a personal read-only knowledge base.",
+  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",
@@ -1056,7 +1157,7 @@ var importSnapshot = {
       type: "string",
       required: true,
       maxLength: 30,
-      desc: "Personal knowledge base name (max 30 characters)"
+      desc: "Knowledge base name (max 30 characters)"
     },
     {
       name: "description",
@@ -1081,6 +1182,7 @@ var importSnapshot = {
   ],
   risk: "write",
   validate: (ctx) => {
+    getScope2(ctx);
     validateArchivePath(ctx.str("file"));
     normalizeTags2(ctx.json("tags"));
   },
@@ -1093,13 +1195,14 @@ var importSnapshot = {
       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) {
@@ -1114,6 +1217,9 @@ var importSnapshot = {
         );
       }
       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;
       }
@@ -1157,6 +1263,7 @@ var importStatus = {
     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,
@@ -1164,23 +1271,413 @@ var importStatus = {
         API_PATH15,
         { requestId: requestIdFrom(ctx) },
         void 0,
-        { preserveErrorMetadata: true, retryUnauthorized: true }
+        { preserveErrorMetadata: true }
       );
     } catch (error) {
-      if (!(error instanceof CapabilityGatewayError) || error.hint) throw error;
-      throw new CapabilityGatewayError(
-        error.message,
-        error.code,
-        error.httpStatus,
-        "Verify the request ID and that the server supports kb +import-status. Do not retry the import until its status is known.",
-        error.meta
-      );
+      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,
@@ -1216,7 +1713,20 @@ export {
   listSources,
   remove,
   rmSource,
+  rollback,
+  rollbackStatus,
   schema,
+  sourceLs,
+  sourcePut,
+  sourceRead,
+  sourceRm,
   status,
-  url
+  url,
+  versionDiff,
+  versionDownload,
+  versionRead,
+  versionShow,
+  versionSources,
+  versionTree,
+  versions
 };