@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/man/await_user.md

@@ -0,0 +1,214 @@
+<!-- also: await_click, next, ask -->
+<!-- group: Talking to the user -->
+
+# api.await_user(target=None, timeout_seconds=300) -> dict
+
+Wait for the person to do something, and say what they did.
+
+**One wait, five answers**, because somebody being guided has more than one
+thing they might do:
+
+```python
+{"clicked": True}                 # they clicked the control you rang
+{"advanced": True}                # they pressed Next
+{"reported": True}                # they marked what is wrong and sent it
+{"asked": "why this one?"}        # they typed a question
+{"stopped": True}                 # they ended it — Finish, or the chat
+{"clicked": False, "reason": …}   # nothing, for the whole window
+```
+
+**`reported` is the one to read differently.** It always carries
+`annotations`, and it means they stopped to say something is wrong rather than
+doing what the step asked. Writing step N+1 on it is the mistake it exists to
+prevent: deal with what is marked first. It ends the *step*, not the demo — you
+may well want to acknowledge it with an `instruct` and carry on, and that is
+your call to make rather than theirs to have made for them.
+
+Any of them may also carry `annotations`: boxes somebody drew on the app with
+**Mark what is wrong**, each with a note and a picture of the screen as it was
+when they wrote it.
+
+Pressing it opens a marking layer over the whole window, with a card of its own
+in the corner — the notes taken so far, a ✕ to take any of them back, and
+**Submit annotations**, which is what answers `reported`. While it is open the
+step card puts its own controls away: Next beside a Done marking that could not
+be reached was the reported confusion, and there is now exactly one way forward
+on screen at a time. **Discard and return** leaves without sending, and the wait
+does not time out while somebody is writing.
+
+**That is the point of showing somebody something rather than asking them.** A
+demo walked end to end can still be a demo of six broken screens, and until
+there was somewhere to put that, the only thing a step could be answered with
+was Next. Deal with what they marked before you claim anything works.
+
+```python
+[{"region": {"x": 0.04, "y": 0.31, "width": 0.47, "height": 0.11},
+  "note": "this column is empty",
+  "$image": {...}}]                 # regions are 0-1, so a resize cannot move them
+```
+
+Notes are banked the moment they are written, each with its own picture —
+a tour is a sequence of screens, so one photograph taken at the end would show
+the last one for every note. Drawing does not end the step it is about.
+
+## The row in the chat
+
+A tour runs in its own window, so for as long as one is running it also raises a
+row in the chat and in **Needs you** — otherwise an agent blocked on somebody
+looks exactly like an agent that is busy, and a demo waits in a window nobody
+knows to look at.
+
+`instruct` opens that row and moves it along; `instruct(None)` closes it.
+
+That row carries exactly two buttons, and it is worth knowing which, because
+you will be tempted to tell somebody to press one that is not there.
+
+- **Show me the app** raises the window the demo is drawn in. It answers
+  nothing — it is where you send somebody who has lost the tour behind the chat,
+  and it is the sentence `unraised` is asking you to pass on.
+- **Stop** settles this wait with `{"stopped": True}` and takes the card and the
+  ring down.
+
+There is no Done, no Decline and no Ask on a tour row. Finishing a demo means
+*performing* it, which happens in the app, so those are not answers a row in the
+chat is in a position to give — it used to draw them anyway and they silently
+did nothing. Ask lives on the card instead, beside the step it is about, which
+is the only place a question can be asked with the app in front of you.
+
+Whichever surface they reach for wins — you never get two answers to the same
+step.
+
+**Finish demo**, on the step card itself — its own line under a rule, a whole
+row away from Next — reports `stopped` the same way. It is there because the
+card is drawn in the application's own window, and until it was wired the only
+way to stop a demo was somewhere else, so "I have seen enough" meant leaving the
+thing being shown.
+
+`stopped` is not a failure. Take the card down, say what you were about to show
+in a sentence, and stop.
+
+**Except when nobody stopped it.** The row retires itself after an hour with no
+step, and that arrives here as `stopped` too — carrying a `reason` that says so.
+Every step restarts that clock, so it does not fire under a demo being walked
+through; when it does fire, it means the demo went an hour without moving. Read
+the `reason` before you thank anybody for their time:
+
+```python
+{"stopped": True, "reason": "the demo row expired — an hour passed with no step…"}
+```
+
+## Three answers that are not "they did nothing"
+
+A `{"clicked": false}` has three quite different causes and the `reason` says
+which. Only the last is the person's doing.
+
+- **`unwatched`** — *"nothing was watching that control, so a click could not
+  have been seen"*. The target could not be found when the wait was armed, so
+  the card was drawn and Next and Ask worked, but a press on the control itself
+  was never going to arrive. Not a person ignoring you; a step you aimed at
+  something that is not there.
+- **the window was never in front** — see below.
+- **`"observation timed out"`** — nothing was seen. Named for the *observation*
+  rather than the person on purpose: the harness can miss somebody who acted,
+  and "timed out" reads as being ignored. If presses were seen elsewhere on the
+  page the sentence says how many, and that is the case where they were doing
+  something and this did not agree it counted — not a verdict on the feature.
+
+## Two fields that change what an answer means
+
+Either can ride on any of the shapes above, and both are things you cannot see
+from where you are.
+
+**`lost`** — the app navigated and the control this step is about is gone, so
+the card is now describing something that is not there. Read `{"advanced": true,
+"lost": …}` as "they pressed Next on a step about a screen that has moved on",
+not as progress: writing the next step against a page you think is still up is
+how a demo carries on over a dead app. Look before you write the next one.
+
+**`reason: "timed out, and the app window was never in front…"`** — nobody
+ignored you; the card was drawn somewhere they could not see. Tell them to click
+**Show me the app** on the row in the chat, then instruct again. A bare
+`"timed out"` is the other case, and only that one means they saw it and did
+something else.
+
+A press never reaches this side in a real window — the app handles it — so it is
+reported out of the page and tested the way a mirrored click is: both ends
+inside the control, barely any travel between them, so a press that slides off
+stays the cancelled click it looks like.
+
+## The question box
+
+The card carries a text input, and it is the **only channel in this API that the
+person starts**. Everything else answers a question of *yours*: `ask_user` waits
+for it, and the `request_*` handoffs file it and leave. None of them is a way
+for somebody to raise something you did not ask about.
+
+It is on the card rather than in the chat for two reasons, both structural. A
+tour runs in its own window, so reaching the chat means leaving the thing being
+shown. And you are parked inside this call: a chat message could not reach you
+until the tour moved on anyway, so the moment somebody most wants to ask is the
+moment the chat cannot deliver.
+
+A question typed while nothing is listening is **held in the page** and arrives
+on your next `await_user`, so it is never lost between steps.
+
+## Options
+
+- **`target`** — the control this step is about. **Optional**: omit it for a step
+  with nothing to click ("read this, then carry on"), and Next and the question
+  box are still there.
+- **`timeout_seconds`** — default 300. Each call is its own wait with its own
+  timer, so a conversation of any length costs nothing: loop, and every exchange
+  starts a fresh one.
+
+## Returns
+
+See above. **The timeout is not an error.** Somebody who did something else is
+not a failure, and noticing it is how you say something useful next.
+
+## Examples
+
+The whole loop:
+
+```python
+while True:
+    r = await api.await_user(target)
+    if notes := r.get("annotations"):
+        await fix_or_acknowledge(notes)        # before anything else
+    if r.get("reported"):
+        await api.instruct("Got that — I'll look at it.", title="noted")
+        break
+    if r.get("clicked") or r.get("advanced"):
+        break
+    if q := r.get("asked"):
+        await api.reply(answer_for(q))         # the step stays; loop and wait again
+    elif not r.get("clicked"):
+        await api.instruct("Still here whenever you are.", target)
+        break
+```
+
+`reported` is checked before the two that mean progress, and never falls through
+to the last branch — telling somebody who has just marked three broken screens
+"still here whenever you are" is the reply that makes a demo feel unread.
+
+The `asked` branch loops rather than breaking, and answers with `reply` rather
+than `instruct`. Both halves are the same point: a question is a word about the
+step somebody is on, not a reason to take it away from them. `instruct` there
+would move the ring and replace the sentence being asked about, which is the one
+thing the question was not asking for. See `reply`.
+
+## Getting it wrong
+
+**Treating a question as an interruption.** It is the tour working. Answer it,
+and go wherever it points — you are a guide, not a script.
+
+**Ignoring `{"clicked": False}`.** They did something else, or walked away. Say
+something rather than posting the next step over silence.
+
+**Calling it without an instruction up.** Next and the question box appear only
+while this is waiting, so a wait with no card is a card nobody can see arriving
+with controls nobody asked for.
+
+## See also
+
+`instruct`, `highlight`, `ask_user`, `attach_app`

package/python/xactor/man/bash.md

@@ -0,0 +1,142 @@
+# api.bash(command, timeout=120, background=False, input=None) -> dict
+<!-- group: Coding -->
+<!-- also: bash_output, bash_list, bash_kill, background -->
+
+Run a shell command. Gated. **Never raises — read `exit_code`.**
+
+The escape hatch from the sandbox. The command itself runs in an ordinary
+process with no audit hook, because the user approved *that specific command*.
+
+## Options
+
+- **`command`** — a shell command line. Pipes, redirects, `&&`, globs and
+  `$VAR` all work.
+- **`timeout`** — seconds before a foreground command is killed. Default 120.
+- **`background`** — leave the command running and return immediately. Its stdout
+  and stderr go to a log file rather than this call's pipes; use `bash_output`,
+  `bash_list`, and `bash_kill` to manage it.
+- **`input`** — `str` or `bytes` written to the command's stdin, which is then
+  closed. `api.bash("python -", input=src)` runs `src` without quoting it.
+
+**Not every command wants a shell.** For one program with fixed arguments,
+`api.run(argv)` takes them as a list and nothing is quoted or expanded. For
+PowerShell, `api.powershell(script)`: inside `bash`, `$_` and `$name` are
+bash's variables and are gone before PowerShell runs.
+
+It runs with the shell's cwd as its working directory (`api.cd` moves it), and
+with **stdin closed** unless you pass `input`. A command that waits for input
+will not hang — it gets EOF immediately.
+
+The command is started in its own process group, so a timeout or a user
+cancellation kills the whole tree rather than orphaning children. Background
+commands stay alive after the call returns, but belong to this shell: ending the
+session kills their complete process trees too, rather than leaving a dev server
+or watcher running without an agent that can reach it.
+
+## Background commands
+
+`background=True` is for a server, watcher, or other work that must survive the
+call that starts it. It returns before the command prints anything:
+
+```python
+server = await api.bash("npm run dev", background=True)
+# {"background_id": "bg1", "pid": ..., "log": ..., "running": True}
+```
+
+Read only what arrived since your previous read with `await api.bash_output("bg1")`.
+It returns `{ "output", "running", "exit_code" }`; `exit_code` is `None` while
+it is still running. `await api.bash_list()` shows every background command,
+including finished ones. `await api.bash_kill("bg1")` stops the command and
+anything it spawned, and is safe to repeat after it has already exited.
+
+Do not add `&` yourself in this mode. `background=True` is what replaces this
+call's pipes with a log file; shell backgrounding alone still lets descendants
+hold those pipes open and makes the caller wait until timeout.
+
+On Windows this uses an MSYS bash (Git for Windows): POSIX syntax, and paths
+like `/c/Users/...` and `/tmp` inside the command. Every `api.*` path accepts
+those same spellings, so a directory `pwd` printed can go straight to `api.cd`.
+Windows paths with backslashes need quoting in bash — unquoted, `cd C:\Users\x`
+arrives as `cd C:Usersx` — so prefer `C:/Users/x`. If no bash is found the
+command runs under `cmd.exe` and a warning is prepended to `stderr` — treat
+that warning as a failure, because quoting, `$VAR`, globs and `;` all mean
+something different there.
+
+## Returns
+
+Always a dict, never an exception:
+
+```python
+{"stdout": str, "stderr": str, "exit_code": int}
+```
+
+`exit_code` is the process's real exit status, **except** for two cases that
+both report `-1`:
+
+| `exit_code` | `stderr` | What happened |
+|---|---|---|
+| `0` | | Success. |
+| `> 0` | | The command failed on its own terms. |
+| `-1` | `Failed to start shell: ...` | No shell could be launched. |
+| `-1` | `Command timed out after Ns` | Killed at the timeout. **`stdout` is empty** — everything the command printed is discarded. |
+
+A user cancellation is different again: it propagates as a cancellation of the
+whole exec rather than returning.
+
+## Examples
+
+Check the exit code, always:
+
+```python
+r = await api.bash("pnpm build")
+if r["exit_code"] != 0:
+    return {"failed": True, "stderr": r["stderr"][-3000:]}
+return "build ok"
+```
+
+A long run needs both timeouts raised — this call's, and the exec's own
+`timeout_seconds` on the tool call, or the shell is killed out from under it:
+
+```python
+r = await api.bash("pnpm test", timeout=900)
+return r["stdout"][-4000:]
+```
+
+Getting raw file text the line-numbered `read_file` cannot give you:
+
+```python
+return (await api.bash("sed -n '40,60p' src/index.ts"))["stdout"]
+```
+
+## Getting it wrong
+
+**Ignoring `exit_code`.** `bash` does not raise on a failed command. A build
+that failed and a build that passed both come back as a dict; only
+`exit_code` distinguishes them.
+
+**Reading `stdout` after a timeout.** It is empty. If a command may exceed its
+timeout, tee its output to a file and read that afterwards.
+
+**Confusing the two `-1`s.** "Failed to start" and "timed out" share an exit
+code and are only distinguishable from `stderr`.
+
+**Editing files through `bash`.** `sed -i`, `>` redirects and `git checkout`
+all work, but **bash changes are not journalled**. They do not appear in
+`xylon_get_diff`, and turn-scoped revert cannot undo them. Use `write_file` and
+`edit_file` for file contents and keep `bash` for builds, tests and git.
+
+**Running an interactive command.** stdin is `/dev/null`. `git rebase -i`,
+`npm init` without `-y`, and anything that prompts will fail or do nothing.
+
+**Assuming bash on Windows.** Check `stderr` for the "no MSYS bash found"
+warning before believing an `exit_code: 0` from a command that used bash
+syntax.
+
+**Nesting another interpreter in the command.** `powershell -Command "…"`,
+`python -c "…"` and `node -e "…"` put a second language inside bash's quoting,
+inside your Python string's escaping. Use `api.powershell(script)` or
+`api.run([...], input=script)`, which have no quoting to get wrong.
+
+## See also
+
+`run`, `powershell`, `sandbox`, `permissions`, `write_file`, `edit_file`, `xylon`

package/python/xactor/man/browser-driver.md

@@ -0,0 +1,137 @@
+# Handing the browser to a smaller model
+<!-- also: driver, browser-session, driving-model -->
+<!-- group: Working on a website -->
+
+Driving a website is a long tail of small, mechanical decisions. Put them on a
+cheap model in its own session and talk to it over the relay.
+
+## Why
+
+Two costs, and they compound.
+
+**Context.** Page structure accumulates. Every `outline()`, every `search()`,
+every batch report lands in the context of whoever called it. Twenty steps into
+a console flow, a session that started out reasoning about *your* task is mostly
+full of button lists. The work the user asked for gets worse as the browsing
+gets longer.
+
+**Latency.** "Which of these two buttons did they mean" is not a hard question.
+Answering it on a frontier model, forty times, is most of the wall-clock in a
+long flow — and it is decision latency, not page latency, so none of the Layer 0
+speed work touches it.
+
+A child session on a small model absorbs both. It holds the page context; you
+hold the task.
+
+## The shape
+
+```python
+# 1. A child session, on a small model, in this repo.
+child = await api.agent(
+    prompt=(
+        "You are driving a browser for me. Use api.use_widget / api.drive to "
+        "reach a site, then api.outline / api.search / api.find to locate things "
+        "and the action verbs to act. Load whole chains and await api.drain(); "
+        "do not step one action at a time, and do not take screenshots. "
+        "Relay me a short summary after each objective — what you did and what "
+        "the page says now. Ask me before anything destructive or paid."
+    ),
+    model="claude-haiku-4-5",   # or any small tier api.man('sessions') lists
+)
+node = child["session_id"]
+
+# 2. Open a channel and give it work.
+await api.relay_connect(node)
+await api.relay_send(node, "Create a Vercel token named ci-deploy, no expiry. "
+                           "Tell me the token's name and expiry, never its value.")
+
+# 3. Get on with something else, then read what came back.
+inbox = await api.relay_inbox()
+```
+
+`agent` takes any model your providers expose — `api.man('sessions')`
+covers the lifecycle, and the model list is whatever is configured. Haiku is the
+obvious Claude choice; a small GPT tier works the same way. The point is the
+tier, not the vendor.
+
+## Where the boundary goes
+
+Give the driver the **objective**, not the steps:
+
+> "Create a Vercel token named ci-deploy with no expiry."
+
+not
+
+> "Click Settings, then Tokens, then the Create button, then…"
+
+The second one is you doing the driving through a slower channel. If you already
+know the exact steps, that is a widget — write one (`writing-a-widget`) and stop
+paying a model to replay it.
+
+Ask for **findings**, not transcripts. A driver that relays every batch report
+has moved the context problem, not solved it. "Token created, expires never,
+value extracted to `VERCEL_TOKEN`" is the whole useful content of forty actions.
+
+## Choosing the tool
+
+| | |
+|---|---|
+| `delegate(prompt, model)` | **One question, one answer.** Blocks, returns a string, no session, no relay. Right for "go read this page and tell me the price". Wrong for anything with state. |
+| `agent(prompt, wait=False, model=...)` | **A driver that lives.** Its own session, its own browser, its own context. Relay to it as the task unfolds. This is the pattern here. |
+| `session_fork` | An independent clone. Use when the child should not share your repo state. |
+
+`session_join` waits for a child's current turn if you would rather block than
+poll the inbox.
+
+## Keep it out of *its* loop too
+
+Everything in `widget-model` about efficient navigation applies to the driver,
+and matters more there because it is making more of the decisions. The prompt
+above says the important parts explicitly, and it is worth keeping them:
+
+- **load chains, `drain()` once** — not one awaited action at a time
+- **`outline()` before anything**, to orient cheaply
+- **no screenshots** — a picture costs a round trip through the model, which is
+  the expensive kind; `right_of="Name"` costs a round trip through the page
+- **scope every lookup** with `under=`
+
+A small model told to "look at the page and decide" will screenshot. Tell it not
+to.
+
+## Permissions still belong to the user
+
+A child session is not a way around a prompt. `use_widget`, `drive`,
+`browser_exec` and `browser_screenshot` are gated in the child exactly as they
+are in you, and the card names the delegate that asked. That is deliberate: the
+user is approving *the driver's* action, and should be able to see it was the
+driver.
+
+A driver running unattended needs `session_harness` and explicit grants — see
+`harness`. It will never be prompted, so anything not granted is refused with a
+message it can read.
+
+## Getting it wrong
+
+**Relaying every step.** You have paid for a second session and kept all the
+context anyway. Ask for outcomes.
+
+**Sending the steps instead of the objective.** If you know the steps, the answer
+is a widget, not a driver.
+
+**Letting it screenshot.** It will if you do not say otherwise, and it is the
+single most expensive habit available to it.
+
+**Expecting a secret back.** Use `extract_secret`; the value is written to the
+workspace's `.env` file (not to any running process's environment) and never
+crosses a model boundary in either direction. A shell does not see it as
+`$NAME` until it loads the file: `api.bash('set -a; . ./.env; set +a; curl ... -H "Authorization: Bearer $NAME"')`
+tests a credential without printing it.
+
+**A driver with no widget on a site you drive often.** The driver rediscovers the
+site every session. Have it write the widget once and use that instead.
+
+## See also
+
+`sessions`, `agent`, `relay`, `agent`,
+`agent-vs-fork`, `widget-model`, `writing-a-widget`, `finding`,
+`harness`, `permissions`

package/python/xactor/man/browser_activity.md

@@ -0,0 +1,53 @@
+# What the person did in your tabs
+<!-- also: user-activity, browser-notice, typed, clicked -->
+<!-- group: Working on a website -->
+
+You are told when the person works in one of your browser tabs. There is no
+call to make: it arrives on its own, once, at the end of your next tool result,
+or ahead of your next prompt if you were idle. It does not wake you.
+
+```
+──
+Browser: the person worked in your tabs.
+  tab "Stripe – API keys":
+    clicked "Create secret key"
+    typed into "Key name": "staging"
+  tab "Sign in":
+    typed into "Password" (hidden field, text not shown)
+Read the page again before acting on it. Nothing is waiting on you …
+```
+
+## What is reported
+
+- **Clicks** on buttons, links, tabs and menu items, by their label.
+- **Typing**, as each field's final value. Typing in one field, however long, is
+  one line.
+- **Choices** in selects, checkboxes and radio buttons.
+- **Navigation** the person caused: a link followed, an address typed.
+- **Tabs** the person switched to or closed.
+
+Your own actions are never reported back to you.
+
+## What stays hidden
+
+Text in a field the site hides on screen: a password field, or one styled to
+mask its text. Also fields the site marks as a card number, card code, one-time
+code or password. The decision is made when the field is first focused, so a
+"show password" button does not reveal it later. You are told only that
+something was typed there.
+
+Fields inside another site's embedded frame (a payment form, for example) are
+not watched at all.
+
+## Getting it wrong
+
+**Treating it as an instruction.** The person clicking "Delete" is not them
+asking you to delete something. It tells you the page has changed. Read it
+again before your next action on it.
+
+**Trusting the page you read earlier.** If anything is listed for a tab, what
+you saw on it before is out of date.
+
+## See also
+
+`drive`, `browser_tabs`, `outline`

package/python/xactor/man/browser_attach.md

@@ -0,0 +1,84 @@
+# api.browser_attach(target_session_id, timeout=None) -> dict
+<!-- also: attach, borrow-browser, browser-ownership -->
+<!-- group: Working on a website -->
+
+Borrow another session's browser, waiting if someone else is using it.
+
+Every browser belongs to the session that opened it. No other session can reach
+it by accident — that is what stops two sessions driving one tab and navigating
+it out from under each other. This call is the deliberate exception.
+
+## Why ownership exists
+
+Concurrent sessions used to share whatever tab was open. Nothing errored: each
+one attached to a page it did not open, and each reported confident conclusions
+about a site it was not actually looking at. A session mapping Supabase decided
+the site was behind a login wall while reading another session's Netlify tab.
+
+So a tab now has an owner, and `api.drive` / `api.use_widget` will open a new
+page rather than adopt a claimed one. If everything open is claimed and you have
+no browser yourself, you get an error telling you so — not somebody else's page.
+
+## Options
+
+- **`target_session_id`** — the session whose browser you want. Not a
+  dispatcher id, and not your own session.
+- **`timeout`** — milliseconds to wait for it. Default 120,000.
+
+## Returns
+
+```python
+{"status": "attached", "dispatcher_id": str, "owner": str,
+ "url": str, "title": str, "shell_status": str}
+```
+
+If the wait runs out you get `{"error": ..., "occupied": True}` instead, naming
+the holder and how long they have had it. **It does not raise**, so check for
+`occupied` rather than assuming you have the browser.
+
+While you hold it, your `browser_exec` runs against the borrowed page.
+
+## Examples
+
+Look at what a driver child ended up on:
+
+```python
+r = await api.browser_attach(child_session_id)
+if r.get("occupied"):
+    return f"Could not borrow it: {r['error']}"
+try:
+    out = await api.browser_exec(None, "print(await api.outline())")
+    print(out["output"])
+finally:
+    await api.browser_detach(child_session_id)
+```
+
+Wait a long time for a slow flow to finish, rather than failing fast:
+
+```python
+r = await api.browser_attach("session-42", timeout=600_000)
+```
+
+## Getting it wrong
+
+**Forgetting `browser_detach`.** The lease is held until you release it. The
+owner and every other waiter is blocked the whole time. Use `try/finally`.
+
+**Treating the result as success.** A timed-out attach returns a dict with
+`occupied: True`. Running `browser_exec` after one drives *your own* browser, or
+fails — not the one you meant to borrow.
+
+**Attaching to get around ownership.** If you just need a page, open your own
+with `api.drive` or `api.use_widget`. Borrowing is for looking at a browser that
+is already somewhere you need it to be.
+
+**Passing a dispatcher id.** It takes a session id (`'session-42'`). The
+dispatcher is derived from it.
+
+**Expecting it to release when your turn ends.** It does not. A session that
+attaches and stops without detaching leaves the browser held.
+
+## See also
+
+`browser_detach`, `browser_exec`, `drive`, `use_widget`, `sessions`,
+`browser-driver`, `browser_plumbing`

package/python/xactor/man/browser_close_tab.md

@@ -0,0 +1,50 @@
+# api.browser_close_tab(tab_id) -> dict
+<!-- also: close-tab -->
+<!-- group: Working on a website -->
+
+Close one of your session's tabs.
+
+Closing the tab you were driving moves you to another of your tabs when there is
+one, so you are never left driving a dead page.
+
+## Options
+
+- **`tab_id`** — from `api.browser_tabs()`.
+
+## Returns
+
+```python
+{"status": "closed", "tab_id": str,
+ "focused_tab_id": str | None, "remaining": int}
+```
+
+`focused_tab_id` is what you are driving now. `None` with `remaining: 0` means
+your window is empty — the next `api.drive` or `api.use_widget` starts a new
+one.
+
+## Examples
+
+Tidy up everything you opened for a job:
+
+```python
+for t in (await api.browser_tabs())["tabs"]:
+    if t["url"].startswith("https://docs."):
+        await api.browser_close_tab(t["tab_id"])
+```
+
+## Getting it wrong
+
+**Closing a tab the user opened themselves.** Only tabs in your window are
+addressable, so you cannot — but do not close tabs you did not open *for this
+task* either, if the session has been doing other work.
+
+**Closing the last tab and then calling `browser_exec`.** With nothing left,
+there is no page to run against. Check `remaining`.
+
+**Treating it as a way to stop a flow.** A half-finished action on a console is
+half-finished whether or not you close the tab. Clean up what you created on the
+site first.
+
+## See also
+
+`browser_tabs`, `browser_open_tab`, `browser_focus_tab`, `browser_exec`