@dudousxd/nestjs-agent 0.8.2 → 0.10.0

package/dist/durable/index.d.cts

@@ -1,6 +1,6 @@
 import { LlmStepEnvelope, ModelTurnResult, ToolStepEnvelope, AgentStore, AgentRunInput, AgentRunner, Decision } from '@dudousxd/nestjs-agent-core';
 import { WorkflowCtx } from '@dudousxd/nestjs-durable-core';
-import { A as AgentDepsFactory, a as AgentModuleOptions } from '../agent-deps.factory-BlC9tumI.cjs';
+import { A as AgentDepsFactory, a as AgentSurface, b as AgentModuleOptions } from '../agent-deps.factory-D7GdhqdK.cjs';
 import { WorkflowService } from '@dudousxd/nestjs-durable';
 import { DynamicModule } from '@nestjs/common';
 
@@ -56,9 +56,14 @@ declare class AgentRunSteps {
      */
     llm(input: DispatchedLlmInput): Promise<ModelTurnResult>;
     /**
-     * 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.
+     * 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.
      */
     tool(input: DispatchedToolInput): Promise<unknown>;
 }
@@ -80,7 +85,7 @@ declare class AgentRunWorkflow {
     private readonly store;
     private readonly steps;
     private readonly dispatchedSteps;
-    constructor(factory: AgentDepsFactory, store: AgentStore, steps: AgentRunSteps, dispatchedSteps: boolean);
+    constructor(factory: AgentDepsFactory, store: AgentStore, steps: AgentRunSteps | undefined, dispatchedSteps: boolean);
     run(ctx: WorkflowCtx, input: AgentRunInput): Promise<{
         text: string;
     }>;
@@ -101,6 +106,31 @@ declare class DurableAgentRunner implements AgentRunner {
     cancel(_runId: string): Promise<void>;
 }
 
+/**
+ * `AgentDurableModule.forRoot()` options. `surface` mirrors `AgentModuleOptions.surface` — it has
+ * to be its OWN option here (not read off the shared `AGENT_OPTIONS` provider) because Nest builds
+ * a module's provider LIST at static/decoration time, before any DI value (including
+ * `AGENT_OPTIONS`) exists to read; there is no way to make a `providers` array conditional on an
+ * injected value. Keep both in sync — `agentDurable()` (`./agent-durable.js`) does this
+ * automatically for the one-call setup; importing `AgentModule`/`AgentDurableModule` separately
+ * means passing `surface` to both by hand.
+ */
+interface AgentDurableModuleOptions {
+    /**
+     * Omit (or `'engine'`/`'both'`) for today's full wiring, unconditionally — identical to importing
+     * the bare `AgentDurableModule` class (registers `agent.run` AND `AgentRunSteps.llm`/`.tool`).
+     *
+     * `'http'` registers the `agent.run` WORKFLOW (so `WorkflowService.start(AgentRunWorkflow, …)`
+     * still works — `engine.start` requires local registration to validate/persist a new run, even
+     * on an enqueue-only pod) but does NOT provide `AgentRunSteps` — the fix for the flip incident
+     * this option exists for: an API pod that also registered the dispatched-step handlers
+     * subscribed their queues and ran LLM/tool work meant for the worker fleet. Pair `surface: 'http'`
+     * with the durable `DurableModule.forRoot({ drive: false })` enqueue-only config so this pod also
+     * never DRIVES (polls/executes) the run it just registered — registration alone only satisfies
+     * `start()`'s bookkeeping, it doesn't make this pod execute anything on its own.
+     */
+    surface?: AgentSurface;
+}
 /**
  * Opt-in durable runner. Import this alongside `AgentModule.forRoot({ durable: true })` and a
  * configured `DurableModule`. It registers the `agent.run` workflow (discovered by DurableModule)
@@ -109,15 +139,20 @@ declare class DurableAgentRunner implements AgentRunner {
  *
  * 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.
+ * 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).
  */
 declare class 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(): DynamicModule;
+    static forRoot(options?: AgentDurableModuleOptions): DynamicModule;
 }
 
 /**
@@ -129,7 +164,10 @@ declare class AgentDurableModule {
  *
  * It wires `AgentModule.forRoot({ ...options, durable: true })` together with `AgentDurableModule`,
  * the equivalent of importing both by hand. A configured `DurableModule` is still required. The
- * durable runner has no configuration of its own, so `options` is exactly the agent options.
+ * durable runner has no configuration of its own beyond the agent options, so `options` is exactly
+ * `AgentModuleOptions` — including `surface`, which this helper threads to BOTH calls so a consumer
+ * sets it in exactly one place (see `AgentModuleOptions.surface` / `AgentDurableModuleOptions.surface`
+ * for why each needs its own copy of the value rather than one reading it off the other via DI).
  */
 declare function agentDurable(options: AgentModuleOptions): DynamicModule[];
 
@@ -143,4 +181,4 @@ declare function agentDurable(options: AgentModuleOptions): DynamicModule[];
  */
 declare const AGENT_DISPATCHED_STEPS: unique symbol;
 
-export { AGENT_DISPATCHED_STEPS, AgentDurableModule, AgentRunSteps, AgentRunWorkflow, type DispatchedLlmInput, type DispatchedToolInput, DurableAgentRunner, agentDurable };
+export { AGENT_DISPATCHED_STEPS, AgentDurableModule, type AgentDurableModuleOptions, AgentRunSteps, AgentRunWorkflow, type DispatchedLlmInput, type DispatchedToolInput, DurableAgentRunner, agentDurable };

package/dist/durable/index.d.ts

@@ -1,6 +1,6 @@
 import { LlmStepEnvelope, ModelTurnResult, ToolStepEnvelope, AgentStore, AgentRunInput, AgentRunner, Decision } from '@dudousxd/nestjs-agent-core';
 import { WorkflowCtx } from '@dudousxd/nestjs-durable-core';
-import { A as AgentDepsFactory, a as AgentModuleOptions } from '../agent-deps.factory-BlC9tumI.js';
+import { A as AgentDepsFactory, a as AgentSurface, b as AgentModuleOptions } from '../agent-deps.factory-D7GdhqdK.js';
 import { WorkflowService } from '@dudousxd/nestjs-durable';
 import { DynamicModule } from '@nestjs/common';
 
@@ -56,9 +56,14 @@ declare class AgentRunSteps {
      */
     llm(input: DispatchedLlmInput): Promise<ModelTurnResult>;
     /**
-     * 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.
+     * 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.
      */
     tool(input: DispatchedToolInput): Promise<unknown>;
 }
@@ -80,7 +85,7 @@ declare class AgentRunWorkflow {
     private readonly store;
     private readonly steps;
     private readonly dispatchedSteps;
-    constructor(factory: AgentDepsFactory, store: AgentStore, steps: AgentRunSteps, dispatchedSteps: boolean);
+    constructor(factory: AgentDepsFactory, store: AgentStore, steps: AgentRunSteps | undefined, dispatchedSteps: boolean);
     run(ctx: WorkflowCtx, input: AgentRunInput): Promise<{
         text: string;
     }>;
@@ -101,6 +106,31 @@ declare class DurableAgentRunner implements AgentRunner {
     cancel(_runId: string): Promise<void>;
 }
 
+/**
+ * `AgentDurableModule.forRoot()` options. `surface` mirrors `AgentModuleOptions.surface` — it has
+ * to be its OWN option here (not read off the shared `AGENT_OPTIONS` provider) because Nest builds
+ * a module's provider LIST at static/decoration time, before any DI value (including
+ * `AGENT_OPTIONS`) exists to read; there is no way to make a `providers` array conditional on an
+ * injected value. Keep both in sync — `agentDurable()` (`./agent-durable.js`) does this
+ * automatically for the one-call setup; importing `AgentModule`/`AgentDurableModule` separately
+ * means passing `surface` to both by hand.
+ */
+interface AgentDurableModuleOptions {
+    /**
+     * Omit (or `'engine'`/`'both'`) for today's full wiring, unconditionally — identical to importing
+     * the bare `AgentDurableModule` class (registers `agent.run` AND `AgentRunSteps.llm`/`.tool`).
+     *
+     * `'http'` registers the `agent.run` WORKFLOW (so `WorkflowService.start(AgentRunWorkflow, …)`
+     * still works — `engine.start` requires local registration to validate/persist a new run, even
+     * on an enqueue-only pod) but does NOT provide `AgentRunSteps` — the fix for the flip incident
+     * this option exists for: an API pod that also registered the dispatched-step handlers
+     * subscribed their queues and ran LLM/tool work meant for the worker fleet. Pair `surface: 'http'`
+     * with the durable `DurableModule.forRoot({ drive: false })` enqueue-only config so this pod also
+     * never DRIVES (polls/executes) the run it just registered — registration alone only satisfies
+     * `start()`'s bookkeeping, it doesn't make this pod execute anything on its own.
+     */
+    surface?: AgentSurface;
+}
 /**
  * Opt-in durable runner. Import this alongside `AgentModule.forRoot({ durable: true })` and a
  * configured `DurableModule`. It registers the `agent.run` workflow (discovered by DurableModule)
@@ -109,15 +139,20 @@ declare class DurableAgentRunner implements AgentRunner {
  *
  * 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.
+ * 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).
  */
 declare class 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(): DynamicModule;
+    static forRoot(options?: AgentDurableModuleOptions): DynamicModule;
 }
 
 /**
@@ -129,7 +164,10 @@ declare class AgentDurableModule {
  *
  * It wires `AgentModule.forRoot({ ...options, durable: true })` together with `AgentDurableModule`,
  * the equivalent of importing both by hand. A configured `DurableModule` is still required. The
- * durable runner has no configuration of its own, so `options` is exactly the agent options.
+ * durable runner has no configuration of its own beyond the agent options, so `options` is exactly
+ * `AgentModuleOptions` — including `surface`, which this helper threads to BOTH calls so a consumer
+ * sets it in exactly one place (see `AgentModuleOptions.surface` / `AgentDurableModuleOptions.surface`
+ * for why each needs its own copy of the value rather than one reading it off the other via DI).
  */
 declare function agentDurable(options: AgentModuleOptions): DynamicModule[];
 
@@ -143,4 +181,4 @@ declare function agentDurable(options: AgentModuleOptions): DynamicModule[];
  */
 declare const AGENT_DISPATCHED_STEPS: unique symbol;
 
-export { AGENT_DISPATCHED_STEPS, AgentDurableModule, AgentRunSteps, AgentRunWorkflow, type DispatchedLlmInput, type DispatchedToolInput, DurableAgentRunner, agentDurable };
+export { AGENT_DISPATCHED_STEPS, AgentDurableModule, type AgentDurableModuleOptions, AgentRunSteps, AgentRunWorkflow, type DispatchedLlmInput, type DispatchedToolInput, DurableAgentRunner, agentDurable };