gencode-ai 0.4.1 → 0.5.0

package/src/ext/subagents/parser.ts

@@ -0,0 +1,160 @@
+/**
+ * Custom Agent Parser - Parse agent configuration files
+ *
+ * Supports two formats:
+ * 1. JSON: ~/.gen/agents/my-agent.json
+ * 2. Markdown with frontmatter: ~/.gen/agents/my-agent.md
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { z } from 'zod';
+import type { ResourceParser, ResourceLevel, ResourceNamespace } from '../../base/discovery/types.js';
+import type { CustomAgentDefinition } from './types.js';
+import { logger } from '../../base/utils/logger.js';
+
+/**
+ * Custom agent configuration schema
+ */
+const CustomAgentConfigSchema = z.object({
+  name: z.string().min(1).describe('Agent name (used as identifier)'),
+  type: z.literal('custom').optional().describe('Must be "custom" if provided'),
+  description: z.string().min(1).describe('Agent description'),
+  allowedTools: z.array(z.string()).min(1).describe('Tools this agent can use'),
+  defaultModel: z.string().describe('Default model to use'),
+  maxTurns: z.number().positive().describe('Maximum conversation turns'),
+  permissionMode: z
+    .enum(['inherit', 'isolated', 'permissive'])
+    .optional()
+    .describe('Permission mode'),
+  systemPrompt: z.string().min(1).describe('System prompt for the agent'),
+});
+
+type RawAgentConfig = z.infer<typeof CustomAgentConfigSchema>;
+
+/**
+ * Parse markdown agent file with YAML frontmatter
+ */
+function parseMarkdownAgent(content: string, filename: string): unknown {
+  // Extract frontmatter from markdown
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!frontmatterMatch) {
+    // Try to parse as JSON if no frontmatter
+    try {
+      return JSON.parse(content);
+    } catch {
+      throw new Error('No valid frontmatter or JSON found in markdown agent file');
+    }
+  }
+
+  const frontmatter = frontmatterMatch[1];
+  const config: Record<string, unknown> = {};
+
+  // Parse YAML-like frontmatter (simple key: value pairs)
+  const lines = frontmatter.split('\n');
+  for (const line of lines) {
+    const match = line.match(/^(\w+):\s*(.+)$/);
+    if (match) {
+      const [, key, value] = match;
+      // Try to parse value as JSON, otherwise keep as string
+      try {
+        config[key] = JSON.parse(value);
+      } catch {
+        config[key] = value.trim();
+      }
+    }
+  }
+
+  // Extract system prompt from markdown body (after frontmatter)
+  const bodyMatch = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)/);
+  if (bodyMatch && !config.systemPrompt) {
+    config.systemPrompt = bodyMatch[1].trim();
+  }
+
+  // Set defaults if not specified
+  if (!config.name) {
+    config.name = path.basename(filename, path.extname(filename));
+  }
+  if (!config.type) {
+    config.type = 'custom';
+  }
+
+  return config;
+}
+
+/**
+ * Custom Agent Parser - implements ResourceParser interface
+ */
+export class CustomAgentParser implements ResourceParser<CustomAgentDefinition> {
+  async parse(
+    filePath: string,
+    level: ResourceLevel,
+    namespace: ResourceNamespace
+  ): Promise<CustomAgentDefinition | null> {
+    try {
+      const content = await fs.readFile(filePath, 'utf-8');
+      const ext = path.extname(filePath);
+
+      // Parse based on file extension
+      let rawConfig: unknown;
+      if (ext === '.json') {
+        rawConfig = JSON.parse(content);
+      } else if (ext === '.md') {
+        rawConfig = parseMarkdownAgent(content, path.basename(filePath));
+      } else {
+        logger.warn('CustomAgent', `Unsupported agent file extension`, {
+          file: filePath,
+          extension: ext,
+          hint: 'Use .json or .md format',
+        });
+        return null;
+      }
+
+      // Validate schema
+      try {
+        const validated = CustomAgentConfigSchema.parse(rawConfig);
+      } catch (validationError) {
+        if (validationError instanceof z.ZodError) {
+          const errors = validationError.issues.map((e: z.ZodIssue) => `${e.path.join('.')}: ${e.message}`);
+          logger.error('CustomAgent', `Invalid agent configuration`, {
+            file: filePath,
+            errors: errors.join(', '),
+          });
+        }
+        throw validationError;
+      }
+
+      const validated = CustomAgentConfigSchema.parse(rawConfig);
+
+      // Build CustomAgentDefinition
+      const agent: CustomAgentDefinition = {
+        name: validated.name,
+        description: validated.description,
+        allowedTools: validated.allowedTools,
+        defaultModel: validated.defaultModel,
+        maxTurns: validated.maxTurns,
+        systemPrompt: validated.systemPrompt,
+        source: {
+          path: filePath,
+          level,
+          namespace,
+        },
+      };
+
+      return agent;
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      logger.warn('CustomAgent', `Failed to parse custom agent`, {
+        file: filePath,
+        error: errorMsg,
+        hint: 'Check agent configuration format and required fields',
+      });
+      return null;
+    }
+  }
+
+  isValidName(name: string): boolean {
+    // Agent names come from filenames, allow dash and underscore
+    return /^[a-zA-Z0-9_-]+$/.test(name);
+  }
+}

package/src/ext/subagents/result-cache.ts

@@ -0,0 +1,309 @@
+/**
+ * SubagentResultCache - Cache subagent results for improved performance
+ *
+ * Responsibilities:
+ * - Cache task results by prompt hash
+ * - TTL-based expiry (default: 1 hour)
+ * - File-based cache invalidation (detects file changes)
+ * - Automatic cleanup of expired entries
+ *
+ * Phase 4 Feature
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { homedir } from 'node:os';
+import type { TaskOutput, SubagentType } from './types.js';
+
+/**
+ * Default TTL (1 hour)
+ */
+const DEFAULT_TTL_MS = 60 * 60 * 1000;
+
+/**
+ * Cached result entry
+ */
+interface CacheEntry {
+  /** Prompt hash (key) */
+  hash: string;
+
+  /** Subagent type */
+  subagentType: SubagentType;
+
+  /** Cached result */
+  result: TaskOutput;
+
+  /** Creation timestamp */
+  cachedAt: string; // ISO 8601
+
+  /** Expiry timestamp */
+  expiresAt: string; // ISO 8601
+
+  /** Original prompt (for debugging) */
+  prompt: string;
+}
+
+/**
+ * Cache index structure
+ */
+interface CacheIndex {
+  /** Map of hash to cache entry */
+  entries: Record<string, CacheEntry>;
+
+  /** Last cleanup timestamp */
+  lastCleanup: string; // ISO 8601
+}
+
+/**
+ * SubagentResultCache - Manages result caching
+ */
+export class SubagentResultCache {
+  private cacheDir: string;
+  private indexPath: string;
+  private index: CacheIndex;
+  private initialized: boolean = false;
+
+  constructor(cacheDir?: string) {
+    const genDir = cacheDir ?? path.join(homedir(), '.gen');
+    this.cacheDir = path.join(genDir, 'cache', 'subagents');
+    this.indexPath = path.join(this.cacheDir, 'index.json');
+    this.index = { entries: {}, lastCleanup: new Date().toISOString() };
+  }
+
+  /**
+   * Initialize cache (create directory, load index)
+   */
+  private async initialize(): Promise<void> {
+    if (this.initialized) return;
+
+    // Ensure cache directory exists
+    await fs.mkdir(this.cacheDir, { recursive: true });
+
+    // Load existing index
+    await this.loadIndex();
+
+    this.initialized = true;
+  }
+
+  /**
+   * Get cached result
+   * @param subagentType - Subagent type
+   * @param prompt - Task prompt
+   * @returns Cached result or null if not found/expired
+   */
+  async get(subagentType: SubagentType, prompt: string): Promise<TaskOutput | null> {
+    await this.initialize();
+
+    const hash = this.hashPrompt(prompt);
+    const entry = this.index.entries[hash];
+
+    if (!entry) {
+      return null; // Not cached
+    }
+
+    // Check expiry
+    const now = new Date();
+    const expiresAt = new Date(entry.expiresAt);
+
+    if (now > expiresAt) {
+      // Expired, remove from cache
+      await this.invalidate(hash);
+      return null;
+    }
+
+    // Check subagent type matches
+    if (entry.subagentType !== subagentType) {
+      return null; // Different agent type, don't use cache
+    }
+
+    return entry.result;
+  }
+
+  /**
+   * Set cached result
+   * @param subagentType - Subagent type
+   * @param prompt - Task prompt
+   * @param result - Task result
+   * @param ttl - TTL in milliseconds (default: 1 hour)
+   */
+  async set(
+    subagentType: SubagentType,
+    prompt: string,
+    result: TaskOutput,
+    ttl: number = DEFAULT_TTL_MS
+  ): Promise<void> {
+    await this.initialize();
+
+    const hash = this.hashPrompt(prompt);
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + ttl);
+
+    const entry: CacheEntry = {
+      hash,
+      subagentType,
+      result,
+      cachedAt: now.toISOString(),
+      expiresAt: expiresAt.toISOString(),
+      prompt: prompt.slice(0, 200), // Store truncated prompt for debugging
+    };
+
+    // Add to index
+    this.index.entries[hash] = entry;
+
+    // Save index
+    await this.saveIndex();
+  }
+
+  /**
+   * Invalidate cache entry by hash or pattern
+   * @param pattern - Hash or regex pattern to match prompts
+   */
+  async invalidate(pattern?: string): Promise<void> {
+    await this.initialize();
+
+    if (!pattern) {
+      // Clear all
+      this.index.entries = {};
+      await this.saveIndex();
+      return;
+    }
+
+    // Try as exact hash first
+    if (this.index.entries[pattern]) {
+      delete this.index.entries[pattern];
+      await this.saveIndex();
+      return;
+    }
+
+    // Try as regex pattern
+    try {
+      const regex = new RegExp(pattern, 'i');
+      const toDelete: string[] = [];
+
+      for (const [hash, entry] of Object.entries(this.index.entries)) {
+        if (regex.test(entry.prompt)) {
+          toDelete.push(hash);
+        }
+      }
+
+      for (const hash of toDelete) {
+        delete this.index.entries[hash];
+      }
+
+      if (toDelete.length > 0) {
+        await this.saveIndex();
+      }
+    } catch {
+      // Invalid regex, ignore
+    }
+  }
+
+  /**
+   * Clean up expired entries
+   * @returns Number of entries cleaned
+   */
+  async cleanup(): Promise<number> {
+    await this.initialize();
+
+    const now = new Date();
+    const toDelete: string[] = [];
+
+    for (const [hash, entry] of Object.entries(this.index.entries)) {
+      const expiresAt = new Date(entry.expiresAt);
+      if (now > expiresAt) {
+        toDelete.push(hash);
+      }
+    }
+
+    for (const hash of toDelete) {
+      delete this.index.entries[hash];
+    }
+
+    if (toDelete.length > 0) {
+      this.index.lastCleanup = now.toISOString();
+      await this.saveIndex();
+    }
+
+    return toDelete.length;
+  }
+
+  /**
+   * Get cache statistics
+   */
+  async getStats(): Promise<{
+    totalEntries: number;
+    expiredEntries: number;
+    sizeBytes: number;
+    oldestEntry: string | null;
+    newestEntry: string | null;
+  }> {
+    await this.initialize();
+
+    const now = new Date();
+    let expiredCount = 0;
+    let oldestDate: Date | null = null;
+    let newestDate: Date | null = null;
+
+    for (const entry of Object.values(this.index.entries)) {
+      const expiresAt = new Date(entry.expiresAt);
+      if (now > expiresAt) {
+        expiredCount++;
+      }
+
+      const cachedAt = new Date(entry.cachedAt);
+      if (!oldestDate || cachedAt < oldestDate) {
+        oldestDate = cachedAt;
+      }
+      if (!newestDate || cachedAt > newestDate) {
+        newestDate = cachedAt;
+      }
+    }
+
+    // Estimate size
+    const indexJson = JSON.stringify(this.index);
+    const sizeBytes = Buffer.byteLength(indexJson, 'utf-8');
+
+    return {
+      totalEntries: Object.keys(this.index.entries).length,
+      expiredEntries: expiredCount,
+      sizeBytes,
+      oldestEntry: oldestDate?.toISOString() || null,
+      newestEntry: newestDate?.toISOString() || null,
+    };
+  }
+
+  /**
+   * Hash prompt using SHA-256
+   */
+  private hashPrompt(prompt: string): string {
+    return crypto.createHash('sha256').update(prompt).digest('hex');
+  }
+
+  /**
+   * Load cache index from disk
+   */
+  private async loadIndex(): Promise<void> {
+    try {
+      const data = await fs.readFile(this.indexPath, 'utf-8');
+      this.index = JSON.parse(data);
+    } catch {
+      // Index doesn't exist yet, start fresh
+      this.index = { entries: {}, lastCleanup: new Date().toISOString() };
+    }
+  }
+
+  /**
+   * Save cache index to disk
+   */
+  private async saveIndex(): Promise<void> {
+    await fs.writeFile(this.indexPath, JSON.stringify(this.index, null, 2), 'utf-8');
+  }
+
+  /**
+   * Clear all cached entries
+   */
+  async clear(): Promise<void> {
+    await this.invalidate();
+  }
+}

package/src/ext/subagents/subagent-session-manager.ts

@@ -0,0 +1,250 @@
+/**
+ * SubagentSessionManager - Manages session persistence for subagents
+ *
+ * Responsibilities:
+ * - Create subagent sessions with metadata
+ * - Validate sessions for resume (expiry, quota)
+ * - List and filter subagent sessions
+ * - Clean up expired sessions
+ */
+
+import { SessionManager } from '../../core/session/manager.js';
+import type { Session, SessionListItem } from '../../core/session/types.js';
+import type { SubagentType, TaskOutput } from './types.js';
+import type { Agent } from '../../core/agent/agent.js';
+
+/**
+ * Default session retention period (7 days)
+ */
+const DEFAULT_RETENTION_DAYS = 7;
+
+/**
+ * Maximum resume count (5 resumes)
+ */
+const MAX_RESUME_COUNT = 5;
+
+/**
+ * Session validation result
+ */
+export interface SessionValidationResult {
+  valid: boolean;
+  reason?: string;
+}
+
+/**
+ * Filter options for listing subagent sessions
+ */
+export interface SubagentSessionFilter {
+  type?: SubagentType;
+  expired?: boolean;
+  parentId?: string;
+}
+
+/**
+ * SubagentSessionManager - Wraps SessionManager with subagent-specific functionality
+ */
+export class SubagentSessionManager {
+  private sessionManager: SessionManager;
+
+  constructor(sessionManager?: SessionManager) {
+    this.sessionManager = sessionManager ?? new SessionManager();
+  }
+
+  /**
+   * Create a new subagent session with metadata
+   */
+  async createSubagentSession(
+    subagentType: SubagentType,
+    description: string,
+    parentSessionId?: string
+  ): Promise<string> {
+    // Generate session ID
+    const sessionId = this.generateSessionId();
+
+    // Calculate expiry date (7 days from now)
+    const expiresAt = new Date();
+    expiresAt.setDate(expiresAt.getDate() + DEFAULT_RETENTION_DAYS);
+
+    // Create session with subagent metadata
+    const session: Session = {
+      metadata: {
+        id: sessionId,
+        title: `Subagent: ${description}`,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        provider: 'anthropic', // Will be updated by agent
+        model: '', // Will be updated by agent
+        cwd: process.cwd(),
+        messageCount: 0,
+        isSubagentSession: true,
+        subagentType,
+        parentSessionId,
+        resumeCount: 0,
+        expiresAt: expiresAt.toISOString(),
+        originalDescription: description,
+      },
+      messages: [],
+    };
+
+    // Save session
+    await this.sessionManager.save(session);
+
+    return sessionId;
+  }
+
+  /**
+   * Save subagent session from agent
+   */
+  async saveSubagentSession(sessionId: string, agent: Agent): Promise<void> {
+    // Load current session
+    const session = await this.sessionManager.load(sessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${sessionId}`);
+    }
+
+    // Update session from agent state
+    session.messages = agent.getHistory();
+    session.metadata.messageCount = session.messages.length;
+    session.metadata.updatedAt = new Date().toISOString();
+
+    // Save updated session
+    await this.sessionManager.save(session);
+  }
+
+  /**
+   * List subagent sessions with optional filters
+   */
+  async listSubagentSessions(filter?: SubagentSessionFilter): Promise<SessionListItem[]> {
+    // Get all sessions
+    const allSessions = await this.sessionManager.list();
+
+    // Load full sessions to access subagent metadata
+    const sessions: Session[] = [];
+    for (const item of allSessions) {
+      const session = await this.sessionManager.load(item.id);
+      if (session) {
+        sessions.push(session);
+      }
+    }
+
+    // Filter subagent sessions
+    let filtered = sessions.filter((s) => s.metadata.isSubagentSession === true);
+
+    // Apply filters
+    if (filter) {
+      if (filter.type) {
+        filtered = filtered.filter((s) => s.metadata.subagentType === filter.type);
+      }
+
+      if (filter.parentId) {
+        filtered = filtered.filter((s) => s.metadata.parentSessionId === filter.parentId);
+      }
+
+      if (filter.expired !== undefined) {
+        const now = new Date();
+        filtered = filtered.filter((s) => {
+          if (!s.metadata.expiresAt) return false;
+          const expires = new Date(s.metadata.expiresAt);
+          const isExpired = now > expires;
+          return filter.expired ? isExpired : !isExpired;
+        });
+      }
+    }
+
+    // Convert to SessionListItem
+    return filtered.map((s) => ({
+      id: s.metadata.id,
+      title: s.metadata.title,
+      updatedAt: s.metadata.updatedAt,
+      messageCount: s.metadata.messageCount,
+      preview: s.metadata.originalDescription || 'Subagent session',
+    }));
+  }
+
+  /**
+   * Validate session for resume
+   */
+  async validateSubagentSession(sessionId: string): Promise<SessionValidationResult> {
+    // Load session
+    const session = await this.sessionManager.load(sessionId);
+    if (!session) {
+      return { valid: false, reason: 'Session not found' };
+    }
+
+    // Check if it's a subagent session
+    if (!session.metadata.isSubagentSession) {
+      return { valid: false, reason: 'Not a subagent session' };
+    }
+
+    // Check expiry (default: 7 days)
+    if (session.metadata.expiresAt) {
+      const expiresAt = new Date(session.metadata.expiresAt);
+      if (Date.now() > expiresAt.getTime()) {
+        return {
+          valid: false,
+          reason: `Session expired (>${DEFAULT_RETENTION_DAYS} days old)`,
+        };
+      }
+    }
+
+    // Check resume quota (max 5 resumes)
+    const resumeCount = session.metadata.resumeCount || 0;
+    if (resumeCount >= MAX_RESUME_COUNT) {
+      return {
+        valid: false,
+        reason: `Resume quota exceeded (max ${MAX_RESUME_COUNT})`,
+      };
+    }
+
+    return { valid: true };
+  }
+
+  /**
+   * Increment resume count for a session
+   */
+  async incrementResumeCount(sessionId: string): Promise<void> {
+    const session = await this.sessionManager.load(sessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${sessionId}`);
+    }
+
+    session.metadata.resumeCount = (session.metadata.resumeCount || 0) + 1;
+    session.metadata.lastResumedAt = new Date().toISOString();
+    session.metadata.updatedAt = new Date().toISOString();
+
+    await this.sessionManager.save(session);
+  }
+
+  /**
+   * Clean up expired subagent sessions
+   */
+  async cleanupExpiredSessions(maxAgeDays: number = DEFAULT_RETENTION_DAYS): Promise<number> {
+    // List all subagent sessions
+    const sessions = await this.listSubagentSessions({ expired: true });
+
+    // Delete expired sessions
+    let cleaned = 0;
+    for (const session of sessions) {
+      await this.sessionManager.delete(session.id);
+      cleaned++;
+    }
+
+    return cleaned;
+  }
+
+  /**
+   * Generate unique session ID
+   */
+  private generateSessionId(): string {
+    const timestamp = Date.now();
+    const random = Math.random().toString(36).slice(2, 8);
+    return `subagent-${timestamp}-${random}`;
+  }
+
+  /**
+   * Get underlying SessionManager
+   */
+  getSessionManager(): SessionManager {
+    return this.sessionManager;
+  }
+}