@kuralle-agents/core 0.13.0 → 0.15.0

package/dist/flow/runFlow.js

@@ -1,5 +1,6 @@
 import { popFlowPark, runCollectDigression } from './collectDigression.js';
 import { parseConfirmation } from './confirmParse.js';
+import { inferRequiredFields } from './extraction.js';
 import { hasPendingUserInput, setPendingUserInput } from '../runtime/channels/inputBuffer.js';
 import { userInputToText } from '../runtime/userInput.js';
 import { collectUntilComplete } from './collectUntilComplete.js';
@@ -11,8 +12,7 @@ import { evaluateReplyControl } from './controlEvaluator.js';
 import { runNodeVerify, VerifyBlockedError } from './verify.js';
 import { loadRecordedSteps } from '../runtime/durable/replay.js';
 import { persistTurnUsageFromTurn } from '../runtime/turnTokenUsage.js';
-import { SuspendError } from '../runtime/durable/RunStore.js';
-import { ToolApprovalDeniedError } from '../tools/effect/errors.js';
+import { isApprovalDenial, isControlFlowSignal } from '../runtime/controlFlowSignal.js';
 import { emitInteractiveOnNodeEnter } from './emitInteractive.js';
 import { appendConversationAudit } from '../audit/record.js';
 import { appendSafeAssistantMessage, degradeFlowError, findEscalateNode, } from './degrade.js';
@@ -254,6 +254,27 @@ async function dispatchNode(node, run, driver, ctx, agent, flow) {
     }
     throw new Error(`Unknown node kind: ${node.kind}`);
 }
+/**
+ * Drop everything a previous run of `flow` collected. Namespaced cache keys AND the
+ * un-namespaced copies `reduceTransition` promotes onto `run.state` via Object.assign.
+ *
+ * Clearing only the cache was not enough. The promoted fields are a plain merge, and
+ * `projectCollectData` omits any field the new extraction did not supply — so an optional
+ * field answered on report #1 (say `accessNotes: "key under the mat"`) and left blank on
+ * report #2 survives the merge and is read by the next action node as if it belonged to
+ * report #2. A work order then ships another unit's access instructions.
+ */
+export function clearFlowCollectCache(state, flow) {
+    for (const node of flow.nodes) {
+        if (node.kind !== 'collect')
+            continue;
+        delete state[`__collect_${node.id}`];
+        delete state[`__collectTurns_${node.id}`];
+        for (const field of inferRequiredFields(node.schema)) {
+            delete state[field];
+        }
+    }
+}
 export async function runFlow(flow, run, driver, ctx, agent) {
     const registry = buildNodeRegistry(flow);
     const startNode = resolveStartNode(flow);
@@ -263,10 +284,22 @@ export async function runFlow(flow, run, driver, ctx, agent) {
         throw new Error(`Unknown active node "${initialNodeId}" in flow "${flow.name}"`);
     }
     if (!run.activeNode) {
+        // Fresh entry, not a resume. A collect node caches its extraction under
+        // `__collect_<nodeId>` and that cache is SUPPOSED to survive turn boundaries — it is how
+        // fields accumulate across several user turns mid-flow. But it must not survive the flow
+        // itself: re-entering a completed flow found the previous run's cache already complete,
+        // finished instantly with those values, and the action node acted on them.
+        //
+        // Observed live: three maintenance reports for three different units produced three
+        // copies of the FIRST work order; the units actually reported were never touched.
+        //
+        // Cleared here rather than on completion so mid-flow accumulation is untouched — which
+        // is what `continuity.test.ts` and the G14 slot-correction test encode.
+        clearFlowCollectCache(run.state, flow);
         run.activeNode = node.id;
         run.activeFlow = flow.name;
-        ctx.emit({ type: 'flow-enter', flow: flow.name });
-        ctx.emit({ type: 'node-enter', nodeName: node.id });
+        ctx.emit({ channel: 'internal', type: 'flow-enter', payload: { flow: flow.name } });
+        ctx.emit({ channel: 'internal', type: 'node-enter', payload: { nodeName: node.id } });
         emitInteractiveOnNodeEnter(node, run.state, ctx.emit);
     }
     const edgeCounts = new Map();
@@ -277,11 +310,14 @@ export async function runFlow(flow, run, driver, ctx, agent) {
             transition = await dispatchNode(node, run, driver, ctx, agent, flow);
         }
         catch (error) {
-            if (error instanceof SuspendError || error instanceof ToolApprovalDeniedError) {
+            // Neither is a malfunction, so neither may reach degradeFlowError and be reported to
+            // the user as "something went wrong on my side". A suspend resumes later; a denial is
+            // the action node author's to handle, since they chose to call the tool.
+            if (isControlFlowSignal(error) || isApprovalDenial(error)) {
                 throw error;
             }
             const message = error instanceof Error ? error.message : String(error);
-            ctx.emit({ type: 'error', error: message });
+            ctx.emit({ channel: 'client', type: 'error', payload: { error: message } });
             return degradeFlowError(flow, registry, run, driver, ctx, (n, r, d, c) => dispatchNode(n, r, d, c, agent, flow));
         }
         if (transition.kind === 'switchFlow') {
@@ -298,15 +334,27 @@ export async function runFlow(flow, run, driver, ctx, agent) {
                     run.activeFlow = park.flow;
                     run.activeNode = park.node;
                     await ctx.runStore.putRunState(run);
-                    ctx.emit({ type: 'flow-end', flow: flow.name, reason: transition.reason });
+                    ctx.emit({
+                        channel: 'internal',
+                        type: 'flow-end',
+                        payload: { flow: flow.name, reason: transition.reason },
+                    });
                     return runFlow(parkedFlow, run, driver, ctx, agent);
                 }
             }
-            ctx.emit({ type: 'flow-end', flow: flow.name, reason: transition.reason });
+            ctx.emit({
+                channel: 'internal',
+                type: 'flow-end',
+                payload: { flow: flow.name, reason: transition.reason },
+            });
             return { kind: 'ended', reason: transition.reason };
         }
         if (transition.kind === 'handoff') {
-            ctx.emit({ type: 'handoff', targetAgent: transition.to, reason: transition.reason });
+            ctx.emit({
+                channel: 'internal',
+                type: 'handoff',
+                payload: { targetAgent: transition.to, reason: transition.reason },
+            });
             return { kind: 'handoff', to: transition.to, reason: transition.reason };
         }
         if (transition.kind === 'escalate') {
@@ -337,14 +385,18 @@ export async function runFlow(flow, run, driver, ctx, agent) {
         }
         catch (error) {
             if (error instanceof VerifyBlockedError) {
-                ctx.emit({ type: 'error', error: error.message });
+                ctx.emit({ channel: 'client', type: 'error', payload: { error: error.message } });
                 return { kind: 'awaitingUser' };
             }
             throw error;
         }
         const oscillation = bumpOscillation(edgeCounts, node.id, target.id);
         if (oscillation > maxOscillations) {
-            ctx.emit({ type: 'error', error: `Flow oscillation blocked: ${node.id} -> ${target.id}` });
+            ctx.emit({
+                channel: 'client',
+                type: 'error',
+                payload: { error: `Flow oscillation blocked: ${node.id} -> ${target.id}` },
+            });
             const escalateNode = findEscalateNode(registry);
             if (escalateNode) {
                 appendSafeAssistantMessage(run, ctx);
@@ -363,7 +415,11 @@ export async function runFlow(flow, run, driver, ctx, agent) {
                 continue;
             }
             appendSafeAssistantMessage(run, ctx);
-            ctx.emit({ type: 'flow-end', flow: flow.name, reason: 'error_degraded' });
+            ctx.emit({
+                channel: 'internal',
+                type: 'flow-end',
+                payload: { flow: flow.name, reason: 'error_degraded' },
+            });
             return { kind: 'ended', reason: 'error_degraded' };
         }
         await reduceTransition({

package/dist/foundation/AgentStateController.d.ts

@@ -1,7 +1,7 @@
 import type { Session } from '../types/index.js';
 /**
  * Manages active agent resolution, handoff recording, and agent state.
- * Shared by Runtime and VoiceEngine.
+ * Used by Runtime.
  */
 export interface AgentStateController {
     /** Resolve the active agent ID, falling back to the provided default. */

package/dist/foundation/ToolExecutor.d.ts

@@ -1,7 +1,7 @@
 import type { Session, ToolCallRecord } from '../types/index.js';
 /**
  * Minimal tool shape required by the executor.
- * Compatible with AI SDK `Tool`, VoiceToolDef, and plain `{ execute }` objects.
+ * Compatible with AI SDK `Tool` and plain `{ execute }` objects.
  */
 export interface ExecutableTool {
     execute: (args: unknown, options?: unknown) => Promise<unknown>;
@@ -9,7 +9,7 @@ export interface ExecutableTool {
 }
 /**
  * Encapsulates tool execution with enforcement, idempotency, and context enrichment.
- * Shared by Runtime (text path) and VoiceEngine (audio path).
+ * Used by Runtime.
  */
 export interface ToolExecutor {
     /**

package/dist/foundation/index.d.ts

@@ -1,14 +1,3 @@
-export type { AgentDefinition } from './AgentDefinition.js';
 export type { ToolExecutor, ExecutableTool } from './ToolExecutor.js';
-export type { ConversationState } from './ConversationState.js';
-export type { ConversationEventLog, ConversationEvent } from './ConversationEventLog.js';
 export type { AgentStateController } from './AgentStateController.js';
-export { DefaultToolExecutor, ToolTimeoutError } from './DefaultToolExecutor.js';
-export type { DefaultToolExecutorConfig } from './DefaultToolExecutor.js';
-export { DefaultConversationState } from './DefaultConversationState.js';
-export type { DefaultConversationStateConfig } from './DefaultConversationState.js';
-export { DefaultConversationEventLog } from './DefaultConversationEventLog.js';
-export type { DefaultConversationEventLogConfig } from './DefaultConversationEventLog.js';
 export { DefaultAgentStateController } from './DefaultAgentStateController.js';
-export { createFoundation } from './createFoundation.js';
-export type { Foundation, FoundationConfig } from './createFoundation.js';

package/dist/foundation/index.js

@@ -1,7 +1,2 @@
 // Default implementations
-export { DefaultToolExecutor, ToolTimeoutError } from './DefaultToolExecutor.js';
-export { DefaultConversationState } from './DefaultConversationState.js';
-export { DefaultConversationEventLog } from './DefaultConversationEventLog.js';
 export { DefaultAgentStateController } from './DefaultAgentStateController.js';
-// Factory
-export { createFoundation } from './createFoundation.js';

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';
@@ -21,6 +21,12 @@ import type { WakeOptions } from '../scheduler/index.js';
 import type { HandoffInputFilter } from './handoffFilters.js';
 import type { AgentSpan, AgentTrace } from '../types/trace.js';
 import { type TraceSink, type TraceStore } from '../tracing/TraceStore.js';
+/**
+ * What the user is told when the run hands off to a human and the app has not configured an
+ * escalation handler to say something better. Silence is the wrong default: an escalation
+ * that emits no text is indistinguishable from the agent having crashed.
+ */
+export declare const HANDOFF_TO_HUMAN_MESSAGE = "I'm bringing a colleague into this \u2014 they'll pick it up from here.";
 export interface TracingConfig {
     enabled?: boolean;
     store?: TraceStore;
@@ -131,6 +137,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;