@beignet/agent-auth-better-auth 0.0.35

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @beignet/agent-auth-better-auth
+
+## 0.0.35
+
+### Patch Changes
+
+- 2101386: Authorize agent capabilities against their exact parsed input and keep custom Agent Auth locations outside the Beignet execution bridge.
+- 2290c4a: Add typed, validated agent capability registries and execution, plus a Better Auth Agent Auth bridge with constraint-safe validation, verified principals, grants, and redacted protocol errors.
+- 42921da: Keep agent capability registries type-safe, observe pre-context failures, and preserve application error codes across Agent Auth execution modes.
+
+## 0.0.34
+
+### Patch Changes
+
+- Add the initial Better Auth Agent Auth adapter for typed Beignet agent capabilities.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Taylor Bryant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# @beignet/agent-auth-better-auth
+
+> [!CAUTION]
+> Beignet is experimental alpha software. The `0.0.x` package line is for early
+> evaluation, and APIs may change between releases while the framework settles.
+
+Expose a typed Beignet agent capability registry through Better Auth's Agent
+Auth plugin. Beignet owns capability validation, application context, use-case
+execution, tracing, and instrumentation. Agent Auth owns registration, JWT
+verification, grants, constraints, approval, and protocol persistence.
+
+## Install
+
+```bash
+bun add @beignet/core @beignet/agent-auth-better-auth \
+  @better-auth/agent-auth better-auth zod
+```
+
+## Define capabilities
+
+```typescript
+// lib/agent-capabilities.ts
+import { createAgentCapabilities } from "@beignet/core/agent-capabilities";
+import type { AppContext } from "@/app-context";
+
+export type AgentPrincipal = {
+  agentId: string;
+  userId: string;
+};
+
+export const { defineAgentCapability, defineAgentCapabilityRegistry } =
+  createAgentCapabilities<AppContext, AgentPrincipal>();
+```
+
+```typescript
+// features/issues/agent-capabilities.ts
+import { z } from "zod";
+import { createIssueUseCase } from "./use-cases";
+import { defineAgentCapability } from "@/lib/agent-capabilities";
+
+export const createIssueCapability = defineAgentCapability("issues.create", {
+  description: "Create an issue in one workspace.",
+  input: z.object({
+    workspaceId: z.string().min(1),
+    title: z.string().min(1),
+  }),
+  output: z.object({ id: z.string(), title: z.string() }),
+  async handle({ ctx, input }) {
+    const { workspaceId: _workspaceId, ...useCaseInput } = input;
+    return createIssueUseCase.run({ ctx, input: useCaseInput });
+  },
+});
+```
+
+## Create the registry and executor
+
+```typescript
+import { createAgentCapabilityExecutor } from "@beignet/core/agent-capabilities";
+import { appError } from "@/features/shared/errors";
+import { createIssueCapability } from "@/features/issues/agent-capabilities";
+import { defineAgentCapabilityRegistry } from "@/lib/agent-capabilities";
+import { getServer } from "@/server";
+
+export const agentCapabilityRegistry =
+  defineAgentCapabilityRegistry([createIssueCapability]);
+
+export const agentCapabilityExecutor = createAgentCapabilityExecutor({
+  registry: agentCapabilityRegistry,
+  async createContext({ principal, input }) {
+    const server = await getServer();
+    const membership = await server.ports.members.findMembership({
+      workspaceId: input.workspaceId,
+      userId: principal.userId,
+    });
+    if (!membership) throw appError("NotAWorkspaceMember");
+
+    return server.createServiceContext({
+      asUser: { id: principal.userId, role: membership.role },
+      tenantId: input.workspaceId,
+    });
+  },
+});
+```
+
+The executor validates arguments before context construction and validates the
+handler result before returning it to Agent Auth. The context resolver must
+derive tenant membership from authoritative app state rather than agent claims.
+
+## Add the Agent Auth bridge
+
+```typescript
+import { agentAuth } from "@better-auth/agent-auth";
+import { betterAuth } from "better-auth";
+import { APIError } from "better-auth/api";
+import { createBetterAuthAgentCapabilityAdapter } from
+  "@beignet/agent-auth-better-auth";
+import {
+  agentCapabilityExecutor,
+  agentCapabilityRegistry,
+} from "@/server/agent-capabilities";
+
+const agentCapabilities = createBetterAuthAgentCapabilityAdapter({
+  registry: agentCapabilityRegistry,
+  executor: agentCapabilityExecutor,
+  principal({ agentSession }) {
+    if (!agentSession.userId) {
+      throw new APIError("FORBIDDEN", {
+        message: "A delegated user is required.",
+      });
+    }
+    return {
+      agentId: agentSession.agentId,
+      userId: agentSession.userId,
+    };
+  },
+  metadata: {
+    "issues.create": {
+      approvalStrength: "session",
+      requiredConstraints: ["workspaceId"],
+    },
+  },
+});
+
+export const auth = betterAuth({
+  // database, sessions, and other app-owned configuration
+  plugins: [
+    agentAuth({
+      ...agentCapabilities,
+      providerName: "example",
+      modes: ["delegated"],
+    }),
+  ],
+});
+```
+
+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.
+
+This bridge intentionally uses Agent Auth's default capability execution
+endpoint. It does not expose custom capability `location` metadata because
+custom locations send requests to an app-owned route and bypass this bridge's
+validation, context, constraint-stability, tracing, and output guarantees.
+
+The adapter preserves intentional Better Auth `APIError` failures. Declared
+Beignet `AppError` failures use their stable application code as the Agent Auth
+error code. Individual execution also preserves the AppError HTTP status;
+batch execution reports each item as failed and preserves the code without a
+per-item HTTP status. Invalid arguments become Agent Auth `invalid_request`
+errors; unknown capabilities use `capability_not_found`; invalid outputs and
+unexpected failures become redacted `internal_error` responses. Throw
+`APIError` or a declared `AppError` only when a failure is intentionally safe
+for an agent to receive.
+
+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.
+
+## Agent skills
+
+This package ships a TanStack Intent skill:
+`@beignet/agent-auth-better-auth#agent-capabilities`. Load it when defining a
+capability registry, constructing delegated service contexts, or wiring Better
+Auth Agent Auth.

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import type { AgentCapabilityExecutor, AgentCapabilityPrincipal, AgentCapabilityRegistry, AnyAgentCapabilityDef, MaybePromise } from "@beignet/core/agent-capabilities";
+import { type SchemaConverter } from "@beignet/core/openapi";
+import { type AgentAuthOptions, type Capability } from "@better-auth/agent-auth";
+/** Agent Auth metadata that does not replace Beignet-owned capability fields. */
+export type BetterAuthAgentCapabilityMetadata = Pick<Capability, "approvalStrength" | "grantTTL" | "requiredConstraints">;
+/** Error raised while adapting a Beignet capability registry. */
+export declare class BetterAuthAgentCapabilityAdapterError extends Error {
+    readonly capabilityName: string;
+    readonly cause?: unknown;
+    constructor(args: {
+        capabilityName: string;
+        message: string;
+        cause?: unknown;
+    });
+}
+/** 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>;
+    principal(context: Parameters<NonNullable<AgentAuthOptions["onExecute"]>>[0]): MaybePromise<AgentCapabilityPrincipal<Definitions[number]>>;
+    schemaConverter?: SchemaConverter;
+    metadata?: Partial<Record<Definitions[number]["name"], BetterAuthAgentCapabilityMetadata>>;
+}
+/** Better Auth options produced from a Beignet capability registry. */
+export type BetterAuthAgentCapabilityAdapter = Pick<AgentAuthOptions, "capabilities" | "onExecute">;
+/**
+ * Convert a Beignet capability registry and executor into options accepted by
+ * Better Auth's `agentAuth(...)` plugin.
+ */
+export declare function createBetterAuthAgentCapabilityAdapter<const Definitions extends readonly AnyAgentCapabilityDef[]>(options: CreateBetterAuthAgentCapabilityAdapterOptions<Definitions>): BetterAuthAgentCapabilityAdapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,153 @@
+import { AgentCapabilityError } from "@beignet/core/agent-capabilities";
+import { isAppError } from "@beignet/core/errors";
+import { createZodSchemaConverter, } from "@beignet/core/openapi";
+import { AGENT_AUTH_ERROR_CODES, agentError, } from "@better-auth/agent-auth";
+import { APIError } from "better-auth/api";
+/** Error raised while adapting a Beignet capability registry. */
+export class BetterAuthAgentCapabilityAdapterError extends Error {
+    constructor(args) {
+        super(args.message);
+        this.name = "BetterAuthAgentCapabilityAdapterError";
+        this.capabilityName = args.capabilityName;
+        this.cause = args.cause;
+    }
+}
+function convertSchema(args) {
+    if (!args.converter.canConvert(args.schema)) {
+        throw new BetterAuthAgentCapabilityAdapterError({
+            capabilityName: args.capabilityName,
+            message: `Schema converter "${args.converter.name}" cannot convert the ${args.io} schema for agent capability "${args.capabilityName}".`,
+        });
+    }
+    try {
+        return args.converter.toJSONSchema(args.schema, {
+            io: args.io,
+            nameHint: `${args.capabilityName}.${args.io}`,
+        });
+    }
+    catch (error) {
+        throw new BetterAuthAgentCapabilityAdapterError({
+            capabilityName: args.capabilityName,
+            message: `Schema converter "${args.converter.name}" failed to convert the ${args.io} schema for agent capability "${args.capabilityName}".`,
+            cause: error,
+        });
+    }
+}
+function throwAppError(error) {
+    throw agentError(error.status, {
+        code: error.code,
+        message: error.message,
+    }, undefined, error.headers, {
+        ...(error.details === undefined ? {} : { details: error.details }),
+    });
+}
+function mapExecutionError(error) {
+    if (isBetterAuthApiError(error))
+        throw error;
+    if (isAppError(error))
+        return throwAppError(error);
+    if (!(error instanceof AgentCapabilityError)) {
+        throw agentError("INTERNAL_SERVER_ERROR", AGENT_AUTH_ERROR_CODES.INTERNAL_ERROR);
+    }
+    if (error.code === "execution_failed") {
+        if (isBetterAuthApiError(error.cause))
+            throw error.cause;
+        if (isAppError(error.cause))
+            return throwAppError(error.cause);
+    }
+    if (error.code === "unknown_capability") {
+        throw agentError("BAD_REQUEST", AGENT_AUTH_ERROR_CODES.CAPABILITY_NOT_FOUND);
+    }
+    if (error.code === "invalid_input") {
+        throw agentError("BAD_REQUEST", AGENT_AUTH_ERROR_CODES.INVALID_REQUEST);
+    }
+    throw agentError("INTERNAL_SERVER_ERROR", AGENT_AUTH_ERROR_CODES.INTERNAL_ERROR);
+}
+function isBetterAuthApiError(value) {
+    if (value instanceof APIError)
+        return true;
+    if (!(value instanceof Error) || value.name !== "APIError")
+        return false;
+    if (!("statusCode" in value) || typeof value.statusCode !== "number") {
+        return false;
+    }
+    return "body" in value && (value.body === undefined || value.body !== null);
+}
+function assertConstrainedFieldsAreStable(args) {
+    const constraints = args.constraints;
+    if (!constraints)
+        return;
+    const constrainedFields = Object.keys(constraints);
+    if (constrainedFields.length === 0)
+        return;
+    const parsedInput = args.parsedInput && typeof args.parsedInput === "object"
+        ? args.parsedInput
+        : undefined;
+    for (const field of constrainedFields) {
+        if (!args.constrainedInput ||
+            !parsedInput ||
+            !Object.is(args.constrainedInput[field], parsedInput[field])) {
+            throw agentError("FORBIDDEN", AGENT_AUTH_ERROR_CODES.CONSTRAINT_VIOLATED, `Constrained capability argument "${field}" changed during validation.`);
+        }
+    }
+}
+function snapshotConstrainedInput(args) {
+    if (!args.constraints)
+        return undefined;
+    const rawInput = args.rawInput && typeof args.rawInput === "object"
+        ? args.rawInput
+        : undefined;
+    return Object.fromEntries(Object.keys(args.constraints).map((field) => [field, rawInput?.[field]]));
+}
+/**
+ * Convert a Beignet capability registry and executor into options accepted by
+ * Better Auth's `agentAuth(...)` plugin.
+ */
+export function createBetterAuthAgentCapabilityAdapter(options) {
+    const converter = options.schemaConverter ?? createZodSchemaConverter();
+    const capabilities = options.registry.definitions.map((capability) => ({
+        name: capability.name,
+        description: capability.description,
+        input: convertSchema({
+            capabilityName: capability.name,
+            schema: capability.input,
+            io: "input",
+            converter,
+        }),
+        output: convertSchema({
+            capabilityName: capability.name,
+            schema: capability.output,
+            io: "output",
+            converter,
+        }),
+        ...options.metadata?.[capability.name],
+    }));
+    return {
+        capabilities,
+        async onExecute(context) {
+            try {
+                const rawInput = context.arguments ?? {};
+                const constrainedInput = snapshotConstrainedInput({
+                    constraints: context.grant.constraints,
+                    rawInput,
+                });
+                return await options.executor.executeDynamic({
+                    name: context.capability,
+                    principal: await options.principal(context),
+                    input: rawInput,
+                    authorize({ input }) {
+                        assertConstrainedFieldsAreStable({
+                            constraints: context.grant.constraints,
+                            constrainedInput,
+                            parsedInput: input,
+                        });
+                    },
+                });
+            }
+            catch (error) {
+                return mapExecutionError(error);
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@beignet/agent-auth-better-auth",
+  "version": "0.0.35",
+  "type": "module",
+  "description": "Better Auth Agent Auth adapter for Beignet agent capabilities",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-d.ts",
+    "skills",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "bun run build",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist coverage .turbo",
+    "test": "bun test && bun run typecheck:types",
+    "test:coverage": "bun test --coverage",
+    "typecheck:types": "tsc -p tsconfig.type-tests.json",
+    "lint": "biome check ."
+  },
+  "keywords": [
+    "beignet",
+    "agent",
+    "capabilities",
+    "better-auth",
+    "ai"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taylorbryant/beignet.git",
+    "directory": "packages/agent-auth-better-auth"
+  },
+  "author": "Taylor Bryant",
+  "homepage": "https://github.com/taylorbryant/beignet#readme",
+  "bugs": {
+    "url": "https://github.com/taylorbryant/beignet/issues"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@beignet/core": ">=0.0.3 <1.0.0",
+    "@better-auth/agent-auth": ">=0.6.2 <0.7.0",
+    "better-auth": ">=1.4.0 <1.7.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@beignet/core": "*",
+    "@better-auth/agent-auth": "0.6.2",
+    "@types/bun": "^1.3.13",
+    "@types/node": "^20.10.0",
+    "better-auth": "1.6.20",
+    "jose": "^6.1.3",
+    "typescript": "^5.3.0",
+    "zod": "^4.0.0"
+  }
+}

package/skills/agent-capabilities/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: agent-capabilities
+description: "Expose Beignet use cases to authenticated AI agents with @beignet/core/agent-capabilities and @beignet/agent-auth-better-auth. Use when defining typed capabilities, composing registries, resolving authoritative delegated service contexts, converting schemas, configuring Better Auth Agent Auth grants, or testing agent execution."
+---
+
+# Beignet Agent Capabilities
+
+Use `createAgentCapabilities<AppContext, AgentPrincipal>()` once in
+`lib/agent-capabilities.ts` and export both returned definition helpers. Keep
+capability definitions feature-owned and compose them explicitly with the
+context-bound `defineAgentCapabilityRegistry(...)`; it rejects definitions
+from another app context or principal binding.
+
+Capabilities are entrypoint adapters, not business workflows. Validate their
+agent-facing input and output with Standard Schema, then call existing use
+cases from `handle(...)`.
+
+Create one executor with `createAgentCapabilityExecutor(...)`. Its
+`createContext(...)` callback receives parsed input and a principal derived
+from a verified Agent Auth session. Re-read membership and roles from app
+ports, then call `server.createServiceContext(...)`. Never trust role or tenant
+authorization from agent claims and never assemble `AppContext` manually.
+
+Use `createBetterAuthAgentCapabilityAdapter(...)` to produce `capabilities`
+and `onExecute` for `agentAuth(...)`. The adapter converts Zod schemas by
+default; pass a `SchemaConverter` for another schema library. Put Agent Auth
+approval strength, required constraints, and grant TTL in the adapter's typed
+`metadata` map. Do not configure a custom capability location: custom routes
+bypass the bridge and must implement Agent Auth verification, grant enforcement,
+Beignet execution, and output validation independently.
+
+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.
+
+Better Auth owns registration, JWT verification, grants, constraints,
+approval, and protocol persistence. Beignet owns validation, context, use-case
+execution, tracing, and bounded instrumentation.
+
+Unexpected errors are redacted as `internal_error`. Throw a Better Auth
+`APIError` or declared Beignet `AppError` only for failures intentionally safe
+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.

package/src/index.ts

@@ -0,0 +1,254 @@
+import type {
+  AgentCapabilityExecutor,
+  AgentCapabilityPrincipal,
+  AgentCapabilityRegistry,
+  AnyAgentCapabilityDef,
+  MaybePromise,
+} from "@beignet/core/agent-capabilities";
+import { AgentCapabilityError } from "@beignet/core/agent-capabilities";
+import { type AppError, isAppError } from "@beignet/core/errors";
+import {
+  createZodSchemaConverter,
+  type SchemaConverter,
+} from "@beignet/core/openapi";
+import {
+  AGENT_AUTH_ERROR_CODES,
+  type AgentAuthOptions,
+  agentError,
+  type Capability,
+} from "@better-auth/agent-auth";
+import { APIError } from "better-auth/api";
+
+/** Agent Auth metadata that does not replace Beignet-owned capability fields. */
+export type BetterAuthAgentCapabilityMetadata = Pick<
+  Capability,
+  "approvalStrength" | "grantTTL" | "requiredConstraints"
+>;
+
+/** Error raised while adapting a Beignet capability registry. */
+export class BetterAuthAgentCapabilityAdapterError extends Error {
+  readonly capabilityName: string;
+  override readonly cause?: unknown;
+
+  constructor(args: {
+    capabilityName: string;
+    message: string;
+    cause?: unknown;
+  }) {
+    super(args.message);
+    this.name = "BetterAuthAgentCapabilityAdapterError";
+    this.capabilityName = args.capabilityName;
+    this.cause = args.cause;
+  }
+}
+
+/** 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
+  >;
+  principal(
+    context: Parameters<NonNullable<AgentAuthOptions["onExecute"]>>[0],
+  ): MaybePromise<AgentCapabilityPrincipal<Definitions[number]>>;
+  schemaConverter?: SchemaConverter;
+  metadata?: Partial<
+    Record<Definitions[number]["name"], BetterAuthAgentCapabilityMetadata>
+  >;
+}
+
+/** Better Auth options produced from a Beignet capability registry. */
+export type BetterAuthAgentCapabilityAdapter = Pick<
+  AgentAuthOptions,
+  "capabilities" | "onExecute"
+>;
+
+function convertSchema(args: {
+  capabilityName: string;
+  schema: unknown;
+  io: "input" | "output";
+  converter: SchemaConverter;
+}): Record<string, unknown> {
+  if (!args.converter.canConvert(args.schema)) {
+    throw new BetterAuthAgentCapabilityAdapterError({
+      capabilityName: args.capabilityName,
+      message: `Schema converter "${args.converter.name}" cannot convert the ${args.io} schema for agent capability "${args.capabilityName}".`,
+    });
+  }
+
+  try {
+    return args.converter.toJSONSchema(args.schema, {
+      io: args.io,
+      nameHint: `${args.capabilityName}.${args.io}`,
+    });
+  } catch (error) {
+    throw new BetterAuthAgentCapabilityAdapterError({
+      capabilityName: args.capabilityName,
+      message: `Schema converter "${args.converter.name}" failed to convert the ${args.io} schema for agent capability "${args.capabilityName}".`,
+      cause: error,
+    });
+  }
+}
+
+function throwAppError(error: AppError): never {
+  throw agentError(
+    error.status as ConstructorParameters<typeof APIError>[0],
+    {
+      code: error.code,
+      message: error.message,
+    },
+    undefined,
+    error.headers,
+    {
+      ...(error.details === undefined ? {} : { details: error.details }),
+    },
+  );
+}
+
+function mapExecutionError(error: unknown): never {
+  if (isBetterAuthApiError(error)) throw error;
+  if (isAppError(error)) return throwAppError(error);
+
+  if (!(error instanceof AgentCapabilityError)) {
+    throw agentError(
+      "INTERNAL_SERVER_ERROR",
+      AGENT_AUTH_ERROR_CODES.INTERNAL_ERROR,
+    );
+  }
+
+  if (error.code === "execution_failed") {
+    if (isBetterAuthApiError(error.cause)) throw error.cause;
+    if (isAppError(error.cause)) return throwAppError(error.cause);
+  }
+
+  if (error.code === "unknown_capability") {
+    throw agentError(
+      "BAD_REQUEST",
+      AGENT_AUTH_ERROR_CODES.CAPABILITY_NOT_FOUND,
+    );
+  }
+
+  if (error.code === "invalid_input") {
+    throw agentError("BAD_REQUEST", AGENT_AUTH_ERROR_CODES.INVALID_REQUEST);
+  }
+
+  throw agentError(
+    "INTERNAL_SERVER_ERROR",
+    AGENT_AUTH_ERROR_CODES.INTERNAL_ERROR,
+  );
+}
+
+function isBetterAuthApiError(value: unknown): value is APIError {
+  if (value instanceof APIError) return true;
+  if (!(value instanceof Error) || value.name !== "APIError") return false;
+  if (!("statusCode" in value) || typeof value.statusCode !== "number") {
+    return false;
+  }
+  return "body" in value && (value.body === undefined || value.body !== null);
+}
+
+function assertConstrainedFieldsAreStable(args: {
+  constraints: Record<string, unknown> | null | undefined;
+  constrainedInput: Readonly<Record<string, unknown>> | undefined;
+  parsedInput: unknown;
+}): void {
+  const constraints = args.constraints;
+  if (!constraints) return;
+
+  const constrainedFields = Object.keys(constraints);
+  if (constrainedFields.length === 0) return;
+
+  const parsedInput =
+    args.parsedInput && typeof args.parsedInput === "object"
+      ? (args.parsedInput as Record<string, unknown>)
+      : undefined;
+
+  for (const field of constrainedFields) {
+    if (
+      !args.constrainedInput ||
+      !parsedInput ||
+      !Object.is(args.constrainedInput[field], parsedInput[field])
+    ) {
+      throw agentError(
+        "FORBIDDEN",
+        AGENT_AUTH_ERROR_CODES.CONSTRAINT_VIOLATED,
+        `Constrained capability argument "${field}" changed during validation.`,
+      );
+    }
+  }
+}
+
+function snapshotConstrainedInput(args: {
+  constraints: Record<string, unknown> | null | undefined;
+  rawInput: unknown;
+}): Readonly<Record<string, unknown>> | undefined {
+  if (!args.constraints) return undefined;
+  const rawInput =
+    args.rawInput && typeof args.rawInput === "object"
+      ? (args.rawInput as Record<string, unknown>)
+      : undefined;
+  return Object.fromEntries(
+    Object.keys(args.constraints).map((field) => [field, rawInput?.[field]]),
+  );
+}
+
+/**
+ * Convert a Beignet capability registry and executor into options accepted by
+ * Better Auth's `agentAuth(...)` plugin.
+ */
+export function createBetterAuthAgentCapabilityAdapter<
+  const Definitions extends readonly AnyAgentCapabilityDef[],
+>(
+  options: CreateBetterAuthAgentCapabilityAdapterOptions<Definitions>,
+): BetterAuthAgentCapabilityAdapter {
+  const converter = options.schemaConverter ?? createZodSchemaConverter();
+  const capabilities: Capability[] = options.registry.definitions.map(
+    (capability) => ({
+      name: capability.name,
+      description: capability.description,
+      input: convertSchema({
+        capabilityName: capability.name,
+        schema: capability.input,
+        io: "input",
+        converter,
+      }),
+      output: convertSchema({
+        capabilityName: capability.name,
+        schema: capability.output,
+        io: "output",
+        converter,
+      }),
+      ...options.metadata?.[capability.name as Definitions[number]["name"]],
+    }),
+  );
+
+  return {
+    capabilities,
+    async onExecute(context) {
+      try {
+        const rawInput = context.arguments ?? {};
+        const constrainedInput = snapshotConstrainedInput({
+          constraints: context.grant.constraints,
+          rawInput,
+        });
+        return await options.executor.executeDynamic({
+          name: context.capability,
+          principal: await options.principal(context),
+          input: rawInput,
+          authorize({ input }) {
+            assertConstrainedFieldsAreStable({
+              constraints: context.grant.constraints,
+              constrainedInput,
+              parsedInput: input,
+            });
+          },
+        });
+      } catch (error) {
+        return mapExecutionError(error);
+      }
+    },
+  };
+}