better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/features/loops.md

@@ -0,0 +1,122 @@
+---
+sidebar_position: 17
+title: "Recurring Loops"
+description: "Re-run a prompt on a recurring interval inside your session — Hermes' take on Claude Code's /loop."
+---
+
+# Recurring Loops (`/loop`)
+
+`/loop` re-runs a prompt (or a slash command) on a recurring cadence **inside your current session**. Each wakeup is a real agent turn: Hermes reads the current state fresh — the latest CI result, the newest queue depth, the file as it is now — does the work, reports back, and goes quiet until the next tick.
+
+It's Hermes' take on **Claude Code's `/loop`** (and its `/proactive` alias, which works here too). Where [`/goal`](./goals.md) is judge-driven — "keep working until this objective is achieved" — `/loop` is timer-driven: "do this again every N minutes (or whenever it makes sense) until something says stop."
+
+## When to use it
+
+- **Polling external state.** "Watch the deploy / the CI run / the queue and tell me when it changes." The canonical use case.
+- **Iterate-until-green.** "Run the tests, fix what fails, repeat until they pass."
+- **Monitoring during a work session.** Keep an eye on error rates or a long job's progress while you do something else in the same conversation.
+- **Periodic housekeeping.** Re-run a lint pass or a status summary every N minutes during a long session.
+
+When the work should run **unattended** — overnight, on a real schedule, surviving restarts of your terminal — use a [cron job](./cron.md) instead. `/loop` lives inside a session; cron lives outside all of them. And when the task is a single objective with a definition of done, [`/goal`](./goals.md) is usually the better fit.
+
+## Quick start
+
+```
+/loop 5m check the deploy status and tell me if it's live yet
+```
+
+What you'll see:
+
+1. **Loop accepted** — `↻ Loop set (every 5m): check the deploy status…`
+2. **First wakeup fires right away** — on the next idle poll (gateway: the next 15s watcher scan), Hermes injects the wakeup and runs a normal turn against current state.
+3. **Repeat** — every 5 minutes after that, until a stop condition fires or you stop it.
+
+Loop a slash command just as easily:
+
+```
+/loop 10m /recap
+```
+
+## The two cadence modes
+
+**Fixed interval — you set the clock.** Give an interval (`30s`, `5m`, `2h`, `1h30m`) and the loop fires on that schedule. Use it when the thing you're watching changes on its own timeline:
+
+```
+/loop 2m poll the build at ci.example.com/job/42 and ping me the moment it finishes
+```
+
+**Self-paced — Hermes sets the clock.** Omit the interval and the loop paces itself: it starts at the floor (1 minute by default), and while the agent's replies stop changing it backs off exponentially — 2m, 4m, 8m, up to the ceiling (15 minutes by default). The moment a reply differs from the last one, cadence snaps back to the floor. Change detection is a local digest comparison (timestamps are ignored), so idle waits cost nothing extra:
+
+```
+/loop keep an eye on the migration and summarize progress
+```
+
+The rule of thumb: **fixed interval when an external clock drives the work; self-paced when the work drives the rhythm.**
+
+## Stop conditions
+
+A loop ends when any of these fires:
+
+| Condition | How |
+|---|---|
+| The agent decides it's done | The wakeup prompt teaches the agent to end its reply with `LOOP_COMPLETE` on its own line when the task is finished or moot. |
+| A run cap | `--times N` — stop after N wakeups. |
+| An evidence-based condition | `--until <condition>` — after each wakeup, the same auxiliary judge that powers `/goal` checks the reply against your condition. If the judge rules the condition unachievable, the loop **pauses** with the reason instead of re-firing until the tick budget (fail-open: a broken judge never wedges the loop). |
+| You | `/loop stop` (or `/loop pause` to keep it around). |
+| The backstop budget | `loops.max_ticks` (default 100) pauses the loop so an unattended session can't burn tokens forever. `0` = unlimited. |
+
+Examples:
+
+```
+/loop 2m poll CI --times 30
+/loop 5m watch the queue --until queue depth reaches zero
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/loop [interval] <prompt> [--times N] [--until <cond>]` | Start (or replace) the loop for this session. The first wakeup fires immediately; later ones follow the cadence. |
+| `/loop` or `/loop status` | Show cadence, ticks fired, and time to the next wakeup. |
+| `/loop pause` | Stop firing without losing the loop. |
+| `/loop resume` | Pick it back up. |
+| `/loop stop` | End the loop. |
+| `/proactive …` | Alias for `/loop` (Claude Code parity). |
+
+Works on the CLI, the TUI (`hermes --tui`), the web dashboard chat, the desktop app, and every gateway platform (Telegram, Discord, Slack, WhatsApp, …). On messaging platforms the gateway fires wakeups even between your messages — the loop belongs to the chat's session, and its results arrive as ordinary replies — also when that session is open in the TUI / Desktop app, which leaves the routed wakeup to the gateway.
+
+## Mixing with `/goal`
+
+Both features inject synthetic turns at idle boundaries, so they follow one rule: **an active goal owns the session.** While a `/goal` is actively driving (judge saying "continue"), loop wakeups defer. The loop resumes using idle time as soon as the goal finishes, pauses, or parks itself on a wait barrier (`/goal wait`, or the judge's automatic WAIT verdict). A parked goal plus a `/loop` is a natural combo: the goal waits on the big async thing while the loop keeps a heartbeat on something else.
+
+A real user message always wins over both — wakeups only fire while the session is idle and nothing of yours is queued.
+
+## Behavior details
+
+- **A wakeup is a normal user-role turn.** No system-prompt mutation, no toolset swap — prompt caching stays intact.
+- **Survives `/resume` and compression.** Loop state persists per session and migrates across context-compression boundaries, same as `/goal`.
+- **One loop per session.** Setting a new `/loop` replaces the old one. Run several loops by running several sessions (or use cron for a fleet of schedules).
+- **Interrupting a wakeup turn (Ctrl+C) pauses the loop** — recoverable with `/loop resume`, so cancel actually means cancel.
+- **Token cost scales with cadence.** Every tick is a full agent turn. Match the interval to how often the state actually changes; prefer self-pacing for idle waits.
+
+## Configuration
+
+```yaml
+# ~/.hermes/config.yaml
+loops:
+  min_interval_seconds: 30       # floor for fixed intervals
+  max_ticks: 100                 # backstop budget (0 = unlimited)
+  self_paced_floor_seconds: 60   # self-paced starting cadence
+  self_paced_ceiling_seconds: 900  # self-paced max backoff
+```
+
+The `--until` judge routes through the `goal_judge` auxiliary task, so `auxiliary.goal_judge.*` routing overrides (provider, model) apply to loop conditions too.
+
+## `/loop` vs `/goal` vs cron
+
+| | `/loop` | `/goal` | cron |
+|---|---|---|---|
+| **Trigger** | Timer (or self-paced) | Judge verdict after each turn | Schedule, outside any session |
+| **Lives in** | Your current session | Your current session | Its own session per run |
+| **Ends when** | Stop condition / caps / you | Goal achieved / budget / you | You remove the job |
+| **Best for** | Polling, monitoring, periodic re-runs | One objective, iterate until done | Unattended, long-horizon schedules |

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/features/lsp.md

@@ -0,0 +1,307 @@
+---
+sidebar_position: 16
+title: "LSP — Semantic Diagnostics"
+description: "Real language servers (pyright, gopls, rust-analyzer, …) wired into the post-write lint check used by write_file and patch."
+---
+
+# Language Server Protocol (LSP)
+
+Hermes runs full language servers — pyright, gopls, rust-analyzer,
+typescript-language-server, clangd, and ~20 more — as background
+subprocesses and feeds their semantic diagnostics into the post-write
+lint check used by `write_file` and `patch`. When the agent edits a
+file, it sees exactly the errors that edit introduced — not just
+syntax errors, but **type errors, undefined names, missing imports,
+and project-wide semantic issues** the language server detects.
+
+This is the same architecture top-tier coding agents use. Hermes
+ships it self-contained: no editor host required, no plugins to
+install, no separate daemon to manage.
+
+## When LSP runs
+
+LSP is gated on **git workspace detection**. When the agent's working
+directory (or the file being edited) is inside a git repository, LSP
+runs against that workspace. When neither is in a git repo, LSP
+stays dormant — useful for messaging gateways where the cwd is the
+user's home directory and there's no project to diagnose.
+
+The check is layered: in-process syntax check first (microseconds),
+then LSP diagnostics second when syntax is clean. A flaky or missing
+language server can never break a write — every LSP failure path
+falls back silently to the syntax-only result.
+
+Concretely, on every successful `write_file` or `patch`:
+
+1. Hermes captures a baseline of current diagnostics for the file.
+2. Performs the write.
+3. Re-queries the language server, filters out diagnostics that were
+   already in the baseline, and surfaces only the new ones.
+
+The agent sees output like:
+
+```
+{
+  "bytes_written": 42,
+  "dirs_created": false,
+  "lint": {"status": "ok", "output": ""},
+  "lsp_diagnostics": "LSP diagnostics introduced by this edit:\n<diagnostics file=\"/path/to/foo.py\">\nERROR [42:5] Cannot find name 'foo' [reportUndefinedVariable] (Pyright)\nERROR [50:1] Argument of type \"str\" is not assignable to \"int\" [reportArgumentType] (Pyright)\n</diagnostics>"
+}
+```
+
+The `lint` field carries the syntax-check result (microsecond
+in-process parse via `ast.parse`, `json.loads`, etc.); the
+`lsp_diagnostics` field carries the semantic diagnostics from the
+real language server. Two channels, independent signals — the
+agent sees a syntax-clean file with semantic problems as
+``lint: ok`` plus a populated ``lsp_diagnostics``.
+
+## Supported languages
+
+| Language | Server | Auto-install |
+|----------|--------|--------------|
+| Python | `pyright-langserver` | npm |
+| TypeScript / JavaScript / JSX / TSX | `typescript-language-server` | npm |
+| Vue | `@vue/language-server` | npm |
+| Svelte | `svelte-language-server` | npm |
+| Astro | `@astrojs/language-server` | npm |
+| Go | `gopls` | `go install` |
+| Rust | `rust-analyzer` | manual (rustup) |
+| C / C++ | `clangd` | manual (LLVM) |
+| Bash / Zsh | `bash-language-server` | npm |
+| YAML | `yaml-language-server` | npm |
+| Lua | `lua-language-server` | manual (GitHub releases) |
+| PHP | `intelephense` | npm |
+| OCaml | `ocaml-lsp` | manual (opam) |
+| Dockerfile | `dockerfile-language-server-nodejs` | npm |
+| Terraform | `terraform-ls` | manual |
+| Dart | `dart language-server` | manual (dart sdk) |
+| Haskell | `haskell-language-server` | manual (ghcup) |
+| Julia | `julia` + LanguageServer.jl | manual |
+| Clojure | `clojure-lsp` | manual |
+| Nix | `nixd` | manual |
+| Zig | `zls` | manual |
+| Gleam | `gleam lsp` | manual (gleam install) |
+| Elixir | `elixir-ls` | manual |
+| Prisma | `prisma language-server` | manual |
+| Kotlin | `kotlin-language-server` | manual |
+| Java | `jdtls` | manual |
+| PowerShell | `PowerShellEditorServices` (`pwsh` host) | manual (release zip) |
+
+For "manual" entries, install the server through whatever toolchain
+manager makes sense for that language (rustup, ghcup, opam, brew,
+…). Hermes auto-detects the binary on PATH or in
+`<HERMES_HOME>/lsp/bin/`.
+
+### PowerShell
+
+PowerShellEditorServices isn't a single binary — it's a PowerShell
+module bundle launched by a `pwsh` (PowerShell 7+) or `powershell`
+host. Setup:
+
+1. Install [PowerShell](https://github.com/PowerShell/PowerShell) so
+   `pwsh` (or Windows `powershell`) is on PATH.
+2. Download the latest release zip from
+   [PowerShellEditorServices releases](https://github.com/PowerShell/PowerShellEditorServices/releases)
+   and extract it.
+3. Point Hermes at the extracted bundle — the directory that contains
+   `PowerShellEditorServices/Start-EditorServices.ps1`. Either:
+   - set `lsp.servers.powershell.command: ["/path/to/bundle"]` in
+     `config.yaml`, or
+   - extract it to `<HERMES_HOME>/lsp/PowerShellEditorServices`, or
+   - export `PSES_BUNDLE_PATH=/path/to/bundle`.
+
+`hermes lsp status` reports `installed` once `pwsh` is found; if the
+bundle is missing you'll see a one-time warning in the logs with the
+download link.
+
+A few servers are installed alongside a peer dependency that npm
+won't auto-pull. The current case is `typescript-language-server`,
+which requires the `typescript` SDK importable from the same
+`node_modules` tree — Hermes installs both packages together when you
+run `hermes lsp install typescript` or auto-install fires on first
+use.
+
+## CLI
+
+```
+hermes lsp status          # service state + per-server install status
+hermes lsp list            # registry, optionally --installed-only
+hermes lsp install <id>    # eagerly install one server
+hermes lsp install-all     # try every server with a known recipe
+hermes lsp restart         # tear down running clients
+hermes lsp which <id>      # print resolved binary path
+```
+
+`hermes lsp status` is the best starting point — it shows which
+languages will get semantic diagnostics today and which need a
+binary installed.
+
+## Configuration
+
+The defaults work for typical setups; nothing to set if the binaries
+are on PATH.
+
+```yaml
+# config.yaml
+lsp:
+  # Master toggle. Disabling skips the entire subsystem — no servers
+  # spawn, no background event loop runs.
+  enabled: true
+
+  # How long to wait for diagnostics after each write.
+  wait_mode: document      # "document" or "full"
+  # Max seconds to wait for the server to re-check the file after an
+  # edit. Only *fresh* diagnostics (produced for the post-edit
+  # content) are ever reported; if the server doesn't finish within
+  # this budget, the edit reports "no LSP data" rather than stale
+  # errors from before the edit. Raise this for slow servers on big
+  # projects (tsserver, rust-analyzer mid-indexing).
+  wait_timeout: 5.0
+
+  # How to handle missing server binaries.
+  #   auto    — install via npm/pip/go install into <HERMES_HOME>/lsp/bin
+  #   manual  — only use binaries already on PATH
+  install_strategy: auto
+
+  # How long an unused language-server client stays alive (seconds).
+  # Idle servers are shut down automatically and respawned on the next
+  # relevant file operation. Set to 0 to disable idle reaping and keep
+  # servers alive for the life of the process. Values below 30s are
+  # clamped to 30 so a sweep can never reap a client mid-operation.
+  idle_timeout: 600
+
+  # Per-server overrides (all optional).
+  servers:
+    pyright:
+      disabled: false
+      command: ["/abs/path/to/pyright-langserver", "--stdio"]
+      env: { PYRIGHT_LOG_LEVEL: "info" }
+      initialization_options:
+        python:
+          analysis:
+            typeCheckingMode: "strict"
+    typescript:
+      disabled: true       # skip TS even when its extensions match
+```
+
+### Per-server keys
+
+* `disabled: true` — skip this server entirely even when its
+  extensions match a file.
+* `command: [bin, ...args]` — pin a custom binary path. Bypasses
+  auto-install.
+* `env: {KEY: value}` — extra env vars passed to the spawned process.
+* `initialization_options: {...}` — merged into the LSP
+  `initializationOptions` payload sent in the `initialize`
+  handshake. Server-specific; consult the language server's docs.
+
+## Installation locations
+
+When `install_strategy: auto`, Hermes installs binaries into
+`<HERMES_HOME>/lsp/bin/`. NPM packages land in
+`<HERMES_HOME>/lsp/node_modules/` with bin symlinks one level up.
+Go binaries come from `go install` with `GOBIN` pointed at the
+staging dir.
+
+Nothing is ever installed to `/usr/local/`, `~/.local/`, or any other
+shared location — the staging dir is fully Hermes-owned and is
+removed when you reset the profile.
+
+## Performance characteristics
+
+LSP servers are **lazy-spawned** on first use. Editing a Python file
+in a project that's never seen `.py` traffic spawns pyright; the
+spawn takes 1-3 seconds for most servers (rust-analyzer can take 10+
+on a cold project). Subsequent edits in the same workspace re-use
+the running server.
+
+The LSP layer adds a few milliseconds to clean writes when no
+diagnostics are emitted. When diagnostics are emitted, the wait
+budget is `wait_timeout` seconds — typically the server responds in
+tens of milliseconds for pyright/tsserver and a few seconds for
+rust-analyzer mid-indexing.
+
+Diagnostics are **freshness-gated**: a result only counts when the
+server produced it for the content of the current edit (a
+`publishDiagnostics` push at/after the change, or a pull request
+answered after it). Slow servers that haven't re-checked yet result
+in "no data" for that edit — never in yesterday's errors being
+re-reported as current.
+
+Servers are kept alive while they're being used and shut down after
+`lsp.idle_timeout` seconds (default 600) with no file activity — a
+long-running gateway that touches many worktrees no longer accumulates
+one language-server process per workspace forever. A reaped server is
+respawned automatically on the next relevant file operation. Set
+`idle_timeout: 0` to disable reaping and hold every server's index warm
+for the life of the process.
+
+Servers that support multi-root workspaces (currently pyright) run as a
+**single process** per Hermes process: the first Python project spawns
+it, and every further project root — for example sibling git worktrees
+edited by parallel subagents — is attached to that same server as an
+additional workspace folder instead of starting another copy.
+
+## Disabling
+
+Set `lsp.enabled: false` in `config.yaml` to disable the entire
+subsystem. The post-write check falls back to the in-process syntax
+check (`ast.parse` for Python, `json.loads` for JSON, etc.) which
+ships unchanged from earlier versions.
+
+To disable a single language without disabling the whole layer:
+
+```yaml
+lsp:
+  servers:
+    rust-analyzer:
+      disabled: true
+```
+
+## Troubleshooting
+
+**`hermes lsp status` shows a server as "missing"**
+
+The binary isn't on PATH and isn't in `<HERMES_HOME>/lsp/bin/`. Run
+`hermes lsp install <server_id>` to attempt an auto-install, or
+install the binary manually through the language's normal toolchain.
+
+**`Backend warnings` section in `hermes lsp status`**
+
+Some servers ship as thin wrappers around an external CLI for actual
+diagnostics — they spawn cleanly and accept requests but never emit
+errors when the sidecar binary is missing. The most common case is
+`bash-language-server`, which delegates diagnostics to `shellcheck`.
+When `hermes lsp status` shows a `Backend warnings` section, install
+the named tool through your OS package manager:
+
+```
+apt install shellcheck      # Debian / Ubuntu
+brew install shellcheck     # macOS
+scoop install shellcheck    # Windows
+```
+
+The same warning is logged once at server spawn time in
+`~/.hermes/logs/agent.log`.
+
+**Server starts but never returns diagnostics**
+
+Check `~/.hermes/logs/agent.log` for `[agent.lsp.client]` entries —
+both stderr from the language server and protocol errors land
+there. Some servers (rust-analyzer especially) need to finish a
+project-wide index before they emit per-file diagnostics; the first
+edit after server start may complete with no diagnostics, with
+subsequent edits picking them up.
+
+**Server crashed**
+
+A crashed server is added to the broken-set and won't be retried for
+the rest of the session. Run `hermes lsp restart` to clear the set;
+the next edit re-spawns.
+
+**Editing a file outside any git repo**
+
+By design, LSP only runs inside a git repository. If the project isn't
+yet initialized, run `git init` to enable LSP diagnostics. Otherwise the
+in-process syntax-only fallback applies.