@deepseek-ai/dsh-web-search-perplexity 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/web/web-search-perplexity/README.md
+README.md: 8800609a05e99d3fa8a61e12b2360e633f0fd330
+README.zh.md: fb20d796e9e943a5254b1d22eac3650e45ec95bf

package/README.md

@@ -0,0 +1,65 @@
+# @deepseek-ai/dsh-web-search-perplexity
+
+English | [中文](README.zh.md)
+
+A [Perplexity](https://perplexity.ai)-backed `WebSearchProvider` for the harness [web capability seam](../web/README.md) (`ctx.web`). It calls Perplexity's OpenAI-compatible `POST /chat/completions` endpoint and maps the generated answer plus citations into the seam's normalized `WebSearchResult`.
+
+This is an **implementation** package: it registers a provider into `ctx.web`, it does not own the key and it does not register a model-facing tool. Like `@deepseek-ai/dsh-llm-deepseek`, it is a function/namespace plugin (`inject: ['web']`). The OpenAI-compatible wire shape is a provider-private detail — it does **not** make this provider depend on `ctx.llm`.
+
+## Config
+
+| Key | Default | Meaning |
+|---|---|---|
+| `apiKey` | `$PERPLEXITY_API_KEY` | Perplexity API key. Empty/absent makes the provider unavailable. |
+| `baseURL` | `https://api.perplexity.ai` | Endpoint base; `/chat/completions` is appended. An unparseable value makes the provider unavailable. |
+| `model` | `sonar` | Search model name. |
+| `maxTokens` | `1024` | Upper bound on generated answer tokens (`max_tokens`). Must be a positive integer. |
+| `searchRecency` | (unset) | Recency window sent as `search_recency_filter`: `day`, `week`, `month`, or `year`. Unset sends no filter. |
+
+```yaml
+- id: web-search-perplexity
+  name: '@deepseek-ai/dsh-web-search-perplexity'
+  config:
+    apiKey: !!js process.env.PERPLEXITY_API_KEY
+```
+
+## Mapping
+
+`content` ← `choices[0].message.content` (the generated answer). `sources[]` prefers the structured `search_results[]` (`url`, `title`, `snippet`, `publishedAt` ← `date`), falling back to the URL-only `citations[]` array only when `search_results` is absent — those sources carry just a `url`, which is why `title`/`snippet`/`publishedAt` are optional on the seam. Provider failures surface as `WebError` `WEB_PROVIDER_ERROR`; an aborted request surfaces as `WEB_ABORTED`. HTTP redirects are rejected before the `Location` target is contacted and surface as `WEB_PROVIDER_ERROR`. Perplexity has no result-count control, so `maxResults` is enforced by the seam (truncating `sources[]` and setting `truncated`).
+
+## Model Experience
+
+### Auxiliary Perplexity request
+
+#### What the model sees
+
+A separate Perplexity model receives `<query>` verbatim as its sole user message through the chat-completions endpoint. This request is not part of the conversation model's context.
+
+#### Token effect
+
+Separate provider tokens are incurred per search; `maxTokens` caps the generated answer.
+
+#### KV Cache effect
+
+Independent of the conversation request cache. An identical query under the same model route may reuse provider cache; a changed query or route establishes a different prefix.
+
+### Conversation tool result, indirectly
+
+#### What the model sees
+
+Through [`dsh-tool-web`](../tool-web/README.md), the conversation model sees the generated answer plus structured result metadata or URL-only citations. This provider's exact failures are `Perplexity search aborted`, `Perplexity search request failed: <error>`, and `Perplexity returned an unprocessable response body: <error>`; HTTP failures preserve the provider message. The consumer owns the error wrapper.
+
+#### Token effect
+
+Zero direct conversation tokens from registration. Answer and source tokens are data-dependent, source count is service-bounded, and the retained result or error is resent until compaction.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **Citation-fallback sources are URL-only** — when Perplexity omits structured `search_results[]`, sources carry no `title`/`snippet`/`publishedAt`, so the tool renders bare hostname labels.
+- **Over-returned sources still cost tokens and latency** — with no result-count control on the wire, `maxResults` is enforced only post-hoc by seam truncation.
+- **Only `model`/`maxTokens`/`searchRecency` are exposed** — Perplexity's other search controls (domain filters, `web_search_options` context size, images) wait on provider-neutral Service Definition fields ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)).
+- **Abort classification is error-shape-based** — only a `DOMException` named `AbortError` maps to `WEB_ABORTED`; an abort carrying a custom reason (e.g. `dsh-timeout`'s `TimeoutReason`) surfaces as `WEB_PROVIDER_ERROR`.

package/README.zh.md

@@ -0,0 +1,65 @@
+# @deepseek-ai/dsh-web-search-perplexity
+
+[English](README.md) | 中文
+
+由 [Perplexity](https://perplexity.ai) 支持的 `WebSearchProvider`，用于 harness [web 能力 seam](../web/README.md)（`ctx.web`）。它调用 Perplexity 的 OpenAI 兼容 `POST /chat/completions` 端点，把生成答案与引用映射为 seam 规范化的 `WebSearchResult`。
+
+这是一个**实现**包：它向 `ctx.web` 注册提供方，不拥有该键，也不注册面向模型的工具。与 `@deepseek-ai/dsh-llm-deepseek` 一样，它是函数／命名空间插件（`inject: ['web']`）。OpenAI 兼容协议格式（wire format）是提供方私有细节，并**不**使该提供方依赖 `ctx.llm`。
+
+## 配置
+
+| 配置键 | 默认值 | 含义 |
+|---|---|---|
+| `apiKey` | `$PERPLEXITY_API_KEY` | Perplexity API 密钥。为空或缺失时提供方不可用。 |
+| `baseURL` | `https://api.perplexity.ai` | 端点基址；追加 `/chat/completions`。无法解析时提供方不可用。 |
+| `model` | `sonar` | 搜索模型名称。 |
+| `maxTokens` | `1024` | 生成答案 token 上限（`max_tokens`）。必须是正整数。 |
+| `searchRecency` | （未设置） | 以 `search_recency_filter` 发送的新近程度窗口：`day`、`week`、`month` 或 `year`。未设置时不发送过滤条件。 |
+
+```yaml
+- id: web-search-perplexity
+  name: '@deepseek-ai/dsh-web-search-perplexity'
+  config:
+    apiKey: !!js process.env.PERPLEXITY_API_KEY
+```
+
+## 映射
+
+`content` ← `choices[0].message.content`（生成答案）。`sources[]` 优先使用结构化 `search_results[]`（`url`、`title`、`snippet`、`publishedAt` ← `date`），否则回退到只含 URL 的 `citations[]` 数组；仅当不存在 `search_results` 时才采取这条回退路径。这些源只携带 `url`，因此 seam 上的 `title`／`snippet`／`publishedAt` 是可选字段。提供方失败以 `WebError` `WEB_PROVIDER_ERROR` 呈现；中止请求以 `WEB_ABORTED` 呈现。HTTP 重定向会在访问 `Location` 指向的目标之前被拒绝，并以 `WEB_PROVIDER_ERROR` 呈现。Perplexity 没有结果数量控制，因此 seam 会强制执行 `maxResults`（截断 `sources[]` 并设置 `truncated`）。
+
+## 模型体验
+
+### 辅助 Perplexity 请求
+
+#### 模型看到的内容
+
+独立的 Perplexity 模型通过 chat-completions 端点将 `<query>` 原样作为唯一用户消息接收。该请求不属于会话模型上下文。
+
+#### Token 影响
+
+每次搜索会产生独立的提供方 token；`maxTokens` 限制生成答案。
+
+#### KV Cache 影响
+
+与会话请求缓存相互独立。同一模型路由下的相同查询可能复用提供方缓存；查询或路由改变会建立不同前缀。
+
+### 间接的会话工具结果
+
+#### 模型看到的内容
+
+通过 [`dsh-tool-web`](../tool-web/README.md)，会话模型会看到生成答案及结构化结果元数据，或只含 URL 的引用。该提供方确切的错误消息为 `Perplexity search aborted`、`Perplexity search request failed: <error>` 和 `Perplexity returned an unprocessable response body: <error>`；HTTP 失败保留提供方消息。错误包装层属于消费方。
+
+#### Token 影响
+
+注册不会直接产生会话 token。答案与源 token 取决于数据，源数量受服务限制；保留的结果或错误会重复发送，直到发生压缩（compaction）。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+## 已知限制与暂缓事项
+
+- **引用回退源只含 URL**：Perplexity 省略结构化 `search_results[]` 时，源不含 `title`／`snippet`／`publishedAt`，因此工具只渲染纯主机名标签。
+- **超量返回的来源仍会增加 token 消耗和延迟**：协议没有结果数量控制，`maxResults` 只能由 seam 在事后截断。
+- **只公开 `model`／`maxTokens`／`searchRecency`**：Perplexity 的其他搜索控制项（域名过滤条件、`web_search_options` 上下文大小、图片）等待提供方无关的 Service Definition 字段（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)）。
+- **按错误形状分类中止**：只有 `DOMException` 且名为 `AbortError` 时才映射为 `WEB_ABORTED`；携带自定义原因的中止（例如 `dsh-timeout` 的 `TimeoutReason`）会呈现为 `WEB_PROVIDER_ERROR`。

package/lib/index.js

@@ -0,0 +1,154 @@
+import { environmentOf } from "@deepseek-ai/dsh-environment";
+import z from "@deepseek-ai/schemastery";
+import { WebError } from "@deepseek-ai/dsh-web";
+//#region lib/types/provider.js
+/**
+* Perplexity search over its OpenAI-compatible chat-completions endpoint. The generated answer
+* becomes `content`; sources prefer structured `search_results[]` and fall back to URL-only
+* `citations[]`. The wire format and native `fetch` client are provider-private and do not use
+* `ctx.llm`.
+* @module @deepseek-ai/dsh-web-search-perplexity/provider
+*/
+/** Stable id this provider registers under. */
+const PERPLEXITY_PROVIDER_ID = "perplexity";
+/** Default Perplexity endpoint; `/chat/completions` is the operation. */
+const PERPLEXITY_DEFAULT_BASE_URL = "https://api.perplexity.ai";
+/** Default search model. */
+const PERPLEXITY_DEFAULT_MODEL = "sonar";
+/** Default upper bound on generated answer tokens. */
+const PERPLEXITY_DEFAULT_MAX_TOKENS = 1024;
+/** Attribution header sent on every request. Bump with the package version. */
+const USER_AGENT = "deepseek-harness/0.0.1";
+/**
+* Map one structured Perplexity search result to a normalized source.
+*
+* @param result - one entry of the response's `search_results[]`.
+* @returns the normalized source; blank fields are omitted rather than set empty.
+*/
+function mapPerplexityResult(result) {
+	return {
+		url: result.url,
+		...result.title != null && result.title.length > 0 ? { title: result.title } : {},
+		...result.snippet != null && result.snippet.length > 0 ? { snippet: result.snippet } : {},
+		...result.date != null && result.date.length > 0 ? { publishedAt: result.date } : {}
+	};
+}
+/**
+* Map a Perplexity response envelope to a normalized search result. Prefers
+* structured `search_results[]`; falls back to URL-only `citations[]` (those
+* sources carry just a `url`) only when `search_results` is absent.
+*
+* @param response - the parsed chat-completions response body.
+* @returns the normalized result; `content` is omitted when the answer is empty.
+*/
+function mapPerplexityResponse(response) {
+	const content = response.choices?.[0]?.message?.content;
+	const sources = response.search_results !== void 0 ? response.search_results.map(mapPerplexityResult) : (response.citations ?? []).map((url) => ({ url }));
+	return {
+		...content != null && content.length > 0 ? { content } : {},
+		sources,
+		truncated: false
+	};
+}
+/** The Perplexity-backed search provider; HTTP redirects fail as `WEB_PROVIDER_ERROR`. */
+var PerplexitySearchProvider = class {
+	options;
+	id = PERPLEXITY_PROVIDER_ID;
+	constructor(options) {
+		this.options = options;
+	}
+	available() {
+		return this.options.apiKey.length > 0 && URL.canParse(this.options.baseURL) && isPositiveInteger(this.options.maxTokens);
+	}
+	async search(request, signal) {
+		let response;
+		try {
+			response = await fetch(`${this.options.baseURL}/chat/completions`, {
+				method: "POST",
+				redirect: "error",
+				headers: {
+					"authorization": `Bearer ${this.options.apiKey}`,
+					"content-type": "application/json",
+					"accept": "application/json",
+					"user-agent": USER_AGENT
+				},
+				body: JSON.stringify({
+					model: this.options.model,
+					max_tokens: this.options.maxTokens,
+					messages: [{
+						role: "user",
+						content: request.query
+					}],
+					...this.options.searchRecency !== void 0 ? { search_recency_filter: this.options.searchRecency } : {}
+				}),
+				...signal !== void 0 ? { signal } : {}
+			});
+		} catch (error) {
+			if (isAbortError(error)) throw new WebError("Perplexity search aborted", "WEB_ABORTED", { cause: error });
+			throw new WebError(`Perplexity search request failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+		if (!response.ok) {
+			let message = `Perplexity API error (HTTP ${response.status})`;
+			try {
+				const parsed = await response.json();
+				const detail = typeof parsed.error === "string" ? parsed.error : parsed.error?.message ?? parsed.message;
+				if (detail !== void 0 && detail.length > 0) message = detail;
+			} catch (error) {
+				if (isAbortError(error)) throw new WebError("Perplexity search aborted", "WEB_ABORTED", { cause: error });
+			}
+			throw new WebError(message, "WEB_PROVIDER_ERROR");
+		}
+		try {
+			return mapPerplexityResponse(await response.json());
+		} catch (error) {
+			if (isAbortError(error)) throw new WebError("Perplexity search aborted", "WEB_ABORTED", { cause: error });
+			throw new WebError(`Perplexity returned an unprocessable response body: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+	}
+};
+/** True for a fetch/`AbortSignal` abort, surfaced as `WEB_ABORTED`. */
+function isAbortError(error) {
+	return error instanceof DOMException && error.name === "AbortError";
+}
+/** True for a request limit that can be sent to Perplexity (a positive whole number). */
+function isPositiveInteger(value) {
+	return Number.isInteger(value) && value > 0;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* `@deepseek-ai/dsh-web-search-perplexity`: registers a Perplexity-backed
+* `WebSearchProvider` with `ctx.web`. A function/namespace plugin (NOT a
+* default-export service): it registers INTO the seam's provider registry, like
+* `@deepseek-ai/dsh-llm-deepseek` registers an adapter into `ctx.llm`.
+*
+* @module @deepseek-ai/dsh-web-search-perplexity
+*/
+/** Cordis plugin name used by loader diagnostics. */
+const name = "web-search-perplexity";
+/** The web seam this provider registers into. */
+const inject = ["web"];
+const Config = z.object({
+	apiKey: z.string(),
+	baseURL: z.string(),
+	model: z.string(),
+	maxTokens: z.number().step(1).min(1),
+	searchRecency: z.union([
+		"day",
+		"week",
+		"month",
+		"year"
+	])
+});
+/** Register the Perplexity search provider with `ctx.web`. */
+function apply(ctx, config) {
+	ctx.web.registerSearchProvider(new PerplexitySearchProvider({
+		apiKey: config.apiKey ?? environmentOf(ctx).get("PERPLEXITY_API_KEY")?.value ?? "",
+		baseURL: config.baseURL ?? "https://api.perplexity.ai",
+		model: config.model ?? "sonar",
+		maxTokens: config.maxTokens ?? 1024,
+		...config.searchRecency !== void 0 ? { searchRecency: config.searchRecency } : {}
+	}));
+}
+//#endregion
+export { Config, PERPLEXITY_DEFAULT_BASE_URL, PERPLEXITY_DEFAULT_MAX_TOKENS, PERPLEXITY_DEFAULT_MODEL, PERPLEXITY_PROVIDER_ID, PerplexitySearchProvider, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-web-search-perplexity`.
+* @module @deepseek-ai/dsh-web-search-perplexity/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-web-search-perplexity";
+/** Cordis companion plugin name. */
+const name = "web-search-perplexity-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this package exposes no independent event sequence or mutable data relation
+* beyond contracts enforced at its owning seam.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `@deepseek-ai/dsh-web-search-perplexity`: registers a Perplexity-backed
+ * `WebSearchProvider` with `ctx.web`. A function/namespace plugin (NOT a
+ * default-export service): it registers INTO the seam's provider registry, like
+ * `@deepseek-ai/dsh-llm-deepseek` registers an adapter into `ctx.llm`.
+ *
+ * @module @deepseek-ai/dsh-web-search-perplexity
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export { PERPLEXITY_DEFAULT_BASE_URL, PERPLEXITY_DEFAULT_MAX_TOKENS, PERPLEXITY_DEFAULT_MODEL, PERPLEXITY_PROVIDER_ID, PerplexitySearchProvider, } from './provider.ts';
+export type { PerplexityRecency, PerplexitySearchProviderOptions } from './provider.ts';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "web-search-perplexity";
+/** The web seam this provider registers into. */
+export declare const inject: string[];
+/** Plugin config (all optional — `apply` fills env-var and constant defaults). */
+export interface Config {
+    /** Perplexity API key. Falls back to `$PERPLEXITY_API_KEY`. Empty → unavailable. */
+    apiKey?: string;
+    /** Endpoint base; `/chat/completions` is appended. Defaults to the public API. */
+    baseURL?: string;
+    /** Search model name. Defaults to `sonar`. */
+    model?: string;
+    /** Upper bound on generated answer tokens. Defaults to 1024. */
+    maxTokens?: number;
+    /** Recency window sent as `search_recency_filter`. Omitted = no filter. */
+    searchRecency?: 'day' | 'week' | 'month' | 'year';
+}
+export declare const Config: z<Config>;
+/** Register the Perplexity search provider with `ctx.web`. */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-web-search-perplexity`.
+ * @module @deepseek-ai/dsh-web-search-perplexity/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "web-search-perplexity-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/provider.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Perplexity search over its OpenAI-compatible chat-completions endpoint. The generated answer
+ * becomes `content`; sources prefer structured `search_results[]` and fall back to URL-only
+ * `citations[]`. The wire format and native `fetch` client are provider-private and do not use
+ * `ctx.llm`.
+ * @module @deepseek-ai/dsh-web-search-perplexity/provider
+ */
+import type { WebSearchProvider, WebSearchRequest, WebSearchResult, WebSearchSource } from '@deepseek-ai/dsh-web';
+import type { PerplexityResponse, PerplexitySearchResult } from './types.ts';
+/** Stable id this provider registers under. */
+export declare const PERPLEXITY_PROVIDER_ID = "perplexity";
+/** Default Perplexity endpoint; `/chat/completions` is the operation. */
+export declare const PERPLEXITY_DEFAULT_BASE_URL = "https://api.perplexity.ai";
+/** Default search model. */
+export declare const PERPLEXITY_DEFAULT_MODEL = "sonar";
+/** Default upper bound on generated answer tokens. */
+export declare const PERPLEXITY_DEFAULT_MAX_TOKENS = 1024;
+/** Recency filter values Perplexity accepts for `search_recency_filter`. */
+export type PerplexityRecency = 'day' | 'week' | 'month' | 'year';
+/** Resolved provider options (the plugin's `apply` supplies env-var and constant defaults). */
+export interface PerplexitySearchProviderOptions {
+    /** Perplexity API key. Empty/absent makes the provider unavailable. */
+    apiKey: string;
+    /** Endpoint base; `/chat/completions` is appended. */
+    baseURL: string;
+    /** Search model name. */
+    model: string;
+    /** Upper bound on generated answer tokens (`max_tokens`). */
+    maxTokens: number;
+    /** Optional recency window sent as `search_recency_filter`; omitted = no filter. */
+    searchRecency?: PerplexityRecency;
+}
+/**
+ * Map one structured Perplexity search result to a normalized source.
+ *
+ * @param result - one entry of the response's `search_results[]`.
+ * @returns the normalized source; blank fields are omitted rather than set empty.
+ */
+export declare function mapPerplexityResult(result: PerplexitySearchResult): WebSearchSource;
+/**
+ * Map a Perplexity response envelope to a normalized search result. Prefers
+ * structured `search_results[]`; falls back to URL-only `citations[]` (those
+ * sources carry just a `url`) only when `search_results` is absent.
+ *
+ * @param response - the parsed chat-completions response body.
+ * @returns the normalized result; `content` is omitted when the answer is empty.
+ */
+export declare function mapPerplexityResponse(response: PerplexityResponse): WebSearchResult;
+/** The Perplexity-backed search provider; HTTP redirects fail as `WEB_PROVIDER_ERROR`. */
+export declare class PerplexitySearchProvider implements WebSearchProvider {
+    private readonly options;
+    readonly id = "perplexity";
+    constructor(options: PerplexitySearchProviderOptions);
+    available(): boolean;
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Wire types for the Perplexity search API (`POST https://api.perplexity.ai/chat/completions`,
+ * an OpenAI-compatible chat shape). Results prefer structured `search_results` and fall back to
+ * URL-only `citations`; the provider-private wire shape does not depend on `ctx.llm`.
+ * @module @deepseek-ai/dsh-web-search-perplexity/types
+ */
+/** Request body sent to Perplexity's chat-completions endpoint. */
+export interface PerplexityRequest {
+    model: string;
+    messages: {
+        role: 'user';
+        content: string;
+    }[];
+}
+/** One structured search result (the preferred citation surface). */
+export interface PerplexitySearchResult {
+    url: string;
+    title?: string | null;
+    snippet?: string | null;
+    date?: string | null;
+}
+/** Perplexity's response envelope. */
+export interface PerplexityResponse {
+    choices?: {
+        message?: {
+            content?: string | null;
+        };
+    }[];
+    /** Structured citation surface (preferred). */
+    search_results?: PerplexitySearchResult[];
+    /** URL-only citation fallback. */
+    citations?: string[];
+}
+/** Perplexity's error response envelope (best-effort; fields vary). */
+export interface PerplexityError {
+    error?: {
+        message?: string;
+    } | string;
+    message?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@deepseek-ai/dsh-web-search-perplexity",
+  "description": "Perplexity-backed search provider for the DeepSeek Harness web capability seam (ctx.web)",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/web/web-search-perplexity"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-environment": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-web": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-environment": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-web": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}