qbraid-cli 0.16.15__tar.gz → 0.16.16__tar.gz

{qbraid_cli-0.16.15/qbraid_cli.egg-info → qbraid_cli-0.16.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qbraid-cli
-Version: 0.16.15
+Version: 0.16.16
 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.34
+Requires-Dist: qbraid-core>=0.6.35
 Provides-Extra: compute
-Requires-Dist: qbraid-core[compute]>=0.6.34; extra == "compute"
+Requires-Dist: qbraid-core[compute]>=0.6.35; extra == "compute"
 Provides-Extra: envs
-Requires-Dist: qbraid-core[environments]>=0.6.34; extra == "envs"
+Requires-Dist: qbraid-core[environments]>=0.6.35; extra == "envs"
 Provides-Extra: dev
 Requires-Dist: isort; extra == "dev"
 Requires-Dist: black; extra == "dev"

{qbraid_cli-0.16.15 → qbraid_cli-0.16.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qbraid-cli"
-version = "0.16.15"
+version = "0.16.16"
 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.34",
+    "qbraid-core>=0.6.35",
 ]
 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.34"]
-envs = ["qbraid-core[environments]>=0.6.34"]
+compute = ["qbraid-core[compute]>=0.6.35"]
+envs = ["qbraid-core[environments]>=0.6.35"]
 dev = ["isort", "black", "pytest", "pytest-cov", "pytest-asyncio"]
 
 [project.scripts]

{qbraid_cli-0.16.15 → qbraid_cli-0.16.16}/qbraid_cli/agents/queue.py

@@ -25,15 +25,17 @@ _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"}
+_HOLD_CAPABILITY = "message-queue-hold-v1"
 
 
 class QueueCommandError(Exception):
     """A safe failure with a request identifier for reconciliation."""
 
-    def __init__(self, code, message, request_id=None):
+    def __init__(self, code, message, request_id=None, *, retryable=False):
         super().__init__(message)
         self.code = code
         self.request_id = request_id
+        self.retryable = retryable
 
 
 def _plain(value, multiline=False):
@@ -112,6 +114,59 @@ def _valid_receipt(value, session_id, machine_id):
     )
 
 
+def _valid_hold(value, session_id, binding, *, state="held"):
+    """Validate the Core hold schema and exact destination binding."""
+    keys = {
+        "id",
+        "sessionId",
+        "expectedRuntime",
+        "receiver",
+        "machineId",
+        "bootId",
+        "turn",
+        "revision",
+        "state",
+        "reason",
+        "createdAt",
+        "updatedAt",
+    }
+    if not isinstance(value, dict) or set(value) != keys or not _valid_runtime(value["expectedRuntime"]):
+        return False
+    runtime = value["expectedRuntime"]
+    if set(runtime) != {"pid", "startedAt", "tool", "terminalId", "serverId", "transcriptPath"}:
+        return False
+    receiver = value["receiver"]
+    native = receiver is None and all(
+        isinstance(runtime[key], str) and runtime[key] for key in ("terminalId", "serverId")
+    )
+    tmux = (
+        runtime["terminalId"] is None
+        and runtime["serverId"] is None
+        and isinstance(receiver, dict)
+        and bool(receiver)
+        and len(json.dumps(receiver)) <= 4096
+    )
+    return all(
+        (
+            _canonical_uuid(value["id"]),
+            value["sessionId"] == session_id,
+            value["machineId"] == binding["expectedMachineId"],
+            value["bootId"] == binding["expectedBootId"],
+            _stamp(runtime["startedAt"]),
+            isinstance(runtime["transcriptPath"], str) and bool(runtime["transcriptPath"]),
+            native or tmux,
+            isinstance(value["turn"], str) and re.fullmatch(r"[0-9a-f]{64}", value["turn"]),
+            isinstance(value["revision"], int)
+            and not isinstance(value["revision"], bool)
+            and value["revision"] > 0,
+            value["state"] == state,
+            isinstance(value["reason"], str),
+            _stamp(value["createdAt"]),
+            _stamp(value["updatedAt"]),
+        )
+    )
+
+
 def _new_protocol():
     try:
         from qbraid_core.services.agents.machine_protocol import MachineProtocol
@@ -281,7 +336,10 @@ class Destination:
                     "UNKNOWN_OUTCOME", "Unconfirmed destination error; inspect request status.", rid
                 )
             raise QueueCommandError(
-                error.get("code", "OPERATION_FAILED"), error.get("message", "Request failed."), rid
+                error.get("code", "OPERATION_FAILED"),
+                error.get("message", "Request failed."),
+                rid,
+                retryable=error.get("retryable") is True,
             )
         result = response.get("result")
         if not isinstance(result, dict):
@@ -381,6 +439,10 @@ def _emit(result, json_output, request_id=None, *, ok=True):
             envelope["requestId"] = request_id
         typer.echo(json.dumps(envelope, ensure_ascii=True))
     elif "messages" in result:
+        if result.get("hold"):
+            hold = result["hold"]
+            typer.echo(f"Queue paused. Hold {_plain(hold['id'])}, revision {_plain(hold['revision'])}.")
+            typer.echo("Use queue continue with this hold ID and revision to allow automatic delivery.")
         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  ")
@@ -396,18 +458,64 @@ def _emit(result, json_output, request_id=None, *, ok=True):
         typer.echo(status)
         if result.get("reason"):
             typer.echo(_plain(result["reason"]))
+    elif result.get("interruptRequested") is True:
+        typer.echo("Interrupt requested; queued input is paused.")
+    elif isinstance(result.get("hold"), dict) and result["hold"].get("state") == "released":
+        typer.echo("Queue continued. A running watcher will deliver when the agent is ready.")
+    elif result.get("waiting") == "BUSY":
+        typer.echo("Queue is busy; the watcher will retry on its next tick.")
+    elif "delivered" in result and isinstance(result["delivered"], list):
+        typer.echo(f"Delivered {len(result['delivered'])} queued message(s).")
+    elif isinstance(result.get("state"), str):
+        typer.echo(f"Request status: {_plain(result['state'])}")
+    elif type(result.get("canInterrupt")) is bool:  # pylint: disable=unidiomatic-typecheck
+        if result["canInterrupt"]:
+            typer.echo("Interrupt is available for the verified active turn.")
+        else:
+            reason = result.get("reason")
+            typer.echo(
+                f"Interrupt unavailable: {_plain(reason)}"
+                if isinstance(reason, str)
+                else "Interrupt unavailable."
+            )
     else:
-        typer.echo(_plain(json.dumps(result, ensure_ascii=True)))
+        # Never serialize arbitrary protocol results to a human terminal. Some
+        # operations include receiver identities and transcript paths.
+        typer.echo("Operation completed.")
 
 
 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)
+    result = None
+    for attempt in range(4):
+        try:
+            result = destination.call(operation, rid, **fields)
+            break
+        except QueueCommandError as error:
+            # Core marks only queue-lock refusals that happened before any
+            # durable state or terminal write as retryable. A BUSY code alone
+            # is insufficient: transport-queue BUSY may not carry that proof.
+            if not error.retryable or error.code != "BUSY" or attempt == 3:
+                raise
+            time.sleep(0.1 * (2**attempt))
+    assert result is not None  # every successful destination call returns a JSON object
     if operation == "interrupt":
         confirmed = (
-            result.get("interruptRequested") is True and result.get("sessionId") == fields["sessionId"]
+            result.get("interruptRequested") is True
+            and result.get("sessionId") == fields["sessionId"]
+            and _valid_hold(result.get("hold"), fields["sessionId"], destination.binding)
+            and result["hold"]["expectedRuntime"] == fields["expectedRuntime"]
+            and result["hold"]["turn"] == fields["expectedTurn"]
+        )
+    elif operation == "queue_resume":
+        hold = result.get("hold")
+        confirmed = (
+            _valid_hold(hold, fields["sessionId"], destination.binding, state="released")
+            and hold["id"] == fields["holdId"]
+            and hold["revision"] == fields["revision"] + 1
+            and hold["expectedRuntime"] == fields["expectedRuntime"]
         )
     else:
         expected_id = rid if operation == "queue_enqueue" else fields["messageId"]
@@ -463,8 +571,8 @@ def enqueue(
         )
         if not json_output:
             typer.echo(
-                "Queued input needs a running queue watcher on the destination. "
-                "Sent means terminal submission, not a model response."
+                "Queued input needs a running queue watcher. Check queue list for its status; "
+                "if paused, use queue continue with the displayed hold ID and revision."
             )
 
 
@@ -482,12 +590,29 @@ def list_messages(
         messages: list[dict] = []
         seen, seen_ids = set(), set()
         cursor = None
+        hold = None
+        hold_supported = _HOLD_CAPABILITY in destination.snapshot["capabilities"]
         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.")
+            if hold_supported:
+                current_hold = page.get("hold")
+                if (
+                    "hold" not in page
+                    or current_hold is not None
+                    and not _valid_hold(current_hold, session_id, destination.binding)
+                ):
+                    raise QueueCommandError("INVALID_RESPONSE", "Invalid queue hold receipt.")
+                if current_hold is not None and current_hold["expectedRuntime"] != destination.runtime(
+                    session_id
+                ):
+                    raise QueueCommandError("QUEUE_CHANGED", "The paused runtime changed; list it again.")
+                if cursor is not None and current_hold != hold:
+                    raise QueueCommandError("QUEUE_CHANGED", "The queue hold changed; list it again.")
+                hold = current_hold
             for row in page["messages"]:
                 if (
                     not _valid_receipt(row, session_id, destination.snapshot["machineId"])
@@ -499,7 +624,10 @@ def list_messages(
                 messages.append(row)
             cursor = page["nextCursor"]
             if cursor is None:
-                _emit({"messages": messages, "nextCursor": None}, json_output)
+                _emit(
+                    {"messages": messages, "nextCursor": None, **({"hold": hold} if hold_supported else {})},
+                    json_output,
+                )
                 return
             if (
                 not _canonical_uuid(cursor)
@@ -512,6 +640,33 @@ def list_messages(
         raise QueueCommandError("QUEUE_CHANGED", "Queue pagination changed; start the list again.")
 
 
+@queue_app.command("continue")
+def continue_queue(
+    session_id: str = typer.Argument(..., help="Exact destination session ID."),
+    hold_id: str = typer.Argument(..., help="Hold UUID shown by queue list."),
+    revision: int = typer.Option(..., "--revision", min=1, help="Hold revision shown by queue list."),
+    compute: Optional[str] = typer.Option(None, "--compute"),
+    request_id: Optional[str] = typer.Option(None, "--request-id"),
+    json_output: bool = typer.Option(False, "--json"),
+):
+    """Continue this paused queue.
+
+    Releases only the displayed hold. The watcher still checks turn completion,
+    pending approvals and uncertain messages; no input is sent by this command.
+    """
+    with _action(json_output, compute, _HOLD_CAPABILITY) as destination:
+        _mutation(
+            destination,
+            "queue_resume",
+            json_output,
+            request_id,
+            sessionId=session_id,
+            expectedRuntime=destination.runtime(session_id),
+            holdId=_uuid(hold_id),
+            revision=revision,
+        )
+
+
 @queue_app.command("edit")
 def edit(
     session_id: str = typer.Argument(...),
@@ -634,7 +789,12 @@ def watch(
             raise QueueCommandError(
                 "UNSUPPORTED_OPERATION", "Update qbraid-core to host queued delivery."
             ) from None
-        watcher = MessageQueue(destination.protocol)
+        # Opt in only when this CLI and destination share the hold contract.
+        # Older Core versions retain their original constructor signature.
+        watcher_options = (
+            {"track_native_holds": True} if _HOLD_CAPABILITY in destination.snapshot["capabilities"] else {}
+        )
+        watcher = MessageQueue(destination.protocol, **watcher_options)
         if not once and not json_output:
             typer.echo(f"Watching this machine's queue every {interval:g}s. Ctrl+C pauses delivery.")
         try:
@@ -670,11 +830,18 @@ def interrupt(
 ):
     """Interrupt one verified active turn.
 
-    Request one Escape, without ending the agent process.
+    Request one Escape and pause queued input, without ending the agent process.
     """
     with _action(json_output, compute, "interrupt-v1") as destination:
+        if _HOLD_CAPABILITY not in destination.snapshot["capabilities"]:
+            raise QueueCommandError(
+                "UNSUPPORTED_OPERATION",
+                "Update qbraid-core on this destination to pause queued input safely when interrupting.",
+            )
         runtime = destination.runtime(session_id)
-        offer = destination.call("interrupt_preflight", sessionId=session_id, expectedRuntime=runtime)
+        offer = destination.call(
+            "interrupt_preflight", sessionId=session_id, expectedRuntime=runtime, requireQueueHold=True
+        )
         if preflight:
             available = offer.get("canInterrupt") is True
             _emit(
@@ -697,6 +864,7 @@ def interrupt(
             sessionId=session_id,
             expectedRuntime=runtime,
             expectedTurn=offer["turn"],
+            requireQueueHold=True,
         )
         if not json_output:
-            typer.echo("Interrupt requested. This acknowledges Escape input, not that the agent has stopped.")
+            typer.echo("This acknowledges Escape input, not that the agent has stopped.")

{qbraid_cli-0.16.15 → qbraid_cli-0.16.16/qbraid_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qbraid-cli
-Version: 0.16.15
+Version: 0.16.16
 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.34
+Requires-Dist: qbraid-core>=0.6.35
 Provides-Extra: compute
-Requires-Dist: qbraid-core[compute]>=0.6.34; extra == "compute"
+Requires-Dist: qbraid-core[compute]>=0.6.35; extra == "compute"
 Provides-Extra: envs
-Requires-Dist: qbraid-core[environments]>=0.6.34; extra == "envs"
+Requires-Dist: qbraid-core[environments]>=0.6.35; extra == "envs"
 Provides-Extra: dev
 Requires-Dist: isort; extra == "dev"
 Requires-Dist: black; extra == "dev"

{qbraid_cli-0.16.15 → qbraid_cli-0.16.16}/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.34
+qbraid-core>=0.6.35
 
 [compute]
-qbraid-core[compute]>=0.6.34
+qbraid-core[compute]>=0.6.35
 
 [dev]
 isort
@@ -15,4 +15,4 @@ pytest-cov
 pytest-asyncio
 
 [envs]
-qbraid-core[environments]>=0.6.34
+qbraid-core[environments]>=0.6.35