actoviq-agent-sdk 0.3.0 → 0.3.1

package/dist/src/runtime/conversationEngine.js

@@ -1,12 +1,19 @@
-import { ActoviqSdkError, RunAbortedError, ToolExecutionError } from '../errors.js';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { ActoviqProviderApiError, ActoviqSdkError, RunAbortedError, ToolExecutionError } from '../errors.js';
+import { getActoviqTodoSnapshot, formatActoviqTodoListLines, TODO_WRITE_TOOL_NAME, } from '../tools/todo/TodoWriteTool.js';
 import { asError, deepClone, nowIso, signalAborted } from './helpers.js';
 import { resolveActoviqPostSamplingHooks, resolveActoviqStopHooks } from '../hooks/actoviqHooks.js';
-import { getActoviqApiContextManagement } from './actoviqApiMicrocompact.js';
+import { compactActoviqConversationIfNeeded } from './actoviqCompact.js';
+import { getActoviqApiContextManagement, prepareActoviqProviderRequestMessages, } from './actoviqApiMicrocompact.js';
 import { decideActoviqToolPermission } from './actoviqPermissions.js';
-import { assistantMessageToParam, buildUserMessage, extractTextFromContent, } from './messageUtils.js';
+import { assistantMessageToParam, buildUserMessage, extractTextFromContent, extractTextFromToolResultContent, } from './messageUtils.js';
+const MAX_CONCURRENT_TOOL_USES = 10;
+const TODO_REMINDER_INTERVAL = 10;
+const MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3;
 export async function executeConversation(options) {
     const startedAt = nowIso();
-    const model = options.model ?? options.config.model;
+    let model = options.model ?? options.config.model;
     const promptText = typeof options.input === 'string' ? options.input : extractTextFromContent(options.input);
     const postSamplingHooks = resolveActoviqPostSamplingHooks(options.hooks);
     const conversation = deepClone(options.messages ?? []);
@@ -32,16 +39,50 @@ export async function executeConversation(options) {
     let toolResults = [];
     let consecutiveFailures = 0;
     let lastFailedTool = '';
+    let maxTokensRecoveryCount = 0;
+    let modelFallbackUsed = false;
+    let iterationsSinceTodoWrite = 0;
+    let streamInterruptionRetryIteration = 0;
+    let streamInterruptionRetries = 0;
     while (true) {
         ensureNotAborted(options.signal);
         iteration += 1;
-        options.emit?.({
-            type: 'request.started',
-            runId: options.runId,
-            iteration,
-            timestamp: nowIso(),
+        // In-loop auto-compact: keep a single long run within the context window
+        // by summarizing old turns before each provider request. Mirrors Claude
+        // Code's per-iteration autocompact and never throws.
+        const loopCompact = await compactActoviqConversationIfNeeded(conversation, {
+            model,
+            modelApi: options.modelApi,
+            compactConfig: options.config.compact,
+            maxTokens: options.maxTokens ?? options.config.maxTokens,
+            runKey: options.runId,
+            signal: options.signal,
         });
-        const request = {
+        if (loopCompact.compacted) {
+            conversation.splice(0, conversation.length, ...loopCompact.messages);
+            options.emit?.({
+                type: 'conversation.compacted',
+                runId: options.runId,
+                iteration,
+                tokenEstimateBefore: loopCompact.tokenEstimateBefore,
+                tokenEstimateAfter: loopCompact.tokenEstimateAfter,
+                messagesSummarized: loopCompact.messagesSummarized,
+                preservedMessages: loopCompact.preservedMessages,
+                clearedToolResults: loopCompact.clearedToolResults,
+                timestamp: nowIso(),
+            });
+        }
+        const useAnthropicContextManagement = isAnthropicAPI(options.config.baseURL);
+        const preparedMessages = prepareActoviqProviderRequestMessages(conversation, options.config.compact, { localToolResultMicrocompact: !useAnthropicContextManagement });
+        let localMicrocompact = preparedMessages.clearedToolResults > 0
+            ? {
+                enabled: true,
+                clearedToolResults: preparedMessages.clearedToolResults,
+                tokenEstimateBefore: preparedMessages.tokenEstimateBefore,
+                tokenEstimateAfter: preparedMessages.tokenEstimateAfter,
+            }
+            : undefined;
+        let request = {
             model,
             max_tokens: options.maxTokens ?? options.config.maxTokens,
             system: options.systemPrompt ?? options.config.systemPrompt,
@@ -53,15 +94,102 @@ export async function executeConversation(options) {
                 : undefined,
             // Skip context_management for third-party providers — their APIs
             // may not support server-side message edits, causing undefined behavior.
-            context_management: isAnthropicAPI(options.config.baseURL)
+            context_management: useAnthropicContextManagement
                 ? getActoviqApiContextManagement(conversation, options.config.compact)
                 : undefined,
-            messages: deepClone(conversation),
+            messages: deepClone(preparedMessages.messages),
             signal: options.signal,
         };
-        const message = options.streaming
-            ? await consumeStream(request, options.modelApi, iteration, options.emit, options.runId)
-            : await options.modelApi.createMessage(request);
+        let requestByteLength = getRequestByteLength(request);
+        const maxRequestBytes = options.config.compact.apiMicrocompactMaxRequestBytes;
+        if (!useAnthropicContextManagement &&
+            maxRequestBytes &&
+            requestByteLength > maxRequestBytes) {
+            const forcedMessages = prepareActoviqProviderRequestMessages(conversation, options.config.compact, { localToolResultMicrocompact: true, force: true });
+            const requestByteLengthBefore = requestByteLength;
+            request = {
+                ...request,
+                messages: deepClone(forcedMessages.messages),
+            };
+            requestByteLength = getRequestByteLength(request);
+            localMicrocompact = {
+                enabled: true,
+                clearedToolResults: forcedMessages.clearedToolResults,
+                tokenEstimateBefore: forcedMessages.tokenEstimateBefore,
+                tokenEstimateAfter: forcedMessages.tokenEstimateAfter,
+                requestByteLengthBefore,
+                requestByteLengthAfter: requestByteLength,
+            };
+        }
+        // Prompt caching: a single cache breakpoint on the last message caches the
+        // entire prefix (tools + system + conversation). Anthropic API hosts only.
+        if (useAnthropicContextManagement && options.config.promptCachingEnabled !== false) {
+            applyCacheControlToLastMessage(request.messages);
+        }
+        options.emit?.({
+            type: 'request.started',
+            runId: options.runId,
+            iteration,
+            requestTokenEstimate: localMicrocompact?.tokenEstimateAfter ?? preparedMessages.tokenEstimateAfter,
+            requestByteLength,
+            localMicrocompact,
+            timestamp: nowIso(),
+        });
+        let message;
+        try {
+            message = options.streaming
+                ? await consumeStream(request, options.modelApi, iteration, options.emit, options.runId)
+                : await options.modelApi.createMessage(request);
+        }
+        catch (error) {
+            // Mid-stream interruptions (socket loss after response headers) never hit
+            // the provider-level retry loop; retry the whole iteration here.
+            if (streamInterruptionRetryIteration !== iteration) {
+                streamInterruptionRetryIteration = iteration;
+                streamInterruptionRetries = 0;
+            }
+            if (isRetryableStreamInterruption(error) &&
+                streamInterruptionRetries < MAX_STREAM_INTERRUPTION_RETRIES) {
+                streamInterruptionRetries += 1;
+                options.emit?.({
+                    type: 'request.interrupted',
+                    runId: options.runId,
+                    iteration,
+                    retry: streamInterruptionRetries,
+                    maxRetries: MAX_STREAM_INTERRUPTION_RETRIES,
+                    reason: asError(error).message,
+                    timestamp: nowIso(),
+                });
+                await sleep(1000 * streamInterruptionRetries);
+                iteration -= 1;
+                continue;
+            }
+            // Fallback model: after transport-level retries are exhausted, switch to
+            // the configured fallback model once and retry this iteration.
+            const fallbackModel = options.config.fallbackModel;
+            if (fallbackModel &&
+                !modelFallbackUsed &&
+                fallbackModel !== model &&
+                isModelFallbackEligibleError(error)) {
+                modelFallbackUsed = true;
+                const fromModel = model;
+                model = fallbackModel;
+                options.emit?.({
+                    type: 'model.fallback',
+                    runId: options.runId,
+                    iteration,
+                    fromModel,
+                    toModel: fallbackModel,
+                    reason: asError(error).message,
+                    timestamp: nowIso(),
+                });
+                iteration -= 1;
+                continue;
+            }
+            throw error;
+        }
+        streamInterruptionRetryIteration = 0;
+        streamInterruptionRetries = 0;
         if (!options.streaming) {
             const text = extractTextFromContent(message.content);
             if (text) {
@@ -171,8 +299,26 @@ export async function executeConversation(options) {
             usage: message.usage,
             text: extractTextFromContent(message.content),
             createdAt: nowIso(),
+            requestTokenEstimate: localMicrocompact?.tokenEstimateAfter ?? preparedMessages.tokenEstimateAfter,
+            requestByteLength,
+            localMicrocompact,
         });
         const toolUses = message.content.filter((block) => block.type === 'tool_use');
+        // max_tokens recovery: when the response was truncated mid-thought with no
+        // tool calls, nudge the model to resume instead of ending the run on a
+        // half-finished answer. Mirrors Claude Code's recovery loop (limit 3).
+        if (!preventContinuation &&
+            toolUses.length === 0 &&
+            message.stop_reason === 'max_tokens' &&
+            maxTokensRecoveryCount < MAX_OUTPUT_TOKENS_RECOVERY_LIMIT) {
+            maxTokensRecoveryCount += 1;
+            conversation.push({
+                role: 'user',
+                content: 'Output token limit hit. Resume directly — no apology, no recap of what you were doing. ' +
+                    'Pick up mid-thought if that is where the cut happened. Break remaining work into smaller pieces.',
+            });
+            continue;
+        }
         if (preventContinuation || toolUses.length === 0) {
             const completedAt = nowIso();
             if (!finalMessage) {
@@ -196,6 +342,17 @@ export async function executeConversation(options) {
             };
         }
         if (iteration >= options.config.maxToolIterations) {
+            if (toolUses.length > 0) {
+                conversation.push({
+                    role: 'user',
+                    content: toolUses.map(toolUse => ({
+                        type: 'tool_result',
+                        tool_use_id: toolUse.id,
+                        is_error: true,
+                        content: `The run exceeded the max tool iteration limit (${options.config.maxToolIterations}) before this tool could execute.`,
+                    })),
+                });
+            }
             const completedAt = nowIso();
             if (finalMessage) {
                 return {
@@ -206,6 +363,8 @@ export async function executeConversation(options) {
                     message: finalMessage,
                     messages: conversation,
                     stopReason: finalMessage.stop_reason ?? null,
+                    incompleteReason: `max_tool_iterations_exceeded:${options.config.maxToolIterations}`,
+                    maxToolIterationsExceeded: true,
                     hookStopReason,
                     usage: finalMessage.usage,
                     requests: requestSummaries,
@@ -217,7 +376,7 @@ export async function executeConversation(options) {
             }
             throw new ActoviqSdkError(`The run exceeded the max tool iteration limit (${options.config.maxToolIterations}).`);
         }
-        for (const toolUse of toolUses) {
+        const runSingleToolUse = async (toolUse) => {
             ensureNotAborted(options.signal);
             const started = nowIso();
             const startedClock = Date.now();
@@ -306,10 +465,22 @@ export async function executeConversation(options) {
                     model,
                     provider: options.config.provider,
                 }, onProgress);
-                outputText = execution.text;
+                // Per-tool declared cap first (default 50k via tool factory), clamped
+                // by the global artifact ceiling. MCP tools without a declared cap use
+                // the global ceiling only.
+                const artifactMaxChars = Math.min(adapter.maxResultSizeChars ?? Number.POSITIVE_INFINITY, options.config.compact.toolResultArtifactMaxChars ?? 80_000);
+                const modelFacingExecution = await artifactToolExecutionIfLarge(execution, {
+                    runId: options.runId,
+                    iteration,
+                    toolUseId: toolUse.id,
+                    toolName: toolUse.name,
+                    workDir: options.config.workDir,
+                    maxChars: artifactMaxChars,
+                });
+                outputText = modelFacingExecution.text;
                 output = execution.rawOutput;
                 isError = execution.isError ?? false;
-                content = execution.content;
+                content = modelFacingExecution.content;
             }
             catch (error) {
                 const normalized = error instanceof ToolExecutionError
@@ -328,20 +499,61 @@ export async function executeConversation(options) {
                 completedAt: nowIso(),
                 durationMs: Date.now() - startedClock,
             };
-            toolCalls.push(record);
-            toolResults.push({
-                type: 'tool_result',
-                tool_use_id: toolUse.id,
-                content,
-                is_error: isError,
-            });
-            options.emit?.({
-                type: 'tool.result',
-                runId: options.runId,
-                iteration,
-                result: record,
-                timestamp: record.completedAt,
-            });
+            return {
+                record,
+                resultBlock: {
+                    type: 'tool_result',
+                    tool_use_id: toolUse.id,
+                    content,
+                    is_error: isError,
+                },
+            };
+        };
+        // Execute tool batches: consecutive concurrency-safe (read-only) tools run
+        // in parallel (limit 10), everything else serially. Results are recorded
+        // in the original tool_use order regardless of completion order.
+        for (const batch of partitionToolUsesForConcurrency(toolUses, toolMap)) {
+            const outcomes = batch.concurrent && batch.toolUses.length > 1
+                ? await runWithConcurrencyLimit(batch.toolUses, MAX_CONCURRENT_TOOL_USES, runSingleToolUse)
+                : await runSequentially(batch.toolUses, runSingleToolUse);
+            for (const outcome of outcomes) {
+                toolCalls.push(outcome.record);
+                toolResults.push(outcome.resultBlock);
+                options.emit?.({
+                    type: 'tool.result',
+                    runId: options.runId,
+                    iteration,
+                    result: outcome.record,
+                    timestamp: outcome.record.completedAt,
+                });
+            }
+        }
+        // Aggregate per-message budget: N parallel tools can each pass the
+        // per-tool cap yet collectively flood one user message. Artifact the
+        // largest results until the batch fits (mirrors Claude Code's 200k cap).
+        await enforceToolResultsAggregateBudget(toolResults, {
+            runId: options.runId,
+            iteration,
+            workDir: options.config.workDir,
+            maxTotalChars: options.config.compact.toolResultsPerMessageMaxChars ?? 200_000,
+            nameByToolUseId: new Map(toolCalls.slice(-toolUses.length).map((record) => [record.id, record.publicName])),
+        });
+        // Todo continuity reminder: when TodoWrite is available but unused for a
+        // stretch of iterations, re-inject the current todo state so long runs
+        // stay anchored to the plan (mirrors Claude Code's 10-turn reminder).
+        if (toolUses.some((toolUse) => toolUse.name === TODO_WRITE_TOOL_NAME)) {
+            iterationsSinceTodoWrite = 0;
+        }
+        else {
+            iterationsSinceTodoWrite += 1;
+            if (toolMap.has(TODO_WRITE_TOOL_NAME) && iterationsSinceTodoWrite >= TODO_REMINDER_INTERVAL) {
+                const reminder = buildTodoReminderText(getActoviqTodoSnapshot(options.sessionId ?? options.runId));
+                const lastResult = toolResults.at(-1);
+                if (lastResult) {
+                    appendTextToToolResultContent(lastResult, reminder);
+                    iterationsSinceTodoWrite = 0;
+                }
+            }
         }
         // Detect repeated tool failures to prevent retry loops
         // Only check newly added results (from this iteration)
@@ -361,6 +573,14 @@ export async function executeConversation(options) {
                 lastFailedTool = '';
             }
         }
+        // Always push tool results before any early return so the conversation
+        // never ends with dangling tool_use blocks (which would make a persisted
+        // session unusable: providers reject unpaired tool_use ids on resume).
+        conversation.push({
+            role: 'user',
+            content: toolResults,
+        });
+        toolResults = [];
         if (consecutiveFailures >= 3 && lastFailedTool) {
             const completedAt = nowIso();
             if (finalMessage) {
@@ -372,6 +592,7 @@ export async function executeConversation(options) {
                     message: finalMessage,
                     messages: conversation,
                     stopReason: finalMessage.stop_reason ?? null,
+                    incompleteReason: `consecutive_tool_failures:${lastFailedTool}`,
                     hookStopReason,
                     usage: finalMessage.usage,
                     requests: requestSummaries,
@@ -383,13 +604,252 @@ export async function executeConversation(options) {
             }
             throw new ActoviqSdkError(`Tool "${lastFailedTool}" failed ${consecutiveFailures} times consecutively. Stopping to prevent retry loop.`);
         }
-        conversation.push({
-            role: 'user',
-            content: toolResults,
+    }
+}
+const ARTIFACTED_OUTPUT_MARKER = 'Tool output was large (';
+async function writeToolResultArtifact(text, options) {
+    const artifactDir = path.join(options.workDir, '.actoviq-artifacts', 'tool-results', sanitizeArtifactSegment(options.runId));
+    await mkdir(artifactDir, { recursive: true });
+    const artifactPath = path.join(artifactDir, `${String(options.iteration).padStart(3, '0')}-${sanitizeArtifactSegment(options.toolUseId)}-${sanitizeArtifactSegment(options.toolName)}.txt`);
+    await writeFile(artifactPath, text, 'utf8');
+    const preview = text.slice(0, Math.max(options.previewChars, 0));
+    const omittedChars = Math.max(text.length - preview.length, 0);
+    return [
+        `${ARTIFACTED_OUTPUT_MARKER}${text.length} characters).`,
+        `Full output saved to: ${artifactPath}`,
+        omittedChars > 0 ? `Preview (${preview.length} characters, ${omittedChars} omitted):` : 'Preview:',
+        preview,
+    ].join('\n');
+}
+async function artifactToolExecutionIfLarge(execution, options) {
+    if (options.maxChars <= 0 || execution.text.length <= options.maxChars) {
+        return {
+            text: execution.text,
+            content: execution.content,
+        };
+    }
+    const summary = await writeToolResultArtifact(execution.text, {
+        runId: options.runId,
+        iteration: options.iteration,
+        toolUseId: options.toolUseId,
+        toolName: options.toolName,
+        workDir: options.workDir,
+        previewChars: Math.min(options.maxChars, 4_000),
+    });
+    return {
+        text: summary,
+        content: summary,
+    };
+}
+/**
+ * Enforce an aggregate character budget over all tool_result blocks produced
+ * in one iteration. The largest non-error, not-yet-artifacted results are
+ * persisted to disk (largest first) until the batch fits the budget.
+ */
+async function enforceToolResultsAggregateBudget(toolResults, options) {
+    if (options.maxTotalChars <= 0 || toolResults.length === 0) {
+        return;
+    }
+    const measured = toolResults.map((block, index) => ({
+        block,
+        index,
+        length: extractTextFromToolResultContent(block.content).length,
+    }));
+    let totalChars = measured.reduce((sum, entry) => sum + entry.length, 0);
+    if (totalChars <= options.maxTotalChars) {
+        return;
+    }
+    const candidates = measured
+        .filter((entry) => {
+        if (entry.block.is_error)
+            return false;
+        const text = extractTextFromToolResultContent(entry.block.content);
+        return !text.startsWith(ARTIFACTED_OUTPUT_MARKER);
+    })
+        .sort((a, b) => b.length - a.length);
+    for (const candidate of candidates) {
+        if (totalChars <= options.maxTotalChars) {
+            break;
+        }
+        const text = extractTextFromToolResultContent(candidate.block.content);
+        if (!text) {
+            continue;
+        }
+        const summary = await writeToolResultArtifact(text, {
+            runId: options.runId,
+            iteration: options.iteration,
+            toolUseId: candidate.block.tool_use_id,
+            toolName: options.nameByToolUseId.get(candidate.block.tool_use_id) ?? 'tool',
+            workDir: options.workDir,
+            previewChars: 2_000,
         });
-        toolResults = [];
+        candidate.block.content = summary;
+        totalChars = totalChars - text.length + summary.length;
     }
 }
+/**
+ * Partition tool calls into batches: consecutive concurrency-safe tools are
+ * grouped for parallel execution, everything else runs as a serial batch of
+ * one. Mirrors Claude Code's read-only batching behavior.
+ */
+function partitionToolUsesForConcurrency(toolUses, toolMap) {
+    const batches = [];
+    for (const toolUse of toolUses) {
+        const adapter = toolMap.get(toolUse.name);
+        let safe = false;
+        if (adapter && adapter.requiresUserInteraction?.() !== true) {
+            try {
+                safe = adapter.isConcurrencySafe?.() ?? adapter.isReadOnly?.(toolUse.input) ?? false;
+            }
+            catch {
+                safe = false;
+            }
+        }
+        const last = batches.at(-1);
+        if (safe && last?.concurrent) {
+            last.toolUses.push(toolUse);
+        }
+        else {
+            batches.push({ concurrent: safe, toolUses: [toolUse] });
+        }
+    }
+    return batches;
+}
+async function runSequentially(items, run) {
+    const results = [];
+    for (const item of items) {
+        results.push(await run(item));
+    }
+    return results;
+}
+async function runWithConcurrencyLimit(items, limit, run) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const workers = Array.from({ length: Math.min(Math.max(limit, 1), items.length) }, async () => {
+        while (true) {
+            const index = nextIndex;
+            nextIndex += 1;
+            if (index >= items.length) {
+                return;
+            }
+            results[index] = await run(items[index]);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+function appendTextToToolResultContent(block, text) {
+    if (block.content === undefined || block.content === null) {
+        block.content = text;
+        return;
+    }
+    if (typeof block.content === 'string') {
+        block.content = `${block.content}\n\n${text}`;
+        return;
+    }
+    if (Array.isArray(block.content)) {
+        block.content.push({ type: 'text', text });
+    }
+}
+function buildTodoReminderText(todos) {
+    if (todos.length === 0) {
+        return [
+            '<system-reminder>',
+            'The TodoWrite tool has not been used recently. If you are working on a multi-step task, use TodoWrite to track progress and keep exactly one item in_progress.',
+            'Do not mention this reminder to the user.',
+            '</system-reminder>',
+        ].join('\n');
+    }
+    return [
+        '<system-reminder>',
+        'Current todo list state (re-injected for continuity):',
+        formatActoviqTodoListLines(todos),
+        'Continue working through pending items, update statuses with TodoWrite as you progress, and do not mention this reminder to the user.',
+        '</system-reminder>',
+    ].join('\n');
+}
+function isModelFallbackEligibleError(error) {
+    if (error instanceof ActoviqProviderApiError) {
+        const status = error.status ?? 0;
+        return status === 429 || status === 529 || (status >= 500 && status < 600);
+    }
+    return false;
+}
+const MAX_STREAM_INTERRUPTION_RETRIES = 3;
+const TRANSPORT_ERROR_CODES = new Set([
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'EPIPE',
+    'ETIMEDOUT',
+    'EAI_AGAIN',
+]);
+const TRANSPORT_ERROR_PATTERN = /terminated|fetch failed|socket|other side closed|premature|network|connection (?:closed|reset|error)/i;
+/**
+ * Transport-level failures that occur after the provider accepted the request
+ * (mid-stream socket loss, abrupt connection close). HTTP-status errors are
+ * excluded — the provider client already retried those before throwing — and
+ * so are non-network errors, which must keep propagating.
+ */
+function isRetryableStreamInterruption(error) {
+    if (error instanceof ActoviqProviderApiError ||
+        error instanceof RunAbortedError ||
+        error instanceof ActoviqSdkError ||
+        error instanceof ToolExecutionError) {
+        return false;
+    }
+    if (!(error instanceof Error) || error.name === 'AbortError') {
+        return false;
+    }
+    const cause = error.cause;
+    const causeCode = typeof cause?.code === 'string' ? cause.code : '';
+    if (causeCode.startsWith('UND_ERR') || TRANSPORT_ERROR_CODES.has(causeCode)) {
+        return true;
+    }
+    const causeMessage = typeof cause?.message === 'string' ? cause.message : '';
+    return TRANSPORT_ERROR_PATTERN.test(`${error.message} ${causeMessage}`);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Mark the last content block of the last message with an ephemeral
+ * cache_control breakpoint. One breakpoint caches the entire request prefix
+ * (tools + system + conversation) on Anthropic API hosts. String-content
+ * messages (e.g. the first user prompt) are converted to an equivalent single
+ * text block so the breakpoint still applies — otherwise the whole request
+ * goes uncached whenever the last message is a plain string.
+ */
+function applyCacheControlToLastMessage(messages) {
+    const last = messages.at(-1);
+    if (!last) {
+        return;
+    }
+    if (typeof last.content === 'string') {
+        if (last.content.length === 0) {
+            return;
+        }
+        last.content = [
+            { type: 'text', text: last.content, cache_control: { type: 'ephemeral' } },
+        ];
+        return;
+    }
+    if (!Array.isArray(last.content) || last.content.length === 0) {
+        return;
+    }
+    const lastBlock = last.content[last.content.length - 1];
+    if (lastBlock && typeof lastBlock === 'object') {
+        lastBlock.cache_control = { type: 'ephemeral' };
+    }
+}
+function sanitizeArtifactSegment(value) {
+    return value.replace(/[^A-Za-z0-9_.-]+/g, '_').slice(0, 80) || 'artifact';
+}
+function getRequestByteLength(request) {
+    return Buffer.byteLength(JSON.stringify({
+        ...request,
+        signal: undefined,
+    }), 'utf8');
+}
 async function consumeStream(request, modelApi, iteration, emit, runId) {
     const stream = modelApi.streamMessage(request);
     let textSnapshot = '';