@oar-sh/oar 0.9.16 → 0.9.18

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,7 +33,7 @@ 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.
 
@@ -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
@@ -18,7 +18,9 @@ import { compareGroupMembers } from '../public/app/conversation-group-order.mjs'
 //
 // A group can have a hand order (migration 0015): once the owner drags a row
 // into place, every member after the head gets a `group_position` (10, 20,
-// 30, ...) and keeps it; later arrivals join at the end. A group nobody
+// 30, ...) and keeps it; a later arrival (a session created in the group, a
+// row the menu moves in) goes first, right under the head, and the next
+// drag renumbers from 10 again. A group nobody
 // reordered keeps NULL positions and the activity order. Without the column
 // the hand order is off and moves only change the membership.
 //
@@ -141,8 +143,8 @@ export function createConversationGroupRepository(db) {
     WHERE group_id = ? AND status != 'deleted'
     ORDER BY updated_at DESC
   `);
-  const maxPosition = hasPosition
-    ? db.prepare(`SELECT MAX(group_position) AS n FROM conversations WHERE group_id = ? AND status != 'deleted'`)
+  const minPosition = hasPosition
+    ? db.prepare(`SELECT MIN(group_position) AS n FROM conversations WHERE group_id = ? AND status != 'deleted'`)
     : null;
   const countMembers = db.prepare(`SELECT COUNT(*) AS n FROM conversations WHERE group_id = ? AND status != 'deleted'`);
   // Groups with a live member, the one with the latest activity first, then
@@ -188,11 +190,16 @@ export function createConversationGroupRepository(db) {
 
   const positionValue = (row) => (row?.group_position == null ? null : Number(row.group_position));
 
-  /** Where a row joining `groupId` goes: after the last placed member, or NULL when nobody ordered the group. */
+  /**
+   * Where a row joining `groupId` goes: before the first placed member (the
+   * owner sees a new session at the top of its group, under the head), or
+   * NULL when nobody ordered the group, where newest-first puts it on top
+   * anyway. Positions may go to zero and below; the next drag renumbers.
+   */
   function joiningPosition(groupId) {
     if (!hasPosition) return null;
-    const max = maxPosition.get(toText(groupId))?.n;
-    return max == null ? null : Number(max) + POSITION_STEP;
+    const min = minPosition.get(toText(groupId))?.n;
+    return min == null ? null : Number(min) - POSITION_STEP;
   }
 
   const liveConversation = (id) => {

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
@@ -129,7 +129,8 @@ export function registerConversationGroupRoutes(app, deps) {
   // a conversation into a group. `groupId: null` takes it out (as DELETE).
   // With `beforeConversationId` in the body (null: to the end) it is a drag:
   // the row lands before that one and the group gets a hand order; without
-  // it the row joins at the end of a hand-ordered group, as the menu does.
+  // it the row joins a hand-ordered group first, under the head, as the menu
+  // does (and the next drag renumbers).
   app.put('/api/conversation/:id/group', auth, (req, res) => {
     if (refuseRemote(req, res)) return;
     if (!conversationGroups?.enabled) return unavailable(res);

package/server/routes/deepseek-usage-import-routes.mjs

@@ -0,0 +1,72 @@
+'use strict';
+
+// POST /api/deepseek-usage-import: the two CSV files of DeepSeek's usage
+// export, as text, from Settings → Providers → DeepSeek. The relay's user
+// only: another relay's agent gets a 403. The import itself is in
+// services/deepseek-usage-import.mjs.
+
+import { readRemoteRelayRequest } from '../services/remote-relay-inbound.mjs';
+
+// The two files of a month come to well under a megabyte.
+export const DEEPSEEK_USAGE_IMPORT_MAX_BYTES = 2 * 1024 * 1024;
+
+// How long the import waits for the usage card's currency (the balance's).
+export const DEEPSEEK_USAGE_IMPORT_CURRENCY_WAIT_MS = 5000;
+
+/**
+ * @param {object} deps
+ * @param {Function} [deps.getCardCurrency] the usage card's currency ('USD',
+ *   'CNY'), from the balance; may be async. The summary then says whether
+ *   the card can use the export's rows.
+ * @param {Function} [deps.logError] where a failed import is logged
+ */
+export function registerDeepSeekUsageImportRoutes(app, deps) {
+  const {
+    auth,
+    deepseekUsageImportService,
+    remoteRelayInbound,
+    getCardCurrency = null,
+    logError = (message, err) => console.error(message, err),
+  } = deps;
+
+  async function cardCurrency() {
+    if (typeof getCardCurrency !== 'function') return null;
+    let timer = null;
+    try {
+      return await Promise.race([
+        Promise.resolve().then(() => getCardCurrency()),
+        new Promise((resolve) => { timer = setTimeout(() => resolve(null), DEEPSEEK_USAGE_IMPORT_CURRENCY_WAIT_MS); }),
+      ]);
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  app.post('/api/deepseek-usage-import', auth, async (req, res) => {
+    if (readRemoteRelayRequest(req, remoteRelayInbound || {}).remote) {
+      return res.status(403).json({ error: 'The DeepSeek usage export is imported by this relay\'s user only.' });
+    }
+    if (typeof deepseekUsageImportService?.importExport !== 'function') {
+      return res.status(501).json({ error: 'The DeepSeek usage import is not available on this relay.' });
+    }
+    const amount = req.body?.amount;
+    const cost = req.body?.cost;
+    if (typeof amount !== 'string' || typeof cost !== 'string') {
+      return res.status(400).json({ error: 'Choose both files of the export: the amount file and the cost file.' });
+    }
+    if (Buffer.byteLength(amount, 'utf8') + Buffer.byteLength(cost, 'utf8') > DEEPSEEK_USAGE_IMPORT_MAX_BYTES) {
+      return res.status(413).json({ error: 'The files are larger than 2 MB together; export a shorter period.' });
+    }
+    let result;
+    try {
+      result = deepseekUsageImportService.importExport({ amount, cost, cardCurrency: await cardCurrency() });
+    } catch (err) {
+      logError('[deepseek-usage-import] the import failed:', err);
+      return res.status(500).json({ error: 'The import failed on the relay; nothing was imported. Its log has the reason.' });
+    }
+    if (!result?.ok) return res.status(400).json({ error: result?.error || 'The export could not be read.' });
+    res.json({ ok: true, summary: result.summary });
+  });
+}