@oar-sh/oar 0.9.0

package/.github/extensions/web-relay/runtime/api-client.mjs

@@ -0,0 +1,34 @@
+export function createApiClient({ serverUrl, token, getHeaders }) {
+  return async function api(method, routePath, body) {
+    const url = `${serverUrl}${routePath}`;
+    const extraHeaders = typeof getHeaders === "function" ? (getHeaders() || {}) : {};
+    const opts = {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+        ...extraHeaders,
+      },
+      ...(method !== "GET" ? { body: JSON.stringify(body || {}) } : {}),
+    };
+
+    const res = await fetch(url, opts);
+    if (!res.ok) {
+      const rawText = String(await res.text().catch(() => "")).trim();
+      let detail = rawText;
+      if (rawText) {
+        try {
+          const payload = JSON.parse(rawText);
+          detail = String(payload?.error || payload?.message || rawText).trim();
+        } catch {
+          detail = rawText;
+        }
+      }
+      const error = new Error(`HTTP ${res.status} ${routePath}${detail ? `: ${detail}` : ""}`);
+      error.status = res.status;
+      error.detail = detail;
+      throw error;
+    }
+    return res.json();
+  };
+}

package/.github/extensions/web-relay/runtime/banner-state.mjs

@@ -0,0 +1,126 @@
+import fs from "fs";
+import path from "path";
+
+function normalizePositiveMs(value, fallback) {
+  const num = Number(value);
+  if (!Number.isFinite(num) || num <= 0) return fallback;
+  return Math.max(1000, Math.floor(num));
+}
+
+function stableHash(text) {
+  const input = String(text || "");
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+function nowMs() {
+  return Date.now();
+}
+
+export function createBannerStateStore({
+  stateFilePath,
+  dbg = () => {},
+  ttlMs = 6 * 60 * 60 * 1000,
+  cooldownMs = 15 * 1000,
+} = {}) {
+  const ttl = normalizePositiveMs(ttlMs, 6 * 60 * 60 * 1000);
+  const cooldown = normalizePositiveMs(cooldownMs, 15 * 1000);
+  const inMemorySeen = new Map();
+  let loaded = false;
+  let persistedState = { version: 1, entries: {}, updatedAt: 0 };
+
+  function tokenFingerprint(token) {
+    return stableHash(String(token || ""));
+  }
+
+  function buildEntryKey({ sessionId, bannerKey, token }) {
+    const sessionPart = String(sessionId || "unknown");
+    const bannerPart = stableHash(String(bannerKey || ""));
+    const tokenPart = tokenFingerprint(token);
+    return `${sessionPart}|${tokenPart}|${bannerPart}`;
+  }
+
+  function pruneEntries(state, currentNow = nowMs()) {
+    const entries = state?.entries && typeof state.entries === "object" ? state.entries : {};
+    let changed = false;
+    for (const [key, seenAt] of Object.entries(entries)) {
+      const ts = Number(seenAt);
+      if (!Number.isFinite(ts) || ts <= 0 || (currentNow - ts) > ttl) {
+        delete entries[key];
+        changed = true;
+      }
+    }
+    state.entries = entries;
+    if (changed) state.updatedAt = currentNow;
+    return changed;
+  }
+
+  function loadState() {
+    if (loaded) return;
+    loaded = true;
+    try {
+      const raw = fs.readFileSync(stateFilePath, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object") {
+        persistedState = {
+          version: Number(parsed.version) || 1,
+          entries: parsed.entries && typeof parsed.entries === "object" ? parsed.entries : {},
+          updatedAt: Number(parsed.updatedAt) || 0,
+        };
+      }
+      pruneEntries(persistedState);
+    } catch {
+      persistedState = { version: 1, entries: {}, updatedAt: 0 };
+    }
+  }
+
+  function saveState() {
+    try {
+      const dir = path.dirname(String(stateFilePath || ""));
+      if (dir) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(stateFilePath, JSON.stringify(persistedState, null, 2), "utf8");
+    } catch (error) {
+      dbg("banner dedupe state write failed:", error?.message || String(error));
+    }
+  }
+
+  function shouldSuppress({ sessionId, bannerKey, token, force = false } = {}) {
+    if (force) return { suppress: false, reason: "forced" };
+    const key = buildEntryKey({ sessionId, bannerKey, token });
+    const currentNow = nowMs();
+    const memSeenAt = Number(inMemorySeen.get(key));
+    if (Number.isFinite(memSeenAt) && (currentNow - memSeenAt) < cooldown) {
+      return { suppress: true, reason: "cooldown", key };
+    }
+
+    loadState();
+    pruneEntries(persistedState, currentNow);
+    const persistedSeenAt = Number(persistedState.entries[key]);
+    if (Number.isFinite(persistedSeenAt) && (currentNow - persistedSeenAt) < ttl) {
+      inMemorySeen.set(key, persistedSeenAt);
+      return { suppress: true, reason: "persisted", key };
+    }
+
+    return { suppress: false, reason: "new", key };
+  }
+
+  function markShown({ sessionId, bannerKey, token } = {}) {
+    const key = buildEntryKey({ sessionId, bannerKey, token });
+    const currentNow = nowMs();
+    inMemorySeen.set(key, currentNow);
+    loadState();
+    persistedState.entries[key] = currentNow;
+    persistedState.updatedAt = currentNow;
+    pruneEntries(persistedState, currentNow);
+    saveState();
+  }
+
+  return {
+    shouldSuppress,
+    markShown,
+  };
+}

package/.github/extensions/web-relay/runtime/config-loader.mjs

@@ -0,0 +1,104 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+function toAbsolutePath(value) {
+  if (!value) return "";
+  return path.isAbsolute(value) ? value : path.resolve(process.cwd(), value);
+}
+
+function looksLikeServerDir(serverDir) {
+  if (!serverDir) return false;
+  return fs.existsSync(path.join(serverDir, "server.js")) && fs.existsSync(path.join(serverDir, "config.json"));
+}
+
+export function resolveRelayPaths(importMetaUrl) {
+  const __dirname = path.dirname(fileURLToPath(importMetaUrl));
+  const projectServerDir = path.resolve(__dirname, "../../../server");
+  const cwdServerDir = path.resolve(process.cwd(), "server");
+  const envRoot = toAbsolutePath(process.env.COPILOT_WEB_RELAY_ROOT || "");
+  const envServerDir = toAbsolutePath(process.env.COPILOT_WEB_RELAY_SERVER_DIR || "");
+  const envConfigPath = toAbsolutePath(process.env.COPILOT_WEB_RELAY_CONFIG || "");
+  const envToolsPath = toAbsolutePath(process.env.COPILOT_WEB_RELAY_TOOLS || "");
+  const envLogDir = toAbsolutePath(process.env.COPILOT_WEB_RELAY_LOG_DIR || "");
+
+  const resolvedServerDir =
+    (looksLikeServerDir(envServerDir) && envServerDir) ||
+    (looksLikeServerDir(path.join(envRoot, "server")) && path.join(envRoot, "server")) ||
+    (looksLikeServerDir(projectServerDir) && projectServerDir) ||
+    (looksLikeServerDir(cwdServerDir) && cwdServerDir) ||
+    projectServerDir;
+
+  const SERVER_DIR = resolvedServerDir;
+  const CONFIG_PATH = envConfigPath || path.resolve(SERVER_DIR, "config.json");
+  const RELAY_TOOLS_PATH = envToolsPath || path.resolve(SERVER_DIR, "relay-tools.md");
+  const LOG_DIR = envLogDir || path.resolve(SERVER_DIR, "logs");
+  const SERVER_LOG_PATH = path.resolve(LOG_DIR, "server.log");
+  const SERVER_ERR_PATH = path.resolve(LOG_DIR, "server-err.log");
+
+  return {
+    __dirname,
+    CONFIG_PATH,
+    RELAY_TOOLS_PATH,
+    SERVER_DIR,
+    LOG_DIR,
+    SERVER_LOG_PATH,
+    SERVER_ERR_PATH,
+  };
+}
+
+export function loadTokenFromConfig(configPath) {
+  try {
+    const cfg = loadRelayConfig(configPath);
+    return String(cfg.authToken || "").trim();
+  } catch {
+    return "";
+  }
+}
+
+export function loadRelayConfig(configPath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function normalizeLoopbackHost(value) {
+  const host = String(value || "").trim();
+  if (!host || host === "0.0.0.0" || host === "::") return "127.0.0.1";
+  if (host === "localhost") return "127.0.0.1";
+  return host;
+}
+
+export function resolveRelayServerUrl({ configPath, env = process.env } = {}) {
+  const explicitUrl = String(env.COPILOT_WEB_RELAY_SERVER_URL || "").trim();
+  if (explicitUrl) {
+    const url = new URL(explicitUrl);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      throw new Error(`invalid-relay-server-url:${url.protocol}`);
+    }
+    url.pathname = "";
+    url.search = "";
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+  }
+
+  const config = loadRelayConfig(configPath);
+  const configuredPort = Number.parseInt(String(config.port || ""), 10);
+  const port = Number.isInteger(configuredPort) && configuredPort > 0 && configuredPort <= 65535
+    ? configuredPort
+    : 3333;
+  const host = normalizeLoopbackHost(config.host);
+  const formattedHost = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+  return `http://${formattedHost}:${port}`;
+}
+
+export function loadRelayInstructionsFromFile(relayToolsPath) {
+  try {
+    return String(fs.readFileSync(relayToolsPath, "utf8")).trim();
+  } catch {
+    return "";
+  }
+}

package/.github/extensions/web-relay/runtime/debug-log.mjs

@@ -0,0 +1,27 @@
+import fs from "fs";
+import path from "path";
+
+export function createDebugLogger({ logDir, fileName = "ext-debug.log", prefix = "[web-relay-dbg]" }) {
+  const debugLogPath = path.resolve(logDir, fileName);
+
+  function dbg(...args) {
+    const now = new Date();
+    const stamp = [
+      now.getUTCFullYear(),
+      String(now.getUTCMonth() + 1).padStart(2, "0"),
+      String(now.getUTCDate()).padStart(2, "0"),
+      String(now.getUTCHours()).padStart(2, "0"),
+      String(now.getUTCMinutes()).padStart(2, "0"),
+      String(now.getUTCSeconds()).padStart(2, "0"),
+    ].join("-");
+    const line = `[${stamp}] ${args.join(" ")}\n`;
+    try { fs.mkdirSync(logDir, { recursive: true }); } catch {}
+    try { fs.appendFileSync(debugLogPath, line); } catch {}
+    process.stderr.write(`${prefix} ${line}`);
+  }
+
+  return {
+    dbg,
+    debugLogPath,
+  };
+}

package/.github/extensions/web-relay/runtime/send-and-wait-errors.mjs

@@ -0,0 +1,170 @@
+function readErrorText(error) {
+  return String(error?.message || error || "").trim();
+}
+
+function extractFirstMatch(text, pattern) {
+  const match = text.match(pattern);
+  return String(match?.[1] || "").trim() || null;
+}
+
+export function toKebabToken(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || null;
+}
+
+// The runtime's own vocabulary for "the billing window is spent". The Copilot
+// SDK's `ErrorData.errorCode` documents `quota_exceeded` and
+// `session_quota_exceeded`; `errorType` documents the coarser `quota`
+// category; HTTP 402 is the transport-level form of the same thing.
+const QUOTA_ERROR_CODES = new Set([
+  "quota_exceeded",
+  "session_quota_exceeded",
+  "quota-exceeded",
+  "session-quota-exceeded",
+  "quota",
+]);
+
+/**
+ * True when a runtime flagged quota exhaustion STRUCTURALLY, independent of
+ * how the prose was worded. This exists because the prose is the one part
+ * GitHub rewords freely ("premium requests" → "AI credits" → "monthly quota"),
+ * and a quota failure misfiled as retryable burns the retry budget against a
+ * window that cannot reset until the next billing period.
+ *
+ * Accepts the loose shapes callers actually hold: an `Error` with `code` /
+ * `statusCode`, or a runtime error payload with `errorCode` / `errorType` /
+ * `statusCode`.
+ */
+export function isStructuredQuotaError(source) {
+  if (!source || typeof source !== "object") return false;
+  for (const field of ["code", "errorCode", "errorType"]) {
+    const token = String(source[field] || "").trim().toLowerCase();
+    if (token && QUOTA_ERROR_CODES.has(token)) return true;
+  }
+  const status = Number(source.statusCode ?? source.status);
+  return status === 402;
+}
+
+const QUOTA_EXHAUSTED = {
+  code: "quota-exhausted",
+  message: "GitHub Copilot has no AI credits left for this billing window, so the request was rejected.",
+  guidance: "Open Check Usage for the reset time and retry after the reset, or switch this conversation to another provider.",
+};
+
+/**
+ * `hint` carries structured signals that outrank the prose. Only quota is
+ * modelled today; the prose branches below are unchanged and remain the sole
+ * classifier when no hint is supplied, which is the extension's path.
+ */
+function classifyTerminalError(text, hint = {}) {
+  // Checked before the prose so a structurally-flagged quota error lands in
+  // the non-retryable branch however mildly it was worded.
+  if (hint.quota === true) return QUOTA_EXHAUSTED;
+
+  const lower = text.toLowerCase();
+  if (!lower) return null;
+
+  if (lower.includes("no tool output found for function call")) {
+    return {
+      code: "missing-tool-output",
+      message: "No tool output was returned for a required function call.",
+      guidance: "Retry the message. If this keeps happening, restart the relay and include the error code.",
+    };
+  }
+  if (lower.includes("tool call") && (lower.includes("not found") || lower.includes("missing"))) {
+    return {
+      code: "tool-call-missing",
+      message: "A required tool call was missing in the runtime response.",
+      guidance: "Retry the message. If it repeats, restart the relay and include the error code.",
+    };
+  }
+  if (lower.includes("tool output") && lower.includes("invalid")) {
+    return {
+      code: "invalid-tool-output",
+      message: "Tool output returned from the runtime was invalid.",
+      guidance: "Retry the message. If it repeats, restart the relay and include the error code.",
+    };
+  }
+  // Monthly/plan quota exhaustion is not transient: retrying before the
+  // billing window resets can never succeed. Distinct from "rate limit"
+  // (per-minute throttling), which stays retryable below.
+  if ((lower.includes("quota") && (lower.includes("exceeded") || lower.includes("exhaust")))
+    || lower.includes("out of ai credits")
+    || lower.includes("premium request allowance")) {
+    return QUOTA_EXHAUSTED;
+  }
+  if ((lower.includes("capierror") || lower.includes("http 400") || lower.includes("status 400") || /^400\b/.test(lower))
+    && !lower.includes("timeout")
+    && !lower.includes("temporar")
+    && !lower.includes("rate limit")) {
+    return {
+      code: "request-invalid",
+      message: "The runtime rejected the request as invalid and non-retryable.",
+      guidance: "Retry after adjusting the request. If it persists, restart the relay and include the error code.",
+    };
+  }
+
+  return null;
+}
+
+/**
+ * `options` lets a caller that holds structured error fields (an SDK error
+ * payload rather than a thrown `Error`) pass them in explicitly:
+ * `{ quota: true }`, or `{ errorCode, errorType, statusCode }` to be judged
+ * here. Structured fields carried on the error object itself (`error.code`,
+ * `error.statusCode`) are read as well, so plain HTTP-ish errors classify
+ * without the caller doing anything.
+ */
+export function normalizeTerminalSendAndWaitError(error, options = {}) {
+  const detail = readErrorText(error);
+  const quota = options.quota === true
+    || isStructuredQuotaError(options)
+    || isStructuredQuotaError(error);
+  const base = classifyTerminalError(detail, { quota });
+  if (!base) return null;
+  const functionCallId = extractFirstMatch(detail, /function call\s+([a-z0-9_-]+)/i)
+    || extractFirstMatch(detail, /\b(call_[a-z0-9_-]+)/i);
+  // GitHub request ids are colon-separated hex segments (AFAC:3C07CD:…).
+  const requestId = extractFirstMatch(detail, /\brequest(?:\s+id|_id)?[:=]\s*([a-z0-9_-]+(?::[a-z0-9_-]+)*)/i)
+    || extractFirstMatch(detail, /\b(req_[a-z0-9_-]+)/i);
+  return {
+    terminal: true,
+    code: base.code,
+    stableCode: `relay.${base.code}`,
+    message: base.message,
+    guidance: base.guidance,
+    detail: detail || "unknown error",
+    functionCallId,
+    requestId,
+    classificationHint: toKebabToken(error?.code || error?.name || null),
+  };
+}
+
+export function isTerminalSendAndWaitError(error, options = {}) {
+  return !!normalizeTerminalSendAndWaitError(error, options);
+}
+
+export function buildTerminalFailureText(error, options = {}) {
+  const normalized = normalizeTerminalSendAndWaitError(error, options) || {
+    stableCode: "relay.unknown-terminal",
+    message: "The relay runtime hit a terminal error and could not complete this turn.",
+    guidance: "Retry the message.",
+    detail: readErrorText(error) || "unknown error",
+    functionCallId: null,
+    requestId: null,
+  };
+  const ids = [
+    normalized.functionCallId ? `functionCallId=${normalized.functionCallId}` : null,
+    normalized.requestId ? `requestId=${normalized.requestId}` : null,
+  ].filter(Boolean);
+  return [
+    normalized.message,
+    `Error code: ${normalized.stableCode}.`,
+    ids.length ? `IDs: ${ids.join(", ")}.` : null,
+    normalized.guidance,
+    `Details: ${normalized.detail}`,
+  ].filter(Boolean).join(" ");
+}

package/.github/extensions/web-relay/runtime/session-binding.mjs

@@ -0,0 +1,78 @@
+function normalizeId(value) {
+  const text = String(value ?? "").trim();
+  return text || null;
+}
+
+export function extractTargetSessionId(details, conversationId = null) {
+  return normalizeId(
+    details?.sdkSessionId
+    || details?.runtimeSession?.sdkSessionId
+    || details?.runtimeSession?.sdk_session_id
+    || "",
+  );
+}
+
+export function resolveSessionBinding({
+  conversationId,
+  details,
+  activeSessionId,
+} = {}) {
+  const convId = normalizeId(conversationId);
+  const targetSessionId = extractTargetSessionId(details, convId);
+  const active = normalizeId(activeSessionId);
+
+  if (!convId) {
+    return {
+      ok: false,
+      reason: "conversation-id-missing",
+      retryable: false,
+      message: "Missing conversation id for session binding check",
+      activeSessionId: active,
+      targetSessionId: null,
+    };
+  }
+
+  if (!targetSessionId) {
+    return {
+      ok: false,
+      reason: "target-session-missing",
+      retryable: true,
+      message: "Conversation has no bound SDK session id yet",
+      activeSessionId: active,
+      targetSessionId: null,
+      canClaim: true,
+    };
+  }
+
+  if (!active) {
+    return {
+      ok: false,
+      reason: "active-session-missing",
+      retryable: true,
+      message: "No active SDK runtime session available",
+      activeSessionId: null,
+      targetSessionId,
+    };
+  }
+
+  if (targetSessionId !== active) {
+    return {
+      ok: false,
+      reason: "session-binding-mismatch",
+      retryable: true,
+      message: `Conversation is bound to SDK session ${targetSessionId}`,
+      activeSessionId: active,
+      targetSessionId,
+      canClaim: false,
+    };
+  }
+
+  return {
+    ok: true,
+    switched: false,
+    via: "session-liveness",
+    activeSessionId: active,
+    targetSessionId,
+  };
+}
+