# Contributing to dsh-webbridge

Focused fixes, tests, and documentation changes are welcome. By participating, you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md).

## Before you start

1. Read [README.md](README.md) — install, usage, and troubleshooting.
2. Search existing [issues](https://github.com/omdsh-dev/dsh-webbridge/issues) and pull requests before opening duplicate work.
3. Open an issue before changing the tool surface (which `webbridge_*` tools are exposed, the session contract) or the bundle manifest (`cordis.patch.yml` — the row id `webbridge` deliberately matches the DSH built-in).
4. Keep each change narrowly scoped. Do not mix a feature or fix with unrelated refactoring or generated-output churn.

## Architecture and scope

dsh-webbridge is an out-of-tree DeepSeek Harness host plugin. Contributions must preserve these responsibilities:

- The plugin is a standard DSH **bundle** (host-only: `dsh.bundle` + `cordis.patch.yml`) that registers `webbridge_*` model tools on the `tools` service. It ships no browser-driving code of its own — every action goes through the separately installed Kimi WebBridge daemon and browser extension.
- Tools must fail loud with a `daemon_unreachable` error when the daemon is not running, and browser state must stay in the user's browser — never copy it into model requests (no KV-cache burden).
- The row id `webbridge` deliberately matches the built-in plugin; a later bundle layer replaces an earlier row of the same id, so the override behavior must be preserved.
- The session contract is upstream (Kimi WebBridge): one task = one session = one tab group, and closing is always user-initiated. Do not change tool semantics without coordinating upstream.

## Development

```sh
pnpm install
DSH_CHECKOUT=/path/to/dsh pnpm run build   # tsc -> lib/types, tsdown -> lib/index.js (committed)
```

Peer dependencies and the toolchain come from DSH: set `DSH_CHECKOUT` to a source checkout, or have `dsh` on `PATH` and run it once. Unit tests (`tests/client.spec.ts`) run against a mock HTTP daemon, so no real Kimi install is required; run them in a vitest-equipped environment (e.g. the DSH checkout) and set `KIMI_WEBBRIDGE_IT=1` to run integration tests against a live daemon.

Keep the bilingual README in sync (edit both `README.md` and `README.zh.md`, then `node scripts/verify-i18n.mjs --write`).

## Commit and release

- Bump the version and update `CHANGELOG.md` (Keep a Changelog format) in the same change that ships a user-visible difference.
- Tag releases with a semantic version (`v0.0.3`) and push tags with the release.