@chllming/wave-orchestration 0.5.1

package/scripts/wave-orchestrator/docs-queue.mjs

@@ -0,0 +1,75 @@
+import { readJsonOrNull, toIsoTimestamp, writeJsonAtomic } from "./shared.mjs";
+
+export function buildDocsQueue({
+  lane,
+  wave,
+  summariesByAgentId = {},
+  sharedPlanDocs = [],
+  componentPromotions = [],
+  runtimeAssignments = [],
+}) {
+  const items = [];
+  for (const [agentId, summary] of Object.entries(summariesByAgentId || {})) {
+    if (!summary?.docDelta) {
+      continue;
+    }
+    if (summary.docDelta.state === "owned") {
+      for (const docPath of summary.docDelta.paths || []) {
+        items.push({
+          id: `${agentId}:owned:${docPath}`,
+          kind: "owned-doc",
+          agentId,
+          ownerAgentId: agentId,
+          path: docPath,
+          summary: `Owned documentation update required in ${docPath}`,
+          detail: summary.docDelta.detail || "",
+          targets: [agentId],
+        });
+      }
+    }
+    if (summary.docDelta.state === "shared-plan") {
+      for (const docPath of summary.docDelta.paths || sharedPlanDocs) {
+        items.push({
+          id: `${agentId}:shared:${docPath}`,
+          kind: "shared-plan",
+          agentId,
+          ownerAgentId: null,
+          path: docPath,
+          summary: `Shared-plan reconciliation required in ${docPath}`,
+          detail: summary.docDelta.detail || "",
+          targets: [],
+        });
+      }
+    }
+  }
+  for (const promotion of componentPromotions || []) {
+    items.push({
+      id: `component-matrix:${promotion.componentId}`,
+      kind: "component-matrix",
+      agentId: null,
+      ownerAgentId: null,
+      path: promotion.componentId,
+      summary: `Component matrix currentLevel must reflect ${promotion.componentId} -> ${promotion.targetLevel}`,
+      detail: "",
+      targets: [],
+    });
+  }
+  const releaseNotesRequired = items.some((item) => item.kind === "shared-plan");
+  return {
+    lane,
+    wave: wave.wave || wave,
+    createdAt: toIsoTimestamp(),
+    updatedAt: toIsoTimestamp(),
+    releaseNotesRequired,
+    runtimeAssignments,
+    items,
+  };
+}
+
+export function writeDocsQueue(filePath, payload) {
+  writeJsonAtomic(filePath, payload);
+}
+
+export function readDocsQueue(filePath) {
+  return readJsonOrNull(filePath);
+}

package/scripts/wave-orchestrator/executors.mjs

@@ -0,0 +1,385 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  DEFAULT_CODEX_COMMAND,
+  DEFAULT_CODEX_SANDBOX_MODE,
+  DEFAULT_EXECUTOR_MODE,
+  normalizeExecutorMode,
+} from "./config.mjs";
+import {
+  PACKAGE_ROOT,
+  REPO_ROOT,
+  ensureDirectory,
+  shellQuote,
+  writeJsonAtomic,
+  writeTextAtomic,
+} from "./shared.mjs";
+
+function appendSingleValueFlag(tokens, flag, value) {
+  if (value === null || value === undefined || value === "") {
+    return;
+  }
+  tokens.push(flag, shellQuote(value));
+}
+
+function appendRepeatedFlag(tokens, flag, values) {
+  const list = Array.isArray(values) ? values.filter(Boolean) : [];
+  if (list.length === 0) {
+    return;
+  }
+  for (const value of list) {
+    tokens.push(flag, shellQuote(value));
+  }
+}
+
+function appendBooleanFlag(tokens, flag, enabled) {
+  if (!enabled) {
+    return;
+  }
+  tokens.push(flag);
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function cloneJson(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+function mergeJsonObjects(...sources) {
+  const merged = {};
+  for (const source of sources) {
+    if (!isPlainObject(source)) {
+      continue;
+    }
+    for (const [key, value] of Object.entries(source)) {
+      if (isPlainObject(value) && isPlainObject(merged[key])) {
+        merged[key] = mergeJsonObjects(merged[key], value);
+      } else {
+        merged[key] = cloneJson(value);
+      }
+    }
+  }
+  return merged;
+}
+
+function mergeUniqueStringArrays(...lists) {
+  const merged = [];
+  const seen = new Set();
+  for (const list of lists) {
+    for (const value of Array.isArray(list) ? list : []) {
+      const normalized = String(value || "").trim();
+      if (!normalized || seen.has(normalized)) {
+        continue;
+      }
+      seen.add(normalized);
+      merged.push(normalized);
+    }
+  }
+  return merged;
+}
+
+function resolveRepoFilePath(filePath) {
+  if (!filePath) {
+    return null;
+  }
+  return path.isAbsolute(filePath) ? filePath : path.join(REPO_ROOT, filePath);
+}
+
+function readJsonObjectFile(filePath, label) {
+  const absolutePath = resolveRepoFilePath(filePath);
+  if (!absolutePath || !fs.existsSync(absolutePath)) {
+    throw new Error(`${label} file not found: ${filePath}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(absolutePath, "utf8"));
+  } catch (error) {
+    throw new Error(`Invalid ${label} JSON at ${filePath}: ${error.message}`);
+  }
+  if (!isPlainObject(parsed)) {
+    throw new Error(`${label} must be a JSON object: ${filePath}`);
+  }
+  return parsed;
+}
+
+function buildClaudeSettingsPath(executor, overlayDir) {
+  const inlineSettings = executor.claude.settingsJson || null;
+  const inlineHooks = executor.claude.hooksJson || null;
+  const inlineAllowedHttpHookUrls = Array.isArray(executor.claude.allowedHttpHookUrls)
+    ? executor.claude.allowedHttpHookUrls.filter(Boolean)
+    : [];
+  const hasInlineOverlay =
+    Boolean(inlineSettings) ||
+    Boolean(inlineHooks) ||
+    inlineAllowedHttpHookUrls.length > 0;
+  if (!hasInlineOverlay) {
+    return executor.claude.settings || null;
+  }
+  const baseSettings = executor.claude.settings
+    ? readJsonObjectFile(executor.claude.settings, "Claude settings")
+    : {};
+  const merged = mergeJsonObjects(
+    baseSettings,
+    inlineSettings,
+    inlineHooks ? { hooks: inlineHooks } : null,
+    inlineAllowedHttpHookUrls.length > 0
+      ? { allowedHttpHookUrls: inlineAllowedHttpHookUrls }
+      : null,
+  );
+  const settingsPath = path.join(overlayDir, "claude-settings.json");
+  writeJsonAtomic(settingsPath, merged);
+  return settingsPath;
+}
+
+function buildOpenCodeConfig({ agent, executor, agentName, promptFileName, overlayDir }) {
+  const promptAgent = {
+    description: `Wave agent ${agent.agentId}: ${agent.title}`,
+    mode: "primary",
+    prompt: `{file:./${promptFileName}}`,
+    ...(executor.opencode.model || executor.model
+      ? { model: executor.opencode.model || executor.model }
+      : {}),
+    ...(executor.opencode.steps ? { steps: executor.opencode.steps } : {}),
+    ...(executor.opencode.permission ? { permission: executor.opencode.permission } : {}),
+  };
+  const baseConfig = isPlainObject(executor.opencode.configJson) ? executor.opencode.configJson : {};
+  const baseAgentConfig = isPlainObject(baseConfig.agent) ? baseConfig.agent : {};
+  const config = mergeJsonObjects(baseConfig, {
+    $schema: baseConfig.$schema || "https://opencode.ai/config.json",
+    instructions: mergeUniqueStringArrays(baseConfig.instructions, executor.opencode.instructions),
+    agent: {
+      ...baseAgentConfig,
+      [agentName]: mergeJsonObjects(baseAgentConfig[agentName], promptAgent),
+    },
+  });
+  const configPath = path.join(overlayDir, "opencode.json");
+  writeJsonAtomic(configPath, config);
+  return configPath;
+}
+
+function renderHarnessSystemPrompt(agent, executorId) {
+  return [
+    "You are running inside the Wave orchestration harness.",
+    `Resolved executor: ${executorId}.`,
+    `Assigned wave agent: ${agent.agentId} (${agent.title}).`,
+    "Treat the incoming task prompt as the authoritative assignment.",
+    "Preserve structured Wave markers exactly when they are required by the task.",
+    "Do not omit or rewrite message-board requirements, exit-contract requirements, or ownership boundaries.",
+    "Prefer plain text output unless the task explicitly requires code blocks.",
+  ].join("\n");
+}
+
+export function buildCodexExecInvocation(
+  promptPath,
+  logPath,
+  codexSandboxMode,
+  command = DEFAULT_CODEX_COMMAND,
+  options = {},
+) {
+  const tokens = [
+    command,
+    "--ask-for-approval never",
+    "exec",
+    "--skip-git-repo-check",
+    `--sandbox ${shellQuote(codexSandboxMode || DEFAULT_CODEX_SANDBOX_MODE)}`,
+  ];
+  appendSingleValueFlag(tokens, "--model", options.model);
+  appendSingleValueFlag(tokens, "--profile", options.profileName);
+  appendRepeatedFlag(tokens, "-c", options.config);
+  appendBooleanFlag(tokens, "--search", options.search);
+  appendRepeatedFlag(tokens, "--image", options.images);
+  appendRepeatedFlag(tokens, "--add-dir", options.addDirs);
+  appendBooleanFlag(tokens, "--json", options.json);
+  appendBooleanFlag(tokens, "--ephemeral", options.ephemeral);
+  tokens.push("-", `< ${shellQuote(promptPath)}`, `2>&1 | tee -a ${shellQuote(logPath)}`);
+  return tokens.join(" ");
+}
+
+function buildClaudeLaunchSpec({ agent, promptPath, logPath, overlayDir }) {
+  const executor = agent.executorResolved;
+  const systemPromptPath = path.join(overlayDir, "claude-system-prompt.txt");
+  writeTextAtomic(systemPromptPath, `${renderHarnessSystemPrompt(agent, "claude")}\n`);
+  const tokens = [executor.claude.command, "-p", "--no-session-persistence"];
+  const settingsPath = buildClaudeSettingsPath(executor, overlayDir);
+  appendSingleValueFlag(tokens, "--output-format", executor.claude.outputFormat || "text");
+  appendSingleValueFlag(tokens, "--model", executor.claude.model || executor.model);
+  appendSingleValueFlag(tokens, "--agent", executor.claude.agent);
+  appendSingleValueFlag(tokens, "--permission-mode", executor.claude.permissionMode);
+  appendSingleValueFlag(tokens, "--permission-prompt-tool", executor.claude.permissionPromptTool);
+  appendSingleValueFlag(tokens, "--max-turns", executor.claude.maxTurns);
+  appendRepeatedFlag(tokens, "--mcp-config", executor.claude.mcpConfig);
+  appendSingleValueFlag(tokens, "--settings", settingsPath);
+  appendRepeatedFlag(tokens, "--allowedTools", executor.claude.allowedTools);
+  appendRepeatedFlag(tokens, "--disallowedTools", executor.claude.disallowedTools);
+  if (executor.claude.strictMcpConfig) {
+    tokens.push("--strict-mcp-config");
+  }
+  tokens.push(
+    executor.claude.appendSystemPromptMode === "replace"
+      ? "--system-prompt-file"
+      : "--append-system-prompt-file",
+    shellQuote(systemPromptPath),
+  );
+  return {
+    executorId: "claude",
+    command: executor.claude.command,
+    useRateLimitRetries: true,
+    invocationLines: [
+      `task_prompt=$(cat ${shellQuote(promptPath)})`,
+      `${tokens.join(" ")} "$task_prompt" 2>&1 | tee -a ${shellQuote(logPath)}`,
+    ],
+  };
+}
+
+function buildOpenCodeLaunchSpec({ agent, promptPath, logPath, overlayDir }) {
+  const executor = agent.executorResolved;
+  const requestedAgentName = String(executor.opencode.agent || `wave-${agent.agentId}`)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  const agentName = requestedAgentName || `wave-${agent.agentId.toLowerCase()}`;
+  const promptFileName = "opencode-agent-prompt.txt";
+  const promptFilePath = path.join(overlayDir, promptFileName);
+  writeTextAtomic(promptFilePath, `${renderHarnessSystemPrompt(agent, "opencode")}\n`);
+  const configPath = buildOpenCodeConfig({
+    agent,
+    executor,
+    agentName,
+    promptFileName,
+    overlayDir,
+  });
+  const tokens = [executor.opencode.command, "run", "--agent", shellQuote(agentName)];
+  appendSingleValueFlag(tokens, "--model", executor.opencode.model || executor.model);
+  appendSingleValueFlag(tokens, "--format", executor.opencode.format || "default");
+  appendSingleValueFlag(tokens, "--attach", executor.opencode.attach);
+  appendRepeatedFlag(tokens, "--file", executor.opencode.files);
+  appendSingleValueFlag(tokens, "--title", `wave-${agent.agentId}`);
+  return {
+    executorId: "opencode",
+    command: executor.opencode.command,
+    useRateLimitRetries: true,
+    env: {
+      OPENCODE_CONFIG: configPath,
+    },
+    invocationLines: [
+      `task_prompt=$(cat ${shellQuote(promptPath)})`,
+      `${tokens.join(" ")} "$task_prompt" 2>&1 | tee -a ${shellQuote(logPath)}`,
+    ],
+  };
+}
+
+function buildLocalLaunchSpec({ promptPath, logPath }) {
+  return {
+    executorId: "local",
+    command: "node",
+    useRateLimitRetries: false,
+    invocationLines: [
+      `node ${shellQuote(path.join(PACKAGE_ROOT, "scripts", "wave-local-executor.mjs"))} --prompt-file ${shellQuote(
+        promptPath,
+      )} 2>&1 | tee ${shellQuote(logPath)}`,
+    ],
+  };
+}
+
+function buildCodexLaunchSpec({ agent, promptPath, logPath }) {
+  const executor = agent.executorResolved;
+  return {
+    executorId: "codex",
+    command: executor.codex.command,
+    useRateLimitRetries: true,
+    invocationLines: [
+      buildCodexExecInvocation(
+        promptPath,
+        logPath,
+        executor.codex.sandbox,
+        executor.codex.command,
+        {
+          model: executor.model,
+          profileName: executor.codex.profileName,
+          config: executor.codex.config,
+          search: executor.codex.search,
+          images: executor.codex.images,
+          addDirs: executor.codex.addDirs,
+          json: executor.codex.json,
+          ephemeral: executor.codex.ephemeral,
+        },
+      ),
+    ],
+  };
+}
+
+export function buildExecutorLaunchSpec({ agent, promptPath, logPath, overlayDir }) {
+  const executorId = normalizeExecutorMode(agent?.executorResolved?.id || DEFAULT_EXECUTOR_MODE);
+  ensureDirectory(overlayDir);
+  if (executorId === "local") {
+    return buildLocalLaunchSpec({ promptPath, logPath });
+  }
+  if (executorId === "claude") {
+    return buildClaudeLaunchSpec({ agent, promptPath, logPath, overlayDir });
+  }
+  if (executorId === "opencode") {
+    return buildOpenCodeLaunchSpec({ agent, promptPath, logPath, overlayDir });
+  }
+  return buildCodexLaunchSpec({ agent, promptPath, logPath });
+}
+
+export function commandForExecutor(executor, executorId = executor?.id) {
+  if (executorId === "codex") {
+    return executor?.codex?.command || DEFAULT_CODEX_COMMAND;
+  }
+  if (executorId === "claude") {
+    return executor?.claude?.command || "claude";
+  }
+  if (executorId === "opencode") {
+    return executor?.opencode?.command || "opencode";
+  }
+  return "node";
+}
+
+export function isExecutorCommandAvailable(command) {
+  const result = spawnSync("bash", ["-lc", `command -v ${shellQuote(command)}`], {
+    cwd: REPO_ROOT,
+    encoding: "utf8",
+    env: process.env,
+  });
+  return result.status === 0;
+}
+
+export function preflightExecutorCommand(command, executorId) {
+  if (isExecutorCommandAvailable(command)) {
+    return;
+  }
+  const result = spawnSync("bash", ["-lc", `command -v ${shellQuote(command)}`], {
+    cwd: REPO_ROOT,
+    encoding: "utf8",
+    env: process.env,
+  });
+  const detail = (result.stderr || result.stdout || "").trim();
+  throw new Error(
+    `Executor "${executorId}" requires "${command}" on PATH${detail ? ` (${detail})` : ""}`,
+  );
+}
+
+export function preflightExecutorsForWaves(waves) {
+  const seen = new Map();
+  for (const wave of waves) {
+    for (const agent of wave.agents) {
+      const executor = agent.executorResolved;
+      if (!executor) {
+        continue;
+      }
+      const command = commandForExecutor(executor, executor.id);
+      const key = `${executor.id}:${command}`;
+      if (seen.has(key)) {
+        continue;
+      }
+      seen.set(key, true);
+      preflightExecutorCommand(command, executor.id);
+    }
+  }
+}