Sessions & HITL
Find out which account or session is broken
Open warnings the platform raised about a run's login process — a credentialed login missing its stored secret, or a saved cookie session that stopped working. Named by host and account, so you fix the right one.
list_warnings
What it is
The job: Stop retrying a task blind when the real problem is a broken login, not the goal.
A run that fails on a site you thought you were already signed into is not always a planning problem. Two of the most common causes are login-shaped: the vault has no stored secret for a `{{secret:NAME}}` the login needed (`kind:"credential_missing"`), or a previously captured cookie session was restored and the run still failed because the site no longer honors it (`kind:"session_stale"`). list_warnings is where the platform puts both, instead of leaving them to repeat silently inside failed run results.
Each row carries the host and account it is about, a human-readable message, and — for credential_missing — which secret name is missing. Rows are DEDUPED per (kind, host, account): an account that is broken on every run produces one open warning, not one per run. A later failure on the same identity refreshes it rather than adding a duplicate.
Warnings persist until acknowledged. Fix the underlying problem (store the secret, or send the user through connect_account), then call acknowledge_warning — a later failure on the same identity raises a fresh one, so acknowledging never hides a real recurrence.
The call
Call it exactly like this.
Copied from the tool's registration and the route handler — not paraphrased.
// MCP tool call — server "twin-browser"
{
"tool": "list_warnings",
"arguments": {}
}curl -X GET "https://twin-browser.com/api/v1/warnings" \
-H "Authorization: Bearer $TWIN_API_KEY"| Parameter | Type | What it does |
|---|---|---|
| all | boolean | Include already-acknowledged warnings too (default: open only). |
Returns
{
"warnings": [
{ "id": "…", "kind": "credential_missing", "severity": "warning",
"host": "example.com", "account": "work", "run_id": "…",
"message": "Login on example.com needs the \"password\" credential, which isn't stored — …",
"detail": { "missingSecret": "password" },
"created_at": "…", "acknowledged_at": null }
],
"count": 1
}What it costs
Free
A metadata read. No credits — it is meant to sit ahead of a retry, not inside one.
See the full rate cardWhich one
When a different tool is the right call.
The honest answer is often the neighbouring tool. These are the trades.
list_accountslist_accounts says which logins exist; list_warnings says which of them are currently broken and why. Check warnings when a login-shaped task keeps failing despite an account being on file.
list_accountslist_connectionslist_connections tracks a hand-off link you sent; list_warnings tracks something the platform noticed on its own, without you having minted anything.
list_connectionsQuestions
list_warnings, answered.
- Does a warning ever fire for a reason other than login?
- Not yet — today the two kinds are credential_missing and session_stale, both raised from the sync run endpoint. `kind` is intentionally free text on the platform side, so more classes (rate-limit cooldowns, a session too large to persist) can land here later without a new tool.
- Will this list grow without bound if an account stays broken?
- No — warnings are deduped per (kind, host, account). A run that keeps failing the same way refreshes the one open row's timestamp and message instead of adding another.
Keep going
The rest of the tool set.
acknowledge_warningClose the loop after fixing what a warning named — a missing secret now stored, or a fresh session captured.
list_accountsAnswer “can I get into this site, and as whom?” before starting a run.
connect_accountGet logged into a site that an agent is not going to be allowed to log into.