@lincoln504/pi-research 0.0.0

package/src/types/extension-context.ts

@@ -0,0 +1,60 @@
+/**
+ * Extended Type Definitions for pi Extension Context
+ *
+ * These types extend the base ExtensionContext from @mariozechner/pi-coding-agent
+ * to provide type safety for additional properties that are accessed at runtime.
+ */
+
+import type { SettingsManager } from '@mariozechner/pi-coding-agent';
+
+/**
+ * Session manager interface for accessing session metadata
+ */
+export interface SessionManager {
+  getSessionId(): string;
+  getSessionFile(): string;
+}
+
+/**
+ * Extended ExtensionContext with additional properties
+ * Note: We don't extend ExtensionContext to avoid type conflicts with
+ * ReadonlySessionManager. This is used as a cast target only.
+ */
+export interface ExtendedExtensionContext {
+  sessionManager?: SessionManager;
+  settingsManager?: SettingsManager;
+}
+
+/**
+ * Model with ID property and optional cost information
+ */
+export interface ModelWithId {
+  id: string;
+  cost?: {
+    input: number;
+    output: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+  };
+}
+
+/**
+ * Agent session event with usage and error information
+ */
+export interface ExtendedAgentSessionEvent {
+  type: string;
+  message?: {
+    role?: string;
+    usage?: {
+      totalTokens?: number;
+      input?: number;
+      output?: number;
+      cacheRead?: number;
+      cacheWrite?: number;
+    };
+  };
+  isError?: boolean;
+  details?: {
+    blocked?: boolean;
+  };
+}

package/src/types/llm.ts

@@ -0,0 +1,111 @@
+/**
+ * LLM-Related Type Definitions
+ *
+ * Shared type definitions for LLM responses, usage, and message content.
+ * These types complement the types from @mariozechner/pi-ai and provide
+ * more specific typing for our use cases.
+ */
+
+/**
+ * Token usage information from LLM responses
+ */
+export interface TokenUsage {
+  /** Input tokens consumed */
+  input?: number;
+  /** Output tokens generated */
+  output?: number;
+  /** Cache read tokens (for prompt caching) */
+  cacheRead?: number;
+  /** Cache write tokens (for prompt caching) */
+  cacheWrite?: number;
+  /** Total tokens (may be provided by some providers) */
+  totalTokens?: number;
+}
+
+/**
+ * Text content block in a message
+ */
+export interface TextContentBlock {
+  type: 'text';
+  text: string;
+}
+
+/**
+ * Message content (can be a string or array of blocks)
+ */
+export type MessageContent = string | TextContentBlock[];
+
+/**
+ * Filter for text content blocks from a message content array
+ */
+export function isTextContentBlock(block: unknown): block is TextContentBlock {
+  return (
+    block !== null &&
+    typeof block === 'object' &&
+    (block as Record<string, unknown>)['type'] === 'text' &&
+    typeof (block as Record<string, unknown>)['text'] === 'string'
+  );
+}
+
+/**
+ * Extract text from a message content block or string
+ */
+export function extractTextFromContent(content: MessageContent): string {
+  if (typeof content === 'string') {
+    return content;
+  }
+  if (Array.isArray(content)) {
+    return content
+      .filter(isTextContentBlock)
+      .map(block => block.text)
+      .join('\n');
+  }
+  return '';
+}
+
+/**
+ * Parse token usage from an unknown object
+ * Returns a partial usage object with any fields that were present
+ */
+export function parseTokenUsage(usage: unknown): Partial<TokenUsage> {
+  if (!usage || typeof usage !== 'object') {
+    return {};
+  }
+
+  const obj = usage as Record<string, unknown>;
+  const result: Partial<TokenUsage> = {};
+
+  if (typeof obj['input'] === 'number') {
+    result.input = obj['input'];
+  }
+  if (typeof obj['output'] === 'number') {
+    result.output = obj['output'];
+  }
+  if (typeof obj['cacheRead'] === 'number') {
+    result.cacheRead = obj['cacheRead'];
+  }
+  if (typeof obj['cacheWrite'] === 'number') {
+    result.cacheWrite = obj['cacheWrite'];
+  }
+  if (typeof obj['totalTokens'] === 'number') {
+    result.totalTokens = obj['totalTokens'];
+  }
+
+  return result;
+}
+
+/**
+ * Calculate total tokens from usage object
+ * Falls back to sum of individual components if totalTokens not provided
+ */
+export function calculateTotalTokens(usage: Partial<TokenUsage>): number {
+  if (usage.totalTokens !== undefined) {
+    return usage.totalTokens;
+  }
+  return (
+    (usage.input ?? 0) +
+    (usage.output ?? 0) +
+    (usage.cacheRead ?? 0) +
+    (usage.cacheWrite ?? 0)
+  );
+}

package/src/utils/inject-date.ts

@@ -0,0 +1,29 @@
+/**
+ * Date Injection Utility
+ *
+ * Injects the current date into agent prompts.
+ */
+
+/**
+ * Format current date as a readable string
+ */
+function getCurrentDateString(): string {
+  const now = new Date();
+  const options: Intl.DateTimeFormatOptions = {
+    weekday: 'long',
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+  };
+  return now.toLocaleDateString('en-US', options);
+}
+
+/**
+ * Inject current date into a prompt
+ * Prepends a date context line to the prompt
+ */
+export function injectCurrentDate(prompt: string, _agentType: 'coordinator' | 'researcher'): string {
+  const dateString = getCurrentDateString();
+  const dateContext = `**Current Date:** ${dateString}\n\n`;
+  return dateContext + prompt;
+}

package/src/utils/input-validation.ts

@@ -0,0 +1,103 @@
+/**
+ * Input Validation Utilities
+ *
+ * Basic validation for research queries and parameters.
+ */
+
+import { logger } from '../logger.ts';
+
+/** Maximum query length */
+export const MAX_QUERY_LENGTH = 500;
+
+/** Minimum query length */
+export const MIN_QUERY_LENGTH = 3;
+
+/**
+ * Validate research query
+ *
+ * @param query - The research query to validate
+ * @returns Object with isValid flag and optional error message
+ */
+export function validateQuery(query: string): { isValid: boolean; error?: string } {
+  // Check if query is provided
+  if (!query || typeof query !== 'string') {
+    return { isValid: false, error: 'Query must be a non-empty string' };
+  }
+
+  const trimmed = query.trim();
+
+  // Check minimum length
+  if (trimmed.length < MIN_QUERY_LENGTH) {
+    return { isValid: false, error: `Query must be at least ${MIN_QUERY_LENGTH} characters` };
+  }
+
+  // Check maximum length
+  if (trimmed.length > MAX_QUERY_LENGTH) {
+    return { isValid: false, error: `Query must be at most ${MAX_QUERY_LENGTH} characters` };
+  }
+
+  // Check for empty or whitespace-only queries
+  if (trimmed === '') {
+    return { isValid: false, error: 'Query cannot be empty or whitespace-only' };
+  }
+
+  // Check for potentially dangerous patterns
+  const dangerousPatterns = [
+    /<script/i,
+    /javascript:/i,
+    /on\w+\s*=/i, // Event handlers like onclick=
+    /<iframe/i,
+    /<object/i,
+    /<embed/i,
+  ];
+
+  for (const pattern of dangerousPatterns) {
+    if (pattern.test(trimmed)) {
+      return { isValid: false, error: 'Query contains potentially dangerous content' };
+    }
+  }
+
+  return { isValid: true };
+}
+
+/**
+ * Sanitize research query for safe use
+ *
+ * @param query - The research query to sanitize
+ * @returns Sanitized query
+ */
+export function sanitizeQuery(query: string): string {
+  return query
+    .trim()
+    .replace(/\s+/g, ' ') // Normalize whitespace
+    .replace(/[\x00-\x1F\x7F]/g, ''); // eslint-disable-line no-control-regex -- Remove control characters
+}
+
+/**
+ * Validate and sanitize research query in one step
+ *
+ * @param query - The research query to validate and sanitize
+ * @returns Sanitized query or throws error if invalid
+ * @throws Error if query is invalid
+ */
+export function validateAndSanitizeQuery(query: string): string {
+  const validation = validateQuery(query);
+
+  if (!validation.isValid) {
+    const error = validation.error || 'Invalid query';
+    logger.warn(`[input-validation] ${error}`);
+    throw new Error(error);
+  }
+
+  return sanitizeQuery(query);
+}
+
+/**
+ * Validate complexity level
+ *
+ * @param complexity - The complexity level to validate
+ * @returns True if valid, false otherwise
+ */
+export function validateComplexity(complexity: number): boolean {
+  return complexity === 0 || complexity === 1 || complexity === 2 || complexity === 3;
+}

package/src/utils/json-utils.ts

@@ -0,0 +1,262 @@
+/**
+ * JSON Parsing Utilities
+ *
+ * Shared utilities for parsing JSON from LLM responses.
+ * Handles various formats including code blocks, raw JSON, and malformed input.
+ */
+
+import { logger } from '../logger.ts';
+
+/**
+ * Result of a JSON extraction attempt
+ */
+export interface JsonExtractionResult<T = unknown> {
+  /** Whether extraction was successful */
+  success: boolean;
+  /** The parsed value if successful, undefined otherwise */
+  value: T | undefined;
+  /** Error message if unsuccessful */
+  error?: string;
+  /** The method that succeeded (for logging) */
+  method?: 'code-block' | 'raw-object' | 'raw-array';
+}
+
+/**
+ * Extract JSON from markdown code blocks
+ *
+ * Looks for ```json or ```javascript code blocks and parses the content.
+ * Returns the first successfully parsed block.
+ *
+ * @param text - Text to search for JSON code blocks
+ * @returns Extraction result with parsed value or error
+ */
+export function extractJsonFromCodeBlocks<T = unknown>(
+  text: string
+): JsonExtractionResult<T> {
+  const codeBlockRegex = /```(?:json|javascript)?\s*([\s\S]*?)```/gi;
+  let match: RegExpExecArray | null;
+
+  while ((match = codeBlockRegex.exec(text)) !== null) {
+    const codeContent = match[1] ?? '';
+    try {
+      const parsed = JSON.parse(codeContent.trim());
+      return { success: true, value: parsed as T, method: 'code-block' };
+    } catch {
+      // Try next code block
+      continue;
+    }
+  }
+
+  return {
+    success: false,
+    value: undefined,
+    error: 'No valid JSON found in code blocks',
+  };
+}
+
+/**
+ * Extract JSON object from raw text
+ *
+ * Looks for a JSON object spanning from the first `{` to the last `}`.
+ * Useful when JSON is embedded in prose without code blocks.
+ *
+ * @param text - Text to search for JSON object
+ * @returns Extraction result with parsed value or error
+ */
+export function extractJsonObject<T = unknown>(
+  text: string
+): JsonExtractionResult<T> {
+  const objStart = text.indexOf('{');
+  const objEnd = text.lastIndexOf('}');
+
+  if (objStart === -1 || objEnd <= objStart) {
+    return {
+      success: false,
+      value: undefined,
+      error: 'No JSON object boundaries found',
+    };
+  }
+
+  try {
+    const jsonStr = text.slice(objStart, objEnd + 1);
+    const parsed = JSON.parse(jsonStr);
+    return { success: true, value: parsed as T, method: 'raw-object' };
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    return {
+      success: false,
+      value: undefined,
+      error: `Failed to parse JSON object: ${errorMsg}`,
+    };
+  }
+}
+
+/**
+ * Extract JSON array from raw text
+ *
+ * Looks for a JSON array spanning from the first `[` to the last `]`.
+ * Useful for extracting arrays of strings or objects.
+ *
+ * @param text - Text to search for JSON array
+ * @returns Extraction result with parsed value or error
+ */
+export function extractJsonArray<T = unknown>(
+  text: string
+): JsonExtractionResult<T[]> {
+  const stripped = text.trim();
+  
+  // Quick check if it's a JSON array
+  if (!stripped.startsWith('[') || !stripped.endsWith(']')) {
+    return {
+      success: false,
+      value: undefined,
+      error: 'Text is not a JSON array',
+    };
+  }
+
+  try {
+    const parsed = JSON.parse(stripped);
+    if (!Array.isArray(parsed)) {
+      return {
+        success: false,
+        value: undefined,
+        error: 'Parsed value is not an array',
+      };
+    }
+    return { success: true, value: parsed as T[], method: 'raw-array' };
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    return {
+      success: false,
+      value: undefined,
+      error: `Failed to parse JSON array: ${errorMsg}`,
+    };
+  }
+}
+
+/**
+ * Extract JSON with fallback chain
+ *
+ * Tries multiple extraction methods in order:
+ * 1. Code blocks (most reliable)
+ * 2. Raw JSON object (for objects)
+ * 3. Raw JSON array (for arrays)
+ *
+ * @param text - Text to extract JSON from
+ * @param targetType - Whether to expect 'object', 'array', or 'any'
+ * @returns Extraction result with parsed value or error
+ */
+export function extractJson<T = unknown>(
+  text: string,
+  targetType: 'object' | 'array' | 'any' = 'any'
+): JsonExtractionResult<T> {
+  // Try code blocks first (most reliable)
+  const codeBlockResult = extractJsonFromCodeBlocks<T>(text);
+  if (codeBlockResult.success) {
+    logger.debug('[json-utils] Extracted JSON from code block');
+    return codeBlockResult;
+  }
+
+  // Try raw object (if expecting object or any)
+  if (targetType === 'object' || targetType === 'any') {
+    const objectResult = extractJsonObject<T>(text);
+    if (objectResult.success) {
+      logger.debug('[json-utils] Extracted JSON object from raw text');
+      return objectResult;
+    }
+  }
+
+  // Try raw array (if expecting array or any)
+  if (targetType === 'array' || targetType === 'any') {
+    const arrayResult = extractJsonArray<T>(text);
+    if (arrayResult.success) {
+      logger.debug('[json-utils] Extracted JSON array from raw text');
+      return arrayResult as JsonExtractionResult<T>;
+    }
+  }
+
+  // All methods failed
+  return {
+    success: false,
+    value: undefined,
+    error: 'No valid JSON found using any extraction method',
+  };
+}
+
+/**
+ * Result of string array normalization
+ */
+export interface NormalizeArrayResult {
+  /** Normalized strings */
+  strings: string[];
+  /** Count of items that were skipped (empty after normalization) */
+  skippedCount: number;
+  /** Count of items that were objects and needed extraction */
+  extractedCount: number;
+  /** Warnings about any issues */
+  warnings: string[];
+}
+
+/**
+ * Normalize string array with detailed feedback
+ *
+ * Normalizes an array of values to strings with detailed feedback
+ * about what was normalized and any issues.
+ *
+ * @param arr - Array of values to normalize
+ * @returns Detailed normalization result
+ */
+export function normalizeStringArrayDetailed(
+  arr: unknown[]
+): NormalizeArrayResult {
+  const strings: string[] = [];
+  const warnings: string[] = [];
+  let skippedCount = 0;
+  let extractedCount = 0;
+
+  arr.forEach((item, index) => {
+    if (typeof item === 'string') {
+      const trimmed = item.trim();
+      if (trimmed.length > 0) {
+        strings.push(trimmed);
+      } else {
+        skippedCount++;
+        warnings.push(`Item ${index}: empty string`);
+      }
+    } else if (item !== null && typeof item === 'object') {
+      extractedCount++;
+      const obj = item as Record<string, unknown>;
+      const candidate = obj['query'] ?? obj['topic'] ?? obj['text'] ?? obj['task'];
+      
+      if (typeof candidate === 'string') {
+        const trimmed = candidate.trim();
+        if (trimmed.length > 0) {
+          strings.push(trimmed);
+        } else {
+          skippedCount++;
+          warnings.push(`Item ${index}: object extracted empty string`);
+        }
+      } else {
+        // No recognized key, stringify the whole object
+        const stringified = JSON.stringify(item);
+        if (stringified.length > 0) {
+          strings.push(stringified);
+          warnings.push(`Item ${index}: no recognized key, stringified object`);
+        } else {
+          skippedCount++;
+          warnings.push(`Item ${index}: object stringified to empty`);
+        }
+      }
+    } else {
+      const stringified = String(item).trim();
+      if (stringified.length > 0) {
+        strings.push(stringified);
+      } else {
+        skippedCount++;
+        warnings.push(`Item ${index}: ${typeof item} converted to empty string`);
+      }
+    }
+  });
+
+  return { strings, skippedCount, extractedCount, warnings };
+}

package/src/utils/make-resource-loader.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared ResourceLoader Factory
+ *
+ * Extracted from coordinator.ts and researcher.ts to avoid duplication.
+ * Both files use identical ResourceLoader implementations.
+ */
+
+import type { ResourceLoader, ExtensionRuntime } from '@mariozechner/pi-coding-agent';
+
+export function makeResourceLoader(systemPromptText: string): ResourceLoader {
+  const mockRuntime: ExtensionRuntime = {
+    flagValues: new Map(),
+    pendingProviderRegistrations: [],
+    registerProvider: () => {},
+    unregisterProvider: () => {},
+    sendMessage: async () => {},
+    sendUserMessage: async () => {},
+    appendEntry: async () => {},
+    setSessionName: () => undefined,
+    getSessionName: () => undefined,
+    setLabel: async () => {},
+    getActiveTools: () => [],
+    getAllTools: () => [],
+    setActiveTools: () => {},
+    refreshTools: () => {},
+    getCommands: () => [],
+    setModel: async () => true,
+    getThinkingLevel: () => 'off',
+    setThinkingLevel: () => {},
+  };
+
+  return {
+    getExtensions: () => ({ extensions: [], errors: [], runtime: mockRuntime }),
+    getSkills: () => ({ skills: [], diagnostics: [] }),
+    getPrompts: () => ({ prompts: [], diagnostics: [] }),
+    getThemes: () => ({ themes: [], diagnostics: [] }),
+    getAgentsFiles: () => ({ agentsFiles: [] }),
+    getSystemPrompt: () => systemPromptText,
+    getAppendSystemPrompt: () => [],
+    extendResources: () => {},
+    reload: async () => {},
+  };
+}