@hassangameryt/freeflow 0.2.0 → 0.3.0

package/plugins/freeflow/router/dist/config.d.ts

@@ -1,22 +0,0 @@
-import type { RouterConfig, VaultRetentionPolicy } from "./types.js";
-export declare const OUTPUT_ROUTER_SKILL_PATH = "plugins/freeflow/skills/output-router/SKILL.md";
-export declare const DEFAULT_VAULT_ROOT = "~/.cache/freeflow-router/vault";
-export declare const DEFAULT_POST_TOOL_ROUTING = "off";
-export declare const DEFAULT_VAULT_RETENTION: {
-    readonly strategy: "ttl";
-    readonly ttlDays: 7;
-};
-export declare const DEFAULT_ROUTER_THRESHOLDS: {
-    readonly largeOutputBytes: 64000;
-    readonly largeOutputLines: 1000;
-};
-export interface CreateDefaultRouterConfigOptions {
-    vaultRetention?: VaultRetentionPolicy;
-    vaultRoot?: string;
-}
-export declare function createDefaultRouterConfig(options?: CreateDefaultRouterConfigOptions): RouterConfig;
-export interface NormalizeRouterConfigResult {
-    config: RouterConfig;
-    warnings: string[];
-}
-export declare function normalizeRouterConfig(input: unknown): NormalizeRouterConfigResult;

package/plugins/freeflow/router/dist/config.js

@@ -1,114 +0,0 @@
-import { isValidPostToolRoutingMode, validatePositiveIntegerThreshold } from "./router-contract.js";
-export const OUTPUT_ROUTER_SKILL_PATH = "plugins/freeflow/skills/output-router/SKILL.md";
-export const DEFAULT_VAULT_ROOT = "~/.cache/freeflow-router/vault";
-export const DEFAULT_POST_TOOL_ROUTING = "off";
-export const DEFAULT_VAULT_RETENTION = {
-    strategy: "ttl",
-    ttlDays: 7,
-};
-export const DEFAULT_ROUTER_THRESHOLDS = {
-    largeOutputBytes: 64_000,
-    largeOutputLines: 1_000,
-};
-export function createDefaultRouterConfig(options = {}) {
-    return {
-        postToolRouting: DEFAULT_POST_TOOL_ROUTING,
-        thresholds: { ...DEFAULT_ROUTER_THRESHOLDS },
-        vault: {
-            root: options.vaultRoot ?? DEFAULT_VAULT_ROOT,
-            retention: options.vaultRetention ?? DEFAULT_VAULT_RETENTION,
-        },
-    };
-}
-export function normalizeRouterConfig(input) {
-    const config = createDefaultRouterConfig();
-    const warnings = [];
-    if (input === undefined || input === null) {
-        return { config, warnings };
-    }
-    if (!isRecord(input)) {
-        return {
-            config,
-            warnings: ["outputRouter config must be an object; using built-in output router defaults."],
-        };
-    }
-    applyPostToolRouting(config, warnings, input.postToolRouting);
-    applyPositiveInteger(config.thresholds, warnings, input.largeOutputBytes, "largeOutputBytes");
-    applyPositiveInteger(config.thresholds, warnings, input.largeOutputLines, "largeOutputLines");
-    applyVaultRoot(config, warnings, input.vaultRoot);
-    applyVaultRetention(config, warnings, input.vaultRetentionDays);
-    applyHints(config, warnings, input.generatedPaths, input.noisyCommandHints);
-    return { config, warnings };
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function applyPostToolRouting(config, warnings, value) {
-    if (value === undefined) {
-        return;
-    }
-    if (isValidPostToolRoutingMode(value)) {
-        config.postToolRouting = value;
-        return;
-    }
-    warnings.push(`Invalid outputRouter.postToolRouting=${JSON.stringify(value)}; using ${DEFAULT_POST_TOOL_ROUTING}.`);
-}
-function applyPositiveInteger(thresholds, warnings, value, key) {
-    if (value === undefined) {
-        return;
-    }
-    if (validatePositiveIntegerThreshold(value, `outputRouter.${key}`).length === 0) {
-        thresholds[key] = value;
-        return;
-    }
-    warnings.push(`Invalid outputRouter.${key}=${JSON.stringify(value)}; using ${DEFAULT_ROUTER_THRESHOLDS[key]}.`);
-}
-function applyVaultRoot(config, warnings, value) {
-    if (value === undefined) {
-        return;
-    }
-    if (typeof value === "string" && value.trim().length > 0) {
-        config.vault.root = value;
-        return;
-    }
-    warnings.push(`Invalid outputRouter.vaultRoot=${JSON.stringify(value)}; using ${DEFAULT_VAULT_ROOT}.`);
-}
-function applyVaultRetention(config, warnings, value) {
-    if (value === undefined) {
-        return;
-    }
-    if (validatePositiveIntegerThreshold(value, "outputRouter.vaultRetentionDays").length === 0) {
-        config.vault.retention = { strategy: "ttl", ttlDays: value };
-        return;
-    }
-    warnings.push(`Invalid outputRouter.vaultRetentionDays=${JSON.stringify(value)}; using ${DEFAULT_VAULT_RETENTION.ttlDays}.`);
-}
-function applyHints(config, warnings, generatedPaths, noisyCommandHints) {
-    const hints = {};
-    if (generatedPaths !== undefined) {
-        const parsed = parseStringArray(generatedPaths, "generatedPaths", warnings);
-        if (parsed) {
-            hints.generatedPathGlobs = parsed;
-        }
-    }
-    if (noisyCommandHints !== undefined) {
-        const parsed = parseStringArray(noisyCommandHints, "noisyCommandHints", warnings);
-        if (parsed) {
-            hints.noisyCommandPatterns = parsed;
-        }
-    }
-    if (hints.generatedPathGlobs || hints.noisyCommandPatterns) {
-        config.hints = hints;
-    }
-}
-function parseStringArray(value, key, warnings) {
-    if (!Array.isArray(value)) {
-        warnings.push(`Invalid outputRouter.${key}; expected an array of strings.`);
-        return undefined;
-    }
-    if (!value.every((item) => typeof item === "string")) {
-        warnings.push(`Invalid outputRouter.${key}; expected an array of strings.`);
-        return undefined;
-    }
-    return value;
-}

package/plugins/freeflow/router/dist/experimental-local-index.d.ts

@@ -1 +0,0 @@
-export * from "./experiments/local-index.js";

package/plugins/freeflow/router/dist/experimental-local-index.js

@@ -1 +0,0 @@
-export * from "./experiments/local-index.js";

package/plugins/freeflow/router/dist/index.d.ts

@@ -1,12 +0,0 @@
-export * from "./benchmarks.js";
-export * from "./command-benchmarks.js";
-export * from "./codex-qa-benchmarks.js";
-export * from "./experimental-local-index.js";
-export * from "./index-benchmarks.js";
-export * from "./config.js";
-export * from "./retrieve.js";
-export * from "./run.js";
-export * from "./router-contract.js";
-export * from "./schema.js";
-export * from "./types.js";
-export * from "./vault.js";

package/plugins/freeflow/router/dist/index.js

@@ -1,12 +0,0 @@
-export * from "./benchmarks.js";
-export * from "./command-benchmarks.js";
-export * from "./codex-qa-benchmarks.js";
-export * from "./experimental-local-index.js";
-export * from "./index-benchmarks.js";
-export * from "./config.js";
-export * from "./retrieve.js";
-export * from "./run.js";
-export * from "./router-contract.js";
-export * from "./schema.js";
-export * from "./types.js";
-export * from "./vault.js";

package/plugins/freeflow/router/dist/retrieve.d.ts

@@ -1,33 +0,0 @@
-import type { EvidencePacket, OutputStream, PreserveMode, RetrievalAction, RetrievalRoutedResult } from "./types.js";
-export interface RepoRetrieveSourceInput {
-    kind: "repo";
-    root: string;
-    path?: string;
-}
-export interface VaultRetrieveSourceInput {
-    kind: "vault";
-    root: string;
-    sessionId: string;
-    outputId: string;
-    stream?: OutputStream;
-}
-export type RetrieveSourceInput = RepoRetrieveSourceInput | VaultRetrieveSourceInput;
-export type RepoExpansion = "lines_30" | "lines_80" | "full";
-export interface RetrieveLineRangeInput {
-    start: number;
-    end: number;
-}
-export interface FreeflowRetrieveOptions {
-    action: RetrievalAction;
-    source: RetrieveSourceInput;
-    query?: string;
-    preserve?: PreserveMode;
-    evidence?: EvidencePacket;
-    expansion?: RepoExpansion;
-    maxFullBytes?: number;
-    lineRange?: RetrieveLineRangeInput;
-    topK?: number;
-    decision?: RetrievalRoutedResult;
-    generatedPathGlobs?: readonly string[];
-}
-export declare function freeflowRetrieve(options: FreeflowRetrieveOptions): Promise<RetrievalRoutedResult>;

package/plugins/freeflow/router/dist/run.d.ts

@@ -1,26 +0,0 @@
-import type { CommandRoutedResult, ExecutionStatus, PreserveMode, RouterThresholds, VaultRetentionPolicy } from "./types.js";
-export interface HostCommandRunRequest {
-    command: string | readonly string[];
-    cwd?: string;
-    timeoutMs?: number;
-}
-export interface HostCommandRunResult {
-    stdout: string;
-    stderr: string;
-    executionStatus: ExecutionStatus;
-    exitCode: number | null;
-    combined?: string;
-    durationMs?: number;
-}
-export interface HostCommandRunner {
-    run(request: HostCommandRunRequest): Promise<HostCommandRunResult>;
-}
-export interface FreeflowRunOptions extends HostCommandRunRequest {
-    sessionId: string;
-    vaultRoot?: string;
-    vaultRetention?: VaultRetentionPolicy;
-    preserve?: PreserveMode;
-    goal?: string;
-    thresholds?: Partial<RouterThresholds>;
-}
-export declare function freeflowRun(options: FreeflowRunOptions, runner: HostCommandRunner): Promise<CommandRoutedResult>;

package/plugins/freeflow/router/dist/run.js

@@ -1,356 +0,0 @@
-import { createHash } from "node:crypto";
-import { commandOutputFingerprints, createVault, findExactDuplicateCommandOutput, storeCommandOutput, } from "./vault.js";
-import { DEFAULT_ROUTER_THRESHOLDS } from "./config.js";
-import { assembleTextEvidence, byteLength, countLines } from "./evidence.js";
-import { parseCommandOutput } from "./parsers.js";
-export async function freeflowRun(options, runner) {
-    const preserve = options.preserve ?? "important";
-    const thresholds = { ...DEFAULT_ROUTER_THRESHOLDS, ...options.thresholds };
-    const vaultOptions = {};
-    if (options.vaultRoot !== undefined) {
-        vaultOptions.root = options.vaultRoot;
-    }
-    if (options.vaultRetention !== undefined) {
-        vaultOptions.retention = options.vaultRetention;
-    }
-    const vault = createVault(vaultOptions);
-    let runResult;
-    try {
-        const runRequest = { command: options.command };
-        if (options.cwd !== undefined) {
-            runRequest.cwd = options.cwd;
-        }
-        if (options.timeoutMs !== undefined) {
-            runRequest.timeoutMs = options.timeoutMs;
-        }
-        runResult = await runner.run(runRequest);
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return {
-            toolStatus: "error",
-            decisionId: decisionId("run-error", commandText(options.command), message),
-            preserve,
-            outputId: "",
-            execution: { status: "failed", exitCode: null },
-            routing: {
-                status: "failed",
-                route: "run",
-                reason: `Adapter-provided runner failed before command output could be captured: ${message}`,
-            },
-            recovery: {
-                how: "No command output was captured. Retry through the host-approved runner or use the host-native shell tool if direct raw behavior is required.",
-            },
-        };
-    }
-    const combined = runResult.combined ?? combineOutputSections(runResult.stdout, runResult.stderr);
-    let record;
-    let duplicate;
-    const fingerprints = commandOutputFingerprints({
-        command: options.command,
-        stdout: runResult.stdout,
-        stderr: runResult.stderr,
-        combined,
-        executionStatus: runResult.executionStatus,
-        exitCode: runResult.exitCode,
-        ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
-    });
-    if (preserve !== "full") {
-        try {
-            duplicate = await findExactDuplicateCommandOutput(vault, {
-                sessionId: options.sessionId,
-                fingerprints,
-            });
-        }
-        catch {
-            duplicate = undefined;
-        }
-    }
-    const execution = {
-        status: runResult.executionStatus,
-        exitCode: runResult.exitCode,
-    };
-    if (runResult.durationMs !== undefined) {
-        Object.assign(execution, { durationMs: runResult.durationMs });
-    }
-    try {
-        const storeOptions = {
-            sessionId: options.sessionId,
-            command: options.command,
-            stdout: runResult.stdout,
-            stderr: runResult.stderr,
-            combined,
-            executionStatus: runResult.executionStatus,
-            exitCode: runResult.exitCode,
-            decisionIds: [decisionId("run", commandText(options.command), options.sessionId)],
-        };
-        if (options.cwd !== undefined) {
-            Object.assign(storeOptions, { cwd: options.cwd });
-        }
-        if (runResult.durationMs !== undefined) {
-            Object.assign(storeOptions, { durationMs: runResult.durationMs });
-        }
-        record = await storeCommandOutput(vault, storeOptions);
-        const routeOptions = {
-            outputId: record.outputId,
-            command: options.command,
-            executionStatus: runResult.executionStatus,
-            exitCode: runResult.exitCode,
-            stdout: runResult.stdout,
-            stderr: runResult.stderr,
-            combined,
-            preserve,
-            thresholds,
-        };
-        if (options.goal !== undefined) {
-            routeOptions.goal = options.goal;
-        }
-        const routing = duplicate
-            ? routeDuplicateCommandOutput({
-                outputId: record.outputId,
-                duplicate,
-                command: options.command,
-                executionStatus: runResult.executionStatus,
-                exitCode: runResult.exitCode,
-            })
-            : routeCommandOutput(routeOptions);
-        return {
-            toolStatus: "ok",
-            decisionId: routing.decisionId,
-            outputId: record.outputId,
-            preserve,
-            execution,
-            routing: {
-                status: routing.routingStatus,
-                route: "run",
-                reason: routing.reason,
-            },
-            summary: routing.summary,
-            importantLines: routing.importantLines,
-            parser: routing.parser,
-            recovery: commandRecoveryHint(record.outputId, duplicate),
-        };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return commandRoutingFailureResult({
-            command: options.command,
-            outputId: record?.outputId ?? "",
-            preserve,
-            execution,
-            stdout: runResult.stdout,
-            stderr: runResult.stderr,
-            combined,
-            errorMessage: message,
-        });
-    }
-}
-function routeDuplicateCommandOutput(options) {
-    const currentVaultText = options.outputId === options.duplicate.outputId
-        ? `Current run resolved to the same outputId=${options.outputId}.`
-        : `Current raw output was vaulted as outputId=${options.outputId}.`;
-    const statusText = `executionStatus=${options.executionStatus} exitCode=${options.exitCode}`;
-    return {
-        decisionId: decisionId("run-route", options.outputId, "exact-duplicate", options.duplicate.outputId),
-        routingStatus: "partial",
-        reason: `Exact duplicate command output matched previous outputId=${options.duplicate.outputId} by exact output hash and command/cwd/status fingerprint (${statusText}); returning a compact duplicate note instead of re-injecting repeated output. ${currentVaultText}`,
-        summary: `Command output is an exact duplicate of previous outputId=${options.duplicate.outputId}. ${currentVaultText}`,
-        importantLines: [],
-        parser: {
-            name: "duplicate-output",
-            confidence: 1,
-            fidelity: "exact",
-            compressed: true,
-            counts: { duplicateOutputs: 1 },
-        },
-    };
-}
-function commandRecoveryHint(outputId, duplicate) {
-    if (duplicate) {
-        return {
-            how: `Current exact command output: use freeflow_retrieve with source.kind=vault and outputId=${outputId}. Prior identical output: outputId=${duplicate.outputId}.`,
-            outputId,
-        };
-    }
-    return {
-        how: `Use freeflow_retrieve with source.kind=vault and outputId=${outputId} to recover exact command output.`,
-        outputId,
-    };
-}
-function commandRoutingFailureResult(options) {
-    const { stream, text } = routedCommandText({
-        outputId: options.outputId,
-        command: options.command,
-        executionStatus: options.execution.status,
-        exitCode: options.execution.exitCode,
-        stdout: options.stdout,
-        stderr: options.stderr,
-        combined: options.combined,
-        preserve: options.preserve,
-        thresholds: DEFAULT_ROUTER_THRESHOLDS,
-    });
-    const fallback = assembleTextEvidence({ stream, text });
-    const parser = {
-        name: "router-fallback",
-        confidence: 0,
-        fidelity: fallback.fidelity,
-        compressed: fallback.compressed,
-    };
-    const recovery = options.outputId
-        ? {
-            how: `Routing failed after vault capture; use freeflow_retrieve with source.kind=vault and outputId=${options.outputId} to recover exact command output.`,
-            outputId: options.outputId,
-        }
-        : {
-            how: "Command output could not be vaulted. A bounded in-memory preview was returned; rerun through the host-approved runner if exact recovery is required.",
-        };
-    return {
-        toolStatus: "error",
-        decisionId: decisionId("run-route-error", commandText(options.command), options.errorMessage),
-        outputId: options.outputId,
-        preserve: options.preserve,
-        execution: options.execution,
-        routing: {
-            status: "failed",
-            route: "run",
-            reason: `Command executed, but Freeflow routing failed after execution: ${options.errorMessage}`,
-        },
-        summary: "Command executed, but Freeflow routing failed after execution.",
-        importantLines: fallback.importantLines,
-        parser,
-        recovery,
-    };
-}
-// Keep exactness-sensitive command routing aligned with
-// plugins/freeflow/skills/output-router/references/safety-policy.md.
-function routeCommandOutput(options) {
-    const outputBytes = byteLength(options.combined);
-    const outputLines = countLines(options.combined);
-    const isLarge = outputBytes > options.thresholds.largeOutputBytes || outputLines > options.thresholds.largeOutputLines;
-    const parseInput = {
-        command: options.command,
-        executionStatus: options.executionStatus,
-        exitCode: options.exitCode,
-        stdout: options.stdout,
-        stderr: options.stderr,
-        combined: options.combined,
-    };
-    if (options.goal !== undefined) {
-        Object.assign(parseInput, { goal: options.goal });
-    }
-    const parsed = parseCommandOutput(parseInput);
-    const parser = parsed.parser;
-    const statusText = `executionStatus=${options.executionStatus} exitCode=${options.exitCode}`;
-    const parserText = parserTextFor(parser);
-    if (options.preserve === "full") {
-        return routeFullOutput(options, parsed, outputBytes, outputLines, statusText);
-    }
-    if (options.executionStatus !== "success") {
-        return {
-            decisionId: decisionId("run-route", options.outputId, options.executionStatus, "failed", parser.name),
-            routingStatus: "routed",
-            reason: `Command failed or did not complete (${statusText}); selected failure evidence was returned and raw output was vaulted before routing (${parserText}).`,
-            summary: parsed.summary ?? `Command ${options.executionStatus} with exitCode=${options.exitCode}.`,
-            importantLines: parsed.importantLines,
-            parser,
-        };
-    }
-    if (isLarge) {
-        return {
-            decisionId: decisionId("run-route", options.outputId, "large-success", parser.name),
-            routingStatus: "partial",
-            reason: `Large successful command output (${outputBytes} bytes, ${outputLines} lines) was vaulted; bounded important lines were returned instead of full output (${parserText}).`,
-            summary: parsed.summary ?? `Command succeeded with ${outputLines} output lines and ${outputBytes} bytes.`,
-            importantLines: parsed.importantLines,
-            parser,
-        };
-    }
-    const nearRaw = selectNearRawSuccessfulLines(options);
-    const nearRawParser = parserWithEvidence(parser, nearRaw);
-    return {
-        decisionId: decisionId("run-route", options.outputId, "small-success", parser.name, nearRaw.fidelity),
-        routingStatus: nearRaw.fidelity === "exact" ? "routed" : "partial",
-        reason: `Small successful command output was captured in the vault and returned near-raw (${parserTextFor(nearRawParser)}).`,
-        summary: parsed.summary ?? `Command success with exitCode=${options.exitCode}.`,
-        importantLines: nearRaw.importantLines,
-        parser: nearRawParser,
-    };
-}
-function routeFullOutput(options, parsed, outputBytes, outputLines, statusText) {
-    const full = selectFullOutputLines(options);
-    const parser = parserWithEvidence(parsed.parser, full);
-    const routedStatus = full.fidelity === "exact" ? "routed" : "partial";
-    const capText = `${options.thresholds.largeOutputBytes} byte full-context cap`;
-    const reason = full.fidelity === "exact"
-        ? `preserve=full returned exact command output within the ${capText} after raw output was vaulted (${statusText}; ${parserTextFor(parser)}).`
-        : `preserve=full output exceeded the bounded context policy (${outputBytes} bytes, ${outputLines} lines); a bounded preview was returned with raw vault recovery (${statusText}; ${parserTextFor(parser)}).`;
-    return {
-        decisionId: decisionId("run-route", options.outputId, "preserve-full", full.fidelity, parsed.parser.name),
-        routingStatus: routedStatus,
-        reason,
-        summary: parsed.summary ?? `Command ${options.executionStatus} with exitCode=${options.exitCode}.`,
-        importantLines: full.importantLines,
-        parser,
-    };
-}
-function selectNearRawSuccessfulLines(options) {
-    const { stream, text } = routedCommandText(options);
-    return assembleTextEvidence({
-        stream,
-        text,
-        caps: {
-            maxLines: options.thresholds.largeOutputLines,
-            maxExcerptBytes: options.thresholds.largeOutputBytes,
-            maxLineBytes: options.thresholds.largeOutputBytes,
-        },
-    });
-}
-function selectFullOutputLines(options) {
-    const { stream, text } = routedCommandText(options);
-    return assembleTextEvidence({
-        stream,
-        text,
-        caps: {
-            maxLines: Number.MAX_SAFE_INTEGER,
-            maxExcerptBytes: options.thresholds.largeOutputBytes,
-            maxLineBytes: options.thresholds.largeOutputBytes,
-        },
-    });
-}
-function routedCommandText(options) {
-    if (options.stdout.length > 0 && options.stderr.length === 0) {
-        return { stream: "stdout", text: options.stdout };
-    }
-    if (options.stderr.length > 0 && options.stdout.length === 0) {
-        return { stream: "stderr", text: options.stderr };
-    }
-    return { stream: "combined", text: options.combined };
-}
-function parserWithEvidence(parser, evidence) {
-    return {
-        ...parser,
-        fidelity: parser.fidelity === "lossy" || evidence.fidelity === "lossy" ? "lossy" : "exact",
-        compressed: evidence.compressed,
-    };
-}
-function parserTextFor(parser) {
-    return `parser=${parser.name} confidence=${parser.confidence.toFixed(2)} fidelity=${parser.fidelity}`;
-}
-function combineOutputSections(stdout, stderr) {
-    if (stdout.length === 0) {
-        return stderr;
-    }
-    if (stderr.length === 0) {
-        return stdout;
-    }
-    return `[stdout]\n${stdout}\n[stderr]\n${stderr}`;
-}
-function commandText(command) {
-    return typeof command === "string" ? command : command.join(" ");
-}
-function decisionId(...parts) {
-    return `ffdec_${hash(parts.join("\0")).slice(0, 16)}`;
-}
-function hash(value) {
-    return createHash("sha256").update(value).digest("hex");
-}