alissa-tools-github-revloop 0.26.0__tar.gz → 0.28.0__tar.gz

{alissa_tools_github_revloop-0.26.0/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-revloop
-Version: 0.26.0
+Version: 0.28.0
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_revloop-0.26.0 → alissa_tools_github_revloop-0.28.0}/src/main/alissa/tools/github/revloop/__main__.py

@@ -11,6 +11,7 @@ from pathlib import Path
 from .config import (
     HUB_ADD,
     HUB_SKIP,
+    LOOP_EVENTS_ENV,
     ON_MISSING_CREATE,
     ON_MISSING_SKIP,
     ON_MISSING_SPAWN,
@@ -200,6 +201,31 @@ def build_parser() -> argparse.ArgumentParser:
         f"invisible to this daemon. Overridden by ${TASK_LIST_BOW_ENV}",
     )
 
+    events = over.add_mutually_exclusive_group()
+    events.add_argument(
+        "--loop-events",
+        dest="loop_events_enabled",
+        action="store_true",
+        default=None,
+        help="push loop telemetry (rounds spawned, verdicts, cap-outs, "
+        "stability holds, stalls, checks holds) to Studio's POST "
+        "/v1/loop-events once per poll pass — best-effort, never fatal. "
+        f"Overridden by ${LOOP_EVENTS_ENV}",
+    )
+    events.add_argument(
+        "--no-loop-events",
+        dest="loop_events_enabled",
+        action="store_false",
+        help="do not push loop telemetry even if the config enables it",
+    )
+    over.add_argument(
+        "--alissa-endpoint",
+        dest="alissa_endpoint",
+        metavar="URL",
+        help="the Alissa API base the loop-events client posts to "
+        "(default: https://api.alissa.app)",
+    )
+
     dry = over.add_mutually_exclusive_group()
     dry.add_argument(
         "--dry-run",
@@ -242,6 +268,8 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "review_task_miss_ttl_polls": args.review_task_miss_ttl_polls,
         "task_list_self_scope": args.task_list_self_scope,
         "task_list_bow_id": args.task_list_bow_id,
+        "loop_events_enabled": args.loop_events_enabled,
+        "alissa_endpoint": args.alissa_endpoint,
         "dry_run": args.dry_run,
     }
 

alissa_tools_github_revloop-0.28.0/src/main/alissa/tools/github/revloop/alissa_client.py

@@ -0,0 +1,191 @@
+"""Alissa REST access — the one write loop telemetry needs (issue #112).
+
+This is the SECOND Alissa adapter in the package, and the split is deliberate.
+`alissa.py` shells out to the `alissa` CLI, which is the daemon's established
+Alissa idiom for everything it does today (the review-task search, the tmux
+queue, the CR6 envelope reads). Loop telemetry needs a thing that idiom cannot
+supply: the CLI has no loop-events command, and it cannot attach the actor
+identity `POST /v1/loop-events` keys its rows by — the API stores events under
+the token's principal user, which is exactly the credential this daemon's
+`ALISSA_API_TOKEN` already carries.
+
+So the one write goes over the REST API directly, in the shape devloop's
+`alissa_client.py` adopted (PR #91 there): stdlib `urllib` only — the
+distribution ships no third-party runtime dependency and this must not be the
+change that adds one — a bearer token from the environment, bounded timeouts,
+and errors classified into a small taxonomy instead of leaking raw urllib
+exceptions. The CLI adapter stays untouched for everything else.
+
+The caller here is a BEST-EFFORT emitter (`loop_events`): its answer to every
+bucket is the same — warn once and let the pass complete — so the taxonomy
+exists for the log line, which should say "your token is wrong" (permanent,
+operator-fixable) differently from "the API blinked".
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import urllib.error
+import urllib.request
+
+log = logging.getLogger(__name__)
+
+DEFAULT_ENDPOINT = "https://api.alissa.app"
+
+# The env var the `alissa` CLI itself reads, so a daemon whose CLI is already
+# authenticated needs no second secret.
+ENV_TOKEN = "ALISSA_API_TOKEN"
+
+# The ingest cap: POST /v1/loop-events takes 1-200 events per call. The
+# EMITTER splits batches at this bound; the client refuses an oversized one
+# rather than silently posting a request the API will 400.
+MAX_EVENTS_PER_POST = 200
+
+
+class _RefuseRedirects(urllib.request.HTTPRedirectHandler):
+    """Refuse every redirect instead of following it (PR #113 round 1).
+
+    The default handler copies the request's headers — `Authorization`
+    included — onto the redirected request, ACROSS HOSTS, so a 30x from
+    whatever `alissa_endpoint` names would hand the bearer token to the
+    redirect target (and 301/302/303 would downgrade the POST to a GET that
+    ingests nothing while reading as success). A redirected ingest cannot
+    succeed anyway, so refusal beats strip-and-follow: returning None makes
+    urllib raise the 30x as an HTTPError, which the taxonomy reports like any
+    other unexpected status.
+    """
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+# One opener for the module: default handlers with only the redirect
+# behaviour replaced, built once because handler construction is not free
+# and every client shares the same policy.
+_opener = urllib.request.build_opener(_RefuseRedirects())
+
+
+class AlissaError(Exception):
+    """Base of the taxonomy. `status` is 0 for a transport failure (there was
+    no HTTP response to carry one)."""
+
+    def __init__(self, status: int, detail: object, code: "str | None" = None):
+        super().__init__(f"HTTP {status}: {detail}" if status else str(detail))
+        self.status = status
+        self.detail = detail
+        self.code = code
+
+
+class AlissaAuthError(AlissaError):
+    """401/403, or no token at all. Permanent and operator-fixable — retrying
+    it every pass only writes the same warning again."""
+
+
+class AlissaTransient(AlissaError):
+    """408/429/5xx and every transport failure (DNS, refused, timeout). The
+    'the API blinked' bucket — re-emission next pass is the retry, and the
+    deterministic dedupe keys are what make it harmless."""
+
+
+class AlissaClient:
+    """The one write, with the transport hidden behind the taxonomy.
+
+    Reads `ALISSA_API_TOKEN` from the environment; `base` defaults to the
+    public API. Both are constructor arguments so a test never needs the
+    network and an operator can point a daemon at another deployment
+    (`alissa_endpoint` in the config)."""
+
+    def __init__(
+        self,
+        token: "str | None" = None,
+        base: "str | None" = None,
+        *,
+        timeout: int = 30,
+    ):
+        self.base = (base or DEFAULT_ENDPOINT).rstrip("/")
+        self._token = token if token is not None else os.environ.get(ENV_TOKEN)
+        self._timeout = timeout
+
+    def _request(self, path: str, payload: dict) -> object:
+        """One POST. Every failure leaves as a taxonomy exception — the caller
+        never sees a raw urllib error or an HTTP status."""
+        if not self._token:
+            # No token at all is an auth condition, not a transport one: the
+            # operator must set the env var. Fail the way a 401 would, so the
+            # emitter's warning reads as permanent rather than transient.
+            raise AlissaAuthError(0, f"{ENV_TOKEN} is not set")
+
+        req = urllib.request.Request(
+            f"{self.base}{path}",
+            method="POST",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self._token}",
+            },
+        )
+        try:
+            with _opener.open(req, timeout=self._timeout) as resp:
+                raw = resp.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:
+            raise self._classify(exc) from None
+        except urllib.error.URLError as exc:
+            raise AlissaTransient(0, str(exc.reason)) from None
+        except (TimeoutError, OSError) as exc:  # pragma: no cover - defence
+            # A socket timeout on the READ does not arrive as URLError.
+            raise AlissaTransient(0, str(exc)) from None
+        try:
+            return json.loads(raw) if raw.strip() else {}
+        except json.JSONDecodeError as exc:
+            # A 2xx that is not JSON is a contract violation, not a retry
+            # signal -- but it must not escape as a bare ValueError either,
+            # because the emitter catches AlissaError and nothing else.
+            raise AlissaError(200, f"response was not JSON ({exc})") from None
+
+    @staticmethod
+    def _classify(exc: "urllib.error.HTTPError") -> AlissaError:
+        """Map an HTTP error onto the taxonomy. The API sends JSON error
+        bodies (`{"error": CODE, "message": ...}`); the code rides along when
+        present, but classification keys on the STATUS — codes are advisory,
+        statuses are the contract."""
+        detail: object = exc.read().decode("utf-8", "replace")
+        code: "str | None" = None
+        try:
+            parsed = json.loads(detail)  # type: ignore[arg-type]
+        except (json.JSONDecodeError, TypeError):
+            parsed = None
+        if isinstance(parsed, dict):
+            detail = parsed
+            raw_code = parsed.get("error")
+            code = raw_code if isinstance(raw_code, str) else None
+
+        status = exc.code
+        if status in (401, 403):
+            return AlissaAuthError(status, detail, code)
+        if status in (408, 429) or 500 <= status <= 599:
+            return AlissaTransient(status, detail, code)
+        return AlissaError(status, detail, code)
+
+    def post_loop_events(self, events: "list[dict]") -> dict:
+        """Ingest one batch of loop events (`POST /v1/loop-events`).
+
+        The API is idempotent on `(user, dedupeKey)`, so re-posting a batch —
+        which is exactly what the emitter does after a failed pass — lands as
+        silent duplicates, never as errors or overwrites. Returns the API's
+        `{"accepted": N, "duplicates": M}` payload (empty dict when the body
+        was empty), for the caller's debug line.
+
+        An oversized batch is refused HERE, loudly: the API fails the whole
+        call at >200 events, and the emitter owns the splitting, so reaching
+        this guard is a code defect rather than an operational condition.
+        """
+        if len(events) > MAX_EVENTS_PER_POST:
+            raise ValueError(
+                f"post_loop_events takes at most {MAX_EVENTS_PER_POST} events "
+                f"per call, got {len(events)} — the emitter must split"
+            )
+        payload = self._request("/v1/loop-events", {"events": events})
+        return payload if isinstance(payload, dict) else {}

{alissa_tools_github_revloop-0.26.0 → alissa_tools_github_revloop-0.28.0}/src/main/alissa/tools/github/revloop/config.py

@@ -6,12 +6,15 @@ Settings come from three layers, later winning over earlier:
 2. a JSON config file (see `resolve_config_path`)
 3. CLI arguments
 
-`task_list_bow_id` adds a fourth above them all — the environment
-(`ALISSA_REVIEW_TASK_BOW`, see `env_task_list_bow_id`). It is the only key that
-does, and the reason is that it is the only one a second entry point needs:
-`alissa-pr-review` builds its own `Alissa` client with no config file and no
-argv of the daemon's, so an id that lives only in the file or the flags reaches
-the poll loop and silently misses that call site.
+Two keys add a fourth layer above them all — the environment. `task_list_bow_id`
+(`ALISSA_REVIEW_TASK_BOW`, see `env_task_list_bow_id`) has it because it is the
+one key a second entry point needs: `alissa-pr-review` builds its own `Alissa`
+client with no config file and no argv of the daemon's, so an id that lives only
+in the file or the flags reaches the poll loop and silently misses that call
+site. `loop_events_enabled` (`ALISSA_REV_LOOP_EVENTS_ENABLED`, see
+`env_loop_events_enabled`) has it because a container deployment toggles
+telemetry with one variable and no config-file edit (issue #112); the env wins
+over both other layers so the two env-backed keys share one precedence story.
 
 `workspace_root` is deliberately **not** a config key — it is a property of the
 running process, not of the settings. That lets one config file drive several
@@ -28,6 +31,7 @@ import re
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Mapping
+from urllib.parse import urlsplit
 
 # A POSIX-ish environment variable name -- what `reviewer_token_env` must be.
 _ENV_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
@@ -147,6 +151,8 @@ CONFIG_KEYS = (
     "review_task_miss_ttl_polls",
     "task_list_self_scope",
     "task_list_bow_id",
+    "loop_events_enabled",
+    "alissa_endpoint",
     "dry_run",
 )
 
@@ -156,6 +162,81 @@ CONFIG_KEYS = (
 TASK_LIST_BOW_ENV = "ALISSA_REVIEW_TASK_BOW"
 
 
+# The environment variable toggling loop telemetry (issue #112). Like
+# TASK_LIST_BOW_ENV it outranks both the config file and the CLI flag — see the
+# module docstring for the shared precedence story.
+LOOP_EVENTS_ENV = "ALISSA_REV_LOOP_EVENTS_ENABLED"
+
+# The default Studio API base the loop-events client posts to. Mirrors
+# alissa_client.DEFAULT_ENDPOINT (a test pins the two together); defined here
+# too so config stays importable without the client module.
+DEFAULT_ALISSA_ENDPOINT = "https://api.alissa.app"
+
+# The boolean spellings the env layer accepts, matching the container
+# renderer's contract for its other boolean (ALISSA_TASK_LIST_SELF_SCOPE):
+# anything else is REFUSED rather than read as false, because a silently-false
+# typo is indistinguishable from the default it was trying to change.
+_ENV_TRUE = frozenset({"1", "true", "yes", "on"})
+_ENV_FALSE = frozenset({"0", "false", "no", "off"})
+
+# Hosts a cleartext `alissa_endpoint` is allowed to name. The loop-events
+# client sends a bearer token with every POST, so a non-https endpoint puts
+# that token on the wire — refused at load, except toward the machine itself
+# (a local stub or port-forward, which is how the client is tested against a
+# fake ingest).
+_LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+
+def _validate_alissa_endpoint(endpoint: str) -> str:
+    """`endpoint`, or a ValueError naming why it cannot carry a credential.
+
+    https is the rule; http is allowed only toward loopback. Anything else —
+    a bare host, another scheme, an unparsable value — is refused at load,
+    where the operator reads `config error`, rather than discovered as a
+    token on a cleartext hop (PR #113 round 1, minor).
+    """
+    parts = urlsplit(endpoint)
+    # A host is required on BOTH branches (PR #113 round 2, nit): a bare
+    # "https://" parses with the right scheme and no host, and would then
+    # fail on the wire as a per-pass transient WARN — the exact symptom this
+    # load-time check exists to prevent.
+    if parts.scheme == "https" and parts.hostname:
+        return endpoint
+    if parts.scheme == "http" and parts.hostname in _LOOPBACK_HOSTS:
+        return endpoint
+    raise ValueError(
+        f"alissa_endpoint must be an https:// URL with a host (or http:// "
+        f"toward loopback — localhost, 127.0.0.1, ::1 — for a local stub): "
+        f"the loop-events client sends a bearer token with every request, "
+        f"and a cleartext endpoint puts it on the wire. Got {endpoint!r}"
+    )
+
+
+def env_loop_events_enabled(
+    environ: "Mapping[str, str] | None" = None,
+) -> "bool | None":
+    """The loop-events toggle from the environment, or None when unset.
+
+    None and empty are the SAME answer — an exported-but-empty variable is how
+    a container renders "unset" (the Dockerfile bakes empty ENV defaults), and
+    it must fall through to the file/CLI layers rather than read as false. A
+    non-boolean spelling raises: the startup phase turns a ValueError into
+    `config error` + exit 2, which is where a typo belongs.
+    """
+    raw = (os.environ if environ is None else environ).get(LOOP_EVENTS_ENV)
+    value = (raw or "").strip().lower()
+    if not value:
+        return None
+    if value in _ENV_TRUE:
+        return True
+    if value in _ENV_FALSE:
+        return False
+    raise ValueError(
+        f"{LOOP_EVENTS_ENV} must be a boolean "
+        f"(1/0, true/false, yes/no, on/off), got {raw!r}"
+    )
+
+
 def env_task_list_bow_id(environ: "Mapping[str, str] | None" = None) -> "str | None":
     """The review BOW id from the environment, or None when it is not set.
 
@@ -496,6 +577,20 @@ class Config:
     # get the id wrong (a repo's `autodev:` feed BOW; a `mirrorInstanceId`).
     task_list_bow_id: str | None = None
 
+    # Whether the loop pushes its telemetry — rounds spawned, verdicts posted,
+    # cap-outs, stability holds, stalls, checks holds, grants, reaps — to
+    # Studio's `POST /v1/loop-events` once per poll pass (issue #112). OFF by
+    # default: telemetry is an outbound write to an external service, and an
+    # existing deployment must not start posting because it upgraded. Toggled
+    # by the env var LOOP_EVENTS_ENV above the file and the CLI. Best-effort
+    # when on: a failed push is one WARN and the pass completes.
+    loop_events_enabled: bool = False
+
+    # The Alissa/Studio API base the loop-events client posts to. One knob so
+    # a staging deployment can point telemetry somewhere else; everything else
+    # about the client (its bearer token) comes from the environment.
+    alissa_endpoint: str = DEFAULT_ALISSA_ENDPOINT
+
     dry_run: bool = False
 
     def __post_init__(self) -> None:
@@ -603,6 +698,26 @@ class Config:
         # takes and answers with nobody's tasks.
         bow_id = (bow_id or "").strip() or None
 
+        # The loop-events toggle's env layer, applied after the CLI overrides
+        # like the BOW id's above and for the same reason: the variable is how
+        # a container flips telemetry without editing a file on its volume.
+        env_events = env_loop_events_enabled(environ)
+        if env_events is not None:
+            raw["loop_events_enabled"] = env_events
+
+        endpoint = raw.get("alissa_endpoint", cls.alissa_endpoint)
+        if not isinstance(endpoint, str):
+            raise ValueError(
+                f"alissa_endpoint must be a URL string, got a "
+                f"{type(endpoint).__name__}"
+            )
+        # "" falls back to the default rather than building a client with an
+        # empty base — the same unset-means-default reading every optional
+        # string key here has.
+        endpoint = _validate_alissa_endpoint(
+            endpoint.strip() or cls.alissa_endpoint
+        )
+
         mode = raw.get("on_missing_review_task", ON_MISSING_SPAWN)
         if mode not in _MISSING_MODES:
             raise ValueError(
@@ -781,6 +896,8 @@ class Config:
             review_task_miss_ttl_polls=miss_ttl,
             task_list_self_scope=bool(raw.get("task_list_self_scope", False)),
             task_list_bow_id=bow_id,
+            loop_events_enabled=bool(raw.get("loop_events_enabled", False)),
+            alissa_endpoint=endpoint,
             dry_run=bool(raw.get("dry_run", False)),
         )
 

{alissa_tools_github_revloop-0.26.0 → alissa_tools_github_revloop-0.28.0}/src/main/alissa/tools/github/revloop/loop.py

@@ -56,6 +56,7 @@ from .ghclient import (
     countable_rounds,
     verdict_marker,
 )
+from .loop_events import LoopEventsEmitter, build_emitter
 from .proc import CommandError
 from .state import State
 
@@ -1523,10 +1524,11 @@ class StabilityNotice:
     The bookkeeping travels WITH the text rather than being written when the
     gate decides, because the two are not the same event: the gate runs above
     the CI gate and `_ensure_hub`, either of which can still refuse the round.
-    Writing `lifts` there would spend an operator's re-entry grant on a round
-    that was never queued -- and the grant is the only thing that can lift the
-    hold, so spending one silently is the one bookkeeping error this guard
-    cannot afford.
+    Writing `grants_seen` there would spend an operator's re-entry grant on a
+    round that was never queued -- and the grant is the only thing that can lift
+    the hold, so spending one silently is the one bookkeeping error this guard
+    cannot afford. The seed strengthens that: a gate-time write would also seed
+    a fresh episode's ledger off a round the reviewer never received.
     """
 
     text: str
@@ -1603,6 +1605,14 @@ class ReviewWatcher:
             task_list_bow_id=config.task_list_bow_id,
         )
         self.state = state or State(config.state_db)
+        # The Studio loop-telemetry push (issue #112), or None when the knob
+        # is off — the disabled default costs nothing: no client, no read, no
+        # log line. Built through the seam so tests swap in a fake client.
+        self._loop_events: LoopEventsEmitter | None = (
+            build_emitter(self.state, endpoint=config.alissa_endpoint)
+            if config.loop_events_enabled
+            else None
+        )
         # (repo, number, comment id) of every re-entry directive already
         # refused in this process -- see _log_ignored_ack.
         self._ignored_acks: set[tuple[str, int, int]] = set()
@@ -2319,9 +2329,19 @@ class ReviewWatcher:
         # capped out at 10, was granted +5, and went tests-only at round 13
         # would get five "grace" rounds and no hold -- the guard disarmed on
         # exactly the shape issue #105 cites (PR #106 round 1, minor). After the
-        # seed the predicate means what it should: only an ack posted AFTER this
-        # guard last spoke can lift the hold. Either way the write happens only
-        # once `_spawn` has actually queued the round.
+        # seed the predicate means what it should: only an ack THE LEDGER DID
+        # NOT ALREADY KNOW ABOUT can lift the hold. Deliberately not "posted
+        # after this guard last spoke", which claims more than the code
+        # enforces -- the seed reads `granted_rounds`, i.e. acks already
+        # collected into state, and `_collect_acks` runs from exactly two places
+        # (the cap-out branch and the `graced` branch here). So an ack posted
+        # while the loop is below its cap with no episode open is not recorded
+        # when it is posted; it is first discovered by a later `graced` scan and
+        # lifts the hold despite predating the notice. That is the doctrine
+        # working -- nothing consumed that grant, so it is genuinely unspent,
+        # and it errs toward extra rounds rather than a false hold (PR #106
+        # round 2, nit). Either way the write happens only once `_spawn` has
+        # actually queued the round.
         notice = STABILITY_NOTICE.format(
             base=base[:8],
             head=pr.head_sha[:8],
@@ -2885,7 +2905,9 @@ class ReviewWatcher:
             else f" — CI gate: the rollup at {judged[:8]} is {gate.state}, so the "
             f"{verdict} envelope did not post as an APPROVE"
         )
-        self.state.record_verdict_post(pr.full_name, pr.number, round_, url)
+        self.state.record_verdict_post(
+            pr.full_name, pr.number, round_, url, verdict=verdict
+        )
         log.info(
             "%s round %d closed: native %s review submitted as %s (%s)%s",
             pr.slug, round_, event, self.github.login, url or "no url", gate_note,
@@ -4799,8 +4821,34 @@ class ReviewWatcher:
         self._write_snapshot(
             results, reaped, duration_ms=int((time.monotonic() - started) * 1000)
         )
+        self._emit_loop_events()
         return results
 
+    def _emit_loop_events(self) -> None:
+        """Push this pass's loop telemetry to Studio, when enabled (issue
+        #112). Last thing in the pass, after the snapshot, so the batch sees
+        every ledger row the pass wrote.
+
+        Skipped in dry-run even when enabled: the ledger holds no new rows
+        from a dry-run pass, and while re-emitting old ones would be harmless
+        (idempotent keys), an outbound POST is still an act — and dry-run's
+        contract is decide-and-log only.
+
+        The emitter itself never raises for an API condition (one WARN, the
+        pass completes); the guard here is the same never-fatal promise held
+        against a code defect, so telemetry can never take down a poll.
+        """
+        if self._loop_events is None or self.config.dry_run:
+            return
+        try:
+            self._loop_events.emit_once()
+        except Exception as exc:
+            log.warning(
+                "loop-events: emitter failed unexpectedly (%s: %s) — "
+                "telemetry is best-effort, the pass completes",
+                type(exc).__name__, exc,
+            )
+
     def _note_ledger_unwritable(self) -> None:
         """Report a pass refused because the ledger cannot record it.