@tonyclaw/agent-inspector 3.0.44 → 3.0.46

package/src/lib/instanceContract.ts

@@ -0,0 +1,236 @@
+import { z } from "zod";
+import { normalizePublicBasePath } from "./basePath";
+
+export const INSTANCE_API_SCHEMA_VERSION = 1;
+
+function isCanonicalPublicBasePath(value: string): boolean {
+  const normalized = normalizePublicBasePath(value);
+  return normalized !== null && (normalized.length === 0 ? "/" : normalized) === value;
+}
+
+export const InstanceStateSchema = z.enum(["running", "stopped", "conflict"]);
+export const InstanceStateReasonSchema = z.enum(["identity_mismatch", "port_conflict"]);
+
+export const InstanceUrlsSchema = z
+  .object({
+    ui: z.url(),
+    api: z.url(),
+    health: z.url(),
+    proxy: z.url(),
+    openai: z.url(),
+    mcp: z.url(),
+  })
+  .strict();
+
+export const InstanceStatusOutputSchema = z
+  .object({
+    schemaVersion: z.literal(INSTANCE_API_SCHEMA_VERSION),
+    name: z.string().min(1),
+    instanceId: z.string().min(1),
+    state: InstanceStateSchema,
+    stateReason: InstanceStateReasonSchema.nullable(),
+    checkedAt: z.iso.datetime(),
+    createdAt: z.iso.datetime(),
+    updatedAt: z.iso.datetime(),
+    launch: z
+      .object({
+        launchId: z.string().min(1),
+        startedAt: z.iso.datetime(),
+      })
+      .strict(),
+    host: z.string().min(1),
+    publicPort: z.number().int().min(1).max(65_535),
+    upstreamPort: z.number().int().min(1).max(65_535),
+    basePath: z.string().refine(isCanonicalPublicBasePath, "Invalid public Base Path"),
+    captureMode: z.enum(["simple", "full"]),
+    uiEnabled: z.boolean(),
+    dataDir: z.string().min(1),
+    supervisorPid: z.number().int().positive().nullable(),
+    urls: InstanceUrlsSchema,
+  })
+  .strict();
+
+export const InstanceConnectionSurfacesSchema = z
+  .object({
+    ui: z
+      .object({
+        enabled: z.boolean(),
+        baseUrl: z.url().nullable(),
+      })
+      .strict(),
+    control: z.object({ baseUrl: z.url() }).strict(),
+    agent: z.object({ baseUrl: z.url() }).strict(),
+  })
+  .strict();
+
+export const InstanceConnectionOutputSchema = z
+  .object({
+    schemaVersion: z.literal(INSTANCE_API_SCHEMA_VERSION),
+    uiEnabled: z.boolean(),
+    instance: InstanceStatusOutputSchema,
+    surfaces: InstanceConnectionSurfacesSchema,
+    /** @deprecated Use surfaces.control.baseUrl or surfaces.agent.baseUrl. */
+    baseUrl: z.url(),
+    endpoints: InstanceUrlsSchema,
+    environment: z
+      .object({
+        ANTHROPIC_BASE_URL: z.url(),
+        LLM_BASE_URL: z.url(),
+        OPENAI_BASE_URL: z.url(),
+        AGENT_INSPECTOR_MCP_URL: z.url(),
+      })
+      .strict(),
+    mcp: z
+      .object({
+        serverName: z.string().min(1),
+        transport: z.literal("streamable-http"),
+        url: z.url(),
+      })
+      .strict(),
+    codex: z
+      .object({
+        providerName: z.string().min(1),
+        baseUrl: z.url(),
+        wireApi: z.literal("responses"),
+      })
+      .strict(),
+  })
+  .strict();
+
+export const InstanceStartRequestSchema = z
+  .object({
+    port: z.number().int().min(1).max(65_535).optional(),
+    basePath: z
+      .string()
+      .min(1)
+      .max(2_048)
+      .refine(
+        (value) => normalizePublicBasePath(value) !== null,
+        "Base Path must use URL-safe path segments without traversal, encoded separators, or markup characters",
+      )
+      .optional(),
+    host: z
+      .string()
+      .min(1)
+      .max(253)
+      .refine(
+        (value) =>
+          value.trim() === value &&
+          !value.includes("://") &&
+          !value.includes("/") &&
+          !value.includes("\\") &&
+          !/\s/u.test(value),
+        "Host must be a hostname or IP address without protocol, path, or whitespace",
+      )
+      .optional(),
+    captureMode: z.enum(["simple", "full"]).optional(),
+    uiEnabled: z.boolean().optional(),
+    dataDir: z.string().trim().min(1).max(32_767).optional(),
+  })
+  .strict();
+
+export const InstanceEmptyRequestSchema = z.object({}).strict();
+
+export const InstanceOperationSchema = z.enum(["start", "stop", "restart"]);
+export const InstanceOperationOutcomeSchema = z.enum([
+  "created",
+  "started",
+  "already_running",
+  "stopped",
+  "already_stopped",
+  "restarted",
+]);
+
+export const InstanceOperationOutputSchema = z
+  .object({
+    schemaVersion: z.literal(INSTANCE_API_SCHEMA_VERSION),
+    operation: InstanceOperationSchema,
+    outcome: InstanceOperationOutcomeSchema,
+    instance: InstanceStatusOutputSchema,
+  })
+  .strict();
+
+export const InstanceListOutputSchema = z
+  .object({
+    schemaVersion: z.literal(INSTANCE_API_SCHEMA_VERSION),
+    instances: z.array(InstanceStatusOutputSchema),
+  })
+  .strict();
+
+export const InstancePublicErrorCodeSchema = z.enum([
+  "argument_invalid",
+  "config_mismatch",
+  "data_dir_conflict",
+  "data_dir_invalid",
+  "identity_mismatch",
+  "instance_not_found",
+  "launch_failed",
+  "launch_unavailable",
+  "lock_not_owned",
+  "lock_timeout",
+  "name_invalid",
+  "port_conflict",
+  "port_exhausted",
+  "port_invalid",
+  "record_invalid",
+  "registry_io",
+  "restart_failed_degraded",
+  "restart_failed_rolled_back",
+  "self_lifecycle_unsupported",
+  "shutdown_failed",
+]);
+
+export const InstancePublicErrorSchema = z
+  .object({
+    code: InstancePublicErrorCodeSchema,
+    message: z.string().min(1),
+    retryable: z.boolean(),
+  })
+  .strict();
+
+export const InstanceErrorOutputSchema = z
+  .object({
+    schemaVersion: z.literal(INSTANCE_API_SCHEMA_VERSION),
+    error: InstancePublicErrorSchema,
+  })
+  .strict();
+
+export type InstanceStatusOutput = z.infer<typeof InstanceStatusOutputSchema>;
+export type InstanceConnectionOutput = z.infer<typeof InstanceConnectionOutputSchema>;
+export type InstanceStartRequest = z.infer<typeof InstanceStartRequestSchema>;
+export type InstanceOperationOutcome = z.infer<typeof InstanceOperationOutcomeSchema>;
+export type InstanceOperationOutput = z.infer<typeof InstanceOperationOutputSchema>;
+export type InstancePublicErrorCode = z.infer<typeof InstancePublicErrorCodeSchema>;
+export type InstancePublicError = z.infer<typeof InstancePublicErrorSchema>;
+export type InstanceErrorOutput = z.infer<typeof InstanceErrorOutputSchema>;
+
+export function isRetryableInstanceError(code: InstancePublicErrorCode): boolean {
+  switch (code) {
+    case "launch_failed":
+    case "launch_unavailable":
+    case "lock_timeout":
+    case "port_exhausted":
+    case "registry_io":
+    case "restart_failed_degraded":
+    case "restart_failed_rolled_back":
+    case "shutdown_failed":
+      return true;
+    case "argument_invalid":
+    case "config_mismatch":
+    case "data_dir_conflict":
+    case "data_dir_invalid":
+    case "identity_mismatch":
+    case "instance_not_found":
+    case "lock_not_owned":
+    case "name_invalid":
+    case "port_conflict":
+    case "port_invalid":
+    case "record_invalid":
+    case "self_lifecycle_unsupported":
+      return false;
+  }
+}
+
+export function instanceErrorOutput(error: InstancePublicError): InstanceErrorOutput {
+  return { schemaVersion: INSTANCE_API_SCHEMA_VERSION, error };
+}

package/src/lib/managedInstance.ts

@@ -0,0 +1,104 @@
+export const MANAGED_INSTANCE_CONTROL_PATH = "/.agent-inspector/instance";
+export const MANAGED_INSTANCE_SHUTDOWN_PATH = `${MANAGED_INSTANCE_CONTROL_PATH}/shutdown`;
+export const MANAGED_INSTANCE_TOKEN_HEADER = "x-agent-inspector-instance-token";
+export const MANAGED_INSTANCE_SHUTDOWN_MESSAGE_TYPE = "agent-inspector:managed-shutdown";
+export const AGENT_INSPECTOR_CLI_ENTRY_ENV = "AGENT_INSPECTOR_CLI_ENTRY";
+
+export const MANAGED_INSTANCE_ENV = {
+  name: "AGENT_INSPECTOR_INSTANCE_NAME",
+  instanceId: "AGENT_INSPECTOR_INSTANCE_ID",
+  launchId: "AGENT_INSPECTOR_INSTANCE_LAUNCH_ID",
+  controlToken: "AGENT_INSPECTOR_INSTANCE_CONTROL_TOKEN",
+  startedAt: "AGENT_INSPECTOR_INSTANCE_STARTED_AT",
+  upstreamPort: "AGENT_INSPECTOR_UPSTREAM_PORT",
+} as const;
+
+type ManagedInstanceEnv = Readonly<Record<string, string | undefined>>;
+
+export type ManagedInstanceLaunch = {
+  name: string;
+  instanceId: string;
+  launchId: string;
+  controlToken: string;
+  startedAt: string;
+  upstreamPort: number;
+};
+
+export type ManagedInstanceLaunchResult =
+  | { kind: "unmanaged" }
+  | { kind: "invalid"; message: string }
+  | { kind: "managed"; launch: ManagedInstanceLaunch };
+
+export type ManagedInstanceShutdownMessage = {
+  type: typeof MANAGED_INSTANCE_SHUTDOWN_MESSAGE_TYPE;
+  controlToken: string;
+};
+
+function nonEmpty(value: string | undefined): string | null {
+  const trimmed = value?.trim();
+  return trimmed === undefined || trimmed.length === 0 ? null : trimmed;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function readManagedInstanceLaunch(
+  env: ManagedInstanceEnv = process.env,
+): ManagedInstanceLaunchResult {
+  const values = [
+    env[MANAGED_INSTANCE_ENV.name],
+    env[MANAGED_INSTANCE_ENV.instanceId],
+    env[MANAGED_INSTANCE_ENV.launchId],
+    env[MANAGED_INSTANCE_ENV.controlToken],
+    env[MANAGED_INSTANCE_ENV.startedAt],
+    env[MANAGED_INSTANCE_ENV.upstreamPort],
+  ];
+  if (values.every((value) => value === undefined || value.trim().length === 0)) {
+    return { kind: "unmanaged" };
+  }
+
+  const name = nonEmpty(env[MANAGED_INSTANCE_ENV.name]);
+  const instanceId = nonEmpty(env[MANAGED_INSTANCE_ENV.instanceId]);
+  const launchId = nonEmpty(env[MANAGED_INSTANCE_ENV.launchId]);
+  const controlToken = nonEmpty(env[MANAGED_INSTANCE_ENV.controlToken]);
+  const startedAt = nonEmpty(env[MANAGED_INSTANCE_ENV.startedAt]);
+  const upstreamPort = Number(env[MANAGED_INSTANCE_ENV.upstreamPort]);
+  if (
+    name === null ||
+    instanceId === null ||
+    launchId === null ||
+    controlToken === null ||
+    controlToken.length < 32 ||
+    startedAt === null ||
+    !Number.isFinite(Date.parse(startedAt)) ||
+    !Number.isInteger(upstreamPort) ||
+    upstreamPort < 1 ||
+    upstreamPort > 65_535
+  ) {
+    return {
+      kind: "invalid",
+      message: "Managed instance launch environment is incomplete or invalid.",
+    };
+  }
+  return {
+    kind: "managed",
+    launch: { name, instanceId, launchId, controlToken, startedAt, upstreamPort },
+  };
+}
+
+export function managedInstanceShutdownMessage(
+  controlToken: string,
+): ManagedInstanceShutdownMessage {
+  return { type: MANAGED_INSTANCE_SHUTDOWN_MESSAGE_TYPE, controlToken };
+}
+
+export function parseManagedInstanceShutdownMessage(
+  value: unknown,
+): ManagedInstanceShutdownMessage | null {
+  if (!isRecord(value)) return null;
+  return value["type"] === MANAGED_INSTANCE_SHUTDOWN_MESSAGE_TYPE &&
+    typeof value["controlToken"] === "string"
+    ? { type: MANAGED_INSTANCE_SHUTDOWN_MESSAGE_TYPE, controlToken: value["controlToken"] }
+    : null;
+}

package/src/lib/piAgentContract.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { LogIdSchema } from "../contracts";
 
 export const PiAgentHistoryMessageSchema = z.object({
   role: z.enum(["user", "assistant"]),
@@ -55,9 +56,9 @@ export const PiAgentQueryStatsSchema = z.object({
 export const PiAgentEvidenceSchema = z.object({
   source: PiAgentEvidenceSourceSchema,
   id: z.string(),
-  logId: z.number().int().positive().optional(),
+  logId: LogIdSchema.optional(),
   knowledgeId: z.string().optional(),
-  logIds: z.array(z.number().int().positive()).optional(),
+  logIds: z.array(LogIdSchema).optional(),
   timestamp: z.string().optional(),
   sessionId: z.string().optional(),
   model: z.string().optional(),

package/src/lib/publicBasePathContext.ts

@@ -0,0 +1,137 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import {
+  AGENT_INSPECTOR_PUBLIC_BASE_PATH_HEADER,
+  AGENT_INSPECTOR_PUBLIC_ORIGIN_HEADER,
+  AGENT_INSPECTOR_PUBLIC_PORT_HEADER,
+  getConfiguredBasePath,
+  normalizePublicBasePath,
+} from "./basePath";
+import { getCurrentPort } from "./serverPort";
+
+type BasePathEnv = Readonly<Record<string, string | undefined>>;
+
+type PublicRequestContext = {
+  basePath: string;
+  publicOrigin: string | null;
+  publicPort: number | null;
+};
+
+const publicRequestStorage = new AsyncLocalStorage<PublicRequestContext>();
+
+/**
+ * Resolve the public Base Path attached by the trusted ingress. Invalid or
+ * missing values fall back to the process's canonical Base Path.
+ */
+export function resolveRequestPublicBasePath(request: Request, env?: BasePathEnv): string {
+  const rawValue = request.headers.get(AGENT_INSPECTOR_PUBLIC_BASE_PATH_HEADER);
+  if (rawValue !== null) {
+    const normalized = normalizePublicBasePath(rawValue);
+    if (normalized !== null) return normalized;
+  }
+  return getConfiguredBasePath(env ?? process.env);
+}
+
+/** Resolve the trusted ingress listener port without consulting request URL or Host. */
+export function resolveRequestPublicPort(request: Request): number | null {
+  const rawValue = request.headers.get(AGENT_INSPECTOR_PUBLIC_PORT_HEADER);
+  if (rawValue !== null && /^\d{1,5}$/u.test(rawValue)) {
+    const headerPort = Number(rawValue);
+    if (Number.isSafeInteger(headerPort) && headerPort > 0 && headerPort <= 65_535) {
+      return headerPort;
+    }
+  }
+  try {
+    return getCurrentPort();
+  } catch {
+    // Vite dev does not always publish its listener port through process env.
+  }
+  try {
+    const urlPort = new URL(request.url).port;
+    if (!/^\d{1,5}$/u.test(urlPort)) return null;
+    const port = Number(urlPort);
+    return Number.isSafeInteger(port) && port > 0 && port <= 65_535 ? port : null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizedPublicOrigin(value: string): string | null {
+  try {
+    const parsed = new URL(value);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+    if (parsed.username.length > 0 || parsed.password.length > 0) return null;
+    if (parsed.pathname !== "/" || parsed.search.length > 0 || parsed.hash.length > 0) return null;
+    return parsed.origin;
+  } catch {
+    return null;
+  }
+}
+
+/** Resolve the public origin set by trusted ingress without consulting forwarded headers. */
+export function resolveRequestPublicOrigin(request: Request): string | null {
+  const headerOrigin = request.headers.get(AGENT_INSPECTOR_PUBLIC_ORIGIN_HEADER);
+  if (headerOrigin !== null) return normalizedPublicOrigin(headerOrigin);
+  try {
+    return normalizedPublicOrigin(new URL(request.url).origin);
+  } catch {
+    return null;
+  }
+}
+
+/** Return the originating request's public Base Path, or the canonical path outside a request. */
+export function getPublicBasePath(env?: BasePathEnv): string {
+  return publicRequestStorage.getStore()?.basePath ?? getConfiguredBasePath(env ?? process.env);
+}
+
+/** Return the trusted ingress listener port, or the canonical process port outside a request. */
+export function getPublicPort(): number {
+  return publicRequestStorage.getStore()?.publicPort ?? getCurrentPort();
+}
+
+/** Return the trusted public origin, with a loopback fallback outside an ingress request. */
+export function getPublicOrigin(): string {
+  return (
+    publicRequestStorage.getStore()?.publicOrigin ?? `http://localhost:${String(getCurrentPort())}`
+  );
+}
+
+/** Run work with an explicitly selected public Base Path. Primarily useful for internal calls. */
+export function runWithPublicBasePath<T>(basePath: string, callback: () => T): T {
+  const current = publicRequestStorage.getStore();
+  const normalized = normalizePublicBasePath(basePath) ?? getConfiguredBasePath(process.env);
+  return publicRequestStorage.run(
+    {
+      basePath: normalized,
+      publicOrigin: current?.publicOrigin ?? null,
+      publicPort: current?.publicPort ?? null,
+    },
+    callback,
+  );
+}
+
+/** Run work with an explicit trusted public listener port. */
+export function runWithPublicPort<T>(publicPort: number, callback: () => T): T {
+  const current = publicRequestStorage.getStore();
+  const normalizedPort =
+    Number.isSafeInteger(publicPort) && publicPort > 0 && publicPort <= 65_535 ? publicPort : null;
+  return publicRequestStorage.run(
+    {
+      basePath: current?.basePath ?? getConfiguredBasePath(process.env),
+      publicOrigin: current?.publicOrigin ?? null,
+      publicPort: normalizedPort,
+    },
+    callback,
+  );
+}
+
+/** Run the complete request chain with the ingress-selected public Base Path. */
+export function runWithRequestPublicBasePath<T>(request: Request, callback: () => T): T {
+  return publicRequestStorage.run(
+    {
+      basePath: resolveRequestPublicBasePath(request),
+      publicOrigin: resolveRequestPublicOrigin(request),
+      publicPort: resolveRequestPublicPort(request),
+    },
+    callback,
+  );
+}

package/src/lib/resourceLimits.ts

@@ -9,6 +9,7 @@ export const MAX_PROVIDER_MODEL_METADATA = 64;
 export const MAX_SSE_CLIENTS = 32;
 export const MAX_ACTIVE_PROVIDER_TESTS = 2;
 export const MAX_PROVIDER_TEST_CONCURRENCY = 4;
+export const MAX_ACTIVE_PROXY_REQUESTS = 16;
 
 export const ResourceLimitErrorCodeSchema = z.enum([
   "invalid-page-request",
@@ -16,6 +17,7 @@ export const ResourceLimitErrorCodeSchema = z.enum([
   "provider-model-limit-exceeded",
   "sse-capacity-exceeded",
   "provider-test-capacity-exceeded",
+  "proxy-capacity-exceeded",
 ]);
 
 export const ResourceLimitStatusSchema = z.union([

package/src/lib/runContract.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { JsonValueSchema } from "../contracts";
+import { JsonValueSchema, LogIdSchema } from "../contracts";
 import { SessionInfoSchema } from "./sessionInfoContract";
 
 export const InspectorRunStatusSchema = z.enum([
@@ -33,7 +33,7 @@ export const RunTimelineEventSchema = z.object({
   severity: RunTimelineEventSeveritySchema,
   title: z.string(),
   details: z.string(),
-  logId: z.number().int().positive().nullable(),
+  logId: LogIdSchema.nullable(),
   status: z.number().nullable(),
   model: z.string().nullable(),
   provider: z.string().nullable(),
@@ -62,7 +62,7 @@ export const FailureClassificationSchema = z.object({
   severity: z.enum(["none", "low", "medium", "high"]),
   category: FailureCategorySchema,
   summary: z.string(),
-  evidenceLogIds: z.array(z.number().int().positive()),
+  evidenceLogIds: z.array(LogIdSchema),
   hints: z.array(z.string()),
 });
 

package/src/lib/sessionInfoContract.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { LogIdSchema } from "../contracts";
 
 export const SessionTokenUsageSchema = z.object({
   input: z.number().int().nonnegative(),
@@ -9,7 +10,7 @@ export const SessionTokenUsageSchema = z.object({
 });
 
 export const SessionLogSummarySchema = z.object({
-  id: z.number().int().positive(),
+  id: LogIdSchema,
   sessionLogNumber: z.number().int().positive().optional(),
   timestamp: z.string(),
   provider: z.string().nullable(),
@@ -57,7 +58,7 @@ export const SessionInfoSchema = z.object({
   models: z.array(z.string()),
   providers: z.array(z.string()),
   tokenUsage: SessionTokenUsageSchema,
-  lastLogId: z.number().nullable(),
+  lastLogId: LogIdSchema.nullable(),
   lastModel: z.string().nullable(),
   clientUserAgent: z.string().nullable().optional(),
   clientPid: z.number().nullable(),