@kuralle-agents/hono-server 0.4.1 → 0.5.0

package/README.md

@@ -5,24 +5,74 @@ Hono router that exposes a Kuralle `Runtime` over HTTP, SSE, and WebSocket.
 ## Install
 
 ```bash
-npm install @kuralle-agents/hono-server @kuralle-agents/core
+npm install @kuralle-agents/hono-server @kuralle-agents/core ai
 ```
 
-Peer: `@kuralle-agents/core`.
+Peers: `@kuralle-agents/core`, `ai@^6`.
 
 ## What it does
 
 `createKuralleChatRouter` mounts a complete set of endpoints onto a Hono app — HTTP chat, SSE streaming, WebSocket widget, session management, audit, CSAT, and a manual compression trigger — wired to any `RuntimeLike` instance.
 
+**As of 0.5.0, `POST /api/chat/sse` defaults to an AI SDK `UIMessageStream`** — a `useChat` client works with zero bridge code. Raw `HarnessStreamPart` JSON-SSE is opt-in via `?format=raw`.
+
 **Key exports:**
 
-- **`createKuralleChatRouter`** — full router: chat, SSE, WebSocket, session, outcome, audit endpoints.
-- **`createKuralleSseChatRouter`** — SSE-only variant for simpler setups.
+- **`createKuralleChatRouter`** — full router: chat, SSE (native default), WebSocket, session, outcome, audit endpoints.
+- **`createKuralleSseChatRouter`** — raw JSON-SSE only (explicit legacy wire).
 - **`createOpenAICompatRouter`** — OpenAI-compatible `/v1/chat/completions` endpoint.
 - **`createKuralleRouter`** — standalone router for flow-manager instances.
 - **`shouldEmit` / `sanitizeForClient`** — stream event filter utilities.
 
-## Usage
+## Web client (`useChat`, no bridge)
+
+```tsx
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import type { KuralleUIMessage } from '@kuralle-agents/core';
+
+export function Chat() {
+  const { messages, sendMessage } = useChat<KuralleUIMessage>({
+    api: '/api/chat/sse',
+    onData: (part) => {
+      // transient telemetry (node/flow/control) — not persisted to message.parts
+      if (part.type === 'data-kuralle-node') {
+        console.log('node:', part.data);
+      }
+    },
+  });
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>
+          {m.parts.map((part, i) => {
+            if (part.type === 'text') return <span key={i}>{part.text}</span>;
+            if (part.type === 'data-kuralle-safety') {
+              return <div key={i}>Blocked: {part.data.userFacingMessage}</div>;
+            }
+            if (part.type === 'data-kuralle-interactive') {
+              return (
+                <div key={i}>
+                  {part.data.options.map((o) => (
+                    <button key={o.value} onClick={() => sendMessage({ text: o.value })}>
+                      {o.label}
+                    </button>
+                  ))}
+                </div>
+              );
+            }
+            return null;
+          })}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+Server:
 
 ```ts
 import { Hono } from 'hono';
@@ -48,22 +98,27 @@ const server = serve({ fetch: app.fetch, port: 3000 });
 injectWebSocket(server);
 ```
 
-**Bun:**
+`POST /api/chat/sse` accepts `useChat`-shaped bodies (`{ messages: UIMessage[] }`) and returns a native `UIMessageStream`. No `HarnessStreamPart` → `UIMessageChunk` bridge required.
 
-```ts
-import { upgradeWebSocket } from 'hono/bun';
+## Raw JSON-SSE (`?format=raw`)
 
-app.route('/', createKuralleChatRouter({ runtime, upgradeWebSocket }));
-export default app;
+Non-UI consumers (curl, Studio, custom transports) that parsed raw `HarnessStreamPart` JSON from 0.4.x should append `?format=raw`:
+
+```bash
+curl -N -X POST 'http://localhost:3000/api/chat/sse?format=raw' \
+  -H 'Content-Type: application/json' \
+  -d '{"message":"hello","sessionId":"demo"}'
 ```
 
-## Endpoints (createKuralleChatRouter)
+Or use `createKuralleSseChatRouter` for a router that always emits raw JSON-SSE on `/api/chat/sse`.
+
+## Endpoints (`createKuralleChatRouter`)
 
 | Method | Path | Description |
 |--------|------|-------------|
 | `POST` | `/api/chat` | Single-turn JSON response |
-| `POST` | `/api/chat/sse` | SSE streaming response |
-| `POST` | `/api/chat/stream` | Chunked text stream |
+| `POST` | `/api/chat/sse` | **Default:** AI SDK `UIMessageStream` (`useChat`). **`?format=raw`:** legacy `HarnessStreamPart` JSON-SSE |
+| `POST` | `/api/chat/stream` | Chunked plain-text stream |
 | `GET`  | `/agents/chat/:sessionId` | WebSocket widget endpoint |
 | `GET`  | `/ws/:sessionId` | WebSocket turn endpoint |
 | `GET`  | `/api/session/:id` | Fetch session |
@@ -100,7 +155,10 @@ createKuralleChatRouter({
 });
 ```
 
+Applies to raw JSON-SSE (`?format=raw`) and WebSocket paths. The native `UIMessageStream` default passes through the adapter unfiltered.
+
 ## Related
 
-- [`@kuralle-agents/core`](https://www.npmjs.com/package/@kuralle-agents/core) — runtime and agent primitives.
+- [`@kuralle-agents/core`](https://www.npmjs.com/package/@kuralle-agents/core) — runtime, `harnessToUIMessageStream`, `KuralleUIMessage`.
 - [`@kuralle-agents/cf-agent`](https://www.npmjs.com/package/@kuralle-agents/cf-agent) — Cloudflare Workers variant.
+- `docs/adr/0005-ai-sdk-native-uimessage-default.md` — decision record and `data-kuralle-*` mapping table.

package/dist/index.js

@@ -1,5 +1,7 @@
+import { createUIMessageStreamResponse } from 'ai';
 import { Hono } from 'hono';
 import { streamSSE } from 'hono/streaming';
+import { harnessToUIMessageStream } from '@kuralle-agents/core';
 // PR-20 — re-export the OpenAI-compatible router. Lets consumers do:
 //   import { createOpenAICompatRouter } from '@kuralle-agents/hono-server';
 export { createOpenAICompatRouter, } from './openaiCompat.js';
@@ -15,6 +17,7 @@ const parseJsonBody = async (c) => {
         return null;
     }
 };
+const wantsRawStreamFormat = (c) => c.req.query('format') === 'raw';
 const extractInputFromBody = (body) => {
     if (typeof body.message === 'string') {
         return { input: body.message, sessionId: body.sessionId };
@@ -23,9 +26,15 @@ const extractInputFromBody = (body) => {
         const messages = body.messages;
         const lastMessage = messages[messages.length - 1];
         if (lastMessage.parts && Array.isArray(lastMessage.parts)) {
-            const textPart = lastMessage.parts.find((p) => p.type === 'text');
-            const input = textPart?.text || '';
-            const sessionId = typeof body.id === 'string' ? body.id : undefined;
+            const input = lastMessage.parts
+                .filter((p) => p.type === 'text')
+                .map((p) => p.text ?? '')
+                .join('');
+            const sessionId = typeof body.sessionId === 'string'
+                ? body.sessionId
+                : typeof body.id === 'string'
+                    ? body.id
+                    : undefined;
             return { input, sessionId };
         }
     }
@@ -202,30 +211,42 @@ export const createKuralleChatRouter = ({ runtime, upgradeWebSocket, widgetWelco
     });
     app.post('/api/chat/sse', async (c) => {
         const body = await parseJsonBody(c);
-        if (!body || !body.message) {
+        if (!body) {
+            return c.json({ error: 'invalid body' }, 400);
+        }
+        const { input, sessionId: bodySessionId } = extractInputFromBody(body);
+        if (!input) {
             return c.json({ error: 'message required' }, 400);
         }
-        return streamSSE(c, async (stream) => {
-            try {
-                for await (const part of iterateRuntimeParts(runtime, {
-                    input: body.message,
-                    sessionId: body.sessionId,
-                    userId: body.userId,
-                })) {
-                    await sendSSEPart(stream, part, streamFilter);
+        const sessionId = bodySessionId ??
+            (typeof body.sessionId === 'string' ? body.sessionId : undefined) ??
+            crypto.randomUUID();
+        const userId = typeof body.userId === 'string' ? body.userId : undefined;
+        if (wantsRawStreamFormat(c)) {
+            return streamSSE(c, async (stream) => {
+                try {
+                    for await (const part of iterateRuntimeParts(runtime, {
+                        input,
+                        sessionId,
+                        userId,
+                    })) {
+                        await sendSSEPart(stream, part, streamFilter);
+                    }
                 }
-            }
-            catch (error) {
-                console.error('[Kuralle] SSE stream error:', error);
-                const message = streamFilter === 'all'
-                    ? error.message
-                    : 'An error occurred. Please try again.';
-                await stream.writeSSE({
-                    event: 'error',
-                    data: JSON.stringify({ error: message }),
-                });
-            }
-        });
+                catch (error) {
+                    console.error('[Kuralle] SSE stream error:', error);
+                    const message = streamFilter === 'all'
+                        ? error.message
+                        : 'An error occurred. Please try again.';
+                    await stream.writeSSE({
+                        event: 'error',
+                        data: JSON.stringify({ error: message }),
+                    });
+                }
+            });
+        }
+        const handle = runtime.run({ input, sessionId, userId });
+        return handle.toUIMessageStreamResponse({ sessionId });
     });
     app.post('/api/chat/resume', async (c) => {
         const body = await parseJsonBody(c);
@@ -647,21 +668,60 @@ export const createKuralleRouter = ({ flowManager, sessionId, upgradeWebSocket,
     });
     app.post('/api/flow/sse', async (c) => {
         const body = await parseJsonBody(c);
-        if (!body || !body.message) {
+        if (!body) {
+            return c.json({ error: 'invalid body' }, 400);
+        }
+        const { input, sessionId: bodySessionId } = extractInputFromBody(body);
+        if (!input) {
             return c.json({ error: 'message required' }, 400);
         }
-        return streamSSE(c, async (stream) => {
-            try {
-                for await (const part of flowManager.process(body.message)) {
-                    await sendFlowSSEPart(stream, part);
+        if (wantsRawStreamFormat(c)) {
+            return streamSSE(c, async (stream) => {
+                try {
+                    for await (const part of flowManager.process(input)) {
+                        await sendFlowSSEPart(stream, part);
+                    }
+                }
+                catch (error) {
+                    await stream.writeSSE({
+                        event: 'error',
+                        data: JSON.stringify({ error: error.message }),
+                    });
+                }
+            });
+        }
+        async function* flowHarnessParts() {
+            for await (const part of flowManager.process(input)) {
+                if (part.type === 'text-start' ||
+                    part.type === 'text-delta' ||
+                    part.type === 'text-end' ||
+                    part.type === 'text-cancel' ||
+                    part.type === 'tool-call' ||
+                    part.type === 'tool-result' ||
+                    part.type === 'node-enter' ||
+                    part.type === 'node-exit' ||
+                    part.type === 'flow-enter' ||
+                    part.type === 'flow-transition' ||
+                    part.type === 'flow-end' ||
+                    part.type === 'handoff' ||
+                    part.type === 'interactive' ||
+                    part.type === 'safety-blocked' ||
+                    part.type === 'pipeline-validation-block' ||
+                    part.type === 'conversation-outcome' ||
+                    part.type === 'interrupted' ||
+                    part.type === 'paused' ||
+                    part.type === 'custom' ||
+                    part.type === 'error' ||
+                    part.type === 'done' ||
+                    part.type === 'turn-end') {
+                    yield part;
                 }
             }
-            catch (error) {
-                await stream.writeSSE({
-                    event: 'error',
-                    data: JSON.stringify({ error: error.message }),
-                });
-            }
+        }
+        return createUIMessageStreamResponse({
+            stream: harnessToUIMessageStream(flowHarnessParts(), {
+                sessionId: bodySessionId ?? sessionId,
+            }),
         });
     });
     if (upgradeWebSocket) {

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/kuralle-hono-server"
   },
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Hono router for hosting Kuralle createRuntime() over HTTP, SSE, and WebSocket",
   "type": "module",
   "main": "dist/index.js",
@@ -20,10 +20,10 @@
   "dependencies": {
     "ai": "^6.0.0",
     "hono": "^4.0.0",
-    "@kuralle-agents/core": "0.4.1"
+    "@kuralle-agents/core": "0.5.0"
   },
   "peerDependencies": {
-    "@kuralle-agents/core": "0.4.1"
+    "@kuralle-agents/core": "0.5.0"
   },
   "devDependencies": {
     "@ai-sdk/openai": "^3.0.0",