@keenable/dsh-keenable 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keenable
+
+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.md

@@ -0,0 +1,92 @@
+# Keenable for DeepSeek Harness
+
+Web search and page reading for DeepSeek Harness through [Keenable](https://keenable.ai), with **no API key and no account**. It works with whatever model you run in Harness, local models included.
+
+The plugin points Harness's built-in `web_search` and `web_fetch` tools at Keenable. It adds no new tools: the model asks for a query or a URL exactly as before, and Keenable answers.
+
+## Why
+
+The search provider Harness ships with needs a DeepSeek account or a DeepSeek API key. With a local or third-party model and neither of those, `web_search` fails. Keenable's public endpoints need no key, so search works on a fresh install:
+
+- `web_search` returns ranked web results with an excerpt of each page and its publication date, when known.
+- `web_fetch` returns a page as markdown. The page is retrieved on Keenable's servers, so a URL the model chose is never requested from the machine running Harness, and private or internal hosts are refused.
+
+An API key is optional. It only lifts the rate limit described [below](#limits-and-the-optional-api-key).
+
+## Install
+
+Requires DeepSeek Harness 0.1.7-rc.2 or later and Node.js 22.12 or later.
+
+**From Harness:** open **Plugins → Add plugin**, enter `@keenable/dsh-keenable`, then **Install → Enable now**.
+
+**From the terminal:** install into the profile you use, then restart Harness:
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add @keenable/dsh-keenable
+npx @deepseek-ai/dsh web
+```
+
+Profiles are separate: `web`, `tui` and `headless` each need their own install. Replace `web` with the profile you run.
+
+Then ask your model to search the web. No further setup is needed.
+
+## Limits and the optional API key
+
+Without a key, requests go to Keenable's public endpoints, limited to 10 requests per second and 1,000 per hour per IP address. Search and fetch are counted separately. Everyone behind the same network address shares the limit, so a busy office or CI runner can reach it; the tool error then says so.
+
+A key lifts the limit. Create one in the [Keenable console](https://app.keenable.ai/console), then either:
+
+- set `KEENABLE_API_KEY` in the environment Harness starts in, or
+- enter it as **apiKey** in this plugin's settings on the **Plugins** page.
+
+A key in the settings wins over the environment variable.
+
+## Settings
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `apiKey` | `$KEENABLE_API_KEY` | Optional. Switches both tools to the authenticated endpoints. |
+| `maxSnippetChars` | `500` | Excerpt length per search result, 180 to 10,000 characters. |
+| `fetchLive` | `true` | Fetch pages live from the source. When off, `web_fetch` returns Keenable's indexed copy and fails for pages it has not indexed. |
+| `maxBodyChars` | `100000` | Maximum characters of page text `web_fetch` returns. Longer pages are cut and marked as truncated. |
+| `baseURL` | `https://api.keenable.ai` | API origin. HTTPS only. |
+
+## Keeping the local fetch provider
+
+The plugin pins both capabilities to Keenable. To keep Harness's local HTTP fetch provider and use Keenable for search only, override the web row in your profile's `cordis.patch.yml`:
+
+```yaml
+- id: web
+  config:
+    searchProvider: keenable
+    fetchProvider: http
+```
+
+Both fields are needed: a config patch replaces the row's whole config object.
+
+## Privacy
+
+Search queries and fetched URLs are sent to Keenable, even when your model runs locally. Requests identify the plugin with an `X-Keenable-Title: dsh-keenable` header, which the public endpoints require. Results are external content, and Harness marks them as untrusted data for the model.
+
+## Troubleshooting
+
+| Symptom | What to check |
+| --- | --- |
+| `WEB_PROVIDER_CONFIGURED_MISSING` | The plugin is not loaded in this profile. Install it into the profile you run, and restart Harness. |
+| "requests share a per-IP limit" | The keyless limit was reached. Wait, or set an API key. |
+| "Fetching from private/internal hosts is not allowed" | Keenable does not fetch `localhost` or private addresses. Use the local HTTP fetch provider for those (see above). |
+| Search still asks for DeepSeek credentials | Another patch layer pins `searchProvider` back. Check the composed profile with `npx @deepseek-ai/dsh --profile web --dump-config`. |
+
+## Development
+
+```sh
+npm ci
+npm test            # offline: providers, plugin registration, model-facing tools, manifest
+npm run test:live   # real Keenable API, no key
+```
+
+The tests load the plugin into a real Cordis context with Harness's own `dsh-web` seam and `web_search`/`web_fetch` tools. The code is plain JavaScript and needs no build step.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,18 @@
+# The layer this bundle contributes when a profile lists it.
+#
+# Both providers register under the id `keenable`, one per capability registry.
+# The built-in DeepSeek search provider and the local HTTP fetch provider stay
+# mounted, so both ids are pinned: with two usable providers and no pin, the
+# seam fails with WEB_PROVIDER_AMBIGUOUS instead of picking one. A config patch
+# replaces the row's config object, so both fields are stated.
+#
+# To keep the local HTTP fetch provider, set fetchProvider back to `http`.
+- id: web
+  name: '@deepseek-ai/dsh-web'
+  config:
+    searchProvider: keenable
+    fetchProvider: keenable
+
+- insert:
+    - id: keenable
+      name: '@keenable/dsh-keenable'

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@keenable/dsh-keenable",
+  "version": "0.1.0",
+  "description": "Keenable web search and page fetch for DeepSeek Harness: the built-in web_search and web_fetch tools, with no API key needed",
+  "license": "MIT",
+  "author": "Keenable (https://keenable.ai)",
+  "homepage": "https://github.com/keenableai/dsh-keenable#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keenableai/dsh-keenable.git"
+  },
+  "bugs": {
+    "url": "https://github.com/keenableai/dsh-keenable/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh-plugin",
+    "keenable",
+    "web-search",
+    "web-fetch",
+    "no-api-key"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "test:live": "KEENABLE_LIVE=1 node --test test/live.test.js"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-launch-environment": ">=0.1.7-rc.2",
+    "@deepseek-ai/dsh-web": ">=0.1.7-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.4"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/dsh-launch-environment": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tool-web": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-web": "0.2.0-rc.2",
+    "@deepseek-ai/schemastery": "3.18.4",
+    "js-yaml": "4.1.0"
+  }
+}

package/src/fetch.js

@@ -0,0 +1,120 @@
+/**
+ * `KeenableFetchProvider`: a `WebFetchProvider` for the DeepSeek Harness web
+ * seam (`ctx.web`), backed by `GET /v1/fetch`. The page is retrieved on
+ * Keenable's servers and returned as markdown, so the model-chosen URL is never
+ * requested from the machine running Harness. Keyless by default.
+ * @module @keenable/dsh-keenable/fetch
+ */
+
+import { WebError } from '@deepseek-ai/dsh-web'
+import {
+  PROVIDER_ID,
+  callKeenable,
+  endpoint,
+  isPositiveInteger,
+  isValidBaseUrl,
+  nonblank,
+  providerError,
+} from './http.js'
+
+const LABEL = 'Keenable fetch'
+
+/** Largest `max_chars` the API accepts, and so the largest body this provider asks for. */
+export const MAX_BODY_CHARS_LIMIT = 200_000
+
+export class KeenableFetchProvider {
+  /**
+   * @param {object} options
+   * @param {string} options.apiKey - API key, or `''` for the keyless endpoint.
+   * @param {string} options.baseURL - API origin.
+   * @param {boolean} options.live - fetch from the source instead of the index.
+   * @param {number} options.maxBodyChars - cap on returned characters.
+   * @param {number} options.maxUrlLength - longest accepted request URL.
+   */
+  constructor(options) {
+    this.id = PROVIDER_ID
+    this.options = options
+  }
+
+  /** A local check only: the seam forbids network calls here. No key is needed. */
+  available() {
+    const { baseURL, maxBodyChars, maxUrlLength } = this.options
+    return isValidBaseUrl(baseURL)
+      && isPositiveInteger(maxBodyChars) && maxBodyChars < MAX_BODY_CHARS_LIMIT
+      && isPositiveInteger(maxUrlLength)
+  }
+
+  /**
+   * @param {{ url: string }} request
+   * @param {AbortSignal} [signal]
+   */
+  async fetch(request, signal) {
+    // Reject locally, before anything is sent: a file:// or credential-carrying
+    // URL must never reach the API.
+    assertFetchableUrl(request.url, this.options.maxUrlLength)
+    const payload = await callKeenable({
+      url: `${endpoint(this.options.baseURL, '/v1/fetch', this.options.apiKey)}?${buildFetchQuery(request, this.options)}`,
+      method: 'GET',
+      apiKey: this.options.apiKey,
+      label: LABEL,
+      signal,
+    })
+    try {
+      return mapFetchResponse(payload, request.url, this.options)
+    } catch (error) {
+      throw providerError(`${LABEL} returned an unprocessable response body: ${error.message}`, error)
+    }
+  }
+}
+
+/**
+ * Validate a fetch target, throwing `WEB_INVALID_URL` (the local HTTP
+ * provider's code) when it must not be requested.
+ */
+export function assertFetchableUrl(url, maxUrlLength) {
+  if (typeof url !== 'string' || url.length > maxUrlLength) {
+    throw new WebError(`URL exceeds the ${maxUrlLength}-character limit`, 'WEB_INVALID_URL')
+  }
+  if (!URL.canParse(url)) throw new WebError(`invalid URL: ${url}`, 'WEB_INVALID_URL')
+  const parsed = new URL(url)
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new WebError(`unsupported URL scheme "${parsed.protocol}"; only http and https are fetchable`, 'WEB_INVALID_URL')
+  }
+  if (parsed.username || parsed.password) {
+    throw new WebError('URL must not carry embedded credentials', 'WEB_INVALID_URL')
+  }
+}
+
+/**
+ * The `GET /v1/fetch` query. One character more than the budget is requested,
+ * so a page longer than the budget is detected and flagged as truncated.
+ */
+export function buildFetchQuery(request, { live, maxBodyChars }) {
+  const query = new URLSearchParams({ url: request.url, max_chars: String(maxBodyChars + 1) })
+  if (live) query.set('live', 'true')
+  return query.toString()
+}
+
+/**
+ * Map a fetch response to the seam's result. The body is markdown, the seam's
+ * `text` kind. Keenable returns the page title as a separate field, often
+ * absent from `content`, so it is prepended as a heading when the text does
+ * not already open with it. Keenable reports failures as HTTP errors and
+ * returns no status code of the page on success, so success is reported as 200.
+ */
+export function mapFetchResponse(payload, requestedUrl, { maxBodyChars }) {
+  if (typeof payload !== 'object' || payload === null || typeof payload.content !== 'string') {
+    throw new TypeError('response.content is not a string')
+  }
+  const title = nonblank(payload.title)
+  const content = title !== undefined && !payload.content.slice(0, 300).includes(title)
+    ? `# ${title}\n\n${payload.content}`
+    : payload.content
+  const truncated = content.length > maxBodyChars
+  return {
+    url: nonblank(payload.url) ?? requestedUrl,
+    statusCode: 200,
+    body: { kind: 'text', content: truncated ? content.slice(0, maxBodyChars) : content },
+    truncated,
+  }
+}

package/src/http.js

@@ -0,0 +1,148 @@
+/**
+ * Shared transport for the Keenable search and fetch providers: one request
+ * helper and one error vocabulary, so the redirect policy, the attribution
+ * headers and the abort/error classification cannot drift between the two.
+ * @module @keenable/dsh-keenable/http
+ */
+
+import { WebError } from '@deepseek-ai/dsh-web'
+
+/** The id both providers register under, one per capability registry. */
+export const PROVIDER_ID = 'keenable'
+
+/** Default API origin; the versioned path is appended per operation. */
+export const DEFAULT_BASE_URL = 'https://api.keenable.ai'
+
+/** Package version, sent in the user agent. Bump with package.json. */
+export const VERSION = '0.1.0'
+
+/**
+ * Application name sent as `X-Keenable-Title`. The keyless endpoints reject a
+ * request without it (400 "Missing app identifier"), and it attributes traffic.
+ */
+export const APP_TITLE = 'dsh-keenable'
+
+const USER_AGENT = `@keenable/dsh-keenable/${VERSION} (+https://github.com/keenableai/dsh-keenable)`
+
+/**
+ * The endpoint for one operation. Without a key the request goes to the
+ * keyless `/public` variant, which takes the same parameters and returns the
+ * same shape but is rate limited per IP.
+ *
+ * @param {string} baseURL - the configured API origin.
+ * @param {string} path - the operation path, such as `/v1/search`.
+ * @param {string} apiKey - the API key, or `''` for keyless.
+ * @returns {string} the absolute endpoint URL.
+ */
+export function endpoint(baseURL, path, apiKey) {
+  const base = baseURL.endsWith('/') ? baseURL.slice(0, -1) : baseURL
+  return `${base}${path}${apiKey ? '' : '/public'}`
+}
+
+/**
+ * Send one request to the Keenable API and return the parsed JSON body.
+ *
+ * Redirects fail before the `Location` target is contacted, because the
+ * request may carry the API key. Every non-2xx response is a provider error;
+ * its message keeps Keenable's own explanation (for example "Fetching from
+ * private/internal hosts is not allowed") and, for a keyless rate limit, says
+ * how to lift it.
+ *
+ * @param {object} request
+ * @param {string} request.url - the absolute endpoint URL, with any query.
+ * @param {'GET' | 'POST'} request.method - the HTTP method.
+ * @param {unknown} [request.body] - JSON body for a POST.
+ * @param {string} request.apiKey - the API key, or `''` for keyless.
+ * @param {string} request.label - operation name used in messages ("Keenable search").
+ * @param {AbortSignal} [request.signal] - cancellation signal.
+ * @returns {Promise<any>} the parsed response body.
+ */
+export async function callKeenable({ url, method, body, apiKey, label, signal }) {
+  const headers = {
+    'accept': 'application/json',
+    'user-agent': USER_AGENT,
+    'x-keenable-title': APP_TITLE,
+  }
+  if (body !== undefined) headers['content-type'] = 'application/json'
+  if (apiKey) headers['x-api-key'] = apiKey
+
+  let response
+  try {
+    response = await fetch(url, {
+      method,
+      redirect: 'error',
+      headers,
+      ...body === undefined ? {} : { body: JSON.stringify(body) },
+      ...signal === undefined ? {} : { signal },
+    })
+  } catch (error) {
+    if (signal?.aborted || isAbortError(error)) throw aborted(label, error)
+    throw providerError(`${label} request failed: ${describe(error)}`, error)
+  }
+
+  let payload
+  try {
+    payload = await response.json()
+  } catch (error) {
+    if (signal?.aborted || isAbortError(error)) throw aborted(label, error)
+    // Gateway errors often carry no JSON; the status is the real signal then.
+    if (!response.ok) throw providerError(`${label} failed (HTTP ${response.status})`, error)
+    throw providerError(`${label} returned an unprocessable response body: ${describe(error)}`, error)
+  }
+
+  if (!response.ok) throw providerError(failureMessage(label, response.status, payload, apiKey))
+  return payload
+}
+
+/**
+ * Build the message for a Keenable-reported failure from its `error` and
+ * `message` fields.
+ */
+function failureMessage(label, status, payload, apiKey) {
+  const parts = []
+  for (const field of ['error', 'message']) {
+    const value = typeof payload?.[field] === 'string' ? payload[field].trim() : ''
+    if (value && !parts.includes(value)) parts.push(value)
+  }
+  let message = `${label} failed (HTTP ${status})${parts.length ? `: ${parts.join(': ')}` : ''}`
+  if (status === 429 && !apiKey) {
+    message += ' Without an API key, requests share a per-IP limit; set the plugin\'s apiKey or KEENABLE_API_KEY to lift it.'
+  }
+  return message
+}
+
+function describe(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/** True for a `fetch`/`AbortSignal` abort, which is cancellation, not failure. */
+export function isAbortError(error) {
+  return typeof error === 'object' && error !== null && error.name === 'AbortError'
+}
+
+/** `WEB_ABORTED`: cancellation is not a provider error. */
+export function aborted(label, cause) {
+  return new WebError(`${label} aborted`, 'WEB_ABORTED', cause === undefined ? {} : { cause })
+}
+
+/** `WEB_PROVIDER_ERROR`: the seam's catch-all for a provider's own failure. */
+export function providerError(message, cause) {
+  return new WebError(message, 'WEB_PROVIDER_ERROR', cause === undefined ? {} : { cause })
+}
+
+/** True when `baseURL` is an HTTPS URL with no credentials, query or fragment. */
+export function isValidBaseUrl(baseURL) {
+  if (typeof baseURL !== 'string' || !URL.canParse(baseURL)) return false
+  const url = new URL(baseURL)
+  return url.protocol === 'https:' && !url.username && !url.password && !url.search && !url.hash
+}
+
+/** True for a positive integer. */
+export function isPositiveInteger(value) {
+  return Number.isInteger(value) && value > 0
+}
+
+/** The trimmed string when it is non-blank, else `undefined`. */
+export function nonblank(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}

package/src/index.js

@@ -0,0 +1,61 @@
+/**
+ * `@keenable/dsh-keenable`: registers Keenable search and fetch providers with
+ * the DeepSeek Harness web seam (`ctx.web`), so the built-in `web_search` and
+ * `web_fetch` tools answer through Keenable. Both work without an API key; a
+ * key only lifts the per-IP rate limit of the keyless endpoints.
+ *
+ * A function plugin, not a service: it registers into the registries that
+ * `@deepseek-ai/dsh-web` owns. The bundle patch pins both provider ids.
+ * @module @keenable/dsh-keenable
+ */
+
+import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment'
+import z from '@deepseek-ai/schemastery'
+import { DEFAULT_BASE_URL, nonblank } from './http.js'
+import { KeenableFetchProvider } from './fetch.js'
+import { KeenableSearchProvider, SNIPPET_CHARS_MAX, SNIPPET_CHARS_MIN } from './search.js'
+
+export { APP_TITLE, DEFAULT_BASE_URL, PROVIDER_ID, VERSION } from './http.js'
+export { KeenableSearchProvider, buildSearchBody, mapSearchResponse } from './search.js'
+export { KeenableFetchProvider, assertFetchableUrl, buildFetchQuery, mapFetchResponse } from './fetch.js'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'keenable'
+
+/** The web seam both providers register into. */
+export const inject = ['web']
+
+/** Same cap as the local HTTP fetch provider, below the tool's own output cap. */
+export const DEFAULT_MAX_BODY_CHARS = 100_000
+
+export const Config = z.object({
+  apiKey: z.string().role('secret')
+    .description('Optional Keenable API key. Without one, search and fetch use the keyless endpoints, limited to 10 requests per second and 1,000 per hour per IP address. Falls back to $KEENABLE_API_KEY.'),
+  baseURL: z.string().default(DEFAULT_BASE_URL)
+    .description('Keenable API origin. HTTPS only.'),
+  maxSnippetChars: z.number().step(1).min(SNIPPET_CHARS_MIN).max(SNIPPET_CHARS_MAX).default(500)
+    .description('Excerpt length per search result, in characters.'),
+  fetchLive: z.boolean().default(true)
+    .description('Fetch pages live from the source. When off, web_fetch returns Keenable\'s indexed copy and fails for pages it has not indexed.'),
+  maxBodyChars: z.number().step(1).min(1).max(DEFAULT_MAX_BODY_CHARS * 2 - 1).default(DEFAULT_MAX_BODY_CHARS)
+    .description('Maximum characters of page text web_fetch returns.'),
+})
+
+/** Register both providers. Cordis disposes the registrations with the plugin. */
+export function apply(ctx, config) {
+  const apiKey = nonblank(config.apiKey)
+    ?? nonblank(launchEnvironmentOf(ctx).get('KEENABLE_API_KEY')?.value)
+    ?? ''
+  ctx.web.registerSearchProvider(new KeenableSearchProvider({
+    apiKey,
+    baseURL: config.baseURL,
+    maxSnippetChars: config.maxSnippetChars,
+  }))
+  ctx.web.registerFetchProvider(new KeenableFetchProvider({
+    apiKey,
+    baseURL: config.baseURL,
+    live: config.fetchLive,
+    maxBodyChars: config.maxBodyChars,
+    maxUrlLength: 2048,
+  }))
+}

package/src/search.js

@@ -0,0 +1,119 @@
+/**
+ * `KeenableSearchProvider`: a `WebSearchProvider` for the DeepSeek Harness web
+ * seam (`ctx.web`), backed by `POST /v1/search`. Keyless by default.
+ * @module @keenable/dsh-keenable/search
+ */
+
+import {
+  PROVIDER_ID,
+  callKeenable,
+  endpoint,
+  isPositiveInteger,
+  isValidBaseUrl,
+  nonblank,
+  providerError,
+} from './http.js'
+
+const LABEL = 'Keenable search'
+
+/** The API's own bounds for `max_results` and `snippet_max_length`. */
+export const MAX_RESULTS_LIMIT = 50
+export const SNIPPET_CHARS_MIN = 180
+export const SNIPPET_CHARS_MAX = 10_000
+
+export class KeenableSearchProvider {
+  /**
+   * @param {object} options
+   * @param {string} options.apiKey - API key, or `''` for the keyless endpoint.
+   * @param {string} options.baseURL - API origin.
+   * @param {number} options.maxSnippetChars - excerpt budget per result.
+   */
+  constructor(options) {
+    this.id = PROVIDER_ID
+    this.options = options
+  }
+
+  /** A local check only: the seam forbids network calls here. No key is needed. */
+  available() {
+    const { baseURL, maxSnippetChars } = this.options
+    return isValidBaseUrl(baseURL)
+      && Number.isInteger(maxSnippetChars)
+      && maxSnippetChars >= SNIPPET_CHARS_MIN && maxSnippetChars <= SNIPPET_CHARS_MAX
+  }
+
+  /**
+   * @param {{ query: string, maxResults?: number }} request
+   * @param {AbortSignal} [signal]
+   */
+  async search(request, signal) {
+    const payload = await callKeenable({
+      url: endpoint(this.options.baseURL, '/v1/search', this.options.apiKey),
+      method: 'POST',
+      body: buildSearchBody(request, this.options),
+      apiKey: this.options.apiKey,
+      label: LABEL,
+      signal,
+    })
+    try {
+      return mapSearchResponse(payload, this.options)
+    } catch (error) {
+      throw providerError(`${LABEL} returned an unprocessable response body: ${error.message}`, error)
+    }
+  }
+}
+
+/**
+ * The `POST /v1/search` body. `maxResults` is sent as a cost and latency
+ * optimization; the seam enforces the final bound regardless.
+ */
+export function buildSearchBody(request, { maxSnippetChars }) {
+  const body = { query: request.query, snippet_max_length: maxSnippetChars }
+  if (isPositiveInteger(request.maxResults)) body.max_results = Math.min(request.maxResults, MAX_RESULTS_LIMIT)
+  return body
+}
+
+/**
+ * Map a search response to the seam's result. Keenable puts the page text in
+ * `snippet`, with line breaks, and usually sends `description` empty, so the
+ * excerpt reads `snippet` first and collapses whitespace to one line.
+ * `snippet_max_length` is a hint the API may exceed slightly, so the budget is
+ * enforced here as well.
+ */
+export function mapSearchResponse(payload, { maxSnippetChars }) {
+  if (typeof payload !== 'object' || payload === null || !Array.isArray(payload.results)) {
+    throw new TypeError('response.results is not an array')
+  }
+  const seen = new Set()
+  const sources = []
+  for (const item of payload.results) {
+    if (typeof item !== 'object' || item === null) continue
+    const url = webUrl(item.url)
+    if (url === undefined || seen.has(url)) continue
+    seen.add(url)
+    const title = nonblank(item.title)
+    const snippet = excerpt(item, maxSnippetChars)
+    const publishedAt = nonblank(item.published_at)
+    sources.push({
+      url,
+      ...title === undefined ? {} : { title },
+      ...snippet === undefined ? {} : { snippet },
+      ...publishedAt === undefined ? {} : { publishedAt },
+    })
+  }
+  return { sources, truncated: false }
+}
+
+function excerpt(item, maxChars) {
+  const text = [item.snippet, item.description].map(nonblank).find(value => value !== undefined)
+  if (text === undefined) return undefined
+  const line = text.replace(/\s+/gu, ' ')
+  return line.length > maxChars ? `${line.slice(0, maxChars - 1).trimEnd()}…` : line
+}
+
+/** An http(s) URL without embedded credentials, or `undefined`. */
+function webUrl(value) {
+  if (typeof value !== 'string' || !URL.canParse(value)) return undefined
+  const url = new URL(value)
+  if ((url.protocol !== 'https:' && url.protocol !== 'http:') || url.username || url.password) return undefined
+  return url.href
+}