jfl 0.4.4 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jfl",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "Just Fucking Launch - CLI for AI-powered GTM and development",
   "type": "module",
   "main": "dist/index.js",
@@ -11,6 +11,7 @@
   },
   "files": [
     "dist",
+    "packages/pi",
     "scripts",
     "template",
     "clawdbot-skill",
@@ -90,7 +91,7 @@
     "@types/react": "^19.2.13",
     "@types/sql.js": "^1.4.9",
     "@types/ws": "^8.18.1",
-    "jest": "^30.2.0",
+    "jest": "^30.3.0",
     "ts-jest": "^29.4.6",
     "tsx": "^4.7.0",
     "typescript": "^5.3.3"

package/packages/pi/AGENTS.md

@@ -0,0 +1,112 @@
+# @jfl/pi — Multi-Agent Coordination
+
+This document describes how multiple Pi sessions coordinate within a JFL project.
+
+## Session Isolation
+
+Each Pi session gets its own branch (via JFL session management):
+```
+session-goose-20260125-xxxx
+session-hath-20260126-xxxx
+```
+
+Agents write to their own journal files:
+```
+.jfl/journal/session-goose-20260125-xxxx.jsonl
+.jfl/journal/session-hath-20260126-xxxx.jsonl
+```
+
+Context Hub aggregates all journals — each agent can see what others did via `jfl_context`.
+
+## Event Bus Coordination
+
+All agents connect to the same Context Hub (port 4242) via the MAP event bus.
+
+Key events agents emit and consume:
+
+| Event | Emitter | Consumers |
+|-------|---------|-----------|
+| `agent:health` | All agents | Grid overlay, PP |
+| `eval:scored` | Eval agent | PP, Stratus bridge |
+| `review:findings` | Reviewer agent | PP |
+| `task:requested` | PP, human | Builder agent |
+| `journal:entry` | Any agent | Footer, context |
+| `peter:dispatched` | PP | Status display |
+| `peter:completed` | PP | Status display |
+
+## Scope Enforcement
+
+Each GTM can declare a context scope in `.jfl/config.json`:
+
+```json
+{
+  "context_scope": {
+    "produces": ["discovery:*", "eval:*"],
+    "consumes": ["strategy:*", "seo:serp-data"],
+    "denied": ["portfolio:financial-*"]
+  }
+}
+```
+
+The `map-bridge` extension reads this and filters subscriptions accordingly.
+Cross-GTM leakage is blocked at the subscription level.
+
+## Portfolio Hierarchy
+
+```
+portfolio-hub (runs Context Hub on port 4242)
+├── productrank-gtm (port 4243)
+│   └── agents: scout, builder, eval
+├── seo-agent (port 4244)
+│   └── agents: crawler, ranker
+└── visaclaw (port 4245)
+    └── agents: mcp-registry, payment
+```
+
+Each GTM's `portfolio-bridge` extension phones home to parent on session end,
+syncing journals and eval scores for cross-GTM RL training.
+
+## Peter Parker Loop
+
+PP runs in the primary session and orchestrates others via Pi RPC:
+
+```
+task:requested → PP queries Stratus → pick best action
+              → spawn Pi RPC agent
+              → monitor → eval:scored
+              → if findings: spawn reviewer
+              → max 5 iterations
+              → peter:completed
+```
+
+## Running Multiple Sessions
+
+```bash
+# Terminal 1: Your interactive session
+jfl pi
+
+# Terminal 2: Spawn agent team
+jfl pi agents run --team teams/gtm-team.yaml
+
+# Inside Pi session: monitor agents
+/grid
+
+# Inside Pi session: trigger PP task
+/peter Fix the failing evals in src/lib/eval.ts
+```
+
+## Debugging
+
+```bash
+# Watch all MAP events
+jfl flows watch
+
+# Check agent health
+curl http://localhost:4242/api/events?pattern=agent:health
+
+# View training buffer
+tail -f ~/.jfl/training-buffer.jsonl
+
+# View journal across all sessions
+cat .jfl/journal/*.jsonl | sort -t'"' -k4 | tail -20
+```

package/packages/pi/extensions/agent-grid.ts

@@ -0,0 +1,191 @@
+/**
+ * Agent Grid Extension
+ *
+ * /grid command shows a live overlay of all active Pi sessions.
+ * Polls Context Hub for agent:health events.
+ * Beautiful themed card layout with status icons.
+ *
+ * @purpose /grid command — themed agent status overlay with live polling
+ */
+
+import { existsSync, readdirSync, statSync } from "fs"
+import { join } from "path"
+import type { PiContext, PiTheme } from "./types.js"
+import { hubUrl, authToken } from "./map-bridge.js"
+import { resolveDisplayName, formatAgentLabel } from "./agent-names.js"
+
+interface AgentHealth {
+  name: string
+  role: string
+  status: "running" | "idle" | "blocked" | "error"
+  task?: string
+  duration?: number
+  model?: string
+  lastSeen: number
+}
+
+const agents = new Map<string, AgentHealth>()
+
+function formatDuration(ms?: number): string {
+  if (!ms) return "-"
+  const s = Math.floor(ms / 1000)
+  if (s < 60) return `${s}s`
+  const m = Math.floor(s / 60)
+  const rs = s % 60
+  return `${m}m${rs > 0 ? ` ${rs}s` : ""}`
+}
+
+async function pollAgentHealth(): Promise<void> {
+  try {
+    const resp = await fetch(`${hubUrl}/api/events?pattern=agent:health&limit=50`, {
+      headers: authToken ? { Authorization: `Bearer ${authToken}` } : {},
+    })
+    if (!resp.ok) return
+
+    const data = await resp.json() as { events?: Array<{ data?: AgentHealth; ts?: string }> }
+    for (const event of data.events ?? []) {
+      if (!event.data?.name) continue
+      agents.set(event.data.name, {
+        ...event.data,
+        lastSeen: event.ts ? new Date(event.ts).getTime() : Date.now(),
+      })
+    }
+  } catch {}
+}
+
+function getLocalSessions(root: string): Array<{ name: string; age: number }> {
+  const journalDir = join(root, ".jfl", "journal")
+  if (!existsSync(journalDir)) return []
+  const now = Date.now()
+  const sessions: Array<{ name: string; age: number }> = []
+  for (const f of readdirSync(journalDir)) {
+    if (!f.startsWith("session-") || !f.endsWith(".jsonl")) continue
+    try {
+      const stat = statSync(join(journalDir, f))
+      const age = now - stat.mtimeMs
+      if (age < 600000) {
+        sessions.push({ name: resolveDisplayName(f.replace(".jsonl", "").replace("session-", "")), age })
+      }
+    } catch {}
+  }
+  return sessions
+}
+
+export function setupAgentGrid(ctx: PiContext): void {
+  ctx.on("map:agent:health", (data) => {
+    const health = data as AgentHealth
+    if (!health.name) return
+    agents.set(health.name, { ...health, lastSeen: Date.now() })
+  })
+
+  ctx.registerCommand({
+    name: "grid",
+    description: "Show live agent grid overlay",
+    async handler(_args, ctx) {
+      if (!ctx.ui.hasUI) {
+        ctx.ui.notify("Agent grid requires interactive mode", { level: "warn" })
+        return
+      }
+
+      await pollAgentHealth()
+
+      await ctx.ui.custom<void>((tui: any, theme: PiTheme, _kb: any, done: (r: void) => void) => {
+        let interval: ReturnType<typeof setInterval> | null = null
+
+        interval = setInterval(async () => {
+          await pollAgentHealth()
+          tui.requestRender()
+        }, 3000)
+
+        return {
+          handleInput(key: string) {
+            if (key === "\x1b" || key === "q") {
+              if (interval) clearInterval(interval)
+              done(undefined)
+            }
+          },
+
+          render(width: number): string[] {
+            const w = Math.min(width, 80)
+            const lines: string[] = []
+            const agentList = Array.from(agents.values())
+            const localSessions = getLocalSessions(ctx.session.projectRoot)
+
+            lines.push("")
+            lines.push(`  ${theme.fg("accent", "◆")} ${theme.bold("Agent Grid")}`)
+            lines.push(`  ${theme.fg("border", "─".repeat(w - 4))}`)
+            lines.push("")
+
+            if (agentList.length > 0) {
+              lines.push(`  ${theme.fg("accent", "MAP Agents")} ${theme.fg("dim", `(${agentList.length})`)}`)
+              lines.push("")
+
+              for (const a of agentList) {
+                const now = Date.now()
+                const age = now - a.lastSeen
+                const isOnline = age < 30000
+
+                const statusIcon = a.status === "running" ? theme.fg("success", "●")
+                  : a.status === "error" ? theme.fg("error", "✗")
+                  : a.status === "blocked" ? theme.fg("warning", "◆")
+                  : theme.fg("dim", "○")
+
+                const onlineStr = isOnline ? "" : theme.fg("error", " (offline)")
+                const displayName = resolveDisplayName(a.name)
+
+                lines.push(`  ${statusIcon} ${theme.fg("text", displayName.padEnd(20))} ${theme.fg("muted", a.role ?? "")}${onlineStr}`)
+
+                if (a.task) {
+                  lines.push(`    ${theme.fg("dim", a.task.slice(0, w - 8))}`)
+                }
+                if (a.model || a.duration) {
+                  const parts = [
+                    a.model ? theme.fg("dim", a.model) : "",
+                    a.duration ? theme.fg("dim", formatDuration(a.duration)) : "",
+                  ].filter(Boolean)
+                  if (parts.length) lines.push(`    ${parts.join(" │ ")}`)
+                }
+              }
+            }
+
+            if (localSessions.length > 0) {
+              if (agentList.length > 0) lines.push("")
+              lines.push(`  ${theme.fg("accent", "Local Sessions")} ${theme.fg("dim", `(${localSessions.length})`)}`)
+              lines.push("")
+
+              for (const s of localSessions) {
+                const ageStr = s.age < 60000 ? `${Math.floor(s.age / 1000)}s`
+                  : s.age < 3600000 ? `${Math.floor(s.age / 60000)}m`
+                  : `${Math.floor(s.age / 3600000)}h`
+                const icon = s.age < 120000 ? theme.fg("success", "●") : theme.fg("dim", "○")
+                lines.push(`  ${icon} ${theme.fg("text", s.name)} ${theme.fg("dim", ageStr + " ago")}`)
+              }
+            }
+
+            if (agentList.length === 0 && localSessions.length === 0) {
+              lines.push(`  ${theme.fg("dim", "No active agents or sessions")}`)
+              lines.push(`  ${theme.fg("dim", "Start agents: jfl pi agents run --team teams/gtm-team.yaml")}`)
+            }
+
+            lines.push("")
+            lines.push(`  ${theme.fg("dim", "Esc/q close  │  refreshes every 3s")}`)
+            lines.push("")
+
+            return lines
+          },
+
+          invalidate() {},
+        }
+      }, { overlay: true })
+    },
+  })
+}
+
+export function emitAgentHealth(
+  ctx: PiContext,
+  health: Omit<AgentHealth, "lastSeen">
+): void {
+  ctx.emit("agent:health", { ...health, ts: new Date().toISOString() })
+}
+
+export function stopAgentGrid(): void {}

package/packages/pi/extensions/agent-names.ts

@@ -0,0 +1,178 @@
+/**
+ * Agent Display Name Resolver
+ *
+ * Converts raw agent identifiers (file paths, kebab-case names, frontmatter names)
+ * into clean, human-readable display names for the TUI.
+ *
+ * @purpose Resolve ugly agent IDs to pretty display names across all TUI surfaces
+ */
+
+import { existsSync, readFileSync, readdirSync } from "fs"
+import { join, basename } from "path"
+
+export interface AgentInfo {
+  id: string
+  displayName: string
+  type: "service" | "peer" | "skill" | "custom"
+  color?: string
+  description?: string
+  serviceName?: string
+}
+
+const displayNameCache = new Map<string, AgentInfo>()
+let projectRoot = ""
+
+export function initAgentNames(root: string): void {
+  projectRoot = root
+  displayNameCache.clear()
+  scanAgentFiles(root)
+}
+
+function scanAgentFiles(root: string): void {
+  const agentsDir = join(root, ".claude", "agents")
+  if (!existsSync(agentsDir)) return
+
+  for (const file of readdirSync(agentsDir)) {
+    if (!file.endsWith(".md") || file.startsWith("_") || file === "README.md") continue
+
+    const filePath = join(agentsDir, file)
+    try {
+      const content = readFileSync(filePath, "utf-8")
+      const info = parseAgentFile(file, content)
+      if (info) displayNameCache.set(info.id, info)
+    } catch {}
+  }
+}
+
+function parseAgentFile(filename: string, content: string): AgentInfo | null {
+  const id = filename.replace(/\.md$/, "")
+
+  const frontmatter = parseFrontmatter(content)
+  const fmName = frontmatter.name ?? id
+  const color = frontmatter.color
+  const description = frontmatter.description
+
+  const type = detectAgentType(id, frontmatter)
+  const serviceName = extractServiceName(id)
+  const displayName = frontmatter.label
+    ?? frontmatter.display_name
+    ?? buildDisplayName(id, type)
+
+  return { id, displayName, type, color, description, serviceName }
+}
+
+function parseFrontmatter(content: string): Record<string, string> {
+  const match = content.match(/^---\n([\s\S]*?)\n---/)
+  if (!match) return {}
+
+  const result: Record<string, string> = {}
+  for (const line of match[1].split("\n")) {
+    const kv = line.match(/^(\w[\w_-]*)\s*:\s*(.+)/)
+    if (kv) result[kv[1]] = kv[2].trim()
+  }
+  return result
+}
+
+function detectAgentType(id: string, fm: Record<string, string>): AgentInfo["type"] {
+  if (fm.type === "peer-service" || id.startsWith("peer-service-") || id.startsWith("peer-")) return "peer"
+  if (id.startsWith("service-") || fm.type === "service") return "service"
+  const skillNames = ["web-architect", "content-creator", "brand-architect"]
+  if (skillNames.includes(id)) return "skill"
+  return "custom"
+}
+
+function extractServiceName(id: string): string {
+  return id
+    .replace(/^service-/, "")
+    .replace(/^peer-service-/, "")
+    .replace(/^peer-/, "")
+}
+
+function buildDisplayName(id: string, type: AgentInfo["type"]): string {
+  const clean = extractServiceName(id)
+  const titled = kebabToTitle(clean)
+  if (type === "peer") return titled
+  return titled
+}
+
+const ACRONYMS = new Set(["api", "ui", "cli", "db", "ml", "ai", "ci", "cd", "io", "id", "url", "uri", "sdk", "rl", "mcp", "gtm", "crm", "cms", "cdn", "dns", "tcp", "udp", "ssh", "tls", "ssl", "jwt", "aws", "gcp"])
+
+function kebabToTitle(str: string): string {
+  return str
+    .split("-")
+    .map(word => ACRONYMS.has(word.toLowerCase()) ? word.toUpperCase() : word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ")
+}
+
+/**
+ * Resolve any raw agent identifier to a clean display name.
+ *
+ * Handles:
+ *   .claude/agents/service-stratus-api.md  → Stratus API
+ *   service-stratus-api                     → Stratus API
+ *   peer-service-context-hub               → Context Hub
+ *   stratus-api.md                         → Stratus API
+ *   web-architect                          → Web Architect
+ */
+export function resolveDisplayName(raw: string): string {
+  const id = raw
+    .replace(/^@/, "")
+    .replace(/^\.?claude\/agents\//, "")
+    .replace(/\.md$/, "")
+    .replace(/^.*\//, "")
+
+  const cached = displayNameCache.get(id)
+  if (cached) return cached.displayName
+
+  const type = detectAgentType(id, {})
+  return buildDisplayName(id, type)
+}
+
+/**
+ * Resolve to full agent info (name, type, color, description).
+ */
+export function resolveAgentInfo(raw: string): AgentInfo {
+  const id = raw
+    .replace(/^@/, "")
+    .replace(/^\.?claude\/agents\//, "")
+    .replace(/\.md$/, "")
+    .replace(/^.*\//, "")
+
+  const cached = displayNameCache.get(id)
+  if (cached) return cached
+
+  const type = detectAgentType(id, {})
+  return {
+    id,
+    displayName: buildDisplayName(id, type),
+    type,
+    serviceName: extractServiceName(id),
+  }
+}
+
+/**
+ * Get all known agents with display info.
+ */
+export function listAgents(): AgentInfo[] {
+  if (displayNameCache.size === 0 && projectRoot) scanAgentFiles(projectRoot)
+  return Array.from(displayNameCache.values())
+}
+
+/**
+ * Format an agent name for TUI display with optional type badge.
+ */
+export function formatAgentLabel(raw: string, opts?: { badge?: boolean }): string {
+  const info = resolveAgentInfo(raw)
+
+  if (!opts?.badge) return info.displayName
+
+  const badges: Record<AgentInfo["type"], string> = {
+    service: "svc",
+    peer: "peer",
+    skill: "skill",
+    custom: "",
+  }
+
+  const badge = badges[info.type]
+  return badge ? `${info.displayName} [${badge}]` : info.displayName
+}