@dudousxd/nestjs-agent 1.39.1 → 2.0.0

package/dist/workflows/index.d.ts

@@ -0,0 +1,158 @@
+import { HumanReply, AgentRunner, AgentStore, TokenStreamSink, AgentRunInput, AgentRunStartOptions, AgentLoopResult } from '@dudousxd/nestjs-agent-core';
+import { WorkflowSignal, WorkflowClient, WorkflowInstanceDetails, WorkflowsModuleOptions, WorkflowContext, WorkflowRunner } from '@nestjs/workflows';
+import { C as ChatQueueService, A as AgentDepsFactory, b as AgentModuleOptions } from '../chat-queue.service-BjPCw4Pf.js';
+import '@dudousxd/nestjs-agent-core/genui';
+import '@standard-schema/spec';
+import '@nestjs/common';
+import '@nestjs/ai';
+import '../genui/index.js';
+
+/**
+ * Agent turns on NestJS's `@nestjs/workflows`. Import it next to `WorkflowsModule.forRoot()` and
+ * `AgentModule.forRoot({ durable: true })`:
+ *
+ * ```ts
+ * imports: [
+ *   WorkflowsModule.forRoot(),
+ *   AgentModule.forRoot({ model, store, durable: true }),
+ *   AgentWorkflowsModule,
+ * ]
+ * ```
+ *
+ * It registers the `aviary.agent.run` workflow (and the one a long turn goes on in) and provides the
+ * runner `AgentModule` binds `AGENT_RUNNER` to. Every process registers them, so any process can
+ * start a turn; which processes RUN turns is `WorkflowsModule`'s `worker` option: on an API pod
+ * that must not, `WorkflowsModule.forRoot({ worker: false })`.
+ */
+declare class AgentWorkflowsModule {
+}
+
+/**
+ * A person's reply to a call a turn is parked on: a `Decision` on an action tool, or the answers to
+ * a question set. Keyed by {@link replyKey}, so a reply reaches only the call it answers.
+ */
+declare const AGENT_REPLY: WorkflowSignal<HumanReply>;
+/** The key a reply to call `toolCallId` of run `runId` is sent and awaited under. */
+declare function replyKey(runId: string, toolCallId: string): string;
+/** A call waiting for a person, as `WorkflowsAgentRunner.pendingReplies()` lists it. */
+interface PendingReply {
+    /** What the reply is signalled under ({@link replyKey}). */
+    key: string;
+    /** The turn's run id. */
+    runId: string;
+    toolCallId: string;
+    /** The tool, or `'ask'` / `'intake'` for a question set. */
+    toolName: string;
+    kind: 'approval' | 'elicitation';
+}
+
+/**
+ * Runs agent turns on NestJS's `@nestjs/workflows` (`durable: true`). `start` creates the
+ * `aviary.agent.run` instance under the run id and returns; whichever worker claims it runs the turn
+ * and streams to the sink. A person's reply to a parked call is the `AGENT_REPLY` signal keyed by
+ * `<runId>:<toolCallId>`; a Stop is `WorkflowClient.cancel`.
+ */
+declare class WorkflowsAgentRunner implements AgentRunner {
+    private readonly store;
+    private readonly sink;
+    private readonly queue?;
+    private readonly logger;
+    private readonly client;
+    constructor(store: AgentStore, sink: TokenStreamSink, client?: WorkflowClient, queue?: ChatQueueService | undefined);
+    start(input: AgentRunInput, options?: AgentRunStartOptions): Promise<{
+        runId: string;
+    }>;
+    /** Not ended as far as the engine knows. An unknown run counts as running, and so does one it can't be asked about. */
+    isRunActive(runId: string): Promise<boolean>;
+    signal(runId: string, toolCallId: string, reply: HumanReply): Promise<void>;
+    /** The engine's view of a run: status, custom status, waits, children. `null` for an unknown id. */
+    getStatus(runId: string): Promise<WorkflowInstanceDetails | null>;
+    /**
+     * The calls of run `runId` waiting for a person now, in the instance it started in, in the
+     * instances it went on in, and in the sub-agent runs it delegated to.
+     */
+    pendingReplies(runId: string): Promise<PendingReply[]>;
+    /**
+     * Stop a run: the engine stops the turn at its next `ctx` call (a parked turn at once), and
+     * cancels the sub-agent runs it is waiting on. What the engine knows nothing about is settled
+     * here, as on the `aviary` engine: the delegation a detached run answers, the thread's queue and
+     * live stream, the subscriber's stream (a `cancelled` frame and a normal end), the run's row.
+     */
+    cancel(runId: string): Promise<void>;
+}
+
+/** An error as JSON: its name, its message and its own JSON-safe fields (a `code`, a `status`). */
+interface SerializedTurnError {
+    name: string;
+    message: string;
+    props?: Record<string, unknown>;
+}
+/** What one journaled operation came to: its value, or the error it threw. */
+type TurnOutcome = {
+    v?: unknown;
+} | {
+    e: SerializedTurnError;
+};
+
+/** The workflow a turn runs as. */
+declare const AGENT_RUN_WORKFLOW = "aviary.agent.run";
+/** The workflow a turn goes on in after `stepsPerInstance` model calls. */
+declare const AGENT_RUN_SEGMENT_WORKFLOW = "aviary.agent.run.segment";
+/** What a segment instance starts from: the turn, its run id, and what the instances before it settled. */
+interface AgentRunSegmentInput {
+    input: AgentRunInput;
+    /** The turn's run id: the id of the instance it started in. */
+    runId: string;
+    /** 1 for the first child instance. */
+    segment: number;
+    carried: Record<string, TurnOutcome>;
+}
+/**
+ * The agent turn on `@nestjs/workflows`: what `AgentRunFlow` (`aviary.agent.run`) and
+ * `AgentRunSegmentFlow` run. Each model call and each tool call is a `ctx.step`, the loop's
+ * checkpoints are `ctx.step`s too, a human's reply is a `ctx.waitForSignal(AGENT_REPLY, { key })`,
+ * a delegation is `ctx.executeChild`, a detached delegation and the thread's next queued message are
+ * `ctx.startChild(..., { parentClose: 'abandon' })`. A cancel is the engine's: `WorkflowClient.cancel`
+ * stops the turn at its next `ctx` call, and `WorkflowsAgentRunner.cancel` settles the agent's own
+ * state, as it does on the `aviary` engine.
+ */
+declare class AgentTurnExecutor {
+    private readonly factory;
+    private readonly store;
+    private readonly queue?;
+    private readonly client?;
+    private readonly workflowsOptions?;
+    private readonly logger;
+    private readonly stepsPerInstance;
+    constructor(factory: AgentDepsFactory, store: AgentStore, options?: AgentModuleOptions, queue?: ChatQueueService | undefined, client?: WorkflowClient | undefined, workflowsOptions?: WorkflowsModuleOptions | undefined);
+    /** A turn from its first instance. */
+    run(ctx: WorkflowContext, input: AgentRunInput): Promise<AgentLoopResult>;
+    execute(ctx: WorkflowContext, segment: AgentRunSegmentInput): Promise<AgentLoopResult>;
+    /** The turn goes on in a child instance, from what this one (and those before it) settled. */
+    private continueInSegment;
+    /**
+     * Hand the thread on past this settling turn, as the `aviary` engine does: the decision is one
+     * checkpoint, and the next message starts as an abandoned child under its own id, so the turn
+     * ending doesn't cancel it.
+     */
+    private advanceQueue;
+    private isCancelled;
+    private settleDetachedParent;
+    /** A `ctx` call whose interrupt carries core's control-flow marker. */
+    private ctxCall;
+}
+
+/** An agent turn, as a `@nestjs/workflows` workflow (`aviary.agent.run`). The run id is its instance id. */
+declare class AgentRunFlow implements WorkflowRunner<AgentRunInput, AgentLoopResult> {
+    private readonly turns;
+    constructor(turns: AgentTurnExecutor);
+    run(ctx: WorkflowContext, input: AgentRunInput): Promise<AgentLoopResult>;
+}
+/** A turn going on in a child instance after `stepsPerInstance` model calls. Internal. */
+declare class AgentRunSegmentFlow implements WorkflowRunner<AgentRunSegmentInput, AgentLoopResult> {
+    private readonly turns;
+    constructor(turns: AgentTurnExecutor);
+    run(ctx: WorkflowContext, segment: AgentRunSegmentInput): Promise<AgentLoopResult>;
+}
+
+export { AGENT_REPLY, AGENT_RUN_SEGMENT_WORKFLOW, AGENT_RUN_WORKFLOW, AgentRunFlow, AgentRunSegmentFlow, type AgentRunSegmentInput, AgentWorkflowsModule, type PendingReply, WorkflowsAgentRunner, replyKey };