@dudousxd/nestjs-agent 1.19.2 → 1.19.3

package/README.md

@@ -156,6 +156,8 @@ per-message cap — so a client never repeats them.
 it leaves media with nothing pointing at it. Two optional methods make that findable — `list` on
 your `AttachmentStagingStore` (you stored the bytes, so only you can enumerate them) and
 `referencedMediaIds` on your `AgentStore` (only it can see which media a live message carries).
+A message waiting in a thread's queue — sent while a turn ran, or into a paused queue — counts as
+live: its files are kept until it runs, is removed, or has its attachments edited away.
 
 ```ts
 // a job the host runs; nothing here is reachable over HTTP

package/dist/durable/index.cjs

@@ -282,12 +282,60 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
   store;
   runs;
   queue;
+  workflows;
   logger = new import_common2.Logger(_AgentRunWorkflow.name);
-  constructor(factory, store, runs, queue) {
+  constructor(factory, store, runs, queue, workflows) {
     this.factory = factory;
     this.store = store;
     this.runs = runs;
     this.queue = queue;
+    this.workflows = workflows;
+  }
+  /**
+  * Start a detached delegation as a TOP-LEVEL run, under an id derived from this run and the call.
+  *
+  * Not `ctx.startChild`, because the runtime treats a `spawn:` child as part of its parent: a Stop
+  * on the parent cascades to every run it spawned. A detached run is exactly the one the person did
+  * NOT ask to stop — they stopped the turn they were watching, and the work it handed off is meant
+  * to outlive that turn (it is meant to outlive it finishing, after all). Cascaded, it died parked
+  * on its approval, where its body never runs again, so nothing settled the delegation and the card
+  * said "started" for ever. The agent-level edge stays: the child's input still carries
+  * `parentRunId`, which is what the run rows record.
+  *
+  * Journaled as one `detach:<toolCallId>` localStep whose body runs outside the ambient workflow
+  * ctx (so the start goes to the engine and writes no position in this run). Its recorded result
+  * keeps a replay from starting it again, and a body re-run after a crash between the start and
+  * the checkpoint asks for the same id, which the runtime answers with the run it already has.
+  * The child is stamped with this run's namespace, as `ctx.startChild` would have stamped it, so an
+  * operator re-driving a tenant's turn does not move its delegate off that tenant's workers.
+  */
+  startDetached(ctx, toolCallId2, childInput) {
+    return stepOf(ctx)(`detach:${toolCallId2}`, async () => {
+      const workflows = this.workflows;
+      if (workflows === void 0) {
+        throw new Error("A detached delegation needs WorkflowService (DurableModule) to start its run, and none is bound.");
+      }
+      const childRunId = `${ctx.runId}.detached.${toolCallId2}`;
+      const namespace = await this.namespaceOf(ctx.runId);
+      try {
+        await workflows.start(_AgentRunWorkflow, childInput, childRunId, namespace !== void 0 ? {
+          namespace
+        } : void 0);
+      } catch (error) {
+        if (!(0, import_nestjs_durable_core2.isWorkflowControlFlowSignal)(error)) {
+          throw error;
+        }
+      }
+      return childRunId;
+    });
+  }
+  /** The namespace this run is stamped with, where the runtime can say. */
+  async namespaceOf(runId) {
+    try {
+      return (await this.runs?.getRunDetail(runId))?.run.namespace;
+    } catch {
+      return void 0;
+    }
   }
   /**
   * Move the thread past this settling turn — to the next queued message, started here as a
@@ -488,6 +536,10 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
       //     OWN runId, and that is what `runForToolCall` answers with.
       //   - `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.
+      //   - no runtime parent. A Stop on this turn must not reach the work it handed off, so the
+      //     run is started on its own (`startDetached`), not as a `spawn:` child. A run that
+      //     journaled the `spawn:` before this release replays it: `ctx.patched` answers false at a
+      //     position that already holds one.
       startAgent: /* @__PURE__ */ __name(async ({ agentName, task, toolCallId: toolCallId2 }) => {
         const subThreadId = await stepOf(ctx)(`subthread:${agentName}`, async () => {
           const thread = await this.store.createThread({
@@ -496,7 +548,7 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
           });
           return thread.id;
         });
-        const childRunId = await ctx.startChild(_AgentRunWorkflow, {
+        const childInput = {
           agentName,
           threadId: subThreadId,
           actor: input.actor,
@@ -509,9 +561,14 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
             threadId: input.threadId,
             toolCallId: toolCallId2
           }
-        });
+        };
+        if (!await ctx.patched("agent:detached-unlinked")) {
+          return {
+            runId: await ctx.startChild(_AgentRunWorkflow, childInput)
+          };
+        }
         return {
-          runId: childRunId
+          runId: await this.startDetached(ctx, toolCallId2, childInput)
         };
       }, "startAgent"),
       // The two long steps as engine-dispatched `ctx.step`s, so a turn isn't pinned to this
@@ -624,12 +681,14 @@ AgentRunWorkflow = _ts_decorate2([
   _ts_param2(2, (0, import_common2.Inject)(import_nestjs_durable2.RUN_GATEWAY)),
   _ts_param2(3, (0, import_common2.Optional)()),
   _ts_param2(3, (0, import_common2.Inject)(AGENT_CHAT_QUEUE)),
+  _ts_param2(4, (0, import_common2.Optional)()),
   _ts_metadata2("design:type", Function),
   _ts_metadata2("design:paramtypes", [
     typeof AgentDepsFactory === "undefined" ? Object : AgentDepsFactory,
     typeof AgentStore === "undefined" ? Object : AgentStore,
     typeof RunGateway === "undefined" ? Object : RunGateway,
-    typeof ChatQueueService === "undefined" ? Object : ChatQueueService
+    typeof ChatQueueService === "undefined" ? Object : ChatQueueService,
+    typeof import_nestjs_durable2.WorkflowService === "undefined" ? Object : import_nestjs_durable2.WorkflowService
   ])
 ], AgentRunWorkflow);
 function isSignalTimeout(error) {
@@ -750,6 +809,20 @@ function isThreadTurn(input) {
   return typeof input === "object" && input !== null && input.sinkRunId === void 0 && input.deliverTo === void 0;
 }
 __name(isThreadTurn, "isThreadTurn");
+function deliveryOf(input) {
+  if (typeof input !== "object" || input === null) {
+    return void 0;
+  }
+  const { deliverTo, agentName } = input;
+  if (typeof deliverTo !== "object" || deliverTo === null || typeof deliverTo.threadId !== "string" || typeof deliverTo.toolCallId !== "string") {
+    return void 0;
+  }
+  return {
+    delivery: deliverTo,
+    agent: typeof agentName === "string" ? agentName : "default"
+  };
+}
+__name(deliveryOf, "deliveryOf");
 var DurableAgentRunner = class _DurableAgentRunner {
   static {
     __name(this, "DurableAgentRunner");
@@ -829,11 +902,16 @@ var DurableAgentRunner = class _DurableAgentRunner {
   */
   async cancel(runId) {
     this.logger.log(`cancelling agent run ${runId}`);
-    const input = await this.inputOf(runId);
+    const detail = await this.detailOf(runId);
+    const input = detail?.run.input;
     const threadId = threadOfRun(input);
     await this.runs.cancel(runId, {
       compensate: true
     });
+    await this.settleCancelledDelegation(runId, input);
+    for (const childId of detail?.children ?? []) {
+      await this.settleCascadedDetached(childId);
+    }
     const writer = await this.sink.open(runId);
     if (threadId !== void 0) {
       if (this.queue?.supported === true && isThreadTurn(input)) {
@@ -864,7 +942,57 @@ var DurableAgentRunner = class _DurableAgentRunner {
     });
   }
   /**
-  * The input a run was started with (which thread it was streaming), or `undefined` where the gateway cannot say.
+  * Settle the delegation a DETACHED run was started for, once it has been stopped. A run parked on
+  * a human never runs its body again — the runtime settles it from outside — so the body's own
+  * `deliver:detached:unsettled` is not reached, and without this the card in the calling thread says
+  * "started" for ever. Settles once (see `settleUnsettledDelegation`), so a body that did observe
+  * the Stop and a run that had already answered are both left as they are. A no-op for any run
+  * that does not deliver into another thread.
+  */
+  async settleCancelledDelegation(runId, input) {
+    const target = deliveryOf(input);
+    if (target === void 0) {
+      return;
+    }
+    try {
+      await (0, import_nestjs_agent_core4.settleUnsettledDelegation)({
+        store: this.store,
+        delivery: target.delivery,
+        agent: target.agent,
+        runId,
+        status: "cancelled"
+      });
+    } catch (error) {
+      this.logger.error(`could not settle the delegation of cancelled run ${runId}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  /**
+  * A detached child the runtime cancelled along with its parent (a `spawn:` journaled before
+  * detached runs were started on their own): end it the way a Stop on its own id would have.
+  */
+  async settleCascadedDetached(childId) {
+    const child = await this.detailOf(childId);
+    const status = child?.run.status;
+    if (child === void 0 || deliveryOf(child.run.input) === void 0 || status !== "cancelled" && status !== "cancelling") {
+      return;
+    }
+    const subThreadId = threadOfRun(child.run.input);
+    if (subThreadId !== void 0) {
+      await (0, import_nestjs_agent_core4.releaseThreadRun)(this.store, subThreadId, childId);
+    }
+    await this.settleCancelledDelegation(childId, child.run.input);
+    const writer = await this.sink.open(childId);
+    await writer.write((0, import_nestjs_agent_core4.encodeStreamEvent)({
+      kind: "cancelled"
+    }));
+    await writer.end();
+    await this.store.recordRunEnd?.({
+      runId: childId,
+      status: "cancelled"
+    });
+  }
+  /**
+  * What the runtime recorded for a run — the input it was started with (which thread it was streaming), its status and the runs it spawned — or `undefined` where the gateway cannot say.
   *
   * A read failure answers `undefined` instead of propagating, the same posture `AgentRunWorkflow`
   * takes for its own cancel observation: failing to ask is not an answer worth failing a cancel
@@ -873,9 +1001,9 @@ var DurableAgentRunner = class _DurableAgentRunner {
   * with a subscriber holding a stream that never settles, from the one call whose entire job is to
   * make a run stop.
   */
-  async inputOf(runId) {
+  async detailOf(runId) {
     try {
-      return (await this.runs.getRunDetail(runId))?.run.input;
+      return await this.runs.getRunDetail(runId) ?? void 0;
     } catch {
       return void 0;
     }