dsh-web-search-toggle

Readme

# dsh-web-search-toggle

A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH)
plugin that adds a **"Web Search"** toggle button to the chat composer tool row.
When it is turned on, the agent is instructed that it **must search the web
before answering** — mirroring the "Web Search" toggle in the DeepSeek Web Chat
UI. The toggle is **per-session** (per conversation), like DeepSeek's own
per-conversation toggle.

## Features

- Adds a compact, pill-shaped **"Web Search"** button in the composer tool row.
  Inactive = neutral outline; active = DeepSeek brand blue with a small green
  "on" dot.
- When ON, injects a mandatory **system-prompt directive** telling the agent to
  call `web_search` before answering, on every turn of that session.
- Per-session state, persisted across reloads and host restarts.
- Follows DSH's plugin conventions (`dsh.bundle.patch` + `dsh.client`), so it
  installs like any other DSH web-profile plugin.

<img width="1912" height="1037" alt="Screenshot 2026-08-22 170659" src="https://github.com/user-attachments/assets/51ac6fb5-fb93-4a06-9c59-727aea3d25df" />

## How it works

- **Client half** (`lib/client.js`): registers the toggle into the composer's
  tool row (`conversation.input.left`, the seat beside the resident access-mode
  / plan / attach chrome). On toggle it calls the host through the
  client↔host RPC channel.
- **Host half** (`index.js`):
  - Serves an RPC channel (`/dsh-web-search`) with `websearch.get-state` /
    `websearch.set-state`, storing the flag per session and persisting it to
    `~/.dsh/dsh-web-search-toggle.json`.
  - Registers a **system-prompt section** (`dsh-web-search:force`) whose text is
    evaluated on every prompt assembly. When the current session's flag is ON,
    it injects a mandatory "you MUST call `web_search` first" directive into the
    system prompt; when OFF it renders empty (empty sections disappear).

The `web_search` tool itself is registered by DSH's own `dsh-tool-web` package
(via the auto-selected DeepSeek search-provider seam); this plugin only forces
its use.

## Why "force" is a directive, not a hard block

DSH has no primitive for "the model MUST call tool X on every turn." So the
enforcement is a strong, always-present **system-prompt instruction** — the
authoritative, reliable way to steer the model in this harness. The model
follows it, but compliance is probabilistic rather than guaranteed (as in the
DeepSeek web chat UI itself).

## Requirements

- DeepSeek Harness with the **web** profile (`dsh --profile web`).
- A configured web search provider (the built-in DeepSeek search provider, or
  any `web_search`-providing provider). The plugin forces the tool; it does not
  install one.

## Installation

The plugin is published to npm. From the DSH **web** profile:

```bash
# via the dsh plugin command (recommended — reconciles the bundle list)
dsh plugin --profile web add dsh-web-search-toggle
```

or with pnpm directly (skips bundle-list reconcile):

```bash
cd <your-profile-dir>
npx pnpm add dsh-web-search-toggle
# then add "dsh-web-search-toggle" to dsh.profile.bundles in package.json
```

Then **restart DSH** so the bundle patch composes at boot:

```bash
dsh --profile web restart          # or your normal restart path
```

## Usage

1. Open a conversation in the DSH web UI.
2. Click the **Web Search** pill in the composer tool row to toggle it on.
3. Ask a question — the agent calls `web_search` first and cites sources.
4. Toggle it off to restore normal behavior.

The on/off state is remembered per session.

## Files

| Path | Purpose |
|---|---|
| `package.json` | Package + `dsh.bundle.patch` + `dsh.client` declaration |
| `index.js` | Host plugin: RPC channel + system-prompt force section |
| `lib/client.js` | Client plugin: composer "Web Search" toggle |
| `cordis.patch.yml` | Bundle patch mounting the host half |
| `LICENSE` | MIT License |
| `README.md` | This file |

## License

[MIT](./LICENSE)