# dsh-resource-guard

> **Language:** [English](README.md) · [Česky](README.cs.md)

DeepSeek Harness plugin that intelligently guards local-model memory. It acts as
a semaphore + memory budget so image generation, voice synthesis and local LLM
tasks can never exhaust RAM on the same machine — for example, it refuses a new
local image job while a local LLM is already loaded.

## Features

- **`resourceGuard` service** — other plugins call `ctx.get("resourceGuard")` to
  `acquire()`/`release()` reservations before starting a local model.
- **`dsh_resource` tool** — model-callable: `status`, `models`, `reserve`, `release`.
- **Settings section** — configure the policy and memory budget from the Harness
  settings UI, with a live RAM/reservation overview.
- **Three policies** — `auto` (one local model within budget), `strict` (one at a
  time), `off` (no guarding).

## Install

```sh
dsh plugin --profile web add dsh-resource-guard
```

Then add `dsh-resource-guard` to `dsh.profile.bundles` and `dependencies` in
`~/.dsh/profiles/web/package.json`, and run `dsh plugin --profile web install`.

## Usage

Ask the agent:

- `dsh_resource action=status` — RAM, reservations, running Ollama models.
- `dsh_resource action=models` — list local Ollama models with sizes.
- `dsh_resource action=reserve label="image job" estGb=6` — reserve memory.
- `dsh_resource action=release reservationId=rsv-1` — free a reservation.

## Settings

| Field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `policy` | `auto`\|`strict`\|`off` | `auto` | Reservation policy. |
| `memoryBudgetGb` | number | `0` | Memory budget; `0` = 85% of total RAM. |

Settings are stored in the `resource-guard` namespace of the Harness settings
document (`~/.dsh/settings.yaml`).

## Architecture

- **Host** (`lib/index.js`) — provides the `resourceGuard` service, registers the
  `dsh_resource` tool, publishes a status snapshot into the read-only
  `resource-guard-status` namespace.
- **Client** (`lib/client.js`) — a `settings.section` slot showing policy/budget
  controls and the live status.

## License

MIT