@hassangameryt/freeflow 0.2.0 → 0.3.0

package/router/dist/routing/observed-routing.js

@@ -0,0 +1,377 @@
+import { createHash } from "node:crypto";
+import { DEFAULT_ROUTER_THRESHOLDS } from "../config/config.js";
+import { byteLength, countLines } from "../evidence/evidence.js";
+import { reduceObservedOutput } from "./observed-reducers.js";
+import { createVault, storeMetadataOutput, storeTextOutput } from "../vault/vault.js";
+export async function routeObservedToolOutput(options) {
+    const preserve = options.preserve ?? "important";
+    const thresholds = { ...DEFAULT_ROUTER_THRESHOLDS, ...options.thresholds };
+    let normalizedOutput;
+    let normalized;
+    let decisionId;
+    try {
+        normalizedOutput = normalizeObservedOutput(options.rawResult, options.mediaType);
+        normalized = observedNormalization(normalizedOutput);
+        decisionId = observedDecisionId(options, normalizedOutput.text);
+    }
+    catch (error) {
+        const passthroughText = safePassthroughText(options.rawResult);
+        const fallbackOutput = {
+            text: passthroughText,
+            shape: "structured",
+            ...(options.mediaType !== undefined ? { mediaType: options.mediaType } : {}),
+        };
+        const fallbackNormalized = observedNormalization(fallbackOutput);
+        return failOpenObservedOutput({
+            options,
+            preserve,
+            decisionId: observedDecisionId(options, `${passthroughText}:${errorMessage(error)}`),
+            normalized: fallbackNormalized,
+            text: passthroughText,
+            failureKind: "observed_routing_failure",
+            message: `Observed output from ${producerLabel(options.producer)} could not be normalized: ${errorMessage(error)}`,
+        });
+    }
+    let stored;
+    try {
+        stored = await persistObservedOutput({
+            ...options,
+            decisionId,
+            normalized,
+            text: normalizedOutput.text,
+        });
+    }
+    catch (error) {
+        return failOpenObservedOutput({
+            options,
+            preserve,
+            decisionId,
+            normalized,
+            text: normalizedOutput.text,
+            failureKind: "storage_failure",
+            message: `Observed output from ${producerLabel(options.producer)} could not be persisted: ${errorMessage(error)}`,
+        });
+    }
+    let routed;
+    try {
+        routed = reduceObservedOutput({
+            text: normalizedOutput.text,
+            rawValue: options.rawResult,
+            normalized,
+            preserve,
+            thresholds,
+            source: stored.evidenceSource,
+            outputId: stored.outputId ?? decisionId,
+            producer: options.producer,
+        });
+    }
+    catch (error) {
+        return failOpenObservedOutput({
+            options,
+            preserve,
+            decisionId,
+            normalized,
+            text: normalizedOutput.text,
+            failureKind: "observed_routing_failure",
+            stored,
+            message: `Observed output from ${producerLabel(options.producer)} could not be reduced: ${errorMessage(error)}`,
+        });
+    }
+    const result = {
+        toolStatus: "ok",
+        decisionId,
+        preserve,
+        host: options.host,
+        normalized,
+        producer: options.producer,
+        ...(options.risk !== undefined ? { risk: options.risk } : {}),
+        persistence: stored.persistence,
+        routing: {
+            status: routed.routingStatus,
+            route: "observed",
+            reason: routed.reason,
+        },
+        summary: routed.summary,
+        evidence: routed.evidence,
+        recovery: recoveryHint(stored.persistence),
+    };
+    if (stored.outputId !== undefined) {
+        result.outputId = stored.outputId;
+    }
+    if (stored.recordId !== undefined) {
+        result.recordId = stored.recordId;
+    }
+    return result;
+}
+async function persistObservedOutput(options) {
+    if (options.persistence === "none") {
+        return {
+            persistence: noPersistence(),
+            evidenceSource: { kind: "native", tool: options.host.toolName, outputId: options.decisionId },
+        };
+    }
+    const vaultOptions = {};
+    if (options.vaultRoot !== undefined) {
+        vaultOptions.root = options.vaultRoot;
+    }
+    if (options.vaultRetention !== undefined) {
+        vaultOptions.retention = options.vaultRetention;
+    }
+    const vault = createVault(vaultOptions);
+    const sourceKind = sourceKindForProducer(options.producer);
+    if (options.persistence === "metadata-only") {
+        const record = await storeMetadataOutput(vault, {
+            sessionId: options.sessionId,
+            sourceKind,
+            rawLineCount: options.normalized.lineCount,
+            rawByteCount: options.normalized.byteCount,
+            rawSha256: sha256Text(options.text),
+            metadata: {
+                host: options.host,
+                producer: options.producer,
+                shape: options.normalized.shape,
+                ...(options.normalized.mediaType !== undefined ? { mediaType: options.normalized.mediaType } : {}),
+                ...(options.toolInputHash !== undefined ? { toolInputHash: options.toolInputHash } : {}),
+            },
+            decisionIds: [options.decisionId],
+            ...(options.createdAt !== undefined ? { createdAt: options.createdAt } : {}),
+            producer: options.producer,
+        });
+        return {
+            outputId: record.outputId,
+            recordId: record.recordId,
+            persistence: { ...record.persistence, outputId: record.outputId },
+            evidenceSource: { kind: "native", tool: options.host.toolName, outputId: record.outputId },
+        };
+    }
+    const record = await storeTextOutput(vault, {
+        sessionId: options.sessionId,
+        raw: options.text,
+        sourceKind,
+        decisionIds: [options.decisionId],
+        ...(options.createdAt !== undefined ? { createdAt: options.createdAt } : {}),
+        producer: options.producer,
+    });
+    return {
+        outputId: record.outputId,
+        recordId: record.recordId,
+        persistence: record.persistence,
+        evidenceSource: { kind: "vault", outputId: record.outputId, stream: "raw" },
+    };
+}
+function observedNormalization(normalizedOutput) {
+    return {
+        shape: normalizedOutput.shape,
+        ...(normalizedOutput.mediaType !== undefined ? { mediaType: normalizedOutput.mediaType } : {}),
+        byteCount: byteLength(normalizedOutput.text),
+        lineCount: countLines(normalizedOutput.text),
+    };
+}
+function observedDecisionId(options, text) {
+    return decisionIdFromSeed([
+        "observed",
+        options.sessionId,
+        options.host.name,
+        options.host.toolName,
+        producerLabel(options.producer),
+        options.persistence,
+        sha256Text(text),
+    ].join("|"));
+}
+function failOpenObservedOutput(options) {
+    return {
+        toolStatus: "ok",
+        decisionId: options.decisionId,
+        preserve: options.preserve,
+        host: options.options.host,
+        normalized: options.normalized,
+        producer: options.options.producer,
+        ...(options.options.risk !== undefined ? { risk: options.options.risk } : {}),
+        persistence: options.stored?.persistence ?? noPersistence(),
+        routing: {
+            status: "failed",
+            route: "observed",
+            reason: `${options.message}; failing open with original host output preserved.`,
+        },
+        failure: {
+            kind: options.failureKind,
+            message: options.message,
+        },
+        passthrough: {
+            text: options.text,
+            reason: "Observed routing failed after the host tool completed; host output must be allowed through.",
+        },
+        recovery: options.stored
+            ? recoveryHint(options.stored.persistence)
+            : {
+                how: "No content was persisted because observed routing failed. Recovery is unavailable; use the original host output from this result.",
+            },
+        ...(options.stored?.outputId !== undefined ? { outputId: options.stored.outputId } : {}),
+        ...(options.stored?.recordId !== undefined ? { recordId: options.stored.recordId } : {}),
+    };
+}
+function normalizeObservedOutput(value, mediaType) {
+    if (typeof value === "string") {
+        return { text: value, shape: "text", ...(mediaType !== undefined ? { mediaType } : {}) };
+    }
+    if (isRecord(value)) {
+        const stdio = normalizeStdio(value);
+        if (stdio !== undefined) {
+            return { text: stdio, shape: "stdio", ...(mediaType !== undefined ? { mediaType } : {}) };
+        }
+        const contentBlocks = normalizeContentBlocks(value.content);
+        if (contentBlocks !== undefined) {
+            return { text: contentBlocks, shape: "content_blocks", ...(mediaType !== undefined ? { mediaType } : {}) };
+        }
+        if (typeof value.text === "string") {
+            return { text: value.text, shape: "structured", ...(mediaType !== undefined ? { mediaType } : {}) };
+        }
+        return {
+            text: stableJson(value),
+            shape: "json",
+            mediaType: mediaType ?? "application/json",
+        };
+    }
+    return { text: value === undefined ? "" : String(value), shape: "text", ...(mediaType !== undefined ? { mediaType } : {}) };
+}
+function normalizeStdio(value) {
+    const stdout = typeof value.stdout === "string" ? value.stdout : undefined;
+    const stderr = typeof value.stderr === "string" ? value.stderr : undefined;
+    if (stdout === undefined && stderr === undefined) {
+        return undefined;
+    }
+    if (stdout !== undefined && stderr !== undefined) {
+        if (stdout.length === 0) {
+            return stderr;
+        }
+        if (stderr.length === 0) {
+            return stdout;
+        }
+        return `[stdout]\n${stdout}\n[stderr]\n${stderr}`;
+    }
+    return stdout ?? stderr ?? "";
+}
+function normalizeContentBlocks(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    return value.map(normalizeContentBlock).join("\n");
+}
+function normalizeContentBlock(block) {
+    if (typeof block === "string") {
+        return block;
+    }
+    if (!isRecord(block)) {
+        return String(block);
+    }
+    if (typeof block.text === "string") {
+        return block.text;
+    }
+    if (block.json !== undefined) {
+        return stableJson(block.json);
+    }
+    if (block.content !== undefined) {
+        const nested = normalizeContentBlocks(block.content);
+        if (nested !== undefined) {
+            return nested;
+        }
+    }
+    return stableJson(block);
+}
+function sourceKindForProducer(producer) {
+    if (producer.kind === "mcp") {
+        return "mcp";
+    }
+    if (producer.kind === "web") {
+        return "web";
+    }
+    if (producer.kind === "fetch") {
+        return "fetch";
+    }
+    if (producer.kind === "code_search") {
+        return "code_search";
+    }
+    if (producer.kind === "transform") {
+        return "transform";
+    }
+    if (producer.kind === "native") {
+        return "native";
+    }
+    return "other";
+}
+function recoveryHint(persistence) {
+    const recoveryOutputId = persistence.recoveryOutputId ?? persistence.outputId;
+    if (persistence.recoverability === "exact" && recoveryOutputId !== undefined) {
+        return {
+            how: `Use freeflow_search with source.kind=vault and outputId=${recoveryOutputId}, stream=raw, and an exact lineRange to recover exact observed output.`,
+            outputId: recoveryOutputId,
+        };
+    }
+    if (persistence.recoverability === "metadata_only") {
+        return {
+            how: "Only metadata was persisted for this observed output. No raw content stream is recoverable.",
+            ...(persistence.outputId !== undefined ? { outputId: persistence.outputId } : {}),
+        };
+    }
+    return {
+        how: "No content or metadata was persisted for this observed output. Recovery is unavailable.",
+    };
+}
+function noPersistence() {
+    return { status: "not_persisted", recoverability: "none" };
+}
+function producerLabel(producer) {
+    return [producer.kind, producer.server, producer.tool, producer.name].filter(Boolean).join(":");
+}
+function decisionIdFromSeed(seed) {
+    return `ffdec_${createHash("sha256").update(seed).digest("hex").slice(0, 16)}`;
+}
+function sha256Text(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+function stableJson(value) {
+    return JSON.stringify(value, sortJsonKeys, 2);
+}
+function safePassthroughText(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    try {
+        return JSON.stringify(value, safeJsonReplacer(), 2) ?? String(value);
+    }
+    catch {
+        try {
+            return String(value);
+        }
+        catch {
+            return "[unrepresentable observed tool output]";
+        }
+    }
+}
+function safeJsonReplacer() {
+    const seen = new WeakSet();
+    return function replace(_key, value) {
+        if (typeof value === "bigint") {
+            return `${value.toString()}n`;
+        }
+        if (typeof value === "object" && value !== null) {
+            if (seen.has(value)) {
+                return "[Circular]";
+            }
+            seen.add(value);
+        }
+        return value;
+    };
+}
+function sortJsonKeys(_key, value) {
+    if (!isRecord(value) || Array.isArray(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/{plugins/freeflow/router/dist → router/dist/routing}/parsers.d.ts

@@ -1,4 +1,4 @@
-import type { CommandParserMetadata, ExecutionStatus, ImportantLine } from "./types.js";
+import type { CommandParserMetadata, ExecutionStatus, ImportantLine } from "../config/types.js";
 export interface CommandParseInput {
     command: string | readonly string[];
     executionStatus: ExecutionStatus;

package/{plugins/freeflow/router/dist → router/dist/routing}/parsers.js

@@ -1,4 +1,4 @@
-import { DEFAULT_MAX_IMPORTANT_LINES, assembleImportantLines, lineEntries, nonEmptyLineEntries, splitLines, } from "./evidence.js";
+import { DEFAULT_MAX_IMPORTANT_LINES, assembleImportantLines, lineEntries, nonEmptyLineEntries, splitLines, } from "../evidence/evidence.js";
 const MAX_IMPORTANT_LINES = DEFAULT_MAX_IMPORTANT_LINES;
 const COMMAND_PARSERS = [
     { name: "test-runner", parse: parseTestRunnerOutput },

package/router/dist/routing/run-filters.d.ts

@@ -0,0 +1,56 @@
+import { type BoundedEvidence } from "../evidence/evidence.js";
+import type { ImportantLine, RunOutputFilterMetadata } from "../config/types.js";
+export type { RunOutputFilterMetadata } from "../config/types.js";
+export declare const RUN_FILTER_STREAMS: readonly ["stdout", "stderr", "combined"];
+export type RunFilterStream = (typeof RUN_FILTER_STREAMS)[number];
+export interface RunOutputFiltersInput {
+    stream?: RunFilterStream;
+    include?: string | readonly string[];
+    exclude?: string | readonly string[];
+    flags?: string;
+    head?: number;
+    tail?: number;
+    maxLines?: number;
+    maxBytes?: number;
+}
+export interface NormalizedRunOutputFilters {
+    stream?: RunFilterStream;
+    include: string[];
+    exclude: string[];
+    flags: string;
+    head?: number;
+    tail?: number;
+    maxLines?: number;
+    maxBytes?: number;
+}
+export interface RunOutputFilterResult {
+    stream: RunFilterStream;
+    evidence: BoundedEvidence;
+    metadata: RunOutputFilterMetadata;
+    description: string;
+}
+export type RunOutputFilterValidationResult = {
+    ok: true;
+    filters?: NormalizedRunOutputFilters;
+} | {
+    ok: false;
+    message: string;
+    path: string;
+};
+export declare function normalizeRunOutputFilters(input: unknown): RunOutputFilterValidationResult;
+export declare function hasRunOutputFilters(filters: NormalizedRunOutputFilters | undefined): filters is NormalizedRunOutputFilters;
+export declare function applyRunOutputFilters(options: {
+    filters: NormalizedRunOutputFilters;
+    defaultStream: RunFilterStream;
+    stdout: string;
+    stderr: string;
+    combined: string;
+    fallbackImportantLines?: readonly ImportantLine[];
+    preserveFallbackFailureEvidence?: boolean;
+    caps?: {
+        maxLines?: number;
+        maxExcerptBytes?: number;
+        maxLineBytes?: number;
+    };
+}): RunOutputFilterResult;
+export declare function describeRunOutputFilters(metadata: RunOutputFilterMetadata): string;

package/router/dist/routing/run-filters.js

@@ -0,0 +1,230 @@
+import { assembleImportantLines, lineEntries, } from "../evidence/evidence.js";
+export const RUN_FILTER_STREAMS = ["stdout", "stderr", "combined"];
+export function normalizeRunOutputFilters(input) {
+    if (input === undefined || input === null) {
+        return { ok: true };
+    }
+    if (!isRecord(input)) {
+        return { ok: false, path: "$.filters", message: "freeflow_run filters must be an object." };
+    }
+    const filters = {
+        include: [],
+        exclude: [],
+        flags: typeof input.flags === "string" ? input.flags : "",
+    };
+    if (input.stream !== undefined) {
+        if (!isRunFilterStream(input.stream)) {
+            return { ok: false, path: "$.filters.stream", message: "filters.stream must be stdout, stderr, or combined." };
+        }
+        filters.stream = input.stream;
+    }
+    for (const key of ["include", "exclude"]) {
+        const normalized = normalizeStringList(input[key], `$.filters.${key}`);
+        if (!normalized.ok) {
+            return normalized;
+        }
+        filters[key] = normalized.values;
+    }
+    if (!/^(?!.*([gimsu]).*\1)[gimsu]*$/.test(filters.flags)) {
+        return { ok: false, path: "$.filters.flags", message: "filters.flags may contain g, i, m, s, or u without duplicates." };
+    }
+    for (const key of ["head", "tail", "maxLines", "maxBytes"]) {
+        if (input[key] === undefined) {
+            continue;
+        }
+        const value = input[key];
+        if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+            return { ok: false, path: `$.filters.${key}`, message: `${key} must be a positive integer.` };
+        }
+        filters[key] = value;
+    }
+    for (const [kind, patterns] of [
+        ["include", filters.include],
+        ["exclude", filters.exclude],
+    ]) {
+        for (const pattern of patterns) {
+            try {
+                new RegExp(pattern, filters.flags);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return { ok: false, path: `$.filters.${kind}`, message: `Invalid ${kind} regex ${JSON.stringify(pattern)}: ${message}` };
+            }
+        }
+    }
+    return { ok: true, filters };
+}
+export function hasRunOutputFilters(filters) {
+    return Boolean(filters &&
+        (filters.stream ||
+            filters.include.length > 0 ||
+            filters.exclude.length > 0 ||
+            filters.head !== undefined ||
+            filters.tail !== undefined ||
+            filters.maxLines !== undefined ||
+            filters.maxBytes !== undefined));
+}
+export function applyRunOutputFilters(options) {
+    const stream = options.filters.stream ?? options.defaultStream;
+    const text = streamText(stream, options);
+    const sourceEntries = lineEntries(text);
+    const includeRegexes = options.filters.include.map((pattern) => new RegExp(pattern, options.filters.flags));
+    const excludeRegexes = options.filters.exclude.map((pattern) => new RegExp(pattern, options.filters.flags));
+    let selected = sourceEntries.filter((entry) => {
+        if (includeRegexes.length > 0 && !includeRegexes.some((regex) => regex.test(entry.line))) {
+            return false;
+        }
+        if (excludeRegexes.some((regex) => regex.test(entry.line))) {
+            return false;
+        }
+        return true;
+    });
+    selected = applyHeadTail(selected, options.filters.head, options.filters.tail);
+    if (options.filters.maxLines !== undefined) {
+        selected = selected.slice(0, options.filters.maxLines);
+    }
+    let fallbackPreservedFailureEvidence = false;
+    let evidence;
+    if (selected.length === 0 && options.preserveFallbackFailureEvidence && options.fallbackImportantLines?.length) {
+        fallbackPreservedFailureEvidence = true;
+        evidence = importantLinesAsEvidence(options.fallbackImportantLines, text);
+    }
+    else {
+        const caps = {};
+        const maxLines = options.filters.maxLines ?? options.caps?.maxLines;
+        const maxExcerptBytes = options.filters.maxBytes ?? options.caps?.maxExcerptBytes;
+        const maxLineBytes = options.filters.maxBytes ?? options.caps?.maxLineBytes;
+        if (maxLines !== undefined) {
+            caps.maxLines = maxLines;
+        }
+        if (maxExcerptBytes !== undefined) {
+            caps.maxExcerptBytes = maxExcerptBytes;
+        }
+        if (maxLineBytes !== undefined) {
+            caps.maxLineBytes = maxLineBytes;
+        }
+        evidence = assembleImportantLines({
+            stream,
+            entries: selected,
+            sourceText: text,
+            caps,
+        });
+    }
+    const metadata = {
+        stream,
+        sourceLines: sourceEntries.length,
+        selectedLines: selected.length,
+    };
+    if (options.filters.include.length > 0) {
+        metadata.include = options.filters.include;
+    }
+    if (options.filters.exclude.length > 0) {
+        metadata.exclude = options.filters.exclude;
+    }
+    if (options.filters.flags) {
+        metadata.flags = options.filters.flags;
+    }
+    if (options.filters.head !== undefined) {
+        metadata.head = options.filters.head;
+    }
+    if (options.filters.tail !== undefined) {
+        metadata.tail = options.filters.tail;
+    }
+    if (options.filters.maxLines !== undefined) {
+        metadata.maxLines = options.filters.maxLines;
+    }
+    if (options.filters.maxBytes !== undefined) {
+        metadata.maxBytes = options.filters.maxBytes;
+    }
+    if (fallbackPreservedFailureEvidence) {
+        metadata.fallbackPreservedFailureEvidence = true;
+    }
+    return {
+        stream,
+        evidence,
+        metadata,
+        description: describeRunOutputFilters(metadata),
+    };
+}
+function normalizeStringList(value, path) {
+    if (value === undefined) {
+        return { ok: true, values: [] };
+    }
+    const values = typeof value === "string" ? [value] : Array.isArray(value) ? value : undefined;
+    if (!values) {
+        return { ok: false, path, message: `${path} must be a string or string array.` };
+    }
+    if (!values.every((item) => typeof item === "string" && item.length > 0)) {
+        return { ok: false, path, message: `${path} must contain non-empty strings.` };
+    }
+    return { ok: true, values: [...values] };
+}
+function isRunFilterStream(value) {
+    return typeof value === "string" && RUN_FILTER_STREAMS.includes(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function streamText(stream, options) {
+    if (stream === "stdout") {
+        return options.stdout;
+    }
+    if (stream === "stderr") {
+        return options.stderr;
+    }
+    return options.combined;
+}
+function applyHeadTail(entries, head, tail) {
+    if (head === undefined && tail === undefined) {
+        return entries;
+    }
+    if (head !== undefined && tail !== undefined) {
+        const byLine = new Map();
+        for (const entry of [...entries.slice(0, head), ...entries.slice(Math.max(0, entries.length - tail))]) {
+            byLine.set(entry.lineNumber, entry);
+        }
+        return [...byLine.values()].sort((left, right) => left.lineNumber - right.lineNumber);
+    }
+    if (head !== undefined) {
+        return entries.slice(0, head);
+    }
+    return entries.slice(Math.max(0, entries.length - tail));
+}
+function importantLinesAsEvidence(importantLines, sourceText) {
+    return {
+        importantLines: [...importantLines],
+        fidelity: "exact",
+        compressed: true,
+        selectedLineCount: importantLines.length,
+        sourceLineCount: lineEntries(sourceText).length,
+    };
+}
+export function describeRunOutputFilters(metadata) {
+    const parts = [`stream=${metadata.stream}`];
+    if (metadata.include?.length) {
+        parts.push(`include=${metadata.include.map((pattern) => JSON.stringify(pattern)).join("|")}`);
+    }
+    if (metadata.exclude?.length) {
+        parts.push(`exclude=${metadata.exclude.map((pattern) => JSON.stringify(pattern)).join("|")}`);
+    }
+    if (metadata.flags) {
+        parts.push(`flags=${metadata.flags}`);
+    }
+    if (metadata.head !== undefined) {
+        parts.push(`head=${metadata.head}`);
+    }
+    if (metadata.tail !== undefined) {
+        parts.push(`tail=${metadata.tail}`);
+    }
+    if (metadata.maxLines !== undefined) {
+        parts.push(`maxLines=${metadata.maxLines}`);
+    }
+    if (metadata.maxBytes !== undefined) {
+        parts.push(`maxBytes=${metadata.maxBytes}`);
+    }
+    parts.push(`selected=${metadata.selectedLines}/${metadata.sourceLines} lines`);
+    if (metadata.fallbackPreservedFailureEvidence) {
+        parts.push("fallback=failure-evidence");
+    }
+    return parts.join(" ");
+}