@dudousxd/nestjs-agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davide Carvalho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# `@dudousxd/nestjs-agent`
+
+> 🪺 Part of the [Aviary](https://davidecarvalho.github.io/aviary) — plug-n-play, fully-configurable NestJS libraries.
+
+A **governed, durable-backed AI agent** for NestJS: chat + tool-calling + role/persona governance +
+token quota + cost tracking + human-in-the-loop approval + resumable streaming + multi-agent
+delegation. The agent turn runs in-process or as a **durable workflow** (replay-safe, resumable, HITL
+via signals).
+
+This is the NestJS module — it re-exports the entire `@dudousxd/nestjs-agent-core` surface, so you
+import tools, types, and the module from one place.
+
+## Install
+
+```bash
+pnpm add @dudousxd/nestjs-agent @dudousxd/nestjs-agent-core
+```
+
+## Use
+
+```ts
+import { AgentModule, AiTool, HeaderActorResolver, type ToolHandler } from '@dudousxd/nestjs-agent';
+import { z } from 'zod';
+
+@AiTool({ name: 'getWeather', kind: 'read', description: 'Current weather.', input: z.object({ city: z.string() }) })
+export class GetWeatherTool implements ToolHandler<{ city: string }> {
+  async execute(input: { city: string }) { return { tempC: 21 }; }
+}
+
+@Module({
+  imports: [AgentModule.forRoot({
+    model, store, actorResolver: new HeaderActorResolver(),
+    defaultAgent: { systemPrompt: '…', modelId: 'claude-sonnet-4-6' },
+  })],
+  providers: [GetWeatherTool],
+})
+export class AppModule {}
+```
+
+The module mounts SSE + REST endpoints under `/agent` (`POST /agent/chat`, tool-call approve/reject,
+threads, quota). Add `durable: true` + `AgentDurableModule` for the durable runner;
+`AgentModule.forFeature([…])` for multi-agent orchestration.
+
+See the [monorepo README](https://github.com/DavideCarvalho/aviary) for the full guide (durability,
+multi-agent, authz, governed SQL, the React frontend, diagnostics).
+
+## License
+
+MIT © Davide Carvalho

package/dist/agent-deps.factory-D9BHJJqm.d.cts

@@ -0,0 +1,173 @@
+import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, QuotaStore, TokenStreamSink, PromptBuilder, Persona, Retriever, ToolSpec, ToolHandler, ActorResolver, AgentDefinition, AgentRegistry } from '@dudousxd/nestjs-agent-core';
+import { Provider, FactoryProvider, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
+
+/** Everything `runAgentLoop` needs, minus the per-run `day` the runner stamps. */
+interface AgentDeps {
+    model: ModelProvider;
+    store: AgentStore;
+    registry: ToolRegistry;
+    rolesPolicy: RolesPolicy;
+    quota?: QuotaStore;
+    sink: TokenStreamSink;
+    /** Fallback accounting label; the provider's turn result overrides it when set. */
+    modelId?: string;
+    systemPrompt: string | PromptBuilder;
+    maxSteps: number;
+    personas: Map<string, Persona>;
+    defaultPersona: string;
+    /** Agent-level tool allow-list (intersected with the persona's). Undefined → all tools. */
+    toolAllowList?: string[];
+    /** Per-tool execution timeout in ms (from module options). Undefined → no timeout. */
+    toolTimeoutMs?: number;
+    /** How many follow-up suggestions to generate after the final turn. Undefined/0 → off. */
+    followUpsCount?: number;
+    /** Inject-mode retriever (from `forRoot({ retrieval })`). Undefined → no prompt augmentation. */
+    retriever?: Retriever;
+    /** Passages inject-mode retrieval requests. Undefined → loop default (5). */
+    retrievalTopK?: number;
+}
+declare function utcDay(date?: Date): string;
+
+/**
+ * Brand stamped onto a functional-tool provider instance so `AiToolDiscoveryService` picks it up
+ * when it walks every provider at boot — the declarative alternative to a manual `registry.register`.
+ */
+declare const AGENT_TOOL_BRAND: unique symbol;
+/** A tool expressed as data + handler (e.g. from `createExecuteSqlTool`), not an `@AiTool` class. */
+interface FunctionalTool {
+    spec: ToolSpec;
+    handler: ToolHandler;
+}
+/**
+ * Registers a functional tool declaratively — drop the returned provider in a module's `providers`
+ * and `AiToolDiscoveryService` auto-registers it at boot. Each call uses a fresh, unique provide
+ * token so the same tool can be provided many times without collisions.
+ *
+ * Two forms: a static tool (`useValue`) or a factory with `inject` for DI-resolved dependencies
+ * (`useFactory`). Either way the resolved instance is branded with {@link AGENT_TOOL_BRAND}.
+ */
+declare function provideAgentTool(tool: FunctionalTool): Provider;
+declare function provideAgentTool(factory: (...deps: never[]) => FunctionalTool, inject?: FactoryProvider['inject']): Provider;
+
+/**
+ * The implicit default agent, configured inline on `forRoot`. It is an {@link AgentDefinition}
+ * with `name` optional (defaults to `'default'`) — everything agent-shaped is an AgentDefinition,
+ * whether it's this default or one registered via `forFeature`. Omit it entirely for a bare
+ * assistant with no base prompt, personas, or tool allow-list.
+ */
+type DefaultAgentOptions = Omit<AgentDefinition, 'name'> & {
+    name?: string;
+};
+interface AgentModuleOptions {
+    /** The LLM provider (e.g. a Vercel AI SDK wrapper). Required. */
+    model: ModelProvider;
+    /**
+     * Persistence adapter. Optional — omit it and import a store module (e.g.
+     * `MikroOrmAgentStoreModule.forFeature()`) that binds `AGENT_STORE` globally instead. When
+     * provided here it takes precedence within this module's scope.
+     */
+    store?: AgentStore;
+    /** Live token transport. Defaults to a single-process in-memory sink. */
+    sink?: TokenStreamSink;
+    /**
+     * A {@link QuotaStore} for the daily token budget. Optional — omit (and omit `quotaLimitTokens`)
+     * to disable quotas. Provide this to plug a custom budget; for the common case use the simpler
+     * `quotaLimitTokens` instead, which binds the built-in ledger-backed store.
+     */
+    quota?: QuotaStore;
+    /**
+     * Daily per-actor token budget, enforced against the persisted usage ledger by the built-in
+     * `LedgerQuotaStore`. A convenience over wiring a {@link QuotaStore} by hand — set this and quotas
+     * turn on with no extra store. Ignored when an explicit `quota` is provided. Omit to disable.
+     */
+    quotaLimitTokens?: number;
+    /** Tool authorization gate. Defaults to role-in-`defaultRoles`. */
+    rolesPolicy?: RolesPolicy;
+    /** Default roles a tool requires when its `roles` is omitted. Defaults to `['ADMIN']`. */
+    defaultRoles?: string[];
+    /**
+     * Resolves the acting actor for each request (the identity seam). Required — the agent NEVER
+     * fabricates a caller, so this is a compile-time obligation, not an optional with a throwing
+     * placeholder. Read your authenticated principal here (session / JWT / `nestjs-context`), or use
+     * the opt-in `HeaderActorResolver` for demos and header-trusting gateways.
+     */
+    actorResolver: ActorResolver;
+    /** Route prefix the controllers mount under. Defaults to `'agent'` (→ `/agent/chat`, …). */
+    path?: string;
+    /**
+     * Run each turn as a durable workflow instead of in-process. Requires importing
+     * `AgentDurableModule` from `@dudousxd/nestjs-agent/durable` and a configured `DurableModule`.
+     */
+    durable?: boolean;
+    /**
+     * Static functional tools (`{ spec, handler }`, e.g. from `createExecuteSqlTool`) to register at
+     * boot. For tools that need DI-resolved dependencies, use `provideAgentTool(factory, inject)` in a
+     * module's `providers` instead.
+     */
+    tools?: FunctionalTool[];
+    /**
+     * Per-tool execution timeout in ms. A tool that runs longer is aborted and recorded as failed (the
+     * model receives the timeout as its result and can adapt) instead of hanging the turn. Omit → none.
+     */
+    toolTimeoutMs?: number;
+    /**
+     * Suggest follow-up questions after the final turn. `true` → 3 suggestions; `{ count }` → that many.
+     * Costs one extra model call per turn (recorded as `follow_ups` usage), stored on the assistant
+     * message's `followUps`. Omit/`false` → disabled.
+     */
+    followUps?: boolean | {
+        count: number;
+    };
+    /**
+     * Always-on ("inject") RAG: before each turn, retrieve passages for the user message and augment
+     * the system prompt with them. For agentic retrieval (the model decides when to search) DON'T set
+     * this — instead expose the tool: `provideAgentTool(createRetrievalTool(retriever))`. Omit → off.
+     */
+    retrieval?: {
+        mode: 'inject';
+        retriever: Retriever;
+        topK?: number;
+    };
+    /**
+     * The implicit single agent's config (base prompt, personas, tool allow-list, model/step
+     * config). Omit for a bare assistant. Additional named agents are added via `forFeature`.
+     */
+    defaultAgent?: DefaultAgentOptions;
+}
+interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+    inject?: Array<InjectionToken | OptionalFactoryDependency>;
+    useFactory: (...args: never[]) => AgentModuleOptions | Promise<AgentModuleOptions>;
+    /**
+     * Route prefix the controllers mount under (default `'agent'`). Static routing metadata, so it
+     * lives here rather than in the async factory result (which resolves too late to mount routes).
+     */
+    path?: string;
+    /**
+     * Run each turn as a durable workflow. Static wiring metadata (which `AGENT_RUNNER` to bind), so
+     * it lives here rather than in the async factory result — the factory resolves too late to swap
+     * the runner. Requires importing `AgentDurableModule` and a configured `DurableModule`.
+     */
+    durable?: boolean;
+}
+
+/** The synthesized `agent`-kind tool name an orchestrator uses to delegate to `target`. */
+declare function delegateToolName(target: string): string;
+/** Builds the per-agent loop deps. The single-agent case is just the `default` definition. */
+declare class AgentDepsFactory {
+    private readonly options;
+    private readonly model;
+    private readonly store;
+    private readonly sink;
+    private readonly rolesPolicy;
+    private readonly registry;
+    private readonly agents;
+    private readonly quota;
+    constructor(options: AgentModuleOptions, model: ModelProvider, store: AgentStore, sink: TokenStreamSink, rolesPolicy: RolesPolicy, registry: ToolRegistry, agents: AgentRegistry, quota: QuotaStore | undefined);
+    defaultAgentName(): string;
+    private effectiveTools;
+    forAgent(agentName?: string): AgentDeps;
+    /** Normalize the `followUps` option (`true` → 3, `{ count }` → count) to a number, or undefined. */
+    private followUpsCount;
+}
+
+export { AgentDepsFactory as A, type DefaultAgentOptions as D, type FunctionalTool as F, type AgentModuleOptions as a, type AgentModuleAsyncOptions as b, AGENT_TOOL_BRAND as c, type AgentDeps as d, delegateToolName as e, provideAgentTool as p, utcDay as u };

package/dist/agent-deps.factory-D9BHJJqm.d.ts

@@ -0,0 +1,173 @@
+import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, QuotaStore, TokenStreamSink, PromptBuilder, Persona, Retriever, ToolSpec, ToolHandler, ActorResolver, AgentDefinition, AgentRegistry } from '@dudousxd/nestjs-agent-core';
+import { Provider, FactoryProvider, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
+
+/** Everything `runAgentLoop` needs, minus the per-run `day` the runner stamps. */
+interface AgentDeps {
+    model: ModelProvider;
+    store: AgentStore;
+    registry: ToolRegistry;
+    rolesPolicy: RolesPolicy;
+    quota?: QuotaStore;
+    sink: TokenStreamSink;
+    /** Fallback accounting label; the provider's turn result overrides it when set. */
+    modelId?: string;
+    systemPrompt: string | PromptBuilder;
+    maxSteps: number;
+    personas: Map<string, Persona>;
+    defaultPersona: string;
+    /** Agent-level tool allow-list (intersected with the persona's). Undefined → all tools. */
+    toolAllowList?: string[];
+    /** Per-tool execution timeout in ms (from module options). Undefined → no timeout. */
+    toolTimeoutMs?: number;
+    /** How many follow-up suggestions to generate after the final turn. Undefined/0 → off. */
+    followUpsCount?: number;
+    /** Inject-mode retriever (from `forRoot({ retrieval })`). Undefined → no prompt augmentation. */
+    retriever?: Retriever;
+    /** Passages inject-mode retrieval requests. Undefined → loop default (5). */
+    retrievalTopK?: number;
+}
+declare function utcDay(date?: Date): string;
+
+/**
+ * Brand stamped onto a functional-tool provider instance so `AiToolDiscoveryService` picks it up
+ * when it walks every provider at boot — the declarative alternative to a manual `registry.register`.
+ */
+declare const AGENT_TOOL_BRAND: unique symbol;
+/** A tool expressed as data + handler (e.g. from `createExecuteSqlTool`), not an `@AiTool` class. */
+interface FunctionalTool {
+    spec: ToolSpec;
+    handler: ToolHandler;
+}
+/**
+ * Registers a functional tool declaratively — drop the returned provider in a module's `providers`
+ * and `AiToolDiscoveryService` auto-registers it at boot. Each call uses a fresh, unique provide
+ * token so the same tool can be provided many times without collisions.
+ *
+ * Two forms: a static tool (`useValue`) or a factory with `inject` for DI-resolved dependencies
+ * (`useFactory`). Either way the resolved instance is branded with {@link AGENT_TOOL_BRAND}.
+ */
+declare function provideAgentTool(tool: FunctionalTool): Provider;
+declare function provideAgentTool(factory: (...deps: never[]) => FunctionalTool, inject?: FactoryProvider['inject']): Provider;
+
+/**
+ * The implicit default agent, configured inline on `forRoot`. It is an {@link AgentDefinition}
+ * with `name` optional (defaults to `'default'`) — everything agent-shaped is an AgentDefinition,
+ * whether it's this default or one registered via `forFeature`. Omit it entirely for a bare
+ * assistant with no base prompt, personas, or tool allow-list.
+ */
+type DefaultAgentOptions = Omit<AgentDefinition, 'name'> & {
+    name?: string;
+};
+interface AgentModuleOptions {
+    /** The LLM provider (e.g. a Vercel AI SDK wrapper). Required. */
+    model: ModelProvider;
+    /**
+     * Persistence adapter. Optional — omit it and import a store module (e.g.
+     * `MikroOrmAgentStoreModule.forFeature()`) that binds `AGENT_STORE` globally instead. When
+     * provided here it takes precedence within this module's scope.
+     */
+    store?: AgentStore;
+    /** Live token transport. Defaults to a single-process in-memory sink. */
+    sink?: TokenStreamSink;
+    /**
+     * A {@link QuotaStore} for the daily token budget. Optional — omit (and omit `quotaLimitTokens`)
+     * to disable quotas. Provide this to plug a custom budget; for the common case use the simpler
+     * `quotaLimitTokens` instead, which binds the built-in ledger-backed store.
+     */
+    quota?: QuotaStore;
+    /**
+     * Daily per-actor token budget, enforced against the persisted usage ledger by the built-in
+     * `LedgerQuotaStore`. A convenience over wiring a {@link QuotaStore} by hand — set this and quotas
+     * turn on with no extra store. Ignored when an explicit `quota` is provided. Omit to disable.
+     */
+    quotaLimitTokens?: number;
+    /** Tool authorization gate. Defaults to role-in-`defaultRoles`. */
+    rolesPolicy?: RolesPolicy;
+    /** Default roles a tool requires when its `roles` is omitted. Defaults to `['ADMIN']`. */
+    defaultRoles?: string[];
+    /**
+     * Resolves the acting actor for each request (the identity seam). Required — the agent NEVER
+     * fabricates a caller, so this is a compile-time obligation, not an optional with a throwing
+     * placeholder. Read your authenticated principal here (session / JWT / `nestjs-context`), or use
+     * the opt-in `HeaderActorResolver` for demos and header-trusting gateways.
+     */
+    actorResolver: ActorResolver;
+    /** Route prefix the controllers mount under. Defaults to `'agent'` (→ `/agent/chat`, …). */
+    path?: string;
+    /**
+     * Run each turn as a durable workflow instead of in-process. Requires importing
+     * `AgentDurableModule` from `@dudousxd/nestjs-agent/durable` and a configured `DurableModule`.
+     */
+    durable?: boolean;
+    /**
+     * Static functional tools (`{ spec, handler }`, e.g. from `createExecuteSqlTool`) to register at
+     * boot. For tools that need DI-resolved dependencies, use `provideAgentTool(factory, inject)` in a
+     * module's `providers` instead.
+     */
+    tools?: FunctionalTool[];
+    /**
+     * Per-tool execution timeout in ms. A tool that runs longer is aborted and recorded as failed (the
+     * model receives the timeout as its result and can adapt) instead of hanging the turn. Omit → none.
+     */
+    toolTimeoutMs?: number;
+    /**
+     * Suggest follow-up questions after the final turn. `true` → 3 suggestions; `{ count }` → that many.
+     * Costs one extra model call per turn (recorded as `follow_ups` usage), stored on the assistant
+     * message's `followUps`. Omit/`false` → disabled.
+     */
+    followUps?: boolean | {
+        count: number;
+    };
+    /**
+     * Always-on ("inject") RAG: before each turn, retrieve passages for the user message and augment
+     * the system prompt with them. For agentic retrieval (the model decides when to search) DON'T set
+     * this — instead expose the tool: `provideAgentTool(createRetrievalTool(retriever))`. Omit → off.
+     */
+    retrieval?: {
+        mode: 'inject';
+        retriever: Retriever;
+        topK?: number;
+    };
+    /**
+     * The implicit single agent's config (base prompt, personas, tool allow-list, model/step
+     * config). Omit for a bare assistant. Additional named agents are added via `forFeature`.
+     */
+    defaultAgent?: DefaultAgentOptions;
+}
+interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+    inject?: Array<InjectionToken | OptionalFactoryDependency>;
+    useFactory: (...args: never[]) => AgentModuleOptions | Promise<AgentModuleOptions>;
+    /**
+     * Route prefix the controllers mount under (default `'agent'`). Static routing metadata, so it
+     * lives here rather than in the async factory result (which resolves too late to mount routes).
+     */
+    path?: string;
+    /**
+     * Run each turn as a durable workflow. Static wiring metadata (which `AGENT_RUNNER` to bind), so
+     * it lives here rather than in the async factory result — the factory resolves too late to swap
+     * the runner. Requires importing `AgentDurableModule` and a configured `DurableModule`.
+     */
+    durable?: boolean;
+}
+
+/** The synthesized `agent`-kind tool name an orchestrator uses to delegate to `target`. */
+declare function delegateToolName(target: string): string;
+/** Builds the per-agent loop deps. The single-agent case is just the `default` definition. */
+declare class AgentDepsFactory {
+    private readonly options;
+    private readonly model;
+    private readonly store;
+    private readonly sink;
+    private readonly rolesPolicy;
+    private readonly registry;
+    private readonly agents;
+    private readonly quota;
+    constructor(options: AgentModuleOptions, model: ModelProvider, store: AgentStore, sink: TokenStreamSink, rolesPolicy: RolesPolicy, registry: ToolRegistry, agents: AgentRegistry, quota: QuotaStore | undefined);
+    defaultAgentName(): string;
+    private effectiveTools;
+    forAgent(agentName?: string): AgentDeps;
+    /** Normalize the `followUps` option (`true` → 3, `{ count }` → count) to a number, or undefined. */
+    private followUpsCount;
+}
+
+export { AgentDepsFactory as A, type DefaultAgentOptions as D, type FunctionalTool as F, type AgentModuleOptions as a, type AgentModuleAsyncOptions as b, AGENT_TOOL_BRAND as c, type AgentDeps as d, delegateToolName as e, provideAgentTool as p, utcDay as u };