Sessions and tabs
How an agent splits work into sessions, how tabs are opened, grouped and borrowed, and the limits that apply.
Developer preview
A session is the unit of work in oh-my-webbridge. Every command names a session, and the daemon routes it to the tabs that session holds. Tabs opened by a session sit in a tab group titled with the session name or the title the agent passed, so a task's pages stay together and apart from the pages you use.
One session per task
Give each task its own session name and reuse it for everything the task does. Tasks that run at the same time use different names. Each session keeps its own tabs, tab group, current tab, presets and frame selection. The browser runs commands from different sessions at the same time.
omw call research navigate '{"url":"https://example.com/docs","group_title":"Research"}'
omw call billing navigate '{"url":"https://example.com/pricing","group_title":"Billing"}'A session starts with its first command. Its name is 1 to 96 letters (including CJK), digits, _, . or -.
A session stays in one browser
A session's first command decides the browser it stays in: the browser named by browser, the only connected browser, or Chrome when both are connected. Later commands for that session go there, even after the other browser connects. close_session removes the binding. A command that asks for the other browser fails with session_browser.
Commands run in arrival order
Each session has one queue. Commands for a session run one at a time, in the order the daemon receives them, so a click that follows a snapshot acts on the page that snapshot described. Sessions do not share a queue, and a page that responds slowly in one session does not hold another session.
dialog and close_session are answered outside the session queue, so they still reach a tab whose command is waiting. One session can have 32 commands running or waiting at once.
New tabs open in the background
navigate opens a tab when the session has no current tab or the command sets newTab. The tab opens in the background and joins the session's tab group:
{
"session": "research",
"action": "navigate",
"args": { "url": "https://example.com/docs", "newTab": true, "group_title": "Research" }
}group_titlesets the title of the group. A navigation that opens a tab can change it; otherwise the current title stays. The default is the session name.- The group is created collapsed, so task tabs do not widen the tab strip. Expand it to look at the pages.
- A later
navigatewithoutnewTabreuses the current tab. A session holds at most 32 tabs, task and borrowed together. list_tabsreturns only the session's tabs, with URL, title, active flag, group title and whether the tab is borrowed.
Borrowing one of your tabs
find_tab with active: true claims the tab that is active in the last focused window. The URL must match exactly or by hostname:
omw call research find_tab '{"url":"example.com","active":true}'Without active: true, find_tab only looks at tabs the session already holds. A borrowed tab stays open, and close_tab refuses it with borrowed_tab. The session uses it and releases it when it ends. One tab belongs to one session at a time, and another session that asks for it gets tab_busy. Presets apply only to tabs the session opened. Borrow a tab when the task needs the page you have open; otherwise open a task tab.
Ending a session
close_session cancels the commands still running or waiting for the session, closes the tabs the session opened, and releases the ones it borrowed, which stay open. It removes the session's browser binding and drops what the session recorded on borrowed tabs: frame selection, network entries, console output and @e references. Closing a tab yourself removes it from the session; the session ends only with close_session. When the session's current tab closes other than by close_tab, the session has no current tab: a page action without tabId fails with no_tab, and a command for the closed tab fails with tab_missing. After close_tab, the session continues in the tab it opened last, or else the tab it borrowed last.
Limits
| Limit | Value |
|---|---|
| Sessions | 128 per browser |
| Tabs per session | 32, task and borrowed together |
| Commands running at once | 128 per browser; close_session and dialog use 16 more |
| Commands per session | 32 running or waiting |
| Session name | 1 to 96 letters (including CJK), digits, _, . or - |
timeoutMs | 1 to 120000, default 30000 |
When a limit is reached the command fails with busy and HTTP 429 instead of waiting. Reduce concurrency, or close sessions that are finished.
Timeouts and uncertain results
timeoutMs covers the whole request, including time spent waiting in the session queue. When it runs out, when close_session cancels the command, or when the browser disconnects in the middle of a command, the call returns outcome_unknown, and the message names the cause. The action may already have reached the page: a click may have happened, a form may be submitted. A wait whose condition does not hold fails with wait_timeout just before the deadline instead; it does not change the page.
Retrying after outcome_unknown
Observe the page before reusing a command. snapshot, read_page, the tab URL, get and the
network log show what the page did. Send a command again only when the state shows the action did
not happen, and never replay a payment, publish or submit automatically.
Logins come from your profile
Task tabs and borrowed tabs run in your browser profile, with its cookies, sessions and logins. Sessions and tab groups organize tabs, not accounts: every session sees the same logins, and clearing cookies or site storage for one task clears them for the profile. Sign out of a site when the next task should start signed out.
