Runners

The agent loop doesn't know or care how its step and awaitApproval hooks are implemented — that's the whole point of the AgentRunner SPI. Two implementations exist, and switching between them never touches your tools, your frontend, or the wire protocol.

interface AgentRunner {
  start(input: AgentRunInput, options?: { runId?: string }): Promise<{ runId: string }>;
  isRunActive?(runId: string): Promise<boolean>;
  // HumanReply = Decision (approve/reject an action) | ElicitationReply (answers to an `ask`)
  signal(runId: string, toolCallId: string, reply: HumanReply): Promise<void>;
  cancel(runId: string): Promise<void>;
}

start enqueues and returns immediately with the runId — the actual tokens flow separately over the TokenStreamSink data plane, not through this call. See Architecture for how the control and data planes split.

cancel really stops the run: the loop observes the request between steps, before the next model call, and before a turn's tools are dispatched, then unwinds — recording the run cancelled (its own terminal, not a failure) and ending the stream on a { kind: 'cancelled' } frame. Under the inline runner the model call in flight is aborted at once (and its step not persisted), and tools receive the same signal as ctx.abortSignal; a tool that ignores it is left to finish. See Cancelling a run for the full behaviour, including what each runner does about a turn parked on a human.

Inline (default) vs. durable (opt-in)Copy Anchor Link

AgentModule.forRoot binds InlineAgentRunner to the AGENT_RUNNER token unless durable: true is set — inline is the real, zero-dependency default, not a fallback.

When to pick whichCopy Anchor Link

• Inline for local development, tests (pairs naturally with @dudousxd/nestjs-agent-testing's fake model and in-memory store), and any deployment where a lost in-flight turn on a crash is acceptable.
• Durable once you need a turn to survive a process restart mid-approval, want every model and tool call individually checkpointed (so a crash replays from cache instead of re-charging the model or re-running a side effect), or already run @dudousxd/nestjs-durable elsewhere in the app.

Because the AgentRunner SPI is the only seam, you can develop against inline and flip to durable in production by changing configuration, not code.

Dispatched steps: what the durable runner does with a turnCopy Anchor Link

Under durable: true, the workflow's bookkeeping (persisting a message, bumping quota, stream markers) checkpoints as ctx.localStep — pinned to whichever worker is running the workflow. The turn's two genuinely long operations — the model call and each tool execution — are dispatched as separately-routed durable steps instead (AgentRunSteps.llm / AgentRunSteps.tool), so a turn isn't pinned to one pod for however long the model takes to respond or a tool takes to run. That is not a setting: ctx.step is the one step primitive in nestjs-durable, whose ctx.localStep is the deliberate escape hatch for work that must run in the body, and the agent's bookkeeping is what uses it.

A turn that asks for several read tools dispatches them together — one suspend, N workers busy at once, rather than a suspend/resume round trip per call. See The agent loop for the ordering rules that keep that replay-safe.

Both worker groups are registered by AgentDurableModule under every surface but 'http', so a fleet never ends up routing to an unserved worker group.

Your tool handlers are what pays for this: an @AiTool handler runs in the serving worker with nothing of the originating request ambient around it, exactly like any @Step handler in this ecosystem. A handler that reaches for a request-scoped ORM EntityManager, an AsyncLocalStorage tenant or a CLS transaction has to establish it — @CreateRequestContext() / @EnsureRequestContext() under MikroORM. A handler that does not throws in the worker: the call is recorded failed, the model receives the error, the turn completes, and an action tool's human approval has been spent on something that never ran.

The workflow routes by the @Step-stamped NAME, read off AgentRunSteps.prototype, and never holds the instance. That matters on the 'http' surface, which registers the workflow but deliberately provides no AgentRunSteps: were the branch conditional on having one, the same run would write in-process checkpoint names on an http pod and routed ones on an engine pod, and whichever replayed second would fail on the mismatch. Which branch a turn takes is a property of the run, not of the process replaying it.

The one-import shortcutCopy Anchor Link

The long form wires durable: true on AgentModule.forRoot and imports AgentDurableModule separately. agentDurable(options) collapses both into one:

import { DurableModule } from '@dudousxd/nestjs-durable';
import { agentDurable } from '@dudousxd/nestjs-agent/durable';

@Module({
  imports: [
    DurableModule.forRoot({ /* store, transport, … */ }),
    ...agentDurable({
      model: myModelProvider,
      store: myAgentStore,
      actorResolver: new HeaderActorResolver(),
      // ...same options as AgentModule.forRoot, minus `durable`
    }),
  ],
})
export class AppModule {}

agentDurable spreads into imports because it wires AgentModule.forRoot({ ...options, durable: true }) and AgentDurableModule together — it isn't a module itself.

Full detailsCopy Anchor Link

The mechanics of the durable suspend itself — the agent.run workflow, ctx.waitForSignal, and resuming a dropped stream — are in Human-in-the-loop & Durability; the durable runtime it depends on is documented in full at @dudousxd/nestjs-durable.

Where to go nextCopy Anchor Link