@recombine-ai/bosun 0.13.0 → 0.15.0

package/src/lib/api-telescope/latency-timeline-view-state.ts

@@ -0,0 +1,86 @@
+export type LatencyTimelineViewport = {
+	startMs: number
+	endMs: number
+	originMs: number
+}
+
+const STORAGE_KEY = 'bosun.traces.latencyTimelineViewports.v2'
+
+const viewports = new Map<string, LatencyTimelineViewport>()
+let loadedFromSession = false
+
+function isValidViewport(value: unknown): value is LatencyTimelineViewport {
+	if (!value || typeof value !== 'object') return false
+	const next = value as Record<string, unknown>
+	return (
+		typeof next.startMs === 'number' &&
+		Number.isFinite(next.startMs) &&
+		typeof next.endMs === 'number' &&
+		Number.isFinite(next.endMs) &&
+		next.endMs > next.startMs &&
+		typeof next.originMs === 'number' &&
+		Number.isFinite(next.originMs)
+	)
+}
+
+export function rebaseLatencyTimelineViewport(
+	viewport: LatencyTimelineViewport,
+	nextOriginMs: number
+): LatencyTimelineViewport {
+	if (!Number.isFinite(nextOriginMs)) return { ...viewport }
+
+	const originDeltaMs = nextOriginMs - viewport.originMs
+	return {
+		startMs: viewport.startMs + originDeltaMs,
+		endMs: viewport.endMs + originDeltaMs,
+		originMs: nextOriginMs
+	}
+}
+
+function ensureLoadedFromSession() {
+	if (loadedFromSession) return
+	loadedFromSession = true
+	if (typeof window === 'undefined') return
+
+	try {
+		const raw = window.sessionStorage.getItem(STORAGE_KEY)
+		if (!raw) return
+
+		const parsed = JSON.parse(raw) as unknown
+		if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return
+
+		for (const [key, value] of Object.entries(parsed)) {
+			if (!key || !isValidViewport(value)) continue
+			viewports.set(key, value)
+		}
+	} catch {
+		// Ignore stale or unavailable session state.
+	}
+}
+
+function persistToSession() {
+	if (typeof window === 'undefined') return
+
+	try {
+		window.sessionStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify(Object.fromEntries(viewports.entries()))
+		)
+	} catch {
+		// Ignore storage failures; the in-memory map still works for this app session.
+	}
+}
+
+export function getLatencyTimelineViewport(key: string): LatencyTimelineViewport | null {
+	if (!key) return null
+	ensureLoadedFromSession()
+	const viewport = viewports.get(key)
+	return viewport ? { ...viewport } : null
+}
+
+export function persistLatencyTimelineViewport(key: string, viewport: LatencyTimelineViewport) {
+	if (!key || !isValidViewport(viewport)) return
+	ensureLoadedFromSession()
+	viewports.set(key, { ...viewport })
+	persistToSession()
+}

package/src/lib/api-telescope/latency.ts

@@ -0,0 +1,252 @@
+import type { LatencyTrace, Trace } from './types'
+
+export const RESPONSE_LATENCY_THRESHOLD_MS = 800
+const RESPONSE_LATENCY_TRACE_MATCH_TOLERANCE_MS = 250
+
+export type ResponseLatencySpan = {
+	id: string
+	start: number
+	end: number
+	durationMs: number
+	isHigh: boolean
+	startTrace: LatencyTrace
+	speechCreatedTrace: LatencyTrace | null
+	endTrace: LatencyTrace
+	text: string | null
+}
+
+function normalizeNonEmptyString(value: unknown): string | null {
+	if (typeof value !== 'string') return null
+	const trimmed = value.trim()
+	return trimmed ? trimmed : null
+}
+
+function finiteNumber(value: unknown): number | null {
+	return typeof value === 'number' && Number.isFinite(value) ? value : null
+}
+
+function latencyPayload(trace: LatencyTrace): Record<string, unknown> {
+	const payload = trace.payload
+	return payload && typeof payload === 'object' && !Array.isArray(payload)
+		? (payload as Record<string, unknown>)
+		: {}
+}
+
+function latencyText(trace: LatencyTrace): string | null {
+	return normalizeNonEmptyString(latencyPayload(trace).text)
+}
+
+function isCancellationValue(value: unknown): boolean {
+	if (value === true) return true
+	if (typeof value === 'number') return value === 1
+	if (typeof value !== 'string') return false
+
+	const normalized = value.trim().toLowerCase()
+	return (
+		normalized === 'true' ||
+		normalized === '1' ||
+		normalized === 'cancelled' ||
+		normalized === 'canceled' ||
+		normalized === 'dropped' ||
+		normalized === 'discarded' ||
+		normalized === 'aborted' ||
+		normalized === 'superseded'
+	)
+}
+
+function hasCancellationMarker(payload: Record<string, unknown>): boolean {
+	const flagKeys = [
+		'cancelled',
+		'canceled',
+		'isCancelled',
+		'isCanceled',
+		'wasCancelled',
+		'wasCanceled',
+		'dropped',
+		'discarded',
+		'aborted',
+		'superseded'
+	]
+	if (flagKeys.some((key) => isCancellationValue(payload[key]))) return true
+
+	const timestampKeys = [
+		'cancelledAt',
+		'canceledAt',
+		'droppedAt',
+		'discardedAt',
+		'abortedAt',
+		'supersededAt'
+	]
+	if (
+		timestampKeys.some((key) => {
+			const value = payload[key]
+			if (value == null) return false
+			if (typeof value === 'string') return value.trim() !== ''
+			return true
+		})
+	) {
+		return true
+	}
+
+	const status = normalizeNonEmptyString(payload.status)
+	const state = normalizeNonEmptyString(payload.state)
+	const lifecycle = normalizeNonEmptyString(payload.lifecycle)
+	return [status, state, lifecycle].some((value) => value != null && isCancellationValue(value))
+}
+
+function isFinalSttTranscript(trace: LatencyTrace): boolean {
+	return trace.eventType === 'stt.final' || trace.eventType === 'stt.final_transcript'
+}
+
+function isUncancelledSpeechCreated(trace: LatencyTrace): boolean {
+	if (trace.eventType !== 'speech.created') return false
+	const payload = latencyPayload(trace)
+	if (hasCancellationMarker(payload)) return false
+
+	const speech = payload.speech
+	if (speech && typeof speech === 'object' && !Array.isArray(speech)) {
+		return !hasCancellationMarker(speech as Record<string, unknown>)
+	}
+
+	return true
+}
+
+function isAudioSpeechStart(trace: LatencyTrace): boolean {
+	return (
+		trace.eventType === 'audio.output.wait.completed' ||
+		trace.eventType === 'audio.playback.started'
+	)
+}
+
+function compareLatencyTraces(a: LatencyTrace, b: LatencyTrace): number {
+	return (
+		a.seq - b.seq ||
+		a.atMs - b.atMs ||
+		(a.createdAt ?? 0) - (b.createdAt ?? 0) ||
+		String(a.traceId ?? '').localeCompare(String(b.traceId ?? ''))
+	)
+}
+
+function findNextLatencyEvent(
+	events: LatencyTrace[],
+	startIndex: number,
+	match: (trace: LatencyTrace) => boolean,
+	stop: (trace: LatencyTrace) => boolean
+): LatencyTrace | null {
+	for (let index = startIndex + 1; index < events.length; index += 1) {
+		const next = events[index]
+		if (stop(next)) return null
+		if (match(next)) return next
+	}
+	return null
+}
+
+function isUserConversationalTrace(trace: Trace): boolean {
+	return (
+		trace.traceType === 'CONVERSATIONAL' &&
+		trace.role.toLowerCase() === 'user' &&
+		(trace.eventName === 'received-message' || trace.eventName === 'llm-handler-stream-requested')
+	)
+}
+
+function isAgentConversationalTrace(trace: Trace): boolean {
+	return (
+		trace.traceType === 'CONVERSATIONAL' &&
+		(trace.eventName === 'finished-main-streaming-step' || trace.eventName === 'sent-message')
+	)
+}
+
+function findPreviousConversationalTrace(items: Trace[], beforeIndex: number): Trace | null {
+	for (let index = beforeIndex - 1; index >= 0; index -= 1) {
+		const candidate = items[index]
+		if (candidate.traceType === 'CONVERSATIONAL') return candidate
+	}
+	return null
+}
+
+export function findResponseLatencyUserTurn(
+	items: Trace[],
+	span: ResponseLatencySpan
+): Trace | null {
+	const startCreatedAt = finiteNumber(span.startTrace.createdAt)
+	const endCreatedAt = finiteNumber(span.endTrace.createdAt)
+	if (startCreatedAt == null) return null
+
+	for (let index = 0; index < items.length; index += 1) {
+		const candidate = items[index]
+		if (!isAgentConversationalTrace(candidate)) continue
+		if (candidate.createdAt < startCreatedAt - RESPONSE_LATENCY_TRACE_MATCH_TOLERANCE_MS) {
+			continue
+		}
+		if (
+			endCreatedAt != null &&
+			candidate.createdAt < endCreatedAt - RESPONSE_LATENCY_TRACE_MATCH_TOLERANCE_MS
+		) {
+			continue
+		}
+
+		const previous = findPreviousConversationalTrace(items, index)
+		if (!previous || !isUserConversationalTrace(previous)) continue
+		return previous
+	}
+
+	return null
+}
+
+export function buildResponseLatencySpans(input: LatencyTrace[]): ResponseLatencySpan[] {
+	const events = input
+		.slice()
+		.filter(
+			(trace) =>
+				typeof trace.atMs === 'number' &&
+				Number.isFinite(trace.atMs) &&
+				typeof trace.seq === 'number' &&
+				Number.isFinite(trace.seq)
+		)
+		.sort(compareLatencyTraces)
+
+	const built: ResponseLatencySpan[] = []
+
+	events.forEach((trace, index) => {
+		if (!isFinalSttTranscript(trace)) return
+
+		const speechCreated = findNextLatencyEvent(
+			events,
+			index,
+			isUncancelledSpeechCreated,
+			(candidate) =>
+				candidate.eventType === 'call.ended' ||
+				candidate.eventType === 'vad.activated' ||
+				candidate.eventType === 'stt.started' ||
+				isFinalSttTranscript(candidate)
+		)
+
+		const speechCreatedIndex = speechCreated ? events.indexOf(speechCreated) : index
+		const next = findNextLatencyEvent(
+			events,
+			speechCreatedIndex,
+			isAudioSpeechStart,
+			(candidate) =>
+				candidate.eventType === 'call.ended' ||
+				candidate.eventType === 'vad.activated' ||
+				candidate.eventType === 'stt.started' ||
+				isFinalSttTranscript(candidate)
+		)
+		if (!next || next.atMs < trace.atMs) return
+
+		const durationMs = next.atMs - trace.atMs
+		built.push({
+			id: `response-latency:${trace.seq}:${next.seq}`,
+			start: trace.atMs,
+			end: next.atMs,
+			durationMs,
+			isHigh: durationMs > RESPONSE_LATENCY_THRESHOLD_MS,
+			startTrace: trace,
+			speechCreatedTrace: speechCreated,
+			endTrace: next,
+			text: latencyText(trace)
+		})
+	})
+
+	return built
+}

package/src/lib/api-telescope/source-selection.ts

@@ -0,0 +1,20 @@
+export const TELESCOPE_SOURCE_STORAGE_KEY = 'bosun.traces.telescopeSourceId'
+
+export function getPersistedTelescopeSourceId(): string | null {
+	if (typeof window === 'undefined') return null
+	try {
+		return window.localStorage.getItem(TELESCOPE_SOURCE_STORAGE_KEY)
+	} catch {
+		return null
+	}
+}
+
+export function persistTelescopeSourceId(sourceId: string) {
+	if (typeof window === 'undefined') return
+	if (!sourceId || !sourceId.trim()) return
+	try {
+		window.localStorage.setItem(TELESCOPE_SOURCE_STORAGE_KEY, sourceId)
+	} catch {
+		// ignore
+	}
+}

package/src/lib/api-telescope/sources.server.ts

@@ -0,0 +1,94 @@
+import { env } from '$env/dynamic/private'
+import { z } from 'zod'
+
+const TelescopeSourceInputSchema = z
+	.object({
+		id: z.string().optional(),
+		label: z.string().min(1),
+		// Accept either camelCase or the user-friendly names ("url"/"secret")
+		baseUrl: z.string().optional(),
+		url: z.string().optional(),
+		apiKey: z.string().optional(),
+		secret: z.string().optional()
+	})
+	.superRefine((value, ctx) => {
+		const baseUrl = (value.baseUrl ?? value.url ?? '').trim()
+		const apiKey = (value.apiKey ?? value.secret ?? '').trim()
+
+		if (!baseUrl) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['baseUrl'],
+				message: 'baseUrl/url is required'
+			})
+		}
+		if (!apiKey) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['apiKey'],
+				message: 'apiKey/secret is required'
+			})
+		}
+	})
+
+const TelescopeSourcesJsonSchema = z.array(TelescopeSourceInputSchema)
+
+export interface TelescopeSourceConfig {
+	id: string
+	label: string
+	baseUrl: string
+	apiKey: string
+}
+
+function slugify(value: string): string {
+	return value
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '')
+}
+
+function cleanBaseUrl(value: string): string {
+	return value.trim().replace(/\/+$/, '')
+}
+
+function normalizeSources(
+	inputs: z.infer<typeof TelescopeSourcesJsonSchema>
+): TelescopeSourceConfig[] {
+	const usedIds = new Set<string>()
+
+	return inputs.map((input, idx) => {
+		const label = input.label.trim()
+		const baseUrl = cleanBaseUrl(input.baseUrl ?? input.url ?? '')
+		const apiKey = (input.apiKey ?? input.secret ?? '').trim()
+
+		const preferred = typeof input.id === 'string' && input.id.trim() ? input.id.trim() : label
+		let id = slugify(preferred) || `source-${idx + 1}`
+		let deduped = id
+		let i = 2
+		while (usedIds.has(deduped)) {
+			deduped = `${id}-${i++}`
+		}
+		id = deduped
+		usedIds.add(id)
+
+		return { id, label, baseUrl, apiKey }
+	})
+}
+
+export function getTelescopeSources(): TelescopeSourceConfig[] {
+	const rawJson = env.TELESCOPE_SOURCES_JSON
+
+	if (typeof rawJson === 'string' && rawJson.trim()) {
+		let parsed: unknown
+		try {
+			parsed = JSON.parse(rawJson)
+		} catch {
+			throw new Error('TELESCOPE_SOURCES_JSON is not valid JSON')
+		}
+
+		const inputs = TelescopeSourcesJsonSchema.parse(parsed)
+		return normalizeSources(inputs)
+	}
+	return []
+}

package/src/lib/api-telescope/types.ts

@@ -0,0 +1,143 @@
+import { z } from 'zod'
+
+export const TranscriptSegmentSchema = z.object({
+	text: z.string(),
+	role: z.string(), // 'Agent' or 'User'
+	time: z.string(), // ISO timestamp
+	duration: z.number()
+})
+
+export const ConversationSchema = z
+	.object({
+		conversationId: z.string(),
+		medium: z.string(), // 'phone' | 'whatsapp' | ...
+		agentId: z.string().optional(),
+		phoneNumber: z.string().optional(),
+		duration: z.number().optional(),
+		audioUrl: z.string().url().optional(),
+		transcript: z.union([z.string(), z.array(TranscriptSegmentSchema)]).optional(),
+		createdAt: z.number()
+	})
+	.passthrough()
+
+export type Conversation = z.infer<typeof ConversationSchema>
+
+export const PaginatedConversationsResponseSchema = z.object({
+	limit: z.number(),
+	items: z.array(ConversationSchema),
+	lastConversationId: z.string().optional()
+})
+
+export type PaginatedConversationsResponse = z.infer<typeof PaginatedConversationsResponseSchema>
+
+export type GetConversationsRequest = {
+	phoneNumber?: string
+	agentId?: string
+	limit?: number
+	lastConversationId?: string
+}
+
+export const LlmUsageSchema = z
+	.object({
+		promptTokens: z.number().optional(),
+		completionTokens: z.number().optional(),
+		totalTokens: z.number().optional(),
+		cachedPromptTokens: z.number().optional()
+	})
+	.passthrough()
+
+export const StepTraceSchema = z
+	.object({
+		traceType: z.literal('STEP'),
+		traceId: z.string().optional(),
+		conversationId: z.string().optional(),
+		scopeId: z.string().optional(),
+		workflowId: z.string().optional(),
+		workflowRunId: z.string().optional(),
+		name: z.string().optional(),
+		renderedPrompt: z.string().optional(),
+		receivedContext: z.any().optional(),
+		receivedPrompt: z.any().optional(),
+		stringifiedConversation: z.string().optional(),
+		response: z.string().optional(),
+		model: z.string().optional(),
+		llmUsage: LlmUsageSchema.optional(),
+		createdAt: z.number(),
+		error: z.any().optional()
+	})
+	.passthrough()
+
+export const ApiCallTraceSchema = z
+	.object({
+		traceType: z.literal('API_CALL'),
+		traceId: z.string().optional(),
+		conversationId: z.string().optional(),
+		scopeId: z.string().optional(),
+		operationName: z.string(),
+		method: z.string(),
+		path: z.string(),
+		baseUrl: z.string().optional(),
+		request: z.any().optional(),
+		response: z.any().optional(),
+		status: z.number().optional(),
+		ok: z.boolean().optional(),
+		durationMs: z.number().optional(),
+		createdAt: z.number(),
+		error: z.any().optional()
+	})
+	.passthrough()
+
+export const ConversationalTraceSchema = z
+	.object({
+		traceType: z.literal('CONVERSATIONAL'),
+		traceId: z.string().optional(),
+		conversationId: z.string().optional(),
+		scopeId: z.string().optional(),
+		eventName: z.string(),
+		role: z.string(),
+		medium: z.string(),
+		content: z.string(),
+		createdAt: z.number(),
+		error: z.any().optional()
+	})
+	.passthrough()
+
+export const LatencyTraceSchema = z
+	.object({
+		traceType: z.literal('LATENCY'),
+		traceId: z.string().optional(),
+		conversationId: z.string().optional(),
+		seq: z.number(),
+		atMs: z.number(),
+		eventType: z.string(),
+		payload: z.any().optional(),
+		createdAt: z.number()
+	})
+	.passthrough()
+
+export const TraceSchema = z.discriminatedUnion('traceType', [
+	StepTraceSchema,
+	ApiCallTraceSchema,
+	ConversationalTraceSchema
+])
+
+export type StepTrace = z.infer<typeof StepTraceSchema>
+export type ApiCallTrace = z.infer<typeof ApiCallTraceSchema>
+export type ConversationalTrace = z.infer<typeof ConversationalTraceSchema>
+export type LatencyTrace = z.infer<typeof LatencyTraceSchema>
+export type Trace = z.infer<typeof TraceSchema>
+
+export const PaginatedTracesResponseSchema = z.object({
+	items: z.array(TraceSchema),
+	limit: z.number(),
+	lastTraceId: z.string().optional()
+})
+
+export const PaginatedLatencyTracesResponseSchema = z.object({
+	items: z.array(LatencyTraceSchema),
+	limit: z.number(),
+	lastTraceId: z.string().optional()
+})
+
+export type PaginatedTracesResponse = z.infer<typeof PaginatedTracesResponseSchema>
+export type PaginatedLatencyTracesResponse = z.infer<typeof PaginatedLatencyTracesResponseSchema>

package/src/lib/components/Button.svelte

@@ -0,0 +1,62 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte'
+	import type { HTMLButtonAttributes } from 'svelte/elements'
+
+	type Variant = 'primary' | 'secondary' | 'outlined' | 'ghost'
+	type Size = 'big' | 'medium' | 'small'
+
+	interface Props extends HTMLButtonAttributes {
+		variant?: Variant
+		size?: Size
+		type?: 'button' | 'submit' | 'reset'
+		disabled?: boolean
+		class?: string
+		children: Snippet
+		el?: HTMLButtonElement | null
+	}
+
+	let {
+		variant = 'primary',
+		size = 'medium',
+		type = 'button',
+		disabled = false,
+		class: className = '',
+		children,
+		el = $bindable(),
+		...rest
+	}: Props = $props()
+
+	const variantClasses = {
+		primary:
+			'border border-thin border-rc-green-450 backdrop-blur-xl rounded-lg text-rc-gray-100 font-bold bg-rc-green-350 hover:bg-rc-green-250 focus:bg-rc-green-200 focus:outline-none active:bg-rc-green-250',
+		secondary:
+			'border border-thin border-rc-gray-600 backdrop-blur-2xl rounded-lg bg-rc-gray-800 text-rc-gray-100 font-bold hover:bg-rc-gray-700 focus:bg-rc-gray-700 focus:outline-none active:bg-rc-gray-650',
+		outlined:
+			'border border-rc-gray-500 bg-rc-gray-900 font-semibold hover:bg-rc-gray-700 hover:border-rc-gray-400 focus:outline-none focus:ring-0 focus:border-rc-gray-400 active:border-rc-gray-400',
+		ghost: 'bg-transparent rounded-lg hover:text-gray-100 focus:text-gray-100 active:text-gray-100'
+	}
+
+	const sizeClasses = {
+		big: 'px-4 py-2 text-base',
+		medium: 'px-4 py-2 text-base',
+		small: 'px-4 py-2 text-base'
+	}
+
+	let buttonClasses = $derived(
+		`text-gray-200
+    rounded
+    transition-colors
+    disabled:opacity-50
+    disabled:cursor-not-allowed
+    disabled:pointer-events-none
+    ${variantClasses[variant]}
+    ${sizeClasses[size]}
+    cursor-pointer
+    ${className}
+  `.trim()
+	)
+</script>
+
+<button bind:this={el} {type} class={buttonClasses} {disabled} {...rest}>
+	{@render children()}
+</button>