frappe-builder 1.1.0-dev.8

package/extensions/frappe-session.ts

@@ -0,0 +1,324 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { db } from "../state/db.js";
+import { createFsmAtPhase, type Phase } from "../state/fsm.js";
+
+/** Maps FSM phases to their specialist names. frappe-debugger is manually invoked (Story 3.5). */
+export const PHASE_TO_SPECIALIST: Record<string, string | null> = {
+  idle: null,
+  requirements: "frappe-ba",
+  architecture: "frappe-architect",
+  planning: "frappe-planner",
+  implementation: "frappe-dev",
+  testing: "frappe-qa",
+  documentation: "frappe-docs",
+};
+
+/** Context object injected into a specialist's activation block. */
+export interface SpecialistContext {
+  activeProject: string;
+  featureName: string;
+  currentPhase: string;
+  progressDone: number;
+  progressTotal: number;
+  lastTool: string;
+}
+
+/**
+ * Builds specialist context by reading the active session and feature from state.db.
+ * Synchronous (better-sqlite3). Never throws — returns safe defaults on any failure.
+ */
+export function buildStateContext(featureId: string | null, lastTool = ""): SpecialistContext {
+  const defaults: SpecialistContext = {
+    activeProject: "unknown",
+    featureName: "unknown",
+    currentPhase: "idle",
+    progressDone: 0,
+    progressTotal: 0,
+    lastTool: lastTool || "none",
+  };
+  try {
+    const session = db
+      .prepare(
+        "SELECT project_id, feature_id, current_phase, last_tool FROM sessions WHERE is_active = 1 LIMIT 1"
+      )
+      .get() as {
+        project_id: string;
+        feature_id: string | null;
+        current_phase: string;
+        last_tool: string | null;
+      } | undefined;
+
+    if (!session) return defaults;
+
+    const fid = featureId ?? session.feature_id ?? null;
+    const feature = fid
+      ? (db.prepare("SELECT name FROM features WHERE feature_id = ?").get(fid) as { name: string } | undefined)
+      : undefined;
+
+    const components = fid
+      ? (db.prepare("SELECT status FROM components WHERE feature_id = ?").all(fid) as { status: string }[])
+      : [];
+
+    const done = components.filter((c) => c.status === "complete").length;
+
+    return {
+      activeProject: session.project_id ?? "unknown",
+      featureName: feature?.name ?? "unknown",
+      currentPhase: session.current_phase ?? "idle",
+      progressDone: done,
+      progressTotal: components.length,
+      lastTool: lastTool || session.last_tool || "none",
+    };
+  } catch {
+    return defaults;
+  }
+}
+
+/**
+ * Returns a formatted specialist activation block for the given phase.
+ * Returns empty string for idle phase (no specialist) or unknown phases.
+ * Pure function — no DB access, no side effects.
+ */
+export function loadSpecialist(phase: string, ctx: SpecialistContext): string {
+  const specialistName = PHASE_TO_SPECIALIST[phase] ?? null;
+  if (!specialistName) return "";
+  return [
+    `## Active Specialist: ${specialistName}`,
+    `Project: ${ctx.activeProject} | Feature: ${ctx.featureName} | Phase: ${ctx.currentPhase}`,
+    `Progress: ${ctx.progressDone}/${ctx.progressTotal} components | Last tool: ${ctx.lastTool}`,
+  ].join("\n");
+}
+
+/**
+ * Returns a formatted activation block for the frappe-debugger specialist.
+ * frappe-debugger is NOT phase-driven — it is invoked directly (Story 3.5).
+ * Never throws — pure function, no DB access.
+ */
+export function loadDebuggerSpecialist(ctx: SpecialistContext): string {
+  return [
+    `## Active Specialist: frappe-debugger`,
+    `Project: ${ctx.activeProject} | Feature: ${ctx.featureName} | Phase: ${ctx.currentPhase}`,
+    `Progress: ${ctx.progressDone}/${ctx.progressTotal} components | Last tool: ${ctx.lastTool}`,
+  ].join("\n");
+}
+
+/** Row shapes returned from SQLite queries. */
+interface SessionRow {
+  session_id: string;
+  project_id: string;
+  site_path: string | null;
+  feature_id: string | null;
+  current_phase: string;
+  last_tool: string | null;
+  is_active: number;
+}
+
+interface FeatureRow {
+  feature_id: string;
+  name: string;
+  current_phase: string;
+}
+
+interface ComponentRow {
+  component_id: string;
+  feature_id: string;
+  status: string;
+}
+
+/** Reconstructed session context used for prompt injection. */
+export interface SessionContext {
+  projectId: string;
+  sitePath?: string | null;
+  featureName: string | null;
+  phase: string;
+  componentsDone: number;
+  componentsTotal: number;
+  lastTool: string | null;
+}
+
+/** Returns the sessions directory for JSONL files. */
+function getSessionsDir(): string {
+  return join(homedir(), ".frappe-builder", "sessions");
+}
+
+/** Reads the last N non-empty lines from a JSONL file efficiently. */
+function readLastLines(filePath: string, n: number): string[] {
+  if (!existsSync(filePath)) return [];
+  const content = readFileSync(filePath, "utf-8");
+  return content.split("\n").filter(Boolean).slice(-n);
+}
+
+/** Returns a blank session context for fresh/unknown starts. */
+function freshSession(): SessionContext {
+  return {
+    projectId: "unknown",
+    sitePath: null,
+    featureName: null,
+    phase: "idle",
+    componentsDone: 0,
+    componentsTotal: 0,
+    lastTool: null,
+  };
+}
+
+/** Creates a fresh session row in the sessions table. */
+function createFreshSession(projectId = "default"): void {
+  db.prepare(`
+    INSERT INTO sessions (session_id, project_id, current_phase, started_at, is_active)
+    VALUES (?, ?, 'idle', ?, 1)
+  `).run(randomUUID(), projectId, new Date().toISOString());
+}
+
+/**
+ * Reconstructs session context from SQLite state.
+ * On any error returns a fresh idle context and logs a warning — never throws.
+ */
+export async function reconstructSession(): Promise<SessionContext> {
+  try {
+    const session = db
+      .prepare("SELECT * FROM sessions WHERE is_active = 1 LIMIT 1")
+      .get() as SessionRow | undefined;
+
+    if (!session) {
+      createFreshSession();
+      return freshSession();
+    }
+
+    const feature = session.feature_id
+      ? (db
+          .prepare("SELECT * FROM features WHERE feature_id = ?")
+          .get(session.feature_id) as FeatureRow | undefined)
+      : undefined;
+
+    const components = feature
+      ? (db
+          .prepare("SELECT * FROM components WHERE feature_id = ?")
+          .all(feature.feature_id) as ComponentRow[])
+      : [];
+
+    const done = components.filter((c) => c.status === "complete").length;
+
+    return {
+      projectId: session.project_id,
+      sitePath: session.site_path ?? null,
+      featureName: feature?.name ?? null,
+      phase: session.current_phase,
+      componentsDone: done,
+      componentsTotal: components.length,
+      lastTool: session.last_tool ?? null,
+    };
+  } catch (err) {
+    console.warn(
+      `[frappe-session] State reconstruction failed: ${err}. Starting fresh.`
+    );
+    return freshSession();
+  }
+}
+
+/**
+ * Builds the concise state injection string for the system prompt.
+ * Kept under 500 tokens to respect NFR2 (≤15% context window).
+ */
+export function buildStateInjection(ctx: SessionContext): string {
+  const progress =
+    ctx.componentsTotal > 0
+      ? `${ctx.componentsDone}/${ctx.componentsTotal} components complete`
+      : "no components tracked";
+
+  const lines = [
+    "=== FRAPPE-BUILDER SESSION CONTEXT ===",
+    `Project: ${ctx.projectId}`,
+  ];
+  if (ctx.sitePath) lines.push(`Site: ${ctx.sitePath}`);
+  lines.push(
+    `Feature: ${ctx.featureName ?? "none"}`,
+    `Phase: ${ctx.phase}`,
+    `Progress: ${progress}`,
+    `Last action: ${ctx.lastTool ?? "none"}`,
+    "======================================"
+  );
+  return lines.join("\n");
+}
+
+/**
+ * Returns the current FSM phase from the active session, validated via the Robot3 FSM.
+ * Creates a fast-forward FSM instance to confirm the stored phase is a known state.
+ * Falls back to "idle" on any error.
+ */
+export function getRestoredPhase(): Phase {
+  try {
+    const row = db
+      .prepare("SELECT current_phase FROM sessions WHERE is_active = 1 LIMIT 1")
+      .get() as { current_phase: string } | undefined;
+    const phase = (row?.current_phase ?? "idle") as Phase;
+    createFsmAtPhase(phase); // validates phase is a known FSM state
+    return phase;
+  } catch {
+    return "idle";
+  }
+}
+
+/**
+ * Session start handler — reconstructs state from SQLite and returns the
+ * system prompt injection string. Call this at agent startup before the
+ * first LLM prompt is sent (NFR1: must complete in <500ms).
+ *
+ * Includes specialist activation block when phase is not idle (Story 3.4).
+ * Never throws — on any failure returns a fresh idle context.
+ */
+export async function handleSessionStart(): Promise<string> {
+  try {
+    const ctx = await reconstructSession();
+
+    // Read last 10 JSONL entries for additional context (last action detail)
+    const sessionRow = db
+      .prepare("SELECT session_id FROM sessions WHERE is_active = 1 LIMIT 1")
+      .get() as { session_id: string } | undefined;
+
+    if (sessionRow) {
+      const journalPath = join(
+        getSessionsDir(),
+        `${sessionRow.session_id}.jsonl`
+      );
+      readLastLines(journalPath, 10); // read for context; unused in prompt for now
+    }
+
+    const stateBlock = buildStateInjection(ctx);
+
+    // Specialist auto-load on session resume (Story 3.4)
+    // AGENTS.md base identity (Nexus) is loaded natively by pi from project root.
+    if (ctx.phase !== "idle") {
+      try {
+        const specCtx = buildStateContext(null, "session_start");
+        const specialistBlock = loadSpecialist(ctx.phase, specCtx);
+        if (specialistBlock) return `${stateBlock}\n\n${specialistBlock}`;
+      } catch (specialistErr) {
+        console.warn(`[frappe-session] specialist load failed at session start: ${specialistErr}`);
+      }
+    }
+
+    return stateBlock;
+  } catch (err) {
+    console.warn(`[frappe-session] handleSessionStart failed: ${err}. Using idle context.`);
+    return buildStateInjection(freshSession());
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export default function (pi: any) {
+  pi.on("session_start", async () => {
+    await handleSessionStart();
+  });
+}
+
+/**
+ * Reloads session context after a project switch.
+ * Reconstructs state from SQLite and returns the updated prompt injection string.
+ * Called by setActiveProject() after switchProject() creates the new session.
+ */
+export async function reloadSessionContext(): Promise<void> {
+  await handleSessionStart();
+}

package/extensions/frappe-state.ts

@@ -0,0 +1,235 @@
+import type { AfterToolCallContext, AfterToolCallResult } from "@mariozechner/pi-agent-core";
+import type { TextContent } from "@mariozechner/pi-ai";
+import { db, getCurrentPhase } from "../state/db.js";
+import { appendEntry } from "../state/journal.js";
+import { buildStateContext, loadSpecialist, loadDebuggerSpecialist } from "./frappe-session.js";
+import { loadCredentials } from "../config/loader.js";
+
+/** Reads current_phase and feature_id from the active session. */
+function readSessionState(): { currentPhase: string; activeFeatureId: string | null } {
+  const row = db
+    .prepare("SELECT current_phase, feature_id FROM sessions WHERE is_active = 1 LIMIT 1")
+    .get() as { current_phase: string; feature_id: string | null } | undefined;
+  return {
+    currentPhase: row?.current_phase ?? "idle",
+    activeFeatureId: row?.feature_id ?? null,
+  };
+}
+
+/** Queries the active session_id from SQLite, or returns a fallback. */
+function getActiveSessionId(): string {
+  const row = db
+    .prepare("SELECT session_id FROM sessions WHERE is_active = 1 LIMIT 1")
+    .get() as { session_id: string } | undefined;
+  return row?.session_id ?? "unknown";
+}
+
+/** Type guard for SpawnAgentResult from agent-tools.ts. */
+function isSpawnAgentResult(value: unknown): value is { status: string; skill: string; trigger: string } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "status" in value &&
+    "skill" in value &&
+    "trigger" in value
+  );
+}
+
+/** Type guard for the return value of startFeature(). */
+function isStartFeatureResult(value: unknown): value is { mode: string; feature_id: string } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "mode" in value &&
+    "feature_id" in value &&
+    typeof (value as Record<string, unknown>).mode === "string" &&
+    typeof (value as Record<string, unknown>).feature_id === "string"
+  );
+}
+
+/**
+ * Atomically updates sessions.current_phase and features.current_phase in state.db.
+ * Throws on DB failure — caller (handleAfterToolCall) converts to banner.
+ */
+function applyPhaseTransition(featureId: string, newPhase: string): void {
+  db.transaction(() => {
+    db.prepare("UPDATE sessions SET current_phase = ? WHERE is_active = 1").run(newPhase);
+    db.prepare("UPDATE features SET current_phase = ? WHERE feature_id = ?").run(newPhase, featureId);
+  })();
+}
+
+/**
+ * Session start hook — validates gitignore and loads credentials before any session setup.
+ * Throws with AC error message if .frappe-builder-config.json is not gitignored.
+ * Call this early in the session_start lifecycle; on throw, halt and surface the message.
+ * projectRoot defaults to process.cwd() when not supplied by the pi extension system.
+ *
+ * TODO: wire this into the pi extension system's session_start event once the
+ * session_start hook type is confirmed in @mariozechner/pi-agent-core.
+ */
+export function handleSessionStart(projectRoot: string = process.cwd()): void {
+  loadCredentials(projectRoot);
+}
+
+/**
+ * afterToolCall hook — appends a JSONL journal entry and updates the sessions
+ * table in a single synchronous transaction after every tool call.
+ *
+ * Also handles FSM phase transition when start_feature fires (Story 3.3).
+ * Mode routing never touches gate execution — quality gates run independently
+ * in frappe-gates.ts regardless of mode (full or quick).
+ *
+ * Never throws. On write failure, appends a [STATE WRITE FAILED] banner to the
+ * tool result content instead of crashing the session.
+ */
+export async function handleAfterToolCall(
+  context: AfterToolCallContext,
+  _signal?: AbortSignal
+): Promise<AfterToolCallResult | undefined> {
+  const toolName = context.toolCall.name;
+  const phase = getCurrentPhase();
+  const sessionId = getActiveSessionId();
+
+  try {
+    appendEntry({
+      ts: new Date().toISOString(),
+      sessionId,
+      type: "tool_call",
+      payload: {
+        tool: toolName,
+        phase,
+        result: (() => {
+          const first = context.result.content.find((c) => c.type === "text") as
+            | TextContent
+            | undefined;
+          return first?.text.slice(0, 200) ?? "";
+        })(),
+      },
+    });
+
+    db.transaction(() => {
+      db.prepare(
+        "UPDATE sessions SET last_tool = ? WHERE is_active = 1"
+      ).run(toolName);
+    })();
+
+    // FSM phase transition for start_feature (Story 3.3)
+    if (toolName === "start_feature") {
+      const firstText = context.result.content.find((c) => c.type === "text") as
+        | TextContent
+        | undefined;
+      if (firstText) {
+        let parsed: unknown = null;
+        try {
+          parsed = JSON.parse(firstText.text);
+        } catch {
+          // non-JSON result — skip phase transition silently
+        }
+        if (isStartFeatureResult(parsed)) {
+          const newPhase = parsed.mode === "quick" ? "implementation" : "requirements";
+          applyPhaseTransition(parsed.feature_id, newPhase);
+
+          // Specialist auto-load after phase transition (Story 3.4) — non-fatal
+          try {
+            const specCtx = buildStateContext(parsed.feature_id, toolName);
+            const specialistBlock = loadSpecialist(newPhase, specCtx);
+            if (specialistBlock) {
+              const specialistContent: TextContent = {
+                type: "text",
+                text: `\n\n${specialistBlock}`,
+              };
+              return { content: [...context.result.content, specialistContent] };
+            }
+          } catch (specialistErr) {
+            console.error(`[frappe-state] specialist load failed: ${specialistErr}`);
+            // non-fatal — session continues without specialist block
+          }
+        }
+      }
+    }
+
+    // Debugger specialist invocation (Story 3.5) — no phase transition
+    if (toolName === "invoke_debugger") {
+      const { currentPhase, activeFeatureId } = readSessionState();
+      appendEntry({
+        ts: new Date().toISOString(),
+        sessionId,
+        type: "tool_call",
+        payload: { tool: "invoke_debugger", phase_preserved: currentPhase },
+      });
+      try {
+        const specCtx = buildStateContext(activeFeatureId, toolName);
+        const debuggerBlock = loadDebuggerSpecialist(specCtx);
+        if (debuggerBlock) {
+          const content: TextContent = { type: "text", text: `\n\n${debuggerBlock}` };
+          return { content: [...context.result.content, content] };
+        }
+      } catch (debuggerErr) {
+        console.error(`[frappe-state] debugger specialist load failed: ${debuggerErr}`);
+      }
+    }
+
+    // Sub-agent spawn JSONL logging (Story 3.6) — no phase transition, no specialist change
+    if (toolName === "spawn_agent") {
+      const firstText = context.result.content.find((c) => c.type === "text") as TextContent | undefined;
+      if (firstText) {
+        let parsed: unknown = null;
+        try { parsed = JSON.parse(firstText.text); } catch { /* skip */ }
+        if (isSpawnAgentResult(parsed)) {
+          try {
+            const approved = parsed.status === "spawned";
+            const entry: Record<string, unknown> = {
+              type: "sub_agent",
+              skill: parsed.skill,
+              trigger: parsed.trigger,
+              approved,
+            };
+            if (parsed.status === "disabled") entry.reason = "disabled";
+            if (parsed.status === "requires_approval") entry.reason = "awaiting_approval";
+            appendEntry({
+              ts: new Date().toISOString(),
+              sessionId,
+              type: "tool_call",
+              payload: entry,
+            });
+          } catch (spawnErr) {
+            console.error(`[frappe-state] spawn_agent log failed: ${spawnErr}`);
+          }
+        }
+      }
+    }
+
+    // End debug — restore previous phase specialist (Story 3.5) — no phase transition
+    if (toolName === "end_debug") {
+      const { currentPhase, activeFeatureId } = readSessionState();
+      appendEntry({
+        ts: new Date().toISOString(),
+        sessionId,
+        type: "tool_call",
+        payload: { tool: "end_debug", phase_restored: currentPhase },
+      });
+      try {
+        const specCtx = buildStateContext(activeFeatureId, toolName);
+        const specialistBlock = loadSpecialist(currentPhase, specCtx);
+        if (specialistBlock) {
+          const content: TextContent = { type: "text", text: `\n\n${specialistBlock}` };
+          return { content: [...context.result.content, content] };
+        }
+      } catch (endDebugErr) {
+        console.error(`[frappe-state] end_debug specialist restore failed: ${endDebugErr}`);
+      }
+    }
+
+    return undefined;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[frappe-state] afterToolCall write failed: ${msg}`);
+
+    const banner: TextContent = {
+      type: "text",
+      text: `\n\n[STATE WRITE FAILED: ${msg}]`,
+    };
+
+    return { content: [...context.result.content, banner] };
+  }
+}