@dudousxd/nestjs-agent 1.21.0 → 1.23.0

package/dist/index.js

@@ -17,6 +17,7 @@ import { defineCatalog, genuiTools } from "@dudousxd/nestjs-agent-core/genui";
 import { Inject, Module } from "@nestjs/common";
 
 // src/functional-tool.ts
+import { createFunctionalTool } from "@dudousxd/nestjs-agent-core";
 var AGENT_TOOL_BRAND = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:functional-tool");
 function brand(tool) {
   return {
@@ -53,6 +54,7 @@ function provideAgentTools(factory, inject) {
   };
 }
 __name(provideAgentTools, "provideAgentTools");
+var defineTool = createFunctionalTool;
 
 // src/genui/agent-genui.module.ts
 function _ts_decorate(decorators, target, key, desc) {
@@ -589,7 +591,7 @@ function childSinkWriter(writer) {
 __name(childSinkWriter, "childSinkWriter");
 
 // src/proposals/action-proposal.service.ts
-import { AGENT_OPTIONS as AGENT_OPTIONS2, AGENT_STORE as AGENT_STORE2, mayDecideApproval, parseTextActionProposalCommand, resolveTextActionProposalDecision } from "@dudousxd/nestjs-agent-core";
+import { AGENT_OPTIONS as AGENT_OPTIONS2, AGENT_STORE as AGENT_STORE2, DEFAULT_TEXT_ACTION_PROPOSAL_REPLIES, DEFAULT_TEXT_ACTION_PROPOSAL_VOCABULARY, mayDecideApproval, parseTextActionProposalCommand, resolveTextActionProposalDecision, textActionProposalReply, toActionProposalMutationView, toActionProposalView } from "@dudousxd/nestjs-agent-core";
 import { ForbiddenException, Inject as Inject3, Injectable as Injectable2, NotFoundException, NotImplementedException } from "@nestjs/common";
 function _ts_decorate3(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -626,7 +628,19 @@ var ActionProposalService = class {
   constructor(store, options) {
     this.store = store;
     this.options = options;
+    const text = options.actionProposalText;
+    this.vocabulary = {
+      ...DEFAULT_TEXT_ACTION_PROPOSAL_VOCABULARY,
+      ...text?.vocabulary
+    };
+    this.replies = {
+      ...DEFAULT_TEXT_ACTION_PROPOSAL_REPLIES,
+      ...text?.replies
+    };
   }
+  /** The words a text decision is made of, and what the agent answers — English unless configured. */
+  vocabulary;
+  replies;
   capability() {
     const store = this.store;
     if (typeof store.getThreadActionProposalScope !== "function" || typeof store.listActionProposals !== "function") throw new NotImplementedException("Action proposals are unavailable");
@@ -655,7 +669,8 @@ var ActionProposalService = class {
     for (const row of rows) if (scope.actorRef === actor.id || await this.mayDecide(actor, row)) visible.push(row);
     const last = rows.at(-1);
     return {
-      items: visible,
+      // The public view: a row carries the worker's lease token and the tool's idempotency key.
+      items: visible.map(toActionProposalView),
       ...rows.length === 1e3 && last ? {
         next: {
           createdAt: last.createdAt,
@@ -672,7 +687,7 @@ var ActionProposalService = class {
     const proposal = await this.capability().getActionProposal(scope, proposalId);
     if (!proposal) throw new NotFoundException("Proposal not found");
     if (!await this.mayDecide(actor, proposal)) throw new ForbiddenException("May not decide this proposal");
-    return this.capability().decideActionProposal(scope, proposalId, {
+    const result = await this.capability().decideActionProposal(scope, proposalId, {
       decision: command.decision,
       actorRef: actor.id,
       via: command.via ?? "web",
@@ -683,9 +698,10 @@ var ActionProposalService = class {
         reason: command.reason
       } : {}
     });
+    return toActionProposalMutationView(result);
   }
   async handleTextDecision(threadId, actor, text) {
-    const command = parseTextActionProposalCommand(text);
+    const command = parseTextActionProposalCommand(text, this.vocabulary);
     if (command.status === "unmatched") return command;
     if (command.proposalId !== void 0) {
       const result2 = await this.decide(threadId, command.proposalId, actor, {
@@ -693,7 +709,7 @@ var ActionProposalService = class {
         remember: command.remember,
         via: "text"
       });
-      return this.textReceipt(threadId, result2);
+      return this.textReceipt(threadId, result2, command.decision);
     }
     const candidates = [];
     const scope = await this.scope(threadId, actor);
@@ -702,30 +718,38 @@ var ActionProposalService = class {
       limit: 1e3
     });
     for (const proposal of pending) if (await this.mayDecide(actor, proposal)) candidates.push(proposal);
-    const resolution = resolveTextActionProposalDecision(text, candidates);
+    const resolution = resolveTextActionProposalDecision(text, candidates, this.vocabulary);
     if (resolution.status === "unmatched") return resolution;
-    if (resolution.status === "ambiguous" || resolution.status === "decision" && pending.length === 1e3 && !text.includes("#")) return {
-      threadId,
-      proposalDecision: {
-        status: "ambiguous",
-        proposalIds: candidates.map(({ id }) => id)
-      },
-      text: `Choose the action to decide: ${candidates.map(({ id }) => id).map((id) => `#${id}`).join(", ")}`
-    };
+    const saturated = pending.length === 1e3 && !text.includes("#");
+    if (resolution.status === "ambiguous" || saturated) {
+      const proposalIds = candidates.map(({ id }) => id);
+      return {
+        threadId,
+        proposalDecision: {
+          status: "ambiguous",
+          proposalIds
+        },
+        text: saturated ? this.replies.tooMany : this.replies.ambiguous(proposalIds)
+      };
+    }
     const result = await this.decide(threadId, resolution.proposalId, actor, {
       decision: resolution.decision,
       remember: resolution.remember,
       via: "text"
     });
-    return this.textReceipt(threadId, result);
+    return this.textReceipt(threadId, result, resolution.decision);
   }
-  textReceipt(threadId, result) {
+  textReceipt(threadId, result, decision) {
     return {
       threadId,
       proposalDecision: result,
-      text: result.proposal?.decision === "approved" ? "Action approved and queued for execution." : `Action ${result.proposal?.decision ?? result.status}; no execution was performed by this decision.`
+      text: this.reply(result, decision)
     };
   }
+  /** The configured reply to a decision the store answered with `result`. */
+  reply(result, decision) {
+    return textActionProposalReply(result, decision, this.replies);
+  }
 };
 ActionProposalService = _ts_decorate3([
   Injectable2(),
@@ -742,6 +766,33 @@ ActionProposalService = _ts_decorate3([
 import { AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_OPTIONS as AGENT_OPTIONS3, AGENT_QUOTA_PROVIDER, AGENT_SINK as AGENT_SINK2, AGENT_STORE as AGENT_STORE3, encodeStreamEvent, isChatQueueStore, queuedMessageView } from "@dudousxd/nestjs-agent-core";
 import { Inject as Inject4, Injectable as Injectable3, Logger, NotImplementedException as NotImplementedException2, Optional as Optional2 } from "@nestjs/common";
 
+// src/quota-exceeded.ts
+import { publishAgentQuotaExceeded } from "@dudousxd/nestjs-agent-core";
+function publishQuotaBlocked(actor, report, blocked) {
+  const window = report.windows.find((candidate) => candidate.period === blocked.period);
+  const payload = {
+    actorId: actor.id,
+    period: blocked.period,
+    ...blocked.reason !== void 0 ? {
+      reason: blocked.reason
+    } : {},
+    ...window?.usedTokens !== void 0 ? {
+      usedTokens: window.usedTokens
+    } : {},
+    ...window?.limitTokens !== void 0 ? {
+      limitTokens: window.limitTokens
+    } : {},
+    ...window !== void 0 ? {
+      usedUsd: window.usedUsd
+    } : {},
+    ...window?.limitUsd !== void 0 ? {
+      limitUsd: window.limitUsd
+    } : {}
+  };
+  publishAgentQuotaExceeded(payload);
+}
+__name(publishQuotaBlocked, "publishQuotaBlocked");
+
 // src/thread-persona.ts
 async function threadPersona(store, threadId) {
   const projecting = store;
@@ -1041,6 +1092,9 @@ var ChatQueueService = class _ChatQueueService {
       } : {},
       ...input.uiCapabilities !== void 0 ? {
         uiCapabilities: input.uiCapabilities
+      } : {},
+      ...input.hostContext !== void 0 ? {
+        hostContext: input.hostContext
       } : {}
     });
     await store.setQueuePause(threadId, {
@@ -1085,12 +1139,14 @@ var ChatQueueService = class _ChatQueueService {
       return null;
     }
     try {
-      const { blocked } = await this.quotaProvider.report({
+      const report = await this.quotaProvider.report({
         actor
       });
+      const { blocked } = report;
       if (blocked === void 0) {
         return null;
       }
+      publishQuotaBlocked(actor, report, blocked);
       return blocked.reason ?? `The ${blocked.period === "day" ? "daily" : "monthly"} quota is used up`;
     } catch {
       return null;
@@ -1124,6 +1180,9 @@ var ChatQueueService = class _ChatQueueService {
       ...message.uiCapabilities !== void 0 ? {
         uiCapabilities: message.uiCapabilities
       } : {},
+      ...message.hostContext !== void 0 ? {
+        hostContext: message.hostContext
+      } : {},
       ...message.model !== void 0 ? {
         model: message.model
       } : {}
@@ -1292,6 +1351,21 @@ var AgentService = class {
     this.queue = queue;
     this.proposals = proposals;
   }
+  /**
+  * Decide one independent proposal through the scoped proposal service — what the native
+  * `action-proposals/:id/approve|reject` routes call — and the reply to show for it. `404` when
+  * proposals are not on, `403`/`404` when this actor may not decide it.
+  */
+  async decideActionProposal(actor, threadId, proposalId, command) {
+    if (this.options?.actionApprovalMode !== "independent" || !this.proposals) {
+      throw new NotFoundException2("Proposal not found");
+    }
+    const result = await this.proposals.decide(threadId, proposalId, actor, command);
+    return {
+      proposalDecision: result,
+      text: this.proposals.reply(result, command.decision)
+    };
+  }
   async handleTextDecision(threadId, actor, text) {
     if (this.options?.actionApprovalMode !== "independent" || !this.proposals) return {
       status: "unmatched"
@@ -1339,10 +1413,12 @@ var AgentService = class {
     if (this.options?.quota === void 0 || this.quotaProvider === void 0) {
       return;
     }
-    const { blocked } = await this.quotaProvider.report({
+    const report = await this.quotaProvider.report({
       actor
     });
+    const { blocked } = report;
     if (blocked !== void 0) {
+      publishQuotaBlocked(actor, report, blocked);
       throw new HttpException({
         statusCode: HttpStatus.TOO_MANY_REQUESTS,
         code: "quota_exceeded",
@@ -1477,6 +1553,9 @@ var AgentService = class {
       }
       const created = await this.store.createThread({
         actor: params.actor,
+        ...agentName !== void 0 ? {
+          agentName
+        } : {},
         ...params.transient === true ? {
           transient: true
         } : {},
@@ -1489,7 +1568,7 @@ var AgentService = class {
       });
       threadId = created.id;
     } else {
-      await this.assertOwnsThread(params.actor, threadId);
+      if (params.authorized !== true) await this.assertOwnsThread(params.actor, threadId);
       if (params.personaId !== void 0) {
         await this.pinThreadPersona(threadId, params.personaId);
       }
@@ -1515,6 +1594,9 @@ var AgentService = class {
       ...params.uiCapabilities !== void 0 ? {
         uiCapabilities: params.uiCapabilities
       } : {},
+      ...params.hostContext !== void 0 ? {
+        hostContext: params.hostContext
+      } : {},
       ...model !== void 0 ? {
         model
       } : {}
@@ -1537,7 +1619,7 @@ var AgentService = class {
       });
     }
     if (live === null && mode !== "queue") {
-      const runId = crypto.randomUUID();
+      const runId = this.runner.runIdFor?.(input) ?? crypto.randomUUID();
       if (await queue.queueStore().claimActiveStream(threadId, runId, stale !== null ? {
         replacing: stale
       } : {})) {
@@ -1605,6 +1687,9 @@ var AgentService = class {
       ...input.uiCapabilities !== void 0 ? {
         uiCapabilities: input.uiCapabilities
       } : {},
+      ...input.hostContext !== void 0 ? {
+        hostContext: input.hostContext
+      } : {},
       ...interrupting !== void 0 ? {
         interrupt: true,
         at: "head"
@@ -4633,6 +4718,9 @@ var AiToolDiscoveryService = class _AiToolDiscoveryService {
         } : {}
       }, {
         execute: /* @__PURE__ */ __name((input, ctx) => instance.execute(input, ctx), "execute"),
+        ...typeof handler.present === "function" ? {
+          present: /* @__PURE__ */ __name((output, ctx) => instance.present(output, ctx), "present")
+        } : {},
         ...typeof handler.preflight === "function" ? {
           preflight: /* @__PURE__ */ __name((input, ctx, options) => instance.preflight(input, ctx, options), "preflight")
         } : {},
@@ -5746,15 +5834,15 @@ function _ts_decorate26(decorators, target, key, desc) {
 __name(_ts_decorate26, "_ts_decorate");
 var DEFAULT_PATH = "agent";
 var logger = new Logger7("AgentModule");
-function externalStoreWrapper(modules) {
+function externalWrapper(modules, token) {
   for (const module of modules.values()) {
     if (module.metatype === AgentModule) continue;
-    const wrapper = module.providers.get(AGENT_STORE7);
+    const wrapper = module.providers.get(token);
     if (wrapper !== void 0) return wrapper;
   }
   return void 0;
 }
-__name(externalStoreWrapper, "externalStoreWrapper");
+__name(externalWrapper, "externalWrapper");
 function forwardingStore(wrapper) {
   const target = /* @__PURE__ */ __name(() => {
     const instance = wrapper.instance;
@@ -5777,23 +5865,47 @@ function forwardingStore(wrapper) {
 __name(forwardingStore, "forwardingStore");
 function resolveStore(options, modules) {
   if (options.store !== void 0) return options.store;
-  const external = externalStoreWrapper(modules);
+  const external = externalWrapper(modules, AGENT_STORE7);
   if (external !== void 0) return forwardingStore(external);
   logger.warn("No `store` configured and no store module imported \u2014 using the in-memory store. Threads are lost on restart and not shared between processes: not for production. Pass `store`, or import a store module (e.g. MikroOrmAgentStoreModule.forFeature()).");
   return new InMemoryAgentStore();
 }
 __name(resolveStore, "resolveStore");
+function resolveRolesPolicy(options, modules) {
+  const external = externalWrapper(modules, AGENT_ROLES_POLICY2);
+  if (options.rolesPolicy !== void 0) {
+    if (external !== void 0) {
+      logger.warn("Both a `rolesPolicy` option and a module binding AGENT_ROLES_POLICY (e.g. AgentAuthzModule) are configured \u2014 the `rolesPolicy` option wins.");
+    }
+    return options.rolesPolicy;
+  }
+  if (external !== void 0) return forwardingPolicy(external);
+  return options.emptyRoles === "deny" ? new ClosedRolesPolicy(options.defaultRoles) : new DefaultRolesPolicy(options.defaultRoles);
+}
+__name(resolveRolesPolicy, "resolveRolesPolicy");
+function forwardingPolicy(wrapper) {
+  return {
+    can(actor, tool) {
+      const policy = wrapper.instance;
+      if (policy === void 0 || policy === null) {
+        throw new Error("AgentModule: the AGENT_ROLES_POLICY bound by another module is not ready yet");
+      }
+      return policy.can(actor, tool);
+    }
+  };
+}
+__name(forwardingPolicy, "forwardingPolicy");
 function isQuotaProvider(quota) {
   return quota !== void 0 && typeof quota.report === "function";
 }
 __name(isQuotaProvider, "isQuotaProvider");
 function resolveCatalog(options) {
   if (options.models !== void 0) return options.models;
-  const carried = options.model.catalog;
+  const carried = options.model?.catalog;
   return carried !== void 0 && typeof carried.list === "function" ? carried : void 0;
 }
 __name(resolveCatalog, "resolveCatalog");
-function sharedProviders(durable) {
+function sharedProviders(durable, engine) {
   const providers = [
     {
       provide: AGENT_TOOL_REGISTRY3,
@@ -5844,9 +5956,10 @@ function sharedProviders(durable) {
     },
     {
       provide: AGENT_ROLES_POLICY2,
-      useFactory: /* @__PURE__ */ __name((options) => options.rolesPolicy ?? (options.emptyRoles === "deny" ? new ClosedRolesPolicy(options.defaultRoles) : new DefaultRolesPolicy(options.defaultRoles)), "useFactory"),
+      useFactory: /* @__PURE__ */ __name((options, modules) => resolveRolesPolicy(options, modules), "useFactory"),
       inject: [
-        AGENT_OPTIONS9
+        AGENT_OPTIONS9,
+        ModulesContainer
       ]
     },
     {
@@ -5923,7 +6036,12 @@ function sharedProviders(durable) {
       ModulesContainer
     ]
   });
-  if (durable) {
+  if (engine !== void 0) {
+    providers.push(...engine.providers, {
+      provide: AGENT_RUNNER2,
+      useExisting: engine.runner
+    });
+  } else if (durable) {
     providers.push({
       provide: AGENT_RUNNER2,
       useFactory: /* @__PURE__ */ __name((durableRunner) => {
@@ -5948,8 +6066,9 @@ function sharedProviders(durable) {
   return providers;
 }
 __name(sharedProviders, "sharedProviders");
-function exportsFor() {
+function exportsFor(engine) {
   return [
+    ...engine?.exports ?? [],
     AGENT_OPTIONS9,
     AGENT_TOOL_REGISTRY3,
     AGENT_REGISTRY6,
@@ -5999,10 +6118,11 @@ function adapterProviders(adapters) {
   return (adapters ?? []).flatMap((adapter) => adapter.providers ?? []);
 }
 __name(adapterProviders, "adapterProviders");
-function controllersForSurface(surface, adapters) {
+function controllersForSurface(surface, adapters, engine) {
   return surface === "engine" ? [] : [
     ...BASE_CONTROLLERS,
-    ...adapterControllers(adapters)
+    ...adapterControllers(adapters),
+    ...engine?.controllers ?? []
   ];
 }
 __name(controllersForSurface, "controllersForSurface");
@@ -6032,12 +6152,22 @@ function routerFor(path) {
   ]);
 }
 __name(routerFor, "routerFor");
+function assertRunnable(options) {
+  if (options.engine !== void 0 && options.durable === true) {
+    throw new Error(`AgentModule: \`durable: true\` runs turns on the library's loop, but the \`${options.engine.name}\` engine runs them instead. Drop \`durable\` (the engine decides how its turns survive a restart).`);
+  }
+  if (options.engine === void 0 && options.model === void 0) {
+    throw new Error("AgentModule: set `model` (the loop runs the turns) or `engine` (something else does).");
+  }
+}
+__name(assertRunnable, "assertRunnable");
 var AgentModule = class _AgentModule {
   static {
     __name(this, "AgentModule");
   }
   static forRoot(options) {
     const path = options.path ?? DEFAULT_PATH;
+    assertRunnable(options);
     applyGuards(options.guards, options.adapters);
     return {
       module: _AgentModule,
@@ -6046,21 +6176,27 @@ var AgentModule = class _AgentModule {
         DiscoveryModule,
         routerFor(path)
       ],
-      controllers: controllersForSurface(options.surface, options.adapters),
+      controllers: controllersForSurface(options.surface, options.adapters, options.engine),
       providers: [
         {
           provide: AGENT_OPTIONS9,
           useValue: options
         },
-        ...sharedProviders(options.durable ?? false),
+        ...sharedProviders(options.durable ?? false, options.engine),
         ...guardProviders(options.guards),
         ...adapterProviders(options.adapters)
       ],
-      exports: exportsFor()
+      exports: exportsFor(options.engine)
     };
   }
   static forRootAsync(options) {
     const path = options.path ?? DEFAULT_PATH;
+    if (options.engine !== void 0) {
+      assertRunnable({
+        engine: options.engine,
+        durable: options.durable ?? false
+      });
+    }
     applyGuards(options.guards, options.adapters);
     return {
       module: _AgentModule,
@@ -6070,7 +6206,7 @@ var AgentModule = class _AgentModule {
         routerFor(path),
         ...options.imports ?? []
       ],
-      controllers: controllersForSurface(options.surface, options.adapters),
+      controllers: controllersForSurface(options.surface, options.adapters, options.engine),
       providers: [
         {
           provide: AGENT_OPTIONS9,
@@ -6080,18 +6216,25 @@ var AgentModule = class _AgentModule {
           // anything today (AgentDurableModule takes its own mirror option — see its doc for why),
           // but it's stamped here too so the EFFECTIVE value is always observable off
           // AGENT_OPTIONS, sync or async alike.
-          useFactory: /* @__PURE__ */ __name(async (...args) => ({
-            ...await options.useFactory(...args),
-            durable: options.durable ?? false,
-            surface: options.surface ?? "both"
-          }), "useFactory"),
+          useFactory: /* @__PURE__ */ __name(async (...args) => {
+            const resolved = {
+              ...await options.useFactory(...args),
+              durable: options.durable ?? false,
+              surface: options.surface ?? "both",
+              ...options.engine !== void 0 ? {
+                engine: options.engine
+              } : {}
+            };
+            assertRunnable(resolved);
+            return resolved;
+          }, "useFactory"),
           inject: options.inject ?? []
         },
-        ...sharedProviders(options.durable ?? false),
+        ...sharedProviders(options.durable ?? false, options.engine),
         ...guardProviders(options.guards),
         ...adapterProviders(options.adapters)
       ],
-      exports: exportsFor()
+      exports: exportsFor(options.engine)
     };
   }
 };
@@ -6188,6 +6331,19 @@ var AgUiRunHandler = class {
         warnings.push(`The resume entry ${id} answers an interrupt this agent did not raise.`);
       }
       const first = plan.decisions[0];
+      if (first !== void 0 && plan.decisions.every((d) => d.address.kind === "proposal")) {
+        const decided = await this.decideProposals(actor, plan.decisions);
+        this.writeEvents(res, [
+          ...warningEvents(warnings),
+          ...decided.flatMap((outcome, index) => actionProposalDecisionEvents({
+            threadId: input.threadId,
+            runId: index === 0 ? input.runId : `${input.runId}:${index}`,
+            text: outcome.text,
+            proposalDecision: outcome.proposalDecision
+          }))
+        ]);
+        return;
+      }
       if (first !== void 0) {
         const streamRunId = first.address.stream;
         await this.agent.assertResumable(actor, streamRunId);
@@ -6216,11 +6372,7 @@ var AgUiRunHandler = class {
     if (owner !== null && turn.media.length === 0) {
       const decision = await this.agent.handleTextDecision(input.threadId, actor, turn.text);
       if ("proposalDecision" in decision) {
-        res.status(200);
-        res.setHeader("Content-Type", "text/event-stream");
-        res.setHeader("Cache-Control", "no-cache, no-transform");
-        res.flushHeaders();
-        for (const event of [
+        this.writeEvents(res, [
           ...warningEvents(warnings),
           ...actionProposalDecisionEvents({
             threadId: input.threadId,
@@ -6228,8 +6380,7 @@ var AgUiRunHandler = class {
             text: decision.text,
             proposalDecision: decision.proposalDecision
           })
-        ]) res.write(agUiSse(event));
-        res.end();
+        ]);
         return;
       }
     }
@@ -6321,9 +6472,11 @@ var AgUiRunHandler = class {
   */
   async settle(actor, decisions) {
     const deliveries = [];
+    const proposals = decisions.filter((decision) => decision.address.kind === "proposal");
     for (const { address, entry } of decisions) {
       const { toolCallId: toolCallId2 } = address;
       const abandoned = entry.status === "cancelled";
+      if (address.kind === "proposal") continue;
       if (address.kind === "approval") {
         await this.agent.checkDecision(actor, toolCallId2);
         const decision = abandoned ? {
@@ -6360,9 +6513,53 @@ var AgUiRunHandler = class {
         via: AG_UI_VIA
       }));
     }
+    if (proposals.length > 0) await this.decideProposals(actor, proposals);
     for (const deliver of deliveries) await deliver();
   }
   /**
+  * Decide independent proposals through the proposal service — the call the native
+  * `action-proposals/:id/approve|reject` routes make — never by signalling the origin run, which
+  * is not waiting. Every payload is checked before the first decision; a refusal is the service's
+  * own `403`/`404`.
+  */
+  async decideProposals(actor, decisions) {
+    const planned = decisions.map(({ address, entry }) => {
+      const decision = entry.status === "cancelled" ? {
+        approved: false
+      } : readApprovalPayload(entry.payload);
+      if (decision === null || address.proposalId === void 0 || address.threadId === void 0) {
+        throw invalid("invalid_resume", "an approval is answered with { approved: boolean, reason?, remember? }");
+      }
+      return {
+        address,
+        decision
+      };
+    });
+    const outcomes = [];
+    for (const { address, decision } of planned) {
+      outcomes.push(await this.agent.decideActionProposal(actor, address.threadId, address.proposalId, {
+        decision: decision.approved ? "approved" : "rejected",
+        via: AG_UI_VIA,
+        ...decision.remember !== void 0 ? {
+          remember: decision.remember
+        } : {},
+        ...decision.reason !== void 0 ? {
+          reason: decision.reason
+        } : {}
+      }));
+    }
+    return outcomes;
+  }
+  /** Answer with a complete list of events, no run behind them. */
+  writeEvents(res, events) {
+    res.status(200);
+    res.setHeader("Content-Type", "text/event-stream");
+    res.setHeader("Cache-Control", "no-cache, no-transform");
+    res.flushHeaders();
+    for (const event of events) res.write(agUiSse(event));
+    res.end();
+  }
+  /**
   * Pipe a run to the client as AG-UI 1.0 over SSE: one event per `data:` line, from `RUN_STARTED`
   * to the run's terminal event. It ends when the run stops to ask — the library run stays parked,
   * and the request that answers re-attaches to it.
@@ -6569,6 +6766,7 @@ export {
   attachmentLimits,
   declaredSkillProvider,
   defaultRequestUserMapper,
+  defineTool,
   delegateToolName,
   provideAgentTool,
   provideAgentTools,