repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/autopsy/inspector.ts
Rawimport { 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<object>();
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<string, unknown> = 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<string>();
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<InspectorData> {
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<InspectorMetricEvent> {
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<void>((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<InspectorData>,
getEntry: (id: string) => unknown = () => undefined,
getMetrics?: (
query: InspectorQuery,
signal: AbortSignal,
) => AsyncIterable<InspectorMetricEvent>,
getPrompts?: () => PromptSnapshot[] | Promise<PromptSnapshot[]>,
): Promise<{ url: string; close: () => Promise<void> }> {
const token = randomBytes(32).toString("hex");
const sockets = new Set<Socket>();
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<string, [string, string]> = {
"": ["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<void>((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<void> | undefined;
return {
url: `http://127.0.0.1:${port}/${token}/`,
close: () => {
closing ??= new Promise<void>((resolve, reject) => {
server.close((error) => (error ? reject(error) : resolve()));
for (const socket of sockets) socket.destroy();
});
return closing;
},
};
}