frappe-builder 1.1.0-dev.8 → 1.2.0-dev.29

package/extensions/frappe-workflow.ts

@@ -1,26 +1,37 @@
 import { getCurrentPhase, db } from "../state/db.js";
 import { isToolAllowedInPhase, getValidPhase, type Phase } from "../state/fsm.js";
 import { appendEntry } from "../state/journal.js";
+import { loadConfig } from "../config/loader.js";
+import { type PermissionMode, DEFAULT_PERMISSION_MODE } from "../config/defaults.js";
+import { ALWAYS_ALLOWED_TOOLS, WRITE_TOOLS } from "../config/constants.js";
+import type { PiPlugin, PiUiContext } from "./pi-types.js";
+
+// Re-export for use in tests and other modules
+export type { PermissionMode };
+
+// WRITE_TOOLS imported from config/constants.ts — single source of truth
+export { WRITE_TOOLS };
 
 interface BlockedResponse {
   blocked: true;
   tool: string;
   current_phase: Phase;
-  valid_phase: Phase | "any";
+  valid_phase: string;
   message: string;
 }
 
 function buildBlockedResponse(
   tool: string,
   currentPhase: Phase,
-  validPhase: Phase | "any"
+  validPhase: Phase | Phase[] | "any"
 ): BlockedResponse {
+  const validLabel = Array.isArray(validPhase) ? validPhase.join(", ") : validPhase;
   return {
     blocked: true,
     tool,
     current_phase: currentPhase,
-    valid_phase: validPhase,
-    message: `${tool} is not available in ${currentPhase} phase. Available in: ${validPhase}`,
+    valid_phase: validLabel,
+    message: `${tool} is not available in ${currentPhase} phase. Available in: ${validLabel}`,
   };
 }
 
@@ -33,15 +44,14 @@ function buildBlockedResponse(
  *
  * Never throws — always returns a value or undefined.
  */
-// Tools valid in all phases — never blocked by the phase guard (FR34)
-const ALWAYS_ALLOWED_TOOLS = ["invoke_debugger", "end_debug", "spawn_agent", "get_frappe_docs", "get_audit_log"];
+// ALWAYS_ALLOWED_TOOLS imported from config/constants.ts — single source of truth
 
 export function beforeToolCall(
   toolName: string,
   args: Record<string, unknown>
 ): BlockedResponse | undefined {
   // Always-allowed bypass — checked before everything else
-  if (ALWAYS_ALLOWED_TOOLS.includes(toolName)) return undefined;
+  if (ALWAYS_ALLOWED_TOOLS.has(toolName)) return undefined;
 
   const currentPhase = getCurrentPhase() as Phase;
 
@@ -73,13 +83,72 @@ export function beforeToolCall(
   return undefined; // allow
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export default function (pi: any) {
-  pi.on("tool_call", (event: { toolName?: string; input?: Record<string, unknown> }) => {
-    const result = beforeToolCall(event.toolName ?? "", event.input ?? {});
-    if (result) {
-      return { block: true, reason: result.message };
+/**
+ * Checks the active permission mode for write tools.
+ * - auto: always allowed
+ * - plan: always blocked with dry-run message
+ * - default: prompts via ctx.ui.input(); falls through if unavailable
+ *
+ * Returns a blocked response to halt execution, or undefined to allow.
+ * Never throws.
+ */
+export async function checkPermissionMode(
+  toolName: string,
+  mode: PermissionMode,
+  ctx?: PiUiContext,
+): Promise<BlockedResponse | undefined> {
+  if (!WRITE_TOOLS.has(toolName)) return undefined;
+  if (mode === "auto") return undefined;
+
+  if (mode === "plan") {
+    return {
+      blocked: true,
+      tool: toolName,
+      current_phase: getCurrentPhase() as Phase,
+      valid_phase: "any",
+      message: `[plan mode] ${toolName} is a write operation — dry-run only. Switch to default or auto mode to execute.`,
+    };
+  }
+
+  // default mode: prompt via ctx.ui.input()
+  if (ctx) {
+    try {
+      const answer = await ctx.ui.input?.(`Allow ${toolName}? (yes/no)`);
+      if (!["yes", "y"].includes(answer?.toLowerCase?.() ?? "")) {
+        return {
+          blocked: true,
+          tool: toolName,
+          current_phase: getCurrentPhase() as Phase,
+          valid_phase: "any",
+          message: `${toolName} blocked by user.`,
+        };
+      }
+    } catch {
+      // ctx.ui.input unavailable — fail open (allow)
+    }
+  }
+
+  return undefined;
+}
+
+export default function (pi: PiPlugin) {
+  pi.on("tool_call", async (event: { toolName?: string; input?: Record<string, unknown> }, ctx?: PiUiContext) => {
+    const toolName = event.toolName ?? "";
+
+    // Phase guard
+    const phaseResult = beforeToolCall(toolName, event.input ?? {});
+    if (phaseResult) {
+      return { block: true, reason: phaseResult.message };
+    }
+
+    // Permission mode guard (Story 9.2–9.4)
+    const config = loadConfig();
+    const mode: PermissionMode = config.permissionMode ?? DEFAULT_PERMISSION_MODE;
+    const permResult = await checkPermissionMode(toolName, mode, ctx);
+    if (permResult) {
+      return { block: true, reason: permResult.message };
     }
+
     return undefined;
   });
 }

package/extensions/pi-types.ts

@@ -0,0 +1,53 @@
+import type { AfterToolCallContext, AfterToolCallResult } from "@mariozechner/pi-agent-core";
+
+/** Minimal structural type for the pi event context — covers all current usages.
+ *  Methods are optional because the pi API is unversioned and tests use partial mocks.
+ *  All call sites wrap invocations in try-catch or use optional chaining. */
+export interface PiUiContext {
+  ui: Partial<{
+    setWidget(name: string, lines: string[], options?: { placement?: string }): void;
+    setStatus(name: string, message: string): void;
+    notify(message: string, severity: string): void;
+    input(prompt: string): Promise<string>;
+  }>;
+}
+
+/** Structural type for the `pi` plugin object passed to each extension's default export.
+ *  Derived from observed pi-agent-core v0.62.0 behaviour; no published schema exists. */
+export interface PiPlugin {
+  on(event: "session_start", handler: (event?: unknown, ctx?: PiUiContext) => void | Promise<void>): void;
+  on(event: "session_shutdown", handler: (event?: unknown, ctx?: PiUiContext) => void): void;
+  on(
+    event: "tool_call",
+    handler: (
+      event: { toolName?: string; input?: Record<string, unknown> },
+      ctx?: PiUiContext,
+    ) => unknown,
+  ): void;
+  on(event: "tool_result", handler: (event?: unknown, ctx?: PiUiContext) => void): void;
+  on(
+    event: "after_tool_call",
+    handler: (
+      ctx: AfterToolCallContext,
+      signal?: AbortSignal,
+    ) => AfterToolCallResult | undefined | Promise<AfterToolCallResult | undefined>,
+  ): void;
+  registerTool(definition: PiToolDefinition): void;
+  registerCommand?: (name: string, definition: PiCommandDefinition) => void;
+}
+
+export interface PiToolDefinition {
+  name: string;
+  label: string;
+  description: string;
+  parameters: unknown;
+  execute: (toolCallId: string, params: unknown) => Promise<{
+    content: Array<{ type: string; text: string }>;
+    details?: unknown;
+  }>;
+}
+
+export interface PiCommandDefinition {
+  description: string;
+  handler: (args: string, ctx: Record<string, unknown>) => Promise<string>;
+}

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "frappe-builder",
-  "version": "1.1.0-dev.8",
+  "version": "1.2.0-dev.29",
   "description": "Frappe-native AI co-pilot for building and customising Frappe/ERPNext applications",
   "type": "module",
+  "bin": {
+    "frappe-builder": "./dist/cli.mjs"
+  },
   "pi": {
-    "_note": "TODO: verify 'pi' field schema against @mariozechner/pi-agent-core docs — no schema found in installed package. Reference schema below is a best-guess pending confirmation.",
     "extensions": [
       "./extensions/frappe-session.ts",
       "./extensions/frappe-state.ts",
@@ -35,6 +37,7 @@
   "dependencies": {
     "@mariozechner/pi-agent-core": "0.62.0",
     "@mariozechner/pi-ai": "0.62.0",
+    "@mariozechner/pi-coding-agent": "^0.63.1",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.8.0",
     "execa": "^9.6.1",

package/state/artifacts.ts

@@ -0,0 +1,85 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { db } from "./db.js";
+
+/**
+ * Returns the artifact directory for a feature.
+ * When app_path is set: {app_path}/.frappe-builder/{featureId}/
+ * Fallback (no app_path): {cwd}/.frappe-builder/{featureId}/
+ */
+export function getArtifactDir(featureId: string): string {
+  const row = db
+    .prepare("SELECT app_path FROM sessions WHERE is_active = 1 LIMIT 1")
+    .get() as { app_path: string | null } | undefined;
+  const root = row?.app_path ?? process.cwd();
+  return join(root, ".frappe-builder", featureId);
+}
+
+/**
+ * Regenerates sprint-status.yaml for the given feature from current DB state.
+ * Called after every create_component and complete_component.
+ * Creates the artifact directory if it does not exist.
+ * Non-fatal — caller should catch any errors.
+ */
+export function regenerateSprintStatus(featureId: string): void {
+  const feature = db
+    .prepare("SELECT feature_id, name, mode, current_phase FROM features WHERE feature_id = ?")
+    .get(featureId) as
+    | { feature_id: string; name: string; mode: string; current_phase: string }
+    | undefined;
+
+  if (!feature) return;
+
+  const components = db
+    .prepare(
+      `SELECT component_id, description, sort_order, status, completed_at
+       FROM components WHERE feature_id = ?
+       ORDER BY sort_order ASC, component_id ASC`
+    )
+    .all(featureId) as Array<{
+      component_id: string;
+      description: string | null;
+      sort_order: number;
+      status: string;
+      completed_at: string | null;
+    }>;
+
+  const done = components.filter((c) => c.status === "complete").length;
+  const total = components.length;
+
+  const componentLines = components
+    .map((c) => {
+      const descLine = c.description
+        ? `    description: "${c.description.replace(/"/g, '\\"')}"`
+        : "";
+      return [
+        `  - id: ${c.component_id}`,
+        descLine,
+        `    sort_order: ${c.sort_order}`,
+        `    status: ${c.status}`,
+        `    completed_at: ${c.completed_at ?? "null"}`,
+      ]
+        .filter(Boolean)
+        .join("\n");
+    })
+    .join("\n");
+
+  const yaml = `feature_id: ${feature.feature_id}
+feature_name: "${feature.name.replace(/"/g, '\\"')}"
+mode: ${feature.mode}
+phase: ${feature.current_phase}
+updated_at: ${new Date().toISOString()}
+
+components:
+${componentLines || "  []"}
+
+progress:
+  done: ${done}
+  total: ${total}
+`;
+
+  const artifactDir = getArtifactDir(featureId);
+  const implDir = join(artifactDir, "implementation-artifacts");
+  mkdirSync(implDir, { recursive: true });
+  writeFileSync(join(implDir, "sprint-status.yaml"), yaml, "utf-8");
+}

package/state/db.ts

@@ -1,7 +1,7 @@
 import Database from "better-sqlite3";
 import type { Database as DatabaseType } from "better-sqlite3";
 import { mkdirSync } from "node:fs";
-import { initSchema } from "./schema.js";
+import { initSchema, migrateSchema } from "./schema.js";
 import { appendEntry } from "./journal.js";
 
 mkdirSync(".fb", { recursive: true });
@@ -10,6 +10,7 @@ mkdirSync(".fb", { recursive: true });
 export let db: DatabaseType = new Database(".fb/state.db");
 
 initSchema(db);
+migrateSchema(db);
 
 /**
  * Replaces the db singleton — intended for test use only.
@@ -24,9 +25,18 @@ export function setDb(instance: DatabaseType): void {
  * a new session for newProjectId, restoring its last known phase if a prior
  * session exists. Writes a "state_transition" JSONL entry before the close.
  *
- * sitePath is optional so existing callers without a site path continue to work.
+ * sitePath and appPath are optional so existing callers without them continue to work.
  */
-export function switchProject(newProjectId: string, sitePath?: string): void {
+export interface ProjectCredentials {
+  sitePath?: string;
+  appPath?: string;
+  siteUrl?: string;
+  apiKey?: string;
+  apiSecret?: string;
+}
+
+export function switchProject(newProjectId: string, creds: ProjectCredentials = {}): void {
+  const { sitePath, appPath, siteUrl, apiKey, apiSecret } = creds;
   db.transaction(() => {
     // 1. Read current active session before closing
     const current = db
@@ -62,12 +72,16 @@ export function switchProject(newProjectId: string, sitePath?: string): void {
 
     // 5. Create new session, restoring prior phase if available; feature_id defaults to NULL
     db.prepare(
-      "INSERT INTO sessions (session_id, project_id, current_phase, site_path, started_at, is_active) VALUES (?, ?, ?, ?, ?, 1)"
+      "INSERT INTO sessions (session_id, project_id, current_phase, site_path, app_path, site_url, api_key, api_secret, started_at, is_active) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 1)"
     ).run(
       crypto.randomUUID(),
       newProjectId,
       prior?.current_phase ?? "idle",
       sitePath ?? null,
+      appPath ?? null,
+      siteUrl ?? null,
+      apiKey ?? null,
+      apiSecret ?? null,
       new Date().toISOString()
     );
   })();

package/state/fsm.ts

@@ -1,4 +1,5 @@
 import { createMachine, state, transition } from "robot3";
+import { ALWAYS_ALLOWED_TOOLS } from "../config/constants.js";
 
 export type Phase =
   | "idle"
@@ -7,7 +8,8 @@ export type Phase =
   | "planning"
   | "implementation"
   | "testing"
-  | "documentation";
+  | "documentation"
+  | "chain_running";  // sentinel: full-mode chain active externally, not an in-session FSM node
 
 export const ALL_PHASES: Phase[] = [
   "idle",
@@ -17,52 +19,70 @@ export const ALL_PHASES: Phase[] = [
   "implementation",
   "testing",
   "documentation",
+  "chain_running",
 ];
 
 function buildMachineStates() {
   return {
+    // Quick mode only: idle → implementation.
+    // Full mode phases (requirements, architecture, planning, testing, documentation)
+    // are handled by agent-chain.ts subprocesses — not in-session FSM transitions.
     idle: state(
-      transition("start_full", "requirements"),
-      transition("start_quick", "implementation") as never // quick mode bypass (Story 3.3)
+      transition("start_quick", "implementation")
     ),
-    requirements: state(transition("approve", "architecture")),
-    architecture: state(transition("approve", "planning")),
-    planning: state(transition("approve", "implementation")),
     implementation: state(transition("approve", "testing")),
     testing: state(transition("approve", "documentation")),
     documentation: state(transition("complete", "idle")),
+    // chain_running is a storage sentinel — not a FSM node with transitions.
+    // The parent session cannot transition out of chain_running via FSM events;
+    // the chain runner updates the DB directly when the chain completes.
   };
 }
 
-/** Creates a Robot3 FSM starting at the given phase — fast-forward, no event replay. */
+type FsmPhase = "idle" | "implementation" | "testing" | "documentation";
+const FSM_PHASES = new Set<string>(["idle", "implementation", "testing", "documentation"]);
+
+function isFsmPhase(p: string): p is FsmPhase {
+  return FSM_PHASES.has(p);
+}
+
+/** Creates a Robot3 FSM starting at the given phase — fast-forward, no event replay.
+ *  Non-FSM phases (chain_running, requirements, architecture, planning) fall back to idle. */
 export function createFsmAtPhase(phase: Phase) {
-  return createMachine(phase, buildMachineStates());
+  const fsmPhase: FsmPhase = isFsmPhase(phase) ? phase : "idle";
+  return createMachine(fsmPhase, buildMachineStates());
 }
 
 /**
  * Maps each tool to its valid phase (or 'any').
  * Tools not listed here are allowed in any phase — do not block unregistered tools.
  */
-const TOOL_PHASE_MAP: Record<string, Phase | "any"> = {
+const TOOL_PHASE_MAP: Record<string, Phase | Phase[] | "any"> = {
   set_active_project: "any",
-  start_feature: "idle",
+  start_feature: "idle",          // blocked in chain_running to prevent double-start
+  create_component: ["planning", "implementation"],
   complete_component: "implementation",
-  scaffold_doctype: "implementation",
   run_tests: "testing",
   get_project_status: "any",
   frappe_query: "any",
-  bench_execute: "any",   // allowed in all phases — includes testing (bench run-tests) and implementation (bench migrate)
+  bench_execute: "any",
 };
 
+// ALWAYS_ALLOWED_TOOLS imported from config/constants.ts — single source of truth
+
 /** Returns true if toolName is allowed to run in the given phase. Unknown tools are always allowed. */
 export function isToolAllowedInPhase(toolName: string, phase: Phase): boolean {
+  if (ALWAYS_ALLOWED_TOOLS.has(toolName)) return true;
+  // chain_running: only always-allowed tools pass; all others (including start_feature) are blocked
+  if (phase === "chain_running") return false;
   const validPhase = TOOL_PHASE_MAP[toolName];
   if (validPhase === undefined) return true; // unknown tool — do not block
   if (validPhase === "any") return true;
+  if (Array.isArray(validPhase)) return validPhase.includes(phase);
   return validPhase === phase;
 }
 
 /** Returns the phase where toolName is valid, or 'any' for unrestricted/unknown tools. */
-export function getValidPhase(toolName: string): Phase | "any" {
+export function getValidPhase(toolName: string): Phase | Phase[] | "any" {
   return TOOL_PHASE_MAP[toolName] ?? "any";
 }

package/state/schema.ts

@@ -18,9 +18,13 @@ export function initSchema(db: Database): void {
     );
 
     CREATE TABLE IF NOT EXISTS components (
-      component_id TEXT NOT NULL,
-      feature_id   TEXT NOT NULL,
-      status       TEXT NOT NULL DEFAULT 'in-progress',
+      component_id TEXT    NOT NULL,
+      feature_id   TEXT    NOT NULL,
+      status       TEXT    NOT NULL DEFAULT 'in-progress'
+        CHECK (status IN ('in-progress', 'complete')),
+      description  TEXT,
+      sort_order   INTEGER NOT NULL DEFAULT 0,
+      created_at   TEXT,
       completed_at TEXT,
       PRIMARY KEY (feature_id, component_id),
       FOREIGN KEY (feature_id) REFERENCES features(feature_id)
@@ -31,7 +35,14 @@ export function initSchema(db: Database): void {
       project_id    TEXT NOT NULL,
       current_phase TEXT NOT NULL DEFAULT 'idle',
       site_path     TEXT,
+      app_path      TEXT,
+      site_url      TEXT,
+      api_key       TEXT,
+      api_secret    TEXT,
+      chain_step    TEXT,
+      chain_pid     INTEGER,
       feature_id    TEXT,
+      component_id  TEXT,
       last_tool     TEXT,
       started_at    TEXT NOT NULL,
       ended_at      TEXT,
@@ -39,3 +50,31 @@ export function initSchema(db: Database): void {
     );
   `);
 }
+
+/**
+ * Adds new columns to existing databases without dropping data.
+ * Safe to call on any DB version — ignores "duplicate column" errors.
+ * Call this after initSchema() in db.ts.
+ */
+export function migrateSchema(db: Database): void {
+  const alters = [
+    "ALTER TABLE components ADD COLUMN description TEXT",
+    "ALTER TABLE components ADD COLUMN sort_order INTEGER NOT NULL DEFAULT 0",
+    "ALTER TABLE components ADD COLUMN created_at TEXT",
+    "ALTER TABLE sessions ADD COLUMN component_id TEXT",
+    "ALTER TABLE sessions ADD COLUMN app_path TEXT",
+    "ALTER TABLE sessions ADD COLUMN chain_step TEXT",
+    "ALTER TABLE sessions ADD COLUMN chain_pid INTEGER",
+    "ALTER TABLE sessions ADD COLUMN site_url TEXT",
+    "ALTER TABLE sessions ADD COLUMN api_key TEXT",
+    "ALTER TABLE sessions ADD COLUMN api_secret TEXT",
+  ];
+  for (const sql of alters) {
+    try {
+      db.exec(sql);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (!msg.includes("duplicate column name")) throw err;
+    }
+  }
+}

package/tools/agent-tools.ts

@@ -1,4 +1,12 @@
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { loadConfig } from "../config/loader.js";
+import { CHAIN_STEP_TIMEOUT_MS } from "../config/constants.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENTS_DIR = resolve(__dirname, "../agents");
 
 export interface SpawnAgentArgs {
   skill: string;
@@ -17,11 +25,69 @@ export interface SpawnAgentResult {
 }
 
 /**
- * Stub: no sub-agent spawn API found in @mariozechner/pi-agent-core at this version.
- * Returns spawned status with null result — replace body with actual API when available.
+ * Spawns an isolated `pi` subprocess for the given skill.
+ * The sub-agent gets its own context window. Reads system prompt from agents/{skill}.md.
+ * Uses `reason` as the task prompt. Times out after CHAIN_STEP_TIMEOUT_MS.
  */
-async function doSpawn(skill: string, trigger: string): Promise<SpawnAgentResult> {
-  return { status: "spawned", skill, trigger, result: null };
+async function doSpawn(skill: string, trigger: string, reason: string): Promise<SpawnAgentResult> {
+  const agentFile = join(AGENTS_DIR, `${skill}.md`);
+  let systemPrompt: string;
+  try {
+    systemPrompt = readFileSync(agentFile, "utf-8");
+  } catch {
+    return {
+      status: "disabled",
+      skill,
+      trigger,
+      error: `No agent definition found for skill "${skill}" (expected ${agentFile})`,
+    };
+  }
+
+  return new Promise((resolvePromise) => {
+    const args = [
+      "--mode", "json",
+      "-p",
+      "--no-extensions",
+      "--append-system-prompt", systemPrompt,
+      reason,
+    ];
+
+    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));
+
+    const timer = setTimeout(() => proc.kill("SIGTERM"), CHAIN_STEP_TIMEOUT_MS);
+
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      if (code === 0) {
+        resolvePromise({ status: "spawned", skill, trigger });
+      } else {
+        const stderr = stderrChunks.slice(-20).join("").slice(-2000);
+        resolvePromise({
+          status: "disabled",
+          skill,
+          trigger,
+          error: `Agent "${skill}" exited with code ${code ?? 1}${stderr ? `: ${stderr}` : ""}`,
+        });
+      }
+    });
+
+    proc.on("error", (err) => {
+      clearTimeout(timer);
+      resolvePromise({
+        status: "disabled",
+        skill,
+        trigger,
+        error: `Failed to spawn pi process: ${err.message}`,
+      });
+    });
+  });
 }
 
 /**
@@ -56,5 +122,5 @@ export async function spawnAgent(args: SpawnAgentArgs): Promise<SpawnAgentResult
     return { status: "rejected", skill: args.skill, trigger: args.trigger };
   }
 
-  return doSpawn(args.skill, args.trigger);
+  return doSpawn(args.skill, args.trigger, args.reason);
 }

package/tools/bench-tools.ts

@@ -52,12 +52,8 @@ export async function benchExecute({
   }
 }
 
-/** Stub — full implementation deferred (Story 4.2). */
-export function scaffoldDoctype(_args: unknown): { error: string } {
-  return { error: "scaffold_doctype: not yet implemented — Story 4.2 (deferred)" };
-}
-
-/** Stub — full implementation Epic 6. */
-export function runTests(_args: unknown): { error: string } {
-  return { error: "run_tests: not yet implemented — Epic 6" };
+/** @NOT_IMPLEMENTED Epic 6 (deferred). Use bench_execute with 'bench run-tests --app {app}' instead. */
+export function runTests(_args: unknown): { error: string; _stub: true } {
+  console.warn("[bench-tools] run_tests called but not yet implemented (Epic 6)");
+  return { error: "run_tests: not yet implemented — Epic 6", _stub: true };
 }

package/tools/context-sandbox.ts

@@ -1,9 +1,14 @@
 /**
- * Context-mode sandbox routing for Frappe tool output.
+ * Output truncation guard for Frappe tool output.
  *
- * Context-mode MCP tools are accessible to the LLM session but not callable
- * directly from extension code. Until an HTTP endpoint is discoverable,
- * routeThroughContextMode applies the 8K truncation fallback.
+ * Context-mode MCP tools (ctx_execute, ctx_search, etc.) are only callable by
+ * the LLM agent — NOT from Node.js extension code. There is no HTTP endpoint
+ * to route to from here.
+ *
+ * This module is a last-resort truncation guard for bench_execute and
+ * frappe_query outputs that would otherwise flood the context window.
+ * The agent is instructed via AGENTS.md to use ctx_execute / ctx_batch_execute
+ * proactively instead of relying on this fallback.
  *
  * NFR17: truncation is NEVER silent — warning is always prepended.
  */
@@ -11,12 +16,11 @@
 const CHAR_LIMIT = 8192 * 4; // ~8K tokens at 4 chars/token
 
 /**
- * Routes raw tool output through the context-mode sandbox.
- * Falls back to 8K truncation with a visible warning if sandbox unavailable.
+ * Applies the 8K truncation guard to raw tool output.
+ * Named routeThroughContextMode for API compatibility with existing callers.
  * Never throws.
  */
 export async function routeThroughContextMode(raw: string): Promise<string> {
-  // TODO: wire to context-mode MCP HTTP endpoint when discoverable from extension code
   return applyTruncationFallback(raw);
 }