dsh-logger-panel

Readme

# dsh-logger-panel

English | [中文](README.zh.md)

Runtime log panel for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`). It captures the Host's Cordis logger output, streams it live into a **Settings > Logs** page over SSE, and persists the same records to bounded, date-and-size rotating JSONL files under the private `$DSH_HOME/logs/dsh-logger-panel` directory.

The page renders records as plain text. Raw logger arguments, Fiber references, ANSI escapes, and executable markup never cross the browser wire.

## Preview

<img width="2540" height="1360" alt="图片" src="https://github.com/user-attachments/assets/9a450daa-d75e-4c27-b4ff-d80dbee3dad4" />

## Features

- Live view with snapshot + 100 ms batched SSE appends.
- History paging: a **Load older** button reads records back from the rotated JSONL files across rotations and dates, so the browser can go beyond the in-memory window.
- Bottom auto-follow that pauses when you scroll up, with a **Latest** button to resume.
- Bounded memory: the Host retains the latest 2,000 records for a connecting browser.
- JSONL persistence: a new `YYYY-MM-DD-N.jsonl` file opens on Host activation, date change, or the 5 MiB size limit; matching files older than 30 days are removed. The directory is created with mode `0700` and files with `0600`.
- Bounded disk queue (1,000 records). If persistence fails, the panel reports the failure and the live stream keeps working; omitted records are counted.

## Requirements

- DeepSeek Harness with the Web profile (Settings shell from `dsh-client-ui-settings`, the client module system, and `dsh-host-webserver`), release `0.1.0-rc.6` or newer.
- Node `^22.19 || >=24`.

## Install

The package is a [dsh bundle](https://deepseek-harness.github.io/deepseek-harness/develop/basic/publish/). `package.json` points `dsh.bundle` to `cordis.patch.yml`, which activates the Host plugin, and declares `dsh.client` so the Web profile auto-discovers the browser bundle.

From npm:

```sh
dsh plugin --profile demo add dsh-logger-panel
dsh --profile demo
```

From git (the `prepare` script builds `lib/` during installation; authorize the build in the profile's `pnpm-workspace.yaml` first):

```sh
dsh plugin --profile demo add github:LingLambda/dsh-logger-panel#<sha>
```

For local development against a Harness checkout, load the Host source with an overlay:

```sh
pnpm dsh web --patch ./cordis.patch.yml --patch /absolute/path/to/dsh-logger-panel/overlay.yml
```

```yaml
- insert:
    - id: logger-panel
      name: /absolute/path/to/dsh-logger-panel/src/index.ts
```

## Configuration

The plugin row is inserted as `logger-panel`. Override its `config` in your profile patch:

```yaml
- id: logger-panel
  name: dsh-logger-panel
  config:
    root: /var/log/dsh         # default: $DSH_HOME/logs/dsh-logger-panel
    maxRecords: 2000           # records retained for a connecting browser
    maxRecordChars: 20000      # max chars kept from one formatted message
    batchMs: 100               # SSE batch interval
    maxFileBytes: 5242880      # bytes per JSONL file before rotation
    maxAgeDays: 30             # retention; 0 disables deletion
    maxPendingRecords: 1000    # records accepted ahead of disk writes
    historyPageSize: 500       # records returned by one history page
```

## How It Works

The Host registers a Cordis logger exporter. Every message is formatted to bounded plain text and appended to the in-memory history; the same record is queued to the JSONL writer, so all captured levels are persisted with no content filtering. Each browser connection receives a snapshot followed by batched appends, and a `close` drains accepted file writes. Initial directory or file-open failure rejects plugin activation; a later write failure stops persistence, reports it in the panel, and leaves the in-memory/SSE path active.

A `/dsh-logger-panel/logs/history` endpoint pages older records back from the JSONL files in reverse-chronological order. The first request anchors on the browser's earliest live record so the page never re-delivers the current window; later requests continue with an opaque cursor. The browser keeps loaded history separate from the live window: live trimming never removes history, and reconnected snapshots are folded in without duplicates.

## Develop

```sh
corepack yarn install
corepack yarn typecheck
corepack yarn test
corepack yarn build
```

## License

MIT