@kitlangton/motel 0.1.0

package/src/daemon.ts

@@ -0,0 +1,398 @@
+import * as fs from "node:fs"
+import { promises as fsp } from "node:fs"
+import * as path from "node:path"
+import { Effect } from "effect"
+import { listAliveEntries, MOTEL_SERVICE_ID, type RegistryEntry, isAlive } from "./registry.js"
+
+const DEFAULT_REPO_ROOT = path.resolve(import.meta.dir, "..")
+const DEFAULT_RUNTIME_DIR = path.join(DEFAULT_REPO_ROOT, ".motel-data")
+const DEFAULT_DATABASE_PATH = path.join(DEFAULT_RUNTIME_DIR, "telemetry.sqlite")
+const DEFAULT_HOST = "127.0.0.1"
+const DEFAULT_PORT = 27686
+const START_TIMEOUT_MS = 15_000
+const STOP_TIMEOUT_MS = 10_000
+const LOCK_TIMEOUT_MS = 10_000
+const POLL_INTERVAL_MS = 150
+
+type HealthShape = {
+	readonly ok: boolean
+	readonly service: string
+	readonly databasePath: string
+	readonly pid: number
+	readonly url: string
+	readonly workdir: string
+	readonly startedAt: string
+	readonly version: string
+}
+
+type LockShape = {
+	readonly pid: number
+	readonly createdAt: string
+}
+
+type DaemonConfig = {
+	readonly repoRoot: string
+	readonly runtimeDir: string
+	readonly databasePath: string
+	readonly logPath: string
+	readonly lockPath: string
+	readonly host: string
+	readonly port: number
+	readonly baseUrl: string
+}
+
+export type DaemonStatus = {
+	readonly running: boolean
+	readonly managed: boolean
+	readonly service: string | null
+	readonly pid: number | null
+	readonly url: string
+	readonly databasePath: string
+	readonly workdir: string | null
+	readonly startedAt: string | null
+	readonly version: string | null
+	readonly sameWorkdir: boolean
+	readonly reason: string | null
+	readonly logPath: string
+	readonly lockPath: string
+	readonly registryPid: number | null
+}
+
+export type DaemonManager = {
+	readonly applyEnv: Effect.Effect<void>
+	readonly getStatus: Effect.Effect<DaemonStatus, DaemonError>
+	readonly ensure: Effect.Effect<DaemonStatus, DaemonError>
+	readonly stop: Effect.Effect<DaemonStatus, DaemonError>
+}
+
+type DaemonOptions = {
+	readonly repoRoot?: string
+	readonly runtimeDir?: string
+	readonly databasePath?: string
+	readonly host?: string
+	readonly port?: number
+}
+
+export class DaemonError extends Error {
+	readonly _tag = "DaemonError"
+	constructor(message: string) {
+		super(message)
+	}
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+const resolveConfig = (options: DaemonOptions = {}): DaemonConfig => {
+	const repoRoot = path.resolve(options.repoRoot ?? DEFAULT_REPO_ROOT)
+	const runtimeDir = path.resolve(options.runtimeDir ?? DEFAULT_RUNTIME_DIR)
+	const databasePath = path.resolve(options.databasePath ?? path.join(runtimeDir, "telemetry.sqlite"))
+	const host = options.host ?? DEFAULT_HOST
+	const port = options.port ?? DEFAULT_PORT
+	return {
+		repoRoot,
+		runtimeDir,
+		databasePath,
+		logPath: path.join(runtimeDir, "daemon.log"),
+		lockPath: path.join(runtimeDir, "daemon.lock"),
+		host,
+		port,
+		baseUrl: `http://${host}:${port}`,
+	}
+}
+
+const cwdMatches = (workdir: string) => {
+	const cwd = process.cwd()
+	const normalizedCwd = cwd.endsWith(path.sep) ? cwd : `${cwd}${path.sep}`
+	const normalizedWorkdir = workdir.endsWith(path.sep) ? workdir : `${workdir}${path.sep}`
+	return normalizedCwd === normalizedWorkdir || normalizedCwd.startsWith(normalizedWorkdir)
+}
+
+const pickByCwd = (entries: readonly RegistryEntry[]) => {
+	const cwd = process.cwd()
+	const withSep = cwd.endsWith(path.sep) ? cwd : `${cwd}${path.sep}`
+	return entries
+		.filter((entry) => {
+			const workdir = entry.workdir.endsWith(path.sep) ? entry.workdir : `${entry.workdir}${path.sep}`
+			return withSep === workdir || withSep.startsWith(workdir)
+		})
+		.sort((a, b) => b.workdir.length - a.workdir.length)[0] ?? null
+}
+
+const readRegistryEntry = () => pickByCwd(listAliveEntries())
+
+const expectedEnv = (config: DaemonConfig) => ({
+	MOTEL_OTEL_BASE_URL: config.baseUrl,
+	MOTEL_OTEL_QUERY_URL: config.baseUrl,
+	MOTEL_OTEL_HOST: config.host,
+	MOTEL_OTEL_PORT: String(config.port),
+	MOTEL_OTEL_DB_PATH: config.databasePath,
+	MOTEL_OTEL_EXPORTER_URL: `${config.baseUrl}/v1/traces`,
+	MOTEL_OTEL_LOGS_EXPORTER_URL: `${config.baseUrl}/v1/logs`,
+})
+
+export const createDaemonManager = (options: DaemonOptions = {}): DaemonManager => {
+	const config = resolveConfig(options)
+	const mapError = (error: unknown) => new DaemonError(error instanceof Error ? error.message : String(error))
+
+	const fetchHealth = async (): Promise<HealthShape | null> => {
+		try {
+			const response = await fetch(`${config.baseUrl}/api/health`, { signal: AbortSignal.timeout(750) })
+			if (!response.ok) return null
+			return await response.json() as HealthShape
+		} catch {
+			return null
+		}
+	}
+
+	const describeManagedMismatch = (health: HealthShape) => {
+		if (health.service !== MOTEL_SERVICE_ID) {
+			return `Port ${config.port} is in use by ${health.service}, not ${MOTEL_SERVICE_ID}.`
+		}
+		if (!cwdMatches(health.workdir)) {
+			return `Port ${config.port} is serving motel for ${health.workdir}, not ${process.cwd()}.`
+		}
+		if (health.databasePath !== config.databasePath) {
+			return `Port ${config.port} is serving motel with ${health.databasePath}, expected ${config.databasePath}.`
+		}
+		return null
+	}
+
+	const readLock = async (): Promise<LockShape | null> => {
+		try {
+			const raw = await fsp.readFile(config.lockPath, "utf8")
+			return JSON.parse(raw) as LockShape
+		} catch {
+			return null
+		}
+	}
+
+	const removeStaleLock = async () => {
+		const current = await readLock()
+		if (!current) {
+			await fsp.rm(config.lockPath, { force: true })
+			return true
+		}
+		if (isAlive(current.pid)) return false
+		await fsp.rm(config.lockPath, { force: true })
+		return true
+	}
+
+	const acquireStartupLock = async () => {
+		const deadline = Date.now() + LOCK_TIMEOUT_MS
+		await fsp.mkdir(config.runtimeDir, { recursive: true })
+
+		while (Date.now() < deadline) {
+			try {
+				const handle = await fsp.open(config.lockPath, "wx")
+				const contents = JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() } satisfies LockShape)
+				await handle.writeFile(contents, "utf8")
+				return {
+					release: async () => {
+						await handle.close().catch(() => undefined)
+						await fsp.rm(config.lockPath, { force: true }).catch(() => undefined)
+					},
+				}
+			} catch (error) {
+				const errno = error as NodeJS.ErrnoException
+				if (errno.code !== "EEXIST") throw error
+				if (await removeStaleLock()) continue
+				await sleep(POLL_INTERVAL_MS)
+			}
+		}
+
+		throw new Error(`Timed out waiting for daemon startup lock at ${config.lockPath}`)
+	}
+
+	const openLogFile = async () => {
+		await fsp.mkdir(config.runtimeDir, { recursive: true })
+		return fs.openSync(config.logPath, "a")
+	}
+
+	const waitForHealthy = async (pid: number) => {
+		const deadline = Date.now() + START_TIMEOUT_MS
+		while (Date.now() < deadline) {
+			const health = await fetchHealth()
+			if (health) {
+				const mismatch = describeManagedMismatch(health)
+				if (!mismatch) return health
+				throw new Error(mismatch)
+			}
+			if (!isAlive(pid)) {
+				throw new Error(`Daemon process ${pid} exited before becoming healthy. See ${config.logPath}.`)
+			}
+			await sleep(POLL_INTERVAL_MS)
+		}
+		throw new Error(`Timed out waiting for daemon health at ${config.baseUrl}/api/health. See ${config.logPath}.`)
+	}
+
+	const stopPid = async (pid: number) => {
+		try {
+			process.kill(pid, "SIGTERM")
+		} catch (error) {
+			const errno = error as NodeJS.ErrnoException
+			if (errno.code !== "ESRCH") throw error
+		}
+
+		const deadline = Date.now() + STOP_TIMEOUT_MS
+		while (Date.now() < deadline) {
+			if (!isAlive(pid)) return
+			const health = await fetchHealth()
+			if (!health || health.pid !== pid) return
+			await sleep(POLL_INTERVAL_MS)
+		}
+
+		throw new Error(`Timed out waiting for daemon ${pid} to stop.`)
+	}
+
+	const getStatus = async (): Promise<DaemonStatus> => {
+		const registry = readRegistryEntry()
+		const health = await fetchHealth()
+		if (!health) {
+			return {
+				running: false,
+				managed: false,
+				service: null,
+				pid: registry?.pid ?? null,
+				url: config.baseUrl,
+				databasePath: config.databasePath,
+				workdir: registry?.workdir ?? null,
+				startedAt: registry?.startedAt ?? null,
+				version: registry?.version ?? null,
+				sameWorkdir: registry ? cwdMatches(registry.workdir) : false,
+				reason: registry ? "Registry entry exists but daemon is not healthy." : null,
+				logPath: config.logPath,
+				lockPath: config.lockPath,
+				registryPid: registry?.pid ?? null,
+			}
+		}
+
+		const mismatch = describeManagedMismatch(health)
+		return {
+			running: mismatch === null,
+			managed: mismatch === null,
+			service: health.service,
+			pid: health.pid,
+			url: health.url,
+			databasePath: health.databasePath,
+			workdir: health.workdir,
+			startedAt: health.startedAt,
+			version: health.version,
+			sameWorkdir: cwdMatches(health.workdir),
+			reason: mismatch,
+			logPath: config.logPath,
+			lockPath: config.lockPath,
+			registryPid: registry?.pid ?? null,
+		}
+	}
+
+	const ensure = async (): Promise<DaemonStatus> => {
+		const existing = await getStatus()
+		if (existing.managed && existing.running) return existing
+		if (existing.service !== null && existing.reason) {
+			throw new Error(existing.reason)
+		}
+
+		const lock = await acquireStartupLock()
+		let spawnedPid: number | null = null
+		try {
+			const rechecked = await getStatus()
+			if (rechecked.managed && rechecked.running) return rechecked
+			if (rechecked.service !== null && rechecked.reason) {
+				throw new Error(rechecked.reason)
+			}
+
+			const logFd = await openLogFile()
+			try {
+				const proc = Bun.spawn({
+					cmd: [process.execPath, "run", "src/server.ts"],
+					cwd: config.repoRoot,
+					detached: true,
+					env: {
+						...process.env,
+						...expectedEnv(config),
+					},
+					stdio: ["ignore", logFd, logFd],
+				})
+				spawnedPid = proc.pid
+				proc.unref()
+			} finally {
+				fs.closeSync(logFd)
+			}
+
+			if (spawnedPid === null) {
+				throw new Error("Daemon failed to spawn.")
+			}
+
+			const health = await waitForHealthy(spawnedPid)
+			return {
+				running: true,
+				managed: true,
+				service: health.service,
+				pid: health.pid,
+				url: health.url,
+				databasePath: health.databasePath,
+				workdir: health.workdir,
+				startedAt: health.startedAt,
+				version: health.version,
+				sameWorkdir: cwdMatches(health.workdir),
+				reason: null,
+				logPath: config.logPath,
+				lockPath: config.lockPath,
+				registryPid: health.pid,
+			}
+		} catch (error) {
+			if (spawnedPid !== null) {
+				await stopPid(spawnedPid).catch(() => undefined)
+			}
+			throw error
+		} finally {
+			await lock.release()
+		}
+	}
+
+	const stop = async (): Promise<DaemonStatus> => {
+		const status = await getStatus()
+		if (status.pid === null) return status
+		if (!status.sameWorkdir) {
+			throw new Error(`Refusing to stop motel owned by ${status.workdir}.`)
+		}
+		if (status.service !== null && status.service !== MOTEL_SERVICE_ID) {
+			throw new Error(`Refusing to stop non-motel service ${status.service} on ${status.url}.`)
+		}
+		await stopPid(status.pid)
+		return await getStatus()
+	}
+
+	return {
+		applyEnv: Effect.sync(() => {
+			for (const [key, value] of Object.entries(expectedEnv(config))) {
+				process.env[key] = value
+			}
+		}),
+		getStatus: Effect.fn("DaemonManager.getStatus")(() =>
+			Effect.tryPromise({
+				try: getStatus,
+				catch: mapError,
+			}),
+		)(),
+		ensure: Effect.fn("DaemonManager.ensure")(() =>
+			Effect.tryPromise({
+				try: ensure,
+				catch: mapError,
+			}),
+		)(),
+		stop: Effect.fn("DaemonManager.stop")(() =>
+			Effect.tryPromise({
+				try: stop,
+				catch: mapError,
+			}),
+		)(),
+	}
+}
+
+const defaultManager = createDaemonManager()
+
+export const applyManagedDaemonEnv = defaultManager.applyEnv
+export const getManagedDaemonStatus = defaultManager.getStatus
+export const ensureManagedDaemon = defaultManager.ensure
+export const stopManagedDaemon = defaultManager.stop

package/src/domain.ts

@@ -0,0 +1,233 @@
+import { Schema } from "effect"
+
+// ---------------------------------------------------------------------------
+// Reusable helpers
+// ---------------------------------------------------------------------------
+
+const StringRecord = Schema.Record(Schema.String, Schema.String)
+
+const DateFromString = Schema.DateFromString
+
+// ---------------------------------------------------------------------------
+// Core telemetry domain types (Schema is the single source of truth)
+// ---------------------------------------------------------------------------
+
+export const TraceSpanStatus = Schema.Literals(["ok", "error"])
+export type TraceSpanStatus = typeof TraceSpanStatus.Type
+
+export const TraceSpanEvent = Schema.Struct({
+	name: Schema.String.pipe(Schema.annotateKey({ description: "Event name" })),
+	timestamp: DateFromString.pipe(Schema.annotateKey({ description: "ISO 8601 timestamp" })),
+	attributes: StringRecord.pipe(Schema.annotateKey({ description: "Key-value attributes attached to the event" })),
+}).annotate({ identifier: "TraceSpanEvent" })
+
+export type TraceSpanEvent = typeof TraceSpanEvent.Type
+
+export const TraceSpanItem = Schema.Struct({
+	spanId: Schema.String,
+	parentSpanId: Schema.NullOr(Schema.String),
+	serviceName: Schema.String,
+	scopeName: Schema.NullOr(Schema.String).pipe(Schema.annotateKey({ description: "Instrumentation scope (e.g. module or library name)" })),
+	kind: Schema.NullOr(Schema.String).pipe(Schema.annotateKey({ description: "Span kind: client, server, producer, consumer, or internal" })),
+	operationName: Schema.String.pipe(Schema.annotateKey({ description: "The operation this span represents (e.g. HTTP handler, DB query)" })),
+	startTime: DateFromString.pipe(Schema.annotateKey({ description: "ISO 8601 timestamp" })),
+	isRunning: Schema.Boolean.pipe(Schema.annotateKey({ description: "True when the span has not reported an end timestamp yet" })),
+	durationMs: Schema.Number.pipe(Schema.annotateKey({ description: "Wall-clock duration in milliseconds" })),
+	status: TraceSpanStatus.pipe(Schema.annotateKey({ description: "ok or error" })),
+	depth: Schema.Number.pipe(Schema.annotateKey({ description: "Nesting depth in the span tree (root = 0)" })),
+	tags: StringRecord.pipe(Schema.annotateKey({ description: "Span attributes as key-value pairs" })),
+	warnings: Schema.Array(Schema.String).pipe(Schema.annotateKey({ description: "Structural warnings (e.g. missing parent span)" })),
+	events: Schema.Array(TraceSpanEvent),
+}).annotate({ identifier: "TraceSpan" })
+
+export type TraceSpanItem = typeof TraceSpanItem.Type
+
+export const TraceItem = Schema.Struct({
+	traceId: Schema.String,
+	serviceName: Schema.String.pipe(Schema.annotateKey({ description: "Service that owns the root span" })),
+	rootOperationName: Schema.String.pipe(Schema.annotateKey({ description: "Operation name of the root span" })),
+	startedAt: DateFromString.pipe(Schema.annotateKey({ description: "ISO 8601 timestamp of the earliest span" })),
+	isRunning: Schema.Boolean.pipe(Schema.annotateKey({ description: "True when any span in the trace is still open" })),
+	durationMs: Schema.Number.pipe(Schema.annotateKey({ description: "End-to-end trace duration in milliseconds" })),
+	spanCount: Schema.Number,
+	errorCount: Schema.Number.pipe(Schema.annotateKey({ description: "Number of spans with status=error" })),
+	warnings: Schema.Array(Schema.String),
+	spans: Schema.Array(TraceSpanItem).pipe(Schema.annotateKey({ description: "Spans ordered by parent-child hierarchy, depth-first" })),
+}).annotate({ identifier: "Trace" })
+
+export type TraceItem = typeof TraceItem.Type
+
+export const TraceSummaryItem = Schema.Struct({
+	traceId: Schema.String,
+	serviceName: Schema.String,
+	rootOperationName: Schema.String,
+	startedAt: DateFromString.pipe(Schema.annotateKey({ description: "ISO 8601 timestamp" })),
+	isRunning: Schema.Boolean,
+	durationMs: Schema.Number,
+	spanCount: Schema.Number,
+	errorCount: Schema.Number,
+	warnings: Schema.Array(Schema.String),
+}).annotate({ identifier: "TraceSummary" })
+
+export type TraceSummaryItem = typeof TraceSummaryItem.Type
+
+export const SpanItem = Schema.Struct({
+	traceId: Schema.String,
+	rootOperationName: Schema.String.pipe(Schema.annotateKey({ description: "Operation name of the trace's root span, for context" })),
+	parentOperationName: Schema.NullOr(Schema.String).pipe(Schema.annotateKey({ description: "Parent span operation name, if present" })),
+	span: TraceSpanItem,
+}).annotate({ identifier: "SpanWithContext" })
+
+export type SpanItem = typeof SpanItem.Type
+
+export const LogItem = Schema.Struct({
+	id: Schema.String,
+	timestamp: DateFromString.pipe(Schema.annotateKey({ description: "ISO 8601 timestamp" })),
+	serviceName: Schema.String,
+	severityText: Schema.String.pipe(Schema.annotateKey({ description: "Log level: TRACE, DEBUG, INFO, WARN, ERROR, FATAL" })),
+	body: Schema.String.pipe(Schema.annotateKey({ description: "Log message body" })),
+	traceId: Schema.NullOr(Schema.String).pipe(Schema.annotateKey({ description: "Associated trace ID, if the log was emitted inside a span" })),
+	spanId: Schema.NullOr(Schema.String).pipe(Schema.annotateKey({ description: "Associated span ID, if the log was emitted inside a span" })),
+	scopeName: Schema.NullOr(Schema.String),
+	attributes: StringRecord.pipe(Schema.annotateKey({ description: "Merged resource + log attributes as key-value pairs" })),
+}).annotate({ identifier: "Log" })
+
+export type LogItem = typeof LogItem.Type
+
+// ---------------------------------------------------------------------------
+// Shared query result types
+// ---------------------------------------------------------------------------
+
+export const FacetItem = Schema.Struct({
+	value: Schema.String.pipe(Schema.annotateKey({ description: "Distinct value for the faceted field" })),
+	count: Schema.Number.pipe(Schema.annotateKey({ description: "Number of occurrences" })),
+}).annotate({ identifier: "Facet" })
+
+export type FacetItem = typeof FacetItem.Type
+
+export const StatsItem = Schema.Struct({
+	group: Schema.String.pipe(Schema.annotateKey({ description: "Grouping key" })),
+	value: Schema.Number.pipe(Schema.annotateKey({ description: "Aggregate value for the chosen metric" })),
+	count: Schema.Number.pipe(Schema.annotateKey({ description: "Number of samples in the group" })),
+}).annotate({ identifier: "Stat" })
+
+export type StatsItem = typeof StatsItem.Type
+
+// ---------------------------------------------------------------------------
+// AI Call types
+// ---------------------------------------------------------------------------
+
+/** Maps normalized field names to the AI SDK attribute keys in span_attributes */
+export const AI_ATTR_MAP = {
+	operationId: "ai.operationId",
+	functionId: "ai.telemetry.functionId",
+	provider: "ai.model.provider",
+	model: "ai.model.id",
+	sessionId: "ai.telemetry.metadata.sessionId",
+	userId: "ai.telemetry.metadata.userId",
+	finishReason: "ai.response.finishReason",
+	inputTokens: "ai.usage.inputTokens",
+	outputTokens: "ai.usage.outputTokens",
+	totalTokens: "ai.usage.totalTokens",
+	cachedInputTokens: "ai.usage.cachedInputTokens",
+	reasoningTokens: "ai.usage.reasoningTokens",
+	msToFirstChunk: "ai.response.msToFirstChunk",
+	msToFinish: "ai.response.msToFinish",
+	avgOutputTokensPerSecond: "ai.response.avgOutputTokensPerSecond",
+	promptMessages: "ai.prompt.messages",
+	prompt: "ai.prompt",
+	responseText: "ai.response.text",
+	tools: "ai.prompt.tools",
+	toolChoice: "ai.prompt.toolChoice",
+	providerMetadata: "ai.response.providerMetadata",
+	responseModel: "ai.response.model",
+	responseId: "ai.response.id",
+	responseTimestamp: "ai.response.timestamp",
+} as const
+
+/** Attribute keys to search across when using the `text` filter */
+export const AI_TEXT_SEARCH_KEYS = [
+	"ai.prompt.messages",
+	"ai.prompt",
+	"ai.response.text",
+	"ai.prompt.tools",
+] as const
+
+const PREVIEW_LENGTH = 200
+
+export const truncatePreview = (value: string | null | undefined): string | null => {
+	if (!value) return null
+	if (value.length <= PREVIEW_LENGTH) return value
+	return value.slice(0, PREVIEW_LENGTH) + "..."
+}
+
+export const AiUsage = Schema.Struct({
+	inputTokens: Schema.NullOr(Schema.Number),
+	outputTokens: Schema.NullOr(Schema.Number),
+	totalTokens: Schema.NullOr(Schema.Number),
+	cachedInputTokens: Schema.NullOr(Schema.Number),
+	reasoningTokens: Schema.NullOr(Schema.Number),
+}).annotate({ identifier: "AiUsage" })
+
+export type AiUsage = typeof AiUsage.Type
+
+export const AiCallSummary = Schema.Struct({
+	traceId: Schema.String,
+	spanId: Schema.String,
+	operation: Schema.String.pipe(Schema.annotateKey({ description: "AI operation: streamText, generateText, streamObject, etc." })),
+	service: Schema.String,
+	functionId: Schema.NullOr(Schema.String).pipe(Schema.annotateKey({ description: "ai.telemetry.functionId" })),
+	provider: Schema.NullOr(Schema.String).pipe(Schema.annotateKey({ description: "ai.model.provider (e.g. openai.responses)" })),
+	model: Schema.NullOr(Schema.String).pipe(Schema.annotateKey({ description: "ai.model.id (e.g. gpt-5.4)" })),
+	status: TraceSpanStatus,
+	startedAt: Schema.String.pipe(Schema.annotateKey({ description: "ISO 8601 timestamp" })),
+	durationMs: Schema.Number,
+	sessionId: Schema.NullOr(Schema.String),
+	userId: Schema.NullOr(Schema.String),
+	promptPreview: Schema.NullOr(Schema.String).pipe(Schema.annotateKey({ description: "First ~200 chars of prompt content" })),
+	responsePreview: Schema.NullOr(Schema.String).pipe(Schema.annotateKey({ description: "First ~200 chars of response text" })),
+	finishReason: Schema.NullOr(Schema.String),
+	toolCallCount: Schema.Number.pipe(Schema.annotateKey({ description: "Number of tool call child spans" })),
+	usage: Schema.NullOr(AiUsage),
+}).annotate({ identifier: "AiCallSummary" })
+
+export type AiCallSummary = typeof AiCallSummary.Type
+
+export const AiToolCall = Schema.Struct({
+	name: Schema.String,
+	spanId: Schema.NullOr(Schema.String),
+	status: TraceSpanStatus,
+	durationMs: Schema.NullOr(Schema.Number),
+}).annotate({ identifier: "AiToolCall" })
+
+export type AiToolCall = typeof AiToolCall.Type
+
+export const AiCallDetail = Schema.Struct({
+	traceId: Schema.String,
+	spanId: Schema.String,
+	operation: Schema.String,
+	service: Schema.String,
+	functionId: Schema.NullOr(Schema.String),
+	provider: Schema.NullOr(Schema.String),
+	model: Schema.NullOr(Schema.String),
+	status: TraceSpanStatus,
+	startedAt: Schema.String,
+	durationMs: Schema.Number,
+	sessionId: Schema.NullOr(Schema.String),
+	userId: Schema.NullOr(Schema.String),
+	finishReason: Schema.NullOr(Schema.String),
+	promptMessages: Schema.NullOr(Schema.Unknown).pipe(Schema.annotateKey({ description: "Full parsed ai.prompt.messages or ai.prompt" })),
+	responseText: Schema.NullOr(Schema.String).pipe(Schema.annotateKey({ description: "Full ai.response.text" })),
+	toolCalls: Schema.Array(AiToolCall),
+	toolsAvailable: Schema.NullOr(Schema.Unknown).pipe(Schema.annotateKey({ description: "Full ai.prompt.tools" })),
+	providerMetadata: Schema.NullOr(Schema.Unknown),
+	usage: Schema.NullOr(AiUsage),
+	timing: Schema.Struct({
+		msToFirstChunk: Schema.NullOr(Schema.Number),
+		msToFinish: Schema.NullOr(Schema.Number),
+		avgOutputTokensPerSecond: Schema.NullOr(Schema.Number),
+	}),
+	logs: Schema.Array(Schema.Unknown).pipe(Schema.annotateKey({ description: "Correlated log records" })),
+}).annotate({ identifier: "AiCallDetail" })
+
+export type AiCallDetail = typeof AiCallDetail.Type