rax-flow-core 0.1.0

package/src/plugins/long-term-memory-plugin.ts

@@ -0,0 +1,72 @@
+import { MemoryManager } from "../memory/memory-manager.js";
+import { IEmbeddingProvider, MemoryDocument, AgentInput, AgentOutput, WorkflowNode } from "../types/contracts.js";
+import { RaxPlugin } from "./plugin-system.js";
+
+/**
+ * LongTermMemoryPlugin enables QSGM (Quantum Semantic Graph Memory) by
+ * retrieving relevant past execution data using hybrid graph/vector navigation.
+ */
+export class LongTermMemoryPlugin implements RaxPlugin {
+    public name = "long-term-memory";
+
+    constructor(
+        private memoryManager: MemoryManager,
+        private embeddingProvider: IEmbeddingProvider
+    ) { }
+
+    /**
+     * Called before an agent executes.
+     * Uses Quantum Semantic Graph Memory to retrieve deep context.
+     */
+    async beforeNode({ input }: { node: WorkflowNode; input: AgentInput }): Promise<void> {
+        try {
+            const { vectors } = await this.embeddingProvider.embed([input.userPrompt]);
+            if (!vectors || vectors.length === 0) return;
+
+            const memoryText = await this.memoryManager.getQuantumContext(vectors[0], 3);
+
+            if (memoryText) {
+                // Inject the retrieved knowledge into artifacts for the agent to pick up
+                input.artifacts = {
+                    ...(input.artifacts || {}),
+                    _longTermMemory: memoryText,
+                };
+            }
+        } catch (err) {
+            console.warn("[LongTermMemoryPlugin] Retrieval failed:", err);
+        }
+    }
+
+    /**
+     * Called after an agent finishes.
+     * Persists results into both Vector and Graph stores.
+     */
+    async afterNode({ node, input, output }: { node: WorkflowNode; input: AgentInput; output: AgentOutput }): Promise<void> {
+        if (output.success && output.data && Object.keys(output.data).length > 0) {
+            try {
+                const textToEmbed = `Context: ${input.userPrompt}\nAction: ${node.id} (${node.agent})\nKnowledge: ${JSON.stringify(output.data)}`;
+                const { vectors } = await this.embeddingProvider.embed([textToEmbed]);
+
+                if (!vectors || vectors.length === 0) return;
+
+                const doc: MemoryDocument = {
+                    id: `mem_${Date.now()}_${Math.random().toString(36).substring(7)}`,
+                    text: textToEmbed,
+                    metadata: {
+                        taskId: input.taskId,
+                        nodeId: node.id,
+                        agent: node.agent,
+                        timestamp: new Date().toISOString()
+                    },
+                    timestamp: Date.now()
+                };
+
+                // In a workflow, we can link nodes if we track the previous node execution.
+                // For simplicity, we just add it to the manager.
+                await this.memoryManager.remember(doc, vectors[0]);
+            } catch (err) {
+                console.warn("[LongTermMemoryPlugin] Memorization failed:", err);
+            }
+        }
+    }
+}

package/src/plugins/plugin-system.ts

@@ -0,0 +1,34 @@
+import { AgentInput, AgentOutput, WorkflowNode } from "../types/contracts.js";
+
+export interface RaxPlugin {
+  name: string;
+  setup?(): Promise<void> | void;
+  beforeNode?(params: { node: WorkflowNode; input: AgentInput }): Promise<void> | void;
+  afterNode?(params: { node: WorkflowNode; input: AgentInput; output: AgentOutput }): Promise<void> | void;
+}
+
+export class PluginSystem {
+  private readonly plugins: RaxPlugin[] = [];
+
+  register(plugin: RaxPlugin): void {
+    this.plugins.push(plugin);
+  }
+
+  async initialize(): Promise<void> {
+    for (const plugin of this.plugins) {
+      await plugin.setup?.();
+    }
+  }
+
+  async runBeforeNode(params: { node: WorkflowNode; input: AgentInput }): Promise<void> {
+    for (const plugin of this.plugins) {
+      await plugin.beforeNode?.(params);
+    }
+  }
+
+  async runAfterNode(params: { node: WorkflowNode; input: AgentInput; output: AgentOutput }): Promise<void> {
+    for (const plugin of this.plugins) {
+      await plugin.afterNode?.(params);
+    }
+  }
+}

package/src/recovery/error-recovery.ts

@@ -0,0 +1,23 @@
+export interface RecoveryDecision {
+  retry: boolean;
+  escalate: boolean;
+  reason: string;
+}
+
+export class ErrorRecoverySystem {
+  decide(params: {
+    retries: number;
+    maxRetries: number;
+    confidence: number;
+    minConfidence: number;
+    schemaErrors: string[];
+  }): RecoveryDecision {
+    if (params.schemaErrors.length > 0 && params.retries < params.maxRetries) {
+      return { retry: true, escalate: false, reason: "schema_invalid_retry" };
+    }
+    if (params.confidence < params.minConfidence) {
+      return { retry: false, escalate: true, reason: "low_confidence_escalate" };
+    }
+    return { retry: false, escalate: false, reason: "accept" };
+  }
+}

package/src/runtime/concurrency-scheduler.ts

@@ -0,0 +1,18 @@
+export async function runWithConcurrency<T>(tasks: Array<() => Promise<T>>, maxParallel: number): Promise<T[]> {
+  if (tasks.length === 0) return [];
+  const limit = Math.max(1, maxParallel);
+  const results: T[] = new Array(tasks.length);
+  let nextIndex = 0;
+
+  async function worker(): Promise<void> {
+    while (nextIndex < tasks.length) {
+      const current = nextIndex;
+      nextIndex += 1;
+      results[current] = await tasks[current]();
+    }
+  }
+
+  const workers = Array.from({ length: Math.min(limit, tasks.length) }, () => worker());
+  await Promise.all(workers);
+  return results;
+}

package/src/runtime/runtime-events.ts

@@ -0,0 +1,27 @@
+import { EventEmitter } from "node:events";
+import { ExecutionMetrics, WorkflowGraph } from "../types/contracts.js";
+
+export type RuntimeEvent =
+  | { type: "run_start"; taskId: string; workflow?: WorkflowGraph }
+  | { type: "graph_ready"; taskId: string; workflow: WorkflowGraph }
+  | { type: "node_start"; nodeId: string; agent: string; retry: number }
+  | { type: "node_awaiting_approval"; taskId: string; nodeId: string; agent: string; data: any }
+
+  | { type: "node_end"; nodeId: string; agent: string; success: boolean; confidence: number; retry: number; costUsd?: number; usage?: { promptTokens: number; completionTokens: number; totalTokens: number } }
+  | { type: "node_error"; nodeId: string; agent: string; message: string; retry: number }
+  | { type: "audit_record"; taskId: string; nodeId?: string; action?: string; allowed?: boolean; violations?: any[]; score?: any; mutation?: any }
+  | { type: "run_end"; taskId: string; metrics: ExecutionMetrics };
+
+
+export class RuntimeEventBus {
+  private readonly emitter = new EventEmitter();
+
+  emit(event: RuntimeEvent): void {
+    this.emitter.emit("event", event);
+  }
+
+  onEvent(handler: (event: RuntimeEvent) => void): () => void {
+    this.emitter.on("event", handler);
+    return () => this.emitter.off("event", handler);
+  }
+}

package/src/types/contracts.ts

@@ -0,0 +1,159 @@
+export type Intent =
+  | "brainstorm"
+  | "spec"
+  | "architecture"
+  | "plan"
+  | "generate_code"
+  | "test"
+  | "fix"
+  | "optimize"
+  | "document"
+  | "benchmark";
+
+export type RiskFlag = "schema_drift" | "hallucination" | "high_cost" | "security" | "latency";
+
+export interface AgentInput {
+  taskId: string;
+  userPrompt: string;
+  context?: Record<string, unknown>;
+  artifacts?: Record<string, unknown>;
+}
+
+export interface AgentOutput<TData = Record<string, unknown>> {
+  agent: string;
+  success: boolean;
+  confidence: number;
+  risks: RiskFlag[];
+  logs: string[];
+  data: TData;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  costUsd?: number;
+}
+
+export interface RoutedPlan {
+  intent: Intent;
+  workflowId: string;
+  parallelizable: boolean;
+  escalationPolicy: {
+    maxFixLoops: number;
+    lowConfidenceThreshold: number;
+    escalateTo: string[];
+  };
+}
+
+export interface ProviderCallOptions {
+  model?: string;
+  temperature?: number;
+  maxTokens?: number;
+  metadata?: Record<string, string>;
+}
+
+export interface ModelResponse<T = unknown> {
+  provider: string;
+  model: string;
+  latencyMs: number;
+  costUsd?: number;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  output: T;
+  raw?: unknown;
+}
+
+export interface IModelProvider {
+  callModel(prompt: string, options?: ProviderCallOptions): Promise<ModelResponse<string>>;
+  callStructured<T>(prompt: string, schema: object, options?: ProviderCallOptions): Promise<ModelResponse<T>>;
+  healthCheck(): Promise<boolean>;
+}
+
+export interface AgentDefinition {
+  name: string;
+  role: string;
+  activationWhen: string;
+  inputSchema: object;
+  outputSchema: object;
+  run(input: AgentInput): Promise<AgentOutput>;
+}
+
+export interface WorkflowNode {
+  id: string;
+  agent: string;
+  dependsOn: string[];
+  requireApproval?: boolean;
+}
+
+
+export interface WorkflowGraph {
+  id: string;
+  nodes: WorkflowNode[];
+}
+
+export interface ExecutionMetrics {
+  taskId: string;
+  intent: Intent;
+  confidence: number;
+  retries: number;
+  escalations: number;
+  totalLatencyMs: number;
+  totalCostUsd: number;
+  humanInterventionRequired: boolean;
+}
+
+// --- Memory & RAG ---
+
+export interface EmbeddingResponse {
+  vectors: number[][];
+  model: string;
+  usage: { totalTokens: number };
+}
+
+export interface IEmbeddingProvider {
+  embed(texts: string[]): Promise<EmbeddingResponse>;
+}
+
+export interface MemoryDocument {
+  id: string;
+  text: string;
+  metadata: Record<string, unknown>;
+  timestamp: number;
+}
+
+export interface SearchResult extends MemoryDocument {
+  score: number;
+}
+
+export interface IVectorStore {
+  add(documents: MemoryDocument[], vectors: number[][]): Promise<void>;
+  search(queryVector: number[], limit?: number): Promise<SearchResult[]>;
+  clear(): Promise<void>;
+  delete?(docIds: string[]): Promise<void>;
+}
+
+// --- Governance & Audit ---
+
+export interface PolicyViolation {
+  policy: string;
+  severity: "low" | "medium" | "high" | "critical";
+  message: string;
+}
+
+export interface PolicyDecision {
+  allowed: boolean;
+  violations: PolicyViolation[];
+}
+
+export interface AuditRecord {
+  timestamp: number;
+  taskId: string;
+  nodeId?: string;
+  action: string;
+  decision: PolicyDecision;
+  metadata: Record<string, unknown>;
+}
+

package/src/validator/structured-output-validator.ts

@@ -0,0 +1,20 @@
+import Ajv, { ErrorObject } from "ajv";
+
+export class StructuredOutputValidator {
+  private readonly ajv: any = new (Ajv as any)({ allErrors: true, strict: false });
+
+  validate<T>(schema: object, payload: unknown): { ok: boolean; isValid: boolean; value?: T; errors: string[] } {
+    const validateFn = this.ajv.compile(schema);
+    const ok = validateFn(payload);
+    return {
+      ok: Boolean(ok),
+      isValid: Boolean(ok),
+      value: ok ? (payload as T) : undefined,
+      errors: (validateFn.errors ?? []).map((e: ErrorObject) => {
+        const path = e.instancePath || "/";
+        const field = path.split("/").pop() || path;
+        return `${field} ${e.message || "invalid"}`;
+      })
+    };
+  }
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "src/**/*.test.ts",
+    "tests/**/*"
+  ]
+}