@dudousxd/nestjs-agent 1.24.2 → 1.25.1

package/README.md

@@ -109,13 +109,15 @@ import { BUILTIN_COMPONENTS } from '@dudousxd/nestjs-agent-core/genui/builtins';
 export const catalog = defineCatalog([...BUILTIN_COMPONENTS, DealCard]);
 
 // app.module.ts
-AgentGenuiModule.forRoot({ catalog, mode: 'tree', terminal: true });
+AgentGenuiModule.forRoot({ catalog, terminal: true });
 ```
 
-It registers the tools (`ui__show_<component>` per component by default, one `ui__render` in `tree`
-mode, plus a generic `ui__show` taking `{ component, props }` with `showTool: true`), validating
-every call against the catalog. Options: `mode`, `terminal`, `treeToolName`, `treeInstructions`,
-`treeLimits`, `namePrefix`, `showTool`, `showInstructions`, `roles`, `presentation`.
+It registers the tools (one `ui__render` tree tool by default, `ui__show_<component>` per component
+with `mode: 'per-component'`, plus a generic `ui__show` taking `{ component, props }` with
+`showTool: true`), validating every call against the catalog. Options: `mode`, `treeSchema`,
+`streaming` (`'partial'` draws the tree while the model writes it), `streamingThrottleMs`,
+`terminal`, `treeToolName`, `treeInstructions`, `treeLimits`, `namePrefix`, `showTool`,
+`showInstructions`, `roles`, `presentation`.
 `forRootAsync({ imports, inject, useFactory })` builds them from config. The catalog is injectable
 (`@InjectGenuiCatalog()`, token `GENUI_CATALOG`) and replaceable in a test with
 `overrideProvider(GENUI_CATALOG)` — the tools are built from the injected one.
@@ -149,6 +151,12 @@ With nothing bound to `AGENT_ATTACHMENT_STAGING` there is no way to tell whose m
 turn carrying attachments is refused with `501`. Text-only turns are unaffected. At most 10
 attachments per turn.
 
+A send must carry something to answer: a non-blank `message`, an attachment, or `regenerate: true`.
+Anything else (`{}`, a blank message) is `400 { code: 'no_user_message' }` (`NO_USER_MESSAGE_CODE`)
+before any thread, run or queue entry exists, on `POST /agent/chat`, the AG-UI route and
+`AgentService.send` / `chat` alike; a `message` that is not a string is `400 invalid_message`. An
+attachment-only send runs with an empty text.
+
 `POST /agent/attachments` (multipart, live whenever a staging store is bound — `501` otherwise)
 aborts a body larger than `HARD_MAX_ATTACHMENT_BYTES` (32 MiB) while it streams; the configured
 `maxBytes` narrows that ceiling at request time and cannot raise it. The limits come from ONE place:

package/dist/durable/index.cjs

@@ -159,7 +159,19 @@ var AgentRunSteps = class {
       const opened = await deps.sink.open(input.sinkRunId);
       writer = input.childSink ? childSinkWriter(opened) : opened;
     }
-    const frames = (0, import_nestjs_agent_core3.observeTurnFrames)(writer);
+    const previews = (0, import_nestjs_agent_core3.previewToolInputs)(writer, (0, import_nestjs_agent_core3.registryInputPreviews)(deps.registry, tools, {
+      actor: input.actor,
+      ...input.threadId !== void 0 ? {
+        threadId: input.threadId
+      } : {},
+      ...input.agentName !== void 0 ? {
+        agentName: input.agentName
+      } : {},
+      ...input.preflightContext?.uiCapabilities !== void 0 ? {
+        uiCapabilities: input.preflightContext.uiCapabilities
+      } : {}
+    }));
+    const frames = (0, import_nestjs_agent_core3.observeTurnFrames)(previews.writer);
     const turn = (0, import_nestjs_agent_core3.withTurnFrames)(await (0, import_nestjs_agent_core3.traceLlmTurn)(input.runId, input.step, () => deps.model.runTurn({
       system: input.system,
       messages: input.messages,
@@ -231,8 +243,13 @@ var AgentRunSteps = class {
         };
       }
     }
-    return buffer === void 0 ? stamped : {
+    const shown = previews.shown();
+    const previewed = shown.length > 0 ? {
       ...stamped,
+      previews: shown
+    } : stamped;
+    return buffer === void 0 ? previewed : {
+      ...previewed,
       bufferedFrames: buffer.frames()
     };
   }
@@ -1825,9 +1842,13 @@ var ActionProposalService = class {
   /** The words a text decision is made of, and what the agent answers — English unless configured. */
   vocabulary;
   replies;
+  hasCapability() {
+    const store = this.store;
+    return typeof store.getThreadActionProposalScope === "function" && typeof store.listActionProposals === "function";
+  }
   capability() {
     const store = this.store;
-    if (typeof store.getThreadActionProposalScope !== "function" || typeof store.listActionProposals !== "function") throw new import_common7.NotImplementedException("Action proposals are unavailable");
+    if (!this.hasCapability()) throw new import_common7.NotImplementedException("Action proposals are unavailable");
     return store;
   }
   async scope(threadId, actor) {
@@ -1843,7 +1864,16 @@ var ActionProposalService = class {
       requesterRef: proposal.actorRef
     });
   }
+  /**
+  * One page of a thread's proposals this actor may see. A store without the proposal capability
+  * can only run blocking approvals, so a thread there has no proposals: an empty, final page rather
+  * than `501` — a client that lists by default (React's `useAgentChat`) needs no flag. Deciding one
+  * still answers `501`.
+  */
   async listPage(threadId, actor, query = {}) {
+    if (!this.hasCapability()) return {
+      items: []
+    };
     const scope = await this.scope(threadId, actor);
     const rows = await this.capability().listActionProposals(scope, {
       limit: 1e3,
@@ -2515,6 +2545,30 @@ function _ts_param7(paramIndex, decorator) {
   };
 }
 __name(_ts_param7, "_ts_param");
+var NO_USER_MESSAGE_CODE = "no_user_message";
+function sendableParams(params) {
+  const message = params.message;
+  if (message !== void 0 && message !== null && typeof message !== "string") {
+    throw new import_common10.BadRequestException({
+      statusCode: 400,
+      code: "invalid_message",
+      message: "message must be a string"
+    });
+  }
+  const text = typeof message === "string" ? message : "";
+  if (text.trim().length === 0 && (params.attachments?.length ?? 0) === 0 && params.regenerate !== true) {
+    throw new import_common10.BadRequestException({
+      statusCode: 400,
+      code: NO_USER_MESSAGE_CODE,
+      message: "nothing to answer: send a non-empty message, an attachment, or regenerate"
+    });
+  }
+  return text === message ? params : {
+    ...params,
+    message: text
+  };
+}
+__name(sendableParams, "sendableParams");
 var AgentService = class {
   static {
     __name(this, "AgentService");
@@ -2577,12 +2631,13 @@ var AgentService = class {
   }
   /**
   * 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.
+  * decide them; what `GET <base>/threads/:threadId/action-proposals` serves (its first page).
+  * Without independent approvals (the default blocking mode) there are none, so the read answers an
+  * empty list rather than refusing; deciding one still refuses.
   */
   async listActionProposals(actor, threadId) {
     if (this.options?.actionApprovalMode !== "independent" || !this.proposals) {
-      throw new import_common10.NotFoundException("Proposal not found");
+      return [];
     }
     return this.proposals.list(threadId, actor);
   }
@@ -2782,7 +2837,8 @@ var AgentService = class {
   * Send a message: start a turn, or — when its thread already has one running — queue the message
   * to run after it (see {@link ChatSendMode}). What `POST <base>/chat` calls.
   */
-  async send(params, sendOptions = {}) {
+  async send(claimed, sendOptions = {}) {
+    const params = sendableParams(claimed);
     if (sendOptions.textDecisions !== false && this.options?.actionApprovalMode === "independent" && params.threadId !== void 0 && params.regenerate !== true && this.proposals) {
       const decision = await this.proposals.handleTextDecision(params.threadId, params.actor, params.message);
       if ("proposalDecision" in decision) return decision;
@@ -6461,6 +6517,11 @@ var InlineAgentRunner = class _InlineAgentRunner {
   * running it. A cancelled id is dropped once the run settles, so the set tracks live runs only.
   */
   cancelled = /* @__PURE__ */ new Set();
+  /**
+  * Aborted by {@link cancel}: what cuts short the model call or tool a stopped run is in (the
+  * loop's `abortSignal` hook). Keyed like {@link cancelled}, and dropped with it.
+  */
+  aborts = /* @__PURE__ */ new Map();
   /** Top-level runs this process is running now — what {@link isRunActive} answers from. */
   live = /* @__PURE__ */ new Set();
   constructor(factory, store, queue) {
@@ -6530,7 +6591,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
       await (0, import_nestjs_agent_core37.releaseThreadRun)(this.store, input.threadId, runId);
       await writer.fail((0, import_nestjs_agent_core37.streamFailure)(error));
     }).finally(() => {
-      this.cancelled.delete(runId);
+      this.forgetCancel(runId);
       this.live.delete(runId);
     });
     return {
@@ -6549,8 +6610,10 @@ var InlineAgentRunner = class _InlineAgentRunner {
   * Ask a run to stop, and settle whatever it was parked on.
   *
   * The loop observes the request at its next safe point (between steps, before the turn's tools) and
-  * unwinds from there — so a tool already executing is left to finish, and its result is recorded
-  * exactly as it would have been. What this cannot wait for is a turn parked on a human: that wait
+  * unwinds from there. What the run is in right now is aborted (its `abortSignal`): the model call
+  * streaming the answer ends at once and the step it was writing is not persisted, and a tool that
+  * passes `ctx.abortSignal` on is cut short and recorded failed; a tool that ignores the signal is
+  * left to finish, and its result is recorded exactly as it would have been. What this cannot wait for is a turn parked on a human: that wait
   * is a promise nobody is going to resolve, so it is REJECTED here with the same
   * {@link RunCancelledError} the loop would have thrown, and the run unwinds through the identical
   * path.
@@ -6561,6 +6624,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
   */
   async cancel(runId) {
     this.cancelled.add(runId);
+    this.aborts.get(runId)?.abort(new import_nestjs_agent_core37.RunCancelledError());
     for (const [key, waiter] of this.pending) {
       if (key.startsWith(`${runId}:`)) {
         this.pending.delete(key);
@@ -6569,6 +6633,20 @@ var InlineAgentRunner = class _InlineAgentRunner {
     }
     await Promise.resolve();
   }
+  /** The signal {@link cancel} aborts for `runId` — one per run, shared by its awaited delegates. */
+  abortSignalFor(runId) {
+    let controller = this.aborts.get(runId);
+    if (controller === void 0) {
+      controller = new AbortController();
+      this.aborts.set(runId, controller);
+    }
+    return controller.signal;
+  }
+  /** Drop a settled run's Stop: its flag and its abort controller. */
+  forgetCancel(runId) {
+    this.cancelled.delete(runId);
+    this.aborts.delete(runId);
+  }
   /**
   * The single place a cancelled run's state is settled: recorded as its own terminal (never
   * `failed` — a user pressing Stop must not land in someone's error rate), the thread released, and
@@ -6688,6 +6766,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
       step: /* @__PURE__ */ __name((_name, fn) => fn(), "step"),
       parallel: import_nestjs_agent_core37.settleAll,
       cancelled: /* @__PURE__ */ __name(async () => this.cancelled.has(runId), "cancelled"),
+      abortSignal: this.abortSignalFor(runId),
       runAgent: /* @__PURE__ */ __name((agentName, task) => this.runNested({
         agentName,
         task,
@@ -6739,6 +6818,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
       step: /* @__PURE__ */ __name((_name, fn) => fn(), "step"),
       parallel: import_nestjs_agent_core37.settleAll,
       cancelled: /* @__PURE__ */ __name(async () => this.cancelled.has(runId), "cancelled"),
+      abortSignal: this.abortSignalFor(runId),
       runAgent: /* @__PURE__ */ __name((childName, childTask) => this.runNested({
         agentName: childName,
         task: childTask,
@@ -6814,7 +6894,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
         }
       });
     }).finally(async () => {
-      this.cancelled.delete(runId);
+      this.forgetCancel(runId);
       await this.store.setActiveStream(subThread.id, null);
     });
     return {
@@ -6846,6 +6926,8 @@ var InlineAgentRunner = class _InlineAgentRunner {
       // A child stops when it is cancelled OR when the run a human is actually watching is: the
       // canceller names the top-level run, which is the only id that ever left the server.
       cancelled: /* @__PURE__ */ __name(async () => this.cancelled.has(runId) || this.cancelled.has(sinkRunId), "cancelled"),
+      // Aborted by a Stop on the run the human is watching, which is the id a canceller names.
+      abortSignal: this.abortSignalFor(sinkRunId),
       runAgent: /* @__PURE__ */ __name((childName, childTask) => this.runNested({
         agentName: childName,
         task: childTask,