@dudousxd/nestjs-agent 1.19.1 → 1.19.3

package/dist/durable/index.d.cts

@@ -1,7 +1,7 @@
 import { AgentStore, AgentRunInput, AgentLoopResult, LlmStepEnvelope, BufferedModelTurnResult, ToolStepEnvelope, AgentRunner, TokenStreamSink, AgentRunStartOptions, HumanReply } from '@dudousxd/nestjs-agent-core';
+import { WorkflowService } from '@dudousxd/nestjs-durable';
 import { RunGateway, WorkflowCtx } from '@dudousxd/nestjs-durable-core';
 import { A as AgentDepsFactory, C as ChatQueueService, a as AgentSurface, b as AgentModuleOptions } from '../chat-queue.service-CKZkjlMK.cjs';
-import { WorkflowService } from '@dudousxd/nestjs-durable';
 import { DynamicModule } from '@nestjs/common';
 import '@standard-schema/spec';
 
@@ -23,8 +23,30 @@ declare class AgentRunWorkflow {
     private readonly store;
     private readonly runs?;
     private readonly queue?;
+    private readonly workflows?;
     private readonly logger;
-    constructor(factory: AgentDepsFactory, store: AgentStore, runs?: RunGateway | undefined, queue?: ChatQueueService | undefined);
+    constructor(factory: AgentDepsFactory, store: AgentStore, runs?: RunGateway | undefined, queue?: ChatQueueService | undefined, workflows?: WorkflowService | undefined);
+    /**
+     * 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.
+     */
+    private startDetached;
+    /** The namespace this run is stamped with, where the runtime can say. */
+    private namespaceOf;
     /**
      * Move the thread past this settling turn — to the next queued message, started here as a
      * fire-and-forget `ctx.startChild` under the message's own id, or to a paused/empty queue — and
@@ -188,7 +210,21 @@ declare class DurableAgentRunner implements AgentRunner {
      */
     cancel(runId: string): Promise<void>;
     /**
-     * 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.
+     */
+    private settleCancelledDelegation;
+    /**
+     * 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.
+     */
+    private settleCascadedDetached;
+    /**
+     * 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
@@ -197,7 +233,7 @@ declare class DurableAgentRunner implements AgentRunner {
      * with a subscriber holding a stream that never settles, from the one call whose entire job is to
      * make a run stop.
      */
-    private inputOf;
+    private detailOf;
 }
 
 /**

package/dist/durable/index.d.ts

@@ -1,7 +1,7 @@
 import { AgentStore, AgentRunInput, AgentLoopResult, LlmStepEnvelope, BufferedModelTurnResult, ToolStepEnvelope, AgentRunner, TokenStreamSink, AgentRunStartOptions, HumanReply } from '@dudousxd/nestjs-agent-core';
+import { WorkflowService } from '@dudousxd/nestjs-durable';
 import { RunGateway, WorkflowCtx } from '@dudousxd/nestjs-durable-core';
 import { A as AgentDepsFactory, C as ChatQueueService, a as AgentSurface, b as AgentModuleOptions } from '../chat-queue.service-CKZkjlMK.js';
-import { WorkflowService } from '@dudousxd/nestjs-durable';
 import { DynamicModule } from '@nestjs/common';
 import '@standard-schema/spec';
 
@@ -23,8 +23,30 @@ declare class AgentRunWorkflow {
     private readonly store;
     private readonly runs?;
     private readonly queue?;
+    private readonly workflows?;
     private readonly logger;
-    constructor(factory: AgentDepsFactory, store: AgentStore, runs?: RunGateway | undefined, queue?: ChatQueueService | undefined);
+    constructor(factory: AgentDepsFactory, store: AgentStore, runs?: RunGateway | undefined, queue?: ChatQueueService | undefined, workflows?: WorkflowService | undefined);
+    /**
+     * 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.
+     */
+    private startDetached;
+    /** The namespace this run is stamped with, where the runtime can say. */
+    private namespaceOf;
     /**
      * Move the thread past this settling turn — to the next queued message, started here as a
      * fire-and-forget `ctx.startChild` under the message's own id, or to a paused/empty queue — and
@@ -188,7 +210,21 @@ declare class DurableAgentRunner implements AgentRunner {
      */
     cancel(runId: string): Promise<void>;
     /**
-     * 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.
+     */
+    private settleCancelledDelegation;
+    /**
+     * 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.
+     */
+    private settleCascadedDetached;
+    /**
+     * 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
@@ -197,7 +233,7 @@ declare class DurableAgentRunner implements AgentRunner {
      * with a subscriber holding a stream that never settles, from the one call whose entire job is to
      * make a run stop.
      */
-    private inputOf;
+    private detailOf;
 }
 
 /**

package/dist/durable/index.js

@@ -3,7 +3,7 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
 
 // src/durable/agent-run.workflow.ts
 import { AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY2, AGENT_STORE, RUN_ENDED_BEFORE_TOOL_CALL, RunCancelledError, agentFailureCode, encodeStreamEvent as encodeStreamEvent2, isReplayIntegrityError, publishAgentRunFailed, releaseThreadRun, runAgentLoop, settleAll, settleDeadRun, settleUnsettledDelegation, streamFailure } from "@dudousxd/nestjs-agent-core";
-import { RUN_GATEWAY, Workflow } from "@dudousxd/nestjs-durable";
+import { RUN_GATEWAY, Workflow, WorkflowService } from "@dudousxd/nestjs-durable";
 import { isWorkflowControlFlowSignal } from "@dudousxd/nestjs-durable-core";
 import { Inject as Inject2, Injectable as Injectable2, Logger, Optional } from "@nestjs/common";
 
@@ -15,10 +15,16 @@ __name(utcDay, "utcDay");
 function childSinkWriter(writer) {
   return {
     write: /* @__PURE__ */ __name((chunk) => writer.write(chunk), "write"),
+    // The top-level run owns end/fail — but what the child wrote must not be held back past it.
     end: /* @__PURE__ */ __name(async () => {
+      await writer.flush?.();
     }, "end"),
     fail: /* @__PURE__ */ __name(async () => {
-    }, "fail")
+      await writer.flush?.();
+    }, "fail"),
+    flush: /* @__PURE__ */ __name(async () => {
+      await writer.flush?.();
+    }, "flush")
   };
 }
 __name(childSinkWriter, "childSinkWriter");
@@ -248,12 +254,60 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
   store;
   runs;
   queue;
+  workflows;
   logger = new 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 (!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
@@ -454,6 +508,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({
@@ -462,7 +520,7 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
           });
           return thread.id;
         });
-        const childRunId = await ctx.startChild(_AgentRunWorkflow, {
+        const childInput = {
           agentName,
           threadId: subThreadId,
           actor: input.actor,
@@ -475,9 +533,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
@@ -590,12 +653,14 @@ AgentRunWorkflow = _ts_decorate2([
   _ts_param2(2, Inject2(RUN_GATEWAY)),
   _ts_param2(3, Optional()),
   _ts_param2(3, Inject2(AGENT_CHAT_QUEUE)),
+  _ts_param2(4, 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 WorkflowService === "undefined" ? Object : WorkflowService
   ])
 ], AgentRunWorkflow);
 function isSignalTimeout(error) {
@@ -605,8 +670,8 @@ __name(isSignalTimeout, "isSignalTimeout");
 
 // src/durable/durable-agent-runner.ts
 import { randomUUID } from "crypto";
-import { AGENT_SINK, AGENT_STORE as AGENT_STORE2, encodeStreamEvent as encodeStreamEvent3, releaseThreadRun as releaseThreadRun2 } from "@dudousxd/nestjs-agent-core";
-import { RUN_GATEWAY as RUN_GATEWAY2, WorkflowService } from "@dudousxd/nestjs-durable";
+import { AGENT_SINK, AGENT_STORE as AGENT_STORE2, encodeStreamEvent as encodeStreamEvent3, releaseThreadRun as releaseThreadRun2, settleUnsettledDelegation as settleUnsettledDelegation2 } from "@dudousxd/nestjs-agent-core";
+import { RUN_GATEWAY as RUN_GATEWAY2, WorkflowService as WorkflowService2 } from "@dudousxd/nestjs-durable";
 import { isWorkflowControlFlowSignal as isWorkflowControlFlowSignal2 } from "@dudousxd/nestjs-durable-core";
 import { Inject as Inject3, Injectable as Injectable3, Logger as Logger2, Optional as Optional2 } from "@nestjs/common";
 
@@ -716,6 +781,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");
@@ -795,11 +874,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)) {
@@ -830,7 +914,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 settleUnsettledDelegation2({
+        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 releaseThreadRun2(this.store, subThreadId, childId);
+    }
+    await this.settleCancelledDelegation(childId, child.run.input);
+    const writer = await this.sink.open(childId);
+    await writer.write(encodeStreamEvent3({
+      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
@@ -839,9 +973,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;
     }
@@ -856,7 +990,7 @@ DurableAgentRunner = _ts_decorate3([
   _ts_param3(4, Inject3(AGENT_CHAT_QUEUE)),
   _ts_metadata3("design:type", Function),
   _ts_metadata3("design:paramtypes", [
-    typeof WorkflowService === "undefined" ? Object : WorkflowService,
+    typeof WorkflowService2 === "undefined" ? Object : WorkflowService2,
     typeof RunGateway === "undefined" ? Object : RunGateway,
     typeof AgentStore === "undefined" ? Object : AgentStore,
     typeof TokenStreamSink === "undefined" ? Object : TokenStreamSink,
@@ -5094,7 +5228,7 @@ var LedgerQuotaProvider = class {
 };
 
 // src/runner/inline-agent-runner.ts
-import { AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY6, AGENT_STORE as AGENT_STORE6, RUN_ENDED_BEFORE_TOOL_CALL as RUN_ENDED_BEFORE_TOOL_CALL2, RunCancelledError as RunCancelledError2, agentFailureCode as agentFailureCode2, encodeStreamEvent as encodeStreamEvent5, publishAgentRunFailed as publishAgentRunFailed2, releaseThreadRun as releaseThreadRun3, runAgentLoop as runAgentLoop2, settleAll as settleAll2, settleUnsettledDelegation as settleUnsettledDelegation2, streamFailure as streamFailure3 } from "@dudousxd/nestjs-agent-core";
+import { AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY6, AGENT_STORE as AGENT_STORE6, RUN_ENDED_BEFORE_TOOL_CALL as RUN_ENDED_BEFORE_TOOL_CALL2, RunCancelledError as RunCancelledError2, agentFailureCode as agentFailureCode2, encodeStreamEvent as encodeStreamEvent5, publishAgentRunFailed as publishAgentRunFailed2, releaseThreadRun as releaseThreadRun3, runAgentLoop as runAgentLoop2, settleAll as settleAll2, settleUnsettledDelegation as settleUnsettledDelegation3, streamFailure as streamFailure3 } from "@dudousxd/nestjs-agent-core";
 import { Inject as Inject23, Injectable as Injectable11, Logger as Logger7, Optional as Optional10 } from "@nestjs/common";
 function _ts_decorate25(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -5479,7 +5613,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
         }
       });
       await Promise.resolve(this.store.failUnsettledToolCalls?.(runId, RUN_ENDED_BEFORE_TOOL_CALL2)).catch(() => 0);
-      await settleUnsettledDelegation2({
+      await settleUnsettledDelegation3({
         store: this.store,
         delivery: deliverTo,
         agent: agentName,