@hassangameryt/freeflow 0.2.0 → 0.4.0

package/router/dist/config/types.d.ts

@@ -0,0 +1,573 @@
+export declare const PRESERVE_MODES: readonly ["summary", "important", "full"];
+export type PreserveMode = (typeof PRESERVE_MODES)[number];
+export declare const RETRIEVAL_ACTIONS: readonly ["query", "locate", "get", "retrieve", "expand", "explain"];
+export type RetrievalAction = (typeof RETRIEVAL_ACTIONS)[number];
+export declare const TOOL_STATUSES: readonly ["ok", "error"];
+export type ToolStatus = (typeof TOOL_STATUSES)[number];
+export declare const EXECUTION_STATUSES: readonly ["success", "failed", "timed_out", "cancelled"];
+export type ExecutionStatus = (typeof EXECUTION_STATUSES)[number];
+export declare const ROUTING_STATUSES: readonly ["routed", "passed_through", "partial", "failed"];
+export type RoutingStatus = (typeof ROUTING_STATUSES)[number];
+export declare const ROUTE_KINDS: readonly [
+  "retrieve",
+  "run",
+  "transform",
+  "batch",
+  "observed",
+  "safety-net",
+  "pass-through",
+];
+export type RouteKind = (typeof ROUTE_KINDS)[number];
+export declare const BATCH_STEP_KINDS: readonly ["run", "search"];
+export type BatchStepKind = (typeof BATCH_STEP_KINDS)[number];
+export declare const PRODUCER_KINDS: readonly [
+  "command",
+  "script",
+  "native",
+  "repo",
+  "web",
+  "fetch",
+  "code_search",
+  "mcp",
+  "transform",
+  "other",
+];
+export type ProducerKind = (typeof PRODUCER_KINDS)[number];
+export declare const PERSISTENCE_STATUSES: readonly ["vaulted", "redacted", "metadata_only", "not_persisted"];
+export type PersistenceStatus = (typeof PERSISTENCE_STATUSES)[number];
+export declare const RECOVERABILITY_MODES: readonly ["exact", "redacted", "metadata_only", "none"];
+export type RecoverabilityMode = (typeof RECOVERABILITY_MODES)[number];
+export declare const ROUTER_FAILURE_KINDS: readonly [
+  "adapter_unavailable",
+  "storage_failure",
+  "observed_routing_failure",
+  "script_transform_disabled",
+  "transform_source_unavailable",
+  "transform_validation_failure",
+  "transform_execution_failure",
+];
+export type RouterFailureKind = (typeof ROUTER_FAILURE_KINDS)[number];
+export declare const FAILURE_EXECUTION_STATUSES: readonly [
+  "unavailable",
+  "unsupported",
+  "rejected",
+  "failed",
+  "partial",
+];
+export type FailureExecutionStatus = (typeof FAILURE_EXECUTION_STATUSES)[number];
+export declare const EVIDENCE_WINDOWS: readonly ["exact", "small", "lines_30", "lines_80", "section", "full"];
+export type EvidenceWindow = (typeof EVIDENCE_WINDOWS)[number];
+export declare const OUTPUT_STREAMS: readonly ["stdout", "stderr", "combined", "raw"];
+export type OutputStream = (typeof OUTPUT_STREAMS)[number];
+export declare const POST_TOOL_ROUTING_MODES: readonly ["off", "safety-net", "strict"];
+export type PostToolRoutingMode = (typeof POST_TOOL_ROUTING_MODES)[number];
+export declare const OUTPUT_ROUTER_PROFILES: readonly ["standard"];
+export type OutputRouterProfile = (typeof OUTPUT_ROUTER_PROFILES)[number];
+export declare const STORAGE_POLICY_MODES: readonly ["store-everything", "hybrid-dedupe"];
+export type StoragePolicyMode = (typeof STORAGE_POLICY_MODES)[number];
+export declare const OBSERVED_ROUTING_FAILURE_MODES: readonly ["fail-open"];
+export type ObservedRoutingFailureMode = (typeof OBSERVED_ROUTING_FAILURE_MODES)[number];
+export declare const OBSERVED_ROUTING_PERSISTENCE_MODES: readonly ["exact", "metadata-only", "none"];
+export type ObservedRoutingPersistenceMode = (typeof OBSERVED_ROUTING_PERSISTENCE_MODES)[number];
+export declare const RESERVED_OBSERVED_ROUTING_PERSISTENCE_MODES: readonly ["redacted"];
+export type ReservedObservedRoutingPersistenceMode = (typeof RESERVED_OBSERVED_ROUTING_PERSISTENCE_MODES)[number];
+export interface RepoSourceRef {
+  kind: "repo";
+  path: string;
+}
+export interface VaultSourceRef {
+  kind: "vault";
+  outputId: string;
+  stream?: OutputStream;
+}
+export interface LocalSourceRef {
+  kind: "local";
+  root: string;
+  path: string;
+}
+export interface NativeToolSourceRef {
+  kind: "native";
+  tool: string;
+  outputId: string;
+}
+export type SourceRef = RepoSourceRef | VaultSourceRef | LocalSourceRef | NativeToolSourceRef;
+export interface ProducerDescriptor {
+  kind: ProducerKind;
+  adapter?: string;
+  name?: string;
+  server?: string;
+  tool?: string;
+}
+export interface EvidencePersistence {
+  status: PersistenceStatus;
+  recoverability: RecoverabilityMode;
+  recoveryOutputId?: string;
+  outputId?: string;
+}
+export interface EvidenceLineage {
+  sourceRecordIds?: string[];
+  sourceOutputIds?: string[];
+  operation?: string;
+  operationHash?: string;
+}
+export interface RouterFailure {
+  kind: RouterFailureKind;
+  message: string;
+}
+export interface TransformExecutionFailure {
+  status: FailureExecutionStatus;
+  failureKind: RouterFailureKind;
+  message: string;
+}
+export interface EvidenceRecordIdentity {
+  recordId: string;
+  recoveryOutputId?: string;
+  outputId?: string;
+}
+export interface EvidenceMatchMetadata {
+  type: "exact_phrase" | "lexical" | "metadata";
+  confidence: number;
+}
+export interface EvidencePacket {
+  id: string;
+  source: SourceRef;
+  excerpt: string;
+  why: string;
+  window: EvidenceWindow;
+  expandable: boolean;
+  path?: string;
+  lines?: string;
+  match?: EvidenceMatchMetadata;
+}
+export interface RecoveryHint {
+  how: string;
+  outputId?: string;
+  evidenceId?: string;
+}
+export interface RoutingDecision {
+  status: RoutingStatus;
+  route: RouteKind;
+  reason: string;
+}
+export interface CommandExecution {
+  status: ExecutionStatus;
+  exitCode: number | null;
+  durationMs?: number;
+}
+export interface ImportantLine {
+  stream: Exclude<OutputStream, "raw">;
+  lines: string;
+  excerpt: string;
+}
+export interface CommandParserReference {
+  path: string;
+  line?: number;
+  column?: number;
+  code?: string;
+  severity?: "error" | "warning" | "info";
+  message: string;
+}
+export interface RunOutputFilterMetadata {
+  stream: Exclude<OutputStream, "raw">;
+  include?: string[];
+  exclude?: string[];
+  flags?: string;
+  head?: number;
+  tail?: number;
+  maxLines?: number;
+  maxBytes?: number;
+  sourceLines: number;
+  selectedLines: number;
+  fallbackPreservedFailureEvidence?: boolean;
+}
+export interface RunScriptProducerMetadata {
+  status: "success" | "failed" | "timed_out" | "policy_violation" | "unavailable";
+  language: ScriptTransformLanguage;
+  policy: "sandboxed";
+  rawScriptPersistence: ScriptTransformRawScriptPersistence;
+  codeSha256: string;
+  limits: ScriptTransformLimits;
+  label?: string;
+  adapterId?: string;
+  adapterVersion?: string;
+  runtime?: {
+    name: string;
+    version?: string;
+  };
+  stdoutBytes?: number;
+  stderrBytes?: number;
+  exitCode?: number | null;
+  durationMs?: number;
+  operation?: Record<string, unknown>;
+  failure?: RouterFailure;
+  transformExecution?: TransformExecutionFailure;
+}
+export interface RunScriptFilterMetadata {
+  status: "success" | FailureExecutionStatus;
+  language: ScriptTransformLanguage;
+  sourceAliases: string[];
+  rawOutputId: string;
+  label?: string;
+  operation?: Record<string, unknown>;
+  outputId?: string;
+  recordId?: string;
+  persistence?: EvidencePersistence;
+  lineage?: EvidenceLineage;
+  failure?: RouterFailure;
+  transformExecution?: TransformExecutionFailure;
+  summary?: string;
+}
+export interface RunReducerMetadata {
+  status: "selected" | "success";
+  name: string;
+  version: string;
+  confidence: number;
+  rawOutputId: string;
+  facts: Array<{
+    name: string;
+    value: string | number | boolean;
+  }>;
+  summary?: string;
+  outputId?: string;
+  recordId?: string;
+  persistence?: EvidencePersistence;
+  lineage?: EvidenceLineage;
+}
+export interface CommandParserMetadata {
+  name: string;
+  confidence: number;
+  fidelity: "exact" | "lossy";
+  compressed: boolean;
+  counts?: Record<string, number>;
+  references?: CommandParserReference[];
+}
+export interface RoutedResultBase {
+  toolStatus: ToolStatus;
+  decisionId: string;
+  preserve: PreserveMode;
+  routing: RoutingDecision;
+  recordId?: string;
+  producer?: ProducerDescriptor;
+  persistence?: EvidencePersistence;
+  lineage?: EvidenceLineage;
+  failure?: RouterFailure;
+  transformExecution?: TransformExecutionFailure;
+  recovery?: RecoveryHint;
+  evidence?: EvidencePacket[];
+}
+export interface RetrievalRoutedResult extends RoutedResultBase {
+  source?: SourceRef;
+}
+export interface CommandRoutedResult extends RoutedResultBase {
+  outputId: string;
+  execution: CommandExecution;
+  summary?: string;
+  importantLines?: ImportantLine[];
+  parser?: CommandParserMetadata;
+  filters?: RunOutputFilterMetadata;
+  scriptProducer?: RunScriptProducerMetadata;
+  scriptFilter?: RunScriptFilterMetadata;
+  reducer?: RunReducerMetadata;
+}
+export interface ObservedHostDescriptor {
+  name: string;
+  toolName: string;
+}
+export declare const OBSERVED_PRODUCER_RISK_CLASSES: readonly ["read", "write", "unknown"];
+export type ObservedProducerRiskClass = (typeof OBSERVED_PRODUCER_RISK_CLASSES)[number];
+export declare const OBSERVED_PRODUCER_RISK_SOURCES: readonly [
+  "configured",
+  "mcp_annotation",
+  "manifest",
+  "heuristic",
+  "unknown",
+];
+export type ObservedProducerRiskSource = (typeof OBSERVED_PRODUCER_RISK_SOURCES)[number];
+export interface ObservedProducerRisk {
+  classification: ObservedProducerRiskClass;
+  source: ObservedProducerRiskSource;
+  reason: string;
+}
+export interface ObservedOutputNormalization {
+  shape: "text" | "json" | "content_blocks" | "stdio" | "structured";
+  mediaType?: string;
+  byteCount: number;
+  lineCount: number;
+}
+export interface ObservedRoutedResult extends RoutedResultBase {
+  outputId?: string;
+  host: ObservedHostDescriptor;
+  normalized: ObservedOutputNormalization;
+  risk?: ObservedProducerRisk;
+  summary?: string;
+  passthrough?: {
+    text: string;
+    reason: string;
+  };
+}
+export interface TransformRoutedResult extends RoutedResultBase {
+  outputId: string;
+  source: SourceRef;
+  operation: Record<string, unknown>;
+  summary?: string;
+}
+export interface BatchStepRoutedResult {
+  id: string;
+  index: number;
+  kind: BatchStepKind;
+  status: "ok" | "failed";
+  toolStatus?: ToolStatus;
+  durationMs: number;
+  result?: RoutedResult;
+  error?: string;
+}
+export interface BatchQueryMatch {
+  stepId: string;
+  stepIndex: number;
+  stepKind: BatchStepKind;
+  source: SourceRef;
+  excerpt: string;
+  why: string;
+  score: number;
+  outputId?: string;
+  evidenceId?: string;
+  lines?: string;
+}
+export interface BatchQueryAnswer {
+  query: string;
+  status: "answered" | "no_match";
+  summary: string;
+  matches: BatchQueryMatch[];
+}
+export interface BatchRoutedResult extends RoutedResultBase {
+  summary: string;
+  concurrency: number;
+  stepCount: number;
+  okCount: number;
+  failedCount: number;
+  steps: BatchStepRoutedResult[];
+  queries?: BatchQueryAnswer[];
+}
+export interface FailureRoutedResult extends RoutedResultBase {
+  outputId?: string;
+}
+export type RoutedResult =
+  | RetrievalRoutedResult
+  | CommandRoutedResult
+  | ObservedRoutedResult
+  | TransformRoutedResult
+  | BatchRoutedResult
+  | FailureRoutedResult;
+export interface LineByteCounts {
+  lines: number;
+  bytes: number;
+}
+export interface CommandOutputPaths {
+  meta: string;
+  stdout: string;
+  stderr: string;
+  combined: string;
+}
+export interface OutputFingerprints {
+  exactSha256: string;
+  normalizedSha256: string;
+  commandFingerprintSha256?: string;
+}
+export interface VaultRecordBase {
+  outputId: string;
+  recordId: string;
+  objectId: string;
+  createdAt: string;
+  paths: {
+    meta: string;
+  };
+  decisionIds: string[];
+  producer: ProducerDescriptor;
+  persistence: EvidencePersistence;
+  lineage?: EvidenceLineage;
+  contentHashSha256: string;
+  fingerprints?: OutputFingerprints;
+  retention?: VaultRetentionPolicy;
+  expiresAt?: string;
+}
+export interface CommandOutputRecord extends VaultRecordBase {
+  kind: "command";
+  command: string | readonly string[];
+  executionStatus: ExecutionStatus;
+  exitCode: number | null;
+  paths: CommandOutputPaths;
+  lineCounts: {
+    stdout: number;
+    stderr: number;
+    combined: number;
+  };
+  byteCounts: {
+    stdout: number;
+    stderr: number;
+    combined: number;
+  };
+  hashes: {
+    stdoutSha256?: string;
+    stderrSha256?: string;
+    combinedSha256?: string;
+  };
+  fingerprints: OutputFingerprints & {
+    commandFingerprintSha256: string;
+  };
+  cwd?: string;
+  durationMs?: number;
+}
+export interface TextOutputRecord extends VaultRecordBase {
+  kind: "text";
+  sourceKind: "native" | "script" | "mcp" | "web" | "fetch" | "code_search" | "transform" | "other";
+  paths: {
+    meta: string;
+    raw: string;
+  };
+  lineCounts: {
+    raw: number;
+  };
+  byteCounts: {
+    raw: number;
+  };
+  hashes: {
+    rawSha256?: string;
+  };
+  fingerprints: OutputFingerprints;
+}
+export interface RepoFileReferenceRecord extends VaultRecordBase {
+  kind: "repo-file";
+  path: string;
+  paths: {
+    meta: string;
+  };
+  hashSha256?: string;
+}
+export interface MetadataOutputRecord extends VaultRecordBase {
+  kind: "metadata";
+  sourceKind: TextOutputRecord["sourceKind"];
+  paths: {
+    meta: string;
+  };
+  lineCounts: {
+    raw: number;
+  };
+  byteCounts: {
+    raw: number;
+  };
+  hashes: {
+    rawSha256?: string;
+  };
+  metadata?: Record<string, unknown>;
+}
+export type VaultRecord = CommandOutputRecord | TextOutputRecord | RepoFileReferenceRecord | MetadataOutputRecord;
+export interface SessionIndexEntry {
+  outputId: string;
+  recordId?: string;
+  objectId: string;
+  kind: VaultRecord["kind"];
+  createdAt: string;
+  producer?: ProducerDescriptor;
+  persistence?: EvidencePersistence;
+  lineage?: EvidenceLineage;
+  executionStatus?: ExecutionStatus;
+  fingerprints?: OutputFingerprints;
+}
+export interface VaultSessionIndex {
+  version: 1;
+  sessionId: string;
+  createdAt: string;
+  updatedAt: string;
+  outputs: string[];
+  records: Record<string, SessionIndexEntry>;
+  successful: string[];
+  failed: string[];
+  timedOut: string[];
+  cancelled: string[];
+}
+export interface DecisionRecord {
+  decisionId: string;
+  createdAt: string;
+  route: RouteKind;
+  preserve: PreserveMode;
+  reason: string;
+  source?: SourceRef;
+  outputId?: string;
+  evidenceIds?: string[];
+}
+export interface RouterThresholds {
+  largeOutputBytes: number;
+  largeOutputLines: number;
+}
+export type VaultRetentionPolicy =
+  | {
+      strategy: "ttl";
+      ttlDays: number;
+    }
+  | {
+      strategy: "manual";
+    };
+export interface RouterVaultConfig {
+  root: string;
+  retention?: VaultRetentionPolicy;
+}
+export interface RouterHints {
+  generatedPathGlobs?: string[];
+  noisyCommandPatterns?: string[];
+}
+export interface RouterConfig {
+  enabled: boolean;
+  profile: OutputRouterProfile;
+  postToolRouting: PostToolRoutingMode;
+  storagePolicy: StoragePolicyMode;
+  thresholds: RouterThresholds;
+  vault: RouterVaultConfig;
+  hints?: RouterHints;
+}
+export interface ObservedRoutingProducerConfig {
+  enabled: boolean;
+  persistence: ObservedRoutingPersistenceMode;
+}
+export interface ObservedRoutingMcpConfig {
+  servers: Record<string, ObservedRoutingProducerConfig>;
+}
+export interface ObservedRoutingConfig {
+  enabled: boolean;
+  onRoutingFailure: ObservedRoutingFailureMode;
+  mcp: ObservedRoutingMcpConfig;
+  web: ObservedRoutingProducerConfig;
+  fetch: ObservedRoutingProducerConfig;
+  codeSearch: ObservedRoutingProducerConfig;
+}
+export type ScriptTransformLanguage = "javascript" | "python" | "jq";
+export type ScriptTransformNetworkPolicy = "off";
+export type ScriptTransformSandboxMode = "auto";
+export type ScriptTransformRawScriptPersistence = "disabled";
+export type ProcessingScriptPolicy = "sandboxed" | "unsafe-unsandboxed";
+export interface ScriptTransformLimits {
+  timeoutMs: number;
+  maxInputBytes: number;
+  maxOutputBytes: number;
+}
+export interface ScriptTransformConfig {
+  enabled: boolean;
+  sandbox: ScriptTransformSandboxMode;
+  languages: ScriptTransformLanguage[];
+  network: ScriptTransformNetworkPolicy;
+  limits: ScriptTransformLimits;
+  rawScriptPersistence: ScriptTransformRawScriptPersistence;
+}
+export interface ProcessingUnsafeUnsandboxedConfig {
+  enabled: boolean;
+}
+export interface LocalProcessingConfig {
+  unsafeUnsandboxed: ProcessingUnsafeUnsandboxedConfig;
+}
+export interface LocalFreeflowConfig {
+  processing: LocalProcessingConfig;
+}
+export interface FreeflowConfig {
+  outputRouter: RouterConfig;
+  observedRouting: ObservedRoutingConfig;
+  scriptTransform: ScriptTransformConfig;
+}

package/router/dist/config/types.js

@@ -0,0 +1,41 @@
+export const PRESERVE_MODES = ["summary", "important", "full"];
+export const RETRIEVAL_ACTIONS = ["query", "locate", "get", "retrieve", "expand", "explain"];
+export const TOOL_STATUSES = ["ok", "error"];
+export const EXECUTION_STATUSES = ["success", "failed", "timed_out", "cancelled"];
+export const ROUTING_STATUSES = ["routed", "passed_through", "partial", "failed"];
+export const ROUTE_KINDS = ["retrieve", "run", "transform", "batch", "observed", "safety-net", "pass-through"];
+export const BATCH_STEP_KINDS = ["run", "search"];
+export const PRODUCER_KINDS = [
+  "command",
+  "script",
+  "native",
+  "repo",
+  "web",
+  "fetch",
+  "code_search",
+  "mcp",
+  "transform",
+  "other",
+];
+export const PERSISTENCE_STATUSES = ["vaulted", "redacted", "metadata_only", "not_persisted"];
+export const RECOVERABILITY_MODES = ["exact", "redacted", "metadata_only", "none"];
+export const ROUTER_FAILURE_KINDS = [
+  "adapter_unavailable",
+  "storage_failure",
+  "observed_routing_failure",
+  "script_transform_disabled",
+  "transform_source_unavailable",
+  "transform_validation_failure",
+  "transform_execution_failure",
+];
+export const FAILURE_EXECUTION_STATUSES = ["unavailable", "unsupported", "rejected", "failed", "partial"];
+export const EVIDENCE_WINDOWS = ["exact", "small", "lines_30", "lines_80", "section", "full"];
+export const OUTPUT_STREAMS = ["stdout", "stderr", "combined", "raw"];
+export const POST_TOOL_ROUTING_MODES = ["off", "safety-net", "strict"];
+export const OUTPUT_ROUTER_PROFILES = ["standard"];
+export const STORAGE_POLICY_MODES = ["store-everything", "hybrid-dedupe"];
+export const OBSERVED_ROUTING_FAILURE_MODES = ["fail-open"];
+export const OBSERVED_ROUTING_PERSISTENCE_MODES = ["exact", "metadata-only", "none"];
+export const RESERVED_OBSERVED_ROUTING_PERSISTENCE_MODES = ["redacted"];
+export const OBSERVED_PRODUCER_RISK_CLASSES = ["read", "write", "unknown"];
+export const OBSERVED_PRODUCER_RISK_SOURCES = ["configured", "mcp_annotation", "manifest", "heuristic", "unknown"];

package/router/dist/evidence/bounded-evidence.d.ts

@@ -0,0 +1,40 @@
+import type { EvidenceWindow } from "../config/types.js";
+export interface LineRange {
+  start: number;
+  end: number;
+}
+export interface BoundedEvidenceCaps {
+  queryExcerptMaxBytes: number;
+  linePreviewMaxBytes: number;
+  expandLines30MaxBytes: number;
+  expandLines30MaxLines: number;
+  expandLines80MaxBytes: number;
+  expandLines80MaxLines: number;
+  exactChunkMaxBytes: number;
+}
+export interface BuildBoundedExcerptOptions {
+  lines: readonly string[];
+  range: LineRange;
+  window: EvidenceWindow;
+  caps: BoundedEvidenceCaps;
+  exactNormalizedPhrase?: string;
+}
+export interface BoundedExcerpt {
+  range: LineRange;
+  linesLabel: string;
+  excerpt: string;
+  truncatedByLineCap: boolean;
+  truncatedByByteCap: boolean;
+}
+export interface BoundedEdgeChunk {
+  range: LineRange;
+  linesLabel: string;
+  edge: "head" | "tail";
+  excerpt: string;
+}
+export declare function buildBoundedEdgeChunks(options: {
+  lines: readonly string[];
+  range: LineRange;
+  caps: BoundedEvidenceCaps;
+}): BoundedEdgeChunk[];
+export declare function buildBoundedExcerpt(options: BuildBoundedExcerptOptions): BoundedExcerpt;