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

{qbraid_cli-0.16.12/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.12
+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.30
+Requires-Dist: qbraid-core>=0.6.33
 Provides-Extra: compute
-Requires-Dist: qbraid-core[compute]>=0.6.30; extra == "compute"
+Requires-Dist: qbraid-core[compute]>=0.6.33; extra == "compute"
 Provides-Extra: envs
-Requires-Dist: qbraid-core[environments]>=0.6.30; 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.12 → qbraid_cli-0.16.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qbraid-cli"
-version = "0.16.12"
+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.30",
+    "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.30"]
-envs = ["qbraid-core[environments]>=0.6.30"]
+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.12 → 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},
+        )
+    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},
         )
-        raise typer.Exit(code=1) from error
-    console.print(f"[green]Stopped the agent in tmux window '{escape(session.tmux_window)}'.[/green]")
+
+
+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"
@@ -1241,6 +1376,9 @@ def agents_update(
         console.print("[dim]Use 'qbraid agents list' to see active sessions.[/dim]")
         raise typer.Exit(code=1)
     except Exception as e:
+        if _is_registry_error(e):
+            console.print(f"[red]Cannot update session: {_plain(e)}[/red]", highlight=False)
+            raise typer.Exit(code=1) from e
         handle_error(message=str(e))
         raise typer.Exit(code=1)
 
@@ -1255,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.
 
@@ -1266,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()
@@ -1300,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]")
@@ -1334,87 +1473,104 @@ def agents_kill(
             matches = [s for s in matches if s.session_id == selected]
 
         session = matches[0]
+        if getattr(session, "runtime_kind", None) == "provider_child":
+            _stop_refused(
+                "Native provider children are read-only. Manage this child from its parent agent.",
+                as_json,
+                "READ_ONLY_SESSION",
+            )
         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)
 
 
@@ -2848,7 +3004,8 @@ def agents_watch(
             import subprocess as _sp
 
             remote_flags = f"qbraid agents watch {shlex.quote(session_id)} --stream --lines {lines}"
-            console.print(f"[dim]Watching {session_id} on {compute}... (Ctrl+C to stop)[/dim]")
+            if not stream:
+                console.print(f"[dim]Watching {session_id} on {compute}... (Ctrl+C to stop)[/dim]")
 
             proc = _sp.Popen(  # pylint: disable=consider-using-with
                 ["ssh", "-o", "ConnectTimeout=10", compute, remote_flags],
@@ -2871,6 +3028,11 @@ def agents_watch(
                         try:
 
                             event = json.loads(line)
+                            if event.get("runtime_kind") == "provider_child":
+                                from .provider_children import render_child_event
+
+                                render_child_event(console, event)
+                                continue
                             entry_type = event.get("type", "unknown")
                             content = event.get("content", "")
                             ts = event.get("timestamp")
@@ -2895,12 +3057,18 @@ def agents_watch(
                             console.print(line_text, highlight=False)
                         except Exception:
                             console.print(line, highlight=False)
+                remote_status = proc.wait()
+                if remote_status:
+                    raise typer.Exit(code=remote_status if remote_status > 0 else 1)
             except KeyboardInterrupt:
-                proc.terminate()
-                console.print("\n[dim]Stopped watching.[/dim]")
-            finally:
                 proc.terminate()
                 proc.wait()
+                if not stream:
+                    console.print("\n[dim]Stopped watching.[/dim]")
+            finally:
+                if proc.poll() is None:
+                    proc.terminate()
+                    proc.wait()
             return
 
         from qbraid_core.services.agents import get_parser_for_tool, watch_transcript
@@ -2913,6 +3081,12 @@ def agents_watch(
             console.print("[dim]Use 'qbraid agents list' to see active sessions.[/dim]")
             raise typer.Exit(code=1)
 
+        if getattr(session, "runtime_kind", None) == "provider_child":
+            from .provider_children import watch_child
+
+            watch_child(registry, session.session_id, lines=lines, stream=stream, console=console)
+            return
+
         tool_value = session.tool.value if session.tool else None
 
         # OpenCode uses SQLite DB instead of transcript files