balladeer 0.0.5 → 1.0.1

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,48 @@
+#!/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;
+    /** `setup --force`: set up even though an earlier Balladeer is still installed. */
+    force: boolean;
+    /**
+     * `setup --claude-desktop` / `--no-claude-desktop`. Undefined is neither
+     * asked for nor refused, which is the ordinary run: connect the chat client
+     * where it is installed and say nothing where it is not.
+     */
+    claudeDesktop: boolean | undefined;
+    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;
+    /** `session --new`: start a different session even though one is current. */
+    fresh: boolean;
+    /** `session --record`: read the trailer out of HEAD and record that commit. */
+    record: boolean;
+    /** `prepare --again`: mint a replacement packet and invalidate the unspent one. */
+    again: 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 {};