@oar-sh/oar 0.9.3 → 0.9.4

package/server/claude-worker/claude-session-process.mjs

@@ -35,6 +35,7 @@ import {
   isStaleAttemptError,
 } from './claude-turn-publisher.mjs';
 import { createAskUserBridge } from '../../shared/ask-user-bridge.mjs';
+import { createRemoteRelayToolGate } from '../../shared/remote-relay-tool-core.mjs';
 import { buildRelayStopFailure } from '../../shared/relay-stop-failure.mjs';
 import { STEER_FOLDED_TEXT, STEER_STOPPED_TEXT } from '../../shared/steer-settle-markers.mjs';
 import { stripSteerNote, withSteerNoteContent } from '../../shared/steer-note.mjs';
@@ -336,6 +337,34 @@ function isTaskNotificationReplay(sdkMessage) {
   return text !== null && text.trimStart().startsWith(TASK_NOTIFICATION_TAG_PREFIX);
 }
 
+/**
+ * The CLI's own record of a command that ran locally, replayed on the stream
+ * as a user-role message. The one the relay causes is the model switch:
+ * `set_model` on a conversation another model already answered writes the
+ * "/model" breadcrumbs into the transcript and replays the
+ * `<local-command-stdout>Set model to …` one (`isReplay: true`, string
+ * content, no `origin`) BEFORE it answers the control request — read in the
+ * CLI binaries 2.1.261 to 2.1.283. A session that was never answered gets no
+ * breadcrumb, which is why a probe on a fresh session only ever shows the
+ * re-init. Only the two output tags count, and only on a replay the CLI wrote
+ * itself (no origin, not inside a subagent): output is never a prompt, so it
+ * never opens a turn. A `<command-name>` record is left alone on purpose: it
+ * heads prompt-type slash commands and skills, which do open one.
+ */
+const LOCAL_COMMAND_OUTPUT_TAG_PREFIXES = Object.freeze([
+  '<local-command-stdout>',
+  '<local-command-stderr>',
+]);
+
+function isLocalCommandReplay(sdkMessage) {
+  if (sdkMessage?.isReplay !== true) return false;
+  if (sdkMessage.origin || sdkMessage.parent_tool_use_id) return false;
+  const text = firstTextBlock(sdkMessage);
+  if (text === null) return false;
+  const trimmed = text.trimStart();
+  return LOCAL_COMMAND_OUTPUT_TAG_PREFIXES.some((prefix) => trimmed.startsWith(prefix));
+}
+
 /**
  * Whether a turn the CLI opened by itself may be the compaction re-opening a
  * delivered turn, rather than something else the CLI decided to say.
@@ -484,6 +513,9 @@ export function createClaudeSessionRunner({
   // the socket link: a hold withdraws the relay's readiness, and its end
   // re-arms it at once so a held message steers into the resumed turn.
   onDeliveryReadinessChange = () => {},
+  // Whether CLI processes carry the relay's `remote_relay` tool
+  // (shared/remote-relay-tool-core.mjs). Default: ask the relay.
+  remoteRelayToolGate = null,
   dbg = () => {},
 } = {}) {
   const publisher = createClaudeTurnPublisher({
@@ -491,6 +523,13 @@ export function createClaudeSessionRunner({
     dbg,
     takeWorkflowRuns: () => drainSettledWorkflowRuns(),
   });
+  // `remote_relay` is registered only while this relay has paired remotes.
+  // Asked once when the worker starts, and again whenever a CLI process winds
+  // down, so a remote paired later reaches the next process. A cold spawn
+  // waits for the pending answer (handlePendingPayload): the tool list is
+  // fixed per process, and the first delivery can beat the startup GET.
+  const remoteRelayGate = remoteRelayToolGate || createRemoteRelayToolGate({ api });
+  void remoteRelayGate.refresh();
   const resolveWorkflowSessionDir = resolveWorkflowSessionDirImpl || createDefaultWorkflowSessionDirResolver();
   let claudeNativeSessionId = '';
   let proc = null;
@@ -1060,6 +1099,18 @@ export function createClaudeSessionRunner({
     if (openingText !== null) {
       const matched = proc.pendingDelivered.findIndex((entry) => entry.expectedText === openingText);
       if (matched >= 0) return attachDeliveredContext(matched);
+      // The CLI's record of a local command is not a turn, and no traffic
+      // follows it. Read as a self-opened boundary, the "/model" breadcrumb a
+      // setModel leaves stayed armed through the push that followed: the
+      // delivered message's answer opened a continuation row, and its own row
+      // sat unattached, holding every later message out until the watchdog
+      // failed it or the session was killed (seen live 2026-09-27; the
+      // re-init handling alone cannot cover it). Checked after the match, so
+      // a user who sends such a text still gets their turn.
+      if (isLocalCommandReplay(sdkMessage)) {
+        dbg('local command replay ignored as a turn boundary');
+        return null;
+      }
       // A compaction just replayed the conversation: the CLI re-opens the turn
       // with its own summary message ("This session is being continued…"),
       // whose text matches no delivered entry, and then answers the delivered
@@ -2672,6 +2723,8 @@ export function createClaudeSessionRunner({
 
   async function cleanupProcess(processRef, streamError) {
     const wasCurrent = proc === processRef;
+    // The next spawn reads the registration decision; refresh it now.
+    if (wasCurrent) void remoteRelayGate.refresh();
     stopLifecycleTimer(processRef);
     if (processRef.taskPublishTimer) {
       clearTimeout(processRef.taskPublishTimer);
@@ -2903,6 +2956,7 @@ export function createClaudeSessionRunner({
         || sdkSessionId
         || '',
       ),
+      remoteRelayTool: remoteRelayGate.isEnabled(),
       dbg,
     });
     processRef.lifecycleTimer = setInterval(() => evaluateLifecycle(), lifecyclePollMs);
@@ -2940,18 +2994,10 @@ export function createClaudeSessionRunner({
     // A mode change that would alter the spawn-time system prompt append gets
     // a fresh process — but only when nothing lives in the old one.
     if (modeAppendClass(relayMode) !== proc.appendClass && !hasLiveWork() && !proc.liveTasks.size) {
-      const previous = proc;
       gracefulShutdown('mode-change');
-      await Promise.race([
-        previous.consumer,
-        new Promise((resolve) => setTimeout(resolve, 10_000)),
-      ]);
-      if (proc === previous) {
-        // The drain timed out: force the old CLI down so it cannot keep
-        // streaming next to the replacement the caller is about to spawn.
-        try { previous.turn.close?.(); } catch {}
-        proc = null;
-      }
+      // A drain that times out forces the old CLI down so it cannot keep
+      // streaming next to the replacement the caller is about to spawn.
+      await drainClosingProcess(10_000);
       return null;
     }
 
@@ -3173,6 +3219,25 @@ export function createClaudeSessionRunner({
     return { turnActive, canSteer, holdReason, messageId, supported: true };
   }
 
+  /**
+   * A closing process drains on its own; wait (bounded) so two CLIs never
+   * share the native session transcript, then make sure it is gone.
+   */
+  async function drainClosingProcess(timeoutMs = 15_000) {
+    const previous = proc;
+    if (!previous) return;
+    let timer = null;
+    await Promise.race([
+      previous.consumer,
+      new Promise((resolve) => { timer = setTimeout(resolve, timeoutMs); }),
+    ]);
+    clearTimeout(timer);
+    if (proc === previous) {
+      try { previous.turn.close?.(); } catch {}
+      proc = null;
+    }
+  }
+
   async function handlePendingPayload(pending) {
     const message = pending?.message || null;
     if (!message) return false;
@@ -3204,20 +3269,22 @@ export function createClaudeSessionRunner({
         await adaptProcess(message);
       }
       if (!proc || proc.closing || proc.aborted) {
-        // A closing process drains on its own; wait so two CLIs never share
-        // the native session transcript.
-        const previous = proc;
-        if (previous) {
-          await Promise.race([
-            previous.consumer,
-            new Promise((resolve) => setTimeout(resolve, 15_000)),
-          ]);
-          if (proc === previous) {
-            try { previous.turn.close?.(); } catch {}
-            proc = null;
-          }
-        }
-        spawnProcess(message);
+        // Awaited only when there is one: a cold spawn with the decision
+        // already in pushes synchronously.
+        if (proc) await drainClosingProcess();
+        // The tool set is fixed per CLI process: let the remote_relay
+        // decision settle first. The worker's first delivery can arrive
+        // before its startup GET has answered (seen live: 180 ms after the
+        // spawn). ready() never rejects and is bounded by the gate's timeout.
+        if (!remoteRelayGate.isSettled?.()) await remoteRelayGate.ready();
+        // Another delivery spawned while this one waited: join that process
+        // like any delivery (between turns: adapt; mid-turn: steer below).
+        if (proc && !proc.closing && !proc.aborted && !proc.activeCtx) await adaptProcess(message);
+        // What it joined may be gone by now: that adapt can recycle the
+        // process (a mode change), and a process can wind down under any of
+        // these waits. Only a live one takes the push below.
+        if (proc && (proc.closing || proc.aborted)) await drainClosingProcess();
+        if (!proc) spawnProcess(message);
         // A cold start is the one moment a turn can sit silent for many
         // seconds (transcript load + first request); say so instead of
         // showing bare dots. Posted once here — not in spawnProcess — so a

package/server/claude-worker/sdk-message-normalizer.mjs

@@ -1,5 +1,6 @@
 import { capThought } from '../../shared/thought-cap.mjs';
 import { shouldEmitStreamUpdate } from '../../shared/stream-emit-gating.mjs';
+import { isRemoteRelayToolName, remoteRelayActivitySummary } from '../../shared/remote-relay-tool-core.mjs';
 
 const MAX_TOOL_DETAIL_LENGTH = 140;
 const REDACTED_THINKING_PLACEHOLDER = '[Reasoning redacted by the model provider]';
@@ -89,6 +90,12 @@ export function isSubagentToolName(name) {
 
 export function summarizeToolInput(toolName, input) {
   if (!input || typeof input !== 'object') return '';
+  // `mcp__relay__remote_relay` reads as what it does on which relay
+  // (`send → linux-test session 01234567: “…”`), not as its first argument.
+  if (isRemoteRelayToolName(toolName)) {
+    const summary = remoteRelayActivitySummary(input);
+    if (summary) return summary;
+  }
   const candidates = [
     input.command,
     input.file_path,

package/server/copilot-worker/copilot-remote-relay-tool.mjs

@@ -0,0 +1,59 @@
+// The relay's `remote_relay` tool for Copilot SDK sessions: a plain SDK
+// `Tool` (`{ name, description, parameters, skipPermission, handler }`) built
+// from the shared contract and forwarded through the shared tool core. The
+// module never imports the SDK; the session process hands the definition to
+// `SessionConfig.tools`.
+//
+// `skipPermission`: the relay does the approving. A write action in ask or
+// plan mode raises its own question card server-side, so a runtime permission
+// prompt on top would ask the user twice for one action.
+
+import {
+  REMOTE_RELAY_CALL_FAILED,
+  REMOTE_RELAY_TOOL_DESCRIPTION,
+  REMOTE_RELAY_TOOL_NAME,
+  cloneRemoteRelayToolInputSchema,
+  executeRemoteRelayTool,
+  formatRemoteRelayToolResult,
+} from '../../shared/remote-relay-tool-core.mjs';
+
+/**
+ * `runCall(fn)` wraps every execution — the session process uses it to hold
+ * its stall watchdog and idle shutdown while the relay waits on a remote turn.
+ * The handler never throws: a failure answers in-band as JSON the model can
+ * read, which is what the runtime passes back to it anyway.
+ *
+ * `getSignal(invocation)` is the call's cancellation. By default the SDK's
+ * own `invocation.signal`, which aborts when the runtime completes the
+ * request or the session disconnects; the session process adds the turn's
+ * Stop to it.
+ */
+export function buildCopilotRemoteRelayTool({
+  api,
+  getConversationId = () => '',
+  runCall = (fn) => fn(),
+  getSignal = (invocation) => invocation?.signal || null,
+  dbg = () => {},
+} = {}) {
+  return {
+    name: REMOTE_RELAY_TOOL_NAME,
+    description: REMOTE_RELAY_TOOL_DESCRIPTION,
+    parameters: cloneRemoteRelayToolInputSchema(),
+    skipPermission: true,
+    handler: async (args, invocation) => {
+      let result;
+      try {
+        result = await runCall(() => executeRemoteRelayTool(args, {
+          api,
+          conversationId: String(getConversationId() || ''),
+          signal: getSignal(invocation) || null,
+        }));
+      } catch (error) {
+        const message = error?.message || String(error);
+        dbg('remote_relay tool failed', message);
+        result = { ok: false, code: REMOTE_RELAY_CALL_FAILED, error: message };
+      }
+      return formatRemoteRelayToolResult(result);
+    },
+  };
+}

package/server/copilot-worker/copilot-sdk-event-normalizer.mjs

@@ -22,6 +22,11 @@
 import { sanitizeSubagentRunId } from '../../shared/subagent-run-id.mjs';
 import { capThought } from '../../shared/thought-cap.mjs';
 import { shouldEmitStreamUpdate } from '../../shared/stream-emit-gating.mjs';
+import {
+  REMOTE_RELAY_TOOL_NAME,
+  isRemoteRelayToolName,
+  remoteRelayActivitySummary,
+} from '../../shared/remote-relay-tool-core.mjs';
 
 const MAX_TOOL_DETAIL_LENGTH = 140;
 
@@ -78,8 +83,13 @@ export function summarizeToolInput(input) {
 }
 
 export function formatToolActivityText(toolName, input) {
-  const name = String(toolName || '').trim() || 'tool';
-  const summary = summarizeToolInput(input);
+  const rawName = String(toolName || '').trim() || 'tool';
+  // `remote_relay` (bare, or namespaced by an MCP server) reads as what it
+  // does on which relay (`send → linux-test session 01234567: “…”`); its
+  // arguments may arrive as a JSON string.
+  const isRemoteRelay = isRemoteRelayToolName(rawName);
+  const name = isRemoteRelay ? REMOTE_RELAY_TOOL_NAME : rawName;
+  const summary = (isRemoteRelay && remoteRelayActivitySummary(input)) || summarizeToolInput(input);
   return truncate(summary ? `Tool (${name}): ${summary}` : `Tool (${name})`);
 }
 

package/server/copilot-worker/copilot-sdk-session-process.mjs

@@ -84,6 +84,8 @@ import {
   isToolOverrideRejection,
   parseAskUserToolArguments,
 } from './copilot-ask-user-tool.mjs';
+import { buildCopilotRemoteRelayTool } from './copilot-remote-relay-tool.mjs';
+import { createRemoteRelayToolGate } from '../../shared/remote-relay-tool-core.mjs';
 import {
   EXIT_PLAN_BOARD_POSTED_FEEDBACK,
   EXIT_PLAN_NO_BOARD_FEEDBACK,
@@ -351,6 +353,9 @@ export function createCopilotSdkSessionRunner({
   // runtime's built-in one. A runtime that refuses the override falls back
   // to the built-in for the rest of this worker's life.
   relayAskUserTool = true,
+  // Whether sessions carry the relay's `remote_relay` tool
+  // (shared/remote-relay-tool-core.mjs). Default: ask the relay.
+  remoteRelayToolGate = null,
   taskRefreshMs = DEFAULT_TASK_REFRESH_MS,
   taskPublishThrottleMs = DEFAULT_TASK_PUBLISH_THROTTLE_MS,
   // Called with `true`/`false` whenever the runner flips between accepting
@@ -518,6 +523,17 @@ export function createCopilotSdkSessionRunner({
   // the human's eventual answer to a runtime whose row is already settled.
   // Same guard the Cursor worker's `hasPendingClientWork` provides.
   let pendingHumanRequests = 0;
+  // Running `remote_relay` calls. The runtime is just as silent while one
+  // runs (the relay may wait up to 600 s for a remote turn, plus an approval
+  // card), so they hold the stall watchdog and the idle shutdown too — but
+  // not steering: nobody is answering a card here.
+  let pendingRelayToolCalls = 0;
+  // `remote_relay` is registered only while this relay has paired remotes.
+  // Asked once when the worker starts; a session build waits for that first
+  // answer (it is async anyway), and every runtime stop asks again so the
+  // next session picks up a remote paired in the meantime.
+  const remoteRelayGate = remoteRelayToolGate || createRemoteRelayToolGate({ api });
+  void remoteRelayGate.refresh();
   // The `SessionConfig.provider` block this session was BUILT with, or null for
   // a hosted (`github`) session. Set by `buildSessionConfig` rather than by a
   // second throwaway resolve here, so "is this BYOK?" and "what did the runtime
@@ -1787,6 +1803,32 @@ export function createCopilotSdkSessionRunner({
     };
   }
 
+  /**
+   * The relay's `remote_relay` tool (copilot-remote-relay-tool.mjs). Every call
+   * is counted while it runs: the stall watchdog re-arms instead of failing the
+   * row, and the lifecycle keeps the runtime up. The clock restarts from the
+   * answer, like after a card. A call is cancelled by the runtime (its
+   * invocation signal) or by a Stop of the turn it started under.
+   */
+  function buildRemoteRelayTool() {
+    return buildCopilotRemoteRelayTool({
+      api,
+      getConversationId: () => activeTurn?.message?.conversationId || sdkSessionId || '',
+      getSignal: (invocation) => combineSignals(activeTurn?.remoteRelayStop?.signal, invocation?.signal),
+      runCall: async (fn) => {
+        pendingRelayToolCalls += 1;
+        try {
+          return await fn();
+        } finally {
+          pendingRelayToolCalls -= 1;
+          touch();
+          activeTurn?.armStall?.();
+        }
+      },
+      dbg,
+    });
+  }
+
   /** One signal that aborts when any of the given ones does (nulls ignored). */
   function combineSignals(...signals) {
     const live = signals.filter((signal) => signal && typeof signal.aborted === 'boolean');
@@ -1804,20 +1846,35 @@ export function createCopilotSdkSessionRunner({
    * Open a session, retrying once without the relay's `ask_user` when the
    * runtime refuses the override (an older runtime). The refusal is
    * remembered until the runtime is stopped — the next runtime (possibly
-   * auto-updated under the relay) gets another try.
+   * auto-updated under the relay) gets another try. Only the override goes:
+   * the relay's other tools (`remote_relay`) override nothing and stay.
    */
   async function openSession(open, config) {
     try {
       return await open(config);
     } catch (error) {
-      if (!config?.tools?.length || !isToolOverrideRejection(error) || isSessionNotFoundError(error)) throw error;
+      const tools = Array.isArray(config?.tools) ? config.tools : [];
+      const isAskUserOverride = (tool) => tool?.name === RELAY_ASK_USER_TOOL_NAME && tool?.overridesBuiltInTool === true;
+      if (!tools.some(isAskUserOverride) || !isToolOverrideRejection(error) || isSessionNotFoundError(error)) throw error;
       dbg('the runtime refused the relay ask_user override; using its built-in ask_user', error?.message || String(error));
       askUserOverrideRejected = true;
       const { tools: _tools, ...withoutTools } = config;
-      return open(withoutTools);
+      const kept = tools.filter((tool) => !isAskUserOverride(tool));
+      return open(kept.length ? { ...withoutTools, tools: kept } : withoutTools);
     }
   }
 
+  /** The relay's own session tools; each is added only when it applies. */
+  function relaySessionTools() {
+    return [
+      // The relay's `ask_user` (see copilot-ask-user-tool.mjs): the built-in's
+      // fields plus `multi_select`, so a model can declare a multi-select
+      // question instead of the relay guessing from its wording.
+      ...(relayAskUserTool && !askUserOverrideRejected ? [buildRelayAskUserTool()] : []),
+      ...(remoteRelayGate.isEnabled() ? [buildRemoteRelayTool()] : []),
+    ];
+  }
+
   function buildSessionConfig(model, reasoningEffort = null) {
     // Built once per session, not per request. Reads the mode off the LIVE turn
     // rather than closing over the one the session was built with, because one
@@ -1857,6 +1914,7 @@ export function createCopilotSdkSessionRunner({
     const provider = resolveProviderConfigImpl({ env, model: model || defaultModel, dbg });
     byokProvider = provider;
     const effort = normalizeRelayEffort(reasoningEffort);
+    const tools = relaySessionTools();
     return {
       // The relay session id IS the SDK session id, so the runtime's own state
       // under ~/.copilot/session-state/<id> is addressable by conversation and
@@ -1879,10 +1937,8 @@ export function createCopilotSdkSessionRunner({
       // The runtime's own defaults, pinned. See DEFAULT_INFINITE_SESSION_CONFIG.
       ...(infiniteSessionConfig ? { infiniteSessions: { ...infiniteSessionConfig } } : {}),
       onEvent: routeEvent,
-      // The relay's `ask_user` (see copilot-ask-user-tool.mjs): the built-in's
-      // fields plus `multi_select`, so a model can declare a multi-select
-      // question instead of the relay guessing from its wording.
-      ...(relayAskUserTool && !askUserOverrideRejected ? { tools: [buildRelayAskUserTool()] } : {}),
+      // The relay's own tools (`relaySessionTools`); omitted when there are none.
+      ...(tools.length ? { tools } : {}),
       // Permission policy follows the conversation's relay mode: agent and
       // autopilot auto-approve, plan denies non-read tools with feedback, and
       // ask asks the human through a relay question card. The handler reads the
@@ -2119,6 +2175,9 @@ export function createCopilotSdkSessionRunner({
   async function ensureSession(model, effort) {
     await ensureClient();
     if (!session) {
+      // The tool list is part of the session: wait for the worker's first
+      // registration answer (bounded, and it fails closed).
+      await remoteRelayGate.ready();
       const config = buildSessionConfig(model, effort);
       // Resume first, always. On a brand-new conversation this costs one
       // failed RPC; on every other path (worker restart, idle shutdown,
@@ -2185,6 +2244,8 @@ export function createCopilotSdkSessionRunner({
 
   async function stopRuntime(reason) {
     stopLifecycleTimer();
+    // The next session is built from a fresh registration answer.
+    void remoteRelayGate.refresh();
     try { detachRuntimeExit(); } catch { /* the observer is best-effort */ }
     detachRuntimeExit = () => {};
     const closingSession = session;
@@ -2320,7 +2381,9 @@ export function createCopilotSdkSessionRunner({
     // A pending question card means a human is mid-answer; tearing the runtime
     // down under them would discard the session the answer belongs to. A turn
     // that is still publishing counts too: it settled, but its rows are live.
-    if (disposed || activeTurn || publishingTurns.size > 0 || pendingHumanRequests > 0 || !client) return;
+    if (
+      disposed || activeTurn || publishingTurns.size > 0 || pendingHumanRequests > 0 || pendingRelayToolCalls > 0 || !client
+    ) return;
     if (!(idleShutdownMs > 0)) return;
     // Evaluated before the idle clock so the caps still expire on a runtime
     // that has been quiet far longer than the idle window.
@@ -2441,6 +2504,10 @@ export function createCopilotSdkSessionRunner({
       // Cancels any relay question card this turn is blocked on, so an aborted
       // turn does not leave a human answering into the void.
       abortController: new AbortController(),
+      // Cancels the `remote_relay` calls that started under this turn — on the
+      // user's Stop only. Not `abortController`: that one also fires when the
+      // turn settles normally, and a background agent's call must outlive that.
+      remoteRelayStop: new AbortController(),
       // Cards (questions, ask-mode approvals, elicitations) open on this
       // turn's row; `humansIdle` resolves when the last one is done. A turn
       // that settles with one still open publishes only after it (driveTurn).
@@ -2546,7 +2613,9 @@ export function createCopilotSdkSessionRunner({
         // A human staring at a question card is not a stalled runtime. Re-arm
         // rather than fail: the card has its own (much longer) timeout, and
         // failing the row here would settle it while the answer is still coming.
-        if (pendingHumanRequests > 0) {
+        // A remote_relay call waiting on another relay is the same kind of
+        // silence; the relay bounds that wait itself.
+        if (pendingHumanRequests > 0 || pendingRelayToolCalls > 0) {
           turn.armStall();
           return;
         }
@@ -3010,6 +3079,10 @@ export function createCopilotSdkSessionRunner({
     }
     turn.aborted = true;
     turn.abortedRowId = rowId;
+    // A pending `remote_relay` call ends now rather than when the runtime gets
+    // round to it: the relay drops the request, withdraws its approval card
+    // and stops waiting on the remote, and the watchdog hold is released.
+    turn.remoteRelayStop?.abort();
     // While `ensureSession` is still connecting there is no session to abort
     // and this would be a silent no-op; `runTurn` re-checks `turn.aborted`
     // once the session exists and settles there instead.
@@ -3937,6 +4010,7 @@ export function createCopilotSdkSessionRunner({
       continuationDueSince,
       compacting: isCompacting(),
       pendingHumanRequests,
+      pendingRelayToolCalls,
       sessionRpc: { ...sessionRpc },
       activeEntries: activeTurn
         ? activeTurn.entries.map((entry) => ({

package/server/cursor-worker/cursor-remote-relay-tool.mjs

@@ -0,0 +1,65 @@
+/**
+ * The relay's `remote_relay` custom tool for the Cursor worker. SDK-free: the
+ * turn runner passes the returned `{ description, inputSchema, execute }` into
+ * `customTools.remote_relay`, and every call goes through the shared tool core
+ * to the local relay endpoint.
+ *
+ * A call can legitimately run for many minutes (a remote turn plus an approval
+ * card), during which the SDK emits nothing. `onCallStart`/`onCallEnd` bracket
+ * every execution — errors included — so the runner can count it as pending
+ * client work and hold its stall watchdog, exactly as it does for ask_user.
+ *
+ * The SDK hands `execute` no cancellation of its own (the context is only
+ * `{ toolCallId }`), so `getAbortSignal` supplies the running turn's: a Stop
+ * aborts it, which cancels the pending relay request and ends the hold.
+ */
+
+import {
+  REMOTE_RELAY_CALL_FAILED,
+  REMOTE_RELAY_TOOL_DESCRIPTION,
+  REMOTE_RELAY_TOOL_NAME,
+  cloneRemoteRelayToolInputSchema,
+  executeRemoteRelayTool,
+  formatRemoteRelayToolResult,
+} from '../../shared/remote-relay-tool-core.mjs';
+
+export function createRemoteRelayTool({
+  api,
+  getConversationId = () => '',
+  onCallStart = () => {},
+  onCallEnd = () => {},
+  getAbortSignal = () => null,
+  dbg = () => {},
+} = {}) {
+  async function execute(args) {
+    onCallStart();
+    try {
+      const result = await executeRemoteRelayTool(args, {
+        api,
+        conversationId: String(getConversationId() || ''),
+        signal: getAbortSignal?.() || null,
+      });
+      return {
+        structuredContent: result,
+        content: [{ type: 'text', text: formatRemoteRelayToolResult(result) }],
+      };
+    } catch (error) {
+      // A tool exception must never kill the run.
+      const message = error?.message || String(error);
+      dbg('remote_relay tool failed', message);
+      const result = { ok: false, code: REMOTE_RELAY_CALL_FAILED, error: message };
+      return {
+        structuredContent: result,
+        content: [{ type: 'text', text: formatRemoteRelayToolResult(result) }],
+      };
+    } finally {
+      onCallEnd();
+    }
+  }
+  return {
+    name: REMOTE_RELAY_TOOL_NAME,
+    description: REMOTE_RELAY_TOOL_DESCRIPTION,
+    inputSchema: cloneRemoteRelayToolInputSchema(),
+    execute,
+  };
+}

package/server/cursor-worker/cursor-turn-runner.mjs

@@ -12,6 +12,8 @@ import {
 } from './cursor-sdk-adapter.mjs';
 import { createAskUserTool } from './cursor-ask-user-tool.mjs';
 import { createPreviewTool } from './cursor-preview-tool.mjs';
+import { createRemoteRelayTool } from './cursor-remote-relay-tool.mjs';
+import { createRemoteRelayToolGate } from '../../shared/remote-relay-tool-core.mjs';
 import {
   buildCursorSubagentAgents,
   cursorSubagentRosterFingerprint,
@@ -120,6 +122,9 @@ export function createCursorTurnRunner({
   resolveModelParamsImpl = resolveCursorReasoningParams,
   createNormalizerImpl = createSdkMessageNormalizer,
   buildUserMessageImpl = buildCursorUserMessage,
+  // Whether agent handles carry the relay's `remote_relay` tool
+  // (shared/remote-relay-tool-core.mjs). Default: ask the relay.
+  remoteRelayToolGate = null,
   dbg = () => {},
 } = {}) {
   // Unlike the Claude worker, the agent handle (and the custom tools bound
@@ -140,6 +145,9 @@ export function createCursorTurnRunner({
   // Open ask_user round-trips: the merged-stream stall watchdog defers while
   // a human is thinking about a question card.
   let pendingAskUserCalls = 0;
+  // Running remote_relay calls, same family: the relay may be waiting up to
+  // 600 s for a remote turn (plus an approval card) with no SDK traffic.
+  let pendingRemoteRelayCalls = 0;
   // Mirrors the Copilot extension's lastPromptedRelayMode: full mode
   // instructions ride on the first message of a mode and on mode changes only.
   let lastNudgedRelayMode = '';
@@ -188,6 +196,39 @@ export function createCursorTurnRunner({
       execute: previewTool.execute,
     },
   };
+  // `remote_relay` joins the set only while this relay has paired remotes.
+  // Asked once when the worker starts; the first handle waits for the answer
+  // (it is created asynchronously anyway), and every handle creation refreshes
+  // it so a later rebuild picks up a remote paired in the meantime.
+  const remoteRelayGate = remoteRelayToolGate || createRemoteRelayToolGate({ api });
+  void remoteRelayGate.refresh();
+  const remoteRelayTool = createRemoteRelayTool({
+    api,
+    getConversationId: () => activeMessage?.conversationId || sdkSessionId || '',
+    onCallStart: () => { pendingRemoteRelayCalls += 1; },
+    onCallEnd: () => { pendingRemoteRelayCalls -= 1; },
+    // The running turn's signal, read when the call starts: a Stop (or the
+    // auth retry burning a dead attempt) cancels the pending relay request.
+    // Between turns there is none — the last turn's may be aborted already.
+    getAbortSignal: () => (waitingForTurn ? currentAbortController?.signal || null : null),
+    dbg,
+  });
+
+  function customToolsForHandle() {
+    if (!remoteRelayGate.isEnabled()) return customTools;
+    return {
+      ...customTools,
+      [remoteRelayTool.name]: {
+        description: remoteRelayTool.description,
+        inputSchema: remoteRelayTool.inputSchema,
+        execute: remoteRelayTool.execute,
+      },
+    };
+  }
+
+  function hasPendingClientWork() {
+    return pendingAskUserCalls > 0 || pendingRemoteRelayCalls > 0;
+  }
 
   function getActiveQueueMessageId() {
     return waitingForTurn ? String(activeMessage?.id || '') : '';
@@ -262,7 +303,9 @@ export function createCursorTurnRunner({
     if (!agentHandle) {
       const durableId = String(message.cursorAgentId || '').trim() || cursorAgentId;
       const agents = buildCursorSubagentAgents(rosterModels);
-      const options = { apiKey, model, cwd, storeDir, sdkSessionId, customTools, agents, dbg };
+      await remoteRelayGate.ready();
+      const options = { apiKey, model, cwd, storeDir, sdkSessionId, customTools: customToolsForHandle(), agents, dbg };
+      void remoteRelayGate.refresh();
       try {
         agentHandle = await createAgentHandleImpl({ ...options, agentId: durableId });
       } catch (error) {
@@ -565,7 +608,7 @@ export function createCursorTurnRunner({
             // The SDK's documented recovery for a wedged persisted run —
             // armed by the second busy retry below.
             sendLocal: forceNextSend ? { force: true } : null,
-            hasPendingClientWork: () => pendingAskUserCalls > 0,
+            hasPendingClientWork,
             dbg,
           });
           forceNextSend = false;