@bubblebrain-ai/bubble 0.0.18 → 0.0.20

package/dist/approval/controller.js

@@ -1,4 +1,5 @@
 import { checkPermission } from "../permissions/rule.js";
+import { truncateHookText } from "../hooks/index.js";
 /**
  * Default ApprovalController. Decision tree:
  *
@@ -27,40 +28,48 @@ export class PermissionAwareApprovalController {
     }
     async request(req) {
         const ruleResult = this.checkRequestRules(req);
+        const finalize = async (decision) => {
+            await this.runPermissionResultHook(req, decision);
+            return decision;
+        };
         if (ruleResult.decision === "deny") {
-            return {
+            return finalize({
                 action: "reject",
                 feedback: `Blocked by deny rule: ${ruleResult.rule?.source ?? "<unknown>"}`,
-            };
+            });
         }
         const mode = this.options.getMode();
+        const hookDecision = await this.runPermissionRequestHook(req, mode, ruleResult.decision);
+        if (hookDecision.action === "reject") {
+            return finalize(hookDecision);
+        }
         if (mode === "bypassPermissions") {
-            return { action: "approve" };
+            return finalize({ action: "approve" });
         }
         if (mode === "default" && (req.type === "edit" || req.type === "write" || req.type === "patch")) {
-            return { action: "approve" };
+            return finalize({ action: "approve" });
         }
         if (mode === "plan") {
-            return {
+            return finalize({
                 action: "reject",
                 feedback: "Plan mode is active. Do not call destructive tools directly — propose your changes via exit_plan_mode and wait for user approval.",
-            };
+            });
         }
         if (ruleResult.decision === "allow") {
-            return { action: "approve" };
+            return finalize({ action: "approve" });
         }
         // Session-scoped allowlist: previously-approved bash prefixes skip the prompt.
         if (req.type === "bash" && this.options.bashAllowlist?.matches(req.command)) {
-            return { action: "approve" };
+            return finalize({ action: "approve" });
         }
         const handler = this.options.handlerRef.current;
         if (!handler) {
-            return {
+            return finalize({
                 action: "reject",
                 feedback: "No interactive UI is available to approve this tool call.",
-            };
+            });
         }
-        return handler(req);
+        return finalize(await handler(req));
     }
     requestToQuery(req) {
         switch (req.type) {
@@ -92,4 +101,88 @@ export class PermissionAwareApprovalController {
         }
         return { decision: "ask" };
     }
+    async runPermissionRequestHook(req, mode, ruleDecision) {
+        const hooks = this.options.externalHooks;
+        if (!hooks)
+            return { action: "approve" };
+        try {
+            const result = await hooks.runEvent({
+                eventName: "PermissionRequest",
+                cwd: this.options.cwd,
+                sessionId: this.options.sessionId,
+                agentRole: "driver",
+                target: approvalTarget(req),
+                payload: {
+                    request: summarizeApprovalRequest(req),
+                    mode,
+                    ruleDecision,
+                },
+                fullPayload: { permissionRequest: req },
+            });
+            if (result.decision === "deny") {
+                return {
+                    action: "reject",
+                    feedback: result.reason ?? `Blocked by hook ${result.sourceHookId ?? "<unknown>"}.`,
+                };
+            }
+        }
+        catch {
+            // Hook failures are handled by the hook controller policy and must not
+            // crash approval handling.
+        }
+        return { action: "approve" };
+    }
+    async runPermissionResultHook(req, decision) {
+        const hooks = this.options.externalHooks;
+        if (!hooks)
+            return;
+        try {
+            await hooks.runEvent({
+                eventName: "PermissionResult",
+                cwd: this.options.cwd,
+                sessionId: this.options.sessionId,
+                agentRole: "driver",
+                target: approvalTarget(req),
+                payload: {
+                    request: summarizeApprovalRequest(req),
+                    decision: decision.action,
+                    feedback: decision.feedback ? truncateHookText(decision.feedback, 500) : undefined,
+                },
+                fullPayload: {
+                    permissionRequest: req,
+                    permissionDecision: decision,
+                },
+            });
+        }
+        catch {
+            // Observe-only.
+        }
+    }
+}
+function approvalTarget(req) {
+    switch (req.type) {
+        case "bash":
+            return "Bash";
+        case "write":
+            return "Write";
+        case "edit":
+        case "patch":
+            return "Edit";
+        case "lsp":
+            return "Lsp";
+    }
+}
+function summarizeApprovalRequest(req) {
+    switch (req.type) {
+        case "bash":
+            return { type: req.type, commandPreview: truncateHookText(req.command, 500), cwd: req.cwd };
+        case "write":
+            return { type: req.type, path: req.path, fileExists: req.fileExists, contentLength: req.content.length };
+        case "edit":
+            return { type: req.type, path: req.path, fileExists: req.fileExists, diffLength: req.diff.length };
+        case "patch":
+            return { type: req.type, path: req.path, paths: req.paths, files: req.files, diffLength: req.diff.length };
+        case "lsp":
+            return { type: req.type, path: req.path, operation: req.operation };
+    }
 }

package/dist/debug-trace.js

@@ -181,6 +181,10 @@ export function summarizeAgentEventForTrace(event) {
         case "text_delta":
         case "reasoning_delta":
             return { type: event.type, content: summarizeTraceText(event.content) };
+        case "hook_start":
+        case "hook_end":
+        case "hook_error":
+            return { ...event };
         case "tool_call_start":
             return { type: event.type, id: event.id, name: event.name };
         case "tool_call_delta":

package/dist/feishu/agent-host/run-driver.js

@@ -17,6 +17,7 @@ import { BudgetLedger } from "../../agent/budget-ledger.js";
 import { PermissionAwareApprovalController } from "../../approval/controller.js";
 import { BashAllowlist } from "../../approval/session-cache.js";
 import { getLspService } from "../../lsp/index.js";
+import { ExternalHookController } from "../../hooks/index.js";
 import { buildSystemPrompt } from "../../system-prompt.js";
 import { FileStateTracker } from "../../tools/file-state.js";
 import { buildToolPromptOptions, createAllTools } from "../../tools/index.js";
@@ -41,6 +42,7 @@ export class RunDriver {
     async runOnce(req) {
         // 1. Resolve session
         const session = this.opts.binder.openOrBootstrap(req.scopeKey, req.scope.cwd, req.scope.defaultPermissionMode);
+        const hookController = new ExternalHookController({ cwd: session.cwd });
         // 2. Build approval controller wired to FeishuApprovalUI
         const bashAllowlist = new BashAllowlist();
         const approvalHandlerRef = {
@@ -53,6 +55,7 @@ export class RunDriver {
             bashAllowlist,
             cwd: session.cwd,
             getRuleSet: () => this.opts.deps.settingsManager.getMerged().ruleSet,
+            externalHooks: hookController,
         });
         // 3. Build tools + Agent
         const lspService = getLspService(session.cwd, this.opts.deps.settingsManager.getMerged().lsp);
@@ -137,6 +140,7 @@ export class RunDriver {
             fileStateTracker,
             agentCategories: this.opts.deps.userConfig.getAgentCategories(),
             providerFactory: (route) => this.opts.deps.createProviderForRoute(route, promptCacheKey),
+            externalHooks: hookController,
         });
         sessionTitleUpdater = createSessionTitleUpdater({
             sessionManager: session.manager,
@@ -150,6 +154,18 @@ export class RunDriver {
             thinkingLevel: agent.thinking,
             reasoningEffort: agent.thinking,
         });
+        await hookController.runEvent({
+            eventName: "SessionStart",
+            cwd: session.cwd,
+            sessionId: session.manager.getSessionFile(),
+            agentRole: "driver",
+            target: "feishu",
+            payload: {
+                chatId: req.chatId,
+                providerId,
+                model,
+            },
+        });
         // Restore prior history into the running Agent instance.
         if (!session.fresh) {
             const history = session.manager.getMessages();
@@ -248,6 +264,18 @@ export class RunDriver {
         }
         finally {
             clearInterval(watchdog);
+            await hookController.runEvent({
+                eventName: "SessionEnd",
+                cwd: session.cwd,
+                sessionId: session.manager.getSessionFile(),
+                agentRole: "driver",
+                target: "feishu",
+                payload: {
+                    chatId: req.chatId,
+                    providerId: agent.providerId,
+                    model: agent.apiModel,
+                },
+            });
             // Cancel any pending approval prompts attached to this run.
             this.opts.approvalUI.cancelForChat(req.chatId, "Run ended");
         }

package/dist/hooks/config.d.ts

@@ -0,0 +1,9 @@
+import { type ProjectHookFingerprint, type TrustStoreOptions } from "./trust.js";
+import { type HookEventName, type LoadedHookConfig } from "./types.js";
+export interface LoadHookConfigOptions extends TrustStoreOptions {
+    cwd: string;
+}
+export declare function loadHookConfig(options: LoadHookConfigOptions): LoadedHookConfig;
+export declare function getProjectHookFingerprint(options: LoadHookConfigOptions): ProjectHookFingerprint | undefined;
+export declare function formatHooksStatus(config: LoadedHookConfig): string;
+export declare function explainHookEvent(eventName: HookEventName, config: LoadedHookConfig): string;

package/dist/hooks/config.js

@@ -0,0 +1,278 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { getBubbleHome } from "../bubble-home.js";
+import { buildProjectHookFingerprint, isProjectHookFingerprintTrusted, } from "./trust.js";
+import { isHookEventName, } from "./types.js";
+const SCOPES = ["user", "project", "local"];
+const DEFAULT_TIMEOUT_MS = 5000;
+const MAX_TIMEOUT_MS = 600_000;
+const DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024;
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+export function loadHookConfig(options) {
+    const bubbleHome = options.bubbleHome ?? getBubbleHome();
+    const paths = {
+        user: join(bubbleHome, "settings.json"),
+        project: join(options.cwd, ".bubble", "settings.json"),
+        local: join(options.cwd, ".bubble", "settings.local.json"),
+    };
+    const diagnostics = [];
+    const rules = [];
+    for (const scope of SCOPES) {
+        const path = paths[scope];
+        const loaded = readHooksFile(scope, path);
+        diagnostics.push(...loaded.diagnostics);
+        if (!loaded.settings)
+            continue;
+        const parsed = parseHookSettings(scope, path, loaded.settings);
+        diagnostics.push(...parsed.diagnostics);
+        rules.push(...parsed.rules);
+    }
+    const projectRules = rules.filter((rule) => rule.source.scope === "project");
+    const fingerprint = projectRules.length > 0
+        ? buildProjectHookFingerprint(options.cwd, paths.project, projectRules)
+        : undefined;
+    const trust = isProjectHookFingerprintTrusted(fingerprint, { bubbleHome });
+    for (const rule of rules) {
+        if (rule.source.scope !== "project")
+            continue;
+        rule.trustRequired = true;
+        rule.trusted = trust.trusted;
+    }
+    return {
+        rules: rules.sort(compareRules),
+        diagnostics,
+        paths,
+        projectTrust: {
+            required: projectRules.length > 0,
+            trusted: trust.trusted,
+            projectKey: fingerprint?.projectKey,
+            fingerprint: fingerprint?.fingerprint,
+            trustedFingerprint: trust.trustedFingerprint,
+            reason: projectRules.length === 0
+                ? "No project hooks configured."
+                : trust.trusted
+                    ? "Project hooks are trusted for the current fingerprint."
+                    : "Project hooks are configured but not trusted for the current fingerprint.",
+        },
+    };
+}
+export function getProjectHookFingerprint(options) {
+    const loaded = loadHookConfig(options);
+    if (!loaded.projectTrust.required)
+        return undefined;
+    const projectRules = loaded.rules.filter((rule) => rule.source.scope === "project");
+    return buildProjectHookFingerprint(options.cwd, loaded.paths.project, projectRules);
+}
+export function formatHooksStatus(config) {
+    const lines = ["Hooks status:"];
+    lines.push(`  user:    ${config.paths.user}`);
+    lines.push(`  project: ${config.paths.project}`);
+    lines.push(`  local:   ${config.paths.local}`);
+    if (config.projectTrust.required) {
+        lines.push(`  project trust: ${config.projectTrust.trusted ? "trusted" : "not trusted"}`
+            + (config.projectTrust.fingerprint ? ` (${config.projectTrust.fingerprint.slice(0, 12)})` : ""));
+    }
+    else {
+        lines.push("  project trust: not required");
+    }
+    lines.push("", `Rules (${config.rules.length}):`);
+    if (config.rules.length === 0) {
+        lines.push("  (none)");
+    }
+    else {
+        for (const rule of config.rules) {
+            const state = rule.enabled && rule.trusted ? "enabled" : rule.enabled ? "untrusted" : "disabled";
+            const matcher = rule.matcher ? ` matcher=${rule.matcher}` : "";
+            lines.push(`  ${state} ${rule.id} [${rule.source.scope}] events=${rule.events.join(",")} command=${formatCommand(rule.command.command, rule.command.args)}${matcher}`);
+        }
+    }
+    if (config.diagnostics.length > 0) {
+        lines.push("", "Diagnostics:");
+        for (const diagnostic of config.diagnostics) {
+            lines.push(`  [${diagnostic.scope}] ${diagnostic.path}: ${diagnostic.message}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function explainHookEvent(eventName, config) {
+    const rules = config.rules.filter((rule) => rule.events.includes(eventName));
+    const lines = [`Hooks for ${eventName}:`];
+    if (rules.length === 0) {
+        lines.push("  (none)");
+        return lines.join("\n");
+    }
+    for (const rule of rules) {
+        const reasons = [];
+        if (!rule.enabled)
+            reasons.push("disabled");
+        if (!rule.trusted)
+            reasons.push("untrusted");
+        if (rule.source.scope === "project" && !rule.trusted)
+            reasons.push("run /hooks trust project");
+        const suffix = reasons.length ? ` - ${reasons.join(", ")}` : "";
+        lines.push(`  ${rule.id} [${rule.source.scope}] ${formatCommand(rule.command.command, rule.command.args)}${suffix}`);
+    }
+    return lines.join("\n");
+}
+function readHooksFile(scope, path) {
+    if (!existsSync(path))
+        return { diagnostics: [] };
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return { diagnostics: [{ scope, path, message: "Settings file must contain a JSON object." }] };
+        }
+        if (parsed.hooks === undefined)
+            return { diagnostics: [] };
+        if (Array.isArray(parsed.hooks))
+            return { settings: { rules: parsed.hooks }, diagnostics: [] };
+        if (!parsed.hooks || typeof parsed.hooks !== "object" || Array.isArray(parsed.hooks)) {
+            return { diagnostics: [{ scope, path, message: "Ignored hooks setting - expected object or array." }] };
+        }
+        return { settings: parsed.hooks, diagnostics: [] };
+    }
+    catch (error) {
+        return {
+            diagnostics: [{
+                    scope,
+                    path,
+                    message: `Failed to parse hooks settings: ${error.message}`,
+                }],
+        };
+    }
+}
+function parseHookSettings(scope, path, settings) {
+    const diagnostics = [];
+    const rules = [];
+    if (settings.enabled === false)
+        return { rules, diagnostics };
+    if (!Array.isArray(settings.rules)) {
+        diagnostics.push({ scope, path, message: "Ignored hooks.rules - expected array." });
+        return { rules, diagnostics };
+    }
+    settings.rules.forEach((raw, index) => {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+            diagnostics.push({ scope, path, message: `Ignored hook rule at index ${index} - expected object.` });
+            return;
+        }
+        const parsed = parseHookRule(raw, { scope, path, index });
+        if (parsed.diagnostic)
+            diagnostics.push(parsed.diagnostic);
+        if (parsed.rule)
+            rules.push(parsed.rule);
+    });
+    return { rules, diagnostics };
+}
+function parseHookRule(raw, source) {
+    const events = parseEvents(raw.event, raw.events);
+    if (events.length === 0) {
+        return { diagnostic: diagnostic(source, "Ignored hook rule - event must be a known hook event.") };
+    }
+    const command = parseCommand(raw, source);
+    if (typeof command === "string") {
+        return { diagnostic: diagnostic(source, command) };
+    }
+    const matcher = typeof raw.matcher === "string" && raw.matcher.trim() ? raw.matcher.trim() : undefined;
+    if (matcher) {
+        try {
+            new RegExp(matcher);
+        }
+        catch (error) {
+            return { diagnostic: diagnostic(source, `Ignored hook rule - invalid matcher regex: ${error.message}`) };
+        }
+    }
+    const idRaw = typeof raw.id === "string" ? raw.id : typeof raw.name === "string" ? raw.name : "";
+    const id = idRaw.trim() || `${source.scope}:${source.index}:${events.join("+")}:${command.command}`;
+    const onError = parseFailurePolicy(raw.onError ?? raw.failurePolicy);
+    const include = parseStringArray(raw.include);
+    return {
+        rule: {
+            id,
+            events,
+            matcher,
+            command,
+            timeoutMs: clampNumber(raw.timeoutMs, DEFAULT_TIMEOUT_MS, 50, MAX_TIMEOUT_MS),
+            maxOutputBytes: clampNumber(raw.maxOutputBytes, DEFAULT_MAX_OUTPUT_BYTES, 1024, MAX_OUTPUT_BYTES),
+            enabled: raw.enabled !== false,
+            onError,
+            include,
+            exposeToModel: raw.exposeToModel === true,
+            inheritToSubagents: raw.inheritToSubagents === true,
+            priority: clampNumber(raw.priority, 0, -10_000, 10_000),
+            source,
+            trusted: source.scope !== "project",
+            trustRequired: source.scope === "project",
+        },
+    };
+}
+function parseEvents(event, events) {
+    const values = Array.isArray(events) ? events : event !== undefined ? [event] : [];
+    const parsed = [];
+    for (const value of values) {
+        if (isHookEventName(value) && !parsed.includes(value))
+            parsed.push(value);
+    }
+    return parsed;
+}
+function parseCommand(raw, source) {
+    if (typeof raw.command !== "string" || !raw.command.trim()) {
+        return "Ignored hook rule - command must be a non-empty string.";
+    }
+    if (/[\0\r\n]/.test(raw.command)) {
+        return "Ignored hook rule - command must not contain control characters.";
+    }
+    const command = resolveCommand(raw.command.trim(), source);
+    if (source.scope === "project" && !looksLikePath(raw.command.trim())) {
+        return "Ignored project hook rule - project hook command must be an absolute or relative executable path.";
+    }
+    const args = parseStringArray(raw.args);
+    const cwd = typeof raw.cwd === "string" && raw.cwd.trim()
+        ? resolveAgainstSource(raw.cwd.trim(), source)
+        : undefined;
+    const env = parseEnv(raw.env);
+    return { command, ...(args.length ? { args } : {}), ...(cwd ? { cwd } : {}), ...(env ? { env } : {}) };
+}
+function resolveCommand(command, source) {
+    return looksLikePath(command) ? resolveAgainstSource(command, source) : command;
+}
+function resolveAgainstSource(value, source) {
+    return isAbsolute(value) ? value : resolve(dirname(source.path), value);
+}
+function parseEnv(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const entries = Object.entries(value)
+        .filter(([key, item]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof item === "string");
+    return entries.length ? Object.fromEntries(entries) : undefined;
+}
+function parseFailurePolicy(value) {
+    return value === "block" ? "block" : "allow";
+}
+function parseStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string");
+}
+function clampNumber(value, fallback, min, max) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.floor(value)));
+}
+function diagnostic(source, message) {
+    return { scope: source.scope, path: source.path, message };
+}
+function looksLikePath(value) {
+    return value.startsWith(".") || value.startsWith("/") || value.includes("/");
+}
+function compareRules(a, b) {
+    if (a.priority !== b.priority)
+        return b.priority - a.priority;
+    const scopeOrder = { user: 0, project: 1, local: 2 };
+    if (scopeOrder[a.source.scope] !== scopeOrder[b.source.scope]) {
+        return scopeOrder[a.source.scope] - scopeOrder[b.source.scope];
+    }
+    return a.source.index - b.source.index;
+}
+function formatCommand(command, args) {
+    return [command, ...(args ?? [])].join(" ");
+}

package/dist/hooks/controller.d.ts

@@ -0,0 +1,24 @@
+import { type LoadHookConfigOptions } from "./config.js";
+import { type HookCombinedResult, type HookEventName, type HookProgressEvent, type HookRunRequest, type LoadedHookConfig } from "./types.js";
+export interface ExternalHookControllerOptions extends LoadHookConfigOptions {
+    sessionId?: string;
+}
+export interface HookRunOptions {
+    abortSignal?: AbortSignal;
+    onProgress?: (event: HookProgressEvent) => void;
+}
+export declare class ExternalHookController {
+    private readonly options;
+    private config;
+    private readonly disabledByDepth;
+    constructor(options: ExternalHookControllerOptions);
+    reload(): LoadedHookConfig;
+    getConfig(): LoadedHookConfig;
+    status(): string;
+    explain(eventName: HookEventName): string;
+    logs(limit?: number): string;
+    trustProject(): string;
+    untrustProject(): string;
+    test(eventName: HookEventName, target?: string): Promise<string>;
+    runEvent(request: HookRunRequest, runOptions?: HookRunOptions): Promise<HookCombinedResult>;
+}