@dudousxd/nestjs-agent 0.4.0 → 0.5.0

package/dist/durable/index.d.cts

@@ -1,11 +1,60 @@
-import { AgentStore, AgentRunInput, AgentRunner, Decision } from '@dudousxd/nestjs-agent-core';
+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-BM_RB6br.cjs';
+import { A as AgentDepsFactory, a as AgentModuleOptions } from '../agent-deps.factory-DGM0IVtA.cjs';
 import { WorkflowService } from '@dudousxd/nestjs-durable';
 import { DynamicModule } from '@nestjs/common';
 
 /**
- * The agent turn AS a durable workflow. Each model/tool call is a checkpointed `ctx.step`, HITL is
+ * Serializable input for the dispatched `llm` step: a {@link LlmStepEnvelope} plus the sink routing
+ * only the durable runner knows (`sinkRunId`/`childSink`) — core's `AgentLoopHooks.dispatchLlm` stays
+ * sink-topology-agnostic, so the workflow adds these two fields when it builds the envelope.
+ */
+interface DispatchedLlmInput extends LlmStepEnvelope {
+    /**
+     * The dispatching workflow's own `ctx.runId` — the run this step's outcome accrues to for
+     * reliability metrics (`bumpRunRetries`). Carried even though the handler cannot bump retries
+     * today: the durable handler boundary (`runStepHandler`) hands a `@Step` method only
+     * `(input, StepLogger)` — the wire task's `attempt` is not exposed — so there is no clean way to
+     * detect a retry from inside the handler. Kept on the envelope so the bump can be wired without a
+     * wire-contract change once the durable runtime exposes the attempt.
+     */
+    runId: string;
+    /** The stream target: `input.sinkRunId ?? ctx.runId` of the dispatching workflow. */
+    sinkRunId: string;
+    /** True for a sub-agent run — wrap the writer with {@link childSinkWriter} (no end/fail). */
+    childSink: boolean;
+}
+/**
+ * The two long steps `AgentRunWorkflow` dispatches as routed remote steps when
+ * `dispatchedSteps: true` (`AgentRunSteps.llm` / `AgentRunSteps.tool`) instead of running them
+ * in-process under `ctx.localStep`. 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.
+ */
+declare class AgentRunSteps {
+    private readonly factory;
+    constructor(factory: AgentDepsFactory);
+    /**
+     * 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.
+     */
+    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.
+     */
+    tool(input: ToolStepEnvelope): Promise<unknown>;
+}
+
+/**
+ * The agent turn AS a durable workflow. Each model/tool call is a checkpointed `ctx.localStep` — the
+ * in-process primitive, NOT the always-dispatched `ctx.step`: the loop's deps (model provider, store,
+ * sink) live in THIS workflow worker's DI, and the step names are dynamic checkpoint identities
+ * (`llm:0`, `persist:toolcall:<id>`), not routable worker groups. 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
@@ -14,7 +63,9 @@ import { DynamicModule } from '@nestjs/common';
 declare class AgentRunWorkflow {
     private readonly factory;
     private readonly store;
-    constructor(factory: AgentDepsFactory, store: AgentStore);
+    private readonly steps;
+    private readonly dispatchedSteps;
+    constructor(factory: AgentDepsFactory, store: AgentStore, steps: AgentRunSteps, dispatchedSteps: boolean);
     run(ctx: WorkflowCtx, input: AgentRunInput): Promise<{
         text: string;
     }>;
@@ -40,6 +91,10 @@ declare class DurableAgentRunner implements AgentRunner {
  * configured `DurableModule`. It registers the `agent.run` workflow (discovered by DurableModule)
  * 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.
  */
 declare class AgentDurableModule {
     /**
@@ -63,4 +118,14 @@ declare class AgentDurableModule {
  */
 declare function agentDurable(options: AgentModuleOptions): DynamicModule[];
 
-export { AgentDurableModule, AgentRunWorkflow, DurableAgentRunner, agentDurable };
+/**
+ * DI flag mirroring `AgentModuleOptions.dispatchedSteps`: whether `AgentRunWorkflow` dispatches its
+ * `llm`/`tool` steps as routed remote steps (`AgentRunSteps`) instead of in-process `ctx.localStep`s.
+ * `AgentDurableModule` binds it from `AGENT_OPTIONS` (defaulting to `false`); `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, AgentRunSteps, AgentRunWorkflow, type DispatchedLlmInput, DurableAgentRunner, agentDurable };

package/dist/durable/index.d.ts

@@ -1,11 +1,60 @@
-import { AgentStore, AgentRunInput, AgentRunner, Decision } from '@dudousxd/nestjs-agent-core';
+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-BM_RB6br.js';
+import { A as AgentDepsFactory, a as AgentModuleOptions } from '../agent-deps.factory-DGM0IVtA.js';
 import { WorkflowService } from '@dudousxd/nestjs-durable';
 import { DynamicModule } from '@nestjs/common';
 
 /**
- * The agent turn AS a durable workflow. Each model/tool call is a checkpointed `ctx.step`, HITL is
+ * Serializable input for the dispatched `llm` step: a {@link LlmStepEnvelope} plus the sink routing
+ * only the durable runner knows (`sinkRunId`/`childSink`) — core's `AgentLoopHooks.dispatchLlm` stays
+ * sink-topology-agnostic, so the workflow adds these two fields when it builds the envelope.
+ */
+interface DispatchedLlmInput extends LlmStepEnvelope {
+    /**
+     * The dispatching workflow's own `ctx.runId` — the run this step's outcome accrues to for
+     * reliability metrics (`bumpRunRetries`). Carried even though the handler cannot bump retries
+     * today: the durable handler boundary (`runStepHandler`) hands a `@Step` method only
+     * `(input, StepLogger)` — the wire task's `attempt` is not exposed — so there is no clean way to
+     * detect a retry from inside the handler. Kept on the envelope so the bump can be wired without a
+     * wire-contract change once the durable runtime exposes the attempt.
+     */
+    runId: string;
+    /** The stream target: `input.sinkRunId ?? ctx.runId` of the dispatching workflow. */
+    sinkRunId: string;
+    /** True for a sub-agent run — wrap the writer with {@link childSinkWriter} (no end/fail). */
+    childSink: boolean;
+}
+/**
+ * The two long steps `AgentRunWorkflow` dispatches as routed remote steps when
+ * `dispatchedSteps: true` (`AgentRunSteps.llm` / `AgentRunSteps.tool`) instead of running them
+ * in-process under `ctx.localStep`. 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.
+ */
+declare class AgentRunSteps {
+    private readonly factory;
+    constructor(factory: AgentDepsFactory);
+    /**
+     * 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.
+     */
+    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.
+     */
+    tool(input: ToolStepEnvelope): Promise<unknown>;
+}
+
+/**
+ * The agent turn AS a durable workflow. Each model/tool call is a checkpointed `ctx.localStep` — the
+ * in-process primitive, NOT the always-dispatched `ctx.step`: the loop's deps (model provider, store,
+ * sink) live in THIS workflow worker's DI, and the step names are dynamic checkpoint identities
+ * (`llm:0`, `persist:toolcall:<id>`), not routable worker groups. 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
@@ -14,7 +63,9 @@ import { DynamicModule } from '@nestjs/common';
 declare class AgentRunWorkflow {
     private readonly factory;
     private readonly store;
-    constructor(factory: AgentDepsFactory, store: AgentStore);
+    private readonly steps;
+    private readonly dispatchedSteps;
+    constructor(factory: AgentDepsFactory, store: AgentStore, steps: AgentRunSteps, dispatchedSteps: boolean);
     run(ctx: WorkflowCtx, input: AgentRunInput): Promise<{
         text: string;
     }>;
@@ -40,6 +91,10 @@ declare class DurableAgentRunner implements AgentRunner {
  * configured `DurableModule`. It registers the `agent.run` workflow (discovered by DurableModule)
  * 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.
  */
 declare class AgentDurableModule {
     /**
@@ -63,4 +118,14 @@ declare class AgentDurableModule {
  */
 declare function agentDurable(options: AgentModuleOptions): DynamicModule[];
 
-export { AgentDurableModule, AgentRunWorkflow, DurableAgentRunner, agentDurable };
+/**
+ * DI flag mirroring `AgentModuleOptions.dispatchedSteps`: whether `AgentRunWorkflow` dispatches its
+ * `llm`/`tool` steps as routed remote steps (`AgentRunSteps`) instead of in-process `ctx.localStep`s.
+ * `AgentDurableModule` binds it from `AGENT_OPTIONS` (defaulting to `false`); `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, AgentRunSteps, AgentRunWorkflow, type DispatchedLlmInput, DurableAgentRunner, agentDurable };