@oar-sh/oar 0.9.0

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

@@ -0,0 +1,717 @@
+import { buildCursorUserMessage } from './cursor-attachments.mjs';
+import { buildCursorContextUsage } from './cursor-context-usage.mjs';
+import { createSdkMessageNormalizer } from './sdk-message-normalizer.mjs';
+import {
+  createCursorAgentHandle,
+  startCursorRun,
+  classifyCursorError,
+  isCursorAuthErrorMessage,
+  readModelContextWindow,
+  readAgentUsage,
+  resolveCursorReasoningParams,
+} from './cursor-sdk-adapter.mjs';
+import { createAskUserTool } from './cursor-ask-user-tool.mjs';
+import { createPreviewTool } from './cursor-preview-tool.mjs';
+import {
+  buildCursorSubagentAgents,
+  cursorSubagentRosterFingerprint,
+} from './cursor-subagent-roster.mjs';
+import { createAskUserBridge } from '../../shared/ask-user-bridge.mjs';
+import { EMPTY_TURN_COMPLETION_NOTE } from '../../shared/empty-turn-completion.mjs';
+import { resolveFallbackContextLimitTokens } from '../../shared/context-window-fallbacks.mjs';
+import { countPlanLikeLines } from '../../shared/plan-lines.mjs';
+
+// Stale-auth recovery budget per turn: expiry is routine on long-lived
+// handles, and one retry proved too small in practice (an orchestrator turn
+// re-authenticated once, then died terminally on the second expiry hours
+// later).
+const MAX_STALE_AUTH_RETRIES = 2;
+// Recreate a handle proactively once it has sat idle past this window; the
+// exchanged auth goes stale around the 4h mark while the API key stays valid.
+const STALE_HANDLE_IDLE_MS = 30 * 60_000;
+
+const PLAN_BOARD_ACTIONS = [
+  { id: 'autopilot', label: 'Implement in autopilot', mode: 'autopilot' },
+  { id: 'interactive', label: 'Stop here and prompt myself', mode: 'agent' },
+  { id: 'exit_only', label: 'Stop here', mode: 'agent' },
+];
+
+// The Cursor SDK's SendOptions carries only model/mode/callbacks — there is
+// no per-turn instruction channel — so ask/autopilot steering rides on the
+// user message text, mirroring the Copilot extension's prompt-context
+// injection. Injected only when the mode changes so the session transcript
+// is not spammed with repeated instructions.
+const MODE_NUDGES = {
+  ask: '[Relay mode: ask] Prioritize clarification questions before implementation work; '
+    + 'do not make broad assumptions when a question would materially change the result.',
+  autopilot: '[Relay mode: autopilot] Keep moving unless user input is truly blocking; avoid unnecessary questions.',
+};
+
+export function cursorModeNudge(relayMode, previousMode = '') {
+  const mode = String(relayMode || 'agent').trim().toLowerCase();
+  const previous = String(previousMode || '').trim().toLowerCase();
+  if (mode === previous) return '';
+  if (MODE_NUDGES[mode]) return MODE_NUDGES[mode];
+  // Leaving a nudged mode must cancel the standing instruction; before any
+  // nudge was sent there is nothing to cancel.
+  if (MODE_NUDGES[previous]) return `[Relay mode: ${mode}] Previous relay-mode instructions no longer apply.`;
+  return '';
+}
+
+// Cursor has no exit-plan tool, so the only board source is the plan-mode
+// text-shape fallback; the payload otherwise matches the Claude worker's.
+export function buildCursorPlanReadyBoardPayload({
+  message,
+  planText = '',
+  source = 'plan-mode-fallback',
+} = {}) {
+  const summary = String(planText || '').trim();
+  if (!summary) return null;
+  return {
+    queueId: message?.id,
+    messageId: message?.id,
+    conversationId: message?.conversationId,
+    mode: message?.relayMode || 'agent',
+    boardType: 'plan_ready',
+    title: 'Plan ready for review',
+    body: summary,
+    actions: PLAN_BOARD_ACTIONS,
+    recommendedAction: null,
+    context: {
+      source,
+      queueMessageId: message?.id || null,
+      conversationId: message?.conversationId || null,
+      relayMode: message?.relayMode || 'agent',
+    },
+  };
+}
+
+/**
+ * Execute one delivered relay turn against the Cursor SDK, streaming
+ * normalized events into the relay's activity channels and publishing the
+ * final response. Mirrors the Claude worker's `handlePendingPayload`
+ * contract (response / requeue / abort semantics).
+ */
+export function createCursorTurnRunner({
+  api,
+  sdkSessionId,
+  cwd,
+  defaultModel = '',
+  apiKey = '',
+  storeDir = '',
+  controlPoller,
+  createAgentHandleImpl = createCursorAgentHandle,
+  startCursorRunImpl = startCursorRun,
+  classifyErrorImpl = classifyCursorError,
+  readContextWindowImpl = readModelContextWindow,
+  readAgentUsageImpl = readAgentUsage,
+  resolveModelParamsImpl = resolveCursorReasoningParams,
+  createNormalizerImpl = createSdkMessageNormalizer,
+  buildUserMessageImpl = buildCursorUserMessage,
+  dbg = () => {},
+} = {}) {
+  // Unlike the Claude worker, the agent handle (and the custom tools bound
+  // into it) outlives a single turn, so the ask_user tool is built once here
+  // and reaches the active turn's state through these closures.
+  let agentHandle = null;
+  let cursorAgentId = '';
+  // The subagent roster is fixed when the handle is created, so the handle has
+  // to be rebuilt when the user's model selection changes mid-conversation.
+  let agentRosterFingerprint = null;
+  let activeMessage = null;
+  let waitingForTurn = false;
+  let currentAbortController = null;
+  // Handle staleness is the norm, not the exception (~4h idle expires the
+  // exchanged auth while the API key stays valid); recreate proactively after
+  // a long idle instead of paying a failed attempt to find out.
+  let agentHandleLastUsedAt = 0;
+  // Open ask_user round-trips: the merged-stream stall watchdog defers while
+  // a human is thinking about a question card.
+  let pendingAskUserCalls = 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 = '';
+
+  const bridge = createAskUserBridge({
+    api,
+    getActiveMessage: () => activeMessage,
+    sdkSessionId,
+    questionSource: 'ask_user',
+    questionRationale: 'Cursor requested clarification to continue this turn.',
+    dbg,
+  });
+  const askUserTool = createAskUserTool({
+    bridge,
+    getAbortSignal: () => currentAbortController?.signal || null,
+    dbg,
+  });
+  // Registered even when the relay's preview lane is disabled: the worker
+  // cannot see that configuration, and the API answers a disabled lane with a
+  // plain refusal the model can relay instead of a failed turn.
+  const previewTool = createPreviewTool({
+    api,
+    getConversationId: () => activeMessage?.conversationId || '',
+    dbg,
+  });
+  const customTools = {
+    ask_user: {
+      description: askUserTool.description,
+      inputSchema: askUserTool.inputSchema,
+      execute: async (...args) => {
+        pendingAskUserCalls += 1;
+        try {
+          return await askUserTool.execute(...args);
+        } finally {
+          pendingAskUserCalls -= 1;
+        }
+      },
+    },
+    [previewTool.name]: {
+      description: previewTool.description,
+      inputSchema: previewTool.inputSchema,
+      execute: previewTool.execute,
+    },
+  };
+
+  function getActiveQueueMessageId() {
+    return waitingForTurn ? String(activeMessage?.id || '') : '';
+  }
+
+  function isTurnActive() {
+    return waitingForTurn;
+  }
+
+  async function dispose() {
+    try {
+      await agentHandle?.close?.();
+    } catch (error) {
+      dbg('cursor agent close failed on dispose', error?.message || String(error));
+    }
+    agentHandle = null;
+    agentRosterFingerprint = null;
+  }
+
+  async function persistAgentId(message, agentId) {
+    const normalized = String(agentId || '').trim();
+    if (!normalized || normalized === cursorAgentId) return;
+    try {
+      await api('POST', '/api/cursor-agent-id', {
+        conversationId: message.conversationId,
+        cursorAgentId: normalized,
+      });
+      // Only cache after the server accepted it, so a failed persist is
+      // retried on the next turn — resume across worker restarts depends on
+      // the server-side copy.
+      cursorAgentId = normalized;
+    } catch (error) {
+      dbg('cursor agent id persist failed', error?.message || String(error));
+    }
+  }
+
+  async function ensureAgentHandle(message, model) {
+    const rosterModels = Array.isArray(message.cursorSubagentModels) ? message.cursorSubagentModels : [];
+    const rosterFingerprint = cursorSubagentRosterFingerprint(rosterModels);
+    if (
+      agentHandle
+      && agentHandleLastUsedAt
+      && Date.now() - agentHandleLastUsedAt > STALE_HANDLE_IDLE_MS
+    ) {
+      dbg('cursor agent handle idle past the staleness window, recreating proactively');
+      try {
+        await agentHandle.close?.();
+      } catch (error) {
+        dbg('cursor agent close failed on staleness refresh', error?.message || String(error));
+      }
+      agentHandle = null;
+    }
+    if (agentHandle && agentRosterFingerprint !== rosterFingerprint) {
+      // Closing drops only the local handle; the durable Cursor agent id is
+      // persisted, so the rebuild below resumes the same conversation with the
+      // new roster rather than starting a fresh one.
+      dbg('cursor subagent roster changed, rebuilding agent handle');
+      try {
+        await agentHandle.close?.();
+      } catch (error) {
+        dbg('cursor agent close failed on roster change', error?.message || String(error));
+      }
+      agentHandle = null;
+    }
+    if (!agentHandle) {
+      const durableId = String(message.cursorAgentId || '').trim() || cursorAgentId;
+      const agents = buildCursorSubagentAgents(rosterModels);
+      const options = { apiKey, model, cwd, storeDir, sdkSessionId, customTools, agents, dbg };
+      try {
+        agentHandle = await createAgentHandleImpl({ ...options, agentId: durableId });
+      } catch (error) {
+        if (!durableId) throw error;
+        // The durable agent may have been pruned server-side; fall back to a
+        // fresh agent rather than wedging the conversation.
+        dbg('cursor agent resume failed, creating fresh agent', error?.message || String(error));
+        agentHandle = await createAgentHandleImpl({ ...options, agentId: '' });
+      }
+    }
+    // Only recorded once a handle exists: a create that threw leaves the
+    // fingerprint stale, and the null handle makes the next turn rebuild.
+    agentRosterFingerprint = rosterFingerprint;
+    // Runs even when the handle is reused, so a persist that failed on an
+    // earlier turn is retried here.
+    if (agentHandle.agentId && agentHandle.agentId !== cursorAgentId) {
+      await persistAgentId(message, agentHandle.agentId);
+    }
+    return agentHandle;
+  }
+
+  async function postActivity(message, text, subagentRunId = null) {
+    if (!text) return;
+    await api('POST', '/api/activity', {
+      messageId: message.id,
+      conversationId: message.conversationId,
+      mode: message.relayMode || 'agent',
+      text,
+      ...(subagentRunId ? { subagentRunId } : {}),
+    }).catch(() => {});
+  }
+
+  async function dispatchAction(message, action, state, normalizer) {
+    const { channel, payload } = action;
+    if (channel === 'init') {
+      // The durable agent id is persisted at handle creation, not from init.
+      state.responseModel = payload.model || state.responseModel;
+      return;
+    }
+    if (channel === 'stream') {
+      // Only the main thread's text can stand in for the answer: subagent
+      // text landing here would publish a subagent's prose as the reply on
+      // the abort / error / no-result fallback paths below.
+      if (!payload.subagentRunId) state.lastStreamedText = payload.text;
+      await api('POST', '/api/stream', {
+        messageId: message.id,
+        conversationId: message.conversationId,
+        mode: message.relayMode || 'agent',
+        text: payload.text,
+        done: payload.done === true,
+        ...(payload.subagentRunId ? { subagentRunId: payload.subagentRunId } : {}),
+      }).catch(() => {});
+      return;
+    }
+    if (channel === 'thought') {
+      await api('POST', '/api/thought', {
+        messageId: message.id,
+        conversationId: message.conversationId,
+        mode: message.relayMode || 'agent',
+        reasoningId: payload.reasoningId,
+        text: payload.text,
+        done: payload.done === true,
+        ...(payload.subagentRunId ? { subagentRunId: payload.subagentRunId } : {}),
+      }).catch(() => {});
+      return;
+    }
+    if (channel === 'activity') {
+      await postActivity(message, payload.text, payload.subagentRunId);
+      return;
+    }
+    if (channel === 'subagent') {
+      await api('POST', '/api/subagent-run', {
+        messageId: message.id,
+        conversationId: message.conversationId,
+        subagentRunId: payload.subagentRunId,
+        parentSubagentId: payload.parentSubagentId || undefined,
+        displayName: payload.displayName || undefined,
+        status: payload.status,
+      }).catch(() => {});
+      return;
+    }
+    if (channel === 'result') {
+      state.result = payload;
+      state.lastUsage = payload.usage || state.lastUsage;
+      state.responseModel = state.responseModel || normalizer.model || '';
+    }
+  }
+
+  /**
+   * Ship the turn's token usage to the relay as a context-window breakdown.
+   * Advisory data: a failure here must not disturb the turn's response.
+   */
+  async function publishContextUsage(message, state, model, normalizer) {
+    // The result payload is the primary carrier, but a run can end without a
+    // terminal status message (or get aborted); the normalizer still saw the
+    // turn's usage events, so fall back to its copy rather than dropping them.
+    const usage = state.lastUsage || normalizer?.lastUsage || null;
+    if (!usage) return;
+    const usageModel = state.responseModel || model || '';
+    // Provider-advertised window first; the shared static table covers models
+    // whose `models.list()` entry has no `context` parameter, so the gauge is
+    // not totals-only for them.
+    const contextWindow = (await readContextWindowImpl({ apiKey, model: usageModel, dbg })
+      .catch(() => null))
+      ?? resolveFallbackContextLimitTokens(usageModel);
+    const built = buildCursorContextUsage({
+      usage,
+      model: usageModel,
+      contextWindow,
+      modelCallCount: normalizer?.modelCallCount,
+    });
+    if (!built) return;
+    await api('POST', '/api/cursor-context-usage', {
+      conversationId: message.conversationId,
+      sdkSessionId,
+      model: usageModel,
+      contextUsage: built.contextUsage,
+      modelUsage: built.modelUsage,
+    }).catch((error) => {
+      dbg('context usage publish failed', error?.message || String(error));
+    });
+  }
+
+  /**
+   * Report the agent's cumulative billed usage so the relay can book this
+   * turn's increase against the configured monthly allowance. The model is
+   * carried along because it is the only signal available for deciding which
+   * Cursor billing pool the spend belongs to — the SDK's per-run entries do
+   * not identify a model.
+   */
+  async function publishPlanUsage(message, state, model) {
+    if (!agentHandle?.agent || !agentHandle.agentId) return;
+    const usage = await readAgentUsageImpl({ agent: agentHandle.agent, dbg });
+    if (!usage) return;
+    await api('POST', '/api/cursor-plan-usage', {
+      conversationId: message.conversationId,
+      agentId: agentHandle.agentId,
+      model: state.responseModel || model || '',
+      // Lets the ledger tell a brand-new agent (book its lifetime — it IS
+      // this conversation) from one resumed without a checkpoint (seed the
+      // baseline; booking would dump historic spend into today's cycle).
+      agentCreated: agentHandle.created === true,
+      ...usage,
+      capturedAt: new Date().toISOString(),
+    }).catch((error) => {
+      dbg('plan usage publish failed', error?.message || String(error));
+    });
+  }
+
+  async function publishFinalStream(message, text) {
+    await api('POST', '/api/stream', {
+      messageId: message.id,
+      conversationId: message.conversationId,
+      mode: message.relayMode || 'agent',
+      text: String(text || ''),
+      done: true,
+    }).catch(() => {});
+  }
+
+  async function publishResponse(message, { text, model, terminalError = null, modelOrigin }) {
+    await api('POST', '/api/response', {
+      messageId: message.id,
+      conversationId: message.conversationId,
+      text: String(text || ''),
+      model: model || null,
+      modelOrigin: modelOrigin
+        || (String(message?.model || '').trim().toLowerCase() === 'auto' ? 'auto' : 'manual'),
+      ...(terminalError ? { terminalError } : {}),
+    }).catch(async () => {
+      await api('POST', '/api/requeue', { messageId: message.id }).catch(() => {});
+    });
+  }
+
+  async function runTurn(message) {
+    currentAbortController = new AbortController();
+    // `let`: the auth-retry path burns the old signal to unblock a parked
+    // ask_user wait, then arms a fresh one for the retry attempt.
+    let abortController = currentAbortController;
+    let normalizer = createNormalizerImpl();
+    const state = {
+      result: null,
+      lastStreamedText: '',
+      responseModel: '',
+      lastUsage: null,
+    };
+    let aborted = false;
+    let planBoardPosted = false;
+
+    // Per-message model wins so the composer can switch models between turns.
+    // Cursor model ids are unprefixed, so any non-auto value is accepted.
+    const requestedModel = String(message.model || '').trim();
+    const perTurnModel = requestedModel && requestedModel.toLowerCase() !== 'auto'
+      ? requestedModel
+      : '';
+    const model = perTurnModel
+      || String(message.providerModel || '').trim()
+      || defaultModel;
+
+    let turn = null;
+    // Started before agent/params setup: Agent.resume and the model-params
+    // lookup can take a while (or hang on a slow API), and the user's Stop
+    // must not be inert during that window. The whole setup lives inside the
+    // try so the finally can never leak a running poller.
+    const controlState = controlPoller?.start?.({
+      queueMessageId: message.id,
+      onAbortTurn: async () => {
+        aborted = true;
+        abortController.abort();
+        await turn?.cancel?.();
+      },
+    });
+
+    try {
+      await ensureAgentHandle(message, model);
+      const userMessage = buildUserMessageImpl(message);
+      const modeNudge = cursorModeNudge(message.relayMode, lastNudgedRelayMode);
+      if (modeNudge) userMessage.text = [modeNudge, userMessage.text].filter(Boolean).join('\n\n');
+      // Committed only once the send reached the transport (before the loop's
+      // break below) — a turn that dies before delivery must re-inject the
+      // nudge next time, or a mode change would be silently swallowed.
+      const pendingNudgedRelayMode = String(message.relayMode || 'agent').trim().toLowerCase();
+      // Per-turn like the model: the composer's effort maps onto Cursor model
+      // params, and null (no mapping / lookup failure) sends the model default.
+      const modelParams = await resolveModelParamsImpl({
+        apiKey,
+        model,
+        reasoningEffort: message.reasoningEffort || '',
+        dbg,
+      });
+
+      let busyRetries = 0;
+      let staleAuthRetries = 0;
+      let forceNextSend = false;
+
+      // A stale handle's auth expiry is the norm on long conversations
+      // (~4h idle), so the budget is 2 recreate-and-retry attempts with a
+      // short backoff before the failure goes terminal. Shared by the
+      // result-shaped and the thrown flavor of the same failure.
+      const recreateHandleForAuthRetry = async (flavor) => {
+        staleAuthRetries += 1;
+        dbg(`cursor auth error (${flavor}), recreating handle for retry ${staleAuthRetries}/${MAX_STALE_AUTH_RETRIES}`);
+        // A question card parked on the dead attempt would poll forever:
+        // burn the old signal to settle its wait, then arm a fresh one for
+        // the retry.
+        try { abortController.abort(); } catch {}
+        abortController = new AbortController();
+        currentAbortController = abortController;
+        // Subagent runs the failed attempt already announced can never be
+        // terminated by the fresh normalizer (it has no memory of them), so
+        // close their relay rows out now instead of leaving them 'running'.
+        for (const run of normalizer?.activeSubagentRuns?.() || []) {
+          await dispatchAction(message, {
+            channel: 'subagent',
+            payload: { ...run, parentSubagentId: null, status: 'failed' },
+          }, state, normalizer);
+        }
+        await agentHandle?.close?.();
+        agentHandle = null;
+        await ensureAgentHandle(message, model);
+        normalizer = createNormalizerImpl();
+        state.result = null;
+        state.lastStreamedText = '';
+        state.responseModel = '';
+        state.lastUsage = null;
+        // The failed attempt already streamed partial text to the relay;
+        // clear it and leave a trace so the retry doesn't read as the
+        // same turn silently rewriting itself.
+        await publishFinalStream(message, '');
+        await postActivity(message, 'Cursor session re-authenticated; retrying this message on a fresh agent handle.');
+        await new Promise((resolve) => setTimeout(resolve, 400 * staleAuthRetries));
+      };
+
+      while (true) {
+        try {
+          turn = startCursorRunImpl({
+            agent: agentHandle.agent,
+            message: userMessage,
+            model,
+            modelParams,
+            relayMode: message.relayMode,
+            abortSignal: abortController.signal,
+            // 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,
+            dbg,
+          });
+          forceNextSend = false;
+          for await (const event of turn) {
+            const actions = normalizer.normalize(event);
+            for (const action of actions) {
+              await dispatchAction(message, action, state, normalizer);
+            }
+          }
+          // A long-lived handle whose exchanged auth expired fails as a
+          // terminal ERROR result, not a thrown AuthenticationError, and the
+          // API key itself is usually still valid — so recreate the handle
+          // and retry. Exhausting the budget falls through to the isError
+          // publish below.
+          if (
+            staleAuthRetries < MAX_STALE_AUTH_RETRIES
+            && !aborted
+            && !abortController.signal.aborted
+            && state.result?.isError
+            // Classify on the SDK status message only: result.text is the
+            // model's own prose and mentioning "invalid api key" in an answer
+            // must never trigger a silent re-run.
+            && isCursorAuthErrorMessage(state.result.errorMessage)
+          ) {
+            await recreateHandleForAuthRetry('result');
+            continue;
+          }
+          // An abort can end the iterator cleanly before the send ever
+          // reached the transport; committing the nudge then would swallow a
+          // mode change. Re-injecting on a delivered-then-aborted turn is a
+          // harmless duplicate, so under-committing is the safe direction.
+          if (!aborted && !abortController.signal.aborted) {
+            lastNudgedRelayMode = pendingNudgedRelayMode;
+          }
+          break;
+        } catch (error) {
+          const classified = classifyErrorImpl(error);
+          // A stale handle whose previous run never settled server-side
+          // reports busy; one close-and-resume usually clears it, and the
+          // second attempt additionally expires the wedged persisted run via
+          // LocalSendOptions.force. A third busy is terminal.
+          if (busyRetries < 2 && classified.isBusy) {
+            busyRetries += 1;
+            forceNextSend = busyRetries >= 2;
+            dbg(`cursor agent busy, recreating handle for retry ${busyRetries}/2${forceNextSend ? ' (forcing run expiry)' : ''}`);
+            await agentHandle?.close?.();
+            agentHandle = null;
+            await ensureAgentHandle(message, model);
+            continue;
+          }
+          // The thrown flavor of the same stale-auth failure (an
+          // AuthenticationError from agent.send or from the handle rebuild)
+          // deserves the same recreate-and-retry as the result-shaped one.
+          if (
+            staleAuthRetries < MAX_STALE_AUTH_RETRIES
+            && !aborted
+            && !abortController.signal.aborted
+            && classified.isAuth
+          ) {
+            await recreateHandleForAuthRetry('thrown');
+            continue;
+          }
+          throw error;
+        }
+      }
+    } catch (error) {
+      if (aborted || abortController.signal.aborted) {
+        dbg('turn aborted', message.id);
+        await publishFinalStream(message, state.lastStreamedText);
+        return true;
+      }
+      throw error;
+    } finally {
+      controlPoller?.stop?.(controlState);
+      agentHandleLastUsedAt = Date.now();
+      // Runs on every exit path so usage captured before the turn went
+      // sideways still reaches the relay. `normalizer` is the live instance
+      // (the auth retry swaps it), so a discarded attempt's usage is not
+      // republished over the retry's.
+      await publishContextUsage(message, state, model, normalizer);
+      await publishPlanUsage(message, state, model);
+    }
+
+    if (aborted) {
+      await publishFinalStream(message, state.lastStreamedText);
+      return true;
+    }
+
+    const result = state.result;
+    const responseModel = state.responseModel || model || null;
+    if (!result) {
+      // The run ended without a terminal status message; surface what streamed.
+      const fallbackText = String(state.lastStreamedText || normalizer.finalStreamText() || '').trim();
+      if (fallbackText) {
+        await publishFinalStream(message, fallbackText);
+        await publishResponse(message, { text: fallbackText, model: responseModel });
+      } else {
+        await api('POST', '/api/requeue', { messageId: message.id }).catch(() => {});
+      }
+      return true;
+    }
+
+    if (result.isError) {
+      // Reaching here with an auth error means the fresh-handle retry above
+      // already failed too, so the key itself needs renewing. Only the SDK
+      // status message is auth-classified — result.text is model prose.
+      const authMessage = String(result.errorMessage || '').trim();
+      const isAuthFailure = isCursorAuthErrorMessage(authMessage);
+      const errorText = isAuthFailure
+        ? `System note: the Cursor runtime could not authenticate (${authMessage}). Set or renew the Cursor API key in provider settings, then retry.`
+        : result.text || `Cursor turn failed (${result.subtype || 'unknown error'}).`;
+      const code = isAuthFailure ? 'authentication_failed' : result.subtype || 'unknown';
+      await publishFinalStream(message, state.lastStreamedText);
+      await publishResponse(message, {
+        text: errorText,
+        model: responseModel,
+        terminalError: {
+          kind: 'cursor-turn-failed',
+          code,
+          stableCode: `cursor.${code}`,
+          message: errorText,
+          failedAt: new Date().toISOString(),
+          queueMessageId: String(message.id || '') || null,
+        },
+      });
+      return true;
+    }
+
+    const finalText = String(result.text || state.lastStreamedText || '').trim();
+    if (
+      !planBoardPosted
+      && String(message.relayMode || '').trim().toLowerCase() === 'plan'
+      && countPlanLikeLines(finalText) >= 2
+    ) {
+      const boardPayload = buildCursorPlanReadyBoardPayload({ message, planText: finalText });
+      if (boardPayload) {
+        await api('POST', '/api/relay-board', boardPayload).catch(() => {});
+        planBoardPosted = true;
+      }
+    }
+    // A terminal, non-error result carrying no prose is a COMPLETED turn — not
+    // a failed delivery — so it publishes rather than requeues. The requeue
+    // that used to live here re-ran a turn whose emptiness was deterministic,
+    // re-billing the provider and re-spawning its subagents on every attempt
+    // before the retry cap failed the message with a "Relay timeout" that
+    // misreported a turn which had succeeded.
+    const publishedText = finalText || EMPTY_TURN_COMPLETION_NOTE;
+    await publishFinalStream(message, publishedText);
+    await publishResponse(message, { text: publishedText, model: responseModel });
+    return true;
+  }
+
+  async function handlePendingPayload(pending) {
+    const message = pending?.message || null;
+    if (!message) return false;
+    activeMessage = message;
+    waitingForTurn = true;
+    try {
+      return await runTurn(message);
+    } catch (error) {
+      const classified = classifyErrorImpl(error);
+      dbg('cursor turn failed', message.id, classified.message);
+      await publishResponse(message, {
+        text: classified.isAuth
+          ? `System note: the Cursor runtime could not authenticate (${classified.message}). Set or renew the Cursor API key in provider settings, then retry.`
+          : `System note: the Cursor turn failed (${classified.message}).`,
+        model: null,
+        terminalError: {
+          kind: 'cursor-turn-failed',
+          code: classified.code,
+          stableCode: classified.stableCode,
+          message: classified.message,
+          failedAt: new Date().toISOString(),
+          queueMessageId: String(message.id || '') || null,
+        },
+      });
+      return true;
+    } finally {
+      waitingForTurn = false;
+      activeMessage = null;
+    }
+  }
+
+  return {
+    handlePendingPayload,
+    getActiveQueueMessageId,
+    isTurnActive,
+    dispose,
+  };
+}