@polylogicai/polycode 1.1.4 → 1.1.5

package/lib/paste-aware-prompt.mjs

@@ -0,0 +1,208 @@
+// lib/paste-aware-prompt.mjs
+// A custom line reader that implements bracketed paste mode for the polycode
+// REPL. Standard readline cannot tell a one-character typed key from a
+// multi-line paste, so pasting a 500-line file floods the terminal and
+// floods the display with echoed content. Modern terminals support
+// bracketed paste mode: when enabled, the terminal wraps pasted content in
+// ESC[200~ ... ESC[201~ so the host program can detect the paste as a
+// single event.
+//
+// This reader enables bracketed paste on startup, reads stdin in raw mode,
+// collapses each paste to a placeholder like [Pasted #1 (20 lines)] in the
+// display, and returns both the displayed line and the full content with
+// placeholders expanded for the agent to read.
+
+import { stdin, stdout } from 'node:process';
+
+const ESC = '\u001b';
+const PASTE_START = `${ESC}[200~`;
+const PASTE_END = `${ESC}[201~`;
+
+const BRACKETED_PASTE_ON = `${ESC}[?2004h`;
+const BRACKETED_PASTE_OFF = `${ESC}[?2004l`;
+
+// Ordinal counter for paste placeholders within the lifetime of the process.
+// Each successful paste increments it so the user can reference pastes by
+// number ("expand pasted #3") in future features.
+let pasteOrdinal = 0;
+
+export function enableBracketedPaste() {
+  if (stdout.isTTY) stdout.write(BRACKETED_PASTE_ON);
+}
+
+export function disableBracketedPaste() {
+  if (stdout.isTTY) stdout.write(BRACKETED_PASTE_OFF);
+}
+
+// Read one line from stdin with paste awareness. Returns a promise that
+// resolves to { displayed, content, pastes }:
+//   - displayed: the string the user sees in the terminal (with placeholders)
+//   - content:   the string to send to the agent (with full paste text)
+//   - pastes:    an array of { ordinal, lines, bytes, text } for logging/telemetry
+//
+// On non-TTY stdin (piped input, tests), this reader falls back to a plain
+// line read with no paste handling, since bracketed paste requires a real
+// terminal.
+export function readPasteAwareLine(prompt) {
+  return new Promise((resolve, reject) => {
+    stdout.write(prompt);
+
+    if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') {
+      let buf = '';
+      const onData = (chunk) => {
+        buf += chunk.toString('utf8');
+        const nlIdx = buf.indexOf('\n');
+        if (nlIdx !== -1) {
+          stdin.removeListener('data', onData);
+          const line = buf.slice(0, nlIdx).replace(/\r$/, '');
+          resolve({ displayed: line, content: line, pastes: [] });
+        }
+      };
+      stdin.on('data', onData);
+      return;
+    }
+
+    const wasRaw = stdin.isRaw;
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+
+    let stream = '';
+    const pastes = [];
+    const segments = [];
+    let currentText = '';
+    let visibleLength = 0;
+
+    const cleanup = () => {
+      stdin.removeListener('data', onData);
+      try { stdin.setRawMode(wasRaw); } catch { /* ignore */ }
+      stdin.pause();
+    };
+
+    const flushCurrent = () => {
+      if (currentText.length > 0) {
+        segments.push({ kind: 'text', text: currentText });
+        currentText = '';
+      }
+    };
+
+    const finish = () => {
+      flushCurrent();
+      cleanup();
+      stdout.write('\n');
+
+      const displayed = segments
+        .map((s) =>
+          s.kind === 'text'
+            ? s.text
+            : `[Pasted #${s.ordinal} (${s.lines} lines)]`
+        )
+        .join('');
+      const content = segments.map((s) => (s.kind === 'text' ? s.text : s.text)).join('');
+      resolve({ displayed, content, pastes });
+    };
+
+    const onData = (chunk) => {
+      try {
+        stream += chunk;
+        // Drain the stream one token at a time.
+        while (stream.length > 0) {
+          // Paste start?
+          if (stream.startsWith(PASTE_START)) {
+            const endIdx = stream.indexOf(PASTE_END, PASTE_START.length);
+            if (endIdx === -1) {
+              // Waiting for the rest of the paste; don't consume anything.
+              return;
+            }
+            const pasted = stream.slice(PASTE_START.length, endIdx);
+            stream = stream.slice(endIdx + PASTE_END.length);
+            flushCurrent();
+            pasteOrdinal += 1;
+            const ordinal = pasteOrdinal;
+            const lines = pasted.split('\n').length;
+            const bytes = Buffer.byteLength(pasted, 'utf8');
+            const entry = { ordinal, lines, bytes, text: pasted };
+            pastes.push(entry);
+            segments.push({ kind: 'paste', ordinal, lines, bytes, text: pasted });
+            const placeholder = `[Pasted #${ordinal} (${lines} lines)]`;
+            stdout.write(`\u001b[2m${placeholder}\u001b[0m`);
+            visibleLength += placeholder.length;
+            continue;
+          }
+          // Single char path
+          const ch = stream[0];
+          stream = stream.slice(1);
+
+          if (ch === '\r' || ch === '\n') {
+            finish();
+            return;
+          }
+          if (ch === '\u0003') {
+            // Ctrl-C
+            cleanup();
+            stdout.write('\n');
+            reject(new Error('cancelled'));
+            return;
+          }
+          if (ch === '\u0004') {
+            // Ctrl-D on empty line = exit; on non-empty = ignored
+            if (currentText.length === 0 && segments.length === 0) {
+              finish();
+              return;
+            }
+            continue;
+          }
+          if (ch === '\u007f' || ch === '\b') {
+            // Backspace. If the last segment is a paste, remove the whole
+            // paste (one deletion = one paste). Otherwise remove one char.
+            if (currentText.length > 0) {
+              currentText = currentText.slice(0, -1);
+              stdout.write('\b \b');
+              visibleLength = Math.max(0, visibleLength - 1);
+            } else if (segments.length > 0) {
+              const last = segments.pop();
+              if (last.kind === 'paste') {
+                const width = `[Pasted #${last.ordinal} (${last.lines} lines)]`.length;
+                for (let i = 0; i < width; i++) stdout.write('\b \b');
+                visibleLength = Math.max(0, visibleLength - width);
+                // Also remove from the pastes[] index so logs match.
+                const pi = pastes.findIndex((p) => p.ordinal === last.ordinal);
+                if (pi !== -1) pastes.splice(pi, 1);
+              } else {
+                // Put it back and delete one char.
+                segments.push(last);
+                if (last.text.length > 0) {
+                  last.text = last.text.slice(0, -1);
+                  stdout.write('\b \b');
+                  visibleLength = Math.max(0, visibleLength - 1);
+                }
+              }
+            }
+            continue;
+          }
+          if (ch === ESC) {
+            // Unrecognized escape sequence. Consume the minimum so we don't
+            // block; terminal-specific sequences (arrow keys, etc.) aren't
+            // supported in this reader, they get swallowed silently.
+            if (stream.length >= 2 && stream[0] === '[') {
+              stream = stream.slice(2);
+            }
+            continue;
+          }
+          if (ch < ' ' && ch !== '\t') {
+            // Other control char: ignore.
+            continue;
+          }
+          currentText += ch;
+          stdout.write(ch);
+          visibleLength += 1;
+        }
+      } catch (err) {
+        cleanup();
+        reject(err);
+      }
+    };
+
+    stdin.on('data', onData);
+  });
+}

package/lib/repl-ui.mjs

@@ -139,7 +139,9 @@ export function createRenderer(stdout, opts = {}) {
       const out = compactToolResultLine(ev.name, ev.result);
       if (out) line(out);
     } else if (ev.phase === 'scrub_blocked') {
-      line(`${C.red}refusing to send tool output to the model: contains a recognized secret pattern${C.reset}`);
+      // Suppressed: a follow-up `act/message` event renders the friendlier
+      // guidance that tells the user to type /key instead. We hide the raw
+      // scrub event to avoid a scary red line before the guidance.
     } else if (ev.phase === 'error') {
       line(`${C.red}error: ${ev.message}${C.reset}`);
     }

package/lib/slash-commands.mjs

@@ -5,10 +5,12 @@
 
 import { C } from './repl-ui.mjs';
 import { rotateIntent } from './intent.mjs';
+import { runInteractiveKeyFlow, PROVIDERS, getProviderById } from './key-store.mjs';
 
 export const SLASH_HELP = `
 ${C.bold}polycode commands${C.reset}
   /help                       Show this help
+  /key [provider]             Save an API key (Groq, Anthropic, OpenAI). Input is masked.
   /log                        Show session log path, row count, and last hash
   /replay <n>                 Print the last N session log rows
   /verify                     Verify session log SHA-256 chain integrity
@@ -18,15 +20,44 @@ ${C.bold}polycode commands${C.reset}
   /exit, /quit                Leave polycode
 `;
 
-export async function dispatchSlash(line, { canon, state, stdout }) {
+export async function dispatchSlash(line, { canon, state, stdout, loop, rl }) {
   const [cmd, ...rest] = line.slice(1).split(/\s+/);
-  const args = rest.join(' ');
+  const args = rest.join(' ').trim();
 
   switch (cmd) {
     case 'help':
       stdout.write(SLASH_HELP + '\n');
       return { continue: true };
 
+    case 'key':
+    case 'login': {
+      const providerHint = args || null;
+      if (providerHint && !getProviderById(providerHint)) {
+        stdout.write(`${C.red}unknown provider${C.reset}: ${providerHint}. Known: ${PROVIDERS.map((p) => p.id).join(', ')}\n`);
+        return { continue: true };
+      }
+      stdout.write(`${C.dim}Your key will be saved locally to ~/.polycode/secrets.env (chmod 600) and never sent to the model.${C.reset}\n`);
+      const result = await runInteractiveKeyFlow({ providerHint, stdout, rl });
+      if (!result.ok) {
+        if (result.reason === 'cancelled') {
+          stdout.write(`${C.dim}cancelled${C.reset}\n`);
+        } else {
+          stdout.write(`${C.red}error${C.reset}: ${result.reason}\n`);
+        }
+        return { continue: true };
+      }
+      stdout.write(`${C.amber}saved${C.reset}: ${result.provider.name} key (${result.provider.envVar})\n`);
+      // Hot-swap the live loop: if the saved key is for the current provider
+      // (Groq), flip out of hosted mode so the next turn goes direct to the
+      // provider. Other providers just land in env for next compile.
+      if (loop && result.provider.id === 'groq') {
+        loop.apiKey = process.env[result.provider.envVar];
+        loop.hostedMode = false;
+        stdout.write(`${C.dim}switched this session from hosted tier to direct Groq. Unlimited use.${C.reset}\n`);
+      }
+      return { continue: true };
+    }
+
     case 'log':
     case 'history':
     case 'canon': {

package/lib/tools/describe-image.mjs

@@ -0,0 +1,111 @@
+// lib/tools/describe-image.mjs
+// Vision tool. Reads an image from disk, base64-encodes it, sends to a
+// vision-capable model, returns the text description. In hosted mode the
+// request goes through the Polylogic inference proxy so the user does not
+// need any vision-specific key. In BYOK mode we use the user's Groq key
+// against the same endpoint.
+
+import { promises as fs } from 'node:fs';
+import { extname } from 'node:path';
+
+const MAX_IMAGE_BYTES = 4 * 1024 * 1024;
+const DEFAULT_VISION_MODEL = 'meta-llama/llama-4-scout-17b-16e-instruct';
+const FALLBACK_VISION_MODEL = 'meta-llama/llama-4-scout-17b-16e-instruct';
+
+const MIME_BY_EXT = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+};
+
+function mimeFor(path) {
+  const ext = extname(path).toLowerCase();
+  return MIME_BY_EXT[ext] || null;
+}
+
+export async function describeImage({ path, question }) {
+  const stat = await fs.stat(path);
+  if (!stat.isFile()) throw new Error(`not a file: ${path}`);
+  if (stat.size > MAX_IMAGE_BYTES) {
+    throw new Error(`image too large: ${stat.size} bytes (limit ${MAX_IMAGE_BYTES})`);
+  }
+  const mime = mimeFor(path);
+  if (!mime) {
+    throw new Error(`unsupported image type: ${extname(path) || '(no extension)'}. Supported: png, jpg, jpeg, webp, gif.`);
+  }
+
+  const bytes = await fs.readFile(path);
+  const dataUrl = `data:${mime};base64,${bytes.toString('base64')}`;
+
+  const body = {
+    model: DEFAULT_VISION_MODEL,
+    max_tokens: 700,
+    temperature: 0.2,
+    messages: [
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: question || 'Describe this image in detail.' },
+          { type: 'image_url', image_url: { url: dataUrl } },
+        ],
+      },
+    ],
+  };
+
+  // Routing: BYOK uses Groq directly, hosted mode uses the Polylogic proxy.
+  const groqKey = process.env.GROQ_API_KEY || '';
+  let res;
+  let endpoint;
+  let headers;
+  if (groqKey) {
+    endpoint = 'https://api.groq.com/openai/v1/chat/completions';
+    headers = {
+      Authorization: `Bearer ${groqKey}`,
+      'Content-Type': 'application/json',
+    };
+  } else {
+    const { getOrCreateInstallId } = await import('../polycode-hosted-client.mjs');
+    endpoint = process.env.POLYCODE_PROXY_URL || 'https://polylogicai.com/api/polycode/inference';
+    headers = {
+      'Content-Type': 'application/json',
+      'X-Polycode-Install-ID': getOrCreateInstallId(),
+      'X-Polycode-Version': 'vision',
+    };
+  }
+
+  async function callOnce(modelOverride) {
+    const payload = modelOverride ? { ...body, model: modelOverride } : body;
+    const r = await fetch(endpoint, { method: 'POST', headers, body: JSON.stringify(payload) });
+    const text = await r.text();
+    if (!r.ok) {
+      const err = new Error(`vision upstream ${r.status}: ${text.slice(0, 300)}`);
+      err.status = r.status;
+      err.body = text;
+      throw err;
+    }
+    try { return JSON.parse(text); } catch { throw new Error(`vision upstream returned non-JSON: ${text.slice(0, 200)}`); }
+  }
+
+  let completion;
+  try {
+    completion = await callOnce();
+  } catch (err) {
+    // Fall back to the older preview model if the maverick model is unavailable
+    // on the backend (e.g. proxy allowlist or decommissioned).
+    if (err.status === 400 || err.status === 404) {
+      completion = await callOnce(FALLBACK_VISION_MODEL);
+    } else {
+      throw err;
+    }
+  }
+
+  const content = completion?.choices?.[0]?.message?.content;
+  if (typeof content === 'string' && content.length > 0) return content;
+  if (Array.isArray(content)) {
+    // Some models return content as an array of blocks.
+    return content.map((b) => (typeof b === 'string' ? b : b?.text || '')).join('\n').trim();
+  }
+  throw new Error('vision response had no content');
+}

package/lib/tools/fetch-url.mjs

@@ -0,0 +1,130 @@
+// lib/tools/fetch-url.mjs
+// Fetches a URL from the user's machine and returns its body as text.
+// Supports HTTP(S), follows redirects, converts HTML to readable plain text,
+// returns JSON and text verbatim. Refuses binary content, private network
+// addresses, and non-http protocols.
+
+const MAX_BODY_BYTES = 200 * 1024;
+const FETCH_TIMEOUT_MS = 15_000;
+
+const USER_AGENT = 'polycode/1.1 (+https://polylogicai.com/polycode)';
+
+// Block private network ranges so the tool cannot be used as a server-side
+// request forgery vector against the user's own localhost or LAN. This is a
+// defense-in-depth since polycode is a user-agent, but the LLM might be
+// told to ping an internal endpoint.
+function isForbiddenHost(host) {
+  if (!host) return true;
+  const h = host.toLowerCase();
+  if (h === 'localhost' || h === '127.0.0.1' || h === '::1' || h === '0.0.0.0') return true;
+  if (/^10\./.test(h)) return true;
+  if (/^192\.168\./.test(h)) return true;
+  if (/^172\.(1[6-9]|2\d|3[0-1])\./.test(h)) return true;
+  if (/^169\.254\./.test(h)) return true;
+  if (/^fc[0-9a-f][0-9a-f]:/.test(h)) return true;
+  if (/^fe80:/.test(h)) return true;
+  return false;
+}
+
+// Strip HTML tags and normalize whitespace for a body that the model can
+// actually read. We drop script/style blocks first, then replace tags with
+// newlines, then collapse whitespace runs. This is a best-effort reader, not
+// a full DOM parser.
+function htmlToText(html) {
+  let out = html;
+  out = out.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ' ');
+  out = out.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, ' ');
+  out = out.replace(/<noscript\b[^>]*>[\s\S]*?<\/noscript>/gi, ' ');
+  out = out.replace(/<(?:br|hr|p|div|li|h[1-6]|tr|td|th|section|article)\b[^>]*>/gi, '\n');
+  out = out.replace(/<\/(?:p|div|li|h[1-6]|tr|section|article)>/gi, '\n');
+  out = out.replace(/<[^>]+>/g, ' ');
+  out = out
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/&amp;/gi, '&')
+    .replace(/&lt;/gi, '<')
+    .replace(/&gt;/gi, '>')
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;/gi, "'");
+  out = out.replace(/[ \t]+/g, ' ');
+  out = out.replace(/\n[ \t]+/g, '\n');
+  out = out.replace(/\n{3,}/g, '\n\n');
+  return out.trim();
+}
+
+export async function fetchUrl(rawUrl) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new Error(`invalid URL: ${rawUrl}`);
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error(`unsupported protocol: ${url.protocol}`);
+  }
+  if (isForbiddenHost(url.hostname)) {
+    throw new Error(`refusing to fetch private-network or loopback host: ${url.hostname}`);
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  let res;
+  try {
+    res = await fetch(url.toString(), {
+      method: 'GET',
+      headers: {
+        'User-Agent': USER_AGENT,
+        Accept: 'text/html,text/plain,application/json,application/xhtml+xml,*/*;q=0.8',
+      },
+      redirect: 'follow',
+      signal: controller.signal,
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    if (err.name === 'AbortError') throw new Error(`timeout after ${FETCH_TIMEOUT_MS}ms: ${url.hostname}`);
+    throw new Error(`network error: ${err.message}`);
+  }
+  clearTimeout(timer);
+
+  const contentType = (res.headers.get('content-type') || '').toLowerCase();
+  const isText =
+    contentType.startsWith('text/') ||
+    contentType.includes('json') ||
+    contentType.includes('xml') ||
+    contentType === '';
+  if (!isText) {
+    return `[${res.status} ${res.statusText}] ${url.toString()}\ncontent-type: ${contentType}\n(binary content refused; use describe_image for images)`;
+  }
+
+  const reader = res.body?.getReader?.();
+  let received = 0;
+  const chunks = [];
+  if (reader) {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      received += value.byteLength;
+      if (received > MAX_BODY_BYTES) {
+        chunks.push(value.subarray(0, MAX_BODY_BYTES - (received - value.byteLength)));
+        break;
+      }
+      chunks.push(value);
+    }
+  } else {
+    const buf = Buffer.from(await res.arrayBuffer());
+    chunks.push(buf.subarray(0, MAX_BODY_BYTES));
+    received = buf.byteLength;
+  }
+  const raw = Buffer.concat(chunks.map((c) => (c instanceof Buffer ? c : Buffer.from(c)))).toString('utf8');
+
+  let body;
+  if (contentType.includes('json')) {
+    body = raw;
+  } else if (contentType.includes('html') || /<html[^>]*>/i.test(raw)) {
+    body = htmlToText(raw);
+  } else {
+    body = raw;
+  }
+
+  const header = `[${res.status} ${res.statusText}] ${url.toString()}\ncontent-type: ${contentType || 'unknown'}\nbytes: ${received}${received > MAX_BODY_BYTES ? ' (truncated)' : ''}\n---\n`;
+  return header + body;
+}

package/lib/tools/web-search.mjs

@@ -0,0 +1,107 @@
+// lib/tools/web-search.mjs
+// Web search tool. In hosted mode the request goes to the Polylogic search
+// proxy at polylogicai.com/api/polycode/search, which runs the query against
+// a real search backend (Tavily / Brave) with a server-side key so the user
+// does not need to provision anything. In BYOK mode a user-supplied
+// TAVILY_API_KEY is used directly if present; otherwise we still fall
+// through to the Polylogic proxy.
+//
+// Returns a formatted text block with up to 8 (title, url, snippet) rows so
+// the model can read it as plain context. Never dumps raw HTML.
+
+const DEFAULT_PROXY_URL = 'https://polylogicai.com/api/polycode/search';
+const MAX_RESULTS = 8;
+const SEARCH_TIMEOUT_MS = 15_000;
+
+function formatResults(results, query) {
+  if (!Array.isArray(results) || results.length === 0) {
+    return `web_search("${query}")\n(no results)`;
+  }
+  const lines = [`web_search("${query}")`, ''];
+  let i = 1;
+  for (const r of results.slice(0, MAX_RESULTS)) {
+    const title = String(r.title || r.name || '').slice(0, 200);
+    const url = String(r.url || r.link || '').slice(0, 400);
+    const snippet = String(r.content || r.snippet || r.description || '').replace(/\s+/g, ' ').slice(0, 300);
+    lines.push(`${i}. ${title}`);
+    if (url) lines.push(`   ${url}`);
+    if (snippet) lines.push(`   ${snippet}`);
+    lines.push('');
+    i++;
+  }
+  return lines.join('\n');
+}
+
+async function searchViaTavilyDirect(query, apiKey) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), SEARCH_TIMEOUT_MS);
+  try {
+    const res = await fetch('https://api.tavily.com/search', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        query,
+        max_results: MAX_RESULTS,
+        search_depth: 'basic',
+      }),
+      signal: controller.signal,
+    });
+    const text = await res.text();
+    if (!res.ok) throw new Error(`tavily ${res.status}: ${text.slice(0, 200)}`);
+    const data = JSON.parse(text);
+    return formatResults(data.results || [], query);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function searchViaPolylogicProxy(query) {
+  const { getOrCreateInstallId } = await import('../polycode-hosted-client.mjs');
+  const endpoint = process.env.POLYCODE_SEARCH_URL || DEFAULT_PROXY_URL;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), SEARCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Polycode-Install-ID': getOrCreateInstallId(),
+        'X-Polycode-Version': 'search',
+      },
+      body: JSON.stringify({ query, max_results: MAX_RESULTS }),
+      signal: controller.signal,
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      let msg;
+      try { msg = JSON.parse(text).error; } catch { msg = text; }
+      throw new Error(`polycode search proxy ${res.status}: ${String(msg).slice(0, 300)}`);
+    }
+    const data = JSON.parse(text);
+    if (Array.isArray(data.results)) return formatResults(data.results, query);
+    if (typeof data === 'string') return data;
+    return formatResults(data, query);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function webSearch(query) {
+  const q = String(query || '').trim();
+  if (!q) throw new Error('empty query');
+
+  const byokKey = process.env.TAVILY_API_KEY || '';
+  if (byokKey) {
+    try {
+      return await searchViaTavilyDirect(q, byokKey);
+    } catch (err) {
+      // Fall through to the hosted proxy on direct-provider failure.
+      const hosted = await searchViaPolylogicProxy(q);
+      return `${hosted}\n\n(note: direct tavily call failed: ${err.message})`;
+    }
+  }
+  return searchViaPolylogicProxy(q);
+}