dsh-tool-terminal-search

Readme

# dsh-tool-terminal-search

[![powered by dsh](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

A `terminal_search` tool plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh): locate lines in large retained terminal scrollback by literal substring or regular expression, without paging backward blindly through tens of thousands of log lines.

The tool is composed **only** over the public `ctx.terminals.read` seam — no upstream package changes, so it runs on published dsh releases today.

## Why

`terminal_read` pages retained scrollback by newest-relative `offset`/`count`. With backend log output running to tens of thousands of lines, a model cannot tell where the interesting lines are: it has to page backward from the newest output one page at a time, and `totalLines` alone does not locate a needle in the retained buffer. `terminal_search` closes that gap by finding lines by content.

## Install

Install with the dsh CLI — it forwards pnpm into the profile directory — then add the package to the profile's `bundles` list. The bundle's own patch then contributes `terminal_search` automatically:

```sh
# Installs into the profile's node_modules (dsh plugin forwards to pnpm).
dsh plugin --profile web add dsh-tool-terminal-search

# Verify the install.
dsh plugin --profile web ls
```

```jsonc
// ~/.dsh/profiles/web/package.json
{
  "dependencies": {
    "@deepseek-ai/dsh-tool-terminal": "0.1.2-alpha.5",
    "dsh-tool-terminal-search": "^0.3.0"
  },
  "dsh": {
    "profile": {
      "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-tool-terminal-search"]
    }
  }
}
```

The official `@deepseek-ai/dsh-tool-terminal` plugin (and the `dsh-terminal` / `dsh-terminal-bash` services) must still be present for `terminal_open` / `terminal_send` / `terminal_read`.

Restart your dsh profile. The model gains `terminal_search` next to the official `terminal_open` / `terminal_send` / `terminal_read` tools.

## Behavior

`terminal_search(sessionId, pattern, regex?, offset?, limit?)`:

- Pages the whole retained scrollback (newest → oldest) through `terminal_read` and matches each line.
- `pattern` is a **literal substring** by default (grep `-F` style) — no regex metacharacters to escape; pass `regex: true` to treat it as a JavaScript regular expression. Compiled regexes go through a process-wide bounded FIFO cache (oldest entries evicted first), so repeated patterns never recompile.
- Returns matching lines **newest first**, each with a newest-relative `offset` that is directly usable as a `terminal_read` offset (jump to a match's context in one follow-up call).
- Returns the exact `matchCount`, the retained `totalLines`, and `truncated`; `offset`/`limit` page over matches.
- Renders `[offset N] line` per match plus `[search: X of Y matches, Z retained lines]`; results are capped by `maxResultBytes` (default `262144`).

## Known limitations

- One search pages the bounded scrollback in memory (`scrollbackLines` 10 000 / `scrollbackMaxBytes` 4 MiB by default), so it only sees retained lines — same contract as `terminal_read`.
- A page whose bytes exceed the backend `maxReadBytes` is reread with a smaller page size so line offsets stay exact; a single line larger than `maxReadBytes` degrades to a truncated line and sets `truncated`.
- No surrounding-context lines are returned; read around a match's offset for context.
- Requires the dsh `0.1.2-alpha.5` release line (the package's peer range resolves `@deepseek-ai/dsh-terminal` and `@deepseek-ai/dsh-tools` at `^0.1.2-alpha.5`, so it composes against newer 0.1.2-alpha.x builds of the same read contract).

## Development

```sh
npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest
npm run build       # esbuild bundle + tsc declarations into lib/
```

## Relationship to upstream

An equivalent native implementation (same tool name, schema, and coordinate space) is tracked upstream in [deepseek-harness discussion #1025](https://github.com/deepseek-ai/deepseek-harness/discussions/1025). This plugin lets deployments use the capability today; switching to the native backend later is transparent.