# permission-popup

[中文文档](./README.zh.md)

A community plugin for the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web UI. It surfaces pending permission approvals from current and background sessions as corner cards, so you can allow or reject a request without navigating back to its conversation.

> This is a community project and is not an official DeepSeek plugin.

## Features

- Shows pending approvals from multiple sessions in one corner stack.
- Displays the session title, tool name, justification, and shell command when available.
- Answers with **Allow once** or **Reject** through the existing DSH approval channel.
- Supports `background`, `always`, and `hidden-only` trigger policies.
- Persists corner, stack size, visibility, notification, and title-reminder preferences locally.
- Can send a desktop notification while the browser tab is hidden.
- Adds no prompt text, model request, token usage, or KV-cache content.

## Requirements

- A recent DeepSeek Harness checkout compatible with the `0.1.1-rc.2` client packages.
- The `web` profile and its standard client runtime, locale, and UI layout bundles.
- Node.js `^22.19.0 || >=24.0.0` when running DSH from source.

DeepSeek Harness is currently pre-release. Plugin APIs and compatibility requirements may change before the first tagged release.

## Install from GitHub

Install into the Web profile:

```sh
dsh plugin --profile web add github:wxjgit/permission-popup
```

If you run DSH from a source checkout, use:

```sh
pnpm dsh plugin --profile web add github:wxjgit/permission-popup
```

Restart the Web UI after installation:

```sh
dsh web
```

For a source checkout:

```sh
pnpm dsh web
```

You can verify that the bundle layer is active before booting:

```sh
dsh --profile web --dump-config
```

The output should contain a `dsh-plugin-permission-popup` layer and a `permission-popup` loader entry.

## Update

Re-run the GitHub installation command to fetch the current default branch:

```sh
dsh plugin --profile web add github:wxjgit/permission-popup
```

For a reproducible installation, pin a commit:

```sh
dsh plugin --profile web add github:wxjgit/permission-popup#<commit-sha>
```

Restart `dsh web` after updating.

## Remove

```sh
dsh plugin --profile web remove dsh-plugin-permission-popup
```

## Usage

The plugin activates automatically with the Web profile. When an approval matches the selected trigger policy, a card appears in the configured corner.

- **Allow once** approves only the displayed request.
- **Reject** rejects the displayed request.
- Click the amber strip to open the owning session.
- Use the gear button on the card stack to configure the trigger policy, corner, maximum stack size, desktop notifications, and tab-title reminder.

The default trigger is `background`: a card is shown when the approval belongs to a non-current session or the browser tab is hidden.

### Browser hidden or minimized

The corner card is part of the browser page and cannot appear above a minimized browser window. Enable **Desktop notify while hidden** in the plugin settings and grant the site notification permission to receive an operating-system notification for new approvals. Clicking the notification focuses the browser and opens the relevant session.

Each approval produces at most one arrival notification. Hiding the window repeatedly does not notify again for the same pending request.

## Security and privacy

- The plugin does not bypass DSH permission checks; decisions use the existing `PendingWait` response channel.
- Cards disappear only after the host broadcasts `approval/resolved`.
- Desktop notifications include only the session title and the approval reason or tool name. Full command arguments are intentionally omitted.
- Preferences are stored in browser `localStorage` under `dsh-permission-popup.prefs`.

Review third-party plugin source and pin a trusted commit before using it in a sensitive environment.

## Development

The source of record is developed inside a DeepSeek Harness monorepo checkout at `packages/client/ui-permission-popup`. The standalone GitHub repository commits prebuilt runtime artifacts so GitHub installation does not execute a build script.

From the DSH repository root:

```sh
pnpm exec tsc -b packages/client/ui-permission-popup
pnpm --filter dsh-plugin-permission-popup run bundle
pnpm exec vitest run packages/client/ui-permission-popup/tests/popup.client.spec.tsx
```

Then restart the source Web host:

```sh
pnpm dsh web
```

## Project layout

```text
src/client/index.ts          Browser plugin registration
src/client/model.ts          Approval projection and trigger policy
src/client/ApprovalPopup.tsx React card stack and notifications
src/client/store.ts          Persisted user preferences
cordis.patch.yml             DSH bundle layer
lib/                         Prebuilt install artifacts
tests/                       Unit tests used in the DSH monorepo
```

## License

[MIT](./LICENSE)