@townco/agent 0.1.84 → 0.1.85

package/dist/definition/index.d.ts

@@ -22,7 +22,6 @@ export declare const HookConfigSchema: z.ZodObject<{
         threshold: z.ZodNumber;
     }, z.core.$strip>, z.ZodObject<{
         maxTokensSize: z.ZodOptional<z.ZodNumber>;
-        responseTruncationThreshold: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>]>>;
     callback: z.ZodString;
 }, z.core.$strip>;
@@ -79,7 +78,6 @@ export declare const AgentDefinitionSchema: z.ZodObject<{
             threshold: z.ZodNumber;
         }, z.core.$strip>, z.ZodObject<{
             maxTokensSize: z.ZodOptional<z.ZodNumber>;
-            responseTruncationThreshold: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>]>>;
         callback: z.ZodString;
     }, z.core.$strip>>>;

package/dist/definition/index.js

@@ -65,7 +65,6 @@ export const HookConfigSchema = z.object({
         // For tool_response hooks
         z.object({
             maxTokensSize: z.number().min(0).optional(),
-            responseTruncationThreshold: z.number().min(0).max(100).optional(),
         }),
     ])
         .optional(),

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

@@ -9,7 +9,7 @@ export declare const zAgentRunnerParams: z.ZodObject<{
     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<"artifacts">, z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">, z.ZodLiteral<"town_web_search">, z.ZodLiteral<"filesystem">, z.ZodLiteral<"generate_image">, z.ZodLiteral<"town_generate_image">, z.ZodLiteral<"browser">]>, z.ZodObject<{
+    tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"artifacts">, z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">, z.ZodLiteral<"town_web_search">, z.ZodLiteral<"filesystem">, z.ZodLiteral<"generate_image">, z.ZodLiteral<"town_generate_image">, z.ZodLiteral<"browser">, z.ZodLiteral<"document_extract">]>, z.ZodObject<{
         type: z.ZodLiteral<"custom">;
         modulePath: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
@@ -49,7 +49,6 @@ export declare const zAgentRunnerParams: z.ZodObject<{
             threshold: z.ZodNumber;
         }, z.core.$strip>, z.ZodObject<{
             maxTokensSize: z.ZodOptional<z.ZodNumber>;
-            responseTruncationThreshold: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>]>>;
         callback: z.ZodString;
     }, z.core.$strip>>>;

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

@@ -1,5 +1,5 @@
 import type { ContextEntry } from "../../acp-server/session-storage";
-import type { HookCallback, HookConfig, HookNotification, ReadonlySession } from "./types";
+import type { HookCallback, HookConfig, HookNotification, HookStorageInterface, ReadonlySession } from "./types";
 /**
  * Callback for streaming hook notifications in real-time
  */
@@ -12,7 +12,9 @@ export declare class HookExecutor {
     private model;
     private loadCallback;
     private onNotification;
-    constructor(hooks: HookConfig[], model: string, loadCallback: (callbackRef: string) => Promise<HookCallback>, onNotification?: OnHookNotification);
+    private storage;
+    private sessionId;
+    constructor(hooks: HookConfig[], model: string, loadCallback: (callbackRef: string) => Promise<HookCallback>, onNotification?: OnHookNotification, storage?: HookStorageInterface, sessionId?: string);
     /**
      * Emit a notification - sends immediately if callback provided, otherwise collects for batch return
      */

package/dist/runner/hooks/executor.js

@@ -9,11 +9,15 @@ export class HookExecutor {
     model;
     loadCallback;
     onNotification;
-    constructor(hooks, model, loadCallback, onNotification) {
+    storage;
+    sessionId;
+    constructor(hooks, model, loadCallback, onNotification, storage, sessionId) {
         this.hooks = hooks;
         this.model = model;
         this.loadCallback = loadCallback;
         this.onNotification = onNotification;
+        this.storage = storage;
+        this.sessionId = sessionId;
     }
     /**
      * Emit a notification - sends immediately if callback provided, otherwise collects for batch return
@@ -84,6 +88,8 @@ export class HookExecutor {
                 maxTokens,
                 percentage,
                 model: this.model,
+                sessionId: this.sessionId,
+                storage: this.storage,
             };
             const result = await callback(hookContext);
             // Notify completion
@@ -189,6 +195,8 @@ export class HookExecutor {
                 maxTokens,
                 percentage,
                 model: this.model,
+                sessionId: this.sessionId,
+                storage: this.storage,
                 toolResponse,
             };
             const result = await callback(hookContext);

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

@@ -0,0 +1,37 @@
+/**
+ * Chunk manager for document context extraction
+ *
+ * Handles dynamic chunk sizing and document splitting
+ * to maximize efficiency while staying within model context limits.
+ */
+import type { ChunkInfo, ExtractorConfig } from "./types.js";
+/**
+ * Calculate optimal chunk size based on model context and overhead
+ *
+ * Goal: Maximize chunk size to minimize iterations while leaving room for:
+ * - System prompt
+ * - LLM response buffer
+ * - Safety margin
+ */
+export declare function calculateChunkSize(config: ExtractorConfig): number;
+/**
+ * Calculate maximum iterations based on document size and chunk size
+ */
+export declare function calculateMaxIterations(documentTokens: number, chunkSizeTokens: number): number;
+/**
+ * Split a document string into chunks with optional overlap
+ *
+ * The overlap helps maintain context continuity at chunk boundaries,
+ * ensuring the LLM doesn't miss information that spans boundaries.
+ */
+export declare function createChunks(content: string, chunkSizeTokens: number, overlapTokens?: number): ChunkInfo[];
+/**
+ * Get summary statistics about chunks
+ */
+export declare function getChunkStats(chunks: ChunkInfo[]): {
+    totalChunks: number;
+    totalTokens: number;
+    avgTokensPerChunk: number;
+    minChunkTokens: number;
+    maxChunkTokens: number;
+};

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

@@ -0,0 +1,134 @@
+/**
+ * Chunk manager for document context extraction
+ *
+ * Handles dynamic chunk sizing and document splitting
+ * to maximize efficiency while staying within model context limits.
+ */
+import { countTokens } from "../../../../utils/token-counter.js";
+/**
+ * Calculate optimal chunk size based on model context and overhead
+ *
+ * Goal: Maximize chunk size to minimize iterations while leaving room for:
+ * - System prompt
+ * - LLM response buffer
+ * - Safety margin
+ */
+export function calculateChunkSize(config) {
+    const { modelContextSize, systemPromptTokens } = config;
+    // Reserve space for:
+    // - System prompt (~500 tokens for extraction instructions)
+    // - LLM response buffer (~2000 tokens for scoring/extraction output)
+    // - Safety margin (10%)
+    const responseBuffer = 2000;
+    const overhead = systemPromptTokens + responseBuffer;
+    const availableForChunk = modelContextSize - overhead;
+    const safeChunkSize = Math.floor(availableForChunk * 0.9);
+    // Minimum chunk size to ensure meaningful content (10K tokens)
+    const minChunkSize = 10000;
+    return Math.max(safeChunkSize, minChunkSize);
+}
+/**
+ * Calculate maximum iterations based on document size and chunk size
+ */
+export function calculateMaxIterations(documentTokens, chunkSizeTokens) {
+    // Number of chunks + buffer for processing overhead
+    const estimatedChunks = Math.ceil(documentTokens / chunkSizeTokens);
+    // Add 2 iterations for analysis and merging phases
+    return estimatedChunks + 2;
+}
+/**
+ * Split a document string into chunks with optional overlap
+ *
+ * The overlap helps maintain context continuity at chunk boundaries,
+ * ensuring the LLM doesn't miss information that spans boundaries.
+ */
+export function createChunks(content, chunkSizeTokens, overlapTokens = 200) {
+    const chunks = [];
+    const totalTokens = countTokens(content);
+    // If content fits in a single chunk, return it as-is
+    if (totalTokens <= chunkSizeTokens) {
+        return [
+            {
+                index: 0,
+                startOffset: 0,
+                endOffset: content.length,
+                tokenCount: totalTokens,
+                content,
+            },
+        ];
+    }
+    // Estimate characters per token for this content
+    const charsPerToken = content.length / totalTokens;
+    // Calculate target chunk size in characters
+    const targetChunkChars = Math.floor(chunkSizeTokens * charsPerToken);
+    const overlapChars = Math.floor(overlapTokens * charsPerToken);
+    let currentOffset = 0;
+    let chunkIndex = 0;
+    while (currentOffset < content.length) {
+        // Calculate end offset for this chunk
+        let endOffset = Math.min(currentOffset + targetChunkChars, content.length);
+        // Try to break at a natural boundary (newline or sentence end)
+        if (endOffset < content.length) {
+            const searchStart = Math.max(currentOffset, endOffset - Math.floor(targetChunkChars * 0.1));
+            const searchRegion = content.slice(searchStart, endOffset);
+            // Look for natural break points (paragraph break preferred, then sentence)
+            const paragraphBreak = searchRegion.lastIndexOf("\n\n");
+            const sentenceEnd = searchRegion.search(/[.!?]\s+[A-Z]/);
+            const newline = searchRegion.lastIndexOf("\n");
+            if (paragraphBreak !== -1) {
+                endOffset = searchStart + paragraphBreak + 2;
+            }
+            else if (sentenceEnd !== -1) {
+                endOffset = searchStart + sentenceEnd + 1;
+            }
+            else if (newline !== -1) {
+                endOffset = searchStart + newline + 1;
+            }
+        }
+        // Extract chunk content
+        const chunkContent = content.slice(currentOffset, endOffset);
+        const chunkTokens = countTokens(chunkContent);
+        chunks.push({
+            index: chunkIndex,
+            startOffset: currentOffset,
+            endOffset,
+            tokenCount: chunkTokens,
+            content: chunkContent,
+        });
+        // Move to next chunk with overlap
+        // For the last chunk, we don't need overlap
+        if (endOffset >= content.length) {
+            break;
+        }
+        currentOffset = Math.max(currentOffset + 1, endOffset - overlapChars);
+        chunkIndex++;
+        // Safety check to prevent infinite loops
+        if (chunkIndex > 1000) {
+            break;
+        }
+    }
+    return chunks;
+}
+/**
+ * Get summary statistics about chunks
+ */
+export function getChunkStats(chunks) {
+    if (chunks.length === 0) {
+        return {
+            totalChunks: 0,
+            totalTokens: 0,
+            avgTokensPerChunk: 0,
+            minChunkTokens: 0,
+            maxChunkTokens: 0,
+        };
+    }
+    const tokenCounts = chunks.map((c) => c.tokenCount);
+    const totalTokens = tokenCounts.reduce((a, b) => a + b, 0);
+    return {
+        totalChunks: chunks.length,
+        totalTokens,
+        avgTokensPerChunk: Math.round(totalTokens / chunks.length),
+        minChunkTokens: Math.min(...tokenCounts),
+        maxChunkTokens: Math.max(...tokenCounts),
+    };
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Content extractor for document chunks
+ *
+ * Phase 2 of extraction: Extract relevant information from high-scoring chunks.
+ */
+import type { ChunkExtractionResult, ChunkInfo, ExtractorConfig } from "./types.js";
+/**
+ * Extract content from all relevant chunks
+ *
+ * This is Phase 2 of the extraction process.
+ * Only chunks that meet the relevance threshold are processed.
+ */
+export declare function extractFromChunks(chunks: ChunkInfo[], keyRequirements: string, config: ExtractorConfig, onProgress?: (extracted: number, total: number) => void): Promise<Map<number, ChunkExtractionResult>>;
+/**
+ * Merge extracted content into a single result
+ */
+export declare function mergeExtractions(extractions: Map<number, ChunkExtractionResult>, originalChunks: ChunkInfo[]): {
+    content: string;
+    keyFacts: string[];
+};

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

@@ -0,0 +1,171 @@
+/**
+ * Content extractor for document chunks
+ *
+ * Phase 2 of extraction: Extract relevant information from high-scoring chunks.
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import { createLogger } from "../../../../logger.js";
+import { telemetry } from "../../../../telemetry/index.js";
+const logger = createLogger("content-extractor");
+// Create Anthropic client directly (not using LangChain)
+const anthropic = new Anthropic({
+    apiKey: process.env.ANTHROPIC_API_KEY,
+});
+const EXTRACTION_SYSTEM_PROMPT = `You are extracting relevant information from a document chunk.
+
+Your task is to extract ONLY the information that matches the extraction requirements.
+Be concise but preserve important details, structure, and relationships.
+
+Guidelines:
+1. Focus on information directly related to the requirements
+2. Preserve exact values, names, identifiers, and technical details
+3. Maintain relationships between pieces of information
+4. Summarize verbose explanations while keeping key facts
+5. Omit completely irrelevant content
+
+Respond with ONLY a JSON object in this exact format:
+{"extracted": "concise extracted content as a string", "keyFacts": ["fact1", "fact2", ...]}
+
+Do not include any other text before or after the JSON.`;
+/**
+ * Build the extraction prompt for a chunk
+ */
+function buildExtractionPrompt(chunkContent, keyRequirements, chunkIndex, totalChunks, relevanceScore) {
+    return `## Extraction Requirements
+${keyRequirements}
+
+## Content Chunk (${chunkIndex + 1}/${totalChunks}, relevance score: ${relevanceScore}/10)
+${chunkContent}
+
+## Task
+Extract all information relevant to the requirements above. Preserve important details.`;
+}
+/**
+ * Parse extraction result from LLM response
+ */
+function parseExtractionResult(responseText) {
+    try {
+        // Try to extract JSON from the response
+        const jsonMatch = responseText.match(/\{[\s\S]*?\}/);
+        if (jsonMatch) {
+            const parsed = JSON.parse(jsonMatch[0]);
+            return {
+                extracted: String(parsed.extracted || ""),
+                keyFacts: Array.isArray(parsed.keyFacts)
+                    ? parsed.keyFacts.map(String)
+                    : [],
+            };
+        }
+    }
+    catch {
+        // Fall through to raw extraction
+    }
+    // If JSON parsing failed, use the raw response
+    return {
+        extracted: responseText.trim(),
+        keyFacts: [],
+    };
+}
+/**
+ * Extract content from a single chunk
+ */
+async function extractFromChunk(chunk, keyRequirements, totalChunks, config) {
+    const span = telemetry.startSpan("extractor.extract_chunk", {
+        "gen_ai.operation.name": "chat",
+        "gen_ai.provider.name": "anthropic",
+        "gen_ai.request.model": config.model,
+        "extractor.phase": "extracting",
+        "extractor.chunk_index": chunk.index,
+        "extractor.chunk_tokens": chunk.tokenCount,
+        "extractor.relevance_score": chunk.relevanceScore ?? 0,
+    });
+    try {
+        const prompt = buildExtractionPrompt(chunk.content, keyRequirements, chunk.index, totalChunks, chunk.relevanceScore ?? 5);
+        const response = await telemetry.withActiveSpanAsync(span, () => anthropic.messages.create({
+            model: config.model,
+            max_tokens: 4096,
+            temperature: 0,
+            system: EXTRACTION_SYSTEM_PROMPT,
+            messages: [{ role: "user", content: prompt }],
+        }));
+        telemetry.recordTokenUsage(response.usage.input_tokens, response.usage.output_tokens, span);
+        telemetry.endSpan(span);
+        const firstContent = response.content[0];
+        const responseText = firstContent && firstContent.type === "text" ? firstContent.text : "";
+        return parseExtractionResult(responseText);
+    }
+    catch (error) {
+        telemetry.endSpan(span, error);
+        logger.error("Failed to extract from chunk", {
+            chunkIndex: chunk.index,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        // Return empty extraction on error
+        return { extracted: "", keyFacts: [] };
+    }
+}
+/**
+ * Extract content from all relevant chunks
+ *
+ * This is Phase 2 of the extraction process.
+ * Only chunks that meet the relevance threshold are processed.
+ */
+export async function extractFromChunks(chunks, keyRequirements, config, onProgress) {
+    // Filter to only relevant chunks
+    const relevantChunks = chunks.filter((c) => (c.relevanceScore ?? 0) >= config.relevanceThreshold);
+    logger.info("Starting content extraction phase", {
+        totalChunks: chunks.length,
+        relevantChunks: relevantChunks.length,
+        threshold: config.relevanceThreshold,
+    });
+    const extractions = new Map();
+    for (const chunk of relevantChunks) {
+        const result = await extractFromChunk(chunk, keyRequirements, chunks.length, config);
+        // Only store non-empty extractions
+        if (result.extracted.trim() || result.keyFacts.length > 0) {
+            extractions.set(chunk.index, result);
+        }
+        logger.debug("Chunk extraction complete", {
+            chunkIndex: chunk.index,
+            extractedLength: result.extracted.length,
+            keyFactsCount: result.keyFacts.length,
+        });
+        onProgress?.(extractions.size, relevantChunks.length);
+    }
+    logger.info("Content extraction complete", {
+        chunksProcessed: relevantChunks.length,
+        chunksWithContent: extractions.size,
+    });
+    return extractions;
+}
+/**
+ * Merge extracted content into a single result
+ */
+export function mergeExtractions(extractions, originalChunks) {
+    // Sort by original chunk index to maintain document order
+    const sortedEntries = Array.from(extractions.entries()).sort(([a], [b]) => a - b);
+    const allKeyFacts = [];
+    const contentParts = [];
+    for (const [chunkIndex, result] of sortedEntries) {
+        if (result.extracted.trim()) {
+            // Get the original chunk's relevance score for context
+            const chunk = originalChunks.find((c) => c.index === chunkIndex);
+            const score = chunk?.relevanceScore ?? 5;
+            // Add a section header for high-relevance content
+            if (score >= 8) {
+                contentParts.push(`[High relevance - Chunk ${chunkIndex + 1}]`);
+            }
+            contentParts.push(result.extracted);
+        }
+        // Collect unique key facts
+        for (const fact of result.keyFacts) {
+            if (!allKeyFacts.includes(fact)) {
+                allKeyFacts.push(fact);
+            }
+        }
+    }
+    return {
+        content: contentParts.join("\n\n"),
+        keyFacts: allKeyFacts,
+    };
+}

package/dist/runner/hooks/predefined/document-context-extractor/extraction-state.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Extraction state persistence for debugging and recovery
+ *
+ * Saves intermediate extraction state to session artifacts,
+ * allowing for debugging and potential recovery if extraction fails mid-way.
+ */
+import type { HookStorageInterface } from "../../types.js";
+import type { ChunkInfo, ExtractionPhase, ExtractionState } from "./types.js";
+/**
+ * Re-export the storage interface for convenience
+ */
+export type StorageInterface = HookStorageInterface;
+/**
+ * Create a new extraction state
+ */
+export declare function createExtractionState(params: {
+    sessionId: string;
+    toolCallId: string;
+    toolName: string;
+    originalTokenCount: number;
+    targetTokens: number;
+    keyRequirements: string;
+    chunks: ChunkInfo[];
+    maxIterations: number;
+}): ExtractionState;
+/**
+ * Update extraction state phase
+ */
+export declare function updateStatePhase(state: ExtractionState, phase: ExtractionPhase): ExtractionState;
+/**
+ * Update chunk relevance score in state
+ */
+export declare function updateChunkScore(state: ExtractionState, chunkIndex: number, score: number, reason: string): ExtractionState;
+/**
+ * Add extracted content for a chunk
+ */
+export declare function addExtractedContent(state: ExtractionState, chunkIndex: number, content: string): ExtractionState;
+/**
+ * Record an error in state
+ */
+export declare function recordError(state: ExtractionState, error: string): ExtractionState;
+/**
+ * Increment iteration counter
+ */
+export declare function incrementIteration(state: ExtractionState): ExtractionState;
+/**
+ * Save extraction state to artifacts
+ */
+export declare function saveExtractionState(storage: StorageInterface, state: ExtractionState): void;
+/**
+ * Load extraction state from artifacts
+ */
+export declare function loadExtractionState(storage: StorageInterface, sessionId: string, toolName: string, toolCallId: string): ExtractionState | null;
+/**
+ * Check if extraction state exists
+ */
+export declare function hasExtractionState(storage: StorageInterface, sessionId: string, toolName: string, toolCallId: string): boolean;

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

@@ -0,0 +1,126 @@
+/**
+ * Extraction state persistence for debugging and recovery
+ *
+ * Saves intermediate extraction state to session artifacts,
+ * allowing for debugging and potential recovery if extraction fails mid-way.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Create a new extraction state
+ */
+export function createExtractionState(params) {
+    const now = new Date().toISOString();
+    return {
+        sessionId: params.sessionId,
+        toolCallId: params.toolCallId,
+        toolName: params.toolName,
+        originalTokenCount: params.originalTokenCount,
+        targetTokens: params.targetTokens,
+        keyRequirements: params.keyRequirements,
+        chunks: params.chunks,
+        phase: "initializing",
+        extractedContent: {},
+        currentIteration: 0,
+        maxIterations: params.maxIterations,
+        errors: [],
+        startedAt: now,
+        updatedAt: now,
+    };
+}
+/**
+ * Update extraction state phase
+ */
+export function updateStatePhase(state, phase) {
+    return {
+        ...state,
+        phase,
+        updatedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Update chunk relevance score in state
+ */
+export function updateChunkScore(state, chunkIndex, score, reason) {
+    const updatedChunks = state.chunks.map((chunk) => chunk.index === chunkIndex
+        ? { ...chunk, relevanceScore: score, scoreReason: reason }
+        : chunk);
+    return {
+        ...state,
+        chunks: updatedChunks,
+        updatedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Add extracted content for a chunk
+ */
+export function addExtractedContent(state, chunkIndex, content) {
+    return {
+        ...state,
+        extractedContent: {
+            ...state.extractedContent,
+            [chunkIndex]: content,
+        },
+        updatedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Record an error in state
+ */
+export function recordError(state, error) {
+    return {
+        ...state,
+        errors: [...state.errors, error],
+        updatedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Increment iteration counter
+ */
+export function incrementIteration(state) {
+    return {
+        ...state,
+        currentIteration: state.currentIteration + 1,
+        updatedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Get the file path for extraction state
+ */
+function getStatePath(storage, sessionId, toolName, toolCallId) {
+    return join(storage.getArtifactsDir(sessionId), `tool-${toolName}`, `${toolCallId}.extraction-state.json`);
+}
+/**
+ * Save extraction state to artifacts
+ */
+export function saveExtractionState(storage, state) {
+    const toolDir = join(storage.getArtifactsDir(state.sessionId), `tool-${state.toolName}`);
+    if (!existsSync(toolDir)) {
+        mkdirSync(toolDir, { recursive: true });
+    }
+    const filePath = getStatePath(storage, state.sessionId, state.toolName, state.toolCallId);
+    writeFileSync(filePath, JSON.stringify(state, null, 2), "utf-8");
+}
+/**
+ * Load extraction state from artifacts
+ */
+export function loadExtractionState(storage, sessionId, toolName, toolCallId) {
+    const filePath = getStatePath(storage, sessionId, toolName, toolCallId);
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(filePath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if extraction state exists
+ */
+export function hasExtractionState(storage, sessionId, toolName, toolCallId) {
+    const filePath = getStatePath(storage, sessionId, toolName, toolCallId);
+    return existsSync(filePath);
+}

package/dist/runner/hooks/predefined/document-context-extractor/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Document Context Extractor
+ *
+ * Main orchestration for extracting relevant information from large tool responses.
+ *
+ * Two-phase approach:
+ * 1. Score all chunks for relevance (0-10)
+ * 2. Extract only from high-scoring chunks
+ *
+ * Falls back to truncation if extraction fails.
+ */
+import type { HookStorageInterface } from "../../types.js";
+import type { ExtractorResult } from "./types.js";
+/**
+ * Main extraction function
+ *
+ * Extracts relevant information from a large tool response using a two-phase approach:
+ * 1. Score all chunks for relevance
+ * 2. Extract from high-scoring chunks
+ */
+export declare function extractDocumentContext(rawOutput: Record<string, unknown>, toolName: string, toolCallId: string, toolInput: Record<string, unknown>, conversationContext: string, targetTokens: number, sessionId: string, storage?: HookStorageInterface): Promise<ExtractorResult>;
+export type { ChunkInfo, ExtractionState, ExtractorConfig, ExtractorResult, } from "./types.js";