arkclaw-webchat-cli 0.5.3__tar.gz → 0.6.1__tar.gz

{arkclaw_webchat_cli-0.5.3 → arkclaw_webchat_cli-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkclaw-webchat-cli
-Version: 0.5.3
+Version: 0.6.1
 Summary: CLI to chat with an ArkClaw EE space's Claw over enterprise SSO — zero permanent AK/SK.
 Author: ArkClaw Team
 Keywords: arkclaw,cli,ee,openclaw,sso,sts

{arkclaw_webchat_cli-0.5.3 → arkclaw_webchat_cli-0.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arkclaw-webchat-cli"
-version = "0.5.3"
+version = "0.6.1"
 description = "CLI to chat with an ArkClaw EE space's Claw over enterprise SSO — zero permanent AK/SK."
 readme = "README.md"
 requires-python = ">=3.10"

{arkclaw_webchat_cli-0.5.3 → arkclaw_webchat_cli-0.6.1}/src/ee_claw/cli.py

@@ -161,11 +161,20 @@ def chat(
     message_opt: str | None = typer.Option(
         None, "-m", "--message", help="One-shot message (same as the positional argument)."
     ),
+    agent: str = typer.Option(
+        "main",
+        "--agent",
+        help="Which agent in the claw to talk to (its agentId; see `arkclaw agents`). "
+        "Defaults to the claw's main agent.",
+    ),
     session: str | None = typer.Option(
         None,
         "--session",
-        help="Named server-side session (conversation thread). Defaults to the "
-        "claw's main session; sessions survive CLI restarts.",
+        help="Resume a specific conversation by its 会话ID (see `arkclaw sessions`). "
+        "Omit to continue the agent's main session.",
+    ),
+    new: bool = typer.Option(
+        False, "--new", help="Start a fresh conversation instead of continuing the last one."
     ),
     approve_all: bool = typer.Option(
         False,
@@ -192,6 +201,8 @@ def chat(
             target=target,
             message=message_opt or message,
             session=session,
+            agent=agent,
+            new=new,
             approve_all=approve_all,
             files=list(file) or None,
             output=output,
@@ -200,10 +211,17 @@ def chat(
 
 
 @app.command()
-def sessions(json_mode: bool = _json_opt()) -> None:
-    """List chat sessions this machine has used (most recent first)."""
+def sessions(
+    claw: str | None = typer.Argument(
+        None, metavar="[CLAW]", help="Claw id (ci-...). Omit to use your default claw."
+    ),
+    agent: str = typer.Option("main", "--agent", help="Which agent's conversations to list."),
+    json_mode: bool = _json_opt(),
+) -> None:
+    """List an agent's conversations from the server (newest first). Resume one
+    with `arkclaw chat <claw> --session <会话ID>`, or start fresh with `--new`."""
     emitter = Emitter(json_mode=json_mode)
-    _run(emitter, lambda: flows.do_sessions(emitter))
+    _run(emitter, lambda: flows.do_sessions(emitter, clawid=claw, agent=agent))
 
 
 @app.command(name="ls")
@@ -243,8 +261,8 @@ def push(
 
 @app.command()
 def agents(json_mode: bool = _json_opt()) -> None:
-    """List the agents/claws you can chat with (openclaw: your claws, space
-    auto-discovered; a2a: the agent at the endpoint). Then `chat <id-or-name>`."""
+    """List the agents you can chat with (openclaw: the agents in your accessible
+    claws; a2a: the agent at the endpoint). Then `chat <claw-or-name>`."""
     emitter = Emitter(json_mode=json_mode)
     _run(emitter, lambda: flows.do_agents(emitter))
 

{arkclaw_webchat_cli-0.5.3 → arkclaw_webchat_cli-0.6.1}/src/ee_claw/flows.py

@@ -20,6 +20,7 @@ import signal
 import sys
 import time
 import urllib.parse
+import uuid
 from typing import Any
 
 from ee_claw import config as config_mod
@@ -116,6 +117,79 @@ def _user_identity(id_token: str | None) -> dict[str, str]:
     return ident
 
 
+def _agent_display_name(agent: dict[str, Any]) -> str:
+    """Friendly name for an agent. The main agent often comes back named "main";
+    show a friendly label instead of leaking the internal id (mirrors the web)."""
+    name = str(agent.get("name") or "").strip()
+    agent_id = str(agent.get("agentId") or "")
+    is_main = bool(agent.get("default")) or agent_id == "main"
+    if is_main and (not name or name == "main"):
+        return "ArkClaw 智能助手"
+    return name or agent_id or "(未命名)"
+
+
+def _list_agents_for_claws(
+    cfg: SessionConfig, creds: dict[str, str], identity: dict[str, str], claw_ids: list[str]
+) -> dict[str, tuple[str, list[dict[str, Any]]]]:
+    """For each claw, list its agents over the ws (``arkclaw.team.agent.list``) —
+    which also proves access (the ChatToken mint denies non-owners). Returns
+    ``clawid → (status, agents)``, status ∈ {"ok","denied","error"}. Parallel."""
+    from concurrent.futures import ThreadPoolExecutor
+
+    region = str(cfg.region)
+
+    def one(clawid: str) -> tuple[str, str, list[dict[str, Any]]]:
+        t = OpenClawTransport(clawid=clawid, region=region, creds=creds, identity=identity)
+        try:
+            return clawid, "ok", asyncio.run(t.list_agents())
+        except ClawAccessDeniedError:
+            return clawid, "denied", []
+        except ArkclawError:
+            return clawid, "error", []  # transient — keep the claw, mark unknown
+
+    out: dict[str, tuple[str, list[dict[str, Any]]]] = {}
+    with ThreadPoolExecutor(max_workers=min(8, max(1, len(claw_ids)))) as ex:
+        for clawid, status, agents in ex.map(one, claw_ids):
+            out[clawid] = (status, agents)
+    return out
+
+
+def _resolve_session_key(
+    cfg: SessionConfig, id_token: str, clawid: str, agent: str, session: str | None, new: bool
+) -> str | None:
+    """Compute the OpenClaw sessionKey ``agent:<agentId>:<label>`` for a chat:
+
+    * ``--new``           → a fresh ``agent:<agent>:cli-<uuid>`` (new conversation)
+    * ``--session <id>``  → resume: a full ``agent:…`` key passes through; a short
+                            sessionId is resolved to its key via ``sessions.list``
+    * neither, agent=main → ``None`` (the default ``agent:main:main`` session)
+    * neither, other agent→ ``agent:<agent>:main``
+    """
+    agent = agent or "main"
+    if new:
+        return f"agent:{agent}:cli-{uuid.uuid4()}"
+    if not session:
+        return None if agent == "main" else f"agent:{agent}:main"
+    if session.startswith("agent:"):
+        return session  # already a full sessionKey
+    # A hex token is a 会话ID copied from `arkclaw sessions` → resolve to its key.
+    if re.fullmatch(r"[0-9a-f]{6,}", session):
+        creds = _openclaw_creds(cfg, id_token)
+        t = OpenClawTransport(
+            clawid=clawid, region=str(cfg.region), creds=creds, identity=_user_identity(id_token)
+        )
+        for s in asyncio.run(t.list_sessions(agent)):
+            sid = str(s.get("sessionId") or "")
+            if sid and (sid == session or sid.startswith(session)):
+                return str(s.get("key") or f"agent:{agent}:{session}")
+        raise ValidationError(
+            f"会话 {session!r} 不存在。",
+            hint="用 `arkclaw sessions` 查看现有会话,或加 `--new` 开新会话。",
+        )
+    # Otherwise a human-named session label (created/resumed by this key).
+    return f"agent:{agent}:{session}"
+
+
 def _normalize(url: str) -> tuple[str, str]:
     base = (url if "//" in url else "https://" + url).rstrip("/")
     host = urllib.parse.urlparse(base).hostname or ""
@@ -131,55 +205,72 @@ def _is_userpool_address(host: str) -> bool:
 
 
 def do_init(emitter: Emitter, address: str | None = None) -> dict[str, Any]:
-    """``arkclaw init``: one-time interactive setup. Captures the login address
-    plus the bits not yet auto-discoverable (the CLI's OAuth client, the STS
-    role) so that afterwards ``arkclaw login`` needs no env vars or flags.
-    Anything the space already self-describes (issuer, region, and — once the
-    platform publishes it — client_id/role) is auto-filled and not asked."""
-    if emitter.json or not sys.stdin.isatty():
-        raise ValidationError(
-            "arkclaw init 是交互式的,需要终端。",
-            hint="在终端直接运行 `arkclaw init`;脚本里改用 env(ARKCLAW_CLIENT_ID/ROLE_TRN)+ flags。",
-        )
+    """``arkclaw init``: one-time setup. The GOAL is **address-only** — when the
+    space publishes its CLI config (issuer/region/client_id/role…) via
+    ``/.well-known/arkclaw-cli`` or GetAuthConfig, the user gives ONLY the
+    address and nothing is asked (works non-interactively too). Until then, it
+    prompts for the few bits discovery can't provide (the CLI's OAuth client,
+    the STS role)."""
+    interactive = not emitter.json and sys.stdin.isatty()
+
+    def need_tty() -> None:
+        if not interactive:
+            raise ValidationError(
+                "该空间尚未发布 CLI 配置,需要补充 client_id/role,而当前非交互终端。",
+                hint="在终端运行 `arkclaw init <地址>`;或脚本里用 env(ARKCLAW_CLIENT_ID/ROLE_TRN)+ flags。",
+            )
 
-    def ask(label: str, default: str | None = None, *, required: bool = False) -> str | None:
+    def ask(label: str, default: str | None = None, *, required: bool = False) -> str:
         suffix = f" [{default}]" if default else ""
         while True:
             ans = input(f"  {label}{suffix}: ").strip() or (default or "")
             if ans or not required:
-                return ans or None
+                return ans
             emitter.line("    (必填)")
 
-    emitter.line("arkclaw init —— 一次性配置(能自动发现的不会问你)\n")
-    address = address or ask("空间登录地址 (https://…)", required=True)
+    if not address:
+        need_tty()
+        emitter.line("arkclaw init —— 配置一次(能自动发现的不问你)\n")
+        address = ask("空间登录地址 (https://…)", required=True)
     base, host = _normalize(str(address))
     disc = discover_cli_config(base) or {}
     issuer = disc.get("issuer") or (f"https://{host}" if _is_userpool_address(host) else None)
     region = disc.get("region") or derive_region(base)
-    if issuer:
-        emitter.line("  ✓ 自动发现身份池 issuer")
-    if region:
-        emitter.line(f"  ✓ 区域: {region}")
-
-    # User-facing name is "webchat" (the ChatToken/wss path); internally it's
-    # the "openclaw" transport. "a2a" is unchanged.
-    disc_t = str(disc.get("transport") or "")
-    transport_in = ask("传输方式 (webchat/a2a)", default=("a2a" if disc_t == "a2a" else "webchat")) or "webchat"
-    transport = "a2a" if transport_in.lower() == "a2a" else "openclaw"
-    client_id = disc.get("client_id") or ask(
-        "CLI client_id(public OAuth 客户端,问管理员;平台发布发现后免此项)", required=True
-    )
-    role_trn: object = None
-    endpoint: object = None
-    if transport == "openclaw":
-        role_trn = disc.get("role_trn") or ask("STS role TRN (trn:iam::<账号>:role/<名字>)", required=True)
+    transport = "a2a" if str(disc.get("transport") or "").lower() == "a2a" else "openclaw"
+    client_id = disc.get("client_id")
+    role_trn = disc.get("role_trn")
+    provider_trn = disc.get("provider_trn")
+    endpoint = disc.get("endpoint")
+    clawid = disc.get("clawid")
+
+    # Fully discovered = the space published this CLI's client + target plane →
+    # nothing to ask (address-only). Otherwise prompt ONLY for what's missing.
+    complete = bool(client_id) and (bool(role_trn) if transport == "openclaw" else bool(endpoint))
+    if complete:
+        emitter.line("✓ 该空间已发布 CLI 配置 —— 全部自动解析,无需手动输入。")
     else:
-        endpoint = disc.get("endpoint") or ask("A2A endpoint (https://…)", required=True)
-    clawid = disc.get("clawid") or ask("默认 claw id (ci-…,可留空,登录后用 arkclaw agents 选)")
+        need_tty()
+        if issuer:
+            emitter.line("  ✓ 自动发现身份池 issuer")
+        if region:
+            emitter.line(f"  ✓ 区域: {region}")
+        # "webchat" = the ChatToken/wss path (internal name "openclaw"); "a2a" unchanged.
+        t_in = ask("传输方式 (webchat/a2a)", default=("a2a" if transport == "a2a" else "webchat"))
+        transport = "a2a" if t_in.lower() == "a2a" else "openclaw"
+        if not client_id:
+            client_id = ask(
+                "CLI client_id(public OAuth 客户端,问管理员;平台发布发现后免此项)", required=True
+            )
+        if transport == "openclaw" and not role_trn:
+            role_trn = ask("STS role TRN (trn:iam::<账号>:role/<名字>)", required=True)
+        elif transport == "a2a" and not endpoint:
+            endpoint = ask("A2A endpoint (https://…)", required=True)
+        if not clawid:
+            clawid = ask("默认 claw id (ci-…,可留空,登录后用 arkclaw agents 选)") or None
 
     saved = {
         "address": base, "issuer": issuer, "client_id": client_id, "transport": transport,
-        "region": region, "role_trn": role_trn, "provider_trn": disc.get("provider_trn"),
+        "region": region, "role_trn": role_trn, "provider_trn": provider_trn,
         "endpoint": endpoint, "space_id": disc.get("space_id"), "clawid": clawid,
     }
     config_mod.save_defaults(saved)
@@ -735,6 +826,8 @@ def do_chat(
     target: str | None = None,
     message: str | None = None,
     session: str | None = None,
+    agent: str = "main",
+    new: bool = False,
     approve_all: bool = False,
     files: list[str] | None = None,
     output: str | None = None,
@@ -790,6 +883,12 @@ def do_chat(
         )
 
     approver = _build_approver(emitter, approve_all=approve_all, interactive=interactive)
+    # Resolve agent + session → a concrete sessionKey (openclaw only; a2a uses
+    # the session name as the context label).
+    if cfg.transport == "openclaw":
+        effective_claw = clawid or cfg.claw
+        if effective_claw:
+            session = _resolve_session_key(cfg, id_token, effective_claw, agent, session, new)
     target, transport = _target_transport(
         cfg, clawid, id_token, session=session, approver=approver
     )
@@ -831,8 +930,9 @@ def do_chat(
         pass
     emitter.line(
         f"ArkClaw chat · {target}"
+        + (f" · agent {agent}" if agent and agent != "main" else "")
+        + (f" · 会话 {session.split(':')[-1][:16]}" if session else "")
         + (f" · 空间 {cfg.space}" if cfg.space and cfg.space != target else "")
-        + (f" · 会话 {session}" if session else "")
         + " (Ctrl+C 退出)"
     )
     while True:
@@ -863,11 +963,54 @@ def do_chat(
             emitter.line("")
 
 
-def do_sessions(emitter: Emitter) -> dict[str, Any]:
-    """``arkclaw sessions``: the local view of server-side sessions (which
-    space/claw/session tuples this machine has talked to). Server-side
-    listing + replay land with gate G2."""
-    rows = config_mod.list_sessions()
+def do_sessions(
+    emitter: Emitter, clawid: str | None = None, agent: str = "main"
+) -> dict[str, Any]:
+    """``arkclaw sessions [<claw>] [--agent <id>]``: the conversations of an agent
+    in a claw, from the server (ws ``sessions.list``) — newest first. Resume one
+    with ``arkclaw chat <claw> --session <会话ID>``. Falls back to the local
+    record for a2a / when the claw can't be reached."""
+    cfg = config_mod.load_config()
+    target = (clawid or (cfg.claw if cfg else None)) if cfg else None
+    if cfg and cfg.space and cfg.transport == "openclaw" and target:
+        try:
+            _, id_token = _load_session(cfg)
+            creds = _openclaw_creds(cfg, id_token)
+            t = OpenClawTransport(
+                clawid=target, region=str(cfg.region), creds=creds, identity=_user_identity(id_token)
+            )
+            sessions = asyncio.run(t.list_sessions(agent))
+            sessions.sort(key=lambda s: float(s.get("updatedAt") or 0), reverse=True)
+            emitter.line(f"★ claw {target} · agent {agent} · 空间 {cfg.space}")
+            if sessions:
+                emitter.table(
+                    ["标题", "上次活动", "会话ID", "状态"],
+                    [
+                        [
+                            (str(s.get("derivedTitle") or "(无标题)"))[:48],
+                            _ago_ms(s.get("updatedAt")),
+                            str(s.get("sessionId") or "")[:8],
+                            str(s.get("status") or "—"),
+                        ]
+                        for s in sessions
+                    ],
+                )
+                emitter.line("  续聊: arkclaw chat <claw> --session <会话ID>;新开: --new")
+            else:
+                emitter.line("  该 agent 还没有会话。`arkclaw chat` 开始第一段对话。")
+            return {
+                "claw": target, "agent": agent,
+                "sessions": [
+                    {"sessionId": s.get("sessionId"), "key": s.get("key"),
+                     "title": s.get("derivedTitle"), "updatedAt": s.get("updatedAt"),
+                     "status": s.get("status")}
+                    for s in sessions
+                ],
+            }
+        except ArkclawError as e:
+            emitter.line(f"  ⚠ 无法从服务端列会话({e.code}),回退本地记录:")
+
+    rows = config_mod.list_sessions()  # a2a / not-logged-in / no-claw / server-error fallback
     if rows:
         emitter.table(
             ["会话", "目标", "空间", "最近使用"],
@@ -916,13 +1059,15 @@ def _ago(ts: object) -> str:
 
 
 def do_agents(emitter: Emitter) -> dict[str, Any]:
-    """``arkclaw agents``: the agents/claws you can chat with.
+    """``arkclaw agents``: the agents you can chat with.
 
-    openclaw → the claws YOU have used from this machine (kept locally, newest
-    first), plus your default claw. This is deliberately NOT a server-side
-    enumeration of the space — that API returns every member's claws to anyone
-    (no per-user scoping is reachable by the CLI's role), so we don't call it.
-    You add a claw to this list by chatting it once: ``arkclaw chat ci-...``.
+    openclaw → the AGENTS hosted in your accessible claws. The candidate claws
+    are the ones YOU have used from this machine (kept locally, newest first)
+    plus your default; for each we list its agents over the ws
+    (``arkclaw.team.agent.list``), which also verifies access — inaccessible
+    claws are pruned. This is NOT a space-wide server enumeration (not per-user
+    scoped for the CLI's role). You add a claw by chatting it once: ``arkclaw
+    chat ci-...``.
 
     a2a → the agent at the endpoint (its card). Profiles live under ``arkclaw
     profile``, full conversation history under ``arkclaw sessions``."""
@@ -982,12 +1127,11 @@ def do_agents(emitter: Emitter) -> dict[str, Any]:
             )
     elif cfg.transport == "openclaw":
         emitter.line(f"★ 当前登录(openclaw)· 空间 {cfg.space}")
-        # The claws you can chat = the ones YOU have used from this machine,
-        # remembered locally — NOT a server enumeration of the space. The
-        # space-wide ListClawInstances returns every member's claws to anyone
-        # (no per-user scoping reachable by the CLI's role), so we don't call it.
-        # New claws enter via `arkclaw chat ci-...`; each chat is recorded
-        # (record_session) and shows up here next time.
+        # The chat-able units are AGENTS, and one claw hosts several. Candidates
+        # are the claws YOU have used from this machine (local history) + your
+        # default; for each we list its agents over the ws (which also proves
+        # access). Inaccessible claws are pruned from history (+ cleared as
+        # default). NOT a space-wide server enumeration (not per-user scoped).
         seen: dict[str, float] = {}
         for s in config_mod.list_sessions():
             cid = s.get("claw")
@@ -996,23 +1140,57 @@ def do_agents(emitter: Emitter) -> dict[str, Any]:
                 seen[str(cid)] = max(seen.get(str(cid), 0.0), float(ts) if isinstance(ts, (int, float)) else 0.0)
         if cfg.claw and str(cfg.claw) not in seen:
             seen[str(cfg.claw)] = 0.0  # the default claw, even if not chatted yet
-        claws = [
-            {"ClawInstanceId": cid, "last_used": ts}
-            for cid, ts in sorted(seen.items(), key=lambda kv: kv[1], reverse=True)
-        ]
-        current["claws"] = claws
-        current["source"] = "local-history"
-        if claws:
+
+        claw_ids = sorted(seen, key=lambda c: seen[c], reverse=True)
+        rows: list[list[str]] = []
+        agents_data: list[dict[str, Any]] = []
+        checked = False
+        if claw_ids:
+            if not emitter.json:
+                emitter.line("  列出 agents…")
+            try:
+                _, id_token = _load_session(cfg)
+                creds = _openclaw_creds(cfg, id_token)
+                identity = _user_identity(id_token)
+                results = _list_agents_for_claws(cfg, creds, identity, claw_ids)
+                checked = True
+                for clawid in claw_ids:
+                    status, agents = results[clawid]
+                    if status == "denied":
+                        config_mod.forget_claw(str(cfg.space), clawid)  # stop listing it
+                        if cfg.claw == clawid:
+                            config_mod.save_config(dataclasses.replace(cfg, claw=None))
+                            cfg = config_mod.load_config() or cfg
+                            current["default_claw"] = cfg.claw
+                        continue
+                    if status == "error" or not agents:
+                        rows.append(["(无法列出 agent)", "—", clawid, "★" if clawid == cfg.claw else ""])
+                        continue
+                    for a in agents:
+                        aid = str(a.get("agentId") or "")
+                        is_main = bool(a.get("default")) or aid == "main"
+                        rows.append([
+                            _agent_display_name(a), aid or "—", clawid,
+                            "★" if (clawid == cfg.claw and is_main) else "",
+                        ])
+                        agents_data.append({
+                            "clawId": clawid, "agentId": aid, "name": _agent_display_name(a),
+                            "description": a.get("description"), "default": is_main,
+                        })
+            except ArkclawError:
+                checked = False  # offline / expired / no creds → can't list agents
+
+        current["agents"] = agents_data
+        current["source"] = "verified" if checked else "local-history-unchecked"
+        if checked and rows:
+            emitter.table(["Agent", "agentId", "所属 Claw", "默认"], rows)
+        elif checked:
+            emitter.line("  本空间没有你可访问的 claw / agent(历史里的都已无权或不存在)。")
+        elif claw_ids:
+            emitter.line("  ⚠ 未能连接核对(离线/会话过期),无法列出 agent;以下为本地历史的 claw:")
             emitter.table(
-                ["Claw(可 chat)", "上次使用", "默认"],
-                [
-                    [
-                        str(c["ClawInstanceId"]),
-                        _ago(c["last_used"]) if c["last_used"] else "—",
-                        "★" if c["ClawInstanceId"] == cfg.claw else "",
-                    ]
-                    for c in claws
-                ],
+                ["Claw", "上次使用"],
+                [[c, _ago(seen[c]) if seen[c] else "—"] for c in claw_ids],
             )
         else:
             emitter.line("  还没用过任何 claw。用 `arkclaw chat ci-xxxx` 开始,之后这里会记住它。")

{arkclaw_webchat_cli-0.5.3 → arkclaw_webchat_cli-0.6.1}/src/ee_claw/identity.py

@@ -118,6 +118,20 @@ def discover_cli_config(url: str) -> dict[str, object] | None:
         if result.get(k):
             out["client_id"] = result[k]
             break
+    # The remaining CLI-plane fields (platform-added). Once the BFF surfaces
+    # these on GetAuthConfig, the user types ONLY the address — login/init
+    # resolve everything. (camelCase from the BFF → snake_case the CLI uses.)
+    for src, dst in (
+        ("roleTrn", "role_trn"),
+        ("providerTrn", "provider_trn"),
+        ("region", "region"),
+        ("spaceId", "space_id"),
+        ("transport", "transport"),
+        ("endpoint", "endpoint"),
+        ("defaultClawId", "clawid"),
+    ):
+        if result.get(src):
+            out[dst] = result[src]
     return out or None
 
 

{arkclaw_webchat_cli-0.5.3 → arkclaw_webchat_cli-0.6.1}/src/ee_claw/transport/openclaw.py

@@ -451,9 +451,10 @@ class OpenClawTransport:
     #   agents.files.get  {agentId, name}        → {file:{name,path,size,content}}
     #   agents.files.set  {agentId, name, content} → write
 
-    async def _request(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
-        """connect (hello-ok) → one control request → its res payload. Errors
-        are redacted; the token-bearing URL is never echoed."""
+    async def _request(self, method: str, params: dict[str, Any]) -> Any:
+        """connect (hello-ok) → one control request → its res payload (dict or
+        list, depending on the method). Errors are redacted; the token-bearing
+        URL is never echoed."""
         chat_token, endpoint = get_chat_token(self.clawid, self.region, self.creds, identity=self.identity)
         url = (
             f"wss://{endpoint}/?chatToken={urllib.parse.quote(chat_token)}"
@@ -510,3 +511,31 @@ class OpenClawTransport:
         return await self._request(
             "agents.files.set", {"agentId": agent_id, "name": name, "content": content}
         )
+
+    async def list_agents(self) -> list[dict[str, Any]]:
+        """The agents living in this claw (ws RPC ``arkclaw.team.agent.list``).
+        Each item: ``{agentId, name, description?, default?}``. Raises
+        ClawAccessDeniedError (via the ChatToken mint) if the user can't access
+        this claw."""
+        payload = await self._request("arkclaw.team.agent.list", {})
+        if isinstance(payload, list):
+            return [a for a in payload if isinstance(a, dict)]
+        if isinstance(payload, dict):  # some gateways wrap the array
+            for k in ("data", "agents", "list", "items"):
+                v = payload.get(k)
+                if isinstance(v, list):
+                    return [a for a in v if isinstance(a, dict)]
+        return []
+
+    async def list_sessions(self, agent_id: str = "main") -> list[dict[str, Any]]:
+        """An agent's conversations (ws RPC ``sessions.list``). Each item:
+        ``{key, sessionId, derivedTitle?, updatedAt, status, ...}`` — ``key`` is
+        the sessionKey to resume with."""
+        payload = await self._request(
+            "sessions.list", {"agentId": agent_id, "includeDerivedTitles": True}
+        )
+        if isinstance(payload, dict):
+            sessions = payload.get("sessions")
+            if isinstance(sessions, list):
+                return [s for s in sessions if isinstance(s, dict)]
+        return []