Browser workflow
Discover once, preserve identifiers and inspect real outcomes.
API 2.3.3 · Published service contract ↗
Recommended sequence
- Setup once: use the existing authenticated connection and selected approved Pass; sym_account is optional diagnostics.
- Call sym_passes only if the approved Pass ID is unknown; tools/list discovers tools, not browsers.
- Read sym_pass_docs once for the selected Pass; retain profile/revision and target IDs. Subsequent actions invoke directly without account/discovery/tabs/window/navigation preflights.
- Use sym_browser_read/sym_computer_read for observation and sym_browser_act/sym_computer_act for actions. Legacy sym_browser/sym_computer remain compatible mixed-operation tools. Use the same Pass/session and a fresh requestId. Browser arguments are validated against that operation’s exact native schema.
- Inspect the result after acting. Never automatically replay an uncertain action. Reconnect OAuth only for authentication errors, not payment_required.
Browser envelope
{
"passId": "<chosen-pass-id>",
"requestId": "<new-unique-request-id>",
"operation": {
"verb": "<supported-verb>",
"profile": "<chosen-profile>",
"tabId": "<explicit-tab-id-when-required>",
"capabilityRevision": "<current-revision>",
"args": "<exact-operation-arguments>"
}
}Work sessions and reservations
{
"contract": "work-session-continuity-v1",
"reference": "/docs/work-sessions",
"readable": "/docs/work-sessions.md",
"argumentPlacement": {
"browser": "operation.args.workSessionId on tab operations; not beside operation or inside input.",
"skill": "Top-level workSessionId on sym_skill_run, alongside passId/profile/tabId; never inside skill input.",
"inventory": "docs/tabs/bookmarks use their own schemas; do not append a session token to every tool indiscriminately."
},
"recovery": {
"unreserved": "Controlled async and CPU stalls outside a native work-session reservation were stopped by the existing consented recoverWindow path: document replacement verified, exclusion released, next action succeeded without replay.",
"reserved": "Known limitation of published extension 0.1.29: a genuinely stalled reserved session blocks/queues the native reset commands. API-only session propagation does not fix that installed execution queue. Recovery can fail; the server deliberately retains exclusion. Do not release locks, drop the reservation, repeatedly retry recovery, or claim the old script stopped.",
"consent": "recoverWindow requires explicit user acceptance of reloading the exact blocked tab, with confirmReload:true. Reload can lose unsaved state and cannot undo submitted mutations. No previous operation is automatically replayed.",
"next": "For an unresolved reserved-session stall, stop automation in that window and report the blocker for explicit user/operator handling. Manual reload or closing a page is not proof the server lock cleared. Automatic reserved-stall recovery requires a separately verified installed-component change; none is shipped here."
}
}Browser examples
[
{
"purpose": "Create a separate Chrome window, not a new tab",
"verb": "workWindow",
"args": {
"mode": "own",
"sessionKey": "<stable-key-for-this-task>"
},
"note": "Requires a same-profile tabId anchor. Save returned windowId and workSessionId; no OS foreground focus is requested."
},
{
"purpose": "Open a tab in that work window",
"verb": "newTab",
"args": {
"url": "https://example.com/",
"windowId": "<returned-window-id>",
"workSessionId": "<returned-work-session-id>"
},
"note": "No tabId required. Numeric IDs above are placeholders, not executable values."
},
{
"purpose": "Release the session without closing tabs",
"verb": "endWorkSession",
"args": {
"workSessionId": "<returned-work-session-id>"
},
"note": "Use a tabId in that work window."
}
]