frappe-builder 1.1.0-dev.12 → 1.1.0-dev.16

package/extensions/agent-chain.ts

@@ -0,0 +1,248 @@
+import { spawn } from "node:child_process";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { appendFileSync } from "node:fs";
+import { db } from "../state/db.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENTS_DIR = resolve(__dirname, "../agents");
+const CHAIN_EVENTS_PATH = join(".fb", "chain_events.jsonl");
+const STEP_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes per step
+const ARTIFACT_MIN_BYTES = 100;
+const PREV_ARTIFACT_MAX_CHARS = 4096;
+
+interface ChainStep {
+  phase: string;
+  specialist: string;
+  artifactFile: string; // relative to artifactDir
+  tools: string[];
+}
+
+export const CHAIN_STEPS: ChainStep[] = [
+  {
+    phase: "requirements",
+    specialist: "frappe-ba",
+    artifactFile: "planning-artifacts/requirements.md",
+    tools: ["Read", "Write", "get_frappe_docs"],
+  },
+  {
+    phase: "architecture",
+    specialist: "frappe-architect",
+    artifactFile: "planning-artifacts/architecture.md",
+    tools: ["Read", "Write", "get_frappe_docs"],
+  },
+  {
+    phase: "planning",
+    specialist: "frappe-planner",
+    artifactFile: "planning-artifacts/plan.md",
+    tools: ["Read", "Write", "create_component"],
+  },
+  {
+    phase: "implementation",
+    specialist: "frappe-dev",
+    artifactFile: "implementation-artifacts/sprint-status.yaml",
+    tools: ["Read", "Write", "Edit", "Bash", "create_component", "complete_component", "bench_execute"],
+  },
+  {
+    phase: "testing",
+    specialist: "frappe-qa",
+    artifactFile: "implementation-artifacts/test-report.md",
+    tools: ["Read", "Write", "Bash", "bench_execute"],
+  },
+  {
+    phase: "documentation",
+    specialist: "frappe-docs",
+    artifactFile: "implementation-artifacts/docs.md",
+    tools: ["Read", "Write"],
+  },
+];
+
+const PHASE_TASKS: Record<string, string> = {
+  requirements:
+    "Analyse the feature description and produce requirements.md covering DocTypes, roles, process flows, and acceptance criteria.",
+  architecture:
+    "Design the Frappe-native technical solution based on the requirements above. Produce architecture.md covering DocType schemas, relationships, server logic, and permissions.",
+  planning:
+    "Break the architecture into ordered implementation components. Produce plan.md, then call create_component for every component listed.",
+  implementation:
+    "Implement every component from the plan in order. Call complete_component after each one passes tests.",
+  testing:
+    "Run the full test suite, verify all acceptance criteria, check the permission matrix, and produce test-report.md with Result: PASS.",
+  documentation:
+    "Document the implemented feature — DocType fields, hooks, docstrings, and changelog entry — and produce docs.md.",
+};
+
+function appendChainEvent(entry: Record<string, unknown>): void {
+  try {
+    mkdirSync(".fb", { recursive: true });
+    appendFileSync(CHAIN_EVENTS_PATH, JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n", "utf-8");
+  } catch { /* non-fatal */ }
+}
+
+function readArtifact(artifactDir: string, artifactFile: string): string | null {
+  try {
+    const content = readFileSync(join(artifactDir, artifactFile), "utf-8");
+    return content.slice(0, PREV_ARTIFACT_MAX_CHARS);
+  } catch {
+    return null;
+  }
+}
+
+function verifyArtifact(artifactDir: string, artifactFile: string): boolean {
+  try {
+    const content = readFileSync(join(artifactDir, artifactFile), "utf-8");
+    return content.length >= ARTIFACT_MIN_BYTES;
+  } catch {
+    return false;
+  }
+}
+
+function buildTaskPrompt(
+  step: ChainStep,
+  featureId: string,
+  featureName: string,
+  artifactDir: string,
+  prevArtifact: string | null,
+): string {
+  const prevSection = prevArtifact
+    ? `## Previous Phase Output\n\`\`\`\n${prevArtifact}\n\`\`\`\n\n`
+    : "";
+
+  return [
+    `Feature: "${featureName}" (ID: ${featureId})`,
+    `Artifact directory: ${artifactDir}`,
+    "",
+    prevSection,
+    `## Your Task`,
+    PHASE_TASKS[step.phase],
+    "",
+    `Write your output to: ${join(artifactDir, step.artifactFile)}`,
+    `Do not stop until the artifact file exists with substantive content.`,
+  ].join("\n");
+}
+
+function runSubprocess(
+  step: ChainStep,
+  taskPrompt: string,
+): Promise<{ exitCode: number; stderr: string }> {
+  return new Promise((resolvePromise) => {
+    const agentFile = join(AGENTS_DIR, `${step.specialist}.md`);
+    let systemPrompt = "";
+    try {
+      systemPrompt = readFileSync(agentFile, "utf-8");
+    } catch {
+      systemPrompt = `You are ${step.specialist}, a Frappe specialist. ${PHASE_TASKS[step.phase]}`;
+    }
+
+    const args = [
+      "--mode", "json",
+      "-p",
+      "--no-extensions",
+      "--tools", step.tools.join(","),
+      "--append-system-prompt", systemPrompt,
+      taskPrompt,
+    ];
+
+    const proc = spawn("pi", args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env },
+    });
+
+    const stderrChunks: string[] = [];
+    proc.stderr?.setEncoding("utf-8");
+    proc.stderr?.on("data", (chunk: string) => stderrChunks.push(chunk));
+
+    // Hard timeout per step
+    const timer = setTimeout(() => proc.kill("SIGTERM"), STEP_TIMEOUT_MS);
+
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      resolvePromise({
+        exitCode: code ?? 1,
+        stderr: stderrChunks.slice(-20).join("").slice(-2000),
+      });
+    });
+  });
+}
+
+function updateDb(featureId: string, phase: string, chainStep: string | null): void {
+  try {
+    db.transaction(() => {
+      db.prepare("UPDATE sessions SET chain_step = ? WHERE is_active = 1").run(chainStep);
+      db.prepare("UPDATE features SET current_phase = ? WHERE feature_id = ?").run(phase, featureId);
+    })();
+  } catch { /* non-fatal — chain continues */ }
+}
+
+/**
+ * Runs the full agent chain for a feature. Fire-and-forget: called via setImmediate from startFeature.
+ * Each phase spawns an isolated pi subprocess with a specialist system prompt.
+ * Artifacts are passed between phases via files in artifactDir.
+ */
+export async function spawnChain(
+  featureId: string,
+  featureName: string,
+  artifactDir: string,
+): Promise<void> {
+  appendChainEvent({ featureId, featureName, status: "chain_started" });
+
+  let prevArtifact: string | null = null;
+
+  for (const step of CHAIN_STEPS) {
+    // Update state: chain is now on this phase
+    updateDb(featureId, step.phase, step.phase);
+    appendChainEvent({ featureId, phase: step.phase, status: "started" });
+
+    // Ensure artifact subdirs exist
+    const planningDir = join(artifactDir, "planning-artifacts");
+    const implDir = join(artifactDir, "implementation-artifacts");
+    mkdirSync(planningDir, { recursive: true });
+    mkdirSync(implDir, { recursive: true });
+
+    const taskPrompt = buildTaskPrompt(step, featureId, featureName, artifactDir, prevArtifact);
+
+    // Run subprocess — retry once if artifact missing despite exit 0
+    let result = await runSubprocess(step, taskPrompt);
+    const artifactOk = verifyArtifact(artifactDir, step.artifactFile);
+
+    if (result.exitCode === 0 && !artifactOk) {
+      // Retry with explicit nudge
+      const retryPrompt = taskPrompt +
+        `\n\nWARNING: Your artifact was not detected at ${join(artifactDir, step.artifactFile)}. ` +
+        `You MUST write this file before exiting.`;
+      result = await runSubprocess(step, retryPrompt);
+    }
+
+    if (result.exitCode !== 0 || !verifyArtifact(artifactDir, step.artifactFile)) {
+      // Chain failed — write error file and update state
+      const errorContent = [
+        `# Chain Error`,
+        `Phase: ${step.phase}`,
+        `Exit code: ${result.exitCode}`,
+        `Artifact expected: ${join(artifactDir, step.artifactFile)}`,
+        `Artifact found: ${verifyArtifact(artifactDir, step.artifactFile)}`,
+        ``,
+        `## Stderr (last 2000 chars)`,
+        result.stderr,
+      ].join("\n");
+
+      try {
+        writeFileSync(join(artifactDir, "chain_error.md"), errorContent, "utf-8");
+      } catch { /* non-fatal */ }
+
+      updateDb(featureId, "chain_failed", null);
+      appendChainEvent({ featureId, phase: step.phase, status: "failed", exitCode: result.exitCode });
+      return;
+    }
+
+    appendChainEvent({ featureId, phase: step.phase, status: "complete" });
+
+    // Pass this phase's artifact to the next phase
+    prevArtifact = readArtifact(artifactDir, step.artifactFile);
+  }
+
+  // All steps complete
+  updateDb(featureId, "done", null);
+  appendChainEvent({ featureId, status: "chain_complete" });
+}

package/extensions/frappe-session.ts

@@ -290,6 +290,11 @@ export async function handleSessionStart(): Promise<string> {
 
     // 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 === "chain_running") {
+      // Agent chain is running as a background subprocess — no specialist injection.
+      // Use get_project_status to monitor chain progress.
+      return `${stateBlock}\n\nAgent chain is running. Use get_project_status to monitor progress.`;
+    }
     if (ctx.phase !== "idle") {
       try {
         const specCtx = buildStateContext(null, "session_start");

package/extensions/frappe-state.ts

@@ -8,6 +8,28 @@ import { loadCredentials } from "../config/loader.js";
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export default function (pi: any) {
   pi.on("after_tool_call", handleAfterToolCall);
+
+  // Session-end guard: warn the agent about untracked features before shutdown.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  pi.on("session_shutdown", (_event: any, ctx: any) => {
+    try {
+      const orphans = db
+        .prepare(
+          `SELECT feature_id, name, mode FROM features
+           WHERE current_phase != 'idle' AND progress_total = 0`
+        )
+        .all() as Array<{ feature_id: string; name: string; mode: string }>;
+
+      if (orphans.length > 0) {
+        const list = orphans.map((f) => `  • ${f.name} [${f.feature_id}] (${f.mode})`).join("\n");
+        const warning = `\n⚠ Session ending with ${orphans.length} feature(s) that have no components tracked:\n${list}\n\nCall create_component() + complete_component() before the next session to preserve work history.`;
+        try {
+          ctx.ui.setStatus("frappe-builder", `⚠ ${orphans.length} untracked feature(s) — run create_component`);
+        } catch { /* non-fatal */ }
+        console.error(warning);
+      }
+    } catch { /* non-fatal — never block shutdown */ }
+  });
 }
 
 /** Reads current_phase and feature_id from the active session. */
@@ -29,6 +51,29 @@ function getActiveSessionId(): string {
   return row?.session_id ?? "unknown";
 }
 
+/** Type guard for createComponent() return value. */
+function isCreateComponentResult(value: unknown): value is { feature_id: string; component_id: string; artifact_dir: string } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "feature_id" in value &&
+    "component_id" in value &&
+    "artifact_dir" in value
+  );
+}
+
+/** Type guard for completeComponent() success return value. */
+function isCompleteComponentResult(value: unknown): value is { feature_id: string; component_id: string; status: string } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "feature_id" in value &&
+    "component_id" in value &&
+    "status" in value &&
+    (value as Record<string, unknown>).status === "complete"
+  );
+}
+
 /** Type guard for SpawnAgentResult from agent-tools.ts. */
 function isSpawnAgentResult(value: unknown): value is { status: string; skill: string; trigger: string } {
   return (
@@ -41,14 +86,16 @@ function isSpawnAgentResult(value: unknown): value is { status: string; skill: s
 }
 
 /** Type guard for the return value of startFeature(). */
-function isStartFeatureResult(value: unknown): value is { mode: string; feature_id: string } {
+function isStartFeatureResult(value: unknown): value is { mode: string; feature_id: string; current_phase: string } {
   return (
     typeof value === "object" &&
     value !== null &&
     "mode" in value &&
     "feature_id" in value &&
+    "current_phase" in value &&
     typeof (value as Record<string, unknown>).mode === "string" &&
-    typeof (value as Record<string, unknown>).feature_id === "string"
+    typeof (value as Record<string, unknown>).feature_id === "string" &&
+    typeof (value as Record<string, unknown>).current_phase === "string"
   );
 }
 
@@ -131,13 +178,21 @@ export async function handleAfterToolCall(
           // non-JSON result — skip phase transition silently
         }
         if (isStartFeatureResult(parsed)) {
-          const newPhase = parsed.mode === "quick" ? "implementation" : "requirements";
-          applyPhaseTransition(parsed.feature_id, newPhase);
+          // Full mode: chain running as background subprocess — inject status banner
+          if (parsed.current_phase === "chain_running") {
+            const banner: TextContent = {
+              type: "text",
+              text: `\n\nAgent chain started for "${parsed.feature_id}" (full mode).\n` +
+                    `Each phase runs as an isolated subprocess. Monitor progress with get_project_status.\n` +
+                    `The chain will advance through: requirements → architecture → planning → implementation → testing → documentation.`,
+            };
+            return { content: [...context.result.content, banner] };
+          }
 
-          // Specialist auto-load after phase transition (Story 3.4) — non-fatal
+          // Quick mode: specialist auto-load after phase transition (Story 3.4) — non-fatal
           try {
             const specCtx = buildStateContext(parsed.feature_id, toolName);
-            const specialistBlock = loadSpecialist(newPhase, specCtx);
+            const specialistBlock = loadSpecialist(parsed.current_phase, specCtx);
             if (specialistBlock) {
               const specialistContent: TextContent = {
                 type: "text",
@@ -147,7 +202,6 @@ export async function handleAfterToolCall(
             }
           } catch (specialistErr) {
             console.error(`[frappe-state] specialist load failed: ${specialistErr}`);
-            // non-fatal — session continues without specialist block
           }
         }
       }
@@ -204,6 +258,51 @@ export async function handleAfterToolCall(
       }
     }
 
+    // create_component JSONL logging — no phase transition, no specialist change
+    if (toolName === "create_component") {
+      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 (isCreateComponentResult(parsed)) {
+          appendEntry({
+            ts: new Date().toISOString(),
+            sessionId,
+            type: "tool_call",
+            payload: { tool: "create_component", feature: parsed.feature_id, component: parsed.component_id },
+          });
+        }
+      }
+    }
+
+    // complete_component — check if all components done and inject completion hint
+    if (toolName === "complete_component") {
+      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 (isCompleteComponentResult(parsed)) {
+          appendEntry({
+            ts: new Date().toISOString(),
+            sessionId,
+            type: "tool_call",
+            payload: { tool: "complete_component", feature: parsed.feature_id, component: parsed.component_id },
+          });
+          // Check if all components for this feature are now complete
+          const feature = db
+            .prepare("SELECT progress_done, progress_total FROM features WHERE feature_id = ?")
+            .get(parsed.feature_id) as { progress_done: number; progress_total: number } | undefined;
+          if (feature && feature.progress_total > 0 && feature.progress_done >= feature.progress_total) {
+            const hint: TextContent = {
+              type: "text",
+              text: `\n\n✓ All ${feature.progress_total} components complete for this feature. Ready to advance to the next phase.`,
+            };
+            return { content: [...context.result.content, hint] };
+          }
+        }
+      }
+    }
+
     // End debug — restore previous phase specialist (Story 3.5) — no phase transition
     if (toolName === "end_debug") {
       const { currentPhase, activeFeatureId } = readSessionState();

package/extensions/frappe-ui.ts

@@ -1,72 +1,126 @@
 import type { AfterToolCallContext, AfterToolCallResult } from "@mariozechner/pi-agent-core";
 import { db, getCurrentPhase } from "../state/db.js";
+import { loadConfig } from "../config/loader.js";
+import { DEFAULT_PERMISSION_MODE } from "../config/defaults.js";
 
-interface FooterState {
+interface DashboardState {
   projectId: string | null;
   featureName: string | null;
+  featureMode: string | null;
+  componentId: string | null;
   phase: string;
-  tokenCount: number;
+  chainStep: string | null;
+  progressDone: number;
+  progressTotal: number;
+  permissionMode: string;
 }
 
-function readFooterState(): FooterState {
+// Keep FooterState alias so existing tests compile without changes.
+type FooterState = Pick<DashboardState, "projectId" | "featureName" | "componentId">;
+
+function readDashboardState(): DashboardState {
   try {
     const session = db
       .prepare(
-        `SELECT s.project_id, f.name AS feature_name, s.current_phase
+        `SELECT s.project_id, s.current_phase, s.component_id, s.chain_step,
+                f.name AS feature_name, f.mode AS feature_mode,
+                f.progress_done, f.progress_total
          FROM sessions s
          LEFT JOIN features f ON f.feature_id = s.feature_id
          WHERE s.is_active = 1 LIMIT 1`
       )
       .get() as
-      | { project_id: string | null; feature_name: string | null; current_phase: string }
+      | {
+          project_id: string | null;
+          current_phase: string;
+          component_id: string | null;
+          chain_step: string | null;
+          feature_name: string | null;
+          feature_mode: string | null;
+          progress_done: number | null;
+          progress_total: number | null;
+        }
       | undefined;
 
-    // Token count: count journal_entries for active session; table may not exist yet
-    let tokenCount = 0;
-    try {
-      const tokenRow = db
-        .prepare(
-          `SELECT COUNT(*) as count FROM journal_entries
-           WHERE session_id = (SELECT session_id FROM sessions WHERE is_active = 1 LIMIT 1)`
-        )
-        .get() as { count: number } | undefined;
-      tokenCount = tokenRow?.count ?? 0;
-    } catch {
-      // journal_entries table not yet created — default to 0
-    }
+    const permissionMode = (() => {
+      try { return loadConfig().permissionMode ?? DEFAULT_PERMISSION_MODE; } catch { return DEFAULT_PERMISSION_MODE; }
+    })();
 
     return {
       projectId: session?.project_id ?? null,
       featureName: session?.feature_name ?? null,
+      featureMode: session?.feature_mode ?? null,
+      componentId: session?.component_id ?? null,
       phase: session?.current_phase ?? "idle",
-      tokenCount,
+      chainStep: session?.chain_step ?? null,
+      progressDone: session?.progress_done ?? 0,
+      progressTotal: session?.progress_total ?? 0,
+      permissionMode,
     };
   } catch {
-    return { projectId: null, featureName: null, phase: "idle", tokenCount: 0 };
+    return { projectId: null, featureName: null, featureMode: null, componentId: null, phase: "idle", chainStep: null, progressDone: 0, progressTotal: 0, permissionMode: DEFAULT_PERMISSION_MODE };
   }
 }
 
 /**
- * Pure formatting function — no I/O, no side effects.
+ * Formats dashboard state as a string[] for ctx.ui.setWidget().
  * Exported for unit testing.
  */
-export function formatFooter(state: FooterState): string {
+export function formatDashboard(state: DashboardState): string[] {
   if (!state.projectId) {
-    return `No active project | Phase: ${state.phase}`;
+    return ["frappe-builder  |  No active project"];
   }
-  if (!state.featureName) {
-    return `Project: ${state.projectId} | No active feature | Phase: ${state.phase}`;
+
+  const parts: string[] = [`Project: ${state.projectId}`];
+
+  if (state.featureName) {
+    const modeTag = state.featureMode ? ` [${state.featureMode}]` : "";
+    parts.push(`Feature: ${state.featureName}${modeTag}`);
+  } else {
+    parts.push("No active feature");
+  }
+
+  if (state.componentId) {
+    parts.push(`Component: ${state.componentId}`);
+  }
+
+  if (state.phase === "chain_running") {
+    parts.push(`Phase: chain:${state.chainStep ?? "starting"}`);
+  } else {
+    parts.push(`Phase: ${state.phase}`);
+  }
+
+  if (state.progressTotal > 0) {
+    parts.push(`${state.progressDone}/${state.progressTotal} components`);
   }
-  return `Project: ${state.projectId} | Feature: ${state.featureName} | Phase: ${state.phase} | Tokens: ${state.tokenCount}`;
+
+  parts.push(`Mode: ${state.permissionMode}`);
+
+  return [`frappe-builder  |  ${parts.join("  |  ")}`];
+}
+
+/**
+ * Legacy single-line footer format — kept for backward-compat with existing tests.
+ * Exported for unit testing.
+ */
+export function formatFooter(state: FooterState): string {
+  if (!state.projectId) return "No active project";
+  if (!state.featureName) return `Project: ${state.projectId} | No active feature`;
+  if (!state.componentId) return `Project: ${state.projectId} | Feature: ${state.featureName}`;
+  return `Project: ${state.projectId} | Feature: ${state.featureName} | Component: ${state.componentId}`;
 }
 
-function renderFooter(): void {
+function renderWidget(ctx: unknown): void {
   try {
-    const state = readFooterState();
-    const line = formatFooter(state);
-    process.stderr.write(`\r\x1b[2K[frappe-builder] ${line}\n`);
+    const lines = formatDashboard(readDashboardState());
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (ctx as any).ui.setWidget("frappe-builder", lines, { placement: "aboveEditor" });
   } catch {
-    // Silently swallow all rendering errors — footer is non-critical
+    // Fallback: write to stderr if widget API unavailable
+    try {
+      const state = readDashboardState();
+      process.stderr.write(`\r\x1b[2K[frappe-builder] ${formatDashboard(state).join(" ")}\n`);
+    } catch { /* non-critical */ }
   }
 }
 
@@ -98,22 +152,33 @@ export async function handleAfterToolCall(
   _context: AfterToolCallContext,
   _signal?: AbortSignal
 ): Promise<AfterToolCallResult | undefined> {
-  renderFooter();
   return undefined;
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export default function (pi: any) {
-  pi.on("session_start", () => {
-    renderFooter();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  pi.on("session_start", (_event: any, ctx: any) => {
+    renderWidget(ctx);
   });
 
   // Announcement hook — fires before FSM guard in frappe-workflow.ts (FR25)
-  pi.on("tool_call", (event: { toolName?: string }) => {
-    return handleBeforeToolCall(event.toolName ?? "");
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  pi.on("tool_call", (event: any, ctx: any) => {
+    try {
+      const state = readDashboardState();
+      const lines = formatDashboard(state);
+      const callLine = `→ ${event.toolName ?? "tool"} [${state.phase}]`;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (ctx as any).ui.setWidget("frappe-builder", [...lines, callLine], { placement: "aboveEditor" });
+    } catch {
+      handleBeforeToolCall(event.toolName ?? "");
+    }
   });
 
-  pi.on("after_tool_call", async (context: AfterToolCallContext) => {
-    return await handleAfterToolCall(context);
+  // "tool_result" fires after each tool completes — update the persistent widget.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  pi.on("tool_result", (_event: any, ctx: any) => {
+    renderWidget(ctx);
   });
 }