newo 3.0.0 → 3.1.0

package/dist/sandbox/chat.js

@@ -0,0 +1,280 @@
+/**
+ * Sandbox Chat Utility Module
+ * Handles chat session management, message sending, and polling for responses
+ */
+import { randomBytes } from 'crypto';
+import { listIntegrations, listConnectors, createSandboxPersona, createActor, sendChatMessage, getChatHistory } from '../api.js';
+const SANDBOX_INTEGRATION_IDN = 'sandbox';
+const DEFAULT_TIMEZONE = 'America/Los_Angeles';
+const POLL_INTERVAL_MS = 1000; // 1 second
+const MAX_POLL_ATTEMPTS = 60; // Max 60 seconds wait
+/**
+ * Generate a random external ID for chat session
+ */
+function generateExternalId() {
+    return randomBytes(3).toString('hex');
+}
+/**
+ * Generate a unique persona name with NEWO CLI prefix
+ */
+function generatePersonaName() {
+    const guid = randomBytes(8).toString('hex');
+    return `newo-cli-${guid}`;
+}
+/**
+ * Find a sandbox connector from the customer's connectors list
+ */
+export async function findSandboxConnector(client, verbose = false) {
+    if (verbose)
+        console.log('🔍 Searching for sandbox integration...');
+    // First, get all integrations to find the sandbox integration
+    const integrations = await listIntegrations(client);
+    const sandboxIntegration = integrations.find(i => i.idn === SANDBOX_INTEGRATION_IDN);
+    if (!sandboxIntegration) {
+        if (verbose)
+            console.log('❌ Sandbox integration not found');
+        return null;
+    }
+    if (verbose)
+        console.log(`✓ Found sandbox integration: ${sandboxIntegration.id}`);
+    // Now get connectors for the sandbox integration
+    if (verbose)
+        console.log('🔍 Searching for sandbox connectors...');
+    const connectors = await listConnectors(client, sandboxIntegration.id);
+    const sandboxConnectors = connectors.filter(c => c.status === 'running');
+    if (sandboxConnectors.length === 0) {
+        if (verbose)
+            console.log('❌ No running sandbox connectors found');
+        return null;
+    }
+    if (verbose) {
+        console.log(`✓ Found ${sandboxConnectors.length} running sandbox connector(s)`);
+        const firstConnector = sandboxConnectors[0];
+        if (firstConnector) {
+            console.log(`  Using: ${firstConnector.connector_idn}`);
+        }
+    }
+    return sandboxConnectors[0] || null;
+}
+/**
+ * Create a new sandbox chat session
+ */
+export async function createChatSession(client, connector, verbose = false) {
+    const personaName = generatePersonaName();
+    const externalId = generateExternalId();
+    if (verbose)
+        console.log(`📝 Creating persona: ${personaName}`);
+    // Create user persona
+    const personaResponse = await createSandboxPersona(client, {
+        name: personaName,
+        title: personaName
+    });
+    if (verbose)
+        console.log(`✓ Persona created: ${personaResponse.id}`);
+    // Create actor (ties persona to sandbox connector)
+    if (verbose)
+        console.log(`🔗 Creating actor for ${connector.connector_idn}...`);
+    const actorResponse = await createActor(client, personaResponse.id, {
+        name: personaName,
+        external_id: externalId,
+        integration_idn: SANDBOX_INTEGRATION_IDN,
+        connector_idn: connector.connector_idn,
+        time_zone_identifier: DEFAULT_TIMEZONE
+    });
+    if (verbose)
+        console.log(`✓ Actor created: ${actorResponse.id} (Chat ID)`);
+    return {
+        user_persona_id: personaResponse.id,
+        user_actor_id: actorResponse.id,
+        agent_persona_id: null, // Will be populated from first response
+        connector_idn: connector.connector_idn,
+        session_id: null,
+        external_id: externalId
+    };
+}
+/**
+ * Send a message in the chat session
+ * Returns the timestamp when message was sent (for filtering responses)
+ */
+export async function sendMessage(client, session, text, verbose = false) {
+    if (verbose)
+        console.log(`💬 Sending message: "${text}"`);
+    const sentAt = new Date();
+    await sendChatMessage(client, session.user_actor_id, {
+        text,
+        arguments: []
+    });
+    if (verbose)
+        console.log('✓ Message sent');
+    return sentAt;
+}
+/**
+ * Poll for new conversation acts (messages and debug info)
+ * Continues polling until we get an agent response, not just any new message
+ */
+export async function pollForResponse(client, session, messageSentAt = null, verbose = false) {
+    let attempts = 0;
+    let agentPersonaId = session.agent_persona_id;
+    if (verbose)
+        console.log('⏳ Waiting for agent response...');
+    // Add small delay before first poll to allow message to be processed
+    await new Promise(resolve => setTimeout(resolve, 500));
+    while (attempts < MAX_POLL_ATTEMPTS) {
+        try {
+            if (verbose && attempts % 5 === 0) {
+                console.log(`  [Poll attempt ${attempts + 1}/${MAX_POLL_ATTEMPTS}] Checking for messages...`);
+            }
+            // Use Chat History API instead of acts API (doesn't require account_id)
+            const response = await getChatHistory(client, {
+                user_actor_id: session.user_actor_id,
+                page: 1,
+                per: 100
+            });
+            if (verbose && attempts === 0) {
+                console.log(`  Initial poll returned ${response.items.length} message(s)`);
+            }
+            if (response.items && response.items.length > 0) {
+                // Convert chat history format to acts format
+                const convertedActs = response.items.map((item) => ({
+                    id: item.id || `chat_${Math.random()}`,
+                    command_act_id: null,
+                    external_event_id: item.external_event_id || 'chat_history',
+                    arguments: item.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: session.user_actor_id,
+                    agent_actor_id: item.agent_actor_id || null,
+                    user_persona_id: session.user_persona_id,
+                    user_persona_name: 'User',
+                    agent_persona_id: item.agent_persona_id || agentPersonaId || 'unknown',
+                    external_id: item.external_id || null,
+                    integration_idn: 'sandbox',
+                    connector_idn: session.connector_idn,
+                    to_integration_idn: null,
+                    to_connector_idn: null,
+                    is_agent: Boolean(item.is_agent === true),
+                    project_idn: item.project_idn || null,
+                    flow_idn: item.flow_idn || 'unknown',
+                    skill_idn: item.skill_idn || 'unknown',
+                    session_id: item.session_id || session.session_id || 'unknown',
+                    recordings: item.recordings || [],
+                    contact_information: item.contact_information || null
+                }));
+                // Extract agent_persona_id from the first act if we don't have it yet
+                if (!agentPersonaId && convertedActs.length > 0) {
+                    const firstItem = convertedActs[0];
+                    if (firstItem && firstItem.agent_persona_id !== 'unknown') {
+                        agentPersonaId = firstItem.agent_persona_id;
+                        if (verbose)
+                            console.log(`✓ Extracted agent_persona_id: ${agentPersonaId}`);
+                    }
+                }
+                // Filter for agent messages that came AFTER our message was sent
+                const agentMessages = convertedActs.filter(act => {
+                    if (!act.is_agent)
+                        return false;
+                    // If we have a messageSentAt timestamp, ONLY include messages with datetime after it
+                    if (messageSentAt) {
+                        // Parse the act datetime - it may not have timezone, assume UTC
+                        let actDatetime = act.datetime;
+                        if (!actDatetime.endsWith('Z') && !actDatetime.includes('+') && !actDatetime.includes('-', 10)) {
+                            actDatetime = actDatetime + 'Z'; // Assume UTC if no timezone
+                        }
+                        const actTime = new Date(actDatetime);
+                        const sentTime = messageSentAt.getTime();
+                        const actTimeMs = actTime.getTime();
+                        const timeDiff = actTimeMs - sentTime;
+                        if (verbose && attempts === 0) {
+                            console.log(`  Checking agent message:`);
+                            console.log(`    Original datetime: ${act.datetime}`);
+                            console.log(`    Parsed datetime: ${actDatetime}`);
+                            console.log(`    Act timestamp: ${actTimeMs} (${new Date(actTimeMs).toISOString()})`);
+                            console.log(`    Sent timestamp: ${sentTime} (${messageSentAt.toISOString()})`);
+                            console.log(`    Difference: ${timeDiff}ms (${(timeDiff / 1000).toFixed(1)}s)`);
+                            console.log(`    Include: ${timeDiff > -100 ? 'YES' : 'NO'}`);
+                        }
+                        // Only include messages sent AFTER our message (allow small negative buffer for processing time)
+                        return timeDiff > -100;
+                    }
+                    // For first message (no messageSentAt), include all agent messages
+                    return true;
+                });
+                if (agentMessages.length > 0) {
+                    if (verbose)
+                        console.log(`✓ Received ${agentMessages.length} agent message(s) after our message (${messageSentAt?.toISOString()})`);
+                    // Return ONLY the single newest agent message (first one, since API returns newest first)
+                    const latestAgentMessage = agentMessages[0];
+                    if (latestAgentMessage) {
+                        return { acts: [latestAgentMessage], agentPersonaId };
+                    }
+                }
+                else if (verbose && attempts % 10 === 0) {
+                    console.log(`  No new agent messages yet (checked ${response.items.length} total messages, sentAt: ${messageSentAt?.toISOString()}), continuing...`);
+                }
+            }
+        }
+        catch (error) {
+            if (verbose && attempts < 3) {
+                console.log(`⚠️ Error polling (attempt ${attempts + 1}): ${error.message}`);
+            }
+            // Continue polling despite errors
+        }
+        attempts++;
+        await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+    if (verbose)
+        console.log('⏱️  Timeout waiting for response');
+    return { acts: [], agentPersonaId };
+}
+/**
+ * Extract agent messages from acts
+ */
+export function extractAgentMessages(acts) {
+    return acts.filter(act => act.is_agent && act.reference_idn === 'agent_message');
+}
+/**
+ * Extract debug information from acts
+ */
+export function extractDebugInfo(acts) {
+    return acts.map(act => ({
+        flow_idn: act.flow_idn,
+        skill_idn: act.skill_idn,
+        session_id: act.session_id,
+        runtime_context_id: act.runtime_context_id,
+        reference_idn: act.reference_idn,
+        arguments: act.arguments
+    }));
+}
+/**
+ * Format debug info for display
+ */
+export function formatDebugInfo(acts) {
+    const lines = [];
+    for (const act of acts) {
+        if (act.is_agent) {
+            lines.push(`\n[Agent Act] ${act.reference_idn}`);
+        }
+        else {
+            lines.push(`\n[User Act] ${act.reference_idn}`);
+        }
+        lines.push(`  Flow: ${act.flow_idn || 'N/A'}`);
+        lines.push(`  Skill: ${act.skill_idn || 'N/A'}`);
+        lines.push(`  Session: ${act.session_id}`);
+        if (act.runtime_context_id) {
+            lines.push(`  Context: ${act.runtime_context_id}`);
+        }
+        if (act.arguments && act.arguments.length > 0) {
+            lines.push(`  Arguments:`);
+            for (const arg of act.arguments) {
+                if (typeof arg === 'object' && arg !== null && 'name' in arg) {
+                    lines.push(`    ${arg.name}: ${JSON.stringify(arg.value).substring(0, 100)}`);
+                }
+            }
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=chat.js.map

package/dist/types.d.ts

@@ -480,4 +480,85 @@ export interface PublishFlowRequest {
 export interface PublishFlowResponse {
     success: boolean;
 }
+export interface Integration {
+    readonly id: string;
+    readonly title: string;
+    readonly idn: string;
+    readonly description: string;
+    readonly is_disabled: boolean;
+    readonly channel: string;
+}
+export interface IntegrationSetting {
+    readonly title: string;
+    readonly idn: string;
+    readonly control_type: string;
+    readonly value_type: string;
+    readonly is_required: boolean;
+    readonly default_value?: string | null;
+}
+export interface Connector {
+    readonly id: string;
+    readonly title: string;
+    readonly connector_idn: string;
+    readonly integration_idn: string;
+    readonly status: string;
+    readonly api_key?: string;
+    readonly settings: readonly ConnectorSetting[];
+}
+export interface ConnectorSetting {
+    readonly idn: string;
+    readonly value: string;
+}
+export interface CreateSandboxPersonaRequest {
+    name: string;
+    title: string;
+}
+export interface CreateSandboxPersonaResponse {
+    id: string;
+}
+export interface CreateActorRequest {
+    name: string;
+    external_id: string;
+    integration_idn: string;
+    connector_idn: string;
+    time_zone_identifier?: string;
+}
+export interface CreateActorResponse {
+    id: string;
+}
+export interface SendChatMessageRequest {
+    text: string;
+    arguments?: readonly any[];
+}
+export interface ConversationActsParams {
+    user_persona_id: string;
+    user_actor_id: string;
+    agent_persona_id?: string;
+    per?: number;
+    page?: number;
+}
+export interface ConversationActsResponse {
+    readonly items: readonly ConversationAct[];
+    readonly metadata?: {
+        readonly page: number;
+        readonly per: number;
+        readonly total: number;
+    };
+}
+export interface SandboxChatSession {
+    user_persona_id: string;
+    user_actor_id: string;
+    agent_persona_id: string | null;
+    connector_idn: string;
+    session_id: string | null;
+    external_id: string;
+}
+export interface ChatDebugInfo {
+    flow_idn: string | null;
+    skill_idn: string | null;
+    session_id: string;
+    runtime_context_id: string | null;
+    reference_idn: string;
+    arguments: readonly any[];
+}
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "newo",
-  "version": "3.0.0",
-  "description": "NEWO CLI: Professional command-line tool with modular architecture for NEWO AI Agent development. Features IDN-based file management, real-time progress tracking, intelligent sync operations, and comprehensive multi-customer support.",
+  "version": "3.1.0",
+  "description": "NEWO CLI: Professional command-line tool with modular architecture for NEWO AI Agent development. Features sandbox testing, IDN-based file management, real-time progress tracking, intelligent sync operations, and comprehensive multi-customer support.",
   "type": "module",
   "bin": {
     "newo": "dist/cli.js"
@@ -29,7 +29,10 @@
     "workspace",
     "conversations",
     "chat-history",
-    "personas"
+    "personas",
+    "sandbox",
+    "testing",
+    "agent-testing"
   ],
   "author": "sabbah13",
   "license": "MIT",

package/src/api.ts

@@ -34,7 +34,16 @@ import type {
   CreateProjectRequest,
   CreateProjectResponse,
   PublishFlowRequest,
-  PublishFlowResponse
+  PublishFlowResponse,
+  Integration,
+  Connector,
+  CreateSandboxPersonaRequest,
+  CreateSandboxPersonaResponse,
+  CreateActorRequest,
+  CreateActorResponse,
+  SendChatMessageRequest,
+  ConversationActsParams,
+  ConversationActsResponse
 } from './types.js';
 
 // Per-request retry tracking to avoid shared state issues
@@ -311,4 +320,49 @@ export async function createPersona(client: AxiosInstance, personaData: CreatePe
 export async function publishFlow(client: AxiosInstance, flowId: string, publishData: PublishFlowRequest): Promise<PublishFlowResponse> {
   const response = await client.post<PublishFlowResponse>(`/api/v1/designer/flows/${flowId}/publish`, publishData);
   return response.data;
+}
+
+// Sandbox Chat API Functions
+
+export async function listIntegrations(client: AxiosInstance): Promise<Integration[]> {
+  const response = await client.get<Integration[]>('/api/v1/integrations');
+  return response.data;
+}
+
+export async function listConnectors(client: AxiosInstance, integrationId: string): Promise<Connector[]> {
+  const response = await client.get<Connector[]>(`/api/v1/integrations/${integrationId}/connectors`);
+  return response.data;
+}
+
+export async function createSandboxPersona(client: AxiosInstance, personaData: CreateSandboxPersonaRequest): Promise<CreateSandboxPersonaResponse> {
+  const response = await client.post<CreateSandboxPersonaResponse>('/api/v1/customer/personas', personaData);
+  return response.data;
+}
+
+export async function createActor(client: AxiosInstance, personaId: string, actorData: CreateActorRequest): Promise<CreateActorResponse> {
+  const response = await client.post<CreateActorResponse>(`/api/v1/customer/personas/${personaId}/actors`, actorData);
+  return response.data;
+}
+
+export async function sendChatMessage(client: AxiosInstance, actorId: string, messageData: SendChatMessageRequest): Promise<void> {
+  await client.post(`/api/v1/chat/user/${actorId}`, messageData);
+}
+
+export async function getConversationActs(client: AxiosInstance, params: ConversationActsParams): Promise<ConversationActsResponse> {
+  const queryParams: Record<string, any> = {
+    user_persona_id: params.user_persona_id,
+    user_actor_id: params.user_actor_id,
+    per: params.per || 100,
+    page: params.page || 1
+  };
+
+  // Only add agent_persona_id if provided
+  if (params.agent_persona_id) {
+    queryParams.agent_persona_id = params.agent_persona_id;
+  }
+
+  const response = await client.get<ConversationActsResponse>('/api/v1/bff/conversations/acts', {
+    params: queryParams
+  });
+  return response.data;
 }

package/src/auth.ts

@@ -54,6 +54,11 @@ function validateUrl(url: string, name: string): void {
 
 // Enhanced logging function
 function logAuthEvent(level: 'info' | 'warn' | 'error', message: string, meta?: Record<string, unknown>): void {
+  // Skip all logging if in quiet mode
+  if (process.env.NEWO_QUIET_MODE === 'true') {
+    return;
+  }
+
   const timestamp = new Date().toISOString();
   const logEntry = {
     timestamp,
@@ -62,7 +67,7 @@ function logAuthEvent(level: 'info' | 'warn' | 'error', message: string, meta?:
     message,
     ...meta
   };
-  
+
   // Sanitize sensitive data
   const sanitized = JSON.parse(JSON.stringify(logEntry, (key, value) => {
     if (typeof key === 'string' && (key.toLowerCase().includes('key') || key.toLowerCase().includes('token') || key.toLowerCase().includes('secret'))) {
@@ -70,7 +75,7 @@ function logAuthEvent(level: 'info' | 'warn' | 'error', message: string, meta?:
     }
     return value;
   }));
-  
+
   if (level === 'error') {
     console.error(JSON.stringify(sanitized));
   } else if (level === 'warn') {

package/src/cli/commands/help.ts

@@ -11,6 +11,8 @@ Core Commands:
   newo push [--customer <idn>] [--no-publish]    # upload modified *.guidance/*.jinja + attributes back to NEWO, publish flows by default
   newo status [--customer <idn>]                # show modified files that would be pushed
   newo conversations [--customer <idn>] [--all] # download user conversations -> ./newo_customers/<idn>/conversations.yaml
+  newo sandbox "<message>" [--customer <idn>]   # test agent in sandbox - single message mode (NEW v3.1.0)
+  newo sandbox --actor <id> "message"           # continue existing sandbox conversation with chat ID
   newo pull-attributes [--customer <idn>]       # download customer attributes -> ./newo_customers/<idn>/attributes.yaml
   newo list-customers                           # list available customers and their configuration
   newo meta [--customer <idn>]                  # get project metadata (debug command)
@@ -46,6 +48,8 @@ Flags:
   --all                        # include all available data (for conversations: all personas and acts)
   --force, -f                  # force overwrite without prompting (for pull command)
   --verbose, -v                # enable detailed logging and progress information
+  --quiet, -q                  # minimal output for automation (sandbox only)
+  --actor <id>                 # continue existing sandbox chat with actor/chat ID
   --confirm                    # confirm destructive operations without prompting
   --no-publish                 # skip automatic flow publishing during push operations
 
@@ -108,6 +112,12 @@ Usage Examples:
   # Import AKB articles:
   newo import-akb articles.txt da4550db-2b95-4500-91ff-fb4b60fe7be9
 
+  # Sandbox testing (NEW v3.1.0):
+  newo sandbox "Hello, I want to order pizza"                    # Start new conversation
+  newo sandbox --actor abc123... "I want 2 large pizzas"         # Continue conversation
+  newo sandbox "Test query" --verbose                            # With debug info
+  newo sandbox "Test query" --quiet                              # For automation/scripts
+
 File Structure:
   newo_customers/
   ├── <customer-idn>/