@chllming/wave-orchestration 0.6.2 → 0.7.0

package/scripts/wave-orchestrator/retry-cli.mjs

@@ -0,0 +1,184 @@
+import path from "node:path";
+import { parseWaveFiles } from "./wave-files.mjs";
+import {
+  buildLanePaths,
+  parseNonNegativeInt,
+  readJsonOrNull,
+  REPO_ROOT,
+  sanitizeAdhocRunId,
+  sanitizeLaneName,
+} from "./shared.mjs";
+import {
+  clearWaveRetryOverride,
+  readWaveRelaunchPlanSnapshot,
+  readWaveRetryOverride,
+  resolveRetryOverrideAgentIds,
+  writeWaveRetryOverride,
+} from "./retry-control.mjs";
+
+function printUsage() {
+  console.log(`Usage:
+  pnpm exec wave retry show --lane <lane> --wave <n> [--json]
+  pnpm exec wave retry apply --lane <lane> --wave <n> [--agent <id> ...] [--clear-reuse <id> ...] [--preserve-reuse <id> ...] [--resume-phase <phase>] [--requested-by <name>] [--reason <text>] [--json]
+  pnpm exec wave retry clear --lane <lane> --wave <n>
+  pnpm exec wave retry <subcommand> --run <id> [--wave 0] ...
+`);
+}
+
+function normalizeAgentList(values) {
+  return Array.from(
+    new Set(
+      values
+        .flatMap((value) => String(value || "").split(","))
+        .map((value) => value.trim())
+        .filter(Boolean),
+    ),
+  );
+}
+
+function parseArgs(argv) {
+  const args = argv[0] === "--" ? argv.slice(1) : argv;
+  const subcommand = String(args[0] || "").trim().toLowerCase();
+  const options = {
+    lane: "main",
+    wave: null,
+    runId: "",
+    json: false,
+    selectedAgentIds: [],
+    clearReusableAgentIds: [],
+    preserveReusableAgentIds: [],
+    resumePhase: "",
+    requestedBy: "",
+    reason: "",
+  };
+  for (let i = 1; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--lane") {
+      options.lane = sanitizeLaneName(args[++i]);
+    } else if (arg === "--run") {
+      options.runId = sanitizeAdhocRunId(args[++i]);
+    } else if (arg === "--wave") {
+      options.wave = parseNonNegativeInt(args[++i], "--wave");
+    } else if (arg === "--agent" || arg === "--agents") {
+      options.selectedAgentIds.push(args[++i]);
+    } else if (arg === "--clear-reuse") {
+      options.clearReusableAgentIds.push(args[++i]);
+    } else if (arg === "--preserve-reuse") {
+      options.preserveReusableAgentIds.push(args[++i]);
+    } else if (arg === "--resume-phase") {
+      options.resumePhase = String(args[++i] || "").trim();
+    } else if (arg === "--requested-by") {
+      options.requestedBy = String(args[++i] || "").trim();
+    } else if (arg === "--reason") {
+      options.reason = String(args[++i] || "").trim();
+    } else if (arg === "--json") {
+      options.json = true;
+    } else if (arg === "--help" || arg === "-h") {
+      return { help: true, subcommand, options };
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return { help: false, subcommand, options };
+}
+
+function resolveLaneForRun(runId, fallbackLane) {
+  return (
+    readJsonOrNull(path.join(REPO_ROOT, ".wave", "adhoc", "runs", runId, "result.json"))?.lane ||
+    fallbackLane
+  );
+}
+
+function loadWave(lanePaths, waveNumber) {
+  const waves = parseWaveFiles(lanePaths.wavesDir, { laneProfile: lanePaths.laneProfile });
+  const wave = waves.find((entry) => entry.wave === waveNumber);
+  if (!wave) {
+    throw new Error(`Wave ${waveNumber} not found in ${lanePaths.wavesDir}`);
+  }
+  return wave;
+}
+
+export async function runRetryCli(argv) {
+  const { help, subcommand, options } = parseArgs(argv);
+  if (help || !subcommand) {
+    printUsage();
+    return;
+  }
+  if (!["show", "apply", "clear"].includes(subcommand)) {
+    throw new Error("Expected subcommand: show | apply | clear");
+  }
+  if (options.runId) {
+    options.lane = resolveLaneForRun(options.runId, options.lane);
+  }
+  const lanePaths = buildLanePaths(options.lane, {
+    adhocRunId: options.runId || null,
+  });
+  if (options.wave === null && options.runId) {
+    options.wave = 0;
+  }
+  if (options.wave === null) {
+    throw new Error("--wave is required");
+  }
+  const wave = loadWave(lanePaths, options.wave);
+  if (subcommand === "clear") {
+    clearWaveRetryOverride(lanePaths, wave.wave);
+    console.log(`[wave-retry] cleared override for wave ${wave.wave}`);
+    return;
+  }
+
+  const existingOverride = readWaveRetryOverride(lanePaths, wave.wave);
+  const relaunchPlan = readWaveRelaunchPlanSnapshot(lanePaths, wave.wave);
+  if (subcommand === "show") {
+    const payload = {
+      wave: wave.wave,
+      lane: lanePaths.lane,
+      override: existingOverride,
+      effectiveSelectedAgentIds: resolveRetryOverrideAgentIds(wave, lanePaths, existingOverride),
+      relaunchPlan,
+    };
+    if (options.json) {
+      console.log(JSON.stringify(payload, null, 2));
+    } else {
+      console.log(JSON.stringify(payload, null, 2));
+    }
+    return;
+  }
+
+  const selectedAgentIds = normalizeAgentList(options.selectedAgentIds);
+  const clearReusableAgentIds = normalizeAgentList(options.clearReusableAgentIds);
+  const preserveReusableAgentIds = normalizeAgentList(options.preserveReusableAgentIds);
+  const knownAgentIds = new Set((wave.agents || []).map((agent) => agent.agentId));
+  const unknownAgentIds = [
+    ...selectedAgentIds,
+    ...clearReusableAgentIds,
+    ...preserveReusableAgentIds,
+  ].filter((agentId) => !knownAgentIds.has(agentId));
+  if (unknownAgentIds.length > 0) {
+    throw new Error(`Unknown wave agent ids: ${unknownAgentIds.join(", ")}`);
+  }
+  if (selectedAgentIds.length === 0 && !String(options.resumePhase || "").trim()) {
+    throw new Error("apply requires --agent/--agents or --resume-phase");
+  }
+  const override = writeWaveRetryOverride(lanePaths, wave.wave, {
+    lane: lanePaths.lane,
+    wave: wave.wave,
+    selectedAgentIds,
+    clearReusableAgentIds,
+    preserveReusableAgentIds,
+    resumePhase: options.resumePhase || null,
+    requestedBy: options.requestedBy || "human-operator",
+    reason: options.reason || null,
+    applyOnce: true,
+  });
+  const payload = {
+    wave: wave.wave,
+    lane: lanePaths.lane,
+    override,
+    effectiveSelectedAgentIds: resolveRetryOverrideAgentIds(wave, lanePaths, override),
+  };
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(JSON.stringify(payload, null, 2));
+  }
+}

package/scripts/wave-orchestrator/retry-control.mjs

@@ -0,0 +1,225 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  readRetryOverride,
+  readRelaunchPlan,
+  writeRetryOverride,
+} from "./artifact-schemas.mjs";
+import {
+  appendWaveControlEvent,
+  readWaveControlPlaneState,
+  syncWaveControlPlaneProjections,
+} from "./control-plane.mjs";
+import { isSecurityReviewAgent } from "./role-helpers.mjs";
+import { ensureDirectory, parseNonNegativeInt } from "./shared.mjs";
+
+function uniqueAgentIds(values) {
+  return Array.from(
+    new Set(
+      (Array.isArray(values) ? values : [])
+        .map((value) => String(value || "").trim())
+        .filter(Boolean),
+    ),
+  );
+}
+
+function mergeRetryOverride(activeRequest, projectedOverride, lanePaths, waveNumber) {
+  const projected = projectedOverride || {};
+  return {
+    lane: lanePaths?.lane || projected.lane || null,
+    wave: waveNumber,
+    selectedAgentIds: uniqueAgentIds(
+      projected.selectedAgentIds?.length > 0
+        ? projected.selectedAgentIds
+        : activeRequest?.selectedAgentIds,
+    ),
+    reuseAttemptIds: uniqueAgentIds(
+      projected.reuseAttemptIds?.length > 0
+        ? projected.reuseAttemptIds
+        : activeRequest?.reuseAttemptIds,
+    ),
+    reuseProofBundleIds: uniqueAgentIds(
+      projected.reuseProofBundleIds?.length > 0
+        ? projected.reuseProofBundleIds
+        : activeRequest?.reuseProofBundleIds,
+    ),
+    reuseDerivedSummaries:
+      projected.reuseDerivedSummaries === false ? false : activeRequest?.reuseDerivedSummaries !== false,
+    invalidateComponentIds: uniqueAgentIds(
+      projected.invalidateComponentIds?.length > 0
+        ? projected.invalidateComponentIds
+        : activeRequest?.invalidateComponentIds,
+    ),
+    clearReusableAgentIds: uniqueAgentIds(
+      projected.clearReusableAgentIds?.length > 0
+        ? projected.clearReusableAgentIds
+        : activeRequest?.clearReusableAgentIds,
+    ),
+    preserveReusableAgentIds: uniqueAgentIds(
+      projected.preserveReusableAgentIds?.length > 0
+        ? projected.preserveReusableAgentIds
+        : activeRequest?.preserveReusableAgentIds,
+    ),
+    resumePhase: projected.resumePhase || activeRequest?.resumeCursor || null,
+    requestedBy: projected.requestedBy || activeRequest?.requestedBy || "human-operator",
+    reason: projected.reason || activeRequest?.reason || null,
+    applyOnce: projected.applyOnce === false ? false : activeRequest?.applyOnce !== false,
+    createdAt: projected.createdAt || activeRequest?.createdAt,
+  };
+}
+
+export function waveRetryOverridePath(lanePaths, waveNumber) {
+  return path.join(lanePaths.controlDir, `retry-override-wave-${parseNonNegativeInt(waveNumber, "wave")}.json`);
+}
+
+export function waveRelaunchPlanPath(lanePaths, waveNumber) {
+  return path.join(lanePaths.statusDir, `relaunch-plan-wave-${parseNonNegativeInt(waveNumber, "wave")}.json`);
+}
+
+export function readWaveRetryOverride(lanePaths, waveNumber) {
+  const state = readWaveControlPlaneState(lanePaths, waveNumber);
+  const activeRequest = state.activeRerunRequest;
+  const projectedOverride = readRetryOverride(waveRetryOverridePath(lanePaths, waveNumber), {
+    lane: lanePaths?.lane || null,
+    wave: waveNumber,
+  });
+  if (!activeRequest && state.rerunRequests.length === 0) {
+    return projectedOverride;
+  }
+  if (!activeRequest) {
+    return null;
+  }
+  return mergeRetryOverride(activeRequest, projectedOverride, lanePaths, waveNumber);
+}
+
+export function writeWaveRetryOverride(lanePaths, waveNumber, payload) {
+  const filePath = waveRetryOverridePath(lanePaths, waveNumber);
+  ensureDirectory(path.dirname(filePath));
+  const requestId =
+    String(payload?.requestId || "").trim() ||
+    `rerun-wave-${parseNonNegativeInt(waveNumber, "wave")}-${Date.now()}`;
+  appendWaveControlEvent(lanePaths, waveNumber, {
+    entityType: "rerun_request",
+    entityId: requestId,
+    action: "requested",
+    source: "operator",
+    actor: String(payload?.requestedBy || "human-operator"),
+    data: {
+      requestId,
+      state: "active",
+      selectedAgentIds: uniqueAgentIds(payload?.selectedAgentIds),
+      resumeCursor: String(payload?.resumeCursor || payload?.resumePhase || "").trim() || null,
+      reuseAttemptIds: uniqueAgentIds(payload?.reuseAttemptIds),
+      reuseProofBundleIds: uniqueAgentIds(payload?.reuseProofBundleIds),
+      reuseDerivedSummaries: payload?.reuseDerivedSummaries !== false,
+      invalidateComponentIds: uniqueAgentIds(payload?.invalidateComponentIds),
+      clearReusableAgentIds: uniqueAgentIds(payload?.clearReusableAgentIds),
+      preserveReusableAgentIds: uniqueAgentIds(payload?.preserveReusableAgentIds),
+      requestedBy: String(payload?.requestedBy || "human-operator"),
+      reason: String(payload?.reason || "").trim() || null,
+      applyOnce: payload?.applyOnce !== false,
+      createdAt: String(payload?.createdAt || "") || undefined,
+    },
+  });
+  const projections = syncWaveControlPlaneProjections(
+    lanePaths,
+    waveNumber,
+    readWaveControlPlaneState(lanePaths, waveNumber),
+  );
+  return writeRetryOverride(filePath, projections.retryOverride, {
+    lane: lanePaths?.lane || null,
+    wave: waveNumber,
+  });
+}
+
+export function clearWaveRetryOverride(lanePaths, waveNumber) {
+  const activeRequest = readWaveControlPlaneState(lanePaths, waveNumber).activeRerunRequest;
+  if (activeRequest?.requestId) {
+    appendWaveControlEvent(lanePaths, waveNumber, {
+      entityType: "rerun_request",
+      entityId: activeRequest.requestId,
+      action: "cleared",
+      source: "operator",
+      actor: "human-operator",
+      data: {
+        ...activeRequest,
+        state: "cleared",
+        updatedAt: undefined,
+      },
+    });
+    syncWaveControlPlaneProjections(
+      lanePaths,
+      waveNumber,
+      readWaveControlPlaneState(lanePaths, waveNumber),
+    );
+  }
+  try {
+    fs.rmSync(waveRetryOverridePath(lanePaths, waveNumber), { force: true });
+  } catch {
+    // no-op
+  }
+}
+
+export function readWaveRelaunchPlanSnapshot(lanePaths, waveNumber) {
+  return readRelaunchPlan(waveRelaunchPlanPath(lanePaths, waveNumber), {
+    wave: waveNumber,
+  });
+}
+
+export function resolveRetryOverrideAgentIds(waveDefinition, lanePaths, override) {
+  const selectedAgentIds = uniqueAgentIds(override?.selectedAgentIds);
+  if (selectedAgentIds.length > 0) {
+    return selectedAgentIds;
+  }
+  const resumePhase = String(override?.resumePhase || "")
+    .trim()
+    .toLowerCase();
+  if (!resumePhase) {
+    return [];
+  }
+  const agents = Array.isArray(waveDefinition?.agents) ? waveDefinition.agents : [];
+  const closureAgentIds = new Set(
+    [
+      lanePaths?.contEvalAgentId || "E0",
+      lanePaths?.integrationAgentId || "A8",
+      lanePaths?.documentationAgentId || "A9",
+      lanePaths?.contQaAgentId || "A0",
+    ].filter(Boolean),
+  );
+  if (resumePhase === "implementation") {
+    return agents
+      .filter((agent) => agent?.agentId && !closureAgentIds.has(agent.agentId) && !isSecurityReviewAgent(agent))
+      .map((agent) => agent.agentId);
+  }
+  if (resumePhase === "integrating") {
+    return [lanePaths?.integrationAgentId || "A8"];
+  }
+  if (resumePhase === "docs-closure") {
+    return [lanePaths?.documentationAgentId || "A9"];
+  }
+  if (resumePhase === "cont-qa-closure") {
+    return [lanePaths?.contQaAgentId || "A0"];
+  }
+  if (resumePhase === "cont-eval") {
+    return [lanePaths?.contEvalAgentId || "E0"];
+  }
+  return [];
+}
+
+export function resolveRetryOverrideRuns(agentRuns, override, lanePaths, waveDefinition) {
+  const selectedAgentIds = resolveRetryOverrideAgentIds(waveDefinition, lanePaths, override);
+  if (selectedAgentIds.length === 0) {
+    return {
+      runs: [],
+      selectedAgentIds: [],
+      unknownAgentIds: [],
+    };
+  }
+  const runsByAgentId = new Map((agentRuns || []).map((run) => [run?.agent?.agentId, run]));
+  const unknownAgentIds = selectedAgentIds.filter((agentId) => !runsByAgentId.has(agentId));
+  return {
+    runs: selectedAgentIds.map((agentId) => runsByAgentId.get(agentId)).filter(Boolean),
+    selectedAgentIds,
+    unknownAgentIds,
+  };
+}

package/scripts/wave-orchestrator/shared.mjs

@@ -19,6 +19,9 @@ export const DEFAULT_AGENT_RATE_LIMIT_BASE_DELAY_SECONDS = 20;
 export const DEFAULT_AGENT_RATE_LIMIT_MAX_DELAY_SECONDS = 180;
 export const DEFAULT_AGENT_LAUNCH_STAGGER_MS = 1200;
 export const DEFAULT_WAIT_PROGRESS_INTERVAL_MS = 3000;
+export const DEFAULT_LIVE_COORDINATION_REFRESH_MS = 15000;
+export const DEFAULT_COORDINATION_ACK_TIMEOUT_MS = 5 * 60 * 1000;
+export const DEFAULT_COORDINATION_RESOLUTION_STALE_MS = 30 * 60 * 1000;
 export const DEFAULT_REFRESH_MS = 2000;
 export const DEFAULT_WATCH_REFRESH_MS = 2000;
 export const DEFAULT_WAIT_TIMEOUT_SECONDS = 1800;
@@ -109,6 +112,21 @@ export function buildWorkspaceTmuxToken(workspaceRoot = REPO_ROOT) {
   return `${repoBase}_${repoHash}`;
 }
 
+function buildTelemetryProjectId(config) {
+  return (
+    String(config?.waveControl?.projectId || config?.projectId || config?.projectName || path.basename(REPO_ROOT))
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9._-]+/g, "-")
+      .replace(/-+/g, "-")
+      .replace(/^-+|-+$/g, "") || "wave"
+  );
+}
+
+function readRuntimeVersion() {
+  return String(readJsonOrNull(path.join(PACKAGE_ROOT, "package.json"))?.version || "").trim() || null;
+}
+
 export function buildLanePaths(laneInput = DEFAULT_WAVE_LANE, options = {}) {
   const config = options.config || loadWaveConfig();
   const baseLaneProfile = resolveLaneProfile(config, laneInput || config.defaultLane);
@@ -176,10 +194,14 @@ export function buildLanePaths(laneInput = DEFAULT_WAVE_LANE, options = {}) {
     messageboardsDir: path.join(stateDir, "messageboards"),
     dashboardsDir: path.join(stateDir, "dashboards"),
     coordinationDir: path.join(stateDir, "coordination"),
+    controlDir: path.join(stateDir, "control"),
+    controlPlaneDir: path.join(stateDir, "control-plane"),
+    telemetryDir: path.join(stateDir, "control-plane", "telemetry"),
     assignmentsDir: path.join(stateDir, "assignments"),
     inboxesDir: path.join(stateDir, "inboxes"),
     ledgerDir: path.join(stateDir, "ledger"),
     integrationDir: path.join(stateDir, "integration"),
+    proofDir: path.join(stateDir, "proof"),
     securityDir: path.join(stateDir, "security"),
     dependencySnapshotsDir: path.join(stateDir, "dependencies"),
     docsQueueDir: path.join(stateDir, "docs-queue"),
@@ -224,6 +246,10 @@ export function buildLanePaths(laneInput = DEFAULT_WAVE_LANE, options = {}) {
     executors: laneProfile.executors,
     skills: laneProfile.skills,
     capabilityRouting: laneProfile.capabilityRouting,
+    projectId: buildTelemetryProjectId(config),
+    runtimeVersion: readRuntimeVersion(),
+    orchestratorId: null,
+    waveControl: laneProfile.waveControl,
     defaultManifestPath: path.join(stateDir, "waves.manifest.json"),
     defaultRunStatePath: path.join(stateDir, "run-state.json"),
     globalDashboardPath: path.join(stateDir, "dashboards", "global.json"),