@hassangameryt/freeflow 0.5.0 → 0.6.0

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

@@ -1,256 +0,0 @@
-const BUILT_IN_PI_PRODUCERS = {
-  web_search: {
-    configKey: "web",
-    producer: { kind: "web", tool: "web_search" },
-    risk: { classification: "read", source: "manifest", reason: "Pi web_search is a read-only evidence producer." },
-  },
-  fetch_content: {
-    configKey: "fetch",
-    producer: { kind: "fetch", tool: "fetch_content" },
-    risk: { classification: "read", source: "manifest", reason: "Pi fetch_content is a read-only evidence producer." },
-  },
-  code_search: {
-    configKey: "codeSearch",
-    producer: { kind: "code_search", tool: "code_search" },
-    risk: { classification: "read", source: "manifest", reason: "Pi code_search is a read-only evidence producer." },
-  },
-} as const;
-
-const READ_VERBS = [
-  "get",
-  "list",
-  "search",
-  "fetch",
-  "read",
-  "query",
-  "find",
-  "describe",
-  "diagnostic",
-  "diagnostics",
-  "overview",
-  "lookup",
-  "show",
-];
-
-const WRITE_VERBS = [
-  "create",
-  "update",
-  "delete",
-  "remove",
-  "patch",
-  "post",
-  "put",
-  "deploy",
-  "restart",
-  "rename",
-  "mutate",
-  "set",
-  "write",
-  "send",
-  "transition",
-  "close",
-  "merge",
-  "rerun",
-  "cancel",
-];
-
-export function resolvePiObservedRoutingDecision(event: any, observedRoutingConfig: any) {
-  const host = { name: "pi", toolName: typeof event?.toolName === "string" ? event.toolName : "unknown" };
-
-  if (!observedRoutingConfig || observedRoutingConfig.enabled !== true) {
-    return { route: false, reason: "observedRouting.enabled is not true." };
-  }
-
-  const mcpProducer = identifyPiMcpProducer(event);
-  if (mcpProducer) {
-    const serverConfig = observedRoutingConfig.mcp?.servers?.[mcpProducer.server];
-    if (!serverConfig?.enabled) {
-      return { route: false, reason: `MCP server ${mcpProducer.server} is not enabled for observed routing.` };
-    }
-    return {
-      route: true,
-      host,
-      producer: mcpProducer,
-      persistence: serverConfig.persistence,
-      risk: classifyObservedProducerRisk(mcpProducer, event),
-    };
-  }
-
-  const builtIn = identifyBuiltInPiProducer(event);
-  if (builtIn) {
-    const producerConfig = observedRoutingConfig[builtIn.configKey];
-    if (!producerConfig?.enabled) {
-      return { route: false, reason: `Pi ${host.toolName} observed routing is not enabled.` };
-    }
-    return {
-      route: true,
-      host,
-      producer: { ...builtIn.producer },
-      persistence: producerConfig.persistence,
-      risk: { ...builtIn.risk },
-    };
-  }
-
-  return { route: false, reason: `Pi tool ${host.toolName} is not an observed-routing producer.` };
-}
-
-export function identifyPiMcpProducer(event: any) {
-  const toolName = typeof event?.toolName === "string" ? event.toolName : "";
-  const input = isRecord(event?.input) ? event.input : {};
-  const details = isRecord(event?.details) ? event.details : {};
-  const detailMcp = isRecord(details.mcp) ? details.mcp : {};
-  const inputProducer = isRecord(input.producer) ? input.producer : {};
-  const detailProducer = isRecord(details.producer) ? details.producer : {};
-  const split = splitMcpToolName(toolName);
-
-  const server = firstString(
-    input.server,
-    input.mcpServer,
-    inputProducer.server,
-    details.server,
-    detailMcp.server,
-    detailProducer.server,
-    split?.server,
-  );
-  const tool = firstString(
-    input.tool,
-    input.name,
-    inputProducer.tool,
-    details.tool,
-    detailMcp.tool,
-    detailProducer.tool,
-    split?.tool,
-  );
-
-  if (!server || !tool) {
-    return undefined;
-  }
-
-  if (
-    toolName !== "mcp" &&
-    !toolName.startsWith("mcp__") &&
-    !detailMcp.server &&
-    detailProducer.kind !== "mcp" &&
-    inputProducer.kind !== "mcp"
-  ) {
-    return undefined;
-  }
-
-  return { kind: "mcp", server, tool };
-}
-
-export function identifyBuiltInPiProducer(event: any) {
-  const toolName = typeof event?.toolName === "string" ? event.toolName : "";
-  return BUILT_IN_PI_PRODUCERS[toolName as keyof typeof BUILT_IN_PI_PRODUCERS];
-}
-
-export function classifyObservedProducerRisk(producer: any, event?: any) {
-  const configured = configuredRisk(event);
-  if (configured) {
-    return configured;
-  }
-
-  const annotation = mcpAnnotationRisk(event);
-  if (annotation) {
-    return annotation;
-  }
-
-  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.`,
-    };
-  }
-
-  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.`,
-    };
-  }
-  if (matchesVerb(tool, READ_VERBS)) {
-    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.",
-  };
-}
-
-function configuredRisk(event: any) {
-  const candidate = event?.details?.freeflow?.risk ?? event?.details?.observedRouting?.risk;
-  if (!isRecord(candidate)) {
-    return undefined;
-  }
-  if (!["read", "write", "unknown"].includes(String(candidate.classification))) {
-    return undefined;
-  }
-  return {
-    classification: candidate.classification,
-    source: "configured",
-    reason: typeof candidate.reason === "string" ? candidate.reason : "Configured observed producer risk override.",
-  };
-}
-
-function mcpAnnotationRisk(event: any) {
-  const annotations = event?.details?.mcp?.annotations ?? event?.details?.annotations;
-  if (!isRecord(annotations)) {
-    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.",
-    };
-  }
-  if (annotations.readOnlyHint === true || annotations.readOnly === true) {
-    return {
-      classification: "read",
-      source: "mcp_annotation",
-      reason: "MCP annotations indicate a read-only operation.",
-    };
-  }
-  return undefined;
-}
-
-function splitMcpToolName(toolName: string): { server: string; tool: string } | undefined {
-  if (!toolName.startsWith("mcp__")) {
-    return undefined;
-  }
-  const parts = toolName.split("__");
-  if (parts.length < 3) {
-    return undefined;
-  }
-  return { server: parts[1], tool: parts.slice(2).join("__") };
-}
-
-function matchesVerb(toolName: string, verbs: readonly string[]): boolean {
-  const normalized = toolName.toLowerCase();
-  return verbs.some((verb) => {
-    const escaped = verb.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
-    return new RegExp(`(^|[_-])${escaped}([_-]|$)`).test(normalized);
-  });
-}
-
-function firstString(...values: unknown[]): string | undefined {
-  for (const value of values) {
-    if (typeof value === "string" && value.trim().length > 0) {
-      return value.trim();
-    }
-  }
-  return undefined;
-}
-
-function isRecord(value: unknown): value is Record<string, any> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

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

@@ -1,248 +0,0 @@
-import { readFile } from "node:fs/promises";
-
-import {
-  createVault,
-  findExactDuplicateTextOutput,
-  isNativeSafetyNetEnabled,
-  storeTextOutput,
-  textOutputFingerprints,
-} 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;
-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
-// capabilities/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/output-router/observed-tool-routing.ts

@@ -1,134 +0,0 @@
-import { normalizeFreeflowConfig, routeObservedToolOutput } from "../../../router/dist/index.js";
-import { resolvePiObservedRoutingDecision } from "./host-producer-identification.js";
-import { notifyRouterConfigWarnings, readFreeflowConfig } from "../runtime/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(":");
-}