convoai 1.0.0

package/dist/src/ui/colors.js

@@ -0,0 +1,36 @@
+import chalk from 'chalk';
+// ─── Status Colors ──────────────────────────────────────────────────────────
+const STATUS_COLORS = {
+    RUNNING: chalk.green,
+    STARTING: chalk.yellow,
+    RECOVERING: chalk.yellow,
+    FAILED: chalk.red,
+    STOPPED: chalk.red,
+    IDLE: chalk.gray,
+    STOPPING: chalk.gray,
+};
+/** Colorize an agent status string for terminal display. */
+export function colorStatus(status) {
+    const colorize = STATUS_COLORS[status] ?? chalk.white;
+    return colorize(status);
+}
+// ─── General-Purpose Helpers ────────────────────────────────────────────────
+export function dim(text) {
+    return chalk.dim(text);
+}
+export function bold(text) {
+    return chalk.bold(text);
+}
+export function success(text) {
+    return chalk.green(text);
+}
+export function error(text) {
+    return chalk.red(text);
+}
+export function warn(text) {
+    return chalk.yellow(text);
+}
+export function info(text) {
+    return chalk.cyan(text);
+}
+//# sourceMappingURL=colors.js.map

package/dist/src/ui/colors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.js","sourceRoot":"","sources":["../../../src/ui/colors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,+EAA+E;AAE/E,MAAM,aAAa,GAAkD;IACnE,OAAO,EAAE,KAAK,CAAC,KAAK;IACpB,QAAQ,EAAE,KAAK,CAAC,MAAM;IACtB,UAAU,EAAE,KAAK,CAAC,MAAM;IACxB,MAAM,EAAE,KAAK,CAAC,GAAG;IACjB,OAAO,EAAE,KAAK,CAAC,GAAG;IAClB,IAAI,EAAE,KAAK,CAAC,IAAI;IAChB,QAAQ,EAAE,KAAK,CAAC,IAAI;CACrB,CAAC;AAEF,4DAA4D;AAC5D,MAAM,UAAU,WAAW,CAAC,MAAmB;IAC7C,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC;IACtD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC1B,CAAC;AAED,+EAA+E;AAE/E,MAAM,UAAU,GAAG,CAAC,IAAY;IAC9B,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,IAAY;IAC/B,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,IAAY;IAChC,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,IAAY;IAC/B,OAAO,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,IAAY;IAC/B,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/src/ui/output.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Output data as JSON (if --json flag is set) or do nothing and let
+ * the calling command handle human-friendly rendering.
+ */
+export declare function output(data: unknown, opts: {
+    json?: boolean;
+}): void;
+/** Check whether JSON output mode is active. */
+export declare function isJsonMode(options: {
+    json?: boolean;
+}): boolean;
+/** Print a success message with a green checkmark. */
+export declare function printSuccess(message: string): void;
+/** Print an error message with a red X. */
+export declare function printError(message: string): void;
+/** Print a next-step hint with a dim prefix. */
+export declare function printHint(message: string): void;

package/dist/src/ui/output.js

@@ -0,0 +1,27 @@
+import chalk from 'chalk';
+/**
+ * Output data as JSON (if --json flag is set) or do nothing and let
+ * the calling command handle human-friendly rendering.
+ */
+export function output(data, opts) {
+    if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+    }
+}
+/** Check whether JSON output mode is active. */
+export function isJsonMode(options) {
+    return options.json === true;
+}
+/** Print a success message with a green checkmark. */
+export function printSuccess(message) {
+    console.log(`${chalk.green('\u2714')} ${message}`);
+}
+/** Print an error message with a red X. */
+export function printError(message) {
+    console.error(`${chalk.red('\u2716')} ${message}`);
+}
+/** Print a next-step hint with a dim prefix. */
+export function printHint(message) {
+    console.log(`${chalk.dim('Next:')} ${message}`);
+}
+//# sourceMappingURL=output.js.map

package/dist/src/ui/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../../src/ui/output.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,IAAa,EAAE,IAAwB;IAC5D,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,UAAU,CAAC,OAA2B;IACpD,OAAO,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC;AAC/B,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;AACrD,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;AACrD,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;AAClD,CAAC"}

package/dist/src/ui/spinner.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Run an async function with a terminal spinner.
+ * Gracefully degrades in non-TTY environments (e.g. piped output).
+ */
+export declare function withSpinner<T>(message: string, fn: () => Promise<T>): Promise<T>;

package/dist/src/ui/spinner.js

@@ -0,0 +1,23 @@
+import ora from 'ora';
+/**
+ * Run an async function with a terminal spinner.
+ * Gracefully degrades in non-TTY environments (e.g. piped output).
+ */
+export async function withSpinner(message, fn) {
+    // Skip spinner entirely if stdout is not a TTY
+    if (!process.stdout.isTTY) {
+        return fn();
+    }
+    const spinner = ora(message).start();
+    try {
+        const result = await fn();
+        spinner.succeed();
+        return result;
+    }
+    catch (err) {
+        const failMessage = err instanceof Error ? err.message : String(err);
+        spinner.fail(failMessage);
+        throw err;
+    }
+}
+//# sourceMappingURL=spinner.js.map

package/dist/src/ui/spinner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.js","sourceRoot":"","sources":["../../../src/ui/spinner.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,KAAK,CAAC;AAEtB;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAe,EACf,EAAoB;IAEpB,+CAA+C;IAC/C,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAC1B,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC;IAErC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;QAC1B,OAAO,CAAC,OAAO,EAAE,CAAC;QAClB,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,WAAW,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACrE,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC1B,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/src/ui/table.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Print a formatted table to stdout.
+ */
+export declare function printTable(headers: string[], rows: string[][]): void;
+/**
+ * Print a list of key-value pairs, formatted for single-item detail views.
+ */
+export declare function printKeyValue(pairs: [string, string][]): void;

package/dist/src/ui/table.js

@@ -0,0 +1,38 @@
+import Table from 'cli-table3';
+import chalk from 'chalk';
+/**
+ * Print a formatted table to stdout.
+ */
+export function printTable(headers, rows) {
+    const table = new Table({
+        head: headers.map((h) => chalk.bold(h)),
+        style: {
+            head: [], // disable default color — we apply our own via chalk
+            border: [],
+            compact: true,
+        },
+        chars: {
+            top: '', 'top-mid': '', 'top-left': '', 'top-right': '',
+            bottom: '', 'bottom-mid': '', 'bottom-left': '', 'bottom-right': '',
+            left: '', 'left-mid': '',
+            mid: '', 'mid-mid': '',
+            right: '', 'right-mid': '',
+            middle: '  ',
+        },
+    });
+    for (const row of rows) {
+        table.push(row);
+    }
+    console.log(table.toString());
+}
+/**
+ * Print a list of key-value pairs, formatted for single-item detail views.
+ */
+export function printKeyValue(pairs) {
+    const maxKeyLen = Math.max(...pairs.map(([k]) => k.length));
+    for (const [key, value] of pairs) {
+        const paddedKey = key.padEnd(maxKeyLen);
+        console.log(`  ${chalk.dim(paddedKey)}  ${value}`);
+    }
+}
+//# sourceMappingURL=table.js.map

package/dist/src/ui/table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.js","sourceRoot":"","sources":["../../../src/ui/table.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,YAAY,CAAC;AAC/B,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,OAAiB,EAAE,IAAgB;IAC5D,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC;QACtB,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACvC,KAAK,EAAE;YACL,IAAI,EAAE,EAAE,EAAQ,qDAAqD;YACrE,MAAM,EAAE,EAAE;YACV,OAAO,EAAE,IAAI;SACd;QACD,KAAK,EAAE;YACL,GAAG,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE;YACvD,MAAM,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,cAAc,EAAE,EAAE;YACnE,IAAI,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE;YACxB,GAAG,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE;YACtB,KAAK,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE;YAC1B,MAAM,EAAE,IAAI;SACb;KACF,CAAC,CAAC;IAEH,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClB,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;AAChC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,KAAyB;IACrD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAE5D,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC;QACjC,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACxC,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;IACrD,CAAC;AACH,CAAC"}

package/dist/src/utils/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Extract a human-readable message from an API error.
+ */
+export declare function formatApiError(error: unknown): string;
+/**
+ * Format an error, print to stderr, and exit with code 1.
+ * In JSON mode, outputs a structured error object instead.
+ */
+export declare function handleError(error: unknown, options?: {
+    json?: boolean;
+}): never;

package/dist/src/utils/errors.js

@@ -0,0 +1,38 @@
+import { AxiosError } from 'axios';
+import chalk from 'chalk';
+/**
+ * Extract a human-readable message from an API error.
+ */
+export function formatApiError(error) {
+    if (error instanceof AxiosError) {
+        const status = error.response?.status;
+        const data = error.response?.data;
+        const detail = data?.detail || data?.reason || error.message;
+        if (status) {
+            return `API Error ${status}: ${detail}`;
+        }
+        if (error.code === 'ECONNREFUSED' || error.code === 'ENOTFOUND') {
+            return `Network error: could not reach the API (${error.code})`;
+        }
+        return `Request failed: ${error.message}`;
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+/**
+ * Format an error, print to stderr, and exit with code 1.
+ * In JSON mode, outputs a structured error object instead.
+ */
+export function handleError(error, options) {
+    const message = formatApiError(error);
+    if (options?.json) {
+        console.error(JSON.stringify({ error: message }, null, 2));
+    }
+    else {
+        console.error(`${chalk.red('\u2716')} ${message}`);
+    }
+    process.exit(1);
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/utils/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/utils/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACnC,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAoC,CAAC;QAClE,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,IAAI,IAAI,EAAE,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC;QAE7D,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,aAAa,MAAM,KAAK,MAAM,EAAE,CAAC;QAC1C,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAChE,OAAO,2CAA2C,KAAK,CAAC,IAAI,GAAG,CAAC;QAClE,CAAC;QACD,OAAO,mBAAmB,KAAK,CAAC,OAAO,EAAE,CAAC;IAC5C,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IAED,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,KAAc,EACd,OAA4B;IAE5B,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAEtC,IAAI,OAAO,EAAE,IAAI,EAAE,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7D,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/src/utils/format.d.ts

@@ -0,0 +1,16 @@
+/** Generate a unique agent name. */
+export declare function generateAgentName(): string;
+/** Mask a secret: show first 4 chars, then ****. */
+export declare function maskSecret(value: string | undefined): string;
+/** Format a Unix timestamp (seconds) to readable date. Returns "—" for falsy values. */
+export declare function formatTimestamp(ts: number | undefined): string;
+/** Convert a Unix timestamp to a relative time string. */
+export declare function relativeTime(ts: number | undefined): string;
+/** Format a duration in seconds to human-readable string. */
+export declare function formatDuration(seconds: number): string;
+/** Color-code a latency value: green < 1000ms, yellow 1000-2000ms, red > 2000ms. */
+export declare function colorLatency(ms: number | undefined): string;
+/** Format a role for conversation display. */
+export declare function formatRole(role: string): string;
+/** Calculate average of an array of numbers, ignoring undefined. */
+export declare function averageOf(values: (number | undefined)[]): number;

package/dist/src/utils/format.js

@@ -0,0 +1,87 @@
+import chalk from 'chalk';
+/** Generate a unique agent name. */
+export function generateAgentName() {
+    const ts = Math.floor(Date.now() / 1000);
+    const rand = Math.random().toString(36).slice(2, 6);
+    return `agent-${ts}-${rand}`;
+}
+/** Mask a secret: show first 4 chars, then ****. */
+export function maskSecret(value) {
+    if (!value)
+        return '(not set)';
+    if (value.length <= 4)
+        return '****';
+    return value.slice(0, 4) + '****';
+}
+/** Format a Unix timestamp (seconds) to readable date. Returns "—" for falsy values. */
+export function formatTimestamp(ts) {
+    if (!ts)
+        return '—';
+    const date = new Date(ts * 1000);
+    return date.toLocaleString('en-US', {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false,
+    });
+}
+/** Convert a Unix timestamp to a relative time string. */
+export function relativeTime(ts) {
+    if (!ts)
+        return '—';
+    const nowSec = Math.floor(Date.now() / 1000);
+    const diffSec = nowSec - ts;
+    if (diffSec < 0)
+        return 'just now';
+    if (diffSec < 60)
+        return `${diffSec}s ago`;
+    const diffMin = Math.floor(diffSec / 60);
+    if (diffMin < 60)
+        return `${diffMin}m ago`;
+    const diffHr = Math.floor(diffMin / 60);
+    if (diffHr < 24)
+        return `${diffHr}h ago`;
+    const diffDay = Math.floor(diffHr / 24);
+    return `${diffDay}d ago`;
+}
+/** Format a duration in seconds to human-readable string. */
+export function formatDuration(seconds) {
+    if (seconds < 60)
+        return `${seconds}s`;
+    const min = Math.floor(seconds / 60);
+    const sec = seconds % 60;
+    if (min < 60)
+        return `${min}m ${sec}s`;
+    const hr = Math.floor(min / 60);
+    return `${hr}h ${min % 60}m`;
+}
+/** Color-code a latency value: green < 1000ms, yellow 1000-2000ms, red > 2000ms. */
+export function colorLatency(ms) {
+    if (ms === undefined || ms === null)
+        return '—';
+    const str = `${ms}ms`;
+    if (ms < 1000)
+        return chalk.green(str);
+    if (ms < 2000)
+        return chalk.yellow(str);
+    return chalk.red(str);
+}
+/** Format a role for conversation display. */
+export function formatRole(role) {
+    if (role === 'user')
+        return chalk.cyan(`[${role}]`.padEnd(12));
+    if (role === 'assistant')
+        return chalk.green(`[${role}]`.padEnd(12));
+    return chalk.dim(`[${role}]`.padEnd(12));
+}
+/** Calculate average of an array of numbers, ignoring undefined. */
+export function averageOf(values) {
+    const valid = values.filter((v) => v !== undefined && v !== null);
+    if (valid.length === 0)
+        return 0;
+    return Math.round(valid.reduce((sum, v) => sum + v, 0) / valid.length);
+}
+//# sourceMappingURL=format.js.map

package/dist/src/utils/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../../src/utils/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,oCAAoC;AACpC,MAAM,UAAU,iBAAiB;IAC/B,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACpD,OAAO,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC;AAC/B,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,UAAU,CAAC,KAAyB;IAClD,IAAI,CAAC,KAAK;QAAE,OAAO,WAAW,CAAC;IAC/B,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC;IACrC,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC;AACpC,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,eAAe,CAAC,EAAsB;IACpD,IAAI,CAAC,EAAE;QAAE,OAAO,GAAG,CAAC;IACpB,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;IACjC,OAAO,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE;QAClC,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,OAAO;QACd,GAAG,EAAE,SAAS;QACd,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,SAAS;QACjB,MAAM,EAAE,SAAS;QACjB,MAAM,EAAE,KAAK;KACd,CAAC,CAAC;AACL,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,YAAY,CAAC,EAAsB;IACjD,IAAI,CAAC,EAAE;QAAE,OAAO,GAAG,CAAC;IACpB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAC7C,MAAM,OAAO,GAAG,MAAM,GAAG,EAAE,CAAC;IAC5B,IAAI,OAAO,GAAG,CAAC;QAAE,OAAO,UAAU,CAAC;IACnC,IAAI,OAAO,GAAG,EAAE;QAAE,OAAO,GAAG,OAAO,OAAO,CAAC;IAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACzC,IAAI,OAAO,GAAG,EAAE;QAAE,OAAO,GAAG,OAAO,OAAO,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACxC,IAAI,MAAM,GAAG,EAAE;QAAE,OAAO,GAAG,MAAM,OAAO,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACxC,OAAO,GAAG,OAAO,OAAO,CAAC;AAC3B,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,IAAI,OAAO,GAAG,EAAE;QAAE,OAAO,GAAG,OAAO,GAAG,CAAC;IACvC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACrC,MAAM,GAAG,GAAG,OAAO,GAAG,EAAE,CAAC;IACzB,IAAI,GAAG,GAAG,EAAE;QAAE,OAAO,GAAG,GAAG,KAAK,GAAG,GAAG,CAAC;IACvC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;IAChC,OAAO,GAAG,EAAE,KAAK,GAAG,GAAG,EAAE,GAAG,CAAC;AAC/B,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,YAAY,CAAC,EAAsB;IACjD,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,GAAG,CAAC;IAChD,MAAM,GAAG,GAAG,GAAG,EAAE,IAAI,CAAC;IACtB,IAAI,EAAE,GAAG,IAAI;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,EAAE,GAAG,IAAI;QAAE,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACxC,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/D,IAAI,IAAI,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IACrE,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,SAAS,CAAC,MAA8B;IACtD,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;IAC/E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACjC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;AACzE,CAAC"}

package/dist/src/utils/hints.d.ts

@@ -0,0 +1,7 @@
+/** Display a truncated agent ID (first 12 characters). */
+export declare function shortId(id: string): string;
+export declare function hintAfterStart(agentId: string): string;
+export declare function hintAfterStop(): string;
+export declare function hintAfterLogin(): string;
+export declare function hintAfterList(): string;
+export declare function hintAfterHistory(agentId: string): string;

package/dist/src/utils/hints.js

@@ -0,0 +1,22 @@
+// ─── Short ID ───────────────────────────────────────────────────────────────
+/** Display a truncated agent ID (first 12 characters). */
+export function shortId(id) {
+    return id.slice(0, 12);
+}
+// ─── Next-Step Hints ────────────────────────────────────────────────────────
+export function hintAfterStart(agentId) {
+    return `Run \`convoai agent status ${shortId(agentId)}\` to check status.`;
+}
+export function hintAfterStop() {
+    return 'Run `convoai agent list` to see remaining agents.';
+}
+export function hintAfterLogin() {
+    return 'Run `convoai agent start --channel <name>` to start your first agent.';
+}
+export function hintAfterList() {
+    return 'Run `convoai agent status <id>` to inspect an agent.';
+}
+export function hintAfterHistory(agentId) {
+    return `Run \`convoai agent turns ${shortId(agentId)}\` to view turn-level latency.`;
+}
+//# sourceMappingURL=hints.js.map

package/dist/src/utils/hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hints.js","sourceRoot":"","sources":["../../../src/utils/hints.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAE/E,0DAA0D;AAC1D,MAAM,UAAU,OAAO,CAAC,EAAU;IAChC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACzB,CAAC;AAED,+EAA+E;AAE/E,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,OAAO,8BAA8B,OAAO,CAAC,OAAO,CAAC,qBAAqB,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,mDAAmD,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO,uEAAuE,CAAC;AACjF,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,sDAAsD,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,OAAO,6BAA6B,OAAO,CAAC,OAAO,CAAC,gCAAgC,CAAC;AACvF,CAAC"}

package/dist/src/utils/token.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Generate an RTC token for agent authentication.
+ * Uses app_certificate from config or AGORA_APP_CERTIFICATE env var.
+ * Returns undefined if no certificate is available (app may not require tokens).
+ */
+export declare function generateRtcToken(channelName: string, uid?: number, expireSeconds?: number): Promise<string | undefined>;

package/dist/src/utils/token.js

@@ -0,0 +1,26 @@
+import { loadConfig } from '../config/manager.js';
+/**
+ * Generate an RTC token for agent authentication.
+ * Uses app_certificate from config or AGORA_APP_CERTIFICATE env var.
+ * Returns undefined if no certificate is available (app may not require tokens).
+ */
+export async function generateRtcToken(channelName, uid = 0, expireSeconds = 86400) {
+    const config = loadConfig();
+    const appId = config.app_id;
+    const certificate = process.env.AGORA_APP_CERTIFICATE ?? config.app_certificate;
+    if (!appId || !certificate) {
+        return undefined;
+    }
+    try {
+        const pkg = await import('agora-token');
+        const mod = pkg.default ?? pkg;
+        const { RtcTokenBuilder, RtcRole } = mod;
+        const expireTs = Math.floor(Date.now() / 1000) + expireSeconds;
+        return RtcTokenBuilder.buildTokenWithUid(appId, certificate, channelName, uid, RtcRole.PUBLISHER, expireTs, expireTs);
+    }
+    catch {
+        // agora-token not installed or token generation failed
+        return undefined;
+    }
+}
+//# sourceMappingURL=token.js.map

package/dist/src/utils/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../../src/utils/token.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,WAAmB,EACnB,MAAc,CAAC,EACf,gBAAwB,KAAK;IAE7B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC;IAC5B,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,MAAM,CAAC,eAAe,CAAC;IAEhF,IAAI,CAAC,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;QAC3B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QACxC,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC;QAC/B,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC;QAEzC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,aAAa,CAAC;QAC/D,OAAO,eAAe,CAAC,iBAAiB,CACtC,KAAK,EACL,WAAW,EACX,WAAW,EACX,GAAG,EACH,OAAO,CAAC,SAAS,EACjB,QAAQ,EACR,QAAQ,CACT,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,uDAAuD;QACvD,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "convoai",
+  "version": "1.0.0",
+  "description": "CLI for Agora ConvoAI Engine — start, manage, and monitor conversational AI agents",
+  "type": "module",
+  "bin": {
+    "convoai": "./dist/bin/convoai.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx bin/convoai.ts",
+    "start": "node dist/bin/convoai.js",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "agora",
+    "convoai",
+    "conversational-ai",
+    "cli",
+    "voice-ai",
+    "realtime"
+  ],
+  "author": "Agora ConvoAI CLI Contributors",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AgoraIO-Community/convoai-cli"
+  },
+  "homepage": "https://github.com/AgoraIO-Community/convoai-cli#readme",
+  "bugs": {
+    "url": "https://github.com/AgoraIO-Community/convoai-cli/issues"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "src/web",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "agora-token": "^2.0.5",
+    "axios": "^1.7.0",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.1.0",
+    "inquirer": "^9.3.0",
+    "ora": "^8.1.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.7",
+    "@types/node": "^20.14.0",
+    "@vitest/coverage-v8": "^4.1.2",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/web/client.html

@@ -0,0 +1,136 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>ConvoAI Voice Chat</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #0a0a0a; color: #e0e0e0; min-height: 100vh; display: flex; flex-direction: column; align-items: center; justify-content: center; padding: 20px; }
+    .card { background: #1a1a1a; border: 1px solid #333; border-radius: 16px; padding: 32px; width: 100%; max-width: 420px; text-align: center; }
+    h1 { font-size: 22px; margin-bottom: 4px; color: #00c8ff; }
+    .channel-name { color: #00ff88; font-size: 18px; font-weight: 600; margin: 8px 0 24px; }
+    .status { font-size: 14px; margin-bottom: 16px; }
+    .status.connected { color: #00ff88; }
+    .status.disconnected { color: #666; }
+    .status.connecting { color: #ffaa00; }
+    .status.error { color: #ff4444; }
+    .pulse { width: 120px; height: 120px; border-radius: 50%; background: radial-gradient(circle, #00c8ff22, transparent); display: flex; align-items: center; justify-content: center; margin: 0 auto 24px; position: relative; }
+    .pulse.active { animation: pulse 1.5s ease-in-out infinite; }
+    .pulse-inner { width: 80px; height: 80px; border-radius: 50%; background: #1a1a1a; border: 3px solid #333; display: flex; align-items: center; justify-content: center; font-size: 32px; }
+    .pulse.active .pulse-inner { border-color: #00c8ff; }
+    @keyframes pulse { 0%, 100% { transform: scale(1); opacity: 0.5; } 50% { transform: scale(1.15); opacity: 1; } }
+    .volume-bar { height: 6px; background: #222; border-radius: 3px; margin: 0 auto 20px; width: 80%; overflow: hidden; }
+    .volume-fill { height: 100%; background: linear-gradient(90deg, #00c8ff, #00ff88); width: 0%; transition: width 0.1s; border-radius: 3px; }
+    .log { background: #0a0a0a; border: 1px solid #222; border-radius: 8px; padding: 12px; margin-top: 16px; max-height: 160px; overflow-y: auto; font-family: 'SF Mono', Monaco, monospace; font-size: 11px; line-height: 1.6; text-align: left; }
+    .log-entry { color: #555; }
+    .log-entry.info { color: #00c8ff; }
+    .log-entry.ok { color: #00ff88; }
+    .log-entry.err { color: #ff4444; }
+    .log-entry.audio { color: #ffaa00; }
+    .hint { color: #444; font-size: 11px; margin-top: 20px; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>ConvoAI Voice Chat</h1>
+    <div class="channel-name" id="channelDisplay">—</div>
+    <div class="pulse" id="pulse"><div class="pulse-inner" id="icon">🎙</div></div>
+    <div class="volume-bar"><div id="vol" class="volume-fill"></div></div>
+    <div class="status connecting" id="status">Connecting...</div>
+    <div class="log" id="log"></div>
+    <p class="hint">Press Ctrl+C in the terminal to stop</p>
+  </div>
+
+  <script src="https://download.agora.io/sdk/release/AgoraRTC_N-4.22.0.js"></script>
+  <script>
+    const P = new URLSearchParams(location.search);
+    const appId = P.get('appId');
+    const channel = P.get('channel');
+    const token = P.get('token') || null;
+    const uid = Number(P.get('uid')) || 0;
+
+    document.getElementById('channelDisplay').textContent = channel || '—';
+
+    let client, localTrack, volTimer;
+
+    function log(m, t='') {
+      const el = document.getElementById('log');
+      const d = document.createElement('div');
+      d.className = 'log-entry ' + t;
+      d.textContent = `${new Date().toLocaleTimeString()} ${m}`;
+      el.appendChild(d);
+      el.scrollTop = el.scrollHeight;
+    }
+
+    function setStatus(t, c) {
+      const el = document.getElementById('status');
+      el.textContent = t;
+      el.className = 'status ' + c;
+    }
+
+    async function start() {
+      if (!appId || !channel) {
+        setStatus('Missing appId or channel', 'error');
+        log('Error: appId and channel are required in URL params', 'err');
+        return;
+      }
+
+      try {
+        client = AgoraRTC.createClient({ mode: 'rtc', codec: 'vp8' });
+
+        client.on('user-published', async (user, mediaType) => {
+          await client.subscribe(user, mediaType);
+          if (mediaType === 'audio') {
+            user.audioTrack.play();
+            log('Agent speaking...', 'audio');
+            document.getElementById('pulse').classList.add('active');
+            document.getElementById('icon').textContent = '🔊';
+            if (volTimer) clearInterval(volTimer);
+            volTimer = setInterval(() => {
+              const v = user.audioTrack.getVolumeLevel();
+              document.getElementById('vol').style.width = (v * 100) + '%';
+            }, 100);
+          }
+        });
+
+        client.on('user-unpublished', (user, mediaType) => {
+          if (mediaType === 'audio') {
+            document.getElementById('pulse').classList.remove('active');
+            document.getElementById('icon').textContent = '🎙';
+            document.getElementById('vol').style.width = '0%';
+            log('Agent stopped speaking', 'info');
+          }
+        });
+
+        client.on('user-left', (user) => {
+          log('Agent left the channel', 'info');
+          document.getElementById('pulse').classList.remove('active');
+          document.getElementById('icon').textContent = '👋';
+          setStatus('Agent disconnected', 'disconnected');
+        });
+
+        log('Joining channel: ' + channel, 'info');
+        await client.join(appId, channel, token, uid || null);
+        log('Joined (uid: ' + (uid || 'auto') + ')', 'ok');
+
+        localTrack = await AgoraRTC.createMicrophoneAudioTrack();
+        await client.publish([localTrack]);
+        log('Microphone live — speak now!', 'ok');
+        setStatus('Connected — speak to the agent!', 'connected');
+
+      } catch (err) {
+        log('Error: ' + err.message, 'err');
+        setStatus('Failed: ' + err.message, 'error');
+      }
+    }
+
+    window.addEventListener('beforeunload', async () => {
+      if (localTrack) { localTrack.stop(); localTrack.close(); }
+      if (client) await client.leave();
+    });
+
+    start();
+  </script>
+</body>
+</html>