@williambeto/ai-workflow 2.2.7 → 2.3.1

package/src/core/request-router.js

@@ -0,0 +1,289 @@
+import path from "node:path";
+import fs from "node:fs";
+
+export class RequestRouter {
+  constructor({ cwd = process.cwd() } = {}) {
+    this.cwd = cwd;
+    this.validActors = ["Atlas", "Nexus", "Orion", "Astra", "Sage", "Phoenix"];
+  }
+
+  /**
+   * Understands and classifies a natural language request.
+   * @param {string} request 
+   * @returns {Object} RequestUnderstanding
+   */
+  understand(request) {
+    const text = String(request).trim();
+    if (!text) {
+      throw new Error("Cannot classify an empty request.");
+    }
+
+    // 1. Extract requested actor
+    let requestedActor = undefined;
+    let invalidActor = undefined;
+
+    // Direct addressing/reference pattern e.g., "Nexus, discover...", "ask Sage to..."
+    const askMatch = text.match(/\b(?:ask|use|tell|run|agent|actor)\s+([a-zA-Z]+)\b/i);
+    const addressMatch = text.match(/\b([a-zA-Z]+)\s*(?:,)/);
+
+    let candidate = null;
+    if (askMatch) {
+      candidate = askMatch[1];
+    } else if (addressMatch) {
+      candidate = addressMatch[1];
+    } else {
+      // General match for known actors
+      const knownMatch = text.match(/\b(Atlas|Nexus|Orion|Astra|Sage|Phoenix)\b/i);
+      if (knownMatch) {
+        candidate = knownMatch[1];
+      }
+    }
+
+    if (candidate) {
+      const normalized = candidate.charAt(0).toUpperCase() + candidate.slice(1).toLowerCase();
+      if (this.validActors.includes(normalized)) {
+        requestedActor = normalized;
+      } else {
+        invalidActor = candidate;
+      }
+    }
+
+    // 2. Extract operationType and requestedCapability
+    let operationType = "explain"; // default
+    let requestedCapability = undefined;
+
+    const capabilityMappings = [
+      { op: "discover", pattern: /\b(discover|inspect|map|scan|structure|architecture|repo|search|find)\b/i },
+      { op: "validate", pattern: /\b(validate|audit|review|check|verify|test)\b/i },
+      { op: "implement", pattern: /\b(implement|build|create|add|develop|write|change|modify)\b/i },
+      { op: "fix", pattern: /\b(fix|repair|correct|heal|solve|remediate)\b/i },
+      { op: "release", pattern: /\b(release|tag|prepare release)\b/i },
+      { op: "deploy", pattern: /\b(deploy|publish|push)\b/i }
+    ];
+
+    for (const mapping of capabilityMappings) {
+      const match = text.match(mapping.pattern);
+      if (match) {
+        operationType = mapping.op;
+        requestedCapability = match[1];
+        break;
+      }
+    }
+
+    // 3. Determine mutationIntent
+    const writePatterns = /\b(implement|build|fix|write|change|modify|create|add|refactor|update)\b/i;
+    const readOnlyPatterns = /\b(analyze|check|inspect|review|find|search|show|list|read|view|verify|validate|discover|map)\b/i;
+    
+    let mutationIntent = "write"; // default
+    if (/\b(read-only|readonly)\b/i.test(text)) {
+      mutationIntent = "readonly";
+    } else if (writePatterns.test(text)) {
+      mutationIntent = "write";
+    } else if (readOnlyPatterns.test(text) || ["discover", "validate"].includes(operationType)) {
+      mutationIntent = "readonly";
+    }
+
+    if (/\b(publish|release|deploy|push to npm|push to remote)\b/i.test(text)) {
+      mutationIntent = "publish";
+    }
+
+    // Determine Mode (needed for riskLevel mapping)
+    let mode = "standard";
+    if (/\b(deep|architectural|migration|major|full|\[deep\])\b/i.test(text)) {
+      mode = "full";
+    } else if (/\b(tiny|small|quick|simple|only\s+update|typo|comment|\[tiny\])\b/i.test(text)) {
+      mode = "quick";
+    }
+
+    // 4. Determine riskLevel
+    let riskLevel = "medium";
+    if (mode === "full" || mutationIntent === "publish" || /\b(bypass|force|direct)\b/i.test(text)) {
+      riskLevel = "high";
+    } else if (mode === "quick" || mutationIntent === "readonly") {
+      riskLevel = "low";
+    }
+
+    // 5. safetyConstraints and requiredEvidence
+    const safetyConstraints = [];
+    const requiredEvidence = [];
+
+    if (mutationIntent === "publish") {
+      safetyConstraints.push("Require release gate", "Awaiting user authorization");
+      requiredEvidence.push("release-decision", "tarball-hash");
+    } else if (mutationIntent === "write") {
+      safetyConstraints.push("Require branch gate", "No direct commits to main");
+      requiredEvidence.push("tests", "commit-hash");
+    } else {
+      safetyConstraints.push("No workspace mutations allowed");
+    }
+
+    if (/\b(bypass|force|direct)\b/i.test(text)) {
+      safetyConstraints.push("Block bypass attempts");
+    }
+
+    return {
+      rawRequest: text,
+      taskGoal: `Perform ${operationType} operation under ${mutationIntent} intent`,
+      requestedActor,
+      invalidActor,
+      requestedCapability,
+      operationType,
+      mutationIntent,
+      riskLevel,
+      requiredEvidence,
+      safetyConstraints
+    };
+  }
+
+  /**
+   * Decides the routing decision.
+   * @param {Object} understanding - RequestUnderstanding
+   * @returns {Object} RoutingDecision
+   */
+  route(understanding) {
+    const { requestedActor, invalidActor, operationType, mutationIntent, rawRequest } = understanding;
+
+    // 1. Check for bypass safety attempts
+    if (/\b(bypass safety|bypass validation|force push|directly to main|push to remote without gate)\b/i.test(rawRequest)) {
+      return {
+        requestedActor,
+        selectedActor: "Atlas",
+        operationType,
+        mutationIntent,
+        permissionDecision: "blocked",
+        reason: "Security block: Attempt to bypass safety or push directly is forbidden.",
+        workflowPath: ["Atlas"]
+      };
+    }
+
+    // 2. Check for invalid/ambiguous actor names in critical actions
+    if (invalidActor) {
+      if (["release", "deploy", "fix", "implement"].includes(operationType) || mutationIntent === "publish") {
+        return {
+          requestedActor: undefined,
+          selectedActor: "Atlas",
+          operationType,
+          mutationIntent,
+          permissionDecision: "blocked",
+          reason: `Security block: Request mentions invalid/unrecognized actor '${invalidActor}' for a critical operation.`,
+          workflowPath: ["Atlas"]
+        };
+      }
+    }
+
+    // 3. Permission matrix check
+    const PERMISSION_MATRIX = {
+      Atlas: {
+        allowedOperations: ["explain"],
+        allowedMutations: ["readonly"]
+      },
+      Nexus: {
+        allowedOperations: ["discover", "explain", "plan"],
+        allowedMutations: ["readonly", "write"]
+      },
+      Orion: {
+        allowedOperations: ["plan", "release", "deploy"],
+        allowedMutations: ["readonly", "write", "publish"]
+      },
+      Astra: {
+        allowedOperations: ["implement", "fix", "explain"],
+        allowedMutations: ["readonly", "write"]
+      },
+      Sage: {
+        allowedOperations: ["validate", "explain"],
+        allowedMutations: ["readonly"]
+      },
+      Phoenix: {
+        allowedOperations: ["fix"],
+        allowedMutations: ["readonly", "write"]
+      }
+    };
+
+    let selectedActor = undefined;
+    let permissionDecision = "allowed";
+    let reason = "Routed successfully.";
+    let workflowPath = ["Atlas"];
+
+    if (requestedActor) {
+      const perms = PERMISSION_MATRIX[requestedActor];
+      const isOpAllowed = perms.allowedOperations.includes(operationType);
+      const isMutationAllowed = perms.allowedMutations.includes(mutationIntent);
+
+      if (isOpAllowed && isMutationAllowed) {
+        selectedActor = requestedActor;
+      } else {
+        // Valid actor but unauthorized operation or mutation
+        if (mutationIntent === "publish") {
+          selectedActor = "Orion";
+          permissionDecision = "rerouted";
+          reason = `Rerouted: Requested actor '${requestedActor}' is not authorized to publish. Redirecting to Orion.`;
+        } else {
+          selectedActor = requestedActor;
+          permissionDecision = "blocked";
+          reason = `Blocked: Requested actor '${requestedActor}' does not have permission for operation '${operationType}' or mutation '${mutationIntent}'.`;
+        }
+      }
+    } else {
+      // Infer actor from operation, risk, capability
+      if (operationType === "discover") {
+        selectedActor = "Nexus";
+      } else if (operationType === "validate") {
+        selectedActor = "Sage";
+      } else if (operationType === "fix") {
+        selectedActor = "Phoenix";
+      } else if (operationType === "implement") {
+        selectedActor = "Astra";
+      } else if (operationType === "release" || operationType === "deploy") {
+        selectedActor = "Orion";
+      } else {
+        // Fallback for general explain/plan
+        selectedActor = mutationIntent === "write" ? "Astra" : "Atlas";
+      }
+    }
+
+    // Phoenix findings check: A fix request requires findings before Phoenix acts
+    if (selectedActor === "Phoenix") {
+      const requestPath = path.join(this.cwd, ".ai-workflow/remediation-request.json");
+      let hasFindings = false;
+      if (fs.existsSync(requestPath)) {
+        try {
+          const reqData = JSON.parse(fs.readFileSync(requestPath, "utf8"));
+          if (reqData.affectedChecks && reqData.affectedChecks.length > 0) {
+            hasFindings = true;
+          }
+        } catch {
+          // ignore
+        }
+      }
+      if (!hasFindings) {
+        permissionDecision = "blocked";
+        reason = "Blocked: Phoenix acts only with concrete findings and bounded remediation.";
+      }
+    }
+
+    if (selectedActor && !workflowPath.includes(selectedActor)) {
+      workflowPath.push(selectedActor);
+    }
+
+    // Atlas self-execution guard
+    if (selectedActor === "Atlas" && (requestedActor || ["discover", "validate", "fix", "release", "deploy"].includes(operationType))) {
+      permissionDecision = "blocked";
+      reason = "Atlas self-execution guard: Atlas cannot silently execute specialized actor or capability requests.";
+    }
+
+    // Sage and Phoenix revalidation loop path in full mode:
+    if (selectedActor === "Astra" && understanding.riskLevel === "high") {
+      workflowPath.push("Sage", "Phoenix", "Sage");
+    }
+
+    return {
+      requestedActor,
+      selectedActor,
+      operationType,
+      mutationIntent,
+      permissionDecision,
+      reason,
+      workflowPath
+    };
+  }
+}

package/src/core/runtime/opencode-adapter.js

@@ -1,4 +1,4 @@
-import { spawn, execSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import readline from "node:readline";
 
 /**
@@ -9,86 +9,194 @@ export class OpenCodeAdapter {
     this.cwd = cwd;
   }
 
+  /**
+   * Inspects the availability and capability of the OpenCode CLI.
+   * @returns {Promise<{available: boolean, supports: {run: boolean, formatJson: boolean, agent: boolean, model: boolean}}>}
+   */
+  async inspect() {
+    try {
+      const cliHelp = spawnSync("opencode", ["--help"], { encoding: "utf8" });
+      const runHelp = spawnSync("opencode", ["run", "--help"], { encoding: "utf8" });
+
+      const available = cliHelp.status === 0 && runHelp.status === 0;
+      if (!available) {
+        return {
+          available: false,
+          supports: { run: false, formatJson: false, agent: false, model: false }
+        };
+      }
+
+      return {
+        available: true,
+        supports: {
+          run: /\brun\b/.test(cliHelp.stdout),
+          formatJson: /--format/.test(runHelp.stdout),
+          agent: /--agent/.test(runHelp.stdout),
+          model: /--model/.test(runHelp.stdout),
+        }
+      };
+    } catch {
+      return {
+        available: false,
+        supports: { run: false, formatJson: false, agent: false, model: false }
+      };
+    }
+  }
+
   /**
    * Runs opencode with a prompt and options.
    * @param {string} message - The message prompt.
-   * @param {Object} options - CLI options (e.g. agent, model, dangerouslySkipPermissions).
-   * @returns {Promise<{success: boolean, commandsRun: string[], eventCount: number}>}
+   * @param {Object} options - CLI options (e.g. agent, model, readOnly).
+   * @returns {Promise<{success: boolean, commandsRun: string[], eventCount: number, error?: string}>}
    */
-  async execute(message, { agent = null, model = null, dangerouslySkipPermissions = false } = {}) {
-    return new Promise((resolve) => {
-      const args = ["run", message, "--format", "json"];
-      if (agent) {
-        args.push("--agent", agent);
-      }
-      if (model) {
-        args.push("--model", model);
-      }
-      if (dangerouslySkipPermissions) {
-        args.push("--dangerously-skip-permissions");
-      }
+  async execute(message, { agent = null, model = null, readOnly = false } = {}) {
+    const inspection = await this.inspect();
+    const isSpecializedAgent = agent && ["Nexus", "Orion", "Astra", "Sage", "Phoenix"].includes(agent);
 
-      console.log(`[RUNTIME] Delegating to OpenCode: opencode ${args.map(a => a.includes(" ") ? `"${a}"` : a).join(" ")}`);
+    if (!inspection.available) {
+      return {
+        success: false,
+        status: isSpecializedAgent ? "BLOCKED" : "FAILED",
+        commandsRun: [],
+        eventCount: 0,
+        error: "OpenCode CLI is not installed or not available in the system PATH.",
+        runtimeAgentRequested: agent || null,
+        runtimeAgentApplied: null,
+        runtimeAgentSupported: false,
+        runtimeAgentSelectionMode: isSpecializedAgent ? "explicit" : "default"
+      };
+    }
 
-      const child = spawn("opencode", args, {
-        cwd: this.cwd,
-        shell: true,
-        stdio: ["ignore", "pipe", "inherit"] // Inherit stderr to show warnings directly
-      });
+    if (isSpecializedAgent && !inspection.supports.agent) {
+      return {
+        success: false,
+        status: "BLOCKED",
+        error: `Requested runtime actor '${agent}' cannot be applied because this OpenCode runtime does not support --agent.`,
+        runtimeAgentRequested: agent,
+        runtimeAgentApplied: null,
+        runtimeAgentSupported: false,
+        runtimeAgentSelectionMode: "unsupported",
+        commandsRun: [],
+        eventCount: 0
+      };
+    }
 
-      const rl = readline.createInterface({
-        input: child.stdout,
-        terminal: false
-      });
+    const runInWorkspace = async (targetCwd) => {
+      return new Promise((resolve) => {
+        const args = ["run", message];
+        if (inspection.supports.formatJson) {
+          args.push("--format", "json");
+        }
+        if (isSpecializedAgent && inspection.supports.agent) {
+          args.push("--agent", agent);
+        }
+        if (model && inspection.supports.model) {
+          args.push("--model", model);
+        }
 
-      const commandsRun = [];
-      let eventCount = 0;
+        console.log(`[RUNTIME] Delegating to OpenCode: opencode ${args.map(a => a.includes(" ") ? `"${a}"` : a).join(" ")}`);
 
-      rl.on("line", (line) => {
-        const trimmed = line.trim();
-        if (!trimmed) return;
+        const child = spawn("opencode", args, {
+          cwd: targetCwd,
+          stdio: ["ignore", "pipe", "inherit"] // Inherit stderr to show warnings directly
+        });
 
-        try {
-          const event = JSON.parse(trimmed);
-          eventCount++;
+        const rl = readline.createInterface({
+          input: child.stdout,
+          terminal: false
+        });
 
-          // 1. Stream agent output text in real-time to user
-          if (event.type === "text" && event.part?.text) {
-            process.stdout.write(event.part.text);
-          }
+        const commandsRun = [];
+        let eventCount = 0;
+
+        rl.on("line", (line) => {
+          const trimmed = line.trim();
+          if (!trimmed) return;
+
+          try {
+            const event = JSON.parse(trimmed);
+            eventCount++;
 
-          // 2. Capture tool executions/commands
-          if (event.type === "step_start" && event.part?.toolCalls) {
-            for (const call of event.part.toolCalls) {
-              if (call.name === "run_command" && call.args?.CommandLine) {
-                commandsRun.push(call.args.CommandLine);
+            // 1. Stream agent output text in real-time to user
+            if (event.type === "text" && event.part?.text) {
+              process.stdout.write(event.part.text);
+            }
+
+            // 2. Capture tool executions/commands
+            if (event.type === "step_start" && event.part?.toolCalls) {
+              for (const call of event.part.toolCalls) {
+                if (call.name === "run_command" && call.args?.CommandLine) {
+                  commandsRun.push(call.args.CommandLine);
+                }
+                if (readOnly) {
+                  const name = call.name || "";
+                  const isWriteTool = name.startsWith("write_") || name.includes("write") || name.includes("replace") || name.includes("edit") || name.includes("delete") || name.includes("remove");
+                  let isDestructiveGit = false;
+                  if (name === "run_command" && call.args?.CommandLine) {
+                    const cmd = call.args.CommandLine;
+                    const destPattern = /\b(git\s+(commit|add|push|merge|reset|rm|branch|checkout|switch|stash|init)|touch|rm|mkdir|cp|mv|chmod|chown|tee|sed|awk)\b|>>|>/;
+                    if (destPattern.test(cmd)) {
+                      isDestructiveGit = true;
+                    }
+                  }
+                  if (isWriteTool || isDestructiveGit) {
+                    console.error(`\n[SECURITY WARNING] Read-only execution blocked attempt to write/modify workspace: tool '${name}' or command detected.`);
+                    child.kill();
+                    resolve({
+                      success: false,
+                      commandsRun,
+                      eventCount,
+                      error: `Read-only confinement violation: tool '${name}' or command attempted write/modify operation during read-only task.`,
+                      runtimeAgentRequested: agent || null,
+                      runtimeAgentApplied: null,
+                      runtimeAgentSupported: inspection.supports.agent,
+                      runtimeAgentSelectionMode: isSpecializedAgent ? "explicit" : "default"
+                    });
+                    return;
+                  }
+                }
               }
             }
+          } catch {
+            // If a line is not valid JSON (e.g. starting/finishing logs), print it directly
+            console.log(trimmed);
           }
-        } catch {
-          // If a line is not valid JSON (e.g. starting/finishing logs), print it directly
-          console.log(trimmed);
-        }
-      });
+        });
 
-      child.on("close", (code) => {
-        console.log("\n[RUNTIME] OpenCode finished execution.");
-        resolve({
-          success: code === 0,
-          commandsRun,
-          eventCount
+        child.on("close", (code) => {
+          console.log("\n[RUNTIME] OpenCode finished execution.");
+          resolve({
+            success: code === 0,
+            commandsRun,
+            eventCount,
+            runtimeAgentRequested: agent || null,
+            runtimeAgentApplied: isSpecializedAgent ? agent : null,
+            runtimeAgentSupported: inspection.supports.agent,
+            runtimeAgentSelectionMode: isSpecializedAgent ? "explicit" : "default"
+          });
         });
-      });
 
-      child.on("error", (err) => {
-        console.error(`\n[RUNTIME] Failed to launch opencode: ${err.message}`);
-        resolve({
-          success: false,
-          commandsRun,
-          eventCount: 0,
-          error: err.message
+        child.on("error", (err) => {
+          console.error(`\n[RUNTIME] Failed to launch opencode: ${err.message}`);
+          resolve({
+            success: false,
+            commandsRun,
+            eventCount: 0,
+            error: err.message,
+            runtimeAgentRequested: agent || null,
+            runtimeAgentApplied: null,
+            runtimeAgentSupported: inspection.supports.agent,
+            runtimeAgentSelectionMode: isSpecializedAgent ? "explicit" : "default"
+          });
         });
       });
-    });
+    };
+
+    if (readOnly) {
+      const { runInReadOnlyWorkspace } = await import("../workspace/read-only-workspace.js");
+      return runInReadOnlyWorkspace(this.cwd, runInWorkspace);
+    } else {
+      return runInWorkspace(this.cwd);
+    }
   }
 }

package/src/core/validation/evidence-collector.js

@@ -42,22 +42,45 @@ export class EvidenceCollector {
     if (task.presetStatus) {
       return { name: task.name, command: task.command, kind, status: task.presetStatus, exitCode: null, summary: task.summary, output: "" };
     }
+
+    let cmd = task.command;
+    let args = [];
+    if (Array.isArray(cmd)) {
+      const [c, ...a] = cmd;
+      cmd = c;
+      args = a;
+    } else if (typeof cmd === "string") {
+      const parts = cmd.split(/\s+/);
+      cmd = parts[0];
+      args = parts.slice(1);
+    }
+
     const isWin32 = process.platform === "win32";
     const isUncPath = typeof this.cwd === "string" && (this.cwd.startsWith("\\\\") || this.cwd.startsWith("//"));
-    const shellOption = isWin32 && isUncPath ? "powershell.exe" : true;
+    const shellOption = isWin32 && isUncPath ? "powershell.exe" : (isWin32 ? true : false);
 
-    const result = spawnSync(task.command, {
+    const result = spawnSync(cmd, args, {
       cwd: this.cwd,
       shell: shellOption,
       encoding: "utf8",
       timeout: this.timeout
     });
+
     let status = result.status === 0 ? "PASS" : "FAIL";
+    if (result.error) {
+      status = "FAIL";
+      if (result.error.code === "ETIMEDOUT") {
+        status = "BLOCKED";
+      }
+    }
+
     let summary = status === "PASS" ? "Command completed successfully." : "Command failed.";
     if (result.error?.code === "ETIMEDOUT") {
-      status = "BLOCKED";
       summary = `Command timed out after ${this.timeout / 1000}s.`;
+    } else if (result.error) {
+      summary = `Command execution error: ${result.error.message}`;
     }
+
     const rawOutput = `${result.stdout || ""}${result.stderr || ""}`.trim();
     const output = rawOutput.length > this.maxLogLength ? `${rawOutput.slice(0, this.maxLogLength)}\n... [TRUNCATED]` : rawOutput;
     return { name: task.name, command: task.command, kind, status, exitCode: result.status, signal: result.signal, summary, output };

package/src/core/validation/stack-detector.js

@@ -0,0 +1,65 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export class StackDetector {
+  constructor({ cwd = process.cwd() } = {}) {
+    this.cwd = cwd;
+  }
+
+  async detect() {
+    const stacks = [];
+
+    // 1. Node check
+    const packageJsonExists = await fs.access(path.join(this.cwd, "package.json")).then(() => true).catch(() => false);
+    if (packageJsonExists) {
+      stacks.push("node");
+    }
+
+    // 2. Python check
+    const pyprojectExists = await fs.access(path.join(this.cwd, "pyproject.toml")).then(() => true).catch(() => false) ||
+                             await fs.access(path.join(this.cwd, "requirements.txt")).then(() => true).catch(() => false) ||
+                             await fs.access(path.join(this.cwd, "setup.py")).then(() => true).catch(() => false) ||
+                             await fs.access(path.join(this.cwd, "Pipfile")).then(() => true).catch(() => false);
+    
+    let hasPythonFiles = pyprojectExists;
+    if (!hasPythonFiles) {
+      hasPythonFiles = await this.hasFileWithExtension(this.cwd, ".py");
+    }
+    if (hasPythonFiles) {
+      stacks.push("python");
+    }
+
+    // 3. PHP check
+    const composerExists = await fs.access(path.join(this.cwd, "composer.json")).then(() => true).catch(() => false);
+    let hasPhpFiles = composerExists;
+    if (!hasPhpFiles) {
+      hasPhpFiles = await this.hasFileWithExtension(this.cwd, ".php");
+    }
+    if (hasPhpFiles) {
+      stacks.push("php");
+    }
+
+    return stacks;
+  }
+
+  async hasFileWithExtension(dir, ext) {
+    try {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          if (["node_modules", "vendor", ".git", "dist", "build", ".cache"].includes(entry.name)) {
+            continue;
+          }
+          const subPath = path.join(dir, entry.name);
+          const found = await this.hasFileWithExtension(subPath, ext);
+          if (found) return true;
+        } else if (entry.isFile() && entry.name.endsWith(ext)) {
+          return true;
+        }
+      }
+    } catch {
+      // ignore
+    }
+    return false;
+  }
+}