generic-ml-wrapper 0.1.0__py3-none-any.whl

generic_ml_wrapper/adapter/outbound/caller/status_line_config.py

@@ -0,0 +1,142 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Install/restore a client's ``statusLine`` command hook in its JSON settings file.
+
+Both Claude Code (``~/.claude/settings.json``) and cursor-agent
+(``~/.cursor/cli-config.json``) point a ``statusLine`` key at ``gmlw statusline``.
+This snapshots the prior value on install and puts it back on restore, so the
+user's own setting survives a run.
+
+Two safety properties matter because this file is the user's, not ours:
+- If the file exists but cannot be parsed as JSON, we NEVER overwrite it (that would
+  destroy the user's settings). We raise :class:`SettingsUnreadableError` and the run
+  aborts with guidance. "Absent" and "unparseable" are different: absent is fine.
+- Writes are atomic (temp file + ``replace``), and restore is ownership-aware: it puts
+  the old value back only if this run's value is still installed, so two concurrent
+  runs can't clobber each other into leaving ``gmlw statusline`` behind.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import cast
+
+from generic_ml_wrapper.common.log import log
+
+
+def statusline_command() -> str:
+    """The command a client's ``statusLine`` hook invokes.
+
+    ``gmlw statusline`` when ``gmlw`` is on ``PATH`` (survives reinstalls); otherwise
+    the absolute path to the ``gmlw`` beside this interpreter -- so the hook still
+    resolves when the client is launched from an environment that lacks ``gmlw`` on
+    ``PATH`` (a dev checkout, a venv that isn't activated).
+    """
+    if shutil.which("gmlw"):
+        return "gmlw statusline"
+    candidate = Path(sys.executable).with_name("gmlw")
+    return f"{candidate} statusline" if candidate.exists() else "gmlw statusline"
+
+
+class SettingsUnreadableError(Exception):
+    """A client settings file exists but is not a readable JSON object.
+
+    Overwriting it would destroy the user's settings, so the run aborts instead.
+    """
+
+    def __init__(self, path: Path) -> None:
+        """Build the error with actionable guidance for ``path``."""
+        self.path = path
+        super().__init__(
+            f"{path} is not valid JSON.\n\n"
+            "The wrapper installs its status line by editing this file, and would have to\n"
+            "overwrite it to continue. Overwriting a file it cannot parse would destroy your\n"
+            "existing settings (model, permissions, env, hooks), so the run is aborted.\n\n"
+            "To fix:\n"
+            f"  1. Check it:   python -m json.tool {path}\n"
+            "  2. Common causes: // or /* */ comments, or a trailing comma -- JSON allows none.\n"
+            f"  3. Or move it aside:  mv {path} {path}.bak   (a fresh one will be created)\n"
+            "Then run gmlw again."
+        )
+
+
+@dataclass(frozen=True)
+class StatusLineSnapshot:
+    """The ``statusLine`` before install, plus what this run installed (for restore)."""
+
+    had_status_line: bool
+    previous: object
+    installed: object
+
+
+def install(path: Path, status_line: dict[str, object]) -> StatusLineSnapshot:
+    """Install ``status_line`` into the settings at ``path``, returning a snapshot.
+
+    Args:
+        path: The client's JSON settings file.
+        status_line: The ``statusLine`` value to install.
+
+    Returns:
+        A snapshot of the prior ``statusLine`` for :func:`restore`.
+
+    Raises:
+        SettingsUnreadableError: If ``path`` exists but is not a JSON object; the file
+            is left untouched.
+    """
+    settings = _load(path)
+    installed = dict(status_line)
+    snapshot = StatusLineSnapshot("statusLine" in settings, settings.get("statusLine"), installed)
+    settings["statusLine"] = installed
+    _write(path, settings)
+    return snapshot
+
+
+def restore(path: Path, snapshot: StatusLineSnapshot) -> None:
+    """Restore the ``statusLine`` captured in ``snapshot`` -- if this run still owns it.
+
+    Best-effort teardown: if the file is no longer readable, or another run has
+    installed over this one's value, the file is left as-is (with a warning) rather
+    than clobbered.
+
+    Args:
+        path: The client's JSON settings file.
+        snapshot: The snapshot returned by :func:`install`.
+    """
+    try:
+        settings = _load(path)
+    except SettingsUnreadableError:
+        log.warning(f"leaving {path} untouched: it is no longer readable JSON")
+        return
+    if settings.get("statusLine") != snapshot.installed:
+        return  # a later run owns the statusLine now -- don't clobber its value
+    if snapshot.had_status_line:
+        settings["statusLine"] = snapshot.previous
+    else:
+        settings.pop("statusLine", None)
+    _write(path, settings)
+
+
+def _load(path: Path) -> dict[str, object]:
+    if not path.exists():
+        return {}
+    try:
+        raw: object = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise SettingsUnreadableError(path) from error
+    if not isinstance(raw, dict):
+        raise SettingsUnreadableError(path)
+    return cast("dict[str, object]", raw)
+
+
+def _write(path: Path, settings: dict[str, object]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # Same-directory, per-process temp then atomic replace: a crash mid-write can't
+    # truncate the user's file, and a unique name avoids two runs colliding on it.
+    temporary = path.parent / f"{path.name}.{os.getpid()}.tmp"
+    temporary.write_text(json.dumps(settings, indent=2), encoding="utf-8")
+    temporary.replace(path)

generic_ml_wrapper/adapter/outbound/caller/vibe_cli_caller.py

@@ -0,0 +1,169 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Vibe (Mistral CLI) callers: launch vibe, optionally through a per-turn relay."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from generic_ml_wrapper.adapter.outbound.caller import context_file, vibe_config
+from generic_ml_wrapper.adapter.outbound.caller.context_opening import read_first_opening
+from generic_ml_wrapper.adapter.outbound.gateway import openai_chat
+from generic_ml_wrapper.adapter.outbound.gateway.relay import MeteringRelay
+from generic_ml_wrapper.application.port.outbound.cli_caller import CliCaller
+from generic_ml_wrapper.common.log import log
+
+if TYPE_CHECKING:
+    from generic_ml_wrapper.application.domain.model.run import RunContext
+    from generic_ml_wrapper.application.domain.service.interceptor_chain import InterceptorChain
+    from generic_ml_wrapper.application.port.outbound.per_turn_metering import PerTurnMeteringPort
+    from generic_ml_wrapper.application.port.outbound.transcript import TranscriptPort
+
+BINARY = "vibe"
+_VIBE_CONFIG = Path.home() / ".vibe" / "config.toml"
+
+
+class VibeCliCaller(CliCaller):
+    """Launch vibe (Mistral's CLI) for a run, routed through a per-turn metering relay.
+
+    vibe mints its own UUID session id and exposes no way to set one at launch, so
+    the wrapper cannot bind or resume a session by its own id — :meth:`can_resume`
+    is ``False`` — and it has no status-line hook. It takes its operating context via
+    a "read this file first" opening message (it has no system-prompt flag).
+    ``start_metering`` stands up a relay pointed at the active model's upstream and
+    writes a throwaway ``VIBE_HOME`` whose config repoints that provider at the relay;
+    if the relay cannot start (or the config can't be read), vibe launches unmetered.
+    """
+
+    def __init__(
+        self,
+        run: RunContext,
+        metering: PerTurnMeteringPort,
+        interceptors: InterceptorChain | None = None,
+        transcript: TranscriptPort | None = None,
+    ) -> None:
+        """Bind the caller to a run, its metering store, and the interceptor chain.
+
+        Args:
+            run: The run this caller will launch and meter.
+            metering: Where the relay records per-turn usage.
+            interceptors: The interceptor chain the relay applies to wire traffic.
+            transcript: Where the relay records each call's transcript, or ``None``.
+        """
+        super().__init__(run)
+        self._metering = metering
+        self._interceptors = interceptors
+        self._transcript = transcript
+        self._relay: MeteringRelay | None = None
+        self._vibe_home: str | None = None
+
+    def can_resume(self) -> bool:
+        """Vibe mints its own session id and cannot be told one at launch."""
+        return False
+
+    def can_meter_per_call(self) -> bool:
+        """This caller records per-turn usage via its metering relay."""
+        return True
+
+    def start_metering(self) -> None:
+        """Start the relay and write the throwaway VIBE_HOME pointed at it."""
+        try:
+            source_text = _VIBE_CONFIG.read_text(encoding="utf-8")
+        except OSError as error:
+            log.warning(f"cannot read {_VIBE_CONFIG} ({error}); launching vibe unmetered")
+            return
+        upstream = vibe_config.active_upstream(source_text)
+        if upstream is None:
+            log.warning("could not resolve vibe's active-model upstream; launching unmetered")
+            return
+        relay = MeteringRelay(
+            job=self.run.job,
+            session=self.run.session_id,
+            metering=self._metering,
+            client=self.run.client,
+            transcript=self._transcript,
+            upstream_base=upstream,
+            usage_reader=openai_chat.read_usage,
+            is_metered=_vibe_metered,
+            interceptors=self._interceptors,
+        )
+        try:
+            relay.start()
+        except OSError as error:
+            log.warning(f"metering relay failed to start ({error}); launching vibe unmetered")
+            return
+        self._relay = relay
+        home = Path(tempfile.mkdtemp(prefix="gmlw-vibe-"))
+        (home / "config.toml").write_text(
+            vibe_config.redirect(source_text, upstream, relay.base_url), encoding="utf-8"
+        )
+        self._vibe_home = str(home)
+
+    def end_metering(self) -> None:
+        """Stop the relay and remove the throwaway VIBE_HOME."""
+        if self._relay is not None:
+            self._relay.stop()
+            self._relay = None
+        if self._vibe_home is not None:
+            shutil.rmtree(self._vibe_home, ignore_errors=True)
+            self._vibe_home = None
+
+    def _provider_flags(self) -> list[str]:
+        # The throwaway VIBE_HOME has no trusted-folder record; trust the cwd for
+        # this invocation so vibe does not stop to prompt.
+        return [] if self._vibe_home is None else ["--trust"]
+
+    def command(self, opening: str | None = None) -> list[str]:
+        """Build the ``vibe`` command line for this run.
+
+        Args:
+            opening: The opening prompt to start the session on, or ``None``.
+
+        Returns:
+            The argv list to execute.
+        """
+        argv = [BINARY, *self._provider_flags()]
+        if opening is not None:
+            argv.append(opening)
+        return argv
+
+    def start_client(self) -> int:
+        """Launch vibe, blocking until it exits.
+
+        Injected context is written to a temporary file the agent is told to read
+        first, removed when the client exits.
+
+        Returns:
+            The client's exit code.
+        """
+        if self.run.context is not None and not self.run.resume:
+            path = context_file.write(self.run.job, self.run.session_id, self.run.context)
+            return self._run(self.command(read_first_opening(str(path), self.run.kickoff)))
+        return self._run(self.command(self.run.kickoff))
+
+    def _extra_env(self) -> dict[str, str]:
+        """Point vibe at the throwaway config home when the relay is running."""
+        return {} if self._vibe_home is None else {"VIBE_HOME": self._vibe_home}
+
+    def _run(self, argv: list[str]) -> int:
+        env = {
+            **os.environ,
+            **dict(self.run.env),
+            **self._extra_env(),
+            "GMLW_JOB": self.run.job,
+            "GMLW_SESSION": self.run.session_id,
+            "GMLW_CLIENT": self.run.client,
+        }
+        # Trusted argv from our resolved run; no shell. The program is PATH-resolved (BINARY).
+        completed = subprocess.run(argv, check=False, cwd=self.run.cwd, env=env)  # noqa: S603
+        return completed.returncode
+
+
+def _vibe_metered(method: str, path: str) -> bool:
+    """A metered vibe turn: ``POST`` to the Chat Completions endpoint."""
+    return method == "POST" and path.split("?", 1)[0].endswith("/chat/completions")

generic_ml_wrapper/adapter/outbound/caller/vibe_config.py

@@ -0,0 +1,128 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Bootstrap an isolated vibe config that routes the active model through a relay.
+
+The metering gateway copies the user's real ``~/.vibe/config.toml`` into a throwaway
+``VIBE_HOME`` and repoints one thing: the ``api_base`` of the provider its active
+model uses. Everything else — model definitions, prices, ``api_key_env_var``, tool
+permissions — is preserved, so the metered run behaves like the real one but its
+traffic detours through the local relay. The API key resolves from the OS keyring,
+which is independent of ``VIBE_HOME``, so no credential is copied.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from typing import cast
+from urllib.parse import urlsplit
+
+
+def active_upstream(source_text: str) -> str | None:
+    """Return the ``api_base`` the config's active model talks to, or ``None``.
+
+    Resolves ``active_model`` to its ``[[models]]`` entry (matched by ``name`` or
+    ``alias``), then that model's ``[[providers]]`` entry, and returns its
+    ``api_base`` (e.g. ``https://api.mistral.ai/v1``).
+
+    Args:
+        source_text: The contents of a vibe ``config.toml``.
+
+    Returns:
+        The active provider's ``api_base``, or ``None`` if it cannot be resolved.
+    """
+    try:
+        data = tomllib.loads(source_text)
+    except tomllib.TOMLDecodeError:
+        return None
+    active = data.get("active_model")
+    if not isinstance(active, str):
+        return None
+    provider_name = _provider_of(data.get("models"), active)
+    if provider_name is None:
+        return None
+    return _api_base_of(data.get("providers"), provider_name)
+
+
+def redirect(source_text: str, upstream: str, relay_base_url: str) -> str:
+    """Repoint ``upstream``'s host at the relay, keeping its path.
+
+    ``https://api.mistral.ai/v1`` becomes ``http://127.0.0.1:PORT/v1`` — vibe then
+    posts ``/v1/chat/completions`` to the relay, which forwards to the real host.
+
+    Args:
+        source_text: The contents of a vibe ``config.toml``.
+        upstream: The ``api_base`` to repoint (from :func:`active_upstream`).
+        relay_base_url: The relay's base URL (``http://127.0.0.1:PORT``).
+
+    Returns:
+        The config text with ``upstream`` replaced by the relay-pointed base URL, changed
+        only inside the active provider's ``[[providers]]`` table -- so the same URL in a
+        comment or in another provider is left alone. Unchanged if the active provider
+        cannot be resolved.
+    """
+    new_api_base = relay_base_url + urlsplit(upstream).path
+    provider = _active_provider_name(source_text)
+    if provider is None:
+        return source_text
+    return _repoint_provider(source_text, provider, f'"{upstream}"', f'"{new_api_base}"')
+
+
+def _active_provider_name(source_text: str) -> str | None:
+    try:
+        data = tomllib.loads(source_text)
+    except tomllib.TOMLDecodeError:
+        return None
+    active = data.get("active_model")
+    if not isinstance(active, str):
+        return None
+    return _provider_of(data.get("models"), active)
+
+
+def _repoint_provider(source_text: str, provider_name: str, old: str, new: str) -> str:
+    lines = source_text.splitlines(keepends=True)
+    index = 0
+    while index < len(lines):
+        if lines[index].strip() != "[[providers]]":
+            index += 1
+            continue
+        end = index + 1
+        name: str | None = None
+        api_line: int | None = None
+        while end < len(lines) and not lines[end].lstrip().startswith("["):
+            stripped = lines[end].strip()
+            if stripped.startswith("name") and "=" in stripped:
+                name = stripped.split("=", 1)[1].strip().strip('"')
+            elif stripped.startswith("api_base") and old in lines[end]:
+                api_line = end
+            end += 1
+        if name == provider_name and api_line is not None:
+            lines[api_line] = lines[api_line].replace(old, new, 1)
+            break
+        index = end
+    return "".join(lines)
+
+
+def _provider_of(models: object, active: str) -> str | None:
+    if not isinstance(models, list):
+        return None
+    for entry in cast("list[object]", models):
+        if not isinstance(entry, dict):
+            continue
+        model = cast("dict[str, object]", entry)
+        if model.get("name") == active or model.get("alias") == active:
+            provider = model.get("provider")
+            return provider if isinstance(provider, str) else None
+    return None
+
+
+def _api_base_of(providers: object, name: str) -> str | None:
+    if not isinstance(providers, list):
+        return None
+    for entry in cast("list[object]", providers):
+        if not isinstance(entry, dict):
+            continue
+        provider = cast("dict[str, object]", entry)
+        if provider.get("name") == name:
+            api_base = provider.get("api_base")
+            return api_base if isinstance(api_base, str) else None
+    return None

generic_ml_wrapper/adapter/outbound/credentials/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Credentials-store adapters."""

generic_ml_wrapper/adapter/outbound/credentials/filesystem_credentials_store.py

@@ -0,0 +1,130 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Filesystem ``CredentialsStorePort``: a ``0600`` ``credentials.toml`` we own."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import tomllib
+from pathlib import Path
+from typing import cast
+
+from generic_ml_wrapper.application.port.outbound.credentials_store import CredentialsStorePort
+
+_OWNER_READ_WRITE = 0o600
+
+
+class CredentialsUnreadableError(Exception):
+    """The credentials file exists but cannot be parsed as TOML.
+
+    Overwriting it would destroy every stored secret, so the run aborts instead.
+    """
+
+    def __init__(self, path: Path) -> None:
+        """Build the error with actionable guidance for ``path``."""
+        self.path = path
+        super().__init__(
+            f"{path} is not valid TOML.\n\n"
+            "It holds your stored credentials. Rewriting it would parse the corruption as\n"
+            "'no secrets' and destroy them all, so the run is aborted.\n\n"
+            "To fix: repair the TOML by hand, or move it aside\n"
+            f"  (mv {path} {path}.bak)  and re-run `gmlw creds set` to start fresh."
+        )
+
+
+class FilesystemCredentialsStore(CredentialsStorePort):
+    """Persist per-workflow credentials as ``[workflow]`` tables in one TOML file.
+
+    The file is written with owner-only permissions and is never committed; it lives
+    under ``~/.gmlw`` alongside the rest of the runtime state.
+    """
+
+    def __init__(self, path: Path) -> None:
+        """Bind the store to its file.
+
+        Args:
+            path: The ``credentials.toml`` file this store reads and writes.
+        """
+        self._path = path
+
+    def resolve(self, workflow: str) -> dict[str, str]:
+        """Return a workflow's credentials as an env-var-name to value mapping."""
+        table = self._load().get(workflow)
+        if not isinstance(table, dict):
+            return {}
+        return {
+            name: value
+            for name, value in cast("dict[str, object]", table).items()
+            if isinstance(value, str)
+        }
+
+    def set(self, workflow: str, name: str, value: str) -> None:
+        """Store one credential for a workflow, replacing any prior value.
+
+        Raises:
+            CredentialsUnreadableError: If the file exists but is corrupt; it is left
+                untouched rather than overwritten (which would destroy every secret).
+        """
+        data = self._load()
+        table = data.get(workflow)
+        entries = cast("dict[str, object]", table) if isinstance(table, dict) else {}
+        entries[name] = value
+        data[workflow] = entries
+        self._write(_dump(data))
+
+    def _write(self, text: str) -> None:
+        # Atomic + owner-only from creation: mkstemp makes the temp 0600, so after the
+        # replace the secrets file is 0600 with no world-readable window, and a crash
+        # mid-write can't corrupt it. replace swaps the path itself, so it never writes
+        # THROUGH a symlink the file might have been redirected to.
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        descriptor, temporary = tempfile.mkstemp(dir=self._path.parent, suffix=".tmp")
+        temporary_path = Path(temporary)
+        try:
+            with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+                handle.write(text)
+            temporary_path.replace(self._path)
+        except BaseException:
+            temporary_path.unlink()
+            raise
+        self._path.chmod(_OWNER_READ_WRITE)
+
+    def _load(self) -> dict[str, object]:
+        if not self._path.exists():
+            return {}
+        try:
+            with self._path.open("rb") as handle:
+                return tomllib.load(handle)
+        except (OSError, tomllib.TOMLDecodeError) as error:
+            raise CredentialsUnreadableError(self._path) from error
+
+
+def _dump(data: dict[str, object]) -> str:
+    """Serialize ``{workflow: {name: value}}`` as TOML tables of basic strings."""
+    blocks: list[str] = []
+    for workflow in sorted(data):
+        table = data[workflow]
+        if not isinstance(table, dict):
+            continue
+        entries = cast("dict[str, object]", table)
+        lines = [f"[{workflow}]"]
+        lines += [
+            f"{name} = {_basic_string(value)}"
+            for name, value in sorted(entries.items())
+            if isinstance(value, str)
+        ]
+        if len(lines) > 1:
+            blocks.append("\n".join(lines))
+    return "\n\n".join(blocks) + "\n" if blocks else ""
+
+
+def _basic_string(value: str) -> str:
+    escaped = (
+        value.replace("\\", "\\\\")
+        .replace('"', '\\"')
+        .replace("\n", "\\n")
+        .replace("\t", "\\t")
+        .replace("\r", "\\r")
+    )
+    return f'"{escaped}"'

generic_ml_wrapper/adapter/outbound/gateway/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Metering-gateway adapters (local relays that read per-turn usage on the wire)."""