@thinkingai/ae-cli 6.1.19 → 6.1.20

package/skills/ae-use-agent/references/local-agent.md

@@ -0,0 +1,114 @@
+# Local Agent command guide
+
+This guide is included in ae-use-agent; installing ae-agent is optional. Use Node.js 20+
+and a local client that can run shell commands and read files.
+
+## Setup and recovery
+
+Run `ae-cli --version`. If the command is missing, obtain the AE host and supported CLI
+version from the user's environment administrator. Give the appropriate installation
+command with that version substituted; do not install automatically:
+
+```bash
+# Customer/public distribution
+npm install -g @thinkingai/ae-cli@<supported-version>
+# Internal ThinkingData distribution
+npm install -g @tant/ae-cli@<supported-version> --registry=https://npm.thinkingdata.cn:3443
+```
+
+Use the environment URL supplied by the user or configured in ae-cli; never guess a host.
+Keep that original host on every request, including authentication:
+
+```bash
+ae-cli auth status --host <original-host>
+ae-cli auth login --host <original-host>
+ae-cli agent +get-agent-context --help
+```
+
+Login is needed only when the session is missing or expired. Let the user complete the
+browser login; never request tokens in chat. If the command is unknown, the CLI is too old.
+For the public package, `ae-cli update --dry-run` previews host-compatible updates;
+perform an update only under the client's existing permissions. Internal builds use the
+internal registry above. If the host-supported release lacks this command or endpoint,
+ask the environment administrator for a compatible deployment; do not repeatedly update.
+
+## Discover and load
+
+```bash
+ae-cli agent +list-agents --q <agent-name> --host <original-host>
+ae-cli agent +get-agent-context --id <agent-id> --host <original-host>
+```
+
+Default JSON output is `{ "ok": true, "data": ... }`. Check `ok` before reading `data`.
+Name search results are in `data.agents`. Match name, scope and description; ask the user
+when ambiguous. Search by name instead of assuming an unfiltered list contains every Agent.
+An explicit ID can go directly to the context command. Ordinary members can read their
+own personal Agents and shared Agents visible to their account; no admin role is required.
+
+Context fields are `data.schema_version`, `data.context_version`, `data.agent.instructions`,
+`data.model`, `data.dependencies.skills`, `data.dependencies.mcps` and `data.summary`.
+This guide supports schema version 1; stop and obtain matching documentation for other
+versions. Use your current client model. An unavailable platform model does not block it.
+`availability=available` means visible metadata, not a working local dependency.
+
+## Read required Skill files
+
+For an available Skill, use its `id` and `files` descriptors. No extra list-skills call is
+needed. Each descriptor has `executable` and `argv`; pass arguments separately, never as
+interpolated shell code. Append `--host <original-host>`. Supported read commands are:
+
+```bash
+ae-cli agent +get-skill-content --id <skill-id> --host <original-host>
+ae-cli agent +list-skill-references --id <skill-id> --host <original-host>
+ae-cli agent +list-skill-scripts --id <skill-id> --host <original-host>
+ae-cli agent +list-skill-assets --id <skill-id> --host <original-host>
+ae-cli agent +read-skill-reference --id <skill-id> --path <relative-path> --host <original-host>
+ae-cli agent +read-skill-script --id <skill-id> --path <relative-path> --host <original-host>
+ae-cli agent +read-skill-asset --id <skill-id> --path <relative-path> --output <local-file> --host <original-host>
+```
+
+Skill body is in `data.item.content`; directory entries are in `data.items`. Text file
+reads return `data.content`. Use a path returned by the corresponding directory listing;
+`--path` is relative to references, scripts or assets, without that directory prefix.
+All three read commands support `--output <local-file>` to preserve binary bytes. Use a
+new workspace file path and inspect scripts before any execution. Check reported versions
+against the context and re-fetch if they change. An empty listing does not prove that a
+file required by the Skill is unnecessary: report a missing required file and stop that step.
+
+## MCP dependencies and failures
+
+If the user explicitly requests exporting current-user MCP credentials, use:
+
+```bash
+ae-cli agent +get-agent-context --id <agent-id> --include-mcp-credentials --host <original-host>
+```
+
+This is sensitive output: do not quote it in chat or logs, or commit it. Put the connection
+only in the intended local client configuration. Require `data.credentials_included=true`;
+its absence means an older server, not success. For each MCP, check `connection_config`:
+`exported` supplies `connection_name` and the same `connection` configuration shown in the
+current user's MCP market: `type`, `url`, `headers` for remote MCPs, or `type`, `command`,
+`args`, `env` for stdio. Header and environment keys are unchanged; system URLs use the AE
+host. `credential_expires_at=null` means expiry is not exposed. `unavailable` supplies a safe
+`connection_error`. No refresh tokens or platform-internal keys are included. Re-export
+after credentials expire or are revoked. Platform managed bridges require the platform
+runtime. Do not assume a successful export proves connectivity.
+
+
+Use `ae-cli agent +mcp-tools --id <mcp-id> --host <original-host>` for platform tool metadata.
+For OAuth MCPs only, `ae-cli agent +mcp-auth-status --id <mcp-id> --host <original-host>`
+reports platform authentication. Neither establishes a local connection. Reuse an existing
+local capability when suitable; otherwise obtain connection setup through the client's
+normal credential flow. Do not ask for secrets in chat or claim platform OAuth transfers.
+
+- 401/auth error: log in on the same host and retry once; stop if authentication still fails.
+- 403: permission denied; do not refresh repeatedly or require an admin account by default.
+- 404 on context: run `ae-cli agent +get-agent --id <agent-id> --host <original-host>`.
+  If it also fails, verify the ID/account/host. If it succeeds, verify endpoint deployment
+  with the administrator. Raw Agent configuration is not a complete context fallback.
+- 409 `invalid_agent_configuration`: ask the Agent owner to repair dependency configuration.
+- 500/network error: report the failed step and host; no silent success or fallback.
+- Unavailable dependency or file: stop only the step that needs it; explain what is missing.
+
+Never claim the full Agent is ready from prompt loading alone. Context is live metadata,
+not a frozen package; re-fetch it for a new task.

package/dist/auth-UMJAA72O.js

@@ -1,15 +0,0 @@
-import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
-import {
-  getToken,
-  invalidateAccessTokenForRetry,
-  resolveHost,
-  validateToken
-} from "./chunk-O6K2ODUE.js";
-import "./chunk-KZ6ZHF5J.js";
-import "./chunk-FR2EDAQM.js";
-export {
-  getToken,
-  invalidateAccessTokenForRetry,
-  resolveHost,
-  validateToken
-};

package/dist/chunk-533JK3YX.js

@@ -1,72 +0,0 @@
-import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
-
-// src/core/errors.ts
-var PermissionError = class extends Error {
-  constructor(message, code, hint) {
-    super(message);
-    this.code = code;
-    this.hint = hint;
-    this.name = "PermissionError";
-  }
-  code;
-  hint;
-};
-var CliValidationError = class extends Error {
-  code;
-  hint;
-  location;
-  constructor(message, options = {}) {
-    super(message);
-    this.name = "CliValidationError";
-    this.code = options.code;
-    this.hint = options.hint;
-    if (options.location) {
-      const location = {};
-      if (typeof options.location.segment === "number" && Number.isFinite(options.location.segment)) {
-        location.segment = options.location.segment;
-      }
-      if (typeof options.location.record === "number" && Number.isFinite(options.location.record)) {
-        location.record = options.location.record;
-      }
-      if (typeof options.location.field === "string" && options.location.field.length > 0) {
-        location.field = options.location.field;
-      }
-      if (Object.keys(location).length > 0) this.location = location;
-    }
-  }
-};
-var CommunityReportError = class extends Error {
-  code;
-  httpStatus;
-  hint;
-  meta;
-  constructor(message, options = {}) {
-    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
-    this.name = "CommunityReportError";
-    this.code = options.code;
-    this.httpStatus = options.httpStatus;
-    this.hint = options.hint;
-    this.meta = options.meta;
-  }
-};
-var LocalDataUploadError = class extends Error {
-  code;
-  httpStatus;
-  hint;
-  meta;
-  constructor(message, options = {}) {
-    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
-    this.name = "LocalDataUploadError";
-    this.code = options.code;
-    this.httpStatus = options.httpStatus;
-    this.hint = options.hint;
-    this.meta = options.meta;
-  }
-};
-
-export {
-  PermissionError,
-  CliValidationError,
-  CommunityReportError,
-  LocalDataUploadError
-};

package/dist/chunk-O6K2ODUE.js

@@ -1,318 +0,0 @@
-import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
-import {
-  getActiveHost,
-  getConfigDir,
-  normalizeUrl,
-  safeJsonParse
-} from "./chunk-KZ6ZHF5J.js";
-import {
-  logger
-} from "./chunk-FR2EDAQM.js";
-
-// src/core/secure-store.ts
-import crypto from "crypto";
-import fs from "fs";
-import os from "os";
-import path from "path";
-import { execFileSync } from "child_process";
-var STORE_DIR_SUFFIX = "secure-tokens";
-var SCRYPT_SALT = Buffer.from("ae-cli-secure-store-v1");
-var SCRYPT_N = 16384;
-var SCRYPT_R = 8;
-var SCRYPT_P = 1;
-var KEY_LEN = 32;
-var NONCE_LEN = 12;
-var REFRESH_TOKEN_PATH = "/v1/oauth/refreshForToken";
-function getMachineId() {
-  if (process.platform === "darwin") {
-    try {
-      const out = execFileSync(
-        "ioreg",
-        ["-rd1", "-c", "IOPlatformExpertDevice"],
-        { encoding: "utf8", timeout: 3e3 }
-      );
-      const m = out.match(/IOPlatformUUID.*?=.*?"([0-9A-F-]{36})"/i);
-      if (m?.[1]) return `darwin:${m[1]}`;
-    } catch {
-    }
-  }
-  if (process.platform === "linux") {
-    for (const p of ["/etc/machine-id", "/var/lib/dbus/machine-id"]) {
-      try {
-        const id = fs.readFileSync(p, "utf8").trim();
-        if (id) return `linux:${id}`;
-      } catch {
-      }
-    }
-  }
-  if (process.platform === "win32") {
-    try {
-      const out = execFileSync(
-        "reg",
-        ["query", "HKLM\\SOFTWARE\\Microsoft\\Cryptography", "/v", "MachineGuid"],
-        { encoding: "utf8", timeout: 3e3 }
-      );
-      const m = out.match(/MachineGuid\s+REG_SZ\s+([0-9a-f-]+)/i);
-      if (m?.[1]) return `win32:${m[1]}`;
-    } catch {
-    }
-  }
-  const fallback = `${os.homedir()}|${os.hostname()}|${os.platform()}`;
-  logger.warn("secure-store: using fallback machine-id (HOME+hostname+platform)");
-  return `fallback:${fallback}`;
-}
-var _cachedMachineId;
-function getCachedMachineId() {
-  if (!_cachedMachineId) _cachedMachineId = getMachineId();
-  return _cachedMachineId;
-}
-function deriveKey(machineId) {
-  return crypto.scryptSync(machineId, SCRYPT_SALT, KEY_LEN, {
-    N: SCRYPT_N,
-    r: SCRYPT_R,
-    p: SCRYPT_P
-  });
-}
-var _cachedKey;
-function getKey() {
-  if (!_cachedKey) _cachedKey = deriveKey(getCachedMachineId());
-  return _cachedKey;
-}
-function encrypt(plaintext) {
-  const key = getKey();
-  const nonce = crypto.randomBytes(NONCE_LEN);
-  const cipher = crypto.createCipheriv("aes-256-gcm", key, nonce);
-  const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
-  const tag = cipher.getAuthTag();
-  return {
-    nonce: nonce.toString("hex"),
-    tag: tag.toString("hex"),
-    data: encrypted.toString("hex")
-  };
-}
-function decrypt(blob) {
-  const key = getKey();
-  const nonce = Buffer.from(blob.nonce, "hex");
-  const tag = Buffer.from(blob.tag, "hex");
-  const data = Buffer.from(blob.data, "hex");
-  const decipher = crypto.createDecipheriv("aes-256-gcm", key, nonce);
-  decipher.setAuthTag(tag);
-  const decrypted = Buffer.concat([decipher.update(data), decipher.final()]);
-  return decrypted.toString("utf8");
-}
-function storeDir() {
-  return path.join(getConfigDir(), STORE_DIR_SUFFIX);
-}
-function tokenFilePath(host) {
-  const safe = host.replace(/^https?:\/\//, "").replace(/[^a-zA-Z0-9._-]/g, "_");
-  return path.join(storeDir(), `${safe}.enc.json`);
-}
-function ensureStoreDir() {
-  const dir = storeDir();
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-    try {
-      fs.chmodSync(dir, 448);
-    } catch {
-    }
-  }
-}
-function save(host, payload) {
-  ensureStoreDir();
-  const plaintext = JSON.stringify(payload);
-  const blob = encrypt(plaintext);
-  const filePath = tokenFilePath(host);
-  fs.writeFileSync(filePath, JSON.stringify(blob, null, 2), { encoding: "utf8" });
-  try {
-    fs.chmodSync(filePath, 384);
-  } catch {
-  }
-  logger.info(`secure-store: token saved for ${host}`);
-}
-function load(host) {
-  const filePath = tokenFilePath(host);
-  if (!fs.existsSync(filePath)) return null;
-  try {
-    const raw = fs.readFileSync(filePath, "utf8");
-    const blob = safeJsonParse(raw);
-    if (!blob?.nonce || !blob?.tag || !blob?.data) {
-      logger.warn(`secure-store: malformed blob for ${host}`);
-      return null;
-    }
-    const plaintext = decrypt(blob);
-    return JSON.parse(plaintext);
-  } catch (e) {
-    logger.error(`secure-store: decrypt failed for ${host}: ${e.message}`);
-    return null;
-  }
-}
-function clear(host) {
-  const filePath = tokenFilePath(host);
-  if (fs.existsSync(filePath)) {
-    fs.rmSync(filePath);
-    logger.info(`secure-store: token cleared for ${host}`);
-  }
-}
-async function getValidAccessToken(host) {
-  const payload = load(host);
-  if (!payload) {
-    throw new SecureStoreAuthError(
-      `No stored token for ${host}. Please run: ae-cli auth login`
-    );
-  }
-  const expiresAt = new Date(payload.accessExpiresAt).getTime();
-  const now = Date.now();
-  const needsRefresh = expiresAt - now < 6e4;
-  if (!needsRefresh) {
-    return payload.accessToken;
-  }
-  if (payload.refreshToken) {
-    logger.info(`secure-store: access token past local expiry for ${host}, refreshing\u2026`);
-    const refreshed = await doRefresh(host, payload.refreshToken);
-    save(host, { ...refreshed, cliToken: payload.cliToken });
-    logger.info(`secure-store: token refreshed for ${host}`);
-    return refreshed.accessToken;
-  }
-  logger.info(`secure-store: ${host} past static local expiry, no refresh token \u2014 returning stored token, server validates (lazy)`);
-  return payload.accessToken;
-}
-function loadCliToken(host) {
-  return load(host)?.cliToken ?? null;
-}
-async function doRefresh(host, refreshToken) {
-  const base = host.replace(/\/+$/, "");
-  const url = `${base}${REFRESH_TOKEN_PATH}`;
-  let resp;
-  try {
-    resp = await fetch(url, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ refreshToken })
-    });
-  } catch (e) {
-    throw new SecureStoreAuthError(
-      `Token refresh network error for ${host}: ${e.message}. Please run: ae-cli auth login`
-    );
-  }
-  if (!resp.ok) {
-    throw new SecureStoreAuthError(
-      `Token refresh failed (HTTP ${resp.status}) for ${host}. Please run: ae-cli auth login`
-    );
-  }
-  let body;
-  try {
-    body = safeJsonParse(await resp.text());
-  } catch {
-    throw new SecureStoreAuthError(
-      `Token refresh returned invalid JSON for ${host}. Please run: ae-cli auth login`
-    );
-  }
-  if (body.return_code !== 0) {
-    throw new SecureStoreAuthError(
-      `Token refresh error (${body.return_code}: ${body.return_message ?? "unknown"}) for ${host}. Please run: ae-cli auth login`
-    );
-  }
-  const d = body.data;
-  const newAccess = d?.accessToken ?? d?.access_token ?? "";
-  const newRefresh = d?.refreshToken ?? d?.refresh_token ?? refreshToken;
-  const expiresIn = d?.expiresIn ?? d?.expires_in ?? 72e3;
-  if (!newAccess) {
-    throw new SecureStoreAuthError(
-      `Token refresh returned empty accessToken for ${host}. Please run: ae-cli auth login`
-    );
-  }
-  return {
-    accessToken: newAccess,
-    refreshToken: newRefresh,
-    accessExpiresAt: new Date(Date.now() + expiresIn * 1e3).toISOString()
-  };
-}
-var SecureStoreAuthError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "SecureStoreAuthError";
-  }
-};
-
-// src/core/host-guidance.ts
-var AE_TRIAL_URL = "https://thinkingai.cn/request-demo";
-var AE_HOST_SETUP_COMMAND = "ae-cli config set-host <url>";
-function missingAeHostHint(additionalAction) {
-  const actions = [
-    `If your organization already uses AgenticEngine, ask your administrator for its AE URL, then run: ${AE_HOST_SETUP_COMMAND}.`,
-    `If you do not have an AgenticEngine environment, request a trial: ${AE_TRIAL_URL}`
-  ];
-  if (additionalAction) actions.push(additionalAction);
-  return actions.join(" ");
-}
-function missingAeHostGuidance() {
-  return {
-    configure_host: AE_HOST_SETUP_COMMAND,
-    existing_customer: "Ask your AgenticEngine administrator for the AE environment URL.",
-    request_trial_url: AE_TRIAL_URL
-  };
-}
-
-// src/core/auth.ts
-function resolveHost(hostOverride) {
-  if (hostOverride) return normalizeUrl(hostOverride);
-  return getActiveHost();
-}
-async function validateToken(token, hostUrl) {
-  const url = `${hostUrl}/v1/oauth/checkToken`;
-  try {
-    const resp = await fetch(url, {
-      method: "POST",
-      headers: { "Content-Type": "application/x-www-form-urlencoded" },
-      body: new URLSearchParams({ accessToken: token }).toString()
-    });
-    const respJson = safeJsonParse(await resp.text());
-    return respJson?.return_code === 0;
-  } catch {
-    return false;
-  }
-}
-function invalidateAccessTokenForRetry(hostUrl) {
-  const payload = load(hostUrl);
-  if (!payload) return;
-  save(hostUrl, { ...payload, accessExpiresAt: (/* @__PURE__ */ new Date(0)).toISOString() });
-  logger.info(`auth: marked access token stale for retry on ${hostUrl}`);
-}
-async function getToken(hostUrl) {
-  if (!hostUrl) {
-    throw new Error(
-      `No AE host configured.
-` + missingAeHostHint()
-    );
-  }
-  try {
-    const secureToken = await getValidAccessToken(hostUrl);
-    logger.info(`Using secure-store token for ${hostUrl}`);
-    return secureToken;
-  } catch (e) {
-    if (e instanceof SecureStoreAuthError) {
-      logger.info(`secure-store: ${e.message}`);
-    } else {
-      logger.warn(`secure-store unexpected error: ${e.message}`);
-    }
-  }
-  throw new Error(
-    `Cannot obtain token for ${hostUrl}.
-Run: ae-cli auth login   (device code flow, cross-platform)`
-  );
-}
-
-export {
-  save,
-  load,
-  clear,
-  loadCliToken,
-  SecureStoreAuthError,
-  AE_TRIAL_URL,
-  missingAeHostHint,
-  missingAeHostGuidance,
-  resolveHost,
-  validateToken,
-  invalidateAccessTokenForRetry,
-  getToken
-};