import { randomBytes } from "node:crypto"; import { readFile } from "node:fs/promises"; import { createServer } from "node:http"; import type { Socket } from "node:net"; import { Readable } from "node:stream"; import { pipeline } from "node:stream/promises"; import { entryDetailEvents } from "./details.ts"; import type { HistoryContext, PriceLookup } from "./history.ts"; import { InspectorQueryError, scanHistory, validateQuery } from "./history.ts"; import { sessionImage } from "./images.ts"; import { metricsOf } from "./metrics.ts"; export type { CatalogPrices, InspectorMetricEvent, InspectorQuery, } from "./src/types.ts"; import type { InspectorData, InspectorEntry, InspectorMetricEvent, InspectorQuery, PromptSnapshot, } from "./src/types.ts"; const TEXT_LIMIT = 2 * 1024; const DATA_LIMIT = 32 * 1024 * 1024; function bounded(value: string): [string, boolean] { const bytes = Buffer.from(value); if (bytes.length <= TEXT_LIMIT) return [value, false]; return [ `${bytes.subarray(0, TEXT_LIMIT - 64).toString("utf8")}\n[truncated]`, true, ]; } function serialize(value: unknown, state = { truncated: false }): string { const seen = new WeakSet(); let remaining = TEXT_LIMIT; let nodes = 256; const text = (value: string): string => { const count = Math.min(remaining, value.length); remaining -= count; if (count < value.length) state.truncated = true; return count < value.length ? `${value.slice(0, count)}[truncated]` : value; }; const copy = (item: unknown, depth: number): unknown => { if (--nodes < 0 || remaining <= 0 || depth > 32) { state.truncated = true; return "[truncated]"; } if (typeof item === "string") return text(item); if (typeof item === "bigint") return text(item.toString()); if (!item || typeof item !== "object") return item; if (seen.has(item)) { state.truncated = true; return "[circular or repeated reference]"; } seen.add(item); if (Array.isArray(item)) { const out: unknown[] = []; for (let i = 0; i < item.length; i++) { if (nodes <= 0 || remaining <= 0 || i === 2_000) { state.truncated = true; out.push("[truncated]"); break; } const descriptor = Object.getOwnPropertyDescriptor(item, String(i)); if (descriptor && !("value" in descriptor)) state.truncated = true; out.push( copy( descriptor && "value" in descriptor ? descriptor.value : null, depth + 1, ), ); } return out; } const out: Record = Object.create(null); for (const key in item) { if (!Object.hasOwn(item, key)) continue; if (nodes <= 0 || remaining <= 0) { state.truncated = true; out["[truncated]"] = true; break; } if (key.length > 512) state.truncated = true; const boundedKey = text( key.slice(0, 512) + (key.length > 512 ? "[truncated]" : ""), ); if (key === "data" && "type" in item && item.type === "image") out[boundedKey] = "[image data: available on demand]"; else { const descriptor = Object.getOwnPropertyDescriptor(item, key); if (descriptor && !("value" in descriptor)) state.truncated = true; out[boundedKey] = copy( descriptor && "value" in descriptor ? descriptor.value : "[unsupported accessor]", depth + 1, ); } } return out; }; // Only the bounded copy is enumerated by JSON.stringify. return JSON.stringify(copy(value, 0), null, 2) ?? "null"; } async function preview( entry: unknown, signal?: AbortSignal, ): Promise<{ text: string; truncated: boolean }> { let text = ""; let events = 0; for await (const event of entryDetailEvents(entry, "text")) { if (++events > 256) return { text, truncated: true }; signal?.throwIfAborted(); if (event.type === "error") return { text, truncated: true }; if (event.type !== "text") continue; const remaining = TEXT_LIMIT - Buffer.byteLength(text); if (Buffer.byteLength(event.text) > remaining) { return { text: text + Buffer.from(event.text) .subarray(0, Math.max(0, remaining - 3)) .toString("utf8"), truncated: true, }; } text += event.text; } return { text, truncated: false }; } function toolNames(entry: unknown): { names: string[]; truncated: boolean } { const source = entry as { message?: { toolName?: unknown; content?: unknown }; }; const message = source.message; const names = new Set(); let truncated = false; const add = (value: unknown) => { if (typeof value !== "string") return; if (value.length > 256) truncated = true; names.add(value.slice(0, 256)); }; add(message?.toolName); if (Array.isArray(message?.content)) { const content = message.content; if (content.length > 256) truncated = true; for (let index = 0; index < Math.min(content.length, 256); index++) { const descriptor = Object.getOwnPropertyDescriptor( content, String(index), ); const part = descriptor && "value" in descriptor ? descriptor.value : undefined; if (part && (part.type === "toolCall" || part.type === "tool_call")) add(part.name); } } return { names: [...names], truncated }; } export async function buildInspectorData( ctx: HistoryContext, _prompts: PromptSnapshot[], warnings: string[] = [], getPrices?: PriceLookup, query: InspectorQuery = {}, signal?: AbortSignal, ): Promise { const scope = await scanHistory(ctx, query, getPrices, signal); const entries: InspectorEntry[] = []; const budget = { text: 4 * 1024 * 1024, images: 4 * 1024 * 1024, visits: 100_000, }; for (const { source, metadata } of scope.selected.slice( scope.start, scope.end, )) { signal?.throwIfAborted(); const measured = metricsOf(source, budget); const state = { truncated: false }; const [raw, rawTruncated] = bounded(serialize(source, state)); const text = await preview(source, signal); const tools = toolNames(source); entries.push({ ...metadata, ...measured, text: text.text, raw, toolNames: tools.names, previewTruncated: state.truncated || rawTruncated || text.truncated || tools.truncated, }); } signal?.throwIfAborted(); return { sessionId: scope.sessionId, name: scope.name, cwd: ctx.cwd, leafId: scope.leafId, generatedAt: new Date().toISOString(), entries, revision: scope.revision, page: scope.page, summary: scope.summary, facets: scope.facets, prompts: [], warnings: [...warnings], }; } export async function* streamInspectorMetrics( ctx: HistoryContext, getPrices?: PriceLookup, query: InspectorQuery = {}, signal?: AbortSignal, ): AsyncGenerator { try { const scope = await scanHistory(ctx, query, getPrices, signal); const budget = { text: 4 * 1024 * 1024, images: 4 * 1024 * 1024, visits: 100_000, }; let count = 0; for (const { source, metadata } of scope.selected) { if (count++ % 32 === 0) await new Promise((resolve) => setImmediate(resolve)); signal?.throwIfAborted(); const measured = metricsOf(source, budget); yield { type: "entry", entry: { ...metadata, metrics: measured.metrics, toolNames: toolNames(source).names, }, }; } signal?.throwIfAborted(); yield { type: "end" }; } catch (error) { signal?.throwIfAborted(); if (error instanceof InspectorQueryError && error.status !== 422) throw error; yield { type: "error", message: error instanceof InspectorQueryError ? error.message : "Could not measure complete matching history", }; } } function requestQuery(url: string): InspectorQuery { const params = new URL(url, "http://127.0.0.1").searchParams; const query = Object.fromEntries(params) as InspectorQuery; if (params.has("limit")) query.limit = Number(params.get("limit")); validateQuery(query); return query; } export async function startInspector( getData: ( query: InspectorQuery, signal: AbortSignal, ) => InspectorData | Promise, getEntry: (id: string) => unknown = () => undefined, getMetrics?: ( query: InspectorQuery, signal: AbortSignal, ) => AsyncIterable, getPrompts?: () => PromptSnapshot[] | Promise, ): Promise<{ url: string; close: () => Promise }> { const token = randomBytes(32).toString("hex"); const sockets = new Set(); let port = 0; const server = createServer(async (req, res) => { res.setHeader("Cache-Control", "no-store"); res.setHeader("Referrer-Policy", "no-referrer"); res.setHeader( "Content-Security-Policy", "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'", ); res.setHeader("X-Content-Type-Options", "nosniff"); const reject = (status: number, message: string) => { res.writeHead(status, { "Content-Type": "text/plain; charset=utf-8" }); res.end(message); }; if ( req.headers.host !== `127.0.0.1:${port}` || (req.headers.origin !== undefined && req.headers.origin !== `http://127.0.0.1:${port}`) ) return reject(403, "Forbidden"); if (req.method !== "GET") return reject(405, "Method not allowed"); const path = req.url?.split("?", 1)[0]; const prefix = `/${token}/`; if (!path?.startsWith(prefix)) return reject(404, "Not found"); const route = path.slice(prefix.length); const controller = new AbortController(); res.on("close", () => { if (!res.writableFinished) controller.abort(); }); try { const imageRoute = /^image\/([a-zA-Z0-9_-]{1,128})\/([0-9]{1,16})$/u.exec( route, ); if (imageRoute?.[1]) { const result = sessionImage( getEntry(imageRoute[1]), Number(imageRoute[2]), ); res.writeHead(result.status, { "Content-Type": result.contentType }); return res.end(result.body); } const detailRoute = /^entry\/([a-zA-Z0-9_-]{1,128})\/(text|json)$/u.exec( route, ); if ( detailRoute?.[1] && (detailRoute[2] === "text" || detailRoute[2] === "json") ) { const entry = getEntry(detailRoute[1]); if (entry == null) return reject(404, "Not found"); res.writeHead(200, { "Content-Type": "application/x-ndjson; charset=utf-8", }); const events = entryDetailEvents(entry, detailRoute[2]); async function* lines() { for await (const event of events) yield `${JSON.stringify(event)}\n`; } await pipeline(Readable.from(lines()), res, { signal: controller.signal, }); return; } if (route === "metrics") { const query = requestQuery(req.url ?? ""); if (!getMetrics) return reject(404, "Metrics unavailable"); const events = getMetrics(query, controller.signal)[ Symbol.asyncIterator ](); const first = await events.next(); res.writeHead(200, { "Content-Type": "application/x-ndjson; charset=utf-8", }); async function* lines() { try { let next = first; while (!next.done) { controller.signal.throwIfAborted(); yield `${JSON.stringify(next.value)}\n`; next = await events.next(); } } catch { controller.signal.throwIfAborted(); yield `${JSON.stringify({ type: "error", message: "Inspector metrics failed" })}\n`; } finally { await events.return?.(); } } await pipeline(Readable.from(lines()), res, { signal: controller.signal, }); return; } if (route === "prompts") { const json = JSON.stringify((await getPrompts?.()) ?? []); if (Buffer.byteLength(json) > DATA_LIMIT) return reject(413, "Inspector prompts exceed 32 MiB"); res.writeHead(200, { "Content-Type": "application/json; charset=utf-8", }); return res.end(json); } if (route === "data") { const json = JSON.stringify( await getData(requestQuery(req.url ?? ""), controller.signal), ); if (Buffer.byteLength(json) > DATA_LIMIT) return reject(413, "Inspector data exceeds 32 MiB"); res.writeHead(200, { "Content-Type": "application/json; charset=utf-8", }); return res.end(json); } const assets: Record = { "": ["index.html", "text/html"], "app.js": ["app.js", "text/javascript"], "app.css": ["app.css", "text/css"], "nugu.css": ["nugu.css", "text/css"], }; if (!Object.hasOwn(assets, route)) return reject(404, "Not found"); const asset = assets[route]; if (!asset) return reject(404, "Not found"); const [file, type] = asset; const body = await readFile(new URL(`./site/${file}`, import.meta.url)); res.writeHead(200, { "Content-Type": `${type}; charset=utf-8` }); res.end(body); } catch (error) { if (controller.signal.aborted) return; if (!res.headersSent) reject( error instanceof InspectorQueryError ? error.status : 500, error instanceof InspectorQueryError ? error.message : "Inspector request failed", ); else res.destroy(); } }); server.requestTimeout = 10_000; server.headersTimeout = 10_000; // Full-history scans and backpressured metrics may legitimately exceed 10 seconds. server.timeout = 0; server.on("connection", (socket) => { sockets.add(socket); socket.on("close", () => sockets.delete(socket)); }); await new Promise((resolve, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", () => { server.off("error", reject); resolve(); }); }); const address = server.address(); if (!address || typeof address === "string") { server.close(); throw new Error("Inspector could not bind"); } port = address.port; server.unref(); let closing: Promise | undefined; return { url: `http://127.0.0.1:${port}/${token}/`, close: () => { closing ??= new Promise((resolve, reject) => { server.close((error) => (error ? reject(error) : resolve())); for (const socket of sockets) socket.destroy(); }); return closing; }, }; }