@hassangameryt/freeflow 0.3.0 → 0.5.0

package/pi-extension/dist/host-producer-identification.js

@@ -1,186 +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." },
-    },
-};
-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, observedRoutingConfig) {
-    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) {
-    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) {
-    const toolName = typeof event?.toolName === "string" ? event.toolName : "";
-    return BUILT_IN_PI_PRODUCERS[toolName];
-}
-export function classifyObservedProducerRisk(producer, event) {
-    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) {
-    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) {
-    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) {
-    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, verbs) {
-    const normalized = toolName.toLowerCase();
-    return verbs.some((verb) => {
-        const escaped = verb.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
-        return new RegExp(`(^|[_-])${escaped}([_-]|$)`).test(normalized);
-    });
-}
-function firstString(...values) {
-    for (const value of values) {
-        if (typeof value === "string" && value.trim().length > 0) {
-            return value.trim();
-        }
-    }
-    return undefined;
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/pi-extension/dist/mcp-config.js

@@ -1,30 +0,0 @@
-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/dist/native-safety-net.js

@@ -1,209 +0,0 @@
-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, } 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/dist/observed-tool-routing.js

@@ -1,114 +0,0 @@
-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, ctx) {
-    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,
-        rawResult,
-        persistence: decision.persistence,
-        risk: decision.risk,
-        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) {
-    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, routed) {
-    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) {
-    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) {
-    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) {
-    if (!producer) {
-        return "unknown";
-    }
-    return [producer.kind, producer.server, producer.tool, producer.name].filter(Boolean).join(":");
-}