@dudousxd/nestjs-agent-react 0.34.0 → 0.34.2

package/dist/index.d.cts

@@ -390,18 +390,33 @@ declare function useAttachments(options?: UseAttachmentsOptions): AttachmentsSta
  * What maps where (the inverse of the producer in `@adonis-agora/agent/ag-ui`):
  *  - `TEXT_MESSAGE_*` → `text`; `REASONING_MESSAGE_*` → `reasoning`; `STEP_*` → `step-start` /
  *    `step-finish`;
- *  - `TOOL_CALL_START` / `ARGS` / `END` → `tool-input-start` / `-delta` / `-available`;
- *    `TOOL_CALL_RESULT` → `tool-output` (or `tool-output-error` / `-denied`, from
- *    `metadata['agora.outcome']`);
+ *  - `TOOL_CALL_START` / `ARGS` / `END` → `tool-input-start` / `-delta` / `-available`, with the
+ *    `toolKind` and `parentId` from `metadata['agora.toolKind']` / `['agora.parentId']` (a call
+ *    without them is a `read`); `TOOL_CALL_RESULT` → `tool-output` (or `tool-output-error` /
+ *    `-denied`, from `metadata['agora.outcome']`);
  *  - `ACTIVITY_SNAPSHOT` / `ACTIVITY_DELTA` → a `ui` part named `AgUiActivity`, id
  *    `activity:<messageId>`, props `{ activityType, content }` — the whole content each time (the
  *    delta's JSON Patch applied here), so a repeat replaces the widget in place;
  *  - `RUN_ERROR` → the stream's `event: error`; `RUN_FINISHED` → `event: done` (a cancelled
- *    outcome writes `cancelled` first; an interrupt outcome writes a `ui` part named
- *    `AgUiInterrupt` carrying the interrupts, for the app to render);
+ *    outcome writes `cancelled` first). An interrupt outcome whose every interrupt this stream
+ *    already showed (`agora.approval-requested` / `agora.elicitation`) ends the stream WITHOUT
+ *    `done`: the run is parked, not over, so the transport re-attaches to it on the native route
+ *    (`chat/:runId/stream?after=`) and the rest of the run — after the person decides through the
+ *    native `tool-call` routes — streams into the same message. An interrupt nothing showed (another
+ *    producer's) becomes a `ui` part named `AgUiInterrupt` carrying it, for the app to render;
+ *  - the producer's SSE `id:` (the run's own sequence number, which this library's producer writes)
+ *    is passed on as the cursor the transport re-attaches with; frames of a producer that numbers
+ *    nothing carry no id, and the transport then does not try to re-attach;
  *  - `CUSTOM` events a producer of this family writes (`agora.ui`, `agora.title`, `agora.queue`,
- *    `agora.approval-requested` / `-settled`, `agora.run`) → the frames they stand for. Any other
- *    `CUSTOM` is ignored, as the protocol requires of a consumer that does not know it.
+ *    `agora.approval-requested` / `-settled`, `agora.elicitation`, `agora.run`) → the frames they
+ *    stand for; `agora.step-usage` (right after a `STEP_FINISHED`) → that step's `usage`, `costUsd`
+ *    and `reasoningMs` on its `step-finish`; `agora.action-proposal-decision` → the
+ *    `data-proposal-decision` part a native decision answers with (`{ threadId, proposalDecision,
+ *    text }`). Any other `CUSTOM` is ignored, as the protocol requires of a consumer that does not
+ *    know it.
+ *
+ * And on the way in: the send's staged `attachments` (`{ mediaId }`) become `file` content parts
+ * the producer resolves for the caller, and `regenerate: true` rides `forwardedProps`.
  */
 interface AgUiChatStreamOptions {
     /** The producer's endpoint (`POST`, `RunAgentInput` in, `text/event-stream` out). */
@@ -411,16 +426,20 @@ interface AgUiChatStreamOptions {
     /** Defaults to the global `fetch`, with `credentials: 'same-origin'`. */
     fetch?: typeof fetch;
     /**
-     * Shape `forwardedProps` from the send's body. Default: `{ pageContext, agent, model, persona, uiCapabilities }` from the
-     * body, whichever are present.
+     * Shape `forwardedProps` from the send's body. Default: `{ pageContext, agent, model, persona,
+     * uiCapabilities, regenerate }` from the body, whichever are present.
      */
     forwardedProps?: (body: Record<string, unknown>) => unknown;
     /** Read the refusal of a non-2xx answer. Default: the JSON body's `message`, else the status. */
     refusal?: (response: Response) => Promise<Error>;
     /**
-     * The user message's `content` for the send. Default: the body's `message` as a string. Return
-     * a list of AG-UI content parts to send a file with it — `{ type: 'image' | 'document' | …,
-     * source: { type: 'data', value: <base64>, mimeType } }` — and the text as a `text` part.
+     * The user message's `content` for the send. Default: the body's `message` as a string — or,
+     * when the send carries staged `attachments` (`{ mediaId, contentType? }`, what the composer
+     * uploads), a `text` part followed by one `file` part per attachment
+     * (`source: { type: 'file', value: <mediaId>, provider: 'nestjs-agent' }`), which this library's
+     * producer resolves for the caller. Return your own list of AG-UI content parts to send inline
+     * bytes instead — `{ type: 'image' | 'document' | …, source: { type: 'data', value: <base64>,
+     * mimeType } }`.
      */
     content?: (body: Record<string, unknown>) => string | AgUiContentPart[];
 }
@@ -450,8 +469,8 @@ type AgUiContentPart = {
 declare function agUiChatStream(request: ChatStreamRequest, options: AgUiChatStreamOptions): Promise<ChatStreamResponse>;
 /**
  * Re-frame an AG-UI event stream (SSE, one event per `data:`) in this library's stream protocol:
- * `event: meta`, numbered `data:` frames of {@link AgentStreamEvent}, then `event: done` or
- * `event: error`. Exported for a backend that fetches the stream itself.
+ * `event: meta`, `data:` frames of {@link AgentStreamEvent} (numbered with the run's own sequence
+ * when the producer numbers its events), then `event: done` or `event: error`. Exported for a backend that fetches the stream itself.
  */
 declare function reframeAgUiStream(source: ReadableStream<Uint8Array>, ids: {
     threadId: string;

package/dist/index.d.ts

@@ -390,18 +390,33 @@ declare function useAttachments(options?: UseAttachmentsOptions): AttachmentsSta
  * What maps where (the inverse of the producer in `@adonis-agora/agent/ag-ui`):
  *  - `TEXT_MESSAGE_*` → `text`; `REASONING_MESSAGE_*` → `reasoning`; `STEP_*` → `step-start` /
  *    `step-finish`;
- *  - `TOOL_CALL_START` / `ARGS` / `END` → `tool-input-start` / `-delta` / `-available`;
- *    `TOOL_CALL_RESULT` → `tool-output` (or `tool-output-error` / `-denied`, from
- *    `metadata['agora.outcome']`);
+ *  - `TOOL_CALL_START` / `ARGS` / `END` → `tool-input-start` / `-delta` / `-available`, with the
+ *    `toolKind` and `parentId` from `metadata['agora.toolKind']` / `['agora.parentId']` (a call
+ *    without them is a `read`); `TOOL_CALL_RESULT` → `tool-output` (or `tool-output-error` /
+ *    `-denied`, from `metadata['agora.outcome']`);
  *  - `ACTIVITY_SNAPSHOT` / `ACTIVITY_DELTA` → a `ui` part named `AgUiActivity`, id
  *    `activity:<messageId>`, props `{ activityType, content }` — the whole content each time (the
  *    delta's JSON Patch applied here), so a repeat replaces the widget in place;
  *  - `RUN_ERROR` → the stream's `event: error`; `RUN_FINISHED` → `event: done` (a cancelled
- *    outcome writes `cancelled` first; an interrupt outcome writes a `ui` part named
- *    `AgUiInterrupt` carrying the interrupts, for the app to render);
+ *    outcome writes `cancelled` first). An interrupt outcome whose every interrupt this stream
+ *    already showed (`agora.approval-requested` / `agora.elicitation`) ends the stream WITHOUT
+ *    `done`: the run is parked, not over, so the transport re-attaches to it on the native route
+ *    (`chat/:runId/stream?after=`) and the rest of the run — after the person decides through the
+ *    native `tool-call` routes — streams into the same message. An interrupt nothing showed (another
+ *    producer's) becomes a `ui` part named `AgUiInterrupt` carrying it, for the app to render;
+ *  - the producer's SSE `id:` (the run's own sequence number, which this library's producer writes)
+ *    is passed on as the cursor the transport re-attaches with; frames of a producer that numbers
+ *    nothing carry no id, and the transport then does not try to re-attach;
  *  - `CUSTOM` events a producer of this family writes (`agora.ui`, `agora.title`, `agora.queue`,
- *    `agora.approval-requested` / `-settled`, `agora.run`) → the frames they stand for. Any other
- *    `CUSTOM` is ignored, as the protocol requires of a consumer that does not know it.
+ *    `agora.approval-requested` / `-settled`, `agora.elicitation`, `agora.run`) → the frames they
+ *    stand for; `agora.step-usage` (right after a `STEP_FINISHED`) → that step's `usage`, `costUsd`
+ *    and `reasoningMs` on its `step-finish`; `agora.action-proposal-decision` → the
+ *    `data-proposal-decision` part a native decision answers with (`{ threadId, proposalDecision,
+ *    text }`). Any other `CUSTOM` is ignored, as the protocol requires of a consumer that does not
+ *    know it.
+ *
+ * And on the way in: the send's staged `attachments` (`{ mediaId }`) become `file` content parts
+ * the producer resolves for the caller, and `regenerate: true` rides `forwardedProps`.
  */
 interface AgUiChatStreamOptions {
     /** The producer's endpoint (`POST`, `RunAgentInput` in, `text/event-stream` out). */
@@ -411,16 +426,20 @@ interface AgUiChatStreamOptions {
     /** Defaults to the global `fetch`, with `credentials: 'same-origin'`. */
     fetch?: typeof fetch;
     /**
-     * Shape `forwardedProps` from the send's body. Default: `{ pageContext, agent, model, persona, uiCapabilities }` from the
-     * body, whichever are present.
+     * Shape `forwardedProps` from the send's body. Default: `{ pageContext, agent, model, persona,
+     * uiCapabilities, regenerate }` from the body, whichever are present.
      */
     forwardedProps?: (body: Record<string, unknown>) => unknown;
     /** Read the refusal of a non-2xx answer. Default: the JSON body's `message`, else the status. */
     refusal?: (response: Response) => Promise<Error>;
     /**
-     * The user message's `content` for the send. Default: the body's `message` as a string. Return
-     * a list of AG-UI content parts to send a file with it — `{ type: 'image' | 'document' | …,
-     * source: { type: 'data', value: <base64>, mimeType } }` — and the text as a `text` part.
+     * The user message's `content` for the send. Default: the body's `message` as a string — or,
+     * when the send carries staged `attachments` (`{ mediaId, contentType? }`, what the composer
+     * uploads), a `text` part followed by one `file` part per attachment
+     * (`source: { type: 'file', value: <mediaId>, provider: 'nestjs-agent' }`), which this library's
+     * producer resolves for the caller. Return your own list of AG-UI content parts to send inline
+     * bytes instead — `{ type: 'image' | 'document' | …, source: { type: 'data', value: <base64>,
+     * mimeType } }`.
      */
     content?: (body: Record<string, unknown>) => string | AgUiContentPart[];
 }
@@ -450,8 +469,8 @@ type AgUiContentPart = {
 declare function agUiChatStream(request: ChatStreamRequest, options: AgUiChatStreamOptions): Promise<ChatStreamResponse>;
 /**
  * Re-frame an AG-UI event stream (SSE, one event per `data:`) in this library's stream protocol:
- * `event: meta`, numbered `data:` frames of {@link AgentStreamEvent}, then `event: done` or
- * `event: error`. Exported for a backend that fetches the stream itself.
+ * `event: meta`, `data:` frames of {@link AgentStreamEvent} (numbered with the run's own sequence
+ * when the producer numbers its events), then `event: done` or `event: error`. Exported for a backend that fetches the stream itself.
  */
 declare function reframeAgUiStream(source: ReadableStream<Uint8Array>, ids: {
     threadId: string;

package/dist/index.js

@@ -948,7 +948,10 @@ var AgentChatTransport = class {
               forwardAsData(event, true);
               break;
             default:
-              forwardAsData(event, false);
+              forwardAsData(
+                event,
+                event.kind === "proposal-decision"
+              );
               break;
           }
         }
@@ -1969,8 +1972,33 @@ function defaultForwardedProps(body) {
   for (const key of ["pageContext", "agent", "model", "persona", "uiCapabilities"]) {
     if (body[key] !== void 0 && body[key] !== null) out[key] = body[key];
   }
+  if (body.regenerate === true) out.regenerate = true;
   return Object.keys(out).length > 0 ? out : void 0;
 }
+var MEDIA_PROVIDER = "nestjs-agent";
+function partTypeFor(contentType) {
+  const major = contentType?.split("/")[0]?.toLowerCase();
+  return major === "image" || major === "audio" || major === "video" ? major : "document";
+}
+function defaultContent(body, message) {
+  const attachments = Array.isArray(body.attachments) ? body.attachments : [];
+  const files = [];
+  for (const attachment of attachments) {
+    if (!isRecord2(attachment) || typeof attachment.mediaId !== "string") continue;
+    const contentType = typeof attachment.contentType === "string" ? attachment.contentType : void 0;
+    files.push({
+      type: partTypeFor(contentType),
+      source: {
+        type: "file",
+        value: attachment.mediaId,
+        provider: MEDIA_PROVIDER,
+        ...contentType !== void 0 ? { mimeType: contentType } : {}
+      }
+    });
+  }
+  if (files.length === 0) return message;
+  return [...message.length > 0 ? [{ type: "text", text: message }] : [], ...files];
+}
 async function agUiChatStream(request, options) {
   const body = request.body;
   const threadId = typeof body.threadId === "string" ? body.threadId : newId();
@@ -1980,7 +2008,13 @@ async function agUiChatStream(request, options) {
     threadId,
     runId: newId(),
     protocolVersion: "1.0",
-    messages: [{ id: newId(), role: "user", content: options.content?.(body) ?? message }],
+    messages: [
+      {
+        id: newId(),
+        role: "user",
+        content: options.content?.(body) ?? defaultContent(body, message)
+      }
+    ],
     ...forwarded !== void 0 ? { forwardedProps: forwarded } : {}
   };
   const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
@@ -2017,6 +2051,8 @@ function reframeAgUiStream(source, ids) {
       for (; ; ) {
         const { value, done } = await reader.read();
         if (done) {
+          const rest = reframer.flush();
+          if (rest.length > 0) controller.enqueue(encoder.encode(rest));
           controller.close();
           return;
         }
@@ -2027,7 +2063,10 @@ function reframeAgUiStream(source, ids) {
           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");
+          const lines = block.split("\n");
+          const idLine = lines.find((line) => line.startsWith("id:"));
+          const id = idLine === void 0 ? void 0 : Number(idLine.slice(3).trim());
+          const data = lines.filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart()).join("\n");
           if (data.length === 0) continue;
           let event;
           try {
@@ -2036,7 +2075,10 @@ function reframeAgUiStream(source, ids) {
             continue;
           }
           if (isRecord2(event) && typeof event.type === "string") {
-            out += reframer.push(event);
+            out += reframer.push(
+              event,
+              id !== void 0 && Number.isSafeInteger(id) && id > 0 ? id : void 0
+            );
           }
           if (reframer.closed) break;
         }
@@ -2056,21 +2098,55 @@ function reframeAgUiStream(source, ids) {
 }
 function createReframer(threadId) {
   const activities = /* @__PURE__ */ new Map();
-  let seq = 0;
   let metaSent = false;
   const tools = /* @__PURE__ */ new Map();
+  let pendingStep;
+  const encodeFrame = (streamEvent) => `data: ${JSON.stringify(streamEvent)}
+
+`;
+  const flushStep = () => {
+    if (pendingStep === void 0) return "";
+    const step = pendingStep;
+    pendingStep = void 0;
+    return encodeFrame(step);
+  };
+  let current;
+  let written;
+  const cursor = () => {
+    if (current === void 0 || current === written) return "";
+    written = current;
+    return `${flushStep()}id: ${current}
+
+`;
+  };
+  const shown = /* @__PURE__ */ new Set();
+  let decision;
   const state = {
     closed: false,
-    push(event) {
+    flush() {
+      return state.closed ? "" : `${flushStep()}${cursor()}`;
+    },
+    push(event, id) {
       if (state.closed) return "";
       let out = "";
+      if (id !== void 0) {
+        if (current !== void 0 && id > current) out += cursor();
+        current = id;
+      }
       const frame = (streamEvent) => {
-        seq += 1;
-        out += `id: ${seq}
-data: ${JSON.stringify(streamEvent)}
-
-`;
+        out += encodeFrame(streamEvent);
       };
+      if (event.type === "CUSTOM" && event.name === "agora.step-usage" && pendingStep !== void 0 && isRecord2(event.value)) {
+        const value = event.value;
+        if (isRecord2(value.usage)) pendingStep.usage = value.usage;
+        if (typeof value.costUsd === "number" || value.costUsd === null) {
+          pendingStep.costUsd = value.costUsd;
+        }
+        if (typeof value.reasoningMs === "number") pendingStep.reasoningMs = value.reasoningMs;
+        out += flushStep();
+        return out;
+      }
+      out += flushStep();
       const meta = (runId, thread) => {
         if (metaSent) return;
         metaSent = true;
@@ -2100,9 +2176,24 @@ data: ${JSON.stringify({
             frame({ kind: "title", title: value.title });
           } else if (event.name === "agora.queue") frame({ kind: "queue", ...value });
           else if (event.name === "agora.approval-requested") {
+            if (typeof value.id === "string") shown.add(value.id);
             frame({ ...value, kind: "approval-requested" });
           } else if (event.name === "agora.approval-settled") {
             frame({ ...value, kind: "approval-settled" });
+          } else if (event.name === "agora.elicitation" && typeof value.id === "string" && isRecord2(value.request) && Array.isArray(value.request.questions)) {
+            shown.add(value.id);
+            if (typeof value.request.id === "string") shown.add(value.request.id);
+            frame({
+              kind: "elicitation",
+              id: value.id,
+              request: value.request
+            });
+          } else if (event.name === "agora.action-proposal-decision") {
+            decision = {
+              threadId: value.threadId,
+              proposalDecision: value.proposalDecision,
+              text: ""
+            };
           }
           return out;
         }
@@ -2112,6 +2203,9 @@ data: ${JSON.stringify({
       switch (event.type) {
         case "TEXT_MESSAGE_CONTENT":
         case "TEXT_MESSAGE_CHUNK":
+          if (decision !== void 0 && typeof event.delta === "string") {
+            decision.text += event.delta;
+          }
           if (typeof event.delta === "string" && event.delta.length > 0) {
             frame({ kind: "text", text: event.delta });
           }
@@ -2126,20 +2220,34 @@ data: ${JSON.stringify({
           frame({ kind: "step-start" });
           break;
         case "STEP_FINISHED":
-          frame({ kind: "step-finish" });
+          pendingStep = { 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 id2 = String(event.toolCallId ?? "");
+          if (id2 === "") break;
+          if (!tools.has(id2)) {
             const name = typeof event.toolCallName === "string" ? event.toolCallName : "";
-            tools.set(id, { name, args: "" });
-            frame({ kind: "tool-input-start", id, name, toolKind: "read" });
+            const metadata = isRecord2(event.metadata) ? event.metadata : {};
+            const toolKind2 = metadata["agora.toolKind"] === "action" ? "action" : "read";
+            const parentId = typeof metadata["agora.parentId"] === "string" ? metadata["agora.parentId"] : void 0;
+            tools.set(id2, {
+              name,
+              args: "",
+              toolKind: toolKind2,
+              ...parentId !== void 0 ? { parentId } : {}
+            });
+            frame({
+              kind: "tool-input-start",
+              id: id2,
+              name,
+              toolKind: toolKind2,
+              ...parentId !== void 0 ? { parentId } : {}
+            });
           }
           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 });
+            tools.get(id2).args += event.delta;
+            frame({ kind: "tool-input-delta", id: id2, delta: event.delta });
           }
           break;
         }
@@ -2151,25 +2259,26 @@ data: ${JSON.stringify({
           break;
         }
         case "TOOL_CALL_END": {
-          const id = String(event.toolCallId);
-          const call = tools.get(id);
+          const id2 = String(event.toolCallId);
+          const call = tools.get(id2);
           if (call === void 0) break;
           frame({
             kind: "tool-input-available",
-            id,
+            id: id2,
             name: call.name,
             input: parseJson(call.args, {}),
-            toolKind: "read"
+            toolKind: call.toolKind,
+            ...call.parentId !== void 0 ? { parentId: call.parentId } : {}
           });
           break;
         }
         case "TOOL_CALL_RESULT": {
-          const id = String(event.toolCallId);
+          const id2 = 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) });
+          if (outcome === "error") frame({ kind: "tool-output-error", id: id2, error: content });
+          else if (outcome === "denied") frame({ kind: "tool-output-denied", id: id2, reason: content });
+          else frame({ kind: "tool-output", id: id2, output: parseJson(content, content) });
           break;
         }
         case "ACTIVITY_SNAPSHOT":
@@ -2208,15 +2317,26 @@ data: ${JSON.stringify({
           break;
         case "RUN_FINISHED": {
           const outcome = isRecord2(event.outcome) ? event.outcome : void 0;
+          if (decision !== void 0) {
+            frame({ kind: "proposal-decision", ...decision });
+            decision = void 0;
+          }
           if (outcome?.type === "cancelled") frame({ kind: "cancelled" });
           if (outcome?.type === "interrupt" && Array.isArray(outcome.interrupts)) {
+            const unseen = outcome.interrupts.filter((interrupt) => !isShown(interrupt, shown));
+            if (unseen.length === 0) {
+              out += cursor();
+              state.closed = true;
+              break;
+            }
             frame({
               kind: "ui",
               id: `ag-ui:interrupt:${String(event.runId ?? "")}`,
               component: "AgUiInterrupt",
-              props: { interrupts: outcome.interrupts }
+              props: { interrupts: unseen }
             });
           }
+          out += cursor();
           state.closed = true;
           out += "event: done\ndata: {}\n\n";
           break;
@@ -2236,6 +2356,13 @@ data: ${JSON.stringify({
   let pendingStart;
   return state;
 }
+function isShown(interrupt, shown) {
+  if (!isRecord2(interrupt)) return false;
+  if (typeof interrupt.toolCallId === "string" && shown.has(interrupt.toolCallId)) return true;
+  const metadata = isRecord2(interrupt.metadata) ? interrupt.metadata : void 0;
+  const request = isRecord2(metadata?.["agora.request"]) ? metadata["agora.request"] : void 0;
+  return typeof request?.id === "string" && shown.has(request.id);
+}
 function parseJson(text, fallback2) {
   if (text.trim().length === 0) return fallback2;
   try {