dsh-tool-terminal-search

A terminal_search tool plugin for 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:

# 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

// ~/.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

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. This plugin lets deployments use the capability today; switching to the native backend later is transparent.