qbraid-cli 0.16.6__tar.gz → 0.16.8__tar.gz

{qbraid_cli-0.16.6/qbraid_cli.egg-info → qbraid_cli-0.16.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qbraid-cli
-Version: 0.16.6
+Version: 0.16.8
 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.15
+Requires-Dist: qbraid-core>=0.6.19
 Provides-Extra: compute
-Requires-Dist: qbraid-core[compute]>=0.6.15; extra == "compute"
+Requires-Dist: qbraid-core[compute]>=0.6.19; extra == "compute"
 Provides-Extra: envs
-Requires-Dist: qbraid-core[environments]>=0.6.15; extra == "envs"
+Requires-Dist: qbraid-core[environments]>=0.6.19; extra == "envs"
 Provides-Extra: dev
 Requires-Dist: isort; extra == "dev"
 Requires-Dist: black; extra == "dev"
@@ -172,5 +172,5 @@ qbraid comms email send --subject "Progress" --file report.txt --json
 qbraid comms slack read --json
 ```
 
-See [communication commands](docs/comms-cli.md) for Slack connection, stdin input,
-pagination, and deployment requirements.
+See [communication commands](https://docs.qbraid.com/v2/cli/api-reference/qbraid_comms) for Slack connection, stdin input,
+message limits, and pagination.

{qbraid_cli-0.16.6 → qbraid_cli-0.16.8}/README.md

@@ -127,5 +127,5 @@ qbraid comms email send --subject "Progress" --file report.txt --json
 qbraid comms slack read --json
 ```
 
-See [communication commands](docs/comms-cli.md) for Slack connection, stdin input,
-pagination, and deployment requirements.
+See [communication commands](https://docs.qbraid.com/v2/cli/api-reference/qbraid_comms) for Slack connection, stdin input,
+message limits, and pagination.

{qbraid_cli-0.16.6 → qbraid_cli-0.16.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qbraid-cli"
-version = "0.16.6"
+version = "0.16.8"
 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.15",
+    "qbraid-core>=0.6.19",
 ]
 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.15"]
-envs = ["qbraid-core[environments]>=0.6.15"]
+compute = ["qbraid-core[compute]>=0.6.19"]
+envs = ["qbraid-core[environments]>=0.6.19"]
 dev = ["isort", "black", "pytest", "pytest-cov", "pytest-asyncio"]
 
 [project.scripts]

{qbraid_cli-0.16.6 → qbraid_cli-0.16.8}/qbraid_cli/agents/app.py

@@ -17,6 +17,7 @@ from typing import Any, Callable, Dict, List, Optional
 import click
 import typer
 from rich.console import Console
+from rich.markup import escape
 from rich.panel import Panel
 from rich.table import Table
 
@@ -114,7 +115,6 @@ def _remote_failure(stdout: str, stderr: str) -> str:
     "Session not found" into "Warning: Permanently added ... to the list of
     known hosts", which names the one thing that went right.
     """
-    from rich.markup import escape
 
     def useful(text: str) -> list[str]:
         # The remote's Rich error panel arrives as box-drawing borders around
@@ -204,12 +204,91 @@ def _since_to_timestamp(since_str: str) -> float:
     return time.time() - seconds
 
 
+def _plain(value) -> str:
+    """A user- or agent-supplied value, escaped so Rich prints it literally."""
+    return escape(str(value))
+
+
+def _core_method(registry, name: str):
+    """A registry method the installed qbraid-core actually defines, else None.
+
+    Checked on the class so older Core releases (and test doubles) fall back
+    to the previous behavior instead of calling a missing method.
+    """
+    if not callable(getattr(type(registry), name, None)):
+        return None
+    return getattr(registry, name)
+
+
+def _calling_session(registry) -> Optional[str]:
+    """The live agent session this command runs inside, if any.
+
+    Newer qbraid-core finds it by process ancestry, so unsetting
+    QBRAID_SESSION_ID does not make an agent look like the person, and a
+    person typing in a pane that kept the variable is not mistaken for the
+    agent that exited. Older Core falls back to the variable, unless it names
+    a session the registry records as stopped or errored.
+    """
+    find = _core_method(registry, "calling_session")
+    if find is not None:
+        try:
+            return find()
+        except Exception as err:  # pylint: disable=broad-exception-caught
+            if _is_registry_error(err):
+                # Core could not tell which agent this is (for example, the
+                # caller matches more than one live session). Refuse rather
+                # than fail open to "the person".
+                console.print(
+                    f"[red]Cannot tell which agent session this command runs in: {_plain(err)}[/red]"
+                )
+                raise typer.Exit(code=1) from err
+            # any other failure: fall back to the variable, as older Core does
+    env_sid = os.environ.get("QBRAID_SESSION_ID") or None
+    if env_sid and _session_status(registry, env_sid) in ("stopped", "error"):
+        return None
+    return env_sid
+
+
+def _is_registry_error(err: Exception) -> bool:
+    """Whether ``err`` is qbraid-core's AgentRegistryError (or a subclass)."""
+    try:
+        # pylint: disable-next=import-outside-toplevel
+        from qbraid_core.services.agents.exceptions import AgentRegistryError
+    except ImportError:
+        return False
+    return isinstance(err, AgentRegistryError)
+
+
+def _session_status(registry, session_id: str) -> Optional[str]:
+    """The registry status of a session ("stopped", "working", ...), or None
+    when it is not registered or the registry cannot be read."""
+    try:
+        session = registry.get_session(session_id)
+    except Exception:  # pylint: disable=broad-exception-caught
+        return None
+    status = getattr(session, "status", None)
+    value = getattr(status, "value", status)
+    return value if isinstance(value, str) else None
+
+
 def _find_session_by_prefix(registry, session_id: str):
     """Find a session by ID, prefix, or name from the registry.
 
     Searches session_id (exact/prefix), then tmux_window and terminal_name.
     Returns the matched AgentSession or None.
     """
+    resolve = _core_method(registry, "resolve_session")
+    if resolve is not None:
+        # Newer Core: exact id, unique prefix, then a name that prefers the live
+        # session over stopped namesakes; ambiguity is an error, not a guess.
+        try:
+            return resolve(session_id)
+        except Exception as err:  # pylint: disable=broad-exception-caught
+            if type(err).__name__ != "AgentSessionAmbiguousError":
+                raise
+            console.print(f"[red]{_plain(err)}[/red]")
+            raise typer.Exit(code=1) from err
+
     all_sessions = registry.load_registry().sessions
 
     # Try session_id exact or prefix match first
@@ -766,9 +845,9 @@ def agents_status(
 
         # Team info
         if s.team_id:
-            lines.append(f"[bold]Team ID:[/bold]    {s.team_id}")
+            lines.append(f"[bold]Team ID:[/bold]    {_plain(s.team_id)}")
         if s.role:
-            lines.append(f"[bold]Role:[/bold]       {s.role}")
+            lines.append(f"[bold]Role:[/bold]       {_plain(s.role)}")
 
         # Transcript path
         if s.transcript_path:
@@ -807,8 +886,24 @@ def agents_update(
     status: Optional[str] = typer.Option(
         None, "--status", help="Set session status (working, waiting, idle, error, stopped)"
     ),
+    agent_type: Optional[str] = typer.Option(
+        None,
+        "--type",
+        help="Set the agent type (leader, worker, observer, reviewer); '' clears it.",
+    ),
+    team: Optional[str] = typer.Option(None, "--team", help="Join a team by id; '' leaves it."),
+    parent: Optional[str] = typer.Option(
+        None, "--parent", help="Set the parent session (id, prefix or name); '' clears it."
+    ),
 ):
-    """Update metadata fields on an agent session."""
+    """Update metadata fields on an agent session.
+
+    --type, --team and --parent let agents started from a terminal join a
+    team after launch, so they can message each other. From your own shell
+    any change is allowed. Inside an agent, it may only place teamless
+    sessions or its teammates into a team it leads, never as or out of
+    leader. These are coordination guardrails, not a security boundary.
+    """
     try:
         from qbraid_core.services.agents import (
             AgentSessionNotFoundError,
@@ -820,7 +915,7 @@ def agents_update(
         # Support prefix and name matching
         match = _find_session_by_prefix(registry, session_id)
         if not match:
-            console.print(f"[red]Session not found: {session_id}[/red]")
+            console.print(f"[red]Session not found: {_plain(session_id)}[/red]")
             console.print("[dim]Use 'qbraid agents list' to see active sessions.[/dim]")
             raise typer.Exit(code=1)
         matched_id = match.session_id
@@ -842,7 +937,9 @@ def agents_update(
             valid_statuses = {"working", "waiting", "idle", "error", "stopped"}
             if status not in valid_statuses:
                 valid_opts = ", ".join(sorted(valid_statuses))
-                console.print(f"[red]Invalid status: {status!r}." f" Must be one of: {valid_opts}[/red]")
+                console.print(
+                    f"[red]Invalid status: {_plain(repr(status))}. Must be one of: {valid_opts}[/red]"
+                )
                 raise typer.Exit(code=1)
             updates["status"] = status
 
@@ -854,31 +951,70 @@ def agents_update(
                     merged.append(t)
             updates["tags"] = merged
 
-        if not updates:
+        team_change = agent_type is not None or team is not None or parent is not None
+        if not updates and not team_change:
             console.print(
-                "[yellow]No updates specified. Use --name, --model, --cwd, --status, or --tag.[/yellow]"
+                "[yellow]No updates specified. Use --name, --model, --cwd, --status, --tag, "
+                "--type, --team or --parent.[/yellow]"
             )
             raise typer.Exit(code=0)
 
-        updated = registry.update_session(matched_id, **updates)
+        if team_change:
+            assign = _core_method(registry, "assign_team")
+            if assign is None:
+                console.print(
+                    "[red]This qbraid-core cannot change a session's team or role.[/red] "
+                    "Upgrade qbraid-core, or launch the agent with --type/--team/--parent."
+                )
+                raise typer.Exit(code=1)
+            parent_id = parent
+            if parent:
+                parent_match = _find_session_by_prefix(registry, parent)
+                if not parent_match:
+                    console.print(f"[red]Parent session not found: {_plain(parent)}[/red]")
+                    raise typer.Exit(code=1)
+                parent_id = parent_match.session_id
+            try:
+                assign(
+                    matched_id,
+                    team_id=team,
+                    agent_type=agent_type,
+                    parent_session_id=parent_id,
+                    actor_session_id=_calling_session(registry),
+                )
+            except AgentSessionNotFoundError:
+                raise
+            except Exception as err:  # pylint: disable=broad-exception-caught
+                console.print(f"[red]{_plain(err)}[/red]")
+                raise typer.Exit(code=1) from err
+
+        updated = (
+            registry.update_session(matched_id, **updates) if updates else registry.get_session(matched_id)
+        )
 
         # Display updated session info
         status_val = updated.status.value if updated.status else "idle"
         style = _status_style(status_val)
 
+        # Every value here can come from a user or an agent: escape it so a
+        # name or team such as "[/]" prints literally instead of breaking Rich.
         lines = []
-        lines.append(f"[bold]Session ID:[/bold]  {updated.session_id}")
+        lines.append(f"[bold]Session ID:[/bold]  {_plain(updated.session_id)}")
         lines.append(f"[bold]Tool:[/bold]        {updated.tool.value if updated.tool else '-'}")
-        lines.append(f"[bold]Status:[/bold]      [{style}]{status_val}[/{style}]")
-        lines.append(f"[bold]Model:[/bold]       {updated.model_name or '-'}")
-        lines.append(f"[bold]Name:[/bold]        {updated.terminal_name or '-'}")
-        lines.append(f"[bold]CWD:[/bold]         {updated.cwd or '-'}")
+        lines.append(f"[bold]Status:[/bold]      [{style}]{_plain(status_val)}[/{style}]")
+        lines.append(f"[bold]Model:[/bold]       {_plain(updated.model_name or '-')}")
+        lines.append(f"[bold]Name:[/bold]        {_plain(updated.terminal_name or '-')}")
+        lines.append(f"[bold]CWD:[/bold]         {_plain(updated.cwd or '-')}")
         if updated.tags:
-            lines.append(f"[bold]Tags:[/bold]        {', '.join(updated.tags)}")
+            lines.append(f"[bold]Tags:[/bold]        {_plain(', '.join(updated.tags))}")
+        if updated.agent_type or updated.team_id or updated.parent_session_id:
+            lines.append(f"[bold]Type:[/bold]        {_plain(updated.agent_type or 'worker (default)')}")
+            lines.append(f"[bold]Team:[/bold]        {_plain(updated.team_id or '-')}")
+            lines.append(f"[bold]Parent:[/bold]      {_plain(updated.parent_session_id or '-')}")
 
         panel = Panel(
             "\n".join(lines),
-            title=f"Updated Session [{updated.session_id[:8]}]",
+            title=_plain(f"Updated Session [{updated.session_id[:8]}]"),
             border_style="green",
         )
         console.print(panel)
@@ -886,7 +1022,7 @@ def agents_update(
     except (typer.Exit, SystemExit):
         raise
     except AgentSessionNotFoundError:
-        console.print(f"[red]Session not found: {session_id}[/red]")
+        console.print(f"[red]Session not found: {_plain(session_id)}[/red]")
         console.print("[dim]Use 'qbraid agents list' to see active sessions.[/dim]")
         raise typer.Exit(code=1)
     except Exception as e:
@@ -1278,6 +1414,27 @@ def _request_id_kwargs(method: Callable[..., Any], request_id: Optional[str]) ->
     return {"request_id": request_id}
 
 
+def _fork_execution(original: Any, approval: Optional[Any], execution_mode: Optional[Any]):
+    """Execution mode for a fork of ``original``.
+
+    An explicit --execution-mode wins. Otherwise the original's mode is reused
+    -- unless it was YOLO's forced container and the fork asks for a safer
+    approval, or the fork asks for auto-review, which Core pins to the
+    workspace sandbox. Inheriting there carried danger-full-access into a
+    session labelled manual or auto-review (core#378 review F2).
+    """
+    if execution_mode:
+        return execution_mode.value
+    requested = approval.value if approval else None
+    recorded = getattr(original, "approval", None)
+    effective = requested or recorded
+    if effective in ("auto-review", "yolo") or (recorded == "yolo" and requested not in (None, "yolo")):
+        # auto-review is pinned to workspace and yolo to container by core;
+        # passing the original's mode would make core refuse the fork.
+        return None
+    return getattr(original, "execution_mode", None)
+
+
 def _approval_kwargs(method: Callable[..., Any], approval: Optional[str]) -> Dict[str, Any]:
     """Forward ``approval`` only to a qbraid-core new enough to accept it.
 
@@ -1425,6 +1582,43 @@ def agents_settings(
         handle_error(error_type=type(error).__name__, message=str(error), include_traceback=False)
 
 
+def _hook_trust_kwargs(method, value):
+    """Fail before launch when an explicit choice cannot be honored."""
+    if value is None:
+        return {}
+
+    from qbraid_core.services.agents import AgentLauncherError
+
+    params = inspect.signature(method).parameters
+    if "trust_hooks" not in params and not any(
+        p.kind is inspect.Parameter.VAR_KEYWORD for p in params.values()
+    ):
+        raise AgentLauncherError("Hook trust requires a newer qbraid-core on this machine.")
+    return {"trust_hooks": value}
+
+
+def _startup_pending(session):
+    return session.tool.value in ("codex", "claude") and not getattr(session, "startup_confirmed_at", None)
+
+
+def _startup_notice(session, compute=None):
+    import shlex
+
+    suffix = f" --compute {shlex.quote(compute)}" if compute else ""
+    if _startup_pending(session):
+        console.print(
+            "Session created; startup is not yet confirmed. It may be waiting for sign-in, "
+            "folder trust, or hook review. The initial task waits until setup is complete.",
+            markup=False,
+        )
+        if session.tool.value == "codex":
+            console.print(
+                "Approve hooks in the agent's terminal (/hooks); Codex remembers unchanged ones.",
+                markup=False,
+            )
+    console.print(f"  qbraid agents attach {shlex.quote(session.session_id)}{suffix}", markup=False)
+
+
 @agents_app.command("launch")
 def agents_launch(
     backend: TerminalBackend = typer.Option(
@@ -1470,6 +1664,15 @@ def agents_launch(
             "decides. yolo: no permission checks. ask/auto: legacy modes, unchanged."
         ),
     ),
+    trust_hooks: bool = typer.Option(
+        False,
+        "--trust-hooks",
+        help=(
+            "Codex only, DANGEROUS: run ALL enabled hooks (yours, the project's and "
+            "plugins') without Codex's hook review, for this launch only. Not retained on "
+            "resume. Refused with --repo. Independent of --approval and --yolo."
+        ),
+    ),
     yolo: bool = typer.Option(
         False, "--yolo", help="Claude: skip permissions. Codex: bypass approvals and its sandbox."
     ),
@@ -1498,6 +1701,14 @@ def agents_launch(
             tag = tag or result.get("tags")
             repo = repo or result.get("repo")
 
+        if trust_hooks and repo:
+            # Codex would run the clone's own .codex hooks unreviewed once its folder is
+            # trusted. Core refuses this too; refuse here before cloning anything.
+            raise AgentLauncherError(
+                "--trust-hooks cannot be combined with --repo: the repository's project hooks "
+                "would run without review. Clone and vet it, then launch with --cwd."
+            )
+
         if yolo:
             if tool not in ("claude", "claude-auto", "codex"):
                 raise AgentLauncherError("--yolo is supported only for Claude and Codex.")
@@ -1535,6 +1746,7 @@ def agents_launch(
                 tags=tag,
                 **_request_id_kwargs(launcher.remote_launch, request_id),
                 **_approval_kwargs(launcher.remote_launch, approval.value if approval else None),
+                **_hook_trust_kwargs(launcher.remote_launch, True if trust_hooks else None),
                 **_execution_kwargs(launcher.remote_launch, execution_mode.value if execution_mode else None),
             )
         else:
@@ -1553,11 +1765,16 @@ def agents_launch(
                 team_id=team,
                 tags=tag,
                 **_approval_kwargs(launcher.launch, approval.value if approval else None),
+                **_hook_trust_kwargs(launcher.launch, True if trust_hooks else None),
                 **_execution_kwargs(launcher.launch, execution_mode.value if execution_mode else None),
                 progress_callback=_clone_progress if repo else None,
             )
 
-        status_val = session.status.value if session.status else "idle"
+        status_val = (
+            "starting / check terminal"
+            if _startup_pending(session)
+            else (session.status.value if session.status else "idle")
+        )
         style = _status_style(status_val)
 
         lines = []
@@ -1583,7 +1800,7 @@ def agents_launch(
         console.print(panel)
         console.print()
         console.print("[dim]Open from the Agent Dashboard or attach with:[/dim]")
-        console.print(f"  qbraid agents attach {session.session_id}")
+        _startup_notice(session, compute)
 
     except AgentLauncherError as e:
         console.print(
@@ -1686,6 +1903,14 @@ def agents_resume(
     approval: Optional[ApprovalMode] = typer.Option(
         None, "--approval", help="Override recorded permissions for this resume. Omit to preserve them."
     ),
+    trust_hooks: bool = typer.Option(
+        False,
+        "--trust-hooks",
+        help=(
+            "Codex only, DANGEROUS: run ALL enabled hooks without Codex's hook review, "
+            "for this resume only. Hooks are reviewed again on every run that omits it."
+        ),
+    ),
     compute: Optional[str] = typer.Option(None, "--compute", "-c", help="SSH alias for remote compute"),
 ):
     """Resume a previous agent session.
@@ -1716,6 +1941,8 @@ def agents_resume(
                 flags += f" --execution-mode {shlex.quote(execution_mode.value)}"
             if approval:
                 flags += f" --approval {shlex.quote(approval.value)}"
+            if trust_hooks:
+                flags += " --trust-hooks"
             # markup=False -- see agents_status.
             console.print(
                 _ssh_cmd(compute, f"qbraid agents resume {shlex.quote(session_id)}{flags}"),
@@ -1735,6 +1962,7 @@ def agents_resume(
                 session_id=session_id,
                 name=name,
                 **(_approval_kwargs(launcher.resume, approval.value) if approval else {}),
+                **_hook_trust_kwargs(launcher.resume, True if trust_hooks else None),
                 **_execution_kwargs(launcher.resume, execution_mode.value if execution_mode else None),
             )
         except AgentLauncherError as e:
@@ -1779,6 +2007,12 @@ def agents_resume(
                             cwd=original.cwd,
                             name=fork_name,
                             instructions=None,
+                            **_hook_trust_kwargs(
+                                launcher.launch,
+                                # Never inherited from the original: only an explicit
+                                # --trust-hooks on this command bypasses hook review.
+                                True if trust_hooks else None,
+                            ),
                             # A fork of a detached agent must not quietly
                             # become one that waits for a human.
                             **_approval_kwargs(
@@ -1787,11 +2021,7 @@ def agents_resume(
                             ),
                             **_execution_kwargs(
                                 launcher.launch,
-                                (
-                                    execution_mode.value
-                                    if execution_mode
-                                    else getattr(original, "execution_mode", None)
-                                ),
+                                _fork_execution(original, approval, execution_mode),
                             ),
                         )
                     else:
@@ -1806,60 +2036,68 @@ def agents_resume(
 
             elif "Multiple sessions match" not in err_msg:
                 raise
+            else:
+                # Only an ambiguous prefix reaches the picker. A completed fork
+                # used to fall through to it, find no matches and exit 1 after
+                # the fork had already launched.
+                # Show filtered picker with only matching sessions
+                import questionary
+
+                registry = _get_registry()
+                all_sessions = registry.search_sessions(include_stopped=True)
+                matches = [
+                    s
+                    for s in all_sessions
+                    if (
+                        s.session_id == session_id
+                        or s.session_id.startswith(session_id)
+                        or (s.tmux_window and s.tmux_window == session_id)
+                        or (s.terminal_name and s.terminal_name == session_id)
+                    )
+                ]
+                matches.sort(key=lambda s: s.last_activity or s.started_at or 0, reverse=True)
 
-            # Show filtered picker with only matching sessions
-            import questionary
-
-            registry = _get_registry()
-            all_sessions = registry.search_sessions(include_stopped=True)
-            matches = [
-                s
-                for s in all_sessions
-                if (
-                    s.session_id == session_id
-                    or s.session_id.startswith(session_id)
-                    or (s.tmux_window and s.tmux_window == session_id)
-                    or (s.terminal_name and s.terminal_name == session_id)
-                )
-            ]
-            matches.sort(key=lambda s: s.last_activity or s.started_at or 0, reverse=True)
+                if not matches:
+                    console.print(
+                        "[yellow]No visible sessions match this prefix. "
+                        "Use a full session ID to resume a retained record.[/yellow]"
+                    )
+                    raise typer.Exit(code=1)
+
+                choices = []
+                for s in matches:
+                    sid = s.session_id[:8]
+                    tool_val = s.tool.value if s.tool else "?"
+                    status_val = s.status.value if s.status else "?"
+                    cwd_display = s.cwd or ""
+                    if len(cwd_display) > 30:
+                        cwd_display = "..." + cwd_display[-27:]
+                    age_str = _time_ago(s.last_activity or s.started_at)
+                    label = f"{sid}  {tool_val:<8} {status_val:<8} {cwd_display:<30} {age_str}"
+                    choices.append(questionary.Choice(title=label, value=s.session_id))
+
+                console.print(f"[yellow]Multiple sessions match '{session_id}':[/yellow]")
+                selected = questionary.select(
+                    "Select a session to resume:",
+                    choices=choices,
+                    instruction="(use arrow keys)",
+                ).ask()
+                if selected is None:
+                    raise typer.Exit()
 
-            if not matches:
-                console.print(
-                    "[yellow]No visible sessions match this prefix. "
-                    "Use a full session ID to resume a retained record.[/yellow]"
+                session = launcher.resume(
+                    session_id=selected,
+                    name=name,
+                    **(_approval_kwargs(launcher.resume, approval.value) if approval else {}),
+                    **_hook_trust_kwargs(launcher.resume, True if trust_hooks else None),
+                    **_execution_kwargs(launcher.resume, execution_mode.value if execution_mode else None),
                 )
-                raise typer.Exit(code=1)
-
-            choices = []
-            for s in matches:
-                sid = s.session_id[:8]
-                tool_val = s.tool.value if s.tool else "?"
-                status_val = s.status.value if s.status else "?"
-                cwd_display = s.cwd or ""
-                if len(cwd_display) > 30:
-                    cwd_display = "..." + cwd_display[-27:]
-                age_str = _time_ago(s.last_activity or s.started_at)
-                label = f"{sid}  {tool_val:<8} {status_val:<8} {cwd_display:<30} {age_str}"
-                choices.append(questionary.Choice(title=label, value=s.session_id))
 
-            console.print(f"[yellow]Multiple sessions match '{session_id}':[/yellow]")
-            selected = questionary.select(
-                "Select a session to resume:",
-                choices=choices,
-                instruction="(use arrow keys)",
-            ).ask()
-            if selected is None:
-                raise typer.Exit()
-
-            session = launcher.resume(
-                session_id=selected,
-                name=name,
-                **(_approval_kwargs(launcher.resume, approval.value) if approval else {}),
-                **_execution_kwargs(launcher.resume, execution_mode.value if execution_mode else None),
-            )
-
-        status_val = session.status.value if session.status else "idle"
+        status_val = (
+            "starting / check terminal"
+            if _startup_pending(session)
+            else (session.status.value if session.status else "idle")
+        )
         style = _status_style(status_val)
 
         lines = []
@@ -1880,7 +2118,7 @@ def agents_resume(
         console.print(panel)
         console.print()
         console.print("[dim]Attach with:[/dim]")
-        console.print(f"  qbraid agents attach {session.tmux_window or session.session_id[:8]}")
+        _startup_notice(session)
 
     except AgentLauncherError as e:
         console.print(Panel(str(e), title="Resume Error", border_style="red"))
@@ -2845,17 +3083,44 @@ def hooks_uninstall():
 # =============================================================================
 
 
-def _resolve_from_session(explicit: Optional[str]) -> str:
+def _resolve_from_session(explicit: Optional[str], registry=None) -> 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.
+    Priority: explicit --from > the agent session this command runs inside
+    (process ancestry, else QBRAID_SESSION_ID) > fail with a helpful error.
+    An explicit sender may be an id prefix or a name, like a recipient, but
+    inside an agent it must be that agent.
     """
+    caller = _calling_session(registry) if registry is not None else None
     if explicit:
-        return explicit
+        sender = explicit
+        if registry is not None:
+            match = _find_session_by_prefix(registry, explicit)
+            if match is not None:
+                sender = match.session_id
+        if caller and sender != caller:
+            # A coordination guardrail, not authentication: an agent speaks
+            # as itself so recipients and permission rules see the real sender.
+            console.print(
+                f"[red]This command runs inside agent session {_plain(caller[:8])}; it cannot send "
+                f"as {_plain(explicit)}.[/red] Omit --from to send as yourself."
+            )
+            raise typer.Exit(code=1)
+        return sender
+    if caller:
+        return caller
     env_sid = os.environ.get("QBRAID_SESSION_ID")
-    if env_sid:
+    if registry is None and env_sid:
         return env_sid
+    if env_sid:
+        # The variable outlived its agent (a pane kept it after the agent
+        # stopped): whoever types here is the person, not that agent.
+        console.print(
+            f"[red]QBRAID_SESSION_ID names {_plain(env_sid[:8])}, which is not a running "
+            "agent, so this shell does not send as it.[/red] Pass --from <session-id> to "
+            "choose a sender."
+        )
+        raise typer.Exit(code=1)
     console.print(
         "[red]No sender session id available.[/red] "
         "Pass --from <session-id>, or run this inside a qBraid-managed "
@@ -2911,13 +3176,34 @@ def _resolve_target_session(registry, identifier: str) -> str:
     match = _find_session_by_prefix(registry, identifier)
     if match is None:
         console.print(
-            f"[red]No session matched '{identifier}'.[/red] "
+            f"[red]No session matched '{_plain(identifier)}'.[/red] "
             "Try 'qbraid agents list' to see available sessions."
         )
         raise typer.Exit(code=1)
     return match.session_id
 
 
+def _note_offline_recipient(registry, session_id: str) -> None:
+    """Say so when the recipient is not running: an inbox keeps the message,
+    but nothing reads it until the session is resumed."""
+    status = _session_status(registry, session_id)
+    if status not in ("stopped", "error"):
+        return
+    try:
+        from qbraid_core.services.agents import messaging  # pylint: disable=import-outside-toplevel
+
+        successor = getattr(messaging, "live_successor", None)
+        if callable(successor) and successor(registry, session_id):  # pylint: disable=not-callable
+            return  # Core forwards it to the resumed session and says so.
+    except Exception:  # pylint: disable=broad-exception-caught
+        pass
+    console.print(
+        f"[yellow]Note: {_plain(session_id[:8])} is {status}. The message waits in its inbox and is "
+        "read when the conversation is resumed (in place, or with `qbraid agents resume`, "
+        "which carries unread messages to the new session).[/yellow]"
+    )
+
+
 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).
 
@@ -2947,7 +3233,8 @@ def _parse_target_csv(csv: str, registry) -> list[str]:
             resolved.append(match.session_id)
     if unresolved:
         console.print(
-            f"[red]No session matched: {', '.join(unresolved)}[/red]. " "Broadcast aborted; nothing sent."
+            f"[red]No session matched: {_plain(', '.join(unresolved))}[/red]. "
+            "Broadcast aborted; nothing sent."
         )
         raise typer.Exit(code=1)
     return resolved
@@ -2985,7 +3272,15 @@ def _deliver_to_many(
                 registry=registry,
                 validate_permissions=validate_permissions,
             )
-            delivered.append((target_sid, msg.id))
+            delivered.append((getattr(msg, "to_session", None) or target_sid, msg.id))
+            # Older Core has no forwarded_from; newer Core types it Optional[str].
+            forwarded = getattr(msg, "forwarded_from", None)
+            if isinstance(forwarded, str) and forwarded:
+                old_sid, new_sid = str(forwarded), str(msg.to_session)
+                console.print(
+                    f"[dim]{_plain(old_sid[:8])} was resumed as {_plain(new_sid[:8])}; "
+                    "delivered to the running session.[/dim]"
+                )
         except AgentMessagingError as err:
             failed.append((target_sid, str(err)))
         except Exception as err:  # pylint: disable=broad-exception-caught
@@ -2993,10 +3288,11 @@ def _deliver_to_many(
 
     for sid, mid in delivered:
         console.print(
-            f"[green]→[/green] Sent to [bold]{sid}[/bold] " f"[dim](id={mid}, type={message_type})[/dim]"
+            f"[green]→[/green] Sent to [bold]{_plain(sid)}[/bold] "
+            f"[dim](id={_plain(mid)}, type={_plain(message_type)})[/dim]"
         )
     for sid, reason in failed:
-        console.print(f"[red]✗[/red] [bold]{sid}[/bold]: {reason}")
+        console.print(f"[red]✗[/red] [bold]{_plain(sid)}[/bold]: {_plain(reason)}")
 
     if failed and not delivered:
         return 1
@@ -3005,6 +3301,7 @@ def _deliver_to_many(
     return 0
 
 
+# Cross-host messaging transport: qBraid-CLI#328 / qbraid-core#307.
 @agents_app.command("send-to")
 def agents_send_to(
     to: str = typer.Argument(
@@ -3043,7 +3340,7 @@ def agents_send_to(
 
     Same-host only: an inbox is a JSONL file under ``~/.qbraid/inboxes/`` on
     the machine that owns it, so there is no ``--compute``. Cross-host
-    messaging needs a transport, tracked in qBraid-CLI#328 / qbraid-core#307.
+    messaging is not supported yet.
 
 
     Delivery is a JSONL append at ~/.qbraid/inboxes/<to-session-id>.jsonl
@@ -3059,8 +3356,9 @@ def agents_send_to(
         raise typer.Exit(code=1) from err
 
     registry = _get_registry()
-    from_sid = _resolve_from_session(from_)
+    from_sid = _resolve_from_session(from_, registry)
     to_sid = _resolve_target_session(registry, to)
+    _note_offline_recipient(registry, to_sid)
 
     code = _deliver_to_many(
         [to_sid],
@@ -3074,6 +3372,7 @@ def agents_send_to(
         raise typer.Exit(code=code)
 
 
+# Cross-host messaging transport: qBraid-CLI#328 / qbraid-core#307.
 @agents_app.command("broadcast")
 def agents_broadcast(
     text: str = typer.Argument(..., help="Message body — delivered to every target."),
@@ -3115,7 +3414,7 @@ def agents_broadcast(
 
     Same-host only: an inbox is a JSONL file under ``~/.qbraid/inboxes/`` on
     the machine that owns it, so there is no ``--compute``. Cross-host
-    messaging needs a transport, tracked in qBraid-CLI#328 / qbraid-core#307.
+    messaging is not supported yet.
 
     Two selectors — pick exactly one:
       * ``--team <team_id>``  — every session with that team_id (except sender)
@@ -3140,7 +3439,7 @@ def agents_broadcast(
         raise typer.Exit(code=2)
 
     registry = _get_registry()
-    from_sid = _resolve_from_session(from_)
+    from_sid = _resolve_from_session(from_, registry)
 
     if team is not None:
         members = _resolve_team_targets(registry, team, exclude_session_id=from_sid)
@@ -3201,14 +3500,15 @@ def _render_messages_table(messages, session_id: str, full_ids: bool = False) ->
         from_display = msg.from_session if full_ids else msg.from_session[:12]
         table.add_row(
             ts,
-            from_display,
-            msg.type.value,
+            _plain(from_display),
+            _plain(msg.type.value),
             read_marker,
-            msg.text,
+            _plain(msg.text),
         )
     console.print(table)
 
 
+# Cross-host messaging transport: qBraid-CLI#328 / qbraid-core#307.
 @inbox_app.callback()
 def inbox_default(  # pylint: disable=too-many-arguments
     ctx: typer.Context,
@@ -3247,7 +3547,7 @@ def inbox_default(  # pylint: disable=too-many-arguments
 
     Same-host only: an inbox is a JSONL file under ``~/.qbraid/inboxes/`` on
     the machine that owns it, so there is no ``--compute``. Cross-host
-    messaging needs a transport, tracked in qBraid-CLI#328 / qbraid-core#307.
+    messaging is not supported yet.
     """
     if ctx.invoked_subcommand is not None:
         return
@@ -3279,8 +3579,8 @@ def inbox_default(  # pylint: disable=too-many-arguments
                 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}"
+                    f"[cyan]{_plain(from_display)}[/cyan] "
+                    f"[yellow]({_plain(msg.type.value)})[/yellow] {_plain(msg.text)}"
                 )
                 if mark_read_flag:
                     mark_read(session_id, message_ids=[msg.id])
@@ -3343,6 +3643,7 @@ def inbox_mark_read(
 # =============================================================================
 
 
+# Cross-host messaging transport: qBraid-CLI#328 / qbraid-core#307.
 @agents_app.command("team")
 def agents_team(
     team_id: str = typer.Argument(..., help="Team identifier (matches AgentSession.team_id)."),
@@ -3357,7 +3658,7 @@ def agents_team(
 
     Same-host only: an inbox is a JSONL file under ``~/.qbraid/inboxes/`` on
     the machine that owns it, so there is no ``--compute``. Cross-host
-    messaging needs a transport, tracked in qBraid-CLI#328 / qbraid-core#307.
+    messaging is not supported yet.
 
     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
@@ -3380,7 +3681,7 @@ def agents_team(
 
     if not members:
         console.print(
-            f"[yellow]No sessions found with team_id '{team_id}'.[/yellow] "
+            f"[yellow]No sessions found with team_id '{_plain(team_id)}'.[/yellow] "
             "Check 'qbraid agents list' for known team_ids."
         )
         raise typer.Exit(code=0)
@@ -3400,7 +3701,7 @@ def agents_team(
     table = Table(
         show_header=True,
         header_style="bold",
-        title=f"Team: {team_id} ({len(members)} member{'s' if len(members) != 1 else ''})",
+        title=f"Team: {_plain(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)
@@ -3432,12 +3733,12 @@ def agents_team(
 
         table.add_row(
             "★" if s.session_id == me_sid else "",
-            session_display,
-            s.agent_type or "worker",
+            _plain(session_display),
+            _plain(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,
+            _plain(last_from),
+            _plain(last_text),
         )
 
     console.print(table)

{qbraid_cli-0.16.6 → qbraid_cli-0.16.8}/qbraid_cli/comms/app.py

@@ -76,7 +76,16 @@ def slack_send(
     file: Optional[str] = typer.Option(None, "--file", "-f", help="UTF-8 file, or - for stdin."),
     as_json: bool = typer.Option(False, "--json", help="Output the API result as JSON."),
 ):
-    """Send a Slack DM to yourself."""
+    """Send a Slack DM to yourself.
+
+    Give the message as an argument or with --file (- reads stdin), not both.
+    Messages are limited to 3,000 characters. Invalid input exits 2 and API
+    failures exit 1. Sends are never retried, since delivery can succeed even
+    if the response is lost.
+
+    Example:
+        qbraid comms slack send "Tests passed" --json
+    """
     text = _message(message, file)
     data = _run("send_slack", text)
     _sent(data, as_json, "Slack update sent.")
@@ -89,7 +98,16 @@ def email_send(
     file: Optional[str] = typer.Option(None, "--file", "-f", help="UTF-8 file, or - for stdin."),
     as_json: bool = typer.Option(False, "--json", help="Output the API result as JSON."),
 ):
-    """Email an update to yourself."""
+    """Email an update to yourself.
+
+    Mail goes to your qBraid account address. Give the body as an argument or
+    with --file (- reads stdin), not both. Bodies are limited to 20,000
+    characters, and the API allows 20 emails per hour. Invalid input exits 2
+    and API failures exit 1. Sends are never retried.
+
+    Example:
+        qbraid comms email send --subject "Progress" --file report.txt --json
+    """
     text = _message(message, file)
     data = _run("send_email", subject, text)
     _sent(data, as_json, "Email update sent.")
@@ -108,7 +126,18 @@ def slack_read(
     ),
     as_json: bool = typer.Option(False, "--json", help="Output messages and pagination as JSON."),
 ):
-    """Read your messages to the Slack bot."""
+    """Read your messages to the Slack bot.
+
+    Returns one page, newest first, of messages you sent in the bot DM; thread
+    replies are not included. --limit applies before filtering, so an empty
+    page can still have a next cursor. Keep --after fixed while following
+    cursors, and keep timestamps as strings, not floats. Reading does not mark
+    messages as read. Slack rate limits can be as low as one request per
+    minute, so avoid tight polling loops.
+
+    Example:
+        qbraid comms slack read --after 1789940000.000001 --json
+    """
     data = _run("read_slack", after=after, cursor=cursor, limit=limit)
     if as_json:
         typer.echo(json.dumps(data, ensure_ascii=True))

{qbraid_cli-0.16.6 → qbraid_cli-0.16.8/qbraid_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qbraid-cli
-Version: 0.16.6
+Version: 0.16.8
 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.15
+Requires-Dist: qbraid-core>=0.6.19
 Provides-Extra: compute
-Requires-Dist: qbraid-core[compute]>=0.6.15; extra == "compute"
+Requires-Dist: qbraid-core[compute]>=0.6.19; extra == "compute"
 Provides-Extra: envs
-Requires-Dist: qbraid-core[environments]>=0.6.15; extra == "envs"
+Requires-Dist: qbraid-core[environments]>=0.6.19; extra == "envs"
 Provides-Extra: dev
 Requires-Dist: isort; extra == "dev"
 Requires-Dist: black; extra == "dev"
@@ -172,5 +172,5 @@ qbraid comms email send --subject "Progress" --file report.txt --json
 qbraid comms slack read --json
 ```
 
-See [communication commands](docs/comms-cli.md) for Slack connection, stdin input,
-pagination, and deployment requirements.
+See [communication commands](https://docs.qbraid.com/v2/cli/api-reference/qbraid_comms) for Slack connection, stdin input,
+message limits, and pagination.

{qbraid_cli-0.16.6 → qbraid_cli-0.16.8}/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.15
+qbraid-core>=0.6.19
 
 [compute]
-qbraid-core[compute]>=0.6.15
+qbraid-core[compute]>=0.6.19
 
 [dev]
 isort
@@ -15,4 +15,4 @@ pytest-cov
 pytest-asyncio
 
 [envs]
-qbraid-core[environments]>=0.6.15
+qbraid-core[environments]>=0.6.19