@oar-sh/oar 0.9.3 → 0.9.4

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

@@ -1,6 +1,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;
 const SUBAGENT_TOOL_NAMES = new Set(['task', 'agent']);
@@ -39,7 +44,27 @@ export function summarizeToolInput(toolName, input) {
   }
 }
 
+/**
+ * The relay's custom tools reach the stream as the SDK's generic MCP call
+ * (`name: 'mcp'`, args `{ providerIdentifier: 'custom-user-tools', toolName,
+ * args }`). `remote_relay` is shown as itself with the contract's one-line
+ * summary, so the transcript reads `Tool (remote_relay): send → …` like every
+ * other provider's; null for any other tool.
+ */
+function remoteRelayCallArgs(toolName, input) {
+  if (isRemoteRelayToolName(toolName)) return input || {};
+  if (String(toolName || '').trim().toLowerCase() !== 'mcp' || !input || typeof input !== 'object') return null;
+  return isRemoteRelayToolName(input.toolName) ? (input.args || {}) : null;
+}
+
 export function formatToolActivityText(toolName, input) {
+  const remoteArgs = remoteRelayCallArgs(toolName, input);
+  if (remoteArgs) {
+    const remoteSummary = remoteRelayActivitySummary(remoteArgs);
+    return truncate(remoteSummary
+      ? `Tool (${REMOTE_RELAY_TOOL_NAME}): ${remoteSummary}`
+      : `Tool (${REMOTE_RELAY_TOOL_NAME})`);
+  }
   const summary = summarizeToolInput(toolName, input);
   return truncate(summary ? `Tool (${toolName}): ${summary}` : `Tool (${toolName})`);
 }

package/server/db-schema.mjs

@@ -10,6 +10,7 @@
 import { rebuildRecentWorkspaceRootsTable } from './migrations/0002-recent-workspace-roots-path-key.mjs';
 import { ensurePushSubscriptionsTable } from './migrations/0003-push-subscriptions.mjs';
 import { migrateSteerSettleMarkers } from './migrations/0004-steer-settle-markers.mjs';
+import { migrateRemoteRelays } from './migrations/0005-remote-relays.mjs';
 import { migrateImageConversationSchema } from './repositories/image-conversation-repository.mjs';
 
 // Mirrors DEFAULT_RELAY_MODE in server-runtime.mjs; used only by the one-time
@@ -702,6 +703,13 @@ try {
 } catch (error) {
   console.warn(`[steering] migration 0004 failed; retrying on next boot: ${error?.message || error}`);
 }
+// Remote relays: additive columns and the unlock table. Readers tolerate their
+// absence, so a failure is logged and retried next boot like 0004.
+try {
+  migrateRemoteRelays(db);
+} catch (error) {
+  console.warn(`[remote-relays] migration 0005 failed; retrying on next boot: ${error?.message || error}`);
+}
 
 const runtimeSessionColumns = db.prepare(`PRAGMA table_info(runtime_sessions)`).all().map((c) => c.name);
 if (runtimeSessionColumns.length) {

package/server/grok-worker/acp-client.mjs

@@ -17,6 +17,40 @@ function whichCommand(command = 'grok') {
 // ceiling bounds a single prompt absolutely. Both are overridable per call.
 export const ACP_PROMPT_INACTIVITY_MS = 120_000;
 export const ACP_PROMPT_MAX_TURN_MS = 1_800_000;
+// How long the watchdog waits for its `holdStall` question before treating
+// the silence as a stall after all.
+export const ACP_HOLD_CHECK_TIMEOUT_MS = 10_000;
+
+/**
+ * An MCP server launch (`{ command, args, env }`, see
+ * server/mcp/oar-mcp-server.mjs `buildOarMcpServerLaunch`) in the ACP stdio
+ * shape `session/new` and `session/load` take: no `type` field (that marks the
+ * http/sse transports), `args` and `env` always present, `env` as a list of
+ * `{ name, value }` pairs.
+ */
+export function toAcpStdioMcpServer(launch, name = 'oar') {
+  const env = launch?.env && typeof launch.env === 'object' ? launch.env : {};
+  return {
+    name: String(name || '').trim() || 'oar',
+    command: String(launch?.command || ''),
+    args: Array.isArray(launch?.args) ? launch.args.map((arg) => String(arg)) : [],
+    env: Object.entries(env).map(([key, value]) => ({ name: key, value: String(value ?? '') })),
+  };
+}
+
+/**
+ * An AcpClient class whose sessions carry `mcpServers` unless the caller
+ * passes its own. Lets the turn runner hand the adapter (which builds the
+ * client and opens the session in one step) a client that already knows them.
+ */
+export function withAcpMcpServers(BaseClient, mcpServers = []) {
+  const servers = Array.isArray(mcpServers) ? mcpServers : [];
+  return class AcpClientWithMcpServers extends BaseClient {
+    constructor(opts = {}) {
+      super({ ...opts, mcpServers: Array.isArray(opts?.mcpServers) ? opts.mcpServers : servers });
+    }
+  };
+}
 
 /**
  * Pick the one-shot allow option from an ACP permission request. A blanket
@@ -47,10 +81,13 @@ export class AcpClient extends EventEmitter {
    * @param {string} [opts.cwd]
    * @param {NodeJS.ProcessEnv} [opts.env]
    * @param {boolean} [opts.alwaysApprove]
+   * @param {Array<object>} [opts.mcpServers] ACP McpServer entries every
+   *   session/new and session/load carries (see toAcpStdioMcpServer)
    * @param {typeof spawn} [opts.spawnImpl]
    */
   constructor(opts = {}) {
     super();
+    this.mcpServers = Array.isArray(opts.mcpServers) ? opts.mcpServers.map((server) => ({ ...server })) : [];
     this.command = whichCommand(opts.command || 'grok');
     this.args = Array.isArray(opts.args) ? [...opts.args] : ['agent', '--no-leader', 'stdio'];
     if (opts.alwaysApprove && !this.args.includes('--always-approve') && !this.args.includes('--yolo')) {
@@ -276,10 +313,12 @@ export class AcpClient extends EventEmitter {
     return this.initializeResult;
   }
 
+  // MCP servers are per session in ACP, and a loaded session does not keep the
+  // ones it was created with — both calls pass them.
   async sessionNew(cwd, extra = {}) {
     return this.request('session/new', {
       cwd,
-      mcpServers: [],
+      mcpServers: this.mcpServers,
       ...extra,
     });
   }
@@ -288,7 +327,7 @@ export class AcpClient extends EventEmitter {
     return this.request('session/load', {
       sessionId,
       cwd,
-      mcpServers: [],
+      mcpServers: this.mcpServers,
       ...extra,
     });
   }
@@ -305,8 +344,15 @@ export class AcpClient extends EventEmitter {
    * @param {string} sessionId
    * @param {Array} prompt content blocks
    * @param {(update: object) => void} [onUpdate]
+   * `holdStall` (async, optional) is asked once the inactivity window has run
+   * out: `true` re-arms the full window instead of failing the prompt. It is
+   * for work the agent is blocked on that this client cannot see — a
+   * remote_relay call the agent runs through its MCP server, which the relay
+   * reports as in flight. A question that fails or takes longer than
+   * `holdCheckTimeoutMs` counts as `false`.
+   *
    * @param {object} [extra] additional session/prompt params (e.g. `_meta`)
-   * @param {object} [watchdog] { inactivityMs, maxTurnMs, hasPendingWork }
+   * @param {object} [watchdog] { inactivityMs, maxTurnMs, hasPendingWork, holdStall, holdCheckTimeoutMs }
    */
   async sessionPrompt(sessionId, prompt, onUpdate, extra = {}, watchdog = {}) {
     const inactivityMs = Number(watchdog?.inactivityMs) > 0
@@ -322,6 +368,10 @@ export class AcpClient extends EventEmitter {
     const hasPendingWork = typeof watchdog?.hasPendingWork === 'function'
       ? watchdog.hasPendingWork
       : () => false;
+    const holdStall = typeof watchdog?.holdStall === 'function' ? watchdog.holdStall : null;
+    const holdCheckTimeoutMs = Number(watchdog?.holdCheckTimeoutMs) > 0
+      ? Number(watchdog.holdCheckTimeoutMs)
+      : ACP_HOLD_CHECK_TIMEOUT_MS;
     const handler = (msg) => {
       if (msg.method !== 'session/update') return;
       if (msg.params?.sessionId && msg.params.sessionId !== sessionId) return;
@@ -329,8 +379,40 @@ export class AcpClient extends EventEmitter {
     };
     this.on('notification', handler);
     let watchdogTimer = null;
+    let settled = false;
+    // A granted hold restarts the window without faking ACP traffic.
+    let heldAt = 0;
+    let holdCheck = null;
+    const quietSince = () => Math.max(this.lastActivityAt, heldAt);
     const startedAt = Date.now();
     const stallPromise = new Promise((_, reject) => {
+      const stall = () => {
+        if (settled) return;
+        try { this.sessionCancel(sessionId); } catch { /* ignore */ }
+        reject(new Error(`grok turn stalled: no ACP activity for ${Math.round(inactivityMs / 1000)}s`));
+      };
+      const askForHold = () => {
+        let timer = null;
+        holdCheck = Promise.race([
+          Promise.resolve().then(() => holdStall()),
+          new Promise((resolve) => {
+            timer = setTimeout(() => resolve(false), holdCheckTimeoutMs);
+            timer.unref?.();
+          }),
+        ])
+          .then((hold) => hold === true, () => false)
+          .then((hold) => {
+            if (timer) clearTimeout(timer);
+            holdCheck = null;
+            if (settled) return;
+            if (hold) {
+              heldAt = Date.now();
+              return;
+            }
+            // Traffic that arrived while the question ran re-armed it anyway.
+            if (Date.now() - quietSince() >= inactivityMs) stall();
+          });
+      };
       const pollMs = Math.max(250, Math.min(5000, Math.floor(inactivityMs / 4)));
       watchdogTimer = setInterval(() => {
         const now = Date.now();
@@ -340,10 +422,13 @@ export class AcpClient extends EventEmitter {
           return;
         }
         if (hasPendingWork()) return;
-        if (now - this.lastActivityAt >= inactivityMs) {
-          try { this.sessionCancel(sessionId); } catch { /* ignore */ }
-          reject(new Error(`grok turn stalled: no ACP activity for ${Math.round(inactivityMs / 1000)}s`));
+        if (now - quietSince() < inactivityMs) return;
+        if (!holdStall) {
+          stall();
+          return;
         }
+        // Before the abort: is the agent blocked on work only the relay sees?
+        if (!holdCheck) askForHold();
       }, pollMs);
       if (typeof watchdogTimer.unref === 'function') watchdogTimer.unref();
     });
@@ -360,6 +445,7 @@ export class AcpClient extends EventEmitter {
         stallPromise,
       ]);
     } finally {
+      settled = true;
       clearInterval(watchdogTimer);
       this.off('notification', handler);
     }

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

@@ -3,9 +3,12 @@ import {
   startGrokTurn,
   classifyGrokError,
 } from './grok-sdk-adapter.mjs';
+import { AcpClient, toAcpStdioMcpServer, withAcpMcpServers } from './acp-client.mjs';
 import { buildGrokContextUsage, resolveGrokContextWindow } from './grok-context-usage.mjs';
 import { extractGrokUsageFromPromptResult, normalizeGrokTurnUsage } from '../services/plan-usage-grok.mjs';
+import { OAR_MCP_SERVER_NAME, buildOarMcpServerLaunch, isOarMcpServerDisabled } from '../mcp/oar-mcp-server.mjs';
 import { createPreviewInstructionsProvider } from '../../shared/preview-instructions.mjs';
+import { fetchRemoteRelayInflight } from '../../shared/remote-relay-tool-core.mjs';
 import { renderMediaEmbedInstructionBlock } from '../../shared/media-embed-instructions.mjs';
 import { countPlanLikeLines } from '../../shared/plan-lines.mjs';
 import { EMPTY_TURN_COMPLETION_NOTE } from '../../shared/empty-turn-completion.mjs';
@@ -110,8 +113,30 @@ export function createGrokTurnRunner({
   startGrokTurnImpl = startGrokTurn,
   classifyErrorImpl = classifyGrokError,
   getPreviewInstructions = createPreviewInstructionsProvider({ api }),
+  env = process.env,
+  nodePath = process.execPath,
+  // The OAR MCP server launch (`{ command, args, env }`) every Grok session
+  // gets through ACP `mcpServers`; undefined builds the default for this
+  // worker's conversation, null leaves Grok without it.
+  oarMcpServer = undefined,
   dbg = () => {},
 } = {}) {
+  // The OAR MCP server gives Grok the relay's real tools — `preview`, and
+  // `remote_relay` when remotes are paired — bound to this conversation.
+  // `OAR_MCP_SERVER=0` is the operator's way back to the preview instruction
+  // block, should an agent build turn out to ignore ACP `mcpServers`.
+  const oarMcpLaunch = oarMcpServer !== undefined
+    ? (oarMcpServer || null)
+    : (() => {
+      if (isOarMcpServerDisabled(env)) return null;
+      try {
+        return buildOarMcpServerLaunch({ nodePath, conversationId: sdkSessionId, env });
+      } catch (error) {
+        dbg('oar mcp server unavailable', error?.message || String(error));
+        return null;
+      }
+    })();
+  const acpMcpServers = oarMcpLaunch ? [toAcpStdioMcpServer(oarMcpLaunch, OAR_MCP_SERVER_NAME)] : [];
   let agentHandle = null;
   let grokNativeSessionId = '';
   let activeMessage = null;
@@ -175,6 +200,12 @@ export function createGrokTurnRunner({
       alwaysApprove,
       nativeSessionId: resumeId,
       model,
+      // The adapter builds the ACP client and opens the session in one step,
+      // so the client it builds must already carry the MCP servers — for
+      // session/new and for session/load alike.
+      ...(acpMcpServers.length
+        ? { AcpClientImpl: withAcpMcpServers(AcpClient, acpMcpServers), mcpServers: acpMcpServers }
+        : {}),
       dbg,
     });
     if (agentHandle.sessionId) {
@@ -188,6 +219,20 @@ export function createGrokTurnRunner({
     return agentHandle;
   }
 
+  /**
+   * The inactivity hold. A remote_relay call runs inside the MCP server, which
+   * this worker cannot see: Grok just goes quiet for as long as the relay
+   * waits on the remote turn. Before the ACP watchdog calls that a stall, the
+   * relay is asked whether a call of this conversation is still in flight.
+   * Keyed by the MCP server's own conversation id, which is what its calls
+   * carry.
+   */
+  async function remoteRelayCallInFlight() {
+    const inflight = await fetchRemoteRelayInflight({ api, conversationId: sdkSessionId });
+    if (inflight > 0) dbg('remote_relay call in flight; holding the inactivity watchdog', String(inflight));
+    return inflight > 0;
+  }
+
   async function postActivity(message, text, subagentRunId = null) {
     if (!text) return;
     await api('POST', '/api/activity', {
@@ -369,7 +414,9 @@ export function createGrokTurnRunner({
     const modeNudge = grokModeNudge(message.relayMode, lastNudgedRelayMode);
     const userText = buildGrokUserText(message);
     // Advisory: a preview lookup that fails costs the guidance, never the turn.
-    const previewBlock = previewInstructionsSent
+    // With the OAR MCP server wired in, `preview` is a real tool and the HTTP
+    // instruction block (which says there is none) would contradict it.
+    const previewBlock = previewInstructionsSent || acpMcpServers.length
       ? ''
       : await Promise.resolve()
         .then(() => getPreviewInstructions?.())
@@ -378,6 +425,16 @@ export function createGrokTurnRunner({
     const promptText = [previewBlock, mediaBlock, modeNudge, userText].filter(Boolean).join('\n\n');
     const pendingNudgedRelayMode = String(message.relayMode || 'agent').trim().toLowerCase();
 
+    // The user's max-turn-duration setting overrides the worker-local
+    // absolute cap: "No limit" (0) must not be silently trimmed to the
+    // 30-minute default. The inactivity watchdog stays — it detects a dead
+    // transport, not a long turn — but asks the relay before it fires while
+    // Grok may be blocked on a remote_relay call.
+    const watchdog = {
+      ...(turnCeilingMs !== null ? { maxTurnMs: turnCeilingMs > 0 ? turnCeilingMs : 0 } : {}),
+      ...(acpMcpServers.length ? { holdStall: remoteRelayCallInFlight } : {}),
+    };
+
     let turn = null;
     let planBoardPosted = false;
     const controlState = controlPoller?.start?.({
@@ -399,13 +456,7 @@ export function createGrokTurnRunner({
             text: promptText,
             reasoningEffort: message.reasoningEffort || '',
             abortSignal: abortController.signal,
-            // The user's max-turn-duration setting overrides the worker-local
-            // absolute cap: "No limit" (0) must not be silently trimmed to
-            // the 30-minute default. The inactivity watchdog stays — it
-            // detects a dead transport, not a long turn.
-            watchdog: turnCeilingMs !== null
-              ? { maxTurnMs: turnCeilingMs > 0 ? turnCeilingMs : 0 }
-              : null,
+            watchdog: Object.keys(watchdog).length ? watchdog : null,
             dbg,
           });
           for await (const action of turn) {

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

@@ -4,6 +4,11 @@
  */
 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;
 const SUBAGENT_TOOL_NAMES = new Set(['task', 'agent', 'subagent']);
@@ -59,6 +64,14 @@ export function summarizeToolInput(input) {
 }
 
 export function formatToolActivityText(toolName, input, title = '') {
+  // The OAR MCP server's `remote_relay`, however the agent labels it (bare,
+  // or namespaced by the server), reads as what it does on which relay.
+  if (isRemoteRelayToolName(toolName) || isRemoteRelayToolName(title)) {
+    const remoteSummary = remoteRelayActivitySummary(input);
+    return truncate(remoteSummary
+      ? `Tool (${REMOTE_RELAY_TOOL_NAME}): ${remoteSummary}`
+      : `Tool (${REMOTE_RELAY_TOOL_NAME})`);
+  }
   const name = String(toolName || title || 'tool').trim() || 'tool';
   const summary = summarizeToolInput(input) || String(title || '').trim();
   return truncate(summary ? `Tool (${name}): ${summary}` : `Tool (${name})`);