@cuylabs/agent-http 0.1.6 → 0.5.0

package/README.md

@@ -1,6 +1,14 @@
 # @cuylabs/agent-http
 
-HTTP streaming adapter for [@cuylabs/agent-core](https://github.com/cuylabs-ai/agents-ts/tree/main/packages/agent-core). Bridges agent events to AI SDK v6 UIMessageStream for use with `useChat()`.
+HTTP streaming adapter for [@cuylabs/agent-core](https://github.com/cuylabs-ai/agents-ts/tree/main/packages/agent-core). Bridges agent events to AI SDK v6 `UIMessageStream` for use with `useChat()`.
+
+It maps the UI-facing streaming events (`text-*`, `reasoning-*`, `tool-*`, `error`) and intentionally skips advanced agent-core events that do not have a direct `UIMessageStream` equivalent (`turn-boundary`, `turn-summary`, approvals, interventions, retries, etc.).
+
+This package is intentionally narrow:
+
+- It is a good way to expose an agent over HTTP when your client already speaks the AI SDK v6 chat stream protocol.
+- It is not a full generic agent hosting layer, REST API surface, or control plane.
+- For broader host/runtime concerns, keep those in your app or use the runtime packages.
 
 ## Installation
 
@@ -34,6 +42,12 @@ export async function POST(req: Request) {
   const { messages, id } = await req.json();
   const lastMessage = messages[messages.length - 1];
 
+  if (typeof lastMessage?.content !== "string") {
+    return new Response("agent-http expects a plain text user message", {
+      status: 400,
+    });
+  }
+
   return createAgentStreamResponse(agent, {
     sessionId: id,
     message: lastMessage.content,
@@ -85,9 +99,12 @@ interface AgentStreamOptions {
   message: string;
   abortSignal?: AbortSignal;
   system?: string;
+  onFinish?: (result: { response: string; messageId?: string }) => void | Promise<void>;
 }
 ```
 
+`message` is plain text. If your HTTP route accepts richer UI message parts, convert or validate them before calling `createAgentStreamResponse(...)`.
+
 ### createAgentStream
 
 Lower-level API that returns a ReadableStream.
@@ -99,6 +116,24 @@ function createAgentStream(
 ): ReturnType<typeof createUIMessageStream>;
 ```
 
+Use `createAgentStream(...)` when you need to compose the stream yourself before turning it into a `Response`.
+
+## Boundary
+
+`agent-http` is best thought of as:
+
+- `agent-core` -> AI SDK chat stream adapter
+
+It does not own:
+
+- request parsing
+- auth
+- session storage policy
+- non-AI-SDK wire formats
+- approval or intervention HTTP APIs
+
+If you need a generic HTTP interface for agents, build that at the app layer and treat `createAgentStream(...)` as one rendering option.
+
 ## License
 
 Apache-2.0

package/dist/index.d.ts

@@ -8,6 +8,8 @@ export { createUIMessageStream, createUIMessageStreamResponse } from 'ai';
  *
  * HTTP streaming adapter for @cuylabs/agent-core.
  * Bridges agent events to AI SDK v6 compatible UIMessageStream for use with useChat().
+ * Advanced agent-core events without a direct UIMessageStream equivalent are
+ * intentionally skipped here.
  *
  * @example
  * ```typescript

package/dist/index.js

@@ -9,7 +9,6 @@ function generatePartId() {
 }
 async function writeAgentEventsToStream(agent, options, writer) {
   let currentTextId = null;
-  let currentReasoningId = null;
   let fullResponse = "";
   for await (const event of agent.chat(options.sessionId, options.message, {
     abort: options.abortSignal,
@@ -45,29 +44,23 @@ async function writeAgentEventsToStream(agent, options, writer) {
         break;
       // Reasoning/thinking streaming
       case "reasoning-start":
-        currentReasoningId = generatePartId();
         writer.write({
           type: "reasoning-start",
-          id: currentReasoningId
+          id: event.id
         });
         break;
       case "reasoning-delta":
-        if (currentReasoningId) {
-          writer.write({
-            type: "reasoning-delta",
-            id: currentReasoningId,
-            delta: event.text
-          });
-        }
+        writer.write({
+          type: "reasoning-delta",
+          id: event.id,
+          delta: event.text
+        });
         break;
       case "reasoning-end":
-        if (currentReasoningId) {
-          writer.write({
-            type: "reasoning-end",
-            id: currentReasoningId
-          });
-          currentReasoningId = null;
-        }
+        writer.write({
+          type: "reasoning-end",
+          id: event.id
+        });
         break;
       // Tool invocations
       case "tool-start":
@@ -99,11 +92,14 @@ async function writeAgentEventsToStream(agent, options, writer) {
           errorText: event.error.message
         });
         break;
-      // Step and message lifecycle events - no direct mapping in AI SDK v6
-      // These can be exposed via custom data parts if needed
+      // Step/message/runtime lifecycle events - no direct mapping in AI SDK v6.
+      // These can be exposed later via custom data parts if the UI needs them.
       case "step-start":
       case "step-finish":
+      case "turn-boundary":
       case "message":
+      case "intervention-applied":
+      case "turn-summary":
       case "complete":
         break;
       // Events we don't need to stream

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-http",
-  "version": "0.1.6",
+  "version": "0.5.0",
   "description": "HTTP streaming adapter for @cuylabs/agent-core - bridges agent events to AI SDK compatible streams",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@cuylabs/agent-core": "^0.4.0"
+    "@cuylabs/agent-core": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",