@dudousxd/nestjs-agent 1.1.2 → 1.3.0

package/README.md

@@ -41,6 +41,35 @@ The module mounts SSE + REST endpoints under `/agent` (`POST /agent/chat`, tool-
 threads, quota). Add `durable: true` + `AgentDurableModule` for the durable runner;
 `AgentModule.forFeature([…])` for multi-agent orchestration.
 
+### How a chat talks about a tool
+
+A tool's name is an identifier, not copy. Declare how a person-facing surface narrates it beside its
+input schema, so whoever renames an input field is the one who re-words the sentence that mentions
+it:
+
+```ts
+@AiTool({
+  name: 'purgeCache',
+  kind: 'action',
+  description: 'Purge a cache key.',
+  input: z.object({ key: z.string() }),
+  presentation: {
+    label: 'Cache purge',
+    running: 'Purging {key}',          // templates over the call's INPUT
+    done: 'Purged {key}',
+    icon: 'cache',                     // a key into the client's own glyph map
+    tone: 'destructive',
+    confirm: { title: 'Purge {key}?', verb: 'Purge' },
+    result: { kind: 'metrics', fields: [{ path: 'evicted', label: 'Evicted' }] }, // over the OUTPUT
+  },
+})
+```
+
+`GET /agent/tools?agent=<name>` returns `ToolCatalogEntry[]` — `{ name, kind, presentation? }` for the
+tools THIS actor can reach through that agent (the default agent when omitted; `404` for an unknown
+one), built by `ToolRegistry.visibleSpecs`, the same gates the model is offered tools through. The
+React package's `useToolCatalog` reads it. The model never sees `presentation`.
+
 ### Message attachments
 
 A chat turn attaches a file by **`mediaId` only**:
@@ -101,6 +130,36 @@ nobody is streaming (including one that has already finished). In-process caller
 authorized elsewhere use `AgentService.subscribe(runId)`; anything reachable from a request must go
 through `AgentService.subscribeAs(actor, runId)`.
 
+### Who approves an action, and for how long
+
+Every `action` tool call waits on the person chatting by default. `approvalPolicy` changes that per
+call:
+
+```ts
+AgentModule.forRoot({
+  // …
+  approvalPolicy: {
+    requirementFor: (tool, actor) =>
+      tool.name === 'issueRefund'
+        ? { required: true, approver: 'finance', ttlMs: 15 * 60_000 }
+        : { required: true, approver: 'requester' },
+    // Optional. Default: 'requester' = the thread's own actor, anything else = a role the decider holds.
+    // canDecide: (actor, { approver, requesterRef }) => gate.forUser(actor).allows('approve', approver),
+  },
+});
+```
+
+- `POST /agent/tool-call/approve` `{ toolCallId, remember?, via? }` and `…/reject` `{ toolCallId,
+  reason?, via? }` enforce the recorded approver (`403` otherwise) and refuse a request that has
+  lapsed (`410`). The decider is recorded as `executedByRef`, `via` as `decided_via` (`'web'` when
+  omitted; the console approvals port takes `decidedVia` too).
+- `remember: true` approves later calls of the same tool in the same thread without asking.
+- A `ttlMs` becomes the approval wait's timeout — `ctx.waitForSignal(…, { timeoutMs })` on the
+  durable runner, a timer inline. On expiry the call settles `expired`, the model is told nobody
+  approved it in time, and the stream carries `tool-output-denied` + `approval-settled`.
+- The tool-call row gains `approver`, `expires_at`, `remember` and `decided_via`; a reloaded thread
+  carries them as `StoredMessage.approvals`.
+
 ### A durable turn's model call and tools run in a worker
 
 Under `durable: true` the turn's model call and each of its tool executions are **dispatched steps**

package/dist/{agent-deps.factory-OjrLyAZo.d.cts → agent-deps.factory-CUyVPsa1.d.cts}

@@ -1,4 +1,4 @@
-import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry } from '@dudousxd/nestjs-agent-core';
+import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry } from '@dudousxd/nestjs-agent-core';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
 
@@ -8,6 +8,8 @@ interface AgentDeps {
     store: AgentStore;
     registry: ToolRegistry;
     rolesPolicy: RolesPolicy;
+    /** Who approves an action call, and for how long (from `forRoot({ approvalPolicy })`). Undefined → the requester, no expiry. */
+    approvalPolicy?: ApprovalPolicy;
     quota?: QuotaStore;
     sink: TokenStreamSink;
     /** Fallback accounting label; the provider's turn result overrides it when set. */
@@ -205,6 +207,13 @@ interface AgentModuleOptions {
     quotaLimitTokens?: number;
     /** Tool authorization gate. Defaults to role-in-`defaultRoles`. */
     rolesPolicy?: RolesPolicy;
+    /**
+     * Who has to approve an `action` tool call, and how long the request stays open. Defaults to the
+     * requester (the thread's own actor) with no expiry. A requirement naming another approver (a
+     * role) is enforced by `POST tool-call/approve|reject` through `canDecide` — by default, the
+     * deciding actor must hold that role. See `ApprovalPolicy`.
+     */
+    approvalPolicy?: ApprovalPolicy;
     /** Default roles a tool requires when its `roles` is omitted. Defaults to `['ADMIN']`. */
     defaultRoles?: string[];
     /**

package/dist/{agent-deps.factory-OjrLyAZo.d.ts → agent-deps.factory-CUyVPsa1.d.ts}

@@ -1,4 +1,4 @@
-import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry } from '@dudousxd/nestjs-agent-core';
+import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry } from '@dudousxd/nestjs-agent-core';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
 
@@ -8,6 +8,8 @@ interface AgentDeps {
     store: AgentStore;
     registry: ToolRegistry;
     rolesPolicy: RolesPolicy;
+    /** Who approves an action call, and for how long (from `forRoot({ approvalPolicy })`). Undefined → the requester, no expiry. */
+    approvalPolicy?: ApprovalPolicy;
     quota?: QuotaStore;
     sink: TokenStreamSink;
     /** Fallback accounting label; the provider's turn result overrides it when set. */
@@ -205,6 +207,13 @@ interface AgentModuleOptions {
     quotaLimitTokens?: number;
     /** Tool authorization gate. Defaults to role-in-`defaultRoles`. */
     rolesPolicy?: RolesPolicy;
+    /**
+     * Who has to approve an `action` tool call, and how long the request stays open. Defaults to the
+     * requester (the thread's own actor) with no expiry. A requirement naming another approver (a
+     * role) is enforced by `POST tool-call/approve|reject` through `canDecide` — by default, the
+     * deciding actor must hold that role. See `ApprovalPolicy`.
+     */
+    approvalPolicy?: ApprovalPolicy;
     /** Default roles a tool requires when its `roles` is omitted. Defaults to `['ADMIN']`. */
     defaultRoles?: string[];
     /**