@adonis-agora/agent 0.60.1 → 0.62.0

package/dist/providers/agent_provider.js

@@ -1,7 +1,13 @@
 import { pathToFileURL } from 'node:url';
-import { AgentDepsFactory, AgentGenui, AgentRegistry, AgentService, AgentSseEncoder, ALL_AGENTS, AnonymousActorResolver, AttachmentInventoryError, AttachmentRefusedError, ChatQueueError, ChatQueueService, DefaultToolAuthorizer, discoverTools, evaluateGovernanceGate, evaluateOwnership, governanceQueries as governanceQueriesFactories, HumanReplyMismatchError, InlineAgentRunner, InProcessTokenStreamSink, isQuotaProvider, LedgerQuotaProvider, lucidStoreConnection, ModelNotAllowedError, memoryForgetVerdict, offerMemories, offerSkills, PersonaNotFoundError, parseStreamCursor, pricingStores, QuotaBlockedError, REQUESTER_APPROVER, RegenerateNeedsThreadError, RunNotActiveError, registerDelegateTools, registerFunctionalTool, registerToolsFromBarrel, resolveActorResolver, resolvePersonaAlias, ToolRegistry, toApprovalPolicy, toModelCatalog, UnknownAgentError, withActorLabel, withActorLabels, } from '../src/index.js';
+import { personalAgentGate, personalAgentScopes } from '../src/a2a/gate.js';
+import { assertIndependentActionRuntime } from '../src/action-proposal-runtime.js';
+import { ActionProposalService, ActionProposalServiceError, } from '../src/action-proposal-service.js';
+import { validateActionProposalListQuery } from '../src/action-proposal-transitions.js';
+import { assertRunnable, engineOnlyModel } from '../src/engine.js';
+import { ActionProposalExecutor, ActionProposalWorker, AgentDepsFactory, AgentGenui, AgentRegistry, AgentService, AgentSseEncoder, ALL_AGENTS, AnonymousActorResolver, AttachmentInventoryError, AttachmentRefusedError, ChatQueueError, ChatQueueService, DefaultToolAuthorizer, discoverTools, evaluateGovernanceGate, evaluateOwnership, governanceQueries as governanceQueriesFactories, HumanReplyMismatchError, InlineAgentRunner, InProcessTokenStreamSink, isQuotaProvider, LedgerQuotaProvider, lucidStoreConnection, ModelNotAllowedError, memoryForgetVerdict, offerMemories, offerSkills, PersonaNotFoundError, parseStreamCursor, pricingStores, QuotaBlockedError, REQUESTER_APPROVER, RegenerateNeedsThreadError, RunNotActiveError, registerDelegateTools, registerFunctionalTool, registerToolsFromBarrel, resolveActorResolver, resolvePersonaAlias, ToolRegistry, toApprovalPolicy, toModelCatalog, UnknownAgentError, withActorLabel, withActorLabels, } from '../src/index.js';
 import { McpToolImporter } from '../src/mcp-client/index.js';
 import { setTelescopeGovernanceQueries } from '../src/telescope/governance-registry.js';
+import { validateUiCapabilities } from '../src/ui-capabilities.js';
 /** A send's `mode`, or `null` when it names none of the three. `interrupt: true` is `'interrupt'`. */
 function sendMode(body) {
     if (body.mode === undefined) {
@@ -112,11 +118,14 @@ const DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES = [
 export default class AgentProvider {
     app;
     #store = null;
+    #actionProposalWorker = null;
     #sink = null;
     #actorDirectory = null;
     #mcpTools = null;
     /** Whatever was built at boot that may own a schema: the store, the pricing store, the read-model. */
     #schemaOwners = [];
+    /** The engine running the turns instead of the loop (`engine` in the config), when there is one. */
+    #engine;
     constructor(app) {
         this.app = app;
     }
@@ -172,17 +181,32 @@ export default class AgentProvider {
         registerDelegateTools(registry, agents);
         // Generative UI: the catalog's tools, registered like config-level functional tools, and the
         // boot-time catalog bound for injection.
+        let resolveUiCatalog;
         if (config.genui !== undefined) {
             const setup = await config.genui({
                 make: (klass) => this.app.container.make(klass),
             });
+            resolveUiCatalog = async (scope) => {
+                const serverScope = {
+                    ...scope,
+                    ...(scope.actor.tenantRef !== undefined ? { tenant: scope.actor.tenantRef } : {}),
+                };
+                return (await (setup.resolveCatalog?.(serverScope) ?? setup.catalog));
+            };
             for (const tool of setup.tools) {
                 registerFunctionalTool(registry, tool, defaultRoles);
             }
-            this.app.container.bindValue(AgentGenui, new AgentGenui(setup.catalog));
+            this.app.container.bindValue(AgentGenui, new AgentGenui(setup.catalog, setup.resolveCatalog));
         }
         // ── Runtime graph ──
-        const model = await this.#resolveModel(config);
+        // An engine (`engine` in the config) runs the turns instead of the loop: `model` is optional
+        // then, and `durable: true` (the LOOP's durable runner) is refused unless the engine is durable.
+        const engine = typeof config.engine === 'function' ? await config.engine() : config.engine;
+        assertRunnable({ model: config.model, engine, durable: config.durable });
+        this.#engine = engine;
+        const model = config.model === undefined && engine !== undefined
+            ? engineOnlyModel(engine)
+            : await this.#resolveModel(config);
         const store = await this.#resolveStore(config);
         const sink = await this.#resolveSink(config);
         // One budget: `{ limits }` over the usage ledger, or a `QuotaProvider` of your own — reported by
@@ -217,13 +241,19 @@ export default class AgentProvider {
         this.#sink = sink;
         this.#actorDirectory = actorDirectory;
         this.#schemaOwners = [store, pricingStore, governance, sink];
+        const onPresentationError = config.onPresentationError ?? (await this.#logPresentationErrors());
         const factory = new AgentDepsFactory({
+            ...(onPresentationError !== undefined ? { onPresentationError } : {}),
             model,
             store,
             sink,
             rolesPolicy: authorizer,
             registry,
             agents,
+            ...(resolveUiCatalog !== undefined ? { resolveUiCatalog } : {}),
+            ...(config.actionApprovalMode !== undefined
+                ? { actionApprovalMode: config.actionApprovalMode }
+                : {}),
             defaultAgentName: config.defaultAgent?.name ?? 'default',
             ...(config.approvalPolicy !== undefined
                 ? { approvalPolicy: toApprovalPolicy(config.approvalPolicy) }
@@ -236,8 +266,13 @@ export default class AgentProvider {
                 ? { toolTransientRetry: config.toolTransientRetry }
                 : {}),
             ...(config.historyWindow !== undefined ? { historyWindow: config.historyWindow } : {}),
-            ...(config.skills !== undefined ? { skills: config.skills } : {}),
-            ...(config.memory !== undefined ? { memory: config.memory } : {}),
+            // Personal agents (A2A) resolve no memory or skill scope — see `personalAgentScopes`.
+            ...(config.skills !== undefined
+                ? { skills: { ...config.skills, scopes: personalAgentScopes(config.skills.scopes) } }
+                : {}),
+            ...(config.memory !== undefined
+                ? { memory: { ...config.memory, scopes: personalAgentScopes(config.memory.scopes) } }
+                : {}),
             ...(config.inputProcessors !== undefined ? { inputProcessors: config.inputProcessors } : {}),
             ...(config.outputProcessors !== undefined
                 ? { outputProcessors: config.outputProcessors }
@@ -253,12 +288,69 @@ export default class AgentProvider {
             ...(attachmentStaging !== undefined ? { attachments: attachmentStaging } : {}),
             resolveTarget: (message) => service.queuedTarget(message),
         });
-        const runner = config.durable === true
-            ? ((await this.#resolveDurableRunner(factory, store, queue, sink)) ??
-                new InlineAgentRunner(factory, store, queue))
-            : new InlineAgentRunner(factory, store, queue);
+        assertIndependentActionRuntime(config.actionApprovalMode, store, config.backgroundActorResolver, queue.supported);
+        if (config.actionApprovalMode === 'independent') {
+            const executionStore = store;
+            const executor = new ActionProposalExecutor({
+                resolver: config.backgroundActorResolver,
+                resolveExecution: async (proposal) => {
+                    const name = proposal.executionContext?.agentName ?? factory.defaultAgentName();
+                    if (!factory.isAgent(name))
+                        throw new Error(`Action proposal agent no longer exists: ${name}`);
+                    const deps = factory.forAgent(name);
+                    const personaId = proposal.executionContext?.persona;
+                    if (personaId !== undefined && !deps.personas.has(personaId))
+                        throw new Error(`Action proposal persona no longer exists: ${personaId}`);
+                    const persona = personaId === undefined ? undefined : deps.personas.get(personaId);
+                    const allowedTools = persona?.allowedTools === undefined
+                        ? deps.toolAllowList
+                        : deps.toolAllowList === undefined
+                            ? persona.allowedTools
+                            : deps.toolAllowList.filter((tool) => persona.allowedTools.includes(tool));
+                    return {
+                        registry: deps.registry,
+                        rolesPolicy: deps.rolesPolicy,
+                        ...(onPresentationError !== undefined ? { onPresentationError } : {}),
+                        ...(resolveUiCatalog !== undefined ? { resolveUiCatalog } : {}),
+                        ...(persona !== undefined ? { persona } : {}),
+                        ...(allowedTools !== undefined ? { allowedTools } : {}),
+                    };
+                },
+            });
+            this.#actionProposalWorker = new ActionProposalWorker({
+                store: executionStore,
+                executor,
+                workerId: `agora-${crypto.randomUUID()}`,
+                ...config.actionProposalWorker,
+                onError: (error) => console.error('[@adonis-agora/agent] Action proposal worker failed', error),
+            });
+        }
+        if (this.#actionProposalWorker)
+            this.app.container.bindValue(ActionProposalWorker, this.#actionProposalWorker);
+        const runner = engine !== undefined
+            ? await engine.createRunner({
+                factory,
+                store,
+                sink,
+                registry,
+                queue,
+                make: (binding) => this.app.container.make(binding),
+                ...this.#appKey(),
+            })
+            : config.durable === true
+                ? ((await this.#resolveDurableRunner(factory, store, queue, sink)) ??
+                    new InlineAgentRunner(factory, store, queue))
+                : new InlineAgentRunner(factory, store, queue);
         const service = new AgentService(runner, store, factory, {
             queue,
+            ...(config.backgroundActorResolver !== undefined
+                ? { backgroundActorResolver: config.backgroundActorResolver }
+                : {}),
+            ...(config.actionApprovalMode === 'independent'
+                ? {
+                    actionProposals: new ActionProposalService(store, factory.forAgent().approvalPolicy, config.actionProposalText),
+                }
+                : {}),
             // No `models` → the catalog the model provider carries (`aiSdkModels`), else none.
             ...(config.models !== undefined
                 ? { models: toModelCatalog(config.models) }
@@ -304,8 +396,13 @@ export default class AgentProvider {
                 console.warn('[@adonis-agora/agent] Could not provision the agent tables at startup; it will be retried on first use.', error);
             }
         }
+        this.#actionProposalWorker?.start();
     }
     async shutdown() {
+        await this.#engine?.shutdown?.();
+        this.#engine = undefined;
+        await this.#actionProposalWorker?.stop();
+        this.#actionProposalWorker = null;
         // The Lucid store shares the app's `db` (it owns no connection to close); the in-process sink
         // holds only per-run buffers that GC with the provider. Drop refs so a hot reload starts clean.
         // An MCP client DOES own a connection — a spawned stdio child or an HTTP session — so it closes.
@@ -335,6 +432,14 @@ export default class AgentProvider {
         await importer.start();
     }
     // ── resolution helpers ────────────────────────────────────────────────────
+    /** The app's `APP_KEY` (a `Secret` in `config/app.ts`), for an engine that signs something. */
+    #appKey() {
+        const raw = this.app.config.get('app.appKey', undefined);
+        const released = typeof raw?.release === 'function'
+            ? raw.release()
+            : raw;
+        return typeof released === 'string' && released.length > 0 ? { appKey: released } : {};
+    }
     async #resolveModel(config) {
         const model = config.model;
         if (typeof model === 'function') {
@@ -429,7 +534,9 @@ export default class AgentProvider {
         return typeof staging === 'function' ? staging({ app: this.app, agentStore }) : staging;
     }
     #resolveAuthorizer(config, defaultRoles) {
-        return (config.authorizer ??
+        // Whatever the app configured, personal agents (A2A) reach only tools that name them — see
+        // `personalAgentGate`. A no-op for every other actor.
+        return personalAgentGate(config.authorizer ??
             config.rolesPolicy ??
             new DefaultToolAuthorizer(defaultRoles, { emptyRoles: config.emptyRoles ?? 'allow' }));
     }
@@ -522,6 +629,17 @@ export default class AgentProvider {
             if (mode === null) {
                 return ctx.response.badRequest({ message: "mode must be 'auto', 'queue' or 'interrupt'" });
             }
+            let uiCapabilities;
+            try {
+                if (body.uiCapabilities !== undefined)
+                    uiCapabilities = validateUiCapabilities(body.uiCapabilities);
+            }
+            catch {
+                return ctx.response.badRequest({
+                    message: 'uiCapabilities must be valid UI capabilities',
+                    code: 'invalid_ui_capabilities',
+                });
+            }
             let started;
             try {
                 started = await service.send({
@@ -538,10 +656,13 @@ export default class AgentProvider {
                         ? { personaId: body.persona }
                         : {}),
                     ...(body.pageContext !== undefined ? { pageContext: body.pageContext } : {}),
+                    ...(uiCapabilities !== undefined ? { uiCapabilities } : {}),
                     ...(refs.length > 0 ? { attachments: refs } : {}),
                 });
             }
             catch (error) {
+                if (error instanceof ActionProposalServiceError)
+                    return ctx.response.status(error.status).json({ message: error.message });
                 if (error instanceof AttachmentRefusedError) {
                     return ctx.response.status(error.status).json({ message: error.message });
                 }
@@ -566,6 +687,8 @@ export default class AgentProvider {
                 }
                 throw error;
             }
+            if ('proposalDecision' in started)
+                return ctx.response.json(started);
             if (started.queued === true) {
                 // The thread already has a turn running: the message waits in its queue (`202`, JSON — no
                 // stream). `runId` is there when it started straight away; attach to it with `GET …/stream`.
@@ -612,7 +735,9 @@ export default class AgentProvider {
         // 3b. Protocol adapters (`adapters` in the config): other wire protocols over the same runs —
         // e.g. `agUiAdapter()` mounts `POST <path>/ag-ui`. Each gets the checks these routes use, so an
         // adapter cannot be more permissive than the native routes by forgetting one.
-        for (const adapter of config.adapters ?? []) {
+        // An engine's own routes (the MCP endpoint OpenCode reaches the app's tools through) mount the
+        // same way, after the configured adapters.
+        for (const adapter of [...(config.adapters ?? []), ...(this.#engine?.adapters?.() ?? [])]) {
             await adapter.mount({
                 service,
                 defaultAgentName,
@@ -843,6 +968,52 @@ export default class AgentProvider {
                 return;
             return ctx.response.json(service.personaCatalog());
         });
+        const proposalResponse = async (ctx, action) => {
+            try {
+                return ctx.response.json(await action());
+            }
+            catch (error) {
+                if (error instanceof ActionProposalServiceError)
+                    return ctx.response.status(error.status).json({ message: error.message });
+                throw error;
+            }
+        };
+        router.get(p('threads/:id/action-proposals'), async (ctx) => {
+            const actor = await this.#resolveActor(ctx, actorResolver);
+            if (!actor)
+                return;
+            return proposalResponse(ctx, async () => {
+                let after;
+                const cursor = ctx.request.input('after');
+                if (cursor !== undefined) {
+                    try {
+                        if (typeof cursor !== 'string')
+                            throw new Error('cursor');
+                        after = JSON.parse(cursor);
+                        validateActionProposalListQuery({ after });
+                    }
+                    catch {
+                        throw new ActionProposalServiceError(400, 'Invalid action proposal cursor');
+                    }
+                }
+                const page = await service.listActionProposalsPage(actor, ctx.params.id, after);
+                if (page.next)
+                    ctx.response.header('X-Action-Proposals-Next', encodeURIComponent(JSON.stringify(page.next)));
+                ctx.response.header('Access-Control-Expose-Headers', 'X-Action-Proposals-Next');
+                return page.items;
+            });
+        });
+        for (const [route, decision] of [
+            ['approve', 'approved'],
+            ['reject', 'rejected'],
+        ]) {
+            router.post(p(`threads/:id/action-proposals/:proposalId/${route}`), async (ctx) => {
+                const actor = await this.#resolveActor(ctx, actorResolver);
+                if (!actor)
+                    return;
+                return proposalResponse(ctx, () => service.decideActionProposal(actor, ctx.params.id, ctx.params.proposalId, decision, ctx.request.body() ?? {}));
+            });
+        }
         // 8. GET /agent/threads/:id — detail or null. Authenticated + owner-scoped (a caller reads only its
         // own threads, unless governance-privileged).
         router.get(p('threads/:id'), async (ctx) => {
@@ -1654,6 +1825,15 @@ export default class AgentProvider {
         const owner = await service.threadOwner(threadId);
         return this.#assertOwner(ctx, actor, owner, 'thread', governanceAuthorize);
     }
+    /** The default `onPresentationError`: a warning on the app's logger (none bound → `undefined`). */
+    async #logPresentationErrors() {
+        if (!this.app.container.hasBinding('logger'))
+            return undefined;
+        const logger = await this.app.container.make('logger');
+        return (error, details) => {
+            logger.warn({ err: error, ...details }, 'Tool presentation failed after successful execution');
+        };
+    }
     #conflictOnMismatch(ctx, error) {
         // The run the decision was for has ended: nothing is waiting for it (`409 run_not_active`).
         if (error instanceof RunNotActiveError) {
@@ -1670,6 +1850,10 @@ export default class AgentProvider {
      * `POST <path>/chat` does. `false` for an error that is none of those (the caller rethrows).
      */
     #refuseSend(ctx, error) {
+        if (error instanceof ActionProposalServiceError) {
+            ctx.response.status(error.status).json({ message: error.message });
+            return true;
+        }
         if (error instanceof AttachmentRefusedError) {
             ctx.response.status(error.status).json({ message: error.message });
             return true;