convoai 1.0.0

package/bin/convoai.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../src/index.js';
+run();

package/dist/bin/convoai.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/convoai.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from '../src/index.js';
+run();
+//# sourceMappingURL=convoai.js.map

package/dist/bin/convoai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convoai.js","sourceRoot":"","sources":["../../bin/convoai.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AACtC,GAAG,EAAE,CAAC"}

package/dist/src/api/agents.d.ts

@@ -0,0 +1,24 @@
+import type { AxiosInstance } from 'axios';
+import type { StartAgentRequest, StartAgentResponse, QueryAgentResponse, ListAgentsParams, ListAgentsResponse, UpdateAgentRequest, UpdateAgentResponse, SpeakRequest, SpeakResponse, HistoryResponse, TurnsResponse } from './types.js';
+export declare class AgentAPI {
+    private readonly client;
+    constructor(client: AxiosInstance);
+    /** Start (join) a new conversational AI agent. */
+    start(req: StartAgentRequest): Promise<StartAgentResponse>;
+    /** Stop (leave) a running agent. */
+    stop(agentId: string): Promise<void>;
+    /** Query the current status of an agent. */
+    status(agentId: string): Promise<QueryAgentResponse>;
+    /** List agents with optional filters. */
+    list(params?: ListAgentsParams): Promise<ListAgentsResponse>;
+    /** Update a running agent's properties (e.g. token, LLM config). */
+    update(agentId: string, req: UpdateAgentRequest): Promise<UpdateAgentResponse>;
+    /** Instruct an agent to speak the given text. */
+    speak(agentId: string, req: SpeakRequest): Promise<SpeakResponse>;
+    /** Interrupt an agent that is currently speaking. */
+    interrupt(agentId: string): Promise<void>;
+    /** Retrieve conversation history for an agent. */
+    history(agentId: string): Promise<HistoryResponse>;
+    /** Retrieve turn-level analytics for an agent. */
+    turns(agentId: string): Promise<TurnsResponse>;
+}

package/dist/src/api/agents.js

@@ -0,0 +1,51 @@
+// ─── Agent API ──────────────────────────────────────────────────────────────
+export class AgentAPI {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Start (join) a new conversational AI agent. */
+    async start(req) {
+        const { data } = await this.client.post('/join', req);
+        return data;
+    }
+    /** Stop (leave) a running agent. */
+    async stop(agentId) {
+        await this.client.post(`/agents/${agentId}/leave`);
+    }
+    /** Query the current status of an agent. */
+    async status(agentId) {
+        const { data } = await this.client.get(`/agents/${agentId}`);
+        return data;
+    }
+    /** List agents with optional filters. */
+    async list(params) {
+        const { data } = await this.client.get('/agents', { params });
+        return data;
+    }
+    /** Update a running agent's properties (e.g. token, LLM config). */
+    async update(agentId, req) {
+        const { data } = await this.client.post(`/agents/${agentId}/update`, req);
+        return data;
+    }
+    /** Instruct an agent to speak the given text. */
+    async speak(agentId, req) {
+        const { data } = await this.client.post(`/agents/${agentId}/speak`, req);
+        return data;
+    }
+    /** Interrupt an agent that is currently speaking. */
+    async interrupt(agentId) {
+        await this.client.post(`/agents/${agentId}/interrupt`);
+    }
+    /** Retrieve conversation history for an agent. */
+    async history(agentId) {
+        const { data } = await this.client.get(`/agents/${agentId}/history`);
+        return data;
+    }
+    /** Retrieve turn-level analytics for an agent. */
+    async turns(agentId) {
+        const { data } = await this.client.get(`/agents/${agentId}/turns`);
+        return data;
+    }
+}
+//# sourceMappingURL=agents.js.map

package/dist/src/api/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../../../src/api/agents.ts"],"names":[],"mappings":"AAeA,+EAA+E;AAE/E,MAAM,OAAO,QAAQ;IACU;IAA7B,YAA6B,MAAqB;QAArB,WAAM,GAAN,MAAM,CAAe;IAAG,CAAC;IAEtD,kDAAkD;IAClD,KAAK,CAAC,KAAK,CAAC,GAAsB;QAChC,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAqB,OAAO,EAAE,GAAG,CAAC,CAAC;QAC1E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,oCAAoC;IACpC,KAAK,CAAC,IAAI,CAAC,OAAe;QACxB,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,OAAO,QAAQ,CAAC,CAAC;IACrD,CAAC;IAED,4CAA4C;IAC5C,KAAK,CAAC,MAAM,CAAC,OAAe;QAC1B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAqB,WAAW,OAAO,EAAE,CAAC,CAAC;QACjF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,yCAAyC;IACzC,KAAK,CAAC,IAAI,CAAC,MAAyB;QAClC,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAqB,SAAS,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QAClF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,oEAAoE;IACpE,KAAK,CAAC,MAAM,CAAC,OAAe,EAAE,GAAuB;QACnD,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CACrC,WAAW,OAAO,SAAS,EAC3B,GAAG,CACJ,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,iDAAiD;IACjD,KAAK,CAAC,KAAK,CAAC,OAAe,EAAE,GAAiB;QAC5C,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CACrC,WAAW,OAAO,QAAQ,EAC1B,GAAG,CACJ,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,qDAAqD;IACrD,KAAK,CAAC,SAAS,CAAC,OAAe;QAC7B,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,OAAO,YAAY,CAAC,CAAC;IACzD,CAAC;IAED,kDAAkD;IAClD,KAAK,CAAC,OAAO,CAAC,OAAe;QAC3B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CACpC,WAAW,OAAO,UAAU,CAC7B,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kDAAkD;IAClD,KAAK,CAAC,KAAK,CAAC,OAAe;QACzB,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAgB,WAAW,OAAO,QAAQ,CAAC,CAAC;QAClF,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/src/api/calls.d.ts

@@ -0,0 +1,53 @@
+import type { AxiosInstance } from 'axios';
+export interface InitiateCallRequest {
+    name: string;
+    properties: {
+        channel: string;
+        phone_number: string;
+        agent_rtc_uid?: string;
+        idle_timeout?: number;
+        llm?: {
+            url?: string;
+            api_key?: string;
+            system_messages?: Array<{
+                role: string;
+                content: string;
+            }>;
+            greeting_message?: string;
+            params?: {
+                model?: string;
+                max_tokens?: number;
+                temperature?: number;
+            };
+        };
+        tts?: {
+            vendor?: string;
+            params?: Record<string, unknown>;
+        };
+        asr?: {
+            language?: string;
+            vendor?: string;
+        };
+    };
+}
+export interface CallStatusResponse {
+    agent_id: string;
+    status: string;
+    direction: 'inbound' | 'outbound';
+    phone_number?: string;
+    start_ts: number;
+    end_ts?: number;
+}
+export declare class CallAPI {
+    private readonly client;
+    constructor(client: AxiosInstance);
+    /** Initiate an outbound phone call. */
+    initiate(req: InitiateCallRequest): Promise<{
+        agent_id: string;
+        status: string;
+    }>;
+    /** Hang up an active call. */
+    hangup(agentId: string): Promise<void>;
+    /** Get the current status of a call. */
+    status(agentId: string): Promise<CallStatusResponse>;
+}

package/dist/src/api/calls.js

@@ -0,0 +1,22 @@
+// ─── Call API ───────────────────────────────────────────────────────────────
+export class CallAPI {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Initiate an outbound phone call. */
+    async initiate(req) {
+        const { data } = await this.client.post('/call', req);
+        return data;
+    }
+    /** Hang up an active call. */
+    async hangup(agentId) {
+        await this.client.post(`/calls/${agentId}/hangup`);
+    }
+    /** Get the current status of a call. */
+    async status(agentId) {
+        const { data } = await this.client.get(`/calls/${agentId}`);
+        return data;
+    }
+}
+//# sourceMappingURL=calls.js.map

package/dist/src/api/calls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calls.js","sourceRoot":"","sources":["../../../src/api/calls.ts"],"names":[],"mappings":"AAgCA,+EAA+E;AAE/E,MAAM,OAAO,OAAO;IACW;IAA7B,YAA6B,MAAqB;QAArB,WAAM,GAAN,MAAM,CAAe;IAAG,CAAC;IAEtD,uCAAuC;IACvC,KAAK,CAAC,QAAQ,CAAC,GAAwB;QACrC,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAuC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC5F,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8BAA8B;IAC9B,KAAK,CAAC,MAAM,CAAC,OAAe;QAC1B,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,OAAO,SAAS,CAAC,CAAC;IACrD,CAAC;IAED,wCAAwC;IACxC,KAAK,CAAC,MAAM,CAAC,OAAe;QAC1B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAqB,UAAU,OAAO,EAAE,CAAC,CAAC;QAChF,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/src/api/client.d.ts

@@ -0,0 +1,10 @@
+import { type AxiosInstance } from 'axios';
+export interface ClientConfig {
+    appId: string;
+    customerId: string;
+    customerSecret: string;
+    baseUrl?: string;
+    region?: 'global' | 'cn';
+}
+export declare function resolveBaseUrl(appId: string, region?: string, customBaseUrl?: string): string;
+export declare function createClient(config: ClientConfig): AxiosInstance;

package/dist/src/api/client.js

@@ -0,0 +1,63 @@
+import axios from 'axios';
+// ─── Base URL Resolution ────────────────────────────────────────────────────
+const BASE_URLS = {
+    global: 'https://api.agora.io/api/conversational-ai-agent/v2/projects',
+    cn: 'https://api.agora.io/cn/api/conversational-ai-agent/v2/projects',
+};
+export function resolveBaseUrl(appId, region, customBaseUrl) {
+    if (customBaseUrl) {
+        // If custom URL already contains the appId path segment, use as-is
+        return customBaseUrl.replace(/\/$/, '');
+    }
+    const base = BASE_URLS[region ?? 'global'] ?? BASE_URLS.global;
+    return `${base}/${appId}`;
+}
+// ─── Retry Helpers ─────────────────────────────────────────────────────────
+const RETRY_STATUS_CODES = new Set([429, 500, 502, 503, 504]);
+const MAX_RETRIES = 3;
+const BASE_DELAY_MS = 1000;
+async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ─── Client Factory ─────────────────────────────────────────────────────────
+export function createClient(config) {
+    const { appId, customerId, customerSecret, baseUrl, region } = config;
+    const resolvedUrl = resolveBaseUrl(appId, region, baseUrl);
+    const credentials = Buffer.from(`${customerId}:${customerSecret}`).toString('base64');
+    const client = axios.create({
+        baseURL: resolvedUrl,
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Basic ${credentials}`,
+        },
+        timeout: 60_000,
+    });
+    // ── Response interceptor: retry + normalize API errors ───────────────────
+    client.interceptors.response.use((res) => res, async (error) => {
+        const config = error.config;
+        const status = error.response?.status;
+        // Retry on retryable status codes
+        if (config && status && RETRY_STATUS_CODES.has(status)) {
+            const retryCount = (config.__retryCount ?? 0);
+            if (retryCount < MAX_RETRIES) {
+                config.__retryCount = retryCount + 1;
+                const delay = BASE_DELAY_MS * Math.pow(2, retryCount);
+                await sleep(delay);
+                return client.request(config);
+            }
+        }
+        // Format the error
+        if (error.response?.data) {
+            const { detail, reason } = error.response.data;
+            const message = detail || reason || error.message;
+            const formatted = new Error(`API Error ${status}: ${message}`);
+            formatted.status = status;
+            formatted.detail = detail;
+            formatted.reason = reason;
+            return Promise.reject(formatted);
+        }
+        return Promise.reject(error);
+    });
+    return client;
+}
+//# sourceMappingURL=client.js.map

package/dist/src/api/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/api/client.ts"],"names":[],"mappings":"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"}

package/dist/src/api/types.d.ts

@@ -0,0 +1,207 @@
+export type AgentStatus = 'IDLE' | 'STARTING' | 'RUNNING' | 'STOPPING' | 'STOPPED' | 'RECOVERING' | 'FAILED';
+export declare const AgentStatusCode: Record<number, AgentStatus>;
+export declare const AgentStatusNumber: Record<AgentStatus, number>;
+export interface TurnDetection {
+    type?: 'agora_vad' | 'server_vad' | 'semantic_vad';
+    interrupt_mode?: 'interrupt' | 'append' | 'ignore' | 'adaptive';
+    silence_duration_ms?: number;
+    interrupt_duration_ms?: number;
+    prefix_padding_ms?: number;
+    threshold?: number;
+}
+export interface LLMConfig {
+    url?: string;
+    api_key?: string;
+    vendor?: string;
+    style?: 'openai' | 'gemini' | 'anthropic' | 'dify';
+    model?: string;
+    headers?: string;
+    system_messages?: Array<Record<string, unknown>>;
+    greeting_message?: string;
+    failure_message?: string;
+    max_history?: number;
+    input_modalities?: string[];
+    output_modalities?: string[];
+    params?: {
+        model?: string;
+        max_tokens?: number;
+        temperature?: number;
+        top_p?: number;
+        [key: string]: unknown;
+    };
+}
+export interface TTSConfig {
+    vendor?: string;
+    params?: {
+        key?: string;
+        region?: string;
+        voice_name?: string;
+        speed?: number;
+        volume?: number;
+        sample_rate?: number;
+        [key: string]: unknown;
+    };
+}
+export interface ASRConfig {
+    language?: string;
+    vendor?: string;
+    params?: {
+        key?: string;
+        model?: string;
+        language?: string;
+        [key: string]: unknown;
+    };
+}
+export interface AdvancedFeatures {
+    enable_aivad?: boolean;
+    enable_rtm?: boolean;
+    enable_mllm?: boolean;
+    enable_sal?: boolean;
+    enable_mcp?: boolean;
+}
+export interface SilenceConfig {
+    timeout_ms?: number;
+    action?: 'speak' | 'leave';
+    content?: string;
+}
+export interface AgentParameters {
+    silence_config?: SilenceConfig;
+    data_channel?: string;
+    enable_metrics?: boolean;
+    enable_error_message?: boolean;
+}
+export interface AgentProperties {
+    channel: string;
+    token?: string;
+    agent_rtc_uid?: string;
+    remote_rtc_uids?: string[];
+    enable_string_uid?: boolean;
+    idle_timeout?: number;
+    llm?: LLMConfig;
+    tts?: TTSConfig;
+    asr?: ASRConfig;
+    turn_detection?: TurnDetection;
+    parameters?: AgentParameters;
+    advanced_features?: AdvancedFeatures;
+    labels?: Record<string, string>;
+}
+export interface StartAgentRequest {
+    name: string;
+    properties?: AgentProperties;
+    preset?: string;
+    pipeline_id?: string;
+}
+export interface StartAgentResponse {
+    agent_id: string;
+    create_ts: number;
+    status: AgentStatus;
+}
+export interface QueryAgentResponse {
+    agent_id: string;
+    status: AgentStatus;
+    start_ts: number;
+    stop_ts?: number;
+    message?: string;
+    channel?: string;
+}
+export interface ListAgentsParams {
+    state?: number;
+    limit?: number;
+    channel?: string;
+    from_time?: number;
+    to_time?: number;
+    cursor?: string;
+}
+export interface ListAgentsResponse {
+    data: {
+        count: number;
+        list: Array<{
+            agent_id: string;
+            status: AgentStatus;
+            start_ts: number;
+            stop_ts?: number;
+            channel?: string;
+        }>;
+    };
+    meta: {
+        cursor?: string;
+        total?: number;
+    };
+    status: string;
+}
+export interface UpdateAgentRequest {
+    properties: Partial<Pick<AgentProperties, 'token' | 'llm'>>;
+}
+export interface UpdateAgentResponse {
+    agent_id: string;
+    create_ts: number;
+    status: AgentStatus;
+}
+export type SpeakPriority = 'INTERRUPT' | 'APPEND' | 'IGNORE';
+export interface SpeakRequest {
+    text: string;
+    priority?: SpeakPriority;
+    interrupt?: boolean;
+}
+export interface SpeakResponse {
+    agent_id: string;
+    channel: string;
+    start_ts: number;
+}
+export interface HistoryEntry {
+    role: 'user' | 'assistant';
+    content: string;
+    turn_id?: string;
+    timestamp?: number;
+    metadata?: {
+        source?: string;
+        interrupted?: boolean;
+    };
+}
+export interface HistoryResponse {
+    agent_id: string;
+    start_ts: number;
+    status: AgentStatus;
+    contents: HistoryEntry[];
+}
+export interface TurnEntry {
+    turn_id: string;
+    start_ts: number;
+    end_ts: number;
+    type: 'voice_input' | 'greeting' | 'silence_timeout' | 'api_speak';
+    end_reason: 'ok' | 'interrupted' | 'ignored' | 'error';
+    e2e_latency_ms?: number;
+    segmented_latency_ms?: {
+        asr_ms?: number;
+        llm_ms?: number;
+        tts_ms?: number;
+    };
+}
+export interface TurnsResponse {
+    agent_id: string;
+    turns: TurnEntry[];
+}
+export interface ApiErrorResponse {
+    detail: string;
+    reason: string;
+}
+export interface ConvoAIConfig {
+    app_id?: string;
+    app_certificate?: string;
+    customer_id?: string;
+    customer_secret?: string;
+    base_url?: string;
+    region?: 'global' | 'cn';
+    default_profile?: string;
+    profiles?: Record<string, ProfileConfig>;
+}
+export interface ProfileConfig {
+    app_id?: string;
+    customer_id?: string;
+    customer_secret?: string;
+    base_url?: string;
+    region?: 'global' | 'cn';
+    llm?: Partial<LLMConfig>;
+    tts?: Partial<TTSConfig>;
+    asr?: Partial<ASRConfig>;
+}

package/dist/src/api/types.js

@@ -0,0 +1,20 @@
+// ─── Agent Status ────────────────────────────────────────────────────────────
+export const AgentStatusCode = {
+    0: 'IDLE',
+    1: 'STARTING',
+    2: 'RUNNING',
+    3: 'STOPPING',
+    4: 'STOPPED',
+    5: 'RECOVERING',
+    6: 'FAILED',
+};
+export const AgentStatusNumber = {
+    IDLE: 0,
+    STARTING: 1,
+    RUNNING: 2,
+    STOPPING: 3,
+    STOPPED: 4,
+    RECOVERING: 5,
+    FAILED: 6,
+};
+//# sourceMappingURL=types.js.map

package/dist/src/api/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/api/types.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAWhF,MAAM,CAAC,MAAM,eAAe,GAAgC;IAC1D,CAAC,EAAE,MAAM;IACT,CAAC,EAAE,UAAU;IACb,CAAC,EAAE,SAAS;IACZ,CAAC,EAAE,UAAU;IACb,CAAC,EAAE,SAAS;IACZ,CAAC,EAAE,YAAY;IACf,CAAC,EAAE,QAAQ;CACZ,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAgC;IAC5D,IAAI,EAAE,CAAC;IACP,QAAQ,EAAE,CAAC;IACX,OAAO,EAAE,CAAC;IACV,QAAQ,EAAE,CAAC;IACX,OAAO,EAAE,CAAC;IACV,UAAU,EAAE,CAAC;IACb,MAAM,EAAE,CAAC;CACV,CAAC"}

package/dist/src/commands/agent/_helpers.d.ts

@@ -0,0 +1,7 @@
+import { AgentAPI } from '../../api/agents.js';
+/**
+ * Resolve config for the given profile, create an authenticated HTTP client,
+ * and return a ready-to-use AgentAPI instance.
+ */
+export declare function getAgentAPI(profileName?: string): AgentAPI;
+export { formatTimestamp, relativeTime } from '../../utils/format.js';

package/dist/src/commands/agent/_helpers.js

@@ -0,0 +1,32 @@
+import { resolveConfig } from '../../config/manager.js';
+import { createClient } from '../../api/client.js';
+import { AgentAPI } from '../../api/agents.js';
+// ─── Agent API Factory ─────────────────────────────────────────────────────
+/**
+ * Resolve config for the given profile, create an authenticated HTTP client,
+ * and return a ready-to-use AgentAPI instance.
+ */
+export function getAgentAPI(profileName) {
+    const config = resolveConfig(profileName);
+    if (!config.app_id || !config.customer_id || !config.customer_secret) {
+        const missing = [];
+        if (!config.app_id)
+            missing.push('app_id');
+        if (!config.customer_id)
+            missing.push('customer_id');
+        if (!config.customer_secret)
+            missing.push('customer_secret');
+        throw new Error(`Missing required credentials: ${missing.join(', ')}. Run "convoai auth login" to configure.`);
+    }
+    const client = createClient({
+        appId: config.app_id,
+        customerId: config.customer_id,
+        customerSecret: config.customer_secret,
+        baseUrl: config.base_url,
+        region: config.region,
+    });
+    return new AgentAPI(client);
+}
+// ─── Timestamp Formatting (re-exported from shared utils) ─────────────────
+export { formatTimestamp, relativeTime } from '../../utils/format.js';
+//# sourceMappingURL=_helpers.js.map

package/dist/src/commands/agent/_helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_helpers.js","sourceRoot":"","sources":["../../../../src/commands/agent/_helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,WAAoB;IAC9C,MAAM,MAAM,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IAE1C,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;QACrE,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,IAAI,CAAC,MAAM,CAAC,MAAM;YAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,CAAC,WAAW;YAAE,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QACrD,IAAI,CAAC,MAAM,CAAC,eAAe;YAAE,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAC7D,MAAM,IAAI,KAAK,CACb,iCAAiC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,0CAA0C,CAC9F,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC;QAC1B,KAAK,EAAE,MAAM,CAAC,MAAM;QACpB,UAAU,EAAE,MAAM,CAAC,WAAW;QAC9B,cAAc,EAAE,MAAM,CAAC,eAAe;QACtC,OAAO,EAAE,MAAM,CAAC,QAAQ;QACxB,MAAM,EAAE,MAAM,CAAC,MAAqC;KACrD,CAAC,CAAC;IACH,OAAO,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC;AAED,6EAA6E;AAE7E,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/src/commands/agent/history.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerAgentHistory(program: Command): void;

package/dist/src/commands/agent/history.js

@@ -0,0 +1,78 @@
+import chalk from 'chalk';
+import { getAgentAPI, formatTimestamp } from './_helpers.js';
+import { withSpinner } from '../../ui/spinner.js';
+import { handleError } from '../../utils/errors.js';
+import { hintAfterHistory, shortId } from '../../utils/hints.js';
+import { printHint } from '../../ui/output.js';
+import { colorStatus, dim } from '../../ui/colors.js';
+// ─── Command Registration ──────────────────────────────────────────────────
+export function registerAgentHistory(program) {
+    program
+        .command('history <agent-id>')
+        .description('View conversation history for an agent')
+        .option('--profile <name>', 'Use a named config profile')
+        .option('--json', 'Output result as JSON')
+        .option('--limit <n>', 'Show only the last N entries', parseInt)
+        .action(async (agentId, opts) => {
+        try {
+            await historyAction(agentId, opts);
+        }
+        catch (error) {
+            handleError(error, { json: opts.json });
+        }
+    });
+}
+// ─── Action ────────────────────────────────────────────────────────────────
+async function historyAction(agentId, opts) {
+    const api = getAgentAPI(opts.profile);
+    const data = await withSpinner('Fetching history...', () => api.history(agentId));
+    const allContents = data.contents ?? [];
+    if (opts.json) {
+        const output = opts.limit
+            ? { ...data, contents: allContents.slice(-opts.limit) }
+            : data;
+        console.log(JSON.stringify(output, null, 2));
+        return;
+    }
+    const entries = opts.limit
+        ? allContents.slice(-opts.limit)
+        : allContents;
+    // ── Header ──────────────────────────────────────────────────────────────
+    console.log();
+    console.log(`Agent: ${chalk.bold(shortId(data.agent_id))} | Status: ${colorStatus(data.status)} | Since: ${formatTimestamp(data.start_ts)}`);
+    console.log();
+    // ── Conversation ────────────────────────────────────────────────────────
+    if (entries.length === 0) {
+        console.log(dim('  No conversation history yet.'));
+    }
+    else {
+        for (const entry of entries) {
+            printEntry(entry);
+        }
+    }
+    // ── Footer ──────────────────────────────────────────────────────────────
+    console.log();
+    const totalCount = allContents.length;
+    const shownCount = entries.length;
+    if (opts.limit && totalCount > shownCount) {
+        console.log(dim(`Showing ${shownCount} of ${totalCount} entries.`));
+    }
+    else {
+        console.log(dim(`${totalCount} entries total.`));
+    }
+    printHint(hintAfterHistory(agentId));
+}
+// ─── Helpers ───────────────────────────────────────────────────────────────
+function printEntry(entry) {
+    const roleTag = formatRole(entry.role);
+    // Wrap long content to keep output readable
+    const content = entry.content || dim('(empty)');
+    console.log(`${roleTag} ${content}`);
+}
+function formatRole(role) {
+    const padded = `[${role}]`.padEnd(13);
+    return role === 'user'
+        ? chalk.cyan(padded)
+        : chalk.green(padded);
+}
+//# sourceMappingURL=history.js.map

package/dist/src/commands/agent/history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.js","sourceRoot":"","sources":["../../../../src/commands/agent/history.ts"],"names":[],"mappings":"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"}

package/dist/src/commands/agent/interrupt.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerAgentInterrupt(program: Command): void;