balladeer 0.0.4 → 1.0.0

package/dist/commands/invite.js

@@ -0,0 +1,197 @@
+import { ClientTooOldError, RefusalError, TransportError, request } from "../client.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 ${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/propose.d.ts

@@ -0,0 +1,59 @@
+export type ProposeOptions = Readonly<{
+    controlPlane: string;
+    json: boolean;
+    file?: string;
+    /** 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;
+}>;
+export type TeachBackRequest = Readonly<{
+    explicitIntent: string;
+    teachBack: Readonly<{
+        meaning: Record<string, unknown>;
+        unresolvedQuestions?: unknown;
+        proposedOwnerId?: unknown;
+        /** How sure whoever wrote this file was, 0 to 1. Read, never assumed. */
+        confidence: number;
+    }>;
+}>;
+/**
+ * The shape check that happens on the developer's machine, and the body it
+ * builds.
+ *
+ * `--file` reads whatever path it is handed, and an agent that mistypes one
+ * would otherwise upload a `.env`, a source file, or a log to a service whose
+ * whole boundary is that it never receives those. Refusing here means the wrong
+ * file never leaves the machine, rather than leaving it and being refused.
+ *
+ * So this returns the exact object to send rather than a verdict on the file.
+ * Spreading the parsed file into the request was the same mistake in a quieter
+ * form: whatever else the file happened to carry travelled with it, and the
+ * strict schema on the other side is a refusal after the fact, not a boundary.
+ */
+export declare function readTeachBackFile(raw: string): Readonly<{
+    ok: true;
+    value: TeachBackRequest;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Proposes one promise over this repository's own agent connection.
+ *
+ * It used to go over the delegated setup session, which lives for a bounded time
+ * and is meant for setting Balladeer up. That made proposing something a person
+ * could only do for a while after pairing: the credential expired, and a command
+ * whose whole job is "propose this" answered "run setup again". The connection
+ * this uses instead is the one setup issued for this repository, the same one
+ * the agent host forwards, and it does not expire.
+ *
+ * Nothing widens by moving: the call is `propose_promise` on the MCP endpoint,
+ * so it is authenticated as the agent principal, bound to that one repository,
+ * and refused everything except proposing. It lands as a candidate awaiting a
+ * named person's agreement, and nothing this command can do agrees to it.
+ */
+export declare function runPropose(options: ProposeOptions): Promise<number>;