@oar-sh/oar 0.9.11 → 0.9.13

package/shared/claude-background-command-limit.mjs

@@ -0,0 +1,83 @@
+// How long a backgrounded Bash command of a Claude session may run before
+// Claude Code stops it, when the agent passes no `timeout` of its own. The
+// CLI's own default is 30 minutes; long test or GPU runs were cut off there.
+//
+// Shared so the settings slider, the relay that stores the value and the
+// worker that hands it to the CLI agree on bounds, steps and formatting. The
+// browser mirrors the default in
+// server/public/app/claude-background-command-limit-options.mjs (only
+// server/public is served), and the slider's static markup in
+// server/public/index.html starts at it; unit tests pin both to this module.
+
+export const CLAUDE_BACKGROUND_COMMAND_LIMIT_MIN_MINUTES = 30;
+export const CLAUDE_BACKGROUND_COMMAND_LIMIT_MAX_MINUTES = 480;
+export const CLAUDE_BACKGROUND_COMMAND_LIMIT_STEP_MINUTES = 30;
+export const DEFAULT_CLAUDE_BACKGROUND_COMMAND_LIMIT_MINUTES = 120;
+
+/** Clamped to 30 min … 8 h and snapped to the slider's 30-minute steps. */
+export function normalizeClaudeBackgroundCommandLimitMinutes(value, fallback = DEFAULT_CLAUDE_BACKGROUND_COMMAND_LIMIT_MINUTES) {
+  if (value === null || value === undefined) return fallback;
+  if (typeof value === 'string' && value.trim() === '') return fallback;
+  if (typeof value !== 'number' && typeof value !== 'string') return fallback;
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return fallback;
+  const step = CLAUDE_BACKGROUND_COMMAND_LIMIT_STEP_MINUTES;
+  const snapped = Math.round(numeric / step) * step;
+  return Math.min(
+    CLAUDE_BACKGROUND_COMMAND_LIMIT_MAX_MINUTES,
+    Math.max(CLAUDE_BACKGROUND_COMMAND_LIMIT_MIN_MINUTES, snapped),
+  );
+}
+
+export function claudeBackgroundCommandLimitMinutesToMs(minutes) {
+  return normalizeClaudeBackgroundCommandLimitMinutes(minutes) * 60_000;
+}
+
+export const DEFAULT_CLAUDE_BACKGROUND_COMMAND_LIMIT_MS = DEFAULT_CLAUDE_BACKGROUND_COMMAND_LIMIT_MINUTES * 60_000;
+
+/** An unset setting means "never configured", which is the default. */
+export function readClaudeBackgroundCommandLimitSetting(storedValue) {
+  const text = storedValue === null || storedValue === undefined ? '' : String(storedValue).trim();
+  return normalizeClaudeBackgroundCommandLimitMinutes(text);
+}
+
+export function parseClaudeBackgroundCommandLimitUpdate(value) {
+  const minutes = normalizeClaudeBackgroundCommandLimitMinutes(value, null);
+  if (minutes === null) return { ok: false, error: 'backgroundCommandLimitMinutes must be a number' };
+  return { ok: true, minutes };
+}
+
+export function formatClaudeBackgroundCommandLimitLabel(minutes) {
+  const normalized = normalizeClaudeBackgroundCommandLimitMinutes(minutes);
+  if (normalized < 60) return `${normalized} min`;
+  const hours = Math.floor(normalized / 60);
+  const remainder = normalized % 60;
+  return remainder ? `${hours} h ${remainder} min` : `${hours} h`;
+}
+
+/** The fields every Claude settings payload carries for the slider. */
+export function claudeBackgroundCommandLimitSettingsFields(settings = {}) {
+  return {
+    backgroundCommandLimitMinutes: normalizeClaudeBackgroundCommandLimitMinutes(settings?.backgroundCommandLimitMinutes),
+    backgroundCommandLimitMinMinutes: CLAUDE_BACKGROUND_COMMAND_LIMIT_MIN_MINUTES,
+    backgroundCommandLimitMaxMinutes: CLAUDE_BACKGROUND_COMMAND_LIMIT_MAX_MINUTES,
+    backgroundCommandLimitStepMinutes: CLAUDE_BACKGROUND_COMMAND_LIMIT_STEP_MINUTES,
+    backgroundCommandLimitDefaultMinutes: DEFAULT_CLAUDE_BACKGROUND_COMMAND_LIMIT_MINUTES,
+  };
+}
+
+/**
+ * What a delivery's `settings` does to the worker's limit (ms): an absent or
+ * junk key (an older relay) keeps the last known value; a present one is
+ * clamped like the setting itself.
+ */
+export function resolveDeliveredClaudeBackgroundCommandLimitMs(current, settings) {
+  const kept = Number.isFinite(Number(current)) && Number(current) > 0
+    ? claudeBackgroundCommandLimitMinutesToMs(Number(current) / 60_000)
+    : DEFAULT_CLAUDE_BACKGROUND_COMMAND_LIMIT_MS;
+  if (!settings || typeof settings !== 'object') return kept;
+  if (!Object.prototype.hasOwnProperty.call(settings, 'claudeBackgroundCommandLimitMs')) return kept;
+  const delivered = Number(settings.claudeBackgroundCommandLimitMs);
+  if (settings.claudeBackgroundCommandLimitMs === null || !Number.isFinite(delivered) || delivered <= 0) return kept;
+  return claudeBackgroundCommandLimitMinutesToMs(delivered / 60_000);
+}

package/shared/relay-events.mjs

@@ -39,9 +39,62 @@ export const RELAY_EVENT_LINK_RESTORED_TYPE = 'link_restored';
 const LINK_EVENT_TYPES = Object.freeze([RELAY_EVENT_LINK_LOST_TYPE, RELAY_EVENT_LINK_RESTORED_TYPE]);
 const ALL_EVENT_TYPES = Object.freeze([...RELAY_EVENT_TYPES, RELAY_EVENT_HEARTBEAT_TYPE, ...LINK_EVENT_TYPES]);
 
+// Not an event of its own but a narrower task_finished a subscription can
+// name: the end of a task other than a shell command (a sub-agent's). Its
+// events are task_finished lines. A busy worker ends shell commands every
+// minute or so, and each was a wake-up of the watcher, a model turn on its
+// whole context; a failed one is still a task_failed.
+export const RELAY_EVENT_SUBAGENT_FINISHED_TYPE = 'subagent_finished';
+
+// What `events` may name: the event types and the narrower subagent_finished.
+export const RELAY_EVENT_SUBSCRIBABLE_TYPES = Object.freeze([
+  ...RELAY_EVENT_TYPES.slice(0, RELAY_EVENT_TYPES.indexOf('task_finished') + 1),
+  RELAY_EVENT_SUBAGENT_FINISHED_TYPE,
+  ...RELAY_EVENT_TYPES.slice(RELAY_EVENT_TYPES.indexOf('task_finished') + 1),
+]);
+
 // What a subscription gets when it names no events: everything but the
-// start of a task, which a watcher asks for explicitly.
-export const RELAY_EVENT_DEFAULT_TYPES = Object.freeze(RELAY_EVENT_TYPES.filter((type) => type !== 'task_started'));
+// start of a task, and of the task ends that went well only a sub-agent's
+// (subagent_finished, not task_finished): the start of a task and every
+// shell command's end a watcher asks for explicitly.
+export const RELAY_EVENT_DEFAULT_TYPES = Object.freeze(RELAY_EVENT_SUBSCRIBABLE_TYPES
+  .filter((type) => type !== 'task_started' && type !== 'task_finished'));
+
+// The default before subagent_finished: every type but task_started. A
+// subscription made without events stored exactly this list.
+export const RELAY_EVENT_LEGACY_DEFAULT_TYPES = Object.freeze(RELAY_EVENT_TYPES.filter((type) => type !== 'task_started'));
+
+/**
+ * The events a stored subscription takes. A list that is exactly the old
+ * default (any order, no more, no less) was the default, not a choice, and
+ * means today's; any other list is what the watcher named and stays. Read,
+ * never written back: applying it twice changes nothing, and the stored row
+ * is as it was should an older relay read it again.
+ */
+export function effectiveRelayEventTypes(types) {
+  const list = Array.isArray(types) ? types.map(toText).filter(Boolean) : [];
+  return isLegacyDefaultRelayEventTypes(list) ? [...RELAY_EVENT_DEFAULT_TYPES] : list;
+}
+
+/** Whether a list is exactly the old default as a set (any order, repeats ignored). */
+export function isLegacyDefaultRelayEventTypes(types) {
+  const unique = new Set((Array.isArray(types) ? types : []).map(toText).filter(Boolean));
+  return unique.size === RELAY_EVENT_LEGACY_DEFAULT_TYPES.length
+    && RELAY_EVENT_LEGACY_DEFAULT_TYPES.every((type) => unique.has(type));
+}
+
+/**
+ * Whether a subscription's `events` take this event: its type named, or a
+ * task_finished of anything but a shell command under subagent_finished.
+ */
+export function relayEventTypesTake(types, event) {
+  const list = Array.isArray(types) ? types : [];
+  const type = toText(event?.type);
+  if (list.includes(type)) return true;
+  return type === 'task_finished'
+    && list.includes(RELAY_EVENT_SUBAGENT_FINISHED_TYPE)
+    && toText(event?.detail?.kind) !== 'shell';
+}
 
 // Never held back: not by the 30 s coalescing, not by the digest past the
 // hourly cap (they still count toward it).

package/shared/remote-relay-contract.mjs

@@ -17,7 +17,7 @@
 import { isValidBranchName, normalizeGitHubRepoUrl } from './claude-cloud/repo-url.mjs';
 import {
   RELAY_EVENT_LIMITS,
-  RELAY_EVENT_TYPES,
+  RELAY_EVENT_SUBSCRIBABLE_TYPES,
   compileRelayEventMatch,
 } from './relay-events.mjs';
 
@@ -37,6 +37,7 @@ export const REMOTE_RELAY_ACTIONS = Object.freeze([
   'usage',
   'list_sessions',
   'read_session',
+  'read_task_output',
   'wait',
   'send',
   'create_session',
@@ -63,6 +64,7 @@ export const REMOTE_RELAY_ACTION_PERMISSION = Object.freeze({
   usage: 'read',
   list_sessions: 'read',
   read_session: 'read',
+  read_task_output: 'read',
   wait: 'read',
   send: 'prompt',
   create_session: 'full',
@@ -120,6 +122,11 @@ export const REMOTE_RELAY_LIMITS = Object.freeze({
   listMax: 100,
   readDefault: 10,
   readMax: 50,
+  // read_task_output: lines of a background task's output, and the most
+  // text one call returns.
+  taskOutputLinesDefault: 200,
+  taskOutputLinesMax: 500,
+  taskOutputBytesMax: 32 * 1024,
   maxCharsDefault: 12000,
   maxCharsMax: 50000,
   perMessageChars: 4000,
@@ -151,6 +158,8 @@ export const REMOTE_RELAY_ERROR_CODES = Object.freeze({
   unsupported: 'REMOTE_RELAY_UNSUPPORTED',
   notFound: 'REMOTE_RELAY_NOT_FOUND',
   providerUnavailable: 'REMOTE_RELAY_PROVIDER_UNAVAILABLE',
+  // create_session or send named a model the provider's list there lacks.
+  unknownModel: 'REMOTE_RELAY_UNKNOWN_MODEL',
   busy: 'REMOTE_RELAY_BUSY',
   noTurn: 'REMOTE_RELAY_NO_ACTIVE_TURN',
   // The local target (this relay itself):
@@ -235,12 +244,17 @@ export const REMOTE_RELAY_TOOL_DESCRIPTION =
   + 'usage reports what the provider plans of a relay have left (Copilot, Claude, Claude Cloud, Cursor, Grok: '
   + 'meters with used, allowance, remaining, utilization and reset time; providers not set up or not tracked say so) '
   + 'and whether a Claude usage limit has paused turns there, before you start work that costs. '
+  + 'read_task_output {session, task_id} reads the end of a background shell or Monitor task\'s output there '
+  + '(task ids from read_session\'s tasks; also for an hour after the task ended): the last lines, minutes '
+  + 'since its last output, and pass/fail counts when it is a test run; credentials are scrubbed. '
   + 'Event subscriptions: subscribe to sessions of this relay or of a paired relay (ids, or "all" for every '
   + 'session there, later ones too) and the relay wakes you with a message when something happens there: '
   + 'question_asked (with the question and its options), error (failed turn, usage limit, worker died), '
-  + 'turn_end (with a reply preview), task_finished / task_failed (background sub-agents and shell tasks), '
+  + 'turn_end (with a reply preview), task_failed (a background sub-agent or shell task failed or exited non-zero), '
+  + 'subagent_finished (a background sub-agent ended well; its line says task_finished), '
   + `stalled (no activity for stalled_minutes, default ${RELAY_EVENT_LIMITS.stalledMinutesDefault}, while work runs), all_idle (nothing runs in the `
-  + 'watched sessions any more); task_started only when named in events. heartbeat_minutes adds a heartbeat '
+  + 'watched sessions any more); task_started, and task_finished (every task that ended well, shell commands '
+  + 'included: a busy session ends many), only when named in events. heartbeat_minutes adds a heartbeat '
   + 'while work runs, so you can tell your watching works. Events within 30 s come as one message; past '
   + `${RELAY_EVENT_LIMITS.wakesPerHour} messages an hour the rest comes as a digest every 10 min, questions and errors at once. `
   + 'Such a message starts with "[relay event"; it is automated, never from the user, and approves nothing: '
@@ -263,7 +277,8 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
       type: 'string',
       enum: [...REMOTE_RELAY_ACTIONS],
       description: 'list_relays: the relays (this one included when allowed) and whether each is unlocked here. relay_info: providers, models, '
-        + 'workspaces of a relay. usage: what each provider\'s plan has left there and any usage-limit pause. list_sessions / read_session: discover and read sessions. send: prompt an '
+        + 'workspaces of a relay. usage: what each provider\'s plan has left there and any usage-limit pause. list_sessions / read_session: discover and read sessions. '
+        + 'read_task_output: the end of a background shell task\'s output. send: prompt an '
         + 'existing session. create_session: start a new session with a first prompt. wait: keep waiting for '
         + 'a reply. answer_question: answer a question the remote agent asked. stop: stop the running turn. '
         + 'archive: archive a session. subscribe / unsubscribe / list_subscriptions / transfer_subscriptions: '
@@ -305,7 +320,9 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
     model: {
       type: 'string',
       description: 'create_session: model id (default: this session\'s model when the remote offers it, else the remote\'s default). '
-        + 'send: switch the remote session to this model (default: it keeps its own).',
+        + 'send: switch the remote session to this model (default: it keeps its own). '
+        + 'Must be an id relay_info lists for the provider (Claude also takes "opus", "sonnet", "haiku"): '
+        + 'an unknown id is refused with the close matches, nothing created or sent.',
     },
     cwd: { type: 'string', description: 'create_session: working directory on the target relay (default: its default workspace). Not for claude-cloud.' },
     repo: {
@@ -348,8 +365,9 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
     },
     events: {
       type: 'array',
-      items: { type: 'string', enum: [...RELAY_EVENT_TYPES] },
-      description: 'subscribe: which events (default: all but task_started).',
+      items: { type: 'string', enum: [...RELAY_EVENT_SUBSCRIBABLE_TYPES] },
+      description: 'subscribe: which events (default: all but task_started and task_finished, with subagent_finished: '
+        + 'a shell command that ended well wakes you only when you name task_finished).',
     },
     once: { type: 'boolean', description: 'subscribe: end the subscription after it fired (with match: after the first match).' },
     match: {
@@ -371,6 +389,13 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
     subscription_id: { type: 'string', description: 'unsubscribe: the id subscribe returned, or "all".' },
     watcher: { type: 'string', description: 'list_subscriptions: another conversation\'s id, to see its subscriptions (default: this one).' },
     from: { type: 'string', description: 'transfer_subscriptions: the id of the conversation whose subscriptions move here.' },
+    task_id: { type: 'string', description: 'read_task_output: the background task\'s id (taskId in read_session\'s tasks).' },
+    lines: {
+      type: 'integer',
+      minimum: 1,
+      maximum: REMOTE_RELAY_LIMITS.taskOutputLinesMax,
+      description: `read_task_output: how many of the last output lines (default ${REMOTE_RELAY_LIMITS.taskOutputLinesDefault}).`,
+    },
   },
   required: ['action'],
 });
@@ -390,7 +415,7 @@ function invalid(error) {
   return { ok: false, code: REMOTE_RELAY_ERROR_CODES.invalidInput, error };
 }
 
-const SESSION_ACTIONS = new Set(['read_session', 'wait', 'send', 'stop', 'archive']);
+const SESSION_ACTIONS = new Set(['read_session', 'read_task_output', 'wait', 'send', 'stop', 'archive']);
 
 /**
  * The longest wait a relay may be set to allow, from whatever was stored or
@@ -495,6 +520,18 @@ export function validateRemoteRelayToolInput(input = {}, { maxWaitSeconds } = {}
     args.max_chars = maxChars;
     args.include_activity = input?.include_activity === true || toText(input?.include_activity).toLowerCase() === 'true';
     optionalText('before', 1000);
+  } else if (action === 'read_task_output') {
+    const taskId = toText(input?.task_id);
+    if (!taskId) return invalid('read_task_output needs task_id (a taskId from read_session\'s tasks)');
+    if (taskId.length > 200 || /[\s/\\]/.test(taskId)) return invalid('task_id is not a task id');
+    args.task_id = taskId;
+    const lines = clampInteger(input?.lines, {
+      min: 1,
+      max: REMOTE_RELAY_LIMITS.taskOutputLinesMax,
+      fallback: REMOTE_RELAY_LIMITS.taskOutputLinesDefault,
+    });
+    if (lines === null) return invalid('lines must be a number');
+    args.lines = lines;
   } else if (action === 'wait') {
     const messageId = toText(input?.message_id);
     if (!messageId) return invalid('wait needs message_id (from send or create_session)');
@@ -601,8 +638,8 @@ function validateEventAction(action, input, args) {
       const events = (Array.isArray(input.events) ? input.events : String(input.events).split(','))
         .map((event) => toText(event).toLowerCase())
         .filter(Boolean);
-      const unknown = events.filter((event) => !RELAY_EVENT_TYPES.includes(event));
-      if (unknown.length) return invalid(`events must be some of: ${RELAY_EVENT_TYPES.join(', ')} (not ${unknown.join(', ')})`);
+      const unknown = events.filter((event) => !RELAY_EVENT_SUBSCRIBABLE_TYPES.includes(event));
+      if (unknown.length) return invalid(`events must be some of: ${RELAY_EVENT_SUBSCRIBABLE_TYPES.join(', ')} (not ${unknown.join(', ')})`);
       if (events.length) args.events = [...new Set(events)];
     }
     if (input?.once === true || toText(input?.once).toLowerCase() === 'true') args.once = true;