dsh-http-probe

Readme

# dsh-http-probe

Third-party DeepSeek Harness plugin bundle providing the model-facing `http_probe` tool: a controlled HTTP GET against a deployment-owned probe target.

## Features

- Controlled probe: only the URL path is model-controlled; host and port come from deployment config.
- Deployment-owned `baseUrl`.
- Bounded response body read: past the byte cap the read stops and the canonical result carries `truncated: true`.
- Cooperative timeout integration: the budget is declared on the tool and enforced by the host tool-call timeout policy.
- Structured canonical Tool result (`ok`, `status`, `url`, `contentType`, `body`, `truncated`), with the model-facing text produced separately by `output.render`.
- Redirects are not followed automatically (`redirect: 'manual'`).

## Installation

Prebuilt GitHub Release tarball (the currently verified distribution path):

1. Download `dsh-http-probe-0.1.0.tgz` from the [Releases page](https://github.com/TwistedRiCen/dsh-http-probe/releases).
2. Install it with:

```sh
dsh plugin --profile <profile> add /path/to/dsh-http-probe-0.1.0.tgz
```

The package declares `dsh.bundle`, so `dsh plugin add` registers it as a profile bundle layer automatically. Remove it with:

```sh
dsh plugin --profile <profile> remove dsh-http-probe
```

## Configuration

| Field | Type | Default | Meaning |
|---|---|---|---|
| `baseUrl` | string | `http://127.0.0.1:3199` | Probe target base URL (http/https, normalized with a trailing `/`). |
| `maxBodyBytes` | number | `8192` | Maximum response body bytes read from the wire; past it the read stops and the canonical result carries `truncated: true`. |
| `timeoutMs` | number | `2000` | Cooperative tool-call timeout budget, enforced by the host's `@deepseek-ai/dsh-tool-call-timeout-policy`. |

Config is validated by the plugin at load (no schema dependency): unknown fields and non-positive-integer limits fail loud.

## Tool

- Name: `http_probe`
- Parameter: `path` only — must start with a single `/`; no `..` segments, query, fragment, or control characters.

Example: `Use the http_probe tool to GET /ok.`

## Security

- The model cannot choose a full URL: only `path` is exposed.
- `baseUrl` is deployment configuration.
- Redirects are not followed automatically.
- This is a fixed-target probe, not a general-purpose arbitrary-URL fetcher.

## Compatibility / Developer Preview

- Requires the host to provide `@deepseek-ai/cordis@4.0.1` and `@deepseek-ai/dsh-tools@0.1.0-rc.5` (hard peer dependencies).
- `@deepseek-ai/dsh-tools@0.1.0-rc.5` is not currently published on the npm registry, therefore:
  - Prebuilt tarball installation is verified and supported.
  - Git source self-contained install is not verified and is currently blocked.
  - Do not substitute a different `@deepseek-ai/dsh-tools` version; keep the exact host version.

## Development

- The public `tsconfig.json` carries no machine-specific paths and is used by `pnpm build`.
- While `@deepseek-ai/dsh-tools@0.1.0-rc.5` types are unavailable from the registry, local development uses a gitignored `tsconfig.local.json` that extends `./tsconfig.json` with a `paths` mapping to a local rc.5 declaration build; run `pnpm build:local` to use it.
- `tsconfig.local.json` never ships in the tarball and never enters Git.