@thinkingai/ae-cli 6.0.55 → 6.0.57

package/dist/{te-kb-ULATOTQ3.js → te-kb-WSMOW7WS.js}

@@ -2,23 +2,44 @@ import { createRequire as __createRequire } from 'node:module'; const require =
 import {
   kbApi,
   kbUpload
-} from "./chunk-7KU2WNQE.js";
+} from "./chunk-QEMQKVHW.js";
 import {
   TeAgentApiError
-} from "./chunk-3YVEAZUN.js";
+} from "./chunk-RJHGDWSC.js";
 import {
   CapabilityGatewayError
-} from "./chunk-VZZNLV3I.js";
+} from "./chunk-JCWM2TYP.js";
 import {
   printError
-} from "./chunk-6VNIR4AP.js";
+} from "./chunk-752BSLZC.js";
 import "./chunk-Y74WTIKJ.js";
-import "./chunk-GHXZK54S.js";
-import "./chunk-ZL7SGNIA.js";
+import "./chunk-TULINOLS.js";
+import "./chunk-H3K5UGYC.js";
+import "./chunk-JNVVJ273.js";
 import {
+  CliApiError,
   CliValidationError,
-  PermissionError
-} from "./chunk-WNGFSIOB.js";
+  PermissionError,
+  kbExecutionContextRequired
+} from "./chunk-Z3Q2AEIN.js";
+
+// src/commands/te-kb/project-target.ts
+var API_PATH = "/agent/api/project-semantic-target";
+var projectTargetGet = {
+  service: "kb",
+  resource: "project-target",
+  command: "get",
+  description: "Resolve the company project semantic KB on the server, including disabled and inaccessible candidates. Never select a different target on permission denial.",
+  flags: [{ name: "project-id", type: "string", required: true, desc: "Exact project ID" }],
+  risk: "read",
+  validate(ctx) {
+    if (!/^[1-9]\d{0,15}$/.test(ctx.str("project-id"))) throw new Error("A valid --project-id is required.");
+  },
+  dryRun(ctx) {
+    return { method: "GET", url: `${ctx.host().replace(/\/$/, "")}${API_PATH}`, params: { projectId: ctx.str("project-id") } };
+  },
+  execute: async (ctx) => kbApi(ctx, "GET", API_PATH, { projectId: ctx.str("project-id") })
+};
 
 // src/commands/te-kb/target-scope.ts
 function getExternalKnowledgeBaseTargetScope(ctx) {
@@ -30,8 +51,244 @@ function getExternalKnowledgeBaseTargetScope(ctx) {
   );
 }
 
+// src/commands/te-kb/publication.ts
+var root = "/agent/api/external/knowledge-bases";
+var options = { preserveErrorMetadata: true, retryUnauthorized: false };
+var targets = [
+  { name: "name", type: "string", required: true, desc: "Knowledge base name" },
+  {
+    name: "scope",
+    type: "string",
+    desc: "personal | company; omit for personal then company lookup"
+  }
+];
+var candidate = {
+  name: "candidate",
+  type: "string",
+  required: true,
+  desc: "Immutable candidate ID returned by publication get"
+};
+function selector(ctx) {
+  return {
+    name: ctx.str("name"),
+    ...getExternalKnowledgeBaseTargetScope(ctx) ? { scope: getExternalKnowledgeBaseTargetScope(ctx) } : {}
+  };
+}
+function candidatePath(ctx) {
+  const id = ctx.str("candidate");
+  if (!/^[A-Za-z0-9_-]{1,191}$/.test(id)) throw new CliValidationError("Invalid --candidate");
+  return `${root}/publication-candidates/${id}`;
+}
+function targetCommand(resource, command2, suffix, extra = []) {
+  const method = command2 === "discard" ? "POST" : "GET";
+  const endpoint3 = (ctx) => resource === "publication" ? `${root}/publication` : candidatePath(ctx) + suffix;
+  const params = (ctx) => ({
+    ...selector(ctx),
+    ...command2 === "read" ? { path: ctx.str("path") } : {},
+    ...command2 === "changes" ? changesParams(ctx) : {}
+  });
+  return {
+    service: "kb",
+    resource,
+    command: command2,
+    risk: command2 === "discard" ? "high-risk-write" : "read",
+    description: command2 === "discard" ? "Close a retryable failed candidate after a confirmed failed publication; pending requests use approval cancel." : `Read ${resource} ${command2} from immutable publication metadata.`,
+    flags: [...targets, ...resource === "candidate" ? [candidate] : [], ...extra],
+    validate: (ctx) => {
+      selector(ctx);
+      endpoint3(ctx);
+      if (command2 === "changes") changesParams(ctx);
+    },
+    dryRun: (ctx) => ({
+      method,
+      url: ctx.host().replace(/\/$/, "") + endpoint3(ctx),
+      params: params(ctx),
+      ...method === "POST" ? { body: {} } : {}
+    }),
+    execute: async (ctx) => {
+      const result = await kbApi(
+        ctx,
+        method,
+        endpoint3(ctx),
+        params(ctx),
+        method === "POST" ? {} : void 0,
+        options
+      );
+      if (command2 === "changes") {
+        const query6 = changesParams(ctx);
+        const directoryRequested = !query6.entryId && ["group", "search", "change", "offset", "limit"].some((key) => key in query6);
+        const memberRequested = query6.entryId && ["fileOffset", "fileLimit", "fileSearch"].some((key) => key in query6);
+        const body4 = result && typeof result === "object" ? result : {};
+        if (directoryRequested && !body4.page || memberRequested && !body4.filePage)
+          throw new CliApiError(
+            "This server does not support filtered or paginated candidate changes.",
+            {
+              code: "KB_CANDIDATE_PAGING_UNSUPPORTED",
+              hint: "Deploy a compatible server or omit the new paging and filter flags."
+            }
+          );
+      }
+      return result;
+    }
+  };
+}
+var publicationGet = targetCommand("publication", "get", "");
+var candidateGet = targetCommand("candidate", "get", "");
+var candidateRead = targetCommand("candidate", "read", "/files", [
+  {
+    name: "path",
+    type: "string",
+    required: true,
+    desc: "index.md, CLAUDE.md or wiki Markdown path from the candidate"
+  }
+]);
+function changesParams(ctx) {
+  const entryId = ctx.str("entry-id");
+  const file = ctx.str("file");
+  const context = ctx.optionalNum("context");
+  if (file && !entryId) throw new CliValidationError("--file requires --entry-id");
+  if (context !== void 0 && context !== 0 && context !== 3)
+    throw new CliValidationError("--context must be 0 or 3");
+  const group = ctx.str("group");
+  const change = ctx.str("change");
+  const search = ctx.str("search");
+  const fileSearch = ctx.str("file-search");
+  if (group && !["sources", "wiki", "index"].includes(group))
+    throw new CliValidationError("--group must be sources, wiki or index");
+  if (change && !["added", "modified", "deleted"].includes(change))
+    throw new CliValidationError("--change must be added, modified or deleted");
+  if (search.length > 500 || fileSearch.length > 500)
+    throw new CliValidationError("Search text must not exceed 500 characters");
+  const paging = {};
+  for (const [flag2, key, min, max] of [
+    ["offset", "offset", 0, 1e6],
+    ["limit", "limit", 1, 200],
+    ["file-offset", "fileOffset", 0, 1e6],
+    ["file-limit", "fileLimit", 1, 200]
+  ]) {
+    const value = ctx.optionalNum(flag2);
+    if (value === void 0) continue;
+    if (!Number.isInteger(value) || value < min || value > max)
+      throw new CliValidationError(`--${flag2} must be an integer between ${min} and ${max}`);
+    paging[key] = value;
+  }
+  if ((fileSearch || "fileOffset" in paging || "fileLimit" in paging) && !entryId)
+    throw new CliValidationError("Member search and pagination require --entry-id");
+  return {
+    ...paging,
+    ...group ? { group } : {},
+    ...change ? { change } : {},
+    ...search ? { search } : {},
+    ...fileSearch ? { fileSearch } : {},
+    ...entryId ? { entryId } : {},
+    ...file ? { file } : {},
+    ...context !== void 0 ? { context } : {}
+  };
+}
+var candidateChanges = targetCommand("candidate", "changes", "/changes", [
+  { name: "group", type: "string", desc: "Filter changed entries: sources | wiki | index" },
+  { name: "search", type: "string", desc: "Search changed names or paths (up to 500 characters)" },
+  { name: "change", type: "string", desc: "Filter change type: added | modified | deleted" },
+  { name: "offset", type: "number", desc: "Changed entry offset (0 to 1000000)" },
+  {
+    name: "limit",
+    type: "number",
+    desc: "Changed entry page size (1 to 200); omit for legacy full list"
+  },
+  { name: "file-offset", type: "number", desc: "Changed member offset (0 to 1000000)" },
+  { name: "file-limit", type: "number", desc: "Changed member page size (1 to 200)" },
+  { name: "file-search", type: "string", desc: "Search changed member paths" },
+  {
+    name: "entry-id",
+    type: "string",
+    desc: "Changed entry ID returned by candidate changes; omit to list changes"
+  },
+  {
+    name: "file",
+    type: "string",
+    desc: "Changed member path returned by an entry detail; requires --entry-id"
+  },
+  {
+    name: "context",
+    type: "number",
+    desc: "Unchanged context lines: 0 (default) or 3"
+  }
+]);
+var candidateDiscard = targetCommand("candidate", "discard", "/discard");
+function createBody(ctx) {
+  const sources = ctx.json("sources");
+  if (sources !== void 0 && sources !== null && (!Array.isArray(sources) || sources.length > 100 || sources.some(
+    (source) => !source || !["personal", "company", "system"].includes(source.scope) || typeof source.name !== "string" || !source.name || Object.keys(source).some((key) => !["name", "scope"].includes(key))
+  )))
+    throw new CliValidationError("--sources must be an array of {scope,name}");
+  return {
+    ...sources ? { sources } : {},
+    ...ctx.str("locale") ? { locale: ctx.str("locale") } : {}
+  };
+}
+var readContextCreate = {
+  service: "kb",
+  resource: "read-context",
+  command: "create",
+  risk: "read",
+  description: "Pin the current authorized formal KB views for subsequent reads (15 minutes).",
+  flags: [
+    {
+      name: "sources",
+      type: "json",
+      desc: "Optional array of {scope,name}; omit to discover authorized published KBs"
+    },
+    { name: "locale", type: "string", desc: "zh | en | ja | ko" }
+  ],
+  validate: (ctx) => {
+    createBody(ctx);
+  },
+  dryRun: (ctx) => ({
+    method: "POST",
+    url: ctx.host().replace(/\/$/, "") + `${root}/read-contexts`,
+    body: createBody(ctx)
+  }),
+  execute: (ctx) => kbApi(ctx, "POST", `${root}/read-contexts`, {}, createBody(ctx), options)
+};
+var readContextRelease = {
+  service: "kb",
+  resource: "read-context",
+  command: "release",
+  risk: "write",
+  description: "Release a read context owned by the current user.",
+  flags: [
+    {
+      name: "id",
+      type: "string",
+      required: true,
+      desc: "readContextId returned by read-context create"
+    }
+  ],
+  dryRun: (ctx) => ({
+    method: "DELETE",
+    url: ctx.host().replace(/\/$/, "") + `${root}/read-contexts/${encodeURIComponent(ctx.str("id"))}`
+  }),
+  execute: (ctx) => kbApi(
+    ctx,
+    "DELETE",
+    `${root}/read-contexts/${encodeURIComponent(ctx.str("id"))}`,
+    {},
+    {},
+    options
+  )
+};
+var publicationCommands = [
+  publicationGet,
+  candidateGet,
+  candidateRead,
+  candidateChanges,
+  candidateDiscard,
+  readContextCreate,
+  readContextRelease
+];
+
 // src/commands/te-kb/source-check-url-updates.ts
-var API_PATH = "/agent/api/external/knowledge-bases/sources/check-url-updates";
+var API_PATH2 = "/agent/api/external/knowledge-bases/sources/check-url-updates";
 function body(ctx) {
   const scope = getExternalKnowledgeBaseTargetScope(ctx);
   return { name: ctx.str("name").trim(), sourceId: ctx.str("id").trim(), ...scope ? { scope } : {} };
@@ -54,15 +311,15 @@ var sourceCheckUrlUpdates = {
     }
     getExternalKnowledgeBaseTargetScope(ctx);
   },
-  dryRun: (ctx) => ({ method: "POST", url: `${ctx.host().replace(/\/$/, "")}${API_PATH}`, body: body(ctx) }),
-  execute: (ctx) => kbApi(ctx, "POST", API_PATH, {}, body(ctx), { preserveErrorMetadata: true })
+  dryRun: (ctx) => ({ method: "POST", url: `${ctx.host().replace(/\/$/, "")}${API_PATH2}`, body: body(ctx) }),
+  execute: (ctx) => kbApi(ctx, "POST", API_PATH2, {}, body(ctx), { preserveErrorMetadata: true })
 };
 
 // src/commands/te-kb/schema-import.ts
 import { promises as fs } from "fs";
 import path from "path";
 var ROOT = "/agent/api/external/knowledge-bases/schema";
-var options = { preserveBusinessErrorCode: true, preserveErrorMetadata: true };
+var options2 = { preserveBusinessErrorCode: true, preserveErrorMetadata: true };
 var flag = (name, type, desc, required = false) => ({ name, type, desc, required });
 var targetFlags = [flag("name", "string", "Knowledge base name", true), flag("scope", "string", "Exact scope: personal | company")];
 var identityFlags = [flag("import-id", "string", "Stable import ID", true)];
@@ -121,7 +378,7 @@ async function waitSchemaImport(ctx, initial, api = kbApi, sleep = (ms) => new P
   let current = initial;
   while (current.task && Date.now() < deadline) {
     await sleep(Math.min(2e3, Math.max(1, deadline - Date.now())));
-    current = await api(ctx, "GET", `${ROOT}/imports/${encodeURIComponent(initial.id)}`, {}, void 0, options);
+    current = await api(ctx, "GET", `${ROOT}/imports/${encodeURIComponent(initial.id)}`, {}, void 0, options2);
   }
   return { ...current, waitTimedOut: Boolean(current.task) };
 }
@@ -140,10 +397,10 @@ async function executeSchemaImport(ctx, action, api = kbApi, upload = kbUpload)
       form.set("replacesImportId", ctx.str("replaces-import-id"));
       form.set("expectedReplacedRevision", String(ctx.num("replaced-revision")));
     }
-    result = await upload(ctx, endpoint(ctx, action), form, {}, options);
+    result = await upload(ctx, endpoint(ctx, action), form, {}, options2);
   } else if (["download", "list", "status", "content", "diff"].includes(action)) {
     const binary = action === "download" || action === "content" && Boolean(ctx.str("output"));
-    result = await api(ctx, "GET", endpoint(ctx, action), query(ctx, action), void 0, { ...options, ...binary ? { responseType: "bytes" } : {} });
+    result = await api(ctx, "GET", endpoint(ctx, action), query(ctx, action), void 0, { ...options2, ...binary ? { responseType: "bytes" } : {} });
     if (binary) {
       const output = path.resolve(ctx.str("output"));
       const bytes = Buffer.from(result.bytes);
@@ -161,7 +418,7 @@ async function executeSchemaImport(ctx, action, api = kbApi, upload = kbUpload)
       const { bytes } = await readMarkdown(ctx);
       input.content = bytes.toString("utf8");
     }
-    result = await api(ctx, action === "save" ? "PUT" : "POST", endpoint(ctx, action), {}, input, options);
+    result = await api(ctx, action === "save" ? "PUT" : "POST", endpoint(ctx, action), {}, input, options2);
   }
   return ctx.bool("wait") && result.task ? waitSchemaImport(ctx, result, api) : result;
 }
@@ -183,7 +440,7 @@ var schemaImportAbandon = command("abandon", "+schema-import-abandon", "Abandon
 var schemaImportCommands = [schemaDownload, schemaImport, schemaImportList, schemaImportStatus, schemaImportContent, schemaImportDiff, schemaImportSave, schemaImportValidate, schemaImportOptimize, schemaImportReject, schemaImportApply, schemaImportAbandon];
 
 // src/commands/te-kb/source-check-updates.ts
-var API_PATH2 = "/agent/api/external/knowledge-bases/sources/check-updates";
+var API_PATH3 = "/agent/api/external/knowledge-bases/sources/check-updates";
 function body3(ctx) {
   const scope = getExternalKnowledgeBaseTargetScope(ctx);
   return { name: ctx.str("name").trim(), sourceId: ctx.str("id").trim(), ...scope ? { scope } : {} };
@@ -206,10 +463,10 @@ var sourceCheckUpdates = {
     }
     getExternalKnowledgeBaseTargetScope(ctx);
   },
-  dryRun: (ctx) => ({ method: "POST", url: `${ctx.host().replace(/\/$/, "")}${API_PATH2}`, body: body3(ctx) }),
+  dryRun: (ctx) => ({ method: "POST", url: `${ctx.host().replace(/\/$/, "")}${API_PATH3}`, body: body3(ctx) }),
   execute: async (ctx) => {
     try {
-      return await kbApi(ctx, "POST", API_PATH2, {}, body3(ctx), { preserveErrorMetadata: true });
+      return await kbApi(ctx, "POST", API_PATH3, {}, body3(ctx), { preserveErrorMetadata: true });
     } catch (error) {
       const hint = "Read kb +list-sources to confirm the current source state before retrying.";
       if (error instanceof PermissionError) {
@@ -595,7 +852,7 @@ var sourceCancel = {
 import { promises as fs4 } from "fs";
 import * as path4 from "path";
 import TurndownService from "turndown";
-var API_PATH3 = "/agent/api/external/knowledge-bases/sources/upload";
+var API_PATH4 = "/agent/api/external/knowledge-bases/sources/upload";
 var SUPPORTED_EXTENSIONS = /* @__PURE__ */ new Set([
   ".zip",
   ".md",
@@ -819,7 +1076,7 @@ var add = {
     body4.contentType = "multipart/form-data";
     return {
       method: "POST",
-      url: `${ctx.host().replace(/\/$/, "")}${API_PATH3}`,
+      url: `${ctx.host().replace(/\/$/, "")}${API_PATH4}`,
       body: body4
     };
   },
@@ -828,7 +1085,7 @@ var add = {
     const scope = getExternalKnowledgeBaseTargetScope(ctx);
     const files = await collectFiles(ctx);
     const form = buildForm(name, scope, files);
-    const result = await kbUpload(ctx, API_PATH3, form);
+    const result = await kbUpload(ctx, API_PATH4, form);
     return {
       uploaded: files.map((f) => ({ filename: f.filename, origin: f.origin, source: f.source })),
       result
@@ -837,7 +1094,7 @@ var add = {
 };
 
 // src/commands/te-kb/compile.ts
-var API_PATH4 = "/agent/api/external/knowledge-bases/compile";
+var API_PATH5 = "/agent/api/external/knowledge-bases/compile";
 var VALID_MODES = /* @__PURE__ */ new Set(["incremental", "full"]);
 function getMode(ctx) {
   const mode = ctx.str("mode") || "incremental";
@@ -874,14 +1131,14 @@ var compile = {
   },
   dryRun: (ctx) => ({
     method: "POST",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH4}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH5}`,
     body: buildBody(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "POST", API_PATH4, {}, buildBody(ctx))
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH5, {}, buildBody(ctx))
 };
 
 // src/commands/te-kb/remove.ts
-var API_PATH5 = "/agent/api/external/knowledge-bases";
+var API_PATH6 = "/agent/api/external/knowledge-bases";
 function buildBody2(ctx) {
   const body4 = { name: ctx.str("name") };
   const scope = getExternalKnowledgeBaseTargetScope(ctx);
@@ -902,14 +1159,14 @@ var remove = {
   },
   dryRun: (ctx) => ({
     method: "DELETE",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH5}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH6}`,
     body: buildBody2(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "DELETE", API_PATH5, {}, buildBody2(ctx))
+  execute: async (ctx) => kbApi(ctx, "DELETE", API_PATH6, {}, buildBody2(ctx))
 };
 
 // src/commands/te-kb/create.ts
-var API_PATH6 = "/agent/api/external/knowledge-bases/create";
+var API_PATH7 = "/agent/api/external/knowledge-bases/create";
 var VALID_SCOPES = /* @__PURE__ */ new Set(["personal", "company"]);
 function getScope(ctx) {
   const scope = ctx.str("scope") || "company";
@@ -943,7 +1200,16 @@ function buildBody3(ctx) {
   };
   const description = ctx.str("description");
   if (description) body4.description = description;
-  const tags = normalizeTags(ctx.json("tags"));
+  const purpose = ctx.str("purpose");
+  if (purpose) {
+    if (purpose !== "project-semantic" || getScope(ctx) !== "company" || !/^[1-9]\d{0,15}$/.test(ctx.str("project-id")))
+      throw new Error("--purpose project-semantic requires company scope and a valid --project-id.");
+    body4.purpose = purpose;
+  }
+  const supplied = normalizeTags(ctx.json("tags"));
+  const tags = purpose ? [.../* @__PURE__ */ new Set(["\u9879\u76EE\u8BED\u4E49", ...supplied ?? []])] : supplied;
+  if (tags && (tags.length > 2 || tags.some((tag) => tag.length > 15)))
+    throw new Error("Tags must contain at most 2 entries, each at most 15 characters.");
   if (tags && tags.length > 0) body4.tags = tags;
   const projectId = ctx.str("project-id");
   if (projectId) body4.projectId = projectId;
@@ -960,24 +1226,24 @@ var create = {
     { 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: "purpose", type: "string", required: false, desc: "Optional project-semantic purpose: presets the fixed semantic tag and checks the existing project target before creation" },
     { 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"));
+    buildBody3(ctx);
   },
   dryRun: (ctx) => ({
     method: "POST",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH6}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH7}`,
     body: buildBody3(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "POST", API_PATH6, {}, buildBody3(ctx))
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH7, {}, buildBody3(ctx))
 };
 
 // src/commands/te-kb/rm-source.ts
-var API_PATH7 = "/agent/api/external/knowledge-bases/sources";
+var API_PATH8 = "/agent/api/external/knowledge-bases/sources";
 function sourceSelector(ctx) {
   const id = ctx.str("id").trim();
   if (id) return { id };
@@ -991,13 +1257,18 @@ function buildBody4(ctx) {
   };
   const scope = getExternalKnowledgeBaseTargetScope(ctx);
   if (scope) body4.scope = scope;
-  return { ...body4, ...sourceSelector(ctx) };
+  const cancelCandidate = ctx.bool("cancel-candidate");
+  const expectedCandidateId = ctx.str("expected-candidate-id");
+  if (cancelCandidate !== Boolean(expectedCandidateId)) throw new CliValidationError("--cancel-candidate and --expected-candidate-id must be supplied together.");
+  return { ...body4, ...sourceSelector(ctx), ...cancelCandidate ? { cancelCandidate, expectedCandidateId } : {} };
 }
 var rmSource = {
   service: "kb",
   command: "+rm-source",
   description: "Delete one source from a knowledge base by ID or exact display name.",
   flags: [
+    { name: "cancel-candidate", type: "boolean", desc: "Atomically cancel the pending candidate approval before deleting its source" },
+    { name: "expected-candidate-id", type: "string", desc: "Exact active candidate ID; required with --cancel-candidate" },
     { 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)" },
@@ -1006,14 +1277,14 @@ var rmSource = {
   risk: "high-risk-write",
   validate: (ctx) => {
     getExternalKnowledgeBaseTargetScope(ctx);
-    sourceSelector(ctx);
+    buildBody4(ctx);
   },
   dryRun: (ctx) => ({
     method: "DELETE",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH7}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH8}`,
     body: buildBody4(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "DELETE", API_PATH7, {}, buildBody4(ctx), {
+  execute: async (ctx) => kbApi(ctx, "DELETE", API_PATH8, {}, buildBody4(ctx), {
     preserveErrorMetadata: true
   })
 };
@@ -1021,7 +1292,7 @@ var rmSource = {
 // src/commands/te-kb/schema.ts
 import fs5 from "fs";
 import path5 from "path";
-var API_PATH8 = "/agent/api/external/knowledge-bases/schema";
+var API_PATH9 = "/agent/api/external/knowledge-bases/schema";
 var MAX_CUSTOM_INSTRUCTIONS_CHARS = 1e4;
 function getCustomInstructions(ctx) {
   const inline = ctx.str("custom-instructions");
@@ -1052,7 +1323,7 @@ function buildBody5(ctx) {
   return body4;
 }
 async function executeSchema(ctx, api = kbApi) {
-  return api(ctx, "POST", API_PATH8, {}, buildBody5(ctx), {
+  return api(ctx, "POST", API_PATH9, {}, buildBody5(ctx), {
     preserveBusinessErrorCode: true
   });
 }
@@ -1087,14 +1358,14 @@ var schema = {
   },
   dryRun: (ctx) => ({
     method: "POST",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH8}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH9}`,
     body: buildBody5(ctx)
   }),
   execute: executeSchema
 };
 
 // src/commands/te-kb/status.ts
-var API_PATH9 = "/agent/api/external/knowledge-bases/status";
+var API_PATH10 = "/agent/api/external/knowledge-bases/status";
 function buildBody6(ctx) {
   const body4 = {
     name: ctx.str("name")
@@ -1117,14 +1388,14 @@ var status = {
   },
   dryRun: (ctx) => ({
     method: "POST",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH9}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH10}`,
     body: buildBody6(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "POST", API_PATH9, {}, buildBody6(ctx))
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH10, {}, buildBody6(ctx))
 };
 
 // src/commands/te-kb/kb-index.ts
-var API_PATH10 = "/agent/api/external/knowledge-bases/index";
+var API_PATH11 = "/agent/api/external/knowledge-bases/index";
 function buildBody7(ctx) {
   const body4 = {};
   const sources = ctx.json("sources");
@@ -1138,6 +1409,7 @@ var kbIndex = {
   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: "read-context", type: "string", required: false, desc: "Pin reads to an existing read context" },
     {
       name: "sources",
       type: "json",
@@ -1149,18 +1421,18 @@ var kbIndex = {
   risk: "read",
   dryRun: (ctx) => ({
     method: "POST",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH10}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH11}`,
     body: buildBody7(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "POST", API_PATH10, {}, buildBody7(ctx))
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH11, {}, buildBody7(ctx))
 };
 
 // src/commands/te-kb/kb-list.ts
-var API_PATH11 = "/agent/api/external/knowledge-bases/list";
+var API_PATH12 = "/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;
+  return ctx.str("build-status") || (ctx.str("view") === "published" || ctx.str("read-context") || kbExecutionContextRequired() ? void 0 : DEFAULT_BUILD_STATUS);
 }
 function validateBuildStatus(ctx) {
   const value = ctx.str("build-status");
@@ -1174,7 +1446,8 @@ function validateBuildStatus(ctx) {
 }
 function buildBody8(ctx) {
   const body4 = {
-    buildStatus: getBuildStatus(ctx)
+    ...getBuildStatus(ctx) ? { buildStatus: getBuildStatus(ctx) } : {},
+    ...ctx.str("view") ? { view: ctx.str("view") } : {}
   };
   const locale = ctx.str("locale");
   if (locale) body4.locale = locale;
@@ -1185,11 +1458,12 @@ var kbList = {
   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: "view", type: "string", required: false, desc: "Use published for formal views without an implicit build-status filter" },
+    { name: "read-context", type: "string", required: false, desc: "Pin reads to an existing read context" },
     {
       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" }
@@ -1197,23 +1471,39 @@ var kbList = {
   risk: "read",
   validate: (ctx) => {
     validateBuildStatus(ctx);
+    if (ctx.str("view") && ctx.str("view") !== "published") throw new Error("Invalid --view: expected published");
   },
   dryRun: (ctx) => ({
     method: "POST",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH11}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH12}`,
     body: buildBody8(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "POST", API_PATH11, {}, buildBody8(ctx))
+  execute: async (ctx) => {
+    if (ctx.str("view") !== "published" || ctx.str("read-context") || kbExecutionContextRequired())
+      return kbApi(ctx, "POST", API_PATH12, {}, buildBody8(ctx));
+    const endpoint3 = "/agent/api/external/knowledge-bases/read-contexts";
+    const options3 = { preserveErrorMetadata: true, retryUnauthorized: false };
+    const created = await kbApi(ctx, "POST", endpoint3, {}, ctx.str("locale") ? { locale: ctx.str("locale") } : {}, options3);
+    if (typeof created?.readContextId !== "string" || !/^[A-Za-z0-9_-]{1,191}$/.test(created.readContextId))
+      throw new Error("KB_READ_CONTEXT_CAPABILITY_UNAVAILABLE");
+    const pinned = Object.create(ctx);
+    pinned.str = (name) => name === "read-context" ? created.readContextId : ctx.str(name);
+    try {
+      return await kbApi(pinned, "POST", API_PATH12, {}, buildBody8(ctx), options3);
+    } finally {
+      await kbApi(ctx, "DELETE", `${endpoint3}/${encodeURIComponent(created.readContextId)}`, {}, {}, options3);
+    }
+  }
 };
 
 // src/commands/te-kb/list-sources.ts
-var API_PATH12 = "/agent/api/external/knowledge-bases/sources";
+var API_PATH13 = "/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_PATH12}`);
+  const url2 = new URL(`${ctx.host().replace(/\/$/, "")}${API_PATH13}`);
   url2.searchParams.set("name", knowledgeBaseName(ctx));
   const scope = getExternalKnowledgeBaseTargetScope(ctx);
   if (scope) url2.searchParams.set("scope", scope);
@@ -1266,7 +1556,7 @@ var listSources = {
     const scope = getExternalKnowledgeBaseTargetScope(ctx);
     if (scope) params.scope = scope;
     if (ctx.str("content-type")) params.contentType = ctx.str("content-type");
-    return kbApi(ctx, "GET", API_PATH12, params, void 0, {
+    return kbApi(ctx, "GET", API_PATH13, params, void 0, {
       preserveErrorMetadata: true,
       retryUnauthorized: false
     });
@@ -1274,7 +1564,7 @@ var listSources = {
 };
 
 // src/commands/te-kb/usage-list.ts
-var API_PATH13 = "/agent/api/external/knowledge-bases/usage-logs";
+var API_PATH14 = "/agent/api/external/knowledge-bases/usage-logs";
 function query3(ctx) {
   const scope = getExternalKnowledgeBaseTargetScope(ctx);
   return {
@@ -1307,10 +1597,10 @@ var usageList = {
       }
     }
   },
-  dryRun: (ctx) => ({ method: "GET", url: `${ctx.host().replace(/\/$/, "")}${API_PATH13}`, params: query3(ctx) }),
+  dryRun: (ctx) => ({ method: "GET", url: `${ctx.host().replace(/\/$/, "")}${API_PATH14}`, params: query3(ctx) }),
   execute: async (ctx) => {
     try {
-      return await kbApi(ctx, "GET", API_PATH13, query3(ctx), void 0, { preserveErrorMetadata: true });
+      return await kbApi(ctx, "GET", API_PATH14, query3(ctx), void 0, { preserveErrorMetadata: true });
     } catch (error) {
       if (error instanceof PermissionError) {
         error.message = "Permission denied when reading knowledge base usage logs.";
@@ -1329,7 +1619,7 @@ var usageList = {
 };
 
 // src/commands/te-kb/kb-grep.ts
-var API_PATH14 = "/agent/api/external/knowledge-bases/grep";
+var API_PATH15 = "/agent/api/external/knowledge-bases/grep";
 function buildBody9(ctx) {
   const body4 = {
     query: ctx.str("query"),
@@ -1347,6 +1637,7 @@ var kbGrep = {
   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: "read-context", type: "string", required: false, desc: "Pin reads to an existing read context" },
     {
       name: "query",
       type: "string",
@@ -1372,14 +1663,14 @@ var kbGrep = {
   risk: "read",
   dryRun: (ctx) => ({
     method: "POST",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH14}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH15}`,
     body: buildBody9(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "POST", API_PATH14, {}, buildBody9(ctx))
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH15, {}, buildBody9(ctx))
 };
 
 // src/commands/te-kb/kb-read.ts
-var API_PATH15 = "/agent/api/external/knowledge-bases/read";
+var API_PATH16 = "/agent/api/external/knowledge-bases/read";
 var VALID_EXPAND_MODES = /* @__PURE__ */ new Set(["block", "none"]);
 var MAX_READ_LIMIT = 2e3;
 function readExpand(ctx) {
@@ -1423,6 +1714,7 @@ var kbRead = {
   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: "read-context", type: "string", required: false, desc: "Pin reads to an existing read context" },
     {
       name: "source",
       type: "json",
@@ -1457,10 +1749,10 @@ var kbRead = {
   },
   dryRun: (ctx) => ({
     method: "POST",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH15}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH16}`,
     body: buildBody10(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "POST", API_PATH15, {}, buildBody10(ctx))
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH16, {}, buildBody10(ctx))
 };
 
 // src/commands/te-kb/ask-shared.ts
@@ -1479,12 +1771,12 @@ function isTransientAskPollError(error) {
     error.message
   );
 }
-async function pollUntilSettled(getStatus, executionId, options2 = {}) {
-  const intervalMs = options2.intervalMs ?? ASK_POLL_INTERVAL_MS;
-  const timeoutMs = options2.timeoutMs ?? ASK_POLL_TIMEOUT_MS;
-  const maxTransientFailures = options2.maxTransientFailures ?? ASK_MAX_TRANSIENT_POLL_FAILURES;
-  const now = options2.now ?? Date.now;
-  const sleep = options2.sleep ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms)));
+async function pollUntilSettled(getStatus, executionId, options3 = {}) {
+  const intervalMs = options3.intervalMs ?? ASK_POLL_INTERVAL_MS;
+  const timeoutMs = options3.timeoutMs ?? ASK_POLL_TIMEOUT_MS;
+  const maxTransientFailures = options3.maxTransientFailures ?? ASK_MAX_TRANSIENT_POLL_FAILURES;
+  const now = options3.now ?? Date.now;
+  const sleep = options3.sleep ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms)));
   const startTime = now();
   let transientFailures = 0;
   while (true) {
@@ -1636,8 +1928,15 @@ function executionIdFrom(ctx) {
 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.",
+  description: "Query an Ask execution. With --source-index, revisit that saved citation at its original version using current permissions; never selects the latest version. Does not poll.",
   flags: [
+    {
+      name: "source-index",
+      type: "number",
+      required: false,
+      min: 0,
+      desc: "Zero-based sourceIndex from a completed Ask source reference. Unversioned historical sources cannot be revisited."
+    },
     {
       name: "execution-id",
       type: "string",
@@ -1649,6 +1948,10 @@ var askStatus = {
   ],
   risk: "read",
   validate: (ctx) => {
+    const index = ctx.optionalNum("source-index");
+    if (index !== void 0 && (!Number.isSafeInteger(index) || index < 0 || index > 999999999)) {
+      throw new CliValidationError("--source-index must be a non-negative integer below 1000000000.");
+    }
     const executionId = executionIdFrom(ctx);
     if (!executionId) {
       throw new Error("Invalid --execution-id: must be non-empty.");
@@ -1661,16 +1964,26 @@ var askStatus = {
   },
   dryRun: (ctx) => ({
     method: "GET",
-    url: `${ctx.host().replace(/\/$/, "")}${ASK_API_PATH}?executionId=${encodeURIComponent(executionIdFrom(ctx))}`
+    url: `${ctx.host().replace(/\/$/, "")}${ASK_API_PATH}?executionId=${encodeURIComponent(executionIdFrom(ctx))}${ctx.optionalNum("source-index") !== void 0 ? `&sourceIndex=${ctx.optionalNum("source-index")}` : ""}`
   }),
   execute: async (ctx) => {
     const executionId = executionIdFrom(ctx);
-    return await kbApi(ctx, "GET", ASK_API_PATH, { executionId });
+    const sourceIndex = ctx.optionalNum("source-index");
+    if (sourceIndex !== void 0 && kbExecutionContextRequired()) {
+      throw new CliValidationError(
+        "Historical references cannot be read inside a pinned KB execution. Use this command outside that execution with your current user credentials.",
+        { code: "KB_READ_CONTEXT_REFERENCE_FORBIDDEN" }
+      );
+    }
+    return kbApi(ctx, "GET", ASK_API_PATH, {
+      executionId,
+      ...sourceIndex !== void 0 ? { sourceIndex } : {}
+    });
   }
 };
 
 // src/commands/te-kb/url.ts
-var API_PATH16 = "/agent/api/external/knowledge-bases/sources/url";
+var API_PATH17 = "/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`);
@@ -1707,16 +2020,16 @@ var url = {
   },
   dryRun: (ctx) => ({
     method: "POST",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH16}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH17}`,
     body: buildBody12(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "POST", API_PATH16, {}, buildBody12(ctx))
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH17, {}, buildBody12(ctx))
 };
 
 // src/commands/te-kb/import.ts
 import { promises as fs6 } from "fs";
 import path6 from "path";
-var API_PATH17 = "/agent/api/external/knowledge-bases/import";
+var API_PATH18 = "/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) {
@@ -1846,7 +2159,7 @@ var importSnapshot = {
     try {
       return await kbUpload(
         ctx,
-        API_PATH17,
+        API_PATH18,
         form,
         { scope: getScope2(ctx) },
         { preserveErrorMetadata: true, retryUnauthorized: true }
@@ -1875,7 +2188,7 @@ var importSnapshot = {
 };
 
 // src/commands/te-kb/import-status.ts
-var API_PATH18 = "/agent/api/external/knowledge-bases/import";
+var API_PATH19 = "/agent/api/external/knowledge-bases/import";
 var MAX_REQUEST_ID_LENGTH = 191;
 function requestIdFrom(ctx) {
   return ctx.str("request-id").trim();
@@ -1906,7 +2219,7 @@ var importStatus = {
   },
   dryRun: (ctx) => ({
     method: "GET",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH18}?requestId=${encodeURIComponent(requestIdFrom(ctx))}`
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH19}?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.";
@@ -1914,7 +2227,7 @@ var importStatus = {
       return await kbApi(
         ctx,
         "GET",
-        API_PATH18,
+        API_PATH19,
         { requestId: requestIdFrom(ctx) },
         void 0,
         { preserveErrorMetadata: true, retryUnauthorized: true }
@@ -2311,6 +2624,8 @@ var rollbackStatus = {
 
 // src/commands/te-kb/index.ts
 var commands = [
+  projectTargetGet,
+  ...publicationCommands,
   usageList,
   ...schemaImportCommands,
   sourceCheckUpdates,
@@ -2358,6 +2673,10 @@ export {
   add,
   ask,
   askStatus,
+  candidateChanges,
+  candidateDiscard,
+  candidateGet,
+  candidateRead,
   compile,
   create,
   te_kb_default as default,
@@ -2369,6 +2688,11 @@ export {
   kbList,
   kbRead,
   listSources,
+  projectTargetGet,
+  publicationCommands,
+  publicationGet,
+  readContextCreate,
+  readContextRelease,
   remove,
   rmSource,
   rollback,