@dudousxd/nestjs-agent-react 0.29.1 → 0.30.0

package/README.md

@@ -621,6 +621,35 @@ const readCookie = (name: string) =>
 </AgentProvider>;
 ```
 
+
+### An AG-UI agent (`agUiChatStream`)
+
+`useAgentChat` can drive any [AG-UI 1.0](https://docs.ag-ui.com/spec/1.0) producer — this library's
+own (`@adonis-agora/agent/ag-ui`), CopilotKit's, a Python or .NET agent. Put `agUiChatStream` behind
+`openChatStream`: it POSTs a `RunAgentInput` (the send's text as the user message, `pageContext`,
+`agent` and `model` in `forwardedProps`) and hands the transport the answer re-framed in this
+library's stream protocol, so the transcript, tool activity and generative UI render unchanged.
+
+```ts
+import { agUiChatStream, type AgentBackend } from '@dudousxd/nestjs-agent-react';
+
+const backend: AgentBackend = {
+  ...myBackend,
+  openChatStream: (request) =>
+    agUiChatStream(request, { url: '/agent/ag-ui', headers: { 'x-csrf-token': csrf } }),
+};
+```
+
+- Text, reasoning, steps, tool calls and tool results map one to one; `RUN_ERROR` is the stream's
+  error, a cancelled outcome writes `cancelled`.
+- `CUSTOM` events named `agora.*` (generative UI, title, queue, approvals) become the frames they
+  stand for; any other `CUSTOM` is ignored, as the protocol requires.
+- An interrupt outcome arrives as a `ui` part, component `AgUiInterrupt`, props `{ interrupts }`:
+  answering it is a new run with `resume`, which the app sends through its own backend.
+- A send without a `threadId` gets a new one (AG-UI's thread id is the consumer's), returned as
+  the stream's `threadId`, so `onThreadCreated` fires as usual.
+- `reframeAgUiStream(body, { threadId })` is the re-framing alone, for a backend that fetches itself.
+
 ### Typing ahead: the message queue
 
 Send while a turn is still answering and the message waits in the thread's queue — server-side, so

package/dist/{client-DhHEJi7c.d.cts → client-BuobfZtx.d.cts}

@@ -436,4 +436,4 @@ declare class AgentClient implements AgentBackend {
     private handleResponse;
 }
 
-export { type AgentRequestError as A, type CancelResult as C, type ErrorAnswer as E, type HttpErrorListener as H, type MessageFeedbackInput as M, type QueuedMessageUpdate as Q, type ResumeStreamRequest as R, type ThreadPatch as T, type UploadAttachmentOptions as U, type AgentBackend as a, type AttachmentUploadStrategy as b, AgentBackendUnsupportedError as c, AgentClient as d, type AgentClientOptions as e, type AgentConnection as f, AgentHttpError as g, type ChatStreamRequest as h, type ChatStreamResponse as i, type QueuedSendResult as j, requireBackendMethod as r };
+export { type AgentRequestError as A, type ChatStreamRequest as C, type ErrorAnswer as E, type HttpErrorListener as H, type MessageFeedbackInput as M, type QueuedMessageUpdate as Q, type ResumeStreamRequest as R, type ThreadPatch as T, type UploadAttachmentOptions as U, type AgentBackend as a, type ChatStreamResponse as b, type AttachmentUploadStrategy as c, AgentBackendUnsupportedError as d, AgentClient as e, type AgentClientOptions as f, type AgentConnection as g, AgentHttpError as h, type CancelResult as i, type QueuedSendResult as j, requireBackendMethod as r };

package/dist/{client-DhHEJi7c.d.ts → client-BuobfZtx.d.ts}

@@ -436,4 +436,4 @@ declare class AgentClient implements AgentBackend {
     private handleResponse;
 }
 
-export { type AgentRequestError as A, type CancelResult as C, type ErrorAnswer as E, type HttpErrorListener as H, type MessageFeedbackInput as M, type QueuedMessageUpdate as Q, type ResumeStreamRequest as R, type ThreadPatch as T, type UploadAttachmentOptions as U, type AgentBackend as a, type AttachmentUploadStrategy as b, AgentBackendUnsupportedError as c, AgentClient as d, type AgentClientOptions as e, type AgentConnection as f, AgentHttpError as g, type ChatStreamRequest as h, type ChatStreamResponse as i, type QueuedSendResult as j, requireBackendMethod as r };
+export { type AgentRequestError as A, type ChatStreamRequest as C, type ErrorAnswer as E, type HttpErrorListener as H, type MessageFeedbackInput as M, type QueuedMessageUpdate as Q, type ResumeStreamRequest as R, type ThreadPatch as T, type UploadAttachmentOptions as U, type AgentBackend as a, type ChatStreamResponse as b, type AttachmentUploadStrategy as c, AgentBackendUnsupportedError as d, AgentClient as e, type AgentClientOptions as f, type AgentConnection as g, AgentHttpError as h, type CancelResult as i, type QueuedSendResult as j, requireBackendMethod as r };

package/dist/index.cjs

@@ -47,6 +47,7 @@ __export(src_exports, {
   RUN_NOT_ACTIVE_CODE: () => RUN_NOT_ACTIVE_CODE,
   SPEECH_LANGUAGES: () => SPEECH_LANGUAGES,
   acceptsFile: () => acceptsFile,
+  agUiChatStream: () => agUiChatStream,
   applyCompletion: () => applyCompletion,
   approvalCountdown: () => approvalCountdown,
   attachmentFile: () => attachmentFile,
@@ -79,6 +80,7 @@ __export(src_exports, {
   phraseFor: () => phraseFor,
   readPath: () => readPath,
   readReasoningMs: () => readReasoningMs,
+  reframeAgUiStream: () => reframeAgUiStream,
   requireBackendMethod: () => requireBackendMethod,
   resolveResultView: () => resolveResultView,
   storedMessageToUiMessage: () => storedMessageToUiMessage,
@@ -679,6 +681,7 @@ var AgentChatTransport = class {
         return null;
       }
       this.captureHeaderMeta(response);
+      this.options.onResumeAttached?.(response.runId ?? runId);
       return this.toChunkStream(response, {
         runId,
         ...headers !== void 0 ? { headers } : {}
@@ -1924,6 +1927,282 @@ function useAttachments(options = {}) {
   }, [items, add, remove, retry, clear, inputProps, dropZoneProps, dragDepth, onPaste]);
 }
 
+// src/ag-ui-backend.ts
+function newId() {
+  return globalThis.crypto.randomUUID();
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function defaultRefusal(response) {
+  try {
+    const body = await response.json();
+    if (typeof body.message === "string" && body.message.length > 0) return new Error(body.message);
+  } catch {
+  }
+  return new Error(`The agent refused the request (${response.status}).`);
+}
+function defaultForwardedProps(body) {
+  const out = {};
+  for (const key of ["pageContext", "agent", "model"]) {
+    if (body[key] !== void 0 && body[key] !== null) out[key] = body[key];
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+async function agUiChatStream(request, options) {
+  const body = request.body;
+  const threadId = typeof body.threadId === "string" ? body.threadId : newId();
+  const message = typeof body.message === "string" ? body.message : "";
+  const forwarded = (options.forwardedProps ?? defaultForwardedProps)(body);
+  const input = {
+    threadId,
+    runId: newId(),
+    protocolVersion: "1.0",
+    messages: [{ id: newId(), role: "user", content: message }],
+    ...forwarded !== void 0 ? { forwardedProps: forwarded } : {}
+  };
+  const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  const response = await doFetch(options.url, {
+    method: "POST",
+    credentials: "same-origin",
+    headers: {
+      "content-type": "application/json",
+      accept: "text/event-stream",
+      ...options.headers,
+      ...request.headers
+    },
+    body: JSON.stringify(input),
+    ...request.signal !== void 0 ? { signal: request.signal } : {}
+  });
+  if (!response.ok || response.body === null) {
+    throw await (options.refusal ?? defaultRefusal)(response);
+  }
+  const runId = response.headers.get("x-agent-run-id") ?? void 0;
+  return {
+    body: reframeAgUiStream(response.body, { threadId }),
+    threadId,
+    ...runId !== void 0 ? { runId } : {}
+  };
+}
+function reframeAgUiStream(source, ids) {
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+  const reframer = createReframer(ids.threadId);
+  const reader = source.getReader();
+  let buffer = "";
+  return new ReadableStream({
+    async pull(controller) {
+      for (; ; ) {
+        const { value, done } = await reader.read();
+        if (done) {
+          controller.close();
+          return;
+        }
+        buffer += decoder.decode(value, { stream: true }).replace(/\r\n?/g, "\n");
+        let out = "";
+        let separator = buffer.indexOf("\n\n");
+        while (separator !== -1) {
+          const block = buffer.slice(0, separator);
+          buffer = buffer.slice(separator + 2);
+          separator = buffer.indexOf("\n\n");
+          const data = block.split("\n").filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart()).join("\n");
+          if (data.length === 0) continue;
+          let event;
+          try {
+            event = JSON.parse(data);
+          } catch {
+            continue;
+          }
+          if (isRecord2(event) && typeof event.type === "string") {
+            out += reframer.push(event);
+          }
+          if (reframer.closed) break;
+        }
+        if (out.length > 0) controller.enqueue(encoder.encode(out));
+        if (reframer.closed) {
+          void reader.cancel().catch(() => void 0);
+          controller.close();
+          return;
+        }
+        if (out.length > 0) return;
+      }
+    },
+    cancel(reason) {
+      return reader.cancel(reason).catch(() => void 0);
+    }
+  });
+}
+function createReframer(threadId) {
+  let seq = 0;
+  let metaSent = false;
+  const tools = /* @__PURE__ */ new Map();
+  const state = {
+    closed: false,
+    push(event) {
+      if (state.closed) return "";
+      let out = "";
+      const frame = (streamEvent) => {
+        seq += 1;
+        out += `id: ${seq}
+data: ${JSON.stringify(streamEvent)}
+
+`;
+      };
+      const meta = (runId, thread) => {
+        if (metaSent) return;
+        metaSent = true;
+        out += `event: meta
+data: ${JSON.stringify({
+          runId: typeof runId === "string" ? runId : "",
+          threadId: typeof thread === "string" ? thread : threadId
+        })}
+
+`;
+      };
+      switch (event.type) {
+        case "RUN_STARTED":
+          pendingStart = { runId: event.runId, threadId: event.threadId };
+          return out;
+        case "CUSTOM": {
+          const value = event.value;
+          if (event.name === "agora.run" && isRecord2(value)) {
+            meta(value.runId, pendingStart?.threadId ?? value.threadId);
+            pendingStart = void 0;
+            return out;
+          }
+          flushStart();
+          if (!isRecord2(value)) return out;
+          if (event.name === "agora.ui") frame({ kind: "ui", ...value });
+          else if (event.name === "agora.title" && typeof value.title === "string") {
+            frame({ kind: "title", title: value.title });
+          } else if (event.name === "agora.queue") frame({ kind: "queue", ...value });
+          else if (event.name === "agora.approval-requested") {
+            frame({ ...value, kind: "approval-requested" });
+          } else if (event.name === "agora.approval-settled") {
+            frame({ ...value, kind: "approval-settled" });
+          }
+          return out;
+        }
+        default:
+          flushStart();
+      }
+      switch (event.type) {
+        case "TEXT_MESSAGE_CONTENT":
+        case "TEXT_MESSAGE_CHUNK":
+          if (typeof event.delta === "string" && event.delta.length > 0) {
+            frame({ kind: "text", text: event.delta });
+          }
+          break;
+        case "REASONING_MESSAGE_CONTENT":
+        case "REASONING_MESSAGE_CHUNK":
+          if (typeof event.delta === "string" && event.delta.length > 0) {
+            frame({ kind: "reasoning", text: event.delta });
+          }
+          break;
+        case "STEP_STARTED":
+          frame({ kind: "step-start" });
+          break;
+        case "STEP_FINISHED":
+          frame({ kind: "step-finish" });
+          break;
+        case "TOOL_CALL_START":
+        case "TOOL_CALL_CHUNK": {
+          const id = String(event.toolCallId ?? "");
+          if (id === "") break;
+          if (!tools.has(id)) {
+            const name = typeof event.toolCallName === "string" ? event.toolCallName : "";
+            tools.set(id, { name, args: "" });
+            frame({ kind: "tool-input-start", id, name, toolKind: "read" });
+          }
+          if (event.type === "TOOL_CALL_CHUNK" && typeof event.delta === "string") {
+            tools.get(id).args += event.delta;
+            frame({ kind: "tool-input-delta", id, delta: event.delta });
+          }
+          break;
+        }
+        case "TOOL_CALL_ARGS": {
+          const call = tools.get(String(event.toolCallId));
+          if (call === void 0 || typeof event.delta !== "string") break;
+          call.args += event.delta;
+          frame({ kind: "tool-input-delta", id: String(event.toolCallId), delta: event.delta });
+          break;
+        }
+        case "TOOL_CALL_END": {
+          const id = String(event.toolCallId);
+          const call = tools.get(id);
+          if (call === void 0) break;
+          frame({
+            kind: "tool-input-available",
+            id,
+            name: call.name,
+            input: parseJson(call.args, {}),
+            toolKind: "read"
+          });
+          break;
+        }
+        case "TOOL_CALL_RESULT": {
+          const id = String(event.toolCallId);
+          const content = contentText(event.content);
+          const outcome = isRecord2(event.metadata) ? event.metadata["agora.outcome"] : void 0;
+          if (outcome === "error") frame({ kind: "tool-output-error", id, error: content });
+          else if (outcome === "denied") frame({ kind: "tool-output-denied", id, reason: content });
+          else frame({ kind: "tool-output", id, output: parseJson(content, content) });
+          break;
+        }
+        case "RUN_ERROR":
+          state.closed = true;
+          out += `event: error
+data: ${JSON.stringify({
+            code: typeof event.code === "string" ? event.code : "run_failed",
+            message: typeof event.message === "string" ? event.message : "The run failed."
+          })}
+
+`;
+          break;
+        case "RUN_FINISHED": {
+          const outcome = isRecord2(event.outcome) ? event.outcome : void 0;
+          if (outcome?.type === "cancelled") frame({ kind: "cancelled" });
+          if (outcome?.type === "interrupt" && Array.isArray(outcome.interrupts)) {
+            frame({
+              kind: "ui",
+              id: `ag-ui:interrupt:${String(event.runId ?? "")}`,
+              component: "AgUiInterrupt",
+              props: { interrupts: outcome.interrupts }
+            });
+          }
+          state.closed = true;
+          out += "event: done\ndata: {}\n\n";
+          break;
+        }
+        default:
+          break;
+      }
+      return out;
+      function flushStart() {
+        if (pendingStart !== void 0) {
+          meta(pendingStart.runId, pendingStart.threadId);
+          pendingStart = void 0;
+        }
+      }
+    }
+  };
+  let pendingStart;
+  return state;
+}
+function parseJson(text, fallback2) {
+  if (text.trim().length === 0) return fallback2;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return fallback2;
+  }
+}
+function contentText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.filter((part) => isRecord2(part) && part.type === "text" && typeof part.text === "string").map((part) => part.text).join("");
+}
+
 // src/catalog/use-agents.ts
 var import_react9 = require("react");
 
@@ -2561,7 +2840,7 @@ function phraseFor(presentation, input, isSettled2, fallback2 = { running: "Work
 }
 
 // src/presentation/result-view.ts
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function toText(value) {
@@ -2573,18 +2852,18 @@ function toText(value) {
   return "\u2014";
 }
 function inferResultView(output) {
-  if (!isRecord2(output)) return void 0;
+  if (!isRecord3(output)) return void 0;
   for (const [key, value] of Object.entries(output)) {
     if (!Array.isArray(value) || value.length === 0) continue;
     if (value.every((entry) => typeof entry === "string")) {
       return { kind: "log", lines: key };
     }
-    if (value.every(isRecord2)) {
+    if (value.every(isRecord3)) {
       const first = value[0];
       return {
         kind: "table",
         rows: key,
-        columns: Object.keys(first).filter((column) => !isRecord2(first[column])).map((column) => ({ path: column, label: column }))
+        columns: Object.keys(first).filter((column) => !isRecord3(first[column])).map((column) => ({ path: column, label: column }))
       };
     }
   }
@@ -2911,7 +3190,7 @@ function isSettled(state) {
 }
 function toolKind(part) {
   const metadata = part.toolMetadata;
-  return isRecord3(metadata) && typeof metadata.toolKind === "string" ? metadata.toolKind : void 0;
+  return isRecord4(metadata) && typeof metadata.toolKind === "string" ? metadata.toolKind : void 0;
 }
 function isAwaitingApproval(part) {
   if (part.state === "approval-requested") {
@@ -2924,7 +3203,7 @@ function isAwaitingApproval(part) {
 }
 function toolParentId(part) {
   const metadata = part.toolMetadata;
-  return isRecord3(metadata) && typeof metadata.parentId === "string" ? metadata.parentId : null;
+  return isRecord4(metadata) && typeof metadata.parentId === "string" ? metadata.parentId : null;
 }
 function nestToolCalls(calls) {
   const byId = new Map(calls.map((call) => [call.toolCallId, call]));
@@ -2983,12 +3262,12 @@ function buildToolCall(part, options, approval, catalog) {
 }
 function readElicitationRequest(part) {
   const input = part.input;
-  if (!isRecord3(input) || !Array.isArray(input.questions) || input.questions.length === 0) {
+  if (!isRecord4(input) || !Array.isArray(input.questions) || input.questions.length === 0) {
     return null;
   }
   const questions = [];
   for (const candidate of input.questions) {
-    if (!isRecord3(candidate) || typeof candidate.id !== "string" || typeof candidate.prompt !== "string") {
+    if (!isRecord4(candidate) || typeof candidate.id !== "string" || typeof candidate.prompt !== "string") {
       return null;
     }
     const input2 = (0, import_nestjs_agent_core3.readElicitationInput)(candidate.input) ?? null;
@@ -2998,7 +3277,7 @@ function readElicitationRequest(part) {
     }
     const options = [];
     for (const option of rawOptions) {
-      if (!isRecord3(option) || typeof option.value !== "string" || typeof option.label !== "string") {
+      if (!isRecord4(option) || typeof option.value !== "string" || typeof option.label !== "string") {
         return null;
       }
       options.push({
@@ -3025,7 +3304,7 @@ function readElicitationRequest(part) {
 }
 function readElicitationOutcome(part) {
   const output = part.output;
-  if (!isRecord3(output) || !isRecord3(output.answers) || typeof output.skipped !== "boolean") {
+  if (!isRecord4(output) || !isRecord4(output.answers) || typeof output.skipped !== "boolean") {
     return null;
   }
   const answers = {};
@@ -3150,7 +3429,7 @@ function readApprovals(parts) {
       continue;
     }
     const data = part.data;
-    if (!isRecord3(data) || typeof data.id !== "string") {
+    if (!isRecord4(data) || typeof data.id !== "string") {
       continue;
     }
     const approval = entry(data.id);
@@ -3203,7 +3482,7 @@ function statusFromPart(call) {
 }
 function readUiComponent(part) {
   const data = part.data;
-  if (!isRecord3(data) || typeof data.component !== "string") {
+  if (!isRecord4(data) || typeof data.component !== "string") {
     return null;
   }
   const id = typeof data.id === "string" ? data.id : part.id;
@@ -3213,29 +3492,29 @@ function readUiComponent(part) {
   return {
     id,
     component: data.component,
-    props: isRecord3(data.props) ? data.props : {},
+    props: isRecord4(data.props) ? data.props : {},
     version: typeof data.version === "number" ? data.version : null,
     toolCallId: typeof data.toolCallId === "string" ? data.toolCallId : null
   };
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return typeof value === "object" && value !== null;
 }
 function readQuery(part) {
   const input = part.input;
-  if (!isRecord3(input) || typeof input.query !== "string") {
+  if (!isRecord4(input) || typeof input.query !== "string") {
     return null;
   }
   return input.query;
 }
 function readPassages(part) {
   const output = part.output;
-  if (!isRecord3(output) || !Array.isArray(output.passages) || output.passages.length === 0) {
+  if (!isRecord4(output) || !Array.isArray(output.passages) || output.passages.length === 0) {
     return null;
   }
   const passages = [];
   for (const candidate of output.passages) {
-    if (!isRecord3(candidate) || typeof candidate.id !== "string" || typeof candidate.text !== "string") {
+    if (!isRecord4(candidate) || typeof candidate.id !== "string" || typeof candidate.text !== "string") {
       return null;
     }
     passages.push({
@@ -3243,7 +3522,7 @@ function readPassages(part) {
       text: candidate.text,
       score: typeof candidate.score === "number" ? candidate.score : 0,
       ...typeof candidate.source === "string" ? { source: candidate.source } : {},
-      ...isRecord3(candidate.metadata) ? { metadata: candidate.metadata } : {}
+      ...isRecord4(candidate.metadata) ? { metadata: candidate.metadata } : {}
     });
   }
   return passages;
@@ -4803,6 +5082,14 @@ function storedMessageToUiMessage(message) {
           approved: false,
           ...refusalReason(result) !== void 0 ? { reason: refusalReason(result) } : {}
         }
+      } : typeof result.error === "string" && result.error !== "" ? {
+        // A call that FAILED — the tool threw, its input was refused, or its turn died
+        // before it was settled — is not an available output either. The live stream says
+        // so with `tool-output-error`; a reloaded thread has to say the same, or the card of
+        // an action that never ran comes back reading as one that completed.
+        state: "output-error",
+        input: call.input,
+        errorText: result.error
       } : { state: "output-available", input: call.input, output: result.output } : { state: "input-available", input: call.input }
     });
     parts.push(...pushedByCall.get(call.id) ?? []);
@@ -5040,6 +5327,12 @@ function useAgentChat(options = {}) {
         return { ...turnBody(), ...regenerate2 ? { regenerate: true } : {} };
       },
       getResumeRunId: () => latest.current.resumeRunId ?? autoResumeRunIdRef.current,
+      // A stream attached to after a reload carries no `meta` frame: without this the chat would
+      // be reading a run it cannot name, and `cancel()` would stop nothing.
+      onResumeAttached: (resumedRunId) => {
+        settlingRunIdRef.current = resumedRunId;
+        setRunId(resumedRunId);
+      },
       onMeta,
       onAttemptStart: () => {
         settlingRunIdRef.current = void 0;
@@ -5509,7 +5802,14 @@ function useAgentChat(options = {}) {
       } catch {
       }
     }
-  }, [client]);
+    const threadId = currentThreadId();
+    if (threadId !== void 0 && queueStateRef.current.items.length > 0 && typeof client.getQueue === "function") {
+      try {
+        applyQueue(await client.getQueue(threadId));
+      } catch {
+      }
+    }
+  }, [client, currentThreadId, applyQueue]);
   const approve = (0, import_react23.useCallback)(
     async ({ toolCallId, remember, via }) => {
       await requireBackendMethod(
@@ -5849,6 +6149,7 @@ function isRunNotActiveError(error) {
   RUN_NOT_ACTIVE_CODE,
   SPEECH_LANGUAGES,
   acceptsFile,
+  agUiChatStream,
   applyCompletion,
   approvalCountdown,
   attachmentFile,
@@ -5881,6 +6182,7 @@ function isRunNotActiveError(error) {
   phraseFor,
   readPath,
   readReasoningMs,
+  reframeAgUiStream,
   requireBackendMethod,
   resolveResultView,
   storedMessageToUiMessage,