@townco/agent 0.1.101 → 0.1.104

package/dist/runner/hooks/predefined/tool-response-compactor.js

@@ -2,7 +2,9 @@ import Anthropic from "@anthropic-ai/sdk";
 import { createLogger } from "../../../logger.js";
 import { telemetry } from "../../../telemetry/index.js";
 import { countToolResultTokens } from "../../../utils/token-counter.js";
+import { isContextOverflowError, validatePromptFits, } from "./context-validator.js";
 import { extractDocumentContext } from "./document-context-extractor/index.js";
+import { applyTokenPadding } from "./token-utils.js";
 const logger = createLogger("tool-response-compactor");
 // Create Anthropic client directly (not using LangChain)
 // This ensures compaction LLM calls don't get captured by LangGraph's streaming
@@ -16,8 +18,8 @@ const COMPACTION_MODEL_CONTEXT = 200000; // Haiku context size for calculating t
  * Tool response compaction hook - compacts or truncates large tool responses
  * to prevent context overflow
  */
-// Tools that should never be compacted (internal/small response tools)
-const SKIP_COMPACTION_TOOLS = new Set(["todo_write", "TodoWrite"]);
+// Default tools to skip compaction for
+const DEFAULT_SKIP_TOOLS = ["todo_write"];
 export const toolResponseCompactor = async (ctx) => {
     // Only process if we have tool response data
     if (!ctx.toolResponse) {
@@ -25,14 +27,15 @@ export const toolResponseCompactor = async (ctx) => {
         return { newContextEntry: null };
     }
     const { toolCallId, toolName, toolInput, rawOutput, outputTokens } = ctx.toolResponse;
-    // Skip compaction for certain internal tools
-    if (SKIP_COMPACTION_TOOLS.has(toolName)) {
-        logger.debug("Skipping compaction for internal tool", { toolName });
+    // Get settings from callbackSetting - each callback has its own settings
+    const settings = ctx.callbackSetting;
+    const maxTokensSize = settings?.maxTokensSize ?? 20000; // Default: 20000 tokens
+    const skipTools = new Set(settings?.skipTools ?? DEFAULT_SKIP_TOOLS);
+    // Skip compaction for configured tools
+    if (skipTools.has(toolName)) {
+        logger.debug("Skipping compaction for tool", { toolName });
         return { newContextEntry: null };
     }
-    // Get settings from hook configuration
-    const settings = ctx.session.requestParams.hookSettings;
-    const maxTokensSize = settings?.maxTokensSize ?? 20000; // Default: 20000 tokens
     // Use maxTokensSize directly as it's now in tokens
     const maxAllowedResponseSize = maxTokensSize;
     // Calculate available space in context
@@ -42,12 +45,16 @@ export const toolResponseCompactor = async (ctx) => {
         ? Math.floor(availableSpace * 0.9)
         : maxAllowedResponseSize;
     // Calculate compaction limit: max response size that can fit in a single LLM compaction call
-    const COMPACTION_OVERHEAD = 10000;
-    const compactionLimit = Math.floor((COMPACTION_MODEL_CONTEXT - COMPACTION_OVERHEAD) * 0.9); // ~175K tokens
+    // Increased overhead to 25K to account for system prompt, conversation context, JSON serialization
+    const COMPACTION_OVERHEAD = 25000;
+    const compactionLimit = Math.floor((COMPACTION_MODEL_CONTEXT - COMPACTION_OVERHEAD) * 0.9); // ~157K tokens
+    // Apply 10% padding to output tokens to account for estimation inaccuracies
+    const paddedOutputTokens = applyTokenPadding(outputTokens);
     logger.info("Tool response compaction hook triggered", {
         toolCallId,
         toolName,
         outputTokens,
+        paddedOutputTokens,
         currentContext: ctx.currentTokens,
         maxTokens: ctx.maxTokens,
         maxAllowedResponseSize,
@@ -56,8 +63,8 @@ export const toolResponseCompactor = async (ctx) => {
         compactionLimit,
         settings,
     });
-    // Case 0: Small response, no action needed
-    if (outputTokens <= effectiveMaxResponseSize) {
+    // Case 0: Small response, no action needed (using padded tokens for safety)
+    if (paddedOutputTokens <= effectiveMaxResponseSize) {
         logger.info("Tool response fits within threshold, no compaction needed");
         return {
             newContextEntry: null,
@@ -83,7 +90,8 @@ export const toolResponseCompactor = async (ctx) => {
         contextAlreadyOverThreshold: availableSpace <= maxAllowedResponseSize,
     });
     // Case 2: Huge response - use document context extractor (with truncation fallback)
-    if (outputTokens >= compactionLimit) {
+    // Use padded tokens for safety margin
+    if (paddedOutputTokens >= compactionLimit) {
         logger.info("Tool response exceeds compaction capacity, using document context extractor", {
             outputTokens,
             compactionLimit,
@@ -180,23 +188,24 @@ export const toolResponseCompactor = async (ctx) => {
         const finalTokens = countToolResultTokens(compacted);
         // Verify compaction stayed within boundaries
         if (finalTokens > targetSize) {
-            logger.error("LLM compaction exceeded target", {
+            // Compaction exceeded target - log warning but accept the result
+            // The next callback in the chain (compaction-tool) will handle context overflow if needed
+            logger.warn("LLM compaction exceeded target, accepting result anyway", {
                 finalTokens,
                 targetSize,
                 excess: finalTokens - targetSize,
                 toolName,
                 toolCallId,
             });
-            throw new Error(`LLM compaction for tool "${toolName}" exceeded target size. ` +
-                `Compacted to ${finalTokens.toLocaleString()} tokens but target was ${targetSize.toLocaleString()}. ` +
-                `Original response was ${outputTokens.toLocaleString()} tokens.`);
         }
-        logger.info("Successfully compacted tool response", {
-            originalTokens: outputTokens,
-            finalTokens,
-            targetSize,
-            tokensSaved: outputTokens - finalTokens,
-        });
+        else {
+            logger.info("Successfully compacted tool response", {
+                originalTokens: outputTokens,
+                finalTokens,
+                targetSize,
+                tokensSaved: outputTokens - finalTokens,
+            });
+        }
         return {
             newContextEntry: null,
             metadata: {
@@ -205,17 +214,20 @@ export const toolResponseCompactor = async (ctx) => {
                 finalTokens,
                 tokensSaved: outputTokens - finalTokens,
                 modifiedOutput: compacted,
+                compactionMethod: finalTokens > targetSize ? "llm_exceeded_target" : "llm",
             },
         };
     }
     catch (error) {
-        logger.error("Compaction failed", {
+        // Compaction failed - throw error to stop the callback chain
+        // The error will be returned to the agent so it can decide what to do
+        logger.error("Tool response compaction failed", {
             error: error instanceof Error ? error.message : String(error),
             toolName,
             toolCallId,
             outputTokens,
         });
-        throw new Error(`LLM compaction failed for tool "${toolName}": ${error instanceof Error ? error.message : String(error)}. Original response was ${outputTokens.toLocaleString()} tokens.`);
+        throw new Error(`Tool response compaction failed for "${toolName}": ${error instanceof Error ? error.message : String(error)}. Response was ${outputTokens.toLocaleString()} tokens.`);
     }
 };
 /**
@@ -235,6 +247,17 @@ ${conversationContext}
 Based on the tool input and conversation context, what key information is the user looking for from this tool response?
 
 Provide a concise list (3-5 bullet points) of the most important elements to extract.`;
+    // Pre-flight validation: ensure analysis prompt fits in compaction model's context
+    const analysisValidation = validatePromptFits(analysisPrompt, COMPACTION_MODEL, 0.1);
+    if (!analysisValidation.isValid) {
+        logger.warn("Analysis prompt too large for compaction model, using default requirements", {
+            promptTokens: analysisValidation.totalTokens,
+            maxAllowed: analysisValidation.maxAllowedTokens,
+        });
+        // Skip analysis and use generic requirements - will rely on compaction step
+        const keyRequirements = "Extract the most important and relevant information from this tool response.";
+        return compactWithLLMInternal(rawOutput, keyRequirements, targetTokens);
+    }
     // Create OTEL span for analysis call
     const analysisSpan = telemetry.startSpan("compaction.analysis", {
         "gen_ai.operation.name": "chat",
@@ -324,6 +347,19 @@ Your task: Further compact this data by:
 
 Return ONLY valid JSON (no explanation text).`;
         }
+        // Pre-flight validation: ensure compaction prompt fits in compaction model's context
+        const compactionValidation = validatePromptFits(compactionPrompt, COMPACTION_MODEL, 0.1);
+        if (!compactionValidation.isValid) {
+            logger.warn("Compaction prompt too large for LLM, cannot compact further", {
+                attempt: attempt + 1,
+                promptTokens: compactionValidation.totalTokens,
+                maxAllowed: compactionValidation.maxAllowedTokens,
+                currentDataTokens: currentTokens,
+            });
+            // Return what we have - the caller will need to handle this via chunking
+            throw new Error(`Compaction prompt exceeds model context (${compactionValidation.totalTokens} tokens > ${compactionValidation.maxAllowedTokens} max). ` +
+                `Current data is ${currentTokens} tokens.`);
+        }
         // Create OTEL span for compaction call
         const compactionSpan = telemetry.startSpan("compaction.compact", {
             "gen_ai.operation.name": "chat",
@@ -354,6 +390,16 @@ Return ONLY valid JSON (no explanation text).`;
         }
         catch (error) {
             telemetry.endSpan(compactionSpan, error);
+            // Check if this is a context overflow error from the API
+            if (isContextOverflowError(error)) {
+                logger.warn("Context overflow error from compaction API, returning current data", {
+                    attempt: attempt + 1,
+                    currentTokens,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                // Return what we have - better than crashing
+                return currentData;
+            }
             throw error;
         }
         // Extract and parse JSON
@@ -404,3 +450,87 @@ Return ONLY valid JSON (no explanation text).`;
     });
     return currentData;
 }
+/**
+ * Internal helper for compaction when analysis is skipped
+ * Uses generic key requirements and goes directly to compaction
+ */
+async function compactWithLLMInternal(rawOutput, keyRequirements, targetTokens) {
+    let currentData = rawOutput;
+    let currentTokens = countToolResultTokens(rawOutput);
+    const maxAttempts = 4;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const reductionNeeded = Math.round(((currentTokens - targetTokens) / currentTokens) * 100);
+        const compactionPrompt = `You are helping to compact a large tool response to save context space.
+
+Key information needed:
+${keyRequirements}
+
+Data to compact (JSON):
+${JSON.stringify(currentData, null, 2)}
+
+Current size: ${currentTokens.toLocaleString()} tokens
+Target size: ${targetTokens.toLocaleString()} tokens (reduce by ${reductionNeeded}%)
+
+Your task: Create a compacted version that:
+1. Retains all information relevant to the key requirements above
+2. Removes or summarizes less relevant details
+3. Maintains the same JSON structure where possible
+4. Reduces the size to ${targetTokens.toLocaleString()} tokens or less
+5. Be aggressive in removing unnecessary data
+
+Return ONLY valid JSON (no explanation text).`;
+        // Pre-flight validation
+        const validation = validatePromptFits(compactionPrompt, COMPACTION_MODEL, 0.1);
+        if (!validation.isValid) {
+            logger.warn("Internal compaction prompt too large", {
+                attempt: attempt + 1,
+                promptTokens: validation.totalTokens,
+                maxAllowed: validation.maxAllowedTokens,
+            });
+            // Return what we have - caller will need to handle via chunking
+            return currentData;
+        }
+        const compactionSpan = telemetry.startSpan("compaction.compact.internal", {
+            "gen_ai.operation.name": "chat",
+            "gen_ai.provider.name": "anthropic",
+            "gen_ai.request.model": COMPACTION_MODEL,
+            "compaction.attempt": attempt + 1,
+            "compaction.target_tokens": targetTokens,
+            "compaction.current_tokens": currentTokens,
+        });
+        try {
+            const compactionResponse = await telemetry.withActiveSpanAsync(compactionSpan, () => anthropic.messages.create({
+                model: COMPACTION_MODEL,
+                max_tokens: 4096,
+                temperature: 0,
+                system: "You are a helpful assistant compacting data.",
+                messages: [{ role: "user", content: compactionPrompt }],
+            }));
+            telemetry.recordTokenUsage(compactionResponse.usage.input_tokens, compactionResponse.usage.output_tokens, compactionSpan);
+            telemetry.endSpan(compactionSpan);
+            const firstContent = compactionResponse.content[0];
+            const responseText = firstContent && firstContent.type === "text" ? firstContent.text : "";
+            const jsonMatch = responseText.match(/```(?:json)?\n([\s\S]*?)\n```/) || [
+                null,
+                responseText,
+            ];
+            const jsonText = jsonMatch[1] || responseText;
+            const compacted = JSON.parse(jsonText.trim());
+            const compactedTokens = countToolResultTokens(compacted);
+            if (compactedTokens <= targetTokens ||
+                compactedTokens <= targetTokens * 1.05) {
+                return compacted;
+            }
+            currentData = compacted;
+            currentTokens = compactedTokens;
+        }
+        catch (error) {
+            telemetry.endSpan(compactionSpan, error);
+            if (isContextOverflowError(error)) {
+                return currentData;
+            }
+            throw error;
+        }
+    }
+    return currentData;
+}

package/dist/runner/hooks/registry.js

@@ -1,4 +1,5 @@
 import { compactionTool } from "./predefined/compaction-tool";
+import { midTurnCompaction } from "./predefined/mid-turn-compaction";
 import { toolResponseCompactor } from "./predefined/tool-response-compactor";
 /**
  * Registry of predefined hook callbacks
@@ -6,6 +7,7 @@ import { toolResponseCompactor } from "./predefined/tool-response-compactor";
  */
 export const HOOK_REGISTRY = {
     compaction_tool: compactionTool,
+    mid_turn_compaction: midTurnCompaction,
     tool_response_compactor: toolResponseCompactor,
 };
 /**

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

@@ -22,6 +22,7 @@ export interface ContextSizeSettings {
 }
 /**
  * Settings for tool_response hook
+ * @deprecated Use CallbackConfig.setting instead for individual callback settings
  */
 export interface ToolResponseSettings {
     /**
@@ -31,6 +32,21 @@ export interface ToolResponseSettings {
      */
     maxTokensSize?: number | undefined;
 }
+/**
+ * Individual callback configuration with its own settings
+ */
+export interface CallbackConfig {
+    /**
+     * Callback reference - either a predefined hook name or a file path
+     * Examples: "compaction_tool" or "./hooks/my_compaction_tool.ts"
+     */
+    name: string;
+    /**
+     * Callback-specific settings
+     * The callback is responsible for interpreting these settings
+     */
+    setting?: Record<string, unknown> | undefined;
+}
 /**
  * Hook configuration in agent definition
  */
@@ -40,14 +56,21 @@ export interface HookConfig {
      */
     type: HookType;
     /**
-     * Optional hook-specific settings
+     * @deprecated Use callbacks array instead for new configurations.
+     * Single callback reference - either a predefined hook name or a file path
+     * Examples: "compaction_tool" or "./hooks/my_compaction_tool.ts"
+     */
+    callback?: string | undefined;
+    /**
+     * @deprecated Use CallbackConfig.setting in callbacks array instead.
+     * Optional hook-specific settings (only used with deprecated callback field)
      */
     setting?: ContextSizeSettings | ToolResponseSettings | undefined;
     /**
-     * Callback reference - either a predefined hook name or a file path
-     * Examples: "compaction_tool" or "./hooks/my_compaction_tool.ts"
+     * Array of callback configurations to execute in order.
+     * Each callback has its own settings and decides whether to run.
      */
-    callback: string;
+    callbacks?: CallbackConfig[] | undefined;
 }
 /**
  * Read-only view of an agent session for hooks
@@ -102,6 +125,11 @@ export interface HookContext {
      * Storage interface for hooks that need to persist data
      */
     storage?: HookStorageInterface | undefined;
+    /**
+     * Settings for the current callback being executed.
+     * Each callback receives its own settings from CallbackConfig.setting
+     */
+    callbackSetting?: Record<string, unknown> | undefined;
     /**
      * Tool response data (only for tool_response hooks)
      */
@@ -112,6 +140,11 @@ export interface HookContext {
         rawOutput: Record<string, unknown>;
         outputTokens: number;
     };
+    /**
+     * Token count of the pending tool response (only for tool_response hooks).
+     * This is recalculated after each callback in the chain to reflect any modifications.
+     */
+    toolResponseTokens?: number | undefined;
 }
 /**
  * Result returned by hook callbacks

package/dist/runner/index.d.ts

@@ -36,12 +36,16 @@ export declare const makeRunnerFromDefinition: (definition: {
     harnessImplementation?: "langchain" | undefined;
     hooks?: {
         type: "context_size" | "tool_response";
-        setting?: {
+        setting?: Record<string, unknown> | {
             threshold: number;
         } | {
             maxTokensSize?: number | undefined;
         } | undefined;
-        callback: string;
+        callback?: string | undefined;
+        callbacks?: {
+            name: string;
+            setting?: Record<string, unknown> | undefined;
+        }[] | undefined;
     }[] | undefined;
     initialMessage?: {
         enabled: boolean;

package/dist/runner/langchain/index.js

@@ -8,6 +8,8 @@ import { z } from "zod";
 import { SUBAGENT_MODE_KEY } from "../../acp-server/adapter";
 import { createLogger } from "../../logger.js";
 import { telemetry } from "../../telemetry/index.js";
+import { calculateContextSize } from "../../utils/context-size-calculator.js";
+import { getModelContextWindow } from "../hooks/constants.js";
 import { bindGeneratorToAbortSignal, bindGeneratorToSessionContext, getAbortSignal, runWithAbortSignal, } from "../session-context";
 import { loadCustomToolModule, } from "../tool-loader.js";
 import { createModelFromString, detectProvider } from "./model-factory.js";
@@ -384,6 +386,53 @@ export class LangchainAgent {
                 toolOverheadTokens,
                 mcpOverheadTokens,
             };
+            // Calculate accurate context size for tool response compaction decisions
+            // This includes: system prompt, tool overhead, MCP overhead, and message history
+            const baseSystemPromptTokens = this.definition.systemPrompt
+                ? countTokens(this.definition.systemPrompt)
+                : 0;
+            // Estimate additional injection tokens based on enabled features
+            // These will be injected into the system prompt later
+            const hasWebSearchToolsForEstimate = builtInNames.includes("web_search") ||
+                builtInNames.includes("town_web_search");
+            const hasLibraryToolsForEstimate = enabledTools.some((t) => t.name.startsWith("library__") ||
+                t.name.includes("get_document") ||
+                t.name.includes("retrieve_document") ||
+                t.name.includes("search_document"));
+            const hasSubagentToolsForEstimate = enabledTools.some((t) => t.name === SUBAGENT_TOOL_NAME);
+            // Rough estimate for injection overhead (citations, subagent instructions, date/time)
+            // This is approximate but adds safety margin for the compaction decision
+            const injectionOverheadEstimate = (hasWebSearchToolsForEstimate ? 500 : 0) + // Citation instructions
+                (hasLibraryToolsForEstimate ? 400 : 0) + // Document citation instructions
+                (hasSubagentToolsForEstimate ? 300 : 0) + // Subagent citation instructions
+                200; // Date/time injection + safety margin
+            const systemPromptTokensEstimate = baseSystemPromptTokens +
+                todoInstructionsTokens +
+                injectionOverheadEstimate;
+            // Calculate message history tokens from context messages
+            const messageHistoryContext = calculateContextSize(req.contextMessages || [], undefined, // Don't double count system prompt
+            0, // Don't double count tool overhead
+            0);
+            const messageHistoryTokens = messageHistoryContext.userMessagesTokens +
+                messageHistoryContext.assistantMessagesTokens +
+                messageHistoryContext.toolInputTokens +
+                messageHistoryContext.toolResultsTokens;
+            // Total base context (everything except new tool outputs in this turn)
+            const baseContextTokens = systemPromptTokensEstimate +
+                toolOverheadTokens +
+                mcpOverheadTokens +
+                messageHistoryTokens;
+            const modelContextWindow = getModelContextWindow(this.definition.model);
+            _logger.debug("Calculated accurate context size for compaction", {
+                baseSystemPromptTokens,
+                injectionOverheadEstimate,
+                systemPromptTokensEstimate,
+                toolOverheadTokens,
+                mcpOverheadTokens,
+                messageHistoryTokens,
+                baseContextTokens,
+                modelContextWindow,
+            });
             // Wrap tools with response compaction if hook is configured
             const hooks = this.definition.hooks ?? [];
             const hasToolResponseHook = hooks.some((h) => h.type === "tool_response");
@@ -418,10 +467,9 @@ export class LangchainAgent {
                             cumulativeToolOutputTokens,
                         });
                         // Calculate current context including all tool outputs so far in this turn
+                        // Uses accurate baseContextTokens calculated earlier (system prompt, tool overhead, MCP overhead, message history)
                         // This ensures we account for multiple large tool calls in the same turn
-                        const baseContextTokens = turnTokenUsage.inputTokens || 10000;
                         const currentTokens = baseContextTokens + cumulativeToolOutputTokens;
-                        const maxTokens = 200000; // Claude's limit
                         // Build proper hook context with all required fields
                         const hookContext = {
                             session: {
@@ -433,8 +481,8 @@ export class LangchainAgent {
                                 },
                             },
                             currentTokens,
-                            maxTokens,
-                            percentage: (currentTokens / maxTokens) * 100,
+                            maxTokens: modelContextWindow,
+                            percentage: (currentTokens / modelContextWindow) * 100,
                             model: this.definition.model,
                             agent: this.definition,
                             toolResponse: {
@@ -628,14 +676,18 @@ export class LangchainAgent {
             if (hasSubagentTool) {
                 agentConfig.systemPrompt = `${agentConfig.systemPrompt ?? ""}\n\n${SUBAGENT_CITATION_INSTRUCTIONS}`;
             }
-            // Process template variables in system prompt and inject current date/time
+            // Inject current date/time into system prompt
+            const currentDateTime = getCurrentDateTimeString();
+            // First, replace any template variables if they exist
             if (agentConfig.systemPrompt) {
-                const currentDateTime = getCurrentDateTimeString();
-                // Replace {{.CurrentDate}} template variable
                 agentConfig.systemPrompt = agentConfig.systemPrompt.replace(/\{\{\.CurrentDate\}\}/g, currentDateTime);
-                // Replace {{.CurrentDateTime}} template variable (alias)
                 agentConfig.systemPrompt = agentConfig.systemPrompt.replace(/\{\{\.CurrentDateTime\}\}/g, currentDateTime);
             }
+            // Always append current date/time information (if not already present via template)
+            const dateInfoLine = `The current date and time is ${currentDateTime}.`;
+            if (!agentConfig.systemPrompt?.includes(currentDateTime)) {
+                agentConfig.systemPrompt = `${agentConfig.systemPrompt ?? ""}\n\n${dateInfoLine}`;
+            }
             // Apply prompt parameters from request (user-selected per-message options)
             if (req.promptParameters && this.definition.promptParameters) {
                 for (const param of this.definition.promptParameters) {