@hassangameryt/freeflow 0.1.0 → 0.3.0

package/pi-extension/src/index.ts

@@ -0,0 +1,121 @@
+import { handleNativeToolSafetyNet } from "./native-safety-net.js";
+import { handleObservedToolRouting } from "./observed-tool-routing.js";
+import { registerRouterTools } from "./router-tools.js";
+import {
+  CONTRIBUTOR_COMMANDS,
+  WORKFLOW_COMMANDS,
+  getRuntimeContext,
+  handleWorkflowCommand,
+  hasDiscoverActivation,
+  hasFreeflowActivation,
+  hasFreeflowPriorityActivation,
+  hasOutputRouterActivation,
+  consumeRuntimeContextInjectionState,
+  readModeState,
+  readOutputRouterConfig,
+  refreshRuntimeContext,
+  resetRuntimeContextInjection,
+  restoreModeOverride,
+  runtimeContext,
+  setModeStatus,
+  skillPrompt,
+  notifyRouterConfigWarnings,
+} from "./runtime-context.js";
+
+export default function freeflow(pi) {
+  resetRuntimeContextInjection();
+  registerRouterTools(pi);
+
+  pi.on("session_start", async (_event, ctx) => {
+    resetRuntimeContextInjection();
+    restoreModeOverride(ctx);
+    const [modeState, routerConfigResult] = await Promise.all([
+      readModeState(ctx.cwd),
+      readOutputRouterConfig(ctx.cwd),
+      refreshRuntimeContext(),
+    ]);
+    setModeStatus(ctx, modeState);
+    notifyRouterConfigWarnings(ctx, routerConfigResult);
+  });
+
+  pi.on("session_compact", async (_event, ctx) => {
+    resetRuntimeContextInjection();
+    const [modeState, routerConfigResult] = await Promise.all([
+      readModeState(ctx.cwd),
+      readOutputRouterConfig(ctx.cwd),
+      refreshRuntimeContext(),
+    ]);
+    setModeStatus(ctx, modeState);
+    notifyRouterConfigWarnings(ctx, routerConfigResult);
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    const [modeState, freeflowContext, routerConfigResult] = await Promise.all([
+      readModeState(ctx.cwd),
+      getRuntimeContext(),
+      readOutputRouterConfig(ctx.cwd),
+    ]);
+    setModeStatus(ctx, modeState);
+    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
+        ),
+    };
+  });
+
+  pi.on("tool_result", async (event, ctx) => {
+    const observed = await handleObservedToolRouting(event, ctx);
+    if (observed) {
+      return observed;
+    }
+    return handleNativeToolSafetyNet(event, ctx);
+  });
+
+  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));
+      },
+    });
+  }
+
+  for (const skill of CONTRIBUTOR_COMMANDS) {
+    pi.registerCommand(skill, {
+      description: `Run Freeflow ${skill}`,
+      handler: async (args) => {
+        await pi.sendUserMessage(skillPrompt(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 }));
+    },
+    handler: async (args, ctx) => {
+      await handleWorkflowCommand(args, ctx, pi);
+    },
+  });
+}

package/pi-extension/src/mcp-config.ts

@@ -0,0 +1,32 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+function getMcpConfigPaths(cwd) {
+  return [
+    join(homedir(), ".config", "mcp", "mcp.json"),
+    join(homedir(), ".pi", "agent", "mcp.json"),
+    resolve(cwd, ".mcp.json"),
+    resolve(cwd, ".pi", "mcp.json"),
+  ];
+}
+
+export async function isMcpServerConfigured(serverName, cwd) {
+  return Boolean(await loadMcpServerConfig(serverName, cwd));
+}
+
+export async function loadMcpServerConfig(serverName, cwd) {
+  let found = null;
+  for (const configPath of getMcpConfigPaths(cwd)) {
+    try {
+      const raw = JSON.parse(await readFile(configPath, "utf8"));
+      const servers = raw?.mcpServers ?? raw?.["mcp-servers"] ?? {};
+      if (servers && typeof servers === "object" && !Array.isArray(servers) && servers[serverName]) {
+        found = servers[serverName];
+      }
+    } catch {
+      // Missing or invalid MCP configs are ignored here; pi-mcp-adapter owns user-facing setup diagnostics.
+    }
+  }
+  return found;
+}

package/pi-extension/src/native-safety-net.ts

@@ -0,0 +1,252 @@
+import { readFile } from "node:fs/promises";
+
+import {
+  createVault,
+  findExactDuplicateTextOutput,
+  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";
+
+const SAFETY_NET_NATIVE_TOOLS = new Set(["read", "bash"]);
+const SAFETY_NET_EXCERPT_LINES = 8;
+const SAFETY_NET_HEURISTIC_MIN_BYTES = 16_384;
+const SAFETY_NET_HEURISTIC_MIN_LINES = 200;
+
+async function nativeResultText(event) {
+  const fullOutputPath = event.toolName === "bash" ? event.details?.fullOutputPath : undefined;
+  if (typeof fullOutputPath === "string" && fullOutputPath.length > 0) {
+    try {
+      return await readFile(fullOutputPath, "utf8");
+    } catch {
+      // Fall back to the exact text that would otherwise enter model context.
+    }
+  }
+
+  return extractTextContent(event.content);
+}
+
+function nativeOutputStats(text, truncation) {
+  const measuredLines = splitLines(text).length;
+  const measuredBytes = byteLength(text);
+  return {
+    lines: Number.isInteger(truncation?.totalLines) ? truncation.totalLines : measuredLines,
+    bytes: Number.isInteger(truncation?.totalBytes) ? truncation.totalBytes : measuredBytes,
+    capturedLines: measuredLines,
+    capturedBytes: measuredBytes,
+  };
+}
+
+function isSafetyNetEnabled(routerConfig) {
+  return routerConfig.enabled !== false && isNativeSafetyNetEnabled(routerConfig.postToolRouting);
+}
+
+function shouldRouteNativeToolResult(event, routerConfig, text) {
+  if (!SAFETY_NET_NATIVE_TOOLS.has(event.toolName) || !isSafetyNetEnabled(routerConfig)) {
+    return { route: false };
+  }
+
+  const stats = nativeOutputStats(text, event.details?.truncation);
+  if (stats.bytes > routerConfig.thresholds.largeOutputBytes) {
+    return {
+      route: true,
+      stats,
+      reason: `native ${event.toolName} output exceeded largeOutputBytes (${stats.bytes} > ${routerConfig.thresholds.largeOutputBytes})`,
+    };
+  }
+
+  if (stats.lines > routerConfig.thresholds.largeOutputLines) {
+    return {
+      route: true,
+      stats,
+      reason: `native ${event.toolName} output exceeded largeOutputLines (${stats.lines} > ${routerConfig.thresholds.largeOutputLines})`,
+    };
+  }
+
+  if (matchesConfiguredNoiseHint(event, routerConfig) && exceedsHeuristicMinimum(stats, routerConfig)) {
+    return {
+      route: true,
+      stats,
+      reason: `native ${event.toolName} output matched configured noisy/generated-output hints and exceeded the conservative heuristic floor`,
+    };
+  }
+
+  return { route: false };
+}
+
+function exceedsHeuristicMinimum(stats, routerConfig) {
+  const byteFloor = Math.min(routerConfig.thresholds.largeOutputBytes, SAFETY_NET_HEURISTIC_MIN_BYTES);
+  const lineFloor = Math.min(routerConfig.thresholds.largeOutputLines, SAFETY_NET_HEURISTIC_MIN_LINES);
+  return stats.bytes > byteFloor || stats.lines > lineFloor;
+}
+
+function matchesConfiguredNoiseHint(event, routerConfig) {
+  if (event.toolName === "bash") {
+    const command = typeof event.input?.command === "string" ? event.input.command : "";
+    return matchesAnyHint(command, routerConfig.hints?.noisyCommandPatterns);
+  }
+
+  if (event.toolName === "read") {
+    const path = typeof event.input?.path === "string" ? event.input.path : "";
+    return matchesAnyPathHint(path, routerConfig.hints?.generatedPathGlobs);
+  }
+
+  return false;
+}
+
+function matchesAnyHint(value, hints) {
+  if (!value || !Array.isArray(hints)) {
+    return false;
+  }
+  return hints.some((hint) => typeof hint === "string" && hint.length > 0 && value.includes(hint));
+}
+
+function matchesAnyPathHint(path, hints) {
+  if (!path || !Array.isArray(hints)) {
+    return false;
+  }
+  return hints.some((hint) => matchesSimpleGlob(path, hint));
+}
+
+function matchesSimpleGlob(path, pattern) {
+  if (typeof pattern !== "string" || pattern.length === 0) {
+    return false;
+  }
+
+  if (pattern.endsWith("/**")) {
+    const prefix = pattern.slice(0, -3);
+    return path === prefix || path.startsWith(`${prefix}/`);
+  }
+
+  if (!pattern.includes("*")) {
+    return path === pattern || path.includes(pattern);
+  }
+
+  const escaped = pattern
+    .split("*")
+    .map((part) => part.replace(/[|\\{}()[\]^$+?.]/g, "\\$&"))
+    .join(".*");
+  return new RegExp(`^${escaped}$`).test(path);
+}
+
+function nativeSafetyDecisionId(event, text) {
+  return `ffdec_native_${stableHash(`${event.toolName}:${event.toolCallId}:${text}`).slice(0, 24)}`;
+}
+
+function formatNativeSafetyNetResult({ event, record, duplicate, stats, reason, mode, text }) {
+  const lines = splitLines(text);
+  const shownLines = lines.slice(0, SAFETY_NET_EXCERPT_LINES);
+  const shownEnd = shownLines.length;
+  const omittedLines = Math.max(0, stats.capturedLines - shownLines.length);
+  const inputLabel = nativeInputLabel(event);
+  const duplicateLine = duplicate
+    ? `Duplicate: exact native output matches previous outputId=${duplicate.outputId}; current raw output was vaulted as outputId=${record.outputId}.`
+    : null;
+
+  return [
+    `Freeflow routed this native ${event.toolName} result (post-tool safety net).`,
+    `Reason: ${reason}; outputRouter.postToolRouting=${mode}.`,
+    `Captured exact native text in the Freeflow vault: outputId=${record.outputId}, stream=raw, lines=${stats.capturedLines}, bytes=${stats.capturedBytes}.`,
+    ...(duplicateLine ? [duplicateLine] : []),
+    `Original native result stats: lines=${stats.lines}, bytes=${stats.bytes}.${inputLabel ? ` Input: ${inputLabel}.` : ""}`,
+    `Recovery: use freeflow_search with action=retrieve, source.kind=vault, outputId=${record.outputId}, stream=raw, and a lineRange to recover exact content.`,
+    `Showing exact captured lines 1-${shownEnd}${omittedLines > 0 ? ` (${omittedLines} captured lines omitted from context)` : ""}:`,
+    "```text",
+    shownLines.join("\n"),
+    "```",
+  ].join("\n");
+}
+
+function nativeInputLabel(event) {
+  if (event.toolName === "bash" && typeof event.input?.command === "string") {
+    return `command=${JSON.stringify(event.input.command)}`;
+  }
+  if (event.toolName === "read" && typeof event.input?.path === "string") {
+    return `path=${JSON.stringify(event.input.path)}`;
+  }
+  return "";
+}
+
+function appendSafetyNetWarning(event, message) {
+  return [
+    ...event.content,
+    {
+      type: "text",
+      text: `Freeflow safety-net warning: ${message} Native output was not shortened or removed.`,
+    },
+  ];
+}
+
+// Keep post-tool native transformations aligned with
+// skills/output-router/references/safety-policy.md.
+export async function handleNativeToolSafetyNet(event, ctx) {
+  const routerConfigResult = await readOutputRouterConfig(ctx.cwd);
+  notifyRouterConfigWarnings(ctx, routerConfigResult);
+  const routerConfig = routerConfigResult.config;
+
+  if (!SAFETY_NET_NATIVE_TOOLS.has(event.toolName) || !isSafetyNetEnabled(routerConfig)) {
+    return undefined;
+  }
+
+  const text = await nativeResultText(event);
+  if (text === null) {
+    return undefined;
+  }
+
+  const routeDecision = shouldRouteNativeToolResult(event, routerConfig, text);
+  if (!routeDecision.route) {
+    return undefined;
+  }
+
+  try {
+    const vault = createVault({ root: routerConfig.vault.root, retention: routerConfig.vault.retention });
+    const sessionId = getRouterSessionId(ctx);
+    const fingerprints = textOutputFingerprints({ raw: text });
+    const duplicate = await findExactDuplicateTextOutput(vault, { sessionId, fingerprints });
+    const decisionId = nativeSafetyDecisionId(event, text);
+    const record = await storeTextOutput(vault, {
+      sessionId,
+      raw: text,
+      sourceKind: "native",
+      decisionIds: [decisionId],
+    });
+    const routedText = formatNativeSafetyNetResult({
+      event,
+      record,
+      duplicate,
+      stats: routeDecision.stats,
+      reason: routeDecision.reason,
+      mode: routerConfig.postToolRouting,
+      text,
+    });
+
+    return {
+      content: [{ type: "text", text: routedText }],
+      details: {
+        ...(event.details && typeof event.details === "object" ? event.details : {}),
+        freeflowOutputRouter: {
+          route: "safety-net",
+          outputId: record.outputId,
+          decisionId,
+          reason: routeDecision.reason,
+          ...(duplicate ? { duplicateOfOutputId: duplicate.outputId } : {}),
+        },
+      },
+    };
+  } 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");
+    return {
+      content: appendSafetyNetWarning(event, message),
+    };
+  }
+}

package/pi-extension/src/observed-tool-routing.ts

@@ -0,0 +1,126 @@
+import { normalizeFreeflowConfig, routeObservedToolOutput } from "../../router/dist/index.js";
+import { resolvePiObservedRoutingDecision } from "./host-producer-identification.js";
+import { notifyRouterConfigWarnings, readFreeflowConfig } from "./runtime-context.js";
+import { getRouterSessionId } from "./utils.js";
+
+export async function handleObservedToolRouting(event: any, ctx: any) {
+  const parsedConfig = await readFreeflowConfig(ctx.cwd);
+  const normalized = normalizeFreeflowConfig(parsedConfig);
+  notifyRouterConfigWarnings(ctx, { warnings: normalized.warnings });
+
+  if (normalized.config.outputRouter.enabled === false) {
+    return undefined;
+  }
+
+  const decision = resolvePiObservedRoutingDecision(event, normalized.config.observedRouting);
+  if (!decision.route) {
+    return undefined;
+  }
+
+  const rawResult = rawObservedResult(event);
+  const routed = await routeObservedToolOutput({
+    sessionId: getRouterSessionId(ctx),
+    host: decision.host,
+    producer: decision.producer as any,
+    rawResult,
+    persistence: decision.persistence,
+    risk: decision.risk as any,
+    preserve: "important",
+    vaultRoot: normalized.config.outputRouter.vault.root,
+    vaultRetention: normalized.config.outputRouter.vault.retention,
+    thresholds: normalized.config.outputRouter.thresholds,
+  });
+
+  if (routed.passthrough) {
+    return {
+      content: [{ type: "text", text: formatObservedFailOpen(routed) }],
+      details: observedDetails(event, routed),
+    };
+  }
+
+  return {
+    content: [{ type: "text", text: formatObservedRoutedResult(routed) }],
+    details: observedDetails(event, routed),
+  };
+}
+
+function rawObservedResult(event: any): unknown {
+  if (event?.details?.result !== undefined) {
+    return event.details.result;
+  }
+  if (event?.details?.rawResult !== undefined) {
+    return event.details.rawResult;
+  }
+  if (Array.isArray(event?.content)) {
+    return { content: event.content };
+  }
+  if (event?.content !== undefined) {
+    return event.content;
+  }
+  return "";
+}
+
+function observedDetails(event: any, routed: any) {
+  return {
+    ...(event.details && typeof event.details === "object" ? event.details : {}),
+    freeflowObservedRouting: {
+      route: "observed",
+      decisionId: routed.decisionId,
+      routingStatus: routed.routing?.status,
+      outputId: routed.outputId,
+      recordId: routed.recordId,
+      persistence: routed.persistence,
+      producer: routed.producer,
+      risk: routed.risk,
+      recovery: routed.recovery,
+      failure: routed.failure,
+    },
+  };
+}
+
+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 producer = producerLabel(routed.producer);
+  const output = routed.outputId ? ` outputId=${routed.outputId}` : "";
+  const recovery = routed.recovery?.how ? `\nRecovery: ${routed.recovery.how}` : "";
+  const persistence = routed.persistence
+    ? `persistence=${routed.persistence.status}; recoverability=${routed.persistence.recoverability}`
+    : "persistence=unknown";
+
+  return [
+    `Freeflow routed this observed ${routed.host?.toolName ?? "tool"} result.`,
+    `Producer: ${producer}; ${persistence}; routing.status=${routed.routing?.status}.${output}`,
+    `Reason: ${routed.routing?.reason ?? "Observed output routed."}`,
+    routed.summary ? `Summary: ${routed.summary}` : "",
+    recovery,
+    evidenceText,
+  ].filter(Boolean).join("\n");
+}
+
+function formatObservedFailOpen(routed: any): string {
+  const original = routed.passthrough?.text ?? "";
+  return [
+    `Freeflow observed-routing warning: ${routed.failure?.message ?? "routing failed"}`,
+    "Observed routing failed open; original host output was not shortened or removed.",
+    routed.recovery?.how ? `Recovery: ${routed.recovery.how}` : "Recovery: unavailable.",
+    "Original output:",
+    "```text",
+    original,
+    "```",
+  ].join("\n");
+}
+
+function producerLabel(producer: any): string {
+  if (!producer) {
+    return "unknown";
+  }
+  return [producer.kind, producer.server, producer.tool, producer.name].filter(Boolean).join(":");
+}