@oar-sh/oar 0.9.1 → 0.9.3

package/shared/worker-runtime/prompt-context.mjs

@@ -0,0 +1,160 @@
+import {
+  applyPreviewInstructions,
+  createPreviewInstructionsProvider,
+} from "../preview-instructions.mjs";
+
+export { createPreviewInstructionsProvider };
+
+export function buildPrompt(message) {
+  const text = String(message?.text || "").trim();
+  const attachments = Array.isArray(message?.attachments) ? message.attachments : [];
+  if (!attachments.length) return text;
+
+  const attachmentNote = attachments.map((att) => {
+    const name = att?.name ? String(att.name) : "attachment";
+    const type = att?.type ? String(att.type) : "file";
+    if (type.startsWith("image/")) return `${name} (${type}, inline image attachment)`;
+    const reference = att?.path ? ` @${att.path}` : "";
+    return `${name} (${type})${reference}`;
+  }).join(", ");
+  const suffix = `\n\n[Attached file${attachments.length === 1 ? "" : "s"}: ${attachmentNote}]`;
+  return text ? `${text}${suffix}` : suffix.trimStart();
+}
+
+function normalizeRelayMode(mode) {
+  const value = String(mode || "agent").trim().toLowerCase();
+  if (value === "plan" || value === "ask" || value === "autopilot" || value === "agent") return value;
+  return "agent";
+}
+
+function buildModeInstructionText(mode) {
+  if (mode === "plan") {
+    return [
+      "Draft a concise plan only.",
+      "Use read-only inspection tools (glob, rg, view) only when they materially improve plan quality; otherwise draft from provided context.",
+      "Do not edit repository files or run mutating commands unless the user explicitly asks for implementation.",
+      "If clarification is required, pause and ask through the web relay.",
+      "These instructions remain in effect until relay mode changes.",
+    ].join(" ");
+  }
+  if (mode === "ask") {
+    return [
+      "Prioritize clarification questions before doing any implementation work.",
+      "If the request is ambiguous or underspecified, pause and ask through the web relay before making assumptions.",
+      "Do not make broad assumptions when a question would materially change the result.",
+      "These instructions remain in effect until relay mode changes.",
+    ].join(" ");
+  }
+  if (mode === "autopilot") {
+    return [
+      "Act directly on the request and use tools when needed.",
+      "Keep moving unless user input is truly blocking.",
+      "These instructions remain in effect until relay mode changes.",
+    ].join(" ");
+  }
+  return [
+    "Proceed as an interactive coding agent and use tools as needed.",
+    "If you need clarification, pause and ask through the web relay instead of stalling silently.",
+    "These instructions remain in effect until relay mode changes.",
+  ].join(" ");
+}
+
+export function buildModeMarker(mode) {
+  return `[Relay mode: ${normalizeRelayMode(mode)}]`;
+}
+
+export function buildModePrompt(mode, toolInstructions = "", options = {}) {
+  const normalizedMode = normalizeRelayMode(mode);
+  const includeInstructions = options?.includeInstructions !== false;
+  const parts = [buildModeMarker(normalizedMode)];
+  if (includeInstructions) {
+    parts.push(buildModeInstructionText(normalizedMode));
+    if (toolInstructions) {
+      parts.push(toolInstructions);
+    }
+  }
+  return parts.join(" ");
+}
+
+export function buildPromptWithMode(message, toolInstructions = "", options = {}) {
+  const modePrompt = buildModePrompt(message?.relayMode, toolInstructions, options);
+  const body = buildPrompt(message);
+  return [modePrompt, body].filter(Boolean).join(" ");
+}
+
+/**
+ * The relay's prompt prefix builder: tool guidance rides along only when the
+ * relay mode changed, so repeat turns in one mode stay cheap.
+ */
+export function createRelayPromptBuilder({
+  toolInstructions = "",
+  getPreviewInstructions = null,
+} = {}) {
+  let lastPromptedRelayMode = null;
+  return async function buildPromptWithRelayContext(message) {
+    const relayMode = normalizeRelayMode(message?.relayMode);
+    const includeInstructions = lastPromptedRelayMode !== relayMode;
+    let instructions = "";
+    if (includeInstructions) {
+      // Guidance is advisory: a preview lookup that fails must cost the block,
+      // never the turn.
+      const previewBlock = typeof getPreviewInstructions === "function"
+        ? await Promise.resolve().then(getPreviewInstructions).catch(() => "")
+        : "";
+      instructions = applyPreviewInstructions(toolInstructions, previewBlock);
+    }
+    const prompt = buildPromptWithMode({ ...message, relayMode }, instructions, { includeInstructions });
+    lastPromptedRelayMode = relayMode;
+    return prompt;
+  };
+}
+
+export function stripPromptPrefix(text, promptPrefix = "") {
+  const value = String(text || "").trim();
+  if (!value) return "";
+  const prompt = String(promptPrefix || "").trim();
+  if (!prompt) return value;
+  if (!value.startsWith(prompt)) return value;
+  const remainder = value.slice(prompt.length).trim();
+  return remainder || "";
+}
+
+function escapeRegExp(value) {
+  return String(value || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function whitespaceFlexiblePattern(value) {
+  return String(value || "")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((part) => escapeRegExp(part))
+    .join("\\s+");
+}
+
+function stripPromptPrefixFlexible(text, promptPrefix = "") {
+  const value = String(text || "").trim();
+  const prompt = String(promptPrefix || "").trim();
+  if (!value || !prompt) return value;
+  const pattern = new RegExp(`^${whitespaceFlexiblePattern(prompt)}\\s*`, "i");
+  const stripped = value.replace(pattern, "").trim();
+  return stripped || "";
+}
+
+export function stripPromptContextPrefix(text, message, toolInstructions = "", promptPrefix = "") {
+  const value = String(text || "").trim();
+  if (!value) return "";
+  const candidates = [
+    String(promptPrefix || "").trim(),
+    buildPromptWithMode(message, toolInstructions),
+    buildPromptWithMode(message, toolInstructions, { includeInstructions: false }),
+    buildModeMarker(message?.relayMode),
+  ].filter(Boolean);
+  for (const candidate of candidates) {
+    const stripped = stripPromptPrefix(value, candidate);
+    if (stripped !== value) return stripped;
+    const flexibleStripped = stripPromptPrefixFlexible(value, candidate);
+    if (flexibleStripped !== value) return flexibleStripped;
+  }
+  return value;
+}

package/shared/worker-runtime/runner-link-wiring.mjs

@@ -0,0 +1,44 @@
+// Glue between a steering-capable session runner and the relay socket link —
+// shared by every worker whose runner exposes a delivery gate (the Claude
+// session runner, the Copilot SDK runner). Kept out of the worker entry files
+// (which run main() on import) so the wiring itself is testable.
+
+import { requeueOwedRows } from '../worker-crash-guard.mjs';
+
+/**
+ * The runner reports every flip of its delivery gate; the link turns them
+ * into relay readiness frames. `attach` is late-bound because the runner is
+ * built before the link (the link's probes call into the runner).
+ */
+export function createRunnerLinkBridge() {
+  let link = null;
+  return {
+    attach(nextLink) {
+      link = nextLink || null;
+    },
+    onDeliveryReadinessChange(ready) {
+      if (!link) return;
+      if (ready) void link.notifyReady('steering-resumed');
+      else link.notifyUnready('steering-held');
+    },
+    // Only a relay that advertised the capability in server.hello understands
+    // the penalty-free hand-back; before any hello, assume an older relay.
+    canHandBackHeldDelivery() {
+      return Boolean(link?.serverSupports?.('steering-held'));
+    },
+  };
+}
+
+/**
+ * Worker shutdown (SIGTERM/SIGINT): rows whose prompt the engine already
+ * consumed and whose settle has not landed are failed terminally before the
+ * process goes — left behind, the relay's dead-worker recovery would requeue
+ * them and run them a second time. Bounded like the crash guard: a shutdown
+ * that hangs is worse than none. Other owed rows are left to the relay's
+ * recovery, as before.
+ */
+export async function failSettlingRowsOnShutdown({ api, runner, timeoutMs = 2_000 } = {}) {
+  const settling = (runner?.getActiveQueueMessageIds?.() || []).filter((entry) => entry?.terminalError);
+  await requeueOwedRows({ api, entries: settling, timeoutMs });
+  return settling.length;
+}

package/shared/worker-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(" ");
+}