qbraid-cli 0.13.1__tar.gz → 0.13.2__tar.gz

{qbraid_cli-0.13.1/qbraid_cli.egg-info → qbraid_cli-0.13.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qbraid-cli
-Version: 0.13.1
+Version: 0.13.2
 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

{qbraid_cli-0.13.1 → qbraid_cli-0.13.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qbraid-cli"
-version = "0.13.1"
+version = "0.13.2"
 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" }]

{qbraid_cli-0.13.1 → qbraid_cli-0.13.2}/qbraid_cli/admin/app.py

@@ -6,7 +6,7 @@ Module defining commands in the 'qbraid admin' namespace.
 
 """
 
-from typing import Optional
+from typing import List, Optional
 
 import typer
 
@@ -22,11 +22,11 @@ admin_app = typer.Typer(
 
 @admin_app.command(name="headers")
 def admin_headers(
-    src_paths: list[str] = typer.Argument(
+    src_paths: List[str] = typer.Argument(
         ..., help="Source file or directory paths to verify.", callback=validate_paths_exist
     ),
     header_type: HeaderType = typer.Option("default", "--type", "-t", help="Type of header to use."),
-    skip_files: list[str] = typer.Option([], "--skip", "-s", help="Files to skip during verification."),
+    skip_files: List[str] = typer.Option([], "--skip", "-s", help="Files to skip during verification."),
     fix: bool = typer.Option(
         False, "--fix", "-f", help="Whether to fix the headers instead of just verifying."
     ),

{qbraid_cli-0.13.1 → qbraid_cli-0.13.2}/qbraid_cli/admin/validation.py

@@ -7,13 +7,14 @@ Module for validating command arguments for qBraid admin commands.
 """
 
 import os
+from typing import List
 
 import typer
 
 from qbraid_cli.handlers import _format_list_items
 
 
-def validate_paths_exist(paths: list[str]) -> list[str]:
+def validate_paths_exist(paths: List[str]) -> List[str]:
     """Verifies that each path in the provided list exists."""
     non_existent_paths = [path for path in paths if not os.path.exists(path)]
     if non_existent_paths:

{qbraid_cli-0.13.1 → qbraid_cli-0.13.2}/qbraid_cli/agents/app.py

@@ -9,7 +9,7 @@ import signal
 import time
 from datetime import datetime
 from pathlib import Path
-from typing import Optional
+from typing import List, Optional
 
 import click
 import typer
@@ -49,6 +49,20 @@ hooks_app = typer.Typer(
 
 agents_app.add_typer(hooks_app, name="hooks")
 
+inbox_app = typer.Typer(
+    help=(
+        "Read messages sent to this agent's inbox.\n\n"
+        "Follow, filter unread, and mark-read messages sent to this agent\n"
+        "session's inbox. Inboxes are per-session JSONL files at\n"
+        "~/.qbraid/inboxes/. Every agent session has one; peers use\n"
+        "``qbraid agents send-to`` to write to it."
+    ),
+    no_args_is_help=False,
+    invoke_without_command=True,
+)
+
+agents_app.add_typer(inbox_app, name="inbox")
+
 console = Console()
 
 
@@ -267,7 +281,7 @@ def agents_deregister():
 def agents_list(
     tool: Optional[str] = typer.Option(None, "--tool", "-t", help="Filter by tool (claude, codeq, codex)"),
     status: Optional[str] = typer.Option(None, "--status", help="Filter by status"),
-    tag: Optional[list[str]] = typer.Option(None, "--tag", help="Filter by tag (repeatable)"),
+    tag: Optional[List[str]] = typer.Option(None, "--tag", help="Filter by tag (repeatable)"),
     since: Optional[str] = typer.Option(None, "--since", help="Time window (e.g., '1h', '30m', '2d')"),
     compute: Optional[str] = typer.Option(
         None, "--compute", "-c", help="SSH alias for remote compute (runs list on remote)"
@@ -704,7 +718,7 @@ def agents_status(
 @agents_app.command("update")
 def agents_update(
     session_id: str = typer.Argument(..., help="Session ID (full or prefix)"),
-    tags: Optional[list[str]] = typer.Option(
+    tags: Optional[List[str]] = typer.Option(
         None, "--tag", help="Tag to add (can be repeated)", show_default=False
     ),
     name: Optional[str] = typer.Option(None, "--name", help="Set terminal name for the session"),
@@ -1098,7 +1112,7 @@ def agents_launch(
     ),
     parent: Optional[str] = typer.Option(None, "--parent", help="Parent session ID"),
     team: Optional[str] = typer.Option(None, "--team", help="Team ID"),
-    tag: Optional[list[str]] = typer.Option(None, "--tag", help="Tags (repeatable)"),
+    tag: Optional[List[str]] = typer.Option(None, "--tag", help="Tags (repeatable)"),
     compute: Optional[str] = typer.Option(
         None, "--compute", "-c", help="SSH alias for remote compute server"
     ),
@@ -2261,3 +2275,589 @@ def hooks_uninstall():
     except Exception as e:
         handle_error(message=str(e))
         raise typer.Exit(code=1)
+
+
+# =============================================================================
+# Messaging: send-to / inbox / inbox mark-read
+# =============================================================================
+
+
+def _resolve_from_session(explicit: Optional[str]) -> str:
+    """Determine the sender session id.
+
+    Priority: explicit --from > QBRAID_SESSION_ID env var (set by the qBraid
+    launcher for every agent it spawns) > fail with a helpful error.
+    """
+    if explicit:
+        return explicit
+    env_sid = os.environ.get("QBRAID_SESSION_ID")
+    if env_sid:
+        return env_sid
+    console.print(
+        "[red]No sender session id available.[/red] "
+        "Pass --from <session-id>, or run this inside a qBraid-managed "
+        "agent shell (which sets QBRAID_SESSION_ID)."
+    )
+    raise typer.Exit(code=1)
+
+
+def _resolve_session_id(
+    explicit: Optional[str], registry=None, allow_missing_in_registry: bool = True
+) -> str:
+    """Determine which session to operate on (for inbox read/mark-read).
+
+    Priority:
+      1. ``explicit`` (from --session): full id, prefix, or tmux/terminal name.
+         Resolved via the registry so prefixes and names work (fixes Persona A's
+         "``inbox --session <prefix>`` returned empty" finding).
+      2. ``$QBRAID_SESSION_ID`` env var (set by the launcher for managed shells).
+      3. Fail with a helpful error.
+
+    When ``allow_missing_in_registry`` is True (the default for inbox ops),
+    a name/prefix that doesn't resolve is returned as-is — the inbox file
+    might still exist even if the registry entry has been pruned. This
+    preserves the "list old inbox that outlived its session" case.
+    """
+    if explicit:
+        if registry is not None:
+            match = _find_session_by_prefix(registry, explicit)
+            if match is not None:
+                return match.session_id
+        if allow_missing_in_registry:
+            return explicit
+        console.print(
+            f"[red]No session matched '{explicit}'.[/red] "
+            "Try 'qbraid agents list' to see available sessions."
+        )
+        raise typer.Exit(code=1)
+
+    env_sid = os.environ.get("QBRAID_SESSION_ID")
+    if env_sid:
+        return env_sid
+    console.print(
+        "[red]No session id.[/red] Pass --session <id>, or run this inside a "
+        "qBraid-managed agent shell (which sets QBRAID_SESSION_ID)."
+    )
+    raise typer.Exit(code=1)
+
+
+def _resolve_target_session(registry, identifier: str) -> str:
+    """Resolve a target-session identifier (full id / prefix / name) to a
+    session_id. Prints suggestions on miss.
+    """
+    match = _find_session_by_prefix(registry, identifier)
+    if match is None:
+        console.print(
+            f"[red]No session matched '{identifier}'.[/red] "
+            "Try 'qbraid agents list' to see available sessions."
+        )
+        raise typer.Exit(code=1)
+    return match.session_id
+
+
+def _resolve_team_targets(registry, team_id: str, exclude_session_id: Optional[str] = None) -> list:
+    """Return every session in a team, optionally excluding one (usually the sender).
+
+    Returns a list of ``AgentSession`` objects. Empty list if the team has no
+    members other than the excluded one.
+    """
+    all_sessions = registry.load_registry().sessions
+    members = [s for s in all_sessions if s.team_id == team_id and s.session_id != exclude_session_id]
+    return members
+
+
+def _parse_target_csv(csv: str, registry) -> list[str]:
+    """Parse ``--to A,B,C`` into a list of resolved session_ids.
+
+    Each token goes through ``_find_session_by_prefix`` — id, prefix, or
+    tmux/terminal name. Fails the whole call if ANY token doesn't resolve
+    (bulk sends are all-or-nothing to avoid partial delivery surprises).
+    """
+    tokens = [t.strip() for t in csv.split(",") if t.strip()]
+    resolved: list[str] = []
+    unresolved: list[str] = []
+    for tok in tokens:
+        match = _find_session_by_prefix(registry, tok)
+        if match is None:
+            unresolved.append(tok)
+        else:
+            resolved.append(match.session_id)
+    if unresolved:
+        console.print(
+            f"[red]No session matched: {', '.join(unresolved)}[/red]. " "Broadcast aborted; nothing sent."
+        )
+        raise typer.Exit(code=1)
+    return resolved
+
+
+def _deliver_to_many(
+    targets: list[str],
+    text: str,
+    from_sid: str,
+    message_type: str,
+    registry,
+    validate_permissions: bool,
+) -> int:
+    """Deliver one message to each target session_id; render results.
+
+    Returns a shell exit code: 0 = all delivered, 1 = zero delivered,
+    3 = partial success. Kept out of the command bodies so send-to and
+    broadcast can share it without duplicating error rendering.
+    """
+    # pylint: disable-next=import-outside-toplevel
+    from qbraid_core.services.agents import send_message
+
+    # pylint: disable-next=import-outside-toplevel
+    from qbraid_core.services.agents.exceptions import AgentMessagingError
+
+    delivered: list[tuple[str, str]] = []
+    failed: list[tuple[str, str]] = []
+    for target_sid in targets:
+        try:
+            msg = send_message(
+                from_session_id=from_sid,
+                to_session_id=target_sid,
+                text=text,
+                message_type=message_type,
+                registry=registry,
+                validate_permissions=validate_permissions,
+            )
+            delivered.append((target_sid, msg.id))
+        except AgentMessagingError as err:
+            failed.append((target_sid, str(err)))
+        except Exception as err:  # pylint: disable=broad-exception-caught
+            failed.append((target_sid, f"{type(err).__name__}: {err}"))
+
+    for sid, mid in delivered:
+        console.print(
+            f"[green]→[/green] Sent to [bold]{sid}[/bold] " f"[dim](id={mid}, type={message_type})[/dim]"
+        )
+    for sid, reason in failed:
+        console.print(f"[red]✗[/red] [bold]{sid}[/bold]: {reason}")
+
+    if failed and not delivered:
+        return 1
+    if failed:
+        return 3
+    return 0
+
+
+@agents_app.command("send-to")
+def agents_send_to(
+    to: str = typer.Argument(
+        ...,
+        help="Target session id (full or prefix), tmux window name, or terminal name.",
+    ),
+    text: str = typer.Argument(..., help="Message body."),
+    from_: Optional[str] = typer.Option(
+        None,
+        "--from",
+        help=(
+            "Sender session id. Defaults to $QBRAID_SESSION_ID (set by the "
+            "qBraid launcher for every managed agent shell)."
+        ),
+    ),
+    message_type: str = typer.Option(
+        "message",
+        "--type",
+        help=(
+            "One of: message, task_assignment, status_update, shutdown_request. "
+            "Controls how the recipient's UI/hooks categorize it."
+        ),
+    ),
+    no_permission_check: bool = typer.Option(
+        False,
+        "--no-permission-check",
+        help=(
+            "Skip the sender→target permission check (agent-type rules from "
+            "qbraid_core.services.agents.types.can_message). Use for testing."
+        ),
+    ),
+) -> None:
+    """Send a message to another agent's inbox.
+
+    For multi-recipient / team broadcast, use ``qbraid agents broadcast``.
+
+    Delivery is a JSONL append at ~/.qbraid/inboxes/<to-session-id>.jsonl
+    (local host only — cross-host messaging isn't yet supported and will raise
+    a clear error). Permission rules (leader/worker/observer/reviewer) are
+    enforced by default.
+    """
+    try:
+        # pylint: disable-next=import-outside-toplevel,unused-import
+        from qbraid_core.services.agents import send_message  # noqa: F401
+    except ImportError as err:
+        handle_error(message=f"qbraid-core messaging unavailable: {err}", include_traceback=False)
+        raise typer.Exit(code=1) from err
+
+    registry = _get_registry()
+    from_sid = _resolve_from_session(from_)
+    to_sid = _resolve_target_session(registry, to)
+
+    code = _deliver_to_many(
+        [to_sid],
+        text,
+        from_sid=from_sid,
+        message_type=message_type,
+        registry=registry,
+        validate_permissions=not no_permission_check,
+    )
+    if code:
+        raise typer.Exit(code=code)
+
+
+@agents_app.command("broadcast")
+def agents_broadcast(
+    text: str = typer.Argument(..., help="Message body — delivered to every target."),
+    team: Optional[str] = typer.Option(
+        None,
+        "--team",
+        help=(
+            "Deliver to every session with this team_id (excluding the sender). " "Use one of --team or --to."
+        ),
+    ),
+    to_csv: Optional[str] = typer.Option(
+        None,
+        "--to",
+        help=(
+            "Comma-separated list of target session ids/prefixes/names for "
+            "multi-recipient send. Use one of --team or --to."
+        ),
+    ),
+    from_: Optional[str] = typer.Option(
+        None,
+        "--from",
+        help="Sender session id. Defaults to $QBRAID_SESSION_ID.",
+    ),
+    message_type: str = typer.Option(
+        "message",
+        "--type",
+        help=(
+            "One of: message, task_assignment, status_update, shutdown_request. "
+            "Controls how the recipient's UI/hooks categorize it."
+        ),
+    ),
+    no_permission_check: bool = typer.Option(
+        False,
+        "--no-permission-check",
+        help="Skip the sender→target permission check. Use for testing.",
+    ),
+) -> None:
+    """Broadcast to multiple agent inboxes.
+
+    Two selectors — pick exactly one:
+      * ``--team <team_id>``  — every session with that team_id (except sender)
+      * ``--to A,B,C``        — explicit id/prefix/name list
+
+    Delivery is all-or-nothing on target resolution: if any target can't be
+    resolved, NOTHING is sent (avoids partial-delivery surprises). Once
+    resolved, per-target send failures are reported individually; a partial
+    delivery exits with code 3.
+    """
+    try:
+        # pylint: disable-next=import-outside-toplevel,unused-import
+        from qbraid_core.services.agents import send_message  # noqa: F401
+    except ImportError as err:
+        handle_error(message=f"qbraid-core messaging unavailable: {err}", include_traceback=False)
+        raise typer.Exit(code=1) from err
+
+    modes_used = sum(bool(x) for x in (team, to_csv))
+    if modes_used != 1:
+        # Use typer's own error path so exit code is 2 (usage error) not 1.
+        console.print("[red]Error:[/red] Use exactly one of --team or --to.")
+        raise typer.Exit(code=2)
+
+    registry = _get_registry()
+    from_sid = _resolve_from_session(from_)
+
+    if team is not None:
+        members = _resolve_team_targets(registry, team, exclude_session_id=from_sid)
+        if not members:
+            handle_error(
+                message=(
+                    f"No sessions found in team '{team}' (other than the sender). "
+                    "Check 'qbraid agents list' for team_id values."
+                ),
+                include_traceback=False,
+            )
+            raise typer.Exit(code=1)
+        targets = [m.session_id for m in members]
+    else:
+        # to_csv is not None due to the modes_used check above
+        assert to_csv is not None
+        targets = _parse_target_csv(to_csv, registry)
+
+    code = _deliver_to_many(
+        targets,
+        text,
+        from_sid=from_sid,
+        message_type=message_type,
+        registry=registry,
+        validate_permissions=not no_permission_check,
+    )
+    if code:
+        raise typer.Exit(code=code)
+
+
+def _render_messages_table(messages, session_id: str, full_ids: bool = False) -> None:
+    """Render a list of AgentMessage to the console as a table.
+
+    Args:
+        messages: list of AgentMessage.
+        session_id: session whose inbox we're rendering (for the title).
+        full_ids: when True, show full session_ids in the ``From`` column and
+            the table title. Default is a 12-char prefix so the table stays
+            narrow — but when ``list`` shows multiple sessions with the same
+            prefix, the prefix version is ambiguous (Persona A + B finding).
+    """
+    if not messages:
+        display_sid = session_id if full_ids else session_id[:12]
+        console.print(f"[dim]Inbox for {display_sid} is empty.[/dim]")
+        return
+
+    title_sid = session_id if full_ids else session_id[:12]
+    table = Table(show_header=True, header_style="bold", title=f"Inbox: {title_sid}")
+    table.add_column("Time", style="dim", no_wrap=True)
+    table.add_column("From", style="cyan", no_wrap=full_ids)
+    table.add_column("Type", style="yellow", no_wrap=True)
+    table.add_column("R", justify="center", no_wrap=True)
+    table.add_column("Message")
+
+    for msg in messages:
+        ts = datetime.fromtimestamp(msg.timestamp).strftime("%m-%d %H:%M")
+        read_marker = "[dim]✓[/dim]" if msg.read else "[bold red]•[/bold red]"
+        from_display = msg.from_session if full_ids else msg.from_session[:12]
+        table.add_row(
+            ts,
+            from_display,
+            msg.type.value,
+            read_marker,
+            msg.text,
+        )
+    console.print(table)
+
+
+@inbox_app.callback()
+def inbox_default(  # pylint: disable=too-many-arguments
+    ctx: typer.Context,
+    session: Optional[str] = typer.Option(
+        None,
+        "--session",
+        "-s",
+        help=(
+            "Session whose inbox to read. Accepts full id, prefix, or "
+            "tmux/terminal name (resolved via the registry). Defaults to "
+            "$QBRAID_SESSION_ID."
+        ),
+    ),
+    follow: bool = typer.Option(False, "--follow", "-f", help="Stream new messages as they arrive."),
+    unread: bool = typer.Option(False, "--unread", "-u", help="Show only unread messages."),
+    limit: int = typer.Option(50, "--limit", "-n", help="Max messages to show (most recent)."),
+    mark_read_flag: bool = typer.Option(
+        True,
+        "--mark-read/--no-mark-read",
+        help="Mark shown messages as read after display. Default on.",
+    ),
+    wide: bool = typer.Option(
+        False,
+        "--wide",
+        "-w",
+        help=(
+            "Show full session ids in the From column and title (not the "
+            "12-char prefix). Use when multiple senders share a prefix."
+        ),
+    ),
+) -> None:
+    """Read messages from an agent session's inbox.
+
+    Without a subcommand this reads the inbox (optionally streams with
+    --follow). Use ``qbraid agents inbox mark-read`` to mark manually.
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+
+    try:
+        # pylint: disable-next=import-outside-toplevel
+        from qbraid_core.services.agents import mark_read, read_inbox, watch_inbox
+    except ImportError as err:
+        handle_error(message=f"qbraid-core messaging unavailable: {err}", include_traceback=False)
+        raise typer.Exit(code=1) from err
+
+    # Registry-aware resolution so `--session <prefix>` and tmux names work
+    # — Persona A's #1 finding was that inbox silently returned "empty"
+    # for a valid prefix. Registry is only touched when an explicit
+    # --session was passed, so the env-var-fallback code path stays cheap
+    # and testable without mocking the registry.
+    session_id = _resolve_session_id(session, registry=_get_registry() if session else None)
+
+    if follow:
+        existing = read_inbox(session_id, unread_only=unread, limit=limit)
+        _render_messages_table(existing, session_id, full_ids=wide)
+        if mark_read_flag and existing:
+            mark_read(session_id, message_ids=[m.id for m in existing if not m.read])
+
+        console.print("[dim]Watching for new messages… Ctrl-C to stop.[/dim]")
+        try:
+            for msg in watch_inbox(session_id):
+                ts = datetime.fromtimestamp(msg.timestamp).strftime("%H:%M:%S")
+                from_display = msg.from_session if wide else msg.from_session[:12]
+                console.print(
+                    f"[dim]{ts}[/dim] "
+                    f"[cyan]{from_display}[/cyan] "
+                    f"[yellow]({msg.type.value})[/yellow] {msg.text}"
+                )
+                if mark_read_flag:
+                    mark_read(session_id, message_ids=[msg.id])
+        except KeyboardInterrupt:
+            console.print("[dim]Stopped watching.[/dim]")
+        return
+
+    messages = read_inbox(session_id, unread_only=unread, limit=limit)
+    _render_messages_table(messages, session_id, full_ids=wide)
+
+    if mark_read_flag and messages:
+        unread_ids = [m.id for m in messages if not m.read]
+        if unread_ids:
+            n = mark_read(session_id, message_ids=unread_ids)
+            if n:
+                console.print(f"[dim]Marked {n} message(s) as read.[/dim]")
+
+
+@inbox_app.command("mark-read")
+def inbox_mark_read(
+    session: Optional[str] = typer.Option(
+        None,
+        "--session",
+        "-s",
+        help=(
+            "Session whose inbox to update. Accepts full id, prefix, or "
+            "tmux/terminal name. Defaults to $QBRAID_SESSION_ID."
+        ),
+    ),
+    message_id: Optional[List[str]] = typer.Option(
+        None,
+        "--message-id",
+        "-m",
+        help=(
+            "Specific message id(s) to mark. May be passed multiple times. "
+            "Omit to mark ALL unread messages in the inbox."
+        ),
+    ),
+) -> None:
+    """Mark inbox messages as read.
+
+    Without --message-id, marks every unread message in the session's inbox.
+    """
+    try:
+        # pylint: disable-next=import-outside-toplevel
+        from qbraid_core.services.agents import mark_read
+    except ImportError as err:
+        handle_error(message=f"qbraid-core messaging unavailable: {err}", include_traceback=False)
+        raise typer.Exit(code=1) from err
+
+    session_id = _resolve_session_id(session, registry=_get_registry() if session else None)
+    ids = list(message_id) if message_id else None
+
+    n = mark_read(session_id, message_ids=ids)
+    console.print(f"[green]Marked {n} message(s) as read[/green] for {session_id[:12]}.")
+
+
+# =============================================================================
+# `qbraid agents team <id>` — leader-centric roster view
+# =============================================================================
+
+
+@agents_app.command("team")
+def agents_team(
+    team_id: str = typer.Argument(..., help="Team identifier (matches AgentSession.team_id)."),
+    wide: bool = typer.Option(
+        False,
+        "--wide",
+        "-w",
+        help="Show full session ids instead of the 12-char prefix.",
+    ),
+) -> None:
+    """Show a team roster with unread counts.
+
+    Answers the leader-orchestrator question "who is on my team, how many
+    unread messages do they have, and what was the last thing they heard from
+    anyone?" — which today requires peeking each worker's inbox individually.
+
+    Rows are sorted with the current session first (identified via
+    $QBRAID_SESSION_ID), then by agent_type (leader → worker → observer →
+    reviewer), then by session_id.
+    """
+    try:
+        # pylint: disable-next=import-outside-toplevel
+        from qbraid_core.services.agents import read_inbox
+    except ImportError as err:
+        handle_error(message=f"qbraid-core messaging unavailable: {err}", include_traceback=False)
+        raise typer.Exit(code=1) from err
+
+    registry = _get_registry()
+    all_sessions = registry.load_registry().sessions
+    members = [s for s in all_sessions if s.team_id == team_id]
+
+    if not members:
+        console.print(
+            f"[yellow]No sessions found with team_id '{team_id}'.[/yellow] "
+            "Check 'qbraid agents list' for known team_ids."
+        )
+        raise typer.Exit(code=0)
+
+    me_sid = os.environ.get("QBRAID_SESSION_ID")
+    role_order = {"leader": 0, "worker": 1, "reviewer": 2, "observer": 3}
+
+    def _sort_key(session):
+        return (
+            0 if session.session_id == me_sid else 1,
+            role_order.get(session.agent_type or "worker", 99),
+            session.session_id,
+        )
+
+    members.sort(key=_sort_key)
+
+    table = Table(
+        show_header=True,
+        header_style="bold",
+        title=f"Team: {team_id} ({len(members)} member{'s' if len(members) != 1 else ''})",
+    )
+    table.add_column("You", justify="center", no_wrap=True)
+    table.add_column("Session", style="cyan", no_wrap=wide)
+    table.add_column("Type", style="yellow", no_wrap=True)
+    table.add_column("Status", no_wrap=True)
+    table.add_column("Unread", justify="right", no_wrap=True)
+    table.add_column("Last msg from", style="dim")
+    table.add_column("Last msg text", style="dim")
+
+    status_styles = {"idle": "green", "active": "green", "stopped": "red"}
+
+    for s in members:
+        try:
+            # Read up to 10K so the unread count reflects the full inbox
+            # for realistic sizes (matches watch_inbox's cap). Members with
+            # >10K messages will still undercount, but that's the same
+            # boundary the follower uses.
+            inbox = read_inbox(s.session_id, limit=10_000)
+        except Exception:  # pylint: disable=broad-exception-caught
+            inbox = []
+        unread_count = sum(1 for m in inbox if not m.read)
+        last = inbox[-1] if inbox else None
+
+        session_display = s.session_id if wide else s.session_id[:12]
+        last_from = (last.from_session if wide else last.from_session[:12]) if last else "-"
+        last_text = (last.text[:60] + "…") if last and len(last.text) > 60 else (last.text if last else "-")
+        status_style = status_styles.get(s.status or "", "dim")
+        unread_style = "bold red" if unread_count else "dim"
+
+        table.add_row(
+            "★" if s.session_id == me_sid else "",
+            session_display,
+            s.agent_type or "worker",
+            f"[{status_style}]{s.status or 'unknown'}[/{status_style}]",
+            f"[{unread_style}]{unread_count}[/{unread_style}]",
+            last_from,
+            last_text,
+        )
+
+    console.print(table)

{qbraid_cli-0.13.1 → qbraid_cli-0.13.2}/qbraid_cli/envs/app.py

@@ -10,7 +10,7 @@ import shlex
 import subprocess
 import sys
 from pathlib import Path
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING, List, Optional
 
 import typer
 from qbraid_core.services.environments.schema import EnvironmentConfig
@@ -359,11 +359,23 @@ def envs_create(  # pylint: disable=too-many-statements
 @envs_app.command(name="uninstall")
 def envs_uninstall(
     name: str = typer.Option(..., "-n", "--name", help="Name of the environment to remove"),
+    delete_cloud: bool = typer.Option(
+        False,
+        "--delete-cloud",
+        "-c",
+        help=(
+            "Also delete the environment from qBraid cloud (requires ownership). "
+            "By default only the local copy is removed and the cloud slug is preserved, "
+            "so you can reinstall it later."
+        ),
+    ),
     auto_confirm: bool = typer.Option(False, "--yes", "-y", help="Automatically answer 'yes' to all prompts"),
 ) -> None:
     """Remove a local environment.
 
-    Removes a qBraid environment from your filesystem.
+    By default this removes only the local copy — the cloud environment is
+    preserved so you can reinstall it later. Pass ``--delete-cloud`` to also
+    retire the cloud environment (requires ownership).
     """
     import asyncio
 
@@ -374,38 +386,55 @@ def envs_uninstall(
         emc = EnvironmentManagerClient()
 
         # Run async uninstall method
-        result = asyncio.run(emc.uninstall_environment_local(slug, delete_metadata=True, force=auto_confirm))
+        result = asyncio.run(
+            emc.uninstall_environment_local(slug, delete_metadata=delete_cloud, force=auto_confirm)
+        )
         return result
 
-    def gather_local_data(env_name: str) -> tuple[Path | None, str | None]:
-        """Get environment path and env_id from name, env_id, or slug."""
+    def gather_local_data(env_name: str) -> tuple[Path | None, str | None, str | None]:
+        """Return ``(path, env_id, slug)`` for a name/env_id/slug lookup.
+
+        ``slug`` is ``None`` when the env was never uploaded (local-only env);
+        the ``--delete-cloud`` hint below uses this to avoid pointing users at
+        a flag that would be a no-op for their env.
+        """
+        from qbraid_core.services.environments.registry import EnvironmentRegistryManager
+
         installed, aliases = installed_envs_data()
+        registry_mgr = None
+
+        def _slug_for(env_id: str) -> str | None:
+            nonlocal registry_mgr
+            try:
+                if registry_mgr is None:
+                    registry_mgr = EnvironmentRegistryManager()
+                entry = registry_mgr.registry.environments.get(env_id)
+                return entry.slug if entry else None
+            except Exception:
+                return None
+
         # Try to find by name first, then by env_id
         if env_name in aliases:
             env_id = aliases[env_name]
-            path = installed[env_id]
-            return path, env_id
+            return installed[env_id], env_id, _slug_for(env_id)
         if env_name in installed:
-            # Direct env_id lookup
-            path = installed[env_name]
-            return path, env_name
+            return installed[env_name], env_name, _slug_for(env_name)
 
         # Fall back to slug lookup via registry
         try:
-            from qbraid_core.services.environments.registry import EnvironmentRegistryManager
-
-            registry_mgr = EnvironmentRegistryManager()
+            if registry_mgr is None:
+                registry_mgr = EnvironmentRegistryManager()
             match = registry_mgr.find_by_slug(env_name)
             if match:
                 env_id, entry = match
                 if entry.path.exists():
-                    return entry.path, env_id
+                    return entry.path, env_id, entry.slug
         except Exception:
             pass
 
-        return None, None
+        return None, None, None
 
-    env_path, env_id = gather_local_data(name)
+    env_path, env_id, env_slug = gather_local_data(name)
 
     if env_path is None:
         console = Console()
@@ -414,12 +443,28 @@ def envs_uninstall(
         console.print("[dim]Run 'qbraid envs list' to see all installed environments.[/dim]")
         raise typer.Exit(0)
 
+    # Only hint at --delete-cloud when there's actually a cloud copy to delete.
+    # Local-only envs (never uploaded → no slug) would treat --delete-cloud as
+    # a no-op, so mentioning it there is confusing.
+    if delete_cloud:
+        scope_line = (
+            "This will remove the local install AND permanently delete the environment "
+            "from qBraid cloud. This operation CANNOT be undone."
+        )
+    elif env_slug:
+        scope_line = (
+            "This will remove only the LOCAL copy. The cloud environment is preserved "
+            "so you can reinstall it later — pass --delete-cloud to also delete from "
+            "qBraid cloud."
+        )
+    else:
+        scope_line = (
+            "This will remove the local copy. (No cloud environment associated — this "
+            "env was never uploaded.)"
+        )
     confirmation_message = (
-        f"⚠️  Warning: You are about to delete the environment '{name}' "
-        f"located at '{env_path}'.\n"
-        "This will remove all local packages and permanently delete all "
-        "of its associated qBraid environment metadata.\n"
-        "This operation CANNOT be undone.\n\n"
+        f"⚠️  About to remove the environment '{name}' at '{env_path}'.\n"
+        f"{scope_line}\n\n"
         "Are you sure you want to continue?"
     )
 
@@ -433,9 +478,28 @@ def envs_uninstall(
         )
 
         if result.get("deleted_metadata"):
-            typer.echo(f"✅ Environment '{name}' successfully removed (local files and metadata).")
+            typer.echo(f"✅ Environment '{name}' removed (local files and cloud metadata).")
+        elif delete_cloud:
+            # User asked for cloud delete but it didn't happen. Point them at
+            # the actionable diagnostic — a missing slug is the common cause;
+            # otherwise re-run with QBRAID_LOG_LEVEL=DEBUG to surface the API
+            # error the core swallowed at line 3098 of environments/client.py.
+            reason = (
+                "no cloud slug is registered for this environment"
+                if not env_slug
+                else "re-run with QBRAID_LOG_LEVEL=DEBUG to see the underlying API error"
+            )
+            typer.echo(
+                f"✅ Environment '{name}' removed locally. Cloud delete was requested "
+                f"but skipped ({reason})."
+            )
+        elif env_slug:
+            typer.echo(
+                f"✅ Environment '{name}' removed locally. "
+                "Cloud copy preserved (pass --delete-cloud to also remove from qBraid cloud)."
+            )
         else:
-            typer.echo(f"✅ Environment '{name}' successfully removed (local files only).")
+            typer.echo(f"✅ Environment '{name}' removed locally.")
 
 
 @envs_app.command(name="delete")
@@ -1243,6 +1307,7 @@ def envs_install(
                         overwrite=yes,
                         progress_callback=progress_callback,
                         auto_install_python=False,  # We handled Python above
+                        env_info=env_info,  # skip the internal fetch — we already have it
                     )
 
                 console.print("")
@@ -1698,8 +1763,8 @@ def envs_config(
     tags: Optional[str] = typer.Option(
         None, "--tags", help="Replace tags (comma-separated, use '' to clear)"
     ),
-    add_tag: Optional[list[str]] = typer.Option(None, "--add-tag", help="Append a tag (repeatable)"),
-    remove_tag: Optional[list[str]] = typer.Option(None, "--remove-tag", help="Remove a tag (repeatable)"),
+    add_tag: Optional[List[str]] = typer.Option(None, "--add-tag", help="Append a tag (repeatable)"),
+    remove_tag: Optional[List[str]] = typer.Option(None, "--remove-tag", help="Remove a tag (repeatable)"),
     kernel_name: Optional[str] = typer.Option(
         None, "--kernel-name", help="Update Jupyter kernel display name"
     ),

{qbraid_cli-0.13.1 → qbraid_cli-0.13.2}/qbraid_cli/lab/app.py

@@ -12,7 +12,6 @@ rejected before our code runs.
 import os
 import sys
 
-import click
 import typer
 
 app = typer.Typer(help="Launch qBraid Lab (JupyterLab).")
@@ -43,6 +42,9 @@ def lab_command(_ctx: typer.Context):
     try:
         os.execvp("jupyter-lab", ["jupyter-lab"] + jupyter_args)
     except FileNotFoundError:
-        raise click.UsageError(
-            "jupyter-lab is not installed or not on PATH. Install qBraid Lab first: pip install qbraid-lab"
+        typer.echo(
+            "Error: jupyter-lab is not installed or not on PATH. "
+            "Install qBraid Lab first: pip install qbraid-lab",
+            err=True,
         )
+        raise typer.Exit(code=1)

{qbraid_cli-0.13.1 → qbraid_cli-0.13.2/qbraid_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qbraid-cli
-Version: 0.13.1
+Version: 0.13.2
 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