Metadata-Version: 2.4
Name: hermes-navigator
Version: 0.9.0
Summary: Domain/workspace context management — Hermes Navigator v1
License: MIT
Keywords: context,domain,hermes,miadi,navigator,tmux,workspace
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: controller
Requires-Dist: libtmux>=0.28; extra == 'controller'
Provides-Extra: daemon
Requires-Dist: watchdog>=4.0; extra == 'daemon'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: studio
Requires-Dist: textual>=0.50; extra == 'studio'
Provides-Extra: telegram
Requires-Dist: httpx>=0.27; extra == 'telegram'
Requires-Dist: python-telegram-bot>=21.0; extra == 'telegram'
Description-Content-Type: text/markdown

# Hermes Navigator — Multiverse Context Management
<!-- Ref: jgwill/Miadi#265 -->

## MIGRATION plan

* Migrate as submodule and repo 'git@github.com:jgwill/hnavig.git'
* Change the pypi.org name from 'hermes-navigator' to 'hnavig' for a relation to CLI name and repo name.
* deprecate the old 'hermes-navigator' package on pypi.org after migration and update the README to point to the new package repo before deprecation (require publishing a new package right away on "hermes-navigator" with a deprecation warning and link to the new repo.


## description
Hermes Navigator (`hnavig`) is the v1 implementation of the Hermes Navigator multiverse context management system. It gives William (and any local Hermes-class agent) instant orientation across 3 active development universes and ~120 terminals.

## What It Does

- **R1 — Universe Detection:** Auto-detects which universe each terminal/tmux pane belongs to, using a priority chain of signals (env var → tmux name → git remote → path prefix → heuristic)
- **R4 — Terminal Focus:** Lists or switches tmux focus to a universe's terminal group
- **R2 — Context Engine:** Always-on background collector that builds a queryable snapshot of all terminal activity, scoped by universe
- **R5 — Approval Queue:** Proposed terminal actions flow through a review queue before execution
- **R7 — Session Store:** Named persistent sessions resumable from desktop or Telegram (`/resume <name>`)
- **R8 — Skill Interface:** Packaged as a Hermes skill, callable from any Hermes-class agent

**Issue:** [jgwill/Miadi#265](https://github.com/jgwill/Miadi/issues/265)

---

## Quick Start

```bash
# Install
cd runtime/hermes-navigator
pip install -e .

# Configure universes
mkdir -p ~/.hermes
cp examples/universes.yml ~/.hermes/universes.yml
# Edit ~/.hermes/universes.yml to match your universe roots

# Detect universe for current directory
hnavig detect

# Detect for a specific path
hnavig detect --cwd ~/src/Miadi

# List terminals for a universe
hnavig focus miadi

# Show context snapshot
hnavig context

# Start background daemon
hnavig daemon

# Install/start as a user service
hnavig service install --interval 15 --now

# Release/install smoke gate
hnavig doctor --release-target 0.7.0

# Operator cockpit: know/enter existing tmux work
hnavig operator terminals
hnavig operator peek 7 --lines 80
hnavig operator attach 7
hnavig operator registry save
hnavig operator registry last-known
hnavig operator registry drift
hnavig operator checkpoint
hnavig operator checkpoint --write
hnavig operator steer-proposal 7 --message "continue from the visible prompt"
hnavig session new ava-260512 --cwd /usr/local/src/ironsilk
hnavig session attach ava-260512
```

## Fast Demo Path For This Branch

Want to try the workspace/context slice without touching your real
`~/.hermes` state?

```bash
cd runtime/hermes-navigator
pip install -e .
./examples/demo-miadi-workspace.sh /usr/local/src/mightyeagle
```

What this does:
- sets `HNAVIG_HOME` to an isolated temp directory
- writes a one-universe config pointed at the repo you pass in
- captures a persisted context snapshot when the demo scene is frozen
- runs `detect`, `ecf observe`, `scene activate`, `scene list`, `scene snapshot`, and `scene resume`
- leaves the generated SQLite/files behind so you can inspect them after the run

You can also point the runtime at any alternate state directory yourself:

```bash
export HNAVIG_HOME=/tmp/hnavig-demo
hnavig detect --cwd /usr/local/src/mightyeagle
```

---

## Configuration

### `~/.hermes/universes.yml` — Universe Registry

```yaml
universes:
  - name: miadi
    aliases: [main, mia]
    roots:
      - ~/src/Miadi
      - ~/work/Miadi
    remotes:
      - "github.com/jgwill/Miadi"
    env_var: "MIADI_UNIVERSE"
    tmux_pattern: "miadi-*"

  - name: aureon
    aliases: [aur]
    roots:
      - ~/src/aureon
    remotes:
      - "github.com/jgwill/aureon"
    tmux_pattern: "aureon-*"
```

See `examples/universes.yml` for a full example.

### `~/.hermes/config.yml` — Navigator Config

```yaml
mode: observer           # observer | controller
daemon_interval: 5.0     # seconds between context polls
session_db: ~/.hermes/sessions.db
context_log: ~/.hermes/context/log.ndjson
universes_config: ~/.hermes/universes.yml
```

See `examples/config.yml` for full options.

---

## Commands

### Detection

```bash
# Detect universe for current directory
hnavig detect

# Detect for specific cwd
hnavig detect --cwd ~/src/Miadi

# Detect for specific tmux pane
hnavig detect --pane %42

# Detect all panes in current tmux session
hnavig detect --all-panes
```

### Focus (R4)

```bash
# List terminals for a universe (observer mode)
hnavig focus miadi

# List matching desktop terminal windows (Terminator/Konsole/etc.)
hnavig focus miadi --desktop
hnavig focus miadi --desktop --format json

# Activate a matching desktop window (controller mode + approval required)
hnavig mode controller
hnavig focus miadi --desktop --activate
hnavig focus miadi --desktop --activate --window-id 0x00eaf0d8

# Activate tmux focus to universe pane group (controller mode required)
hnavig mode controller
hnavig focus miadi
```

### Operator Cockpit

These commands are the first "avoid context rot" surface. They are deliberately
small: list the live tmux targets, inspect recent scrollback without attaching,
and print the exact attach/switch commands before changing focus.

```bash
# List existing tmux sessions/panes and their attach commands
hnavig operator terminals
hnavig operator terminals --format json

# Inspect what is happening in a session or pane without attaching
hnavig operator peek 7 --lines 80
hnavig operator peek %7 --format json

# Print the commands for entering a target
hnavig operator attach 7

# Execute attach/switch from an interactive controller terminal
hnavig mode controller
hnavig operator attach 7 --run

# Persist terminal awareness as append-only JSONL
hnavig operator registry save
hnavig operator registry last-known
hnavig operator registry drift

# One read-only "know before entering" checkpoint
hnavig operator checkpoint
hnavig operator checkpoint --target 7 --peek-lines 20
hnavig operator checkpoint --format json
hnavig operator checkpoint --write
hnavig operator checkpoint --target 7 --peek-lines 20 --write

# Human-reviewable follow-up proposal; no send is performed
hnavig operator steer-proposal 7 --message "continue from the visible prompt"
hnavig operator steer-proposal 7 --message-file prompt.md --write
hnavig operator steer-proposal 7 --message "continue" --peek-lines 40
hnavig operator steer-proposal 7 --message "continue" --format json
```

The registry is a read-only awareness surface after capture: `save` appends a
timestamped snapshot under the Navigator state directory, `last-known` reads the
newest persisted snapshot, and `drift` compares current tmux state with that
snapshot. It stores observed tmux fields separately from inferred Navigator
fields such as universe and attach commands.

`operator checkpoint` combines current terminals, the last-known registry
metadata, drift summary, stale/last-seen hints, and safe entry commands. It does
not capture scrollback unless `--target` is provided.

Add `--write` to save a portable Markdown and JSON handoff under
`HNAVIG_HOME/operator/checkpoints/`. This serializes the same checkpoint report;
it does not attach, resume, or mutate terminals.

`operator steer-proposal` creates a reviewed-message artifact for a specific
target. It prints manual `tmux send-keys` suggestions only; Navigator does not
send input, attach, resume, or require controller mode.

### Context (R2)

```bash
# Show full context snapshot
hnavig context

# Filter by universe
hnavig context --universe miadi

# JSON output
hnavig context --format json

# Context from last 30 minutes
hnavig context --since 30m
```

### Sessions (R7)

```bash
# Tmux-style named session plan (dry-run by default)
hnavig session new ava-260512 --cwd /usr/local/src/ironsilk
hnavig session attach ava-260512

# Execute from a local human-controlled terminal
hnavig mode controller
hnavig session new ava-260512 --cwd /usr/local/src/ironsilk --run
hnavig session attach ava-260512 --run

# Create a named session
hnavig session create aureon-refactor-2025

# Resume a session
hnavig session resume aureon-refactor-2025

# List all sessions
hnavig session list

# Archive a session
hnavig session archive aureon-refactor-2025
```

`session new` and `session attach` are tmux-backed verbs for the v0.7.0
Hermes-Agent CLI base. They print exact tmux commands by default; execution
requires `ACTIVE_CONTROLLER` mode and an interactive local terminal.

### Doctor / Release Gate

```bash
hnavig doctor
hnavig doctor --release-target 0.7.0 --strict
hnavig doctor --release-target 0.7.0 --require-daemon --strict
```

`doctor` checks package version, state/config shape, tmux availability, daemon
ping/context readiness, user service hints, and the operator/session CLI
surfaces needed before workspace registry work.

### Mode

```bash
# Check current mode
hnavig mode

# Switch to active controller (enables tmux actions)
hnavig mode controller

# Switch back to observer (safe default)
hnavig mode observer
```

### Daemon

```bash
# Start daemon (blocks; use & or a process manager)
hnavig daemon

# Start with custom poll interval
hnavig daemon --interval 10

# Scene launch opens a terminal/editor for a stored workspace. On systems with
# Terminator installed, Navigator prefers Terminator for new terminal windows.
hnavig scene activate /path/to/project --launch

# Daemon writes to:
#   ~/.hermes/context/latest.json    (last snapshot)
#   ~/.hermes/context/log.ndjson     (rolling log)
#   ~/.hermes/daemon.pid             (PID file)
```

### User Service

Hermes Navigator should run as a **user service**, not a root/system service.
It observes your user terminals, desktop windows, tmux panes, and user-owned
state. The service writes a systemd user unit at
`~/.config/systemd/user/hermes-navigator.service`.

```bash
# Install and start immediately
hnavig service install --interval 15 --now

# If you want an explicit isolated runtime state:
hnavig service install --interval 15 --state-home ~/.local/state/hermes-navigator --now

# Control it later
hnavig service status
hnavig service restart
hnavig service stop
hnavig service uninstall
```

If `~/.hermes` exists but is not accessible to your current user, Navigator
falls back to `~/.local/state/hermes-navigator`. If `systemctl --user` is
unavailable, keep using `hnavig daemon` in a terminal or a local process manager
until the desktop session imports user services.

### Desktop App / Overlay

There is not yet a real floating Hermes window. The current working surfaces
are:

- `hnavig context` — current daemon snapshot, including desktop windows
- `hnavig focus <universe> --desktop` — matching terminal windows
- `hnavig session ...` — named session continuity
- `app/docs/miadi-agent/navigator` — an interactive docs/mock UI that shows the
  intended overlay, approval queue, sessions, and Telegram continuity story

The desktop overlay is specified in
`rispecs/hermes-navigator/05-ui-surface.spec.md`, but implementation remains the
next product step.

---

## Architecture Overview

```
universes.yml ──► UniverseDetector ──► ContextEngine ──► Daemon
                                              │
                                     ┌────────┼─────────┐
                                     │        │         │
                                 SessionStore  ApprovalQ  Focus
                                     │
                                    CLI (hnavig)
```

**Data flow (Phase 1):**
1. `UniverseDetector` reads `universes.yml` and detects universe identity for tmux panes
2. `ContextEngine` polls tmux and desktop windows every N seconds and builds `ContextSnapshot`
3. `Daemon` runs `ContextEngine.start_continuous()` and writes to `~/.hermes/`
4. CLI commands query the daemon or directly invoke detection/focus

---

## Integration with Hermes Skill Ecosystem

The navigator is packaged as a Hermes skill at `skills/navigator.skill.yml`. Any Hermes-class agent can load this manifest and call:

- `navigator.focus(universe)` — list or activate universe terminal group
- `navigator.context(universe?, format?)` — get context snapshot
- `navigator.propose(action)` — queue a terminal action for approval
- `navigator.session.resume(name)` — rehydrate a named session
- `navigator.session.list()` — list all sessions

See `rispecs/hermes-navigator/04-skill-contract.spec.md` for full action definitions.

---

## Development

```bash
# Install in development mode
pip install -e ".[dev]"

# Run directly
python -m hermes_navigator.cli --help
```

### Project Structure

```
runtime/hermes-navigator/
├── hermes_navigator/
│   ├── __init__.py         # package init
│   ├── models.py           # data models
│   ├── config.py           # config management
│   ├── universe_detector.py  # R1 — universe detection
│   ├── context_engine.py   # R2 — always-on context
│   ├── session_store.py    # R7 — named sessions (SQLite)
│   ├── focus.py            # R4 — terminal focus
│   ├── approval_queue.py   # R5 — action approval
│   ├── daemon.py           # background daemon
│   └── cli.py              # hnavig CLI
├── skills/
│   └── navigator.skill.yml  # Hermes skill manifest
├── examples/
│   ├── universes.yml        # example universe config
│   └── config.yml           # example navigator config
├── pyproject.toml
└── README.md
```

---

## Specs

- Master: `rispecs/hermes-navigator/00-hermes-navigator-master.spec.md`
- Universe Detection: `rispecs/hermes-navigator/01-universe-detection.spec.md`
- Context Engine: `rispecs/hermes-navigator/02-context-engine.spec.md`
- Session Store: `rispecs/hermes-navigator/03-session-store.spec.md`
- Skill Contract: `rispecs/hermes-navigator/04-skill-contract.spec.md`
- UI Surface: `rispecs/hermes-navigator/05-ui-surface.spec.md`
- Daemon Lifecycle: `rispecs/hermes-navigator/06-daemon-lifecycle.spec.md`
- Mode And Safety: `rispecs/hermes-navigator/07-mode-and-safety.spec.md`
- Threat Model: `rispecs/hermes-navigator/08-threat-model.spec.md`
- Telegram Bridge: `rispecs/hermes-navigator/09-telegram-bridge.spec.md`
- Universe Relational Graph: `rispecs/hermes-navigator/10-universe-relational-graph.spec.md`
- Status: `rispecs/hermes-navigator/STATUS.md`
