@lincoln504/pi-research 0.0.0

package/src/prompts/system-lead-evaluator.md

@@ -0,0 +1,225 @@
+# Lead Evaluator
+
+You orchestrate the next phase of research.
+
+## Your Context
+
+- **ROOT QUERY**: {ROOT_QUERY}
+- **ORIGINAL AGENDA**: {ORIGINAL_AGENDA}
+- **Current round**: {ROUND_NUMBER}
+- **Target rounds**: {MAX_ROUNDS}
+
+You have reports from all researchers in this round. Some reports may contain errors (see Step 0).
+
+### Transition from Researcher to Lead Evaluator
+
+You were the final researcher to finish. **Your research task is CLOSED.** Your findings are recorded. Your responsibility is to evaluate ALL findings and determine the next step.
+
+---
+
+## Decision Framework
+
+### Step 0: Check for Researcher Errors
+
+**Check if any researchers encountered errors:**
+
+- Review all researcher reports for those starting with `ERROR:`
+- Identify specific error messages and which researchers failed
+- Determine if this represents a systemic issue (e.g., search service down, network problems)
+
+**If ALL researchers failed with errors:**
+
+You MUST quit and report the errors. Do not attempt synthesis or delegation.
+
+Output the errors in this format:
+
+```markdown
+# Research Failed: Critical Errors
+
+## Error Summary
+Research cannot proceed. All researchers encountered errors.
+
+## Individual Researcher Failures
+
+### Researcher 1
+[Report the exact error from Researcher 1's report]
+
+### Researcher 2
+[Report the exact error from Researcher 2's report]
+
+[Continue for all failed researchers...]
+
+## Systemic Issue Analysis
+[Analyze if errors indicate a pattern: search service unavailable, network timeout, all engines blocked, etc.]
+
+## Recommended Actions
+[Suggest what user should do: check network, try again later, use different query, etc.]
+```
+
+**If SOME researchers succeeded but others failed:**
+
+Proceed with synthesis but include a section acknowledging the failures:
+- Note which researchers failed and why
+- Explain how partial failures affected comprehensiveness
+- Identify areas that may need future research
+
+---
+
+### Step 1: Assess Information Completeness
+
+Evaluate cumulative findings against ROOT QUERY and ORIGINAL AGENDA.
+
+**For each agenda item**:
+- Is it covered in depth with specific, actionable information?
+- Are claims backed by multiple corroborating sources?
+- Are there significant gaps or superficial coverage?
+- Is information contradicted without resolution?
+
+**SYNTHESIZE NOW if:**
+- Every agenda item substantively addressed with depth
+- Root query answerable with high confidence
+- Findings corroborated by multiple sources
+- Remaining gaps trivial, academic, or beyond reasonable scope
+- Information high-quality, specific, actionable
+
+**DELEGATE FURTHER RESEARCH if:**
+- One or more agenda items missing or barely explored
+- Critical aspects of root query unaddressed
+- Findings superficial, generic, lack specificity
+- Claims lack adequate evidence or corroboration
+- High-value scrape candidates would fill gaps
+- Contradictions exist requiring targeted resolution
+
+### Step 2: Consider Depth Budget
+
+**If current round < Target rounds**: You have capacity. Prioritize fulfilling all agenda items before synthesizing.
+
+**If current round == Target rounds**: At intended depth. Synthesize if the agenda is substantially covered. Only delegate if CRITICAL GAPS remain unexplored — limit to 1-2 high-impact queries.
+
+**If current round > Target rounds**: Extended territory (bonus rounds). Synthesize NOW unless a catastrophic coverage failure occurred. Do NOT delegate for minor gaps.
+
+### Step 3: Make Strategic Decision
+
+**If synthesizing**: Provide comprehensive synthesis. Be exhaustive. Integrate findings from all researchers. Resolve conflicts where possible. Acknowledge limitations.
+
+**If delegating**: Formulate targeted queries for remaining gaps. Focus on unaddressed agenda items. Limit to 1-2 high-impact queries.
+
+---
+
+## Researcher Scrape Protocol
+
+Each researcher followed a context-aware up-to-4-call scrape protocol:
+1. **Handshake**: Check for already-scraped links (no network)
+2. **Batch 1**: Up to 3 URLs — primary broad scraping
+3. **Batch 2**: Up to 2 URLs — targeted follow-up (auto-deduplicated)
+4. **Batch 3**: Up to 3 URLs — deep-dive
+
+Batches automatically skipped when researcher's context exceeds 55%. Fewer sources than maximum is expected and not a failure.
+
+**When evaluating findings**:
+- **Corroborating**: Multiple researchers found similar information — strong confidence
+- **Complementary**: Different researchers covered different aspects — integrate both
+- **Conflicting**: Sources disagree — identify conflict, explain evidence, suggest resolution or acknowledge uncertainty
+
+---
+
+## Synthesis Output Format
+
+Provide **full breadth, depth, nuance** of information from all sources. This is the final result — be thorough.
+
+```markdown
+# Research Synthesis: [Comprehensive Topic Title]
+
+## Executive Summary
+[High-level analytical overview. Identify most critical insights, patterns, conclusions. Comprehensive summary that stands alone.]
+
+## Detailed Key Findings
+
+### [Major Theme/Category 1]
+- **In-Depth Analysis**: [Exhaustive explanation. Incorporate multiple sources and perspectives. Cite researchers where relevant. Provide context.]
+- **Sub-Finding 1**: [Specific detail with citations]
+- **Sub-Finding 2**: [Specific detail with citations]
+- **Context & Implications**: [What do findings mean? Why significant? How relate to broader topic?]
+
+### [Major Theme/Category 2]
+- **In-Depth Analysis**: [Continue for all major themes...]
+
+## Critical Nuance and Conflicting Perspectives
+
+[Identify areas where:
+- Sources provided different or contradictory information
+- Topic inherently complex or ambiguous
+- Findings require interpretation or multiple perspectives
+- Uncertainty or lack of consensus
+
+For each: describe conflicting information, explain evidence, provide synthesis or acknowledge ambiguity, suggest resolution or additional research needs]
+
+## Coverage & Agenda Assessment
+
+[Address specifically:
+- Which initial agenda items fully resolved
+- Which items partially explored or unaddressed
+- Why certain areas incomplete (sources unavailable, complexity, etc.)
+- Overall comprehensiveness relative to original query]
+
+## Final Conclusions & Strategic Recommendations
+
+[Synthesize key takeaways:
+- Most important conclusions
+- Practical implications
+- Actions/decisions informed by findings
+- Research limitations
+- Most valuable additional information if further research conducted]
+
+## CITED LINKS
+
+[List every URL cited in synthesis, deduplicated. For each:]
+* [URL] — Brief description of contribution and significance
+
+## Research Limitations
+
+[Only include if there are material gaps that significantly constrain the findings — omit if coverage is adequate. Do NOT list scrape candidates as raw URLs. Instead describe what remains unknown and why it matters:]
+- [Topic/area] — What is unknown and its relevance to the root query
+```
+
+---
+
+## Delegation Output Format
+
+Provide a JSON object with `action` and `queries` fields:
+
+```json
+{"action": "delegate", "queries": ["Targeted research question addressing critical gap", "Another specific research direction for remaining gaps"]}
+```
+
+**CRITICAL REQUIREMENTS FOR DELEGATION**:
+- `action` must be exactly the string `"delegate"` (not `delegate` without quotes)
+- `queries` must be an array of strings (not objects, not numbers)
+- Each query string must be non-empty after trimming
+- Do not include nested objects like `{"query": "text"}` — use plain strings only
+
+**Delegation Guidance**:
+- Each query addresses specific, high-impact gap
+- Queries distinct and complementary, not overlapping
+- **For unfulfilled agenda items: copy the exact query string from the "Unfulfilled Agenda Items" list** — do not rephrase. This ensures the system can track coverage.
+- For new gaps not in the original agenda, formulate targeted queries
+- Consider what information would most transform understanding
+- Avoid duplicating already-researched topics
+- Ensure queries specific enough to yield actionable results
+
+---
+
+## Critical Rules
+
+- **CHECK FOR ERRORS FIRST**: If all researchers failed with `ERROR:` reports, output error report format.
+- **ONE DECISION ONLY**: Either synthesize OR delegate. Do not provide both.
+- **OUTPUT FORMAT DETERMINES ACTION**:
+  - JSON object `{"action": "delegate", "queries": [...]}` → Delegating additional research
+  - Any other output (markdown, prose) → Treated as final synthesis
+  - **IMPORTANT**: The JSON must be valid, properly formatted, with string values in the `queries` array
+- **NO DECISION MEMOS**: Never output text explaining decision (e.g., "# Decision: NO"). Provide ONLY synthesis, error report, or JSON array.
+- **BE EXHAUSTIVE IN SYNTHESIS**: Provide full depth and breadth. Do not truncate excessively.
+- **NO SCRAPE CANDIDATE LISTS**: Do not enumerate URLs from researcher SCRAPE CANDIDATES sections — these are internal scaffolding. Mention material gaps in prose under Research Limitations only if they affect the findings.
+- **BE TARGETED IN DELEGATION**: Provide specific, high-impact queries addressing genuine gaps.
+- **USE PLAIN STRINGS IN QUERIES**: Do not use objects like `{"query": "text"}` in the queries array — use plain strings only.
+- **SUBMIT AND STOP**: After providing decision, stop. System handles next steps.

package/src/security/cisa-kev.ts

@@ -0,0 +1,242 @@
+/**
+ * CISA Known Exploited Vulnerabilities (KEV) Catalog Client
+ *
+ * CISA KEV Catalog - actively exploited vulnerabilities
+ * JSON feed: https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json
+ * Free public feed, no authentication required
+ */
+
+import type { Vulnerability, CisaKevResult } from './types.ts';
+import { createTimeoutSignal } from '../web-research/retry-utils.ts';
+
+const CISA_KEV_URL = 'https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json';
+
+// ============================================================================
+// Type Definitions for CISA KEV API
+// ============================================================================
+
+/**
+ * CISA KEV Catalog Item structure from the official API
+ */
+interface CisaKevItem {
+  readonly cveID?: string;
+  readonly cve_id?: string;
+  readonly id?: string;
+  readonly vendorProject?: string;
+  readonly vendor?: string;
+  readonly product?: string;
+  readonly vulnerabilityName?: string;
+  readonly shortDescription?: string;
+  readonly description?: string;
+  readonly dateAdded?: string;
+  readonly addedDate?: string;
+  readonly dueDate?: string;
+  readonly requiredAction?: string;
+  readonly action?: string;
+}
+
+/**
+ * CISA KEV API Response structure
+ */
+interface CisaKevResponse {
+  readonly vulnerabilities?: readonly CisaKevItem[];
+  readonly title?: string;
+  readonly catalogVersion?: string;
+  readonly dateReleased?: string;
+}
+
+/**
+ * Type guard to check if value is a valid CisaKevItem
+ */
+function isCisaKevItem(value: unknown): value is CisaKevItem {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+
+  const item = value as Record<string, unknown>;
+  return (
+    typeof item['cveID'] === 'string' ||
+    typeof item['cve_id'] === 'string' ||
+    typeof item['id'] === 'string'
+  );
+}
+
+/**
+ * Type guard to check if value is an array of CisaKevItem
+ */
+function isCisaKevItemArray(value: unknown): value is readonly CisaKevItem[] {
+  return Array.isArray(value) && value.every(isCisaKevItem);
+}
+
+/**
+ * Type guard to check if value is a CisaKevResponse
+ */
+function isCisaKevResponse(value: unknown): value is CisaKevResponse {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+
+  const response = value as Record<string, unknown>;
+  return (
+    typeof response === 'object' &&
+    (response['vulnerabilities'] === undefined || Array.isArray(response['vulnerabilities']))
+  );
+}
+
+/**
+ * Extract CISA KEV items from various possible response formats
+ */
+function extractCisaKevItems(data: unknown): readonly CisaKevItem[] {
+  if (isCisaKevItemArray(data)) {
+    return data;
+  }
+
+  if (isCisaKevResponse(data) && data.vulnerabilities) {
+    return data.vulnerabilities.filter(isCisaKevItem);
+  }
+
+  return [];
+}
+
+// ============================================================================
+// Main API Functions
+// ============================================================================
+
+/**
+ * Fetch and search CISA KEV catalog
+ *
+ * @param terms - CVE IDs to search for (optional)
+ * @param options - Optional filters
+ * @returns Promise resolving to CISA KEV search results
+ */
+export async function searchCisaKev(
+  terms: string[] = [],
+  options?: {
+    readonly vendor?: string;
+    readonly product?: string;
+    readonly maxResults?: number;
+  },
+): Promise<CisaKevResult> {
+  const maxResults = options?.maxResults ?? 100;
+  const vulnerabilities: Vulnerability[] = [];
+  let error: string | undefined = undefined;
+
+  try {
+    const response: Response = await fetch(CISA_KEV_URL, {
+      headers: {
+        'User-Agent': 'pi-research/2.0',
+        'Accept': 'application/json',
+      },
+      signal: createTimeoutSignal(30000), // 30s timeout
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const data: unknown = await response.json();
+
+    // CISA KEV format is an array of vulnerability objects or nested in a response object
+    const cisaData = extractCisaKevItems(data);
+
+    // Map CISA format to our Vulnerability interface
+    for (const item of cisaData) {
+      const vuln: Vulnerability = mapCisaItemToVulnerability(item);
+
+      // Filter by search terms if provided
+      if (terms.length > 0 && !terms.some((term: string): boolean =>
+        vuln.id.toLowerCase().includes(term.toLowerCase()) ||
+        vuln.description.toLowerCase().includes(term.toLowerCase()),
+      )) {
+        continue;
+      }
+
+      // Filter by vendor/product if provided
+      if (options?.vendor !== undefined) {
+        const vendorLower = vuln.vendor?.toLowerCase() ?? '';
+        if (!vendorLower.includes(options.vendor.toLowerCase())) {
+          continue;
+        }
+      }
+
+      if (options?.product !== undefined) {
+        const productLower = vuln.product?.toLowerCase() ?? '';
+        if (!productLower.includes(options.product.toLowerCase())) {
+          continue;
+        }
+      }
+
+      vulnerabilities.push(vuln);
+    }
+
+    // Sort by due date (most urgent first)
+    vulnerabilities.sort((a: Vulnerability, b: Vulnerability): number => {
+      if (a.dueDate === undefined) {
+        return 1;
+      }
+      if (b.dueDate === undefined) {
+        return -1;
+      }
+      return new Date(a.dueDate).getTime() - new Date(b.dueDate).getTime();
+    });
+
+  } catch (err: unknown) {
+    error = err instanceof Error ? err.message : String(err);
+  }
+
+  return {
+    count: vulnerabilities.length,
+    vulnerabilities: vulnerabilities.slice(0, maxResults),
+    error,
+  };
+}
+
+/**
+ * Safely extract a string property from an unknown object
+ */
+function safeString(value: unknown, defaultValue: string = ''): string {
+  if (typeof value === 'string') {
+    return value;
+  }
+  return defaultValue;
+}
+
+/**
+ * Map CISA KEV item to Vulnerability interface
+ *
+ * @param item - CISA KEV item from API
+ * @returns Mapped Vulnerability object
+ */
+function mapCisaItemToVulnerability(item: CisaKevItem): Vulnerability {
+  // CISA KEV format (example based on scraped structure)
+  const cveId: string = [item.cveID, item.cve_id, item.id].map(v => safeString(v)).find(s => s.length > 0) ?? '';
+  const vendor: string = [item.vendorProject, item.vendor].map(v => safeString(v)).find(s => s.length > 0) ?? '';
+  const product: string = [item.product, item.vulnerabilityName].map(v => safeString(v)).find(s => s.length > 0) ?? '';
+  const description: string = [item.shortDescription, item.description].map(v => safeString(v)).find(s => s.length > 0) ?? '';
+  const dateAdded: string = [item.dateAdded, item.addedDate].map(v => safeString(v)).find(s => s.length > 0) ?? '';
+  const dueDate: string = safeString(item.dueDate);
+  const requiredAction: string = [item.requiredAction, item.action].map(v => safeString(v)).find(s => s.length > 0) ?? '';
+
+  const affectedProducts: string[] = [vendor, product].filter(
+    (value: string): boolean => value.length > 0,
+  );
+
+  return {
+    id: cveId,
+    source: 'cisa_kev',
+    severity: 'CRITICAL', // All KEV entries are critical priority
+    description,
+    published: dateAdded.length > 0 ? dateAdded : undefined,
+    modified: dateAdded.length > 0 ? dateAdded : undefined,
+    cvssScore: undefined, // CISA doesn't include CVSS score
+    cwes: [],
+    references: [],
+    affectedProducts,
+    fixes: [],
+    vendor: vendor.length > 0 ? vendor : undefined,
+    product: product.length > 0 ? product : undefined,
+    knownExploited: true,
+    dueDate: dueDate.length > 0 ? dueDate : undefined,
+    requiredAction: requiredAction.length > 0 ? requiredAction : undefined,
+  };
+}