balladeer 0.0.4 → 1.0.0

package/dist/agent.js

@@ -0,0 +1,209 @@
+import { noteServerVersion } from "./currency.js";
+import { commandLine } from "./release.js";
+import {} from "./store.js";
+import { CLIENT_HEADER, CLIENT_HEADER_VALUE } from "./wire.js";
+const REPOSITORY_NAME = /^[A-Za-z0-9._-]{1,39}\/[A-Za-z0-9._-]{1,100}$/;
+/**
+ * Which stored credential a command uses, or a refusal saying why none.
+ *
+ * There are exactly two ways to be right about this, and taking whichever entry
+ * comes first is neither. Either the caller named a repository, in which case
+ * only that repository's credential will do, or it did not, in which case the
+ * only defensible answer is the credential belonging to the repository this
+ * process was started in. A machine set up for two repositories otherwise binds
+ * an agent working in one of them to the other one's promises, silently, and
+ * everything that agent then reads and proposes is about the wrong repository.
+ *
+ * The bearer is never written to stdout or stderr, and an entry whose MCP URL
+ * points somewhere other than the control plane it belongs to is refused: a
+ * server response must not be able to send this credential to a new host.
+ */
+export function selectAgent(agents, controlPlane, repositoryId, currentRepository) {
+    const here = agents.filter((agent) => agent.controlPlane === controlPlane);
+    if (repositoryId !== undefined) {
+        const named = here.find((agent) => agent.repositoryId === repositoryId);
+        if (named === undefined) {
+            return {
+                kind: "refused",
+                reason: `No Balladeer connection for repository ${repositoryId} is stored for ${controlPlane}.`,
+                missingFor: repositoryId,
+            };
+        }
+        return withSafeEndpoint(named);
+    }
+    // `unknown/unknown` is what the origin parse answers when it read nothing, so
+    // it is the absence of a repository rather than the name of one.
+    if (!REPOSITORY_NAME.test(currentRepository) || currentRepository === "unknown/unknown") {
+        return {
+            kind: "refused",
+            reason: "This directory has no GitHub origin remote I could read, so I cannot tell which repository's Balladeer connection to use. Pass --repository <id>.",
+        };
+    }
+    const matches = here.filter((agent) => agent.repository?.toLowerCase() === currentRepository.toLowerCase());
+    // Newest wins among the matches, which is the one the last setup wrote.
+    const chosen = matches[matches.length - 1];
+    if (chosen === undefined) {
+        return {
+            kind: "refused",
+            reason: `No Balladeer connection for ${currentRepository} is stored for ${controlPlane}.`,
+            missingFor: currentRepository,
+        };
+    }
+    return withSafeEndpoint(chosen);
+}
+/**
+ * What a command says when this machine holds no credential for the repository.
+ *
+ * A credential belongs to the machine it was issued on. A repository can be
+ * connected in a browser, or from a colleague's laptop, and this machine still
+ * hold nothing: the bearer is shown once, to whoever was there. Saying
+ * "Balladeer refused this workspace, run setup to pair again" in that state sent
+ * the founder to re-pair a machine whose pairing was never the problem, and a
+ * new setup session would not have helped, because these commands do not run
+ * over one.
+ *
+ * The invocation named is the checkout form, which is the one this copy was run
+ * as: nothing here has read the server's answer about publication yet.
+ */
+export function noAgentCredentialSentence(repository) {
+    return `This machine holds no agent credential for ${repository}. Run \`${commandLine(null, "setup")}\` to connect this machine; a setup session alone cannot propose.`;
+}
+export function withSafeEndpoint(agent) {
+    try {
+        if (new URL(agent.mcpUrl).origin !== new URL(agent.controlPlane).origin) {
+            return {
+                kind: "refused",
+                reason: "That connection's MCP endpoint is not on the control plane it belongs to, so I sent its credential nowhere.",
+            };
+        }
+    }
+    catch {
+        return {
+            kind: "refused",
+            reason: "That connection's MCP endpoint is not a URL, so I did not use it.",
+        };
+    }
+    return { kind: "agent", agent };
+}
+/**
+ * The headers every frame this program sends over an agent connection carries,
+ * and the one place they are written.
+ *
+ * `accept` names both media types because the Streamable HTTP transport refuses
+ * a POST that does not: a request accepting only JSON is answered 406 by the
+ * server before any tool runs. Nothing in this repository noticed, because every
+ * test that drove the endpoint wrote its own headers rather than the ones the
+ * forwarder sends. The setup probe now sends its one real call through this same
+ * constant, so a forwarder that cannot talk to the server is a failed setup step
+ * rather than a connection reported as working.
+ *
+ * `x-balladeer-client` is what lets the server refuse a copy of this program
+ * that is too old to talk to it, and answer with the line that updates it.
+ */
+export function forwarderHeaders(token) {
+    return {
+        authorization: `Bearer ${token}`,
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream",
+        [CLIENT_HEADER]: CLIENT_HEADER_VALUE,
+    };
+}
+/**
+ * One JSON-RPC tool call to the endpoint the forwarder would use, with the
+ * headers the forwarder sends and the same refusal of an endpoint on another
+ * origin. Nothing here reads the bearer back out or writes it anywhere.
+ */
+export async function callAgentTool(agent, name, argumentsValue, timeoutMs = 20_000) {
+    const safe = withSafeEndpoint(agent);
+    if (safe.kind === "refused")
+        return { kind: "endpoint_refused", reason: safe.reason };
+    let response;
+    try {
+        response = await fetch(agent.mcpUrl, {
+            method: "POST",
+            headers: forwarderHeaders(agent.token),
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "tools/call",
+                params: { name, arguments: argumentsValue },
+            }),
+            redirect: "manual",
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch {
+        return { kind: "unreachable" };
+    }
+    noteServerVersion(response.headers);
+    if (response.status === 426) {
+        return { kind: "client_too_old", update: updateLine(await safeJson(response)) };
+    }
+    if (response.status === 401 || response.status === 403)
+        return { kind: "unauthorized" };
+    if (!response.ok)
+        return { kind: "http", status: response.status };
+    const frame = await safeJson(response);
+    const result = resultOf(frame);
+    if (result === undefined)
+        return { kind: "malformed" };
+    return result;
+}
+export async function safeJson(response) {
+    try {
+        return (await response.json());
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The server's own remedy, read from the 426 body.
+ *
+ * Never a literal written here. Only the control plane knows whether this
+ * program is published, and a remedy naming a specifier the registry cannot
+ * serve leaves the person worse off than the refusal did.
+ */
+export function updateLine(payload) {
+    const update = payload?.update;
+    return typeof update === "string" && update.length > 0 && update.length < 200
+        ? update
+        : "the update line Balladeer prints on its setup page";
+}
+/**
+ * The result inside a JSON-RPC frame, read with `unknown` at every step. A shape
+ * that does not match is absence rather than a guess.
+ */
+function resultOf(payload) {
+    if (payload === null || typeof payload !== "object")
+        return undefined;
+    const result = payload.result;
+    if (result === null || typeof result !== "object")
+        return undefined;
+    const structured = result.structuredContent;
+    if (result.isError === true) {
+        return { kind: "tool_refusal", text: refusalText(result), structured };
+    }
+    if (structured === null || typeof structured !== "object")
+        return undefined;
+    return { kind: "result", structured };
+}
+/** The first text block of a refusing tool result, bounded. */
+function refusalText(result) {
+    const content = result.content;
+    if (!Array.isArray(content))
+        return "Balladeer refused this call.";
+    for (const block of content) {
+        const text = block?.text;
+        if (typeof text === "string" && text.length > 0)
+            return text.slice(0, 800);
+    }
+    return "Balladeer refused this call.";
+}
+/** One field of a tool result, when it is a string. Never a guess. */
+export function structuredString(structured, field) {
+    if (structured === null || typeof structured !== "object")
+        return undefined;
+    const value = structured[field];
+    return typeof value === "string" ? value : undefined;
+}

package/dist/cli.d.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+type Parsed = Readonly<{
+    command: string;
+    subcommand: string | undefined;
+    json: boolean;
+    wait: boolean;
+    /** Repair the files a previous setup wrote, and do nothing else. */
+    refresh: boolean;
+    repo: string | undefined;
+    file: string | undefined;
+    repository: string | undefined;
+    /**
+     * Every repository named on this run, in order.
+     *
+     * `setup` is the one command that takes more than one, because adding a
+     * repository is the one step it can do for a repository this directory is not
+     * a checkout of. Everywhere else a second name is a mistake, and is refused
+     * rather than quietly resolved to the last one.
+     */
+    repositories: readonly string[];
+    owner: string | undefined;
+    /** `check-seals --install-hook`: write the optional pre-push hook. */
+    installHook: boolean;
+    /** `check-seals --runner`: where the pinned runner is, when it has moved. */
+    runner: string | undefined;
+    createWorkspace: string | undefined;
+    /** Everything that was not a flag: the addresses `invite` sends to. */
+    positional: readonly string[];
+    role: string | undefined;
+    controlPlane: string;
+}>;
+export declare function parseArguments(argv: readonly string[]): Parsed;
+export declare function main(argv: readonly string[]): Promise<number>;
+export {};

package/dist/cli.js

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runAffected } from "./commands/affected.js";
+import { runCheckSeals } from "./commands/check-seals.js";
+import { runDiscover } from "./commands/discover.js";
+import { runExplain } from "./commands/explain.js";
+import { parseRole, runInvite } from "./commands/invite.js";
+import { runMcp } from "./commands/mcp.js";
+import { runPropose } from "./commands/propose.js";
+import { runRepositories } from "./commands/repositories.js";
+import { CREATE_WORKSPACE_MAX_LENGTH, runSetup } from "./commands/setup.js";
+import { runStatus } from "./commands/status.js";
+import { runTouchMap } from "./commands/touch-map.js";
+import { runWhoami } from "./commands/whoami.js";
+import { updateNotice } from "./currency.js";
+import { StoreError, normalizeControlPlane } from "./store.js";
+import { CLI_VERSION, DEFAULT_CONTROL_PLANE } from "./wire.js";
+const USAGE = `balladeer ${CLI_VERSION}
+
+  balladeer setup [--repository owner/name]... [--json] [--wait] [--control-plane <url>]
+                  [--create-workspace <name>] [--refresh]
+      Pair this session, add this repository, connect this coding agent and CI,
+      and report what a person still has to do. Name --repository more than once
+      to add other repositories to the same workspace; each of those is added and
+      nothing more, because connecting an agent and CI happens in a checkout.
+      --create-workspace carries a name to the approval page, where a person
+      signs in and creates the workspace themselves; this command never creates
+      one.
+      --refresh does one thing and talks to nobody: it rewrites this
+      repository's balladeer entry in .mcp.json and its Balladeer instructions
+      block to the current form, leaves every other entry in that file alone,
+      and prints what it changed. Run it when Balladeer says a newer version is
+      available.
+
+  balladeer repositories [--json] [--control-plane <url>]
+      List the repositories this machine's GitHub account can see, marking the
+      one you are standing in and the ones Balladeer already has.
+
+  balladeer invite <email>... [--role contributor|viewer|administrator] [--json]
+      Invite teammates into this workspace by email, and say per address whether
+      the invitation went. Inviting is an administrator's act.
+
+  balladeer status [<promise id>] [--repo owner/name] [--repository <uuid>] [--json]
+                   [--control-plane <url>]
+      Report this repository over its agent connection, and every repository in
+      the workspace when a setup session is still live. Named with a promise id,
+      report that one promise instead: whether it is holding, and if it is not,
+      the commit the failing run checked, the bounded reason, and the cases in
+      the agreed meaning that run was checking. That is the form the line on a
+      broken promise tells a person to run first.
+
+  balladeer propose --file <path> [--repo owner/name] [--repository <uuid>] [--json]
+      Propose one promise from a proposal file, over this repository's agent
+      connection. A named person still agrees to it.
+
+  balladeer discover --file <path> [--repo owner/name] [--repository <uuid>]
+                     [--owner <membership id>] [--json]
+      Propose a whole discovered catalog, up to ten promises from one file, each
+      owned by whoever paired this machine, and print one link that opens all of
+      them. A named person still agrees to every one.
+
+  balladeer check-seals [--json] [--runner <path>] [--install-hook]
+      Say whether what you are about to push would break a promise's seal. It
+      prints nothing and exits 0 when it would not, and names the promise, its
+      owner, its page and the line that seals it again when it would. It runs
+      offline, over the runner this repository is pinned to. --install-hook
+      writes .git/hooks/pre-push so every push asks first; nothing installs it
+      for you, and deleting that file removes it.
+
+  balladeer touch-map [--json]
+      Run this repository's promise verifiers under coverage and write down
+      which files each one actually executed, to .continuity/touch-map.json.
+      It runs offline and the map stays on this machine: Balladeer is never
+      sent it. Node verifiers only in this release.
+
+  balladeer affected <paths...> [--json]
+      Say which promises the named files touch, out of that map, marking any
+      answer whose verifier has changed since the map was built. It reads one
+      local file and contacts nothing.
+
+  balladeer explain [--control-plane <url>]
+      Print, word for word, what Balladeer can and cannot see, where to watch
+      your promises, and what leaving costs.
+
+  balladeer whoami [--json] [--control-plane <url>]
+      Report the stored setup session's workspace, role, scopes, and expiry.
+
+  balladeer agent rotate [--control-plane <url>]
+      Replace this repository's agent credential. A setup session cannot do this,
+      because rotating revokes the connections the repository already has.
+
+  balladeer mcp [--repository <uuid>] [--control-plane <url>]
+      Forward one MCP session over stdio using this repository's agent connection.
+
+Exit codes: 0 progress reported truthfully, 2 pairing expired or denied or already
+claimed, 3 this copy is too old for the server, 4 usage or credential store problem,
+5 transport or server failure.
+`;
+const SUBCOMMANDS = { agent: ["rotate"] };
+export function parseArguments(argv) {
+    const args = [...argv];
+    const command = args.shift() ?? "help";
+    let subcommand;
+    if (SUBCOMMANDS[command] !== undefined) {
+        subcommand = args.shift();
+        if (subcommand === undefined || !SUBCOMMANDS[command].includes(subcommand)) {
+            throw new StoreError("usage", `${command} needs one of: ${SUBCOMMANDS[command].join(", ")}.`);
+        }
+    }
+    let json = false;
+    let wait = false;
+    let refresh = false;
+    let installHook = false;
+    let runner;
+    let controlPlane;
+    let repo;
+    let file;
+    let owner;
+    let createWorkspace;
+    let role;
+    const repositories = [];
+    const positional = [];
+    const NEEDS = {
+        "--control-plane": "a URL",
+        "--repo": "an owner/name",
+        "--file": "a path",
+        "--repository": "a repository, as owner/name for setup or as an id elsewhere",
+        "--owner": "a membership id",
+        "--create-workspace": "a workspace name",
+        "--role": "contributor, viewer, or administrator",
+        "--runner": "a path to the pinned runner's cli.js",
+    };
+    const value = (flag, inline) => {
+        const next = inline ?? args.shift();
+        if (!next)
+            throw new StoreError("usage", `${flag} needs ${NEEDS[flag] ?? "a value"}.`);
+        return next;
+    };
+    while (args.length > 0) {
+        const flag = args.shift();
+        if (!flag.startsWith("--")) {
+            positional.push(flag);
+            continue;
+        }
+        const [name, ...rest] = flag.split("=");
+        const inline = rest.length > 0 ? rest.join("=") : undefined;
+        if (name === "--json")
+            json = true;
+        else if (name === "--install-hook")
+            installHook = true;
+        else if (name === "--runner")
+            runner = value("--runner", inline);
+        else if (name === "--wait")
+            wait = true;
+        else if (name === "--refresh")
+            refresh = true;
+        else if (name === "--control-plane")
+            controlPlane = value("--control-plane", inline);
+        else if (name === "--repo")
+            repo = value("--repo", inline);
+        else if (name === "--file")
+            file = value("--file", inline);
+        else if (name === "--repository")
+            repositories.push(value("--repository", inline));
+        else if (name === "--owner")
+            owner = value("--owner", inline);
+        else if (name === "--role")
+            role = value("--role", inline);
+        else if (name === "--create-workspace") {
+            createWorkspace = value("--create-workspace", inline).trim();
+            if (createWorkspace.length === 0 || createWorkspace.length > CREATE_WORKSPACE_MAX_LENGTH) {
+                throw new StoreError("usage", `--create-workspace needs a workspace name of 1 to ${CREATE_WORKSPACE_MAX_LENGTH} characters.`);
+            }
+        }
+        else
+            throw new StoreError("usage", `Unknown option ${flag}.`);
+    }
+    // `invite` is the one command that takes a bare word, and the words it takes
+    // are email addresses. Anywhere else a bare word is a mistyped flag or a
+    // value that lost its flag, and it was refused before this loop learned to
+    // collect them, so it is refused here rather than ignored.
+    // `affected` is the other one, and the words it takes are paths in the change
+    // in front of the person.
+    if (positional.length > 0 && command !== "invite" && command !== "affected") {
+        throw new StoreError("usage", `${command} takes no bare arguments: ${positional.join(", ")}.`);
+    }
+    // `--repository` names one repository everywhere but `setup`, where it names
+    // as many as a person wants to add. A second one anywhere else is refused
+    // rather than resolved to the last: silently acting on one of two repositories
+    // somebody named is worse than saying no.
+    // `--refresh` repairs the files setup writes, so it belongs to setup and to
+    // nothing else. Accepting it silently elsewhere would let somebody run
+    // `status --refresh`, see no error, and believe their install was repaired.
+    if (refresh && command !== "setup") {
+        throw new StoreError("usage", "--refresh belongs to setup: run `balladeer setup --refresh`.");
+    }
+    if (command !== "setup" && repositories.length > 1) {
+        throw new StoreError("usage", `${command} acts on one repository. Name --repository once, or run it again for the other.`);
+    }
+    const chosen = controlPlane ?? process.env.BALLADEER_CONTROL_PLANE?.trim() ?? DEFAULT_CONTROL_PLANE;
+    return {
+        command,
+        subcommand,
+        json,
+        wait,
+        refresh,
+        repo,
+        file,
+        repository: repositories[0],
+        repositories,
+        owner,
+        installHook,
+        runner,
+        createWorkspace,
+        positional,
+        role,
+        controlPlane: normalizeControlPlane(chosen),
+    };
+}
+export async function main(argv) {
+    let parsed;
+    try {
+        parsed = parseArguments(argv);
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n\n${USAGE}`);
+        return 4;
+    }
+    const write = (text) => void process.stdout.write(text);
+    const code = await dispatch(parsed, write);
+    // Said once, at the end, on stderr: an agent reading `--json` gets its steps
+    // on stdout unchanged, and a person reading a terminal gets the one line that
+    // says this copy is behind. It is a nag and never a failure, so it does not
+    // touch the exit code.
+    const notice = updateNotice();
+    if (notice !== undefined)
+        process.stderr.write(`${notice}\n`);
+    return code;
+}
+async function dispatch(parsed, write) {
+    switch (parsed.command) {
+        case "explain":
+            return runExplain(write, parsed.controlPlane);
+        case "setup":
+            return runSetup({
+                controlPlane: parsed.controlPlane,
+                json: parsed.json,
+                wait: parsed.wait,
+                refresh: parsed.refresh,
+                ...(parsed.repo === undefined ? {} : { repo: parsed.repo }),
+                repositories: parsed.repositories,
+                ...(parsed.createWorkspace === undefined
+                    ? {}
+                    : { createWorkspace: parsed.createWorkspace }),
+                environment: process.env,
+                cwd: process.cwd(),
+                write,
+            });
+        case "repositories":
+            return runRepositories({
+                controlPlane: parsed.controlPlane,
+                json: parsed.json,
+                environment: process.env,
+                cwd: process.cwd(),
+                write,
+            });
+        case "invite": {
+            const role = parseRole(parsed.role);
+            if (role === undefined) {
+                process.stderr.write(`--role takes contributor, viewer, or administrator. It was given "${parsed.role}".\n`);
+                return 4;
+            }
+            return runInvite({
+                controlPlane: parsed.controlPlane,
+                json: parsed.json,
+                emails: parsed.positional,
+                role,
+                environment: process.env,
+                write,
+            });
+        }
+        case "check-seals":
+            return runCheckSeals({
+                json: parsed.json,
+                installHook: parsed.installHook,
+                ...(parsed.runner === undefined ? {} : { runner: parsed.runner }),
+                environment: process.env,
+                cwd: process.cwd(),
+                write,
+            });
+        case "touch-map":
+            return runTouchMap({
+                json: parsed.json,
+                environment: process.env,
+                cwd: process.cwd(),
+                write,
+            });
+        case "affected":
+            return runAffected({
+                json: parsed.json,
+                paths: parsed.positional,
+                cwd: process.cwd(),
+                write,
+            });
+        case "status": {
+            // At most one. Two ids on one line is a mistake, and answering for the
+            // first of them silently would report a promise nobody asked about.
+            if (parsed.positional.length > 1) {
+                process.stderr.write("status reads one promise id at a time.\n");
+                return 4;
+            }
+            const promiseId = parsed.positional[0];
+            return runStatus({
+                controlPlane: parsed.controlPlane,
+                json: parsed.json,
+                ...(promiseId === undefined ? {} : { promiseId }),
+                ...(parsed.repo === undefined ? {} : { repo: parsed.repo }),
+                ...(parsed.repository === undefined ? {} : { repository: parsed.repository }),
+                environment: process.env,
+                cwd: process.cwd(),
+                write,
+            });
+        }
+        case "propose":
+            return runPropose({
+                controlPlane: parsed.controlPlane,
+                json: parsed.json,
+                ...(parsed.file === undefined ? {} : { file: parsed.file }),
+                ...(parsed.repo === undefined ? {} : { repo: parsed.repo }),
+                ...(parsed.repository === undefined ? {} : { repository: parsed.repository }),
+                environment: process.env,
+                cwd: process.cwd(),
+                write,
+            });
+        case "discover":
+            return runDiscover({
+                controlPlane: parsed.controlPlane,
+                json: parsed.json,
+                ...(parsed.file === undefined ? {} : { file: parsed.file }),
+                ...(parsed.repo === undefined ? {} : { repo: parsed.repo }),
+                ...(parsed.repository === undefined ? {} : { repository: parsed.repository }),
+                ...(parsed.owner === undefined ? {} : { owner: parsed.owner }),
+                environment: process.env,
+                cwd: process.cwd(),
+                write,
+            });
+        case "agent":
+            // Rotating revokes every live connection for the repository, which is
+            // removal. The approval page tells a person their setup session cannot
+            // remove anything, so this command says the same rather than trying and
+            // relaying a server refusal the person cannot act on.
+            process.stderr.write("A setup session cannot rotate an agent connection: rotating revokes the connections this repository already has, and a setup session may not remove anything.\n" +
+                `Rotate it in Balladeer under workspace settings at ${parsed.controlPlane}/settings.\n`);
+            return 4;
+        case "whoami":
+            return runWhoami({
+                controlPlane: parsed.controlPlane,
+                json: parsed.json,
+                environment: process.env,
+                write,
+            });
+        case "mcp":
+            return runMcp({
+                controlPlane: parsed.controlPlane,
+                ...(parsed.repository === undefined ? {} : { repositoryId: parsed.repository }),
+                environment: process.env,
+                cwd: process.cwd(),
+                stdin: process.stdin,
+                write,
+                error: (text) => void process.stderr.write(text),
+            });
+        case "help":
+        case "--help":
+        case "-h":
+            write(USAGE);
+            return 0;
+        case "--version":
+        case "-v":
+            write(`${CLI_VERSION}\n`);
+            return 0;
+        default:
+            process.stderr.write(`Unknown command "${parsed.command}".\n\n${USAGE}`);
+            return 4;
+    }
+}
+// Only when this file is the program, so a test may import `main` without the
+// import itself running a command.
+const entry = process.argv[1];
+if (entry !== undefined && fileURLToPath(import.meta.url) === resolve(entry)) {
+    process.exitCode = await main(process.argv.slice(2));
+}

package/dist/client.d.ts

@@ -0,0 +1,44 @@
+import { type PairRefusal } from "./wire.js";
+export declare class TransportError extends Error {
+    readonly controlPlane: string;
+    constructor(controlPlane: string, reason: string);
+}
+export declare class ClientTooOldError extends Error {
+    readonly update: string;
+    readonly controlPlane: string;
+    constructor(controlPlane: string, update: string);
+}
+export declare class RefusalError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(status: number, refusal: PairRefusal);
+}
+/**
+ * A link this command prints, always built from the address it paired with.
+ *
+ * Behind a platform proxy a server can resolve a link against the machine it is
+ * running on rather than against the address customers use, and the first
+ * production `propose` printed exactly that: `https://localhost:8080/candidates/...`
+ * as the place to go and agree. A command that prints such a link is worse than
+ * one that prints none, because the person tries it.
+ *
+ * So no link a server sends is ever printed. The proposal path answers with an
+ * identifier and this builds the address, which is why there is no parameter
+ * here for a server's own link to arrive through.
+ */
+export declare function reviewLink(controlPlane: string, path: string): string;
+export type RequestOptions = Readonly<{
+    method: "GET" | "POST";
+    path: string;
+    body?: unknown;
+    bearer?: string;
+    timeoutMs?: number;
+}>;
+/**
+ * The one place this command talks to a network.
+ *
+ * `redirect: "manual"` so no redirect can carry a bearer to a host the person
+ * never paired with, and the 426 handshake is decoded here so every caller gets
+ * the same actionable refusal rather than a status code.
+ */
+export declare function request<T>(controlPlane: string, options: RequestOptions): Promise<T>;