@kuralle-agents/core 0.12.0 → 0.14.0

package/dist/runtime/Runtime.js

@@ -7,10 +7,16 @@ import { createEventBus, createTurnHandle } from '../events/TurnHandle.js';
 import { CoreToolExecutor } from '../tools/effect/index.js';
 import { buildAgentToolSurface } from './buildAgentToolSurface.js';
 import { hostLoop } from './hostLoop.js';
+import { isHandoffOscillating } from './handoffOscillation.js';
+import { applyHandoffContinuation } from './handoffContinuation.js';
 import { isDegradableRuntimeError } from '../flow/degradableErrors.js';
 import { SAFE_DEGRADED_MESSAGE } from '../flow/degrade.js';
 import { adaptHostSelect } from './hostClassifyAdapter.js';
 import { openRun, sessionDerivedRunId } from './openRun.js';
+function resolveOutOfBandControl(agent) {
+    const hasFlows = (agent.flows?.length ?? 0) > 0;
+    return agent.experimental?.outOfBandControl ?? hasFlows;
+}
 import { closeRun } from './closeRun.js';
 import { SessionRunStore } from './durable/SessionRunStore.js';
 import { loadRecordedSteps } from './durable/replay.js';
@@ -19,8 +25,16 @@ 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 { readLastPromptTokens, readCumulativeUsage, computeTurnTraceUsage } from './turnTokenUsage.js';
 import { isContextOverflowError, recoverFromContextOverflow } from './contextOverflow.js';
+import { projectGoalsPromptFromState, updateGoalsFromTurn } from './goals.js';
 import { buildEscalationRequest, recordEscalationOutcome, ESCALATION_NOTIFIED_KEY, } from '../escalation/escalation.js';
+import { runOnce as recordRunOnce } from './TraceRecorder.js';
+import { TraceRecorder } from './TraceRecorder.js';
+import { MemoryTraceStore } from '../tracing/MemoryTraceStore.js';
+import { mutateSessionWithRetry } from '../session/utils.js';
+import { isTraceStore } from '../tracing/TraceStore.js';
+import { runHookSafely } from './runHookSafely.js';
 export class Runtime {
     config;
     agentsById;
@@ -31,6 +45,9 @@ export class Runtime {
     hooks;
     activeTurnAborts = new Map();
     sessionMutex = new SessionMutex();
+    traceStore;
+    traceSinks;
+    pendingTraceWrites = new Set();
     constructor(config) {
         this.config = config;
         this.agentsById = indexAgents(config.agents);
@@ -39,12 +56,28 @@ export class Runtime {
         this.maxHandoffs = config.maxHandoffs ?? 5;
         this.terminalHandoffTargets = new Set(config.terminalHandoffTargets ?? ['human']);
         this.hooks = config.hooks;
+        const configuredSinks = config.tracing?.sinks ?? [];
+        const configuredStore = config.tracing?.store ?? configuredSinks.find(isTraceStore);
+        this.traceStore = config.tracing?.enabled === false
+            ? undefined
+            : configuredStore ?? new MemoryTraceStore();
+        this.traceSinks = this.traceStore
+            ? [this.traceStore, ...configuredSinks.filter((sink) => sink !== this.traceStore)]
+            : [];
     }
     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 recorder = this.shouldTrace(sessionId, opts.input)
+            ? new TraceRecorder({
+                sessionId,
+                agentId: opts.agentId ?? this.config.defaultAgentId,
+                input: opts.input,
+                onSpan: (span) => this.writeSpan(span),
+            })
+            : undefined;
         const bus = createEventBus();
         const abortController = new AbortController();
         this.activeTurnAborts.set(sessionId, abortController);
@@ -54,8 +87,11 @@ export class Runtime {
         const execute = async () => {
             let runCtx;
             const emit = (part) => {
+                recorder?.record(part);
+                if (part.type === 'done')
+                    this.flushTraceSinks();
                 bus.emit(part);
-                void this.hooks?.onStreamPart?.(runCtx, part);
+                void runHookSafely('onStreamPart', () => this.hooks?.onStreamPart?.(runCtx, part));
             };
             const opened = await openRun(this.agentsById, {
                 sessionId,
@@ -67,10 +103,12 @@ export class Runtime {
                 seedMessages: opts.seedMessages,
                 historyDelta: opts.historyDelta,
                 signalDelivery: opts.signalDelivery,
+                idempotencyKey: opts.idempotencyKey,
                 transcriptionModel: this.config.transcriptionModel,
                 defaultAgentId: this.config.defaultAgentId,
                 sessionStore: this.sessionStore,
             });
+            recorder?.setInitiatingAgent(opened.agent.id);
             const policies = resolveAgentPolicies(opened.agent);
             const knowledgeProvider = this.config.knowledge
                 ? buildKnowledgeProvider(this.config.knowledge)
@@ -86,13 +124,24 @@ export class Runtime {
                 agentId: opened.agent.id,
                 onInterim: (message) => {
                     const id = crypto.randomUUID();
-                    emit({ type: 'text-start', id });
-                    emit({ type: 'text-delta', id, delta: message });
-                    emit({ type: 'text-end', id });
+                    emit({ channel: 'client', type: 'text-start', payload: { id } });
+                    emit({ channel: 'client', type: 'text-delta', payload: { id, delta: message } });
+                    emit({ channel: 'client', type: 'text-end', payload: { id } });
+                },
+                onChunk: (chunk, toolName, toolCallId) => {
+                    emit({
+                        channel: 'internal',
+                        type: 'tool-result',
+                        payload: { toolName, result: chunk, toolCallId, preliminary: true },
+                    });
                 },
             });
             const steps = await loadRecordedSteps(opened.runStore, opened.runState.runId);
             const freshRunState = (await opened.runStore.getRunState(opened.runState.runId)) ?? opened.runState;
+            // Snapshot cumulative token usage as this turn opens, so the trace can report
+            // THIS turn's consumption (delta), not the running session total (see the
+            // per-turn scope requirement in the observability guide).
+            const usageBaseline = readCumulativeUsage(freshRunState.state);
             const model = opened.agent.model ?? this.defaultModel;
             if (!model) {
                 throw new Error('Runtime requires agent.model or config.defaultModel');
@@ -120,16 +169,20 @@ export class Runtime {
                     : undefined,
                 fs: openingSurface.resolvedWorkspace?.fs,
             });
+            // Session retrieval cache (G6): created once per run, persists across
+            // in-session handoffs (runCtx survives the handoff branch). RAG-only —
+            // a knowledge-less runtime leaves it undefined.
+            runCtx.retrievalCache = knowledgeProvider?.createSessionCache();
             // Agent base layer (ADR 0001): composed into every node turn by the drivers.
             runCtx.baseInstructions = opened.agent.instructions;
             runCtx.globalTools = openingSurface.globalTools;
-            runCtx.outOfBandControl = opened.agent.experimental?.outOfBandControl ?? false;
+            runCtx.outOfBandControl = resolveOutOfBandControl(opened.agent);
             runCtx.skillPrompt = openingSurface.skillPrompt;
-            runCtx.workingMemoryPrompt = openingSurface.workingMemoryPrompt;
+            runCtx.workingMemoryPrompt = appendGoalsPrompt(openingSurface.workingMemoryPrompt, opened.session.workingMemory);
             runCtx.workingMemoryTools = openingSurface.workingMemoryTools;
-            await this.hooks?.onStart?.(runCtx);
+            await runHookSafely('onStart', () => this.hooks?.onStart?.(runCtx));
             if (opts.wake) {
-                emit({ type: 'wake', reason: opts.wake.reason });
+                emit({ channel: 'internal', type: 'wake', payload: { reason: opts.wake.reason } });
             }
             const driver = opts.driver ?? new TextDriver();
             let activeAgent = opened.agent;
@@ -159,7 +212,11 @@ export class Runtime {
                     }
                     if (loopResult.kind === 'handoff') {
                         if (this.terminalHandoffTargets.has(loopResult.to)) {
-                            emit({ type: 'handoff', targetAgent: loopResult.to, reason: loopResult.reason });
+                            emit({
+                                channel: 'internal',
+                                type: 'handoff',
+                                payload: { 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 });
@@ -169,6 +226,14 @@ export class Runtime {
                         if (handoffCount > this.maxHandoffs) {
                             throw new Error(`maxHandoffs exceeded (${this.maxHandoffs})`);
                         }
+                        // Cross-turn ping-pong safeguard (handoffCount resets each turn, so it
+                        // can't catch A↔B oscillation spread across turns). This is a bound
+                        // ABOVE maxHandoffs: within-run runaway is caught by the maxHandoffs
+                        // check above; oscillation only fires for same-pair accumulation in the
+                        // persisted handoffHistory beyond that, so it never pre-empts maxHandoffs.
+                        if (isHandoffOscillating(opened.session.handoffHistory, runCtx.runState.activeAgentId, loopResult.to, this.maxHandoffs + 1)) {
+                            throw new Error(`Handoff oscillation detected between "${runCtx.runState.activeAgentId}" and "${loopResult.to}"`);
+                        }
                         const target = this.agentsById.get(loopResult.to);
                         if (!target) {
                             throw new Error(`Handoff target agent not found: ${loopResult.to}`);
@@ -179,6 +244,20 @@ export class Runtime {
                             reason: loopResult.reason ?? 'handoff',
                             timestamp: new Date(),
                         });
+                        const handoffTarget = loopResult.to;
+                        const routeFilter = activeAgent.routes?.find((r) => r.agent === handoffTarget)?.filter;
+                        const inputFilter = routeFilter ?? this.config.handoffInputFilter;
+                        if (inputFilter) {
+                            const filtered = await inputFilter({
+                                messages: runCtx.runState.messages,
+                                workingMemory: runCtx.session.workingMemory,
+                                sourceAgentId: runCtx.runState.activeAgentId,
+                                targetAgentId: handoffTarget,
+                                reason: loopResult.reason,
+                            });
+                            runCtx.runState.messages = filtered.messages;
+                            runCtx.session.workingMemory = filtered.workingMemory;
+                        }
                         runCtx.runState.activeAgentId = loopResult.to;
                         activeAgent = target;
                         const targetSurface = await buildAgentToolSurface(target, opened.session, {
@@ -191,12 +270,51 @@ export class Runtime {
                             : undefined;
                         runCtx.globalTools = targetSurface.globalTools;
                         runCtx.skillPrompt = targetSurface.skillPrompt;
-                        runCtx.workingMemoryPrompt = targetSurface.workingMemoryPrompt;
+                        runCtx.workingMemoryPrompt = appendGoalsPrompt(targetSurface.workingMemoryPrompt, runCtx.session.workingMemory);
                         runCtx.workingMemoryTools = targetSurface.workingMemoryTools;
                         runCtx.fs = targetSurface.resolvedWorkspace?.fs;
                         runCtx.memoryService = this.config.memoryService
                             ? buildMemoryService(this.config.memoryService, target)
                             : undefined;
+                        const targetPolicies = resolveAgentPolicies(target);
+                        const targetModel = target.model ?? this.defaultModel;
+                        if (!targetModel) {
+                            throw new Error('Runtime requires agent.model or config.defaultModel');
+                        }
+                        runCtx.baseInstructions =
+                            (this.config.silentHandoff ?? true)
+                                ? applyHandoffContinuation(target.instructions)
+                                : target.instructions;
+                        runCtx.model = targetModel;
+                        runCtx.controlModel = target.controlModel ?? targetModel;
+                        runCtx.outOfBandControl = resolveOutOfBandControl(target);
+                        runCtx.limits = targetPolicies.limits;
+                        runCtx.refinementPolicies = targetPolicies.refinementPolicies;
+                        runCtx.validationPolicies = targetPolicies.validationPolicies;
+                        runCtx.inputProcessors = targetPolicies.inputProcessors;
+                        runCtx.outputProcessors = targetPolicies.outputProcessors;
+                        runCtx.toolExecutor = new CoreToolExecutor({
+                            tools: targetSurface.executorTools,
+                            enforcer: targetPolicies.enforcer,
+                            agentId: target.id,
+                            onInterim: (message) => {
+                                const id = crypto.randomUUID();
+                                emit({ channel: 'client', type: 'text-start', payload: { id } });
+                                emit({
+                                    channel: 'client',
+                                    type: 'text-delta',
+                                    payload: { id, delta: message },
+                                });
+                                emit({ channel: 'client', type: 'text-end', payload: { id } });
+                            },
+                            onChunk: (chunk, toolName, toolCallId) => {
+                                emit({
+                                    channel: 'internal',
+                                    type: 'tool-result',
+                                    payload: { toolName, result: chunk, toolCallId, preliminary: true },
+                                });
+                            },
+                        });
                         await runCtx.runStore.putRunState(runCtx.runState);
                         continue;
                     }
@@ -221,14 +339,18 @@ export class Runtime {
                 await this.applyCompaction(runCtx, activeAgent, emit, false);
             }
             catch (error) {
-                await this.hooks?.onError?.(runCtx, error);
+                await runHookSafely('onError', () => this.hooks?.onError?.(runCtx, error));
                 if (isDegradableRuntimeError(error)) {
                     const message = error instanceof Error ? error.message : String(error);
-                    emit({ type: 'error', error: message });
+                    emit({ channel: 'client', type: 'error', payload: { error: message } });
                     const degradedId = crypto.randomUUID();
-                    emit({ type: 'text-start', id: degradedId });
-                    emit({ type: 'text-delta', id: degradedId, delta: SAFE_DEGRADED_MESSAGE });
-                    emit({ type: 'text-end', id: degradedId });
+                    emit({ channel: 'client', type: 'text-start', payload: { id: degradedId } });
+                    emit({
+                        channel: 'client',
+                        type: 'text-delta',
+                        payload: { id: degradedId, delta: SAFE_DEGRADED_MESSAGE },
+                    });
+                    emit({ channel: 'client', type: 'text-end', payload: { id: degradedId } });
                     runCtx.runState.messages = [
                         ...runCtx.runState.messages,
                         { role: 'assistant', content: SAFE_DEGRADED_MESSAGE },
@@ -254,10 +376,22 @@ export class Runtime {
                     outcomeReason: loopResult.kind === 'ended' ? loopResult.reason : undefined,
                     memoryIngest: async () => {
                         await runMemoryIngest(runCtx);
+                        if (this.config.trackGoals) {
+                            const controlModel = this.agentsById.get(runCtx.runState.activeAgentId)?.controlModel ??
+                                runCtx.controlModel;
+                            await updateGoalsFromTurn(runCtx, controlModel);
+                        }
+                    },
+                });
+                await runHookSafely('onEnd', () => this.hooks?.onEnd?.(runCtx));
+                emit({
+                    channel: 'client',
+                    type: 'done',
+                    payload: {
+                        sessionId: opened.session.id,
+                        usage: computeTurnTraceUsage(usageBaseline, runCtx.runState.state),
                     },
                 });
-                await this.hooks?.onEnd?.(runCtx);
-                emit({ type: 'done', sessionId: opened.session.id });
             }
             return { text: collectAssistantText(runCtx.runState.messages), toolResults: [] };
         };
@@ -276,12 +410,35 @@ export class Runtime {
             run: gated,
         });
     }
+    async runOnce(opts) {
+        const existing = opts.sessionId ? await this.sessionStore.get(opts.sessionId) : null;
+        // Caller's explicit agentId wins, matching run() (`opts.agentId ?? defaultAgentId`).
+        // Persisted state is the fallback, not an override — otherwise the two public
+        // entry points disagree about which agent handles the same turn.
+        const agentId = opts.agentId ?? existing?.activeAgentId ?? existing?.currentAgent ?? this.config.defaultAgentId;
+        return recordRunOnce(this, { ...opts, agentId });
+    }
     stream(opts) {
         return this.run(opts);
     }
     async getSession(sessionId) {
         return this.sessionStore.get(sessionId);
     }
+    async getTrace(traceId) {
+        await this.settleTraceWrites();
+        return this.traceStore?.getTrace(traceId) ?? null;
+    }
+    async listTraces(sessionId) {
+        await this.settleTraceWrites();
+        return this.traceStore?.listTraces(sessionId) ?? [];
+    }
+    getTraceStore() {
+        return this.traceStore;
+    }
+    /** The agent used when neither the caller nor persisted state names one. */
+    getDefaultAgentId() {
+        return this.config.defaultAgentId;
+    }
     getSessionStore() {
         return this.sessionStore;
     }
@@ -308,6 +465,65 @@ export class Runtime {
             markedBy: opts?.markedBy ?? 'http',
         });
     }
+    shouldTrace(sessionId, input) {
+        if (this.traceSinks.length === 0)
+            return false;
+        const sampling = this.config.tracing?.sampling;
+        if (typeof sampling === 'function') {
+            try {
+                return sampling({ sessionId, input });
+            }
+            catch {
+                return false;
+            }
+        }
+        if (sampling === undefined)
+            return true;
+        return sampling > 0 && (sampling >= 1 || Math.random() < sampling);
+    }
+    writeSpan(original) {
+        let span = original;
+        try {
+            if (this.config.tracing?.redact) {
+                span = this.config.tracing.redact(structuredClone(original));
+            }
+        }
+        catch {
+            return;
+        }
+        if (!span)
+            return;
+        for (const sink of this.traceSinks) {
+            try {
+                const result = sink.write(span);
+                if (result instanceof Promise) {
+                    const pending = result.catch(() => { }).finally(() => this.pendingTraceWrites.delete(pending));
+                    this.pendingTraceWrites.add(pending);
+                }
+            }
+            catch {
+                // Traces are derived observability and never participate in run correctness.
+            }
+        }
+    }
+    async settleTraceWrites() {
+        await Promise.allSettled([...this.pendingTraceWrites]);
+        await Promise.allSettled(this.traceSinks.map((sink) => sink.flush?.()));
+    }
+    flushTraceSinks() {
+        for (const sink of this.traceSinks) {
+            try {
+                const result = sink.flush?.();
+                if (result) {
+                    const pending = result.catch(() => { }).finally(() => this.pendingTraceWrites.delete(pending));
+                    this.pendingTraceWrites.add(pending);
+                }
+            }
+            catch {
+                // Export flushes are observational and never affect the run.
+            }
+        }
+    }
     /**
      * Compact `runState.messages` when over the configured trigger (or always,
      * when `force`). Persists both the run state and the session message mirror.
@@ -327,27 +543,33 @@ export class Runtime {
             model,
             config,
             force,
+            lastPromptTokens: readLastPromptTokens(runCtx.runState.state),
         });
         if (!result.compacted) {
             if (force) {
-                emit({ type: 'compaction-skipped', reason: result.reason });
+                emit({
+                    channel: 'internal',
+                    type: 'compaction-skipped',
+                    payload: { 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) {
+        await mutateSessionWithRetry(this.sessionStore, runCtx.session.id, (latest) => {
             latest.messages = [...result.messages];
-            await this.sessionStore.save(latest);
-        }
+        });
         runCtx.session.messages = [...result.messages];
         emit({
+            channel: 'internal',
             type: 'context-compacted',
-            beforeTokens: result.beforeTokens,
-            afterTokens: result.afterTokens,
-            summarizedCount: result.summarizedCount,
+            payload: {
+                beforeTokens: result.beforeTokens,
+                afterTokens: result.afterTokens,
+                summarizedCount: result.summarizedCount,
+            },
         });
         return true;
     }
@@ -362,9 +584,12 @@ export class Runtime {
         runCtx.runState.messages = runCtx.session.messages;
         const compacted = await this.applyCompaction(runCtx, agent, emit, true);
         emit({
+            channel: 'internal',
             type: 'context-overflow-recovered',
-            strippedCount: recovery.strippedCount,
-            compacted,
+            payload: {
+                strippedCount: recovery.strippedCount,
+                compacted,
+            },
         });
     }
     async getConversationLength(sessionId) {
@@ -409,18 +634,23 @@ export class Runtime {
                 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);
+        const latestSession = await mutateSessionWithRetry(this.sessionStore, runCtx.session.id, (latest) => {
+            recordEscalationOutcome(latest, info.category ?? 'user-request', outcome);
+        });
+        runCtx.session.metadata = latestSession.metadata;
         emit({
+            channel: 'internal',
             type: 'escalation',
-            reason: info.reason,
-            category: info.category,
-            outcome: outcome.status,
-            summary: request.summary,
+            payload: {
+                reason: info.reason,
+                category: info.category,
+                outcome: outcome.status,
+                summary: request.summary,
+            },
         });
     }
     /**
@@ -451,9 +681,9 @@ export class Runtime {
         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);
+        await mutateSessionWithRetry(this.sessionStore, sessionId, (latest) => {
+            latest.messages = [...runState.messages];
+        });
     }
 }
 export function createRuntime(config) {
@@ -476,3 +706,10 @@ function collectAssistantText(messages) {
     }
     return '';
 }
+function appendGoalsPrompt(workingMemoryPrompt, workingMemory) {
+    const goalsPrompt = projectGoalsPromptFromState(workingMemory);
+    if (!goalsPrompt) {
+        return workingMemoryPrompt;
+    }
+    return [workingMemoryPrompt, goalsPrompt].filter((part) => part && part.trim()).join('\n\n');
+}

package/dist/runtime/TokenAccumulator.d.ts

@@ -12,6 +12,13 @@ export declare class TokenAccumulator {
     private _peakUtil;
     private _cumCacheRead;
     constructor(contextWindow?: number | undefined);
+    /** Rehydrate cumulative totals from persisted session state (cross-turn). */
+    restoreCumulative(saved: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cacheReadTokens?: number;
+    }): void;
     record(usage: TurnUsageInput): TurnUsage;
     get cumulative(): {
         inputTokens: number;

package/dist/runtime/TokenAccumulator.js

@@ -12,6 +12,13 @@ export class TokenAccumulator {
     constructor(contextWindow) {
         this.contextWindow = contextWindow;
     }
+    /** Rehydrate cumulative totals from persisted session state (cross-turn). */
+    restoreCumulative(saved) {
+        this._cumInput = saved.inputTokens;
+        this._cumOutput = saved.outputTokens;
+        this._cumTotal = saved.totalTokens;
+        this._cumCacheRead = saved.cacheReadTokens ?? 0;
+    }
     record(usage) {
         this._cumInput += usage.inputTokens;
         this._cumOutput += usage.outputTokens;

package/dist/runtime/TraceRecorder.d.ts

@@ -0,0 +1,51 @@
+import type { TurnResult } from '../types/channel.js';
+import type { StreamPart, TurnHandle } from '../types/stream.js';
+import type { AgentSpan, AgentTrace } from '../types/trace.js';
+import type { RunOptions } from './Runtime.js';
+export interface TraceRecorderOptions {
+    sessionId?: string;
+    agentId?: string;
+    input?: unknown;
+    onSpan?: (span: AgentSpan) => void;
+}
+export declare class TraceRecorder {
+    private readonly trace;
+    private readonly root;
+    private currentFlow?;
+    private currentNode?;
+    private readonly openTools;
+    private readonly toolCallIds;
+    private readonly emitted;
+    private readonly onSpan?;
+    private currentAgentId?;
+    constructor(options?: TraceRecorderOptions);
+    setInitiatingAgent(agentId: string): void;
+    record(part: StreamPart): void;
+    finish(result: TurnResult): AgentTrace;
+    private openSpan;
+    private takeToolSpan;
+    private closeTools;
+    private closeNode;
+    private closeFlow;
+    private setSessionId;
+    private close;
+    private emitSpan;
+}
+/**
+ * What the standalone {@link runOnce} needs from a runtime. `run` is required;
+ * the optional accessors let it resolve the same agent `Runtime.runOnce` would.
+ *
+ * It must NOT call `runtime.runOnce` — that method delegates here, so delegating
+ * back is infinite recursion.
+ */
+export interface RunOnceRuntime {
+    run(opts: RunOptions): TurnHandle;
+    getSessionStore?(): {
+        get(id: string): Promise<{
+            activeAgentId?: string;
+            currentAgent?: string;
+        } | null>;
+    };
+    getDefaultAgentId?(): string;
+}
+export declare function runOnce(runtime: RunOnceRuntime, opts: RunOptions): Promise<AgentTrace>;