@variance-authority/mcp 0.1.0

package/dist/observability-subject.d.ts

@@ -0,0 +1,22 @@
+import type { EyesArchive } from '@variance-authority/eyes';
+import type { PresentationReport } from '@variance-authority/presentation';
+import type { RunReport } from '@variance-authority/report';
+import type { ScenarioArchiveManifest } from '@variance-authority/scenario/archive';
+import type { ExecutionIndex } from '@variance-authority/sense/test-selection';
+import type { VantageState } from '@variance-authority/vantage';
+/**
+ * Independently produced observability domains supplied to one MCP connection.
+ *
+ * Every field is optional because no instrument may stand in for another. A
+ * missing field means no producer supplied that domain; a present empty value
+ * means its producer measured an empty set.
+ */
+export interface ObservabilitySubject {
+    readonly report?: RunReport;
+    readonly presentations?: readonly PresentationReport[];
+    readonly execution?: ExecutionIndex;
+    readonly vantage?: VantageState;
+    readonly eyes?: EyesArchive;
+    readonly scenarios?: readonly ScenarioArchiveManifest[];
+}
+//# sourceMappingURL=observability-subject.d.ts.map

package/dist/observability-subject.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=observability-subject.js.map

package/dist/observability-subject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability-subject.js","sourceRoot":"","sources":["../src/observability-subject.ts"],"names":[],"mappings":"","sourcesContent":["import type { EyesArchive } from '@variance-authority/eyes';\nimport type { PresentationReport } from '@variance-authority/presentation';\nimport type { RunReport } from '@variance-authority/report';\nimport type { ScenarioArchiveManifest } from '@variance-authority/scenario/archive';\nimport type { ExecutionIndex } from '@variance-authority/sense/test-selection';\nimport type { VantageState } from '@variance-authority/vantage';\n\n/**\n * Independently produced observability domains supplied to one MCP connection.\n *\n * Every field is optional because no instrument may stand in for another. A\n * missing field means no producer supplied that domain; a present empty value\n * means its producer measured an empty set.\n */\nexport interface ObservabilitySubject {\n  readonly report?: RunReport;\n  readonly presentations?: readonly PresentationReport[];\n  readonly execution?: ExecutionIndex;\n  readonly vantage?: VantageState;\n  readonly eyes?: EyesArchive;\n  readonly scenarios?: readonly ScenarioArchiveManifest[];\n}\n"]}

package/dist/presentation.d.ts

@@ -0,0 +1,6 @@
+import type { PresentationSignalRecord, RunReport } from '@variance-authority/report';
+/** Presentation consequence in the shared text vocabulary used by CLI and MCP. */
+export declare function presentationSummary(report: RunReport): readonly string[];
+/** One subject's durable presentation consequence, without re-running analysis. */
+export declare function describePresentation(signal: PresentationSignalRecord): readonly string[];
+//# sourceMappingURL=presentation.d.ts.map

package/dist/presentation.js

@@ -0,0 +1,64 @@
+/** Presentation consequence in the shared text vocabulary used by CLI and MCP. */
+export function presentationSummary(report) {
+    const observed = report.observations.filter((entry) => entry.signals?.presentation !== undefined);
+    if (observed.length === 0)
+        return [];
+    const comparable = observed.filter((entry) => entry.signals.presentation.verdict !== 'incomparable');
+    const incomparable = observed.length - comparable.length;
+    const effects = comparable.flatMap((entry) => {
+        const signal = entry.signals.presentation;
+        return signal.verdict === 'incomparable' ? [] : signal.effects;
+    });
+    const counts = new Map();
+    for (const effect of effects)
+        counts.set(effect.transition, (counts.get(effect.transition) ?? 0) + 1);
+    const changed = comparable.filter((entry) => entry.signals.presentation.verdict === 'changed').length;
+    return [
+        `presentation impact: ${counts.get('introduced') ?? 0} introduced, ` +
+            `${counts.get('resolved') ?? 0} resolved, ${counts.get('persisted') ?? 0} persisted ` +
+            `across ${changed} changed subject(s); ${comparable.length} compared, ${incomparable} incomparable. ` +
+            'Independent of the regression verdict.',
+    ];
+}
+/** One subject's durable presentation consequence, without re-running analysis. */
+export function describePresentation(signal) {
+    if (signal.verdict === 'incomparable') {
+        return [`presentation: incomparable — ${signal.because}`];
+    }
+    const information = signal.information;
+    const info = [
+        information.contentPreserved ? 'content preserved' : 'content changed',
+        delta('characters', information.characters.delta),
+        delta('elements', information.elements.delta),
+        delta('repeated objects', information.repeatedObjects.delta),
+    ].filter((part) => part !== '');
+    if (signal.effects.length === 0) {
+        return [`presentation: ${signal.verdict} — ${info.join(', ')}`];
+    }
+    return [
+        `presentation: ${signal.verdict} — ${info.join(', ')}`,
+        ...signal.effects.flatMap(effectLines),
+    ];
+}
+function effectLines(effect) {
+    const identity = `  [${effect.transition}] ${effect.rule} at ${effect.owner}` +
+        (effect.contract === undefined ? '' : ` (contract ${effect.contract})`);
+    if (effect.transition === 'introduced')
+        return [identity, evidenceLine('after', effect.after)];
+    if (effect.transition === 'resolved')
+        return [identity, evidenceLine('before', effect.before)];
+    return [identity, evidenceLine('before', effect.before), evidenceLine('after', effect.after)];
+}
+function evidenceLine(side, evidence) {
+    const measurements = Object.entries(evidence.measurements)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([name, value]) => `${name}=${value}`)
+        .join(', ');
+    return `    ${side} ${evidence.finding}${measurements === '' ? '' : `: ${measurements}`}`;
+}
+function delta(name, value) {
+    if (value === 0)
+        return '';
+    return `${name} ${value > 0 ? '+' : ''}${value}`;
+}
+//# sourceMappingURL=presentation.js.map

package/dist/presentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentation.js","sourceRoot":"","sources":["../src/presentation.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  PresentationEffectEvidence,\n  PresentationEffectRecord,\n  PresentationSignalRecord,\n  RunReport,\n} from '@variance-authority/report';\n\n/** Presentation consequence in the shared text vocabulary used by CLI and MCP. */\nexport function presentationSummary(report: RunReport): readonly string[] {\n  const observed = report.observations.filter((entry) => entry.signals?.presentation !== undefined);\n  if (observed.length === 0) return [];\n  const comparable = observed.filter((entry) => entry.signals!.presentation!.verdict !== 'incomparable');\n  const incomparable = observed.length - comparable.length;\n  const effects = comparable.flatMap((entry) => {\n    const signal = entry.signals!.presentation!;\n    return signal.verdict === 'incomparable' ? [] : signal.effects;\n  });\n  const counts = new Map<string, number>();\n  for (const effect of effects) counts.set(effect.transition, (counts.get(effect.transition) ?? 0) + 1);\n  const changed = comparable.filter((entry) => entry.signals!.presentation!.verdict === 'changed').length;\n\n  return [\n    `presentation impact: ${counts.get('introduced') ?? 0} introduced, ` +\n      `${counts.get('resolved') ?? 0} resolved, ${counts.get('persisted') ?? 0} persisted ` +\n      `across ${changed} changed subject(s); ${comparable.length} compared, ${incomparable} incomparable. ` +\n      'Independent of the regression verdict.',\n  ];\n}\n\n/** One subject's durable presentation consequence, without re-running analysis. */\nexport function describePresentation(signal: PresentationSignalRecord): readonly string[] {\n  if (signal.verdict === 'incomparable') {\n    return [`presentation: incomparable — ${signal.because}`];\n  }\n  const information = signal.information;\n  const info = [\n    information.contentPreserved ? 'content preserved' : 'content changed',\n    delta('characters', information.characters.delta),\n    delta('elements', information.elements.delta),\n    delta('repeated objects', information.repeatedObjects.delta),\n  ].filter((part) => part !== '');\n  if (signal.effects.length === 0) {\n    return [`presentation: ${signal.verdict} — ${info.join(', ')}`];\n  }\n  return [\n    `presentation: ${signal.verdict} — ${info.join(', ')}`,\n    ...signal.effects.flatMap(effectLines),\n  ];\n}\n\nfunction effectLines(effect: PresentationEffectRecord): readonly string[] {\n  const identity =\n    `  [${effect.transition}] ${effect.rule} at ${effect.owner}` +\n    (effect.contract === undefined ? '' : ` (contract ${effect.contract})`);\n  if (effect.transition === 'introduced') return [identity, evidenceLine('after', effect.after!)];\n  if (effect.transition === 'resolved') return [identity, evidenceLine('before', effect.before!)];\n  return [identity, evidenceLine('before', effect.before!), evidenceLine('after', effect.after!)];\n}\n\nfunction evidenceLine(side: string, evidence: PresentationEffectEvidence): string {\n  const measurements = Object.entries(evidence.measurements)\n    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))\n    .map(([name, value]) => `${name}=${value}`)\n    .join(', ');\n  return `    ${side} ${evidence.finding}${measurements === '' ? '' : `: ${measurements}`}`;\n}\n\nfunction delta(name: string, value: number): string {\n  if (value === 0) return '';\n  return `${name} ${value > 0 ? '+' : ''}${value}`;\n}\n"]}

package/dist/protocol.d.ts

@@ -0,0 +1,82 @@
+import type { EyesArchive } from '@variance-authority/eyes';
+import type { PresentationReport } from '@variance-authority/presentation';
+import type { RunReport } from '@variance-authority/report';
+import type { ScenarioArchiveManifest } from '@variance-authority/scenario/archive';
+import type { ExecutionIndex } from '@variance-authority/sense/test-selection';
+import type { VantageState } from '@variance-authority/vantage';
+import type { ObservabilitySubject } from './observability-subject.js';
+import type { Served, ToolInvocation } from './tools/tool.js';
+/**
+ * MCP over stdio, written out rather than depended on.
+ *
+ * The protocol is JSON-RPC 2.0 with newline-delimited framing and three methods
+ * that matter. Writing it is roughly a hundred lines; depending on an SDK to
+ * obtain those hundred lines costs a package, a version, and a transitive tree
+ * in a repository whose `core` went to the trouble of implementing SHA-256 to
+ * avoid depending on `node:crypto` (ADR-0006). The same judgement applies.
+ *
+ * The payoff is the same too: `handle` is a pure function from a request to a
+ * response. No sockets, no streams, no process. Every behaviour below can be
+ * asserted by calling it.
+ */
+export declare const PROTOCOL_VERSION = "2024-11-05";
+export declare const SERVER_NAME = "variance-authority";
+export declare const SERVER_VERSION = "0.0.0";
+export interface JsonRpcRequest {
+    readonly jsonrpc: '2.0';
+    /** Absent on a notification, which must not be answered. */
+    readonly id?: string | number;
+    readonly method: string;
+    readonly params?: Readonly<Record<string, unknown>>;
+}
+export interface JsonRpcResponse {
+    readonly jsonrpc: '2.0';
+    readonly id: string | number;
+    readonly result?: unknown;
+    readonly error?: {
+        readonly code: number;
+        readonly message: string;
+    };
+}
+/** The visual-report tools this package ships, as the thing `handle` is handed. */
+export declare const REPORTS: Served<RunReport>;
+/** The MCP surface for agents asking which named tests exercise source. */
+export declare const SOURCE_TESTS: Served<ExecutionIndex>;
+/**
+ * The MCP surface for an agent watching a suite that has not finished.
+ *
+ * The only served set that instructs. The other two answer about something that
+ * already exists; this one answers about a run somebody still has to start, and
+ * an agent that is not told the variable at the handshake starts it without one.
+ */
+export declare const VANTAGE: Served<VantageState>;
+/** The MCP surface for synchronously captured test attention. */
+export declare const EYES: Served<EyesArchive>;
+/** The MCP surface for full presentation graphs held by their caller. */
+export declare const PRESENTATIONS: Served<readonly PresentationReport[]>;
+/** The MCP surface for retained scenario executions. */
+export declare const SCENARIOS: Served<readonly ScenarioArchiveManifest[]>;
+/**
+ * The MCP surface that exposes every supplied observability domain without
+ * merging their evidence or inventing cross-domain identity.
+ */
+export declare const OBSERVABILITY: Served<ObservabilitySubject>;
+/**
+ * Answer one request. `null` means "no response", which is not the same as an
+ * empty one — a notification that gets answered is a protocol violation.
+ *
+ * `served` is required rather than defaulted to {@link REPORTS}. A default would
+ * infer its subject from whatever the second argument returns and then answer it
+ * with report tools, which is the class of mistake this file exists to make
+ * impossible: a server that speaks fluently about the wrong thing.
+ */
+export declare function handle<Subject>(request: JsonRpcRequest, subject: () => Subject, served: Served<Subject>, invocation?: ToolInvocation<Subject>): JsonRpcResponse | null;
+/**
+ * Newline-delimited framing.
+ *
+ * Buffers partial lines because a stdio chunk boundary falls wherever the OS
+ * puts it, not where a JSON value ends. Getting this wrong produces a parse
+ * error under load and never in a test.
+ */
+export declare function createLineReader(onLine: (line: string) => void): (chunk: string) => void;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.js

@@ -0,0 +1,186 @@
+import { EYES_TOOLS, OBSERVABILITY_TOOLS, PRESENTATION_TOOLS, SCENARIO_TOOLS, SOURCE_TEST_TOOLS, TOOLS, VANTAGE_TOOLS, } from './tools.js';
+import { attaching } from './tools/vantage-lines.js';
+/**
+ * MCP over stdio, written out rather than depended on.
+ *
+ * The protocol is JSON-RPC 2.0 with newline-delimited framing and three methods
+ * that matter. Writing it is roughly a hundred lines; depending on an SDK to
+ * obtain those hundred lines costs a package, a version, and a transitive tree
+ * in a repository whose `core` went to the trouble of implementing SHA-256 to
+ * avoid depending on `node:crypto` (ADR-0006). The same judgement applies.
+ *
+ * The payoff is the same too: `handle` is a pure function from a request to a
+ * response. No sockets, no streams, no process. Every behaviour below can be
+ * asserted by calling it.
+ */
+export const PROTOCOL_VERSION = '2024-11-05';
+export const SERVER_NAME = 'variance-authority';
+export const SERVER_VERSION = '0.0.0';
+/** The visual-report tools this package ships, as the thing `handle` is handed. */
+export const REPORTS = {
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+    tools: TOOLS,
+};
+/** The MCP surface for agents asking which named tests exercise source. */
+export const SOURCE_TESTS = {
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+    tools: SOURCE_TEST_TOOLS,
+};
+/**
+ * The MCP surface for an agent watching a suite that has not finished.
+ *
+ * The only served set that instructs. The other two answer about something that
+ * already exists; this one answers about a run somebody still has to start, and
+ * an agent that is not told the variable at the handshake starts it without one.
+ */
+export const VANTAGE = {
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+    tools: VANTAGE_TOOLS,
+    instructions: (state) => [
+        'This server watches a test run while it happens. It answers about a suite ' +
+            'in flight rather than about a report on disk, and none of it is limited ' +
+            'to visual tests.',
+        '',
+        'Ask `variance_run_signals` for where the run has got to and which test is ' +
+            'still going, and `variance_test_signals` for everything one test has ' +
+            'announced — in order, with the realm that said each, plus work that ' +
+            'started and never ended. Both answer while the test is still running, ' +
+            'which is what a runner cannot do from outside the worker.',
+        '',
+        attaching(state),
+    ].join('\n'),
+};
+/** The MCP surface for synchronously captured test attention. */
+export const EYES = {
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+    tools: EYES_TOOLS,
+};
+/** The MCP surface for full presentation graphs held by their caller. */
+export const PRESENTATIONS = {
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+    tools: PRESENTATION_TOOLS,
+};
+/** The MCP surface for retained scenario executions. */
+export const SCENARIOS = {
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+    tools: SCENARIO_TOOLS,
+};
+/**
+ * The MCP surface that exposes every supplied observability domain without
+ * merging their evidence or inventing cross-domain identity.
+ */
+export const OBSERVABILITY = {
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+    tools: OBSERVABILITY_TOOLS,
+    instructions: () => [
+        'This connection can expose visual reports, full presentation readings and durable signals, runtime journeys, ' +
+            'live events, Eyes attention and retained scenarios. Start with `variance_observability` ' +
+            'to learn which independent evidence domains were supplied.',
+        '',
+        'Unavailable evidence is not an empty measurement. Cross-domain answers join only on ' +
+            'exact identities emitted by both producers. `variance_testing_surface` reports replay ' +
+            'candidates; it does not establish that a branch is safe to mock.',
+    ].join('\n'),
+};
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+/**
+ * Answer one request. `null` means "no response", which is not the same as an
+ * empty one — a notification that gets answered is a protocol violation.
+ *
+ * `served` is required rather than defaulted to {@link REPORTS}. A default would
+ * infer its subject from whatever the second argument returns and then answer it
+ * with report tools, which is the class of mistake this file exists to make
+ * impossible: a server that speaks fluently about the wrong thing.
+ */
+export function handle(request, subject, served, invocation) {
+    if (request.id === undefined)
+        return null;
+    const id = request.id;
+    switch (request.method) {
+        case 'initialize':
+            return ok(id, {
+                protocolVersion: PROTOCOL_VERSION,
+                capabilities: { tools: {} },
+                serverInfo: { name: served.name, version: served.version },
+                // Read at the handshake rather than fixed at construction, because the
+                // one thing worth saying here — the address a run reports to — is not
+                // known until the listener has a port.
+                ...(served.instructions === undefined
+                    ? {}
+                    : { instructions: served.instructions(subject()) }),
+            });
+        case 'ping':
+            return ok(id, {});
+        case 'tools/list':
+            return ok(id, {
+                tools: served.tools.map((tool) => ({
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                })),
+            });
+        case 'tools/call':
+            return callTool(id, request.params ?? {}, subject, served.tools, invocation);
+        default:
+            return fail(id, METHOD_NOT_FOUND, `unknown method: ${request.method}`);
+    }
+}
+function callTool(id, params, subject, tools, invocation) {
+    const name = params['name'];
+    if (typeof name !== 'string')
+        return fail(id, INVALID_PARAMS, 'tools/call requires a name');
+    const tool = tools.find((candidate) => candidate.name === name);
+    if (tool === undefined)
+        return fail(id, INVALID_PARAMS, `unknown tool: ${name}`);
+    try {
+        const text = tool.run(subject(), (params['arguments'] ?? {}), invocation);
+        return ok(id, { content: [{ type: 'text', text }] });
+    }
+    catch (error) {
+        // A tool failure is a *result* with `isError`, not a JSON-RPC error. The
+        // distinction matters here: a transport error is invisible to the model,
+        // while an error result is text it can read and correct from — and "unknown
+        // subject; this run has: …" is precisely the kind of correction worth
+        // handing back rather than swallowing.
+        return ok(id, {
+            content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+            isError: true,
+        });
+    }
+}
+function ok(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+function fail(id, code, message) {
+    return { jsonrpc: '2.0', id, error: { code, message } };
+}
+/**
+ * Newline-delimited framing.
+ *
+ * Buffers partial lines because a stdio chunk boundary falls wherever the OS
+ * puts it, not where a JSON value ends. Getting this wrong produces a parse
+ * error under load and never in a test.
+ */
+export function createLineReader(onLine) {
+    let buffer = '';
+    return (chunk) => {
+        buffer += chunk;
+        let index = buffer.indexOf('\n');
+        while (index !== -1) {
+            const line = buffer.slice(0, index).trim();
+            buffer = buffer.slice(index + 1);
+            if (line !== '')
+                onLine(line);
+            index = buffer.indexOf('\n');
+        }
+    };
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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","sourcesContent":["import type { EyesArchive } from '@variance-authority/eyes';\nimport type { PresentationReport } from '@variance-authority/presentation';\nimport type { RunReport } from '@variance-authority/report';\nimport type { ScenarioArchiveManifest } from '@variance-authority/scenario/archive';\nimport type { ExecutionIndex } from '@variance-authority/sense/test-selection';\nimport type { VantageState } from '@variance-authority/vantage';\nimport type { ObservabilitySubject } from './observability-subject.js';\nimport type { Served, Tool, ToolInvocation } from './tools/tool.js';\nimport {\n  EYES_TOOLS,\n  OBSERVABILITY_TOOLS,\n  PRESENTATION_TOOLS,\n  SCENARIO_TOOLS,\n  SOURCE_TEST_TOOLS,\n  TOOLS,\n  VANTAGE_TOOLS,\n} from './tools.js';\nimport { attaching } from './tools/vantage-lines.js';\n\n/**\n * MCP over stdio, written out rather than depended on.\n *\n * The protocol is JSON-RPC 2.0 with newline-delimited framing and three methods\n * that matter. Writing it is roughly a hundred lines; depending on an SDK to\n * obtain those hundred lines costs a package, a version, and a transitive tree\n * in a repository whose `core` went to the trouble of implementing SHA-256 to\n * avoid depending on `node:crypto` (ADR-0006). The same judgement applies.\n *\n * The payoff is the same too: `handle` is a pure function from a request to a\n * response. No sockets, no streams, no process. Every behaviour below can be\n * asserted by calling it.\n */\n\nexport const PROTOCOL_VERSION = '2024-11-05';\nexport const SERVER_NAME = 'variance-authority';\nexport const SERVER_VERSION = '0.0.0';\n\nexport interface JsonRpcRequest {\n  readonly jsonrpc: '2.0';\n  /** Absent on a notification, which must not be answered. */\n  readonly id?: string | number;\n  readonly method: string;\n  readonly params?: Readonly<Record<string, unknown>>;\n}\n\nexport interface JsonRpcResponse {\n  readonly jsonrpc: '2.0';\n  readonly id: string | number;\n  readonly result?: unknown;\n  readonly error?: { readonly code: number; readonly message: string };\n}\n\n/** The visual-report tools this package ships, as the thing `handle` is handed. */\nexport const REPORTS: Served<RunReport> = {\n  name: SERVER_NAME,\n  version: SERVER_VERSION,\n  tools: TOOLS,\n};\n\n/** The MCP surface for agents asking which named tests exercise source. */\nexport const SOURCE_TESTS: Served<ExecutionIndex> = {\n  name: SERVER_NAME,\n  version: SERVER_VERSION,\n  tools: SOURCE_TEST_TOOLS,\n};\n\n/**\n * The MCP surface for an agent watching a suite that has not finished.\n *\n * The only served set that instructs. The other two answer about something that\n * already exists; this one answers about a run somebody still has to start, and\n * an agent that is not told the variable at the handshake starts it without one.\n */\nexport const VANTAGE: Served<VantageState> = {\n  name: SERVER_NAME,\n  version: SERVER_VERSION,\n  tools: VANTAGE_TOOLS,\n  instructions: (state) =>\n    [\n      'This server watches a test run while it happens. It answers about a suite ' +\n        'in flight rather than about a report on disk, and none of it is limited ' +\n        'to visual tests.',\n      '',\n      'Ask `variance_run_signals` for where the run has got to and which test is ' +\n        'still going, and `variance_test_signals` for everything one test has ' +\n        'announced — in order, with the realm that said each, plus work that ' +\n        'started and never ended. Both answer while the test is still running, ' +\n        'which is what a runner cannot do from outside the worker.',\n      '',\n      attaching(state),\n    ].join('\\n'),\n};\n\n/** The MCP surface for synchronously captured test attention. */\nexport const EYES: Served<EyesArchive> = {\n  name: SERVER_NAME,\n  version: SERVER_VERSION,\n  tools: EYES_TOOLS,\n};\n\n/** The MCP surface for full presentation graphs held by their caller. */\nexport const PRESENTATIONS: Served<readonly PresentationReport[]> = {\n  name: SERVER_NAME,\n  version: SERVER_VERSION,\n  tools: PRESENTATION_TOOLS,\n};\n\n/** The MCP surface for retained scenario executions. */\nexport const SCENARIOS: Served<readonly ScenarioArchiveManifest[]> = {\n  name: SERVER_NAME,\n  version: SERVER_VERSION,\n  tools: SCENARIO_TOOLS,\n};\n\n/**\n * The MCP surface that exposes every supplied observability domain without\n * merging their evidence or inventing cross-domain identity.\n */\nexport const OBSERVABILITY: Served<ObservabilitySubject> = {\n  name: SERVER_NAME,\n  version: SERVER_VERSION,\n  tools: OBSERVABILITY_TOOLS,\n  instructions: () => [\n    'This connection can expose visual reports, full presentation readings and durable signals, runtime journeys, ' +\n      'live events, Eyes attention and retained scenarios. Start with `variance_observability` ' +\n      'to learn which independent evidence domains were supplied.',\n    '',\n    'Unavailable evidence is not an empty measurement. Cross-domain answers join only on ' +\n      'exact identities emitted by both producers. `variance_testing_surface` reports replay ' +\n      'candidates; it does not establish that a branch is safe to mock.',\n  ].join('\\n'),\n};\n\nconst METHOD_NOT_FOUND = -32601;\nconst INVALID_PARAMS = -32602;\n\n/**\n * Answer one request. `null` means \"no response\", which is not the same as an\n * empty one — a notification that gets answered is a protocol violation.\n *\n * `served` is required rather than defaulted to {@link REPORTS}. A default would\n * infer its subject from whatever the second argument returns and then answer it\n * with report tools, which is the class of mistake this file exists to make\n * impossible: a server that speaks fluently about the wrong thing.\n */\nexport function handle<Subject>(\n  request: JsonRpcRequest,\n  subject: () => Subject,\n  served: Served<Subject>,\n  invocation?: ToolInvocation<Subject>,\n): JsonRpcResponse | null {\n  if (request.id === undefined) return null;\n  const id = request.id;\n\n  switch (request.method) {\n    case 'initialize':\n      return ok(id, {\n        protocolVersion: PROTOCOL_VERSION,\n        capabilities: { tools: {} },\n        serverInfo: { name: served.name, version: served.version },\n        // Read at the handshake rather than fixed at construction, because the\n        // one thing worth saying here — the address a run reports to — is not\n        // known until the listener has a port.\n        ...(served.instructions === undefined\n          ? {}\n          : { instructions: served.instructions(subject()) }),\n      });\n\n    case 'ping':\n      return ok(id, {});\n\n    case 'tools/list':\n      return ok(id, {\n        tools: served.tools.map((tool) => ({\n          name: tool.name,\n          description: tool.description,\n          inputSchema: tool.inputSchema,\n        })),\n      });\n\n    case 'tools/call':\n      return callTool(id, request.params ?? {}, subject, served.tools, invocation);\n\n    default:\n      return fail(id, METHOD_NOT_FOUND, `unknown method: ${request.method}`);\n  }\n}\n\nfunction callTool<Subject>(\n  id: string | number,\n  params: Readonly<Record<string, unknown>>,\n  subject: () => Subject,\n  tools: readonly Tool<Subject>[],\n  invocation?: ToolInvocation<Subject>,\n): JsonRpcResponse {\n  const name = params['name'];\n  if (typeof name !== 'string') return fail(id, INVALID_PARAMS, 'tools/call requires a name');\n\n  const tool = tools.find((candidate) => candidate.name === name);\n  if (tool === undefined) return fail(id, INVALID_PARAMS, `unknown tool: ${name}`);\n\n  try {\n    const text = tool.run(\n      subject(),\n      (params['arguments'] ?? {}) as Record<string, unknown>,\n      invocation,\n    );\n    return ok(id, { content: [{ type: 'text', text }] });\n  } catch (error) {\n    // A tool failure is a *result* with `isError`, not a JSON-RPC error. The\n    // distinction matters here: a transport error is invisible to the model,\n    // while an error result is text it can read and correct from — and \"unknown\n    // subject; this run has: …\" is precisely the kind of correction worth\n    // handing back rather than swallowing.\n    return ok(id, {\n      content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],\n      isError: true,\n    });\n  }\n}\n\nfunction ok(id: string | number, result: unknown): JsonRpcResponse {\n  return { jsonrpc: '2.0', id, result };\n}\n\nfunction fail(id: string | number, code: number, message: string): JsonRpcResponse {\n  return { jsonrpc: '2.0', id, error: { code, message } };\n}\n\n/**\n * Newline-delimited framing.\n *\n * Buffers partial lines because a stdio chunk boundary falls wherever the OS\n * puts it, not where a JSON value ends. Getting this wrong produces a parse\n * error under load and never in a test.\n */\nexport function createLineReader(onLine: (line: string) => void): (chunk: string) => void {\n  let buffer = '';\n\n  return (chunk: string): void => {\n    buffer += chunk;\n\n    let index = buffer.indexOf('\\n');\n    while (index !== -1) {\n      const line = buffer.slice(0, index).trim();\n      buffer = buffer.slice(index + 1);\n      if (line !== '') onLine(line);\n      index = buffer.indexOf('\\n');\n    }\n  };\n}\n"]}

package/dist/server.d.ts

@@ -0,0 +1,71 @@
+import type { Readable, Writable } from 'node:stream';
+import type { RunReport } from '@variance-authority/report';
+import type { Served } from './tools/tool.js';
+/**
+ * The transport, and nothing else.
+ *
+ * Everything decidable lives in `protocol.ts` and `tools.ts`, both of which are
+ * pure. What is left here is stream plumbing, which is the part that cannot be
+ * unit-tested meaningfully and therefore the part that should contain no
+ * decisions.
+ */
+export interface ServerOptions<Subject = RunReport> {
+    readonly input: Readable;
+    readonly output: Writable;
+    /** Which tools answer, and what the server calls itself. */
+    readonly served: Served<Subject>;
+    /**
+     * Supplies the current subject.
+     *
+     * A function rather than a value so a long-lived server picks up a re-run
+     * without a restart — an agent that fixes something and asks again should be
+     * answered from the new report, not from the one loaded at boot.
+     *
+     * It may be async, and the request waits for it. A supplier that kicked off a
+     * refresh and answered from the previous value would make *this* request the
+     * stale one, which is the request that matters: the agent asking is the agent
+     * that just re-ran.
+     */
+    readonly subject: () => Subject | Promise<Subject>;
+}
+export declare function serve<Subject>(options: ServerOptions<Subject>): () => void;
+/**
+ * Where a report-file server reads and writes. Both default to this process's
+ * stdio; they are parameters so the reload below is reachable from a test.
+ */
+export interface ReportFileOptions {
+    readonly input?: Readable;
+    readonly output?: Writable;
+}
+/**
+ * Serve a report file, re-read before each request is answered.
+ *
+ * The reload is why `report` is a function, and awaiting it is why the answer is
+ * current rather than one request behind. An agent that fixes something, re-runs,
+ * and asks again is the whole reason this server outlives a single report — and
+ * answering that agent from the copy loaded at boot tells it the edit did not
+ * take, which is the one sentence here nobody should ever produce falsely.
+ */
+export declare function serveReportFile(path: string, streams?: ReportFileOptions): Promise<() => void>;
+/** A watcher that is listening, and the address a run must be started with. */
+export interface ServedVantage {
+    /** What to put in the run's environment, verbatim. */
+    readonly address: string;
+    readonly stop: () => Promise<void>;
+}
+/**
+ * Serve a suite that has not finished.
+ *
+ * The subject is a **snapshot** rather than the store, and that is the whole of
+ * why a live subject fits a surface built for files. A store is a thing a socket
+ * writes into while an answer is being composed; a snapshot is a value, so every
+ * tool here stays what every tool here is — a pure function over evidence — and
+ * `variance_diff` gets a coherent previous state to compare against instead of
+ * an object that changed underneath it.
+ *
+ * Nothing is written to disk, and nothing outlives this process. That is the
+ * position `@variance-authority/event` takes about announcements, kept: what
+ * changes is how long one execution lasts when somebody is watching it.
+ */
+export declare function serveVantage(streams?: ReportFileOptions): Promise<ServedVantage>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,103 @@
+import { readRunReport } from '@variance-authority/report/file';
+import { attachVantage } from '@variance-authority/vantage/attach';
+import { REPORTS, VANTAGE, createLineReader, handle } from './protocol.js';
+export function serve(options) {
+    const write = (value) => {
+        options.output.write(`${JSON.stringify(value)}\n`);
+    };
+    // Requests are answered in the order they arrived. JSON-RPC matches responses
+    // by id and would tolerate any order, but a supplier that awaits makes the
+    // ordering depend on how long each read took, and an interleaving that only
+    // shows up under a slow disk is not a thing to debug later.
+    let queue = Promise.resolve();
+    let previous;
+    const read = createLineReader((line) => {
+        let request;
+        try {
+            request = JSON.parse(line);
+        }
+        catch {
+            // Unparseable input has no id, so there is nothing to answer. Answering
+            // with a null id would be a second protocol violation on top of the first.
+            return;
+        }
+        queue = queue.then(async () => {
+            const subject = await options.subject();
+            const response = handle(request, () => subject, options.served, previous === undefined ? {} : { previous });
+            if (request.method === 'tools/call' && succeeded(response)) {
+                previous = structuredClone(subject);
+            }
+            if (response !== null)
+                write(response);
+        });
+    });
+    const onData = (chunk) => read(chunk.toString());
+    options.input.on('data', onData);
+    return () => options.input.off('data', onData);
+}
+function succeeded(response) {
+    if (response === null || response.error !== undefined)
+        return false;
+    return response.result?.isError !== true;
+}
+/**
+ * Serve a report file, re-read before each request is answered.
+ *
+ * The reload is why `report` is a function, and awaiting it is why the answer is
+ * current rather than one request behind. An agent that fixes something, re-runs,
+ * and asks again is the whole reason this server outlives a single report — and
+ * answering that agent from the copy loaded at boot tells it the edit did not
+ * take, which is the one sentence here nobody should ever produce falsely.
+ */
+export async function serveReportFile(path, streams = {}) {
+    // Read once before serving, so a path that is not a run report fails at
+    // startup rather than on whichever request happens to arrive first.
+    let cached = await readRunReport(path);
+    return serve({
+        input: streams.input ?? process.stdin,
+        output: streams.output ?? process.stdout,
+        served: REPORTS,
+        subject: async () => {
+            try {
+                cached = await readRunReport(path);
+            }
+            catch {
+                // A report that becomes unreadable mid-run — being rewritten, most
+                // likely — must not take the server down. The previous one is stale,
+                // not wrong.
+            }
+            return cached;
+        },
+    });
+}
+/**
+ * Serve a suite that has not finished.
+ *
+ * The subject is a **snapshot** rather than the store, and that is the whole of
+ * why a live subject fits a surface built for files. A store is a thing a socket
+ * writes into while an answer is being composed; a snapshot is a value, so every
+ * tool here stays what every tool here is — a pure function over evidence — and
+ * `variance_diff` gets a coherent previous state to compare against instead of
+ * an object that changed underneath it.
+ *
+ * Nothing is written to disk, and nothing outlives this process. That is the
+ * position `@variance-authority/event` takes about announcements, kept: what
+ * changes is how long one execution lasts when somebody is watching it.
+ */
+export async function serveVantage(streams = {}) {
+    const attached = await attachVantage();
+    const stop = serve({
+        input: streams.input ?? process.stdin,
+        output: streams.output ?? process.stdout,
+        served: VANTAGE,
+        subject: () => attached.observatory.snapshot(),
+    });
+    return {
+        address: attached.address,
+        stop: async () => {
+            stop();
+            await attached.close();
+        },
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Readable, Writable } from 'node:stream';\nimport type { RunReport } from '@variance-authority/report';\nimport { readRunReport } from '@variance-authority/report/file';\nimport { attachVantage } from '@variance-authority/vantage/attach';\nimport { REPORTS, VANTAGE, createLineReader, handle, type JsonRpcRequest } from './protocol.js';\nimport type { Served } from './tools/tool.js';\n\n/**\n * The transport, and nothing else.\n *\n * Everything decidable lives in `protocol.ts` and `tools.ts`, both of which are\n * pure. What is left here is stream plumbing, which is the part that cannot be\n * unit-tested meaningfully and therefore the part that should contain no\n * decisions.\n */\n\nexport interface ServerOptions<Subject = RunReport> {\n  readonly input: Readable;\n  readonly output: Writable;\n  /** Which tools answer, and what the server calls itself. */\n  readonly served: Served<Subject>;\n  /**\n   * Supplies the current subject.\n   *\n   * A function rather than a value so a long-lived server picks up a re-run\n   * without a restart — an agent that fixes something and asks again should be\n   * answered from the new report, not from the one loaded at boot.\n   *\n   * It may be async, and the request waits for it. A supplier that kicked off a\n   * refresh and answered from the previous value would make *this* request the\n   * stale one, which is the request that matters: the agent asking is the agent\n   * that just re-ran.\n   */\n  readonly subject: () => Subject | Promise<Subject>;\n}\n\nexport function serve<Subject>(options: ServerOptions<Subject>): () => void {\n  const write = (value: unknown): void => {\n    options.output.write(`${JSON.stringify(value)}\\n`);\n  };\n\n  // Requests are answered in the order they arrived. JSON-RPC matches responses\n  // by id and would tolerate any order, but a supplier that awaits makes the\n  // ordering depend on how long each read took, and an interleaving that only\n  // shows up under a slow disk is not a thing to debug later.\n  let queue: Promise<void> = Promise.resolve();\n  let previous: Subject | undefined;\n\n  const read = createLineReader((line) => {\n    let request: JsonRpcRequest;\n    try {\n      request = JSON.parse(line) as JsonRpcRequest;\n    } catch {\n      // Unparseable input has no id, so there is nothing to answer. Answering\n      // with a null id would be a second protocol violation on top of the first.\n      return;\n    }\n\n    queue = queue.then(async () => {\n      const subject = await options.subject();\n      const response = handle(\n        request,\n        () => subject,\n        options.served,\n        previous === undefined ? {} : { previous },\n      );\n      if (request.method === 'tools/call' && succeeded(response)) {\n        previous = structuredClone(subject);\n      }\n      if (response !== null) write(response);\n    });\n  });\n\n  const onData = (chunk: Buffer | string): void => read(chunk.toString());\n  options.input.on('data', onData);\n\n  return () => options.input.off('data', onData);\n}\n\nfunction succeeded(response: ReturnType<typeof handle>): boolean {\n  if (response === null || response.error !== undefined) return false;\n  return (response.result as { readonly isError?: boolean } | undefined)?.isError !== true;\n}\n\n/**\n * Where a report-file server reads and writes. Both default to this process's\n * stdio; they are parameters so the reload below is reachable from a test.\n */\nexport interface ReportFileOptions {\n  readonly input?: Readable;\n  readonly output?: Writable;\n}\n\n/**\n * Serve a report file, re-read before each request is answered.\n *\n * The reload is why `report` is a function, and awaiting it is why the answer is\n * current rather than one request behind. An agent that fixes something, re-runs,\n * and asks again is the whole reason this server outlives a single report — and\n * answering that agent from the copy loaded at boot tells it the edit did not\n * take, which is the one sentence here nobody should ever produce falsely.\n */\nexport async function serveReportFile(\n  path: string,\n  streams: ReportFileOptions = {},\n): Promise<() => void> {\n  // Read once before serving, so a path that is not a run report fails at\n  // startup rather than on whichever request happens to arrive first.\n  let cached = await readRunReport(path);\n\n  return serve({\n    input: streams.input ?? process.stdin,\n    output: streams.output ?? process.stdout,\n    served: REPORTS,\n    subject: async () => {\n      try {\n        cached = await readRunReport(path);\n      } catch {\n        // A report that becomes unreadable mid-run — being rewritten, most\n        // likely — must not take the server down. The previous one is stale,\n        // not wrong.\n      }\n      return cached;\n    },\n  });\n}\n\n/** A watcher that is listening, and the address a run must be started with. */\nexport interface ServedVantage {\n  /** What to put in the run's environment, verbatim. */\n  readonly address: string;\n  readonly stop: () => Promise<void>;\n}\n\n/**\n * Serve a suite that has not finished.\n *\n * The subject is a **snapshot** rather than the store, and that is the whole of\n * why a live subject fits a surface built for files. A store is a thing a socket\n * writes into while an answer is being composed; a snapshot is a value, so every\n * tool here stays what every tool here is — a pure function over evidence — and\n * `variance_diff` gets a coherent previous state to compare against instead of\n * an object that changed underneath it.\n *\n * Nothing is written to disk, and nothing outlives this process. That is the\n * position `@variance-authority/event` takes about announcements, kept: what\n * changes is how long one execution lasts when somebody is watching it.\n */\nexport async function serveVantage(streams: ReportFileOptions = {}): Promise<ServedVantage> {\n  const attached = await attachVantage();\n  const stop = serve({\n    input: streams.input ?? process.stdin,\n    output: streams.output ?? process.stdout,\n    served: VANTAGE,\n    subject: () => attached.observatory.snapshot(),\n  });\n\n  return {\n    address: attached.address,\n    stop: async () => {\n      stop();\n      await attached.close();\n    },\n  };\n}\n"]}

package/dist/tools/adjudicate.d.ts

@@ -0,0 +1,25 @@
+import type { Tool } from './tool.js';
+/**
+ * `variance_adjudicate` — the run read back against what the agent said it did.
+ *
+ * Every other tool here answers about the run. This one answers about the
+ * *agent*, and it is the only tool in the set that takes evidence in rather than
+ * only handing it out: the declaration is something no report can contain,
+ * because the report was written by a process that never knew what the edit was
+ * for.
+ *
+ * What it buys is the arm nothing else in this category ships. `variance_changes`
+ * can tell an agent that `Button` moved in twelve subjects; it cannot tell it
+ * that `Card` — which the agent believes it just edited — did not move at all.
+ * That is not a diff finding, it is the *absence* of one, and an absence is only
+ * a finding once something declared it should have been there.
+ *
+ * The tool deliberately refuses to help an agent declare after the fact. It takes
+ * claims as an argument and derives none, so an agent that calls
+ * `variance_changes` first and then submits the answer back as its intent is
+ * scoring the run against itself — visibly, because the transcript shows the
+ * order. Nothing here can prevent that; what it can do is never do it *for* the
+ * agent.
+ */
+export declare const adjudicate: Tool;
+//# sourceMappingURL=adjudicate.d.ts.map