dsh-session-activity

Readme

# dsh-session-activity

Activity-first session organization for the DeepSeek Harness Web sidebar.

## Features

- Always groups visible Sessions by **Hot**, **Warm**, **Cool**, then **Cold**, using the existing `Last updated` timestamp while idle.
- Keeps every Session with a running AI or uninterrupted running subagent in **Hot**, refreshing its view-local activity timestamp on each periodic evaluation.
- Keeps the existing **Group by → Workspace / In one list** choice as the secondary layout inside every activity group.
- Keeps the existing **Order by → Manual / Last updated** choice inside each attention tier.
- Sorts explicit user interactions first, completed AI replies next, ordinary idle Sessions after them, and AI-running Sessions last.
- Adds a persistent **Focus** button that hides every group except Hot.
- Recalculates activity groups every minute by default while the page remains open.
- Hides empty activity groups and temporarily expands the group containing the current Session.
- Searches all Sessions even while Focus is enabled.
- Preserves Session open, rename, fork, archive, Workspace create, rename, remove, and new-Session actions.

## Install

```bash
dsh plugin --profile web add dsh-session-activity
```

Restart the running `dsh web` process after installation, then refresh the existing page. The plugin shadows the built-in Workspace browser through DSH's supported slot-priority mechanism; uninstalling it reveals the built-in browser again.

## Configuration

Open **Settings → Session Organizer** to edit and save these values. Browser edits are stored in `$DSH_HOME/session-organizer.json`, override the profile defaults, and update the open sidebar immediately.

The defaults are:

```yaml
config:
  hot:
    label: Hot
    within: 3h
    expanded: true
  warm:
    label: Warm
    within: 1d
    expanded: false
  cool:
    label: Cool
    within: 2d
    expanded: false
  cold:
    label: Cold
    expanded: false
  focus:
    defaultEnabled: false
  refreshEvery: 1m
```

You can also configure the existing `dsh-session-activity` plugin row in your profile; do not insert the same plugin id a second time. Values saved from Settings take precedence over that composition config.

Durations accept positive integers followed by `m`, `h`, `d`, or `w`. The thresholds must satisfy `hot.within < warm.within < cool.within`. Cold is always the unbounded final group. `refreshEvery` must be at least `1m`.

Boundary membership uses the older side at equality:

- Hot: age `< hot.within`
- Warm: `hot.within ≤ age < warm.within`
- Cool: `warm.within ≤ age < cool.within`
- Cold: age `≥ cool.within`

Group names, initial expansion, and initial Focus state come from configuration. After a user changes Focus or a group's expansion, the browser persists that choice across reloads. The current Session is shown from a collapsed group without overwriting the saved collapse preference.

## Ordering

The primary ordering inside each activity and Workspace section is:

1. A question, approval, or other explicit interaction is waiting for the user.
2. The AI has finished and the Session is waiting for the user to continue.
3. The Session is otherwise idle.
4. The AI or one of its uninterrupted subagents is working.

`Last updated` sorts newest-first inside one tier. `Manual` preserves the account order inside one tier; the Session action menu provides keyboard-accessible **Move earlier** and **Move later** actions.

## Focus and search

Focus hides Warm, Cool, and Cold, including a selected non-Hot Session's sidebar row. The conversation remains open. Entering a search query temporarily searches all visible, unarchived Sessions; clearing it restores Focus.

## Adding a Workspace

**Add workspace** opens an in-app directory browser backed by DSH's public `browse` capability. Navigate with folder rows, breadcrumbs, or an absolute path; optionally show hidden folders, then choose **Use this folder**. This works in Web deployments that do not provide a native operating-system directory chooser.

## Development

```bash
npm install
npm test
npm run verify:plugin
npm run smoke:install
npm pack --dry-run
```

`npm test` rebuilds `client/client.js` from `src/client/` before running unit and integration tests.

## Known limitations

- DSH owns the durable `Last updated` field and exposes it read-only to client plugins. While work is running, this plugin projects the current evaluation time into its own rows without mutating DSH's Session summary.
- Subagent child Sessions remain outside the top-level list, matching the built-in Workspace browser.

## License

MIT