@dudousxd/nestjs-agent 1.33.0 → 1.35.0

package/dist/index.d.cts

@@ -1,14 +1,14 @@
 import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit, ConflictException, OnModuleDestroy } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, d as AgentProtocolAdapter, A as AgentDepsFactory, e as AgentSkillsOptions, C as ChatQueueService } from './chat-queue.service-QIuTS-5c.cjs';
-export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentEngine, j as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, k as QueueSettleOutcome, l as QueuedTurn, m as QueuedTurnStarter, n as QuotaLimits, o as QuotaWindowLimits, p as defineTool, q as delegateToolName, r as provideAgentTool, s as provideAgentTools, u as utcDay } from './chat-queue.service-QIuTS-5c.cjs';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, d as AgentProtocolAdapter, A as AgentDepsFactory, e as AgentSkillsOptions, C as ChatQueueService } from './chat-queue.service-CF2fcJDx.cjs';
+export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentEngine, j as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, k as QueueSettleOutcome, l as QueuedTurn, m as QueuedTurnStarter, n as QuotaLimits, o as QuotaWindowLimits, p as defineTool, q as delegateToolName, r as provideAgentTool, s as provideAgentTools, u as utcDay } from './chat-queue.service-CF2fcJDx.cjs';
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
-import { ActorResolver, AttachmentStagingStore, AgentApprovalPort, Actor, AgentStore, StagedAttachment, MessageAttachment, ModelCatalog, AgentClientConfig, ToolSpec, ToolPresentation, AgentHistoryWindow, AgentIntake, Persona, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, MessageFeedbackValue, MessageFeedback, ModelCatalogView, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunner, AgentRunInput, AgentRunStartOptions, HumanReply, ChatQueueState, TokenStreamSink, SinkWriter, ActionProposal } from '@dudousxd/nestjs-agent-core';
+import { ActorResolver, AttachmentStagingStore, AgentApprovalPort, Actor, AgentStore, StagedAttachment, MessageAttachment, ModelCatalog, AgentClientConfig, ToolSpec, ToolPresentation, AgentHistoryWindow, AgentIntake, Persona, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, MessageFeedbackValue, MessageFeedback, ModelCatalogView, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunner, AgentRunInput, AgentRunStartOptions, HumanReply, ChatQueueState, TokenStreamSink, SinkWriter, ActionProposalOutcome, ActionProposal } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 export { FunctionalToolDefinition } from '@dudousxd/nestjs-agent-core';
 import { A2uiOptions } from '@dudousxd/nestjs-agent-core/a2ui';
 import { Request, Response } from 'express';
-import { A as AgentService, a as ActionProposalService } from './index-DIFUEKPr.cjs';
-export { b as A2uiAdapterOptions, c as A2uiRunHandler, d as AttachmentLimits, C as ChatParams, e as ChatSendMode, f as ChatSendResult, D as DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, g as DEFAULT_MAX_ATTACHMENT_BYTES, M as MAX_ATTACHMENTS_PER_MESSAGE, N as NO_USER_MESSAGE_CODE, Q as QueuedSend, T as ThreadDefaultAgentReader, h as ThreadModelReader, i as a2uiAdapter, j as attachmentLimits } from './index-DIFUEKPr.cjs';
+import { A as AgentService, a as ActionProposalService } from './index-NF93YDF4.cjs';
+export { b as A2uiAdapterOptions, c as A2uiRunHandler, d as AttachmentLimits, C as ChatParams, e as ChatSendMode, f as ChatSendResult, D as DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, g as DEFAULT_MAX_ATTACHMENT_BYTES, M as MAX_ATTACHMENTS_PER_MESSAGE, N as NO_USER_MESSAGE_CODE, Q as QueuedSend, T as ThreadDefaultAgentReader, h as ThreadModelReader, i as a2uiAdapter, j as attachmentLimits } from './index-NF93YDF4.cjs';
 import { AgentGenui } from './genui/index.cjs';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
@@ -354,10 +354,15 @@ interface AgentOptions {
      * per edge, by the author, and never by the model: the same worker is worth waiting for in one
      * orchestrator and worth backgrounding in another, and only the person wiring the edge knows
      * which side of that the user is sitting on.
+     *
+     * `roles` / `ability` gate who may delegate along the edge (the delegate tool's own), e.g.
+     * `{ agent: Helper, roles: ['personal_agent'] }` to let a personal agent's turn delegate.
      */
     handoff?: (Type | {
         agent: Type;
         detached?: boolean;
+        roles?: string[];
+        ability?: string;
     })[];
     /**
      * How much of the thread this agent's turns carry, overriding `AgentModule.forRoot({ history })`.
@@ -994,6 +999,8 @@ declare class ActionProposalController {
 
 /** Called with a proposal the worker just settled (executed, or failed executing). */
 type ActionProposalSettledListener = (proposal: ActionProposal) => void | Promise<void>;
+/** Called with a proposal outcome the worker just wrote to its thread. */
+type ActionProposalAdmittedListener = (outcome: ActionProposalOutcome) => void | Promise<void>;
 declare class ActionProposalWorkerService implements OnModuleInit, OnModuleDestroy {
     private readonly store;
     private readonly options;
@@ -1001,6 +1008,16 @@ declare class ActionProposalWorkerService implements OnModuleInit, OnModuleDestr
     private worker;
     private readonly logger;
     private readonly settledListeners;
+    private readonly admittedListeners;
+    /**
+     * Run `listener` once a settled proposal's outcome is written to its thread by this process's
+     * worker (the thread was free) — what a module uses to CONTINUE a conversation once an action it
+     * proposed ran (a Poppy connect: the next turn goes on with what was asked). Next to
+     * `actionProposalWorker.onAdmitted`; a listener that throws is logged and does not stop the
+     * others. Returns the unsubscribe.
+     */
+    onAdmitted(listener: ActionProposalAdmittedListener): () => void;
+    private admitted;
     /**
      * Run `listener` after every proposal this process's worker settles — how a module relays an
      * outcome somewhere the turn's stream no longer reaches (a text channel's conversation). Next to
@@ -1014,4 +1031,4 @@ declare class ActionProposalWorkerService implements OnModuleInit, OnModuleDestr
     onModuleDestroy(): Promise<void>;
 }
 
-export { AGENT_CHAT_QUEUE, AGENT_METADATA, AGENT_SERVICE, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, ActionProposalController, ActionProposalService, type ActionProposalSettledListener, ActionProposalWorkerService, type AgUiAdapterOptions, AgUiRunHandler, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentProtocolAdapter, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, type AnonymousActorOptions, AnonymousActorResolver, AttachmentsController, ChatQueueService, ConfigController, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, MemoriesController, MessagesController, ModelsController, QueueController, type RequestUserMapper, type ResolvedAiToolOptions, RunNotActiveException, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadPersonaReader, ToolsController, agUiAdapter, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, threadPersona, toolNameFromClass };
+export { AGENT_CHAT_QUEUE, AGENT_METADATA, AGENT_SERVICE, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, type ActionProposalAdmittedListener, ActionProposalController, ActionProposalService, type ActionProposalSettledListener, ActionProposalWorkerService, type AgUiAdapterOptions, AgUiRunHandler, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentProtocolAdapter, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, type AnonymousActorOptions, AnonymousActorResolver, AttachmentsController, ChatQueueService, ConfigController, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, MemoriesController, MessagesController, ModelsController, QueueController, type RequestUserMapper, type ResolvedAiToolOptions, RunNotActiveException, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadPersonaReader, ToolsController, agUiAdapter, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, threadPersona, toolNameFromClass };

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit, ConflictException, OnModuleDestroy } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, d as AgentProtocolAdapter, A as AgentDepsFactory, e as AgentSkillsOptions, C as ChatQueueService } from './chat-queue.service-wNWaoUN8.js';
-export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentEngine, j as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, k as QueueSettleOutcome, l as QueuedTurn, m as QueuedTurnStarter, n as QuotaLimits, o as QuotaWindowLimits, p as defineTool, q as delegateToolName, r as provideAgentTool, s as provideAgentTools, u as utcDay } from './chat-queue.service-wNWaoUN8.js';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, d as AgentProtocolAdapter, A as AgentDepsFactory, e as AgentSkillsOptions, C as ChatQueueService } from './chat-queue.service-CzXsKVb1.js';
+export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentEngine, j as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, k as QueueSettleOutcome, l as QueuedTurn, m as QueuedTurnStarter, n as QuotaLimits, o as QuotaWindowLimits, p as defineTool, q as delegateToolName, r as provideAgentTool, s as provideAgentTools, u as utcDay } from './chat-queue.service-CzXsKVb1.js';
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
-import { ActorResolver, AttachmentStagingStore, AgentApprovalPort, Actor, AgentStore, StagedAttachment, MessageAttachment, ModelCatalog, AgentClientConfig, ToolSpec, ToolPresentation, AgentHistoryWindow, AgentIntake, Persona, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, MessageFeedbackValue, MessageFeedback, ModelCatalogView, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunner, AgentRunInput, AgentRunStartOptions, HumanReply, ChatQueueState, TokenStreamSink, SinkWriter, ActionProposal } from '@dudousxd/nestjs-agent-core';
+import { ActorResolver, AttachmentStagingStore, AgentApprovalPort, Actor, AgentStore, StagedAttachment, MessageAttachment, ModelCatalog, AgentClientConfig, ToolSpec, ToolPresentation, AgentHistoryWindow, AgentIntake, Persona, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, MessageFeedbackValue, MessageFeedback, ModelCatalogView, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunner, AgentRunInput, AgentRunStartOptions, HumanReply, ChatQueueState, TokenStreamSink, SinkWriter, ActionProposalOutcome, ActionProposal } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 export { FunctionalToolDefinition } from '@dudousxd/nestjs-agent-core';
 import { A2uiOptions } from '@dudousxd/nestjs-agent-core/a2ui';
 import { Request, Response } from 'express';
-import { A as AgentService, a as ActionProposalService } from './index-DFKUTFfZ.js';
-export { b as A2uiAdapterOptions, c as A2uiRunHandler, d as AttachmentLimits, C as ChatParams, e as ChatSendMode, f as ChatSendResult, D as DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, g as DEFAULT_MAX_ATTACHMENT_BYTES, M as MAX_ATTACHMENTS_PER_MESSAGE, N as NO_USER_MESSAGE_CODE, Q as QueuedSend, T as ThreadDefaultAgentReader, h as ThreadModelReader, i as a2uiAdapter, j as attachmentLimits } from './index-DFKUTFfZ.js';
+import { A as AgentService, a as ActionProposalService } from './index-DpS9P7so.js';
+export { b as A2uiAdapterOptions, c as A2uiRunHandler, d as AttachmentLimits, C as ChatParams, e as ChatSendMode, f as ChatSendResult, D as DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, g as DEFAULT_MAX_ATTACHMENT_BYTES, M as MAX_ATTACHMENTS_PER_MESSAGE, N as NO_USER_MESSAGE_CODE, Q as QueuedSend, T as ThreadDefaultAgentReader, h as ThreadModelReader, i as a2uiAdapter, j as attachmentLimits } from './index-DpS9P7so.js';
 import { AgentGenui } from './genui/index.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
@@ -354,10 +354,15 @@ interface AgentOptions {
      * per edge, by the author, and never by the model: the same worker is worth waiting for in one
      * orchestrator and worth backgrounding in another, and only the person wiring the edge knows
      * which side of that the user is sitting on.
+     *
+     * `roles` / `ability` gate who may delegate along the edge (the delegate tool's own), e.g.
+     * `{ agent: Helper, roles: ['personal_agent'] }` to let a personal agent's turn delegate.
      */
     handoff?: (Type | {
         agent: Type;
         detached?: boolean;
+        roles?: string[];
+        ability?: string;
     })[];
     /**
      * How much of the thread this agent's turns carry, overriding `AgentModule.forRoot({ history })`.
@@ -994,6 +999,8 @@ declare class ActionProposalController {
 
 /** Called with a proposal the worker just settled (executed, or failed executing). */
 type ActionProposalSettledListener = (proposal: ActionProposal) => void | Promise<void>;
+/** Called with a proposal outcome the worker just wrote to its thread. */
+type ActionProposalAdmittedListener = (outcome: ActionProposalOutcome) => void | Promise<void>;
 declare class ActionProposalWorkerService implements OnModuleInit, OnModuleDestroy {
     private readonly store;
     private readonly options;
@@ -1001,6 +1008,16 @@ declare class ActionProposalWorkerService implements OnModuleInit, OnModuleDestr
     private worker;
     private readonly logger;
     private readonly settledListeners;
+    private readonly admittedListeners;
+    /**
+     * Run `listener` once a settled proposal's outcome is written to its thread by this process's
+     * worker (the thread was free) — what a module uses to CONTINUE a conversation once an action it
+     * proposed ran (a Poppy connect: the next turn goes on with what was asked). Next to
+     * `actionProposalWorker.onAdmitted`; a listener that throws is logged and does not stop the
+     * others. Returns the unsubscribe.
+     */
+    onAdmitted(listener: ActionProposalAdmittedListener): () => void;
+    private admitted;
     /**
      * Run `listener` after every proposal this process's worker settles — how a module relays an
      * outcome somewhere the turn's stream no longer reaches (a text channel's conversation). Next to
@@ -1014,4 +1031,4 @@ declare class ActionProposalWorkerService implements OnModuleInit, OnModuleDestr
     onModuleDestroy(): Promise<void>;
 }
 
-export { AGENT_CHAT_QUEUE, AGENT_METADATA, AGENT_SERVICE, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, ActionProposalController, ActionProposalService, type ActionProposalSettledListener, ActionProposalWorkerService, type AgUiAdapterOptions, AgUiRunHandler, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentProtocolAdapter, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, type AnonymousActorOptions, AnonymousActorResolver, AttachmentsController, ChatQueueService, ConfigController, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, MemoriesController, MessagesController, ModelsController, QueueController, type RequestUserMapper, type ResolvedAiToolOptions, RunNotActiveException, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadPersonaReader, ToolsController, agUiAdapter, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, threadPersona, toolNameFromClass };
+export { AGENT_CHAT_QUEUE, AGENT_METADATA, AGENT_SERVICE, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, type ActionProposalAdmittedListener, ActionProposalController, ActionProposalService, type ActionProposalSettledListener, ActionProposalWorkerService, type AgUiAdapterOptions, AgUiRunHandler, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentProtocolAdapter, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, type AnonymousActorOptions, AnonymousActorResolver, AttachmentsController, ChatQueueService, ConfigController, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, MemoriesController, MessagesController, ModelsController, QueueController, type RequestUserMapper, type ResolvedAiToolOptions, RunNotActiveException, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadPersonaReader, ToolsController, agUiAdapter, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, threadPersona, toolNameFromClass };

package/dist/index.js

@@ -69,7 +69,7 @@ var init_kit = __esm({
 });
 
 // src/agent.module.ts
-import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER14, AGENT_APPROVAL_PORT, AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY7, AGENT_DURABLE_RUNNER, AGENT_MEMORY as AGENT_MEMORY3, AGENT_MODEL as AGENT_MODEL3, AGENT_MODEL_CATALOG as AGENT_MODEL_CATALOG3, AGENT_OPTIONS as AGENT_OPTIONS10, AGENT_PROMPT_CONTRIBUTORS as AGENT_PROMPT_CONTRIBUTORS3, AGENT_QUOTA_PROVIDER as AGENT_QUOTA_PROVIDER3, AGENT_REGISTRY as AGENT_REGISTRY6, AGENT_ROLES_POLICY as AGENT_ROLES_POLICY2, AGENT_RUNNER as AGENT_RUNNER2, AGENT_SINK as AGENT_SINK3, AGENT_SKILLS as AGENT_SKILLS3, AGENT_SKILL_SOURCES as AGENT_SKILL_SOURCES2, AGENT_STORE as AGENT_STORE7, AGENT_TOOL_REGISTRY as AGENT_TOOL_REGISTRY3, AgentRegistry as AgentRegistry6, ClosedRolesPolicy, DefaultRolesPolicy, InMemoryAgentStore, ToolRegistry as ToolRegistry3 } from "@dudousxd/nestjs-agent-core";
+import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER14, AGENT_APPROVAL_PORT, AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY7, AGENT_DURABLE_RUNNER, AGENT_MEMORY as AGENT_MEMORY3, AGENT_MODEL as AGENT_MODEL3, AGENT_MODEL_CATALOG as AGENT_MODEL_CATALOG3, AGENT_OPTIONS as AGENT_OPTIONS10, AGENT_PROMPT_CONTRIBUTORS as AGENT_PROMPT_CONTRIBUTORS3, AGENT_QUOTA_PROVIDER as AGENT_QUOTA_PROVIDER3, AGENT_REGISTRY as AGENT_REGISTRY6, AGENT_ROLES_POLICY as AGENT_ROLES_POLICY2, AGENT_RUNNER as AGENT_RUNNER2, AGENT_SINK as AGENT_SINK3, AGENT_SKILLS as AGENT_SKILLS3, AGENT_SKILL_SOURCES as AGENT_SKILL_SOURCES2, AGENT_STORE as AGENT_STORE7, AGENT_TOOL_REGISTRY as AGENT_TOOL_REGISTRY3, AgentRegistry as AgentRegistry6, ClosedRolesPolicy, DefaultRolesPolicy, InMemoryAgentStore, ToolRegistry as ToolRegistry3, personalAgentGate, personalAgentScopes } from "@dudousxd/nestjs-agent-core";
 import { Global, Logger as Logger8, Module as Module2 } from "@nestjs/common";
 import { DiscoveryModule, ModulesContainer, RouterModule } from "@nestjs/core";
 
@@ -4893,9 +4893,19 @@ var AgentDiscoveryService = class _AgentDiscoveryService {
         this.logger.warn(`Agent "${meta.name}" hands off to ${target.name}, which is not an @Agent \u2014 skipped.`);
         continue;
       }
-      edges.push(detached ? {
+      const roles = typeof entry === "function" ? void 0 : entry.roles;
+      const ability = typeof entry === "function" ? void 0 : entry.ability;
+      edges.push(detached || roles !== void 0 || ability !== void 0 ? {
         agent: targetMeta.name,
-        detached: true
+        ...detached ? {
+          detached: true
+        } : {},
+        ...roles !== void 0 ? {
+          roles
+        } : {},
+        ...ability !== void 0 ? {
+          ability
+        } : {}
       } : targetMeta.name);
     }
     return edges;
@@ -5107,7 +5117,7 @@ var AiToolDiscoveryService = class _AiToolDiscoveryService {
     let delegates = 0;
     for (const definition of this.agents.list()) {
       for (const edge of definition.delegatesTo ?? []) {
-        const { agent: target, detached } = normalizeDelegation2(edge);
+        const { agent: target, detached, roles, ability } = normalizeDelegation2(edge);
         const targetDefinition = this.agents.get(target);
         if (targetDefinition === void 0) {
           throw new Error(`Agent "${definition.name}" hands off to "${target}", which is not a registered @Agent. Declare it as an @Agent provider or fix the reference.`);
@@ -5129,6 +5139,12 @@ var AiToolDiscoveryService = class _AiToolDiscoveryService {
             ...detached ? {
               detached: true
             } : {},
+            ...roles !== void 0 ? {
+              roles
+            } : {},
+            ...ability !== void 0 ? {
+              ability
+            } : {},
             description,
             inputSchema: z.object({
               task: z.string()
@@ -5541,6 +5557,35 @@ var ActionProposalWorkerService = class _ActionProposalWorkerService {
   worker;
   logger = new Logger6(_ActionProposalWorkerService.name);
   settledListeners = /* @__PURE__ */ new Set();
+  admittedListeners = /* @__PURE__ */ new Set();
+  /**
+  * Run `listener` once a settled proposal's outcome is written to its thread by this process's
+  * worker (the thread was free) — what a module uses to CONTINUE a conversation once an action it
+  * proposed ran (a Poppy connect: the next turn goes on with what was asked). Next to
+  * `actionProposalWorker.onAdmitted`; a listener that throws is logged and does not stop the
+  * others. Returns the unsubscribe.
+  */
+  onAdmitted(listener) {
+    this.admittedListeners.add(listener);
+    return () => {
+      this.admittedListeners.delete(listener);
+    };
+  }
+  async admitted(outcome) {
+    const configured = this.options.actionProposalWorker?.onAdmitted;
+    for (const listener of [
+      ...configured ? [
+        configured
+      ] : [],
+      ...this.admittedListeners
+    ]) {
+      try {
+        await listener(outcome);
+      } catch (error) {
+        this.logger.error(error);
+      }
+    }
+  }
   /**
   * Run `listener` after every proposal this process's worker settles — how a module relays an
   * outcome somewhere the turn's stream no longer reaches (a text channel's conversation). Next to
@@ -5584,6 +5629,7 @@ var ActionProposalWorkerService = class _ActionProposalWorkerService {
       workerId: randomUUID(),
       ...this.options.actionProposalWorker,
       onSettled: /* @__PURE__ */ __name((proposal) => this.settled(proposal), "onSettled"),
+      onAdmitted: /* @__PURE__ */ __name((outcome) => this.admitted(outcome), "onAdmitted"),
       executor: new ActionProposalExecutor({
         resolver,
         resolveExecution: /* @__PURE__ */ __name(async (proposal, actor) => {
@@ -6402,6 +6448,13 @@ function forwardingPolicy(wrapper) {
         throw new Error("AgentModule: the AGENT_ROLES_POLICY bound by another module is not ready yet");
       }
       return policy.can(actor, tool);
+    },
+    canOffer(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.canOffer ? policy.canOffer(actor, tool) : policy.can(actor, tool);
     }
   };
 }
@@ -6443,7 +6496,14 @@ function sharedProviders(durable, engine) {
       // drift, and a user would be offered a skill the agent cannot reach. `undefined` when the
       // host configured none — which is what keeps the turn's checkpoint sequence unchanged.
       provide: AGENT_SKILLS3,
-      useFactory: /* @__PURE__ */ __name((options, declared) => resolveSkillsConfig(options.skills, declared), "useFactory"),
+      // Personal agents resolve no skill scope (`personalAgentScopes`): nothing of the app's to load.
+      useFactory: /* @__PURE__ */ __name((options, declared) => {
+        const skills = resolveSkillsConfig(options.skills, declared);
+        return skills === void 0 ? void 0 : {
+          ...skills,
+          scopes: personalAgentScopes(skills.scopes)
+        };
+      }, "useFactory"),
       inject: [
         AGENT_OPTIONS10,
         AGENT_SKILL_SOURCES2
@@ -6453,7 +6513,12 @@ function sharedProviders(durable, engine) {
       // One resolution, shared by the loop's deps and the read-back endpoint: a person has to be
       // shown what the model was shown, and two resolutions would eventually disagree about that.
       provide: AGENT_MEMORY3,
-      useFactory: /* @__PURE__ */ __name((options) => options.memory, "useFactory"),
+      // Personal agents resolve no memory scope (`personalAgentScopes`): under a signed-in Poppy
+      // conversation the actor is the account, and it must neither read nor write its memories.
+      useFactory: /* @__PURE__ */ __name((options) => options.memory === void 0 ? void 0 : {
+        ...options.memory,
+        scopes: personalAgentScopes(options.memory.scopes)
+      }, "useFactory"),
       inject: [
         AGENT_OPTIONS10
       ]
@@ -6467,7 +6532,10 @@ function sharedProviders(durable, engine) {
     },
     {
       provide: AGENT_ROLES_POLICY2,
-      useFactory: /* @__PURE__ */ __name((options, modules) => resolveRolesPolicy(options, modules), "useFactory"),
+      // Personal agents (a Poppy conversation, a Poppy session's MCP token) reach only the tools
+      // written for them, and run only those of the scopes their user granted. A no-op for every
+      // other actor.
+      useFactory: /* @__PURE__ */ __name((options, modules) => personalAgentGate(resolveRolesPolicy(options, modules)), "useFactory"),
       inject: [
         AGENT_OPTIONS10,
         ModulesContainer