@dudousxd/nestjs-agent 1.1.2 → 1.3.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { DynamicModule, OnModuleInit, Type, OnApplicationBootstrap } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, d as AgentSkillsOptions } from './agent-deps.factory-OjrLyAZo.cjs';
-export { e as AGENT_TOOL_BRAND, f as AgentAttachmentsOptions, g as AgentDeps, h as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, i as delegateToolName, p as provideAgentTool, u as utcDay } from './agent-deps.factory-OjrLyAZo.cjs';
-import { AgentRunner, AgentStore, QuotaStore, AttachmentStagingStore, Actor, AttachmentRef, PageContext, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, StagedAttachment, QuotaView, AgentApprovalPort, ActorResolver, MessageAttachment, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, TokenStreamSink, SinkWriter, QuotaState } from '@dudousxd/nestjs-agent-core';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, d as AgentSkillsOptions } from './agent-deps.factory-CUyVPsa1.cjs';
+export { e as AGENT_TOOL_BRAND, f as AgentAttachmentsOptions, g as AgentDeps, h as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, i as delegateToolName, p as provideAgentTool, u as utcDay } from './agent-deps.factory-CUyVPsa1.cjs';
+import { AgentRunner, AgentStore, QuotaStore, AttachmentStagingStore, Actor, AttachmentRef, PageContext, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, StagedAttachment, QuotaView, AgentApprovalPort, ActorResolver, MessageAttachment, ToolPresentation, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, TokenStreamSink, SinkWriter, QuotaState } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 import { Request } from 'express';
 import { StandardSchemaV1 } from '@standard-schema/spec';
@@ -80,8 +80,19 @@ declare class AgentService {
      * ownership is derived from.
      */
     subscribeAs(actor: Actor, runId: string): Promise<AsyncIterable<Uint8Array>>;
-    approve(actor: Actor, toolCallId: string): Promise<void>;
-    reject(actor: Actor, toolCallId: string, reason?: string): Promise<void>;
+    /**
+     * Approve a parked action call as `actor`. Who may is the call's recorded approver's business
+     * (see {@link assertMayDecide}); `remember` approves later calls of the same tool in the same
+     * thread, and `via` names the surface the decision came through (`'web'`, `'slack'`, …) — both
+     * persisted with the call.
+     */
+    approve(actor: Actor, toolCallId: string, opts?: {
+        remember?: boolean;
+        via?: string;
+    }): Promise<void>;
+    reject(actor: Actor, toolCallId: string, reason?: string, opts?: {
+        via?: string;
+    }): Promise<void>;
     /**
      * Answer a parked question set. An omitted question takes the request's own pre-picked default —
      * resolved by the LOOP against the request it already holds, so "the user just submitted" and
@@ -193,6 +204,20 @@ declare class AgentService {
      * adapter can resolve+signal a decision WITHOUT this check — it is authorized upstream instead.
      */
     private assertOwnsToolCall;
+    /**
+     * Authorization seam for approve/reject. The call's recorded approver decides who may settle it:
+     * the requester (the default, and every call recorded before approvers existed) is the thread's
+     * own actor — the ownership check this always was; any other approver goes through the policy's
+     * `canDecide`, which by default asks whether the actor holds that role.
+     */
+    private assertMayDecide;
+    /**
+     * Refuse a decision on a request that has already lapsed — recorded `expired`, or past its
+     * `expiresAt` with the run's own timer about to fire. Signalling it anyway would race the timeout:
+     * a durable runtime buffers a signal nobody is waiting on, and a late approval must not be what a
+     * later replay of the run reads back.
+     */
+    private assertNotExpired;
     /**
      * Resolve the run awaiting `toolCallId`. Derived server-side from the tool call alone — the client
      * never knows or supplies a runId, and that run is the sub-agent's own child run when the pending
@@ -223,10 +248,13 @@ declare class AgentApprovalPortAdapter implements AgentApprovalPort {
     constructor(agent: AgentService);
     approve(toolCallId: string, opts?: {
         executedByRef?: string;
+        remember?: boolean;
+        decidedVia?: string;
     }): Promise<void>;
     reject(toolCallId: string, opts?: {
         executedByRef?: string;
         reason?: string;
+        decidedVia?: string;
     }): Promise<void>;
 }
 
@@ -315,6 +343,22 @@ interface AiToolOptions {
      * role-based policy, which uses `roles`.
      */
     ability?: string;
+    /**
+     * How a chat surface talks about this tool without naming it — sentence templates over the
+     * call's input, an icon key, the approval prompt's wording, and how its output reads. Never shown
+     * to the model. Served by `GET <base>/tools` to the actors who can reach the tool:
+     *
+     * ```ts
+     * @AiTool({
+     *   name: 'purgeCache', kind: 'action', description: '…', input,
+     *   presentation: {
+     *     label: 'Cache purge', running: 'Purging {key}', done: 'Purged {key}', icon: 'cache',
+     *     tone: 'destructive', confirm: { title: 'Purge {key}?', verb: 'Purge' },
+     *   },
+     * })
+     * ```
+     */
+    presentation?: ToolPresentation;
 }
 /**
  * Marks a provider class as an AI tool. The class must implement `execute(input, ctx)`.
@@ -610,6 +654,30 @@ declare class SkillsController {
     threadId?: string): Promise<SkillCatalogEntry[]>;
 }
 
+/**
+ * The tools THIS caller can reach through an agent, with how a chat surface should talk about each
+ * one (`@AiTool({ presentation })`) — so a client narrates "Querying orders" instead of printing
+ * `executeSql`, from words declared beside the tool's input schema rather than a client-side map
+ * that goes stale on the next rename.
+ *
+ * THE SAME LIST THE MODEL IS OFFERED: built by `ToolRegistry.visibleSpecs`, the call behind
+ * `definitionsFor`, against the agent's own allow-list, the roles policy and each tool's
+ * `isEnabled`/`canUse`. Built-in tools the loop serves itself (`ask`, `skill`, `remember`) are not
+ * registry tools and are not listed.
+ *
+ * Posture mirrors `GET /agent/skills`: a plain array, and nothing the caller can pass to widen it —
+ * the actor comes from the resolver, and `agent` only ever narrows to that agent's allow-list.
+ */
+declare class ToolsController {
+    private readonly actorResolver;
+    private readonly depsFactory;
+    private readonly agents;
+    constructor(actorResolver: ActorResolver, depsFactory: AgentDepsFactory, agents: AgentRegistry);
+    list(req: Request, 
+    /** The agent whose tools to list. Omitted → the default agent, the one a turn naming none uses. */
+    agent?: string): Promise<ToolCatalogEntry[]>;
+}
+
 /**
  * What the assistant believes about THIS caller — and how they take one of those beliefs back.
  *
@@ -714,6 +782,12 @@ declare class InlineAgentRunner implements AgentRunner {
      * shape it is delivering — the loop asked for one and only ever gets what the caller sent. A
      * cancel settles the wait too, by rejecting it.
      */
+    /**
+     * {@link park} for an approval, bounded by the policy's time to live when it has one: the timer
+     * settles the wait as `expired` — the same Decision the durable runner builds from its signal
+     * timeout — and a decision that arrives first disarms it.
+     */
+    private parkApproval;
     private park;
     private topLevelHooks;
     /**
@@ -783,4 +857,4 @@ declare class HeaderActorResolver implements ActorResolver {
     resolve(req: unknown): Actor;
 }
 
-export { AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, AttachmentsController, type ChatParams, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, MemoriesController, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, declaredSkillProvider, readAgentMetadata, readAiToolMetadata, readSkillMetadata, resolveSkillsConfig, skillScope };
+export { AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, AttachmentsController, type ChatParams, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, MemoriesController, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, ToolsController, declaredSkillProvider, readAgentMetadata, readAiToolMetadata, readSkillMetadata, resolveSkillsConfig, skillScope };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { DynamicModule, OnModuleInit, Type, OnApplicationBootstrap } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, d as AgentSkillsOptions } from './agent-deps.factory-OjrLyAZo.js';
-export { e as AGENT_TOOL_BRAND, f as AgentAttachmentsOptions, g as AgentDeps, h as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, i as delegateToolName, p as provideAgentTool, u as utcDay } from './agent-deps.factory-OjrLyAZo.js';
-import { AgentRunner, AgentStore, QuotaStore, AttachmentStagingStore, Actor, AttachmentRef, PageContext, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, StagedAttachment, QuotaView, AgentApprovalPort, ActorResolver, MessageAttachment, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, TokenStreamSink, SinkWriter, QuotaState } from '@dudousxd/nestjs-agent-core';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, d as AgentSkillsOptions } from './agent-deps.factory-CUyVPsa1.js';
+export { e as AGENT_TOOL_BRAND, f as AgentAttachmentsOptions, g as AgentDeps, h as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, i as delegateToolName, p as provideAgentTool, u as utcDay } from './agent-deps.factory-CUyVPsa1.js';
+import { AgentRunner, AgentStore, QuotaStore, AttachmentStagingStore, Actor, AttachmentRef, PageContext, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, StagedAttachment, QuotaView, AgentApprovalPort, ActorResolver, MessageAttachment, ToolPresentation, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, TokenStreamSink, SinkWriter, QuotaState } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 import { Request } from 'express';
 import { StandardSchemaV1 } from '@standard-schema/spec';
@@ -80,8 +80,19 @@ declare class AgentService {
      * ownership is derived from.
      */
     subscribeAs(actor: Actor, runId: string): Promise<AsyncIterable<Uint8Array>>;
-    approve(actor: Actor, toolCallId: string): Promise<void>;
-    reject(actor: Actor, toolCallId: string, reason?: string): Promise<void>;
+    /**
+     * Approve a parked action call as `actor`. Who may is the call's recorded approver's business
+     * (see {@link assertMayDecide}); `remember` approves later calls of the same tool in the same
+     * thread, and `via` names the surface the decision came through (`'web'`, `'slack'`, …) — both
+     * persisted with the call.
+     */
+    approve(actor: Actor, toolCallId: string, opts?: {
+        remember?: boolean;
+        via?: string;
+    }): Promise<void>;
+    reject(actor: Actor, toolCallId: string, reason?: string, opts?: {
+        via?: string;
+    }): Promise<void>;
     /**
      * Answer a parked question set. An omitted question takes the request's own pre-picked default —
      * resolved by the LOOP against the request it already holds, so "the user just submitted" and
@@ -193,6 +204,20 @@ declare class AgentService {
      * adapter can resolve+signal a decision WITHOUT this check — it is authorized upstream instead.
      */
     private assertOwnsToolCall;
+    /**
+     * Authorization seam for approve/reject. The call's recorded approver decides who may settle it:
+     * the requester (the default, and every call recorded before approvers existed) is the thread's
+     * own actor — the ownership check this always was; any other approver goes through the policy's
+     * `canDecide`, which by default asks whether the actor holds that role.
+     */
+    private assertMayDecide;
+    /**
+     * Refuse a decision on a request that has already lapsed — recorded `expired`, or past its
+     * `expiresAt` with the run's own timer about to fire. Signalling it anyway would race the timeout:
+     * a durable runtime buffers a signal nobody is waiting on, and a late approval must not be what a
+     * later replay of the run reads back.
+     */
+    private assertNotExpired;
     /**
      * Resolve the run awaiting `toolCallId`. Derived server-side from the tool call alone — the client
      * never knows or supplies a runId, and that run is the sub-agent's own child run when the pending
@@ -223,10 +248,13 @@ declare class AgentApprovalPortAdapter implements AgentApprovalPort {
     constructor(agent: AgentService);
     approve(toolCallId: string, opts?: {
         executedByRef?: string;
+        remember?: boolean;
+        decidedVia?: string;
     }): Promise<void>;
     reject(toolCallId: string, opts?: {
         executedByRef?: string;
         reason?: string;
+        decidedVia?: string;
     }): Promise<void>;
 }
 
@@ -315,6 +343,22 @@ interface AiToolOptions {
      * role-based policy, which uses `roles`.
      */
     ability?: string;
+    /**
+     * How a chat surface talks about this tool without naming it — sentence templates over the
+     * call's input, an icon key, the approval prompt's wording, and how its output reads. Never shown
+     * to the model. Served by `GET <base>/tools` to the actors who can reach the tool:
+     *
+     * ```ts
+     * @AiTool({
+     *   name: 'purgeCache', kind: 'action', description: '…', input,
+     *   presentation: {
+     *     label: 'Cache purge', running: 'Purging {key}', done: 'Purged {key}', icon: 'cache',
+     *     tone: 'destructive', confirm: { title: 'Purge {key}?', verb: 'Purge' },
+     *   },
+     * })
+     * ```
+     */
+    presentation?: ToolPresentation;
 }
 /**
  * Marks a provider class as an AI tool. The class must implement `execute(input, ctx)`.
@@ -610,6 +654,30 @@ declare class SkillsController {
     threadId?: string): Promise<SkillCatalogEntry[]>;
 }
 
+/**
+ * The tools THIS caller can reach through an agent, with how a chat surface should talk about each
+ * one (`@AiTool({ presentation })`) — so a client narrates "Querying orders" instead of printing
+ * `executeSql`, from words declared beside the tool's input schema rather than a client-side map
+ * that goes stale on the next rename.
+ *
+ * THE SAME LIST THE MODEL IS OFFERED: built by `ToolRegistry.visibleSpecs`, the call behind
+ * `definitionsFor`, against the agent's own allow-list, the roles policy and each tool's
+ * `isEnabled`/`canUse`. Built-in tools the loop serves itself (`ask`, `skill`, `remember`) are not
+ * registry tools and are not listed.
+ *
+ * Posture mirrors `GET /agent/skills`: a plain array, and nothing the caller can pass to widen it —
+ * the actor comes from the resolver, and `agent` only ever narrows to that agent's allow-list.
+ */
+declare class ToolsController {
+    private readonly actorResolver;
+    private readonly depsFactory;
+    private readonly agents;
+    constructor(actorResolver: ActorResolver, depsFactory: AgentDepsFactory, agents: AgentRegistry);
+    list(req: Request, 
+    /** The agent whose tools to list. Omitted → the default agent, the one a turn naming none uses. */
+    agent?: string): Promise<ToolCatalogEntry[]>;
+}
+
 /**
  * What the assistant believes about THIS caller — and how they take one of those beliefs back.
  *
@@ -714,6 +782,12 @@ declare class InlineAgentRunner implements AgentRunner {
      * shape it is delivering — the loop asked for one and only ever gets what the caller sent. A
      * cancel settles the wait too, by rejecting it.
      */
+    /**
+     * {@link park} for an approval, bounded by the policy's time to live when it has one: the timer
+     * settles the wait as `expired` — the same Decision the durable runner builds from its signal
+     * timeout — and a decision that arrives first disarms it.
+     */
+    private parkApproval;
     private park;
     private topLevelHooks;
     /**
@@ -783,4 +857,4 @@ declare class HeaderActorResolver implements ActorResolver {
     resolve(req: unknown): Actor;
 }
 
-export { AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, AttachmentsController, type ChatParams, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, MemoriesController, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, declaredSkillProvider, readAgentMetadata, readAiToolMetadata, readSkillMetadata, resolveSkillsConfig, skillScope };
+export { AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, AttachmentsController, type ChatParams, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, MemoriesController, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, ToolsController, declaredSkillProvider, readAgentMetadata, readAiToolMetadata, readSkillMetadata, resolveSkillsConfig, skillScope };