callkaro-cli-unofficial 0.9.4 → 0.10.0

package/dist/index.js

@@ -51,6 +51,7 @@ const KPI_COLUMNS = 'action_items | in_progress | testing_ab | live_prod | done
 const analyzers_1 = require("./commands/analyzers");
 const models_1 = require("./commands/models");
 const agents_1 = require("./commands/agents");
+const agentMemory_1 = require("./commands/agentMemory");
 const agentChat_1 = require("./commands/agentChat");
 const scheduled_1 = require("./commands/scheduled");
 const agentVersions_1 = require("./commands/agentVersions");
@@ -75,6 +76,7 @@ const knowledge_1 = require("./commands/knowledge");
 const aiTools_1 = require("./commands/aiTools");
 const batches_1 = require("./commands/batches");
 const simulations_1 = require("./commands/simulations");
+const liveTest_1 = require("./commands/liveTest");
 const simVariables_1 = require("./commands/simVariables");
 const dashboardApiCmd_1 = require("./commands/dashboardApiCmd");
 const adminAuth_1 = require("./lib/adminAuth");
@@ -877,8 +879,33 @@ agents.command('update <agentId>').description('update fields via --set \'{json}
     .option('--versions <id>', 'target a specific version (needed for version-level fields)')
     .option('--commit <msg>', 'commit message for the version change')
     .option('--replace-functions', 'replace the whole functions list instead of merging by name (default merges; omitted functions are kept)')
+    .option('--dry-run', 'show which fields would change, without saving')
+    .option('--yes', 'allow an update that changes more than 8 fields')
     .option('--json', 'output the raw updated-agent response')
     .action(agents_1.agentsUpdateCommand);
+agents.command('memory <agentId>').description('show or change call memory (x_call_history for functions); no flags = show')
+    .option('--versions <id>', 'version id (required)')
+    .option('--enable', 'turn call memory on').option('--disable', 'turn call memory off')
+    .option('--max-calls <n>', 'earlier calls to load, -1 (all, up to 200) to 200')
+    .option('--days <n>', 'only calls from the last n days, 0 = no limit')
+    .option('--only-connected', 'only calls that connected').option('--all-calls', 'include calls that did not connect')
+    .option('--with-transcript', 'include transcripts (large)').option('--without-transcript', 'leave transcripts out')
+    .option('--agents <scope>', 'self | all | <agentId,agentId,...> - whose calls to read')
+    .option('--commit <msg>', 'commit message for the version change')
+    .option('--json', 'output the raw agentMemory object')
+    .action(agentMemory_1.agentsMemoryCommand);
+agents.command('voice-rotation <agentId>').description('show or change voice rotation on retry; no flags = show')
+    .option('--versions <id>', 'version id (required)')
+    .option('--enable', 'turn rotation on').option('--disable', 'turn rotation off')
+    .option('--trigger <mode>', 'instant_hangup | custom')
+    .option('--status <status>', 'custom trigger: previous call connected | not_connected')
+    .option('--condition <expr>', 'custom trigger condition source[.field]:operator[:value] (repeatable)', (value, previous = []) => [...previous, value])
+    .option('--clear-conditions', 'remove all conditions')
+    .option('--voices <@file.json>', 'JSON array of retry voice configurations (max 5)')
+    .option('--on-exhausted <mode>', 'last | primary | cycle')
+    .option('--commit <msg>', 'commit message for the version change')
+    .option('--json', 'output the raw agentMemory object')
+    .action(agentMemory_1.agentsVoiceRotationCommand);
 // Phone assignment (agent-centric). The one-inbound-agent rule is enforced server-side.
 agents.command('set-inbound <agentId>').description("add/remove an agent's inbound phone number")
     .option('--number <id>', 'phone number id')
@@ -1371,6 +1398,8 @@ sim.command('create <agentId>').description('create a test case')
     .option('--model <model>', 'test LLM model (default: platform default; see `cku sim models`)')
     .option('--variables <json|@file>', 'testVariables: a JSON object of name -> value (non-strings are stringified)')
     .option('--functions <json|@file>', 'a JSON array of {"name":"fn","mock":true,"response":{}}; "mock":false runs the REAL function (never for WhatsApp functions)')
+    .option('--real-functions', 'run every agent function for real (mock:false), like switching every Mock off in the dashboard; --functions entries win by name')
+    .option('--versions <versionId>', 'with --real-functions: read the functions from this version (default: the agent\'s default version)')
     .action(simulations_1.simCreateCommand);
 sim.command('update <testCaseId>').description('edit a test case (only the fields you pass are sent)')
     .option('--name <name>', 'test case name')
@@ -1380,6 +1409,9 @@ sim.command('update <testCaseId>').description('edit a test case (only the field
     .option('--model <model>', 'test LLM model')
     .option('--variables <json|@file>', 'testVariables: replaces the whole map')
     .option('--functions <json|@file>', 'function list, replaces the whole list; entries are {name, mock?, response?}, "mock":false runs the REAL function')
+    .option('--real-functions', 'replace the list with every agent function run for real (mock:false); --functions entries win by name; needs --agent')
+    .option('--agent <agentId>', 'agent to read functions from (for --real-functions)')
+    .option('--versions <versionId>', 'with --real-functions: read the functions from this version')
     .action(simulations_1.simUpdateCommand);
 sim.command('models').description('models that can play the simulated caller').option('--json', 'raw JSON').action(simulations_1.simModelsCommand);
 sim.command('delete <testCaseId>').description('delete a test case').option('--yes', 'skip confirmation')
@@ -1423,6 +1455,47 @@ simVars.command('create <agentId> <name>').description('save a variable set')
     .action(simVariables_1.simVarsCreateCommand);
 simVars.command('delete <agentId> <nameOrId>').description('delete a saved set').option('--yes', 'skip confirmation')
     .action(simVariables_1.simVarsDeleteCommand);
+// --- live test calls (the editor's Test Chat, from a terminal) -------------
+const liveTest = program.command('test').description('live test calls against the real call runtime; you or an LLM play the caller (functions RUN FOR REAL)');
+liveTest.command('start <agentId>').description('start a test call and print the agent\'s opening turn; then `test say` / `test end`')
+    .option('--versions <versionId>', 'version to test (default: the published one)')
+    .option('--variables <json|@file>', 'call metadata as a JSON object')
+    .option('--yes', 'confirm the real test call without asking')
+    .option('--json', 'print {sessionId, callSid, events} as JSON')
+    .action(liveTest_1.testStartCommand);
+liveTest.command('say <sessionId> <text...>').description('send one caller turn and print the agent\'s reply')
+    .option('--timeout <seconds>', 'wait this long for the agent to finish its turn (default 60)')
+    .option('--json', 'print {events, ended} as JSON')
+    .action(liveTest_1.testSayCommand);
+liveTest.command('end <sessionId>').description('hang up and print the full transcript with function calls')
+    .option('--json', 'print {callSid, events, ended} as JSON')
+    .action(liveTest_1.testEndCommand);
+liveTest.command('_serve <sessionId>', { hidden: true }).action(liveTest_1.testServeCommand);
+liveTest.command('run <agentId>').description('the CLI plays the caller with an LLM, then grades the call against --criteria')
+    .option('--test <testCaseId>', 'reuse a saved simulation test case (persona, prompt, criteria, variables)')
+    .option('--persona <text>', 'who the caller is')
+    .option('--prompt <text>', 'what the caller wants and does in this call')
+    .option('--criteria <text>', 'success criteria for the judge; without it the call is not graded')
+    .option('--variables <json|@file>', 'call metadata as a JSON object (merged over the test case\'s)')
+    .option('--versions <versionId>', 'version to test (default: the published one)')
+    .option('--llm <provider>', 'openai | anthropic | gemini | deepseek | groq | openrouter | ollama | custom (default: first key found in the environment)')
+    .option('--llm-model <model>', 'caller model (default per provider)')
+    .option('--llm-url <url>', 'OpenAI-compatible base URL (custom provider; key in CKU_LLM_API_KEY)')
+    .option('--judge-model <model>', 'judge model on the same provider (default: the caller model)')
+    .option('--max-turns <n>', 'caller turns before giving up (default 20)')
+    .option('--timeout <seconds>', 'per agent turn (default 60)')
+    .option('--yes', 'confirm the real test call without asking')
+    .option('--json', 'print {callSid, endedBy, events, verdict} as JSON')
+    .addHelpText('after', `
+Keys come from the environment only: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY,
+DEEPSEEK_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, or CKU_LLM_API_KEY for any provider.
+Exit 1 when the judge fails the call (or cannot grade it).
+
+Examples:
+  cku test run <agentId> --test <testCaseId> --yes
+  cku test run <agentId> --persona "Busy dealer in Pune" --prompt "Ask for the price, then say you will think about it" \\
+    --criteria "1. Agent states the price from call data. 2. Agent ends politely with end_call." --llm anthropic --yes`)
+    .action(liveTest_1.testRunCommand);
 // --- audit strategies ------------------------------------------------------
 const chatSim = program.command('chat-sim').description('chat agent simulations & test cases');
 chatSim.command('tests <chatAgentId>').description('list chat test cases').option('--json', 'raw JSON').action(chatSimulations_1.chatSimTestsListCommand);

package/dist/lib/agentMemory.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasChanges = exports.CONDITION_OPERATORS = exports.CONDITION_SOURCES = exports.ON_EXHAUSTED = exports.PREVIOUS_STATUSES = exports.TRIGGER_MODES = exports.MAX_CONDITIONS = exports.MAX_ROTATION_VOICES = exports.MAX_DAYS_RANGE = exports.MAX_CALLS_RANGE = void 0;
+exports.applyMemoryFlags = applyMemoryFlags;
+exports.parseCondition = parseCondition;
+exports.applyRotationFlags = applyRotationFlags;
+exports.describeMemory = describeMemory;
+exports.describeRotation = describeRotation;
+/** Helpers for call memory and retry voice rotation stored in version.agentMemory. */
+exports.MAX_CALLS_RANGE = [-1, 200];
+exports.MAX_DAYS_RANGE = [0, 3650];
+exports.MAX_ROTATION_VOICES = 5;
+exports.MAX_CONDITIONS = 20;
+exports.TRIGGER_MODES = ['instant_hangup', 'custom'];
+exports.PREVIOUS_STATUSES = ['connected', 'not_connected'];
+exports.ON_EXHAUSTED = ['last', 'primary', 'cycle'];
+exports.CONDITION_SOURCES = ['post_call_variable', 'hangup_reason', 'call_duration', 'conversion_status'];
+exports.CONDITION_OPERATORS = ['equals', 'not_equals', 'empty', 'not_empty', 'eq', 'gt', 'gte', 'lt', 'lte'];
+const OBJECT_ID = /^[0-9a-fA-F]{24}$/;
+const clone = (value) => JSON.parse(JSON.stringify(value ?? {}));
+function oneOf(label, value, allowed) {
+    if (!allowed.includes(value))
+        throw new Error(`Invalid ${label} "${value}"\n  allowed: ${allowed.join(', ')}`);
+    return value;
+}
+function intIn(label, raw, [min, max]) {
+    const value = Number(raw);
+    if (raw.trim() === '' || !Number.isInteger(value) || value < min || value > max) {
+        throw new Error(`Invalid ${label} "${raw}": expected a whole number from ${min} to ${max}`);
+    }
+    return value;
+}
+function pairFlag(label, on, off, onFlag, offFlag) {
+    if (on && off)
+        throw new Error(`${onFlag} and ${offFlag} cannot be used together (${label})`);
+}
+const hasChanges = (flags) => Object.values(flags).some((value) => value !== undefined && value !== false);
+exports.hasChanges = hasChanges;
+function applyMemoryFlags(current, flags) {
+    pairFlag('on/off', flags.enable, flags.disable, '--enable', '--disable');
+    pairFlag('connected filter', flags.onlyConnected, flags.allCalls, '--only-connected', '--all-calls');
+    pairFlag('transcript', flags.withTranscript, flags.withoutTranscript, '--with-transcript', '--without-transcript');
+    const out = clone(current);
+    const filters = (out.call_filters = out.call_filters || {});
+    if (flags.enable)
+        out.enabled_for_call = true;
+    if (flags.disable)
+        out.enabled_for_call = false;
+    if (flags.maxCalls !== undefined)
+        filters.maxCalls = intIn('--max-calls', String(flags.maxCalls), exports.MAX_CALLS_RANGE);
+    if (flags.days !== undefined)
+        filters.maxDays = intIn('--days', String(flags.days), exports.MAX_DAYS_RANGE);
+    if (flags.onlyConnected)
+        filters.onlyConnected = true;
+    if (flags.allCalls)
+        filters.onlyConnected = false;
+    if (flags.withTranscript)
+        filters.includeTranscript = true;
+    if (flags.withoutTranscript)
+        filters.includeTranscript = false;
+    if (flags.agents !== undefined) {
+        const raw = String(flags.agents).trim();
+        if (raw === 'self' || raw === 'all')
+            filters.additionalAgents = { mode: raw, agentIds: [] };
+        else {
+            const ids = raw.split(',').map((id) => id.trim()).filter(Boolean);
+            const bad = ids.filter((id) => !OBJECT_ID.test(id));
+            if (!ids.length || bad.length) {
+                throw new Error(`Invalid --agents "${raw}": use self, all, or a comma-separated list of agent ids${bad.length ? ` (bad: ${bad.join(', ')})` : ''}`);
+            }
+            if (ids.length > 50)
+                throw new Error('--agents takes at most 50 agent ids');
+            filters.additionalAgents = { mode: 'selected', agentIds: ids };
+        }
+    }
+    return out;
+}
+/** Parse source[.field]:operator[:value]. */
+function parseCondition(text) {
+    const [lhs, operator, ...rest] = text.split(':');
+    if (!lhs || !operator)
+        throw new Error(`Bad --condition "${text}": expected source[.field]:operator[:value], e.g. hangup_reason:equals:user_busy`);
+    const dot = lhs.indexOf('.');
+    const source = dot < 0 ? lhs : lhs.slice(0, dot);
+    const field = dot < 0 ? undefined : lhs.slice(dot + 1);
+    oneOf('condition source', source, exports.CONDITION_SOURCES);
+    oneOf('condition operator', operator, exports.CONDITION_OPERATORS);
+    if (source === 'post_call_variable' && !field)
+        throw new Error(`Bad --condition "${text}": post_call_variable needs a field, e.g. post_call_variable.interested:equals:false`);
+    if (source !== 'post_call_variable' && field)
+        throw new Error(`Bad --condition "${text}": only post_call_variable takes a .field`);
+    const condition = { source, operator };
+    if (field)
+        condition.field = field;
+    if (operator !== 'empty' && operator !== 'not_empty') {
+        if (!rest.length)
+            throw new Error(`Bad --condition "${text}": operator "${operator}" needs a value`);
+        const raw = rest.join(':');
+        try {
+            condition.value = JSON.parse(raw);
+        }
+        catch {
+            condition.value = raw;
+        }
+        if (typeof condition.value === 'object')
+            condition.value = raw;
+    }
+    return condition;
+}
+function applyRotationFlags(current, flags) {
+    pairFlag('on/off', flags.enable, flags.disable, '--enable', '--disable');
+    if (flags.clearConditions && flags.condition?.length)
+        throw new Error('--clear-conditions and --condition cannot be used together');
+    const out = clone(current);
+    const rotation = (out.voice_rotation_config = out.voice_rotation_config || {});
+    const trigger = (rotation.trigger = rotation.trigger || {});
+    if (flags.enable)
+        rotation.enabled = true;
+    if (flags.disable)
+        rotation.enabled = false;
+    if (flags.trigger !== undefined)
+        trigger.mode = oneOf('--trigger', flags.trigger, exports.TRIGGER_MODES);
+    if (flags.status !== undefined)
+        trigger.previous_call_status = oneOf('--status', flags.status, exports.PREVIOUS_STATUSES);
+    if (flags.onExhausted !== undefined)
+        rotation.on_exhausted = oneOf('--on-exhausted', flags.onExhausted, exports.ON_EXHAUSTED);
+    if (flags.clearConditions)
+        trigger.conditions = [];
+    if (flags.condition?.length)
+        trigger.conditions = flags.condition.map(parseCondition);
+    if ((trigger.conditions || []).length > exports.MAX_CONDITIONS)
+        throw new Error(`At most ${exports.MAX_CONDITIONS} conditions`);
+    if ((trigger.conditions || []).length && (trigger.mode || 'instant_hangup') !== 'custom') {
+        throw new Error('Conditions only apply with --trigger custom (instant_hangup ignores them)');
+    }
+    if (flags.voices !== undefined) {
+        if (!Array.isArray(flags.voices) || flags.voices.some((voice) => !voice || typeof voice !== 'object' || Array.isArray(voice))) {
+            throw new Error('--voices must be a JSON array of voice configuration objects');
+        }
+        if (flags.voices.length > exports.MAX_ROTATION_VOICES)
+            throw new Error(`At most ${exports.MAX_ROTATION_VOICES} retry voices (got ${flags.voices.length})`);
+        flags.voices.forEach((voice, index) => {
+            if (typeof voice.voice_provider !== 'string' || !voice.voice_provider.trim()) {
+                throw new Error(`voices[${index}]: voice_provider is required - copy the "configuration" object from \`cku voices --json\` unchanged`);
+            }
+        });
+        rotation.voices = flags.voices;
+    }
+    if (rotation.enabled && !(rotation.voices || []).length)
+        throw new Error('Rotation needs at least one retry voice - pass --voices @voices.json (a JSON array), or leave it disabled');
+    return out;
+}
+function describeMemory(memory) {
+    const value = memory || {};
+    const filters = value.call_filters || {};
+    const agents = filters.additionalAgents || {};
+    const maxCalls = filters.maxCalls ?? 10;
+    return {
+        'call memory': value.enabled_for_call ? 'on' : 'off',
+        'max calls': maxCalls < 0 ? 'all (up to 200)' : String(maxCalls),
+        'max age (days)': (filters.maxDays ?? 0) > 0 ? String(filters.maxDays) : 'no limit',
+        'connected only': filters.onlyConnected === false ? 'no' : 'yes',
+        transcripts: filters.includeTranscript ? 'yes' : 'no',
+        'agents read': agents.mode === 'selected' ? `selected (${(agents.agentIds || []).length})` : agents.mode || 'self',
+    };
+}
+function describeRotation(memory) {
+    const rotation = (memory || {}).voice_rotation_config || {};
+    const trigger = rotation.trigger || {};
+    const mode = trigger.mode || 'instant_hangup';
+    return {
+        'voice rotation': rotation.enabled ? 'on' : 'off',
+        trigger: mode === 'custom' ? `custom (previous call ${trigger.previous_call_status || 'connected'}, ${(trigger.conditions || []).length} condition(s))` : 'instant_hangup',
+        'retry voices': String((rotation.voices || []).length),
+        'when exhausted': rotation.on_exhausted || 'last',
+    };
+}

package/dist/lib/agentUpdate.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ENUMS = exports.STRING_ARRAY_KEYS = exports.REPLACE_WHOLESALE_KEYS = void 0;
+exports.MAX_FIELDS_WITHOUT_YES = exports.ENUMS = exports.STRING_ARRAY_KEYS = exports.REPLACE_WHOLESALE_KEYS = void 0;
 exports.applyLiveModels = applyLiveModels;
 exports.validateEnums = validateEnums;
 exports.validateCallSettings = validateCallSettings;
 exports.validateProviderConfigs = validateProviderConfigs;
 exports.preparePatch = preparePatch;
+exports.jsonEqual = jsonEqual;
+exports.planUpdate = planUpdate;
 exports.coerce = coerce;
 exports.deepMerge = deepMerge;
 exports.mergeWholesaleKeys = mergeWholesaleKeys;
@@ -28,7 +30,7 @@ const catalog_1 = require("./catalog");
 exports.REPLACE_WHOLESALE_KEYS = new Set([
     'preFormatVariables', 'customPronunciations', 'transcriber', 'secondary_transcriber',
     'voice_configuration', 'secondary_voice_configuration', 'callFlow_json',
-    'variableSource', 'callPropertyMapping',
+    'variableSource', 'callPropertyMapping', 'agentMemory',
 ]);
 /** String-array fields the web trims + drops empties on; we match that. */
 exports.STRING_ARRAY_KEYS = new Set([
@@ -160,8 +162,10 @@ const PROVIDER_CONFIGS = [
  * Patches may be partial (a dotted `--set` touching only `voice_speed`), so each
  * check runs only when the keys it needs are actually present.
  */
-function validateProviderConfigs(obj) {
+function validateProviderConfigs(obj, opts = {}) {
     for (const { key, kind } of PROVIDER_CONFIGS) {
+        if (opts.skipVoices && kind === 'voice')
+            continue;
         const cfg = obj[key];
         if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg))
             continue;
@@ -199,7 +203,7 @@ function validateProviderConfigs(obj) {
  * `wholesaleKeys` lists the replace-wholesale objects present in the patch, so
  * the caller can merge them against the agent's current value before sending.
  */
-function preparePatch(obj) {
+function preparePatch(obj, opts = {}) {
     if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
         throw new Error('--set must be a JSON object of fields, e.g. \'{"name":"x","temperature":5}\'');
     }
@@ -207,7 +211,7 @@ function preparePatch(obj) {
     validateEnums(source);
     validateCallSettings(source);
     const patch = { ...source };
-    validateProviderConfigs(patch);
+    validateProviderConfigs(patch, opts);
     for (const key of Object.keys(patch)) {
         if (exports.STRING_ARRAY_KEYS.has(key))
             patch[key] = normalizeStringArray(patch[key]);
@@ -216,6 +220,32 @@ function preparePatch(obj) {
     const wholesaleKeys = Object.keys(patch).filter((k) => exports.REPLACE_WHOLESALE_KEYS.has(k) && patch[k] && typeof patch[k] === 'object' && !Array.isArray(patch[k]));
     return { patch, versionKeys, wholesaleKeys };
 }
+exports.MAX_FIELDS_WITHOUT_YES = 8;
+const isObject = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+/** Structural JSON equality: object key order does not matter; array order does. */
+function jsonEqual(a, b) {
+    if (Array.isArray(a) || Array.isArray(b))
+        return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((value, i) => jsonEqual(value, b[i]));
+    if (isObject(a) && isObject(b))
+        return [...new Set([...Object.keys(a), ...Object.keys(b)])].every((key) => jsonEqual(a[key], b[key]));
+    return a === b;
+}
+function planUpdate(current, patch) {
+    const send = {};
+    const changed = [];
+    const unchanged = [];
+    for (const [key, value] of Object.entries(patch)) {
+        const before = current[key];
+        const next = exports.REPLACE_WHOLESALE_KEYS.has(key) && isObject(before) && isObject(value) ? deepMerge(before, value) : value;
+        if (jsonEqual(before, next))
+            unchanged.push(key);
+        else {
+            send[key] = next;
+            changed.push(key);
+        }
+    }
+    return { send, changed, unchanged };
+}
 /** JSON-first value coercion: `true`→bool, `5`→num, `[...]`→array, else the raw string. */
 function coerce(raw) {
     try {