forge-server 0.1.0

package/dist/memory/session-tracker.js

@@ -0,0 +1,262 @@
+/**
+ * Session lifecycle and context tracking.
+ * Tracks current session ID, start time, and provides session-scoped observation queries.
+ * Sessions are identified by a timestamp-based ID generated at server startup.
+ *
+ * Phase 3: Sessions persist as Observation nodes in Qdrant with type: 'session_marker'.
+ * Cross-session retrieval queries those nodes to build a session registry.
+ */
+import { randomUUID } from 'crypto';
+import { embedText } from '../ingestion/embedder.js';
+import { logger } from '../util/logger.js';
+// The active session for this server process (created at startup)
+// Format: session-{timestamp} as specified in the architecture
+const SESSION_TIMESTAMP = Date.now();
+const SESSION_ID = `session-${SESSION_TIMESTAMP}`;
+const SESSION_START = SESSION_TIMESTAMP;
+// Track observation count for this session (in-memory)
+let observationCount = 0;
+// Whether we have already persisted this session's marker to Qdrant
+let sessionMarkerPersisted = false;
+/**
+ * Get the current session ID.
+ * Format: session-{timestamp}. Consistent for the lifetime of the MCP server process.
+ */
+export function getCurrentSessionId() {
+    return SESSION_ID;
+}
+/**
+ * Get the session start timestamp (Unix ms).
+ */
+export function getSessionStart() {
+    return SESSION_START;
+}
+/**
+ * Get session uptime in seconds.
+ */
+export function getUptimeSeconds() {
+    return Math.round((Date.now() - SESSION_START) / 1000);
+}
+/**
+ * Increment the in-memory observation count for this session.
+ * Called by observation-store after a successful save.
+ */
+export function incrementObservationCount() {
+    observationCount++;
+}
+/**
+ * Get the current session observation count.
+ */
+export function getObservationCount() {
+    return observationCount;
+}
+/**
+ * Persist the current session as a session_marker observation in Qdrant.
+ * This enables cross-session discovery — other processes can find recent sessions
+ * by searching for type: 'session_marker' observations.
+ *
+ * Idempotent — only writes once per process lifecycle.
+ */
+export async function persistSessionMarker(vectorStore) {
+    if (sessionMarkerPersisted)
+        return;
+    try {
+        const markerId = randomUUID();
+        const content = `Session ${SESSION_ID} started at ${new Date(SESSION_START).toISOString()}`;
+        // Embed the session marker content for potential semantic retrieval
+        let vector;
+        try {
+            vector = await embedText(content);
+        }
+        catch {
+            vector = new Array(384).fill(0);
+        }
+        const markerPayload = {
+            id: markerId,
+            repo_id: null,
+            session_id: SESSION_ID,
+            content,
+            type: 'working', // session markers are working memory
+            category: 'session_marker',
+            tags: ['session_marker'],
+            importance: 0.1,
+            created_at: SESSION_START,
+            accessed_at: SESSION_START,
+            access_count: 0,
+            is_stale: false,
+            linked_symbols: [],
+            source: 'forge',
+            metadata: {
+                session_id: SESSION_ID,
+                started_at: SESSION_START,
+                is_session_marker: true,
+            },
+            key: SESSION_ID,
+            namespace: 'session_registry',
+        };
+        await vectorStore.upsertObservation(markerId, vector, markerPayload);
+        sessionMarkerPersisted = true;
+        logger.debug('Session marker persisted', { sessionId: SESSION_ID });
+    }
+    catch (err) {
+        logger.warn('Failed to persist session marker (non-fatal)', { error: String(err) });
+    }
+}
+/**
+ * Retrieve recent session IDs and their start times from Qdrant.
+ * Queries for session_marker observations ordered by created_at descending.
+ */
+export async function getRecentSessions(vectorStore, count = 5) {
+    try {
+        const filter = {
+            must: [
+                { key: 'namespace', match: { value: 'session_registry' } },
+                { key: 'tags', match: { value: 'session_marker' } },
+            ],
+        };
+        const results = await vectorStore.filterObservations(filter, count * 2);
+        const sessions = results
+            .map(r => {
+            const payload = r.payload;
+            return {
+                sessionId: payload.session_id,
+                startedAt: payload.created_at,
+            };
+        })
+            // Sort by startedAt descending (most recent first)
+            .sort((a, b) => b.startedAt - a.startedAt)
+            // Deduplicate by sessionId (keep first/most-recent occurrence)
+            .filter((s, idx, arr) => arr.findIndex(x => x.sessionId === s.sessionId) === idx)
+            .slice(0, count);
+        return sessions;
+    }
+    catch (err) {
+        logger.warn('Failed to get recent sessions', { error: String(err) });
+        return [];
+    }
+}
+/**
+ * Get observations from recent sessions.
+ * Phase 3: Queries the persistent session registry to find sessions,
+ * then retrieves observations for each one.
+ *
+ * If a query is provided, observations are ranked by semantic relevance.
+ * Otherwise they are returned in reverse chronological order.
+ */
+export async function getRecentSessionObservations(vectorStore, opts) {
+    const { query, queryVector, sessionCount = 3, limit = 10 } = opts;
+    try {
+        // Always include the current session
+        const recentSessions = await getRecentSessions(vectorStore, sessionCount);
+        // Ensure the current session is included even if not yet persisted
+        const sessionIds = new Set(recentSessions.map(s => s.sessionId));
+        sessionIds.add(SESSION_ID);
+        // Build the full session list with timestamps
+        const sessionsWithTime = [
+            { sessionId: SESSION_ID, startedAt: SESSION_START },
+            ...recentSessions.filter(s => s.sessionId !== SESSION_ID),
+        ].slice(0, sessionCount);
+        // Determine the query vector for relevance ranking
+        let resolvedQueryVector = queryVector;
+        if (query && !resolvedQueryVector) {
+            try {
+                resolvedQueryVector = await embedText(query);
+            }
+            catch {
+                resolvedQueryVector = undefined;
+            }
+        }
+        // Retrieve observations per session
+        const groups = [];
+        let remainingLimit = limit;
+        for (const session of sessionsWithTime) {
+            if (remainingLimit <= 0)
+                break;
+            const sessionObs = await getSessionObservations(vectorStore, session.sessionId, resolvedQueryVector, remainingLimit);
+            if (sessionObs.length > 0) {
+                groups.push({
+                    sessionId: session.sessionId,
+                    startedAt: session.startedAt,
+                    observations: sessionObs,
+                });
+                remainingLimit -= sessionObs.length;
+            }
+        }
+        return groups;
+    }
+    catch (err) {
+        logger.warn('Failed to get recent session observations', { error: String(err) });
+        return [];
+    }
+}
+/**
+ * Retrieve observations for a specific session from Qdrant.
+ * Excludes session_marker observations and stale observations.
+ * If a queryVector is provided, filters use it for ordering but Qdrant scroll
+ * doesn't support semantic ranking — we fetch extra and sort in memory.
+ */
+async function getSessionObservations(vectorStore, sessionId, queryVector, limit = 10) {
+    try {
+        // If we have a query vector, use semantic search for this session
+        if (queryVector) {
+            const results = await vectorStore.searchObservations(queryVector, {
+                limit: limit * 3,
+                scoreThreshold: 0.0,
+                filter: {
+                    must: [
+                        { key: 'session_id', match: { value: sessionId } },
+                    ],
+                    must_not: [
+                        { key: 'tags', match: { value: 'session_marker' } },
+                    ],
+                },
+            });
+            return results
+                .map(r => {
+                const payload = r.payload;
+                return {
+                    id: payload.id,
+                    content: payload.content,
+                    relevance_score: Math.round(r.score * 1000) / 1000,
+                    is_stale: payload.is_stale,
+                };
+            })
+                .filter(o => !o.is_stale)
+                .slice(0, limit);
+        }
+        // No query vector: use scroll (filterObservations) for chronological retrieval
+        const filter = {
+            session_id: sessionId,
+        };
+        const results = await vectorStore.filterObservations(filter, limit * 2);
+        return results
+            .map(r => {
+            const payload = r.payload;
+            return {
+                id: payload.id,
+                content: payload.content,
+                relevance_score: r.score,
+                is_stale: payload.is_stale,
+            };
+        })
+            // Exclude session_marker observations from result listing
+            .filter(o => !o.is_stale)
+            .slice(0, limit);
+    }
+    catch (err) {
+        logger.warn('Failed to get session observations', { sessionId, error: String(err) });
+        return [];
+    }
+}
+/**
+ * Get the current session info summary.
+ */
+export function getSessionInfo() {
+    return {
+        sessionId: SESSION_ID,
+        startedAt: SESSION_START,
+        uptimeSeconds: getUptimeSeconds(),
+        observationCount,
+    };
+}
+//# sourceMappingURL=session-tracker.js.map

package/dist/memory/session-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-tracker.js","sourceRoot":"","sources":["../../src/memory/session-tracker.ts"],"names":[],"mappings":"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"}

package/dist/pipeline/engine.d.ts

@@ -0,0 +1,179 @@
+import type { PipelineDB } from '../storage/sqlite.js';
+import type { Phase, PipelineTier, Project, ProjectMetadata, Trajectory, TrajectoryStepMetadata, PhaseOutput, Claim, ClaimStatus, PipelineEvent } from '../util/types.js';
+export interface CreateProjectOptions {
+    name: string;
+    description?: string;
+    repoId: string;
+    tier?: PipelineTier;
+    metadata?: ProjectMetadata;
+}
+export interface TransitionResult {
+    projectId: string;
+    fromPhase: Phase;
+    toPhase: Phase;
+    trajectoryId: string;
+    cycleCounts: Record<string, number>;
+    availableTransitions: Phase[];
+}
+/** Full project state snapshot — returned by getState(). */
+export interface EngineState {
+    project: Project;
+    history: PipelineEvent[];
+    activeClaims: Claim[];
+    cycleCounts: Record<string, number>;
+    availableTransitions: Phase[];
+}
+export interface ProjectState {
+    project: Project;
+    activeTrajectory: Trajectory | null;
+    cycleCounts: Record<string, number>;
+    availableTransitions: Phase[];
+    activeClaims: Claim[];
+}
+export interface PhaseHistory {
+    phase: Phase;
+    agent: string;
+    startedAt: string;
+    completedAt?: string;
+    success?: boolean;
+}
+export interface ProjectHistory {
+    projectId: string;
+    events: PipelineEvent[];
+    outputs: PhaseOutput[];
+    history: PhaseHistory[];
+}
+export type PipelineEngineErrorCode = 'PROJECT_NOT_FOUND' | 'PROJECT_NOT_ACTIVE' | 'INVALID_TRANSITION' | 'CYCLE_LIMIT_EXCEEDED';
+export declare class PipelineEngineError extends Error {
+    readonly code: PipelineEngineErrorCode;
+    readonly details: Record<string, unknown>;
+    constructor(code: PipelineEngineErrorCode, message: string, details?: Record<string, unknown>);
+}
+export declare class PipelineEngine {
+    private readonly db;
+    constructor(db: PipelineDB);
+    createProject(opts: CreateProjectOptions): Project;
+    getProject(projectId: string): Project | null;
+    /**
+     * Lists projects with optional repo and status filters.
+     * Ordered by updated_at DESC (most recently modified first).
+     */
+    listProjects(repoId?: string, status?: string): Project[];
+    /**
+     * Returns the most recently updated active project for a repo, or null when
+     * there is no active project for that repo.
+     */
+    getActiveProject(repoId: string): Project | null;
+    /**
+     * Returns the full current state of a project: project data, full event
+     * history, active claims, derived cycle counts, and available transitions.
+     *
+     * Throws PipelineEngineError with code PROJECT_NOT_FOUND when the project
+     * does not exist.
+     */
+    getState(projectId: string): EngineState;
+    /**
+     * Atomically advances a project to `toPhase` in a single SQLite transaction:
+     *   1. Validates the transition (throws on illegal transitions).
+     *   2. Checks cycle limits (throws CYCLE_LIMIT_EXCEEDED; details include the
+     *      forced advance phase so callers can decide how to proceed).
+     *   3. Inserts a phase_transition event.
+     *   4. Updates projects.current_phase and updated_at.
+     *   5. If toPhase === 'completed', marks the project status 'complete' and
+     *      emits an additional project_completed event.
+     *
+     * Throws PipelineEngineError for invalid transitions and cycle limit exceeded.
+     * All writes are in a single better-sqlite3 transaction.
+     */
+    advancePhase(projectId: string, toPhase: Phase, agent?: string, payload?: Record<string, unknown>): void;
+    /**
+     * Persists a phase output to phase_outputs. Multiple outputs per phase are
+     * allowed (e.g., vision doc, refined vision doc, etc.).
+     *
+     * Throws PipelineEngineError with code PROJECT_NOT_FOUND when the project
+     * does not exist.
+     */
+    recordOutput(projectId: string, phase: Phase, outputType: string, content: string, filePath?: string): void;
+    /**
+     * Returns phase outputs for a project, optionally filtered to a specific
+     * phase. Ordered by created_at ASC.
+     */
+    getOutputs(projectId: string, phase?: Phase): PhaseOutput[];
+    /**
+     * Returns all events for a project ordered by created_at ASC.
+     * This is the raw event sourcing log used for history reconstruction.
+     */
+    getEventHistory(projectId: string): PipelineEvent[];
+    /**
+     * Marks a project as 'archived'. Emits a project_completed event with an
+     * 'abandoned' flag. Idempotent if already archived.
+     *
+     * Throws PipelineEngineError with code PROJECT_NOT_FOUND when the project
+     * does not exist.
+     */
+    abandonProject(projectId: string): void;
+    /**
+     * Transition a project to a new phase.
+     * Validates the transition against the state machine, emits events,
+     * starts a trajectory, and returns the result.
+     */
+    startPhase(projectId: string, toPhase: Phase, agent: string, extra?: Record<string, unknown>): TransitionResult | {
+        error: string;
+        current_phase: Phase;
+        legal_transitions: Phase[];
+    };
+    /**
+     * Record completion of a phase: persist output, complete the trajectory,
+     * and optionally advance the state machine.
+     */
+    completePhase(projectId: string, phase: Phase, outputType: string, content: string, opts: {
+        agent: string;
+        filePath?: string;
+        advanceTo?: Phase;
+        trajectoryId?: string;
+        qualityScore?: number;
+        metadata?: Record<string, unknown>;
+    }): {
+        outputId: number;
+        nextPhase: Phase | null;
+    };
+    startTrajectory(projectId: string, phase: Phase, agent: string): string;
+    recordTrajectoryStep(trajectoryId: string, action: string, result?: string, qualityScore?: number, metadata?: TrajectoryStepMetadata): void;
+    completeTrajectory(trajectoryId: string, success: boolean, feedback?: string): void;
+    createClaim(projectId: string, moduleName: string, agent: string): Claim;
+    completeClaim(claimId: string, result?: string): {
+        remainingCount: number;
+        allComplete: boolean;
+    };
+    failClaim(claimId: string, reason: string): void;
+    getActiveClaims(projectId: string): Claim[];
+    getClaims(projectId: string, status?: ClaimStatus): Claim[];
+    getClaim(claimId: string): Claim | null;
+    getClaimByModule(projectId: string, moduleName: string): Claim | null;
+    getPhaseOutput(projectId: string, phase: Phase, outputType?: string): PhaseOutput | null;
+    /**
+     * Retrieve metadata stored in the agent_completed event for a phase.
+     * This includes flags like requires_qa, requires_designer, modules, etc.
+     * that are passed via opts.metadata in completePhase().
+     */
+    getPhaseMetadata(projectId: string, phase: Phase): Record<string, unknown> | null;
+    /**
+     * Record a broadcast event in the pipeline_events table.
+     * Used by phase tools to auto-broadcast module completions for swarm coordination.
+     */
+    recordBroadcast(projectId: string, content: string, severity?: 'info' | 'warning' | 'critical'): void;
+    getAllPhaseOutputs(projectId: string): PhaseOutput[];
+    getHistory(projectId: string): ProjectHistory;
+    getCycleCounts(projectId: string): Record<string, number>;
+    private _getCycleCounts;
+    /**
+     * Retrieves a project by id and throws a typed PipelineEngineError when not
+     * found. Used by every method that requires an existing project.
+     */
+    private _requireProject;
+    private _rowToProject;
+    private _rowToClaim;
+    private _rowToPhaseOutput;
+    getActiveTrajectory(projectId: string, phase: Phase): Trajectory | null;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/pipeline/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/pipeline/engine.ts"],"names":[],"mappings":"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"}