balladeer 1.0.5 → 1.0.7

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.js

@@ -23,9 +23,10 @@ function commandOnPath(name, env) {
     }
     return undefined;
 }
-function execute(command, args, env) {
+function execute(command, args, env, cwd) {
     return execFileSync(command, args, {
         env,
+        ...(cwd ? { cwd } : {}),
         encoding: "utf8",
         stdio: ["ignore", "pipe", "pipe"],
         timeout: 120_000,
@@ -33,14 +34,14 @@ function execute(command, args, env) {
     }).trim();
 }
 /** Inspect package ownership before executing a command from PATH. */
-function packageVersion(command, env) {
+function packageVersion(command, env, cwd) {
     let entry = realpathSync(command);
     if (basename(entry) === "volta-shim") {
         const volta = commandOnPath("volta", env);
         if (!volta)
             return undefined;
         try {
-            entry = realpathSync(execute(volta, ["which", "balladeer"], env));
+            entry = realpathSync(execute(volta, ["which", "balladeer"], env, cwd));
         }
         catch {
             return undefined;
@@ -121,25 +122,114 @@ function shellProfiles(env, bin) {
         return { path, text, previous: old };
     });
 }
+function atLeastCurrent(version) {
+    if (!/^\d+\.\d+\.\d+$/.test(version))
+        return false;
+    const actual = version.split(".").map(Number), expected = CLI_VERSION.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        if (actual[i] !== expected[i])
+            return actual[i] > expected[i];
+    }
+    return true;
+}
+/** npm exec may put the actual Node-image bin ahead of Volta's registered shim. */
+function installWithVolta(env) {
+    const home = env.VOLTA_HOME ?? (env.HOME ? join(env.HOME, ".volta") : undefined);
+    const volta = commandOnPath("volta", env);
+    if (!home || !isAbsolute(home) || !volta)
+        return undefined;
+    const bin = join(home, "bin"), shim = join(bin, "balladeer");
+    const nodeShim = join(bin, "node");
+    // Merely having Volta somewhere on PATH must not select it for another toolchain.
+    const onPath = (env.PATH ?? "")
+        .split(delimiter)
+        .some((part) => resolve(part || ".") === resolve(bin));
+    const managedNode = existsSync(nodeShim) && basename(realpathSync(nodeShim)) === "volta-shim";
+    const imageDirectory = join(home, "tools/image/node");
+    const imageRoot = existsSync(imageDirectory)
+        ? realpathSync(imageDirectory)
+        : resolve(imageDirectory);
+    const selectedNode = commandOnPath("node", env);
+    const actualNode = selectedNode ? realpathSync(selectedNode) : undefined;
+    const activeToolchain = actualNode !== undefined &&
+        ((managedNode && actualNode === realpathSync(nodeShim)) ||
+            actualNode.startsWith(imageRoot + "/"));
+    if (!onPath || !managedNode || !activeToolchain)
+        return undefined;
+    const bootstrap = env.npm_command === "exec";
+    const parentEnv = {
+        ...env,
+        PATH: (env.PATH ?? "")
+            .split(delimiter)
+            .filter((part) => {
+            const full = resolve(part || ".");
+            if (full.split(/[\\/]/).includes("node_modules"))
+                return false;
+            return !(bootstrap &&
+                (existsSync(full) ? realpathSync(full) : full).startsWith(imageRoot + "/") &&
+                basename(full) === "bin");
+        })
+            .join(delimiter),
+    };
+    const selected = commandOnPath("balladeer", parentEnv);
+    if (selected && resolve(selected) !== resolve(shim))
+        throw new InstallError(`Another command precedes Volta at ${selected}. Resolve that PATH conflict before installing; nothing was overwritten.`);
+    if (existsSync(shim) && basename(realpathSync(shim)) !== "volta-shim")
+        throw new InstallError("Another command owns Volta's balladeer path. Nothing was overwritten.");
+    const neutral = mkdtempSync(join(tmpdir(), "balladeer-volta-install-"));
+    const installEnv = { ...parentEnv, npm_config_cache: join(neutral, "npm-cache") };
+    try {
+        let version = existsSync(shim) ? packageVersion(shim, installEnv, neutral) : undefined;
+        if (existsSync(shim) && version === undefined)
+            throw new InstallError("Volta's registered Balladeer package cannot be verified. Repair the toolchain before pairing.");
+        const alreadyCurrent = version !== undefined && atLeastCurrent(version);
+        if (!alreadyCurrent) {
+            try {
+                execute(volta, ["install", `balladeer@${CLI_VERSION}`], installEnv, neutral);
+            }
+            catch {
+                throw new InstallError("Volta could not install the exact Balladeer release. Check network and toolchain write access, then repeat npx -y balladeer@latest install. No pairing has started.");
+            }
+            version = existsSync(shim) ? packageVersion(shim, installEnv, neutral) : undefined;
+            if (version !== CLI_VERSION)
+                throw new InstallError("Volta finished, but its registered default is not the expected Balladeer release. No pairing has started.");
+        }
+        // Verify both the global default and what an ordinary fresh child in the
+        // caller's directory sees. A project override is never mistaken for a default.
+        if (!version ||
+            execute(shim, ["--version"], installEnv, neutral) !== version ||
+            commandOnPath("balladeer", parentEnv) !== shim ||
+            execute(shim, ["--version"], parentEnv) !== version)
+            throw new InstallError("Volta's default was checked, but this terminal or project selects a different Balladeer. Resolve its PATH or project tool pin before pairing.");
+        const shell = execute("/bin/sh", ["-c", "command -v balladeer; balladeer --version"], parentEnv).split("\n");
+        if (shell[0] !== shim || shell[1] !== version)
+            throw new InstallError("The fresh terminal PATH does not select the verified Volta command. No pairing has started.");
+        env.PATH = parentEnv.PATH;
+        return {
+            status: alreadyCurrent ? "current" : "installed",
+            command: shim,
+            version,
+            restartRequired: false,
+        };
+    }
+    finally {
+        rmSync(neutral, { recursive: true, force: true });
+    }
+}
 export function ensureInstalled(options) {
     const env = options.environment;
     const platform = options.platform ?? process.platform;
     if (platform === "win32")
         throw new InstallError("Automatic command installation currently supports macOS and Linux. On Windows, use npm install --global balladeer@latest, then verify balladeer --version. No files or pairing were changed.");
+    const managed = installWithVolta(env);
+    if (managed)
+        return managed;
     const current = commandOnPath("balladeer", env);
     if (current) {
         const version = packageVersion(current, env);
         if (version === undefined)
             throw new InstallError(`Another command already owns ${current}. Keep it intact and resolve that command conflict before installing Balladeer.`);
-        const newer = /^\d+\.\d+\.\d+$/.test(version) &&
-            version
-                .split(".")
-                .map(Number)
-                .some((part, index, parts) => part > Number(CLI_VERSION.split(".")[index]) &&
-                parts
-                    .slice(0, index)
-                    .every((value, before) => value === Number(CLI_VERSION.split(".")[before])));
-        if (version === CLI_VERSION || newer) {
+        if (atLeastCurrent(version)) {
             if (execute(current, ["--version"], env) !== version)
                 throw new InstallError("The installed Balladeer command does not run the expected version. Repair the installation before pairing.");
             return { status: "current", command: current, restartRequired: false, version };

package/dist/wire.d.ts

@@ -5,10 +5,10 @@
  * runtime dependency at all: Node 22 builtins and global fetch, nothing else.
  * A contract test compares the scope list below against the server's.
  */
-export declare const CLI_VERSION = "1.0.5";
+export declare const CLI_VERSION = "1.0.7";
 export declare const CLI_INVOCATION = "npx -y balladeer@latest";
 export declare const CLIENT_HEADER = "x-balladeer-client";
-export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.5";
+export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.7";
 export declare const DEFAULT_CONTROL_PLANE = "https://envelopes.balladeer.ai";
 export type DelegatedScope = "repository:enroll" | "agent:issue" | "ci:connect" | "workspace:invite" | "candidate:propose";
 export declare const DELEGATED_SCOPES: readonly DelegatedScope[];
@@ -222,6 +222,12 @@ export type ClaudeDesktopStep = Readonly<{
     reason?: string;
 }>;
 export type JsonStep = Readonly<{
+    step: "guidance_loader";
+    status: "installed_needs_host_trust" | "installed_trust_unverified" | "unavailable" | "not_applicable";
+    changed: boolean;
+    hosts: readonly ("codex" | "claude")[];
+    reason?: string;
+}> | Readonly<{
     step: "explain";
     version: string;
 }> | Readonly<{

package/dist/wire.js

@@ -5,7 +5,7 @@
  * runtime dependency at all: Node 22 builtins and global fetch, nothing else.
  * A contract test compares the scope list below against the server's.
  */
-export const CLI_VERSION = "1.0.5";
+export const CLI_VERSION = "1.0.7";
 export const CLI_INVOCATION = "npx -y balladeer@latest";
 export const CLIENT_HEADER = "x-balladeer-client";
 export const CLIENT_HEADER_VALUE = `balladeer/${CLI_VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "balladeer",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Set up Balladeer from your terminal, or from a coding agent's.",
   "license": "Apache-2.0",
   "private": false,
@@ -21,11 +21,12 @@
     "node": ">=22.0.0"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && node build-guidance.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "devDependencies": {
-    "typescript": "5.9.3"
+    "typescript": "5.9.3",
+    "esbuild": "0.25.12"
   },
   "dependencies": {
     "@iarna/toml": "2.2.5"