@oar-sh/oar 0.9.17 → 0.9.19

package/server/relay-self-restart.mjs

@@ -1,6 +1,7 @@
 import { spawn } from 'child_process';
 import path from 'path';
 import { RELAY_RESTART_EXIT_CODE, RELAY_STOP_EXIT_CODE } from './relay-exit-codes.mjs';
+import { relayRuntimeNodeFlags, relayRuntimeNodeFlagsOrNone } from './relay-heap-guard.mjs';
 
 // Role selection travels on argv, never in the environment. The runtime's env is
 // inherited by tmux worker sessions and by the Copilot CLI it launches, and the
@@ -34,8 +35,11 @@ export function spawnRelayRuntime({
   detached = false,
   windowsHide = true,
   logger = console,
+  // The heap limit and heap snapshot flags (relay-heap-guard.mjs).
+  nodeFlags = relayRuntimeNodeFlags,
 } = {}) {
-  const child = spawnImpl(process.execPath, [...execArgv, scriptPath, RELAY_RUNTIME_FLAG, ...args], {
+  const { flags } = relayRuntimeNodeFlagsOrNone(nodeFlags, { env, execArgv, serverDir: path.dirname(String(scriptPath || '')), logger });
+  const child = spawnImpl(process.execPath, [...flags, ...execArgv, scriptPath, RELAY_RUNTIME_FLAG, ...args], {
     cwd,
     env,
     detached,
@@ -84,8 +88,14 @@ export async function runDirectRelaySupervisor({
   exitImpl = (code) => process.exit(code),
   logger = console,
   installSignalHandlers = true,
+  signals = process,
+  nodeFlags = relayRuntimeNodeFlags,
   restartDelayMs = 500,
   maxCrashRestarts = 3,
+  // A runtime that ran this long before it crashed starts the count afresh:
+  // crashes days apart are not a crash loop.
+  crashCountResetMs = 10 * 60 * 1000,
+  now = Date.now,
 } = {}) {
   let runtimeProc = null;
   let shuttingDown = false;
@@ -102,13 +112,20 @@ export async function runDirectRelaySupervisor({
   const handleSigTerm = () => requestShutdown('SIGTERM', 0);
 
   if (installSignalHandlers) {
-    process.on('SIGINT', handleSigInt);
-    process.on('SIGTERM', handleSigTerm);
+    signals.on('SIGINT', handleSigInt);
+    signals.on('SIGTERM', handleSigTerm);
   }
 
   try {
     let crashCount = 0;
     while (true) {
+      // A Ctrl-C reaches the runtime (same process group) before this
+      // supervisor's handler can run: the runtime's signal exit looks like a
+      // crash, and the shutdown arrives during the delay. Never relaunch then.
+      if (shuttingDown) {
+        return await exitImpl(shutdownExitCode);
+      }
+      const startedAt = now();
       runtimeProc = spawnRelayRuntime({
         env,
         cwd,
@@ -119,6 +136,7 @@ export async function runDirectRelaySupervisor({
         stdio,
         detached: false,
         logger,
+        nodeFlags,
       });
       if (runtimeProc.stdout?.on) {
         runtimeProc.stdout.on('data', (chunk) => process.stdout.write(chunk));
@@ -139,7 +157,13 @@ export async function runDirectRelaySupervisor({
         return await exitImpl(1);
       }
 
-      const exitCode = Number.isInteger(Number(result.code)) ? Number(result.code) : null;
+      // A runtime killed by a signal (an out-of-memory abort is SIGABRT, the
+      // kernel's OOM killer SIGKILL) exits with code null: a crash. Number(null)
+      // is 0, which once ended the supervisor as if the runtime stopped cleanly.
+      const exitCode = result.code !== null && result.code !== undefined && Number.isInteger(Number(result.code))
+        ? Number(result.code)
+        : null;
+      const signal = exitCode === null ? (result.signal || null) : null;
       if (exitCode === RELAY_RESTART_EXIT_CODE) {
         logger?.log?.(`[relay] runtime requested restart; relaunching ${path.basename(String(scriptPath || ''))}...`);
         crashCount = 0;
@@ -156,8 +180,10 @@ export async function runDirectRelaySupervisor({
         return await exitImpl(RELAY_STOP_EXIT_CODE);
       }
 
+      if (now() - startedAt >= crashCountResetMs) crashCount = 0;
       const attempt = crashCount + 1;
-      logger?.error?.(`[relay] runtime crashed with exit code ${exitCode ?? 'null'} (crash ${attempt}/${maxCrashRestarts}).`);
+      const how = signal ? `signal ${signal}` : `exit code ${exitCode ?? 'null'}`;
+      logger?.error?.(`[relay] runtime crashed with ${how} (crash ${attempt}/${maxCrashRestarts}).`);
       if (attempt >= maxCrashRestarts) {
         logger?.error?.('[relay] crash limit reached; supervisor stopping.');
         return await exitImpl(1);
@@ -168,8 +194,8 @@ export async function runDirectRelaySupervisor({
 
   } finally {
     if (installSignalHandlers) {
-      process.off('SIGINT', handleSigInt);
-      process.off('SIGTERM', handleSigTerm);
+      signals.off('SIGINT', handleSigInt);
+      signals.off('SIGTERM', handleSigTerm);
     }
   }
 }

package/server/relay-tools.md

@@ -23,7 +23,7 @@ Use `restart: true` in the request body when the user wants a real relay restart
 
 Never pass `immediate` in that request body: it restarts without waiting for the running turns, which only the user may decide, with Restart now in the web UI.
 
-To go on with your work once the relay is back, subscribe first with `remote_relay` `{"action":"subscribe","events":["relay_restarted"],"once":true}` (no sessions needed), then request the restart. Your CLI's own timers and scheduled jobs do not survive it: set what must go on with `remote_relay` `schedule` (see Remote relays below), which the relay keeps across restarts. A restart requested while a turn that `relay_restarted` woke is still running does not wake that conversation (a `once` subscription ends with it).
+To go on with your work once the relay is back, subscribe first with `relay_tool` `{"action":"subscribe","events":["relay_restarted"],"once":true}` (no sessions needed), then request the restart. Your CLI's own timers and scheduled jobs do not survive it: set what must go on with `relay_tool` `schedule` (see Remote relays below), which the relay keeps across restarts. A restart requested while a turn that `relay_restarted` woke is still running does not wake that conversation (a `once` subscription ends with it).
 
 ## Preview servers
 
@@ -33,18 +33,18 @@ If you have a `preview` tool, use it. Otherwise use the authenticated localhost
 
 ## Remote relays
 
-If you have a `remote_relay` tool, it works with sessions on OAR relays: the other relays this relay is paired with and, when its owner allows it, this relay itself. It lists and reads sessions, prompts a session, starts a new one and waits for its reply. Start with `{"action":"list_relays"}`.
+If you have a `relay_tool` tool, it works with sessions on OAR relays: the other relays this relay is paired with and, when its owner allows it, this relay itself. It lists and reads sessions, prompts a session, starts a new one and waits for its reply. Start with `{"action":"list_relays"}`.
 
 A paired relay stays locked until the user mentions it in this conversation (`@name` or its plain name) or an agent on that relay writes to this conversation; a locked relay refuses everything except `list_relays`, so ask the user to mention it rather than retrying. Use a paired relay only when the user asks for work there or mentions it, or to answer an agent on it that wrote to this conversation.
 
 This relay itself is listed with "self": true when its owner switched agent sessions on, and is addressed by its name or as "this"; it needs no mention. Use it to hand parts of your task to other sessions:
 
-- `create_session` starts a session with any provider that `relay_info` lists: a local one in a folder ("cwd"), or provider "claude-cloud" with "repo" (a GitHub URL or owner/repo) and an optional "branch". At most 4 sessions you started may work at the same time; a fifth is refused until one finishes.
+- `create_session` starts a session with any provider that `relay_info` lists: a local one in a folder ("cwd"), or provider "claude-cloud" with "repo" (a GitHub URL or owner/repo) and an optional "branch". The provider ids are the target relay's, as `relay_info` shows them; an id it does not know is refused with the list it has. A session started before a relay update can use providers the update added, without a restart. At most 4 sessions you started may work at the same time; a fifth is refused until one finishes.
 - The first `create_session` on this relay shows the user an approval card, once per conversation. A session that an agent created cannot create sessions itself (one level only), unless the owner allowed it for that session: `list_sessions` and `read_session` then show "mayCreateSessions": true. Only the owner sets that.
 - Sessions you start here are grouped under this session in the user's sidebar. `list_sessions` lists in the sidebar's order (a group sorts by its newest session, head first) and shows the group as a "group" field (id, name, role); `read_session` adds the group's live members with their state. `create_session` takes "group" (a group id, or its name in any case, from `relay_info`'s "groups") to put the new session into an existing group instead, here or on a paired relay; an unknown group is refused with the groups listed and nothing is created, and the result carries the "group". Renaming and dissolving groups is the user's.
 - `update_session` ("session" plus any of "model", "effort", "mode", "auto_compact_window", "title", "group", "thinking_enabled", "thinking_display", "cwd") changes another session's settings for its next turns without prompting it, here or on a paired relay, and answers the settings and "changed"; a group name that does not exist makes one, "none" takes the session out (a group the user made stays, even empty; one update_session made goes once empty), a new "cwd" restarts its CLI there (refused while it works), "auto_compact_window" 0 is the model default. The model is checked as for `send`. A failed call still lists in "changed" what it wrote before the failing step. A mode set this way lasts until the next `send` that names another mode or comes from a caller in another mode: a `send` without "mode" passes the caller's own mode.
 - Only a session your conversation started may be updated freely; any other (the user's, another agent's, the one that started you) needs the user's approval card once per conversation and relay (refused: `REMOTE_RELAY_PERMISSION`); never your own conversation.
-- A "model" for `create_session` or `send` 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 and the valid ids (`Unknown model 'gpt-5-4' for Copilot on relay "…"; did you mean 'gpt-5.4'? Valid ids: … Nothing was sent.`), and nothing is created or sent: pick from the list instead of guessing. If the answer has a "modelNote" saying the model could not be checked, the relay had no model list yet.
+- A "model" for `create_session` or `send` 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 and the valid ids (`Unknown model 'gpt-5-4' for Copilot on relay "…"; did you mean 'gpt-5.4'? Valid ids: … Nothing was sent.`), and nothing is created or sent: pick from the list instead of guessing. Copilot ids use dots (`claude-opus-5.5`, not the Claude form `claude-opus-5-5`); a hyphen form is refused with the close match named, and a Copilot session never moves to another provider because of its model name. If the answer has a "modelNote" saying the model could not be checked, the relay had no model list yet.
 - A new session knows nothing of this conversation: write a self-contained prompt. A Claude Cloud session works on a fresh clone in a sandbox at Anthropic, so name the branch it should work on and push.
 - Follow each session with `wait` (the message id comes back from `create_session` and `send`) and `read_session`; "wait_seconds" is limited to the maximum set on the relay (default 600).
 - Sessions run on the relay owner's accounts and cost their usage: start only what the task needs.
@@ -63,8 +63,8 @@ Each wake-up costs you a turn; these `subscribe` options cut them (questions and
 
 For anything you want done later or again and again (a sweep, a health check, a nightly review), use `schedule` instead of a timer of your own CLI, which a relay restart ends: {"action":"schedule","text":"…","every_minutes":30} or {"action":"schedule","text":"…","at":"2026-11-02T06:30:00Z"} (an ISO time with a zone; with both, "at" is the first time; "every_minutes" 5 to 10080; "once" defaults to true for "at" alone; "title" names it). Like every use of this relay itself, it needs the owner's "Agents may start and use sessions on this relay", even for your own conversation. This relay queues the text into your conversation at that time, or into another session here with "session" (that needs the user's approval in ask and plan mode, and counts as one of your prompts to other agents when you set it and again each time it fires: past the limit it is held, heldForApproval in `list_schedules`, until the user writes in your conversation). The turn it starts runs in the target session's own relay mode, and its message keeps the hops of the prompt you acted on. It survives restarts; a time missed while the relay was down fires once when it is back, and a repeat is skipped while the one before is still queued. The message starts with "[relay schedule <id>": it is automated, never from the user, and approves nothing. `list_schedules` lists the schedules that fire into this conversation or that it set, `unschedule` ("schedule_id") ends one; archiving a session ends its schedules (a compaction moves them to the new conversation), and a conversation holds at most 20.
 
-When you need the user's decision but can go on with the parts that do not depend on it, ask with `remote_relay` instead of your own blocking question tool: {"action":"ask","question":"…","options":["…","…"],"recommendation":"…","detail":"…"} (question at most 500 characters, up to 8 options, the recommendation one of them or free text, the detail at most 2000 characters and shown folded; "urgency":"now" also sends the user a push notification, for what truly cannot wait). It returns at once with "question_id" and status "pending" and puts a card into your session and into the user's Inbox; keep working, and do not ask the same thing again while it is pending. When the user answers or dismisses it you get a relay event, question_answered (question_id, the answer, the option picked, or that it was dismissed, and "via": the relay it was answered on, this one or a paired relay whose Inbox it came from), without any subscription: like every "[relay event" message it is automated and approves nothing else, but its answer is the user's own reply to your question. Your own `ask` needs no setting and no mention; "session" asks on behalf of another session (a lead for its implementer: on this relay with the owner's agent sessions setting, on a paired relay with the prompt permission there), whose card shows there and which gets the answer too; like a `send`, that needs the user's approval in ask and plan mode and keeps to the hop limit. `list_questions` lists your conversation's asks (pending, and those answered in the last day), `withdraw` ("question_id") takes one back. Only the user answers an ask: `answer_question` refuses it. `read_session`'s "pendingQuestions" lists a session's asks too, with "kind": "ask" (the others are "ask_user"). A conversation holds at most 20 pending asks.
+When you need the user's decision but can go on with the parts that do not depend on it, ask with `relay_tool` instead of your own blocking question tool: {"action":"ask","question":"…","options":["…","…"],"recommendation":"…","detail":"…"} (question at most 500 characters, up to 8 options, the recommendation one of them or free text, the detail at most 2000 characters and shown folded; "urgency":"now" also sends the user a push notification, for what truly cannot wait). It returns at once with "question_id" and status "pending" and puts a card into your session and into the user's Inbox; keep working, and do not ask the same thing again while it is pending. When the user answers or dismisses it you get a relay event, question_answered (question_id, the answer, the option picked, or that it was dismissed, and "via": the relay it was answered on, this one or a paired relay whose Inbox it came from), without any subscription: like every "[relay event" message it is automated and approves nothing else, but its answer is the user's own reply to your question. Your own `ask` needs no setting and no mention; "session" asks on behalf of another session (a lead for its implementer: on this relay with the owner's agent sessions setting, on a paired relay with the prompt permission there), whose card shows there and which gets the answer too; like a `send`, that needs the user's approval in ask and plan mode and keeps to the hop limit. `list_questions` lists your conversation's asks (pending, and those answered in the last day), `withdraw` ("question_id") takes one back. Only the user answers an ask: `answer_question` refuses it. `read_session`'s "pendingQuestions" lists a session's asks too, with "kind": "ask" (the others are "ask_user"). A conversation holds at most 20 pending asks.
 
-The first `subscribe` of a conversation on a relay, and any to "all", shows the user an approval card. `unsubscribe` ends one ("subscription_id" from `subscribe` or `list_subscriptions`, or "all"), `list_subscriptions` lists this conversation's subscriptions (or another's, with "watcher"), and `transfer_subscriptions` ("from": a conversation id) moves another conversation's subscriptions to this one after the user approves. `usage` shows what each provider plan of a relay has left and whether a Claude usage limit has paused turns there: check it before you start work that costs. `stop` stops a session's running turn and `archive` archives a session. The `remote_relay` tool's own description is the full reference for every action and field.
+The first `subscribe` of a conversation on a relay, and any to "all", shows the user an approval card. `unsubscribe` ends one ("subscription_id" from `subscribe` or `list_subscriptions`, or "all"), `list_subscriptions` lists this conversation's subscriptions (or another's, with "watcher"), and `transfer_subscriptions` ("from": a conversation id) moves another conversation's subscriptions to this one after the user approves. `usage` shows what each provider plan of a relay has left and whether a Claude usage limit has paused turns there: check it before you start work that costs. `stop` stops a session's running turn and `archive` archives a session. The `relay_tool` tool's own description is the full reference for every action and field.
 
 Write actions may first wait for the user's approval. If a result lists `pendingQuestions`, the other agent is waiting for an answer: ask the user (unless they told you to decide), then pass it on with `answer_question`. Always tell the user which relay and session you worked on.

package/server/repositories/conversation-group-repository.mjs

@@ -7,7 +7,7 @@ import { compareGroupMembers } from '../public/app/conversation-group-order.mjs'
 // Session groups (migration 0014): the set of conversations that share a
 // `group_id`, with a row in `conversation_groups` for what the set itself
 // needs: a name given by hand, and the head (the session that created the
-// others with the remote_relay tool; NULL for a group made by hand or once
+// others with the relay_tool; NULL for a group made by hand or once
 // the head is deleted).
 //
 // A session an agent creates on this relay joins its creator's group at

package/server/repositories/message-repository.mjs

@@ -15,6 +15,8 @@ export function createMessageRepository(db) {
     // worker, so it neither keeps one warm nor counts as queued.
     const queueHasUsageLimitPause = db.prepare(`PRAGMA table_info(queue)`).all()
         .some((column) => column.name === 'usage_limit_pause');
+    const queueHasProvider = db.prepare(`PRAGMA table_info(queue)`).all()
+        .some((column) => column.name === 'provider');
     const notHeldForUsageLimit = (alias = '') => (queueHasUsageLimitPause
         ? `AND NOT (${alias}usage_limit_pause IS NOT NULL AND ${alias}status = 'pending' AND ${alias}next_attempt_at IS NOT NULL AND ${alias}next_attempt_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`
         : '');
@@ -351,6 +353,11 @@ export function createMessageRepository(db) {
           WHERE id = ?
         `),
         setQueueRuntimeSession: db.prepare(`UPDATE queue SET runtime_session_id = ? WHERE id = ?`),
+        // The billing a row runs on (migration 0031): a continuation is the
+        // kind of the worker whose CLI started it, whatever the chat's now.
+        setQueueProvider: queueHasProvider
+          ? db.prepare(`UPDATE queue SET provider = ? WHERE id = ?`)
+          : null,
         setQueueResponseMessageId: db.prepare(`UPDATE queue SET response_message_id = ? WHERE id = ?`),
         // Legacy (unfenced) finalization keeps 'pending' in the set so a
         // response landing after a stale-sweep requeue still finalizes; fenced

package/server/repositories/session-repository.mjs

@@ -11,6 +11,12 @@ export function createSessionRepository(db) {
       : 'rs.model AS runtime_model, NULL AS runtime_provider_type, NULL AS runtime_provider_model';
     // Provenance of conversations another relay's agent created (migration
     // 0005); NULL on a schema that predates it.
+    // The billing a queue row runs on (migration 0031): the Claude API key
+    // removal counts the unfinished rows stamped with the key.
+    const queueHasProvider = db.prepare(`PRAGMA table_info(queue)`).all().some((column) => column.name === 'provider');
+    const claudeApiQueueCountSelect = queueHasProvider
+      ? `(SELECT COUNT(*) FROM queue q WHERE q.conversation_id = c.id AND q.status IN ('pending', 'processing', 'parked') AND LOWER(COALESCE(q.provider, '')) = 'claude-api') AS claude_api_queue_count`
+      : '0 AS claude_api_queue_count';
     const conversationsHaveOrigin = db.prepare(`PRAGMA table_info(conversations)`).all()
       .some((column) => String(column?.name || '').trim() === 'origin_json');
     const conversationOriginSelect = conversationsHaveOrigin ? 'c.origin_json' : 'NULL AS origin_json';
@@ -100,7 +106,8 @@ export function createSessionRepository(db) {
             rs.*,
             c.sdk_session_id AS conversation_sdk_session_id,
             (SELECT COUNT(*) FROM messages m WHERE m.conversation_id = c.id) AS message_count,
-            (SELECT COUNT(*) FROM queue q WHERE q.conversation_id = c.id AND q.status IN ('pending', 'processing', 'parked')) AS active_queue_count
+            (SELECT COUNT(*) FROM queue q WHERE q.conversation_id = c.id AND q.status IN ('pending', 'processing', 'parked')) AS active_queue_count,
+            ${claudeApiQueueCountSelect}
           FROM runtime_sessions rs
           JOIN conversations c ON c.id = rs.conversation_id
           WHERE c.status != 'deleted'

package/server/routes/ask-user-routes.mjs

@@ -192,7 +192,7 @@ export function registerAskUserRoutes(app, deps) {
   });
 
   /**
-   * An ask (remote_relay `ask`) is the user's to answer: from this relay's
+   * An ask (relay_tool `ask`) is the user's to answer: from this relay's
    * own UI here, from a paired relay's Inbox through its own route
    * (relay-ask-routes.mjs). Never from an agent, this relay's or another's.
    */

package/server/routes/conversation-group-routes.mjs

@@ -7,7 +7,7 @@
 // (messages-routes.mjs), next to the code they reuse.
 //
 // The owner's action only: every route is behind `auth`, and a request that
-// arrived from a paired relay is refused, as the remote_relay tool's own
+// arrived from a paired relay is refused, as the relay_tool's own
 // route refuses calls from other relays. The tool reads groups, names an
 // existing one for a session it creates (the bootstrap route), and moves one
 // session into a group, out of it, or into a new group of a name it gives