@kitlangton/motel 0.2.0 → 0.2.4

package/src/daemon.ts

@@ -2,17 +2,27 @@ 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"
+import { isAlive, listAliveEntries, MOTEL_SERVICE_ID, MOTEL_VERSION, type RegistryEntry } 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 START_TIMEOUT_MS = 30_000
 const STOP_TIMEOUT_MS = 10_000
 const LOCK_TIMEOUT_MS = 10_000
 const POLL_INTERVAL_MS = 150
+/** Fast probe used inside the waitForHealthy poll loop — we call it
+ *  every POLL_INTERVAL_MS, so a generous budget would stall the loop. */
+const HEALTH_FAST_TIMEOUT_MS = 750
+/** Patient probe used on critical paths: the first getStatus() call
+ *  in ensure(), and the final pre-throw check after a spawned child
+ *  dies. A real daemon with a busy SQLite writer (FTS backfill, big
+ *  DB) can easily take 1-2s to answer /api/health — if we declare
+ *  the port empty at 750ms we'll spawn a duplicate and collide with
+ *  EADDRINUSE. 3s is long enough to tolerate a slow healthy daemon
+ *  and short enough that a truly-down daemon is still detected
+ *  before START_TIMEOUT_MS fires. */
+const HEALTH_PATIENT_TIMEOUT_MS = 3_000
 
 type HealthShape = {
 	readonly ok: boolean
@@ -32,6 +42,8 @@ type LockShape = {
 
 type DaemonConfig = {
 	readonly repoRoot: string
+	readonly serverEntry: string
+	readonly workdir: string
 	readonly runtimeDir: string
 	readonly databasePath: string
 	readonly logPath: string
@@ -67,6 +79,7 @@ export type DaemonManager = {
 
 type DaemonOptions = {
 	readonly repoRoot?: string
+	readonly workdir?: string
 	readonly runtimeDir?: string
 	readonly databasePath?: string
 	readonly host?: string
@@ -84,12 +97,15 @@ 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 workdir = path.resolve(options.workdir ?? process.cwd())
+	const runtimeDir = path.resolve(options.runtimeDir ?? path.join(workdir, ".motel-data"))
 	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,
+		serverEntry: path.join(repoRoot, "src/server.ts"),
+		workdir,
 		runtimeDir,
 		databasePath,
 		logPath: path.join(runtimeDir, "daemon.log"),
@@ -100,16 +116,14 @@ const resolveConfig = (options: DaemonOptions = {}): DaemonConfig => {
 	}
 }
 
-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 workdirMatches = (targetWorkdir: string, daemonWorkdir: string) => {
+	const normalizedTarget = targetWorkdir.endsWith(path.sep) ? targetWorkdir : `${targetWorkdir}${path.sep}`
+	const normalizedDaemon = daemonWorkdir.endsWith(path.sep) ? daemonWorkdir : `${daemonWorkdir}${path.sep}`
+	return normalizedTarget === normalizedDaemon || normalizedTarget.startsWith(normalizedDaemon)
 }
 
-const pickByCwd = (entries: readonly RegistryEntry[]) => {
-	const cwd = process.cwd()
-	const withSep = cwd.endsWith(path.sep) ? cwd : `${cwd}${path.sep}`
+const pickByWorkdir = (entries: readonly RegistryEntry[], targetWorkdir: string) => {
+	const withSep = targetWorkdir.endsWith(path.sep) ? targetWorkdir : `${targetWorkdir}${path.sep}`
 	return entries
 		.filter((entry) => {
 			const workdir = entry.workdir.endsWith(path.sep) ? entry.workdir : `${entry.workdir}${path.sep}`
@@ -118,8 +132,6 @@ const pickByCwd = (entries: readonly RegistryEntry[]) => {
 		.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,
@@ -133,10 +145,11 @@ const expectedEnv = (config: DaemonConfig) => ({
 export const createDaemonManager = (options: DaemonOptions = {}): DaemonManager => {
 	const config = resolveConfig(options)
 	const mapError = (error: unknown) => new DaemonError(error instanceof Error ? error.message : String(error))
+	const readRegistryEntry = () => pickByWorkdir(listAliveEntries(), config.workdir)
 
-	const fetchHealth = async (): Promise<HealthShape | null> => {
+	const fetchHealth = async (timeoutMs: number = HEALTH_FAST_TIMEOUT_MS): Promise<HealthShape | null> => {
 		try {
-			const response = await fetch(`${config.baseUrl}/api/health`, { signal: AbortSignal.timeout(750) })
+			const response = await fetch(`${config.baseUrl}/api/health`, { signal: AbortSignal.timeout(timeoutMs) })
 			if (!response.ok) return null
 			return await response.json() as HealthShape
 		} catch {
@@ -144,12 +157,39 @@ export const createDaemonManager = (options: DaemonOptions = {}): DaemonManager
 		}
 	}
 
+	const startupMarkers = [`Listening on ${config.baseUrl}`, `motel local telemetry server listening on ${config.baseUrl}`]
+
+	const readLogSince = async (offset: number) => {
+		try {
+			const raw = await fsp.readFile(config.logPath, "utf8")
+			return raw.slice(offset)
+		} catch {
+			return ""
+		}
+	}
+
+	const detectStartedFromLog = async (pid: number, offset: number): Promise<HealthShape | null> => {
+		if (!isAlive(pid)) return null
+		const tail = await readLogSince(offset)
+		if (!startupMarkers.some((marker) => tail.includes(marker))) return null
+		return {
+			ok: true,
+			service: MOTEL_SERVICE_ID,
+			databasePath: config.databasePath,
+			pid,
+			url: config.baseUrl,
+			workdir: config.workdir,
+			startedAt: new Date().toISOString(),
+			version: MOTEL_VERSION,
+		}
+	}
+
 	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 (!workdirMatches(config.workdir, health.workdir)) {
+			return `Port ${config.port} is serving motel for ${health.workdir}, not ${config.workdir}.`
 		}
 		if (health.databasePath !== config.databasePath) {
 			return `Port ${config.port} is serving motel with ${health.databasePath}, expected ${config.databasePath}.`
@@ -157,6 +197,62 @@ export const createDaemonManager = (options: DaemonOptions = {}): DaemonManager
 		return null
 	}
 
+	/**
+	 * Mismatch check against a registry entry — mirrors describeManagedMismatch
+	 * but drives off the registry file instead of an HTTP health response.
+	 * Used on the fast path in getStatus so warm-start doesn't need to wait
+	 * on an HTTP round-trip that may queue behind heavy OTLP ingest.
+	 *
+	 * The service-id check is implicit: any entry living in the motel
+	 * registry dir is by construction a motel daemon. databasePath is
+	 * optional for back-compat with entries written by older builds;
+	 * when absent we skip the DB check rather than refusing to adopt.
+	 */
+	const describeRegistryMismatch = (entry: RegistryEntry): string | null => {
+		if (!workdirMatches(config.workdir, entry.workdir)) {
+			return `Port ${config.port} is serving motel for ${entry.workdir}, not ${config.workdir}.`
+		}
+		if (entry.databasePath && entry.databasePath !== config.databasePath) {
+			return `Port ${config.port} is serving motel with ${entry.databasePath}, expected ${config.databasePath}.`
+		}
+		return null
+	}
+
+	/**
+	 * Build a DaemonStatus from a live registry entry. Returns null when
+	 * there's no entry for our cwd, the registered pid isn't running, or
+	 * the entry is for a differently-configured daemon (different port).
+	 * This is the fast path: no HTTP, no event-loop round-trip, just a
+	 * directory read and a process.kill(pid, 0) liveness probe.
+	 */
+	const getStatusFromRegistry = (): DaemonStatus | null => {
+		const entry = readRegistryEntry()
+		if (!entry) return null
+		// Port discriminator: a motel registry shared across several
+		// daemons (e.g., user running two instances on different
+		// ports from the same workdir, or a test harness on a random
+		// port) would otherwise have us adopt an unrelated daemon.
+		// URL match is a fast, unambiguous identity check.
+		if (entry.url !== config.baseUrl) return null
+		const mismatch = describeRegistryMismatch(entry)
+		return {
+			running: mismatch === null,
+			managed: mismatch === null,
+			service: MOTEL_SERVICE_ID,
+			pid: entry.pid,
+			url: entry.url,
+			databasePath: entry.databasePath ?? config.databasePath,
+			workdir: entry.workdir,
+			startedAt: entry.startedAt,
+			version: entry.version,
+			sameWorkdir: workdirMatches(config.workdir, entry.workdir),
+			reason: mismatch,
+			logPath: config.logPath,
+			lockPath: config.lockPath,
+			registryPid: entry.pid,
+		}
+	}
+
 	const readLock = async (): Promise<LockShape | null> => {
 		try {
 			const raw = await fsp.readFile(config.lockPath, "utf8")
@@ -208,7 +304,7 @@ export const createDaemonManager = (options: DaemonOptions = {}): DaemonManager
 		return fs.openSync(config.logPath, "a")
 	}
 
-	const waitForHealthy = async (pid: number) => {
+	const waitForHealthy = async (pid: number, logOffset: number) => {
 		const deadline = Date.now() + START_TIMEOUT_MS
 		while (Date.now() < deadline) {
 			const health = await fetchHealth()
@@ -217,7 +313,20 @@ export const createDaemonManager = (options: DaemonOptions = {}): DaemonManager
 				if (!mismatch) return health
 				throw new Error(mismatch)
 			}
+			const started = await detectStartedFromLog(pid, logOffset)
+			if (started) return started
 			if (!isAlive(pid)) {
+				// The spawned child is gone. Before declaring failure,
+				// do one patient probe: the child may have died from
+				// EADDRINUSE because another healthy motel is alive on
+				// the port but was answering /api/health too slowly for
+				// our fast poll. If that's the case, adopt it.
+				const patient = await fetchHealth(HEALTH_PATIENT_TIMEOUT_MS)
+				if (patient) {
+					const mismatch = describeManagedMismatch(patient)
+					if (!mismatch) return patient
+					throw new Error(mismatch)
+				}
 				throw new Error(`Daemon process ${pid} exited before becoming healthy. See ${config.logPath}.`)
 			}
 			await sleep(POLL_INTERVAL_MS)
@@ -237,16 +346,33 @@ export const createDaemonManager = (options: DaemonOptions = {}): DaemonManager
 		while (Date.now() < deadline) {
 			if (!isAlive(pid)) return
 			const health = await fetchHealth()
-			if (!health || health.pid !== pid) return
+			if (health && health.pid !== pid) return
+			const registry = readRegistryEntry()
+			if (!health && (!registry || registry.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 getStatus = async (timeoutMs: number = HEALTH_FAST_TIMEOUT_MS): Promise<DaemonStatus> => {
+		// Fast path: trust the local filesystem registry. When a motel
+		// daemon started on this machine it wrote an entry for its pid
+		// + cwd + databasePath; if that entry is still there and the pid
+		// is alive, the daemon is almost certainly the one we want to
+		// adopt. HTTP health is skipped because the daemon's health
+		// endpoint can queue behind heavy OTLP ingest traffic, making
+		// the probe unreliable exactly when the daemon is busy.
+		const registryStatus = getStatusFromRegistry()
+		if (registryStatus) return registryStatus
+
+		// No local evidence → fall back to HTTP. Covers the edge cases
+		// where: a motel daemon is running but was started before this
+		// registry-first path shipped; OR the port is held by something
+		// entirely unrelated (the mismatch check turns that into a
+		// human-readable reason).
 		const registry = readRegistryEntry()
-		const health = await fetchHealth()
+		const health = await fetchHealth(timeoutMs)
 		if (!health) {
 			return {
 				running: false,
@@ -258,7 +384,7 @@ export const createDaemonManager = (options: DaemonOptions = {}): DaemonManager
 				workdir: registry?.workdir ?? null,
 				startedAt: registry?.startedAt ?? null,
 				version: registry?.version ?? null,
-				sameWorkdir: registry ? cwdMatches(registry.workdir) : false,
+				sameWorkdir: registry ? workdirMatches(config.workdir, registry.workdir) : false,
 				reason: registry ? "Registry entry exists but daemon is not healthy." : null,
 				logPath: config.logPath,
 				lockPath: config.lockPath,
@@ -277,7 +403,7 @@ export const createDaemonManager = (options: DaemonOptions = {}): DaemonManager
 			workdir: health.workdir,
 			startedAt: health.startedAt,
 			version: health.version,
-			sameWorkdir: cwdMatches(health.workdir),
+			sameWorkdir: workdirMatches(config.workdir, health.workdir),
 			reason: mismatch,
 			logPath: config.logPath,
 			lockPath: config.lockPath,
@@ -286,7 +412,11 @@ export const createDaemonManager = (options: DaemonOptions = {}): DaemonManager
 	}
 
 	const ensure = async (): Promise<DaemonStatus> => {
-		const existing = await getStatus()
+		// Use the patient timeout for the initial probe — this is the
+		// critical "is there already a daemon here?" check. A false
+		// negative here drops us into the spawn path and collides with
+		// any slow-but-healthy daemon sitting on the port.
+		const existing = await getStatus(HEALTH_PATIENT_TIMEOUT_MS)
 		if (existing.managed && existing.running) return existing
 		if (existing.service !== null && existing.reason) {
 			throw new Error(existing.reason)
@@ -295,17 +425,22 @@ export const createDaemonManager = (options: DaemonOptions = {}): DaemonManager
 		const lock = await acquireStartupLock()
 		let spawnedPid: number | null = null
 		try {
-			const rechecked = await getStatus()
+			// Same reasoning for the post-lock re-check: another ensure()
+			// may have spawned a daemon between our first probe and the
+			// lock grant, and its initial health response can be slow
+			// while the runtime warms up.
+			const rechecked = await getStatus(HEALTH_PATIENT_TIMEOUT_MS)
 			if (rechecked.managed && rechecked.running) return rechecked
 			if (rechecked.service !== null && rechecked.reason) {
 				throw new Error(rechecked.reason)
 			}
 
 			const logFd = await openLogFile()
+			const logOffset = fs.fstatSync(logFd).size
 			try {
 				const proc = Bun.spawn({
-					cmd: [process.execPath, "run", "src/server.ts"],
-					cwd: config.repoRoot,
+					cmd: [process.execPath, "run", config.serverEntry],
+					cwd: config.workdir,
 					detached: true,
 					env: {
 						...process.env,
@@ -323,7 +458,7 @@ export const createDaemonManager = (options: DaemonOptions = {}): DaemonManager
 				throw new Error("Daemon failed to spawn.")
 			}
 
-			const health = await waitForHealthy(spawnedPid)
+			const health = await waitForHealthy(spawnedPid, logOffset)
 			return {
 				running: true,
 				managed: true,
@@ -334,7 +469,7 @@ export const createDaemonManager = (options: DaemonOptions = {}): DaemonManager
 				workdir: health.workdir,
 				startedAt: health.startedAt,
 				version: health.version,
-				sameWorkdir: cwdMatches(health.workdir),
+				sameWorkdir: workdirMatches(config.workdir, health.workdir),
 				reason: null,
 				logPath: config.logPath,
 				lockPath: config.lockPath,
@@ -371,7 +506,10 @@ export const createDaemonManager = (options: DaemonOptions = {}): DaemonManager
 		}),
 		getStatus: Effect.fn("DaemonManager.getStatus")(() =>
 			Effect.tryPromise({
-				try: getStatus,
+				// Wrapped so Effect.tryPromise only sees the no-arg call
+				// signature — the optional timeoutMs parameter is an
+				// internal detail used by ensure()'s critical probes.
+				try: () => getStatus(),
 				catch: mapError,
 			}),
 		)(),
@@ -390,9 +528,7 @@ export const createDaemonManager = (options: DaemonOptions = {}): DaemonManager
 	}
 }
 
-const defaultManager = createDaemonManager()
-
-export const applyManagedDaemonEnv = defaultManager.applyEnv
-export const getManagedDaemonStatus = defaultManager.getStatus
-export const ensureManagedDaemon = defaultManager.ensure
-export const stopManagedDaemon = defaultManager.stop
+export const applyManagedDaemonEnv = Effect.suspend(() => createDaemonManager().applyEnv)
+export const getManagedDaemonStatus = Effect.suspend(() => createDaemonManager().getStatus)
+export const ensureManagedDaemon = Effect.suspend(() => createDaemonManager().ensure)
+export const stopManagedDaemon = Effect.suspend(() => createDaemonManager().stop)

package/src/domain.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test"
+import { AI_FTS_KEYS, isAiSpan } from "./domain.ts"
+
+describe("isAiSpan", () => {
+	test("returns false for empty tags", () => {
+		expect(isAiSpan({})).toBe(false)
+	})
+
+	test("returns false when no AI key is present", () => {
+		expect(isAiSpan({
+			"service.name": "web",
+			"http.method": "GET",
+			"db.statement": "SELECT 1",
+		})).toBe(false)
+	})
+
+	test("detects Vercel AI SDK keys", () => {
+		expect(isAiSpan({ "ai.prompt.messages": "[]" })).toBe(true)
+		expect(isAiSpan({ "ai.response.text": "hi" })).toBe(true)
+		expect(isAiSpan({ "ai.toolCall.args": "{}" })).toBe(true)
+	})
+
+	test("detects OpenTelemetry gen_ai semconv keys", () => {
+		expect(isAiSpan({ "gen_ai.prompt": "foo" })).toBe(true)
+		expect(isAiSpan({ "gen_ai.input.messages": "[]" })).toBe(true)
+		expect(isAiSpan({ "gen_ai.tool.definitions": "[]" })).toBe(true)
+	})
+
+	test("detects OpenInference keys", () => {
+		expect(isAiSpan({ "input.value": "hi" })).toBe(true)
+		expect(isAiSpan({ "output.value": "hi" })).toBe(true)
+	})
+
+	test("detects a single AI key among many non-AI keys", () => {
+		expect(isAiSpan({
+			"service.name": "web",
+			"http.method": "POST",
+			"http.status_code": "200",
+			"ai.model.id": "ignored-not-in-fts-keys",
+			"ai.prompt": "tell me a joke",
+		})).toBe(true)
+	})
+
+	test("ignores AI-adjacent keys that are not in the FTS set", () => {
+		// `ai.model.provider`, `ai.settings.*`, `ai.telemetry.*` carry
+		// metadata, not content, so they intentionally aren't part of
+		// AI_FTS_KEYS. A span with ONLY those should not be flagged.
+		expect(isAiSpan({
+			"ai.model.provider": "openai",
+			"ai.model.id": "gpt-4",
+			"ai.settings.maxRetries": "2",
+		})).toBe(false)
+	})
+
+	test("every documented key triggers detection", () => {
+		// Guard against a future reshuffle of AI_FTS_KEYS that might
+		// drop a key silently — every declared key should round-trip.
+		for (const key of AI_FTS_KEYS) {
+			expect(isAiSpan({ [key]: "payload" })).toBe(true)
+		}
+	})
+})

package/src/domain.ts

@@ -195,6 +195,22 @@ export const AI_FTS_KEYS = [
  */
 export const AI_TEXT_SEARCH_KEYS = AI_FTS_KEYS
 
+/**
+ * True if a span's tags contain any of the AI content keys we track.
+ * Used as the single source of truth for "this span has LLM payloads
+ * worth a specialized view" — drives the ✦ marker in the waterfall row
+ * and picks the chat-flavored renderer when the user drills into the
+ * span's detail. Scanning happens once per row during render so this
+ * needs to stay O(AI_FTS_KEYS.length) with cheap `in` checks rather
+ * than an `Object.keys(...).some(...)` allocation.
+ */
+export const isAiSpan = (tags: Readonly<Record<string, string>>): boolean => {
+	for (const key of AI_FTS_KEYS) {
+		if (key in tags) return true
+	}
+	return false
+}
+
 const PREVIEW_LENGTH = 200
 
 export const truncatePreview = (value: string | null | undefined): string | null => {