@selesai/code 0.10.2 → 0.11.0

package/dist/extensions/pi-web-agent/src/backends/doctor.ts

@@ -1,136 +1,136 @@
-import type { BackendConfig, FirecrawlOptions, SearxngOptions } from './config.js';
-import { readBraveKeyFromSettings } from './settings-reader.js';
-
-function withTimeout(timeoutMs: number) {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), timeoutMs);
-  return { signal: controller.signal, done: () => clearTimeout(timeout) };
-}
-
-function message(error: unknown) {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function braveDoctorUrl() {
-  const url = new URL('https://api.search.brave.com/res/v1/web/search');
-  url.searchParams.set('q', 'pi-web-agent-doctor');
-  url.searchParams.set('count', '1');
-  return url.toString();
-}
-
-function searxngDoctorUrl(baseUrl: string, options: SearxngOptions = {}) {
-  const url = new URL('/search', baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`);
-  url.searchParams.set('q', 'pi-web-agent-doctor');
-  url.searchParams.set('format', 'json');
-  if (options.categories?.length) url.searchParams.set('categories', options.categories.join(','));
-  if (options.language) url.searchParams.set('language', options.language);
-  if (options.safesearch !== undefined) url.searchParams.set('safesearch', String(options.safesearch));
-  return url.toString();
-}
-
-function firecrawlDoctorBody(options: FirecrawlOptions = {}) {
-  return {
-    url: 'https://example.com',
-    formats: options.formats ?? ['markdown'],
-    ...(options.onlyMainContent !== undefined ? { onlyMainContent: options.onlyMainContent } : {})
-  };
-}
-
-export async function checkBackendHealth(
-  config: BackendConfig,
-  {
-    fetchImpl = fetch,
-    timeoutMs = 3_000
-  }: {
-    fetchImpl?: typeof fetch;
-    timeoutMs?: number;
-  } = {}
-): Promise<string[]> {
-  const lines: string[] = [];
-
-  if (config.search.provider === 'duckduckgo') {
-    lines.push('search backend: duckduckgo');
-  } else if (config.search.provider === 'brave') {
-    const apiKey = process.env.PI_WEB_AGENT_BRAVE_API_KEY ?? readBraveKeyFromSettings();
-    if (!apiKey?.trim()) {
-      lines.push('search backend: brave warning (missing Brave API key — set webAgent.braveApiKey in settings.json or PI_WEB_AGENT_BRAVE_API_KEY env var)');
-    } else {
-      const timeout = withTimeout(timeoutMs);
-      try {
-        const response = await fetchImpl(braveDoctorUrl(), {
-          headers: {
-            Accept: 'application/json',
-            'X-Subscription-Token': apiKey
-          },
-          signal: timeout.signal
-        });
-        if (!response.ok) {
-          lines.push(`search backend: brave warning (HTTP ${response.status})`);
-        } else {
-          const json = (await response.json()) as { web?: { results?: unknown } };
-          lines.push(Array.isArray(json.web?.results)
-            ? 'search backend: brave ok'
-            : 'search backend: brave warning (unexpected response)');
-        }
-      } catch (error) {
-        lines.push(`search backend: brave warning (${message(error)})`);
-      } finally {
-        timeout.done();
-      }
-    }
-  } else if (!config.search.baseUrl) {
-    lines.push('search backend: searxng warning (missing baseUrl)');
-  } else {
-    const timeout = withTimeout(timeoutMs);
-    try {
-      const response = await fetchImpl(searxngDoctorUrl(config.search.baseUrl, config.search.options), { signal: timeout.signal });
-      const json = (await response.json()) as { results?: unknown };
-      lines.push(response.ok && Array.isArray(json.results)
-        ? 'search backend: searxng ok'
-        : 'search backend: searxng warning (unexpected response)');
-    } catch (error) {
-      lines.push(`search backend: searxng warning (${message(error)})`);
-    } finally {
-      timeout.done();
-    }
-  }
-
-  if (config.search.fallback) {
-    lines.push(`search fallback: ${config.search.fallback}`);
-  }
-
-  if (config.fetch.provider === 'http') {
-    lines.push('fetch backend: http');
-  } else if (!config.fetch.baseUrl) {
-    lines.push('fetch backend: firecrawl warning (missing baseUrl)');
-  } else {
-    const timeout = withTimeout(timeoutMs);
-    try {
-      const headers: Record<string, string> = { 'content-type': 'application/json' };
-      if (config.fetch.apiKey ?? process.env.PI_WEB_AGENT_FIRECRAWL_API_KEY) {
-        headers.Authorization = `Bearer ${config.fetch.apiKey ?? process.env.PI_WEB_AGENT_FIRECRAWL_API_KEY}`;
-      }
-      const response = await fetchImpl(new URL('/v1/scrape', config.fetch.baseUrl).toString(), {
-        method: 'POST',
-        headers,
-        body: JSON.stringify(firecrawlDoctorBody(config.fetch.options)),
-        signal: timeout.signal
-      });
-      lines.push(response.ok ? 'fetch backend: firecrawl ok' : `fetch backend: firecrawl warning (HTTP ${response.status})`);
-    } catch (error) {
-      lines.push(`fetch backend: firecrawl warning (${message(error)})`);
-    } finally {
-      timeout.done();
-    }
-  }
-
-  if (config.fetch.fallback) {
-    lines.push(`fetch fallback: ${config.fetch.fallback}`);
-  }
-
-  if (config.headless.provider === 'local-browser') {
-    lines.push('headless backend: local-browser (managed Chromium fallback configured)');
-  }
-
-  return lines;
-}
+import type { BackendConfig, FirecrawlOptions, SearxngOptions } from './config.js';
+import { readBraveKeyFromSettings } from './settings-reader.js';
+
+function withTimeout(timeoutMs: number) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  return { signal: controller.signal, done: () => clearTimeout(timeout) };
+}
+
+function message(error: unknown) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function braveDoctorUrl() {
+  const url = new URL('https://api.search.brave.com/res/v1/web/search');
+  url.searchParams.set('q', 'pi-web-agent-doctor');
+  url.searchParams.set('count', '1');
+  return url.toString();
+}
+
+function searxngDoctorUrl(baseUrl: string, options: SearxngOptions = {}) {
+  const url = new URL('/search', baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`);
+  url.searchParams.set('q', 'pi-web-agent-doctor');
+  url.searchParams.set('format', 'json');
+  if (options.categories?.length) url.searchParams.set('categories', options.categories.join(','));
+  if (options.language) url.searchParams.set('language', options.language);
+  if (options.safesearch !== undefined) url.searchParams.set('safesearch', String(options.safesearch));
+  return url.toString();
+}
+
+function firecrawlDoctorBody(options: FirecrawlOptions = {}) {
+  return {
+    url: 'https://example.com',
+    formats: options.formats ?? ['markdown'],
+    ...(options.onlyMainContent !== undefined ? { onlyMainContent: options.onlyMainContent } : {})
+  };
+}
+
+export async function checkBackendHealth(
+  config: BackendConfig,
+  {
+    fetchImpl = fetch,
+    timeoutMs = 3_000
+  }: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+  } = {}
+): Promise<string[]> {
+  const lines: string[] = [];
+
+  if (config.search.provider === 'duckduckgo') {
+    lines.push('search backend: duckduckgo');
+  } else if (config.search.provider === 'brave') {
+    const apiKey = process.env.PI_WEB_AGENT_BRAVE_API_KEY ?? readBraveKeyFromSettings();
+    if (!apiKey?.trim()) {
+      lines.push('search backend: brave warning (missing Brave API key — set webAgent.braveApiKey in settings.json or PI_WEB_AGENT_BRAVE_API_KEY env var)');
+    } else {
+      const timeout = withTimeout(timeoutMs);
+      try {
+        const response = await fetchImpl(braveDoctorUrl(), {
+          headers: {
+            Accept: 'application/json',
+            'X-Subscription-Token': apiKey
+          },
+          signal: timeout.signal
+        });
+        if (!response.ok) {
+          lines.push(`search backend: brave warning (HTTP ${response.status})`);
+        } else {
+          const json = (await response.json()) as { web?: { results?: unknown } };
+          lines.push(Array.isArray(json.web?.results)
+            ? 'search backend: brave ok'
+            : 'search backend: brave warning (unexpected response)');
+        }
+      } catch (error) {
+        lines.push(`search backend: brave warning (${message(error)})`);
+      } finally {
+        timeout.done();
+      }
+    }
+  } else if (!config.search.baseUrl) {
+    lines.push('search backend: searxng warning (missing baseUrl)');
+  } else {
+    const timeout = withTimeout(timeoutMs);
+    try {
+      const response = await fetchImpl(searxngDoctorUrl(config.search.baseUrl, config.search.options), { signal: timeout.signal });
+      const json = (await response.json()) as { results?: unknown };
+      lines.push(response.ok && Array.isArray(json.results)
+        ? 'search backend: searxng ok'
+        : 'search backend: searxng warning (unexpected response)');
+    } catch (error) {
+      lines.push(`search backend: searxng warning (${message(error)})`);
+    } finally {
+      timeout.done();
+    }
+  }
+
+  if (config.search.fallback) {
+    lines.push(`search fallback: ${config.search.fallback}`);
+  }
+
+  if (config.fetch.provider === 'http') {
+    lines.push('fetch backend: http');
+  } else if (!config.fetch.baseUrl) {
+    lines.push('fetch backend: firecrawl warning (missing baseUrl)');
+  } else {
+    const timeout = withTimeout(timeoutMs);
+    try {
+      const headers: Record<string, string> = { 'content-type': 'application/json' };
+      if (config.fetch.apiKey ?? process.env.PI_WEB_AGENT_FIRECRAWL_API_KEY) {
+        headers.Authorization = `Bearer ${config.fetch.apiKey ?? process.env.PI_WEB_AGENT_FIRECRAWL_API_KEY}`;
+      }
+      const response = await fetchImpl(new URL('/v1/scrape', config.fetch.baseUrl).toString(), {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(firecrawlDoctorBody(config.fetch.options)),
+        signal: timeout.signal
+      });
+      lines.push(response.ok ? 'fetch backend: firecrawl ok' : `fetch backend: firecrawl warning (HTTP ${response.status})`);
+    } catch (error) {
+      lines.push(`fetch backend: firecrawl warning (${message(error)})`);
+    } finally {
+      timeout.done();
+    }
+  }
+
+  if (config.fetch.fallback) {
+    lines.push(`fetch fallback: ${config.fetch.fallback}`);
+  }
+
+  if (config.headless.provider === 'local-browser') {
+    lines.push('headless backend: local-browser (managed Chromium fallback configured)');
+  }
+
+  return lines;
+}

package/dist/extensions/pi-web-agent/src/backends/factory.ts

@@ -1,152 +1,152 @@
-import { createFirecrawlFetcher } from '../fetch/firecrawl-fetch.js';
-import { createBraveSearchTool } from '../search/brave.js';
-import { createSearxngSearchTool } from '../search/searxng.js';
-import { buildFetchPresentation } from '../presentation/fetch-presentation.js';
-import { buildSearchPresentation } from '../presentation/search-presentation.js';
-import { createWebFetchHeadlessTool } from '../tools/web-fetch-headless.js';
-import { createWebFetchTool } from '../tools/web-fetch.js';
-import { createWebSearchTool } from '../tools/web-search.js';
-import { readBraveKeyFromSettings } from './settings-reader.js';
-import type { WebFetchHeadlessResponse, WebFetchResponse, WebSearchResponse } from '../types.js';
-import { DEFAULT_BACKEND_CONFIG, type BackendConfig } from './config.js';
-
-export type BackendSet = {
-  search: (input: { query: string }) => Promise<WebSearchResponse>;
-  fetchPage: (input: { url: string }) => Promise<WebFetchResponse>;
-  headlessFetch: (input: { url: string }) => Promise<WebFetchHeadlessResponse>;
-};
-
-export type BackendFactoryDeps = {
-  createDuckDuckGoSearch?: typeof createWebSearchTool;
-  createSearxngSearch?: typeof createSearxngSearchTool;
-  createBraveSearch?: typeof createBraveSearchTool;
-  createHttpFetch?: typeof createWebFetchTool;
-  createFirecrawlFetch?: typeof createFirecrawlFetcher;
-  createHeadlessFetch?: typeof createWebFetchHeadlessTool;
-};
-
-function invalidSearxngSearch() {
-  return async function search() {
-    const result: WebSearchResponse = {
-      status: 'error',
-      results: [],
-      metadata: { backend: 'searxng', cacheHit: false },
-      error: {
-        code: 'BACKEND_CONFIG_INVALID',
-        message: 'SearXNG search requires backends.search.baseUrl.'
-      }
-    };
-
-    return { ...result, presentation: buildSearchPresentation(result) };
-  };
-}
-
-function invalidFirecrawlFetch() {
-  return async function fetchPage(url: string): Promise<WebFetchResponse> {
-    const result: WebFetchResponse = {
-      status: 'error',
-      url,
-      metadata: { method: 'firecrawl', cacheHit: false },
-      error: {
-        code: 'BACKEND_CONFIG_INVALID',
-        message: 'Firecrawl fetch requires backends.fetch.baseUrl.'
-      }
-    };
-
-    return { ...result, presentation: buildFetchPresentation(result) };
-  };
-}
-
-function withSearchFallback(
-  primary: BackendSet['search'],
-  fallback: BackendSet['search'],
-  fallbackFrom: 'searxng' | 'brave'
-): BackendSet['search'] {
-  return async (input) => {
-    const first = await primary(input);
-    if (first.status !== 'error') return first;
-
-    const second = await fallback(input);
-    const result: WebSearchResponse = {
-      ...second,
-      metadata: {
-        ...second.metadata,
-        fallbackFrom,
-        fallbackReason: first.error?.message ?? `${fallbackFrom} search failed.`
-      }
-    };
-    return { ...result, presentation: buildSearchPresentation(result) };
-  };
-}
-
-function withFetchFallback(
-  primary: BackendSet['fetchPage'],
-  fallback: BackendSet['fetchPage']
-): BackendSet['fetchPage'] {
-  return async (input) => {
-    const first = await primary(input);
-    if (first.status !== 'error' && first.status !== 'needs_headless') return first;
-
-    const second = await fallback(input);
-    const result: WebFetchResponse = {
-      ...second,
-      metadata: {
-        ...second.metadata,
-        fallbackFrom: 'firecrawl',
-        fallbackReason: first.error?.message ?? 'Firecrawl fetch failed.'
-      }
-    };
-    return { ...result, presentation: buildFetchPresentation(result) };
-  };
-}
-
-export function createBackendSet(
-  config: BackendConfig = DEFAULT_BACKEND_CONFIG,
-  deps: BackendFactoryDeps = {}
-): BackendSet {
-  const createDuckDuckGoSearch = deps.createDuckDuckGoSearch ?? createWebSearchTool;
-  const createSearxngSearch = deps.createSearxngSearch ?? createSearxngSearchTool;
-  const createBraveSearch = deps.createBraveSearch ?? createBraveSearchTool;
-  const createHttpFetch = deps.createHttpFetch ?? createWebFetchTool;
-  const createFirecrawlFetch = deps.createFirecrawlFetch ?? createFirecrawlFetcher;
-  const createHeadlessFetch = deps.createHeadlessFetch ?? createWebFetchHeadlessTool;
-
-  let search = config.search.provider === 'searxng'
-    ? config.search.baseUrl
-      ? createSearxngSearch({ baseUrl: config.search.baseUrl, options: config.search.options })
-      : invalidSearxngSearch()
-    : config.search.provider === 'brave'
-      ? createBraveSearch({ apiKey: process.env.PI_WEB_AGENT_BRAVE_API_KEY ?? readBraveKeyFromSettings() })
-      : createDuckDuckGoSearch();
-
-  if (config.search.provider === 'searxng' && config.search.fallback === 'duckduckgo') {
-    search = withSearchFallback(search, createDuckDuckGoSearch(), 'searxng');
-  }
-
-  if (config.search.provider === 'brave' && config.search.fallback === 'duckduckgo') {
-    search = withSearchFallback(search, createDuckDuckGoSearch(), 'brave');
-  }
-
-  const httpFetch = createHttpFetch();
-  let fetchPage = config.fetch.provider === 'firecrawl'
-    ? config.fetch.baseUrl
-      ? createHttpFetch({
-          fetchPage: createFirecrawlFetch({
-            baseUrl: config.fetch.baseUrl,
-            apiKey: config.fetch.apiKey ?? process.env.PI_WEB_AGENT_FIRECRAWL_API_KEY,
-            options: config.fetch.options
-          })
-        })
-      : createHttpFetch({ fetchPage: invalidFirecrawlFetch() })
-    : httpFetch;
-
-  if (config.fetch.provider === 'firecrawl' && config.fetch.fallback === 'http') {
-    fetchPage = withFetchFallback(fetchPage, httpFetch);
-  }
-
-  return {
-    search,
-    fetchPage,
-    headlessFetch: createHeadlessFetch()
-  };
-}
+import { createFirecrawlFetcher } from '../fetch/firecrawl-fetch.js';
+import { createBraveSearchTool } from '../search/brave.js';
+import { createSearxngSearchTool } from '../search/searxng.js';
+import { buildFetchPresentation } from '../presentation/fetch-presentation.js';
+import { buildSearchPresentation } from '../presentation/search-presentation.js';
+import { createWebFetchHeadlessTool } from '../tools/web-fetch-headless.js';
+import { createWebFetchTool } from '../tools/web-fetch.js';
+import { createWebSearchTool } from '../tools/web-search.js';
+import { readBraveKeyFromSettings } from './settings-reader.js';
+import type { WebFetchHeadlessResponse, WebFetchResponse, WebSearchResponse } from '../types.js';
+import { DEFAULT_BACKEND_CONFIG, type BackendConfig } from './config.js';
+
+export type BackendSet = {
+  search: (input: { query: string }) => Promise<WebSearchResponse>;
+  fetchPage: (input: { url: string }) => Promise<WebFetchResponse>;
+  headlessFetch: (input: { url: string }) => Promise<WebFetchHeadlessResponse>;
+};
+
+export type BackendFactoryDeps = {
+  createDuckDuckGoSearch?: typeof createWebSearchTool;
+  createSearxngSearch?: typeof createSearxngSearchTool;
+  createBraveSearch?: typeof createBraveSearchTool;
+  createHttpFetch?: typeof createWebFetchTool;
+  createFirecrawlFetch?: typeof createFirecrawlFetcher;
+  createHeadlessFetch?: typeof createWebFetchHeadlessTool;
+};
+
+function invalidSearxngSearch() {
+  return async function search() {
+    const result: WebSearchResponse = {
+      status: 'error',
+      results: [],
+      metadata: { backend: 'searxng', cacheHit: false },
+      error: {
+        code: 'BACKEND_CONFIG_INVALID',
+        message: 'SearXNG search requires backends.search.baseUrl.'
+      }
+    };
+
+    return { ...result, presentation: buildSearchPresentation(result) };
+  };
+}
+
+function invalidFirecrawlFetch() {
+  return async function fetchPage(url: string): Promise<WebFetchResponse> {
+    const result: WebFetchResponse = {
+      status: 'error',
+      url,
+      metadata: { method: 'firecrawl', cacheHit: false },
+      error: {
+        code: 'BACKEND_CONFIG_INVALID',
+        message: 'Firecrawl fetch requires backends.fetch.baseUrl.'
+      }
+    };
+
+    return { ...result, presentation: buildFetchPresentation(result) };
+  };
+}
+
+function withSearchFallback(
+  primary: BackendSet['search'],
+  fallback: BackendSet['search'],
+  fallbackFrom: 'searxng' | 'brave'
+): BackendSet['search'] {
+  return async (input) => {
+    const first = await primary(input);
+    if (first.status !== 'error') return first;
+
+    const second = await fallback(input);
+    const result: WebSearchResponse = {
+      ...second,
+      metadata: {
+        ...second.metadata,
+        fallbackFrom,
+        fallbackReason: first.error?.message ?? `${fallbackFrom} search failed.`
+      }
+    };
+    return { ...result, presentation: buildSearchPresentation(result) };
+  };
+}
+
+function withFetchFallback(
+  primary: BackendSet['fetchPage'],
+  fallback: BackendSet['fetchPage']
+): BackendSet['fetchPage'] {
+  return async (input) => {
+    const first = await primary(input);
+    if (first.status !== 'error' && first.status !== 'needs_headless') return first;
+
+    const second = await fallback(input);
+    const result: WebFetchResponse = {
+      ...second,
+      metadata: {
+        ...second.metadata,
+        fallbackFrom: 'firecrawl',
+        fallbackReason: first.error?.message ?? 'Firecrawl fetch failed.'
+      }
+    };
+    return { ...result, presentation: buildFetchPresentation(result) };
+  };
+}
+
+export function createBackendSet(
+  config: BackendConfig = DEFAULT_BACKEND_CONFIG,
+  deps: BackendFactoryDeps = {}
+): BackendSet {
+  const createDuckDuckGoSearch = deps.createDuckDuckGoSearch ?? createWebSearchTool;
+  const createSearxngSearch = deps.createSearxngSearch ?? createSearxngSearchTool;
+  const createBraveSearch = deps.createBraveSearch ?? createBraveSearchTool;
+  const createHttpFetch = deps.createHttpFetch ?? createWebFetchTool;
+  const createFirecrawlFetch = deps.createFirecrawlFetch ?? createFirecrawlFetcher;
+  const createHeadlessFetch = deps.createHeadlessFetch ?? createWebFetchHeadlessTool;
+
+  let search = config.search.provider === 'searxng'
+    ? config.search.baseUrl
+      ? createSearxngSearch({ baseUrl: config.search.baseUrl, options: config.search.options })
+      : invalidSearxngSearch()
+    : config.search.provider === 'brave'
+      ? createBraveSearch({ apiKey: process.env.PI_WEB_AGENT_BRAVE_API_KEY ?? readBraveKeyFromSettings() })
+      : createDuckDuckGoSearch();
+
+  if (config.search.provider === 'searxng' && config.search.fallback === 'duckduckgo') {
+    search = withSearchFallback(search, createDuckDuckGoSearch(), 'searxng');
+  }
+
+  if (config.search.provider === 'brave' && config.search.fallback === 'duckduckgo') {
+    search = withSearchFallback(search, createDuckDuckGoSearch(), 'brave');
+  }
+
+  const httpFetch = createHttpFetch();
+  let fetchPage = config.fetch.provider === 'firecrawl'
+    ? config.fetch.baseUrl
+      ? createHttpFetch({
+          fetchPage: createFirecrawlFetch({
+            baseUrl: config.fetch.baseUrl,
+            apiKey: config.fetch.apiKey ?? process.env.PI_WEB_AGENT_FIRECRAWL_API_KEY,
+            options: config.fetch.options
+          })
+        })
+      : createHttpFetch({ fetchPage: invalidFirecrawlFetch() })
+    : httpFetch;
+
+  if (config.fetch.provider === 'firecrawl' && config.fetch.fallback === 'http') {
+    fetchPage = withFetchFallback(fetchPage, httpFetch);
+  }
+
+  return {
+    search,
+    fetchPage,
+    headlessFetch: createHeadlessFetch()
+  };
+}

package/dist/extensions/pi-web-agent/src/backends/settings-reader.ts

@@ -1,25 +1,25 @@
-// ponytail: selesai stores the Brave API key in settings.json (webAgent.braveApiKey),
-// set by the bundled web-agent-onboarding extension. Upstream pi-web-agent reads the
-// key only from PI_WEB_AGENT_BRAVE_API_KEY env var. This helper bridges that gap with a
-// minimal settings.json read. Ceiling: if selesai moves web search config elsewhere, this
-// helper needs updating; upgrade path = upstream pi-web-agent adopting a settings hook.
-import { existsSync, readFileSync } from 'node:fs';
-import { getSettingsPath } from '@selesai/code';
-
-/**
- * Read the Brave API key from selesai settings.json (webAgent.braveApiKey).
- * Returns undefined if settings.json or the key is absent. Never throws.
- */
-export function readBraveKeyFromSettings(settingsPath: string = getSettingsPath()): string | undefined {
-	try {
-		if (!existsSync(settingsPath)) return undefined;
-		const raw = readFileSync(settingsPath, 'utf-8');
-		const parsed = JSON.parse(raw) as Record<string, unknown>;
-		const webAgent = parsed.webAgent;
-		if (!webAgent || typeof webAgent !== 'object' || Array.isArray(webAgent)) return undefined;
-		const apiKey = (webAgent as Record<string, unknown>).braveApiKey;
-		return typeof apiKey === 'string' && apiKey.trim() !== '' ? apiKey : undefined;
-	} catch {
-		return undefined;
-	}
-}
+// ponytail: selesai stores the Brave API key in settings.json (webAgent.braveApiKey),
+// set by the bundled web-agent-onboarding extension. Upstream pi-web-agent reads the
+// key only from PI_WEB_AGENT_BRAVE_API_KEY env var. This helper bridges that gap with a
+// minimal settings.json read. Ceiling: if selesai moves web search config elsewhere, this
+// helper needs updating; upgrade path = upstream pi-web-agent adopting a settings hook.
+import { existsSync, readFileSync } from 'node:fs';
+import { getSettingsPath } from '@selesai/code';
+
+/**
+ * Read the Brave API key from selesai settings.json (webAgent.braveApiKey).
+ * Returns undefined if settings.json or the key is absent. Never throws.
+ */
+export function readBraveKeyFromSettings(settingsPath: string = getSettingsPath()): string | undefined {
+	try {
+		if (!existsSync(settingsPath)) return undefined;
+		const raw = readFileSync(settingsPath, 'utf-8');
+		const parsed = JSON.parse(raw) as Record<string, unknown>;
+		const webAgent = parsed.webAgent;
+		if (!webAgent || typeof webAgent !== 'object' || Array.isArray(webAgent)) return undefined;
+		const apiKey = (webAgent as Record<string, unknown>).braveApiKey;
+		return typeof apiKey === 'string' && apiKey.trim() !== '' ? apiKey : undefined;
+	} catch {
+		return undefined;
+	}
+}