@x1a0f3n9/dsh-web-search-perplexity 0.1.5-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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: 1e0c98ed985a0d364ec44fbc939901f57d6657e0
+README.zh.md: 0947fb1939a9c6bba214ec995458a189b4100700

package/README.md

@@ -0,0 +1,166 @@
+---
+description: "The Perplexity-backed search provider for ctx.web: how deployments mount OpenAI-compatible Perplexity search with generated answers and citations."
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-web-search-perplexity
+
+English | [中文](README.zh.md)
+
+## Summary
+
+With `dsh-web-search-perplexity`, the harness searches the web through Perplexity and gets a model-generated answer plus citeable sources in one call. Choose it when a deployment has a Perplexity API key and wants a generated answer. Perplexity has no result-count control, so the returned sources are truncated to the requested bound after the fact. When Perplexity omits structured result metadata, sources fall back to URL-only citations. The model-facing `web_search` tool lives in `dsh-tool-web`.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount the provider in a composition that already loads the web service; it registers as the `perplexity` search provider, so `ctx.web.search()` resolves it automatically when it is the only usable search backend — or pin it with `searchProvider: perplexity`.
+
+### When to choose it
+
+Choose this backend when a deployment holds a Perplexity API key and wants a model-generated answer plus citeable sources in one search. The provider is unavailable — and every search call fails with a structured error — when the key is empty or the endpoint base does not parse.
+
+### Minimal configuration
+
+Load the web service and the provider; the API key falls back to `$PERPLEXITY_API_KEY` from the launch environment, and all other settings have safe defaults.
+
+```yaml
+- name: '@x1a0f3n9/dsh-web'
+- name: '@x1a0f3n9/dsh-web-search-perplexity'
+  config:
+    apiKey: !!js process.env.PERPLEXITY_API_KEY
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `apiKey` | `$PERPLEXITY_API_KEY` | Perplexity API key; empty or 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 |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-web-search-perplexity) is the exhaustive source for every accepted field and its JSDoc.
+
+### What a search returns
+
+`content` carries Perplexity's generated answer. `sources[]` prefers the structured `search_results[]` (`url`, `title`, `snippet`, `publishedAt` from `date`) and falls back to the URL-only `citations[]` array only when `search_results` is absent — which is why `title`/`snippet`/`publishedAt` are optional on the service. Perplexity exposes no result-count control, so the service enforces `maxResults` by truncating and flagging.
+
+### Failures and recovery
+
+Provider failures — HTTP errors, network failures, unparseable or wrong-shape bodies — 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`. Callers route on the code; the model-facing `web_search` tool surfaces failures to the model under its own error wrapper.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design decisions behind the provider; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design philosophy
+
+The provider is a thin adapter over Perplexity's chat-completions endpoint with two deliberate rules:
+
+- **The generated answer is trusted as `content`.** Unlike the other search backends, Perplexity returns a model-generated answer, and this provider passes it through as the normalized `content` field.
+- **Structured sources win; URL-only citations are the fallback.** `search_results[]` carries the portable fields; `citations[]` carries only URLs, and the service vocabulary makes those fields optional precisely for this case.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: config schema, environment fallback, provider registration |
+| [`src/provider.ts`](src/provider.ts) | The `PerplexitySearchProvider`: request dispatch, abort classification, answer and source mapping |
+| [`src/types.ts`](src/types.ts) | Perplexity wire types for the chat-completions response |
+| — | No runtime invariant companion is published; this package exposes no independent event sequence or mutable data relation beyond contracts enforced at its owning seam. |
+
+### Request and mapping flow
+
+`search()` posts the query with the model, token cap, and optional recency filter to `{baseURL}/chat/completions` with `redirect: 'error'`. The response's `content` becomes `content`; `search_results[]` becomes `sources[]` when present, otherwise each `citations[]` entry becomes a URL-only source; and the service applies the final `maxResults` bound on the way back. An abort — a `DOMException` named `AbortError` — becomes `WEB_ABORTED`; anything else becomes `WEB_PROVIDER_ERROR`.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the shared vocabulary to the service, the model-facing tools, and the design rationale.
+
+- [Web subsystem](../../../docs/subsystems/web.md) — the exhaustive search request/result vocabulary and error codes.
+- [Web package map](../README.md) — the seven-package family and each role.
+- [dsh-web](../web/README.md) — the web service this provider registers into.
+- [dsh-tool-web](../tool-web/README.md) — the model-facing `web_search` tool that renders this provider's sources.
+- [Generated configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-web-search-perplexity) — every accepted config field and its source declaration.
+- [Web capability seam decision](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) — why search and fetch share one provider-selection service.
+
+-----
+
+<a id="model-experience"></a>
+## 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`, 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
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the provider is a poor fit. They are current package constraints.
+
+- **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 service 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 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 (such as `dsh-timeout`'s `TimeoutReason`) surfaces as `WEB_PROVIDER_ERROR`.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+This Dev Note is working context for maintainers: open questions and undecided directions. It is explicitly non-authoritative — shipped behavior, limits, and rationale live in the sections above and the linked Agent Notes.
+
+#### Future: wider Perplexity control surface
+
+Perplexity's domain filters, `web_search_options` context size, and image support stay unexposed. Exposing them needs provider-neutral service fields first, so the family adds one coordinated control rather than a vendor-specific argument.
+
+</details>

package/README.zh.md

@@ -0,0 +1,166 @@
+---
+description: "ctx.web 的 Perplexity 搜索提供方：部署方如何挂载 OpenAI 兼容的 Perplexity 搜索，获得生成答案与引用。"
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-web-search-perplexity
+
+[English](README.md) | 中文
+
+## 概述
+
+有了 `dsh-web-search-perplexity`，harness 可以通过 Perplexity 搜索 web，一次调用同时获得模型生成的答案与可引用来源。当部署持有 Perplexity API 密钥、并希望获得生成答案时选择它。Perplexity 没有结果数量控制，因此返回的来源会在事后被截断到请求的上限。Perplexity 省略结构化结果元数据时，来源回退为只含 URL 的引用。面向模型的 `web_search` 工具位于 `dsh-tool-web`。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在已加载 web 服务的组合中挂载本提供方；它以 `perplexity` 搜索提供方身份注册，因此当它是唯一可用的搜索后端时，`ctx.web.search()` 会自动解析到它——也可以用 `searchProvider: perplexity` 固定。
+
+### 何时选择
+
+当部署持有 Perplexity API 密钥、并希望一次搜索同时获得模型生成的答案与可引用来源时选择此后端。密钥为空或端点基址无法解析时，提供方不可用——每次搜索调用都会以结构化错误失败。
+
+### 最小配置
+
+加载 web 服务与本提供方；API 密钥回退到启动环境中的 `$PERPLEXITY_API_KEY`，其余设置都有安全默认值。
+
+```yaml
+- name: '@x1a0f3n9/dsh-web'
+- name: '@x1a0f3n9/dsh-web-search-perplexity'
+  config:
+    apiKey: !!js process.env.PERPLEXITY_API_KEY
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `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`。未设置时不发送过滤条件 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-web-search-perplexity)是每个受支持字段及其 JSDoc 的穷尽式真源。
+
+### 搜索返回什么
+
+`content` 携带 Perplexity 的生成答案。`sources[]` 优先使用结构化 `search_results[]`（`url`、`title`、`snippet`、`publishedAt` 取自 `date`），仅当 `search_results` 缺失时才回退到只含 URL 的 `citations[]` 数组——这正是服务上 `title`／`snippet`／`publishedAt` 为可选字段的原因。Perplexity 不公开结果数量控制，因此服务通过截断并标记来强制执行 `maxResults`。
+
+### 失败与恢复
+
+提供方失败——HTTP 错误、网络失败、响应体无法解析或结构不符——以 `WebError` `WEB_PROVIDER_ERROR` 呈现；中止请求以 `WEB_ABORTED` 呈现。HTTP 重定向会在访问 `Location` 指向的目标之前被拒绝，并以 `WEB_PROVIDER_ERROR` 呈现。调用方根据错误码进行路由；面向模型的 `web_search` 工具会在自己的错误包装层内把失败呈现给模型。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释提供方背后的设计决策；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+该提供方是 Perplexity chat-completions 端点之上的薄适配器，遵循两条刻意的规则：
+
+- **生成答案直接用作 `content`。** 与其他搜索后端不同，Perplexity 返回模型生成的答案，本提供方将其作为规范化 `content` 字段透传。
+- **结构化来源优先；只含 URL 的引用是回退。** `search_results[]` 携带可移植字段；`citations[]` 只携带 URL，服务词汇把这些字段设为可选，正是为了这种情况。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：配置 schema、环境变量回退、提供方注册 |
+| [`src/provider.ts`](src/provider.ts) | `PerplexitySearchProvider`：请求分发、中止分类、答案与来源映射 |
+| [`src/types.ts`](src/types.ts) | chat-completions 响应的 Perplexity 协议类型 |
+| — | 不发布运行时不变量配套入口；除所属 seam 强制执行的约定外，本包不公开独立的事件序列或可变数据关系。 |
+
+### 请求与映射流程
+
+`search()` 以 `redirect: 'error'` 把查询连同模型、token 上限与可选新近程度过滤条件 POST 到 `{baseURL}/chat/completions`。响应的 `content` 变为 `content`；存在 `search_results[]` 时它变为 `sources[]`，否则每个 `citations[]` 条目变为只含 URL 的来源；服务在返回路径上应用最终的 `maxResults` 上限。中止——名为 `AbortError` 的 `DOMException`——变为 `WEB_ABORTED`；其余情况变为 `WEB_PROVIDER_ERROR`。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从共享词汇逐步进入服务、面向模型的工具与设计依据。
+
+- [web 子系统](../../../docs/subsystems/web.zh.md)——穷尽式的搜索请求／结果词汇与错误码。
+- [web 包映射](../README.zh.md)——七包家族与各角色。
+- [dsh-web](../web/README.zh.md)——本提供方注册进入的 web 服务。
+- [dsh-tool-web](../tool-web/README.zh.md)——渲染本提供方来源的面向模型 `web_search` 工具。
+- [生成配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-web-search-perplexity)——每个受支持配置字段及其源声明。
+- [web 能力 seam 决策](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md)——搜索与抓取为何共用一项提供方选择服务。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 辅助 Perplexity 请求
+
+#### 模型看到的内容
+
+独立的 Perplexity 模型通过 chat-completions 端点将 `<query>` 原样作为唯一用户消息接收。该请求不属于会话模型上下文。
+
+#### Token 影响
+
+每次搜索都会产生独立的提供方 token；`maxTokens` 限制生成答案。
+
+#### KV Cache 影响
+
+与会话请求缓存相互独立。同一模型路由下的相同查询可能复用提供方缓存；查询或路由改变会建立不同前缀。
+
+### 间接的会话工具结果
+
+#### 模型看到的内容
+
+通过 `dsh-tool-web`，会话模型会看到生成答案及结构化结果元数据，或只含 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 条目失效。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明提供方在哪些情况下不合适。它们是当前包约束。
+
+- **引用回退来源只含 URL**——Perplexity 省略结构化 `search_results[]` 时，来源不含 `title`／`snippet`／`publishedAt`，因此工具只渲染纯主机名标签。
+- **超量返回的来源仍会增加 token 消耗与延迟**——协议没有结果数量控制，`maxResults` 只能由服务在事后截断。
+- **只公开 `model`／`maxTokens`／`searchRecency`**——Perplexity 的其他搜索控制项（域名过滤条件、`web_search_options` 上下文大小、图片）等待提供方无关的服务字段（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md)）。
+- **按错误形状分类中止**——只有名为 `AbortError` 的 `DOMException` 才映射为 `WEB_ABORTED`；携带自定义原因的中止（例如 `dsh-timeout` 的 `TimeoutReason`）呈现为 `WEB_PROVIDER_ERROR`。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+本开发备注是维护者的工作上下文：开放问题与尚未决定的探索方向。它明确不具权威性——已交付的行为、限制与既定理由以上文和相关 Agent Note 为准。
+
+#### 未来：更宽的 Perplexity 控制面
+
+Perplexity 的域名过滤条件、`web_search_options` 上下文大小与图片支持仍未公开。公开它们需要先有提供方无关的服务字段，让家族以一个协调一致的控制项、而非厂商专有参数的方式新增。
+
+</details>

package/lib/index.js

@@ -0,0 +1,152 @@
+import { launchEnvironmentOf } from "@x1a0f3n9/dsh-launch-environment";
+import z from "@deepseek-ai/schemastery";
+import { WebError } from "@x1a0f3n9/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 @x1a0f3n9/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
+/**
+* Perplexity-backed `WebSearchProvider` plugin. It contributes to the
+* `ctx.web` registry without owning the service.
+*
+* @module @x1a0f3n9/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 ?? launchEnvironmentOf(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/types/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Perplexity-backed `WebSearchProvider` plugin. It contributes to the
+ * `ctx.web` registry without owning the service.
+ *
+ * @module @x1a0f3n9/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/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 @x1a0f3n9/dsh-web-search-perplexity/provider
+ */
+import type { WebSearchProvider, WebSearchRequest, WebSearchResult, WebSearchSource } from '@x1a0f3n9/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 @x1a0f3n9/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 shape). */
+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 data (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,43 @@
+{
+  "name": "@x1a0f3n9/dsh-web-search-perplexity",
+  "description": "Perplexity-backed search provider for the DeepSeek Harness web capability seam (ctx.web)",
+  "version": "0.1.5-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@x1a0f3n9/dsh-launch-environment": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-web": "^0.1.5-rc.2",
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@x1a0f3n9/dsh-web": "^0.1.5-rc.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@x1a0f3n9/dsh-http-proxy": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-launch-environment": "^0.1.5-rc.2"
+  }
+}