@recombine-ai/bosun 0.10.1 → 0.11.2

package/src/backend/roleplay/agents.ts

@@ -24,6 +24,8 @@ import { createStepRegistry } from './step-registry'
 import { getAgentFactories } from '../lib/get-agent-factories'
 import { getImportNonce } from '../lib/import-nonce'
 import { getRootPath } from '../lib/get-root-path'
+import { sendCallStartMessage } from '../lib/voice-agent-lifecycle'
+import { normalizeTracePayload } from './trace-serialization'
 
 interface MessageEntry {
 	type: 'message'
@@ -136,7 +138,7 @@ export function createAgents(
 			lastLoadedImportNonce = importNonce
 			basePath = loaded.basePath
 			factories = loaded.factories
-			console.log(`createAgents, load; loaded agents: ${Object.keys(factories)}`)
+			console.log(`createAgents, load; loaded agents: ${Object.keys(factories).join(', ')}`)
 			await dispatcher.sendLoaded(Object.keys(factories))
 		},
 		reload: async () => {
@@ -156,7 +158,7 @@ export function createAgents(
 			currentRegion = region || null
 			const agent = await getCurrentAgent()
 
-			dispatcher.sendAgentSelected({
+			await dispatcher.sendAgentSelected({
 				id: agentId,
 				type: isVoiceAgent(agent.agent) ? 'voice' : 'text',
 				steps: await Promise.all(
@@ -174,7 +176,7 @@ export function createAgents(
 			if (agent.ctx.get()) {
 				const context = agent.ctx.get()
 				const promptContext = agent.ctx.getPromptContextMapper()(context)
-				dispatcher.sendContext(context, promptContext)
+				await dispatcher.sendContext(context, promptContext)
 			}
 
 			const rawStates = agentStates[getAgentCacheKey(agentId, currentRegion)]
@@ -185,7 +187,7 @@ export function createAgents(
 				isInitialLoad = true
 			}
 			currentStateId = stateId ?? null
-			dispatcher.sendUpdateStates(
+			await dispatcher.sendUpdateStates(
 				states.map((state) => ({
 					id: state.id,
 					name: state.name,
@@ -209,12 +211,11 @@ export function createAgents(
 			await (await getCurrentAgent()).triggerAction(action)
 		},
 		handleMessage: async (message: Message) => {
-			await dispatcher.sendMessage(message) // echo message
 			currentStateId = await (await getCurrentAgent()).handleMessage(message)
 		},
 		hangup: async (agentId: string, region: string | null) => {
 			const cacheKey = getAgentCacheKey(agentId, region)
-			let agent = agents[cacheKey]
+			const agent = agents[cacheKey]
 			if (!agent) {
 				throw new Error(`Cannot hangup: cannot find agent: ${cacheKey}`)
 			}
@@ -250,62 +251,74 @@ export async function loadAgent(props: LoadProps) {
 	ctx.subscribe((context) => {
 		console.log('------ context updated --------')
 		const promptContext = ctx.getPromptContextMapper()(context)
-		props.sendContext(context, promptContext)
+		void props.sendContext(context, promptContext)
 	})
 	const logger = createLogger((msg) => {
 		state.history.push({
 			type: 'log',
 			payload: msg
 		})
-		props.sendLog(msg)
+		void props.sendLog(msg)
 	})
 
 	const stepTracer: StepTracer = {
 		addStepTrace: (stepTrace) => {
+			const normalizedTrace = normalizeTracePayload(stepTrace)
 			state.history.push({
 				type: 'trace',
-				payload: stepTrace
+				payload: normalizedTrace
 			})
-			props.sendTrace(stepTrace)
+			void props.sendTrace(normalizedTrace)
 		},
 		async flush() {}
 	}
 
 	const apiCallTracer: ApiCallTracer = {
 		addApiCallTrace: (apiCallTrace) => {
+			const normalizedTrace = normalizeTracePayload(apiCallTrace)
 			logger.log(
 				'[apiCallTracer] addApiCallTrace',
-				apiCallTrace?.operationName,
-				apiCallTrace?.method,
-				apiCallTrace?.path
+				normalizedTrace?.operationName,
+				normalizedTrace?.method,
+				normalizedTrace?.path
 			)
 			state.history.push({
 				type: 'api-call-trace',
-				payload: apiCallTrace
+				payload: normalizedTrace
 			})
-			props.sendApiCallTrace(apiCallTrace)
+			void props.sendApiCallTrace(normalizedTrace)
 		},
 		async flush() {}
 	}
 
 	const conversationalTracer: ConversationalTracer = {
 		addConversationalTrace: (conversationalTrace) => {
-			const rawUserMessage = userMessage(state)
-			;(conversationalTrace as any).bosunStateId = state.id
-			;(conversationalTrace as any).bosunPrevStateId = state.prev
-			if (rawUserMessage) {
-				;(conversationalTrace as any).bosunUserMessage = rawUserMessage
+			const inputMessage = latestInputMessage(state)
+			attachInputMessageMetadata(conversationalTrace, state, inputMessage)
+			const isInboundMessageEvent =
+				conversationalTrace.eventName === 'received-message' ||
+				conversationalTrace.eventName === 'llm-handler-stream-requested'
+			if (isInboundMessageEvent && !String(conversationalTrace.content ?? '').trim()) {
+				return
+			}
+			if (
+				inputMessage &&
+				isInboundMessageEvent &&
+				hasInputMessageTrace(state.history, inputMessage)
+			) {
+				return
 			}
+			const normalizedTrace = normalizeTracePayload(conversationalTrace)
 			logger.log(
 				'[conversationalTracer] addConversationalTrace',
-				conversationalTrace?.eventName,
-				conversationalTrace?.role
+				normalizedTrace?.eventName,
+				normalizedTrace?.role
 			)
 			state.history.push({
 				type: 'conversational-trace',
-				payload: conversationalTrace
+				payload: normalizedTrace
 			})
-			props.sendConversationalTrace(conversationalTrace)
+			void props.sendConversationalTrace(normalizedTrace)
 		},
 		async flush() {}
 	}
@@ -314,11 +327,25 @@ export async function loadAgent(props: LoadProps) {
 
 	scheduler = createScheduler({
 		logger,
-		onUpdate: async (actions) => {
-			await props.sendSchedule(actions)
+		onUpdate: (actions) => {
+			void props.sendSchedule(actions)
 		}
 	})
 
+	const sendAgentMessage = async (message: string | Message) => {
+		if (typeof message === 'string') {
+			state.history.push({
+				type: 'message',
+				payload: { text: message, sender: 'agent' }
+			})
+		} else {
+			state.history.push({
+				type: 'message',
+				payload: message
+			})
+		}
+	}
+
 	agent = await props.factory({
 		stepTracer: stepTracer,
 		stepRegistry,
@@ -327,7 +354,7 @@ export async function loadAgent(props: LoadProps) {
 		conversationalTracer,
 		scheduler,
 		getMessages: () => {
-			let messages: Array<MessageEntry['payload']> = []
+			const messages: Array<MessageEntry['payload']> = []
 			let curState = state
 			while (true) {
 				curState.history
@@ -343,21 +370,7 @@ export async function loadAgent(props: LoadProps) {
 			}
 			return messages.reverse()
 		},
-		sendMessage: async (message: string | Message) => {
-			if (typeof message === 'string') {
-				state.history.push({
-					type: 'message',
-					payload: { text: message, sender: 'agent' }
-				})
-				await props.sendMessage({ text: message, sender: 'agent' })
-			} else {
-				state.history.push({
-					type: 'message',
-					payload: message
-				})
-				await props.sendMessage({ text: message.text, sender: message.sender })
-			}
-		},
+		sendMessage: sendAgentMessage,
 		ctx,
 		config: {
 			enableTimers: false,
@@ -393,6 +406,7 @@ export async function loadAgent(props: LoadProps) {
 				id: state.id,
 				name: state.name,
 				userMessage: userMessage(state),
+				userMessageSender: userMessageSender(state),
 				prev: state.prev,
 				next: state.next
 			}))
@@ -430,7 +444,12 @@ export async function loadAgent(props: LoadProps) {
 				console.log(' --- init agent ---')
 				state = createState({}, null)
 				if (agent) {
-					await (isVoiceAgent(agent) ? agent.onCallStart() : agent.start())
+					if (isVoiceAgent(agent)) {
+						const callStartResult = await agent.onCallStart()
+						await sendCallStartMessage(callStartResult, sendAgentMessage)
+					} else {
+						await agent.start()
+					}
 				}
 				return
 			}
@@ -448,29 +467,32 @@ export async function loadAgent(props: LoadProps) {
 			}
 			console.log('replay: ' + replay.length)
 			replay.reverse().forEach((state) => {
-				state.history.forEach((entry) => {
+				state.history.forEach((entry, index) => {
 					switch (entry.type) {
 						case 'message':
-							props.sendMessage(entry.payload)
+							if (
+								isInputMessage(entry.payload) &&
+								!hasInputMessageTrace(state.history, entry.payload)
+							) {
+								const inputTrace = createInputMessageTrace(entry.payload, state, agentMedium(agent))
+								if (inputTrace) void props.sendConversationalTrace(inputTrace)
+							}
 							break
 						case 'log':
-							props.sendLog(entry.payload)
+							void props.sendLog(entry.payload)
 							break
 						case 'trace':
-							props.sendTrace(entry.payload)
+							void props.sendTrace(entry.payload)
 							break
 						case 'api-call-trace':
-							props.sendApiCallTrace(entry.payload)
+							void props.sendApiCallTrace(entry.payload)
 							break
-						case 'conversational-trace':
-							const rawUserMessage = userMessage(state)
-							;(entry.payload as any).bosunStateId = state.id
-							;(entry.payload as any).bosunPrevStateId = state.prev
-							if (rawUserMessage) {
-								;(entry.payload as any).bosunUserMessage = rawUserMessage
-							}
-							props.sendConversationalTrace(entry.payload)
+						case 'conversational-trace': {
+							const inputMessage = inputMessageBefore(state.history, index)
+							attachInputMessageMetadata(entry.payload, state, inputMessage)
+							void props.sendConversationalTrace(entry.payload)
 							break
+						}
 					}
 				})
 			})
@@ -534,6 +556,11 @@ export async function loadAgent(props: LoadProps) {
 				type: 'message',
 				payload: message
 			})
+			const inputTrace = createInputMessageTrace(message, state, agentMedium(agent))
+			if (inputTrace) {
+				state.history.push({ type: 'conversational-trace', payload: inputTrace })
+				void props.sendConversationalTrace(inputTrace)
+			}
 			if (isVoiceAgent(agent)) {
 				await agent.streamResponse()
 			} else {
@@ -571,7 +598,7 @@ function createState(schedule: DelayedActions, prev: string | null) {
 }
 
 function clone(obj: any) {
-	return JSON.parse(JSON.stringify(obj))
+	return normalizeTracePayload(obj)
 }
 
 function indexStates(stateHistory: AgentState[]) {
@@ -591,23 +618,116 @@ function createLiveStateFromHistory(stateHistory: AgentState[]) {
 	return createState(clone(latestSavedState.schedule ?? {}), latestSavedState.id)
 }
 
-function userMessage(st: AgentState): string | undefined {
+function isInputMessage(message: Message): message is Message & { sender: 'user' | 'system' } {
+	return message.sender === 'user' || message.sender === 'system'
+}
+
+function latestInputMessage(st: AgentState): (Message & { sender: 'user' | 'system' }) | null {
 	for (let i = st.history.length - 1; i >= 0; i--) {
 		const entry = st.history[i]
 		if (entry.type === 'message') {
-			const m = entry.payload as Message
-			if (m.sender === 'user') {
-				if (typeof (m as any).text === 'string' && (m as any).text.trim()) {
-					return (m as any).text
-				}
-				if (typeof (m as any).imageUrl === 'string' && (m as any).imageUrl.trim()) {
-					return `[image] ${(m as any).imageUrl}`
-				}
-				return JSON.stringify(m)
-			}
+			const m = entry.payload
+			if (isInputMessage(m)) return m
 		}
 	}
-	return undefined
+	return null
+}
+
+function inputMessageBefore(
+	history: AgentState['history'],
+	beforeIndex: number
+): (Message & { sender: 'user' | 'system' }) | null {
+	for (let i = beforeIndex - 1; i >= 0; i--) {
+		const entry = history[i]
+		if (entry.type === 'message' && isInputMessage(entry.payload)) {
+			return entry.payload
+		}
+	}
+	return null
+}
+
+function messageSummary(message: Message): string {
+	if (typeof message.text === 'string' && message.text.trim()) {
+		return message.text
+	}
+	if (typeof message.imageUrl === 'string' && message.imageUrl.trim()) {
+		return `[image] ${message.imageUrl}`
+	}
+	return JSON.stringify(message)
+}
+
+function attachInputMessageMetadata(
+	trace: ConversationalTrace,
+	state: AgentState,
+	inputMessage: (Message & { sender: 'user' | 'system' }) | null
+) {
+	const rawUserMessage = inputMessage ? messageSummary(inputMessage) : undefined
+	;(trace as any).bosunStateId = state.id
+	;(trace as any).bosunPrevStateId = state.prev
+	delete (trace as any).bosunUserMessage
+	delete (trace as any).bosunInputMessageSender
+	if (rawUserMessage) {
+		;(trace as any).bosunUserMessage = rawUserMessage
+	}
+	if (inputMessage) {
+		;(trace as any).bosunInputMessageSender = inputMessage.sender
+	}
+}
+
+function hasInputMessageTrace(history: AgentState['history'], message: Message): boolean {
+	if (!isInputMessage(message)) return true
+	const summary = messageSummary(message)
+	return history.some((entry) => {
+		if (entry.type !== 'conversational-trace') return false
+		const trace = entry.payload
+		if (
+			trace.eventName !== 'received-message' &&
+			trace.eventName !== 'llm-handler-stream-requested'
+		) {
+			return false
+		}
+		const sender = (trace as any)?.bosunInputMessageSender
+		return trace.content === summary && (sender === message.sender || trace.role === message.sender)
+	})
+}
+
+function createInputMessageTrace(
+	message: Message,
+	state: AgentState,
+	medium: ConversationalTrace['medium']
+): ConversationalTrace | null {
+	if (!isInputMessage(message)) return null
+	const trace: ConversationalTrace = {
+		conversationId: state.id,
+		eventName: 'received-message',
+		role: message.sender,
+		medium,
+		content: messageSummary(message),
+		createdAt: stateCreatedAt(state)
+	}
+	attachInputMessageMetadata(trace, state, message)
+	return trace
+}
+
+function stateCreatedAt(state: AgentState): number {
+	const fromId = Date.parse(state.id)
+	if (Number.isFinite(fromId)) return fromId
+	const fromName = Date.parse(state.name)
+	if (Number.isFinite(fromName)) return fromName
+	return Date.now()
+}
+
+function agentMedium(agent: TestAgent | null): ConversationalTrace['medium'] {
+	return agent && isVoiceAgent(agent) ? 'phone' : 'whatsapp'
+}
+
+function userMessage(st: AgentState): string | undefined {
+	const message = latestInputMessage(st)
+	return message ? messageSummary(message) : undefined
+}
+
+function userMessageSender(st: AgentState): 'user' | 'system' | undefined {
+	return latestInputMessage(st)?.sender
 }
 
 async function loadSchemaFile(basePath: string, promptPath: string) {

package/src/backend/roleplay/message-dispatcher.ts

@@ -5,7 +5,6 @@ import type {
 	AgentSateHeader,
 	WsMessage
 } from '../../lib/ws-message'
-import { type Message } from '@recombine-ai/engine'
 
 import {
 	type ApiCallTrace,
@@ -20,8 +19,6 @@ export class MessageDispatcher {
 	private sendWsMessage(message: WsMessage) {
 		if (message.channel === 'app-events') {
 			console.log('<-- ', message.channel, message.event.type)
-		} else if (message.channel === 'chat') {
-			console.log('<-- ', message.channel, message.message)
 		} else if (message.channel === 'step-trace') {
 			console.log('<-- ', message.channel, message.trace?.name)
 		} else if (message.channel === 'api-call-trace') {
@@ -36,10 +33,6 @@ export class MessageDispatcher {
 		this.ws.send(JSON.stringify(message))
 	}
 
-	sendMessage = async (message: Message) => {
-		this.sendWsMessage({ channel: 'chat', message })
-	}
-
 	sendLog = async (message: LogEntry) => {
 		this.sendWsMessage({ channel: 'log', message })
 	}

package/src/backend/roleplay/router.ts

@@ -3,7 +3,7 @@ import path from 'path'
 import { z } from 'zod'
 import { createContext } from '@recombine-ai/engine'
 import type { TRPCRootObject } from '@trpc/server/unstable-core-do-not-import'
-import { getAgentFactories } from '../lib/get-agent-factories'
+import { getAgentCatalog, getAgentFactories } from '../lib/get-agent-factories'
 import { getProjectDataDir } from '../lib/project-data-dir'
 import { getRootPath } from '../lib/get-root-path'
 import type { TrpcContext } from '../lib/trpc-context'
@@ -19,8 +19,13 @@ export function createRolePlayRouter(t: TRPCRootObject<TrpcContext, any, any>) {
 	return t.router({
 		list: t.procedure.query(async () => {
 			const rootPath = await getRootPath()
-			const agentFactories = await getAgentFactories(rootPath)
-			return Object.keys(agentFactories.factories)
+			const project = await getAgentFactories(rootPath)
+			return Object.keys(project.factories)
+		}),
+		catalog: t.procedure.query(async () => {
+			const rootPath = await getRootPath()
+			const project = await getAgentFactories(rootPath)
+			return getAgentCatalog(project)
 		}),
 		analyzeTrace: t.procedure
 			.input(
@@ -104,7 +109,7 @@ export function createRolePlayRouter(t: TRPCRootObject<TrpcContext, any, any>) {
 						if (entry.type !== 'message') continue
 						const payload = entry.payload
 						if (!payload || typeof payload !== 'object') continue
-						if (payload.sender !== 'user') continue
+						if (payload.sender !== 'user' && payload.sender !== 'system') continue
 
 						const rawText = payload.text
 						if (typeof rawText !== 'string') continue
@@ -130,8 +135,6 @@ export function createRolePlayRouter(t: TRPCRootObject<TrpcContext, any, any>) {
 				z.object({
 					agentId: AgentIdSchema,
 					region: z.string().trim().min(1).max(128).nullable().optional(),
-					prevStateId: z.string().trim().min(1).max(2048).nullable(),
-					rawUserMessage: z.string().trim().min(1).max(100_000),
 					context: z.record(z.string(), z.unknown()).nullable().optional(),
 					promptUpdate: z
 						.object({
@@ -155,16 +158,13 @@ export function createRolePlayRouter(t: TRPCRootObject<TrpcContext, any, any>) {
 				const rawStates = await fsStatePersistence.load(stateKey)
 				const states = Array.isArray(rawStates) ? rawStates : []
 				const context =
-					input.context && typeof input.context === 'object'
-						? input.context
-						: ((await fsContextPersistence.load('default')) as Record<string, any>) || {}
+					input.context ??
+					(((await fsContextPersistence.load('default')) as Record<string, any> | null) || {})
 
 				const variants = await generateReplyVariants({
 					agentId: input.agentId,
 					region: input.region ?? null,
 					states,
-					prevStateId: input.prevStateId ?? null,
-					rawUserMessage: input.rawUserMessage,
 					count: input.count,
 					context
 				})
@@ -183,7 +183,6 @@ export function createRolePlayRouter(t: TRPCRootObject<TrpcContext, any, any>) {
 				z.object({
 					agentId: AgentIdSchema,
 					region: z.string().trim().min(1).max(128).nullable().optional(),
-					targetStateId: z.string().trim().min(1).max(2048),
 					state: z.object({
 						history: z.unknown(),
 						schedule: z.unknown()
@@ -194,12 +193,10 @@ export function createRolePlayRouter(t: TRPCRootObject<TrpcContext, any, any>) {
 				const stateKey = resolveAgentStateKey(input.agentId, input.region ?? null)
 				const rawStates = await fsStatePersistence.load(stateKey)
 				const states = Array.isArray(rawStates) ? rawStates : []
-				if (!states.length) throw new Error('No saved roleplay states found for this agent')
-				if (states[states.length - 1]?.id !== input.targetStateId) {
-					throw new Error('Variants can only be applied to the latest saved reply')
-				}
+				const latestState = states.at(-1)
+				if (!latestState) throw new Error('No saved roleplay states found for this agent')
 
-				const nextStates = replaceSavedState(states, input.targetStateId, {
+				const nextStates = replaceSavedState(states, latestState.id, {
 					history: input.state.history as AgentState['history'],
 					schedule: input.state.schedule as AgentState['schedule']
 				})

package/src/backend/roleplay/trace-serialization.spec.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest'
+import { normalizeTracePayload } from './trace-serialization'
+
+describe('normalizeTracePayload', () => {
+	it('keeps error details when trace payloads are JSON serialized', () => {
+		const cause = new Error('schema expected array')
+		const error = new Error('Response parsing error') as Error & {
+			cause?: unknown
+			operation?: string
+		}
+		error.cause = cause
+		error.operation = 'fetchCustomerDetails'
+
+		const normalized = normalizeTracePayload({
+			name: 'request-customer-details',
+			error
+		})
+
+		expect(normalized.error).toMatchObject({
+			name: 'Error',
+			message: 'Response parsing error',
+			operation: 'fetchCustomerDetails',
+			cause: {
+				name: 'Error',
+				message: 'schema expected array'
+			}
+		})
+		expect(JSON.parse(JSON.stringify(normalized)).error).toMatchObject({
+			message: 'Response parsing error',
+			cause: {
+				message: 'schema expected array'
+			}
+		})
+	})
+})

package/src/backend/roleplay/trace-serialization.ts

@@ -0,0 +1,57 @@
+export function normalizeTracePayload<T>(value: T): T {
+	return normalizeValue(value, new WeakMap<object, unknown>()) as T
+}
+
+function normalizeValue(value: unknown, seen: WeakMap<object, unknown>): unknown {
+	if (value == null) return value
+	if (typeof value === 'bigint') return value.toString()
+	if (typeof value !== 'object') return value
+	if (value instanceof Error) return normalizeError(value, seen)
+	if (value instanceof Date) return value.toISOString()
+
+	const existing = seen.get(value)
+	if (existing) return '[Circular]'
+
+	if (Array.isArray(value)) {
+		const next: unknown[] = []
+		seen.set(value, next)
+		for (const item of value) {
+			const normalized = normalizeValue(item, seen)
+			next.push(normalized === undefined ? null : normalized)
+		}
+		return next
+	}
+
+	const next: Record<string, unknown> = {}
+	seen.set(value, next)
+	for (const [key, item] of Object.entries(value)) {
+		next[key] = normalizeValue(item, seen)
+	}
+	return next
+}
+
+function normalizeError(error: Error, seen: WeakMap<object, unknown>): Record<string, unknown> {
+	const existing = seen.get(error)
+	if (existing) return { name: error.name || 'Error', message: '[Circular]' }
+
+	const next: Record<string, unknown> = {
+		name: error.name || 'Error',
+		message: error.message || String(error)
+	}
+	seen.set(error, next)
+
+	if (typeof error.stack === 'string' && error.stack) {
+		next.stack = error.stack
+	}
+
+	if ('cause' in error) {
+		next.cause = normalizeValue((error as Error & { cause?: unknown }).cause, seen)
+	}
+
+	for (const key of Object.getOwnPropertyNames(error)) {
+		if (key in next) continue
+		next[key] = normalizeValue((error as unknown as Record<string, unknown>)[key], seen)
+	}
+
+	return next
+}