@townco/agent 0.1.102 → 0.1.104

package/dist/runner/hooks/executor.js

@@ -1,5 +1,7 @@
 import { createLogger } from "../../logger.js";
+import { countToolResultTokens } from "../../utils/token-counter";
 import { getModelContextWindow } from "./constants";
+import { loadHookCallbacks } from "./loader";
 const logger = createLogger("hook-executor");
 /**
  * Hook executor manages hook lifecycle
@@ -12,7 +14,8 @@ export class HookExecutor {
     agentDefinition;
     storage;
     sessionId;
-    constructor(hooks, model, loadCallback, onNotification, agentDefinition, storage, sessionId) {
+    agentDir;
+    constructor(hooks, model, loadCallback, onNotification, agentDefinition, storage, sessionId, agentDir) {
         this.hooks = hooks;
         this.model = model;
         this.loadCallback = loadCallback;
@@ -20,6 +23,7 @@ export class HookExecutor {
         this.agentDefinition = agentDefinition ?? { model, systemPrompt: null };
         this.storage = storage;
         this.sessionId = sessionId;
+        this.agentDir = agentDir;
     }
     /**
      * Emit a notification - sends immediately if callback provided, otherwise collects for batch return
@@ -58,37 +62,33 @@ export class HookExecutor {
     }
     /**
      * Execute a context_size hook
+     * The callback is responsible for checking its own threshold and deciding whether to run.
      */
     async executeContextSizeHook(hook, session, actualInputTokens) {
+        // Get callback config from either the callbacks array or the deprecated callback field
+        const callbackConfig = hook.callbacks?.[0];
+        const callbackName = callbackConfig?.name ?? hook.callback ?? "compaction_tool";
+        // Get settings from new callbacks format or deprecated hook.setting
+        const callbackSetting = (callbackConfig?.setting ?? hook.setting);
         const maxTokens = getModelContextWindow(this.model);
         const percentage = (actualInputTokens / maxTokens) * 100;
-        // Default threshold is 95%
-        const threshold = hook.setting?.threshold ?? 95;
-        // Check if threshold exceeded
-        if (percentage < threshold) {
-            logger.info(`Context hook not triggered: ${actualInputTokens} tokens (${percentage.toFixed(1)}%) < threshold ${threshold}%`);
-            return null; // No action needed
-        }
-        logger.info(`Context hook triggered: ${actualInputTokens} tokens (${percentage.toFixed(1)}%) exceeds threshold ${threshold}%`);
+        logger.info("Executing context_size hook", {
+            callback: callbackName,
+            tokens: actualInputTokens,
+            percentage: `${percentage.toFixed(1)}%`,
+            maxTokens,
+        });
         const notifications = [];
         const triggeredAt = Date.now();
-        // Notify that hook is triggered - sent immediately via callback if available
-        this.emitNotification({
-            type: "hook_triggered",
-            hookType: "context_size",
-            threshold,
-            currentPercentage: percentage,
-            callback: hook.callback,
-            triggeredAt,
-        }, notifications);
+        const threshold = callbackSetting?.threshold ?? 80;
         try {
             // Load and execute callback
             logger.info("Loading context_size hook callback", {
-                callback: hook.callback,
+                callback: callbackName,
             });
-            const callback = await this.loadCallback(hook.callback);
+            const callback = await this.loadCallback(callbackName);
             logger.info("Loaded context_size hook callback, executing...", {
-                callback: hook.callback,
+                callback: callbackName,
             });
             const hookContext = {
                 session,
@@ -99,21 +99,36 @@ export class HookExecutor {
                 agent: this.agentDefinition,
                 sessionId: this.sessionId,
                 storage: this.storage,
+                callbackSetting,
             };
             const result = await callback(hookContext);
+            // Check if actual compaction happened (action !== "none")
+            const action = result.metadata?.action;
+            const actuallyCompacted = action && action !== "none";
             logger.info("Context_size hook callback completed", {
-                callback: hook.callback,
+                callback: callbackName,
                 hasNewContextEntry: !!result.newContextEntry,
+                actuallyCompacted,
                 metadata: result.metadata,
             });
-            // Notify completion
-            this.emitNotification({
-                type: "hook_completed",
-                hookType: "context_size",
-                callback: hook.callback,
-                metadata: result.metadata,
-                completedAt: Date.now(),
-            }, notifications);
+            // Only emit notifications if actual compaction happened
+            if (actuallyCompacted) {
+                this.emitNotification({
+                    type: "hook_triggered",
+                    hookType: "context_size",
+                    threshold,
+                    currentPercentage: percentage,
+                    callback: callbackName,
+                    triggeredAt,
+                }, notifications);
+                this.emitNotification({
+                    type: "hook_completed",
+                    hookType: "context_size",
+                    callback: callbackName,
+                    metadata: result.metadata,
+                    completedAt: Date.now(),
+                }, notifications);
+            }
             return {
                 newContextEntry: result.newContextEntry,
                 notifications,
@@ -121,7 +136,7 @@ export class HookExecutor {
         }
         catch (error) {
             logger.error("Context_size hook callback failed", {
-                callback: hook.callback,
+                callback: callbackName,
                 error: error instanceof Error ? error.message : String(error),
                 stack: error instanceof Error ? error.stack : undefined,
             });
@@ -129,7 +144,7 @@ export class HookExecutor {
             this.emitNotification({
                 type: "hook_error",
                 hookType: "context_size",
-                callback: hook.callback,
+                callback: callbackName,
                 error: error instanceof Error ? error.message : String(error),
                 completedAt: Date.now(),
             }, notifications);
@@ -141,7 +156,8 @@ export class HookExecutor {
         }
     }
     /**
-     * Execute tool_response hooks when a tool returns output
+     * Execute tool_response hooks when a tool returns output.
+     * Chains callbacks in order, passing modified output between them.
      */
     async executeToolResponseHooks(session, currentContextTokens, toolResponse) {
         logger.info(`Executing tool_response hooks - found ${this.hooks.length} hook(s)`, {
@@ -150,131 +166,155 @@ export class HookExecutor {
             outputTokens: toolResponse.outputTokens,
         });
         const notifications = [];
-        for (const hook of this.hooks) {
-            if (hook.type === "tool_response") {
-                const result = await this.executeToolResponseHook(hook, session, currentContextTokens, toolResponse);
-                if (result) {
-                    notifications.push(...result.notifications);
-                    const response = { notifications };
-                    if (result.modifiedOutput !== undefined) {
-                        response.modifiedOutput = result.modifiedOutput;
-                    }
-                    if (result.truncationWarning !== undefined) {
-                        response.truncationWarning = result.truncationWarning;
-                    }
-                    if (result.metadata !== undefined) {
-                        response.metadata = result.metadata;
-                    }
-                    return response;
-                }
-            }
-        }
-        return { notifications }; // No modifications
-    }
-    /**
-     * Execute a single tool_response hook
-     */
-    async executeToolResponseHook(hook, session, currentContextTokens, toolResponse) {
+        let currentOutput = toolResponse.rawOutput;
+        let currentTokens = currentContextTokens;
+        let combinedMetadata = {};
+        let newContextEntry = null;
+        let truncationWarning;
         const maxTokens = getModelContextWindow(this.model);
-        const percentage = (currentContextTokens / maxTokens) * 100;
-        const notifications = [];
-        // Get threshold from settings
-        const settings = hook.setting;
-        // For notifications, calculate a percentage based on maxTokensSize relative to maxTokens
-        // Default to 20000 tokens, which we'll convert to a percentage for display
-        const maxTokensSize = settings?.maxTokensSize ?? 20000;
-        // Calculate approximate percentage: maxTokensSize / maxTokens * 100
-        const threshold = Math.min(100, Math.round((maxTokensSize / maxTokens) * 100));
-        // Capture start time and emit hook_triggered BEFORE callback runs
-        // This allows the UI to show the loading state immediately
-        const triggeredAt = Date.now();
-        this.emitNotification({
-            type: "hook_triggered",
-            hookType: "tool_response",
-            threshold,
-            currentPercentage: percentage,
-            callback: hook.callback,
-            triggeredAt,
-            toolCallId: toolResponse.toolCallId,
-        }, notifications);
-        try {
-            // Load and execute callback
-            const callback = await this.loadCallback(hook.callback);
-            // Pass hook settings through requestParams
-            const sessionWithSettings = {
-                ...session,
-                requestParams: {
-                    ...session.requestParams,
-                    hookSettings: hook.setting,
-                },
-            };
-            const hookContext = {
-                session: sessionWithSettings,
-                currentTokens: currentContextTokens,
-                maxTokens,
-                percentage,
-                model: this.model,
-                agent: this.agentDefinition,
-                sessionId: this.sessionId,
-                storage: this.storage,
-                toolResponse,
-            };
-            const result = await callback(hookContext);
-            logger.info("Hook callback result", {
-                hasMetadata: !!result.metadata,
-                metadataAction: result.metadata?.action,
-                hasModifiedOutput: !!result.metadata?.modifiedOutput,
-                modifiedOutputType: typeof result.metadata?.modifiedOutput,
-                toolCallId: toolResponse.toolCallId,
+        for (const hook of this.hooks) {
+            if (hook.type !== "tool_response")
+                continue;
+            // Load all callbacks for this hook
+            const loadedCallbacks = await loadHookCallbacks(hook, this.agentDir);
+            logger.debug("Loaded callbacks for hook", {
+                hookType: hook.type,
+                callbackCount: loadedCallbacks.length,
+                callbackNames: loadedCallbacks.map((lc) => lc.config.name),
             });
-            // Extract modified output and warnings from metadata
-            if (result.metadata?.modifiedOutput) {
-                // Hook took action - emit completed notification
-                const response = { notifications };
-                response.modifiedOutput = result.metadata.modifiedOutput;
-                if (result.metadata.truncationWarning) {
-                    response.truncationWarning = result.metadata
-                        .truncationWarning;
-                }
-                // Include full metadata for persistence
-                response.metadata = result.metadata;
-                // Notify completion
+            // Build mutable tool response that gets updated after each callback
+            let currentToolResponse = {
+                ...toolResponse,
+                rawOutput: currentOutput,
+                outputTokens: toolResponse.outputTokens,
+            };
+            // Execute callbacks in order - each callback decides if it should run
+            for (const { callback, config } of loadedCallbacks) {
+                // Include pending tool response in token calculation
+                const effectiveTokens = currentTokens + currentToolResponse.outputTokens;
+                const percentage = (effectiveTokens / maxTokens) * 100;
+                const triggeredAt = Date.now();
+                // Emit hook_triggered notification
                 this.emitNotification({
-                    type: "hook_completed",
+                    type: "hook_triggered",
                     hookType: "tool_response",
-                    callback: hook.callback,
-                    metadata: result.metadata,
-                    completedAt: Date.now(),
+                    threshold: 0, // Callbacks decide their own thresholds
+                    currentPercentage: percentage,
+                    callback: config.name,
+                    triggeredAt,
                     toolCallId: toolResponse.toolCallId,
                 }, notifications);
-                return response;
+                try {
+                    const hookContext = {
+                        session,
+                        currentTokens, // Base context tokens (without tool response)
+                        maxTokens,
+                        percentage,
+                        toolResponseTokens: currentToolResponse.outputTokens,
+                        model: this.model,
+                        agent: this.agentDefinition,
+                        sessionId: this.sessionId,
+                        storage: this.storage,
+                        callbackSetting: config.setting, // Pass callback-specific settings
+                        toolResponse: currentToolResponse, // Pass updated tool response
+                    };
+                    // Callback decides whether to run based on its settings and context
+                    const result = await callback(hookContext);
+                    logger.debug("Callback result", {
+                        callbackName: config.name,
+                        hasMetadata: !!result.metadata,
+                        metadataAction: result.metadata?.action,
+                        hasModifiedOutput: !!result.metadata?.modifiedOutput,
+                        hasNewContextEntry: !!result.newContextEntry,
+                    });
+                    // Update tool response if callback modified it
+                    if (result.metadata?.modifiedOutput) {
+                        const newOutput = result.metadata.modifiedOutput;
+                        const newOutputTokens = result.metadata.finalTokens ??
+                            countToolResultTokens(newOutput);
+                        currentOutput = newOutput;
+                        currentToolResponse = {
+                            ...currentToolResponse,
+                            rawOutput: newOutput,
+                            outputTokens: newOutputTokens,
+                        };
+                        logger.debug("Updated tool response after callback", {
+                            callbackName: config.name,
+                            previousTokens: result.metadata.originalTokens,
+                            newTokens: newOutputTokens,
+                        });
+                    }
+                    // Update context entry if callback created one (e.g., compaction)
+                    if (result.newContextEntry) {
+                        newContextEntry = result.newContextEntry;
+                        // Recalculate tokens after context change
+                        const contextSize = result.newContextEntry.context_size;
+                        if (contextSize) {
+                            currentTokens = contextSize.totalEstimated;
+                        }
+                    }
+                    // Capture truncation warning
+                    if (result.metadata?.truncationWarning) {
+                        truncationWarning = result.metadata.truncationWarning;
+                    }
+                    // Merge metadata
+                    combinedMetadata = { ...combinedMetadata, ...result.metadata };
+                    // Emit hook_completed notification
+                    this.emitNotification({
+                        type: "hook_completed",
+                        hookType: "tool_response",
+                        callback: config.name,
+                        metadata: result.metadata,
+                        completedAt: Date.now(),
+                        toolCallId: toolResponse.toolCallId,
+                    }, notifications);
+                }
+                catch (error) {
+                    logger.error("Hook callback failed", {
+                        callbackName: config.name,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    // Emit hook_error notification
+                    this.emitNotification({
+                        type: "hook_error",
+                        hookType: "tool_response",
+                        callback: config.name,
+                        error: error instanceof Error ? error.message : String(error),
+                        completedAt: Date.now(),
+                        toolCallId: toolResponse.toolCallId,
+                    }, notifications);
+                    // Stop on error, but return error in output so agent can handle it
+                    return {
+                        modifiedOutput: {
+                            error: `Tool response processing failed: ${error instanceof Error ? error.message : String(error)}`,
+                            originalToolName: toolResponse.toolName,
+                            suggestion: "The tool response was too large to process. Consider using more specific queries or breaking the task into smaller parts.",
+                        },
+                        metadata: {
+                            action: "error",
+                            failedCallback: config.name,
+                            error: error instanceof Error ? error.message : String(error),
+                        },
+                        notifications,
+                    };
+                }
             }
-            // No action was taken - emit completed with no-op metadata
-            this.emitNotification({
-                type: "hook_completed",
-                hookType: "tool_response",
-                callback: hook.callback,
-                metadata: { action: "no_action_needed" },
-                completedAt: Date.now(),
-                toolCallId: toolResponse.toolCallId,
-            }, notifications);
-            return { notifications };
         }
-        catch (error) {
-            // Notify error
-            this.emitNotification({
-                type: "hook_error",
-                hookType: "tool_response",
-                callback: hook.callback,
-                error: error instanceof Error ? error.message : String(error),
-                completedAt: Date.now(),
-                toolCallId: toolResponse.toolCallId,
-            }, notifications);
-            logger.error("Tool response hook execution failed", {
-                callback: hook.callback,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            return { notifications }; // Return notifications even on error
+        // Build response
+        const response = { notifications };
+        // Only include modifiedOutput if it was actually modified
+        if (currentOutput !== toolResponse.rawOutput) {
+            response.modifiedOutput = currentOutput;
+        }
+        if (truncationWarning) {
+            response.truncationWarning = truncationWarning;
+        }
+        if (Object.keys(combinedMetadata).length > 0) {
+            response.metadata = combinedMetadata;
+        }
+        if (newContextEntry) {
+            response.newContextEntry = newContextEntry;
         }
+        return response;
     }
 }

package/dist/runner/hooks/loader.d.ts

@@ -1,5 +1,17 @@
-import type { HookCallback } from "./types";
+import type { CallbackConfig, HookCallback, HookConfig } from "./types";
+/**
+ * Loaded callback with its configuration
+ */
+export interface LoadedCallback {
+    callback: HookCallback;
+    config: CallbackConfig;
+}
 /**
  * Load a hook callback from either registry or custom file
  */
 export declare function loadHookCallback(callbackRef: string, agentDir?: string): Promise<HookCallback>;
+/**
+ * Load all callbacks for a hook configuration.
+ * Supports both the deprecated single `callback` field and the new `callbacks` array.
+ */
+export declare function loadHookCallbacks(hookConfig: HookConfig, agentDir?: string): Promise<LoadedCallback[]>;

package/dist/runner/hooks/loader.js

@@ -47,3 +47,30 @@ export async function loadHookCallback(callbackRef, agentDir) {
         throw new Error(`Failed to load custom hook "${callbackRef}": ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+/**
+ * Load all callbacks for a hook configuration.
+ * Supports both the deprecated single `callback` field and the new `callbacks` array.
+ */
+export async function loadHookCallbacks(hookConfig, agentDir) {
+    // Normalize to CallbackConfig array
+    const callbackConfigs = hookConfig.callbacks ?? [];
+    // Handle deprecated single callback field
+    if (hookConfig.callback && callbackConfigs.length === 0) {
+        callbackConfigs.push({
+            name: hookConfig.callback,
+            // Migrate legacy setting to callback-level setting
+            setting: hookConfig.setting,
+        });
+    }
+    // Load all callbacks in parallel
+    const loadedCallbacks = await Promise.all(callbackConfigs.map(async (config) => ({
+        callback: await loadHookCallback(config.name, agentDir),
+        config,
+    })));
+    logger.debug("Loaded hook callbacks", {
+        hookType: hookConfig.type,
+        callbackCount: loadedCallbacks.length,
+        callbackNames: callbackConfigs.map((c) => c.name),
+    });
+    return loadedCallbacks;
+}

package/dist/runner/hooks/predefined/compaction-tool.d.ts

@@ -1,6 +1,8 @@
 import { type HookCallback } from "../types";
 /**
  * Compaction tool that uses an LLM to summarize conversation history
- * when context size reaches the configured threshold
+ * when context size reaches the configured threshold.
+ *
+ * This callback checks its own threshold setting to decide whether to run.
  */
 export declare const compactionTool: HookCallback;

package/dist/runner/hooks/predefined/compaction-tool.js

@@ -2,16 +2,52 @@ import { ChatAnthropic } from "@langchain/anthropic";
 import { HumanMessage, SystemMessage } from "@langchain/core/messages";
 import { createLogger } from "../../../logger.js";
 import { createContextEntry, createFullMessageEntry, } from "../types";
+import { applyTokenPadding } from "./token-utils.js";
 const logger = createLogger("compaction-tool");
 /**
  * Compaction tool that uses an LLM to summarize conversation history
- * when context size reaches the configured threshold
+ * when context size reaches the configured threshold.
+ *
+ * This callback checks its own threshold setting to decide whether to run.
  */
 export const compactionTool = async (ctx) => {
+    // Read settings from callbackSetting
+    const settings = ctx.callbackSetting;
+    const threshold = settings?.threshold ?? 80;
+    // Calculate effective token usage including pending tool response if present
+    const toolResponseTokens = ctx.toolResponse?.outputTokens ?? 0;
+    const estimatedTokens = ctx.currentTokens + toolResponseTokens;
+    // Apply 10% padding to account for token estimation inaccuracies
+    const paddedTokens = applyTokenPadding(estimatedTokens);
+    const effectivePercentage = (paddedTokens / ctx.maxTokens) * 100;
+    // Check if we should run based on context percentage (including tool response)
+    if (effectivePercentage < threshold) {
+        logger.debug("Context below threshold, skipping compaction", {
+            currentTokens: ctx.currentTokens,
+            toolResponseTokens,
+            estimatedTokens,
+            paddedTokens,
+            effectivePercentage: effectivePercentage.toFixed(2),
+            threshold,
+        });
+        return {
+            newContextEntry: null,
+            metadata: {
+                action: "none",
+                reason: "below_threshold",
+                percentage: effectivePercentage,
+                threshold,
+            },
+        };
+    }
     logger.info("Compaction tool triggered", {
         currentTokens: ctx.currentTokens,
+        toolResponseTokens,
+        estimatedTokens,
+        paddedTokens,
         maxTokens: ctx.maxTokens,
-        percentage: `${ctx.percentage.toFixed(2)}%`,
+        effectivePercentage: `${effectivePercentage.toFixed(2)}%`,
+        threshold,
         contextEntries: ctx.session.context.length,
         totalMessages: ctx.session.messages.length,
         model: ctx.model,

package/dist/runner/hooks/predefined/context-validator.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Context validation utilities for ensuring LLM calls don't exceed context limits.
+ *
+ * Key principle: Before passing content to ANY LLM, validate it's within
+ * the model's context limit minus a safety buffer.
+ */
+/**
+ * Result of context validation
+ */
+export interface ValidationResult {
+    /** Whether the content fits within the allowed context size */
+    isValid: boolean;
+    /** Total tokens that would be used (current + new content) */
+    totalTokens: number;
+    /** Maximum allowed tokens (modelLimit * (1 - bufferPercent)) */
+    maxAllowedTokens: number;
+    /** Model's full context window size */
+    modelContextWindow: number;
+    /** How many tokens over the limit (undefined if within limits) */
+    excess?: number;
+}
+/**
+ * Default buffer percentage (10%)
+ * Accounts for tokenizer estimation differences and API overhead
+ */
+export declare const DEFAULT_BUFFER_PERCENT = 0.1;
+/**
+ * Validates whether adding new content would exceed the model's context limit.
+ *
+ * @param contentTokens - Tokens in the new content to be added
+ * @param currentContextTokens - Tokens already in the context
+ * @param modelContextWindow - Model's full context window size
+ * @param bufferPercent - Safety buffer as a percentage (default 10%)
+ * @returns Validation result indicating if content fits
+ */
+export declare function validateContextFits(contentTokens: number, currentContextTokens: number, modelContextWindow: number, bufferPercent?: number): ValidationResult;
+/**
+ * Validates whether a prompt string fits within a model's context limit.
+ * Convenience function that counts tokens from the prompt string.
+ *
+ * @param prompt - The prompt string to validate
+ * @param modelName - Name of the model to get context window for
+ * @param bufferPercent - Safety buffer as a percentage (default 10%)
+ * @returns Validation result indicating if prompt fits
+ */
+export declare function validatePromptFits(prompt: string, modelName: string, bufferPercent?: number): ValidationResult;
+/**
+ * Checks if an error is a context overflow error from the Anthropic API.
+ *
+ * @param error - The error to check
+ * @returns true if the error indicates context overflow
+ */
+export declare function isContextOverflowError(error: unknown): boolean;
+/**
+ * Logs validation result with appropriate severity
+ */
+export declare function logValidationResult(result: ValidationResult, context: string): void;