@kitlangton/motel 0.1.0

package/src/locator.ts

@@ -0,0 +1,138 @@
+import { Effect, Layer, Ref, Context } from "effect"
+import { listAliveEntries, MOTEL_SERVICE_ID, type RegistryEntry } from "./registry.js"
+
+export class LocatorError extends Error {
+	readonly _tag = "LocatorError"
+	constructor(readonly detail: string) {
+		super(detail)
+	}
+}
+
+const ambiguousDetail = (candidates: readonly RegistryEntry[]) =>
+	`Multiple motel instances running and none match cwd. Set MOTEL_URL to choose one:\n` +
+	candidates.map((c) => `  - ${c.url}  (workdir=${c.workdir}, pid=${c.pid})`).join("\n")
+
+type Resolved = {
+	readonly url: string
+	readonly pid: number
+	readonly workdir: string
+	readonly version: string
+	readonly cwdMatch: boolean
+	readonly instanceCount: number
+	readonly source: "env" | "registry"
+}
+
+type HealthShape = {
+	readonly ok: boolean
+	readonly service: string
+	readonly pid: number
+	readonly url: string
+	readonly workdir: string
+	readonly version: string
+}
+
+const handshake = (url: string): Effect.Effect<HealthShape, LocatorError> =>
+	Effect.tryPromise({
+		try: async () => {
+			const res = await fetch(new URL("/api/health", url), {
+				signal: AbortSignal.timeout(1500),
+			})
+			if (!res.ok) throw new Error(`HTTP ${res.status}`)
+			const body = (await res.json()) as HealthShape
+			if (body.service !== MOTEL_SERVICE_ID) {
+				throw new Error(`service=${body.service} (expected ${MOTEL_SERVICE_ID})`)
+			}
+			return body
+		},
+		catch: (err) => new LocatorError(`Handshake with ${url} failed: ${(err as Error).message}`),
+	})
+
+const pickByCwd = (entries: readonly RegistryEntry[], cwd: string) => {
+	const withSep = cwd.endsWith("/") ? cwd : cwd + "/"
+	const matching = entries
+		.filter((e) => {
+			const workdir = e.workdir.endsWith("/") ? e.workdir : e.workdir + "/"
+			return withSep === workdir || withSep.startsWith(workdir)
+		})
+		.sort((a, b) => b.workdir.length - a.workdir.length)
+	return matching[0] ?? null
+}
+
+const discover = Effect.fn("Locator.discover")(function* () {
+	const envUrl = process.env.MOTEL_URL?.trim()
+	if (envUrl) {
+		const health = yield* handshake(envUrl)
+		return {
+			url: envUrl,
+			pid: health.pid,
+			workdir: health.workdir,
+			version: health.version,
+			cwdMatch: process.cwd().startsWith(health.workdir),
+			instanceCount: 1,
+			source: "env" as const,
+		}
+	}
+
+	const all = listAliveEntries()
+
+	if (all.length === 0) {
+		return yield* Effect.fail(
+			new LocatorError(
+				"No motel instance found. Start one with `bun run server` from your project root, then retry.",
+			),
+		)
+	}
+
+	const cwd = process.cwd()
+	const byCwd = pickByCwd(all, cwd)
+	const chosen = byCwd ?? (all.length === 1 ? all[0]! : null)
+
+	if (!chosen) {
+		return yield* Effect.fail(new LocatorError(ambiguousDetail(all)))
+	}
+
+	const health = yield* handshake(chosen.url)
+
+	if (health.pid !== chosen.pid) {
+		return yield* Effect.fail(
+			new LocatorError(
+				`Registry entry pid=${chosen.pid} but server at ${chosen.url} reports pid=${health.pid}. Stale entry — next discovery will prune it.`,
+			),
+		)
+	}
+
+	return {
+		url: chosen.url,
+		pid: health.pid,
+		workdir: health.workdir,
+		version: health.version,
+		cwdMatch: cwd.startsWith(chosen.workdir),
+		instanceCount: all.length,
+		source: "registry" as const,
+	}
+})
+
+export class Locator extends Context.Service<
+	Locator,
+	{
+		readonly resolve: Effect.Effect<Resolved, LocatorError>
+		readonly invalidate: Effect.Effect<void>
+	}
+>()("motel/Locator") {}
+
+export const LocatorLive = Layer.effect(
+	Locator,
+	Effect.gen(function* () {
+		const cache = yield* Ref.make<Resolved | null>(null)
+		return {
+			resolve: Effect.gen(function* () {
+				const cached = yield* Ref.get(cache)
+				if (cached) return cached
+				const resolved = yield* discover()
+				yield* Ref.set(cache, resolved)
+				return resolved
+			}),
+			invalidate: Ref.set(cache, null),
+		}
+	}),
+)

package/src/mcp.ts

@@ -0,0 +1,260 @@
+#!/usr/bin/env bun
+import { BunRuntime, BunStdio } from "@effect/platform-bun"
+import { Effect, Layer, Logger, Schema } from "effect"
+import { McpServer, Tool, Toolkit } from "effect/unstable/ai"
+import { TraceSpanStatus } from "./domain.js"
+import { MotelClient, MotelClientLive } from "./motelClient.js"
+import { Locator, LocatorLive } from "./locator.js"
+
+const Attributes = Schema.optional(
+	Schema.Record(Schema.String, Schema.String).annotate({
+		description:
+			"Arbitrary OTel attribute filters. Key is the attribute name WITHOUT the 'attr.' prefix (it is added for you). Values must be strings.",
+	}),
+)
+
+const Lookback = Schema.optional(
+	Schema.String.annotate({
+		description:
+			"Time window to look back, e.g. '15m', '1h', '6h', '1d'. Max 24h. Default 60m.",
+	}),
+)
+
+const Limit = Schema.optional(
+	Schema.Number.annotate({ description: "Max items to return in this page. Tool defaults apply." }),
+)
+
+const Cursor = Schema.optional(
+	Schema.String.annotate({
+		description:
+			"Opaque pagination cursor from a previous response's meta.nextCursor. Pass it back to fetch the next page.",
+	}),
+)
+
+const ServiceParam = Schema.optional(
+	Schema.String.annotate({ description: "Filter by OTel service name (e.g. 'opencode', 'my-app')." }),
+)
+
+const Status = Schema.optional(
+	TraceSpanStatus.annotate({
+		description:
+			"Filter by trace health. 'error' = at least one span errored. 'ok' = no errors.",
+	}),
+)
+
+const StatusTool = Tool.make("motel_status", {
+	description:
+		"Check which motel instance this shim is connected to. Call this FIRST if any other tool errors, to confirm the connection. Returns url, version, workdir, whether the cwd matches, and how many motel instances are running on this machine.",
+	parameters: Tool.EmptyParams,
+	success: Schema.Struct({
+		connected: Schema.Boolean,
+		url: Schema.optional(Schema.String),
+		version: Schema.optional(Schema.String),
+		workdir: Schema.optional(Schema.String),
+		cwdMatch: Schema.optional(Schema.Boolean),
+		instanceCount: Schema.optional(Schema.Number),
+		source: Schema.optional(Schema.String),
+		error: Schema.optional(Schema.String),
+	}),
+}).annotate(Tool.Readonly, true)
+
+const ServicesTool = Tool.make("motel_services", {
+	description:
+		"List every OTel service name that has emitted traces or logs recently. Use this to discover what's being observed before narrowing down with motel_search_traces or motel_search_logs.",
+	parameters: Tool.EmptyParams,
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const FacetsTool = Tool.make("motel_facets", {
+	description:
+		"Return distinct values and counts for a given field, so the agent can see what data exists before filtering. For traces, valid fields include 'service', 'operation', 'status'. For logs, 'service', 'severity', 'scope'. Supports attr.<key> fields too.",
+	parameters: Schema.Struct({
+		type: Schema.Literals(["traces", "logs"]).annotate({
+			description: "Which dataset to facet.",
+		}),
+		field: Schema.String.annotate({
+			description: "The column or attr.<key> to return distinct values for.",
+		}),
+		service: ServiceParam,
+		lookback: Lookback,
+		limit: Limit,
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const SearchTracesTool = Tool.make("motel_search_traces", {
+	description:
+		"Search distributed traces by service, operation, error status, minimum duration, time window, and arbitrary OTel attributes. Returns compact trace summaries with traceId, duration, error count, span count, and a nextCursor. Drill into a specific trace with motel_get_trace. For 'what just broke' investigations, pass status='error' with a short lookback like '15m'.",
+	parameters: Schema.Struct({
+		service: ServiceParam,
+		operation: Schema.optional(
+			Schema.String.annotate({ description: "Substring match on span operation name." }),
+		),
+		status: Status,
+		minDurationMs: Schema.optional(
+			Schema.Number.annotate({ description: "Only return traces slower than this (ms)." }),
+		),
+		attributes: Attributes,
+		lookback: Lookback,
+		limit: Limit,
+		cursor: Cursor,
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const GetTraceTool = Tool.make("motel_get_trace", {
+	description:
+		"Fetch a single trace by its 32-character hex traceId, including the full span tree ordered parent-first. Use this to drill into a trace found via motel_search_traces. For the logs emitted inside this trace, use motel_get_trace_logs instead.",
+	parameters: Schema.Struct({
+		traceId: Schema.String.annotate({ description: "Full 32-character hex trace ID." }),
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const GetTraceLogsTool = Tool.make("motel_get_trace_logs", {
+	description:
+		"Fetch log records correlated with a specific trace, across all spans. When investigating a failing trace, call this before motel_search_logs — it is the most scoped and usually the most informative log view.",
+	parameters: Schema.Struct({
+		traceId: Schema.String.annotate({ description: "Full 32-character hex trace ID." }),
+		lookback: Lookback,
+		limit: Limit,
+		cursor: Cursor,
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const SearchLogsTool = Tool.make("motel_search_logs", {
+	description:
+		"Search logs by service, trace/span correlation, body substring, time window, and arbitrary OTel attributes. Returns log entries with a nextCursor. For logs tied to a known traceId, prefer motel_get_trace_logs — it is more focused.",
+	parameters: Schema.Struct({
+		service: ServiceParam,
+		traceId: Schema.optional(
+			Schema.String.annotate({ description: "Filter by trace ID." }),
+		),
+		spanId: Schema.optional(
+			Schema.String.annotate({ description: "Filter by span ID." }),
+		),
+		body: Schema.optional(
+			Schema.String.annotate({ description: "Substring match on log body (case-sensitive)." }),
+		),
+		attributes: Attributes,
+		lookback: Lookback,
+		limit: Limit,
+		cursor: Cursor,
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const TraceStatsTool = Tool.make("motel_traces_stats", {
+	description:
+		"Aggregate statistics across traces: count, average duration, p95 duration, or error rate, grouped by a field like service, operation, status, or attr.<key>. Use this BEFORE paginating raw traces when you want to understand the shape of the data — for example 'what tools are the slowest' or 'which services are erroring'.",
+	parameters: Schema.Struct({
+		groupBy: Schema.String.annotate({
+			description: "Grouping dimension. Examples: 'service', 'operation', 'status', 'attr.tool.name'.",
+		}),
+		agg: Schema.Literals(["count", "avg_duration", "p95_duration", "error_rate"]),
+		service: ServiceParam,
+		operation: Schema.optional(Schema.String),
+		status: Status,
+		minDurationMs: Schema.optional(Schema.Number),
+		attributes: Attributes,
+		lookback: Lookback,
+		limit: Limit,
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const LogStatsTool = Tool.make("motel_logs_stats", {
+	description:
+		"Group and count logs by a field like 'severity', 'service', 'scope', or 'attr.<key>'. Useful for quickly understanding log-level distribution (e.g. how many ERROR logs there are in the last hour) before drilling into individual entries.",
+	parameters: Schema.Struct({
+		groupBy: Schema.String.annotate({
+			description: "Grouping dimension. Examples: 'service', 'severity', 'scope', 'attr.session.id'.",
+		}),
+		service: ServiceParam,
+		traceId: Schema.optional(Schema.String),
+		spanId: Schema.optional(Schema.String),
+		body: Schema.optional(Schema.String),
+		attributes: Attributes,
+		lookback: Lookback,
+		limit: Limit,
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const MotelToolkit = Toolkit.make(
+	StatusTool,
+	ServicesTool,
+	FacetsTool,
+	SearchTracesTool,
+	GetTraceTool,
+	GetTraceLogsTool,
+	SearchLogsTool,
+	TraceStatsTool,
+	LogStatsTool,
+)
+
+const asResult = <A>(effect: Effect.Effect<A, { readonly message: string }>) =>
+	Effect.match(effect, {
+		onFailure: (err) => ({ error: err.message }) as unknown,
+		onSuccess: (value) => value as unknown,
+	})
+
+const ToolHandlers = MotelToolkit.toLayer(
+	Effect.gen(function* () {
+		const client = yield* MotelClient
+		const locator = yield* Locator
+
+		return {
+			motel_status: () =>
+				Effect.match(locator.resolve, {
+					onFailure: (err) => ({
+						connected: false as const,
+						error: err instanceof Error ? err.message : String(err),
+					}),
+					onSuccess: (r) => ({
+						connected: true as const,
+						url: r.url,
+						version: r.version,
+						workdir: r.workdir,
+						cwdMatch: r.cwdMatch,
+						instanceCount: r.instanceCount,
+						source: r.source,
+					}),
+				}),
+
+			motel_services: () => asResult(client.services),
+
+			motel_facets: (input) => asResult(client.facets(input)),
+
+			motel_search_traces: (input) => asResult(client.searchTraces(input)),
+
+			motel_get_trace: ({ traceId }) => asResult(client.getTrace(traceId)),
+
+			motel_get_trace_logs: ({ traceId, lookback, limit, cursor }) =>
+				asResult(client.getTraceLogs(traceId, { lookback, limit, cursor })),
+
+			motel_search_logs: (input) => asResult(client.searchLogs(input)),
+
+			motel_traces_stats: (input) => asResult(client.traceStats(input)),
+
+			motel_logs_stats: (input) => asResult(client.logStats(input)),
+		}
+	}),
+)
+
+const ServerLayer = McpServer.toolkit(MotelToolkit).pipe(
+	Layer.provideMerge(ToolHandlers),
+	Layer.provide(MotelClientLive),
+	Layer.provide(LocatorLive),
+	Layer.provide(
+		McpServer.layerStdio({
+			name: "motel",
+			version: "0.1.0",
+		}),
+	),
+	Layer.provide(BunStdio.layer),
+	Layer.provide(Logger.layer([Logger.consolePretty({ stderr: true })])),
+)
+
+Layer.launch(ServerLayer).pipe(BunRuntime.runMain)

package/src/motel.ts

@@ -0,0 +1,86 @@
+#!/usr/bin/env bun
+
+import { Effect } from "effect"
+import { applyManagedDaemonEnv, ensureManagedDaemon, getManagedDaemonStatus, stopManagedDaemon } from "./daemon.js"
+
+const [command, ...args] = process.argv.slice(2)
+
+const run = <A>(effect: Effect.Effect<A, Error>) => Effect.runPromise(effect)
+
+switch (command) {
+case undefined:
+case "tui":
+case "ui": {
+	await run(applyManagedDaemonEnv)
+	await run(ensureManagedDaemon)
+	await import("./index.js")
+	break
+}
+
+case "daemon":
+case "start": {
+	const status = await run(ensureManagedDaemon)
+	console.log(JSON.stringify(status, null, 2))
+	break
+}
+
+case "status": {
+	const status = await run(getManagedDaemonStatus)
+	console.log(JSON.stringify(status, null, 2))
+	break
+}
+
+case "stop": {
+	const status = await run(stopManagedDaemon)
+	console.log(JSON.stringify(status, null, 2))
+	break
+}
+
+case "server": {
+	await run(applyManagedDaemonEnv)
+	await import("./server.js")
+	break
+}
+
+case "mcp": {
+	await import("./mcp.js")
+	break
+}
+
+case "help":
+case "--help":
+case "-h": {
+	console.log(`Usage:
+	motel
+	motel tui
+	motel daemon
+	motel status
+	motel stop
+	motel server
+	motel mcp
+	motel services
+	motel traces [service] [limit]
+	motel trace <trace-id>
+	motel span <span-id>
+	motel trace-spans <trace-id>
+	motel search-spans [service] [operation] [parent=<operation>] [attr.key=value ...]
+	motel search-traces [service] [operation] [attr.key=value ...]
+	motel trace-stats <groupBy> <agg> [service] [attr.key=value ...]
+	motel logs [service]
+	motel search-logs [service] [body] [attr.key=value ...]
+	motel log-stats <groupBy> [service] [attr.key=value ...]
+	motel trace-logs <trace-id>
+	motel span-logs <span-id>
+	motel facets <traces|logs> <field>
+	motel instructions
+	motel endpoints`)
+	break
+}
+
+default: {
+	await run(applyManagedDaemonEnv)
+	process.argv = [process.argv[0]!, process.argv[1]!, command, ...args]
+	await import("./cli.js")
+	break
+}
+}

package/src/motelClient.ts

@@ -0,0 +1,201 @@
+import { Effect, Layer, Context } from "effect"
+import { Locator } from "./locator.js"
+
+export class MotelHttpError extends Error {
+	readonly _tag = "MotelHttpError"
+	constructor(
+		readonly status: number,
+		readonly detail: string,
+	) {
+		super(`motel returned HTTP ${status}: ${detail}`)
+	}
+}
+
+type QueryValue = string | number | boolean | null | undefined
+type Query = Readonly<Record<string, QueryValue>>
+
+const appendQuery = (url: URL, query: Query | undefined) => {
+	if (!query) return url
+	for (const [key, value] of Object.entries(query)) {
+		if (value === undefined || value === null || value === "") continue
+		url.searchParams.set(key, String(value))
+	}
+	return url
+}
+
+const appendAttributes = (url: URL, attributes: Readonly<Record<string, string>> | undefined) => {
+	if (!attributes) return url
+	for (const [key, value] of Object.entries(attributes)) {
+		url.searchParams.set(`attr.${key}`, value)
+	}
+	return url
+}
+
+export type SearchTracesInput = {
+	readonly service?: string
+	readonly operation?: string
+	readonly status?: "ok" | "error"
+	readonly minDurationMs?: number
+	readonly lookback?: string
+	readonly limit?: number
+	readonly cursor?: string
+	readonly attributes?: Readonly<Record<string, string>>
+}
+
+export type SearchLogsInput = {
+	readonly service?: string
+	readonly traceId?: string
+	readonly spanId?: string
+	readonly body?: string
+	readonly lookback?: string
+	readonly limit?: number
+	readonly cursor?: string
+	readonly attributes?: Readonly<Record<string, string>>
+}
+
+export type TraceStatsInput = {
+	readonly groupBy: string
+	readonly agg: "count" | "avg_duration" | "p95_duration" | "error_rate"
+	readonly service?: string
+	readonly operation?: string
+	readonly status?: "ok" | "error"
+	readonly minDurationMs?: number
+	readonly lookback?: string
+	readonly limit?: number
+	readonly attributes?: Readonly<Record<string, string>>
+}
+
+export type LogStatsInput = {
+	readonly groupBy: string
+	readonly service?: string
+	readonly traceId?: string
+	readonly spanId?: string
+	readonly body?: string
+	readonly lookback?: string
+	readonly limit?: number
+	readonly attributes?: Readonly<Record<string, string>>
+}
+
+export type FacetsInput = {
+	readonly type: "traces" | "logs"
+	readonly field: string
+	readonly service?: string
+	readonly lookback?: string
+	readonly limit?: number
+}
+
+export class MotelClient extends Context.Service<
+	MotelClient,
+	{
+		readonly searchTraces: (input: SearchTracesInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly getTrace: (traceId: string) => Effect.Effect<unknown, MotelHttpError>
+		readonly getTraceLogs: (
+			traceId: string,
+			options: { readonly lookback?: string; readonly limit?: number; readonly cursor?: string },
+		) => Effect.Effect<unknown, MotelHttpError>
+		readonly searchLogs: (input: SearchLogsInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly traceStats: (input: TraceStatsInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly logStats: (input: LogStatsInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly facets: (input: FacetsInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly services: Effect.Effect<unknown, MotelHttpError>
+		readonly health: Effect.Effect<unknown, MotelHttpError>
+	}
+>()("motel/MotelClient") {}
+
+export const MotelClientLive = Layer.effect(
+	MotelClient,
+	Effect.gen(function* () {
+		const locator = yield* Locator
+
+		const get = <A = unknown>(path: string, query?: Query, attributes?: Readonly<Record<string, string>>) =>
+			Effect.gen(function* () {
+				const { url } = yield* Effect.mapError(
+					locator.resolve,
+					(err) => new MotelHttpError(0, err.message),
+				)
+				const target = appendAttributes(appendQuery(new URL(path, url), query), attributes)
+				return yield* Effect.tryPromise({
+					try: async () => {
+						const res = await fetch(target, { signal: AbortSignal.timeout(5000) })
+						const body = (await res.json().catch(() => ({ error: "invalid json" }))) as A
+						if (!res.ok) throw new MotelHttpError(res.status, JSON.stringify(body))
+						return body
+					},
+					catch: (err) =>
+						err instanceof MotelHttpError ? err : new MotelHttpError(0, (err as Error).message),
+				}).pipe(
+					Effect.tapError((err) => (err.status === 0 ? locator.invalidate : Effect.void)),
+				)
+			})
+
+		return {
+			searchTraces: (input) =>
+				get("/api/traces/search", {
+					service: input.service,
+					operation: input.operation,
+					status: input.status,
+					minDurationMs: input.minDurationMs,
+					lookback: input.lookback,
+					limit: input.limit,
+					cursor: input.cursor,
+				}, input.attributes),
+
+			getTrace: (traceId) => get(`/api/traces/${encodeURIComponent(traceId)}`),
+
+			getTraceLogs: (traceId, options) =>
+				get(`/api/traces/${encodeURIComponent(traceId)}/logs`, {
+					lookback: options.lookback,
+					limit: options.limit,
+					cursor: options.cursor,
+				}),
+
+			searchLogs: (input) =>
+				get("/api/logs/search", {
+					service: input.service,
+					traceId: input.traceId,
+					spanId: input.spanId,
+					body: input.body,
+					lookback: input.lookback,
+					limit: input.limit,
+					cursor: input.cursor,
+				}, input.attributes),
+
+			traceStats: (input) =>
+				get("/api/traces/stats", {
+					groupBy: input.groupBy,
+					agg: input.agg,
+					service: input.service,
+					operation: input.operation,
+					status: input.status,
+					minDurationMs: input.minDurationMs,
+					lookback: input.lookback,
+					limit: input.limit,
+				}, input.attributes),
+
+			logStats: (input) =>
+				get("/api/logs/stats", {
+					groupBy: input.groupBy,
+					agg: "count",
+					service: input.service,
+					traceId: input.traceId,
+					spanId: input.spanId,
+					body: input.body,
+					lookback: input.lookback,
+					limit: input.limit,
+				}, input.attributes),
+
+			facets: (input) =>
+				get("/api/facets", {
+					type: input.type,
+					field: input.field,
+					service: input.service,
+					lookback: input.lookback,
+					limit: input.limit,
+				}),
+
+			services: get("/api/services"),
+
+			health: get("/api/health"),
+		}
+	}),
+)