forge-server 0.1.0

package/src/learning/patterns.ts

@@ -0,0 +1,360 @@
+// 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

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