@tonyclaw/agent-inspector 3.0.29 → 3.0.31

package/src/services/piAgentRetrieval.ts

@@ -0,0 +1,1180 @@
+import type { CapturedLog } from "../contracts";
+import { listCandidates } from "../knowledge/candidateStore";
+import type { KnowledgeCandidate } from "../knowledge/types";
+import type { Alert } from "../lib/alertContract";
+import type { InspectorGroup } from "../lib/groupContract";
+import type { ProviderConfig } from "../lib/providerContract";
+import type { InspectorRun } from "../lib/runContract";
+import { listAlerts } from "../proxy/alerts";
+import { listGroups } from "../proxy/groupStore";
+import { getProviders } from "../proxy/providers";
+import { listRuns } from "../proxy/runStore";
+import {
+  getLogById,
+  listLogsPage,
+  type ListLogsPageOptions,
+  type ListLogsPageResult,
+} from "../proxy/store";
+
+export type PiAgentEvidenceSource = "log" | "knowledge" | "alert" | "run" | "group" | "provider";
+
+export type PiAgentCountEntry = {
+  value: string;
+  count: number;
+};
+
+export type PiAgentRetrievalSummary = {
+  matchedLogs: number;
+  knowledgeMatched: number;
+  failures: number;
+  pending: number;
+  sessions: number;
+  models: PiAgentCountEntry[];
+  providers: PiAgentCountEntry[];
+  latency: {
+    count: number;
+    minMs: number | null;
+    maxMs: number | null;
+    averageMs: number | null;
+  };
+  tokens: {
+    input: number;
+    output: number;
+    total: number;
+  };
+  sourceCounts: Record<PiAgentEvidenceSource, number>;
+};
+
+export type PiAgentQueryStats = {
+  scannedLogs: number;
+  hydratedLogs: number;
+  matchedLogs: number;
+  scannedKnowledge: number;
+  matchedKnowledge: number;
+  returnedEvidence: number;
+  truncated: boolean;
+  durationMs: number;
+};
+
+export type PiAgentEvidence = {
+  source: PiAgentEvidenceSource;
+  id: string;
+  logId?: number;
+  knowledgeId?: string;
+  logIds?: number[];
+  timestamp?: string;
+  sessionId?: string;
+  model?: string;
+  providerName?: string;
+  path?: string;
+  status?: number | string | null;
+  elapsedMs?: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  score: number;
+  matchedFields: string[];
+  excerpt: string;
+  entityType?: string;
+  title?: string;
+  knowledgeType?: string;
+  tags?: string[];
+};
+
+export type PiAgentRetrievalResult = {
+  summary: PiAgentRetrievalSummary;
+  queryStats: PiAgentQueryStats;
+  evidence: PiAgentEvidence[];
+};
+
+export type PiAgentRetrievalLimits = {
+  scanPageSize: number;
+  maxScannedLogs: number;
+  maxHydratedLogs: number;
+  maxEvidence: number;
+  maxExcerptChars: number;
+  maxKnowledgeCandidates: number;
+  maxAuxiliaryRecords: number;
+};
+
+export type PiAgentRetrievalInput = {
+  question: string;
+  sessionId?: string;
+  recentUserQuestion?: string;
+  limits?: Partial<PiAgentRetrievalLimits>;
+};
+
+export type PiAgentRetrievalDependencies = {
+  listLogPage: (options: ListLogsPageOptions) => Promise<ListLogsPageResult>;
+  getLog: (id: number) => Promise<CapturedLog | null>;
+  listKnowledgeCandidates: () => KnowledgeCandidate[];
+  listInspectorAlerts: () => Promise<Alert[]>;
+  listInspectorRuns: () => InspectorRun[];
+  listInspectorGroups: () => InspectorGroup[];
+  listInspectorProviders: () => ProviderConfig[];
+};
+
+type QueryIntents = {
+  failure: boolean;
+  pending: boolean;
+  performance: boolean;
+  tokens: boolean;
+  tools: boolean;
+  sessions: boolean;
+  overview: boolean;
+};
+
+type QueryPlan = {
+  phrase: string;
+  terms: string[];
+  intents: QueryIntents;
+};
+
+type SearchField = {
+  name: string;
+  text: string;
+  weight: number;
+};
+
+type ScoreResult = {
+  score: number;
+  matchedFields: string[];
+};
+
+type RankedLog = ScoreResult & {
+  log: CapturedLog;
+};
+
+type ScanResult = {
+  logs: CapturedLog[];
+  total: number;
+  truncated: boolean;
+};
+
+type SourceCandidate = {
+  evidence: PiAgentEvidence;
+  sortTimestamp: string;
+};
+
+const DEFAULT_LIMITS: PiAgentRetrievalLimits = {
+  scanPageSize: 250,
+  maxScannedLogs: 20_000,
+  maxHydratedLogs: 48,
+  maxEvidence: 16,
+  maxExcerptChars: 720,
+  maxKnowledgeCandidates: 5_000,
+  maxAuxiliaryRecords: 1_000,
+};
+
+const MAX_LIMITS: PiAgentRetrievalLimits = {
+  scanPageSize: 1_000,
+  maxScannedLogs: 100_000,
+  maxHydratedLogs: 100,
+  maxEvidence: 30,
+  maxExcerptChars: 1_200,
+  maxKnowledgeCandidates: 20_000,
+  maxAuxiliaryRecords: 5_000,
+};
+
+const ENGLISH_STOP_WORDS = new Set([
+  "a",
+  "an",
+  "and",
+  "are",
+  "be",
+  "did",
+  "do",
+  "does",
+  "for",
+  "from",
+  "how",
+  "i",
+  "in",
+  "is",
+  "it",
+  "me",
+  "of",
+  "on",
+  "or",
+  "the",
+  "this",
+  "to",
+  "was",
+  "were",
+  "what",
+  "when",
+  "where",
+  "which",
+  "who",
+  "why",
+  "with",
+]);
+
+const REFERENTIAL_MARKERS = [
+  "which one",
+  "that one",
+  "the former",
+  "the latter",
+  "it",
+  "哪个",
+  "那个",
+  "其中",
+  "它",
+  "这个",
+  "上述",
+];
+
+const INTENT_ALIASES = {
+  failure: [
+    "error",
+    "fail",
+    "failed",
+    "failure",
+    "exception",
+    "timeout",
+    "错误",
+    "失败",
+    "异常",
+    "超时",
+    "报错",
+  ],
+  pending: [
+    "pending",
+    "hang",
+    "hung",
+    "stuck",
+    "unfinished",
+    "未完成",
+    "没结束",
+    "卡住",
+    "挂起",
+    "无响应",
+  ],
+  performance: [
+    "slow",
+    "slowest",
+    "latency",
+    "performance",
+    "duration",
+    "耗时",
+    "延迟",
+    "性能",
+    "最慢",
+    "响应时间",
+  ],
+  tokens: ["token", "tokens", "cost", "usage", "消耗", "用量", "费用"],
+  tools: ["tool", "tools", "function call", "工具", "调用了什么"],
+  sessions: ["session", "sessions", "conversation", "会话", "对话"],
+  overview: [
+    "overview",
+    "summary",
+    "overall",
+    "aggregate",
+    "statistics",
+    "概览",
+    "汇总",
+    "总体",
+    "整体",
+    "统计",
+    "情况",
+  ],
+} satisfies Record<keyof QueryIntents, readonly string[]>;
+
+const SENSITIVE_KEY_PATTERN =
+  /^(?:raw[-_]?headers?|headers?|authorization|proxy[-_]?authorization|x[-_]?api[-_]?key|api[-_]?key|access[-_]?token|refresh[-_]?token|password|passwd|secret|cookie|set[-_]?cookie)$/i;
+
+async function defaultListAlerts(): Promise<Alert[]> {
+  const result = await listAlerts({ limit: 200, scanLimit: 2_000 });
+  return result.alerts;
+}
+
+const DEFAULT_DEPENDENCIES: PiAgentRetrievalDependencies = {
+  listLogPage: listLogsPage,
+  getLog: getLogById,
+  listKnowledgeCandidates: listCandidates,
+  listInspectorAlerts: defaultListAlerts,
+  listInspectorRuns: listRuns,
+  listInspectorGroups: listGroups,
+  listInspectorProviders: getProviders,
+};
+
+function clampLimit(value: number | undefined, fallback: number, maximum: number): number {
+  if (value === undefined || !Number.isInteger(value) || value < 1) return fallback;
+  return Math.min(value, maximum);
+}
+
+function resolveLimits(input: Partial<PiAgentRetrievalLimits> | undefined): PiAgentRetrievalLimits {
+  return {
+    scanPageSize: clampLimit(
+      input?.scanPageSize,
+      DEFAULT_LIMITS.scanPageSize,
+      MAX_LIMITS.scanPageSize,
+    ),
+    maxScannedLogs: clampLimit(
+      input?.maxScannedLogs,
+      DEFAULT_LIMITS.maxScannedLogs,
+      MAX_LIMITS.maxScannedLogs,
+    ),
+    maxHydratedLogs: clampLimit(
+      input?.maxHydratedLogs,
+      DEFAULT_LIMITS.maxHydratedLogs,
+      MAX_LIMITS.maxHydratedLogs,
+    ),
+    maxEvidence: clampLimit(input?.maxEvidence, DEFAULT_LIMITS.maxEvidence, MAX_LIMITS.maxEvidence),
+    maxExcerptChars: clampLimit(
+      input?.maxExcerptChars,
+      DEFAULT_LIMITS.maxExcerptChars,
+      MAX_LIMITS.maxExcerptChars,
+    ),
+    maxKnowledgeCandidates: clampLimit(
+      input?.maxKnowledgeCandidates,
+      DEFAULT_LIMITS.maxKnowledgeCandidates,
+      MAX_LIMITS.maxKnowledgeCandidates,
+    ),
+    maxAuxiliaryRecords: clampLimit(
+      input?.maxAuxiliaryRecords,
+      DEFAULT_LIMITS.maxAuxiliaryRecords,
+      MAX_LIMITS.maxAuxiliaryRecords,
+    ),
+  };
+}
+
+function replaceControlCharacters(value: string): string {
+  let output = "";
+  for (const character of value) {
+    const code = character.charCodeAt(0);
+    output += code <= 31 || (code >= 127 && code <= 159) ? " " : character;
+  }
+  return output;
+}
+
+function normalizeSearchText(value: string): string {
+  return replaceControlCharacters(value)
+    .normalize("NFKC")
+    .toLocaleLowerCase()
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function hasCjk(value: string): boolean {
+  return /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u.test(value);
+}
+
+function appendCjkTerms(segment: string, output: Set<string>): void {
+  const characters = [...segment];
+  if (characters.length > 1) output.add(segment);
+  for (const size of [2, 3]) {
+    for (let index = 0; index + size <= characters.length; index += 1) {
+      output.add(characters.slice(index, index + size).join(""));
+      if (output.size >= 64) return;
+    }
+  }
+}
+
+function extractTerms(value: string): string[] {
+  const output = new Set<string>();
+  for (const match of value.matchAll(/[\p{L}\p{N}][\p{L}\p{N}_.:/-]*/gu)) {
+    const token = match[0];
+    if (token.length < 2 || hasCjk(token) || ENGLISH_STOP_WORDS.has(token)) continue;
+    output.add(token);
+    if (output.size >= 64) return [...output];
+  }
+  for (const match of value.matchAll(
+    /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]+/gu,
+  )) {
+    appendCjkTerms(match[0], output);
+    if (output.size >= 64) break;
+  }
+  return [...output];
+}
+
+function hasAlias(value: string, aliases: readonly string[]): boolean {
+  return aliases.some((alias) => value.includes(alias));
+}
+
+function isReferential(value: string): boolean {
+  return REFERENTIAL_MARKERS.some((marker) => value.includes(marker));
+}
+
+function buildQueryPlan(input: PiAgentRetrievalInput): QueryPlan {
+  const current = normalizeSearchText(input.question.slice(0, 4_000));
+  const previous = normalizeSearchText(input.recentUserQuestion?.slice(0, 2_000) ?? "");
+  const retrievalText =
+    isReferential(current) && previous !== "" ? `${current} ${previous}` : current;
+  const terms = extractTerms(retrievalText);
+  return {
+    phrase: current.length >= 2 && current.length <= 240 ? current : "",
+    terms,
+    intents: {
+      failure: hasAlias(retrievalText, INTENT_ALIASES.failure),
+      pending: hasAlias(retrievalText, INTENT_ALIASES.pending),
+      performance: hasAlias(retrievalText, INTENT_ALIASES.performance),
+      tokens: hasAlias(retrievalText, INTENT_ALIASES.tokens),
+      tools: hasAlias(retrievalText, INTENT_ALIASES.tools),
+      sessions: hasAlias(retrievalText, INTENT_ALIASES.sessions),
+      overview: current === "" || hasAlias(retrievalText, INTENT_ALIASES.overview),
+    },
+  };
+}
+
+function scoreFields(query: QueryPlan, fields: readonly SearchField[]): ScoreResult {
+  let score = 0;
+  const matchedFields = new Set<string>();
+  for (const field of fields) {
+    const normalized = normalizeSearchText(field.text);
+    if (normalized === "") continue;
+    let matched = false;
+    if (query.phrase !== "" && normalized.includes(query.phrase)) {
+      score += field.weight * 3;
+      matched = true;
+    }
+    let termMatches = 0;
+    for (const term of query.terms) {
+      if (normalized.includes(term)) termMatches += 1;
+      if (termMatches >= 4) break;
+    }
+    if (termMatches > 0) {
+      score += field.weight * termMatches;
+      matched = true;
+    }
+    if (matched) matchedFields.add(field.name);
+  }
+  return { score, matchedFields: [...matchedFields] };
+}
+
+function addScore(result: ScoreResult, score: number, field: string): void {
+  result.score += score;
+  if (!result.matchedFields.includes(field)) result.matchedFields.push(field);
+}
+
+function isFailedLog(log: CapturedLog): boolean {
+  const hasError = log.error !== undefined && log.error !== null && log.error.trim() !== "";
+  return (log.responseStatus !== null && log.responseStatus >= 400) || hasError;
+}
+
+function scoreLogMetadata(log: CapturedLog, query: QueryPlan): ScoreResult {
+  const result = scoreFields(query, [
+    { name: "sessionId", text: log.sessionId ?? "", weight: 14 },
+    { name: "model", text: log.model ?? "", weight: 12 },
+    { name: "providerName", text: log.providerName ?? "", weight: 11 },
+    { name: "path", text: log.path, weight: 9 },
+    { name: "error", text: log.error ?? "", weight: 13 },
+    { name: "warnings", text: log.warnings?.join(" ") ?? "", weight: 10 },
+    { name: "responseStatus", text: log.responseStatus?.toString() ?? "pending", weight: 8 },
+    { name: "apiFormat", text: log.apiFormat, weight: 5 },
+    { name: "project", text: log.clientProjectFolder ?? "", weight: 4 },
+  ]);
+
+  if (query.intents.failure && isFailedLog(log)) addScore(result, 24, "failure");
+  if (query.intents.failure && (log.warnings?.length ?? 0) > 0) {
+    addScore(result, 12, "warnings");
+  }
+  if (query.intents.pending && log.responseStatus === null) addScore(result, 28, "pending");
+  if (query.intents.performance && log.elapsedMs !== null) {
+    addScore(result, 4 + Math.min(18, Math.log2(Math.max(1, log.elapsedMs))), "elapsedMs");
+  }
+  if (query.intents.tokens && (log.inputTokens !== null || log.outputTokens !== null)) {
+    addScore(result, 8, "tokens");
+  }
+  if (query.intents.tools) addScore(result, 1, "toolTraceCandidate");
+  if (query.intents.sessions && log.sessionId !== null) addScore(result, 3, "sessionId");
+  if (query.intents.overview) addScore(result, 1, "overviewScope");
+  return result;
+}
+
+function scoreHydratedLog(log: CapturedLog, query: QueryPlan): ScoreResult {
+  const metadata = scoreLogMetadata(log, query);
+  const bodies = scoreFields(query, [
+    { name: "requestBody", text: log.rawRequestBody ?? "", weight: 9 },
+    { name: "responseBody", text: log.responseText ?? "", weight: 8 },
+  ]);
+  for (const field of bodies.matchedFields) {
+    if (!metadata.matchedFields.includes(field)) metadata.matchedFields.push(field);
+  }
+  metadata.score += bodies.score;
+  return metadata;
+}
+
+function compareRankedLogs(left: RankedLog, right: RankedLog): number {
+  return (
+    right.score - left.score ||
+    right.log.timestamp.localeCompare(left.log.timestamp) ||
+    right.log.id - left.log.id
+  );
+}
+
+async function scanLogs(
+  input: PiAgentRetrievalInput,
+  limits: PiAgentRetrievalLimits,
+  dependencies: PiAgentRetrievalDependencies,
+): Promise<ScanResult> {
+  const logsById = new Map<number, CapturedLog>();
+  let offset = 0;
+  let knownTotal = 0;
+  let truncated = false;
+  while (offset < limits.maxScannedLogs) {
+    const limit = Math.min(limits.scanPageSize, limits.maxScannedLogs - offset);
+    let page: ListLogsPageResult;
+    try {
+      page = await dependencies.listLogPage({
+        sessionId: input.sessionId,
+        offset,
+        limit,
+        includeBodies: false,
+      });
+    } catch {
+      truncated = true;
+      break;
+    }
+    knownTotal = page.total;
+    for (const log of page.logs) logsById.set(log.id, log);
+    offset += page.logs.length;
+    if (page.logs.length === 0 || offset >= page.total) break;
+  }
+  if (knownTotal > logsById.size) truncated = true;
+  return {
+    logs: [...logsById.values()],
+    total: Math.max(knownTotal, logsById.size),
+    truncated,
+  };
+}
+
+async function readLogSafely(
+  id: number,
+  dependencies: PiAgentRetrievalDependencies,
+): Promise<CapturedLog | null> {
+  try {
+    return await dependencies.getLog(id);
+  } catch {
+    return null;
+  }
+}
+
+async function hydrateRankedLogs(
+  ranked: readonly RankedLog[],
+  query: QueryPlan,
+  limits: PiAgentRetrievalLimits,
+  dependencies: PiAgentRetrievalDependencies,
+): Promise<{ ranked: RankedLog[]; hydrated: number }> {
+  const hydrationPool = ranked.slice(0, limits.maxHydratedLogs);
+  const hydratedById = new Map<number, RankedLog>();
+  let hydrated = 0;
+  for (let offset = 0; offset < hydrationPool.length; offset += 8) {
+    const batch = hydrationPool.slice(offset, offset + 8);
+    const logs = await Promise.all(
+      batch.map(async (candidate) => readLogSafely(candidate.log.id, dependencies)),
+    );
+    for (const log of logs) {
+      if (log === null) continue;
+      hydrated += 1;
+      hydratedById.set(log.id, { log, ...scoreHydratedLog(log, query) });
+    }
+  }
+  return {
+    ranked: ranked
+      .map((candidate) => hydratedById.get(candidate.log.id) ?? candidate)
+      .sort(compareRankedLogs),
+    hydrated,
+  };
+}
+
+function sanitizeUnknown(value: unknown, depth = 0): unknown {
+  if (depth > 6) return "[bounded]";
+  if (value === null || typeof value === "boolean" || typeof value === "number") return value;
+  if (typeof value === "string") return sanitizeText(value);
+  if (Array.isArray(value))
+    return value.slice(0, 40).map((item) => sanitizeUnknown(item, depth + 1));
+  if (typeof value !== "object") return String(value);
+
+  const output: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(value).slice(0, 60)) {
+    if (SENSITIVE_KEY_PATTERN.test(key)) continue;
+    output[key] = sanitizeUnknown(child, depth + 1);
+  }
+  return output;
+}
+
+function sanitizeText(value: string): string {
+  return replaceControlCharacters(value)
+    .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, "[REDACTED]")
+    .replace(/\bsk-[A-Za-z0-9_-]{6,}/gi, "[REDACTED]")
+    .replace(
+      /\b(?:raw[-_]?headers?|headers?|authorization|proxy[-_]?authorization|x[-_]?api[-_]?key|api[-_]?key|access[-_]?token|refresh[-_]?token|password|passwd|secret|cookie|set[-_]?cookie)\b\s*[=:]\s*(?:"[^"]*"|'[^']*'|[^\s,;}]+)/gi,
+      "[REDACTED]",
+    )
+    .replace(
+      /\b(?:rawheaders|headers|authorization|proxy-authorization|x-api-key|apikey|api_key|access_token|refresh_token)\b/gi,
+      "[sensitive-field]",
+    )
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function sanitizePiAgentEvidenceText(value: string): string {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    return sanitizeText(JSON.stringify(sanitizeUnknown(parsed)));
+  } catch {
+    return sanitizeText(value);
+  }
+}
+
+function excerptAroundTerms(value: string, query: QueryPlan, maxLength: number): string {
+  const sanitized = sanitizePiAgentEvidenceText(value);
+  if (sanitized.length <= maxLength) return sanitized;
+  const normalized = normalizeSearchText(sanitized);
+  const anchors = query.phrase === "" ? query.terms : [query.phrase, ...query.terms];
+  let matchIndex = -1;
+  for (const anchor of anchors) {
+    matchIndex = normalized.indexOf(anchor);
+    if (matchIndex >= 0) break;
+  }
+  const start = matchIndex < 0 ? 0 : Math.max(0, matchIndex - Math.floor(maxLength / 3));
+  const end = Math.min(sanitized.length, start + maxLength);
+  return `${start > 0 ? "…" : ""}${sanitized.slice(start, end)}${end < sanitized.length ? "…" : ""}`;
+}
+
+function firstMatchingBody(log: CapturedLog, matchedFields: readonly string[]): string | null {
+  if (matchedFields.includes("requestBody") && log.rawRequestBody !== null) {
+    return log.rawRequestBody;
+  }
+  if (matchedFields.includes("responseBody") && log.responseText !== null) {
+    return log.responseText;
+  }
+  if (log.error !== undefined && log.error !== null && log.error.trim() !== "") return log.error;
+  if (log.warnings !== undefined && log.warnings.length > 0) return log.warnings.join(" | ");
+  return null;
+}
+
+function logExcerpt(
+  log: CapturedLog,
+  candidate: RankedLog,
+  query: QueryPlan,
+  maxLength: number,
+): string {
+  const body = firstMatchingBody(log, candidate.matchedFields);
+  if (body !== null) return excerptAroundTerms(body, query, maxLength);
+  const metadata = [
+    `Log ${String(log.id)}`,
+    `session ${log.sessionId ?? "unknown"}`,
+    `model ${log.model ?? "unknown"}`,
+    `provider ${log.providerName ?? "unknown"}`,
+    `path ${log.path}`,
+    `status ${log.responseStatus?.toString() ?? "pending"}`,
+    `elapsed ${log.elapsedMs?.toString() ?? "unknown"} ms`,
+  ].join(" · ");
+  return excerptAroundTerms(metadata, query, maxLength);
+}
+
+function logEvidence(
+  candidate: RankedLog,
+  query: QueryPlan,
+  maxExcerptChars: number,
+): PiAgentEvidence {
+  const log = candidate.log;
+  return {
+    source: "log",
+    id: String(log.id),
+    logId: log.id,
+    timestamp: log.timestamp,
+    sessionId: log.sessionId ?? undefined,
+    model: log.model ?? undefined,
+    providerName: log.providerName ?? undefined,
+    path: log.path,
+    status: log.responseStatus,
+    elapsedMs: log.elapsedMs ?? undefined,
+    inputTokens: log.inputTokens ?? undefined,
+    outputTokens: log.outputTokens ?? undefined,
+    score: Math.round(candidate.score * 100) / 100,
+    matchedFields: candidate.matchedFields,
+    excerpt: logExcerpt(log, candidate, query, maxExcerptChars),
+    entityType: "log",
+    title: `Log #${String(log.id)}`,
+  };
+}
+
+function safeMetadataText(value: Record<string, unknown>): string {
+  return sanitizeText(JSON.stringify(sanitizeUnknown(value)));
+}
+
+function scoreKnowledge(candidate: KnowledgeCandidate, query: QueryPlan): ScoreResult {
+  const result = scoreFields(query, [
+    { name: "knowledgeId", text: candidate.id, weight: 10 },
+    { name: "title", text: candidate.title, weight: 12 },
+    { name: "content", text: candidate.content, weight: 9 },
+    { name: "tags", text: candidate.tags.join(" "), weight: 8 },
+    { name: "knowledgeType", text: candidate.type, weight: 6 },
+    { name: "knowledgeStatus", text: candidate.status, weight: 5 },
+    { name: "sessionId", text: candidate.sessionId, weight: 10 },
+    { name: "logIds", text: candidate.logIds.join(" "), weight: 4 },
+  ]);
+  if (query.intents.failure && candidate.status === "failed") {
+    addScore(result, 12, "knowledgeStatus");
+  }
+  if (query.intents.overview) addScore(result, 1, "overviewScope");
+  return result;
+}
+
+function knowledgeEvidence(
+  candidate: KnowledgeCandidate,
+  score: ScoreResult,
+  query: QueryPlan,
+  maxExcerptChars: number,
+): PiAgentEvidence {
+  return {
+    source: "knowledge",
+    id: candidate.id,
+    knowledgeId: candidate.id,
+    logIds: candidate.logIds,
+    timestamp: candidate.updatedAt,
+    sessionId: candidate.sessionId,
+    status: candidate.status,
+    score: Math.round(score.score * 100) / 100,
+    matchedFields: score.matchedFields,
+    excerpt: excerptAroundTerms(
+      `${candidate.title}. ${candidate.content}. Tags: ${candidate.tags.join(", ")}`,
+      query,
+      maxExcerptChars,
+    ),
+    entityType: "knowledge-candidate",
+    title: sanitizeText(candidate.title),
+    knowledgeType: candidate.type,
+    tags: candidate.tags
+      .map(sanitizeText)
+      .filter((tag) => tag !== "")
+      .slice(0, 20),
+  };
+}
+
+function scoreAlert(alert: Alert, query: QueryPlan): ScoreResult {
+  const result = scoreFields(query, [
+    { name: "alertId", text: alert.id, weight: 9 },
+    { name: "title", text: alert.title, weight: 11 },
+    { name: "message", text: alert.message, weight: 10 },
+    { name: "category", text: alert.category, weight: 8 },
+    { name: "severity", text: alert.severity, weight: 7 },
+    { name: "sessionId", text: alert.sessionIds.join(" "), weight: 9 },
+    { name: "providerName", text: alert.provider ?? "", weight: 8 },
+    { name: "model", text: alert.model ?? "", weight: 8 },
+    { name: "metadata", text: safeMetadataText(alert.metadata), weight: 3 },
+  ]);
+  if (query.intents.failure) addScore(result, alert.severity === "critical" ? 18 : 10, "alert");
+  if (query.intents.performance && alert.category === "slow-response") {
+    addScore(result, 16, "category");
+  }
+  if (query.intents.overview) addScore(result, 1, "overviewScope");
+  return result;
+}
+
+function alertEvidence(
+  alert: Alert,
+  score: ScoreResult,
+  query: QueryPlan,
+  maxExcerptChars: number,
+): PiAgentEvidence {
+  return {
+    source: "alert",
+    id: alert.id,
+    logIds: alert.logIds,
+    timestamp: alert.lastSeenAt,
+    sessionId: alert.sessionIds[0],
+    model: alert.model ?? undefined,
+    providerName: alert.provider ?? undefined,
+    status: alert.status,
+    score: Math.round(score.score * 100) / 100,
+    matchedFields: score.matchedFields,
+    excerpt: excerptAroundTerms(`${alert.title}. ${alert.message}`, query, maxExcerptChars),
+    entityType: alert.category,
+    title: sanitizeText(alert.title),
+  };
+}
+
+function scoreRun(run: InspectorRun, query: QueryPlan): ScoreResult {
+  const result = scoreFields(query, [
+    { name: "runId", text: run.id, weight: 10 },
+    { name: "sessionId", text: run.sessionId, weight: 11 },
+    { name: "title", text: run.title, weight: 10 },
+    { name: "task", text: run.task ?? "", weight: 9 },
+    { name: "project", text: run.project ?? "", weight: 7 },
+    { name: "agent", text: run.agent ?? "", weight: 7 },
+    { name: "status", text: run.status, weight: 7 },
+    { name: "tags", text: run.tags.join(" "), weight: 7 },
+    { name: "metadata", text: safeMetadataText(run.metadata), weight: 3 },
+  ]);
+  if (query.intents.failure && run.status === "failed") addScore(result, 18, "status");
+  if (query.intents.pending && (run.status === "created" || run.status === "running")) {
+    addScore(result, 14, "status");
+  }
+  if (query.intents.overview) addScore(result, 1, "overviewScope");
+  return result;
+}
+
+function runEvidence(
+  run: InspectorRun,
+  score: ScoreResult,
+  query: QueryPlan,
+  maxExcerptChars: number,
+): PiAgentEvidence {
+  return {
+    source: "run",
+    id: run.id,
+    timestamp: run.updatedAt,
+    sessionId: run.sessionId,
+    status: run.status,
+    score: Math.round(score.score * 100) / 100,
+    matchedFields: score.matchedFields,
+    excerpt: excerptAroundTerms(
+      `${run.title}. ${run.task ?? ""} Project: ${run.project ?? "unknown"}. Agent: ${run.agent ?? "unknown"}`,
+      query,
+      maxExcerptChars,
+    ),
+    entityType: "run",
+    title: sanitizeText(run.title),
+    tags: run.tags
+      .map(sanitizeText)
+      .filter((tag) => tag !== "")
+      .slice(0, 20),
+  };
+}
+
+function groupSessions(group: InspectorGroup): string[] {
+  return [...new Set(group.members.map((member) => member.sessionId))];
+}
+
+function scoreGroup(group: InspectorGroup, query: QueryPlan): ScoreResult {
+  const result = scoreFields(query, [
+    { name: "groupId", text: group.id, weight: 10 },
+    { name: "title", text: group.title, weight: 10 },
+    { name: "task", text: group.task ?? "", weight: 9 },
+    { name: "project", text: group.project ?? "", weight: 7 },
+    { name: "status", text: group.status, weight: 7 },
+    { name: "tags", text: group.tags.join(" "), weight: 7 },
+    { name: "sessionId", text: groupSessions(group).join(" "), weight: 9 },
+    { name: "metadata", text: safeMetadataText(group.metadata), weight: 3 },
+  ]);
+  if (query.intents.failure && group.status === "failed") addScore(result, 18, "status");
+  if (query.intents.pending && (group.status === "created" || group.status === "running")) {
+    addScore(result, 14, "status");
+  }
+  if (query.intents.overview) addScore(result, 1, "overviewScope");
+  return result;
+}
+
+function groupEvidence(
+  group: InspectorGroup,
+  score: ScoreResult,
+  query: QueryPlan,
+  maxExcerptChars: number,
+): PiAgentEvidence {
+  return {
+    source: "group",
+    id: group.id,
+    timestamp: group.updatedAt,
+    sessionId: groupSessions(group)[0],
+    status: group.status,
+    score: Math.round(score.score * 100) / 100,
+    matchedFields: score.matchedFields,
+    excerpt: excerptAroundTerms(
+      `${group.title}. ${group.task ?? ""} Project: ${group.project ?? "unknown"}. Members: ${String(group.members.length)}`,
+      query,
+      maxExcerptChars,
+    ),
+    entityType: "group",
+    title: sanitizeText(group.title),
+    tags: group.tags
+      .map(sanitizeText)
+      .filter((tag) => tag !== "")
+      .slice(0, 20),
+  };
+}
+
+function scoreProvider(provider: ProviderConfig, query: QueryPlan): ScoreResult {
+  const result = scoreFields(query, [
+    { name: "providerId", text: provider.id, weight: 10 },
+    { name: "providerName", text: provider.name, weight: 12 },
+    { name: "model", text: provider.models.join(" "), weight: 10 },
+    { name: "providerSource", text: provider.source ?? "", weight: 5 },
+    { name: "apiFormat", text: provider.format ?? "", weight: 5 },
+  ]);
+  if (query.intents.overview) addScore(result, 1, "overviewScope");
+  return result;
+}
+
+function providerEvidence(
+  provider: ProviderConfig,
+  score: ScoreResult,
+  query: QueryPlan,
+  maxExcerptChars: number,
+): PiAgentEvidence {
+  return {
+    source: "provider",
+    id: provider.id,
+    timestamp: provider.updatedAt,
+    providerName: provider.name,
+    status: "configured",
+    score: Math.round(score.score * 100) / 100,
+    matchedFields: score.matchedFields,
+    excerpt: excerptAroundTerms(
+      `Provider ${provider.name}. Models: ${provider.models.join(", ") || "none"}. Source: ${provider.source ?? "unknown"}. Format: ${provider.format ?? "mixed"}.`,
+      query,
+      maxExcerptChars,
+    ),
+    entityType: "provider",
+    title: sanitizeText(provider.name),
+  };
+}
+
+function readSyncStore<T>(reader: () => T[]): T[] {
+  try {
+    return reader();
+  } catch {
+    return [];
+  }
+}
+
+async function readAlertsStore(reader: () => Promise<Alert[]>): Promise<Alert[]> {
+  try {
+    return await reader();
+  } catch {
+    return [];
+  }
+}
+
+function sessionMatches(
+  candidateSessionIds: readonly string[],
+  sessionId: string | undefined,
+): boolean {
+  return sessionId === undefined || candidateSessionIds.includes(sessionId);
+}
+
+function collectKnowledgeCandidates(
+  candidates: readonly KnowledgeCandidate[],
+  input: PiAgentRetrievalInput,
+  query: QueryPlan,
+  limits: PiAgentRetrievalLimits,
+): SourceCandidate[] {
+  const output: SourceCandidate[] = [];
+  for (const candidate of candidates.slice(0, limits.maxKnowledgeCandidates)) {
+    if (!sessionMatches([candidate.sessionId], input.sessionId)) continue;
+    const score = scoreKnowledge(candidate, query);
+    if (score.score <= 0) continue;
+    output.push({
+      evidence: knowledgeEvidence(candidate, score, query, limits.maxExcerptChars),
+      sortTimestamp: candidate.updatedAt,
+    });
+  }
+  return output;
+}
+
+function collectAlertCandidates(
+  alerts: readonly Alert[],
+  input: PiAgentRetrievalInput,
+  query: QueryPlan,
+  limits: PiAgentRetrievalLimits,
+): SourceCandidate[] {
+  const output: SourceCandidate[] = [];
+  for (const alert of alerts.slice(0, limits.maxAuxiliaryRecords)) {
+    if (!sessionMatches(alert.sessionIds, input.sessionId)) continue;
+    const score = scoreAlert(alert, query);
+    if (score.score <= 0) continue;
+    output.push({
+      evidence: alertEvidence(alert, score, query, limits.maxExcerptChars),
+      sortTimestamp: alert.lastSeenAt,
+    });
+  }
+  return output;
+}
+
+function collectRunCandidates(
+  runs: readonly InspectorRun[],
+  input: PiAgentRetrievalInput,
+  query: QueryPlan,
+  limits: PiAgentRetrievalLimits,
+): SourceCandidate[] {
+  const output: SourceCandidate[] = [];
+  for (const run of runs.slice(0, limits.maxAuxiliaryRecords)) {
+    if (!sessionMatches([run.sessionId], input.sessionId)) continue;
+    const score = scoreRun(run, query);
+    if (score.score <= 0) continue;
+    output.push({
+      evidence: runEvidence(run, score, query, limits.maxExcerptChars),
+      sortTimestamp: run.updatedAt,
+    });
+  }
+  return output;
+}
+
+function collectGroupCandidates(
+  groups: readonly InspectorGroup[],
+  input: PiAgentRetrievalInput,
+  query: QueryPlan,
+  limits: PiAgentRetrievalLimits,
+): SourceCandidate[] {
+  const output: SourceCandidate[] = [];
+  for (const group of groups.slice(0, limits.maxAuxiliaryRecords)) {
+    const sessions = groupSessions(group);
+    if (!sessionMatches(sessions, input.sessionId)) continue;
+    const score = scoreGroup(group, query);
+    if (score.score <= 0) continue;
+    output.push({
+      evidence: groupEvidence(group, score, query, limits.maxExcerptChars),
+      sortTimestamp: group.updatedAt,
+    });
+  }
+  return output;
+}
+
+function collectProviderCandidates(
+  providers: readonly ProviderConfig[],
+  input: PiAgentRetrievalInput,
+  query: QueryPlan,
+  limits: PiAgentRetrievalLimits,
+): SourceCandidate[] {
+  if (input.sessionId !== undefined) return [];
+  const output: SourceCandidate[] = [];
+  for (const provider of providers.slice(0, limits.maxAuxiliaryRecords)) {
+    const score = scoreProvider(provider, query);
+    if (score.score <= 0) continue;
+    output.push({
+      evidence: providerEvidence(provider, score, query, limits.maxExcerptChars),
+      sortTimestamp: provider.updatedAt,
+    });
+  }
+  return output;
+}
+
+function countValues(values: readonly (string | null | undefined)[]): PiAgentCountEntry[] {
+  const counts = new Map<string, number>();
+  for (const value of values) {
+    if (value === null || value === undefined || value.trim() === "") continue;
+    counts.set(value, (counts.get(value) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .map(([value, count]) => ({ value, count }))
+    .sort((left, right) => right.count - left.count || left.value.localeCompare(right.value));
+}
+
+function sourceCounts(
+  candidates: readonly SourceCandidate[],
+): Record<PiAgentEvidenceSource, number> {
+  const counts: Record<PiAgentEvidenceSource, number> = {
+    log: 0,
+    knowledge: 0,
+    alert: 0,
+    run: 0,
+    group: 0,
+    provider: 0,
+  };
+  for (const candidate of candidates) {
+    counts[candidate.evidence.source] += 1;
+  }
+  return counts;
+}
+
+function summarize(
+  logs: readonly RankedLog[],
+  candidates: readonly SourceCandidate[],
+): PiAgentRetrievalSummary {
+  const matchedLogs = logs
+    .filter((candidate) => candidate.score > 0)
+    .map((candidate) => candidate.log);
+  const latencies = matchedLogs
+    .map((log) => log.elapsedMs)
+    .filter((value): value is number => value !== null && Number.isFinite(value));
+  const latencyTotal = latencies.reduce((sum, value) => sum + value, 0);
+  const input = matchedLogs.reduce((sum, log) => sum + (log.inputTokens ?? 0), 0);
+  const output = matchedLogs.reduce((sum, log) => sum + (log.outputTokens ?? 0), 0);
+  const counts = sourceCounts(candidates);
+  return {
+    matchedLogs: matchedLogs.length,
+    knowledgeMatched: counts.knowledge,
+    failures: matchedLogs.filter(isFailedLog).length,
+    pending: matchedLogs.filter((log) => log.responseStatus === null).length,
+    sessions: new Set(
+      matchedLogs
+        .map((log) => log.sessionId)
+        .filter((sessionId): sessionId is string => sessionId !== null),
+    ).size,
+    models: countValues(matchedLogs.map((log) => log.model)),
+    providers: countValues(matchedLogs.map((log) => log.providerName)),
+    latency: {
+      count: latencies.length,
+      minMs: latencies.length > 0 ? Math.min(...latencies) : null,
+      maxMs: latencies.length > 0 ? Math.max(...latencies) : null,
+      averageMs:
+        latencies.length > 0 ? Math.round((latencyTotal / latencies.length) * 100) / 100 : null,
+    },
+    tokens: { input, output, total: input + output },
+    sourceCounts: counts,
+  };
+}
+
+function compareSourceCandidates(left: SourceCandidate, right: SourceCandidate): number {
+  return (
+    right.evidence.score - left.evidence.score ||
+    right.sortTimestamp.localeCompare(left.sortTimestamp) ||
+    left.evidence.id.localeCompare(right.evidence.id)
+  );
+}
+
+export async function retrievePiAgentEvidence(
+  input: PiAgentRetrievalInput,
+  dependencies: PiAgentRetrievalDependencies = DEFAULT_DEPENDENCIES,
+): Promise<PiAgentRetrievalResult> {
+  const startedAt = Date.now();
+  const limits = resolveLimits(input.limits);
+  const query = buildQueryPlan(input);
+  const [scan, alerts] = await Promise.all([
+    scanLogs(input, limits, dependencies),
+    readAlertsStore(dependencies.listInspectorAlerts),
+  ]);
+  const knowledge = readSyncStore(dependencies.listKnowledgeCandidates);
+  const runs = readSyncStore(dependencies.listInspectorRuns);
+  const groups = readSyncStore(dependencies.listInspectorGroups);
+  const providers = readSyncStore(dependencies.listInspectorProviders);
+
+  const metadataRanked = scan.logs
+    .map((log): RankedLog => ({ log, ...scoreLogMetadata(log, query) }))
+    .sort(compareRankedLogs);
+  const hydrated = await hydrateRankedLogs(metadataRanked, query, limits, dependencies);
+  const matchedLogs = hydrated.ranked.filter((candidate) => candidate.score > 0);
+  const logCandidates: SourceCandidate[] = matchedLogs.map((candidate) => ({
+    evidence: logEvidence(candidate, query, limits.maxExcerptChars),
+    sortTimestamp: candidate.log.timestamp,
+  }));
+  const auxiliaryCandidates = [
+    ...collectKnowledgeCandidates(knowledge, input, query, limits),
+    ...collectAlertCandidates(alerts, input, query, limits),
+    ...collectRunCandidates(runs, input, query, limits),
+    ...collectGroupCandidates(groups, input, query, limits),
+    ...collectProviderCandidates(providers, input, query, limits),
+  ];
+  const allCandidates = [...logCandidates, ...auxiliaryCandidates].sort(compareSourceCandidates);
+  const evidence = allCandidates
+    .slice(0, limits.maxEvidence)
+    .map((candidate) => candidate.evidence);
+  const matchedKnowledge = auxiliaryCandidates.filter(
+    (candidate) => candidate.evidence.source === "knowledge",
+  ).length;
+  const boundedSource =
+    knowledge.length > limits.maxKnowledgeCandidates ||
+    alerts.length > limits.maxAuxiliaryRecords ||
+    runs.length > limits.maxAuxiliaryRecords ||
+    groups.length > limits.maxAuxiliaryRecords ||
+    providers.length > limits.maxAuxiliaryRecords;
+  const truncated = scan.truncated || boundedSource || allCandidates.length > limits.maxEvidence;
+
+  return {
+    summary: summarize(hydrated.ranked, allCandidates),
+    queryStats: {
+      scannedLogs: scan.logs.length,
+      hydratedLogs: hydrated.hydrated,
+      matchedLogs: matchedLogs.length,
+      scannedKnowledge: Math.min(knowledge.length, limits.maxKnowledgeCandidates),
+      matchedKnowledge,
+      returnedEvidence: evidence.length,
+      truncated,
+      durationMs: Math.max(0, Date.now() - startedAt),
+    },
+    evidence,
+  };
+}