v2.0.0.8 - Cookie Management and Integration Reliability Update

中文发行说明

v2.0.0.8 新增 Cookie 历史查询、本地与远端快照读写及健康检查接口，完善运行中环境重复打开时的窗口激活、生命周期终态与本地 MCP 接入契约，同时保持既有 C ABI、Web API 和 WebSocket 接入兼容。

English Release Notes

Highlights
BroSDK 2.0.0.8 expands the public Cookie management surface and strengthens lifecycle and local automation integration contracts. The release adds Cookie history access, local and remote snapshot operations, offline health analysis, idempotent handling for repeated browser-open requests, and updated MCP integration guidance.

Existing C ABI, C++ ISDK, local Web API, and WebSocket integrations remain compatible. Applications can adopt the new capabilities incrementally by updating both the runtime library and the matching brosdk.h.

New Features
Added six synchronous public Cookie APIs: sdk_get_cookies_history, sdk_get_cookies_local, sdk_set_cookies_local, sdk_get_cookies_remote, sdk_set_cookies_remote, and sdk_cookies_health_check. Equivalent methods are available through C++ ISDK.

Added Cookie history lookup for an environment. History entries expose an opaque fileUrl that can be passed unchanged to sdk_get_cookies_remote; when an md5 value is present, it can be supplied for integrity checking.

Added local Cookie snapshot read and write operations that work without starting the browser environment. Local reads return the latest persisted Cookie array, while local writes update only the local snapshot.

Added remote Cookie snapshot read and write operations. A remote history node can be retrieved and decoded directly into a Cookie array without changing the local snapshot or a running browser. After a remote write succeeds, BroSDK also attempts a best-effort refresh of the local snapshot.

Added sdk_cookies_health_check, a synchronous offline analyzer that does not require SDK initialization, a running browser, or network access. It reports health by domain, Cookie persistence and expiration state, authentication-token time windows when detectable, issue severity, and the remaining seconds before expiration.

Added POST /sdk/v1/env/getcookiehistory for Cookie history access through the local Web API.

Operational Improvements
Opening an environment that is already running is now treated as an idempotent success. BroSDK keeps the existing browser instance, attempts to activate its window, and emits browser-open-success with CL_WBRWALREADYRUNNING (107) and data.alreadyRunning=true.

Applications must use the terminal event type as the primary success or failure signal. A nonzero warning code carried by browser-open-success is still a successful terminal result.

Browser close completion is independent of subsequent remote synchronization. browser-close-success means that the browser has exited and the local data required by the close operation has been persisted; remote synchronization may continue afterward.

The Cookie health report exposes remainingSeconds for individual Cookies and nextExpirationRemainingSeconds for each domain. expiresSoonThresholdSeconds=86400 is the warning window, not the Cookie lifetime.

Cookie Persistence Contract
The Cookie persistence callback receives the standard event envelope, with the Cookie array in data.cookies.

A replacement must be a complete, non-empty array containing at least one injectable Cookie. Invalid JSON, an empty array, or a replacement in which every Cookie is rejected preserves the original snapshot; the callback is not a Cookie-clearing API.

Local and remote Cookie setters do not modify Cookies in a running browser. A newer snapshot captured when that browser closes may replace an earlier manual write.

MCP Integration Updates
Updated MCP initialization examples to protocol version 2025-11-25 and aligned the documented global and single-environment contracts with v2.0.0.8.

MCP clients must discover capabilities through tools/list and use the returned inputSchema definitions instead of relying on a hard-coded tool count or a tool list from an earlier release.

Global MCP browser.open and browser.close calls are asynchronous. A successful tool response means that the request was accepted; clients must retain the returned taskId and poll task.get with bounded backoff until the task reaches succeeded or failed.

If a management task times out or is no longer available, clients must query the current browser state before retrying any operation that has side effects. Global GET is a heartbeat endpoint and does not replay lifecycle events.

Single-environment event streams can resume from the latest available tab-state revision by sending Last-Event-ID. Artifact data remains scoped to the creating session and environment, and clients must validate both chunk metadata and the complete result size and hash.

Compatibility Notes
No existing public C ABI or Web API signature is removed or changed by this release.

Use the v2.0.0.8 runtime and brosdk.h together. Mixing header and runtime versions is unsupported.

Treat every envId as a decimal string. JavaScript clients must not convert environment identifiers to number, because they may exceed safe integer precision.

Direct returns from asynchronous C/C++ calls and HTTP acknowledgement responses indicate acceptance only. Continue waiting for the result callback, WebSocket terminal event, or MCP task terminal state required by the selected integration surface.

Cookie APIs do not read or modify browser Storage. Storage continues to follow the environment configuration and browser lifecycle contract.

sdk_env_get_cookies is not supported in v2.0.0.8. Use the dedicated Cookie APIs introduced by this release.

MCP browser.install reports acceptance but does not expose terminal completion through an MCP task in this release. Integrations that require an installation result must use the native result callback or the local Web API together with WebSocket terminal events.

Cookie Health Limitations
Cookie health analysis is diagnostic and does not verify that a website session is accepted by the server.

remainingSeconds is the direct difference between the Cookie expiration time and checkedAt. Negative values indicate expiration; session Cookies and Cookies without a valid expiration use null.

Token time analysis does not verify cryptographic signatures. A time_valid result only means that the visible time claims are currently valid; it is not proof that the login is still accepted.

Changing a session Cookie into a persistent Cookie or assigning an extreme expiration date does not extend a server-side session and may damage the original Cookie semantics.

Security And Data Handling
Cookie values, API keys, user tokens, proxy credentials, page content, and artifact bytes are sensitive. Do not include complete Cookie requests, responses, callbacks, or health-check inputs in normal application logs.

Cookie health output intentionally omits Cookie values. Preserve unknown Cookie fields when reading, inspecting, or writing Cookie arrays, and modify only fields explicitly owned by the application.

MCP and local Web API endpoints are intended for trusted same-machine clients. Do not expose the SDK listening port to untrusted networks.

Recommended Upgrade Validation
Before production rollout, validate initialization, browser open, repeated open, browser close, local Cookie read and write, Cookie history retrieval, remote snapshot retrieval and update, Cookie health analysis, WebSocket terminal events, MCP task completion, and artifact integrity in a non-production environment.

Integrations should also verify that warning-success events are accepted correctly, all SDK-owned output buffers are released with sdk_free(), and every envId remains a string across native, Web, WebSocket, and MCP boundaries.

Reference
For the complete v2.0.0.8 integration contract, see docs/brosdk/release/sdk-reference-v2.0.0.8.md.