@mini-z/dsh-search-providers 0.1.2

package/README.md

@@ -0,0 +1,188 @@
+# dsh-search-providers
+
+A modular [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/dsh) plugin that takes over `web_search` and `read_page` with an extensible provider registry and automatic failover.
+
+## Features
+
+- **Takes over native `web_search`**: registers as the DSH web seam search provider.
+- **Adds/replaces `read_page`**: fetches clean page content through the active provider.
+- **Multi-provider failover + cooldown**: automatic fallback; providers that fail are temporarily skipped to avoid repeated timeouts.
+- **Modular providers**: add more by implementing `SearchProvider`.
+- **Standard DSH configuration**: secrets via `~/.dsh/.env`, cordis config via `~/.dsh/profiles/<profile>/cordis.patch.yml`.
+- **Demo mode**: test wiring without any API key.
+
+## Supported providers
+
+| Provider | Search | Fetch | Requires API key |
+|----------|--------|-------|------------------|
+| TinyFish | ✅ | ✅ | Yes |
+| Tavily   | ✅ | ❌ | Yes |
+| Exa      | ✅ | ✅ | Yes |
+| Firecrawl| ✅ | ✅ | Yes |
+| Codex    | ✅ | ❌ | Static credential file in `~/.dsh` |
+| Demo     | ✅ | ✅ | No |
+
+## Installation
+
+### Option 1: Install from npm (when published)
+
+```bash
+npx -y @deepseek-ai/dsh plugin --profile web add @mini-z/dsh-search-providers
+```
+
+### Option 2: Local / migrate from another machine
+
+1. Copy the project folder (or the migration zip) to the target machine.
+2. Install dependencies:
+
+   ```bash
+   cd dsh-search-providers
+   bun install --frozen-lockfile
+   ```
+
+3. Configure API keys in `~/.dsh/.env` (see [Configuration](#configuration)).
+
+4. Link the plugin into your DSH profile:
+
+   ```bash
+   cd ~/.dsh/profiles/<your-profile>
+   npx -y @deepseek-ai/dsh plugin add /path/to/dsh-search-providers
+   ```
+
+> The built plugin artifacts are already included in `dsh/`, so you do not need to run `bun run build` unless you modify the source.
+
+### Option 3: Development install
+
+```bash
+git clone <repo-url>
+cd dsh-search-providers
+bun install
+bun run build
+```
+
+## Configuration
+
+This plugin follows DSH conventions: secrets go in `~/.dsh/.env`, and cordis-level config goes in the profile patch file.
+
+### Environment variables
+
+Put one or more of these in `~/.dsh/.env`:
+
+```bash
+TINYFISH_API_KEY=...
+TAVILY_API_KEY=...
+EXA_API_KEY=...
+FIRECRAWL_API_KEY=...
+CODEX_CREDENTIAL_FILE=C:/Users/you/.dsh/some-codex-auth.json
+```
+
+DSH loads this file automatically when the profile starts. Providers are tried in this default priority order:
+
+1. Codex
+2. TinyFish
+3. Tavily
+4. Exa
+5. Firecrawl
+
+API-key providers are attempted only when their key is configured. Codex is attempted only when `CODEX_CREDENTIAL_FILE` points to a usable static credential file. Missing or malformed configuration is silently skipped. Confirmed authentication failures disable that provider until DSH restarts; ordinary HTTP 403 responses do not. Rate limits use a 5-minute cooldown, network/timeouts 30 seconds, and other failures 10 seconds. Transient cooldowns are isolated between search and page fetching, and caller cancellation never cools a provider. Successful fallback responses identify cooling and disabled providers explicitly.
+
+### Codex credential file
+
+Codex is fully independent of login or model plugins. Set `CODEX_CREDENTIAL_FILE` to any specific JSON credential file. When the variable is absent, the Codex provider is disabled. The minimal JSON shape is:
+
+```json
+{
+  "access_token": "eyJ...",
+  "account_id": "account-id"
+}
+```
+
+The reader explicitly supports top-level fields plus `credential` and `tokens` wrappers. Access-token fields may be named `access_token` or `access`; account fields may be named `account_id` or `accountId`. When the account field is absent, the standard `chatgpt_account_id` JWT claim is used. Extra fields—including `refresh_token`, `expired`, `expires_at`, and `expires`—are ignored.
+
+This plugin only reads the file. It never starts a login, refreshes a token, checks local timestamps, or writes credential data. A missing or malformed credential makes Codex unavailable and is skipped. If Codex rejects the credential with HTTP 401/403, Codex is disabled until restart and the normal fallback chain continues. Restrict the file's filesystem permissions to the owning user.
+
+Codex does not implement `read_page`, and its standalone endpoint ignores this plugin's recency, domain, location, language, and maximum-result filters.
+
+### Override the active provider or fallback order
+
+The active `provider` is always tried first. `fallbackChain` lists the providers to try afterward, is de-duplicated in order, and may be an empty array to disable fallback.
+
+Edit `~/.dsh/profiles/<profile>/cordis.patch.yml`:
+
+```yaml
+- id: search-providers
+  config:
+    provider: exa
+    fallbackChain: [codex, tinyfish, tavily, firecrawl]
+    providers:
+      exa:
+        timeoutMs: 55000
+```
+
+## Usage
+
+Once the plugin is loaded by DSH, the model can use the native `web_search` and `read_page` tools. No extra configuration is needed.
+
+### web_search
+
+Ask the model to search the web:
+
+```text
+Search the web for "latest Rust memory safety features".
+```
+
+The plugin will use the active provider and automatically fall back to the next available provider if the first one fails. Every successful result starts with `[Search provider: ...]`, naming the provider that actually returned it.
+
+### read_page
+
+Give the model a URL to read:
+
+```text
+Read this page: https://example.com/article
+```
+
+The plugin will fetch the page content through the active provider (or the first available fetch-capable provider in the fallback chain).
+
+> Note: Tavily and Codex support search only, so they are skipped for `read_page`.
+
+## Demo mode (test without API key)
+
+```bash
+SEARCH_PROVIDERS_DEMO=1 npx -y @deepseek-ai/dsh --profile web --no-open --port 9876
+```
+
+Then ask the model to run `web_search` or `read_page`; it will receive canned demo results.
+
+## Development
+
+```bash
+bun install
+bun run typecheck
+bun run test
+bun run build
+```
+
+## Architecture
+
+- `src/providers/types.ts` — `SearchProvider` interface.
+- `src/providers/registry.ts` — provider registry and active-provider selection.
+- `src/providers/cooldown.ts` — failure tracking and cooldown logic.
+- `src/providers/tinyfish.ts`, `tavily.ts`, `exa.ts`, `firecrawl.ts`, `codex.ts` — provider implementations.
+- `src/providers/demo.ts` — canned demo provider for testing.
+- `src/tools/web-search.ts` — registers the plugin as `ctx.web.registerSearchProvider` with failover.
+- `src/tools/read-page.ts` — registers the `read_page` tool with failover.
+- `src/index.ts` — DSH plugin entry (`apply`).
+
+## Adding a provider
+
+Implement the `SearchProvider` interface, register it in `src/index.ts`, and add its config resolution.
+
+## Publishing
+
+1. Bump the version in `package.json`.
+2. `npm login`
+3. `bun publish --access public`
+
+## License
+
+MIT. The Codex interoperability implementation was developed with reference to [dsh-codex-connect](https://github.com/franksong2702/dsh-codex-connect) (Apache-2.0); no runtime dependency on that package is required.

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh bundle patch: mount the search-providers plugin and route the web seam
+# search capability through it. This replaces the default search provider.
+- id: web
+  config:
+    searchProvider: search-providers
+
+- insert:
+    - id: search-providers
+      name: '@mini-z/dsh-search-providers'

package/dsh/client.js

@@ -0,0 +1,7 @@
+function init() {
+  console.log("[search-providers] client stub loaded");
+}
+export {
+  init
+};
+//# sourceMappingURL=client.js.map

package/dsh/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sources":["../src/client.ts"],"sourcesContent":["// Browser-side companion for dsh web settings card.\n// Currently a no-op stub; Phase 6 can add a configuration UI here.\nexport function init() {\n  console.log('[search-providers] client stub loaded');\n}\n"],"names":[],"mappings":"AAEO,SAAS,OAAO;AACrB,UAAQ,IAAI,uCAAuC;AACrD;"}