@oar-sh/oar 0.9.6 → 0.9.7

package/shared/remote-relay-contract.mjs

@@ -7,9 +7,15 @@
 // provenance ("origin") shape a relay attaches when its agent prompts a remote
 // session, the prompt header line, and the URL policy for remote addresses.
 //
+// Since agent sessions, the relay an agent runs on is a target as well (the
+// "local target", addressed by this relay's name or `this`): the same tool
+// creates and drives sessions on its own relay, behind a setting.
+//
 // SDK-free and side-effect free: imported by the server, the session workers,
 // the stdio MCP server and (for the header/URL helpers) the browser.
 
+import { isValidBranchName, normalizeGitHubRepoUrl } from './claude-cloud/repo-url.mjs';
+
 export const REMOTE_RELAY_TOOL_NAME = 'remote_relay';
 
 // Bumped when a relay starts relying on a newer inbound behaviour of its peers.
@@ -60,7 +66,7 @@ export const REMOTE_RELAY_PROMPT_ACTIONS = Object.freeze(['send', 'create_sessio
 export const REMOTE_RELAY_APPROVAL_MODES = Object.freeze(['ask', 'plan']);
 
 export const REMOTE_RELAY_SESSION_SCOPES = Object.freeze(['active', 'recent', 'all']);
-export const REMOTE_RELAY_PROVIDERS = Object.freeze(['github', 'openai', 'claude', 'cursor', 'grok']);
+export const REMOTE_RELAY_PROVIDERS = Object.freeze(['github', 'openai', 'claude', 'cursor', 'grok', 'claude-cloud']);
 export const REMOTE_RELAY_MODES = Object.freeze(['plan', 'ask', 'agent', 'autopilot']);
 export const REMOTE_RELAY_IF_BUSY = Object.freeze(['queue', 'fail']);
 // Reasoning efforts differ per provider and model (none, low, medium, high,
@@ -81,7 +87,16 @@ export const REMOTE_RELAY_RESULT_STATUSES = Object.freeze([
 
 export const REMOTE_RELAY_LIMITS = Object.freeze({
   waitDefaultSeconds: 120,
+  // The longest wait of one call is a setting of the relay ("Longest wait per
+  // tool call"): waitMaxSeconds is its default, the next three its range. The
+  // validator below clamps to the ceiling; the relay clamps to its setting.
   waitMaxSeconds: 600,
+  waitMaxFloorSeconds: 120,
+  waitMaxCeilingSeconds: 3600,
+  waitMaxStepSeconds: 60,
+  // Sessions one conversation's agent started on its own relay that may have
+  // a turn queued or running at the same time.
+  localActiveSessions: 4,
   listDefault: 20,
   listMax: 100,
   readDefault: 10,
@@ -119,6 +134,15 @@ export const REMOTE_RELAY_ERROR_CODES = Object.freeze({
   providerUnavailable: 'REMOTE_RELAY_PROVIDER_UNAVAILABLE',
   busy: 'REMOTE_RELAY_BUSY',
   noTurn: 'REMOTE_RELAY_NO_ACTIVE_TURN',
+  // The local target (this relay itself):
+  // the setting "Agents may start and use sessions on this relay" is off,
+  localDisabled: 'REMOTE_RELAY_LOCAL_DISABLED',
+  // a session an agent created tried to create one itself,
+  nestedSession: 'REMOTE_RELAY_NESTED_SESSION',
+  // the conversation already has `localActiveSessions` created sessions at work,
+  sessionLimit: 'REMOTE_RELAY_SESSION_LIMIT',
+  // and an agent tried to prompt, stop, archive, wait for or answer itself.
+  ownSession: 'REMOTE_RELAY_OWN_SESSION',
   internal: 'REMOTE_RELAY_INTERNAL',
   // Prefix: the remote answered with this HTTP status, e.g. REMOTE_RELAY_HTTP_409.
   httpPrefix: 'REMOTE_RELAY_HTTP_',
@@ -131,6 +155,10 @@ export const REMOTE_RELAY_SETTING_KEYS = Object.freeze({
   relays: 'remote_relays',
   publicUrl: 'relay_public_url',
   inboundEnabled: 'remote_relay_inbound_enabled',
+  // Agent sessions: the local target's switch (off unless set) and the longest
+  // wait of one tool call, for local and paired targets alike.
+  agentSessionsEnabled: 'agent_sessions_enabled',
+  maxWaitSeconds: 'remote_relay_max_wait_seconds',
 });
 
 // Headers a relay adds to every call it forwards to a remote. The remote uses
@@ -142,22 +170,42 @@ export const REMOTE_RELAY_HEADERS = Object.freeze({
 });
 
 export const REMOTE_RELAY_SOCKET_EVENT = 'remote_relays_updated';
+// Carries the payload of GET /api/settings/agent-sessions.
+export const AGENT_SESSIONS_SOCKET_EVENT = 'agent_sessions_settings_updated';
+
+// The local target: the alias that always names the relay the agent runs on,
+// and the id it has wherever a paired relay has its registry id (the
+// remembered approval is stored as an unlock under it).
+export const REMOTE_RELAY_LOCAL_ALIAS = 'this';
+export const REMOTE_RELAY_LOCAL_ID = 'self';
+export const REMOTE_RELAY_CLOUD_PROVIDER = 'claude-cloud';
 
 export const REMOTE_RELAY_TOOL_DESCRIPTION =
-  'Work with sessions on other OAR relays this relay is paired with ("remote relays"): '
-  + 'list the relays, list or read their sessions, prompt a session, start a new one, '
-  + 'wait for its reply, and answer or stop it. Use it only when the user asks for work '
-  + 'on another relay or mentions one, or to answer an agent on another relay that wrote '
-  + 'to this conversation. Start with {action:"list_relays"}. A relay stays locked until '
+  'Work with sessions on OAR relays: the other relays this relay is paired with ("remote relays") '
+  + 'and, when its owner allows it, this relay itself. List the relays, list or read their '
+  + 'sessions, prompt a session, start a new one, wait for its reply, and answer or stop it. '
+  + 'Start with {action:"list_relays"}. A paired relay stays locked until '
   + 'the user mentions it in this conversation (for example @name) or an agent on that '
   + 'relay writes to it; from then on it stays open for the whole conversation. A '
   + 'locked relay refuses everything except list_relays, so ask the user to mention it. '
+  + '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 is listed with self:true 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 up to '
+  + `${REMOTE_RELAY_LIMITS.localActiveSessions} sessions that work at the same time (any provider relay_info lists: local ones `
+  + 'with cwd, provider "claude-cloud" with repo and an optional branch), then wait for and read '
+  + 'each one. The first create_session here shows the user an approval card once per '
+  + 'conversation. A session you created cannot create sessions itself, and every session '
+  + 'runs on the relay owner\'s accounts, so start only what the task needs. A new session '
+  + 'knows nothing of this conversation: write a self-contained prompt, and for '
+  + '"claude-cloud" (a sandbox with a fresh clone of the repository) name the branch to '
+  + 'work on and to push. '
   + 'send and create_session queue the prompt and wait up to wait_seconds (default 120, '
-  + 'max 600) for the reply. If the remote turn is still running you get status '
+  + 'max set on the relay, default 600) for the reply. If the turn is still running you get status '
   + '"running" with progress: call {action:"wait", relay, session, message_id} to keep '
-  + 'waiting. A remote agent that answers but keeps working in the background also comes '
+  + 'waiting. An agent that answers but keeps working in the background also comes '
   + 'back as "running", with its latest reply so far; "done" means it has finished. '
-  + 'If a result lists pendingQuestions, the remote agent is waiting for an '
+  + 'If a result lists pendingQuestions, the other agent is waiting for an '
   + 'answer: ask the user (unless they told you to decide yourself) and pass the answer '
   + 'with answer_question. Write actions can first need the user\'s approval. Always '
   + 'tell the user which relay and session you worked on.';
@@ -168,21 +216,22 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
     action: {
       type: 'string',
       enum: [...REMOTE_RELAY_ACTIONS],
-      description: 'list_relays: paired relays and whether each is unlocked here. relay_info: providers, models, '
+      description: 'list_relays: the relays (this one included when allowed) and whether each is unlocked here. relay_info: providers, models, '
         + 'workspaces of a relay. list_sessions / read_session: discover and read sessions. 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.',
     },
-    relay: { type: 'string', description: 'Relay name (or its host) from list_relays. Required except for list_relays.' },
-    session: { type: 'string', description: 'Remote session (conversation) id from list_sessions or create_session.' },
-    text: { type: 'string', description: 'send / create_session: the prompt for the remote agent.' },
+    relay: { type: 'string', description: 'Relay name (or its host) from list_relays, or "this" for the relay you run on. Required except for list_relays.' },
+    session: { type: 'string', description: 'Session (conversation) id from list_sessions or create_session.' },
+    text: { type: 'string', description: 'send / create_session: the prompt for the other agent.' },
     message_id: { type: 'string', description: 'wait: the message_id that send or create_session returned.' },
     wait_seconds: {
       type: 'integer',
       minimum: 0,
-      maximum: REMOTE_RELAY_LIMITS.waitMaxSeconds,
-      description: 'send / create_session / wait: how long to wait for the reply (default 120, 0 = do not wait).',
+      maximum: REMOTE_RELAY_LIMITS.waitMaxCeilingSeconds,
+      description: 'send / create_session / wait: how long to wait for the reply (default 120, 0 = do not wait; '
+        + 'the relay limits it to its own maximum, 600 unless its owner changed it).',
     },
     scope: {
       type: 'string',
@@ -211,7 +260,16 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
       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).',
     },
-    cwd: { type: 'string', description: 'create_session: working directory on the remote relay (default: its default workspace).' },
+    cwd: { type: 'string', description: 'create_session: working directory on the target relay (default: its default workspace). Not for claude-cloud.' },
+    repo: {
+      type: 'string',
+      description: 'create_session with provider "claude-cloud" (required there, an error with any other provider): '
+        + 'the GitHub repository the cloud session clones, as https://github.com/owner/repo or owner/repo.',
+    },
+    branch: {
+      type: 'string',
+      description: 'create_session with provider "claude-cloud": the branch to check out (default: the repository\'s default branch).',
+    },
     mode: {
       type: 'string',
       enum: [...REMOTE_RELAY_MODES],
@@ -257,13 +315,46 @@ function invalid(error) {
 
 const SESSION_ACTIONS = new Set(['read_session', 'wait', 'send', 'stop', 'archive']);
 
+/**
+ * The longest wait a relay may be set to allow, from whatever was stored or
+ * sent: a whole number of seconds inside the range, or the default.
+ */
+export function normalizeRemoteRelayMaxWaitSeconds(value) {
+  const number = Number(value);
+  if (value === null || value === undefined || value === '' || !Number.isFinite(number)) {
+    return REMOTE_RELAY_LIMITS.waitMaxSeconds;
+  }
+  return Math.min(
+    REMOTE_RELAY_LIMITS.waitMaxCeilingSeconds,
+    Math.max(REMOTE_RELAY_LIMITS.waitMaxFloorSeconds, Math.trunc(number)),
+  );
+}
+
+/**
+ * The repository of a Claude Cloud session as an agent may write it: any form
+ * shared/claude-cloud/repo-url.mjs takes, or the bare `owner/repo`. Returns
+ * the canonical https URL, or '' when the text names no GitHub repository.
+ */
+export function normalizeRemoteRelayRepo(value) {
+  const text = toText(value);
+  if (!text) return '';
+  const direct = normalizeGitHubRepoUrl(text);
+  if (direct) return direct.repoUrl;
+  if (!/^[^/\s:@]+\/[^/\s:@]+$/.test(text)) return '';
+  return normalizeGitHubRepoUrl(`https://github.com/${text}`)?.repoUrl || '';
+}
+
 /**
  * Validates and normalises one tool call. Adapters call it for a crisp early
  * message; the relay calls it again authoritatively. Returns
  * `{ ok:true, action, args }` with only the fields the action uses, defaults
  * filled in and numbers clamped, or `{ ok:false, code, error }`.
+ *
+ * `maxWaitSeconds` is the relay's own setting; without it (an adapter, which
+ * does not know the setting) wait_seconds is clamped to the ceiling only.
+ * `waitLimitedFrom` is set on the result when the relay's setting cut the wait.
  */
-export function validateRemoteRelayToolInput(input = {}) {
+export function validateRemoteRelayToolInput(input = {}, { maxWaitSeconds } = {}) {
   const action = toText(input?.action).toLowerCase();
   if (!REMOTE_RELAY_ACTIONS.includes(action)) {
     return invalid(`action must be one of: ${REMOTE_RELAY_ACTIONS.join(', ')}`);
@@ -281,12 +372,20 @@ export function validateRemoteRelayToolInput(input = {}) {
     args.session = session;
   }
 
-  const waitSeconds = clampInteger(input?.wait_seconds, {
+  const waitCeiling = clampInteger(input?.wait_seconds, {
     min: 0,
-    max: REMOTE_RELAY_LIMITS.waitMaxSeconds,
+    max: REMOTE_RELAY_LIMITS.waitMaxCeilingSeconds,
     fallback: REMOTE_RELAY_LIMITS.waitDefaultSeconds,
   });
-  if (waitSeconds === null) return invalid('wait_seconds must be a number of seconds');
+  if (waitCeiling === null) return invalid('wait_seconds must be a number of seconds');
+  const waitMax = maxWaitSeconds === undefined
+    ? REMOTE_RELAY_LIMITS.waitMaxCeilingSeconds
+    : normalizeRemoteRelayMaxWaitSeconds(maxWaitSeconds);
+  const waitSeconds = Math.min(waitCeiling, waitMax);
+  // What the agent asked for, when the relay's setting allows less.
+  const waitLimited = waitSeconds < waitCeiling
+    ? { waitLimitedFrom: Math.trunc(Math.min(Number(input.wait_seconds), Number.MAX_SAFE_INTEGER)) }
+    : {};
 
   const optionalEnum = (key, allowed) => {
     const value = toText(input?.[key]).toLowerCase();
@@ -348,6 +447,29 @@ export function validateRemoteRelayToolInput(input = {}) {
       if (!providerCheck.ok) return providerCheck;
       optionalText('cwd', 1000);
       optionalText('title', 200);
+      // A Claude Cloud session clones a repository instead of opening a
+      // folder: repo and branch belong to that provider alone. A call that
+      // names no provider gets this session's, so "repo is missing" for a
+      // cloud caller is the relay's to say.
+      const repoText = toText(input?.repo);
+      const branchText = toText(input?.branch);
+      if (args.provider === REMOTE_RELAY_CLOUD_PROVIDER) {
+        if (!repoText) {
+          return invalid('create_session with provider "claude-cloud" needs repo (https://github.com/owner/repo or owner/repo)');
+        }
+        if (args.cwd) return invalid('cwd does not apply to provider "claude-cloud": it clones repo instead of opening a folder');
+      } else if (repoText || branchText) {
+        return invalid('repo and branch go with provider "claude-cloud" only; pass provider "claude-cloud", or cwd for a folder on the relay');
+      }
+      if (repoText) {
+        const repo = normalizeRemoteRelayRepo(repoText);
+        if (!repo) return invalid('repo must be a GitHub repository: https://github.com/owner/repo or owner/repo');
+        args.repo = repo;
+      }
+      if (branchText) {
+        if (!isValidBranchName(branchText)) return invalid(`branch "${branchText.slice(0, 80)}" is not a valid branch name`);
+        args.branch = branchText;
+      }
     }
   } else if (action === 'answer_question') {
     const questionId = toText(input?.question_id);
@@ -361,7 +483,8 @@ export function validateRemoteRelayToolInput(input = {}) {
     if (answer) args.answer = answer.slice(0, REMOTE_RELAY_LIMITS.textMax);
     if (choices.length) args.choices = choices;
   }
-  return { ok: true, action, args };
+  const waits = Object.prototype.hasOwnProperty.call(args, 'wait_seconds');
+  return { ok: true, action, args, ...(waits ? waitLimited : {}) };
 }
 
 const PERMISSION_RANK = { read: 1, prompt: 2, full: 3 };
@@ -417,7 +540,12 @@ const ORIGIN_CAPS = {
 /**
  * Sanitises an `origin` object received on /api/message or bootstrap (or built
  * locally before forwarding). Returns null when it does not describe an agent
- * on another relay. Every field is a capped string except `hops`.
+ * on a relay. Every field is a capped string except `hops` and `local`.
+ *
+ * `local: true` marks an agent of THIS relay (the local target): the
+ * conversation named by `conversationId` lives here. Only the in-process
+ * loopback may claim it; the inbound side drops it from anything that came in
+ * over HTTP (readRemoteRelayRequest).
  */
 export function normalizeRemoteRelayOrigin(raw) {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
@@ -430,6 +558,7 @@ export function normalizeRemoteRelayOrigin(raw) {
   if (origin.relayUrl && !/^https?:\/\//i.test(origin.relayUrl)) origin.relayUrl = '';
   const hops = Number(raw.hops);
   origin.hops = Number.isInteger(hops) && hops >= 0 ? Math.min(hops, 10) : 1;
+  if (raw.local === true) origin.local = true;
   return origin;
 }
 
@@ -443,6 +572,8 @@ function quoteForHeader(value) {
  * message carries `origin` (the badge shows the same facts).
  */
 export function formatRemotePromptHeader(origin) {
+  // The same line for an agent of this relay (origin.local): REMOTE_PROMPT_HEADER_PATTERN
+  // and every reader that strips it stay as they are.
   const parts = [`[Remote prompt from an agent on relay "${quoteForHeader(origin?.relayName) || 'unknown'}"`];
   const title = quoteForHeader(origin?.conversationTitle);
   if (title) parts.push(`session "${title}"`);

package/shared/remote-relay-tool-core.mjs

@@ -41,7 +41,8 @@ export function cloneRemoteRelayToolInputSchema() {
   return JSON.parse(JSON.stringify(REMOTE_RELAY_TOOL_INPUT_SCHEMA));
 }
 
-// How many remotes this relay knows (`{ count }`): the registration decision.
+// How many remotes this relay knows and whether its own sessions are open to
+// agents (`{ count, localEnabled }`): the registration decision.
 export const REMOTE_RELAY_SUMMARY_PATH = '/api/remote-relays/summary';
 // Calls of one conversation the relay is still working on (`{ inflight }`):
 // the Grok inactivity hold, which cannot see the tool call itself.
@@ -62,9 +63,9 @@ export const REMOTE_RELAY_CANCELLED = 'REMOTE_RELAY_CANCELLED';
 export const REMOTE_RELAY_DECISION_TIMEOUT_MS = 5_000;
 
 // A hard ceiling for one tool call on the providers that impose their own
-// (MCP clients). The relay already bounds the wait (wait_seconds ≤ 600) but not
-// the time an approval card may sit unanswered, so this only has to outlast a
-// human, never a remote turn.
+// (MCP clients). The relay already bounds the wait (wait_seconds up to its
+// "longest wait" setting, at most an hour) but not the time an approval card
+// may sit unanswered, so this only has to outlast a human, never a turn.
 export const REMOTE_RELAY_TOOL_CALL_TIMEOUT_MS = 8 * 60 * 60_000;
 
 function toText(value) {
@@ -146,8 +147,9 @@ export function remoteRelayCancelledResult() {
  * contract as executePreviewTool.
  *
  * The call goes out as a long call (`{ longCall: true }`): no client-side
- * timeout at all, because the relay bounds the wait itself (wait_seconds plus
- * approval time) and fetch's 300 s header limit would cut both short.
+ * timeout at all, because the relay bounds the wait itself (wait_seconds,
+ * cut to the relay's own maximum, plus approval time) and fetch's 300 s
+ * header limit would cut both short.
  * `signal` (the provider's cancellation) is the only way to end it early.
  */
 export async function executeRemoteRelayTool(input, { api, conversationId = '', signal = null } = {}) {
@@ -176,7 +178,8 @@ export async function executeRemoteRelayTool(input, { api, conversationId = '',
 }
 
 /**
- * Whether a worker should register the tool: at least one remote is paired.
+ * Whether a worker should register the tool: at least one remote is paired,
+ * or this relay lets agents start and use sessions on it (the local target).
  * Fails closed — any error, a malformed answer or a slow relay leaves the tool
  * out, and the next worker start asks again.
  */
@@ -188,7 +191,7 @@ export async function shouldRegisterRemoteRelayTool({ api, timeoutMs = REMOTE_RE
       timeoutMs,
       'remote relay summary',
     );
-    return Number(response?.count) > 0;
+    return Number(response?.count) > 0 || response?.localEnabled === true;
   } catch {
     return false;
   }

package/shared/steer-settle-failure.mjs

@@ -84,6 +84,7 @@ export function steerAgentLabelForProvider(providerType) {
     case 'openai': return 'Copilot';
     case 'cursor': return 'Cursor';
     case 'grok': return 'Grok';
+    case 'claude-cloud': return 'Claude Cloud';
     default: return DEFAULT_STEER_AGENT_LABEL;
   }
 }