@oar-sh/oar 0.9.3 → 0.9.5

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-session-worker.mjs

@@ -12,10 +12,15 @@ import {
 import { createApiClient } from '../../shared/worker-runtime/api-client.mjs';
 import { createWorkerWebSocketLink } from '../../shared/worker-runtime/worker-websocket-link.mjs';
 import { createHeartbeatController } from '../../shared/worker-runtime/heartbeat.mjs';
+import { installWorkerLogFile } from '../../shared/worker-runtime/worker-log-file.mjs';
 import { createControlPoller } from '../../shared/control-poller.mjs';
 import { installWorkerCrashGuard } from '../../shared/worker-crash-guard.mjs';
 import { createGrokTurnRunner } from './grok-turn-runner.mjs';
 
+// Windows console launch: the launcher names the worker log, this copies
+// stdout/stderr into it. A no-op wherever the launcher redirects instead.
+installWorkerLogFile();
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const HEARTBEAT_MS = 10_000;
 

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})`);