@townco/agent 0.1.102 → 0.1.104

package/dist/runner/hooks/predefined/context-validator.js

@@ -0,0 +1,92 @@
+/**
+ * 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.
+ */
+import { createLogger } from "../../../logger.js";
+import { countTokens } from "../../../utils/token-counter.js";
+import { getModelContextWindow } from "../constants.js";
+import { applyTokenPadding } from "./token-utils.js";
+const logger = createLogger("context-validator");
+/**
+ * Default buffer percentage (10%)
+ * Accounts for tokenizer estimation differences and API overhead
+ */
+export 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 function validateContextFits(contentTokens, currentContextTokens, modelContextWindow, bufferPercent = DEFAULT_BUFFER_PERCENT) {
+    const maxAllowedTokens = Math.floor(modelContextWindow * (1 - bufferPercent));
+    const totalTokens = currentContextTokens + contentTokens;
+    // Apply 10% padding to account for token estimation inaccuracies
+    const paddedTotalTokens = applyTokenPadding(totalTokens);
+    const isValid = paddedTotalTokens <= maxAllowedTokens;
+    const result = {
+        isValid,
+        totalTokens,
+        maxAllowedTokens,
+        modelContextWindow,
+    };
+    if (!isValid) {
+        result.excess = paddedTotalTokens - maxAllowedTokens;
+    }
+    return result;
+}
+/**
+ * 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 function validatePromptFits(prompt, modelName, bufferPercent = DEFAULT_BUFFER_PERCENT) {
+    const promptTokens = countTokens(prompt);
+    const modelContextWindow = getModelContextWindow(modelName);
+    return validateContextFits(promptTokens, 0, // No existing context for a fresh prompt
+    modelContextWindow, bufferPercent);
+}
+/**
+ * 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 function isContextOverflowError(error) {
+    if (error instanceof Error) {
+        const message = error.message.toLowerCase();
+        return (message.includes("prompt is too long") ||
+            message.includes("context_length_exceeded") ||
+            message.includes("maximum context length") ||
+            (message.includes("tokens") && message.includes("maximum")));
+    }
+    return false;
+}
+/**
+ * Logs validation result with appropriate severity
+ */
+export function logValidationResult(result, context) {
+    if (result.isValid) {
+        logger.debug(`Context validation passed for ${context}`, {
+            totalTokens: result.totalTokens,
+            maxAllowed: result.maxAllowedTokens,
+            headroom: result.maxAllowedTokens - result.totalTokens,
+        });
+    }
+    else {
+        logger.warn(`Context validation failed for ${context}`, {
+            totalTokens: result.totalTokens,
+            maxAllowed: result.maxAllowedTokens,
+            excess: result.excess,
+        });
+    }
+}

package/dist/runner/hooks/predefined/document-context-extractor/chunk-manager.js

@@ -18,11 +18,11 @@ export function calculateChunkSize(config) {
     // Reserve space for:
     // - System prompt (~500 tokens for extraction instructions)
     // - LLM response buffer (~2000 tokens for scoring/extraction output)
-    // - Safety margin (10%)
+    // - Safety margin (25% - increased from 10% to prevent context overflow)
     const responseBuffer = 2000;
     const overhead = systemPromptTokens + responseBuffer;
     const availableForChunk = modelContextSize - overhead;
-    const safeChunkSize = Math.floor(availableForChunk * 0.9);
+    const safeChunkSize = Math.floor(availableForChunk * 0.75);
     // Minimum chunk size to ensure meaningful content (10K tokens)
     const minChunkSize = 10000;
     return Math.max(safeChunkSize, minChunkSize);

package/dist/runner/hooks/predefined/document-context-extractor/content-extractor.js

@@ -6,6 +6,8 @@
 import Anthropic from "@anthropic-ai/sdk";
 import { createLogger } from "../../../../logger.js";
 import { telemetry } from "../../../../telemetry/index.js";
+import { countTokens } from "../../../../utils/token-counter.js";
+import { isContextOverflowError, validateContextFits, } from "../context-validator.js";
 const logger = createLogger("content-extractor");
 // Create Anthropic client directly (not using LangChain)
 const anthropic = new Anthropic({
@@ -81,6 +83,22 @@ async function extractFromChunk(chunk, keyRequirements, totalChunks, config) {
     });
     try {
         const prompt = buildExtractionPrompt(chunk.content, keyRequirements, chunk.index, totalChunks, chunk.relevanceScore ?? 5);
+        // Pre-flight validation: ensure prompt fits in model context
+        const systemPromptTokens = countTokens(EXTRACTION_SYSTEM_PROMPT);
+        const promptTokens = countTokens(prompt);
+        const validation = validateContextFits(promptTokens, systemPromptTokens, config.modelContextSize, 0.1);
+        if (!validation.isValid) {
+            logger.warn("Extraction prompt too large for model context, skipping chunk", {
+                chunkIndex: chunk.index,
+                promptTokens: validation.totalTokens,
+                maxAllowed: validation.maxAllowedTokens,
+            });
+            // Return empty extraction for chunks we can't process
+            return {
+                extracted: `[Chunk ${chunk.index + 1} skipped: content too large (${validation.totalTokens} tokens > ${validation.maxAllowedTokens} max)]`,
+                keyFacts: [],
+            };
+        }
         const response = await telemetry.withActiveSpanAsync(span, () => anthropic.messages.create({
             model: config.model,
             max_tokens: 4096,
@@ -96,6 +114,17 @@ async function extractFromChunk(chunk, keyRequirements, totalChunks, config) {
     }
     catch (error) {
         telemetry.endSpan(span, error);
+        // Handle context overflow errors gracefully
+        if (isContextOverflowError(error)) {
+            logger.warn("Context overflow during chunk extraction, returning empty", {
+                chunkIndex: chunk.index,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return {
+                extracted: `[Chunk ${chunk.index + 1} skipped: context overflow]`,
+                keyFacts: [],
+            };
+        }
         logger.error("Failed to extract from chunk", {
             chunkIndex: chunk.index,
             error: error instanceof Error ? error.message : String(error),

package/dist/runner/hooks/predefined/document-context-extractor/relevance-scorer.js

@@ -7,6 +7,8 @@
 import Anthropic from "@anthropic-ai/sdk";
 import { createLogger } from "../../../../logger.js";
 import { telemetry } from "../../../../telemetry/index.js";
+import { countTokens } from "../../../../utils/token-counter.js";
+import { isContextOverflowError, validateContextFits, } from "../context-validator.js";
 const logger = createLogger("relevance-scorer");
 // Create Anthropic client directly (not using LangChain)
 // This ensures scoring LLM calls don't get captured by LangGraph's streaming
@@ -82,6 +84,22 @@ async function scoreChunk(chunk, keyRequirements, totalChunks, config) {
     });
     try {
         const prompt = buildScoringPrompt(chunk.content, keyRequirements, chunk.index, totalChunks);
+        // Pre-flight validation: ensure prompt fits in model context
+        const systemPromptTokens = countTokens(SCORING_SYSTEM_PROMPT);
+        const promptTokens = countTokens(prompt);
+        const validation = validateContextFits(promptTokens, systemPromptTokens, config.modelContextSize, 0.1);
+        if (!validation.isValid) {
+            logger.warn("Scoring prompt too large for model context, skipping chunk", {
+                chunkIndex: chunk.index,
+                promptTokens: validation.totalTokens,
+                maxAllowed: validation.maxAllowedTokens,
+            });
+            // Return medium relevance for chunks we can't score
+            return {
+                score: 5,
+                reason: `Chunk too large to score (${validation.totalTokens} tokens > ${validation.maxAllowedTokens} max)`,
+            };
+        }
         const response = await telemetry.withActiveSpanAsync(span, () => anthropic.messages.create({
             model: config.model,
             max_tokens: 256,
@@ -97,6 +115,17 @@ async function scoreChunk(chunk, keyRequirements, totalChunks, config) {
     }
     catch (error) {
         telemetry.endSpan(span, error);
+        // Handle context overflow errors gracefully
+        if (isContextOverflowError(error)) {
+            logger.warn("Context overflow during chunk scoring, returning medium relevance", {
+                chunkIndex: chunk.index,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return {
+                score: 5,
+                reason: `Chunk too large to score (context overflow)`,
+            };
+        }
         logger.error("Failed to score chunk", {
             chunkIndex: chunk.index,
             error: error instanceof Error ? error.message : String(error),

package/dist/runner/hooks/predefined/mid-turn-compaction.d.ts

@@ -0,0 +1,17 @@
+import { type HookCallback } from "../types";
+/**
+ * Mid-turn compaction callback that triggers when context + tool response
+ * would exceed the maximum limit. Unlike the regular compaction_tool,
+ * this callback signals that the current turn should be aborted and
+ * restarted with the compacted context.
+ *
+ * This is necessary because the LangChain agent builds messages once at
+ * the start of a turn and doesn't re-read from session.context mid-turn.
+ *
+ * When triggered, this callback:
+ * 1. Creates a compacted summary of the conversation
+ * 2. Returns requiresRestart: true in metadata
+ * 3. The adapter detects this and aborts the current turn
+ * 4. The turn is restarted with the compacted context
+ */
+export declare const midTurnCompaction: HookCallback;

package/dist/runner/hooks/predefined/mid-turn-compaction.js

@@ -0,0 +1,224 @@
+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("mid-turn-compaction");
+/**
+ * Mid-turn compaction callback that triggers when context + tool response
+ * would exceed the maximum limit. Unlike the regular compaction_tool,
+ * this callback signals that the current turn should be aborted and
+ * restarted with the compacted context.
+ *
+ * This is necessary because the LangChain agent builds messages once at
+ * the start of a turn and doesn't re-read from session.context mid-turn.
+ *
+ * When triggered, this callback:
+ * 1. Creates a compacted summary of the conversation
+ * 2. Returns requiresRestart: true in metadata
+ * 3. The adapter detects this and aborts the current turn
+ * 4. The turn is restarted with the compacted context
+ */
+export const midTurnCompaction = async (ctx) => {
+    const settings = ctx.callbackSetting;
+    const threshold = settings?.threshold ?? 80;
+    // Calculate effective token usage including pending tool response
+    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 trigger compaction
+    if (effectivePercentage < threshold) {
+        logger.debug("Context below threshold, no mid-turn compaction needed", {
+            currentTokens: ctx.currentTokens,
+            toolResponseTokens,
+            estimatedTokens,
+            paddedTokens,
+            effectivePercentage: effectivePercentage.toFixed(2),
+            threshold,
+        });
+        return {
+            newContextEntry: null,
+            metadata: {
+                action: "none",
+                reason: "below_threshold",
+                percentage: effectivePercentage,
+                threshold,
+            },
+        };
+    }
+    logger.warn("Mid-turn compaction triggered - context near limit", {
+        currentTokens: ctx.currentTokens,
+        toolResponseTokens,
+        estimatedTokens,
+        paddedTokens,
+        maxTokens: ctx.maxTokens,
+        effectivePercentage: `${effectivePercentage.toFixed(2)}%`,
+        threshold,
+        contextEntries: ctx.session.context.length,
+        totalMessages: ctx.session.messages.length,
+        model: ctx.model,
+    });
+    try {
+        // Create the LLM client using the same model as the agent
+        const model = new ChatAnthropic({
+            model: ctx.model,
+            temperature: 0,
+        });
+        // Build the conversation history to compact
+        const messagesToCompact = ctx.session.messages;
+        // Convert session messages to text for context, including tool calls and results
+        const conversationText = messagesToCompact
+            .map((msg) => {
+            const parts = [];
+            for (const block of msg.content) {
+                if (block.type === "text") {
+                    parts.push(block.text);
+                }
+                else if (block.type === "tool_call") {
+                    // Include tool call info
+                    parts.push(`[Tool: ${block.title}]`);
+                    if (block.rawInput) {
+                        parts.push(`Input: ${JSON.stringify(block.rawInput, null, 2)}`);
+                    }
+                    if (block.rawOutput) {
+                        // Summarize large outputs to avoid overwhelming the compaction LLM
+                        const outputStr = JSON.stringify(block.rawOutput);
+                        if (outputStr.length > 2000) {
+                            parts.push(`Output: [Large output - ${outputStr.length} chars]`);
+                        }
+                        else {
+                            parts.push(`Output: ${outputStr}`);
+                        }
+                    }
+                    if (block.error) {
+                        parts.push(`Error: ${block.error}`);
+                    }
+                }
+            }
+            return `${msg.role.toUpperCase()}:\n${parts.join("\n")}`;
+        })
+            .join("\n\n---\n\n");
+        // Add the pending tool response that triggered this compaction
+        let fullConversationText = conversationText;
+        if (ctx.toolResponse) {
+            const toolOutputStr = JSON.stringify(ctx.toolResponse.rawOutput);
+            // Truncate very large outputs to avoid overwhelming the compaction LLM
+            const truncatedOutput = toolOutputStr.length > 5000
+                ? toolOutputStr.substring(0, 5000) +
+                    `... [truncated, ${toolOutputStr.length} total chars]`
+                : toolOutputStr;
+            fullConversationText += `\n\n---\n\n[PENDING TOOL RESPONSE - This must be included in the summary]\nTool: ${ctx.toolResponse.toolName}\nTool Call ID: ${ctx.toolResponse.toolCallId}\nInput: ${JSON.stringify(ctx.toolResponse.toolInput, null, 2)}\nOutput: ${truncatedOutput}`;
+        }
+        // Create system prompt for compaction
+        const systemPrompt = new SystemMessage("You are a helpful AI assistant tasked with summarizing conversations.");
+        // Create detailed compaction instructions
+        const userPrompt = `Your task is to create a detailed summary of the conversation so far, paying close attention to the user's explicit requests and your previous actions.
+This summary should be thorough in capturing important details, decisions, and context that would be essential for continuing the conversation/task without losing important information.
+
+IMPORTANT: This is a mid-turn compaction. The agent was in the middle of processing a tool response when context limits were reached. The summary must preserve:
+1. What task the agent was working on
+2. What tools were being used
+3. The current state of the work in progress
+4. Any pending operations that need to continue
+5. The key findings from the pending tool response (marked at the end of the conversation)
+
+Before providing your final summary, wrap your analysis in <analysis> tags to organize your thoughts and ensure you've covered all necessary points. In your analysis process:
+
+1. Chronologically analyze each message and section of the conversation. For each section thoroughly identify:
+   - The user's explicit requests and intents
+   - Your approach to addressing the user's requests
+   - Key decisions and important concepts discussed
+   - Specific details that are important to remember
+   - Challenges encountered and how they were addressed
+   - Pay special attention to specific user feedback, especially if the user told you to do something differently
+2. Double-check for accuracy and completeness, addressing each required element thoroughly
+
+Your summary should include the following sections:
+
+1. Primary Request and Intent: Capture all of the user's explicit requests and intents in detail
+2. Key Topics and Concepts: List all important topics, concepts, and themes discussed in the conversation
+3. Important Details and Information: Document specific details, information, or content that was shared, examined, or created. Pay special attention to the most recent messages and include important details where applicable
+4. Challenges and Solutions: List any challenges, issues, or obstacles that came up and how they were addressed. Pay special attention to specific user feedback, especially if the user asked for a different approach
+5. Problem Solving: Document problems solved and any ongoing work or troubleshooting efforts
+6. All User Messages: List ALL user messages (excluding tool results). These are critical for understanding the user's feedback and changing intent
+7. Pending Tasks: Outline any pending tasks that you have explicitly been asked to work on
+8. Current Work: Describe in detail precisely what was being worked on immediately before this summary, paying special attention to the most recent messages from both user and assistant. CRITICAL: Include the tool that was just called, its purpose, AND summarize the key findings from the pending tool response at the end of the conversation.
+9. Optional Next Step: List the next step related to the most recent work. IMPORTANT: ensure this step is DIRECTLY in line with the user's most recent explicit requests and the task you were working on. Include direct quotes from the most recent conversation showing exactly what task you were working on and where you left off.
+10. Pending Tool Response: Summarize the key information from the tool response that was being processed when this compaction triggered (marked as [PENDING TOOL RESPONSE] at the end). This is critical for continuity.
+
+Here's the conversation to summarize:
+
+${fullConversationText}
+
+Please provide your summary based on the conversation above, following this structure and ensuring precision and thoroughness in your response.`;
+        const userMessage = new HumanMessage(userPrompt);
+        // Invoke the LLM
+        logger.info("Invoking LLM for mid-turn compaction summary");
+        const response = await model.invoke([systemPrompt, userMessage]);
+        // Extract the summary text from the response
+        const summaryText = typeof response.content === "string"
+            ? response.content
+            : Array.isArray(response.content)
+                ? response.content
+                    .filter((block) => typeof block === "object" &&
+                    block !== null &&
+                    "text" in block)
+                    .map((block) => block.text)
+                    .join("\n")
+                : "Failed to extract summary";
+        // Extract token usage from LLM response
+        const responseUsage = response
+            .usage_metadata;
+        const summaryTokens = responseUsage?.output_tokens ?? 0;
+        const inputTokensUsed = responseUsage?.input_tokens ?? ctx.currentTokens;
+        logger.info("Generated mid-turn compaction summary", {
+            originalMessages: messagesToCompact.length,
+            summaryLength: summaryText.length,
+            inputTokens: inputTokensUsed,
+            summaryTokens,
+            tokensSaved: inputTokensUsed - summaryTokens,
+        });
+        // Create a new context entry with the summary
+        // Mark it as a mid-turn compaction so the agent knows to continue
+        const summaryEntry = createFullMessageEntry("user", `This session is being continued from a previous conversation that ran out of context during a tool call. The conversation AND the pending tool response are summarized below. IMPORTANT: Continue from where you left off.\n\n${summaryText}`);
+        // Set compactedUpTo to indicate all messages have been compacted into the summary
+        const lastMessageIndex = messagesToCompact.length - 1;
+        const newContextEntry = createContextEntry([summaryEntry], undefined, lastMessageIndex, {
+            // Store summary tokens in userMessagesTokens since the summary is a user message
+            systemPromptTokens: 0,
+            userMessagesTokens: summaryTokens,
+            assistantMessagesTokens: 0,
+            toolInputTokens: 0,
+            toolResultsTokens: 0,
+            totalEstimated: summaryTokens,
+        });
+        return {
+            newContextEntry,
+            metadata: {
+                action: "compacted",
+                requiresRestart: true, // Signal to adapter to restart the turn
+                messagesRemoved: messagesToCompact.length - 1,
+                tokensBeforeCompaction: inputTokensUsed,
+                tokensSaved: inputTokensUsed - summaryTokens,
+                summaryTokens,
+                summaryGenerated: true,
+                midTurn: true,
+            },
+        };
+    }
+    catch (error) {
+        logger.error("Mid-turn compaction failed", {
+            error: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined,
+        });
+        return {
+            newContextEntry: null,
+            metadata: {
+                action: "failed",
+                error: error instanceof Error ? error.message : String(error),
+            },
+        };
+    }
+};

package/dist/runner/hooks/predefined/token-utils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Utility functions for token calculations in hooks
+ */
+/**
+ * Apply 10% safety padding to estimated token counts.
+ * This accounts for potential inaccuracies in token estimation.
+ *
+ * @param estimatedTokens - The estimated token count
+ * @returns The padded token count (10% higher, rounded up)
+ */
+export declare function applyTokenPadding(estimatedTokens: number): number;

package/dist/runner/hooks/predefined/token-utils.js

@@ -0,0 +1,13 @@
+/**
+ * Utility functions for token calculations in hooks
+ */
+/**
+ * Apply 10% safety padding to estimated token counts.
+ * This accounts for potential inaccuracies in token estimation.
+ *
+ * @param estimatedTokens - The estimated token count
+ * @returns The padded token count (10% higher, rounded up)
+ */
+export function applyTokenPadding(estimatedTokens) {
+    return Math.ceil(estimatedTokens * 1.1);
+}