@kuralle-agents/core 0.8.0 → 0.9.0

package/dist/runtime/Runtime.d.ts

@@ -15,6 +15,9 @@ import type { classifyHostTarget, selectHostTarget } from './select.js';
 import type { KnowledgeProviderConfig } from '../types/voice.js';
 import type { MemoryService as V1MemoryService } from '../memory/MemoryService.js';
 import type { PersistentMemoryStore } from '../memory/blocks/types.js';
+import { type CompactionConfig } from './compaction.js';
+import type { EscalationConfig } from '../escalation/types.js';
+import type { WakeOptions } from '../scheduler/index.js';
 export interface HarnessConfig {
     agents: AgentConfig[];
     defaultAgentId: string;
@@ -38,12 +41,34 @@ export interface HarnessConfig {
      * text-only models. When omitted, audio parts pass through to audio-capable models.
      */
     transcriptionModel?: TranscriptionModel;
+    /**
+     * Automatic history compaction. When set, the runtime summarizes older
+     * messages into one system note after any turn whose history exceeds
+     * `triggerTokens` (off the user's latency path), and force-compacts once as
+     * the retry step after a provider context-overflow error.
+     */
+    compaction?: CompactionConfig;
+    /**
+     * Escalation-to-human pipeline. When set, any escalation — a terminal
+     * handoff (`handoffs: ['human']`, validator `escalate` decision, host
+     * control) or a flow `escalate()` pause — builds an `EscalationRequest`
+     * (state snapshot + recent messages + optional LLM handoff brief) and
+     * invokes the handler. Resume with `runtime.resumeFromEscalation()`.
+     */
+    escalation?: EscalationConfig;
 }
 export interface RunOptions {
     sessionId?: string;
     /** The user turn: plain text, or AI SDK multimodal content (text + file/image/audio parts). */
     input?: UserInputContent;
     selection?: ResolvedSelection;
+    /**
+     * Agent-initiated (proactive) turn — mutually exclusive with `input`. The
+     * runtime appends a wake note instead of a user message and runs the normal
+     * loop: free-conversation agents proactively re-engage; an active flow
+     * re-prompts its current step. Schedule wakes with `createWakeJobRunner`.
+     */
+    wake?: WakeOptions;
     userId?: string;
     agentId?: string;
     seedMessages?: ModelMessage[];
@@ -74,6 +99,34 @@ export declare class Runtime {
         reason?: string;
         markedBy?: ConversationOutcomeMarkedBy;
     }): Promise<void>;
+    /**
+     * 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.
+     */
+    private applyCompaction;
+    /**
+     * 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.
+     */
+    private recoverFromOverflow;
     getConversationLength(sessionId: string): Promise<number>;
+    /**
+     * 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.
+     */
+    private dispatchEscalation;
+    /**
+     * 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.
+     */
+    resumeFromEscalation(sessionId: string, opts?: {
+        resolutionSummary?: string;
+    }): Promise<void>;
 }
 export declare function createRuntime(config: HarnessConfig): Runtime;

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

@@ -2,7 +2,7 @@ import { streamText } from 'ai';
 import { buildNodePrompt, resolveInstructions, composeSystem } from '../../flow/nodeBuilders.js';
 import { buildToolSet } from '../../tools/effect/index.js';
 import { executeModelToolCall, toolResultMessage } from './executeModelTool.js';
-import { consumePendingUserInput } from './inputBuffer.js';
+import { consumeAllPendingUserInput } from './inputBuffer.js';
 import { runSilentExtraction } from './extractionTurn.js';
 import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTurn.js';
 import { resolveMaxSteps } from '../policies/limits.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 });
@@ -161,7 +167,7 @@ export class TextDriver {
         return resolveStructuredDecide(node, ctx, system);
     }
     async awaitUser(ctx) {
-        const input = consumePendingUserInput(ctx.session);
+        const input = consumeAllPendingUserInput(ctx.session) ?? '';
         return { type: 'message', input };
     }
     resolveTools(resolved, ctx) {

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/channels/index.d.ts

@@ -4,4 +4,4 @@ export type { TextDriverConfig } from './TextDriver.js';
 export { VoiceDriver } from './VoiceDriver.js';
 export type { VoiceDriverConfig } from './VoiceDriver.js';
 export { resolveVoiceGeminiTools, v2ToolsToGemini } from './voiceTools.js';
-export { setPendingUserInput, consumePendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './inputBuffer.js';
+export { setPendingUserInput, consumePendingUserInput, consumeAllPendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './inputBuffer.js';

package/dist/runtime/channels/index.js

@@ -5,4 +5,4 @@ export { TextDriver, buildNodePrompt } from './TextDriver.js';
 // the primary primitive; cascaded voice runs over text (see livekit-plugin).
 export { VoiceDriver } from './VoiceDriver.js';
 export { resolveVoiceGeminiTools, v2ToolsToGemini } from './voiceTools.js';
-export { setPendingUserInput, consumePendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './inputBuffer.js';
+export { setPendingUserInput, consumePendingUserInput, consumeAllPendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './inputBuffer.js';

package/dist/runtime/channels/inputBuffer.d.ts

@@ -1,6 +1,9 @@
 import type { Session } from '../../types/session.js';
-import type { UserInputContent } from '../userInput.js';
+import { type UserInputContent } from '../userInput.js';
 export declare function setPendingUserInput(session: Session, input: UserInputContent): void;
+/** Dequeue one pending input. Built-in drivers drain the full queue via {@link consumeAllPendingUserInput}. */
 export declare function consumePendingUserInput(session: Session): UserInputContent;
+/** Drain the pending-input FIFO and merge into one turn (mid-turn enqueue-merge). */
+export declare function consumeAllPendingUserInput(session: Session): UserInputContent | undefined;
 export declare function peekPendingUserInput(session: Session): UserInputContent | undefined;
 export declare function hasPendingUserInput(session: Session): boolean;

package/dist/runtime/channels/inputBuffer.js

@@ -1,3 +1,4 @@
+import { mergeUserInputContents } from '../userInput.js';
 const PENDING_INPUT_KEY = '__v2_pendingUserInput';
 function queue(session) {
     const v = session.workingMemory[PENDING_INPUT_KEY];
@@ -10,6 +11,7 @@ function queue(session) {
 export function setPendingUserInput(session, input) {
     session.workingMemory[PENDING_INPUT_KEY] = [...queue(session), input];
 }
+/** Dequeue one pending input. Built-in drivers drain the full queue via {@link consumeAllPendingUserInput}. */
 export function consumePendingUserInput(session) {
     const q = queue(session);
     const next = q.shift() ?? '';
@@ -19,6 +21,12 @@ export function consumePendingUserInput(session) {
         session.workingMemory[PENDING_INPUT_KEY] = q;
     return next;
 }
+/** Drain the pending-input FIFO and merge into one turn (mid-turn enqueue-merge). */
+export function consumeAllPendingUserInput(session) {
+    const q = queue(session);
+    delete session.workingMemory[PENDING_INPUT_KEY];
+    return mergeUserInputContents(q);
+}
 export function peekPendingUserInput(session) {
     return queue(session)[0];
 }

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/index.d.ts

@@ -3,6 +3,6 @@ export type { RuntimeLike } from './RuntimeLike.js';
 export { SessionWorkingMemory } from './WorkingMemory.js';
 export { TextDriver, VoiceDriver } from './channels/index.js';
 export type { VoiceDriverConfig } from './channels/index.js';
-export { setPendingUserInput, consumePendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './channels/index.js';
-export { userInputToText, hasMediaParts, transcribeAudioParts, type UserInputContent, } from './userInput.js';
+export { setPendingUserInput, consumePendingUserInput, consumeAllPendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './channels/index.js';
+export { userInputToText, mergeUserInputContents, hasMediaParts, transcribeAudioParts, type UserInputContent, } from './userInput.js';
 export { isAbortSignal, type InterruptionEvent, type AbortOptions, type CancellationReason, } from '../types/index.js';

package/dist/runtime/index.js

@@ -4,9 +4,9 @@ export { TextDriver, VoiceDriver } from './channels/index.js';
 // Pending-input buffer helpers — required by custom ChannelDriver authors to
 // implement awaitUser the same FIFO-aware way the built-in drivers do (the
 // buffer is an ordered queue since 0.3.13/H3, not a single slot).
-export { setPendingUserInput, consumePendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './channels/index.js';
+export { setPendingUserInput, consumePendingUserInput, consumeAllPendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './channels/index.js';
 // Multimodal user input — `UserInputContent` is the runtime's accepted user-turn
 // shape (text or AI SDK file/image/audio parts). Helpers project to text and
 // transcribe audio so ingress adapters (web/messaging) can build it uniformly.
-export { userInputToText, hasMediaParts, transcribeAudioParts, } from './userInput.js';
+export { userInputToText, mergeUserInputContents, hasMediaParts, transcribeAudioParts, } from './userInput.js';
 export { isAbortSignal, } from '../types/index.js';