Metadata-Version: 2.4
Name: hugpy-harness
Version: 0.1.6
Summary: Optional standalone terminal chat and agent harness for a Hugpy wrapper or fleet
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: hugpy-tools>=0.2.7

# Hugpy Harness

Connect to either a standalone wrapper or a basic Core fleet endpoint with
`hugpy-harness --base http://host:port`. The harness displays fleet resource
snapshots per worker, including stale/offline state. Conversations remain in the
same local workspace journal when changing endpoints.

Optional standalone terminal interface for a local or remote Hugpy wrapper.
No dependency on hugpy-agent or the hugpy-wrapper Python package. Communication
uses HTTP; no background service, engine installation or worker enrollment.

## Install

Build with `bash packaging/debian/build.sh`. The output directory contains the
harness `.deb`, a separate wrapper `.deb` when its local build is available,
and `install.sh`. Distribute these together for installation without an APT
repository (system Python packages must still be available).

```sh
cd build/debian
./install.sh                         # missing local wrapper: prompt [Y/n]
./install.sh --yes                   # default yes without prompts
./install.sh --without-wrapper       # harness only, e.g. remote wrapper
./install.sh --dry-run               # show APT plan without changing packages
```

A compatible installed wrapper is reused. The installer checks all required
local package files before calling APT. Noninteractive default is yes; use
`--without-wrapper` explicitly for a remote-only client.

The `.deb` declares the wrapper as `Recommends`, so standard APT installations
include it by default when a repository provides it. It is optional, not a
hard dependency. For the current local release use `install.sh`, which passes
the separate wrapper package to APT when needed. Alternatively:

```sh
sudo apt install ./hugpy-wrapper_0.1.62_all.deb ./hugpy-harness_0.1.1_all.deb
sudo apt install --no-install-recommends ./hugpy-harness_0.1.1_all.deb
```

The harness runtime is `/opt/hugpy-harness/venv`; the wrapper retains its own
runtime and service. Neither package embeds the other. Installing the wrapper
alone does not install the harness.

## Launch

```sh
hugpy-harness
hugpy-harness launch --workspace /path/to/project
hugpy-harness --base http://HOST:PORT --workspace /path/to/project
hugpy-harness chat --model MODEL_ID
```

A local endpoint is discovered from the wrapper endpoint file. Remote access
uses `--base` and `HUGPY_WRAPPER_API_KEY` when authentication is required.
`hugpy-chat` is an alias for the plain chat interface. `/model` opens the model
picker; `/resources` toggles telemetry and `/resources full` opens the monitor.

Existing sessions remain in each workspace's `.hugpy_wrapper/chat` directory
for compatibility. Reopen using the same `--workspace` and `/session`.
Removal (`sudo apt remove hugpy-harness`) leaves chat history, the wrapper,
models, and original Hugpy Agent untouched. Purge removes only this package's
runtime, not workspace data. The wrapper never installs this optional package.

Chat accepts plain replies; tools are optional when the request needs them.
Each user message has its own bounded agent loop. Empty answers and engine
errors are reported without demanding a tool call.

## Model tools

The harness imports the standalone `hugpy_tools` catalog. Core file, search,
text, data, hash, time, and web tools are available automatically in both the
full-screen interface and plain chat. Schemas reach models through prompted
tool instructions or native function calling, and results feed back into the
conversation through the existing journaled loop.

Existing `fs_read`, `fs_write`, `fs_glob`, and `shell` calls remain supported.
The harness keeps its workspace-relative `fs_glob(pattern)` contract when the
portable catalog contains the same name. File arguments are resolved inside
`--workspace`; writes, network requests, and host operations use `--policy`
(`ask` by default). Tools execute on the harness machine, even when the model
runs on a remote wrapper or fleet.

```sh
hugpy-harness --workspace /path/to/project
hugpy-harness chat --workspace /path/to/project --policy readonly
# Add optional document, media, rendering, image, desktop, and VM tools:
hugpy-harness --workspace /path/to/project --optional-tools
hugpy-harness chat --workspace /path/to/project --optional-tools
```

Optional tools load their backends only when called. Install the relevant
`hugpy-tools` extras in the harness environment, for example
`pip install 'hugpy-tools[images,files,render]'`; rendering also needs Playwright
Chromium, and desktop/VM tools need the corresponding host software. Missing
backends return a tool error to the model. Generated image and screenshot
outputs default to `.hugpy_wrapper/tool-artifacts` inside the workspace.

Python installations require `hugpy-tools>=0.2.7`. The Debian build bundles
the core tools wheel alongside the harness wheel and installs both offline.
Neither mode requires a Toolserver service. Optional backend dependencies are
not bundled. To install the unreleased workspace versions together:

```sh
pip install ../hugpy_tools .
```

## 0.1.5 (2026-10-14)

- Every picker searches as you type (`/model`, sessions, loci): each typed word must appear in the
  label, so `qwen 0.6` narrows to the Qwen 0.6B entries. Backspace edits, Esc clears, then leaves.
- `/resources full` is the hugpy UI's compute panel in the terminal: every occupant is a row with its
  state, its share of the card as a bar, VRAM / RAM, ctx and threads; ↑↓ selects an occupant and `e`
  (or Delete) evicts it through the wrapper's operator action — the same eviction the UI's panel does.
  PgUp / PgDn scroll; Esc returns.
- A local model's reply is no longer shown twice (first as a JSON list, then joined): the wrapper
  client drops the loop's duplicate `assistant` event and unwraps one-value payloads.
