@dexto/core 1.2.6 → 1.4.0

package/dist/llm/executor/turn-executor.d.ts

@@ -0,0 +1,166 @@
+import { LanguageModel, type ModelMessage } from 'ai';
+import { ContextManager } from '../../context/manager.js';
+import { ToolManager } from '../../tools/tool-manager.js';
+import { ExecutorResult } from './types.js';
+import type { IDextoLogger } from '../../logger/v2/types.js';
+import type { SessionEventBus } from '../../events/index.js';
+import type { ResourceManager } from '../../resources/index.js';
+import { DynamicContributorContext } from '../../systemPrompt/types.js';
+import { LLMContext } from '../types.js';
+import type { MessageQueueService } from '../../session/message-queue.js';
+import { type ModelLimits } from '../../context/compression/overflow.js';
+/**
+ * TurnExecutor orchestrates the agent loop using `stopWhen: stepCountIs(1)`.
+ *
+ * This is the main entry point that replaces Vercel's internal loop with our
+ * controlled execution, giving us control between steps for:
+ * - Message queue injection (Phase 6)
+ * - Compression decisions (Phase 4)
+ * - Pruning old tool outputs (Phase 5)
+ *
+ * Key design: Uses stopWhen: stepCountIs(1) to regain control after each step.
+ * A "step" = ONE LLM call + ALL tool executions from that call.
+ */
+export declare class TurnExecutor {
+    private model;
+    private toolManager;
+    private contextManager;
+    private eventBus;
+    private resourceManager;
+    private sessionId;
+    private config;
+    private llmContext;
+    private messageQueue;
+    private modelLimits?;
+    private externalSignal?;
+    private logger;
+    /**
+     * Per-step abort controller. Created fresh for each iteration of the loop.
+     * This allows soft cancel (abort current step) while still continuing with queued messages.
+     */
+    private stepAbortController;
+    private compressionStrategy;
+    /**
+     * Map to track approval metadata by toolCallId.
+     * Used to pass approval info from tool execution to result persistence.
+     */
+    private approvalMetadata;
+    constructor(model: LanguageModel, toolManager: ToolManager, contextManager: ContextManager<ModelMessage>, eventBus: SessionEventBus, resourceManager: ResourceManager, sessionId: string, config: {
+        maxSteps: number;
+        maxOutputTokens?: number | undefined;
+        temperature?: number | undefined;
+        baseURL?: string | undefined;
+    }, llmContext: LLMContext, logger: IDextoLogger, messageQueue: MessageQueueService, modelLimits?: ModelLimits | undefined, externalSignal?: AbortSignal | undefined);
+    /**
+     * Get StreamProcessor config from TurnExecutor state.
+     */
+    private getStreamProcessorConfig;
+    /**
+     * Main agent execution loop.
+     * Uses stopWhen: stepCountIs(1) to regain control after each step.
+     *
+     * @param contributorContext Context for system prompt contributors
+     * @param streaming If true, emits llm:chunk events during streaming. Default true.
+     */
+    execute(contributorContext: DynamicContributorContext, streaming?: boolean): Promise<ExecutorResult>;
+    /**
+     * Abort the current step execution.
+     * Note: For full run cancellation, use the external abort signal.
+     */
+    abort(): void;
+    /**
+     * Inject coalesced queued messages into the context as a single user message.
+     * This enables mid-task user guidance.
+     */
+    private injectQueuedMessages;
+    /**
+     * Validates if the current model supports tools.
+     * Uses a static cache to avoid repeated validation calls.
+     *
+     * For models using custom baseURL endpoints, makes a test call to verify tool support.
+     * Built-in providers without baseURL are assumed to support tools.
+     */
+    private validateToolSupport;
+    /**
+     * Creates tools with execute callbacks and toModelOutput.
+     *
+     * Key design decisions:
+     * - execute() returns raw result with inline images (async)
+     * - toModelOutput() formats for LLM consumption (sync)
+     * - StreamProcessor handles persistence via tool-result events
+     */
+    private createTools;
+    /**
+     * Format tool result for LLM consumption.
+     * Handles multimodal content (text + images).
+     *
+     * This handles RAW tool results - the structure may vary.
+     */
+    private formatToolResultForLLM;
+    /**
+     * Extract image data from a part, handling various formats.
+     */
+    private extractImageData;
+    /**
+     * Extract file data from a part.
+     */
+    private extractFileData;
+    /**
+     * Check if result has multimodal content array
+     */
+    private hasMultimodalContent;
+    /**
+     * Constants for pruning thresholds
+     */
+    private static readonly PRUNE_PROTECT;
+    private static readonly PRUNE_MINIMUM;
+    /**
+     * Prunes old tool outputs by marking them with compactedAt timestamp.
+     * Does NOT modify content - transformation happens at format time in
+     * ContextManager.getFormattedMessagesWithCompression().
+     *
+     * Algorithm:
+     * 1. Go backwards through history (most recent first)
+     * 2. Stop at summary message (only process post-summary messages)
+     * 3. Count tool message tokens
+     * 4. If total exceeds PRUNE_PROTECT, mark older ones for pruning
+     * 5. Only prune if savings exceed PRUNE_MINIMUM
+     */
+    private pruneOldToolOutputs;
+    /**
+     * Estimates tokens for tool message content using simple heuristic (length/4).
+     * Used for pruning decisions only - actual token counts come from API.
+     *
+     * Tool message content is always Array<TextPart | ImagePart | FilePart | UIResourcePart>
+     * after sanitization via SanitizedToolResult.
+     */
+    private estimateToolTokens;
+    /**
+     * Cleanup resources when execution scope exits.
+     * Called automatically via defer() on normal exit, throw, or abort.
+     */
+    private cleanup;
+    /**
+     * Check if context has overflowed based on actual token usage from API.
+     */
+    private checkAndHandleOverflow;
+    /**
+     * Compress context using ReactiveOverflowStrategy.
+     *
+     * Generates a summary of older messages and adds it to history.
+     * The actual token reduction happens at read-time via filterCompacted()
+     * in getFormattedMessagesWithCompression().
+     *
+     * @param originalTokens The actual input token count from API that triggered overflow
+     */
+    private compress;
+    /**
+     * Set telemetry span attributes for token usage.
+     */
+    private setTelemetryAttributes;
+    /**
+     * Map provider errors to DextoRuntimeError.
+     */
+    private mapProviderError;
+}
+//# sourceMappingURL=turn-executor.d.ts.map

package/dist/llm/executor/turn-executor.d.ts.map

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