@oar-sh/oar 0.9.5 → 0.9.7

package/shared/control-poller.mjs

@@ -23,7 +23,10 @@ export function createControlPoller({
   onAbortSubagent = null,
   dbg = () => {},
 } = {}) {
-  let active = null;
+  // The turns a Stop is polled for, oldest first, and whether the one loop
+  // that serves them all is running.
+  const registrations = new Set();
+  let polling = false;
 
   async function checkOnce({ queueMessageId, onAbortTurn }) {
     const ownerSessionId = String(sdkSessionId || '').trim();
@@ -81,37 +84,83 @@ export function createControlPoller({
     }
   }
 
-  function start({ queueMessageId, onAbortTurn }) {
-    stop();
-    const state = { stopped: false };
-    active = state;
-    (async () => {
-      while (!state.stopped) {
-        await sleep(pollMs);
-        if (state.stopped) return;
+  /**
+   * Hand a Stop to the turns that polled for it, newest first, until one of
+   * them takes it. The candidates were chosen before the request went out and
+   * are not re-checked here: the relay has claimed the control for this worker
+   * by now, so a turn that finished meanwhile still has to answer it.
+   */
+  async function offerAbort(candidates, control) {
+    let failure = null;
+    for (const registration of candidates) {
+      try {
+        await registration.onAbortTurn(control);
+        return;
+      } catch (error) {
+        failure = error;
+      }
+    }
+    throw failure || new Error('abort failed');
+  }
+
+  async function pollLoop() {
+    while (registrations.size) {
+      await sleep(pollMs);
+      // One request per row filter, however many turns share it, asked in the
+      // order of the newest turn that uses it.
+      const byFilter = new Map();
+      for (const registration of [...registrations].reverse()) {
+        const candidates = byFilter.get(registration.queueMessageId) || [];
+        candidates.push(registration);
+        byFilter.set(registration.queueMessageId, candidates);
+      }
+      for (const [queueMessageId, candidates] of byFilter) {
+        // Every turn behind this filter ended while an earlier one was asked.
+        if (candidates.every((registration) => registration.stopped)) continue;
         try {
-          const aborted = await checkOnce({ queueMessageId, onAbortTurn });
-          if (aborted) return;
+          await checkOnce({ queueMessageId, onAbortTurn: (control) => offerAbort(candidates, control) });
         } catch (error) {
           dbg('control poll failed', error?.message || String(error));
         }
       }
-    })();
-    return state;
+    }
+    polling = false;
+  }
+
+  /**
+   * Poll for a Stop on behalf of one turn, until `stop(handle)`. Turns overlap
+   * (a settled turn still waiting on a question card or publishing, beside the
+   * one that runs), so a new registration never displaces an older one, and a
+   * handled Stop does not end the polling: the Stop may have been for another
+   * turn's row, and the turns that remain still need theirs.
+   */
+  function start({ queueMessageId, onAbortTurn }) {
+    const registration = {
+      stopped: false,
+      queueMessageId: String(queueMessageId || ''),
+      onAbortTurn,
+    };
+    registrations.add(registration);
+    if (!polling) {
+      polling = true;
+      void pollLoop();
+    }
+    return registration;
   }
 
   function stop(handle) {
-    // Handle-scoped stop: a caller finishing an old turn must only stop that
-    // turn's poller. Without the scoping, a late finalize for a previous
-    // context would kill the poller of the turn currently running — leaving
-    // its Stop button dead. A bare stop() still stops whatever is active.
+    // Handle-scoped stop: a caller finishing a turn ends that turn's
+    // registration and no other. Without the scoping, a late finalize for a
+    // previous context would end the polling for the turn currently running,
+    // leaving its Stop button dead. A bare stop() ends every registration (the
+    // worker is shutting down).
     if (handle) {
       handle.stopped = true;
-      if (active === handle) active = null;
+      registrations.delete(handle);
       return;
     }
-    if (active) active.stopped = true;
-    active = null;
+    for (const registration of registrations) registration.stopped = true;
+    registrations.clear();
   }
 
   return { start, stop, checkOnce };

package/shared/failure-note-text.mjs

@@ -0,0 +1,38 @@
+// What makes a text a failure note of the relay.
+//
+// A failed turn is reported as a record. Where only text is there (a sender
+// that reports a failure as text, a reply read from another relay), the note
+// is known by its shape: one paragraph that leads up to "Error code:
+// relay.<code>" within a few sentences. A reply that quotes or describes such
+// a note, in a report on a failed test for example, is a reply.
+//
+// One rule for every reader: the relay's response route and the remote-relay
+// dispatcher must not disagree about what a failure is.
+
+export const FAILURE_NOTE_LEAD_MAX = 600;
+
+const CODE_PATTERN = /error code:\s*(relay\.[a-z0-9-]+)/i;
+// Somebody is talking about a note: the code stands in quotation marks, in a
+// code span or a table cell, or the paragraph is a list item, a heading or a
+// quotation.
+const QUOTED_LEAD = /["“”'`|>]\s*$/;
+const MARKUP_LEAD = /^\s*(?:#+|[>|*-]|\d+\.)\s/;
+
+/**
+ * `{ stableCode, index, lead }` when `text` is a failure note, else null.
+ * `index` is where "Error code" begins, `lead` the text before it.
+ */
+export function matchFailureNote(text) {
+  const raw = String(text ?? '').trim();
+  if (!raw) return null;
+  const match = CODE_PATTERN.exec(raw);
+  if (!match) return null;
+  const lead = raw.slice(0, match.index);
+  if (lead.length > FAILURE_NOTE_LEAD_MAX || /[\r\n]/.test(lead)) return null;
+  if (QUOTED_LEAD.test(lead) || MARKUP_LEAD.test(lead)) return null;
+  return { stableCode: match[1].toLowerCase(), index: match.index, lead };
+}
+
+export function isFailureNoteText(text) {
+  return matchFailureNote(text) !== null;
+}

package/shared/provider-routing.mjs

@@ -11,7 +11,9 @@
  */
 export const LEGACY_RELAY_PROVIDER_TYPES = Object.freeze(['github', 'openai']);
 
-export const SESSION_WORKER_PROVIDER_TYPES = Object.freeze(['claude', 'cursor', 'grok']);
+// `claude-cloud` is its own provider, never an alias of `claude`: its worker
+// drives a session in Anthropic's cloud and spawns no CLI.
+export const SESSION_WORKER_PROVIDER_TYPES = Object.freeze(['claude', 'cursor', 'grok', 'claude-cloud']);
 
 export function isLegacyRelayProviderType(value) {
   const normalized = String(value || '').trim().toLowerCase();
@@ -23,7 +25,7 @@ export function isSessionWorkerProviderType(value) {
   return SESSION_WORKER_PROVIDER_TYPES.includes(String(value || '').trim().toLowerCase());
 }
 
-/** `'claude', 'cursor', 'grok'` — for interpolation into SQL NOT IN (...) lists. */
+/** `'claude', 'cursor', 'grok', 'claude-cloud'` — for interpolation into SQL NOT IN (...) lists. */
 export function sessionWorkerProviderSqlList() {
   return SESSION_WORKER_PROVIDER_TYPES.map((provider) => `'${provider}'`).join(', ');
 }

package/shared/question-wait.mjs

@@ -0,0 +1,108 @@
+// Waiting for the answer to a question card, and creating the card, through
+// a relay that is briefly not there.
+//
+// A card may be open for hours and is polled every 1.5 s. One poll that failed
+// — the relay restarting, a reset connection, a 502 from a proxy in front of
+// it — used to end the wait with an error, and the callers turn an error into
+// an answer: "continue with your best judgement" for a question, a rejection
+// for an approval. The card itself stayed open, so the user later answered a
+// question nobody was waiting on any more. The relay keeps its cards across a
+// restart; the wait only has to outlast it.
+
+import { QUESTION_TIMEOUT_CONTINUATION_TEXT } from './question-timeout.mjs';
+import { isRelayUnreachableError, isTransientRelayError } from './worker-runtime/relay-errors.mjs';
+
+const DEFAULT_POLL_MS = 1500;
+/** The spacing between polls grows to this while the relay does not answer. */
+const MAX_OUTAGE_POLL_MS = 10_000;
+/** Attempts to create a card while the relay refuses connections (~16 s). */
+const DEFAULT_CREATE_RETRY_DELAYS_MS = Object.freeze([500, 1_000, 2_000, 4_000, 8_000]);
+
+function sleepDefault(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Create a question card. Retried only while the relay refuses the
+ * connection: any other failure may have created the card, and a second
+ * request would put a second one in front of the user.
+ */
+export async function createRelayQuestion({
+  api, payload, sleep = sleepDefault, retryDelaysMs = DEFAULT_CREATE_RETRY_DELAYS_MS, signal = null, dbg = () => {},
+} = {}) {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      const created = await api('POST', '/api/relay-question', payload);
+      const questionId = created?.question?.id;
+      if (!questionId) throw new Error('Relay question could not be created');
+      return questionId;
+    } catch (error) {
+      if (!isRelayUnreachableError(error) || attempt >= retryDelaysMs.length || signal?.aborted) throw error;
+      dbg('relay unreachable while creating a question; trying again', error?.message || String(error));
+      await sleep(retryDelaysMs[attempt]);
+    }
+  }
+}
+
+/**
+ * Poll a card until it is answered, times out, is cancelled, or `signal`
+ * aborts the wait. Resolves `{ answer, structuredAnswer, timedOut, aborted? }`.
+ * Rejects only on the relay's own refusal (a 4xx, a card that does not exist).
+ */
+export async function waitForRelayQuestion({
+  api,
+  questionId,
+  deadlineMs,
+  pollMs = DEFAULT_POLL_MS,
+  sleep = sleepDefault,
+  signal = null,
+  trimAnswer = true,
+  now = Date.now,
+  dbg = () => {},
+} = {}) {
+  const started = now();
+  const expired = { answer: QUESTION_TIMEOUT_CONTINUATION_TEXT, structuredAnswer: null, timedOut: true };
+  let failedPolls = 0;
+  while (true) {
+    if (signal?.aborted) {
+      await api('POST', `/api/relay-question/${questionId}/timeout`, {}).catch(() => {});
+      return { ...expired, aborted: true };
+    }
+    let question = null;
+    let outage = null;
+    try {
+      ({ question } = await api('GET', `/api/relay-question/${questionId}`));
+      if (!question) throw Object.assign(new Error('Relay question missing'), { status: 404 });
+    } catch (error) {
+      if (!isTransientRelayError(error)) throw error;
+      outage = error;
+    }
+    if (outage) {
+      failedPolls += 1;
+      if (failedPolls === 1) dbg('relay did not answer the question poll; the card stays open', questionId, outage?.message || String(outage));
+    } else {
+      if (failedPolls) dbg('relay answers the question poll again', questionId, `after ${failedPolls} failed poll(s)`);
+      failedPolls = 0;
+      if (question.status === 'answered') {
+        const answer = String(question.answer || '');
+        return {
+          answer: trimAnswer ? answer.trim() : answer,
+          // The validated structured submission, when the card carried a
+          // `requestedSchema` and the relay stored one. Null otherwise — flat
+          // consumers read `answer` and never see a shape change.
+          structuredAnswer: question.structuredAnswer && typeof question.structuredAnswer === 'object'
+            && !Array.isArray(question.structuredAnswer)
+            ? question.structuredAnswer
+            : null,
+          timedOut: false,
+        };
+      }
+      if (question.status === 'timed_out' || question.status === 'cancelled') return { ...expired };
+    }
+    if (now() - started >= deadlineMs) {
+      await api('POST', `/api/relay-question/${questionId}/timeout`, {}).catch(() => {});
+      return { ...expired };
+    }
+    await sleep(failedPolls ? Math.min(MAX_OUTAGE_POLL_MS, pollMs * 2 ** Math.min(failedPolls, 6)) : pollMs);
+  }
+}

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.
@@ -54,10 +60,13 @@ export const REMOTE_RELAY_ACTION_PERMISSION = Object.freeze({
 // the calling session runs in ask or plan mode.
 export const REMOTE_RELAY_WRITE_ACTIONS = Object.freeze(['send', 'create_session', 'answer_question', 'stop', 'archive']);
 
+// The write actions that carry an agent's words to another relay's agent.
+export const REMOTE_RELAY_PROMPT_ACTIONS = Object.freeze(['send', 'create_session', 'answer_question']);
+
 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,
@@ -78,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,
@@ -87,7 +105,12 @@ export const REMOTE_RELAY_LIMITS = Object.freeze({
   maxCharsMax: 50000,
   perMessageChars: 4000,
   textMax: 100000,
+  // Only toward a relay the user did not unlock and that is not the one the
+  // prompt came from: a third relay.
   hopLimit: 2,
+  // Prompts a conversation's agent may send to other relays' agents without a
+  // message from the user in between, before the user is asked.
+  agentPromptsBeforeAsking: 30,
   callsPerMinute: 60,
   writesPerMinute: 10,
   healthIntervalMs: 60_000,
@@ -111,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_',
@@ -123,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
@@ -134,20 +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. Start with {action:"list_relays"}. A relay stays '
-  + 'locked until the user mentions it in this conversation (for example @name); a '
+  '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.';
@@ -158,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',
@@ -201,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],
@@ -247,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(', ')}`);
@@ -271,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();
@@ -338,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);
@@ -351,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 };
@@ -373,6 +506,10 @@ export function isRemoteRelayWriteAction(action) {
   return REMOTE_RELAY_WRITE_ACTIONS.includes(action);
 }
 
+export function isRemoteRelayPromptAction(action) {
+  return REMOTE_RELAY_PROMPT_ACTIONS.includes(action);
+}
+
 // ─── Approval cards ──────────────────────────────────────────────────────────
 
 // The Allow / Deny card a relay puts on its own turn before a write action on
@@ -403,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;
@@ -416,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;
 }
 
@@ -429,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}"`);