@dudousxd/nestjs-agent 0.4.1 → 0.6.0

package/dist/durable/index.d.cts

@@ -1,23 +1,73 @@
-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-BlC9tumI.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.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
- * its action tools; the approval routes to the child's own run via `runForToolCall`.
+ * 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 (`AgentRunSteps.llm` /
+ * `AgentRunSteps.tool`) — the default under `durable: true`; `dispatchedSteps: false` runs them
+ * in-process under `ctx.localStep` instead. 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. 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` by default (`AGENT_DISPATCHED_STEPS`, ON under `durable: true`) so the
+ * run isn't pinned to this pod while they execute; `dispatchedSteps: false` keeps them 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`.
  */
 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;
     }>;
@@ -43,6 +93,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 {
     /**
@@ -66,4 +120,14 @@ declare class AgentDurableModule {
  */
 declare function agentDurable(options: AgentModuleOptions): DynamicModule[];
 
-export { AgentDurableModule, AgentRunWorkflow, DurableAgentRunner, agentDurable };
+/**
+ * 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 !==
+ * false` — default ON under durable); `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,23 +1,73 @@
-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-BlC9tumI.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.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
- * its action tools; the approval routes to the child's own run via `runForToolCall`.
+ * 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 (`AgentRunSteps.llm` /
+ * `AgentRunSteps.tool`) — the default under `durable: true`; `dispatchedSteps: false` runs them
+ * in-process under `ctx.localStep` instead. 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. 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` by default (`AGENT_DISPATCHED_STEPS`, ON under `durable: true`) so the
+ * run isn't pinned to this pod while they execute; `dispatchedSteps: false` keeps them 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`.
  */
 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;
     }>;
@@ -43,6 +93,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 {
     /**
@@ -66,4 +120,14 @@ declare class AgentDurableModule {
  */
 declare function agentDurable(options: AgentModuleOptions): DynamicModule[];
 
-export { AgentDurableModule, AgentRunWorkflow, DurableAgentRunner, agentDurable };
+/**
+ * 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 !==
+ * false` — default ON under durable); `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 };