# DSH Plugin: UI Session Pin

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

> [!IMPORTANT]
> **This plugin does not run on a stock harness.** It injects `sessionPins`, a
> service no released DeepSeek Harness provides, so an unpatched install leaves
> the entry pending forever and the web UI fails to load with
> `Failed to load plugins`.
>
> Applying [`patches/harness-session-pin.patch`](patches/README.md) to a
> `dsh-v0.1.1-rc.2` checkout is a prerequisite, not an optional extra. The pin
> control lives on each sidebar session row and pinning changes session
> ordering; neither is reachable from any extension point the harness exposes
> today. [Why, and when this ends](patches/README.md).

Provides a **global session pinning** feature for the [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness) web interface, pinning important conversations to a dedicated top section of the sidebar for instant access across all workspaces.

## Target Audience and Use Cases

Designed for users managing multiple projects with numerous sessions who want to keep ongoing goals, key references, or daily conversations easily accessible at the top of the sidebar.

## Key Features

- **Cross-Workspace Persistence**: Pinned sessions stay in a dedicated section above all workspace folders, remaining reachable when switching projects.
- **Codex-Style Interaction**: Click "Pin / Unpin" directly from any session menu; newly pinned sessions automatically stay at the top.
- **Archive Lifecycle Integration**: Retains pin status when sessions are archived, automatically restoring pin placement upon unarchiving.
- **Lightweight Local Storage**: Stores only session IDs in `$DSH_HOME/settings.yaml` under `ui-session-pin.pinnedSessionIds`, updated automatically without manual editing.
- **Clean Unload**: Removing the plugin restores every session to its ordinary position without modifying transcript logs or workspace records.

## Installation and Quick Start

Install a reviewed revision into your Web profile. The repository tracks prebuilt `lib/` artifacts, so Git installation requires no local build step:

```sh
dsh plugin --profile web add github:OpenSaozi/dsh-session-pin#<commit-sha>
```

After installation, refresh the page and hover over any conversation in the left sidebar to access the "Pin Session" menu action.

## Compatibility

This plugin requires a DeepSeek Harness version whose `@deepseek-ai/dsh-client-ui-workspace` package exposes the `ctx.sessionPins` provider registry.

## Storage and Privacy

The host settings provider persists only an ordered list of session IDs. The plugin stores no prompt text, model response, credential, workspace path, or provider request.

## Model Experience

### Request Context and Condition

#### What the model sees

Nothing. The only persisted field is `pinnedSessionIds`, and request assembly never reads it; this package adds no prompt, message, tool schema, or provider request field.

#### Token effect

Zero direct tokens.

#### KV Cache effect

None; pin and unpin operations do not issue or alter model requests.

## Known Limitations and Deferred Work

- **Host-owned settings exposure is required** — a deployment that does not expose `ui-session-pin` through its settings API shows no pin controls rather than storing a second browser-local copy.
- **No manual ordering inside the pinned section** — pinning moves a Session to the top; drag ordering remains limited to ordinary Workspace and flat-list rows.