@kuralle-agents/core 0.12.0 → 0.14.0

package/dist/types/runtime.d.ts

@@ -1,10 +1,6 @@
-import type { ModelMessage } from 'ai';
-import type { SessionEndMetadata, TurnUsage } from './telemetry.js';
-import type { AgentStreamPart } from './processors.js';
-import type { AgentContext, RunContext, Session, ToolCallRecord } from './session.js';
-import type { HarnessStreamPart } from './voice.js';
+import type { AgentContext, RunContext } from './session.js';
+import type { StreamPart } from './stream.js';
 import type { RefineDecision, ValidateDecision } from '../capabilities/index.js';
-import type { ConversationOutcome, ConversationOutcomeRecord } from '../outcomes/types.js';
 import type { ChannelId } from './session.js';
 export interface RefinementStageResult {
     proceed: boolean;
@@ -24,7 +20,7 @@ export interface Hook {
     name: string;
     onTurnStart?: (ctx: AgentContext, input: string) => Promise<void>;
     onTurnEnd?: (ctx: AgentContext) => Promise<void>;
-    onStreamPart?: (ctx: AgentContext, part: AgentStreamPart) => Promise<void>;
+    onStreamPart?: (ctx: AgentContext, part: StreamPart) => Promise<void>;
     onAgentSwitch?: (ctx: AgentContext, from: string, to: string) => Promise<void>;
     onError?: (ctx: AgentContext, error: Error) => Promise<void>;
 }
@@ -36,73 +32,6 @@ export interface StopCondition {
     name: string;
     check: (context: RunContext) => StopConditionResult;
 }
-export interface StepResult {
-    text?: string;
-    toolCalls: ToolCallRecord[];
-    finishReason: string;
-    tokensUsed: number;
-    handoffTo?: string;
-}
-export interface TurnSummary {
-    sessionId: string;
-    userId?: string;
-    agentId: string;
-    messageCount: number;
-    toolCallCount: number;
-    totalTokens: number;
-}
-export interface TurnEndHookResult {
-    outcome?: ConversationOutcome;
-    reason?: string;
-}
-export interface HarnessHooks {
-    onStart?: (context: RunContext) => Promise<void>;
-    onEnd?: (context: RunContext, result: {
-        success: boolean;
-        error?: Error;
-    }) => Promise<void>;
-    onStepStart?: (context: RunContext, step: number) => Promise<void>;
-    onStepEnd?: (context: RunContext, step: number, result: StepResult) => Promise<void>;
-    onToolCall?: (context: RunContext, call: ToolCallRecord) => Promise<void>;
-    onToolResult?: (context: RunContext, call: ToolCallRecord) => Promise<void>;
-    onToolError?: (context: RunContext, call: ToolCallRecord, error: Error) => Promise<void>;
-    onTurnEnd?: (context: RunContext, summary: TurnSummary) => Promise<TurnEndHookResult | void>;
-    onAgentStart?: (context: RunContext, agentId: string) => Promise<void>;
-    onAgentEnd?: (context: RunContext, agentId: string) => Promise<void>;
-    onHandoff?: (context: RunContext, from: string, to: string, reason: string) => Promise<void>;
-    onError?: (context: RunContext, error: Error) => Promise<void>;
-    onMessage?: (context: RunContext, message: ModelMessage) => Promise<void>;
-    onStreamPart?: (context: RunContext, part: HarnessStreamPart) => Promise<void>;
-    onPersistenceError?: (session: Session, error: Error) => Promise<void>;
-    onMemoryIngest?: (context: RunContext, session: Session) => Promise<boolean | void>;
-    onMemoryIngested?: (context: RunContext, session: Session) => Promise<void>;
-    onBeforeModelCall?: (context: RunContext, data: BeforeModelCallData) => Promise<BeforeModelCallResult | void>;
-    onSessionEnd?: (session: Session, metadata: SessionEndMetadata) => Promise<void>;
-    onConversationEnd?: (session: Session, outcome: ConversationOutcomeRecord) => Promise<{
-        csatInvited: boolean;
-        csatChannel?: 'email' | 'in-app' | 'sms';
-    } | void>;
-    onTokensUpdate?: (context: RunContext, turn: TurnUsage) => Promise<void> | void;
-}
-export interface BeforeModelCallData {
-    systemPrompt: string;
-    messages: ModelMessage[];
-    estimatedTokens: number;
-    agentId: string;
-    tokenBreakdown: {
-        basePrompt: number;
-        autoRetrieve: number;
-        workingMemory: number;
-        extraction: number;
-        longTermMemory: number;
-        policyInjections: number;
-        messageHistory: number;
-    };
-}
-export interface BeforeModelCallResult {
-    systemPrompt?: string;
-    messages?: ModelMessage[];
-}
 export interface StreamOptions {
     input: string;
     sessionId?: string;

package/dist/types/session.d.ts

@@ -1,11 +1,19 @@
 import type { ModelMessage } from 'ai';
-import type { RetrievalCacheAdapter } from './voice.js';
+import type { RetrievalCacheAdapter } from './knowledge.js';
 import type { RefinementStageResult } from './runtime.js';
 import type { EscalationReason, EscalationOutcome } from '../escalation/types.js';
 import type { ConversationOutcomeRecord, CsatRecord } from '../outcomes/types.js';
 import type { PersonaExperimentMetadata } from '../persona/types.js';
 import type { ConversationAuditEntry } from '../audit/types.js';
 export type ChannelId = 'web' | 'email' | 'sms' | 'voice' | 'api' | 'slack' | 'discord' | (string & {});
+/** Structured goal/thread entry on session.workingMemory.__goals (G5). */
+export type GoalStatus = 'open' | 'resolved';
+export interface TrackedGoal {
+    topic: string;
+    status: GoalStatus;
+    lastTurn: number;
+    note?: string;
+}
 export interface WorkingMemory {
     get<T>(key: string): T | undefined;
     set<T>(key: string, value: T): void;
@@ -42,6 +50,8 @@ export interface Session {
     pendingRefinement?: RefinementStageResult;
     /** @internal Pending key-facts extraction promises. Awaited before session save. */
     __pendingExtractions?: Promise<void>[];
+    /** Optimistic-concurrency version; must match the stored row on save (C2 CAS). */
+    version?: number;
 }
 export interface SessionMetadata {
     createdAt: Date;

package/dist/types/skills.d.ts

@@ -16,4 +16,18 @@ export interface SkillStoreLike {
     getAllSkills?(): SkillLike[] | Promise<SkillLike[]>;
     loadAllSkills?(): Promise<SkillLike[]>;
 }
-export type SkillSource = SkillLike | SkillLike[] | SkillStoreLike;
+/**
+ * One way to supply skills. A `string` is a filesystem root scanned for
+ * `<dir>/SKILL.md`, resolved against the agent's `workspace` filesystem.
+ */
+export type SkillEntry = SkillLike | SkillStoreLike | string;
+/**
+ * Skills for an agent: one entry, or an ordered array mixing inline skills, stores, and
+ * workspace paths. **Later entries win** on a name collision, so layering reads in the
+ * order you write it:
+ *
+ * ```ts
+ * skills: ['/skills/org', '/skills/team', defineSkill({ name: 'override', … })]
+ * ```
+ */
+export type SkillSource = SkillEntry | ReadonlyArray<SkillEntry>;

package/dist/types/stream.d.ts

@@ -1,127 +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;
-};
+    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

@@ -0,0 +1,52 @@
+export type SpanKind = 'turn' | 'flow' | 'node' | 'tool' | 'handoff' | 'llm';
+export interface AgentSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: SpanKind;
+    startTime: number;
+    endTime?: number;
+    status: 'ok' | 'error';
+    events?: Array<{
+        name: string;
+        time: number;
+        attributes?: Record<string, unknown>;
+    }>;
+    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;
+        handoffFrom?: string;
+        handoffTo?: string;
+        input?: unknown;
+        output?: unknown;
+        error?: string;
+        /** Input tokens consumed by this turn (delta — for cost attribution). */
+        tokensIn?: number;
+        /** Output tokens generated by this turn (delta — for cost attribution). */
+        tokensOut?: number;
+        /** Context-window occupancy at this turn (last prompt tokens — a snapshot, not a delta). */
+        contextTokens?: number;
+    };
+}
+export interface AgentTrace {
+    traceId: string;
+    sessionId: string;
+    spans: AgentSpan[];
+    answer: string;
+    usedTool: boolean;
+    toolCalls: Array<{
+        name: string;
+        args: unknown;
+    }>;
+    toolResults: Array<{
+        name: string;
+        result: unknown;
+    }>;
+    startedAt: number;
+    endedAt?: number;
+}

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/EXAMPLE_VERIFICATION.md

@@ -8,8 +8,8 @@ This verification was run after runtime policy-profile changes to check for regr
 
 Covered suites:
 
-1. `packages/kuralle-core/examples/agents` (Line parity set)
-2. `packages/kuralle-core/examples/flows` (Pipecat parity set)
+1. `packages/core/examples/agents` (Line parity set)
+2. `packages/core/examples/flows` (Pipecat parity set)
 3. Extended package examples (`kuralle-tools`, `kuralle-redis-store`)
 
 ## Results
@@ -30,8 +30,8 @@ Interpretation:
 
 Non-pass items:
 
-1. `packages/kuralle-redis-store/examples/local-redis/test.ts` -> `SKIPPED`
-2. `packages/kuralle-redis-store/examples/local-redis/multi-turn.ts` -> `SKIPPED`
+1. `packages/redis-store/examples/local-redis/test.ts` -> `SKIPPED`
+2. `packages/redis-store/examples/local-redis/multi-turn.ts` -> `SKIPPED`
    - Cause: local Redis was not started.
 
 ## Verdict

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;
 ```