@townco/agent 0.1.50 → 0.1.51

package/dist/definition/index.js

@@ -54,16 +54,29 @@ const ToolSchema = z.union([
 ]);
 /** Hook configuration schema. */
 export const HookConfigSchema = z.object({
-    type: z.enum(["context_size"]),
+    type: z.enum(["context_size", "tool_response"]),
     setting: z
-        .object({
-        threshold: z.number().min(0).max(100),
-    })
+        .union([
+        // For context_size hooks
+        z.object({
+            threshold: z.number().min(0).max(100),
+        }),
+        // For tool_response hooks
+        z.object({
+            maxContextThreshold: z.number().min(0).max(100).optional(),
+            responseTruncationThreshold: z.number().min(0).max(100).optional(),
+        }),
+    ])
         .optional(),
     callback: z.string(),
 });
 /** Agent definition schema. */
 export const AgentDefinitionSchema = z.object({
+    /** Human-readable display name for the agent (shown in UI). */
+    displayName: z.string().optional(),
+    version: z.string().optional(),
+    description: z.string().optional(),
+    suggestedPrompts: z.array(z.string()).optional(),
     systemPrompt: z.string().nullable(),
     model: z.string(),
     tools: z.array(ToolSchema).optional(),

package/dist/index.js

@@ -36,7 +36,7 @@ const exampleAgent = {
         {
             type: "context_size",
             setting: {
-                threshold: 95,
+                threshold: 80,
             },
             callback: "compaction_tool",
         },

package/dist/runner/agent-runner.d.ts

@@ -2,6 +2,10 @@ import type { PromptRequest, PromptResponse, SessionNotification } from "@agentc
 import { z } from "zod";
 import type { ContentBlock } from "../acp-server/session-storage.js";
 export declare const zAgentRunnerParams: z.ZodObject<{
+    displayName: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    suggestedPrompts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     systemPrompt: z.ZodNullable<z.ZodString>;
     model: z.ZodString;
     tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">, z.ZodLiteral<"filesystem">]>, z.ZodObject<{
@@ -33,10 +37,14 @@ export declare const zAgentRunnerParams: z.ZodObject<{
     hooks: z.ZodOptional<z.ZodArray<z.ZodObject<{
         type: z.ZodEnum<{
             context_size: "context_size";
+            tool_response: "tool_response";
         }>;
-        setting: z.ZodOptional<z.ZodObject<{
+        setting: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
             threshold: z.ZodNumber;
-        }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            maxContextThreshold: z.ZodOptional<z.ZodNumber>;
+            responseTruncationThreshold: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>]>>;
         callback: z.ZodString;
     }, z.core.$strip>>>;
 }, z.core.$strip>;

package/dist/runner/agent-runner.js

@@ -2,6 +2,10 @@ import { z } from "zod";
 import { HookConfigSchema, McpConfigSchema } from "../definition";
 import { zToolType } from "./tools";
 export const zAgentRunnerParams = z.object({
+    displayName: z.string().optional(),
+    version: z.string().optional(),
+    description: z.string().optional(),
+    suggestedPrompts: z.array(z.string()).optional(),
     systemPrompt: z.string().nullable(),
     model: z.string(),
     tools: z.array(zToolType).optional(),

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

@@ -20,4 +20,21 @@ export declare class HookExecutor {
      * Execute a context_size hook
      */
     private executeContextSizeHook;
+    /**
+     * Execute tool_response hooks when a tool returns output
+     */
+    executeToolResponseHooks(session: ReadonlySession, currentContextTokens: number, toolResponse: {
+        toolCallId: string;
+        toolName: string;
+        toolInput: Record<string, unknown>;
+        rawOutput: Record<string, unknown>;
+        outputTokens: number;
+    }): Promise<{
+        modifiedOutput?: Record<string, unknown>;
+        truncationWarning?: string;
+    }>;
+    /**
+     * Execute a single tool_response hook
+     */
+    private executeToolResponseHook;
 }

package/dist/runner/hooks/executor.js

@@ -106,4 +106,70 @@ export class HookExecutor {
             };
         }
     }
+    /**
+     * Execute tool_response hooks when a tool returns output
+     */
+    async executeToolResponseHooks(session, currentContextTokens, toolResponse) {
+        logger.info(`Executing tool_response hooks - found ${this.hooks.length} hook(s)`, {
+            toolCallId: toolResponse.toolCallId,
+            toolName: toolResponse.toolName,
+            outputTokens: toolResponse.outputTokens,
+        });
+        for (const hook of this.hooks) {
+            if (hook.type === "tool_response") {
+                const result = await this.executeToolResponseHook(hook, session, currentContextTokens, toolResponse);
+                if (result) {
+                    return result;
+                }
+            }
+        }
+        return {}; // No modifications
+    }
+    /**
+     * Execute a single tool_response hook
+     */
+    async executeToolResponseHook(hook, session, currentContextTokens, toolResponse) {
+        const maxTokens = getModelMaxTokens(this.model);
+        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: (currentContextTokens / maxTokens) * 100,
+                model: this.model,
+                toolResponse,
+            };
+            const result = await callback(hookContext);
+            // Extract modified output and warnings from metadata
+            if (result.metadata) {
+                const response = {};
+                if (result.metadata.modifiedOutput) {
+                    response.modifiedOutput = result.metadata.modifiedOutput;
+                }
+                if (result.metadata.truncationWarning) {
+                    response.truncationWarning = result.metadata
+                        .truncationWarning;
+                }
+                return response;
+            }
+            return null;
+        }
+        catch (error) {
+            logger.error("Tool response hook execution failed", {
+                callback: hook.callback,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null; // Return original output on error
+        }
+    }
 }

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

@@ -99,7 +99,15 @@ Please provide your summary based on the conversation above, following this stru
         const summaryEntry = createFullMessageEntry("user", `This session is being continued from a previous conversation that ran out of context. The conversation is summarized below:\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, summaryTokens);
+        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: {

package/dist/runner/hooks/predefined/tool-response-compactor.d.ts

@@ -0,0 +1,6 @@
+import type { HookCallback } from "../types.js";
+/**
+ * Tool response compaction hook - compacts or truncates large tool responses
+ * to prevent context overflow
+ */
+export declare const toolResponseCompactor: HookCallback;

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

@@ -0,0 +1,461 @@
+import { ChatAnthropic } from "@langchain/anthropic";
+import { HumanMessage, SystemMessage } from "@langchain/core/messages";
+import { createLogger } from "@townco/core";
+import { countToolResultTokens } from "../../../utils/token-counter.js";
+const logger = createLogger("tool-response-compactor");
+// Haiku 4.5 for compaction (fast and cost-effective)
+const COMPACTION_MODEL = "claude-haiku-4-5-20251001";
+const COMPACTION_MODEL_CONTEXT = 200000; // Haiku context size for calculating truncation limits
+/**
+ * Tool response compaction hook - compacts or truncates large tool responses
+ * to prevent context overflow
+ */
+export const toolResponseCompactor = async (ctx) => {
+    // Only process if we have tool response data
+    if (!ctx.toolResponse) {
+        logger.warn("toolResponseCompactor called without tool response data");
+        return { newContextEntry: null };
+    }
+    const { toolCallId, toolName, toolInput, rawOutput, outputTokens } = ctx.toolResponse;
+    // Get settings from hook configuration
+    const settings = ctx.session.requestParams.hookSettings;
+    const maxContextThreshold = settings?.maxContextThreshold ?? 80;
+    const responseTruncationThreshold = settings?.responseTruncationThreshold ?? 30;
+    // Calculate actual token limits from percentages
+    const maxAllowedTotal = ctx.maxTokens * (maxContextThreshold / 100);
+    const availableSpace = maxAllowedTotal - ctx.currentTokens;
+    const projectedTotal = ctx.currentTokens + outputTokens;
+    const compactionLimit = COMPACTION_MODEL_CONTEXT * (responseTruncationThreshold / 100);
+    logger.info("Tool response compaction hook triggered", {
+        toolCallId,
+        toolName,
+        outputTokens,
+        currentContext: ctx.currentTokens,
+        maxAllowedTotal,
+        availableSpace,
+        projectedTotal,
+        compactionLimit,
+        settings,
+    });
+    // Case 0: Small response, no action needed
+    if (projectedTotal < maxAllowedTotal) {
+        logger.info("Tool response fits within threshold, no compaction needed");
+        return {
+            newContextEntry: null,
+            metadata: {
+                action: "none",
+                originalTokens: outputTokens,
+                finalTokens: outputTokens,
+            },
+        };
+    }
+    // Response would exceed threshold, need to compact or truncate
+    // Determine target size: fit within available space, but cap at compactionLimit for truncation
+    const targetSize = Math.min(availableSpace, compactionLimit);
+    // Case 2: Huge response, must truncate (too large for LLM compaction)
+    if (outputTokens >= compactionLimit) {
+        logger.warn("Tool response exceeds compaction capacity, truncating", {
+            outputTokens,
+            compactionLimit,
+            targetSize,
+            availableSpace,
+        });
+        const truncated = truncateToolResponse(rawOutput, targetSize);
+        const finalTokens = countToolResultTokens(truncated);
+        // Verify truncation stayed within boundaries
+        if (finalTokens > targetSize) {
+            logger.error("Truncation exceeded target size - this should not happen!", {
+                finalTokens,
+                targetSize,
+                excess: finalTokens - targetSize,
+            });
+            // Try more aggressive truncation (70% of target as emergency measure)
+            const emergencySize = Math.floor(targetSize * 0.7);
+            const emergencyTruncated = truncateToolResponse(rawOutput, emergencySize);
+            let emergencyTokens = countToolResultTokens(emergencyTruncated);
+            // Final safety check - if emergency truncation STILL exceeded target, use ultra-conservative fallback
+            if (emergencyTokens > targetSize) {
+                logger.error("Emergency truncation STILL exceeded target - using ultra-conservative fallback", {
+                    emergencyTokens,
+                    targetSize,
+                    emergencySize,
+                });
+                // Ultra-conservative: just return a simple error structure with the raw data sliced to 50% of target
+                const ultraConservativeSize = Math.floor(targetSize * 0.5);
+                return {
+                    newContextEntry: null,
+                    metadata: {
+                        action: "truncated",
+                        originalTokens: outputTokens,
+                        finalTokens: ultraConservativeSize, // Conservative estimate
+                        modifiedOutput: {
+                            _truncation_error: "Tool response was too large and could not be reliably truncated",
+                            _original_token_count: outputTokens,
+                            _target_token_count: targetSize,
+                            _partial_data: JSON.stringify(rawOutput).slice(0, ultraConservativeSize * 3),
+                        },
+                        truncationWarning: `Tool response was severely truncated from ${outputTokens.toLocaleString()} to ~${ultraConservativeSize.toLocaleString()} tokens (emergency truncation failed - data may be incomplete)`,
+                    },
+                };
+            }
+            return {
+                newContextEntry: null,
+                metadata: {
+                    action: "truncated",
+                    originalTokens: outputTokens,
+                    finalTokens: emergencyTokens,
+                    modifiedOutput: emergencyTruncated,
+                    truncationWarning: `Tool response was aggressively truncated from ${outputTokens.toLocaleString()} to ${emergencyTokens.toLocaleString()} tokens to fit within context limit (emergency truncation)`,
+                },
+            };
+        }
+        return {
+            newContextEntry: null,
+            metadata: {
+                action: "truncated",
+                originalTokens: outputTokens,
+                finalTokens,
+                modifiedOutput: truncated,
+                truncationWarning: `Tool response was truncated from ${outputTokens.toLocaleString()} to ${finalTokens.toLocaleString()} tokens to fit within context limit (available space: ${availableSpace.toLocaleString()} tokens)`,
+            },
+        };
+    }
+    // Case 1: Medium response, intelligent compaction
+    logger.info("Tool response requires intelligent compaction", {
+        outputTokens,
+        targetSize,
+        availableSpace,
+        compactionLimit,
+    });
+    try {
+        // Build conversation context (last 5 messages)
+        const recentMessages = ctx.session.messages.slice(-5);
+        const conversationContext = recentMessages
+            .map((msg) => {
+            const text = msg.content
+                .filter((b) => b.type === "text")
+                .map((b) => b.text)
+                .join("\n");
+            return `${msg.role}: ${text}`;
+        })
+            .join("\n\n");
+        const compacted = await compactWithLLM(rawOutput, toolName, toolInput, conversationContext, targetSize);
+        let finalTokens = countToolResultTokens(compacted);
+        // Verify compaction stayed within boundaries
+        if (finalTokens > targetSize) {
+            logger.warn("LLM compaction exceeded target, falling back to truncation", {
+                finalTokens,
+                targetSize,
+                excess: finalTokens - targetSize,
+            });
+            // Fallback to truncation
+            const truncated = truncateToolResponse(compacted, targetSize);
+            finalTokens = countToolResultTokens(truncated);
+            return {
+                newContextEntry: null,
+                metadata: {
+                    action: "compacted_then_truncated",
+                    originalTokens: outputTokens,
+                    finalTokens,
+                    tokensSaved: outputTokens - finalTokens,
+                    modifiedOutput: truncated,
+                    truncationWarning: `Tool response was compacted then truncated from ${outputTokens.toLocaleString()} to ${finalTokens.toLocaleString()} tokens to fit within context limit`,
+                },
+            };
+        }
+        logger.info("Successfully compacted tool response", {
+            originalTokens: outputTokens,
+            finalTokens,
+            targetSize,
+            tokensSaved: outputTokens - finalTokens,
+        });
+        return {
+            newContextEntry: null,
+            metadata: {
+                action: "compacted",
+                originalTokens: outputTokens,
+                finalTokens,
+                tokensSaved: outputTokens - finalTokens,
+                modifiedOutput: compacted,
+            },
+        };
+    }
+    catch (error) {
+        logger.error("Compaction failed, falling back to truncation", {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        // Fallback to truncation with the same target size
+        const truncated = truncateToolResponse(rawOutput, targetSize);
+        let finalTokens = countToolResultTokens(truncated);
+        // Verify truncation stayed within boundaries
+        if (finalTokens > targetSize) {
+            logger.error("Fallback truncation exceeded target, using emergency truncation", {
+                finalTokens,
+                targetSize,
+            });
+            const emergencySize = Math.floor(targetSize * 0.7);
+            const emergencyTruncated = truncateToolResponse(rawOutput, emergencySize);
+            finalTokens = countToolResultTokens(emergencyTruncated);
+            // Final safety check
+            if (finalTokens > targetSize) {
+                logger.error("Emergency truncation STILL exceeded target - using ultra-conservative fallback");
+                const ultraConservativeSize = Math.floor(targetSize * 0.5);
+                return {
+                    newContextEntry: null,
+                    metadata: {
+                        action: "truncated",
+                        originalTokens: outputTokens,
+                        finalTokens: ultraConservativeSize,
+                        modifiedOutput: {
+                            _truncation_error: "Tool response was too large and could not be reliably truncated (compaction failed)",
+                            _original_token_count: outputTokens,
+                            _target_token_count: targetSize,
+                            _partial_data: JSON.stringify(rawOutput).slice(0, ultraConservativeSize * 3),
+                        },
+                        truncationWarning: `Tool response was severely truncated from ${outputTokens.toLocaleString()} to ~${ultraConservativeSize.toLocaleString()} tokens (compaction+emergency truncation failed)`,
+                    },
+                };
+            }
+            return {
+                newContextEntry: null,
+                metadata: {
+                    action: "truncated",
+                    originalTokens: outputTokens,
+                    finalTokens,
+                    modifiedOutput: emergencyTruncated,
+                    truncationWarning: `Tool response was truncated from ${outputTokens.toLocaleString()} to ${finalTokens.toLocaleString()} tokens (compaction failed, emergency truncation applied)`,
+                },
+            };
+        }
+        return {
+            newContextEntry: null,
+            metadata: {
+                action: "truncated",
+                originalTokens: outputTokens,
+                finalTokens,
+                modifiedOutput: truncated,
+                truncationWarning: `Tool response was truncated from ${outputTokens.toLocaleString()} to ${finalTokens.toLocaleString()} tokens (compaction failed)`,
+            },
+        };
+    }
+};
+/**
+ * Recursive LLM compaction with adaptive retries
+ */
+async function compactWithLLM(rawOutput, toolName, toolInput, conversationContext, targetTokens) {
+    const model = new ChatAnthropic({
+        model: COMPACTION_MODEL,
+        temperature: 0,
+    });
+    // Step 1: Understand what we're looking for (only need to do this once)
+    const analysisPrompt = `You are helping to manage context size in an agent conversation.
+
+A tool was just called with these parameters:
+Tool: ${toolName}
+Input: ${JSON.stringify(toolInput, null, 2)}
+
+Recent conversation context:
+${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.`;
+    const analysisResponse = await model.invoke([
+        new SystemMessage("You are a helpful assistant analyzing information needs."),
+        new HumanMessage(analysisPrompt),
+    ]);
+    const keyRequirements = typeof analysisResponse.content === "string"
+        ? analysisResponse.content
+        : "Extract relevant information";
+    logger.info("Identified key requirements for compaction", {
+        requirements: keyRequirements.substring(0, 200),
+    });
+    // Step 2: Recursively compact until we meet the target
+    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);
+        // Build the compaction prompt based on whether this is first attempt or retry
+        let compactionPrompt;
+        if (attempt === 0) {
+            // First attempt - compact from original
+            compactionPrompt = `You are helping to compact a large tool response to save context space.
+
+Key information needed:
+${keyRequirements}
+
+Tool response 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).`;
+        }
+        else {
+            // Retry - need to compact further
+            compactionPrompt = `Your previous compaction was good but still too large.
+
+Key information needed:
+${keyRequirements}
+
+Previous compaction result (JSON):
+${JSON.stringify(currentData, null, 2)}
+
+Current size: ${currentTokens.toLocaleString()} tokens
+Target size: ${targetTokens.toLocaleString()} tokens
+You need to reduce by another ${reductionNeeded}%
+
+Your task: Further compact this data by:
+1. Being MORE aggressive in removing unnecessary details
+2. Summarizing verbose content more concisely
+3. Removing any redundant information
+4. Keeping ONLY the most essential data related to the key requirements
+5. Reduce to ${targetTokens.toLocaleString()} tokens or less
+
+Return ONLY valid JSON (no explanation text).`;
+        }
+        const compactionResponse = await model.invoke([
+            new SystemMessage("You are a helpful assistant compacting data."),
+            new HumanMessage(compactionPrompt),
+        ]);
+        // Extract and parse JSON
+        const responseText = typeof compactionResponse.content === "string"
+            ? compactionResponse.content
+            : JSON.stringify(compactionResponse.content);
+        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);
+        logger.info(`LLM compaction attempt ${attempt + 1}/${maxAttempts}`, {
+            currentTokens,
+            compactedTokens,
+            targetTokens,
+            reductionAchieved: currentTokens - compactedTokens,
+        });
+        // Check if we've met the target
+        if (compactedTokens <= targetTokens) {
+            logger.info("LLM compaction succeeded", {
+                attempts: attempt + 1,
+                originalTokens: countToolResultTokens(rawOutput),
+                finalTokens: compactedTokens,
+                targetTokens,
+            });
+            return compacted;
+        }
+        // If we're within 5% of target, accept it (close enough)
+        if (compactedTokens <= targetTokens * 1.05) {
+            logger.info("LLM compaction close enough to target", {
+                attempts: attempt + 1,
+                finalTokens: compactedTokens,
+                targetTokens,
+                overshoot: compactedTokens - targetTokens,
+            });
+            return compacted;
+        }
+        // Still too large - prepare for another attempt
+        currentData = compacted;
+        currentTokens = compactedTokens;
+    }
+    // If we exhausted all attempts, return the last result anyway
+    logger.warn("LLM compaction exhausted attempts but did not meet target", {
+        finalTokens: currentTokens,
+        targetTokens,
+        overshoot: currentTokens - targetTokens,
+    });
+    return currentData;
+}
+/**
+ * Truncate tool response to target token count
+ * Uses iterative approach to ensure we stay under the target
+ */
+function truncateToolResponse(rawOutput, targetTokens) {
+    const currentTokens = countToolResultTokens(rawOutput);
+    if (currentTokens <= targetTokens) {
+        return rawOutput; // Already within limit
+    }
+    const outputString = JSON.stringify(rawOutput);
+    // Start with 70% of target to leave significant room for closing braces and metadata
+    let ratio = 0.7;
+    let lastResult = null;
+    // Iteratively truncate until we meet the target
+    for (let attempt = 0; attempt < 15; attempt++) {
+        // Calculate character limit based on ratio
+        const targetChars = Math.floor((targetTokens * ratio * outputString.length) / currentTokens);
+        // Truncate the JSON string
+        let truncated = outputString.slice(0, targetChars);
+        // Try to close any open JSON structures
+        const openBraces = (truncated.match(/{/g) || []).length;
+        const closeBraces = (truncated.match(/}/g) || []).length;
+        const openBrackets = (truncated.match(/\[/g) || []).length;
+        const closeBrackets = (truncated.match(/\]/g) || []).length;
+        truncated += "}".repeat(Math.max(0, openBraces - closeBraces));
+        truncated += "]".repeat(Math.max(0, openBrackets - closeBrackets));
+        try {
+            // Try to parse as valid JSON
+            const parsed = JSON.parse(truncated);
+            const parsedTokens = countToolResultTokens(parsed);
+            // Store the result
+            lastResult = { parsed, tokens: parsedTokens };
+            if (parsedTokens <= targetTokens) {
+                // Success! Add truncation notice
+                return {
+                    ...parsed,
+                    _truncation_notice: "... [TRUNCATED - response exceeded size limit]",
+                    _original_token_count: currentTokens,
+                    _truncated_token_count: parsedTokens,
+                };
+            }
+            // Still too large - calculate how much we need to reduce
+            // If we overshot, reduce ratio proportionally to how much we exceeded
+            const overshootRatio = parsedTokens / targetTokens; // e.g., 1.03 if we're 3% over
+            ratio = (ratio / overshootRatio) * 0.95; // Reduce by overshoot amount plus 5% safety margin
+            logger.debug("Truncation attempt resulted in overshoot, retrying", {
+                attempt,
+                targetTokens,
+                parsedTokens,
+                overshootRatio,
+                newRatio: ratio,
+            });
+        }
+        catch {
+            // JSON parse failed, try more aggressive truncation
+            ratio *= 0.85;
+        }
+    }
+    // If we exhausted all attempts, return the last successful parse (if any)
+    // or a very conservative fallback
+    if (lastResult && lastResult.tokens <= targetTokens * 1.1) {
+        // Within 10% of target - good enough
+        logger.warn("Truncation reached attempt limit but result is close enough", {
+            targetTokens,
+            actualTokens: lastResult.tokens,
+        });
+        return {
+            ...lastResult.parsed,
+            _truncation_notice: "... [TRUNCATED - response exceeded size limit]",
+            _original_token_count: currentTokens,
+            _truncated_token_count: lastResult.tokens,
+        };
+    }
+    // If all attempts failed, return a simple truncated structure
+    const safeChars = Math.floor(targetTokens * 3); // Very conservative
+    return {
+        truncated: true,
+        originalSize: currentTokens,
+        targetSize: targetTokens,
+        content: outputString.slice(0, safeChars),
+        warning: "Response was truncated due to size constraints (JSON parsing failed)",
+    };
+}

package/dist/runner/hooks/registry.js

@@ -1,10 +1,12 @@
 import { compactionTool } from "./predefined/compaction-tool";
+import { toolResponseCompactor } from "./predefined/tool-response-compactor";
 /**
  * Registry of predefined hook callbacks
  * Maps callback names to their implementations
  */
 export const HOOK_REGISTRY = {
     compaction_tool: compactionTool,
+    tool_response_compactor: toolResponseCompactor,
 };
 /**
  * Check if a callback name is a predefined hook