# Contributing

Thanks for helping improve `dsh-llm-call-inspector`. This package is deliberately narrow: it observes session-associated normalized LLM calls and presents them locally without changing model behavior.

## Development baseline

- Node.js `22.19.x`
- pnpm `11.21.0`
- DeepSeek Harness packages `0.1.2-alpha.2` for the current exact compatibility lane

Install and run the complete local gate:

```sh
pnpm install --frozen-lockfile
pnpm verify
pnpm pack --dry-run
```

Build artifacts under `lib/` are part of the GitHub distribution and must be updated with source changes. Do not add a `prepare`, `preinstall`, `install`, or `postinstall` script: Git consumers should not have to authorize package code execution during installation.

## Design invariants

Changes must preserve these boundaries unless a proposal explicitly revises the public design:

- Observe the public `llm/stream` seam and delegate exactly once.
- Do not mutate request objects, chunk objects, stream order, or thrown outcomes.
- Capture only calls with a DSH `sessionId` and only the documented normalized request allowlist.
- Never capture top-level headers, API keys, abort signals, or adapter-private request extensions.
- Keep prompt/tool/result sensitivity visible; structural exclusion is not content redaction.
- Keep records bounded by per-body, per-session, session-count, and global-body limits; session-isolated; memory-only; and explicitly clearable.
- Keep state summaries body-free; fetch one selected detail separately.
- Register the Connection channel through the current DSH authenticated-browser contract, validate every RPC payload, and document that DSH-approved non-loopback browser sessions can access captured bodies.
- Use the public `conversation.view` slot; do not patch or copy Trajectory internals.
- Do not claim provider-native HTTP/SSE visibility from normalized DSH chunks.

## Tests expected for a change

- Host transparency and fail-open capture behavior.
- Request allowlist, byte omissions, response ordering, and retention eviction.
- RPC browser-auth contract, payload validation, session isolation, cancellation, and disposal.
- UI loading/error/empty/running states, filters, detail selection, copy, clear, polling cleanup, keyboard focus, and narrow layout when affected.
- Build and package checks for any manifest, export, loader, patch, or dependency change.

For a new DSH prerelease, update dependency declarations only after testing a fresh profile install, `--dump-config`, real Web boot, and browser interaction. DSH is a developer preview; a passing typecheck alone is not a compatibility receipt.

## Pull requests

Keep each pull request focused and include:

- the user-visible problem and intended behavior;
- privacy or compatibility impact;
- commands run and their results;
- screenshots for material UI changes; and
- any verification that remains pending.

Do not include real prompts, tool results, API keys, or proprietary trace data in issues, fixtures, screenshots, or test output. Use synthetic fixtures.

Security vulnerabilities should not be filed as public issues. Follow [SECURITY.md](SECURITY.md).