More custom code cleanup

[pirate]

Summary by cubic

Standardized custom-code boundaries in the client and tightened typing for session resources. Hardened the example by validating observe results as dicts and restored the _sea keep file.

• Refactors

  • Standardized custom-code markers across Stagehand and AsyncStagehand methods; no logic changes.
  • Clarified sessions accessors’ type hints via TYPE_CHECKING imports; runtime imports unchanged.
  • Updated with_options comment (start → create).
  • Restored src/stagehand/_sea/.keep to keep the directory in VCS.

• Bug Fixes

  • Example: Validate observe stream items are dicts and read ['description']; raises a clear error if not.

^{Written for commit a150bbe. Summary will update on new commits. Review in cubic}

[cubic-dev-ai]

No issues found across 3 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    应用 ->> 客户端 (Stagehand): 初始化 (server_mode="local" | "remote")
    Note over 客户端 (Stagehand), 内部逻辑 (_custom): 标记: 运行时补丁逻辑封装在 _custom 模块中

    应用 ->> 会话资源 (SessionsResource): sessions.observe(...)
    会话资源 (SessionsResource) ->> 客户端 (Stagehand): 调用 _prepare_options()

    alt 模式: 本地 (Local Mode)
        客户端 (Stagehand) ->> 内部逻辑 (_custom): prepare_client_base_url()
        内部逻辑 (_custom) ->> SEA 服务进程: CHANGED: 延迟启动本地 SEA 服务
        SEA 服务进程 -->> 内部逻辑 (_custom): 返回本地 URL
        内部逻辑 (_custom) -->> 客户端 (Stagehand): 更新 base_url 为本地地址
    else 模式: 远程 (Remote Mode)
        Note over 客户端 (Stagehand): 使用默认 Browserbase API URL
    end

    客户端 (Stagehand) ->> SEA 服务进程: 发起 HTTP 请求 (观察页面)
    SEA 服务进程 -->> 客户端 (Stagehand): 返回结果流 (JSON 数据)
    客户端 (Stagehand) -->> 应用: 返回结果列表

    Note over 应用: NEW: 增强的类型校验
    alt 结果验证
        应用 ->> 应用: 检查 result 是否为 dict
        opt 类型不匹配
            应用 -->> 应用: 抛出 RuntimeError (明确的错误信息)
        end
        应用 ->> 应用: 读取 result['description']
    end

    应用 ->> 客户端 (Stagehand): close()
    客户端 (Stagehand) ->> 客户端 (Stagehand): 调用 super.close() (关闭 HTTP 连接)
    客户端 (Stagehand) ->> 内部逻辑 (_custom): CHANGED: 调用 close_client_sea_server()
    内部逻辑 (_custom) ->> SEA 服务进程: 终止受管进程

Loading