@oar-sh/oar 0.9.3 → 0.9.4

package/server/services/host-suspend-service.mjs

@@ -0,0 +1,254 @@
+'use strict';
+
+/**
+ * Deferred host suspend: a "💤 Suspend host" request is queued and fulfilled
+ * only once nothing is running any more — no queued/processing turn, no live
+ * background task, no open CI run of a watched workspace — for a sustained
+ * idle window. Idle at request time means a short countdown instead, so the
+ * banner still gives the user a moment to cancel.
+ *
+ * Everything lives in memory: a relay restart drops the request (dispose()
+ * reports it so the caller can push a notice). The service is pure
+ * orchestration; the activity collector, the suspend command and the timers
+ * are injected so the state machine is unit-testable with fake clocks.
+ */
+
+export const HOST_SUSPEND_IDLE_WINDOW_MS = 2 * 60 * 1000;
+export const HOST_SUSPEND_IDLE_COUNTDOWN_MS = 30 * 1000;
+const DEFAULT_POLL_MS = 1000;
+
+export const HOST_SUSPEND_STATUSES = Object.freeze(['idle', 'queued', 'countdown', 'suspending']);
+
+function clampText(value, max, fallback) {
+  const text = String(value ?? '').trim().slice(0, max);
+  return text || fallback;
+}
+
+/**
+ * Normalise a blocker so the client can render it without guessing. Blockers
+ * with the same `kind` and `detail` are treated as identical when deciding
+ * whether the state changed.
+ */
+export function normalizeHostActivityBlocker(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const kind = String(raw.kind || '').trim();
+  if (!kind) return null;
+  const count = Number(raw.count);
+  return {
+    kind,
+    conversationId: raw.conversationId ? String(raw.conversationId) : null,
+    title: raw.title ? String(raw.title).slice(0, 160) : null,
+    count: Number.isFinite(count) && count > 0 ? Math.trunc(count) : null,
+    detail: String(raw.detail || '').slice(0, 400),
+  };
+}
+
+export function blockersFromActivity(activity) {
+  const list = Array.isArray(activity?.blockers) ? activity.blockers : Array.isArray(activity) ? activity : [];
+  return list.map(normalizeHostActivityBlocker).filter(Boolean);
+}
+
+export function createHostSuspendService({
+  collectActivity,
+  runSuspend,
+  onStateChange = null,
+  onSuspended = null,
+  onDropped = null,
+  logger = console,
+  now = () => Date.now(),
+  setIntervalImpl = setInterval,
+  clearIntervalImpl = clearInterval,
+  pollMs = DEFAULT_POLL_MS,
+  idleWindowMs = HOST_SUSPEND_IDLE_WINDOW_MS,
+  idleCountdownMs = HOST_SUSPEND_IDLE_COUNTDOWN_MS,
+} = {}) {
+  if (typeof collectActivity !== 'function') throw new Error('collectActivity is required');
+  if (typeof runSuspend !== 'function') throw new Error('runSuspend is required');
+
+  let status = 'idle';
+  let request = null;
+  let blockers = [];
+  let idleSince = null;
+  let fireAt = null;
+  let everBlocked = false;
+  let checkedAt = null;
+  let lastError = null;
+  let pollTimer = null;
+  let lastEmittedKey = '';
+  let ticking = false;
+
+  function publicState() {
+    return {
+      status,
+      pending: status === 'queued' || status === 'countdown' || status === 'suspending',
+      reason: request?.reason || null,
+      requestedBy: request?.requestedBy || null,
+      requestedAt: request?.requestedAt || null,
+      idleSince: idleSince ? new Date(idleSince).toISOString() : null,
+      fireAt: fireAt ? new Date(fireAt).toISOString() : null,
+      idleWindowMs: everBlocked ? idleWindowMs : idleCountdownMs,
+      checkedAt: checkedAt ? new Date(checkedAt).toISOString() : null,
+      blockers: blockers.map((b) => ({ ...b })),
+      lastError,
+    };
+  }
+
+  function emit(force = false) {
+    const state = publicState();
+    // Countdowns tick on the client from fireAt; only real transitions go out.
+    const key = JSON.stringify([
+      state.status,
+      state.requestedAt,
+      state.fireAt,
+      state.blockers.map((b) => `${b.kind}|${b.conversationId}|${b.count}|${b.detail}`),
+      state.lastError,
+    ]);
+    if (!force && key === lastEmittedKey) return;
+    lastEmittedKey = key;
+    try { onStateChange?.(state); } catch (error) {
+      try { logger.warn?.(`[host-suspend] state listener failed: ${error?.message || error}`); } catch {}
+    }
+  }
+
+  function stopPolling() {
+    if (!pollTimer) return;
+    try { clearIntervalImpl(pollTimer); } catch {}
+    pollTimer = null;
+  }
+
+  function resetToIdle() {
+    status = 'idle';
+    request = null;
+    blockers = [];
+    idleSince = null;
+    fireAt = null;
+    everBlocked = false;
+    lastError = null;
+    stopPolling();
+  }
+
+  function collect() {
+    try {
+      const activity = collectActivity({ request: request ? { ...request } : null });
+      lastError = null;
+      return blockersFromActivity(activity);
+    } catch (error) {
+      // An unreadable activity picture must not sleep the box under running
+      // agents: report it as a blocker until the collector recovers.
+      lastError = String(error?.message || error || 'activity check failed').slice(0, 300);
+      return [{
+        kind: 'error',
+        conversationId: null,
+        title: null,
+        count: null,
+        detail: `Activity check failed: ${lastError}`,
+      }];
+    }
+  }
+
+  function evaluate() {
+    if (status !== 'queued' && status !== 'countdown') return;
+    const at = now();
+    checkedAt = at;
+    blockers = collect();
+    if (blockers.length) {
+      everBlocked = true;
+      idleSince = null;
+      fireAt = null;
+      status = 'queued';
+      emit();
+      return;
+    }
+    if (!idleSince) idleSince = at;
+    const windowMs = everBlocked ? idleWindowMs : idleCountdownMs;
+    fireAt = idleSince + windowMs;
+    status = 'countdown';
+    if (at >= fireAt) {
+      fire();
+      return;
+    }
+    emit();
+  }
+
+  function fire() {
+    status = 'suspending';
+    stopPolling();
+    const state = publicState();
+    emit(true);
+    try { logger.log?.(`[host-suspend] everything idle for ${Math.round((state.idleWindowMs || 0) / 1000)} s; suspending host (requested by ${state.requestedBy || 'unknown'})`); } catch {}
+    let result = null;
+    try {
+      result = runSuspend({ state });
+    } catch (error) {
+      lastError = String(error?.message || error || 'suspend failed').slice(0, 300);
+      try { logger.warn?.(`[host-suspend] suspend command failed: ${lastError}`); } catch {}
+    }
+    const failed = result && result.ok === false;
+    if (failed && !lastError) lastError = String(result.error || 'suspend failed').slice(0, 300);
+    const finalError = lastError;
+    resetToIdle();
+    lastError = finalError;
+    emit(true);
+    if (!finalError) {
+      try { onSuspended?.(state); } catch {}
+    }
+  }
+
+  function tick() {
+    if (ticking) return;
+    ticking = true;
+    try { evaluate(); } finally { ticking = false; }
+  }
+
+  function requestSuspend({ reason = 'manual-suspend', requestedBy = 'localhost-api' } = {}) {
+    if (status === 'suspending') return { accepted: false, state: publicState() };
+    if (status === 'queued' || status === 'countdown') {
+      return { accepted: false, alreadyPending: true, state: publicState() };
+    }
+    request = {
+      reason: clampText(reason, 140, 'manual-suspend'),
+      requestedBy: clampText(requestedBy, 80, 'localhost-api'),
+      requestedAt: new Date(now()).toISOString(),
+    };
+    everBlocked = false;
+    idleSince = null;
+    fireAt = null;
+    lastError = null;
+    status = 'queued';
+    evaluate();
+    if (status === 'queued' || status === 'countdown') {
+      pollTimer = setIntervalImpl(tick, pollMs);
+      pollTimer?.unref?.();
+    }
+    return { accepted: true, state: publicState() };
+  }
+
+  function cancel({ requestedBy = 'localhost-api' } = {}) {
+    if (status !== 'queued' && status !== 'countdown') {
+      return { cancelled: false, state: publicState() };
+    }
+    try { logger.log?.(`[host-suspend] queued suspend cancelled by ${clampText(requestedBy, 80, 'unknown')}`); } catch {}
+    resetToIdle();
+    emit(true);
+    return { cancelled: true, state: publicState() };
+  }
+
+  function dispose({ reason = 'shutdown' } = {}) {
+    const wasPending = status === 'queued' || status === 'countdown';
+    const state = publicState();
+    resetToIdle();
+    if (wasPending) {
+      try { logger.log?.(`[host-suspend] queued suspend dropped (${reason})`); } catch {}
+      try { onDropped?.(state, reason); } catch {}
+    }
+  }
+
+  return {
+    request: requestSuspend,
+    cancel,
+    getState: publicState,
+    /** Re-run the activity check now (used by the status/GET routes). */
+    refresh() { if (status === 'queued' || status === 'countdown') tick(); return publicState(); },
+    dispose,
+  };
+}

package/server/services/push-dispatch-service.mjs

@@ -10,7 +10,7 @@
  * reports outcomes through the status-events store instead.
  */
 
-export const PUSH_EVENT_TYPES = Object.freeze(['question', 'turnComplete', 'turnFailed', 'board', 'cliOffline']);
+export const PUSH_EVENT_TYPES = Object.freeze(['question', 'turnComplete', 'turnFailed', 'board', 'cliOffline', 'hostSuspend']);
 
 export const VAPID_PUBLIC_KEY_SETTING = 'push_vapid_public_key';
 export const VAPID_PRIVATE_KEY_SETTING = 'push_vapid_private_key';
@@ -34,8 +34,13 @@ const EVENT_LABELS = Object.freeze({
   turnFailed: { title: 'Turn failed', generic: 'The agent turn failed.' },
   board: { title: 'Plan ready for review', generic: 'The agent posted a board for review.' },
   cliOffline: { title: 'CLI offline', generic: 'The relay lost its connection to the CLI host.' },
+  hostSuspend: { title: 'Host suspend', generic: 'The queued host suspend changed state.' },
 });
 
+// System events carry their own body: no conversation text to preview, and
+// the body is the message itself regardless of the preview preference.
+const SYSTEM_BODY_TYPES = new Set(['hostSuspend']);
+
 function clampInt(value, min, max, fallback) {
   const numeric = Number(value);
   if (!Number.isFinite(numeric)) return fallback;
@@ -90,7 +95,9 @@ export function renderPushNotification(event, preferences) {
   let body = labels.generic;
   const text = String(event?.body || '').trim();
   // cliOffline has no conversation text to preview; the generic body is the message.
-  if (text && type !== 'cliOffline') {
+  if (text && SYSTEM_BODY_TYPES.has(type)) {
+    body = text.slice(0, MAX_FULL_PREVIEW_CHARS);
+  } else if (text && type !== 'cliOffline') {
     if (prefs.content.preview === 'full') {
       body = text.slice(0, MAX_FULL_PREVIEW_CHARS);
     } else if (prefs.content.preview === 'truncated') {
@@ -300,6 +307,23 @@ export function createPushDispatchService({
     } catch {}
   }
 
+  // A turn another relay's agent started (its user message carries `origin`)
+  // pushes no "reply ready" or "failed": that agent is the one waiting for the
+  // reply and reports back to the user itself (decision 22). Question pushes
+  // are unchanged. Prepared lazily: a schema without the column (before
+  // migration 0005) simply means "not an agent's turn".
+  let messageOriginStatement = null;
+  function turnStartedByRemoteAgent(sourceMessageId) {
+    const id = String(sourceMessageId || '').trim();
+    if (!id) return false;
+    try {
+      messageOriginStatement ??= db.prepare(`SELECT origin_json FROM messages WHERE id = ?`);
+      return String(messageOriginStatement.get(id)?.origin_json || '').trim() !== '';
+    } catch {
+      return false;
+    }
+  }
+
   async function sendToSubscription(row, event) {
     const preferences = normalizePushPreferences(parseJsonObject(row.preferences_json));
     const payload = renderPushNotification(event, preferences);
@@ -412,7 +436,10 @@ export function createPushDispatchService({
     });
   }
 
-  function notifyTurnComplete({ conversationId, messageId, text } = {}) {
+  // `messageId` is the reply; `sourceMessageId` the user message that started
+  // the turn.
+  function notifyTurnComplete({ conversationId, messageId, sourceMessageId, text } = {}) {
+    if (turnStartedByRemoteAgent(sourceMessageId)) return Promise.resolve({ outcome: 'remote-agent' });
     return dispatch({
       type: 'turnComplete',
       conversationId: conversationId || null,
@@ -421,7 +448,8 @@ export function createPushDispatchService({
     });
   }
 
-  function notifyTurnFailed({ conversationId, messageId, text } = {}) {
+  function notifyTurnFailed({ conversationId, messageId, sourceMessageId, text } = {}) {
+    if (turnStartedByRemoteAgent(sourceMessageId)) return Promise.resolve({ outcome: 'remote-agent' });
     return dispatch({
       type: 'turnFailed',
       conversationId: conversationId || null,
@@ -443,7 +471,12 @@ export function createPushDispatchService({
     return dispatch({ type: 'cliOffline' });
   }
 
+  function notifyHostSuspend({ body = null } = {}) {
+    return dispatch({ type: 'hostSuspend', body: body || null, data: { hostSuspendAt: Date.now() } });
+  }
+
   return {
+    notifyHostSuspend,
     listDevices,
     getDevice,
     upsertSubscription,

package/server/services/remote-relay-caller-context.mjs

@@ -0,0 +1,341 @@
+'use strict';
+
+import { randomUUID as nodeRandomUUID } from 'crypto';
+
+import {
+  REMOTE_RELAY_APPROVAL_SOURCE,
+  REMOTE_RELAY_ERROR_CODES,
+  REMOTE_RELAY_PROVIDERS,
+} from '../../shared/remote-relay-contract.mjs';
+import { DEFAULT_QUESTION_TIMEOUT_MS, questionExpiresAt } from '../../shared/question-timeout.mjs';
+import { createQuestionRepository } from '../repositories/question-repository.mjs';
+import { pickLiveTurnRowId } from './live-turn-picker.mjs';
+import { sanitizeRelayQuestionContext } from './relay-question-context.mjs';
+
+// The runtime side of the remote-relay dispatcher: who is calling (the
+// conversation, its current turn, provider, model, relay mode and hop count)
+// and the approval card that write actions need in ask/plan mode.
+//
+// A tool call arrives while the calling session's turn is processing, so the
+// turn is that conversation's live processing queue row. Its id is also the
+// id of the user message behind it (POST /api/message writes both with one
+// id), which is where an agent-sent prompt keeps its `origin` and hop count.
+//
+// A background continuation turn (queue kind 'continuation') has no user
+// message behind it; it continues work an earlier turn started, so it counts
+// the hops of the latest user message before it.
+//
+// The approval card is an ordinary relay question on that row, written the
+// way POST /api/relay-question writes one: same columns, same socket event and
+// push, so it renders like any ask_user card and the stale-recovery and turn
+// ceiling exemptions for a turn waiting on a question apply to it. Its context
+// source (REMOTE_RELAY_APPROVAL_SOURCE) keeps other relays' agents away from it.
+
+const LOG_PREFIX = '[remote-relays]';
+const APPROVAL_HEADER = 'Remote relay';
+const APPROVAL_ALLOW = 'Allow';
+const APPROVAL_DENY = 'Deny';
+const EXCERPT_MAX = 200;
+
+function toText(value) {
+  return String(value ?? '').trim();
+}
+
+function shortId(value) {
+  return toText(value).slice(0, 8) || '-';
+}
+
+function defaultNormalizeRelayMode(mode) {
+  return toText(mode).toLowerCase() || null;
+}
+
+function parseJson(value, fallback) {
+  if (!value) return fallback;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return fallback;
+  }
+}
+
+/** Enough of the runtime's formatQuestionRow for the card and the tests. */
+function defaultFormatQuestionRow(row) {
+  if (!row) return null;
+  const envelope = parseJson(row.request, null);
+  return {
+    id: row.id,
+    queueId: row.queue_id,
+    conversationId: row.conversation_id,
+    sdkSessionId: row.sdk_session_id || null,
+    messageId: row.message_id,
+    mode: row.relay_mode,
+    prompt: row.prompt,
+    choices: parseJson(row.choices, []),
+    context: envelope && typeof envelope === 'object' ? envelope.context || null : null,
+    allowFreeform: envelope?.allowFreeform ?? false,
+    status: row.status,
+    answer: row.answer || null,
+    createdAt: row.created_at,
+    answeredAt: row.answered_at || null,
+    expiresAt: row.expires_at,
+  };
+}
+
+function excerpt(value) {
+  const text = toText(value).replace(/\s+/g, ' ');
+  return text.length > EXCERPT_MAX ? `${text.slice(0, EXCERPT_MAX - 1)}…` : text;
+}
+
+const APPROVAL_VERBS = Object.freeze({
+  send: 'send a prompt',
+  create_session: 'start a new session',
+  answer_question: 'answer a question',
+  stop: 'stop the running turn',
+  archive: 'archive a session',
+});
+
+/**
+ * How the remote turn would run, as far as this relay knows it: the mode (the
+ * requested one, else the calling session's, which the dispatcher passes on),
+ * the provider a new session gets (requested, else the caller's), and the
+ * model and working directory when the agent asked for them.
+ */
+function describeRemoteTurn(action, args, caller) {
+  const parts = [];
+  const mode = toText(args.mode).toLowerCase() || toText(caller?.mode).toLowerCase();
+  if (mode) parts.push(`Mode: ${mode}`);
+  if (action === 'create_session') {
+    const requested = toText(args.provider).toLowerCase();
+    const callerProvider = toText(caller?.provider).toLowerCase();
+    const provider = requested || (REMOTE_RELAY_PROVIDERS.includes(callerProvider) ? callerProvider : 'github');
+    parts.push(`Provider: ${provider}`);
+  }
+  if (toText(args.model)) parts.push(`Model: ${excerpt(args.model)}`);
+  if (toText(args.cwd)) parts.push(`Folder: ${excerpt(args.cwd)}`);
+  return parts.join(' · ');
+}
+
+/**
+ * The card text: what the agent wants to do where, how the remote turn would
+ * run, then the prompt (or the answer) it wants to send, so the user decides
+ * on the actual words. `caller` is the calling session's context.
+ */
+export function formatRemoteRelayApprovalPrompt({ relay, action, args = {}, caller = null } = {}) {
+  const name = toText(relay?.name) || 'a remote relay';
+  const verb = APPROVAL_VERBS[action] || toText(action).replace(/_/g, ' ') || 'act';
+  const target = args.session ? ` (session ${shortId(args.session)})` : '';
+  const lines = [`Allow the agent to ${verb} on relay "${name}"${target}?`];
+  if (action === 'send' || action === 'create_session') {
+    const details = describeRemoteTurn(action, args, caller);
+    if (details) lines.push(details);
+    const text = excerpt(args.text);
+    if (text) lines.push(`“${text}”`);
+  } else if (action === 'answer_question') {
+    const answer = excerpt([...(Array.isArray(args.choices) ? args.choices : []), args.answer].filter(Boolean).join(', '));
+    if (answer) lines.push(`Answer: “${answer}”`);
+  }
+  return lines.join('\n\n');
+}
+
+export function createRemoteRelayCallerContext({
+  db,
+  repository,
+  questions = null,
+  resolveLiveTurnQueueRow = null,
+  formatQuestionRow = defaultFormatQuestionRow,
+  normalizeRelayMode = defaultNormalizeRelayMode,
+  defaultRelayMode = 'agent',
+  emit = () => {},
+  notifyQuestion = () => {},
+  uuid = nodeRandomUUID,
+  now = () => new Date(),
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  logger = console,
+  questionPollMs = 1000,
+  questionTimeoutMs = DEFAULT_QUESTION_TIMEOUT_MS,
+} = {}) {
+  const questionStatements = questions || createQuestionRepository(db);
+  const getConversation = db.prepare(`SELECT id, title, preferred_relay_mode, preferred_model FROM conversations WHERE id = ?`);
+  const getRuntimeSession = db.prepare(`SELECT provider_type, provider_model, model FROM runtime_sessions WHERE conversation_id = ?`);
+  const listProcessingRows = db.prepare(`
+    SELECT id, kind, relay_mode, model, attempt_id, owner_sdk_session_id, timestamp, processing_at
+    FROM queue
+    WHERE conversation_id = ? AND status = 'processing'
+    ORDER BY COALESCE(processing_at, timestamp) ASC
+  `);
+  const getQueueRow = db.prepare(`SELECT * FROM queue WHERE id = ?`);
+  const getLatestUserMessage = db.prepare(`
+    SELECT id FROM messages WHERE conversation_id = ? AND role = 'user' ORDER BY timestamp DESC LIMIT 1
+  `);
+  const getLatestUserMessageAtOrBefore = db.prepare(`
+    SELECT id FROM messages WHERE conversation_id = ? AND role = 'user' AND timestamp <= ? ORDER BY timestamp DESC LIMIT 1
+  `);
+
+  function normalizeMode(mode) {
+    return normalizeRelayMode(mode) || defaultRelayMode;
+  }
+
+  /** The live turn: the runtime's own picker when given, else the same rule. */
+  function liveTurnRow(conversationId, rows) {
+    if (!rows.length) return null;
+    if (typeof resolveLiveTurnQueueRow === 'function') {
+      const live = resolveLiveTurnQueueRow(conversationId);
+      const match = live && rows.find((row) => row.id === live.id);
+      if (match) return match;
+    }
+    if (rows.length === 1) return rows[0];
+    const liveId = pickLiveTurnRowId(rows.map((row) => {
+      const output = questionStatements.getLastOutputAtByQueueMessage?.get({ id: row.id }) || null;
+      return {
+        id: String(row.id),
+        lastOutputAtMs: Date.parse(String(output?.last_output_at || '')) || 0,
+        streamDone: Number(output?.stream_done || 0) === 1,
+        processingAtMs: Date.parse(String(row.processing_at || row.timestamp || '')) || 0,
+      };
+    }));
+    return rows.find((row) => row.id === liveId) || rows[0];
+  }
+
+  function originHops(messageId) {
+    const origin = messageId ? repository?.getMessageOrigin?.(messageId) : null;
+    const hops = Number(origin?.hops);
+    return Number.isInteger(hops) && hops >= 0 ? hops : 0;
+  }
+
+  /**
+   * A turn's hops: those of its own user message, or for a continuation row
+   * (no message of its own) those of the latest user message before it, the
+   * turn whose background work it continues.
+   */
+  function rowHops(conversationId, row) {
+    if (toText(row.kind).toLowerCase() !== 'continuation') return originHops(row.id);
+    const at = toText(row.timestamp) || toText(row.processing_at);
+    const message = at
+      ? getLatestUserMessageAtOrBefore.get(conversationId, at)
+      : getLatestUserMessage.get(conversationId);
+    return originHops(message?.id);
+  }
+
+  /**
+   * `{ conversationId, title, provider, model, mode, processingRowId,
+   * attemptId, userMessageId, hops }` for the conversation making the call.
+   * `hops` is how many relays the current turn's prompt already crossed: 0
+   * for a human's message. A steered message folded into the live turn is
+   * part of what the agent is acting on, so the highest count among the
+   * conversation's processing rows wins (a background continuation counts as
+   * the turn it continues); without a turn (an off-turn call) the latest user
+   * message decides.
+   */
+  function getCallerContext(conversationId) {
+    const id = toText(conversationId);
+    const conversation = getConversation.get(id) || null;
+    const runtime = getRuntimeSession.get(id) || null;
+    const rows = listProcessingRows.all(id);
+    const live = liveTurnRow(id, rows);
+    const hops = rows.length
+      ? Math.max(...rows.map((row) => rowHops(id, row)))
+      : originHops(getLatestUserMessage.get(id)?.id);
+    return {
+      conversationId: id,
+      title: toText(conversation?.title),
+      provider: toText(runtime?.provider_type).toLowerCase() || 'github',
+      model: toText(live?.model) || toText(runtime?.provider_model) || toText(runtime?.model) || toText(conversation?.preferred_model) || '',
+      mode: normalizeMode(live?.relay_mode || conversation?.preferred_relay_mode),
+      processingRowId: live?.id || null,
+      attemptId: toText(live?.attempt_id) || null,
+      userMessageId: live?.id || null,
+      hops,
+    };
+  }
+
+  function formatQuestion(questionId) {
+    return formatQuestionRow(questionStatements.getQuestion.get(questionId));
+  }
+
+  function withdraw(questionId) {
+    try {
+      questionStatements.timeoutQuestion.run(questionId);
+      emit('relay_question_updated', { question: formatQuestion(questionId) });
+    } catch {}
+  }
+
+  /**
+   * Puts an Allow / Deny card on the calling turn and waits for the user.
+   * Resolves `{ approved:true }`, or `{ approved:false, code?, error? }`:
+   * denied, timed out, cancelled with the turn, or no turn to ask on (fails
+   * closed with REMOTE_RELAY_NO_ACTIVE_TURN). Waits as long as the question
+   * lives (8 h by default); `signal` withdraws the card early.
+   */
+  async function requestApproval({ conversationId, callerContext, relay, action, args = {}, signal } = {}) {
+    const rowId = toText(callerContext?.processingRowId);
+    const row = rowId ? getQueueRow.get(rowId) : null;
+    if (!row || row.status !== 'processing') {
+      return {
+        approved: false,
+        code: REMOTE_RELAY_ERROR_CODES.noTurn,
+        error: 'This write action needs the user\'s approval, but the conversation has no running turn to ask on.',
+      };
+    }
+
+    const createdAt = now().toISOString();
+    const questionId = String(uuid());
+    const relayMode = normalizeMode(row.relay_mode);
+    const prompt = formatRemoteRelayApprovalPrompt({ relay, action, args, caller: callerContext });
+    const context = sanitizeRelayQuestionContext({
+      source: REMOTE_RELAY_APPROVAL_SOURCE,
+      rationale: `Write actions on other relays need approval in ${relayMode} mode.`,
+      queueMessageId: row.id,
+      conversationId: toText(conversationId) || row.conversation_id,
+      relayMode,
+      header: APPROVAL_HEADER,
+    }, { normalizeRelayMode: normalizeMode, defaultRelayMode });
+    questionStatements.insertQuestion.run(
+      questionId,
+      row.id,
+      toText(conversationId) || row.conversation_id,
+      row.id,
+      relayMode,
+      prompt,
+      JSON.stringify([APPROVAL_ALLOW, APPROVAL_DENY]),
+      JSON.stringify({ request: null, context, allowFreeform: false }),
+      null,
+      toText(row.owner_sdk_session_id) || null,
+      null,
+      null,
+      null,
+      createdAt,
+      questionExpiresAt(createdAt, questionTimeoutMs),
+      toText(row.attempt_id) || null,
+    );
+    const question = formatQuestion(questionId);
+    try {
+      logger?.log?.(`${LOG_PREFIX} approval ${shortId(questionId)} conv=${shortId(row.conversation_id)} ${action} ${toText(relay?.name) || '-'}`);
+    } catch {}
+    try { emit('relay_question', { question }); } catch {}
+    try { void notifyQuestion(question); } catch {}
+
+    for (;;) {
+      const current = questionStatements.getQuestion.get(questionId);
+      if (!current) return { approved: false, error: 'The approval question was removed.' };
+      if (current.status === 'answered') {
+        const approved = toText(current.answer).toLowerCase() === APPROVAL_ALLOW.toLowerCase();
+        return approved ? { approved: true } : { approved: false };
+      }
+      if (current.status !== 'pending') {
+        return {
+          approved: false,
+          error: current.status === 'timed_out'
+            ? 'The approval question timed out without an answer.'
+            : 'The approval question was cancelled (the turn ended).',
+        };
+      }
+      if (signal?.aborted) {
+        withdraw(questionId);
+        return { approved: false, error: 'The tool call was abandoned before the user answered.' };
+      }
+      await sleep(questionPollMs);
+    }
+  }
+
+  return { getCallerContext, requestApproval };
+}