@nestjs/ai 0.0.0-stage → 0.0.1

package/dist/workflows/ai-agents.service.d.ts

@@ -0,0 +1,83 @@
+import { ModuleRef } from '@nestjs/core';
+import { WorkflowClient, WorkflowSignal, type WorkflowContext } from '@nestjs/workflows';
+import type { ModelMessage } from 'ai';
+import type { AiStep } from '../interfaces/ai-result.interface.js';
+import type { AiUsage } from '../interfaces/ai-usage.interface.js';
+import type { AiAgentRunOptions, AiAgentRunResult, AiPendingApproval, AiToolApproval } from './ai-agent.interfaces.js';
+/** The signal a tool call that waits for approval takes, keyed by the call (`AiPendingApproval.key`). */
+export declare const TOOL_APPROVAL: WorkflowSignal<AiToolApproval>;
+/** A run's options, resolved once and stored with it: tools as names. Internal. */
+export interface AgentSettings extends Omit<AiAgentRunOptions, 'tools' | 'prompt' | 'messages'> {
+    tools: string[];
+    approve: string[];
+    maxSteps: number;
+    stepsPerInstance: number;
+}
+/** Where a run is: what each instance replays to, and what a child instance starts from. Internal. */
+export interface AgentState {
+    /** The instance `run()` was called in: approval keys name it. */
+    runId: string;
+    index: number;
+    messages: ModelMessage[];
+    responseMessages: ModelMessage[];
+    steps: AiStep[];
+    usage: AiUsage;
+    cost?: number;
+}
+/**
+ * The agent loop as a durable workflow: inside a `@Workflow()`'s `run()`, each model call is a step and each tool
+ * call (an agent function's) another, so that a restart resumes where the run was, without calling a model or an agent
+ * function again for what is journaled. Calls of the functions named in `approve` wait for a person
+ * (`waitForSignal()`), for days if need be. After `stepsPerInstance` model calls the run goes on in a child workflow.
+ *
+ * ```ts
+ * @Workflow('refund-request')
+ * export class RefundRequest {
+ *   constructor(private readonly agents: AiAgents) {}
+ *
+ *   run(ctx: WorkflowContext, { email, customerId }: RefundInput) {
+ *     return this.agents.run(ctx, {
+ *       prompt: email,
+ *       tools: ['find-order', 'refund'],
+ *       approve: ['refund'],
+ *       caller: { user: { id: customerId } },
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare class AiAgents {
+    private readonly moduleRef;
+    private readonly client;
+    constructor(moduleRef: ModuleRef, client: WorkflowClient);
+    /** Runs the agent loop in the workflow `ctx` is the context of; resolves with its result. */
+    run(ctx: WorkflowContext, options: AiAgentRunOptions): Promise<AiAgentRunResult>;
+    /** Approves a tool call waiting for it; `key` is `AiPendingApproval.key`. The first answer for a call counts. */
+    approve(key: string, { by }?: {
+        by?: unknown;
+    }): Promise<void>;
+    /** Rejects a tool call waiting for approval: the agent function does not run, and the model is told `reason`. */
+    reject(key: string, { reason, by }?: {
+        reason?: string;
+        by?: unknown;
+    }): Promise<void>;
+    /** The tool calls of run `runId` that wait for approval now, in it or in the child instances it goes on in. */
+    pendingApprovals(runId: string): Promise<AiPendingApproval[]>;
+    /** @internal Runs from `state` on: `run()`'s instance, and each child instance a run goes on in. */
+    resume(ctx: WorkflowContext, settings: AgentSettings, state: AgentState): Promise<AiAgentRunResult>;
+    /**
+     * The step's valid tool calls (`ai` answered the invalid ones), one durable step each, after their approval when
+     * they need one. An agent function's failure is a result the model reads, not the step's failure: the step is
+     * retried only after a crash, with the same `idempotencyKey` in the function's context.
+     */
+    private runTools;
+    private settings;
+    /** The module's `defaults`, which a run's `maxSteps` and `budget` fall back to, as a call's do. */
+    private defaults;
+    private answer;
+    private ai;
+    private tools;
+}
+/** The workflow a run goes on in after `stepsPerInstance` model calls (`AiAgentSegment`). */
+export declare const AGENT_WORKFLOW = "nestjs-ai.agent";
+export declare function approvalKey(runId: string, toolCallId: string): string;

package/dist/workflows/ai-agents.service.js

@@ -0,0 +1,277 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Injectable } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+import { NonRetryableStepError, WorkflowClient, WorkflowSignal } from '@nestjs/workflows';
+import { AI_MODULE_OPTIONS } from '../ai.constants.js';
+import { AiConfigurationError, AiToolError } from '../errors/ai.errors.js';
+import { assertWithinBudget } from '../runtime/agent-loop.js';
+import { AiService } from '../services/ai.service.js';
+import { AiTools } from '../tools/ai-tools.service.js';
+import { INTERNAL_ERROR_MESSAGE } from '../utils/errors.util.js';
+import { addCost, addUsage, ZERO_USAGE } from '../utils/usage.util.js';
+/** The signal a tool call that waits for approval takes, keyed by the call (`AiPendingApproval.key`). */
+export const TOOL_APPROVAL = new WorkflowSignal('nestjs-ai.tool-approval');
+const DEFAULT_MAX_STEPS = 25;
+const DEFAULT_STEPS_PER_INSTANCE = 10;
+/**
+ * The agent loop as a durable workflow: inside a `@Workflow()`'s `run()`, each model call is a step and each tool
+ * call (an agent function's) another, so that a restart resumes where the run was, without calling a model or an agent
+ * function again for what is journaled. Calls of the functions named in `approve` wait for a person
+ * (`waitForSignal()`), for days if need be. After `stepsPerInstance` model calls the run goes on in a child workflow.
+ *
+ * ```ts
+ * @Workflow('refund-request')
+ * export class RefundRequest {
+ *   constructor(private readonly agents: AiAgents) {}
+ *
+ *   run(ctx: WorkflowContext, { email, customerId }: RefundInput) {
+ *     return this.agents.run(ctx, {
+ *       prompt: email,
+ *       tools: ['find-order', 'refund'],
+ *       approve: ['refund'],
+ *       caller: { user: { id: customerId } },
+ *     });
+ *   }
+ * }
+ * ```
+ */
+let AiAgents = class AiAgents {
+    constructor(moduleRef, client) {
+        this.moduleRef = moduleRef;
+        this.client = client;
+    }
+    /** Runs the agent loop in the workflow `ctx` is the context of; resolves with its result. */
+    run(ctx, options) {
+        const settings = this.settings(options);
+        const messages = initialMessages(options);
+        return this.resume(ctx, settings, {
+            runId: ctx.workflowId,
+            index: 0,
+            messages,
+            responseMessages: [],
+            steps: [],
+            usage: ZERO_USAGE,
+        });
+    }
+    /** Approves a tool call waiting for it; `key` is `AiPendingApproval.key`. The first answer for a call counts. */
+    async approve(key, { by } = {}) {
+        await this.answer(key, { approved: true, ...(by !== undefined && { by }) });
+    }
+    /** Rejects a tool call waiting for approval: the agent function does not run, and the model is told `reason`. */
+    async reject(key, { reason, by } = {}) {
+        await this.answer(key, { approved: false, ...(reason !== undefined && { reason }), ...(by !== undefined && { by }) });
+    }
+    /** The tool calls of run `runId` that wait for approval now, in it or in the child instances it goes on in. */
+    async pendingApprovals(runId) {
+        const pending = [];
+        const visit = async (id) => {
+            const details = await this.client.getStatus(id, { children: true });
+            if (!details) {
+                return;
+            }
+            pending.push(...(details.customStatus?.pendingApprovals ?? []));
+            for (const child of details.children ?? []) {
+                if (child.status !== 'completed' && child.status !== 'failed' && child.status !== 'cancelled') {
+                    await visit(child.id);
+                }
+            }
+        };
+        await visit(runId);
+        return pending;
+    }
+    /** @internal Runs from `state` on: `run()`'s instance, and each child instance a run goes on in. */
+    async resume(ctx, settings, state) {
+        const last = state.index + settings.stepsPerInstance;
+        while (state.index < settings.maxSteps) {
+            if (state.index >= last) {
+                const result = await ctx.executeChild(AGENT_WORKFLOW, { settings, state }, { id: `${state.runId}:from-${state.index}` });
+                return result;
+            }
+            assertWithinBudget(settings, state.usage, state.cost);
+            const index = state.index;
+            const { outcome, attempts } = await ctx.step(`model-${index}`, (step) => this.ai()
+                .callModel(callOptions(settings), { index, messages: state.messages, signal: step.signal })
+                .catch((error) => {
+                // A mistake in the options fails the same way every time: not worth a durable retry.
+                throw error instanceof AiConfigurationError ? new NonRetryableStepError(error.message) : error;
+            }));
+            const step = outcome.step;
+            const results = await this.runTools(ctx, settings, state, index, step);
+            state.messages.push(...outcome.responseMessages);
+            state.responseMessages.push(...outcome.responseMessages);
+            if (results.length > 0) {
+                const message = toolMessage(results);
+                state.messages.push(message);
+                state.responseMessages.push(message);
+            }
+            state.steps.push({ ...step, toolResults: [...step.toolResults, ...results], attempts });
+            state.usage = addUsage(state.usage, step.usage);
+            state.cost = addCost(state.cost, step.cost);
+            state.index++;
+            if (step.finishReason !== 'tool-calls' || step.toolCalls.length === 0) {
+                break;
+            }
+        }
+        return resultOf(state);
+    }
+    /**
+     * The step's valid tool calls (`ai` answered the invalid ones), one durable step each, after their approval when
+     * they need one. An agent function's failure is a result the model reads, not the step's failure: the step is
+     * retried only after a crash, with the same `idempotencyKey` in the function's context.
+     */
+    async runTools(ctx, settings, state, index, step) {
+        const answered = new Set(step.toolResults.map((result) => result.toolCallId));
+        const calls = step.toolCalls.filter((call) => !answered.has(call.toolCallId));
+        // Every call of the step that needs approval is listed at once; they are answered in any order.
+        const waiting = calls
+            .filter((call) => settings.approve.includes(call.toolName))
+            .map((call) => ({
+            key: approvalKey(state.runId, call.toolCallId),
+            runId: state.runId,
+            toolCallId: call.toolCallId,
+            toolName: call.toolName,
+            input: call.input,
+        }));
+        if (waiting.length > 0) {
+            ctx.setStatus({ pendingApprovals: waiting });
+        }
+        const results = [];
+        for (const call of calls) {
+            const approval = waiting.find((pending) => pending.toolCallId === call.toolCallId);
+            if (approval) {
+                const decision = await ctx.waitForSignal(`approval-${index}-${call.toolCallId}`, TOOL_APPROVAL, {
+                    key: approval.key,
+                    ...(settings.approvalTimeout !== undefined && { timeout: settings.approvalTimeout }),
+                });
+                waiting.splice(waiting.indexOf(approval), 1);
+                ctx.setStatus(waiting.length > 0 ? { pendingApprovals: waiting } : null);
+                if (!decision?.approved) {
+                    const error = decision ? `The call was rejected${decision.reason ? `: ${decision.reason}` : ''}` : 'No one approved the call in time';
+                    results.push({ ...call, error });
+                    continue;
+                }
+            }
+            results.push((await ctx.step(`tool-${index}-${call.toolCallId}`, async (toolStep) => {
+                const tools = this.tools();
+                const entry = tools.tools.get(call.toolName);
+                if (!entry) {
+                    return { ...call, error: `There is no tool named "${call.toolName}"` };
+                }
+                try {
+                    const output = await tools.call(entry, call.input, settings.caller ?? {}, {
+                        toolCallId: call.toolCallId,
+                        messages: state.messages,
+                        abortSignal: toolStep.signal,
+                        idempotencyKey: toolStep.idempotencyKey,
+                    });
+                    return { ...call, output };
+                }
+                catch (error) {
+                    return { ...call, error: error instanceof AiToolError ? error.message : INTERNAL_ERROR_MESSAGE };
+                }
+            })));
+        }
+        return results;
+    }
+    settings(options) {
+        if (typeof options !== 'object' || options === null) {
+            throw new AiConfigurationError('AiAgents.run() takes options: { prompt } or { messages }, and the rest.');
+        }
+        const { tools, prompt: _prompt, messages: _messages, ...rest } = options;
+        const names = tools?.length ? this.tools().resolve(tools).map((entry) => entry.name) : [];
+        const approve = options.approve ?? [];
+        for (const name of approve) {
+            if (!names.includes(name)) {
+                throw new AiConfigurationError(`\`approve\` names "${name}", which is not one of the run's \`tools\`.`);
+            }
+        }
+        const defaults = this.defaults();
+        const budget = options.budget ?? defaults.budget;
+        return {
+            ...rest,
+            tools: names,
+            approve,
+            maxSteps: options.maxSteps ?? defaults.maxSteps ?? DEFAULT_MAX_STEPS,
+            stepsPerInstance: options.stepsPerInstance ?? DEFAULT_STEPS_PER_INSTANCE,
+            ...(budget && { budget }),
+        };
+    }
+    /** The module's `defaults`, which a run's `maxSteps` and `budget` fall back to, as a call's do. */
+    defaults() {
+        return this.moduleRef.get(AI_MODULE_OPTIONS, { strict: false }).defaults ?? {};
+    }
+    answer(key, decision) {
+        return this.client.signal(TOOL_APPROVAL, decision, { key, id: `${key}:answer` });
+    }
+    ai() {
+        return this.moduleRef.get(AiService, { strict: false });
+    }
+    tools() {
+        return this.moduleRef.get(AiTools, { strict: false });
+    }
+};
+AiAgents = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [ModuleRef,
+        WorkflowClient])
+], AiAgents);
+export { AiAgents };
+/** The workflow a run goes on in after `stepsPerInstance` model calls (`AiAgentSegment`). */
+export const AGENT_WORKFLOW = 'nestjs-ai.agent';
+export function approvalKey(runId, toolCallId) {
+    return `${runId}:${toolCallId}`;
+}
+function initialMessages(options) {
+    if (options.prompt !== undefined && options.messages !== undefined) {
+        throw new AiConfigurationError('Pass `prompt` or `messages`, not both.');
+    }
+    if (typeof options.prompt === 'string') {
+        return [{ role: 'user', content: options.prompt }];
+    }
+    if (Array.isArray(options.messages) && options.messages.length > 0) {
+        return [...options.messages];
+    }
+    throw new AiConfigurationError('Pass `prompt` (a string) or `messages` (a non-empty array of model messages).');
+}
+function callOptions(settings) {
+    const { approve: _approve, approvalTimeout: _timeout, stepsPerInstance: _steps, maxSteps: _max, budget: _budget, caller, tools, ...rest } = settings;
+    return { ...rest, tools, caller: { ...(caller?.user !== undefined && { user: caller.user }), ...(caller?.scopes && { scopes: caller.scopes }) } };
+}
+/** The results of tool calls as the tool message the model reads next. */
+function toolMessage(results) {
+    return {
+        role: 'tool',
+        content: results.map((result) => ({
+            type: 'tool-result',
+            toolCallId: result.toolCallId,
+            toolName: result.toolName,
+            output: result.error !== undefined
+                ? { type: 'error-text', value: result.error }
+                : typeof result.output === 'string'
+                    ? { type: 'text', value: result.output }
+                    : { type: 'json', value: (result.output ?? null) },
+        })),
+    };
+}
+function resultOf(state) {
+    const final = state.steps[state.steps.length - 1];
+    return {
+        text: final.text,
+        finishReason: final.finishReason,
+        steps: state.steps,
+        usage: state.usage,
+        ...(state.cost !== undefined && { cost: state.cost }),
+        toolCalls: state.steps.flatMap((step) => step.toolCalls),
+        toolResults: state.steps.flatMap((step) => step.toolResults),
+        responseMessages: state.responseMessages,
+        model: final.model,
+    };
+}

package/dist/workflows/ai-workflows.module.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Durable agent runs on `@nestjs/workflows`: import it next to `AiModule` and `WorkflowsModule`, and inject
+ * `AiAgents` into your `@Workflow()` classes.
+ */
+export declare class AiWorkflowsModule {
+}

package/dist/workflows/ai-workflows.module.js

@@ -0,0 +1,22 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from '@nestjs/common';
+import { AiAgentSegment } from './ai-agent.workflow.js';
+import { AiAgents } from './ai-agents.service.js';
+/**
+ * Durable agent runs on `@nestjs/workflows`: import it next to `AiModule` and `WorkflowsModule`, and inject
+ * `AiAgents` into your `@Workflow()` classes.
+ */
+let AiWorkflowsModule = class AiWorkflowsModule {
+};
+AiWorkflowsModule = __decorate([
+    Module({
+        providers: [AiAgents, AiAgentSegment],
+        exports: [AiAgents],
+    })
+], AiWorkflowsModule);
+export { AiWorkflowsModule };

package/dist/workflows/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `@nestjs/ai/workflows`: the agent loop as a durable workflow, on `@nestjs/workflows`.
+ */
+export { AiWorkflowsModule } from './ai-workflows.module.js';
+export { AiAgents, TOOL_APPROVAL } from './ai-agents.service.js';
+export type { AiAgentCaller, AiAgentRunOptions, AiAgentRunResult, AiPendingApproval, AiToolApproval, } from './ai-agent.interfaces.js';

package/dist/workflows/index.js

@@ -0,0 +1,5 @@
+/**
+ * `@nestjs/ai/workflows`: the agent loop as a durable workflow, on `@nestjs/workflows`.
+ */
+export { AiWorkflowsModule } from './ai-workflows.module.js';
+export { AiAgents, TOOL_APPROVAL } from './ai-agents.service.js';

package/package.json

@@ -1,6 +1,102 @@
 {
   "name": "@nestjs/ai",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Nest - modern, fast, powerful node.js web framework (@ai)",
+  "author": "Kamil Mysliwiec",
+  "license": "MIT",
+  "url": "https://github.com/nestjs/ai#readme",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
+    },
+    "./workflows": {
+      "types": "./dist/workflows/index.d.ts",
+      "import": "./dist/workflows/index.js",
+      "default": "./dist/workflows/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "format": "prettier --write \"**/*.ts\"",
+    "lint": "oxlint lib/",
+    "prepublish:npm": "npm run build",
+    "publish:npm": "npm publish --access public",
+    "prepublish:next": "npm run build",
+    "publish:next": "npm publish --access public --tag next",
+    "test:e2e": "vitest run",
+    "test:e2e:dev": "vitest",
+    "prerelease": "npm run build",
+    "release": "release-it",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@ai-sdk/anthropic": "4.0.96",
+    "@commitlint/cli": "21.2.4",
+    "@commitlint/config-angular": "21.2.4",
+    "@modelcontextprotocol/client": "2.4.0",
+    "@modelcontextprotocol/server": "2.4.0",
+    "@nestjs/authentication": "0.1.4",
+    "@nestjs/authorization": "0.1.2",
+    "@nestjs/common": "12.3.3",
+    "@nestjs/core": "12.3.3",
+    "@nestjs/mcp": "^0.0.3",
+    "@nestjs/platform-express": "12.3.3",
+    "@nestjs/platform-fastify": "12.3.3",
+    "@nestjs/platform-node": "12.3.3",
+    "@nestjs/resilience": "0.0.3",
+    "@nestjs/testing": "12.3.3",
+    "@nestjs/workflows": "0.0.4",
+    "@types/node": "24.19.2",
+    "ai": "7.0.162",
+    "husky": "9.1.7",
+    "lint-staged": "17.6.0",
+    "oxlint": "1.91.0",
+    "prettier": "3.9.10",
+    "reflect-metadata": "0.2.2",
+    "release-it": "21.1.2",
+    "rxjs": "7.8.2",
+    "typescript": "7.0.2",
+    "vite": "8.3.5",
+    "vitest": "5.1.0",
+    "zod": "4.6.7"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^12.0.0",
+    "@nestjs/core": "^12.0.0",
+    "@nestjs/resilience": ">=0.0.3 <1",
+    "@nestjs/testing": "^12.0.0",
+    "@nestjs/workflows": ">=0.0.4 <1",
+    "ai": "^7.0.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0",
+    "rxjs": "^7.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/testing": {
+      "optional": true
+    },
+    "@nestjs/workflows": {
+      "optional": true
+    }
+  },
+  "lint-staged": {
+    "**/*.{ts,json}": []
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nestjs/ai"
+  }
+}