browser-broker 0.1.0

package/dist/src/tool/conformance-driver.js

@@ -0,0 +1,184 @@
+import { toolStdioAdapter } from "./adapter.js";
+import { encodeMessage, METHODS, decodeMessage } from "./protocol.js";
+import { serveSession } from "./session.js";
+import { TOOL_DEFINITIONS } from "./tools.js";
+/**
+ * How the conformance suite drives the tool surface.
+ *
+ * ── It goes through the real session loop, and that is the whole point ───
+ *
+ * The command line's driver builds an argv and calls the real entry point.
+ * This one builds a **line on the wire** and runs the real
+ * {@link serveSession}, then reads the outcome back out of the line that came
+ * off it. So every part of this route that could hold a rule of its own is
+ * exercised: the framing, the decode, the method dispatch, the tool lookup,
+ * the argument shaping, and the never-returned rule.
+ *
+ * **The hollow version is worth naming so nobody reinvents it.** A driver
+ * that called `toolStdioAdapter.invoke` directly — or worse, called the
+ * service — would produce a green matrix while testing none of that, and it
+ * would pass. That is the "tested a local copy of the logic so the shipped
+ * code was never exercised" failure this repository has caught before.
+ *
+ * ── One session per case, because that is the deployment ────────────────
+ *
+ * `MILESTONES.md` #27: the service is spawned by its caller, serves that
+ * session and exits with it. A driver that kept one long-lived session across
+ * the whole matrix would be measuring an arrangement this design does not
+ * have, and it would hide any state accidentally held between calls — the one
+ * bug this lifecycle is chosen to make impossible. So each case gets its own
+ * session, opened and ended around the single call.
+ *
+ * The process boundary is deliberately **not** crossed here: the matrix runs
+ * in process, and a smaller spawned smoke subset proves the wiring
+ * separately.
+ */
+/** Turn a neutral case input into this route's own vocabulary: a tool call. */
+export function toolCallFor(testCase) {
+    const tool = TOOL_DEFINITIONS.find((entry) => entry.operation === testCase.operation);
+    if (tool === undefined) {
+        throw new Error(`the tool surface has no tool for "${testCase.operation}"`);
+    }
+    const args = {};
+    for (const [key, value] of Object.entries(testCase.input)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        // This transport carries JSON, so unlike the command line it can express
+        // a structure. What it cannot express is a value with no JSON
+        // representation, and coercing one would put something meaningless on the
+        // wire and then assert against whatever came back — a comparison that
+        // runs, means nothing, and passes.
+        if (typeof value === 'function' || typeof value === 'symbol' || typeof value === 'bigint') {
+            throw new TypeError(`case "${testCase.name}" gives ${key} a value the tool surface cannot carry`);
+        }
+        // The case table is authored in the service's own spelling, and the
+        // arguments the tool takes are the same names (§3), so this is a copy
+        // rather than a translation. Where a route's spelling differs — the
+        // command line's hyphens — the translation lives in that route's driver.
+        args[key] = value;
+    }
+    return { name: tool.name, arguments: args };
+}
+/**
+ * Read the outcome back out of the line the session wrote.
+ *
+ * A refusal arrives as a **successful response carrying a refusal**, never as
+ * a protocol error (`session.ts`), so a protocol error here is a real failure
+ * of this route rather than something to reinterpret as a refusal. Raising it
+ * is what keeps the two apart in the matrix: a route that reported refusals
+ * as protocol errors would be a route with its own rules, which is the exact
+ * thing #30 asserts against.
+ */
+export function outcomeFrom(line) {
+    if (line === undefined) {
+        throw new Error('the session wrote no response');
+    }
+    const decoded = JSON.parse(line);
+    if (decoded === null || typeof decoded !== 'object') {
+        throw new Error('the session wrote something that is not a message');
+    }
+    const message = decoded;
+    if (message['error'] !== undefined) {
+        const error = message['error'];
+        throw new Error(`the tool surface answered with a protocol error (${String(error.code)}): ${String(error.message)}`);
+    }
+    const result = message['result'];
+    if (result === null || typeof result !== 'object') {
+        throw new Error('the response carries no result');
+    }
+    // The outcome is read out of `structuredContent`, which is where a
+    // `tools/call` result carries its machine-readable half. **This is not a
+    // second spelling of the domain object** — the result root holds `content`,
+    // `structuredContent` and `isError`, which is the specification's shape and
+    // the only shape a client can read.
+    //
+    // Reading it here does not make the wire shape *asserted*: this function
+    // normalises a route's answer back into a neutral outcome so the matrix can
+    // compare two routes, and it would go on doing that faithfully if `content`
+    // vanished tomorrow. That is exactly how the missing content array shipped
+    // — the suite compared outcomes at the service layer and both routes agreed.
+    // The shape itself is asserted by its own test, against the bytes.
+    const structured = result['structuredContent'];
+    if (structured === null || typeof structured !== 'object') {
+        throw new Error('the result carries no structured content');
+    }
+    const record = structured;
+    if (record['outcome'] === 'accepted') {
+        return { outcome: 'accepted', value: (record['value'] ?? {}) };
+    }
+    if (record['outcome'] === 'refused') {
+        return {
+            outcome: 'refused',
+            code: String(record['code']),
+            rule: String(record['rule']),
+            // The sentence is worded for this transport and is never compared
+            // across routes (§3.14), so it is carried but not read back for the
+            // comparison.
+            message: typeof record['message'] === 'string' ? record['message'] : '',
+            ...(record['details'] === undefined
+                ? {}
+                : { details: record['details'] }),
+        };
+    }
+    throw new Error(`the result names no outcome: ${line}`);
+}
+/**
+ * One line in, as an async iterable, because that is what the loop reads.
+ *
+ * The loop's input is asynchronous because a real standard input is; a
+ * driver supplying one line has nothing to wait for, so this adapts a value
+ * to the shape rather than pretending to be asynchronous.
+ */
+function oneLine(line) {
+    return {
+        [Symbol.asyncIterator]: () => {
+            let sent = false;
+            return {
+                next: () => {
+                    if (sent) {
+                        return Promise.resolve({ done: true, value: undefined });
+                    }
+                    sent = true;
+                    return Promise.resolve({ done: false, value: line });
+                },
+            };
+        },
+    };
+}
+/** The tool surface's conformance driver. */
+export const toolStdioConformanceDriver = {
+    adapter: toolStdioAdapter,
+    run: async (service, testCase, observe) => {
+        const written = [];
+        // Built through the surface's own encoder rather than by hand, because
+        // the framing is the thing under test as much as the dispatch is.
+        const request = encodeMessage({
+            id: 1,
+            method: METHODS.callTool,
+            params: toolCallFor(testCase),
+        });
+        // Confirm the line this driver built is one the surface's own decoder
+        // accepts. Without this a malformed request would be answered with a
+        // protocol error, `outcomeFrom` would raise, and the case would fail with
+        // a message about the surface rather than about the driver.
+        const decoded = decodeMessage(request);
+        if (decoded.kind !== 'request') {
+            // Every line this driver builds carries an identifier and a method, so
+            // neither of the other two readings is reachable from here. The reason
+            // is named anyway rather than reported as a bare kind, because the
+            // whole point of the check is that a driver defect should say so.
+            const why = decoded.kind === 'malformed' ? decoded.why : 'it decoded as a notification';
+            throw new Error(`the driver built a line the surface rejects: ${why}`);
+        }
+        await serveSession(oneLine(request), {
+            service,
+            streams: { write: (line) => written.push(line) },
+        });
+        return {
+            outcome: outcomeFrom(written[0]),
+            driverCalls: observe.driverCalls(),
+            liveClaimCount: observe.liveClaimCount(),
+        };
+    },
+};

package/dist/src/tool/protocol.js

@@ -0,0 +1,310 @@
+/**
+ * The wire format the tool surface speaks, implemented directly.
+ *
+ * ── Why this is written out rather than taken from a package ────────────
+ *
+ * `MILESTONES.md`'s binding for this row: no runtime dependency is added for
+ * it, because the protocol is a documented wire format and a framework would
+ * be a design regression rather than a convenience. The whole of what a
+ * caller needs is here: newline-delimited JSON objects on standard input and
+ * standard output, an integer or string identifier correlating a response
+ * with its request, and a small fixed set of method names.
+ *
+ * The cost of that choice is stated rather than implied: this implements the
+ * subset this service uses — the handshake, listing the tools and calling one
+ * — and nothing else. A caller sending a method outside that set gets an
+ * explicit `method_not_found` rather than silence, which is the part that
+ * makes the subset honest instead of merely small.
+ *
+ * ── The envelope is JSON-RPC 2.0, because a client will not speak anything ─
+ *
+ * The subset above was, for a time, *only* those last two methods, framed as
+ * bare JSON objects. That was reachable by a program written against this
+ * file and by nothing else: a Model Context Protocol client opens with
+ * `initialize`, waits for the server's `protocolVersion`, `capabilities` and
+ * `serverInfo`, sends `notifications/initialized`, and only then asks what
+ * tools exist. Against a surface with no `initialize` the very first message
+ * is answered `method_not_found` and the client hangs up — so ten working,
+ * conformance-proven tools sat behind a doorway that did not open.
+ *
+ * So the envelope here is the real one: `jsonrpc: "2.0"` on every message,
+ * the identifier echoed, `result` exclusive-or `error`, and errors carrying
+ * JSON-RPC's *numeric* codes. Implemented against Model Context Protocol
+ * revision {@link PROTOCOL_VERSION}
+ * (https://modelcontextprotocol.io/specification/2025-06-18).
+ *
+ * ── Two code spaces, deliberately, and both of them travel ──────────────
+ *
+ * JSON-RPC requires a small fixed set of integers. This surface already had a
+ * vocabulary of its own — `method_not_found`, `tool_not_found`,
+ * `malformed_call`, `unexpected_failure` — and those distinctions are
+ * load-bearing rather than decorative: `SCHEMA.md` and two build checks read
+ * them by name, and the paragraph on {@link ProtocolError} explains why a
+ * caller must be able to tell a typo from a capacity refusal.
+ *
+ * Collapsing the vocabulary into five integers would have thrown that away to
+ * satisfy a transport. So **both travel**: {@link ProtocolError.code} keeps
+ * the name, and {@link toJsonRpcCode} maps it onto the integer the transport
+ * requires. A generic client reads the integer and behaves correctly; a
+ * caller who knows this service reads the name and keeps every distinction it
+ * had before. The mapping is the only thing that is new, and it is one
+ * function rather than a rewrite.
+ *
+ * ── Framing: one JSON object per line ───────────────────────────────────
+ *
+ * A line is a message. That is the whole framing rule, and it is chosen over
+ * a length-prefixed header for a reason worth keeping: a line-delimited
+ * stream is readable by a person watching it, debuggable with ordinary text
+ * tools, and has exactly one failure mode — a message containing a raw
+ * newline. {@link encodeMessage} is where that is prevented, by serialising
+ * without pretty-printing, and {@link decodeMessage} refuses a line it cannot
+ * parse rather than skipping it silently.
+ */
+/** The JSON-RPC version string every message on this surface carries. */
+export const JSONRPC_VERSION = '2.0';
+/**
+ * The Model Context Protocol revision this surface implements.
+ *
+ * Named as a constant because it is answered to a client during negotiation
+ * and asserted by a test; a version that lived only in a string literal
+ * inside a handler would drift from the one the documentation claims.
+ */
+export const PROTOCOL_VERSION = '2025-06-18';
+/**
+ * The revisions this surface will agree to speak.
+ *
+ * Ordered newest first, which is what makes {@link negotiateProtocolVersion}
+ * able to answer "the newest thing we both know" without a second list. A
+ * revision is added here only when this surface has actually been made to
+ * speak it — the point of the list is that it is a claim, not a wish.
+ */
+export const SUPPORTED_PROTOCOL_VERSIONS = [PROTOCOL_VERSION, '2025-03-26'];
+/**
+ * JSON-RPC's own error codes, which are integers and are not negotiable.
+ *
+ * These are the transport's, not this service's. They exist so a client that
+ * has never heard of this service still behaves correctly — retry, report,
+ * give up — and the names above are what a caller that *has* heard of it
+ * reads instead. See {@link toJsonRpcCode} for why both travel.
+ */
+export const JSONRPC_ERROR_CODES = {
+    parseError: -32700,
+    invalidRequest: -32600,
+    methodNotFound: -32601,
+    invalidParams: -32602,
+    internalError: -32603,
+};
+/**
+ * This surface's refusal vocabulary, mapped onto the transport's integers.
+ *
+ * **The mapping is many-to-one and that is the point.** `tool_not_found` and
+ * `method_not_found` are genuinely different facts — one means the caller
+ * mistyped a tool, the other that it spoke a method this surface does not
+ * implement — and JSON-RPC has one integer for both. Rather than pick a
+ * winner, the name survives on {@link ProtocolError.code} and the integer is
+ * derived here. Nothing reading the name loses a distinction; nothing reading
+ * the integer sees a code it does not recognise.
+ *
+ * An unrecognised name maps to `internalError`, which is the honest answer:
+ * a code this function has not been taught about is, from the transport's
+ * point of view, this surface failing to describe itself.
+ */
+export function toJsonRpcCode(code) {
+    switch (code) {
+        case 'method_not_found':
+        case 'tool_not_found':
+            return JSONRPC_ERROR_CODES.methodNotFound;
+        case 'malformed_message':
+            return JSONRPC_ERROR_CODES.invalidRequest;
+        case 'malformed_call':
+        case 'unsupported_protocol_version':
+            return JSONRPC_ERROR_CODES.invalidParams;
+        default:
+            return JSONRPC_ERROR_CODES.internalError;
+    }
+}
+/**
+ * Agree a revision with the caller.
+ *
+ * The rule the specification gives is short: answer with the caller's own
+ * revision when this surface speaks it, and otherwise answer with the newest
+ * one it does speak. **The second branch is not a failure** — a client asking
+ * for something newer than this surface knows is told what is on offer and
+ * decides for itself whether to continue, which is the difference between a
+ * negotiation and a rejection. So this returns a version in every case and
+ * never throws: a handshake that crashed on an unfamiliar version string
+ * would break on the next revision of the specification rather than on
+ * anything wrong with the caller.
+ */
+export function negotiateProtocolVersion(requested) {
+    if (typeof requested === 'string' && SUPPORTED_PROTOCOL_VERSIONS.includes(requested)) {
+        return requested;
+    }
+    return PROTOCOL_VERSION;
+}
+/** The methods this surface answers. Anything else is `method_not_found`. */
+export const METHODS = {
+    /** Open the session: negotiate a revision and describe the server. */
+    initialize: 'initialize',
+    /** Enumerate the tools, with their descriptions and argument schemas. */
+    listTools: 'tools/list',
+    /** Call one tool by name. */
+    callTool: 'tools/call',
+};
+/**
+ * The notifications this surface accepts — and answers with silence.
+ *
+ * `notifications/initialized` is the client saying the handshake is complete.
+ * There is nothing to do with it and nothing to send back; accepting it
+ * without replying is the whole of the requirement.
+ *
+ * `notifications/cancelled` is listed because a client may send it at any
+ * time and a surface that treated it as an unknown *method* would try to
+ * answer a notification — the one thing a notification must never draw. This
+ * surface answers a call when it finishes, so there is no work to interrupt;
+ * ignoring it is both correct and complete.
+ */
+export const NOTIFICATIONS = {
+    initialized: 'notifications/initialized',
+    cancelled: 'notifications/cancelled',
+};
+/**
+ * Serialise a message to one line.
+ *
+ * `JSON.stringify` without an indent argument emits no newline of its own,
+ * and every newline inside a string value is escaped as `\n` by the
+ * serialiser, so the result is guaranteed to be a single line. That guarantee
+ * is the framing, so it is asserted by a test rather than assumed here.
+ */
+export function encodeMessage(message) {
+    return JSON.stringify(withEnvelope(message));
+}
+/**
+ * Put the JSON-RPC envelope on a message on its way out.
+ *
+ * Two properties are enforced here rather than trusted to every call site,
+ * because both are the kind of thing that is right nine times and wrong once:
+ *
+ * **`jsonrpc: "2.0"` leads.** Key order is not semantically meaningful, but
+ * this stream is read by people as well as programs — that is the stated
+ * reason the framing is lines rather than length prefixes — and a message
+ * whose first field names the protocol is one a reader can identify at a
+ * glance.
+ *
+ * **`result` and `error` are exclusive.** JSON-RPC requires exactly one, and
+ * a response carrying both is the ambiguity a client cannot resolve. So an
+ * error wins and `result` is dropped, rather than both being written and the
+ * contradiction shipped; and an error is rewritten to carry the transport's
+ * integer in `code` with this surface's own name preserved beside it, which
+ * is the whole of the two-code-spaces bargain in {@link toJsonRpcCode}.
+ */
+function withEnvelope(message) {
+    if ('method' in message) {
+        return { jsonrpc: JSONRPC_VERSION, ...message };
+    }
+    if (message.error !== undefined) {
+        return {
+            jsonrpc: JSONRPC_VERSION,
+            id: message.id,
+            error: {
+                code: toJsonRpcCode(message.error.code),
+                message: message.error.message,
+                // The name is kept, in the place JSON-RPC reserves for exactly this.
+                // A caller reading `error.code` gets the integer it expects; one that
+                // knows this service reads the name and keeps the distinction the
+                // integer cannot carry.
+                data: { code: message.error.code },
+            },
+        };
+    }
+    return { jsonrpc: JSONRPC_VERSION, id: message.id, result: message.result };
+}
+/**
+ * Read one line as a request.
+ *
+ * **A malformed line is reported, never skipped.** A surface that ignored
+ * what it could not parse would leave a caller waiting forever for a response
+ * to a message the surface decided not to mention — and from the caller's
+ * side that is indistinguishable from a hang. So this returns a description
+ * of the problem, and the loop above answers with it where there is an
+ * identifier to answer to.
+ *
+ * ── Why the id KEY's presence is checked separately from its value ───────
+ *
+ * `record['id']` on an object with no `id` property and `record['id']` on
+ * one with `id: null` are both `undefined` in JavaScript, so a check that
+ * reads only the value cannot tell "there is no id to answer to" from "there
+ * is an id, and it is unusable". Those are different situations: the first
+ * is a notification-shaped line with genuinely nobody to answer; the second
+ * is a request-shaped line whose id this surface cannot echo back, but can
+ * still answer with `id: null` — JSON-RPC's own way of saying "I received
+ * this, and could not identify it". Losing that distinction is what let a
+ * caller sending `id: null` or `id: true` — a malformed request, not a
+ * notification — be read as a notification and dropped, indistinguishable
+ * from a hang.
+ */
+export function decodeMessage(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return { kind: 'malformed', id: undefined, why: 'the line is not JSON' };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { kind: 'malformed', id: undefined, why: 'a message is a JSON object' };
+    }
+    const record = parsed;
+    const hasIdKey = 'id' in record;
+    const rawId = record['id'];
+    const id = typeof rawId === 'number' || typeof rawId === 'string' ? rawId : undefined;
+    const method = record['method'];
+    const params = record['params'];
+    const paramsAreWrong = params !== undefined && (params === null || typeof params !== 'object');
+    // **A message with no id KEY at all but a method is a NOTIFICATION, not a
+    // malformed message**, and reading it as the latter is how a surface ends
+    // up either answering one or refusing the handshake that follows it. The
+    // key's absence — not merely an unusable value — is the signal, so it is
+    // tested before anything is concluded from it.
+    if (!hasIdKey && typeof method === 'string') {
+        if (paramsAreWrong) {
+            // Nobody to answer — a notification has no identifier by construction —
+            // so the loop above logs this rather than replying to it.
+            return { kind: 'malformed', id: undefined, why: 'params, when present, is an object' };
+        }
+        return {
+            kind: 'notification',
+            notification: {
+                method,
+                ...(params === undefined ? {} : { params: params }),
+            },
+        };
+    }
+    if (id === undefined) {
+        // The id key is present (checked above) but its value is neither a
+        // number nor a string — `null`, `true`, an object, an array. There is an
+        // id to answer to; this surface simply cannot echo the caller's own
+        // value back, so it answers with `id: null` rather than staying silent.
+        // Absent the id key entirely, this line would have taken the
+        // notification branch above and never reached here.
+        return {
+            kind: 'malformed',
+            id: hasIdKey ? null : undefined,
+            why: 'a message carries an id, which is a number or a string',
+        };
+    }
+    if (typeof method !== 'string') {
+        return { kind: 'malformed', id, why: 'a message carries a method, which is a string' };
+    }
+    if (paramsAreWrong) {
+        return { kind: 'malformed', id, why: 'params, when present, is an object' };
+    }
+    return {
+        kind: 'request',
+        request: {
+            id,
+            method,
+            ...(params === undefined ? {} : { params: params }),
+        },
+    };
+}