@dudousxd/nestjs-agent-core 0.42.0 → 0.43.0

package/dist/ag-ui/index.d.cts

@@ -1,6 +1,6 @@
-import { A as AgentStreamEvent, U as UiCapabilities } from '../stream-events-C-pj3bVY.cjs';
+import { A as AgentStreamEvent, U as UiCapabilities } from '../stream-events-BfxJAckJ.cjs';
 import '@standard-schema/spec';
-import '../catalog-BKS3Yxo6.cjs';
+import '../catalog-G8usJpx5.cjs';
 
 /**
  * The slice of AG-UI 1.0 (https://docs.ag-ui.com/spec/1.0) this producer writes and reads. Typed by
@@ -141,6 +141,13 @@ type AgUiPartSource = {
     provider?: string;
     mimeType?: string;
 };
+/**
+ * The `provider` of a `file` content part whose `value` is a `mediaId` this library staged
+ * (`POST <path>/attachments`, or the media module's upload routes). The producer takes such a part as
+ * an attachment reference and resolves it for the caller exactly as the native `chat` route does —
+ * a mediaId the caller does not own is refused. Any other `file` part is dropped.
+ */
+declare const AG_UI_MEDIA_PROVIDER = "nestjs-agent";
 type AgUiContentPart = {
     type: 'text';
     text: string;
@@ -195,7 +202,7 @@ declare const AG_UI_CUSTOM: {
     /** The approval request as the native protocol carries it, for a consumer that renders it live. */
     readonly approvalRequested: "agora.approval-requested";
     readonly approvalSettled: "agora.approval-settled";
-    /** The whole question set of an elicitation (`ElicitationRequest`). */
+    /** `{ id, runId, request }` — the whole question set of an elicitation, under its tool-call id. */
     readonly elicitation: "agora.elicitation";
     /** `{ usage, costUsd, reasoningMs }` of one model step. */
     readonly stepUsage: "agora.step-usage";
@@ -285,9 +292,6 @@ interface AgUiEncoderOptions {
  *  - `cancelled` → the cancelled outcome; an error frame → `RUN_ERROR`;
  *  - generative UI, title, queue and the native approval/elicitation frames → `CUSTOM` events named
  *    in {@link AG_UI_CUSTOM}, for what AG-UI has no event for.
- *
- * Not mapped: sub-agent attribution (`subagentRunId`) — a delegated agent's frames are projected
- * flat, as the protocol allows of a producer that does not attribute.
  */
 declare class AgUiEncoder {
     private readonly options;
@@ -343,6 +347,11 @@ declare class AgUiEncoder {
     private closeText;
     private closeReasoning;
     private closeStreams;
+    /**
+     * `metadata['agora.toolKind']` says whether the call is an `action` (it may park for approval) or
+     * a `read`, and `metadata['agora.parentId']` the call it runs under — what the native
+     * `tool-input-start` frame carries and AG-UI's event has no field for.
+     */
     private callStart;
     private result;
     private addUsage;
@@ -399,6 +408,14 @@ interface UserTurn {
     /** The text of the message the run answers. */
     text: string;
     media: InlineMedia[];
+    /**
+     * Attachments the consumer already staged with this library, by `mediaId` — `file` parts whose
+     * `provider` is {@link AG_UI_MEDIA_PROVIDER}. Resolved (and ownership-checked) like the native
+     * route's `attachments`.
+     */
+    staged: {
+        mediaId: string;
+    }[];
     /** Why a part was not used, one sentence each — reported, never fatal. */
     dropped: string[];
 }
@@ -408,8 +425,10 @@ interface UserTurn {
  * agent resumes from is what it stored.
  *
  * Multimodal parts: text parts are the message's text; a media part carried inline (`data`) becomes
- * an attachment. A part by `url` or by provider `file` handle is dropped and said so — this producer
- * hands the model only bytes it staged itself, never an address a caller supplied.
+ * an attachment, and a `file` part whose `provider` is {@link AG_UI_MEDIA_PROVIDER} names one this
+ * library already staged (its `mediaId`). A part by `url` or by another provider's `file` handle is
+ * dropped and said so — this producer hands the model only bytes it staged itself, never an address
+ * a caller supplied.
  */
 declare function readUserTurn(messages: readonly AgUiMessage[]): UserTurn | null;
 /** `context` entries as the library's page context carries them, or `undefined` for none. */
@@ -424,6 +443,11 @@ interface ForwardedOptions {
     model?: string;
     persona?: string;
     pageContext?: Record<string, unknown>;
+    /**
+     * Re-run the thread's last exchange instead of appending a turn — what the native `chat` body's
+     * `regenerate: true` asks. The user message is the one being answered again.
+     */
+    regenerate?: boolean;
 }
 declare function readForwardedProps(forwarded: unknown): ForwardedOptions;
 /** One resume entry this producer can act on. */
@@ -462,7 +486,20 @@ interface AgUiStreamOptions extends AgUiEncoderOptions {
     quietMs?: number;
     /** Events to write right after `RUN_STARTED` (warnings about input that was dropped). */
     preamble?: AgUiEvent[];
+    /**
+     * Kept at the run's own sequence number (the native stream's SSE `id:`) of the library frame
+     * whose events are being yielded — `0` before the first. Write it as each event's SSE `id:`
+     * ({@link agUiSse}) and a consumer can re-attach to the native stream with `?after=` exactly where
+     * this AG-UI run left off.
+     */
+    cursor?: AgUiCursor;
 }
+/** See {@link AgUiStreamOptions.cursor}. */
+interface AgUiCursor {
+    seq: number;
+}
+/** The run's own sequence number of a frame read by {@link agUiFramesFromNdjson}, if known. */
+declare function frameSeq(frame: AgUiSourceFrame): number | undefined;
 /**
  * One AG-UI run over a library run's stream.
  *
@@ -473,8 +510,12 @@ interface AgUiStreamOptions extends AgUiEncoderOptions {
  * with the interrupt outcome, and leaves the library run parked for the resume to pick up.
  */
 declare function agUiEvents(frames: AsyncIterable<AgUiSourceFrame>, options: AgUiStreamOptions): AsyncGenerator<AgUiEvent>;
-/** One AG-UI event as an SSE frame: a single `data:` line, LF-terminated, as the binding pins. */
-declare function agUiSse(event: AgUiEvent): string;
+/**
+ * One AG-UI event as an SSE frame: a single `data:` line, LF-terminated, as the binding pins. With a
+ * positive `id`, an SSE `id:` line first — the run's sequence number ({@link AgUiStreamOptions.cursor}),
+ * which AG-UI clients ignore and this library's React client re-attaches with.
+ */
+declare function agUiSse(event: AgUiEvent, id?: number): string;
 /**
  * A byte sink's stream (NDJSON {@link AgentStreamEvent}s, one per line, as the NestJS sinks carry
  * it) as the frames the encoder reads. A line that is not a stream event is bare model text — the
@@ -492,4 +533,4 @@ declare function actionProposalDecisionEvents(input: {
     proposalDecision: unknown;
 }): AgUiEvent[];
 
-export { AG_UI_CUSTOM, AG_UI_PROTOCOL_VERSION, type AgUiContentPart, type AgUiContext, AgUiEncoder, type AgUiEncoderOptions, type AgUiEvent, type AgUiInterrupt, type AgUiMessage, type AgUiMetadata, type AgUiPartSource, type AgUiResumeEntry, type AgUiRunInput, type AgUiRunOutcome, type AgUiSourceFrame, type AgUiStreamOptions, type AgUiTokenUsage, type ForwardedOptions, type InlineMedia, type InterruptAddress, type ResumeDecision, type ResumePlan, type UserTurn, actionProposalDecisionEvents, agUiEvents, agUiFramesFromNdjson, agUiSse, decodeInterruptId, encodeInterruptId, parseRunInput, planResume, readAnswersPayload, readApprovalPayload, readContext, readForwardedProps, readUserTurn };
+export { AG_UI_CUSTOM, AG_UI_MEDIA_PROVIDER, AG_UI_PROTOCOL_VERSION, type AgUiContentPart, type AgUiContext, type AgUiCursor, AgUiEncoder, type AgUiEncoderOptions, type AgUiEvent, type AgUiInterrupt, type AgUiMessage, type AgUiMetadata, type AgUiPartSource, type AgUiResumeEntry, type AgUiRunInput, type AgUiRunOutcome, type AgUiSourceFrame, type AgUiStreamOptions, type AgUiTokenUsage, type ForwardedOptions, type InlineMedia, type InterruptAddress, type ResumeDecision, type ResumePlan, type UserTurn, actionProposalDecisionEvents, agUiEvents, agUiFramesFromNdjson, agUiSse, decodeInterruptId, encodeInterruptId, frameSeq, parseRunInput, planResume, readAnswersPayload, readApprovalPayload, readContext, readForwardedProps, readUserTurn };

package/dist/ag-ui/index.d.ts

@@ -1,6 +1,6 @@
-import { A as AgentStreamEvent, U as UiCapabilities } from '../stream-events-D92SgfRk.js';
+import { A as AgentStreamEvent, U as UiCapabilities } from '../stream-events-DFa2Do42.js';
 import '@standard-schema/spec';
-import '../catalog-BKS3Yxo6.js';
+import '../catalog-G8usJpx5.js';
 
 /**
  * The slice of AG-UI 1.0 (https://docs.ag-ui.com/spec/1.0) this producer writes and reads. Typed by
@@ -141,6 +141,13 @@ type AgUiPartSource = {
     provider?: string;
     mimeType?: string;
 };
+/**
+ * The `provider` of a `file` content part whose `value` is a `mediaId` this library staged
+ * (`POST <path>/attachments`, or the media module's upload routes). The producer takes such a part as
+ * an attachment reference and resolves it for the caller exactly as the native `chat` route does —
+ * a mediaId the caller does not own is refused. Any other `file` part is dropped.
+ */
+declare const AG_UI_MEDIA_PROVIDER = "nestjs-agent";
 type AgUiContentPart = {
     type: 'text';
     text: string;
@@ -195,7 +202,7 @@ declare const AG_UI_CUSTOM: {
     /** The approval request as the native protocol carries it, for a consumer that renders it live. */
     readonly approvalRequested: "agora.approval-requested";
     readonly approvalSettled: "agora.approval-settled";
-    /** The whole question set of an elicitation (`ElicitationRequest`). */
+    /** `{ id, runId, request }` — the whole question set of an elicitation, under its tool-call id. */
     readonly elicitation: "agora.elicitation";
     /** `{ usage, costUsd, reasoningMs }` of one model step. */
     readonly stepUsage: "agora.step-usage";
@@ -285,9 +292,6 @@ interface AgUiEncoderOptions {
  *  - `cancelled` → the cancelled outcome; an error frame → `RUN_ERROR`;
  *  - generative UI, title, queue and the native approval/elicitation frames → `CUSTOM` events named
  *    in {@link AG_UI_CUSTOM}, for what AG-UI has no event for.
- *
- * Not mapped: sub-agent attribution (`subagentRunId`) — a delegated agent's frames are projected
- * flat, as the protocol allows of a producer that does not attribute.
  */
 declare class AgUiEncoder {
     private readonly options;
@@ -343,6 +347,11 @@ declare class AgUiEncoder {
     private closeText;
     private closeReasoning;
     private closeStreams;
+    /**
+     * `metadata['agora.toolKind']` says whether the call is an `action` (it may park for approval) or
+     * a `read`, and `metadata['agora.parentId']` the call it runs under — what the native
+     * `tool-input-start` frame carries and AG-UI's event has no field for.
+     */
     private callStart;
     private result;
     private addUsage;
@@ -399,6 +408,14 @@ interface UserTurn {
     /** The text of the message the run answers. */
     text: string;
     media: InlineMedia[];
+    /**
+     * Attachments the consumer already staged with this library, by `mediaId` — `file` parts whose
+     * `provider` is {@link AG_UI_MEDIA_PROVIDER}. Resolved (and ownership-checked) like the native
+     * route's `attachments`.
+     */
+    staged: {
+        mediaId: string;
+    }[];
     /** Why a part was not used, one sentence each — reported, never fatal. */
     dropped: string[];
 }
@@ -408,8 +425,10 @@ interface UserTurn {
  * agent resumes from is what it stored.
  *
  * Multimodal parts: text parts are the message's text; a media part carried inline (`data`) becomes
- * an attachment. A part by `url` or by provider `file` handle is dropped and said so — this producer
- * hands the model only bytes it staged itself, never an address a caller supplied.
+ * an attachment, and a `file` part whose `provider` is {@link AG_UI_MEDIA_PROVIDER} names one this
+ * library already staged (its `mediaId`). A part by `url` or by another provider's `file` handle is
+ * dropped and said so — this producer hands the model only bytes it staged itself, never an address
+ * a caller supplied.
  */
 declare function readUserTurn(messages: readonly AgUiMessage[]): UserTurn | null;
 /** `context` entries as the library's page context carries them, or `undefined` for none. */
@@ -424,6 +443,11 @@ interface ForwardedOptions {
     model?: string;
     persona?: string;
     pageContext?: Record<string, unknown>;
+    /**
+     * Re-run the thread's last exchange instead of appending a turn — what the native `chat` body's
+     * `regenerate: true` asks. The user message is the one being answered again.
+     */
+    regenerate?: boolean;
 }
 declare function readForwardedProps(forwarded: unknown): ForwardedOptions;
 /** One resume entry this producer can act on. */
@@ -462,7 +486,20 @@ interface AgUiStreamOptions extends AgUiEncoderOptions {
     quietMs?: number;
     /** Events to write right after `RUN_STARTED` (warnings about input that was dropped). */
     preamble?: AgUiEvent[];
+    /**
+     * Kept at the run's own sequence number (the native stream's SSE `id:`) of the library frame
+     * whose events are being yielded — `0` before the first. Write it as each event's SSE `id:`
+     * ({@link agUiSse}) and a consumer can re-attach to the native stream with `?after=` exactly where
+     * this AG-UI run left off.
+     */
+    cursor?: AgUiCursor;
 }
+/** See {@link AgUiStreamOptions.cursor}. */
+interface AgUiCursor {
+    seq: number;
+}
+/** The run's own sequence number of a frame read by {@link agUiFramesFromNdjson}, if known. */
+declare function frameSeq(frame: AgUiSourceFrame): number | undefined;
 /**
  * One AG-UI run over a library run's stream.
  *
@@ -473,8 +510,12 @@ interface AgUiStreamOptions extends AgUiEncoderOptions {
  * with the interrupt outcome, and leaves the library run parked for the resume to pick up.
  */
 declare function agUiEvents(frames: AsyncIterable<AgUiSourceFrame>, options: AgUiStreamOptions): AsyncGenerator<AgUiEvent>;
-/** One AG-UI event as an SSE frame: a single `data:` line, LF-terminated, as the binding pins. */
-declare function agUiSse(event: AgUiEvent): string;
+/**
+ * One AG-UI event as an SSE frame: a single `data:` line, LF-terminated, as the binding pins. With a
+ * positive `id`, an SSE `id:` line first — the run's sequence number ({@link AgUiStreamOptions.cursor}),
+ * which AG-UI clients ignore and this library's React client re-attaches with.
+ */
+declare function agUiSse(event: AgUiEvent, id?: number): string;
 /**
  * A byte sink's stream (NDJSON {@link AgentStreamEvent}s, one per line, as the NestJS sinks carry
  * it) as the frames the encoder reads. A line that is not a stream event is bare model text — the
@@ -492,4 +533,4 @@ declare function actionProposalDecisionEvents(input: {
     proposalDecision: unknown;
 }): AgUiEvent[];
 
-export { AG_UI_CUSTOM, AG_UI_PROTOCOL_VERSION, type AgUiContentPart, type AgUiContext, AgUiEncoder, type AgUiEncoderOptions, type AgUiEvent, type AgUiInterrupt, type AgUiMessage, type AgUiMetadata, type AgUiPartSource, type AgUiResumeEntry, type AgUiRunInput, type AgUiRunOutcome, type AgUiSourceFrame, type AgUiStreamOptions, type AgUiTokenUsage, type ForwardedOptions, type InlineMedia, type InterruptAddress, type ResumeDecision, type ResumePlan, type UserTurn, actionProposalDecisionEvents, agUiEvents, agUiFramesFromNdjson, agUiSse, decodeInterruptId, encodeInterruptId, parseRunInput, planResume, readAnswersPayload, readApprovalPayload, readContext, readForwardedProps, readUserTurn };
+export { AG_UI_CUSTOM, AG_UI_MEDIA_PROVIDER, AG_UI_PROTOCOL_VERSION, type AgUiContentPart, type AgUiContext, type AgUiCursor, AgUiEncoder, type AgUiEncoderOptions, type AgUiEvent, type AgUiInterrupt, type AgUiMessage, type AgUiMetadata, type AgUiPartSource, type AgUiResumeEntry, type AgUiRunInput, type AgUiRunOutcome, type AgUiSourceFrame, type AgUiStreamOptions, type AgUiTokenUsage, type ForwardedOptions, type InlineMedia, type InterruptAddress, type ResumeDecision, type ResumePlan, type UserTurn, actionProposalDecisionEvents, agUiEvents, agUiFramesFromNdjson, agUiSse, decodeInterruptId, encodeInterruptId, frameSeq, parseRunInput, planResume, readAnswersPayload, readApprovalPayload, readContext, readForwardedProps, readUserTurn };

package/dist/ag-ui/index.js

@@ -48,6 +48,7 @@ __name(decodeInterruptId, "decodeInterruptId");
 
 // src/ag-ui/types.ts
 var AG_UI_PROTOCOL_VERSION = "1.0";
+var AG_UI_MEDIA_PROVIDER = "nestjs-agent";
 var AG_UI_CUSTOM = {
   /** `{ runId, threadId }` — the library's own ids for the run behind this stream (cancel, re-attach). */
   run: "agora.run",
@@ -58,7 +59,7 @@ var AG_UI_CUSTOM = {
   /** The approval request as the native protocol carries it, for a consumer that renders it live. */
   approvalRequested: "agora.approval-requested",
   approvalSettled: "agora.approval-settled",
-  /** The whole question set of an elicitation (`ElicitationRequest`). */
+  /** `{ id, runId, request }` — the whole question set of an elicitation, under its tool-call id. */
   elicitation: "agora.elicitation",
   /** `{ usage, costUsd, reasoningMs }` of one model step. */
   stepUsage: "agora.step-usage",
@@ -337,6 +338,7 @@ var AgUiEncoder = class {
         });
         return [
           this.custom(AG_UI_CUSTOM.elicitation, {
+            id: event.id,
             runId: parked,
             request: event.request
           })
@@ -392,7 +394,7 @@ var AgUiEncoder = class {
           sawDelta: false,
           answered: false
         });
-        out.push(this.callStart(event.id, event.name));
+        out.push(this.callStart(event.id, event.name, event.toolKind, event.parentId));
         return out;
       }
       case "tool-input-delta": {
@@ -420,7 +422,7 @@ var AgUiEncoder = class {
         };
         if (!call.started) {
           call.started = true;
-          out.push(this.callStart(event.id, event.name));
+          out.push(this.callStart(event.id, event.name, event.toolKind, event.parentId));
         }
         if (!call.sawDelta) {
           out.push({
@@ -626,13 +628,29 @@ var AgUiEncoder = class {
       ...this.closeText()
     ];
   }
-  callStart(id, name) {
+  /**
+  * `metadata['agora.toolKind']` says whether the call is an `action` (it may park for approval) or
+  * a `read`, and `metadata['agora.parentId']` the call it runs under — what the native
+  * `tool-input-start` frame carries and AG-UI's event has no field for.
+  */
+  callStart(id, name, toolKind, parentId) {
+    const metadata = {
+      ...toolKind !== void 0 ? {
+        "agora.toolKind": toolKind
+      } : {},
+      ...parentId !== void 0 ? {
+        "agora.parentId": parentId
+      } : {}
+    };
     return {
       type: "TOOL_CALL_START",
       toolCallId: id,
       toolCallName: name,
       ...this.stepMessage !== void 0 ? {
         parentMessageId: this.stepMessage
+      } : {},
+      ...Object.keys(metadata).length > 0 ? {
+        metadata
       } : {}
     };
   }
@@ -790,18 +808,23 @@ function readUserTurn(messages) {
     }
   }
   if (last === void 0) return null;
-  if (typeof last.content === "string") return {
-    text: last.content,
-    media: [],
-    dropped: []
-  };
+  if (typeof last.content === "string") {
+    return {
+      text: last.content,
+      media: [],
+      staged: [],
+      dropped: []
+    };
+  }
   if (!Array.isArray(last.content)) return {
     text: "",
     media: [],
+    staged: [],
     dropped: []
   };
   const texts = [];
   const media = [];
+  const staged = [];
   const dropped = [];
   last.content.forEach((part, index) => {
     if (!isRecord(part)) return;
@@ -813,6 +836,12 @@ function readUserTurn(messages) {
       return;
     }
     const source = part.source;
+    if (isRecord(source) && source.type === "file" && source.provider === AG_UI_MEDIA_PROVIDER && typeof source.value === "string" && source.value.length > 0) {
+      staged.push({
+        mediaId: source.value
+      });
+      return;
+    }
     if (!isRecord(source) || source.type !== "data") {
       const how = isRecord(source) && typeof source.type === "string" ? source.type : "unknown";
       dropped.push(`The ${part.type} part ${index + 1} was not used: only inline data is accepted, not a ${how} source.`);
@@ -838,6 +867,7 @@ function readUserTurn(messages) {
   return {
     text: texts.join("\n"),
     media,
+    staged,
     dropped
   };
 }
@@ -872,6 +902,9 @@ function readForwardedProps(forwarded) {
     } : {},
     ...isRecord(forwarded.pageContext) ? {
       pageContext: forwarded.pageContext
+    } : {},
+    ...forwarded.regenerate === true ? {
+      regenerate: true
     } : {}
   };
 }
@@ -971,6 +1004,11 @@ function decodeStreamEvent(line) {
 __name(decodeStreamEvent, "decodeStreamEvent");
 
 // src/ag-ui/stream.ts
+var frameSeqs = /* @__PURE__ */ new WeakMap();
+function frameSeq(frame) {
+  return frameSeqs.get(frame);
+}
+__name(frameSeq, "frameSeq");
 var DEFAULT_QUIET_MS = 750;
 var GRACE_MS = 50;
 async function* agUiEvents(frames, options) {
@@ -997,6 +1035,9 @@ async function* agUiEvents(frames, options) {
         ended = true;
         break;
       }
+      if (options.cursor !== void 0) {
+        options.cursor.seq = frameSeq(next.value) ?? encoder2.consumed + 1;
+      }
       yield* encoder2.encode(next.value);
     }
   } finally {
@@ -1018,8 +1059,10 @@ function raceQuiet(upcoming, ms) {
   });
 }
 __name(raceQuiet, "raceQuiet");
-function agUiSse(event) {
-  return `data: ${JSON.stringify(event)}
+function agUiSse(event, id) {
+  const head = id !== void 0 && id > 0 ? `id: ${id}
+` : "";
+  return `${head}data: ${JSON.stringify(event)}
 
 `;
 }
@@ -1027,7 +1070,14 @@ __name(agUiSse, "agUiSse");
 async function* agUiFramesFromNdjson(chunks) {
   const decoder = new TextDecoder();
   let buffer = "";
+  let seq = 0;
   const read = /* @__PURE__ */ __name((line) => {
+    seq += 1;
+    const frames = parse(line);
+    for (const frame of frames) frameSeqs.set(frame, seq);
+    return frames;
+  }, "read");
+  const parse = /* @__PURE__ */ __name((line) => {
     const event = decodeStreamEvent(line);
     if (event !== null) return [
       event
@@ -1047,7 +1097,7 @@ async function* agUiFramesFromNdjson(chunks) {
         text: line
       }
     ];
-  }, "read");
+  }, "parse");
   try {
     for await (const chunk of chunks) {
       buffer += decoder.decode(chunk, {
@@ -1119,6 +1169,7 @@ function actionProposalDecisionEvents(input) {
 __name(actionProposalDecisionEvents, "actionProposalDecisionEvents");
 export {
   AG_UI_CUSTOM,
+  AG_UI_MEDIA_PROVIDER,
   AG_UI_PROTOCOL_VERSION,
   AgUiEncoder,
   actionProposalDecisionEvents,
@@ -1127,6 +1178,7 @@ export {
   agUiSse,
   decodeInterruptId,
   encodeInterruptId,
+  frameSeq,
   parseRunInput,
   planResume,
   readAnswersPayload,