@iducky/media-agent 1.1.0

package/src/media_agent/runtime/__init__.py

@@ -0,0 +1 @@
+"""Media Agent capabilities."""

package/src/media_agent/runtime/account_manager.py

@@ -0,0 +1,672 @@
+from media_agent.runtime.paths import runtime_home
+# ============================================================
+# 社交媒体账号管理 — 核心脚本
+# 依赖: CloakBrowser (pip install cloakbrowser)
+# ============================================================
+import json
+import os
+import sys
+import time
+import uuid
+from pathlib import Path
+from datetime import datetime, timezone
+from typing import Optional, List, Dict, Any
+
+# ── 路径常量 ────────────────────────────────────────────────
+BASE_DIR = runtime_home()
+ACCOUNTS_YAML = BASE_DIR / "accounts.yaml"
+PROFILES_DIR = BASE_DIR / "profiles"
+LOCKS_DIR = BASE_DIR / "locks"
+SCREENSHOTS_DIR = BASE_DIR / "screenshots"
+TASKS_DIR = BASE_DIR / "tasks"
+
+# 默认指纹参数
+DEFAULT_FINGERPRINT = {
+    "platform": "macos",
+    "locale": "zh-CN",
+    "timezone": "Asia/Shanghai",
+    "viewport": {"width": 1440, "height": 900},
+    "humanize": True,
+    "human_preset": "default",
+    "stealth_args": True,
+    "color_scheme": "light",
+    "headless": False,
+}
+
+# 锁超时（秒）— 超过此时间视为僵死锁
+LOCK_STALE_TIMEOUT = 7200  # 2小时
+
+
+# ═══════════════════════════════════════════════════════════════
+# 1. 账号注册表操作
+# ═══════════════════════════════════════════════════════════════
+def load_accounts() -> list:
+    """加载 accounts.yaml"""
+    import yaml
+    if not ACCOUNTS_YAML.exists():
+        return []
+    with open(ACCOUNTS_YAML, "r", encoding="utf-8") as f:
+        data = yaml.safe_load(f) or {}
+    return data.get("accounts", [])
+
+
+def save_accounts(accounts: list):
+    """保存 accounts.yaml"""
+    import yaml
+    data = {"accounts": accounts}
+    with open(ACCOUNTS_YAML, "w", encoding="utf-8") as f:
+        yaml.dump(data, f, allow_unicode=True, default_flow_style=False, sort_keys=False)
+    print(f"✅ 已保存 {len(accounts)} 个账号到 {ACCOUNTS_YAML}")
+
+
+def find_account(alias: str):
+    """按 alias 查找账号"""
+    for a in load_accounts():
+        if a["alias"] == alias:
+            return a
+    return None
+
+
+# ═══════════════════════════════════════════════════════════════
+# 2. Profile 配置操作
+# ═══════════════════════════════════════════════════════════════
+def profile_path(alias: str) -> Path:
+    return PROFILES_DIR / alias
+
+
+def profile_config_path(alias: str) -> Path:
+    return profile_path(alias) / "config.json"
+
+
+def profile_state_path(alias: str) -> Path:
+    return profile_path(alias) / "state.json"
+
+
+def profile_user_data_dir(alias: str) -> Path:
+    return profile_path(alias) / "browser_data"
+
+
+def load_profile_config(alias: str) -> dict:
+    """加载 profile 的 config.json"""
+    p = profile_config_path(alias)
+    if not p.exists():
+        return {}
+    with open(p, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def save_profile_config(alias: str, config: dict):
+    """保存 profile 的 config.json"""
+    p = profile_config_path(alias)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    with open(p, "w", encoding="utf-8") as f:
+        json.dump(config, f, indent=2, ensure_ascii=False)
+    print(f"  ✅ config.json 已写入: {p}")
+
+
+def load_profile_state(alias: str) -> dict:
+    """加载 profile 的 state.json"""
+    p = profile_state_path(alias)
+    if not p.exists():
+        return {
+            "is_logged_in": False,
+            "last_login_check": None,
+            "last_activity": None,
+            "login_method": None,
+            "notes": "",
+        }
+    with open(p, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def save_profile_state(alias: str, state: dict):
+    """保存 profile 的 state.json"""
+    p = profile_state_path(alias)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    with open(p, "w", encoding="utf-8") as f:
+        json.dump(state, f, indent=2, ensure_ascii=False)
+
+
+def init_profile(alias: str, account: dict):
+    """初始化一个新 profile"""
+    profile_dir = profile_path(alias)
+    profile_dir.mkdir(parents=True, exist_ok=True)
+
+    # 生成唯一指纹 seed
+    fingerprint_seed = str(uuid.uuid4())
+
+    # 构建 config.json
+    config = {
+        "fingerprint": {
+            "seed": fingerprint_seed,
+            "platform": DEFAULT_FINGERPRINT["platform"],
+            "locale": DEFAULT_FINGERPRINT["locale"],
+            "timezone": DEFAULT_FINGERPRINT["timezone"],
+            "viewport": DEFAULT_FINGERPRINT["viewport"],
+            "color_scheme": DEFAULT_FINGERPRINT["color_scheme"],
+        },
+        "browser": {
+            "headless": DEFAULT_FINGERPRINT["headless"],
+            "stealth_args": DEFAULT_FINGERPRINT["stealth_args"],
+            "humanize": DEFAULT_FINGERPRINT["humanize"],
+            "human_preset": DEFAULT_FINGERPRINT["human_preset"],
+        },
+        "account": {
+            "alias": alias,
+            "platform": account.get("platform", "unknown"),
+            "label": account.get("label", alias),
+            "login_method": account.get("login_method", "unknown"),
+            "status": account.get("status", "active"),
+            "notes": account.get("notes", ""),
+        },
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "updated_at": datetime.now(timezone.utc).isoformat(),
+    }
+    save_profile_config(alias, config)
+
+    # 初始化 state.json
+    state = {
+        "is_logged_in": False,
+        "last_login_check": None,
+        "last_activity": None,
+        "login_method": account.get("login_method", "unknown"),
+        "notes": account.get("notes", ""),
+    }
+    save_profile_state(alias, state)
+
+    # 创建 browser_data 目录（CloakBrowser 自动创建，但先建好）
+    browser_data = profile_user_data_dir(alias)
+    browser_data.mkdir(parents=True, exist_ok=True)
+
+    # 创建空 cookie 快照文件
+    cookies_path = profile_path(alias) / "cookies.json"
+    if not cookies_path.exists():
+        with open(cookies_path, "w", encoding="utf-8") as f:
+            json.dump([], f)
+
+    print(f"\n{'='*60}")
+    print(f"  ✅ Profile 初始化完成: {alias}")
+    print(f"  📁 目录: {profile_dir}")
+    print(f"  🆔 指纹 seed: {fingerprint_seed[:16]}...")
+    print(f"  🌐 平台: {config['fingerprint']['platform']}")
+    print(f"  📍 locale: {config['fingerprint']['locale']}")
+    print(f"  🕐 timezone: {config['fingerprint']['timezone']}")
+    print(f"  🖥  viewport: {config['fingerprint']['viewport']}")
+    print(f"  👤 humanize: {config['browser']['humanize']}")
+    print(f"  🔑 登录方式: {config['account']['login_method']}")
+    print(f"{'='*60}\n")
+
+
+# ═══════════════════════════════════════════════════════════════
+# 3. Profile Lock 机制
+# ═══════════════════════════════════════════════════════════════
+def lock_path(alias: str) -> Path:
+    return LOCKS_DIR / f"{alias}.lock"
+
+
+def acquire_lock(alias: str, task_id: str) -> bool:
+    """
+    尝试获取 profile 锁。
+    返回 True 成功，False 失败（已被其他任务占用）。
+    """
+    lock_file = lock_path(alias)
+    lock_file.parent.mkdir(parents=True, exist_ok=True)
+
+    # 检查是否存在僵死锁
+    if lock_file.exists():
+        try:
+            data = json.loads(lock_file.read_text())
+            locked_at = data.get("locked_at", "")
+            locked_pid = data.get("pid", 0)
+            locked_task = data.get("task_id", "unknown")
+
+            # 检查进程是否还在运行
+            import subprocess
+            if locked_pid:
+                try:
+                    os.kill(locked_pid, 0)  # 信号 0 只检测进程存在
+                    process_alive = True
+                except (OSError, ProcessLookupError):
+                    process_alive = False
+            else:
+                process_alive = False
+
+            # 检查超时
+            if locked_at:
+                locked_dt = datetime.fromisoformat(locked_at)
+                elapsed = (datetime.now(timezone.utc) - locked_dt).total_seconds()
+                is_stale = elapsed > LOCK_STALE_TIMEOUT
+            else:
+                is_stale = False
+
+            if process_alive and not is_stale:
+                print(f"  ⛔ Profile [{alias}] 已被占用 (task: {locked_task}, pid: {locked_pid})")
+                return False
+            elif is_stale:
+                print(f"  ⚠️  检测到僵死锁 (task: {locked_task}, {elapsed:.0f}s 超时)，正在释放...")
+                release_lock(alias, locked_task)
+            else:
+                # 进程已死但尚未超时
+                print(f"  ⚠️  检测到过期锁 (task: {locked_task}, 进程已结束)，正在释放...")
+                release_lock(alias, locked_task)
+        except (json.JSONDecodeError, Exception) as e:
+            print(f"  ⚠️  锁文件异常 ({e})，覆盖...")
+            lock_file.unlink(missing_ok=True)
+
+    # 创建锁
+    lock_data = {
+        "task_id": task_id,
+        "locked_at": datetime.now(timezone.utc).isoformat(),
+        "pid": os.getpid(),
+        "hostname": os.uname().nodename,
+    }
+    try:
+        lock_file.write_text(json.dumps(lock_data, indent=2))
+        print(f"  🔒 已锁定 profile [{alias}] (task: {task_id})")
+        return True
+    except Exception as e:
+        print(f"  ❌ 锁写入失败: {e}")
+        return False
+
+
+def release_lock(alias: str, task_id: str):
+    """释放 profile 锁"""
+    lock_file = lock_path(alias)
+    if not lock_file.exists():
+        print(f"  🔓 Profile [{alias}] 没有被锁定")
+        return True
+
+    try:
+        data = json.loads(lock_file.read_text())
+        if data.get("task_id") != task_id:
+            print(f"  ⚠️  锁不属于当前任务 ({data.get('task_id')} != {task_id})，跳过")
+            return False
+        lock_file.unlink()
+        print(f"  🔓 已释放 profile [{alias}] (task: {task_id})")
+        return True
+    except Exception as e:
+        print(f"  ❌ 解锁失败: {e}")
+        # 强制删除
+        try:
+            lock_file.unlink(missing_ok=True)
+            print(f"  🔓 强制释放 profile [{alias}]")
+            return True
+        except Exception:
+            return False
+
+
+def list_locks() -> list[dict]:
+    """列出所有当前锁"""
+    locks = []
+    if not LOCKS_DIR.exists():
+        return locks
+    for f in sorted(LOCKS_DIR.glob("*.lock")):
+        try:
+            data = json.loads(f.read_text())
+            data["alias"] = f.stem.replace(".lock", "")
+            locks.append(data)
+        except Exception:
+            locks.append({"alias": f.stem.replace(".lock", ""), "error": "unreadable"})
+    return locks
+
+
+# ═══════════════════════════════════════════════════════════════
+# 4. 浏览器启动
+# ═══════════════════════════════════════════════════════════════
+def launch_browser(alias: str, task_id: str, headless: bool = False):
+    """
+    使用 CloakBrowser 启动一个持久化 profile 浏览器。
+    返回 (context, pages) 或抛出异常。
+    """
+    from media_agent.runtime.browser import launch_persistent_context
+
+    config = load_profile_config(alias)
+    if not config:
+        raise RuntimeError(f"Profile [{alias}] 未初始化，请先运行 init_account")
+
+    fp = config.get("fingerprint", {})
+    br = config.get("browser", {})
+
+    print(f"  🚀 启动 CloakBrowser: {alias}")
+    print(f"     user_data_dir: {profile_user_data_dir(alias)}")
+    print(f"     viewport: {fp.get('viewport', DEFAULT_FINGERPRINT['viewport'])}")
+    print(f"     locale: {fp.get('locale', 'zh-CN')}")
+    print(f"     timezone: {fp.get('timezone', 'Asia/Shanghai')}")
+
+    # 构建 viewport 参数
+    viewport = fp.get("viewport", DEFAULT_FINGERPRINT["viewport"])
+
+    context = launch_persistent_context(
+        user_data_dir=str(profile_user_data_dir(alias)),
+        headless=headless,
+        stealth_args=br.get("stealth_args", True),
+        viewport=viewport,
+        locale=fp.get("locale", "zh-CN"),
+        timezone=fp.get("timezone", "Asia/Shanghai"),
+        color_scheme=fp.get("color_scheme", "light"),
+        humanize=br.get("humanize", True),
+        human_preset=br.get("human_preset", "default"),
+        # 显式不启用 geoip，保持指纹固定
+        geoip=False,
+    )
+
+    # 更新最后活动时间
+    state = load_profile_state(alias)
+    state["last_activity"] = datetime.now(timezone.utc).isoformat()
+    save_profile_state(alias, state)
+
+    return context
+
+
+# ═══════════════════════════════════════════════════════════════
+# 5. 登录状态检查
+# ═══════════════════════════════════════════════════════════════
+def check_login_status(alias: str, page) -> bool:
+    """
+    检查当前页面是否已登录。
+    需传入对应平台的 page 对象，子类化实现。
+    返回 True 已登录 / False 未登录。
+    """
+    # 由各平台具体实现
+    raise NotImplementedError("由各平台子类实现")
+
+
+# ═══════════════════════════════════════════════════════════════
+# 6. 人工接管流程
+# ═══════════════════════════════════════════════════════════════
+def human_intervene(alias: str, reason: str, screenshot_path=None):
+    """
+    暂停任务，通知用户人工处理。
+    输出格式供 Hermes Agent 解析并通知用户。
+    """
+    msg = [
+        f"\n{'🔴'*30}",
+        f"  需要人工介入！",
+        f"  Profile: {alias}",
+        f"  原因: {reason}",
+        f"  截图: {screenshot_path or '无'}",
+        f"{'🔴'*30}\n",
+    ]
+    print("\n".join(msg))
+    return msg
+
+
+# ═══════════════════════════════════════════════════════════════
+# CLI 入口
+# ═══════════════════════════════════════════════════════════════
+def cmd_init(alias: str, platform: str, label: str, login_method: str, notes: str = ""):
+    """初始化新账号: init_account <alias> --platform <p> --label <l> --login <m>"""
+    account = {
+        "alias": alias,
+        "platform": platform,
+        "label": label,
+        "login_method": login_method,
+        "status": "active",
+        "notes": notes,
+    }
+    accounts = load_accounts()
+
+    # 检查是否已存在
+    existing = find_account(alias)
+    if existing:
+        print(f"⚠️  账号 [{alias}] 已存在，跳过")
+        return
+
+    accounts.append(account)
+    save_accounts(accounts)
+    init_profile(alias, account)
+
+
+def cmd_list():
+    """列出所有账号"""
+    accounts = load_accounts()
+    locks = {l["alias"]: l for l in list_locks()}
+
+    print(f"\n{'='*60}")
+    print(f"  社交媒体账号列表 ({len(accounts)} 个)")
+    print(f"{'='*60}")
+    for a in accounts:
+        alias = a["alias"]
+        state = load_profile_state(alias)
+        locked = "🔒" if alias in locks else "  "
+        logged = "✅" if state.get("is_logged_in") else "⬜"
+        print(f"  {locked} {logged} [{alias:20s}] {a.get('label',''):10s}  {a['platform']:12s}  {a.get('status','')}")
+    print(f"{'='*60}\n")
+
+
+def cmd_status(alias: str):
+    """查看单个 profile 状态"""
+    config = load_profile_config(alias)
+    state = load_profile_state(alias)
+
+    if not config:
+        print(f"❌ Profile [{alias}] 不存在")
+        return
+
+    acct = find_account(alias) or config.get("account", {})
+
+    print(f"\n{'='*60}")
+    print(f"  Profile: {alias}")
+    print(f"{'='*60}")
+    print(f"  accounts.yaml status: {acct.get('status', 'unknown')}")
+    print(f"  state.json is_logged_in: {state.get('is_logged_in', False)}")
+    print(f"  last_login_check: {state.get('last_login_check', 'never')}")
+    print(f"  profile_path: {profile_path(alias)}")
+    locked = "是"
+    locks = list_locks()
+    l = next((l for l in locks if l["alias"] == alias), None)
+    if not l:
+        locked = "否"
+    print(f"  锁定状态: {locked}")
+    if l:
+        print(f"    锁信息: task={l.get('task_id','?')} pid={l.get('pid','?')} locked_at={l.get('locked_at','?')}")
+    print(f"  平台: {acct.get('platform', '?')}  标签: {acct.get('label', '?')}  登录方式: {acct.get('login_method', '?')}")
+    print(f"  指纹 seed: {config.get('fingerprint', {}).get('seed', '?')[:16]}...")
+    print(f"  viewport: {config.get('fingerprint', {}).get('viewport', '?')}")
+    print(f"{'='*60}\n")
+
+
+def cmd_locks():
+    """查看所有锁"""
+    locks = list_locks()
+    if not locks:
+        print("  当前没有活跃锁")
+        return
+    print(f"\n  当前活跃锁 ({len(locks)} 个):")
+    now = datetime.now(timezone.utc)
+    for l in locks:
+        alias = l.get("alias", "?")
+        task = l.get("task_id", "?")
+        locked_at = l.get("locked_at", "?")
+        pid = l.get("pid", "?")
+        stale = ""
+        try:
+            locked_dt = datetime.fromisoformat(locked_at)
+            elapsed = (now - locked_dt).total_seconds()
+            if elapsed > LOCK_STALE_TIMEOUT:
+                stale = " ⚠️ 僵尸锁 (已超时)"
+        except:
+            stale = " ⚠️ 时间解析失败"
+        print(f"  🔒 {alias:20s} task={task:20s} pid={pid} locked_at={locked_at}{stale}")
+
+
+def cmd_open(alias: str):
+    """打开 profile 进入企业号后台"""
+    import uuid
+    task_id = f"open_{alias}_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+
+    # acquire lock
+    if not acquire_lock(alias, task_id):
+        return
+
+    try:
+        from media_agent.runtime.browser import launch_persistent_context
+
+        config = load_profile_config(alias)
+        if not config:
+            print(f"❌ Profile [{alias}] 未初始化")
+            release_lock(alias, task_id)
+            return
+
+        fp = config.get("fingerprint", {})
+        br = config.get("browser", {})
+
+        print(f"  🚀 启动 CloakBrowser: {alias}")
+        context = launch_persistent_context(
+            user_data_dir=str(profile_user_data_dir(alias)),
+            headless=False,
+            stealth_args=br.get("stealth_args", True),
+            viewport=fp.get("viewport", {"width": 1440, "height": 900}),
+            locale=fp.get("locale", "zh-CN"),
+            timezone=fp.get("timezone", "Asia/Shanghai"),
+            color_scheme=fp.get("color_scheme", "light"),
+            humanize=True,
+            human_preset="default",
+            geoip=False,
+        )
+        page = context.pages[0] if context.pages else context.new_page()
+        page.goto("https://e.douyin.com/", wait_until="domcontentloaded", timeout=30000)
+        import time
+        time.sleep(3)
+
+        logged_in = "login" not in page.url.lower() and "passport" not in page.url.lower()
+        if logged_in:
+            print(f"  ✅ 已进入后台: {page.url}")
+        else:
+            print(f"  ⚠️ 未登录，当前页面: {page.url}")
+            print(f"  ⚠️ 浏览器保持打开，请手动扫码登录")
+
+        # 保持浏览器打开
+        print(f"  🔄 浏览器保持打开中... (按 Ctrl+C 关闭)")
+        while True:
+            time.sleep(10)
+            cu = page.url
+            if "login" not in cu.lower() and "passport" not in cu.lower():
+                if not logged_in:
+                    print(f"  ✅ 检测到登录成功: {cu}")
+                    logged_in = True
+    except KeyboardInterrupt:
+        print(f"\n  🛑 用户中断")
+    finally:
+        try:
+            context.close()
+        except:
+            pass
+        release_lock(alias, task_id)
+        print(f"  ✅ 浏览器已关闭，锁已释放")
+
+
+def cmd_check_login(alias: str):
+    """检查登录状态，更新 state.json，截图留痕"""
+    import uuid
+    import time
+    task_id = f"check_{alias}_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+
+    if not acquire_lock(alias, task_id):
+        return
+
+    try:
+        from media_agent.runtime.browser import launch_persistent_context
+
+        config = load_profile_config(alias)
+        if not config:
+            print(f"❌ Profile [{alias}] 未初始化")
+            release_lock(alias, task_id)
+            return
+
+        fp = config.get("fingerprint", {})
+        br = config.get("browser", {})
+
+        context = launch_persistent_context(
+            user_data_dir=str(profile_user_data_dir(alias)),
+            headless=False,
+            stealth_args=br.get("stealth_args", True),
+            viewport=fp.get("viewport", {"width": 1440, "height": 900}),
+            locale=fp.get("locale", "zh-CN"),
+            timezone=fp.get("timezone", "Asia/Shanghai"),
+            color_scheme=fp.get("color_scheme", "light"),
+            humanize=True,
+            human_preset="default",
+            geoip=False,
+        )
+        page = context.pages[0] if context.pages else context.new_page()
+        page.goto("https://e.douyin.com/", wait_until="domcontentloaded", timeout=30000)
+        time.sleep(3)
+
+        logged_in = "login" not in page.url.lower() and "passport" not in page.url.lower()
+        now_ts = time.strftime("%Y-%m-%dT%H:%M:%S+00:00", time.gmtime())
+
+        # 截图
+        screenshot = str(BASE_DIR / "screenshots" / f"{alias}_check_login_{datetime.now().strftime('%Y%m%d_%H%M%S')}.png")
+        page.screenshot(path=screenshot, full_page=True)
+
+        # 更新 state.json
+        state = load_profile_state(alias)
+        state["is_logged_in"] = logged_in
+        state["last_login_check"] = now_ts
+        state["last_activity"] = now_ts
+        save_profile_state(alias, state)
+
+        if logged_in:
+            print(f"  ✅ 登录状态正常 - 免扫码进入后台")
+            print(f"  URL: {page.url}")
+        else:
+            print(f"  ⚠️ 未登录 - 当前页面: {page.url}")
+            print(f"  📸 截图: {screenshot}")
+
+        print(f"  📸 截图: {screenshot}")
+        print(f"  📝 state.json: is_logged_in={logged_in}, last_login_check={now_ts}")
+
+        context.close()
+        print(f"  ✅ 浏览器已关闭")
+    finally:
+        release_lock(alias, task_id)
+        print(f"  ✅ 锁已释放")
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="社交媒体账号 Profile 管理")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # init
+    p_init = sub.add_parser("init", help="初始化新账号 profile")
+    p_init.add_argument("alias", help="账号别名")
+    p_init.add_argument("--platform", required=True, help="平台名称")
+    p_init.add_argument("--label", required=True, help="中文备注")
+    p_init.add_argument("--login", required=True, help="登录方式: phone_qr/phone_code/password/wechat")
+    p_init.add_argument("--notes", default="", help="备注")
+
+    # list
+    sub.add_parser("list", help="列出所有账号")
+
+    # open
+    p_open = sub.add_parser("open", help="打开 profile 进入后台")
+    p_open.add_argument("alias", help="账号别名")
+
+    # check-login
+    p_check = sub.add_parser("check-login", help="检查登录状态")
+    p_check.add_argument("alias", help="账号别名")
+
+    # status
+    p_status = sub.add_parser("status", help="查看 profile 状态")
+    p_status.add_argument("alias", help="账号别名")
+
+    # locks
+    sub.add_parser("locks", help="查看所有锁")
+
+    args = parser.parse_args()
+
+    if args.command == "init":
+        cmd_init(args.alias, args.platform, args.label, args.login, args.notes)
+    elif args.command == "list":
+        cmd_list()
+    elif args.command == "open":
+        cmd_open(args.alias)
+    elif args.command == "check-login":
+        cmd_check_login(args.alias)
+    elif args.command == "status":
+        cmd_status(args.alias)
+    elif args.command == "locks":
+        cmd_locks()

package/src/media_agent/runtime/browser.py

@@ -0,0 +1,5 @@
+"""Load the optional browser dependency only when an operation launches it."""
+
+def launch_persistent_context(*args, **kwargs):
+    from cloakbrowser import launch_persistent_context as launch
+    return launch(*args, **kwargs)

package/src/media_agent/runtime/paths.py

@@ -0,0 +1,7 @@
+"""One data root shared by CLI, controllers and direct script entry points."""
+import os
+from pathlib import Path
+
+
+def runtime_home():
+    return Path(os.environ.get('MEDIA_AGENT_HOME') or Path.home() / '.media-agent' / 'social-accounts').expanduser().resolve()