balladeer 1.0.6 → 1.0.8

package/dist/guidance.js

@@ -0,0 +1,293 @@
+import { CLIENT_HEADER, CLIENT_HEADER_VALUE } from "./wire.js";
+import { createHash, randomBytes } from "node:crypto";
+import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { configHome } from "./store.js";
+export const GUIDANCE_UNAVAILABLE = "Balladeer could not verify the current workspace guidance and capture mode. Continue the user's authorized work, but do not make unsolicited capture offers or file inferred promises. Do not reuse earlier Quiet/Thorough permission or cached instructions as current. An explicit request to record still requires current Balladeer tool checks and named-human agreement to meaning; never invent approval. Retry current guidance at the next hook boundary.";
+const HEX = /^[a-f0-9]{64}$/;
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i;
+const MAX_BYTES = 40_000;
+const sha = (value) => createHash("sha256").update(value).digest("hex");
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function parseGuidance(value, agent) {
+    if (!object(value) ||
+        Object.keys(value).sort().join(",") !==
+            "captureStyle,digest,instructions,repositoryId,revision,schemaVersion,workspaceId" ||
+        value.schemaVersion !== 1 ||
+        value.workspaceId !== agent.workspaceId ||
+        value.repositoryId !== agent.repositoryId ||
+        typeof value.revision !== "string" ||
+        !/^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$/.test(value.revision) ||
+        typeof value.digest !== "string" ||
+        !HEX.test(value.digest) ||
+        !["quiet", "thorough", "off"].includes(String(value.captureStyle)) ||
+        typeof value.instructions !== "string" ||
+        value.instructions.length === 0 ||
+        value.instructions.length > 8_000 ||
+        sha(value.instructions) !== value.digest) {
+        throw new Error("invalid_guidance");
+    }
+    return value;
+}
+export function guidanceEndpoint(agent) {
+    const url = new URL(agent.mcpUrl);
+    const expected = new URL(agent.controlPlane);
+    if (url.origin !== expected.origin ||
+        url.protocol !== "https:" ||
+        url.pathname !== "/api/mcp" ||
+        url.username ||
+        url.password ||
+        url.hash ||
+        !UUID.test(agent.workspaceId) ||
+        !UUID.test(agent.repositoryId))
+        throw new Error("invalid_guidance_scope");
+    for (const [key, value] of [
+        ["workspaceId", agent.workspaceId],
+        ["repositoryId", agent.repositoryId],
+    ]) {
+        if (url.searchParams.getAll(key).length > 1 ||
+            (url.searchParams.has(key) && url.searchParams.get(key) !== value))
+            throw new Error("invalid_guidance_scope");
+        url.searchParams.set(key, value);
+    }
+    url.pathname = "/api/agent-guidance";
+    return url;
+}
+function readJson(path) {
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > MAX_BYTES || (stat.mode & 0o077) !== 0)
+            return undefined;
+        return JSON.parse(readFileSync(fd, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function privateDirectory(path) {
+    try {
+        mkdirSync(path, { mode: 0o700 });
+    }
+    catch {
+        /* Existing private directory is checked below. */
+    }
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0)
+        throw new Error("cache_unavailable");
+}
+function atomicJson(path, value) {
+    const temporary = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+    try {
+        writeFileSync(temporary, `${JSON.stringify(value)}\n`, { flag: "wx", mode: 0o600 });
+        renameSync(temporary, path);
+    }
+    finally {
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            /* Renamed or never created. */
+        }
+    }
+}
+export function guidanceScopeKey(agent) {
+    return sha(JSON.stringify([
+        new URL(agent.controlPlane).origin,
+        sha(agent.token),
+        agent.workspaceId,
+        agent.repositoryId,
+        1,
+    ]));
+}
+function cacheDirectory(environment) {
+    const home = configHome(environment);
+    privateDirectory(home);
+    const directory = join(home, "guidance-v1");
+    privateDirectory(directory);
+    return directory;
+}
+function cached(directory, scopeKey, agent) {
+    try {
+        const pointer = readJson(join(directory, `${scopeKey}.current.json`));
+        if (!object(pointer) || typeof pointer.key !== "string" || !HEX.test(pointer.key))
+            return undefined;
+        const body = readJson(join(directory, `${pointer.key}.body.json`));
+        if (!object(body) || typeof body.etag !== "string" || !/^"[a-f0-9]{64}"$/.test(body.etag))
+            return undefined;
+        const document = parseGuidance(body.document, agent);
+        if (pointer.key !== sha(JSON.stringify([scopeKey, document.revision])))
+            return undefined;
+        return { document, etag: body.etag, key: pointer.key };
+    }
+    catch {
+        return undefined;
+    }
+}
+async function boundedBody(response) {
+    const declared = Number(response.headers.get("content-length") ?? 0);
+    if (declared > MAX_BYTES)
+        throw new Error("guidance_oversized");
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error("guidance_empty");
+    const buffers = [];
+    let bytes = 0;
+    try {
+        while (true) {
+            const part = await reader.read();
+            if (part.done)
+                break;
+            bytes += part.value.byteLength;
+            if (bytes > MAX_BYTES)
+                throw new Error("guidance_oversized");
+            buffers.push(part.value);
+        }
+        return JSON.parse(Buffer.concat(buffers).toString("utf8"));
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+}
+/** Never returns stale instructions: even a cache hit requires a fresh scoped server response. */
+export async function loadGuidance(input) {
+    const scopeKey = guidanceScopeKey(input.agent);
+    let directory;
+    try {
+        directory = cacheDirectory(input.environment);
+    }
+    catch {
+        /* Cache is optional. */
+    }
+    const previous = directory ? cached(directory, scopeKey, input.agent) : undefined;
+    const abort = new AbortController();
+    let timer;
+    try {
+        const task = async () => {
+            const response = await (input.fetchImpl ?? fetch)(guidanceEndpoint(input.agent), {
+                method: "GET",
+                redirect: "manual",
+                signal: abort.signal,
+                headers: {
+                    authorization: `Bearer ${input.agent.token}`,
+                    [CLIENT_HEADER]: CLIENT_HEADER_VALUE,
+                    accept: "application/json",
+                    ...(previous ? { "if-none-match": previous.etag } : {}),
+                },
+            });
+            if (response.status === 304) {
+                if (!previous ||
+                    response.headers.get("etag") !== previous.etag ||
+                    response.headers.get("x-balladeer-guidance-revision") !== previous.document.revision) {
+                    throw new Error("invalid_guidance_revalidation");
+                }
+                return { status: "revalidated", document: previous.document, scopeKey };
+            }
+            if (response.status !== 200) {
+                await response.body?.cancel();
+                throw new Error("guidance_unavailable");
+            }
+            const document = parseGuidance(await boundedBody(response), input.agent);
+            const etag = response.headers.get("etag");
+            if (!etag ||
+                !/^"[a-f0-9]{64}"$/.test(etag) ||
+                response.headers.get("x-balladeer-guidance-revision") !== document.revision)
+                throw new Error("invalid_guidance_headers");
+            // Do not let a late, nonconforming transport populate cache after the deadline.
+            if (abort.signal.aborted)
+                throw new Error("guidance_deadline");
+            if (directory) {
+                try {
+                    const key = sha(JSON.stringify([scopeKey, document.revision]));
+                    atomicJson(join(directory, `${key}.body.json`), { document, etag });
+                    atomicJson(join(directory, `${scopeKey}.current.json`), { key });
+                    if (previous && previous.key !== key) {
+                        try {
+                            unlinkSync(join(directory, `${previous.key}.body.json`));
+                        }
+                        catch {
+                            /* Concurrent cache is optional. */
+                        }
+                    }
+                }
+                catch {
+                    /* Fresh guidance remains usable without disk caching. */
+                }
+            }
+            return { status: "fresh", document, scopeKey };
+        };
+        return await Promise.race([
+            task(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    abort.abort();
+                    reject(new Error("guidance_deadline"));
+                }, Math.min(input.timeoutMs ?? 1000, 1000));
+            }),
+        ]);
+    }
+    catch {
+        abort.abort();
+        return { status: "unavailable", scopeKey };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/** Writes context first, then records emission metadata; this never claims model receipt. */
+export function recordGuidanceContext(input, write) {
+    const always = input.event !== "UserPromptSubmit" || input.load.status === "unavailable" || !input.sessionId;
+    const contextKey = sha(JSON.stringify([
+        input.scopeKey,
+        input.hook,
+        input.sessionId ?? randomBytes(16).toString("hex"),
+        input.agentId ?? "root",
+    ]));
+    const document = input.load.document;
+    let path;
+    let emitted = true;
+    try {
+        path = join(cacheDirectory(input.environment), `${contextKey}.context.json`);
+        const previous = readJson(path);
+        emitted =
+            always ||
+                !object(previous) ||
+                previous.status === "unavailable" ||
+                previous.digest !== document?.digest ||
+                previous.revision !== document?.revision ||
+                (previous.runtimeGeneration ?? null) !== (input.runtimeGeneration ?? null);
+    }
+    catch {
+        /* Cache failure requires emission. */
+    }
+    if (!emitted)
+        return false;
+    write();
+    if (path) {
+        try {
+            atomicJson(path, {
+                schemaVersion: 1,
+                contextKey,
+                event: input.event,
+                status: input.load.status,
+                digest: document?.digest ?? null,
+                revision: document?.revision ?? null,
+                runtimeGeneration: input.runtimeGeneration ?? null,
+                emitted: true,
+                emittedAt: new Date(input.now ?? Date.now()).toISOString(),
+            });
+        }
+        catch {
+            /* An unwritten receipt causes another emission, never a skipped one. */
+        }
+    }
+    return true;
+}

package/dist/install.d.ts

@@ -19,5 +19,7 @@ export declare function runInstall(options: InstallOptions & {
     json: boolean;
     write: (text: string) => void;
     allowPartial?: boolean;
+    /** Carried into the one JSON object this prints, never as a second line. */
+    extra?: Record<string, unknown>;
 }): number;
 export {};

package/dist/install.js

@@ -344,6 +344,7 @@ export function runInstall(options) {
                 ...result,
                 status: result.manualPathRequired ? "path_pending" : result.status,
                 message,
+                ...(options.extra ?? {}),
             }) + "\n"
             : message + "\n");
         return result.manualPathRequired && !options.allowPartial ? 4 : 0;
@@ -353,7 +354,12 @@ export function runInstall(options) {
             ? error.message
             : "Installation could not access a required local file or command. Allow the reported installer operation and retry; no pairing has started.";
         options.write(options.json
-            ? JSON.stringify({ step: "install", status: "blocked", message }) + "\n"
+            ? JSON.stringify({
+                step: "install",
+                status: "blocked",
+                message,
+                ...(options.extra ?? {}),
+            }) + "\n"
             : message + "\n");
         return 4;
     }

package/dist/quiet.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Where a person said "not here".
+ *
+ * With Balladeer registered once per laptop, every session in every folder
+ * asks whether this folder is tracked. In one that is not, the hook says so
+ * once and names the command that would track it; a person who does not want
+ * to hear that again in a scratch clone silences the folder, and one who does
+ * not want it for a whole product silences the remote. The default is the
+ * folder, because "not here" usually means this checkout and not the repository.
+ */
+export type QuietList = Readonly<{
+    schemaVersion: 1;
+    folders: string[];
+    remotes: string[];
+}>;
+export declare function quietPath(environment?: NodeJS.ProcessEnv): string;
+export declare function readQuiet(environment?: NodeJS.ProcessEnv): QuietList;
+/** The folder a session is in, as git names it, so a worktree and a clone are
+ * each their own folder while the remote stays one thing. */
+export declare function folderKey(cwd: string): string;
+export declare function isQuiet(cwd: string, environment?: NodeJS.ProcessEnv): boolean;
+export declare function setQuiet(cwd: string, scope: "folder" | "repo", quiet: boolean, environment?: NodeJS.ProcessEnv): {
+    key: string;
+    changed: boolean;
+};

package/dist/quiet.js

@@ -0,0 +1,73 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { writeJsonAtomically } from "./mcp-config.js";
+import { repositoryHint } from "./repository.js";
+import { configHome } from "./store.js";
+const EMPTY = { schemaVersion: 1, folders: [], remotes: [] };
+export function quietPath(environment = process.env) {
+    return join(configHome(environment), "quiet.json");
+}
+export function readQuiet(environment = process.env) {
+    const path = quietPath(environment);
+    if (!existsSync(path))
+        return EMPTY;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed.schemaVersion !== 1)
+            return EMPTY;
+        return {
+            schemaVersion: 1,
+            folders: Array.isArray(parsed.folders) ? parsed.folders.filter(isString) : [],
+            remotes: Array.isArray(parsed.remotes) ? parsed.remotes.filter(isString) : [],
+        };
+    }
+    catch {
+        return EMPTY;
+    }
+}
+const isString = (value) => typeof value === "string";
+function writeQuiet(list, environment) {
+    mkdirSync(configHome(environment), { recursive: true, mode: 0o700 });
+    writeJsonAtomically(quietPath(environment), JSON.stringify(list, null, 2) + "\n");
+}
+/** The folder a session is in, as git names it, so a worktree and a clone are
+ * each their own folder while the remote stays one thing. */
+export function folderKey(cwd) {
+    try {
+        return realpathSync(execFileSync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 1000,
+        }).trim());
+    }
+    catch {
+        return realpathSync(cwd);
+    }
+}
+export function isQuiet(cwd, environment = process.env) {
+    const list = readQuiet(environment);
+    const folder = folderKey(cwd);
+    const remote = repositoryHint(cwd);
+    return (list.folders.includes(folder) ||
+        (remote !== "unknown/unknown" &&
+            list.remotes.some((r) => r.toLowerCase() === remote.toLowerCase())));
+}
+export function setQuiet(cwd, scope, quiet, environment = process.env) {
+    const list = readQuiet(environment);
+    const key = scope === "folder" ? folderKey(cwd) : repositoryHint(cwd);
+    if (scope === "repo" && key === "unknown/unknown")
+        throw new Error("This folder has no GitHub origin remote, so there is no repository to name.");
+    const field = scope === "folder" ? "folders" : "remotes";
+    const has = list[field].some((x) => x.toLowerCase() === key.toLowerCase());
+    if (has === quiet)
+        return { key, changed: false };
+    const next = {
+        ...list,
+        [field]: quiet
+            ? [...list[field], key]
+            : list[field].filter((x) => x.toLowerCase() !== key.toLowerCase()),
+    };
+    writeQuiet(next, environment);
+    return { key, changed: true };
+}

package/dist/user-scope.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Install Balladeer once per laptop.
+ *
+ * Setup used to write two files into one repository checkout, uncommitted: an
+ * `.mcp.json` entry and a hook in `.claude/settings.json`. A coding host lists
+ * a project server only when that exact folder is open, so every other clone,
+ * every worktree and every teammate saw nothing, and `/mcp` on two laptops
+ * showed only the legacy server. This registers the same server and the same
+ * hook at the host's user scope instead: one entry that runs in every session,
+ * and decides at run time, from the folder's git remote, which connection it
+ * is for. Nothing to commit and nothing per folder.
+ *
+ * Every write here is an additive merge that refuses to touch an entry it does
+ * not own, exactly as the project writers do. What it owns is recognised by
+ * shape, never by trust in the name.
+ */
+export declare const USER_SCOPE_OWNER = "Balladeer current guidance (user scope, loader 1)";
+export type UserScopeHost = "claude" | "codex";
+export type UserScopeWrite = Readonly<{
+    host: UserScopeHost;
+    path: string;
+    status: "current" | "written" | "refused";
+    reason?: string;
+}>;
+/** The command a host runs to reach Balladeer, with no repository named: the
+ * directory decides. The published form is what a laptop gets; the checkout
+ * form exists so this repository's own tests can point a host at source. */
+export declare function userScopeCommand(published: boolean): {
+    command: string;
+    args: string[];
+};
+/** `~/.claude.json` carries the user-scope MCP list under `mcpServers`. */
+export declare function mergeClaudeUserMcp(home: string, published: boolean): UserScopeWrite;
+/** Ours when it runs `npx` on our published specifier, or `node` on this
+ * checkout's entry file, with `mcp` as the subcommand and no repository named:
+ * a repository argument at user scope would pin every folder to one connection. */
+export declare function isOurUserEntry(entry: unknown): boolean;
+/** `~/.claude/settings.json` carries user-scope hooks. */
+export declare function mergeClaudeUserHooks(home: string, published: boolean): UserScopeWrite;
+/** `~/.codex/config.toml` carries both the server and the hooks for Codex, in
+ * one fenced block this command owns end to end. */
+export declare function mergeCodexUserConfig(home: string, published: boolean): UserScopeWrite;
+/** A copy of this command running out of a source checkout registers the
+ * checkout; any installed or npx copy registers the published package. */
+export declare function runningFromCheckout(entry?: string): boolean;
+/** The home whose host files get the entries. `BALLADEER_USER_HOME` exists for
+ * this repository's own tests, which cannot move HOME under a Volta-managed
+ * Node without losing Node. */
+export declare function userHome(environment?: NodeJS.ProcessEnv): string;
+/** Register both hosts. Codex is skipped, not refused, on a laptop without it. */
+export declare function installUserScope(options: {
+    environment: NodeJS.ProcessEnv;
+    published: boolean;
+    home?: string;
+}): UserScopeWrite[];