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

{qbraid_cli-0.16.11/qbraid_cli.egg-info → qbraid_cli-0.16.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qbraid-cli
-Version: 0.16.11
+Version: 0.16.12
 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.29
+Requires-Dist: qbraid-core>=0.6.30
 Provides-Extra: compute
-Requires-Dist: qbraid-core[compute]>=0.6.29; extra == "compute"
+Requires-Dist: qbraid-core[compute]>=0.6.30; extra == "compute"
 Provides-Extra: envs
-Requires-Dist: qbraid-core[environments]>=0.6.29; extra == "envs"
+Requires-Dist: qbraid-core[environments]>=0.6.30; extra == "envs"
 Provides-Extra: dev
 Requires-Dist: isort; extra == "dev"
 Requires-Dist: black; extra == "dev"

{qbraid_cli-0.16.11 → qbraid_cli-0.16.12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qbraid-cli"
-version = "0.16.11"
+version = "0.16.12"
 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.29",
+    "qbraid-core>=0.6.30",
 ]
 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.29"]
-envs = ["qbraid-core[environments]>=0.6.29"]
+compute = ["qbraid-core[compute]>=0.6.30"]
+envs = ["qbraid-core[environments]>=0.6.30"]
 dev = ["isort", "black", "pytest", "pytest-cov", "pytest-asyncio"]
 
 [project.scripts]

{qbraid_cli-0.16.11 → qbraid_cli-0.16.12}/qbraid_cli/agents/app.py

@@ -23,6 +23,7 @@ from rich.table import Table
 
 from qbraid_cli.handlers import handle_error, run_progress_task
 
+from .queue import interrupt, queue_app
 from .work import register_work_commands
 
 agents_app = typer.Typer(
@@ -54,6 +55,8 @@ hooks_app = typer.Typer(
 )
 
 agents_app.add_typer(hooks_app, name="hooks")
+agents_app.add_typer(queue_app, name="queue")
+agents_app.command("interrupt")(interrupt)
 
 inbox_app = typer.Typer(
     help=(

qbraid_cli-0.16.12/qbraid_cli/agents/queue.py

@@ -0,0 +1,702 @@
+# Copyright (c) 2026, qBraid Development Team
+# All rights reserved.
+
+"""Destination-bound queued follow-ups and turn interruption."""
+
+import json
+import math
+import os
+import re
+import subprocess
+import tempfile
+import threading
+import time
+import unicodedata
+import uuid
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+queue_app = typer.Typer(help="Queue follow-ups for a managed runtime.", no_args_is_help=True)
+_MAX_REQUEST = 256 * 1024
+_MAX_RESPONSE = 2 * 1024 * 1024
+_SSH_TIMEOUT = 120
+_STATES = {"queued", "sending", "sent", "uncertain", "cancelled", "stale", "expired", "resolved"}
+_ACTION_STATES = {"queue_edit": "queued", "queue_cancel": "cancelled", "queue_resolve": "resolved"}
+
+
+class QueueCommandError(Exception):
+    """A safe failure with a request identifier for reconciliation."""
+
+    def __init__(self, code, message, request_id=None):
+        super().__init__(message)
+        self.code = code
+        self.request_id = request_id
+
+
+def _plain(value, multiline=False):
+    text = str(value)
+    allowed = {"\n", "\u200c", "\u200d"} if multiline else set()
+    if multiline:
+        text = text.replace("\r\n", "\n").expandtabs(4)
+    return "".join(
+        (
+            "\ufffd"
+            if char not in allowed and unicodedata.category(char) in {"Cc", "Cf", "Cs", "Zl", "Zp"}
+            else char
+        )
+        for char in text
+    )
+
+
+def _canonical_uuid(value):
+    try:
+        return isinstance(value, str) and str(uuid.UUID(value)) == value
+    except ValueError:
+        return False
+
+
+def _uuid(value=None):
+    if value is None:
+        return str(uuid.uuid4())
+    if not _canonical_uuid(value):
+        raise QueueCommandError("INVALID_ARGUMENT", "Use a canonical UUID for request/message IDs.")
+    return value
+
+
+def _stamp(value):
+    try:
+        return type(value) in (int, float) and math.isfinite(value) and value > 0
+    except OverflowError:
+        return False
+
+
+def _valid_runtime(value):
+    keys = {"pid", "startedAt", "tool", "terminalId", "serverId", "transcriptPath"}
+    if not isinstance(value, dict) or not keys <= value.keys():
+        return False
+    return all(
+        (
+            isinstance(value["pid"], int) and not isinstance(value["pid"], bool) and value["pid"] > 0,
+            value["startedAt"] is None or _stamp(value["startedAt"]),
+            value["tool"] in ("claude", "codex"),
+            all(
+                value[key] is None or isinstance(value[key], str)
+                for key in ("terminalId", "serverId", "transcriptPath")
+            ),
+        )
+    )
+
+
+def _valid_receipt(value, session_id, machine_id):
+    """Validate destination-bound history without rejecting earlier boot receipts."""
+    if not isinstance(value, dict):
+        return False
+    return all(
+        (
+            _canonical_uuid(value.get("id")),
+            value.get("sessionId") == session_id,
+            value.get("machineId") == machine_id,
+            isinstance(value.get("bootId"), str) and bool(value["bootId"]),
+            _valid_runtime(value.get("expectedRuntime")),
+            isinstance(value.get("text"), str) and bool(value["text"]),
+            isinstance(value.get("state"), str) and value["state"] in _STATES,
+            isinstance(value.get("revision"), int)
+            and not isinstance(value["revision"], bool)
+            and value["revision"] > 0,
+            all(_stamp(value.get(key)) for key in ("createdAt", "updatedAt", "expiresAt")),
+            "reason" not in value or isinstance(value["reason"], str),
+        )
+    )
+
+
+def _new_protocol():
+    try:
+        from qbraid_core.services.agents.machine_protocol import MachineProtocol
+    except ImportError:
+        raise QueueCommandError(
+            "UNSUPPORTED_OPERATION", "Update qbraid-core on this destination to enable queue controls."
+        ) from None
+    return MachineProtocol()
+
+
+def _ssh_exchange(command, payload):
+    """Bound stdout while the owned SSH child runs, including on Windows pipes."""
+    # Only stdin is spooled, and it has already passed the 256 KiB request bound.
+    # SSH startup output never touches disk; stderr is never captured or shown.
+    with tempfile.TemporaryFile() as incoming:
+        incoming.write(payload)
+        incoming.seek(0)
+        deadline = time.monotonic() + _SSH_TIMEOUT
+        # Explicit finally below must kill before waiting when output overflows.
+        child = subprocess.Popen(  # pylint: disable=consider-using-with
+            command, stdin=incoming, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL
+        )
+        output = bytearray()
+        failed = []
+        done = threading.Event()
+        stopped = threading.Event()
+        descriptor = child.stdout.fileno()
+
+        def read_output():
+            try:
+                while not stopped.is_set() and len(output) <= _MAX_RESPONSE:
+                    chunk = os.read(descriptor, min(65536, _MAX_RESPONSE + 1 - len(output)))
+                    if not chunk:
+                        return
+                    output.extend(chunk)
+            except OSError:
+                failed.append(True)
+            finally:
+                done.set()
+
+        reader = threading.Thread(target=read_output, daemon=True)
+        try:
+            reader.start()
+            if not done.wait(max(0, deadline - time.monotonic())):
+                raise subprocess.TimeoutExpired(command, _SSH_TIMEOUT)
+            if len(output) > _MAX_RESPONSE or failed:
+                raise OSError("Destination output exceeded its bound or could not be read.")
+            code = child.wait(timeout=max(0, deadline - time.monotonic()))
+            if code:
+                raise OSError("Destination protocol exited unsuccessfully.")
+            return bytes(output)
+        finally:
+            # This is only the SSH child just created by this request. Never
+            # kill a destination agent or infer that its operation did not run.
+            stopped.set()
+            if child.poll() is None:
+                child.kill()
+            child.wait(timeout=5)
+            if reader.ident is not None:
+                reader.join(timeout=1)
+            child.stdout.close()
+
+
+def _remote_request(compute, request):
+    """One SSH request, with payload on stdin and no transport replay."""
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.@:-]{0,254}", compute):
+        raise QueueCommandError("INVALID_ARGUMENT", "Use a configured SSH alias for --compute.")
+    encoded = json.dumps(request, ensure_ascii=True, allow_nan=False).encode() + b"\n"
+    if len(encoded) > _MAX_REQUEST:
+        raise QueueCommandError("REQUEST_TOO_LARGE", "Request exceeds the 256 KiB protocol limit.")
+    try:
+        raw = _ssh_exchange(
+            [
+                "ssh",
+                "-T",
+                "-o",
+                "BatchMode=yes",
+                "-o",
+                "ConnectTimeout=10",
+                compute,
+                "qbraid agents machine --once",
+            ],
+            encoded,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        raise QueueCommandError(
+            "UNKNOWN_OUTCOME",
+            "Destination reply was unavailable or exceeded its size/time limit. "
+            "No request was retried; reconcile its status.",
+            request["id"],
+        ) from None
+    try:
+        return json.loads(raw)
+    except (ValueError, UnicodeError, RecursionError):
+        raise QueueCommandError(
+            "UNKNOWN_OUTCOME", "Invalid destination reply. No request was retried.", request["id"]
+        ) from None
+
+
+class Destination:
+    """One capability-checked machine/boot snapshot retained through an action."""
+
+    def __init__(self, compute=None, capability="message-queue-v1"):
+        self.compute = compute
+        self.protocol = None if compute else _new_protocol()
+        self.binding = {}
+        try:
+            self.snapshot = self.call("snapshot")
+            if not isinstance(self.snapshot.get("capabilities"), list) or not isinstance(
+                self.snapshot.get("sessions"), list
+            ):
+                raise QueueCommandError("INVALID_RESPONSE", "Invalid destination snapshot.")
+            if capability not in self.snapshot.get("capabilities", []):
+                raise QueueCommandError(
+                    "UNSUPPORTED_OPERATION",
+                    f"Destination does not support {capability}. "
+                    "Update its qbraid-core before using this command.",
+                )
+            if not all(
+                isinstance(self.snapshot.get(key), str) and self.snapshot[key]
+                for key in ("machineId", "bootId")
+            ):
+                raise QueueCommandError("INVALID_RESPONSE", "Destination identity is missing.")
+            self.binding = {
+                "expectedMachineId": self.snapshot["machineId"],
+                "expectedBootId": self.snapshot["bootId"],
+            }
+        except BaseException:
+            self.close()
+            raise
+
+    def close(self):
+        """Release local display subscriptions without affecting agent processes."""
+        if self.protocol is not None:
+            self.protocol.close()
+
+    def call(self, operation, request_id=None, **fields):
+        """Dispatch exactly once; keep the caller's request ID on any failure."""
+        rid = _uuid(request_id)
+        request = {"id": rid, "op": operation, **self.binding, **fields}
+        if len(json.dumps(request, ensure_ascii=True, allow_nan=False).encode()) + 1 > _MAX_REQUEST:
+            raise QueueCommandError("REQUEST_TOO_LARGE", "Request exceeds the 256 KiB protocol limit.", rid)
+        try:
+            response = (
+                _remote_request(self.compute, request) if self.compute else self.protocol.handle(request)
+            )
+        except QueueCommandError:
+            raise
+        except Exception:
+            raise QueueCommandError(
+                "UNKNOWN_OUTCOME", "Destination reply failed; inspect request status before retrying.", rid
+            ) from None
+        if (
+            not isinstance(response, dict)
+            or response.get("id") != rid
+            or not isinstance(response.get("ok"), bool)
+        ):
+            raise QueueCommandError(
+                "UNKNOWN_OUTCOME", "Unconfirmed destination response; inspect request status.", rid
+            )
+        if response["ok"] is False:
+            error = response.get("error") or {}
+            if not isinstance(error, dict) or not all(
+                isinstance(error.get(key), str) for key in ("code", "message")
+            ):
+                raise QueueCommandError(
+                    "UNKNOWN_OUTCOME", "Unconfirmed destination error; inspect request status.", rid
+                )
+            raise QueueCommandError(
+                error.get("code", "OPERATION_FAILED"), error.get("message", "Request failed."), rid
+            )
+        result = response.get("result")
+        if not isinstance(result, dict):
+            raise QueueCommandError(
+                "UNKNOWN_OUTCOME", "Unconfirmed destination result; inspect request status.", rid
+            )
+        return result
+
+    def runtime(self, session_id):
+        """Resolve only the exact session ID from the destination's displayed rows."""
+        rows = [
+            row
+            for row in self.snapshot["sessions"]
+            if isinstance(row, dict) and row.get("sessionId") == session_id
+        ]
+        if len(rows) != 1:
+            raise QueueCommandError(
+                "SESSION_NOT_FOUND", "Use the full session ID listed on the selected destination."
+            )
+        row = rows[0]
+        metadata = row.get("metadata") or {}
+        if not isinstance(metadata, dict):
+            raise QueueCommandError("INVALID_RESPONSE", "Invalid destination runtime metadata.")
+        return {
+            "pid": row.get("pid"),
+            "startedAt": row.get("startedAt"),
+            "tool": row.get("tool"),
+            "terminalId": metadata.get("jupyter_terminal_id"),
+            "serverId": metadata.get("jupyter_server_id"),
+            "transcriptPath": row.get("transcriptPath"),
+        }
+
+
+@contextmanager
+def _action(json_output, compute=None, capability="message-queue-v1"):
+    destination = None
+    try:
+        destination = Destination(compute, capability)
+        yield destination
+    except QueueCommandError as error:
+        result = {"ok": False, "error": {"code": error.code, "message": str(error)}}
+        if error.request_id:
+            result["requestId"] = error.request_id
+        if json_output:
+            typer.echo(json.dumps(result, ensure_ascii=True))
+        else:
+            typer.echo(f"{_plain(error.code)}: {_plain(error)}", err=True)
+            if error.request_id:
+                typer.echo(f"Request ID: {_plain(error.request_id)}.", err=True)
+                if error.code in {"UNKNOWN_OUTCOME", "INDETERMINATE", "OPERATION_FAILED"}:
+                    typer.echo("Inspect queue list and queue request-status before retrying.", err=True)
+        raise typer.Exit(1) from None
+    except typer.Exit:
+        raise
+    except Exception:
+        if json_output:
+            typer.echo(
+                json.dumps(
+                    {
+                        "ok": False,
+                        "error": {
+                            "code": "OPERATION_FAILED",
+                            "message": "Local queue operation failed. Inspect state before retrying.",
+                        },
+                    }
+                )
+            )
+        else:
+            typer.echo("Local queue operation failed. Inspect state before retrying.", err=True)
+        raise typer.Exit(1) from None
+    finally:
+        if destination is not None:
+            destination.close()
+
+
+def _text(text, file):
+    if (text is None) == (file is None):
+        raise QueueCommandError("INVALID_ARGUMENT", "Choose exactly one of --text or --file.")
+    if file is not None:
+        try:
+            with Path(file).open("rb") as stream:
+                raw = stream.read(32768 * 4 + 1)
+            if len(raw) > 32768 * 4:
+                raise QueueCommandError("INVALID_ARGUMENT", "Use 1–32768 characters of plain text.")
+            text = raw.decode("utf-8")
+        except (OSError, UnicodeError):
+            raise QueueCommandError("INVALID_ARGUMENT", "Cannot read the message file as UTF-8.") from None
+    if not isinstance(text, str) or not text.strip() or len(text) > 32768:
+        raise QueueCommandError("INVALID_ARGUMENT", "Use 1–32768 characters of plain text.")
+    return text
+
+
+def _emit(result, json_output, request_id=None, *, ok=True):
+    if json_output:
+        envelope = {"ok": ok, "result": result}
+        if request_id:
+            envelope["requestId"] = request_id
+        typer.echo(json.dumps(envelope, ensure_ascii=True))
+    elif "messages" in result:
+        for row in result["messages"]:
+            typer.echo(f"{_plain(row['id'])}  {_plain(row['state'])}  revision {_plain(row['revision'])}")
+            prose = _plain(row["text"], multiline=True).replace("\n", "\n  ")
+            typer.echo(f"  {prose}")
+            if row.get("reason"):
+                typer.echo(f"  {_plain(row['reason'])}")
+        if not result["messages"]:
+            typer.echo("No queued messages or retained receipts.")
+    elif "state" in result and "id" in result:
+        status = f"{_plain(result['id'])}  {_plain(result['state'])}"
+        if "revision" in result:
+            status += f"  revision {_plain(result['revision'])}"
+        typer.echo(status)
+        if result.get("reason"):
+            typer.echo(_plain(result["reason"]))
+    else:
+        typer.echo(_plain(json.dumps(result, ensure_ascii=True)))
+
+
+def _mutation(destination, operation, json_output, request_id, **fields):
+    rid = _uuid(request_id)
+    # Written before crossing the transport, so even Ctrl+C leaves the ID visible.
+    typer.echo(f"Request ID: {rid}", err=True)
+    result = destination.call(operation, rid, **fields)
+    if operation == "interrupt":
+        confirmed = (
+            result.get("interruptRequested") is True and result.get("sessionId") == fields["sessionId"]
+        )
+    else:
+        expected_id = rid if operation == "queue_enqueue" else fields["messageId"]
+        confirmed = (
+            _valid_receipt(result, fields["sessionId"], destination.snapshot["machineId"])
+            and result["id"] == expected_id
+        )
+        if confirmed and operation == "queue_enqueue":
+            confirmed = (
+                result["bootId"] == destination.snapshot["bootId"]
+                and result["expectedRuntime"] == fields["expectedRuntime"]
+                and (result["revision"] != 1 or result["text"] == fields["text"].replace("\r\n", "\n"))
+            )
+        elif confirmed:
+            # Edits/resolution can address older-boot history. The displayed
+            # revision and action bind the receipt without silently refetching.
+            confirmed = (
+                result["revision"] == fields["revision"] + 1
+                and result["state"] == _ACTION_STATES.get(operation)
+                and (operation != "queue_edit" or result["text"] == fields["text"].replace("\r\n", "\n"))
+            )
+    if not confirmed:
+        raise QueueCommandError(
+            "UNKNOWN_OUTCOME", "No valid operation receipt was confirmed; inspect request status.", rid
+        )
+    _emit(result, json_output, rid)
+
+
+@queue_app.command("enqueue")
+def enqueue(
+    session_id: str = typer.Argument(..., help="Exact destination session ID."),
+    text: Optional[str] = typer.Option(None, "--text", help="Plain follow-up text."),
+    file: Optional[Path] = typer.Option(None, "--file", help="UTF-8 text file (at most 32768 characters)."),
+    compute: Optional[str] = typer.Option(None, "--compute", help="Destination SSH alias."),
+    request_id: Optional[str] = typer.Option(
+        None, "--request-id", help="Retain this UUID to reconcile a lost reply."
+    ),
+    json_output: bool = typer.Option(False, "--json"),
+):
+    """Queue a follow-up for this runtime.
+
+    Delivery waits for a confirmed completed turn and a running watcher.
+    """
+    with _action(json_output, compute) as destination:
+        _mutation(
+            destination,
+            "queue_enqueue",
+            json_output,
+            request_id,
+            sessionId=session_id,
+            expectedRuntime=destination.runtime(session_id),
+            text=_text(text, file),
+        )
+        if not json_output:
+            typer.echo(
+                "Queued input needs a running queue watcher on the destination. "
+                "Sent means terminal submission, not a model response."
+            )
+
+
+@queue_app.command("list")
+def list_messages(
+    session_id: str = typer.Argument(...),
+    compute: Optional[str] = typer.Option(None, "--compute"),
+    json_output: bool = typer.Option(False, "--json"),
+):
+    """List retained messages and delivery state.
+
+    Includes uncertain outcomes and wait reasons across all receipt pages.
+    """
+    with _action(json_output, compute) as destination:
+        messages: list[dict] = []
+        seen, seen_ids = set(), set()
+        cursor = None
+        for _ in range(257):
+            page = destination.call(
+                "queue_list", sessionId=session_id, **({"cursor": cursor} if cursor else {})
+            )
+            if not isinstance(page.get("messages"), list) or "nextCursor" not in page:
+                raise QueueCommandError("INVALID_RESPONSE", "Invalid queue listing.")
+            for row in page["messages"]:
+                if (
+                    not _valid_receipt(row, session_id, destination.snapshot["machineId"])
+                    or row["id"] in seen_ids
+                    or len(messages) >= 256
+                ):
+                    raise QueueCommandError("INVALID_RESPONSE", "Invalid or repeated queue receipts.")
+                seen_ids.add(row["id"])
+                messages.append(row)
+            cursor = page["nextCursor"]
+            if cursor is None:
+                _emit({"messages": messages, "nextCursor": None}, json_output)
+                return
+            if (
+                not _canonical_uuid(cursor)
+                or cursor in seen
+                or not page["messages"]
+                or cursor != page["messages"][-1]["id"]
+            ):
+                break
+            seen.add(cursor)
+        raise QueueCommandError("QUEUE_CHANGED", "Queue pagination changed; start the list again.")
+
+
+@queue_app.command("edit")
+def edit(
+    session_id: str = typer.Argument(...),
+    message_id: str = typer.Argument(...),
+    revision: int = typer.Option(..., "--revision", min=1, help="Revision shown by queue list."),
+    text: Optional[str] = typer.Option(None, "--text"),
+    file: Optional[Path] = typer.Option(None, "--file"),
+    compute: Optional[str] = typer.Option(None, "--compute"),
+    request_id: Optional[str] = typer.Option(None, "--request-id"),
+    json_output: bool = typer.Option(False, "--json"),
+):
+    """Edit a queued message at its revision.
+
+    A concurrent delivery or edit refuses this operation.
+    """
+    with _action(json_output, compute) as destination:
+        _mutation(
+            destination,
+            "queue_edit",
+            json_output,
+            request_id,
+            sessionId=session_id,
+            messageId=_uuid(message_id),
+            revision=revision,
+            text=_text(text, file),
+        )
+
+
+@queue_app.command("cancel")
+def cancel(
+    session_id: str = typer.Argument(...),
+    message_id: str = typer.Argument(...),
+    revision: int = typer.Option(..., "--revision", min=1),
+    compute: Optional[str] = typer.Option(None, "--compute"),
+    request_id: Optional[str] = typer.Option(None, "--request-id"),
+    json_output: bool = typer.Option(False, "--json"),
+):
+    """Cancel a queued message at its revision.
+
+    This cannot interrupt a message already submitted.
+    """
+    with _action(json_output, compute) as destination:
+        _mutation(
+            destination,
+            "queue_cancel",
+            json_output,
+            request_id,
+            sessionId=session_id,
+            messageId=_uuid(message_id),
+            revision=revision,
+        )
+
+
+@queue_app.command("resolve")
+def resolve(
+    session_id: str = typer.Argument(...),
+    message_id: str = typer.Argument(...),
+    revision: int = typer.Option(..., "--revision", min=1),
+    terminal_checked: bool = typer.Option(
+        False, "--terminal-checked", help="Confirm you inspected the terminal and cleared partial input."
+    ),
+    compute: Optional[str] = typer.Option(None, "--compute"),
+    request_id: Optional[str] = typer.Option(None, "--request-id"),
+    json_output: bool = typer.Option(False, "--json"),
+):
+    """Resolve an uncertain delivery.
+
+    Check the terminal and clear partial input first. This never resends text.
+    """
+    with _action(json_output, compute) as destination:
+        if not terminal_checked:
+            raise QueueCommandError(
+                "INVALID_ARGUMENT",
+                "Inspect the terminal and clear partial input, then pass --terminal-checked.",
+            )
+        _mutation(
+            destination,
+            "queue_resolve",
+            json_output,
+            request_id,
+            sessionId=session_id,
+            messageId=_uuid(message_id),
+            revision=revision,
+            terminalChecked=True,
+        )
+
+
+@queue_app.command("request-status")
+def request_status(
+    request_id: str = typer.Argument(...),
+    compute: Optional[str] = typer.Option(None, "--compute"),
+    json_output: bool = typer.Option(False, "--json"),
+):
+    """Inspect a request without replaying it.
+
+    Not-found does not prove non-delivery.
+    """
+    with _action(json_output, compute) as destination:
+        result = destination.call("request_status", requestId=_uuid(request_id))
+        _emit(result, json_output)
+
+
+@queue_app.command("watch")
+def watch(
+    once: bool = typer.Option(False, "--once", help="Run one delivery tick and exit."),
+    interval: float = typer.Option(4.0, "--interval", min=1.0, max=60.0),
+    json_output: bool = typer.Option(False, "--json", help="Emit one JSON object per tick."),
+):
+    """Host queued delivery on this machine.
+
+    Run on the destination; Ctrl+C pauses delivery.
+    Closing this watcher preserves queued input. A tick sends at most one message
+    per session; an uncertain write pauses that runtime until explicitly resolved.
+    """
+    with _action(json_output) as destination:
+        try:
+            from qbraid_core.services.agents.message_queue import MessageQueue
+            from qbraid_core.services.agents.runtime_controls import SessionControlError
+        except ImportError:
+            raise QueueCommandError(
+                "UNSUPPORTED_OPERATION", "Update qbraid-core to host queued delivery."
+            ) from None
+        watcher = MessageQueue(destination.protocol)
+        if not once and not json_output:
+            typer.echo(f"Watching this machine's queue every {interval:g}s. Ctrl+C pauses delivery.")
+        try:
+            while True:
+                try:
+                    delivered = watcher.poll_once()
+                    result = {
+                        "delivered": delivered,
+                        "machineId": destination.snapshot["machineId"],
+                        "bootId": destination.snapshot["bootId"],
+                    }
+                except SessionControlError as error:
+                    if error.code != "BUSY":
+                        raise QueueCommandError(error.code, str(error)) from error
+                    result = {"delivered": [], "waiting": "BUSY"}
+                _emit(result, json_output)
+                if once:
+                    return
+                time.sleep(interval)
+        except KeyboardInterrupt:
+            if not json_output:
+                typer.echo("Watcher stopped; queue preserved. Inspect uncertain receipts before retrying.")
+
+
+def interrupt(
+    session_id: str = typer.Argument(..., help="Exact destination session ID."),
+    preflight: bool = typer.Option(
+        False, "--preflight", help="Inspect availability and turn without sending Escape."
+    ),
+    compute: Optional[str] = typer.Option(None, "--compute"),
+    request_id: Optional[str] = typer.Option(None, "--request-id"),
+    json_output: bool = typer.Option(False, "--json"),
+):
+    """Interrupt one verified active turn.
+
+    Request one Escape, without ending the agent process.
+    """
+    with _action(json_output, compute, "interrupt-v1") as destination:
+        runtime = destination.runtime(session_id)
+        offer = destination.call("interrupt_preflight", sessionId=session_id, expectedRuntime=runtime)
+        if preflight:
+            available = offer.get("canInterrupt") is True
+            _emit(
+                {**offer, "sessionId": session_id, "expectedRuntime": runtime, **destination.binding},
+                json_output,
+                ok=available,
+            )
+            if not available:
+                raise typer.Exit(1)
+            return
+        if offer.get("canInterrupt") is not True or not isinstance(offer.get("turn"), str):
+            raise QueueCommandError(
+                "CONTROL_UNAVAILABLE", offer.get("reason") or "No supported active turn is confirmed."
+            )
+        _mutation(
+            destination,
+            "interrupt",
+            json_output,
+            request_id,
+            sessionId=session_id,
+            expectedRuntime=runtime,
+            expectedTurn=offer["turn"],
+        )
+        if not json_output:
+            typer.echo("Interrupt requested. This acknowledges Escape input, not that the agent has stopped.")

{qbraid_cli-0.16.11 → qbraid_cli-0.16.12/qbraid_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qbraid-cli
-Version: 0.16.11
+Version: 0.16.12
 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.29
+Requires-Dist: qbraid-core>=0.6.30
 Provides-Extra: compute
-Requires-Dist: qbraid-core[compute]>=0.6.29; extra == "compute"
+Requires-Dist: qbraid-core[compute]>=0.6.30; extra == "compute"
 Provides-Extra: envs
-Requires-Dist: qbraid-core[environments]>=0.6.29; extra == "envs"
+Requires-Dist: qbraid-core[environments]>=0.6.30; extra == "envs"
 Provides-Extra: dev
 Requires-Dist: isort; extra == "dev"
 Requires-Dist: black; extra == "dev"

{qbraid_cli-0.16.11 → qbraid_cli-0.16.12}/qbraid_cli.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ qbraid_cli/admin/validation.py
 qbraid_cli/agents/__init__.py
 qbraid_cli/agents/app.py
 qbraid_cli/agents/permission_response.py
+qbraid_cli/agents/queue.py
 qbraid_cli/agents/work.py
 qbraid_cli/ai/__init__.py
 qbraid_cli/ai/app.py

{qbraid_cli-0.16.11 → qbraid_cli-0.16.12}/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.29
+qbraid-core>=0.6.30
 
 [compute]
-qbraid-core[compute]>=0.6.29
+qbraid-core[compute]>=0.6.30
 
 [dev]
 isort
@@ -15,4 +15,4 @@ pytest-cov
 pytest-asyncio
 
 [envs]
-qbraid-core[environments]>=0.6.29
+qbraid-core[environments]>=0.6.30