@kuralle-agents/core 0.4.0 → 0.5.0

package/README.md

@@ -130,9 +130,18 @@ const runtime = createRuntime({
 });
 ```
 
-## HTTP streaming
+## HTTP streaming (web)
 
-`TurnHandle` exposes `handle.toResponseStream('sse')` for HTTP transports — or use `@kuralle-agents/hono-server` for a ready-made Hono router.
+For React/web consumers, return a native AI SDK `UIMessageStream` — `useChat` works with no bridge:
+
+```ts
+const handle = runtime.run({ input: 'Hello', sessionId: 'demo' });
+return handle.toUIMessageStreamResponse({ sessionId: 'demo' });
+```
+
+Kuralle orchestration events (flow telemetry, safety blocks, interactive choices) arrive as typed `data-kuralle-*` parts. Import `KuralleUIMessage` and `KuralleDataParts` for compile-time-safe `message.parts` and `useChat({ onData })` handlers.
+
+For non-UI consumers (curl, custom transports), use `handle.toResponseStream('sse')` to emit raw `HarnessStreamPart` JSON-SSE. Or use `@kuralle-agents/hono-server` — `POST /api/chat/sse` defaults to native `UIMessageStream`; append `?format=raw` for the legacy wire.
 
 ## Related
 

package/dist/ai-sdk/uiMessageStream.d.ts

@@ -0,0 +1,51 @@
+import { type UIMessage } from 'ai';
+import type { ConversationOutcome } from '../outcomes/types.js';
+import type { ChoiceOption } from '../types/selection.js';
+import type { HarnessStreamPart } from '../types/stream.js';
+export type KuralleMetadata = {
+    sessionId?: string;
+};
+export type KuralleDataParts = {
+    'kuralle-node': {
+        event: 'enter' | 'exit';
+        node: string;
+    };
+    'kuralle-flow': {
+        event: 'enter' | 'transition' | 'end';
+        flow?: string;
+        from?: string;
+        to?: string;
+        reason?: string;
+    };
+    'kuralle-handoff': {
+        targetAgent: string;
+        reason?: string;
+    };
+    'kuralle-interactive': {
+        nodeId: string;
+        prompt: string;
+        options: ChoiceOption[];
+    };
+    'kuralle-safety': {
+        kind: 'safety-blocked' | 'pipeline-validation-block';
+        moderator?: string;
+        rationale: string;
+        userFacingMessage?: string;
+    };
+    'kuralle-outcome': {
+        outcome: ConversationOutcome;
+    };
+    'kuralle-control': {
+        event: 'interrupted' | 'paused';
+        reason?: string;
+        waitingFor?: string;
+    };
+    'kuralle-custom': {
+        name: string;
+        data: unknown;
+    };
+};
+export type KuralleUIMessage = UIMessage<KuralleMetadata, KuralleDataParts>;
+export declare function harnessToUIMessageStream(source: AsyncIterable<HarnessStreamPart>, opts?: {
+    sessionId?: string;
+}): ReadableStream;

package/dist/ai-sdk/uiMessageStream.js

@@ -0,0 +1,164 @@
+import { createUIMessageStream, generateId, } from 'ai';
+function writeHarnessPart(part, writer) {
+    switch (part.type) {
+        case 'text-start':
+            writer.write({ type: 'text-start', id: part.id });
+            break;
+        case 'text-delta':
+            writer.write({ type: 'text-delta', id: part.id, delta: part.delta });
+            break;
+        case 'text-end':
+            writer.write({ type: 'text-end', id: part.id });
+            break;
+        case 'text-cancel':
+            writer.write({ type: 'text-end', id: part.id });
+            break;
+        case 'tool-call':
+            writer.write({
+                type: 'tool-input-available',
+                toolCallId: part.toolCallId ?? generateId(),
+                toolName: part.toolName,
+                input: part.args,
+            });
+            break;
+        case 'tool-result':
+            writer.write({
+                type: 'tool-output-available',
+                toolCallId: part.toolCallId ?? 'unknown',
+                output: part.result,
+            });
+            break;
+        case 'node-enter':
+            writer.write({
+                type: 'data-kuralle-node',
+                data: { event: 'enter', node: part.nodeName },
+                transient: true,
+            });
+            break;
+        case 'node-exit':
+            writer.write({
+                type: 'data-kuralle-node',
+                data: { event: 'exit', node: part.nodeName },
+                transient: true,
+            });
+            break;
+        case 'flow-enter':
+            writer.write({
+                type: 'data-kuralle-flow',
+                data: { event: 'enter', flow: part.flow },
+                transient: true,
+            });
+            break;
+        case 'flow-end':
+            writer.write({
+                type: 'data-kuralle-flow',
+                data: { event: 'end', flow: part.flow, reason: part.reason },
+                transient: true,
+            });
+            break;
+        case 'flow-transition':
+            writer.write({
+                type: 'data-kuralle-flow',
+                data: { event: 'transition', from: part.from, to: part.to },
+                transient: true,
+            });
+            break;
+        case 'handoff':
+            writer.write({
+                type: 'data-kuralle-handoff',
+                id: generateId(),
+                data: { targetAgent: part.targetAgent, reason: part.reason },
+            });
+            break;
+        case 'interactive':
+            writer.write({
+                type: 'data-kuralle-interactive',
+                id: part.nodeId,
+                data: { nodeId: part.nodeId, prompt: part.prompt, options: part.options },
+            });
+            break;
+        case 'safety-blocked':
+            writer.write({
+                type: 'data-kuralle-safety',
+                id: generateId(),
+                data: {
+                    kind: 'safety-blocked',
+                    moderator: part.moderator,
+                    rationale: part.rationale,
+                    userFacingMessage: part.userFacingMessage,
+                },
+            });
+            break;
+        case 'pipeline-validation-block':
+            writer.write({
+                type: 'data-kuralle-safety',
+                id: generateId(),
+                data: {
+                    kind: 'pipeline-validation-block',
+                    rationale: part.rationale,
+                    userFacingMessage: part.userFacingMessage,
+                },
+            });
+            break;
+        case 'conversation-outcome':
+            writer.write({
+                type: 'data-kuralle-outcome',
+                id: generateId(),
+                data: { outcome: part.outcome },
+            });
+            break;
+        case 'interrupted':
+            writer.write({
+                type: 'data-kuralle-control',
+                data: { event: 'interrupted', reason: part.reason },
+                transient: true,
+            });
+            break;
+        case 'paused':
+            writer.write({
+                type: 'data-kuralle-control',
+                data: { event: 'paused', waitingFor: part.waitingFor },
+                transient: true,
+            });
+            break;
+        case 'custom':
+            writer.write({
+                type: 'data-kuralle-custom',
+                data: { name: part.name, data: part.data },
+                transient: true,
+            });
+            break;
+        case 'error':
+            throw new Error(part.error);
+        case 'done':
+        case 'turn-end':
+            break;
+    }
+}
+export function harnessToUIMessageStream(source, opts) {
+    return createUIMessageStream({
+        execute: async ({ writer }) => {
+            let doneSessionId = opts?.sessionId;
+            if (doneSessionId) {
+                writer.write({
+                    type: 'start',
+                    messageMetadata: { sessionId: doneSessionId },
+                });
+            }
+            for await (const part of source) {
+                if (part.type === 'done' && part.sessionId) {
+                    doneSessionId = doneSessionId ?? part.sessionId;
+                }
+                else {
+                    writeHarnessPart(part, writer);
+                }
+            }
+            if (doneSessionId) {
+                writer.write({
+                    type: 'finish',
+                    messageMetadata: { sessionId: doneSessionId },
+                });
+            }
+        },
+    });
+}

package/dist/events/TurnHandle.js

@@ -1,3 +1,5 @@
+import { createUIMessageStreamResponse } from 'ai';
+import { harnessToUIMessageStream } from '../ai-sdk/uiMessageStream.js';
 export function createEventBus() {
     const events = [];
     const waiters = [];
@@ -48,6 +50,11 @@ export function createTurnHandle(options) {
         toResponseStream(format = 'sse') {
             return createResponseStream(bus.events(), format);
         },
+        toUIMessageStreamResponse(opts) {
+            return createUIMessageStreamResponse({
+                stream: harnessToUIMessageStream(bus.events(), opts),
+            });
+        },
         cancel(reason) {
             abortController.abort(reason);
             bus.close();

package/dist/flow/collectDigression.js

@@ -76,11 +76,6 @@ export async function runCollectDigression(options) {
     };
     const turn = await driver.runAgentTurn(resolveReplyNode(replyNode, run.state, { freeConversation: true }), ctx);
     if (turn.text.trim()) {
-        const id = crypto.randomUUID();
-        ctx.emit({ type: 'text-start', id });
-        ctx.emit({ type: 'text-delta', id, delta: turn.text });
-        ctx.emit({ type: 'text-end', id });
-        ctx.emit({ type: 'turn-end' });
         appendAssistantMessage(run, turn.text);
     }
     if (turn.control?.type === 'handoff') {

package/dist/index.d.ts

@@ -77,6 +77,8 @@ 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 { harnessToUIMessageStream } from './ai-sdk/uiMessageStream.js';
+export type { KuralleMetadata, KuralleDataParts, KuralleUIMessage, } from './ai-sdk/uiMessageStream.js';
 export type { ChoiceOption, ResolvedSelection } from './types/selection.js';
 export type { RunState, StepRecord } from './runtime/durable/types.js';
 export type { RunStore } from './runtime/durable/RunStore.js';

package/dist/index.js

@@ -40,4 +40,5 @@ export { defineAgent, defineFlow, reply, collect, action, decide, confirmGate, }
 export { defineTool } from './types/effectTool.js';
 export { buildToolSet, toolToAiSdk, ToolApprovalDeniedError, ToolTimeoutError, } from './tools/effect/index.js';
 export { parseConfirmation } from './flow/confirmParse.js';
+export { harnessToUIMessageStream } from './ai-sdk/uiMessageStream.js';
 export { createRuntime, Runtime, } from './runtime/Runtime.js';

package/dist/testing/mocks.js

@@ -1,7 +1,14 @@
+import { createUIMessageStreamResponse } from 'ai';
+import { harnessToUIMessageStream } from '../ai-sdk/uiMessageStream.js';
 export function createMockTurnHandle(events, settled = { text: '', toolResults: [] }) {
     return Object.assign(Promise.resolve(settled), {
         events,
         toResponseStream: () => new ReadableStream(),
+        toUIMessageStreamResponse(opts) {
+            return createUIMessageStreamResponse({
+                stream: harnessToUIMessageStream(events, opts),
+            });
+        },
         cancel: () => { },
     });
 }

package/dist/types/stream.d.ts

@@ -91,5 +91,8 @@ export type HarnessStreamPart = {
 export interface TurnHandle extends Promise<import('./channel.js').TurnResult> {
     readonly events: AsyncIterable<HarnessStreamPart>;
     toResponseStream(format?: 'sse' | 'ndjson'): ReadableStream;
+    toUIMessageStreamResponse(opts?: {
+        sessionId?: string;
+    }): Response;
     cancel(reason?: string): void;
 }

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.text);
+  if (part.type === 'text-delta') process.stdout.write(part.delta);
 }
 await handle;
 ```
@@ -225,7 +225,7 @@ const handle = runtime.run({
   sessionId: 'demo',
 });
 for await (const part of handle.events) {
-  if (part.type === 'text-delta') process.stdout.write(part.text);
+  if (part.type === 'text-delta') process.stdout.write(part.delta);
 }
 await handle;
 ```

package/guides/FLOWS.md

@@ -60,7 +60,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.text);
+  if (part.type === 'text-delta') process.stdout.write(part.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.text);
+  if (part.type === 'text-delta') process.stdout.write(part.delta);
 }
 await handle;
 ```

package/guides/RUNTIME.md

@@ -11,7 +11,24 @@
 
 ## Stream Events
 
-`runtime.run()` returns a `TurnHandle` with an `.events` async iterable of `HarnessStreamPart` items. Typical UI usage only renders `text-delta`.
+`runtime.run()` returns a `TurnHandle` with an `.events` async iterable of `HarnessStreamPart` items.
+
+### Web UI (AI SDK native, 0.5.0+)
+
+For React/web consumers, return a native `UIMessageStream` — `useChat` works with no bridge:
+
+```ts
+const handle = runtime.run({ input, sessionId });
+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.
+
+### Direct `HarnessStreamPart` consumption
+
+For CLI scripts, cascaded voice, messaging, or custom transports, iterate `handle.events` directly. Typical usage renders `text-delta` chunks via `part.delta`.
 
 Common types:
 - `text-delta`

package/guides/TOOLS.md

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

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/kuralle-core"
   },
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A framework for structured conversational AI agents",
   "publishConfig": {
     "access": "public"
@@ -97,7 +97,7 @@
     "dotenv": "^16.4.0",
     "typescript": "^5.3.0",
     "zod": "^3.23.0",
-    "@kuralle-agents/realtime-audio": "0.4.0"
+    "@kuralle-agents/realtime-audio": "0.5.0"
   },
   "dependencies": {
     "chrono-node": "^2.6.0",