@bitkyc08/opencodex 2.7.9-preview.20260712.1 → 2.7.9

package/src/claude/outbound.ts

@@ -54,7 +54,7 @@ export function anthropicErrorResponse(status: number, message: string, type?: s
  * subtract the full cache detail (devlog 070 — subtracting reads only inflated the
  * non-cached input Claude Code displays by the write share).
  */
-export function anthropicUsage(usage: unknown): Rec {
+export function anthropicUsage(usage: unknown, webSearchRequests = 0): Rec {
   const u = isRec(usage) ? usage : {};
   const details = isRec(u.input_tokens_details) ? u.input_tokens_details : {};
   const cached = typeof details.cached_tokens === "number" ? details.cached_tokens : 0;
@@ -66,6 +66,8 @@ export function anthropicUsage(usage: unknown): Rec {
     output_tokens: output,
     cache_read_input_tokens: cached,
     cache_creation_input_tokens: cacheWrite,
+    // Only successful searches are billed/counted (Anthropic contract; Claude Code cost accounting).
+    ...(webSearchRequests > 0 ? { server_tool_use: { web_search_requests: webSearchRequests } } : {}),
   };
 }
 
@@ -73,6 +75,37 @@ function sseFrame(name: string, data: Rec): string {
   return `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`;
 }
 
+/**
+ * Map a Responses `web_search_call` item to its Anthropic pair: the server_tool_use
+ * input (query/queries) and the web_search_tool_result content (hits, or the error
+ * object when the search failed). Shared by the SSE and JSON translation paths.
+ */
+function webSearchPairFromItem(item: Rec): { id: string; input: Rec; resultContent: unknown; completed: boolean } {
+  const action = isRec(item.action) ? item.action : {};
+  const queries = Array.isArray(action.queries)
+    ? action.queries.filter((q): q is string => typeof q === "string" && q.length > 0)
+    : [];
+  const query = typeof action.query === "string" ? action.query : "";
+  const input: Rec = queries.length > 1 ? { queries } : { query: queries[0] ?? query };
+  const completed = item.status !== "failed";
+  let resultContent: unknown;
+  if (completed) {
+    const hits: Rec[] = [];
+    if (Array.isArray(item.sources)) {
+      for (const s of item.sources) {
+        if (isRec(s) && typeof s.url === "string" && s.url.length > 0) {
+          hits.push({ type: "web_search_result", title: typeof s.title === "string" ? s.title : "", url: s.url });
+        }
+      }
+    }
+    resultContent = hits;
+  } else {
+    resultContent = { type: "web_search_tool_result_error", error_code: "unavailable" };
+  }
+  const id = typeof item.id === "string" && item.id.length > 0 ? item.id : `srvtoolu_${uuid()}`;
+  return { id, input, resultContent, completed };
+}
+
 function messageSnapshot(model: string): Rec {
   return {
     id: `msg_${uuid()}`,
@@ -105,13 +138,16 @@ export function responsesSseToAnthropicSse(
   let buffer = "";
   let started = false;
   let terminated = false;
+  let cancelled = false;
   let blockIndex = 0;
   let open: OpenBlock | null = null;
   let sawToolUse = false;
+  let webSearchRequests = 0;
   let pingTimer: ReturnType<typeof setInterval> | undefined;
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
 
   return new ReadableStream<Uint8Array>({
-    async start(controller) {
+    start(controller) {
       const emit = (name: string, data: Rec) => controller.enqueue(encoder.encode(sseFrame(name, data)));
       const ensureStarted = () => {
         if (started) return;
@@ -162,7 +198,7 @@ export function responsesSseToAnthropicSse(
         emit("message_delta", {
           type: "message_delta",
           delta: { stop_reason: stopReason, stop_sequence: null },
-          usage: anthropicUsage(usage),
+          usage: anthropicUsage(usage, webSearchRequests),
         });
         emit("message_stop", { type: "message_stop" });
       };
@@ -232,7 +268,35 @@ export function responsesSseToAnthropicSse(
           }
           case "response.output_item.done": {
             const item = isRec(data.item) ? data.item : null;
-            if (!open || !item) break;
+            if (!item) break;
+            // Server-side web search (native passthrough or sidecar bridge): translate the
+            // finished call into the Anthropic pair Claude Code natively parses —
+            // server_tool_use (query via input_json_delta) + web_search_tool_result.
+            // Never marks sawToolUse (stop_reason stays end_turn unless a real tool ran).
+            if (item.type === "web_search_call") {
+              ensureStarted();
+              closeOpenBlock();
+              const pair = webSearchPairFromItem(item);
+              const toolIndex = blockIndex++;
+              emit("content_block_start", {
+                type: "content_block_start", index: toolIndex,
+                content_block: { type: "server_tool_use", id: pair.id, name: "web_search" },
+              });
+              emit("content_block_delta", {
+                type: "content_block_delta", index: toolIndex,
+                delta: { type: "input_json_delta", partial_json: JSON.stringify(pair.input) },
+              });
+              emit("content_block_stop", { type: "content_block_stop", index: toolIndex });
+              const resultIndex = blockIndex++;
+              emit("content_block_start", {
+                type: "content_block_start", index: resultIndex,
+                content_block: { type: "web_search_tool_result", tool_use_id: pair.id, content: pair.resultContent },
+              });
+              emit("content_block_stop", { type: "content_block_stop", index: resultIndex });
+              if (pair.completed) webSearchRequests++;
+              break;
+            }
+            if (!open) break;
             // Close the matching open block (message/reasoning items close implicitly on
             // the next block; function_call items must close here so tool input parses).
             if (open.kind === "tool_use" && item.type === "function_call") closeOpenBlock();
@@ -267,46 +331,49 @@ export function responsesSseToAnthropicSse(
         }
       };
 
-      const reader = upstream.getReader();
-      try {
-        for (;;) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          buffer += decoder.decode(value, { stream: true });
-          let sep: number;
-          while ((sep = buffer.indexOf("\n\n")) !== -1) {
-            const rawFrame = buffer.slice(0, sep);
-            buffer = buffer.slice(sep + 2);
-            let eventName = "";
-            let dataLine = "";
-            for (const line of rawFrame.split("\n")) {
-              if (line.startsWith("event: ")) eventName = line.slice(7).trim();
-              else if (line.startsWith("data: ")) dataLine += line.slice(6);
+      reader = upstream.getReader();
+      void (async () => {
+        try {
+          for (;;) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            buffer += decoder.decode(value, { stream: true });
+            let sep: number;
+            while ((sep = buffer.indexOf("\n\n")) !== -1) {
+              const rawFrame = buffer.slice(0, sep);
+              buffer = buffer.slice(sep + 2);
+              let eventName = "";
+              let dataLine = "";
+              for (const line of rawFrame.split("\n")) {
+                if (line.startsWith("event: ")) eventName = line.slice(7).trim();
+                else if (line.startsWith("data: ")) dataLine += line.slice(6);
+              }
+              if (!eventName || !dataLine) continue;
+              let data: unknown;
+              try { data = JSON.parse(dataLine); } catch { continue; }
+              if (!isRec(data)) continue;
+              if (terminated) continue;
+              handleFrame(eventName, data);
             }
-            if (!eventName || !dataLine) continue;
-            let data: unknown;
-            try { data = JSON.parse(dataLine); } catch { continue; }
-            if (!isRec(data)) continue;
-            if (terminated) continue;
-            handleFrame(eventName, data);
           }
+          // EOF without a terminal frame is a TRUNCATION, not success (devlog 100:
+          // gateways that close such streams politely hand Claude Code an empty/partial
+          // turn with no retryable error — CLIProxyAPI#2189 failure pattern). Fail closed
+          // with a mid-stream Anthropic error event so the client can retry.
+          if (!cancelled) fail(502, "upstream stream ended before a terminal frame (truncated response)");
+        } catch (err) {
+          fail(500, err instanceof Error ? err.message : String(err));
+        } finally {
+          if (pingTimer !== undefined) clearInterval(pingTimer);
+          reader.releaseLock();
+          if (!cancelled) controller.close();
         }
-        // EOF without a terminal frame is a TRUNCATION, not success (devlog 100:
-        // gateways that close such streams politely hand Claude Code an empty/partial
-        // turn with no retryable error — CLIProxyAPI#2189 failure pattern). Fail closed
-        // with a mid-stream Anthropic error event so the client can retry.
-        fail(502, "upstream stream ended before a terminal frame (truncated response)");
-      } catch (err) {
-        fail(500, err instanceof Error ? err.message : String(err));
-      } finally {
-        if (pingTimer !== undefined) clearInterval(pingTimer);
-        reader.releaseLock();
-        controller.close();
-      }
+      })();
     },
     cancel(reason) {
+      cancelled = true;
       if (pingTimer !== undefined) clearInterval(pingTimer);
-      return upstream.cancel(reason);
+      return reader?.cancel(reason);
     },
   });
 }
@@ -317,6 +384,7 @@ export function responsesJsonToAnthropicMessage(json: unknown, model: string): R
   const output = Array.isArray(body.output) ? body.output : [];
   const content: Rec[] = [];
   let sawToolUse = false;
+  let webSearchRequests = 0;
 
   for (const raw of output) {
     if (!isRec(raw)) continue;
@@ -361,6 +429,14 @@ export function responsesJsonToAnthropicMessage(json: unknown, model: string): R
         });
         break;
       }
+      case "web_search_call": {
+        // Server-side search: emit the Anthropic pair. Does NOT set sawToolUse.
+        const pair = webSearchPairFromItem(raw);
+        content.push({ type: "server_tool_use", id: pair.id, name: "web_search", input: pair.input });
+        content.push({ type: "web_search_tool_result", tool_use_id: pair.id, content: pair.resultContent });
+        if (pair.completed) webSearchRequests++;
+        break;
+      }
       default:
         break;
     }
@@ -379,7 +455,7 @@ export function responsesJsonToAnthropicMessage(json: unknown, model: string): R
     model,
     stop_reason: stopReason,
     stop_sequence: null,
-    usage: anthropicUsage(body.usage),
+    usage: anthropicUsage(body.usage, webSearchRequests),
   };
 }
 
@@ -402,7 +478,8 @@ export async function collectAnthropicMessage(stream: ReadableStream<Uint8Array>
 
   const closeBlock = () => {
     if (!openBlock) return;
-    if (openBlock.type === "tool_use") {
+    // server_tool_use streams its query via input_json_delta exactly like tool_use (audit F3).
+    if (openBlock.type === "tool_use" || openBlock.type === "server_tool_use") {
       try { openBlock.input = toolJson.length > 0 ? JSON.parse(toolJson) : {}; } catch { openBlock.input = {}; }
     }
     content.push(openBlock);

package/src/cli/claude.ts

@@ -3,7 +3,8 @@
  *
  * Mirrors `ccr code` UX (devlog/260711_claude_inbound/020, 003 E1/E2/E5/G1):
  * ensures the proxy is running, injects the Anthropic env slots, then execs the
- * `claude` CLI with stdio inherited. User-exported env always wins.
+ * `claude` CLI with stdio inherited. User-exported env wins except when a stale
+ * loopback opencodex base URL points at a different proxy port.
  */
 import { spawn } from "node:child_process";
 import { loadConfig } from "../config";
@@ -20,7 +21,8 @@ export interface ClaudeLaunchEnv {
 /**
  * Pure env assembly (unit-tested): never sets ANTHROPIC_API_KEY (setting both
  * token vars triggers Claude Code's auth-conflict warning, 003 E1), and never
- * overrides variables the user already exported.
+ * overrides variables the user already exported, apart from stale loopback
+ * ANTHROPIC_BASE_URL values owned by a previous opencodex launch.
  */
 export function buildClaudeEnv(config: OcxConfig, port: number, base: ClaudeLaunchEnv, contextWindows: Record<string, number> = {}): ClaudeLaunchEnv {
   const env: ClaudeLaunchEnv = { ...base };
@@ -30,6 +32,20 @@ export function buildClaudeEnv(config: OcxConfig, port: number, base: ClaudeLaun
     env[name] = value;
   };
   setDefault("ANTHROPIC_BASE_URL", `http://127.0.0.1:${port}`);
+  const existingBaseUrl = env.ANTHROPIC_BASE_URL;
+  if (existingBaseUrl) {
+    try {
+      const parsed = new URL(existingBaseUrl);
+      const isLoopback = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
+      if (isLoopback && parsed.port !== "" && Number(parsed.port) !== port) {
+        const replacement = `http://127.0.0.1:${port}`;
+        console.error(`⚠ Replacing stale opencodex ANTHROPIC_BASE_URL ${existingBaseUrl} with ${replacement}.`);
+        env.ANTHROPIC_BASE_URL = replacement;
+      }
+    } catch {
+      // Preserve user-provided values that are not parseable URLs.
+    }
+  }
   // Subscription-preserving default (teamclaude --no-mitm / Vercel gateway pattern):
   // setting ANTHROPIC_AUTH_TOKEN/API_KEY disables claude.ai connectors and overrides
   // the user's Claude login. Only inject a token when the proxy actually requires an
@@ -137,9 +153,25 @@ export async function cmdClaude(args: string[]): Promise<number> {
   const env = buildClaudeEnv(config, port, process.env, contextWindows);
   // Pre-write the CLI's gateway-model cache (devlog 030): without a token the CLI
   // never refreshes it, so the picker would keep showing yesterday's aliases.
-  await refreshGatewayModelCacheFromProxy(port);
+  try {
+    const cachePath = await refreshGatewayModelCacheFromProxy(port);
+    if (cachePath === null) {
+      console.error("⚠ Gateway model cache could not be refreshed; the model picker may be stale.");
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`⚠ Gateway model cache could not be refreshed: ${message}`);
+  }
   // Sync roster agents (devlog 070): subagentModels + self -> ~/.claude/agents/ocx-*.md.
-  injectClaudeAgentDefs(config, contextWindows);
+  try {
+    const written = injectClaudeAgentDefs(config, contextWindows);
+    if (written === null) {
+      console.error("⚠ Claude agent definitions could not be synced; check ~/.claude/agents permissions.");
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`⚠ Claude agent definitions could not be synced: ${message}`);
+  }
   return await new Promise<number>(resolve => {
     const child = spawn("claude", args, { stdio: "inherit", env: env as NodeJS.ProcessEnv });
     child.on("error", (err: NodeJS.ErrnoException) => {

package/src/config.ts

@@ -3,9 +3,41 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSy
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import * as z from "zod/v4";
+import { hardenSecretDir, hardenSecretPath } from "./lib/windows-secret-acl";
+import { providerDestinationConfigError } from "./lib/destination-policy";
 import type { OcxConfig } from "./types";
 
 let _atomicSeq = 0;
+
+interface AtomicRenameIO {
+  platform: NodeJS.Platform;
+  rename: (source: string, destination: string) => void;
+  sleep: (milliseconds: number) => void;
+}
+
+export function renameAtomicFile(
+  source: string,
+  destination: string,
+  io: AtomicRenameIO = {
+    platform: process.platform,
+    rename: renameSync,
+    sleep: Bun.sleepSync,
+  },
+): void {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      io.rename(source, destination);
+      return;
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      const transientWindowsError = io.platform === "win32"
+        && (code === "EBUSY" || code === "EPERM" || code === "EACCES");
+      if (!transientWindowsError || attempt >= 2) throw error;
+      io.sleep(25 * (attempt + 1));
+    }
+  }
+}
+
 /**
  * Write a file atomically (temp + rename) so concurrent writers — e.g. `ocx stop` and the
  * proxy's own shutdown handler both restoring Codex — can never leave a half-written file.
@@ -13,7 +45,7 @@ let _atomicSeq = 0;
 export function atomicWriteFile(path: string, content: string): void {
   const tmp = `${path}.ocx.${process.pid}.${++_atomicSeq}.tmp`;
   writeFileSync(tmp, content, { encoding: "utf-8", mode: 0o600 });
-  renameSync(tmp, path);
+  renameAtomicFile(tmp, path);
 }
 
 /**
@@ -54,6 +86,7 @@ const warnedConfigFallbacks = new Set<string>();
 const providerConfigSchema = z.object({
   adapter: z.string().min(1),
   baseUrl: z.string().min(1),
+  allowPrivateNetwork: z.boolean().optional(),
 }).passthrough();
 
 const RESERVED_PROVIDER_NAMES = new Set(["__proto__", "prototype", "constructor"]);
@@ -128,6 +161,15 @@ const configSchema = z.object({
         path: ["providers", name, "baseUrl"],
         message: baseUrlError,
       });
+    } else {
+      const destinationError = providerDestinationConfigError(name, provider);
+      if (destinationError) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["providers", name, "baseUrl"],
+          message: destinationError,
+        });
+      }
     }
     const headersError = providerHeadersConfigError((provider as { headers?: unknown }).headers);
     if (headersError) {
@@ -178,15 +220,20 @@ export function hardenConfigDir(): void {
   const dir = getConfigDir();
   if (existsSync(dir)) {
     try { chmodSync(dir, 0o700); } catch { /* best-effort */ }
+    if (process.platform === "win32") {
+      hardenSecretDir(dir, { required: false });
+    }
   }
 }
 
 export function hardenExistingSecret(path: string): void {
   if (existsSync(path)) {
     try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+    if (process.platform === "win32") {
+      hardenSecretPath(path, { required: false });
+    }
   }
 }
-
 export function loadConfig(): OcxConfig {
   const dir = getConfigDir();
   const configPath = getConfigPath();
@@ -305,7 +352,11 @@ export function saveConfig(config: OcxConfig): void {
   } else {
     try { chmodSync(dir, 0o700); } catch { /* best-effort on existing dir */ }
   }
-  atomicWriteFile(getConfigPath(), JSON.stringify(config, null, 2) + "\n");
+  if (process.platform === "win32") {
+    hardenSecretDir(dir, { required: true });
+  }
+  const configPath = getConfigPath();
+  atomicWriteFile(configPath, JSON.stringify(config, null, 2) + "\n");
 }
 
 export function websocketsEnabled(config: Pick<OcxConfig, "websockets">): boolean {

package/src/lib/destination-policy.ts

@@ -0,0 +1,167 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { getProviderRegistryEntry } from "../providers/registry";
+import type { OcxProviderConfig } from "../types";
+
+const BLOCKED_METADATA_HOSTS = new Set([
+  "instance-data.ec2.internal",
+  "metadata.azure.internal",
+  "metadata.google.internal",
+]);
+
+const BLOCKED_METADATA_IPV4 = new Set([
+  "100.100.100.200",
+  "169.254.169.254",
+  "169.254.170.2",
+]);
+
+const BLOCKED_METADATA_IPV6 = new Set([
+  "fd00:ec2::254",
+]);
+
+type DestinationKind =
+  | "public"
+  | "hostname"
+  | "localhost"
+  | "loopback"
+  | "private"
+  | "link-local"
+  | "unspecified"
+  | "metadata";
+
+interface DestinationAssessment {
+  kind: DestinationKind;
+  detail: string;
+}
+
+function normalizeHostname(hostname: string): string {
+  const trimmed = hostname.trim().toLowerCase().replace(/\.+$/, "");
+  return trimmed.startsWith("[") && trimmed.endsWith("]") ? trimmed.slice(1, -1) : trimmed;
+}
+
+function parseIpv4(hostname: string): number[] | null {
+  const parts = hostname.split(".");
+  if (parts.length !== 4) return null;
+  const octets = parts.map(part => Number(part));
+  return octets.every(octet => Number.isInteger(octet) && octet >= 0 && octet <= 255) ? octets : null;
+}
+
+function classifyIpv4(hostname: string): DestinationAssessment {
+  if (BLOCKED_METADATA_IPV4.has(hostname)) return { kind: "metadata", detail: "blocked metadata endpoint" };
+  const octets = parseIpv4(hostname);
+  if (!octets) return { kind: "public", detail: "public IP" };
+  const [a, b, c] = octets;
+  if (a === 127) return { kind: "loopback", detail: "loopback address" };
+  if (a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 100 && b >= 64 && b <= 127)) {
+    return { kind: "private", detail: "private-network address" };
+  }
+  if (a === 169 && b === 254) return { kind: "link-local", detail: "link-local address" };
+  if (a === 0) return { kind: "unspecified", detail: "unspecified address" };
+  // Reserved / non-public ranges (review finding, PR #96): protocol-assignment,
+  // documentation, benchmark, multicast, and reserved-future space never name a
+  // legitimate provider endpoint.
+  if (a === 192 && b === 0 && (c === 0 || c === 2)) return { kind: "private", detail: "reserved address" };
+  if (a === 198 && (b === 18 || b === 19)) return { kind: "private", detail: "benchmark address" };
+  if (a === 198 && b === 51 && c === 100) return { kind: "private", detail: "documentation address" };
+  if (a === 203 && b === 0 && c === 113) return { kind: "private", detail: "documentation address" };
+  if (a >= 224) return { kind: "private", detail: "multicast/reserved address" };
+  return { kind: "public", detail: "public IP" };
+}
+
+function firstIpv6Hextet(hostname: string): number | null {
+  const head = hostname.split(":")[0];
+  if (!head) return 0;
+  const parsed = Number.parseInt(head, 16);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+
+function classifyIpv6(hostname: string): DestinationAssessment {
+  if (BLOCKED_METADATA_IPV6.has(hostname)) return { kind: "metadata", detail: "blocked metadata endpoint" };
+  const mappedIpv4 = hostname.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i)?.[1];
+  if (mappedIpv4) return classifyIpv4(mappedIpv4);
+  if (hostname === "::1") return { kind: "loopback", detail: "loopback address" };
+  if (hostname === "::") return { kind: "unspecified", detail: "unspecified address" };
+  const hextet = firstIpv6Hextet(hostname);
+  if (hextet === null) return { kind: "public", detail: "public IP" };
+  if (hextet >= 0xfc00 && hextet <= 0xfdff) return { kind: "private", detail: "private-network address" };
+  if (hextet >= 0xfe80 && hextet <= 0xfebf) return { kind: "link-local", detail: "link-local address" };
+  return { kind: "public", detail: "public IP" };
+}
+
+function assessDestination(baseUrl: string): DestinationAssessment | null {
+  try {
+    const parsed = new URL(baseUrl.trim());
+    const hostname = normalizeHostname(parsed.hostname);
+    if (!hostname) return null;
+    if (BLOCKED_METADATA_HOSTS.has(hostname)) return { kind: "metadata", detail: "blocked metadata endpoint" };
+    if (hostname === "localhost" || hostname.endsWith(".localhost")) {
+      return { kind: "localhost", detail: "localhost destination" };
+    }
+    const ipKind = isIP(hostname);
+    if (ipKind === 4) return classifyIpv4(hostname);
+    if (ipKind === 6) return classifyIpv6(hostname);
+    return { kind: "hostname", detail: "hostname destination" };
+  } catch {
+    return null;
+  }
+}
+
+function registryAllowsPrivateNetwork(name: string): boolean {
+  return getProviderRegistryEntry(name)?.allowPrivateNetworkByDefault === true;
+}
+
+export function providerDestinationConfigError(name: string, provider: Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork">): string | null {
+  const assessment = assessDestination(provider.baseUrl);
+  if (!assessment) return null;
+  if (assessment.kind === "public" || assessment.kind === "hostname") return null;
+  if (assessment.kind === "metadata") return "baseUrl targets a blocked metadata endpoint";
+  if (registryAllowsPrivateNetwork(name)) return null;
+  if (provider.allowPrivateNetwork === true) return null;
+  return `baseUrl points to a ${assessment.detail}; set allowPrivateNetwork:true only for intentionally local/self-hosted providers`;
+}
+
+export function assertProviderDestinationAllowed(name: string, provider: Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork">): void {
+  const error = providerDestinationConfigError(name, provider);
+  if (error) throw new Error(`provider ${name} ${error}`);
+}
+
+/**
+ * Async companion to {@link providerDestinationConfigError} for hostname destinations:
+ * resolves A/AAAA records and classifies every address, so a hostname that points at
+ * loopback/private/metadata space is caught at provider write time (review finding,
+ * PR #96 — the sync path must stay literal-only because the router hot path and
+ * config load are synchronous). DNS failures return null: config-time validation is
+ * advisory and must not hard-fail offline startups. DNS rebinding after validation is
+ * a recorded residual for this loopback proxy (devlog 260712_pr_batch_landing 000).
+ */
+export async function providerDestinationResolvedError(
+  name: string,
+  provider: Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork">,
+): Promise<string | null> {
+  const syncError = providerDestinationConfigError(name, provider);
+  if (syncError) return syncError;
+  let hostname: string;
+  try {
+    hostname = normalizeHostname(new URL(provider.baseUrl.trim()).hostname);
+  } catch {
+    return null;
+  }
+  if (!hostname || isIP(hostname) !== 0 || hostname === "localhost" || hostname.endsWith(".localhost")) {
+    return null; // literals and localhost are fully handled by the sync path
+  }
+  if (registryAllowsPrivateNetwork(name) || provider.allowPrivateNetwork === true) return null;
+  let addresses: { address: string }[];
+  try {
+    addresses = await lookup(hostname, { all: true, verbatim: true });
+  } catch {
+    return null; // unresolvable now ≠ malicious; the provider simply won't connect
+  }
+  for (const { address } of addresses) {
+    const ipKind = isIP(address);
+    const assessment = ipKind === 4 ? classifyIpv4(address) : ipKind === 6 ? classifyIpv6(normalizeHostname(address)) : null;
+    if (!assessment || assessment.kind === "public") continue;
+    if (assessment.kind === "metadata") return `baseUrl hostname ${hostname} resolves to a blocked metadata endpoint (${address})`;
+    return `baseUrl hostname ${hostname} resolves to a ${assessment.detail} (${address}); set allowPrivateNetwork:true only for intentionally local/self-hosted providers`;
+  }
+  return null;
+}

package/src/lib/injection-debug-log.ts

@@ -0,0 +1,34 @@
+/** In-memory ring buffer of multi-agent guidance-injection / effort-cap log lines.
+ *
+ * Injection debug lines were previously console-only, so the GUI had an "Injection log"
+ * toggle with nothing to display. This buffer mirrors the provider debug buffer so the
+ * management API and GUI can tail injection lines the same way. Callers keep their own
+ * `isInjectionDebugEnabled()` guard; this module only stores what it is given. */
+
+import type { DebugLogEntry } from "./debug-log-buffer";
+
+const MAX_LINES = 2_000;
+const buffer: DebugLogEntry[] = [];
+let nextSeq = 1;
+
+/** Append a line to the injection buffer and echo it to the server console. */
+export function injectionDebugLog(line: string): void {
+  const entry: DebugLogEntry = { seq: nextSeq++, at: Date.now(), line };
+  buffer.push(entry);
+  if (buffer.length > MAX_LINES) buffer.splice(0, buffer.length - MAX_LINES);
+  console.log(line);
+}
+
+export function getInjectionDebugLogEntries(options?: { after?: number; limit?: number }): DebugLogEntry[] {
+  const after = options?.after ?? 0;
+  const limit = options?.limit ?? 500;
+  const filtered = after > 0 ? buffer.filter(entry => entry.seq > after) : buffer;
+  if (filtered.length <= limit) return filtered;
+  return filtered.slice(-limit);
+}
+
+/** Test isolation. */
+export function resetInjectionDebugLogBufferForTests(): void {
+  buffer.length = 0;
+  nextSeq = 1;
+}