@bubblebrain-ai/bubble 0.0.18 → 0.0.20

package/dist/hooks/controller.js

@@ -0,0 +1,254 @@
+import { randomUUID } from "node:crypto";
+import { explainHookEvent, formatHooksStatus, getProjectHookFingerprint, loadHookConfig, } from "./config.js";
+import { appendHookLog, readRecentHookLogs } from "./log.js";
+import { runHookCommand } from "./runner.js";
+import { trustProjectHooks, untrustProjectHooks } from "./trust.js";
+import { BLOCKABLE_HOOK_EVENTS, } from "./types.js";
+export class ExternalHookController {
+    options;
+    config;
+    disabledByDepth;
+    constructor(options) {
+        this.options = options;
+        this.config = loadHookConfig(options);
+        this.disabledByDepth = process.env.BUBBLE_HOOK_DEPTH === "1";
+    }
+    reload() {
+        this.config = loadHookConfig(this.options);
+        return this.config;
+    }
+    getConfig() {
+        return this.config;
+    }
+    status() {
+        return formatHooksStatus(this.config);
+    }
+    explain(eventName) {
+        return explainHookEvent(eventName, this.config);
+    }
+    logs(limit = 20) {
+        const entries = readRecentHookLogs(limit, this.options);
+        if (entries.length === 0)
+            return "No hook logs yet.";
+        return entries.map((entry) => {
+            const hook = entry.hookId ? ` ${entry.hookId}` : "";
+            const event = entry.eventName ? ` ${entry.eventName}` : "";
+            const decision = entry.decision ? ` ${entry.decision}` : "";
+            return `${entry.ts} [${entry.level}]${event}${hook}${decision} - ${entry.message}`;
+        }).join("\n");
+    }
+    trustProject() {
+        const fingerprint = getProjectHookFingerprint(this.options);
+        if (!fingerprint)
+            return "No project hooks are configured.";
+        trustProjectHooks(fingerprint, this.options);
+        this.reload();
+        return `Trusted project hooks for fingerprint ${fingerprint.fingerprint.slice(0, 12)}.`;
+    }
+    untrustProject() {
+        const key = this.config.projectTrust.projectKey;
+        if (!key)
+            return "No project hooks are configured.";
+        const changed = untrustProjectHooks(key, this.options);
+        this.reload();
+        return changed ? "Untrusted project hooks for this project." : "Project hooks were not trusted.";
+    }
+    async test(eventName, target) {
+        const result = await this.runEvent({
+            eventName,
+            cwd: this.options.cwd,
+            sessionId: this.options.sessionId,
+            agentRole: "driver",
+            target,
+            payload: {
+                test: true,
+                target,
+            },
+        });
+        return formatCombinedResult(result);
+    }
+    async runEvent(request, runOptions = {}) {
+        if (this.disabledByDepth) {
+            return emptyResult(request.eventName, ["Hooks disabled because BUBBLE_HOOK_DEPTH=1."]);
+        }
+        const agentRole = request.agentRole ?? "parent";
+        const candidates = this.config.rules.filter((rule) => {
+            if (!rule.enabled || !rule.trusted)
+                return false;
+            if (!rule.events.includes(request.eventName))
+                return false;
+            if (agentRole === "subagent" && !rule.inheritToSubagents)
+                return false;
+            return matchesRule(rule, request);
+        });
+        const diagnostics = [];
+        const results = [];
+        const modelContext = [];
+        const blockable = BLOCKABLE_HOOK_EVENTS.has(request.eventName);
+        let decision = "allow";
+        let reason;
+        let sourceHookId;
+        let source;
+        for (const rule of candidates) {
+            const start = {
+                type: "hook_start",
+                eventName: request.eventName,
+                hookId: rule.id,
+                source: rule.source,
+            };
+            runOptions.onProgress?.(start);
+            appendHookLog({
+                ts: new Date().toISOString(),
+                level: "info",
+                eventName: request.eventName,
+                hookId: rule.id,
+                message: "Hook started.",
+            }, this.options);
+            const envelope = buildEnvelope(rule, {
+                ...request,
+                sessionId: request.sessionId ?? this.options.sessionId,
+                agentRole,
+            });
+            const runnerResult = await runHookCommand(rule, envelope, { abortSignal: runOptions.abortSignal });
+            const single = {
+                hookId: rule.id,
+                eventName: request.eventName,
+                source: rule.source,
+                decision: runnerResult.decision,
+                reason: runnerResult.reason,
+                modelContext: runnerResult.modelContext,
+                exitCode: runnerResult.exitCode,
+                signal: runnerResult.signal,
+                elapsedMs: runnerResult.elapsedMs,
+                stdout: runnerResult.stdout,
+                stderr: runnerResult.stderr,
+                truncated: runnerResult.truncated,
+                error: runnerResult.error,
+            };
+            results.push(single);
+            modelContext.push(...runnerResult.modelContext);
+            if (runnerResult.error) {
+                const event = {
+                    type: "hook_error",
+                    eventName: request.eventName,
+                    hookId: rule.id,
+                    source: rule.source,
+                    elapsedMs: runnerResult.elapsedMs,
+                    decision: runnerResult.decision,
+                    reason: runnerResult.reason,
+                    error: runnerResult.error,
+                };
+                runOptions.onProgress?.(event);
+                appendHookLog({
+                    ts: new Date().toISOString(),
+                    level: runnerResult.decision === "deny" ? "error" : "warn",
+                    eventName: request.eventName,
+                    hookId: rule.id,
+                    decision: runnerResult.decision,
+                    message: runnerResult.error,
+                }, this.options);
+            }
+            else {
+                const event = {
+                    type: "hook_end",
+                    eventName: request.eventName,
+                    hookId: rule.id,
+                    source: rule.source,
+                    elapsedMs: runnerResult.elapsedMs,
+                    decision: runnerResult.decision,
+                    reason: runnerResult.reason,
+                };
+                runOptions.onProgress?.(event);
+                appendHookLog({
+                    ts: new Date().toISOString(),
+                    level: "info",
+                    eventName: request.eventName,
+                    hookId: rule.id,
+                    decision: runnerResult.decision,
+                    message: runnerResult.reason ?? "Hook completed.",
+                }, this.options);
+            }
+            if (runnerResult.decision === "deny" && !blockable) {
+                diagnostics.push(`${rule.id} returned deny for observe-only event ${request.eventName}; denial ignored.`);
+                continue;
+            }
+            if (runnerResult.decision === "deny") {
+                decision = "deny";
+                reason = runnerResult.reason ?? `Denied by hook ${rule.id}.`;
+                sourceHookId = rule.id;
+                source = rule.source;
+                break;
+            }
+        }
+        return {
+            eventName: request.eventName,
+            decision,
+            reason,
+            sourceHookId,
+            source,
+            modelContext,
+            results,
+            diagnostics,
+            matched: candidates.length,
+        };
+    }
+}
+function matchesRule(rule, request) {
+    if (!rule.matcher)
+        return true;
+    const target = request.target ?? JSON.stringify(request.payload ?? {});
+    return new RegExp(rule.matcher).test(target);
+}
+function buildEnvelope(rule, request) {
+    const payload = { ...(request.payload ?? {}) };
+    const redacted = [];
+    const full = request.fullPayload ?? {};
+    for (const [key, value] of Object.entries(full)) {
+        if (rule.include.includes("all") || rule.include.includes(key)) {
+            payload[key] = value;
+        }
+        else {
+            redacted.push(key);
+        }
+    }
+    return {
+        schemaVersion: 1,
+        eventName: request.eventName,
+        eventId: randomUUID(),
+        timestamp: new Date().toISOString(),
+        cwd: request.cwd,
+        sessionId: request.sessionId,
+        runId: request.runId,
+        agentRole: request.agentRole,
+        subAgentId: request.subAgentId,
+        target: request.target,
+        payload,
+        redacted,
+    };
+}
+function emptyResult(eventName, diagnostics = []) {
+    return {
+        eventName,
+        decision: "allow",
+        modelContext: [],
+        results: [],
+        diagnostics,
+        matched: 0,
+    };
+}
+function formatCombinedResult(result) {
+    const lines = [
+        `Hook test ${result.eventName}: ${result.decision}${result.reason ? ` - ${result.reason}` : ""}`,
+        `Matched: ${result.matched}`,
+    ];
+    for (const item of result.results) {
+        const suffix = item.reason ? ` - ${item.reason}` : item.error ? ` - ${item.error}` : "";
+        lines.push(`  ${item.decision} ${item.hookId} (${item.elapsedMs}ms)${suffix}`);
+    }
+    if (result.diagnostics.length) {
+        lines.push("Diagnostics:");
+        for (const diagnostic of result.diagnostics)
+            lines.push(`  ${diagnostic}`);
+    }
+    return lines.join("\n");
+}

package/dist/hooks/index.d.ts

@@ -0,0 +1,6 @@
+export { ExternalHookController } from "./controller.js";
+export type { ExternalHookControllerOptions, HookRunOptions } from "./controller.js";
+export { loadHookConfig, formatHooksStatus, explainHookEvent } from "./config.js";
+export { runHookCommand } from "./runner.js";
+export { HOOK_EVENT_NAMES, BLOCKABLE_HOOK_EVENTS, isHookEventName, normalizeHookInput, truncateHookText, } from "./types.js";
+export type { HookAgentRole, HookCombinedResult, HookDecision, HookEventName, HookProgressEvent, HookRunRequest, } from "./types.js";

package/dist/hooks/index.js

@@ -0,0 +1,4 @@
+export { ExternalHookController } from "./controller.js";
+export { loadHookConfig, formatHooksStatus, explainHookEvent } from "./config.js";
+export { runHookCommand } from "./runner.js";
+export { HOOK_EVENT_NAMES, BLOCKABLE_HOOK_EVENTS, isHookEventName, normalizeHookInput, truncateHookText, } from "./types.js";

package/dist/hooks/log.d.ts

@@ -0,0 +1,14 @@
+export interface HookLogEntry {
+    ts: string;
+    level: "info" | "warn" | "error";
+    eventName?: string;
+    hookId?: string;
+    decision?: string;
+    message: string;
+    detail?: Record<string, unknown>;
+}
+export interface HookLogOptions {
+    bubbleHome?: string;
+}
+export declare function appendHookLog(entry: HookLogEntry, options?: HookLogOptions): void;
+export declare function readRecentHookLogs(limit?: number, options?: HookLogOptions): HookLogEntry[];

package/dist/hooks/log.js

@@ -0,0 +1,54 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { getBubbleHome } from "../bubble-home.js";
+const MAX_RECENT_LOG_BYTES = 512 * 1024;
+export function appendHookLog(entry, options = {}) {
+    const bubbleHome = options.bubbleHome ?? getBubbleHome();
+    const dir = join(bubbleHome, "hooks");
+    try {
+        mkdirSync(dir, { recursive: true });
+        const file = join(dir, `${entry.ts.slice(0, 10)}.jsonl`);
+        appendFileSync(file, JSON.stringify(entry) + "\n", "utf-8");
+    }
+    catch {
+        // Hook logging must never affect the agent run.
+    }
+}
+export function readRecentHookLogs(limit = 30, options = {}) {
+    const bubbleHome = options.bubbleHome ?? getBubbleHome();
+    const dir = join(bubbleHome, "hooks");
+    if (!existsSync(dir))
+        return [];
+    try {
+        const files = readdirSync(dir)
+            .filter((file) => file.endsWith(".jsonl"))
+            .sort()
+            .reverse();
+        const lines = [];
+        for (const file of files) {
+            const path = join(dir, file);
+            const size = statSync(path).size;
+            const text = readFileSync(path, "utf-8");
+            const chunk = size > MAX_RECENT_LOG_BYTES
+                ? text.slice(Math.max(0, text.length - MAX_RECENT_LOG_BYTES))
+                : text;
+            lines.unshift(...chunk.trimEnd().split("\n").filter(Boolean));
+            if (lines.length >= limit)
+                break;
+        }
+        return lines
+            .slice(-limit)
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return undefined;
+            }
+        })
+            .filter((entry) => !!entry);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/hooks/runner.d.ts

@@ -0,0 +1,5 @@
+import type { HookEventEnvelope, HookRunnerResult, LoadedHookRule } from "./types.js";
+export interface HookRunnerOptions {
+    abortSignal?: AbortSignal;
+}
+export declare function runHookCommand(rule: LoadedHookRule, envelope: HookEventEnvelope, options?: HookRunnerOptions): Promise<HookRunnerResult>;

package/dist/hooks/runner.js

@@ -0,0 +1,225 @@
+import { spawn } from "node:child_process";
+import { performance } from "node:perf_hooks";
+import { truncateHookText } from "./types.js";
+const TERMINATE_GRACE_MS = 250;
+export async function runHookCommand(rule, envelope, options = {}) {
+    const startedAt = performance.now();
+    let stdout = "";
+    let stderr = "";
+    let truncated = false;
+    let timeout;
+    let settled = false;
+    return new Promise((resolve) => {
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeout)
+                clearTimeout(timeout);
+            resolve({
+                ...result,
+                elapsedMs: Math.round(performance.now() - startedAt),
+                stdout,
+                stderr,
+                truncated,
+            });
+        };
+        const child = spawn(rule.command.command, rule.command.args ?? [], {
+            cwd: rule.command.cwd ?? envelope.cwd,
+            env: buildHookEnv(rule, envelope),
+            shell: false,
+            detached: true,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        const terminate = (signal = "SIGTERM") => {
+            if (!child.pid)
+                return;
+            try {
+                process.kill(-child.pid, signal);
+            }
+            catch {
+                try {
+                    child.kill(signal);
+                }
+                catch {
+                    // ignore
+                }
+            }
+        };
+        const hardTerminateSoon = () => {
+            setTimeout(() => terminate("SIGKILL"), TERMINATE_GRACE_MS).unref?.();
+        };
+        const abortListener = () => {
+            terminate();
+            hardTerminateSoon();
+            finish({
+                decision: rule.onError === "block" ? "deny" : "allow",
+                reason: rule.onError === "block" ? "Hook aborted." : undefined,
+                modelContext: [],
+                error: "Hook aborted.",
+            });
+        };
+        options.abortSignal?.addEventListener("abort", abortListener, { once: true });
+        timeout = setTimeout(() => {
+            terminate();
+            hardTerminateSoon();
+            finish({
+                decision: rule.onError === "block" ? "deny" : "allow",
+                reason: rule.onError === "block" ? `Hook timed out after ${rule.timeoutMs}ms.` : undefined,
+                modelContext: [],
+                error: `Hook timed out after ${rule.timeoutMs}ms.`,
+            });
+        }, rule.timeoutMs);
+        child.on("error", (error) => {
+            finish({
+                decision: rule.onError === "block" ? "deny" : "allow",
+                reason: rule.onError === "block" ? error.message : undefined,
+                modelContext: [],
+                error: error.message,
+            });
+        });
+        child.stdout?.on("data", (chunk) => {
+            if (truncated)
+                return;
+            stdout += chunk.toString("utf-8");
+            if (Buffer.byteLength(stdout, "utf-8") > rule.maxOutputBytes) {
+                stdout = truncateByBytes(stdout, rule.maxOutputBytes);
+                truncated = true;
+                terminate();
+                hardTerminateSoon();
+            }
+        });
+        child.stderr?.on("data", (chunk) => {
+            if (Buffer.byteLength(stderr, "utf-8") > rule.maxOutputBytes)
+                return;
+            stderr += chunk.toString("utf-8");
+            if (Buffer.byteLength(stderr, "utf-8") > rule.maxOutputBytes) {
+                stderr = truncateByBytes(stderr, rule.maxOutputBytes);
+                truncated = true;
+            }
+        });
+        child.on("close", (exitCode, signal) => {
+            options.abortSignal?.removeEventListener("abort", abortListener);
+            const parsed = parseHookOutput(stdout);
+            const parseError = stdout.trim() && !parsed ? "Hook stdout was not valid JSON." : undefined;
+            const parsedContext = parsed ? extractModelContext(parsed, rule.exposeToModel) : [];
+            const parsedDecision = parsed?.decision === "block" ? "deny" : parsed?.decision;
+            const reason = typeof parsed?.reason === "string"
+                ? parsed.reason
+                : exitCode === 2
+                    ? firstNonEmpty(stderr, stdout, "Hook denied the event.")
+                    : undefined;
+            if (truncated) {
+                finish({
+                    decision: rule.onError === "block" ? "deny" : "allow",
+                    reason: rule.onError === "block" ? "Hook output exceeded the configured limit." : undefined,
+                    modelContext: [],
+                    exitCode,
+                    signal,
+                    error: "Hook output exceeded the configured limit.",
+                });
+                return;
+            }
+            if (parseError) {
+                finish({
+                    decision: rule.onError === "block" ? "deny" : "allow",
+                    reason: rule.onError === "block" ? parseError : undefined,
+                    modelContext: [],
+                    exitCode,
+                    signal,
+                    error: parseError,
+                });
+                return;
+            }
+            if (exitCode === 2 || parsedDecision === "deny") {
+                finish({
+                    decision: "deny",
+                    reason: reason ?? "Hook denied the event.",
+                    modelContext: parsedContext,
+                    exitCode,
+                    signal,
+                });
+                return;
+            }
+            if (exitCode && exitCode !== 0) {
+                const error = firstNonEmpty(stderr, stdout, `Hook exited with code ${exitCode}.`);
+                finish({
+                    decision: rule.onError === "block" ? "deny" : "allow",
+                    reason: rule.onError === "block" ? error : undefined,
+                    modelContext: parsedContext,
+                    exitCode,
+                    signal,
+                    error,
+                });
+                return;
+            }
+            finish({
+                decision: "allow",
+                reason,
+                modelContext: parsedContext,
+                exitCode,
+                signal,
+            });
+        });
+        child.stdin?.end(JSON.stringify(envelope));
+    });
+}
+function buildHookEnv(rule, envelope) {
+    const base = {};
+    for (const key of ["PATH", "HOME", "TMPDIR", "LANG", "LC_ALL", "SHELL"]) {
+        if (process.env[key])
+            base[key] = process.env[key];
+    }
+    return {
+        ...base,
+        ...(rule.command.env ?? {}),
+        BUBBLE_HOOK_DEPTH: "1",
+        BUBBLE_HOOK_ID: rule.id,
+        BUBBLE_HOOK_EVENT: envelope.eventName,
+        BUBBLE_HOOK_EVENT_ID: envelope.eventId,
+        BUBBLE_HOOK_CWD: envelope.cwd,
+    };
+}
+function parseHookOutput(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return {};
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function extractModelContext(parsed, ruleExposeToModel) {
+    const visible = parsed.visibleToModel === true || parsed.exposeToModel === true || ruleExposeToModel;
+    if (!visible)
+        return [];
+    const raw = parsed.modelContext ?? parsed.context;
+    if (typeof raw === "string")
+        return [truncateHookText(raw, 4000)];
+    if (Array.isArray(raw)) {
+        return raw
+            .filter((item) => typeof item === "string")
+            .map((item) => truncateHookText(item, 4000))
+            .slice(0, 8);
+    }
+    return [];
+}
+function truncateByBytes(value, maxBytes) {
+    const buffer = Buffer.from(value, "utf-8");
+    if (buffer.length <= maxBytes)
+        return value;
+    return buffer.subarray(0, maxBytes).toString("utf-8");
+}
+function firstNonEmpty(...values) {
+    for (const value of values) {
+        const trimmed = value.trim();
+        if (trimmed)
+            return truncateHookText(trimmed, 1000);
+    }
+    return "";
+}

package/dist/hooks/trust.d.ts

@@ -0,0 +1,37 @@
+import type { LoadedHookRule } from "./types.js";
+export interface ProjectHookFingerprint {
+    projectKey: string;
+    cwdRealpath: string;
+    fingerprint: string;
+    projectSettingsPath: string;
+    ruleCount: number;
+    files: Array<{
+        path: string;
+        sha256: string;
+    }>;
+}
+interface TrustedProjectHooks {
+    cwdRealpath: string;
+    fingerprint: string;
+    trustedAt: string;
+    projectSettingsPath: string;
+    ruleCount: number;
+}
+interface TrustStore {
+    version: 1;
+    projects: Record<string, TrustedProjectHooks>;
+}
+export interface TrustStoreOptions {
+    bubbleHome?: string;
+}
+export declare function getHookTrustPath(options?: TrustStoreOptions): string;
+export declare function buildProjectHookFingerprint(cwd: string, projectSettingsPath: string, projectRules: LoadedHookRule[]): ProjectHookFingerprint;
+export declare function readHookTrustStore(options?: TrustStoreOptions): TrustStore;
+export declare function writeHookTrustStore(store: TrustStore, options?: TrustStoreOptions): void;
+export declare function isProjectHookFingerprintTrusted(fingerprint: ProjectHookFingerprint | undefined, options?: TrustStoreOptions): {
+    trusted: boolean;
+    trustedFingerprint?: string;
+};
+export declare function trustProjectHooks(fingerprint: ProjectHookFingerprint, options?: TrustStoreOptions): void;
+export declare function untrustProjectHooks(projectKey: string, options?: TrustStoreOptions): boolean;
+export {};