@jiayunxie/aerial 0.2.1 → 0.2.2

package/src/cli/service-command.js

@@ -0,0 +1,120 @@
+import { serviceInstall, serviceRestart, serviceStart, serviceStatus, serviceStop, serviceUninstall } from "../service/index.js";
+import { printServiceDiagnostics, printServiceWarning } from "./output.js";
+
+export function printServiceUninstallResult(r, { prefix = "Service uninstall" } = {}) {
+  if (r.note === "no service installed") console.log(`${prefix}: no service installed`);
+  else if (r.ok) console.log(`${prefix}: ok (${r.platform})`);
+  else {
+    console.log(`${prefix}: FAILED (${r.reason || "see stderr"})`);
+    if (r.message) console.log(`  ${r.message}`);
+    else console.log(`  Retry with: aerial service uninstall`);
+  }
+  if (r.delete?.stderr) console.log(`  schtasks stderr: ${r.delete.stderr.trim()}`);
+  if (r.bootout?.stderr) console.log(`  bootout stderr: ${r.bootout.stderr.trim()}`);
+}
+
+async function runServiceCliAction(action, render) {
+  try {
+    const result = await action();
+    render(result);
+    process.exitCode = result.ok ? 0 : 1;
+  } catch (err) {
+    console.error(err.message);
+    process.exitCode = 1;
+  }
+}
+
+function printServiceStatus(status) {
+  console.log(`Aerial: http://${status.config.host}:${status.config.port}  (platform: ${status.platform})`);
+  if (status.supported === false) {
+    console.log(`service: unsupported on ${status.platform}`);
+    console.log(`summary: ${status.summary}`);
+    process.exitCode = 1;
+    return;
+  }
+  const svc = status.service;
+  const stateLine = svc.loaded ? "running" : (svc.installed ? "installed (not running)" : "not installed");
+  console.log(`service: ${stateLine}`);
+  if (svc.pid) console.log(`  pid: ${svc.pid}`);
+  if (svc.status) console.log(`  win status: ${svc.status}`);
+  if (svc.lastExitStatus !== undefined) console.log(`  last exit: ${svc.lastExitStatus}`);
+  const h = status.health;
+  let healthLine;
+  if (h.aerial && h.supervisor === "service-managed") healthLine = "ok (Aerial, service-managed)";
+  else if (h.aerial && h.supervisor === "foreground") healthLine = "ok (Aerial, foreground)";
+  else if (h.portConflict) healthLine = `port conflict (${h.conflictReason})`;
+  else if (h.ok) healthLine = "ok";
+  else healthLine = `unreachable (${h.error || `http ${h.status}`})`;
+  console.log(`health:  ${healthLine}`);
+  console.log(`summary: ${status.summary}`);
+  console.log(`logs:    ${status.logs.dir}`);
+  console.log(`  primary: ${status.logs.primary.exists ? `${status.logs.primary.size} bytes` : "missing"}  ${status.logs.primary.file}`);
+  console.log(`  stdio:   ${status.logs.stdio.exists ? `${status.logs.stdio.size} bytes` : "missing"}  ${status.logs.stdio.file}`);
+  console.log(`auth:    api_key=${status.auth.api_key.state}  github_token=${status.auth.github_token.state}`);
+}
+
+export async function runServiceCli(subcommand, rest) {
+  if (subcommand === "install") {
+    await runServiceCliAction(serviceInstall, (r) => {
+      if (r.ok && r.note) console.log(`Service install: ${r.note} (${r.platform}).`);
+      else if (r.ok) console.log(`Service installed (${r.platform}).`);
+      else console.log(`Service install: FAILED (${r.reason || "unknown"}): ${r.message || ""}`);
+      if (r.file) console.log(`  unit: ${r.file}`);
+      if (r.taskName) console.log(`  task: ${r.taskName}`);
+      if (r.wrapper) console.log(`  wrapper: ${r.wrapper}`);
+      if (r.bootstrap?.stderr) console.log(`  bootstrap stderr: ${r.bootstrap.stderr.trim()}`);
+      if (r.create?.stderr) console.log(`  schtasks stderr: ${r.create.stderr.trim()}`);
+      if (r.run?.stderr) console.log(`  schtasks /Run stderr: ${r.run.stderr.trim()}`);
+      printServiceDiagnostics(r.diagnostics);
+      printServiceWarning(r);
+    });
+    return;
+  }
+  if (subcommand === "start") {
+    await runServiceCliAction(serviceStart, (r) => {
+      if (r.ok && r.note) console.log(`Service start: ${r.note} (${r.platform})`);
+      else if (r.ok) console.log(`Service start: ok (${r.platform})`);
+      else console.log(`Service start: FAILED (${r.reason || `status=${r.status}`})${r.message ? ": " + r.message : ""}`);
+      if (r.stderr) console.log(`  ${r.stderr.trim()}`);
+      printServiceDiagnostics(r.diagnostics);
+      printServiceWarning(r);
+    });
+    return;
+  }
+  if (subcommand === "stop") {
+    await runServiceCliAction(serviceStop, (r) => {
+      if (r.note) console.log(`Service stop: ${r.note} (${r.platform})`);
+      else if (r.ok) console.log(`Service stop: ok (${r.platform})`);
+      else console.log(`Service stop: FAILED (status=${r.status})`);
+      if (r.stderr) console.log(`  ${r.stderr.trim()}`);
+    });
+    return;
+  }
+  if (subcommand === "restart") {
+    await runServiceCliAction(serviceRestart, (r) => {
+      if (!r.ok && r.reason === "stop_failed") console.log(`Service restart: FAILED on stop; start not attempted`);
+      else if (r.ok) console.log(`Service restart: ok`);
+      else console.log(`Service restart: FAILED`);
+      if (r.stop?.stderr) console.log(`  stop: ${r.stop.stderr.trim()}`);
+      if (r.start?.stderr) console.log(`  start: ${r.start.stderr.trim()}`);
+      printServiceWarning(r);
+    });
+    return;
+  }
+  if (subcommand === "uninstall") {
+    await runServiceCliAction(serviceUninstall, printServiceUninstallResult);
+    return;
+  }
+  if (subcommand === "status") {
+    const status = await serviceStatus();
+    if (rest.includes("--json")) {
+      console.log(JSON.stringify(status, null, 2));
+      process.exitCode = status.supported === false ? 1 : 0;
+      return;
+    }
+    printServiceStatus(status);
+    return;
+  }
+  console.error(`Unknown service subcommand: ${subcommand}. Use install, start, stop, restart, status, or uninstall.`);
+  process.exitCode = 1;
+}

package/src/cli/setup-command.js

@@ -0,0 +1,122 @@
+import { loadConfig } from "../shared/config.js";
+import { configPath } from "../shared/paths.js";
+import { restoreAllClients, restoreClient, setupClaude, setupCodex, setupStatus } from "../setup/index.js";
+import { chooseSetupModel, formatModelChoices } from "./model-selection.js";
+import { assertValidEffort, chooseSetupEffort, formatEffortSelection } from "./setup-selection.js";
+import { requiredArgValue } from "./args.js";
+import { claudeApiKeyHelper, codexAuthCommand } from "./runtime-auth.js";
+import { printRestoreResults, printSetupCompletionSummary } from "./output.js";
+
+async function selectSetupOptions(target, route, args) {
+  const explicitEffort = requiredArgValue(args, "--effort");
+  if (explicitEffort !== undefined) assertValidEffort(explicitEffort);
+  const selected = await chooseSetupModel({ target, route, explicitModel: requiredArgValue(args, "--model") });
+  if (!selected.displayed) {
+    for (const line of formatModelChoices({ target, route, choices: selected.choices, selectedModel: selected.model, source: selected.source, recommended: selected.recommended })) {
+      console.log(line);
+    }
+  } else {
+    console.log(`Selected ${target} model: ${selected.model}`);
+  }
+  const effortChoice = await chooseSetupEffort({ target, explicitEffort });
+  console.log(formatEffortSelection({ target, effort: effortChoice.effort, source: effortChoice.source }));
+  return {
+    model: selected.model,
+    effort: effortChoice.effort,
+    modelSource: selected.source,
+    effortSource: effortChoice.source,
+    modelDisplayed: Boolean(selected.displayed),
+    effortDisplayed: Boolean(effortChoice.displayed)
+  };
+}
+
+function printSetupStatus(status) {
+  console.log(`Aerial: http://${status.config.host}:${status.config.port}  (platform: ${status.platform})`);
+  console.log(`API key file:    ${status.auth.api_key.file}  (${status.auth.api_key.exists ? "present" : "missing"})`);
+  const ghSourceText = status.auth.github_token.source === "missing"
+    ? `(missing)`
+    : status.auth.github_token.source === "env"
+      ? `(present, source=env; file path ${status.auth.github_token.file} is not consulted while AERIAL_GITHUB_TOKEN is set)`
+      : `${status.auth.github_token.file}  (present, source=file)`;
+  console.log(`GitHub token:    ${ghSourceText}`);
+  for (const cs of Object.values(status.clients)) {
+    const head = `${cs.target.padEnd(7)} state=${cs.state}`;
+    const effortText = ` effort=${cs.effort || "missing"}`;
+    console.log(`${head}${effortText}  file=${cs.file}`);
+    if (cs.backups.length) console.log(`         backups=${cs.backups.length}`);
+    if (cs.error) console.log(`         error=${cs.error}`);
+  }
+}
+
+export async function runSetupCli(subcommand, rest) {
+  if (subcommand === "codex") {
+    const options = await selectSetupOptions("Codex", "responses", rest);
+    const result = setupCodex({ model: options.model, effort: options.effort, authCommand: codexAuthCommand() });
+    const config = loadConfig();
+    printSetupCompletionSummary({
+      heading: "Configured Codex",
+      cli: "Codex",
+      model: result.model,
+      effort: result.effort || "missing",
+      proxy: `http://${config.host}:${config.port}/v1`,
+      configFile: result.file,
+      aerialConfigFile: configPath(),
+      aerialDefaultEffort: config.defaultEffort || "missing",
+      backup: result.backup,
+      auth: "command-backed local Aerial key",
+      notes: ["restart Codex if it was already running so it reloads the profile."]
+    });
+    return;
+  }
+  if (subcommand === "claude") {
+    const options = await selectSetupOptions("Claude Code", "messages", rest);
+    const result = setupClaude({ model: options.model, effort: options.effort, apiKeyHelper: claudeApiKeyHelper() });
+    const config = loadConfig();
+    printSetupCompletionSummary({
+      heading: "Configured Claude Code",
+      cli: "Claude Code",
+      model: result.model || "preserved",
+      effort: result.effort || config.defaultEffort || "missing",
+      proxy: `http://${config.host}:${config.port}`,
+      configFile: result.file,
+      aerialConfigFile: configPath(),
+      aerialDefaultEffort: config.defaultEffort || "missing",
+      backup: result.backup,
+      auth: "apiKeyHelper local Aerial key",
+      notes: ["effort is applied via Aerial defaultEffort and proxy fallback; Claude settings.json does not store an effort value."]
+    });
+    return;
+  }
+  if (subcommand === "all") {
+    throw new Error("aerial setup all has been removed. Run `aerial setup codex` and/or `aerial setup claude` instead.");
+  }
+  if (subcommand === "status") {
+    const status = setupStatus();
+    if (rest.includes("--json")) {
+      console.log(JSON.stringify(status, null, 2));
+      return;
+    }
+    printSetupStatus(status);
+    return;
+  }
+  if (subcommand === "restore") {
+    const which = rest[0];
+    if (!which) throw new Error("Usage: aerial setup restore <codex|claude|all> --latest");
+    if (!rest.includes("--latest")) throw new Error("aerial setup restore: only --latest is supported in this release");
+    if (which === "all") {
+      const { ok, results } = restoreAllClients();
+      printRestoreResults(results);
+      process.exitCode = ok ? 0 : 1;
+      return;
+    }
+    if (which !== "codex" && which !== "claude") throw new Error(`Unknown restore target: ${which}. Use codex, claude, or all.`);
+    const r = restoreClient(which);
+    if (r.restored) {
+      console.log(`Restored ${which}: ${r.file} <- ${r.from}`);
+      if (r.snapshot) console.log(`  pre-restore snapshot: ${r.snapshot}`);
+    } else if (r.reason === "no_backup") {
+      console.log(`Restored ${which}: no backup to restore`);
+    }
+    return;
+  }
+}

package/src/{setup-selection.js → cli/setup-selection.js}

@@ -1,26 +1,9 @@
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
-import { parseNumberChoice } from "./prompt-utils.js";
+import { parseNumberChoice } from "../shared/prompt-utils.js";
+import { DEFAULT_EFFORT, EFFORT_VALUES, assertValidEffort } from "../shared/effort.js";
 
-export const EFFORT_VALUES = Object.freeze(["low", "medium", "high", "xhigh"]);
-export const DEFAULT_EFFORT = "medium";
-
-export function normalizeEffort(value) {
-  if (value === undefined || value === null) return undefined;
-  const trimmed = String(value).trim().toLowerCase();
-  if (!trimmed) return undefined;
-  if (trimmed === "max") return "xhigh";
-  if (EFFORT_VALUES.includes(trimmed)) return trimmed;
-  return undefined;
-}
-
-export function assertValidEffort(raw) {
-  const normalized = normalizeEffort(raw);
-  if (!normalized) {
-    throw new Error(`Invalid --effort ${JSON.stringify(raw)}. Allowed: ${EFFORT_VALUES.join(", ")} (or alias 'max' for xhigh).`);
-  }
-  return normalized;
-}
+export { DEFAULT_EFFORT, EFFORT_VALUES, normalizeEffort, assertValidEffort } from "../shared/effort.js";
 
 export async function chooseSetupEffort({
   target,

package/src/cli/start-command.js

@@ -0,0 +1,11 @@
+import { ensureApiKey, loadConfig } from "../shared/config.js";
+import { startServer } from "../proxy/server.js";
+import { argValue } from "./args.js";
+
+export function runStartCli(args) {
+  const config = loadConfig();
+  const host = argValue(args, "--host") || config.host;
+  const port = Number(argValue(args, "--port") || config.port);
+  ensureApiKey();
+  startServer({ host, port });
+}

package/src/cli/status-command.js

@@ -0,0 +1,26 @@
+import { setupStatus } from "../setup/index.js";
+import { serviceStatus } from "../service/index.js";
+import { computeAppStatus } from "./app-status.js";
+import { printServiceSummary, printSetupSummary } from "./output.js";
+
+export async function appStatus({ json = false } = {}) {
+  const setup = setupStatus();
+  const service = await serviceStatus();
+  const status = computeAppStatus(setup, service);
+  if (json) {
+    console.log(JSON.stringify(status, null, 2));
+    return status;
+  }
+  console.log("Aerial status");
+  printSetupSummary(setup);
+  printServiceSummary(service);
+  if (status.nextSteps.length) {
+    console.log("next:");
+    for (const step of status.nextSteps) console.log(`  - ${step}`);
+  }
+  if (status.hints.length) {
+    console.log("hints:");
+    for (const hint of status.hints) console.log(`  - ${hint}`);
+  }
+  return status;
+}

package/src/{version.js → cli/version.js}

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 
-const PACKAGE_JSON_URL = new URL("../package.json", import.meta.url);
+const PACKAGE_JSON_URL = new URL("../../package.json", import.meta.url);
 
 export function readPackageVersion(packageJsonUrl = PACKAGE_JSON_URL) {
   try {

package/src/proxy/cache-policy.js

@@ -0,0 +1,89 @@
+import crypto from "node:crypto";
+import { loadConfig } from "../shared/config.js";
+
+export function configuredPromptCacheRetention(config = loadConfig()) {
+  const value = config.promptCacheRetention;
+  if (!value || value === "off") return undefined;
+  if (!["in_memory", "24h"].includes(value)) return undefined;
+  return value;
+}
+
+function stableCacheKeyPart(value) {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === "string") return value.trim() || undefined;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return undefined;
+  }
+}
+
+function metadataCacheKey(metadata) {
+  if (!metadata || typeof metadata !== "object") return undefined;
+  for (const key of ["prompt_cache_key", "session_id", "conversation_id", "thread_id", "user_id"]) {
+    const value = stableCacheKeyPart(metadata[key]);
+    if (value) return value;
+  }
+  return undefined;
+}
+
+export function configuredPromptCacheKey(payload, config = loadConfig()) {
+  const value = config.promptCacheKey;
+  if (!value || value === "off") return undefined;
+  if (value !== "auto") return String(value);
+  const basis = [
+    stableCacheKeyPart(payload?.model),
+    metadataCacheKey(payload?.metadata),
+    stableCacheKeyPart(payload?.conversation_id),
+    stableCacheKeyPart(payload?.thread_id),
+    stableCacheKeyPart(process.cwd())
+  ].filter(Boolean).join(":");
+  if (!basis) return undefined;
+  return "aerial:" + crypto.createHash("sha256").update(basis).digest("hex").slice(0, 32);
+}
+
+export function withDefaultPromptCache(payload) {
+  const config = loadConfig();
+  const retention = configuredPromptCacheRetention(config);
+  const promptCacheKey = configuredPromptCacheKey(payload, config);
+  const next = { ...payload };
+  if (retention && next.prompt_cache_retention === undefined) next.prompt_cache_retention = retention;
+  if (promptCacheKey && next.prompt_cache_key === undefined) next.prompt_cache_key = promptCacheKey;
+  return next;
+}
+
+export function countCacheControlBlocks(value) {
+  if (!value || typeof value !== "object") return 0;
+  if (Array.isArray(value)) return value.reduce((total, item) => total + countCacheControlBlocks(item), 0);
+  return Object.entries(value).reduce((total, [key, item]) => total + (key === "cache_control" ? 1 : 0) + countCacheControlBlocks(item), 0);
+}
+
+function addEphemeralCacheControl(value) {
+  if (typeof value === "string") {
+    return value.trim() ? { value: [{ type: "text", text: value, cache_control: { type: "ephemeral" } }], changed: true } : { value, changed: false };
+  }
+  if (!Array.isArray(value) || value.length === 0) return { value, changed: false };
+  for (let i = value.length - 1; i >= 0; i -= 1) {
+    const item = value[i];
+    if (item && typeof item === "object" && !Array.isArray(item) && item.cache_control === undefined) {
+      const next = [...value];
+      next[i] = { ...item, cache_control: { type: "ephemeral" } };
+      return { value: next, changed: true };
+    }
+  }
+  return { value, changed: false };
+}
+
+export function withDefaultAnthropicCache(payload) {
+  const retention = configuredPromptCacheRetention();
+  if (!retention || countCacheControlBlocks(payload) > 0) return payload;
+  const next = { ...payload };
+  const system = addEphemeralCacheControl(next.system);
+  if (system.changed) return { ...next, system: system.value };
+  if (Array.isArray(next.tools) && next.tools.length > 0) {
+    const tools = addEphemeralCacheControl(next.tools);
+    if (tools.changed) return { ...next, tools: tools.value };
+  }
+  return next;
+}

package/src/proxy/cache-telemetry.js

@@ -0,0 +1,172 @@
+import { logEvent } from "../shared/log.js";
+import { copyResponseHeaders } from "./headers.js";
+import { countCacheControlBlocks } from "./cache-policy.js";
+
+export function parseJsonBody(body, contentType) {
+  if (!body || !contentType.includes("json")) return undefined;
+  try {
+    return JSON.parse(Buffer.from(body).toString("utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+export function cacheRequestFields(payload) {
+  if (!payload || typeof payload !== "object") return {};
+  const fields = {
+    model: typeof payload.model === "string" ? payload.model : undefined,
+    promptCacheRetention: payload.prompt_cache_retention,
+    hasPromptCacheKey: payload.prompt_cache_key !== undefined,
+    cacheControlBlocks: countCacheControlBlocks(payload)
+  };
+  return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined && value !== false && value !== 0));
+}
+
+function responseItems(payload) {
+  return Array.isArray(payload?.input) ? payload.input : [];
+}
+
+export function responseHasVision(payload) {
+  const visit = (value) => {
+    if (Array.isArray(value)) return value.some(visit);
+    if (!value || typeof value !== "object") return false;
+    if (value.type === "input_image") return true;
+    return Array.isArray(value.content) && value.content.some(visit);
+  };
+  return responseItems(payload).some(visit);
+}
+
+export function responseInitiator(payload) {
+  const last = responseItems(payload).at(-1);
+  if (!last) return "user";
+  if (!last.role) return "agent";
+  return String(last.role).toLowerCase() === "assistant" ? "agent" : "user";
+}
+
+export function hasExplicitCacheRequest(fields) {
+  return fields.promptCacheRetention !== undefined || fields.hasPromptCacheKey === true || Number(fields.cacheControlBlocks || 0) > 0;
+}
+
+function sumCopilotCacheDetails(details, kind) {
+  if (!Array.isArray(details)) return undefined;
+  const total = details.reduce((sum, detail) => {
+    const label = String(detail.type || detail.name || detail.kind || detail.cache || "");
+    if (!label.includes(kind)) return sum;
+    return sum + Number(detail.tokens || detail.count || detail.token_count || 0);
+  }, 0);
+  return total || undefined;
+}
+
+function usageFields(payload) {
+  const usage = payload?.usage || payload?.response?.usage;
+  if (!usage || typeof usage !== "object") return {};
+  const copilotDetails = usage.copilot_usage?.token_details || payload?.copilot_usage?.token_details;
+  const fields = {
+    input: usage.input_tokens ?? usage.prompt_tokens,
+    output: usage.output_tokens ?? usage.completion_tokens,
+    cached: usage.input_tokens_details?.cached_tokens ?? usage.prompt_tokens_details?.cached_tokens,
+    cacheCreation: usage.cache_creation_input_tokens,
+    cacheRead: usage.cache_read_input_tokens,
+    copilotCacheRead: sumCopilotCacheDetails(copilotDetails, "cache_read"),
+    copilotCacheWrite: sumCopilotCacheDetails(copilotDetails, "cache_write")
+  };
+  return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+}
+
+function hasCacheUsage(fields) {
+  return fields.cached !== undefined || fields.cacheCreation !== undefined || fields.cacheRead !== undefined || fields.copilotCacheRead !== undefined || fields.copilotCacheWrite !== undefined;
+}
+
+function sseJsonPayloads(text) {
+  return text.split(/\r?\n/)
+    .filter((line) => line.startsWith("data:"))
+    .map((line) => line.slice("data:".length).trim())
+    .filter((line) => line && line !== "[DONE]")
+    .flatMap((line) => {
+      try {
+        return [JSON.parse(line)];
+      } catch {
+        return [];
+      }
+    });
+}
+
+function shouldEmitCacheObserve(requestCache, usage) {
+  return hasExplicitCacheRequest(requestCache) || hasCacheUsage(usage);
+}
+
+export function createSseCacheObserver(route, requestCache) {
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let usage = {};
+  let logged = false;
+
+  const consume = () => {
+    let match;
+    const boundary = /\r?\n\r?\n/;
+    while ((match = boundary.exec(buffer)) !== null) {
+      const frame = buffer.slice(0, match.index);
+      buffer = buffer.slice(match.index + match[0].length);
+      for (const payload of sseJsonPayloads(frame)) {
+        const fields = usageFields(payload);
+        if (Object.keys(fields).length) usage = { ...usage, ...fields };
+      }
+    }
+  };
+
+  const emit = () => {
+    if (logged) return;
+    logged = true;
+    if (shouldEmitCacheObserve(requestCache, usage)) {
+      logEvent("cache_observe", { route, request: requestCache, usage });
+    }
+  };
+
+  return new TransformStream({
+    transform(chunk, controller) {
+      controller.enqueue(chunk);
+      try {
+        buffer += decoder.decode(chunk, { stream: true });
+        consume();
+      } catch (error) {
+        logEvent("cache_observe_error", { route, error: error.message });
+      }
+    },
+    flush() {
+      try {
+        buffer += decoder.decode();
+        consume();
+      } catch (error) {
+        logEvent("cache_observe_error", { route, error: error.message });
+      }
+      emit();
+    }
+  });
+}
+
+async function logJsonCacheUsage(route, requestCache, clone) {
+  try {
+    const payload = await clone.json();
+    const usage = usageFields(payload);
+    if (shouldEmitCacheObserve(requestCache, usage)) {
+      logEvent("cache_observe", { route, request: requestCache, usage });
+    }
+  } catch (error) {
+    logEvent("cache_observe_error", { route, error: error.message });
+  }
+}
+
+export function wrapResponseWithCacheObserver(upstream, route, requestCache) {
+  const headers = copyResponseHeaders(upstream);
+  const contentType = upstream.headers.get("content-type") || "";
+  if (!upstream.body) return new Response(upstream.body, { status: upstream.status, headers });
+  if (contentType.includes("text/event-stream")) {
+    const observer = createSseCacheObserver(route, requestCache);
+    return new Response(upstream.body.pipeThrough(observer), { status: upstream.status, headers });
+  }
+  if (contentType.includes("json")) {
+    void logJsonCacheUsage(route, requestCache, upstream.clone());
+    return new Response(upstream.body, { status: upstream.status, headers });
+  }
+  return new Response(upstream.body, { status: upstream.status, headers });
+}