@chllming/wave-orchestration 0.9.0 → 0.9.2

package/scripts/wave-orchestrator/context7.mjs

@@ -9,6 +9,15 @@ import {
   sleep,
   writeJsonAtomic,
 } from "./shared.mjs";
+import {
+  DEFAULT_CONTEXT7_API_KEY_ENV_VAR,
+  DEFAULT_WAVE_CONTROL_ENDPOINT,
+} from "./config.mjs";
+import {
+  isDefaultWaveControlEndpoint,
+  readJsonResponse,
+  resolveWaveControlAuthToken,
+} from "./provider-runtime.mjs";
 
 export const DEFAULT_CONTEXT7_BUNDLE_INDEX_PATH = path.join(
   REPO_ROOT,
@@ -277,16 +286,10 @@ function renderPrefetchedContextText({ selection, results, budget }) {
   return trimContextText(sections.join("\n\n"), budget);
 }
 
-async function requestContext7(fetchImpl, url, { apiKey, expectText = false, maxRetries = 3 } = {}) {
+async function requestContext7(fetchImpl, request, { expectText = false, maxRetries = 3 } = {}) {
   let lastError = null;
   for (let attempt = 0; attempt < maxRetries; attempt += 1) {
-    const response = await fetchImpl(url, {
-      method: "GET",
-      headers: {
-        Authorization: `Bearer ${apiKey}`,
-        Accept: expectText ? "text/plain, application/json" : "application/json",
-      },
-    });
+    const response = await request();
     if (response.ok) {
       return expectText ? response.text() : response.json();
     }
@@ -296,7 +299,7 @@ async function requestContext7(fetchImpl, url, { apiKey, expectText = false, max
       : 0;
     let payload = null;
     try {
-      payload = await response.json();
+      payload = await readJsonResponse(response, null);
     } catch {
       payload = null;
     }
@@ -311,7 +314,193 @@ async function requestContext7(fetchImpl, url, { apiKey, expectText = false, max
   throw lastError || new Error("Context7 request failed.");
 }
 
-async function resolveLibraryId(fetchImpl, library, selection, apiKey) {
+function buildDirectContext7Requester(fetchImpl, apiKey) {
+  return {
+    async search(params) {
+      const url = `${CONTEXT7_SEARCH_URL}?${params.toString()}`;
+      return requestContext7(
+        fetchImpl,
+        () =>
+          fetchImpl(url, {
+            method: "GET",
+            headers: {
+              Authorization: `Bearer ${apiKey}`,
+              Accept: "application/json",
+            },
+          }),
+      );
+    },
+    async context(params) {
+      const url = `${CONTEXT7_CONTEXT_URL}?${params.toString()}`;
+      return requestContext7(
+        fetchImpl,
+        () =>
+          fetchImpl(url, {
+            method: "GET",
+            headers: {
+              Authorization: `Bearer ${apiKey}`,
+              Accept: "text/plain, application/json",
+            },
+          }),
+        { expectText: true },
+      );
+    },
+  };
+}
+
+function buildBrokerContext7Requester(fetchImpl, lanePaths) {
+  const waveControl = lanePaths?.waveControl || lanePaths?.laneProfile?.waveControl || {};
+  const endpoint = String(waveControl.endpoint || DEFAULT_WAVE_CONTROL_ENDPOINT).trim();
+  if (!endpoint || isDefaultWaveControlEndpoint(endpoint)) {
+    throw new Error("Context7 broker mode requires an owned Wave Control endpoint.");
+  }
+  const authToken = resolveWaveControlAuthToken(waveControl);
+  if (!authToken) {
+    throw new Error("WAVE_API_TOKEN is not set; skipping Context7 broker prefetch.");
+  }
+  const baseEndpoint = endpoint.replace(/\/$/, "");
+  return {
+    async search(params) {
+      return requestContext7(
+        fetchImpl,
+        () =>
+          fetchImpl(`${baseEndpoint}/providers/context7/search?${params.toString()}`, {
+            method: "GET",
+            headers: {
+              authorization: `Bearer ${authToken}`,
+              accept: "application/json",
+            },
+          }),
+      );
+    },
+    async context(params) {
+      return requestContext7(
+        fetchImpl,
+        () =>
+          fetchImpl(`${baseEndpoint}/providers/context7/context?${params.toString()}`, {
+            method: "GET",
+            headers: {
+              authorization: `Bearer ${authToken}`,
+              accept: "text/plain, application/json",
+            },
+          }),
+        { expectText: true },
+      );
+    },
+  };
+}
+
+function buildHybridContext7Requester({
+  lanePaths,
+  fetchImpl,
+  directApiKey,
+  directApiKeyEnvVar,
+}) {
+  const brokerRequester = buildBrokerContext7Requester(fetchImpl, lanePaths);
+  let directRequester = null;
+  let activeProviderMode = "broker";
+  let fallbackWarning = "";
+
+  const resolveDirectRequester = () => {
+    if (directRequester) {
+      return directRequester;
+    }
+    if (!directApiKey) {
+      throw new Error(`${directApiKeyEnvVar} is not set; skipping Context7 prefetch.`);
+    }
+    directRequester = buildDirectContext7Requester(fetchImpl, directApiKey);
+    return directRequester;
+  };
+
+  const runWithFallback = async (method, params) => {
+    if (activeProviderMode === "direct") {
+      return resolveDirectRequester()[method](params);
+    }
+    try {
+      return await brokerRequester[method](params);
+    } catch (brokerError) {
+      let fallbackRequester = null;
+      try {
+        fallbackRequester = resolveDirectRequester();
+      } catch (fallbackUnavailableError) {
+        throw new Error(
+          `Context7 broker request failed and direct fallback is unavailable: ${brokerError instanceof Error ? brokerError.message : String(brokerError)}; ${fallbackUnavailableError instanceof Error ? fallbackUnavailableError.message : String(fallbackUnavailableError)}`,
+        );
+      }
+      activeProviderMode = "direct";
+      fallbackWarning =
+        fallbackWarning ||
+        `Context7 broker request failed; fell back to direct auth: ${brokerError instanceof Error ? brokerError.message : String(brokerError)}`;
+      try {
+        return await fallbackRequester[method](params);
+      } catch (fallbackError) {
+        throw new Error(
+          `Context7 broker request failed and direct fallback also failed: ${brokerError instanceof Error ? brokerError.message : String(brokerError)}; ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`,
+        );
+      }
+    }
+  };
+
+  return {
+    requester: {
+      search(params) {
+        return runWithFallback("search", params);
+      },
+      context(params) {
+        return runWithFallback("context", params);
+      },
+    },
+    providerMode: "broker",
+    getProviderMode() {
+      return activeProviderMode;
+    },
+    getWarning() {
+      return fallbackWarning;
+    },
+  };
+}
+
+function resolveContext7Requester({
+  lanePaths,
+  fetchImpl,
+  apiKey,
+  apiKeyEnvVar = DEFAULT_CONTEXT7_API_KEY_ENV_VAR,
+}) {
+  const provider = lanePaths?.externalProviders?.context7 || {};
+  const mode = String(provider.mode || "direct").trim().toLowerCase();
+  const directApiKey = apiKey || process.env[provider.apiKeyEnvVar || apiKeyEnvVar] || "";
+  const direct = () => {
+    if (!directApiKey) {
+      throw new Error(`${provider.apiKeyEnvVar || apiKeyEnvVar} is not set; skipping Context7 prefetch.`);
+    }
+    return {
+      requester: buildDirectContext7Requester(fetchImpl, directApiKey),
+      providerMode: "direct",
+    };
+  };
+  const broker = () => ({
+    requester: buildBrokerContext7Requester(fetchImpl, lanePaths),
+    providerMode: "broker",
+  });
+  if (mode === "broker") {
+    return broker();
+  }
+  if (mode === "hybrid") {
+    try {
+      return buildHybridContext7Requester({
+        lanePaths,
+        fetchImpl,
+        directApiKey,
+        directApiKeyEnvVar: provider.apiKeyEnvVar || apiKeyEnvVar,
+      });
+    } catch {
+      return direct();
+    }
+  }
+  return direct();
+}
+
+async function resolveLibraryId(requester, library, selection) {
   if (library.libraryId) {
     return {
       libraryId: library.libraryId,
@@ -322,9 +511,7 @@ async function resolveLibraryId(fetchImpl, library, selection, apiKey) {
     libraryName: library.libraryName,
     query: selection.query || library.queryHint || library.libraryName,
   });
-  const results = await requestContext7(fetchImpl, `${CONTEXT7_SEARCH_URL}?${params.toString()}`, {
-    apiKey,
-  });
+  const results = await requester.search(params);
   if (!Array.isArray(results) || results.length === 0) {
     throw new Error(`Context7 search returned no matches for "${library.libraryName}".`);
   }
@@ -334,8 +521,8 @@ async function resolveLibraryId(fetchImpl, library, selection, apiKey) {
   };
 }
 
-async function fetchLibraryContext(fetchImpl, library, selection, apiKey) {
-  const resolvedLibrary = await resolveLibraryId(fetchImpl, library, selection, apiKey);
+async function fetchLibraryContext(requester, library, selection) {
+  const resolvedLibrary = await resolveLibraryId(requester, library, selection);
   const query = compactSingleLine(
     [selection.query, library.queryHint].filter(Boolean).join(". Focus: "),
     320,
@@ -345,10 +532,7 @@ async function fetchLibraryContext(fetchImpl, library, selection, apiKey) {
     query,
     type: "txt",
   });
-  const text = await requestContext7(fetchImpl, `${CONTEXT7_CONTEXT_URL}?${params.toString()}`, {
-    apiKey,
-    expectText: true,
-  });
+  const text = await requester.context(params);
   return {
     libraryId: resolvedLibrary.libraryId,
     libraryName: resolvedLibrary.libraryName,
@@ -360,6 +544,7 @@ async function fetchLibraryContext(fetchImpl, library, selection, apiKey) {
 export async function prefetchContext7ForSelection(
   selection,
   {
+    lanePaths = null,
     cacheDir,
     apiKey = process.env.CONTEXT7_API_KEY || "",
     fetchImpl = globalThis.fetch,
@@ -397,13 +582,18 @@ export async function prefetchContext7ForSelection(
     };
   }
   if (!apiKey) {
-    return {
-      mode: "missing-key",
-      selection,
-      promptText: "",
-      snippetHash: "",
-      warning: "CONTEXT7_API_KEY is not set; skipping Context7 prefetch.",
-    };
+    const providerMode = String(lanePaths?.externalProviders?.context7?.mode || "direct")
+      .trim()
+      .toLowerCase();
+    if (providerMode === "direct") {
+      return {
+        mode: "missing-key",
+        selection,
+        promptText: "",
+        snippetHash: "",
+        warning: "CONTEXT7_API_KEY is not set; skipping Context7 prefetch.",
+      };
+    }
   }
 
   ensureDirectory(cacheDir);
@@ -427,9 +617,15 @@ export async function prefetchContext7ForSelection(
   }
 
   try {
+    const requesterState = resolveContext7Requester({
+      lanePaths,
+      fetchImpl,
+      apiKey,
+    });
+    const { requester } = requesterState;
     const results = [];
     for (const library of selection.libraries) {
-      const result = await fetchLibraryContext(fetchImpl, library, selection, apiKey);
+      const result = await fetchLibraryContext(requester, library, selection);
       if (result.text) {
         results.push(result);
       }
@@ -450,12 +646,18 @@ export async function prefetchContext7ForSelection(
       promptText,
       snippetHash,
     });
+    const providerMode =
+      typeof requesterState.getProviderMode === "function"
+        ? requesterState.getProviderMode()
+        : requesterState.providerMode;
+    const warning =
+      typeof requesterState.getWarning === "function" ? requesterState.getWarning() : "";
     return {
-      mode: "fetched",
+      mode: providerMode === "broker" ? "fetched-broker" : "fetched",
       selection,
       promptText,
       snippetHash,
-      warning: "",
+      warning,
     };
   } catch (error) {
     return {

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

@@ -42,11 +42,12 @@ import {
 import { readWaveRelaunchPlanSnapshot, readWaveRetryOverride, resolveRetryOverrideAgentIds, writeWaveRetryOverride, clearWaveRetryOverride } from "./retry-control.mjs";
 import { flushWaveControlQueue, readWaveControlQueueState } from "./wave-control-client.mjs";
 import { readAgentExecutionSummary, validateImplementationSummary } from "./agent-state.mjs";
-import { isContEvalReportOnlyAgent, isSecurityReviewAgent } from "./role-helpers.mjs";
+import { isContEvalReportOnlyAgent, isSecurityReviewAgentForLane } from "./role-helpers.mjs";
 import {
   buildSignalStatusLine,
   syncWaveSignalProjections,
 } from "./signals.mjs";
+import { summarizeSupervisorStateForWave } from "./supervisor-cli.mjs";
 
 function printUsage() {
   console.log(`Usage:
@@ -366,7 +367,8 @@ function buildLogicalAgents({
       proofRegistry || { entries: [] },
     );
     const proofValidation =
-      !isSecurityReviewAgent(agent) && !isContEvalReportOnlyAgent(agent, { contEvalAgentId: lanePaths.contEvalAgentId })
+      !isSecurityReviewAgentForLane(agent, lanePaths) &&
+      !isContEvalReportOnlyAgent(agent, { contEvalAgentId: lanePaths.contEvalAgentId })
         ? validateImplementationSummary(agent, summary ? summary : null)
         : { ok: statusRecord?.code === 0, statusCode: statusRecord?.code === 0 ? "pass" : "pending" };
     const targetedTasks = tasks.filter(
@@ -385,7 +387,7 @@ function buildLogicalAgents({
     const satisfiedByStatus =
       statusRecord?.code === 0 &&
       (proofValidation.ok ||
-        isSecurityReviewAgent(agent) ||
+        isSecurityReviewAgentForLane(agent, lanePaths) ||
         isContEvalReportOnlyAgent(agent, { contEvalAgentId: lanePaths.contEvalAgentId }));
     let state = "planned";
     let reason = "";
@@ -404,7 +406,7 @@ function buildLogicalAgents({
         lanePaths.integrationAgentId || "A8",
         lanePaths.documentationAgentId || "A9",
         lanePaths.contQaAgentId || "A0",
-      ].includes(agent.agentId) || isSecurityReviewAgent(agent)
+      ].includes(agent.agentId) || isSecurityReviewAgentForLane(agent, lanePaths)
         ? "closed"
         : "satisfied";
       reason = "Completed wave preserves the latest satisfied agent state.";
@@ -425,7 +427,7 @@ function buildLogicalAgents({
         lanePaths.integrationAgentId || "A8",
         lanePaths.documentationAgentId || "A9",
         lanePaths.contQaAgentId || "A0",
-      ].includes(agent.agentId) || isSecurityReviewAgent(agent)
+      ].includes(agent.agentId) || isSecurityReviewAgentForLane(agent, lanePaths)
         ? "closed"
         : "satisfied";
       reason = "Latest attempt satisfied current control-plane state.";
@@ -657,6 +659,12 @@ export function buildControlStatusPayload({ lanePaths, wave, agentId = "" }) {
   const controlState = readWaveControlPlaneState(lanePaths, wave.wave);
   const proofRegistry = readWaveProofRegistry(lanePaths, wave.wave) || { entries: [] };
   const relaunchPlan = readWaveRelaunchPlanSnapshot(lanePaths, wave.wave);
+  const supervisor = summarizeSupervisorStateForWave(lanePaths, wave.wave, {
+    agentId,
+  });
+  const forwardedClosureGaps = Array.isArray(relaunchPlan?.forwardedClosureGaps)
+    ? relaunchPlan.forwardedClosureGaps
+    : [];
   const rerunRequest = controlState.activeRerunRequest
     ? {
         ...controlState.activeRerunRequest,
@@ -718,6 +726,8 @@ export function buildControlStatusPayload({ lanePaths, wave, agentId = "" }) {
     selectionSource: selection.source,
     rerunRequest,
     relaunchPlan,
+    forwardedClosureGaps,
+    supervisor,
     nextTimer: isCompletedPhase(phase) ? null : nextTaskDeadline(tasks),
     activeAttempt: controlState.activeAttempt,
   };
@@ -758,6 +768,33 @@ function printStatus(payload) {
     console.log(buildSignalStatusLine(payload.signals.wave, payload));
   }
   console.log(`blocking=${blocking}`);
+  if (payload.supervisor) {
+    console.log(
+      `supervisor=${payload.supervisor.terminalDisposition || payload.supervisor.status} run_id=${payload.supervisor.runId} launcher_pid=${payload.supervisor.launcherPid || "none"}`,
+    );
+    if (payload.supervisor.sessionBackend || payload.supervisor.recoveryState || payload.supervisor.resumeAction) {
+      console.log(
+        `supervisor-backend=${payload.supervisor.sessionBackend || "unknown"} recovery=${payload.supervisor.recoveryState || "unknown"} resume=${payload.supervisor.resumeAction || "none"}`,
+      );
+    }
+    if ((payload.supervisor.agentRuntimeSummary || []).length > 0) {
+      console.log("supervisor-runtime:");
+      for (const record of payload.supervisor.agentRuntimeSummary) {
+        console.log(
+          `- ${record.agentId || "unknown"} ${record.terminalDisposition || "unknown"} pid=${record.pid || "none"} backend=${record.sessionBackend || "process"} attach=${record.attachMode || "log-tail"} heartbeat=${record.lastHeartbeatAt || "n/a"}`,
+        );
+      }
+    }
+  }
+  if ((payload.forwardedClosureGaps || []).length > 0) {
+    console.log("forwarded-closure-gaps:");
+    for (const gap of payload.forwardedClosureGaps) {
+      const targets = Array.isArray(gap.targets) && gap.targets.length > 0 ? gap.targets.join(",") : "none";
+      console.log(
+        `- ${gap.stageKey} agent=${gap.agentId || "unknown"} attempt=${gap.attempt ?? "n/a"} targets=${targets}${gap.detail ? ` detail=${gap.detail}` : ""}`,
+      );
+    }
+  }
   if (payload.nextTimer) {
     console.log(`next-timer=${payload.nextTimer.kind} ${payload.nextTimer.taskId} at ${payload.nextTimer.at}`);
   }

package/scripts/wave-orchestrator/coordination.mjs

@@ -197,6 +197,8 @@ export function buildExecutionPrompt({
   inboxPath = null,
   inboxText = "",
   context7 = null,
+  corridorContextPath = null,
+  corridorContextText = "",
   componentPromotions = null,
   evalTargets = null,
   benchmarkCatalogPath = null,
@@ -215,6 +217,9 @@ export function buildExecutionPrompt({
     ? path.relative(REPO_ROOT, sharedSummaryPath)
     : null;
   const relativeInboxPath = inboxPath ? path.relative(REPO_ROOT, inboxPath) : null;
+  const relativeCorridorContextPath = corridorContextPath
+    ? path.relative(REPO_ROOT, corridorContextPath)
+    : null;
   const relativeSignalStatePath = signalStatePath
     ? path.relative(REPO_ROOT, signalStatePath)
     : null;
@@ -537,6 +542,12 @@ export function buildExecutionPrompt({
           `Agent inbox repo-relative path: ${relativeInboxPath}`,
         ]
       : []),
+    ...(corridorContextPath
+      ? [
+          `Corridor context absolute path: ${corridorContextPath}`,
+          `Corridor context repo-relative path: ${relativeCorridorContextPath}`,
+        ]
+      : []),
     ...(signalStatePath
       ? [
           `Signal state absolute path: ${signalStatePath}`,
@@ -552,6 +563,9 @@ export function buildExecutionPrompt({
     ...(inboxText
       ? ["Current agent inbox:", "```markdown", inboxText, "```", ""]
       : []),
+    ...(corridorContextText
+      ? ["Current Corridor context:", "```text", corridorContextText, "```", ""]
+      : []),
     ...(signalStatePath
       ? [
           "Long-running signal loop:",