@dudousxd/nestjs-agent 1.15.0 → 1.16.1

package/README.md

@@ -311,6 +311,8 @@ starts under its own id, and the settling turn's stream says so in a final `queu
 (`started: { messageId, runId }`). `mode: 'interrupt'` cancels the running turn and runs the message
 next; `mode: 'queue'` always queues. A failed turn or a Stop pauses the queue (`POST
 /agent/threads/:id/queue/resume` lifts it); an exhausted quota pauses it as the next message starts.
+`POST /agent/queue/:messageId/interrupt` runs a message that is already waiting now — it moves to
+the head as an interrupt and the running turn is cancelled for it, in one request.
 `GET`/`DELETE /agent/threads/:id/queue`, `PATCH`/`DELETE /agent/queue/:messageId` list, clear,
 edit, move and remove what is waiting.
 

package/dist/durable/index.cjs

@@ -32,7 +32,7 @@ module.exports = __toCommonJS(durable_exports);
 // src/durable/agent-run.workflow.ts
 var import_nestjs_agent_core3 = require("@dudousxd/nestjs-agent-core");
 var import_nestjs_durable2 = require("@dudousxd/nestjs-durable");
-var import_nestjs_durable_core = require("@dudousxd/nestjs-durable-core");
+var import_nestjs_durable_core2 = require("@dudousxd/nestjs-durable-core");
 var import_common3 = require("@nestjs/common");
 
 // src/agent-deps.ts
@@ -482,6 +482,19 @@ __name(queueFrame, "queueFrame");
 var import_nestjs_agent_core2 = require("@dudousxd/nestjs-agent-core");
 var import_nestjs_durable = require("@dudousxd/nestjs-durable");
 var import_common2 = require("@nestjs/common");
+
+// src/durable/outside-workflow-ctx.ts
+var import_nestjs_durable_core = require("@dudousxd/nestjs-durable-core");
+function outsideWorkflowCtx(fn) {
+  return (0, import_nestjs_durable_core.runInWorkflowCtx)(void 0, fn);
+}
+__name(outsideWorkflowCtx, "outsideWorkflowCtx");
+function stepOf(ctx) {
+  return (name, fn, ...rest) => ctx.localStep(name, (...args) => outsideWorkflowCtx(() => fn(...args)), ...rest);
+}
+__name(stepOf, "stepOf");
+
+// src/durable/agent-run.steps.ts
 function _ts_decorate2(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") {
@@ -522,7 +535,10 @@ var AgentRunSteps = class {
   * double-writes. NEVER call `writer.end()`/`fail()` here: the workflow owns the stream's lifecycle,
   * across however many turns/retries it takes.
   */
-  async llm(input) {
+  llm(input) {
+    return outsideWorkflowCtx(() => this.runLlm(input));
+  }
+  async runLlm(input) {
     const deps = this.factory.forAgent(input.agentName);
     const tools = (0, import_nestjs_agent_core2.withMemoryTool)({
       tools: (0, import_nestjs_agent_core2.withSkillTool)({
@@ -575,7 +591,10 @@ var AgentRunSteps = class {
   * bounds engine liveness (retryable) rather than the tool's own business outcome — and per
   * ATTEMPT, so a retried invocation gets its own fresh timeout window.
   */
-  async tool(input) {
+  tool(input) {
+    return outsideWorkflowCtx(() => this.runTool(input));
+  }
+  async runTool(input) {
     const deps = this.factory.forAgent(input.ctx.agentName);
     if (deps.registry.spec(input.toolName)?.kind === "action" && input.toolType !== "action") {
       throw new Error(`tool "${input.toolName}" is an action tool but was dispatched without approval: the dispatching process resolved its kind against a registry that does not have it`);
@@ -627,7 +646,7 @@ _ts_decorate2([
   _ts_metadata2("design:paramtypes", [
     typeof DispatchedLlmInput === "undefined" ? Object : DispatchedLlmInput
   ]),
-  _ts_metadata2("design:returntype", Promise)
+  _ts_metadata2("design:returntype", typeof Promise === "undefined" ? Object : Promise)
 ], AgentRunSteps.prototype, "llm", null);
 _ts_decorate2([
   (0, import_nestjs_durable.Step)(),
@@ -635,7 +654,7 @@ _ts_decorate2([
   _ts_metadata2("design:paramtypes", [
     typeof DispatchedToolInput === "undefined" ? Object : DispatchedToolInput
   ]),
-  _ts_metadata2("design:returntype", Promise)
+  _ts_metadata2("design:returntype", typeof Promise === "undefined" ? Object : Promise)
 ], AgentRunSteps.prototype, "tool", null);
 AgentRunSteps = _ts_decorate2([
   (0, import_common2.Injectable)(),
@@ -705,7 +724,7 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
     if (!await ctx.patched("agent:chat-queue")) {
       return void 0;
     }
-    const plan = await ctx.localStep(`queue:${outcome}`, async () => {
+    const plan = await stepOf(ctx)(`queue:${outcome}`, async () => {
       try {
         const settled = outcome === "completed" && await this.isCancelled(ctx.runId) ? "cancelled" : outcome;
         return await queue.plan({
@@ -728,11 +747,11 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
       await ctx.startChild(_AgentRunWorkflow, next.input, next.runId);
       return plan.frame;
     } catch (failure) {
-      if ((0, import_nestjs_durable_core.isWorkflowControlFlowSignal)(failure)) {
+      if ((0, import_nestjs_durable_core2.isWorkflowControlFlowSignal)(failure)) {
         throw failure;
       }
       const reason = failure instanceof Error ? failure.message : String(failure);
-      return ctx.localStep("queue:restore", async () => {
+      return stepOf(ctx)("queue:restore", async () => {
         await queue.restore(input.threadId, next, "start_failed", reason);
         return queue.pausedFrame(input.threadId);
       });
@@ -774,7 +793,7 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
     if (delivery === void 0) {
       return;
     }
-    await ctx.localStep("deliver:detached:unsettled", () => (0, import_nestjs_agent_core3.settleUnsettledDelegation)({
+    await stepOf(ctx)("deliver:detached:unsettled", () => (0, import_nestjs_agent_core3.settleUnsettledDelegation)({
       store: this.store,
       delivery,
       agent: input.agentName ?? "default",
@@ -790,7 +809,7 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
     const deps = this.factory.forAgent(input.agentName);
     const dispatchSteps = await ctx.patched("agent:dispatched-steps");
     if (input.sinkRunId !== void 0 || input.deliverTo !== void 0) {
-      await ctx.localStep("activate", () => this.store.setActiveStream(input.threadId, ctx.runId));
+      await stepOf(ctx)("activate", () => this.store.setActiveStream(input.threadId, ctx.runId));
     }
     const sinkRunId = input.sinkRunId ?? ctx.runId;
     const chainBelow = [
@@ -840,7 +859,9 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
       // question set and an approval reach a parked run through one path, and the HTTP surface that
       // settles either one is the same `POST /agent/tool-call/*` family.
       awaitAnswers: /* @__PURE__ */ __name((request) => ctx.waitForSignal(`tool:${ctx.runId}:${request.id}`), "awaitAnswers"),
-      step: /* @__PURE__ */ __name((name, fn) => ctx.localStep(name, fn), "step"),
+      // Bodies run outside the ambient workflow ctx, so nothing the application does in there can
+      // take a position in this run's journal (see `outsideWorkflowCtx`).
+      step: /* @__PURE__ */ __name((name, fn) => stepOf(ctx)(name, fn), "step"),
       // Both durable step primitives take their checkpoint position on the CALL, before their first
       // await, so launching a batch in one tick — what `settleAll` does — fixes the block of
       // positions in call order however the tools then settle. `ctx.patched` keeps a run that
@@ -852,9 +873,9 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
       // failure. Marker-based predicate, NOT instanceof: the signal's CLASS differs by runtime
       // (engine in-process throws durable-core's WorkflowSuspended/ContinueAsNew; the BullMQ thin
       // worker throws durable-worker's own Suspend), so only the Symbol.for marker is reliable.
-      isControlFlowError: /* @__PURE__ */ __name((error) => (0, import_nestjs_durable_core.isWorkflowControlFlowSignal)(error), "isControlFlowError"),
+      isControlFlowError: /* @__PURE__ */ __name((error) => (0, import_nestjs_durable_core2.isWorkflowControlFlowSignal)(error), "isControlFlowError"),
       runAgent: /* @__PURE__ */ __name(async (agentName, task) => {
-        const subThreadId = await ctx.localStep(`subthread:${agentName}`, async () => {
+        const subThreadId = await stepOf(ctx)(`subthread:${agentName}`, async () => {
           const thread = await this.store.createThread({
             actor: input.actor,
             transient: true
@@ -885,7 +906,7 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
       //   - `deliverTo` instead. The parent's tool result is a receipt, so the answer needs an
       //     address of its own, and by the time it exists nobody is holding one.
       startAgent: /* @__PURE__ */ __name(async ({ agentName, task, toolCallId: toolCallId2 }) => {
-        const subThreadId = await ctx.localStep(`subthread:${agentName}`, async () => {
+        const subThreadId = await stepOf(ctx)(`subthread:${agentName}`, async () => {
           const thread = await this.store.createThread({
             actor: input.actor,
             transient: true
@@ -943,14 +964,14 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
         ...deps,
         day
       }, input, hooks);
-      await ctx.localStep("deactivate", () => (0, import_nestjs_agent_core3.releaseThreadRun)(this.store, input.threadId, ctx.runId));
+      await stepOf(ctx)("deactivate", () => (0, import_nestjs_agent_core3.releaseThreadRun)(this.store, input.threadId, ctx.runId));
       return result;
     } catch (error) {
-      if ((0, import_nestjs_durable_core.isWorkflowControlFlowSignal)(error)) {
+      if ((0, import_nestjs_durable_core2.isWorkflowControlFlowSignal)(error)) {
         throw error;
       }
       if (error instanceof import_nestjs_agent_core3.RunCancelledError) {
-        await ctx.localStep("deactivate", () => (0, import_nestjs_agent_core3.releaseThreadRun)(this.store, input.threadId, ctx.runId));
+        await stepOf(ctx)("deactivate", () => (0, import_nestjs_agent_core3.releaseThreadRun)(this.store, input.threadId, ctx.runId));
         await this.settleDetachedParent(ctx, input, {
           status: "cancelled"
         });
@@ -975,14 +996,14 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
         code,
         message
       });
-      await ctx.localStep("persist:run:fail", () => this.store.recordRunEnd?.({
+      await stepOf(ctx)("persist:run:fail", () => this.store.recordRunEnd?.({
         runId: ctx.runId,
         status: "failed",
         errorCode: code,
         errorMessage: message
       }) ?? Promise.resolve());
       const queueFrame2 = await this.advanceQueue(ctx, input, "failed", message);
-      await ctx.localStep("deactivate", () => (0, import_nestjs_agent_core3.releaseThreadRun)(this.store, input.threadId, ctx.runId));
+      await stepOf(ctx)("deactivate", () => (0, import_nestjs_agent_core3.releaseThreadRun)(this.store, input.threadId, ctx.runId));
       await this.settleDetachedParent(ctx, input, {
         status: "failed",
         error: message
@@ -1027,7 +1048,7 @@ __name(isSignalTimeout, "isSignalTimeout");
 var import_node_crypto = require("crypto");
 var import_nestjs_agent_core5 = require("@dudousxd/nestjs-agent-core");
 var import_nestjs_durable3 = require("@dudousxd/nestjs-durable");
-var import_nestjs_durable_core2 = require("@dudousxd/nestjs-durable-core");
+var import_nestjs_durable_core3 = require("@dudousxd/nestjs-durable-core");
 var import_common4 = require("@nestjs/common");
 
 // src/in-process-sink.ts
@@ -1165,7 +1186,7 @@ var DurableAgentRunner = class _DurableAgentRunner {
     try {
       await this.workflows.start(AgentRunWorkflow, stamped, runId);
     } catch (error) {
-      if (!(0, import_nestjs_durable_core2.isWorkflowControlFlowSignal)(error)) {
+      if (!(0, import_nestjs_durable_core3.isWorkflowControlFlowSignal)(error)) {
         throw error;
       }
     }
@@ -2035,6 +2056,59 @@ var AgentService = class {
     }
     return queue.publish(threadId);
   }
+  /**
+  * `POST <base>/queue/:messageId/interrupt` — run a message that is already waiting NOW: it moves
+  * to the head of its queue marked as an interrupt, any pause is lifted, and the running turn is
+  * cancelled (its settle starts this message — the same path a `mode: 'interrupt'` send takes).
+  * With nothing running, the message starts at once.
+  *
+  * One request, and the message never leaves the queue: a client that removed it and sent it again
+  * would lose it if the second call failed, and would run it twice if another tab's drain started
+  * it in between. Answers the queue, plus `interrupting` (the run that was cancelled) or `runId`
+  * (the run this message started).
+  */
+  async interruptQueuedMessage(actor, messageId) {
+    const queue = this.requireQueue();
+    const store = queue.queueStore();
+    const threadId = await this.assertOwnsQueuedMessage(actor, messageId);
+    const gone = /* @__PURE__ */ __name(() => new import_common7.GoneException(`queued message ${messageId} already started or was removed`), "gone");
+    const marked = await store.updateQueuedMessage(messageId, {
+      interrupt: true
+    });
+    if (marked === null) {
+      throw gone();
+    }
+    if (marked.interrupt !== true) {
+      throw new import_common7.NotImplementedException("Interrupting a queued message requires a ChatQueueStore whose updateQueuedMessage stores `interrupt`; the bound store ignored it.");
+    }
+    if (!await store.moveQueuedMessage(messageId, 0)) {
+      throw gone();
+    }
+    await store.setQueuePause(threadId, null);
+    const { live } = await queue.holder(threadId, this.runner);
+    if (live !== null && live !== messageId && await store.getQueuedMessage(messageId) !== null) {
+      const state2 = await queue.publish(threadId);
+      await this.runner.cancel(live);
+      return {
+        ...state2,
+        interrupting: live
+      };
+    }
+    if (live !== null) {
+      return {
+        ...await queue.state(threadId),
+        runId: messageId
+      };
+    }
+    const runId = await queue.kick(threadId, this.runner);
+    const state = runId === void 0 ? await queue.publish(threadId) : await queue.state(threadId);
+    return {
+      ...state,
+      ...runId !== void 0 ? {
+        runId
+      } : {}
+    };
+  }
   /** `DELETE <base>/threads/:id/queue` — drop every waiting message (and any pause). */
   async clearQueue(actor, threadId) {
     await this.assertOwnsThread(actor, threadId);
@@ -3677,6 +3751,14 @@ var QueueController = class {
       } : {}
     });
   }
+  /**
+  * Run a waiting message now: it moves to the head as an interrupt and the running turn is
+  * cancelled for it. Carries `interrupting` (the cancelled run), or `runId` when nothing was
+  * running and it started at once.
+  */
+  async interrupt(req, messageId) {
+    return this.agent.interruptQueuedMessage(await this.actorResolver.resolve(req), messageId);
+  }
   async remove(req, messageId) {
     return this.agent.removeQueuedMessage(await this.actorResolver.resolve(req), messageId);
   }
@@ -3727,6 +3809,17 @@ _ts_decorate16([
   ]),
   _ts_metadata15("design:returntype", Promise)
 ], QueueController.prototype, "update", null);
+_ts_decorate16([
+  (0, import_common16.Post)("queue/:messageId/interrupt"),
+  _ts_param14(0, (0, import_common16.Req)()),
+  _ts_param14(1, (0, import_common16.Param)("messageId")),
+  _ts_metadata15("design:type", Function),
+  _ts_metadata15("design:paramtypes", [
+    typeof Request === "undefined" ? Object : Request,
+    String
+  ]),
+  _ts_metadata15("design:returntype", Promise)
+], QueueController.prototype, "interrupt", null);
 _ts_decorate16([
   (0, import_common16.Delete)("queue/:messageId"),
   _ts_param14(0, (0, import_common16.Req)()),