dsh-loglens
DeepSeek Harness plugin for bounded, cursor-aware log inspection. See
TESTING.md for the smallest install and usefulness check.
dsh-loglens is a dsh-plugin for DeepSeek Harness, not a generic log viewer or a Codex Skill. It adds bounded, cursor-aware log tools to a Harness profile and renders compact log snapshots in the Harness Web conversation UI.
Install from GitHub
Install the public plugin into a Harness profile:
dsh plugin --profile headless add github:Monicaxixi/dsh-loglens
dsh plugin --profile web add github:Monicaxixi/dsh-loglens
Restart the profile after installation. Then add .dsh/logs.yml in the project being inspected. The plugin exposes logs_list, logs_read, logs_raw, and logs_reset_cursor; it does not read logs until a source is configured.
dsh-loglens is a small DeepSeek Harness plugin for bounded, repeatable log inspection. It exposes four model-facing tools:
logs_list — configured sources and cursor status.logs_read — parse a bounded window, normalize severity, group repeats, fingerprint issues, and return a compact snapshot.logs_raw — retrieve cached original events only after an explicit event id or fingerprint lookup.logs_reset_cursor — restart incremental reading for one source.
The implementation supports file sources and configured shell commands. File reads use byte offsets and inode checks; command output is capped in memory. The model receives a source id, never an arbitrary command or path. State is stored atomically under .dsh/.loglens/state.json by default and contains only bounded cached events.
Local setup
cp .dsh/logs.yml.example .dsh/logs.yml
corepack pnpm install
corepack pnpm test
corepack pnpm run build
The Host bundle has no additional runtime dependency. The browser bundle declares React as a peer dependency and is emitted in the Harness window.__ModuleLoader__ format. Node 22 can run the TypeScript tests directly with --experimental-strip-types.
To install this checkout into a local Harness profile:
dsh plugin --profile headless add /absolute/path/to/dsh-loglens
dsh --profile headless --help
The package's dsh.bundle.patch adds the Host plugin entry. Its dsh.client metadata is discovered by the Web client-module roster; the browser entry is intentionally not mounted in headless/TUI Host profiles.
This workspace keeps the local Harness checkout and its test profiles beside the plugin:
./vendor/deepseek-harness — official Harness source checkout and build../runtime/dsh-loglens-home/profiles/headless — isolated headless profile../runtime/dsh-loglens-home/profiles/web — isolated Web profile.
The root-level package.json, pnpm-lock.yaml, tsconfig*.json, tsdown.config.ts, and cordis.patch.yml are package/build entry files required by pnpm, TypeScript, tsdown, and Harness. They are intentionally kept at the project root; generated dependencies remain in node_modules/ and the Harness checkout's own node_modules/.
To run the checked-in local Harness directly:
DSH_HOME="$PWD/runtime/dsh-loglens-home" \
node "$PWD/vendor/deepseek-harness/apps/cli/lib/bin.js" \
--profile headless --help
Harness host integration
The host entry point is src/plugin.ts (also exported as the package default). It loads .dsh/logs.yml, constructs the service, registers the four tools through ctx.tools.register, and appends a compact loglens/snapshot session event after logs_read. The event is durable when the host's normal session persistence is enabled.
The plugin uses the official tools context shape: each definition has name, description, parameters, output.schema, output.render, and execute(args, exec). In a host package that has typed session events, add the event to the host's SessionEventMap using the event data shape from src/client.ts:
"loglens/snapshot": {
viewId: string;
snapshot: LogLensCardSnapshot;
}
The official Web Client entry point is src/client.ts. It registers a loglens conversation node and a keyed conversation.chat.node renderer. It uses React's createElement by default and accepts an optional compatible factory for tests. It shows stats, grouped issues, recent events, and expandable stack frames; raw content stays behind logs_raw.
Configuration
.dsh/logs.yml uses a deliberately small YAML subset: mappings, scalar strings/numbers/booleans, and comments. Lists are rejected so configuration remains predictable. Relative file paths resolve from the project root. See .dsh/logs.yml.example.
Fingerprinting replaces volatile timestamps, UUIDs, ids, temporary paths, and long numeric values. Exception fingerprints include the exception type/message and the first meaningful stack frames. It is intentionally conservative: application-specific fields can remain in the message and should be reviewed before enabling this on sensitive logs.
Security and limits
Only source ids are exposed to model tool arguments. Commands are administrator-authored configuration and run with the Harness process environment. Output, recent events, raw cache, group count, and returned raw events are all bounded. Do not put secrets in command-line arguments or commit .dsh/logs.yml if it contains private paths or credentials.
Official Harness conventions used
The adapter follows the public Harness package conventions documented in development, architecture, the tool API README, and the conversation node cookbook.
