@dudousxd/nestjs-agent 1.2.0 → 1.3.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 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 { 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';
@@ -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>;
 }
 
@@ -754,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;
     /**

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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 { 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';
@@ -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>;
 }
 
@@ -754,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;
     /**

package/dist/index.js

@@ -122,6 +122,9 @@ var AgentDepsFactory2 = class {
       store: this.store,
       sink: this.sink,
       rolesPolicy: this.rolesPolicy,
+      ...this.options.approvalPolicy !== void 0 ? {
+        approvalPolicy: this.options.approvalPolicy
+      } : {},
       registry: this.registry,
       promptContributors: this.promptContributors,
       systemPrompt: definition?.systemPrompt ?? "You are a helpful assistant.",
@@ -269,8 +272,8 @@ AgentDepsFactory2 = _ts_decorate([
 ], AgentDepsFactory2);
 
 // src/agent.service.ts
-import { AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_QUOTA_STORE as AGENT_QUOTA_STORE2, AGENT_RUNNER, AGENT_STORE as AGENT_STORE2 } from "@dudousxd/nestjs-agent-core";
-import { BadRequestException, ForbiddenException, Inject as Inject2, Injectable as Injectable2, NotFoundException, NotImplementedException, Optional as Optional2 } from "@nestjs/common";
+import { AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_QUOTA_STORE as AGENT_QUOTA_STORE2, AGENT_RUNNER, AGENT_STORE as AGENT_STORE2, REQUESTER_APPROVER, mayDecideApproval } from "@dudousxd/nestjs-agent-core";
+import { BadRequestException, ForbiddenException, GoneException, Inject as Inject2, Injectable as Injectable2, NotFoundException, NotImplementedException, Optional as Optional2 } from "@nestjs/common";
 
 // src/agent-deps.ts
 function utcDay(date = /* @__PURE__ */ new Date()) {
@@ -423,18 +426,35 @@ var AgentService = class {
     await this.assertOwnsActiveStream(actor, runId);
     return this.subscribe(runId);
   }
-  async approve(actor, toolCallId2) {
-    await this.assertOwnsToolCall(actor, toolCallId2);
+  /**
+  * 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.
+  */
+  async approve(actor, toolCallId2, opts = {}) {
+    await this.assertMayDecide(actor, toolCallId2);
     return this.signalToolCall(toolCallId2, {
-      approved: true
+      approved: true,
+      executedByRef: actor.id,
+      ...opts.remember === true ? {
+        remember: true
+      } : {},
+      ...opts.via !== void 0 ? {
+        decidedVia: opts.via
+      } : {}
     });
   }
-  async reject(actor, toolCallId2, reason) {
-    await this.assertOwnsToolCall(actor, toolCallId2);
+  async reject(actor, toolCallId2, reason, opts = {}) {
+    await this.assertMayDecide(actor, toolCallId2);
     return this.signalToolCall(toolCallId2, {
       approved: false,
+      executedByRef: actor.id,
       ...reason !== void 0 ? {
         reason
+      } : {},
+      ...opts.via !== void 0 ? {
+        decidedVia: opts.via
       } : {}
     });
   }
@@ -475,6 +495,7 @@ var AgentService = class {
   * not the thread's own actor).
   */
   async signalToolCall(toolCallId2, reply) {
+    await this.assertNotExpired(toolCallId2);
     const runId = await this.resolveRunForToolCall(toolCallId2);
     return this.runner.signal(runId, toolCallId2, reply);
   }
@@ -713,6 +734,47 @@ var AgentService = class {
     }
   }
   /**
+  * 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.
+  */
+  async assertMayDecide(actor, toolCallId2) {
+    const approval = await this.store.toolCallApproval?.(toolCallId2);
+    const approver = approval?.approver ?? REQUESTER_APPROVER;
+    if (approver === REQUESTER_APPROVER) {
+      return this.assertOwnsToolCall(actor, toolCallId2);
+    }
+    const requesterRef = await this.store.ownerOfToolCall(toolCallId2);
+    if (requesterRef === null) {
+      throw new NotFoundException(`tool call ${toolCallId2} not found`);
+    }
+    const allowed = await mayDecideApproval(this.deps.forAgent().approvalPolicy, actor, {
+      toolCallId: toolCallId2,
+      approver,
+      requesterRef
+    });
+    if (!allowed) {
+      throw new ForbiddenException(`this approval is for ${approver}`);
+    }
+  }
+  /**
+  * 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.
+  */
+  async assertNotExpired(toolCallId2) {
+    const approval = await this.store.toolCallApproval?.(toolCallId2);
+    if (approval === null || approval === void 0) {
+      return;
+    }
+    const lapsed = approval.status === "expired" || approval.status === "pending_approval" && approval.expiresAt !== null && Date.parse(approval.expiresAt) <= Date.now();
+    if (lapsed) {
+      throw new GoneException(`the approval request for tool call ${toolCallId2} has expired`);
+    }
+  }
+  /**
   * 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
   * call belongs to a delegated agent. The store answers from the CALL'S OWN `runId` where it has
@@ -790,6 +852,12 @@ var AgentApprovalPortAdapter = class {
       approved: true,
       ...opts?.executedByRef !== void 0 ? {
         executedByRef: opts.executedByRef
+      } : {},
+      ...opts?.remember === true ? {
+        remember: true
+      } : {},
+      ...opts?.decidedVia !== void 0 ? {
+        decidedVia: opts.decidedVia
       } : {}
     });
   }
@@ -801,6 +869,9 @@ var AgentApprovalPortAdapter = class {
       } : {},
       ...opts?.reason !== void 0 ? {
         reason: opts.reason
+      } : {},
+      ...opts?.decidedVia !== void 0 ? {
+        decidedVia: opts.decidedVia
       } : {}
     });
   }
@@ -1720,6 +1791,8 @@ var MAX_ANSWERED_QUESTIONS = 100;
 var MAX_VALUES_PER_QUESTION = 100;
 var MAX_ANSWER_VALUE_LENGTH = 4096;
 var MAX_REJECT_REASON_LENGTH = 4096;
+var MAX_VIA_LENGTH = 64;
+var DEFAULT_VIA = "web";
 function toolCallId(claimed) {
   if (typeof claimed !== "string" || claimed.length === 0) {
     throw new BadRequestException4("toolCallId must be a non-empty string");
@@ -1740,6 +1813,26 @@ function rejectReason(claimed) {
   return claimed;
 }
 __name(rejectReason, "rejectReason");
+function remember(claimed) {
+  if (claimed === void 0) {
+    return false;
+  }
+  if (typeof claimed !== "boolean") {
+    throw new BadRequestException4("remember must be a boolean");
+  }
+  return claimed;
+}
+__name(remember, "remember");
+function via(claimed) {
+  if (claimed === void 0) {
+    return DEFAULT_VIA;
+  }
+  if (typeof claimed !== "string" || claimed.length === 0 || claimed.length > MAX_VIA_LENGTH) {
+    throw new BadRequestException4(`via must be a string of 1-${MAX_VIA_LENGTH} characters`);
+  }
+  return claimed;
+}
+__name(via, "via");
 function answers(claimed) {
   if (claimed === void 0) {
     return void 0;
@@ -1784,14 +1877,19 @@ var ToolCallController = class {
   }
   async approve(req, body) {
     const actor = await this.actorResolver.resolve(req);
-    await this.agent.approve(actor, toolCallId(body.toolCallId));
+    await this.agent.approve(actor, toolCallId(body.toolCallId), {
+      remember: remember(body.remember),
+      via: via(body.via)
+    });
     return {
       ok: true
     };
   }
   async reject(req, body) {
     const actor = await this.actorResolver.resolve(req);
-    await this.agent.reject(actor, toolCallId(body.toolCallId), rejectReason(body.reason));
+    await this.agent.reject(actor, toolCallId(body.toolCallId), rejectReason(body.reason), {
+      via: via(body.via)
+    });
     return {
       ok: true
     };
@@ -1857,7 +1955,7 @@ _ts_decorate11([
   _ts_metadata11("design:type", Function),
   _ts_metadata11("design:paramtypes", [
     typeof Request === "undefined" ? Object : Request,
-    typeof ApproveBody === "undefined" ? Object : ApproveBody
+    Object
   ]),
   _ts_metadata11("design:returntype", Promise)
 ], ToolCallController.prototype, "skip", null);
@@ -2723,6 +2821,36 @@ var InlineAgentRunner = class _InlineAgentRunner {
   * 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.
+  */
+  parkApproval(runId, toolCallId2, timeoutMs) {
+    const waiting = this.park(runId, toolCallId2);
+    if (timeoutMs === void 0) {
+      return waiting;
+    }
+    const key = `${runId}:${toolCallId2}`;
+    let timer;
+    const lapse = new Promise((resolve) => {
+      timer = setTimeout(() => {
+        const entry = this.pending.get(key);
+        if (entry !== void 0) {
+          this.pending.delete(key);
+          resolve({
+            approved: false,
+            expired: true
+          });
+        }
+      }, timeoutMs);
+      timer.unref?.();
+    });
+    return Promise.race([
+      waiting,
+      lapse
+    ]).finally(() => clearTimeout(timer));
+  }
   park(runId, toolCallId2) {
     return new Promise((resolve, reject) => {
       this.pending.set(`${runId}:${toolCallId2}`, {
@@ -2736,7 +2864,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
     return {
       runId,
       openSink: /* @__PURE__ */ __name(() => deps.sink.open(runId), "openSink"),
-      awaitApproval: /* @__PURE__ */ __name((call) => this.park(runId, call.id), "awaitApproval"),
+      awaitApproval: /* @__PURE__ */ __name((call, _ctx, opts) => this.parkApproval(runId, call.id, opts?.timeoutMs), "awaitApproval"),
       awaitAnswers: /* @__PURE__ */ __name((request) => this.park(runId, request.id), "awaitAnswers"),
       step: /* @__PURE__ */ __name((_name, fn) => fn(), "step"),
       parallel: settleAll,
@@ -2787,7 +2915,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
     const hooks = {
       runId,
       openSink: /* @__PURE__ */ __name(() => deps.sink.open(runId), "openSink"),
-      awaitApproval: /* @__PURE__ */ __name((call) => this.park(runId, call.id), "awaitApproval"),
+      awaitApproval: /* @__PURE__ */ __name((call, _ctx, opts) => this.parkApproval(runId, call.id, opts?.timeoutMs), "awaitApproval"),
       awaitAnswers: /* @__PURE__ */ __name((request) => this.park(runId, request.id), "awaitAnswers"),
       step: /* @__PURE__ */ __name((_name, fn) => fn(), "step"),
       parallel: settleAll,
@@ -2891,7 +3019,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
       runId,
       // Forward into the top-level stream; the top-level run owns end/fail on that shared sink.
       openSink: /* @__PURE__ */ __name(async () => childSinkWriter(await deps.sink.open(sinkRunId)), "openSink"),
-      awaitApproval: /* @__PURE__ */ __name((call) => this.park(runId, call.id), "awaitApproval"),
+      awaitApproval: /* @__PURE__ */ __name((call, _ctx, opts) => this.parkApproval(runId, call.id, opts?.timeoutMs), "awaitApproval"),
       awaitAnswers: /* @__PURE__ */ __name((request) => this.park(runId, request.id), "awaitAnswers"),
       step: /* @__PURE__ */ __name((_name, fn) => fn(), "step"),
       parallel: settleAll,