@hassangameryt/freeflow 0.3.0 → 0.5.0

package/pi-extension/freeflow/index.js

@@ -0,0 +1 @@
+export { default } from "../dist/index.js";

package/pi-extension/src/index.ts

@@ -1,86 +1,247 @@
-import { handleNativeToolSafetyNet } from "./native-safety-net.js";
-import { handleObservedToolRouting } from "./observed-tool-routing.js";
-import { registerRouterTools } from "./router-tools.js";
+import { handleNativeToolSafetyNet } from "./output-router/native-safety-net.js";
+import { handleObservedToolRouting } from "./output-router/observed-tool-routing.js";
+import { registerRouterTools } from "./output-router/router-tools.js";
+import { handleFreeflowCommand, handleOutputRouterCommand } from "./settings/settings-ui.js";
 import {
   CONTRIBUTOR_COMMANDS,
   WORKFLOW_COMMANDS,
+  WORKFLOW_BOOTSTRAP_MESSAGE_TYPE,
+  FREEFLOW_STATUS_TOOL_NAME,
+  freeflowModelSkillPaths,
+  freeflowSkillPath,
   getRuntimeContext,
-  handleWorkflowCommand,
-  hasDiscoverActivation,
-  hasFreeflowActivation,
-  hasFreeflowPriorityActivation,
-  hasOutputRouterActivation,
-  consumeRuntimeContextInjectionState,
+  OUTPUT_ROUTER_TOOL_NAMES,
+  readCapabilityState,
   readModeState,
   readOutputRouterConfig,
   refreshRuntimeContext,
-  resetRuntimeContextInjection,
   restoreModeOverride,
   runtimeContext,
+  workflowBootstrapMessage,
   setModeStatus,
   skillPrompt,
   notifyRouterConfigWarnings,
-} from "./runtime-context.js";
+} from "./runtime/runtime-context.js";
+
+function isOutputRouterToolName(name: string): boolean {
+  return OUTPUT_ROUTER_TOOL_NAMES.includes(name);
+}
+
+async function applyCapabilityToolVisibility(pi: any, ctx: any, capabilityState = undefined): Promise<void> {
+  if (typeof pi?.setActiveTools !== "function" || typeof pi?.getAllTools !== "function") {
+    return;
+  }
+
+  const state = capabilityState ?? (await readCapabilityState(ctx.cwd));
+  const allToolNames = pi
+    .getAllTools()
+    .map((tool: any) => tool?.name)
+    .filter(Boolean);
+  const allToolNameSet = new Set(allToolNames);
+  const currentActive = typeof pi.getActiveTools === "function" ? pi.getActiveTools() : undefined;
+  const active = new Set(
+    (Array.isArray(currentActive) ? currentActive : allToolNames).filter((name: string) => allToolNameSet.has(name)),
+  );
+
+  if (allToolNameSet.has(FREEFLOW_STATUS_TOOL_NAME)) {
+    if (state.configured && state.enabled) active.add(FREEFLOW_STATUS_TOOL_NAME);
+    else active.delete(FREEFLOW_STATUS_TOOL_NAME);
+  }
+
+  for (const toolName of OUTPUT_ROUTER_TOOL_NAMES) {
+    if (!allToolNameSet.has(toolName)) continue;
+    if (state.outputRouter.enabled) active.add(toolName);
+    else active.delete(toolName);
+  }
+
+  pi.setActiveTools([...active]);
+}
+
+async function applyLiveCapabilityState(pi: any, ctx: any): Promise<void> {
+  const [modeState, capabilityState] = await Promise.all([readModeState(ctx.cwd), readCapabilityState(ctx.cwd)]);
+  await refreshRuntimeContext(capabilityState);
+  setModeStatus(ctx, modeState, capabilityState);
+  await applyCapabilityToolVisibility(pi, ctx, capabilityState);
+}
+
+function disabledToolCall(toolName: string, capability: string) {
+  const command = capability === "freeflow" ? "/freeflow settings" : `/${capability} settings`;
+  return {
+    block: true,
+    reason: `${toolName} is disabled by Freeflow config. Configure ${capability} with ${command}.`,
+  };
+}
+
+function capabilityCompletions(prefix: string | undefined) {
+  const query = prefix ?? "";
+  return [
+    { value: "settings", label: "settings", description: "Open repository Output Router settings" },
+    { value: "status", label: "status", description: "Show effective Output Router state" },
+    { value: "enable", label: "enable", description: "Enable Output Router for this repository" },
+    { value: "disable", label: "disable", description: "Disable Output Router for this repository" },
+  ].filter((item) => item.value.startsWith(query));
+}
+
+function freeflowCompletions(prefix: string | undefined) {
+  const query = prefix ?? "";
+  if (query.startsWith("settings ")) {
+    const settingsQuery = query.slice("settings ".length);
+    return [
+      { value: "session", label: "session", description: "Override Freeflow for this Pi session" },
+      { value: "local", label: "local", description: "Edit personal overrides for this repository" },
+      { value: "repo", label: "repo", description: "Edit shared repository settings" },
+    ]
+      .filter((item) => item.value.startsWith(settingsQuery))
+      .map((item) => ({ ...item, value: `settings ${item.value}` }));
+  }
+  if (query.startsWith("mode ")) {
+    const modeQuery = query.slice("mode ".length);
+    return [
+      { value: "conversation", label: "conversation", description: "Read-only discussion and inspection" },
+      { value: "workflow", label: "workflow", description: "Adaptive workflow for consequential work" },
+      { value: "strict-workflow", label: "strict-workflow", description: "Stronger pressure at high-risk boundaries" },
+      {
+        value: "reset",
+        label: "reset",
+        description: "Clear the session override and use the configured default",
+      },
+    ]
+      .filter((item) => item.value.startsWith(modeQuery))
+      .map((item) => ({ ...item, value: `mode ${item.value}` }));
+  }
+  return [
+    { value: "settings", label: "settings", description: "Open personal override settings" },
+    { value: "status", label: "status", description: "Show effective Freeflow state" },
+    { value: "mode", label: "mode", description: "Select a temporary session mode" },
+    { value: "enable", label: "enable", description: "Enable Freeflow for this repository" },
+    { value: "disable", label: "disable", description: "Disable Freeflow for this repository" },
+  ].filter((item) => item.value.startsWith(query));
+}
+
+function bypassCompletions(prefix: string | undefined) {
+  const query = prefix ?? "";
+  return [
+    { value: "next", label: "next", description: "Skip one optional step" },
+    { value: "task", label: "task", description: "Reduce optional pressure for the current task" },
+  ].filter((item) => item.value.startsWith(query));
+}
+
+async function sendSkillCommand(pi: any, ctx: any, skill: string, args: string | undefined) {
+  const state = await readCapabilityState(ctx.cwd);
+  if (skill === "setup-freeflow" && !state.configured) {
+    await pi.sendUserMessage(skillPrompt(skill, args));
+    return;
+  }
+  if (!state.configured) {
+    ctx.ui.notify("Freeflow is installed but this repo is not set up. Run /setup-freeflow first.", "warning");
+    return;
+  }
+  if (!state.enabled) {
+    ctx.ui.notify(
+      "Freeflow is disabled for this repo. Use /freeflow enable or /freeflow settings to re-enable it.",
+      "warning",
+    );
+    return;
+  }
+  if (!state.skills.effective) {
+    ctx.ui.notify("Freeflow skills are disabled. Use /freeflow settings to enable skills.", "warning");
+    return;
+  }
+  await pi.sendUserMessage(skillPrompt(skill, args));
+}
 
 export default function freeflow(pi) {
-  resetRuntimeContextInjection();
   registerRouterTools(pi);
 
+  pi.on("resources_discover", async (event, ctx) => {
+    const cwd = ctx?.cwd ?? event?.cwd ?? process.cwd();
+    const state = await readCapabilityState(cwd);
+    if (!state.configured) {
+      return { skillPaths: [freeflowSkillPath("setup-freeflow")] };
+    }
+    if (!state.enabled || !state.skills.effective) {
+      return { skillPaths: [] };
+    }
+    return { skillPaths: freeflowModelSkillPaths() };
+  });
+
   pi.on("session_start", async (_event, ctx) => {
-    resetRuntimeContextInjection();
     restoreModeOverride(ctx);
-    const [modeState, routerConfigResult] = await Promise.all([
+    const [modeState, routerConfigResult, capabilityState] = await Promise.all([
       readModeState(ctx.cwd),
       readOutputRouterConfig(ctx.cwd),
-      refreshRuntimeContext(),
+      readCapabilityState(ctx.cwd),
     ]);
-    setModeStatus(ctx, modeState);
+    await refreshRuntimeContext(capabilityState);
+    setModeStatus(ctx, modeState, capabilityState);
     notifyRouterConfigWarnings(ctx, routerConfigResult);
+    await applyCapabilityToolVisibility(pi, ctx, capabilityState);
+  });
+
+  pi.on("session_tree", async (_event, ctx) => {
+    restoreModeOverride(ctx);
+    await applyLiveCapabilityState(pi, ctx);
   });
 
   pi.on("session_compact", async (_event, ctx) => {
-    resetRuntimeContextInjection();
-    const [modeState, routerConfigResult] = await Promise.all([
+    const [modeState, routerConfigResult, capabilityState] = await Promise.all([
       readModeState(ctx.cwd),
       readOutputRouterConfig(ctx.cwd),
-      refreshRuntimeContext(),
+      readCapabilityState(ctx.cwd),
     ]);
-    setModeStatus(ctx, modeState);
+    await refreshRuntimeContext(capabilityState);
+    setModeStatus(ctx, modeState, capabilityState);
     notifyRouterConfigWarnings(ctx, routerConfigResult);
+    await applyCapabilityToolVisibility(pi, ctx, capabilityState);
   });
 
   pi.on("before_agent_start", async (event, ctx) => {
-    const [modeState, freeflowContext, routerConfigResult] = await Promise.all([
+    const [modeState, routerConfigResult, capabilityState] = await Promise.all([
       readModeState(ctx.cwd),
-      getRuntimeContext(),
       readOutputRouterConfig(ctx.cwd),
+      readCapabilityState(ctx.cwd),
     ]);
-    setModeStatus(ctx, modeState);
+    const freeflowContext = await getRuntimeContext(capabilityState);
+    setModeStatus(ctx, modeState, capabilityState);
     notifyRouterConfigWarnings(ctx, routerConfigResult);
-    // Full skill markdown is expensive. Inject it once per session/compaction boundary,
-    // then keep later turns to a short mode/priority refresh.
-    const injectFullRuntimeContext = consumeRuntimeContextInjectionState();
-    const hasFullRuntimeContext = !injectFullRuntimeContext || hasFreeflowActivation(event.systemPrompt);
-    const routerAlreadyActivated = !injectFullRuntimeContext || hasOutputRouterActivation(event.systemPrompt);
-    const discoverAlreadyActivated = !injectFullRuntimeContext || hasDiscoverActivation(event.systemPrompt);
-    const priorityAlreadyActivated = hasFreeflowPriorityActivation(event.systemPrompt);
-    return {
-      systemPrompt:
-        event.systemPrompt +
-        "\n\n" +
-        runtimeContext(
-          modeState,
-          freeflowContext,
-          routerConfigResult,
-          hasFullRuntimeContext,
-          routerAlreadyActivated,
-          discoverAlreadyActivated,
-          priorityAlreadyActivated
-        ),
-    };
+    await applyCapabilityToolVisibility(pi, ctx, capabilityState);
+    const freeflowRuntimeContext = runtimeContext(modeState, freeflowContext, routerConfigResult, capabilityState);
+    const workflowMessage = workflowBootstrapMessage(freeflowContext, capabilityState, ctx.sessionManager);
+    const systemPrompt = freeflowRuntimeContext
+      ? `${event.systemPrompt}\n\n${freeflowRuntimeContext}`
+      : event.systemPrompt;
+    return { message: workflowMessage, systemPrompt };
+  });
+
+  pi.on("context", async (event, ctx) => {
+    const capabilityState = await readCapabilityState(ctx.cwd);
+    if (capabilityState.skills.effective) {
+      return undefined;
+    }
+
+    const messages = event.messages.filter(
+      (message) => !(message?.role === "custom" && message?.customType === WORKFLOW_BOOTSTRAP_MESSAGE_TYPE),
+    );
+    return messages.length === event.messages.length ? undefined : { messages };
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    const capabilityState = await readCapabilityState(ctx.cwd);
+    const toolName = typeof event?.toolName === "string" ? event.toolName : "";
+    if ((!capabilityState.configured || !capabilityState.enabled) && toolName === FREEFLOW_STATUS_TOOL_NAME) {
+      return disabledToolCall(toolName, "freeflow");
+    }
+    if (!capabilityState.outputRouter.enabled && isOutputRouterToolName(toolName)) {
+      return disabledToolCall(toolName, "output-router");
+    }
+    return undefined;
   });
 
   pi.on("tool_result", async (event, ctx) => {
+    const capabilityState = await readCapabilityState(ctx.cwd);
+    if (!capabilityState.outputRouter.enabled) {
+      return undefined;
+    }
     const observed = await handleObservedToolRouting(event, ctx);
     if (observed) {
       return observed;
@@ -91,8 +252,9 @@ export default function freeflow(pi) {
   for (const { command, skill } of WORKFLOW_COMMANDS) {
     pi.registerCommand(command, {
       description: command === skill ? `Run Freeflow ${skill}` : `Run Freeflow ${skill} via ${command}`,
-      handler: async (args) => {
-        await pi.sendUserMessage(skillPrompt(skill, args));
+      ...(command === "bypass" ? { getArgumentCompletions: bypassCompletions } : {}),
+      handler: async (args, ctx) => {
+        await sendSkillCommand(pi, ctx, skill, args);
       },
     });
   }
@@ -100,22 +262,34 @@ export default function freeflow(pi) {
   for (const skill of CONTRIBUTOR_COMMANDS) {
     pi.registerCommand(skill, {
       description: `Run Freeflow ${skill}`,
-      handler: async (args) => {
-        await pi.sendUserMessage(skillPrompt(skill, args));
+      handler: async (args, ctx) => {
+        await sendSkillCommand(pi, ctx, skill, args);
       },
     });
   }
 
-  pi.registerCommand("workflow", {
-    description: "Set or inspect the current Freeflow session mode",
-    getArgumentCompletions: (prefix) => {
-      const query = prefix ?? "";
-      const values = ["conversation", "workflow", "strict-workflow", "reset"];
-      const filtered = values.filter((value) => value.startsWith(query));
-      return filtered.map((value) => ({ value, label: value }));
+  pi.registerCommand("freeflow", {
+    description: "Open unified Freeflow settings or print compact status",
+    getArgumentCompletions: freeflowCompletions,
+    handler: async (args, ctx) => {
+      await handleFreeflowCommand(
+        args,
+        ctx,
+        async () => {
+          await applyLiveCapabilityState(pi, ctx);
+        },
+        pi,
+      );
     },
+  });
+
+  pi.registerCommand("output-router", {
+    description: "Open Freeflow Output Router settings or print compact status",
+    getArgumentCompletions: capabilityCompletions,
     handler: async (args, ctx) => {
-      await handleWorkflowCommand(args, ctx, pi);
+      await handleOutputRouterCommand(args, ctx, async () => {
+        await applyLiveCapabilityState(pi, ctx);
+      });
     },
   });
 }

package/pi-extension/src/{host-producer-identification.ts → output-router/host-producer-identification.ts}

@@ -126,7 +126,13 @@ export function identifyPiMcpProducer(event: any) {
     return undefined;
   }
 
-  if (toolName !== "mcp" && !toolName.startsWith("mcp__") && !detailMcp.server && detailProducer.kind !== "mcp" && inputProducer.kind !== "mcp") {
+  if (
+    toolName !== "mcp" &&
+    !toolName.startsWith("mcp__") &&
+    !detailMcp.server &&
+    detailProducer.kind !== "mcp" &&
+    inputProducer.kind !== "mcp"
+  ) {
     return undefined;
   }
 
@@ -150,18 +156,34 @@ export function classifyObservedProducerRisk(producer: any, event?: any) {
   }
 
   if (producer?.kind === "web" || producer?.kind === "fetch" || producer?.kind === "code_search") {
-    return { classification: "read", source: "manifest", reason: `${producer.kind} is treated as a read-only Pi evidence producer.` };
+    return {
+      classification: "read",
+      source: "manifest",
+      reason: `${producer.kind} is treated as a read-only Pi evidence producer.`,
+    };
   }
 
   const tool = typeof producer?.tool === "string" ? producer.tool : "";
   if (matchesVerb(tool, WRITE_VERBS)) {
-    return { classification: "write", source: "heuristic", reason: `MCP tool name ${tool} matched a write-like verb heuristic.` };
+    return {
+      classification: "write",
+      source: "heuristic",
+      reason: `MCP tool name ${tool} matched a write-like verb heuristic.`,
+    };
   }
   if (matchesVerb(tool, READ_VERBS)) {
-    return { classification: "read", source: "heuristic", reason: `MCP tool name ${tool} matched a read-like verb heuristic.` };
+    return {
+      classification: "read",
+      source: "heuristic",
+      reason: `MCP tool name ${tool} matched a read-like verb heuristic.`,
+    };
   }
 
-  return { classification: "unknown", source: "unknown", reason: "No configured risk, MCP annotation, manifest entry, or deterministic name heuristic matched." };
+  return {
+    classification: "unknown",
+    source: "unknown",
+    reason: "No configured risk, MCP annotation, manifest entry, or deterministic name heuristic matched.",
+  };
 }
 
 function configuredRisk(event: any) {
@@ -185,10 +207,18 @@ function mcpAnnotationRisk(event: any) {
     return undefined;
   }
   if (annotations.destructiveHint === true || annotations.write === true || annotations.mutating === true) {
-    return { classification: "write", source: "mcp_annotation", reason: "MCP annotations indicate a mutating/destructive operation." };
+    return {
+      classification: "write",
+      source: "mcp_annotation",
+      reason: "MCP annotations indicate a mutating/destructive operation.",
+    };
   }
   if (annotations.readOnlyHint === true || annotations.readOnly === true) {
-    return { classification: "read", source: "mcp_annotation", reason: "MCP annotations indicate a read-only operation." };
+    return {
+      classification: "read",
+      source: "mcp_annotation",
+      reason: "MCP annotations indicate a read-only operation.",
+    };
   }
   return undefined;
 }

package/pi-extension/src/{native-safety-net.ts → output-router/native-safety-net.ts}

@@ -6,16 +6,9 @@ import {
   isNativeSafetyNetEnabled,
   storeTextOutput,
   textOutputFingerprints,
-} from "../../router/dist/index.js";
-import { readOutputRouterConfig, notifyRouterConfigWarnings } from "./runtime-context.js";
-import {
-  byteLength,
-  extractTextContent,
-  getRouterSessionId,
-  splitLines,
-  stableHash,
-  truncateText,
-} from "./utils.js";
+} from "../../../router/dist/index.js";
+import { readOutputRouterConfig, notifyRouterConfigWarnings } from "../runtime/runtime-context.js";
+import { byteLength, extractTextContent, getRouterSessionId, splitLines, stableHash, truncateText } from "./utils.js";
 
 const SAFETY_NET_NATIVE_TOOLS = new Set(["read", "bash"]);
 const SAFETY_NET_EXCERPT_LINES = 8;
@@ -187,7 +180,7 @@ function appendSafetyNetWarning(event, message) {
 }
 
 // Keep post-tool native transformations aligned with
-// skills/output-router/references/safety-policy.md.
+// capabilities/output-router/references/safety-policy.md.
 export async function handleNativeToolSafetyNet(event, ctx) {
   const routerConfigResult = await readOutputRouterConfig(ctx.cwd);
   notifyRouterConfigWarnings(ctx, routerConfigResult);
@@ -244,7 +237,10 @@ export async function handleNativeToolSafetyNet(event, ctx) {
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    ctx.ui.notify(`Freeflow safety-net routing failed; passing native ${event.toolName} output through. ${message}`, "warning");
+    ctx.ui.notify(
+      `Freeflow safety-net routing failed; passing native ${event.toolName} output through. ${message}`,
+      "warning",
+    );
     return {
       content: appendSafetyNetWarning(event, message),
     };

package/pi-extension/src/{observed-tool-routing.ts → output-router/observed-tool-routing.ts}

@@ -1,6 +1,6 @@
-import { normalizeFreeflowConfig, routeObservedToolOutput } from "../../router/dist/index.js";
+import { normalizeFreeflowConfig, routeObservedToolOutput } from "../../../router/dist/index.js";
 import { resolvePiObservedRoutingDecision } from "./host-producer-identification.js";
-import { notifyRouterConfigWarnings, readFreeflowConfig } from "./runtime-context.js";
+import { notifyRouterConfigWarnings, readFreeflowConfig } from "../runtime/runtime-context.js";
 import { getRouterSessionId } from "./utils.js";
 
 export async function handleObservedToolRouting(event: any, ctx: any) {
@@ -80,14 +80,20 @@ function observedDetails(event: any, routed: any) {
 
 function formatObservedRoutedResult(routed: any): string {
   const evidence = Array.isArray(routed.evidence) ? routed.evidence : [];
-  const evidenceText = evidence.length > 0
-    ? evidence.slice(0, 3).map((packet, index) => [
-        `Evidence ${index + 1}${packet.lines ? ` lines ${packet.lines}` : ""}:`,
-        "```text",
-        packet.excerpt ?? "",
-        "```",
-      ].join("\n")).join("\n")
-    : "No evidence packets returned.";
+  const evidenceText =
+    evidence.length > 0
+      ? evidence
+          .slice(0, 3)
+          .map((packet, index) =>
+            [
+              `Evidence ${index + 1}${packet.lines ? ` lines ${packet.lines}` : ""}:`,
+              "```text",
+              packet.excerpt ?? "",
+              "```",
+            ].join("\n"),
+          )
+          .join("\n")
+      : "No evidence packets returned.";
   const producer = producerLabel(routed.producer);
   const output = routed.outputId ? ` outputId=${routed.outputId}` : "";
   const recovery = routed.recovery?.how ? `\nRecovery: ${routed.recovery.how}` : "";
@@ -102,7 +108,9 @@ function formatObservedRoutedResult(routed: any): string {
     routed.summary ? `Summary: ${routed.summary}` : "",
     recovery,
     evidenceText,
-  ].filter(Boolean).join("\n");
+  ]
+    .filter(Boolean)
+    .join("\n");
 }
 
 function formatObservedFailOpen(routed: any): string {