@kuralle-agents/core 0.13.0 → 0.15.0

package/dist/types/stream.d.ts

@@ -1,135 +1,197 @@
 import type { ConversationOutcome } from '../outcomes/types.js';
 import type { ChoiceOption } from './selection.js';
 import type { EscalationReason } from '../escalation/types.js';
-/**
- * Authoritative runtime stream union (`runFlow` / `Runtime` emit).
- * `types/voice.ts` defines a separate voice/realtime union that intentionally
- * does not include `{ type: 'interactive' }`.
- */
-export type HarnessStreamPart = {
-    type: 'text-start';
+export type StreamChannel = 'client' | 'internal';
+export interface StreamPartBase<Channel extends StreamChannel = StreamChannel> {
+    channel: Channel;
+}
+export interface TextStartPayload {
     id: string;
-} | {
-    type: 'text-delta';
+}
+export interface TextDeltaPayload {
     id: string;
     delta: string;
-} | {
-    type: 'text-end';
+}
+export interface TextEndPayload {
     id: string;
-} | {
-    type: 'text-cancel';
+}
+export interface TextCancelPayload {
     id: string;
     reason: string;
-} | {
-    type: 'tool-call';
+}
+export interface ToolCallPayload {
     toolName: string;
     args: unknown;
     toolCallId?: string;
-} | {
-    type: 'tool-result';
+}
+export interface ToolResultPayload {
     toolName: string;
     result: unknown;
     toolCallId?: string;
-} | {
-    type: 'flow-enter';
+    /** A chunk from a still-running async-iterable tool. The final result follows without it. */
+    preliminary?: boolean;
+}
+export interface FlowEnterPayload {
     flow: string;
-} | {
-    type: 'flow-end';
+}
+export interface FlowEndPayload {
     flow: string;
     reason: string;
-} | {
-    type: 'node-enter';
+}
+export interface NodeEnterPayload {
     nodeName: string;
-} | {
-    type: 'node-exit';
+}
+export interface NodeExitPayload {
     nodeName: string;
-} | {
-    type: 'flow-transition';
+}
+export interface FlowTransitionPayload {
     from: string;
     to: string;
-} | {
-    type: 'handoff';
+}
+export interface HandoffPayload {
     targetAgent: string;
     reason?: string;
-} | {
-    type: 'interrupted';
+}
+export interface InterruptedPayload {
     reason: string;
     lastStep: number;
-} | {
-    type: 'paused';
+}
+export interface PausedPayload {
     waitingFor: string;
-} | {
-    type: 'conversation-outcome';
+}
+export interface ConversationOutcomePayload {
     outcome: ConversationOutcome;
-} | {
-    type: 'interactive';
+}
+export interface InteractivePayload {
     nodeId: string;
     options: ChoiceOption[];
     prompt: string;
-} | {
-    type: 'turn-end';
-} | {
-    type: 'pipeline-validation-block';
+}
+export interface TurnEndPayload {
+}
+export interface PipelineValidationBlockPayload {
     rationale: string;
     userFacingMessage?: string;
-} | {
-    type: 'safety-blocked';
+}
+export interface SafetyBlockedPayload {
     moderator: string;
     rationale: string;
     userFacingMessage: string;
     handlerOutcome?: 'queued' | 'connected' | 'failed';
-} | {
-    /** An agent-initiated (scheduled wake) turn — there is no new user message. */
-    type: 'wake';
+}
+export interface WakePayload {
     reason: string;
-} | {
-    type: 'escalation';
+}
+export interface EscalationPayload {
     reason: string;
     category?: EscalationReason;
-    /** Result of the configured escalation handler. */
     outcome: 'queued' | 'connected' | 'failed';
-    /** The LLM handoff brief included in the request, when generated. */
     summary?: string;
-} | {
-    type: 'context-compacted';
-    /** Estimated history tokens before/after compaction. */
+}
+export interface ContextCompactedPayload {
     beforeTokens: number;
     afterTokens: number;
-    /** Number of older messages folded into the summary. */
     summarizedCount: number;
-} | {
-    type: 'compaction-skipped';
+}
+export interface CompactionSkippedPayload {
     reason: string;
-} | {
-    type: 'context-overflow-recovered';
-    /** Partial assistant/tool messages stripped from the failed turn. */
+}
+export interface ContextOverflowRecoveredPayload {
     strippedCount: number;
-    /** Whether the forced post-recovery compaction actually compacted. */
     compacted: boolean;
-} | {
-    type: 'error';
+}
+export interface ErrorPayload {
     error: string;
-} | {
-    type: 'custom';
+}
+export interface CustomPayload {
     name: string;
     data: unknown;
-} | {
-    type: 'done';
+}
+export interface DonePayload {
     sessionId: string;
-    /** Per-turn token usage: `inputTokens`/`outputTokens` are THIS turn's
-     *  consumption (deltas, for cost attribution); `contextTokens` is the current
-     *  context-window occupancy (last prompt tokens, a snapshot). */
     usage?: {
         inputTokens?: number;
         outputTokens?: number;
         contextTokens?: number;
     };
-};
+}
+export interface KnowledgeCacheHitPayload {
+    query: string;
+    resultCount: number;
+    latencyMs: number;
+}
+export interface KnowledgeCacheMissPayload {
+    query: string;
+    latencyMs: number;
+}
+export interface KnowledgeSearchPayload {
+    query: string;
+    resultCount: number;
+    latencyMs: number;
+    layer: 'cache' | 'hybrid';
+}
+export interface KnowledgeQualityCheckPayload {
+    query: string;
+    quality: 'high' | 'medium' | 'low';
+    topScore: number;
+    avgScore: number;
+    coverageEstimate: number;
+}
+export interface KnowledgeReformulationPayload {
+    originalQuery: string;
+    reformulatedQuery: string;
+    trigger: 'inline' | 'background';
+    latencyMs: number;
+}
+interface StreamPayloadMap {
+    'text-start': TextStartPayload;
+    'text-delta': TextDeltaPayload;
+    'text-end': TextEndPayload;
+    'text-cancel': TextCancelPayload;
+    'tool-call': ToolCallPayload;
+    'tool-result': ToolResultPayload;
+    'flow-enter': FlowEnterPayload;
+    'flow-end': FlowEndPayload;
+    'node-enter': NodeEnterPayload;
+    'node-exit': NodeExitPayload;
+    'flow-transition': FlowTransitionPayload;
+    handoff: HandoffPayload;
+    interrupted: InterruptedPayload;
+    paused: PausedPayload;
+    'conversation-outcome': ConversationOutcomePayload;
+    interactive: InteractivePayload;
+    'turn-end': TurnEndPayload;
+    'pipeline-validation-block': PipelineValidationBlockPayload;
+    'safety-blocked': SafetyBlockedPayload;
+    wake: WakePayload;
+    escalation: EscalationPayload;
+    'context-compacted': ContextCompactedPayload;
+    'compaction-skipped': CompactionSkippedPayload;
+    'context-overflow-recovered': ContextOverflowRecoveredPayload;
+    error: ErrorPayload;
+    custom: CustomPayload;
+    done: DonePayload;
+    'knowledge-cache-hit': KnowledgeCacheHitPayload;
+    'knowledge-cache-miss': KnowledgeCacheMissPayload;
+    'knowledge-search': KnowledgeSearchPayload;
+    'knowledge-quality-check': KnowledgeQualityCheckPayload;
+    'knowledge-reformulation': KnowledgeReformulationPayload;
+}
+type ClientStreamPartType = 'text-start' | 'text-delta' | 'text-end' | 'text-cancel' | 'conversation-outcome' | 'error' | 'done';
+type ChannelFor<Type extends keyof StreamPayloadMap> = Type extends ClientStreamPartType ? 'client' : 'internal';
+export type StreamPart = {
+    [Type in keyof StreamPayloadMap]: StreamPartBase<ChannelFor<Type>> & {
+        type: Type;
+        payload: StreamPayloadMap[Type];
+    };
+}[keyof StreamPayloadMap];
+export declare const PART_CHANNEL: Record<StreamPart['type'], StreamChannel>;
 export interface TurnHandle extends Promise<import('./channel.js').TurnResult> {
-    readonly events: AsyncIterable<HarnessStreamPart>;
+    readonly events: AsyncIterable<StreamPart>;
     toResponseStream(format?: 'sse' | 'ndjson'): ReadableStream;
     toUIMessageStreamResponse(opts?: {
         sessionId?: string;
     }): Response;
     cancel(reason?: string): void;
 }
+export {};

package/dist/types/stream.js

@@ -1 +1,34 @@
-export {};
+export const PART_CHANNEL = {
+    'text-start': 'client',
+    'text-delta': 'client',
+    'text-end': 'client',
+    'text-cancel': 'client',
+    'tool-call': 'internal',
+    'tool-result': 'internal',
+    'flow-enter': 'internal',
+    'flow-end': 'internal',
+    'node-enter': 'internal',
+    'node-exit': 'internal',
+    'flow-transition': 'internal',
+    handoff: 'internal',
+    interrupted: 'internal',
+    paused: 'internal',
+    'conversation-outcome': 'client',
+    interactive: 'internal',
+    'turn-end': 'internal',
+    'pipeline-validation-block': 'internal',
+    'safety-blocked': 'internal',
+    wake: 'internal',
+    escalation: 'internal',
+    'context-compacted': 'internal',
+    'compaction-skipped': 'internal',
+    'context-overflow-recovered': 'internal',
+    error: 'client',
+    custom: 'internal',
+    done: 'client',
+    'knowledge-cache-hit': 'internal',
+    'knowledge-cache-miss': 'internal',
+    'knowledge-search': 'internal',
+    'knowledge-quality-check': 'internal',
+    'knowledge-reformulation': 'internal',
+};

package/dist/types/trace.d.ts

@@ -15,6 +15,8 @@ export interface AgentSpan {
     }>;
     attributes: {
         sessionId: string;
+        /** Agent active when the span opened; a turn span keeps its initiating agent across handoffs. */
+        agentId?: string;
         activeFlow?: string;
         nodeId?: string;
         toolName?: string;

package/guides/AGENTS.md

@@ -43,7 +43,7 @@ const runtime = createRuntime({
 
 const handle = runtime.run({ input: 'Hello', sessionId: 'demo' });
 for await (const part of handle.events) {
-  if (part.type === 'text-delta') process.stdout.write(part.delta);
+  if (part.type === 'text-delta') process.stdout.write(part.payload.delta);
 }
 await handle;
 ```
@@ -221,7 +221,7 @@ const handle = runtime.run({
   sessionId: 'demo',
 });
 for await (const part of handle.events) {
-  if (part.type === 'text-delta') process.stdout.write(part.delta);
+  if (part.type === 'text-delta') process.stdout.write(part.payload.delta);
 }
 await handle;
 ```
@@ -260,7 +260,7 @@ See [standalone-agent.ts](../examples/agents/standalone-agent.ts) (Example 4) fo
 - `AgentConfig` — Agent configuration returned by `defineAgent`
 - `Route`, `RoutingPolicy` — Routing declarations on an agent
 - `Flow`, `FlowNode` — Flow graph types from `defineFlow` and node builders
-- `HarnessStreamPart` — Stream event union (`text-delta`, `handoff`, `flow-transition`, etc.)
+- `StreamPart` — Stream event union (`text-delta`, `handoff`, `flow-transition`, etc.)
 - `TurnHandle` — Return value of `runtime.run`; async iterable via `.events`
 - `ToolExecutionOptions`, `ToolExecutionContext` — Tool execution context
 - `getRuntimeFromContext()` — Read runtime from tool context when available

package/guides/FLOWS.md

@@ -57,7 +57,7 @@ const agent = defineAgent({
 const runtime = createRuntime({ agents: [agent], defaultAgentId: 'booking' });
 const handle = runtime.run({ input: 'Hi', sessionId: 'demo' });
 for await (const part of handle.events) {
-  if (part.type === 'text-delta') process.stdout.write(part.delta);
+  if (part.type === 'text-delta') process.stdout.write(part.payload.delta);
 }
 await handle;
 ```

package/guides/GETTING_STARTED.md

@@ -52,7 +52,7 @@ const runtime = createRuntime({
 
 const handle = runtime.run({ input: 'Hello there', sessionId: 'demo' });
 for await (const part of handle.events) {
-  if (part.type === 'text-delta') process.stdout.write(part.delta);
+  if (part.type === 'text-delta') process.stdout.write(part.payload.delta);
 }
 await handle;
 ```

package/guides/RUNTIME.md

@@ -11,7 +11,7 @@
 
 ## Stream Events
 
-`runtime.run()` returns a `TurnHandle` with an `.events` async iterable of `HarnessStreamPart` items.
+`runtime.run()` returns a `TurnHandle` with an `.events` async iterable of `StreamPart` items.
 
 ### Web UI (AI SDK native, 0.5.0+)
 
@@ -24,29 +24,29 @@ return handle.toUIMessageStreamResponse({ sessionId });
 
 Kuralle orchestration events map to typed `data-kuralle-*` parts (see `docs/adr/0005-ai-sdk-native-uimessage-default.md`). Import `KuralleUIMessage` for compile-time-safe `message.parts`.
 
-With `@kuralle-agents/hono-server`, `POST /api/chat/sse` defaults to this native wire. Append `?format=raw` for legacy `HarnessStreamPart` JSON-SSE.
+With `@kuralle-agents/hono-server`, `POST /api/chat/sse` defaults to this native wire. Append `?format=raw` for legacy `StreamPart` JSON-SSE.
 
-### Direct `HarnessStreamPart` consumption
+### Direct `StreamPart` consumption
 
-For CLI scripts, cascaded voice, messaging, or custom transports, iterate `handle.events` directly. Typical usage renders `text-delta` chunks via `part.delta`.
+For CLI scripts, messaging, or custom transports, iterate `handle.events` directly. Every part has `{ channel, type, payload }`; render `text-delta` chunks via `part.payload.delta`.
 
 Common types:
-- `text-delta`
-- `tool-call`, `tool-result`, `tool-error`
+- `text-start`, `text-delta`, `text-end`, `text-cancel`
+- `tool-call`, `tool-result`
 - `handoff`
-- `node-enter`, `flow-transition`, `flow-end`
+- `flow-enter`, `node-enter`, `node-exit`, `flow-transition`, `flow-end`
 - `custom` (flow/runtime emitted app events)
-- `agent-start`, `agent-end`
 - `turn-end`, `done`, `error`
+- `knowledge-cache-hit`, `knowledge-cache-miss`, `knowledge-search`, `knowledge-quality-check`, `knowledge-reformulation`
 
-Internal events can expose operational details. Treat them as privileged data.
+Use `PART_CHANNEL` or the envelope's `channel` field to distinguish client events from privileged internal events.
 
 ## Stream Callback (Persistence Defaults)
 
 Use `streamCallback` when sending runtime events to file/webhook/DB/queue sinks.
 
 Default behavior is message-oriented:
-- emits: `input`, `done`, `error`, `tripwire`, `tool-call`, `tool-result`, `tool-error`, `flow-transition`, `handoff`
+- emits terminal events plus configured tool and transition events
 - does not emit `text-delta` tokens unless enabled
 - attaches final assistant text as `fullText` on terminal events
 - if no sink is configured, adapter is a no-op
@@ -95,7 +95,6 @@ To prevent internal runtime state from leaking into the model's context window:
 
 Runtime checkpoints session state automatically on critical events:
 - `tool-result`
-- `tool-error`
 - `flow-transition`
 - handoff state updates (after `activeAgentId` mutation)
 
@@ -135,21 +134,27 @@ const runtime = createRuntime({
   ],
   hooks: {
     onStreamPart: async (ctx, part) => {
-      if (part.type === 'error') console.error(part.error);
+      if (part.type === 'error') console.error(part.payload.error);
     },
   },
 });
 ```
 
-## Hooks
+## Tracing
 
-Use hooks for logging, metrics, and audit trails without polluting prompts.
+Use a trace sink for logging, metrics, and audit trails without polluting prompts.
 
 ```ts
+const loggingSink: TraceSink = {
+  write(span) {
+    console.log(JSON.stringify(span));
+  },
+};
+
 const runtime = createRuntime({
   agents,
   defaultAgentId: 'router',
-  hooks: loggingHooks(),
+  tracing: { sinks: [loggingSink] },
 });
 ```
 

package/guides/TOOLS.md

@@ -152,7 +152,7 @@ const handle = runtime.run({
   sessionId: 'demo',
 });
 for await (const part of handle.events) {
-  if (part.type === 'text-delta') process.stdout.write(part.delta);
+  if (part.type === 'text-delta') process.stdout.write(part.payload.delta);
 }
 await handle;
 ```

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/core"
   },
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "A framework for structured conversational AI agents",
   "publishConfig": {
     "access": "public"
@@ -32,10 +32,6 @@
       "types": "./dist/runtime/index.d.ts",
       "default": "./dist/runtime/index.js"
     },
-    "./hooks": {
-      "types": "./dist/hooks/index.d.ts",
-      "default": "./dist/hooks/index.js"
-    },
     "./guards": {
       "types": "./dist/guards/index.d.ts",
       "default": "./dist/guards/index.js"
@@ -91,10 +87,6 @@
     "./capabilities": {
       "types": "./dist/capabilities/index.d.ts",
       "default": "./dist/capabilities/index.js"
-    },
-    "./realtime": {
-      "types": "./dist/realtime/index.d.ts",
-      "default": "./dist/realtime/index.js"
     }
   },
   "peerDependencies": {
@@ -111,8 +103,7 @@
     "typescript": "^5.3.0",
     "vitest": "^3.2.4",
     "zod": "^4.0.0",
-    "@kuralle-agents/fs": "0.13.0",
-    "@kuralle-agents/realtime-audio": "0.13.0"
+    "@kuralle-agents/fs": "0.14.1"
   },
   "dependencies": {
     "chrono-node": "^2.6.0"
@@ -131,7 +122,6 @@
     "smoke:flow": "bun test ./test/core-flow/flow.smoke.ts",
     "smoke:agent": "bun test ./test/core-agent/agent.smoke.ts",
     "smoke:approval": "bun test ./test/core-policy/approval.smoke.ts",
-    "smoke:knowledge": "bun test ./test/core-grounding/knowledge.smoke.ts",
-    "smoke:realtime": "bun test ./test/core-voice/realtime.smoke.ts"
+    "smoke:knowledge": "bun test ./test/core-grounding/knowledge.smoke.ts"
   }
 }

package/dist/foundation/AgentDefinition.d.ts

@@ -1,17 +0,0 @@
-import type { PromptTemplate } from '../prompts/types.js';
-import type { AgentPrompt } from '../prompts/AgentPrompt.js';
-/**
- * Shared agent definition — the minimal shape every engine needs.
- * Both Runtime (text) and VoiceEngine (audio) extend this.
- *
- * Define agents once against this interface, then spread into
- * engine-specific configs to add model, voice, processors, etc.
- */
-export interface AgentDefinition {
-    id: string;
-    name: string;
-    description?: string;
-    /** Agent prompt — a plain string, PromptTemplate, or structured AgentPrompt. */
-    prompt?: string | PromptTemplate | AgentPrompt;
-    tools?: Record<string, unknown>;
-}

package/dist/foundation/ConversationEventLog.d.ts

@@ -1,71 +0,0 @@
-import type { HarnessStreamPart, RunContext, Session } from '../types/index.js';
-/**
- * Discriminated union of conversation-level events for the runtime event log.
- * Stored in session workingMemory for observability.
- */
-export type ConversationEvent = {
-    type: 'user';
-    text: string;
-    userId?: string;
-    timestamp: Date;
-} | {
-    type: 'assistant';
-    text: string;
-    timestamp: Date;
-} | {
-    type: 'tool-call';
-    toolCallId: string;
-    toolName: string;
-    args: unknown;
-    timestamp: Date;
-} | {
-    type: 'tool-result';
-    toolCallId: string;
-    toolName: string;
-    result: unknown;
-    timestamp: Date;
-} | {
-    type: 'tool-error';
-    toolCallId: string;
-    toolName: string;
-    error: string;
-    timestamp: Date;
-} | {
-    type: 'handoff';
-    from: string;
-    to: string;
-    reason?: string;
-    timestamp: Date;
-} | {
-    type: 'flow-transition';
-    from: string;
-    to: string;
-    timestamp: Date;
-} | {
-    type: 'error';
-    error: string;
-    timestamp: Date;
-};
-/**
- * Records conversation events into session working memory and manages checkpointing.
- * Shared by Runtime and VoiceEngine.
- */
-export interface ConversationEventLog {
-    /**
-     * Record a stream part into the session's runtime event log.
-     * Text-deltas are accumulated; terminal events flush the assistant text.
-     */
-    record(context: RunContext, part: HarnessStreamPart): void;
-    /**
-     * Persist the session as a checkpoint (called after significant events).
-     */
-    checkpoint(session: Session): Promise<void>;
-    /**
-     * Whether a given stream part type should trigger a checkpoint save.
-     */
-    shouldCheckpoint(part: HarnessStreamPart): boolean;
-    /**
-     * Clean up transient state (e.g., accumulated assistant text) from the session.
-     */
-    cleanup(session: Session): void;
-}

package/dist/foundation/ConversationEventLog.js

@@ -1 +0,0 @@
-export {};

package/dist/foundation/ConversationState.d.ts

@@ -1,33 +0,0 @@
-import type { ChannelId, Session, WorkingMemory } from '../types/index.js';
-import type { ModelMessage } from 'ai';
-/**
- * Manages session lifecycle: load, save, delete, message append, turn counting.
- * Shared by Runtime and VoiceEngine.
- */
-export interface ConversationState {
-    /** Load an existing session or create a new one. */
-    load(sessionId: string, userId?: string): Promise<Session>;
-    /** Persist session to the backing store. */
-    save(session: Session): Promise<void>;
-    /** Delete a session from the backing store. */
-    delete(sessionId: string): Promise<void>;
-    /** Get a WorkingMemory wrapper for the session. */
-    workingMemory(session: Session): WorkingMemory;
-    /** Append a user message to the session history. */
-    appendUserMessage(session: Session, text: string): void;
-    /** Append an assistant message to the session history. */
-    appendAssistantMessage(session: Session, text: string): void;
-    /** Append a raw ModelMessage to the session history. */
-    appendMessage(session: Session, message: ModelMessage): void;
-    /** Get the current turn number for the session. */
-    getSessionTurn(session: Session): number;
-    /** Increment and return the new turn number. */
-    bumpSessionTurn(session: Session): number;
-    /** Update the session's updatedAt timestamp. */
-    touchSession(session: Session): void;
-    /** Create a fresh session with defaults. */
-    createSession(id: string, defaultAgentId: string, userId?: string, opts?: {
-        channelId?: ChannelId;
-        conversationId?: string;
-    }): Session;
-}

package/dist/foundation/ConversationState.js

@@ -1 +0,0 @@
-export {};

package/dist/foundation/DefaultConversationEventLog.d.ts

@@ -1,27 +0,0 @@
-import type { HarnessStreamPart, RunContext, Session } from '../types/index.js';
-import type { SessionStore } from '../session/SessionStore.js';
-import type { ConversationEventLog } from './ConversationEventLog.js';
-export interface DefaultConversationEventLogConfig {
-    sessionStore: SessionStore;
-}
-/**
- * Default conversation event log extracted from SessionEventManager + Runtime checkpoint logic.
- *
- * Handles:
- * - Recording stream parts into session working memory
- * - Text-delta accumulation and flush on terminal events
- * - Value truncation at depth 5 for safe serialization
- * - Checkpoint determination and persistence
- */
-export declare class DefaultConversationEventLog implements ConversationEventLog {
-    private sessionStore;
-    constructor(config: DefaultConversationEventLogConfig);
-    record(context: RunContext, part: HarnessStreamPart): void;
-    checkpoint(session: Session): Promise<void>;
-    shouldCheckpoint(part: HarnessStreamPart): boolean;
-    cleanup(session: Session): void;
-    private getSessionTurn;
-    private appendEvent;
-    private flushAssistantText;
-    private toEventLogValue;
-}