jfl 0.4.4 → 0.5.0

package/packages/pi/extensions/peter-parker.ts

@@ -0,0 +1,202 @@
+/**
+ * Peter Parker Extension — Full Orchestrator
+ *
+ * Replaces the WebSocket bridge with a proper Pi extension orchestrator.
+ * Subscribes to MAP events, queries Stratus predictor for optimal action,
+ * spawns Pi RPC subprocesses, and runs the review loop (max 5 iterations).
+ *
+ * @purpose Full Peter Parker orchestrator — review loop with Stratus dispatch via Pi RPC
+ */
+
+import { spawn } from "child_process"
+import { existsSync, readFileSync } from "fs"
+import { join } from "path"
+import type { PiContext, JflConfig } from "./types.js"
+import { emitCustomEvent, hubUrl, authToken } from "./map-bridge.js"
+
+interface ReviewTask {
+  id: string
+  prompt: string
+  source: string
+  priority?: number
+}
+
+interface PeterIteration {
+  taskId: string
+  iteration: number
+  agentPid?: number
+  startTime: Date
+  prediction?: { delta: number; recommendation: string }
+  result?: "success" | "failed" | "max_iterations"
+}
+
+const MAX_ITERATIONS = 5
+let projectRoot = ""
+let maxIterations = MAX_ITERATIONS
+let activeIterations = new Map<string, PeterIteration>()
+
+async function getPredictor(root: string) {
+  try {
+    // @ts-ignore — resolved from jfl package at runtime
+    const { Predictor } = await import("../../src/lib/predictor.js")
+    return new Predictor(root)
+  } catch {
+    return null
+  }
+}
+
+async function spawnPiAgent(
+  ctx: PiContext,
+  task: ReviewTask,
+  extensionPath: string
+): Promise<{ exitCode: number | null }> {
+  return new Promise((resolve) => {
+    const args = [
+      "--mode", "rpc",
+      "--extension", extensionPath,
+      "--task", task.prompt,
+      "--yolo",
+    ]
+
+    ctx.log(`PP: spawning agent for task ${task.id}`, "debug")
+
+    const proc = spawn("pi", args, {
+      cwd: projectRoot,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        JFL_SESSION_ID: ctx.session.id,
+        JFL_TASK_ID: task.id,
+      },
+    })
+
+    proc.stdout?.on("data", (d: Buffer) => ctx.log(`PP agent: ${d.toString().trim()}`, "debug"))
+    proc.stderr?.on("data", (d: Buffer) => ctx.log(`PP agent err: ${d.toString().trim()}`, "debug"))
+
+    proc.on("close", (code) => resolve({ exitCode: code }))
+    proc.on("error", () => resolve({ exitCode: -1 }))
+
+    setTimeout(() => {
+      proc.kill()
+      resolve({ exitCode: -1 })
+    }, 5 * 60 * 1000)
+  })
+}
+
+async function runReviewLoop(ctx: PiContext, task: ReviewTask): Promise<void> {
+  const current = activeIterations.get(task.id)
+  const iteration = current ? current.iteration + 1 : 1
+
+  if (iteration > maxIterations) {
+    ctx.log(`PP: max iterations (${maxIterations}) reached for task ${task.id}`, "warn")
+    await emitCustomEvent(ctx, "peter:max-iterations", { taskId: task.id, iterations: iteration - 1 })
+    activeIterations.delete(task.id)
+    return
+  }
+
+  const iterRecord: PeterIteration = {
+    taskId: task.id,
+    iteration,
+    startTime: new Date(),
+  }
+
+  const predictor = await getPredictor(projectRoot)
+  if (predictor) {
+    try {
+      const prediction = await predictor.predict({
+        proposal: {
+          description: task.prompt,
+          change_type: "fix",
+          scope: "small",
+        },
+        current_score: 0,
+        goal: "resolve review findings",
+        recent_trajectory: [],
+      })
+      iterRecord.prediction = { delta: prediction.predicted_delta, recommendation: prediction.recommendation }
+
+      if (prediction.recommendation === "abandon") {
+        ctx.log(`PP: predictor recommends abandon for task ${task.id}`, "info")
+        activeIterations.delete(task.id)
+        return
+      }
+    } catch {}
+  }
+
+  activeIterations.set(task.id, iterRecord)
+  await emitCustomEvent(ctx, "peter:dispatched", { taskId: task.id, iteration, prediction: iterRecord.prediction })
+
+  const extensionPath = join(projectRoot, "node_modules", "@jfl", "pi", "dist", "extensions", "index.js")
+  const result = await spawnPiAgent(ctx, task, extensionPath)
+
+  iterRecord.result = result.exitCode === 0 ? "success" : "failed"
+  activeIterations.set(task.id, iterRecord)
+
+  if (result.exitCode !== 0) {
+    ctx.log(`PP: agent failed (iteration ${iteration}), will retry`, "info")
+    await runReviewLoop(ctx, task)
+  } else {
+    await emitCustomEvent(ctx, "peter:completed", { taskId: task.id, iterations: iteration })
+    activeIterations.delete(task.id)
+  }
+}
+
+export async function setupPeterParker(ctx: PiContext, config: JflConfig): Promise<void> {
+  projectRoot = ctx.session.projectRoot
+  maxIterations = config.pi?.max_peter_iterations ?? MAX_ITERATIONS
+
+  ctx.on("map:eval:scored", async (data) => {
+    const event = data as { taskId?: string; score?: number; findings?: string[] }
+    if (!event.taskId || !event.findings?.length) return
+
+    const task: ReviewTask = {
+      id: event.taskId,
+      prompt: `Review findings to address:\n${event.findings.join("\n")}`,
+      source: "eval:scored",
+    }
+    await runReviewLoop(ctx, task)
+  })
+
+  ctx.on("map:review:findings", async (data) => {
+    const event = data as { id?: string; findings?: string; priority?: number }
+    if (!event.findings) return
+
+    const task: ReviewTask = {
+      id: event.id ?? `review-${Date.now()}`,
+      prompt: event.findings,
+      source: "review:findings",
+      priority: event.priority,
+    }
+    await runReviewLoop(ctx, task)
+  })
+
+  ctx.on("map:task:requested", async (data) => {
+    const event = data as { id?: string; prompt?: string }
+    if (!event.prompt) return
+
+    const task: ReviewTask = {
+      id: event.id ?? `task-${Date.now()}`,
+      prompt: event.prompt,
+      source: "task:requested",
+    }
+    await runReviewLoop(ctx, task)
+  })
+
+  ctx.registerCommand({
+    name: "peter",
+    description: "Peter Parker orchestrator — run a task through the review loop",
+    async handler(args, ctx) {
+      if (!args.trim()) {
+        ctx.ui.notify("Usage: /peter <task description>", { level: "info" })
+        return
+      }
+      const task: ReviewTask = {
+        id: `peter-${Date.now()}`,
+        prompt: args.trim(),
+        source: "manual",
+      }
+      ctx.ui.notify(`Starting Peter Parker loop for: ${args.trim().slice(0, 60)}`, { level: "info" })
+      await runReviewLoop(ctx, task)
+    },
+  })
+}

package/packages/pi/extensions/policy-head-tool.ts

@@ -0,0 +1,276 @@
+/**
+ * Policy Head Tool
+ *
+ * Exposes the RL policy head to the agent as a tool. The agent can score
+ * candidate actions before executing them — "should I fix this test or
+ * refactor that module?" — and get a predicted reward delta.
+ *
+ * Also registers /policy command to show policy head stats and rank
+ * ad-hoc proposals interactively.
+ *
+ * @purpose Pi tool for RL policy head — score candidate actions, rank proposals
+ */
+
+import { existsSync, readFileSync } from "fs"
+import { join } from "path"
+import type { PiContext, JflConfig } from "./types.js"
+import { emitCustomEvent } from "./map-bridge.js"
+
+let projectRoot = ""
+
+interface PolicyWeights {
+  version: number
+  trained_on: number
+  direction_accuracy: number
+  rank_correlation: number
+  target_mean: number
+  target_std: number
+}
+
+function getWeightsInfo(): PolicyWeights | null {
+  const weightsPath = join(projectRoot, ".jfl", "policy-weights.json")
+  if (!existsSync(weightsPath)) return null
+  try {
+    return JSON.parse(readFileSync(weightsPath, "utf-8")) as PolicyWeights
+  } catch {
+    return null
+  }
+}
+
+async function getPolicyHead(): Promise<any> {
+  try {
+    // @ts-ignore — resolved from jfl package at runtime
+    const { PolicyHeadInference } = await import("../../src/lib/policy-head.js")
+    return new PolicyHeadInference(projectRoot)
+  } catch {
+    return null
+  }
+}
+
+async function getTrainingBuffer(): Promise<any> {
+  try {
+    // @ts-ignore — resolved from jfl package at runtime
+    const { TrainingBuffer } = await import("../../src/lib/training-buffer.js")
+    return new TrainingBuffer(projectRoot)
+  } catch {
+    return null
+  }
+}
+
+export async function setupPolicyHeadTool(ctx: PiContext, _config: JflConfig): Promise<void> {
+  projectRoot = ctx.session.projectRoot
+
+  ctx.registerTool({
+    name: "jfl_policy_score",
+    description: "Score a candidate action using the RL policy head. Returns predicted reward delta to help decide which action to take next. Requires trained policy weights (.jfl/policy-weights.json).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action_type: {
+          type: "string",
+          description: "Type of action",
+          enum: ["fix", "refactor", "feature", "test", "config", "experiment"],
+        },
+        description: {
+          type: "string",
+          description: "What the action does (1-2 sentences)",
+        },
+        files: {
+          type: "string",
+          description: "Comma-separated list of files affected",
+        },
+        scope: {
+          type: "string",
+          description: "Scope of change",
+          enum: ["small", "medium", "large"],
+        },
+      },
+      required: ["action_type", "description"],
+    },
+    async handler(input) {
+      const {
+        action_type,
+        description,
+        files,
+        scope,
+      } = input as {
+        action_type: string
+        description: string
+        files?: string
+        scope?: string
+      }
+
+      const policyHead = await getPolicyHead()
+      if (!policyHead || !policyHead.isLoaded) {
+        return "Policy head not available. No trained weights found at .jfl/policy-weights.json. Run `jfl eval train` to train the policy head from existing training tuples."
+      }
+
+      const tb = await getTrainingBuffer()
+      const entries: any[] = tb ? tb.read() : []
+      const recentDeltas = entries.slice(-10).map((e: any) => e.reward.composite_delta)
+
+      const state = {
+        composite_score: entries.length > 0
+          ? entries[entries.length - 1].reward.composite_delta + entries[entries.length - 1].state.composite_score
+          : 0,
+        dimension_scores: {} as Record<string, number>,
+        tests_passing: 0,
+        tests_total: 0,
+        trajectory_length: entries.length,
+        recent_deltas: recentDeltas,
+        agent: "pi-agent",
+      }
+
+      const action = {
+        type: action_type as "fix" | "refactor" | "feature" | "test" | "config" | "experiment",
+        description,
+        files_affected: files ? files.split(",").map(f => f.trim()) : [],
+        scope: (scope || "medium") as "small" | "medium" | "large",
+        branch: ctx.session.branch,
+      }
+
+      try {
+        const predicted = await policyHead.predictReward(state, action)
+        const stats = policyHead.stats
+
+        await emitCustomEvent(ctx, "policy:scored", {
+          action_type,
+          description: description.slice(0, 80),
+          predicted_reward: predicted,
+        })
+
+        const lines = [
+          `Predicted reward delta: ${predicted >= 0 ? "+" : ""}${predicted.toFixed(4)}`,
+          `Recommendation: ${predicted > 0.01 ? "PROCEED — positive expected outcome" : predicted > -0.005 ? "NEUTRAL — marginal expected impact" : "SKIP — negative expected outcome"}`,
+          "",
+          `Policy head stats:`,
+          `  Trained on: ${stats?.trained_on ?? "?"} tuples`,
+          `  Direction accuracy: ${stats?.direction_accuracy ? (stats.direction_accuracy * 100).toFixed(1) + "%" : "?"}`,
+          `  Rank correlation: ${stats?.rank_correlation?.toFixed(3) ?? "?"}`,
+        ]
+
+        return lines.join("\n")
+      } catch (err) {
+        return `Policy head inference failed: ${err}. Ensure STRATUS_API_KEY is set for embedding generation.`
+      }
+    },
+  })
+
+  ctx.registerTool({
+    name: "jfl_policy_rank",
+    description: "Rank multiple candidate actions by predicted reward. Pass 2-5 actions as JSON array. Returns ranked list with predicted deltas.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        actions: {
+          type: "string",
+          description: 'JSON array of actions, each with: {"type": "fix|refactor|feature|test|config|experiment", "description": "what it does", "files": ["file1.ts"], "scope": "small|medium|large"}',
+        },
+      },
+      required: ["actions"],
+    },
+    async handler(input) {
+      const { actions: actionsStr } = input as { actions: string }
+
+      const policyHead = await getPolicyHead()
+      if (!policyHead || !policyHead.isLoaded) {
+        return "Policy head not available. No trained weights at .jfl/policy-weights.json."
+      }
+
+      let candidates: Array<{
+        type: string
+        description: string
+        files?: string[]
+        scope?: string
+      }>
+      try {
+        candidates = JSON.parse(actionsStr)
+        if (!Array.isArray(candidates) || candidates.length < 2) {
+          return "Provide at least 2 actions as a JSON array."
+        }
+      } catch {
+        return "Invalid JSON. Provide a JSON array of action objects."
+      }
+
+      const tb = await getTrainingBuffer()
+      const entries: any[] = tb ? tb.read() : []
+
+      const state = {
+        composite_score: entries.length > 0
+          ? entries[entries.length - 1].reward.composite_delta + entries[entries.length - 1].state.composite_score
+          : 0,
+        dimension_scores: {} as Record<string, number>,
+        tests_passing: 0,
+        tests_total: 0,
+        trajectory_length: entries.length,
+        recent_deltas: entries.slice(-10).map((e: any) => e.reward.composite_delta),
+        agent: "pi-agent",
+      }
+
+      const rlActions = candidates.map(c => ({
+        type: (c.type || "feature") as "fix" | "refactor" | "feature" | "test" | "config" | "experiment",
+        description: c.description,
+        files_affected: c.files || [],
+        scope: (c.scope || "medium") as "small" | "medium" | "large",
+        branch: ctx.session.branch,
+      }))
+
+      try {
+        const ranked = await policyHead.rankActions(state, rlActions)
+
+        await emitCustomEvent(ctx, "policy:ranked", {
+          count: ranked.length,
+          top: ranked[0]?.action.description.slice(0, 60),
+        })
+
+        const lines = ["Ranked actions (best first):", ""]
+        for (const r of ranked) {
+          const sign = r.predictedReward >= 0 ? "+" : ""
+          lines.push(`  #${r.rank} [${sign}${r.predictedReward.toFixed(4)}] ${r.action.type}: ${r.action.description.slice(0, 80)}`)
+        }
+
+        return lines.join("\n")
+      } catch (err) {
+        return `Ranking failed: ${err}`
+      }
+    },
+  })
+
+  ctx.registerCommand({
+    name: "policy",
+    description: "Show policy head status and training buffer stats",
+    async handler(_args, ctx) {
+      const weights = getWeightsInfo()
+      const tb = await getTrainingBuffer()
+      const stats = tb ? tb.stats() : null
+
+      const lines: string[] = []
+
+      if (weights) {
+        lines.push(
+          "Policy Head: LOADED",
+          `  Trained on: ${weights.trained_on} tuples`,
+          `  Direction accuracy: ${(weights.direction_accuracy * 100).toFixed(1)}%`,
+          `  Rank correlation: ${weights.rank_correlation.toFixed(3)}`,
+          "",
+        )
+      } else {
+        lines.push("Policy Head: NOT LOADED (no .jfl/policy-weights.json)", "")
+      }
+
+      if (stats) {
+        lines.push(
+          `Training Buffer: ${stats.total} tuples`,
+          `  Avg reward: ${stats.avgReward.toFixed(4)}`,
+          `  Improvement rate: ${(stats.improvedRate * 100).toFixed(1)}%`,
+          `  By agent: ${Object.entries(stats.byAgent).map(([k, v]) => `${k}=${v}`).join(", ") || "none"}`,
+          `  By source: ${Object.entries(stats.bySource).map(([k, v]) => `${k}=${v}`).join(", ") || "none"}`,
+        )
+      } else {
+        lines.push("Training Buffer: empty or unavailable")
+      }
+
+      ctx.ui.notify(lines.join("\n"), { level: "info" })
+    },
+  })
+}

package/packages/pi/extensions/portfolio-bridge.ts

@@ -0,0 +1,90 @@
+/**
+ * Portfolio Bridge Extension
+ *
+ * Handles cross-GTM coordination: phoneHome on session end, journal sync to parent,
+ * and eval scores propagated to portfolio hub for cross-GTM RL training.
+ *
+ * @purpose Portfolio-GTM coordination — phoneHome, journal sync, eval propagation
+ */
+
+import { existsSync, readFileSync } from "fs"
+import { join } from "path"
+import type { PiContext, JflConfig } from "./types.js"
+import { emitCustomEvent } from "./map-bridge.js"
+
+let projectRoot = ""
+let portfolioParent: string | null = null
+
+async function phoneHome(ctx: PiContext): Promise<void> {
+  if (!portfolioParent || !existsSync(portfolioParent)) return
+
+  try {
+    // @ts-ignore — resolved from jfl package at runtime
+    const { phoneHomeToPortfolio } = await import("../../src/lib/service-gtm.js")
+    await phoneHomeToPortfolio(projectRoot)
+    ctx.log("Portfolio phoneHome complete", "debug")
+  } catch (err) {
+    ctx.log(`Portfolio phoneHome failed: ${err}`, "debug")
+  }
+}
+
+async function syncJournalEntry(ctx: PiContext, entry: unknown): Promise<void> {
+  if (!portfolioParent || !existsSync(portfolioParent)) return
+
+  try {
+    // @ts-ignore — resolved from jfl package at runtime
+    const { writeSyncToParent } = await import("../../src/lib/service-gtm.js")
+    await (writeSyncToParent as (root: string, entry: unknown) => Promise<void>)(projectRoot, entry)
+  } catch (err) {
+    ctx.log(`Journal sync to parent failed: ${err}`, "debug")
+  }
+}
+
+async function propagateEvalToPortfolio(ctx: PiContext, evalData: unknown): Promise<void> {
+  if (!portfolioParent) return
+
+  const portfolioConfigPath = join(portfolioParent, ".jfl", "context-hub.port")
+  if (!existsSync(portfolioConfigPath)) return
+
+  try {
+    const port = readFileSync(portfolioConfigPath, "utf-8").trim()
+    const portfolioHub = `http://localhost:${port}`
+    const tokenPath = join(portfolioParent, ".jfl", "context-hub.token")
+    const token = existsSync(tokenPath) ? readFileSync(tokenPath, "utf-8").trim() : null
+
+    await fetch(`${portfolioHub}/api/events`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      },
+      body: JSON.stringify({
+        type: "eval:scored",
+        source: projectRoot,
+        data: evalData,
+        ts: new Date().toISOString(),
+      }),
+    })
+  } catch {}
+}
+
+export async function setupPortfolioBridge(ctx: PiContext, config: JflConfig): Promise<void> {
+  projectRoot = ctx.session.projectRoot
+  portfolioParent = config.portfolio_parent ?? null
+
+  if (!portfolioParent) return
+
+  ctx.on("map:journal:entry", (data) => syncJournalEntry(ctx, data))
+
+  ctx.on("map:eval:scored", (data) => propagateEvalToPortfolio(ctx, data))
+
+  ctx.on("map:portfolio:directive", async (data) => {
+    const directive = data as { action?: string; payload?: unknown }
+    ctx.log(`Portfolio directive received: ${directive.action}`, "info")
+    await emitCustomEvent(ctx, "portfolio:directive:received", directive)
+  })
+}
+
+export async function onPortfolioShutdown(ctx: PiContext): Promise<void> {
+  await phoneHome(ctx)
+}

package/packages/pi/extensions/session.ts

@@ -0,0 +1,90 @@
+/**
+ * JFL Session Extension
+ *
+ * Handles auto-commit and session cleanup within a Pi session.
+ * Does NOT run session-init.sh — that script is a Claude Code pre-hook that
+ * launches the AI CLI, which would cause a double-launch inside Pi.
+ * Pi IS the AI runtime; we only handle the persistent background tasks here.
+ *
+ * @purpose Pi session lifecycle — auto-commit daemon + cleanup script delegation
+ */
+
+import { execSync, spawn } from "child_process"
+import { existsSync, readFileSync } from "fs"
+import { join } from "path"
+import type { PiContext, JflConfig } from "./types.js"
+
+let autoCommitProcess: ReturnType<typeof spawn> | null = null
+
+function findScript(root: string, scriptName: string): string | null {
+  const candidates = [
+    join(root, "scripts", "session", scriptName),
+    join(root, "scripts", scriptName),
+  ]
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate
+  }
+  return null
+}
+
+export async function setupSession(ctx: PiContext, _config: JflConfig): Promise<void> {
+  const root = ctx.session.projectRoot
+
+  // Start auto-commit daemon — detached so it outlives this call
+  const autoCommitScript = findScript(root, "auto-commit.sh")
+  if (autoCommitScript) {
+    autoCommitProcess = spawn("bash", [autoCommitScript, "start", "120"], {
+      cwd: root,
+      detached: true,
+      stdio: "ignore",
+    })
+    autoCommitProcess.unref()
+    ctx.log("Auto-commit daemon started (120s interval)", "debug")
+  }
+
+  ctx.emit("hook:session-start", {
+    session: ctx.session.id,
+    branch: ctx.session.branch,
+    projectRoot: root,
+    ts: new Date().toISOString(),
+  })
+}
+
+export async function onShutdown(ctx: PiContext): Promise<void> {
+  const root = ctx.session.projectRoot
+
+  if (autoCommitProcess) {
+    try {
+      autoCommitProcess.kill()
+    } catch {}
+    autoCommitProcess = null
+  }
+
+  const cleanupScript = findScript(root, "session-cleanup.sh")
+  if (cleanupScript) {
+    try {
+      execSync(`bash "${cleanupScript}"`, { cwd: root, stdio: "inherit" })
+    } catch (err) {
+      ctx.log(`session-cleanup.sh failed: ${err}`, "warn")
+    }
+  }
+
+  ctx.emit("hook:session-end", {
+    session: ctx.session.id,
+    branch: ctx.session.branch,
+    ts: new Date().toISOString(),
+  })
+}
+
+export function getCurrentBranch(root: string): string {
+  try {
+    return execSync("git branch --show-current", { cwd: root }).toString().trim()
+  } catch {
+    try {
+      const saved = readFileSync(join(root, ".jfl", "current-session-branch.txt"), "utf-8").trim()
+      return saved
+    } catch {
+      return "main"
+    }
+  }
+}