@bubblebrain-ai/bubble 0.0.63 → 0.0.64

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 {};

package/dist/hooks/trust.js

@@ -0,0 +1,143 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { getBubbleHome } from "../bubble-home.js";
+export function getHookTrustPath(options = {}) {
+    return join(options.bubbleHome ?? getBubbleHome(), "hooks-trust.json");
+}
+export function buildProjectHookFingerprint(cwd, projectSettingsPath, projectRules) {
+    const cwdRealpath = safeRealpath(cwd);
+    const projectKey = sha256(cwdRealpath);
+    const files = collectRuleFiles(projectSettingsPath, projectRules);
+    const stableRules = projectRules.map((rule) => ({
+        id: rule.id,
+        events: rule.events,
+        matcher: rule.matcher,
+        command: rule.command,
+        onError: rule.onError,
+        include: rule.include,
+        exposeToModel: rule.exposeToModel,
+        inheritToSubagents: rule.inheritToSubagents,
+        priority: rule.priority,
+    }));
+    const fingerprint = sha256(JSON.stringify({
+        cwdRealpath,
+        projectSettingsPath: safeRealpath(projectSettingsPath),
+        projectSettingsHash: hashFileIfExists(projectSettingsPath),
+        rules: stableRules,
+        files,
+    }));
+    return {
+        projectKey,
+        cwdRealpath,
+        fingerprint,
+        projectSettingsPath,
+        ruleCount: projectRules.length,
+        files,
+    };
+}
+export function readHookTrustStore(options = {}) {
+    const path = getHookTrustPath(options);
+    if (!existsSync(path))
+        return { version: 1, projects: {} };
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (!parsed || typeof parsed !== "object" || parsed.version !== 1 || typeof parsed.projects !== "object") {
+            return { version: 1, projects: {} };
+        }
+        return parsed;
+    }
+    catch {
+        return { version: 1, projects: {} };
+    }
+}
+export function writeHookTrustStore(store, options = {}) {
+    const path = getHookTrustPath(options);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(store, null, 2) + "\n", "utf-8");
+}
+export function isProjectHookFingerprintTrusted(fingerprint, options = {}) {
+    if (!fingerprint)
+        return { trusted: true };
+    const store = readHookTrustStore(options);
+    const trusted = store.projects[fingerprint.projectKey];
+    return {
+        trusted: trusted?.fingerprint === fingerprint.fingerprint,
+        trustedFingerprint: trusted?.fingerprint,
+    };
+}
+export function trustProjectHooks(fingerprint, options = {}) {
+    const store = readHookTrustStore(options);
+    store.projects[fingerprint.projectKey] = {
+        cwdRealpath: fingerprint.cwdRealpath,
+        fingerprint: fingerprint.fingerprint,
+        trustedAt: new Date().toISOString(),
+        projectSettingsPath: fingerprint.projectSettingsPath,
+        ruleCount: fingerprint.ruleCount,
+    };
+    writeHookTrustStore(store, options);
+}
+export function untrustProjectHooks(projectKey, options = {}) {
+    const store = readHookTrustStore(options);
+    if (!store.projects[projectKey])
+        return false;
+    delete store.projects[projectKey];
+    writeHookTrustStore(store, options);
+    return true;
+}
+function collectRuleFiles(projectSettingsPath, projectRules) {
+    const files = new Map();
+    const settingsHash = hashFileIfExists(projectSettingsPath);
+    if (settingsHash)
+        files.set(safeRealpath(projectSettingsPath), settingsHash);
+    for (const rule of projectRules) {
+        for (const candidate of [rule.command.command, ...(rule.command.args ?? [])]) {
+            const path = resolveExistingFile(candidate, rule.source);
+            if (!path)
+                continue;
+            const hash = hashFileIfExists(path);
+            if (hash)
+                files.set(safeRealpath(path), hash);
+        }
+    }
+    return [...files.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([path, sha]) => ({ path, sha256: sha }));
+}
+function resolveExistingFile(value, source) {
+    if (!value || !looksLikePath(value))
+        return undefined;
+    const path = isAbsolute(value) ? value : resolve(dirname(source.path), value);
+    try {
+        if (existsSync(path) && statSync(path).isFile())
+            return path;
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function looksLikePath(value) {
+    return value.startsWith(".") || value.startsWith("/") || value.includes("/");
+}
+function hashFileIfExists(path) {
+    try {
+        if (!existsSync(path) || !statSync(path).isFile())
+            return undefined;
+        return sha256(readFileSync(path));
+    }
+    catch {
+        return undefined;
+    }
+}
+function safeRealpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}

package/dist/hooks/types.d.ts

@@ -0,0 +1,173 @@
+import type { ApprovalDecision, ApprovalRequest } from "../approval/types.js";
+import type { ContentPart, PermissionMode, ToolResult } from "../types.js";
+export type HookEventName = "SessionStart" | "SessionEnd" | "UserPromptSubmit" | "PreModelCall" | "PreToolUse" | "PostToolUse" | "PostToolUseFailure" | "PermissionRequest" | "PermissionResult" | "Stop" | "StopFailure" | "PreCompact" | "PostCompact" | "SubagentStart" | "SubagentStop" | "Notification" | "SteerInputApplied" | "QueuedInputRejected";
+export declare const HOOK_EVENT_NAMES: readonly HookEventName[];
+export declare const BLOCKABLE_HOOK_EVENTS: Set<HookEventName>;
+export type HookSourceScope = "user" | "project" | "local";
+export type HookAgentRole = "parent" | "subagent" | "driver";
+export type HookFailurePolicy = "allow" | "block";
+export type HookDecision = "allow" | "deny";
+export interface HookCommandConfig {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+}
+export interface RawHookRule {
+    id?: unknown;
+    name?: unknown;
+    event?: unknown;
+    events?: unknown;
+    matcher?: unknown;
+    command?: unknown;
+    args?: unknown;
+    cwd?: unknown;
+    env?: unknown;
+    timeoutMs?: unknown;
+    maxOutputBytes?: unknown;
+    enabled?: unknown;
+    onError?: unknown;
+    failurePolicy?: unknown;
+    include?: unknown;
+    exposeToModel?: unknown;
+    inheritToSubagents?: unknown;
+    priority?: unknown;
+}
+export interface HookRule {
+    id: string;
+    events: HookEventName[];
+    matcher?: string;
+    command: HookCommandConfig;
+    timeoutMs: number;
+    maxOutputBytes: number;
+    enabled: boolean;
+    onError: HookFailurePolicy;
+    include: string[];
+    exposeToModel: boolean;
+    inheritToSubagents: boolean;
+    priority: number;
+}
+export interface HookRuleSource {
+    scope: HookSourceScope;
+    path: string;
+    index: number;
+}
+export interface LoadedHookRule extends HookRule {
+    source: HookRuleSource;
+    trusted: boolean;
+    trustRequired: boolean;
+}
+export interface HookDiagnostic {
+    scope: HookSourceScope;
+    path: string;
+    message: string;
+}
+export interface ProjectHookTrustStatus {
+    required: boolean;
+    trusted: boolean;
+    projectKey?: string;
+    fingerprint?: string;
+    trustedFingerprint?: string;
+    reason?: string;
+}
+export interface LoadedHookConfig {
+    rules: LoadedHookRule[];
+    diagnostics: HookDiagnostic[];
+    paths: Record<HookSourceScope, string>;
+    projectTrust: ProjectHookTrustStatus;
+}
+export interface HookEventEnvelope {
+    schemaVersion: 1;
+    eventName: HookEventName;
+    eventId: string;
+    timestamp: string;
+    cwd: string;
+    sessionId?: string;
+    runId?: string;
+    agentRole: HookAgentRole;
+    subAgentId?: string;
+    target?: string;
+    payload: Record<string, unknown>;
+    redacted: string[];
+}
+export interface HookRunRequest {
+    eventName: HookEventName;
+    cwd: string;
+    sessionId?: string;
+    runId?: string;
+    agentRole?: HookAgentRole;
+    subAgentId?: string;
+    target?: string;
+    payload?: Record<string, unknown>;
+    fullPayload?: Record<string, unknown>;
+}
+export interface HookRunSingleResult {
+    hookId: string;
+    eventName: HookEventName;
+    source: HookRuleSource;
+    decision: HookDecision;
+    reason?: string;
+    modelContext: string[];
+    exitCode?: number | null;
+    signal?: NodeJS.Signals | null;
+    elapsedMs: number;
+    stdout?: string;
+    stderr?: string;
+    truncated?: boolean;
+    error?: string;
+}
+export interface HookCombinedResult {
+    eventName: HookEventName;
+    decision: HookDecision;
+    reason?: string;
+    sourceHookId?: string;
+    source?: HookRuleSource;
+    modelContext: string[];
+    results: HookRunSingleResult[];
+    diagnostics: string[];
+    matched: number;
+}
+export interface HookProgressEvent {
+    type: "hook_start" | "hook_end" | "hook_error";
+    eventName: HookEventName;
+    hookId: string;
+    source: HookRuleSource;
+    elapsedMs?: number;
+    decision?: HookDecision;
+    reason?: string;
+    error?: string;
+}
+export interface HookRunnerResult {
+    decision: HookDecision;
+    reason?: string;
+    modelContext: string[];
+    exitCode?: number | null;
+    signal?: NodeJS.Signals | null;
+    elapsedMs: number;
+    stdout?: string;
+    stderr?: string;
+    truncated?: boolean;
+    error?: string;
+}
+export interface HookApprovalPayload {
+    request: Pick<ApprovalRequest, "type"> & Record<string, unknown>;
+    mode?: PermissionMode;
+}
+export interface HookApprovalResultPayload extends HookApprovalPayload {
+    decision: ApprovalDecision["action"];
+    feedback?: string;
+}
+export interface HookToolPayload {
+    id: string;
+    name: string;
+    argsPreview?: string;
+    args?: unknown;
+}
+export interface HookToolResultPayload extends HookToolPayload {
+    resultPreview?: string;
+    result?: ToolResult;
+    isError?: boolean;
+}
+export declare function isHookEventName(value: unknown): value is HookEventName;
+export declare function normalizeHookInput(input: string | ContentPart[]): Record<string, unknown>;
+export declare function truncateHookText(value: string, max?: number): string;

package/dist/hooks/types.js

@@ -0,0 +1,46 @@
+export const HOOK_EVENT_NAMES = [
+    "SessionStart",
+    "SessionEnd",
+    "UserPromptSubmit",
+    "PreModelCall",
+    "PreToolUse",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "PermissionRequest",
+    "PermissionResult",
+    "Stop",
+    "StopFailure",
+    "PreCompact",
+    "PostCompact",
+    "SubagentStart",
+    "SubagentStop",
+    "Notification",
+    "SteerInputApplied",
+    "QueuedInputRejected",
+];
+export const BLOCKABLE_HOOK_EVENTS = new Set([
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PermissionRequest",
+    "PreCompact",
+]);
+export function isHookEventName(value) {
+    return typeof value === "string" && HOOK_EVENT_NAMES.includes(value);
+}
+export function normalizeHookInput(input) {
+    if (typeof input === "string") {
+        return {
+            promptPreview: truncateHookText(input, 240),
+            promptLength: input.length,
+        };
+    }
+    return {
+        promptPreview: truncateHookText(JSON.stringify(input), 240),
+        contentParts: input.length,
+    };
+}
+export function truncateHookText(value, max = 2000) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, max)}...`;
+}

package/dist/loop/engine.d.ts

@@ -0,0 +1,29 @@
+/**
+ * /loop — recurring prompts (background-tasks design §2.6).
+ *
+ * Pure decision logic kept out of the TUI, mirroring goal/engine.ts: the TUI
+ * owns a 1s ticker and calls decideLoopFiring per loop; this module owns
+ * parsing, caps, and the defer-not-stack rule (a firing due while a turn is
+ * running reschedules with a notice instead of piling up).
+ */
+export interface LoopState {
+    id: number;
+    prompt: string;
+    intervalMs: number;
+    nextFireAt: number;
+    fires: number;
+}
+export declare const MAX_ACTIVE_LOOPS = 5;
+export declare const MIN_LOOP_INTERVAL_MS = 60000;
+export interface ParsedLoopCommand {
+    action: "start" | "list" | "stop" | "help";
+    intervalMs?: number;
+    prompt?: string;
+    stopId?: number;
+    error?: string;
+}
+export declare function parseLoopCommand(raw: string): ParsedLoopCommand;
+export type LoopFiringDecision = "fire" | "defer" | "wait";
+export declare function decideLoopFiring(loop: LoopState, now: number, turnRunning: boolean): LoopFiringDecision;
+export declare function formatLoopList(loops: LoopState[], now: number): string;
+export declare function formatInterval(intervalMs: number): string;