rax-flow 0.1.0

package/src/install.ts

@@ -0,0 +1,118 @@
+import { mkdir, writeFile, access, copyFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { execSync } from "node:child_process";
+import path from "node:path";
+import os from "node:os";
+import { c } from "./styles.js";
+
+interface InstallOptions {
+  cwd: string;
+  openUi: boolean;
+  autoConfirm?: boolean;
+}
+
+async function detectBridges(): Promise<string[]> {
+  const candidates = [
+    { id: "claude-code", cmd: "claude-code --version" },
+    { id: "codex", cmd: "codex --version" },
+    { id: "opencode", cmd: "opencode --version" },
+    { id: "kilo", cmd: "kilo --version" }
+  ];
+
+  const detected: string[] = [];
+  for (const tool of candidates) {
+    try {
+      execSync(tool.cmd, { stdio: "ignore" });
+      detected.push(tool.id);
+    } catch {
+      // Not in path
+    }
+  }
+  return detected;
+}
+
+async function ensureRaxrc(targetDir: string, detectedBridge?: string): Promise<string> {
+  const file = path.join(targetDir, ".raxrc");
+  const body = {
+    version: 1,
+    defaultProvider: detectedBridge ? "host" : "openai",
+    strongProvider: "openai",
+    providers: {
+      host: {
+        model: detectedBridge ?? "host-managed",
+        mode: "auto",
+        bridgeCommand: detectedBridge ?? "claude-code", // Store direct command if found
+        bridgeCommandEnv: "RAX_HOST_BRIDGE_COMMAND"
+      },
+      openai: { model: "gpt-4o", apiKeyEnv: "OPENAI_API_KEY" },
+      claude: { model: "claude-3-5-sonnet-latest", apiKeyEnv: "ANTHROPIC_API_KEY" }
+    },
+    privacyMode: true,
+    verifyFixLoops: 3
+  };
+  await writeFile(file, `${JSON.stringify(body, null, 2)}\n`, "utf8");
+  return file;
+}
+
+async function ensureExampleWorkflow(targetDir: string): Promise<string> {
+  const workflowsDir = path.join(targetDir, ".rax-flow", "workflows");
+  await mkdir(workflowsDir, { recursive: true });
+  const file = path.join(workflowsDir, "fullstack-feature.json");
+  const sample = {
+    id: "fullstack-feature",
+    nodes: [
+      { id: "analyze", agent: "IntentClassifierAgent", dependsOn: [] },
+      { id: "spec", agent: "SpecAgent", dependsOn: ["analyze"] },
+      { id: "implement", agent: "CodeGeneratorAgent", dependsOn: ["spec"] },
+      { id: "verify", agent: "ValidatorAgent", dependsOn: ["implement"] }
+    ]
+  };
+  await writeFile(file, `${JSON.stringify(sample, null, 2)}\n`, "utf8");
+  return file;
+}
+
+async function validateEnvironment(): Promise<{ ok: boolean; missing: string[] }> {
+  const optional = ["OPENAI_API_KEY", "RAX_HOST_BRIDGE_COMMAND"];
+  const missing = optional.filter((k) => !process.env[k]);
+  return { ok: true, missing };
+}
+
+export async function runInstall(options: InstallOptions): Promise<number> {
+  console.log(c.blue("RAX-FLOW Installer - Professional Setup"));
+
+  console.log("- Scanning for local coding tools...");
+  const detected = await detectBridges();
+  if (detected.length > 0) {
+    console.log(c.green(`  [OK] Detected: ${detected.join(", ")}`));
+  } else {
+    console.log(c.yellow("  [!] No local coding tools (Claude Code/Codex) detected in PATH."));
+  }
+
+  const primaryBridge = detected[0];
+  const raxrc = await ensureRaxrc(options.cwd, primaryBridge);
+  const workflow = await ensureExampleWorkflow(options.cwd);
+
+  console.log(c.green(`- Project Initialized: ${raxrc}`));
+  console.log(c.green(`- Default Blueprint Created: ${workflow}`));
+
+  const env = await validateEnvironment();
+  if (env.missing.length > 0) {
+    console.log(c.yellow(`- Note: Optional env vars missing: ${env.missing.join(", ")}`));
+  }
+
+  const localHome = path.join(os.homedir(), ".rax-flow");
+  await mkdir(localHome, { recursive: true });
+
+  console.log("\n" + c.blue("--- Zero-Error Compliance Checklist ---"));
+  console.log(c.green("✓ Host Bridge Architecture: Scalable & Compliant"));
+  console.log(c.green("✓ Dynamic Planner: Enabled (Self-Optimizing)"));
+  console.log(c.green("✓ Long-term Memory: Configured"));
+
+  console.log("\n" + c.yellow("Next Logical Steps:"));
+  console.log("1. Run `rax-flow doctor` to verify bridge connectivity.");
+  console.log("2. Launch a task: `rax-flow run --prompt \"Implement feature Y\" --stream`.");
+
+  console.log("\n" + c.green("RAX-FLOW is now the operational backbone of your CLI workflow."));
+  return 0;
+}
+

package/src/run.ts

@@ -0,0 +1,317 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import * as readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+import { CoreOrchestrator, WorkflowGraph } from "@rax-flow/core";
+import { buildOfficialAgentsRuntime } from "@rax-flow/agents";
+import { ClaudeAdapter, GenericRestAdapter, HostBridgeAdapter, OpenAIAdapter } from "@rax-flow/providers";
+import { WebSocketRelay } from "./ws-relay.js";
+import { c } from "./styles.js";
+
+interface RunOptions {
+  cwd: string;
+  prompt: string;
+  workflowPath?: string;
+  asJson?: boolean;
+  stream?: boolean;
+  maxParallel?: number;
+  noCachePersist?: boolean;
+  providerOverride?: string;
+  bridgeCommandOverride?: string;
+  ui?: boolean;
+  yolo?: boolean;
+}
+
+
+interface RaxConfig {
+  defaultProvider?: string;
+  strongProvider?: string;
+  providers?: {
+    host?: { model?: string; mode?: "auto" | "bridge-only" | "mock"; bridgeCommandEnv?: string; timeoutMs?: number };
+    openai?: { model?: string; apiKeyEnv?: string; baseUrl?: string };
+    claude?: { model?: string; apiKeyEnv?: string; baseUrl?: string };
+    rest?: { endpoint?: string; tokenEnv?: string; model?: string };
+  };
+}
+
+async function loadConfig(cwd: string): Promise<RaxConfig> {
+  const file = path.join(cwd, ".raxrc");
+  const raw = await readFile(file, "utf8");
+  return JSON.parse(raw) as RaxConfig;
+}
+
+async function loadWorkflow(cwd: string, workflowPath?: string): Promise<WorkflowGraph | undefined> {
+  const file = workflowPath
+    ? path.resolve(cwd, workflowPath)
+    : path.join(cwd, ".rax-flow", "workflows", "fullstack-feature.json");
+
+  try {
+    const raw = await readFile(file, "utf8");
+    return JSON.parse(raw) as WorkflowGraph;
+  } catch {
+    return undefined;
+  }
+}
+
+function createProviders(config: RaxConfig, bridgeCommandOverride?: string) {
+  const providers: Record<string, OpenAIAdapter | ClaudeAdapter | GenericRestAdapter | HostBridgeAdapter> = {};
+
+  const hostCfg = config.providers?.host;
+  const bridgeCommand = bridgeCommandOverride ?? process.env[hostCfg?.bridgeCommandEnv ?? "RAX_HOST_BRIDGE_COMMAND"];
+  providers.host = new HostBridgeAdapter({
+    model: hostCfg?.model ?? "host-managed",
+    mode: hostCfg?.mode ?? "auto",
+    command: bridgeCommand,
+    timeoutMs: hostCfg?.timeoutMs ?? 20000
+  });
+
+  const openaiKey = process.env[config.providers?.openai?.apiKeyEnv ?? "OPENAI_API_KEY"];
+  if (openaiKey) {
+    providers.openai = new OpenAIAdapter(openaiKey, config.providers?.openai?.baseUrl);
+  }
+
+  const claudeKey = process.env[config.providers?.claude?.apiKeyEnv ?? "ANTHROPIC_API_KEY"];
+  if (claudeKey) {
+    providers.claude = new ClaudeAdapter(claudeKey, config.providers?.claude?.baseUrl);
+  }
+
+  const restEndpoint = config.providers?.rest?.endpoint;
+  if (restEndpoint) {
+    const restToken = process.env[config.providers?.rest?.tokenEnv ?? "RAX_REST_TOKEN"];
+    providers.rest = new GenericRestAdapter(restEndpoint, restToken);
+  }
+
+  return providers;
+}
+
+function cachePath(cwd: string): string {
+  return path.join(cwd, ".rax-flow", "cache", "semantic-cache.json");
+}
+
+async function saveHistory(cwd: string, taskId: string, data: any) {
+  const dir = path.join(cwd, ".rax-flow", "history");
+  await mkdir(dir, { recursive: true });
+  const file = path.join(dir, `${taskId}.json`);
+  await writeFile(file, JSON.stringify(data, null, 2));
+}
+
+async function askApproval(nodeId: string, agent: string, data: any): Promise<{ approved: boolean; feedback?: string }> {
+  const rl = readline.createInterface({ input, output });
+  console.log(c.magenta("\n--- [HUMAN INTERVENTION REQUIRED] ---"));
+  console.log(c.cyan(`Step: ${nodeId} | Agent: ${agent}`));
+  console.log(c.white("Candidate Output Data:"));
+  console.log(JSON.stringify(data, null, 2));
+
+  const answer = await rl.question(c.yellow("\nApprove? [Y to accept, or type your feedback to reject/fix]: "));
+  rl.close();
+
+  if (answer.toLowerCase() === "y" || answer === "") {
+    return { approved: true };
+  } else {
+    return { approved: false, feedback: answer };
+  }
+}
+
+
+export async function runWorkflow(options: RunOptions): Promise<number> {
+  let config: RaxConfig;
+  try {
+    config = await loadConfig(options.cwd);
+  } catch {
+    console.error(c.red("Missing .raxrc. Run `rax-flow install` first."));
+    return 1;
+  }
+  const providers = createProviders(config, options.bridgeCommandOverride);
+  const selectedDefault = options.providerOverride ?? config.defaultProvider ?? "host";
+
+  // Pre-flight check: Ensure Zero-Error compliance for Bridge integration
+  if (selectedDefault === "host") {
+    const health = await providers.host.healthCheck();
+    if (!health) {
+      console.error(c.red(`[Error] Host Bridge connectivity failed.`));
+      console.error(c.yellow(`Check your .raxrc or set RAX_HOST_BRIDGE_COMMAND env var.`));
+      console.log("Tip: run `rax-flow doctor` for detailed diagnostics.");
+      return 1;
+    }
+  }
+
+  const selectedStrong = config.strongProvider ?? "host";
+
+
+  const agents = buildOfficialAgentsRuntime({
+    providers,
+    defaultProvider: selectedDefault,
+    strongProvider: selectedStrong,
+    providerModels: {
+      host: config.providers?.host?.model ?? "host-managed",
+      openai: config.providers?.openai?.model ?? "gpt-4.1-mini",
+      claude: config.providers?.claude?.model ?? "claude-3-5-sonnet-latest",
+      rest: config.providers?.rest?.model ?? "generic-llm"
+    }
+  });
+
+  const workflow = await loadWorkflow(options.cwd, options.workflowPath);
+  // Memory System: Quantum Semantic Graph Memory (QSGM)
+  const memoryDir = path.join(options.cwd, ".rax-flow", "memory");
+  const { LocalVectorStore, GraphMemory, MemoryManager } = await import("@rax-flow/core");
+
+  const vectorStore = new LocalVectorStore(path.join(memoryDir, "vector-index.json"));
+  await vectorStore.load();
+
+  const graphMemory = new GraphMemory(path.join(memoryDir, "graph-memory.json"));
+  await graphMemory.load();
+
+  const memoryManager = new MemoryManager(vectorStore, graphMemory);
+
+  const orchestrator = new CoreOrchestrator(providers, agents, { memory: memoryManager }, { maxParallel: options.maxParallel ?? 4, cacheTtlMs: 1000 * 60 * 60 * 24 });
+
+  // Governance System: Enterprise security & compliance
+  const { GovernancePlugin, PIIPolicy } = await import("@rax-flow/core");
+  const governancePlugin = new GovernancePlugin(
+    [new PIIPolicy()],
+    path.join(options.cwd, ".rax-flow", "audit"),
+    orchestrator.events
+  );
+  orchestrator.registerPlugin(governancePlugin);
+
+
+  // Register Memory Plugin if an embedding provider is available (OpenAI in this case)
+  if (providers.openai) {
+    const { LongTermMemoryPlugin } = await import("@rax-flow/core");
+    orchestrator.registerPlugin(new LongTermMemoryPlugin(memoryManager, providers.openai as any));
+  }
+
+
+
+  let relay: WebSocketRelay | undefined;
+
+  if (options.ui) {
+    relay = new WebSocketRelay(3002);
+    relay.start(orchestrator.events);
+  }
+
+  const persistentCacheFile = cachePath(options.cwd);
+  if (!options.noCachePersist) {
+    await orchestrator.loadCache(persistentCacheFile);
+  }
+
+  const sessionEvents: any[] = [];
+  orchestrator.onEvent(e => sessionEvents.push(e));
+
+  // Connect WebSocket relay resolutions to orchestrator
+  orchestrator.onEvent((event: any) => {
+    if (event.type === "INTERNAL_RESOLVE_APPROVAL") {
+      orchestrator.resolveApproval(event.taskId, event.nodeId, event.approved, event.feedback);
+    }
+  });
+
+  if (options.stream) {
+    orchestrator.onEvent((event) => {
+      if (event.type === "graph_ready") {
+        console.log(c.magenta(c.bold(`\n--- [DAG FLOW] ---`)));
+        const edgeCount = event.workflow.nodes.reduce((acc: number, n: any) => acc + (n.dependsOn?.length || 0), 0);
+        console.log(c.gray(`Tasks: ${event.workflow.nodes.length} | Edges: ${edgeCount}`));
+      }
+
+      if (event.type === "node_start") {
+        const retryPrefix = event.retry > 0 ? c.yellow(` (Retry ${event.retry})`) : "";
+        console.log(`${c.blue("◆")} ${c.bold(event.nodeId)}${retryPrefix} ${c.gray(`[${event.agent}]`)}`);
+      }
+
+      if (event.type === "node_awaiting_approval") {
+        if (options.yolo) {
+          orchestrator.resolveApproval(event.taskId, event.nodeId, true);
+        } else {
+          (async () => {
+            const { approved, feedback } = await askApproval(event.nodeId, event.agent, event.data);
+            orchestrator.resolveApproval(event.taskId, event.nodeId, approved, feedback);
+          })();
+        }
+      }
+
+      if (event.type === "node_end") {
+        const confColor = event.confidence >= 0.8 ? c.green : (event.confidence >= 0.6 ? c.yellow : c.red);
+        const icon = event.success ? c.green("✔") : c.red("✘");
+        console.log(`  ${icon} ${confColor(`conf: ${(event.confidence * 100).toFixed(0)}%`)} ${c.gray(`cost: $${(event.costUsd || 0).toFixed(5)}`)}`);
+      }
+
+      if (event.type === "node_error") {
+        console.log(`  ${c.red("!")} ${c.red(event.message)}`);
+      }
+
+      if (event.type === "audit_record" && event.mutation) {
+        console.log(c.magenta(`\n🧬 [Genetic Mutation Generated]`));
+        console.log(c.magenta(`   Reason: ${event.mutation.reason ?? "Optimization"}`));
+      }
+    });
+  }
+
+  const taskId = `task_${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+  const result = await orchestrator.run(
+    {
+      taskId,
+      userPrompt: options.prompt,
+      context: {
+        cli: true,
+        host: os.hostname()
+      }
+    },
+    workflow
+  );
+
+  if (relay) {
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+    relay.stop();
+  }
+
+  if (!options.noCachePersist) {
+    await orchestrator.saveCache(persistentCacheFile);
+  }
+
+  // Save to history
+  await saveHistory(options.cwd, taskId, {
+    taskId,
+    timestamp: Date.now(),
+    prompt: options.prompt,
+    result: result.result,
+    metrics: result.metrics,
+    workflow: result.workflow,
+    events: sessionEvents
+  });
+
+  if (options.asJson) {
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  // Final Summary Table
+  console.log(c.bold(c.cyan(`\n\n--- [RUN SUMMARY] ---`)));
+  const tableData = [
+    ["Task ID", taskId],
+    ["Main Agent", result.result.agent],
+    ["Status", result.result.success ? c.green("SUCCESS") : c.red("FAILED")],
+    ["Confidence", `${(result.result.confidence * 100).toFixed(1)}%`],
+    ["Retries", result.metrics.retries.toString()],
+    ["Escalations", result.metrics.escalations.toString()],
+    ["Latency", `${(result.metrics.totalLatencyMs / 1000).toFixed(2)}s`],
+    ["Total Cost", c.yellow(`$${(result.metrics.totalCostUsd || 0).toFixed(5)}`)]
+  ];
+
+  for (const [key, value] of tableData) {
+    console.log(`${c.bold(key.padEnd(15))} : ${value}`);
+  }
+
+  if (result.result.logs.length > 0) {
+    console.log(c.bold(`\nTrace Logs:`));
+    for (const line of result.result.logs.slice(-5)) {
+      console.log(c.gray(`  • ${line}`));
+    }
+    if (result.result.logs.length > 5) {
+      console.log(c.gray(`  ... and ${result.result.logs.length - 5} more lines.`));
+    }
+  }
+
+  return 0;
+}

package/src/styles.ts

@@ -0,0 +1,12 @@
+export const c = {
+  blue: (s: string) => `\u001b[34m${s}\u001b[0m`,
+  green: (s: string) => `\u001b[32m${s}\u001b[0m`,
+  yellow: (s: string) => `\u001b[33m${s}\u001b[0m`,
+  red: (s: string) => `\u001b[31m${s}\u001b[0m`,
+  magenta: (s: string) => `\u001b[35m${s}\u001b[0m`,
+  cyan: (s: string) => `\u001b[36m${s}\u001b[0m`,
+  white: (s: string) => `\u001b[37m${s}\u001b[0m`,
+  gray: (s: string) => `\u001b[90m${s}\u001b[0m`,
+  bold: (s: string) => `\u001b[1m${s}\u001b[22m`
+};
+

package/src/vendor-manifests.ts

@@ -0,0 +1,113 @@
+import path from "node:path";
+import { HostTarget } from "./host-init-templates.js";
+
+export interface HostManifestModel {
+  version: number;
+  target: HostTarget;
+  title: string;
+  autoInjectMode: "native" | "scripted" | "manual";
+  bridgeCommand: string;
+  quickCommands: string[];
+  sessionEntryExamples: string[];
+  task: string | null;
+  files: {
+    bootstrapPrompt: string;
+    instructions: string;
+    bridgeAdapter: string;
+    bridgeRuntimeConfig: string;
+    bridgeSmokeTest: string;
+    vendorManifest: string;
+  };
+}
+
+function toRelative(baseDir: string, file: string): string {
+  const rel = path.relative(baseDir, file);
+  return rel.length > 0 ? rel : path.basename(file);
+}
+
+function buildClaudeManifest(baseDir: string, manifest: HostManifestModel) {
+  return {
+    schema: "rax.vendor.claude-code.v1",
+    session: {
+      initMessageFile: toRelative(baseDir, manifest.files.bootstrapPrompt),
+      mode: manifest.autoInjectMode,
+      bridgeCommand: manifest.bridgeCommand
+    },
+    orchestrator: {
+      tool: "rax-flow",
+      quickCommands: manifest.quickCommands
+    }
+  };
+}
+
+function buildCodexManifest(baseDir: string, manifest: HostManifestModel) {
+  return {
+    schema: "rax.vendor.codex.v1",
+    chat: {
+      bootstrapFile: toRelative(baseDir, manifest.files.bootstrapPrompt),
+      strategy: manifest.autoInjectMode
+    },
+    runtime: {
+      bridgeCommand: manifest.bridgeCommand,
+      taskContext: manifest.task
+    }
+  };
+}
+
+function buildOpenCodeManifest(baseDir: string, manifest: HostManifestModel) {
+  return {
+    schema: "rax.vendor.opencode.v1",
+    integration: {
+      startupPromptFile: toRelative(baseDir, manifest.files.bootstrapPrompt),
+      launchMode: manifest.autoInjectMode
+    },
+    orchestration: {
+      quickCommands: manifest.quickCommands,
+      bridgeCommand: manifest.bridgeCommand
+    }
+  };
+}
+
+function buildKiloManifest(baseDir: string, manifest: HostManifestModel) {
+  return {
+    schema: "rax.vendor.kilo.v1",
+    initializer: {
+      promptFile: toRelative(baseDir, manifest.files.bootstrapPrompt),
+      injectMode: manifest.autoInjectMode
+    },
+    runtime: {
+      bridgeCommand: manifest.bridgeCommand,
+      commandHints: manifest.sessionEntryExamples
+    }
+  };
+}
+
+function buildGenericManifest(baseDir: string, manifest: HostManifestModel) {
+  return {
+    schema: "rax.vendor.generic.v1",
+    bootstrap: {
+      file: toRelative(baseDir, manifest.files.bootstrapPrompt)
+    },
+    bridge: {
+      command: manifest.bridgeCommand,
+      mode: manifest.autoInjectMode
+    },
+    commands: manifest.quickCommands
+  };
+}
+
+export function generateVendorManifest(target: HostTarget, baseDir: string, manifest: HostManifestModel): Record<string, unknown> {
+  if (target === "claude-code") return buildClaudeManifest(baseDir, manifest);
+  if (target === "codex") return buildCodexManifest(baseDir, manifest);
+  if (target === "opencode") return buildOpenCodeManifest(baseDir, manifest);
+  if (target === "kilo") return buildKiloManifest(baseDir, manifest);
+  return buildGenericManifest(baseDir, manifest);
+}
+
+export function vendorManifestFilename(target: HostTarget): string {
+  if (target === "claude-code") return "vendor-claude-code.json";
+  if (target === "codex") return "vendor-codex.json";
+  if (target === "opencode") return "vendor-opencode.json";
+  if (target === "kilo") return "vendor-kilo.json";
+  return "vendor-generic.json";
+}