The M13 fix stopped counting any key a tool panel also asks for, since a
bare PUT /api/env cannot tell connecting a provider from configuring a
tool. Desktop onboarding and model settings now send provider_setup=true
and the server counts those saves; the Keys page and tool panels keep
the exclusion.
Only the Desktop consent RPC purged desktop_onboarding/; opting out with
hermes config set or the setup wizard left the latches until the Desktop
switch was next flipped. An opted-out process start now removes them
with the other pending markers.
model_route('lm-studio', id) kept the user's model id because only the
canonical lmstudio was in user_named_model_providers while the alias
passed provider_metric_name as a shipped name. Bedrock ARNs carry the
AWS account id. Both now read custom.
hermes.execution_backend.count still counted terminal/browser/code calls made
under the background_review write origin (the review and curator forks),
while hermes.terminal.outcome and file_edit already skip them. Owner ruling:
match terminal.outcome. record_execution_backend now returns early when
is_background_review() is set (one contextvar read, before any work).
Doc: the execution_backend row lists the forks as not counted.
Probe probe_internal.py (terminal_tool inside a background-review origin):
before: [execution_backend {backend: local, kind: terminal, outcome: success} x1]
after: []
test_background_review_fork_terminal_calls_are_not_backend_usage is RED on base
(2 rows != 1), green here.
_run_foreground recorded outcome=timeout whenever a backend exception's
text contained "timeout" (an SSH connect timeout, a sandbox API timeout).
That command never reached an exit status, and the doc says timeout comes
only from Hermes' own deadline flag (hermes_timed_out), which
terminal_outcome() already reads. Owner ruling: never from exception text.
The exception path now records nothing; the model-facing result (exit 124)
is unchanged.
Probe (code-read finding; the new test drives the real terminal_tool with a
backend raising "... Connection timeout"):
before: terminal.outcome {backend: local, command_kind: shell_builtin, outcome: timeout} x1
after: no terminal.outcome row; tool result still exit_code 124
test_backend_exception_mentioning_timeout_is_not_a_terminal_timeout is RED on
base, green here.
_cmd_undo counted role=="user" rows of the old history, so a compaction
handoff (role user, not a turn) added a phantom wasted_tokens row with
tokens_bucket=unknown. The TUI and gateway already pass the real
turns_undone. undo_last now returns turns_undone (None when nothing was
rewound) and _cmd_undo records exactly that.
Probe probe_cli_undo.py (history = handoff + 2 real turns, /undo 5):
before: wasted_tokens 10k_to_50k x2 + unknown x1 (3 rows)
after: wasted_tokens 10k_to_50k x2 (2 rows)
Test test_cli_undo_n_counts_the_user_turns_actually_undone_not_compaction_handoffs
is RED on base (3 == 2), green here.
m22: migrations ran save_config -> record_config_saved inside surfaced
processes (`hermes config migrate`, console migrate, dashboard/TUI profile
create), so e.g. v45 appending `connections` to platform_toolsets read as a
user re-enabling a toolset. _persist_migration (the single migration write
path) now wraps save_config in hermes_applied_write(), a ContextVar the hook
honours.
m23: the old side is the raw file (`memory_enabled: ${MEM_ON}`) and the new
side the env-expanded config, so any unrelated save reported `disabled` once a
day forever. A setting whose value on either side is an unexpanded `${...}`
string is now skipped (its value is unknown to the diff).
m24: dashboard handlers call save_config inside config_write_scope
(_CONFIG_MUTATION_LOCK), and the diff (tools_config._get_platform_tools per
platform) + record ran there. record_config_saved now runs only the cheap
gate inline (surface, enabled, surface/home resolution) and hands deep copies
to a non-daemon thread bound to the owning profile (non-daemon so a CLI
command exiting right after its write still records).
Test contract change: test_record_config_saved_needs_a_surface_and_collection
and test_real_config_writes_report_the_move_away_from_default now join the
recording thread before asserting (the record is asynchronous by design).
Probes (review/signals/mine):
p2_migration.py config|dashboard
before: re_enabled toolset connections row; after: <no db>
p4_envref_configset.py
before: memory.memory_enabled disabled after an unrelated save;
after: no row (config set curator.enabled false still records)
p3_lock_v2.py (times config_transitions, try-acquires the web lock)
before (p3_lock.py): record_config_saved 0.047s/0.004s, lock held=True
after: diff 0.003-0.008s, lock held=False
Tests test_migrations_and_env_templates_are_not_user_disables and
test_diff_and_record_run_off_the_callers_lock_in_the_owning_profile are RED on
base.
- `curator` latched on the default-on scheduled pass (outcome=success, all
buckets 0), so it meant "idled through one curator interval". It now needs
trigger=manual (the user ran it).
- `skills_created` and the v4 milestone `first_skill_created` latched when
the background-review fork created a skill (provenance=agent_created).
Both now require provenance != agent_created (foreground creates are
stamped "learn" -> not agent_created, see tools/skill_usage.record_created).
- days_since_install_bucket caught only sqlite3.Error; a non-numeric
sessions.started_at raised ValueError into the subscriber on every event,
re-opened state.db each time and never latched. It now also catches
OSError/TypeError/ValueError -> `unknown`.
Probes:
probe_internal_adoption.py
before: feature_adoption curator + skills_created, milestone first_skill_created
after: no feature_adoption rows, no milestone
probe_statedb_errors.py textstamp
before: ValueError warnings, 0 rows, settled 0 of 1
after: 1 state.db read, feature_adoption {unknown, projects}, settled 1 of 1
Tests test_hermes_internal_work_never_latches_adoption and
test_unreadable_first_session_reads_unknown are RED on base.
tool_unavailable_fields compared against agent.valid_tool_names, the
model-visible array after tool-search assembly. With the default
tools.tool_search.enabled=auto, 14 enabled built-ins (session_search,
todo_list, process_manage, ...) live behind the tool_call bridge, so a direct
call to one was reported as "disabled in this session". Cron agents had
clarify stripped on purpose by the scheduler and still counted.
- Names in the session's tool-search scoped set
(agent.tool_executor._tool_search_scoped_names: the deferrable names its
enabled/disabled toolsets allow, cached on the agent) are enabled, not
unavailable. A session that turned the toolset off still reports it.
- platform == "cron" returns None, like delegated children and background
review.
Probes:
probe_deferred_tools.py (real AIAgent, default config)
before: rows for session_search and todo_list; after: no rows
probe_cron_narrowed.py
before: tool_name=clarify row; after: no rows
Test test_deferred_builtins_and_cron_narrowing_are_not_unavailable is RED on
base.
begin_process's collection-off branch purged only parked update receipts.
A provider_setup marker (pid, start_time, surface, provider) or a process
exit marker written while collection was on stayed on disk through the
opt-out and was reported (`abandoned` / `killed`) once collection came back
on, in a period the user had not consented to.
The same branch now removes process_markers/ and provider_setup_markers/.
Probe p2b_off_then_on.sh:
before: marker survives two OFF starts; the ON start emits
`abandoned openrouter`
after: markers {} after the first OFF start; the ON start emits only its
own started/completed rows
Test test_opted_out_start_purges_markers_left_while_opted_in is RED on base.
Every PUT /api/env write of a provider-shaped variable recorded
started+completed: an empty value (a clear), a same-value re-save,
GITHUB_TOKEN/GH_TOKEN (-> copilot), HF_TOKEN, and keys the TTS/STT/image
panels also save (GEMINI_API_KEY, XAI_API_KEY, DEEPINFRA_API_KEY). TUI
model.save_key counted re-saves; editing a custom endpoint counted as a new
setup.
- record_api_key_saved takes the value and the stored value read before the
save: only a non-empty, changed value counts.
- provider_for_api_key_env returns None for ecosystem tokens (GITHUB_TOKEN,
GH_TOKEN, HF_TOKEN) and any key a TOOL_CATEGORIES panel asks for: a bare
key save cannot tell a provider connection from a tool setting (the PUT
body has no provider flag; adding one is Desktop work, see NOT_COVERED).
Provider pickers (CLI, TUI model.save_key with its explicit slug) still
count those providers.
- model.save_key skips a same-key re-save.
- upsert_custom_endpoint records only when the endpoint did not exist.
Probe p4_web_double.py (real route functions):
before: openrouter started x3/completed x3 (save, re-save, clear),
copilot x1 from GITHUB_TOKEN, custom x3 (create + 2 edits)
after: openrouter x1, no copilot row, custom x1
Tests test_web_forms_count_only_a_new_provider_key_or_endpoint and the
extended test_api_key_env_maps_to_provider_only are RED on base.
cli_provider_setup treated the setup menus' BaseException control flow as
errors: Esc (_SetupCancelled) recorded failed/other, and Back (_SetupGoBack)
recorded failed/other and then a second `started` when the wizard replayed
the provider picker.
- setup_failure_class maps _SetupCancelled to `cancelled`.
- Back leaves the flow open on the thread-local; the replayed picker
re-entering the same surface+provider continues it (no new `started`).
Picking another provider, or leaving the entry point
(provider_setup_surface exit other than a Back), ends it failed/cancelled.
Probe p5_cli_nav.py (real cmd_model):
before: back_then_pick started x2, failed/other x1, completed x1;
escape started x1, failed/other x1
after: back_then_pick started x1, completed x1;
escape started x1, failed/cancelled x1;
back_then_esc_menu started x1, failed/cancelled x1;
back_then_other openrouter started+cancelled, anthropic started+completed
Test test_cli_setup_navigation_esc_cancels_and_back_resumes_one_flow is RED
on base (failed/other, extra started).
m16. shared_metrics.set(enabled=false) purged the renderer's onboarding latch
but left telemetry/shared_metrics/desktop_onboarding/<step>.<event> in the
profile, so a content-free per-profile record outlived the opt-out and the two
sides disagreed on re-opt-in. The Desktop's consent RPC now removes that
directory when it turns collection off (shared_metrics_desktop.
purge_onboarding_latches). Opting out from the CLI (config set / setup wizard)
leaves them until the Desktop's switch is next turned off — see NOT_COVERED.
Test: test_turning_collection_off_drops_the_onboarding_latches — RED on base
(latch file survives), green now.
Probe (review/desktop/probe_optout_set.py):
before: surviving desktop latches: [.../desktop_onboarding, .../intro.reached, ...]
after: surviving desktop latches: [] (only metrics.sqlite3 / outbox remain)
M10 + m17 (+ the backend half of M9). The backend's once-per-day latches for
hermes.desktop.{action_use,mode_use} (the finished-day report) and
hermes.desktop.feature_use lived in process memory, so a second window's report,
a backend restart or a pooled backend re-counted the same day/area. The daily
rows also went through the relay's current-day marks, so a day flushed a week
late was counted in the flush day's period.
- record_desktop_daily now writes through SharedMetricsStore.update_rollup_state:
one write transaction checks a `desktop_daily_reported` state row (the usage
days already reported, bounded to the last 8 days) and records the rows with
period_start = the usage day. Days outside [today-8, today] settle unrecorded.
- record_desktop_feature_use uses store.record_counter_once_per_day (the same
durable per-UTC-day-per-dimension latch feature_disabled uses).
- With collection off, desktop_daily answers recorded:false instead of true, so a
renderer that has not learnt the switch yet never treats that as "settled" and
drops the day (the client's own gate purges it when it reads off).
- Neither metric has feature/milestone side effects in the subscriber, so
writing to the store directly is equivalent apart from the latch and period.
Tests: the fixture mocked record_process_marks_saved; the daily/feature-use
assertions now read the profile's store (their contract changed: rows no longer
go through the relay). The disabled-profile test now expects recorded:false.
The store-refusal test raises from update_rollup_state instead of mocking the
relay's saved count. New invariant test (two windows / a restarted backend, all
in-process state reset between reports): RED on base, green now.
Probe (review/desktop/probe_latch.py, run twice on one home = backend restart):
before: run 2 → action_use composer.send 2, feature_use terminal_pane 2,
mode_use 2, all in period 2026-09-28 for usage day 2026-09-20
after: run 2 → action_use 1, feature_use 1, mode_use 1; action_use/mode_use in
period 2026-09-20. Opted-out home: daily -> {'recorded': False}.
What:
- m1: record_known_cache_break emits only when it is the first announcement for the pending cold
read (the first cause names the break); several causes before one cold read were one row each.
- m5: enabled() while OFF returns before taking the process-wide _RUNTIME_LOCK when no runtime
exists for the profile (nothing to tear down).
Tests: compression x2 + model_switch before one cold read -> one compression row (RED on the
previous commit: compression 2 + model_switch 1). Existing cache_break test unchanged and green.
Measured (uncontended, fakehome): enabled() OFF 17.72 -> 17.24 us/call. The lock was the
cross-thread serialisation point, not the bulk of the cost: _raw_config() is 13.0 us of it (see
NOT_COVERED.md).
What:
- M2: engagement.record reads the clock inside the rollup write transaction, so writers apply in
clock order and no process closes a day another already closed. apply() never moves the stored
day backwards: an interaction that lands behind the stored day folds into it (the only close path
is a later clock), instead of being dropped or re-opening a day.
- m7: SharedMetricsStore counter and rollup writes that hit the 250 ms busy timeout are kept in a
bounded in-memory queue (4096) and land with the next write, the next package export, or an exit
drain (atexit, 5 s busy timeout, registered only after a deferral). The caller still waits at most
250 ms; a non-busy error drops only the failing write.
Why: the Relay subscriber thread saw "database is locked" and lost the row (engagement under
multi-process contention; model-call counters under host load).
Tests (RED on the previous commit): a write while another connection holds BEGIN IMMEDIATE ->
no raise, lands with the next write (value 2); a late interaction folds into the newer day and the
closed day reports once.
Stress: 20 parallel copies of the existing
test_cross_process_model_call_updates_are_transactional under -n 12 (load avg 6-15, a second
-n 12 suite running): fixed store 10 rounds -> 200/200 passed; previous store 3 rounds -> 55/60
(5 failed: child exit 1, database is locked).
What:
- M1: the engagement turn mark (primary model) needs a user turn (pre_llm_call) on an interactive
surface or a gateway message; API-server, python embedding and curator turns no longer create
engagement.day rows or outvote the person's model. close_day emits nothing for a day with no
engaged surface (the root profile's host row with an active-profile count stays).
- M3 (owner ruling): unattended cron runs are dropped from engagement entirely. surface_day always
carries an active-minutes bucket, so it cannot express cron presence without minutes; hermes.cron.run
already counts runs. The `cron` enum value stays in the contract for already-stored rows.
- M7: background review forks (no pre_llm_call) no longer advance model_switch_after's turn run.
- M8: the run observes the route each turn was sent on (its first request), so a provider failover
neither restarts the run nor names the fallback as the model left.
- m6: documented that the root host row (surfaces_used_count 0) is excluded from days-active counts.
Why: Hermes-internal and unattended activity is not user engagement; switch_after measures how long
a person stayed on the model they chose.
Tests (RED on the previous commit): API/cron-only day -> no day row, mixed day -> primary = person's
model; failover + review fork -> switch_after names the selected model with 2_to_3.
Probe (review/engagement/probe_internal.py, switch/probe_switch.py -k "p3c or p7"), before:
API-only / curator-only day -> engagement.day {"primary_model": "openai/gpt-5", "surfaces_used_count": "0"}
cron all day -> day {"active_minutes_bucket": "gte_6h", "active_profile_count_bucket": "1"} + surface_day cron
2 CLI + 5 API turns -> primary openai/gpt-5
P3c (6 turns on A, 7th failed over to B) -> {"model": "gpt-5", "turns_before_switch_bucket": "1"}
P7 review fork -> 4_to_10 (routed=False) / gpt-5-mini "1" (routed=True)
after: the equivalent invariant tests pass (no day row, primary = PUBLIC, selected model 2_to_3).
What: the metrics lineage no longer keys off the ambient Portal conversation id (it walks every
parent_session_id: gateway reset/idle expiry, /new, /branch). Compression calls
relay_shared_metrics.rotate_segment(old, new) from the committed rotation
(_notify_context_engine_compression_complete) and from a stale agent adopting the live tip
(_adopt_live_compression_child). The hand-off registers the new id in the lineage, moves the
route run and the spent-turn history into it, and closes the old segment now (or when its in-flight
compression turn ends). A rotated-to id closed before serving a turn, or still open at shutdown,
closes too; a 512-lineage backstop flushes conversations a surface never closed.
- m2: /undo or /retry on the new id reaches the turns earlier segments spent (tokens_bucket known).
- m11: /model right after a rotation finds the conversation's turn run.
- m8: background review forks (same session id, no pre_llm_call) add no turns/calls/messages.
Why: one conversation = one session / context_peak / tool_overhead / tool_enabled_unused row, on
time; N gateway conversations collapsed into one row emitted only at process exit, and rotated
segments stayed in memory until exit.
Tests: two existing tests simulated rotation by sharing a conversation context; their contract
changes to the explicit hand-off (test_a_compressed_conversation..., test_context_peak_is_one_row...).
New: reset/branch chain after a compression + tip-first close order, the compression seam, switch/undo
right after a rotation, review fork volume. RED on base (rotate_segment missing / switch_after [] /
turn bucket '2' for one user turn).
Probe (review/engagement/lineage probe_lineage.py -k c2, probe_branch.py; fix-lineage/probe_handoff.py):
before: c2 3 conversations -> session.count 0 until shutdown, then 1; branch -> 1; 50 compressed
conversations -> 0 rows, 50 lineages/sessions live.
after: c2 -> 3 rows before shutdown (turns 2,1,1), lineages=0; branch -> 2; 50 compressed -> 50 rows,
0 lineages, no sessions; tip-first close with the old turn running -> 0 then 1; shutdown with an
open tip -> 1 per conversation.
What:
- shared_metrics_catalog.model_metric_name also collapses a model id that is
a network address: a loopback/IPv4 host or localhost at the start, or a
leading host:port with a 2-5 digit port (so Bedrock's "...-v1:0" and
OpenRouter's ":free" / Ollama's ":120b" tags stay readable). The existing
URL/path/weight-file rules move into the same compiled pattern.
- shared_metrics_contract._bounded_dimensions (every mark -> counter
projection) and model_token_counters re-run provider_metric_name /
model_metric_name on the mark's provider/model identifier fields and drop
the row when either would rewrite it ("none" = unset provider passes).
Record-time only: counter_dimensions_are_valid (also used at packaging) is
unchanged, so catalog drift can never raise out of _package_metric and
block a package of rows already stored.
Why: `127.0.0.1:8080/x` on a public provider passed verbatim through every
route metric, and the subscriber validated identifier shape only, so a mark
that skipped the producer's catalog pass stored custom:acme, ollama/<model>,
unknown vendors and even http:// URLs.
Probe (fix-catalog/probe_b1_m12.py):
before: route(openrouter, 127.0.0.1:8080/x) -> model '127.0.0.1:8080/x'
(also localhost/qwen, 10.0.0.5/x, gpu-box.lan:8000/qwen verbatim)
subscriber injected switch_after {127.0.0.1:8080/x, openrouter} -> stored
subscriber injected switch_after {acme-secret, acmecorp-internal} -> stored
after: all of the above -> model 'custom'; both injected marks -> None;
bedrock anthropic.claude-3-5-sonnet-20241022-v2:0, openai/gpt-4o:free,
gpt-oss:120b and the legit anthropic mark unchanged.
Test: test_network_address_model_ids_and_raw_injected_marks_never_reach_counters
(RED with the catalog reverted: model_route kept 127.0.0.1:8080/x; RED with the
contract reverted: the injected host:port mark was stored; GREEN with both).
What: shared_metrics_catalog.provider_names() no longer reads the live
PROVIDER_REGISTRY / models._KNOWN_PROVIDER_NAMES. It is now the built-in
auth rows (BUILTIN_PROVIDER_IDS), HERMES_OVERLAYS, the three static alias
tables, openrouter/custom, and the names+aliases of profiles registered
from the in-tree plugins/model-providers dir (providers._SOURCES ==
"bundled", process-wide layer, independent of the bound profile home).
Why: auth_plugin_providers mirrors every $HERMES_HOME (and pip) provider
plugin, plus its aliases, into PROVIDER_REGISTRY and the picker labels, so a
user-chosen provider name was treated as shipped and its model id was not
collapsed either. Every consumer goes through provider_metric_name, so the
one fix covers model_route and every per-model v4/v5 metric (tokens,
context_peak, friction, tool_quality, loop_guard, tool_recovery,
model_reply_issue, task_cost, wasted_tokens, cache_break, switch_after,
tool_unavailable, engagement.day), provider_setup (all surfaces, incl. the
PUT /api/env key path), the on-disk pending marker, setup.completed,
model_switch/fallback and install.snapshot main_provider. Pip-installed
provider plugins now read custom too (third-party, not shipped); doc says so.
Probe (fix-catalog/probe_b1_m12.py, user plugin acmecorp-internal alias
acme-llm):
before: provider_metric_name('acmecorp-internal') -> 'acmecorp-internal'
route: {'model': 'acme-secret-model-v2', 'provider': 'acmecorp-internal'}
marker on disk: {..., "provider": "acmecorp-internal"}
after: provider_metric_name('acmecorp-internal') -> 'custom' ('acme-llm' too)
route: {'model': 'custom', 'provider': 'custom'}; marker "provider": "custom"
install main_provider custom; switch/fallback/setup custom
shipped plugin deepinfra: {'model': 'meta-llama/...', 'provider': 'deepinfra'}
Test: test_user_provider_plugin_name_and_model_never_leave (RED on base:
marker carried "acme-llm"; GREEN after).
- hermes.tool_unavailable.count: model called a shipped built-in (BUILTIN_TOOL_NAMES) not enabled in
the session; tool name + catalog provider/model. Unknown names stay in v4 unknown_tool quality.
- hermes.provider_setup.count: started/completed/abandoned/failed per provider and surface
(cli_setup, cli_model, tui, desktop, dashboard) with a closed failure_class. Pending marker per flow;
a dead or stale marker is reported abandoned at the next start (v4 process-marker pattern).
- hermes.feature_adoption.count: once per feature per install at first real use, derived from existing
counters in the subscriber (metric -> feature table) plus Bot Mode / Projects hooks; bucketed by the
owning profile's install age.
- hermes.feature_disabled.count: turning off a default-on toolset/skill/plugin/platform/setting (and the
re-enable back to default), diffed at the config write chokepoints; once per (kind,name,event)/day.
Surface comes from the user entry point; setup/migrations record nothing.
Desktop love/hate telemetry needs a backend half: six counters
(feature_use, action_use, mode_use, friction, dislike, onboarding) with
closed dimension sets, the v3 JSON schema entries, the public doc rows,
and profile-scoped gateway RPCs the app reports through.
Every value the app sends is collapsed server-side onto the closed set
(unknown -> other); feature use latches per area per UTC day, friction
and dislike are capped per day, the daily report (action counts + mode
time + bot count) latches per day and answers recorded=false on a store
failure so the app keeps the day for a retry. For setting changes the
app sends only the config key: the backend reads the saved value and
compares it to DEFAULT_CONFIG itself, so values never cross the wire;
keys outside DEFAULT_CONFIG read other. All helpers check enabled()
before doing any work.
Engagement (local daily rollup, emitted once the UTC day closes, exactly once per profile):
- hermes.engagement.surface_day.count {surface, active_minutes_bucket} per surface used
(cli/tui/desktop/gateway/acp/cron); active time = inter-interaction gaps capped at 5 min.
- hermes.engagement.day.count {active_minutes_bucket, surfaces_used_count, primary_provider,
primary_model, active_profile_count_bucket}; primary model = most attended turns that day.
Active profiles are folded into one host accumulator in the root profile's store (opaque local
hashes); only the root profile's row reports the count, other profiles report 0.
- Days-active-per-week / return-by-model are derived server-side; no weekly state, no new id.
Model satisfaction:
- hermes.model_switch_after.count {provider, model, turns_before_switch_bucket}: turns the model
being left served in the conversation, from every /model site (CLI, TUI, ACP, gateway).
Decisions:
- hermes.session.count counts once per conversation across compression rotation (merged over the
v4 conversation lineage), and gains message/model-call/tool-call count buckets with a longer
tail (251_to_1000, gte_1001); rows recorded before the upgrade still package.
- Relay-delivered hermes.gateway.reply_latency and hermes.platform.delivery report the originating
platform instead of `relay`.
Six opt-in, bucketed shared-metrics counters (schema + contract + docs in `v5 efficiency` blocks):
- hermes.task_cost.count {provider, model, tokens_bucket, tool_calls_bucket, api_calls_bucket,
outcome}: one row per user turn the user saw end (pre_llm_call-started, attended; forks, delegated
children and session-close aborts excluded). Tokens = prompt+completion over the turn's primary
calls. Tool/API call buckets reach gte_101 (TURN_ACTIVITY_BUCKETS; COUNT_BUCKETS untouched).
- hermes.wasted_tokens.count {provider, model, reason in undo/retry/interrupt, tokens_bucket}:
emitted from the v4 friction sites (no re-detection). /undo N counts N turns; an interrupted turn
later undone counts once; turns this process never saw read unknown.
- hermes.tool_output_truncation.count {tool, truncated, original_size_bucket}: one row per tool
result, judged after the per-turn budget; covers the per-result spill, the turn budget, and the
shared head/tail notice tools write when they cut their own output (original size reported).
- hermes.tool_overhead.count {enabled_tool_count_bucket, tool_schema_tokens_bucket,
execution_surface} + hermes.tool_enabled_unused.count {toolset (shipped TOOLSETS else custom),
used}: once per closed interactive conversation (merged across compression lineage).
- hermes.cache_break.count {provider, model, cause}: compression (committed), model_switch /
system_prompt_rebuild (continuing conversation rebuilt its prompt), toolset_change (tool array
changed mid-conversation, Bot Chat capability rebuild), provider_reported_miss (cold read after a
warm read on the same route with no Hermes-known cause), cache_expired (same after >=5 min idle).
A Hermes-known break suppresses the miss it causes. No prompt hashing.
Live-proven against a fake OpenAI-compatible server (chat -q, --resume -m, TUI gateway JSON-RPC
undo/retry/interrupt); disabled => zero telemetry files.
Five opt-in counters that tune the agent loop itself, recorded through
record_process_mark (disabled config => zero rows, zero files):
- hermes.file_edit.count: tool, mode, outcome, match_strategy. The fuzzy
matcher reports the strategy that landed (or no_match / ambiguous) into a
context-local probe opened only around the patch/write_file handlers, so we
learn which strategies earn their keep without counting internal callers.
- hermes.loop_guard.count: provider, model, signal, detector. Hooked where
the guardrail already warns/blocks/halts and at turn end for the iteration
budget; latched once per turn per (signal, detector).
- hermes.tool_recovery.count: provider, model, tool, next_tool,
next_outcome. One row per failed tool call, resolved against the model's
next round (same tool first) or the turn end (no_tool_call / gave_up).
- hermes.terminal.outcome.count: backend, command_kind, outcome. The kind is
a table lookup on the first program word, never the text. Hermes' own
deadline/interrupt now set hermes_timed_out / hermes_interrupted on the
backend result, so a command's own `exit 124` reads nonzero, not timeout.
Disjoint dims from hermes.execution_backend.count (served vs not).
- hermes.model_reply_issue.count: provider, model, issue. Refusal and
truncation only from the structured finish reason; empty/reasoning_only
from the normalized message; issue=none per response as the denominator
(model_route counts attempts and files empty replies as failures).
Background review / curator loops and _host_local / unmetered terminal
calls never count. Helpers live in shared_metrics_harness.py; call sites
are one or two lines each.
- m9: shared_metrics.startup_latency had no server-side latch, so any repeat
call added a row. The TUI and Desktop now send an opaque per-launch id
(TUI: one per process; Desktop: minted when the once-per-launch main-process
claim succeeds) and the backend claims (surface, launch_id) once per
process: a reconnect re-sending the same launch counts once, a new Desktop
launch against a long-lived backend still counts. Legacy clients without an
id count once per backend process and surface. The id is only a local latch
key (bounded set, length-capped), never recorded. Only a usable measurement
spends the claim. Contract + apps/shared regenerated.
- m10: relaunch() execs in place, keeping the PID, so `sessions browse` ->
resume counted the picker time as CLI startup. relaunch() stamps its PID in
HERMES_RELAUNCHED_PID right before exec; process-start surfaces skip when it
matches, while children (other PIDs) inheriting the env still count.
- m8 (psutil half): record_process_ready checks the opt-in gate before reading
the process start time (psutil) or starting a thread. The claim is taken
first so a later opt-in never records a stale "startup" mid-session.
Test changes to existing assertions: the TUI/Desktop param assertions now
expect launch_id (a new wire param); the RPC surface test sends distinct
launch ids so its three calls stay three launches under the new latch.
Two false negatives in the install snapshot's local-server flag (review m11):
- an auxiliary slot under provider auto / no provider with base_url + api_key
was skipped as "inherits main", but agent.auxiliary_client routes exactly
that shape to the endpoint as custom; the filter now mirrors the runtime;
- a providers:/custom_providers: entry referenced by bare name (provider:
home-llama) was only resolved for the custom:<name> spelling. The lookup
now goes through _get_named_custom_provider for any non-inheriting id, so
built-ins still shadow entries exactly as at runtime.
Review findings M7, M8, m6, m7 and the browser half of m8 on the v4 loop metrics.
- M7: TUI/Desktop @-path completion on a non-local backend lists the directory through
terminal_tool, so every keystroke added a hermes.execution_backend.count row as if the user
ran a command. Hermes-owned calls now run inside shared_metrics_loop.unmetered_backend_calls()
(a contextvar checked in record_execution_backend) instead of a flag threaded through
terminal_tool. It was the only non-_host_local internal terminal_tool caller (bot DM runners
already use _host_local; the prompt-builder probe calls env.execute directly).
- M8: a scheduled curator tick that finds the run claim held recorded scheduled/skipped every
tick (5 ticks -> 5 rows for one pass). The holder's own pass is the one counted; the held
branch now records nothing. Real dry runs still report skipped.
- m6: a foreground timeout returns exit 124 with partial output and no error field, so it was
recorded as success. exit 124 now records outcome=failed, error_class=timeout.
- m7: vercel_sandbox (and managed_modal) are built-in backends in
tools/terminal_tool_config._BUILTIN_BACKENDS but collapsed to other. Added to
TERMINAL_BACKENDS and both schema enums; a test pins every built-in backend to its own bucket.
- m8 (browser): record_browser_call resolved the browser backend on every call even with
collection off. The resolver is now passed lazily and only runs inside the gated builder.
The existing test asserting a held claim records scheduled/skipped encoded M8 itself and is
replaced by one asserting held ticks record nothing.
hermes.platform.health / delivery / reply_latency built their core platform
vocabulary from hermes_cli.platforms.PLATFORMS (the setup wizard list), which
has no relay, msgraph_webhook or local entry, so those first-party adapters
were reported as the anonymous "plugin" bucket. The adapter vocabulary now
comes from gateway.config.Platform's declared members (loaded on first use:
gateway.config is too heavy for the contract's import); plugin pseudo-members
are not declared members, so unknown plugin platforms still collapse to
"plugin" and catalog/bundled plugin names keep working. The v3 task platform
vocabulary (GATEWAY_PLATFORMS) is unchanged.
Invariant test: every declared Platform member is named as itself, is
contract-valid for the three adapter metrics and validates against the v3
JSON schema counter definitions (red at d2f70bfaa08b: relay/local -> plugin).
Three defects in how hermes.update.run/stage and hermes.process.exit rows
are recovered from disk:
- Opt-in (M1): the pre-pull park path only checked that the telemetry dir
existed, so it wrote the WHOLE receipt (argv, step detail) while the user
was opted out, and a later opt-in counted that run. It now reads consent
through the already-loaded hermes_cli.config (this interpreter predates
the checkout swap, so nothing may be imported), parks only when
collection is on, parks only the fields update_receipt_fields reads (no
argv, no step text), and purges pending_updates when collection is found
off. begin_process purges them too on a start with collection off.
- Double count (M2): the completion child records the receipt and the
parent's boundary finalize (run_completion returned receipt=None) parks
the same update_id again, so one run became (failed, deps) + (success,
none). record_update_receipt now claims the update_id with an O_EXCL
latch under shared_metrics/recorded_updates (last 64 kept); the second
finalize records nothing.
- Loss (m3): dead-process markers and parked receipts were unlinked before
their row reached the store; "database is locked" under concurrent starts
lost them (17/20 rows in the reviewer's race). The claim-by-rename stays,
but the file is deleted only after record_process_marks_saved confirms
the rows settled: rows carry a random commit ticket in event metadata
(allowlisted in the contract), the subscriber tallies tickets whose rows
persisted, and the reporter flushes the Relay subscribers and compares.
Otherwise the file is renamed back for the next start. A parked receipt
whose rows partly landed is not retried (that would double count).
Also: _epoch returns None for a timestamp float() cannot represent
(10**400 raised OverflowError).
Every graceful gateway stop was reported by the next start as
hermes.process.exit exit_kind=killed: the gateway always leaves through
_exit_after_graceful_shutdown -> os._exit, which skips the atexit
stamp_exit("clean") that begin_process registered, so the marker still
said "running" and a dead "running" owner reads as killed.
The same shape existed on the two other deliberate os._exit exits: the TUI
gateway's grace timer (_hard_exit, only ever armed by a termination
signal, i.e. a requested stop) and the serve parent-death watchdog (the
designed self-reap once the owning Desktop is gone). Each now stamps
"clean" right before os._exit. Crash and watchdog paths are untouched:
the excepthook's "crash" and shutdown_watchdog's "watchdog" stamps win
because stamp_exit only restamps a marker still in "running".
Live: a real `hermes gateway run` in a scratch home stopped with SIGTERM
now reports (gateway, clean); SIGKILL still reports (gateway, killed).
Rotating compaction continues a conversation under a new session id, and
each metrics session emitted its own context_peak at close, so one
conversation produced a row per segment (the fuller one plus a low-fill
one), skewing the per-model distribution. The agent turn already
publishes the lineage root (the Portal conversation id); segments sharing
it join one lineage, contribute their peak when they close, and the
merged peak (fullest fill, limit hit anywhere) is emitted once when the
last open segment closes, whatever the close order. Delegated children
share their parent's root but stay their own conversation.
Review finding m2.
_cmd_undo counted undo friction before undo_last ran, so a refused
durable rewind (active turn lease) still counted. Count after, only when
undo_last installed a rewound history.
Review finding m1.
With no agent yet and `--provider X`, _current_model_runtime returns the
TARGET provider as the current one (switch_model needs that), so the
switch_away friction paired the configured model with the target's
provider: a custom endpoint's private model id shipped labelled `openai`,
and the switch row read openai -> openai. The metric now names the
launch route's provider (HERMES_TUI_PROVIDER, else config.yaml's
provider); when only a credential resolve could tell (env-seeded model),
it reports `unknown`, which collapses the model to `custom`.
Review finding B1.
provider_names() accepts ollama/local/vllm/llamacpp/llama.cpp as published
names (they are aliases of the generic `custom` provider), so every
provider/model metric kept the raw config.yaml model id under them, and a
missing provider (`unknown`) kept it too. Map the aliases Hermes itself
routes to `custom` (derived from the providers/auth/models alias tables)
to `custom`, and report the model as `custom` whenever the provider is
unknown: nothing proves such an id is public. Shipped providers with
public ids are unchanged. Covers model_route, model_tokens (primary and
auxiliary), fallback, model_switch, setup.completed, install snapshot
main_provider, friction, tool_quality and context_peak, which all go
through this pair.
Gateway /model also labelled the configured model with switch_model's
`openrouter` default when config.yaml names no provider; it now reports
the provider actually configured/overridden (None -> `unknown`). And the
switch row + switch_away friction bind the routed profile's home on a
multiplexed runner (slash dispatch installs no profile scope), as the
/retry and /undo friction already do.
Review findings B2, M3.
A crash or SIGKILL cannot record itself. CLI, TUI, gateway, serve and cron-tick
drop a small marker under the profile's store dir at start (only when
collection is on), restamp it clean at exit, crash+exception family from the
excepthook, or watchdog before the gateway's os._exit. The next start in that
profile reports every marker whose owner fails the canonical start-time
liveness check (running => killed), on a daemon thread with rename-claims so
startup never waits and concurrent starts never double count.
Turns killed by the turn liveness watchdog or the gateway inactivity watchdog
count as exit_kind=watchdog once per turn, in the turn's own profile (home
captured at turn entry; off-thread watchdogs bind it explicitly).
The update pipeline already writes one machine-readable receipt per run, so the
run/stage counters are derived from it in the process that finalizes it instead
of instrumenting stages for metrics. The receipt gains minimal stage END marks
(plan, snapshot, apply[mode], deps, build, restart; verify is inferred from the
fleet matrix), an initiator fact (desktop when a live orchestrator claim
names another pid) and the pre-update commit date, which is all the derivation
needs for outcome, failed stage, duration and from-version-age buckets.
A pre-pull interpreter must never import pulled code: when it is the finalizer
(same pid, checkout sha moved) it parks the receipt (stdlib only) and the next
Hermes start records it. Collection off => nothing imported beyond a config read.
The completion-process test stub gains the new record_stage API the real
module now exposes (no assertion changed).
Two product questions shared metrics could not answer: how long each surface
takes from launch to usable (so startup regressions show per release), and how
current, on which channel and on what class of machine installs run.
hermes.startup.latency {surface, latency_bucket} records once per process start:
cli (process creation -> first rendered prompt, or -q dispatch; Kanban workers
excluded), gateway_boot (-> GatewayRunner.start done), serve_boot (-> hermes
serve listening), and tui / desktop_attach reported by the clients through the
new shared_metrics.startup_latency RPC. The clients declare their surface
because a Desktop on a URL/cloud backend has no HERMES_DESKTOP there; env
detection is the fallback for older clients. In-process surfaces measure from
psutil's process create time, the earliest timestamp available, and hand the
runtime start to a daemon thread under the caller's context so no event loop
waits on it. Everything goes through _emit, so disabled profiles record nothing.
The install snapshot gains release_channel, version_age_bucket, behind_bucket,
ram_bucket, gpu_class and local_model_provider_used. All are read offline:
the installed commit's own date, the channel record / packaged channel / checkout
branch (never the remote URL or branch name), and the update check's existing
cache for this exact revision (never a network call). Rows counted before these
fields existed stay valid as a legacy field set.
Three shared-metrics counters that answer "which models misbehave, frustrate
users, or run out of room", all attributed to catalog provider/model names
(custom endpoints and loopback servers collapse to custom) and all behind the
existing enabled() gate.
hermes.model_tool_quality.count {provider, model, call_role, issue}
Counts every tool call a model emits where the agent validates it, clean calls
as issue=none so the rates have a denominator: invalid_json, unknown_tool,
schema_mismatch (missing required keys / non-object), empty_arguments (only for
tools with required params), repaired (Hermes fixed the name or the streamed
argument JSON and ran the call). Stream assembly marks args it repaired and the
chat transport carries the marker onto the normalized ToolCall, because
normalization otherwise erases it.
hermes.model_friction.count {provider, model, signal}
retry / undo / interrupt / quick_abandon / switch_away, blamed on the model that
produced the turn: the relay session remembers its last primary route, so a
/retry after a /model switch still counts against the retried model. Counted
where the action executes, once: CLI handlers (skipped on the TUI slash worker's
shadow CLI), tui_gateway command.dispatch retry/undo and session.undo (Ink
/retry now sends intent=retry, so it counts as a retry, not an undo), gateway
/retry and /undo (multiplexed runners bind the owning profile home), and every
/model surface via record_model_switch(from_model=...). Interrupts and quick
abandonment (session closed within 60s of a failed turn) come from the runtime's
turn close, for attended entrypoints only; a turn still running when the
session closes is neither.
hermes.context_peak.count {provider, model, peak_fill_bucket, window_bucket, limit_hit}
One row per closed top-level session: the fullest primary context it reached
(post_api_request now carries the compressor's context_length) and whether a
call was rejected as too large (context_overflow / payload_too_large, the
rejections Hermes answers with a forced compression). A session whose every
call overflowed still reports, with unknown buckets.
The gateway and cron ticker were blind spots in shared metrics: we could not
tell which messaging platforms fail to connect or drop, how often replies fail
to reach users, how long users wait for a first reply, or whether scheduled
jobs run, fail, get skipped or get missed while Hermes was down.
New opt-in counters (all through the existing enabled() / record_process_mark
gate, recorded fire-and-forget on one background worker that runs in a copy of
the caller's context so the owning profile gets the row):
- hermes.platform.health: platform, event (connect_ok/connect_failed/
reconnect/disconnect), error_class. One seam in the runner
(_connect_adapter_with_timeout, used by cold start, multiplex secondaries and
the reconnect watcher) plus the fatal-error handler; classified from
exception types, HTTP statuses and Hermes's own fatal codes, never text.
- hermes.platform.delivery: platform, outcome, failure_class. One row per
logical BasePlatformAdapter._send_with_retry call (retries and plain-text
fallback included), from SendResult's typed fields or the exception type.
- hermes.gateway.reply_latency: platform, first_response_bucket. Clock starts
when _handle_message accepts a non-internal turn; stops on the stream
consumer's first delivered text or send_final_ledgered. Busy acks and
command replies never stop it.
- hermes.cron.run: outcome (success/failed/missed/skipped), delivery_kind,
duration_bucket. Recorded at the write-once terminal execution row
(finish_execution) and where the due scan drops an occurrence (catch-up
disabled, expired one-shot). Job names, prompts and targets never leave.
Platform names: platforms Hermes ships under plugins/platforms/ now report by
name, and a plugin-catalog platform reports its catalog entry name only when
the installer-owned .install-metadata.json record proves a catalog install of
the plugin dir that defines the registered adapter factory (a URL install
cannot claim a catalog name via its tree or manifest). Everything else stays
"plugin". GATEWAY_PLATFORMS becomes catalog-backed (_CatalogValues), and the
v3 schema's platform fields accept published catalog identifiers.
- memory tool: one row per operation (a batch counts each op); gate/validation
refusals are "rejected", store-level non-application "failed". Memory provider
tools are counted in MemoryManager.handle_tool_call with the op read from the
action arg or tool-name verb.
- curator: run_curator_review records one row per pass (dry run = skipped) with
the before/after diff bucketed; a scheduled pass whose claim is held by another
process counts as skipped. The home is captured before the review thread starts.
- delegate_task: _run_batch opens the call, each joined unit folds its results in,
and the last unit emits the call's single row, so group-split background calls
are not counted per unit.
- terminal / execute_code / browser: counted per call that reached the backend;
the backend is resolved from the owning profile at call time (terminal plan
env_type, code local/remote, browser CDP > Camofox > cloud provider > engine, or
"extension" when the extension controller served the call). Guard refusals and
Hermes' own _host_local commands are not counted.
Tests read rows back from the real store; each call-site group is red with its
source reverted.
Independent review of the v3 metrics found:
- Provider fields were shape-checked only, so `custom:<config key>` (and
any unshipped provider id) reached setup.completed, install.snapshot,
model_switch, fallback, model_tokens and model_route. Providers now pass
only when Hermes ships them (auth registry, overlays, model catalog,
aliases, cached models.dev ids); everything else reads `custom`. A custom
or loopback provider's model id reads `custom`, as does any model id that
looks like a path or URL. Two existing tests asserted the old export of a
custom endpoint's model id and an unshipped provider; they now assert the
collapse, and the smoke run treats the model canary as prohibited.
- Install milestones read the install age on the Relay thread, which has no
profile binding, so a multiplexed profile got the launch profile's age.
The subscriber captures its home at construction.
- Gateway sessions retired by the store (auto-reset, /new, resume) now close
their metrics session at the route transition instead of at shutdown.
- The dashboard MCP add records its install after leaving the config lock.
- Compression and gateway slash counting helpers move into
shared_metrics_events so the >2k-line files barely grow.
plugins_cmd_install.recorded_install wraps the install attempt in every
plugin install entry point: `hermes plugins install` (catalog name, git
URL or shorthand), the dashboard/TUI/connector install
(dashboard_install_plugin) and plugin packs. Each emits one
hermes.extension.install.count event:
- source: catalog for a catalog entry (name = entry name), local for a
file:// repo, url for any other git source (name None)
- outcome: failed when the clone/scan/publish raises, success otherwise
A reinstall over an already-installed plugin and `plugins update` (which
calls the installer core directly) are not counted.
Every path that adds an MCP server now emits one
hermes.extension.install.count event through record_extension_install:
- catalog installs (hermes mcp install, the picker, the dashboard route and
its background CLI action) via mcp_catalog.install_entry
- catalog installs from connector cards and the agent's catalog tool via
_CatalogBackend.install / start_install_oauth (OAuth: success at commit,
failed when the flow cannot start; an abandoned browser step is a cancel)
- custom servers from `hermes mcp add`, POST /api/mcp/servers and the
mcp.add RPC (source url for http, local for stdio, name None)
A reinstall or overwrite of an already-configured server is not counted,
so the metric measures new installs rather than config churn. Catalog
names pass through raw; the contract reports non-catalog names as custom.
The stub binds each HermesCLI member process_command reads;
process_command now reads the shared-metrics surface class attribute,
so the stand-in carries it like _slash_handler.
HermesCLI.process_command records each user-typed slash command once
(canonical registry name, surface cli) through the lazy
shared_metrics_events API. Internal re-entries (quick-command alias,
unique-prefix expansion) pass redispatch=True so one typed command is
one count. Gives hermes.slash_command.count its classic-CLI producer.
- Docs: a Decision-data metrics section mapping each metric to the product question it answers;
skill-load and snapshot paragraphs describe the new public-name and install-age fields.
- setup consent copy names the new data classes (session length, token totals, command and
catalog names, bucketed setup counts).
- The real-CLI smoke now asserts the session summary, token sums, TTFT bucket and milestones in
both the SQLite store and the exported, schema-validated package.
- A profile with no sessions yet is a brand-new install (lt_1h), not unknown: the first task's
milestone and the first snapshot fire before state.db has a session row.
- Two invariant tests: session summaries + once-per-install milestones; token sums per model and
auxiliary task with private task names collapsed.
Adds the contract, store and runtime side of the decision-data extension to shared metrics v3:
per-session summaries, once-per-install milestones, token sums per model/provider (primary and
auxiliary by task), time-to-first-token on model routes, bundled skill names on skill loads, and
install age / main provider / terminal backend / messaging platform count / language on the
daily snapshot. Process-level facts (setup, slash commands, compression, model switches,
fallbacks, extension installs) get a call-site API in shared_metrics_events. Every new
dimension is a closed enum, a bucket or a public catalog name.
The fleet rollups could say that tasks and tools failed, but not why, on which
model, on which messaging platform, or which features installs actually use.
- model_route rows gain call_role, outcome and error_class (the classifier's
FailoverReason for the last failed attempt; a success row keeps the error it
recovered from).
- task_run rows gain platform (built-in gateway platform, plugin, or none);
task_run.finished gains failure_class from a closed set.
- new hermes.tool.usage.count: tool_name (only names from the static
toolsets.TOOLSETS snapshot; mcp/plugin otherwise), outcome, error_class.
- new hermes.install.snapshot, latched to once per rolling 24h like
client.active: memory provider plus bucketed counts of MCP servers,
plugins, skills, cron jobs and profiles; no names.
- package schema v3; v2-shaped pending counters still validate and drain.
- consent copy and developer docs list the new categories; the relay smoke
asserts v3 shapes and disables title generation (its third model request
broke the smoke's request-count check on main).
* feat(vercel): start fresh sandboxes from a managed image instead of the deprecated runtime
Vercel deprecated Sandbox runtimes (node24/node22/python3.13) in Aug 2026 in favour of
images, and rejects runtime+image together and runtime with a snapshot source. New
terminal.vercel_image (default vercel/sandbox/universal:latest, Node 24 + Python 3.14)
picks the image for fresh sandboxes; a pinned terminal.vercel_runtime still works, wins
over the image and logs a deprecation warning; snapshot restores send neither.
Setup wizard prompts for the image, dashboard exposes both keys, status/config show the
effective choice, TERMINAL_VERCEL_IMAGE bridges config to the tool like its siblings.
* feat(config): migration 49 drops the seeded node24 Vercel runtime pin
Every pre-49 config.yaml carries terminal.vercel_runtime: node24 (the template default) and
the setup wizard mirrored it into .env as TERMINAL_VERCEL_RUNTIME. Both are the default
copied, not a choice, so the migration drops them and fresh sandboxes follow vercel_image;
node22 / python3.13 pins are the user's and survive. Persisted sandboxes are unaffected:
a snapshot restore never sends a runtime or an image.
