@karajan-family/code 4.21.0

package/src/orchestrator/direct-actions.js

@@ -0,0 +1,217 @@
+// Direct actions: commands Karajan Brain can execute without invoking a full role.
+// Keeps the action catalog small, auditable, and safe.
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * @typedef {Object} DirectAction
+ * @property {string} type - action type identifier
+ * @property {Object} params - action-specific parameters
+ */
+
+/**
+ * @typedef {Object} ActionResult
+ * @property {boolean} ok
+ * @property {string} [output]
+ * @property {string} [error]
+ * @property {string} action
+ */
+
+const ALLOWED_COMMANDS = [
+  "npm install", "npm ci", "pnpm install", "yarn install",
+  "pip install -r requirements.txt", "poetry install",
+  "go mod download", "cargo fetch",
+  "bundle install", "composer install", "dotnet restore"
+];
+
+// KJC-BUG-0099: a dependency install must not be arbitrary code execution —
+// lifecycle hooks (postinstall & friends) run whatever the dependency ships.
+// The allow-list above names the INTENT; execution appends the ecosystem's
+// script-skipping flag. Ecosystems without package hooks run untouched.
+const HARDEN_FLAGS = {
+  npm: ["--ignore-scripts"],
+  pnpm: ["--ignore-scripts"],
+  yarn: ["--ignore-scripts"],
+  composer: ["--no-scripts", "--no-plugins"],
+};
+
+/**
+ * True when `target` resolves to a path inside `base` (or is `base` itself).
+ * Uses path.relative instead of a string prefix check: a naive
+ * `resolved.startsWith(base)` lets a sibling with a shared prefix slip through
+ * (base `/repo/app` would accept `/repo/app2`). Also rejects absolute paths
+ * pointing outside the project.
+ */
+function isInsideBase(target, base) {
+  const rel = path.relative(base, target);
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+/**
+ * Validate that a shell command is in the allow-list.
+ * Prevents arbitrary command execution.
+ */
+function isCommandAllowed(cmd) {
+  if (!cmd || typeof cmd !== "string") return false;
+  const tokens = cmd.trim().split(/\s+/);
+  return ALLOWED_COMMANDS.some(allowed => {
+    const allowedTokens = allowed.split(/\s+/);
+    return allowedTokens.every((t, i) => tokens[i] === t) && tokens.length === allowedTokens.length;
+  });
+}
+
+/**
+ * Execute an allowed shell command (install deps, etc.).
+ */
+async function runCommand({ cmd, cwd }) {
+  if (!isCommandAllowed(cmd)) {
+    return { ok: false, error: `Command not in allow-list: ${cmd}`, action: "run_command" };
+  }
+
+  try {
+    // Audit follow-up: was using execSync, which routes through /bin/sh.
+    // Even though `cmd` is allow-listed, defense-in-depth: switched to
+    // execFileSync with a tokenised arg array so no shell expansion at all.
+    const [program, ...args] = cmd.trim().split(/\s+/);
+    const output = execFileSync(program, [...args, ...(HARDEN_FLAGS[program] ?? [])], {
+      cwd: cwd || process.cwd(),
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 120_000
+    });
+    return { ok: true, output: output.trim(), action: "run_command" };
+  } catch (err) {
+    return { ok: false, error: err.message, action: "run_command" };
+  }
+}
+
+/**
+ * Create a file with given content (only if it doesn't exist).
+ */
+async function createFile({ filePath, content, cwd, overwrite = false }) {
+  try {
+    const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd || process.cwd(), filePath);
+
+    // Path traversal guard
+    const resolved = path.resolve(fullPath);
+    const base = path.resolve(cwd || process.cwd());
+    if (!isInsideBase(resolved, base)) {
+      return { ok: false, error: "Path traversal denied", action: "create_file" };
+    }
+
+    try {
+      await fs.access(fullPath);
+      if (!overwrite) {
+        return { ok: false, error: `File already exists: ${filePath}`, action: "create_file" };
+      }
+    } catch { /* file doesn't exist, proceed */ }
+
+    await fs.mkdir(path.dirname(fullPath), { recursive: true });
+    await fs.writeFile(fullPath, content || "", "utf8");
+    return { ok: true, output: `Created ${filePath}`, action: "create_file" };
+  } catch (err) {
+    return { ok: false, error: err.message, action: "create_file" };
+  }
+}
+
+/**
+ * Append entries to .gitignore (creates if missing, skips duplicates).
+ */
+async function updateGitignore({ entries, cwd }) {
+  if (!Array.isArray(entries) || entries.length === 0) {
+    return { ok: false, error: "No entries provided", action: "update_gitignore" };
+  }
+
+  try {
+    const gitignorePath = path.join(cwd || process.cwd(), ".gitignore");
+    let content = "";
+    try {
+      content = await fs.readFile(gitignorePath, "utf8");
+    } catch { /* will create */ }
+
+    const missing = entries.filter(e => !content.includes(e));
+    if (missing.length === 0) {
+      return { ok: true, output: "All entries already present", action: "update_gitignore" };
+    }
+
+    const append = (content && !content.endsWith("\n") ? "\n" : "") + missing.join("\n") + "\n";
+    await fs.appendFile(gitignorePath, append, "utf8");
+    return { ok: true, output: `Added: ${missing.join(", ")}`, action: "update_gitignore" };
+  } catch (err) {
+    return { ok: false, error: err.message, action: "update_gitignore" };
+  }
+}
+
+/**
+ * Stage files with git add.
+ */
+async function gitAdd({ files, cwd }) {
+  if (!Array.isArray(files) || files.length === 0) {
+    return { ok: false, error: "No files to add", action: "git_add" };
+  }
+
+  try {
+    // Reject shell metacharacters and anything that resolves outside the project.
+    const base = path.resolve(cwd || process.cwd());
+    for (const f of files) {
+      if (typeof f !== "string" || /[;&|`$]/.test(f) || !isInsideBase(path.resolve(base, f), base)) {
+        return { ok: false, error: `Invalid file path: ${f}`, action: "git_add" };
+      }
+    }
+    execFileSync("git", ["add", ...files], {
+      cwd: cwd || process.cwd(),
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return { ok: true, output: `Staged ${files.length} file(s)`, action: "git_add" };
+  } catch (err) {
+    return { ok: false, error: err.message, action: "git_add" };
+  }
+}
+
+const ACTION_HANDLERS = {
+  run_command: runCommand,
+  create_file: createFile,
+  update_gitignore: updateGitignore,
+  git_add: gitAdd
+};
+
+/**
+ * Execute a single direct action.
+ */
+export async function executeAction(action, { cwd } = {}) {
+  if (!action || typeof action !== "object") {
+    return { ok: false, error: "Invalid action", action: "unknown" };
+  }
+
+  const handler = ACTION_HANDLERS[action.type];
+  if (!handler) {
+    return { ok: false, error: `Unknown action type: ${action.type}`, action: action.type };
+  }
+
+  return handler({ ...action.params, cwd: cwd || action.params?.cwd });
+}
+
+/**
+ * Execute a list of actions in sequence. Stops on first failure unless continueOnError.
+ */
+export async function executeActions(actions, { cwd, continueOnError = false } = {}) {
+  const results = [];
+  for (const action of actions || []) {
+    const result = await executeAction(action, { cwd });
+    results.push(result);
+    if (!result.ok && !continueOnError) break;
+  }
+  return results;
+}
+
+/**
+ * Get list of allowed action types.
+ */
+export function getAllowedActionTypes() {
+  return Object.keys(ACTION_HANDLERS);
+}
+
+export { isCommandAllowed };

package/src/orchestrator/drivers/error-recovery.js

@@ -0,0 +1,287 @@
+/**
+ * Error-recovery driver — extracted from src/orchestrator/flow-runner.js
+ * in TSK-0335 (Oleada 3 of the v2.7.4 audit refactor).
+ *
+ * Five handlers that react to pipeline-level failure signals and decide
+ * whether to retry, pause, or escalate to Solomon:
+ *
+ *   - handleStandbyResult:            rate-limit / provider-outage →
+ *                                     Solomon decides skip/retry/wait/pause.
+ *   - emitSolomonAlerts:              forward Solomon-rules findings to
+ *                                     the progress stream.
+ *   - handleSolomonCheck:             evaluate Solomon-rules context,
+ *                                     escalate critical alerts (direct to
+ *                                     human without Brain, via Solomon
+ *                                     with Brain).
+ *   - checkSolomonCriticalAlerts:     non-Brain branch — ask the user
+ *                                     whether to continue/pause/stop on
+ *                                     critical alerts.
+ *   - handleReviewerRetryAndSolomon:  reviewer sub-loop limit → invoke
+ *                                     Solomon to resolve the stall.
+ *
+ * These were extracted verbatim; no behavior change. flow-runner.js now
+ * imports them instead of defining them. Part of breaking up the 2254-LOC
+ * god-module — see docs/ARCHITECTURE.md and the TSK-0335 acceptance
+ * criteria.
+ */
+
+import { invokeSolomon } from "../solomon-escalation.js";
+import { saveSession, pauseSession } from "../../session/store.js";
+import {
+  setReviewerFeedback, setAlternativeAgent, resetRetryCount,
+  incrementRetryCount,
+} from "../../session/mutators.js";
+import { emitProgress, makeEvent } from "../../utils/events.js";
+import { tryCiComment } from "../ci-integration.js";
+
+export async function handleStandbyResult({ stageResult, session, emitter, eventBase, i, stage, logger, config, askQuestion }) {
+  if (stageResult?.action !== "standby") {
+    return { handled: false };
+  }
+
+  const isOutage = stageResult.standbyInfo.isProviderOutage;
+  const agent = stageResult.standbyInfo.agent;
+  const cooldownUntil = stageResult.standbyInfo.cooldownUntil;
+  const cooldownMs = stageResult.standbyInfo.cooldownMs;
+
+  // Rate limit = out of normal flow → Solomon decides immediately
+  const solomonResult = await invokeSolomon({
+    config, logger, emitter, eventBase, stage: `${stage}_rate_limit`, askQuestion, session,
+    iteration: i,
+    conflict: {
+      stage: `${stage}_rate_limit`,
+      task: session.task,
+      iterationCount: i,
+      maxIterations: config?.max_iterations || 5,
+      cooldownUntil,
+      cooldownMs,
+      history: [{
+        agent: stage,
+        feedback: `Agent "${agent}" rate-limited. ${isOutage ? "Provider outage (5xx)." : "API rate limit (429)."} ${cooldownUntil ? `Cooldown until ${cooldownUntil}.` : ""}`
+      }]
+    }
+  });
+
+  if (solomonResult.action === "approve") {
+    // Solomon says skip is safe — only allowed after exhausting alternatives
+    logger.info(`Solomon: skip ${stage} after evaluating risk (agent "${agent}" rate-limited)`);
+    emitProgress(emitter, makeEvent(`${stage}:rate_limit`, { ...eventBase, stage }, {
+      status: "ok",
+      message: `Solomon: skip ${stage} (low risk, agent "${agent}" unavailable)`,
+      detail: { agent, solomonAction: "approve" }
+    }));
+    return { handled: true, action: "skip" };
+  }
+
+  if (solomonResult.action === "continue") {
+    // Solomon says: wait for cooldown, or retry with alternative agent
+    const altAgent = solomonResult.alternativeAgent;
+    const waitTarget = solomonResult.waitUntil;
+
+    if (waitTarget) {
+      const waitMs = Math.max(0, new Date(waitTarget).getTime() - Date.now());
+      if (waitMs > 0 && waitMs < 10 * 60 * 1000) {
+        logger.info(`Solomon: wait ${Math.round(waitMs / 1000)}s for cooldown, then retry ${stage}`);
+        await new Promise(r => setTimeout(r, waitMs));
+      }
+    }
+
+    if (altAgent) {
+      logger.info(`Solomon: retry ${stage} with alternative agent "${altAgent}"`);
+      setAlternativeAgent(session, stage, altAgent);
+    }
+
+    if (solomonResult.humanGuidance) {
+      setReviewerFeedback(session, `Solomon guidance: ${solomonResult.humanGuidance}`);
+    }
+    await saveSession(session);
+    return { handled: true, action: "retry_reviewer_only" };
+  }
+
+  if (solomonResult.action === "pause") {
+    return {
+      handled: true,
+      action: "return",
+      result: { paused: true, sessionId: session.id, question: solomonResult.question, context: "rate_limit" }
+    };
+  }
+
+  // Solomon couldn't resolve — pause
+  await pauseSession(session, {
+    question: `Agent "${agent}" rate-limited. Solomon could not resolve.`,
+    context: { iteration: i, stage, reason: "rate_limit" }
+  });
+  return {
+    handled: true,
+    action: "return",
+    result: { paused: true, sessionId: session.id, question: `Agent "${agent}" rate-limited`, context: "rate_limit" }
+  };
+}
+
+
+function emitSolomonAlerts(alerts, emitter, eventBase, logger) {
+  for (const alert of alerts) {
+    emitProgress(emitter, makeEvent("brain:rules-alert", { ...eventBase, stage: "brain" }, {
+      status: alert.severity === "critical" ? "fail" : "warn",
+      message: alert.message,
+      detail: alert.detail
+    }));
+    logger.warn(`Rules alert [${alert.rule}]: ${alert.message}`);
+  }
+}
+
+export async function handleSolomonCheck({ config, session, emitter, eventBase, logger, task, i, askQuestion, ciEnabled, blockingIssues, brainCtx }) {
+  if (config.pipeline?.solomon?.enabled === false) return { action: "continue" };
+
+  try {
+    const { evaluateRules, buildRulesContext } = await import("../solomon-rules.js");
+    const rulesContext = await buildRulesContext({ session, task, iteration: i, blockingIssues });
+    const rulesResult = evaluateRules(rulesContext, config.solomon?.rules);
+
+    if (rulesResult.alerts.length > 0) {
+      emitSolomonAlerts(rulesResult.alerts, emitter, eventBase, logger);
+      // Brain gateway: when Brain is the orchestrator, rule alerts are telemetry.
+      // On critical alerts Brain consults Solomon (AI judge). Only if Solomon can't
+      // resolve does Brain escalate to human. Solomon-rules never prompts directly.
+      if (!brainCtx?.enabled) {
+        const pauseResult = await checkSolomonCriticalAlerts({ rulesResult, askQuestion, session, i });
+        if (pauseResult) return pauseResult;
+      } else if (rulesResult.hasCritical) {
+        const criticalAlerts = rulesResult.alerts.filter(a => a.severity === "critical");
+        brainCtx.ruleAlerts = brainCtx.ruleAlerts || [];
+        brainCtx.ruleAlerts.push(...criticalAlerts);
+        logger.info(`Brain: ${criticalAlerts.length} critical rule alert(s) — consulting Solomon`);
+
+        const alertSummary = criticalAlerts.map(a => a.message).join("; ");
+        const solomonOpinion = await invokeSolomon({
+          config, logger, emitter, eventBase, stage: "brain-dilemma", askQuestion, session, iteration: i,
+          conflict: {
+            stage: "brain-dilemma",
+            task,
+            iterationCount: i,
+            maxIterations: config.max_iterations,
+            dilemma: `Brain detected critical rule alerts: ${alertSummary}. Should we continue iterating, pause for human, or stop?`,
+            ruleAlerts: criticalAlerts,
+            blockingIssues: blockingIssues || [],
+            history: (session.checkpoints || []).filter(cp => cp.stage === "reviewer").slice(-5).map(cp => ({ iteration: cp.iteration, feedback: cp.note || "" }))
+          }
+        });
+
+        if (solomonOpinion.action === "pause") {
+          logger.info("Brain: Solomon advised pause — escalating to human");
+          return { action: "return", result: { paused: true, sessionId: session.id, question: solomonOpinion.question || `Brain+Solomon paused: ${alertSummary}`, context: "brain_solomon_dilemma" } };
+        }
+        if (solomonOpinion.action === "approve") {
+          logger.info("Brain: Solomon advised proceeding — treating as approved");
+          return { action: "continue", approved: true };
+        }
+        // action === "continue" | "subtask" | fallback → Brain continues the loop
+        logger.info(`Brain: Solomon said '${solomonOpinion.action}' — continuing loop`);
+      }
+    }
+
+    if (ciEnabled && session.ci_pr_number) {
+      const alerts = rulesResult.alerts || [];
+      const alertMsg = alerts.length > 0
+        ? alerts.map(a => `- [${a.severity}] ${a.message}`).join("\n")
+        : "No anomalies detected";
+      await tryCiComment({
+        config, session, logger,
+        agent: "Solomon",
+        body: `Supervisor check iteration ${i}: ${alertMsg}`
+      });
+    }
+  } catch (err) {
+    logger.warn(`Solomon rules evaluation failed: ${err.message}`);
+  }
+
+  return { action: "continue" };
+}
+
+async function checkSolomonCriticalAlerts({ rulesResult, askQuestion, session, i }) {
+  if (!rulesResult.hasCritical || !askQuestion) return null;
+
+  const alertSummary = rulesResult.alerts
+    .filter(a => a.severity === "critical")
+    .map(a => a.message)
+    .join("\n");
+  const question = [
+    "Solomon detected critical issues:",
+    alertSummary,
+    "",
+    "What should we do?",
+    "1 = Continue anyway",
+    "2 = Pause the session",
+    "3 = Stop the session",
+    "",
+    "Type 1, 2, or 3:"
+  ].join("\n");
+  const answer = await askQuestion(question, { iteration: i, stage: "solomon" });
+  const trimmed = (answer || "").trim().toLowerCase();
+  const shouldPause = !answer
+    || trimmed === "2" || trimmed === "3"
+    || trimmed.startsWith("pause") || trimmed.startsWith("stop");
+  if (shouldPause) {
+    await pauseSession(session, {
+      question: `Solomon supervisor paused: ${alertSummary}`,
+      context: { iteration: i, stage: "solomon", alerts: rulesResult.alerts }
+    });
+    return { action: "pause", result: { paused: true, sessionId: session.id, reason: "solomon_alert" } };
+  }
+  return null;
+}
+
+export async function handleReviewerRetryAndSolomon({ config, session, emitter, eventBase, logger, review, task, i, askQuestion }) {
+  setReviewerFeedback(session, review.blocking_issues
+    .map((x) => {
+      const parts = [`[${x.severity || "high"}] ${x.id || "ISSUE"}: ${x.description || "Missing description"}`];
+      if (x.file) parts.push(`  File: ${x.file}${x.line ? `:${x.line}` : ""}`);
+      if (x.suggested_fix) parts.push(`  Fix: ${x.suggested_fix}`);
+      return parts.join("\n");
+    })
+    .join("\n\n"));
+  incrementRetryCount(session, "reviewer");
+  await saveSession(session);
+
+  const maxReviewerRetries = config.session.max_reviewer_retries ?? config.session.fail_fast_repeats;
+  if (session.reviewer_retry_count < maxReviewerRetries) {
+    return { action: "continue" };
+  }
+
+  emitProgress(
+    emitter,
+    makeEvent("solomon:escalate", { ...eventBase, stage: "reviewer" }, {
+      message: `Reviewer sub-loop limit reached (${session.reviewer_retry_count}/${maxReviewerRetries})`,
+      detail: { subloop: "reviewer", retryCount: session.reviewer_retry_count, limit: maxReviewerRetries }
+    })
+  );
+
+  const solomonResult = await invokeSolomon({
+    config, logger, emitter, eventBase, stage: "reviewer", askQuestion, session, iteration: i,
+    conflict: {
+      stage: "reviewer",
+      task,
+      iterationCount: session.reviewer_retry_count,
+      maxIterations: maxReviewerRetries,
+      history: [{ agent: "reviewer", feedback: session.last_reviewer_feedback }]
+    }
+  });
+
+  if (solomonResult.action === "pause") {
+    return { action: "return", result: { paused: true, sessionId: session.id, question: solomonResult.question, context: "reviewer_fail_fast" } };
+  }
+  if (solomonResult.action === "continue") {
+    if (solomonResult.humanGuidance) {
+      // Append, not overwrite — keep the reviewer's blocking issues context.
+      setReviewerFeedback(session, `${session.last_reviewer_feedback}\nUser guidance: ${solomonResult.humanGuidance}`);
+    }
+    resetRetryCount(session, "reviewer");
+    await saveSession(session);
+    return { action: "continue" };
+  }
+  if (solomonResult.action === "subtask") {
+    return { action: "return", result: { paused: true, sessionId: session.id, subtask: solomonResult.subtask, context: "reviewer_subtask" } };
+  }
+
+  return { action: "continue" };
+}