@dudousxd/nestjs-agent 1.23.0 → 1.24.0

package/dist/index.cjs

@@ -673,6 +673,31 @@ function childSinkWriter(writer) {
 }
 __name(childSinkWriter, "childSinkWriter");
 
+// src/attachment-limits.ts
+var DEFAULT_MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+var DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES = [
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+  "application/pdf",
+  "text/plain",
+  "text/csv"
+];
+var MAX_ATTACHMENTS_PER_MESSAGE = 10;
+function attachmentLimits(options, staging) {
+  const declared = staging?.describe?.();
+  const own = options?.attachments;
+  return {
+    enabled: staging !== void 0,
+    upload: staging === void 0 ? null : declared?.upload ?? "multipart",
+    maxBytes: declared?.maxBytes ?? own?.maxBytes ?? DEFAULT_MAX_ATTACHMENT_BYTES,
+    allowedContentTypes: declared?.allowedContentTypes ?? own?.allowedContentTypes ?? DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES,
+    maxPerMessage: MAX_ATTACHMENTS_PER_MESSAGE
+  };
+}
+__name(attachmentLimits, "attachmentLimits");
+
 // src/proposals/action-proposal.service.ts
 var import_nestjs_agent_core5 = require("@dudousxd/nestjs-agent-core");
 var import_common3 = require("@nestjs/common");
@@ -829,6 +854,10 @@ var ActionProposalService = class {
       text: this.reply(result, decision)
     };
   }
+  /** The configured words a text decision is made of (`actionProposalText.vocabulary`). */
+  textVocabulary() {
+    return this.vocabulary;
+  }
   /** The configured reply to a decision the store answered with `result`. */
   reply(result, decision) {
     return (0, import_nestjs_agent_core5.textActionProposalReply)(result, decision, this.replies);
@@ -1455,6 +1484,65 @@ var AgentService = class {
     };
     return this.proposals.handleTextDecision(threadId, actor, text);
   }
+  /** How `action` tools wait for their approval here — `AgentModule.forRoot({ actionApprovalMode })`. */
+  actionApprovalMode() {
+    return this.options?.actionApprovalMode ?? "blocking";
+  }
+  /**
+  * The words a text decision is made of (`actionProposalText.vocabulary`, English by default) — what
+  * a surface without buttons tells the person to reply.
+  */
+  actionProposalVocabulary() {
+    return this.proposals?.textVocabulary() ?? import_nestjs_agent_core9.DEFAULT_TEXT_ACTION_PROPOSAL_VOCABULARY;
+  }
+  /** The configured reply (`actionProposalText.replies`) to a decision the store answered with `result`. */
+  actionProposalReply(result, decision) {
+    return this.proposals?.reply(result, decision) ?? (0, import_nestjs_agent_core9.textActionProposalReply)(result, decision);
+  }
+  /**
+  * The proposals of a thread this actor may see — the thread's own actor, or one the policy lets
+  * decide them; what `GET <base>/threads/:threadId/action-proposals` serves (its first page). `404`
+  * when independent approvals are not on.
+  */
+  async listActionProposals(actor, threadId) {
+    if (this.options?.actionApprovalMode !== "independent" || !this.proposals) {
+      throw new import_common6.NotFoundException("Proposal not found");
+    }
+    return this.proposals.list(threadId, actor);
+  }
+  /**
+  * The attachment rules in force — what `GET <base>/config` serves and `POST <base>/attachments`
+  * enforces. `enabled: false` when no `AGENT_ATTACHMENT_STAGING` provider is bound.
+  */
+  attachmentLimits() {
+    return attachmentLimits(this.options, this.staging);
+  }
+  /**
+  * Stage a file for a later turn, held to the same limits as `POST <base>/attachments` — for a
+  * surface that receives files itself (a messaging webhook). Refuses with `501` when attachments are
+  * off, `415` for a type outside the allowlist and `413` past the size cap; send the returned
+  * `mediaId` as `attachments: [{ mediaId }]`.
+  */
+  async stageAttachment(actor, file) {
+    if (this.staging === void 0) {
+      throw new import_common6.NotImplementedException("Attachments are not configured on this server: bind AGENT_ATTACHMENT_STAGING (e.g. import AgentMediaAttachmentsModule).");
+    }
+    const { allowedContentTypes, maxBytes } = this.attachmentLimits();
+    const contentType = file.contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+    if (!allowedContentTypes.includes(contentType)) {
+      throw new import_common6.UnsupportedMediaTypeException(`content type "${contentType}" is not allowed (allowed: ${allowedContentTypes.join(", ")})`);
+    }
+    if (file.data.byteLength > maxBytes) {
+      throw new import_common6.PayloadTooLargeException(`file exceeds the ${maxBytes}-byte limit`);
+    }
+    return this.staging.stage({
+      data: file.data,
+      filename: file.filename,
+      contentType,
+      sizeBytes: file.data.byteLength,
+      actor
+    });
+  }
   /** The queue service when the bound store can hold a queue, else `undefined`. */
   queueing() {
     return this.queue?.supported === true ? this.queue : void 0;
@@ -2738,33 +2826,6 @@ AgentsController = _ts_decorate7([
 var import_nestjs_agent_core11 = require("@dudousxd/nestjs-agent-core");
 var import_common9 = require("@nestjs/common");
 var import_platform_express = require("@nestjs/platform-express");
-
-// src/attachment-limits.ts
-var DEFAULT_MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
-var DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES = [
-  "image/png",
-  "image/jpeg",
-  "image/gif",
-  "image/webp",
-  "application/pdf",
-  "text/plain",
-  "text/csv"
-];
-var MAX_ATTACHMENTS_PER_MESSAGE = 10;
-function attachmentLimits(options, staging) {
-  const declared = staging?.describe?.();
-  const own = options?.attachments;
-  return {
-    enabled: staging !== void 0,
-    upload: staging === void 0 ? null : declared?.upload ?? "multipart",
-    maxBytes: declared?.maxBytes ?? own?.maxBytes ?? DEFAULT_MAX_ATTACHMENT_BYTES,
-    allowedContentTypes: declared?.allowedContentTypes ?? own?.allowedContentTypes ?? DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES,
-    maxPerMessage: MAX_ATTACHMENTS_PER_MESSAGE
-  };
-}
-__name(attachmentLimits, "attachmentLimits");
-
-// src/controller/attachments.controller.ts
 function _ts_decorate8(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
@@ -5167,6 +5228,34 @@ var ActionProposalWorkerService = class _ActionProposalWorkerService {
   deps;
   worker;
   logger = new import_common24.Logger(_ActionProposalWorkerService.name);
+  settledListeners = /* @__PURE__ */ new Set();
+  /**
+  * Run `listener` after every proposal this process's worker settles — how a module relays an
+  * outcome somewhere the turn's stream no longer reaches (a text channel's conversation). Next to
+  * `actionProposalWorker.onSettled`; a listener that throws is logged and does not stop the others.
+  * Returns the unsubscribe. Only the replicas that run the worker (not `surface: 'http'`) call it.
+  */
+  onSettled(listener) {
+    this.settledListeners.add(listener);
+    return () => {
+      this.settledListeners.delete(listener);
+    };
+  }
+  async settled(proposal) {
+    const configured = this.options.actionProposalWorker?.onSettled;
+    for (const listener of [
+      ...configured ? [
+        configured
+      ] : [],
+      ...this.settledListeners
+    ]) {
+      try {
+        await listener(proposal);
+      } catch (error) {
+        this.logger.error(error);
+      }
+    }
+  }
   constructor(store, options, deps) {
     this.store = store;
     this.options = options;
@@ -5182,6 +5271,7 @@ var ActionProposalWorkerService = class _ActionProposalWorkerService {
       store: this.store,
       workerId: (0, import_node_crypto2.randomUUID)(),
       ...this.options.actionProposalWorker,
+      onSettled: /* @__PURE__ */ __name((proposal) => this.settled(proposal), "onSettled"),
       executor: new import_nestjs_agent_core29.ActionProposalExecutor({
         resolver,
         resolveExecution: /* @__PURE__ */ __name(async (proposal, actor) => {
@@ -6452,7 +6542,10 @@ var AgUiRunHandler = class {
     if (owner !== null && owner !== actor.id) {
       throw new import_common28.ForbiddenException("thread belongs to another actor");
     }
-    if (owner !== null && turn.media.length === 0) {
+    if (forwarded.regenerate === true && owner === null) {
+      throw invalid("invalid_input", "regenerate needs a thread that already has an exchange");
+    }
+    if (owner !== null && forwarded.regenerate !== true && turn.media.length === 0 && turn.staged.length === 0) {
       const decision = await this.agent.handleTextDecision(input.threadId, actor, turn.text);
       if ("proposalDecision" in decision) {
         this.writeEvents(res, [
@@ -6467,7 +6560,7 @@ var AgUiRunHandler = class {
         return;
       }
     }
-    const refs = await this.stage(actor, turn.media, warnings);
+    const refs = await this.stage(actor, turn.media, warnings, turn.staged);
     if (turn.text.trim().length === 0 && refs.length === 0) {
       throw invalid("no_user_message", "the user message to answer is empty");
     }
@@ -6503,6 +6596,9 @@ var AgUiRunHandler = class {
       } : {},
       ...refs.length > 0 ? {
         attachments: refs
+      } : {},
+      ...forwarded.regenerate === true ? {
+        regenerate: true
       } : {}
     });
     await this.pipe(res, started.runId, {
@@ -6514,10 +6610,25 @@ var AgUiRunHandler = class {
       preamble: warningEvents(warnings)
     });
   }
-  /** Stage the turn's inline media through the bound store, within its limits; say what was not used. */
-  async stage(actor, media, warnings) {
+  /**
+  * The turn's attachments: the ones already staged (by mediaId), then its inline media staged
+  * through the bound store — all within the store's limits; say what was not used.
+  */
+  async stage(actor, media, warnings, staged = []) {
     const refs = [];
     const limits = attachmentLimits(this.options, this.staging);
+    for (const ref of staged) {
+      const label = `The attachment ${ref.mediaId} was not used`;
+      if (this.staging === void 0) {
+        warnings.push(`${label}: attachments are not enabled on this agent.`);
+      } else if (refs.length >= limits.maxPerMessage) {
+        warnings.push(`${label}: a message carries at most ${limits.maxPerMessage} attachments.`);
+      } else {
+        refs.push({
+          mediaId: ref.mediaId
+        });
+      }
+    }
     for (const item of media) {
       const label = `The ${item.kind} "${item.filename}" was not used`;
       if (this.staging === void 0) {
@@ -6530,7 +6641,7 @@ var AgUiRunHandler = class {
         warnings.push(`${label}: it is larger than ${limits.maxBytes} bytes.`);
       } else {
         try {
-          const staged = await this.staging.stage({
+          const staged2 = await this.staging.stage({
             data: item.data,
             filename: item.filename,
             contentType: item.contentType,
@@ -6538,7 +6649,7 @@ var AgUiRunHandler = class {
             actor
           });
           refs.push({
-            mediaId: staged.mediaId
+            mediaId: staged2.mediaId
           });
         } catch {
           warnings.push(`${label}: it could not be stored.`);
@@ -6656,11 +6767,17 @@ var AgUiRunHandler = class {
     res.setHeader("X-Agent-Run-Id", runId);
     res.flushHeaders();
     let terminal = false;
+    const cursor = {
+      seq: 0
+    };
     try {
       const frames = (0, import_ag_ui.agUiFramesFromNdjson)(this.agent.subscribe(runId));
-      for await (const event of (0, import_ag_ui.agUiEvents)(frames, options)) {
+      for await (const event of (0, import_ag_ui.agUiEvents)(frames, {
+        ...options,
+        cursor
+      })) {
         if (event.type === "RUN_FINISHED" || event.type === "RUN_ERROR") terminal = true;
-        res.write((0, import_ag_ui.agUiSse)(event));
+        res.write((0, import_ag_ui.agUiSse)(event, cursor.seq));
       }
     } catch {
       if (!terminal) {