@oar-sh/oar 0.9.6 → 0.9.7

package/server/services/session-worker-supervisor-service.mjs

@@ -63,6 +63,19 @@ export function createSessionWorkerSupervisor({
   maxRestartRetries = 5,
   restartBackoffBaseMs = 1_000,
   restartBackoffMaxMs = 30_000,
+  // Exhausted is not for ever: what failed the launches can be gone — a
+  // process list the relay could not read for an hour was (2026-10-01) — and
+  // the pending work would otherwise wait for a hand-made launch or a relay
+  // restart. One more launch is allowed this long after the last failure; a
+  // failure exhausts the session again at once. 0 keeps it exhausted.
+  restartExhaustedRetryAfterMs = 60_000,
+  // ...and not for longer than this after the first exhaustion: then the
+  // session stays exhausted until a launch is asked for (the Retry button,
+  // the launch or kill route, a relay restart). 0 retries without end.
+  restartExhaustedRetryWindowMs = 10 * 60_000,
+  // Told about launch episodes, for the note in the conversation:
+  // ({ type: 'exhausted' | 'retry-failed' | 'stopped' | 'launched', sdkSessionId, lifecycle }).
+  onLaunchState = null,
   idleEvictionMs = 0,
   // Copilot-kind workers boot a full CLI (auth, model catalog, workspace scan)
   // before their extension can heartbeat; measured median is ~35s. A 30s
@@ -88,6 +101,8 @@ export function createSessionWorkerSupervisor({
   const retryLimit = Math.max(0, clampInt(maxRestartRetries, 5));
   const backoffBaseMs = Math.max(1, clampInt(restartBackoffBaseMs, 1_000));
   const backoffMaxMs = Math.max(backoffBaseMs, clampInt(restartBackoffMaxMs, 30_000));
+  const exhaustedRetryAfterMs = Math.max(0, clampInt(restartExhaustedRetryAfterMs, 60_000));
+  const exhaustedRetryWindowMs = Math.max(0, clampInt(restartExhaustedRetryWindowMs, 10 * 60_000));
   const idleTimeoutMs = clampInt(idleEvictionMs, 0);
   const heartbeatStaleAfterMs = Math.max(1_000, clampInt(heartbeatTimeoutMs, 90_000));
   const recoveryGraceMs = Math.max(0, clampInt(degradedRecoveryGraceMs, 10_000));
@@ -129,6 +144,10 @@ export function createSessionWorkerSupervisor({
       backoffMs: 0,
       nextRestartAtMs: null,
       restartExhausted: false,
+      // The launch episode: when the launches were first exhausted, and
+      // whether the relay has stopped trying again by itself.
+      exhaustedSinceMs: null,
+      retriesStopped: false,
       lastError: null,
       lastFailureAtMs: null,
       lastActivityAtMs: nowAtMs,
@@ -167,6 +186,11 @@ export function createSessionWorkerSupervisor({
       backoffMs: clampInt(lifecycle.backoffMs, 0),
       nextRestartAt: lifecycle.nextRestartAtMs ? new Date(lifecycle.nextRestartAtMs).toISOString() : null,
       restartExhausted: Boolean(lifecycle.restartExhausted),
+      exhaustedSince: lifecycle.exhaustedSinceMs ? new Date(lifecycle.exhaustedSinceMs).toISOString() : null,
+      retriesStopped: Boolean(lifecycle.retriesStopped),
+      retryAgainAt: lifecycle.restartExhausted && !lifecycle.retriesStopped && lifecycle.lastFailureAtMs && exhaustedRetryAfterMs > 0
+        ? new Date(lifecycle.lastFailureAtMs + exhaustedRetryAfterMs).toISOString()
+        : null,
       lastError: lifecycle.lastError || null,
       lastFailureAt: lifecycle.lastFailureAtMs ? new Date(lifecycle.lastFailureAtMs).toISOString() : null,
       lastActivityAt: lifecycle.lastActivityAtMs ? new Date(lifecycle.lastActivityAtMs).toISOString() : null,
@@ -189,6 +213,16 @@ export function createSessionWorkerSupervisor({
     };
   }
 
+  // The caller's listener must not break the supervisor.
+  function notifyLaunchState(type, sessionId) {
+    if (typeof onLaunchState !== 'function') return;
+    try {
+      onLaunchState({ type, sdkSessionId: sessionId, lifecycle: toLifecycleSnapshot(sessionId) });
+    } catch (error) {
+      try { log?.(`launch state listener failed (${type}, session=${String(sessionId).slice(0, 8)}): ${error?.message || error}`); } catch {}
+    }
+  }
+
   function touchActivity(sessionId, atMs = nowMs()) {
     return setLifecycle(sessionId, { lastActivityAtMs: atMs });
   }
@@ -394,16 +428,26 @@ export function createSessionWorkerSupervisor({
     const failedAtMs = nowMs();
 
     if (nextRetryCount > retryLimit) {
+      const firstExhaustion = !lifecycle.restartExhausted;
+      const exhaustedSinceMs = lifecycle.exhaustedSinceMs || failedAtMs;
+      const retriesStopped = exhaustedRetryAfterMs === 0
+        || (exhaustedRetryWindowMs > 0 && failedAtMs - exhaustedSinceMs >= exhaustedRetryWindowMs);
       const exhausted = setLifecycle(sessionId, {
         retryCount: nextRetryCount,
         backoffMs: 0,
         nextRestartAtMs: null,
         restartExhausted: true,
+        exhaustedSinceMs,
+        retriesStopped,
         lastError: message,
         lastFailureAtMs: failedAtMs,
         lastActivityAtMs: failedAtMs,
       });
       registerDegradedState(sessionId, 'restart-exhausted', { atMs: failedAtMs });
+      notifyLaunchState(
+        firstExhaustion ? 'exhausted' : (retriesStopped && !lifecycle.retriesStopped ? 'stopped' : 'retry-failed'),
+        sessionId,
+      );
       return { scheduled: false, exhausted: true, lifecycle: toLifecycleSnapshot(sessionId, exhausted) };
     }
 
@@ -432,6 +476,8 @@ export function createSessionWorkerSupervisor({
       backoffMs: 0,
       nextRestartAtMs: null,
       restartExhausted: false,
+      exhaustedSinceMs: null,
+      retriesStopped: false,
       lastError: null,
       lastFailureAtMs: null,
       lastActivityAtMs: nowAtMs,
@@ -454,7 +500,13 @@ export function createSessionWorkerSupervisor({
     const lifecycle = lifecycleBySession.get(sessionId);
     if (!lifecycle) return { allowed: true, reason: null, lifecycle: null };
     if (lifecycle.restartExhausted) {
-      return { allowed: false, reason: 'restart-exhausted', lifecycle: toLifecycleSnapshot(sessionId, lifecycle) };
+      const failedAtMs = Number(lifecycle.lastFailureAtMs || 0);
+      const dueAgain = !lifecycle.retriesStopped
+        && exhaustedRetryAfterMs > 0 && failedAtMs > 0 && nowMs() - failedAtMs >= exhaustedRetryAfterMs;
+      if (!dueAgain) {
+        return { allowed: false, reason: 'restart-exhausted', lifecycle: toLifecycleSnapshot(sessionId, lifecycle) };
+      }
+      return { allowed: true, reason: null, lifecycle: toLifecycleSnapshot(sessionId, lifecycle) };
     }
     if (lifecycle.nextRestartAtMs && nowMs() < lifecycle.nextRestartAtMs) {
       return { allowed: false, reason: 'restart-delayed', lifecycle: toLifecycleSnapshot(sessionId, lifecycle) };
@@ -545,6 +597,7 @@ export function createSessionWorkerSupervisor({
       // backoff/exhausted lifecycle state was left behind by earlier failures.
       clearRestartSchedule(sessionId, { resetDegradedState: false });
       assessSessionHealth(sessionId, reusedWorker, { nowAtMs, questionPending: false });
+      notifyLaunchState('launched', sessionId);
       return { ok: true, reused: true, worker: reusedWorker, lifecycle: toLifecycleSnapshot(sessionId) };
     }
 
@@ -609,6 +662,7 @@ export function createSessionWorkerSupervisor({
           });
           clearRestartSchedule(sessionId);
           assessSessionHealth(sessionId, readyState, { questionPending: false });
+          notifyLaunchState('launched', sessionId);
           return { ok: true, reused: false, worker: readyState, lifecycle: toLifecycleSnapshot(sessionId) };
         }
         const simulatedReady = setWorkerState(sessionId, {
@@ -625,6 +679,7 @@ export function createSessionWorkerSupervisor({
         });
         clearRestartSchedule(sessionId);
         assessSessionHealth(sessionId, simulatedReady, { questionPending: false });
+        notifyLaunchState('launched', sessionId);
         return { ok: true, reused: false, worker: simulatedReady, lifecycle: toLifecycleSnapshot(sessionId) };
       } catch (error) {
         const scheduled = scheduleRestart(sessionId, error, { incrementRetry: true });

package/server/services/usage-limit-pause-service.mjs

@@ -177,7 +177,9 @@ export function createUsageLimitPauseService({
    */
   function planPause({ terminalError, conversationId, providerType, queueRow = null, partialText = '' } = {}) {
     if (!isUsageLimitTerminalError(terminalError)) return null;
-    if (String(providerType || '').trim().toLowerCase() !== 'claude') return null;
+    // Claude sessions, local and in the cloud: both run Claude Code on the
+    // same account and report the same limit.
+    if (!['claude', 'claude-cloud'].includes(String(providerType || '').trim().toLowerCase())) return null;
     if (!String(conversationId || '').trim()) return null;
     const at = now();
     const rateLimitType = String(terminalError.rateLimitType || '').trim() || null;

package/server/services/worker-launch-note-service.mjs

@@ -0,0 +1,151 @@
+'use strict';
+
+/**
+ * The note in the conversation when a session's worker cannot be started.
+ *
+ * Until 2026-10-01 a session whose launches were exhausted showed a yellow
+ * dot and nothing else: the message stayed queued, nothing said why, and
+ * nothing tried again. The supervisor now retries for a while and tells this
+ * service about the episode; the service keeps ONE relay-authored note per
+ * episode in the conversation and updates it in place — exhausted, each
+ * failed retry, stopped (with a Retry button in the client), started.
+ *
+ * The note is an assistant message of kind `worker-launch-failed`,
+ * `worker-launch-stopped` or `worker-launch-started`; the queued message is
+ * left queued throughout, so a launch that works delivers it.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+export const WORKER_LAUNCH_NOTE_KINDS = Object.freeze({
+  failed: 'worker-launch-failed',
+  stopped: 'worker-launch-stopped',
+  started: 'worker-launch-started',
+});
+
+const CAUSE_MAX_CHARS = 160;
+
+function clipCause(text) {
+  const cause = String(text || '').replace(/\s+/g, ' ').trim();
+  if (!cause) return 'unknown';
+  return cause.length > CAUSE_MAX_CHARS ? `${cause.slice(0, CAUSE_MAX_CHARS - 1)}…` : cause;
+}
+
+function defaultFormatTime(iso) {
+  const ms = Date.parse(String(iso || ''));
+  if (!Number.isFinite(ms)) return 'now';
+  return `${new Date(ms).toISOString().slice(11, 16)} UTC`;
+}
+
+function minutesOf(ms) {
+  const minutes = Math.max(1, Math.round(Number(ms || 0) / 60_000));
+  return `${minutes} minute${minutes === 1 ? '' : 's'}`;
+}
+
+/** The text of the note for an episode state; exported for the tests and the client copy. */
+export function buildWorkerLaunchNoteText({ type, lifecycle = {}, retryEveryMs = 60_000, retryWindowMs = 10 * 60_000, formatTime = defaultFormatTime } = {}) {
+  const tries = Math.max(0, Number(lifecycle?.retryCount || 0));
+  const triesText = `${tries} ${tries === 1 ? 'try' : 'tries'}`;
+  const cause = clipCause(lifecycle?.lastError);
+  if (type === 'launched') {
+    return `✅ The worker for this conversation started at ${formatTime(lifecycle?.launchAt || new Date().toISOString())}. The queued message is being delivered.`;
+  }
+  if (type === 'stopped') {
+    return `⛔ The worker for this conversation could not be started; the relay stopped trying after ${minutesOf(retryWindowMs)} (${triesText}). Cause: ${cause}. Your message stays queued — press Retry once the cause is fixed.`;
+  }
+  const until = lifecycle?.exhaustedSince && retryWindowMs > 0
+    ? ` until ${formatTime(new Date(Date.parse(lifecycle.exhaustedSince) + retryWindowMs).toISOString())}`
+    : '';
+  const last = type === 'retry-failed' && lifecycle?.lastFailureAt ? `, last at ${formatTime(lifecycle.lastFailureAt)}` : '';
+  return `⚠️ The worker for this conversation could not be started (${triesText}${last}). Cause: ${cause}. Your message stays queued; the relay tries again every ${minutesOf(retryEveryMs)}${until}.`;
+}
+
+export function createWorkerLaunchNoteService({
+  db,
+  stmts,
+  emit,
+  resolveConversationId,
+  retryEveryMs = 60_000,
+  retryWindowMs = 10 * 60_000,
+  now = () => Date.now(),
+  formatTime = defaultFormatTime,
+  logger = console,
+} = {}) {
+  if (!db || !stmts) throw new Error('createWorkerLaunchNoteService requires db and stmts');
+  const updateNote = db.prepare('UPDATE messages SET text = ?, kind = ? WHERE id = ?');
+  // One open episode per session: the note's id and where it is.
+  const episodes = new Map();
+
+  function kindFor(type) {
+    if (type === 'launched') return WORKER_LAUNCH_NOTE_KINDS.started;
+    if (type === 'stopped') return WORKER_LAUNCH_NOTE_KINDS.stopped;
+    return WORKER_LAUNCH_NOTE_KINDS.failed;
+  }
+
+  function conversationFor(sdkSessionId) {
+    try {
+      return String(resolveConversationId?.(sdkSessionId) || '').trim() || null;
+    } catch {
+      return null;
+    }
+  }
+
+  function messagePayload({ messageId, text, kind, timestamp }) {
+    return { id: messageId, role: 'assistant', text, kind, model: null, mode: null, attachments: [], timestamp };
+  }
+
+  function open({ sdkSessionId, conversationId, type, lifecycle }) {
+    const at = new Date(now()).toISOString();
+    const messageId = randomUUID();
+    const kind = kindFor(type);
+    const text = buildWorkerLaunchNoteText({ type, lifecycle, retryEveryMs, retryWindowMs, formatTime });
+    const write = db.transaction(() => {
+      stmts.insertMsg.run(messageId, conversationId, 'assistant', text, null, null, null, at, null, null, null);
+      stmts.setMessageKind?.run?.(kind, messageId);
+      stmts.updateConvTime?.run?.(at, conversationId);
+    });
+    write();
+    episodes.set(sdkSessionId, { messageId, conversationId, timestamp: at });
+    try { emit('assistant_message', { conversationId, messageId, message: messagePayload({ messageId, text, kind, timestamp: at }) }); } catch {}
+    try { logger.log?.(`[worker-launch] conv=${conversationId.slice(0, 8)} note opened (${type}): ${clipCause(lifecycle?.lastError)}`); } catch {}
+  }
+
+  function update(episode, sdkSessionId, { type, lifecycle }) {
+    const kind = kindFor(type);
+    const text = buildWorkerLaunchNoteText({ type, lifecycle, retryEveryMs, retryWindowMs, formatTime });
+    updateNote.run(text, kind, episode.messageId);
+    try {
+      emit('message_updated', {
+        conversationId: episode.conversationId,
+        messageId: episode.messageId,
+        message: messagePayload({ messageId: episode.messageId, text, kind, timestamp: episode.timestamp }),
+      });
+    } catch {}
+    if (type === 'launched') {
+      episodes.delete(sdkSessionId);
+      try { logger.log?.(`[worker-launch] conv=${episode.conversationId.slice(0, 8)} worker started, note closed`); } catch {}
+    }
+  }
+
+  /** The supervisor's onLaunchState listener. */
+  function handle({ type, sdkSessionId, lifecycle = null } = {}) {
+    const sid = String(sdkSessionId || '').trim();
+    if (!sid || !['exhausted', 'retry-failed', 'stopped', 'launched'].includes(type)) return false;
+    const episode = episodes.get(sid) || null;
+    if (episode) {
+      update(episode, sid, { type, lifecycle });
+      return true;
+    }
+    // A launch that works without an open note is the ordinary case.
+    if (type === 'launched') return false;
+    const conversationId = conversationFor(sid);
+    if (!conversationId) return false;
+    open({ sdkSessionId: sid, conversationId, type, lifecycle });
+    return true;
+  }
+
+  return {
+    handle,
+    openEpisode: (sdkSessionId) => episodes.get(String(sdkSessionId || '').trim()) || null,
+  };
+}

package/shared/claude-attribution.mjs

@@ -0,0 +1,117 @@
+// Commit and pull-request attribution for Claude sessions.
+//
+// Claude Code appends its own trailer to every commit an agent makes
+// ("Co-Authored-By: Claude … <noreply@anthropic.com>") and a line to every PR
+// body. The CLI lets a settings object replace both (`Settings.attribution`,
+// SDK 0.3.x), and OAR uses that so commits made through the relay carry one
+// identity whatever model wrote them:
+//
+//   Co-authored-by: Open Agent Relay (Claude Fable 5.1) <no-reply@oar.sh>
+//
+// Three modes: `oar` (the default), `vanilla` (the CLI's own attribution),
+// `off` (none). The relay resolves the mode (provider setting, later a
+// per-folder override) and the model label, and hands the finished settings
+// object to the worker with each delivery; the worker applies it at spawn and
+// when it changes. Shared by both sides so they build the same object.
+
+export const CLAUDE_ATTRIBUTION_MODES = Object.freeze(['oar', 'vanilla', 'off']);
+export const DEFAULT_CLAUDE_ATTRIBUTION_MODE = 'oar';
+
+export const OAR_ATTRIBUTION_NAME = 'Open Agent Relay';
+export const OAR_ATTRIBUTION_EMAIL = 'no-reply@oar.sh';
+export const OAR_PR_ATTRIBUTION = '🤖 Generated with [Open Agent Relay](https://oar.sh)';
+
+/** A mode string, or null for anything that is not one. */
+export function normalizeClaudeAttributionMode(value) {
+  const mode = String(value ?? '').trim().toLowerCase();
+  return CLAUDE_ATTRIBUTION_MODES.includes(mode) ? mode : null;
+}
+
+/** The provider mode unless a folder override says otherwise; never null. */
+export function resolveClaudeAttributionMode({ providerMode = null, folderMode = null } = {}) {
+  return normalizeClaudeAttributionMode(folderMode)
+    || normalizeClaudeAttributionMode(providerMode)
+    || DEFAULT_CLAUDE_ATTRIBUTION_MODE;
+}
+
+const FAMILY_LABELS = Object.freeze({
+  fable: 'Fable',
+  opus: 'Opus',
+  sonnet: 'Sonnet',
+  haiku: 'Haiku',
+  mythos: 'Mythos',
+});
+
+/**
+ * "claude-fable-5-1[1m]" → "Claude Fable 5.1"; "claude-haiku-4-5-20251001" →
+ * "Claude Haiku 4.5". The context-tier suffix and a date stamp are not part
+ * of the model's name. An id the pattern does not know is used as it is.
+ */
+export function claudeAttributionModelLabel(modelId) {
+  const raw = String(modelId || '').trim();
+  if (!raw) return 'Claude';
+  const id = raw.replace(/\[[^\]]*\]\s*$/, '').trim();
+  const parts = id.toLowerCase().split('-').filter(Boolean);
+  if (parts[0] !== 'claude' || parts.length < 2) return id || raw;
+  const family = FAMILY_LABELS[parts[1]];
+  if (!family) return id;
+  const version = parts.slice(2)
+    .filter((part) => /^\d+$/.test(part) && part.length < 8)
+    .join('.');
+  return version ? `Claude ${family} ${version}` : `Claude ${family}`;
+}
+
+export function claudeAttributionTrailer(modelLabel) {
+  const label = String(modelLabel || '').trim() || 'Claude';
+  return `Co-authored-by: ${OAR_ATTRIBUTION_NAME} (${label}) <${OAR_ATTRIBUTION_EMAIL}>`;
+}
+
+/**
+ * The `Settings.attribution` object for a mode and model: the OAR identity,
+ * nothing at all (`off`), or null for `vanilla` (the key is left to the CLI).
+ * Always the object form: older CLIs reject `true`/`false` here.
+ */
+export function buildClaudeAttributionSettings({ mode, modelId = '', modelLabel = '' } = {}) {
+  const resolved = normalizeClaudeAttributionMode(mode) || DEFAULT_CLAUDE_ATTRIBUTION_MODE;
+  if (resolved === 'vanilla') return null;
+  if (resolved === 'off') return { commit: '', pr: '', sessionUrl: false };
+  const label = String(modelLabel || '').trim() || claudeAttributionModelLabel(modelId);
+  return {
+    commit: claudeAttributionTrailer(label),
+    pr: OAR_PR_ATTRIBUTION,
+    // A relay session link in a public history: never.
+    sessionUrl: false,
+  };
+}
+
+function normalizeAttributionObject(value) {
+  if (value === null) return null;
+  if (!value || typeof value !== 'object') return undefined;
+  return {
+    commit: String(value.commit ?? ''),
+    pr: String(value.pr ?? ''),
+    sessionUrl: value.sessionUrl === true,
+  };
+}
+
+/**
+ * What a delivery's `settings` does to the worker's attribution — the twin
+ * of resolveDeliveredThinking: an absent key (an older relay) keeps the last
+ * known value; a present key replaces it, and null means vanilla.
+ */
+export function resolveDeliveredAttribution(current, settings) {
+  const base = normalizeAttributionObject(current);
+  const kept = base === undefined ? null : base;
+  if (!settings || typeof settings !== 'object') return kept;
+  if (!Object.prototype.hasOwnProperty.call(settings, 'attribution')) return kept;
+  const next = normalizeAttributionObject(settings.attribution);
+  return next === undefined ? kept : next;
+}
+
+/** Two attribution values mean the same thing (both vanilla, or equal fields). */
+export function sameClaudeAttribution(left, right) {
+  const a = normalizeAttributionObject(left) ?? null;
+  const b = normalizeAttributionObject(right) ?? null;
+  if (a === null || b === null) return a === b;
+  return a.commit === b.commit && a.pr === b.pr && a.sessionUrl === b.sessionUrl;
+}