@thinkingai/ae-cli 6.1.14 → 6.1.17

package/skills/ae-kb/references/query-workflow.md

@@ -0,0 +1,112 @@
+# ae-kb deterministic query workflow
+
+How to answer a knowledge question with the deterministic retrieval primitives
+(`+list` / `+index` / `+grep` / `+read`) instead of `+ask`. Follow this order;
+it is designed to reach the right section in a few calls and to avoid crawling a
+page line by line.
+
+Use `+ask` when the question requires synthesizing across multiple pages or
+multi-hop reasoning; simple factual lookups are served by the steps below.
+Everything below is server-side LLM-free.
+
+## The loop
+
+This picks up **after** `ae-kb-discovery` has listed accessible knowledge bases
+and ranked candidates. Start here with a chosen candidate; scope every `+index`
+/ `+grep` / `+read` call to it with `--sources` / `--source`. If the candidate
+turns out not to cover the question, go back to `ae-kb-discovery` for the next
+candidate rather than searching everything blindly.
+
+1. **Index the candidate.** Call `+index --sources` with the discovery pick.
+   Use `index.md` for navigation, a fit check, and **query wording** — the real
+   terms in the index (product names, API identifiers, section titles) become
+   your `+grep` keywords.
+
+   **Done when:** you have the candidate's `index.md`, and a list of `wiki/...`
+   links you can **copy** (0 items still counts as done).
+
+2. **Grep copied paths.** Copy 1–3 `wiki/...` entries from the index (a page
+   such as `wiki/sandbox.md`, or a subdirectory such as `wiki/guides`). Call
+   `+grep` with the candidate `--sources` and the copied list as `--paths`. Search
+   with the index terms. If the first grep misses, rewrite the query **once**
+   using different index terms — still with this same `--paths` — then stop
+   rewriting.
+
+   **Done when:** you have hits, or you have rewritten once, or step 1 copied
+   0 paths. Copied 0 paths → skip grep and `+read --outline` the likeliest
+   title page, or go back to discovery for the next candidate.
+
+   A grep hit gives both a hit anchor and its enclosing section range:
+
+   - `line` is the exact matched line. Use it as the anchor when the evidence
+     is local.
+   - `sectionStartLine` / `sectionEndLine` are the enclosing heading-section
+     boundaries. Use them when the answer needs the whole section context, or
+     as the maximum boundary when choosing a smaller window.
+   - `+read --offset` / `--limit` are the actual read window. Choose the
+     smallest reliable window that preserves the needed evidence; do not
+     shell-truncate with `| head`.
+
+3. **Choose the section locator.** Pick one locator for the current target
+   page:
+
+   - **Same-page grep hit:** choose a read window from the hit. For narrow
+     fact/table/code evidence, read a bounded window anchored at `line`; stay
+     within `sectionStartLine`–`sectionEndLine`. For section-level meaning,
+     field definitions, caveats, or rows that depend on the heading context,
+     read the section range with
+     `--offset sectionStartLine` and
+     `--limit sectionEndLine - sectionStartLine + 1`. If the first window is
+     too small, widen once up to the section range. Do not crawl by shifting
+     offsets line by line.
+   - **Linked or related page:** if you follow a catalog/detail/related link to
+     a different page, the old grep range no longer applies. If you have
+     concrete terms for that new page, run `+grep --paths '["<new-page>"]'`
+     scoped to that page and use the new hit range.
+   - **No reliable range:** if the new page has no concrete grep terms, its
+     grep misses, or headings are needed to choose the right section, call
+     `+read --outline` for that page. It returns only the heading tree
+     (`{level, heading, line}`), independent of any offset/limit window, with
+     empty content.
+
+   A bare `+read` without `--offset` / `--limit` is only acceptable after the
+   response proves the whole page was returned (`startLine: 1`,
+   `endLine: totalLines`, and `truncated: false`).
+
+   **Done when:** you have a reliable range from the same-page grep hit, a new
+   page grep hit, an outline-derived heading range, or a complete untruncated
+   page response.
+
+4. **Read the selected window.** Read the selected window in one call. Windows
+   come from the hit anchor, the grep hit's section boundaries, or two adjacent
+   outline headings (`heading.line` of the target section to `heading.line - 1`
+   of the next). If a window turns out too small, widen to the section boundary
+   in one more call.
+
+   **Done when:** the needed evidence is in context without shell truncation,
+   or the page response is complete and untruncated.
+
+5. **Assess coverage, then answer or iterate.** Map the user's question into
+   subquestions and check each one against the sections you actually read. If a
+   subquestion is covered, answer with citations (knowledge base + page path +
+   section). If a gap remains, go back to step 2 with another set of `--paths`
+   **copied** from the index, or return to discovery for the next candidate.
+   If the evidence is missing after the allowed search, say which subquestion is
+   not covered instead of filling it from memory.
+
+   **Done when:** every answered subquestion is supported by read sections, or
+   the remaining gaps are explicitly reported as missing evidence.
+
+## Anti-pattern: same-page offset crawling
+
+The failure this workflow prevents: grep returns a line number, you `+read` a
+tiny window around it, it is cut mid-evidence, so you nudge the window one line
+at a time. That wastes calls and never shows page structure. Instead: use the
+hit anchor, widen once up to the section boundary, or open `--outline` and read
+the selected heading range.
+
+## Related
+
+- Command flags and JSON shapes: see the `+grep` / `+read` sections in
+  [`../SKILL.md`](../SKILL.md).
+- Use `+ask` for multi-page synthesis or multi-hop questions. Default `+ask` submits then polls until the answer is ready; `--no-wait` and `+ask-status` are for batch submit/retrieve. See the `+ask` section in [`../SKILL.md`](../SKILL.md).

package/skills/ae-kb-discovery/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: ae-kb-discovery
+description: >
+  Discover which AE/TE/ThinkingEngine knowledge bases accessible to the current user are worth searching, and decide whether to search at all, through read-only operations. Use when the user explicitly asks to search knowledge bases, internal documentation, or company materials. Also use when a task requires internal facts or business context, including product design and rules, events, campaign or operations calendars, release and iteration records, workflows, policies, and terminology; use it as well when this context is needed to explain data analysis results, anomalies, or trends and form evidence-backed conclusions. Do not use if the user explicitly asks not to access knowledge bases. This skill covers discovery and candidate selection; run the actual `+index` / `+grep` / `+read` / `+ask` retrieval with the `ae-kb` skill.
+---
+
+# Knowledge Base Discovery
+
+Treat knowledge bases as an optional source of internal facts and business context. Keep the user's original goal unchanged; knowledge base retrieval is a supporting workflow, not the task itself.
+
+This skill decides **whether** to use a knowledge base and **which** knowledge base is worth searching. The retrieval procedure itself — inspecting the index, grep, reading sections, and optional LLM synthesis — lives in the `ae-kb` skill (`references/query-workflow.md`). Discover here, then hand off to `ae-kb` to execute.
+
+## Decide Whether to Use This Skill
+
+Use this skill when:
+
+- The user explicitly asks to search a knowledge base, internal documentation, or company materials.
+- The task requires organization-specific facts or context, such as product design and rules, events, campaign or operations calendars, release and iteration records, workflows, policies, or terminology.
+- Internal context is needed to explain data analysis results, anomalies, or trends and form evidence-backed conclusions.
+- The knowledge base context currently available does not cover the question, and discovering other accessible sources has clear value.
+
+Do not use this skill when:
+
+- The user explicitly asks not to use knowledge bases.
+- The task only requires querying real-time state or performing an operation and does not need document context.
+- General knowledge is sufficient for a reliable answer and internal evidence would not materially improve it.
+
+## Discovery Workflow
+
+### 1. Get the List of Accessible Knowledge Bases
+
+First, get the lightweight list of knowledge bases accessible to the current user:
+
+```bash
+ae-cli kb +list
+```
+
+Use the exact `scope` and knowledge base name returned by the command, together with available metadata such as description, tags, language, and `bindings`. A binding identifies an associated context through `targetType`, `targetId`, and optional `targetName`. Do not guess a name, scope, or binding. Treat metadata returned by `+list` only as input for candidate selection, not as evidence from knowledge base content.
+
+If `+list` is unavailable or fails, do not guess which knowledge bases exist. If the user explicitly requested a knowledge base search, explain that discovery cannot currently be completed. Otherwise, return to the original task and reassess the capabilities currently available.
+
+### 2. Rank Candidate Knowledge Bases
+
+Rank candidates in this order:
+
+1. Prefer a knowledge base explicitly named by the user. Use the exact name and scope returned by `+list`, regardless of whether it has a matching binding.
+2. Prefer candidates whose bindings exactly match the current session context. Match `targetType: project` against the current analysis project ID, `targetType: space` against the current community space ID, and `targetType: dwSpace` against the current digital workspace code.
+3. For the remaining candidates, compare the user's request with the knowledge base name, description, and tags. Use language only as a preference between candidates with similar relevance; language alone does not establish relevance.
+
+Compare `targetId` with the corresponding current ID or code first. Use `targetName` only as a secondary signal when an ID or code is unavailable; do not replace a conflicting ID match with a name match. A candidate with no bindings or no current-context match remains eligible for semantic ranking. A binding to another project or space lowers implicit priority but does not exclude the candidate, and an explicit user choice still takes precedence.
+
+Select one preferred knowledge base by default. When several candidates are highly relevant, retain no more than three and try them one at a time in priority order. Do not read the indexes of all candidates in advance. A binding, name, description, tag, or language match only indicates that a knowledge base is worth searching; it does not prove a content match, grant access, or count as knowledge base evidence.
+
+### 3. Hand Off to Retrieval
+
+Once a preferred knowledge base is selected, hand off to the `ae-kb` skill and follow its `references/query-workflow.md` for the entire retrieval procedure — including when `+ask` is appropriate.
+
+## Assess Coverage
+
+- Full coverage: The page content read supports the key conclusions required for the information request or analysis.
+- Partial coverage: The page content read provides only background, definitions, or partially relevant facts and cannot independently support the required conclusions.
+- No coverage: No suitable candidate knowledge base exists, or `+grep` and `+read` return no content that can support the conclusions.
+
+A candidate returned by `+list`, navigation returned by `+index`, a successful command, a tool call, or a metadata match does not count as a knowledge base hit. Only relevant page content that has actually been read can serve as knowledge base evidence.
+
+## Use Knowledge Base Evidence in Analysis
+
+When using internal context to explain data analysis results, anomalies, or trends:
+
+1. First state what the analysis itself demonstrates, including the metric change, time range, affected entity, and magnitude.
+2. Search using the affected entity, metric, time range, campaign or event name, product area, and release or version name.
+3. Verify that the retrieved evidence:
+   - Applies to the same entity, product area, or business scope.
+   - Overlaps with the time range covered by the analysis.
+   - Records an event, rule, release, or change that actually took effect.
+   - Uses a version and effective date that remained valid during the analysis period.
+4. Distinguish planned activities from completed events. A calendar or roadmap does not prove that an activity or release occurred unless the retrieved content confirms execution.
+5. Combine analytical facts with retrieved internal evidence and state directly what the evidence supports. Do not list possible causes that lack evidence.
+6. Use causal language such as "caused" or "led to" only when the available evidence establishes causality. Otherwise, say that the evidence supports a factor as a key explanation or that the factor is consistent with the observed change.
+7. If the evidence is insufficient, state clearly that the cause cannot be determined from the available evidence. Do not fill evidence gaps with speculation.
+8. When appropriate, organize the final answer in this order:
+   - Conclusion.
+   - Analytical evidence.
+   - Knowledge base evidence and relevant page paths.
+   - Necessary limitations of the evidence.
+
+## Handle Partial or No Coverage
+
+When knowledge base evidence provides only partial coverage, is entirely absent, or retrieval fails:
+
+1. Stop repeating searches against the same candidate knowledge base.
+2. If ranked candidates remain, switch to the next candidate. Search no more than three knowledge bases in one task.
+3. When all candidates provide no coverage, return to the user's original request instead of remaining in the knowledge base retrieval subtask.
+4. Reassess the capabilities currently available and choose the next path that best serves the original task. Do not hard-code a fixed fallback.
+5. Retain verified background evidence when useful, but never attribute conclusions drawn from other sources to a knowledge base.
+6. Do not report an unsuccessful knowledge base search unless the retrieval failure itself affects the user's decision.
+
+Knowledge base information must not replace required business operations. If the original task also requires real-time data or an action, complete that part through the appropriate available capability.
+
+## Safety Boundaries
+
+- Limit knowledge base access to the read-only retrieval primitives (`+list`, `+index`, `+grep`, `+read`, and `+ask` when the question requires multi-page synthesis or multi-hop reasoning). Do not create, upload, compile, or delete knowledge bases.
+- Respect existing scope, tenant, and membership permissions. Do not attempt to bypass an inaccessible knowledge base.
+- Do not expose internal root paths, access tokens, or raw permission metadata.
+- For protected knowledge bases, provide only summaries and synthesized conclusions allowed by the current permissions. Do not export complete source text or extensive verbatim excerpts.

package/skills/ae-metadata/SKILL.md

@@ -83,4 +83,3 @@ ae-cli analysis input-file purpose list --project-id 1
 ## Related Skills
 
 - **`ae-analysis`**: `analysis-meta event get` / `analysis-meta property get` for detail, and `analysis-meta event list` / `analysis-meta property list` to discover names.
-- **Dev workflow**: `.cursor/skills/te-cli-capability-gateway` — inspect gateway schema when adding new metadata capabilities.

package/dist/chunk-3FY3RJ26.js

@@ -1,293 +0,0 @@
-import {
-  logger
-} from "./chunk-JHENBQ5B.js";
-
-// src/core/json-utils.ts
-import fs from "fs";
-import { createRequire } from "module";
-var require2 = createRequire(import.meta.url);
-var JSONbig = require2("json-bigint");
-var jsonParser = JSONbig({ storeAsString: true });
-var INTEGER_TOKEN = /^-?(?:0|[1-9]\d*)$/;
-function normalizeParsedNumbers(lossless, native) {
-  if (typeof lossless === "string" && typeof native === "number") {
-    if (INTEGER_TOKEN.test(lossless) && !Number.isSafeInteger(native)) {
-      return lossless;
-    }
-    return native;
-  }
-  if (Array.isArray(lossless) && Array.isArray(native)) {
-    for (let index = 0; index < lossless.length; index++) {
-      lossless[index] = normalizeParsedNumbers(lossless[index], native[index]);
-    }
-    return lossless;
-  }
-  if (lossless !== null && native !== null && typeof lossless === "object" && typeof native === "object") {
-    for (const key of Object.keys(lossless)) {
-      lossless[key] = normalizeParsedNumbers(lossless[key], native[key]);
-    }
-  }
-  return lossless;
-}
-function safeJsonParse(text) {
-  const lossless = jsonParser.parse(text);
-  return normalizeParsedNumbers(lossless, JSON.parse(text));
-}
-function safeReadJsonFile(filePath) {
-  const content = fs.readFileSync(filePath, "utf-8");
-  return safeJsonParse(content);
-}
-
-// src/core/url-utils.ts
-function normalizeUrl(url) {
-  if (!url) return url;
-  if (!url.startsWith("http://") && !url.startsWith("https://")) {
-    url = `https://${url}`;
-  }
-  return url.replace(/\/$/, "");
-}
-
-// src/core/config.ts
-import fs3 from "fs";
-import path from "path";
-
-// src/core/sandbox-runtime.ts
-import { homedir } from "os";
-import { join } from "path";
-import fs2 from "fs";
-var LINUX_SANDBOX_RUNTIME_ROOT = "/home/ta/te_agent_ta";
-function getDefaultSandboxRuntimeRoot() {
-  if (process.platform === "linux") {
-    return LINUX_SANDBOX_RUNTIME_ROOT;
-  }
-  return homedir();
-}
-function getSandboxRuntimeRoot() {
-  return process.env.SANDBOX_RUNTIME_ROOT || getDefaultSandboxRuntimeRoot();
-}
-function getSandboxAeConfigDir() {
-  return join(getSandboxRuntimeRoot(), ".ae-config");
-}
-function getSandboxCliTokenFilePath() {
-  return join(getSandboxAeConfigDir(), "cli-token.json");
-}
-function isAeSandboxRuntime() {
-  if (process.env.SANDBOX_RUNTIME_ROOT) {
-    return true;
-  }
-  try {
-    if (fs2.existsSync(getSandboxCliTokenFilePath())) {
-      return true;
-    }
-  } catch {
-  }
-  return false;
-}
-
-// src/core/config.ts
-var CONFIG_DIR = path.join(process.env.HOME || "", ".ae-cli");
-var CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
-function sandboxCliTokenCandidatePaths() {
-  const paths = [getSandboxCliTokenFilePath()];
-  const homeFallback = path.join(process.env.HOME || "", ".ae-config", "cli-token.json");
-  if (!paths.includes(homeFallback)) {
-    paths.push(homeFallback);
-  }
-  return paths;
-}
-function readSandboxCliTokenEntry() {
-  for (const file of sandboxCliTokenCandidatePaths()) {
-    if (!fs3.existsSync(file)) continue;
-    try {
-      const data = safeReadJsonFile(file);
-      if (data && typeof data === "object" && !Array.isArray(data)) {
-        const url = data.url;
-        const token = data.token ?? data["cli-token"];
-        if (url && token) {
-          return { url, token };
-        }
-      }
-    } catch {
-    }
-  }
-  return null;
-}
-function forceMigrateFromFallback() {
-  const entry = readSandboxCliTokenEntry();
-  if (!entry) return null;
-  return { [entry.url]: entry.token };
-}
-function getFallbackCliToken(hostUrl) {
-  const store = forceMigrateFromFallback();
-  if (!store) return null;
-  if (hostUrl && store[hostUrl]) return store[hostUrl];
-  const entries = Object.values(store);
-  if (entries.length === 1) return entries[0];
-  return null;
-}
-function ensureDir() {
-  if (!fs3.existsSync(CONFIG_DIR)) fs3.mkdirSync(CONFIG_DIR, { recursive: true });
-}
-function dedupeNormalizedHosts(config) {
-  const hosts = {};
-  for (const [url, entry] of Object.entries(config.hosts)) {
-    const key = normalizeUrl(url);
-    if (!hosts[key]) {
-      hosts[key] = entry;
-    }
-  }
-  return {
-    activeHost: config.activeHost ? normalizeUrl(config.activeHost) : "",
-    hosts
-  };
-}
-function configNeedsNormalization(config) {
-  if (config.activeHost && normalizeUrl(config.activeHost) !== config.activeHost) return true;
-  const keys = Object.keys(config.hosts);
-  if (keys.some((url) => normalizeUrl(url) !== url)) return true;
-  return new Set(keys.map(normalizeUrl)).size !== keys.length;
-}
-function loadConfig() {
-  try {
-    if (fs3.existsSync(CONFIG_FILE)) {
-      const raw = safeReadJsonFile(CONFIG_FILE);
-      if (raw.defaultHost && !raw.activeHost) {
-        const migrated = dedupeNormalizedHosts(migrateConfig(raw));
-        saveConfig(migrated);
-        return migrated;
-      }
-      const rawConfig = raw;
-      if (configNeedsNormalization(rawConfig)) {
-        const config = dedupeNormalizedHosts(rawConfig);
-        saveConfig(config);
-        return config;
-      }
-      return rawConfig;
-    }
-  } catch (err) {
-    logger.error(`Error loading config: ${err.message}`);
-    console.error(`Error loading config: ${err.message}`);
-  }
-  return { activeHost: "", hosts: {} };
-}
-function migrateConfig(old) {
-  const hosts = {};
-  const oldHost = old.defaultHost;
-  if (old.hosts) {
-    for (const [key, val] of Object.entries(old.hosts)) {
-      const url = normalizeUrl(key.startsWith("http") ? key : `https://${key}`);
-      hosts[url] = val;
-    }
-  }
-  const activeHost = normalizeUrl(oldHost.startsWith("http") ? oldHost : `https://${oldHost}`);
-  if (!hosts[activeHost]) {
-    hosts[activeHost] = { label: "default" };
-  }
-  return { activeHost, hosts };
-}
-function saveConfig(config) {
-  ensureDir();
-  fs3.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
-  logger.info(`Config saved: activeHost=${config.activeHost}, hosts=${Object.keys(config.hosts).length}`);
-}
-function getActiveHost() {
-  const sandboxHost = readSandboxCliTokenEntry()?.url;
-  if (sandboxHost) return sandboxHost;
-  const config = loadConfig();
-  return config.activeHost || "";
-}
-function setActiveHost(url) {
-  url = normalizeUrl(url);
-  const config = loadConfig();
-  if (!config.hosts[url]) {
-    throw new Error(`Host ${url} is not in the configured hosts list. Add it first.`);
-  }
-  config.activeHost = url;
-  saveConfig(config);
-}
-function addHost(url, label) {
-  url = normalizeUrl(url);
-  label = normalizeLabel(label);
-  const config = loadConfig();
-  assertUniqueHostLabel(config, label, url);
-  config.hosts[url] = { label };
-  if (!config.activeHost) {
-    config.activeHost = url;
-  }
-  saveConfig(config);
-}
-function updateHostLabel(url, label) {
-  url = normalizeUrl(url);
-  label = normalizeLabel(label);
-  const config = loadConfig();
-  if (!config.hosts[url]) {
-    throw new Error(`Host is not configured: ${url}`);
-  }
-  assertUniqueHostLabel(config, label, url);
-  config.hosts[url].label = label;
-  saveConfig(config);
-}
-function normalizeLabel(label) {
-  const normalized = label.trim();
-  if (!normalized) {
-    throw new Error("Label cannot be empty.");
-  }
-  return normalized;
-}
-function assertUniqueHostLabel(config, label, excludeUrl) {
-  const duplicate = Object.entries(config.hosts).find(([url, entry]) => url !== excludeUrl && entry.label === label);
-  if (duplicate) {
-    throw new Error(`Label already exists: ${label}. Rename the existing label first: ${duplicate[0]}`);
-  }
-}
-function removeHost(url) {
-  url = normalizeUrl(url);
-  const config = loadConfig();
-  delete config.hosts[url];
-  if (config.activeHost === url) {
-    const remaining = Object.keys(config.hosts);
-    config.activeHost = remaining.length > 0 ? remaining[0] : "";
-  }
-  saveConfig(config);
-}
-function listHosts() {
-  const config = loadConfig();
-  return Object.entries(config.hosts).map(([url, entry]) => ({
-    url,
-    label: entry.label,
-    active: url === config.activeHost
-  }));
-}
-function resolveHostSelector(env) {
-  const raw = env.trim();
-  const selector = raw.startsWith("http://") || raw.startsWith("https://") ? normalizeUrl(raw) : raw;
-  const hosts = listHosts();
-  const byUrl = hosts.find((host) => host.url === selector);
-  if (byUrl) return { status: "found", host: byUrl };
-  const byLabel = hosts.filter((host) => host.label === raw);
-  if (byLabel.length === 1) return { status: "found", host: byLabel[0] };
-  if (byLabel.length > 1) return { status: "duplicate-label", matches: byLabel };
-  return { status: "not-found", hosts };
-}
-function getConfigDir() {
-  return CONFIG_DIR;
-}
-
-export {
-  safeJsonParse,
-  safeReadJsonFile,
-  normalizeUrl,
-  getSandboxRuntimeRoot,
-  isAeSandboxRuntime,
-  getFallbackCliToken,
-  loadConfig,
-  saveConfig,
-  getActiveHost,
-  setActiveHost,
-  addHost,
-  updateHostLabel,
-  removeHost,
-  listHosts,
-  resolveHostSelector,
-  getConfigDir
-};