@tonyclaw/agent-inspector 3.0.29 → 3.0.31

package/src/lib/piAgentContract.ts

@@ -1,11 +1,88 @@
 import { z } from "zod";
 
+export const PiAgentHistoryMessageSchema = z.object({
+  role: z.enum(["user", "assistant"]),
+  content: z.string().trim().min(1).max(4_000),
+});
+
+export const PiAgentEvidenceSourceSchema = z.enum([
+  "log",
+  "knowledge",
+  "alert",
+  "run",
+  "group",
+  "provider",
+]);
+
+export const PiAgentCountEntrySchema = z.object({
+  value: z.string(),
+  count: z.number().int().nonnegative(),
+});
+
+export const PiAgentSummarySchema = z.object({
+  matchedLogs: z.number().int().nonnegative(),
+  knowledgeMatched: z.number().int().nonnegative(),
+  failures: z.number().int().nonnegative(),
+  pending: z.number().int().nonnegative(),
+  sessions: z.number().int().nonnegative(),
+  models: z.array(PiAgentCountEntrySchema),
+  providers: z.array(PiAgentCountEntrySchema),
+  latency: z.object({
+    count: z.number().int().nonnegative(),
+    minMs: z.number().nullable(),
+    maxMs: z.number().nullable(),
+    averageMs: z.number().nullable(),
+  }),
+  tokens: z.object({
+    input: z.number().int().nonnegative(),
+    output: z.number().int().nonnegative(),
+    total: z.number().int().nonnegative(),
+  }),
+  sourceCounts: z.record(PiAgentEvidenceSourceSchema, z.number().int().nonnegative()),
+});
+
+export const PiAgentQueryStatsSchema = z.object({
+  scannedLogs: z.number().int().nonnegative(),
+  hydratedLogs: z.number().int().nonnegative(),
+  matchedLogs: z.number().int().nonnegative(),
+  scannedKnowledge: z.number().int().nonnegative(),
+  matchedKnowledge: z.number().int().nonnegative(),
+  returnedEvidence: z.number().int().nonnegative(),
+  truncated: z.boolean(),
+  durationMs: z.number().nonnegative(),
+});
+
+export const PiAgentEvidenceSchema = z.object({
+  source: PiAgentEvidenceSourceSchema,
+  id: z.string(),
+  logId: z.number().int().positive().optional(),
+  knowledgeId: z.string().optional(),
+  logIds: z.array(z.number().int().positive()).optional(),
+  timestamp: z.string().optional(),
+  sessionId: z.string().optional(),
+  model: z.string().optional(),
+  providerName: z.string().optional(),
+  path: z.string().optional(),
+  status: z.union([z.number(), z.string()]).nullable().optional(),
+  elapsedMs: z.number().optional(),
+  inputTokens: z.number().int().nonnegative().optional(),
+  outputTokens: z.number().int().nonnegative().optional(),
+  score: z.number(),
+  matchedFields: z.array(z.string()),
+  excerpt: z.string(),
+  entityType: z.string().optional(),
+  title: z.string().optional(),
+  knowledgeType: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+});
+
 export const PiAgentRequestSchema = z.object({
   question: z.string().trim().min(1).max(4_000),
   sessionId: z.string().trim().min(1).optional(),
   providerId: z.string().trim().min(1).optional(),
   model: z.string().trim().min(1).optional(),
   logLimit: z.number().int().min(1).max(80).optional(),
+  history: z.array(PiAgentHistoryMessageSchema).max(12).optional(),
 });
 
 export const PiAgentResponseSchema = z.object({
@@ -15,6 +92,9 @@ export const PiAgentResponseSchema = z.object({
   model: z.string(),
   protocol: z.enum(["openaiResponses", "openaiChat", "anthropic"]),
   logCount: z.number().int().nonnegative(),
+  evidence: z.array(PiAgentEvidenceSchema).optional(),
+  summary: PiAgentSummarySchema.optional(),
+  queryStats: PiAgentQueryStatsSchema.optional(),
 });
 
 export type PiAgentRequest = z.infer<typeof PiAgentRequestSchema>;

package/src/lib/providerContract.ts

@@ -1,4 +1,9 @@
 import { z } from "zod";
+import {
+  MAX_PROVIDER_MODEL_METADATA,
+  MAX_PROVIDER_MODEL_NAME_CHARS,
+  MAX_PROVIDER_MODELS,
+} from "./resourceLimits";
 
 /**
  * Validates that a string is a well-formed http(s) URL. Rejects non-HTTP
@@ -20,8 +25,11 @@ function httpUrl(): z.ZodString {
   }, "Must be a valid http(s) URL");
 }
 
+export const ProviderModelNameSchema = z.string().max(MAX_PROVIDER_MODEL_NAME_CHARS);
+export const ProviderModelsSchema = z.array(ProviderModelNameSchema).max(MAX_PROVIDER_MODELS);
+
 export const ProviderModelMetadataSchema = z.object({
-  model: z.string().min(1),
+  model: ProviderModelNameSchema.min(1),
   contextWindow: z.number().int().positive().optional(),
   outputLimit: z.number().int().positive().optional(),
   source: z.enum(["manual", "registry"]).optional(),
@@ -29,6 +37,10 @@ export const ProviderModelMetadataSchema = z.object({
   updatedAt: z.string().optional(),
 });
 
+export const ProviderModelMetadataListSchema = z
+  .array(ProviderModelMetadataSchema)
+  .max(MAX_PROVIDER_MODEL_METADATA);
+
 /**
  * Persisted provider shape shared by the server store and browser API clients.
  *
@@ -39,8 +51,8 @@ export const ProviderConfigSchema = z.object({
   id: z.string(),
   name: z.string(),
   apiKey: z.string(),
-  model: z.string().optional(),
-  models: z.array(z.string()).optional().default([]),
+  model: ProviderModelNameSchema.optional(),
+  models: ProviderModelsSchema.optional().default([]),
   format: z.enum(["anthropic", "openai"]).optional(),
   baseUrl: httpUrl().optional(),
   anthropicBaseUrl: httpUrl().optional(),
@@ -49,11 +61,65 @@ export const ProviderConfigSchema = z.object({
   authHeader: z.enum(["bearer", "x-api-key"]).optional().default("bearer"),
   apiDocsUrl: z.string().optional(),
   modelMetadataUrl: z.string().optional(),
-  modelMetadata: z.array(ProviderModelMetadataSchema).optional(),
+  modelMetadata: ProviderModelMetadataListSchema.optional(),
   source: z.enum(["company", "personal"]).optional(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
 
+export const REDACTED_PROVIDER_API_KEY = "configured";
+
+/**
+ * Secret-safe provider shape used at every API and tool output boundary.
+ *
+ * Keeping the marker in the existing `apiKey` field preserves compatibility
+ * with older browser clients while making plaintext provider credentials
+ * impossible to represent in a validated response.
+ */
+export const RedactedProviderDtoSchema = ProviderConfigSchema.extend({
+  apiKey: z.literal(REDACTED_PROVIDER_API_KEY),
+});
+
 export type ProviderModelMetadata = z.infer<typeof ProviderModelMetadataSchema>;
 export type ProviderConfig = z.infer<typeof ProviderConfigSchema>;
+export type RedactedProviderDto = z.infer<typeof RedactedProviderDtoSchema>;
+
+export type ProviderModelLimitViolation = {
+  resource: "provider-models" | "provider-model-metadata";
+  limit: number;
+};
+
+function arrayFieldLength(value: unknown, key: string): number | null {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+  const descriptor = Object.getOwnPropertyDescriptor(value, key);
+  if (descriptor === undefined) return null;
+  const field: unknown = descriptor.value;
+  return Array.isArray(field) ? field.length : null;
+}
+
+export function getProviderModelLimitViolation(value: unknown): ProviderModelLimitViolation | null {
+  const modelCount = arrayFieldLength(value, "models");
+  if (modelCount !== null && modelCount > MAX_PROVIDER_MODELS) {
+    return { resource: "provider-models", limit: MAX_PROVIDER_MODELS };
+  }
+
+  const metadataCount = arrayFieldLength(value, "modelMetadata");
+  if (metadataCount !== null && metadataCount > MAX_PROVIDER_MODEL_METADATA) {
+    return { resource: "provider-model-metadata", limit: MAX_PROVIDER_MODEL_METADATA };
+  }
+
+  return null;
+}
+
+export function toRedactedProviderDto(provider: ProviderConfig): RedactedProviderDto {
+  return {
+    ...provider,
+    apiKey: REDACTED_PROVIDER_API_KEY,
+  };
+}
+
+export function toRedactedProviderDtos(
+  providers: readonly ProviderConfig[],
+): RedactedProviderDto[] {
+  return providers.map(toRedactedProviderDto);
+}

package/src/lib/providerImportContract.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+
+export const ScannedProviderDtoSchema = z.object({
+  selectionId: z.string().uuid(),
+  name: z.string(),
+  apiKeyHint: z.string(),
+  format: z.enum(["anthropic", "openai"]),
+  anthropicBaseUrl: z.string(),
+  openaiBaseUrl: z.string(),
+  openaiResponsesBaseUrl: z.string().optional().default(""),
+  models: z.array(z.string()),
+  sourceTool: z.enum(["claude-code", "opencode", "mimo-code"]),
+  alreadyExists: z.boolean(),
+});
+
+export const ProviderScanResponseSchema = z.object({
+  scanId: z.string().uuid(),
+  providers: z.array(ScannedProviderDtoSchema),
+  warnings: z.array(z.string()).optional(),
+});
+
+export const ProviderScanImportRequestSchema = z.object({
+  scanId: z.string().uuid(),
+  selectionIds: z.array(z.string().uuid()).min(1).max(100),
+});
+
+export type ScannedProviderDto = z.infer<typeof ScannedProviderDtoSchema>;

package/src/lib/providerModelMetadata.ts

@@ -1,9 +1,14 @@
 import { z } from "zod";
 import type { ProviderConfig, ProviderModelMetadata } from "./providerContract";
+import { MAX_PROVIDER_MODEL_NAME_CHARS, MAX_PROVIDER_MODELS } from "./resourceLimits";
 
 export const ProviderRegistryModelSchema = z.object({
-  id: z.string().min(1),
-  aliases: z.array(z.string()).optional().default([]),
+  id: z.string().min(1).max(MAX_PROVIDER_MODEL_NAME_CHARS),
+  aliases: z
+    .array(z.string().max(MAX_PROVIDER_MODEL_NAME_CHARS))
+    .max(MAX_PROVIDER_MODELS)
+    .optional()
+    .default([]),
   contextWindow: z.number().int().positive().optional(),
   outputLimit: z.number().int().positive().optional(),
   sourceUrl: z.string().optional(),
@@ -11,16 +16,20 @@ export const ProviderRegistryModelSchema = z.object({
 
 export const ProviderRegistryProviderSchema = z.object({
   name: z.string().min(1).optional(),
-  aliases: z.array(z.string()).optional().default([]),
-  baseUrls: z.array(z.string()).optional().default([]),
-  models: z.array(ProviderRegistryModelSchema).min(1),
+  aliases: z.array(z.string()).max(MAX_PROVIDER_MODELS).optional().default([]),
+  baseUrls: z.array(z.string()).max(MAX_PROVIDER_MODELS).optional().default([]),
+  models: z.array(ProviderRegistryModelSchema).min(1).max(MAX_PROVIDER_MODELS),
 });
 
 export const ProviderModelRegistrySchema = z.object({
   version: z.number().int().positive().optional(),
   updatedAt: z.string().optional(),
-  providers: z.array(ProviderRegistryProviderSchema).optional().default([]),
-  models: z.array(ProviderRegistryModelSchema).optional().default([]),
+  providers: z
+    .array(ProviderRegistryProviderSchema)
+    .max(MAX_PROVIDER_MODELS)
+    .optional()
+    .default([]),
+  models: z.array(ProviderRegistryModelSchema).max(MAX_PROVIDER_MODELS).optional().default([]),
 });
 
 export type ProviderRegistryModel = z.infer<typeof ProviderRegistryModelSchema>;

package/src/lib/resourceLimits.ts

@@ -0,0 +1,152 @@
+import { z } from "zod";
+
+export const MAX_REST_LOG_PAGE_SIZE = 200;
+export const MAX_SEARCH_QUERY_CHARS = 512;
+export const MAX_SEARCH_PROJECT_CHARS = 256;
+export const MAX_PROVIDER_MODELS = 64;
+export const MAX_PROVIDER_MODEL_NAME_CHARS = 256;
+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 ResourceLimitErrorCodeSchema = z.enum([
+  "invalid-page-request",
+  "search-limit-exceeded",
+  "provider-model-limit-exceeded",
+  "sse-capacity-exceeded",
+  "provider-test-capacity-exceeded",
+]);
+
+export const ResourceLimitStatusSchema = z.union([
+  z.literal(400),
+  z.literal(413),
+  z.literal(429),
+  z.literal(503),
+]);
+
+export const ResourceLimitErrorSchema = z.object({
+  error: z.string().min(1).max(300),
+  code: ResourceLimitErrorCodeSchema,
+  status: ResourceLimitStatusSchema,
+  resource: z.string().min(1).max(80),
+  limit: z.number().int().positive(),
+  retryable: z.boolean(),
+});
+
+export type ResourceLimitErrorCode = z.infer<typeof ResourceLimitErrorCodeSchema>;
+export type ResourceLimitStatus = z.infer<typeof ResourceLimitStatusSchema>;
+export type ResourceLimitError = z.infer<typeof ResourceLimitErrorSchema>;
+
+export type ResourceLimitErrorInput = {
+  error: string;
+  code: ResourceLimitErrorCode;
+  status: ResourceLimitStatus;
+  resource: string;
+  limit: number;
+  retryable: boolean;
+};
+
+export function createResourceLimitError(input: ResourceLimitErrorInput): ResourceLimitError {
+  return ResourceLimitErrorSchema.parse(input);
+}
+
+export function resourceLimitResponse(
+  input: ResourceLimitErrorInput & { retryAfterSeconds?: number },
+): Response {
+  const body = createResourceLimitError(input);
+  const headers = new Headers({ "cache-control": "no-store" });
+  if (input.retryAfterSeconds !== undefined) {
+    headers.set("retry-after", String(input.retryAfterSeconds));
+  }
+  return Response.json(body, { status: input.status, headers });
+}
+
+type BoundedIntegerParameterInput = {
+  value: string | null;
+  parameter: string;
+  fallback: number;
+  minimum: number;
+  maximum: number;
+  resource: string;
+};
+
+export type BoundedIntegerParameterResult =
+  | { ok: true; value: number }
+  | { ok: false; response: Response };
+
+export function parseBoundedIntegerParameter(
+  input: BoundedIntegerParameterInput,
+): BoundedIntegerParameterResult {
+  if (input.value === null) return { ok: true, value: input.fallback };
+
+  const parsed = Number(input.value);
+  if (!Number.isSafeInteger(parsed) || parsed < input.minimum || parsed > input.maximum) {
+    return {
+      ok: false,
+      response: resourceLimitResponse({
+        error: `Query parameter "${input.parameter}" must be an integer between ${String(input.minimum)} and ${String(input.maximum)}.`,
+        code: "invalid-page-request",
+        status: 400,
+        resource: input.resource,
+        limit: input.maximum,
+        retryable: false,
+      }),
+    };
+  }
+
+  return { ok: true, value: parsed };
+}
+
+export type CapacityLease = {
+  release: () => void;
+};
+
+export type CapacityLimiter = {
+  tryAcquire: () => CapacityLease | null;
+  activeCount: () => number;
+  capacity: number;
+};
+
+export function createCapacityLimiter(maxActive: number): CapacityLimiter {
+  const capacity = Number.isSafeInteger(maxActive) && maxActive > 0 ? maxActive : 1;
+  let active = 0;
+
+  return {
+    capacity,
+    activeCount: () => active,
+    tryAcquire: () => {
+      if (active >= capacity) return null;
+      active += 1;
+      let released = false;
+      return {
+        release: () => {
+          if (released) return;
+          released = true;
+          active = Math.max(0, active - 1);
+        },
+      };
+    },
+  };
+}
+
+export async function runWithConcurrencyLimit(
+  tasks: readonly (() => Promise<void>)[],
+  maxConcurrent: number,
+): Promise<void> {
+  if (tasks.length === 0) return;
+  const concurrency = Number.isSafeInteger(maxConcurrent) && maxConcurrent > 0 ? maxConcurrent : 1;
+  const workerCount = Math.min(concurrency, tasks.length);
+  let nextIndex = 0;
+
+  const runWorker = async (): Promise<void> => {
+    while (nextIndex < tasks.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      const task = tasks[index];
+      if (task !== undefined) await task();
+    }
+  };
+
+  await Promise.all(Array.from({ length: workerCount }, runWorker));
+}

package/src/lib/safeDiagnostic.ts

@@ -0,0 +1,38 @@
+function normalizeScope(scope: string): string {
+  const normalized = scope
+    .toUpperCase()
+    .replaceAll(/[^A-Z0-9]+/g, "-")
+    .replaceAll(/^-+|-+$/g, "")
+    .slice(0, 24);
+  return normalized.length > 0 ? normalized : "UNKNOWN";
+}
+
+function errorKind(error: unknown): string {
+  if (error instanceof Error) {
+    return error.name;
+  }
+  return typeof error;
+}
+
+function shortHash(value: string): string {
+  let hash = 5381;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = (hash * 33 + value.charCodeAt(index)) % 2_176_782_336;
+  }
+  return Math.floor(hash).toString(36).toUpperCase().padStart(6, "0");
+}
+
+/**
+ * Creates an operator-friendly reference without encoding an error message,
+ * stack, captured content, headers, or credentials into the displayed value.
+ */
+export function createSafeDiagnosticReference(
+  scope: string,
+  error: unknown,
+  caughtAt: number = Date.now(),
+): string {
+  const safeScope = normalizeScope(scope);
+  const timePart = Math.max(0, Math.floor(caughtAt)).toString(36).toUpperCase();
+  const fingerprint = shortHash(`${safeScope}:${errorKind(error)}:${timePart}`);
+  return `AI-${safeScope}-${timePart}-${fingerprint}`;
+}

package/src/lib/useProviders.ts

@@ -1,18 +1,18 @@
 import useSWR, { type SWRResponse } from "swr";
 import { fetchJson } from "./apiClient";
-import { ProviderConfigSchema, type ProviderConfig } from "./providerContract";
+import { RedactedProviderDtoSchema, type RedactedProviderDto } from "./providerContract";
 
-async function fetcher(url: string): Promise<ProviderConfig[]> {
+async function fetcher(url: string): Promise<RedactedProviderDto[]> {
   return fetchJson(
     url,
-    ProviderConfigSchema.array(),
+    RedactedProviderDtoSchema.array(),
     undefined,
     (response) => `Failed to fetch ${url}: ${response.status}`,
   );
 }
 
 export function useProviders() {
-  const response: SWRResponse<ProviderConfig[], Error> = useSWR<ProviderConfig[], Error>(
+  const response: SWRResponse<RedactedProviderDto[], Error> = useSWR<RedactedProviderDto[], Error>(
     "/api/providers",
     fetcher,
     {

package/src/mcp/server.ts

@@ -35,6 +35,12 @@ import {
 import { InspectorRunStatusSchema, UpdateInspectorRunInputSchema } from "../lib/runContract";
 import { getCurrentPort, setCurrentPort } from "../lib/serverPort";
 import { JsonValueSchema } from "../contracts";
+import {
+  MAX_PROVIDER_MODEL_NAME_CHARS,
+  MAX_PROVIDER_MODELS,
+  MAX_SEARCH_PROJECT_CHARS,
+  MAX_SEARCH_QUERY_CHARS,
+} from "../lib/resourceLimits";
 import { getCurrentContext } from "./currentContext";
 import { getMcpModeInfo, isMcpWriteEnabled } from "./mode";
 import {
@@ -81,6 +87,7 @@ import {
   getLogImpl,
   getProviderImpl,
   listGroupsImpl,
+  LIMIT_HARD_CAP,
   listKnowledgeCandidatesImpl,
   listLogsImpl,
   listModelsImpl,
@@ -222,9 +229,15 @@ const AddProviderInputSchema = z
     model: z
       .string()
       .min(1)
+      .max(MAX_PROVIDER_MODEL_NAME_CHARS)
       .optional()
       .describe("Legacy single-model input. Prefer models for new clients."),
-    models: z.array(z.string().min(1)).min(1).optional().describe("Provider model names."),
+    models: z
+      .array(z.string().min(1).max(MAX_PROVIDER_MODEL_NAME_CHARS))
+      .min(1)
+      .max(MAX_PROVIDER_MODELS)
+      .optional()
+      .describe("Provider model names."),
     anthropicBaseUrl: z
       .string()
       .optional()
@@ -252,8 +265,17 @@ const UpdateProviderInputSchema = z.object({
   name: z.string().min(1).optional(),
   apiKey: z.string().min(1).optional(),
   format: z.enum(["anthropic", "openai"]).optional(),
-  model: z.string().min(1).optional().describe("Legacy single-model input. Prefer models."),
-  models: z.array(z.string().min(1)).optional().describe("Replace provider model names."),
+  model: z
+    .string()
+    .min(1)
+    .max(MAX_PROVIDER_MODEL_NAME_CHARS)
+    .optional()
+    .describe("Legacy single-model input. Prefer models."),
+  models: z
+    .array(z.string().min(1).max(MAX_PROVIDER_MODEL_NAME_CHARS))
+    .max(MAX_PROVIDER_MODELS)
+    .optional()
+    .describe("Replace provider model names."),
   baseUrl: z
     .string()
     .min(1)
@@ -694,6 +716,7 @@ function registerTools(server: McpServer): void {
           .number()
           .int()
           .positive()
+          .max(LIMIT_HARD_CAP)
           .optional()
           .describe("How many summaries to return. Hard-capped at 5."),
         sessionId: z.string().optional().describe("Filter by session/affinity id."),
@@ -718,6 +741,7 @@ function registerTools(server: McpServer): void {
       inputSchema: z.object({
         query: z
           .string()
+          .max(MAX_SEARCH_QUERY_CHARS)
           .optional()
           .describe("Search terms. Empty or omitted returns the newest scanned logs."),
         offset: z.number().int().nonnegative().optional().describe("Skip this many matches."),
@@ -725,6 +749,7 @@ function registerTools(server: McpServer): void {
           .number()
           .int()
           .positive()
+          .max(LIMIT_HARD_CAP)
           .optional()
           .describe("How many summaries to return. Hard-capped at 5 by the MCP handler."),
         scanLimit: z
@@ -1401,8 +1426,12 @@ PATCH-style update: only the fields you supply are changed. Use models to update
       description:
         "Searches knowledge through Inspector. OpenClaw backend details are hidden from the agent.",
       inputSchema: z.object({
-        query: z.string().min(1).describe("Knowledge search query."),
-        project: z.string().optional().describe("Optional project filter."),
+        query: z.string().min(1).max(MAX_SEARCH_QUERY_CHARS).describe("Knowledge search query."),
+        project: z
+          .string()
+          .max(MAX_SEARCH_PROJECT_CHARS)
+          .optional()
+          .describe("Optional project filter."),
       }),
     },
     (args) => safeCall(() => searchKnowledgeImpl(callApi, args)),
@@ -1415,7 +1444,11 @@ PATCH-style update: only the fields you supply are changed. Use models to update
       description:
         "Returns relevant Inspector knowledge for a project so an agent can seed task context without calling OpenClaw directly.",
       inputSchema: z.object({
-        project: z.string().min(1).describe("Project name or folder."),
+        project: z
+          .string()
+          .min(1)
+          .max(MAX_SEARCH_PROJECT_CHARS)
+          .describe("Project name or folder."),
       }),
     },
     (args) => safeCall(() => getProjectContextImpl(callApi, args)),