forge-server 0.1.0 → 0.1.1

package/src/learning/patterns.ts

@@ -1,360 +0,0 @@
-// PatternExtractor — B11
-//
-// Extracts learnable knowledge items from completed project trajectories.
-// Called by the knowledge_collection phase tool handler after a project
-// reaches the inspection->completed transition.
-//
-// Two operations:
-//
-//   extractFromProject(projectId)
-//     Reads all trajectory steps for the project, looks for high-quality
-//     steps (qualityScore >= 0.7) and steps with "gotcha"-like language,
-//     and promotes the best observations to KnowledgeItem records.
-//     Writes to both the YAML store (durable) and Qdrant (searchable).
-//
-//   promoteToKnowledge(observation, category, repoId, ...)
-//     One-shot promotion: takes a raw observation string and creates a
-//     full KnowledgeItem with embedding, persisting to YAML and Qdrant.
-//     Used by the knowledge-keeper agent for manual promotion.
-
-import { randomUUID } from 'node:crypto';
-import type { PipelineDB } from '../storage/sqlite.js';
-import type { KnowledgeYamlStore } from '../knowledge/store.js';
-import type { KnowledgeSearch } from '../knowledge/search.js';
-import type {
-  KnowledgeItem,
-  KnowledgeCategory,
-  Phase,
-  PipelinePhase,
-  TrajectoryStepRow,
-  TrajectoryRow,
-} from '../util/types.js';
-import { embedText } from '../ingestion/embedder.js';
-import { logger } from '../util/logger.js';
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-/** Minimum quality score for a step to be considered a candidate. */
-const QUALITY_THRESHOLD = 0.7;
-
-/** Words that strongly suggest a step contains a gotcha / pain point. */
-const GOTCHA_KEYWORDS = [
-  'gotcha',
-  'bug',
-  'fix',
-  'broken',
-  'failed',
-  'error',
-  'issue',
-  'problem',
-  'mistake',
-  'avoid',
-  'warning',
-  'careful',
-  'unexpected',
-  'pitfall',
-  'caveat',
-];
-
-/** Words that suggest a step contains a positive pattern. */
-const PATTERN_KEYWORDS = [
-  'pattern',
-  'approach',
-  'works',
-  'solution',
-  'discovered',
-  'learned',
-  'efficient',
-  'best',
-  'prefer',
-  'recommend',
-];
-
-// ---------------------------------------------------------------------------
-// PatternExtractor
-// ---------------------------------------------------------------------------
-
-export class PatternExtractor {
-  constructor(
-    private readonly db: PipelineDB,
-    private readonly knowledgeStore: KnowledgeYamlStore,
-    private readonly knowledgeSearch: KnowledgeSearch,
-    private readonly embedder: typeof embedText,
-  ) {}
-
-  /**
-   * Extract knowledge from all trajectory steps of a completed project.
-   *
-   * Algorithm:
-   * 1. Load all trajectories + their steps for the project.
-   * 2. Collect steps that are either:
-   *    a. High quality (qualityScore >= QUALITY_THRESHOLD), or
-   *    b. Contain gotcha-like language in action/result text.
-   * 3. For each candidate step, determine whether it looks like a gotcha
-   *    or a pattern (keyword matching).
-   * 4. Deduplicate against existing knowledge (semantic similarity check).
-   * 5. Promote unique candidates to KnowledgeItem records.
-   * 6. Return the list of newly created items.
-   */
-  async extractFromProject(projectId: string): Promise<KnowledgeItem[]> {
-    // Load all trajectories for the project
-    const trajectoryRows = this.db.all<TrajectoryRow>(
-      `SELECT * FROM trajectories WHERE project_id = ? ORDER BY started_at ASC`,
-      [projectId],
-    );
-
-    if (trajectoryRows.length === 0) {
-      logger.debug('PatternExtractor: no trajectories for project', { projectId });
-      return [];
-    }
-
-    // Load all steps for these trajectories in one query
-    const trajectoryIds = trajectoryRows.map((t) => t.id);
-    const placeholders = trajectoryIds.map(() => '?').join(', ');
-    const stepRows = this.db.all<TrajectoryStepRow>(
-      `SELECT * FROM trajectory_steps WHERE trajectory_id IN (${placeholders}) ORDER BY created_at ASC`,
-      trajectoryIds,
-    );
-
-    // Build a map from trajectory_id -> trajectory for phase/agent lookup
-    const trajectoryMap = new Map<string, TrajectoryRow>(
-      trajectoryRows.map((t) => [t.id, t]),
-    );
-
-    // Identify candidate steps
-    const candidates = stepRows.filter((step) => {
-      const hasHighQuality =
-        step.quality_score !== null && step.quality_score >= QUALITY_THRESHOLD;
-      const text = `${step.action} ${step.result ?? ''}`.toLowerCase();
-      const hasGotchaLanguage = GOTCHA_KEYWORDS.some((kw) => text.includes(kw));
-      const hasPatternLanguage = PATTERN_KEYWORDS.some((kw) => text.includes(kw));
-      return hasHighQuality || hasGotchaLanguage || hasPatternLanguage;
-    });
-
-    if (candidates.length === 0) {
-      logger.debug('PatternExtractor: no candidate steps found', { projectId });
-      return [];
-    }
-
-    // Look up repo_id from the project
-    const projectRow = this.db.get<{ repo_id: string }>(
-      `SELECT repo_id FROM projects WHERE id = ?`,
-      [projectId],
-    );
-    const repoId = projectRow?.repo_id ?? 'unknown';
-
-    // Promote each candidate (with deduplication)
-    const promoted: KnowledgeItem[] = [];
-
-    for (const step of candidates) {
-      const traj = trajectoryMap.get(step.trajectory_id);
-      const observation = buildObservationText(step);
-      const category = classifyCategory(step);
-
-      try {
-        // Check for near-duplicate in existing knowledge
-        const isDuplicate = await this.isDuplicateKnowledge(observation, category);
-        if (isDuplicate) {
-          logger.debug('PatternExtractor: skipping duplicate', {
-            action: step.action.slice(0, 60),
-          });
-          continue;
-        }
-
-        const item = await this.promoteToKnowledge(
-          observation,
-          category,
-          repoId,
-          traj ? (traj.phase as Phase) : undefined,
-          traj?.agent,
-        );
-        promoted.push(item);
-      } catch (err) {
-        // Non-fatal: log and continue to next candidate
-        logger.warn('PatternExtractor: failed to promote step', {
-          trajectoryId: step.trajectory_id,
-          error: String(err),
-        });
-      }
-    }
-
-    logger.info('PatternExtractor: extraction complete', {
-      projectId,
-      candidateCount: candidates.length,
-      promotedCount: promoted.length,
-    });
-
-    return promoted;
-  }
-
-  /**
-   * Promote a raw observation string to a full KnowledgeItem.
-   *
-   * Steps:
-   * 1. Synthesise a title from the first sentence of the observation.
-   * 2. Build a KnowledgeItem with appropriate defaults.
-   * 3. Add to the YAML store (the git-tracked source of truth).
-   * 4. Embed and upsert to Qdrant via hydrateItem() (if available).
-   * 5. Return the new item.
-   */
-  async promoteToKnowledge(
-    observation: string,
-    category: KnowledgeCategory,
-    repoId: string,
-    phase?: Phase | PipelinePhase,
-    agent?: string,
-  ): Promise<KnowledgeItem> {
-    const now = Date.now();
-    const prefix = categoryPrefix(category);
-    const id = `${prefix}-${randomUUID().slice(0, 8)}`;
-    const title = deriveTitle(observation, category);
-
-    const item: KnowledgeItem = {
-      id,
-      title,
-      content: observation,
-      stack_tags: [],           // Extracted without stack context; caller can enrich
-      confidence: 0.6,          // New items start at moderate confidence
-      source: 'agent',
-      // Phase values from both Phase and PipelinePhase unions are valid strings
-      // in YAML. We cast to satisfy the KnowledgeItem type declaration.
-      source_phase: (phase ?? null) as PipelinePhase | null,
-      source_agent: agent ?? null,
-      created_at: now,
-      updated_at: now,
-    };
-
-    // Persist to YAML (source of truth)
-    this.knowledgeStore.addItem(item);
-
-    // Embed and upsert to Qdrant via the KnowledgeSearch's backing store
-    // The KnowledgeSearch class does not expose hydrateItem directly — we
-    // go through the embedder + vectorStore path manually.
-    try {
-      const text = `${title} ${observation}`;
-      const vector = await this.embedder(text);
-
-      // Access the backing QdrantVectorStore from KnowledgeSearch
-      const store = (this.knowledgeSearch as unknown as {
-        vectorStore?: { upsertKnowledge?: (id: string, vector: number[], payload: Record<string, unknown>) => Promise<void> };
-      }).vectorStore;
-
-      if (store?.upsertKnowledge) {
-        await store.upsertKnowledge(id, vector, {
-          id,
-          repo_id: repoId,
-          category,
-          title,
-          content: observation,
-          stack_tags: [],
-          confidence: 0.6,
-          source: 'agent',
-          source_phase: phase ?? null,
-          source_agent: agent ?? null,
-          sharing: 'private',
-          created_at: now,
-          updated_at: now,
-          accessed_at: now,
-          access_count: 0,
-        });
-        logger.debug('PatternExtractor: item upserted to Qdrant', { id });
-      } else {
-        logger.debug('PatternExtractor: Qdrant upsert unavailable, YAML only', { id });
-      }
-    } catch (err) {
-      // Non-fatal: YAML write succeeded, Qdrant will be synced on next hydration
-      logger.warn('PatternExtractor: Qdrant upsert failed (YAML write succeeded)', {
-        id,
-        error: String(err),
-      });
-    }
-
-    logger.info('PatternExtractor: knowledge item promoted', {
-      id,
-      category,
-      title,
-      repoId,
-    });
-
-    return item;
-  }
-
-  // ---------------------------------------------------------------------------
-  // Private helpers
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Check whether the observation text is semantically too close to an
-   * existing knowledge item (similarity > 0.92). If so, we skip promotion
-   * to avoid building up near-duplicate entries over many projects.
-   */
-  private async isDuplicateKnowledge(
-    observation: string,
-    category: KnowledgeCategory,
-  ): Promise<boolean> {
-    try {
-      const results = await this.knowledgeSearch.search(observation, {
-        category,
-        limit: 1,
-        min_confidence: 0.0,
-      });
-
-      return results.length > 0 && results[0]!.relevance_score > 0.92;
-    } catch {
-      // If search fails, assume not duplicate so we don't lose knowledge
-      return false;
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Internal utilities
-// ---------------------------------------------------------------------------
-
-function buildObservationText(step: TrajectoryStepRow): string {
-  const parts: string[] = [step.action];
-  if (step.result) parts.push(step.result);
-  return parts.join('\n').trim();
-}
-
-function classifyCategory(step: TrajectoryStepRow): KnowledgeCategory {
-  const text = `${step.action} ${step.result ?? ''}`.toLowerCase();
-  const gotchaScore = GOTCHA_KEYWORDS.filter((kw) => text.includes(kw)).length;
-  const patternScore = PATTERN_KEYWORDS.filter((kw) => text.includes(kw)).length;
-
-  if (gotchaScore > patternScore) return 'gotcha';
-  if (patternScore > gotchaScore) return 'pattern';
-
-  // If quality score is high, lean toward "pattern" (positive finding)
-  if (step.quality_score !== null && step.quality_score >= QUALITY_THRESHOLD) {
-    return 'pattern';
-  }
-
-  return 'gotcha';
-}
-
-function categoryPrefix(category: KnowledgeCategory): string {
-  switch (category) {
-    case 'gotcha': return 'gotcha';
-    case 'pattern': return 'pattern';
-    case 'decision': return 'decision';
-    case 'convention': return 'convention';
-  }
-}
-
-function deriveTitle(observation: string, category: KnowledgeCategory): string {
-  // Use the first sentence (up to 80 chars) as the title
-  const firstSentence = observation.split(/[.!?\n]/)[0]?.trim() ?? observation;
-  const truncated = firstSentence.length > 80
-    ? firstSentence.slice(0, 77) + '...'
-    : firstSentence;
-
-  // Prefix with category for clarity when browsing YAML files
-  const prefix = category.charAt(0).toUpperCase() + category.slice(1);
-  return `${prefix}: ${truncated}`;
-}
-
-// Re-export keyword arrays so callers (e.g., tests) can reason about classification
-export { GOTCHA_KEYWORDS, PATTERN_KEYWORDS, QUALITY_THRESHOLD };

package/src/learning/trajectory.ts

@@ -1,268 +0,0 @@
-// TrajectoryRecorder — B10
-//
-// Server-side automatic trajectory recording. Agents do NOT call this directly
-// — the pipeline tool handlers call startTrajectory() and recordStep() as a
-// side effect of processing forge.start_* and forge.submit_* tool calls.
-//
-// Storage: SQLite `trajectories` and `trajectory_steps` tables.
-// All operations are synchronous (better-sqlite3). No async needed.
-//
-// Design notes:
-// - startTrajectory() is safe to call multiple times for the same
-//   (projectId, phase, agent) tuple — it creates a fresh trajectory each
-//   time, returning the new ID. Old active trajectories for the same project
-//   are left in the DB as historical records.
-// - recordStep() silently returns if `trajectoryId` is not found. This
-//   prevents a missing trajectory from crashing a tool handler.
-// - completeTrajectory() and failTrajectory() are idempotent — they only
-//   update rows whose status is 'active'.
-
-import { randomUUID } from 'node:crypto';
-import type { PipelineDB } from '../storage/sqlite.js';
-import type {
-  Trajectory,
-  TrajectoryRow,
-  TrajectoryStep,
-  TrajectoryStepRow,
-  TrajectoryStepMetadata,
-  PipelinePhase,
-} from '../util/types.js';
-import { logger } from '../util/logger.js';
-
-// ---------------------------------------------------------------------------
-// Row deserializers
-// ---------------------------------------------------------------------------
-
-function rowToTrajectory(row: TrajectoryRow): Trajectory {
-  return {
-    id: row.id,
-    projectId: row.project_id,
-    phase: row.phase as PipelinePhase,
-    agent: row.agent,
-    status: row.status,
-    startedAt: row.started_at,
-    completedAt: row.completed_at ?? null,
-    success: row.success === null ? null : row.success === 1,
-    feedback: row.feedback ?? null,
-  };
-}
-
-function rowToStep(row: TrajectoryStepRow): TrajectoryStep {
-  let metadata: TrajectoryStepMetadata = {};
-  try {
-    metadata = JSON.parse(row.metadata) as TrajectoryStepMetadata;
-  } catch {
-    metadata = {};
-  }
-  return {
-    id: row.id,
-    trajectoryId: row.trajectory_id,
-    action: row.action,
-    result: row.result ?? null,
-    qualityScore: row.quality_score ?? null,
-    metadata,
-    createdAt: row.created_at,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// TrajectoryRecorder
-// ---------------------------------------------------------------------------
-
-export class TrajectoryRecorder {
-  constructor(private readonly db: PipelineDB) {}
-
-  /**
-   * Start a new trajectory for the given project / phase / agent.
-   * Returns the UUID of the newly created trajectory.
-   *
-   * Side-effect: any previously active trajectory for this project is NOT
-   * auto-closed — they are left as historical data. The caller is responsible
-   * for calling completeTrajectory() or failTrajectory() when appropriate.
-   */
-  startTrajectory(projectId: string, phase: PipelinePhase, agent: string): string {
-    const id = randomUUID();
-    const now = Date.now();
-
-    this.db.run(
-      `INSERT INTO trajectories (id, project_id, phase, agent, status, started_at, completed_at, success, feedback)
-       VALUES (?, ?, ?, ?, 'active', ?, NULL, NULL, NULL)`,
-      [id, projectId, phase, agent, now],
-    );
-
-    logger.debug('TrajectoryRecorder: trajectory started', {
-      id,
-      projectId,
-      phase,
-      agent,
-    });
-
-    return id;
-  }
-
-  /**
-   * Record a step in an existing trajectory.
-   * Silently returns when the trajectoryId does not exist in the DB — this
-   * prevents missing trajectories from surfacing as user-facing errors.
-   */
-  recordStep(
-    trajectoryId: string,
-    action: string,
-    result?: string,
-    qualityScore?: number,
-    metadata?: Record<string, unknown>,
-  ): void {
-    const now = Date.now();
-
-    try {
-      this.db.run(
-        `INSERT INTO trajectory_steps (trajectory_id, action, result, quality_score, metadata, created_at)
-         VALUES (?, ?, ?, ?, ?, ?)`,
-        [
-          trajectoryId,
-          action,
-          result ?? null,
-          qualityScore ?? null,
-          JSON.stringify(metadata ?? {}),
-          now,
-        ],
-      );
-
-      logger.debug('TrajectoryRecorder: step recorded', {
-        trajectoryId,
-        action: action.slice(0, 80),
-        qualityScore,
-      });
-    } catch (err) {
-      // Non-fatal — step recording must never crash the tool handler
-      logger.warn('TrajectoryRecorder: failed to record step (non-fatal)', {
-        trajectoryId,
-        error: String(err),
-      });
-    }
-  }
-
-  /**
-   * Mark a trajectory as successfully completed.
-   * Idempotent — only updates rows with status='active'.
-   */
-  completeTrajectory(trajectoryId: string, feedback?: string): void {
-    this.db.run(
-      `UPDATE trajectories
-       SET status = 'complete', completed_at = ?, success = 1, feedback = ?
-       WHERE id = ? AND status = 'active'`,
-      [Date.now(), feedback ?? null, trajectoryId],
-    );
-    logger.debug('TrajectoryRecorder: trajectory completed', { trajectoryId });
-  }
-
-  /**
-   * Mark a trajectory as failed.
-   * Idempotent — only updates rows with status='active'.
-   */
-  failTrajectory(trajectoryId: string, feedback?: string): void {
-    this.db.run(
-      `UPDATE trajectories
-       SET status = 'failed', completed_at = ?, success = 0, feedback = ?
-       WHERE id = ? AND status = 'active'`,
-      [Date.now(), feedback ?? null, trajectoryId],
-    );
-    logger.debug('TrajectoryRecorder: trajectory failed', { trajectoryId });
-  }
-
-  /**
-   * Return the most recent active trajectory for a project, or null.
-   * "Active" means status = 'active'.
-   */
-  getActiveTrajectory(projectId: string): Trajectory | null {
-    const row = this.db.get<TrajectoryRow>(
-      `SELECT * FROM trajectories
-       WHERE project_id = ? AND status = 'active'
-       ORDER BY started_at DESC LIMIT 1`,
-      [projectId],
-    );
-    return row ? rowToTrajectory(row) : null;
-  }
-
-  /**
-   * Return all trajectories for a project, ordered by started_at ascending.
-   */
-  getTrajectories(projectId: string): Trajectory[] {
-    const rows = this.db.all<TrajectoryRow>(
-      `SELECT * FROM trajectories WHERE project_id = ? ORDER BY started_at ASC`,
-      [projectId],
-    );
-    return rows.map(rowToTrajectory);
-  }
-
-  /**
-   * Return all steps for a trajectory, ordered by created_at ascending.
-   */
-  getSteps(trajectoryId: string): TrajectoryStep[] {
-    const rows = this.db.all<TrajectoryStepRow>(
-      `SELECT * FROM trajectory_steps WHERE trajectory_id = ? ORDER BY created_at ASC`,
-      [trajectoryId],
-    );
-    return rows.map(rowToStep);
-  }
-
-  /**
-   * Produce a summary of all trajectory activity for a project.
-   * Used by the knowledge_collection phase to feed the PatternExtractor.
-   */
-  getSummary(projectId: string): {
-    totalSteps: number;
-    phasesCompleted: number;
-    cycles: Record<string, number>;
-    durationMinutes: number;
-  } {
-    const trajectories = this.getTrajectories(projectId);
-
-    if (trajectories.length === 0) {
-      return {
-        totalSteps: 0,
-        phasesCompleted: 0,
-        cycles: {},
-        durationMinutes: 0,
-      };
-    }
-
-    // Count total steps across all trajectories
-    const totalStepsRow = this.db.get<{ cnt: number }>(
-      `SELECT COUNT(*) as cnt FROM trajectory_steps ts
-       JOIN trajectories t ON ts.trajectory_id = t.id
-       WHERE t.project_id = ?`,
-      [projectId],
-    );
-    const totalSteps = totalStepsRow?.cnt ?? 0;
-
-    // Count completed phases
-    const phasesCompleted = trajectories.filter(
-      (t) => t.status === 'complete' && t.success === true,
-    ).length;
-
-    // Count cycles: phases that appear more than once in completed trajectories
-    const phaseCompletions = trajectories
-      .filter((t) => t.status === 'complete')
-      .reduce<Record<string, number>>((acc, t) => {
-        acc[t.phase] = (acc[t.phase] ?? 0) + 1;
-        return acc;
-      }, {});
-
-    const cycles: Record<string, number> = {};
-    for (const [phase, count] of Object.entries(phaseCompletions)) {
-      if (count > 1) {
-        cycles[phase] = count - 1; // cycles = extra runs beyond the first
-      }
-    }
-
-    // Duration: from first startedAt to last completedAt (or now if still active)
-    const firstStart = Math.min(...trajectories.map((t) => t.startedAt));
-    const lastEnd = Math.max(
-      ...trajectories.map((t) => t.completedAt ?? Date.now()),
-    );
-    const durationMinutes = Math.round((lastEnd - firstStart) / 60_000);
-
-    return { totalSteps, phasesCompleted, cycles, durationMinutes };
-  }
-}