@kuralle-agents/core 0.13.0 → 0.14.0

package/dist/index.d.ts

@@ -30,12 +30,6 @@ export type { PromptSection, PromptTemplate, ToolGuideline } from './prompts/ind
 export { BuiltinPersonas, composePersonaPrompt } from './persona/index.js';
 export { resolvePersonaExperiment } from './persona/index.js';
 export type { PersonaConfig, PersonaExperimentCohort, PersonaExperimentConfig, PersonaExperimentMetadata, PersonaExperimentResolution, PersonaLanguagePolicy, PersonaRegister, PersonaVoice, } from './persona/index.js';
-export { HookRunner, createHookRunner } from './hooks/HookRunner.js';
-export { loggingHooks, createLoggingHooks } from './hooks/builtin/logging.js';
-export { createMetricsHooks, InMemoryMetrics } from './hooks/builtin/metrics.js';
-export type { Metrics } from './hooks/builtin/metrics.js';
-export { createObservabilityHooks } from './hooks/builtin/observability.js';
-export type { ObservabilityConfig } from './hooks/builtin/observability.js';
 export type { SessionTrace, TraceStreamEvent } from './types/telemetry.js';
 export { createPromptInjectionGuard } from './processors/builtin/promptInjectionGuard.js';
 export type { PromptInjectionGuardOptions } from './processors/builtin/promptInjectionGuard.js';
@@ -76,8 +70,8 @@ export { applyPromptCache, applyAnthropicCacheControl, buildOpenAIResponsesProvi
 export type { AnthropicCacheTtl, OpenAIResponsesCompactOptions } from './runtime/promptCache.js';
 export { handoffFilters, removeToolHistory, keepRecentMessages, removeKeys, composeFilters, } from './runtime/handoffFilters.js';
 export type { HandoffInputFilter, HandoffInputData, HandoffInputResult, } from './runtime/handoffFilters.js';
-export { DefaultToolExecutor, DefaultConversationState, DefaultConversationEventLog, DefaultAgentStateController, createFoundation, } from './foundation/index.js';
-export type { ToolExecutor, ConversationState, ConversationEventLog, ConversationEvent, AgentStateController, Foundation, FoundationConfig, } from './foundation/index.js';
+export { DefaultAgentStateController } from './foundation/index.js';
+export type { ToolExecutor, AgentStateController, } from './foundation/index.js';
 export type * from './types/index.js';
 export { CapabilityHost, ExtractionCapability, GuardrailCapability, AutoRetrieveCapability, PassThroughRefinement, PassThroughValidation, toGeminiDeclarations, toAISDKTools, } from './capabilities/index.js';
 export type { Capability, CapabilityAction, ExtractionToolResponseEnvelope, FlowReconfigureTransition, ToolDeclaration, PromptSection as CapabilityPromptSection, GeminiFunctionDeclaration, ExtractionCapabilityConfig, RetrieveProvider, AutoRetrieveCapabilityConfig, RefinementCapability, RefineInput, RefineDecision, ValidationCapability, ValidateInput, ValidateDecision, SourceRef, } from './capabilities/index.js';
@@ -87,9 +81,7 @@ export { createInProcessScheduler, createWakeJobRunner, createScheduleFollowupTo
 export type { Scheduler, ScheduledJob, InjectableTimer, WakeOptions, WakeJobPayload, WakeDelivery, WakeRunnable, } from './scheduler/index.js';
 export { filterAuditEntries } from './audit/index.js';
 export type { AuditConfig, AuditEntryBase, AuditEntryType, AuditListOptions, AuditReplayOptions, ConversationAuditEntry, ConversationAuditLog, } from './audit/types.js';
-export type { RealtimeAudioClient, RealtimeSessionConfig, RealtimeAudioConfig, RealtimeToolResponse, RealtimeEventMap, RealtimeSessionHandle, } from './realtime/index.js';
 export type { Hooks } from './types/hooks.js';
-export type { HarnessHooks } from './types/runtime.js';
 export { defineAgent, defineFlow, reply, collect, action, decide, confirmGate, } from './authoring/index.js';
 export { defineTool } from './types/effectTool.js';
 export { fsErrorCode } from './types/filesystem.js';
@@ -98,8 +90,8 @@ export type { CreateFsToolOptions, GrepHit } from './tools/fs/createFsTool.js';
 export { createShellTool } from './tools/fs/createShellTool.js';
 export type { CreateShellToolOptions } from './tools/fs/createShellTool.js';
 export type { Shell, ShellResult, ShellExecOptions } from './types/shell.js';
-export { SkillsCapability, wireAgentSkills, collectRegisteredNames, validateSkillAllowedTools, prepareSkillStore, isSkillStore, InlineSkillStore, } from './skills/index.js';
-export type { WiredAgentSkills, SkillWireAgent } from './skills/index.js';
+export { SkillsCapability, wireAgentSkills, collectRegisteredNames, validateSkillAllowedTools, prepareSkillStore, isSkillStore, InlineSkillStore, CompositeSkillStore, fsSkillStore, defineSkill, parseSkillFrontmatter, } from './skills/index.js';
+export type { WiredAgentSkills, SkillWireAgent, DefineSkillConfig, ParsedSkill, } from './skills/index.js';
 export { buildToolSet, toolToAiSdk, wrapAiSdkTool, ToolApprovalDeniedError, ToolTimeoutError, } from './tools/effect/index.js';
 export type { Tool as EffectTool } from './types/effectTool.js';
 export type { AgentRoute } from './types/processors.js';
@@ -108,12 +100,15 @@ export type { Flow, FlowNode, Transition, CollectNode, DecideNode, ConfirmGate,
 export { parseConfirmation } from './flow/confirmParse.js';
 export type { ConfirmVerdict } from './flow/confirmParse.js';
 export type { Route } from './types/route.js';
-export type { TurnHandle } from './types/stream.js';
-export type { HarnessStreamPart } from './types/stream.js';
+export { PART_CHANNEL } from './types/stream.js';
+export type { StreamChannel, StreamPartBase, TextStartPayload, TextDeltaPayload, TextEndPayload, TextCancelPayload, ToolCallPayload, ToolResultPayload, FlowEnterPayload, FlowEndPayload, NodeEnterPayload, NodeExitPayload, FlowTransitionPayload, HandoffPayload, InterruptedPayload, PausedPayload, ConversationOutcomePayload, InteractivePayload, TurnEndPayload, PipelineValidationBlockPayload, SafetyBlockedPayload, WakePayload, EscalationPayload, ContextCompactedPayload, CompactionSkippedPayload, ContextOverflowRecoveredPayload, ErrorPayload, CustomPayload, DonePayload, KnowledgeCacheHitPayload, KnowledgeCacheMissPayload, KnowledgeSearchPayload, KnowledgeQualityCheckPayload, KnowledgeReformulationPayload, StreamPart, TurnHandle, } from './types/stream.js';
 export type { AgentSpan, AgentTrace, SpanKind } from './types/trace.js';
 export { MemoryTraceStore, isTraceStore, type MemoryTraceStoreOptions, type TraceListWindow, type TraceSink, type TraceStore, } from './tracing/index.js';
 export { OtelTraceSink, langfuseSink, otelSink, toOtlpPayload, type LangfuseSinkOptions, type OtelTraceSinkOptions, } from './tracing/index.js';
 export { TraceRecorder, runOnce, type TraceRecorderOptions } from './runtime/TraceRecorder.js';
+export { TracingService } from './services/TracingService.js';
+export { InMemoryMetricsService } from './services/MetricsService.js';
+export type { MetricsService } from './services/MetricsService.js';
 export { harnessToUIMessageStream } from './ai-sdk/uiMessageStream.js';
 export type { KuralleMetadata, KuralleDataParts, KuralleUIMessage, } from './ai-sdk/uiMessageStream.js';
 export type { ChoiceOption, ResolvedSelection } from './types/selection.js';

package/dist/index.js

@@ -18,10 +18,6 @@ export { createLoadMemoryTool } from './tools/memory.js';
 export { PromptTemplateBuilder, PromptBuilder, createPromptTemplate, SUPPORT_AGENT_TEMPLATE, SALES_AGENT_TEMPLATE, TRIAGE_AGENT_TEMPLATE, createSupportAgentTemplate, DEFAULT_HANDOFF_INSTRUCTION, } from './prompts/index.js';
 export { BuiltinPersonas, composePersonaPrompt } from './persona/index.js';
 export { resolvePersonaExperiment } from './persona/index.js';
-export { HookRunner, createHookRunner } from './hooks/HookRunner.js';
-export { loggingHooks, createLoggingHooks } from './hooks/builtin/logging.js';
-export { createMetricsHooks, InMemoryMetrics } from './hooks/builtin/metrics.js';
-export { createObservabilityHooks } from './hooks/builtin/observability.js';
 export { createPromptInjectionGuard } from './processors/builtin/promptInjectionGuard.js';
 export { createPiiInputGuard, createPiiOutputGuard, redactPii, } from './processors/builtin/piiGuard.js';
 export { createModerationGuard, createModerationOutputGuard, } from './processors/builtin/moderationGuard.js';
@@ -45,7 +41,7 @@ export { compactMessages, estimateMessagesTokens, DEFAULT_COMPACTION_TRIGGER_TOK
 export { isContextOverflowError, recoverFromContextOverflow, } from './runtime/contextOverflow.js';
 export { applyPromptCache, applyAnthropicCacheControl, buildOpenAIResponsesProviderOptions, isAnthropicLanguageModel, isOpenAIResponsesModel, } from './runtime/promptCache.js';
 export { handoffFilters, removeToolHistory, keepRecentMessages, removeKeys, composeFilters, } from './runtime/handoffFilters.js';
-export { DefaultToolExecutor, DefaultConversationState, DefaultConversationEventLog, DefaultAgentStateController, createFoundation, } from './foundation/index.js';
+export { DefaultAgentStateController } from './foundation/index.js';
 export { CapabilityHost, ExtractionCapability, GuardrailCapability, AutoRetrieveCapability, PassThroughRefinement, PassThroughValidation, toGeminiDeclarations, toAISDKTools, } from './capabilities/index.js';
 export { buildEscalationRequest, ensureSessionMetadata } from './escalation/escalation.js';
 export { createInProcessScheduler, createWakeJobRunner, createScheduleFollowupTool, wakeJob, isWakeJob, WAKE_JOB_KIND, } from './scheduler/index.js';
@@ -55,12 +51,15 @@ export { defineTool } from './types/effectTool.js';
 export { fsErrorCode } from './types/filesystem.js';
 export { createFsTool } from './tools/fs/createFsTool.js';
 export { createShellTool } from './tools/fs/createShellTool.js';
-export { SkillsCapability, wireAgentSkills, collectRegisteredNames, validateSkillAllowedTools, prepareSkillStore, isSkillStore, InlineSkillStore, } from './skills/index.js';
+export { SkillsCapability, wireAgentSkills, collectRegisteredNames, validateSkillAllowedTools, prepareSkillStore, isSkillStore, InlineSkillStore, CompositeSkillStore, fsSkillStore, defineSkill, parseSkillFrontmatter, } from './skills/index.js';
 export { buildToolSet, toolToAiSdk, wrapAiSdkTool, ToolApprovalDeniedError, ToolTimeoutError, } from './tools/effect/index.js';
 export { parseConfirmation } from './flow/confirmParse.js';
+export { PART_CHANNEL } from './types/stream.js';
 export { MemoryTraceStore, isTraceStore, } from './tracing/index.js';
 export { OtelTraceSink, langfuseSink, otelSink, toOtlpPayload, } from './tracing/index.js';
 export { TraceRecorder, runOnce } from './runtime/TraceRecorder.js';
+export { TracingService } from './services/TracingService.js';
+export { InMemoryMetricsService } from './services/MetricsService.js';
 export { harnessToUIMessageStream } from './ai-sdk/uiMessageStream.js';
 export { DURABLE_RUNS_KEY } from './runtime/durable/types.js';
 export { createRuntime, Runtime, } from './runtime/Runtime.js';

package/dist/outcomes/streamPart.d.ts

@@ -1,3 +1,3 @@
-import type { HarnessStreamPart } from '../types/voice.js';
+import type { StreamPart } from '../types/stream.js';
 import type { ConversationOutcomeRecord } from './types.js';
-export declare function toConversationOutcomeStreamPart(record: ConversationOutcomeRecord): HarnessStreamPart;
+export declare function toConversationOutcomeStreamPart(record: ConversationOutcomeRecord): StreamPart;

package/dist/outcomes/streamPart.js

@@ -1,8 +1,7 @@
 export function toConversationOutcomeStreamPart(record) {
     return {
+        channel: 'client',
         type: 'conversation-outcome',
-        outcome: record.outcome,
-        ...(record.reason ? { reason: record.reason } : {}),
-        markedBy: record.markedBy,
+        payload: { outcome: record.outcome },
     };
 }

package/dist/prompts/PromptBuilder.d.ts

@@ -1,5 +1,5 @@
 import type { ToolSet } from '../tools/Tool.js';
-import type { PromptTemplate, PromptBuilderConfig, BrandVoiceConfig, KnowledgeContext, SessionMemory, AgentDefinition, PolicyProfile } from './types.js';
+import type { PromptTemplate, PromptBuilderConfig, BrandVoiceConfig, KnowledgeContext, SessionMemory, AgentIdentity, PolicyProfile } from './types.js';
 import { type PersonaConfig } from '../persona/index.js';
 export declare class PromptBuilder {
     private config;
@@ -10,7 +10,7 @@ export declare class PromptBuilder {
      */
     constructor(config?: PromptBuilderConfig | PromptTemplate);
     withTemplate(template: PromptTemplate): this;
-    withAgentDefinition(definition: AgentDefinition): this;
+    withAgentIdentity(identity: AgentIdentity): this;
     withBrandVoice(brandVoice: BrandVoiceConfig): this;
     withPersona(persona: PersonaConfig): this;
     addPersona(persona: PersonaConfig): this;
@@ -19,7 +19,7 @@ export declare class PromptBuilder {
     withKnowledgeContext(context: KnowledgeContext): this;
     withPolicyProfile(profile: PolicyProfile): this;
     build(): string;
-    private buildAgentDefinitionSections;
+    private buildAgentIdentitySections;
     private buildPersonaSections;
     private buildBrandVoiceSections;
     private buildKnowledgeSections;

package/dist/prompts/PromptBuilder.js

@@ -22,8 +22,8 @@ export class PromptBuilder {
         this.config.template = template;
         return this;
     }
-    withAgentDefinition(definition) {
-        this.config.agentDefinition = definition;
+    withAgentIdentity(identity) {
+        this.config.agentIdentity = identity;
         return this;
     }
     withBrandVoice(brandVoice) {
@@ -63,8 +63,8 @@ export class PromptBuilder {
             immutable: true,
         });
         // Layer 1: Agent Definition
-        if (this.config.agentDefinition) {
-            sections.push(...this.buildAgentDefinitionSections());
+        if (this.config.agentIdentity) {
+            sections.push(...this.buildAgentIdentitySections());
         }
         if (this.config.persona) {
             sections.push(...this.buildPersonaSections());
@@ -100,8 +100,8 @@ export class PromptBuilder {
         const sorted = sections.sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
         return sorted.map(s => this.formatSection(s)).join('\n\n');
     }
-    buildAgentDefinitionSections() {
-        const def = this.config.agentDefinition;
+    buildAgentIdentitySections() {
+        const def = this.config.agentIdentity;
         const sections = [];
         sections.push({
             type: 'identity',

package/dist/prompts/index.d.ts

@@ -1,4 +1,4 @@
-export type { PromptSection, PromptTemplate, ToolGuideline, PromptTemplateBuilderOptions, PromptSectionType, VoiceRulesConfig, VoiceRules, GlossaryTerm, GlossaryConfig, BrandVoiceConfig, KnowledgeContext, SessionMemory, AgentDefinition, PolicyProfile, PromptBuilderConfig, } from './types.js';
+export type { PromptSection, PromptTemplate, ToolGuideline, PromptTemplateBuilderOptions, PromptSectionType, VoiceRulesConfig, VoiceRules, GlossaryTerm, GlossaryConfig, BrandVoiceConfig, KnowledgeContext, SessionMemory, AgentIdentity, PolicyProfile, PromptBuilderConfig, } from './types.js';
 export { PromptTemplateBuilder, createPromptTemplate, LAYER_PRIORITIES } from './types.js';
 export { PromptBuilder, createPrompt } from './PromptBuilder.js';
 export { SUPPORT_AGENT_TEMPLATE, SALES_AGENT_TEMPLATE, TRIAGE_AGENT_TEMPLATE, createSupportAgentTemplate, BUILTIN_TEMPLATES, DEFAULT_HANDOFF_INSTRUCTION, } from './templates.js';

package/dist/prompts/types.d.ts

@@ -52,14 +52,19 @@ export interface SessionMemory {
     /** Compact open-thread note projected from session.workingMemory.__goals (G5). */
     openGoalsPrompt?: string;
 }
-export interface AgentDefinition {
+/**
+ * Who the agent is, rendered into the `identity` / `role` / `capabilities` prompt
+ * sections by `PromptBuilder`. A prompt fragment — not the agent itself, which is
+ * `AgentConfig` from `defineAgent`.
+ */
+export interface AgentIdentity {
     identity: string;
     role: string;
     capabilities?: string[];
 }
 export interface PromptBuilderConfig {
     template?: PromptTemplate;
-    agentDefinition?: AgentDefinition;
+    agentIdentity?: AgentIdentity;
     persona?: PersonaConfig;
     brandVoice?: BrandVoiceConfig;
     knowledgeContext?: KnowledgeContext;

package/dist/runtime/InMemoryRetrievalCache.d.ts

@@ -1,4 +1,4 @@
-import type { KnowledgeRetrievalResult, RetrievalCacheAdapter } from '../types/voice.js';
+import type { KnowledgeRetrievalResult, RetrievalCacheAdapter } from '../types/knowledge.js';
 /**
  * Zero-config, in-process session retrieval cache (G6). Keyed by the query
  * embedding: a lookup returns the cached results of the most-similar recent

package/dist/runtime/KnowledgeProvider.d.ts

@@ -12,7 +12,8 @@
  * The provider holds no mutable state itself — per-session cache state is
  * stored on RunContext.retrievalCache so it survives agent handoffs.
  */
-import type { KnowledgeProviderConfig, AgentKnowledgeOverrides, KnowledgeRetrievalResult, HarnessStreamPart, RetrievalCacheAdapter } from '../types/index.js';
+import type { KnowledgeProviderConfig, AgentKnowledgeOverrides, KnowledgeRetrievalResult, RetrievalCacheAdapter } from '../types/index.js';
+import type { StreamPart } from '../types/stream.js';
 export type { RetrievalCacheAdapter } from '../types/index.js';
 interface ResolvedKnowledgeConfig {
     compiledEnabled: boolean;
@@ -72,7 +73,7 @@ export declare class KnowledgeProvider {
      */
     retrieve(query: string, cache: RetrievalCacheAdapter | undefined, agentOverrides?: AgentKnowledgeOverrides, isVoice?: boolean): Promise<{
         results: KnowledgeRetrievalResult[];
-        events: HarnessStreamPart[];
+        events: StreamPart[];
     }>;
     /**
      * Run quality check on retrieval results and optionally reformulate.

package/dist/runtime/KnowledgeProvider.js

@@ -92,24 +92,33 @@ export class KnowledgeProvider {
             const cacheLatency = Date.now() - cacheStart;
             if (cached.length > 0) {
                 events.push({
+                    channel: 'internal',
                     type: 'knowledge-cache-hit',
-                    query,
-                    resultCount: cached.length,
-                    latencyMs: cacheLatency,
+                    payload: {
+                        query,
+                        resultCount: cached.length,
+                        latencyMs: cacheLatency,
+                    },
                 });
                 events.push({
+                    channel: 'internal',
                     type: 'knowledge-search',
-                    query,
-                    resultCount: cached.length,
-                    latencyMs: cacheLatency,
-                    layer: 'cache',
+                    payload: {
+                        query,
+                        resultCount: cached.length,
+                        latencyMs: cacheLatency,
+                        layer: 'cache',
+                    },
                 });
                 return { results: cached, events };
             }
             events.push({
+                channel: 'internal',
                 type: 'knowledge-cache-miss',
-                query,
-                latencyMs: cacheLatency,
+                payload: {
+                    query,
+                    latencyMs: cacheLatency,
+                },
             });
             // Layer 3: Hybrid search (cache miss)
             const searchStart = Date.now();
@@ -121,11 +130,14 @@ export class KnowledgeProvider {
             });
             const searchLatency = Date.now() - searchStart;
             events.push({
+                channel: 'internal',
                 type: 'knowledge-search',
-                query,
-                resultCount: results.length,
-                latencyMs: searchLatency,
-                layer: 'hybrid',
+                payload: {
+                    query,
+                    resultCount: results.length,
+                    latencyMs: searchLatency,
+                    layer: 'hybrid',
+                },
             });
             // Quality check + optional reformulation
             results = await this.runQualityCheck(query, results, events, isVoice, resolved);
@@ -144,11 +156,14 @@ export class KnowledgeProvider {
         });
         const searchLatency = Date.now() - searchStart;
         events.push({
+            channel: 'internal',
             type: 'knowledge-search',
-            query,
-            resultCount: results.length,
-            latencyMs: searchLatency,
-            layer: 'hybrid',
+            payload: {
+                query,
+                resultCount: results.length,
+                latencyMs: searchLatency,
+                layer: 'hybrid',
+            },
         });
         // Quality check + optional reformulation
         results = await this.runQualityCheck(query, results, events, isVoice, resolved);
@@ -182,12 +197,15 @@ export class KnowledgeProvider {
             quality = 'low';
         }
         events.push({
+            channel: 'internal',
             type: 'knowledge-quality-check',
-            query,
-            quality,
-            topScore,
-            avgScore,
-            coverageEstimate,
+            payload: {
+                query,
+                quality,
+                topScore,
+                avgScore,
+                coverageEstimate,
+            },
         });
         // Only reformulate on low quality with a reformulate callback
         if (quality !== 'low' || !qc.reformulate)
@@ -195,11 +213,14 @@ export class KnowledgeProvider {
         if (isVoice) {
             // Voice: signal background reformulation, don't block
             events.push({
+                channel: 'internal',
                 type: 'knowledge-reformulation',
-                originalQuery: query,
-                reformulatedQuery: '',
-                trigger: 'background',
-                latencyMs: 0,
+                payload: {
+                    originalQuery: query,
+                    reformulatedQuery: '',
+                    trigger: 'background',
+                    latencyMs: 0,
+                },
             });
             return results;
         }
@@ -209,11 +230,14 @@ export class KnowledgeProvider {
             const reformulatedQuery = await qc.reformulate(query, results);
             const reformulateLatency = Date.now() - reformulateStart;
             events.push({
+                channel: 'internal',
                 type: 'knowledge-reformulation',
-                originalQuery: query,
-                reformulatedQuery,
-                trigger: 'inline',
-                latencyMs: reformulateLatency,
+                payload: {
+                    originalQuery: query,
+                    reformulatedQuery,
+                    trigger: 'inline',
+                    latencyMs: reformulateLatency,
+                },
             });
             // Re-retrieve with reformulated query (one attempt, no recursion)
             if (this.retriever) {

package/dist/runtime/Runtime.d.ts

@@ -12,7 +12,7 @@ import type { SignalDelivery } from './durable/types.js';
 import type { ResolvedSelection } from '../types/selection.js';
 import type { ConversationOutcome, ConversationOutcomeMarkedBy } from '../outcomes/types.js';
 import type { classifyHostTarget, selectHostTarget } from './select.js';
-import type { KnowledgeProviderConfig } from '../types/voice.js';
+import type { KnowledgeProviderConfig } from '../types/knowledge.js';
 import type { MemoryService as V1MemoryService } from '../memory/MemoryService.js';
 import type { PersistentMemoryStore } from '../memory/blocks/types.js';
 import { type CompactionConfig } from './compaction.js';
@@ -131,6 +131,8 @@ export declare class Runtime {
     getTrace(traceId: string): Promise<AgentTrace | null>;
     listTraces(sessionId: string): Promise<AgentTrace[]>;
     getTraceStore(): TraceStore | undefined;
+    /** The agent used when neither the caller nor persisted state names one. */
+    getDefaultAgentId(): string;
     getSessionStore(): SessionStore;
     deleteSession(sessionId: string): Promise<void>;
     abortSession(sessionId: string, reason?: string): void;

package/dist/runtime/Runtime.js

@@ -34,6 +34,7 @@ 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;
@@ -72,6 +73,7 @@ export class Runtime {
         const recorder = this.shouldTrace(sessionId, opts.input)
             ? new TraceRecorder({
                 sessionId,
+                agentId: opts.agentId ?? this.config.defaultAgentId,
                 input: opts.input,
                 onSpan: (span) => this.writeSpan(span),
             })
@@ -89,7 +91,7 @@ export class Runtime {
                 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,
@@ -106,6 +108,7 @@ export class Runtime {
                 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)
@@ -121,9 +124,16 @@ 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);
@@ -170,9 +180,9 @@ export class Runtime {
             runCtx.skillPrompt = openingSurface.skillPrompt;
             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;
@@ -202,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 });
@@ -285,9 +299,20 @@ export class Runtime {
                             agentId: target.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 },
+                                });
                             },
                         });
                         await runCtx.runStore.putRunState(runCtx.runState);
@@ -314,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 },
@@ -354,11 +383,14 @@ export class Runtime {
                         }
                     },
                 });
-                await this.hooks?.onEnd?.(runCtx);
+                await runHookSafely('onEnd', () => this.hooks?.onEnd?.(runCtx));
                 emit({
+                    channel: 'client',
                     type: 'done',
-                    sessionId: opened.session.id,
-                    usage: computeTurnTraceUsage(usageBaseline, runCtx.runState.state),
+                    payload: {
+                        sessionId: opened.session.id,
+                        usage: computeTurnTraceUsage(usageBaseline, runCtx.runState.state),
+                    },
                 });
             }
             return { text: collectAssistantText(runCtx.runState.messages), toolResults: [] };
@@ -378,8 +410,13 @@ export class Runtime {
             run: gated,
         });
     }
-    runOnce(opts) {
-        return recordRunOnce(this, opts);
+    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);
@@ -398,6 +435,10 @@ export class Runtime {
     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;
     }
@@ -506,7 +547,11 @@ export class Runtime {
         });
         if (!result.compacted) {
             if (force) {
-                emit({ type: 'compaction-skipped', reason: result.reason });
+                emit({
+                    channel: 'internal',
+                    type: 'compaction-skipped',
+                    payload: { reason: result.reason },
+                });
             }
             return false;
         }
@@ -518,10 +563,13 @@ export class Runtime {
         });
         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;
     }
@@ -536,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) {
@@ -592,11 +643,14 @@ export class Runtime {
         });
         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,
+            },
         });
     }
     /**