@dudousxd/nestjs-agent 0.13.0 → 1.0.0

package/dist/durable/index.d.cts

@@ -1,6 +1,6 @@
 import { AgentStore, AgentRunInput, AgentLoopResult, LlmStepEnvelope, BufferedModelTurnResult, ToolStepEnvelope, AgentRunner, TokenStreamSink, HumanReply } from '@dudousxd/nestjs-agent-core';
 import { RunGateway, WorkflowCtx } from '@dudousxd/nestjs-durable-core';
-import { A as AgentDepsFactory, a as AgentSurface, b as AgentModuleOptions } from '../agent-deps.factory-y2hvoQ6U.cjs';
+import { A as AgentDepsFactory, a as AgentSurface, b as AgentModuleOptions } from '../agent-deps.factory-OjrLyAZo.cjs';
 import { WorkflowService } from '@dudousxd/nestjs-durable';
 import { DynamicModule } from '@nestjs/common';
 import '@standard-schema/spec';
@@ -9,20 +9,20 @@ import '@standard-schema/spec';
  * The agent turn AS a durable workflow. Persist/stream checkpoints are `ctx.localStep`s — the
  * in-process primitive, NOT the always-dispatched `ctx.step`: their names are dynamic checkpoint
  * identities (`persist:toolcall:<id>`), not routable worker groups, and their deps (store, sink)
- * live in THIS workflow worker's DI. The two LONG steps (model call, tool execution) are dispatched
- * through `AgentRunSteps` where the deployment asked for it (`AGENT_DISPATCHED_STEPS`, from
- * `dispatchedSteps: true`) so the run isn't pinned to this pod while they execute; without that
- * flag they are localSteps too. HITL is `ctx.waitForSignal`, and sub-agent delegation is
- * `ctx.child(AgentRunWorkflow)` — a replay-safe, observable child run (it shows up as a node in the durable dashboard). A child
- * streams into its top-level ancestor's sink (`sinkRunId`) so the human watching the parent sees it
- * and can approve its action tools; the approval routes to the child's own run via `runForToolCall`.
+ * live in THIS workflow worker's DI. The two LONG steps (model call, tool execution) are `ctx.step`s
+ * routed to `AgentRunSteps`, so the run is never pinned to this pod while they execute — the same
+ * thing `ctx.step` means anywhere in this ecosystem, and the reason a `@AiTool` handler must
+ * establish whatever execution context it needs itself. HITL is `ctx.waitForSignal`, and sub-agent
+ * delegation is `ctx.child(AgentRunWorkflow)` — a replay-safe, observable child run (it shows up as
+ * a node in the durable dashboard). A child streams into its top-level ancestor's sink
+ * (`sinkRunId`) so the human watching the parent sees it and can approve its action tools; the
+ * approval routes to the child's own run via `runForToolCall`.
  */
 declare class AgentRunWorkflow {
     private readonly factory;
     private readonly store;
-    private readonly dispatchedSteps;
     private readonly runs?;
-    constructor(factory: AgentDepsFactory, store: AgentStore, dispatchedSteps: boolean, runs?: RunGateway | undefined);
+    constructor(factory: AgentDepsFactory, store: AgentStore, runs?: RunGateway | undefined);
     /**
      * Has someone asked this run to stop? Read from the runtime's own run status, which is where
      * `DurableAgentRunner.cancel` puts it — `cancelling` while a compensating cancel is in flight,
@@ -85,12 +85,13 @@ interface DispatchedToolInput extends ToolStepEnvelope {
     toolType: 'read' | 'action';
 }
 /**
- * The two long steps `AgentRunWorkflow` dispatches as routed remote steps (`AgentRunSteps.llm` /
- * `AgentRunSteps.tool`) under `dispatchedSteps: true`; omitting that flag runs them in-process
- * under `ctx.localStep` instead. Both re-resolve their deps from THIS worker's own DI via
+ * The two long steps every turn dispatches as routed remote steps (`AgentRunSteps.llm` /
+ * `AgentRunSteps.tool`). Both re-resolve their deps from THIS worker's own DI via
  * `AGENT_DEPS_FACTORY.forAgent` — a step can be served by any worker in the fleet, not just the one
- * that started the run. Always provided by `AgentDurableModule` regardless of `dispatchedSteps`, so
- * the worker group is never orphaned.
+ * that started the run, which is also why a host's `@AiTool` handler has to establish whatever
+ * execution context it needs (a request-scoped ORM EntityManager, a CLS transaction) rather than
+ * inherit one. Provided by `AgentDurableModule` under every surface but `'http'`, so the routed
+ * groups are served wherever a run may be driven.
  */
 declare class AgentRunSteps {
     private readonly factory;
@@ -143,13 +144,31 @@ declare class DurableAgentRunner implements AgentRunner {
      * settles the run `cancelled` regardless. The cascade to child runs comes with it.
      *
      * Neither of those settles the agent's own state, so this does: the run row gets its own terminal,
-     * and the subscriber gets a `cancelled` frame followed by a normal end. Both are keyed by runId
-     * alone, which is why they belong here rather than in the body — the body is the only place that
-     * knows which THREAD was streaming, so releasing that stays there (see `AgentRunWorkflow`).
+     * the thread stops reporting a live stream, and the subscriber gets a `cancelled` frame followed
+     * by a normal end.
+     *
+     * The thread is released HERE rather than left to the body, because a cancelled turn is usually
+     * suspended — parked on a human, or on one of the dispatched steps a turn spends most of its life
+     * in — and a suspended body never reaches its own catch: the runtime settles the run from outside
+     * it. The body still releases the thread on the paths where it does unwind (see
+     * `AgentRunWorkflow`); both write the same `null`, and whichever gets there first is right. The
+     * thread id comes off the run's own recorded input, so this holds for a sub-agent's subthread too
+     * — read best-effort, because a gateway that cannot name the thread must not stop the cancel.
      *
      * A tool already executing is not interrupted, here or anywhere: see `haltIfCancelled` in core.
      */
     cancel(runId: string): Promise<void>;
+    /**
+     * Which thread a run was streaming, 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
+     * over. This id is only needed to clear the thread's active stream, and a stream still marked live
+     * is a far smaller fault than the one a throw here would cause — a run nobody ever told to stop,
+     * with a subscriber holding a stream that never settles, from the one call whose entire job is to
+     * make a run stop.
+     */
+    private threadOf;
 }
 
 /**
@@ -183,11 +202,10 @@ interface AgentDurableModuleOptions {
  * and exposes the durable runner via `AGENT_DURABLE_RUNNER`, which AgentModule binds to
  * `AGENT_RUNNER`. Forgetting this import makes AgentModule throw a clear error at boot.
  *
- * Always provides `AgentRunSteps` regardless of `dispatchedSteps` — the worker group it serves
- * (`AgentRunSteps.llm`/`.tool`) must never be orphaned by a config flag the durable step registrar
- * can't see ahead of time. This is the FULL ('both'/'engine'-equivalent) wiring: bare-importing this
- * class (no `forRoot()` call) always gets it, unconditionally — `forRoot({ surface: 'http' })` is
- * the only form that diverges (see `AgentDurableHttpModule` above).
+ * Provides `AgentRunSteps`, whose two groups (`AgentRunSteps.llm`/`.tool`) every turn dispatches to.
+ * This is the FULL ('both'/'engine'-equivalent) wiring: bare-importing this class (no `forRoot()`
+ * call) always gets it, unconditionally — `forRoot({ surface: 'http' })` is the only form that
+ * diverges (see `AgentDurableHttpModule` above).
  */
 declare class AgentDurableModule {
     /**
@@ -217,14 +235,4 @@ declare class AgentDurableModule {
  */
 declare function agentDurable(options: AgentModuleOptions): DynamicModule[];
 
-/**
- * DI flag carrying the EFFECTIVE `dispatchedSteps` value: whether `AgentRunWorkflow` dispatches its
- * `llm`/`tool` steps as routed remote steps (`AgentRunSteps`) instead of in-process `ctx.localStep`s.
- * `AgentDurableModule` derives it from `AGENT_OPTIONS` (`durable === true && dispatchedSteps ===
- * true`); `AgentRunWorkflow` injects it. Kept in its own file — `AgentDurableModule` provides
- * `AgentRunWorkflow` and `AgentRunWorkflow` injects this token, so declaring it in either of those
- * two files would make them import each other.
- */
-declare const AGENT_DISPATCHED_STEPS: unique symbol;
-
-export { AGENT_DISPATCHED_STEPS, AgentDurableModule, type AgentDurableModuleOptions, AgentRunSteps, AgentRunWorkflow, type DispatchedLlmInput, type DispatchedToolInput, DurableAgentRunner, agentDurable };
+export { AgentDurableModule, type AgentDurableModuleOptions, AgentRunSteps, AgentRunWorkflow, type DispatchedLlmInput, type DispatchedToolInput, DurableAgentRunner, agentDurable };

package/dist/durable/index.d.ts

@@ -1,6 +1,6 @@
 import { AgentStore, AgentRunInput, AgentLoopResult, LlmStepEnvelope, BufferedModelTurnResult, ToolStepEnvelope, AgentRunner, TokenStreamSink, HumanReply } from '@dudousxd/nestjs-agent-core';
 import { RunGateway, WorkflowCtx } from '@dudousxd/nestjs-durable-core';
-import { A as AgentDepsFactory, a as AgentSurface, b as AgentModuleOptions } from '../agent-deps.factory-y2hvoQ6U.js';
+import { A as AgentDepsFactory, a as AgentSurface, b as AgentModuleOptions } from '../agent-deps.factory-OjrLyAZo.js';
 import { WorkflowService } from '@dudousxd/nestjs-durable';
 import { DynamicModule } from '@nestjs/common';
 import '@standard-schema/spec';
@@ -9,20 +9,20 @@ import '@standard-schema/spec';
  * The agent turn AS a durable workflow. Persist/stream checkpoints are `ctx.localStep`s — the
  * in-process primitive, NOT the always-dispatched `ctx.step`: their names are dynamic checkpoint
  * identities (`persist:toolcall:<id>`), not routable worker groups, and their deps (store, sink)
- * live in THIS workflow worker's DI. The two LONG steps (model call, tool execution) are dispatched
- * through `AgentRunSteps` where the deployment asked for it (`AGENT_DISPATCHED_STEPS`, from
- * `dispatchedSteps: true`) so the run isn't pinned to this pod while they execute; without that
- * flag they are localSteps too. HITL is `ctx.waitForSignal`, and sub-agent delegation is
- * `ctx.child(AgentRunWorkflow)` — a replay-safe, observable child run (it shows up as a node in the durable dashboard). A child
- * streams into its top-level ancestor's sink (`sinkRunId`) so the human watching the parent sees it
- * and can approve its action tools; the approval routes to the child's own run via `runForToolCall`.
+ * live in THIS workflow worker's DI. The two LONG steps (model call, tool execution) are `ctx.step`s
+ * routed to `AgentRunSteps`, so the run is never pinned to this pod while they execute — the same
+ * thing `ctx.step` means anywhere in this ecosystem, and the reason a `@AiTool` handler must
+ * establish whatever execution context it needs itself. HITL is `ctx.waitForSignal`, and sub-agent
+ * delegation is `ctx.child(AgentRunWorkflow)` — a replay-safe, observable child run (it shows up as
+ * a node in the durable dashboard). A child streams into its top-level ancestor's sink
+ * (`sinkRunId`) so the human watching the parent sees it and can approve its action tools; the
+ * approval routes to the child's own run via `runForToolCall`.
  */
 declare class AgentRunWorkflow {
     private readonly factory;
     private readonly store;
-    private readonly dispatchedSteps;
     private readonly runs?;
-    constructor(factory: AgentDepsFactory, store: AgentStore, dispatchedSteps: boolean, runs?: RunGateway | undefined);
+    constructor(factory: AgentDepsFactory, store: AgentStore, runs?: RunGateway | undefined);
     /**
      * Has someone asked this run to stop? Read from the runtime's own run status, which is where
      * `DurableAgentRunner.cancel` puts it — `cancelling` while a compensating cancel is in flight,
@@ -85,12 +85,13 @@ interface DispatchedToolInput extends ToolStepEnvelope {
     toolType: 'read' | 'action';
 }
 /**
- * The two long steps `AgentRunWorkflow` dispatches as routed remote steps (`AgentRunSteps.llm` /
- * `AgentRunSteps.tool`) under `dispatchedSteps: true`; omitting that flag runs them in-process
- * under `ctx.localStep` instead. Both re-resolve their deps from THIS worker's own DI via
+ * The two long steps every turn dispatches as routed remote steps (`AgentRunSteps.llm` /
+ * `AgentRunSteps.tool`). Both re-resolve their deps from THIS worker's own DI via
  * `AGENT_DEPS_FACTORY.forAgent` — a step can be served by any worker in the fleet, not just the one
- * that started the run. Always provided by `AgentDurableModule` regardless of `dispatchedSteps`, so
- * the worker group is never orphaned.
+ * that started the run, which is also why a host's `@AiTool` handler has to establish whatever
+ * execution context it needs (a request-scoped ORM EntityManager, a CLS transaction) rather than
+ * inherit one. Provided by `AgentDurableModule` under every surface but `'http'`, so the routed
+ * groups are served wherever a run may be driven.
  */
 declare class AgentRunSteps {
     private readonly factory;
@@ -143,13 +144,31 @@ declare class DurableAgentRunner implements AgentRunner {
      * settles the run `cancelled` regardless. The cascade to child runs comes with it.
      *
      * Neither of those settles the agent's own state, so this does: the run row gets its own terminal,
-     * and the subscriber gets a `cancelled` frame followed by a normal end. Both are keyed by runId
-     * alone, which is why they belong here rather than in the body — the body is the only place that
-     * knows which THREAD was streaming, so releasing that stays there (see `AgentRunWorkflow`).
+     * the thread stops reporting a live stream, and the subscriber gets a `cancelled` frame followed
+     * by a normal end.
+     *
+     * The thread is released HERE rather than left to the body, because a cancelled turn is usually
+     * suspended — parked on a human, or on one of the dispatched steps a turn spends most of its life
+     * in — and a suspended body never reaches its own catch: the runtime settles the run from outside
+     * it. The body still releases the thread on the paths where it does unwind (see
+     * `AgentRunWorkflow`); both write the same `null`, and whichever gets there first is right. The
+     * thread id comes off the run's own recorded input, so this holds for a sub-agent's subthread too
+     * — read best-effort, because a gateway that cannot name the thread must not stop the cancel.
      *
      * A tool already executing is not interrupted, here or anywhere: see `haltIfCancelled` in core.
      */
     cancel(runId: string): Promise<void>;
+    /**
+     * Which thread a run was streaming, 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
+     * over. This id is only needed to clear the thread's active stream, and a stream still marked live
+     * is a far smaller fault than the one a throw here would cause — a run nobody ever told to stop,
+     * with a subscriber holding a stream that never settles, from the one call whose entire job is to
+     * make a run stop.
+     */
+    private threadOf;
 }
 
 /**
@@ -183,11 +202,10 @@ interface AgentDurableModuleOptions {
  * and exposes the durable runner via `AGENT_DURABLE_RUNNER`, which AgentModule binds to
  * `AGENT_RUNNER`. Forgetting this import makes AgentModule throw a clear error at boot.
  *
- * Always provides `AgentRunSteps` regardless of `dispatchedSteps` — the worker group it serves
- * (`AgentRunSteps.llm`/`.tool`) must never be orphaned by a config flag the durable step registrar
- * can't see ahead of time. This is the FULL ('both'/'engine'-equivalent) wiring: bare-importing this
- * class (no `forRoot()` call) always gets it, unconditionally — `forRoot({ surface: 'http' })` is
- * the only form that diverges (see `AgentDurableHttpModule` above).
+ * Provides `AgentRunSteps`, whose two groups (`AgentRunSteps.llm`/`.tool`) every turn dispatches to.
+ * This is the FULL ('both'/'engine'-equivalent) wiring: bare-importing this class (no `forRoot()`
+ * call) always gets it, unconditionally — `forRoot({ surface: 'http' })` is the only form that
+ * diverges (see `AgentDurableHttpModule` above).
  */
 declare class AgentDurableModule {
     /**
@@ -217,14 +235,4 @@ declare class AgentDurableModule {
  */
 declare function agentDurable(options: AgentModuleOptions): DynamicModule[];
 
-/**
- * DI flag carrying the EFFECTIVE `dispatchedSteps` value: whether `AgentRunWorkflow` dispatches its
- * `llm`/`tool` steps as routed remote steps (`AgentRunSteps`) instead of in-process `ctx.localStep`s.
- * `AgentDurableModule` derives it from `AGENT_OPTIONS` (`durable === true && dispatchedSteps ===
- * true`); `AgentRunWorkflow` injects it. Kept in its own file — `AgentDurableModule` provides
- * `AgentRunWorkflow` and `AgentRunWorkflow` injects this token, so declaring it in either of those
- * two files would make them import each other.
- */
-declare const AGENT_DISPATCHED_STEPS: unique symbol;
-
-export { AGENT_DISPATCHED_STEPS, AgentDurableModule, type AgentDurableModuleOptions, AgentRunSteps, AgentRunWorkflow, type DispatchedLlmInput, type DispatchedToolInput, DurableAgentRunner, agentDurable };
+export { AgentDurableModule, type AgentDurableModuleOptions, AgentRunSteps, AgentRunWorkflow, type DispatchedLlmInput, type DispatchedToolInput, DurableAgentRunner, agentDurable };