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

generic_ml_wrapper/adapter/outbound/caller/claude_cli_caller.py

@@ -0,0 +1,158 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""``ClaudeCliCaller``: launch Claude Code, install the status line, meter the run."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from generic_ml_wrapper.adapter.outbound.caller import context_file, status_line_config
+from generic_ml_wrapper.adapter.outbound.caller.status_line_config import StatusLineSnapshot
+from generic_ml_wrapper.adapter.outbound.gateway.relay import MeteringRelay
+from generic_ml_wrapper.application.domain.model.run import RunContext
+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.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 = "claude"
+_SETTINGS = Path.home() / ".claude" / "settings.json"
+_STATUSLINE: dict[str, object] = {
+    "type": "command",
+    "command": status_line_config.statusline_command(),
+    "padding": 0,
+}
+
+
+class ClaudeCliCaller(CliCaller):
+    """Launch Claude Code for a run, metered via the status line and a local relay.
+
+    ``start_metering`` points Claude Code's ``statusLine`` at ``gmlw statusline`` and
+    stands up a :class:`MeteringRelay`, pointing Claude at it via ``ANTHROPIC_BASE_URL``
+    to record per-turn tokens; ``end_metering`` tears both down. If the relay cannot
+    start, the launch falls back to unmetered (status line only). A new session may
+    carry injected ``context`` (Claude's system prompt), an opening ``kickoff``, and a
+    ``cwd``; the run's identity is exported as ``GMLW_JOB`` / ``GMLW_SESSION`` /
+    ``GMLW_CLIENT``.
+    """
+
+    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._snapshot: StatusLineSnapshot | None = None
+        self._relay: MeteringRelay | None = None
+
+    def can_deliver_statusline(self) -> bool:
+        """Claude Code hosts a command-backed status line the wrapper renders into."""
+        return True
+
+    def can_meter_per_call(self) -> bool:
+        """This caller records per-turn usage via its metering relay."""
+        return True
+
+    def start_metering(self) -> None:
+        """Install the status line and start the metering relay for this session."""
+        if self.can_deliver_statusline():
+            self._snapshot = status_line_config.install(_SETTINGS, _STATUSLINE)
+        relay = MeteringRelay(
+            job=self.run.job,
+            session=self.run.session_id,
+            metering=self._metering,
+            client=self.run.client,
+            transcript=self._transcript,
+            interceptors=self._interceptors,
+        )
+        try:
+            relay.start()
+        except OSError as error:
+            log.warning(f"metering relay failed to start ({error}); launching unmetered")
+            return
+        self._relay = relay
+
+    def end_metering(self) -> None:
+        """Stop the metering relay and restore the status line."""
+        if self._relay is not None:
+            self._relay.stop()
+            self._relay = None
+        if self._snapshot is not None:
+            status_line_config.restore(_SETTINGS, self._snapshot)
+
+    def command(self, context_file: str | None = None) -> list[str]:
+        """Build the ``claude`` command line for this run.
+
+        Args:
+            context_file: A file whose contents to append to the system prompt, or
+                ``None`` (only used for a new session).
+
+        Returns:
+            The argv list to execute.
+        """
+        run = self.run
+        if run.resume:
+            argv = [BINARY, "--resume", run.uuid or run.session_id]
+        else:
+            argv = [BINARY, "-n", run.session_id]
+            if run.uuid is not None:
+                argv += ["--session-id", run.uuid]
+            if context_file is not None:
+                argv += ["--append-system-prompt-file", context_file]
+        if run.kickoff is not None:
+            argv.append(run.kickoff)
+        return argv
+
+    def start_client(self) -> int:
+        """Launch Claude, blocking until it exits.
+
+        Injected context (new sessions only) is persisted per session and passed via
+        ``--append-system-prompt-file`` -- a durable provenance artifact.
+
+        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(str(path)))
+        return self._run(self.command())
+
+    def _extra_env(self) -> dict[str, str]:
+        """Point Claude at the relay when it is running.
+
+        Returns:
+            ``ANTHROPIC_BASE_URL`` for the relay, or empty when it isn't running.
+        """
+        return {} if self._relay is None else {"ANTHROPIC_BASE_URL": self._relay.base_url}
+
+    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

generic_ml_wrapper/adapter/outbound/caller/codex_cli_caller.py

@@ -0,0 +1,165 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Codex callers: launch codex, optionally through a per-turn metering relay."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from typing import TYPE_CHECKING
+
+from generic_ml_wrapper.adapter.outbound.caller import context_file
+from generic_ml_wrapper.adapter.outbound.caller.context_opening import read_first_opening
+from generic_ml_wrapper.adapter.outbound.gateway import openai_responses
+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 = "codex"
+# ChatGPT-sign-in upstream (the verified default). API-key mode would target
+# api.openai.com with a /v1 prefix; a config-driven option is a later follow-up.
+_UPSTREAM = "https://chatgpt.com"
+_UPSTREAM_PREFIX = "/backend-api/codex"
+
+
+class CodexCliCaller(CliCaller):
+    """Launch codex for a run, routed through a per-turn metering relay.
+
+    Codex has no status-line hook, so none is installed. 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 ChatGPT-Codex backend
+    and ``_provider_flags`` adds the ``model_providers`` overrides pointing codex at
+    it; if the relay cannot start, codex 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
+
+    def can_resume(self) -> bool:
+        """Codex mints a fresh conversation and exposes no session id to resume.
+
+        Resuming would require scanning ``~/.codex`` for the local rollout, which
+        the wrapper deliberately does not do; ``--resume-latest`` is refused for
+        codex rather than silently starting a new session.
+        """
+        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 Codex metering relay for this session."""
+        relay = MeteringRelay(
+            job=self.run.job,
+            session=self.run.session_id,
+            metering=self._metering,
+            client=self.run.client,
+            transcript=self._transcript,
+            upstream_base=_UPSTREAM,
+            path_map=_codex_path_map,
+            usage_reader=openai_responses.read_usage,
+            is_metered=_codex_metered,
+            interceptors=self._interceptors,
+        )
+        try:
+            relay.start()
+        except OSError as error:
+            log.warning(f"metering relay failed to start ({error}); launching codex unmetered")
+            return
+        self._relay = relay
+
+    def end_metering(self) -> None:
+        """Stop the metering relay."""
+        if self._relay is not None:
+            self._relay.stop()
+            self._relay = None
+
+    def _provider_flags(self) -> list[str]:
+        if self._relay is None:
+            return []
+        base_url = f"{self._relay.base_url}/v1"
+        return [
+            "-c",
+            'model_providers.gml.name="gmlcache"',
+            "-c",
+            f'model_providers.gml.base_url="{base_url}"',
+            "-c",
+            'model_providers.gml.wire_api="responses"',
+            "-c",
+            "model_providers.gml.requires_openai_auth=true",
+            "-c",
+            'model_provider="gml"',
+        ]
+
+    def command(self, opening: str | None = None) -> list[str]:
+        """Build the ``codex`` command line for this run.
+
+        Args:
+            opening: The opening message 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 codex, blocking until it 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 _run(self, argv: list[str]) -> int:
+        env = {
+            **os.environ,
+            **dict(self.run.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 _codex_path_map(path: str) -> str:
+    """Map codex's ``/v1/x`` (its base_url ends ``/v1``) to the backend prefix."""
+    sub = path[len("/v1") :] if path.startswith("/v1") else path
+    return _UPSTREAM_PREFIX + sub
+
+
+def _codex_metered(method: str, path: str) -> bool:
+    """A metered codex turn: ``POST`` to the Responses endpoint."""
+    return method == "POST" and path.split("?", 1)[0].endswith("/responses")

generic_ml_wrapper/adapter/outbound/caller/context_file.py

@@ -0,0 +1,44 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Persist a session's compiled context to a durable, inspectable file.
+
+The exact operating context a session launches with (profile + rules + workflow) is
+written per session to ``~/.gmlw/contexts/<job>/<session>.context.md`` and handed to
+the client from there -- a durable provenance artifact you can inspect after the run,
+instead of a temp file discarded the moment the client exits.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+from generic_ml_wrapper.common import paths
+
+
+def write(job: str, session: str, context: str) -> Path:
+    """Write ``session``'s compiled ``context`` durably, returning the file path.
+
+    Args:
+        job: The job the session belongs to.
+        session: The session id (``<job>_NNN``).
+        context: The compiled operating context to persist and inject.
+
+    Returns:
+        The path to the written ``<session>.context.md`` file.
+    """
+    directory = paths.CONTEXTS / job
+    directory.mkdir(parents=True, exist_ok=True)
+    path = directory / f"{session}.context.md"
+    # Atomic: same-dir temp + replace, so a crash mid-write can't leave a torn artifact.
+    descriptor, temporary = tempfile.mkstemp(dir=directory, suffix=".tmp")
+    temporary_path = Path(temporary)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(context)
+        temporary_path.replace(path)
+    except BaseException:
+        temporary_path.unlink()
+        raise
+    return path

generic_ml_wrapper/adapter/outbound/caller/context_opening.py

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Build the opening message that points a fileless-prompt agent at its context.
+
+Clients without a system-prompt flag (cursor-agent, codex) receive their compiled
+operating context by being told, in the opening message, to read a file first.
+"""
+
+from __future__ import annotations
+
+
+def read_first_opening(context_path: str, kickoff: str | None = None) -> str:
+    """Build an opening message telling the agent to read its context file first.
+
+    Args:
+        context_path: The path to the compiled operating-context file.
+        kickoff: An opening user message to append after the instruction, or ``None``.
+
+    Returns:
+        The opening message.
+    """
+    preamble = (
+        f"Your operating context for this session is in the file:\n{context_path}\n"
+        "Read that file in full FIRST — it is your instructions, profile, rules, and "
+        "the workflow steps — then proceed as it says."
+    )
+    return f"{preamble}\n\n{kickoff}" if kickoff else preamble

generic_ml_wrapper/adapter/outbound/caller/cursor_cli_caller.py

@@ -0,0 +1,98 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""``CursorCliCaller``: launch cursor-agent and install its status line (no metering)."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+from generic_ml_wrapper.adapter.outbound.caller import context_file, status_line_config
+from generic_ml_wrapper.adapter.outbound.caller.context_opening import read_first_opening
+from generic_ml_wrapper.adapter.outbound.caller.status_line_config import StatusLineSnapshot
+from generic_ml_wrapper.application.domain.model.run import RunContext
+from generic_ml_wrapper.application.port.outbound.cli_caller import CliCaller
+
+BINARY = "cursor-agent"
+_CONFIG = Path.home() / ".cursor" / "cli-config.json"
+_STATUSLINE: dict[str, object] = {
+    "type": "command",
+    "command": status_line_config.statusline_command(),
+    "updateIntervalMs": 2000,
+    "timeoutMs": 5000,
+}
+
+
+class CursorCliCaller(CliCaller):
+    """Launch cursor-agent for a run, with the wrapper's status line, without metering.
+
+    cursor-agent hosts a command-backed status line (``~/.cursor/cli-config.json``),
+    so ``start_metering`` points it at ``gmlw statusline`` and ``end_metering``
+    restores the prior setting. Its ``--resume <name>`` both creates and resumes a
+    session. It has no system-prompt flag, so injected context is written to a file
+    the agent is told to read first. This light client does not meter usage.
+    """
+
+    def __init__(self, run: RunContext) -> None:
+        """Bind the caller to a run.
+
+        Args:
+            run: The run this caller will launch.
+        """
+        super().__init__(run)
+        self._snapshot: StatusLineSnapshot | None = None
+
+    def can_deliver_statusline(self) -> bool:
+        """cursor-agent hosts a command-backed status line the wrapper renders into."""
+        return True
+
+    def start_metering(self) -> None:
+        """Point cursor-agent's status line at ``gmlw statusline`` for this session."""
+        if self.can_deliver_statusline():
+            self._snapshot = status_line_config.install(_CONFIG, _STATUSLINE)
+
+    def end_metering(self) -> None:
+        """Restore cursor-agent's previous status-line setting."""
+        if self._snapshot is not None:
+            status_line_config.restore(_CONFIG, self._snapshot)
+
+    def command(self, opening: str | None = None) -> list[str]:
+        """Build the ``cursor-agent`` command line for this run.
+
+        Args:
+            opening: The opening message to start the session on, or ``None``.
+
+        Returns:
+            The argv list to execute.
+        """
+        argv = [BINARY, "--resume", self.run.session_id]
+        if opening is not None:
+            argv.append(opening)
+        return argv
+
+    def start_client(self) -> int:
+        """Launch cursor-agent, blocking until it exits.
+
+        Injected context (new sessions only) 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 _run(self, argv: list[str]) -> int:
+        env = {
+            **os.environ,
+            **dict(self.run.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

generic_ml_wrapper/adapter/outbound/caller/default_provider.py

@@ -0,0 +1,79 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""``DefaultCliCallerProvider``: config overrides first, then built-in callers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from generic_ml_wrapper.adapter.outbound.caller.claude_cli_caller import ClaudeCliCaller
+from generic_ml_wrapper.adapter.outbound.caller.codex_cli_caller import CodexCliCaller
+from generic_ml_wrapper.adapter.outbound.caller.cursor_cli_caller import CursorCliCaller
+from generic_ml_wrapper.adapter.outbound.caller.loader import load_caller_class
+from generic_ml_wrapper.adapter.outbound.caller.vibe_cli_caller import VibeCliCaller
+from generic_ml_wrapper.application.port.outbound.cli_caller import CliCaller, CliCallerProvider
+
+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
+
+
+class UnsupportedClientError(ValueError):
+    """Raised when a run's client has no override and no built-in caller."""
+
+
+class DefaultCliCallerProvider(CliCallerProvider):
+    """Resolve a run's caller: a config override if present, else the built-in one."""
+
+    def __init__(
+        self,
+        overrides: dict[str, str] | None = None,
+        *,
+        metering: PerTurnMeteringPort,
+        transcript: TranscriptPort | None = None,
+        interceptors: InterceptorChain | None = None,
+    ) -> None:
+        """Bind the provider to its overrides, metering store, and interceptor chain.
+
+        Args:
+            overrides: A client-to-spec mapping (``"module:Class"``) from config; an
+                override is loaded in place of the built-in caller for that client.
+            metering: The per-turn store the built-in gateway callers record to. Every
+                built-in client except cursor routes through a relay that records here.
+            transcript: Where the relay records each call's transcript, or ``None``.
+            interceptors: The interceptor chain the relay applies to wire traffic.
+        """
+        self._overrides = overrides or {}
+        self._metering = metering
+        self._transcript = transcript
+        self._interceptors = interceptors
+
+    def for_run(self, run: RunContext) -> CliCaller:
+        """Return the caller for the run's client.
+
+        Args:
+            run: The run to launch.
+
+        Returns:
+            A caller bound to the run — an overridden one when configured, else the
+            built-in caller (every built-in but cursor routes through the relay).
+
+        Raises:
+            UnsupportedClientError: If the client has neither an override nor a
+                built-in caller.
+        """
+        spec = self._overrides.get(run.client)
+        if spec is not None:
+            return load_caller_class(spec)(run)
+        if run.client == "claude":
+            return ClaudeCliCaller(run, self._metering, self._interceptors, self._transcript)
+        if run.client == "cursor":
+            return CursorCliCaller(run)
+        if run.client == "codex":
+            return CodexCliCaller(run, self._metering, self._interceptors, self._transcript)
+        if run.client == "vibe":
+            return VibeCliCaller(run, self._metering, self._interceptors, self._transcript)
+        message = f"unsupported client: {run.client!r}"
+        raise UnsupportedClientError(message)

generic_ml_wrapper/adapter/outbound/caller/loader.py

@@ -0,0 +1,34 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Load an external ``CliCaller`` class from a config spec, at runtime."""
+
+from __future__ import annotations
+
+from generic_ml_wrapper.application.port.outbound.cli_caller import CliCaller
+from generic_ml_wrapper.common.spec_loader import SpecLoadError, load_class
+
+
+class CallerLoadError(ValueError):
+    """Raised when a caller spec cannot be resolved to a ``CliCaller`` subclass."""
+
+
+def load_caller_class(spec: str) -> type[CliCaller]:
+    """Resolve a ``"module:Class"`` or ``"/path/to/file.py:Class"`` spec to a class.
+
+    The spec lets a private metering caller be plugged in via config without ever
+    living in this repo.
+
+    Args:
+        spec: The import spec, ``"<module-or-path>:<ClassName>"``.
+
+    Returns:
+        The referenced ``CliCaller`` subclass.
+
+    Raises:
+        CallerLoadError: If the spec is malformed, cannot be imported, or does not
+            name a ``CliCaller`` subclass.
+    """
+    try:
+        return load_class(spec, CliCaller)
+    except SpecLoadError as error:
+        raise CallerLoadError(str(error)) from error