better-dsh 0.2.4-a → 0.2.4-b

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

@@ -1,122 +0,0 @@
----
-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

@@ -1,307 +0,0 @@
----
-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.