browser-broker 0.1.0

package/dist/src/capture/pipeline.js

@@ -0,0 +1,153 @@
+import { randomUUID } from 'node:crypto';
+import { captureFileName } from "../artifacts/names.js";
+import { BrokerError } from "../errors.js";
+import { captureWarning } from "./accounting.js";
+import { decodePng, downscale, encodePng } from "./image.js";
+import { DEFAULT_TIER, REASON_MAXIMUM_LENGTH, REASON_MINIMUM_LENGTH, TIER_LONGEST_EDGE, TIER_REQUIRING_REASON, estimateTokens, } from "./tiers.js";
+/**
+ * The escalation guidance, built from the tier names themselves.
+ *
+ * `SCHEMA.md` §3.11 is specific about what this must say, and the specificity
+ * is the point: *"Not merely that higher tiers exist — **which fields to
+ * pass**, naming `tier` and its two values, **and that the top tier requires a
+ * written reason.**"* A caller that cannot read the fine print out of a
+ * specification it does not have open is a caller that either never escalates
+ * or escalates by trial and error, and both waste a call.
+ *
+ * Composed from {@link TIER_LONGEST_EDGE} and {@link TIER_REQUIRING_REASON}
+ * rather than written out, so this text always quotes the rungs the pipeline
+ * actually shrinks to, whatever the study (#34) sets them to.
+ */
+function escalationGuidance() {
+    return (`This is the default resolution (about ${String(TIER_LONGEST_EDGE.default)}px on the long ` +
+        `edge), which is what you get for passing no tier. For more detail pass ` +
+        `tier="detail" (about ${String(TIER_LONGEST_EDGE.detail)}px). For the most, pass ` +
+        `tier="max" (about ${String(TIER_LONGEST_EDGE.max)}px) — and note that "max" additionally ` +
+        `requires reason, a written explanation of ${String(REASON_MINIMUM_LENGTH)}–` +
+        `${String(REASON_MAXIMUM_LENGTH)} characters in your own words. The reason is recorded for ` +
+        `review rather than used to decide anything: escalating is allowed, and saying why is how ` +
+        `the default gets tuned.`);
+}
+/**
+ * The three argument mistakes §3.11 names, and **the only refusals here.**
+ *
+ * *"The only refusals are argument mistakes: an unknown or closed tab, the top
+ * tier without a reason, and a selector combined with a full page."* The first
+ * belongs to the layer that resolves a tab identifier; the other two are this
+ * module's.
+ *
+ * **Nothing in this function considers cost, budget, count or resolution**,
+ * and that absence is what `capture.never_refused_for_cost` (§7.3) asserts.
+ * Every refusal it can make is about the arguments disagreeing with each
+ * other, never about how many pictures anybody has taken.
+ */
+function refuseArgumentMistakes(options) {
+    if (options.fullPage === true && options.selector !== undefined) {
+        throw new BrokerError('capture.arguments_consistent', 'A selector cannot be combined with a full page: one asks for a single element and the other for the whole document. Pass one or the other.');
+    }
+    const tier = options.tier ?? DEFAULT_TIER;
+    if (tier !== TIER_REQUIRING_REASON) {
+        return;
+    }
+    const reason = options.reason?.trim() ?? '';
+    if (reason.length < REASON_MINIMUM_LENGTH || reason.length > REASON_MAXIMUM_LENGTH) {
+        throw new BrokerError('capture.reason_required', `tier="${TIER_REQUIRING_REASON}" requires reason: a written explanation of ${String(REASON_MINIMUM_LENGTH)}–${String(REASON_MAXIMUM_LENGTH)} characters, in your own words rather than chosen from a list. It is recorded for review, not used to decide whether to serve the capture — nothing here is refused on cost grounds.`);
+    }
+}
+/**
+ * Take one capture.
+ *
+ * @param capturesTakenBefore how many captures this lease had already taken.
+ *   Supplied by the layer that counts them, because counting is a query
+ *   against the store and this module reaches no store.
+ *
+ * The order below is the specification and is not incidental:
+ *
+ * 1. **Refuse the argument mistakes first**, before anything physical happens.
+ *    `DECISIONS.md` §5: *a guard that returns "denied" after the tab has
+ *    already opened is worse than no guard.* The refusals above run before the
+ *    driver is touched at all, and the test for each asserts the driver's call
+ *    log is empty rather than merely that an error was thrown.
+ * 2. **Settle the page, then take the picture** (§3.11). Two calls in that
+ *    order, on the seam, so the ordering is assertable from outside.
+ * 3. **Downscale to the tier**, never up.
+ * 4. **Write it**, through the artifact store, which is the only thing that
+ *    decides where a file may go.
+ */
+export async function takeCapture(dependencies, claimId, tab, options, capturesTakenBefore) {
+    refuseArgumentMistakes(options);
+    const now = dependencies.now ?? (() => new Date());
+    const newId = dependencies.newId ?? randomUUID;
+    const tier = options.tier ?? DEFAULT_TIER;
+    const fullPage = options.fullPage ?? false;
+    // Settling comes before the shutter and is a separate call, so that "every
+    // capture settles the page first" is one assertion on the driver's call log
+    // rather than a claim about a driver's internals (§3.11).
+    await dependencies.tabs.settlePage(tab);
+    const raw = await dependencies.tabs.capture(tab, {
+        fullPage,
+        selector: options.selector,
+        // Passed straight through to the driver, because masking *before* the
+        // pixels exist beats filtering afterwards: a region that was never
+        // captured cannot be reported as changed (§3.11).
+        mask: options.mask,
+    });
+    const decoded = decodePng(raw.image);
+    const shrunk = downscale(decoded, TIER_LONGEST_EDGE[tier]);
+    // Re-encoded only when the pixels actually changed. A picture already inside
+    // the rung is written as the browser produced it, which keeps
+    // `width === source_width` meaning "nothing was shrunk" without a re-encode
+    // silently changing the bytes underneath that claim.
+    const encoded = shrunk === decoded ? raw.image : encodePng(shrunk);
+    const takenAt = now();
+    const id = newId();
+    const stored = dependencies.artifacts.write(claimId, 'images', captureFileName({
+        // Derived from the address, with the query string stripped first — see
+        // `names.ts` for why a file name is held to a stricter rule than a
+        // column is.
+        url: raw.url,
+        label: options.label,
+        viewportWidth: raw.viewportWidth,
+        takenAt,
+        id,
+    }), encoded);
+    const warning = captureWarning(capturesTakenBefore);
+    const kind = options.selector !== undefined ? 'element' : fullPage ? 'full_page' : 'viewport';
+    const telemetry = {
+        id,
+        kind,
+        tier,
+        // Only ever recorded on the tier that requires it: a reason attached to a
+        // capture nobody had to justify would put noise into the one column the
+        // resolution study reads (§1.7).
+        reason: tier === TIER_REQUIRING_REASON ? options.reason?.trim() : undefined,
+        sourceWidth: raw.width,
+        sourceHeight: raw.height,
+        width: shrunk.width,
+        height: shrunk.height,
+        bytes: stored.bytes,
+        path: stored.relativePath,
+        selector: options.selector,
+        viewportWidth: raw.viewportWidth,
+        url: raw.url,
+        warned: warning !== undefined,
+        takenAt,
+    };
+    return {
+        captureId: id,
+        path: stored.relativePath,
+        width: shrunk.width,
+        height: shrunk.height,
+        bytes: stored.bytes,
+        sourceWidth: raw.width,
+        sourceHeight: raw.height,
+        tier,
+        estimatedTokens: estimateTokens(shrunk.width, shrunk.height),
+        capturesThisLease: capturesTakenBefore + 1,
+        // Present exactly when the caller landed on the default rung, because that
+        // is exactly the caller who has not been told what the alternatives are.
+        ...(tier === DEFAULT_TIER ? { escalation: escalationGuidance() } : {}),
+        ...(warning !== undefined ? { warning } : {}),
+        telemetry,
+    };
+}

package/dist/src/capture/tiers.js

@@ -0,0 +1,166 @@
+/**
+ * The three resolution rungs, the default, and the estimate of what a picture
+ * costs to look at.
+ *
+ * ── The default is the lever, and this file is where it lives ───────────
+ *
+ * `DECISIONS.md` §13d reverses the research recommendation, which was a hard
+ * service-enforced ceiling with a refusal past a per-lease budget. What ships
+ * is a **low default, an explicit opt-in to go higher, and a warning that
+ * never becomes a wall** — and the reason is that *most callers never pass an
+ * optional parameter*, so a low default does nearly all the work of a ceiling
+ * **without blocking anyone**. `MILESTONES.md` #31 puts it plainly: this row
+ * carries the lever, not #33.
+ *
+ * The property underneath, stated as a property because a property survives
+ * somebody raising the default and a coincidence does not: **text legibility
+ * breaks at a higher resolution than layout critique does.** So a low default
+ * naturally pushes a caller that needs to *read* something toward the snapshot
+ * or the evaluation, which return text and cost almost nothing. The policy does
+ * not have to argue anyone into the cheaper tool.
+ *
+ * ── These numbers have been MEASURED, and they survived it ──────────────
+ *
+ * `MILESTONES.md` #34's resolution-ladder study has been run — the harness is
+ * `ladder.ts`, the instruments are `legibility.ts`, and the measurements are
+ * `tests/capture/ladder.test.ts` (everywhere) and
+ * `tests/capture/ladder-rendered.test.ts` (where a browser exists).
+ * **The measurement kept all three rungs below**, and the evidence for each is
+ * published beside it. A change to any of them needs a measurement rather than
+ * an argument.
+ *
+ * **The property the default rests on held.** *Text legibility breaks at a
+ * higher resolution than layout critique does* is now measured rather than
+ * asserted, and the mechanism is nameable: a downscale destroys a feature when
+ * the feature's period falls below roughly two and a half **destination**
+ * pixels, so what a rung costs a picture depends on the size of the feature
+ * rather than on the rung. A block-scale feature — the scale a layout
+ * judgement is made at — survives every rung on this ladder, including well
+ * below the cheapest one. Fine text detail does not.
+ *
+ * Stem retention on rendered prose, at a viewport wide enough that all three
+ * rungs genuinely shrink:
+ *
+ * | Font | `default` | `detail` | `max` |
+ * |---|---|---|---|
+ * | 11px | 35% | 41% | 100% |
+ * | 12px | 24% | 50% | 100% |
+ * | 14px | 7% | 83% | 100% |
+ * | 16px | 63% | 93% | 100% |
+ * | 20px | 87% | 100% | 100% |
+ * | 32px | 98% | 100% | 100% |
+ *
+ * Each rung does the job its name claims: **`max` returns everything**, which
+ * is why it is the one that costs a written reason; **`detail` recovers
+ * ordinary body copy**; and **`default` keeps headings and layout intact while
+ * damaging small body copy** — which is not a defect but the lever working,
+ * since a caller that needs to *read* something is pushed toward the snapshot
+ * or the evaluation, which return text and cost almost nothing.
+ *
+ * ── ⚠️ What the study did NOT settle ────────────────────────────────────
+ *
+ * **The absolute legibility floor is still open**, and it is worth being exact
+ * about why. The instruments measure what the *pipeline* destroys — stroke
+ * contrast, and whether the gaps between strokes survive — which **bounds**
+ * what any reader could recover but does not predict what one will. What an
+ * agent looking at a picture can actually read is a property of that model,
+ * not of these pixels, and no test here can establish it. So the rungs are
+ * settled as *"these deliver the structure they claim to"*, not as *"this is
+ * the smallest picture a reader can use"*. §9.3 keeps that second question
+ * open.
+ *
+ * They remain named constants in one module: **nothing hard-codes a rung
+ * anywhere a later study cannot change it**, and a capture records which rung
+ * it was taken at (`captures.tier`) rather than having its rung inferred from
+ * its dimensions, so a rung moving invalidates nothing already stored (§6.2).
+ *
+ * ── The token estimate is fixed by the version, deliberately ────────────
+ *
+ * `SCHEMA.md` §6.4: the formula that estimates an image's token cost is fixed
+ * by the version and **is not configurable**. *"An estimate is only comparable
+ * across time if it was computed the same way, and letting an operator change
+ * the formula would silently make old and new numbers incomparable — which
+ * would break the one study they exist for."* So there is no environment
+ * variable here and no parameter: {@link estimateTokens} takes dimensions and
+ * nothing else.
+ */
+/**
+ * What a caller gets for asking for nothing.
+ *
+ * The single most consequential value in this milestone — `MILESTONES.md`
+ * #31: *"getting 'cheapest tier when nothing is asked for' right matters more
+ * than any threshold downstream of it."*
+ */
+export const DEFAULT_TIER = 'default';
+/**
+ * The tier that costs a written reason.
+ *
+ * Named rather than spelled `'max'` at each site that checks it, so that the
+ * rule *"the top tier requires a reason"* has one definition and the message
+ * telling a caller so cannot drift from the check that enforces it.
+ */
+export const TIER_REQUIRING_REASON = 'max';
+/**
+ * The long edge each rung shrinks to, in pixels (`SCHEMA.md` §6.2,
+ * `DECISIONS.md` §13d). **Measured by #34 and kept** — see the evidence table
+ * in this file's header.
+ *
+ * | Tier | Long edge | How a caller gets it | What the study measured it delivering |
+ * |---|---|---|---|
+ * | `default` | 1024 | passes nothing | layout and headings intact; small body copy damaged |
+ * | `detail` | 1568 | asks for it — the ceiling of the cheap vision tier | ordinary body copy recovered |
+ * | `max` | 2576 | asks for it **and gives a written reason**, which is recorded | everything, at every font size tested |
+ */
+export const TIER_LONGEST_EDGE = {
+    default: 1024,
+    detail: 1568,
+    max: 2576,
+};
+/**
+ * The bounds on a written reason (`SCHEMA.md` §3.11: 8–200 characters).
+ *
+ * **The minimum is not a deterrent and must not be tuned as one.** §3.11 is
+ * explicit: *a caller asked to justify itself will always produce a
+ * justification*, so the friction is not the mechanism, and making the field
+ * longer or the wording sterner pursues an effect it was never going to have.
+ * **The value is the record** — every escalation leaves a reviewable row with
+ * a reason attached. The minimum exists only to make the empty answer
+ * slightly harder to give than a real one.
+ */
+export const REASON_MINIMUM_LENGTH = 8;
+export const REASON_MAXIMUM_LENGTH = 200;
+/**
+ * How many captures a lease may take before every subsequent one carries a
+ * warning (`SCHEMA.md` §6.2: **12**).
+ *
+ * *"Roughly a five-view sweep at two breakpoints plus slack."* **Never a
+ * refusal** — see `accounting.ts`, which is where that promise is kept and
+ * where the reason it can never become a wall is written down.
+ */
+export const CAPTURES_BEFORE_WARNING = 12;
+/**
+ * The divisor in the token estimate. **Fixed by the version** (§6.4).
+ *
+ * `SCHEMA.md` §1.7 declines to store the result: *"It is width times height
+ * divided by a fixed constant — a calculation over two columns on the same
+ * row … computed when asked for rather than frozen into a column that could
+ * disagree with the dimensions beside it."*
+ *
+ * The constant is consistent with the measured figures `DECISIONS.md` records
+ * — roughly 1,600 tokens at the 1568-pixel rung and roughly 4,800 at the
+ * 2576-pixel one — and it is an **estimate**, which is the word used
+ * everywhere on purpose. `captures.bytes` is what it is sanity-checked
+ * against (§1.7): a file whose size is wildly out of step with its dimensions
+ * is the signal that a picture was not what the numbers said.
+ */
+const TOKENS_PER_PIXEL_DIVISOR = 750;
+/**
+ * What looking at a picture of these dimensions is estimated to cost.
+ *
+ * Takes dimensions and nothing else — no tier, no configuration, no options
+ * object with a divisor in it. That signature is the enforcement of §6.4:
+ * there is no position in which an operator's value could arrive.
+ */
+export function estimateTokens(width, height) {
+    return Math.ceil((width * height) / TOKENS_PER_PIXEL_DIVISOR);
+}

package/dist/src/cli/adapter.js

@@ -0,0 +1,233 @@
+import { OPERATION_COMMANDS } from "./commands.js";
+/**
+ * The command line as an adapter: a thin shell over one service call.
+ *
+ * `SCHEMA.md` §5.1: "The command line is a full route in, and it is worth
+ * building even if no agent ever calls it. It is the cheapest available proof
+ * that the rules live in one place rather than inside a tool handler — a rule
+ * inside a handler is a rule that holds on one route and nowhere else."
+ *
+ * ── What this file may and may not do ───────────────────────────────────
+ *
+ * It resolves an argument vector into arguments, calls **one** operation, and
+ * shapes the outcome for a terminal. It reaches no database and no guard: it
+ * is handed a {@link BrokerService} rather than finding one, so there is no
+ * store handle in scope to be tempted by. Every rule that decides whether an
+ * operation is allowed lives behind that seam, or it holds on this route and
+ * not the others (`CLAUDE.md`).
+ *
+ * §5.2 is the consequence worth stating because it surprises people once: in
+ * process, **any command that goes through arbitration performs the lazy
+ * sweep** — so a listing command can close somebody else's lapsed tabs. That
+ * is correct, and it is why no command reads the tables directly.
+ */
+/** Exit codes, chosen so opposite responses are distinguishable (§5.6). */
+export const EXIT = {
+    /**
+     * Accepted — **including queued**. §5.6 is explicit: "queuing is an
+     * outcome, not a failure". A caller that treated a queue place as an error
+     * would abandon exactly the wait the queue exists to make orderly.
+     */
+    accepted: 0,
+    /** Something this service did not anticipate. */
+    unexpected: 1,
+    /** The command itself was malformed. */
+    malformed: 2,
+    /**
+     * Refused by a rule — distinct, "because a refusal is the service
+     * working". A caller can retry a refusal intelligently; it cannot retry a
+     * typo.
+     */
+    refused: 3,
+    /** Not configured. */
+    notConfigured: 4,
+};
+/**
+ * Fields never printed by any command, on any stream, in any mode.
+ *
+ * §5.6: "**The lease key is never printed by any command**, including in
+ * error output and in the machine-readable mode, where the field is absent
+ * rather than masked." Absent rather than masked is the specification — a
+ * masked field tells a reader a key exists and is being withheld, which is an
+ * invitation, and a masked value is one careless format change away from
+ * being the real one.
+ */
+export const NEVER_PRINTED = ['lease_key', 'leaseKey', 'key'];
+/**
+ * Strip anything that must never be printed, at every depth.
+ *
+ * Applied on the way out rather than trusted not to be included, because the
+ * shape of an operation's result belongs to the operation and this route
+ * cannot know what a later row will put in one. A rule enforced at the exit
+ * holds for results that did not exist when it was written.
+ */
+export function withoutSecrets(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => withoutSecrets(entry));
+    }
+    if (value !== null && typeof value === 'object') {
+        const output = {};
+        for (const [key, entry] of Object.entries(value)) {
+            if (NEVER_PRINTED.includes(key)) {
+                continue;
+            }
+            output[key] = withoutSecrets(entry);
+        }
+        return output;
+    }
+    return value;
+}
+/**
+ * Turn the words after a command into arguments.
+ *
+ * `--name value` and `--name=value`, plus bare `--flag` for a boolean. No
+ * argument-parsing library: the manifest carries exactly one runtime
+ * dependency and a command line of this shape does not need a second
+ * (`MILESTONES.md`'s binding, and a framework here would be a design
+ * regression rather than a convenience).
+ *
+ * Keys are normalised from the terminal's spelling to the service's:
+ * `--session-id` becomes `session_id`, so a caller types what a terminal
+ * reads and the service receives what §3 names.
+ *
+ * ── Why a value is not rejected merely for starting with `--` ───────────
+ *
+ * A lease key is 32 random bytes rendered as base64url, and **the base64url
+ * alphabet contains `-`**, so about one key in 6,250 begins with `--`. Read
+ * as "the next word looks like a flag, so this one is a boolean", such a key
+ * is swallowed: `lease_key` arrives as `true`, the key never reaches the
+ * service, and the caller is told its key is missing — for a key it holds and
+ * typed correctly. It is a real defect on the shipped route rather than a
+ * curiosity, because there is no way for that caller to succeed and nothing
+ * in the message points at the cause.
+ *
+ * So "looks like a flag" is decided by **shape rather than by the leading
+ * dashes**: a flag's name is lower-case letters, digits and hyphens, which is
+ * every option this command line actually has. A base64url key contains
+ * upper-case letters or underscores, or is far longer than any option name,
+ * so it fails that test and is correctly read as a value. A genuine adjacent
+ * flag — `broker read --lease-key K --json` — still parses as two arguments,
+ * because `json` matches the shape.
+ *
+ * This is deliberately a **narrow** rule and not an argument-parsing library:
+ * it separates the two cases that actually occur without adding a dependency
+ * the manifest's one-runtime-dependency binding forbids.
+ */
+export function parseArguments(rest) {
+    const parsed = {};
+    for (let index = 0; index < rest.length; index += 1) {
+        const word = rest[index];
+        if (word === undefined || !word.startsWith('--')) {
+            continue;
+        }
+        const body = word.slice(2);
+        const equals = body.indexOf('=');
+        if (equals !== -1) {
+            parsed[normaliseKey(body.slice(0, equals))] = body.slice(equals + 1);
+            continue;
+        }
+        const next = rest[index + 1];
+        if (next === undefined || looksLikeFlag(next)) {
+            parsed[normaliseKey(body)] = true;
+            continue;
+        }
+        parsed[normaliseKey(body)] = next;
+        index += 1;
+    }
+    return parsed;
+}
+function normaliseKey(key) {
+    return key.replaceAll('-', '_');
+}
+/**
+ * Whether a word is an option rather than a value that begins with dashes.
+ *
+ * See {@link parseArguments} for why the leading `--` cannot decide this on
+ * its own. The name after the dashes must look like an option name: lower-case
+ * letters and digits, hyphen-separated, and non-empty. `--json` and
+ * `--full-page` match; a base64url lease key such as
+ * `--SgvBJ5qVwX2T8B9XEhfQHsD2iZ2maYPC0sflBlFjg` does not, because of its
+ * upper-case letters.
+ */
+function looksLikeFlag(word) {
+    if (!word.startsWith('--')) {
+        return false;
+    }
+    const body = word.slice(2);
+    // `--name=value` is unambiguously an option however its value is spelled.
+    const name = body.indexOf('=') === -1 ? body : body.slice(0, body.indexOf('='));
+    return /^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(name);
+}
+/**
+ * The waivers this route carries (§5.5).
+ *
+ * Every one of these is a **command that exists** with no service operation
+ * behind it, which is why it is a written waiver rather than an absence: the
+ * command line genuinely offers `snapshot`, `doctor`, `login` and `init`, and
+ * none of them is a §3 operation to be at parity about.
+ *
+ * They do not name §3 operations, so nothing here is exempting this route
+ * from an operation it should offer — the waiver rule in the runner refuses
+ * that, and this list is deliberately empty of operation names for that
+ * reason. It is kept as prose the reviewer can read rather than being
+ * discarded, because "quietly absent from the matrix" is the failure
+ * `MILESTONES.md` names.
+ */
+export const CLI_COMMAND_WAIVERS = [
+    {
+        command: 'snapshot',
+        reason: 'Writes the operations document and exits. It performs no service operation and refuses nothing, so it has nothing to be at parity with.',
+    },
+    {
+        command: 'doctor',
+        reason: 'Reports preconditions and exits with a distinct code. It is a readiness check rather than an operation, and refuses no caller.',
+    },
+    {
+        command: 'login',
+        reason: 'Hands a browser to a person to sign in to. A person drives it, no lease is granted, and the tool surface deliberately has no equivalent.',
+    },
+    {
+        command: 'init',
+        reason: 'Shows the setup handshake report. Every spawn performs the handshake anyway, so the command causes no effect of its own.',
+    },
+];
+/**
+ * Operations this route does not offer, with the reason each is absent.
+ *
+ * **Empty, and that is the claim.** §5.3: every §3 operation has a command,
+ * so parity is real rather than claimed. The array exists so that a later row
+ * removing a command has somewhere to write down why — and so the runner's
+ * waiver rule has something to check rather than an absence to interpret.
+ */
+export const CLI_OPERATION_WAIVERS = [];
+/** Every operation this route offers — all ten, from the command table. */
+export const CLI_OPERATIONS = OPERATION_COMMANDS.map((command) => command.operation);
+/**
+ * The command-line adapter.
+ *
+ * `readOnly` is false because this route performs writes, and that
+ * declaration is what makes the waiver rule bite: a route exposing a write
+ * operation may not waive an operation any rule can refuse
+ * (`MILESTONES.md`). Declaring it read-only to buy waivers would be the
+ * loophole, so the declaration is made honestly and the waiver list is empty.
+ */
+export const cliAdapter = {
+    id: 'cli',
+    description: 'The command line. In process, because there is nothing else for a command to talk to.',
+    readOnly: false,
+    operations: CLI_OPERATIONS,
+    waivers: CLI_OPERATION_WAIVERS,
+    invoke: async (service, operation, input) => {
+        // The route's own vocabulary is an argument vector. Anything else is a
+        // caller reaching past the transport, so it is refused rather than
+        // coerced — a shell only ever produces an array of strings.
+        if (!Array.isArray(input) || input.some((word) => typeof word !== 'string')) {
+            throw new TypeError('the command-line adapter takes an argument vector');
+        }
+        return service.perform({
+            operation,
+            adapter: 'cli',
+            arguments: parseArguments(input),
+        });
+    },
+};