@oh-my-pi/pi-coding-agent 13.2.0 → 13.3.0

package/src/web/scrapers/musicbrainz.ts

@@ -1,8 +1,10 @@
 /**
  * MusicBrainz URL handler for artists, releases, and recordings
  */
+
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, formatMediaDuration, loadPage, tryParseJson } from "./types";
+import { buildResult, formatMediaDuration, loadPage } from "./types";
 
 type MusicBrainzEntity = "artist" | "release" | "recording";
 

package/src/web/scrapers/npm.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, formatNumber, loadPage, tryParseJson } from "./types";
+import { buildResult, formatNumber, loadPage } from "./types";
 
 /**
  * Handle npm URLs via registry API

package/src/web/scrapers/nuget.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, formatIsoDate, formatNumber, loadPage, tryParseJson } from "./types";
+import { buildResult, formatIsoDate, formatNumber, loadPage } from "./types";
 
 interface NuGetCatalogEntry {
 	id: string;

package/src/web/scrapers/nvd.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, formatIsoDate, loadPage, tryParseJson } from "./types";
+import { buildResult, formatIsoDate, loadPage } from "./types";
 
 interface CvssV31 {
 	baseScore: number;

package/src/web/scrapers/ollama.ts

@@ -1,6 +1,7 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import { formatBytes } from "../../tools/render-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, decodeHtmlEntities, loadPage, tryParseJson } from "./types";
+import { buildResult, decodeHtmlEntities, loadPage } from "./types";
 
 interface OllamaTagDetails {
 	parent_model?: string;

package/src/web/scrapers/open-vsx.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, formatNumber, loadPage, tryParseJson } from "./types";
+import { buildResult, formatNumber, loadPage } from "./types";
 
 interface OpenVsxFileLinks {
 	readme?: string;

package/src/web/scrapers/opencorporates.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, loadPage, tryParseJson } from "./types";
+import { buildResult, loadPage } from "./types";
 
 interface Officer {
 	id: number;

package/src/web/scrapers/openlibrary.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, loadPage, tryParseJson } from "./types";
+import { buildResult, loadPage } from "./types";
 
 interface OpenLibraryAuthor {
 	name?: string;

package/src/web/scrapers/orcid.ts

@@ -1,8 +1,10 @@
 /**
  * ORCID handler for web-fetch
  */
+
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, loadPage, tryParseJson } from "./types";
+import { buildResult, loadPage } from "./types";
 
 const MAX_WORKS = 50;
 const ORCID_PATTERN = /\/(\d{4}-\d{4}-\d{4}-\d{3}[\dXx])(?:\/|$)/;

package/src/web/scrapers/osv.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, formatIsoDate, loadPage, tryParseJson } from "./types";
+import { buildResult, formatIsoDate, loadPage } from "./types";
 
 interface OsvSeverity {
 	type: string;

package/src/web/scrapers/packagist.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, formatNumber, loadPage, tryParseJson } from "./types";
+import { buildResult, formatNumber, loadPage } from "./types";
 
 /**
  * Handle Packagist URLs via JSON API

package/src/web/scrapers/pub-dev.ts

@@ -1,4 +1,5 @@
-import { buildResult, formatNumber, htmlToBasicMarkdown, loadPage, type SpecialHandler, tryParseJson } from "./types";
+import { tryParseJson } from "@oh-my-pi/pi-utils";
+import { buildResult, formatNumber, htmlToBasicMarkdown, loadPage, type SpecialHandler } from "./types";
 
 /**
  * Handle pub.dev URLs via API

package/src/web/scrapers/pubmed.ts

@@ -1,7 +1,8 @@
 /**
  * PubMed handler for web-fetch
  */
-import { buildResult, loadPage, type RenderResult, type SpecialHandler, tryParseJson } from "./types";
+import { tryParseJson } from "@oh-my-pi/pi-utils";
+import { buildResult, loadPage, type RenderResult, type SpecialHandler } from "./types";
 
 const NCBI_HEADERS = {
 	Accept: "application/json, text/plain;q=0.9, */*;q=0.8",

package/src/web/scrapers/pypi.ts

@@ -1,4 +1,5 @@
-import { buildResult, formatNumber, loadPage, type RenderResult, type SpecialHandler, tryParseJson } from "./types";
+import { tryParseJson } from "@oh-my-pi/pi-utils";
+import { buildResult, formatNumber, loadPage, type RenderResult, type SpecialHandler } from "./types";
 
 /**
  * Handle PyPI URLs via JSON API

package/src/web/scrapers/rawg.ts

@@ -1,11 +1,5 @@
-import {
-	buildResult,
-	htmlToBasicMarkdown,
-	loadPage,
-	type RenderResult,
-	type SpecialHandler,
-	tryParseJson,
-} from "./types";
+import { tryParseJson } from "@oh-my-pi/pi-utils";
+import { buildResult, htmlToBasicMarkdown, loadPage, type RenderResult, type SpecialHandler } from "./types";
 
 interface RawgPlatformEntry {
 	platform?: {

package/src/web/scrapers/reddit.ts

@@ -1,4 +1,5 @@
-import { buildResult, formatIsoDate, loadPage, type RenderResult, type SpecialHandler, tryParseJson } from "./types";
+import { tryParseJson } from "@oh-my-pi/pi-utils";
+import { buildResult, formatIsoDate, loadPage, type RenderResult, type SpecialHandler } from "./types";
 
 interface RedditPost {
 	title: string;

package/src/web/scrapers/repology.ts

@@ -1,4 +1,5 @@
-import { buildResult, loadPage, type RenderResult, type SpecialHandler, tryParseJson } from "./types";
+import { tryParseJson } from "@oh-my-pi/pi-utils";
+import { buildResult, loadPage, type RenderResult, type SpecialHandler } from "./types";
 
 interface RepologyPackage {
 	repo: string;

package/src/web/scrapers/rfc.ts

@@ -1,4 +1,5 @@
-import { buildResult, loadPage, type RenderResult, type SpecialHandler, tryParseJson } from "./types";
+import { tryParseJson } from "@oh-my-pi/pi-utils";
+import { buildResult, loadPage, type RenderResult, type SpecialHandler } from "./types";
 
 interface RfcMetadata {
 	doc_id: string;

package/src/web/scrapers/rubygems.ts

@@ -1,4 +1,5 @@
-import { buildResult, formatNumber, loadPage, type RenderResult, type SpecialHandler, tryParseJson } from "./types";
+import { tryParseJson } from "@oh-my-pi/pi-utils";
+import { buildResult, formatNumber, loadPage, type RenderResult, type SpecialHandler } from "./types";
 
 interface RubyGemsDependency {
 	name: string;

package/src/web/scrapers/searchcode.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, formatNumber, loadPage, tryParseJson } from "./types";
+import { buildResult, formatNumber, loadPage } from "./types";
 
 interface SearchcodeResult {
 	id?: number | string;

package/src/web/scrapers/sec-edgar.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, loadPage, tryParseJson } from "./types";
+import { buildResult, loadPage } from "./types";
 
 interface SecFiling {
 	accessionNumber: string;

package/src/web/scrapers/semantic-scholar.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { SpecialHandler } from "./types";
-import { buildResult, formatNumber, loadPage, tryParseJson } from "./types";
+import { buildResult, formatNumber, loadPage } from "./types";
 
 interface SemanticScholarAuthor {
 	name: string;

package/src/web/scrapers/snapcraft.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, formatNumber, loadPage, tryParseJson } from "./types";
+import { buildResult, formatNumber, loadPage } from "./types";
 
 interface SnapcraftPublisher {
 	"display-name"?: string;

package/src/web/scrapers/sourcegraph.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, loadPage, tryParseJson } from "./types";
+import { buildResult, loadPage } from "./types";
 
 const GRAPHQL_ENDPOINT = "https://sourcegraph.com/.api/graphql";
 const GRAPHQL_HEADERS = {

package/src/web/scrapers/spdx.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, htmlToBasicMarkdown, loadPage, tryParseJson } from "./types";
+import { buildResult, htmlToBasicMarkdown, loadPage } from "./types";
 
 interface SpdxCrossRef {
 	url?: string;

package/src/web/scrapers/stackoverflow.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, formatIsoDate, htmlToBasicMarkdown, loadPage, tryParseJson } from "./types";
+import { buildResult, formatIsoDate, htmlToBasicMarkdown, loadPage } from "./types";
 
 interface SOQuestion {
 	title: string;

package/src/web/scrapers/terraform.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, formatNumber, loadPage, tryParseJson } from "./types";
+import { buildResult, formatNumber, loadPage } from "./types";
 
 interface TerraformModule {
 	id: string;

package/src/web/scrapers/types.ts

@@ -190,17 +190,6 @@ export function htmlToBasicMarkdown(html: string): string {
 	return decodeHtmlEntities(stripped);
 }
 
-/**
- * Try to parse JSON, returning null on failure.
- */
-export function tryParseJson<T = unknown>(content: string): T | null {
-	try {
-		return JSON.parse(content) as T;
-	} catch {
-		return null;
-	}
-}
-
 /**
  * Build a RenderResult from markdown content. Calls finalizeOutput internally.
  */

package/src/web/scrapers/vimeo.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { SpecialHandler } from "./types";
-import { buildResult, formatMediaDuration, loadPage, tryParseJson } from "./types";
+import { buildResult, formatMediaDuration, loadPage } from "./types";
 
 interface VimeoOEmbed {
 	title: string;

package/src/web/scrapers/vscode-marketplace.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, formatNumber, loadPage, tryParseJson } from "./types";
+import { buildResult, formatNumber, loadPage } from "./types";
 
 interface MarketplaceProperty {
 	key?: string;

package/src/web/scrapers/w3c.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, htmlToBasicMarkdown, loadPage, tryParseJson } from "./types";
+import { buildResult, htmlToBasicMarkdown, loadPage } from "./types";
 import { asRecord } from "./utils";
 
 type JsonRecord = Record<string, unknown>;

package/src/web/scrapers/wikidata.ts

@@ -1,5 +1,6 @@
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, formatNumber, loadPage, tryParseJson } from "./types";
+import { buildResult, formatNumber, loadPage } from "./types";
 
 /**
  * Common Wikidata property IDs mapped to human-readable names

package/src/web/search/index.ts

@@ -353,13 +353,6 @@ async function executeExaTool(
 ): Promise<{ content: Array<{ type: "text"; text: string }>; details: ExaRenderDetails }> {
 	try {
 		const apiKey = await findExaKey();
-		if (!apiKey) {
-			return {
-				content: [{ type: "text" as const, text: "Error: EXA_API_KEY not found" }],
-				details: { error: "EXA_API_KEY not found", toolName },
-			};
-		}
-
 		const response = await callExaTool(mcpToolName, params, apiKey);
 
 		if (isSearchResponse(response)) {
@@ -402,7 +395,7 @@ Parameters:
 
 	async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
 		const { num_results, ...rest } = params as Record<string, unknown>;
-		const args = { ...rest, type: "deep", numResults: num_results ?? 10 };
+		const args = { ...rest, type: "auto", numResults: num_results ?? 10 };
 		return executeExaTool("web_search_exa", args, "web_search_deep");
 	},
 
@@ -462,7 +455,7 @@ Parameters:
 	parameters: webSearchCrawlSchema,
 
 	async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
-		return executeExaTool("crawling", params as Record<string, unknown>, "web_search_crawl");
+		return executeExaTool("crawling_exa", params as Record<string, unknown>, "web_search_crawl");
 	},
 
 	renderCall(args, _options, theme) {
@@ -493,7 +486,7 @@ Parameters:
 	parameters: webSearchLinkedinSchema,
 
 	async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
-		return executeExaTool("linkedin_search", params as Record<string, unknown>, "web_search_linkedin");
+		return executeExaTool("linkedin_search_exa", params as Record<string, unknown>, "web_search_linkedin");
 	},
 
 	renderCall(args, _options, theme) {
@@ -523,7 +516,7 @@ Parameters:
 	parameters: webSearchCompanySchema,
 
 	async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
-		return executeExaTool("company_research", params as Record<string, unknown>, "web_search_company");
+		return executeExaTool("company_research_exa", params as Record<string, unknown>, "web_search_company");
 	},
 
 	renderCall(args, _options, theme) {
@@ -561,17 +554,20 @@ export interface SearchToolsOptions {
  *
  * Returns:
  * - Always: web_search (unified, works with Anthropic/Perplexity/Exa)
- * - With EXA_API_KEY: web_search_deep, web_search_code_context, web_search_crawl
+ * - Always: web_search_deep, web_search_code_context (public Exa MCP tools)
+ * - With EXA_API_KEY: web_search_crawl
  * - With EXA_API_KEY + options.enableLinkedin: web_search_linkedin
  * - With EXA_API_KEY + options.enableCompany: web_search_company
  */
 export async function getSearchTools(options: SearchToolsOptions = {}): Promise<CustomTool<any, any>[]> {
 	const tools: CustomTool<any, any>[] = [webSearchCustomTool];
 
-	// Check for Exa API key
+	tools.push(webSearchDeepTool, webSearchCodeContextTool);
+
+	// Advanced/add-on tools remain key-gated to avoid exposing known unauthenticated failures
 	const exaKey = await findExaKey();
 	if (exaKey) {
-		tools.push(...exaSearchTools);
+		tools.push(webSearchCrawlTool);
 
 		if (options.enableLinkedin) {
 			tools.push(...linkedinSearchTools);

package/src/web/search/provider.ts

@@ -29,7 +29,6 @@ const SEARCH_PROVIDERS: Record<SearchProviderId, SearchProvider> = {
 
 export const SEARCH_PROVIDER_ORDER: SearchProviderId[] = [
 	"perplexity",
-	"exa",
 	"brave",
 	"jina",
 	"kimi",
@@ -37,6 +36,7 @@ export const SEARCH_PROVIDER_ORDER: SearchProviderId[] = [
 	"gemini",
 	"codex",
 	"zai",
+	"exa",
 	"synthetic",
 ];
 
@@ -52,7 +52,7 @@ export function setPreferredSearchProvider(provider: SearchProviderId | "auto"):
 	preferredProvId = provider;
 }
 
-/** Determine which providers are configured (priority: Perplexity → Exa → Brave → Jina → Kimi → Anthropic → Gemini → Codex → Z.AI → Synthetic) */
+/** Determine which providers are configured (priority: Perplexity → Brave → Jina → Kimi → Anthropic → Gemini → Codex → Z.AI → Exa → Synthetic) */
 export async function resolveProviderChain(
 	preferredProvider: SearchProviderId | "auto" = preferredProvId,
 ): Promise<SearchProvider[]> {

package/src/web/search/providers/codex.ts

@@ -6,8 +6,7 @@
  * Returns synthesized answers with web search sources.
  */
 import * as os from "node:os";
-import { readSseJson } from "@oh-my-pi/pi-utils";
-import { getAgentDbPath } from "@oh-my-pi/pi-utils/dirs";
+import { getAgentDbPath, readSseJson } from "@oh-my-pi/pi-utils";
 import packageJson from "../../../../package.json" with { type: "json" };
 import { AgentStorage } from "../../../session/agent-storage";
 import type { SearchResponse, SearchSource } from "../../../web/search/types";

package/src/web/search/providers/exa.ts

@@ -3,9 +3,10 @@
  *
  * High-quality neural search via Exa Search API.
  * Returns structured search results with optional content extraction.
+ * Requests per-result summaries via `contents.summary` and synthesizes
+ * them into a combined `answer` string on the SearchResponse.
  */
 import { getEnvApiKey } from "@oh-my-pi/pi-ai";
-import { findApiKey as findExaKey } from "../../../exa/mcp-client";
 import type { SearchResponse, SearchSource } from "../../../web/search/types";
 import { SearchProviderError } from "../../../web/search/types";
 import { dateToAgeSeconds } from "../utils";
@@ -35,6 +36,7 @@ interface ExaSearchResult {
 	publishedDate?: string | null;
 	text?: string | null;
 	highlights?: string[] | null;
+	summary?: string | null;
 }
 
 interface ExaSearchResponse {
@@ -45,18 +47,41 @@ interface ExaSearchResponse {
 	searchTime?: number;
 }
 
-function normalizeSearchType(type: ExaSearchParamType | undefined): ExaSearchType {
+export function normalizeSearchType(type: ExaSearchParamType | undefined): ExaSearchType {
 	if (!type) return "auto";
 	if (type === "keyword") return "fast";
 	return type;
 }
 
-/** Call Exa Search API */
-async function callExaSearch(apiKey: string, params: ExaSearchParams): Promise<ExaSearchResponse> {
+/** Maximum number of per-result summaries to include in the synthesized answer. */
+const MAX_ANSWER_SUMMARIES = 3;
+
+/**
+ * Synthesize an answer string from per-result summaries returned by Exa.
+ * Returns `undefined` when no non-empty summaries are available so callers
+ * can leave `SearchResponse.answer` unset (matching other providers).
+ */
+export function synthesizeAnswer(results: ExaSearchResult[]): string | undefined {
+	const parts: string[] = [];
+	for (const r of results) {
+		if (parts.length >= MAX_ANSWER_SUMMARIES) break;
+		const summary = r.summary?.trim();
+		if (!summary) continue;
+		const title = r.title?.trim() || r.url || "Untitled";
+		parts.push(`**${title}**: ${summary}`);
+	}
+	return parts.length > 0 ? parts.join("\n\n") : undefined;
+}
+
+/** Build the request body for `callExaSearch`. Exported for testing. */
+export function buildExaRequestBody(params: ExaSearchParams): Record<string, unknown> {
 	const body: Record<string, unknown> = {
 		query: params.query,
 		numResults: params.num_results ?? 10,
 		type: normalizeSearchType(params.type),
+		contents: {
+			summary: { query: params.query },
+		},
 	};
 
 	if (params.include_domains?.length) {
@@ -72,6 +97,13 @@ async function callExaSearch(apiKey: string, params: ExaSearchParams): Promise<E
 		body.endPublishedDate = params.end_published_date;
 	}
 
+	return body;
+}
+
+/** Call Exa Search API */
+async function callExaSearch(apiKey: string, params: ExaSearchParams): Promise<ExaSearchResponse> {
+	const body = buildExaRequestBody(params);
+
 	const response = await fetch(EXA_API_URL, {
 		method: "POST",
 		headers: {
@@ -107,7 +139,7 @@ export async function searchExa(params: ExaSearchParams): Promise<SearchResponse
 			sources.push({
 				title: result.title ?? result.url,
 				url: result.url,
-				snippet: result.text ?? result.highlights?.join(" ") ?? undefined,
+				snippet: result.summary || result.text || result.highlights?.join(" ") || undefined,
 				publishedDate: result.publishedDate ?? undefined,
 				ageSeconds: dateToAgeSeconds(result.publishedDate ?? undefined),
 				author: result.author ?? undefined,
@@ -118,8 +150,12 @@ export async function searchExa(params: ExaSearchParams): Promise<SearchResponse
 	// Apply num_results limit if specified
 	const limitedSources = params.num_results ? sources.slice(0, params.num_results) : sources;
 
+	// Synthesize answer only from results that have a URL (same guard as sources loop)
+	const answer = response.results ? synthesizeAnswer(response.results.filter(r => !!r.url)) : undefined;
+
 	return {
 		provider: "exa",
+		answer,
 		sources: limitedSources,
 		requestId: response.requestId,
 	};
@@ -131,11 +167,7 @@ export class ExaProvider extends SearchProvider {
 	readonly label = "Exa";
 
 	isAvailable(): boolean {
-		try {
-			return !!findExaKey();
-		} catch {
-			return false;
-		}
+		return true;
 	}
 
 	search(params: SearchParams): Promise<SearchResponse> {

package/src/web/search/providers/gemini.ts

@@ -6,7 +6,7 @@
  * Returns synthesized answers with citations and source metadata from grounding chunks.
  */
 import { getAntigravityHeaders, getGeminiCliHeaders, refreshGoogleCloudToken } from "@oh-my-pi/pi-ai";
-import { getAgentDbPath } from "@oh-my-pi/pi-utils/dirs";
+import { getAgentDbPath } from "@oh-my-pi/pi-utils";
 import { AgentStorage } from "../../../session/agent-storage";
 import type { SearchCitation, SearchResponse, SearchSource } from "../../../web/search/types";
 import { SearchProviderError } from "../../../web/search/types";

package/src/web/search/providers/perplexity.ts

@@ -1,14 +1,14 @@
 /**
  * Perplexity Web Search Provider
  *
- * Supports two auth modes:
- * - API key (`PERPLEXITY_API_KEY`) via `api.perplexity.ai/chat/completions`
+ * Supports three auth modes:
+ * - Cookies (`PERPLEXITY_COOKIES`) via `www.perplexity.ai/rest/sse/perplexity_ask`
  * - OAuth JWT (stored in `agent.db`) via `www.perplexity.ai/rest/sse/perplexity_ask`
+ * - API key (`PERPLEXITY_API_KEY`) via `api.perplexity.ai/chat/completions`
  */
 
 import { getEnvApiKey } from "@oh-my-pi/pi-ai";
-import { readSseJson } from "@oh-my-pi/pi-utils";
-import { getAgentDbPath } from "@oh-my-pi/pi-utils/dirs";
+import { $env, getAgentDbPath, readSseJson } from "@oh-my-pi/pi-utils";
 import { AgentStorage } from "../../../session/agent-storage";
 import type {
 	PerplexityMessageOutput,
@@ -47,6 +47,10 @@ type PerplexityAuth =
 	| {
 			type: "oauth";
 			token: string;
+	  }
+	| {
+			type: "cookies";
+			cookies: string;
 	  };
 
 interface PerplexityOAuthStreamMarkdownBlock {
@@ -189,10 +193,17 @@ async function findOAuthToken(): Promise<string | null> {
 }
 
 async function findPerplexityAuth(): Promise<PerplexityAuth | null> {
+	// 1. PERPLEXITY_COOKIES env var
+	const cookies = $env.PERPLEXITY_COOKIES?.trim();
+	if (cookies) {
+		return { type: "cookies", cookies };
+	}
+	// 2. OAuth token from agent.db
 	const oauthToken = await findOAuthToken();
 	if (oauthToken) {
 		return { type: "oauth", token: oauthToken };
 	}
+	// 3. PERPLEXITY_API_KEY env var
 	const apiKey = findApiKey();
 	if (apiKey) {
 		return { type: "api_key", token: apiKey };
@@ -290,7 +301,7 @@ function buildOAuthAnswer(event: PerplexityOAuthStreamEvent): string {
 }
 
 async function callPerplexityOAuth(
-	oauthToken: string,
+	auth: { type: "oauth"; token: string } | { type: "cookies"; cookies: string },
 	params: PerplexitySearchParams,
 ): Promise<{ answer: string; sources: SearchSource[]; model?: string; requestId?: string }> {
 	const requestId = crypto.randomUUID();
@@ -299,7 +310,7 @@ async function callPerplexityOAuth(
 	const response = await fetch(PERPLEXITY_OAUTH_ASK_URL, {
 		method: "POST",
 		headers: {
-			Authorization: `Bearer ${oauthToken}`,
+			...(auth.type === "cookies" ? { Cookie: auth.cookies } : { Authorization: `Bearer ${auth.token}` }),
 			"Content-Type": "application/json",
 			Accept: "text/event-stream",
 			Origin: "https://www.perplexity.ai",
@@ -456,11 +467,11 @@ function applySourceLimit(result: SearchResponse, limit?: number): SearchRespons
 export async function searchPerplexity(params: PerplexitySearchParams): Promise<SearchResponse> {
 	const auth = await findPerplexityAuth();
 	if (!auth) {
-		throw new Error("Perplexity auth not found. Set PERPLEXITY_API_KEY or login via OAuth.");
+		throw new Error("Perplexity auth not found. Set PERPLEXITY_COOKIES, PERPLEXITY_API_KEY, or login via OAuth.");
 	}
 
-	if (auth.type === "oauth") {
-		const oauthResult = await callPerplexityOAuth(auth.token, params);
+	if (auth.type === "oauth" || auth.type === "cookies") {
+		const oauthResult = await callPerplexityOAuth(auth, params);
 		return applySourceLimit(
 			{
 				provider: "perplexity",

package/src/web/search/providers/utils.ts

@@ -1,4 +1,4 @@
-import { getAgentDbPath } from "@oh-my-pi/pi-utils/dirs";
+import { getAgentDbPath } from "@oh-my-pi/pi-utils";
 import { AgentStorage } from "../../../session/agent-storage";
 
 /**