feat: expose cron runtime overrides for burn-loop pinning (#799)

Add cron CLI flags for per-job model, provider, and base URL overrides,
forward them through hermes_cli.cron, and print pinned runtime overrides
in create/edit/list output so Gemma burn-loop jobs are auditable.

docs/issue-954-verification.md

@@ -1,100 +0,0 @@
-# Issue #954 Verification — maps skill guest_house / camp_site / bakery
-
-Status: PASS
-
-## Drift noted
-
-Issue #954 asked for validation on `upstream/main` (commit `c5a814b23`).
-Fresh `forge/main` did not contain `skills/productivity/maps/`, so the forge branch was behind upstream for this feature cluster.
-This branch ports the upstream maps skill files into the forge checkout and adds regression coverage.
-
-## Automated verification
-
-Command:
-
-```bash
-pytest -q tests/skills/test_maps_client.py
-```
-
-Result:
-
-- 5 passed
-
-Coverage added:
-
-- maps skill files exist in the repo
-- `guest_house` category maps to `tourism=guest_house`
-- `camp_site` category maps to `tourism=camp_site`
-- `bakery` expands to both `shop=bakery` and `amenity=bakery`
-- dual-key bakery results dedupe correctly
-- skill documentation lists the new categories and supersedes `find-nearby`
-
-## Manual evidence
-
-### 1) guest_house lookup
-
-Command:
-
-```bash
-python3 skills/productivity/maps/scripts/maps_client.py nearby --near "Bath, United Kingdom" --category guest_house --limit 3
-```
-
-Observed results:
-
-- Henrietta House — 390.3 m
-- The Windsor — 437.2 m
-- The Old Rectory Bed & Breakfast — 495.7 m
-
-All returned `tourism=guest_house` in the raw tags.
-
-### 2) camp_site lookup
-
-Command:
-
-```bash
-python3 skills/productivity/maps/scripts/maps_client.py nearby --near "Yosemite Valley, California" --category camp_site --limit 5
-```
-
-Observed result:
-
-- Yellow Pine Administrative Campground — 90.3 m
-
-Returned `tourism=camp_site` in the raw tags.
-
-### 3) bakery lookup via `shop=bakery`
-
-Command:
-
-```bash
-python3 skills/productivity/maps/scripts/maps_client.py nearby --near "Lawrenceville, New Jersey" --category bakery --radius 5000 --limit 10
-```
-
-Observed results:
-
-- The Gingered Peach — 713.8 m
-- WildFlour Bakery — 741.9 m
-
-Both returned `shop=bakery` in the raw tags.
-
-### 4) bakery lookup via `amenity=bakery`
-
-Command:
-
-```bash
-python3 skills/productivity/maps/scripts/maps_client.py nearby --near "20735 Stevens Creek Boulevard, Cupertino, CA" --category bakery --radius 600 --limit 5
-```
-
-Observed result:
-
-- Paris Baguette — 28.6 m
-
-Returned `amenity=bakery` in the raw tags (and also includes `shop=bakery`), proving the dual-key union query reaches amenity-tagged bakeries too.
-
-## Conclusion
-
-PASS.
-
-- `guest_house` resolves correctly
-- `camp_site` resolves correctly
-- `bakery` resolves through both supported keys
-- forge/main drift from upstream/main was real and is addressed on this branch

hermes_cli/cron.py

@@ -38,6 +38,18 @@ def _cron_api(**kwargs):
     return json.loads(cronjob_tool(**kwargs))
 
 
+def _print_runtime_overrides(job: dict) -> None:
+    model = job.get("model")
+    provider = job.get("provider")
+    base_url = job.get("base_url")
+    if model:
+        print(f"    Model:     {model}")
+    if provider:
+        print(f"    Provider:  {provider}")
+    if base_url:
+        print(f"    Base URL:  {base_url}")
+
+
 def cron_list(show_all: bool = False):
     """List all scheduled jobs."""
     from cron.jobs import list_jobs
@@ -93,6 +105,7 @@ def cron_list(show_all: bool = False):
         script = job.get("script")
         if script:
             print(f"    Script:    {script}")
+        _print_runtime_overrides(job)
 
         # Execution history
         last_status = job.get("last_status")
@@ -167,6 +180,9 @@ def cron_create(args):
         repeat=getattr(args, "repeat", None),
         skill=getattr(args, "skill", None),
         skills=_normalize_skills(getattr(args, "skill", None), getattr(args, "skills", None)),
+        model=getattr(args, "model", None),
+        provider=getattr(args, "provider", None),
+        base_url=getattr(args, "base_url", None),
         script=getattr(args, "script", None),
     )
     if not result.get("success"):
@@ -180,6 +196,8 @@ def cron_create(args):
     job_data = result.get("job", {})
     if job_data.get("script"):
         print(f"  Script: {job_data['script']}")
+    if job_data:
+        _print_runtime_overrides(job_data)
     print(f"  Next run: {result['next_run_at']}")
     return 0
 
@@ -217,6 +235,9 @@ def cron_edit(args):
         deliver=getattr(args, "deliver", None),
         repeat=getattr(args, "repeat", None),
         skills=final_skills,
+        model=getattr(args, "model", None),
+        provider=getattr(args, "provider", None),
+        base_url=getattr(args, "base_url", None),
         script=getattr(args, "script", None),
     )
     if not result.get("success"):
@@ -233,6 +254,7 @@ def cron_edit(args):
         print("  Skills: none")
     if updated.get("script"):
         print(f"  Script: {updated['script']}")
+    _print_runtime_overrides(updated)
     return 0
 
 

hermes_cli/main.py

@@ -4958,6 +4958,9 @@ For more help on a command:
     cron_create.add_argument("--deliver", help="Delivery target: origin, local, telegram, discord, signal, or platform:chat_id")
     cron_create.add_argument("--repeat", type=int, help="Optional repeat count")
     cron_create.add_argument("--skill", dest="skills", action="append", help="Attach a skill. Repeat to add multiple skills.")
+    cron_create.add_argument("--model", help="Pin this job to a specific model (for example: google/gemma-4-31b-it)")
+    cron_create.add_argument("--provider", help="Pin this job to a specific provider (for example: openrouter)")
+    cron_create.add_argument("--base-url", dest="base_url", help="Optional base URL override for the job's runtime provider")
     cron_create.add_argument("--script", help="Path to a Python script whose stdout is injected into the prompt each run")
 
     # cron edit
@@ -4972,6 +4975,9 @@ For more help on a command:
     cron_edit.add_argument("--add-skill", dest="add_skills", action="append", help="Append a skill without replacing the existing list. Repeatable.")
     cron_edit.add_argument("--remove-skill", dest="remove_skills", action="append", help="Remove a specific attached skill. Repeatable.")
     cron_edit.add_argument("--clear-skills", action="store_true", help="Remove all attached skills from the job")
+    cron_edit.add_argument("--model", help="Update the job's pinned model")
+    cron_edit.add_argument("--provider", help="Update the job's pinned provider")
+    cron_edit.add_argument("--base-url", dest="base_url", help="Update the job's pinned base URL. Pass an empty string to clear it.")
     cron_edit.add_argument("--script", help="Path to a Python script whose stdout is injected into the prompt each run. Pass empty string to clear.")
 
     # lifecycle actions

skills/productivity/maps/SKILL.md

@@ -1,199 +0,0 @@
----
-name: maps
-description: >
-  Location intelligence — geocode a place, reverse-geocode coordinates,
-  find nearby places (46 POI categories), driving/walking/cycling
-  distance + time, turn-by-turn directions, timezone lookup, bounding
-  box + area for a named place, and POI search within a rectangle.
-  Uses OpenStreetMap + Overpass + OSRM. Free, no API key.
-version: 1.2.0
-author: Mibayy
-license: MIT
-metadata:
-  hermes:
-    tags: [maps, geocoding, places, routing, distance, directions, nearby, location, openstreetmap, nominatim, overpass, osrm]
-    category: productivity
-    requires_toolsets: [terminal]
-    supersedes: [find-nearby]
----
-
-# Maps Skill
-
-Location intelligence using free, open data sources. 8 commands, 44 POI
-categories, zero dependencies (Python stdlib only), no API key required.
-
-Data sources: OpenStreetMap/Nominatim, Overpass API, OSRM, TimeAPI.io.
-
-This skill supersedes the old `find-nearby` skill — all of find-nearby's
-functionality is covered by the `nearby` command below, with the same
-`--near "<place>"` shortcut and multi-category support.
-
-## When to Use
-
-- User sends a Telegram location pin (latitude/longitude in the message) → `nearby`
-- User wants coordinates for a place name → `search`
-- User has coordinates and wants the address → `reverse`
-- User asks for nearby restaurants, hospitals, pharmacies, hotels, etc. → `nearby`
-- User wants driving/walking/cycling distance or travel time → `distance`
-- User wants turn-by-turn directions between two places → `directions`
-- User wants timezone information for a location → `timezone`
-- User wants to search for POIs within a geographic area → `area` + `bbox`
-
-## Prerequisites
-
-Python 3.8+ (stdlib only — no pip installs needed).
-
-Script path: `~/.hermes/skills/maps/scripts/maps_client.py`
-
-## Commands
-
-```bash
-MAPS=~/.hermes/skills/maps/scripts/maps_client.py
-```
-
-### search — Geocode a place name
-
-```bash
-python3 $MAPS search "Eiffel Tower"
-python3 $MAPS search "1600 Pennsylvania Ave, Washington DC"
-```
-
-Returns: lat, lon, display name, type, bounding box, importance score.
-
-### reverse — Coordinates to address
-
-```bash
-python3 $MAPS reverse 48.8584 2.2945
-```
-
-Returns: full address breakdown (street, city, state, country, postcode).
-
-### nearby — Find places by category
-
-```bash
-# By coordinates (from a Telegram location pin, for example)
-python3 $MAPS nearby 48.8584 2.2945 restaurant --limit 10
-python3 $MAPS nearby 40.7128 -74.0060 hospital --radius 2000
-
-# By address / city / zip / landmark — --near auto-geocodes
-python3 $MAPS nearby --near "Times Square, New York" --category cafe
-python3 $MAPS nearby --near "90210" --category pharmacy
-
-# Multiple categories merged into one query
-python3 $MAPS nearby --near "downtown austin" --category restaurant --category bar --limit 10
-```
-
-46 categories: restaurant, cafe, bar, hospital, pharmacy, hotel, guest_house,
-camp_site, supermarket, atm, gas_station, parking, museum, park, school,
-university, bank, police, fire_station, library, airport, train_station,
-bus_stop, church, mosque, synagogue, dentist, doctor, cinema, theatre, gym,
-swimming_pool, post_office, convenience_store, bakery, bookshop, laundry,
-car_wash, car_rental, bicycle_rental, taxi, veterinary, zoo, playground,
-stadium, nightclub.
-
-Each result includes: `name`, `address`, `lat`/`lon`, `distance_m`,
-`maps_url` (clickable Google Maps link), `directions_url` (Google Maps
-directions from the search point), and promoted tags when available —
-`cuisine`, `hours` (opening_hours), `phone`, `website`.
-
-### distance — Travel distance and time
-
-```bash
-python3 $MAPS distance "Paris" --to "Lyon"
-python3 $MAPS distance "New York" --to "Boston" --mode driving
-python3 $MAPS distance "Big Ben" --to "Tower Bridge" --mode walking
-```
-
-Modes: driving (default), walking, cycling. Returns road distance, duration,
-and straight-line distance for comparison.
-
-### directions — Turn-by-turn navigation
-
-```bash
-python3 $MAPS directions "Eiffel Tower" --to "Louvre Museum" --mode walking
-python3 $MAPS directions "JFK Airport" --to "Times Square" --mode driving
-```
-
-Returns numbered steps with instruction, distance, duration, road name, and
-maneuver type (turn, depart, arrive, etc.).
-
-### timezone — Timezone for coordinates
-
-```bash
-python3 $MAPS timezone 48.8584 2.2945
-python3 $MAPS timezone 35.6762 139.6503
-```
-
-Returns timezone name, UTC offset, and current local time.
-
-### area — Bounding box and area for a place
-
-```bash
-python3 $MAPS area "Manhattan, New York"
-python3 $MAPS area "London"
-```
-
-Returns bounding box coordinates, width/height in km, and approximate area.
-Useful as input for the bbox command.
-
-### bbox — Search within a bounding box
-
-```bash
-python3 $MAPS bbox 40.75 -74.00 40.77 -73.98 restaurant --limit 20
-```
-
-Finds POIs within a geographic rectangle. Use `area` first to get the
-bounding box coordinates for a named place.
-
-## Working With Telegram Location Pins
-
-When a user sends a location pin, the message contains `latitude:` and
-`longitude:` fields. Extract those and pass them straight to `nearby`:
-
-```bash
-# User sent a pin at 36.17, -115.14 and asked "find cafes nearby"
-python3 $MAPS nearby 36.17 -115.14 cafe --radius 1500
-```
-
-Present results as a numbered list with names, distances, and the
-`maps_url` field so the user gets a tap-to-open link in chat. For "open
-now?" questions, check the `hours` field; if missing or unclear, verify
-with `web_search` since OSM hours are community-maintained and not always
-current.
-
-## Workflow Examples
-
-**"Find Italian restaurants near the Colosseum":**
-1. `nearby --near "Colosseum Rome" --category restaurant --radius 500`
-   — one command, auto-geocoded
-
-**"What's near this location pin they sent?":**
-1. Extract lat/lon from the Telegram message
-2. `nearby LAT LON cafe --radius 1500`
-
-**"How do I walk from hotel to conference center?":**
-1. `directions "Hotel Name" --to "Conference Center" --mode walking`
-
-**"What restaurants are in downtown Seattle?":**
-1. `area "Downtown Seattle"` → get bounding box
-2. `bbox S W N E restaurant --limit 30`
-
-## Pitfalls
-
-- Nominatim ToS: max 1 req/s (handled automatically by the script)
-- `nearby` requires lat/lon OR `--near "<address>"` — one of the two is needed
-- OSRM routing coverage is best for Europe and North America
-- Overpass API can be slow during peak hours; the script automatically
-  falls back between mirrors (overpass-api.de → overpass.kumi.systems)
-- `distance` and `directions` use `--to` flag for the destination (not positional)
-- If a zip code alone gives ambiguous results globally, include country/state
-
-## Verification
-
-```bash
-python3 ~/.hermes/skills/maps/scripts/maps_client.py search "Statue of Liberty"
-# Should return lat ~40.689, lon ~-74.044
-
-python3 ~/.hermes/skills/maps/scripts/maps_client.py nearby --near "Times Square" --category restaurant --limit 3
-# Should return a list of restaurants within ~500m of Times Square
-```

tests/hermes_cli/test_cron.py

@@ -1,6 +1,7 @@
 """Tests for hermes_cli.cron command handling."""
 
 from argparse import Namespace
+from unittest.mock import patch
 
 import pytest
 
@@ -105,3 +106,135 @@ class TestCronCommandLifecycle:
         assert len(jobs) == 1
         assert jobs[0]["skills"] == ["blogwatcher", "find-nearby"]
         assert jobs[0]["name"] == "Skill combo"
+
+    def test_create_can_pin_runtime_model_provider_and_base_url(self, tmp_cron_dir, capsys):
+        cron_command(
+            Namespace(
+                cron_command="create",
+                schedule="every 1h",
+                prompt="Run the burn loop",
+                name="Gemma burn",
+                deliver=None,
+                repeat=None,
+                skill=None,
+                skills=None,
+                script=None,
+                model="google/gemma-4-31b-it",
+                provider="openrouter",
+                base_url="https://openrouter.ai/api/v1",
+            )
+        )
+
+        job = list_jobs()[0]
+        assert job["model"] == "google/gemma-4-31b-it"
+        assert job["provider"] == "openrouter"
+        assert job["base_url"] == "https://openrouter.ai/api/v1"
+
+        out = capsys.readouterr().out
+        assert "Created job" in out
+        assert "Model:     google/gemma-4-31b-it" in out
+        assert "Provider:  openrouter" in out
+
+    def test_edit_can_update_runtime_model_provider_and_clear_base_url(self, tmp_cron_dir, capsys):
+        job = create_job(prompt="Check server status", schedule="every 1h")
+
+        cron_command(
+            Namespace(
+                cron_command="edit",
+                job_id=job["id"],
+                schedule=None,
+                prompt=None,
+                name=None,
+                deliver=None,
+                repeat=None,
+                skill=None,
+                skills=None,
+                add_skills=None,
+                remove_skills=None,
+                clear_skills=False,
+                script=None,
+                model="google/gemma-4-31b-it",
+                provider="openrouter",
+                base_url="",
+            )
+        )
+
+        updated = get_job(job["id"])
+        assert updated["model"] == "google/gemma-4-31b-it"
+        assert updated["provider"] == "openrouter"
+        assert updated["base_url"] is None
+
+        out = capsys.readouterr().out
+        assert "Updated job" in out
+        assert "Model:     google/gemma-4-31b-it" in out
+        assert "Provider:  openrouter" in out
+
+
+class TestCronParserRuntimeOverrideFlags:
+    def test_main_parses_create_runtime_override_flags(self, monkeypatch):
+        from hermes_cli import main as main_mod
+
+        captured = {}
+
+        def fake_cmd_cron(args):
+            captured["args"] = args
+
+        monkeypatch.setattr(main_mod, "cmd_cron", fake_cmd_cron)
+        monkeypatch.setattr(
+            "sys.argv",
+            [
+                "hermes",
+                "cron",
+                "create",
+                "every 1h",
+                "Run the burn loop",
+                "--model",
+                "google/gemma-4-31b-it",
+                "--provider",
+                "openrouter",
+                "--base-url",
+                "https://openrouter.ai/api/v1",
+            ],
+        )
+
+        main_mod.main()
+
+        args = captured["args"]
+        assert args.cron_command == "create"
+        assert args.model == "google/gemma-4-31b-it"
+        assert args.provider == "openrouter"
+        assert args.base_url == "https://openrouter.ai/api/v1"
+
+    def test_main_parses_edit_runtime_override_flags(self, monkeypatch):
+        from hermes_cli import main as main_mod
+
+        captured = {}
+
+        def fake_cmd_cron(args):
+            captured["args"] = args
+
+        monkeypatch.setattr(main_mod, "cmd_cron", fake_cmd_cron)
+        monkeypatch.setattr(
+            "sys.argv",
+            [
+                "hermes",
+                "cron",
+                "edit",
+                "job123",
+                "--model",
+                "google/gemma-4-31b-it",
+                "--provider",
+                "openrouter",
+                "--base-url",
+                "",
+            ],
+        )
+
+        main_mod.main()
+
+        args = captured["args"]
+        assert args.cron_command == "edit"
+        assert args.job_id == "job123"
+        assert args.model == "google/gemma-4-31b-it"
+        assert args.provider == "openrouter"
+        assert args.base_url == ""

tests/skills/test_maps_client.py

@@ -1,135 +0,0 @@
-"""Regression tests for the bundled maps skill."""
-
-from __future__ import annotations
-
-import importlib.util
-from pathlib import Path
-from types import SimpleNamespace
-
-SCRIPT_PATH = (
-    Path(__file__).resolve().parents[2]
-    / "skills/productivity/maps/scripts/maps_client.py"
-)
-SKILL_PATH = (
-    Path(__file__).resolve().parents[2]
-    / "skills/productivity/maps/SKILL.md"
-)
-
-
-def load_module():
-    assert SCRIPT_PATH.exists(), f"missing maps client script: {SCRIPT_PATH}"
-    spec = importlib.util.spec_from_file_location("maps_client_test", SCRIPT_PATH)
-    module = importlib.util.module_from_spec(spec)
-    assert spec.loader is not None
-    spec.loader.exec_module(module)
-    return module
-
-
-def test_maps_skill_files_exist():
-    assert SCRIPT_PATH.exists()
-    assert SKILL_PATH.exists()
-
-
-def test_category_tags_cover_guest_house_camp_site_and_dual_key_bakery():
-    module = load_module()
-
-    assert module.CATEGORY_TAGS["guest_house"] == ("tourism", "guest_house")
-    assert module.CATEGORY_TAGS["camp_site"] == ("tourism", "camp_site")
-    assert module.CATEGORY_TAGS["bakery"] == [
-        ("shop", "bakery"),
-        ("amenity", "bakery"),
-    ]
-    assert module._tags_for("bakery") == [
-        ("shop", "bakery"),
-        ("amenity", "bakery"),
-    ]
-
-
-def test_build_overpass_queries_include_all_supported_tags():
-    module = load_module()
-
-    bakery_query = module.build_overpass_nearby(
-        None,
-        None,
-        40.0,
-        -74.0,
-        500,
-        10,
-        tag_pairs=module._tags_for("bakery"),
-    )
-    assert 'node["shop"="bakery"]' in bakery_query
-    assert 'way["shop"="bakery"]' in bakery_query
-    assert 'node["amenity"="bakery"]' in bakery_query
-    assert 'way["amenity"="bakery"]' in bakery_query
-
-    guest_house_query = module.build_overpass_nearby(
-        None,
-        None,
-        40.0,
-        -74.0,
-        500,
-        10,
-        tag_pairs=module._tags_for("guest_house"),
-    )
-    assert 'node["tourism"="guest_house"]' in guest_house_query
-    assert 'way["tourism"="guest_house"]' in guest_house_query
-
-    camp_site_bbox = module.build_overpass_bbox(
-        None,
-        None,
-        39.0,
-        -75.0,
-        41.0,
-        -73.0,
-        10,
-        tag_pairs=module._tags_for("camp_site"),
-    )
-    assert 'node["tourism"="camp_site"]' in camp_site_bbox
-    assert 'way["tourism"="camp_site"]' in camp_site_bbox
-
-
-def test_cmd_nearby_dedupes_dual_tag_bakery_results(monkeypatch, capsys):
-    module = load_module()
-
-    duplicate_bakery = {
-        "elements": [
-            {
-                "type": "node",
-                "id": 101,
-                "lat": 40.0,
-                "lon": -74.0,
-                "tags": {"name": "Wild Flour", "shop": "bakery"},
-            },
-            {
-                "type": "node",
-                "id": 101,
-                "lat": 40.0,
-                "lon": -74.0,
-                "tags": {"name": "Wild Flour", "amenity": "bakery"},
-            },
-        ]
-    }
-
-    monkeypatch.setattr(module, "overpass_query", lambda query: duplicate_bakery)
-    args = SimpleNamespace(
-        lat="40.0",
-        lon="-74.0",
-        near=None,
-        category="bakery",
-        category_list=[],
-        radius=500,
-        limit=10,
-    )
-
-    module.cmd_nearby(args)
-    out = capsys.readouterr().out
-    assert '"count": 1' in out
-    assert '"Wild Flour"' in out
-
-
-def test_skill_doc_lists_new_categories_and_supersession():
-    text = SKILL_PATH.read_text(encoding="utf-8")
-    assert "guest_house" in text
-    assert "camp_site" in text
-    assert "bakery" in text
-    assert "supersedes: [find-nearby]" in text