@dudousxd/nestjs-agent 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,16 +1,14 @@
-import { AgentDefinition, AgentRunner, AgentStore, Actor, PageContext, Persona, ThreadSummary, ThreadDetail, ToolRegistry, AgentRegistry, AgentRunInput, Decision, TokenStreamSink, SinkWriter, QuotaStore, QuotaState, ActorResolver } from '@dudousxd/nestjs-agent-core';
+import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit } from '@nestjs/common';
+import { a as AgentModuleOptions, b as AgentModuleAsyncOptions, A as AgentDepsFactory } from './agent-deps.factory-DpVkZYCy.js';
+export { c as AGENT_TOOL_BRAND, d as AgentDeps, F as FunctionalTool, e as delegateToolName, p as provideAgentTool, u as utcDay } from './agent-deps.factory-DpVkZYCy.js';
+import { AgentRunner, AgentStore, QuotaStore, Actor, PageContext, ThreadSummary, ThreadDetail, QuotaView, ToolRegistry, AgentRegistry, PromptContributor, AgentRunInput, Decision, TokenStreamSink, SinkWriter, QuotaState, ActorResolver } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
-import { DynamicModule, OnApplicationBootstrap } from '@nestjs/common';
-import { a as AgentModuleOptions, b as AgentModuleAsyncOptions, A as AgentDepsFactory } from './agent-deps.factory-D9BHJJqm.js';
-export { c as AGENT_TOOL_BRAND, d as AgentDeps, D as DefaultAgentOptions, F as FunctionalTool, e as delegateToolName, p as provideAgentTool, u as utcDay } from './agent-deps.factory-D9BHJJqm.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { DiscoveryService } from '@nestjs/core';
+import { DiscoveryService, MetadataScanner } from '@nestjs/core';
 
 declare class AgentModule {
     static forRoot(options: AgentModuleOptions): DynamicModule;
     static forRootAsync(options: AgentModuleAsyncOptions): DynamicModule;
-    /** Register additional named agents (an orchestrator + its sub-agents). */
-    static forFeature(definitions: AgentDefinition[]): DynamicModule;
 }
 
 interface ChatParams {
@@ -18,17 +16,22 @@ interface ChatParams {
     message: string;
     threadId?: string;
     agentName?: string;
-    personaId?: string;
     pageContext?: PageContext;
     /** Re-run the last exchange instead of adding a new message. Requires an existing `threadId`. */
     regenerate?: boolean;
+    /**
+     * When creating a thread (no `threadId`), start it transient — a scratch conversation hidden from
+     * the thread list until the caller promotes it. Ignored when `threadId` is set.
+     */
+    transient?: boolean;
 }
 /** The orchestration facade the controllers call. */
 declare class AgentService {
     private readonly runner;
     private readonly store;
     private readonly deps;
-    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory);
+    private readonly quota;
+    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, quota: QuotaStore | undefined);
     chat(params: ChatParams): Promise<{
         runId: string;
         threadId: string;
@@ -37,18 +40,24 @@ declare class AgentService {
     approve(actor: Actor, toolCallId: string): Promise<void>;
     reject(actor: Actor, toolCallId: string, reason?: string): Promise<void>;
     cancel(actor: Actor, runId: string): Promise<void>;
-    resolvePersona(agentName?: string, id?: string): Persona | undefined;
-    personaCatalog(agentName?: string): {
-        id: string;
-        label: string;
-    }[];
     listThreads(actorRef: string): Promise<ThreadSummary[]>;
     getThread(actor: Actor, threadId: string): Promise<ThreadDetail | null>;
     deleteThread(actor: Actor, threadId: string): Promise<void>;
     forkThread(actor: Actor, threadId: string, fromMessageId: string): Promise<ThreadSummary>;
-    quotaToday(actorRef: string): Promise<{
-        usedTokens: number;
-    }>;
+    renameThread(actor: Actor, threadId: string, title: string): Promise<void>;
+    promoteThread(actor: Actor, threadId: string): Promise<void>;
+    /**
+     * Drop a message and everything after it — the "edit and resend" / "delete from here" primitive.
+     * The client then sends a fresh turn on the truncated thread. Ownership-gated like the other
+     * thread-scoped mutations.
+     */
+    truncateThreadFrom(actor: Actor, threadId: string, messageId: string): Promise<void>;
+    /**
+     * The day's usage for the badge: tokens + summed USD cost from the store, and the configured
+     * limit from the quota store (null → unlimited). `withinLimit` comes from the quota store so it
+     * can never drift from what enforcement uses.
+     */
+    quotaToday(actorRef: string): Promise<QuotaView>;
     /**
      * Authorization seam for thread-scoped endpoints: the caller must own the thread. A missing
      * thread is a 404; someone else's thread is a 403 — one actor never touches another's thread.
@@ -102,6 +111,59 @@ interface AiToolOptions {
 declare function AiTool(options: AiToolOptions): ClassDecorator;
 declare function readAiToolMetadata(target: object): AiToolOptions | undefined;
 
+/**
+ * Declares a class as an agent. The class is discovered at boot (via `DiscoveryService`) and
+ * registered into the `AgentRegistry` — its name, base prompt, tool allow-list, and handoff targets
+ * become an internal `AgentDefinition` the loop consumes. The class is an ordinary provider, so it
+ * gets constructor DI (its retriever, schema service, policy) — the reason an agent is a class and
+ * not a config object.
+ *
+ * The base prompt is either the `systemPrompt` string here or, for a dynamic prompt, a
+ * `@SystemPrompt()` method on the class (which may inject services and read the turn's
+ * `PromptContext`). Tools are the global `@AiTool` providers named in `tools` (omit → all tools the
+ * actor's role allows); handoff targets are other `@Agent` classes.
+ */
+interface AgentOptions {
+    /** Unique agent name — how a turn selects it and how a message records its provenance. */
+    name: string;
+    /** Human-readable summary (shown to an orchestrator that may hand off to this agent). */
+    description?: string;
+    /** A flat base prompt. For a dynamic prompt, add a `@SystemPrompt()` method instead. */
+    systemPrompt?: string;
+    /** Accounting label for the model this agent uses (the model provider itself is shared). */
+    model?: string;
+    /** Max model→tool iterations for this agent's turn. Default 8. */
+    maxSteps?: number;
+    /** Allow-list of global tool names this agent may use. Omit → every tool its role allows. */
+    tools?: string[];
+    /** Other `@Agent` classes this agent may hand off to (auto-exposed as handoff tools). */
+    handoff?: Type[];
+}
+declare const AGENT_METADATA: unique symbol;
+/** Marks a provider class as an agent. See {@link AgentOptions}. */
+declare function Agent(options: AgentOptions): ClassDecorator;
+/** Reads {@link AgentOptions} off a class (its constructor), or `undefined` if not an `@Agent`. */
+declare function readAgentMetadata(target: Type | Function): AgentOptions | undefined;
+
+/**
+ * Marks the method on an `@Agent` class that builds the agent's base system prompt. The method
+ * receives the turn's `PromptContext` and returns a string (optionally async); because it lives on a
+ * provider, it can inject services (e.g. describe a schema, read the actor). Exactly one per agent —
+ * it takes precedence over the `@Agent({ systemPrompt })` string.
+ */
+declare const SYSTEM_PROMPT_METADATA: unique symbol;
+/**
+ * Marks a method on any provider as a cross-agent system-prompt contributor: it returns an ordered
+ * section appended to the composed prompt (after the selected agent's base), or `null` to contribute
+ * nothing this turn. This is the seam an app uses to inject domain sections (base scope, a mentions
+ * legend, schema hints) across every agent without forking the loop.
+ */
+declare const SYSTEM_PROMPT_CONTRIBUTOR_METADATA: unique symbol;
+/** Marks an `@Agent` method as the agent's dynamic base prompt. See {@link SYSTEM_PROMPT_METADATA}. */
+declare function SystemPrompt(): MethodDecorator;
+/** Marks a provider method as a cross-agent prompt contributor. See {@link SYSTEM_PROMPT_CONTRIBUTOR_METADATA}. */
+declare function SystemPromptContributor(): MethodDecorator;
+
 /** Walks every provider at boot and registers `@AiTool` classes into the shared registry. */
 declare class AiToolDiscoveryService implements OnApplicationBootstrap {
     private readonly discovery;
@@ -118,6 +180,32 @@ declare class AiToolDiscoveryService implements OnApplicationBootstrap {
     private registerFunctionalTool;
 }
 
+/**
+ * Populates the {@link AgentRegistry} from `@Agent`-decorated providers and collects every
+ * `@SystemPromptContributor()` method into the app-wide contributor list — the discovery counterpart
+ * to authoring agents as config objects. Runs on `onModuleInit`, so agents/contributors are in place
+ * before `AiToolDiscoveryService` (which synthesizes handoff tools) runs its `onApplicationBootstrap`.
+ */
+declare class AgentDiscoveryService implements OnModuleInit {
+    private readonly discovery;
+    private readonly scanner;
+    private readonly registry;
+    private readonly contributors;
+    private readonly logger;
+    constructor(discovery: DiscoveryService, scanner: MetadataScanner, registry: AgentRegistry, contributors: PromptContributor[]);
+    onModuleInit(): void;
+    /** Build the internal {@link AgentDefinition} from an `@Agent` instance and its options. */
+    private definitionFrom;
+    /** Resolve each handoff `@Agent` class to its registered name (skipping non-agent classes). */
+    private handoffNames;
+    /** Push every `@SystemPromptContributor()` method on `instance` (bound) into the contributor list. */
+    private collectContributors;
+    /** The single method on `instance` carrying `metadataKey`, bound to the instance, or undefined. */
+    private methodWith;
+    /** Bind a named method to its instance, guarding that it is actually a function. */
+    private boundMethod;
+}
+
 /**
  * Runs the agent turn in-process. HITL approval resolves a pending promise keyed by
  * `runId:toolCallId`. Sub-agent delegation runs a nested loop that streams into the top-level run's
@@ -192,4 +280,4 @@ declare class HeaderActorResolver implements ActorResolver {
     resolve(req: unknown): Actor;
 }
 
-export { AI_TOOL_METADATA, AgentDepsFactory, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, AgentService, AiTool, AiToolDiscoveryService, type AiToolOptions, type ChatParams, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, readAiToolMetadata };
+export { AGENT_METADATA, AI_TOOL_METADATA, Agent, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AiTool, AiToolDiscoveryService, type AiToolOptions, type ChatParams, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, SystemPrompt, SystemPromptContributor, readAgentMetadata, readAiToolMetadata };