browser-broker 0.1.0 → 0.3.1

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',
@@ -91,9 +222,10 @@ export const TOOL_DEFINITIONS = [
     {
         name: 'browser_navigate',
         operation: 'navigate',
-        description: 'Point your tab at an address. Returns the final address after redirects, the title, the ' +
-            'status, and a path to the accessibility snapshot taken on arrival — a path, because a ' +
-            'snapshot is thousands of tokens and you usually want one part of it.',
+        description: 'Point your tab at an address. Returns the final address after redirects — which is not ' +
+            'always the address you asked for, and is the field to check when you need to know ' +
+            'whether something sent you elsewhere — plus the title and the status. ' +
+            'It does NOT take a snapshot: use browser_read for one.',
         arguments: [
             LEASE_KEY,
             {
@@ -107,7 +239,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 +316,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 +340,23 @@ 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. **A tier raises the LONGEST ' +
+                    'edge, not the width**, so on a full_page capture of a page taller than it is wide the ' +
+                    'height takes the whole budget and the width stays small at every rung — a 1030px-wide ' +
+                    'page 6400px tall is about 165px wide by default and about 414px wide at "max". For ' +
+                    'legible text on a tall page, capture a selector instead, or read the page as text.',
+            },
             {
                 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.3.1",
   "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",
@@ -52,7 +53,6 @@
     "dist/",
     ".env.example",
     "README.md",
-    "RELEASES.md",
     "LICENSE"
   ]
 }

package/RELEASES.md

@@ -1,97 +0,0 @@
-# Release notes
-
-**What changes between versions, and specifically what changes *behaviour* on an installation that
-sets nothing.**
-
-That second half is the reason this file exists rather than the commit log being enough. A new
-setting with a neutral default is not news: an installation that does not set it behaves exactly as
-before. **A changed default is news**, because it moves an installation that has taken no action and
-made no decision. `docs/plans/DECISIONS.md` §6.3 puts a changed default here rather than in a quiet
-edit for that reason.
-
-Entries are newest first. Each names what moved, what an installation has to do about it, and what
-happens if it does nothing.
-
----
-
-## Unreleased
-
-### The package is published, and it ships compiled JavaScript
-
-**What moved.** The service is installable from the registry as `browser-broker`, so a caller can
-spawn it without a checkout. The manifest's `bin` entries now name emitted JavaScript under `dist/`
-rather than the TypeScript sources.
-
-**Why the build exists**, given that the development path deliberately has none: **Node refuses to
-strip types from any file under a `node_modules` path**, and an installed package is a directory
-under `node_modules`. A manifest whose `bin` named a `.ts` file would install cleanly and then fail
-on the machine of whoever installed it. There is no flag that changes this. The compiler therefore
-runs once per release rather than on every machine that consumes the package, and `erasableSyntaxOnly`
-stays on so the sources still run unbuilt — the two paths execute the same dialect.
-
-**What an installation has to do.** Nothing. A checkout is unaffected: `node src/bin/broker.ts` still
-runs the sources with no build. An installation that would rather not track a checkout can point at
-the package instead, and npm revalidates the version on every spawn:
-
-```json
-{ "command": "npx", "args": ["-y", "browser-broker"] }
-```
-
-**Worth weighing before switching:** `npx` performs a registry round-trip on every spawn, costing
-seconds where a path on disk costs a fraction of one. It buys an upgrade path, not speed.
-
-**One surface changes what it reports.** The tool handshake's `serverInfo.version` was the literal
-`0.0.0` while the package was unversioned, and now reads the manifest — so a client logging it sees
-the released version rather than a placeholder.
-
-
-### ⚠ Behaviour change: the default browser engine is Edge
-
-**What moved.** A browser launched by this service uses **`msedge`** by default. The previous
-behaviour was to launch whatever `chromium.executablePath()` resolved to — the Chromium build the
-automation library had fetched.
-
-**Why.** Edge is present on every Windows machine, so a fresh install runs with nothing set, with no
-separate browser download step. That is `DECISIONS.md` §6.1's *"a fresh install runs with nothing
-set"* applied to the one prerequisite `npm install` genuinely could not cover.
-
-**What an installation has to do.** Nothing, if Edge is acceptable. To keep the prior behaviour, or
-to pick a different browser, set the engine per kind:
-
-```bash
-BROKER_REGULAR_BROWSER_ENGINE=chrome     # chrome | brave | msedge
-BROKER_PRIVATE_BROWSER_ENGINE=chrome     # may differ from the line above
-```
-
-**If it does nothing:** browsers launch under Edge. **Profiles are per browser and are not shared
-between engines**, so an installation whose signed-in profile was established under a different
-binary will find that browser signed out, and a person will be asked to sign in once more with
-`broker login`. Nothing is destroyed — `setup.profile_never_destroyed` still holds, and the earlier
-profile directory is left exactly where it is.
-
-### Browsers are a configured list, and `browser` on a claim is optional
-
-**What moved.** Two things, both reversals of recorded decisions — the argument for each is in
-`DECISIONS.md` §13i:
-
-- **The fixed pair of browsers becomes a bounded list per kind**, at most three each, named in
-  configuration. A name is what a caller claims by and what its profile directory is called.
-- **`browser` on `browser_claim` becomes optional.** Unstated resolves to the first signed-in
-  browser; `regular` or `private` resolves to the first of that kind; a configured name resolves to
-  that browser exactly.
-
-**What an installation has to do.** Nothing. The defaults name one browser of each kind, `regular`
-and `private`, which is the pair that existed before — so an installation that sets nothing has the
-same two browsers under the same two names, and a caller that states `browser` explicitly is
-unaffected.
-
-**Worth reading before configuring more than the default two:** the tab budget counts *tabs*, and
-each browser costs a process **before it holds a single tab**. `BROKER_TAB_BUDGET=15` with six
-browsers is six browser processes, plus up to fifteen tabs, plus six keeper tabs that are not
-counted against the budget at all. `.env.example` states this beside the variables.
-
-**One schema step.** The store gains a `kind` column on `browsers` and drops the check constraint
-that limited a browser's name to two literals. It is applied on the next spawn, like every step, and
-the two existing rows are backfilled to their own kinds. **A store stepped by this build is not
-readable by an earlier one**, which is the ordinary direction — a build refuses a store newer than
-itself rather than downgrading it.