From 747ee024815aa890514ac8aec5b74ab7d996465d Mon Sep 17 00:00:00 2001 From: TejasLamba2006 Date: Tue, 17 Nov 2026 23:08:20 +0530 Subject: [PATCH 1/2] feat(hermes): follow gateway and cron sessions, add /te command Follow sessions started through the API server, messaging platforms and cron, taking a gateway session's directory from TERMINAL_CWD when its row has none. Register /te through register_command where Hermes offers it. Subagents stay unfollowed, since a session's fold already prices them. --- docs/PLUGIN.md | 10 +++-- plugin/README.md | 17 ++++---- plugin/hermes/__init__.py | 44 +++++++++++++++++---- tests/test_hermes_plugin.py | 78 +++++++++++++++++++++++++++++++++++-- 4 files changed, 126 insertions(+), 23 deletions(-) diff --git a/docs/PLUGIN.md b/docs/PLUGIN.md index 0ca122fc..25b6942e 100644 --- a/docs/PLUGIN.md +++ b/docs/PLUGIN.md @@ -598,8 +598,10 @@ was not.) (`reason: cli_close`), and, against the docs, not for `hermes -z`. * A subagent fires the whole set, on a session of its own (`created_source: subagent`). * A user's interactive row reads `source: local`, `created_source: cli`; a side call's reads - `tool`, with no `cwd`. The plugin follows `created_source` `cli` and `oneshot` with a `cwd`, and a - row it cannot read not at all, so the filter fails closed. + `tool`, with no `cwd`. The plugin follows `created_source` `cli`, `oneshot`, `cron` and the gateway + platforms it lists with a `cwd` (a gateway session with none takes the gateway's `TERMINAL_CWD`), + and a row it cannot read not at all, so the filter fails closed. Subagents stay out: the fold + prices a session with its subagents. * **Side calls.** `--source tokeneconomizer` is refused (`invalid_params`), though the docs say any value is stored; `tool` is accepted. `TE_SIDECALL` does not reach the gateway, and worse: with no gateway running a side call starts one, which kept `TE_SIDECALL=1` in its environment, and would @@ -835,8 +837,8 @@ open-vocabulary. On a repository you do not trust, leave micro-skills off (the d never gets it), and the ledger counts it as injected from `SessionStart`. A turn interrupted with Ctrl+C is closed by the next prompt, not by an event. Side calls leave a session under `~/.grok/sessions/`; xAI models are priced on the fallback curve. -* **Hermes Agent** — experimental: micro-skills and the loop guard, on the classic CLI and one-shot - runs, verified with a scripted model and one free real model. Its limits are listed in +* **Hermes Agent** (experimental): micro-skills and the loop guard, on the classic CLI, one-shot + runs, gateway sessions and `cron`, and `/te` where Hermes has `register_command`; verified with a scripted model and one free real model. Its limits are listed in `plugin/README.md`. * **Antigravity CLI (`agy`, experimental)** — micro-skills' LLM-free facts, tested against `agy` 1.5.1 and 1.5.2 on Windows 11, macOS, and Linux, using its installed hook documentation; diff --git a/plugin/README.md b/plugin/README.md index c2c497cb..d9567c22 100644 --- a/plugin/README.md +++ b/plugin/README.md @@ -487,8 +487,11 @@ the side call denies only `bash`, `edit`, `webfetch` and `websearch`. ## Hermes Agent Experimental, and narrower than the other agents: **micro-skills and the loop guard**, on Hermes's -**classic CLI** (`hermes`, `hermes chat`) and **one-shot runs** (`hermes -z`, `hermes chat --oneshot`), -with `terminal.backend: local`. Tested on 0.22.5 only. +**classic CLI** (`hermes`, `hermes chat`), **one-shot runs** (`hermes -z`, `hermes chat --oneshot`), +and gateway sessions (the API server and messaging platforms such as Discord and Telegram) and `cron` +runs, with `terminal.backend: local`. Tested on 0.22.5 only; the gateway and `cron` sessions have +been exercised against a recorded `state.db` and not against a live platform. Where Hermes has +`register_command`, `/te` runs the command line below. **1. Install.** Link the plugin directory, keeping it next to `scripts/` and `lib/`, enable it, and restart the gateway, which is what runs your sessions: @@ -524,8 +527,9 @@ each later start in that repository, for a week after its last hook; after that unreadable. **Which repository.** Each session's own row names its directory, so sessions in different -repositories can run at once in the one gateway. A session with no directory on this machine is -not followed. +repositories can run at once in the one gateway. A gateway session whose row records no directory +uses the gateway's working directory (`TERMINAL_CWD`); any other session with no directory on this +machine is not followed. A `cron` run is one turn and ends with it. **Model calls.** The proposer and the loop guard's judge run through `hermes chat --oneshot --source tool` on your default Hermes model (`paid_model` names another; `hermes_cli` or `TE_HERMES_CLI` @@ -577,9 +581,8 @@ off in mid-turn by a gateway that died, and two timed-out side calls, were recov * A session resumed after it was folded: its later turns are neither learned from nor priced, since a session folds once. That rule is shared by every agent. It matters more here, because a one-shot run folds as soon as its turn ends, so `hermes -c` after `hermes -z` always lands on it. -* The Ink TUI (`--tui`), Desktop, ACP, messaging platforms and cron are ignored, on purpose: nothing - has been verified there, and a chat is not repository work. So are subagents, whose tokens are - counted with their session and whose tool calls are not. +* The Ink TUI (`--tui`), Desktop and ACP are ignored, on purpose: nothing has been verified there. + So are subagents, whose tokens are counted with their session and whose tool calls are not. * Remote terminal backends, named profiles and `plugins.isolation: host`. * Tool pruning. Hermes has no per-repository tool setting. `llm_request` middleware removed a tool from a request in a probe, but keeping a session's list stable across its cache has not been built. diff --git a/plugin/hermes/__init__.py b/plugin/hermes/__init__.py index 5ab826ee..55db847b 100644 --- a/plugin/hermes/__init__.py +++ b/plugin/hermes/__init__.py @@ -26,11 +26,16 @@ One gateway serves every session and every repository, and its own directory and environment belong to neither, so everything about a session is read from its row in `state.db`, per session. -The plugin follows only sessions a person started in a directory on this machine: `created_source` -`cli` or `oneshot`, with a `cwd`. That is also what keeps it out of its own side calls, which run -in this same gateway as `--source tool` and which `TE_SIDECALL` cannot reach; a session whose row -cannot be read is not followed. Subagents (`subagent`), messaging platforms, cron and the other -surfaces are not followed either. +The plugin follows the sessions a person or a schedule started: `created_source` `cli` or +`oneshot` on this machine, a messaging platform or the API server (`GATEWAY_SOURCES`), and `cron`. +Each needs a directory: its row's `cwd`, or for a gateway session with none, the gateway's own +working directory (`TERMINAL_CWD`). A `cron` run is one turn, so it ends with it, as `hermes -z` +does. Sessions of the plugin's own side calls run in this same gateway as `--source tool` and +`TE_SIDECALL` cannot reach them, and a session whose row cannot be read is not followed, so both +stay out. Subagents (`subagent`) are not followed: the fold prices a session with its subagents, +and a child of its own would count them twice. The terminal UI and ACP are not followed either. + +`/te` runs the command line (`te --host hermes ...`) where Hermes has `register_command`. Hermes runs hooks under `plugins.hook_callback_timeout` (30s), and one overrun silences that callback for 60s for every session, so a dispatcher call has a shorter limit of its own. Every @@ -40,6 +45,7 @@ import logging import os import pathlib +import shlex import sqlite3 import subprocess import sys @@ -50,6 +56,10 @@ HERE = os.path.dirname(os.path.realpath(__file__)) BOOTSTRAP = os.path.join(HERE, "..", "scripts", "te_bootstrap.py") USER_SOURCES = ("cli", "oneshot") +GATEWAY_SOURCES = ("api_server", "discord", "telegram", "slack", "whatsapp", "signal", "matrix", + "mattermost", "email", "sms", "webhook") +SCHEDULED_SOURCES = ("cron",) +FOLLOWED_SOURCES = USER_SOURCES + GATEWAY_SOURCES + SCHEDULED_SOURCES HOOK_TIMEOUT_S = 20 LOCK_TIMEOUT_S = 5 HIDDEN = {"creationflags": subprocess.CREATE_NO_WINDOW} if os.name == "nt" else {} @@ -176,8 +186,8 @@ def _forget_ended(self): def _record(self, row, root): return {"id": root, "cwd": row["cwd"], "lock": threading.Lock(), "started": False, - "mode": "oneshot" if (row.get("created_source") or row.get("source")) == "oneshot" - else "cli", "held": [], "notices": []} + "mode": "oneshot" if (row.get("created_source") or row.get("source")) + in ("oneshot",) + SCHEDULED_SOURCES else "cli", "held": [], "notices": []} def session(self, session_id): """The record of a session the plugin follows, or None. A row that cannot be read is @@ -201,8 +211,10 @@ def session(self, session_id): leaf, root = chain[-1], chain[0]["id"] origin = chain[0].get("created_source") or chain[0].get("source") cwd = leaf.get("cwd") or chain[0].get("cwd") + if not cwd and origin in GATEWAY_SOURCES: + cwd = os.environ.get("TERMINAL_CWD") # a messaging session records none with self.guard: - if origin not in USER_SOURCES or not cwd or not os.path.isdir(cwd): + if origin not in FOLLOWED_SOURCES or not cwd or not os.path.isdir(cwd): if len(self.ignored) >= MAX_IGNORED: self.ignored.clear() self.ignored.add(session_id) @@ -316,6 +328,20 @@ def on_session_finalize(self, session_id=None, reason="", **_): return "\n".join(notices) or None +def te_command(raw_args=""): + """`/te ...`: the command line, as `te --host hermes ...`, and its output as the reply.""" + try: + argv = shlex.split(raw_args or "") + out = subprocess.run([os.environ.get("TE_PYTHON") or sys.executable, BOOTSTRAP, "cli", + "--host", "hermes", *argv], + capture_output=True, encoding="utf-8", errors="replace", + timeout=HOOK_TIMEOUT_S, stdin=subprocess.DEVNULL, + env=dict(os.environ, PYTHONUTF8="1", HERMES_HOME=hermes_home()), + **HIDDEN) + return ((out.stdout or "") + (out.stderr or "")).strip() or "te: no output" + except (OSError, ValueError, subprocess.SubprocessError) as e: + return f"te: {e}" + def register(ctx): bridge = Bridge() ctx.register_system_prompt_section(SECTION_ID, bridge.section, position="after_memory", @@ -324,3 +350,5 @@ def register(ctx): ctx.register_hook("transform_tool_result", bridge.transform_tool_result) ctx.register_hook("on_session_end", bridge.on_session_end) ctx.register_hook("on_session_finalize", bridge.on_session_finalize) + if hasattr(ctx, "register_command"): # older Hermes has none + ctx.register_command("te", te_command, description="TokenEconomizer status and settings") diff --git a/tests/test_hermes_plugin.py b/tests/test_hermes_plugin.py index bed0f667..285203f1 100644 --- a/tests/test_hermes_plugin.py +++ b/tests/test_hermes_plugin.py @@ -283,10 +283,10 @@ def test_a_result_with_no_place_for_a_redirect_is_left_alone(raw): # ---- which sessions are followed --------------------------------------------------------------- @pytest.mark.parametrize("source,created", [("tool", "tool"), ("subagent", "subagent"), - ("telegram", "telegram"), ("cron", "cron"), - ("local", "tui"), ("local", "acp")]) -def test_only_a_persons_classic_or_one_shot_session_is_followed(bridge, home, tmp_path, source, - created): + ("local", "tui"), ("local", "acp"), + ("unknown", "unknown")]) +def test_only_sessions_a_person_or_a_schedule_started_are_followed(bridge, home, tmp_path, source, + created): home.session("x", source=source, created=created, cwd=str(tmp_path)) assert bridge.section({"session_id": "x"}) == "" assert bridge.pre_llm_call(session_id="x", turn_id="t") is None @@ -295,6 +295,39 @@ def test_only_a_persons_classic_or_one_shot_session_is_followed(bridge, home, tm assert bridge.on_session_finalize(session_id="x") is None assert bridge.fake.calls == [] +@pytest.mark.parametrize("source", ["discord", "telegram", "api_server", "slack", "cron"]) +def test_a_gateway_or_cron_session_is_followed_from_its_recorded_directory(bridge, home, tmp_path, + source): + home.session("g", source=source, created=source, cwd=str(tmp_path)) + bridge.section({"session_id": "g"}) + bridge.pre_llm_call(session_id="g", user_message="hi", turn_id="t") + assert bridge.fake.events() == ["SessionStart", "UserPromptSubmit"] + assert {c["_cwd"] for c in bridge.fake.calls} == {str(tmp_path)} + assert bridge.fake.calls[0]["_mode"] == ("oneshot" if source == "cron" else "cli") + +def test_a_gateway_session_with_no_recorded_directory_uses_the_gateways_working_one( + bridge, home, tmp_path, monkeypatch): + home.session("g", source="discord", created="discord", cwd=None) + home.session("t", source="tool", created="tool", cwd=None) + monkeypatch.setenv("TERMINAL_CWD", str(tmp_path)) + bridge.section({"session_id": "g"}) + bridge.section({"session_id": "t"}) + assert bridge.fake.events() == ["SessionStart"] + assert bridge.fake.calls[0]["_cwd"] == str(tmp_path) + assert bridge.fake.calls[0]["session_id"] == "g" + +def test_a_cli_session_with_no_directory_does_not_borrow_the_gateways(bridge, home, tmp_path, + monkeypatch): + home.session("c", cwd=None) + monkeypatch.setenv("TERMINAL_CWD", str(tmp_path)) + assert bridge.section({"session_id": "c"}) == "" + assert bridge.fake.calls == [] + +def test_a_cron_session_ends_with_its_turn(bridge, home, tmp_path): + home.session("j", source="cron", created="cron", cwd=str(tmp_path)) + bridge.pre_llm_call(session_id="j", user_message="go", turn_id="t") + bridge.on_session_end(session_id="j", turn_id="t", completed=True) + assert bridge.fake.events() == ["SessionStart", "UserPromptSubmit", "Stop", "SessionEnd"] def test_a_session_with_no_directory_here_or_with_the_plugin_off_is_not_followed( bridge, home, monkeypatch): @@ -749,6 +782,43 @@ def register_hook(self, name, cb): def register_system_prompt_section(self, sid, cb, position="", max_chars=0): self.sections[sid] = (cb, position, max_chars) +class CommandCtx(Ctx): + def __init__(self): + super().__init__() + self.commands = {} + + def register_command(self, name, handler, description=""): + self.commands[name] = (handler, description) + +def test_te_is_a_slash_command_where_hermes_has_them_and_nothing_where_it_has_not(): + plugin.register(Ctx()) # an older Hermes: no register_command + ctx = CommandCtx() + plugin.register(ctx) + handler, description = ctx.commands["te"] + assert description + +def test_te_runs_the_command_line_for_hermes_and_returns_its_output(monkeypatch): + seen = {} + + def run(cmd, **kw): + seen.update(cmd=cmd, kw=kw) + return subprocess.CompletedProcess(cmd, 0, stdout="all quiet\n", stderr="") + + monkeypatch.setattr(plugin.subprocess, "run", run) + monkeypatch.setattr(plugin, "hermes_home", lambda: "/h") + assert plugin.te_command("status --explain") == "all quiet" + assert seen["cmd"][1:] == [plugin.BOOTSTRAP, "cli", "--host", "hermes", "status", "--explain"] + assert seen["kw"]["env"]["HERMES_HOME"] == "/h" + assert seen["kw"]["timeout"] <= plugin.HOOK_TIMEOUT_S + +@pytest.mark.parametrize("fail", [OSError("no python"), subprocess.TimeoutExpired("te", 1)]) +def test_te_never_raises(monkeypatch, fail): + def run(*a, **kw): + raise fail + monkeypatch.setattr(plugin.subprocess, "run", run) + assert plugin.te_command("status").startswith("te:") + assert plugin.te_command("unbalanced 'quote").startswith("te:") + def test_the_plugin_registers_what_its_manifest_declares(): text = open(os.path.join(REPO, "plugin", "hermes", "plugin.yaml"), encoding="utf-8").read() From e5bb7fe8d265bf1511e13218a53bd3f439219b11 Mon Sep 17 00:00:00 2001 From: TejasLamba2006 Date: Wed, 18 Nov 2026 09:58:14 +0530 Subject: [PATCH 2/2] fix(hermes): resolve each session's directory per session, run /te there, end sessions on reset A gateway session whose row records no cwd no longer takes the gateway's TERMINAL_CWD, which every chat shares. It takes its chat's routed terminal_cwd from gateway_routing, then the directory scoped to the running turn, and is retried at its next hook if it has neither. /te runs in the calling session's directory (session_id, session_key), passes --cwd and cwd, honors an explicit --cwd, and says so when it has no directory. on_session_reset ends the session a /new leaves. Tests cover two repositories through the real dispatcher with gateway and cron sessions, finalize, reset, stale recovery, and /te status. --- docs/PLUGIN.md | 11 +- plugin/README.md | 17 ++- plugin/hermes/__init__.py | 140 +++++++++++++++--- plugin/hermes/plugin.yaml | 1 + tests/test_hermes_plugin.py | 274 ++++++++++++++++++++++++++++++++++-- 5 files changed, 407 insertions(+), 36 deletions(-) diff --git a/docs/PLUGIN.md b/docs/PLUGIN.md index 25b6942e..3b202f63 100644 --- a/docs/PLUGIN.md +++ b/docs/PLUGIN.md @@ -599,8 +599,15 @@ was not.) * A subagent fires the whole set, on a session of its own (`created_source: subagent`). * A user's interactive row reads `source: local`, `created_source: cli`; a side call's reads `tool`, with no `cwd`. The plugin follows `created_source` `cli`, `oneshot`, `cron` and the gateway - platforms it lists with a `cwd` (a gateway session with none takes the gateway's `TERMINAL_CWD`), - and a row it cannot read not at all, so the filter fails closed. Subagents stay out: the fold + platforms it lists with a directory, and a row it cannot read not at all, so the filter fails + closed. The gateway's `os.getcwd()` and `TERMINAL_CWD` are the daemon's, shared by every chat, so + neither names a session's repository. A session's directory is its row's `cwd`; a gateway or + `cron` row that records none (Hermes writes `cwd` at a cron run's end) takes the `terminal_cwd` + of its `gateway_routing` entry, then the directory scoped to the running turn + (`agent.runtime_cwd.scoped_session_cwd`, `ctx.session_cwd()`), and with none it is looked at again + at its next hook. `/te` handlers are passed the `session_id` and `session_key` they declare, and + run in that session's directory. `on_session_reset` is handled as a finalize of the session it + leaves. Subagents stay out: the fold prices a session with its subagents. * **Side calls.** `--source tokeneconomizer` is refused (`invalid_params`), though the docs say any value is stored; `tool` is accepted. `TE_SIDECALL` does not reach the gateway, and worse: with no diff --git a/plugin/README.md b/plugin/README.md index d9567c22..477ef419 100644 --- a/plugin/README.md +++ b/plugin/README.md @@ -526,10 +526,19 @@ quiet for 10 minutes. A session whose rows cannot be read then stays unfolded an each later start in that repository, for a week after its last hook; after that it is recorded as unreadable. -**Which repository.** Each session's own row names its directory, so sessions in different -repositories can run at once in the one gateway. A gateway session whose row records no directory -uses the gateway's working directory (`TERMINAL_CWD`); any other session with no directory on this -machine is not followed. A `cron` run is one turn and ends with it. +**Which repository.** Each session names its own directory, so sessions in different repositories +can run at once in the one gateway; the gateway's working directory and `TERMINAL_CWD` are never +used. A session's directory is its row's `cwd` in Hermes's `state.db`. A gateway or `cron` session +whose row records none takes the `terminal_cwd` of its chat's routing entry (`gateway_routing`), +then the directory Hermes scopes to the running turn; with none of these it is not followed yet, +and is looked at again at its next hook. Any other session with no directory on this machine is not +followed. A `cron` run is one turn and ends with it; a gateway chat ends at `/new` (a finalize or a +reset), at shutdown, or, if neither fires, when the next session starts in its repository after 10 +quiet minutes. + +**`/te`.** It runs in the repository of the session that typed it, found as above and by the chat's +`session_key`. `/te --cwd PATH status` names another. A session with no directory gets +`te: no working directory for this session; pass --cwd PATH`. **Model calls.** The proposer and the loop guard's judge run through `hermes chat --oneshot --source tool` on your default Hermes model (`paid_model` names another; `hermes_cli` or `TE_HERMES_CLI` diff --git a/plugin/hermes/__init__.py b/plugin/hermes/__init__.py index 55db847b..3a7f7203 100644 --- a/plugin/hermes/__init__.py +++ b/plugin/hermes/__init__.py @@ -18,24 +18,36 @@ turn cut short sends no Stop, so it cannot feed the envelope on_session_end (one-shot), - on_session_finalize -> SessionEnd a detached fold. `hermes -z` sends no finalize, + on_session_finalize, + on_session_reset -> SessionEnd a detached fold. `hermes -z` sends no finalize, nor does a killed session: the next session's start folds it once its hooks have gone quiet. The fold reads the session from `state.db` One gateway serves every session and every repository, and its own directory and environment -belong to neither, so everything about a session is read from its row in `state.db`, per session. +(`os.getcwd()`, `TERMINAL_CWD`) belong to neither, so a session's directory is read per session, +and never from them. The plugin follows the sessions a person or a schedule started: `created_source` `cli` or `oneshot` on this machine, a messaging platform or the API server (`GATEWAY_SOURCES`), and `cron`. -Each needs a directory: its row's `cwd`, or for a gateway session with none, the gateway's own -working directory (`TERMINAL_CWD`). A `cron` run is one turn, so it ends with it, as `hermes -z` -does. Sessions of the plugin's own side calls run in this same gateway as `--source tool` and -`TE_SIDECALL` cannot reach them, and a session whose row cannot be read is not followed, so both -stay out. Subagents (`subagent`) are not followed: the fold prices a session with its subagents, -and a child of its own would count them twice. The terminal UI and ACP are not followed either. - -`/te` runs the command line (`te --host hermes ...`) where Hermes has `register_command`. +Each needs a directory, the first of: its row's `cwd` in `state.db`; for a gateway or `cron` +session whose row has none, the `terminal_cwd` of the `gateway_routing` entry that names it (a +database without that table has no such entries); then the directory Hermes scopes to the running +turn (`ctx.session_cwd()`, else `agent.runtime_cwd.scoped_session_cwd()`). A gateway or `cron` +session with none is not followed yet, and is looked at again at its next hook, since a chat can +be given a directory later; any other session without one is not followed. A `cron` run is one +turn, so it ends with it, as `hermes -z` does. Sessions of the plugin's own side calls run in this +same gateway as `--source tool` and `TE_SIDECALL` cannot reach them, and a session whose row cannot +be read is not followed, so both stay out. Subagents (`subagent`) are not followed: the fold +prices a session with its subagents, and a child of its own would count them twice. The terminal +UI and ACP are not followed either. + +`/te` runs the command line (`te --host hermes ...`) where Hermes has `register_command`, in the +calling session's directory: Hermes passes the `session_id` and `session_key` the handler declares, +and the directory is that session's (as above; a chat is also found by its `session_key` in +`gateway_routing`). A `--cwd` in the arguments is used as given. With no directory it says so and +runs nothing, rather than read the gateway's own repository. `on_session_reset` ends the session +a `/new` leaves, as `on_session_finalize` does, and one already ended is not ended twice. Hermes runs hooks under `plugins.hook_callback_timeout` (30s), and one overrun silences that callback for 60s for every session, so a dispatcher call has a shorter limit of its own. Every @@ -146,6 +158,41 @@ def lineage(con, session_id): return rows +def _routes(con): + """Every gateway routing entry, as dicts; none where `state.db` has no such table.""" + try: + rows = con.execute("SELECT session_key, entry_json FROM gateway_routing").fetchall() + except sqlite3.Error: + return [] + out = [] + for key, raw in rows: + try: + entry = json.loads(raw) + except (TypeError, ValueError): + continue + if isinstance(entry, dict): + meta = entry.get("metadata") + out.append((key, entry.get("session_id"), + meta.get("terminal_cwd") if isinstance(meta, dict) else None)) + return out + +def routed_cwd(con, session_ids): + """The directory a gateway chat works in, from the routing entry that names one of these + sessions.""" + for _, sid, cwd in _routes(con): + if cwd and sid in session_ids: + return cwd + return None + +def scoped_cwd(): + """The directory scoped to the session whose turn is running (Hermes binds it per turn and per + cron run), or "". Never the gateway's own.""" + try: + from agent.runtime_cwd import scoped_session_cwd + return scoped_session_cwd() or "" + except Exception: + return "" + def with_redirect(result, text): """`result` carrying `text`, or None when it cannot without losing its shape. A JSON object keeps every byte it had, after a first key of ours; plain text gets the line after it.""" @@ -170,9 +217,10 @@ class Bridge: """What the plugin keeps about sessions in the gateway's memory, keyed by the lineage's first id. A gateway restart loses it, and the next hook finds each session again.""" - def __init__(self, call=dispatch, home=hermes_home): + def __init__(self, call=dispatch, home=hermes_home, session_cwd=scoped_cwd): self.call = call self.home = home + self.session_cwd = session_cwd self.sessions = {} # any id of a followed session -> its record self.ignored = set() self.guard = threading.Lock() @@ -202,18 +250,23 @@ def session(self, session_id): con = _connect(self.home()) try: chain = lineage(con, session_id) + origin = (chain[0].get("created_source") or chain[0].get("source")) if chain else "" + cwd = (chain[-1].get("cwd") or chain[0].get("cwd")) if chain else None + scheduled = origin in GATEWAY_SOURCES + SCHEDULED_SOURCES + if chain and not cwd and scheduled: + cwd = routed_cwd(con, {r["id"] for r in chain}) # a chat's own directory finally: con.close() except (OSError, ValueError, sqlite3.Error): return None if not chain: return None - leaf, root = chain[-1], chain[0]["id"] - origin = chain[0].get("created_source") or chain[0].get("source") - cwd = leaf.get("cwd") or chain[0].get("cwd") - if not cwd and origin in GATEWAY_SOURCES: - cwd = os.environ.get("TERMINAL_CWD") # a messaging session records none + root = chain[0]["id"] + if not cwd and scheduled: + cwd = self.session_cwd() or None # this turn's, never the gateway's with self.guard: + if scheduled and not (cwd and os.path.isdir(cwd)): + return None # a chat or run can be given a directory later if origin not in FOLLOWED_SOURCES or not cwd or not os.path.isdir(cwd): if len(self.ignored) >= MAX_IGNORED: self.ignored.clear() @@ -328,13 +381,56 @@ def on_session_finalize(self, session_id=None, reason="", **_): return "\n".join(notices) or None -def te_command(raw_args=""): + def on_session_reset(self, session_id="", old_session_id="", reason="", **_): + """`/new` ends the session it leaves; a surface that fires this and no finalize still ends + it. A session already ended is not ended twice.""" + return self.on_session_finalize(session_id=old_session_id or session_id, + reason=reason or "reset") + + def command_cwd(self, session_id="", session_key=""): + """The directory of the session that typed `/te`: not this process's, which is the + gateway's.""" + rec = self.session(session_id) + if rec is not None: + return rec["cwd"] + if session_key: + try: + con = _connect(self.home()) + try: + routes = [r for r in _routes(con) if r[0] == session_key] + finally: + con.close() + except (OSError, ValueError, sqlite3.Error): + routes = [] + for _, sid, cwd in routes: + rec = self.session(sid) + found = cwd if cwd and os.path.isdir(cwd) else rec and rec["cwd"] + if found: + return found + cwd = self.session_cwd() + return cwd if cwd and os.path.isdir(cwd) else None + + def command(self, raw_args="", session_id="", session_key="", platform="", source=None, **_): + """`/te ...` for the calling session. Hermes passes the arguments a handler declares.""" + try: + argv = shlex.split(raw_args or "") + if any(a == "--cwd" or a.startswith("--cwd=") for a in argv): + return te_command(raw_args) # the person named a repository + cwd = self.command_cwd(session_id, session_key) + except (ValueError, sqlite3.Error) as e: + return f"te: {e}" + if not cwd and argv[:1] not in (["repos"], ["doctor"]): + return "te: no working directory for this session; pass --cwd PATH" + return te_command(raw_args, cwd) + +def te_command(raw_args="", cwd=None): """`/te ...`: the command line, as `te --host hermes ...`, and its output as the reply.""" try: argv = shlex.split(raw_args or "") + where = ["--cwd", cwd] if cwd else [] out = subprocess.run([os.environ.get("TE_PYTHON") or sys.executable, BOOTSTRAP, "cli", - "--host", "hermes", *argv], - capture_output=True, encoding="utf-8", errors="replace", + "--host", "hermes", *where, *argv], + cwd=cwd, capture_output=True, encoding="utf-8", errors="replace", timeout=HOOK_TIMEOUT_S, stdin=subprocess.DEVNULL, env=dict(os.environ, PYTHONUTF8="1", HERMES_HOME=hermes_home()), **HIDDEN) @@ -343,12 +439,14 @@ def te_command(raw_args=""): return f"te: {e}" def register(ctx): - bridge = Bridge() + # `ctx.session_cwd()` is the calling session's directory, task-local to its turn. + bridge = Bridge(session_cwd=getattr(ctx, "session_cwd", scoped_cwd)) ctx.register_system_prompt_section(SECTION_ID, bridge.section, position="after_memory", max_chars=4000) ctx.register_hook("pre_llm_call", bridge.pre_llm_call) ctx.register_hook("transform_tool_result", bridge.transform_tool_result) ctx.register_hook("on_session_end", bridge.on_session_end) ctx.register_hook("on_session_finalize", bridge.on_session_finalize) + ctx.register_hook("on_session_reset", bridge.on_session_reset) if hasattr(ctx, "register_command"): # older Hermes has none - ctx.register_command("te", te_command, description="TokenEconomizer status and settings") + ctx.register_command("te", bridge.command, description="TokenEconomizer status and settings") diff --git a/plugin/hermes/plugin.yaml b/plugin/hermes/plugin.yaml index 7835ee1e..7d18ee70 100644 --- a/plugin/hermes/plugin.yaml +++ b/plugin/hermes/plugin.yaml @@ -7,3 +7,4 @@ provides_hooks: - transform_tool_result - on_session_end - on_session_finalize + - on_session_reset diff --git a/tests/test_hermes_plugin.py b/tests/test_hermes_plugin.py index 285203f1..a4958a40 100644 --- a/tests/test_hermes_plugin.py +++ b/tests/test_hermes_plugin.py @@ -10,6 +10,7 @@ import os import pathlib import re +import shlex import sqlite3 import subprocess import sys @@ -77,6 +78,16 @@ def usage(self, sid, task="", calls=1, fresh=400, cached=600, out=10, model="te- con.execute("INSERT INTO session_model_usage VALUES (?,?,?,?,?,?,?,0,0,0)", (sid, model, task, calls, fresh, out, cached)) + def route(self, key, sid, cwd=None, scope="gateway"): + """A gateway chat's routing entry, as Hermes persists it when a chat works in a directory.""" + entry = {"session_id": sid, "metadata": {"terminal_cwd": cwd} if cwd else {}} + with self._con() as con: + con.execute("CREATE TABLE IF NOT EXISTS gateway_routing " + "(scope TEXT, session_key TEXT, entry_json TEXT)") + con.execute("DELETE FROM gateway_routing WHERE session_key = ?", (key,)) + con.execute("INSERT INTO gateway_routing VALUES (?,?,?)", + (scope, key, json.dumps(entry))) + def gone(self, sid): with self._con() as con: con.execute("DELETE FROM session_model_usage WHERE session_id = ?", (sid,)) @@ -177,8 +188,8 @@ def test_the_host_reads_what_the_plugin_sends(): # ---- the export ---------------------------------------------------------------------------- -def _conversation(home, sid="s1", cwd="/w/repo"): - home.session(sid, cwd=cwd) +def _conversation(home, sid="s1", cwd="/w/repo", source="local", created="cli"): + home.session(sid, source=source, created=created, cwd=cwd) home.message(sid, "user", "fix it", message_uid="u1") home.message(sid, "assistant", tool_calls=_call("terminal", {"command": "pytest"})) home.message(sid, "tool", '{"output": "1 failed", "exit_code": 1, "error": null}', @@ -305,16 +316,66 @@ def test_a_gateway_or_cron_session_is_followed_from_its_recorded_directory(bridg assert {c["_cwd"] for c in bridge.fake.calls} == {str(tmp_path)} assert bridge.fake.calls[0]["_mode"] == ("oneshot" if source == "cron" else "cli") -def test_a_gateway_session_with_no_recorded_directory_uses_the_gateways_working_one( - bridge, home, tmp_path, monkeypatch): +def test_a_gateway_session_never_borrows_the_gateways_directory(bridge, home, tmp_path, + monkeypatch): + """`TERMINAL_CWD` and the working directory are the gateway's: shared by every chat.""" home.session("g", source="discord", created="discord", cwd=None) home.session("t", source="tool", created="tool", cwd=None) monkeypatch.setenv("TERMINAL_CWD", str(tmp_path)) - bridge.section({"session_id": "g"}) - bridge.section({"session_id": "t"}) - assert bridge.fake.events() == ["SessionStart"] - assert bridge.fake.calls[0]["_cwd"] == str(tmp_path) - assert bridge.fake.calls[0]["session_id"] == "g" + monkeypatch.chdir(tmp_path) + assert bridge.section({"session_id": "g", "cwd": str(tmp_path)}) == "" + assert bridge.section({"session_id": "t"}) == "" + assert bridge.fake.calls == [] + +def test_two_gateway_chats_with_no_recorded_directory_take_their_routed_ones(bridge, home, + tmp_path): + dirs = {} + for name in ("a", "b"): + dirs[name] = str(tmp_path / name) + os.makedirs(dirs[name]) + home.session(name, source="discord", created="discord", cwd=None) + home.route(f"agent:main:discord:dm:{name}", name, dirs[name]) + home.session("c", source="telegram", created="telegram", cwd=None) + home.route("agent:main:telegram:dm:c", "c") # a chat that works in no directory + for name in ("a", "b", "c"): + bridge.section({"session_id": name}) + assert {c["session_id"]: c["_cwd"] for c in bridge.fake.calls} == dirs + +def test_a_routed_directory_is_found_from_a_session_the_chat_rotated_into(bridge, home, tmp_path): + home.session("old", source="discord", created="discord", cwd=None, ended=time.time(), + reason="compression") + home.session("new", source="discord", created="discord", cwd=None, parent="old") + home.route("k", "old", str(tmp_path)) + bridge.section({"session_id": "new"}) + assert [(c["session_id"], c["_cwd"]) for c in bridge.fake.calls] == [("old", str(tmp_path))] + +def test_a_session_scoped_directory_stands_in_for_a_row_that_records_none(home, tmp_path): + calls = [] + for source in ("discord", "cron"): + home.session(source, source=source, created=source, cwd=None) + home.session("c", cwd=None) + b = plugin.Bridge(call=lambda p, cwd, mode, h: calls.append((p["session_id"], cwd)) or {}, + home=lambda: home.path, session_cwd=lambda: str(tmp_path)) + for sid in ("discord", "cron", "c"): + b.section({"session_id": sid}) + assert calls == [("discord", str(tmp_path)), ("cron", str(tmp_path))] # not the CLI's + +def test_a_gateway_chat_that_gets_a_directory_later_is_followed_from_then_on(bridge, home, + tmp_path): + home.session("g", source="discord", created="discord", cwd=None) + assert bridge.section({"session_id": "g"}) == "" + assert bridge.pre_llm_call(session_id="g", user_message="hi", turn_id="t") is None + assert bridge.fake.calls == [] + home.route("k", "g", str(tmp_path)) + bridge.pre_llm_call(session_id="g", user_message="hi", turn_id="t") + assert bridge.fake.events() == ["SessionStart", "UserPromptSubmit"] + +def test_a_side_call_stays_ignored_even_when_a_directory_is_routed_to_it(bridge, home, tmp_path): + home.session("t", source="tool", created="tool", cwd=None) + home.route("k", "t", str(tmp_path)) + assert bridge.section({"session_id": "t"}) == "" + home.session("u", source="tool", created="tool", cwd=str(tmp_path)) + assert bridge.section({"session_id": "u"}) == "" and bridge.fake.calls == [] def test_a_cli_session_with_no_directory_does_not_borrow_the_gateways(bridge, home, tmp_path, monkeypatch): @@ -601,6 +662,126 @@ def turn(sid): assert r["input_tokens"] == 2800 and r["requests"] == 7 and not r.get("error") +def _real(monkeypatch, tmp_path): + root = tmp_path / "te" + monkeypatch.setenv("TOKENECONOMIZER_HOME", str(root)) + monkeypatch.setenv("TE_FOLD_SYNC", "1") + monkeypatch.setenv("TE_CORE_PATH", REPO) + for var in ("TE_DISABLE", "TE_SIDECALL", "TERMINAL_CWD"): + monkeypatch.delenv(var, raising=False) + return root + +def _folded(root): + """Session records in each repository's ledger: {state directory: [session ids]}.""" + out = {} + for path in root.rglob("ledger.jsonl"): + rows = [json.loads(ln) for ln in path.read_text("utf-8").splitlines()] + out[path.parent] = sorted(r["session_id"] for r in rows if r.get("kind") == "session") + return out + +def _one_turn(b, sid, end=True): + b.pre_llm_call(session_id=sid, user_message="fix it", turn_id=f"{sid}-t") + b.transform_tool_result("terminal", {"command": "pytest"}, + '{"output": "1 failed", "exit_code": 1, "error": null}', + session_id=sid, turn_id=f"{sid}-t", tool_call_id=f"{sid}-1") + b.on_session_end(session_id=sid, turn_id=f"{sid}-t", completed=True) + +def test_gateway_and_cron_sessions_in_two_repositories_fold_apart_through_the_real_dispatcher( + home, tmp_path, monkeypatch): + """Four sessions run at once in one gateway, each finding its repository a different way: a + row's `cwd`, a chat's routed directory, the directory scoped to the cron run. The process's + own directory and `TERMINAL_CWD` are a fifth place that is none of theirs.""" + root = _real(monkeypatch, tmp_path) + elsewhere = tmp_path / "gateway-install" + elsewhere.mkdir() + monkeypatch.chdir(elsewhere) + monkeypatch.setenv("TERMINAL_CWD", str(elsewhere)) + alpha, beta = _repo(tmp_path / "alpha"), _repo(tmp_path / "beta") + scoped = threading.local() + b = plugin.Bridge(home=lambda: home.path, session_cwd=lambda: getattr(scoped, "cwd", "")) + sessions = {"rowed": ("api_server", alpha), "chat-a": ("discord", None), + "chat-b": ("telegram", None), "job": ("cron", None)} + for sid, (source, cwd) in sessions.items(): + _conversation(home, sid, cwd=cwd, source=source, created=source) + home.route("agent:discord:a", "chat-a", alpha) + home.route("agent:telegram:b", "chat-b", beta) + + def run(sid): + if sid == "job": + scoped.cwd = beta # `_CronRunScope` binds it per run + b.section({"session_id": sid}) + _one_turn(b, sid) + threads = [threading.Thread(target=run, args=(s,)) for s in sessions] + [t.start() for t in threads] + [t.join() for t in threads] + assert not (root / "errors.log").exists() or not (root / "errors.log").read_text("utf-8").strip() + # A cron run is one turn and ends with it; the chats are still open. + assert list(_folded(root).values()) == [["job"]] + (state_dir,) = _folded(root) + assert state_dir != elsewhere and not any(elsewhere.iterdir()) + + b.on_session_finalize(session_id="chat-a", reason="new_session") # `/new` + b.on_session_reset(session_id="chat-b-2", old_session_id="chat-b", reason="new_session") + ledgers = _folded(root) + assert sorted(map(tuple, ledgers.values())) == [("chat-a",), ("chat-b", "job")] + by_repo = {} + for path in root.rglob("ledger.jsonl"): + rows = [json.loads(ln) for ln in path.read_text("utf-8").splitlines()] + for r in rows: + if r.get("kind") == "session": + by_repo[r["session_id"]] = r["repo"] + assert by_repo == {"job": "beta", "chat-b": "beta", "chat-a": "alpha"} + for rows in (json.loads(ln) for p in root.rglob("ledger.jsonl") + for ln in p.read_text("utf-8").splitlines()): + if rows.get("kind") == "session": + assert rows["input_tokens"] == 2800 and rows["requests"] == 7 and not rows.get("error") + +def test_a_gateway_session_nobody_finalized_is_folded_by_the_next_start_in_its_repository( + home, tmp_path, monkeypatch): + root = _real(monkeypatch, tmp_path) + alpha = _repo(tmp_path / "alpha") + b = plugin.Bridge(home=lambda: home.path) + for sid in ("lost", "next"): + _conversation(home, sid, cwd=None, source="discord", created="discord") + home.route(f"agent:discord:{sid}", sid, alpha) + b.section({"session_id": "lost"}) + _one_turn(b, "lost") + assert _folded(root) == {} + state = next(p for p in root.rglob("lost.json") if p.parent.name == "sessions") + doc = json.loads(state.read_text("utf-8")) + doc.update(started=time.time() - 3 * 600, updated=time.time() - 2 * 600) + state.write_text(json.dumps(doc), encoding="utf-8") + b.section({"session_id": "next"}) # the repository's next session starts + assert list(_folded(root).values()) == [["lost"]] + +def test_te_reads_the_repository_of_the_session_that_asks_whatever_the_process_directory_is( + home, tmp_path, monkeypatch): + root = _real(monkeypatch, tmp_path) + elsewhere = tmp_path / "gateway-install" + elsewhere.mkdir() + monkeypatch.chdir(elsewhere) + alpha, beta = _repo(tmp_path / "alpha"), _repo(tmp_path / "beta") + b = plugin.Bridge(home=lambda: home.path) + for sid, source, repo in (("a", "local", alpha), ("b", "discord", None)): + _conversation(home, sid, cwd=repo, source=source, created="cli" if repo else source) + home.route("agent:discord:b", "b", beta) + b.section({"session_id": "a"}) + b.section({"session_id": "b"}) + monkeypatch.setenv("HERMES_HOME", home.path) + ctx = CommandCtx() + plugin.register(ctx) + handler = ctx.commands["te"][0] + # `status` names the repository it read; the process's own is neither + for kw, want in (({"session_id": "a"}, "alpha"), ({"session_id": "b"}, "beta"), + ({"session_key": "agent:discord:b"}, "beta")): + out = handler("status", **kw) + assert want in out and "gateway-install" not in out, out + explicit = handler(f"--cwd {alpha} status", session_id="b") + assert "alpha" in explicit and "beta" not in explicit + assert "pass --cwd PATH" in handler("status") + assert "alpha" in handler("repos") and "beta" in handler("repos") + assert not any(elsewhere.iterdir()) + # ---- the plugin's own model calls -------------------------------------------------------------- class FakeCli: """`subprocess.run` for the `hermes` commands a side call runs, on a real `state.db`.""" @@ -820,6 +1001,81 @@ def run(*a, **kw): assert plugin.te_command("unbalanced 'quote").startswith("te:") +def _te_run(monkeypatch): + seen = {} + + def run(cmd, **kw): + seen.update(cmd=cmd, kw=kw) + return subprocess.CompletedProcess(cmd, 0, stdout="ok\n", stderr="") + monkeypatch.setattr(plugin.subprocess, "run", run) + return seen + +def test_te_declares_the_session_arguments_hermes_passes_a_handler(): + import inspect + ctx = CommandCtx() + plugin.register(ctx) + params = inspect.signature(ctx.commands["te"][0]).parameters + for name in ("session_id", "session_key", "platform", "source"): + assert params[name].default in ("", None) + +def test_te_runs_in_the_repository_of_the_session_that_called_it(bridge, home, tmp_path, + monkeypatch): + seen = _te_run(monkeypatch) + repo = str(tmp_path / "repo") + os.makedirs(repo) + home.session("s", cwd=repo) + assert bridge.command("status", session_id="s") == "ok" + assert seen["cmd"][1:] == [plugin.BOOTSTRAP, "cli", "--host", "hermes", "--cwd", repo, "status"] + assert seen["kw"]["cwd"] == repo + +def test_te_finds_a_chat_by_its_session_key_before_any_hook_has_run(bridge, home, tmp_path, + monkeypatch): + seen = _te_run(monkeypatch) + routed, rowed = str(tmp_path / "routed"), str(tmp_path / "rowed") + os.makedirs(routed) + os.makedirs(rowed) + home.route("k1", "x", routed) + home.session("y", source="telegram", created="telegram", cwd=rowed) + home.route("k2", "y") + bridge.command("status", session_key="k1") + assert seen["kw"]["cwd"] == routed + bridge.command("status", session_key="k2") + assert seen["kw"]["cwd"] == rowed + +def test_te_falls_back_to_the_directory_scoped_to_the_calling_session(home, tmp_path, monkeypatch): + seen = _te_run(monkeypatch) + b = plugin.Bridge(call=FakeDispatcher(), home=lambda: home.path, + session_cwd=lambda: str(tmp_path)) + b.command("status") + assert seen["kw"]["cwd"] == str(tmp_path) and "--cwd" in seen["cmd"] + +@pytest.mark.parametrize("args", ["--cwd /elsewhere status", "status --cwd /elsewhere", + "status --cwd=/elsewhere"]) +def test_te_leaves_a_directory_the_person_named(bridge, home, tmp_path, monkeypatch, args): + seen = _te_run(monkeypatch) + home.session("s", cwd=str(tmp_path)) + bridge.command(args, session_id="s") + assert seen["cmd"][5:] == shlex.split(args) and seen["kw"].get("cwd") is None + +def test_te_with_no_directory_for_its_session_says_so_and_runs_nothing(bridge, home, tmp_path, + monkeypatch): + seen = _te_run(monkeypatch) + monkeypatch.setenv("TERMINAL_CWD", str(tmp_path)) + monkeypatch.chdir(tmp_path) + home.session("g", source="discord", created="discord", cwd=None) + for kw in ({}, {"session_id": "g"}, {"session_key": "unknown"}): + assert bridge.command("status", **kw) == "te: no working directory for this session; " \ + "pass --cwd PATH" + assert not seen + +def test_a_reset_ends_the_session_it_left_and_only_once(bridge, home, tmp_path): + home.session("old", cwd=str(tmp_path)) + bridge.section({"session_id": "old"}) + bridge.on_session_reset(session_id="new", old_session_id="old", reason="new_session") + bridge.on_session_reset(session_id="new", old_session_id="old", reason="new_session") + assert bridge.fake.events() == ["SessionStart", "SessionEnd"] + assert bridge.fake.calls[1]["reason"] == "new_session" + def test_the_plugin_registers_what_its_manifest_declares(): text = open(os.path.join(REPO, "plugin", "hermes", "plugin.yaml"), encoding="utf-8").read() ctx = Ctx()