@auggieteo/dsh-synthetic-web-search 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,143 @@
+# @auggieteo/dsh-synthetic-web-search
+
+A [Synthetic Search](https://dev.synthetic.new/docs/synthetic/search)-backed `WebSearchProvider` and Settings card for the DeepSeek Harness `ctx.web` capability seam.
+
+This is a **host-plane** plugin: it registers the `synthetic` provider into the Harness-owned `web` service. It does not provide `ctx.web` or a model-facing tool. Use it with the existing `@deepseek-ai/dsh-tool-web` row.
+
+## Requirements
+
+- DeepSeek Harness with the `web` profile.
+- Node.js 22.12 or newer.
+- A [Synthetic API key](https://dev.synthetic.new/docs/synthetic/search).
+
+## Install
+
+Install the package as a dependency of the profile that hosts `web` (normally `web`). Choose one route.
+
+### npm registry
+
+```bash
+dsh plugin --profile web add @auggieteo/dsh-synthetic-web-search
+```
+
+### Public Git URL
+
+After the public repository exists, install directly from Git:
+
+```bash
+dsh plugin --profile web add git+https://github.com/auggie246/dsh-synthetic-web-search.git
+```
+
+#### pnpm `prepare` allowlist for Git installs
+
+A Git install builds this package from source with its `prepare` script. DSH forwards the install to pnpm, and pnpm may block that script. If it does, the command prints the package/build key that pnpm requires. Copy that **exact printed key** into `$DSH_HOME/profiles/web/pnpm-workspace.yaml`, for example:
+
+```yaml
+allowBuilds:
+  # Replace this with the exact key pnpm printed for this install.
+  <exact-key-printed-by-pnpm>: true
+```
+
+Then rerun the same `dsh plugin --profile web add git+https://…` command. Do not guess or substitute a package name: pnpm requires the exact key it printed.
+
+### Activate the provider
+
+Add this top-level `insert` block to `$DSH_HOME/profiles/web/cordis.patch.yml` (create the file with this YAML array if it does not exist):
+
+```yaml
+- insert:
+    - id: web-search-synthetic
+      name: '@auggieteo/dsh-synthetic-web-search'
+      config:
+        # Settings stores the key using this DSH credential reference.
+        apiKeyEnv: SYNTHETIC_API_KEY
+        # Optional; defaults to https://api.synthetic.new.
+        # baseURL: https://api.synthetic.new
+```
+
+The row belongs in the **web host profile**, not an agent preset: `ctx.web` is process-wide and each provider must register once. The same example is in [`examples/synthetic.cordis.yml`](examples/synthetic.cordis.yml).
+
+Restart the DSH web profile after changing its composition. Do not start a separate Vite server; it does not update an existing DSH GUI.
+
+## Configure credentials and provider selection
+
+Open **Settings → Plugins → Plugin configuration → Synthetic web search**, enter the API key, and select **Save**. DSH stores it in its credentials domain and does not return it to the browser after saving.
+
+For headless use, the plugin also reads the launch environment reference (by default `SYNTHETIC_API_KEY`):
+
+```bash
+export SYNTHETIC_API_KEY='…'
+```
+
+When another usable search provider is installed, explicitly select Synthetic before launching DSH:
+
+```bash
+export DSH_WEB_SEARCH_PROVIDER=synthetic
+dsh web
+```
+
+Provider selection is intentionally unambiguous. The existing `@deepseek-ai/dsh-tool-web` agent-preset row exposes `web_search` to the model.
+
+### Configuration
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `apiKey` | (unset) | Literal API key for non-interactive composition. Prefer the Settings card or environment reference; this secret is redacted from Settings responses. |
+| `apiKeyEnv` | `SYNTHETIC_API_KEY` | Credential reference used by the Settings card and launch environment. |
+| `baseURL` | `https://api.synthetic.new` | Synthetic API origin; the provider appends `/v2/search`. |
+
+## Uninstall
+
+1. Remove the `web-search-synthetic` row from `$DSH_HOME/profiles/web/cordis.patch.yml`.
+2. Remove the dependency:
+
+   ```bash
+   dsh plugin --profile web remove @auggieteo/dsh-synthetic-web-search
+   ```
+
+3. Restart the DSH web profile.
+4. If no other configuration uses it, remove `SYNTHETIC_API_KEY` from the process environment and remove the stored credential through your normal DSH credentials management.
+
+## Compatibility
+
+The public package name is `@auggieteo/dsh-synthetic-web-search`, replacing the former local `@deepseek-ai/dsh-web-search-synthetic` reference. Only the package reference changes. The Cordis row id (`web-search-synthetic`), Settings namespace (`web-search-synthetic`), and default credential reference (`SYNTHETIC_API_KEY`) remain unchanged, so existing persisted plugin settings and credentials continue to apply after the row is updated.
+
+## Development and verification
+
+```bash
+npm ci
+npm run verify
+```
+
+`npm run verify` cleans generated output, type-checks, runs mocked provider tests, builds `lib/` from source (including the browser client bundle), and checks the npm package contents with `npm pack --dry-run`.
+
+To test a local checkout without touching another profile, point a throwaway profile at its absolute path:
+
+```bash
+dsh plugin --profile synthetic-smoke add /absolute/path/to/dsh-synthetic-web-search
+```
+
+## Behavior
+
+The provider sends the documented request:
+
+```http
+POST https://api.synthetic.new/v2/search
+Authorization: Bearer $SYNTHETIC_API_KEY
+Content-Type: application/json
+
+{ "query": "…" }
+```
+
+It maps valid results into the Harness source vocabulary:
+
+| Synthetic field | Harness field |
+| --- | --- |
+| `url` | `url` |
+| `title` | `title` |
+| `text` | `snippet` |
+| `published` | `publishedAt` |
+
+Malformed or non-URL entries are ignored. The provider does not create a generated answer (`content`) and returns `truncated: false`; the `ctx.web` seam applies the caller's `maxResults` cap. Network, redirect, HTTP, and response-shape failures surface as `WEB_PROVIDER_ERROR`; aborted requests surface as `WEB_ABORTED`.
+
+Synthetic's documented API currently exposes only `query`, so `maxResults` is intentionally not sent upstream.

package/examples/synthetic.cordis.yml

@@ -0,0 +1,8 @@
+# Host-plane row: it registers a provider into the process-wide `web` service.
+# Install the package into the target profile before adding this row.
+- id: web-search-synthetic
+  name: '@auggieteo/dsh-synthetic-web-search'
+  config:
+    # The Settings card stores its key under this DSH credential reference.
+    # apiKeyEnv: SYNTHETIC_API_KEY
+    # baseURL: https://api.synthetic.new

package/lib/client.d.ts

@@ -0,0 +1,7 @@
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+
+/** Required client services for the Synthetic Settings card. */
+export declare const inject: string[]
+
+/** Register the Synthetic card in Settings > Plugins > Plugin configuration. */
+export declare function apply(ctx: ClientContext): void

package/lib/client.js

@@ -0,0 +1,159 @@
+window.__ModuleLoader__.load({
+  id: '@auggieteo/dsh-synthetic-web-search',
+  factory: (require) => {
+    const module = { exports: {} }
+    const exports = module.exports
+    const React = require('react')
+
+    const SETTINGS_NAMESPACE = 'web-search-synthetic'
+    const DEFAULT_API_KEY_ENV = 'SYNTHETIC_API_KEY'
+    const DEFAULT_BASE_URL = 'https://api.synthetic.new'
+    const inject = ['slots', 'settingsScope', 'connection']
+
+    function useScope(scope) {
+      const [snapshot, setSnapshot] = React.useState(() => scope.getSnapshot())
+      React.useEffect(() => scope.subscribe(() => setSnapshot(scope.getSnapshot())), [scope])
+      return snapshot
+    }
+
+    function createCard(scope, api) {
+      return function SyntheticSettingsCard() {
+        const snapshot = useScope(scope)
+        const configured = snapshot.value || {}
+        const reference = configured.apiKeyEnv || DEFAULT_API_KEY_ENV
+        const [apiKey, setApiKey] = React.useState('')
+        const [baseURL, setBaseURL] = React.useState('')
+        const [credentialState, setCredentialState] = React.useState({ configured: false, writable: true })
+        const [status, setStatus] = React.useState('')
+        const [saving, setSaving] = React.useState(false)
+        const [open, setOpen] = React.useState(false)
+
+        React.useEffect(() => {
+          setBaseURL(configured.baseURL || '')
+        }, [configured.baseURL])
+
+        React.useEffect(() => {
+          let active = true
+          api.credentials.describe({ refs: [reference] }).then((response) => {
+            if (!active || !response.result.ok) return
+            const credential = response.result.value.credentials[reference]
+            setCredentialState({
+              configured: credential?.configured === true,
+              writable: credential?.writable !== false,
+            })
+          }).catch(() => {})
+          return () => { active = false }
+        }, [api, reference])
+
+        if (snapshot.status === 'unavailable') return null
+        if (snapshot.status === 'loading') return React.createElement('p', null, 'Loading Synthetic search settings…')
+
+        const save = async () => {
+          setSaving(true)
+          setStatus('')
+          try {
+            const nextBaseURL = baseURL.trim()
+            if (nextBaseURL.length === 0) await scope.unset('baseURL')
+            else await scope.set('baseURL', nextBaseURL)
+
+            if (apiKey.trim().length > 0) {
+              await api.credentials.set({ ref: reference, value: apiKey.trim() })
+              setApiKey('')
+              setCredentialState((current) => ({ ...current, configured: true }))
+            }
+            setStatus('Saved.')
+          } catch {
+            setStatus('Could not save the Synthetic configuration. Check the URL and credential permissions.')
+          } finally {
+            setSaving(false)
+          }
+        }
+
+        const baseValue = configured.baseURL || ''
+        const dirty = apiKey.trim().length > 0 || baseURL !== baseValue
+        const discard = () => {
+          setApiKey('')
+          setBaseURL(baseValue)
+          setStatus('')
+        }
+        const body = open ? React.createElement('div', { className: 'YyYd_a_body' },
+          React.createElement('label', { className: 'At1oFq_field' },
+            React.createElement('span', { className: 'At1oFq_head' },
+              React.createElement('span', { className: 'At1oFq_label' }, 'API key'),
+              React.createElement('span', { className: credentialState.configured ? 'At1oFq_badge' : 'At1oFq_badgeMuted' }, credentialState.configured ? 'Configured' : 'Not configured'),
+            ),
+            React.createElement('input', {
+              className: 'At1oFq_input',
+              type: 'password',
+              value: apiKey,
+              disabled: saving || !credentialState.writable,
+              placeholder: credentialState.configured ? 'Enter a replacement key' : 'Enter a Synthetic API key',
+              onChange: (event) => setApiKey(event.target.value),
+            }),
+            React.createElement('p', { className: 'At1oFq_hint' }, credentialState.configured ? 'A key is stored in DSH credentials.' : `No key is configured for ${reference}.`),
+          ),
+          React.createElement('label', { className: 'At1oFq_field' },
+            React.createElement('span', { className: 'At1oFq_head' },
+              React.createElement('span', { className: 'At1oFq_label' }, 'API base URL'),
+            ),
+            React.createElement('input', {
+              className: 'At1oFq_input',
+              type: 'url',
+              value: baseURL,
+              disabled: saving || !snapshot.writable,
+              placeholder: DEFAULT_BASE_URL,
+              onChange: (event) => setBaseURL(event.target.value),
+            }),
+            React.createElement('p', { className: 'At1oFq_hint' }, 'Leave blank to use https://api.synthetic.new.'),
+          ),
+          React.createElement('div', { className: 'YyYd_a_footer' },
+            status.length > 0 ? React.createElement('p', { className: 'YyYd_a_failed', role: 'status' }, status) : null,
+            React.createElement('button', {
+              type: 'button',
+              className: 'YyYd_a_discard',
+              onClick: discard,
+              disabled: !dirty || saving,
+            }, 'Discard'),
+            React.createElement('button', {
+              type: 'button',
+              className: 'YyYd_a_save',
+              onClick: save,
+              disabled: !dirty || saving || !snapshot.writable,
+            }, saving ? 'Saving…' : 'Save'),
+          ),
+        ) : null
+        return React.createElement('li', {
+          className: open ? 'YyYd_a_card YyYd_a_cardOpen' : 'YyYd_a_card',
+        },
+        React.createElement('button', {
+          type: 'button',
+          className: 'YyYd_a_header',
+          'aria-expanded': open,
+          'aria-label': `${open ? 'Collapse' : 'Expand'}: Synthetic web search`,
+          onClick: () => setOpen(!open),
+        },
+        React.createElement('span', { className: 'YyYd_a_headText' },
+          React.createElement('span', { className: 'YyYd_a_name' }, 'Synthetic web search'),
+          React.createElement('span', { className: 'YyYd_a_description' }, 'The Synthetic search provider.'),
+        ),
+        React.createElement('span', { className: open ? 'YyYd_a_chevron YyYd_a_chevronOpen' : 'YyYd_a_chevron', 'aria-hidden': true }, '⌄'),
+        ),
+        body)
+      }
+    }
+
+    function apply(ctx) {
+      const scope = ctx.settingsScope.bind({ namespace: SETTINGS_NAMESPACE })
+      const api = ctx.connection.api
+      const Card = createCard(scope, api)
+      ctx.slots.inject('settings.plugin.item', () => ctx.slots.register({
+        name: 'settings.plugin.item',
+        key: SETTINGS_NAMESPACE,
+      }, Card))
+    }
+
+    exports.inject = inject
+    exports.apply = apply
+    return module.exports
+  },
+})

package/lib/index.d.ts

@@ -0,0 +1,34 @@
+import z from '@deepseek-ai/schemastery';
+import type { Context } from '@deepseek-ai/cordis';
+/** Default Synthetic API origin. */
+export declare const SYNTHETIC_DEFAULT_BASE_URL = "https://api.synthetic.new";
+/** Default credential reference, shared by the Settings card and launch environment. */
+export declare const SYNTHETIC_DEFAULT_API_KEY_ENV = "SYNTHETIC_API_KEY";
+/** Namespace exposed to Settings > Plugins > Plugin configuration. */
+export declare const SYNTHETIC_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+export { SyntheticSearchProvider, SYNTHETIC_DEFAULT_ENDPOINT, SYNTHETIC_PROVIDER_ID, mapSyntheticResponse, mapSyntheticResult, } from './provider.js';
+export type { SyntheticSearchProviderOptions } from './provider.js';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "web-search-synthetic";
+/** The provider registers into the host-owned web capability seam. */
+export declare const inject: string[];
+export interface Config {
+    /** Optional literal API key. Settings stores keys in the credentials domain instead. */
+    apiKey?: string;
+    /** Credential reference used by Settings and the launch environment. */
+    apiKeyEnv?: string;
+    /** Synthetic API origin. The provider appends `/v2/search`. */
+    baseURL?: string;
+}
+/** Loader and Settings schema. Secret values are redacted from all Settings wire responses. */
+export declare const Config: z<Schemastery.ObjectS<{
+    apiKey: z<string, string>;
+    apiKeyEnv: z<string, string>;
+    baseURL: z<string, string>;
+}>, Schemastery.ObjectT<{
+    apiKey: z<string, string>;
+    apiKeyEnv: z<string, string>;
+    baseURL: z<string, string>;
+}>>;
+/** Register Synthetic as a search provider and expose its persisted Settings section. */
+export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -0,0 +1,54 @@
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment';
+import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings';
+import z from '@deepseek-ai/schemastery';
+import { SyntheticSearchProvider } from './provider.js';
+/** Default Synthetic API origin. */
+export const SYNTHETIC_DEFAULT_BASE_URL = 'https://api.synthetic.new';
+/** Default credential reference, shared by the Settings card and launch environment. */
+export const SYNTHETIC_DEFAULT_API_KEY_ENV = 'SYNTHETIC_API_KEY';
+/** Namespace exposed to Settings > Plugins > Plugin configuration. */
+export const SYNTHETIC_SETTINGS_NAMESPACE = settingsNamespace('web-search-synthetic');
+export { SyntheticSearchProvider, SYNTHETIC_DEFAULT_ENDPOINT, SYNTHETIC_PROVIDER_ID, mapSyntheticResponse, mapSyntheticResult, } from './provider.js';
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'web-search-synthetic';
+/** The provider registers into the host-owned web capability seam. */
+export const inject = ['web'];
+/** Loader and Settings schema. Secret values are redacted from all Settings wire responses. */
+export const Config = z.object({
+    apiKey: z.string().role('secret'),
+    apiKeyEnv: z.string().role('credential-ref').default(SYNTHETIC_DEFAULT_API_KEY_ENV),
+    baseURL: z.string(),
+});
+/** Register Synthetic as a search provider and expose its persisted Settings section. */
+export function apply(ctx, config) {
+    let current = () => config;
+    installSettingsSection(ctx, SYNTHETIC_SETTINGS_NAMESPACE, Config, config, {
+        setSource: (source) => {
+            current = source;
+        },
+        onChange: () => { },
+    });
+    ctx.web.registerSearchProvider(new SyntheticSearchProvider(() => resolveOptions(ctx, current())));
+}
+function resolveOptions(ctx, config) {
+    const apiKeyEnv = config.apiKeyEnv ?? SYNTHETIC_DEFAULT_API_KEY_ENV;
+    const ref = credentialRef(apiKeyEnv);
+    return {
+        apiKey: config.apiKey,
+        apiKeyEnv,
+        endpoint: searchEndpoint(config.baseURL ?? SYNTHETIC_DEFAULT_BASE_URL),
+        resolveApiKey: async () => {
+            const credential = await ctx.get('credentials')?.resolve(ref);
+            return credential?.value ?? launchEnvironmentOf(ctx).get(apiKeyEnv)?.value;
+        },
+    };
+}
+function searchEndpoint(baseURL) {
+    try {
+        return new URL('/v2/search', baseURL).toString();
+    }
+    catch {
+        return baseURL;
+    }
+}

package/lib/invariant.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis plugin name for the package's invariant companion. */
+export declare const name = "web-search-synthetic-invariant";
+export declare const inject: string[];
+/** Register package ownership; the provider has no independent runtime invariant. */
+export declare function apply(ctx: Context): Promise<() => void>;

package/lib/invariant.js

@@ -0,0 +1,8 @@
+const PACKAGE_NAME = '@auggieteo/dsh-synthetic-web-search';
+/** Cordis plugin name for the package's invariant companion. */
+export const name = 'web-search-synthetic-invariant';
+export const inject = ['invariants'];
+/** Register package ownership; the provider has no independent runtime invariant. */
+export function apply(ctx) {
+    return Promise.resolve(ctx.invariants.register(PACKAGE_NAME, () => { }));
+}

package/lib/provider.d.ts

@@ -0,0 +1,38 @@
+import type { WebSearchProvider, WebSearchRequest, WebSearchResult, WebSearchSource } from '@deepseek-ai/dsh-web';
+/** Stable id used by the Harness web-provider registry. */
+export declare const SYNTHETIC_PROVIDER_ID = "synthetic";
+/** Synthetic's documented web-search endpoint. */
+export declare const SYNTHETIC_DEFAULT_ENDPOINT = "https://api.synthetic.new/v2/search";
+export interface SyntheticSearchProviderOptions {
+    /** Optional literal API key from the composition layer. */
+    apiKey?: string;
+    /** Resolves the API key held by DSH credentials or the launch environment. */
+    resolveApiKey?: () => Promise<string | undefined>;
+    /** The credential reference shown in missing-key errors. */
+    apiKeyEnv?: string;
+    /** Complete Synthetic search endpoint. */
+    endpoint: string;
+}
+interface SyntheticSearchResult {
+    url: string;
+    title?: string;
+    text?: string;
+    published?: string;
+}
+interface SyntheticSearchResponse {
+    results: SyntheticSearchResult[];
+}
+/** Convert a Synthetic result into the web seam's portable source shape. */
+export declare function mapSyntheticResult(result: SyntheticSearchResult): WebSearchSource | undefined;
+/** Convert a validated Synthetic response into the Harness result shape. */
+export declare function mapSyntheticResponse(response: SyntheticSearchResponse): WebSearchResult;
+/** A Synthetic-backed implementation of the Harness WebSearchProvider contract. */
+export declare class SyntheticSearchProvider implements WebSearchProvider {
+    readonly id = "synthetic";
+    private readonly resolveOptions;
+    constructor(options: SyntheticSearchProviderOptions | (() => SyntheticSearchProviderOptions));
+    available(): boolean;
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+    private apiKey;
+}
+export {};

package/lib/provider.js

@@ -0,0 +1,162 @@
+import { WebError } from '@deepseek-ai/dsh-web';
+/** Stable id used by the Harness web-provider registry. */
+export const SYNTHETIC_PROVIDER_ID = 'synthetic';
+/** Synthetic's documented web-search endpoint. */
+export const SYNTHETIC_DEFAULT_ENDPOINT = 'https://api.synthetic.new/v2/search';
+const USER_AGENT = 'deepseek-harness-synthetic/0.1.0';
+/** Convert a Synthetic result into the web seam's portable source shape. */
+export function mapSyntheticResult(result) {
+    if (result.url.trim().length === 0 || !URL.canParse(result.url))
+        return undefined;
+    return {
+        url: result.url,
+        ...(nonBlankString(result.title) ? { title: result.title } : {}),
+        ...(nonBlankString(result.text) ? { snippet: result.text } : {}),
+        ...(nonBlankString(result.published) ? { publishedAt: result.published } : {}),
+    };
+}
+/** Convert a validated Synthetic response into the Harness result shape. */
+export function mapSyntheticResponse(response) {
+    return {
+        sources: response.results
+            .map(mapSyntheticResult)
+            .filter((source) => source !== undefined),
+        truncated: false,
+    };
+}
+/** A Synthetic-backed implementation of the Harness WebSearchProvider contract. */
+export class SyntheticSearchProvider {
+    id = SYNTHETIC_PROVIDER_ID;
+    resolveOptions;
+    constructor(options) {
+        this.resolveOptions = typeof options === 'function' ? options : () => options;
+    }
+    available() {
+        const options = this.resolveOptions();
+        return (((options.apiKey?.trim().length ?? 0) > 0 || options.resolveApiKey !== undefined) &&
+            URL.canParse(options.endpoint));
+    }
+    async search(request, signal) {
+        const options = this.resolveOptions();
+        const apiKey = await this.apiKey(options, signal);
+        throwIfAborted(signal);
+        let response;
+        try {
+            response = await fetch(options.endpoint, {
+                method: 'POST',
+                redirect: 'error',
+                headers: {
+                    authorization: `Bearer ${apiKey}`,
+                    accept: 'application/json',
+                    'content-type': 'application/json',
+                    'user-agent': USER_AGENT,
+                },
+                body: JSON.stringify({ query: request.query }),
+                ...(signal === undefined ? {} : { signal }),
+            });
+        }
+        catch (error) {
+            if (signal?.aborted === true || isAbortError(error))
+                throw aborted(signal, error);
+            throw new WebError(`Synthetic search request failed: ${String(error)}`, 'WEB_PROVIDER_ERROR', { cause: error });
+        }
+        if (!response.ok)
+            throw new WebError(await errorMessage(response, signal), 'WEB_PROVIDER_ERROR');
+        try {
+            return mapSyntheticResponse(parseResponse(await response.json()));
+        }
+        catch (error) {
+            if (signal?.aborted === true || isAbortError(error))
+                throw aborted(signal, error);
+            if (error instanceof WebError)
+                throw error;
+            throw new WebError(`Synthetic returned an unprocessable response body: ${String(error)}`, 'WEB_PROVIDER_ERROR', { cause: error });
+        }
+    }
+    async apiKey(options, signal) {
+        throwIfAborted(signal);
+        if (nonBlankString(options.apiKey))
+            return options.apiKey;
+        let resolved;
+        try {
+            resolved = await abortable(options.resolveApiKey?.() ?? Promise.resolve(undefined), signal);
+        }
+        catch (error) {
+            if (signal?.aborted === true || isAbortError(error))
+                throw aborted(signal, error);
+            throw new WebError(`Synthetic search credential resolution failed: ${String(error)}`, 'WEB_PROVIDER_ERROR', { cause: error });
+        }
+        if (nonBlankString(resolved))
+            return resolved;
+        throw new WebError(`Synthetic search has no API key for "${options.apiKeyEnv ?? 'SYNTHETIC_API_KEY'}"; configure it in Settings > Plugins > Plugin configuration, export it in the launching environment, or set a literal "apiKey" in the web-search-synthetic config`, 'WEB_PROVIDER_CREDENTIAL_MISSING');
+    }
+}
+function nonBlankString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function parseResponse(value) {
+    if (!isRecord(value) || !Array.isArray(value.results)) {
+        throw new Error('response must contain a results array');
+    }
+    return {
+        results: value.results.flatMap((result) => {
+            if (!isRecord(result) || typeof result.url !== 'string')
+                return [];
+            return [{
+                    url: result.url,
+                    ...(typeof result.title === 'string' ? { title: result.title } : {}),
+                    ...(typeof result.text === 'string' ? { text: result.text } : {}),
+                    ...(typeof result.published === 'string' ? { published: result.published } : {}),
+                }];
+        }),
+    };
+}
+async function errorMessage(response, signal) {
+    const fallback = `Synthetic API error (HTTP ${response.status})`;
+    try {
+        const body = await response.json();
+        if (!isRecord(body))
+            return fallback;
+        for (const key of ['error', 'message', 'detail']) {
+            if (nonBlankString(body[key]))
+                return body[key];
+        }
+    }
+    catch (error) {
+        if (signal?.aborted === true || isAbortError(error))
+            throw aborted(signal, error);
+    }
+    return fallback;
+}
+function abortable(operation, signal) {
+    if (signal === undefined)
+        return operation;
+    if (signal.aborted)
+        return Promise.reject(aborted(signal));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(aborted(signal));
+        signal.addEventListener('abort', onAbort, { once: true });
+        operation.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(error);
+        });
+    });
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted === true)
+        throw aborted(signal);
+}
+function aborted(signal, fallback) {
+    return new WebError('Synthetic search aborted', 'WEB_ABORTED', {
+        cause: signal?.aborted === true ? signal.reason : fallback,
+    });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isAbortError(error) {
+    return error instanceof DOMException && error.name === 'AbortError';
+}

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@auggieteo/dsh-synthetic-web-search",
+  "version": "0.2.0",
+  "description": "Synthetic-backed search provider and Settings card for the DeepSeek Harness web capability seam (ctx.web)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/auggie246/dsh-synthetic-web-search.git"
+  },
+  "bugs": {
+    "url": "https://github.com/auggie246/dsh-synthetic-web-search/issues"
+  },
+  "homepage": "https://github.com/auggie246/dsh-synthetic-web-search#readme",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/client.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./invariant": {
+      "types": "./lib/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-settings-plugins",
+        "@deepseek-ai/dsh-client-connection"
+      ]
+    }
+  },
+  "files": [
+    "lib",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "node ./scripts/build.mjs --clean-only",
+    "build": "node ./scripts/build.mjs",
+    "check": "tsc --noEmit",
+    "test": "tsx --test test/**/*.test.ts",
+    "prepare": "npm run build",
+    "prepack": "npm run build",
+    "verify": "npm run clean && npm run check && npm test && npm run build && npm pack --dry-run"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-credentials": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-web": "^0.1.1-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-credentials": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-web": "^0.1.1-rc.2",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}