surf-skill 2.0.0

package/src/lib/providers/index.mjs

@@ -0,0 +1,32 @@
+// Provider registry: capability map + factory.
+
+import { tavilyProvider } from './tavily.mjs';
+import { parallelProvider } from './parallel.mjs';
+
+export const PROVIDERS = {
+  tavily: tavilyProvider,
+  parallel: parallelProvider,
+};
+
+// Default fallback chain per operation. Adjust with care: order matters.
+export const capabilityMap = {
+  search:           ['tavily', 'parallel'],
+  extract:          ['tavily', 'parallel'],
+  crawl:            ['tavily'],
+  map:              ['tavily'],
+  'research-start': ['parallel', 'tavily'],
+  research:         ['parallel', 'tavily'],
+  'research-poll':  ['BY_REQUEST_ID'],
+  usage:            ['BY_PROVIDER'],
+};
+
+export function getProvider(name) {
+  return PROVIDERS[name];
+}
+
+export function providerFromRequestId(requestId) {
+  if (typeof requestId !== 'string') return null;
+  if (requestId.startsWith('tvly:')) return { provider: 'tavily', providerRunId: requestId.slice(5) };
+  if (requestId.startsWith('pllx:')) return { provider: 'parallel', providerRunId: requestId.slice(5) };
+  return null;
+}

package/src/lib/providers/parallel.mjs

@@ -0,0 +1,270 @@
+// Parallel AI adapter — talks to https://api.parallel.ai with x-api-key header.
+// Capability notes:
+//   - search:           POST /v1/search
+//   - extract:          POST /v1beta/extract  (beta endpoint)
+//   - crawl:            NOT supported
+//   - map:              NOT supported
+//   - research-start:   POST /v1/tasks/runs   (async; returns run_id)
+//   - research-poll:    GET  /v1/tasks/runs/{id}  + GET /v1/tasks/runs/{id}/result
+//   - usage:            NOT documented publicly
+// Auth: header `x-api-key: <key>` (NOT Bearer).
+// Error body: { "type":"error", "error":{ "ref_id":"...", "message":"...", "detail":{} } }
+
+import { clamp, compactObject, flat, splitList } from '../flags.mjs';
+
+const BASE = process.env.SURF_PARALLEL_API_BASE || 'https://api.parallel.ai';
+const DEFAULT_TIMEOUT = Number(process.env.SURF_TIMEOUT_MS) || 45000;
+
+const DEPTH_TO_PROCESSOR = {
+  'ultra-fast': 'lite',
+  'fast': 'lite',
+  'basic': 'lite',
+  'advanced': 'base',
+};
+
+const RESEARCH_MODEL_TO_PROCESSOR = {
+  mini: 'lite',
+  auto: 'base',
+  pro: 'pro',
+  ultra: 'ultra',
+};
+
+export const parallelProvider = {
+  name: 'parallel',
+  supports: {
+    search: true,
+    extract: true,
+    crawl: false,
+    map: false,
+    'research-start': true,
+    'research-poll': true,
+    usage: false,
+  },
+  search,
+  extract,
+  crawl: notSupported('crawl'),
+  map: notSupported('map'),
+  'research-start': researchStart,
+  'research-poll': researchPoll,
+  usage: notSupported('usage'),
+  mapError,
+};
+
+function notSupported(op) {
+  return async () => {
+    throw Object.assign(new Error(`parallel does not support '${op}'`), {
+      kind: 'not_supported', statusCode: 0,
+    });
+  };
+}
+
+function buildHeaders(key, version) {
+  return {
+    'x-api-key': key,
+    'Content-Type': 'application/json',
+    'X-Client-Name': `surf-skill/${version || '2.0.0'}`,
+  };
+}
+
+async function doFetch(path, body, ctx, opts = {}) {
+  const method = opts.method || 'POST';
+  const timeout = opts.timeoutMs || ctx.timeout || DEFAULT_TIMEOUT;
+  const ctl = new AbortController();
+  const t = setTimeout(() => ctl.abort('timeout'), timeout);
+  const t0 = Date.now();
+  try {
+    const res = await fetch(`${BASE}${path}`, {
+      method,
+      headers: buildHeaders(ctx.key, ctx.version),
+      body: method === 'POST' ? JSON.stringify(body) : undefined,
+      signal: ctl.signal,
+    });
+    clearTimeout(t);
+    const text = await res.text();
+    let data;
+    try { data = JSON.parse(text); } catch { data = { raw: text }; }
+    return { status: res.status, ok: res.ok, data, latency_ms: Date.now() - t0 };
+  } catch (e) {
+    clearTimeout(t);
+    if (e.name === 'AbortError' || /timeout/i.test(e.message)) {
+      throw Object.assign(new Error(`Parallel request exceeded ${timeout}ms`), { kind: 'network' });
+    }
+    throw Object.assign(new Error(`Parallel network error: ${e.message}`), { kind: 'network' });
+  }
+}
+
+function extractMessage(body) {
+  if (!body) return '';
+  if (body.error) {
+    if (typeof body.error === 'string') return body.error;
+    const parts = [];
+    if (body.error.message) parts.push(body.error.message);
+    // Parallel returns detailed validation errors at body.error.detail.errors[]
+    // with shape { type, loc: ["body","field"], msg, input }. Surface them so
+    // schema mismatches are debuggable without --raw-json.
+    const errs = body.error.detail && body.error.detail.errors;
+    if (Array.isArray(errs) && errs.length) {
+      for (const e of errs) {
+        const loc = Array.isArray(e.loc) ? e.loc.join('.') : '';
+        parts.push(`${loc}: ${e.msg}`);
+      }
+    } else if (body.error.detail) {
+      parts.push(flat(body.error.detail));
+    }
+    return parts.filter(Boolean).join(' — ');
+  }
+  return flat(body.message) || flat(body.detail) || '';
+}
+
+function mapError(status, body) {
+  const msg = extractMessage(body);
+  if (status === 401) return { kind: 'auth', statusCode: status, message: 'invalid Parallel key' };
+  if (status === 402) return { kind: 'auth', statusCode: status, message: 'Parallel: insufficient credits' };
+  if (status === 403) {
+    // 403 may be auth OR "invalid processor" depending on body. The latter is a
+    // caller error — switching keys won't help.
+    if (/processor/i.test(msg)) return { kind: 'caller_4xx', statusCode: status, message: msg };
+    return { kind: 'auth', statusCode: status, message: msg || 'forbidden' };
+  }
+  if (status === 429) return { kind: 'rate_limit_429', statusCode: status, message: msg || 'Parallel rate limit' };
+  if (status >= 500) return { kind: 'server_5xx', statusCode: status, message: msg || 'Parallel server error' };
+  if (status >= 400) return { kind: 'caller_4xx', statusCode: status, message: msg || `HTTP ${status}` };
+  return { kind: 'caller_4xx', statusCode: status, message: msg || `unexpected HTTP ${status}` };
+}
+
+function asError(status, body) {
+  const m = mapError(status, body);
+  return Object.assign(new Error(`parallel ${m.kind} (HTTP ${status}): ${m.message}`), m, { body });
+}
+
+function wrap(operation, raw, data, latency_ms) {
+  return {
+    provider: 'parallel',
+    operation,
+    raw,
+    usage: { credits: raw && raw.usage && (raw.usage.credits ?? raw.usage.total_credits) },
+    latency_ms,
+    data,
+  };
+}
+
+async function search(args, ctx) {
+  const queries = args.searchQueries
+    ? (Array.isArray(args.searchQueries) ? args.searchQueries : splitList(args.searchQueries))
+    : (args.query ? [args.query] : []);
+  if (!queries.length) throw Object.assign(new Error('search requires query or --queries'), { kind: 'caller_4xx', statusCode: 400 });
+
+  // Parallel POST /v1/search currently accepts ONLY { objective, search_queries }.
+  // Any other field (processor, max_results, source_policy, ...) is rejected
+  // with "Extra inputs are not permitted". Tavily-only knobs like --depth,
+  // --max, --domains are silently ignored on this provider — that's expected.
+  // Verified against api.parallel.ai 2026-05-20; if Parallel expands the
+  // schema later, add fields here.
+  const body = {
+    objective: args.objective || args.query || queries[0],
+    search_queries: queries,
+  };
+
+  const { status, ok, data, latency_ms } = await doFetch('/v1/search', body, ctx);
+  if (!ok) throw asError(status, data);
+
+  return wrap('search', data, {
+    query: args.query || queries.join(' | '),
+    answer: undefined,
+    results: (data.results || []).map(it => ({
+      url: it.url,
+      title: it.title,
+      content: Array.isArray(it.excerpts) ? it.excerpts.join('\n\n') : (it.excerpts || it.snippet || ''),
+      score: undefined,
+      raw_content: it.full_content,
+      published_date: it.publish_date,
+    })),
+  }, latency_ms);
+}
+
+async function extract(args, ctx) {
+  if (!Array.isArray(args.urls) || args.urls.length === 0) {
+    throw Object.assign(new Error('extract requires at least 1 URL'), { kind: 'caller_4xx', statusCode: 400 });
+  }
+  const body = compactObject({
+    urls: args.urls,
+    objective: args.query,
+    excerpts: args.depth !== 'advanced',
+    full_content: args.depth === 'advanced',
+  });
+  const { status, ok, data, latency_ms } = await doFetch('/v1beta/extract', body, ctx);
+  if (!ok) throw asError(status, data);
+  return wrap('extract', data, {
+    results: (data.results || []).map(it => ({
+      url: it.url,
+      raw_content: it.full_content || (Array.isArray(it.excerpts) ? it.excerpts.join('\n\n') : ''),
+      title: it.title,
+      images: undefined,
+    })),
+    failed: (data.errors || []).map(e => ({
+      url: e.url || (typeof e === 'string' ? e : ''),
+      reason: e.message || e.error || 'unknown',
+    })),
+  }, latency_ms);
+}
+
+async function researchStart(args, ctx) {
+  const processor = args.processor || RESEARCH_MODEL_TO_PROCESSOR[args.model || 'auto'] || 'base';
+  const body = compactObject({
+    input: args.input,
+    processor,
+    task_spec: args.outputSchema ? { output_schema: args.outputSchema } : undefined,
+  });
+  const { status, ok, data, latency_ms } = await doFetch('/v1/tasks/runs', body, ctx, { timeoutMs: 30000 });
+  if (!ok) throw asError(status, data);
+  return wrap('research-start', data, {
+    request_id: `pllx:${data.run_id}`,
+    provider_run_id: data.run_id,
+    status: data.status || 'queued',
+    model: processor,
+  }, latency_ms);
+}
+
+async function researchPoll(args, ctx) {
+  const id = args.providerRunId;
+  // 1) status check
+  const head = await doFetch(`/v1/tasks/runs/${id}`, null, ctx, { method: 'GET', timeoutMs: 15000 });
+  if (!head.ok) throw asError(head.status, head.data);
+
+  const headData = head.data;
+  const status = String(headData.status || '').toLowerCase();
+  const isCompleted = status === 'completed' || status === 'success';
+  const isFailed = status === 'failed' || status === 'errored' || status === 'error';
+
+  // Map Parallel statuses to normalized vocabulary.
+  let normStatus = status;
+  if (isCompleted) normStatus = 'completed';
+  else if (isFailed) normStatus = 'failed';
+  else if (status === 'queued' || status === 'pending') normStatus = 'pending';
+  else normStatus = 'running';
+
+  let content, sources, errorMsg;
+  if (isCompleted) {
+    const res = await doFetch(`/v1/tasks/runs/${id}/result`, null, ctx, { method: 'GET', timeoutMs: 20000 });
+    if (!res.ok) throw asError(res.status, res.data);
+    const r = res.data || {};
+    const output = r.output || r.result || {};
+    content = typeof output === 'string' ? output : (output.content || output.text || JSON.stringify(output));
+    sources = (output.basis || r.basis || []).map(s => ({
+      url: s.url || s.source_url || '',
+      title: s.title,
+    })).filter(s => s.url);
+  } else if (isFailed) {
+    errorMsg = headData.error || extractMessage(headData) || 'task failed';
+  }
+
+  return wrap('research-poll', headData, {
+    request_id: `pllx:${id}`,
+    provider_run_id: id,
+    status: normStatus,
+    model: headData.processor,
+    content,
+    sources,
+    error: errorMsg,
+  }, head.latency_ms);
+}

package/src/lib/providers/tavily.mjs

@@ -0,0 +1,245 @@
+// Tavily adapter — talks to https://api.tavily.com with Authorization: Bearer.
+
+import { clamp, splitList, compactObject, flat } from '../flags.mjs';
+
+const BASE = process.env.SURF_TAVILY_API_BASE || process.env.TAVILY_API_BASE || 'https://api.tavily.com';
+const DEFAULT_TIMEOUT = Number(process.env.SURF_TIMEOUT_MS || process.env.TAVILY_TIMEOUT_MS) || 45000;
+
+export const tavilyProvider = {
+  name: 'tavily',
+  supports: {
+    search: true,
+    extract: true,
+    crawl: true,
+    map: true,
+    'research-start': true,
+    'research-poll': true,
+    usage: true,
+  },
+  search,
+  extract,
+  crawl,
+  map,
+  'research-start': researchStart,
+  'research-poll': researchPoll,
+  usage,
+  mapError,
+};
+
+function buildHeaders(key, version) {
+  return {
+    'Authorization': `Bearer ${key}`,
+    'Content-Type': 'application/json',
+    'X-Client-Name': `surf-skill/${version || '2.0.0'}`,
+  };
+}
+
+async function doFetch(path, body, ctx, opts = {}) {
+  const method = opts.method || 'POST';
+  const timeout = opts.timeoutMs || ctx.timeout || DEFAULT_TIMEOUT;
+  const ctl = new AbortController();
+  const t = setTimeout(() => ctl.abort('timeout'), timeout);
+  const t0 = Date.now();
+  try {
+    const res = await fetch(`${BASE}${path}`, {
+      method,
+      headers: buildHeaders(ctx.key, ctx.version),
+      body: method === 'POST' ? JSON.stringify(body) : undefined,
+      signal: ctl.signal,
+    });
+    clearTimeout(t);
+    const text = await res.text();
+    let data;
+    try { data = JSON.parse(text); } catch { data = { raw: text }; }
+    return { status: res.status, ok: res.ok, data, latency_ms: Date.now() - t0 };
+  } catch (e) {
+    clearTimeout(t);
+    if (e.name === 'AbortError' || /timeout/i.test(e.message)) {
+      throw Object.assign(new Error(`Tavily request exceeded ${timeout}ms`), { kind: 'network' });
+    }
+    throw Object.assign(new Error(`Tavily network error: ${e.message}`), { kind: 'network' });
+  }
+}
+
+function mapError(status, body) {
+  if (status === 401) return { kind: 'auth', statusCode: status, message: 'invalid Tavily key' };
+  if (status === 403) return { kind: 'auth', statusCode: status, message: 'forbidden Tavily key' };
+  if (status === 432 || status === 433) return { kind: 'auth', statusCode: status, message: 'Tavily plan/quota limit hit' };
+  if (status === 429) return { kind: 'rate_limit_429', statusCode: status, message: 'Tavily rate limit' };
+  if (status >= 500) return { kind: 'server_5xx', statusCode: status, message: 'Tavily server error' };
+  if (status >= 400) return { kind: 'caller_4xx', statusCode: status, message: flat(body && (body.error || body.detail || body.message)) || `HTTP ${status}` };
+  return { kind: 'caller_4xx', statusCode: status, message: `unexpected HTTP ${status}` };
+}
+
+function wrap(operation, raw, data, latency_ms) {
+  return {
+    provider: 'tavily',
+    operation,
+    raw,
+    usage: { credits: raw && raw.usage && raw.usage.credits },
+    latency_ms,
+    data,
+  };
+}
+
+async function search(args, ctx) {
+  const body = compactObject({
+    query: args.query,
+    search_depth: args.depth || 'basic',
+    max_results: clamp(Number(args.max) || 5, 1, 20),
+    topic: args.topic,
+    time_range: args.time,
+    start_date: args.startDate,
+    end_date: args.endDate,
+    include_domains: splitList(args.domains),
+    exclude_domains: splitList(args.excludeDomains),
+    country: args.country,
+    include_answer: args.answer === true ? 'basic' : args.answer,
+    include_raw_content: args.raw === true ? 'markdown' : args.raw,
+    include_images: !!args.images,
+    include_image_descriptions: !!args.imageDesc,
+    include_favicon: !!args.favicon,
+    auto_parameters: !!args.auto,
+    exact_match: !!args.exactMatch,
+    include_usage: true,
+  });
+  const { status, ok, data, latency_ms } = await doFetch('/search', body, ctx);
+  if (!ok) throw asError(status, data);
+  return wrap('search', data, {
+    query: data.query || args.query,
+    answer: data.answer,
+    results: (data.results || []).map(it => ({
+      url: it.url,
+      title: it.title,
+      content: it.content || '',
+      score: it.score,
+      raw_content: it.raw_content,
+      published_date: it.published_date,
+    })),
+  }, latency_ms);
+}
+
+async function extract(args, ctx) {
+  const body = compactObject({
+    urls: args.urls,
+    extract_depth: args.depth || 'basic',
+    format: args.format || 'markdown',
+    include_images: !!args.images,
+    include_favicon: !!args.favicon,
+    query: args.query,
+    chunks_per_source: args.chunks ? Number(args.chunks) : undefined,
+    timeout: args.extractTimeout ? Number(args.extractTimeout) : undefined,
+    include_usage: true,
+  });
+  const { status, ok, data, latency_ms } = await doFetch('/extract', body, ctx);
+  if (!ok) throw asError(status, data);
+  return wrap('extract', data, {
+    results: (data.results || []).map(it => ({
+      url: it.url,
+      raw_content: it.raw_content || '',
+      title: it.title,
+      images: it.images,
+    })),
+    failed: (data.failed_results || []).map(f => ({
+      url: f.url || (typeof f === 'string' ? f : ''),
+      reason: f.error || 'unknown',
+    })),
+  }, latency_ms);
+}
+
+async function crawl(args, ctx) {
+  const body = compactObject({
+    url: args.url,
+    max_depth: clamp(Number(args.maxDepth) || 1, 1, 5),
+    max_breadth: clamp(Number(args.maxBreadth) || 20, 1, 500),
+    limit: clamp(Number(args.limit) || 50, 1, 200),
+    instructions: args.instructions,
+    select_paths: splitList(args.selectPaths),
+    select_domains: splitList(args.selectDomains),
+    exclude_paths: splitList(args.excludePaths),
+    exclude_domains: splitList(args.excludeDomains),
+    allow_external: !!args.allowExternal,
+    include_images: !!args.images,
+    categories: splitList(args.categories),
+    extract_depth: args.extractDepth || 'basic',
+    format: args.format || 'markdown',
+    query: args.query,
+    chunks_per_source: args.chunks ? Number(args.chunks) : undefined,
+    timeout: args.timeout ? Number(args.timeout) : undefined,
+    include_usage: true,
+  });
+  const { status, ok, data, latency_ms } = await doFetch('/crawl', body, ctx, { timeoutMs: 50000 });
+  if (!ok) throw asError(status, data);
+  return wrap('crawl', data, {
+    base_url: data.base_url || args.url,
+    results: (data.results || []).map(it => typeof it === 'string'
+      ? { url: it }
+      : { url: it.url, raw_content: it.raw_content }),
+  }, latency_ms);
+}
+
+async function map(args, ctx) {
+  const body = compactObject({
+    url: args.url,
+    max_depth: clamp(Number(args.maxDepth) || 1, 1, 5),
+    max_breadth: clamp(Number(args.maxBreadth) || 20, 1, 500),
+    limit: clamp(Number(args.limit) || 50, 1, 500),
+    instructions: args.instructions,
+    select_paths: splitList(args.selectPaths),
+    select_domains: splitList(args.selectDomains),
+    exclude_paths: splitList(args.excludePaths),
+    exclude_domains: splitList(args.excludeDomains),
+    allow_external: !!args.allowExternal,
+    categories: splitList(args.categories),
+    timeout: args.timeout ? Number(args.timeout) : undefined,
+    include_usage: true,
+  });
+  const { status, ok, data, latency_ms } = await doFetch('/map', body, ctx);
+  if (!ok) throw asError(status, data);
+  const urls = (data.results || []).map(it => typeof it === 'string' ? it : it.url).filter(Boolean);
+  return wrap('map', data, { base_url: data.base_url || args.url, urls }, latency_ms);
+}
+
+async function researchStart(args, ctx) {
+  const body = compactObject({
+    input: args.input,
+    model: args.model || 'auto',
+    citation_format: args.citationFormat || 'numbered',
+    stream: false,
+    output_schema: args.outputSchema,
+  });
+  const { status, ok, data, latency_ms } = await doFetch('/research', body, ctx, { timeoutMs: 30000 });
+  if (!ok) throw asError(status, data);
+  return wrap('research-start', data, {
+    request_id: `tvly:${data.request_id}`,
+    provider_run_id: data.request_id,
+    status: data.status || 'pending',
+    model: data.model || body.model,
+  }, latency_ms);
+}
+
+async function researchPoll(args, ctx) {
+  const id = args.providerRunId;
+  const { status, ok, data, latency_ms } = await doFetch(`/research/${id}`, null, ctx, { method: 'GET', timeoutMs: 15000 });
+  if (!ok) throw asError(status, data);
+  return wrap('research-poll', data, {
+    request_id: `tvly:${id}`,
+    provider_run_id: id,
+    status: data.status,
+    model: data.model,
+    content: data.content,
+    sources: (data.sources || []).map(s => ({ url: s.url, title: s.title })),
+    error: data.error,
+  }, latency_ms);
+}
+
+async function usage(_args, ctx) {
+  const { status, ok, data, latency_ms } = await doFetch('/usage', null, ctx, { method: 'GET', timeoutMs: 15000 });
+  if (!ok) throw asError(status, data);
+  return wrap('usage', data, data, latency_ms);
+}
+
+function asError(status, body) {
+  const m = mapError(status, body);
+  return Object.assign(new Error(`tavily ${m.kind} (HTTP ${status}): ${m.message}`), m, { body });
+}

package/src/lib/setup.mjs

@@ -0,0 +1,111 @@
+// Interactive onboarding wizard. Requires a TTY. Non-TTY callers should use
+// `surf-skill keys add` directly.
+//
+// Multi-key: prompts for N keys per provider (Enter to finish that provider).
+
+import readline from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { loadState, saveStateAtomic, KEYS_FILE } from './state.mjs';
+
+const BANNER = `
+┌─ surf-skill setup ──────────────────────────────────────
+│ Configure API keys. You can add multiple keys per provider
+│ (Enter empty to finish a provider; Enter twice in a row to
+│ skip it entirely).
+│
+│ Tavily:    https://app.tavily.com    (1,000 free credits/mo)
+│ Parallel:  https://platform.parallel.ai
+│
+│ Keys live in ${KEYS_FILE} (chmod 600).
+└──────────────────────────────────────────────────────────
+`;
+
+const CHEAT_SHEET_TPL = (counts) => `
+✓ Saved ${counts.tav} Tavily key${counts.tav === 1 ? '' : 's'}, ${counts.par} Parallel key${counts.par === 1 ? '' : 's'}.
+
+Try one of:
+  surf-skill search "your query"
+  surf-skill search "q1" "q2" "q3"      # batch (N queries)
+  surf-skill extract https://example.com
+  surf-skill keys list
+
+Add another key later with:
+  surf-skill keys add --provider <tavily|parallel> <key>
+
+🛠  IMPORTANT — in each project where you'll use surf-skill, run:
+      surf-skill project-config
+   This raises the per-project bash timeout for the harness in that repo.
+
+⚠  GitHub Copilot CLI users: this step is REQUIRED. Copilot's default bash
+   timeout is 30s and surf-skill needs more (most commands run 3–60s).
+
+Docs: SKILL.md  ·  Repo: https://github.com/frederico-kluser/surf-skill
+`;
+
+async function promptKeys(rl, provider, existing = []) {
+  const collected = [];
+  let i = 1;
+  const seen = new Set(existing);
+  while (true) {
+    const promptText = i === 1
+      ? `${provider} key #${i} (Enter to skip ${provider}): `
+      : `${provider} key #${i} (Enter to finish, or paste another): `;
+    let ans = '';
+    try {
+      ans = (await rl.question(promptText)).trim();
+    } catch {
+      break;
+    }
+    if (!ans) break;
+    if (seen.has(ans)) {
+      stdout.write(`  (already configured, skipping)\n`);
+      continue;
+    }
+    collected.push(ans);
+    seen.add(ans);
+    i++;
+  }
+  return collected;
+}
+
+export async function runSetup() {
+  if (!stdin.isTTY) {
+    const err = new Error(`'setup' requires a TTY. Use:
+  surf-skill keys add --provider tavily <key>
+  surf-skill keys add --provider parallel <key>`);
+    err.code = 'NO_TTY';
+    throw err;
+  }
+
+  stdout.write(BANNER);
+
+  const state = await loadState();
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  let newTav = [];
+  let newPar = [];
+  try {
+    newTav = await promptKeys(rl, 'Tavily', state.tavily.keys);
+    stdout.write('\n');
+    newPar = await promptKeys(rl, 'Parallel', state.parallel.keys);
+  } finally {
+    rl.close();
+  }
+
+  if (!newTav.length && !newPar.length) {
+    stdout.write('\nNo new keys provided. Rerun with: surf-skill setup\n');
+    return { addedTavily: 0, addedParallel: 0 };
+  }
+
+  for (const k of newTav) state.tavily.keys.push(k);
+  for (const k of newPar) state.parallel.keys.push(k);
+  if (state.tavily.keys.length && state.tavily.current >= state.tavily.keys.length) state.tavily.current = 0;
+  if (state.parallel.keys.length && state.parallel.current >= state.parallel.keys.length) state.parallel.current = 0;
+
+  await saveStateAtomic(state);
+
+  stdout.write(CHEAT_SHEET_TPL({
+    tav: state.tavily.keys.length,
+    par: state.parallel.keys.length,
+  }));
+  return { addedTavily: newTav.length, addedParallel: newPar.length };
+}