callkaro-cli-unofficial 0.1.0

package/dist/commands/agentVersions.js

@@ -0,0 +1,228 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentsCloneVersionCommand = agentsCloneVersionCommand;
+exports.agentsPublishCommand = agentsPublishCommand;
+exports.agentsToggleActiveCommand = agentsToggleActiveCommand;
+exports.agentsAbCommand = agentsAbCommand;
+exports.agentsAbAdvancedCommand = agentsAbAdvancedCommand;
+const session_1 = require("../lib/session");
+const ui_1 = require("../lib/ui");
+const versions_1 = require("../lib/versions");
+const agentUpdate_1 = require("../lib/agentUpdate");
+const setJson_1 = require("./setJson");
+/** Keys a clone may override. Anything else is rejected before the request. */
+const CLONE_OVERRIDE_KEYS = new Set([
+    'transcriber',
+    'secondary_transcriber',
+    'voice_configuration',
+    'secondary_voice_configuration',
+    'silence_language',
+]);
+/** `cku agents clone-version <agentId> --versions <src> --name <n> --prompt-type <0-3> --language <code>` */
+async function agentsCloneVersionCommand(agentId, opts) {
+    const api = (0, session_1.requireApi)();
+    const sourceVersionId = (0, versions_1.firstVersion)(opts.versions);
+    if (!sourceVersionId)
+        return (0, ui_1.handleError)(new Error('--versions <sourceVersionId> is required'));
+    if (!opts.name?.trim())
+        return (0, ui_1.handleError)(new Error('--name <versionName> is required'));
+    const promptType = Number(opts.promptType);
+    if (!Number.isInteger(promptType) || promptType < 0 || promptType > 3) {
+        return (0, ui_1.handleError)(new Error('--prompt-type must be 0, 1, 2, or 3'));
+    }
+    const language = opts.language?.trim();
+    if (!language)
+        return (0, ui_1.handleError)(new Error('--language <code> is required'));
+    if (!agentUpdate_1.ENUMS.default_language.includes(language)) {
+        return (0, ui_1.handleError)(new Error(`Invalid --language value: "${language}"\n  allowed: ${agentUpdate_1.ENUMS.default_language.join(', ')}`));
+    }
+    try {
+        let overrides = {};
+        if (opts.set) {
+            let parsed;
+            try {
+                parsed = (0, setJson_1.readSetJson)(opts.set);
+            }
+            catch (err) {
+                return (0, ui_1.handleError)(err);
+            }
+            const unsupported = Object.keys(parsed).filter((key) => !CLONE_OVERRIDE_KEYS.has(key));
+            if (unsupported.length) {
+                return (0, ui_1.handleError)(new Error(`Unsupported clone override(s): ${unsupported.join(', ')}\n  allowed: ${[...CLONE_OVERRIDE_KEYS].join(', ')}`));
+            }
+            overrides = (0, agentUpdate_1.preparePatch)(parsed).patch;
+        }
+        const res = await api.cloneAgentVersion(agentId, sourceVersionId, {
+            ...overrides,
+            versionName: opts.name.trim(),
+            systempromptType: promptType,
+            default_language: language,
+        });
+        if (opts.json)
+            return void console.log(JSON.stringify(res, null, 2));
+        (0, ui_1.success)(res.msg || 'Agent version cloned.');
+        if (res.newVersion?._id)
+            (0, ui_1.info)(`  id:   ${res.newVersion._id}`);
+        if (res.newVersion?.versionName)
+            (0, ui_1.info)(`  name: ${res.newVersion.versionName}`);
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+async function agentsPublishCommand(agentId, opts) {
+    const api = (0, session_1.requireApi)();
+    const versionId = (0, versions_1.firstVersion)(opts.versions);
+    if (!versionId)
+        return (0, ui_1.handleError)(new Error('--versions <versionId> is required'));
+    try {
+        const res = await api.publishVersion(agentId, versionId);
+        (0, ui_1.success)(res.msg || `Published version ${versionId}.`);
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+async function agentsToggleActiveCommand(agentId, opts) {
+    const api = (0, session_1.requireApi)();
+    const versionId = (0, versions_1.firstVersion)(opts.versions);
+    if (!versionId)
+        return (0, ui_1.handleError)(new Error('--versions <versionId> is required'));
+    try {
+        const res = await api.toggleVersionActive(agentId, versionId);
+        (0, ui_1.success)(res.msg || `Toggled version ${versionId}.`);
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+/** Parse `--versions "v1=60,v2=40"` into [{versionId, ratio}], validating the split. */
+function parseWeightedVersions(spec) {
+    const parts = spec.split(',').map((s) => s.trim()).filter(Boolean);
+    const out = parts.map((p) => {
+        const [versionId, ratioStr] = p.split('=').map((x) => (x || '').trim());
+        const ratio = Number(ratioStr);
+        if (!versionId || !ratioStr || isNaN(ratio) || ratio < 0) {
+            throw new Error(`Bad entry "${p}" — use versionId=ratio, e.g. 68d...=60`);
+        }
+        return { versionId, ratio };
+    });
+    if (out.length < 2)
+        throw new Error('A/B testing needs at least 2 versions');
+    // Two entries for one version would send 100% of traffic to it while the CLI
+    // reports a two-way split, so refuse it rather than apply a silent no-op.
+    const seen = new Set();
+    for (const v of out) {
+        if (seen.has(v.versionId)) {
+            throw new Error(`Version ${v.versionId} appears twice in --versions.\n` +
+                '  Each version may appear once, or the split does nothing.');
+        }
+        seen.add(v.versionId);
+    }
+    const total = out.reduce((sum, v) => sum + v.ratio, 0);
+    // Exact comparison is right: every ratio must be an integer percentage, so a
+    // fractional total means the user mistyped something.
+    if (total !== 100)
+        throw new Error(`Ratios must sum to 100 (got ${total})`);
+    return out;
+}
+async function agentsAbCommand(agentId, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        if (opts.disable) {
+            await api.disableAbTest(agentId);
+            return void (0, ui_1.success)(`A/B testing disabled for agent ${agentId}.`);
+        }
+        if (!opts.versions) {
+            return (0, ui_1.handleError)(new Error('Provide --versions "v1=60,v2=40" (ratios summing to 100), or --disable'));
+        }
+        let weighted;
+        try {
+            weighted = parseWeightedVersions(opts.versions);
+        }
+        catch (e) {
+            return (0, ui_1.handleError)(e);
+        }
+        await api.enableAbTest(agentId, weighted);
+        (0, ui_1.success)(`A/B testing enabled for agent ${agentId}:`);
+        weighted.forEach((v) => (0, ui_1.info)(`  ${v.versionId} → ${v.ratio}%`));
+        (0, ui_1.info)('Note: versions must be active (`cku agents toggle-active`) to serve traffic.');
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+/** Human-readable one-liner per rule, for --show and confirmation output. */
+function describeRule(r) {
+    const head = r.kind === 'else' ? 'ELSE' : `${r.kind.toUpperCase()} ${r.condition}`;
+    const targets = (r.targets || [])
+        .map((t) => `${r.returnType === 'version' ? t.versionId : t.language}=${t.ratio ?? 100}%`)
+        .join(', ');
+    return `${head}  →  ${r.returnType}: ${targets}`;
+}
+/**
+ * `cku agents ab-advanced <agentId> --rules '<json>' | --rules @rules.json | --show | --disable`
+ *
+ * Rule-based A/B: an ordered if/elseif/else chain evaluated against call
+ * metadata. `returnType: "version"` pins the version; `"language"` overrides
+ * only the language. Full semantic validation happens server-side.
+ */
+async function agentsAbAdvancedCommand(agentId, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        if (opts.disable) {
+            await api.updateAgent(agentId, undefined, { advancedAbTestEnabled: false });
+            return void (0, ui_1.success)(`Advanced A/B testing disabled for agent ${agentId}.`);
+        }
+        if (opts.show) {
+            const { agent } = await api.getAgent(agentId);
+            if (opts.json) {
+                return void console.log(JSON.stringify({ advancedAbTestEnabled: !!agent.advancedAbTestEnabled, advancedAbTestRules: agent.advancedAbTestRules || [] }, null, 2));
+            }
+            (0, ui_1.info)(`Advanced A/B: ${agent.advancedAbTestEnabled ? 'ENABLED' : 'disabled'}`);
+            (agent.advancedAbTestRules || []).forEach((r) => (0, ui_1.info)(`  ${describeRule(r)}`));
+            return;
+        }
+        if (!opts.rules) {
+            return (0, ui_1.handleError)(new Error('Provide --rules \'<json array>\' or --rules @rules.json (or --show / --disable).\n' +
+                'Rule shape: {"kind":"if|elseif|else","condition":"(metadata.age > 24)",' +
+                '"returnType":"version|language","targets":[{"versionId":"...","ratio":50}]}'));
+        }
+        let rules;
+        try {
+            rules = (0, setJson_1.readSetJson)(opts.rules);
+        }
+        catch (e) {
+            return (0, ui_1.handleError)(e);
+        }
+        // Accept `--show --json` output as-is, so edit round-trips need no jq.
+        if (!Array.isArray(rules) && rules && Array.isArray(rules.advancedAbTestRules)) {
+            rules = rules.advancedAbTestRules;
+        }
+        if (!Array.isArray(rules) || rules.length === 0) {
+            return (0, ui_1.handleError)(new Error('--rules must be a non-empty JSON ARRAY of rule objects'));
+        }
+        // Light structural checks for fast feedback; the server does the full
+        // semantic validation (expressions, version ownership, ratio sums).
+        if (rules[0]?.kind !== 'if')
+            return (0, ui_1.handleError)(new Error('The first rule must have "kind": "if"'));
+        for (const r of rules) {
+            if (!['if', 'elseif', 'else'].includes(r?.kind)) {
+                return (0, ui_1.handleError)(new Error(`Unknown rule kind "${r?.kind}" — use if | elseif | else`));
+            }
+            if (!['version', 'language'].includes(r?.returnType)) {
+                return (0, ui_1.handleError)(new Error(`returnType must be "version" or "language" (got "${r?.returnType}")`));
+            }
+            if (!Array.isArray(r?.targets) || r.targets.length === 0) {
+                return (0, ui_1.handleError)(new Error(`Every rule needs a non-empty "targets" array (${r.kind})`));
+            }
+        }
+        await api.updateAgent(agentId, undefined, { advancedAbTestEnabled: true, advancedAbTestRules: rules });
+        (0, ui_1.success)(`Advanced A/B testing enabled for agent ${agentId}:`);
+        rules.forEach((r) => (0, ui_1.info)(`  ${describeRule(r)}`));
+        (0, ui_1.info)('Rules run before ratio A/B, only when the call does not pin a version.');
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}

package/dist/commands/agents.js

@@ -0,0 +1,455 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.preparePatch = void 0;
+exports.agentsListCommand = agentsListCommand;
+exports.agentsGetCommand = agentsGetCommand;
+exports.agentsVersionsCommand = agentsVersionsCommand;
+exports.agentsExportCommand = agentsExportCommand;
+exports.agentsImportCommand = agentsImportCommand;
+exports.agentsCreateCommand = agentsCreateCommand;
+exports.agentsUpdateCommand = agentsUpdateCommand;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const prompts_1 = __importDefault(require("prompts"));
+const session_1 = require("../lib/session");
+const ui_1 = require("../lib/ui");
+const versions_1 = require("../lib/versions");
+const agentUpdate_1 = require("../lib/agentUpdate");
+Object.defineProperty(exports, "preparePatch", { enumerable: true, get: function () { return agentUpdate_1.preparePatch; } });
+const dashboardAuth_1 = require("../lib/dashboardAuth");
+const agentImport_1 = require("../lib/agentImport");
+const dbFields_1 = require("../lib/dbFields");
+const jsonInput_1 = require("./jsonInput");
+const NOT_SET = 'Not Selected';
+/** Match the UI's "MMMM D, YYYY" created-at format. */
+function formatDate(value) {
+    if (!value)
+        return 'N/A';
+    const d = new Date(value);
+    return isNaN(d.getTime()) ? 'N/A' : d.toLocaleDateString('en-US', { month: 'long', day: 'numeric', year: 'numeric' });
+}
+/** UI shows 'live' → "Live", anything else → "In Progress". */
+const statusLabel = (status) => (status === 'live' ? 'Live' : 'In Progress');
+/** Read `.phoneNumber` off a populated phone ref; bare IDs/strings → ''. */
+const phoneOf = (ref) => ref && typeof ref === 'object' ? (ref.phoneNumber || '') : '';
+const outboundPhone = (a) => phoneOf(a.outboundPhoneNumber) || NOT_SET;
+function inboundPhones(a) {
+    const list = Array.isArray(a.inboundPhoneNumbers) ? a.inboundPhoneNumbers : [];
+    const nums = list.map(phoneOf).filter(Boolean);
+    return nums.length ? nums.join(', ') : NOT_SET;
+}
+/** Published versions like the UI: "{language}-{versionName}", comma-joined. */
+function publishedVersions(a) {
+    const list = Array.isArray(a.publishedVersionsByLanguage) ? a.publishedVersionsByLanguage : [];
+    const labels = list
+        .map((v) => {
+        const ver = v.versionId;
+        if (!ver || !ver.versionName)
+            return '';
+        return ver.default_language ? `${ver.default_language}-${ver.versionName}` : ver.versionName;
+    })
+        .filter(Boolean);
+    return labels.length ? labels.join('\n') : 'No Published Versions';
+}
+async function agentsListCommand(opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        const { agents } = await api.listAgents();
+        const list = agents || [];
+        // --file: persist the raw agent data as JSON for scripting/backup.
+        if (opts.file) {
+            (0, fs_1.writeFileSync)(opts.file, JSON.stringify(list, null, 2));
+            return void (0, ui_1.success)(`Saved ${list.length} agent(s) to ${opts.file}`);
+        }
+        if (opts.json)
+            return void console.log(JSON.stringify(list, null, 2));
+        if (list.length === 0)
+            return void (0, ui_1.info)('No agents yet.');
+        // Columns mirror the web dashboard (V2Agents.jsx), minus the Action column.
+        (0, ui_1.table)(['AGENT NAME', 'ID', 'STATUS', 'OUTBOUND', 'INBOUND', 'PUBLISHED VERSIONS', 'CREATED AT'], list.map((a) => [
+            a.name || '(unnamed)',
+            a._id,
+            statusLabel(a.agentStatus),
+            outboundPhone(a),
+            inboundPhones(a),
+            publishedVersions(a),
+            formatDate(a.createdAt),
+        ]));
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+/**
+ * Agent-level fields (models/v2Agent.js). `getAgent` returns the agent merged
+ * with a version doc, so without an explicit version we strip back to just
+ * these — the caller asked for "the agent", not a version.
+ */
+const AGENT_FIELDS = [
+    '_id', 'userId', 'folderId', 'name', 'phoneNumber',
+    'inboundPhoneNumbers', 'outboundPhoneNumber', 'secondaryOutboundPhoneNumber',
+    'whatsappPhoneNumber', 'whatsappInboundPhoneNumber', 'default_agent_language',
+    'publishedVersionsByLanguage', 'publishedVersionId', 'lastPublishedDate',
+    'abTestEnabled', 'abTestVersions', 'advancedAbTestEnabled', 'advancedAbTestRules',
+    'agentStatus', 'useMultiTranscribers',
+    'createdAt', 'updatedAt',
+];
+function pickAgentFields(agent) {
+    const out = {};
+    for (const k of AGENT_FIELDS)
+        if (k in agent)
+            out[k] = agent[k];
+    return out;
+}
+async function agentsGetCommand(agentId, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        const versionId = (0, versions_1.firstVersion)(opts.versions);
+        const res = await api.getAgent(agentId, versionId);
+        const { agent, phoneNumbers, allVersions } = res;
+        // JSON/file output: with a version → the merged agent+version doc the API
+        // already builds; without one → agent fields only.
+        const payload = versionId ? agent : pickAgentFields(agent);
+        if (opts.file) {
+            (0, fs_1.writeFileSync)(opts.file, JSON.stringify(payload, null, 2));
+            return void (0, ui_1.success)(`Saved agent ${agentId} to ${opts.file}`);
+        }
+        if (opts.json)
+            return void console.log(JSON.stringify(payload, null, 2));
+        (0, ui_1.keyValue)({
+            id: agent._id,
+            name: agent.name,
+            status: statusLabel(agent.agentStatus),
+            language: agent.default_agent_language,
+            created: formatDate(agent.createdAt),
+            updated: formatDate(agent.updatedAt),
+        });
+        if (versionId) {
+            (0, ui_1.info)('\nVersion:');
+            (0, ui_1.keyValue)({ id: versionId, name: agent.versionName, model: agent.model, language: agent.default_language });
+        }
+        if (Array.isArray(allVersions) && allVersions.length) {
+            (0, ui_1.info)('\nVersions:');
+            (0, ui_1.table)(['VERSION', 'ID', 'LANGUAGE', 'PROMPT TYPE', 'ACTIVE'], allVersions.map((v) => [
+                v.versionName || '',
+                v._id,
+                v.default_language || '',
+                v.systempromptType ?? '',
+                v.is_active ? 'yes' : 'no',
+            ]));
+        }
+        if (Array.isArray(phoneNumbers) && phoneNumbers.length) {
+            (0, ui_1.info)('\nPhone numbers:');
+            (0, ui_1.table)(['NUMBER', 'TYPE'], phoneNumbers.map((p) => [p.phoneNumber || '', p.type || '']));
+        }
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+async function agentsVersionsCommand(agentId, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        const res = await api.listAgentVersions(agentId);
+        const versions = res.versions || [];
+        if (opts.file) {
+            (0, fs_1.writeFileSync)(opts.file, JSON.stringify(versions, null, 2));
+            return void (0, ui_1.success)(`Saved ${versions.length} version(s) to ${opts.file}`);
+        }
+        if (opts.json)
+            return void console.log(JSON.stringify(versions, null, 2));
+        if (!versions.length)
+            return void (0, ui_1.info)('No versions yet.');
+        (0, ui_1.table)(['VERSION', 'ID', 'LANGUAGE', 'PROMPT TYPE', 'ACTIVE'], versions.map((v) => [
+            v.versionName || '',
+            v._id,
+            v.default_language || '',
+            v.systempromptType ?? '',
+            v.is_active ? 'yes' : 'no',
+        ]));
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+/** Slugify an agent name for a default filename, matching the UI's rule. */
+function safeName(name) {
+    return String(name || 'agent').replace(/[^\w-]+/g, '-').replace(/-+/g, '-').toLowerCase();
+}
+function defaultFilename(name) {
+    const ts = new Date().toISOString().slice(0, 19).replace(/[:T]/g, '-');
+    return `${safeName(name)}-${ts}.json`;
+}
+/**
+ * Where a bare `export` lands, mirroring the browser's "Export" download: the
+ * user's Downloads folder, or the current directory if that doesn't exist.
+ */
+function downloadDir() {
+    const dir = (0, path_1.join)((0, os_1.homedir)(), 'Downloads');
+    return (0, fs_1.existsSync)(dir) ? dir : process.cwd();
+}
+async function agentsExportCommand(agentId, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        let ids = (0, versions_1.versionList)(opts.versions);
+        if (ids.length === 0) {
+            const res = await api.listAgentVersions(agentId);
+            const versions = res.versions || [];
+            if (!versions.length)
+                return (0, ui_1.handleError)(new Error('This agent has no versions'));
+            const picked = await (0, prompts_1.default)({
+                type: 'multiselect',
+                name: 'ids',
+                message: 'Which versions to export?',
+                choices: versions.map((v) => ({ title: v.versionName || v._id, value: v._id })),
+            });
+            if (!picked.ids || !picked.ids.length) {
+                return (0, ui_1.handleError)(new Error('No versions selected — pass --versions <ids> to skip the picker.'));
+            }
+            ids = picked.ids;
+        }
+        const { agents } = await api.exportAgent(agentId, ids);
+        if (!agents || agents.length === 0)
+            return (0, ui_1.handleError)(new Error('No data returned'));
+        // Match the UI: a single version exports as an object, many as an array.
+        const payload = agents.length === 1 ? agents[0] : agents;
+        const name = agents[0]?.name || agentId;
+        // Default → the Downloads folder (like the browser export); --file wins as typed.
+        const out = opts.file ? (0, path_1.resolve)(opts.file) : (0, path_1.join)(downloadDir(), defaultFilename(name));
+        try {
+            (0, fs_1.writeFileSync)(out, JSON.stringify(payload, null, 2));
+        }
+        catch (e) {
+            return (0, ui_1.handleError)(new Error(`Could not write ${out}: ${e.message}`));
+        }
+        (0, ui_1.success)(`Exported ${agents.length} version(s) to:`);
+        (0, ui_1.info)(`  ${out}`);
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+async function agentsImportCommand(filepath, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        const { readJsonFile } = await Promise.resolve().then(() => __importStar(require('../lib/looseJson')));
+        const { existsSync } = await Promise.resolve().then(() => __importStar(require('fs')));
+        if (!existsSync(filepath))
+            return (0, ui_1.handleError)(new Error(`File not found: ${filepath}`));
+        let parsed = JSON.parse(readJsonFile(filepath));
+        // Older `cku agents export` wrote the raw `{ agents: [...] }` response; unwrap it.
+        if (parsed && Array.isArray(parsed.agents))
+            parsed = parsed.agents;
+        const entries = Array.isArray(parsed) ? parsed : [parsed];
+        // Validate every entry before touching the network, so a bad file fails fast.
+        for (let i = 0; i < entries.length; i++) {
+            const missing = (0, agentImport_1.missingKeys)(entries[i]);
+            if (missing.length) {
+                return (0, ui_1.handleError)(new Error(`Entry ${i + 1} is missing ${missing.length} required field(s): ${missing.slice(0, 8).join(', ')}` +
+                    `${missing.length > 8 ? ', …' : ''}\n  Use \`cku agents export\` to get a complete template.`));
+            }
+            const found = (0, dbFields_1.dbManagedFields)(entries[i]);
+            if (found.length)
+                return (0, ui_1.handleError)(new Error((0, dbFields_1.dbManagedFieldsError)(found, `entry ${i + 1}`)));
+        }
+        const mismatches = (0, agentImport_1.agentLevelMismatches)(entries);
+        if (mismatches.length) {
+            return (0, ui_1.handleError)(new Error(`Agent-level fields differ across versions, so they cannot merge into one agent:\n` +
+                mismatches.map((m) => `  ${m.key}: entry 1 has ${JSON.stringify(m.expected)}, entry ${m.entry} has ${JSON.stringify(m.got)}`).join('\n')));
+        }
+        if (opts.dryRun)
+            return void (0, ui_1.success)(`File looks valid — ${entries.length} version(s). Nothing created (--dry-run).`);
+        const res = entries.length === 1
+            ? await api.createAgent(entries[0])
+            : await api.importMultiple(entries);
+        (0, ui_1.success)(res.msg || `Imported ${entries.length} version(s).`);
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+/**
+ * `cku agents create '<json>'` — create an agent from a JSON object supplied
+ * inline, via `--file`, an `@file` argument, or stdin. `name` is required;
+ * `versionName` defaults to "v1"; the backend fills the rest of the defaults.
+ */
+async function agentsCreateCommand(json, opts) {
+    const api = (0, session_1.requireApi)();
+    let resolved;
+    try {
+        resolved = await (0, jsonInput_1.resolveJsonInput)(json, opts.file);
+    }
+    catch (e) {
+        return (0, ui_1.handleError)(e);
+    }
+    let obj;
+    try {
+        obj = (0, jsonInput_1.parseJsonInput)(resolved);
+    }
+    catch (e) {
+        return (0, ui_1.handleError)(new Error(`Not valid JSON: ${e.message}${(0, jsonInput_1.jsonHelpTip)(resolved.raw, resolved.fromShell)}`));
+    }
+    if (Array.isArray(obj)) {
+        return (0, ui_1.handleError)(new Error('That JSON is an array (multiple versions) — `create` takes a single agent object.\n' +
+            '  For a multi-version file, use:  cku agents import <file>'));
+    }
+    if (!obj || typeof obj !== 'object')
+        return (0, ui_1.handleError)(new Error('Agent config must be a JSON object'));
+    const found = (0, dbFields_1.dbManagedFields)(obj);
+    if (found.length)
+        return (0, ui_1.handleError)(new Error((0, dbFields_1.dbManagedFieldsError)(found, 'agent JSON')));
+    if (!obj.name || typeof obj.name !== 'string') {
+        return (0, ui_1.handleError)(new Error('"name" is required to create an agent'));
+    }
+    if (!obj.versionName)
+        obj.versionName = 'v1'; // version model requires it
+    try {
+        const res = await api.createAgent(obj);
+        (0, ui_1.success)(res.msg || 'Agent created.');
+        if (res.agent?._id) {
+            (0, ui_1.info)(`  name: ${res.agent.name || obj.name}`);
+            (0, ui_1.info)(`  id:   ${res.agent._id}`);
+        }
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+/**
+ * `cku agents update <agentId> --set '<json>' --commit "msg"` — update multiple
+ * fields at once. Values are validated (enums/models) before sending; version-
+ * level fields require --versions.
+ *
+ * Dotted paths into a REPLACE_WHOLESALE_KEY object are deep-merged against the
+ * agent's current value first. The backend replaces those objects wholesale, so
+ * sending only the named sub-key would silently delete its siblings.
+ */
+async function agentsUpdateCommand(agentId, opts) {
+    const api = (0, session_1.requireApi)();
+    if (!opts.set) {
+        return (0, ui_1.handleError)(new Error('--set \'{...}\' is required (a JSON object of fields to update)'));
+    }
+    // `--set @patch.json` reads the JSON from a file — quote-proof, like create.
+    let rawSet = opts.set;
+    let fromShell = true;
+    if (rawSet.startsWith('@')) {
+        const { existsSync } = await Promise.resolve().then(() => __importStar(require('fs')));
+        const { readJsonFile } = await Promise.resolve().then(() => __importStar(require('../lib/looseJson')));
+        const path = rawSet.slice(1);
+        if (!existsSync(path))
+            return (0, ui_1.handleError)(new Error(`File not found: ${path}`));
+        rawSet = readJsonFile(path);
+        fromShell = false;
+    }
+    let obj;
+    try {
+        // Inline JSON may have had its quotes eaten by the shell (`{name:mini}`);
+        // parseLooseJson puts them back. File contents are parsed strictly.
+        obj = fromShell
+            ? (await Promise.resolve().then(() => __importStar(require('../lib/looseJson')))).parseLooseJson(rawSet)
+            : JSON.parse(rawSet);
+    }
+    catch (e) {
+        return (0, ui_1.handleError)(new Error(`--set is not valid JSON: ${e.message}${(0, jsonInput_1.jsonHelpTip)(rawSet, fromShell)}`));
+    }
+    let patch;
+    let versionKeys;
+    let wholesaleKeys;
+    try {
+        // Validate model fields against the server's own per-slot list when we can.
+        // Best-effort: without a dashboard session the built-in list still applies.
+        await (0, dashboardAuth_1.refreshModelCatalog)();
+        const dbf = (0, dbFields_1.dbManagedFields)(obj);
+        if (dbf.length)
+            throw new Error((0, dbFields_1.dbManagedFieldsError)(dbf, '--set object'));
+        const prepared = (0, agentUpdate_1.preparePatch)(obj); // throws on invalid enum/model values
+        patch = prepared.patch;
+        versionKeys = prepared.versionKeys;
+        wholesaleKeys = prepared.wholesaleKeys;
+    }
+    catch (e) {
+        return (0, ui_1.handleError)(e);
+    }
+    if (Object.keys(patch).length === 0)
+        return (0, ui_1.handleError)(new Error('Nothing to update'));
+    if (versionKeys.length && !(0, versions_1.firstVersion)(opts.versions)) {
+        return (0, ui_1.handleError)(new Error(`--versions is required to update version field(s): ${versionKeys.join(', ')}`));
+    }
+    // One PUT targets one version. Taking the first id and dropping the rest would
+    // report success for versions that were never touched.
+    const targets = (0, versions_1.versionList)(opts.versions);
+    if (targets.length > 1) {
+        return (0, ui_1.handleError)(new Error(`agents update changes one version at a time, but --versions lists ${targets.length}.\n` +
+            '  Run the command once per version id.'));
+    }
+    try {
+        // The backend replaces these objects wholesale, so a partial --set would drop
+        // every sibling key. Merge against the agent's current value first. This is
+        // a no-op when the object sent is already complete. Merge against the
+        // *target* version: without one, getAgent returns the default version, and
+        // its siblings (provider, voice id, …) would be written onto a different
+        // version. Wholesale keys are version-level, so --versions is set here.
+        if (wholesaleKeys.length) {
+            const { agent } = await api.getAgent(agentId, (0, versions_1.firstVersion)(opts.versions));
+            patch = (0, agentUpdate_1.mergeWholesaleKeys)(patch, agent);
+        }
+        // A commit message is recorded against a version. Version-level updates
+        // already name one; for an agent-level-only update with --commit, attach it
+        // to the agent's current version so the change (e.g. a rename) is logged.
+        let versionTarget = (0, versions_1.firstVersion)(opts.versions);
+        if (opts.commit && !versionTarget) {
+            const { agent } = await api.getAgent(agentId);
+            versionTarget = agent.versionId;
+        }
+        const body = { ...patch };
+        if (opts.commit)
+            body.commitMessage = opts.commit;
+        const res = await api.updateAgent(agentId, versionTarget, body);
+        if (opts.json)
+            return void console.log(JSON.stringify(res, null, 2));
+        (0, ui_1.success)(res.msg || 'Agent updated.');
+        (0, ui_1.info)(`  updated: ${Object.keys(patch).join(', ')}`);
+        if (opts.commit)
+            (0, ui_1.info)(`  commit:  ${opts.commit}`);
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}