@oar-sh/oar 0.9.3 → 0.9.5

package/shared/remote-relay-tool-core.mjs

@@ -0,0 +1,314 @@
+// The provider-facing side of the `remote_relay` tool, in one place.
+//
+// Every adapter (Claude's in-process MCP server, Cursor's customTools, the
+// Copilot SDK engine's session tools, and the OAR stdio MCP server that Grok
+// and the Copilot extension engine reach) registers the SAME name, description
+// and schema from the contract and forwards every call to the one local relay
+// endpoint. The relay does the gating, the approval, the forwarding and the
+// waiting; nothing here knows about remote relays beyond the wire shape.
+//
+// SDK-free and dependency-injected, following preview-tool-core.mjs: all relay
+// traffic goes through the worker's injected `api(method, path, body, options)`
+// helper (shared/worker-runtime/api-client.mjs).
+
+import {
+  REMOTE_RELAY_ERROR_CODES,
+  REMOTE_RELAY_TOOL_DESCRIPTION,
+  REMOTE_RELAY_TOOL_ENDPOINT,
+  REMOTE_RELAY_TOOL_INPUT_SCHEMA,
+  REMOTE_RELAY_TOOL_NAME,
+  summarizeRemoteRelayCall,
+  validateRemoteRelayToolInput,
+} from './remote-relay-contract.mjs';
+
+export {
+  REMOTE_RELAY_TOOL_DESCRIPTION,
+  REMOTE_RELAY_TOOL_ENDPOINT,
+  REMOTE_RELAY_TOOL_INPUT_SCHEMA,
+  REMOTE_RELAY_TOOL_NAME,
+  summarizeRemoteRelayCall,
+};
+
+// The adapters' crisp early check; the relay validates again authoritatively.
+export const validateRemoteRelayTool = validateRemoteRelayToolInput;
+
+/**
+ * A private deep copy of the contract schema for SDKs that take ownership of
+ * the object they are handed (the contract's is frozen at the top level, and
+ * an SDK that annotates its input would throw on it).
+ */
+export function cloneRemoteRelayToolInputSchema() {
+  return JSON.parse(JSON.stringify(REMOTE_RELAY_TOOL_INPUT_SCHEMA));
+}
+
+// How many remotes this relay knows (`{ count }`): the registration decision.
+export const REMOTE_RELAY_SUMMARY_PATH = '/api/remote-relays/summary';
+// Calls of one conversation the relay is still working on (`{ inflight }`):
+// the Grok inactivity hold, which cannot see the tool call itself.
+export const REMOTE_RELAY_INFLIGHT_PATH = '/api/remote-relays/inflight';
+
+// The local relay could not be asked at all, or answered without a body the
+// model could read (a transport error, a crash page). Distinct from every
+// contract code, which describe a refusal the relay itself made.
+export const REMOTE_RELAY_CALL_FAILED = 'REMOTE_RELAY_CALL_FAILED';
+
+// The provider cancelled the call (the user's Stop, a host's cancel, a
+// runtime going away) before the relay answered. The relay sees the request
+// close and stops too: it withdraws an open approval card and stops waiting
+// on the remote. A prompt already handed over is NOT taken back.
+export const REMOTE_RELAY_CANCELLED = 'REMOTE_RELAY_CANCELLED';
+
+// How long the registration probe may take before the tool is left out.
+export const REMOTE_RELAY_DECISION_TIMEOUT_MS = 5_000;
+
+// A hard ceiling for one tool call on the providers that impose their own
+// (MCP clients). The relay already bounds the wait (wait_seconds ≤ 600) but not
+// the time an approval card may sit unanswered, so this only has to outlast a
+// human, never a remote turn.
+export const REMOTE_RELAY_TOOL_CALL_TIMEOUT_MS = 8 * 60 * 60_000;
+
+function toText(value) {
+  return String(value ?? '').trim();
+}
+
+function withTimeout(promise, timeoutMs, label) {
+  if (!(Number(timeoutMs) > 0)) return promise;
+  let timer = null;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+      timer.unref?.();
+    }),
+  ]).finally(() => { if (timer) clearTimeout(timer); });
+}
+
+function errorBodyOf(error) {
+  // `body` is the parsed JSON error body when the api client kept it; a
+  // client that parsed it into `detail` instead is tolerated too.
+  for (const candidate of [error?.body, error?.detail]) {
+    if (candidate && typeof candidate === 'object' && !Array.isArray(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Maps an api-client failure onto the result shape the model reads. The relay
+ * answers a refusal with `{ ok:false, code, error }` and a 4xx/5xx status; that
+ * body IS the answer (LOCKED, FORBIDDEN, OFFLINE, …), so it is passed through
+ * as-is. Anything without such a body becomes REMOTE_RELAY_CALL_FAILED.
+ */
+export function remoteRelayErrorResult(error) {
+  const status = Number(error?.status) || 0;
+  const body = errorBodyOf(error);
+  const detail = typeof error?.detail === 'string' ? toText(error.detail) : '';
+  if (body && (body.code || body.error)) {
+    return {
+      ...body,
+      ok: false,
+      code: toText(body.code) || REMOTE_RELAY_CALL_FAILED,
+      error: toText(body.error || body.message) || detail || `HTTP ${status}`,
+    };
+  }
+  if (status === 404) {
+    // A relay that predates the feature (or runs without its routes).
+    return {
+      ok: false,
+      code: REMOTE_RELAY_ERROR_CODES.unsupported,
+      error: 'This relay does not offer remote relays (the tool endpoint is missing). Tell the user.',
+    };
+  }
+  return {
+    ok: false,
+    code: REMOTE_RELAY_CALL_FAILED,
+    ...(status ? { status } : {}),
+    error: detail || toText(error?.message || error) || 'The relay could not be reached',
+  };
+}
+
+function isAbortError(error) {
+  return error?.name === 'AbortError' || error?.code === 'ABORT_ERR';
+}
+
+/** The answer for a call its provider cancelled before the relay answered. */
+export function remoteRelayCancelledResult() {
+  return {
+    ok: false,
+    code: REMOTE_RELAY_CANCELLED,
+    error: 'The call was cancelled before the relay answered. A message it had already handed over may still run on the remote.',
+  };
+}
+
+/**
+ * Executes one `remote_relay` call: validate, then forward
+ * `{ conversationId, action, args }` to the local relay and hand back its JSON.
+ * Never throws — a refusal reads as an answer the model can act on, the same
+ * contract as executePreviewTool.
+ *
+ * The call goes out as a long call (`{ longCall: true }`): no client-side
+ * timeout at all, because the relay bounds the wait itself (wait_seconds plus
+ * approval time) and fetch's 300 s header limit would cut both short.
+ * `signal` (the provider's cancellation) is the only way to end it early.
+ */
+export async function executeRemoteRelayTool(input, { api, conversationId = '', signal = null } = {}) {
+  if (typeof api !== 'function') {
+    return { ok: false, code: REMOTE_RELAY_CALL_FAILED, error: 'Remote relay API unavailable in this worker' };
+  }
+  const conversation = toText(conversationId);
+  if (!conversation) {
+    return { ok: false, code: REMOTE_RELAY_CALL_FAILED, error: 'No conversation is bound to this call' };
+  }
+  const parsed = validateRemoteRelayToolInput(input);
+  if (!parsed.ok) return parsed;
+  if (signal?.aborted) return remoteRelayCancelledResult();
+  try {
+    const response = await api('POST', REMOTE_RELAY_TOOL_ENDPOINT, {
+      conversationId: conversation,
+      action: parsed.action,
+      args: parsed.args,
+    }, { longCall: true, ...(signal ? { signal } : {}) });
+    if (response && typeof response === 'object' && !Array.isArray(response)) return response;
+    return { ok: true, result: response ?? null };
+  } catch (error) {
+    if (signal?.aborted || isAbortError(error)) return remoteRelayCancelledResult();
+    return remoteRelayErrorResult(error);
+  }
+}
+
+/**
+ * Whether a worker should register the tool: at least one remote is paired.
+ * Fails closed — any error, a malformed answer or a slow relay leaves the tool
+ * out, and the next worker start asks again.
+ */
+export async function shouldRegisterRemoteRelayTool({ api, timeoutMs = REMOTE_RELAY_DECISION_TIMEOUT_MS } = {}) {
+  if (typeof api !== 'function') return false;
+  try {
+    const response = await withTimeout(
+      Promise.resolve().then(() => api('GET', REMOTE_RELAY_SUMMARY_PATH)),
+      timeoutMs,
+      'remote relay summary',
+    );
+    return Number(response?.count) > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The registration decision as a worker holds it: asked once when the worker
+ * starts (`refresh()`), read synchronously where a tool set is fixed
+ * (`isEnabled()`), and awaitable where the first build may wait for it
+ * (`ready()`, which never rejects). `fixed` pins the answer (tests, kill
+ * switches) without asking the relay.
+ */
+export function createRemoteRelayToolGate({
+  api,
+  fixed = undefined,
+  decide = shouldRegisterRemoteRelayTool,
+  timeoutMs = REMOTE_RELAY_DECISION_TIMEOUT_MS,
+} = {}) {
+  if (typeof fixed === 'boolean') {
+    return {
+      isEnabled: () => fixed,
+      isSettled: () => true,
+      refresh: () => Promise.resolve(fixed),
+      ready: () => Promise.resolve(fixed),
+    };
+  }
+  let enabled = false;
+  let settledOnce = false;
+  let pending = null;
+  function refresh() {
+    if (!pending) {
+      pending = Promise.resolve()
+        .then(() => decide({ api, timeoutMs }))
+        .then((value) => { enabled = value === true; }, () => { enabled = false; })
+        .then(() => {
+          settledOnce = true;
+          pending = null;
+          return enabled;
+        });
+    }
+    return pending;
+  }
+  return {
+    isEnabled: () => enabled,
+    // True once an answer is in and no refresh is running: a caller can then
+    // read isEnabled() without awaiting ready().
+    isSettled: () => settledOnce && !pending,
+    refresh,
+    ready: () => (settledOnce && !pending ? Promise.resolve(enabled) : (pending || refresh())),
+  };
+}
+
+/**
+ * How many remote_relay calls of this conversation the relay is still working
+ * on. 0 on any failure: the caller's watchdog then does what it would have
+ * done without the question.
+ */
+export async function fetchRemoteRelayInflight({ api, conversationId = '', timeoutMs = 10_000 } = {}) {
+  const conversation = toText(conversationId);
+  if (typeof api !== 'function' || !conversation) return 0;
+  try {
+    const response = await withTimeout(
+      Promise.resolve().then(() => api(
+        'GET',
+        `${REMOTE_RELAY_INFLIGHT_PATH}?conversationId=${encodeURIComponent(conversation)}`,
+      )),
+      timeoutMs,
+      'remote relay inflight',
+    );
+    const count = Number(response?.inflight);
+    return Number.isFinite(count) && count > 0 ? count : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** The text every adapter hands the model: the relay's JSON, pretty-printed. */
+export function formatRemoteRelayToolResult(result) {
+  try {
+    const text = JSON.stringify(result ?? null, null, 2);
+    return text === undefined ? 'null' : text;
+  } catch {
+    return String(result);
+  }
+}
+
+// ─── Activity lines ──────────────────────────────────────────────────────────
+
+// A provider may report the tool under its bare name or namespaced by the MCP
+// server that carries it (`mcp__relay__remote_relay`, `oar__remote_relay`,
+// `oar/remote_relay`, `oar-remote_relay`); all of them are this tool.
+const REMOTE_RELAY_NAME_PATTERN = new RegExp(`(?:^|__|[^A-Za-z0-9_])${REMOTE_RELAY_TOOL_NAME}$`, 'i');
+
+export function isRemoteRelayToolName(name) {
+  return REMOTE_RELAY_NAME_PATTERN.test(toText(name));
+}
+
+/**
+ * The arguments of a tool call as an object, whether the provider delivered
+ * them parsed or as a JSON string. Null when there is nothing usable.
+ */
+export function remoteRelayCallInput(rawInput) {
+  let input = rawInput;
+  if (typeof input === 'string') {
+    try {
+      input = JSON.parse(input);
+    } catch {
+      return null;
+    }
+  }
+  return input && typeof input === 'object' && !Array.isArray(input) ? input : null;
+}
+
+/**
+ * The summary part of the activity line (`send → linux-test session 01234567:
+ * “…”`), or '' when the call carries no action yet (a streaming frame before
+ * its arguments arrived) so the caller keeps its generic line.
+ */
+export function remoteRelayActivitySummary(rawInput) {
+  const input = remoteRelayCallInput(rawInput);
+  if (!input || !toText(input.action)) return '';
+  return summarizeRemoteRelayCall(input);
+}

package/shared/steer-settle-failure.mjs

@@ -41,6 +41,12 @@ const VARIANTS = Object.freeze({
     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.',
   }),
+  // Not a steer: delivered between turns and answered on a background
+  // continuation row (ANSWERED_ELSEWHERE_KIND in steer-settle-markers.mjs).
+  answeredElsewhere: (label) => ({
+    message: `${sentenceCase(label)} answered this message in a reply marked “background continuation” — check the replies next to it.`,
+    guidance: 'Resend it only if it went unanswered.',
+  }),
   // 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) => ({

package/shared/steer-settle-markers.mjs

@@ -16,3 +16,19 @@ export const STEER_FOLDED_TEXT = '_(Handled together with the previous reply —
  * kind='stopped' — the stable handle the client keys its Resend on.
  */
 export const STEER_STOPPED_TEXT = '_(Stopped with the turn — not answered.)_';
+
+/**
+ * Not a steer: a message delivered between turns whose answer the worker
+ * published on a background-continuation row, because it took the turn for one
+ * the CLI had opened by itself. Stamped with a kind of its own: it is a
+ * marker, not a reply (no completion push, muted in the transcript, never
+ * handed to a calling relay as the answer), and not a steer marker either,
+ * which would label the message "steered mid-turn".
+ *
+ * The wording names the reply by its badge, not by its position: a live
+ * append puts the marker below that reply, a reload anchors it under its own
+ * message and so above it. The worker infers all this from silence, hence the
+ * way out at the end.
+ */
+export const ANSWERED_ELSEWHERE_KIND = 'answered-elsewhere';
+export const DELIVERY_ANSWERED_ELSEWHERE_TEXT = '_(Answered in the reply marked “background continuation” next to this message. Resend the message if that reply does not answer it.)_';

package/shared/worker-runtime/api-client.mjs

@@ -1,33 +1,123 @@
+import http from "node:http";
+import https from "node:https";
+
+// The error a non-2xx answer throws, the same for both transports:
+// `HTTP <status> <path>: <detail>`, with `status`, `detail` and `body`.
+function httpError(status, routePath, text) {
+  const rawText = String(text || "").trim();
+  let detail = rawText;
+  let payload = null;
+  if (rawText) {
+    try {
+      payload = JSON.parse(rawText);
+      detail = String(payload?.error || payload?.message || rawText).trim();
+    } catch {
+      detail = rawText;
+    }
+  }
+  const error = new Error(`HTTP ${status} ${routePath}${detail ? `: ${detail}` : ""}`);
+  error.status = status;
+  error.detail = detail;
+  // The parsed error body, for callers that pass the relay's answer on as
+  // is (a refused remote_relay call carries its code there).
+  error.body = payload && typeof payload === "object" ? payload : null;
+  return error;
+}
+
+function abortError(signal) {
+  const error = new Error("The operation was aborted");
+  error.name = "AbortError";
+  error.code = "ABORT_ERR";
+  if (signal?.reason !== undefined) error.cause = signal.reason;
+  return error;
+}
+
+/**
+ * One request over node:http(s) with no clock on it at all. Global fetch
+ * (undici) gives up when no response headers arrive within 300 s, and a
+ * long call's route sends nothing until it has its answer: a remote turn of
+ * up to 600 s, or an approval card that may sit for hours. So: its own
+ * connection (`agent: false` — the global agent carries a socket timeout),
+ * no request timeout, no body timeout. Only `signal` ends it early; the
+ * relay notices the closed request and stops waiting on its side too.
+ */
+function requestWithoutTimeout({ url, method, headers, payload, signal }) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortError(signal));
+      return;
+    }
+    const target = new URL(url);
+    const transport = target.protocol === "https:" ? https : http;
+    let settled = false;
+    let req = null;
+    const onAbort = () => {
+      const error = abortError(signal);
+      finish(error);
+      req?.destroy(error);
+    };
+    function finish(error, value) {
+      if (settled) return;
+      settled = true;
+      signal?.removeEventListener?.("abort", onAbort);
+      if (error) reject(error);
+      else resolve(value);
+    }
+    req = transport.request(target, {
+      method,
+      agent: false,
+      headers: {
+        ...headers,
+        ...(payload !== undefined ? { "Content-Length": Buffer.byteLength(payload) } : {}),
+      },
+    }, (res) => {
+      const chunks = [];
+      res.on("data", (chunk) => { chunks.push(chunk); });
+      res.on("end", () => finish(null, { status: res.statusCode, text: Buffer.concat(chunks).toString("utf8") }));
+      res.on("error", (error) => finish(error));
+      res.on("close", () => {
+        if (!res.complete) finish(new Error(`The relay closed the connection mid-answer (${url})`));
+      });
+    });
+    req.on("error", (error) => finish(error));
+    signal?.addEventListener?.("abort", onAbort, { once: true });
+    if (payload !== undefined) req.write(payload);
+    req.end();
+  });
+}
+
 export function createApiClient({ serverUrl, token, getHeaders }) {
-  return async function api(method, routePath, body) {
+  /**
+   * `options.longCall`: a call the relay may legitimately hold open for many
+   * minutes (the remote_relay tool) — it goes over node:http without any
+   * timeout instead of fetch. `options.signal` aborts either kind; an aborted
+   * call rejects with an AbortError.
+   */
+  return async function api(method, routePath, body, { longCall = false, signal = null } = {}) {
     const url = `${serverUrl}${routePath}`;
     const extraHeaders = typeof getHeaders === "function" ? (getHeaders() || {}) : {};
+    const headers = {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`,
+      ...extraHeaders,
+    };
+    const payload = method !== "GET" ? JSON.stringify(body || {}) : undefined;
+
+    if (longCall) {
+      const res = await requestWithoutTimeout({ url, method, headers, payload, signal });
+      if (res.status < 200 || res.status > 299) throw httpError(res.status, routePath, res.text);
+      return JSON.parse(res.text);
+    }
+
     const opts = {
       method,
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${token}`,
-        ...extraHeaders,
-      },
-      ...(method !== "GET" ? { body: JSON.stringify(body || {}) } : {}),
+      headers,
+      ...(payload !== undefined ? { body: payload } : {}),
+      ...(signal ? { signal } : {}),
     };
-
     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;
+      throw httpError(res.status, routePath, await res.text().catch(() => ""));
     }
     return res.json();
   };

package/shared/worker-runtime/worker-log-file.mjs

@@ -0,0 +1,97 @@
+// The worker log for launches that cannot redirect the worker's output.
+//
+// On Linux the launcher redirects a Node worker's stdout/stderr into
+// `<log dir>/worker-<session id>.log` (`>> file 2>&1` under tmux, an inherited
+// descriptor on the detached path). On Windows the worker runs in its own
+// console window behind `cmd /c start`: no descriptor of the launcher reaches
+// it, and a shell redirect would empty the window. So the launcher names the
+// file in `COPILOT_WEB_RELAY_WORKER_LOG_FILE` and the worker copies what it
+// writes to stdout/stderr into it, while the console keeps showing the same
+// lines.
+//
+// Out of reach from inside the process: what Node prints natively (a V8 fatal
+// error such as heap exhaustion, a module that fails to load before this is
+// installed) and what a child process writes to an inherited console.
+import fs from 'fs';
+
+export const WORKER_LOG_FILE_ENV = 'COPILOT_WEB_RELAY_WORKER_LOG_FILE';
+
+// Colours are for the console; the Linux file never has them, because there
+// stdout is not a terminal.
+const ANSI_STYLE_PATTERN = /\u001b\[[0-9;]*m/g;
+
+/**
+ * Copies stdout/stderr into the log file the launcher named. Returns null when
+ * no file was named or it cannot be opened: best-effort like the launcher's
+ * side, a log problem must never stop a worker.
+ */
+export function installWorkerLogFile({
+  env = process.env,
+  processImpl = process,
+  fsImpl = fs,
+} = {}) {
+  const logPath = String(env?.[WORKER_LOG_FILE_ENV] || '').trim();
+  // Not inherited: the provider CLI, the agent's shells and anything started
+  // from them must not write into this worker's log.
+  if (env && WORKER_LOG_FILE_ENV in env) delete env[WORKER_LOG_FILE_ENV];
+  if (!logPath) return null;
+
+  let fd = null;
+  try {
+    fd = fsImpl.openSync(logPath, 'a');
+  } catch {
+    return null;
+  }
+
+  // Synchronous on purpose: the last lines before a process.exit() are the
+  // ones an incident needs.
+  const append = (chunk, encoding) => {
+    if (fd === null) return;
+    try {
+      if (typeof chunk === 'string') {
+        const text = chunk.replace(ANSI_STYLE_PATTERN, '');
+        if (text) fsImpl.writeSync(fd, text, null, typeof encoding === 'string' ? encoding : 'utf8');
+      } else if (chunk instanceof Uint8Array) {
+        fsImpl.writeSync(fd, chunk);
+      }
+    } catch {
+      // A file that stopped taking writes (disk full, handle gone) is given up.
+      try { fsImpl.closeSync(fd); } catch {}
+      fd = null;
+    }
+  };
+
+  const restores = [];
+  for (const stream of [processImpl.stdout, processImpl.stderr]) {
+    if (!stream || typeof stream.write !== 'function') continue;
+    const originalWrite = stream.write;
+    const teeWrite = function teeWrite(chunk, encoding, callback) {
+      append(chunk, encoding);
+      return originalWrite.call(this, chunk, encoding, callback);
+    };
+    stream.write = teeWrite;
+    restores.push(() => {
+      if (stream.write === teeWrite) stream.write = originalWrite;
+    });
+  }
+
+  // Without an uncaughtException handler Node prints the error natively, past
+  // the streams above. With one (the worker crash guard) the handler logs it.
+  const onUncaught = (error, origin) => {
+    if (processImpl.listenerCount('uncaughtException') > 0) return;
+    append(`${origin || 'uncaughtException'}: ${error?.stack || error?.message || error}\n`);
+  };
+  processImpl.on?.('uncaughtExceptionMonitor', onUncaught);
+
+  return {
+    logPath,
+    uninstall() {
+      for (const restore of restores) restore();
+      processImpl.off?.('uncaughtExceptionMonitor', onUncaught);
+      if (fd !== null) {
+        try { fsImpl.closeSync(fd); } catch {}
+        fd = null;
+      }
+    },
+  };
+}