@memberjunction/ai-agents 5.48.0 → 5.49.0

package/dist/ConversationCompactionManager.js

@@ -0,0 +1,384 @@
+/**
+ * @fileoverview Cross-turn conversation compaction manager.
+ *
+ * Implements the durable summary layer from plans/agent-conversation-compaction.md:
+ * when a conversation's assembled context window crosses the effective trigger budget,
+ * a single summary prompt folds the prior running summary plus the raw message delta
+ * into a new summary, persisted on the boundary row's
+ * `ConversationDetail.SummaryOfEarlierConversation` (with `SummaryPromptRunID` linking
+ * the producing `AIPromptRun` for cost/model audit). Subsequent runs assemble
+ * `[summary, boundary row, ...tail]` via `ConversationEngine.AssembleContextWindow`
+ * over rows from the single-sourced `ConversationEngine.LoadWindowRowsFresh` loader.
+ *
+ * This class owns the trigger math, boundary selection, prompt invocation, and the
+ * boundary-row write. BaseAgent owns run-step recording and when the check fires
+ * (pre-turn fallback / post-turn fire-and-forget).
+ *
+ * @module @memberjunction/ai-agents
+ */
+import { LogError, LogStatusEx, Metadata } from '@memberjunction/core';
+import { NormalizeUUID, UUIDsEqual } from '@memberjunction/global';
+import { ConversationEngine } from '@memberjunction/core-entities';
+import { AIPromptParams, ExtractPromptResultText } from '@memberjunction/ai-core-plus';
+import { FormatSequencedHistoryLine } from './conversation-history-format.js';
+import { AIPromptRunner } from '@memberjunction/ai-prompts';
+import { AIEngine } from '@memberjunction/aiengine';
+/** Name of the system-default cross-turn summary prompt (seeded metadata). */
+const CONVERSATION_SUMMARY_PROMPT_NAME = 'Conversation Summary';
+/** Conservative context default, mirroring BaseAgent.getModelContextLimit's fallback. */
+const DEFAULT_CONTEXT_TOKENS = 8000;
+/**
+ * Safety values for the two percents. The AIAgentType columns are NOT NULL with DB
+ * defaults (75/30), so these only apply on typeless programmatic runs — keep in sync
+ * with the migration defaults.
+ */
+const DEFAULT_TRIGGER_PERCENT = 75;
+const DEFAULT_TARGET_PERCENT = 30;
+/** Tokens reserved for the yet-unwritten new summary when choosing the boundary. */
+const SUMMARY_RESERVE_TOKENS = 1500;
+/**
+ * Minimum projected token relief for a compaction pass to be worth its summary-prompt
+ * LLM call. Also exceeds a typical turn's context growth, so a degenerate budget (a
+ * trigger at or below the steady-state summary size) stops churning — without this,
+ * such a config re-fires a wasted summary call on EVERY turn while advancing the
+ * boundary one message at a time (observed live during contour testing).
+ */
+const MIN_COMPACTION_GAIN_TOKENS = 500;
+/** Below this many raw messages a compaction pass is not worth a prompt run. */
+const MIN_MESSAGES_TO_COMPACT = 4;
+/** Per-message character cap when rendering the delta for the summary prompt. */
+const MAX_DELTA_MESSAGE_CHARS = 10_000;
+/**
+ * Owns cross-turn (Tier A) conversation compaction: budget resolution, trigger math,
+ * boundary selection, the summary prompt run, and the durable boundary-row write.
+ * Stateless aside from an in-process re-entrancy guard; all entry points are static.
+ */
+export class ConversationCompactionManager {
+    /** Conversations with a compaction currently in flight in this process (re-entrancy guard). */
+    static { this.inFlightConversations = new Set(); }
+    /** Conversations already warned (once per process) about an unsatisfiable trigger budget. */
+    static { this.warnedConversationBudgets = new Set(); }
+    /** Agents already warned (once per process) about an inverted target/trigger percent pair. */
+    static { this.warnedAgentPercentConfigs = new Set(); }
+    /**
+     * Resolves the effective context budget for a run.
+     *
+     * MaxTokens: `Agent.ContextWindowMaxTokens || AgentType.ContextWindowMaxTokens ||
+     * modelMaxInputTokens || 8000`, then clamped to `modelMaxInputTokens` when the
+     * configured value exceeds it (never silently exceed the model — the clamp is
+     * surfaced via `ClampedToModel` for the caller to log). Percents:
+     * `Agent || AgentType || framework default` (`||` by design — zero is not a valid
+     * value for any of these knobs, and NULL means inherit).
+     *
+     * @param agent - The executing agent
+     * @param agentType - The agent's type (null for typeless programmatic runs)
+     * @param modelMaxInputTokens - The selected model's MaxInputTokens when known, else null
+     */
+    static ResolveEffectiveBudget(agent, agentType, modelMaxInputTokens) {
+        let maxTokens;
+        let boundedBy;
+        if (agent.ContextWindowMaxTokens) {
+            maxTokens = agent.ContextWindowMaxTokens;
+            boundedBy = 'Agent';
+        }
+        else if (agentType?.ContextWindowMaxTokens) {
+            maxTokens = agentType.ContextWindowMaxTokens;
+            boundedBy = 'AgentType';
+        }
+        else if (modelMaxInputTokens) {
+            maxTokens = modelMaxInputTokens;
+            boundedBy = 'Model';
+        }
+        else {
+            maxTokens = DEFAULT_CONTEXT_TOKENS;
+            boundedBy = 'Default';
+        }
+        let clampedToModel = false;
+        if (modelMaxInputTokens && maxTokens > modelMaxInputTokens) {
+            maxTokens = modelMaxInputTokens;
+            boundedBy = 'Model';
+            clampedToModel = true;
+        }
+        // Defense-in-depth clamps mirroring the DB CHECK constraints (percents 1-100,
+        // target strictly under trigger). The DB enforces these on AIAgentType (both
+        // NOT NULL there); AIAgent's nullable inherit semantics mean the EFFECTIVE pair
+        // can only be validated here, after resolution — an inverted pair would make
+        // every pass select a no-progress boundary and churn.
+        const rawTriggerPercent = agent.CompactionTriggerPercent || agentType?.CompactionTriggerPercent || DEFAULT_TRIGGER_PERCENT;
+        const rawTargetPercent = agent.CompactionTargetPercent || agentType?.CompactionTargetPercent || DEFAULT_TARGET_PERCENT;
+        const triggerPercent = Math.min(Math.max(rawTriggerPercent, 1), 100);
+        let targetPercent = Math.min(Math.max(rawTargetPercent, 1), 100);
+        if (targetPercent >= triggerPercent) {
+            targetPercent = Math.max(1, triggerPercent - 1);
+            // Warn once per agent per process — this re-resolves every turn while the
+            // config stays wrong, and the operator only needs telling once (§8: don't
+            // spam logs, don't lose the diagnostic either).
+            const agentKey = NormalizeUUID(agent.ID);
+            if (!this.warnedAgentPercentConfigs.has(agentKey)) {
+                this.warnedAgentPercentConfigs.add(agentKey);
+                LogStatusEx({ message: `⚠️ [CrossTurnCompaction] CompactionTargetPercent (${rawTargetPercent}) >= CompactionTriggerPercent (${rawTriggerPercent}) for agent '${agent.Name}' — clamped target to ${targetPercent}. Fix the agent/type configuration.` });
+            }
+        }
+        return {
+            MaxTokens: maxTokens,
+            TriggerTokens: Math.floor(maxTokens * triggerPercent / 100),
+            TargetTokens: Math.floor(maxTokens * targetPercent / 100),
+            ClampedToModel: clampedToModel,
+            BoundedBy: boundedBy
+        };
+    }
+    /**
+     * Checks the conversation's assembled window against the trigger budget and, when
+     * crossed, runs the summary prompt (input = prior summary + raw delta only — the
+     * recursive pattern) and persists the result on the boundary row. Never throws for
+     * business failures — returns an outcome with `ErrorMessage` and leaves the
+     * conversation untouched, so a failed compaction simply re-triggers next turn.
+     */
+    static async CompactIfNeeded(input) {
+        const conversationKey = NormalizeUUID(input.ConversationId);
+        if (this.inFlightConversations.has(conversationKey)) {
+            return { Fired: false, SkippedReason: 'Compaction already in flight for this conversation', TokensBefore: 0, Warnings: [] };
+        }
+        this.inFlightConversations.add(conversationKey);
+        try {
+            return await this.compactIfNeededInternal(input);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            LogError(`Cross-turn compaction failed for conversation ${input.ConversationId}: ${message}`);
+            return { Fired: false, TokensBefore: 0, Warnings: [], ErrorMessage: message };
+        }
+        finally {
+            this.inFlightConversations.delete(conversationKey);
+        }
+    }
+    /** Core pass: window → trigger check → boundary + worth-it guards → prompt → boundary-row write. */
+    static async compactIfNeededInternal(input) {
+        const warnings = [];
+        if (input.Budget.ClampedToModel) {
+            warnings.push(`Configured ContextWindowMaxTokens exceeded the model's MaxInputTokens — clamped to ${input.Budget.MaxTokens}`);
+        }
+        const window = await this.loadWindowFresh(input);
+        const tokensBefore = input.EstimateTokens(window);
+        if (tokensBefore < input.Budget.TriggerTokens) {
+            this.logVerbose(input, `No compaction needed: ~${tokensBefore} tokens < trigger ${input.Budget.TriggerTokens}`);
+            return { Fired: false, SkippedReason: `Window ~${tokensBefore} tokens is under the ${input.Budget.TriggerTokens}-token trigger`, TokensBefore: tokensBefore, Warnings: warnings };
+        }
+        const { priorSummary, rawMessages } = this.splitWindow(window);
+        this.warnOnceIfBudgetUnsatisfiable(input, window, priorSummary, warnings);
+        const boundary = this.chooseBoundary(rawMessages, tokensBefore, input);
+        if ('skippedReason' in boundary) {
+            return { Fired: false, SkippedReason: boundary.skippedReason, TokensBefore: tokensBefore, Warnings: warnings };
+        }
+        const promptResult = await this.runSummaryPrompt(input, priorSummary, rawMessages.slice(0, boundary.index));
+        if (!promptResult.success) {
+            return { Fired: false, TokensBefore: tokensBefore, Warnings: warnings, ErrorMessage: promptResult.errorMessage, PromptId: promptResult.promptId };
+        }
+        const boundaryMessage = rawMessages[boundary.index];
+        await this.writeBoundaryRow(input, boundaryMessage.metadata.conversationDetailId, promptResult.summaryText, promptResult.promptRunId);
+        const tokensAfter = input.EstimateTokens([
+            { role: 'user', content: promptResult.summaryText },
+            ...rawMessages.slice(boundary.index)
+        ]);
+        this.logVerbose(input, `Compacted at sequence ${boundaryMessage.metadata.sequence}: ~${tokensBefore} → ~${tokensAfter} tokens`);
+        return {
+            Fired: true,
+            BoundarySequence: boundaryMessage.metadata.sequence,
+            PromptId: promptResult.promptId,
+            PromptRunId: promptResult.promptRunId,
+            PromptRun: promptResult.promptRun,
+            TokensBefore: tokensBefore,
+            TokensAfter: tokensAfter,
+            SummaryText: promptResult.summaryText,
+            Warnings: warnings
+        };
+    }
+    /**
+     * Loads the conversation window FRESH for this pass — via the single-sourced
+     * {@link ConversationEngine.LoadWindowRowsFresh} query (entity RLS via ContextUser,
+     * provider-scoped) assembled through the engine's pure fold — never the engine's
+     * process-global detail cache. Server-side compaction must see rows written by
+     * other servers (a warm cache can be stale across nodes) and must not grow an
+     * unbounded per-conversation cache in MJAPI. Honors `input.ExcludeDetailIds` (the
+     * in-flight placeholder row). Load failures throw — caught by
+     * {@link CompactIfNeeded}'s wrapper → ErrorMessage outcome, so the conversation is
+     * left untouched and the pass re-triggers later.
+     */
+    static async loadWindowFresh(input) {
+        const rows = await ConversationEngine.LoadWindowRowsFresh(input.ConversationId, input.ContextUser, input.Provider || Metadata.Provider // global-provider-ok: caller-supplied provider preferred; global is the documented last-resort fallback
+        );
+        return ConversationEngine.AssembleContextWindow(rows, {
+            excludeDetailIds: input.ExcludeDetailIds
+        });
+    }
+    /**
+     * Splits the assembled window into the leading running summary (when the engine
+     * placed one at index 0) and the raw sequence-addressable messages eligible for
+     * folding (summary rows and non-addressable placeholders are excluded).
+     */
+    static splitWindow(window) {
+        const priorSummary = window.length > 0 && window[0].metadata?.isConversationSummary
+            ? (typeof window[0].content === 'string' ? window[0].content : '')
+            : '';
+        const rawMessages = window.filter(m => !m.metadata?.isConversationSummary
+            && m.metadata?.sequence !== undefined
+            && !!m.metadata?.conversationDetailId);
+        return { priorSummary, rawMessages };
+    }
+    /**
+     * Unsatisfiable-budget warning: when the prior summary ALONE meets the trigger, no
+     * amount of folding can bring the window back under it — the operator needs a bigger
+     * ContextWindowMaxTokens or a higher CompactionTriggerPercent. Warns once per
+     * conversation per process; the guard skip paths in {@link chooseBoundary} stop the
+     * per-turn churn.
+     */
+    static warnOnceIfBudgetUnsatisfiable(input, window, priorSummary, warnings) {
+        const conversationKey = NormalizeUUID(input.ConversationId);
+        if (priorSummary.length === 0
+            || input.EstimateTokens([window[0]]) < input.Budget.TriggerTokens
+            || this.warnedConversationBudgets.has(conversationKey)) {
+            return;
+        }
+        this.warnedConversationBudgets.add(conversationKey);
+        const budgetWarning = `Compaction trigger (~${input.Budget.TriggerTokens} tokens) is at or below the running summary's size — the window can never get under the trigger. Raise ContextWindowMaxTokens or CompactionTriggerPercent for this agent/type.`;
+        warnings.push(budgetWarning);
+        LogStatusEx({ message: `⚠️ [CrossTurnCompaction] Conversation ${input.ConversationId}: ${budgetWarning}` });
+    }
+    /**
+     * Selects the fold boundary and applies the worth-it guards. Returns the boundary
+     * index into `rawMessages`, or a skip reason when there is no foldable boundary
+     * (too few addressable messages, or the window already fits the target tail —
+     * possible only with inverted trigger/target configs) or when the projected token
+     * relief is under {@link MIN_COMPACTION_GAIN_TOKENS} (not worth a summary-prompt
+     * LLM call).
+     */
+    static chooseBoundary(rawMessages, tokensBefore, input) {
+        const boundaryIndex = this.selectBoundaryIndex(rawMessages, input);
+        if (boundaryIndex === null) {
+            this.logVerbose(input, `Over trigger (~${tokensBefore} tokens) but no foldable boundary — ${rawMessages.length} addressable messages, target tail ${input.Budget.TargetTokens - SUMMARY_RESERVE_TOKENS} tokens`);
+            return { skippedReason: 'No foldable boundary (too few addressable messages, or the window already fits the target tail)' };
+        }
+        // Minimum-gain guard: projected post-compaction size = summary reserve + retained tail.
+        const projectedTokensAfter = SUMMARY_RESERVE_TOKENS + input.EstimateTokens(rawMessages.slice(boundaryIndex));
+        const projectedGain = tokensBefore - projectedTokensAfter;
+        if (projectedGain < MIN_COMPACTION_GAIN_TOKENS) {
+            this.logVerbose(input, `Skipping: projected gain ~${projectedGain} tokens < minimum ${MIN_COMPACTION_GAIN_TOKENS}`);
+            return { skippedReason: `Projected gain (~${projectedGain} tokens) is under the ${MIN_COMPACTION_GAIN_TOKENS}-token minimum — not worth a summary prompt run` };
+        }
+        return { index: boundaryIndex };
+    }
+    /**
+     * Picks the boundary index within the raw (non-summary, sequence-addressable)
+     * messages: the earliest message whose tail fits inside
+     * `TargetTokens - SUMMARY_RESERVE_TOKENS`, walking backward from the newest.
+     * Returns null when there is nothing worthwhile to fold (window too small or the
+     * boundary would sit at the first raw message, folding nothing).
+     */
+    static selectBoundaryIndex(rawMessages, input) {
+        if (rawMessages.length < MIN_MESSAGES_TO_COMPACT) {
+            return null;
+        }
+        const tailBudget = input.Budget.TargetTokens - SUMMARY_RESERVE_TOKENS;
+        let accumulated = 0;
+        let boundaryIndex = rawMessages.length - 1;
+        for (let i = rawMessages.length - 1; i >= 0; i--) {
+            const messageTokens = input.EstimateTokens([rawMessages[i]]);
+            if (accumulated + messageTokens > tailBudget) {
+                break;
+            }
+            accumulated += messageTokens;
+            boundaryIndex = i;
+        }
+        // The newest raw row must never be the boundary (possible when it alone exceeds
+        // the tail budget — the walk breaks on iteration one leaving boundaryIndex at
+        // length-1): it may be an in-flight row whose Message a resolver is still
+        // writing, and the boundary write's Load→Save would race it. Defense-in-depth
+        // alongside ExcludeDetailIds; the retained tail may then exceed TargetTokens
+        // (correctness over compression — the next turn simply re-triggers).
+        // MIN_MESSAGES_TO_COMPACT >= 4 guarantees length-2 >= 2, so the clamp never
+        // nulls a previously valid selection.
+        const clamped = Math.min(boundaryIndex, rawMessages.length - 2);
+        // boundaryIndex 0 would fold nothing (delta empty) — no progress, skip.
+        return clamped > 0 ? clamped : null;
+    }
+    /** Renders the delta and runs the summary prompt. */
+    static async runSummaryPrompt(input, priorSummary, delta) {
+        const prompt = this.resolveSummaryPrompt(input);
+        if (!prompt) {
+            return { success: false, summaryText: '', errorMessage: `No conversation summary prompt found (agent/type ConversationSummaryPromptID unset and no '${CONVERSATION_SUMMARY_PROMPT_NAME}' system prompt)` };
+        }
+        const promptParams = new AIPromptParams();
+        promptParams.prompt = prompt;
+        // Keys are the conversation-summary.template.md contract ({{ priorSummary }}, {{ deltaMessages }})
+        promptParams.data = {
+            priorSummary: priorSummary || '(none — this is the first compaction of this conversation)',
+            deltaMessages: delta.map(m => this.renderDeltaMessage(m)).join('\n')
+        };
+        promptParams.contextUser = input.ContextUser;
+        if (input.AgentRunId) {
+            // Links the summary AIPromptRun to the agent run (AgentRunID) so per-run
+            // cost rollups include the recursive summary sub-call.
+            promptParams.agentRunId = input.AgentRunId;
+        }
+        if (input.OnPromptRunCreated) {
+            promptParams.onPromptRunCreated = input.OnPromptRunCreated;
+        }
+        const runner = new AIPromptRunner();
+        const result = await runner.ExecutePrompt(promptParams);
+        const summaryText = ExtractPromptResultText(result);
+        if (!result.success || summaryText.length === 0) {
+            return { success: false, summaryText: '', promptId: prompt.ID, promptRunId: result.promptRun?.ID, errorMessage: result.errorMessage || 'Summary prompt returned no content' };
+        }
+        return { success: true, summaryText, promptId: prompt.ID, promptRunId: result.promptRun?.ID, promptRun: result.promptRun };
+    }
+    /** Prompt resolution: agent override, else type override, else the seeded system prompt by name. */
+    static resolveSummaryPrompt(input) {
+        const overrideId = input.Agent.ConversationSummaryPromptID || input.AgentType?.ConversationSummaryPromptID;
+        if (overrideId) {
+            const overridePrompt = AIEngine.Instance.Prompts.find(p => UUIDsEqual(p.ID, overrideId));
+            if (overridePrompt) {
+                return overridePrompt;
+            }
+            LogError(`ConversationSummaryPromptID ${overrideId} not found in AIEngine prompt cache — falling back to the system prompt`);
+        }
+        // Trimmed, case-insensitive compare (the AIPromptRunner 'Repair JSON' lookup style)
+        // so cosmetic re-casing of the seeded prompt's display name can't disable compaction.
+        const targetName = CONVERSATION_SUMMARY_PROMPT_NAME.toLowerCase();
+        return AIEngine.Instance.Prompts.find(p => p.Name.trim().toLowerCase() === targetName);
+    }
+    /** One delta line (shared `[seq N] Role: text` shape) with a per-message size cap. */
+    static renderDeltaMessage(message) {
+        const text = typeof message.content === 'string' ? message.content : JSON.stringify(message.content);
+        const capped = text.length > MAX_DELTA_MESSAGE_CHARS
+            ? `${text.slice(0, MAX_DELTA_MESSAGE_CHARS)}\n[truncated — ${text.length.toLocaleString()} chars total]`
+            : text;
+        return FormatSequencedHistoryLine(message.metadata?.sequence, message.role, capped);
+    }
+    /**
+     * Persists the summary on the boundary row. Written through a plain entity Save (the
+     * same external-save path everything else uses) so ConversationEngine's entity-event
+     * handler merges it into any warm cache in place — never through engine mutation
+     * helpers, whose self-mutation guard would skip the merge.
+     */
+    static async writeBoundaryRow(input, boundaryDetailId, summaryText, promptRunId) {
+        // Favor the caller-supplied provider; the global is the explicit last resort
+        const provider = input.Provider || Metadata.Provider; // global-provider-ok: caller-supplied provider preferred; global is the documented last-resort fallback
+        const detail = await provider.GetEntityObject('MJ: Conversation Details', input.ContextUser);
+        if (!(await detail.Load(boundaryDetailId))) {
+            throw new Error(`Failed to load boundary ConversationDetail ${boundaryDetailId}`);
+        }
+        detail.SummaryOfEarlierConversation = summaryText;
+        detail.SummaryPromptRunID = promptRunId || null;
+        if (!(await detail.Save())) {
+            throw new Error(`Boundary-row save failed: ${detail.LatestResult?.CompleteMessage || 'unknown error'}`);
+        }
+    }
+    static logVerbose(input, message) {
+        LogStatusEx({
+            message: `[CrossTurnCompaction] ${message}`,
+            verboseOnly: true,
+            isVerboseEnabled: () => input.Verbose === true
+        });
+    }
+}
+//# sourceMappingURL=ConversationCompactionManager.js.map

package/dist/ConversationCompactionManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConversationCompactionManager.js","sourceRoot":"","sources":["../src/ConversationCompactionManager.ts"],"names":[],"mappings":"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"}

package/dist/ConversationToolManager.d.ts

@@ -0,0 +1,154 @@
+/**
+ * @fileoverview Conversation-history retrieval tools (RLM-style addressable paging).
+ *
+ * The cross-turn summary (see ConversationCompactionManager) is deliberately lossy — a
+ * compact handle over history that has left the context window. These tools are the
+ * other half of the design (plans/agent-conversation-compaction.md §5): the full
+ * history stays in an addressable external store (ConversationDetail rows keyed by the
+ * persisted per-conversation `Sequence`), and the agent pages exact slices back in on
+ * demand instead of trusting the summary. Zero turn cost — calls ride the
+ * `conversationToolCalls` inline response field, mirroring `artifactToolCalls`.
+ *
+ * All reads are served from `ConversationEngine`'s per-conversation cache (one query on
+ * a cold miss, in-memory afterward).
+ *
+ * @module @memberjunction/ai-agents
+ */
+import { UserInfo } from '@memberjunction/core';
+/**
+ * The conversation-tool name vocabulary — single source of truth. The LLM is taught these
+ * exact strings (GetToolDocumentation + the loop-agent system template's response-type
+ * union), the dispatch switch matches them, and framework guidance messages enumerate them.
+ * Add/rename tools HERE; everything else derives from this array.
+ */
+export declare const ConversationToolNames: readonly ["getMessageBySequence", "getMessagesByRange", "searchConversation", "summarizeRange"];
+/** Tool names available on `conversationToolCalls` (derived from {@link ConversationToolNames}). */
+export type ConversationToolName = typeof ConversationToolNames[number];
+/**
+ * The seam through which `summarizeRange` runs its recursive LLM sub-call. Implemented by
+ * BaseAgent (which owns prompt execution and run-step observability) so this manager stays
+ * free of prompt-runner dependencies and trivially testable.
+ */
+export interface ConversationToolSummaryHost {
+    /**
+     * Runs the range-summary prompt over the rendered slice.
+     * @param rangeText - The `[seq N] Role: text` rendering of the requested range
+     * @param lens - The task-specific focus the summary must serve
+     * @returns The summary text plus the AIPromptRun ID of the sub-call (for lineage)
+     */
+    RunSummaryPrompt(rangeText: string, lens: string): Promise<{
+        text: string;
+        promptRunId?: string;
+    }>;
+}
+/**
+ * One conversation-tool invocation from the LLM. A single input shape with per-tool
+ * validation (mirrors the artifact tools' generic `input` while staying typed).
+ */
+export interface ConversationToolCall {
+    tool: ConversationToolName;
+    input: {
+        /** getMessageBySequence: the exact Sequence to fetch */
+        sequence?: number;
+        /** getMessagesByRange / searchConversation: inclusive range start */
+        startSequence?: number;
+        /** getMessagesByRange / searchConversation: inclusive range end */
+        endSequence?: number;
+        /** searchConversation: keyword (default) or regex pattern */
+        query?: string;
+        /** searchConversation: treat `query` as a regular expression */
+        isRegex?: boolean;
+        /** searchConversation: restrict to a role ('User' | 'AI') */
+        role?: string;
+        /** searchConversation: result cap (default 20, max 50) */
+        maxResults?: number;
+        /** summarizeRange: the task-specific focus the summary must serve */
+        lens?: string;
+    };
+}
+/** A message as returned by the paging tools. */
+export interface ConversationToolMessage {
+    sequence: number;
+    role: string;
+    /** Responding agent's name when the row was produced by an agent */
+    agent: string | null;
+    message: string;
+}
+/** One search hit: enough to decide whether to page the full message in. */
+export interface ConversationSearchHit {
+    sequence: number;
+    role: string;
+    agent: string | null;
+    snippet: string;
+    matchType: 'keyword' | 'regex';
+}
+/** Execution record for one tool call (step OutputData + next-turn result message). */
+export interface ConversationToolExecutionResult {
+    tool: ConversationToolName;
+    input: ConversationToolCall['input'];
+    result: {
+        success: boolean;
+        data?: unknown;
+        errorMessage?: string;
+    };
+    durationMs: number;
+    /** summarizeRange only: the AIPromptRun of the recursive sub-call (step TargetLogID lineage) */
+    promptRunId?: string;
+}
+/**
+ * Max conversationToolCalls executed per LLM response. Each call is a run step (and
+ * summarizeRange is a full LLM sub-call) — an unbounded Promise.all would let a single
+ * response fan out arbitrary work/cost. Excess calls are reported back to the model as
+ * skipped so it can re-request them next turn. Consumed by BaseAgent's executor.
+ */
+export declare const MAX_CONVERSATION_TOOL_CALLS_PER_TURN = 8;
+/**
+ * Per-run manager for conversation-history retrieval tools. Initialized with the run's
+ * conversationId (the availability gate — no conversation, no tools) and serving all
+ * reads from the ConversationEngine cache.
+ */
+export declare class ConversationToolManager {
+    private conversationId;
+    private contextUser;
+    private summaryHost;
+    /** Arms the manager for a run. Pass null conversationId to disable (programmatic runs). */
+    Initialize(conversationId: string | null, contextUser: UserInfo): void;
+    /** Wires the recursive-sub-call seam (BaseAgent owns prompt execution). */
+    SetSummaryHost(host: ConversationToolSummaryHost | null): void;
+    /** Disarms the manager (per-run reset). */
+    Clear(): void;
+    /** True when the run has a conversation to page against. */
+    get IsAvailable(): boolean;
+    /** Executes one tool call with timing + full error containment. */
+    ExecuteSingleToolCall(call: ConversationToolCall): Promise<ConversationToolExecutionResult>;
+    /**
+     * Markdown tool documentation injected into the system prompt (the
+     * `{{ _CONVERSATION_TOOLS }}` template block), rendered only when the run has a
+     * conversation.
+     */
+    GetToolDocumentation(): string;
+    /** Routes a call to its tool implementation. */
+    private dispatch;
+    /**
+     * The recursive sub-call (RLM pattern): renders the requested slice and hands it to
+     * the host's summary prompt with the caller's lens. The agent is not limited to the
+     * one baseline summary's framing — any window can be re-summarized however the
+     * current task needs, on a cheap sub-call model.
+     */
+    private summarizeRange;
+    /** `[seq N] Role: text` rendering (shared shape) with a total input budget for the sub-call model. */
+    private renderRangeForSummary;
+    /** Full conversation history, ordered by Sequence, from the engine cache. */
+    private loadOrderedDetails;
+    private getMessageBySequence;
+    private getMessagesByRange;
+    private searchConversation;
+    /** Compiles the query as a case-insensitive regex in regex mode; null in keyword mode. */
+    private compileSearchRegex;
+    /** Role and sequence-range filters applied to every candidate message in a search. */
+    private passesSearchFilters;
+    /** A ~300-char window centered on the match, with ellipses at cut edges. */
+    private buildSnippet;
+    private toToolMessage;
+}
+//# sourceMappingURL=ConversationToolManager.d.ts.map

package/dist/ConversationToolManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConversationToolManager.d.ts","sourceRoot":"","sources":["../src/ConversationToolManager.ts"],"names":[],"mappings":"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"}