dsh-pin-session

Readme

# dsh-pin-session

[![DSH plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)

A client-side [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web plugin for keeping important sessions visible:

- **Pin session** puts a session in a dedicated **Pinned** group at the top of the sidebar.
- **Mark unread** restores the native green completion dot, even after the session has already been opened.
- **Mark read** removes the plugin-owned unread marker.
- State is persisted in the browser's profile-local storage and is independent on each machine/browser profile.
- Pin/unread actions are available from the session's existing three-dot menu.

The plugin deliberately does not modify DSH session logs or the host database. It is a reversible browser-side annotation layer: uninstalling it leaves all sessions and their logs untouched.

## Requirements

- DSH Web with the standard `@deepseek-ai/dsh-client-ui-sidebar` and `@deepseek-ai/dsh-client-ui-workspace` packages.
- A recent DSH `0.1.x` Web profile. The plugin targets the public sidebar/workspace slot contracts and checks the runtime shape before mounting.

## Install

Install from npm when published:

```sh
dsh plugin --profile web add dsh-pin-session
```

Install directly from a GitHub repository:

```sh
dsh plugin --profile web add github:RaberShef/dsh-pin-session
```

For local development:

```sh
dsh plugin --profile web add file:/absolute/path/to/dsh-pin-session
```

After installing, restart `dsh web` if the profile does not hot-reload, then refresh the browser page.

## Use

1. Hover a session in the left sidebar and click its three-dot actions button.
2. Choose **Pin session** to move it to **Pinned** at the top.
3. Choose **Mark unread** to restore the green dot. Opening the session does not erase this explicit marker; choose **Mark read** when finished.
4. Use **Unpin session** to return it to the normal DSH session list.

Pinned sessions retain their normal workspace/session list behavior below the Pinned group. In search results the plugin leaves DSH's search ordering untouched; actions remain available when the session is visible in the normal sidebar list.

## Persistence and portability

Annotations are stored under the namespaced key `dsh-pin-session.v1` in `localStorage`. They are portable with the browser profile's local-storage data, but are intentionally not written to the DSH host so that the package remains safe for multi-machine use and does not require a server-side schema.

## Compatibility and fallback behavior

The plugin uses the supported `shell.overlay` slot and the global `useSessions` hook. It observes the stock workspace browser only to add session annotations and menu actions, so DSH continues to own workspace/session controls, search, rename, fork, archive, drag ordering, and directory picker composition. The client is loaded immediately so it can observe native menu openings; it resolves the clicked row from DSH's live session snapshot and retries portal mounting briefly because the stock menu is rendered in a portal. If the expected runtime shape or overlay seat is unavailable, it declines to mount rather than replacing the sidebar with a broken surface.

A DSH release that changes the `shell.overlay` contract or native session-row accessibility markup may require a compatibility update. The plugin's version should be pinned in shared deployments so an app upgrade and plugin upgrade can be tested together.

## Session identification

Stock session rows carry no stable id attribute, so the plugin resolves a clicked row to its runtime session in this order: a cached id from a previous scan, a semantic `data-session-id`-style attribute if DSH ever ships one, and — as the primary reliable path — the exact id read from the row's React fiber (the row is rendered by the session item component whose props carry the session record; the same id DSH itself uses for open/rename/fork/archive). Title matching with workspace-group disambiguation remains only as a last-resort fallback, so sessions with identical or prefix-overlapping titles still resolve correctly. If a row genuinely cannot be mapped to a session, its native menu is left untouched and tracking terminates deterministically — the plugin never annotates the wrong session. One known limitation: DSH's blank "new session" placeholder rows render no three-dot action button at all, so they cannot be pinned or marked unread until they become real sessions.

## Development

```sh
npm install
npm run check
npm pack --dry-run
```

The package commits the generated `lib/` browser and host artifacts so it can be installed without a TypeScript/esbuild toolchain. The build script uses only Node.js and emits a small ModuleLoader client wrapper.

## License

MIT