dsh-loglens

Readme

# dsh-loglens

DeepSeek Harness plugin for bounded, cursor-aware log inspection. See
[TESTING.md](TESTING.md) for the smallest install and usefulness check.

`dsh-loglens` is a `dsh-plugin` for [DeepSeek Harness](https://github.com/deepseek-ai/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:

```bash
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

```sh
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:

```sh
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:

```sh
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`:

```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](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/development.md), [architecture](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md), the [tool API README](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/tools/README.md), and the [conversation node cookbook](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cookbook/adding-a-conversation-node.md).