@oar-sh/oar 0.9.1 → 0.9.3

package/shared/steer-note.mjs

@@ -0,0 +1,66 @@
+// The hidden note a steered message carries to the model.
+//
+// A message the user sends while a turn is running is pushed into that turn
+// (steering). When it lands before the model has produced anything, the model
+// sees two user messages at once — and in the 2026-09-25 burn-in gpt-5.4-mini
+// answered only the newest and silently dropped the original request (the
+// runtime's own event log confirmed nothing was lost by the relay). The note
+// tells the model the new message is an addition, not a replacement, unless
+// the user says otherwise. Only the model sees it: the relay stores and shows
+// the user's own text.
+//
+// Shared by the Claude and Copilot SDK workers (maintainer decision, 2026-09-25: both).
+
+// Worded to stay true whether the runtime folds the message into the running
+// turn or runs it as a turn of its own after that one finished: "if not
+// finished yet" never asks the model to redo work it already completed. The
+// opening words are the stable handle the prompt sanitizers match on
+// (services/relay-prompt-sanitizer.mjs and its browser copy).
+export const STEERED_MESSAGE_NOTE = '[Sent while you were still working on my previous message. '
+  + 'If that request is not finished yet, finish it too; do not drop it unless this message says so.]';
+
+// The note LEADS the user's text, inside the same text block, and that
+// position is load-bearing beyond the replay's shape. The Claude CLI runs a
+// prompt as a slash command when the string, or its LAST text block trimmed,
+// starts with "/" — and one dequeued mid-turn is deferred to a turn of its
+// own, whose output the relay would misattribute. The relay itself runs only
+// /compact and /preview as commands (any other "/x" is confirmed as text
+// first), so a steered "/cmd …" must reach the model as plain text folded
+// into the running turn, which the leading note guarantees. Appended, the
+// prompt would still start with "/" and run as a command whose arguments
+// include the note; as a separate leading block, the last block would still
+// start with "/". A "/x" that is not steered (or is pushed into a continuation,
+// which gets no note) is kept text by the Claude worker's slash-command guard
+// instead (shared/slash-command-guard.mjs).
+
+/** Prefix a plain-text prompt with the steer note. */
+export function withSteerNote(text) {
+  const body = String(text ?? '');
+  return body.trim() ? `${STEERED_MESSAGE_NOTE}\n\n${body}` : STEERED_MESSAGE_NOTE;
+}
+
+/**
+ * Prefix a content-block array (Claude's user message content) with the note:
+ * into the first text block when there is one, so the block structure — and
+ * with it the replay the CLI echoes back — keeps its shape; otherwise as a new
+ * leading text block. Returns a new array; the input is not mutated.
+ */
+export function withSteerNoteContent(content) {
+  if (typeof content === 'string') return withSteerNote(content);
+  if (!Array.isArray(content)) return content;
+  const index = content.findIndex((block) => block?.type === 'text');
+  if (index < 0) return [{ type: 'text', text: STEERED_MESSAGE_NOTE }, ...content];
+  return content.map((block, i) => (i === index ? { ...block, text: withSteerNote(block.text) } : block));
+}
+
+/**
+ * The user's own text from a prompt that may carry the steer note — what a
+ * worker compares a replayed message against. Note-agnostic matching: the
+ * replay the CLI echoes back carries the note, the relay row does not.
+ */
+export function stripSteerNote(text) {
+  const value = String(text ?? '');
+  if (value === STEERED_MESSAGE_NOTE) return '';
+  const prefix = `${STEERED_MESSAGE_NOTE}\n\n`;
+  return value.startsWith(prefix) ? value.slice(prefix.length) : value;
+}

package/shared/steer-settle-failure.mjs

@@ -0,0 +1,89 @@
+// The terminal failure for a message whose prompt the agent already consumed
+// but whose outcome could not be recorded. At-most-once: such a row is never
+// requeued (a re-delivery would run the prompt a second time), so it fails for
+// good with wording that tells the user where the answer went. Shared by the
+// session workers (their own settle paths) and the relay (recovery paths that
+// meet a row marked consumed).
+//
+// Provider-neutral: the wording names `agentLabel` ("the agent" unless the
+// caller knows better — the Claude worker passes 'Claude').
+
+export const STEER_SETTLE_FAILED_CODE = 'steer-settle-failed';
+export const STEER_SETTLE_FAILED_STABLE_CODE = `relay.${STEER_SETTLE_FAILED_CODE}`;
+export const DEFAULT_STEER_AGENT_LABEL = 'the agent';
+
+function normalizeAgentLabel(value) {
+  const text = String(value || '').trim();
+  return text || DEFAULT_STEER_AGENT_LABEL;
+}
+
+// "the agent" → "The agent" at the start of a sentence; a proper name is
+// left as it is.
+function sentenceCase(label) {
+  return label.charAt(0).toUpperCase() + label.slice(1);
+}
+
+const VARIANTS = Object.freeze({
+  // Folded into a turn whose reply answered it (or the path is unknown — the
+  // relay's recovery paths cannot tell which).
+  folded: (label) => ({
+    message: `This message was already sent to ${label} — check the reply above.`,
+    guidance: 'Resend it only if it went unanswered.',
+  }),
+  // Handed off mid-reply: its own partial reply stands, and the rest of the
+  // answer continued on the next message.
+  handoff: (label) => ({
+    message: `${sentenceCase(label)} started answering this message, then carried on with your next one — check both replies.`,
+    guidance: 'Resend it only if something went unanswered.',
+  }),
+  // Steered into a turn the user stopped.
+  stopped: (label) => ({
+    message: `This message was sent to ${label} just before you stopped the turn, so it was not answered.`,
+    guidance: 'Resend it if you still want an answer.',
+  }),
+  // Pulled back out of the runtime's queue by the user (un-steer) — the
+  // prompt never ran — but the relay could not be told in time.
+  cancelled: (label) => ({
+    message: `This message was cancelled before ${label} started on it, so it was not answered.`,
+    guidance: 'Resend it if you still want an answer.',
+  }),
+});
+
+/**
+ * The name a provider's runtime goes by in the settle wording, for callers
+ * that only know the conversation's provider type (the relay's recovery
+ * paths). Workers that know exactly which runtime took the prompt pass the
+ * label themselves.
+ */
+export function steerAgentLabelForProvider(providerType) {
+  switch (String(providerType || '').trim().toLowerCase()) {
+    case 'claude': return 'Claude';
+    case 'github':
+    case 'openai': return 'Copilot';
+    case 'cursor': return 'Cursor';
+    case 'grok': return 'Grok';
+    default: return DEFAULT_STEER_AGENT_LABEL;
+  }
+}
+
+function wordingFor(variant, agentLabel) {
+  const build = VARIANTS[variant] || VARIANTS.folded;
+  return build(normalizeAgentLabel(agentLabel));
+}
+
+export function steerSettleFailureText(variant = 'folded', agentLabel = DEFAULT_STEER_AGENT_LABEL) {
+  return wordingFor(variant, agentLabel).message;
+}
+
+export function buildSteerSettleFailure(message, { variant = 'folded', agentLabel = DEFAULT_STEER_AGENT_LABEL } = {}) {
+  const wording = wordingFor(variant, agentLabel);
+  return {
+    kind: STEER_SETTLE_FAILED_CODE,
+    code: STEER_SETTLE_FAILED_CODE,
+    stableCode: STEER_SETTLE_FAILED_STABLE_CODE,
+    message: wording.message,
+    guidance: wording.guidance,
+    failedAt: new Date().toISOString(),
+    queueMessageId: String(message?.id || '') || null,
+  };
+}

package/shared/steer-settle-markers.mjs

@@ -0,0 +1,18 @@
+// The settle stubs of steered messages the Claude CLI consumed without opening
+// a turn of their own. Each is stamped with its own message kind, which is
+// what the client renders from; the texts are shared so the relay's migration
+// can recognise stubs saved before the kind existed.
+
+/**
+ * A steer folded into the running turn and answered by that turn's reply.
+ * Stamped kind='folded' (before 0.9.3: kind='absorbed', which the client read
+ * as "the reply continues through the next message" and mis-merged the next
+ * ordinary message on reload).
+ */
+export const STEER_FOLDED_TEXT = '_(Handled together with the previous reply — this message was steered into that turn.)_';
+
+/**
+ * A steer pushed into a turn the user then stopped: never answered. Stamped
+ * kind='stopped' — the stable handle the client keys its Resend on.
+ */
+export const STEER_STOPPED_TEXT = '_(Stopped with the turn — not answered.)_';

package/shared/update-semver.mjs

@@ -0,0 +1,50 @@
+// Minimal version comparison for OAR's update check: releases are X.Y.Z or
+// X.Y.Z-beta.N, nothing else. Not a general semver implementation on purpose —
+// anything unparseable compares as "no update" instead of guessing.
+
+export function parseSemverIsh(value) {
+  const text = String(value ?? '').trim();
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(text);
+  if (!match) return null;
+  const prerelease = match[4]
+    ? match[4].split('.').map((part) => (/^\d+$/.test(part) ? Number(part) : part))
+    : null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease,
+  };
+}
+
+/** -1 | 0 | 1; a prerelease sorts below the release with the same triple. */
+export function compareSemverIsh(a, b) {
+  const left = typeof a === 'object' && a !== null ? a : parseSemverIsh(a);
+  const right = typeof b === 'object' && b !== null ? b : parseSemverIsh(b);
+  if (!left || !right) return 0;
+  for (const key of ['major', 'minor', 'patch']) {
+    if (left[key] !== right[key]) return left[key] < right[key] ? -1 : 1;
+  }
+  if (!left.prerelease && !right.prerelease) return 0;
+  if (!left.prerelease) return 1;
+  if (!right.prerelease) return -1;
+  const length = Math.max(left.prerelease.length, right.prerelease.length);
+  for (let i = 0; i < length; i += 1) {
+    const l = left.prerelease[i];
+    const r = right.prerelease[i];
+    if (l === undefined) return -1;
+    if (r === undefined) return 1;
+    if (l === r) continue;
+    if (typeof l === 'number' && typeof r === 'number') return l < r ? -1 : 1;
+    if (typeof l === 'number') return -1; // numeric identifiers sort first
+    if (typeof r === 'number') return 1;
+    return l < r ? -1 : 1;
+  }
+  return 0;
+}
+
+export function channelForVersion(version) {
+  const parsed = parseSemverIsh(version);
+  const first = parsed?.prerelease?.[0];
+  return typeof first === 'string' && first.toLowerCase().startsWith('beta') ? 'beta' : 'stable';
+}

package/shared/worker-crash-guard.mjs

@@ -11,6 +11,45 @@
  * The requeue is strictly bounded: a crash handler that hangs is worse than
  * no handler at all.
  */
+/**
+ * Post a bounded, fenced requeue for each owed row. Entries are plain ids or
+ * { id, attemptId, terminalError } objects: the attempt id fences the requeue
+ * (a row that has moved on to another attempt must not be yanked back by a
+ * dying predecessor), and a `terminalError` makes the requeue route fail the
+ * row outright — for a row whose prompt was already consumed, which must not
+ * be requeued and run a second time. Never waits longer than `timeoutMs`.
+ */
+export async function requeueOwedRows({ api, entries = [], timeoutMs = 2_000 } = {}) {
+  const seen = new Set();
+  const owed = (Array.isArray(entries) ? entries : [])
+    .map((entry) => (entry && typeof entry === 'object'
+      ? {
+        id: String(entry.id || '').trim(),
+        attemptId: String(entry.attemptId || '').trim() || null,
+        terminalError: entry.terminalError && typeof entry.terminalError === 'object' ? entry.terminalError : null,
+      }
+      : { id: String(entry || '').trim(), attemptId: null, terminalError: null }))
+    .filter((entry) => {
+      if (!entry.id || seen.has(entry.id)) return false;
+      seen.add(entry.id);
+      return true;
+    });
+  if (!owed.length || typeof api !== 'function') return;
+  let timer = null;
+  await Promise.race([
+    Promise.allSettled(owed.map((entry) => api('POST', '/api/requeue', {
+      messageId: entry.id,
+      ...(entry.attemptId ? { attemptId: entry.attemptId } : {}),
+      ...(entry.terminalError ? { terminalError: entry.terminalError } : {}),
+    }))),
+    new Promise((resolve) => {
+      timer = setTimeout(resolve, Math.max(0, Number(timeoutMs) || 0));
+      timer.unref?.();
+    }),
+  ]);
+  clearTimeout(timer);
+}
+
 export function installWorkerCrashGuard({
   api,
   workerName = 'session-worker',
@@ -28,20 +67,7 @@ export function installWorkerCrashGuard({
     logError(`${workerName} ${kind}:`, error?.stack || error?.message || error);
     (async () => {
       try {
-        const ids = [...new Set(
-          (getActiveQueueMessageIds() || [])
-            .map((id) => String(id || '').trim())
-            .filter(Boolean),
-        )];
-        if (ids.length && typeof api === 'function') {
-          await Promise.race([
-            Promise.allSettled(ids.map((id) => api('POST', '/api/requeue', { messageId: id }))),
-            new Promise((resolve) => {
-              const timer = setTimeout(resolve, Math.max(0, Number(requeueTimeoutMs) || 0));
-              timer.unref?.();
-            }),
-          ]);
-        }
+        await requeueOwedRows({ api, entries: getActiveQueueMessageIds() || [], timeoutMs: requeueTimeoutMs });
       } catch {}
       try { onBeforeExit(); } catch {}
       exit(1);

package/shared/worker-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/shared/worker-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/shared/worker-runtime/heartbeat.mjs

@@ -0,0 +1,109 @@
+export function createHeartbeatController({
+  api,
+  pollMs,
+  getSessionReady,
+  getHeartbeatTimer,
+  setHeartbeatTimer,
+  getActiveQueueMessageId,
+  // Optional: every queue message the worker currently owns work for (a
+  // persistent-process worker can hold a running turn, a delivered message
+  // queued behind it, and a background continuation at once). Each reported
+  // id gets its owner lease refreshed; unreported owned rows are recovered.
+  getActiveQueueMessageIds,
+  // Optional: the worker's steering snapshot ({turnActive, canSteer,
+  // holdReason}) for the composer. Workers that do not steer leave it unset
+  // and the heartbeat body is unchanged.
+  getSteeringState,
+  // Optional: rows the worker gave up settling ([{id, attemptId,
+  // terminalError}]); the relay fails them and names them back in
+  // `settleFailedHandled`, which `onSettleFailedHandled` receives.
+  getSettleFailed,
+  onSettleFailedHandled = () => {},
+  // requestPulse's window: one turn transition can flip the steering
+  // snapshot several times in quick succession, and each flip only needs to
+  // reach the relay once.
+  pulseCoalesceMs = 300,
+  setTimeoutImpl = setTimeout,
+  clearTimeoutImpl = clearTimeout,
+}) {
+  let requestedPulseTimer = null;
+
+  async function pulseHeartbeat() {
+    if (!getSessionReady()) return false;
+    try {
+      const activeQueueMessageId = typeof getActiveQueueMessageId === "function"
+        ? String(getActiveQueueMessageId() || "").trim()
+        : "";
+      const activeQueueMessageIds = typeof getActiveQueueMessageIds === "function"
+        ? (getActiveQueueMessageIds() || []).map((id) => String(id || "").trim()).filter(Boolean)
+        : [];
+      const steering = typeof getSteeringState === "function"
+        ? getSteeringState()
+        : null;
+      const settleFailed = typeof getSettleFailed === "function"
+        ? (getSettleFailed() || []).filter((entry) => entry && String(entry.id || "").trim())
+        : [];
+      const body = {
+        ...(activeQueueMessageId ? { activeQueueMessageId } : {}),
+        ...(activeQueueMessageIds.length ? { activeQueueMessageIds } : {}),
+        ...(steering && typeof steering === "object" ? { steering } : {}),
+        ...(settleFailed.length ? { settleFailed } : {}),
+      };
+      const response = await api("POST", "/api/heartbeat", body);
+      // Failed by the relay, or skipped because this worker has no claim on
+      // the row: either way the worker releases it.
+      const handled = [
+        ...(Array.isArray(response?.settleFailedHandled) ? response.settleFailedHandled : []),
+        ...(Array.isArray(response?.settleFailedSkipped) ? response.settleFailedSkipped : []),
+      ];
+      if (handled.length) {
+        try { onSettleFailedHandled(handled); } catch {}
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * An out-of-cycle pulse for state the relay should see before the next
+   * periodic one (the composer's steering snapshot, a relay that just came
+   * up). Requests inside one window share a single pulse, sent at its end so
+   * it carries the settled state.
+   */
+  function requestPulse() {
+    if (requestedPulseTimer) return;
+    requestedPulseTimer = setTimeoutImpl(() => {
+      requestedPulseTimer = null;
+      void pulseHeartbeat();
+    }, pulseCoalesceMs);
+    requestedPulseTimer?.unref?.();
+  }
+
+  function startHeartbeat() {
+    if (getHeartbeatTimer()) return;
+    void pulseHeartbeat();
+    const timer = setInterval(() => {
+      void pulseHeartbeat();
+    }, pollMs);
+    setHeartbeatTimer(timer);
+  }
+
+  function stopHeartbeat() {
+    if (requestedPulseTimer) {
+      clearTimeoutImpl(requestedPulseTimer);
+      requestedPulseTimer = null;
+    }
+    const timer = getHeartbeatTimer();
+    if (!timer) return;
+    clearInterval(timer);
+    setHeartbeatTimer(null);
+  }
+
+  return {
+    pulseHeartbeat,
+    requestPulse,
+    startHeartbeat,
+    stopHeartbeat,
+  };
+}