@poolzin/pool-bot 2026.2.21 → 2026.2.22

package/dist/plugins/hooks.js

@@ -10,7 +10,7 @@
 function getHooksForName(registry, hookName) {
     return registry.typedHooks
         .filter((h) => h.hookName === hookName)
-        .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+        .toSorted((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
 }
 /**
  * Create a hook runner for a specific registry.
@@ -18,14 +18,26 @@ function getHooksForName(registry, hookName) {
 export function createHookRunner(registry, options = {}) {
     const logger = options.logger;
     const catchErrors = options.catchErrors ?? true;
+    const mergeBeforeModelResolve = (acc, next) => ({
+        // Keep the first defined override so higher-priority hooks win.
+        modelOverride: acc?.modelOverride ?? next.modelOverride,
+        providerOverride: acc?.providerOverride ?? next.providerOverride,
+    });
+    const mergeBeforePromptBuild = (acc, next) => ({
+        systemPrompt: next.systemPrompt ?? acc?.systemPrompt,
+        prependContext: acc?.prependContext && next.prependContext
+            ? `${acc.prependContext}\n\n${next.prependContext}`
+            : (next.prependContext ?? acc?.prependContext),
+    });
     /**
      * Run a hook that doesn't return a value (fire-and-forget style).
      * All handlers are executed in parallel for performance.
      */
     async function runVoidHook(hookName, event, ctx) {
         const hooks = getHooksForName(registry, hookName);
-        if (hooks.length === 0)
+        if (hooks.length === 0) {
             return;
+        }
         logger?.debug?.(`[hooks] running ${hookName} (${hooks.length} handlers)`);
         const promises = hooks.map(async (hook) => {
             try {
@@ -37,7 +49,7 @@ export function createHookRunner(registry, options = {}) {
                     logger?.error(msg);
                 }
                 else {
-                    throw new Error(msg);
+                    throw new Error(msg, { cause: err });
                 }
             }
         });
@@ -49,8 +61,9 @@ export function createHookRunner(registry, options = {}) {
      */
     async function runModifyingHook(hookName, event, ctx, mergeResults) {
         const hooks = getHooksForName(registry, hookName);
-        if (hooks.length === 0)
+        if (hooks.length === 0) {
             return undefined;
+        }
         logger?.debug?.(`[hooks] running ${hookName} (${hooks.length} handlers, sequential)`);
         let result;
         for (const hook of hooks) {
@@ -71,7 +84,7 @@ export function createHookRunner(registry, options = {}) {
                     logger?.error(msg);
                 }
                 else {
-                    throw new Error(msg);
+                    throw new Error(msg, { cause: err });
                 }
             }
         }
@@ -80,17 +93,28 @@ export function createHookRunner(registry, options = {}) {
     // =========================================================================
     // Agent Hooks
     // =========================================================================
+    /**
+     * Run before_model_resolve hook.
+     * Allows plugins to override provider/model before model resolution.
+     */
+    async function runBeforeModelResolve(event, ctx) {
+        return runModifyingHook("before_model_resolve", event, ctx, mergeBeforeModelResolve);
+    }
+    /**
+     * Run before_prompt_build hook.
+     * Allows plugins to inject context and system prompt before prompt submission.
+     */
+    async function runBeforePromptBuild(event, ctx) {
+        return runModifyingHook("before_prompt_build", event, ctx, mergeBeforePromptBuild);
+    }
     /**
      * Run before_agent_start hook.
-     * Allows plugins to inject context into the system prompt.
-     * Runs sequentially, merging systemPrompt and prependContext from all handlers.
+     * Legacy compatibility hook that combines model resolve + prompt build phases.
      */
     async function runBeforeAgentStart(event, ctx) {
         return runModifyingHook("before_agent_start", event, ctx, (acc, next) => ({
-            systemPrompt: next.systemPrompt ?? acc?.systemPrompt,
-            prependContext: acc?.prependContext && next.prependContext
-                ? `${acc.prependContext}\n\n${next.prependContext}`
-                : (next.prependContext ?? acc?.prependContext),
+            ...mergeBeforePromptBuild(acc, next),
+            ...mergeBeforeModelResolve(acc, next),
         }));
     }
     /**
@@ -101,6 +125,22 @@ export function createHookRunner(registry, options = {}) {
     async function runAgentEnd(event, ctx) {
         return runVoidHook("agent_end", event, ctx);
     }
+    /**
+     * Run llm_input hook.
+     * Allows plugins to observe the exact input payload sent to the LLM.
+     * Runs in parallel (fire-and-forget).
+     */
+    async function runLlmInput(event, ctx) {
+        return runVoidHook("llm_input", event, ctx);
+    }
+    /**
+     * Run llm_output hook.
+     * Allows plugins to observe the exact output payload returned by the LLM.
+     * Runs in parallel (fire-and-forget).
+     */
+    async function runLlmOutput(event, ctx) {
+        return runVoidHook("llm_output", event, ctx);
+    }
     /**
      * Run before_compaction hook.
      */
@@ -113,6 +153,14 @@ export function createHookRunner(registry, options = {}) {
     async function runAfterCompaction(event, ctx) {
         return runVoidHook("after_compaction", event, ctx);
     }
+    /**
+     * Run before_reset hook.
+     * Fired when /new or /reset clears a session, before messages are lost.
+     * Runs in parallel (fire-and-forget).
+     */
+    async function runBeforeReset(event, ctx) {
+        return runVoidHook("before_reset", event, ctx);
+    }
     // =========================================================================
     // Message Hooks
     // =========================================================================
@@ -175,13 +223,16 @@ export function createHookRunner(registry, options = {}) {
      */
     function runToolResultPersist(event, ctx) {
         const hooks = getHooksForName(registry, "tool_result_persist");
-        if (hooks.length === 0)
+        if (hooks.length === 0) {
             return undefined;
+        }
         let current = event.message;
         for (const hook of hooks) {
             try {
+                // oxlint-disable-next-line typescript/no-explicit-any
                 const out = hook.handler({ ...event, message: current }, ctx);
                 // Guard against accidental async handlers (this hook is sync-only).
+                // oxlint-disable-next-line typescript/no-explicit-any
                 if (out && typeof out.then === "function") {
                     const msg = `[hooks] tool_result_persist handler from ${hook.pluginId} returned a Promise; ` +
                         `this hook is synchronous and the result was ignored.`;
@@ -192,8 +243,9 @@ export function createHookRunner(registry, options = {}) {
                     throw new Error(msg);
                 }
                 const next = out?.message;
-                if (next)
+                if (next) {
                     current = next;
+                }
             }
             catch (err) {
                 const msg = `[hooks] tool_result_persist handler from ${hook.pluginId} failed: ${String(err)}`;
@@ -201,13 +253,75 @@ export function createHookRunner(registry, options = {}) {
                     logger?.error(msg);
                 }
                 else {
-                    throw new Error(msg);
+                    throw new Error(msg, { cause: err });
                 }
             }
         }
         return { message: current };
     }
     // =========================================================================
+    // Message Write Hooks
+    // =========================================================================
+    /**
+     * Run before_message_write hook.
+     *
+     * This hook is intentionally synchronous: it runs on the hot path where
+     * session transcripts are appended synchronously.
+     *
+     * Handlers are executed sequentially in priority order (higher first).
+     * If any handler returns { block: true }, the message is NOT written
+     * to the session JSONL and we return immediately.
+     * If a handler returns { message }, the modified message replaces the
+     * original for subsequent handlers and the final write.
+     */
+    function runBeforeMessageWrite(event, ctx) {
+        const hooks = getHooksForName(registry, "before_message_write");
+        if (hooks.length === 0) {
+            return undefined;
+        }
+        let current = event.message;
+        for (const hook of hooks) {
+            try {
+                // oxlint-disable-next-line typescript/no-explicit-any
+                const out = hook.handler({ ...event, message: current }, ctx);
+                // Guard against accidental async handlers (this hook is sync-only).
+                // oxlint-disable-next-line typescript/no-explicit-any
+                if (out && typeof out.then === "function") {
+                    const msg = `[hooks] before_message_write handler from ${hook.pluginId} returned a Promise; ` +
+                        `this hook is synchronous and the result was ignored.`;
+                    if (catchErrors) {
+                        logger?.warn?.(msg);
+                        continue;
+                    }
+                    throw new Error(msg);
+                }
+                const result = out;
+                // If any handler blocks, return immediately.
+                if (result?.block) {
+                    return { block: true };
+                }
+                // If handler provided a modified message, use it for subsequent handlers.
+                if (result?.message) {
+                    current = result.message;
+                }
+            }
+            catch (err) {
+                const msg = `[hooks] before_message_write handler from ${hook.pluginId} failed: ${String(err)}`;
+                if (catchErrors) {
+                    logger?.error(msg);
+                }
+                else {
+                    throw new Error(msg, { cause: err });
+                }
+            }
+        }
+        // If message was modified by any handler, return it.
+        if (current !== event.message) {
+            return { message: current };
+        }
+        return undefined;
+    }
+    // =========================================================================
     // Session Hooks
     // =========================================================================
     /**
@@ -258,10 +372,15 @@ export function createHookRunner(registry, options = {}) {
     }
     return {
         // Agent hooks
+        runBeforeModelResolve,
+        runBeforePromptBuild,
         runBeforeAgentStart,
+        runLlmInput,
+        runLlmOutput,
         runAgentEnd,
         runBeforeCompaction,
         runAfterCompaction,
+        runBeforeReset,
         // Message hooks
         runMessageReceived,
         runMessageSending,
@@ -270,6 +389,8 @@ export function createHookRunner(registry, options = {}) {
         runBeforeToolCall,
         runAfterToolCall,
         runToolResultPersist,
+        // Message write hooks
+        runBeforeMessageWrite,
         // Session hooks
         runSessionStart,
         runSessionEnd,