@beignet/agent-auth-better-auth 0.0.35 → 0.0.36

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @beignet/agent-auth-better-auth
 
+## 0.0.36
+
+### Patch Changes
+
+- 5c7f6bb: Harden agent capability execution with lazy Better Auth executors, runtime required-constraint checks, validated lifecycle data, and adapter test utilities.
+
 ## 0.0.35
 
 ### Patch Changes

package/README.md

@@ -133,18 +133,53 @@ export const auth = betterAuth({
 });
 ```
 
+If auth initialization and server composition depend on each other, provide a
+lazy executor instead of building an app-owned proxy:
+
+```typescript
+import { agentCapabilityRegistry } from "@/lib/agent-capability-registry";
+
+const agentCapabilities = createBetterAuthAgentCapabilityAdapter({
+  registry: agentCapabilityRegistry,
+  executor: () =>
+    import("@/server/agent-capabilities").then(
+      ({ agentCapabilityExecutor }) => agentCapabilityExecutor,
+    ),
+  principal({ agentSession }) {
+    if (!agentSession.userId) {
+      throw new APIError("FORBIDDEN", {
+        message: "A delegated user is required.",
+      });
+    }
+    return { agentId: agentSession.agentId, userId: agentSession.userId };
+  },
+});
+```
+
+Keep the transport-safe registry in a module that does not import server
+composition; only the executor needs the dynamic server import.
+The adapter loads the executor on the first execution and memoizes the first
+successful resolution for the lifetime of the warm module instance. Concurrent
+executions share initialization; a failed resolution is not cached.
+
 Zod schemas are converted to protocol JSON Schema by default. Pass a Beignet
 `SchemaConverter` through `schemaConverter` when using another Standard Schema
 library. Conversion runs at adapter creation so unsupported schemas fail during
 boot instead of on the first agent request.
 
 Agent Auth authorizes grant constraints against raw arguments before invoking
-the adapter. Beignet therefore rejects an invocation when schema validation
-changes a field constrained by the active grant. Keep constrained identifiers
-and amounts non-transforming; normalization remains available for unconstrained
-fields. The adapter snapshots active constrained values before validation,
-parses once, and checks the exact parsed input subsequently used for context
-construction and execution.
+the adapter. The adapter also verifies at execution time that the active grant
+still contains every field currently declared in `requiredConstraints`. This
+prevents older broad grants from remaining usable after capability metadata is
+tightened. Revoke or migrate stale grants so agents can request replacement
+grants with the newly required scope.
+
+Beignet also rejects an invocation when schema validation changes a field
+constrained by the active grant. Keep constrained identifiers and amounts
+non-transforming; normalization remains available for unconstrained fields.
+The adapter snapshots active constrained values before validation, parses once,
+and checks the exact parsed input subsequently used for context construction
+and execution.
 
 This bridge intentionally uses Agent Auth's default capability execution
 endpoint. It does not expose custom capability `location` metadata because
@@ -165,6 +200,24 @@ Only synchronous request/response capability results are supported in this
 release. Agent Auth asynchronous polling and streaming results remain
 transport-owned and are not produced by the Beignet executor.
 
+## Testing
+
+Use the adapter testing subpath to exercise `onExecute` without manufacturing
+Better Auth's internal endpoint context:
+
+```typescript
+import { createBetterAuthAgentCapabilityTestContext } from
+  "@beignet/agent-auth-better-auth/testing";
+
+await agentCapabilities.onExecute?.(
+  createBetterAuthAgentCapabilityTestContext({
+    capability: "issues.create",
+    arguments: { workspaceId: "workspace_1", title: "Fix login" },
+    constraints: { workspaceId: "workspace_1" },
+  }),
+);
+```
+
 ## Agent skills
 
 This package ships a TanStack Intent skill:

package/dist/index.d.ts

@@ -16,9 +16,12 @@ export declare class BetterAuthAgentCapabilityAdapterError extends Error {
 /** Options for adapting a Beignet registry to Better Auth Agent Auth. */
 export interface CreateBetterAuthAgentCapabilityAdapterOptions<Definitions extends readonly AnyAgentCapabilityDef[]> {
     registry: AgentCapabilityRegistry<Definitions>;
-    executor: AgentCapabilityExecutor<AgentCapabilityPrincipal<Definitions[number]>, Definitions>;
+    /** Direct executor or lazy factory memoized after its first successful load. */
+    executor: AgentCapabilityExecutor<AgentCapabilityPrincipal<Definitions[number]>, Definitions> | (() => MaybePromise<AgentCapabilityExecutor<AgentCapabilityPrincipal<Definitions[number]>, Definitions>>);
     principal(context: Parameters<NonNullable<AgentAuthOptions["onExecute"]>>[0]): MaybePromise<AgentCapabilityPrincipal<Definitions[number]>>;
+    /** Converter used to expose Standard Schema inputs and outputs as JSON Schema. */
     schemaConverter?: SchemaConverter;
+    /** Transport metadata keyed by names in the Beignet capability registry. */
     metadata?: Partial<Record<Definitions[number]["name"], BetterAuthAgentCapabilityMetadata>>;
 }
 /** Better Auth options produced from a Beignet capability registry. */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,wBAAwB,EACxB,uBAAuB,EACvB,qBAAqB,EACrB,YAAY,EACb,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,KAAK,gBAAgB,EAErB,KAAK,UAAU,EAChB,MAAM,yBAAyB,CAAC;AAGjC,iFAAiF;AACjF,MAAM,MAAM,iCAAiC,GAAG,IAAI,CAClD,UAAU,EACV,kBAAkB,GAAG,UAAU,GAAG,qBAAqB,CACxD,CAAC;AAEF,iEAAiE;AACjE,qBAAa,qCAAsC,SAAQ,KAAK;IAC9D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEtB,IAAI,EAAE;QAChB,cAAc,EAAE,MAAM,CAAC;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAMF;AAED,yEAAyE;AACzE,MAAM,WAAW,6CAA6C,CAC5D,WAAW,SAAS,SAAS,qBAAqB,EAAE;IAEpD,QAAQ,EAAE,uBAAuB,CAAC,WAAW,CAAC,CAAC;IAC/C,QAAQ,EAAE,uBAAuB,CAC/B,wBAAwB,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,EAC7C,WAAW,CACZ,CAAC;IACF,SAAS,CACP,OAAO,EAAE,UAAU,CAAC,WAAW,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACjE,YAAY,CAAC,wBAAwB,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC/D,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,EAAE,OAAO,CAChB,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,EAAE,iCAAiC,CAAC,CACvE,CAAC;CACH;AAED,uEAAuE;AACvE,MAAM,MAAM,gCAAgC,GAAG,IAAI,CACjD,gBAAgB,EAChB,cAAc,GAAG,WAAW,CAC7B,CAAC;AAmIF;;;GAGG;AACH,wBAAgB,sCAAsC,CACpD,KAAK,CAAC,WAAW,SAAS,SAAS,qBAAqB,EAAE,EAE1D,OAAO,EAAE,6CAA6C,CAAC,WAAW,CAAC,GAClE,gCAAgC,CAgDlC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,wBAAwB,EACxB,uBAAuB,EACvB,qBAAqB,EACrB,YAAY,EACb,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,KAAK,gBAAgB,EAErB,KAAK,UAAU,EAChB,MAAM,yBAAyB,CAAC;AAGjC,iFAAiF;AACjF,MAAM,MAAM,iCAAiC,GAAG,IAAI,CAClD,UAAU,EACV,kBAAkB,GAAG,UAAU,GAAG,qBAAqB,CACxD,CAAC;AAEF,iEAAiE;AACjE,qBAAa,qCAAsC,SAAQ,KAAK;IAC9D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEtB,IAAI,EAAE;QAChB,cAAc,EAAE,MAAM,CAAC;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAMF;AAED,yEAAyE;AACzE,MAAM,WAAW,6CAA6C,CAC5D,WAAW,SAAS,SAAS,qBAAqB,EAAE;IAEpD,QAAQ,EAAE,uBAAuB,CAAC,WAAW,CAAC,CAAC;IAC/C,gFAAgF;IAChF,QAAQ,EACJ,uBAAuB,CACrB,wBAAwB,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,EAC7C,WAAW,CACZ,GACD,CAAC,MAAM,YAAY,CACjB,uBAAuB,CACrB,wBAAwB,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,EAC7C,WAAW,CACZ,CACF,CAAC,CAAC;IACP,SAAS,CACP,OAAO,EAAE,UAAU,CAAC,WAAW,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACjE,YAAY,CAAC,wBAAwB,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC/D,kFAAkF;IAClF,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAChB,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,EAAE,iCAAiC,CAAC,CACvE,CAAC;CACH;AAED,uEAAuE;AACvE,MAAM,MAAM,gCAAgC,GAAG,IAAI,CACjD,gBAAgB,EAChB,cAAc,GAAG,WAAW,CAC7B,CAAC;AAyLF;;;GAGG;AACH,wBAAgB,sCAAsC,CACpD,KAAK,CAAC,WAAW,SAAS,SAAS,qBAAqB,EAAE,EAE1D,OAAO,EAAE,6CAA6C,CAAC,WAAW,CAAC,GAClE,gCAAgC,CA0DlC"}

package/dist/index.js

@@ -99,6 +99,33 @@ function snapshotConstrainedInput(args) {
         : undefined;
     return Object.fromEntries(Object.keys(args.constraints).map((field) => [field, rawInput?.[field]]));
 }
+function assertGrantHasRequiredConstraints(args) {
+    const requiredConstraints = args.capability?.requiredConstraints ?? [];
+    if (requiredConstraints.length === 0)
+        return;
+    const missing = requiredConstraints.filter((field) => !args.constraints || !Object.hasOwn(args.constraints, field));
+    if (missing.length === 0)
+        return;
+    throw agentError("FORBIDDEN", AGENT_AUTH_ERROR_CODES.CONSTRAINT_VIOLATED, `The active grant for capability "${args.capability?.name}" is missing required constraints: ${missing.join(", ")}. Request a new constrained grant.`);
+}
+function createExecutorResolver(source) {
+    if (typeof source !== "function") {
+        return async () => source;
+    }
+    let pending;
+    return () => {
+        if (pending)
+            return pending;
+        const resolution = Promise.resolve().then(source);
+        const guarded = resolution.catch((error) => {
+            if (pending === guarded)
+                pending = undefined;
+            throw error;
+        });
+        pending = guarded;
+        return pending;
+    };
+}
 /**
  * Convert a Beignet capability registry and executor into options accepted by
  * Better Auth's `agentAuth(...)` plugin.
@@ -122,18 +149,26 @@ export function createBetterAuthAgentCapabilityAdapter(options) {
         }),
         ...options.metadata?.[capability.name],
     }));
+    const capabilitiesByName = new Map(capabilities.map((capability) => [capability.name, capability]));
+    const resolveExecutor = createExecutorResolver(options.executor);
     return {
         capabilities,
         async onExecute(context) {
             try {
+                assertGrantHasRequiredConstraints({
+                    capability: capabilitiesByName.get(context.capability),
+                    constraints: context.grant.constraints,
+                });
                 const rawInput = context.arguments ?? {};
                 const constrainedInput = snapshotConstrainedInput({
                     constraints: context.grant.constraints,
                     rawInput,
                 });
-                return await options.executor.executeDynamic({
+                const principal = await options.principal(context);
+                const executor = await resolveExecutor();
+                return await executor.executeDynamic({
                     name: context.capability,
-                    principal: await options.principal(context),
+                    principal,
                     input: rawInput,
                     authorize({ input }) {
                         assertConstrainedFieldsAreStable({

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/testing.d.ts

@@ -0,0 +1,29 @@
+import type { AgentAuthOptions } from "@better-auth/agent-auth";
+/** Better Auth execution context accepted by an Agent Auth adapter. */
+export type BetterAuthAgentCapabilityTestContext = Parameters<NonNullable<AgentAuthOptions["onExecute"]>>[0];
+/** Options for a minimal Better Auth Agent Auth execution context. */
+export interface CreateBetterAuthAgentCapabilityTestContextOptions {
+    /** Capability name presented to the adapter. */
+    capability?: string;
+    /** Raw capability arguments presented by Agent Auth. */
+    arguments?: Record<string, unknown>;
+    /** Constraints attached to the active grant. */
+    constraints?: BetterAuthAgentCapabilityTestContext["grant"]["constraints"];
+    /** Verified agent identifier. */
+    agentId?: string;
+    /** Represented user identifier, or null for an autonomous agent. */
+    userId?: string | null;
+    /** Complete capability definition override for advanced adapter tests. */
+    capabilityDef?: BetterAuthAgentCapabilityTestContext["capabilityDef"];
+    /** Agent session fields merged over the generated session. */
+    agentSession?: Partial<BetterAuthAgentCapabilityTestContext["agentSession"]>;
+    /** Grant fields merged over the generated active grant. */
+    grant?: Partial<BetterAuthAgentCapabilityTestContext["grant"]>;
+    /** Better Auth endpoint context override. */
+    ctx?: BetterAuthAgentCapabilityTestContext["ctx"];
+    /** Grant revocation callback override. */
+    revokeGrant?: BetterAuthAgentCapabilityTestContext["revokeGrant"];
+}
+/** Create a typed execution context for adapter unit tests. */
+export declare function createBetterAuthAgentCapabilityTestContext(options?: CreateBetterAuthAgentCapabilityTestContextOptions): BetterAuthAgentCapabilityTestContext;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,uEAAuE;AACvE,MAAM,MAAM,oCAAoC,GAAG,UAAU,CAC3D,WAAW,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAC3C,CAAC,CAAC,CAAC,CAAC;AAEL,sEAAsE;AACtE,MAAM,WAAW,iDAAiD;IAChE,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,gDAAgD;IAChD,WAAW,CAAC,EAAE,oCAAoC,CAAC,OAAO,CAAC,CAAC,aAAa,CAAC,CAAC;IAC3E,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,oCAAoC,CAAC,eAAe,CAAC,CAAC;IACtE,8DAA8D;IAC9D,YAAY,CAAC,EAAE,OAAO,CAAC,oCAAoC,CAAC,cAAc,CAAC,CAAC,CAAC;IAC7E,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,CAAC,oCAAoC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/D,6CAA6C;IAC7C,GAAG,CAAC,EAAE,oCAAoC,CAAC,KAAK,CAAC,CAAC;IAClD,0CAA0C;IAC1C,WAAW,CAAC,EAAE,oCAAoC,CAAC,aAAa,CAAC,CAAC;CACnE;AAED,+DAA+D;AAC/D,wBAAgB,0CAA0C,CACxD,OAAO,GAAE,iDAAsD,GAC9D,oCAAoC,CAyDtC"}

package/dist/testing.js

@@ -0,0 +1,59 @@
+/** Create a typed execution context for adapter unit tests. */
+export function createBetterAuthAgentCapabilityTestContext(options = {}) {
+    const capability = options.capability ?? "capability.test";
+    const agentId = options.agentId ?? "agent_test";
+    const userId = options.userId === undefined ? "user_test" : options.userId;
+    const now = new Date("2026-01-01T00:00:00.000Z");
+    const capabilityDef = options.capabilityDef ?? {
+        name: capability,
+        description: `Test capability ${capability}`,
+        input: { type: "object" },
+        output: { type: "object" },
+    };
+    const grant = {
+        id: "grant_test",
+        agentId,
+        capability,
+        constraints: options.constraints ?? null,
+        grantedBy: userId,
+        deniedBy: null,
+        reason: null,
+        expiresAt: null,
+        status: "active",
+        createdAt: now,
+        updatedAt: now,
+        ...options.grant,
+    };
+    const agentSession = {
+        type: "delegated",
+        agentId,
+        userId,
+        agent: {
+            id: agentId,
+            name: "Test agent",
+            mode: "delegated",
+            capabilityGrants: [grant],
+            hostId: "host_test",
+            createdAt: now,
+            activatedAt: now,
+            metadata: null,
+        },
+        host: null,
+        user: {
+            id: userId ?? `agent-user:${agentId}`,
+            name: "Test user",
+            email: "agent-test@example.test",
+        },
+        ...options.agentSession,
+    };
+    return {
+        ctx: options.ctx ?? {},
+        capability,
+        capabilityDef,
+        arguments: options.arguments,
+        agentSession,
+        grant,
+        revokeGrant: options.revokeGrant ?? (async () => { }),
+    };
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AA+BA,+DAA+D;AAC/D,MAAM,UAAU,0CAA0C,CACxD,UAA6D,EAAE;IAE/D,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,iBAAiB,CAAC;IAC3D,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,YAAY,CAAC;IAChD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IAC3E,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,0BAA0B,CAAC,CAAC;IACjD,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI;QAC7C,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,mBAAmB,UAAU,EAAE;QAC5C,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QACzB,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;KAC3B,CAAC;IACF,MAAM,KAAK,GAAG;QACZ,EAAE,EAAE,YAAY;QAChB,OAAO;QACP,UAAU;QACV,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;QACxC,SAAS,EAAE,MAAM;QACjB,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,IAAI;QACZ,SAAS,EAAE,IAAI;QACf,MAAM,EAAE,QAAiB;QACzB,SAAS,EAAE,GAAG;QACd,SAAS,EAAE,GAAG;QACd,GAAG,OAAO,CAAC,KAAK;KACjB,CAAC;IACF,MAAM,YAAY,GAAG;QACnB,IAAI,EAAE,WAAoB;QAC1B,OAAO;QACP,MAAM;QACN,KAAK,EAAE;YACL,EAAE,EAAE,OAAO;YACX,IAAI,EAAE,YAAY;YAClB,IAAI,EAAE,WAAoB;YAC1B,gBAAgB,EAAE,CAAC,KAAK,CAAC;YACzB,MAAM,EAAE,WAAW;YACnB,SAAS,EAAE,GAAG;YACd,WAAW,EAAE,GAAG;YAChB,QAAQ,EAAE,IAAI;SACf;QACD,IAAI,EAAE,IAAI;QACV,IAAI,EAAE;YACJ,EAAE,EAAE,MAAM,IAAI,cAAc,OAAO,EAAE;YACrC,IAAI,EAAE,WAAW;YACjB,KAAK,EAAE,yBAAyB;SACjC;QACD,GAAG,OAAO,CAAC,YAAY;KACxB,CAAC;IAEF,OAAO;QACL,GAAG,EAAE,OAAO,CAAC,GAAG,IAAK,EAAkD;QACvE,UAAU;QACV,aAAa;QACb,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,YAAY;QACZ,KAAK;QACL,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,CAAC,KAAK,IAAI,EAAE,GAAE,CAAC,CAAC;KACrD,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beignet/agent-auth-better-auth",
-  "version": "0.0.35",
+  "version": "0.0.36",
   "type": "module",
   "description": "Better Auth Agent Auth adapter for Beignet agent capabilities",
   "main": "./dist/index.js",
@@ -9,6 +9,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
     }
   },
   "files": [

package/skills/agent-capabilities/SKILL.md

@@ -29,11 +29,21 @@ approval strength, required constraints, and grant TTL in the adapter's typed
 bypass the bridge and must implement Agent Auth verification, grant enforcement,
 Beignet execution, and output validation independently.
 
+Pass an executor factory when auth and server modules depend on each other.
+Keep the registry in an import-safe module that does not import server
+composition, then dynamically import only the executor.
+The adapter resolves it on first execution, shares concurrent initialization,
+memoizes success per warm module instance, and retries after initialization
+failure.
+
 Grant constraints are checked by Agent Auth against raw arguments. Do not
 transform constrained fields such as tenant IDs, resource IDs, or amounts in
 the capability input schema. The adapter snapshots active constrained values
 before its single validation pass and rejects executions where validation
-changes one; normalization is fine for unconstrained fields.
+changes one; normalization is fine for unconstrained fields. The adapter also
+rejects active grants missing any currently required constraint. Revoke or
+migrate stale grants after tightening capability metadata so agents can request
+replacement scoped grants.
 
 Better Auth owns registration, JWT verification, grants, constraints,
 approval, and protocol persistence. Beignet owns validation, context, use-case
@@ -45,5 +55,9 @@ to return to the agent. AppError codes are preserved by individual and batch
 execution; only individual execution carries the AppError HTTP status.
 
 Test malformed inputs, missing tenant membership, authorization denial,
-output validation, and successful query/command execution. Do not record raw
-principal data, arguments, or results in instrumentation.
+output validation, stale broad grants, and successful query/command execution.
+Use `createBetterAuthAgentCapabilityTestContext(...)` from
+`@beignet/agent-auth-better-auth/testing` instead of casting Better Auth
+execution contexts. Completion hooks receive validated input/output and error
+hooks receive validated input only when available. Do not record raw principal
+data, arguments, or results in instrumentation.

package/src/index.ts

@@ -47,14 +47,24 @@ export interface CreateBetterAuthAgentCapabilityAdapterOptions<
   Definitions extends readonly AnyAgentCapabilityDef[],
 > {
   registry: AgentCapabilityRegistry<Definitions>;
-  executor: AgentCapabilityExecutor<
-    AgentCapabilityPrincipal<Definitions[number]>,
-    Definitions
-  >;
+  /** Direct executor or lazy factory memoized after its first successful load. */
+  executor:
+    | AgentCapabilityExecutor<
+        AgentCapabilityPrincipal<Definitions[number]>,
+        Definitions
+      >
+    | (() => MaybePromise<
+        AgentCapabilityExecutor<
+          AgentCapabilityPrincipal<Definitions[number]>,
+          Definitions
+        >
+      >);
   principal(
     context: Parameters<NonNullable<AgentAuthOptions["onExecute"]>>[0],
   ): MaybePromise<AgentCapabilityPrincipal<Definitions[number]>>;
+  /** Converter used to expose Standard Schema inputs and outputs as JSON Schema. */
   schemaConverter?: SchemaConverter;
+  /** Transport metadata keyed by names in the Beignet capability registry. */
   metadata?: Partial<
     Record<Definitions[number]["name"], BetterAuthAgentCapabilityMetadata>
   >;
@@ -195,6 +205,60 @@ function snapshotConstrainedInput(args: {
   );
 }
 
+function assertGrantHasRequiredConstraints(args: {
+  capability: Capability | undefined;
+  constraints: Record<string, unknown> | null | undefined;
+}): void {
+  const requiredConstraints = args.capability?.requiredConstraints ?? [];
+  if (requiredConstraints.length === 0) return;
+
+  const missing = requiredConstraints.filter(
+    (field) => !args.constraints || !Object.hasOwn(args.constraints, field),
+  );
+  if (missing.length === 0) return;
+
+  throw agentError(
+    "FORBIDDEN",
+    AGENT_AUTH_ERROR_CODES.CONSTRAINT_VIOLATED,
+    `The active grant for capability "${args.capability?.name}" is missing required constraints: ${missing.join(", ")}. Request a new constrained grant.`,
+  );
+}
+
+function createExecutorResolver<
+  Definitions extends readonly AnyAgentCapabilityDef[],
+>(
+  source: CreateBetterAuthAgentCapabilityAdapterOptions<Definitions>["executor"],
+): () => Promise<
+  AgentCapabilityExecutor<
+    AgentCapabilityPrincipal<Definitions[number]>,
+    Definitions
+  >
+> {
+  if (typeof source !== "function") {
+    return async () => source;
+  }
+
+  let pending:
+    | Promise<
+        AgentCapabilityExecutor<
+          AgentCapabilityPrincipal<Definitions[number]>,
+          Definitions
+        >
+      >
+    | undefined;
+
+  return () => {
+    if (pending) return pending;
+    const resolution = Promise.resolve().then(source);
+    const guarded = resolution.catch((error) => {
+      if (pending === guarded) pending = undefined;
+      throw error;
+    });
+    pending = guarded;
+    return pending;
+  };
+}
+
 /**
  * Convert a Beignet capability registry and executor into options accepted by
  * Better Auth's `agentAuth(...)` plugin.
@@ -224,19 +288,29 @@ export function createBetterAuthAgentCapabilityAdapter<
       ...options.metadata?.[capability.name as Definitions[number]["name"]],
     }),
   );
+  const capabilitiesByName = new Map(
+    capabilities.map((capability) => [capability.name, capability]),
+  );
+  const resolveExecutor = createExecutorResolver(options.executor);
 
   return {
     capabilities,
     async onExecute(context) {
       try {
+        assertGrantHasRequiredConstraints({
+          capability: capabilitiesByName.get(context.capability),
+          constraints: context.grant.constraints,
+        });
         const rawInput = context.arguments ?? {};
         const constrainedInput = snapshotConstrainedInput({
           constraints: context.grant.constraints,
           rawInput,
         });
-        return await options.executor.executeDynamic({
+        const principal = await options.principal(context);
+        const executor = await resolveExecutor();
+        return await executor.executeDynamic({
           name: context.capability,
-          principal: await options.principal(context),
+          principal,
           input: rawInput,
           authorize({ input }) {
             assertConstrainedFieldsAreStable({

package/src/testing.ts

@@ -0,0 +1,92 @@
+import type { AgentAuthOptions } from "@better-auth/agent-auth";
+
+/** Better Auth execution context accepted by an Agent Auth adapter. */
+export type BetterAuthAgentCapabilityTestContext = Parameters<
+  NonNullable<AgentAuthOptions["onExecute"]>
+>[0];
+
+/** Options for a minimal Better Auth Agent Auth execution context. */
+export interface CreateBetterAuthAgentCapabilityTestContextOptions {
+  /** Capability name presented to the adapter. */
+  capability?: string;
+  /** Raw capability arguments presented by Agent Auth. */
+  arguments?: Record<string, unknown>;
+  /** Constraints attached to the active grant. */
+  constraints?: BetterAuthAgentCapabilityTestContext["grant"]["constraints"];
+  /** Verified agent identifier. */
+  agentId?: string;
+  /** Represented user identifier, or null for an autonomous agent. */
+  userId?: string | null;
+  /** Complete capability definition override for advanced adapter tests. */
+  capabilityDef?: BetterAuthAgentCapabilityTestContext["capabilityDef"];
+  /** Agent session fields merged over the generated session. */
+  agentSession?: Partial<BetterAuthAgentCapabilityTestContext["agentSession"]>;
+  /** Grant fields merged over the generated active grant. */
+  grant?: Partial<BetterAuthAgentCapabilityTestContext["grant"]>;
+  /** Better Auth endpoint context override. */
+  ctx?: BetterAuthAgentCapabilityTestContext["ctx"];
+  /** Grant revocation callback override. */
+  revokeGrant?: BetterAuthAgentCapabilityTestContext["revokeGrant"];
+}
+
+/** Create a typed execution context for adapter unit tests. */
+export function createBetterAuthAgentCapabilityTestContext(
+  options: CreateBetterAuthAgentCapabilityTestContextOptions = {},
+): BetterAuthAgentCapabilityTestContext {
+  const capability = options.capability ?? "capability.test";
+  const agentId = options.agentId ?? "agent_test";
+  const userId = options.userId === undefined ? "user_test" : options.userId;
+  const now = new Date("2026-01-01T00:00:00.000Z");
+  const capabilityDef = options.capabilityDef ?? {
+    name: capability,
+    description: `Test capability ${capability}`,
+    input: { type: "object" },
+    output: { type: "object" },
+  };
+  const grant = {
+    id: "grant_test",
+    agentId,
+    capability,
+    constraints: options.constraints ?? null,
+    grantedBy: userId,
+    deniedBy: null,
+    reason: null,
+    expiresAt: null,
+    status: "active" as const,
+    createdAt: now,
+    updatedAt: now,
+    ...options.grant,
+  };
+  const agentSession = {
+    type: "delegated" as const,
+    agentId,
+    userId,
+    agent: {
+      id: agentId,
+      name: "Test agent",
+      mode: "delegated" as const,
+      capabilityGrants: [grant],
+      hostId: "host_test",
+      createdAt: now,
+      activatedAt: now,
+      metadata: null,
+    },
+    host: null,
+    user: {
+      id: userId ?? `agent-user:${agentId}`,
+      name: "Test user",
+      email: "agent-test@example.test",
+    },
+    ...options.agentSession,
+  };
+
+  return {
+    ctx: options.ctx ?? ({} as BetterAuthAgentCapabilityTestContext["ctx"]),
+    capability,
+    capabilityDef,
+    arguments: options.arguments,
+    agentSession,
+    grant,
+    revokeGrant: options.revokeGrant ?? (async () => {}),
+  };
+}