@kitlangton/motel 0.2.0 → 0.2.4

package/src/localServer.ts

@@ -1,18 +1,27 @@
 import { promises as fs } from "node:fs"
 import path from "node:path"
-import { Effect, Layer, Context } from "effect"
-import { config, parsePositiveInt, resolveOtelUrl } from "./config.js"
+import { Effect, Layer } from "effect"
+import { config, parsePositiveInt } from "./config.js"
 import { HttpApiBuilder, HttpApiScalar } from "effect/unstable/httpapi"
+import * as HttpMiddleware from "effect/unstable/http/HttpMiddleware"
 import * as HttpRouter from "effect/unstable/http/HttpRouter"
-import * as HttpServer from "effect/unstable/http/HttpServer"
 import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse"
+import * as HttpStaticServer from "effect/unstable/http/HttpStaticServer"
+import * as BunHttpServer from "@effect/platform-bun/BunHttpServer"
 import { MotelHttpApi } from "./httpApi.js"
-import { attributeFiltersFromEntries, attributeContainsFiltersFromEntries, ATTRIBUTE_FILTER_PREFIX, ATTRIBUTE_CONTAINS_PREFIX } from "./queryFilters.js"
-import { MOTEL_SERVICE_ID, MOTEL_VERSION, writeRegistryEntry } from "./registry.js"
+import { attributeFiltersFromEntries, attributeContainsFiltersFromEntries } from "./queryFilters.js"
+import { MOTEL_SERVICE_ID, MOTEL_VERSION, removeRegistryEntry, writeRegistryEntry } from "./registry.js"
+import { AsyncIngest, AsyncIngestLive } from "./services/AsyncIngest.js"
 import { TelemetryStore, TelemetryStoreLive } from "./services/TelemetryStore.js"
 import type { LogItem, TraceItem, TraceSummaryItem } from "./domain.js"
 import { lifecycleLabel } from "./ui/format.js"
 
+// Set by the RegistryLayer acquisition once the Bun socket has bound.
+// Both /api/health and the registry entry read from here so they agree
+// on a single server-start timestamp, and the value reflects actual
+// listen time rather than module-evaluation time.
+let serverStartedAt: string = new Date(0).toISOString()
+
 const TRACE_DEFAULT_LIMIT = 20
 const TRACE_MAX_LIMIT = 100
 const TRACE_DEFAULT_LOOKBACK = 60
@@ -24,28 +33,21 @@ const LOG_MAX_LIMIT = 500
 const LOG_DEFAULT_LOOKBACK = 60
 const LOG_MAX_LOOKBACK = 24 * 60
 
-let server: ReturnType<typeof Bun.serve> | null = null
-let disposeWebHandler: (() => Promise<void>) | null = null
-let startedAt: string | null = null
-
-const resolveBoundUrl = () => {
-	if (!server) return config.otel.queryUrl
-	const host = server.hostname === "0.0.0.0" || server.hostname === "::" ? "127.0.0.1" : server.hostname
-	return `http://${host}:${server.port}`
-}
-
 const jsonResponse = (value: unknown, status = 200) => HttpServerResponse.jsonUnsafe(value, { status })
 const textResponse = (value: string) => HttpServerResponse.text(value)
 const htmlResponse = (value: string) => HttpServerResponse.html(value)
 const notFoundResponse = (message = "Not found") => jsonResponse({ error: message }, 404)
 const requestUrl = (request: { readonly url: string }) => new URL(request.url, config.otel.baseUrl)
 const withStore = <A>(f: (store: TelemetryStore["Service"]) => Effect.Effect<A, Error>) => Effect.flatMap(TelemetryStore.asEffect(), f)
-const respondJson = <A>(effect: Effect.Effect<A, unknown, TelemetryStore>) =>
+// Response-building helpers are generic in R so a handler can depend
+// on TelemetryStore (query path) or AsyncIngest (worker-RPC path)
+// without forcing every handler onto the same service surface.
+const respondJson = <A, R>(effect: Effect.Effect<A, unknown, R>) =>
 	Effect.match(effect, {
 		onFailure: (error) => jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 500),
 		onSuccess: (value) => jsonResponse(value),
 	})
-const respondRaw = (effect: Effect.Effect<ReturnType<typeof jsonResponse>, unknown, TelemetryStore>) =>
+const respondRaw = <R>(effect: Effect.Effect<ReturnType<typeof jsonResponse>, unknown, R>) =>
 	Effect.match(effect, {
 		onFailure: (error) => jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 500),
 		onSuccess: (value) => value,
@@ -70,14 +72,10 @@ const parseLookbackMinutes = (value: string | null, fallback: number) => {
 const parseBoundedLookbackMinutes = (value: string | null, fallback: number, max: number) => clamp(parseLookbackMinutes(value, fallback), 1, max)
 
 const attributeFiltersFromQuery = (url: URL) =>
-	attributeFiltersFromEntries(
-		[...url.searchParams.entries()].filter(([key]) => key.startsWith(ATTRIBUTE_FILTER_PREFIX) && !key.startsWith(ATTRIBUTE_CONTAINS_PREFIX)),
-	)
+	attributeFiltersFromEntries(url.searchParams.entries())
 
 const attributeContainsFiltersFromQuery = (url: URL) =>
-	attributeContainsFiltersFromEntries(
-		[...url.searchParams.entries()].filter(([key]) => key.startsWith(ATTRIBUTE_CONTAINS_PREFIX)),
-	)
+	attributeContainsFiltersFromEntries(url.searchParams.entries())
 
 type CursorShape =
 	| { readonly kind: "trace"; readonly startedAt: number; readonly id: string }
@@ -284,23 +282,33 @@ const TelemetryGroupLive = HttpApiBuilder.group(
 					service: MOTEL_SERVICE_ID,
 					databasePath: config.otel.databasePath,
 					pid: process.pid,
-					url: resolveBoundUrl(),
+					url: config.otel.baseUrl,
 					workdir: process.cwd(),
-					startedAt: startedAt ?? new Date(0).toISOString(),
+					startedAt: serverStartedAt,
 					version: MOTEL_VERSION,
 				}),
 			)
+			// OTLP ingest is routed to the worker thread via AsyncIngest
+			// so the main event loop stays free during heavy SQLite writes.
+			// Everything else still uses the direct TelemetryStore — reads
+			// are fast enough that IPC overhead isn't worth paying.
 			.handleRaw("ingestTraces", ({ request }) =>
 				respondRaw(
 					Effect.flatMap(request.json, (payload) =>
-						Effect.map(withStore((store) => store.ingestTraces(payload as any)), (result) => jsonResponse(result)),
+						Effect.map(
+							Effect.flatMap(AsyncIngest.asEffect(), (ingest) => ingest.ingestTraces({ payload })),
+							(result) => jsonResponse(result),
+						),
 					),
 				),
 			)
 			.handleRaw("ingestLogs", ({ request }) =>
 				respondRaw(
 					Effect.flatMap(request.json, (payload) =>
-						Effect.map(withStore((store) => store.ingestLogs(payload as any)), (result) => jsonResponse(result)),
+						Effect.map(
+							Effect.flatMap(AsyncIngest.asEffect(), (ingest) => ingest.ingestLogs({ payload })),
+							(result) => jsonResponse(result),
+						),
 					),
 				),
 			)
@@ -587,115 +595,93 @@ const TelemetryGroupLive = HttpApiBuilder.group(
 			),
 )
 
-const ApiLive = Layer.provideMerge(
-	HttpApiBuilder.layer(MotelHttpApi, { openapiPath: "/openapi.json" }).pipe(
-		Layer.provide(TelemetryGroupLive),
-		Layer.provide(HttpApiScalar.layer(MotelHttpApi, { scalar: { forceDarkModeState: "dark", showOperationId: true } })),
-		Layer.provide(HttpServer.layerServices),
-	),
-	TelemetryStoreLive,
-)
-
 // ---------------------------------------------------------------------------
-// Static file serving for the web UI
+// App layer: HTTP router + static SPA + telemetry store
 // ---------------------------------------------------------------------------
 
-const WEB_DIST_DIR = path.resolve(import.meta.dir, "../web/dist")
-// Only cache `true` — a `false` result is rechecked so a later `web:build` is picked up
-let webUiAvailable = false
-
-const isWebUiAvailable = async (): Promise<boolean> => {
-	if (webUiAvailable) return true
-	try {
-		webUiAvailable = await Bun.file(path.join(WEB_DIST_DIR, "index.html")).exists()
-	} catch {
-		/* ignore */
-	}
-	return webUiAvailable
-}
-
-/** Routes that must always go through the Effect API handler */
-const isStrictApiRoute = (pathname: string) =>
-	pathname.startsWith("/api/") ||
-	pathname.startsWith("/v1/") ||
-	pathname === "/openapi.json" ||
-	pathname === "/docs"
-
-const serveWebUi = async (request: Request, apiHandler: (req: Request) => Promise<Response>): Promise<Response> => {
-	const url = new URL(request.url)
-	const pathname = url.pathname
-
-	// Strict API routes always go through the Effect handler
-	if (isStrictApiRoute(pathname)) return apiHandler(request)
-
-	// Only serve web UI if built
-	if (!(await isWebUiAvailable())) return apiHandler(request)
+// API routes come from the Effect HttpApi definition. Everything under
+// /api/*, /v1/*, /openapi.json, /docs is handled here.
+const ApiLayer = HttpApiBuilder.layer(MotelHttpApi, { openapiPath: "/openapi.json" }).pipe(
+	Layer.provide(TelemetryGroupLive),
+	Layer.provide(HttpApiScalar.layer(MotelHttpApi, { scalar: { forceDarkModeState: "dark", showOperationId: true } })),
+)
 
-	// Try to serve a static file from web/dist/ (hashed assets, favicon, etc.)
-	if (pathname.startsWith("/assets/") || (pathname !== "/" && pathname.includes("."))) {
-		const resolved = path.resolve(WEB_DIST_DIR, pathname.slice(1))
-		if (resolved.startsWith(WEB_DIST_DIR) && await Bun.file(resolved).exists()) {
-			return new Response(Bun.file(resolved))
-		}
-	}
+// Web UI: Vite-built SPA served from web/dist. HttpStaticServer.layer
+// handles GET /*, filesystem lookup under `root`, and SPA fallback to
+// index.html for unknown paths — replacing the hand-rolled serveWebUi
+// wrapper that previously lived inline with Bun.serve. The API routes
+// above take precedence because HttpApi registers specific paths that
+// the router matches before falling through to the /* catch-all.
+const WEB_DIST_DIR = path.resolve(import.meta.dir, "../web/dist")
+const StaticLayer = HttpStaticServer.layer({
+	root: WEB_DIST_DIR,
+	spa: true,
+})
 
-	// SPA fallback: serve index.html for / and all client routes
-	return new Response(Bun.file(path.join(WEB_DIST_DIR, "index.html")), {
-		headers: { "content-type": "text/html; charset=utf-8" },
-	})
-}
+// Registry-entry writer as a scoped acquisition. The entry is published
+// after BunHttpServer.layer binds the socket (scope acquisition order)
+// and removed on scope release, so a bind failure never leaves a zombie
+// entry and a graceful shutdown cleans up alongside the server stop —
+// both in the same finalizer chain managed by Layer.launch.
+const RegistryLayer = Layer.effectDiscard(
+	Effect.acquireRelease(
+		Effect.sync(() => {
+			serverStartedAt = new Date().toISOString()
+			try {
+				writeRegistryEntry({
+					pid: process.pid,
+					url: config.otel.baseUrl,
+					workdir: process.cwd(),
+					startedAt: serverStartedAt,
+					version: MOTEL_VERSION,
+					databasePath: config.otel.databasePath,
+				})
+			} catch (err) {
+				console.warn(`motel: failed to write registry entry: ${(err as Error).message}`)
+			}
+		}),
+		() => Effect.sync(() => removeRegistryEntry(process.pid)),
+	),
+)
 
 // ---------------------------------------------------------------------------
 // Server lifecycle
 // ---------------------------------------------------------------------------
 
-export const startLocalServer = async () => {
-	if (server) return server
-	const { handler, dispose } = HttpRouter.toWebHandler(ApiLive, { disableLogger: true })
-	disposeWebHandler = dispose
-	server = Bun.serve({
-		hostname: config.otel.host,
+/**
+ * Launchable server layer. Composes the API + static UI + store + registry,
+ * wraps the whole stack in HttpMiddleware.tracer (per-request OTel spans
+ * with http.method / url / status / user-agent attributes), and binds the
+ * socket via @effect/platform-bun's BunHttpServer. Use from server.ts:
+ *
+ *   await Effect.runPromise(Layer.launch(ServerLive))
+ *
+ * Socket lifecycle, graceful shutdown, and error propagation are managed
+ * by the BunHttpServer layer's Scope — no hand-rolled start/stop plumbing.
+ * `reusePort: true` is retained as defense-in-depth against TIME_WAIT
+ * rebind conflicts (the registry-based adoption path in daemon.ts is the
+ * primary protection, but this covers a raw `bun src/server.ts` restart).
+ */
+export const ServerLive = HttpRouter.serve(
+	Layer.mergeAll(ApiLayer, StaticLayer, RegistryLayer),
+	{ middleware: HttpMiddleware.tracer },
+).pipe(
+	// OTLP ingest paths are NOT traced by the middleware, otherwise
+	// MOTEL_OTEL_ENABLED creates a feedback loop: every outbound span
+	// POSTs to /v1/traces, the tracer emits a span for that POST, which
+	// POSTs again on the next flush. This also shaves ~1 KB of header
+	// attributes off every ingest request that would have been written
+	// to the spans table as noise.
+	Layer.provide(HttpMiddleware.layerTracerDisabledForUrls(["/v1/traces", "/v1/logs"])),
+	// AsyncIngest spawns the telemetry worker — keeps the main-thread
+	// event loop free during heavy SQLite writes. Provided alongside
+	// the direct TelemetryStore so query handlers can still resolve
+	// their dependency directly.
+	Layer.provideMerge(AsyncIngestLive),
+	Layer.provideMerge(TelemetryStoreLive),
+	Layer.provideMerge(BunHttpServer.layer({
 		port: config.otel.port,
-		fetch(request) {
-			return serveWebUi(request, handler)
-		},
-	})
-	startedAt = new Date().toISOString()
-	try {
-		writeRegistryEntry({
-			pid: process.pid,
-			url: resolveBoundUrl(),
-			workdir: process.cwd(),
-			startedAt,
-			version: MOTEL_VERSION,
-		})
-	} catch (err) {
-		console.warn(`motel: failed to write registry entry: ${(err as Error).message}`)
-	}
-	return server
-}
-
-export const ensureLocalServer = async () => {
-	if (server) return server
-	try {
-		const response = await fetch(resolveOtelUrl("/api/health"), { signal: AbortSignal.timeout(250) })
-		if (response.ok) return null
-	} catch {
-		// Start local server below.
-	}
-	return await startLocalServer()
-}
-
-export const stopLocalServer = () => {
-	server?.stop(true)
-	server = null
-	startedAt = null
-
-	const dispose = disposeWebHandler
-	disposeWebHandler = null
-	if (dispose) {
-		void dispose().catch((err) => {
-			console.warn(`motel: failed to dispose web handler: ${(err as Error).message}`)
-		})
-	}
-}
+		hostname: config.otel.host,
+		reusePort: true,
+	})),
+)

package/src/mcp.ts

@@ -13,6 +13,13 @@ const Attributes = Schema.optional(
 	}),
 )
 
+const AttributeContains = Schema.optional(
+	Schema.Record(Schema.String, Schema.String).annotate({
+		description:
+			"Case-insensitive substring attribute filters. Key is the attribute name WITHOUT the 'attrContains.' prefix (it is added for you). Values must be strings.",
+	}),
+)
+
 const Lookback = Schema.optional(
 	Schema.String.annotate({
 		description:
@@ -42,6 +49,12 @@ const Status = Schema.optional(
 	}),
 )
 
+const Severity = Schema.optional(
+	Schema.String.annotate({
+		description: "Filter by log severity, e.g. TRACE, DEBUG, INFO, WARN, ERROR, FATAL.",
+	}),
+)
+
 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.",
@@ -123,11 +136,65 @@ const GetTraceLogsTool = Tool.make("motel_get_trace_logs", {
 	success: Schema.Unknown,
 }).annotate(Tool.Readonly, true)
 
+const GetTraceSpansTool = Tool.make("motel_get_trace_spans", {
+	description:
+		"Fetch the flat span list for a specific trace. Use this when you already know the traceId and want to inspect span durations, status, parents, and raw attributes without the nested trace wrapper.",
+	parameters: Schema.Struct({
+		traceId: Schema.String.annotate({ description: "Full 32-character hex trace ID." }),
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const SearchSpansTool = Tool.make("motel_search_spans", {
+	description:
+		"Search spans directly by service, traceId, operation, parentOperation, status, time window, and raw OTel attributes. Use this when traces are too coarse and you need to find the exact span or suspicious operation first.",
+	parameters: Schema.Struct({
+		service: ServiceParam,
+		traceId: Schema.optional(
+			Schema.String.annotate({ description: "Scope search to a single trace ID." }),
+		),
+		operation: Schema.optional(
+			Schema.String.annotate({ description: "Substring match on span operation name." }),
+		),
+		parentOperation: Schema.optional(
+			Schema.String.annotate({ description: "Substring match on parent operation name." }),
+		),
+		status: Status,
+		attributes: Attributes,
+		attributeContains: AttributeContains,
+		lookback: Lookback,
+		limit: Limit,
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const GetSpanTool = Tool.make("motel_get_span", {
+	description:
+		"Fetch a single span by its 16-character hex spanId. Use this after motel_search_spans to inspect one span's full payload, parent trace, raw tags, and events.",
+	parameters: Schema.Struct({
+		spanId: Schema.String.annotate({ description: "Full 16-character hex span ID." }),
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const GetSpanLogsTool = Tool.make("motel_get_span_logs", {
+	description:
+		"Fetch log records correlated with a specific span. Use this after motel_get_span when you need the exact logs emitted from that one span, not the entire trace.",
+	parameters: Schema.Struct({
+		spanId: Schema.String.annotate({ description: "Full 16-character hex span 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,
+		severity: Severity,
 		traceId: Schema.optional(
 			Schema.String.annotate({ description: "Filter by trace ID." }),
 		),
@@ -138,6 +205,7 @@ const SearchLogsTool = Tool.make("motel_search_logs", {
 			Schema.String.annotate({ description: "Substring match on log body (case-sensitive)." }),
 		),
 		attributes: Attributes,
+		attributeContains: AttributeContains,
 		lookback: Lookback,
 		limit: Limit,
 		cursor: Cursor,
@@ -145,6 +213,79 @@ const SearchLogsTool = Tool.make("motel_search_logs", {
 	success: Schema.Unknown,
 }).annotate(Tool.Readonly, true)
 
+const SearchAiCallsTool = Tool.make("motel_search_ai_calls", {
+	description:
+		"Search normalized AI calls such as streamText and generateText by session, provider, model, functionId, operation, duration, status, or free-text prompt/response content. Use this for LLM-specific investigations rather than raw span search.",
+	parameters: Schema.Struct({
+		service: ServiceParam,
+		traceId: Schema.optional(Schema.String.annotate({ description: "Filter by trace ID." })),
+		sessionId: Schema.optional(Schema.String.annotate({ description: "Filter by normalized AI sessionId." })),
+		functionId: Schema.optional(Schema.String.annotate({ description: "Filter by AI functionId, e.g. session.llm." })),
+		provider: Schema.optional(Schema.String.annotate({ description: "Filter by provider, e.g. openai.responses." })),
+		model: Schema.optional(Schema.String.annotate({ description: "Filter by model ID." })),
+		operation: Schema.optional(Schema.String.annotate({ description: "Filter by normalized AI operation, e.g. streamText." })),
+		status: Status,
+		minDurationMs: Schema.optional(Schema.Number.annotate({ description: "Only return AI calls slower than this (ms)." })),
+		text: Schema.optional(Schema.String.annotate({ description: "Case-insensitive substring match across prompt, response, and tool content." })),
+		lookback: Lookback,
+		limit: Limit,
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const GetAiCallTool = Tool.make("motel_get_ai_call", {
+	description:
+		"Fetch the full detail for one AI call by spanId, including complete prompt messages, response payloads, tool calls, token usage, provider metadata, and correlated logs.",
+	parameters: Schema.Struct({
+		spanId: Schema.String.annotate({ description: "The span ID of the AI call." }),
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const AiStatsTool = Tool.make("motel_ai_stats", {
+	description:
+		"Aggregate AI call statistics grouped by provider, model, functionId, sessionId, or status. Use this before paging raw AI calls when you want to understand which models are slowest or which functions consume the most tokens.",
+	parameters: Schema.Struct({
+		groupBy: Schema.Literals(["provider", "model", "functionId", "sessionId", "status"]),
+		agg: Schema.Literals(["count", "avg_duration", "p95_duration", "total_input_tokens", "total_output_tokens"]),
+		service: ServiceParam,
+		traceId: Schema.optional(Schema.String),
+		sessionId: Schema.optional(Schema.String),
+		functionId: Schema.optional(Schema.String),
+		provider: Schema.optional(Schema.String),
+		model: Schema.optional(Schema.String),
+		operation: Schema.optional(Schema.String),
+		status: Status,
+		minDurationMs: Schema.optional(Schema.Number),
+		lookback: Lookback,
+		limit: Limit,
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const DocsIndexTool = Tool.make("motel_docs_index", {
+	description:
+		"List the documentation pages bundled with motel, such as the debug workflow and Effect guide. Use this before motel_get_doc if you are unsure which docs are available.",
+	parameters: Tool.EmptyParams,
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const GetDocTool = Tool.make("motel_get_doc", {
+	description:
+		"Fetch a bundled motel documentation page as markdown text. Useful for giving an agent the exact debug workflow or Effect instrumentation guidance without leaving MCP.",
+	parameters: Schema.Struct({
+		name: Schema.String.annotate({ description: "Document name, e.g. 'debug' or 'effect'." }),
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const OpenApiTool = Tool.make("motel_openapi", {
+	description:
+		"Fetch motel's OpenAPI JSON document. Use this when you need the authoritative HTTP API surface or want to compare MCP coverage against the server routes.",
+	parameters: Tool.EmptyParams,
+	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'.",
@@ -189,9 +330,19 @@ const MotelToolkit = Toolkit.make(
 	SearchTracesTool,
 	GetTraceTool,
 	GetTraceLogsTool,
+	GetTraceSpansTool,
+	SearchSpansTool,
+	GetSpanTool,
+	GetSpanLogsTool,
 	SearchLogsTool,
+	SearchAiCallsTool,
+	GetAiCallTool,
+	AiStatsTool,
 	TraceStatsTool,
 	LogStatsTool,
+	DocsIndexTool,
+	GetDocTool,
+	OpenApiTool,
 )
 
 const asResult = <A>(effect: Effect.Effect<A, { readonly message: string }>) =>
@@ -234,11 +385,32 @@ const ToolHandlers = MotelToolkit.toLayer(
 			motel_get_trace_logs: ({ traceId, lookback, limit, cursor }) =>
 				asResult(client.getTraceLogs(traceId, { lookback, limit, cursor })),
 
+			motel_get_trace_spans: ({ traceId }) => asResult(client.getTraceSpans(traceId)),
+
+			motel_search_spans: (input) => asResult(client.searchSpans(input)),
+
+			motel_get_span: ({ spanId }) => asResult(client.getSpan(spanId)),
+
+			motel_get_span_logs: ({ spanId, lookback, limit, cursor }) =>
+				asResult(client.getSpanLogs(spanId, { lookback, limit, cursor })),
+
 			motel_search_logs: (input) => asResult(client.searchLogs(input)),
 
+			motel_search_ai_calls: (input) => asResult(client.searchAiCalls(input)),
+
+			motel_get_ai_call: ({ spanId }) => asResult(client.getAiCall(spanId)),
+
+			motel_ai_stats: (input) => asResult(client.aiCallStats(input)),
+
 			motel_traces_stats: (input) => asResult(client.traceStats(input)),
 
 			motel_logs_stats: (input) => asResult(client.logStats(input)),
+
+			motel_docs_index: () => asResult(client.docs),
+
+			motel_get_doc: ({ name }) => asResult(Effect.map(client.getDoc(name), (data) => ({ data }))),
+
+			motel_openapi: () => asResult(client.openapi),
 		}
 	}),
 )