browser-broker 0.1.0 → 0.2.0

package/dist/src/service/reconcile.js

@@ -82,7 +82,9 @@
  * on the assumption the seam holds up its end.
  */
 export function decideReconciliation(pages, recorded) {
-    const skippedOpening = recorded.filter((tab) => tab.driverTabId === null).map((tab) => tab.tabId);
+    const skippedOpening = recorded
+        .filter((tab) => tab.driverTabId === null)
+        .map((tab) => ({ tabId: tab.tabId, sessionId: tab.sessionId }));
     // Every driver name a live lease claims. Built from the rows that have one,
     // which by §1.4's check is exactly the rows that are not `opening`.
     const owned = new Set(recorded
@@ -123,7 +125,8 @@ export function readRecordedTabs(db, browserId) {
     return db
         .prepare(`SELECT tabs.id AS tabId,
               tabs.driver_tab_id AS driverTabId,
-              tabs.claim_id AS claimId
+              tabs.claim_id AS claimId,
+              claims.session_id AS sessionId
          FROM tabs
          JOIN claims ON claims.id = tabs.claim_id
         WHERE tabs.browser_id = ?
@@ -132,6 +135,57 @@ export function readRecordedTabs(db, browserId) {
         ORDER BY tabs.id`)
         .all(browserId);
 }
+/**
+ * Settle rows stranded at `closing` whose page the browser does not have.
+ *
+ * ── Why the vanished-tab path cannot reach these ────────────────────────
+ *
+ * {@link readRecordedTabs} requires `claims.state = 'active'`, and rightly:
+ * a lapsed lease's rows are the sweep's business, not reconciliation's. But
+ * that is exactly the population that strands. A lease ends, its tab is moved
+ * to `closing`, and if the answer is never written back the row is left in a
+ * state meaning "waiting for the tool" — attached to a lease that is no
+ * longer active, and therefore invisible to every later reconciliation.
+ *
+ * A store was found holding 22 such rows, the oldest two days old, every one
+ * with `close_attempts = 0`. The pages had been closed by hand; the rows
+ * could not be reached by anything.
+ *
+ * ── Why this is safe to settle without asking again ─────────────────────
+ *
+ * The caller has just asked the browser what it has open, and passes the
+ * driver names it answered with. A row whose name is not in that list
+ * describes a page this browser does not have, so there is no round trip
+ * outstanding and nothing to wait for — the same reasoning
+ * {@link applyReconciliation} uses for a vanished page, and the sweep uses
+ * for a tab that never opened.
+ *
+ * **A row whose name IS in the list is left alone.** Its page exists, the
+ * close may genuinely still be in flight, and settling it would claim an
+ * answer nobody has given.
+ */
+export function settleStrandedTabs(db, browserId, openDriverTabIds, at) {
+    const stranded = db
+        .prepare(`SELECT tabs.id AS tabId, tabs.driver_tab_id AS driverTabId
+         FROM tabs
+         JOIN claims ON claims.id = tabs.claim_id
+        WHERE tabs.browser_id = ?
+          AND tabs.state = 'closing'
+          AND claims.state <> 'active'
+        ORDER BY tabs.id`)
+        .all(browserId);
+    const open = new Set(openDriverTabIds);
+    const gone = stranded.filter((tab) => tab.driverTabId === null || !open.has(tab.driverTabId));
+    if (gone.length === 0) {
+        return 0;
+    }
+    const placeholders = gone.map(() => '?').join(', ');
+    db.prepare(`UPDATE tabs
+        SET state = 'closed', closed_at = ?, updated_at = ?
+      WHERE id IN (${placeholders})
+        AND state = 'closing'`).run(at, at, ...gone.map((tab) => tab.tabId));
+    return gone.length;
+}
 /**
  * Settle the rows whose pages are gone, and end the leases that held them.
  *
@@ -155,6 +209,24 @@ export function readRecordedTabs(db, browserId) {
  * | `updateSweptTabs` | The lease ended; is there a page to close? | `closing` — the tool is about to be asked |
  * | this | The page is already gone | `closed` — there is nothing to ask |
  *
+ * **`closing` appears in the predicate, and no row reaches it in that
+ * state.** The rows here come from {@link readRecordedTabs} by way of
+ * {@link decideReconciliation}, and that read requires `tabs.state IN
+ * ('opening', 'open')` — so the third value in the predicate below matches
+ * nothing this caller can supply. It is kept as a bound on what the write is
+ * permitted to touch rather than as a population it serves: the statement
+ * says which states this function may move a row out of, and a future caller
+ * that widens its own read cannot silently reopen a `closed` row through it.
+ *
+ * **The stranded-`closing` population is {@link settleStrandedTabs}'s**, not
+ * this function's, and the distinction is load-bearing. Those rows belong to
+ * leases that have already ended, which is precisely why `readRecordedTabs`
+ * (`claims.state = 'active'`) cannot see them and why they need their own
+ * pass. A store was found holding 22 of them, each still occupying its slot
+ * in the partial unique index on `(browser_id, driver_tab_id)`. Reading that
+ * story as this function's would leave the impression the gap is covered
+ * here, and it is not.
+ *
  * A vanished page has no round trip outstanding, so `closing` would assert
  * one that is not, and the row would wait forever for an answer nobody is
  * coming to give — the exact reasoning the sweep uses for a tab that never
@@ -193,7 +265,7 @@ export function applyReconciliation(db, vanished, at) {
     db.prepare(`UPDATE tabs
         SET state = 'closed', closed_at = ?, updated_at = ?
       WHERE id IN (${tabPlaceholders})
-        AND state IN ('opening', 'open')`).run(at, at, ...tabIds);
+        AND state IN ('opening', 'open', 'closing')`).run(at, at, ...tabIds);
     // The lease goes with the tab, because a lease *is* a tab (§2.3): a lease
     // whose tab is gone owns nothing while still counting against the budget,
     // which §3.13 names as a state that should not exist.

package/dist/src/service/runtime.js

@@ -1,3 +1,4 @@
+import { recordTabCloseFailed, recordTabClosed } from "./arbitration.js";
 import { readEnvironment } from "../config/environment.js";
 import { prepareStore } from "../store/open.js";
 import { ArtifactStore } from "../artifacts/store.js";
@@ -70,6 +71,14 @@ export async function createRuntime(options) {
         environment,
         adapter: options.adapter,
         session: browsers.session,
+        // **What makes `status` able to tell the truth about a dead browser.**
+        // Supplied here rather than defaulted inside the broker for the reason
+        // the option's own comment gives: a build that cannot look must report
+        // `unknown` rather than claim the browser is fine. This build can look,
+        // so it does. Note this is the provider's `liveness`, which asks the
+        // operating system — not its memoised session, which is the very thing
+        // that keeps presenting a dead browser as a working connection.
+        checkBrowser: browsers.liveness,
         artifacts,
         // The same provider closes the tabs the sweep orphaned. Without one,
         // `SCHEMA.md` §2.4b's "a leaked tab is not a leaked lease" describes a
@@ -79,8 +88,24 @@ export async function createRuntime(options) {
         closeTab: async (tab) => {
             const session = await browsers.session(tab.browserId);
             const opened = await resolveDriverTab(store.db, tab.tabId);
-            if (opened !== undefined) {
+            if (opened === undefined) {
+                return;
+            }
+            // **The answer is written down either way.** `closing` means "the tool
+            // was asked and has not answered", so a close that returns and is never
+            // recorded leaves a row saying that forever — which is what happened,
+            // 22 rows deep, until a person noticed his browser had filled with
+            // pages no lease owned.
+            //
+            // A failure is recorded rather than thrown: §2.4b's "a leaked tab is
+            // not a leaked lease" means the capacity is already back, and failing
+            // the release over the page would fail a call that did its job.
+            try {
                 await session.closeTab({ browser: tab.browserId, driverTabId: opened });
+                recordTabClosed(store.db, tab.tabId, new Date().toISOString());
+            }
+            catch {
+                recordTabCloseFailed(store.db, tab.tabId, new Date().toISOString());
             }
         },
     });

package/dist/src/service/tabs.js

@@ -121,3 +121,73 @@ export function recordTabOpened(db, tabId, driverTabId) {
         throw new Error(`Tab ${tabId} was not awaiting an open, so the driver name could not be recorded against it.`);
     }
 }
+/**
+ * How many tabs on one browser are waiting on a close that will not come.
+ *
+ * ── Why this is one function and not two ────────────────────────────────
+ *
+ * `broker doctor` and the claim grant both have to answer *"is this browser
+ * carrying a backlog of stranded tabs"*, and a product holding two notions of
+ * "stranded" would be the same defect the backlog itself caused: a caller
+ * told one number by one surface and a different number by another has no way
+ * to tell which is the real one. So the predicate lives here once, and both
+ * read it.
+ *
+ * ── Why the threshold is a lease's own lifetime ─────────────────────────
+ *
+ * Taken from `doctor`'s existing definition rather than invented alongside
+ * it. `closing` means the tool was asked and has not answered — a transient
+ * state measured in a round trip. The honest boundary between "a close is in
+ * flight" and "a close is never happening" is the one the system already uses
+ * to decide a caller is gone: if a lease may be declared lapsed after this
+ * long without contact, a round trip outstanding for longer is not pending.
+ *
+ * The comparison is on `updated_at`, which is when the row was moved to
+ * `closing`. A round trip still inside the window is deliberately not
+ * counted, because reporting one would make a healthy release look like a
+ * fault.
+ */
+export function countStrandedTabsFor(db, browserId, leaseSeconds, at = new Date()) {
+    const cutoff = new Date(at.getTime() - leaseSeconds * 1000).toISOString();
+    const row = db
+        .prepare(`SELECT COUNT(*) AS n
+         FROM tabs
+        WHERE browser_id = ?
+          AND state = 'closing'
+          AND updated_at < ?`)
+        .get(browserId, cutoff);
+    return row?.n ?? 0;
+}
+/**
+ * The stranded backlog broken down per browser, heaviest first.
+ *
+ * ── Why a breakdown rather than a total ─────────────────────────────────
+ *
+ * A total is not actionable when the remedy is per-browser. `doctor`'s
+ * remedy line says to run `broker reconcile` against each browser, but a
+ * single total cannot say which ones still need it: an operator who
+ * reconciled `regular` and saw the count fall from 29 to 13 reasonably
+ * concluded reconcile had not worked, when in fact the remaining 13 were all
+ * on `private` and the run had done exactly what it said.
+ *
+ * **Grouped rather than asked per browser from a configured list**, because
+ * the browsers are a configured list per kind and not a fixed pair — a
+ * breakdown assembled from the list this build happens to know about would
+ * silently omit a backlog on a browser that had been reconfigured away, which
+ * is the population most likely to be stranded.
+ *
+ * Only browsers carrying a backlog appear. A row reading zero is not a
+ * finding, and listing every configured browser on every healthy run would
+ * bury the one line that matters.
+ */
+export function strandedTabsByBrowser(db, leaseSeconds, at = new Date()) {
+    const cutoff = new Date(at.getTime() - leaseSeconds * 1000).toISOString();
+    return db
+        .prepare(`SELECT browser_id AS browserId, COUNT(*) AS stranded
+         FROM tabs
+        WHERE state = 'closing'
+          AND updated_at < ?
+        GROUP BY browser_id
+        ORDER BY COUNT(*) DESC, browser_id`)
+        .all(cutoff);
+}

package/dist/src/tool/session.js

@@ -14,13 +14,26 @@ import { TOOLS_BY_NAME, TOOL_DEFINITIONS } from "./tools.js";
  *
  * Read once at module load rather than per handshake: it cannot change while
  * the process runs, and a session serves one client.
+ *
+ * ── Why the read is allowed to fail ─────────────────────────────────────
+ *
+ * A missing or unreadable manifest must not take the surface down with it.
+ * This module is imported by the executable a client spawns, so a throw here
+ * happens *before* anything can be served and before the protocol exists to
+ * describe it — the client sees the process exit, not an error it can act on.
+ * Weighed against that, the cost of not knowing the version is a cosmetic
+ * field in one handshake.
+ *
+ * The command line degrades this way already, and by accident rather than by
+ * design: it reads the manifest inside the function behind `--version`, so
+ * every other command keeps working when the file is gone. Matching that
+ * behaviour deliberately is the point of the `catch` — the fallback is the
+ * same literal this constant held before it read anything.
  */
-const manifest = await import('../../package.json', { with: { type: 'json' } });
+const manifest = await import('../../package.json', { with: { type: 'json' } }).catch(() => undefined);
 export const SERVER_INFO = {
     name: 'browser-broker',
-    version: typeof manifest.default.version === 'string'
-        ? manifest.default.version
-        : '0.0.0',
+    version: typeof manifest?.default?.version === 'string' ? manifest.default.version : '0.0.0',
 };
 /**
  * What `initialize` returns: the negotiated revision, what this server can

package/dist/src/tool/tools.js

@@ -1,5 +1,136 @@
 import { OPERATION_NAMES } from "../adapter/operations.js";
 import { BROWSER_CHOICE_GUIDANCE } from "../browser/driver.js";
+/**
+ * The twelve tools, their descriptions, and their argument schemas.
+ *
+ * ── Surface area is a standing tax, and this file is where it is paid ────
+ *
+ * `SCHEMA.md` §3.1 opens with it: every description here sits in a connected
+ * session's context **on every turn**, whether or not anything calls the
+ * tool. Twelve descriptions is the whole agent-facing documentation of this
+ * service and it is also a per-turn cost on every session, so each one is
+ * written to be the shortest text that still prevents a wrong call.
+ *
+ * **The description is the only place a calling agent reliably reads.** Not
+ * `SCHEMA.md`, not a wiki, not a refusal it has not hit yet. So where a fact
+ * changes what a caller does — that `browser_status` is also the renew verb,
+ * that the browser choice has no default, that feedback needs no lease — the
+ * fact is in the description rather than only in the argument list.
+ *
+ * **`browser_sign_in`'s description is the strongest case of that rule, and
+ * the reason it reads as an instruction rather than a summary.** The failure
+ * it exists to end is a caller hitting a login wall and never learning it
+ * could ask — and **no refusal can reach that caller**, because it never
+ * makes a call to be refused. It abandons the task or fabricates a session
+ * instead, which is what 25 measured sessions did in a month. There is no
+ * second surface for that guidance to live on, so the description names the
+ * alternative outright, the way a refusal would.
+ *
+ * ── What is deliberately absent ─────────────────────────────────────────
+ *
+ * **There is no browser-scoped destructive verb, and there must never be
+ * one.** No close-browser, no kill-all, no restart. `SCHEMA.md` §3.13 makes
+ * that part of the contract rather than an omission: the administrative
+ * operations act on something every caller shares, so they are commands a
+ * person runs (§4.3, §5.4) and the ledger records that a person did.
+ * **The worst thing an agent can do through this surface is close its own
+ * tab**, and that ceiling is the reason this surface can be handed to an
+ * arbitrary caller at all.
+ *
+ * **`browser_sign_in` and `browser_sign_in_done` move a browser's state and
+ * do not breach that ceiling**, which is worth stating because they look like
+ * the exception. Both are keyed, and both act only on the lease that called
+ * them: the first takes the browser only when no *other* lease holds a tab on
+ * it, and the second is refused unless the calling lease is the one that
+ * asked — so a caller can neither interrupt somebody else's work nor end a
+ * person's sign-in command mid-password. The unkeyed pair that could do those
+ * things, `begin_sign_in` and `end_sign_in`, is deliberately not on this
+ * surface at all.
+ *
+ * `browser_tab_close` is absent for a second, separate reason (§3.1): it
+ * closed a caller's only tab while keeping the lease, producing a lease that
+ * owned nothing and still consumed budget. It is gone rather than deprecated,
+ * and it should not be reintroduced.
+ */
+/**
+ * What a capture can and cannot be trusted to show (§3.11).
+ *
+ * ── A picture is the one result a caller cannot check against itself ─────
+ *
+ * Every other operation here returns something self-describing: a claim
+ * returns a key, an evaluation returns a value, a refusal explains itself. A
+ * capture returns a path to an image, and **an image of a half-rendered page
+ * looks exactly like an image of a broken one.** There is no field in the
+ * result to distrust, so a caller has nothing to weigh the picture against —
+ * which makes a wrong conclusion from a capture both easy to reach and hard
+ * to notice.
+ *
+ * The consequence is not hypothetical, and it is what puts this text on the
+ * description rather than in a document: a field session captured a canvas
+ * before it had drawn, read the dark frame as the page's real appearance, and
+ * **reported a fault against an application that did not have one.** It was
+ * caught only because a second measurement happened to disagree — which is
+ * not a mechanism anything can rely on.
+ *
+ * ── Why settling does not already cover this ─────────────────────────────
+ *
+ * Every capture settles the page first, and settling is worth exactly what
+ * §3.11 claims: it stops animations and transitions, hides the caret, and
+ * waits for web fonts, so the same page yields the same pixels run to run.
+ * **That is repeatability, not completeness.** It makes a moving page hold
+ * still; it cannot make an unfinished page finish. A canvas that has not
+ * drawn its first frame is not moving — it is absent — and holding it still
+ * is not the same as waiting for it.
+ *
+ * ── Why this names a check rather than a duration ────────────────────────
+ *
+ * The tempting sentence is *"allow the page to settle first"*, and it is
+ * advice a caller cannot act on: **the right wait is a property of the page,
+ * not of this service**, and a caller that has never seen the page rendered
+ * has no way to pick a number. Any figure written here would be wrong for
+ * some page and would be trusted anyway, which is worse than saying nothing.
+ *
+ * So the guidance is a **check** instead — capture twice and compare, which
+ * this tool can already express through `compare_to`. A caller can act on it
+ * without knowing anything about the page in advance, and it answers the
+ * question actually being asked, which is not *"has enough time passed"* but
+ * *"has this stopped changing"*. Two identical frames are evidence; one frame
+ * and a duration are an assumption.
+ */
+const CAPTURE_SETTLE_CAVEAT = 'Captures are settled — animations stopped, fonts waited for — so a page yields the same ' +
+    'pixels twice; that steadies a moving page but does not wait for one still drawing. A canvas ' +
+    'or a deferred region can be captured before it has rendered, and the picture will look like a ' +
+    'broken page rather than an early one. When a frame looks wrong, capture again with compare_to ' +
+    'and check it against the first: no difference means you are seeing the page, not a moment of it.';
+/**
+ * What this tool's unit is wrong for, so a caller with the other job does not
+ * reach for it anyway.
+ *
+ * ── The distinction this exists to draw ──────────────────────────────────
+ *
+ * `compare_to` answers *"did this page change since a moment ago, on this
+ * same tab"* — a before-and-after over time, one lease, one running build.
+ * That is a different question from *"how do these two builds differ"*,
+ * where the two things being compared are not two moments of one tab but two
+ * separate runs, often of separate processes. This surface's unit is one
+ * lease holding one tab, which is the right shape for the first question and
+ * the wrong one for the second: a two-build comparison wants something that
+ * reads the scene or the DOM directly, not pixels from whichever tab happened
+ * to be open.
+ *
+ * ── Why this is worth a sentence rather than leaving it to be inferred ────
+ *
+ * A caller framing its task as "compare two builds" will reach for whatever
+ * on this surface has the word "compare" in it, and `compare_to` is the only
+ * candidate. Nothing here refuses that call — a diff still runs and still
+ * answers a real question about the two pixels it was given — so the caller
+ * gets an answer that looks like the one it asked for while measuring
+ * something else. A routing hint at the point of the call is the only thing
+ * that can catch this before the wrong tool is already in use; there is no
+ * refusal to word better; the call succeeds.
+ */
+const CAPTURE_BUILD_COMPARISON_CAVEAT = 'For comparing two builds — not two moments of the one tab you hold — a tool reading the scene ' +
+    'or DOM directly beats this one: this surface is one lease, one tab, pixels.';
 /** Every tool takes the key except the first and the last (§3.1). */
 const LEASE_KEY = {
     name: 'lease_key',
@@ -107,7 +238,16 @@ export const TOOL_DEFINITIONS = [
                 name: 'wait_ms',
                 type: 'integer',
                 required: false,
-                description: 'How long to wait for the page, in milliseconds.',
+                description: 'How long the navigation may take before it is abandoned, in whole milliseconds. ' +
+                    'A bound, not a pause: the call returns as soon as the page is there, so a larger ' +
+                    'value costs nothing on a page that loads quickly and two calls differing only in ' +
+                    'this argument tell you nothing about how long the page was given to settle. ' +
+                    'It bounds the load only, and does not wait for work the page starts afterwards, so ' +
+                    'a canvas or a lazily-loaded region can still be unfinished when this returns; see ' +
+                    'browser_capture on how to tell. ' +
+                    'At most the lease lifetime, because a wait outliving the lease would hold the tab ' +
+                    'past the point it becomes reclaimable; the refusal names the accepted range. ' +
+                    'Omit it to leave the browser default in force.',
             },
         ],
     },
@@ -175,7 +315,10 @@ export const TOOL_DEFINITIONS = [
         operation: 'capture',
         description: 'Take a picture of the page — and, if you name an earlier capture, what changed since it. ' +
             'Returns paths, never the image itself. A selector and a full page cannot both be asked ' +
-            'for. Never refused for cost.',
+            'for. Never refused for cost. ' +
+            CAPTURE_SETTLE_CAVEAT +
+            ' ' +
+            CAPTURE_BUILD_COMPARISON_CAVEAT,
         arguments: [
             LEASE_KEY,
             {
@@ -196,11 +339,19 @@ export const TOOL_DEFINITIONS = [
                 required: false,
                 description: 'An earlier capture to diff against. The diff rides here rather than being its own tool.',
             },
+            {
+                name: 'tier',
+                type: 'string',
+                required: false,
+                description: '"detail" or "max" for a higher resolution. Omit for the default — there is no way to ' +
+                    'ask for the default by name. "max" also requires reason.',
+            },
             {
                 name: 'reason',
                 type: 'string',
                 required: false,
-                description: 'Free text, recorded, never refused — why this capture needed more than the default tier.',
+                description: 'Free text, 8-200 characters, recorded, never refused — why this capture needed more ' +
+                    'than the default tier. Required with tier="max".',
             },
         ],
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-broker",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "MIT",
   "description": "Leases over tabs in a fixed set of browsers: bounded capacity, a queue, reclamation, and an enforced capture policy.",
   "type": "module",
@@ -19,12 +19,13 @@
     "check:operations": "node scripts/check-operations.mjs",
     "check:argument-refusals": "node scripts/check-argument-refusals.mjs",
     "check:injected-tests": "node scripts/check-injected-tests.mjs",
+    "check:argument-reachability": "node scripts/check-argument-reachability.mjs",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "test": "node --test \"tests/**/*.test.mjs\" \"tests/**/*.test.ts\"",
-    "check": "npm run check:external-refs && npm run check:doc-links && npm run check:arbitration && npm run check:capture-isolation && npm run check:artifact-path && npm run typecheck && npm run lint && npm run format:check && npm test && npm run check:install && npm run check:operations && npm run check:argument-refusals && npm run check:injected-tests",
+    "check": "npm run check:external-refs && npm run check:doc-links && npm run check:arbitration && npm run check:capture-isolation && npm run check:artifact-path && npm run typecheck && npm run lint && npm run format:check && npm test && npm run check:install && npm run check:operations && npm run check:argument-refusals && npm run check:argument-reachability && npm run check:injected-tests && npm run check:package",
     "check:arbitration": "node scripts/check-arbitration.mjs",
     "check:artifact-path": "node scripts/check-artifact-path.mjs",
     "build": "tsc --project tsconfig.build.json",