@tonyclaw/agent-inspector 4.0.1 → 4.0.2

package/src/knowledge/types.ts

@@ -1,83 +0,0 @@
-import { z } from "zod";
-import { LogIdSchema } from "../contracts";
-
-export const KnowledgeCandidateTypeSchema = z.enum([
-  "episode",
-  "procedure",
-  "preference",
-  "project-fact",
-]);
-
-export type KnowledgeCandidateType = z.infer<typeof KnowledgeCandidateTypeSchema>;
-
-export const KnowledgeCandidateStatusSchema = z.enum(["draft", "promoted", "failed"]);
-
-export type KnowledgeCandidateStatus = z.infer<typeof KnowledgeCandidateStatusSchema>;
-
-export const KnowledgeEvidenceSchema = z.object({
-  source: z.literal("agent-inspector"),
-  sessionId: z.string(),
-  logIds: z.array(LogIdSchema),
-  project: z.string().nullable(),
-  models: z.array(z.string()),
-});
-
-export const RedactionMetadataSchema = z.object({
-  redacted: z.boolean(),
-  patterns: z.array(z.string()),
-});
-
-export type RedactionMetadata = z.infer<typeof RedactionMetadataSchema>;
-
-export const KnowledgeCandidateSchema = z.object({
-  id: z.string(),
-  type: KnowledgeCandidateTypeSchema,
-  title: z.string(),
-  content: z.string(),
-  tags: z.array(z.string()),
-  source: z.literal("agent-inspector"),
-  sessionId: z.string(),
-  logIds: z.array(LogIdSchema),
-  evidence: KnowledgeEvidenceSchema,
-  status: KnowledgeCandidateStatusSchema,
-  createdAt: z.string(),
-  updatedAt: z.string(),
-  openClawMemoryId: z.string().nullable(),
-  error: z.string().nullable(),
-  redaction: RedactionMetadataSchema,
-});
-
-export type KnowledgeCandidate = z.infer<typeof KnowledgeCandidateSchema>;
-
-export const OpenClawMemoryPayloadSchema = z.object({
-  idempotencyKey: z.string(),
-  type: KnowledgeCandidateTypeSchema,
-  title: z.string(),
-  content: z.string(),
-  tags: z.array(z.string()),
-  source: z.literal("agent-inspector"),
-  project: z.string().nullable(),
-  evidence: KnowledgeEvidenceSchema,
-});
-
-export type OpenClawMemoryPayload = z.infer<typeof OpenClawMemoryPayloadSchema>;
-
-export const KnowledgeSearchResultSchema = z.object({
-  id: z.string(),
-  type: KnowledgeCandidateTypeSchema.or(z.string()),
-  title: z.string(),
-  content: z.string(),
-  score: z.number().nullable(),
-  source: z.string().nullable(),
-  project: z.string().nullable(),
-  evidence: z.unknown().optional(),
-});
-
-export type KnowledgeSearchResult = z.infer<typeof KnowledgeSearchResultSchema>;
-
-export const KnowledgeSearchResponseSchema = z.object({
-  results: z.array(KnowledgeSearchResultSchema),
-  warning: z.string().nullable(),
-});
-
-export type KnowledgeSearchResponse = z.infer<typeof KnowledgeSearchResponseSchema>;

package/src/lib/alertContract.ts

@@ -1,76 +0,0 @@
-import { z } from "zod";
-import { JsonValueSchema, LogIdSchema } from "../contracts";
-
-export const AlertSeveritySchema = z.enum(["critical", "warning", "notice"]);
-export const AlertStatusSchema = z.enum(["open"]);
-export const AlertSourceSchema = z.enum(["proxy", "tool-schema", "run", "group"]);
-export const AlertCategorySchema = z.enum([
-  "request-failure",
-  "request-timeout",
-  "slow-response",
-  "tool-schema",
-  "run-failure",
-  "group-failure",
-  "group-incomplete",
-]);
-export const AlertEvidenceKindSchema = z.enum(["log", "session", "run", "group"]);
-export const AlertApiFormatSchema = z.enum(["anthropic", "openai", "unknown"]);
-
-export const AlertEvidenceLinkSchema = z.object({
-  kind: AlertEvidenceKindSchema,
-  id: z.string(),
-  label: z.string(),
-  href: z.string().nullable(),
-});
-
-export const AlertSchema = z.object({
-  id: z.string(),
-  fingerprint: z.string(),
-  severity: AlertSeveritySchema,
-  category: AlertCategorySchema,
-  source: AlertSourceSchema,
-  status: AlertStatusSchema,
-  title: z.string(),
-  message: z.string(),
-  count: z.number().int().positive(),
-  firstSeenAt: z.string(),
-  lastSeenAt: z.string(),
-  logIds: z.array(LogIdSchema),
-  sessionIds: z.array(z.string()),
-  runIds: z.array(z.string()),
-  groupIds: z.array(z.string()),
-  provider: z.string().nullable(),
-  model: z.string().nullable(),
-  apiFormat: AlertApiFormatSchema.nullable(),
-  evidence: z.array(AlertEvidenceLinkSchema),
-  metadata: z.record(z.string(), JsonValueSchema),
-});
-
-export const AlertCategoryCountSchema = z.object({
-  category: AlertCategorySchema,
-  count: z.number().int().nonnegative(),
-});
-
-export const AlertSummarySchema = z.object({
-  total: z.number().int().nonnegative(),
-  open: z.number().int().nonnegative(),
-  critical: z.number().int().nonnegative(),
-  warning: z.number().int().nonnegative(),
-  notice: z.number().int().nonnegative(),
-  byCategory: z.array(AlertCategoryCountSchema),
-});
-
-export const AlertListResponseSchema = z.object({
-  alerts: z.array(AlertSchema),
-  total: z.number().int().nonnegative(),
-  limit: z.number().int().positive(),
-  summary: AlertSummarySchema,
-});
-
-export type AlertSeverity = z.infer<typeof AlertSeveritySchema>;
-export type AlertSource = z.infer<typeof AlertSourceSchema>;
-export type AlertCategory = z.infer<typeof AlertCategorySchema>;
-export type AlertEvidenceLink = z.infer<typeof AlertEvidenceLinkSchema>;
-export type Alert = z.infer<typeof AlertSchema>;
-export type AlertSummary = z.infer<typeof AlertSummarySchema>;
-export type AlertListResponse = z.infer<typeof AlertListResponseSchema>;

package/src/lib/apiClient.ts

@@ -1,166 +0,0 @@
-/* eslint-disable functional/no-throw-statements */
-import { z } from "zod";
-import { buildControlRuntimeUrl, resolveBrowserRuntimeForDocument } from "./browserRuntimeResolver";
-
-const ApiErrorSchema = z.object({
-  error: z.string(),
-});
-
-const MUTATION_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
-
-function withInspectorControlSurface(input: RequestInfo | URL): RequestInfo | URL {
-  if (typeof input !== "string") return input;
-  if (!input.startsWith("/")) return input;
-  if (input.startsWith("//")) {
-    throw new TypeError("Protocol-relative API URLs are not allowed.");
-  }
-
-  const runtime = resolveBrowserRuntimeForDocument();
-  if (!runtime.ok) {
-    throw new Error(`Browser runtime is unavailable: ${runtime.issues.join("; ")}`);
-  }
-  const url = buildControlRuntimeUrl(runtime.runtime, input);
-  if (url === null) {
-    throw new TypeError(`Invalid logical control path: ${input}`);
-  }
-  return url;
-}
-
-export function withBrowserMutationProof(init?: RequestInit): RequestInit | undefined {
-  const method = init?.method?.toUpperCase();
-  if (method === undefined || !MUTATION_METHODS.has(method)) return init;
-  const headers = new Headers(init?.headers);
-  if (!headers.has("x-agent-inspector-csrf")) {
-    headers.set("x-agent-inspector-csrf", "1");
-  }
-  return { ...init, headers };
-}
-
-/**
- * Parse and validate a JSON response at the browser/server trust boundary.
- *
- * Keeping this in one place makes response validation consistent without
- * coupling callers to a specific API or domain type.
- */
-export async function parseJsonResponse<T>(response: Response, schema: z.ZodType<T>): Promise<T> {
-  const data: unknown = await response.json();
-  return schema.parse(data);
-}
-
-/**
- * Read the conventional `{ error: string }` API response when available.
- * Malformed or non-JSON error bodies deliberately fall back to caller-owned
- * text so each screen retains its existing user-facing message.
- */
-export async function readApiError(response: Response, fallback: string): Promise<string> {
-  try {
-    const data: unknown = await response.json();
-    const result = ApiErrorSchema.safeParse(data);
-    return result.success ? result.data.error : fallback;
-  } catch {
-    return fallback;
-  }
-}
-
-/**
- * Fetch through the browser runtime's control surface while retaining the
- * mutation proof required by the protected ingress.
- */
-export async function fetchControl(
-  input: RequestInfo | URL,
-  init?: RequestInit,
-): Promise<Response> {
-  return await fetch(withInspectorControlSurface(input), withBrowserMutationProof(init));
-}
-
-/**
- * Fetch a JSON resource and validate its successful response.
- */
-export async function fetchJson<T>(
-  input: RequestInfo | URL,
-  schema: z.ZodType<T>,
-  init?: RequestInit,
-  errorFallback?: (response: Response) => string,
-): Promise<T> {
-  const response = await fetchControl(input, init);
-  if (!response.ok) {
-    const fallback = errorFallback?.(response) ?? `Request failed with status ${response.status}`;
-    throw new Error(await readApiError(response, fallback));
-  }
-  return parseJsonResponse(response, schema);
-}
-
-function formatTimeout(timeoutMs: number): string {
-  if (timeoutMs < 1000) return `${String(timeoutMs)}ms`;
-  return `${String(Math.round(timeoutMs / 1000))}s`;
-}
-
-export class ApiTimeoutError extends Error {
-  constructor(timeoutMs: number) {
-    super(`Request timed out after ${formatTimeout(timeoutMs)}`);
-    this.name = "ApiTimeoutError";
-  }
-}
-
-/**
- * Fetch any resource with a browser-side timeout while preserving a caller
- * supplied abort signal. The timeout is reported as `ApiTimeoutError`; caller
- * cancellations keep the native abort shape so UI code can distinguish them.
- */
-export async function fetchWithTimeout(
-  input: RequestInfo | URL,
-  timeoutMs: number,
-  init?: RequestInit,
-): Promise<Response> {
-  const controller = new AbortController();
-  let timedOut = false;
-  const timeout = setTimeout(() => {
-    timedOut = true;
-    controller.abort();
-  }, timeoutMs);
-
-  const callerSignal = init?.signal ?? undefined;
-  const abortFromCaller = (): void => controller.abort();
-  if (callerSignal !== undefined) {
-    if (callerSignal.aborted) {
-      controller.abort();
-    } else {
-      callerSignal.addEventListener("abort", abortFromCaller, { once: true });
-    }
-  }
-
-  try {
-    return await fetchControl(input, {
-      ...init,
-      signal: controller.signal,
-    });
-  } catch (error) {
-    if (timedOut && error instanceof DOMException && error.name === "AbortError") {
-      throw new ApiTimeoutError(timeoutMs);
-    }
-    throw error;
-  } finally {
-    clearTimeout(timeout);
-    callerSignal?.removeEventListener("abort", abortFromCaller);
-  }
-}
-
-/**
- * Fetch a JSON resource with a browser-side timeout. This prevents UI loading
- * states from waiting forever when a tab keeps a stale connection across a
- * local server force-restart.
- */
-export async function fetchJsonWithTimeout<T>(
-  input: RequestInfo | URL,
-  schema: z.ZodType<T>,
-  timeoutMs: number,
-  init?: RequestInit,
-  errorFallback?: (response: Response) => string,
-): Promise<T> {
-  const response = await fetchWithTimeout(input, timeoutMs, init);
-  if (!response.ok) {
-    const fallback = errorFallback?.(response) ?? `Request failed with status ${response.status}`;
-    throw new Error(await readApiError(response, fallback));
-  }
-  return parseJsonResponse(response, schema);
-}

package/src/lib/apiFormat.ts

@@ -1,29 +0,0 @@
-import type { ApiFormat } from "../contracts/log";
-
-type KnownApiFormat = Exclude<ApiFormat, "unknown">;
-
-/**
- * Request paths whose protocol is part of the public Agent Inspector contract.
- *
- * Keep this module browser-safe: both the proxy registry and the UI's log
- * presentation use the same path classifier without importing proxy startup
- * registrations or provider implementations.
- */
-export const API_FORMAT_PATH_ENTRIES: ReadonlyArray<
-  readonly [path: string, format: KnownApiFormat]
-> = [
-  ["/v1/messages", "anthropic"],
-  ["/v1/chat/completions", "openai"],
-  ["/chat/completions", "openai"],
-  ["/v1/responses", "openai"],
-  ["/responses", "openai"],
-];
-
-/** Resolve an API format from its authoritative request path. */
-export function apiFormatForPath(path: string): ApiFormat {
-  const requestPath = path.split("?")[0] ?? "";
-  for (const [knownPath, format] of API_FORMAT_PATH_ENTRIES) {
-    if (requestPath === knownPath) return format;
-  }
-  return "unknown";
-}

package/src/lib/backendImplementation.ts

@@ -1,16 +0,0 @@
-import { z } from "zod";
-
-export const AGENT_INSPECTOR_BACKEND_ENV = "AGENT_INSPECTOR_BACKEND";
-export const AGENT_INSPECTOR_BACKEND_HEADER = "x-agent-inspector-backend";
-
-export const BackendImplementationSchema = z.enum(["typescript", "rust"]);
-
-export type BackendImplementation = z.infer<typeof BackendImplementationSchema>;
-
-export function parseBackendImplementation(
-  value: string | undefined,
-): BackendImplementation | null {
-  if (value === undefined) return "typescript";
-  const parsed = BackendImplementationSchema.safeParse(value.trim().toLowerCase());
-  return parsed.success ? parsed.data : null;
-}

package/src/lib/basePath.ts

@@ -1,107 +0,0 @@
-/// <reference types="vite/client" />
-
-export const AGENT_INSPECTOR_BASE_PATH_ENV = "AGENT_INSPECTOR_BASE_PATH";
-export const AGENT_INSPECTOR_INTERNAL_STRIPPED_BASE_PATH_ENV =
-  "AGENT_INSPECTOR_INTERNAL_STRIPPED_BASE_PATH";
-export const AGENT_INSPECTOR_BASE_PATH_META_NAME = "agent-inspector-base-path";
-export const AGENT_INSPECTOR_PUBLIC_BASE_PATH_HEADER = "x-agent-inspector-public-base-path";
-export const AGENT_INSPECTOR_PUBLIC_PORT_HEADER = "x-agent-inspector-public-port";
-export const AGENT_INSPECTOR_PUBLIC_ORIGIN_HEADER = "x-agent-inspector-public-origin";
-export const DEFAULT_AGENT_INSPECTOR_BASE_PATH = "/inspector";
-
-type BasePathEnv = Readonly<Record<string, string | undefined>>;
-
-function trimSlashes(value: string): string {
-  return value.replace(/^\/+/u, "").replace(/\/+$/u, "");
-}
-
-const SAFE_PUBLIC_BASE_PATH_PATTERN = /^\/[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*$/u;
-
-/**
- * Normalize a public mount path only when every segment is safe to reuse in
- * URLs, HTML attributes, JavaScript bootstrap data, and ingress routing.
- * Root is represented internally as the empty string.
- */
-export function normalizePublicBasePath(value: string | undefined): string | null {
-  const trimmed = value?.trim() ?? "";
-  if (trimmed.length === 0 || trimmed === "/") return "";
-  if (!trimmed.startsWith("/") || trimmed.startsWith("//")) return null;
-
-  const normalized = normalizeBasePath(trimmed);
-  if (!SAFE_PUBLIC_BASE_PATH_PATTERN.test(normalized)) return null;
-  if (normalized.split("/").some((segment) => segment === "." || segment === "..")) return null;
-  return normalized;
-}
-
-export function normalizeBasePath(value: string | undefined): string {
-  const trimmed = value?.trim();
-  if (trimmed === undefined || trimmed.length === 0 || trimmed === "/") return "";
-  const path = trimSlashes(trimmed);
-  if (path.length === 0) return "";
-  return `/${path}`;
-}
-
-function readDocumentBasePath(): string | undefined {
-  if (typeof document === "undefined") return undefined;
-  return (
-    document
-      .querySelector(`meta[name="${AGENT_INSPECTOR_BASE_PATH_META_NAME}"]`)
-      ?.getAttribute("content") ?? undefined
-  );
-}
-
-function readProcessBasePath(): string | undefined {
-  if (typeof process === "undefined") return undefined;
-  return process.env[AGENT_INSPECTOR_BASE_PATH_ENV];
-}
-
-export function getConfiguredBasePath(env?: BasePathEnv): string {
-  const configured =
-    env !== undefined
-      ? (env[AGENT_INSPECTOR_BASE_PATH_ENV] ?? DEFAULT_AGENT_INSPECTOR_BASE_PATH)
-      : (readProcessBasePath() ??
-        readDocumentBasePath() ??
-        import.meta.env?.BASE_URL ??
-        DEFAULT_AGENT_INSPECTOR_BASE_PATH);
-  const normalized = normalizePublicBasePath(configured);
-  if (normalized !== null) return normalized;
-  return normalizePublicBasePath(DEFAULT_AGENT_INSPECTOR_BASE_PATH) ?? "";
-}
-
-export function getRouterBasePath(env?: BasePathEnv): string {
-  if (env?.[AGENT_INSPECTOR_INTERNAL_STRIPPED_BASE_PATH_ENV] === "1") return "";
-  return getConfiguredBasePath(env);
-}
-
-export function basePathForVite(basePath: string): string {
-  const normalized = normalizeBasePath(basePath);
-  return normalized.length === 0 ? "/" : `${normalized}/`;
-}
-
-export function withBasePath(path: string, basePath = getConfiguredBasePath()): string {
-  const normalized = normalizeBasePath(basePath);
-  if (/^[a-z][a-z0-9+.-]*:/iu.test(path)) return path;
-  if (normalized.length === 0) return path;
-  if (path.length === 0 || path === "/") return normalized;
-  if (path.startsWith(`${normalized}/`) || path === normalized) return path;
-  return path.startsWith("/") ? `${normalized}${path}` : `${normalized}/${path}`;
-}
-
-export function stripBasePath(pathname: string, basePath = getConfiguredBasePath()): string {
-  const normalized = normalizeBasePath(basePath);
-  if (normalized.length === 0) return pathname;
-  if (pathname === normalized) return "/";
-  if (pathname.startsWith(`${normalized}/`)) return pathname.slice(normalized.length);
-  return pathname;
-}
-
-export function appendBasePathToOrigin(origin: string, path: string, basePath: string): string {
-  const normalized = normalizeBasePath(basePath);
-  if (normalized.length === 0 && path === "/") return origin;
-  return `${origin}${withBasePath(path, normalized)}`;
-}
-
-export function stripBasePathFromRequestPath(rawPath: string, basePath: string): string {
-  const url = new URL(rawPath, "http://localhost");
-  return `${stripBasePath(url.pathname, basePath)}${url.search}`;
-}

package/src/lib/browserRuntimeContract.ts

@@ -1,124 +0,0 @@
-import { z } from "zod";
-import { normalizePublicBasePath } from "./basePath";
-
-export const BROWSER_RUNTIME_SCHEMA_VERSION = 1;
-export const BROWSER_RUNTIME_JSON_PLACEHOLDER = "__AGENT_INSPECTOR_RUNTIME_JSON__";
-
-function parseAbsoluteUrl(value: string): URL | null {
-  try {
-    return new URL(value);
-  } catch {
-    return null;
-  }
-}
-
-function hasUnsafePathSegment(pathname: string): boolean {
-  return pathname
-    .split("/")
-    .some((segment) => segment === "." || segment === ".." || /%(?:2e|2f|5c)/iu.test(segment));
-}
-
-function hasControlCharacter(value: string): boolean {
-  return [...value].some((character) => {
-    const code = character.charCodeAt(0);
-    return code < 32 || code === 127;
-  });
-}
-
-export function normalizeBrowserRuntimeBasePath(value: string): string | null {
-  const trimmed = value.trim();
-  if (trimmed.length === 0) return null;
-  const normalized = normalizePublicBasePath(trimmed);
-  if (normalized === null) return null;
-  return normalized.length === 0 ? "/" : normalized;
-}
-
-export function normalizeBrowserRuntimeBaseUrl(value: string): string | null {
-  if (
-    value.trim() !== value ||
-    value.includes("\\") ||
-    hasControlCharacter(value) ||
-    hasUnsafePathSegment(value)
-  ) {
-    return null;
-  }
-
-  const parsed = parseAbsoluteUrl(value);
-  if (parsed === null) return null;
-
-  switch (parsed.protocol) {
-    case "http:":
-    case "https:":
-      break;
-    default:
-      return null;
-  }
-
-  if (
-    parsed.username.length > 0 ||
-    parsed.password.length > 0 ||
-    parsed.search.length > 0 ||
-    parsed.hash.length > 0 ||
-    hasUnsafePathSegment(parsed.pathname)
-  ) {
-    return null;
-  }
-
-  const basePath = normalizeBrowserRuntimeBasePath(parsed.pathname);
-  if (basePath === null) return null;
-  return basePath === "/" ? parsed.origin : `${parsed.origin}${basePath}`;
-}
-
-export const BrowserRuntimeBasePathSchema = z
-  .string()
-  .min(1)
-  .max(2_048)
-  .refine(
-    (value) => normalizeBrowserRuntimeBasePath(value) !== null,
-    "UI Base Path must be an absolute path without query, hash, backslash, or traversal",
-  )
-  .transform((value) => normalizeBrowserRuntimeBasePath(value) ?? value);
-
-export const BrowserRuntimeBaseUrlSchema = z
-  .string()
-  .min(1)
-  .max(2_048)
-  .refine(
-    (value) => normalizeBrowserRuntimeBaseUrl(value) !== null,
-    "Runtime Base URL must be an HTTP(S) URL without credentials, query, hash, or traversal",
-  )
-  .transform((value) => normalizeBrowserRuntimeBaseUrl(value) ?? value);
-
-export const BrowserRuntimeCapabilitiesSchema = z
-  .object({
-    rest: z.boolean(),
-    sse: z.boolean(),
-    proxy: z.boolean(),
-    mcp: z.boolean(),
-  })
-  .strict();
-
-export const BrowserRuntimeDeploymentSchema = z
-  .object({
-    schemaVersion: z.literal(BROWSER_RUNTIME_SCHEMA_VERSION),
-    deploymentMode: z.enum(["composed", "backend-only", "separated"]),
-    ui: z
-      .object({
-        basePath: BrowserRuntimeBasePathSchema,
-      })
-      .strict(),
-    control: z
-      .object({
-        baseUrl: BrowserRuntimeBaseUrlSchema,
-      })
-      .strict(),
-    agent: z
-      .object({
-        baseUrl: BrowserRuntimeBaseUrlSchema,
-      })
-      .strict(),
-    capabilities: BrowserRuntimeCapabilitiesSchema,
-  })
-  .strict();
-
-export type BrowserRuntimeDeployment = z.infer<typeof BrowserRuntimeDeploymentSchema>;