agentremote-cli 1.0.0__py3-none-any.whl

remotecli/cli.py

@@ -0,0 +1,635 @@
+"""
+remotecli — AgentRemote 命令行工具.
+
+Agent 通过此 CLI 与 Middleware 交互:
+  remotecli cua click --pid 17376 --window-id 7014188 --target 保存
+  remotecli rpa run --flow crm-transaction-filter --param START_DATE=20260701 --param END_DATE=20260701
+  remotecli result <trace_id>
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict
+
+_RUNTIME_ROOT = Path(__file__).resolve().parents[1]
+_SHARED_ROOT = _RUNTIME_ROOT / "shared"
+if str(_SHARED_ROOT) not in sys.path:
+    sys.path.insert(0, str(_SHARED_ROOT))
+
+from agentremote_common.config import load_cli_defaults
+
+from .client import RemoteCliClient
+from .cua import CuaCommands
+from .agent import AgentCommands
+from .rpa import RpaCommands
+from .shell import ShellCommands
+
+
+def _configure_stdio() -> None:
+    for stream_name in ("stdout", "stderr"):
+        stream = getattr(sys, stream_name, None)
+        if hasattr(stream, "reconfigure"):
+            try:
+                stream.reconfigure(encoding="utf-8", errors="replace")
+            except Exception:
+                pass
+
+
+def _print_json(data: Dict[str, Any]) -> None:
+    text = json.dumps(data, ensure_ascii=False, indent=2)
+    try:
+        print(text)
+    except UnicodeEncodeError:
+        print(json.dumps(data, ensure_ascii=True, indent=2))
+
+
+def _maybe_wait_for_result(
+    client: RemoteCliClient,
+    submitted: Dict[str, Any],
+    wait: bool,
+    timeout_sec: float,
+    interval: float,
+) -> Dict[str, Any]:
+    if not wait:
+        return submitted
+    trace_id = submitted.get("trace_id")
+    if not trace_id:
+        return submitted
+    return client.poll_result(trace_id, timeout_sec=timeout_sec, interval=interval)
+
+
+def _split_targets(value: str) -> list[str]:
+    return [part.strip() for part in value.split(",") if part.strip()]
+
+
+def _parse_param_flags(values: list[str]) -> Dict[str, str]:
+    params: Dict[str, str] = {}
+    for value in values:
+        if "=" not in value:
+            raise ValueError(f"RPA --param must be KEY=VALUE: {value}")
+        key, param_value = value.split("=", 1)
+        key = key.strip()
+        if not key:
+            raise ValueError(f"RPA --param key cannot be empty: {value}")
+        params[key] = param_value
+    return params
+
+
+def _add_agent_window_cache_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--session", default="",
+                        help="Task session id for reusing cached app pid/window_id")
+    parser.add_argument("--refresh-window", action="store_true",
+                        help="Ignore cached pid/window_id and resolve the app window again")
+    parser.add_argument("--no-window-cache", action="store_true",
+                        help="Disable session window cache for this command")
+
+
+def main() -> None:
+    _configure_stdio()
+    pre_parser = argparse.ArgumentParser(add_help=False)
+    pre_parser.add_argument("--config", default="")
+    pre_args, _ = pre_parser.parse_known_args()
+    defaults = load_cli_defaults(pre_args.config)
+
+    parser = argparse.ArgumentParser(
+        description="AgentRemote CLI — capability-first remote control",
+        prog="remotecli",
+    )
+    parser.add_argument("--config", default=pre_args.config,
+                       help="AgentRemote CLI TOML config path")
+    parser.add_argument("--middleware", default=defaults.middleware_url,
+                       help="Middleware HTTP URL")
+    parser.add_argument("--tenant", default=defaults.tenant, help="Tenant ID")
+    parser.add_argument("--node", default=defaults.node, help="Node ID")
+    parser.add_argument("--agent", default=defaults.agent, help="Agent ID")
+    parser.add_argument("--handle", default=defaults.handle, help="Auth broker handle (wch_v1_...)")
+    parser.add_argument("--wait", dest="wait_result", action="store_true",
+                        help="Wait for submitted task result before printing")
+    parser.add_argument("--wait-timeout", type=float, default=30.0,
+                        help="Seconds to wait for task result when --wait is set")
+    parser.add_argument("--poll-interval", type=float, default=0.1,
+                        help="Seconds between result polls when --wait is set")
+
+    sub = parser.add_subparsers(dest="command", help="Subcommands")
+
+    # ── cua ──────────────────────────────
+    cua_parser = sub.add_parser("cua", help="CUA desktop control")
+    cua_sub = cua_parser.add_subparsers(dest="cua_action", help="CUA actions")
+
+    # cua click
+    p = cua_sub.add_parser("click", help="Click an element")
+    p.add_argument("--pid", type=int, required=True)
+    p.add_argument("--window-id", type=int, required=True)
+    p.add_argument("--target", default="")
+    p.add_argument("--x", type=int, default=0)
+    p.add_argument("--y", type=int, default=0)
+    p.add_argument("--element-index", type=int, default=0)
+    p.add_argument("--locate-mode", choices=["smart", "uia", "som"], default="",
+                   help="Target resolution mode: smart=UIA then SOM/OCR, uia=UIA only, som=SOM/OCR only")
+
+    # cua double-click
+    p = cua_sub.add_parser("double-click", help="Double-click an element")
+    p.add_argument("--pid", type=int, required=True)
+    p.add_argument("--window-id", type=int, required=True)
+    p.add_argument("--target", default="")
+    p.add_argument("--locate-mode", choices=["smart", "uia", "som"], default="",
+                   help="Target resolution mode")
+
+    # cua right-click
+    p = cua_sub.add_parser("right-click", help="Right-click an element")
+    p.add_argument("--pid", type=int, required=True)
+    p.add_argument("--window-id", type=int, required=True)
+    p.add_argument("--target", default="")
+    p.add_argument("--locate-mode", choices=["smart", "uia", "som"], default="",
+                   help="Target resolution mode")
+
+    # cua type-text
+    p = cua_sub.add_parser("type-text", help="Type text into an element")
+    p.add_argument("--pid", type=int, required=True)
+    p.add_argument("--window-id", type=int, default=0)
+    p.add_argument("--target", required=True)
+    p.add_argument("--text", required=True)
+    p.add_argument("--locate-mode", choices=["smart", "uia", "som"], default="",
+                   help="Target resolution mode")
+
+    # cua hotkey
+    p = cua_sub.add_parser("hotkey", help="Send hotkey combination")
+    p.add_argument("--pid", type=int, required=True)
+    p.add_argument("--window-id", type=int, default=0)
+    p.add_argument("--keys", required=True, help="e.g. ctrl,s")
+
+    # cua press-key
+    p = cua_sub.add_parser("press-key", help="Press a single key")
+    p.add_argument("--pid", type=int, required=True)
+    p.add_argument("--window-id", type=int, default=0)
+    p.add_argument("--key", required=True, help="e.g. enter, tab")
+
+    # cua launch-app
+    p = cua_sub.add_parser("launch-app", help="Launch an application")
+    p.add_argument("--name", default="")
+    p.add_argument("--path", dest="launch_path", default="")
+    p.add_argument("--args", dest="app_args", default="")
+    p.add_argument("--wait", dest="app_wait", action="store_true",
+                   help="Wait for launched app window before returning")
+
+    # cua list-apps
+    p = cua_sub.add_parser("list-apps", help="List running applications")
+    p.add_argument("--query", default="")
+    p.add_argument("--max-results", type=int, default=0)
+
+    # cua list-windows
+    p = cua_sub.add_parser("list-windows", help="List windows")
+    p.add_argument("--pid", type=int, default=0)
+
+    # cua bring-to-front
+    p = cua_sub.add_parser("bring-to-front", help="Bring window to front")
+    p.add_argument("--pid", type=int, required=True)
+    p.add_argument("--window-id", type=int, required=True)
+
+    # cua get-window-state
+    p = cua_sub.add_parser("get-window-state", help="Get window state")
+    p.add_argument("--pid", type=int, required=True)
+    p.add_argument("--window-id", type=int, required=True)
+    p.add_argument("--mode", choices=["uia", "vision", "som-full"], default="vision",
+                   help="uia=UIA tree, vision=screenshot only, som-full=full YOLO/OCR annotated snapshot")
+
+    # cua probe-window
+    p = cua_sub.add_parser("probe-window", help="Probe target labels in one window")
+    p.add_argument("--pid", type=int, required=True)
+    p.add_argument("--window-id", type=int, required=True)
+    p.add_argument("--targets", required=True,
+                   help="Comma-separated target labels to probe")
+    p.add_argument("--mode", choices=["smart", "uia", "som"], default="smart",
+                   help="smart=UIA then SOM/OCR, uia=UIA only, som=SOM/OCR only")
+
+    # cua get-cursor-position
+    cua_sub.add_parser("get-cursor-position", help="Get current cursor position")
+
+    # cua move-mouse
+    p = cua_sub.add_parser("move-mouse", help="Move mouse to absolute screen coordinates")
+    p.add_argument("--x", type=int, required=True)
+    p.add_argument("--y", type=int, required=True)
+
+    # cua move-mouse-relative
+    p = cua_sub.add_parser("move-mouse-relative", help="Move mouse relative to current position")
+    p.add_argument("--dx", type=int, required=True)
+    p.add_argument("--dy", type=int, required=True)
+
+    # cua scroll
+    p = cua_sub.add_parser("scroll", help="Scroll in a window")
+    p.add_argument("--pid", type=int, required=True)
+    p.add_argument("--window-id", type=int, required=True)
+    p.add_argument("--dx", type=int, default=0)
+    p.add_argument("--dy", type=int, default=0)
+    p.add_argument("--direction", choices=["up", "down", "left", "right"], default="",
+                   help="Scroll direction; preferred over dx/dy")
+    p.add_argument("--amount", type=int, default=0,
+                   help="Number of scroll ticks when --direction is used")
+    p.add_argument("--by", choices=["line", "page"], default="",
+                   help="Scroll granularity when --direction is used")
+    p.add_argument("--dispatch", choices=["background", "foreground", "auto"], default="",
+                   help="Driver dispatch mode")
+
+    # cua drag
+    p = cua_sub.add_parser("drag", help="Drag from one point to another")
+    p.add_argument("--pid", type=int, required=True)
+    p.add_argument("--window-id", type=int, required=True)
+    p.add_argument("--from-x", type=int, default=0)
+    p.add_argument("--from-y", type=int, default=0)
+    p.add_argument("--to-x", type=int, required=True)
+    p.add_argument("--to-y", type=int, required=True)
+
+    # cua set-value
+    p = cua_sub.add_parser("set-value", help="Set value of a UI element")
+    p.add_argument("--pid", type=int, required=True)
+    p.add_argument("--window-id", type=int, default=0)
+    p.add_argument("--target", default="")
+    p.add_argument("--element-index", type=int, default=0)
+    p.add_argument("--value", required=True)
+    p.add_argument("--locate-mode", choices=["smart", "uia", "som"], default="",
+                   help="Target resolution mode")
+
+    # ── rpa ──────────────────────────────
+    rpa_parser = sub.add_parser("rpa", help="RPA flow execution")
+    rpa_sub = rpa_parser.add_subparsers(dest="rpa_action", help="RPA actions")
+
+    p = rpa_sub.add_parser("run", help="Run an RPA flow")
+    p.add_argument("--flow", required=True, help="Flow ID")
+    p.add_argument("--task", default="", help="Task name")
+    p.add_argument("--param", action="append", default=[],
+                   help="Robot variable in KEY=VALUE form; can be repeated")
+
+    p = rpa_sub.add_parser("list-flows", help="List available RPA flows")
+
+    # ── shell ────────────────────────────
+    shell_parser = sub.add_parser("shell", help="Remote shell execution")
+    shell_sub = shell_parser.add_subparsers(dest="shell_action", help="Shell actions")
+
+    # shell exec
+    p = shell_sub.add_parser("exec", help="Execute a shell command")
+    p.add_argument("--cmd", required=True, help="Command to execute")
+    p.add_argument("--cwd", default="", help="Working directory")
+    p.add_argument("--timeout", type=int, default=60, help="Timeout in seconds")
+
+    # shell exec-script
+    p = shell_sub.add_parser("exec-script", help="Execute a multi-line script")
+    p.add_argument("--script", required=True, help="Script content")
+    p.add_argument("--shell", default="", help="Shell type: cmd / powershell / bash / sh")
+    p.add_argument("--cwd", default="", help="Working directory")
+    p.add_argument("--timeout", type=int, default=60, help="Timeout in seconds")
+
+    # shell info
+    shell_sub.add_parser("info", help="Get shell/OS environment info")
+
+    # ── agent ────────────────────────────
+    agent_parser = sub.add_parser("agent", help="Agent-friendly high-level wrappers")
+    agent_sub = agent_parser.add_subparsers(dest="agent_action", help="Agent actions")
+
+    p = agent_sub.add_parser("ps", help="Run PowerShell and print unpacked result")
+    p.add_argument("script", help="PowerShell script")
+    p.add_argument("--cwd", default="", help="Working directory")
+    p.add_argument("--timeout", type=int, default=60, help="Remote command timeout in seconds")
+
+    p = agent_sub.add_parser("cmd", help="Run cmd.exe command and print unpacked result")
+    p.add_argument("cmd", help="Command to execute")
+    p.add_argument("--cwd", default="", help="Working directory")
+    p.add_argument("--timeout", type=int, default=60, help="Remote command timeout in seconds")
+
+    p = agent_sub.add_parser("open", help="Ensure an app main window exists and cache pid/window_id")
+    p.add_argument("app", help="Application query, e.g. firefox or 微信")
+    p.add_argument("--path", dest="launch_path", default="",
+                   help="Optional explicit executable path")
+    p.add_argument("--args", dest="app_args", default="",
+                   help="Optional launch arguments")
+    p.add_argument("--timeout", dest="launch_timeout", type=int, default=15,
+                   help="Seconds to wait for a main window after launch")
+    p.add_argument("--no-start", action="store_true",
+                   help="Only find an existing main window; do not launch")
+    p.add_argument("--no-foreground", action="store_true",
+                   help="Do not try to bring the main window to front")
+    _add_agent_window_cache_args(p)
+
+    p = agent_sub.add_parser("observe", help="Find an app window and return its state")
+    p.add_argument("app", help="Application query, e.g. firefox")
+    p.add_argument("--mode", choices=["uia", "vision", "som-full"], default="uia",
+                   help="uia=UIA tree, vision=screenshot only, som-full=full YOLO/OCR annotated snapshot")
+    p.add_argument("--format", dest="observe_format", choices=["compact", "full"], default="compact",
+                   help="Return compact AI-facing state or full raw state")
+    p.add_argument("--element-limit", type=int, default=20,
+                   help="Maximum compact elements to return")
+    p.add_argument("--targets", default="",
+                   help="Comma-separated target labels to prioritize in compact output")
+    _add_agent_window_cache_args(p)
+
+    p = agent_sub.add_parser("probe", help="Find an app window and probe target labels")
+    p.add_argument("app", help="Application query, e.g. firefox")
+    p.add_argument("--targets", required=True,
+                   help="Comma-separated target labels to probe")
+    p.add_argument("--mode", choices=["smart", "uia", "som"], default="smart",
+                   help="smart=UIA then SOM/OCR, uia=UIA only, som=SOM/OCR only")
+    _add_agent_window_cache_args(p)
+
+    p = agent_sub.add_parser("click", help="Find an app window and click target text")
+    p.add_argument("app", help="Application query, e.g. firefox")
+    p.add_argument("target", help="Target text")
+    p.add_argument("--locate-mode", choices=["smart", "uia", "som"], default="smart",
+                   help="Target resolution mode: smart=UIA then SOM/OCR, uia=UIA only, som=SOM/OCR only")
+    _add_agent_window_cache_args(p)
+
+    p = agent_sub.add_parser("type", help="Find an app window and type text into target")
+    p.add_argument("app", help="Application query, e.g. firefox")
+    p.add_argument("target", help="Target text")
+    p.add_argument("text", help="Text to type")
+    p.add_argument("--locate-mode", choices=["smart", "uia", "som"], default="smart",
+                   help="Target resolution mode: smart=UIA then SOM/OCR, uia=UIA only, som=SOM/OCR only")
+    _add_agent_window_cache_args(p)
+
+    p = agent_sub.add_parser("key", help="Find an app window and press one key")
+    p.add_argument("app", help="Application query, e.g. firefox")
+    p.add_argument("key", help="Key name, e.g. escape")
+    _add_agent_window_cache_args(p)
+
+    p = agent_sub.add_parser("hotkey", help="Find an app window and send a hotkey")
+    p.add_argument("app", help="Application query, e.g. firefox")
+    p.add_argument("keys", help="Keys, e.g. ctrl,l or ctrl+shift+s")
+    _add_agent_window_cache_args(p)
+
+    p = agent_sub.add_parser("scroll", help="Find an app window and scroll it")
+    p.add_argument("app", help="Application query, e.g. firefox")
+    p.add_argument("--direction", choices=["up", "down", "left", "right"], default="down")
+    p.add_argument("--amount", type=int, default=3)
+    p.add_argument("--by", choices=["line", "page"], default="line")
+    p.add_argument("--dispatch", choices=["background", "foreground", "auto"], default="")
+    _add_agent_window_cache_args(p)
+
+    p = agent_sub.add_parser("session-clear", help="Clear cached agent window refs")
+    p.add_argument("session", nargs="?", default="",
+                   help="Task session id; falls back to REMOTECLI_SESSION")
+
+    # ── result ───────────────────────────
+    p = sub.add_parser("result", help="Query task result")
+    p.add_argument("trace_id", help="Trace ID")
+
+    args = parser.parse_args()
+
+    client = RemoteCliClient(
+        middleware_url=args.middleware,
+        tenant_id=args.tenant,
+        node_id=args.node,
+        agent_id=args.agent,
+        handle=args.handle,
+    )
+
+    if args.command == "cua":
+        cua = CuaCommands(client)
+        action = args.cua_action
+        if action == "click":
+            result = cua.click(
+                args.pid,
+                args.window_id,
+                args.target,
+                args.x,
+                args.y,
+                args.element_index,
+                locate_mode=args.locate_mode,
+            )
+        elif action == "double-click":
+            result = cua.double_click(args.pid, args.window_id, args.target, locate_mode=args.locate_mode)
+        elif action == "right-click":
+            result = cua.right_click(args.pid, args.window_id, args.target, locate_mode=args.locate_mode)
+        elif action == "type-text":
+            result = cua.type_text(
+                args.pid,
+                args.target,
+                args.text,
+                window_id=args.window_id,
+                locate_mode=args.locate_mode,
+            )
+        elif action == "hotkey":
+            result = cua.hotkey(args.pid, args.keys, window_id=args.window_id)
+        elif action == "press-key":
+            result = cua.press_key(args.pid, args.key, window_id=args.window_id)
+        elif action == "launch-app":
+            result = cua.launch_app(args.name, args.launch_path, args.app_args, args.app_wait)
+        elif action == "list-apps":
+            result = cua.list_apps(args.query, args.max_results)
+        elif action == "list-windows":
+            result = cua.list_windows(args.pid)
+        elif action == "bring-to-front":
+            result = cua.bring_to_front(args.pid, args.window_id)
+        elif action == "get-window-state":
+            result = cua.get_window_state(args.pid, args.window_id, args.mode)
+        elif action == "probe-window":
+            result = cua.probe_window(args.pid, args.window_id, _split_targets(args.targets), mode=args.mode)
+        elif action == "get-cursor-position":
+            result = cua.get_cursor_position()
+        elif action == "move-mouse":
+            result = cua.move_mouse(args.x, args.y)
+        elif action == "move-mouse-relative":
+            result = cua.move_mouse_relative(args.dx, args.dy)
+        elif action == "scroll":
+            result = cua.scroll(
+                args.pid,
+                args.window_id,
+                args.dx,
+                args.dy,
+                direction=args.direction,
+                amount=args.amount,
+                by=args.by,
+                dispatch=args.dispatch,
+            )
+        elif action == "drag":
+            result = cua.drag(args.pid, args.window_id, args.from_x, args.from_y, args.to_x, args.to_y)
+        elif action == "set-value":
+            result = cua.set_value(
+                args.pid,
+                args.target,
+                args.value,
+                args.element_index,
+                args.window_id,
+                locate_mode=args.locate_mode,
+            )
+        else:
+            print(f"Unknown cua action: {action}", file=sys.stderr)
+            sys.exit(1)
+        _print_json(_maybe_wait_for_result(
+            client, result, args.wait_result, args.wait_timeout, args.poll_interval
+        ))
+
+    elif args.command == "rpa":
+        rpa = RpaCommands(client)
+        action = args.rpa_action
+        if action == "run":
+            result = rpa.run(args.flow, args.task, params=_parse_param_flags(args.param))
+        elif action == "list-flows":
+            result = rpa.list_flows()
+        else:
+            print(f"Unknown rpa action: {action}", file=sys.stderr)
+            sys.exit(1)
+        _print_json(_maybe_wait_for_result(
+            client, result, args.wait_result, args.wait_timeout, args.poll_interval
+        ))
+
+    elif args.command == "shell":
+        shell = ShellCommands(client)
+        action = args.shell_action
+        if action == "exec":
+            result = shell.exec(args.cmd, args.cwd, args.timeout)
+        elif action == "exec-script":
+            result = shell.exec_script(args.script, args.shell, args.cwd, args.timeout)
+        elif action == "info":
+            result = shell.info()
+        else:
+            print(f"Unknown shell action: {action}", file=sys.stderr)
+            sys.exit(1)
+        _print_json(_maybe_wait_for_result(
+            client, result, args.wait_result, args.wait_timeout, args.poll_interval
+        ))
+
+    elif args.command == "agent":
+        agent = AgentCommands(client)
+        action = args.agent_action
+        if action == "ps":
+            result = agent.ps(
+                args.script,
+                cwd=args.cwd,
+                timeout_sec=args.timeout,
+                wait_timeout=args.wait_timeout,
+                poll_interval=args.poll_interval,
+            )
+        elif action == "cmd":
+            result = agent.cmd(
+                args.cmd,
+                cwd=args.cwd,
+                timeout_sec=args.timeout,
+                wait_timeout=args.wait_timeout,
+                poll_interval=args.poll_interval,
+            )
+        elif action == "open":
+            result = agent.open(
+                args.app,
+                launch_path=args.launch_path,
+                app_args=args.app_args,
+                start_if_missing=not args.no_start,
+                foreground=not args.no_foreground,
+                launch_timeout=args.launch_timeout,
+                wait_timeout=args.wait_timeout,
+                poll_interval=args.poll_interval,
+                session_id=args.session,
+                use_window_cache=not args.no_window_cache,
+            )
+        elif action == "observe":
+            result = agent.observe(
+                args.app,
+                mode=args.mode,
+                output_format=args.observe_format,
+                element_limit=args.element_limit,
+                targets=_split_targets(args.targets),
+                wait_timeout=args.wait_timeout,
+                poll_interval=args.poll_interval,
+                session_id=args.session,
+                use_window_cache=not args.no_window_cache,
+                refresh_window=args.refresh_window,
+            )
+        elif action == "probe":
+            result = agent.probe(
+                args.app,
+                _split_targets(args.targets),
+                mode=args.mode,
+                wait_timeout=args.wait_timeout,
+                poll_interval=args.poll_interval,
+                session_id=args.session,
+                use_window_cache=not args.no_window_cache,
+                refresh_window=args.refresh_window,
+            )
+        elif action == "click":
+            result = agent.click(
+                args.app,
+                args.target,
+                locate_mode=args.locate_mode,
+                wait_timeout=args.wait_timeout,
+                poll_interval=args.poll_interval,
+                session_id=args.session,
+                use_window_cache=not args.no_window_cache,
+                refresh_window=args.refresh_window,
+            )
+        elif action == "type":
+            result = agent.type_text(
+                args.app,
+                args.target,
+                args.text,
+                locate_mode=args.locate_mode,
+                wait_timeout=args.wait_timeout,
+                poll_interval=args.poll_interval,
+                session_id=args.session,
+                use_window_cache=not args.no_window_cache,
+                refresh_window=args.refresh_window,
+            )
+        elif action == "key":
+            result = agent.key(
+                args.app,
+                args.key,
+                wait_timeout=args.wait_timeout,
+                poll_interval=args.poll_interval,
+                session_id=args.session,
+                use_window_cache=not args.no_window_cache,
+                refresh_window=args.refresh_window,
+            )
+        elif action == "hotkey":
+            result = agent.hotkey(
+                args.app,
+                args.keys,
+                wait_timeout=args.wait_timeout,
+                poll_interval=args.poll_interval,
+                session_id=args.session,
+                use_window_cache=not args.no_window_cache,
+                refresh_window=args.refresh_window,
+            )
+        elif action == "scroll":
+            result = agent.scroll(
+                args.app,
+                direction=args.direction,
+                amount=args.amount,
+                by=args.by,
+                dispatch=args.dispatch,
+                wait_timeout=args.wait_timeout,
+                poll_interval=args.poll_interval,
+                session_id=args.session,
+                use_window_cache=not args.no_window_cache,
+                refresh_window=args.refresh_window,
+            )
+        elif action == "session-clear":
+            result = agent.clear_session(args.session)
+        else:
+            print(f"Unknown agent action: {action}", file=sys.stderr)
+            sys.exit(1)
+        _print_json(result)
+
+    elif args.command == "result":
+        data = client.poll_result(
+            args.trace_id,
+            timeout_sec=args.wait_timeout,
+            interval=args.poll_interval,
+        )
+        _print_json(data)
+
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:
+        import traceback
+        _print_json({
+            "status": "rejected",
+            "reason": "cli_error",
+            "error": str(e),
+            "traceback": traceback.format_exc(),
+        })
+        sys.exit(1)