cdp-toolkit 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -5,6 +5,443 @@ All notable changes to cdp-toolkit are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.8.0] - 2026-08-09
+
+Two tracks land together, merged onto one integration branch. Track S closes the
+gap 1.7.0's takeover mode opened: an agent can now claim a human's open tab, but
+nothing detected the human was still there, and reap could destroy an
+agent-abandoned tab the moment it went idle. Track P is four groups of input
+parity chrome-devtools-mcp already had and this toolkit didn't: a wheel/scroll
+tool, a raw mouse primitive, real HTML5 drag-and-drop, and navigation
+history/downloads/permissions. Tool count moves 41 → 45. Every new
+input-dispatching path (Track P) was wired through Track S's dispatch log as
+part of the merge, not left as a follow-up — see "Changed" below.
+
+### Added
+
+- **An activity beacon: `claim_page` and `list_leases` now know when a human is
+  already using a tab (`src/activity.ts`).** A tiny in-page script records the
+  timestamp of the last `pointerdown`/`mousedown`/`keydown`/`wheel`/`touchstart`,
+  installed at claim time on both `claim_page` modes and
+  `new_page{claim:true}`. On Chrome, `Page.addScriptToEvaluateOnNewDocument`
+  alone does **not** survive navigation under this toolkit's per-call connection
+  lifetime — the registration dies with the connection that made it, which is
+  every tool call, a fact verified against a live browser before anything was
+  built on it (`addScriptToEvaluateOnNewDocument` → new connection → navigate →
+  `null`). So the CDP driver now holds one connection open per beaconed tab
+  purely to keep the registration alive across navigations, bounded at 32
+  tabs with oldest-first eviction; an evicted tab still answers for input on
+  its current document, only the next navigation's re-arm is lost. Firefox
+  needs none of this — its BiDi session lives for the whole process, so a
+  `script.addPreloadScript` registration survives navigation for free, and was
+  implemented and live-verified rather than left absent, since the spec's
+  Firefox carve-out only applied if the plumbing was intractable and it wasn't.
+  CDP-dispatched input is `isTrusted:true` too, so the beacon alone cannot tell
+  a human click from the toolkit's own: every input-dispatching call writes to
+  an in-process dispatch log, and a beacon timestamp counts as human only when
+  it postdates this server's last dispatch on that tab by more than 1500ms.
+  `claim_page`/`list_leases` surface it as `humanActiveMs` — milliseconds since
+  input this server did not dispatch. **`null`/absent means NO DATA, never "no
+  human"**: a fresh tab, a tab whose every input was this server's own, and a
+  backend that cannot answer at all are all indistinguishable from each other
+  and from silence. A `claim_page` takeover of a tab a human used within the
+  last 30 seconds additionally carries a `contention` warning string, and **the
+  claim is never refused for it** — taking over a person's tab is what
+  takeover mode is for, so the warning informs a caller who already holds the
+  lease, it does not gate anything. Known blind spots, stated rather than
+  designed away: input inside a cross-origin iframe is invisible to the
+  beacon, and a *second* MCP server process's dispatches read as human to this
+  one, since dispatch-log correlation is scoped to this process.
+
+- **Split reap horizon: reclaimable and destroyed are different moments, now
+  separated by `CDP_REAP_GRACE_MS`.** Before this release, `list_pages` and
+  `list_leases` closed an agent's tab the instant its lease read `expired`,
+  which is also the instant another agent becomes *entitled* to take it —
+  fine for handing the lease to someone else, destructive when applied to the
+  tab itself. An agent 20 minutes into a build between tool calls does not
+  expect to come back to a destroyed tab just because it could, in principle,
+  have been reclaimed. `staleAgentTabs` (`src/reap.ts`) stays a pure function
+  but now takes `now`/`reapGraceMs`: an `expired` lease qualifies for the
+  destructive close only once `now - lastUsedAt > ttlMs + reapGraceMs`.
+  `CDP_REAP_GRACE_MS` defaults to `2700000` (45 minutes), for a 60-minute total
+  fuse after last use. Lease *reclaimability* — `list_leases`' `stale` field —
+  is byte-for-byte unchanged at `ttlMs`; only the destructive close moved.
+  `dead-pid` is unaffected by grace and reaps immediately, because that
+  process is never coming back and there is nothing to wait for.
+
+- **Renderer ping and lease observability on `list_pages`/`list_leases`.**
+  `list_pages` gains `probe?: boolean` (default false, byte-identical shape
+  when omitted): one bounded (500ms) `Runtime.evaluate` per page-type target,
+  run concurrently so one wedged tab cannot stall the rest of the listing
+  beyond its own budget. Adds `responsive: boolean` (false on a timeout, a
+  page-side exception, or an unreachable target — never an error for the
+  whole call) and, where the same round trip finds human-attributed input,
+  `humanActiveMs`, reusing the beacon's own discrimination rule rather than a
+  second implementation of it. Separately and unconditional on `probe`,
+  `list_leases` rows gain computed `idleMs` (now−lastUsedAt) and `expiresAt`
+  (lastUsedAt+ttlMs, the same value `claim_page` already returns under that
+  name), and `list_pages` entries for a tab under an active, readable lease of
+  the driver's own backend gain `lease: {label,pid,idleMs,expiresAt,stale}`.
+  Both are computed fresh in the tool layer on every call, never stored.
+
+- **`scroll`, a new wheel-dispatch tool, on both backends.** Anchor at
+  `uid`/`selector`/`x`+`y` (element anchors are scrolled into view first, same
+  as `click`), or the viewport center if all three are omitted; at least one
+  of `deltaX`/`deltaY` is required, positive `deltaY` scrolling down and
+  positive `deltaX` scrolling right (wheel convention). Chrome dispatches
+  `Input.dispatchMouseEvent{type:"mouseWheel"}`; Firefox dispatches WebDriver
+  BiDi's `wheel` input source — both live-verified against a real browser, not
+  left on "it typechecks." A real bug surfaced along the way: Chrome
+  smooth-scrolls a wheel dispatch, so the command's ack resolves once the
+  event is *queued*, not once the resulting scroll has *settled*, and a
+  caller reading `scrollTop` immediately after could see the pre-scroll
+  value. Fixed with a capture-phase `scroll` listener armed before dispatch
+  (window-level, since `scroll` doesn't bubble but a capture-phase listener on
+  `window` still sees it), debounced 60ms with a 500ms hard cap rather than a
+  blind sleep sized wrong for both large and small deltas.
+
+- **`dispatch_mouse`, the raw move/down/up primitive, Chrome-only.** Dispatch
+  exactly one `move`/`down`/`up` mouse event at absolute viewport coordinates
+  (`x`/`y` required on every call — CDP has no notion of a current pointer
+  position to default from); compose your own move/down/move/up sequences for
+  anything a physical mouse can do that `click`/`drag`'s fixed sequences
+  can't — canvas drag-painting, marquee/rubber-band selection, a custom
+  hit-testing widget. Takes the same `button`/`clickCount`/`modifiers` as
+  `click`. Lives outside the Driver abstraction by design, alongside
+  `heap.ts`/`screencast.ts`'s other chrome-only-tool modules, but is
+  lease-gated through the exact same choke point every other interaction tool
+  uses. Chrome-only, capability `input.raw`: absent from `tools/list` under
+  `--browser firefox`, never present-and-throwing.
+
+- **`click` gains `modifiers` and `clickCount:3`.** `modifiers` (Alt/Control/
+  Meta/Shift, CDP bits 1/2/4/8) is held for both press and release, e.g.
+  `["Shift"]` for a shift-click; `clickCount:3` triple-clicks, selecting a
+  paragraph/line in most editors. `modifiers` is a **Chrome-only parameter on
+  an otherwise-universal tool**: a non-empty array throws a clear error under
+  `--browser firefox` rather than being silently dropped or ignored — a
+  documented param-level gap under ADR-001, not a missing tool.
+
+- **Real HTML5 drag-and-drop (`drag mode:"html5"`), plus `steps`, `to:{x,y}`,
+  and `by:{dx,dy}` on the existing mouse-mode drag.** The spec's premise —
+  that synthetic mouse events cannot drive HTML5 drag-and-drop at all — is
+  **false**, measured against Chrome 151: `mode:"mouse"` (the default) does
+  start a real drag and can fire `dragstart`/`dragover`/`drop`. The actual gap
+  is that *which* `dragover` events reach the page depends on where the
+  interpolated pointer path happens to land, because mouse mode's drag
+  events follow that path rather than being dispatched at fixed points. At
+  the default `steps:2`, a drop zone written the standard way (`preventDefault`
+  only inside `dragover`, the HTML spec's own pattern) sees **zero** `dragover`
+  events and refuses the drop outright — a coin flip decided by geometry, not
+  a reliable "it doesn't work." `mode:"html5"` closes that gap deterministically:
+  `Input.setInterceptDrags(true)` arms interception, the mouse press/move
+  sequence runs, `Input.dragIntercepted` hands back the page's own `dragstart`
+  DragData, and the toolkit replays it as `dragEnter`→`dragOver`→`drop` exactly
+  at the destination — path-independent, and interception is always disabled
+  in a `finally`. Missing the intercepted event within 5 seconds (e.g. the
+  source isn't `draggable="true"`) is an actionable error, never a silent
+  no-op. `mode:"html5"` is Chrome-only (capability `input.html5Drag`, absent
+  from `REQUIRED_CAPABILITIES` so `drag` itself stays available on both
+  backends) and is rejected with a clear error under Firefox rather than
+  silently downgrading to mouse mode, which would report a drop that never
+  happened. `steps` (default 2, matching the exact pre-1.8.0 dispatch) sets
+  the interpolated-move count for mouse mode; `to` now also accepts an
+  absolute `{x,y}` alongside `uid`/`selector`, and a new top-level `by:{dx,dy}`
+  offsets from the source point instead (sliders, map panning, resize
+  handles) — exactly one of `to`/`by` is required, refused rather than
+  resolved by precedence when both or neither are given.
+
+- **`navigate_page` gains `history: "back"|"forward"`, on both backends.**
+  Traverses this tab's session history like the browser's own Back/Forward
+  buttons: Chrome via `Page.getNavigationHistory` + `Page.navigateToHistoryEntry`,
+  Firefox via BiDi's `browsingContext.traverseHistory{delta:±1}`. Mutually
+  exclusive with `url`/`reload` — passing two of the three is refused by name,
+  never resolved by precedence. Going back from the first entry, or forward
+  from the last, is an **error naming the direction**, never a silent
+  no-op that navigates nowhere; both backends were made to raise the same
+  sentence (Firefox's own error never names a direction, so the BiDi driver
+  rewraps it). Waits for the same load milestone as an ordinary navigation.
+
+- **`wait_for_download`, capture a real file download as a file on disk,
+  Chrome-only and MCP-server-only.** Returns `{path,suggestedFilename,bytes,
+  url,target}`, renaming Chrome's internal guid to the page's own filename
+  (collision-suffixed: `report.csv`, `report-1.csv`, ...). Two premises in the
+  original design were probed against a real browser before anything was
+  built, and both were **false**: `Browser.setDownloadBehavior` does **not**
+  persist past the arming client's disconnect (measured: an armed-then-closed
+  connection followed by a click landed zero files, no events, anywhere — the
+  download is *denied*, not merely misdirected), and the toolkit's per-call
+  CDP lifetime means every tool call is exactly such a disconnect. The fix is
+  `src/tools/browser-session.ts`: one lazily-opened, module-scoped connection
+  to the browser endpoint, held open for the process's life, arming download
+  capture once and keeping a ring buffer of completions — opened only when
+  `wait_for_download` or `grant_permissions` is first called, so a session
+  that never downloads pays nothing. **Ordering rule, not optional:** call
+  `wait_for_download{arm:true}` *before* the click that starts the download
+  (it arms and returns immediately: `{armed:true,downloadPath,pending}`), then
+  click, then call `wait_for_download` again to collect the finished file —
+  arming late loses the download with no file anywhere to recover it from.
+  **Browser-global side effect:** while armed, *every* download in the
+  browser, all tabs and origins, is redirected into the toolkit's downloads
+  directory for as long as the server runs. **MCP-server only, not a
+  preference:** the arm lives on a connection this server process holds open;
+  under the one-shot CLI that connection dies with the process before a
+  download could ever complete, so the tool needs the long-lived server the
+  same way `performance_start_trace`/`start_screen_recording` already do.
+  Chrome-only, capability `browser.downloads`: WebDriver BiDi has no command
+  to redirect a download to a chosen directory.
+
+- **`grant_permissions`, pre-answer permission prompts for an origin,
+  Chrome-only and MCP-server-only.** `permissions: string[]` takes CDP
+  PermissionType values (`geolocation`, `notifications`, `clipboardReadWrite`,
+  `camera`, `microphone`, `midi`, ...; an unknown name is refused by Chrome
+  with the bad value in the message), keyed by **origin**, not tab — every
+  tab on that origin is affected, including ones opened later. `reset:true`
+  clears this server's previous grants first, or instead when no permissions
+  are given; CDP's reset is not itself origin-scoped, so it clears every
+  origin at once. The same probe that falsified `wait_for_download`'s
+  persistence assumption was run against `Browser.grantPermissions` on
+  spec, since the same per-connection-state trap applies here too, and it
+  sprang: a grant also does **not** survive the granting client's disconnect.
+  Shares `browser-session.ts`'s standing connection with `wait_for_download`
+  for exactly that reason. Chrome-only, capability `browser.permissions`:
+  absent from `tools/list` under Firefox, never present-and-throwing.
+
+### Changed (behavior, no flag)
+
+- **Every input-dispatching path, old and new, now writes through one choke
+  point, closing a real bug the individual branches could not see.** Track P
+  was built against pre-1.8.0 main, before Track S's dispatch log existed, so
+  its `scroll` and html5-drag paths sent `Input.*` straight down the
+  connection. Merged as-is, this compiles, typechecks, and passes both
+  branches' full test suites while the activity beacon reports the toolkit's
+  own scroll as a human using the tab — an agent warned about contention with
+  itself, the exact failure the beacon exists to prevent, invisible to either
+  branch's own tests because neither branch could see the other's code.
+  `dispatch_mouse` lives outside the Driver abstraction and has no
+  `dispatchInput` to call, so the write moved to a new shared function,
+  `sendInput(conn, backend, targetId, method, params)` in `src/activity.ts`;
+  `CdpPageDriver.dispatchInput` now delegates to it and `dispatch-mouse.ts`
+  calls it directly. `Input.setInterceptDrags` (html5 drag's arm and its
+  `finally`) is sent but deliberately **not** recorded: it synthesizes no
+  page input, and logging it would suppress a real human input landing in the
+  same 1500ms window — classified by denylist, so an `Input.*` command nobody
+  thought to classify defaults to being logged, because over-warning is
+  recoverable and silent misattribution is the bug this feature exists to
+  avoid. Firefox needed no code change: Track P built its BiDi scroll and drag
+  on `performActions`, which already called `recordDispatch`, so it inherited
+  the log for free — the whole argument for having a choke point in the first
+  place. The invariant — nothing in `src/` sends `Input.*` except through
+  `sendInput` — is grep-verified post-merge and is now also a test
+  (`test/input-dispatch-wiring.test.ts`), mutation-checked by reverting
+  `scroll` to a raw send and confirming the test names the exact line and the
+  live smoke reproduces the bug (`humanActiveMs=202` on the toolkit's own
+  scroll, instead of `undefined`).
+
+### Residuals
+
+- **A stale claim in `drag`'s own manifest description was caught and fixed
+  during integration, not by a fresh reader later.** An earlier pass on the
+  top-level `drag` description already stated the measured mouse-vs-html5
+  finding, but the `mode` property's own enum description still read "does
+  nothing on HTML5 draggable elements" — the exact folklore the rest of this
+  release measured false. Corrected to match; no test pinned the stale
+  string.
+- **Second-MCP-server blind spot, stated plainly.** Two MCP server processes
+  driving the same browser cannot see each other's dispatch logs, so one
+  server's tool calls read as human activity to the other. Accepted: the
+  discrimination rule is honest about what it can and cannot see, and the
+  alternative (a shared dispatch log across processes) is a much larger
+  feature for a scenario this toolkit does not otherwise support (see
+  "Parallel tabs" — one writer per flow).
+- **Cross-origin iframe input is invisible to the beacon,** since the
+  listener is installed on the top document only. Under-warning here is the
+  same accepted direction as the denylist above: a missed human input reads
+  as agent-only, never the reverse.
+- **`dispatch_mouse`'s `modifiers` and `click`'s `modifiers` are two separate
+  parameters that happen to share an enum,** not one modifier system: each
+  tool validates and documents its own Firefox behavior independently.
+- **Firefox's BiDi `scroll` path shipped once and was verified twice, in two
+  different seats.** It typechecked and passed unit tests against the real
+  BiDi capability set when Track P landed, but no Firefox was available to
+  that seat to run it live; the integration seat had one, ran it, and it
+  passed unmodified — the implementation was correct the first time, only the
+  live evidence was missing. Recorded here so "typechecks" is never mistaken
+  for "verified" on the next capability that ships without a live check.
+
+### Notes
+
+- Tool count is now 45 (29 parity + 16 superset: `performance_trace`, the
+  cookie group, the network-mocking group, the lease group, the
+  screen-recording pair, `scroll`, `dispatch_mouse`, `wait_for_download`, and
+  `grant_permissions`); 34 under Firefox, which lacks the eleven
+  capability-gated tools — the pre-1.8.0 eight (tracing, heap-snapshot,
+  Lighthouse, screen-recording) plus `dispatch_mouse`, `wait_for_download`,
+  and `grant_permissions`. `scroll` and the extended `navigate_page`/`click`/
+  `drag` params ship on both backends; only `click`'s `modifiers` and `drag`'s
+  `mode:"html5"` stay Chrome-only, and only at the parameter level — the
+  tools themselves are universal.
+- Two new live-smoke scripts, `bun run staleness:smoke` and `bun run
+  input:smoke`, are each a single process talking to a single browser:
+  `CDP_BASE` is a module-level constant captured at import time, so one
+  process cannot address two browsers on two ports. Each is therefore
+  env-driven — `staleness:smoke` honors `STALENESS_SMOKE_PORT` (default
+  9501), `input:smoke` honors `CDP_SMOKE_PORT` (default 9513) — so the two
+  can run against separate scratch Chromes without colliding.
+
+## [1.7.0] - 2026-08-09
+
+Four things land on top of 1.2's opt-in lease model, all under one new switch
+plus one default that moves without it. `CDP_REQUIRE_LEASE` turns leasing from
+optional into mandatory for a long-lived MCP server: every call auto-acquires
+the tab it touches instead of driving it lease-free. `release_page` now closes
+a tab this toolkit opened, the one behavior a caller sees without opting into
+anything. Reap closes tabs an agent abandoned instead of leaking them forever.
+And `claim_page` gained a `target` mode so an agent can take over a tab a human
+already has open, not just claim one it created itself.
+
+### Added
+
+- **`CDP_REQUIRE_LEASE`, a switch that makes holding a lease mandatory instead
+  of optional, and the `auto` tier that makes it livable.** Off by default, so
+  a 1.6.0 consumer is unaffected. On, in a long-lived MCP server process only:
+  `assertLeaseOk` now *acquires* a lease on an unheld tab instead of waving the
+  call through, which is what makes "you cannot drive a tab you do not hold"
+  actually true rather than aspirational. That acquired lease is marked
+  `auto: true` on the `LeaseRecord` (absent, and therefore `false`, on every
+  record a pre-1.7.0 toolkit ever wrote, so an upgrade never downgrades a held
+  lease's protection), and an auto lease is owned by a *process*: any later
+  call from the same pid passes with no token, while a lease taken explicitly
+  via `claim_page` or `new_page{claim:true}` still demands its token even from
+  that same process. That two-tier split is what lets an ordinary tool call
+  keep working with zero protocol changes while still giving one subagent a
+  way to fence off a tab from its siblings, which share its pid. `new_page`
+  auto-claims the tab it just created under strict mode, even without
+  `claim:true`, because a tab nobody holds the instant it exists is a tab the
+  very next call would have to auto-acquire anyway; `claim:true` still yields
+  the stronger, explicit tier. **Strict mode is MCP-only, deliberately and
+  unconditionally**, not just by convention: `requireLease()` reads a
+  per-process flag that only `mcp.ts` sets at startup, so `CDP_REQUIRE_LEASE=1`
+  in a CLI invocation's environment is inert no matter what. A CLI call is one
+  process per invocation, so a lease it auto-acquired would be reclaimable by
+  the dead-pid rule the instant that process exited, and "a lease that is
+  reclaimable on arrival" is worse protection than none; the sharper danger is
+  reap, which would then read that instantly-dead-pid record as an abandoned
+  agent tab and could close it on the very next `list_pages` call.
+
+- **`release_page{target}`, the counterpart an auto-acquired lease needs**,
+  because the gate mints those without ever handing the caller a token to give
+  back with `lease`. `target` takes the same selector grammar as everywhere
+  else and resolves through `resolvePage`, which is itself the authorization:
+  it runs `assertLeaseOk`, so a tab another live process holds is refused
+  there and, under strict mode, an unheld tab is acquired on the way in, which
+  means the caller genuinely holds it by the time it is released. `lease` and
+  `target` are mutually exclusive and exactly one is required.
+
+- **Reap: `list_pages` and `list_leases` close tabs an agent abandoned,
+  instead of leaking them forever.** `release_page` only closes a tab an agent
+  gives back, and an agent that crashes, is killed, or just stops calling
+  never gives anything back; a timeout is a more likely end for an agent than
+  a clean shutdown. Rather than a background sweeper (a second lifetime to
+  reason about, and a process that has to be running), reap runs on read: the
+  two list tools already hold the browser's live target list and the lease
+  directory in hand at that moment, so checking costs one extra pass over data
+  already fetched. The selection itself, `staleAgentTabs` in the new
+  `src/reap.ts`, is a pure function so the four conditions that gate a close
+  can be tested exhaustively with no browser and no filesystem, which matters
+  because every mistake in this code closes a tab someone wanted: (1) the
+  lease row is for this backend and actually readable — an `unreadable` row is
+  never a candidate, because a guess in the destructive direction is the one
+  guess that cannot be undone; (2) it is stale for `dead-pid` or `expired`,
+  never `target-gone` (nothing to close) or a healthy lease; (3) the target is
+  still genuinely open, per the live page listing; and (4), the load-bearing
+  one, **the toolkit both opened the tab AND leased it** — an origin record by
+  itself is not enough. An agent-created tab that never went through
+  `claim_page`/`new_page{claim:true}` and was never auto-leased has no lease
+  row at all, and that is exactly what `new_page` produces for a caller who
+  never touches leases; reaping those would be a data-loss bug wearing a
+  cleanup's clothes, not a cleanup. Closed tabs are reported in an additive
+  `reaped` array (`{targetId, label, reason}`) present only when something was
+  actually closed, so the common-case response shape is byte-identical to
+  1.6.0; a close that fails is not reported and the lease is left in place, so
+  the next read tries again rather than lying about what is still open.
+  Strict-mode gated, for the same MCP-only reason as auto-acquire: a CLI user
+  running `list_pages` twice would otherwise watch the second run close the
+  tabs the first run's now-dead process just leased.
+
+- **`claim_page{target}`, a takeover path for a tab that is already open.**
+  With neither `target` nor `targetId`, `claim_page` still opens a fresh tab,
+  which was its only mode before; `targetId` still claims an exact existing
+  target id, kept for back-compat. Neither of those covers "work in the tab I
+  already have open" when the caller does not have that tab's id to hand,
+  which is the ordinary shape of a human asking an agent to continue in a tab
+  that is sitting right in front of them. `target` takes the toolkit's whole
+  selector grammar (`active | index:N | url:<substr> | title:<substr> |
+  <targetId>`) and resolves it against the live page list only: an unmatched
+  selector is an error, never a silently substituted new tab, because "the tab
+  I asked for is not there" and "here is an empty one instead" are answers a
+  caller has to be able to tell apart. The result gained `opened: boolean`,
+  true only when this call actually created the tab, which is the same
+  distinction the creation ledger records and is what keeps close-on-release
+  safe through this new path: a tab taken over this way has no creation
+  record, so `release_page` releases it and leaves it open. **Resolution here
+  is deliberately gate-free** — it goes through `pickPage`, not `resolvePage`
+  — because under strict mode `resolvePage` would auto-acquire a lease on an
+  unheld tab on the way in, and the explicit claim right behind it would then
+  collide with the lease it had just minted for itself. The protection this
+  skips is not lost, only moved one layer down: `claimLease`'s own conflict
+  check still refuses a tab any live process holds, auto-acquired or explicit.
+  **There is deliberately no force or steal option.** A tab another live agent
+  holds is refused with the same conflict error as ever; the tab this feature
+  exists to take over is a human's, and a human's tab carries no lease at all.
+
+### Changed (behavior, no flag)
+
+- **`release_page` now closes a tab this toolkit opened, by default.** This is
+  the one thing a 1.6.0 caller sees without setting `CDP_REQUIRE_LEASE`:
+  previously `release_page` only ever gave the lease back and never touched
+  the tab. The close is scoped by the creation ledger from `origins.ts`, which
+  answers "did this toolkit open it" independently of the lease, and only
+  independently of the lease could it answer that at release time: a tab this
+  toolkit opened for an agent is closed, a tab a human already had open and an
+  agent merely claimed is released and left exactly alone, and `close: false`
+  opts out of a close per call while `close: true` forces one either way. A
+  release that did not actually happen — already released, reclaimed, or
+  expired — never closes anything, because by then the tab may belong to
+  another agent entirely; that is the one rule here that is a safety property
+  rather than a convenience, not a default that can be overridden.
+
+### Residuals
+
+Stated plainly rather than designed away, most inherited from strict mode's
+design doc, one new to the takeover path:
+
+- **Auto leases do not isolate subagents sharing one MCP server process.** All
+  of a session's subagents share one pid, so they pass each other's auto
+  leases freely. The escape hatch is an explicit `claim_page`, which demands
+  its token even same-process; that is the accepted cost of keeping the
+  ordinary path ergonomic.
+- **Reap closes an idle-but-alive agent's tab after `ttlMs` elapses.**
+  `expired` means reclaimable, so another agent could already have taken the
+  tab by the time reap runs; closing it is consistent with that, but it is
+  still a close the original agent did not ask for. Tunable via
+  `CDP_LEASE_TTL_MS` (default 15 minutes).
+- **A read can have a side effect.** `list_pages` and `list_leases` can close
+  tabs under strict mode. Mitigated only by reporting every close in `reaped`.
+- **`release_page{target}` under strict mode, on an unleased agent tab,**
+  auto-acquires it and then closes it in the same call, closing a tab the
+  caller itself never drove a single command against. Accepted because under
+  strict mode an unleased agent tab means nobody is actually driving it.
+- **Auto-acquire can mint a lease on a non-page target.** `pickPage`'s bare-id
+  branch searches the full `all:true` listing, so an exact id for a worker or
+  an iframe still resolves and gets leased. Harmless, since a lease is just a
+  file, but it will show up as a row in `list_leases`.
+
+### Notes
+
+- Tool count is unchanged at 41 (29 parity + 12 superset); 33 under Firefox.
+  `claim_page`, `release_page`, and `list_leases` gain arguments and result
+  fields, none of them removed or renamed.
+
 ## [1.6.0] - 2026-08-09
 
 This release skips 1.5.0 (reserved for in-flight work on another branch).
@@ -315,5 +752,7 @@ First public release.
 - Zero runtime dependencies in the CDP/CLI layer (Node's global `WebSocket` + `fetch`). The MCP server adds only `@modelcontextprotocol/sdk`; `lighthouse_audit` is the sole non-CDP tool and shells out to `npx lighthouse`.
 - Runtime: Bun ≥ 1.1 (recommended) or Node ≥ 22 (for the global `WebSocket`). Requires Chrome/Chromium started with `--remote-debugging-port=9222`.
 
+[1.8.0]: https://github.com/sblattj/cdp-toolkit/releases/tag/v1.8.0
+[1.7.0]: https://github.com/sblattj/cdp-toolkit/releases/tag/v1.7.0
 [1.6.0]: https://github.com/sblattj/cdp-toolkit/releases/tag/v1.6.0
 [1.0.0]: https://github.com/sblattj/cdp-toolkit/releases/tag/v1.0.0

package/CONTRACT.md

@@ -12,7 +12,13 @@ writing a module.
 3. **TypeScript strict.** `tsc --noEmit` must pass with `strict`, `noUncheckedIndexedAccess`, `verbatimModuleSyntax`. Import types with `import type`. Use `.ts` extensions in imports (e.g. `import { withPage } from "../client.ts"`).
 4. **One module per assigned bundle.** Write only the files you are assigned. Never edit `client.ts`, `types.ts`, or another agent's file.
 5. **Tool fn naming = camelCase of the MCP tool name.** `take_snapshot` → `export async function takeSnapshot(...)`. `list_network_requests` → `listNetworkRequests`. The integration step maps mechanically, so the names must be exact.
-6. **Never re-resolve a target outside a choke point.** There are exactly three functions that turn a `TargetSelector` into a concrete tab, and all three call `assertLeaseOk`: `resolveTarget` (`src/client.ts`, Chrome), `resolveContext` (`src/bidi/driver.ts`, Firefox), and `resolvePage` (`src/shared-tools.ts`, used by `close_page` and `select_page`). A new tool must go through one of them. If you add a fourth resolution path, it must call `assertLeaseOk` too, or every tool on that path silently loses lease protection. Do NOT add a lease check to an individual tool: that puts the burden on every future contributor to remember it, and one forgotten tool defeats the feature for that tool. A lease conflict throws `LeaseConflictError` rather than being modelled as a capability gap under ADR-001. That departure is deliberate and reviewed: a runtime ownership collision between two agents is not a missing backend capability, so it cannot be discovered at `tools/list` time and must surface at call time. If you touch any of those three choke points, or the error handling above them, re-run `bun run lease:smoke` (`test/lease-smoke.ts`): `bun test` cannot reach this, because a lease is keyed on the claiming pid and only a second live OS process can collide with the first. That harness spawns one, drives a real browser, and asserts the refusal keeps its type, its `targetId` and its `holder` and actually blocks the side effect. It is safe against a browser with real tabs open: one throwaway tab, addressed and closed by its own id, with a runtime-captured baseline diffed at the end.
+6. **Never re-resolve a target outside a choke point.** There are exactly three functions that turn a `TargetSelector` into a concrete tab, and all three call `assertLeaseOk`: `resolveTarget` (`src/client.ts`, Chrome), `resolveContext` (`src/bidi/driver.ts`, Firefox), and `resolvePage` (`src/shared-tools.ts`, used by `close_page`, `select_page`, and `release_page`'s `target` argument). A new tool must go through one of them. If you add a fourth resolution path, it must call `assertLeaseOk` too, or every tool on that path silently loses lease protection. Do NOT add a lease check to an individual tool: that puts the burden on every future contributor to remember it, and one forgotten tool defeats the feature for that tool. A lease conflict throws `LeaseConflictError` rather than being modelled as a capability gap under ADR-001. That departure is deliberate and reviewed: a runtime ownership collision between two agents is not a missing backend capability, so it cannot be discovered at `tools/list` time and must surface at call time. If you touch any of those three choke points, or the error handling above them, re-run `bun run lease:smoke` (`test/lease-smoke.ts`): `bun test` cannot reach this, because a lease is keyed on the claiming pid and only a second live OS process can collide with the first. That harness spawns one, drives a real browser, and asserts the refusal keeps its type, its `targetId` and its `holder` and actually blocks the side effect. It is safe against a browser with real tabs open: one throwaway tab, addressed and closed by its own id, with a runtime-captured baseline diffed at the end.
+
+   **Under `CDP_REQUIRE_LEASE` the gate does not only check, it can ACQUIRE.** `assertLeaseOk` calls `claimLease` itself when the resolved tab is unheld and strict mode is on (see `requireLease()` and the `auto` tier in `src/leases.ts`). A fourth resolution path that skipped the choke point used to lose only enforcement; under strict mode it also loses acquisition, so a tab reached that way is silently never protected even after the flag is on. `lease:smoke`'s strict-mode phase (`CDP_REQUIRE_LEASE=1`, run as a second live process) is what actually exercises this; `bun test` cannot, since acquisition is keyed on the calling pid the same way enforcement is.
+
+   **`claim_page{target}` is a deliberate, reviewed exception to this rule, not a violation of it.** Its target resolution goes through `pickPage` (`src/shared-tools.ts`), which is exported *specifically* for this one caller and does **not** call `assertLeaseOk`. Routing a claim through `resolvePage` instead would, under strict mode, auto-acquire a lease on the way in and then collide with the explicit claim right behind it, one call claiming the same tab against itself twice. The protection is not dropped, only relocated one layer down: `claimLease`'s own conflict check still refuses a tab any live process holds, auto-acquired or explicit, so a stranger's tab is still refused, only later and by a different function. `pickPage` must never gain a second caller without re-deriving this argument for that caller too; if it does not need gate-free resolution, it needs `resolvePage`, not `pickPage`.
+
+7. **Never dispatch `Input.*` outside `sendInput`.** As of 1.8.0 there is exactly one function that writes a synthesized input command to a Chrome connection: `sendInput(conn, backend, targetId, method, params)` in `src/activity.ts`. `CdpPageDriver.dispatchInput` (the per-driver choke point every interaction method already had to go through) delegates to it, and any tool built outside the Driver abstraction (`dispatch_mouse`, in `src/tools/dispatch-mouse.ts`, is the precedent) must call it directly rather than opening its own `conn.send("Input....", ...)`. This is what keeps the activity beacon's human/agent discrimination (`src/activity.ts`'s dispatch log) correct: a new input path that bypasses `sendInput` will typecheck, pass its own unit tests, and pass `bun test` in full, while silently making the toolkit's own input read as a human using the tab — exactly the 1.8.0 merge bug `test/input-dispatch-wiring.test.ts` now exists to catch (it walks every `.ts` under `src/`, strips comment-only lines, and fails on any line that both sends and names `Input.`). On the Firefox side, `BidiPageDriver.performActions` is the twin choke point and already calls `recordDispatch`; a new BiDi input path goes through it the same way `CdpPageDriver.dispatchInput` is used on Chrome. Mode-toggle commands that dispatch no page input themselves (`Input.setInterceptDrags`'s arm/disarm around HTML5 drag) are still sent through `sendInput` but are on a denylist that skips recording them — classify a new such command explicitly; the default for anything unclassified is to be logged, since over-warning a human is recoverable and silently misattributing their input to "agent" is not.
 
 ## Core client API (from `src/client.ts`)
 
@@ -62,7 +68,10 @@ export async function click(args: ClickArgs): Promise<unknown>;
 - Selected-target state file (for `select_page`): `process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit"` + `/selected`. Contains a bare targetId. `resolveTarget` does NOT read it; tools may read it as a fallback default if you choose, but the simplest correct behavior is fine.
 - Recorder buffers: `${ARTIFACT_DIR}/rec-<targetId>.jsonl`.
 - Screencast spool: `${ARTIFACT_DIR}/screencast-<targetIdShort>-<isoish>/` holding `frame-NNNNNN.jpg|png` plus the generated `frames.ffconcat`. Deleted on a successful encode; **kept, and named in the error, when ffmpeg fails**, so the frames can be re-encoded by hand instead of lost. Output video: `${ARTIFACT_DIR}/screen-recording-<targetIdShort>-<isoish>.mp4`.
-- Lease files: `${ARTIFACT_DIR}/lease-<backend>-<targetId>.json`, one per leased tab, backend is `chrome` or `firefox`. Written with the `wx` exclusive-create flag so two simultaneous claims cannot both win. Keyed by backend plus id because a CDP targetId and a BiDi context id are not disjoint by construction.
+- Lease files: `${ARTIFACT_DIR}/lease-<backend>-<targetId>.json`, one per leased tab, backend is `chrome` or `firefox`. Written with the `wx` exclusive-create flag so two simultaneous claims cannot both win. Keyed by backend plus id because a CDP targetId and a BiDi context id are not disjoint by construction. Carries an `auto?: boolean` field (absent, and read as `false`, on any record older than 1.7.0): `true` means the gate itself acquired it under `CDP_REQUIRE_LEASE` and it is usable by any call from the owning pid with no token; `false` means it was claimed explicitly (`claim_page` or `new_page{claim:true}`) and demands its token even from that same pid.
+- Origin files (`src/origins.ts`): `${ARTIFACT_DIR}/origin-<backend>-<targetId>.json`, one per tab this toolkit itself created (never written for a tab merely claimed). Same exclusive-create discipline as lease files, same directory, and it deliberately OUTLIVES the lease: `release_page`, expiry, and reclamation never touch it, only the tab closing does (reaped on the next `list_pages`/`list_origins` read). This is what `release_page` and reap both consult to decide whether closing a given tab is this toolkit's call to make; see `src/reap.ts`'s header for the four conditions that gate a reap close. As of 1.8.0 an `expired` lease qualifies for that close only past `ttlMs + CDP_REAP_GRACE_MS` (default 45 extra minutes) — `list_leases`' `stale`/reclaimable reading is unchanged at `ttlMs`; only the destructive close moved later. `dead-pid` is unaffected by grace.
+- Beacon sessions (`src/activity.ts`, `src/cdp/driver.ts`): a `BeaconSessions` pool of held Chrome connections, one per tab with an installed activity beacon, bounded at 32 with oldest-first eviction — the same module-scope pattern `recorder.ts`/`network_mock.ts` already use for their own persistent per-target sessions. Exists only because `Page.addScriptToEvaluateOnNewDocument`'s registration dies with the connection that made it (verified against a live browser, not assumed), so surviving navigation under this toolkit's per-call lifetime requires holding a connection open; eviction degrades (the current document's listeners keep answering, only the next navigation's re-arm is lost) rather than breaking. Firefox needs no equivalent: its `LifetimeModel` is `"session"`, so a `script.addPreloadScript` registration on the one memoized BiDi connection per port already lives as long as that connection does.
+- The browser-session connection (`src/tools/browser-session.ts`): one lazily-opened, module-scoped connection to the CDP browser endpoint (not a page endpoint), held open for the process's life, backing `wait_for_download` and `grant_permissions`. Opened only on first use of either tool, so a session that never touches downloads or permissions pays nothing. Exists because `Browser.setDownloadBehavior` and `Browser.grantPermissions` were measured — probed against a real browser before either tool was written — to NOT persist past the arming/granting client's disconnect, which this toolkit's per-call connection lifetime would otherwise hit on every single call. Both tools are therefore MCP-server-only capabilities, the same category as `performance_start_trace`/`stop_screen_recording`'s persistent-connection requirement, for the same underlying reason.
 
 ## The element-reference scheme (READ if you touch snapshot or input)