@kuralle-agents/core 0.8.0 → 0.8.5

package/dist/runtime/Runtime.js

@@ -10,7 +10,7 @@ import { hostLoop } from './hostLoop.js';
 import { isDegradableRuntimeError } from '../flow/degradableErrors.js';
 import { SAFE_DEGRADED_MESSAGE } from '../flow/degrade.js';
 import { adaptHostSelect } from './hostClassifyAdapter.js';
-import { openRun } from './openRun.js';
+import { openRun, sessionDerivedRunId } from './openRun.js';
 import { closeRun } from './closeRun.js';
 import { SessionRunStore } from './durable/SessionRunStore.js';
 import { loadRecordedSteps } from './durable/replay.js';
@@ -18,6 +18,9 @@ import { markSessionOutcome } from './outcomeMarking.js';
 import { resolveAgentPolicies } from './policies/resolvePolicies.js';
 import { buildAutoRetrieveProvider, buildKnowledgeProvider, buildMemoryService, runMemoryIngest, } from './grounding/index.js';
 import { SessionMutex } from './SessionMutex.js';
+import { compactMessages } from './compaction.js';
+import { isContextOverflowError, recoverFromContextOverflow } from './contextOverflow.js';
+import { buildEscalationRequest, recordEscalationOutcome, ESCALATION_NOTIFIED_KEY, } from '../escalation/escalation.js';
 export class Runtime {
     config;
     agentsById;
@@ -38,6 +41,9 @@ export class Runtime {
         this.hooks = config.hooks;
     }
     run(opts) {
+        if (opts.wake && opts.input !== undefined) {
+            throw new Error('RunOptions.wake and RunOptions.input are mutually exclusive');
+        }
         const sessionId = opts.sessionId || randomUUID();
         const bus = createEventBus();
         const abortController = new AbortController();
@@ -56,6 +62,7 @@ export class Runtime {
                 userId: opts.userId,
                 input: opts.input,
                 selection: opts.selection,
+                wake: opts.wake,
                 agentId: opts.agentId,
                 seedMessages: opts.seedMessages,
                 historyDelta: opts.historyDelta,
@@ -121,26 +128,41 @@ export class Runtime {
             runCtx.workingMemoryPrompt = openingSurface.workingMemoryPrompt;
             runCtx.workingMemoryTools = openingSurface.workingMemoryTools;
             await this.hooks?.onStart?.(runCtx);
+            if (opts.wake) {
+                emit({ type: 'wake', reason: opts.wake.reason });
+            }
             const driver = opts.driver ?? new TextDriver();
             let activeAgent = opened.agent;
             let loopResult = { kind: 'turnComplete' };
             let handoffCount = 0;
             let terminalOutcome;
+            let overflowRetried = false;
             try {
-                for (;;) {
-                    loopResult = await hostLoop({
-                        agent: activeAgent,
-                        run: runCtx.runState,
-                        driver,
-                        ctx: runCtx,
-                        classify: this.config.hostClassify ??
-                            (this.config.hostSelect ? adaptHostSelect(this.config.hostSelect) : undefined),
-                    });
+                turnLoop: for (;;) {
+                    try {
+                        loopResult = await hostLoop({
+                            agent: activeAgent,
+                            run: runCtx.runState,
+                            driver,
+                            ctx: runCtx,
+                            classify: this.config.hostClassify ??
+                                (this.config.hostSelect ? adaptHostSelect(this.config.hostSelect) : undefined),
+                        });
+                    }
+                    catch (error) {
+                        if (!overflowRetried && this.config.compaction && isContextOverflowError(error)) {
+                            overflowRetried = true;
+                            await this.recoverFromOverflow(runCtx, activeAgent, emit);
+                            continue turnLoop;
+                        }
+                        throw error;
+                    }
                     if (loopResult.kind === 'handoff') {
                         if (this.terminalHandoffTargets.has(loopResult.to)) {
                             emit({ type: 'handoff', targetAgent: loopResult.to, reason: loopResult.reason });
                             runCtx.runState.status = 'paused';
                             await runCtx.runStore.putRunState(runCtx.runState);
+                            await this.dispatchEscalation(runCtx, activeAgent, { reason: loopResult.reason ?? 'handoff_to_human', category: loopResult.category }, emit, { setLatch: false });
                             break;
                         }
                         handoffCount += 1;
@@ -183,10 +205,20 @@ export class Runtime {
                         break;
                     }
                     if (loopResult.kind === 'paused') {
+                        if (runCtx.runState.waitingFor?.signalName === '__escalate') {
+                            // Flow escalate() parks on the durable signal — notify the human
+                            // side now; the latch keeps the post-resume terminal handoff from
+                            // notifying a second time.
+                            const meta = runCtx.runState.waitingFor.meta;
+                            await this.dispatchEscalation(runCtx, activeAgent, { reason: String(meta?.reason ?? 'flow_escalation') }, emit, { setLatch: true });
+                        }
                         break;
                     }
                     break;
                 }
+                // Post-turn maintenance: text already streamed, so the summarizer call
+                // is off the user's latency path; the NEXT turn starts compact.
+                await this.applyCompaction(runCtx, activeAgent, emit, false);
             }
             catch (error) {
                 await this.hooks?.onError?.(runCtx, error);
@@ -276,11 +308,153 @@ export class Runtime {
             markedBy: opts?.markedBy ?? 'http',
         });
     }
+    /**
+     * Compact `runState.messages` when over the configured trigger (or always,
+     * when `force`). Persists both the run state and the session message mirror.
+     * Returns whether compaction applied.
+     */
+    async applyCompaction(runCtx, agent, emit, force) {
+        const config = this.config.compaction;
+        if (!config) {
+            return false;
+        }
+        const model = config.model ?? agent.controlModel ?? agent.model ?? this.defaultModel;
+        if (!model) {
+            return false;
+        }
+        const result = await compactMessages({
+            messages: runCtx.runState.messages,
+            model,
+            config,
+            force,
+        });
+        if (!result.compacted) {
+            if (force) {
+                emit({ type: 'compaction-skipped', reason: result.reason });
+            }
+            return false;
+        }
+        runCtx.runState.messages = result.messages;
+        runCtx.runState.updatedAt = Date.now();
+        await runCtx.runStore.putRunState(runCtx.runState);
+        const latest = await this.sessionStore.get(runCtx.session.id);
+        if (latest) {
+            latest.messages = [...result.messages];
+            await this.sessionStore.save(latest);
+        }
+        runCtx.session.messages = [...result.messages];
+        emit({
+            type: 'context-compacted',
+            beforeTokens: result.beforeTokens,
+            afterTokens: result.afterTokens,
+            summarizedCount: result.summarizedCount,
+        });
+        return true;
+    }
+    /**
+     * Context-overflow recovery: strip the failed turn's partial assistant/tool
+     * messages (the user's own message is preserved), force one compaction, and
+     * let the caller retry the turn once.
+     */
+    async recoverFromOverflow(runCtx, agent, emit) {
+        runCtx.session.messages = runCtx.runState.messages;
+        const recovery = await recoverFromContextOverflow(runCtx.session);
+        runCtx.runState.messages = runCtx.session.messages;
+        const compacted = await this.applyCompaction(runCtx, agent, emit, true);
+        emit({
+            type: 'context-overflow-recovered',
+            strippedCount: recovery.strippedCount,
+            compacted,
+        });
+    }
     async getConversationLength(sessionId) {
         const runStore = new SessionRunStore(this.sessionStore, sessionId);
         const runState = await runStore.getRunState(sessionId);
         return runState?.messages.length ?? 0;
     }
+    /**
+     * Build the escalation request, invoke the configured handler, record the
+     * outcome on session metadata, and emit the `escalation` stream part.
+     * No-op without `config.escalation`. Handler errors become a `failed`
+     * outcome — escalation must never take down the turn.
+     */
+    async dispatchEscalation(runCtx, agent, info, emit, opts) {
+        const config = this.config.escalation;
+        if (!config) {
+            return;
+        }
+        if (!opts.setLatch && runCtx.runState.state[ESCALATION_NOTIFIED_KEY]) {
+            // The handler already fired when the flow parked on `__escalate`;
+            // consume the latch instead of notifying twice.
+            delete runCtx.runState.state[ESCALATION_NOTIFIED_KEY];
+            await runCtx.runStore.putRunState(runCtx.runState);
+            return;
+        }
+        const model = config.model ?? agent.controlModel ?? agent.model ?? this.defaultModel;
+        const request = await buildEscalationRequest({
+            session: runCtx.session,
+            runState: runCtx.runState,
+            reason: info.reason,
+            category: info.category,
+            config,
+            model,
+        });
+        let outcome;
+        try {
+            outcome = await config.handler(request);
+        }
+        catch (error) {
+            outcome = {
+                status: 'failed',
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+        recordEscalationOutcome(runCtx.session, info.category ?? 'user-request', outcome);
+        if (opts.setLatch) {
+            runCtx.runState.state[ESCALATION_NOTIFIED_KEY] = true;
+        }
+        await runCtx.runStore.putRunState(runCtx.runState);
+        await this.sessionStore.save(runCtx.session);
+        emit({
+            type: 'escalation',
+            reason: info.reason,
+            category: info.category,
+            outcome: outcome.status,
+            summary: request.summary,
+        });
+    }
+    /**
+     * Hand the conversation back to the bot after a human resolved an
+     * escalation: appends a resolution note the model will see, clears any
+     * parked flow/escalation state, and marks the run runnable again. The next
+     * `run()` continues the conversation with full context.
+     */
+    async resumeFromEscalation(sessionId, opts) {
+        const session = await this.sessionStore.get(sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        const runStore = new SessionRunStore(this.sessionStore, sessionId);
+        const runState = await runStore.getRunState(sessionDerivedRunId(sessionId));
+        if (!runState) {
+            throw new Error(`No run state for session: ${sessionId}`);
+        }
+        const note = {
+            role: 'system',
+            content: `[A human agent handled this conversation${opts?.resolutionSummary ? `. Resolution: ${opts.resolutionSummary}` : ''}. The assistant is now resuming.]`,
+        };
+        runState.messages = [...runState.messages, note];
+        runState.status = 'running';
+        runState.waitingFor = undefined;
+        runState.activeFlow = undefined;
+        runState.activeNode = undefined;
+        delete runState.state[ESCALATION_NOTIFIED_KEY];
+        runState.updatedAt = Date.now();
+        await runStore.putRunState(runState);
+        const latest = (await this.sessionStore.get(sessionId)) ?? session;
+        latest.messages = [...runState.messages];
+        await this.sessionStore.save(latest);
+    }
 }
 export function createRuntime(config) {
     return new Runtime(config);

package/dist/runtime/channels/TextDriver.js

@@ -28,6 +28,12 @@ export class TextDriver {
         const preTurn = await applyPreTurnPolicies(ctx);
         if (!preTurn.proceed) {
             const blocked = preTurn.blockedMessage ?? 'Input blocked by guardrails';
+            ctx.emit({
+                type: 'safety-blocked',
+                moderator: preTurn.blockedBy ?? 'input-guardrails',
+                rationale: preTurn.blockedReason ?? 'input blocked',
+                userFacingMessage: blocked,
+            });
             const id = crypto.randomUUID();
             ctx.emit({ type: 'text-start', id });
             ctx.emit({ type: 'text-delta', id, delta: blocked });

package/dist/runtime/channels/VoiceDriver.js

@@ -53,6 +53,12 @@ export class VoiceDriver {
         const preTurn = await applyPreTurnPolicies(ctx);
         if (!preTurn.proceed) {
             const blocked = preTurn.blockedMessage ?? 'Input blocked by guardrails';
+            ctx.emit({
+                type: 'safety-blocked',
+                moderator: preTurn.blockedBy ?? 'input-guardrails',
+                rationale: preTurn.blockedReason ?? 'input blocked',
+                userFacingMessage: blocked,
+            });
             const id = crypto.randomUUID();
             ctx.emit({ type: 'text-start', id });
             ctx.emit({ type: 'text-delta', id, delta: blocked });

package/dist/runtime/closeRun.js

@@ -22,5 +22,9 @@ export async function closeRun(options) {
     const latest = (await sessionStore.get(session.id)) ?? session;
     latest.currentAgent = runState.activeAgentId;
     latest.activeAgentId = runState.activeAgentId;
+    // Sync the session-level message mirror to the canonical run record — it
+    // otherwise lacks assistant turns and keeps pre-guardrail (unredacted)
+    // user input written at openRun.
+    latest.messages = [...runState.messages];
     await sessionStore.save(latest);
 }

package/dist/runtime/compaction.d.ts

@@ -0,0 +1,51 @@
+import { type LanguageModel, type ModelMessage } from 'ai';
+/**
+ * Automatic conversation-history compaction.
+ *
+ * Long-running sessions (weeks-long WhatsApp threads) grow unbounded; budget
+ * truncation silently loses the early relationship. Compaction summarizes the
+ * older history into one system note and keeps the recent tail verbatim, so
+ * the model retains facts/decisions without paying the full token cost.
+ *
+ * Runs post-turn (off the user's latency path) when the estimated history
+ * tokens exceed `triggerTokens`, and force-runs as the recovery step after a
+ * provider context-overflow error (see `contextOverflow.ts`).
+ */
+export interface CompactionConfig {
+    /** Summarizer model. Defaults to the active agent's controlModel/model. */
+    model?: LanguageModel;
+    /** Estimated history tokens that trigger compaction. Default: 8000. */
+    triggerTokens?: number;
+    /** Number of recent messages kept verbatim. Default: 12. */
+    keepRecentMessages?: number;
+    /** Override the summarizer system prompt. */
+    summaryPrompt?: string;
+}
+export declare const DEFAULT_COMPACTION_TRIGGER_TOKENS = 8000;
+export declare const DEFAULT_COMPACTION_KEEP_RECENT = 12;
+export type CompactionResult = {
+    compacted: true;
+    messages: ModelMessage[];
+    beforeTokens: number;
+    afterTokens: number;
+    summarizedCount: number;
+} | {
+    compacted: false;
+    reason: 'under-threshold' | 'too-few-messages' | 'summarizer-error';
+    beforeTokens: number;
+};
+export declare function estimateMessagesTokens(messages: ModelMessage[]): number;
+export interface CompactMessagesOptions {
+    messages: ModelMessage[];
+    model: LanguageModel;
+    config: CompactionConfig;
+    /** Skip the threshold check (overflow recovery). */
+    force?: boolean;
+    abortSignal?: AbortSignal;
+}
+/**
+ * Pure compaction step: returns a new message list when compaction applied.
+ * The kept tail always starts at a `user` message so assistant/tool-call
+ * pairs are never split across the summary boundary.
+ */
+export declare function compactMessages(options: CompactMessagesOptions): Promise<CompactionResult>;

package/dist/runtime/compaction.js

@@ -0,0 +1,111 @@
+import { generateText } from 'ai';
+import { estimateTokenCount } from './ContextBudget.js';
+export const DEFAULT_COMPACTION_TRIGGER_TOKENS = 8_000;
+export const DEFAULT_COMPACTION_KEEP_RECENT = 12;
+const DEFAULT_SUMMARY_PROMPT = [
+    'Summarize this conversation so an assistant can continue it seamlessly.',
+    'Preserve, with exact values: user identity details shared (name, address, contact),',
+    'stable preferences, decisions made, actions COMPLETED (orders, bookings, tool actions',
+    'with their result ids/amounts), and open questions or pending steps.',
+    'Do not invent anything. Maximum 250 words.',
+].join(' ');
+export function estimateMessagesTokens(messages) {
+    let total = 0;
+    for (const message of messages) {
+        total += estimateTokenCount(typeof message.content === 'string' ? message.content : safeStringify(message.content));
+    }
+    return total;
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? '';
+    }
+    catch {
+        return String(value);
+    }
+}
+/** Text projection of messages for the summarizer (tool calls become bracketed notes). */
+function renderTranscript(messages) {
+    const lines = [];
+    for (const message of messages) {
+        if (typeof message.content === 'string') {
+            lines.push(`${message.role}: ${message.content}`);
+            continue;
+        }
+        if (!Array.isArray(message.content))
+            continue;
+        const parts = [];
+        for (const part of message.content) {
+            if (part.type === 'text' && typeof part.text === 'string') {
+                parts.push(part.text);
+            }
+            else if (part.type === 'tool-call') {
+                parts.push(`[called ${String(part.toolName)} with ${truncate(safeStringify(part.input ?? part.args), 200)}]`);
+            }
+            else if (part.type === 'tool-result') {
+                parts.push(`[${String(part.toolName)} returned ${truncate(safeStringify(part.output ?? part.result), 200)}]`);
+            }
+            else if (part.type === 'file' || part.type === 'image') {
+                parts.push(`[${String(part.type)} attachment]`);
+            }
+        }
+        if (parts.length > 0) {
+            lines.push(`${message.role}: ${parts.join(' ')}`);
+        }
+    }
+    return lines.join('\n');
+}
+function truncate(text, max) {
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+/**
+ * Pure compaction step: returns a new message list when compaction applied.
+ * The kept tail always starts at a `user` message so assistant/tool-call
+ * pairs are never split across the summary boundary.
+ */
+export async function compactMessages(options) {
+    const { messages, model, config, force, abortSignal } = options;
+    const triggerTokens = config.triggerTokens ?? DEFAULT_COMPACTION_TRIGGER_TOKENS;
+    const keepRecent = config.keepRecentMessages ?? DEFAULT_COMPACTION_KEEP_RECENT;
+    const beforeTokens = estimateMessagesTokens(messages);
+    if (!force && beforeTokens < triggerTokens) {
+        return { compacted: false, reason: 'under-threshold', beforeTokens };
+    }
+    let cut = Math.max(messages.length - keepRecent, 0);
+    while (cut > 0 && messages[cut]?.role !== 'user') {
+        cut -= 1;
+    }
+    if (cut < 2) {
+        return { compacted: false, reason: 'too-few-messages', beforeTokens };
+    }
+    const older = messages.slice(0, cut);
+    const transcript = renderTranscript(older);
+    let summary;
+    try {
+        const result = await generateText({
+            model,
+            system: config.summaryPrompt ?? DEFAULT_SUMMARY_PROMPT,
+            prompt: transcript,
+            abortSignal,
+        });
+        summary = result.text.trim();
+        if (!summary) {
+            return { compacted: false, reason: 'summarizer-error', beforeTokens };
+        }
+    }
+    catch {
+        return { compacted: false, reason: 'summarizer-error', beforeTokens };
+    }
+    const summaryMessage = {
+        role: 'system',
+        content: `[Conversation summary — earlier turns were compacted]\n${summary}`,
+    };
+    const compacted = [summaryMessage, ...messages.slice(cut)];
+    return {
+        compacted: true,
+        messages: compacted,
+        beforeTokens,
+        afterTokens: estimateMessagesTokens(compacted),
+        summarizedCount: older.length,
+    };
+}

package/dist/runtime/hostLoop.d.ts

@@ -1,3 +1,4 @@
+import type { EscalationReason } from '../escalation/types.js';
 import type { AgentConfig } from '../types/agentConfig.js';
 import type { ChannelDriver } from '../types/channel.js';
 import type { RunContext } from '../types/run-context.js';
@@ -8,6 +9,7 @@ export type HostLoopResult = {
     kind: 'handoff';
     to: string;
     reason?: string;
+    category?: EscalationReason;
 } | {
     kind: 'ended';
     reason: string;

package/dist/runtime/hostLoop.js

@@ -183,7 +183,7 @@ async function executeHostControl(agent, run, driver, ctx, control) {
     }
     if (control.type === 'escalate') {
         ctx.emit({ type: 'handoff', targetAgent: 'human', reason: control.reason });
-        return { kind: 'handoff', to: 'human', reason: control.reason };
+        return { kind: 'handoff', to: 'human', reason: control.reason, category: control.category };
     }
     if (control.type === 'recover') {
         return { kind: 'ended', reason: control.reason ?? 'error_degraded' };

package/dist/runtime/openRun.d.ts

@@ -12,6 +12,11 @@ export interface OpenRunOptions {
     userId?: string;
     input?: UserInputContent;
     selection?: ResolvedSelection;
+    /** Agent-initiated turn: no user input; a wake note is appended instead. */
+    wake?: {
+        reason: string;
+        payload?: Record<string, unknown>;
+    };
     agentId?: string;
     seedMessages?: ModelMessage[];
     historyDelta?: ModelMessage[];

package/dist/runtime/openRun.js

@@ -71,6 +71,23 @@ export async function openRun(agentsById, options) {
             await options.sessionStore.save(sessionAfterPersist);
         }
     }
+    if (options.wake && !hasInput) {
+        const payloadNote = options.wake.payload
+            ? ` Context: ${JSON.stringify(options.wake.payload)}.`
+            : '';
+        const wakeMessage = {
+            role: 'system',
+            content: `[Scheduled wake: ${options.wake.reason}]${payloadNote} ` +
+                'There is no new user message. Re-engage the user proactively per your instructions; ' +
+                'if a task is in progress, follow up on it gently.',
+        };
+        runState.messages = [...runState.messages, wakeMessage];
+        runState.updatedAt = Date.now();
+        await runStore.putRunState(runState);
+        const sessionAfterPersist = (await options.sessionStore.get(options.sessionId)) ?? session;
+        sessionAfterPersist.messages = [...sessionAfterPersist.messages, wakeMessage];
+        await options.sessionStore.save(sessionAfterPersist);
+    }
     const agent = agentsById.get(runState.activeAgentId);
     if (!agent) {
         throw new Error(`Unknown activeAgentId "${runState.activeAgentId}"`);

package/dist/runtime/policies/agentTurn.d.ts

@@ -6,6 +6,10 @@ export interface PreTurnResult {
     proceed: boolean;
     userMessage: string;
     blockedMessage?: string;
+    /** Id of the processor/policy that blocked (set when `proceed` is false). */
+    blockedBy?: string;
+    /** Machine-readable block reason (set when `proceed` is false). */
+    blockedReason?: string;
 }
 export interface PostTurnResult {
     proceed: boolean;

package/dist/runtime/policies/agentTurn.js

@@ -1,11 +1,24 @@
 import { appendConversationAudit } from '../../audit/record.js';
 import { SAFE_DEGRADED_MESSAGE } from '../../flow/degrade.js';
 import { runInputProcessors, runOutputProcessors } from '../../processors/ProcessorRunner.js';
+function userTextProjection(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .filter((part) => part.type === 'text' && typeof part.text === 'string')
+        .map((part) => part.text)
+        .join('\n');
+}
+// Guards must see multimodal turns too: a WhatsApp image whose CAPTION carries
+// a card number is still PII; an injection attempt in a caption is still an
+// injection. Project the text parts — file/image parts pass through untouched.
 function latestUserMessage(messages) {
     for (let index = messages.length - 1; index >= 0; index -= 1) {
         const message = messages[index];
-        if (message?.role === 'user' && typeof message.content === 'string') {
-            return message.content;
+        if (message?.role === 'user') {
+            return userTextProjection(message.content);
         }
     }
     return '';
@@ -91,6 +104,8 @@ async function runRefinementPolicies(ctx, userMessage) {
                 proceed: false,
                 userMessage: current,
                 blockedMessage: decision.userFacingMessage ?? decision.rationale ?? 'Input blocked',
+                blockedBy: policy.name,
+                blockedReason: decision.rationale,
             };
         }
         if (decision.decision === 'rewrite') {
@@ -138,7 +153,7 @@ async function runValidationPolicies(ctx, userMessage, assistantOutput, toolCall
                 proceed: false,
                 text: safe,
                 blockedMessage: safe,
-                control: { type: 'escalate', reason: decision.rationale },
+                control: { type: 'escalate', reason: decision.rationale, category: decision.escalationReason },
                 confidence: decision.confidence,
             };
         }
@@ -170,10 +185,16 @@ export async function applyPreTurnPolicies(ctx) {
                 proceed: false,
                 userMessage,
                 blockedMessage: outcome.message,
+                blockedBy: outcome.processorId,
+                blockedReason: outcome.reason,
             };
         }
         if (outcome.input !== userMessage) {
             patchLatestUserMessage(ctx.runState.messages, outcome.input);
+            patchLatestUserMessage(ctx.session.messages, outcome.input);
+            // Persist immediately: a redaction (e.g. PII) must replace the raw
+            // value in the durable record, not only in this turn's memory.
+            await ctx.runStore.putRunState(ctx.runState);
         }
     }
     return runRefinementPolicies(ctx, latestUserMessage(ctx.runState.messages));
@@ -210,7 +231,17 @@ function patchLatestUserMessage(messages, next) {
     for (let index = messages.length - 1; index >= 0; index -= 1) {
         const message = messages[index];
         if (message?.role === 'user') {
-            messages[index] = { role: 'user', content: next };
+            if (Array.isArray(message.content)) {
+                // Multimodal turn: rewrite the text while preserving file/image parts.
+                const mediaParts = message.content.filter((part) => part.type !== 'text');
+                messages[index] = {
+                    role: 'user',
+                    content: [{ type: 'text', text: next }, ...mediaParts],
+                };
+            }
+            else {
+                messages[index] = { role: 'user', content: next };
+            }
             return;
         }
     }