@oar-sh/oar 0.9.0

package/shared/empty-turn-completion.mjs

@@ -0,0 +1,20 @@
+/**
+ * What a worker publishes when a turn ends terminally, without error, and
+ * without any assistant prose.
+ *
+ * That is a *completed* turn, not a failed delivery: the model can legitimately
+ * end a turn on tool activity alone ("do nothing else than spawn a subagent
+ * that returns OK" — conv `1e497a75`, where the Cursor SDK recorded
+ * `status: FINISHED, result: null`). Requeuing such a turn re-runs work that
+ * deterministically produces the same empty text, so every attempt re-bills the
+ * provider and re-spawns its subagents until the queue's retry cap fails the
+ * message with a "Relay timeout" that misreports a turn which actually
+ * succeeded.
+ *
+ * A note rather than an empty string because `/api/response` rejects an empty
+ * body (`shouldAcceptAssistantResponsePayload`), so publishing '' would leave
+ * the queue row stuck in `processing` — swapping one stall for another. Kept
+ * deliberately free of inference about *why* the model stayed silent; the
+ * activity and subagent bubbles already show what ran.
+ */
+export const EMPTY_TURN_COMPLETION_NOTE = 'System note: the turn completed without a text reply.';

package/shared/model-catalog-freshness.mjs

@@ -0,0 +1,11 @@
+export function latestModelCatalogRefresh(...timestamps) {
+  let latestMs = Number.NEGATIVE_INFINITY;
+  let latestValue = null;
+  for (const timestamp of timestamps) {
+    const parsed = Date.parse(timestamp || '');
+    if (!Number.isFinite(parsed) || parsed <= latestMs) continue;
+    latestMs = parsed;
+    latestValue = new Date(parsed).toISOString();
+  }
+  return latestValue;
+}

package/shared/model-descriptors.mjs

@@ -0,0 +1,118 @@
+import { isValidModelId, normalizeModelIdCandidate } from './model-id.mjs';
+
+// Keys that hold lists of sibling models in provider responses. The per-model
+// fallback search must not descend into them, or a model with no context limit
+// of its own would inherit a sibling's.
+const MODEL_CONTAINER_KEYS = ['data', 'models', 'list', 'available', 'items', 'entries', 'result', 'response'];
+
+export function normalizeContextLimitTokens(value) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric) || numeric <= 0) return null;
+  return Math.round(numeric);
+}
+
+function findContextLimitTokens(value) {
+  if (!value || typeof value !== 'object') return null;
+  const candidates = [
+    value.contextLimitTokens,
+    value.maxContextTokens,
+    value.contextWindow,
+    value.max_context_tokens,
+    value.tokenBudget,
+  ];
+  for (const candidate of candidates) {
+    const normalized = normalizeContextLimitTokens(candidate);
+    if (normalized !== null) return normalized;
+  }
+  for (const [key, nested] of Object.entries(value)) {
+    if (!nested || typeof nested !== 'object') continue;
+    if (MODEL_CONTAINER_KEYS.includes(key)) continue;
+    const normalized = findContextLimitTokens(nested);
+    if (normalized !== null) return normalized;
+  }
+  return null;
+}
+
+function findPromptBudgetTokens(value) {
+  if (!value || typeof value !== 'object') return null;
+  const candidates = [
+    value.maxPromptTokens,
+    value.max_prompt_tokens,
+    value.contextMax,
+  ];
+  for (const candidate of candidates) {
+    const normalized = normalizeContextLimitTokens(candidate);
+    if (normalized !== null) return normalized;
+  }
+  return null;
+}
+
+function normalizePrice(value) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) && numeric >= 0 ? numeric : null;
+}
+
+function normalizePricing(value, fallbackBatchSize = null) {
+  if (!value || typeof value !== 'object') return null;
+  const batchSize = normalizeContextLimitTokens(value.batchSize) ?? normalizeContextLimitTokens(fallbackBatchSize);
+  const rates = {
+    input: normalizePrice(value.inputPrice),
+    output: normalizePrice(value.outputPrice),
+    cacheRead: normalizePrice(value.cacheReadPrice ?? value.cachePrice),
+    cacheWrite: normalizePrice(value.cacheWritePrice),
+  };
+  // batchSize alone is a denominator, not evidence of real pricing.
+  if (!Object.values(rates).some((entry) => entry !== null)) return null;
+  return { ...rates, batchSize };
+}
+
+function contextLimitForTier(value, tier = 'default') {
+  const limits = value?.capabilities?.limits || value?.limits || {};
+  const outputTokens = normalizeContextLimitTokens(
+    limits.max_output_tokens ?? limits.maxOutputTokens ?? value?.maxOutputTokens,
+  ) || 0;
+  const tokenPrices = value?.billing?.tokenPrices || value?.tokenPrices || null;
+  if (tier === 'long_context') {
+    const longContext = tokenPrices?.longContext
+      || value?.longContext;
+    const promptTokens = findPromptBudgetTokens(longContext);
+    return promptTokens === null ? null : promptTokens + outputTokens;
+  }
+  const defaultPromptTokens = findPromptBudgetTokens(tokenPrices)
+    ?? normalizeContextLimitTokens(limits.max_prompt_tokens ?? limits.maxPromptTokens);
+  if (defaultPromptTokens !== null) return defaultPromptTokens + outputTokens;
+  return findContextLimitTokens(value);
+}
+
+export function extractModelDescriptors(value, out = []) {
+  if (!value) return out;
+  if (typeof value === 'string') {
+    const modelId = normalizeModelIdCandidate(value);
+    if (isValidModelId(modelId)) out.push({ modelId, contextLimitTokens: null });
+    return out;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) extractModelDescriptors(item, out);
+    return out;
+  }
+  if (typeof value !== 'object') return out;
+
+  const modelId = normalizeModelIdCandidate(value.modelId || value.id || value.model || null);
+  if (isValidModelId(modelId)) {
+    const tokenPrices = value?.billing?.tokenPrices || value?.tokenPrices || null;
+    out.push({
+      modelId,
+      contextLimitTokens: contextLimitForTier(value),
+      longContextLimitTokens: contextLimitForTier(value, 'long_context'),
+      pricing: {
+        default: normalizePricing(tokenPrices),
+        longContext: normalizePricing(tokenPrices?.longContext, tokenPrices?.batchSize),
+      },
+    });
+  }
+  for (const key of MODEL_CONTAINER_KEYS) {
+    const nested = value[key];
+    if (nested !== undefined && nested !== null) extractModelDescriptors(nested, out);
+  }
+  return out;
+}

package/shared/model-id.mjs

@@ -0,0 +1,147 @@
+const MODEL_ID_PREFIXES = [
+  'gpt-',
+  'chatgpt-',
+  'claude-',
+  'gemini-',
+  'mai-',
+  'o1-',
+  'o3-',
+  'o4-',
+  'codex-',
+  'openai/',
+  'anthropic/',
+  'google/',
+  'microsoft/',
+];
+const PROVIDER_PREFIXES = ['openai/', 'anthropic/', 'google/', 'microsoft/'];
+const BASE_MODEL_PREFIXES = MODEL_ID_PREFIXES.filter((prefix) => !prefix.includes('/'));
+
+const MODEL_ID_TOKEN_PATTERN = /^[a-z0-9](?:[a-z0-9._/-]{0,118}[a-z0-9])$/i;
+
+const MODEL_ID_DENY_SUBSTRINGS = [
+  'requires enablement',
+  'enable this model',
+  'pick a different one',
+  'accept',
+  'settings',
+  'policy',
+  'missing required authentication',
+  'missing-required-authentication',
+  'not authorized',
+  'not-authorized',
+  'http://',
+  'https://',
+  'github.com/settings',
+];
+
+function isLikelyModelIdPrefix(value) {
+  const lower = String(value || '').toLowerCase();
+  if (lower === 'o1' || lower === 'o3') return true;
+  return MODEL_ID_PREFIXES.some((prefix) => lower.startsWith(prefix));
+}
+
+export function normalizeModelIdCandidate(value) {
+  return String(value || '').trim();
+}
+
+export function isSafeProviderModelId(value) {
+  const candidate = normalizeModelIdCandidate(value);
+  return candidate.length <= 120 && MODEL_ID_TOKEN_PATTERN.test(candidate);
+}
+
+// Claude Agent SDK model ids may carry a bracketed capability suffix
+// (e.g. "claude-opus-5[1m]" for the 1M-context variant).
+export function isSafeClaudeModelId(value) {
+  const candidate = normalizeModelIdCandidate(value);
+  if (candidate.length > 120) return false;
+  const base = candidate.replace(/\[[a-z0-9-]{1,12}\]$/i, '');
+  return MODEL_ID_TOKEN_PATTERN.test(base);
+}
+
+// Cursor model ids ("composer-2.5", "gpt-5.5", "auto-smart") carry no fixed
+// prefix; the safe-chars token check is the whole validation today. Kept as a
+// named seam so cursor-specific rules can diverge without touching callers.
+export function isSafeCursorModelId(value) {
+  return isSafeProviderModelId(value);
+}
+
+// Grok / xAI model ids ("grok-4.5", "grok-code-fast-1") use the same safe-token
+// rules as other unprefixed agent providers.
+export function isSafeGrokModelId(value) {
+  return isSafeProviderModelId(value);
+}
+
+// The "[1m]" suffix marks the 1M-context variant of a Claude model. The UI
+// treats it as a context tier of the base model, not a separate model.
+export const CLAUDE_LONG_CONTEXT_SUFFIX = '[1m]';
+export const CLAUDE_LONG_CONTEXT_SUFFIX_PATTERN = /\[1m\]$/i;
+export const CLAUDE_LONG_CONTEXT_LIMIT_TOKENS = 1_000_000;
+export const CLAUDE_DEFAULT_CONTEXT_LIMIT_TOKENS = 200_000;
+
+export function isClaudeLongContextModelId(value) {
+  return CLAUDE_LONG_CONTEXT_SUFFIX_PATTERN.test(normalizeModelIdCandidate(value));
+}
+
+export function claudeBaseModelId(value) {
+  return normalizeModelIdCandidate(value).replace(CLAUDE_LONG_CONTEXT_SUFFIX_PATTERN, '');
+}
+
+export function claudeLongContextModelId(value) {
+  const base = claudeBaseModelId(value);
+  return base ? `${base}${CLAUDE_LONG_CONTEXT_SUFFIX}` : '';
+}
+
+export function isOpenAIModelId(value) {
+  const candidate = normalizeModelIdCandidate(value).toLowerCase();
+  if (candidate === 'o1' || candidate === 'o3') return true;
+  return [
+    'gpt-',
+    'chatgpt-',
+    'o1-',
+    'o3-',
+    'o4-',
+    'codex-',
+    'openai/',
+  ].some((prefix) => candidate.startsWith(prefix));
+}
+
+export function canonicalizeModelId(value) {
+  const candidate = normalizeModelIdCandidate(value).toLowerCase();
+  if (!candidate) return '';
+  for (const providerPrefix of PROVIDER_PREFIXES) {
+    if (!candidate.startsWith(providerPrefix)) continue;
+    const stripped = candidate.slice(providerPrefix.length);
+    // Provider prefixes are redundant for known base model families,
+    // including the bare "o1"/"o3" ids that carry no dash suffix.
+    if (stripped === 'o1' || stripped === 'o3') return stripped;
+    if (BASE_MODEL_PREFIXES.some((prefix) => stripped.startsWith(prefix))) {
+      return stripped;
+    }
+  }
+  return candidate;
+}
+
+export function isValidModelId(value) {
+  const candidate = normalizeModelIdCandidate(value);
+  if (!candidate) return false;
+  if (candidate.length > 120) return false;
+  if (!isSafeProviderModelId(candidate)) return false;
+  if (!isLikelyModelIdPrefix(candidate)) return false;
+  const lower = candidate.toLowerCase();
+  if (MODEL_ID_DENY_SUBSTRINGS.some((token) => lower.includes(token))) return false;
+  return true;
+}
+
+export function filterValidModelIds(values = []) {
+  const out = [];
+  const seen = new Set();
+  for (const value of values || []) {
+    const candidate = normalizeModelIdCandidate(value);
+    if (!isValidModelId(candidate)) continue;
+    const canonical = canonicalizeModelId(candidate);
+    if (!canonical || seen.has(canonical)) continue;
+    seen.add(canonical);
+    out.push(canonical);
+  }
+  return out;
+}

package/shared/model-refresh.mjs

@@ -0,0 +1,24 @@
+import { filterValidModelIds, normalizeModelIdCandidate } from './model-id.mjs';
+
+export function selectModelIdsForVariantRefresh({
+  snapshotModels = [],
+  currentModel = '',
+  defaultModel = '',
+  helpModelIds = [],
+} = {}) {
+  const fromSnapshot = filterValidModelIds([
+    ...(Array.isArray(snapshotModels) ? snapshotModels : []),
+    normalizeModelIdCandidate(currentModel),
+    normalizeModelIdCandidate(defaultModel),
+  ]);
+  if (fromSnapshot.length) {
+    return {
+      source: 'rpc-snapshot',
+      modelIds: fromSnapshot,
+    };
+  }
+  return {
+    source: 'copilot-help-manual-refresh',
+    modelIds: filterValidModelIds(Array.isArray(helpModelIds) ? helpModelIds : []),
+  };
+}

package/shared/openai-reasoning.mjs

@@ -0,0 +1,13 @@
+export function openAIReasoningEffortsForModel(model = '') {
+  const normalized = String(model || '').trim().toLowerCase().replace(/^openai\//, '');
+  if (/^(?:gpt-image|dall-e)(?:[.-]|$)/.test(normalized)) {
+    return ['auto', 'low', 'medium', 'high'];
+  }
+  if (/^gpt-5(?:[.-]|$)/.test(normalized) || /^codex(?:[.-]|$)/.test(normalized)) {
+    return ['none', 'low', 'medium', 'high', 'xhigh'];
+  }
+  if (/^(?:o1|o3|o4)(?:[.-]|$)/.test(normalized)) {
+    return ['low', 'medium', 'high'];
+  }
+  return ['none'];
+}

package/shared/plan-lines.mjs

@@ -0,0 +1,13 @@
+/**
+ * Count bullet or numbered lines in a reply. Provider workers use this as the
+ * plan-mode fallback heuristic: a plan-mode turn whose final text contains at
+ * least two plan-like lines gets a `plan_ready` board even when the runtime
+ * never signalled plan completion explicitly.
+ */
+export function countPlanLikeLines(text) {
+  return String(text || '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => /^([-*]\s+|\d+\.\s+)/.test(line))
+    .length;
+}

package/shared/preview-instructions.mjs

@@ -0,0 +1,77 @@
+// Preview guidance for providers without a custom-tool surface (Copilot CLI,
+// Grok). The wording lives in preview-tool-core.mjs; this module only decides
+// whether a relay should advertise the capability at all, and where the
+// generated block lands inside an existing guidance document.
+
+import { renderPreviewInstructionBlock } from './preview-tool-core.mjs';
+
+// Derived rather than restated, so a heading change in the generated block
+// still matches the section it is meant to replace.
+export const PREVIEW_INSTRUCTION_HEADING = String(
+  renderPreviewInstructionBlock({}).split('\n')[0] || '',
+).trim();
+
+const DEFAULT_TTL_MS = 6 * 60 * 60 * 1000;
+
+/**
+ * Resolves the instruction block for this relay, or '' when the preview lane
+ * is off. Preview settings only change on relay restart, so the answer is
+ * cached: this must not become a per-turn HTTP call.
+ */
+export function createPreviewInstructionsProvider({
+  api,
+  ttlMs = DEFAULT_TTL_MS,
+  now = () => Date.now(),
+} = {}) {
+  let cachedText = '';
+  let cachedUntil = 0;
+  let inFlight = null;
+
+  async function load() {
+    const response = await api('GET', '/api/previews');
+    const text = response?.enabled === true
+      ? renderPreviewInstructionBlock({ publicBaseUrl: response?.publicBaseUrl || '' })
+      : '';
+    cachedText = text;
+    cachedUntil = now() + ttlMs;
+    return text;
+  }
+
+  return async function getPreviewInstructions() {
+    if (typeof api !== 'function') return '';
+    if (cachedUntil > now()) return cachedText;
+    if (!inFlight) {
+      // A failed lookup is deliberately not cached, and yields no block: an
+      // unreachable relay must neither lose the capability for the rest of the
+      // process nor advertise one that would 503.
+      inFlight = load()
+        .catch(() => '')
+        .finally(() => { inFlight = null; });
+    }
+    return inFlight;
+  };
+}
+
+/**
+ * Swap a guidance document's preview section for the generated block, or drop
+ * the section when there is no block. Other sections are untouched.
+ */
+export function applyPreviewInstructions(baseInstructions = '', previewBlock = '') {
+  const base = String(baseInstructions || '');
+  const block = String(previewBlock || '').trim();
+  const lines = base.split(/\r?\n/);
+  const start = lines.findIndex((line) => line.trim() === PREVIEW_INSTRUCTION_HEADING);
+  if (start === -1) {
+    return [base.trimEnd(), block].filter(Boolean).join('\n\n');
+  }
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (/^##\s/.test(lines[index])) {
+      end = index;
+      break;
+    }
+  }
+  const before = lines.slice(0, start).join('\n').trim();
+  const after = lines.slice(end).join('\n').trim();
+  return [before, block, after].filter(Boolean).join('\n\n');
+}

package/shared/preview-tool-core.mjs

@@ -0,0 +1,191 @@
+// The provider-facing definition of the preview capability, in one place.
+//
+// Two consumption modes, one source of truth:
+//  - Providers with a custom-tool surface (Claude via SDK MCP server, Cursor via
+//    customTools) register `{ name, description, inputSchema, execute }` built
+//    from these exports.
+//  - Providers without one (Copilot CLI, Grok) get renderPreviewInstructionBlock(),
+//    which teaches the identical HTTP API and is generated from the same strings —
+//    the tool and the instructions cannot drift apart.
+//
+// SDK-free and dependency-injected, following ask-user-bridge.mjs: all relay
+// traffic goes through the worker's injected `api(method, path, body)` helper.
+
+export const PREVIEW_TOOL_NAME = 'preview';
+
+export const PREVIEW_TOOL_DESCRIPTION =
+  'Publish a local web server or a static directory on a public preview URL so '
+  + 'the user can open it from any device, or list/close existing previews. Use '
+  + 'this whenever the user wants to see, try, or share something with a web UI '
+  + '— never ask them to open localhost or forward a port. '
+  + 'For a dev server: call this FIRST with {action:"create", port} to get the '
+  + 'basePath, then start the server configured to serve under that basePath '
+  + '(Vite --base, Next basePath, Express mount prefix); the proxy forwards '
+  + 'X-Forwarded-Prefix but does not rewrite bodies, so root-absolute asset '
+  + 'paths will not work. For plain files or a build output: pass {action:'
+  + '"create", dir} instead and the relay serves the directory itself — no dev '
+  + 'server needed. Always tell the user the returned URL and that the link is '
+  + 'public: anyone who has it can reach the app without logging in. Previews '
+  + 'never expire on their own; close them with {action:"close"} when the user '
+  + 'is done.';
+
+export const PREVIEW_TOOL_INPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    action: {
+      type: 'string',
+      enum: ['create', 'list', 'close'],
+      description: 'create: publish a port or directory. list: live previews. close: unpublish one.',
+    },
+    port: {
+      type: 'integer',
+      minimum: 1024,
+      maximum: 65535,
+      description: 'create only: local port an already-listening dev server is on. Mutually exclusive with dir.',
+    },
+    dir: {
+      type: 'string',
+      description: 'create only: directory to serve statically (absolute, or relative to the workspace root). Mutually exclusive with port.',
+    },
+    label: {
+      type: 'string',
+      maxLength: 120,
+      description: 'create only: short human label shown on the preview card, e.g. "web app (vite)".',
+    },
+    token: {
+      type: 'string',
+      pattern: '^[0-9a-f]{32}$',
+      description: 'close only: which preview. May be omitted when exactly one preview is live in this conversation.',
+    },
+  },
+  required: ['action'],
+};
+
+function toText(value) {
+  return String(value ?? '').trim();
+}
+
+/**
+ * Validates and normalizes tool input. This is a courtesy layer so the model
+ * gets a crisp message instead of an HTTP 400 — the API performs the same
+ * checks authoritatively.
+ */
+export function validatePreviewToolInput(input = {}) {
+  const action = toText(input?.action).toLowerCase();
+  if (!['create', 'list', 'close'].includes(action)) {
+    return { ok: false, error: 'action must be one of: create, list, close' };
+  }
+  if (action === 'create') {
+    const hasPort = input?.port !== undefined && input?.port !== null && toText(input?.port) !== '';
+    const dir = toText(input?.dir);
+    if (hasPort && dir) {
+      return { ok: false, error: 'Pass either port (proxy a running server) or dir (serve files statically), not both' };
+    }
+    if (!hasPort && !dir) {
+      return { ok: false, error: 'create needs a port (running dev server) or a dir (static files)' };
+    }
+    if (hasPort) {
+      const port = Number(input.port);
+      if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+        return { ok: false, error: 'port must be an integer between 1024 and 65535' };
+      }
+      return { ok: true, action, port, label: toText(input?.label).slice(0, 120) };
+    }
+    return { ok: true, action, dir, label: toText(input?.label).slice(0, 120) };
+  }
+  if (action === 'close') {
+    const token = toText(input?.token).toLowerCase();
+    if (token && !/^[0-9a-f]{32}$/.test(token)) {
+      return { ok: false, error: 'token must be the 32-hex preview token from create/list' };
+    }
+    return { ok: true, action, token: token || null };
+  }
+  return { ok: true, action };
+}
+
+/**
+ * Executes a validated call against the relay API. Returns a compact object the
+ * model can quote directly; errors come back as `{ ok:false, error }` rather
+ * than throws, so a refused create reads as an answer, not a tool crash.
+ */
+export async function executePreviewTool(input, { api, conversationId = '' } = {}) {
+  if (typeof api !== 'function') return { ok: false, error: 'Preview API unavailable in this worker' };
+  const parsed = validatePreviewToolInput(input);
+  if (!parsed.ok) return parsed;
+
+  try {
+    if (parsed.action === 'list') {
+      const response = await api('GET', '/api/previews');
+      return {
+        ok: true,
+        enabled: response?.enabled === true,
+        previews: (response?.previews || []).map((entry) => ({
+          token: entry.token,
+          label: entry.label,
+          url: entry.url,
+          target: entry.mode === 'static' ? entry.rootDir : `localhost:${entry.targetPort}`,
+          online: entry.online,
+          conversationId: entry.conversationId,
+        })),
+      };
+    }
+
+    if (parsed.action === 'close') {
+      let token = parsed.token;
+      if (!token) {
+        const response = await api('GET', `/api/previews?conversationId=${encodeURIComponent(conversationId)}`);
+        const live = response?.previews || [];
+        if (live.length === 0) return { ok: false, error: 'No live previews in this conversation' };
+        if (live.length > 1) {
+          return {
+            ok: false,
+            error: 'Multiple previews are live; pass the token of the one to close',
+            previews: live.map((entry) => ({ token: entry.token, label: entry.label })),
+          };
+        }
+        token = live[0].token;
+      }
+      const response = await api('DELETE', `/api/previews/${token}`);
+      return { ok: true, closed: { token, label: response?.preview?.label || null } };
+    }
+
+    const body = {
+      conversationId,
+      label: parsed.label || undefined,
+      ...(parsed.port ? { port: parsed.port } : { dir: parsed.dir }),
+    };
+    const response = await api('POST', '/api/previews', body);
+    return {
+      ok: true,
+      url: response?.url,
+      basePath: response?.basePath,
+      token: response?.preview?.token,
+      mode: response?.preview?.mode || (parsed.port ? 'port' : 'static'),
+      hint: parsed.port
+        ? `Serve the app under ${response?.basePath} (the proxy strips the prefix and sends X-Forwarded-Prefix). Tell the user the URL and that the link is public.`
+        : 'The directory is served as-is; relative asset paths work, root-absolute ones do not. Tell the user the URL and that the link is public.',
+    };
+  } catch (error) {
+    return { ok: false, error: String(error?.message || error) };
+  }
+}
+
+/**
+ * The instruction block for providers without a custom-tool surface. Generated
+ * from the same description/schema strings the tool uses; keep any wording
+ * change up in the constants, never here.
+ */
+export function renderPreviewInstructionBlock({ publicBaseUrl = '' } = {}) {
+  const base = toText(publicBaseUrl) || 'https://<preview-host>';
+  return `## Preview servers
+
+${PREVIEW_TOOL_DESCRIPTION}
+
+There is no \`${PREVIEW_TOOL_NAME}\` tool on this provider — use the authenticated localhost API (same auth as /api/relay/shutdown):
+
+- Publish a running dev server: \`POST /api/previews\` with \`{ "conversationId": "<conv>", "port": 5173, "label": "web app" }\` → \`{ "url": "${base}/test_<token>/", "basePath": "/test_<token>/" }\`. Register FIRST, then start the server under the returned basePath.
+- Publish files without a server: \`POST /api/previews\` with \`{ "conversationId": "<conv>", "dir": "./dist", "label": "built site" }\` — the relay serves the directory itself. \`dir\` must live inside the conversation's workspace root.
+- List: \`GET /api/previews\` (\`?conversationId=\` filters). Close: \`DELETE /api/previews/:token\` — closes the link only, never the dev server behind it.
+
+A 503 with \`details\` means the preview lane is disabled or misconfigured — surface those details to the user. A 400 names exactly what was refused (relay-owned port, non-loopback host, dir outside the workspace root).`;
+}

package/shared/provider-routing.mjs

@@ -0,0 +1,29 @@
+/**
+ * The single source of truth for which providers execute where.
+ *
+ * The legacy Copilot relay CLI (server/relay.mjs) may only execute turns for
+ * these providers; everything else runs on a dedicated session worker. This
+ * used to be encoded twice in inverse shapes — an allowlist in relay.mjs and a
+ * NOT IN (...) denylist inside message-repository's SQL — so adding a provider
+ * meant editing both and missing one silently reopened cross-provider
+ * execution. relay.mjs is a standalone CLI that must not import the express
+ * routes, which is exactly why this lives in shared/.
+ */
+export const LEGACY_RELAY_PROVIDER_TYPES = Object.freeze(['github', 'openai']);
+
+export const SESSION_WORKER_PROVIDER_TYPES = Object.freeze(['claude', 'cursor', 'grok']);
+
+export function isLegacyRelayProviderType(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (!normalized) return true; // no runtime session = github
+  return LEGACY_RELAY_PROVIDER_TYPES.includes(normalized);
+}
+
+export function isSessionWorkerProviderType(value) {
+  return SESSION_WORKER_PROVIDER_TYPES.includes(String(value || '').trim().toLowerCase());
+}
+
+/** `'claude', 'cursor', 'grok'` — for interpolation into SQL NOT IN (...) lists. */
+export function sessionWorkerProviderSqlList() {
+  return SESSION_WORKER_PROVIDER_TYPES.map((provider) => `'${provider}'`).join(', ');
+}