@chllming/wave-orchestration 0.8.2 → 0.8.4

package/scripts/wave-orchestrator/human-input-resolution.mjs

@@ -0,0 +1,348 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  appendCoordinationRecord,
+  clarificationClosureCondition,
+  clarificationLinkedRequests,
+  isOpenCoordinationStatus,
+  readMaterializedCoordinationState,
+} from "./coordination-store.mjs";
+import { readWaveHumanFeedbackRequests } from "./coordination.mjs";
+import {
+  readControlPlaneEvents,
+  readWaveControlPlaneState,
+  syncWaveControlPlaneProjections,
+  waveControlPlaneLogPath,
+} from "./control-plane.mjs";
+import { readWaveLedger } from "./ledger.mjs";
+import { readRunResultEnvelope } from "./gate-engine.mjs";
+import { buildResumePlan, clearWaveRelaunchPlan } from "./retry-engine.mjs";
+import { readWaveProofRegistry } from "./proof-registry.mjs";
+import { buildDependencySnapshot, buildRequestAssignments, syncAssignmentRecords } from "./routing-state.mjs";
+import { buildLanePaths } from "./shared.mjs";
+import { reduceWaveState } from "./wave-state-reducer.mjs";
+import { parseWaveFiles } from "./wave-files.mjs";
+import { writeWaveRetryOverride } from "./retry-control.mjs";
+import { resolveWaveRoleBindings } from "./role-helpers.mjs";
+
+function coordinationLogPath(lanePaths, waveNumber) {
+  return path.join(lanePaths.coordinationDir, `wave-${waveNumber}.jsonl`);
+}
+
+function ledgerPath(lanePaths, waveNumber) {
+  return path.join(lanePaths.ledgerDir, `wave-${waveNumber}.json`);
+}
+
+function coordinationTriagePath(lanePaths, waveNumber) {
+  return path.join(lanePaths.feedbackTriageDir, `wave-${waveNumber}.jsonl`);
+}
+
+function appendCoordinationStatusUpdate(logPath, record, status, options = {}) {
+  return appendCoordinationRecord(logPath, {
+    ...record,
+    status,
+    summary: options.summary || record.summary,
+    detail: options.detail || record.detail,
+    source: options.source || "operator",
+  });
+}
+
+function appendTriageEscalationUpdateIfPresent(lanePaths, waveNumber, record) {
+  const triagePath = coordinationTriagePath(lanePaths, waveNumber);
+  if (!fs.existsSync(triagePath) || record?.kind !== "human-escalation") {
+    return;
+  }
+  appendCoordinationRecord(triagePath, record);
+}
+
+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;
+}
+
+function taskRunInfoForAgent(lanePaths, wave, agent, proofRegistry) {
+  const safeName = `wave-${wave.wave}-${agent.slug}`;
+  return {
+    agent,
+    lane: lanePaths.lane,
+    wave: wave.wave,
+    resultsDir: lanePaths.resultsDir,
+    logPath: path.join(lanePaths.logsDir, `${safeName}.log`),
+    statusPath: path.join(lanePaths.statusDir, `${safeName}.status`),
+    proofRegistry,
+  };
+}
+
+function feedbackLinkMatchesRecord(record, requestId) {
+  const normalizedRequestId = String(requestId || "").trim();
+  if (!normalizedRequestId) {
+    return false;
+  }
+  if (String(record?.id || "").trim() === normalizedRequestId) {
+    return true;
+  }
+  if (
+    Array.isArray(record?.artifactRefs) &&
+    record.artifactRefs.some((ref) => String(ref || "").trim() === normalizedRequestId)
+  ) {
+    return true;
+  }
+  if (
+    Array.isArray(record?.dependsOn) &&
+    record.dependsOn.some((value) => String(value || "").trim() === normalizedRequestId)
+  ) {
+    return true;
+  }
+  return false;
+}
+
+function linkedClarificationIdsForRecords(records) {
+  const ids = new Set();
+  for (const record of records || []) {
+    if (record?.kind === "clarification-request" && record?.id) {
+      ids.add(record.id);
+      continue;
+    }
+    const closureCondition = String(record?.closureCondition || "").trim();
+    if (closureCondition.startsWith("clarification:")) {
+      ids.add(closureCondition.slice("clarification:".length));
+    }
+  }
+  return [...ids].filter(Boolean);
+}
+
+export function resolveFeedbackLinkedCoordination({
+  lanePaths,
+  wave,
+  requestId,
+  operator = "human-operator",
+  detail = "",
+}) {
+  const logPath = coordinationLogPath(lanePaths, wave.wave);
+  const state = readMaterializedCoordinationState(logPath);
+  const resolvedRecords = [];
+
+  const directlyLinked = state.latestRecords.filter((record) =>
+    isOpenCoordinationStatus(record.status) && feedbackLinkMatchesRecord(record, requestId),
+  );
+
+  for (const record of directlyLinked) {
+    const updated = appendCoordinationStatusUpdate(logPath, record, "resolved", {
+      detail: detail || `Resolved after answered human input ${requestId}.`,
+      summary: record.summary,
+      source: operator,
+    });
+    resolvedRecords.push(updated);
+    appendTriageEscalationUpdateIfPresent(lanePaths, wave.wave, updated);
+  }
+
+  const nextState = readMaterializedCoordinationState(logPath);
+  const clarificationIds = linkedClarificationIdsForRecords([
+    ...directlyLinked,
+    ...resolvedRecords,
+  ]);
+  for (const clarificationId of clarificationIds) {
+    const clarification = nextState.byId.get(clarificationId);
+    if (!clarification || !isOpenCoordinationStatus(clarification.status)) {
+      continue;
+    }
+    const updatedClarification = appendCoordinationStatusUpdate(logPath, clarification, "resolved", {
+      detail: detail || `Resolved after answered human input ${requestId}.`,
+      summary: clarification.summary,
+      source: operator,
+    });
+    resolvedRecords.push(updatedClarification);
+  }
+
+  const resolvedState = readMaterializedCoordinationState(logPath);
+  for (const clarificationId of clarificationIds) {
+    const linkedRequests = clarificationLinkedRequests(resolvedState, clarificationId).filter((entry) =>
+      isOpenCoordinationStatus(entry.status),
+    );
+    for (const linked of linkedRequests) {
+      const updatedLinked = appendCoordinationStatusUpdate(logPath, linked, "resolved", {
+        detail: `Resolved via clarification ${clarificationId}.`,
+        summary: linked.summary,
+        source: operator,
+      });
+      resolvedRecords.push(updatedLinked);
+    }
+    for (const escalation of (resolvedState.humanEscalations || []).filter(
+      (entry) =>
+        isOpenCoordinationStatus(entry.status) &&
+        entry.closureCondition === clarificationClosureCondition(clarificationId),
+    )) {
+      const updatedEscalation = appendCoordinationStatusUpdate(logPath, escalation, "resolved", {
+        detail: detail || `Resolved via clarification ${clarificationId}.`,
+        summary: escalation.summary,
+        source: operator,
+      });
+      resolvedRecords.push(updatedEscalation);
+      appendTriageEscalationUpdateIfPresent(lanePaths, wave.wave, updatedEscalation);
+    }
+  }
+
+  const assignmentState = readMaterializedCoordinationState(logPath);
+  const ledger = readWaveLedger(ledgerPath(lanePaths, wave.wave)) || { phase: "planned" };
+  const assignments = buildRequestAssignments({
+    coordinationState: assignmentState,
+    agents: wave.agents,
+    ledger,
+    capabilityRouting: lanePaths.capabilityRouting,
+  });
+  syncAssignmentRecords(logPath, {
+    lane: lanePaths.lane,
+    wave: wave.wave,
+    assignments,
+  });
+
+  return {
+    resolvedRecords,
+    clarificationIds,
+  };
+}
+
+export function buildResumePlanFromDisk({ lanePaths, wave }) {
+  const proofRegistry = readWaveProofRegistry(lanePaths, wave.wave);
+  const agentRuns = wave.agents.map((agent) =>
+    taskRunInfoForAgent(lanePaths, wave, agent, proofRegistry),
+  );
+  const agentEnvelopes = Object.fromEntries(
+    agentRuns
+      .map((runInfo) => {
+        const envelopeResult = readRunResultEnvelope(runInfo, wave, { mode: "compat" });
+        return [runInfo.agent.agentId, envelopeResult?.valid ? envelopeResult.envelope : null];
+      })
+      .filter(([, envelope]) => Boolean(envelope)),
+  );
+  const coordinationState = readMaterializedCoordinationState(coordinationLogPath(lanePaths, wave.wave));
+  const feedbackRequests = readWaveHumanFeedbackRequests({
+    feedbackRequestsDir: lanePaths.feedbackRequestsDir,
+    lane: lanePaths.lane,
+    waveNumber: wave.wave,
+    agentIds: wave.agents.map((agent) => agent.agentId),
+    orchestratorId: "",
+  });
+  const ledger = readWaveLedger(ledgerPath(lanePaths, wave.wave)) || { phase: "planned" };
+  const dependencySnapshot = buildDependencySnapshot({
+    dirPath: lanePaths.crossLaneDependenciesDir,
+    lane: lanePaths.lane,
+    waveNumber: wave.wave,
+    agents: wave.agents,
+    ledger,
+    capabilityRouting: lanePaths.capabilityRouting,
+  });
+  const reducerState = reduceWaveState({
+    controlPlaneEvents: readControlPlaneEvents(waveControlPlaneLogPath(lanePaths, wave.wave)),
+    coordinationRecords: coordinationState.latestRecords || [],
+    agentEnvelopes,
+    waveDefinition: wave,
+    dependencyTickets: dependencySnapshot,
+    feedbackRequests,
+    laneConfig: {
+      lane: lanePaths.lane,
+      ...resolveWaveRoleBindings(wave, lanePaths, wave.agents),
+      validationMode: "live",
+      evalTargets: wave.evalTargets,
+      benchmarkCatalogPath: lanePaths.laneProfile?.paths?.benchmarkCatalogPath,
+      laneProfile: lanePaths.laneProfile,
+      requireIntegrationStewardFromWave: lanePaths.requireIntegrationStewardFromWave,
+      capabilityRouting: lanePaths.capabilityRouting,
+    },
+  });
+  return buildResumePlan(reducerState, {
+    waveDefinition: wave,
+    lanePaths,
+  });
+}
+
+export function maybeWriteAutoResumeRequest({
+  lanePaths,
+  wave,
+  requestedBy = "human-operator",
+  reason = "",
+}) {
+  const controlState = readWaveControlPlaneState(lanePaths, wave.wave);
+  if (controlState.activeAttempt || controlState.activeRerunRequest) {
+    return null;
+  }
+  const resumePlan = buildResumePlanFromDisk({ lanePaths, wave });
+  if (!resumePlan.canResume || resumePlan.reason === "human-request") {
+    return { resumePlan, request: null };
+  }
+  if (resumePlan.resumeFromPhase === "completed") {
+    return { resumePlan, request: null };
+  }
+  clearWaveRelaunchPlan(lanePaths, wave.wave);
+  const payload = {
+    requestedBy,
+    reason:
+      reason ||
+      `Auto continuation after answered human input; resume from ${resumePlan.resumeFromPhase}.`,
+    preserveReusableAgentIds: resumePlan.reusableAgentIds,
+    reuseProofBundleIds: resumePlan.reusableProofBundleIds,
+    applyOnce: true,
+  };
+  if (resumePlan.resumeFromPhase === "implementation") {
+    payload.selectedAgentIds = resumePlan.invalidatedAgentIds;
+  } else {
+    payload.resumePhase = resumePlan.resumeFromPhase;
+  }
+  const request = writeWaveRetryOverride(lanePaths, wave.wave, payload);
+  return { resumePlan, request };
+}
+
+export function answerHumanInputAndReconcile({
+  lanePaths,
+  wave,
+  requestId,
+  answeredPayload,
+  operator = "human-operator",
+}) {
+  const detail =
+    `Resolved after human input ${requestId} was answered by ${operator}` +
+    (answeredPayload?.response?.text ? `: ${answeredPayload.response.text}` : ".");
+  const resolution = resolveFeedbackLinkedCoordination({
+    lanePaths,
+    wave,
+    requestId,
+    operator,
+    detail,
+  });
+  syncWaveControlPlaneProjections(
+    lanePaths,
+    wave.wave,
+    readWaveControlPlaneState(lanePaths, wave.wave),
+  );
+  const autoResume = maybeWriteAutoResumeRequest({
+    lanePaths,
+    wave,
+    requestedBy: operator,
+    reason: `Auto continuation after answered human input ${requestId}.`,
+  });
+  return {
+    resolution,
+    autoResume,
+  };
+}
+
+export function answerHumanInputByRequest({
+  lane,
+  waveNumber,
+  requestId,
+  operator = "human-operator",
+  runId = null,
+}) {
+  const lanePaths = buildLanePaths(lane, { adhocRunId: runId || null });
+  const wave = loadWave(lanePaths, waveNumber);
+  return answerHumanInputAndReconcile({
+    lanePaths,
+    wave,
+    requestId,
+    operator,
+  });
+}

package/scripts/wave-orchestrator/human-input-workflow.mjs

@@ -287,3 +287,107 @@ export function computeHumanInputMetrics(requests) {
       : null,
   };
 }
+
+export function buildHumanFeedbackWorkflowUpdate({
+  request,
+  lane,
+  waveNumber,
+  existingEscalation = null,
+}) {
+  const question = request?.question || "n/a";
+  const context = request?.context ? `; context=${request.context}` : "";
+  const agentId = request?.agentId || "human";
+  const responseOperator = request?.responseOperator || "human-operator";
+  const responseText = request?.responseText || "(empty response)";
+  if (request?.status === "pending") {
+    return {
+      combinedEvent: {
+        level: "warn",
+        agentId: request.agentId,
+        message: `Human feedback requested (${request.id}): ${question}`,
+      },
+      coordinationNotice: {
+        event: "human_feedback_requested",
+        waves: [waveNumber],
+        status: "waiting-human",
+        details: `request_id=${request.id}; agent=${request.agentId}; question=${question}${context}`,
+        actionRequested:
+          `Launcher operator should ask or answer in the parent session, then run: pnpm exec wave control task act answer --lane ${lane} --wave ${waveNumber} --id ${request.id} --response "<answer>" --operator "<name>"`,
+      },
+      consoleLines: [
+        `[human-feedback] wave=${waveNumber} agent=${request.agentId} request=${request.id} pending: ${question}`,
+        `[human-feedback] respond with: pnpm exec wave control task act answer --lane ${lane} --wave ${waveNumber} --id ${request.id} --response "<answer>" --operator "<name>"`,
+      ],
+      coordinationUpdates: [
+        {
+          id: request.id,
+          lane,
+          wave: waveNumber,
+          agentId,
+          kind: "human-feedback",
+          targets: request.agentId ? [`agent:${request.agentId}`] : [],
+          priority: "high",
+          summary: question,
+          detail: request.context || "",
+          status: "open",
+          source: "feedback",
+        },
+      ],
+      triageUpdates: [],
+    };
+  }
+  if (request?.status === "answered") {
+    const escalationId = `escalation-${request.id}`;
+    const escalationRecord = {
+      id: escalationId,
+      lane,
+      wave: waveNumber,
+      agentId,
+      kind: "human-escalation",
+      targets:
+        existingEscalation?.targets ||
+        (request.agentId ? [`agent:${request.agentId}`] : []),
+      dependsOn: existingEscalation?.dependsOn || [],
+      closureCondition: existingEscalation?.closureCondition || "",
+      priority: "high",
+      summary: question,
+      detail: responseText,
+      artifactRefs: [request.id],
+      status: "resolved",
+      source: "feedback",
+    };
+    return {
+      combinedEvent: {
+        level: "info",
+        agentId: request.agentId,
+        message: `Human feedback answered (${request.id}) by ${responseOperator}: ${responseText}`,
+      },
+      coordinationNotice: {
+        event: "human_feedback_answered",
+        waves: [waveNumber],
+        status: "resolved",
+        details: `request_id=${request.id}; agent=${request.agentId}; operator=${responseOperator}; response=${responseText}`,
+        actionRequested: "None",
+      },
+      consoleLines: [],
+      coordinationUpdates: [
+        escalationRecord,
+        {
+          id: request.id,
+          lane,
+          wave: waveNumber,
+          agentId,
+          kind: "human-feedback",
+          targets: request.agentId ? [`agent:${request.agentId}`] : [],
+          priority: "high",
+          summary: question,
+          detail: responseText,
+          status: "resolved",
+          source: "feedback",
+        },
+      ],
+      triageUpdates: [escalationRecord],
+    };
+  }
+  return null;
+}

package/scripts/wave-orchestrator/implementation-engine.mjs

@@ -0,0 +1,120 @@
+import { readStatusCodeIfPresent } from "./dashboard-state.mjs";
+import { resolveRetryOverrideRuns } from "./retry-control.mjs";
+import {
+  applyPersistedRelaunchPlan,
+  persistedRelaunchPlanMatchesCurrentState,
+  resolveRelaunchRuns,
+  selectInitialWaveRuns,
+  selectReusablePreCompletedAgentIds,
+} from "./retry-engine.mjs";
+
+export function planInitialWaveAttempt({
+  agentRuns,
+  lanePaths,
+  wave,
+  derivedState,
+  proofRegistry,
+  retryOverride,
+  persistedRelaunchPlan,
+}) {
+  const preCompletedAgentIds = selectReusablePreCompletedAgentIds(agentRuns, lanePaths, {
+    retryOverride,
+    wave,
+    derivedState,
+    proofRegistry,
+  });
+  const staleCompletedAgentIds = agentRuns
+    .filter(
+      (run) =>
+        !preCompletedAgentIds.has(run.agent.agentId) &&
+        readStatusCodeIfPresent(run.statusPath) === 0,
+    )
+    .map((run) => run.agent.agentId);
+
+  const persistedPlanIsCurrent =
+    !persistedRelaunchPlan ||
+    persistedRelaunchPlanMatchesCurrentState(
+      agentRuns,
+      persistedRelaunchPlan,
+      lanePaths,
+      wave,
+    );
+  const effectivePersistedPlan = persistedPlanIsCurrent ? persistedRelaunchPlan : null;
+  const availableRuns = agentRuns.filter((run) => !preCompletedAgentIds.has(run.agent.agentId));
+  const persistedRuns = applyPersistedRelaunchPlan(
+    availableRuns,
+    effectivePersistedPlan,
+    lanePaths,
+    wave,
+  );
+  const overrideResolution = resolveRetryOverrideRuns(availableRuns, retryOverride, lanePaths, wave);
+
+  let selectedRuns = [];
+  let source = "initial";
+  if (overrideResolution.unknownAgentIds.length === 0 && overrideResolution.runs.length > 0) {
+    selectedRuns = overrideResolution.runs;
+    source = "override";
+  } else if (persistedRuns.length > 0) {
+    selectedRuns = persistedRuns;
+    source = "persisted-relaunch";
+  } else {
+    selectedRuns = selectInitialWaveRuns(availableRuns, lanePaths, wave);
+  }
+
+  return {
+    preCompletedAgentIds,
+    staleCompletedAgentIds,
+    availableRuns,
+    selectedRuns,
+    source,
+    overrideResolution,
+    persistedPlanIsCurrent,
+    shouldClearPersistedRelaunchPlan: Boolean(
+      persistedRelaunchPlan && !persistedPlanIsCurrent,
+    ),
+  };
+}
+
+export function planRetryWaveAttempt({
+  agentRuns,
+  failures,
+  derivedState,
+  lanePaths,
+  wave,
+  retryOverride,
+  waveState = null,
+}) {
+  const relaunchResolution = resolveRelaunchRuns(
+    agentRuns,
+    failures,
+    derivedState,
+    lanePaths,
+    wave,
+    waveState ? { waveState } : {},
+  );
+  const overrideResolution = resolveRetryOverrideRuns(
+    agentRuns,
+    retryOverride,
+    lanePaths,
+    wave,
+  );
+
+  let selectedRuns = [];
+  let source = "retry";
+  let barrier = relaunchResolution.barrier || null;
+  if (overrideResolution.unknownAgentIds.length === 0 && overrideResolution.runs.length > 0) {
+    selectedRuns = overrideResolution.runs;
+    barrier = null;
+    source = "override";
+  } else if (!barrier) {
+    selectedRuns = relaunchResolution.runs;
+  }
+
+  return {
+    selectedRuns,
+    source,
+    barrier,
+    relaunchResolution,
+    overrideResolution,
+  };
+}

package/scripts/wave-orchestrator/launcher-runtime.mjs

@@ -14,6 +14,7 @@ import { readStatusCodeIfPresent } from "./dashboard-state.mjs";
 import { buildExecutorLaunchSpec } from "./executors.mjs";
 import { hashAgentPromptFingerprint, prefetchContext7ForSelection } from "./context7.mjs";
 import { killTmuxSessionIfExists } from "./terminals.mjs";
+import { resolveWaveRoleBindings } from "./role-helpers.mjs";
 import {
   resolveAgentSkills,
   summarizeResolvedSkills,
@@ -71,6 +72,7 @@ export async function launchAgentSession(lanePaths, params, { runTmuxFn }) {
     inboxText,
     promptOverride = "",
     orchestratorId,
+    attempt = 1,
     agentRateLimitRetries,
     agentRateLimitBaseDelaySeconds,
     agentRateLimitMaxDelaySeconds,
@@ -105,6 +107,7 @@ export async function launchAgentSession(lanePaths, params, { runTmuxFn }) {
   const prompt =
     String(promptOverride || "").trim() ||
     buildExecutionPrompt({
+      ...resolveWaveRoleBindings(resolvedWaveDefinition, lanePaths),
       lane: lanePaths.lane,
       wave,
       agent,
@@ -120,10 +123,6 @@ export async function launchAgentSession(lanePaths, params, { runTmuxFn }) {
       evalTargets: resolvedWaveDefinition.evalTargets,
       benchmarkCatalogPath: lanePaths.laneProfile?.paths?.benchmarkCatalogPath,
       sharedPlanDocs: lanePaths.sharedPlanDocs,
-      contQaAgentId: lanePaths.contQaAgentId,
-      contEvalAgentId: lanePaths.contEvalAgentId,
-      integrationAgentId: lanePaths.integrationAgentId,
-      documentationAgentId: lanePaths.documentationAgentId,
     });
   const promptHash = hashAgentPromptFingerprint(agent);
   fs.writeFileSync(promptPath, `${prompt}\n`, "utf8");
@@ -216,8 +215,8 @@ export async function launchAgentSession(lanePaths, params, { runTmuxFn }) {
     `export WAVE_EXECUTOR_MODE=${shellQuote(resolvedExecutorMode)}`,
     ...executionLines,
     `node -e ${shellQuote(
-      "const fs=require('node:fs'); const statusPath=process.argv[1]; const payload={code:Number(process.argv[2]),promptHash:process.argv[3]||null,orchestratorId:process.argv[4]||null,completedAt:new Date().toISOString()}; fs.writeFileSync(statusPath, JSON.stringify(payload, null, 2)+'\\n', 'utf8');",
-    )} ${shellQuote(statusPath)} "$status" ${shellQuote(promptHash)} ${shellQuote(orchestratorId || "")}`,
+      "const fs=require('node:fs'); const statusPath=process.argv[1]; const payload={code:Number(process.argv[2]),promptHash:process.argv[3]||null,orchestratorId:process.argv[4]||null,attempt:Number(process.argv[5])||1,completedAt:new Date().toISOString()}; fs.writeFileSync(statusPath, JSON.stringify(payload, null, 2)+'\\n', 'utf8');",
+    )} ${shellQuote(statusPath)} "$status" ${shellQuote(promptHash)} ${shellQuote(orchestratorId || "")} ${shellQuote(String(attempt || 1))}`,
     `echo "[${lanePaths.lane}-wave-launcher] ${sessionName} finished with code $status"`,
     "exec bash -l",
   ].join("\n");