qbraid-cli 0.16.13__tar.gz → 0.16.14__tar.gz

{qbraid_cli-0.16.13/qbraid_cli.egg-info → qbraid_cli-0.16.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qbraid-cli
-Version: 0.16.13
+Version: 0.16.14
 Summary: Command Line Interface for interacting with all parts of the qBraid platform.
 Author-email: qBraid Development Team <contact@qbraid.com>
 License-Expression: LicenseRef-Proprietary
@@ -30,11 +30,11 @@ Requires-Dist: typer>=0.12.1
 Requires-Dist: rich>=10.11.0
 Requires-Dist: click<=8.5.0
 Requires-Dist: questionary>=2.0.0
-Requires-Dist: qbraid-core>=0.6.32
+Requires-Dist: qbraid-core>=0.6.33
 Provides-Extra: compute
-Requires-Dist: qbraid-core[compute]>=0.6.32; extra == "compute"
+Requires-Dist: qbraid-core[compute]>=0.6.33; extra == "compute"
 Provides-Extra: envs
-Requires-Dist: qbraid-core[environments]>=0.6.32; extra == "envs"
+Requires-Dist: qbraid-core[environments]>=0.6.33; extra == "envs"
 Provides-Extra: dev
 Requires-Dist: isort; extra == "dev"
 Requires-Dist: black; extra == "dev"

{qbraid_cli-0.16.13 → qbraid_cli-0.16.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qbraid-cli"
-version = "0.16.13"
+version = "0.16.14"
 description = "Command Line Interface for interacting with all parts of the qBraid platform."
 readme = "README.md"
 authors = [{ name = "qBraid Development Team", email = "contact@qbraid.com" }]
@@ -32,7 +32,7 @@ dependencies = [
     "rich>=10.11.0",
     "click<=8.5.0",
     "questionary>=2.0.0",
-    "qbraid-core>=0.6.32",
+    "qbraid-core>=0.6.33",
 ]
 requires-python = ">= 3.10"
 
@@ -43,8 +43,8 @@ Documentation = "https://docs.qbraid.com/v2/cli/api-reference/qbraid"
 Discord = "https://discord.gg/KugF6Cnncm"
 
 [project.optional-dependencies]
-compute = ["qbraid-core[compute]>=0.6.32"]
-envs = ["qbraid-core[environments]>=0.6.32"]
+compute = ["qbraid-core[compute]>=0.6.33"]
+envs = ["qbraid-core[environments]>=0.6.33"]
 dev = ["isort", "black", "pytest", "pytest-cov", "pytest-asyncio"]
 
 [project.scripts]

{qbraid_cli-0.16.13 → qbraid_cli-0.16.14}/qbraid_cli/agents/app.py

@@ -3,12 +3,14 @@
 
 """Agents CLI - Monitor and manage AI coding agent sessions."""
 
+import errno
 import inspect
 import json
 import os
 import re
 import signal
 import time
+from contextlib import nullcontext
 from datetime import datetime
 from enum import Enum
 from pathlib import Path
@@ -23,6 +25,7 @@ from rich.table import Table
 
 from qbraid_cli.handlers import handle_error, run_progress_task
 
+from .keep_alive import KeepAliveCommandError, keep_alive_app, stop_plan
 from .queue import interrupt, queue_app
 from .work import register_work_commands
 
@@ -55,6 +58,7 @@ hooks_app = typer.Typer(
 )
 
 agents_app.add_typer(hooks_app, name="hooks")
+agents_app.add_typer(keep_alive_app, name="keep-alive")
 agents_app.add_typer(queue_app, name="queue")
 agents_app.command("interrupt")(interrupt)
 
@@ -452,17 +456,23 @@ def _not_running_reason(session):
     return None
 
 
-def _signal_agent(pid, force):
+def _signal_agent(pid, force, *, quiet=False):
     sig = signal.SIGKILL if force else signal.SIGTERM
     sig_name = "SIGKILL" if force else "SIGTERM"
     try:
         os.kill(pid, sig)
-        console.print(f"[green]Sent {sig_name} to process {pid}.[/green]")
-    except (OSError, ProcessLookupError):
-        console.print(f"[dim]Process {pid} already stopped.[/dim]")
+        if not quiet:
+            console.print(f"[green]Sent {sig_name} to process {pid}.[/green]")
+    except OSError as error:
+        if not isinstance(error, ProcessLookupError) and error.errno != errno.ESRCH:
+            raise KeepAliveCommandError(
+                "STOP_FAILED", f"Stop was not confirmed for PID {pid}: {error}. Inspect its current status."
+            ) from error
+        if not quiet:
+            console.print(f"[dim]Process {pid} already stopped.[/dim]")
 
 
-def _kill_tmux_session(session):
+def _kill_tmux_session(session, *, launcher=None, confirmation=None, as_json=False):
     """Stop a tmux-hosted agent only through a verified target.
 
     A saved window name is mutable: another session may hold it now. Core's
@@ -472,25 +482,150 @@ def _kill_tmux_session(session):
     """
     from qbraid_core.services.agents import AgentLauncher, AgentLauncherError
 
-    launcher = AgentLauncher()
+    launcher = launcher or AgentLauncher()
     if not callable(getattr(launcher, "kill_bound", None)):
         # Core has had kill_bound since 0.6.5; a saved window name alone is
         # never trusted, so without it nothing is closed.
-        console.print(
-            "[red]Not stopped:[/red] this qbraid-core cannot verify a tmux window; update qbraid-core.",
-            highlight=False,
-        )
-        raise typer.Exit(code=1)
+        _stop_refused("This qbraid-core cannot verify a tmux window; update qbraid-core.", as_json)
     try:
-        launcher.kill_bound(session.session_id)
+        launcher.kill_bound(session.session_id, **_stop_options(confirmation))
     except AgentLauncherError as error:
-        console.print(
-            "[red]Not stopped: Core could not verify this session's tmux window.[/red] "
-            f"{escape(str(error))}",
-            highlight=False,
+        if as_json:
+            from .keep_alive import _error
+
+            _error(error, True)
+        _stop_refused(f"Core could not verify this session's tmux window. {error}", False)
+    _stop_success(session, as_json, f"Stopped the agent in tmux window '{session.tmux_window}'.")
+
+
+def _stop_options(confirmation):
+    return {"keep_alive_confirmation": confirmation} if confirmation is not None else {}
+
+
+def _stop_refused(message, as_json, code="STOP_REFUSED"):
+    from .keep_alive import _error
+    from .keep_alive import _plain as safe_text
+
+    if as_json:
+        _error(KeepAliveCommandError(code, message), True)
+    console.print(f"[red]Not stopped:[/red] {escape(safe_text(message))}", highlight=False)
+    raise typer.Exit(code=1)
+
+
+def _stop_success(session, as_json, message):
+    from .keep_alive import _plain as safe_text
+
+    if as_json:
+        typer.echo(json.dumps({"ok": True, "sessionId": session.session_id, "stopped": True}))
+    else:
+        console.print(f"[green]{escape(safe_text(message))}[/green]", highlight=False)
+
+
+def _require_remote_stop_cli(compute):
+    """Inspect help before any Stop; a legacy CLI cannot provide consent receipts."""
+    import subprocess
+
+    try:
+        probe = subprocess.run(
+            [
+                "ssh",
+                "-T",
+                "-o",
+                "BatchMode=yes",
+                "-o",
+                "ConnectTimeout=10",
+                compute,
+                "qbraid agents kill --help",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+            stdin=subprocess.DEVNULL,
+        )
+    except (OSError, subprocess.TimeoutExpired) as error:
+        raise KeepAliveCommandError(
+            "DESTINATION_UNAVAILABLE",
+            "Could not inspect destination Stop capabilities. No Stop was attempted.",
+            {"attempted": False},
+        ) from error
+    if probe.returncode == 255:
+        raise KeepAliveCommandError(
+            "DESTINATION_UNAVAILABLE",
+            "Destination SSH connection failed during the capability check. No Stop was attempted.",
+            {"attempted": False},
         )
-        raise typer.Exit(code=1) from error
-    console.print(f"[green]Stopped the agent in tmux window '{escape(session.tmux_window)}'.[/green]")
+    help_text = re.sub(r"\x1b\[[0-9;]*m", "", probe.stdout)
+    if probe.returncode or not all(option in help_text for option in ("--json", "--yes")):
+        raise KeepAliveCommandError(
+            "UNSUPPORTED_OPERATION",
+            "Update the destination qbraid-cli for confirmed remote Stop. No Stop was attempted.",
+            {"attempted": False},
+        )
+
+
+def _remote_stop(compute, target, force, yes, as_json):
+    """New destination CLI owns consent; unknown authority cannot run legacy kill."""
+    import shlex
+    import subprocess
+
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.@:-]{0,254}", compute):
+        raise KeepAliveCommandError("INVALID_ARGUMENT", "Use a configured SSH alias for --compute.")
+    _require_remote_stop_cli(compute)
+    command = "qbraid agents kill --json"
+    command += " --force" if force else ""
+    command += " --yes" if yes else ""
+    command += f" -- {shlex.quote(target)}"
+    try:
+        response = subprocess.run(
+            ["ssh", "-T", "-o", "BatchMode=yes", "-o", "ConnectTimeout=10", compute, command],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+            stdin=subprocess.DEVNULL,
+        )
+    except (OSError, subprocess.TimeoutExpired) as error:
+        raise KeepAliveCommandError(
+            "UNKNOWN_OUTCOME",
+            "Remote Stop was not confirmed. It was not retried; inspect the destination.",
+        ) from error
+    try:
+        result = json.loads(response.stdout)
+    except (ValueError, UnicodeError, RecursionError):
+        raise KeepAliveCommandError(
+            "UNKNOWN_OUTCOME",
+            "Destination Stop could not be verified. Update its CLI/Core for confirmation support. "
+            "No command was retried; inspect the destination before retrying.",
+        ) from None
+    if not isinstance(result, dict) or not isinstance(result.get("ok"), bool):
+        raise KeepAliveCommandError(
+            "UNKNOWN_OUTCOME", "Destination Stop receipt was invalid; no command was retried."
+        )
+    if not result["ok"]:
+        failure = result.get("error")
+        if not isinstance(failure, dict) or not isinstance(failure.get("message"), str):
+            raise KeepAliveCommandError(
+                "UNKNOWN_OUTCOME", "Destination Stop error was invalid; no command was retried."
+            )
+        raise KeepAliveCommandError(
+            failure.get("code") or "STOP_REFUSED", failure["message"], failure.get("details")
+        )
+    if (
+        response.returncode
+        or result.get("stopped") is not True
+        or not isinstance(result.get("sessionId"), str)
+        or not result["sessionId"]
+    ):
+        raise KeepAliveCommandError(
+            "UNKNOWN_OUTCOME", "Destination did not confirm an exact stopped session; no command was retried."
+        )
+    if as_json:
+        typer.echo(json.dumps(result, ensure_ascii=True))
+    else:
+        from .keep_alive import _plain as safe_text
+
+        console.print(f"[green]Stopped '{escape(safe_text(target))}' on {escape(compute)}.[/green]")
 
 
 _GONE = "gone"
@@ -1258,6 +1393,8 @@ def agents_kill(
     target: str = typer.Argument(..., help="Agent name, ID prefix, or PID"),
     force: bool = typer.Option(False, "--force", "-f", help="Use SIGKILL instead of SIGTERM"),
     compute: Optional[str] = typer.Option(None, "--compute", "-c", help="SSH alias for remote compute"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Confirm disabling keep-alive before Stop."),
+    as_json: bool = typer.Option(False, "--json", help="Print a JSON receipt; enrolled Stop requires --yes."),
 ):
     """Stop an agent by name, session ID, or PID.
 
@@ -1269,11 +1406,7 @@ def agents_kill(
         from qbraid_core.services.agents import AgentSessionRegistryManager
 
         if compute:
-            import shlex
-
-            flags = " --force" if force else ""
-            _ssh_cmd(compute, f"qbraid agents kill {shlex.quote(target)}{flags}")
-            console.print(f"[green]Stopped '{target}' on {compute}.[/green]")
+            _remote_stop(compute, target, force, yes, as_json)
             return
 
         registry = AgentSessionRegistryManager()
@@ -1303,11 +1436,14 @@ def agents_kill(
             ]
 
         if not matches:
-            console.print(f"[red]No session found matching '{target}'.[/red]")
-            raise typer.Exit(code=1)
+            _stop_refused(f"No session found matching '{target}'.", as_json, "SESSION_NOT_FOUND")
 
         # If multiple matches, show filtered picker
         if len(matches) > 1:
+            if as_json or not _can_ask():
+                _stop_refused(
+                    "Multiple sessions match; use a complete, exact session ID.", as_json, "AMBIGUOUS_SESSION"
+                )
             import questionary
 
             console.print(f"[yellow]Multiple sessions match '{target}':[/yellow]")
@@ -1338,92 +1474,103 @@ def agents_kill(
 
         session = matches[0]
         if getattr(session, "runtime_kind", None) == "provider_child":
-            console.print(
-                "[red]Not stopped:[/red] native provider children are read-only. "
-                "Manage this child from its parent agent."
+            _stop_refused(
+                "Native provider children are read-only. Manage this child from its parent agent.",
+                as_json,
+                "READ_ONLY_SESSION",
             )
-            raise typer.Exit(code=1)
         pid = session.pid
 
         # Shown as interrupted (another Lab's row this Lab cannot verify):
         # refused before anything, Core included, so nothing is written for
         # it. Other native rows go to Core, which asks their owning server.
         if (_lifecycle_view(registry, session).metadata or {}).get("status_overlay"):
-            console.print(
-                "[red]Not stopped:[/red] it belongs to another Lab that this Lab cannot verify, so it is "
+            _stop_refused(
+                "It belongs to another Lab that this Lab cannot verify, so it is "
                 "listed as interrupted. Resume it with --confirm-owner-gone, or stop it from its own Lab. "
                 "Nothing was signalled or closed.",
-                highlight=False,
+                as_json,
             )
-            raise typer.Exit(code=1)
 
-        if session.metadata.get("terminal_backend") == "jupyter":
+        native = session.metadata.get("terminal_backend") == "jupyter"
+        if not native:
+            refusal = _foreign_pid_reason(session) or _not_running_reason(session)
+            if refusal:
+                _stop_refused(f"{refusal} Nothing was signalled or closed.", as_json)
+
+        from qbraid_core.services.agents import AgentLauncher
+
+        launcher = AgentLauncher(registry=registry)
+        recovery, confirmation = stop_plan(launcher, session, yes=yes, as_json=as_json, can_ask=_can_ask)
+
+        if native:
             # A native agent belongs to its Lab server, which Core reaches and
             # verifies; its PID may be another namespace's. Never signalled here.
             from qbraid_core.services.agents import AgentLauncher, AgentLauncherError
             from qbraid_core.services.agents.exceptions import AgentRuntimeUnavailableError
 
             try:
-                AgentLauncher().kill_bound(session.session_id)
+                launcher.kill_bound(session.session_id, **_stop_options(confirmation))
             except AgentRuntimeUnavailableError as error:
                 if _not_running_reason(session):
                     # Nothing to verify: Core says why (e.g. no longer active).
-                    console.print(f"[red]Not stopped:[/red] {escape(str(error))}", highlight=False)
+                    _stop_refused(str(error), as_json)
                 else:
-                    console.print(
-                        "[red]Could not verify the Lab server that owns this agent; "
-                        "nothing was stopped.[/red] "
-                        f"{escape(str(error))}",
-                        highlight=False,
+                    _stop_refused(
+                        f"The owning Lab did not confirm Stop. Inspect its current status. {error}",
+                        as_json,
                     )
-                raise typer.Exit(code=1)
             except AgentLauncherError as error:
-                console.print(f"[red]Not stopped:[/red] {escape(str(error))}", highlight=False)
-                raise typer.Exit(code=1)
-            console.print("[green]Stopped native Lab agent.[/green]")
+                if as_json:
+                    from .keep_alive import _error
+
+                    _error(error, True)
+                _stop_refused(str(error), False)
+            _stop_success(session, as_json, "Stopped native Lab agent.")
             return
 
         # Refused before anything is touched: a row of another PID namespace or
         # machine, or one no longer running, names a PID and a tmux window that
         # may now belong to someone else.
-        refusal = _foreign_pid_reason(session) or _not_running_reason(session)
-        if refusal:
-            console.print(
-                f"[red]Not stopped:[/red] {escape(refusal)} Nothing was signalled or closed.", highlight=False
-            )
-            raise typer.Exit(code=1)
-
         if session.tmux_session and session.tmux_window:
-            _kill_tmux_session(session)
+            _kill_tmux_session(session, launcher=launcher, confirmation=confirmation, as_json=as_json)
             return
 
         if not (pid and pid > 0):
-            console.print(
-                "[red]Not stopped:[/red] no agent process or terminal is recorded for this session."
-            )
-            raise typer.Exit(code=1)
-        identity = _agent_identity_refusal(session)
-        if identity == _GONE:
-            console.print(f"[dim]Process {pid} already stopped.[/dim]")
-        elif identity:
-            console.print(
-                f"[red]Not stopped. Did not signal PID {pid}:[/red] {escape(identity)}", highlight=False
-            )
-            raise typer.Exit(code=1)
-        else:
-            _signal_agent(pid, force)
-
-        # Verified gone or signalled: mark stopped in registry
-        registry.deregister_session(session_id=session.session_id)
-        console.print(
-            f"[dim]Session {session.session_id[:8]} "
-            f"({session.terminal_name or session.tmux_window or '-'}) stopped.[/dim]"
+            _stop_refused("No agent process or terminal is recorded for this session.", as_json)
+        guard = recovery.keep_alive_stop_guard(launcher, None, suppress=False) if recovery else nullcontext()
+        with guard:
+            if recovery and recovery.recovery_bound_pids(registry, {pid}):
+                _stop_refused(
+                    "This PID belongs to a recovery-bound runtime. Use its exact managed session Stop.",
+                    as_json,
+                )
+            identity = _agent_identity_refusal(session)
+            if identity == _GONE:
+                if not as_json:
+                    console.print(f"[dim]Process {pid} already stopped.[/dim]")
+            elif identity:
+                _stop_refused(f"Did not signal PID {pid}: {identity}", as_json)
+            else:
+                _signal_agent(pid, force, quiet=as_json)
+            registry.deregister_session(session_id=session.session_id)
+        _stop_success(
+            session,
+            as_json,
+            f"Session {session.session_id[:8]} "
+            f"({session.terminal_name or session.tmux_window or '-'}) stopped.",
         )
 
     except (typer.Exit, SystemExit):
         raise
     except Exception as e:
-        handle_error(message=str(e))
+        from .keep_alive import _plain as safe_text
+
+        if as_json:
+            from .keep_alive import _error
+
+            _error(e, True)
+        console.print(f"[red]Stop was not confirmed:[/red] {escape(safe_text(e))}", highlight=False)
         raise typer.Exit(code=1)
 
 

qbraid_cli-0.16.14/qbraid_cli/agents/keep_alive.py

@@ -0,0 +1,357 @@
+# Copyright (c) 2026, qBraid Development Team
+# All rights reserved.
+"""Explicit local keep-alive controls and an optional foreground host."""
+
+import importlib
+import inspect
+import json
+import math
+import time
+import unicodedata
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+keep_alive_app = typer.Typer(
+    help=(
+        "Opt-in local managed agent recovery.\n\n"
+        "Restore enrolled local conversations after an instance restart. "
+        "A process exit in the same instance pauses recovery for attention. "
+        "Off by default. Explicit Stop disables recovery. A compatible running host is required; "
+        "these commands do not install a daemon or support remote compute."
+    ),
+    no_args_is_help=True,
+)
+console = Console()
+
+
+class KeepAliveCommandError(Exception):
+    """An actionable failure that also has a stable JSON representation."""
+
+    def __init__(self, code, message, details=None):
+        super().__init__(message)
+        self.code = code
+        self.details = details
+
+
+def _load():
+    """Keep ordinary CLI imports usable with an older installed Core."""
+    try:
+        module = importlib.import_module("qbraid_core.services.agents.keep_alive")
+        manager = module.KeepAliveManager
+        supervisor = module.RecoverySupervisor
+        if not all(
+            callable(getattr(manager, method, None)) for method in ("enable", "list", "disable", "forget")
+        ):
+            raise AttributeError("Incomplete keep-alive controls")
+        if not callable(getattr(supervisor, "tick", None)):
+            raise AttributeError("Missing keep-alive host")
+        return manager, supervisor
+    except (ImportError, AttributeError) as error:
+        raise KeepAliveCommandError(
+            "UNSUPPORTED_OPERATION",
+            "Keep-alive requires a compatible qbraid-core with KeepAliveManager and RecoverySupervisor. "
+            "Upgrade Core before using these commands. No policy was changed.",
+        ) from error
+
+
+def _require_recovery_protocol(*, host=False):
+    """Check installed behavior; the recovery release has no assigned version yet."""
+    try:
+        module = importlib.import_module("qbraid_core.services.agents.keep_alive")
+        end = importlib.import_module("qbraid_core.services.agents.session_end_hook")
+        if not _protocol_is(module, "KEEP_ALIVE_STOP_PROTOCOL", 1) or not _protocol_is(
+            end, "BOUND_END_HOOK_PROTOCOL", 2
+        ):
+            raise AttributeError("Missing reviewed recovery protocols")
+        if host and "supported_backends" not in inspect.signature(module.RecoverySupervisor).parameters:
+            raise AttributeError("Missing recovery-host backend selection")
+    except (ImportError, AttributeError, TypeError, ValueError) as error:
+        raise KeepAliveCommandError(
+            "UNSUPPORTED_OPERATION",
+            "Upgrade Core to the reviewed keep-alive and bound-end adapters before enabling or hosting "
+            "recovery. No recovery release version has been assigned. No policy was changed.",
+        ) from error
+
+
+def _protocol_is(module, name, expected):
+    value = getattr(module, name, None)
+    return isinstance(value, int) and not isinstance(value, bool) and value == expected
+
+
+def stop_plan(launcher, session, *, yes, as_json, can_ask):
+    """Read consent without mutation; Core rechecks the token while stopping."""
+    name = "qbraid_core.services.agents.keep_alive"
+    try:
+        module = importlib.import_module(name)
+    except ModuleNotFoundError as error:
+        if error.name == name:
+            registry_path = getattr(getattr(launcher, "_registry", None), "registry_path", None)
+            from pathlib import Path
+
+            if session.metadata.get("keep_alive_provider") is not None or (
+                isinstance(registry_path, (str, Path))
+                and any((Path(registry_path).parent / "keep-alive").glob("*.json"))
+            ):
+                raise KeepAliveCommandError(
+                    "UNSUPPORTED_OPERATION",
+                    "Update Core to inspect saved recovery policies before stopping this agent. "
+                    "Nothing was stopped or disabled.",
+                ) from error
+            return None, None  # Released Core predating enrollment keeps its Stop behavior.
+        raise
+    try:
+        controls = importlib.import_module("qbraid_core.services.agents.runtime_controls")
+        guard = getattr(module, "keep_alive_stop_guard", None)
+        supported = (
+            _protocol_is(module, "KEEP_ALIVE_STOP_PROTOCOL", 1)
+            and callable(getattr(controls, "stop_preflight", None))
+            and callable(getattr(module, "recovery_bound_pids", None))
+            and callable(guard)
+            and "keep_alive_confirmation" in inspect.signature(guard).parameters
+        )
+    except (ImportError, TypeError, ValueError):
+        supported = False
+    if not supported:
+        raise KeepAliveCommandError(
+            "UNSUPPORTED_OPERATION",
+            "Update Core for atomic keep-alive Stop confirmation. Nothing was stopped or disabled.",
+        )
+    preflight = controls.stop_preflight(launcher, session.session_id)
+    if not isinstance(preflight, dict) or not isinstance(preflight.get("requiresConfirmation"), bool):
+        raise KeepAliveCommandError("INVALID_RESPONSE", "Core returned an invalid Stop preflight.")
+    confirmation = preflight.get("keepAliveConfirmation")
+    if preflight["requiresConfirmation"]:
+        if not isinstance(confirmation, dict):
+            raise KeepAliveCommandError("INVALID_RESPONSE", "Core did not bind its Stop confirmation.")
+        if not yes:
+            if as_json or not can_ask():
+                raise KeepAliveCommandError(
+                    "KEEP_ALIVE_CONFIRMATION_REQUIRED",
+                    "Keep-alive is enabled. Pass --yes to turn it off and stop the agent. "
+                    "Nothing was stopped or disabled.",
+                    preflight,
+                )
+            try:
+                confirmed = typer.confirm(
+                    "Keep-alive is enabled. Turn it off and stop the agent?", default=False
+                )
+            except (typer.Abort, EOFError, KeyboardInterrupt):
+                confirmed = False
+            if not confirmed:
+                typer.echo("Not stopped. No policy was changed.")
+                raise typer.Exit(code=1)
+    elif confirmation is not None:
+        raise KeepAliveCommandError("INVALID_RESPONSE", "Core returned an unexpected Stop confirmation.")
+    return module, confirmation
+
+
+def _manager(compute):
+    if compute is not None:
+        raise ValueError("Keep-alive is local only. Run this command on the session's original instance.")
+    manager, supervisor = _load()
+    from qbraid_core.services.agents import AgentLauncher
+
+    return manager(AgentLauncher()), supervisor
+
+
+def _plain(value):
+    """Keep terminal controls and invisible direction changes out of human output."""
+    return "".join(
+        f"\\u{ord(char):04x}" if unicodedata.category(char) in {"Cc", "Cf", "Cs", "Zl", "Zp"} else char
+        for char in str(value)
+    )
+
+
+def _error(error, as_json=False):
+    if as_json:
+        failure = {"code": getattr(error, "code", None) or "KEEP_ALIVE_ERROR", "message": str(error)}
+        details = getattr(error, "details", None)
+        if isinstance(details, dict):
+            failure["details"] = details
+        typer.echo(json.dumps({"ok": False, "error": failure}, ensure_ascii=True))
+    else:
+        typer.echo(f"Keep-alive: {_plain(error)}", err=True)
+    raise typer.Exit(code=1) from error
+
+
+def _policy(manager, policy_id):
+    matches = [policy for policy in manager.list() if policy["policy_id"] == policy_id]
+    if len(matches) != 1:
+        raise ValueError("No policy has that exact ID. Use 'qbraid agents keep-alive list'.")
+    return matches[0]
+
+
+def _show(policies, as_json):
+    if as_json:
+        typer.echo(json.dumps(policies))
+        return
+    if not policies:
+        typer.echo("No keep-alive policies. Recovery is off for unenrolled sessions.")
+        return
+    table = Table("Policy ID", "Session ID", "State", "Reason")
+    for policy in policies:
+        table.add_row(
+            *(
+                Text(_plain(policy.get(key) or ""))
+                for key in (
+                    "policy_id",
+                    "active_session_id",
+                    "state",
+                    "reason",
+                )
+            )
+        )
+    console.print(table)
+    typer.echo("Enabled policies require a compatible host to be running.")
+
+
+@keep_alive_app.command("list")
+def list_policies(
+    as_json: bool = typer.Option(False, "--json", help="Print policy data as JSON."),
+    compute: Optional[str] = typer.Option(None, "--compute", hidden=True),
+):
+    """List local recovery policies.
+
+    Does not enroll or launch anything.
+    """
+    try:
+        manager, _ = _manager(compute)
+        _show(manager.list(), as_json)
+    except Exception as error:
+        _error(error, as_json)
+
+
+@keep_alive_app.command("enable")
+def enable_policy(
+    session_id: str = typer.Argument(
+        ..., help="Complete local managed session ID; names/prefixes are refused."
+    ),
+    as_json: bool = typer.Option(False, "--json", help="Print the resulting policy as JSON."),
+    compute: Optional[str] = typer.Option(None, "--compute", hidden=True),
+):
+    """Enable recovery for one exact session.
+
+    Preserves the live conversation's recorded permissions.
+    """
+    try:
+        manager, _ = _manager(compute)
+        _require_recovery_protocol()
+        session = manager.registry.get_session(session_id)
+        if session.session_id != session_id:
+            raise ValueError("Enable requires the complete, exact session ID.")
+        expected = {
+            "pid": session.pid,
+            "startedAt": session.started_at,
+            "tool": session.tool.value,
+            "terminalId": session.metadata.get("jupyter_terminal_id"),
+            "serverId": session.metadata.get("jupyter_server_id"),
+            "transcriptPath": session.transcript_path,
+        }
+        policy = manager.enable(session_id, expected)
+        if as_json:
+            typer.echo(json.dumps(policy))
+        else:
+            _show([policy], False)
+    except Exception as error:
+        _error(error, as_json)
+
+
+@keep_alive_app.command("disable")
+def disable_policy(
+    policy_id: str = typer.Argument(..., help="Complete policy ID from keep-alive list."),
+    as_json: bool = typer.Option(False, "--json", help="Print the resulting policy as JSON."),
+    compute: Optional[str] = typer.Option(None, "--compute", hidden=True),
+):
+    """Disable recovery; leave the agent running."""
+    try:
+        manager, _ = _manager(compute)
+        selected = _policy(manager, policy_id)
+        policy = manager.disable(policy_id, selected["revision"])
+        if as_json:
+            typer.echo(json.dumps(policy))
+        else:
+            typer.echo(f"Disabled keep-alive policy {_plain(policy_id)}. The running agent was not stopped.")
+    except Exception as error:
+        _error(error, as_json)
+
+
+@keep_alive_app.command("forget")
+def forget_policy(
+    policy_id: str = typer.Argument(..., help="Complete, already disabled policy ID."),
+    as_json: bool = typer.Option(False, "--json", help="Print a JSON acknowledgement."),
+    compute: Optional[str] = typer.Option(None, "--compute", hidden=True),
+):
+    """Remove an already disabled policy.
+
+    Does not change any agent runtime.
+    """
+    try:
+        manager, _ = _manager(compute)
+        selected = _policy(manager, policy_id)
+        if selected["enabled"]:
+            raise ValueError("Disable this policy before removing it.")
+        manager.forget(policy_id, selected["revision"])
+        if as_json:
+            typer.echo(json.dumps({"policy_id": policy_id, "removed": True}))
+        else:
+            typer.echo(f"Removed disabled policy {_plain(policy_id)}.")
+    except Exception as error:
+        _error(error, as_json)
+
+
+@keep_alive_app.command("run")
+def run_host(
+    once: bool = typer.Option(False, "--once", help="Reconcile once and exit; installs no background host."),
+    interval: float = typer.Option(5.0, "--interval", min=1.0, max=300.0, help="Seconds between ticks."),
+    as_json: bool = typer.Option(
+        False, "--json", help="Print each tick's policies as newline-delimited JSON."
+    ),
+    compute: Optional[str] = typer.Option(None, "--compute", hidden=True),
+):
+    """Run the local recovery host.
+
+    Ctrl-C exits without disabling policies.
+    Exiting leaves policies armed, but recovery requires another compatible host
+    to be running. Native policies pause here and require the owning Lab host.
+    This command never enrolls a session or installs a daemon.
+    """
+    try:
+        if not math.isfinite(interval):
+            raise ValueError("The polling interval must be a finite number of seconds.")
+        manager, supervisor = _manager(compute)
+        _require_recovery_protocol(host=True)
+        host = supervisor(manager, supported_backends={"tmux"})
+        if not once:
+            typer.echo(
+                "Foreground keep-alive host running. No sessions are enrolled by this command.", err=True
+            )
+        try:
+            while True:
+                try:
+                    policies = host.tick()
+                except Exception as error:
+                    raise KeepAliveCommandError(
+                        "HOST_FAILED",
+                        f"Recovery host failed and stopped: {error}. This tick was not retried. "
+                        "Inspect policy status before starting another host.",
+                    ) from error
+                if once or as_json:
+                    # An overlapping host's nonblocking tick can return no
+                    # results; it does not mean there are no saved policies.
+                    _show(policies or manager.list(), as_json)
+                if once:
+                    return
+                time.sleep(interval)
+        except KeyboardInterrupt:
+            return
+        finally:
+            typer.echo(
+                "Host stopped. Policies stay armed, but recovery requires a compatible host to be running.",
+                err=True,
+            )
+    except Exception as error:
+        _error(error, as_json)

{qbraid_cli-0.16.13 → qbraid_cli-0.16.14/qbraid_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qbraid-cli
-Version: 0.16.13
+Version: 0.16.14
 Summary: Command Line Interface for interacting with all parts of the qBraid platform.
 Author-email: qBraid Development Team <contact@qbraid.com>
 License-Expression: LicenseRef-Proprietary
@@ -30,11 +30,11 @@ Requires-Dist: typer>=0.12.1
 Requires-Dist: rich>=10.11.0
 Requires-Dist: click<=8.5.0
 Requires-Dist: questionary>=2.0.0
-Requires-Dist: qbraid-core>=0.6.32
+Requires-Dist: qbraid-core>=0.6.33
 Provides-Extra: compute
-Requires-Dist: qbraid-core[compute]>=0.6.32; extra == "compute"
+Requires-Dist: qbraid-core[compute]>=0.6.33; extra == "compute"
 Provides-Extra: envs
-Requires-Dist: qbraid-core[environments]>=0.6.32; extra == "envs"
+Requires-Dist: qbraid-core[environments]>=0.6.33; extra == "envs"
 Provides-Extra: dev
 Requires-Dist: isort; extra == "dev"
 Requires-Dist: black; extra == "dev"

{qbraid_cli-0.16.13 → qbraid_cli-0.16.14}/qbraid_cli.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ qbraid_cli/admin/headers.py
 qbraid_cli/admin/validation.py
 qbraid_cli/agents/__init__.py
 qbraid_cli/agents/app.py
+qbraid_cli/agents/keep_alive.py
 qbraid_cli/agents/permission_response.py
 qbraid_cli/agents/provider_children.py
 qbraid_cli/agents/queue.py

{qbraid_cli-0.16.13 → qbraid_cli-0.16.14}/qbraid_cli.egg-info/requires.txt

@@ -2,10 +2,10 @@ typer>=0.12.1
 rich>=10.11.0
 click<=8.5.0
 questionary>=2.0.0
-qbraid-core>=0.6.32
+qbraid-core>=0.6.33
 
 [compute]
-qbraid-core[compute]>=0.6.32
+qbraid-core[compute]>=0.6.33
 
 [dev]
 isort
@@ -15,4 +15,4 @@ pytest-cov
 pytest-asyncio
 
 [envs]
-qbraid-core[environments]>=0.6.32
+qbraid-core[environments]>=0.6.33

{qbraid_cli-0.16.13 → qbraid_cli-0.16.14}/tests/test_cli_e2e.py

@@ -937,7 +937,7 @@ class TestAgentsE2E:
 
     @patch("qbraid_core.services.agents.AgentLauncher")
     @patch("qbraid_core.services.agents.AgentSessionRegistryManager")
-    def test_kill_session(self, mock_registry_cls, mock_launcher_cls):
+    def test_kill_session(self, mock_registry_cls, mock_launcher_cls, tmp_path):
         """Kill a session by ID: a tmux row goes through Core's verified kill."""
         mock_session = MagicMock()
         mock_session.session_id = "abc12345-6789"
@@ -952,10 +952,12 @@ class TestAgentsE2E:
         mock_session.tmux_session = "qbraid-agents"
 
         mock_registry = MagicMock()
+        mock_registry.registry_path = tmp_path / "sessions.json"
         all_sessions = MagicMock()
         all_sessions.sessions = [mock_session]
         mock_registry.load_registry.return_value = all_sessions
         mock_registry_cls.return_value = mock_registry
+        mock_launcher_cls.return_value._registry = mock_registry
 
         from qbraid_cli.agents.app import agents_app
 
@@ -964,6 +966,8 @@ class TestAgentsE2E:
 
         assert result.exit_code == 0, result.output
         mock_launcher_cls.return_value.kill_bound.assert_called_once_with("abc12345-6789")
+        assert not (tmp_path / "keep-alive").exists()
+        mock_registry.deregister_session.assert_not_called()
         # Nothing touches the window or the PID directly: Core verified the target.
         tmux.assert_not_called()
         kill.assert_not_called()