@oar-sh/oar 0.9.6 → 0.9.7

package/server/services/plan-usage-contract.mjs

@@ -9,9 +9,9 @@
  * while context usage describes one session's token window.
  *
  * Every provider normalizer in `plan-usage-<provider>.mjs` emits the same
- * `{ card: { meters, details, links } }` shape so the browser renderer stays
- * provider-agnostic, and so a provider that can only report *some* of its
- * limits degrades to fewer meters rather than to a special-cased layout.
+ * `{ card: { meters, details, notes, links } }` shape so the browser renderer
+ * stays provider-agnostic, and so a provider that can only report *some* of
+ * its limits degrades to fewer meters rather than to a special-cased layout.
  */
 
 export const PLAN_USAGE_VERSION = 2;
@@ -134,6 +134,16 @@ export function resolveMeterMath({
   };
 }
 
+/**
+ * A provider's severity word as a plain lowercase token ("normal",
+ * "warning", …). The vocabulary is the provider's; anything that is not a
+ * simple word is dropped rather than shown.
+ */
+export function toSeverity(value) {
+  const text = String(value ?? '').trim().toLowerCase();
+  return /^[a-z][a-z0-9_-]{0,23}$/.test(text) ? text : null;
+}
+
 /**
  * @param {object} spec
  * @param {string} spec.id            stable key, used by tests and DOM ids
@@ -141,6 +151,8 @@ export function resolveMeterMath({
  * @param {'credits'|'requests'|'usd'|'percent'|'tokens'} [spec.unit]
  * @param {boolean} [spec.unlimited]  plan grants unlimited use of this bucket
  * @param {boolean} [spec.estimated]  derived/manual rather than provider-authoritative
+ * @param {string} [spec.severity]    the provider's own word for how close the limit is
+ * @param {'expiry'} [spec.resetKind] `resetAt` is when the allowance ends for good, not when it refills
  * @returns {object|null} null when the meter carries no usable signal at all
  */
 export function buildMeter({
@@ -156,6 +168,8 @@ export function buildMeter({
   unlimited = false,
   estimated = false,
   emphasis = 'primary',
+  severity = null,
+  resetKind = null,
 } = {}) {
   const meterId = toTrimmedString(id);
   const meterLabel = toTrimmedString(label);
@@ -181,10 +195,29 @@ export function buildMeter({
     remaining: math.remaining,
     utilization: math.utilization,
     resetAt: toIsoTimestamp(resetAt),
+    resetKind: resetKind === 'expiry' ? 'expiry' : null,
+    severity: toSeverity(severity),
     note: toTrimmedString(note),
   };
 }
 
+/**
+ * A line of text on the card itself (not inside a collapsed section), with an
+ * optional link behind it. Same link rule as the card's footer: https only.
+ */
+export function buildCardNote({ id, text, link = null } = {}) {
+  const noteId = toTrimmedString(id);
+  const noteText = toTrimmedString(text);
+  if (!noteId || !noteText) return null;
+  const linkLabel = toTrimmedString(link?.label);
+  const url = toTrimmedString(link?.url);
+  return {
+    id: noteId,
+    text: noteText,
+    link: linkLabel && url && /^https:\/\//i.test(url) ? { label: linkLabel, url } : null,
+  };
+}
+
 /** A collapsible block of label/value rows shown under the meters. */
 export function buildDetailSection({ id, label, rows = [], note = null } = {}) {
   const sectionId = toTrimmedString(id);
@@ -214,6 +247,7 @@ export function buildProviderCard({
   stale = false,
   meters = [],
   details = [],
+  notes = [],
   links = [],
 } = {}) {
   const providerId = toTrimmedString(provider);
@@ -222,6 +256,7 @@ export function buildProviderCard({
 
   const normalizedMeters = (Array.isArray(meters) ? meters : []).filter(Boolean);
   const normalizedDetails = (Array.isArray(details) ? details : []).filter(Boolean);
+  const normalizedNotes = (Array.isArray(notes) ? notes : []).map((note) => buildCardNote(note || {})).filter(Boolean);
   const normalizedLinks = (Array.isArray(links) ? links : [])
     .map((link) => {
       const linkLabel = toTrimmedString(link?.label);
@@ -245,6 +280,7 @@ export function buildProviderCard({
     stale: stale === true,
     meters: normalizedMeters,
     details: normalizedDetails,
+    notes: normalizedNotes,
     links: normalizedLinks,
   };
 }

package/server/services/plan-usage-service.mjs

@@ -20,6 +20,7 @@ import {
 } from './plan-usage-contract.mjs';
 import { buildCopilotPlanCard } from './plan-usage-copilot.mjs';
 import { buildClaudePlanCard } from './plan-usage-claude.mjs';
+import { CLAUDE_CLOUD_PROVIDER_ID, buildClaudeCloudPlanCard } from './plan-usage-claude-cloud.mjs';
 import {
   CURSOR_POOLS,
   applyCursorUsageDelta,
@@ -383,6 +384,59 @@ export function createPlanUsageService({ db, now = () => new Date(), dbg = () =>
     return { cycle };
   }
 
+  // Claude Cloud conversations keep their reported cost on the runtime
+  // session row (migration 0007). That table is the relay's, not this
+  // service's, so the statements are prepared on first use, and only once
+  // the table and the column are there (an older database has neither).
+  let claudeCloudSpendStmts = null;
+  function claudeCloudSpendStatements() {
+    if (claudeCloudSpendStmts) return claudeCloudSpendStmts;
+    const columns = new Set(db.prepare(`PRAGMA table_info(runtime_sessions)`).all().map((column) => String(column.name)));
+    if (!columns.has('claude_cloud_cost_usd') || !columns.has('provider_type')) return null;
+    claudeCloudSpendStmts = {
+      totals: db.prepare(`
+        SELECT COUNT(*) AS conversation_count, COALESCE(SUM(claude_cloud_cost_usd), 0) AS total_usd
+        FROM runtime_sessions
+        WHERE LOWER(TRIM(provider_type)) = '${CLAUDE_CLOUD_PROVIDER_ID}'
+      `),
+      byConversation: db.prepare(`
+        SELECT claude_cloud_cost_usd AS cost_usd
+        FROM runtime_sessions
+        WHERE conversation_id = ? AND LOWER(TRIM(provider_type)) = '${CLAUDE_CLOUD_PROVIDER_ID}'
+      `),
+    };
+    return claudeCloudSpendStmts;
+  }
+
+  /**
+   * What the relay's cloud conversations have cost: the sum of the latest
+   * cost each one reported and how many there are, plus the cost of
+   * `conversationId` when that is a cloud conversation (`conversation` is
+   * null for any other). Only conversations that still exist count: a deleted
+   * one takes its row with it. There are no dates on these figures, so no
+   * per-day or per-week sum is offered. Null when the storage is not there.
+   */
+  function readClaudeCloudSpend({ conversationId = '' } = {}) {
+    try {
+      const statements = claudeCloudSpendStatements();
+      if (!statements) return null;
+      const totals = statements.totals.get();
+      const id = toTrimmedString(conversationId);
+      const row = id ? statements.byConversation.get(id) : null;
+      const cost = row ? Number(row.cost_usd) : null;
+      return {
+        totalUsd: Number(totals?.total_usd) || 0,
+        conversationCount: Number(totals?.conversation_count) || 0,
+        conversation: row
+          ? { costUsd: row.cost_usd !== null && Number.isFinite(cost) ? cost : null }
+          : null,
+      };
+    } catch (error) {
+      dbg('claude cloud spend read failed', error?.message || String(error));
+      return null;
+    }
+  }
+
   /**
    * Assemble the full multi-provider report. Every provider is independent:
    * one failing source produces an unavailable card instead of failing the
@@ -392,8 +446,17 @@ export function createPlanUsageService({ db, now = () => new Date(), dbg = () =>
     copilotSummary = null,
     copilotError = null,
     copilotStale = false,
+    // When the quota answer is an earlier one served again (the modal asked
+    // for another provider live), the time it was really read.
+    copilotCapturedAt = null,
     copilotBilling = null,
     claudeConfigured = true,
+    // Live account usage (claude-account-usage-service.mjs), or null: it is
+    // only ever read while Claude Cloud is switched on.
+    claudeAccount = null,
+    claudeCloudConfigured = false,
+    // The conversation the modal was opened from, for its own cloud cost.
+    conversationId = '',
     cursorConfigured = true,
     cursorAllowances = null,
     cursorBilling = null,
@@ -404,6 +467,9 @@ export function createPlanUsageService({ db, now = () => new Date(), dbg = () =>
   } = {}) {
     const generatedAt = nowIso();
     const claudeSnapshot = readSnapshot('claude');
+    // What the cloud workers post to /api/claude-plan-usage is kept under its
+    // own key, so the Claude card stays what the Claude workers wrote.
+    const claudeCloudSnapshot = claudeCloudConfigured === true ? readSnapshot(CLAUDE_CLOUD_PROVIDER_ID) : null;
     const allowances = normalizeCursorAllowanceSettings(cursorAllowances || {});
     const cursorCycle = readCursorCycleTotals({ resetDay: allowances.resetDay });
     const grokSettings = normalizeGrokAllowanceSettings(grokAllowances || {});
@@ -421,7 +487,7 @@ export function createPlanUsageService({ db, now = () => new Date(), dbg = () =>
         billing: copilotBilling,
         workerUsage: copilotWorkerSnapshot?.payload || null,
         error: copilotError,
-        capturedAt: generatedAt,
+        capturedAt: copilotCapturedAt || generatedAt,
         stale: copilotStale === true,
       }),
       buildClaudePlanCard({
@@ -431,9 +497,22 @@ export function createPlanUsageService({ db, now = () => new Date(), dbg = () =>
         message: claudeSnapshot?.error || null,
         // A stored snapshot is by definition from an earlier turn; the SDK's
         // usage control call only works while a session transport is open, and
-        // the relay never opens a billable turn just to refresh this.
+        // the relay never opens a billable turn just to refresh this. Live
+        // account usage, where there is any, takes the meters over.
         stale: !!claudeSnapshot?.payload,
+        account: claudeAccount,
       }),
+      // Opt-in like Grok (no card while the provider is off), and placed next
+      // to the Claude card because both are the same account.
+      claudeCloudConfigured === true
+        ? buildClaudeCloudPlanCard({
+          account: claudeAccount,
+          spend: readClaudeCloudSpend({ conversationId }),
+          usage: claudeCloudSnapshot?.payload || null,
+          capturedAt: claudeCloudSnapshot?.capturedAt || null,
+          configured: true,
+        })
+        : null,
       buildCursorPlanCard({
         totals: cursorCycle.totals,
         allowances,
@@ -481,6 +560,7 @@ export function createPlanUsageService({ db, now = () => new Date(), dbg = () =>
     recordGrokUsageReport,
     readGrokCycleTotals,
     resetGrokAccounting,
+    readClaudeCloudSpend,
     buildReport,
     pools: CURSOR_POOLS,
   };

package/server/services/provider-reasoning-effort.mjs

@@ -12,6 +12,7 @@ import { openAIReasoningEffortsForModel } from '../../shared/openai-reasoning.mj
 export const CLAUDE_ULTRACODE_EFFORT = 'ultracode';
 export const DEFAULT_CLAUDE_REASONING_EFFORTS = Object.freeze(['none', 'low', 'medium', 'high', 'xhigh', 'max', CLAUDE_ULTRACODE_EFFORT]);
 export const DEFAULT_GROK_REASONING_EFFORTS = Object.freeze(['none', 'low', 'medium', 'high']);
+export const CLAUDE_CLOUD_REASONING_EFFORTS = Object.freeze(['none']);
 
 // Ultracode requires an xhigh-capable model (the SDK's stated gate), so the
 // tier is derived from a model's discovered efforts rather than discovery —
@@ -54,6 +55,8 @@ export function supportedReasoningEffortsForProviderModel({
   if (provider === 'grok') {
     return effortsForModel(grokSettings?.effortsByModel, model) || [...DEFAULT_GROK_REASONING_EFFORTS];
   }
+  // A cloud session takes no effort choice: the only tier is the default one.
+  if (provider === 'claude-cloud') return [...CLAUDE_CLOUD_REASONING_EFFORTS];
   if (provider === 'openai' || provider === 'openai-image') {
     const efforts = openAIReasoningEffortsForModel(model);
     return Array.isArray(efforts) && efforts.length ? efforts.map(normalizeEffort).filter(Boolean) : null;

package/server/services/remote-relay-caller-context.mjs

@@ -33,6 +33,8 @@ import { sanitizeRelayQuestionContext } from './relay-question-context.mjs';
 
 const LOG_PREFIX = '[remote-relays]';
 const APPROVAL_HEADER = 'Remote relay';
+// The once-per-conversation card for sessions an agent starts on this relay.
+const LOCAL_SESSIONS_HEADER = 'Agent sessions';
 const APPROVAL_ALLOW = 'Allow';
 const APPROVAL_DENY = 'Deny';
 const EXCERPT_MAX = 200;
@@ -115,21 +117,45 @@ function describeRemoteTurn(action, args, caller) {
   return parts.join(' · ');
 }
 
+/**
+ * What a session an agent starts on this relay works on, for the card: the
+ * repository (and branch) of a Claude Cloud session, else the folder, else
+ * the relay's default folder.
+ */
+function describeLocalSessionTarget(args) {
+  const repo = toText(args.repo).replace(/^https?:\/\/(?:www\.)?github\.com\//i, '');
+  if (repo) return toText(args.branch) ? `${excerpt(repo)}, branch ${excerpt(args.branch)}` : excerpt(repo);
+  return toText(args.cwd) ? excerpt(args.cwd) : 'the default folder';
+}
+
 /**
  * The card text: what the agent wants to do where, how the remote turn would
  * run, then the prompt (or the answer) it wants to send, so the user decides
  * on the actual words. `caller` is the calling session's context.
+ *
+ * `localSessions` is the once-per-conversation card of the local target: the
+ * agent wants to start sessions on this relay itself. Allowing it covers the
+ * later ones of that conversation, so the card says what they cost.
  */
-export function formatRemoteRelayApprovalPrompt({ relay, action, args = {}, caller = null, agentPrompts = 0 } = {}) {
+export function formatRemoteRelayApprovalPrompt({ relay, action, args = {}, caller = null, agentPrompts = 0, localSessions = false } = {}) {
+  const local = relay?.local === true;
   const name = toText(relay?.name) || 'a remote relay';
+  const where = local ? 'this relay' : `relay "${name}"`;
   const verb = APPROVAL_VERBS[action] || toText(action).replace(/_/g, ' ') || 'act';
   const target = args.session ? ` (session ${shortId(args.session)})` : '';
   const lines = [];
   // The loop guard's card: agents that prompt each other without the user.
   if (agentPrompts > 0) {
-    lines.push(`The agent has sent ${agentPrompts} prompts to agents on other relays since your last message. Let it go on?`);
+    lines.push(`The agent has sent ${agentPrompts} prompts to ${local ? 'other agents' : 'agents on other relays'} since your last message. Let it go on?`);
+  }
+  if (localSessions) {
+    const requested = toText(args.provider).toLowerCase();
+    const callerProvider = toText(caller?.provider).toLowerCase();
+    const provider = requested || (REMOTE_RELAY_PROVIDERS.includes(callerProvider) ? callerProvider : 'github');
+    lines.push(`This agent wants to start sessions on this relay (${provider}, ${describeLocalSessionTarget(args)}). Sessions it starts use this relay's accounts.`);
+  } else {
+    lines.push(`Allow the agent to ${verb} on ${where}${target}?`);
   }
-  lines.push(`Allow the agent to ${verb} on relay "${name}"${target}?`);
   if (action === 'send' || action === 'create_session') {
     const details = describeRemoteTurn(action, args, caller);
     if (details) lines.push(details);
@@ -288,31 +314,44 @@ export function createRemoteRelayCallerContext({
    * `agentPrompts` (the loop guard) is how many prompts the agent has sent to
    * other relays' agents since the user last wrote; the card then asks for
    * that, in any relay mode.
+   * `localSessions` makes it the card for starting sessions on this relay
+   * itself, asked once per conversation (the dispatcher remembers the Allow).
    */
-  async function requestApproval({ conversationId, callerContext, relay, action, args = {}, signal, agentPrompts = 0 } = {}) {
+  async function requestApproval({ conversationId, callerContext, relay, action, args = {}, signal, agentPrompts = 0, localSessions = false } = {}) {
     const rowId = toText(callerContext?.processingRowId);
     const row = rowId ? getQueueRow.get(rowId) : null;
     if (!row || row.status !== 'processing') {
       return {
         approved: false,
         code: REMOTE_RELAY_ERROR_CODES.noTurn,
-        error: 'This write action needs the user\'s approval, but the conversation has no running turn to ask on.',
+        error: localSessions
+          ? 'Starting sessions on this relay needs the user\'s approval once per conversation, but the conversation has no running turn to ask on.'
+          : 'This write action needs the user\'s approval, but the conversation has no running turn to ask on.',
       };
     }
 
     const createdAt = now().toISOString();
     const questionId = String(uuid());
     const relayMode = normalizeMode(row.relay_mode);
-    const prompt = formatRemoteRelayApprovalPrompt({ relay, action, args, caller: callerContext, agentPrompts });
+    const prompt = formatRemoteRelayApprovalPrompt({ relay, action, args, caller: callerContext, agentPrompts, localSessions });
+    const local = relay?.local === true;
+    let rationale = `Write actions on ${local ? 'other sessions of this relay' : 'other relays'} need approval in ${relayMode} mode.`;
+    if (agentPrompts > 0) {
+      rationale = local
+        ? 'Agents that keep prompting each other need your go from time to time.'
+        : 'Agents on different relays that keep prompting each other need your go from time to time.';
+    } else if (localSessions) {
+      rationale = 'Allow covers every session this conversation\'s agent starts on this relay; Deny refuses this one.';
+    }
+    // The same source for every card of this tool: it is what keeps agents
+    // (other relays' and this relay's own) from seeing or answering one.
     const context = sanitizeRelayQuestionContext({
       source: REMOTE_RELAY_APPROVAL_SOURCE,
-      rationale: agentPrompts > 0
-        ? 'Agents on different relays that keep prompting each other need your go from time to time.'
-        : `Write actions on other relays need approval in ${relayMode} mode.`,
+      rationale,
       queueMessageId: row.id,
       conversationId: toText(conversationId) || row.conversation_id,
       relayMode,
-      header: APPROVAL_HEADER,
+      header: localSessions ? LOCAL_SESSIONS_HEADER : APPROVAL_HEADER,
     }, { normalizeRelayMode: normalizeMode, defaultRelayMode });
     questionStatements.insertQuestion.run(
       questionId,

package/server/services/remote-relay-client.mjs

@@ -121,6 +121,15 @@ function networkError(relay, error, timeoutMs) {
   );
 }
 
+/**
+ * The error for a relay that answered with a non-2xx status and (maybe) a JSON
+ * body. Shared with the in-process loopback, so a refusal of this relay's own
+ * routes reads exactly like a paired relay's.
+ */
+export function remoteRelayHttpError(relay, status, body) {
+  return httpError(relay, status, body);
+}
+
 function httpError(relay, status, body) {
   const remoteError = isPlainObject(body) && toText(body.error) ? toText(body.error).slice(0, REMOTE_ERROR_TEXT_MAX) : null;
   const remoteCode = isPlainObject(body) && toText(body.code) ? toText(body.code).slice(0, 100) : null;