devops-bot-sdk 1.6.33__tar.gz → 1.6.37__tar.gz

{devops_bot_sdk-1.6.33 → devops_bot_sdk-1.6.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.6.33
+Version: 1.6.37
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.6.33 → devops_bot_sdk-1.6.37}/devops_bot_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.6.33
+Version: 1.6.37
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.6.33 → devops_bot_sdk-1.6.37}/devops_bot_sdk.egg-info/SOURCES.txt

@@ -14,31 +14,41 @@ sdk/client.py
 sdk/config.py
 sdk/crucial.py
 sdk/departments.py
+sdk/estimator.py
 sdk/exceptions.py
+sdk/firewall.py
 sdk/formats.py
 sdk/git_ops.py
 sdk/github_ingest.py
 sdk/graph_recon.py
 sdk/graphify.py
 sdk/intake.py
+sdk/journal.py
 sdk/local_exec.py
 sdk/phase_timer.py
 sdk/plan_run.py
 sdk/platform_compat.py
+sdk/prd_progress.py
 sdk/proof_readers.py
+sdk/providers.py
 sdk/py.typed
+sdk/resume.py
+sdk/router.py
 sdk/run_auto.py
 sdk/scheduler.py
 sdk/self_report.py
 sdk/self_report_local.py
 sdk/sse.py
+sdk/swagger.py
 sdk/task_file.py
+sdk/task_types.py
 sdk/test.py
 sdk/test_pipeline.py
 sdk/ticket_fields.py
 sdk/updater.py
 sdk/url_access.py
 sdk/vps_health.py
+sdk/write_hook.py
 sdk/agents/__init__.py
 sdk/agents/activity.py
 sdk/agents/builder.py
@@ -83,6 +93,8 @@ sdk/models/envelope.py
 sdk/models/requests.py
 sdk/models/responses.py
 sdk/models/snapshots.py
+sdk/tiers/__init__.py
+sdk/tiers/mini_agent.py
 sdk/ui/__init__.py
 sdk/ui/api.py
 sdk/ui/dashboard.py
@@ -102,7 +114,6 @@ sdk/ui/static/chat.html
 sdk/ui/static/custom-agents.html
 sdk/ui/static/default-agents.html
 sdk/ui/static/index.html
-sdk/ui/static/login.html
 sdk/ui/static/report.html
 sdk/ui/static/runs.html
 sdk/ui/static/schedules.html
@@ -122,6 +133,7 @@ tests/test_agents_connectors_builder.py
 tests/test_allowed_tools_config.py
 tests/test_auto_agent_dispatch.py
 tests/test_browser_profile.py
+tests/test_cheap_tier.py
 tests/test_client_jira_projects.py
 tests/test_config_token_diagnostics.py
 tests/test_configure_token_owner.py
@@ -130,6 +142,7 @@ tests/test_departments.py
 tests/test_epic_decompose_run.py
 tests/test_epic_inherited_agent_id.py
 tests/test_epic_session_isolation.py
+tests/test_estimator.py
 tests/test_formats.py
 tests/test_git_action.py
 tests/test_github_ingest.py
@@ -138,24 +151,34 @@ tests/test_graphify_build.py
 tests/test_graphify_hook_install.py
 tests/test_health.py
 tests/test_intake_plan_review.py
-tests/test_otp_login.py
+tests/test_journal.py
+tests/test_local_exec_provider.py
 tests/test_phase_timer.py
 tests/test_plan_new_command.py
 tests/test_plan_run_activity.py
+tests/test_prd_artifact.py
 tests/test_proof_readers.py
+tests/test_providers.py
 tests/test_recon_session_isolation.py
+tests/test_resume.py
+tests/test_router.py
 tests/test_run_auto_agent_only.py
 tests/test_run_outputs.py
 tests/test_schedule_api.py
 tests/test_scheduler.py
 tests/test_self_report.py
 tests/test_service_token_warning.py
+tests/test_swagger_command.py
 tests/test_task_file_and_plan_run.py
 tests/test_task_file_format_doc.py
 tests/test_ticket_fields.py
 tests/test_ticket_run_resolve_by_id.py
 tests/test_ticket_speed_fixes.py
+tests/test_tier_flag_parity.py
+tests/test_ui_gate.py
+tests/test_ui_lifespan.py
 tests/test_update_timer.py
 tests/test_updater_extras.py
 tests/test_url_access.py
-tests/test_vps_health.py
+tests/test_vps_health.py
+tests/test_write_hook.py

{devops_bot_sdk-1.6.33 → devops_bot_sdk-1.6.37}/devops_bot_sdk.egg-info/entry_points.txt

@@ -2,4 +2,5 @@
 agentos = sdk.cli:main
 agentos-agentd = sdk.agentd:main
 agentos-auto = sdk.run_auto:main
+agentos-swagger = sdk.swagger:main
 agentos-ui = sdk.ui.server:main

{devops_bot_sdk-1.6.33 → devops_bot_sdk-1.6.37}/pyproject.toml

@@ -54,6 +54,7 @@ agentos = "sdk.cli:main"                    # unified CLI: configure/agent/integ
 agentos-auto = "sdk.run_auto:main"          # run orchestrate-auto LOCALLY (co_ token from config)
 agentos-agentd = "sdk.agentd:main"          # long-running custom-agent daemon
 agentos-ui = "sdk.ui.server:main"           # local web control panel (needs the [ui] extra)
+agentos-swagger = "sdk.swagger:main"        # where /docs is + can you reach it (= `agentos swagger`)
 
 [project.urls]
 Homepage   = "https://agentos.io"

{devops_bot_sdk-1.6.33 → devops_bot_sdk-1.6.37}/sdk/__init__.py

@@ -1,6 +1,6 @@
 """AgentOS Desktop SDK — thin HTTPS/SSE client for the Electron app.
 
-Version: 1.6.33
+Version: 1.6.37
 
 Public surface:
   BackendClient.from_config()        — create client from ~/.agentos/config.toml
@@ -34,7 +34,7 @@ Rules:
   - All data egress through submit_webhook only
 """
 
-__version__ = "1.6.33"   # SINGLE SOURCE OF TRUTH — bump on every change; pyproject,
+__version__ = "1.6.37"   # SINGLE SOURCE OF TRUTH — bump on every change; pyproject,
 __author__  = "AgentOS"   # sdk.client.SDK_VERSION and the UI server version all read this.
 
 from sdk.client import BackendClient

{devops_bot_sdk-1.6.33 → devops_bot_sdk-1.6.37}/sdk/agentd.py

@@ -429,8 +429,25 @@ async def _dispatch_agent_run(
             )
             run_log.log_line(_log_path, f"task_id={task_id}")
 
+            # A custom-agent run writes real files, so it gets the SAME shared
+            # post-write hook the coding path uses: journal (synchronous,
+            # survives a kill) → requirement overlay → graph refresh. Without
+            # this, a custom-agent run produced no graph update and no journal
+            # entry at all, so a tier switch during one had no anchor to resume
+            # from — the run type was simply outside the resume triple.
+            from sdk import write_hook
+            from sdk.agents.engines.claude_code import ensure_agent_workspace
+
+            _workspace = str(ensure_agent_workspace(manifest.name))
+            _record_write = write_hook.make_recorder(
+                task_id=task_id or f"agent-{manifest.name}",
+                repo_path=_workspace,
+            )
+            _write_events = write_hook.make_event_hook(_record_write)
+
             async def _tee(ev: dict) -> None:
                 run_log.log_event(_log_path, ev)
+                await _write_events(ev)
 
             _started = time.monotonic()
             local_result = await claude_code_engine.run(
@@ -438,6 +455,10 @@ async def _dispatch_agent_run(
                 on_event=_tee,
             )
             run_log.finish_run(_log_path, local_result)
+            # Backstop for writes the stream did not surface (a resumed turn,
+            # an engine that tees events elsewhere). Ordering is lost, but an
+            # ordered-but-empty journal is worse than an unordered complete one.
+            await write_hook.record_result_files(_record_write, local_result)
             # Local ledger + platform `agent_activities` feed. EVERY trigger path
             # reaches this function (cron schedule, ticket label, on-demand
             # run-on-ticket from the UI / CLI / desktop IPC), so a VPS agent run is

{devops_bot_sdk-1.6.33 → devops_bot_sdk-1.6.37}/sdk/cli.py

@@ -58,6 +58,26 @@ Command surface:
     agentos integration rm <name>
         Remove a registered integration.
 
+    agentos firewall [--apply] [--revoke IP] [--port N]
+        Print the host-firewall rules that open the agentos-ui port to every IP in
+        the application allowlist (`sdk.config.get_allowed_ips`), for THIS OS — ufw
+        on Linux, `netsh advfirewall` on Windows, a pf note on macOS. Prints by
+        default; `--apply` executes them and needs root / Administrator. The host
+        firewall is a separate layer the allowlist cannot reach, and the two drifting
+        apart is what silently blinded every VPS when the backend's egress IP moved.
+        See sdk.firewall.
+
+    agentos swagger [--open] [--json [PATH]] [--port N]
+        Where the panel's Swagger UI is and whether it can actually be reached:
+        the URL derived from the bind address the service was installed with,
+        whether a co_ token is configured (masked), how many operations the spec
+        has, and a ufw/netsh diff against sdk.config.get_allowed_ips when the HOST
+        firewall would drop the port — a layer the SDK's own allowlist cannot see.
+        `--open` launches a browser; `--json` writes openapi.json from
+        create_app().openapi() with no server running (`--json -` pipes it).
+        Also flags routes registered twice, since the second copy is dead code.
+        Needs the [ui] extra for the route count and --json. See sdk.swagger.
+
     agentos report submit [--date YYYY-MM-DD] (--text "…" | --file PATH)
                           [--project NAME] [--proof PATH|URL]… [--no-wait]
         Report work that never reached Jira or GitHub, attach proofs (local
@@ -139,6 +159,14 @@ def main() -> None:
         _github_command(rest)
         return
 
+    if noun == "firewall":
+        from sdk import firewall
+        sys.exit(firewall.cli(rest))
+
+    if noun == "swagger":
+        from sdk import swagger
+        sys.exit(swagger.cli(rest))
+
     if noun == "report":
         _report_command(rest)
         return
@@ -152,7 +180,7 @@ def main() -> None:
 
 
 def _print_usage() -> None:
-    print("usage: agentos <configure|chat|agent|integration|default-agents|agentd|github|report|browser> ...")
+    print("usage: agentos <configure|chat|agent|integration|default-agents|agentd|github|report|browser|firewall|swagger> ...")
     print()
     print("  agentos configure [--rotate]")
     print("  agentos chat [--product-id ID] [--pv-id ID] [--no-autorun]   # requirements → ticket")
@@ -164,6 +192,8 @@ def _print_usage() -> None:
     print("  agentos github <ingest [--days N]|status>            # PR ingestion; --days N backfills N days")
     print("  agentos report <submit|list|show ID>                 # report work Jira/GitHub never saw")
     print("  agentos browser <login URL|status|logout>            # sign in once; private links become readable")
+    print("  agentos firewall [--apply] [--revoke IP] [--port N]  # open the UI port to the allowlisted IPs")
+    print("  agentos swagger [--open] [--json [PATH]]             # where /docs is, and can you reach it")
 
 
 # ── agent ────────────────────────────────────────────────────────────────

{devops_bot_sdk-1.6.33 → devops_bot_sdk-1.6.37}/sdk/client.py

@@ -45,6 +45,13 @@ logger = logging.getLogger(__name__)
 # agents without a lookup on every run.
 _AGENT_ID_CACHE: dict[str, str] = {}
 
+# GitHub access token, keyed by the co_ token that fetched it → (token, expires_at
+# monotonic). Keyed per credential so two clients on one box never share a token.
+# Without this the token is re-fetched on EVERY call, which is what
+# tests/test_ticket_speed_fixes.py::TestGithubTokenCache guards against.
+_GITHUB_TOKEN_CACHE: dict[str, tuple[str, float]] = {}
+_GITHUB_TOKEN_TTL_S = float(os.getenv("AGENTOS_GITHUB_TOKEN_TTL_S", "") or 1800.0)
+
 # GitHub access token, keyed by the co_ token that fetched it → (token, expires_at
 # monotonic). Keyed per credential so two clients on one box never share a token.
 _GITHUB_TOKEN_CACHE: dict[str, tuple[str, float]] = {}
@@ -197,6 +204,30 @@ _ORCHESTRATE_TIMEOUT      = 2700.0  # 45 min — covers approval wait + VPS exec
 _AUTO_ORCHESTRATE_TIMEOUT = 2700.0  # 45 min — same budget for multi-task auto runs
 
 
+def _jira_project_records(payload: dict) -> list[dict]:
+    """Normalise a jira-projects envelope to `list[dict]`.
+
+    The endpoint returns `data` as a FLAT LIST. Sibling endpoints on the same
+    gateway wrap theirs in `data.records` / `data.record`, and this shape is not
+    documented, so all three are tolerated rather than guessing one — a wrong
+    guess reads as "no projects", which is indistinguishable from a real empty
+    result and would silently disable the whole picker.
+    """
+    data = payload.get("data")
+    if isinstance(data, list):
+        return [r for r in data if isinstance(r, dict)]
+    if isinstance(data, dict):
+        records = data.get("records")
+        if isinstance(records, list):
+            return [r for r in records if isinstance(r, dict)]
+        record = data.get("record")
+        if isinstance(record, dict):
+            return [record]
+        if data.get("id") or data.get("jiraProjectId"):
+            return [dict(data)]
+    return []
+
+
 class BackendClient:
     """Thin HTTPS/SSE client — wraps all backend /api/v1/* endpoints.
 
@@ -928,51 +959,71 @@ class BackendClient:
         co_ token. Best-effort: returns None on any failure so a run without a
         connected GitHub account still proceeds (clone/PR steps just won't auth).
         """
+        import time as _time
+
+        now = _time.monotonic()
+        cached = _GITHUB_TOKEN_CACHE.get(self._token)
+        if cached and now < cached[1]:
+            return cached[0]
         record = await self.github_token_record()
-        return (record or {}).get("accessToken") or None
+        token = (record or {}).get("accessToken") or None
+        if token:
+            _GITHUB_TOKEN_CACHE[self._token] = (token, now + _GITHUB_TOKEN_TTL_S)
+        return token
 
-    async def ingest_github_prs(self, since: str | None = None) -> dict:
+    async def ingest_github_prs(self, since: str | None = None) -> dict | None:
         """POST {AI}/api/v1/github/prs — trigger this user's daily PR ingestion.
 
-        The backend resolves the caller's GitHub link server-side from the co_
-        token in ``Authorization`` (see ``docs/GITHUB_SCHEDULING_SDK_MIGRATION.md``);
-        ``githubUsername``/``githubAccessToken`` below are placeholders kept only
-        for backends that predate that resolution and are otherwise ignored.
-        ``since`` (ISO-8601 date) scopes the fetch — omit for "today".
-
-        Returns the backend's ``{status, job_id, status_url, ...}`` envelope.
-        Raises BackendUnreachable / HTTP errors — the github_ingest cron catches
-        and logs these itself rather than treating them as success.
+        The daily trigger. The work runs on the AI backend (LLM summarise, the
+        downstream daily-summary forward, the Qdrant upsert); the SDK only decides
+        WHEN, because only this machine knows its own catch-up watermark.
+
+        The backend resolves the caller's GitHub link server-side from the co_ token
+        in ``Authorization`` and OVERWRITES whatever the body sends
+        (``docs/GITHUB_SCHEDULING_SDK_MIGRATION.md`` §7/§9 — that endpoint used to
+        take a GitHub access token in an unauthenticated body). So this deliberately
+        sends NO credentials: a client that still supplied them would be shipping a
+        secret the server ignores.
+
+        ``since`` is an ISO date (``YYYY-MM-DD``) → the backend's ``date_from``.
+        Omitted means "today", which is what a never-missed run wants; the cron sends
+        the watermark instead so a machine that was off does not lose days.
+
+        Returns the response JSON (``{status, job_id, status_url, ...}``) or **None**
+        on any failure — never raises into the cron. WHY it failed lands in
+        ``self.last_ingest_error`` (``{status, body, retryable}``), which the
+        scheduler needs to tell a busy backend (retry in 30 min) from a rejected
+        request (wait for the next slot).
         """
-        body = [{
+        payload = [{
             "userId": self._user_id_from_token(),
-            "githubUsername": "",
-            "githubAccessToken": "",
-            "apiTokenHash": self._token,
-            "date_from": since,
+            "apiTokenHash": self._token,   # downstream daily-summary Authorization
         }]
-        async with httpx.AsyncClient(timeout=30.0) as client:
-            resp = await client.post(
-                self._url("/api/v1/github/prs"), json=body, headers=self._headers,
-            )
-        _check_status(resp.status_code, self._url("/api/v1/github/prs"))
-        return resp.json()
-
-    async def report_vps_health(self, payload: dict) -> dict:
-        """PATCH {AI}/api/v1/vps/health — heartbeat this machine's resource usage.
-
-        Feeds the backend's ``contabo_allocation`` row (VPS health shown in chat /
-        activity reports) — a live GET of the same path answers on-demand checks,
-        this PATCH is what keeps that data from going stale. Raises on failure
-        (BackendUnreachable / HTTP error); the vps_health cron logs and continues
-        rather than crashing the loop.
-        """
-        async with httpx.AsyncClient(timeout=30.0) as client:
-            resp = await client.request(
-                "PATCH", self._url("/api/v1/vps/health"), json=payload, headers=self._headers,
-            )
-        _check_status(resp.status_code, self._url("/api/v1/vps/health"))
-        return resp.json()
+        if since:
+            payload[0]["date_from"] = since
+        self.last_ingest_error = {}
+        try:
+            async with httpx.AsyncClient(timeout=60.0) as client:
+                resp = await client.post(
+                    self._url("/api/v1/github/prs"), json=payload, headers=self._headers,
+                )
+            if resp.status_code >= 400:
+                body = resp.text[:500]
+                logger.warning("client.ingest_github_prs failed status=%s body=%s",
+                               resp.status_code, body[:200])
+                self.last_ingest_error = {
+                    "status": resp.status_code,
+                    "body": body,
+                    "retryable": is_retryable_backend_error(resp.status_code, body),
+                }
+                return None
+            return resp.json()
+        except Exception as exc:  # noqa: BLE001 — a cron must not die on a blip
+            logger.warning("client.ingest_github_prs error err=%s", exc)
+            # A transport failure (timeout, reset, DNS blip) is as retryable as an
+            # exhausted pool — the backend may simply be busy.
+            self.last_ingest_error = {"status": 0, "body": str(exc)[:500], "retryable": True}
+            return None
 
     async def move_to_backlog(self, task_id: str) -> bool:
         """PUT {BE}/tasks-ml/{id} status=backlog (best-effort).
@@ -1096,6 +1147,108 @@ class BackendClient:
             logger.warning("client.set_task_status error task=%s err=%s", task_id, exc)
             return False
 
+    # ── Cheap tier (T0) — the backend holds the Azure/GCP credentials ───
+
+    async def llm_complete(
+        self,
+        messages: list[dict],
+        *,
+        tools: list[dict] | None = None,
+        step_type: str = "small_task",
+        task_id: str | None = None,
+        budget_tokens: int | None = None,
+        used_tokens: int = 0,
+        max_tokens: int | None = None,
+        timeout: float = 120.0,
+        attempts: int = 3,
+    ) -> dict:
+        """POST /api/v1/llm/complete — one turn of the cheap-tier tool loop.
+
+        The credential asymmetry is deliberate (plan §6): Azure/GCP keys stay
+        **server-side** because the backend is the client for T0, while the
+        Bedrock/subscription credentials stay desktop-side because the local
+        ``claude`` CLI is the client for T1/T2. Each tier's creds live where that
+        tier's client runs, so the desktop never holds an Azure key.
+
+        The budget is enforced **server-side** — the desktop is untrusted for
+        accounting — and a breach comes back as ``409 budget_exhausted``, which
+        the router treats as "escalate to T1", not as an error.
+
+        Returns ``{"ok", "text", "tool_calls", "model", "tokens_in",
+        "tokens_out", "status", "reason"}``. Never raises: an unreachable
+        backend is a *routing signal* (the cheap tier is the LESS available one),
+        so it comes back as ``ok=False`` with ``reason="backend_unreachable"``
+        and the router escalates.
+
+        Retries only what is worth retrying, via the existing
+        ``is_retryable_backend_error`` — so a saturated Postgres pool surfaced
+        as a 5xx is retried rather than escalating the whole task off the cheap
+        tier for a transient blip.
+        """
+        path = "/api/v1/llm/complete"
+        payload: dict[str, Any] = {
+            "messages": messages,
+            "step_type": step_type,
+        }
+        if tools:
+            payload["tools"] = tools
+        if task_id:
+            payload["task_id"] = task_id
+        if budget_tokens is not None:
+            payload["budget_tokens"] = budget_tokens
+        if used_tokens:
+            payload["used_tokens"] = used_tokens
+        if max_tokens is not None:
+            payload["max_tokens"] = max_tokens
+
+        def _fail(reason: str, status: int = 0, detail: str = "") -> dict:
+            return {"ok": False, "text": "", "tool_calls": [], "model": None,
+                    "tokens_in": 0, "tokens_out": 0, "status": status,
+                    "reason": reason, "detail": detail[:300]}
+
+        last = _fail("backend_unreachable")
+        for attempt in range(max(1, attempts)):
+            try:
+                async with httpx.AsyncClient(timeout=timeout) as client:
+                    resp = await client.post(
+                        self._url(path), json=payload, headers=self._headers,
+                    )
+            except Exception as exc:  # noqa: BLE001 — network/DNS/TLS
+                last = _fail("backend_unreachable", detail=str(exc))
+                if attempt + 1 < attempts:
+                    await asyncio.sleep(min(2.0 * (attempt + 1), 5.0))
+                    continue
+                return last
+            body = resp.text or ""
+            if resp.status_code == 409:
+                # The hard ceiling. One mechanism serves both accounting and the
+                # cap, so there is nothing to reconcile between them.
+                return _fail("budget_exhausted", resp.status_code, body)
+            if resp.status_code >= 400:
+                if is_retryable_backend_error(resp.status_code, body) and attempt + 1 < attempts:
+                    last = _fail("retryable", resp.status_code, body)
+                    await asyncio.sleep(min(2.0 * (attempt + 1), 5.0))
+                    continue
+                reason = ("auth" if resp.status_code == 401
+                          else "unavailable" if resp.status_code >= 500
+                          else "rejected")
+                return _fail(reason, resp.status_code, body)
+            try:
+                data = resp.json() or {}
+            except Exception:  # noqa: BLE001 — a 200 with a non-JSON body
+                return _fail("bad_response", resp.status_code, body)
+            return {
+                "ok": True,
+                "text": str(data.get("text") or ""),
+                "tool_calls": list(data.get("tool_calls") or []),
+                "model": data.get("model"),
+                "tokens_in": int(data.get("tokens_in") or 0),
+                "tokens_out": int(data.get("tokens_out") or 0),
+                "status": resp.status_code,
+                "reason": "",
+            }
+        return last
+
     async def update_task_ml(
         self, task_id: str, fields: dict, model_used: list[str] | None = None,
     ) -> bool:
@@ -1214,15 +1367,32 @@ class BackendClient:
             return None
 
     async def list_jira_projects(
-        self, pv_id: str, limit: int = 100, offset: int = 0,
+        self, pv_id: str = "", limit: int = 100, offset: int = 0,
+        *, all_: bool = False,
     ) -> list[dict]:
-        """GET {BE}/ml-api/jira-projects?limit=&offset=&pvId= — project records.
-
-        Scoped to one product version. Used to resolve an existing project (match
-        on `key`) before falling back to create_jira_project. Pagination is the
-        caller's: `total` in the envelope is ignored. Returns [] on any failure —
-        unlike list_todo_tasks_raw, a failure is logged rather than silent, so a
-        broken gateway can't read as "this version has no projects".
+        """GET {BE}/ml-api/jira-projects — project records.
+
+        Two fixes over the original, both of which made an unfiltered listing
+        impossible:
+
+        1. `pvId` is now OMITTED when blank. It used to be sent unconditionally as
+           `pvId=""`, which scopes the query to nothing, so there was no way to
+           ask "every project I can see". That matters because `pvId` is null on
+           the large majority of live rows (57 projects, 3 with a pvId at time of
+           writing) — a pvId-only client can reach almost none of the boards a
+           person would actually name.
+        2. The envelope is read TOLERANTLY. This endpoint returns `data` as a
+           FLAT LIST; the original read `data.records` only, so an unfiltered call
+           would have returned `[]` even once (1) was fixed. Both shapes are now
+           accepted, plus a bare `data.record`.
+
+        Pass `all_=True` to send the gateway's `all=true` (no pagination) instead
+        of `limit`/`offset`. Match on `key` to resolve an existing project before
+        falling back to `create_jira_project` — `key` is the same string a ticket
+        carries as `projectKey`.
+
+        Returns [] on any failure, logged rather than silent, so a broken gateway
+        cannot read as "there are no projects".
         """
         from sdk.config import BE_DEFAULT_URL
 
@@ -1233,25 +1403,43 @@ class BackendClient:
             "developer-name": "null",
             "product": "",
         }
+        params: dict[str, object] = {"offset": offset}
+        if all_:
+            params["all"] = "true"
+        else:
+            params["limit"] = limit
+        # Only scope by product when there is one — see (1) above.
+        if str(pv_id or "").strip():
+            params["pvId"] = str(pv_id).strip()
         try:
-            # All three params are always sent — the wire URL keeps its documented
-            # shape even when the caller has no pvId to scope by.
             async with httpx.AsyncClient(timeout=30.0) as client:
-                resp = await client.get(
-                    url,
-                    params={"limit": limit, "offset": offset, "pvId": str(pv_id or "")},
-                    headers=headers,
-                )
+                resp = await client.get(url, params=params, headers=headers)
             if resp.status_code >= 400:
                 logger.warning("client.list_jira_projects failed status=%s body=%s",
                                resp.status_code, resp.text[:300])
                 return []
-            records = ((resp.json() or {}).get("data") or {}).get("records") or []
-            return records if isinstance(records, list) else []
+            return _jira_project_records(resp.json() or {})
         except Exception as exc:  # noqa: BLE001
             logger.warning("client.list_jira_projects error err=%s", exc)
             return []
 
+    async def find_jira_project_by_key(self, key: str) -> dict | None:
+        """The project whose `key` matches, case-insensitively, or None.
+
+        The verification step before filing tickets: a key that no longer resolves
+        means the board was renamed or deleted, and creating N tickets against it
+        would fail N times with nothing naming the cause. Matched locally over the
+        full list because the gateway exposes no `?key=` filter.
+        """
+        wanted = str(key or "").strip().casefold()
+        if not wanted:
+            return None
+        for record in await self.list_jira_projects(all_=True):
+            candidate = record.get("key")
+            if isinstance(candidate, str) and candidate.strip().casefold() == wanted:
+                return record
+        return None
+
     async def add_comment(self, task_id: str, body: str) -> bool:
         """POST /tasks-ml/{id}/comments — add a comment to a ticket (best-effort).