balladeer 1.0.6 → 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/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.6";
+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.6";
+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.6";
+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.6",
+  "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"