newo 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.0] - 2025-09-16
+
+### Added
+- **User Conversations Pull Functionality**: Complete conversation history extraction
+  - New `newo conversations` command to download user conversations and personas
+  - Multi-customer conversation support with `--customer <idn>` flag
+  - Chat History API integration (`/api/v1/chat/history`) with fallback to conversations acts API
+  - Automatic phone number extraction from persona actors
+  - Comprehensive pagination handling for large conversation datasets
+  - Clean YAML output format in `newo_customers/{customerIdn}/conversations.yaml`
+
+### Enhanced
+- **Conversation Data Processing**: Optimized structure and chronological ordering
+  - Acts sorted by datetime ascending (chronological conversation flow)
+  - Personas sorted by most recent activity (descending)
+  - Redundant fields removed (`is_agent`, `session_id: unknown`, etc.)
+  - Clean persona structure: `id` → `name` → `phone` → `act_count` → `acts`
+  - Proper datetime extraction from chat history API responses
+
+### Technical
+- **New API Functions**: Type-safe conversation API integration
+  - `listUserPersonas()` - Get all user personas with pagination
+  - `getChatHistory()` - Get conversation history for user actors
+  - `getConversationActs()` - Fallback for accounts with proper permissions
+  - `pullConversations()` - Complete conversation sync orchestration
+- **NPM Scripts**: Added convenient conversation commands
+  - `npm run conversations` - Build and pull conversations
+  - `npm run conversations:all` - Legacy alias for compatibility
+
+### Performance
+- **Concurrent Processing**: Efficient conversation data extraction
+  - Parallel API calls with concurrency limiting (p-limit)
+  - Graceful error handling with persona-level fault tolerance
+  - No artificial limits on personas or acts (loads all available data)
+  - Multi-customer support with authentication reuse
+
 ## [1.8.0] - 2025-09-15
 
 ### Added

package/dist/api.d.ts

@@ -1,5 +1,5 @@
 import { type AxiosInstance } from 'axios';
-import type { ProjectMeta, Agent, Skill, FlowEvent, FlowState, AkbImportArticle, CustomerProfile, CustomerAttribute, CustomerAttributesResponse } from './types.js';
+import type { ProjectMeta, Agent, Skill, FlowEvent, FlowState, AkbImportArticle, CustomerProfile, CustomerAttribute, CustomerAttributesResponse, UserPersonaResponse, UserPersona, ConversationActsResponse, ConversationActsParams, ChatHistoryParams, ChatHistoryResponse } from './types.js';
 export declare function makeClient(verbose?: boolean, token?: string): Promise<AxiosInstance>;
 export declare function listProjects(client: AxiosInstance): Promise<ProjectMeta[]>;
 export declare function listAgents(client: AxiosInstance, projectId: string): Promise<Agent[]>;
@@ -13,4 +13,12 @@ export declare function importAkbArticle(client: AxiosInstance, articleData: Akb
 export declare function getCustomerProfile(client: AxiosInstance): Promise<CustomerProfile>;
 export declare function getCustomerAttributes(client: AxiosInstance, includeHidden?: boolean): Promise<CustomerAttributesResponse>;
 export declare function updateCustomerAttribute(client: AxiosInstance, attribute: CustomerAttribute): Promise<void>;
+export declare function listUserPersonas(client: AxiosInstance, page?: number, per?: number): Promise<UserPersonaResponse>;
+export declare function getUserPersona(client: AxiosInstance, personaId: string): Promise<UserPersona>;
+export declare function getAccount(client: AxiosInstance): Promise<{
+    id: string;
+    [key: string]: any;
+}>;
+export declare function getConversationActs(client: AxiosInstance, params: ConversationActsParams): Promise<ConversationActsResponse>;
+export declare function getChatHistory(client: AxiosInstance, params: ChatHistoryParams): Promise<ChatHistoryResponse>;
 //# sourceMappingURL=api.d.ts.map

package/dist/api.js

@@ -121,4 +121,54 @@ export async function updateCustomerAttribute(client, attribute) {
         value_type: attribute.value_type
     });
 }
+// Conversation API Functions
+export async function listUserPersonas(client, page = 1, per = 50) {
+    const response = await client.get('/api/v1/bff/conversations/user-personas', {
+        params: { page, per }
+    });
+    return response.data;
+}
+export async function getUserPersona(client, personaId) {
+    const response = await client.get(`/api/v1/bff/conversations/user-personas/${personaId}`);
+    return response.data;
+}
+export async function getAccount(client) {
+    const response = await client.get('/api/v1/account');
+    return response.data;
+}
+export async function getConversationActs(client, params) {
+    const queryParams = {
+        user_persona_id: params.user_persona_id,
+        page: params.page || 1,
+        per: params.per || 50
+    };
+    // Only add optional parameters if explicitly provided
+    if (params.turn_type)
+        queryParams.turn_type = params.turn_type;
+    if (params.connectors)
+        queryParams.connectors = params.connectors;
+    if (params.from_date)
+        queryParams.from_date = params.from_date;
+    if (params.to_date)
+        queryParams.to_date = params.to_date;
+    const response = await client.get('/api/v1/bff/conversations/acts', {
+        params: queryParams
+    });
+    return response.data;
+}
+export async function getChatHistory(client, params) {
+    const queryParams = {
+        user_actor_id: params.user_actor_id,
+        page: params.page || 1,
+        per: params.per || 50
+    };
+    // Only add agent_actor_id if provided
+    if (params.agent_actor_id) {
+        queryParams.agent_actor_id = params.agent_actor_id;
+    }
+    const response = await client.get('/api/v1/chat/history', {
+        params: queryParams
+    });
+    return response.data;
+}
 //# sourceMappingURL=api.js.map

package/dist/cli.js

@@ -2,7 +2,7 @@
 import minimist from 'minimist';
 import dotenv from 'dotenv';
 import { makeClient, getProjectMeta, importAkbArticle } from './api.js';
-import { pullAll, pushChanged, status, saveCustomerAttributes } from './sync.js';
+import { pullAll, pushChanged, status, saveCustomerAttributes, pullConversations } from './sync.js';
 import { parseAkbFile, prepareArticlesForImport } from './akb.js';
 import { initializeEnvironment, ENV, EnvValidationError } from './env.js';
 import { parseCustomerConfigAsync, listCustomers, getCustomer, getDefaultCustomer, tryGetDefaultCustomer, getAllCustomers, validateCustomerConfig } from './customerAsync.js';
@@ -160,12 +160,14 @@ Usage:
   newo pull [--customer <idn>]                  # download projects -> ./newo_customers/<idn>/projects/
   newo push [--customer <idn>]                  # upload modified *.guidance/*.jinja back to NEWO
   newo status [--customer <idn>]                # show modified files
+  newo conversations [--customer <idn>] [--all] # download user conversations -> ./newo_customers/<idn>/conversations.yaml
   newo list-customers                           # list available customers
   newo meta [--customer <idn>]                  # get project metadata (debug)
   newo import-akb <file> <persona_id> [--customer <idn>]  # import AKB articles from file
 
 Flags:
   --customer <idn>             # specify customer (if not set, uses default or interactive selection)
+  --all                        # include all available data (for conversations: all personas and acts)
   --verbose, -v                # enable detailed logging
 
 Environment Variables:
@@ -343,6 +345,53 @@ File Structure:
         }
         return;
     }
+    if (cmd === 'conversations') {
+        // Handle customer selection for conversations command
+        if (args.customer) {
+            const customer = getCustomer(customerConfig, args.customer);
+            if (!customer) {
+                console.error(`Unknown customer: ${args.customer}`);
+                console.error(`Available customers: ${listCustomers(customerConfig).join(', ')}`);
+                process.exit(1);
+            }
+            selectedCustomer = customer;
+        }
+        else {
+            // Try to get default, fall back to all customers
+            selectedCustomer = tryGetDefaultCustomer(customerConfig);
+            if (!selectedCustomer) {
+                allCustomers = getAllCustomers(customerConfig);
+                if (verbose)
+                    console.log(`💬 No default customer specified, pulling conversations from all ${allCustomers.length} customers`);
+            }
+        }
+        // Parse conversation-specific options - load all data by default
+        const conversationOptions = {
+            includeAll: true, // Always include all data for conversations
+            maxPersonas: undefined, // No limit on personas
+            maxActsPerPersona: undefined // No limit on acts per persona
+        };
+        if (selectedCustomer) {
+            // Single customer conversations
+            const accessToken = await getValidAccessToken(selectedCustomer);
+            const client = await makeClient(verbose, accessToken);
+            console.log(`💬 Pulling conversations for customer: ${selectedCustomer.idn} (all data)`);
+            await pullConversations(client, selectedCustomer, conversationOptions, verbose);
+            console.log(`✅ Conversations saved to newo_customers/${selectedCustomer.idn}/conversations.yaml`);
+        }
+        else if (allCustomers.length > 0) {
+            // Multi-customer conversations
+            console.log(`💬 Pulling conversations from ${allCustomers.length} customers (all data)...`);
+            for (const customer of allCustomers) {
+                console.log(`\n💬 Pulling conversations for customer: ${customer.idn}`);
+                const accessToken = await getValidAccessToken(customer);
+                const client = await makeClient(verbose, accessToken);
+                await pullConversations(client, customer, conversationOptions, verbose);
+            }
+            console.log(`\n✅ Conversations pull completed for all ${allCustomers.length} customers`);
+        }
+        return;
+    }
     // For all other commands, require a single selected customer
     if (args.customer) {
         const customer = getCustomer(customerConfig, args.customer);

package/dist/sync.d.ts

@@ -1,8 +1,9 @@
 import type { AxiosInstance } from 'axios';
-import type { ProjectData, CustomerConfig } from './types.js';
+import type { ProjectData, CustomerConfig, ConversationOptions } from './types.js';
 export declare function saveCustomerAttributes(client: AxiosInstance, customer: CustomerConfig, verbose?: boolean): Promise<void>;
 export declare function pullSingleProject(client: AxiosInstance, customer: CustomerConfig, projectId: string, projectIdn: string, verbose?: boolean): Promise<ProjectData>;
 export declare function pullAll(client: AxiosInstance, customer: CustomerConfig, projectId?: string | null, verbose?: boolean): Promise<void>;
 export declare function pushChanged(client: AxiosInstance, customer: CustomerConfig, verbose?: boolean): Promise<void>;
 export declare function status(customer: CustomerConfig, verbose?: boolean): Promise<void>;
+export declare function pullConversations(client: AxiosInstance, customer: CustomerConfig, options?: ConversationOptions, verbose?: boolean): Promise<void>;
 //# sourceMappingURL=sync.d.ts.map

package/dist/sync.js

@@ -1,4 +1,4 @@
-import { listProjects, listAgents, listFlowSkills, updateSkill, listFlowEvents, listFlowStates, getProjectMeta, getCustomerAttributes, updateCustomerAttribute } from './api.js';
+import { listProjects, listAgents, listFlowSkills, updateSkill, listFlowEvents, listFlowStates, getProjectMeta, getCustomerAttributes, updateCustomerAttribute, listUserPersonas, getConversationActs, getChatHistory } from './api.js';
 import { ensureState, skillPath, skillScriptPath, writeFileSafe, readIfExists, mapPath, projectMetadataPath, agentMetadataPath, flowMetadataPath, skillMetadataPath, flowsYamlPath, customerAttributesPath, customerAttributesMapPath, customerAttributesBackupPath } from './fsutil.js';
 import fs from 'fs-extra';
 import { sha256, loadHashes, saveHashes } from './hash.js';
@@ -1018,4 +1018,203 @@ async function generateFlowsYaml(client, customer, agents, verbose = false) {
     await writeFileSafe(yamlPath, yamlContent);
     console.log(`✓ Generated flows.yaml`);
 }
+// Conversation sync functions
+export async function pullConversations(client, customer, options = {}, verbose = false) {
+    if (verbose)
+        console.log(`💬 Fetching conversations for customer ${customer.idn}...`);
+    try {
+        // Get all user personas with pagination
+        const allPersonas = [];
+        let page = 1;
+        const perPage = 50;
+        let hasMore = true;
+        while (hasMore) {
+            const response = await listUserPersonas(client, page, perPage);
+            allPersonas.push(...response.items);
+            if (verbose)
+                console.log(`📋 Page ${page}: Found ${response.items.length} personas (${allPersonas.length}/${response.metadata.total} total)`);
+            hasMore = response.items.length === perPage && allPersonas.length < response.metadata.total;
+            page++;
+        }
+        if (options.maxPersonas && allPersonas.length > options.maxPersonas) {
+            allPersonas.splice(options.maxPersonas);
+            if (verbose)
+                console.log(`⚠️  Limited to ${options.maxPersonas} personas as requested`);
+        }
+        if (verbose)
+            console.log(`👥 Processing ${allPersonas.length} personas...`);
+        // Process personas concurrently with limited concurrency
+        const processedPersonas = [];
+        await Promise.all(allPersonas.map(persona => concurrencyLimit(async () => {
+            try {
+                // Extract phone number from actors
+                const phoneActor = persona.actors.find(actor => actor.integration_idn === 'newo_voice' &&
+                    actor.connector_idn === 'newo_voice_connector' &&
+                    actor.contact_information?.startsWith('+'));
+                const phone = phoneActor?.contact_information || null;
+                // Get acts for this persona
+                const allActs = [];
+                let actPage = 1;
+                const actsPerPage = 100; // Higher limit for acts
+                let hasMoreActs = true;
+                while (hasMoreActs) {
+                    // First try the chat history API as alternative
+                    try {
+                        // Get user actor IDs from persona actors
+                        const userActors = persona.actors.filter(actor => actor.integration_idn === 'newo_voice' &&
+                            actor.connector_idn === 'newo_voice_connector');
+                        if (userActors.length > 0) {
+                            const chatHistoryParams = {
+                                user_actor_id: userActors[0].id,
+                                page: actPage,
+                                per: actsPerPage
+                            };
+                            const chatResponse = await getChatHistory(client, chatHistoryParams);
+                            if (chatResponse.items && chatResponse.items.length > 0) {
+                                // Convert chat history format to acts format - create minimal ConversationAct objects
+                                const convertedActs = chatResponse.items.map((item) => ({
+                                    id: item.id || `chat_${Math.random()}`,
+                                    command_act_id: null,
+                                    external_event_id: item.external_event_id || 'chat_history',
+                                    arguments: [],
+                                    reference_idn: (item.is_agent === true) ? 'agent_message' : 'user_message',
+                                    runtime_context_id: item.runtime_context_id || 'chat_history',
+                                    source_text: item.payload?.text || item.message || item.content || item.text || '',
+                                    original_text: item.payload?.text || item.message || item.content || item.text || '',
+                                    datetime: item.datetime || item.created_at || item.timestamp || new Date().toISOString(),
+                                    user_actor_id: userActors[0].id,
+                                    agent_actor_id: null,
+                                    user_persona_id: persona.id,
+                                    user_persona_name: persona.name,
+                                    agent_persona_id: item.agent_persona_id || 'unknown',
+                                    external_id: item.external_id || null,
+                                    integration_idn: 'newo_voice',
+                                    connector_idn: 'newo_voice_connector',
+                                    to_integration_idn: null,
+                                    to_connector_idn: null,
+                                    is_agent: Boolean(item.is_agent === true),
+                                    project_idn: null,
+                                    flow_idn: item.flow_idn || 'unknown',
+                                    skill_idn: item.skill_idn || 'unknown',
+                                    session_id: item.session_id || 'unknown',
+                                    recordings: item.recordings || [],
+                                    contact_information: item.contact_information || null
+                                }));
+                                allActs.push(...convertedActs);
+                                if (verbose && convertedActs.length > 0) {
+                                    console.log(`  👤 ${persona.name}: Chat History - ${convertedActs.length} messages (${allActs.length} total)`);
+                                }
+                                hasMoreActs = chatResponse.items.length === actsPerPage &&
+                                    chatResponse.metadata?.total !== undefined &&
+                                    allActs.length < chatResponse.metadata.total;
+                                actPage++;
+                                continue; // Skip the original acts API call
+                            }
+                        }
+                    }
+                    catch (chatError) {
+                        if (verbose)
+                            console.log(`  ⚠️  Chat history failed for ${persona.name}, trying acts API: ${chatError instanceof Error ? chatError.message : String(chatError)}`);
+                    }
+                    // Fallback to original acts API
+                    const actsParams = {
+                        user_persona_id: persona.id,
+                        page: actPage,
+                        per: actsPerPage,
+                        turn_type: 'messages',
+                        connectors: options.connectors?.join(',') || 'newo_voice/*',
+                        ...(options.fromDate && { from_date: options.fromDate }),
+                        ...(options.toDate && { to_date: options.toDate })
+                    };
+                    const actsResponse = await getConversationActs(client, actsParams);
+                    allActs.push(...actsResponse.items);
+                    if (verbose && actsResponse.items.length > 0) {
+                        console.log(`  👤 ${persona.name}: Page ${actPage} - ${actsResponse.items.length} acts (${allActs.length}/${actsResponse.metadata.total} total)`);
+                    }
+                    hasMoreActs = actsResponse.items.length === actsPerPage && allActs.length < actsResponse.metadata.total;
+                    actPage++;
+                    // Apply per-persona act limit if specified
+                    if (options.maxActsPerPersona && allActs.length >= options.maxActsPerPersona) {
+                        allActs.splice(options.maxActsPerPersona);
+                        hasMoreActs = false;
+                        if (verbose)
+                            console.log(`    ⚠️  Limited to ${options.maxActsPerPersona} acts for ${persona.name}`);
+                    }
+                }
+                // Sort acts by datetime ascending (chronological order)
+                allActs.sort((a, b) => new Date(a.datetime).getTime() - new Date(b.datetime).getTime());
+                // Process acts into simplified format - exclude redundant fields
+                const processedActs = allActs.map(act => {
+                    const processedAct = {
+                        datetime: act.datetime,
+                        type: act.reference_idn,
+                        message: act.source_text
+                    };
+                    // Only include non-redundant fields
+                    if (act.contact_information) {
+                        processedAct.contact_information = act.contact_information;
+                    }
+                    if (act.flow_idn && act.flow_idn !== 'unknown') {
+                        processedAct.flow_idn = act.flow_idn;
+                    }
+                    if (act.skill_idn && act.skill_idn !== 'unknown') {
+                        processedAct.skill_idn = act.skill_idn;
+                    }
+                    if (act.session_id && act.session_id !== 'unknown') {
+                        processedAct.session_id = act.session_id;
+                    }
+                    return processedAct;
+                });
+                processedPersonas.push({
+                    id: persona.id,
+                    name: persona.name,
+                    phone,
+                    act_count: persona.act_count,
+                    acts: processedActs
+                });
+                if (verbose)
+                    console.log(`  ✓ Processed ${persona.name}: ${processedActs.length} acts`);
+            }
+            catch (error) {
+                console.error(`❌ Failed to process persona ${persona.name}:`, error);
+                // Continue with other personas
+            }
+        })));
+        // Sort personas by most recent act time (descending) - use latest act from acts array
+        processedPersonas.sort((a, b) => {
+            const aLatestTime = a.acts.length > 0 ? a.acts[a.acts.length - 1].datetime : '1970-01-01T00:00:00.000Z';
+            const bLatestTime = b.acts.length > 0 ? b.acts[b.acts.length - 1].datetime : '1970-01-01T00:00:00.000Z';
+            return new Date(bLatestTime).getTime() - new Date(aLatestTime).getTime();
+        });
+        // Calculate totals
+        const totalActs = processedPersonas.reduce((sum, persona) => sum + persona.acts.length, 0);
+        // Create final conversations data
+        const conversationsData = {
+            personas: processedPersonas,
+            total_personas: processedPersonas.length,
+            total_acts: totalActs,
+            generated_at: new Date().toISOString()
+        };
+        // Save to YAML file
+        const conversationsPath = `newo_customers/${customer.idn}/conversations.yaml`;
+        const yamlContent = yaml.dump(conversationsData, {
+            indent: 2,
+            quotingType: '"',
+            forceQuotes: false,
+            lineWidth: 120,
+            noRefs: true,
+            sortKeys: false,
+            flowLevel: -1
+        });
+        await writeFileSafe(conversationsPath, yamlContent);
+        if (verbose) {
+            console.log(`✓ Saved conversations to ${conversationsPath}`);
+            console.log(`📊 Summary: ${processedPersonas.length} personas, ${totalActs} total acts`);
+        }
+    }
+    catch (error) {
+        console.error(`❌ Failed to pull conversations for ${customer.idn}:`, error);
+        throw error;
+    }
+}
 //# sourceMappingURL=sync.js.map

package/dist/types.d.ts

@@ -281,4 +281,122 @@ export interface SkillMetadata {
     created_at?: string;
     updated_at?: string;
 }
+export interface Actor {
+    readonly id: string;
+    readonly conversation_is_active: boolean;
+    readonly act_count: number;
+    readonly external_id: string;
+    readonly integration_idn: string;
+    readonly connector_idn: string;
+    readonly contact_information: string;
+}
+export interface UserPersona {
+    readonly id: string;
+    readonly name: string;
+    readonly last_session_id: string;
+    readonly session_is_active: boolean;
+    readonly last_act_time: string;
+    readonly last_act_text: string;
+    readonly act_count: number;
+    readonly actors: readonly Actor[];
+    readonly not_found: boolean;
+}
+export interface ConversationAct {
+    readonly id: string;
+    readonly command_act_id: string | null;
+    readonly external_event_id: string;
+    readonly arguments: readonly any[];
+    readonly reference_idn: string;
+    readonly runtime_context_id: string;
+    readonly source_text: string;
+    readonly original_text: string;
+    readonly datetime: string;
+    readonly user_actor_id: string;
+    readonly agent_actor_id: string | null;
+    readonly user_persona_id: string;
+    readonly user_persona_name: string;
+    readonly agent_persona_id: string;
+    readonly external_id: string | null;
+    readonly integration_idn: string;
+    readonly connector_idn: string;
+    readonly to_integration_idn: string | null;
+    readonly to_connector_idn: string | null;
+    readonly is_agent: boolean;
+    readonly project_idn: string | null;
+    readonly flow_idn: string;
+    readonly skill_idn: string;
+    readonly session_id: string;
+    readonly recordings: readonly any[];
+    readonly contact_information: string | null;
+}
+export interface UserPersonaResponse {
+    readonly items: readonly UserPersona[];
+    readonly metadata: {
+        readonly page: number;
+        readonly per: number;
+        readonly total: number;
+    };
+}
+export interface ConversationActsResponse {
+    readonly items: readonly ConversationAct[];
+    readonly metadata: {
+        readonly page: number;
+        readonly per: number;
+        readonly total: number;
+    };
+}
+export interface ConversationActsParams {
+    readonly turn_type?: string;
+    readonly connectors?: string;
+    readonly user_persona_id: string;
+    readonly page?: number;
+    readonly per?: number;
+    readonly from_date?: string;
+    readonly to_date?: string;
+}
+export interface ChatHistoryParams {
+    readonly user_actor_id: string;
+    readonly agent_actor_id?: string;
+    readonly page?: number;
+    readonly per?: number;
+}
+export interface ChatHistoryResponse {
+    readonly items: readonly any[];
+    readonly metadata?: {
+        readonly page: number;
+        readonly per: number;
+        readonly total: number;
+    };
+}
+export interface ConversationOptions {
+    readonly includeAll?: boolean;
+    readonly connectors?: string[];
+    readonly fromDate?: string;
+    readonly toDate?: string;
+    readonly fields?: string[];
+    readonly maxPersonas?: number | undefined;
+    readonly maxActsPerPersona?: number | undefined;
+}
+export interface ProcessedAct {
+    readonly datetime: string;
+    readonly type: string;
+    readonly message: string;
+    readonly contact_information?: string | null;
+    readonly flow_idn?: string;
+    readonly skill_idn?: string;
+    readonly session_id?: string;
+}
+export interface ProcessedPersona {
+    readonly id: string;
+    readonly name: string;
+    readonly phone: string | null;
+    readonly act_count: number;
+    readonly acts: readonly ProcessedAct[];
+}
+export interface ConversationsData {
+    readonly personas: readonly ProcessedPersona[];
+    readonly total_personas: number;
+    readonly total_acts: number;
+    readonly generated_at: string;
+}
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "newo",
-  "version": "1.8.0",
-  "description": "NEWO CLI: comprehensive sync for AI Agent skills, customer attributes, and metadata between NEWO platform and local files. Multi-customer workspaces, complete change tracking, Git-first workflows.",
+  "version": "1.9.0",
+  "description": "NEWO CLI: comprehensive sync for AI Agent skills, customer attributes, conversations, and metadata between NEWO platform and local files. Multi-customer workspaces, conversation history extraction, complete change tracking, Git-first workflows.",
   "type": "module",
   "bin": {
     "newo": "dist/cli.js"
@@ -26,7 +26,10 @@
     "knowledge-base",
     "import",
     "multi-project",
-    "workspace"
+    "workspace",
+    "conversations",
+    "chat-history",
+    "personas"
   ],
   "author": "sabbah13",
   "license": "MIT",
@@ -71,6 +74,8 @@
     "pull": "npm run build && node ./dist/cli.js pull",
     "push": "npm run build && node ./dist/cli.js push",
     "status": "npm run build && node ./dist/cli.js status",
+    "conversations": "npm run build && node ./dist/cli.js conversations",
+    "conversations:all": "npm run build && node ./dist/cli.js conversations --all",
     "clean": "rm -rf dist coverage",
     "typecheck": "tsc --noEmit",
     "lint": "tsc --noEmit --strict",

package/src/api.ts

@@ -10,7 +10,13 @@ import type {
   AkbImportArticle,
   CustomerProfile,
   CustomerAttribute,
-  CustomerAttributesResponse
+  CustomerAttributesResponse,
+  UserPersonaResponse,
+  UserPersona,
+  ConversationActsResponse,
+  ConversationActsParams,
+  ChatHistoryParams,
+  ChatHistoryResponse
 } from './types.js';
 
 // Per-request retry tracking to avoid shared state issues
@@ -152,4 +158,60 @@ export async function updateCustomerAttribute(client: AxiosInstance, attribute:
     possible_values: attribute.possible_values,
     value_type: attribute.value_type
   });
+}
+
+// Conversation API Functions
+
+export async function listUserPersonas(client: AxiosInstance, page: number = 1, per: number = 50): Promise<UserPersonaResponse> {
+  const response = await client.get<UserPersonaResponse>('/api/v1/bff/conversations/user-personas', {
+    params: { page, per }
+  });
+  return response.data;
+}
+
+export async function getUserPersona(client: AxiosInstance, personaId: string): Promise<UserPersona> {
+  const response = await client.get<UserPersona>(`/api/v1/bff/conversations/user-personas/${personaId}`);
+  return response.data;
+}
+
+export async function getAccount(client: AxiosInstance): Promise<{ id: string; [key: string]: any }> {
+  const response = await client.get<{ id: string; [key: string]: any }>('/api/v1/account');
+  return response.data;
+}
+
+export async function getConversationActs(client: AxiosInstance, params: ConversationActsParams): Promise<ConversationActsResponse> {
+  const queryParams: Record<string, any> = {
+    user_persona_id: params.user_persona_id,
+    page: params.page || 1,
+    per: params.per || 50
+  };
+
+  // Only add optional parameters if explicitly provided
+  if (params.turn_type) queryParams.turn_type = params.turn_type;
+  if (params.connectors) queryParams.connectors = params.connectors;
+  if (params.from_date) queryParams.from_date = params.from_date;
+  if (params.to_date) queryParams.to_date = params.to_date;
+
+  const response = await client.get<ConversationActsResponse>('/api/v1/bff/conversations/acts', {
+    params: queryParams
+  });
+  return response.data;
+}
+
+export async function getChatHistory(client: AxiosInstance, params: ChatHistoryParams): Promise<ChatHistoryResponse> {
+  const queryParams: Record<string, any> = {
+    user_actor_id: params.user_actor_id,
+    page: params.page || 1,
+    per: params.per || 50
+  };
+
+  // Only add agent_actor_id if provided
+  if (params.agent_actor_id) {
+    queryParams.agent_actor_id = params.agent_actor_id;
+  }
+
+  const response = await client.get<ChatHistoryResponse>('/api/v1/chat/history', {
+    params: queryParams
+  });
+  return response.data;
 }

package/src/cli.ts

@@ -2,7 +2,7 @@
 import minimist from 'minimist';
 import dotenv from 'dotenv';
 import { makeClient, getProjectMeta, importAkbArticle } from './api.js';
-import { pullAll, pushChanged, status, saveCustomerAttributes } from './sync.js';
+import { pullAll, pushChanged, status, saveCustomerAttributes, pullConversations } from './sync.js';
 import { parseAkbFile, prepareArticlesForImport } from './akb.js';
 import { initializeEnvironment, ENV, EnvValidationError } from './env.js';
 import { parseCustomerConfigAsync, listCustomers, getCustomer, getDefaultCustomer, tryGetDefaultCustomer, getAllCustomers, validateCustomerConfig } from './customerAsync.js';
@@ -168,12 +168,14 @@ Usage:
   newo pull [--customer <idn>]                  # download projects -> ./newo_customers/<idn>/projects/
   newo push [--customer <idn>]                  # upload modified *.guidance/*.jinja back to NEWO
   newo status [--customer <idn>]                # show modified files
+  newo conversations [--customer <idn>] [--all] # download user conversations -> ./newo_customers/<idn>/conversations.yaml
   newo list-customers                           # list available customers
   newo meta [--customer <idn>]                  # get project metadata (debug)
   newo import-akb <file> <persona_id> [--customer <idn>]  # import AKB articles from file
 
 Flags:
   --customer <idn>             # specify customer (if not set, uses default or interactive selection)
+  --all                        # include all available data (for conversations: all personas and acts)
   --verbose, -v                # enable detailed logging
 
 Environment Variables:
@@ -352,6 +354,53 @@ File Structure:
     return;
   }
 
+  if (cmd === 'conversations') {
+    // Handle customer selection for conversations command
+    if (args.customer) {
+      const customer = getCustomer(customerConfig, args.customer as string);
+      if (!customer) {
+        console.error(`Unknown customer: ${args.customer}`);
+        console.error(`Available customers: ${listCustomers(customerConfig).join(', ')}`);
+        process.exit(1);
+      }
+      selectedCustomer = customer;
+    } else {
+      // Try to get default, fall back to all customers
+      selectedCustomer = tryGetDefaultCustomer(customerConfig);
+      if (!selectedCustomer) {
+        allCustomers = getAllCustomers(customerConfig);
+        if (verbose) console.log(`💬 No default customer specified, pulling conversations from all ${allCustomers.length} customers`);
+      }
+    }
+
+    // Parse conversation-specific options - load all data by default
+    const conversationOptions = {
+      includeAll: true, // Always include all data for conversations
+      maxPersonas: undefined, // No limit on personas
+      maxActsPerPersona: undefined // No limit on acts per persona
+    };
+
+    if (selectedCustomer) {
+      // Single customer conversations
+      const accessToken = await getValidAccessToken(selectedCustomer);
+      const client = await makeClient(verbose, accessToken);
+      console.log(`💬 Pulling conversations for customer: ${selectedCustomer.idn} (all data)`);
+      await pullConversations(client, selectedCustomer, conversationOptions, verbose);
+      console.log(`✅ Conversations saved to newo_customers/${selectedCustomer.idn}/conversations.yaml`);
+    } else if (allCustomers.length > 0) {
+      // Multi-customer conversations
+      console.log(`💬 Pulling conversations from ${allCustomers.length} customers (all data)...`);
+      for (const customer of allCustomers) {
+        console.log(`\n💬 Pulling conversations for customer: ${customer.idn}`);
+        const accessToken = await getValidAccessToken(customer);
+        const client = await makeClient(verbose, accessToken);
+        await pullConversations(client, customer, conversationOptions, verbose);
+      }
+      console.log(`\n✅ Conversations pull completed for all ${allCustomers.length} customers`);
+    }
+    return;
+  }
+
   // For all other commands, require a single selected customer
   if (args.customer) {
     const customer = getCustomer(customerConfig, args.customer as string);

package/src/sync.ts

@@ -7,7 +7,10 @@ import {
   listFlowStates,
   getProjectMeta,
   getCustomerAttributes,
-  updateCustomerAttribute
+  updateCustomerAttribute,
+  listUserPersonas,
+  getConversationActs,
+  getChatHistory
 } from './api.js';
 import {
   ensureState,
@@ -49,7 +52,13 @@ import type {
   SkillMetadata,
   FlowEvent,
   FlowState,
-  CustomerAttribute
+  CustomerAttribute,
+  UserPersona,
+  ConversationAct,
+  ConversationOptions,
+  ConversationsData,
+  ProcessedPersona,
+  ProcessedAct
 } from './types.js';
 
 // Concurrency limits for API operations
@@ -1171,4 +1180,237 @@ async function generateFlowsYaml(
   const yamlPath = flowsYamlPath(customer.idn);
   await writeFileSafe(yamlPath, yamlContent);
   console.log(`✓ Generated flows.yaml`);
+}
+
+// Conversation sync functions
+
+export async function pullConversations(
+  client: AxiosInstance,
+  customer: CustomerConfig,
+  options: ConversationOptions = {},
+  verbose: boolean = false
+): Promise<void> {
+  if (verbose) console.log(`💬 Fetching conversations for customer ${customer.idn}...`);
+
+  try {
+    // Get all user personas with pagination
+    const allPersonas: UserPersona[] = [];
+    let page = 1;
+    const perPage = 50;
+    let hasMore = true;
+
+    while (hasMore) {
+      const response = await listUserPersonas(client, page, perPage);
+      allPersonas.push(...response.items);
+
+      if (verbose) console.log(`📋 Page ${page}: Found ${response.items.length} personas (${allPersonas.length}/${response.metadata.total} total)`);
+
+      hasMore = response.items.length === perPage && allPersonas.length < response.metadata.total;
+      page++;
+    }
+
+    if (options.maxPersonas && allPersonas.length > options.maxPersonas) {
+      allPersonas.splice(options.maxPersonas);
+      if (verbose) console.log(`⚠️  Limited to ${options.maxPersonas} personas as requested`);
+    }
+
+    if (verbose) console.log(`👥 Processing ${allPersonas.length} personas...`);
+
+    // Process personas concurrently with limited concurrency
+    const processedPersonas: ProcessedPersona[] = [];
+
+    await Promise.all(allPersonas.map(persona => concurrencyLimit(async () => {
+      try {
+        // Extract phone number from actors
+        const phoneActor = persona.actors.find(actor =>
+          actor.integration_idn === 'newo_voice' &&
+          actor.connector_idn === 'newo_voice_connector' &&
+          actor.contact_information?.startsWith('+')
+        );
+        const phone = phoneActor?.contact_information || null;
+
+        // Get acts for this persona
+        const allActs: ConversationAct[] = [];
+        let actPage = 1;
+        const actsPerPage = 100; // Higher limit for acts
+        let hasMoreActs = true;
+
+        while (hasMoreActs) {
+          // First try the chat history API as alternative
+          try {
+            // Get user actor IDs from persona actors
+            const userActors = persona.actors.filter(actor =>
+              actor.integration_idn === 'newo_voice' &&
+              actor.connector_idn === 'newo_voice_connector'
+            );
+
+            if (userActors.length > 0) {
+              const chatHistoryParams = {
+                user_actor_id: userActors[0]!.id,
+                page: actPage,
+                per: actsPerPage
+              };
+
+              const chatResponse = await getChatHistory(client, chatHistoryParams);
+              if (chatResponse.items && chatResponse.items.length > 0) {
+                // Convert chat history format to acts format - create minimal ConversationAct objects
+                const convertedActs: ConversationAct[] = chatResponse.items.map((item: any) => ({
+                  id: item.id || `chat_${Math.random()}`,
+                  command_act_id: null,
+                  external_event_id: item.external_event_id || 'chat_history',
+                  arguments: [],
+                  reference_idn: (item.is_agent === true) ? 'agent_message' : 'user_message',
+                  runtime_context_id: item.runtime_context_id || 'chat_history',
+                  source_text: item.payload?.text || item.message || item.content || item.text || '',
+                  original_text: item.payload?.text || item.message || item.content || item.text || '',
+                  datetime: item.datetime || item.created_at || item.timestamp || new Date().toISOString(),
+                  user_actor_id: userActors[0]!.id,
+                  agent_actor_id: null,
+                  user_persona_id: persona.id,
+                  user_persona_name: persona.name,
+                  agent_persona_id: item.agent_persona_id || 'unknown',
+                  external_id: item.external_id || null,
+                  integration_idn: 'newo_voice',
+                  connector_idn: 'newo_voice_connector',
+                  to_integration_idn: null,
+                  to_connector_idn: null,
+                  is_agent: Boolean(item.is_agent === true),
+                  project_idn: null,
+                  flow_idn: item.flow_idn || 'unknown',
+                  skill_idn: item.skill_idn || 'unknown',
+                  session_id: item.session_id || 'unknown',
+                  recordings: item.recordings || [],
+                  contact_information: item.contact_information || null
+                }));
+
+                allActs.push(...convertedActs);
+
+                if (verbose && convertedActs.length > 0) {
+                  console.log(`  👤 ${persona.name}: Chat History - ${convertedActs.length} messages (${allActs.length} total)`);
+                }
+
+                hasMoreActs = chatResponse.items.length === actsPerPage &&
+                             chatResponse.metadata?.total !== undefined &&
+                             allActs.length < chatResponse.metadata.total;
+                actPage++;
+                continue; // Skip the original acts API call
+              }
+            }
+          } catch (chatError) {
+            if (verbose) console.log(`  ⚠️  Chat history failed for ${persona.name}, trying acts API: ${chatError instanceof Error ? chatError.message : String(chatError)}`);
+          }
+
+          // Fallback to original acts API
+          const actsParams = {
+            user_persona_id: persona.id,
+            page: actPage,
+            per: actsPerPage,
+            turn_type: 'messages',
+            connectors: options.connectors?.join(',') || 'newo_voice/*',
+            ...(options.fromDate && { from_date: options.fromDate }),
+            ...(options.toDate && { to_date: options.toDate })
+          };
+
+          const actsResponse = await getConversationActs(client, actsParams);
+          allActs.push(...actsResponse.items);
+
+          if (verbose && actsResponse.items.length > 0) {
+            console.log(`  👤 ${persona.name}: Page ${actPage} - ${actsResponse.items.length} acts (${allActs.length}/${actsResponse.metadata.total} total)`);
+          }
+
+          hasMoreActs = actsResponse.items.length === actsPerPage && allActs.length < actsResponse.metadata.total;
+          actPage++;
+
+          // Apply per-persona act limit if specified
+          if (options.maxActsPerPersona && allActs.length >= options.maxActsPerPersona) {
+            allActs.splice(options.maxActsPerPersona);
+            hasMoreActs = false;
+            if (verbose) console.log(`    ⚠️  Limited to ${options.maxActsPerPersona} acts for ${persona.name}`);
+          }
+        }
+
+        // Sort acts by datetime ascending (chronological order)
+        allActs.sort((a, b) => new Date(a.datetime).getTime() - new Date(b.datetime).getTime());
+
+        // Process acts into simplified format - exclude redundant fields
+        const processedActs: ProcessedAct[] = allActs.map(act => {
+          const processedAct: ProcessedAct = {
+            datetime: act.datetime,
+            type: act.reference_idn,
+            message: act.source_text
+          };
+
+          // Only include non-redundant fields
+          if (act.contact_information) {
+            (processedAct as any).contact_information = act.contact_information;
+          }
+          if (act.flow_idn && act.flow_idn !== 'unknown') {
+            (processedAct as any).flow_idn = act.flow_idn;
+          }
+          if (act.skill_idn && act.skill_idn !== 'unknown') {
+            (processedAct as any).skill_idn = act.skill_idn;
+          }
+          if (act.session_id && act.session_id !== 'unknown') {
+            (processedAct as any).session_id = act.session_id;
+          }
+
+          return processedAct;
+        });
+
+        processedPersonas.push({
+          id: persona.id,
+          name: persona.name,
+          phone,
+          act_count: persona.act_count,
+          acts: processedActs
+        });
+
+        if (verbose) console.log(`  ✓ Processed ${persona.name}: ${processedActs.length} acts`);
+      } catch (error) {
+        console.error(`❌ Failed to process persona ${persona.name}:`, error);
+        // Continue with other personas
+      }
+    })));
+
+    // Sort personas by most recent act time (descending) - use latest act from acts array
+    processedPersonas.sort((a, b) => {
+      const aLatestTime = a.acts.length > 0 ? a.acts[a.acts.length - 1]!.datetime : '1970-01-01T00:00:00.000Z';
+      const bLatestTime = b.acts.length > 0 ? b.acts[b.acts.length - 1]!.datetime : '1970-01-01T00:00:00.000Z';
+      return new Date(bLatestTime).getTime() - new Date(aLatestTime).getTime();
+    });
+
+    // Calculate totals
+    const totalActs = processedPersonas.reduce((sum, persona) => sum + persona.acts.length, 0);
+
+    // Create final conversations data
+    const conversationsData: ConversationsData = {
+      personas: processedPersonas,
+      total_personas: processedPersonas.length,
+      total_acts: totalActs,
+      generated_at: new Date().toISOString()
+    };
+
+    // Save to YAML file
+    const conversationsPath = `newo_customers/${customer.idn}/conversations.yaml`;
+    const yamlContent = yaml.dump(conversationsData, {
+      indent: 2,
+      quotingType: '"',
+      forceQuotes: false,
+      lineWidth: 120,
+      noRefs: true,
+      sortKeys: false,
+      flowLevel: -1
+    });
+
+    await writeFileSafe(conversationsPath, yamlContent);
+
+    if (verbose) {
+      console.log(`✓ Saved conversations to ${conversationsPath}`);
+      console.log(`📊 Summary: ${processedPersonas.length} personas, ${totalActs} total acts`);
+    }
+
+  } catch (error) {
+    console.error(`❌ Failed to pull conversations for ${customer.idn}:`, error);
+    throw error;
+  }
 }

package/src/types.ts

@@ -336,4 +336,136 @@ export interface SkillMetadata {
   path?: string;
   created_at?: string;
   updated_at?: string;
+}
+
+// Conversation Types
+export interface Actor {
+  readonly id: string;
+  readonly conversation_is_active: boolean;
+  readonly act_count: number;
+  readonly external_id: string;
+  readonly integration_idn: string;
+  readonly connector_idn: string;
+  readonly contact_information: string;
+}
+
+export interface UserPersona {
+  readonly id: string;
+  readonly name: string;
+  readonly last_session_id: string;
+  readonly session_is_active: boolean;
+  readonly last_act_time: string;
+  readonly last_act_text: string;
+  readonly act_count: number;
+  readonly actors: readonly Actor[];
+  readonly not_found: boolean;
+}
+
+export interface ConversationAct {
+  readonly id: string;
+  readonly command_act_id: string | null;
+  readonly external_event_id: string;
+  readonly arguments: readonly any[];
+  readonly reference_idn: string;
+  readonly runtime_context_id: string;
+  readonly source_text: string;
+  readonly original_text: string;
+  readonly datetime: string;
+  readonly user_actor_id: string;
+  readonly agent_actor_id: string | null;
+  readonly user_persona_id: string;
+  readonly user_persona_name: string;
+  readonly agent_persona_id: string;
+  readonly external_id: string | null;
+  readonly integration_idn: string;
+  readonly connector_idn: string;
+  readonly to_integration_idn: string | null;
+  readonly to_connector_idn: string | null;
+  readonly is_agent: boolean;
+  readonly project_idn: string | null;
+  readonly flow_idn: string;
+  readonly skill_idn: string;
+  readonly session_id: string;
+  readonly recordings: readonly any[];
+  readonly contact_information: string | null;
+}
+
+export interface UserPersonaResponse {
+  readonly items: readonly UserPersona[];
+  readonly metadata: {
+    readonly page: number;
+    readonly per: number;
+    readonly total: number;
+  };
+}
+
+export interface ConversationActsResponse {
+  readonly items: readonly ConversationAct[];
+  readonly metadata: {
+    readonly page: number;
+    readonly per: number;
+    readonly total: number;
+  };
+}
+
+export interface ConversationActsParams {
+  readonly turn_type?: string;
+  readonly connectors?: string;
+  readonly user_persona_id: string;
+  readonly page?: number;
+  readonly per?: number;
+  readonly from_date?: string;
+  readonly to_date?: string;
+}
+
+export interface ChatHistoryParams {
+  readonly user_actor_id: string;
+  readonly agent_actor_id?: string;
+  readonly page?: number;
+  readonly per?: number;
+}
+
+export interface ChatHistoryResponse {
+  readonly items: readonly any[]; // We'll define this after seeing the response structure
+  readonly metadata?: {
+    readonly page: number;
+    readonly per: number;
+    readonly total: number;
+  };
+}
+
+export interface ConversationOptions {
+  readonly includeAll?: boolean;
+  readonly connectors?: string[];
+  readonly fromDate?: string;
+  readonly toDate?: string;
+  readonly fields?: string[];
+  readonly maxPersonas?: number | undefined;
+  readonly maxActsPerPersona?: number | undefined;
+}
+
+// Processed conversation data for YAML output
+export interface ProcessedAct {
+  readonly datetime: string;
+  readonly type: string;
+  readonly message: string;
+  readonly contact_information?: string | null;
+  readonly flow_idn?: string;
+  readonly skill_idn?: string;
+  readonly session_id?: string;
+}
+
+export interface ProcessedPersona {
+  readonly id: string;
+  readonly name: string;
+  readonly phone: string | null;
+  readonly act_count: number;
+  readonly acts: readonly ProcessedAct[];
+}
+
+export interface ConversationsData {
+  readonly personas: readonly ProcessedPersona[];
+  readonly total_personas: number;
+  readonly total_acts: number;
+  readonly generated_at: string;
 }