@tonyclaw/agent-inspector 4.0.1 → 4.0.3

package/src/lib/safeFetch.ts

@@ -1,508 +0,0 @@
-import { lookup } from "node:dns/promises";
-import { request as requestHttp } from "node:http";
-import { request as requestHttps } from "node:https";
-import { isIP } from "node:net";
-import type { IncomingMessage, RequestOptions } from "node:http";
-import { evaluateUpstreamUrl, isInternalHost, type SsrfGuardOptions } from "./ssrfGuard";
-
-export type ResolvedAddress = {
-  address: string;
-  family: number;
-};
-
-export type HostResolver = (hostname: string) => Promise<readonly ResolvedAddress[]>;
-
-export type SafeFetchOptions = SsrfGuardOptions & {
-  resolver?: HostResolver;
-  deadlineMs?: number;
-  responseBytes?: number;
-  pinDns?: boolean;
-};
-
-export type SafeFetchResult =
-  | { ok: true; response: Response }
-  | {
-      ok: false;
-      kind: "network-policy" | "redirect" | "resource-limit" | "timeout";
-      reason: string;
-    };
-
-async function defaultResolver(hostname: string): Promise<readonly ResolvedAddress[]> {
-  return lookup(hostname, { all: true, verbatim: true });
-}
-
-function isLoopbackAddress(hostname: string): boolean {
-  const lower = hostname.toLowerCase();
-  return (
-    lower === "::1" ||
-    lower.startsWith("::ffff:127.") ||
-    lower.startsWith("::ffff:7f00:") ||
-    /^127\./.test(lower)
-  );
-}
-
-export async function evaluateResolvedUpstreamUrl(
-  rawUrl: string,
-  options: SafeFetchOptions = {},
-): Promise<{ allow: true } | { allow: false; reason: string }> {
-  const decision = await evaluateResolvedUpstreamUrlForFetch(rawUrl, options);
-  return decision.allow ? { allow: true } : { allow: false, reason: decision.reason };
-}
-
-type ResolvedUpstreamUrlDecision =
-  | { allow: true; hostname: string; addresses: readonly ResolvedAddress[] }
-  | { allow: false; reason: string };
-
-async function evaluateResolvedUpstreamUrlForFetch(
-  rawUrl: string,
-  options: SafeFetchOptions,
-): Promise<ResolvedUpstreamUrlDecision> {
-  const initial = evaluateUpstreamUrl(rawUrl, options);
-  if (!initial.allow) return initial;
-
-  const parsed = new URL(rawUrl);
-  const hostname = parsed.hostname.replace(/^\[|]$/g, "");
-  if (options.bypass === true) return { allow: true, hostname, addresses: [] };
-
-  const ipFamily = isIP(hostname);
-  if (ipFamily !== 0)
-    return { allow: true, hostname, addresses: [{ address: hostname, family: ipFamily }] };
-
-  let addresses: readonly ResolvedAddress[];
-  try {
-    addresses = await (options.resolver ?? defaultResolver)(hostname);
-  } catch (error) {
-    return {
-      allow: false,
-      reason: `Could not safely resolve upstream host "${hostname}": ${String(error)}`,
-    };
-  }
-
-  if (addresses.length === 0) {
-    return { allow: false, reason: `Upstream host "${hostname}" resolved to no addresses` };
-  }
-
-  for (const resolved of addresses) {
-    if (!isInternalHost(resolved.address)) continue;
-    if (options.allowLoopback === true && isLoopbackAddress(resolved.address)) continue;
-    return {
-      allow: false,
-      reason: `Refusing upstream host "${hostname}" because it resolves to internal address "${resolved.address}"`,
-    };
-  }
-
-  return { allow: true, hostname, addresses };
-}
-
-function isRedirectStatus(status: number): boolean {
-  return status >= 300 && status < 400;
-}
-
-function formatByteLimit(limit: number): string {
-  return `${String(limit)} bytes`;
-}
-
-function parseContentLength(value: string | null): number | null {
-  if (value === null) return null;
-  const parsed = Number(value);
-  if (!Number.isSafeInteger(parsed) || parsed < 0) return null;
-  return parsed;
-}
-
-function isPinnedDnsEnabled(options: SafeFetchOptions): boolean {
-  const disabledForTest =
-    typeof process !== "undefined" &&
-    process.env["NODE_ENV"] === "test" &&
-    process.env["AGENT_INSPECTOR_DISABLE_DNS_PINNING_FOR_TESTS"] === "1";
-  if (disabledForTest) return false;
-  return options.pinDns !== false && options.bypass !== true;
-}
-
-function choosePinnedAddress(addresses: readonly ResolvedAddress[]): ResolvedAddress | null {
-  return addresses[0] ?? null;
-}
-
-function hostHeaderValue(parsed: URL): string {
-  return parsed.port.length === 0 ? parsed.host : `${parsed.hostname}:${parsed.port}`;
-}
-
-function headersToRecord(headers: HeadersInit | undefined, parsed: URL): Record<string, string> {
-  const normalized = new Headers(headers);
-  if (!normalized.has("host")) {
-    normalized.set("host", hostHeaderValue(parsed));
-  }
-  const result: Record<string, string> = {};
-  normalized.forEach((value, key) => {
-    result[key] = value;
-  });
-  return result;
-}
-
-async function requestBodyToUint8Array(
-  body: BodyInit | null | undefined,
-): Promise<
-  { ok: true; body: Uint8Array | null; contentType: string | null } | { ok: false; reason: string }
-> {
-  if (body === undefined || body === null) return { ok: true, body: null, contentType: null };
-  if (typeof body === "string") {
-    return { ok: true, body: new TextEncoder().encode(body), contentType: null };
-  }
-  if (body instanceof URLSearchParams) {
-    return {
-      ok: true,
-      body: new TextEncoder().encode(body.toString()),
-      contentType: "application/x-www-form-urlencoded;charset=UTF-8",
-    };
-  }
-  if (body instanceof Uint8Array) return { ok: true, body, contentType: null };
-  if (body instanceof ArrayBuffer) {
-    return { ok: true, body: new Uint8Array(body), contentType: null };
-  }
-  if (body instanceof Blob) {
-    return { ok: true, body: new Uint8Array(await body.arrayBuffer()), contentType: body.type };
-  }
-  return {
-    ok: false,
-    reason: "Pinned upstream fetch only supports buffered request bodies",
-  };
-}
-
-function pinnedLookup(
-  pinnedAddress: ResolvedAddress,
-): (
-  hostname: string,
-  options: { all?: boolean },
-  callback: (error: Error | null, address: string | ResolvedAddress[], family?: number) => void,
-) => void {
-  return (_hostname, options, callback) => {
-    if (options.all === true) {
-      callback(null, [pinnedAddress]);
-      return;
-    }
-    callback(null, pinnedAddress.address, pinnedAddress.family);
-  };
-}
-
-function requestOptionsForPinnedFetch(
-  parsed: URL,
-  init: RequestInit,
-  pinnedAddress: ResolvedAddress,
-  contentType: string | null,
-): RequestOptions {
-  const headers = headersToRecord(init.headers, parsed);
-  if (contentType !== null && !new Headers(headers).has("content-type")) {
-    headers["content-type"] = contentType;
-  }
-
-  return {
-    protocol: parsed.protocol,
-    hostname: parsed.hostname,
-    port: parsed.port,
-    path: `${parsed.pathname}${parsed.search}`,
-    method: init.method ?? "GET",
-    headers,
-    lookup: pinnedLookup(pinnedAddress),
-  };
-}
-
-function streamFromIncomingMessage(
-  incoming: IncomingMessage,
-  maxBytes: number | undefined,
-): ReadableStream<Uint8Array> {
-  let seenBytes = 0;
-  return new ReadableStream<Uint8Array>({
-    start(controller) {
-      incoming.on("data", (chunk: Uint8Array) => {
-        seenBytes += chunk.byteLength;
-        if (maxBytes !== undefined && seenBytes > maxBytes) {
-          incoming.destroy(
-            new Error(
-              `Upstream response exceeded configured limit of ${formatByteLimit(maxBytes)}`,
-            ),
-          );
-          controller.error(
-            new Error(
-              `Upstream response exceeded configured limit of ${formatByteLimit(maxBytes)}`,
-            ),
-          );
-          return;
-        }
-        controller.enqueue(chunk);
-      });
-      incoming.on("end", () => {
-        controller.close();
-      });
-      incoming.on("error", (error) => {
-        controller.error(error);
-      });
-    },
-    cancel() {
-      incoming.destroy();
-    },
-  });
-}
-
-async function cancelBody(response: Response): Promise<void> {
-  if (response.body === null) return;
-  await response.body.cancel().catch(() => undefined);
-}
-
-function responseWithByteLimit(response: Response, maxBytes: number): Response {
-  if (response.body === null) return response;
-
-  let seenBytes = 0;
-  const reader = response.body.getReader();
-  const body = new ReadableStream<Uint8Array>({
-    async pull(controller) {
-      const chunk = await reader.read();
-      if (chunk.done) {
-        controller.close();
-        return;
-      }
-
-      seenBytes += chunk.value.byteLength;
-      if (seenBytes > maxBytes) {
-        void reader.cancel().catch(() => undefined);
-        controller.error(
-          new Error(`Upstream response exceeded configured limit of ${formatByteLimit(maxBytes)}`),
-        );
-        return;
-      }
-
-      controller.enqueue(chunk.value);
-    },
-    cancel(reason) {
-      return reader.cancel(reason);
-    },
-  });
-
-  return new Response(body, {
-    status: response.status,
-    statusText: response.statusText,
-    headers: response.headers,
-  });
-}
-
-function shouldUseBudgetedSignal(init: RequestInit, deadlineMs: number | undefined): boolean {
-  return deadlineMs !== undefined || init.signal !== undefined;
-}
-
-async function pinnedNodeFetch(
-  rawUrl: string,
-  init: RequestInit,
-  options: SafeFetchOptions,
-  decision: Extract<ResolvedUpstreamUrlDecision, { allow: true }>,
-): Promise<SafeFetchResult> {
-  const parsed = new URL(rawUrl);
-  const pinnedAddress = choosePinnedAddress(decision.addresses);
-  if (pinnedAddress === null) {
-    return {
-      ok: false,
-      kind: "network-policy",
-      reason: `Could not pin a resolved upstream address for "${decision.hostname}"`,
-    };
-  }
-
-  const encodedBody = await requestBodyToUint8Array(init.body);
-  if (!encodedBody.ok) {
-    return { ok: false, kind: "resource-limit", reason: encodedBody.reason };
-  }
-
-  return await new Promise<SafeFetchResult>((resolve, reject) => {
-    const linkedSignal = init.signal ?? undefined;
-    const transport = parsed.protocol === "https:" ? requestHttps : requestHttp;
-    const requestOptions = requestOptionsForPinnedFetch(
-      parsed,
-      init,
-      pinnedAddress,
-      encodedBody.contentType,
-    );
-    const request = transport(requestOptions, (incoming) => {
-      const status = incoming.statusCode ?? 0;
-      if (isRedirectStatus(status)) {
-        incoming.resume();
-        const location = incoming.headers.location;
-        resolve({
-          ok: false,
-          kind: "redirect",
-          reason:
-            location === undefined
-              ? `Upstream returned blocked redirect HTTP ${String(status)}`
-              : `Upstream redirect to "${location}" is blocked; configure the final API URL directly`,
-        });
-        return;
-      }
-
-      const maxBytes = options.responseBytes;
-      const headers = new Headers();
-      for (const [key, value] of Object.entries(incoming.headers)) {
-        if (Array.isArray(value)) {
-          headers.set(key, value.join(", "));
-          continue;
-        }
-        if (value !== undefined) headers.set(key, value);
-      }
-
-      if (maxBytes !== undefined) {
-        const declaredBytes = parseContentLength(headers.get("content-length"));
-        if (declaredBytes !== null && declaredBytes > maxBytes) {
-          incoming.destroy();
-          resolve({
-            ok: false,
-            kind: "resource-limit",
-            reason: `Upstream declared ${String(declaredBytes)} response bytes, exceeding configured limit of ${formatByteLimit(maxBytes)}`,
-          });
-          return;
-        }
-      }
-
-      resolve({
-        ok: true,
-        response: new Response(streamFromIncomingMessage(incoming, maxBytes), {
-          status,
-          statusText: incoming.statusMessage,
-          headers,
-        }),
-      });
-    });
-
-    let timedOut = false;
-    let timeout: ReturnType<typeof setTimeout> | undefined;
-    const finishAbort = (): void => {
-      request.destroy(new DOMException("Safe fetch aborted", "AbortError"));
-    };
-
-    if (linkedSignal !== undefined) {
-      if (linkedSignal.aborted) {
-        finishAbort();
-      } else {
-        linkedSignal.addEventListener("abort", finishAbort, { once: true });
-      }
-    }
-
-    if (options.deadlineMs !== undefined) {
-      timeout = setTimeout(() => {
-        timedOut = true;
-        request.destroy(new DOMException("Safe fetch deadline exceeded", "TimeoutError"));
-      }, options.deadlineMs);
-    }
-
-    request.on("error", (error) => {
-      if (timeout !== undefined) clearTimeout(timeout);
-      if (linkedSignal !== undefined) {
-        linkedSignal.removeEventListener("abort", finishAbort);
-      }
-      if (timedOut) {
-        resolve({
-          ok: false,
-          kind: "timeout",
-          reason: `Upstream request exceeded configured deadline of ${String(options.deadlineMs)} ms`,
-        });
-        return;
-      }
-      reject(error);
-    });
-
-    request.on("close", () => {
-      if (timeout !== undefined) clearTimeout(timeout);
-      if (linkedSignal !== undefined) {
-        linkedSignal.removeEventListener("abort", finishAbort);
-      }
-    });
-
-    if (encodedBody.body !== null) request.write(encodedBody.body);
-    request.end();
-  });
-}
-
-export async function safeFetch(
-  rawUrl: string,
-  init: RequestInit = {},
-  options: SafeFetchOptions = {},
-): Promise<SafeFetchResult> {
-  const resolvedDecision = await evaluateResolvedUpstreamUrlForFetch(rawUrl, options);
-  if (!resolvedDecision.allow) {
-    return { ok: false, kind: "network-policy", reason: resolvedDecision.reason };
-  }
-
-  if (isPinnedDnsEnabled(options)) {
-    return await pinnedNodeFetch(rawUrl, init, options, resolvedDecision);
-  }
-
-  const deadlineMs = options.deadlineMs;
-  const useBudgetedSignal = shouldUseBudgetedSignal(init, deadlineMs);
-  const controller = useBudgetedSignal ? new AbortController() : undefined;
-  let timedOut = false;
-  let timeout: ReturnType<typeof setTimeout> | undefined;
-  const linkedSignal = init.signal ?? undefined;
-  const forwardAbort = (): void => {
-    controller?.abort(linkedSignal?.reason);
-  };
-
-  if (controller !== undefined && linkedSignal !== undefined) {
-    if (linkedSignal.aborted) {
-      forwardAbort();
-    } else {
-      linkedSignal.addEventListener("abort", forwardAbort, { once: true });
-    }
-  }
-
-  if (controller !== undefined && deadlineMs !== undefined) {
-    timeout = setTimeout(() => {
-      timedOut = true;
-      controller.abort(new DOMException("Safe fetch deadline exceeded", "TimeoutError"));
-    }, deadlineMs);
-  }
-
-  try {
-    const response = await fetch(rawUrl, {
-      ...init,
-      redirect: "manual",
-      signal: controller?.signal ?? init.signal,
-    });
-    if (!isRedirectStatus(response.status)) {
-      const maxBytes = options.responseBytes;
-      if (maxBytes === undefined) return { ok: true, response };
-
-      const declaredBytes = parseContentLength(response.headers.get("content-length"));
-      if (declaredBytes !== null && declaredBytes > maxBytes) {
-        await cancelBody(response);
-        return {
-          ok: false,
-          kind: "resource-limit",
-          reason: `Upstream declared ${String(declaredBytes)} response bytes, exceeding configured limit of ${formatByteLimit(maxBytes)}`,
-        };
-      }
-
-      return { ok: true, response: responseWithByteLimit(response, maxBytes) };
-    }
-
-    await cancelBody(response);
-    const location = response.headers.get("location");
-    return {
-      ok: false,
-      kind: "redirect",
-      reason:
-        location === null
-          ? `Upstream returned blocked redirect HTTP ${String(response.status)}`
-          : `Upstream redirect to "${location}" is blocked; configure the final API URL directly`,
-    };
-  } catch (error) {
-    if (timedOut) {
-      return {
-        ok: false,
-        kind: "timeout",
-        reason:
-          deadlineMs === undefined
-            ? "Upstream request exceeded its configured deadline"
-            : `Upstream request exceeded configured deadline of ${String(deadlineMs)} ms`,
-      };
-    }
-    return Promise.reject(error);
-  } finally {
-    if (timeout !== undefined) clearTimeout(timeout);
-    if (controller !== undefined && linkedSignal !== undefined) {
-      linkedSignal.removeEventListener("abort", forwardAbort);
-    }
-  }
-}

package/src/lib/serverPort.ts

@@ -1,47 +0,0 @@
-/* eslint-disable functional/no-throw-statements */
-/**
- * Tracks the HTTP port the inspector server is bound to, so internal
- * components (currently the MCP server's loopback fetch) can build
- * `http://127.0.0.1:<port>/...` URLs without env-var coupling.
- *
- * Initialization order:
- *   1. `setCurrentPort(port)` — explicit override (used by tests, or any
- *      code that has direct knowledge of the bound port).
- *   2. `process.env.AGENT_INSPECTOR_PUBLIC_PORT` — the public identity-proxy
- *      port. The CLI sets this when the runtime is hidden behind a private
- *      upstream port.
- *   3. `process.env.PORT` — fallback for direct dev/server runs.
- *
- * `getCurrentPort()` throws if neither source is available.
- */
-
-let overridePort: number | null = null;
-
-export function setCurrentPort(port: number): void {
-  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
-    throw new Error(`setCurrentPort: invalid port ${port}`);
-  }
-  overridePort = port;
-}
-
-export function getCurrentPort(): number {
-  if (overridePort !== null) return overridePort;
-  const publicPort = process.env["AGENT_INSPECTOR_PUBLIC_PORT"];
-  if (publicPort !== undefined && publicPort !== "") {
-    const n = Number(publicPort);
-    if (Number.isInteger(n) && n > 0 && n <= 65535) return n;
-  }
-  const envPort = process.env["PORT"];
-  if (envPort !== undefined && envPort !== "") {
-    const n = Number(envPort);
-    if (Number.isInteger(n) && n > 0 && n <= 65535) return n;
-  }
-  throw new Error(
-    "Inspector server port not initialized: PORT env var is unset and setCurrentPort() has not been called",
-  );
-}
-
-/** Reset for tests. */
-export function _resetForTests(): void {
-  overridePort = null;
-}

package/src/lib/sessionInfoContract.ts

@@ -1,78 +0,0 @@
-import { z } from "zod";
-import { LogIdSchema } from "../contracts";
-
-export const SessionTokenUsageSchema = z.object({
-  input: z.number().int().nonnegative(),
-  output: z.number().int().nonnegative(),
-  cacheCreate: z.number().int().nonnegative(),
-  cacheRead: z.number().int().nonnegative(),
-  total: z.number().int().nonnegative(),
-});
-
-export const SessionLogSummarySchema = z.object({
-  id: LogIdSchema,
-  sessionLogNumber: z.number().int().positive().optional(),
-  timestamp: z.string(),
-  provider: z.string().nullable(),
-  model: z.string().nullable(),
-  apiFormat: z.enum(["anthropic", "openai", "unknown"]),
-  method: z.string(),
-  path: z.string(),
-  status: z.number().nullable(),
-  isStreaming: z.boolean(),
-  hasError: z.boolean(),
-  error: z.string().nullable(),
-  latencyMs: z.number().nullable(),
-  firstChunkMs: z.number().nullable().optional(),
-  totalStreamMs: z.number().nullable().optional(),
-  tokensPerSecond: z.number().nullable().optional(),
-  tokens: z.object({
-    input: z.number().nullable(),
-    output: z.number().nullable(),
-    cacheCreate: z.number().nullable(),
-    cacheRead: z.number().nullable(),
-  }),
-  sessionId: z.string().nullable(),
-  userAgent: z.string().nullable().optional(),
-  clientPid: z.number().nullable().optional(),
-  clientProjectFolder: z.string().nullable().optional(),
-});
-
-export const SessionInfoSchema = z.object({
-  id: z.string(),
-  status: z.enum(["active", "failed", "completed", "empty"]),
-  logCoverage: z.enum(["recent", "history"]),
-  source: z.enum(["explicit", "client-process", "client-connection", "provider-test"]).nullable(),
-  runtimeMode: z.enum(["in-process", "worker-thread", "child-process"]).nullable(),
-  createdAt: z.string().nullable(),
-  updatedAt: z.string().nullable(),
-  requestCount: z.number().int().nonnegative(),
-  activeRequests: z.number().int().nonnegative(),
-  completedRequests: z.number().int().nonnegative(),
-  failedRequests: z.number().int().nonnegative(),
-  queuedTasks: z.number().int().nonnegative(),
-  runningTasks: z.number().int().nonnegative(),
-  lastTaskError: z.string().nullable(),
-  logCount: z.number().int().nonnegative(),
-  errorCount: z.number().int().nonnegative(),
-  models: z.array(z.string()),
-  providers: z.array(z.string()),
-  tokenUsage: SessionTokenUsageSchema,
-  lastLogId: LogIdSchema.nullable(),
-  lastModel: z.string().nullable(),
-  clientUserAgent: z.string().nullable().optional(),
-  clientPid: z.number().nullable(),
-  clientProjectFolder: z.string().nullable(),
-  inspectorPath: z.string(),
-  inspectorUrl: z.string(),
-  apiPath: z.string(),
-  apiUrl: z.string(),
-  compactLogsPath: z.string(),
-  compactLogsUrl: z.string(),
-  latestLogLimit: z.number().int().positive(),
-  latestLogs: z.array(SessionLogSummarySchema),
-});
-
-export type SessionTokenUsage = z.infer<typeof SessionTokenUsageSchema>;
-export type SessionLogSummary = z.infer<typeof SessionLogSummarySchema>;
-export type SessionInfo = z.infer<typeof SessionInfoSchema>;

package/src/lib/sessionUrl.ts

@@ -1,46 +0,0 @@
-import { withBasePath } from "./basePath";
-
-const B64URL_RE = /^[A-Za-z0-9_-]+$/;
-
-function bytesToBinary(bytes: Uint8Array): string {
-  let binary = "";
-  for (const byte of bytes) {
-    binary += String.fromCharCode(byte);
-  }
-  return binary;
-}
-
-function binaryToBytes(binary: string): Uint8Array {
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) {
-    bytes[i] = binary.charCodeAt(i);
-  }
-  return bytes;
-}
-
-export function encodeSessionIdForPath(sessionId: string): string {
-  const bytes = new TextEncoder().encode(sessionId);
-  const base64 = btoa(bytesToBinary(bytes));
-  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-
-export function decodeSessionIdFromPath(encoded: string): string {
-  if (encoded.startsWith("%")) {
-    return decodeURIComponent(encoded);
-  }
-  if (!B64URL_RE.test(encoded)) {
-    return encoded;
-  }
-  try {
-    const padded = encoded.padEnd(Math.ceil(encoded.length / 4) * 4, "=");
-    const base64 = padded.replace(/-/g, "+").replace(/_/g, "/");
-    const binary = atob(base64);
-    return new TextDecoder().decode(binaryToBytes(binary));
-  } catch {
-    return encoded;
-  }
-}
-
-export function getSessionPath(sessionId: string, basePath?: string): string {
-  return withBasePath(`/session/${encodeSessionIdForPath(sessionId)}`, basePath);
-}