@dudousxd/nestjs-agent 0.11.1 → 0.13.0

package/dist/durable/index.d.cts

@@ -1,8 +1,55 @@
-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 AgentSurface, b as AgentModuleOptions } from '../agent-deps.factory-D7GdhqdK.cjs';
+import { AgentStore, AgentRunInput, AgentLoopResult, LlmStepEnvelope, BufferedModelTurnResult, ToolStepEnvelope, AgentRunner, TokenStreamSink, HumanReply } from '@dudousxd/nestjs-agent-core';
+import { RunGateway, WorkflowCtx } from '@dudousxd/nestjs-durable-core';
+import { A as AgentDepsFactory, a as AgentSurface, b as AgentModuleOptions } from '../agent-deps.factory-y2hvoQ6U.cjs';
 import { WorkflowService } from '@dudousxd/nestjs-durable';
 import { DynamicModule } from '@nestjs/common';
+import '@standard-schema/spec';
+
+/**
+ * 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` where the deployment asked for it (`AGENT_DISPATCHED_STEPS`, from
+ * `dispatchedSteps: true`) so the run isn't pinned to this pod while they execute; without that
+ * flag they are 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;
+    private readonly dispatchedSteps;
+    private readonly runs?;
+    constructor(factory: AgentDepsFactory, store: AgentStore, dispatchedSteps: boolean, runs?: RunGateway | undefined);
+    /**
+     * Has someone asked this run to stop? Read from the runtime's own run status, which is where
+     * `DurableAgentRunner.cancel` puts it — `cancelling` while a compensating cancel is in flight,
+     * `cancelled` once it has settled.
+     *
+     * Costs a run read at each of the loop's observation points (two per step). That is a row the
+     * control plane already has, against a turn that is otherwise making model calls, and it buys the
+     * property that matters: the answer comes from a place BOTH the canceller and every pod that might
+     * replay this run can see.
+     *
+     * Failing to ask is not a cancel. A tenant with no gateway wired, or an operator briefly
+     * unreachable, answers "no" and the run carries on — the alternative is failing healthy runs
+     * because a status read timed out. The loop journals that answer like any other, so two processes
+     * can never disagree about what was seen here.
+     */
+    private isCancelled;
+    /**
+     * Settle the delegation a DETACHED run was started for, when that run ends without an answer.
+     *
+     * The loop delivers its own success (`deliver:detached`) but cannot catch its own crash, and the
+     * runtime settles the run row without knowing anything delegated it. Left alone, the card in the
+     * calling conversation says "started" for ever — the one state a reader can neither wait on nor
+     * act on. A no-op for every other run: only a detached one carries a delivery address.
+     */
+    private settleDetachedParent;
+    run(ctx: WorkflowCtx, input: AgentRunInput): Promise<AgentLoopResult>;
+}
 
 /**
  * Serializable input for the dispatched `llm` step: a {@link LlmStepEnvelope} plus the sink routing
@@ -39,8 +86,8 @@ interface DispatchedToolInput extends ToolStepEnvelope {
 }
 /**
  * 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
+ * `AgentRunSteps.tool`) under `dispatchedSteps: true`; omitting that flag 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.
@@ -54,7 +101,7 @@ declare class AgentRunSteps {
      * 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>;
+    llm(input: DispatchedLlmInput): Promise<BufferedModelTurnResult>;
     /**
      * 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
@@ -68,42 +115,41 @@ declare class AgentRunSteps {
     tool(input: DispatchedToolInput): 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;
-    private readonly steps;
-    private readonly dispatchedSteps;
-    constructor(factory: AgentDepsFactory, store: AgentStore, steps: AgentRunSteps | undefined, dispatchedSteps: boolean);
-    run(ctx: WorkflowCtx, input: AgentRunInput): Promise<{
-        text: string;
-    }>;
-}
-
 /**
  * Runs the agent turn as a `@dudousxd/nestjs-durable` workflow. `start` creates the run and returns
- * its id immediately; a worker runs the body and streams tokens to the sink. HITL approval is
- * delivered as a durable signal namespaced by run, so it can never cross-resolve another run.
+ * its id immediately; a worker runs the body and streams tokens to the sink. Everything a human
+ * sends back into a parked run — a HITL approval, or the answers to a question set — is delivered as
+ * a durable signal namespaced by run, so it can never cross-resolve another run.
  */
 declare class DurableAgentRunner implements AgentRunner {
     private readonly workflows;
-    constructor(workflows: WorkflowService);
+    private readonly runs;
+    private readonly store;
+    private readonly sink;
+    private readonly logger;
+    constructor(workflows: WorkflowService, runs: RunGateway, store: AgentStore, sink: TokenStreamSink);
     start(input: AgentRunInput): Promise<{
         runId: string;
     }>;
-    signal(runId: string, toolCallId: string, decision: Decision): Promise<void>;
-    cancel(_runId: string): Promise<void>;
+    signal(runId: string, toolCallId: string, reply: HumanReply): Promise<void>;
+    /**
+     * Stop a run, and settle what the durable runtime knows nothing about.
+     *
+     * `compensate: true` is the form that gives the BODY a chance: it moves the run to `cancelling`
+     * (which is what the workflow's own cancel observation reads) and then re-drives it, so a turn
+     * running in-process unwinds at its next safe point instead of finishing. It also guarantees the
+     * outcome for the turn that CANNOT observe anything — one parked on `waitForSignal`, suspended
+     * inside a position its journal already holds — because that re-drive re-suspends and the runtime
+     * settles the run `cancelled` regardless. The cascade to child runs comes with it.
+     *
+     * Neither of those settles the agent's own state, so this does: the run row gets its own terminal,
+     * and the subscriber gets a `cancelled` frame followed by a normal end. Both are keyed by runId
+     * alone, which is why they belong here rather than in the body — the body is the only place that
+     * knows which THREAD was streaming, so releasing that stays there (see `AgentRunWorkflow`).
+     *
+     * A tool already executing is not interrupted, here or anywhere: see `haltIfCancelled` in core.
+     */
+    cancel(runId: string): Promise<void>;
 }
 
 /**
@@ -174,10 +220,10 @@ declare function agentDurable(options: AgentModuleOptions): DynamicModule[];
 /**
  * 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.
+ * `AgentDurableModule` derives it from `AGENT_OPTIONS` (`durable === true && dispatchedSteps ===
+ * true`); `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;
 

package/dist/durable/index.d.ts

@@ -1,8 +1,55 @@
-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 AgentSurface, b as AgentModuleOptions } from '../agent-deps.factory-D7GdhqdK.js';
+import { AgentStore, AgentRunInput, AgentLoopResult, LlmStepEnvelope, BufferedModelTurnResult, ToolStepEnvelope, AgentRunner, TokenStreamSink, HumanReply } from '@dudousxd/nestjs-agent-core';
+import { RunGateway, WorkflowCtx } from '@dudousxd/nestjs-durable-core';
+import { A as AgentDepsFactory, a as AgentSurface, b as AgentModuleOptions } from '../agent-deps.factory-y2hvoQ6U.js';
 import { WorkflowService } from '@dudousxd/nestjs-durable';
 import { DynamicModule } from '@nestjs/common';
+import '@standard-schema/spec';
+
+/**
+ * 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` where the deployment asked for it (`AGENT_DISPATCHED_STEPS`, from
+ * `dispatchedSteps: true`) so the run isn't pinned to this pod while they execute; without that
+ * flag they are 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;
+    private readonly dispatchedSteps;
+    private readonly runs?;
+    constructor(factory: AgentDepsFactory, store: AgentStore, dispatchedSteps: boolean, runs?: RunGateway | undefined);
+    /**
+     * Has someone asked this run to stop? Read from the runtime's own run status, which is where
+     * `DurableAgentRunner.cancel` puts it — `cancelling` while a compensating cancel is in flight,
+     * `cancelled` once it has settled.
+     *
+     * Costs a run read at each of the loop's observation points (two per step). That is a row the
+     * control plane already has, against a turn that is otherwise making model calls, and it buys the
+     * property that matters: the answer comes from a place BOTH the canceller and every pod that might
+     * replay this run can see.
+     *
+     * Failing to ask is not a cancel. A tenant with no gateway wired, or an operator briefly
+     * unreachable, answers "no" and the run carries on — the alternative is failing healthy runs
+     * because a status read timed out. The loop journals that answer like any other, so two processes
+     * can never disagree about what was seen here.
+     */
+    private isCancelled;
+    /**
+     * Settle the delegation a DETACHED run was started for, when that run ends without an answer.
+     *
+     * The loop delivers its own success (`deliver:detached`) but cannot catch its own crash, and the
+     * runtime settles the run row without knowing anything delegated it. Left alone, the card in the
+     * calling conversation says "started" for ever — the one state a reader can neither wait on nor
+     * act on. A no-op for every other run: only a detached one carries a delivery address.
+     */
+    private settleDetachedParent;
+    run(ctx: WorkflowCtx, input: AgentRunInput): Promise<AgentLoopResult>;
+}
 
 /**
  * Serializable input for the dispatched `llm` step: a {@link LlmStepEnvelope} plus the sink routing
@@ -39,8 +86,8 @@ interface DispatchedToolInput extends ToolStepEnvelope {
 }
 /**
  * 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
+ * `AgentRunSteps.tool`) under `dispatchedSteps: true`; omitting that flag 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.
@@ -54,7 +101,7 @@ declare class AgentRunSteps {
      * 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>;
+    llm(input: DispatchedLlmInput): Promise<BufferedModelTurnResult>;
     /**
      * 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
@@ -68,42 +115,41 @@ declare class AgentRunSteps {
     tool(input: DispatchedToolInput): 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;
-    private readonly steps;
-    private readonly dispatchedSteps;
-    constructor(factory: AgentDepsFactory, store: AgentStore, steps: AgentRunSteps | undefined, dispatchedSteps: boolean);
-    run(ctx: WorkflowCtx, input: AgentRunInput): Promise<{
-        text: string;
-    }>;
-}
-
 /**
  * Runs the agent turn as a `@dudousxd/nestjs-durable` workflow. `start` creates the run and returns
- * its id immediately; a worker runs the body and streams tokens to the sink. HITL approval is
- * delivered as a durable signal namespaced by run, so it can never cross-resolve another run.
+ * its id immediately; a worker runs the body and streams tokens to the sink. Everything a human
+ * sends back into a parked run — a HITL approval, or the answers to a question set — is delivered as
+ * a durable signal namespaced by run, so it can never cross-resolve another run.
  */
 declare class DurableAgentRunner implements AgentRunner {
     private readonly workflows;
-    constructor(workflows: WorkflowService);
+    private readonly runs;
+    private readonly store;
+    private readonly sink;
+    private readonly logger;
+    constructor(workflows: WorkflowService, runs: RunGateway, store: AgentStore, sink: TokenStreamSink);
     start(input: AgentRunInput): Promise<{
         runId: string;
     }>;
-    signal(runId: string, toolCallId: string, decision: Decision): Promise<void>;
-    cancel(_runId: string): Promise<void>;
+    signal(runId: string, toolCallId: string, reply: HumanReply): Promise<void>;
+    /**
+     * Stop a run, and settle what the durable runtime knows nothing about.
+     *
+     * `compensate: true` is the form that gives the BODY a chance: it moves the run to `cancelling`
+     * (which is what the workflow's own cancel observation reads) and then re-drives it, so a turn
+     * running in-process unwinds at its next safe point instead of finishing. It also guarantees the
+     * outcome for the turn that CANNOT observe anything — one parked on `waitForSignal`, suspended
+     * inside a position its journal already holds — because that re-drive re-suspends and the runtime
+     * settles the run `cancelled` regardless. The cascade to child runs comes with it.
+     *
+     * Neither of those settles the agent's own state, so this does: the run row gets its own terminal,
+     * and the subscriber gets a `cancelled` frame followed by a normal end. Both are keyed by runId
+     * alone, which is why they belong here rather than in the body — the body is the only place that
+     * knows which THREAD was streaming, so releasing that stays there (see `AgentRunWorkflow`).
+     *
+     * A tool already executing is not interrupted, here or anywhere: see `haltIfCancelled` in core.
+     */
+    cancel(runId: string): Promise<void>;
 }
 
 /**
@@ -174,10 +220,10 @@ declare function agentDurable(options: AgentModuleOptions): DynamicModule[];
 /**
  * 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.
+ * `AgentDurableModule` derives it from `AGENT_OPTIONS` (`durable === true && dispatchedSteps ===
+ * true`); `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;