better-dsh 0.2.5 → 0.3.0

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/chronos-managed-cron-contract.md

@@ -1,227 +0,0 @@
----
-title: "Chronos Managed-Cron Contract"
-description: "Agent ↔ NAS wire contract for the Chronos cron provider"
----
-
-# Chronos managed-cron — agent ↔ NAS wire contract
-
-**Status:** authoritative wire spec for the Chronos cron provider.
-**Audience:** the NAS-side implementer of the `agent-cron` endpoints
-(`nous-account-service`) and anyone debugging the managed-cron path.
-
-Chronos lets a hosted Hermes gateway **scale to zero** while idle and still
-fire cron jobs. Instead of an in-process 60-second ticker, the agent asks NAS
-to arm exactly **one external one-shot per job at that job's real next-fire
-time**. NAS calls the agent back at fire time over an authenticated webhook;
-the agent runs the job and re-arms the next one-shot. Between fires the agent
-process can be fully stopped — it wakes only on a genuine fire.
-
-The external scheduler NAS uses to implement the one-shots is an **internal NAS
-implementation detail**. The agent never talks to it, never holds its
-credentials, and never names it. The agent only knows the three NAS endpoints
-below.
-
-```
-create/update/pause/resume/remove a cron job (agent side)
-  │
-  ▼
-ChronosCronScheduler.reconcile()        ── agent computes next_run_at
-  │  POST {portal}/api/agent-cron/provision   (auth: agent's Nous access token)
-  ▼
-NAS arms a one-shot for fire_at         ── NAS owns the scheduler + its creds
-  │
-  ⏰ at fire_at
-  ▼
-scheduler → POST {portal}/api/agent-cron/relay   (auth: scheduler signature, NAS-verified)
-  │
-  ▼
-NAS mints a short-lived agent-audience JWT (purpose=cron_fire)
-  │  POST {agent_callback_url}/api/cron/fire        (auth: that JWT)
-  ▼
-agent verifies the NAS JWT → store CAS claim → run_one_job → re-arm next one-shot
-```
-
-## Trust model (read this first)
-
-| Hop | Who calls whom | Auth mechanism | Verified by |
-|---|---|---|---|
-| 1 | agent → NAS (`provision`/`cancel`/`list`) | the agent's existing **Nous Portal access token** (Bearer) — for a hosted agent this is the **bootstrap-session token** NAS planted in `auth.json` (client `hermes-cli-vps`), NOT an `agent:*` client token | NAS (its normal agent-token path) |
-| 2 | scheduler → NAS (`relay`) | the scheduler's request **signature** | NAS (the signature path it already has) |
-| 3 | NAS → agent (`/api/cron/fire`) | a **short-lived NAS-minted JWT** (`aud=agent:{instance_id}`, `purpose=cron_fire`) | agent (PyJWT against NAS JWKS) |
-
-> **Which token, exactly (hop 1).** A hosted agent never holds an `agent:{instance_id}`
-> OAuth client credential — that shape is minted only by the interactive dashboard
-> auth-code grant (a browser user). For all of its own outbound portal calls the
-> agent uses the **bootstrap-session access token** (`resolve_nous_access_token`),
-> minted under the bootstrap-only client `hermes-cli-vps` and seeded into the
-> container on first boot. NAS therefore must resolve the calling agent's instance
-> id from EITHER an `agent:{id}` client (self-hosted/dashboard callers) OR — for the
-> bootstrap token — from `AgentInstance.bootstrapSessionId` matching the token's
-> session id (`sid`), org-scoped. The fire JWT minted at hop 3 still carries
-> `aud=agent:{instance_id}` regardless. (Gating hop 1 on an `agent:*` client alone
-> 403s every real hosted-agent provision — see `src/server/agent-cron/instance-auth.ts`.)
-
-Why NAS-mediated rather than scheduler→agent direct: the scheduler signs with
-**NAS's** keys, which the agent does not (and should not) hold. The agent can
-only verify a **NAS-minted** token — a trust path it already has. This keeps
-all scheduler credentials inside NAS. (Full rationale: the plan's DQ-4.)
-
-No new secret is introduced on the agent: hop 1 reuses the token the agent
-already uses for the portal, and hop 3 reuses the NAS-JWT verification the agent
-already performs.
-
----
-
-## Endpoint 1 — `POST /api/agent-cron/provision`  (agent → NAS)
-
-Arm (or re-arm, idempotently) exactly one one-shot for a job.
-
-- **Auth:** `Authorization: Bearer <agent Nous access token>`. NAS validates via
-  its normal agent-token path and scopes the row to the calling agent/org.
-- **Request body:**
-  ```json
-  {
-    "job_id": "ab12cd34",
-    "fire_at": "2026-06-18T12:34:56+00:00",
-    "agent_callback_url": "https://agent-xyz.fly.dev",
-    "dedup_key": "ab12cd34:2026-06-18T12:34:56+00:00"
-  }
-  ```
-  - `fire_at` — ISO 8601, **agent-computed**. May be sub-minute in the future;
-    NAS must honor second-granularity (the agent owns the time, so there is no
-    1-minute scheduler floor).
-  - `agent_callback_url` — the agent's own publicly-reachable base URL. NAS
-    POSTs `{agent_callback_url}/api/cron/fire` at fire time.
-  - `dedup_key` — `"{job_id}:{fire_at}"`. NAS **upserts by `(agent_id, job_id)`**
-    so re-arming the same fire is idempotent (no duplicate one-shots). A new
-    `fire_at` for the same `job_id` replaces the prior arm.
-- **Action:** arm one one-shot to fire at `fire_at`, destined for the NAS
-  **relay** route (Endpoint 3) — NOT the agent directly, so NAS stays in the
-  loop to mint the agent JWT. Persist `(agent_id, job_id, schedule_id,
-  agent_callback_url)`.
-- **Response:** `200 {"schedule_id": "<opaque>"}`.
-
-## Endpoint 2 — `POST /api/agent-cron/cancel`  (agent → NAS)
-
-- **Auth:** same as Endpoint 1.
-- **Body:** `{"job_id": "ab12cd34"}`.
-- **Action:** cancel the armed one-shot for `(agent_id, job_id)` and delete the
-  row. Idempotent — cancelling an unknown job is a 200 no-op.
-- **Response:** `200 {"ok": true}`.
-
-## Endpoint 3 — `POST /api/agent-cron/relay`  (scheduler → NAS, the fire relay)
-
-- **Auth:** the scheduler's request **signature**, verified by NAS with the
-  signature path it already has. This is the trust boundary for the fire — a
-  forged relay call must be rejected here.
-- **Action:**
-  1. Look up `(agent_id, job_id) → agent_callback_url` from the persisted row.
-  2. Mint a **short-lived** JWT: `aud = "agent:{instance_id}"`,
-     `iss = {portal_url}`, `purpose = "cron_fire"`, small `exp` (≈60–120s),
-     signed with NAS's normal asymmetric signing key (published via JWKS).
-  3. `POST {agent_callback_url}/api/cron/fire` with
-     `Authorization: Bearer <that JWT>` and body `{"job_id": "...", "fire_at": "..."}`.
-  4. Treat a non-2xx agent response as a **retryable** failure (let the
-     scheduler retry the relay). The agent's store CAS de-dupes a double fire,
-     so retries are safe.
-- **Response to the scheduler:** 2xx once the agent POST is accepted (202), so
-  the scheduler does not retry a delivered fire.
-
----
-
-## Inbound `POST /api/cron/fire`  (NAS → agent) — agent side, already implemented
-
-This is the agent endpoint NAS calls in Endpoint 3 step 3. Two hops on hosted
-deployments:
-
-1. **Dashboard app** (`hermes_cli/web_server.py`) — the agent's only public
-   HTTP surface (the Fly proxy exposes exactly one port, the dashboard's). It
-   is in `PUBLIC_API_PATHS` so the dashboard cookie gate lets the bearer-JWT
-   callback through to the verifier. The dashboard verifies the JWT, resolves
-   the job's profile, then **forwards** the fire to hop 2 on loopback with the
-   NAS bearer preserved — it does NOT execute the job itself.
-2. **Gateway `APIServerAdapter`** (`gateway/platforms/api_server.py`, loopback
-   bind, default port 8642) — re-verifies the JWT (defense in depth) and runs
-   the job with the gateway's **live platform adapters**, which is what makes
-   delivery work for relay-fronted logical platforms and E2EE rooms (the
-   standalone send path can serve neither). Self-host API-server deployments
-   that expose the api_server directly hit hop 2 without hop 1.
-
-Gateway unreachable from hop 1 (scale-to-zero wake still booting, restart
-window, api_server disabled) → the dashboard returns **503** and NAS retries
-(non-2xx = retryable, below); the store CAS de-dupes the eventual double fire.
-There is deliberately no in-dashboard execution fallback. The verifier is
-`plugins/cron/chronos/verify.py`.
-
-- **Auth:** `Authorization: Bearer <NAS-minted JWT>`. The agent verifies:
-  - signature against the NAS JWKS (`cron.chronos.nas_jwks_url`),
-  - `aud` == `cron.chronos.expected_audience` (this agent's
-    `agent:{instance_id}`),
-  - `iss` == `cron.chronos.portal_url`,
-  - `exp` / `nbf` (30s leeway),
-  - `purpose == "cron_fire"` — a general agent JWT (no/other purpose) is
-    rejected so it can't be replayed against this endpoint.
-- **Body:** `{"job_id": "ab12cd34", "fire_at": "..."}` (only `job_id` is used).
-- **Behavior:**
-  - invalid/missing/forged/expired/wrong-aud/wrong-purpose token → **401**, no
-    execution.
-  - missing `job_id` → **400**.
-  - valid → **202 `{"status": "accepted", "job_id": "..."}`** immediately, and
-    the job runs in the background. 202-before-run means a long agent turn never
-    trips the relay's HTTP timeout.
-- **At-most-once:** the agent claims the job with a store-level compare-and-set
-  (`claim_job_for_fire`) before running. A relay/scheduler retry that arrives
-  while the first fire is in flight (or after it completed) loses the claim and
-  does not double-run.
-
----
-
-## At-most-once & re-arm semantics
-
-- **Recurring (cron/interval):** on fire, the agent advances `next_run_at`
-  (under its store lock) as part of the claim, runs the job, then re-provisions
-  a one-shot for the new `next_run_at`. A duplicate relay for the old `fire_at`
-  finds the claim taken / time advanced and is dropped.
-- **One-shot (`30m`, `+90s`, etc.):** fires once; `mark_job_run` marks it
-  completed. No re-arm.
-- **`repeat.times = N`:** `mark_job_run` deletes the job at the limit, so
-  `get_job` returns `None` after the final fire → the agent does **not** re-arm
-  → the schedule stops cleanly with no orphaned one-shot.
-- **Multi-replica agents:** the store CAS makes the fire at-most-once across N
-  gateway replicas sharing one `HERMES_HOME` — exactly one replica runs each
-  fire.
-
-## Reconcile (self-healing)
-
-The agent reconciles desired (`jobs.json`) vs armed on:
-- `start()` (gateway boot / wake),
-- every successful job mutation (`on_jobs_changed`),
-- piggybacked after each fire (re-arm).
-
-Reconcile arms missing/changed-time jobs and cancels orphans. A missed
-provision (transient NAS error) self-heals on the next reconcile. There is **no
-periodic wake** of a sleeping agent — that would negate scale-to-zero.
-
-## Config (agent side)
-
-All non-secret (`cron.chronos.*` in `config.yaml`); the agent holds no scheduler
-credentials. For hosted agents NAS sets these at provision time:
-
-| key | meaning |
-|---|---|
-| `cron.provider` | `"chronos"` to activate (empty = built-in ticker) |
-| `cron.chronos.portal_url` | NAS base URL (also the expected JWT `iss`) |
-| `cron.chronos.callback_url` | the agent's own public base URL for NAS→agent fires |
-| `cron.chronos.expected_audience` | this agent's JWT `aud` (`agent:{instance_id}`) |
-| `cron.chronos.nas_jwks_url` | NAS JWKS for verifying the fire JWT |
-
-If `callback_url` / `portal_url` is blank or the agent has no Nous login,
-`is_available()` returns False and the resolver falls back to the built-in
-in-process ticker — cron never loses its trigger.
-
-## Escape hatch (not default)
-
-The inbound `/api/cron/fire` verifier is pluggable (`get_fire_verifier()`). If
-relay volume through NAS ever saturates, a direct scheduler→agent mode with a
-per-job NAS-minted cron-key can replace the NAS-JWT verifier with **no change to
-the webhook handler**. NAS-mediated (this contract) is the default.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/cli-internals.md

@@ -1,85 +0,0 @@
----
-sidebar_position: 15
-title: "CLI Internals"
-description: "How hermes_cli is shaped: slash dispatch, config loaders, the skin engine, the transactional update pipeline, and process-identity rules"
----
-
-# CLI Internals
-
-Companion to `hermes_cli/AGENTS.md` (the rules) — this page holds the longer explanations.
-
-## Update pipeline
-
-The stage-by-stage contract (`plan → snapshot → apply → restart-per-kind → verify → report`) and the
-field failure each stage guards are documented in `hermes_cli/AGENTS.md`; user-facing behaviour
-(receipts, `--plan`, snapshot modes) is in [Updating](../getting-started/updating.md).
-
-The systemd blunt-restart fallback waits for the unit's `TimeoutStopUSec` plus
-`TimeoutStartUSec`, with 15 seconds of client-side slack. It reads the target unit
-in the same manager scope as the restart; both the initial attempt and retry use
-this budget, including the catch-up restart after an interrupted update.
-A start after a graceful drain uses only the start budget plus slack.
-A missing, unparseable, or infinite phase limit falls back to 90 seconds
-for that phase, keeping unattended updates bounded. Timing out the `systemctl`
-client does **not** cancel the manager's transaction. Custom multi-command stop
-chains or `EXTEND_TIMEOUT_USEC` can still outlast this estimate; a real timeout
-remains an incomplete restart, and successful commands still require the existing
-service-health and fleet-version verification. Raw numeric `*USec` values are
-microseconds, while formatted values use systemd's fixed units, including days,
-weeks, months and years. The combined timeout is capped below the native signed
-32-bit millisecond poll limit (with rounding headroom), so exceptionally long
-unit limits cannot overflow subprocess polling. Zero/unknown/infinite phase
-limits use the bounded fallback. This does not change active-turn drain settings.
-
-## Process identity: never infer it from argv substrings
-
-The bug class behind ~10 fleet-update issues (#90778, #87594, #78089, #76129, #91964, ...):
-classifying a process by `"serve" in cmdline` or similar. `kanban --preserve-cache` contains
-"serve"; a flag VALUE can equal a subcommand (`-m dashboard serve`); truncated cmdlines hide the real
-subcommand. Rules:
-
-- Use the canonical matchers: `gateway.status.looks_like_gateway_command_line` (gateway run),
-  `hermes_cli.update_cmd._hermes_holder_subcommand` (top-level subcommand of any Hermes argv). Never
-  hand-roll token scans.
-- Flag sets must be DERIVED from the parser (`_holder_value_flags()` introspects
-  `build_top_level_parser()`), never hand-written lists — they drift.
-- Never blanket-exclude ancestors from process scans: when `/update` runs as the gateway's child, a
-  gateway ancestor must stay visible to the pause machinery (#87594). Exclude interactive ancestry,
-  carve out gateway-shaped ancestors.
-- Match on FULL cmdlines; truncate only at display time (#78089).
-- Before adding any new scan heuristic, read #92091 — the gateway control socket replaces scans as
-  the primary coordination mechanism; scans are the fallback layer for old/crashed processes.
-
-## Skin engine — what skins customize
-
-| Element | Skin key | Used by |
-|---|---|---|
-| Banner panel border / title / section headers / dim / body | `colors.banner_border`, `banner_title`, `banner_accent`, `banner_dim`, `banner_text` | `banner.py` |
-| Response box border | `colors.response_border` | `cli.py` |
-| Spinner faces (waiting / thinking) | `spinner.waiting_faces`, `spinner.thinking_faces` | `display.py` |
-| Spinner verbs / wings (optional) | `spinner.thinking_verbs`, `spinner.wings` | `display.py` |
-| Tool output prefix / per-tool emojis | `tool_prefix`, `tool_emojis` | `display.py` → `get_tool_emoji()` |
-| Agent name / welcome / response label / prompt symbol | `branding.agent_name`, `welcome`, `response_label`, `prompt_symbol` | `banner.py`, `cli.py` |
-
-Built-in skins (`_BUILTIN_SKINS` in `hermes_cli/skin_engine.py`): `default` (classic gold/kawaii),
-`ares` (crimson/bronze with custom spinner wings), `mono` (grayscale), `slate` (cool blue). Add a
-built-in as a dict entry `{"name", "description", "colors", "spinner", "branding", "tool_prefix"}`.
-User skins are `~/.hermes/skins/<name>.yaml` with the same keys, activated with `/skin <name>` or
-`display.skin: <name>`; the full YAML template is in the
-[Skins & Themes](../user-guide/features/skins.md) user guide.
-
-## Profiles: multi-instance support
-
-Hermes supports profiles — fully isolated instances, each with its own `HERMES_HOME` (config, API
-keys, memory, sessions, skills, gateway). For single-profile commands (`hermes -p x <cmd>`),
-`_apply_profile_override()` in `hermes_cli/main.py` sets `HERMES_HOME` before any module imports, so
-every `get_hermes_home()` reference scopes to the active profile. The multiplex gateway and the
-Desktop/dashboard `serve` backend serve several profiles from one process instead: the active
-profile is a contextvar override bound per activity, `os.environ["HERMES_HOME"]` stays the launch
-profile's, and a module-level constant derived from the home freezes to that launch profile (see
-[Gateway Internals § Multiplexed profiles](./gateway-internals.md#multiplexed-profiles)). Profile
-operations are HOME-anchored (`_get_profiles_root()` returns
-`Path.home() / ".hermes" / "profiles"`, not `get_hermes_home() / "profiles"`) so
-`hermes -p coder profile list` sees all profiles regardless of which one is active — intentional.
-Profile-safe coding rules are in the root `AGENTS.md`; multiplex secret-scope rules in
-`gateway/AGENTS.md`.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/codebase-ownership.md

@@ -1,34 +0,0 @@
----
-title: "Codebase Ownership Map"
-description: "Which directories belong to which subsystem, and where the right docs entry point lives for each"
----
-
-# Codebase Ownership Map
-
-Hermes is a large repository, and most contributions touch exactly one subsystem. This page maps each subsystem to its source directories and the documentation entry point you should read before changing it. Use it to find the right starting doc, the right place for a change, and the right test directory (tests mirror source: code in `tools/` is tested in `tests/tools/`, plugins in `tests/plugins/<type>/`, and so on).
-
-| Subsystem | Source directories | Docs entry point |
-|-----------|-------------------|------------------|
-| Agent core (loop, transports, compression) | `agent/`, `run_agent.py` | [Agent Loop](agent-loop.md), [Context Compression & Caching](context-compression-and-caching.md) |
-| Prompt assembly | `agent/prompt_builder.py`, `agent/system_prompt.py` | [Prompt Assembly](prompt-assembly.md) |
-| Model providers & transports | `agent/transports/`, `plugins/model-providers/`, `hermes_cli/models.py` | [Adding Providers](adding-providers.md), [Model Provider Plugins](model-provider-plugin.md), [Provider Runtime](provider-runtime.md) |
-| Built-in tools | `tools/` | [Adding Tools](adding-tools.md), [Tools Runtime](tools-runtime.md) |
-| Messaging gateway | `gateway/`, `plugins/platforms/` | [Gateway Internals](gateway-internals.md), [Adding Platform Adapters](adding-platform-adapters.md) |
-| CLI | `hermes_cli/` | [Extending the CLI](extending-the-cli.md) |
-| Plugins system | `plugins/` | [Build a Hermes Plugin](plugins/index.md) |
-| Skills (bundled & optional) | `skills/`, `optional-skills/` | [Creating Skills](creating-skills.md) |
-| Cron / scheduled jobs | `cron/` | [Cron Internals](cron-internals.md) |
-| Session storage | `hermes_state.py`, `hermes_state_*.py` | [Session Storage](session-storage.md) |
-| Browser stack | `tools/browser_tool.py`, `tools/browser_supervisor.py`, `tools/browser_cdp_tool.py` | [Browser Supervisor](browser-supervisor.md) |
-| Egress firewall | `agent/proxy_sources/iron_proxy.py` | [Egress Internals](egress-internals.md) |
-| ACP (IDE integration) | `acp_adapter/` | [ACP Internals](acp-internals.md) |
-| Desktop app | `apps/desktop/` | [Desktop Plugin SDK](desktop-plugin-sdk.md), [Worktree UI Development](worktree-ui-dev.md) |
-| TUI | `ui-tui/`, `tui_gateway/` | [Worktree UI Development](worktree-ui-dev.md) |
-| Docs site | `website/` | [Contributing](contributing.md) |
-| Tests | `tests/`, `tests-js/` | [Contributing → Before Submitting](contributing.md#before-submitting) |
-
-A few conventions that fall out of this map:
-
-- **Changes should stay inside their subsystem.** A plugin that needs to edit core files is a design smell — widen the generic plugin surface instead (see the contribution rubric in the repository's `AGENTS.md`).
-- **Run the mirror test directory for every source directory you touch.** A change to `plugins/platforms/telegram/` needs `tests/plugins/platforms/` green, not just the test file you happened to think of.
-- **When two subsystems are involved, the narrower one owns the change.** Prefer a fix in an adapter or plugin over a branch in the agent core; the core is a narrow waist, and every addition there is paid for on every API call.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/completion-backlog-delivery.md

@@ -1,52 +0,0 @@
----
-title: Background completion backlogs
-sidebar_label: Completion backlogs
----
-
-# Background completion backlogs
-
-Interactive surfaces coalesce consecutive background-process completions that are
-already ready for one conversation into a single notification turn. This does not
-add a delay or promise to combine jobs that finish at different times. Failures and
-successful outputs remain in the batch; one completion keeps its original text.
-
-Process identity remains available until dispatch. Explicit `process_manage`
-wait/log/kill consumption can therefore suppress a CLI completion even after it
-has left the process registry and entered the input queue. An entirely consumed
-batch starts no turn. Watching output and async-delegation results remain separate
-notifications, in their original order; they are not folded into completion batches.
-
-## Consumers and ownership
-
-- **Classic CLI:** `hermes_cli/cli_process_notifications.py` owns the idle/post-turn
-  drain, compression-aware ownership and final input unwrapping.
-- **TUI and Desktop:** `tui_gateway/session_notifications.py` groups the poller's
-  ready snapshot after checking ownership. Each process still emits its own UI
-  status. Busy sessions requeue structured events, not rendered batch strings.
-- **Post-turn TUI safety net:** `tui_gateway/prompt_turn.py` uses the same routing
-  and rendering path. Desktop and dashboard chat clients share this backend.
-- **Messaging gateway:** `gateway/run_notifications.py` already uses its own
-  route-keyed short-window batching. This interactive-backlog change does not
-  replace that mechanism or alter adapter sends.
-- **Noninteractive/headless consumers:** this change does not create a new
-  autonomous notification loop for an API request, ACP client, or one-shot CLI.
-
-The shared renderer is `tools/process_registry_notifications.py::ProcessNotificationBatch`.
-Neither a batch nor its delivery status is persisted into the system prompt.
-Addressed events still require a provable owner; another live session cannot adopt
-them. Delegation delivery continues through its existing durable claim/complete
-ledger, once per delegation rather than once per process batch.
-
-## Local validation and its limits
-
-`evals/completion_backlog_probe.py REPO OUTPUT.json` starts real local shell children
-in temporary directories, reads their real completion events, and drives the
-production CLI, TUI poller and post-turn notification routes. A loopback HTTP turn
-sink replaces `chat` / `_run_prompt_submit`; it records actual dispatches but does
-**not** exercise model inference, native renderer interaction or a hosted platform.
-Synthetic watch and delegation envelopes are labeled fixtures; delegation claims
-use the real temporary SQLite ledger. The backlog case includes a nonzero exit.
-
-The probe checks a ready backlog, a single exact payload, explicitly consumed
-results, foreign ownership, and watches/delegations interleaved with completions.
-It measures turn admission at the notification boundary, not model token savings.