@chllming/wave-orchestration 0.9.1 → 0.9.3

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/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;
@@ -248,7 +253,7 @@ export function buildExecutionPrompt({
       ? [
           `- Because you are Agent ${contQaAgentId}, your cont-QA report must end with exactly one standalone line in the form \`Verdict: PASS\`, \`Verdict: CONCERNS\`, or \`Verdict: BLOCKED\`.`,
           "- Also emit one matching structured marker in your terminal output: `[wave-verdict] pass`, `[wave-verdict] concerns`, or `[wave-verdict] blocked`.",
-          "- Emit one final structured gate marker: `[wave-gate] architecture=<pass|concerns|blocked> integration=<pass|concerns|blocked> durability=<pass|concerns|blocked> live=<pass|concerns|blocked> docs=<pass|concerns|blocked> detail=<short-note>`.",
+          "- Emit one final structured gate marker: `[wave-gate] architecture=<pass|concerns|blocked|gap> integration=<pass|concerns|blocked|gap> durability=<pass|concerns|blocked|gap> live=<pass|concerns|blocked|gap> docs=<pass|concerns|blocked|gap> detail=<short-note>`.",
           "- Only use `Verdict: PASS` when the wave is coherent enough to unblock the next wave.",
           `- Do not declare PASS until the documentation gate is closed: impacted implementation-owned docs must exist, ${sharedPlanDocList} must reflect plan-affecting outcomes, and no unresolved architecture-versus-plans drift remains.`,
           "- If shared-plan reconciliation is still active inside the wave, require the exact remaining doc delta and an explicit `closed` or `no-change` note from the documentation steward or named owner before finalizing. Do not treat ownership handoff alone as the blocker.",
@@ -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:",