balladeer 0.0.5 → 1.0.1

package/dist/commands/invite.js

@@ -0,0 +1,198 @@
+import { ClientTooOldError, RefusalError, TransportError, request } from "../client.js";
+import { formatInstant } from "../local-time.js";
+import { commandLine } from "../release.js";
+import { StoreError, findSession, readCredentials } from "../store.js";
+import {} from "../wire.js";
+/**
+ * What a person types, and what the ledger stores.
+ *
+ * "Administrator" is the word every screen uses and the word a person says out
+ * loud, and `admin` is the value the ledger holds. Both are accepted so nobody
+ * has to know which of the two this command wanted, and the confirmation prints
+ * the long form back, because that is the word on the settings page they will
+ * see this person listed under.
+ */
+const ROLES = {
+    administrator: "admin",
+    admin: "admin",
+    contributor: "contributor",
+    viewer: "viewer",
+};
+export const ROLE_NAMES = {
+    admin: "administrator",
+    contributor: "contributor",
+    viewer: "viewer",
+};
+/** What each role may do, in one clause, so nobody invites by guessing. */
+export const ROLE_MEANINGS = {
+    admin: "read this workspace, propose promises, change setup, and invite people",
+    contributor: "read this workspace and propose promises",
+    viewer: "read this workspace",
+};
+export function parseRole(value) {
+    if (value === undefined)
+        return "contributor";
+    return ROLES[value.trim().toLowerCase()];
+}
+/**
+ * An address this command will send. Deliberately narrow rather than clever: it
+ * refuses here so a typo costs a sentence rather than an invitation nobody can
+ * recall, and the server's own schema refuses it again.
+ */
+const EMAIL = /^[^\s@,;]+@[^\s@,;.]+(?:\.[^\s@,;.]+)+$/;
+export function looksLikeEmail(value) {
+    return value.length <= 320 && EMAIL.test(value);
+}
+function emit(options, step) {
+    if (options.json)
+        options.write(`${JSON.stringify(step)}\n`);
+}
+function say(options, text) {
+    if (!options.json)
+        options.write(`${text}\n`);
+}
+function fail(options, reason, message, exitCode) {
+    say(options, message);
+    emit(options, { step: "error", reason, message, changed: false, exitCode });
+    return exitCode;
+}
+/**
+ * The refusal a person meets when their approver's role never carried this.
+ *
+ * Said before anything is sent, from the scopes the session itself reports,
+ * because the alternative is a person typing four addresses and being refused
+ * by the server four times for a reason that was knowable before the first one.
+ */
+function withoutTheScope(options, session) {
+    return fail(options, "invite_not_permitted", [
+        `This setup session cannot invite anybody into ${session.workspaceName}.`,
+        "  Inviting is an administrator's act, and a session carries only what the person who approved it could do unaided.",
+        `  Next: ask an administrator of ${session.workspaceName} to run this command, or to invite people in Balladeer under workspace settings.`,
+    ].join("\n"), 4);
+}
+/**
+ * Invites teammates by email, one at a time, and says what happened to each.
+ *
+ * Per address rather than per run. Sending four invitations is four separate
+ * things that can each succeed or be refused on their own, and a person reading
+ * "3 of 4 sent" cannot tell whose email is missing. Every address gets its own
+ * line and its own object, and the exit code says only whether every one of
+ * them went.
+ */
+export async function runInvite(options) {
+    if (options.emails.length === 0) {
+        return fail(options, "usage", `Name at least one email address to invite. For example: ${commandLine(null, "invite alice@example.com")}`, 4);
+    }
+    const malformed = options.emails.filter((email) => !looksLikeEmail(email));
+    if (malformed.length > 0) {
+        return fail(options, "usage", `That is not an email address: ${malformed.join(", ")}. Nothing was sent.`, 4);
+    }
+    let credentials;
+    try {
+        credentials = readCredentials(options.environment);
+    }
+    catch (error) {
+        return fail(options, error instanceof StoreError ? error.code : "credential_store_unusable", error instanceof StoreError ? error.message : String(error), 4);
+    }
+    const session = findSession(credentials, options.controlPlane);
+    if (session === undefined) {
+        return fail(options, "no_stored_session", `No Balladeer session is stored for ${options.controlPlane}. Run: ${commandLine(null, "setup")}`, 4);
+    }
+    // Read off the stored session rather than attempted and reported back. The
+    // approval page lists what the person granted, and this is one of the five.
+    if (!session.scopes.includes("workspace:invite")) {
+        return withoutTheScope(options, session);
+    }
+    let refused = 0;
+    for (const email of options.emails) {
+        const sent = await inviteOne(options, session, email);
+        if (!sent)
+            refused += 1;
+    }
+    if (refused === 0) {
+        say(options, `\nEach person gets an email from Balladeer with a link to accept. Nobody is in ${session.workspaceName} until they accept, and until then they are listed as invited under workspace settings.`);
+        return 0;
+    }
+    return 5;
+}
+async function inviteOne(options, session, email) {
+    const body = { email, requestedRole: options.role };
+    try {
+        const answer = await request(options.controlPlane, {
+            method: "POST",
+            path: "/api/setup/v1/invitations",
+            bearer: session.token,
+            body,
+        });
+        const role = ROLE_NAMES[answer.requestedRole];
+        say(options, `Invited ${answer.email} to ${answer.workspaceName} as ${role}. Balladeer has sent them the email.`);
+        say(options, `  They can ${ROLE_MEANINGS[answer.requestedRole]}. They join when they accept, and not before.`);
+        if (answer.expiresAt !== null) {
+            say(options, `  The invitation stops working at ${formatInstant(answer.expiresAt)}.`);
+        }
+        emit(options, {
+            step: "invitation",
+            status: "sent",
+            email: answer.email,
+            role: answer.requestedRole,
+            workspace: answer.workspaceName,
+            expiresAt: answer.expiresAt,
+        });
+        return true;
+    }
+    catch (error) {
+        const { reason, message } = invitationRefusal(options, email, error);
+        say(options, message);
+        emit(options, {
+            step: "invitation",
+            status: "refused",
+            email,
+            role: options.role,
+            reason,
+            message,
+        });
+        return false;
+    }
+}
+/**
+ * One refusal, in the words the person can act on.
+ *
+ * Every arm names the address, because a run inviting four people prints four
+ * lines and a bare "already a member" belongs to one of them. Nothing here
+ * invents a remedy the server did not offer: where the server said why, that
+ * sentence is what is printed.
+ */
+function invitationRefusal(options, email, error) {
+    if (error instanceof ClientTooOldError) {
+        return { reason: "client_too_old", message: `${email}: ${error.message}` };
+    }
+    if (error instanceof TransportError) {
+        return {
+            reason: "control_plane_unreachable",
+            message: `${email}: Balladeer could not be reached at ${options.controlPlane}: ${error.message}. No invitation was sent to this address.`,
+        };
+    }
+    if (error instanceof RefusalError) {
+        if (error.code === "delegated_authority_refused" || error.code === "action_not_allowed") {
+            return {
+                reason: error.code,
+                message: `${email}: this setup session may not invite anybody. Ask an administrator to run this command, or to invite people in Balladeer under workspace settings.`,
+            };
+        }
+        if (error.code === "session_expired" || error.code === "session_revoked") {
+            return {
+                reason: error.code,
+                message: `${email}: this setup session has ended, so nothing was sent. Run \`${commandLine(null, "setup")}\` to pair again.`,
+            };
+        }
+        // The server's own sentence. "That email already has an active membership"
+        // and "an incompatible or already-confirmed invitation is still open for
+        // that email" are both things a person acts on, and both are already
+        // written the way a person reads them.
+        return { reason: error.code, message: `${email}: ${error.message}` };
+    }
+    return {
+        reason: "invitation_failed",
+        message: `${email}: Balladeer could not send this invitation. Nothing was sent to this address.`,
+    };
+}

package/dist/commands/mcp.d.ts

@@ -0,0 +1,65 @@
+import { type StoredAgent } from "../store.js";
+export { forwarderHeaders, selectAgent, type AgentSelection } from "../agent.js";
+export type McpOptions = Readonly<{
+    controlPlane: string;
+    /**
+     * Which repository's credential to forward. The host config setup writes
+     * always names it, because a workspace holds several repositories and each one
+     * has its own connection. Without it, the credential belonging to the
+     * repository this process was started in is used, and where there is no such
+     * credential the command refuses rather than guessing.
+     */
+    repositoryId?: string;
+    environment: NodeJS.ProcessEnv;
+    cwd: string;
+    stdin: NodeJS.ReadableStream;
+    write: (text: string) => void;
+    error: (text: string) => void;
+}>;
+export type ProbeResult = Readonly<{
+    kind: "answered";
+    repositoryId: string;
+}> | Readonly<{
+    kind: "refused";
+    reason: string;
+    nextAction: string;
+}>;
+/**
+ * One real call over the connection just issued, before anything claims it
+ * works.
+ *
+ * It is `get_promise_setup` because that tool answers for the bound repository
+ * and nothing else, so its answer proves three things at once: the credential
+ * authenticated on the MCP endpoint, Balladeer served this repository's
+ * connection rather than another's, and the frames this forwarder writes are
+ * frames that server accepts. A response for a different repository is a failure
+ * here, not a curiosity.
+ *
+ * It sends what the forwarder sends, over the endpoint the forwarder would use,
+ * and refuses the same entries the forwarder refuses. What it cannot prove is
+ * whether an agent host has loaded the entry yet, which is why the step that
+ * calls this also names the host's own next action rather than implying there
+ * is none.
+ */
+export declare function probeAgentConnection(agent: StoredAgent, timeoutMs?: number): Promise<ProbeResult>;
+/**
+ * The frame a host is owed when the server refuses this copy of the program.
+ *
+ * A 426 body is the control plane's JSON, not JSON-RPC, and relaying it to a
+ * host would surface as a protocol error with no sentence in it. The host is
+ * told in its own protocol what happened and which line fixes it, and the same
+ * sentence goes to stderr for whoever is reading the log.
+ */
+export declare function staleClientFrame(id: unknown, update: string): string;
+/**
+ * The frame a host is owed when the credential itself is finished.
+ *
+ * The server refuses a revoked connection at the door, so the model never
+ * reaches a tool and never sees the tool-level refusal that would have told it
+ * apart from a missing scope. Without this it sees a server that died. The
+ * sentence is the same distinction the server's own refusals draw: this is the
+ * connection being gone, not this tool being unavailable, and the remedy is a
+ * person's.
+ */
+export declare function revokedConnectionFrame(id: unknown, controlPlane: string): string;
+export declare function runMcp(options: McpOptions): Promise<number>;

package/dist/commands/mcp.js

@@ -0,0 +1,202 @@
+import { createInterface } from "node:readline";
+import { callAgentTool, forwarderHeaders, noAgentCredentialSentence, safeJson, selectAgent, structuredString, updateLine, } from "../agent.js";
+import { noteServerVersion, updateNotice } from "../currency.js";
+import { repositoryHint } from "../repository.js";
+import { StoreError, readCredentials } from "../store.js";
+// The three commands that use an agent connection select and address it through
+// one module. These are re-exported because this is where the forwarder's
+// callers already look for them.
+export { forwarderHeaders, selectAgent } from "../agent.js";
+const MAX_REQUEST_BYTES = 1024 * 1024;
+const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+/**
+ * One real call over the connection just issued, before anything claims it
+ * works.
+ *
+ * It is `get_promise_setup` because that tool answers for the bound repository
+ * and nothing else, so its answer proves three things at once: the credential
+ * authenticated on the MCP endpoint, Balladeer served this repository's
+ * connection rather than another's, and the frames this forwarder writes are
+ * frames that server accepts. A response for a different repository is a failure
+ * here, not a curiosity.
+ *
+ * It sends what the forwarder sends, over the endpoint the forwarder would use,
+ * and refuses the same entries the forwarder refuses. What it cannot prove is
+ * whether an agent host has loaded the entry yet, which is why the step that
+ * calls this also names the host's own next action rather than implying there
+ * is none.
+ */
+export async function probeAgentConnection(agent, timeoutMs = 15_000) {
+    const call = await callAgentTool(agent, "get_promise_setup", {}, timeoutMs);
+    switch (call.kind) {
+        case "endpoint_refused":
+            return {
+                kind: "refused",
+                reason: call.reason,
+                nextAction: "Issue the connection again from the Balladeer setup page.",
+            };
+        case "unreachable":
+            return {
+                kind: "refused",
+                reason: "Balladeer's MCP endpoint could not be reached from this machine",
+                nextAction: "Check this machine's network access, then run this command again.",
+            };
+        case "client_too_old":
+            return {
+                kind: "refused",
+                reason: "this copy of the command is too old for that Balladeer",
+                nextAction: `Update it with: ${call.update}, then run this command again.`,
+            };
+        case "unauthorized":
+            return {
+                kind: "refused",
+                reason: "Balladeer refused the credential this step just issued",
+                nextAction: "Issue the connection again from the Balladeer setup page.",
+            };
+        case "http":
+            return {
+                kind: "refused",
+                reason: `Balladeer answered ${call.status} to a first call over this connection`,
+                nextAction: "Run this command again; if it repeats, report the status above.",
+            };
+        case "result": {
+            const repositoryId = structuredString(call.structured, "repositoryId");
+            if (repositoryId === undefined)
+                break;
+            if (repositoryId !== agent.repositoryId) {
+                return {
+                    kind: "refused",
+                    reason: "that connection answered for a different repository",
+                    nextAction: "Issue the connection again from the Balladeer setup page, and do not use it.",
+                };
+            }
+            return { kind: "answered", repositoryId };
+        }
+        default:
+            break;
+    }
+    return {
+        kind: "refused",
+        reason: "Balladeer's answer to a first call over this connection was not a tool result",
+        nextAction: "Run this command again; if it repeats, report that to Balladeer.",
+    };
+}
+/**
+ * The frame a host is owed when the server refuses this copy of the program.
+ *
+ * A 426 body is the control plane's JSON, not JSON-RPC, and relaying it to a
+ * host would surface as a protocol error with no sentence in it. The host is
+ * told in its own protocol what happened and which line fixes it, and the same
+ * sentence goes to stderr for whoever is reading the log.
+ */
+export function staleClientFrame(id, update) {
+    return errorFrame(id, `This copy of the Balladeer command is too old for this Balladeer. Update it with: ${update}`);
+}
+/**
+ * The frame a host is owed when the credential itself is finished.
+ *
+ * The server refuses a revoked connection at the door, so the model never
+ * reaches a tool and never sees the tool-level refusal that would have told it
+ * apart from a missing scope. Without this it sees a server that died. The
+ * sentence is the same distinction the server's own refusals draw: this is the
+ * connection being gone, not this tool being unavailable, and the remedy is a
+ * person's.
+ */
+export function revokedConnectionFrame(id, controlPlane) {
+    return errorFrame(id, `Balladeer refused this agent connection: it was revoked, or the repository it was bound to is no longer enrolled. This is the connection being gone rather than one tool being unavailable, so retrying will not help. Ask the person to run Balladeer setup again in this repository, or to issue a new connection at ${controlPlane}/setup.`);
+}
+function errorFrame(id, message) {
+    return JSON.stringify({
+        jsonrpc: "2.0",
+        id: id ?? null,
+        error: { code: -32000, message },
+    });
+}
+function frameId(line) {
+    try {
+        const parsed = JSON.parse(line);
+        if (parsed !== null && typeof parsed === "object") {
+            const id = parsed.id;
+            if (typeof id === "string" || typeof id === "number")
+                return id;
+        }
+    }
+    catch {
+        // A frame we cannot parse still gets an answer, with a null id.
+    }
+    return null;
+}
+export async function runMcp(options) {
+    let credentials;
+    try {
+        credentials = readCredentials(options.environment);
+    }
+    catch (error) {
+        options.error(`${error instanceof StoreError ? error.message : String(error)}\n`);
+        return 4;
+    }
+    const selection = selectAgent(credentials.agents, options.controlPlane, options.repositoryId, repositoryHint(options.cwd));
+    if (selection.kind === "refused") {
+        // Issuing one in the browser is what this used to suggest here, and it is the
+        // move that produces this state: the bearer is shown once, there, and the
+        // forwarder reads the store on this machine.
+        options.error(selection.missingFor === undefined
+            ? `${selection.reason} Run setup in this repository, or issue the connection at ${options.controlPlane}/setup.\n`
+            : `${noAgentCredentialSentence(selection.missingFor)}\n`);
+        return 4;
+    }
+    const { agent } = selection;
+    let saidUpdate = false;
+    const lines = createInterface({ input: options.stdin, crlfDelay: Infinity });
+    for await (const line of lines) {
+        if (line.trim().length === 0)
+            continue;
+        if (Buffer.byteLength(line, "utf8") > MAX_REQUEST_BYTES) {
+            options.error("Balladeer refused a request frame larger than 1 MiB.\n");
+            return 5;
+        }
+        let response;
+        try {
+            response = await fetch(agent.mcpUrl, {
+                method: "POST",
+                headers: forwarderHeaders(agent.token),
+                body: line,
+                redirect: "manual",
+            });
+        }
+        catch {
+            options.error("Balladeer could not be reached. Nothing was changed.\n");
+            return 5;
+        }
+        // The host's own channel for this is the instructions the server sends on
+        // initialize, which reach the model. This line reaches whoever is reading
+        // the log, once per session rather than once per frame.
+        noteServerVersion(response.headers);
+        const notice = updateNotice();
+        if (notice !== undefined && !saidUpdate) {
+            saidUpdate = true;
+            options.error(`${notice}\n`);
+        }
+        if (response.status === 401) {
+            options.write(`${revokedConnectionFrame(frameId(line), options.controlPlane)}\n`);
+            options.error("Balladeer refused this agent connection. Rotate it in Balladeer.\n");
+            return 5;
+        }
+        // The version floor, answered in the host's own protocol. A stale forwarder
+        // that has been running against this control plane for months learns here
+        // what to run, and the host sees a sentence rather than a parse failure.
+        if (response.status === 426) {
+            const update = updateLine(await safeJson(response));
+            options.write(`${staleClientFrame(frameId(line), update)}\n`);
+            options.error(`This copy of the Balladeer command is too old for ${options.controlPlane}. Update it with: ${update}\n`);
+            return 3;
+        }
+        const text = await response.text();
+        if (Buffer.byteLength(text, "utf8") > MAX_RESPONSE_BYTES) {
+            options.error("Balladeer refused a response frame larger than 4 MiB.\n");
+            return 5;
+        }
+        options.write(`${text.replace(/\n+$/, "")}\n`);
+    }
+    return 0;
+}

package/dist/commands/prepare.d.ts

@@ -0,0 +1,74 @@
+export type PrepareOptions = Readonly<{
+    controlPlane: string;
+    json: boolean;
+    promiseId: string;
+    /** Prepare a replacement, invalidating the packet nobody has spent. */
+    again: boolean;
+    /** The repository whose connection to use, named as `owner/name`. */
+    repo?: string;
+    /** The repository whose connection to use, named by id, as `mcp` takes it. */
+    repository?: string;
+    environment: NodeJS.ProcessEnv;
+    cwd: string;
+    write: (text: string) => void;
+}>;
+/**
+ * A refusal Balladeer wrote, as this terminal has to say it.
+ *
+ * Two changes and no others. The instants move onto the reader's own clock,
+ * because the server writes UTC and "already prepared by Robert Clark on
+ * 2026-09-07T18:05:10.698Z" reached somebody whose clock said two in the
+ * afternoon. And the argument is named the way this command takes it. Every
+ * other word, including what to do next and why, is the server's.
+ */
+export declare function atThisTerminal(text: string): string;
+/**
+ * The six keys the sealed run reads, and nothing else.
+ *
+ * The runner rejects an unknown field outright, so a metadata file that carried
+ * a helpful comment, a timestamp, or the whole packet would fail the customer's
+ * protected run for a reason that had nothing to do with their behavior. This
+ * command therefore writes the packet's own `qualificationMetadata` object and
+ * refuses to write anything it does not recognise.
+ */
+declare const METADATA_KEYS: readonly ["schemaVersion", "workspaceLocator", "receiptId", "revisionId", "bindingId", "workflowDigest"];
+type Metadata = Record<(typeof METADATA_KEYS)[number], string>;
+export declare function readQualificationMetadata(structured: unknown): Readonly<{
+    ok: true;
+    value: Metadata;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Where the file goes, refusing any path that would leave this repository.
+ *
+ * The path comes off the server's answer, and the whole point of this command is
+ * that it writes a file the person did not type. A server that answered with
+ * `../../etc/something` would otherwise have this command write there, so the
+ * resolved path has to stay under the directory the command was run in.
+ */
+export declare function metadataDestination(cwd: string, metadataPath: string): Readonly<{
+    ok: true;
+    path: string;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Prepares the one-time qualification setup for one promise, and writes the file
+ * where the sealed run reads it.
+ *
+ * It runs over this repository's own agent connection, which is what makes it
+ * usable at all: preparing a qualification setup is the agent's job, and the
+ * setup session that paired the machine expires. There is no sign-off here and
+ * no code to paste. Agreeing the meaning was the person's act; building the
+ * check that proves it is this command's caller's.
+ *
+ * The file is written once. A second run while nobody has published against the
+ * first packet is refused, naming who prepared it and when, and `--again` mints
+ * a replacement that invalidates the earlier one on the server as well as
+ * overwriting the file here.
+ */
+export declare function runPrepare(options: PrepareOptions): Promise<number>;
+export {};