@dudousxd/nestjs-agent 0.8.2 → 0.10.0

package/dist/durable/index.js

@@ -2,10 +2,10 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // src/durable/agent-run.workflow.ts
-import { AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY2, AGENT_STORE, QuotaExceededError, publishAgentRunFailed, runAgentLoop } from "@dudousxd/nestjs-agent-core";
+import { AGENT_DEPS_FACTORY, AGENT_STORE, QuotaExceededError, publishAgentRunFailed, runAgentLoop } from "@dudousxd/nestjs-agent-core";
 import { Workflow } from "@dudousxd/nestjs-durable";
 import { isWorkflowControlFlowSignal } from "@dudousxd/nestjs-durable-core";
-import { Inject as Inject2, Injectable as Injectable2 } from "@nestjs/common";
+import { Inject, Injectable, Optional } from "@nestjs/common";
 
 // src/agent-deps.ts
 function utcDay(date = /* @__PURE__ */ new Date()) {
@@ -23,10 +23,10 @@ function childSinkWriter(writer) {
 }
 __name(childSinkWriter, "childSinkWriter");
 
-// src/durable/agent-run.steps.ts
-import { AGENT_DEPS_FACTORY, traceLlmTurn, traceToolExecution, withToolTimeout } from "@dudousxd/nestjs-agent-core";
-import { Step } from "@dudousxd/nestjs-durable";
-import { Inject, Injectable } from "@nestjs/common";
+// src/durable/dispatched-steps.token.ts
+var AGENT_DISPATCHED_STEPS = Symbol.for("@dudousxd/nestjs-agent:dispatched-steps");
+
+// src/durable/agent-run.workflow.ts
 function _ts_decorate(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") r = Reflect.decorate(decorators, target, key, desc);
@@ -44,100 +44,6 @@ function _ts_param(paramIndex, decorator) {
   };
 }
 __name(_ts_param, "_ts_param");
-var AgentRunSteps = class {
-  static {
-    __name(this, "AgentRunSteps");
-  }
-  factory;
-  constructor(factory) {
-    this.factory = factory;
-  }
-  /**
-  * Retryable: every side effect (persist/quota/stream markers) happens loop-side under
-  * `hooks.step`, so a durable retry only re-runs the model call and re-streams its tokens — never
-  * 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) {
-    const deps = this.factory.forAgent(input.agentName);
-    const tools = await deps.registry.definitionsFor(input.actor, deps.rolesPolicy, deps.toolAllowList);
-    const opened = await deps.sink.open(input.sinkRunId);
-    const writer = input.childSink ? childSinkWriter(opened) : opened;
-    return traceLlmTurn(input.runId, input.step, () => deps.model.runTurn({
-      system: input.system,
-      messages: input.messages,
-      tools,
-      sink: writer
-    }));
-  }
-  /**
-  * No retries — a tool may not be idempotent (a bare `@Step()` carries none, unlike `llm` above).
-  * The timeout is applied HERE, handler-side, via `withToolTimeout` — never as a durable dispatch
-  * `timeoutMs`, which bounds engine liveness (retryable) rather than the tool's own business outcome.
-  */
-  async tool(input) {
-    const deps = this.factory.forAgent(input.ctx.agentName);
-    const ctx = {
-      ...input.ctx
-    };
-    return traceToolExecution(input.ctx.runId, {
-      toolCallId: input.toolCallId,
-      toolName: input.toolName,
-      toolType: input.toolType
-    }, () => {
-      const invocation = deps.registry.invoke(input.toolName, input.input, ctx, deps.rolesPolicy);
-      return input.timeoutMs !== void 0 ? withToolTimeout(invocation, input.timeoutMs, input.toolName) : invocation;
-    });
-  }
-};
-_ts_decorate([
-  Step({
-    retries: 3
-  }),
-  _ts_metadata("design:type", Function),
-  _ts_metadata("design:paramtypes", [
-    typeof DispatchedLlmInput === "undefined" ? Object : DispatchedLlmInput
-  ]),
-  _ts_metadata("design:returntype", Promise)
-], AgentRunSteps.prototype, "llm", null);
-_ts_decorate([
-  Step(),
-  _ts_metadata("design:type", Function),
-  _ts_metadata("design:paramtypes", [
-    typeof DispatchedToolInput === "undefined" ? Object : DispatchedToolInput
-  ]),
-  _ts_metadata("design:returntype", Promise)
-], AgentRunSteps.prototype, "tool", null);
-AgentRunSteps = _ts_decorate([
-  Injectable(),
-  _ts_param(0, Inject(AGENT_DEPS_FACTORY)),
-  _ts_metadata("design:type", Function),
-  _ts_metadata("design:paramtypes", [
-    typeof AgentDepsFactory === "undefined" ? Object : AgentDepsFactory
-  ])
-], AgentRunSteps);
-
-// src/durable/dispatched-steps.token.ts
-var AGENT_DISPATCHED_STEPS = Symbol.for("@dudousxd/nestjs-agent:dispatched-steps");
-
-// src/durable/agent-run.workflow.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") r = Reflect.decorate(decorators, target, key, desc);
-  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-  return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-__name(_ts_decorate2, "_ts_decorate");
-function _ts_metadata2(k, v) {
-  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
-__name(_ts_metadata2, "_ts_metadata");
-function _ts_param2(paramIndex, decorator) {
-  return function(target, key) {
-    decorator(target, key, paramIndex);
-  };
-}
-__name(_ts_param2, "_ts_param");
 var AgentRunWorkflow = class _AgentRunWorkflow {
   static {
     __name(this, "AgentRunWorkflow");
@@ -155,6 +61,7 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
   async run(ctx, input) {
     const day = input.day ?? utcDay();
     const deps = this.factory.forAgent(input.agentName);
+    const dispatchSteps = this.dispatchedSteps ? this.steps : void 0;
     if (input.sinkRunId !== void 0) {
       await ctx.localStep("activate", () => this.store.setActiveStream(input.threadId, ctx.runId));
     }
@@ -192,8 +99,8 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
       // `ctx.localStep`s, so a turn isn't pinned to this workflow worker for the model call or a tool
       // execution. `sinkRunId`/`childSink` are sink routing this workflow already resolved above —
       // core's dispatchLlm signature stays sink-topology-agnostic, so we add them here, not in core.
-      ...this.dispatchedSteps ? {
-        dispatchLlm: /* @__PURE__ */ __name((index, envelope) => ctx.step(this.steps.llm, {
+      ...dispatchSteps !== void 0 ? {
+        dispatchLlm: /* @__PURE__ */ __name((index, envelope) => ctx.step(dispatchSteps.llm, {
           ...envelope,
           runId: ctx.runId,
           step: index,
@@ -205,7 +112,7 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
         // ('agent'-kind delegations branch to runAgent earlier in the loop), so anything that
         // isn't 'action' is defensively 'read' — the same posture core takes for an
         // unresolvable `kind`.
-        dispatchTool: /* @__PURE__ */ __name((call, envelope) => ctx.step(this.steps.tool, {
+        dispatchTool: /* @__PURE__ */ __name((call, envelope) => ctx.step(dispatchSteps.tool, {
           ...envelope,
           toolCallId: call.id,
           toolType: call.kind === "action" ? "action" : "read"
@@ -246,24 +153,141 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
     }
   }
 };
-AgentRunWorkflow = _ts_decorate2([
-  Injectable2(),
+AgentRunWorkflow = _ts_decorate([
+  Injectable(),
   Workflow({
     name: "agent.run",
     version: "1"
   }),
-  _ts_param2(0, Inject2(AGENT_DEPS_FACTORY2)),
-  _ts_param2(1, Inject2(AGENT_STORE)),
-  _ts_param2(3, Inject2(AGENT_DISPATCHED_STEPS)),
-  _ts_metadata2("design:type", Function),
-  _ts_metadata2("design:paramtypes", [
+  _ts_param(0, Inject(AGENT_DEPS_FACTORY)),
+  _ts_param(1, Inject(AGENT_STORE)),
+  _ts_param(2, Optional()),
+  _ts_param(3, Inject(AGENT_DISPATCHED_STEPS)),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
     typeof AgentDepsFactory === "undefined" ? Object : AgentDepsFactory,
     typeof AgentStore === "undefined" ? Object : AgentStore,
-    typeof AgentRunSteps === "undefined" ? Object : AgentRunSteps,
+    Object,
     Boolean
   ])
 ], AgentRunWorkflow);
 
+// src/durable/agent-run.steps.ts
+import { AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY2, invokeWithTransientRetry, publishAgentToolRetry, traceLlmTurn, traceToolExecution, withToolTimeout } from "@dudousxd/nestjs-agent-core";
+import { Step } from "@dudousxd/nestjs-durable";
+import { Inject as Inject2, Injectable as Injectable2 } from "@nestjs/common";
+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") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate2, "_ts_decorate");
+function _ts_metadata2(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata2, "_ts_metadata");
+function _ts_param2(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param2, "_ts_param");
+var AgentRunSteps = class {
+  static {
+    __name(this, "AgentRunSteps");
+  }
+  factory;
+  constructor(factory) {
+    this.factory = factory;
+  }
+  /**
+  * Retryable: every side effect (persist/quota/stream markers) happens loop-side under
+  * `hooks.step`, so a durable retry only re-runs the model call and re-streams its tokens — never
+  * 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) {
+    const deps = this.factory.forAgent(input.agentName);
+    const tools = await deps.registry.definitionsFor(input.actor, deps.rolesPolicy, deps.toolAllowList);
+    const opened = await deps.sink.open(input.sinkRunId);
+    const writer = input.childSink ? childSinkWriter(opened) : opened;
+    return traceLlmTurn(input.runId, input.step, () => deps.model.runTurn({
+      system: input.system,
+      messages: input.messages,
+      tools,
+      sink: writer
+    }));
+  }
+  /**
+  * NO DURABLE retries — a tool may not be idempotent (a bare `@Step()` carries none, unlike `llm`
+  * above). What it does retry, in place, is a CLASSIFIED-TRANSIENT error from the tool's own
+  * invocation (a DB deadlock, a lock-wait timeout — see `isTransientToolError`): the server rolled
+  * that work back, so re-invoking it is safe, and doing it here (inside this one step, never a new
+  * checkpoint) is exactly how the non-dispatched loop path handles it too. The timeout is applied
+  * HERE, handler-side, via `withToolTimeout` — never as a durable dispatch `timeoutMs`, which
+  * 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) {
+    const deps = this.factory.forAgent(input.ctx.agentName);
+    const ctx = {
+      ...input.ctx
+    };
+    const localClassify = deps.toolTransientRetry !== false ? deps.toolTransientRetry?.classify : void 0;
+    const transientRetry = input.transientRetry === false ? false : {
+      attempts: input.transientRetry.attempts,
+      backoffMs: input.transientRetry.backoffMs,
+      ...localClassify !== void 0 ? {
+        classify: localClassify
+      } : {}
+    };
+    return traceToolExecution(input.ctx.runId, {
+      toolCallId: input.toolCallId,
+      toolName: input.toolName,
+      toolType: input.toolType
+    }, () => invokeWithTransientRetry(() => {
+      const invocation = deps.registry.invoke(input.toolName, input.input, ctx, deps.rolesPolicy);
+      return input.timeoutMs !== void 0 ? withToolTimeout(invocation, input.timeoutMs, input.toolName) : invocation;
+    }, transientRetry, {
+      onRetry: /* @__PURE__ */ __name((attempt, error) => {
+        publishAgentToolRetry({
+          toolName: input.toolName,
+          toolCallId: input.toolCallId,
+          attempt,
+          message: error instanceof Error ? error.message : String(error)
+        });
+      }, "onRetry")
+    }));
+  }
+};
+_ts_decorate2([
+  Step({
+    retries: 3
+  }),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof DispatchedLlmInput === "undefined" ? Object : DispatchedLlmInput
+  ]),
+  _ts_metadata2("design:returntype", Promise)
+], AgentRunSteps.prototype, "llm", null);
+_ts_decorate2([
+  Step(),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof DispatchedToolInput === "undefined" ? Object : DispatchedToolInput
+  ]),
+  _ts_metadata2("design:returntype", Promise)
+], AgentRunSteps.prototype, "tool", null);
+AgentRunSteps = _ts_decorate2([
+  Injectable2(),
+  _ts_param2(0, Inject2(AGENT_DEPS_FACTORY2)),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof AgentDepsFactory === "undefined" ? Object : AgentDepsFactory
+  ])
+], AgentRunSteps);
+
 // src/durable/durable-agent-runner.ts
 import { randomUUID } from "node:crypto";
 import { WorkflowService } from "@dudousxd/nestjs-durable";
@@ -401,16 +425,68 @@ function _ts_decorate4(decorators, target, key, desc) {
 }
 __name(_ts_decorate4, "_ts_decorate");
 var logger = new Logger("AgentDurableModule");
+function runnerProviders() {
+  return [
+    DurableAgentRunner,
+    {
+      provide: AGENT_DURABLE_RUNNER,
+      useExisting: DurableAgentRunner
+    },
+    {
+      provide: AGENT_DISPATCHED_STEPS,
+      useFactory: /* @__PURE__ */ __name((options, sink) => {
+        const enabled = options.durable === true && options.dispatchedSteps !== false;
+        if (enabled && sink instanceof InProcessTokenStreamSink) {
+          logger.warn("Dispatched steps are active (the default under durable: true) with the default InProcessTokenStreamSink, which only buffers tokens in-process. A dispatched `llm` step served by a different worker cannot stream into this buffer. Wire a cross-process TokenStreamSink (e.g. a Redis pub/sub sink) via AgentModule.forRoot({ sink }) before running multi-pod, or set dispatchedSteps: false to keep the turn in-process localSteps.");
+        }
+        return enabled;
+      }, "useFactory"),
+      inject: [
+        AGENT_OPTIONS,
+        AGENT_SINK
+      ]
+    }
+  ];
+}
+__name(runnerProviders, "runnerProviders");
+var AgentDurableHttpModule = class AgentDurableHttpModule2 {
+  static {
+    __name(this, "AgentDurableHttpModule");
+  }
+};
+AgentDurableHttpModule = _ts_decorate4([
+  Global(),
+  Module({
+    providers: [
+      AgentRunWorkflow,
+      ...runnerProviders()
+    ],
+    exports: [
+      AGENT_DURABLE_RUNNER,
+      AgentRunWorkflow,
+      AGENT_DISPATCHED_STEPS
+    ]
+  })
+], AgentDurableHttpModule);
 var AgentDurableModule = class _AgentDurableModule {
   static {
     __name(this, "AgentDurableModule");
   }
   /**
-  * The dynamic form used by the `agentDurable` helper. The module needs no configuration of its
-  * own (its providers come from the decorator above), so this just yields the module reference —
-  * importing `AgentDurableModule` directly stays equivalent.
+  * `surface: 'http'` returns the reduced `AgentDurableHttpModule` wiring (no `AgentRunSteps`);
+  * everything else (omitted, `'engine'`, `'both'`) returns this module's own full wiring — the
+  * class's `@Module` providers above merge in regardless of which DynamicModule shape a caller
+  * imports (Nest merges a class's static provider list with whatever a self-referencing
+  * `DynamicModule` adds), which is exactly why the reduced case has to be a DIFFERENT module class
+  * rather than a conditional subset of this one's own decorator.
   */
-  static forRoot() {
+  static forRoot(options) {
+    if (options?.surface === "http") {
+      return {
+        module: AgentDurableHttpModule,
+        global: true
+      };
+    }
     return {
       module: _AgentDurableModule,
       global: true
@@ -423,25 +499,7 @@ AgentDurableModule = _ts_decorate4([
     providers: [
       AgentRunWorkflow,
       AgentRunSteps,
-      DurableAgentRunner,
-      {
-        provide: AGENT_DURABLE_RUNNER,
-        useExisting: DurableAgentRunner
-      },
-      {
-        provide: AGENT_DISPATCHED_STEPS,
-        useFactory: /* @__PURE__ */ __name((options, sink) => {
-          const enabled = options.durable === true && options.dispatchedSteps !== false;
-          if (enabled && sink instanceof InProcessTokenStreamSink) {
-            logger.warn("Dispatched steps are active (the default under durable: true) with the default InProcessTokenStreamSink, which only buffers tokens in-process. A dispatched `llm` step served by a different worker cannot stream into this buffer. Wire a cross-process TokenStreamSink (e.g. a Redis pub/sub sink) via AgentModule.forRoot({ sink }) before running multi-pod, or set dispatchedSteps: false to keep the turn in-process localSteps.");
-          }
-          return enabled;
-        }, "useFactory"),
-        inject: [
-          AGENT_OPTIONS,
-          AGENT_SINK
-        ]
-      }
+      ...runnerProviders()
     ],
     exports: [
       AGENT_DURABLE_RUNNER,
@@ -460,7 +518,7 @@ import { DiscoveryModule, RouterModule } from "@nestjs/core";
 // src/agent-deps.factory.ts
 import { AGENT_MODEL, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_ROLES_POLICY, AGENT_SINK as AGENT_SINK2, AGENT_STORE as AGENT_STORE2, AGENT_TOOL_REGISTRY, AgentRegistry as AgentRegistry2, ToolRegistry as ToolRegistry2 } from "@dudousxd/nestjs-agent-core";
 import { AGENT_OPTIONS as AGENT_OPTIONS2 } from "@dudousxd/nestjs-agent-core";
-import { Inject as Inject3, Injectable as Injectable4, Optional } from "@nestjs/common";
+import { Inject as Inject3, Injectable as Injectable4, Optional as Optional2 } from "@nestjs/common";
 function _ts_decorate5(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") r = Reflect.decorate(decorators, target, key, desc);
@@ -562,6 +620,9 @@ var AgentDepsFactory2 = class {
       ...this.options.toolTimeoutMs !== void 0 ? {
         toolTimeoutMs: this.options.toolTimeoutMs
       } : {},
+      ...this.options.toolTransientRetry !== void 0 ? {
+        toolTransientRetry: this.options.toolTransientRetry
+      } : {},
       ...followUpsCount !== void 0 ? {
         followUpsCount
       } : {},
@@ -596,7 +657,7 @@ AgentDepsFactory2 = _ts_decorate5([
   _ts_param3(6, Inject3(AGENT_REGISTRY)),
   _ts_param3(7, Inject3(AGENT_PROMPT_CONTRIBUTORS)),
   _ts_param3(8, Inject3(AGENT_QUOTA_STORE)),
-  _ts_param3(9, Optional()),
+  _ts_param3(9, Optional2()),
   _ts_param3(9, Inject3(AGENT_PRICING_STORE)),
   _ts_metadata4("design:type", Function),
   _ts_metadata4("design:paramtypes", [
@@ -1024,7 +1085,7 @@ AgentsController = _ts_decorate8([
 
 // src/controller/attachments.controller.ts
 import { AGENT_ACTOR_RESOLVER, AGENT_ATTACHMENT_STAGING, AGENT_OPTIONS as AGENT_OPTIONS3 } from "@dudousxd/nestjs-agent-core";
-import { BadRequestException as BadRequestException2, Controller as Controller2, Inject as Inject6, NotImplementedException as NotImplementedException2, Optional as Optional2, PayloadTooLargeException, Post, Req, UnsupportedMediaTypeException, UploadedFile, UseInterceptors } from "@nestjs/common";
+import { BadRequestException as BadRequestException2, Controller as Controller2, Inject as Inject6, NotImplementedException as NotImplementedException2, Optional as Optional3, PayloadTooLargeException, Post, Req, UnsupportedMediaTypeException, UploadedFile, UseInterceptors } from "@nestjs/common";
 import { FileInterceptor } from "@nestjs/platform-express";
 function _ts_decorate9(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -1117,7 +1178,7 @@ AttachmentsController = _ts_decorate9([
   Controller2("attachments"),
   _ts_param6(0, Inject6(AGENT_OPTIONS3)),
   _ts_param6(1, Inject6(AGENT_ACTOR_RESOLVER)),
-  _ts_param6(2, Optional2()),
+  _ts_param6(2, Optional3()),
   _ts_param6(2, Inject6(AGENT_ATTACHMENT_STAGING)),
   _ts_metadata8("design:type", Function),
   _ts_metadata8("design:paramtypes", [
@@ -2225,6 +2286,10 @@ function controllersFor(mountAttachments) {
   ] : BASE_CONTROLLERS;
 }
 __name(controllersFor, "controllersFor");
+function controllersForSurface(surface, mountAttachments) {
+  return surface === "engine" ? [] : controllersFor(mountAttachments);
+}
+__name(controllersForSurface, "controllersForSurface");
 var GUARDS_METADATA = "__guards__";
 function applyGuards(guards) {
   const resolved = guards ?? [];
@@ -2270,7 +2335,7 @@ var AgentModule = class _AgentModule {
         DiscoveryModule,
         routerFor(path)
       ],
-      controllers: controllersFor(options.attachments?.upload === true),
+      controllers: controllersForSurface(options.surface, options.attachments?.upload === true),
       providers: [
         {
           provide: AGENT_OPTIONS5,
@@ -2295,17 +2360,21 @@ var AgentModule = class _AgentModule {
         routerFor(path),
         ...options.imports ?? []
       ],
-      controllers: controllersFor(options.attachmentsUpload === true),
+      controllers: controllersForSurface(options.surface, options.attachmentsUpload === true),
       providers: [
         {
           provide: AGENT_OPTIONS5,
-          // Stamp the STATIC wiring flags onto the factory result: `durable`/`dispatchedSteps` are
-          // authoritative on the async config object (they decided the actual wiring above), and
-          // `AgentDurableModule` derives the effective dispatched-steps value from AGENT_OPTIONS —
-          // without this stamp, an async host would get in-process localSteps despite durable: true.
+          // Stamp the STATIC wiring flags onto the factory result: `durable`/`dispatchedSteps`/
+          // `surface` are authoritative on the async config object (they decided the actual wiring
+          // above), and `AgentDurableModule` derives the effective dispatched-steps value from
+          // AGENT_OPTIONS — without this stamp, an async host would get in-process localSteps
+          // despite durable: true. `surface` isn't read back by anything today (AgentDurableModule
+          // takes its own mirror option — see its doc for why), but it's stamped here too so the
+          // EFFECTIVE value is always observable off AGENT_OPTIONS, sync or async alike.
           useFactory: /* @__PURE__ */ __name(async (...args) => ({
             ...await options.useFactory(...args),
             durable: options.durable ?? false,
+            surface: options.surface ?? "both",
             ...options.dispatchedSteps !== void 0 ? {
               dispatchedSteps: options.dispatchedSteps
             } : {}
@@ -2331,7 +2400,9 @@ function agentDurable(options) {
       ...options,
       durable: true
     }),
-    AgentDurableModule.forRoot()
+    AgentDurableModule.forRoot(options.surface !== void 0 ? {
+      surface: options.surface
+    } : {})
   ];
 }
 __name(agentDurable, "agentDurable");