jfl 0.9.1 → 0.9.3

package/packages/pi/extensions/synopsis-tool.ts

@@ -48,7 +48,12 @@ export function setupSynopsisTool(ctx: PiContext): void {
       },
     },
     async handler(input) {
-      const { hours, author } = input as { hours?: number; author?: string }
+      const raw = input as { hours?: number | string; author?: string }
+      // Model sometimes passes "24h" or "48h" — strip the 'h' and parse
+      const hours = typeof raw.hours === "string"
+        ? parseInt(String(raw.hours).replace(/[^0-9]/g, ""), 10) || 24
+        : raw.hours
+      const author = raw.author
 
       const synopsisScript = findSynopsisScript(projectRoot)
       if (synopsisScript) {

package/packages/pi/extensions/training-buffer-tool.ts

@@ -14,6 +14,7 @@
 import { existsSync, readFileSync } from "fs"
 import { join } from "path"
 import type { PiContext, JflConfig, AgentEndEvent } from "./types.js"
+import { jflImport } from "./jfl-resolve.js"
 import { emitCustomEvent } from "./map-bridge.js"
 
 let projectRoot = ""
@@ -21,7 +22,7 @@ let projectRoot = ""
 async function getTrainingBuffer(): Promise<any> {
   try {
     // @ts-ignore — resolved from jfl package at runtime
-    const { TrainingBuffer } = await import("../../src/lib/training-buffer.js")
+    const { TrainingBuffer } = await jflImport("training-buffer")
     return new TrainingBuffer(projectRoot)
   } catch {
     return null
@@ -31,7 +32,7 @@ async function getTrainingBuffer(): Promise<any> {
 async function getTupleMiner(): Promise<any> {
   try {
     // @ts-ignore — resolved from jfl package at runtime
-    return await import("../../src/lib/tuple-miner.js")
+    return await jflImport("tuple-miner")
   } catch {
     return null
   }

package/packages/pi/extensions/types.ts

@@ -74,6 +74,7 @@ export interface PiContext {
     setWidget(id: string, content: string[] | WidgetFactory | undefined, opts?: { placement?: "aboveEditor" | "belowEditor" }): void
     setStatus(key: string, text: string | undefined): void
     setFooter(factory: ((tui: any, theme: PiTheme, footerData: any) => any) | undefined): void
+    setHeader?(factory: ((tui: any, theme: PiTheme) => { render: (width: number) => string[]; invalidate: () => void }) | undefined): void
     setEditorText(text: string): void
     theme: PiTheme
     hasUI: boolean
@@ -115,6 +116,8 @@ export interface AgentEndEvent {
 export interface ToolExecutionEvent {
   toolName?: string
   tool?: string
+  input?: Record<string, any>
+  args?: Record<string, any>
   result?: unknown
   isError?: boolean
   duration?: number

package/packages/pi/package.json

@@ -29,6 +29,7 @@
   ],
   "dependencies": {
     "axios": "^1.13.4",
+    "ws": "^8.19.0",
     "yaml": "^2.8.2"
   },
   "devDependencies": {
@@ -36,7 +37,9 @@
     "typescript": "^5.3.3"
   },
   "pi": {
-    "entry": "dist/extensions/index.js",
+
+    "entry": "dist/index.js",
+    "extensions": ["dist/index.js"],
     "skills": "skills",
     "themes": "themes/jfl.theme.json",
     "teams": "teams"

package/packages/pi/skills/viz/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: viz
+description: Terminal data visualization via kuva — inline plots for agents and humans
+---
+
+# /viz — Terminal Visualization
+
+Pipe JFL data to kuva for inline terminal plots. Agents see results without leaving flow.
+
+## Prerequisites
+
+```bash
+cargo install kuva --features cli
+```
+
+If kuva is not installed, falls back to ASCII bar/sparkline rendering.
+
+## Commands
+
+```
+/viz events      # Event bus activity (bar chart by type, sankey of service flows)
+/viz sessions    # Session activity (line chart over time, duration box plot)
+/viz costs       # API costs (bar by model, pie by provider)
+/viz tools       # Tool usage frequency (bar chart)
+/viz flows       # Flow trigger rates (bar chart, sankey of trigger→action)
+/viz arena       # Arena leaderboard (composite bar chart, score trajectory)
+/viz learning    # Pattern confidence trends (line chart)
+/viz health      # Service health dashboard (cost sparklines, error bars, latency box)
+/viz <custom>    # Describe what you want to visualize
+```
+
+## How It Works
+
+Each `/viz` command:
+1. Reads the relevant data source (events, journals, telemetry, arena results)
+2. Transforms to TSV format
+3. Pipes to `kuva [plot-type] --terminal`
+4. Renders inline in the terminal
+
+## Implementation
+
+### /viz events
+
+Read `.jfl/service-events.jsonl` and `.jfl/map-events.jsonl`:
+
+```bash
+# Event type distribution
+cat .jfl/service-events.jsonl | \
+  jq -r '.type' | sort | uniq -c | sort -rn | \
+  awk '{print $2"\t"$1}' | \
+  kuva bar --label-col 0 --value-col 1 --title "Events by Type" --terminal
+
+# Service-to-service flow (sankey)
+cat .jfl/service-events.jsonl | \
+  jq -r '[.source // "unknown", .type, 1] | @tsv' | \
+  kuva sankey --source-col 0 --target-col 1 --value-col 2 --title "Event Flows" --terminal
+```
+
+Or use the programmatic API from `jfl-cli/src/lib/kuva.ts`:
+
+```typescript
+import { barChart, linePlot, sparkline } from 'jfl-cli/src/lib/kuva.js'
+
+const events = loadEvents()
+const byType = countBy(events, 'type')
+const chart = barChart(
+  Object.entries(byType).map(([label, value]) => ({ label, value })),
+  'Events by Type'
+)
+console.log(chart)
+```
+
+### /viz sessions
+
+```bash
+# Sessions over time (line)
+cat .jfl/journal/*.jsonl | \
+  jq -r 'select(.type == "session-end") | [.ts[:10], 1] | @tsv' | \
+  sort | uniq -c | awk '{print $2"\t"$1}' | \
+  kuva line --x 0 --y 1 --title "Sessions per Day" --terminal
+```
+
+### /viz costs
+
+```bash
+# Cost by model (bar)
+cat .jfl/telemetry-queue.jsonl | \
+  jq -r 'select(.event == "stratus:api_call") | [(.model_name // "unknown"), .estimated_cost_usd] | @tsv' | \
+  kuva bar --label-col 0 --value-col 1 --title "Cost by Model" --terminal
+```
+
+### /viz arena
+
+```bash
+# Run from arena directory
+cd /path/to/productrank-arena
+npm run arena -- leaderboard --all --plots
+```
+
+Or programmatically — arena's `formatLeaderboardPlots()` renders composite scores as kuva bar chart.
+
+### /viz flows
+
+```bash
+# Flow triggers (bar)
+cat .jfl/service-events.jsonl | \
+  jq -r 'select(.type == "flow:triggered") | .data.flow_name' | \
+  sort | uniq -c | sort -rn | awk '{print $2"\t"$1}' | \
+  kuva bar --label-col 0 --value-col 1 --title "Flow Triggers" --terminal
+
+# Flow trigger→action sankey
+cat .jfl/service-events.jsonl | \
+  jq -r 'select(.type == "flow:completed") | [.data.flow_name, .data.action_type, 1] | @tsv' | \
+  kuva sankey --source-col 0 --target-col 1 --value-col 2 --title "Flow Actions" --terminal
+```
+
+### /viz health
+
+Composite dashboard — renders multiple charts:
+
+```
+  Health Dashboard
+  ━━━━━━━━━━━━━━━━
+
+  API Costs (last 24h)
+  [kuva bar: cost by model]
+
+  Error Rate ▁▂▁▁▃▅▂▁▁▁  (sparkline)
+
+  Latency Distribution
+  [kuva box: latency by endpoint]
+
+  Session Duration
+  [kuva box: duration by session]
+```
+
+### /viz learning (RL / Training)
+
+For agents with reinforcement learning loops:
+
+```typescript
+// After each training epoch
+const rewards = epochs.map((e, i) => ({ ts: `epoch-${i}`, value: e.reward }))
+const chart = linePlot(rewards, 'Reward per Epoch')
+console.log(chart)
+
+// Action distribution
+const actions = countBy(episodes, 'action')
+const actionChart = barChart(
+  Object.entries(actions).map(([label, value]) => ({ label, value })),
+  'Action Frequency'
+)
+console.log(actionChart)
+```
+
+### /viz custom
+
+When user describes what they want to visualize, the agent:
+1. Identifies the data source
+2. Extracts/transforms to TSV
+3. Picks the right kuva plot type
+4. Renders with `--terminal`
+
+## Available Plot Types
+
+| kuva command | Best for | Key flags |
+|-------------|----------|-----------|
+| `bar` | Categorical comparisons | `--label-col`, `--value-col` |
+| `line` | Time series, trends | `--x`, `--y`, `--color-by` |
+| `scatter` | Correlations, clustering | `--x`, `--y`, `--color-by` |
+| `box` | Distributions, outliers | `--group-col`, `--value-col` |
+| `histogram` | Value distributions | `--value-col`, `--bins` |
+| `pie` | Proportions | `--label-col`, `--value-col`, `--donut` |
+| `sankey` | Flow routing, transitions | `--source-col`, `--target-col`, `--value-col` |
+| `heatmap` | Matrix data, correlations | First col = row labels |
+| `violin` | Distribution shape | `--group-col`, `--value-col` |
+
+## Design Principles
+
+1. **TSV is the universal interface** — any data source that can produce rows can generate kuva plots
+2. **Graceful degradation** — ASCII fallback (bars, sparklines) when kuva isn't installed
+3. **Agent-native** — inline terminal output, no browser needed, no context-switching
+4. **Composable** — pipe any JSONL through `jq -r @tsv` into kuva. Unix philosophy.
+5. **Zero coupling** — kuva is a standalone Rust binary. kuva.ts is a standalone module. Neither needs the other's internals.
+
+## Examples
+
+```
+User: "show me event activity"
+Agent: *runs /viz events*
+→ Bar chart of event types + sankey of service flows
+
+User: "what's our cost breakdown?"
+Agent: *runs /viz costs*
+→ Bar chart by model + pie chart by provider
+
+User: "how is the arena looking?"
+Agent: *runs /viz arena*
+→ Leaderboard table + composite score bar chart
+
+User: "plot my training rewards"
+Agent: *runs /viz learning with user's data*
+→ Line chart of reward per epoch + action frequency bars
+```

package/scripts/pp-branch-pr.sh

@@ -43,15 +43,33 @@ if git diff --quiet HEAD && [ -z "$(git ls-files --others --exclude-standard)" ]
   exit 0
 fi
 
-# 4. Commit
+# 4. Commit with provenance signing
 git add -A
-COMMIT_MSG="fix(pp): ${TASK}
 
-Agent: peter-parker
-Branch: ${BRANCH_NAME}
-Auto-generated by JFL self-driving loop
+AGENT_ID="peter-parker"
+AGENT_SESSION="${BRANCH_NAME}"
+AGENT_TIMESTAMP="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+
+# Compute provenance hash from staged diff + agent identity
+PROVENANCE_KEY_PATH=".jfl/provenance-key"
+if [ ! -f "${PROVENANCE_KEY_PATH}" ]; then
+  mkdir -p .jfl
+  openssl rand -hex 32 > "${PROVENANCE_KEY_PATH}"
+  chmod 600 "${PROVENANCE_KEY_PATH}"
+fi
+PROVENANCE_KEY=$(cat "${PROVENANCE_KEY_PATH}")
+STAGED_DIFF=$(git diff --cached)
+PROVENANCE_PAYLOAD="${AGENT_ID}
+${AGENT_TIMESTAMP}
+${STAGED_DIFF}"
+PROVENANCE_HASH="sha256:$(printf '%s' "${PROVENANCE_PAYLOAD}" | openssl dgst -sha256 -hmac "${PROVENANCE_KEY}" | awk '{print $NF}')"
+
+COMMIT_MSG="fix(pp): ${TASK}
 
-Co-authored-by: Peter Parker <pp@jfl.dev>"
+Agent-Id: ${AGENT_ID}
+Agent-Session: ${AGENT_SESSION}
+Provenance-Hash: ${PROVENANCE_HASH}
+Agent-Timestamp: ${AGENT_TIMESTAMP}"
 
 git commit -m "${COMMIT_MSG}"
 

package/scripts/pp-branch-pr.sh.bak

@@ -0,0 +1,115 @@
+#!/bin/bash
+# scripts/pp-branch-pr.sh
+#
+# Wraps Peter Parker agent execution in git branch + PR workflow.
+# Creates a branch, runs the agent, commits changes, opens a PR,
+# and posts a pr:created event to the hub.
+#
+# Called by flow engine spawn action or directly.
+#
+# Usage: pp-branch-pr.sh <task-description> [hub-url] [hub-token]
+
+set -euo pipefail
+
+TASK="${1:?Usage: pp-branch-pr.sh <task-description> [hub-url] [hub-token]}"
+HUB_URL="${2:-}"
+HUB_TOKEN="${3:-}"
+BRANCH_NAME="pp/fix-$(date +%s)"
+BASE_BRANCH="main"
+
+if [ -z "$HUB_URL" ] && [ -f ".jfl/context-hub.port" ]; then
+  PORT=$(cat .jfl/context-hub.port)
+  HUB_URL="http://localhost:${PORT}"
+fi
+if [ -z "$HUB_TOKEN" ] && [ -f ".jfl/context-hub.token" ]; then
+  HUB_TOKEN=$(cat .jfl/context-hub.token)
+fi
+
+echo "PP: Creating branch ${BRANCH_NAME}"
+
+# 1. Create branch from clean main
+git fetch origin "${BASE_BRANCH}" 2>/dev/null || true
+git checkout -b "${BRANCH_NAME}" "origin/${BASE_BRANCH}" 2>/dev/null || git checkout -b "${BRANCH_NAME}" "${BASE_BRANCH}"
+
+# 2. Run Peter Parker
+echo "PP: Running agent on task: ${TASK}"
+jfl peter run --task "${TASK}"
+
+# 3. Check if anything changed
+if git diff --quiet HEAD && [ -z "$(git ls-files --others --exclude-standard)" ]; then
+  echo "PP: No changes made, cleaning up"
+  git checkout "${BASE_BRANCH}" 2>/dev/null || true
+  git branch -D "${BRANCH_NAME}" 2>/dev/null || true
+  exit 0
+fi
+
+# 4. Commit
+git add -A
+COMMIT_MSG="fix(pp): ${TASK}
+
+Agent: peter-parker
+Branch: ${BRANCH_NAME}
+Auto-generated by JFL self-driving loop
+
+Co-authored-by: Peter Parker <pp@jfl.dev>"
+
+git commit -m "${COMMIT_MSG}"
+
+# 5. Push
+git push -u origin "${BRANCH_NAME}"
+
+# 6. Create PR
+PR_TITLE="PP: $(echo "${TASK}" | head -c 60)"
+PR_BODY="## Auto-generated by Peter Parker
+
+**Task:** ${TASK}
+**Branch:** \`${BRANCH_NAME}\`
+
+### Eval Suite
+This PR will be evaluated by the CI eval suite.
+Auto-merge will trigger if eval score improves over baseline.
+
+---
+*Generated by JFL self-driving loop*"
+
+PR_URL=$(gh pr create \
+  --title "${PR_TITLE}" \
+  --body "${PR_BODY}" \
+  --base "${BASE_BRANCH}" \
+  --head "${BRANCH_NAME}" \
+  --label "pp-generated" 2>&1) || {
+  echo "PP: Label may not exist, retrying without label"
+  PR_URL=$(gh pr create \
+    --title "${PR_TITLE}" \
+    --body "${PR_BODY}" \
+    --base "${BASE_BRANCH}" \
+    --head "${BRANCH_NAME}" 2>&1)
+}
+
+echo "PP: PR created at ${PR_URL}"
+
+# 7. Post event to hub
+if [ -n "${HUB_URL}" ]; then
+  TASK_JSON=$(printf '%s' "${TASK}" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read().strip()))')
+
+  CURL_ARGS=(-s -X POST "${HUB_URL}/api/events" -H "Content-Type: application/json")
+  if [ -n "${HUB_TOKEN}" ]; then
+    CURL_ARGS+=(-H "Authorization: Bearer ${HUB_TOKEN}")
+  fi
+  CURL_ARGS+=(-d "{
+    \"type\": \"pr:created\",
+    \"source\": \"peter-parker\",
+    \"data\": {
+      \"task\": ${TASK_JSON},
+      \"pr_url\": \"${PR_URL}\",
+      \"branch\": \"${BRANCH_NAME}\"
+    }
+  }")
+
+  curl "${CURL_ARGS[@]}" 2>/dev/null || echo "PP: Warning - could not post event to hub"
+fi
+
+# 8. Return to base branch
+git checkout "${BASE_BRANCH}" 2>/dev/null || true
+
+echo "PP: Done"

package/template/.pi/settings.json

@@ -0,0 +1,5 @@
+{
+  "packages": [
+    "npm:@jfl/pi"
+  ]
+}