@kweaver-ai/kweaver-sdk 0.6.7 → 0.6.8

package/README.md

@@ -31,7 +31,9 @@ export KWEAVER_BASE_URL=https://your-kweaver-instance.com
 export KWEAVER_TOKEN=your-token
 ```
 
-With both set, API commands use that token even if you never ran `auth login`. You can also run **`kweaver auth status`**, **`kweaver auth whoami`** (supports `--json`), and **`kweaver config show`** when there is **no** current platform in `~/.kweaver/` — the CLI decodes the token locally (JWT only). If the token is opaque, identity fields are omitted and a short hint is printed.
+With both set, API commands use that token even if you never ran `auth login`. You can also run **`kweaver auth status`**, **`kweaver auth whoami`** (supports `--json`), and **`kweaver config show`** when there is **no** current platform in `~/.kweaver/`. In env-token mode, `whoami` resolves the bound identity from EACP `/api/eacp/v1/user/get` and prints `Type` (user/app), `User ID`, `Account` and `Name`; this works for both opaque and JWT tokens. If EACP is unreachable, the CLI falls back to local JWT decode and prints a short hint when the token is opaque.
+
+`kweaver config list-bd` lists business domains for the current user. App (service) tokens are not bound to an end-user — when the backend rejects the call with `401 invalid user_id`, the CLI re-checks the token type via EACP and, if confirmed `type:"app"`, replaces the cryptic backend body with `This command does not support app accounts.`. Use a user token (interactive `auth login`) for user-bound endpoints.
 
 ### Business domain (platform)
 

package/README.zh.md

@@ -31,7 +31,9 @@ export KWEAVER_BASE_URL=https://your-kweaver-instance.com
 export KWEAVER_TOKEN=your-token
 ```
 
-两者同时设置时，即使未执行 `auth login`，业务命令也会使用该 token。若 **`~/.kweaver/` 无当前平台**，仍可使用 **`kweaver auth status`**、**`kweaver auth whoami`**（支持 `--json`）、**`kweaver config show`**：CLI 会在本地解 JWT 展示身份；若 token 为 opaque，则省略身份字段并给出简短提示。
+两者同时设置时，即使未执行 `auth login`，业务命令也会使用该 token。若 **`~/.kweaver/` 无当前平台**，仍可使用 **`kweaver auth status`**、**`kweaver auth whoami`**（支持 `--json`）、**`kweaver config show`**。环境变量模式下，`whoami` 会通过 EACP `/api/eacp/v1/user/get` 在线获取身份并展示 `Type`（user/app）、`User ID`、`Account`、`Name`，对 opaque 与 JWT token 都生效；若 EACP 不可达，则回退到本地 JWT 解码，opaque token 会给出简短提示。
+
+`kweaver config list-bd` 用于列出当前用户可访问的业务域。**应用（service）token 没有绑定终端用户**——当后端返回 `401 invalid user_id` 时，CLI 会再向 EACP 复核 token 类型，确认为 `type:"app"` 后将晦涩的后端原文替换为 `This command does not support app accounts.`。需要这个能力时请改用交互式 `auth login` 获得的用户 token。
 
 ### 业务域（平台配置）
 

package/dist/auth/oauth.d.ts

@@ -27,18 +27,73 @@ export declare const DEFAULT_SIGNIN_RSA_MODULUS_HEX = "C1D9F84B95AF6B331FBA2D64D
  * Build an SPKI PEM from an RSA modulus (hex) and public exponent (default 65537 / 0x10001).
  */
 export declare function rsaModulusHexToSpkiPem(modulusHex: string, exponent?: number): string;
-/** POSIX shell single-quote escaping for copy-paste commands. */
-export declare function shellQuoteForShell(value: string): string;
+/** Identity resolved from EACP `/api/eacp/v1/user/get` for the bound access token. */
+export interface EacpUserInfo {
+    /** "user" — interactive end-user; "app" — service / application identity. */
+    type: "user" | "app";
+    /** EACP id (`userid` for users, `id` for apps). */
+    id: string;
+    /** Login name (e.g. "alice@example.com"). User tokens only. */
+    account?: string;
+    /** Display name — `visionName` for users, app name for apps. */
+    name?: string;
+}
+/**
+ * Probe EACP for the bound identity. Returns `null` on any failure (network,
+ * non-2xx, malformed JSON, unknown `type`). Callers must treat absence as a
+ * soft signal — this never throws and never blocks the user's actual command.
+ *
+ * The shape differs per token type, mirroring the EACP backend:
+ *   - `type: "user"` → `{ userid, account, name, ... }`
+ *   - `type: "app"`  → `{ id, name }`
+ */
+export declare function fetchEacpUserInfo(baseUrl: string, accessToken: string, tlsInsecure?: boolean): Promise<EacpUserInfo | null>;
+/**
+ * Quote a value for safe copy-paste into a shell command.
+ *
+ * Strategy:
+ * - If the value only contains "shell-safe" characters, return it bare. This
+ *   keeps the printed command portable across shells (issue #74: POSIX single
+ *   quotes are literal in cmd.exe, so any quoting locks the line to one OS).
+ * - Otherwise the value contains characters the shell would interpret
+ *   (space, `&`, `|`, `$`, `*`, ...), so we must quote per host shell:
+ *     - win32 (cmd.exe / PowerShell): wrap in `"..."`; embedded `"` -> `""`
+ *     - POSIX (bash/zsh/sh): wrap in `'...'`; embedded `'` -> `'\''`
+ *
+ * `platform` defaults to `process.platform`; passable for tests and for
+ * generating commands targeted at a specific shell.
+ */
+export declare function shellQuoteForShell(value: string, platform?: NodeJS.Platform): string;
 /**
  * Build a one-line `kweaver auth login ...` command for headless / other machines.
  * Omits `--client-secret` when empty (PKCE-only client); headless refresh may still require a confidential client.
+ *
+ * `platform` defaults to `process.platform`; pass explicitly in tests or when
+ * generating a command meant for a different OS.
  */
-export declare function buildCopyCommand(baseUrl: string, clientId: string, clientSecret: string, refreshToken: string | undefined, tlsInsecure?: boolean): string;
+export declare function buildCopyCommand(baseUrl: string, clientId: string, clientSecret: string, refreshToken: string | undefined, tlsInsecure?: boolean, platform?: NodeJS.Platform): string;
 /**
  * HTML shown after successful OAuth callback with a copyable headless login command.
  */
 export declare function buildCallbackHtml(copyCommand: string): string;
 export declare function normalizeBaseUrl(value: string): string;
+/**
+ * Resolve the platform URL the CLI should act on, with explicit precedence:
+ *
+ *   1. **positional**  — caller passed a URL/alias (always wins)
+ *   2. **env**         — `KWEAVER_BASE_URL` is set (explicit user intent;
+ *                        wins over a stale `~/.kweaver/` saved session)
+ *   3. **saved**       — `getCurrentPlatform()` from local config
+ *
+ * `source` lets callers print provenance without re-deriving it. This mirrors
+ * `ensureValidToken()` (which is already env-first), so introspection
+ * commands (`auth status`, `auth whoami`, `config show|list-bd|set-bd`) and
+ * data-path commands agree on which platform "current" means.
+ */
+export declare function resolveActivePlatform(positional?: string | null): {
+    url: string;
+    source: "positional" | "env" | "saved";
+} | null;
 /**
  * Temporarily disable TLS certificate verification for Node `fetch` (sets
  * NODE_TLS_REJECT_UNAUTHORIZED). Used for `--insecure` login and token refresh.

package/dist/auth/oauth.js

@@ -246,42 +246,94 @@ function extractRsaPublicKeyMaterialFromPageProps(pageProps) {
     }
     return deepFindSigninRsaMaterial(pageProps, 5, new Set());
 }
-/** Best-effort fetch of display name via EACP userinfo (ShareServer). */
-async function fetchDisplayName(baseUrl, accessToken, tlsInsecure) {
+/**
+ * Probe EACP for the bound identity. Returns `null` on any failure (network,
+ * non-2xx, malformed JSON, unknown `type`). Callers must treat absence as a
+ * soft signal — this never throws and never blocks the user's actual command.
+ *
+ * The shape differs per token type, mirroring the EACP backend:
+ *   - `type: "user"` → `{ userid, account, name, ... }`
+ *   - `type: "app"`  → `{ id, name }`
+ */
+export async function fetchEacpUserInfo(baseUrl, accessToken, tlsInsecure) {
     try {
         const res = await runWithTlsInsecure(tlsInsecure, () => fetch(`${baseUrl}/api/eacp/v1/user/get`, {
             headers: { Authorization: `Bearer ${accessToken}`, Accept: "application/json" },
         }));
         if (!res.ok)
             return null;
-        const info = (await res.json());
-        if (typeof info.account === "string")
-            return info.account;
-        if (typeof info.name === "string")
-            return info.name;
-        if (typeof info.mail === "string")
-            return info.mail;
+        const raw = (await res.json());
+        const type = raw.type;
+        if (type !== "user" && type !== "app")
+            return null;
+        const idCandidate = type === "user" ? raw.userid : raw.id;
+        const id = typeof idCandidate === "string" ? idCandidate : "";
+        if (!id)
+            return null;
+        return {
+            type,
+            id,
+            account: typeof raw.account === "string" ? raw.account : undefined,
+            name: typeof raw.name === "string" ? raw.name : undefined,
+        };
     }
     catch {
-        /* Non-critical — displayName will be absent. */
+        return null;
     }
-    return null;
 }
-/** POSIX shell single-quote escaping for copy-paste commands. */
-export function shellQuoteForShell(value) {
+/** Best-effort fetch of display name via EACP userinfo (ShareServer). */
+async function fetchDisplayName(baseUrl, accessToken, tlsInsecure) {
+    const info = await fetchEacpUserInfo(baseUrl, accessToken, tlsInsecure);
+    return info?.account ?? info?.name ?? null;
+}
+/**
+ * Characters that bash/zsh/sh AND cmd.exe/PowerShell all leave untouched when
+ * a value is written without surrounding quotes. Real-world OAuth values
+ * (URLs, UUID-like client IDs, base64url refresh tokens) live in this set, so
+ * we can emit them bare and the resulting command is portable across macOS,
+ * Linux, Windows cmd, and PowerShell — including the copy-mac-paste-to-windows
+ * (and the reverse) workflow.
+ */
+const SHELL_SAFE_VALUE = /^[A-Za-z0-9._:/+=@-]+$/;
+/**
+ * Quote a value for safe copy-paste into a shell command.
+ *
+ * Strategy:
+ * - If the value only contains "shell-safe" characters, return it bare. This
+ *   keeps the printed command portable across shells (issue #74: POSIX single
+ *   quotes are literal in cmd.exe, so any quoting locks the line to one OS).
+ * - Otherwise the value contains characters the shell would interpret
+ *   (space, `&`, `|`, `$`, `*`, ...), so we must quote per host shell:
+ *     - win32 (cmd.exe / PowerShell): wrap in `"..."`; embedded `"` -> `""`
+ *     - POSIX (bash/zsh/sh): wrap in `'...'`; embedded `'` -> `'\''`
+ *
+ * `platform` defaults to `process.platform`; passable for tests and for
+ * generating commands targeted at a specific shell.
+ */
+export function shellQuoteForShell(value, platform = process.platform) {
+    if (value !== "" && SHELL_SAFE_VALUE.test(value)) {
+        return value;
+    }
+    if (platform === "win32") {
+        return `"${value.replace(/"/g, `""`)}"`;
+    }
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 /**
  * Build a one-line `kweaver auth login ...` command for headless / other machines.
  * Omits `--client-secret` when empty (PKCE-only client); headless refresh may still require a confidential client.
+ *
+ * `platform` defaults to `process.platform`; pass explicitly in tests or when
+ * generating a command meant for a different OS.
  */
-export function buildCopyCommand(baseUrl, clientId, clientSecret, refreshToken, tlsInsecure) {
-    const parts = ["kweaver", "auth", "login", shellQuoteForShell(normalizeBaseUrl(baseUrl)), "--client-id", shellQuoteForShell(clientId)];
+export function buildCopyCommand(baseUrl, clientId, clientSecret, refreshToken, tlsInsecure, platform = process.platform) {
+    const q = (v) => shellQuoteForShell(v, platform);
+    const parts = ["kweaver", "auth", "login", q(normalizeBaseUrl(baseUrl)), "--client-id", q(clientId)];
     if (clientSecret) {
-        parts.push("--client-secret", shellQuoteForShell(clientSecret));
+        parts.push("--client-secret", q(clientSecret));
     }
     if (refreshToken) {
-        parts.push("--refresh-token", shellQuoteForShell(refreshToken));
+        parts.push("--refresh-token", q(refreshToken));
     }
     if (tlsInsecure) {
         parts.push("--insecure");
@@ -351,6 +403,33 @@ function buildCallbackExchangeErrorHtml(message) {
 export function normalizeBaseUrl(value) {
     return value.replace(/\/+$/, "");
 }
+/**
+ * Resolve the platform URL the CLI should act on, with explicit precedence:
+ *
+ *   1. **positional**  — caller passed a URL/alias (always wins)
+ *   2. **env**         — `KWEAVER_BASE_URL` is set (explicit user intent;
+ *                        wins over a stale `~/.kweaver/` saved session)
+ *   3. **saved**       — `getCurrentPlatform()` from local config
+ *
+ * `source` lets callers print provenance without re-deriving it. This mirrors
+ * `ensureValidToken()` (which is already env-first), so introspection
+ * commands (`auth status`, `auth whoami`, `config show|list-bd|set-bd`) and
+ * data-path commands agree on which platform "current" means.
+ */
+export function resolveActivePlatform(positional) {
+    if (positional) {
+        const url = /^https?:\/\//.test(positional) ? normalizeBaseUrl(positional) : positional;
+        return { url, source: "positional" };
+    }
+    const envRaw = process.env.KWEAVER_BASE_URL?.trim();
+    if (envRaw) {
+        return { url: normalizeBaseUrl(envRaw), source: "env" };
+    }
+    const saved = getCurrentPlatform();
+    if (saved)
+        return { url: saved, source: "saved" };
+    return null;
+}
 /**
  * Temporarily disable TLS certificate verification for Node `fetch` (sets
  * NODE_TLS_REJECT_UNAUTHORIZED). Used for `--insecure` login and token refresh.
@@ -1653,7 +1732,12 @@ export function formatHttpError(error) {
         if (oauthMessage) {
             return `HTTP ${error.status} ${error.statusText}\n\n${oauthMessage}`;
         }
-        return `${error.message}\n${error.body}`.trim();
+        const base = `${error.message}\n${error.body}`.trim();
+        if ((error.status === 403 || error.status === 404) &&
+            /BknBackend\.KnowledgeNetwork\.NotFound/.test(error.body)) {
+            return `Hint: this is a "knowledge network not found" error (the kn-id does not exist), not a permission/auth issue. Verify the kn-id you passed.\n${base}`;
+        }
+        return base;
     }
     if (error instanceof NetworkRequestError) {
         return [

package/dist/commands/agent-members.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Pure helpers and orchestrators for managing agent member associations
+ * (skills, tools, mcps) via get → mutate(config) → update.
+ */
+export interface MutationReport {
+    finalIds: string[];
+    added: string[];
+    alreadyAttached: string[];
+    removed: string[];
+    notAttached: string[];
+}
+export interface MutateConfigMembersInput {
+    config: Record<string, unknown>;
+    path: string[];
+    idField: string;
+    addIds: string[];
+    removeIds: string[];
+}
+export interface MutateConfigMembersResult {
+    newConfig: Record<string, unknown>;
+    report: MutationReport;
+    finalIds: string[];
+}
+export declare function mutateConfigMembers(input: MutateConfigMembersInput): MutateConfigMembersResult;
+export interface MemberFetchResult {
+    exists: boolean;
+    published: boolean;
+    name?: string;
+    /** Optional free-form status label for `list` output; e.g. "published" | "draft" | "offline". */
+    status?: string;
+}
+export interface MemberSpec {
+    /** Human-readable noun used in error/warning messages. */
+    memberKind: string;
+    /** Path inside the agent `config` object where the member array lives. */
+    configPath: string[];
+    /** Key inside each array element that identifies the member. */
+    idField: string;
+}
+export interface AgentMembersDeps {
+    getAgent: (agentId: string) => Promise<string>;
+    updateAgent: (agentId: string, body: Record<string, unknown>) => Promise<string>;
+    fetchById: (id: string) => Promise<MemberFetchResult>;
+}
+export interface PatchAgentMembersInput {
+    agentId: string;
+    spec: MemberSpec;
+    addIds: string[];
+    removeIds: string[];
+    strict: boolean;
+    deps: AgentMembersDeps;
+}
+export interface PatchAgentMembersReport extends MutationReport {
+    warnings: string[];
+}
+export declare function patchAgentMembers(input: PatchAgentMembersInput): Promise<PatchAgentMembersReport>;
+export interface ListAgentMembersInput {
+    agentId: string;
+    spec: MemberSpec;
+    deps: Pick<AgentMembersDeps, "getAgent" | "fetchById">;
+}
+export interface ListedMember {
+    id: string;
+    name: string | null;
+    status: string;
+}
+export declare function listAgentMembers(input: ListAgentMembersInput): Promise<ListedMember[]>;
+export declare function runAgentSkillCommand(args: string[]): Promise<number>;

package/dist/commands/agent-members.js

@@ -0,0 +1,383 @@
+/**
+ * Pure helpers and orchestrators for managing agent member associations
+ * (skills, tools, mcps) via get → mutate(config) → update.
+ */
+import { getAgent, updateAgent } from "../api/agent-list.js";
+import { getSkill } from "../api/skills.js";
+import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
+import { resolveBusinessDomain } from "../config/store.js";
+/** Deep-clone a JSON-serializable object so mutations don't leak to callers. */
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * Descend into `config` along `path`, creating empty objects and a terminal
+ * empty array along the way if any node is missing. Returns the terminal array.
+ */
+function ensureArrayAtPath(root, path) {
+    let cursor = root;
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const key = path[i];
+        const next = cursor[key];
+        if (next === undefined || next === null) {
+            cursor[key] = {};
+        }
+        else if (typeof next !== "object" || Array.isArray(next)) {
+            throw new Error(`Config path conflict at ${path.slice(0, i + 1).join(".")}: expected object, got ${Array.isArray(next) ? "array" : typeof next}`);
+        }
+        cursor = cursor[key];
+    }
+    const terminalKey = path[path.length - 1];
+    const terminal = cursor[terminalKey];
+    if (terminal === undefined || terminal === null) {
+        cursor[terminalKey] = [];
+    }
+    else if (!Array.isArray(terminal)) {
+        throw new Error(`Config path conflict at ${path.join(".")}: expected array, got ${typeof terminal}`);
+    }
+    return cursor[terminalKey];
+}
+export function mutateConfigMembers(input) {
+    if (input.path.length === 0) {
+        throw new Error("mutateConfigMembers: path must have at least one segment");
+    }
+    const newConfig = clone(input.config);
+    const arr = ensureArrayAtPath(newConfig, input.path);
+    const existingIds = arr.map((el) => String(el[input.idField] ?? ""));
+    const currentSet = new Set(existingIds);
+    const added = [];
+    const alreadyAttached = [];
+    for (const id of input.addIds) {
+        if (currentSet.has(id)) {
+            alreadyAttached.push(id);
+        }
+        else {
+            arr.push({ [input.idField]: id });
+            currentSet.add(id);
+            added.push(id);
+        }
+    }
+    const removeSet = new Set(input.removeIds);
+    const removed = [];
+    const notAttached = [];
+    if (removeSet.size > 0) {
+        const survivors = [];
+        const survivingIdSet = new Set();
+        for (const el of arr) {
+            const id = String(el[input.idField] ?? "");
+            if (removeSet.has(id)) {
+                if (!removed.includes(id))
+                    removed.push(id);
+                continue;
+            }
+            survivors.push(el);
+            survivingIdSet.add(id);
+        }
+        for (const id of input.removeIds) {
+            if (!removed.includes(id) && !survivingIdSet.has(id)) {
+                notAttached.push(id);
+            }
+        }
+        arr.length = 0;
+        arr.push(...survivors);
+    }
+    const finalIds = arr.map((el) => String(el[input.idField] ?? ""));
+    return {
+        newConfig,
+        finalIds,
+        report: {
+            finalIds,
+            added,
+            alreadyAttached,
+            removed,
+            notAttached,
+        },
+    };
+}
+function mergeAgentBody(current, newConfig) {
+    return {
+        name: current.name,
+        profile: current.profile,
+        avatar_type: current.avatar_type,
+        avatar: current.avatar,
+        product_key: current.product_key,
+        config: newConfig,
+    };
+}
+export async function patchAgentMembers(input) {
+    const { agentId, spec, addIds, removeIds, strict, deps } = input;
+    const warnings = [];
+    // 1. validate (add only)
+    if (addIds.length > 0) {
+        const results = await Promise.all(addIds.map(async (id) => ({ id, info: await deps.fetchById(id) })));
+        const missing = results.filter((r) => !r.info.exists).map((r) => r.id);
+        if (missing.length > 0) {
+            throw new Error(`${spec.memberKind}(s) ${missing.join(", ")} not found (aborting, agent not modified)`);
+        }
+        const drafts = results.filter((r) => r.info.exists && !r.info.published).map((r) => r.id);
+        if (drafts.length > 0) {
+            if (strict) {
+                throw new Error(`${spec.memberKind}(s) ${drafts.join(", ")} are in draft status (aborted by --strict)`);
+            }
+            for (const id of drafts) {
+                warnings.push(`${spec.memberKind} ${id} is in draft status (use --strict to reject, or publish it first)`);
+            }
+        }
+    }
+    // 2. fetch current agent
+    const currentRaw = await deps.getAgent(agentId);
+    const current = JSON.parse(currentRaw);
+    const config = (current.config ?? {});
+    // 3. mutate
+    const { newConfig, report } = mutateConfigMembers({
+        config,
+        path: spec.configPath,
+        idField: spec.idField,
+        addIds,
+        removeIds,
+    });
+    // Short-circuit: no-op (skip the write if neither add nor remove changed anything)
+    const nothingChanged = report.added.length === 0 && report.removed.length === 0;
+    if (nothingChanged) {
+        return { ...report, warnings };
+    }
+    // 4. write
+    await deps.updateAgent(agentId, mergeAgentBody(current, newConfig));
+    // 5. report
+    return { ...report, warnings };
+}
+export async function listAgentMembers(input) {
+    const { agentId, spec, deps } = input;
+    const currentRaw = await deps.getAgent(agentId);
+    const current = JSON.parse(currentRaw);
+    const config = (current.config ?? {});
+    // Read (don't create) the path. If any segment is missing, result is empty.
+    let cursor = config;
+    for (const key of spec.configPath) {
+        if (cursor && typeof cursor === "object" && !Array.isArray(cursor) && key in cursor) {
+            cursor = cursor[key];
+        }
+        else {
+            return [];
+        }
+    }
+    if (!Array.isArray(cursor))
+        return [];
+    const ids = cursor.map((el) => String(el[spec.idField] ?? ""));
+    const results = await Promise.all(ids.map(async (id) => {
+        try {
+            const info = await deps.fetchById(id);
+            return {
+                id,
+                name: info.name ?? null,
+                status: info.status ?? (info.exists ? (info.published ? "published" : "unpublish") : "unknown"),
+            };
+        }
+        catch {
+            return { id, name: null, status: "unknown" };
+        }
+    }));
+    return results;
+}
+// ── Skill command handler ────────────────────────────────────────────────────
+const SKILL_SPEC = {
+    memberKind: "skill",
+    configPath: ["skills", "skills"],
+    idField: "skill_id",
+};
+function parseWriteArgs(args, verb) {
+    const agentId = args[0];
+    if (!agentId || agentId.startsWith("-")) {
+        throw new Error(`Missing <agent-id> for ${verb}`);
+    }
+    const ids = [];
+    let strict = false;
+    let businessDomain = "";
+    for (let i = 1; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--strict") {
+            strict = true;
+            continue;
+        }
+        if (arg === "-bd" || arg === "--biz-domain") {
+            businessDomain = args[i + 1] ?? "";
+            if (!businessDomain || businessDomain.startsWith("-")) {
+                throw new Error("Missing value for biz-domain flag");
+            }
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            throw new Error(`Unsupported flag: ${arg}`);
+        }
+        ids.push(arg);
+    }
+    if (ids.length === 0) {
+        throw new Error(`Missing <member-id> for ${verb}`);
+    }
+    return { agentId, ids, strict, businessDomain };
+}
+function printReport(kind, agentId, report) {
+    for (const w of report.warnings)
+        process.stderr.write(`! ${w}\n`);
+    for (const id of report.added)
+        console.log(`✓ ${id}  added`);
+    for (const id of report.alreadyAttached)
+        console.log(`• ${id}  already attached (skipped)`);
+    for (const id of report.removed)
+        console.log(`✓ ${id}  removed`);
+    for (const id of report.notAttached)
+        console.log(`• ${id}  not attached (skipped)`);
+    console.log(`Agent ${agentId} now has ${report.finalIds.length} ${kind}(s) attached.`);
+}
+async function runSkillAdd(args) {
+    try {
+        const parsed = parseWriteArgs(args, "add");
+        const token = await ensureValidToken();
+        const businessDomain = parsed.businessDomain || resolveBusinessDomain();
+        const deps = {
+            getAgent: (id) => getAgent({ baseUrl: token.baseUrl, accessToken: token.accessToken, agentId: id, businessDomain }),
+            updateAgent: (id, body) => updateAgent({ baseUrl: token.baseUrl, accessToken: token.accessToken, agentId: id, body: JSON.stringify(body), businessDomain }),
+            fetchById: async (id) => {
+                try {
+                    const info = await getSkill({ baseUrl: token.baseUrl, accessToken: token.accessToken, skillId: id, businessDomain });
+                    return {
+                        exists: true,
+                        published: info.status === "published",
+                        name: info.name,
+                        status: info.status,
+                    };
+                }
+                catch {
+                    return { exists: false, published: false };
+                }
+            },
+        };
+        const report = await patchAgentMembers({
+            agentId: parsed.agentId,
+            spec: SKILL_SPEC,
+            addIds: parsed.ids,
+            removeIds: [],
+            strict: parsed.strict,
+            deps,
+        });
+        printReport("skill", parsed.agentId, report);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`✗ ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+async function runSkillRemove(args) {
+    try {
+        const parsed = parseWriteArgs(args, "remove");
+        const token = await ensureValidToken();
+        const businessDomain = parsed.businessDomain || resolveBusinessDomain();
+        const deps = {
+            getAgent: (id) => getAgent({ baseUrl: token.baseUrl, accessToken: token.accessToken, agentId: id, businessDomain }),
+            updateAgent: (id, body) => updateAgent({ baseUrl: token.baseUrl, accessToken: token.accessToken, agentId: id, body: JSON.stringify(body), businessDomain }),
+            fetchById: async () => ({ exists: true, published: true }),
+        };
+        const report = await patchAgentMembers({
+            agentId: parsed.agentId,
+            spec: SKILL_SPEC,
+            addIds: [],
+            removeIds: parsed.ids,
+            strict: false,
+            deps,
+        });
+        printReport("skill", parsed.agentId, report);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`✗ ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+async function runSkillList(args) {
+    const agentId = args[0];
+    if (!agentId || agentId.startsWith("-")) {
+        process.stderr.write("Missing <agent-id> for list\n");
+        return 1;
+    }
+    let pretty = true;
+    let businessDomain = "";
+    for (let i = 1; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--pretty") {
+            pretty = true;
+            continue;
+        }
+        if (arg === "--compact") {
+            pretty = false;
+            continue;
+        }
+        if (arg === "-bd" || arg === "--biz-domain") {
+            businessDomain = args[i + 1] ?? "";
+            if (!businessDomain || businessDomain.startsWith("-")) {
+                process.stderr.write("Missing value for biz-domain flag\n");
+                return 1;
+            }
+            i += 1;
+            continue;
+        }
+        process.stderr.write(`Unsupported flag: ${arg}\n`);
+        return 1;
+    }
+    const token = await ensureValidToken();
+    businessDomain = businessDomain || resolveBusinessDomain();
+    const deps = {
+        getAgent: (id) => getAgent({ baseUrl: token.baseUrl, accessToken: token.accessToken, agentId: id, businessDomain }),
+        fetchById: async (id) => {
+            try {
+                const info = await getSkill({ baseUrl: token.baseUrl, accessToken: token.accessToken, skillId: id, businessDomain });
+                return { exists: true, published: info.status === "published", name: info.name, status: info.status };
+            }
+            catch {
+                return { exists: false, published: false };
+            }
+        },
+    };
+    try {
+        const rows = await listAgentMembers({ agentId, spec: SKILL_SPEC, deps });
+        const output = rows.map((r) => ({ skill_id: r.id, name: r.name, status: r.status }));
+        console.log(JSON.stringify(output, null, pretty ? 2 : 0));
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`✗ ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+export async function runAgentSkillCommand(args) {
+    const [verb, ...rest] = args;
+    if (!verb || verb === "--help" || verb === "-h") {
+        console.log(`kweaver agent skill
+
+Subcommands:
+  add <agent-id> <skill-id>... [--strict] [-bd <bd>]      Attach skills to an agent
+  remove <agent-id> <skill-id>... [-bd <bd>]              Detach skills from an agent
+  list <agent-id> [--pretty|--compact] [-bd <bd>]         List skills attached to an agent
+
+Notes:
+  --strict         On add, reject skills that exist but are not in 'published' status.
+                   Default behaviour: warn and continue.
+  Dedupe is automatic for add; remove silently skips not-attached ids.`);
+        return 0;
+    }
+    try {
+        if (verb === "add")
+            return await runSkillAdd(rest);
+        if (verb === "remove")
+            return await runSkillRemove(rest);
+        if (verb === "list")
+            return await runSkillList(rest);
+        process.stderr.write(`Unknown agent skill subcommand: ${verb}\n`);
+        return 1;
+    }
+    catch (error) {
+        process.stderr.write(`${formatHttpError(error)}\n`);
+        return 1;
+    }
+}

package/dist/commands/agent.js

@@ -1,5 +1,6 @@
 import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
 import { runAgentChatCommand } from "./agent-chat.js";
+import { runAgentSkillCommand } from "./agent-members.js";
 import { listAgents, getAgent, getAgentByKey, createAgent, updateAgent, deleteAgent, publishAgent, unpublishAgent, listPersonalAgents, listPublishedAgentTemplates, getPublishedAgentTemplate, listAgentCategories, } from "../api/agent-list.js";
 import { listConversations, listMessages, getTracesByConversation } from "../api/conversations.js";
 import { fetchAgentInfo } from "../api/agent-chat.js";
@@ -516,6 +517,7 @@ Subcommands:
   unpublish <agent_id>               Unpublish an agent
   chat <agent_id>                    Start interactive chat with an agent
   chat <agent_id> -m "message"       Send a single message (non-interactive)
+  skill <verb> ...                   Manage skills attached to an agent (add/remove/list)
   sessions <agent_id>                List all conversations for an agent
   history <agent_id> <conversation_id> Show message history for a conversation
   trace <agent_id> <conversation_id>  Get trace data for a conversation`);
@@ -554,6 +556,8 @@ Subcommands:
             return runAgentPublishCommand(rest);
         if (subcommand === "unpublish")
             return runAgentUnpublishCommand(rest);
+        if (subcommand === "skill")
+            return runAgentSkillCommand(rest);
         return -1;
     };
     // Show subcommand-specific help inline (no retry needed)

package/dist/commands/auth.js

@@ -2,7 +2,7 @@ import { isNoAuth } from "../config/no-auth.js";
 import { autoSelectBusinessDomain, clearPlatformSession, deletePlatform, deleteUser, getActiveUser, getConfigDir, getCurrentPlatform, getPlatformAlias, hasPlatform, listPlatforms, listUserProfiles, loadClientConfig, loadTokenConfig, loadUserTokenConfig, resolveBusinessDomain, resolvePlatformIdentifier, resolveUserId, saveNoAuthPlatform, setActiveUser, setCurrentPlatform, setPlatformAlias, } from "../config/store.js";
 import { decodeJwtPayload } from "../config/jwt.js";
 import { eacpModifyPassword } from "../auth/eacp-modify-password.js";
-import { buildCopyCommand, formatHttpError, InitialPasswordChangeRequiredError, normalizeBaseUrl, oauth2Login, oauth2PasswordSigninLogin, promptForUsername, promptForPassword, refreshTokenLogin, } from "../auth/oauth.js";
+import { buildCopyCommand, fetchEacpUserInfo, formatHttpError, InitialPasswordChangeRequiredError, normalizeBaseUrl, oauth2Login, oauth2PasswordSigninLogin, promptForUsername, promptForPassword, refreshTokenLogin, resolveActivePlatform, } from "../auth/oauth.js";
 export async function runAuthCommand(args) {
     const target = args[0];
     const rest = args.slice(1);
@@ -54,7 +54,7 @@ Login options:
         return runAuthCommand([url, ...rest.slice(1)]);
     }
     if (target === "whoami") {
-        return runAuthWhoamiCommand(rest);
+        return await runAuthWhoamiCommand(rest);
     }
     if (target === "export") {
         return runAuthExportCommand(rest);
@@ -253,22 +253,26 @@ Login options:
     if (target === "status") {
         const resolvedTarget = args[1] ? resolvePlatformIdentifier(args[1]) : undefined;
         const statusTarget = resolvedTarget && /^https?:\/\//.test(resolvedTarget) ? normalizeBaseUrl(resolvedTarget) : resolvedTarget ?? undefined;
-        const platform = statusTarget ?? getCurrentPlatform();
-        if (!platform) {
-            const envRaw = process.env.KWEAVER_BASE_URL?.trim();
-            const envUrl = envRaw ? normalizeBaseUrl(envRaw) : undefined;
+        const active = resolveActivePlatform(statusTarget);
+        if (!active) {
+            console.error("No active platform. Run `kweaver auth login <platform-url>` first.\n" +
+                "  Tip: set KWEAVER_BASE_URL and KWEAVER_TOKEN to use this command without a saved login.");
+            return 1;
+        }
+        if (active.source === "env") {
             const envToken = process.env.KWEAVER_TOKEN?.trim();
-            if (!envUrl || !envToken) {
-                console.error("No active platform. Run `kweaver auth login <platform-url>` first.\n" +
-                    "  Tip: set KWEAVER_BASE_URL and KWEAVER_TOKEN to use this command without a saved login.");
+            if (!envToken) {
+                console.error(`KWEAVER_BASE_URL is set to ${active.url} but KWEAVER_TOKEN is missing. ` +
+                    "Set KWEAVER_TOKEN, or unset KWEAVER_BASE_URL to fall back to the saved session.");
                 return 1;
             }
             console.log(`Config directory: ${getConfigDir()}`);
-            console.log(`Platform:         ${envUrl} (KWEAVER_BASE_URL)`);
+            console.log(`Platform:         ${active.url} (KWEAVER_BASE_URL)`);
             console.log(`Token present:    yes (KWEAVER_TOKEN)`);
             console.log(`Refresh token:    n/a (env)`);
             return 0;
         }
+        const platform = active.url;
         const token = loadTokenConfig(platform);
         if (!token) {
             console.error(statusTarget ? `No saved token for ${statusTarget}.` : "No saved token found.");
@@ -490,11 +494,13 @@ You can specify either the userId (sub claim) or the username (preferred_usernam
     console.log(`Switched to user ${resolvedId}${displayName} on ${platform}`);
     return 0;
 }
-function runAuthWhoamiCommand(args) {
+async function runAuthWhoamiCommand(args) {
     if (args[0] === "--help" || args[0] === "-h") {
         console.log(`kweaver auth whoami [platform-url|alias] [--json]
 
-Show current user identity decoded from the saved id_token.
+Show current user identity. For env-token mode (KWEAVER_TOKEN), the bound
+identity is resolved live from EACP /api/eacp/v1/user/get; for saved sessions
+it is decoded from the local id_token.
 
 Options:
   --json   Output as JSON (machine-readable)`);
@@ -503,40 +509,71 @@ Options:
     const jsonOutput = args.includes("--json");
     const positional = args.find((a) => !a.startsWith("-"));
     const resolved = positional ? resolvePlatformIdentifier(positional) : null;
-    const platform = resolved && /^https?:\/\//.test(resolved) ? normalizeBaseUrl(resolved) : resolved ?? getCurrentPlatform();
-    if (!platform) {
-        const envRaw = process.env.KWEAVER_BASE_URL?.trim();
-        const envUrl = envRaw ? normalizeBaseUrl(envRaw) : undefined;
+    const active = resolveActivePlatform(resolved);
+    if (!active) {
+        console.error("No active platform. Run `kweaver auth login <platform-url>` first.");
+        return 1;
+    }
+    // Env mode requires both URL and token. resolveActivePlatform() returns
+    // source="env" as soon as KWEAVER_BASE_URL is set; if KWEAVER_TOKEN is
+    // missing we cannot inspect identity at all, so guide the user explicitly.
+    if (active.source === "env") {
         const envToken = process.env.KWEAVER_TOKEN?.trim();
-        if (!envUrl || !envToken) {
-            console.error("No active platform. Run `kweaver auth login <platform-url>` first.");
+        if (!envToken) {
+            console.error(`KWEAVER_BASE_URL is set to ${active.url} but KWEAVER_TOKEN is missing. ` +
+                "Set KWEAVER_TOKEN, or unset KWEAVER_BASE_URL to fall back to the saved session.");
             return 1;
         }
         const accessToken = envToken.replace(/^Bearer\s+/i, "");
-        const payload = decodeJwtPayload(accessToken);
+        const envUrl = active.url;
+        const userInfo = await fetchEacpUserInfo(envUrl, accessToken);
+        // Always decode the JWT in env mode so we can render Issuer/Issued/Expires
+        // alongside EACP's Type/Account/Name. The two carry different facts: EACP
+        // tells us *who* the token belongs to (works for opaque tokens too); the
+        // JWT claims tell us *when* it was issued and when it expires (only
+        // available when the token is a JWT). Showing both gives the user the
+        // complete picture without forcing them to pick a mode.
+        const jwtPayload = decodeJwtPayload(accessToken);
         if (jsonOutput) {
-            console.log(JSON.stringify({ platform: envUrl, source: "env", ...(payload ?? {}) }, null, 2));
+            const out = { platform: envUrl, source: "env" };
+            if (userInfo)
+                out.userInfo = userInfo;
+            if (jwtPayload)
+                Object.assign(out, jwtPayload);
+            console.log(JSON.stringify(out, null, 2));
             return 0;
         }
         console.log(`Platform: ${envUrl}`);
         console.log(`Source:   env (KWEAVER_TOKEN)`);
-        if (payload) {
-            const uname = payload.preferred_username ?? payload.name;
+        if (userInfo) {
+            console.log(`Type:     ${userInfo.type}`);
+            console.log(`User ID:  ${userInfo.id}`);
+            if (userInfo.account)
+                console.log(`Account:  ${userInfo.account}`);
+            if (userInfo.name)
+                console.log(`Name:     ${userInfo.name}`);
+        }
+        else if (jwtPayload) {
+            const uname = jwtPayload.preferred_username ?? jwtPayload.name;
             if (uname)
                 console.log(`Username: ${uname}`);
-            console.log(`User ID:  ${payload.sub ?? "(unknown)"}`);
-            console.log(`Issuer:   ${payload.iss ?? "(unknown)"}`);
-            if (payload.iat)
-                console.log(`Issued:   ${new Date(payload.iat * 1000).toISOString()}`);
-            if (payload.exp)
-                console.log(`Expires:  ${new Date(payload.exp * 1000).toISOString()}`);
+            console.log(`User ID:  ${jwtPayload.sub ?? "(unknown)"}`);
         }
         else {
-            console.log(`User info unavailable: opaque access token.`);
-            console.log(`Hint: run \`kweaver auth login ${envUrl}\` to obtain a full session.`);
+            console.log(`User info unavailable: opaque access token and EACP did not respond.`);
+            console.log(`Hint: run \`kweaver auth login ${envUrl}\` to obtain a full session, or check connectivity to ${envUrl}.`);
+        }
+        if (jwtPayload) {
+            if (jwtPayload.iss)
+                console.log(`Issuer:   ${jwtPayload.iss}`);
+            if (jwtPayload.iat)
+                console.log(`Issued:   ${new Date(jwtPayload.iat * 1000).toISOString()}`);
+            if (jwtPayload.exp)
+                console.log(`Expires:  ${new Date(jwtPayload.exp * 1000).toISOString()}`);
         }
         return 0;
     }
+    const platform = active.url;
     const token = loadTokenConfig(platform);
     if (!token) {
         console.error(`No saved token for ${platform}.`);

package/dist/commands/config.js

@@ -1,15 +1,7 @@
 import { listBusinessDomains } from "../api/business-domains.js";
-import { normalizeBaseUrl, withTokenRetry } from "../auth/oauth.js";
-// Resolve platform URL: saved current platform > KWEAVER_BASE_URL (normalized to
-// match what `auth login` writes, so env users share the same platforms/<key>/ dir).
-function resolvePlatformUrl() {
-    const saved = getCurrentPlatform();
-    if (saved)
-        return saved;
-    const env = process.env.KWEAVER_BASE_URL?.trim();
-    return env ? normalizeBaseUrl(env) : undefined;
-}
-import { getCurrentPlatform, loadPlatformBusinessDomain, resolveBusinessDomain, savePlatformBusinessDomain, } from "../config/store.js";
+import { fetchEacpUserInfo, resolveActivePlatform, withTokenRetry } from "../auth/oauth.js";
+import { HttpError } from "../utils/http.js";
+import { loadPlatformBusinessDomain, resolveBusinessDomain, savePlatformBusinessDomain, } from "../config/store.js";
 const HELP = `kweaver config
 
 Subcommands:
@@ -29,20 +21,21 @@ export async function runConfigCommand(args) {
         return 0;
     }
     if (sub === "show") {
-        const platform = resolvePlatformUrl();
-        if (!platform) {
+        const active = resolveActivePlatform();
+        if (!active) {
             console.error("No active platform. Run `kweaver auth login <url>` first.\n  Tip: set KWEAVER_BASE_URL to use this command without a saved login.");
             return 1;
         }
+        const platform = active.url;
         const bd = resolveBusinessDomain(platform);
-        const source = process.env.KWEAVER_BUSINESS_DOMAIN
+        const bdSource = process.env.KWEAVER_BUSINESS_DOMAIN
             ? "env"
             : loadPlatformBusinessDomain(platform)
                 ? "config"
                 : "default";
-        const platformSource = getCurrentPlatform() ? "" : " (KWEAVER_BASE_URL)";
-        console.log(`Platform:        ${platform}${platformSource}`);
-        console.log(`Business Domain: ${bd} (${source})`);
+        const platformSuffix = active.source === "env" ? " (KWEAVER_BASE_URL)" : "";
+        console.log(`Platform:        ${platform}${platformSuffix}`);
+        console.log(`Business Domain: ${bd} (${bdSource})`);
         return 0;
     }
     if (sub === "set-bd") {
@@ -51,27 +44,36 @@ export async function runConfigCommand(args) {
             console.error("Usage: kweaver config set-bd <value>");
             return 1;
         }
-        const platform = resolvePlatformUrl();
-        if (!platform) {
+        const active = resolveActivePlatform();
+        if (!active) {
             console.error("No active platform. Run `kweaver auth login <url>` first.\n  Tip: set KWEAVER_BASE_URL to write the business domain for that platform.");
             return 1;
         }
+        const platform = active.url;
         savePlatformBusinessDomain(platform, value);
-        console.log(`Business domain set to: ${value} (${getCurrentPlatform() ? platform : `${platform} via KWEAVER_BASE_URL`})`);
+        const provenance = active.source === "env" ? `${platform} via KWEAVER_BASE_URL` : platform;
+        console.log(`Business domain set to: ${value} (${provenance})`);
         return 0;
     }
     if (sub === "list-bd") {
-        const platform = resolvePlatformUrl();
-        if (!platform) {
+        const active = resolveActivePlatform();
+        if (!active) {
             console.error("No active platform. Run `kweaver auth login <url>` first.\n  Tip: set KWEAVER_BASE_URL and KWEAVER_TOKEN to use this command without a saved login.");
             return 1;
         }
+        const platform = active.url;
+        let lastAccessToken = "";
+        let lastTlsInsecure;
         try {
-            const rows = await withTokenRetry((token) => listBusinessDomains({
-                baseUrl: platform,
-                accessToken: token.accessToken,
-                tlsInsecure: token.tlsInsecure,
-            }));
+            const rows = await withTokenRetry((token) => {
+                lastAccessToken = token.accessToken;
+                lastTlsInsecure = token.tlsInsecure;
+                return listBusinessDomains({
+                    baseUrl: platform,
+                    accessToken: token.accessToken,
+                    tlsInsecure: token.tlsInsecure,
+                });
+            });
             const currentId = resolveBusinessDomain(platform);
             const payload = {
                 currentId,
@@ -84,7 +86,12 @@ export async function runConfigCommand(args) {
             return 0;
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            // Backend returns 401 + `invalid user_id` when the caller is an app
+            // (service) token with no bound user. Probe EACP to confirm — only swap
+            // the cryptic backend body for a one-liner when we can prove `type:"app"`.
+            // See kweaver-core#263.
+            const friendly = await maybeAppAccountMessage(error, platform, lastAccessToken, lastTlsInsecure);
+            const message = friendly ?? (error instanceof Error ? error.message : String(error));
             console.error(`Failed to list business domains: ${message}`);
             return 1;
         }
@@ -93,3 +100,48 @@ export async function runConfigCommand(args) {
     console.log(HELP);
     return 1;
 }
+/**
+ * Detect "app account hit a user-scoped endpoint" by signature, then confirm
+ * with EACP. Returns a short user-facing message if the call really came from
+ * an app token, otherwise `null` (caller falls back to the original error).
+ *
+ * Two layers of evidence (signature + identity) keep us from probing EACP on
+ * every random failure and from mislabeling real auth problems.
+ */
+async function maybeAppAccountMessage(error, baseUrl, accessToken, tlsInsecure) {
+    // Detect 401 either as a direct HttpError or via the wrapping Error's
+    // message ("Authentication failed (401)..." / "...status 401..."). We don't
+    // rely solely on the `cause` chain because withTokenRetry may attempt a
+    // token refresh and then wrap with the *refresh* error as cause, dropping
+    // the original list-bd HttpError.
+    if (!is401Error(error))
+        return null;
+    if (!accessToken)
+        return null;
+    const info = await fetchEacpUserInfo(baseUrl, accessToken, tlsInsecure);
+    if (info?.type !== "app")
+        return null;
+    return "This command does not support app accounts.";
+}
+/** True if the error or any cause looks like a 401 from the platform. */
+function is401Error(error) {
+    const seen = new Set();
+    const queue = [error];
+    while (queue.length) {
+        const cur = queue.shift();
+        if (!cur || seen.has(cur))
+            continue;
+        seen.add(cur);
+        if (cur instanceof HttpError && cur.status === 401)
+            return true;
+        if (cur instanceof Error) {
+            if (/\b401\b/.test(cur.message))
+                return true;
+            if (cur.cause)
+                queue.push(cur.cause);
+        }
+        if (cur instanceof AggregateError)
+            queue.push(...cur.errors);
+    }
+    return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kweaver-ai/kweaver-sdk",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "description": "KWeaver TypeScript SDK — CLI tool and programmatic API for knowledge networks and Decision Agents.",
   "type": "module",
   "main": "./dist/index.js",