@tonyclaw/agent-inspector 4.0.1 → 4.0.3

package/src/services/piAgentRetrieval.ts

@@ -1,1180 +0,0 @@
-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,
-  };
-}