alissa-tools-github-devloop 0.8.13__tar.gz → 0.8.15__tar.gz

{alissa_tools_github_devloop-0.8.13/src/main/alissa_tools_github_devloop.egg-info → alissa_tools_github_devloop-0.8.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-devloop
-Version: 0.8.13
+Version: 0.8.15
 Summary: ALISSA-TOOLS-GITHUB-DEVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_devloop-0.8.13 → alissa_tools_github_devloop-0.8.15}/src/main/alissa/tools/github/devloop/__main__.py

@@ -282,6 +282,26 @@ def build_parser() -> argparse.ArgumentParser:
         "(two overlapping instances can then both spawn on one item)",
     )
 
+    loop_events = over.add_mutually_exclusive_group()
+    loop_events.add_argument(
+        "--loop-events",
+        dest="loop_events_enabled",
+        action="store_true",
+        default=None,
+        help="push one idempotent batch of loop events (spawns, defers, "
+        "cap-outs, stalls, hand-offs, reaps, escalations) per poll pass to "
+        "Studio's POST /v1/loop-events on the alissa endpoint — best-effort, "
+        "never fatal. ALISSA_DEV_LOOP_EVENTS_ENABLED (non-blank) overrides "
+        "even this flag",
+    )
+    loop_events.add_argument(
+        "--no-loop-events",
+        dest="loop_events_enabled",
+        action="store_false",
+        help="never push loop telemetry, even if the config enables it "
+        "(the default: the push is opt-in)",
+    )
+
     janitor = over.add_mutually_exclusive_group()
     janitor.add_argument(
         "--janitor",
@@ -386,6 +406,7 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "orphan_sweep_enabled": args.orphan_sweep_enabled,
         "orphan_grace_minutes": args.orphan_grace_minutes,
         "activity_claims_enabled": args.activity_claims_enabled,
+        "loop_events_enabled": args.loop_events_enabled,
         "janitor_enabled": args.janitor_enabled,
         "janitor_grace_minutes": args.janitor_grace_minutes,
         "janitor_interval_minutes": args.janitor_interval_minutes,
@@ -500,6 +521,13 @@ def log_effective_config(config: Config, login: str) -> None:
         config.cache_cap_mb,
         config.disk_warn_percent,
     )
+    log.info(
+        "loop_events=%s%s",
+        config.loop_events_enabled,
+        f" (one batch per pass → POST {config.alissa_endpoint}"
+        f"/v1/loop-events, best-effort)"
+        if config.loop_events_enabled else "",
+    )
     log.debug("hub_template: %s", config.hub_template)
     log.debug(
         "cache_paths: %s",

{alissa_tools_github_devloop-0.8.13 → alissa_tools_github_devloop-0.8.15}/src/main/alissa/tools/github/devloop/alissa_client.py

@@ -22,7 +22,12 @@ already authenticates — the same transport, endpoints and taxonomy orcloop's
 `urllib` only: the distribution ships no third-party runtime dependency, and
 this must not be the change that adds one.
 
-Endpoints, both verified against the live API:
+Since issue #101 the adapter also carries the daemon's ONE write —
+``POST /v1/loop-events`` (`post_loop_events`), the loop-telemetry push — over
+the same transport, token and taxonomy, so the daemon still reads and writes
+Alissa through a single REST idiom.
+
+Endpoints, the reads both verified against the live API:
 
 ``GET /v1/ping``
     ``{"pong", "timestamp", "userId", "actorId", "displayName"}`` — the
@@ -141,22 +146,32 @@ class AlissaClient:
         self._token = token if token is not None else os.environ.get(ENV_TOKEN)
         self._timeout = timeout
 
-    def _request(self, path: str) -> object:
-        """One GET. Every failure leaves as a taxonomy exception — the caller
-        never sees a raw urllib error or an HTTP status."""
+    def _request(
+        self, path: str, *, method: str = "GET", body: object = None
+    ) -> object:
+        """One call. Every failure leaves as a taxonomy exception — the caller
+        never sees a raw urllib error or an HTTP status. `body`, when given,
+        is JSON-serialised and sent with the matching Content-Type (the shape
+        every write on this API takes)."""
         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
             # boot path treats it as permanent rather than retrying forever.
             raise AlissaAuthError(0, f"{ENV_TOKEN} is not set")
 
+        headers = {
+            "Accept": "application/json",
+            "Authorization": f"Bearer {self._token}",
+        }
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
         req = urllib.request.Request(
             f"{self.base}{path}",
-            method="GET",
-            headers={
-                "Accept": "application/json",
-                "Authorization": f"Bearer {self._token}",
-            },
+            method=method,
+            data=data,
+            headers=headers,
         )
         try:
             with urllib.request.urlopen(req, timeout=self._timeout) as resp:
@@ -226,6 +241,27 @@ class AlissaClient:
             display_name=str(row.get("displayName") or ""),
         )
 
+    def post_loop_events(self, events: "list[dict]") -> "dict":
+        """Push one batch of loop-telemetry events (issue #101).
+
+        ``POST /v1/loop-events`` (fahera-mx/studio.alissa.app, `API.md` →
+        "Loop telemetry — ingest"): 1–200 events per call, idempotent on the
+        caller's `dedupeKey` — a repeated key is a silent duplicate, never an
+        error — and any shape error fails the WHOLE batch with a 400 naming
+        the offending index. The batch bound and the event shapes are the
+        CALLER's contract (`loop_events.py` derives and splits); this method
+        is just the transport, returning the server's
+        ``{"accepted": n, "duplicates": m}`` verbatim.
+
+        Failures leave as the taxonomy like every other call here. The one
+        caller is best-effort by design — it catches AlissaError, warns once
+        and moves on — so nothing extra is softened at this layer.
+        """
+        payload = self._request(
+            "/v1/loop-events", method="POST", body={"events": list(events)}
+        )
+        return payload if isinstance(payload, dict) else {}
+
     def list_bodies_of_work(self) -> "list[BodyOfWork]":
         """Every Body of Work this actor owns OR collaborates on — ONE call.
 

{alissa_tools_github_devloop-0.8.13 → alissa_tools_github_devloop-0.8.15}/src/main/alissa/tools/github/devloop/config.py

@@ -21,6 +21,8 @@ var > `--repos-source` > the config key. A BLANK env var means "not set" here
 (unlike ALISSA_DEV_REVIEWERS, where empty is a meaningful answer): an unset
 platform variable reference renders as the empty string, and that must fall
 through to the config rather than fail the daemon's boot on a mode of `''`.
+`loop_events_enabled` rides the same shape of rail through
+`ALISSA_DEV_LOOP_EVENTS_ENABLED`, with the same blank-falls-through rule.
 """
 
 from __future__ import annotations
@@ -88,6 +90,18 @@ ENV_REPOS_SOURCE = "ALISSA_DEV_REPOS_SOURCE"
 # `alissa_endpoint` so one deployment can point both daemons at one API.
 DEFAULT_ALISSA_ENDPOINT = "https://api.alissa.app"
 
+# The loop-telemetry rail (issue #101): `loop_events_enabled` ridden the way
+# ALISSA_DEV_REPOS_SOURCE rides repos_source — a NON-BLANK value here wins
+# over the CLI and the file alike, and a blank one falls through (an unset
+# platform variable reference renders as "", which must not decide anything).
+# Accepted spellings are 1/true/0/false, case-insensitive; anything else is a
+# config error at boot — a typo silently read as false would leave an operator
+# staring at a variable that does nothing.
+ENV_LOOP_EVENTS = "ALISSA_DEV_LOOP_EVENTS_ENABLED"
+
+_ENV_BOOL_TRUE = frozenset(("1", "true"))
+_ENV_BOOL_FALSE = frozenset(("0", "false"))
+
 # What an Alissa actor id looks like: a 32-character opaque handle of
 # lower-case letters and digits (`j5706fv7xe5jy1k5wdwzacab9s8axcd2`). Every id
 # the API mints has this shape, and `bow_owners` is checked against it so a
@@ -138,6 +152,7 @@ CONFIG_KEYS = (
     "orphan_sweep_enabled",
     "orphan_grace_minutes",
     "activity_claims_enabled",
+    "loop_events_enabled",
     "janitor_enabled",
     "janitor_grace_minutes",
     "janitor_interval_minutes",
@@ -499,6 +514,18 @@ class Config:
     # that would rather not pay the extra comments fetch.
     activity_claims_enabled: bool = True
 
+    # The loop-telemetry push (issue #101): at the end of each poll pass,
+    # POST one idempotent batch of the ledger-derived loop events — spawns,
+    # defers, cap-outs, stalls, hand-offs, reaps, escalations — to Studio's
+    # /v1/loop-events on `alissa_endpoint`, over the same REST client and
+    # token `bows` mode reads with. Best-effort and never fatal: a failed
+    # push warns once and the pass completes, and deterministic dedupe keys
+    # make re-emission harmless. Default OFF — the push writes to an external
+    # service on every pass, so it is the operator's to opt into; disabled,
+    # no request is ever made. ALISSA_DEV_LOOP_EVENTS_ENABLED (non-blank)
+    # wins over the CLI and the file, repos_source's rail exactly.
+    loop_events_enabled: bool = False
+
     # The workspace janitor (issue #74): the filesystem sibling of the session
     # reaper. Every worker session materializes a per-task workspace under its
     # repo's hub (a `TASK-<n>-<DESC>` worktree plus whatever its lane installs
@@ -759,6 +786,28 @@ class Config:
                 + (f" (from {ENV_REPOS_SOURCE})" if env_source else "")
             )
 
+        # The loop-telemetry rail, repos_source's shape exactly: a NON-BLANK
+        # ALISSA_DEV_LOOP_EVENTS_ENABLED wins over the CLI and the file, and
+        # blank falls through. Validated by NAME like the enums — a typo read
+        # as false would silently disable a push the operator asked for.
+        loop_events = bool(
+            raw.get("loop_events_enabled", cls.loop_events_enabled)
+        )
+        env_loop_events = (os.environ if environ is None else environ).get(
+            ENV_LOOP_EVENTS, ""
+        ).strip()
+        if env_loop_events:
+            lowered = env_loop_events.casefold()
+            if lowered in _ENV_BOOL_TRUE:
+                loop_events = True
+            elif lowered in _ENV_BOOL_FALSE:
+                loop_events = False
+            else:
+                raise ValueError(
+                    f"{ENV_LOOP_EVENTS} must be one of 1/true/0/false "
+                    f"(case-insensitive), got {env_loop_events!r}"
+                )
+
         bow_owners = normalize_bow_owners(raw.get("bow_owners", cls.bow_owners))
 
         refresh_polls = int(
@@ -961,6 +1010,7 @@ class Config:
             activity_claims_enabled=bool(
                 raw.get("activity_claims_enabled", cls.activity_claims_enabled)
             ),
+            loop_events_enabled=loop_events,
             janitor_enabled=bool(raw.get("janitor_enabled", cls.janitor_enabled)),
             janitor_grace_minutes=janitor_grace,
             janitor_interval_minutes=janitor_interval,

{alissa_tools_github_devloop-0.8.13 → alissa_tools_github_devloop-0.8.15}/src/main/alissa/tools/github/devloop/loop.py

@@ -405,7 +405,9 @@ from pathlib import Path
 from typing import Callable
 
 from . import janitor
+from . import loop_events as loop_events_mod
 from .alissa import Alissa
+from .alissa_client import AlissaClient
 from .bows import BowRepoSource
 from .config import (
     FOREIGN_IGNORE,
@@ -1916,6 +1918,18 @@ class Decision:
     session: str | None = None
     task_ref: str | None = None
     round: int | None = None
+    # True on a SPAWNED decision whose directive was a RESUME (issue or fix
+    # edge). Observational like the three above -- the loop-events emitter
+    # reads it to stamp `data.resume` on the spawn's telemetry event; nothing
+    # in the decision logic does.
+    resume: bool = False
+    # The coarse defer-reason token (loop_events.DEFER_*) on a decision that
+    # is a genuine DEFERRAL -- the external-claim hold and the stale-but-
+    # possibly-alive holds that ride Action.IN_FLIGHT. None on ordinary
+    # progress (a fresh attempt in flight is the loop working, not a defer)
+    # and on the capacity valve, whose Action.DEFERRED already says it.
+    # Observational like `resume`: only the loop-events emitter reads it.
+    defer_token: str | None = None
 
 
 def _oldest_first(found: list) -> list:
@@ -2410,6 +2424,7 @@ class DevWatcher:
         state: State | None = None,
         envelope_verdict: "Callable[[str, str, int], str | None] | None" = None,
         repo_source: "BowRepoSource | None" = None,
+        loop_events: "loop_events_mod.LoopEventEmitter | None" = None,
     ):
         self.config = config
         self.github = github or GitHub(config.developer_login)
@@ -2428,6 +2443,18 @@ class DevWatcher:
         self.repo_source = repo_source or (
             BowRepoSource(config) if config.repos_source == REPOS_BOWS else None
         )
+        # The loop-telemetry push (issue #101), or None when
+        # loop_events_enabled is off -- in which case no client is built and
+        # no request is ever made. Rides the same REST endpoint and token the
+        # bows feed reads (`alissa_endpoint`), and is injectable so a test
+        # never opens a socket.
+        self.loop_events = loop_events or (
+            loop_events_mod.LoopEventEmitter(
+                self.state, AlissaClient(base=config.alissa_endpoint)
+            )
+            if config.loop_events_enabled
+            else None
+        )
         # The reaper's name-slug -> (owner, repo) index (see `_anchor_repo`),
         # rebuilt only when the allowlist itself changes rather than per
         # session per sweep.
@@ -2615,6 +2642,7 @@ class DevWatcher:
                         f"not respawning",
                         attempts,
                         session=session_name(issue, attempts),
+                        defer_token=loop_events_mod.DEFER_IN_FLIGHT,
                     )
             else:
                 # No linked open PR: the IMPLEMENT phase, before the session
@@ -2681,6 +2709,7 @@ class DevWatcher:
                         f"still be running",
                         attempts,
                         session=live_session,
+                        defer_token=loop_events_mod.DEFER_IN_FLIGHT,
                     )
 
         # Never spawn attempt cap+1. Escalate ONCE; `escalated()` dedupes, and
@@ -2804,6 +2833,7 @@ class DevWatcher:
                 f"PR {resume_pr.url}",
                 attempt - 1,
                 session=dead_session,
+                defer_token=loop_events_mod.DEFER_IN_FLIGHT,
             )
 
         hub, problem = self._ensure_hub(issue.owner, issue.repo)
@@ -2948,6 +2978,7 @@ class DevWatcher:
             attempt,
             session=name,
             task_ref=task_ref,
+            resume=resume_pr is not None,
         )
 
     def _resumable_pr(
@@ -3552,6 +3583,7 @@ class DevWatcher:
                         attempts,
                         session=fix_session_name(pr, round_, attempts),
                         round=round_,
+                        defer_token=loop_events_mod.DEFER_IN_FLIGHT,
                     )
 
         # The per-round budget ran dry: stop and page the operator ON the
@@ -5024,6 +5056,7 @@ class DevWatcher:
                 attempt - 1,
                 session=dead_session,
                 round=round_,
+                defer_token=loop_events_mod.DEFER_IN_FLIGHT,
             )
 
         hub, problem = self._ensure_hub(pr.owner, pr.repo)
@@ -5110,6 +5143,7 @@ class DevWatcher:
             attempt,
             session=name,
             round=round_,
+            resume=dead_session is not None,
         )
 
     # -- the maintenance edge (operator-labeled PRs) ------------------------
@@ -5533,6 +5567,7 @@ class DevWatcher:
             attempts,
             session=claim.session,
             round=round_,
+            defer_token=loop_events_mod.DEFER_CLAIM,
         )
 
     def _log_deferral(
@@ -7292,8 +7327,111 @@ class DevWatcher:
             counts,
             duration_ms=int((time.monotonic() - started) * 1000),
         )
+        self._emit_loop_events(
+            issue_results, pr_results, maintain_results, sweep
+        )
         return results
 
+    def _emit_loop_events(
+        self,
+        issue_results: "list[tuple[str, Decision]]",
+        pr_results: "list[tuple[str, Decision]]",
+        maintain_results: "list[tuple[str, Decision]]",
+        sweep: Sweep,
+    ) -> None:
+        """The pass's loop-telemetry push (issue #101): hand the emitter the
+        pass observations the ledgers do not carry -- which spawns were
+        RESUMEs, which candidates deferred and why, which sessions the reaper
+        killed -- then let it derive the ledger events and POST one batch.
+        A no-op when the feature is off, and under dry_run: the push writes
+        to an external service, and a dry pass takes no side effects (the
+        ledgers it would derive from are not written under dry_run either,
+        so a dry pass's batch would misreport the pass as empty anyway).
+        Best-effort end to end -- emit_pass never raises."""
+        if self.loop_events is None or self.config.dry_run:
+            return
+        deferrals: "list[dict]" = []
+        for edge, results in (
+            ("issue", issue_results),
+            ("fix", pr_results),
+            ("maintain", maintain_results),
+        ):
+            for slug, decision in results:
+                repo, _, tail = slug.partition("#")
+                number = int(tail[2:] if tail.startswith("pr") else tail)
+                token = self._defer_token(decision)
+                if token is not None:
+                    deferrals.append({
+                        "repo": repo,
+                        "edge": edge,
+                        "number": number,
+                        "token": token,
+                        "reason": decision.reason,
+                    })
+                if decision.action is Action.SPAWNED and decision.resume:
+                    if edge == "issue":
+                        key = loop_events_mod.issue_spawn_key(
+                            repo, number, decision.attempt or 0
+                        )
+                    else:
+                        key = loop_events_mod.fix_spawn_key(
+                            repo, number, decision.round or 0,
+                            decision.attempt or 0,
+                        )
+                    self.loop_events.note_resume(key)
+        self.loop_events.emit_pass(
+            deferrals=deferrals,
+            reaps=self._reap_records(sweep.names),
+            now_ms=int(time.time() * 1000),
+        )
+
+    @staticmethod
+    def _defer_token(decision: Decision) -> "str | None":
+        """The coarse defer-reason token of one decision, or None when the
+        decision is not a deferral. DEFERRED is the capacity valve by
+        construction; the deferral flavours of IN_FLIGHT (the external-claim
+        hold, the stale-but-possibly-alive holds) carry their token on the
+        decision itself (`Decision.defer_token`, stamped where each deferral
+        is decided) -- a FRESH in-flight attempt carries none, because normal
+        progress is not a defer. Everything else -- spawns, skips, caps,
+        escalations -- emits nothing here."""
+        if decision.action is Action.DEFERRED:
+            return loop_events_mod.DEFER_CAPACITY
+        return decision.defer_token
+
+    def _reap_records(self, names: "set[str]") -> "list[dict]":
+        """The sweep's kills as the emitter's reap records: session name, the
+        anchor evidence the kill line carried, and -- when the name resolves
+        on this ledger -- the repo and number. A name outside devloop's own
+        grammar is a foreign kill: no anchor exists, so the record says so
+        and carries neither repo nor number (both optional on the ingest
+        contract). Sorted for a deterministic batch order."""
+        records: "list[dict]" = []
+        for name in sorted(names):
+            worker = parse_worker_session(name)
+            if worker is None:
+                records.append({"session": name, "anchor": "foreign session"})
+                continue
+            record: "dict" = {
+                "session": name,
+                "edge": "issue" if worker.is_issue else "pr",
+                "number": worker.number,
+                "anchor": worker.anchor,
+            }
+            if worker.is_issue:
+                row = self.state.spawn_for_session(name)
+            elif worker.edge == EDGE_FIX:
+                row = self.state.fix_spawn_for_session(name)
+            else:
+                row = self.state.maintain_spawn_for_session(name)
+            if row is not None:
+                # The ledger's slug, not the name's: the name slug is lossy
+                # (`a/b-c` and `a-b/c` both squash to `a-b-c`), so only a
+                # ledger row can say which repo the kill belonged to.
+                record["repo"] = row["repo_slug"]
+            records.append(record)
+        return records
+
     def _stage_record(
         self, edge: str, slug: str, decision: Decision
     ) -> "dict":