@dudousxd/nestjs-agent 1.24.2 → 1.25.0

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit, ConflictExce
 import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter, e as AgentSkillsOptions } from './chat-queue.service-Crf9uwum.cjs';
 export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentEngine, j as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, k as QueueSettleOutcome, l as QueuedTurn, m as QueuedTurnStarter, n as QuotaLimits, o as QuotaWindowLimits, p as defineTool, q as delegateToolName, r as provideAgentTool, s as provideAgentTools, u as utcDay } from './chat-queue.service-Crf9uwum.cjs';
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
-import { AgentAttachmentConfig, AttachmentStagingStore, AgentStore, Actor, ListActionProposals, ActionProposalMutationView, TextActionProposalVocabulary, AgentRunner, ModelCatalog, QuotaProvider, ActionApprovalMode, ActionProposalView, MessageAttachment, QuotaReport, ModelCatalogView, AgentHostContext, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver, AgentApprovalPort, AgentClientConfig, ToolSpec, ToolPresentation, AgentHistoryWindow, AgentIntake, Persona, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter, ActionProposal } from '@dudousxd/nestjs-agent-core';
+import { AgentAttachmentConfig, AttachmentStagingStore, AgentStore, Actor, ListActionProposals, ActionProposalView, ActionProposalMutationView, TextActionProposalVocabulary, AgentRunner, ModelCatalog, QuotaProvider, ActionApprovalMode, MessageAttachment, QuotaReport, ModelCatalogView, AgentHostContext, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver, AgentApprovalPort, AgentClientConfig, ToolSpec, ToolPresentation, AgentHistoryWindow, AgentIntake, Persona, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter, ActionProposal } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 export { FunctionalToolDefinition } from '@dudousxd/nestjs-agent-core';
 import { Request, Response } from 'express';
@@ -37,17 +37,21 @@ declare class ActionProposalService {
     /** The words a text decision is made of, and what the agent answers — English unless configured. */
     private readonly vocabulary;
     private readonly replies;
+    private hasCapability;
     private capability;
     private scope;
     private mayDecide;
+    /**
+     * 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`.
+     */
     listPage(threadId: string, actor: Actor, query?: Pick<ListActionProposals, 'after'>): Promise<{
-        next?: {
-            createdAt: number;
-            id: string;
-        };
-        items: _dudousxd_nestjs_agent_core.ActionProposalView[];
+        items: ActionProposalView[];
+        next?: NonNullable<ListActionProposals['after']>;
     }>;
-    list(threadId: string, actor: Actor): Promise<_dudousxd_nestjs_agent_core.ActionProposalView[]>;
+    list(threadId: string, actor: Actor): Promise<ActionProposalView[]>;
     decide(threadId: string, proposalId: string, actor: Actor, command: {
         decision: 'approved' | 'rejected';
         remember?: boolean;
@@ -221,8 +225,9 @@ declare class AgentService {
     actionProposalReply(result: Pick<ActionProposalMutationView, 'status' | 'proposal'>, decision: 'approved' | 'rejected'): string;
     /**
      * 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.
      */
     listActionProposals(actor: Actor, threadId: string): Promise<ActionProposalView[]>;
     /**
@@ -1248,6 +1253,11 @@ declare class InlineAgentRunner implements AgentRunner {
      * running it. A cancelled id is dropped once the run settles, so the set tracks live runs only.
      */
     private readonly cancelled;
+    /**
+     * 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.
+     */
+    private readonly aborts;
     /** Top-level runs this process is running now — what {@link isRunActive} answers from. */
     private readonly live;
     constructor(factory: AgentDepsFactory, store: AgentStore, queue?: ChatQueueService | undefined);
@@ -1264,8 +1274,10 @@ declare class InlineAgentRunner implements AgentRunner {
      * 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.
@@ -1275,6 +1287,10 @@ declare class InlineAgentRunner implements AgentRunner {
      * each and can never both write.
      */
     cancel(runId: string): Promise<void>;
+    /** The signal {@link cancel} aborts for `runId` — one per run, shared by its awaited delegates. */
+    private abortSignalFor;
+    /** Drop a settled run's Stop: its flag and its abort controller. */
+    private forgetCancel;
     /**
      * 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

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit, ConflictExce
 import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter, e as AgentSkillsOptions } from './chat-queue.service-ZQkqb1Yw.js';
 export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentEngine, j as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, k as QueueSettleOutcome, l as QueuedTurn, m as QueuedTurnStarter, n as QuotaLimits, o as QuotaWindowLimits, p as defineTool, q as delegateToolName, r as provideAgentTool, s as provideAgentTools, u as utcDay } from './chat-queue.service-ZQkqb1Yw.js';
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
-import { AgentAttachmentConfig, AttachmentStagingStore, AgentStore, Actor, ListActionProposals, ActionProposalMutationView, TextActionProposalVocabulary, AgentRunner, ModelCatalog, QuotaProvider, ActionApprovalMode, ActionProposalView, MessageAttachment, QuotaReport, ModelCatalogView, AgentHostContext, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver, AgentApprovalPort, AgentClientConfig, ToolSpec, ToolPresentation, AgentHistoryWindow, AgentIntake, Persona, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter, ActionProposal } from '@dudousxd/nestjs-agent-core';
+import { AgentAttachmentConfig, AttachmentStagingStore, AgentStore, Actor, ListActionProposals, ActionProposalView, ActionProposalMutationView, TextActionProposalVocabulary, AgentRunner, ModelCatalog, QuotaProvider, ActionApprovalMode, MessageAttachment, QuotaReport, ModelCatalogView, AgentHostContext, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver, AgentApprovalPort, AgentClientConfig, ToolSpec, ToolPresentation, AgentHistoryWindow, AgentIntake, Persona, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter, ActionProposal } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 export { FunctionalToolDefinition } from '@dudousxd/nestjs-agent-core';
 import { Request, Response } from 'express';
@@ -37,17 +37,21 @@ declare class ActionProposalService {
     /** The words a text decision is made of, and what the agent answers — English unless configured. */
     private readonly vocabulary;
     private readonly replies;
+    private hasCapability;
     private capability;
     private scope;
     private mayDecide;
+    /**
+     * 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`.
+     */
     listPage(threadId: string, actor: Actor, query?: Pick<ListActionProposals, 'after'>): Promise<{
-        next?: {
-            createdAt: number;
-            id: string;
-        };
-        items: _dudousxd_nestjs_agent_core.ActionProposalView[];
+        items: ActionProposalView[];
+        next?: NonNullable<ListActionProposals['after']>;
     }>;
-    list(threadId: string, actor: Actor): Promise<_dudousxd_nestjs_agent_core.ActionProposalView[]>;
+    list(threadId: string, actor: Actor): Promise<ActionProposalView[]>;
     decide(threadId: string, proposalId: string, actor: Actor, command: {
         decision: 'approved' | 'rejected';
         remember?: boolean;
@@ -221,8 +225,9 @@ declare class AgentService {
     actionProposalReply(result: Pick<ActionProposalMutationView, 'status' | 'proposal'>, decision: 'approved' | 'rejected'): string;
     /**
      * 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.
      */
     listActionProposals(actor: Actor, threadId: string): Promise<ActionProposalView[]>;
     /**
@@ -1248,6 +1253,11 @@ declare class InlineAgentRunner implements AgentRunner {
      * running it. A cancelled id is dropped once the run settles, so the set tracks live runs only.
      */
     private readonly cancelled;
+    /**
+     * 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.
+     */
+    private readonly aborts;
     /** Top-level runs this process is running now — what {@link isRunActive} answers from. */
     private readonly live;
     constructor(factory: AgentDepsFactory, store: AgentStore, queue?: ChatQueueService | undefined);
@@ -1264,8 +1274,10 @@ declare class InlineAgentRunner implements AgentRunner {
      * 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.
@@ -1275,6 +1287,10 @@ declare class InlineAgentRunner implements AgentRunner {
      * each and can never both write.
      */
     cancel(runId: string): Promise<void>;
+    /** The signal {@link cancel} aborts for `runId` — one per run, shared by its awaited delegates. */
+    private abortSignalFor;
+    /** Drop a settled run's Stop: its flag and its abort controller. */
+    private forgetCancel;
     /**
      * 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

package/dist/index.js

@@ -666,9 +666,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 NotImplementedException("Action proposals are unavailable");
+    if (!this.hasCapability()) throw new NotImplementedException("Action proposals are unavailable");
     return store;
   }
   async scope(threadId, actor) {
@@ -684,7 +688,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,
@@ -1418,12 +1431,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 NotFoundException2("Proposal not found");
+      return [];
     }
     return this.proposals.list(threadId, actor);
   }
@@ -5417,6 +5431,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) {
@@ -5486,7 +5505,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
       await releaseThreadRun(this.store, input.threadId, runId);
       await writer.fail(streamFailure2(error));
     }).finally(() => {
-      this.cancelled.delete(runId);
+      this.forgetCancel(runId);
       this.live.delete(runId);
     });
     return {
@@ -5505,8 +5524,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.
@@ -5517,6 +5538,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
   */
   async cancel(runId) {
     this.cancelled.add(runId);
+    this.aborts.get(runId)?.abort(new RunCancelledError());
     for (const [key, waiter] of this.pending) {
       if (key.startsWith(`${runId}:`)) {
         this.pending.delete(key);
@@ -5525,6 +5547,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
@@ -5644,6 +5680,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
       step: /* @__PURE__ */ __name((_name, fn) => fn(), "step"),
       parallel: settleAll,
       cancelled: /* @__PURE__ */ __name(async () => this.cancelled.has(runId), "cancelled"),
+      abortSignal: this.abortSignalFor(runId),
       runAgent: /* @__PURE__ */ __name((agentName, task) => this.runNested({
         agentName,
         task,
@@ -5695,6 +5732,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
       step: /* @__PURE__ */ __name((_name, fn) => fn(), "step"),
       parallel: 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,
@@ -5770,7 +5808,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
         }
       });
     }).finally(async () => {
-      this.cancelled.delete(runId);
+      this.forgetCancel(runId);
       await this.store.setActiveStream(subThread.id, null);
     });
     return {
@@ -5802,6 +5840,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,