@recombine-ai/bosun 0.18.0 → 0.20.0

package/src/backend/roleplay/agents.ts

@@ -1,756 +0,0 @@
-import { type Message } from '@recombine-ai/engine'
-import {
-	createContext,
-	type TestAgentFactory,
-	type TestAgent,
-	type TestVoiceAgent
-} from '@recombine-ai/bosun-lib'
-import {
-	type ApiCallTrace,
-	type ApiCallTracer,
-	type StepTrace,
-	type ConversationalTrace,
-	type ConversationalTracer,
-	type StepTracer
-} from '@recombine-ai/telescope'
-import type { DelayedActions, LogEntry } from '../../lib/ws-message'
-import fs from 'fs'
-import path, { join } from 'path'
-import type { Context, ContextPersistence, StatePersistence } from './fs-persistence'
-import { createLogger } from './logger'
-import type { MessageDispatcher } from './message-dispatcher'
-import { createScheduler, type BosunScheduler } from './scheduler'
-import { createStepRegistry, type PromptOverrides } 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'
-	payload: Message
-}
-
-interface HistoryLogEntry {
-	type: 'log'
-	payload: LogEntry
-}
-
-interface HistoryTraceEntry {
-	type: 'trace'
-	payload: StepTrace
-}
-
-interface HistoryApiCallTraceEntry {
-	type: 'api-call-trace'
-	payload: ApiCallTrace
-}
-
-interface HistoryConversationalTraceEntry {
-	type: 'conversational-trace'
-	payload: ConversationalTrace
-}
-
-type HistoryEntry =
-	| MessageEntry
-	| HistoryLogEntry
-	| HistoryTraceEntry
-	| HistoryApiCallTraceEntry
-	| HistoryConversationalTraceEntry
-
-export interface AgentState {
-	id: string
-	name: string
-	history: HistoryEntry[]
-	schedule: DelayedActions
-	prev: string | null
-	next: string | null
-}
-
-type AgentWithState = Awaited<ReturnType<typeof loadAgent>>
-
-const agentStates: Record<string, AgentState[]> = {}
-
-export function createAgents(
-	dispatcher: MessageDispatcher,
-	statePersistence: StatePersistence,
-	contextPersistence: ContextPersistence
-) {
-	let factories: Record<string, TestAgentFactory> = {}
-	const agents: Record<string, AgentWithState> = {}
-	let basePath = ''
-	let currentAgent = ''
-	let currentRegion: string | null = null
-	let currentStateId: string | null = null
-	let lastLoadedImportNonce: number | null = null
-
-	function getAgentCacheKey(agentId: string, region: string | null): string {
-		// Region-scoped agent instances let Bosun switch regions without mixing roleplay state.
-		// This mirrors the `<agent>.<region>` suite naming convention used for tests.
-		return region ? `${agentId}.${region}` : agentId
-	}
-
-	async function getCurrentAgent() {
-		if (!currentAgent) {
-			currentAgent = Object.keys(factories)[0]
-		}
-
-		const cacheKey = getAgentCacheKey(currentAgent, currentRegion)
-
-		let agent = agents[cacheKey]
-		if (!agent) {
-			const factory = factories[currentAgent]
-			if (!factory) {
-				throw new Error(`Agent not found ${currentAgent}`)
-			}
-
-			const loadedStatesRaw = await statePersistence.load(cacheKey)
-			const loadedStates = Array.isArray(loadedStatesRaw) ? loadedStatesRaw : []
-			agentStates[cacheKey] = loadedStates
-			agent = await loadAgent({
-				...dispatcher,
-				agentId: cacheKey,
-				region: currentRegion,
-				contextPersistence,
-				statePersistence,
-				factory,
-				basePath,
-				initialStateHistory: loadedStates
-			})
-			agents[cacheKey] = agent
-		}
-		return agent
-	}
-
-	const api = {
-		load: async () => {
-			const rootPath = await getRootPath()
-			const importNonce = getImportNonce()
-			const loaded = await getAgentFactories(rootPath, importNonce)
-
-			if (lastLoadedImportNonce !== null && importNonce !== lastLoadedImportNonce) {
-				// Import nonce changed (e.g. `region-config.json` edited): drop cached agent instances
-				// so newly imported factories/config take effect without restarting Bosun.
-				for (const key of Object.keys(agents)) delete agents[key]
-				for (const key of Object.keys(agentStates)) delete agentStates[key]
-			}
-			lastLoadedImportNonce = importNonce
-			basePath = loaded.basePath
-			factories = loaded.factories
-			console.log(`createAgents, load; loaded agents: ${Object.keys(factories).join(', ')}`)
-			await dispatcher.sendLoaded(Object.keys(factories))
-		},
-		reload: async () => {
-			await api.load()
-			const agentId = currentAgent || Object.keys(factories)[0]
-			if (!agentId) return
-
-			// Force a fresh agent instance so updated factories/config take effect immediately.
-			const cacheKey = getAgentCacheKey(agentId, currentRegion)
-			delete agents[cacheKey]
-			delete agentStates[cacheKey]
-			await api.select(agentId, currentStateId, currentRegion)
-		},
-		select: async (
-			agentId: string,
-			stateId?: string | null,
-			region?: string | null,
-			promptOverrides: PromptOverrides = {}
-		) => {
-			console.log('createAgents, select; agents: ', Object.keys(agents), 'selected: ', agentId)
-			currentAgent = agentId
-			currentRegion = region || null
-			const agent = await getCurrentAgent()
-			// Agent metadata must always reflect the real file, not a pending UI proposal.
-			agent.setPromptOverrides({})
-
-			await dispatcher.sendAgentSelected({
-				id: agentId,
-				type: isVoiceAgent(agent.agent) ? 'voice' : 'text',
-				steps: await Promise.all(
-					agent.stepRegistry.getSteps().map(async (s) => ({
-						name: s.name,
-						prompt: await s.prompt.content(),
-						type: s.type,
-						schema:
-							s.prompt.type === 'file' && s.schema
-								? await loadSchemaFile(agent.basePath, s.prompt.path)
-								: undefined
-					}))
-				)
-			})
-			agent.setPromptOverrides(promptOverrides)
-			if (agent.ctx.get()) {
-				const context = agent.ctx.get()
-				const promptContext = agent.ctx.getPromptContextMapper()(context)
-				await dispatcher.sendContext(context, promptContext)
-			}
-
-			const rawStates = agentStates[getAgentCacheKey(agentId, currentRegion)]
-			const states = Array.isArray(rawStates) ? rawStates : []
-			let isInitialLoad = false
-			if (stateId === undefined && states.length > 0) {
-				stateId = states[states.length - 1].id
-				isInitialLoad = true
-			}
-			currentStateId = stateId ?? null
-			await dispatcher.sendUpdateStates(
-				states.map((state) => ({
-					id: state.id,
-					name: state.name,
-					userMessage: userMessage(state),
-					prev: state.prev,
-					next: state.next
-				}))
-			)
-			await agent.selectState(states, stateId, isInitialLoad)
-		},
-		selectStep: async (step: string) => {
-			await (await getCurrentAgent()).selectStep(step)
-		},
-		updateContext: async (context: Context) => {
-			await (await getCurrentAgent()).updateContext(context)
-		},
-		updatePrompt: async (prompt: string) => {
-			await (await getCurrentAgent()).updatePrompt(prompt)
-		},
-		updatePromptOverrides: async (promptOverrides: PromptOverrides) => {
-			;(await getCurrentAgent()).setPromptOverrides(promptOverrides)
-		},
-		triggerAction: async (action: string) => {
-			await (await getCurrentAgent()).triggerAction(action)
-		},
-		handleMessage: async (message: Message) => {
-			currentStateId = await (await getCurrentAgent()).handleMessage(message)
-		},
-		hangup: async (agentId: string, region: string | null) => {
-			const cacheKey = getAgentCacheKey(agentId, region)
-			const agent = agents[cacheKey]
-			if (!agent) {
-				throw new Error(`Cannot hangup: cannot find agent: ${cacheKey}`)
-			}
-			await agent.hangup()
-		}
-	}
-
-	return api
-}
-
-type Public<T> = { [P in keyof T]: T[P] }
-interface LoadProps extends Public<MessageDispatcher> {
-	agentId: string
-	basePath: string
-	factory: TestAgentFactory
-	region?: string | null
-	contextPersistence: ContextPersistence
-	statePersistence: StatePersistence
-	initialStateHistory: AgentState[]
-}
-
-export async function loadAgent(props: LoadProps) {
-	let states = indexStates(props.initialStateHistory)
-	let state = createLiveStateFromHistory(props.initialStateHistory)
-	let currentStep = ''
-	let scheduler: BosunScheduler | null = null
-	let agent: TestAgent | null = null
-	const ctx = createContext({})
-	if (props.region) {
-		const current = (ctx.get() as Record<string, unknown> | null | undefined) || {}
-		ctx.set({ ...current, recombineRegion: props.region })
-	}
-	ctx.subscribe((context) => {
-		console.log('------ context updated --------')
-		const promptContext = ctx.getPromptContextMapper()(context)
-		void props.sendContext(context, promptContext)
-	})
-	const logger = createLogger((msg) => {
-		state.history.push({
-			type: 'log',
-			payload: msg
-		})
-		void props.sendLog(msg)
-	})
-
-	const stepTracer: StepTracer = {
-		addStepTrace: (stepTrace) => {
-			const normalizedTrace = normalizeTracePayload(stepTrace)
-			state.history.push({
-				type: 'trace',
-				payload: normalizedTrace
-			})
-			void props.sendTrace(normalizedTrace)
-		},
-		async flush() {}
-	}
-
-	const apiCallTracer: ApiCallTracer = {
-		addApiCallTrace: (apiCallTrace) => {
-			const normalizedTrace = normalizeTracePayload(apiCallTrace)
-			logger.log(
-				'[apiCallTracer] addApiCallTrace',
-				normalizedTrace?.operationName,
-				normalizedTrace?.method,
-				normalizedTrace?.path
-			)
-			state.history.push({
-				type: 'api-call-trace',
-				payload: normalizedTrace
-			})
-			void props.sendApiCallTrace(normalizedTrace)
-		},
-		async flush() {}
-	}
-
-	const conversationalTracer: ConversationalTracer = {
-		addConversationalTrace: (conversationalTrace) => {
-			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',
-				normalizedTrace?.eventName,
-				normalizedTrace?.role
-			)
-			state.history.push({
-				type: 'conversational-trace',
-				payload: normalizedTrace
-			})
-			void props.sendConversationalTrace(normalizedTrace)
-		},
-		async flush() {}
-	}
-
-	const stepRegistry = createStepRegistry(logger)
-
-	scheduler = createScheduler({
-		logger,
-		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,
-		logger,
-		apiCallTracer,
-		conversationalTracer,
-		scheduler,
-		getMessages: () => {
-			const messages: Array<MessageEntry['payload']> = []
-			let curState = state
-			while (true) {
-				curState.history
-					.filter((entry) => entry.type === 'message')
-					.reverse()
-					.forEach((entry) => {
-						messages.push(entry.payload)
-					})
-				if (!curState.prev) {
-					break
-				}
-				curState = states[curState.prev]
-			}
-			return messages.reverse()
-		},
-		sendMessage: sendAgentMessage,
-		ctx,
-		config: {
-			enableTimers: false,
-			isTest: false
-		}
-	})
-
-	// loading agent from factory loads it with default context.
-	// if saved context is not empty, let's replace context in ctx with it.
-	const savedContext = await props.contextPersistence.load('default')
-	if (savedContext && Object.keys(savedContext).length > 0) {
-		ctx.set(props.region ? { ...savedContext, recombineRegion: props.region } : savedContext)
-	} else if (ctx.get()) {
-		await props.contextPersistence.save('default', ctx.get())
-	}
-
-	const latestSavedState = props.initialStateHistory[props.initialStateHistory.length - 1]
-	if (latestSavedState) {
-		scheduler?.setState(latestSavedState.schedule)
-	}
-
-	async function saveStates(states: AgentState[]) {
-		await props.statePersistence.save(props.agentId, states)
-		agentStates[props.agentId] = states
-		console.log('------------- save states ---------------')
-		states.forEach((state) => {
-			console.log('State:', state.name, state.prev, state.next)
-		})
-		console.log('-----------------------------------------')
-
-		await props.sendUpdateStates(
-			states.map((state) => ({
-				id: state.id,
-				name: state.name,
-				userMessage: userMessage(state),
-				userMessageSender: userMessageSender(state),
-				prev: state.prev,
-				next: state.next
-			}))
-		)
-	}
-
-	async function addState() {
-		if (!scheduler) {
-			throw new Error('Cannot add state: agent is not initialized')
-		}
-		console.log('!! add state')
-		const savedStateId = state.id
-		const newState = createState(scheduler.serialize(), state.id)
-		state.next = newState.id
-		states[state.id] = clone({ ...state, schedule: scheduler.serialize() })
-		await saveStates(Object.values(states))
-		state = newState
-		return savedStateId
-	}
-
-	return {
-		agent,
-		stepRegistry,
-		basePath: props.basePath,
-		ctx,
-		setPromptOverrides: (promptOverrides: PromptOverrides) => {
-			stepRegistry.setPromptOverrides(promptOverrides)
-		},
-		selectState: async (
-			stateHistory: AgentState[],
-			stateId?: string | null,
-			isInitialLoad?: boolean
-		) => {
-			states = indexStates(stateHistory)
-			console.log('states: ' + stateHistory.length, stateId)
-			if (stateHistory.length === 0 || !stateId) {
-				// this agent loaded for the first time
-				console.log(' --- init agent ---')
-				state = createState({}, null)
-				if (agent) {
-					if (isVoiceAgent(agent)) {
-						const callStartResult = await agent.onCallStart()
-						await sendCallStartMessage(callStartResult, sendAgentMessage)
-					} else {
-						await agent.start()
-					}
-				}
-				return
-			}
-			let loadedState = states[stateId]
-			if (!loadedState) {
-				return
-			}
-			console.log(' --- loaded state history: ', loadedState.history.length, '---')
-			state = loadedState
-			const replay: AgentState[] = []
-			replay.push(loadedState)
-			while (loadedState.prev) {
-				loadedState = states[loadedState.prev]
-				replay.push(loadedState)
-			}
-			console.log('replay: ' + replay.length)
-			replay.reverse().forEach((state) => {
-				state.history.forEach((entry, index) => {
-					switch (entry.type) {
-						case 'message':
-							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':
-							void props.sendLog(entry.payload)
-							break
-						case 'trace':
-							void props.sendTrace(entry.payload)
-							break
-						case 'api-call-trace':
-							void props.sendApiCallTrace(entry.payload)
-							break
-						case 'conversational-trace': {
-							const inputMessage = inputMessageBefore(state.history, index)
-							attachInputMessageMetadata(entry.payload, state, inputMessage)
-							void props.sendConversationalTrace(entry.payload)
-							break
-						}
-					}
-				})
-			})
-			scheduler?.setState(state.schedule)
-			// Always move to a fresh, unsaved state so the next message doesn't mutate the selected snapshot.
-			state = createState(scheduler?.serialize() ?? state.schedule, state.id)
-		},
-		selectStep: async (step: string) => {
-			currentStep = step
-		},
-		updateContext: async (context: Context) => {
-			ctx.swap(context)
-			await props.contextPersistence.save('default', context)
-		},
-		updatePrompt: async (prompt: string) => {
-			const selectedStep = stepRegistry.getSteps().find((s) => s.name === currentStep)
-			if (selectedStep?.prompt.type !== 'file') {
-				return
-			}
-			const promptPath = selectedStep.prompt.path
-			// TODO replace with persistence
-			const resolvedPath = join(props.basePath, promptPath)
-			try {
-				await fs.promises.writeFile(resolvedPath, prompt, 'utf-8')
-				console.debug('FS: saved prompt:', promptPath)
-			} catch (error) {
-				console.error('FS: failed to save prompt:', error)
-			}
-		},
-		triggerAction: async (action: string) => {
-			if (!agent) {
-				throw new Error('Cannot trigger action: agent is not initialized')
-			}
-			if (!scheduler) {
-				throw new Error('Cannot trigger action: scheduler is not initialized')
-			}
-			if ('isAssigned' in agent && (await agent.isAssigned())) {
-				try {
-					await scheduler.triggerAction(action)
-				} catch (e) {
-					await agent.onFatalError(e as any)
-				}
-				state.schedule = scheduler.serialize()
-			}
-		},
-		hangup() {
-			if (!agent) {
-				throw new Error('Cannot trigger hangup: agent is not initialized')
-			}
-			if (!isVoiceAgent(agent)) {
-				throw new Error('Cannot hangup: not a voice agent')
-			}
-			return agent.onCallEnd()
-		},
-		handleMessage: async (message: Message) => {
-			if (!agent) {
-				throw new Error('Cannot handle message: agent is not initialized')
-			}
-			console.log(' --- handle message --- ')
-			state.history.push({
-				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 {
-				// text agent
-				if (await agent.isAssigned()) {
-					try {
-						await agent.reactOnMessage()
-
-						await agent.respondToMessage()
-					} catch (e) {
-						await agent.onFatalError(e as any)
-					}
-				}
-			}
-			return await addState()
-		}
-	}
-}
-
-function isVoiceAgent(agent: TestAgent): agent is TestVoiceAgent {
-	return 'streamResponse' in agent
-}
-
-function createState(schedule: DelayedActions, prev: string | null) {
-	const state: AgentState = {
-		id: new Date().toISOString(),
-		name: new Date().toLocaleString(),
-		history: [],
-		schedule,
-		prev,
-		next: null
-	}
-
-	return state
-}
-
-function clone(obj: any) {
-	return normalizeTracePayload(obj)
-}
-
-function indexStates(stateHistory: AgentState[]) {
-	const states: Record<string, AgentState> = {}
-	stateHistory.forEach((state) => {
-		states[state.id] = state
-	})
-	return states
-}
-
-function createLiveStateFromHistory(stateHistory: AgentState[]) {
-	const latestSavedState = stateHistory[stateHistory.length - 1]
-	if (!latestSavedState) {
-		return createState({}, null)
-	}
-
-	return createState(clone(latestSavedState.schedule ?? {}), latestSavedState.id)
-}
-
-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
-			if (isInputMessage(m)) return m
-		}
-	}
-	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) {
-	const dir = path.dirname(promptPath)
-	const schemaPath = join(basePath, dir, 'schema.ts')
-	console.log('loadSchemaFile', schemaPath)
-	try {
-		return await fs.promises.readFile(schemaPath, 'utf-8')
-	} catch (e) {
-		// console.error(e)
-	}
-}