callkaro-cli-unofficial 0.1.0

package/dist/lib/dashboardApi.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DashboardApi = void 0;
+exports.dashboardApi = dashboardApi;
+const config_1 = require("./config");
+const dashboardAuth_1 = require("./dashboardAuth");
+/**
+ * Client for the CallKaro *dashboard* API — a different surface from `/cli/*`.
+ *
+ * ## Two tokens, two halves of the API
+ *
+ * `POST /auth/login` returns two JWTs and they are not interchangeable. Probed
+ * every route below with both on 1 October 2026:
+ *
+ *   | token                        | claims              | serves                                                     |
+ *   |------------------------------|---------------------|------------------------------------------------------------|
+ *   | `auth-token` (response body) | `{user:{id,email}}` | `GET /v2/agents/` only, as `Authorization: Bearer`          |
+ *   | `access_token` (Set-Cookie)  | `{id,isAdmin,…}`    | `/auth/*`, `/v1/*`, `/kpi-manager`, `/pending-tasks`,      |
+ *   |                              |                     | `/phone-number/`, as `Cookie: access_token=…`               |
+ *
+ * Each is rejected by the other's routes with `401`. The comment on each method
+ * says which token it uses, because getting this wrong produces an unexplained
+ * `Unauthorised!` rather than anything diagnostic.
+ *
+ * The `ck_` token from `/cli/auth/login` is rejected by all of these, so nothing
+ * here may be called through `requireApi()`.
+ *
+ * Everything on this surface is undocumented and can change without notice.
+ */
+class DashboardApi {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+    /**
+     * One place that adds auth, so no caller can forget it. `requireDashboard()`
+     * runs per request rather than once at construction: it is what proves the
+     * stored 24h token is still valid, and a long-lived client must not outlive it.
+     */
+    async request(method, path, body) {
+        const { token, sessionToken } = (0, dashboardAuth_1.requireDashboard)();
+        const headers = { 'Content-Type': 'application/json' };
+        if (usesCookieAuth(path)) {
+            headers.Cookie = `access_token=${sessionToken}`;
+        }
+        else {
+            headers.Authorization = `Bearer ${token}`;
+        }
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}${path}`, {
+                method,
+                headers,
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            throw new Error(`Cannot reach ${this.baseUrl} (${err.message})`);
+        }
+        const text = await res.text();
+        let data;
+        try {
+            data = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            data = { msg: text.slice(0, 200) };
+        }
+        if (!res.ok) {
+            throw new Error(data?.msg || data?.message || `Request failed (${res.status})`);
+        }
+        return data;
+    }
+    /**
+     * `GET /v2/agents/` — the one route that wants the body token as a bearer.
+     * The only place `agentFolders` is exposed, which `/cli/agents` does not return.
+     */
+    agentsWithFolders() { return this.request('GET', '/v2/agents/'); }
+    /**
+     * Bootstrap payload from `/auth/get-user`.
+     *
+     * Worth its own method because it is the one route carrying the server's own
+     * model and provider catalogues, which `ENUMS` validation mirrors. Also returns
+     * `agents` and `phoneNumbers`, which is why it is worth calling rather than
+     * just `/auth/get-user` for the identity.
+     */
+    getUser() { return this.request('GET', '/auth/get-user'); }
+    // --- KPI manager ----------------------------------------------------------
+    /** Agent ids the account is scored on. */
+    kpiAgents() { return this.request('GET', '/kpi-manager'); }
+    /** Metric history for a set of agents. Params: agentIds (csv), startDate, endDate. */
+    kpiHistory(query = {}) {
+        return this.request('GET', `/kpi-manager/metrics-history${qs(query)}`);
+    }
+    /** The pending-task board. Large — always page it client-side or with --limit. */
+    pendingTasks(query = {}) {
+        return this.request('GET', `/pending-tasks${qs(query)}`);
+    }
+    teamMembers() { return this.request('GET', '/feedback/users/team-members'); }
+    // --- KPI board writes -----------------------------------------------------
+    //
+    // Routes, bodies and the column set below were read out of the dashboard's own
+    // bundle rather than guessed — this surface is undocumented, and a wrong guess
+    // is a 404 that looks like a broken CLI. Two things that reading settled, and
+    // which are easy to get wrong:
+    //
+    //   * There is no delete for a card. The board retires one by moving it to the
+    //     `rejected` column. The only DELETE is an attachment, by URL.
+    //   * PATCH /pending-tasks/:taskId writes `description` and nothing else.
+    //     cause / recommendedFix / severity are settable at create and are not
+    //     editable afterwards through this surface.
+    /** Create a card. `cause` is the only field the server treats as required. */
+    createPendingTask(body) {
+        return this.request('POST', '/pending-tasks', body);
+    }
+    /** Edit a card's description. The dashboard PATCHes this field alone. */
+    updatePendingTask(taskId, body) {
+        return this.request('PATCH', `/pending-tasks/${encodeURIComponent(taskId)}`, body);
+    }
+    /**
+     * Move a card to a column, optionally positioning it between two siblings.
+     * `beforeTaskId` / `afterTaskId` may be null to append. Omit both to let the
+     * server place it, which is what the dashboard does for a plain column change.
+     */
+    movePendingTask(taskId, columnId, order) {
+        return this.request('POST', `/pending-tasks/${encodeURIComponent(taskId)}/move`, {
+            columnId,
+            beforeTaskId: order?.beforeTaskId ?? null,
+            afterTaskId: order?.afterTaskId ?? null,
+        });
+    }
+    /** Append a comment. Returns the updated task. */
+    commentOnPendingTask(taskId, text) {
+        return this.request('POST', `/pending-tasks/${encodeURIComponent(taskId)}/comments`, { text });
+    }
+    /**
+     * Assign one or more cards. The response is `{results:[{success,error,queued}]}`
+     * per assignment, so a partial failure is normal — callers must check each.
+     */
+    savePendingAssignments(assignments) {
+        return this.request('POST', '/pending-tasks/save', { assignments });
+    }
+    /** Detach one attachment, identified by its URL. */
+    deletePendingTaskAttachment(taskId, url) {
+        return this.request('DELETE', `/pending-tasks/${encodeURIComponent(taskId)}/attachments`, { url });
+    }
+    // --- KPI manager writes ---------------------------------------------------
+    /** One agent's KPI Manager configuration, or 404 when it has none. */
+    kpiAgentConfig(agentId) {
+        return this.request('GET', `/kpi-manager/${encodeURIComponent(agentId)}`);
+    }
+    /**
+     * Set the target and the RCA config. `rca_model` and `rca_prompt` are sent
+     * together with the metric, and the dashboard sends whatever is in its form —
+     * so read the current config first and send it back, or an omitted field is
+     * cleared rather than left alone.
+     */
+    setKpiAgentConfig(agentId, body) {
+        return this.request('PUT', `/kpi-manager/${encodeURIComponent(agentId)}`, body);
+    }
+    /** Kick off an RCA run for one agent. `filters` scopes the date range. */
+    runKpiRca(agentId, filters) {
+        return this.request('POST', `/kpi-manager/${encodeURIComponent(agentId)}/rca/run-now`, { filters });
+    }
+    // --- Call analyzers -------------------------------------------------------
+    listAnalyzers() { return this.request('GET', '/v1/call-analyzers'); }
+    // --- Audit reports (dashboard side) ---------------------------------------
+    /** Distinct from /cli/audit-strategies: these are completed run reports. */
+    listAuditReports(query = {}) {
+        return this.request('GET', `/v1/audit-reports${qs(query)}`);
+    }
+    listAuditStrategies(query = {}) {
+        return this.request('GET', `/v1/audit-reports/strategies${qs(query)}`);
+    }
+}
+exports.DashboardApi = DashboardApi;
+/** Build a client bound to the configured backend. */
+function dashboardApi() {
+    return new DashboardApi((0, config_1.backendUrl)());
+}
+/**
+ * Which of the two tokens a route wants. Cookie-authenticated by default because
+ * that is the overwhelming majority; only `/v2/agents/` opted out of it.
+ *
+ * Kept as one function so the rule is auditable in one place. Adding a `/v2/*`
+ * route means checking this against a live probe first — the backend does not
+ * accept either token everywhere, and guessing produces an unexplained 401.
+ */
+function usesCookieAuth(path) {
+    return !path.startsWith('/v2/agents');
+}
+/** `?a=1&b=2`, skipping undefined and empty. Mirrors the one in api.ts. */
+function qs(params) {
+    const parts = Object.entries(params)
+        .filter(([, v]) => v !== undefined && v !== '')
+        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+    return parts.length ? `?${parts.join('&')}` : '';
+}

package/dist/lib/dashboardAuth.js

@@ -0,0 +1,339 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeJwt = decodeJwt;
+exports.msUntilExpiry = msUntilExpiry;
+exports.dashboardLogin = dashboardLogin;
+exports.saveDashboard = saveDashboard;
+exports.dashboardSession = dashboardSession;
+exports.hasDashboard = hasDashboard;
+exports.forgetDashboard = forgetDashboard;
+exports.requireDashboard = requireDashboard;
+exports.expiryLabel = expiryLabel;
+exports.dashboardLoginCommand = dashboardLoginCommand;
+exports.dashboardWhoamiCommand = dashboardWhoamiCommand;
+exports.dashboardProbeCommand = dashboardProbeCommand;
+exports.refreshModelCatalog = refreshModelCatalog;
+exports.dashboardLogoutCommand = dashboardLogoutCommand;
+const prompts_1 = __importDefault(require("prompts"));
+const ui_1 = require("./ui");
+const config_1 = require("./config");
+/**
+ * Pull the `access_token` JWT out of the Set-Cookie headers.
+ *
+ * The header is a comma-joined list of several cookies and each is repeated for
+ * three domains, with three leading entries that clear the cookie (empty value,
+ * epoch expiry). Only the populated one carries a JWT.
+ */
+function sessionTokenFrom(response) {
+    const raw = typeof response.headers.getSetCookie === 'function'
+        ? response.headers.getSetCookie()
+        : [response.headers.get('set-cookie') || ''];
+    const jwt = /eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/;
+    // Iterate the headers, not the joined string: `for...of` over a string yields
+    // characters, which silently never matches.
+    for (const header of raw) {
+        const match = header.match(/access_token=([^;,\s]*)/);
+        if (match && jwt.test(match[1]))
+            return match[1];
+    }
+    return undefined;
+}
+/** Decode a JWT payload without verifying it. Safe: we only read `exp`/`email`. */
+function decodeJwt(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return undefined;
+    try {
+        return JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** ms until expiry, or undefined if the token has no readable `exp`. */
+function msUntilExpiry(token) {
+    const exp = decodeJwt(token)?.exp;
+    return typeof exp === 'number' ? exp * 1000 - Date.now() : undefined;
+}
+/**
+ * Password sign-in against the dashboard, exactly as the web form does it.
+ * The password is used here and then discarded — it is never stored.
+ *
+ * Two JWTs come back and both are kept, because they authorise different routes:
+ * `auth-token` in the body serves `GET /v2/agents/` as a bearer, while
+ * `access_token` in the Set-Cookie serves `/auth/*`, `/v1/*`, `/kpi-manager`,
+ * `/pending-tasks` and `/phone-number/` as a cookie. Verified by probing every
+ * route with each token: each is rejected by the other's routes.
+ */
+async function dashboardLogin(email, password) {
+    const res = await fetch(`${(0, config_1.backendUrl)()}/auth/login`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email, password }),
+    });
+    const text = await res.text();
+    let data;
+    try {
+        data = text ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new Error(`Login returned a non-JSON response (HTTP ${res.status}).`);
+    }
+    if (!res.ok) {
+        throw new Error(data.msg || `Login failed (HTTP ${res.status})`);
+    }
+    const token = data['auth-token'];
+    if (!token)
+        throw new Error('Login succeeded but returned no auth-token.');
+    const sessionToken = sessionTokenFrom(res);
+    if (!sessionToken) {
+        // Almost always a proxy stripping Set-Cookie. Worth naming: without it, half
+        // the dashboard (`/kpi-manager`, `/v1/*`, `/pending-tasks`) will 401 later.
+        throw new Error('Login succeeded but no access_token cookie came back, so the dashboard session is incomplete.\n' +
+            '  Without it, `cku kpi` and `cku analyzers` will fail with "Unauthorised!".\n' +
+            '  Usually a proxy or browser extension stripping Set-Cookie on /auth/login.');
+    }
+    const payload = decodeJwt(token) || {};
+    return {
+        email: payload.user?.email || data.user?.email || email,
+        token,
+        sessionToken,
+        userId: data.id || data.user?.id || payload.user?.id || '',
+        /** Precomputed so the UI can show "expires in 23h" without decoding each time. */
+        expiresAt: typeof payload.exp === 'number' ? new Date(payload.exp * 1000).toISOString() : undefined,
+        savedAt: new Date().toISOString(),
+    };
+}
+// --- account binding -------------------------------------------------------
+/** Store on the account, keeping whatever else it holds (notably the `ck_` token). */
+function saveDashboard(email, session) {
+    return (0, config_1.saveDashboardSession)(email, session);
+}
+function dashboardSession(email) {
+    if (!email)
+        return undefined;
+    return (0, config_1.loadAccount)((0, config_1.slugFor)(email)).dashboard;
+}
+/** Does this account hold a dashboard session locally? A hint, not a guarantee. */
+function hasDashboard(email) {
+    return Boolean(email && (0, config_1.loadAccount)((0, config_1.slugFor)(email)).dashboard?.token);
+}
+function forgetDashboard(email) {
+    return (0, config_1.clearDashboardSession)(email);
+}
+// --- the auth gate ---------------------------------------------------------
+/**
+ * The restricted-endpoint gate, the counterpart to session.ts's `requireApi()`.
+ * Deliberately separate: no `/cli/*` command ever depends on this credential,
+ * and no dashboard command depends on the `ck_` token.
+ *
+ * Returns BOTH tokens, because the two halves of the dashboard need different
+ * ones. `dashboardApi.ts` picks per route; callers should not choose.
+ *
+ * There is nothing to refresh — the tokens last 24h and the backend has no
+ * refresh endpoint (confirmed by capture). So this checks expiry locally and
+ * fails with the concrete next command, rather than pretending it can renew.
+ */
+function requireDashboard() {
+    const slug = (0, config_1.activeAccount)();
+    const email = slug ? (0, config_1.loadAccount)(slug).email : undefined;
+    const session = dashboardSession(email);
+    if (!session?.token) {
+        throw new Error(`No dashboard session for ${email || 'the account in effect'}.\n` +
+            '  Dashboard endpoints (/auth/*, /v1/*, /kpi-manager, /pending-tasks) need a dashboard login, not a ck_ token.\n' +
+            '  Run: cku dashboard login');
+    }
+    if (!session.sessionToken) {
+        // A session stored before the two-token split. Re-issuing is the only fix;
+        // the cookie token cannot be derived from the body token.
+        throw new Error(`The stored dashboard session for ${email} is incomplete — it predates the two-token fix.\n` +
+            '  /auth/login returns a separate access_token cookie that the dashboard routes require.\n' +
+            '  Run: cku dashboard login');
+    }
+    // Expiry is read off the cookie token: it is the one that guards every route
+    // except /v2/agents/, so it is the one that matters for a session's lifetime.
+    const left = msUntilExpiry(session.sessionToken);
+    if (left !== undefined && left <= 0) {
+        const when = new Date(Date.now() + left).toLocaleString('en-US');
+        throw new Error(`Dashboard session for ${email} expired ${when}.\n` +
+            '  There is no refresh endpoint — the token lives 24h and must be re-issued.\n' +
+            '  Run: cku dashboard login');
+    }
+    return { token: session.token, sessionToken: session.sessionToken, email: session.email };
+}
+/** Human phrasing for the expiry, used by `accounts` and `dashboard whoami`. */
+function expiryLabel(token) {
+    const left = msUntilExpiry(token);
+    if (left === undefined)
+        return 'unknown';
+    if (left <= 0)
+        return 'expired';
+    const hours = left / 3_600_000;
+    if (hours < 1)
+        return `${Math.round(left / 60_000)}m`;
+    if (hours < 48)
+        return `${Math.round(hours)}h`;
+    return `${Math.round(hours / 24)}d`;
+}
+// --- commands --------------------------------------------------------------
+/** `cku dashboard login` — the browser's email+password flow, minus the browser. */
+async function dashboardLoginCommand(opts) {
+    try {
+        const answers = await (0, prompts_1.default)([
+            { type: opts.email ? null : 'text', name: 'email', message: 'Email' },
+            { type: 'password', name: 'password', message: 'Password' },
+        ], { onCancel: () => process.exit(1) });
+        const email = opts.email || answers.email;
+        const password = answers.password;
+        if (!email || !password)
+            return (0, ui_1.handleError)(new Error('Email and password are required'));
+        const session = await dashboardLogin(email, password);
+        saveDashboard(email, session);
+        (0, ui_1.success)(`Dashboard session stored for ${session.email} (expires in ${expiryLabel(session.token)}).`);
+        (0, ui_1.info)('  Your password was not stored. The token cannot be refreshed, so you re-run');
+        (0, ui_1.info)('  this command once it expires.');
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+/** `cku dashboard whoami` — prove the stored session still works. */
+async function dashboardWhoamiCommand(opts) {
+    try {
+        const { sessionToken, email } = requireDashboard();
+        const res = await fetch(`${(0, config_1.backendUrl)()}/auth/get-user`, {
+            headers: { Cookie: `access_token=${sessionToken}` },
+        });
+        const text = await res.text();
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}: ${text.slice(0, 160)}`);
+        const data = text ? JSON.parse(text) : {};
+        if (opts.json)
+            return void console.log(JSON.stringify(data, null, 2));
+        (0, ui_1.success)(`Dashboard session valid for ${data.email || email} (expires in ${expiryLabel(sessionToken)}).`);
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+/**
+ * `cku dashboard probe` — GET each dashboard route and print status + shape.
+ * Read-only. Each row is tried with BOTH stored tokens, because the backend does
+ * not accept either one everywhere and the only way to know which is which is to
+ * see which one answers.
+ */
+async function dashboardProbeCommand() {
+    const PATHS = [
+        '/auth/get-user',
+        '/v2/agents/',
+        '/v1/call-analyzers',
+        '/v1/audit-reports',
+        '/v1/audit-reports/strategies',
+        '/kpi-manager',
+        '/pending-tasks',
+        '/feedback/users/team-members',
+        '/phone-number/',
+    ];
+    try {
+        const { token, sessionToken, email } = requireDashboard();
+        const base = (0, config_1.backendUrl)();
+        const send = (path, which) => fetch(`${base}${path}`, {
+            headers: which === 'bearer' ? { Authorization: `Bearer ${token}` } : { Cookie: `access_token=${sessionToken}` },
+        });
+        (0, ui_1.info)(`${email} · expires in ${expiryLabel(sessionToken)} · ${base}\n`);
+        for (const path of PATHS) {
+            const results = [];
+            let shape = '';
+            for (const which of ['bearer', 'cookie']) {
+                let status = 'ERR';
+                try {
+                    const res = await send(path, which);
+                    status = res.status;
+                    const text = await res.text();
+                    try {
+                        const d = JSON.parse(text);
+                        const kind = Array.isArray(d) ? `array[${d.length}]` : typeof d;
+                        const keys = d && typeof d === 'object' && !Array.isArray(d) ? Object.keys(d).slice(0, 6).join(',') : '';
+                        shape = `${kind}${keys ? ` {${keys}}` : ''}`;
+                    }
+                    catch {
+                        shape = text.slice(0, 40).replace(/\s+/g, ' ');
+                    }
+                }
+                catch (e) {
+                    shape = e.message;
+                }
+                results.push(`${which}=${String(status).padEnd(4)}`);
+            }
+            // Only print the body shape when one of the two actually worked, so a
+            // rejected 401 doesn't masquerade as the route's shape.
+            const worked = results.some((r) => r.includes('200'));
+            (0, ui_1.info)(`  ${path.padEnd(34)} ${results.join('  ')} ${worked ? shape : ''}`);
+        }
+        (0, ui_1.info)('\nAll calls above are GETs. Nothing was modified.');
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+/**
+ * Load the server's own catalogues into `ENUMS` and the voice/transcriber
+ * provider tables, so validation and `cku voices` reflect what the backend
+ * actually serves instead of the built-in copies.
+ *
+ * Covers three tables, all of which had drifted from the server in both
+ * directions: LLM models per slot, TTS models per provider, and STT models per
+ * provider (including one provider, Groq, the server no longer lists at all).
+ *
+ * Best-effort by design: without a dashboard session, or if the call fails, the
+ * built-in lists stay in place and the command proceeds. A validation list is
+ * not worth failing an update over.
+ *
+ * Exported from here rather than from a command because `agents update`,
+ * `chat-agents update`, `voices` and `transcribers` all need it, and none should
+ * re-implement the fallback.
+ */
+async function refreshModelCatalog() {
+    const { dashboardApi } = require('./dashboardApi');
+    const { applyLiveModels } = require('./agentUpdate');
+    const { applyLiveCatalog } = require('./catalog');
+    try {
+        const res = await dashboardApi().getUser();
+        if (!res?.catalogs)
+            return false;
+        applyLiveCatalog(res.catalogs);
+        return applyLiveModels(res.catalogs);
+    }
+    catch {
+        return false; // no dashboard session, or the route moved
+    }
+}
+/** `cku dashboard logout` — forget the dashboard session, keep the ck_ token. */
+async function dashboardLogoutCommand(opts) {
+    try {
+        const slug = (0, config_1.activeAccount)();
+        const email = slug ? (0, config_1.loadAccount)(slug).email : undefined;
+        if (!hasDashboard(email))
+            return void (0, ui_1.info)('No dashboard session stored for this account.');
+        if (!opts.yes) {
+            const { ok } = await (0, prompts_1.default)({
+                type: 'confirm',
+                name: 'ok',
+                message: `Forget the dashboard session for ${email}? (your ck_ token is kept)`,
+                initial: false,
+            });
+            if (!ok)
+                return void (0, ui_1.info)('Cancelled.');
+        }
+        if (email && forgetDashboard(email))
+            (0, ui_1.success)(`Dashboard session removed for ${email}.`);
+        else
+            (0, ui_1.fail)('Nothing to remove.');
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}

package/dist/lib/dbFields.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dbManagedFields = dbManagedFields;
+exports.dbManagedFieldsError = dbManagedFieldsError;
+/**
+ * Fields the database manages itself. A payload carrying them either 500s on
+ * the server (CastError on a bad _id) or silently lies about identity — so we
+ * reject them client-side with an explanation an LLM or human can act on.
+ */
+const DB_MANAGED = ['_id', '__v', 'createdAt', 'updatedAt', 'userId', 'agentId'];
+/** Returns the offending keys found at the top level of a payload. */
+function dbManagedFields(obj) {
+    if (!obj || typeof obj !== 'object')
+        return [];
+    return DB_MANAGED.filter((k) => k in obj);
+}
+/**
+ * Human/LLM-actionable error message for rejected payloads.
+ *
+ * Error text is written to be read by an LLM as well as a human — the CLI is
+ * driven by the installed skill pack, and an agent has to act on the message.
+ * Name the offending fields, explain why, give the concrete next command.
+ */
+function dbManagedFieldsError(found, where = 'payload') {
+    return (`The ${where} contains database-managed field(s): ${found.join(', ')}. ` +
+        `These are created by MongoDB/the server itself (_id, createdAt, updatedAt, __v) ` +
+        `or derived from your login (userId, agentId) — remove them and retry. ` +
+        `Tip: JSON from \`cku agents get --json\` includes them; strip before reuse, ` +
+        `or use \`cku agents export\` which is already sanitized.`);
+}