@oar-sh/oar 0.9.0

package/server/cursor-worker/cursor-ask-user-tool.mjs

@@ -0,0 +1,83 @@
+/**
+ * The relay's ask_user custom tool for the Cursor worker. SDK-free: the
+ * adapter passes the returned `{ description, inputSchema, execute }` into
+ * `customTools.ask_user`, and all relay traffic goes through the injected
+ * shared ask-user bridge.
+ */
+
+export const ASK_USER_TOOL_DESCRIPTION =
+  'Ask the user one or more clarifying questions and wait for their answers. '
+  + 'This is the ONLY way to ask the user anything: a question written as plain '
+  + 'reply text is NOT shown interactively and ends the turn unanswered. Call '
+  + 'this tool whenever user input would materially change the result, before '
+  + 'making assumptions. Provide 2-4 concise options per question; the user can '
+  + 'always answer in free text instead. This tool blocks until the user '
+  + 'responds; on timeout it returns an instruction to continue under the '
+  + 'current relay mode.';
+
+export const ASK_USER_INPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    questions: {
+      type: 'array',
+      minItems: 1,
+      maxItems: 4,
+      items: {
+        type: 'object',
+        properties: {
+          question: { type: 'string' },
+          header: { type: 'string' },
+          multiSelect: { type: 'boolean', default: false },
+          options: {
+            type: 'array',
+            minItems: 2,
+            maxItems: 6,
+            items: {
+              type: 'object',
+              properties: {
+                label: { type: 'string' },
+                description: { type: 'string' },
+              },
+              required: ['label'],
+            },
+          },
+        },
+        required: ['question', 'options'],
+      },
+    },
+  },
+  required: ['questions'],
+};
+
+export function createAskUserTool({ bridge, getAbortSignal, dbg = () => {} } = {}) {
+  async function execute(args) {
+    const signal = getAbortSignal?.();
+    try {
+      const { answers, timedOut } = await bridge.handleAskUserQuestion(args, { signal });
+      const entries = Object.entries(answers || {});
+      const text = entries.length
+        ? entries.map(([question, answer]) => `Q: ${question}\nA: ${answer}`).join('\n\n')
+        : 'No user response.';
+      return {
+        structuredContent: { answers, timedOut },
+        content: [{ type: 'text', text }],
+      };
+    } catch (error) {
+      // A tool exception must never kill the run.
+      const message = error?.message || String(error);
+      dbg('ask_user bridge failed', message);
+      return {
+        content: [{
+          type: 'text',
+          text: `ask_user failed: ${message}. Continue without user input.`,
+        }],
+      };
+    }
+  }
+  return {
+    name: 'ask_user',
+    description: ASK_USER_TOOL_DESCRIPTION,
+    inputSchema: ASK_USER_INPUT_SCHEMA,
+    execute,
+  };
+}

package/server/cursor-worker/cursor-attachments.mjs

@@ -0,0 +1,88 @@
+import fs from 'fs';
+
+// Very large base64 image payloads risk rejection; larger images fall back to
+// a path reference so the agent can read them from disk instead.
+export const MAX_INLINE_IMAGE_BYTES = 5 * 1024 * 1024;
+
+function isImageAttachment(att) {
+  return String(att?.type || '').toLowerCase().startsWith('image/');
+}
+
+function imageFromDataUrl(att) {
+  const dataUrl = String(att?.dataUrl || '').trim();
+  if (!dataUrl.startsWith('data:')) return null;
+  const match = dataUrl.match(/^data:([^;,]+);base64,(.+)$/i);
+  if (!match) return null;
+  const mimeType = String(match[1] || '').trim().toLowerCase();
+  const data = String(match[2] || '').trim();
+  if (!mimeType.startsWith('image/') || !data) return null;
+  return { data, mimeType };
+}
+
+/**
+ * Build the `{ text, images }` payload for `agent.send()` from a relay
+ * message. Mirrors the Claude worker's attachment handling: images small
+ * enough to embed become base64 `{ data, mimeType }` entries; everything else
+ * (non-images, oversized or unreadable images) becomes a prompt note line with
+ * the absolute path so the agent's file tools can open it directly.
+ *
+ * Text composition order: user text, note lines, server-provided
+ * `attachmentPromptContext`, joined by blank lines.
+ */
+export function buildCursorUserMessage(message, {
+  fsImpl = fs,
+  maxInlineImageBytes = MAX_INLINE_IMAGE_BYTES,
+} = {}) {
+  const text = String(message?.text || '').trim();
+  const input = Array.isArray(message?.attachments) ? message.attachments : [];
+  const images = [];
+  const noteLines = [];
+
+  for (const att of input) {
+    if (!att || typeof att !== 'object') continue;
+    const name = String(att.name || 'attachment').trim() || 'attachment';
+    const mime = String(att.type || 'application/octet-stream').trim() || 'application/octet-stream';
+    const filePath = String(att.path || '').trim();
+
+    if (isImageAttachment(att)) {
+      let embedded = false;
+      if (filePath && fsImpl.existsSync(filePath)) {
+        try {
+          const bytes = fsImpl.readFileSync(filePath);
+          if (Buffer.isBuffer(bytes) && bytes.length && bytes.length <= maxInlineImageBytes) {
+            images.push({
+              data: bytes.toString('base64'),
+              mimeType: mime.toLowerCase().startsWith('image/') ? mime.toLowerCase() : 'image/png',
+            });
+            embedded = true;
+          }
+        } catch {
+          embedded = false;
+        }
+      }
+      if (!embedded) {
+        const fromDataUrl = imageFromDataUrl(att);
+        if (fromDataUrl) {
+          images.push(fromDataUrl);
+          embedded = true;
+        }
+      }
+      if (embedded) {
+        noteLines.push(`Attached image "${name}" (${mime}) is embedded in this message.`);
+      } else if (filePath) {
+        noteLines.push(`Attached image "${name}" (${mime}): ${filePath}`);
+      }
+      continue;
+    }
+
+    if (filePath && fsImpl.existsSync(filePath)) {
+      noteLines.push(`Attached file "${name}" (${mime}): ${filePath}`);
+    }
+  }
+
+  const attachmentPromptContext = String(message?.attachmentPromptContext || '').trim();
+  const textParts = [text];
+  if (noteLines.length) textParts.push(noteLines.join('\n'));
+  if (attachmentPromptContext) textParts.push(attachmentPromptContext);
+  return { text: textParts.filter(Boolean).join('\n\n'), images };
+}

package/server/cursor-worker/cursor-context-usage.mjs

@@ -0,0 +1,85 @@
+/**
+ * Maps the Cursor SDK's TokenUsage onto the payload shape the relay already
+ * persists for Claude sessions, so `normalizeClaudeContextUsage` and
+ * `buildClaudeContextSnapshot` (server/services/claude-context-usage.mjs)
+ * render it unchanged.
+ *
+ * The Cursor SDK reports no per-category breakdown and no auto-compact
+ * settings, so `categories` is always empty and the skills/autoCompact keys
+ * are omitted entirely.
+ */
+
+// Percentages above this are impossible occupancy readings; the worker clamps
+// them so the stored blob never claims more than a full window.
+const MAX_PERCENT = 100;
+
+function tokenCount(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? Math.round(n) : null;
+}
+
+export function buildCursorContextUsage({
+  usage,
+  model = '',
+  contextWindow = null,
+  modelCallCount = 1,
+} = {}) {
+  if (!usage || typeof usage !== 'object') return null;
+
+  const inputTokens = tokenCount(usage.inputTokens);
+  const outputTokens = tokenCount(usage.outputTokens);
+  const cacheReadTokens = tokenCount(usage.cacheReadTokens);
+  const cacheWriteTokens = tokenCount(usage.cacheWriteTokens);
+  if (inputTokens === null && outputTokens === null
+    && cacheReadTokens === null && cacheWriteTokens === null) {
+    return null;
+  }
+
+  // The SDK's turn usage aggregates EVERY model call in the turn, and each
+  // call re-sends the whole context — so input + cache reads + cache writes is
+  // roughly `calls ×` the real occupancy (observed 10× the window on long
+  // agentic turns; the SDK's cumulative `totalTokens` is even further off and
+  // must not be used). Divide the prompt-side aggregate by the model-call
+  // count for a per-call average: an estimate that slightly undershoots the
+  // final call's context instead of pinning the gauge at 100%.
+  const calls = Math.max(1, Math.round(Number(modelCallCount) || 1));
+  const promptAggregate = (inputTokens || 0) + (cacheReadTokens || 0) + (cacheWriteTokens || 0);
+  const totalTokens = Math.round(promptAggregate / calls) + (outputTokens || 0);
+  const estimateKind = calls > 1 ? 'cursor-per-call-average' : null;
+  const maxTokens = (typeof contextWindow === 'number' && Number.isFinite(contextWindow)
+    && contextWindow > 0)
+    ? Math.round(contextWindow)
+    : null;
+
+  const contextUsage = {
+    model,
+    totalTokens,
+    ...(maxTokens !== null
+      ? {
+        maxTokens,
+        percentage: Math.min(MAX_PERCENT, Math.round((totalTokens / maxTokens) * 10000) / 100),
+      }
+      : {}),
+    ...(estimateKind ? { estimateKind } : {}),
+    categories: [],
+    apiUsage: {
+      input_tokens: inputTokens || 0,
+      output_tokens: outputTokens || 0,
+      cache_read_input_tokens: cacheReadTokens || 0,
+      cache_creation_input_tokens: cacheWriteTokens || 0,
+    },
+  };
+
+  const modelUsage = {
+    [model]: {
+      ...(maxTokens !== null ? { contextWindow: maxTokens } : {}),
+      inputTokens: inputTokens || 0,
+      outputTokens: outputTokens || 0,
+      cacheReadInputTokens: cacheReadTokens || 0,
+      cacheCreationInputTokens: cacheWriteTokens || 0,
+    },
+  };
+
+  return { contextUsage, modelUsage };
+}

package/server/cursor-worker/cursor-preview-tool.mjs

@@ -0,0 +1,44 @@
+/**
+ * The relay's preview custom tool for the Cursor worker. SDK-free: the adapter
+ * passes the returned `{ description, inputSchema, execute }` into
+ * `customTools.preview`, and every verb runs through the shared preview core
+ * against the worker's injected relay API helper.
+ */
+
+import {
+  PREVIEW_TOOL_DESCRIPTION,
+  PREVIEW_TOOL_INPUT_SCHEMA,
+  PREVIEW_TOOL_NAME,
+  executePreviewTool,
+} from '../../shared/preview-tool-core.mjs';
+
+export function createPreviewTool({ api, getConversationId = () => '', dbg = () => {} } = {}) {
+  async function execute(args) {
+    try {
+      const result = await executePreviewTool(args, {
+        api,
+        conversationId: String(getConversationId() || ''),
+      });
+      return {
+        structuredContent: result,
+        content: [{ type: 'text', text: JSON.stringify(result) }],
+      };
+    } catch (error) {
+      // A tool exception must never kill the run.
+      const message = error?.message || String(error);
+      dbg('preview tool failed', message);
+      return {
+        content: [{
+          type: 'text',
+          text: `preview failed: ${message}. Continue without publishing a preview.`,
+        }],
+      };
+    }
+  }
+  return {
+    name: PREVIEW_TOOL_NAME,
+    description: PREVIEW_TOOL_DESCRIPTION,
+    inputSchema: PREVIEW_TOOL_INPUT_SCHEMA,
+    execute,
+  };
+}