@beignet/core 0.0.34 → 0.0.36

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @beignet/core
 
+## 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
+
+- 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.
+- 2a5b224: Preserve idempotency and outbox delivery guarantees on persistence and handler failures, enforce multipart limits from actual bytes, support Date and JSON query serialization, and add bounded MySQL deadlock backoff.
+- 74aad51: Replace the schedule-specific instrumentation sink with shared provider targets, serve bodyless HEAD responses from GET routes, improve missing JSON content-type diagnostics, and expose the auth error HTTP status.
+- db79263: Align route, listener, auth-provider, and webhook-integration APIs before 1.0. Route declarations now use an app-bound `createRoutes<AppContext>()` builder, listeners put their stable name first, Better Auth exports `createBetterAuthProvider(...)`, and vendor webhook verifiers live in `@beignet/webhooks-*` packages outside provider audits.
+- 397f106: Standardize framework-owned operational errors, degrade opaque OpenAPI path parameters safely, and add direct Redis, Pino, and Upstash adapters.
+- 40f4155: Refresh package-shipped agent guidance for app-bound route builders, configured route-builder paths, webhook integrations, and operational error responses.
+- d1c0efd: Make contract and contract-group OpenAPI metadata compose consistently across `meta()` and `openapi()` calls.
+- c403db2: Isolate use-case observers, authenticate operational routes before context creation, honor configured generated-test roots, correct feature-helper linting, preserve optional OpenAPI descriptions, and keep upload resets stable.
+- 4cc5254: Decompose the server runtime into focused internal modules while preserving the existing public API and request behavior.
+- 7d0c795: Expose stable named provider types while keeping private config schemas out of package declarations and preserving validated config and contributed-port inference. Drizzle's Postgres and MySQL config schema constants are now internal; use the exported config interfaces for validated shapes.
+
 ## 0.0.34
 
 ### Patch Changes

package/README.md

@@ -7,7 +7,7 @@
 > evaluation, and APIs may change between releases while the framework settles.
 
 This package provides Beignet's framework primitives: contracts, server runtime,
-typed client, use cases, ports, domain helpers, app errors, config, events,
+typed client, use cases, agent capabilities, ports, domain helpers, app errors, config, events,
 idempotency, locks, outbox, mail, notifications, payments, search, webhooks,
 feature flags, error reporting, schedules, uploads, entitlements, pagination
 helpers, testing helpers, and OpenAPI generation.
@@ -46,6 +46,7 @@ name the framework area they depend on.
 
 | Import path | Responsibility |
 | --- | --- |
+| `@beignet/core/agent-capabilities` | Typed agent capability definitions, registries, validation, and execution |
 | `@beignet/core/application` | Use case builder and test helpers |
 | `@beignet/core/client` | Typed HTTP client |
 | `@beignet/core/client-only` | Static lint marker for modules intended for client-side imports |
@@ -89,6 +90,77 @@ import "@beignet/core/client-only";
 import "@beignet/core/server-only";
 ```
 
+## Agent capabilities
+
+Agent capabilities are validated application entrypoints for authenticated AI
+agent transports. Definitions remain transport-neutral and should delegate
+business behavior to the same use cases called by HTTP routes, jobs, and
+scripts.
+
+```typescript
+import {
+  createAgentCapabilities,
+  createAgentCapabilityExecutor,
+} from "@beignet/core/agent-capabilities";
+import { z } from "zod";
+import type { AppContext } from "@/app-context";
+import { createIssueUseCase } from "@/features/issues/use-cases";
+
+type AgentPrincipal = { agentId: string; userId: string };
+
+const { defineAgentCapability, defineAgentCapabilityRegistry } =
+  createAgentCapabilities<AppContext, AgentPrincipal>();
+
+const createIssue = defineAgentCapability("issues.create", {
+  description: "Create an issue in one workspace.",
+  input: z.object({ workspaceId: z.string(), 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 });
+  },
+});
+
+const registry = defineAgentCapabilityRegistry([createIssue]);
+
+export const executor = createAgentCapabilityExecutor({
+  registry,
+  async createContext({ principal, input }) {
+    const membership = await server.ports.members.findMembership({
+      workspaceId: input.workspaceId,
+      userId: principal.userId,
+    });
+    if (!membership) throw new Error("Not a workspace member");
+
+    return server.createServiceContext({
+      asUser: { id: principal.userId, role: membership.role },
+      tenantId: input.workspaceId,
+    });
+  },
+});
+```
+
+Input is validated before `createContext(...)` runs. Output is validated before
+it reaches the transport. Context construction remains app-owned: authenticate
+the transport first, re-read tenant membership from an authoritative port, and
+call `server.createServiceContext(...)` instead of assembling `AppContext` by
+hand. Use `@beignet/agent-auth-better-auth` to expose a registry through Better
+Auth Agent Auth.
+
+Registry creation comes from the same app-bound factory as
+`defineAgentCapability`, so definitions with another context or principal type
+are rejected. Executor hooks observe the complete attempt and include a
+`stage`. Completion events contain the capability, context, principal,
+validated input, validated output, and duration. Failure events expose context
+and validated input only when execution reached those stages; raw malformed
+input and unvalidated output are not exposed. Dynamic transport adapters may
+provide `authorize(...)` to inspect the exact parsed input before context
+construction without causing a second validation pass. Pass an independent
+`instrumentation` target and `tracing` port to the executor when lookup,
+input-validation, and context failures must be visible before an app context
+exists. Without those options, successful context construction lets the
+executor derive observability ports from `ctx`.
+
 ## Durable failure language
 
 Jobs, outbox delivery, and schedule runners use the same terms:
@@ -229,6 +301,13 @@ import type { providers } from "@/server/providers";
 export type AppRuntimePorts = AppPorts & InferProviderPorts<typeof providers>;
 ```
 
+Reusable provider packages should export a named `ServiceProvider` return type
+and use `AnyProviderConfigSchema<Config>` for its config generic. That keeps a
+private Zod or other Standard Schema implementation out of the package
+declaration while preserving the validated config output and exact
+contributed-port inference. App-local providers should keep their concrete
+schema inference because they do not have a package compatibility boundary.
+
 App-local providers can declare required ports, app context, and
 service-context input through the curried `createProvider()` form. `setup`
 then receives typed `ports` and a `createServiceContext` factory that returns
@@ -549,6 +628,15 @@ can compute the digest before `prepare`. Use `verifyFile(...)` for app-owned
 scanning, moderation, and quarantine decisions that run after the object exists
 in storage and before `onComplete(...)`.
 
+`createUploadRouter(...)` bounds JSON request bodies and server-handled
+multipart bodies. Multipart limits are enforced against both a declared
+`Content-Length` and the bytes actually read, so chunked requests cannot bypass
+`limits.multipartMaxBytes` before `formData()` parsing.
+
+Upload route failures use Beignet's flat `{ code, message, details? }` error
+body. The typed upload client maps that response to `UploadClientError` with
+the same code, status, and details.
+
 ## Webhooks
 
 Use `@beignet/core/webhooks` for provider-neutral inbound webhook definitions,
@@ -584,8 +672,8 @@ export const issueWebhook = defineWebhook("issues.provider", {
 
 Use `createMemoryWebhookVerifier(...)` in tests and `createWebhookRoute(...)`
 from `@beignet/next` to expose raw-body webhook routes in Next.js apps. Use a
-provider package such as `@beignet/provider-webhooks-github` or
-`@beignet/provider-webhooks-stripe` when a vendor has signature semantics beyond
+provider package such as `@beignet/webhooks-github` or
+`@beignet/webhooks-stripe` when a vendor has signature semantics beyond
 the generic HMAC verifier. For billing flows backed by `ctx.ports.payments`,
 use `@beignet/core/payments` with `createPaymentWebhookRoute(...)` from
 `@beignet/next` instead of a generic webhook catalog.
@@ -780,10 +868,14 @@ may only be registered once, contract names must be unique across the route
 registry because typed clients, OpenAPI operations, and devtools key on them,
 and an introspectable `.pathParams(...)` object schema must declare exactly the
 `:param` keys from the path template. Mismatches fail server startup with the
-contract name and path. At dispatch time, a request that matches a registered
+contract name and path. Opaque Standard Schemas skip that registration-time key
+comparison; OpenAPI falls back to required string parameters from the literal
+path template unless a custom schema introspector is supplied. At dispatch
+time, a request that matches a registered
 path with an unregistered method receives a framework-owned `405
 METHOD_NOT_ALLOWED` response with an `Allow` header listing the registered
-methods; `HEAD` is intentionally not served by `GET` handlers.
+methods. `GET` routes also serve `HEAD` when no explicit `HEAD` route exists;
+explicit `HEAD` routes take precedence, and every `HEAD` response is bodyless.
 
 ### Runtime integrity
 
@@ -844,6 +936,10 @@ the returned handler at the route's own path.
 Use `.headers(...)` for request headers that are part of the endpoint contract. Declare header keys in lowercase; server and client runtime matching is case-insensitive.
 
 Request bodies are supported for `POST`, `PUT`, and `PATCH` contracts only.
+JSON bodies require `Content-Type: application/json`; otherwise the runtime
+passes the body to validation as text. When a missing content type accompanies
+a valid JSON object or array that fails validation, the framework-owned error
+includes a targeted `details.hint` without changing the response code.
 
 If you do not pass `name`, Beignet generates one from the HTTP method and full path:
 
@@ -1519,6 +1615,11 @@ a transaction-scoped `tx.idempotency` port from the app Unit of Work so
 reservation, business writes, audit records, domain-event records, and
 idempotency completion commit together.
 
+`runIdempotently(...)` releases a reservation only when the protected work
+throws. If the work succeeds but `complete(...)` fails, the reservation stays
+in progress and the completion error is rethrown so an immediate retry cannot
+repeat the successful work.
+
 ### Outbox
 
 Use `@beignet/core/outbox` when events or jobs must be recorded in the same
@@ -1569,6 +1670,11 @@ await drainOutbox({
 The outbox is at-least-once delivery. Use idempotent listeners or jobs when a
 duplicate delivery would be harmful.
 
+When an inline dispatcher exposes Beignet's single-attempt delivery hook, an
+`onError` observer is still notified but cannot swallow the failure. The outbox
+retains retry and dead-letter ownership instead of marking the message
+delivered.
+
 Use `OutboxAdminPort` only from operational contexts. It lets `beignet outbox`
 list, show, requeue, purge dead-lettered rows, and prune delivered rows without
 exposing those destructive operations to transaction-scoped use cases.
@@ -1585,7 +1691,7 @@ import { createInlineScheduleRunner } from "@beignet/core/schedules";
 
 const runner = createInlineScheduleRunner<AppContext>({
   ctx,
-  instrumentation: ctx.ports.devtools,
+  instrumentation: ctx.ports,
   instrumentationContext: {
     requestId: ctx.requestId,
     traceId: ctx.traceId,
@@ -1596,9 +1702,10 @@ await runner.run(SendDailyDigestSchedule, { source: "vercel-cron" });
 ```
 
 `instrumentationContext` attaches request correlation fields to recorded
-events. Recording failures are isolated from schedule execution and reported
-to `onHookError` when provided. Handler failures still reject `runner.run(...)`
-after `onError` runs so trigger hosts can retry.
+events. The shared provider instrumentation helper applies watcher checks,
+redaction, and sink-failure isolation. Lifecycle hook failures still reach
+`onHookError` when provided. Handler failures reject `runner.run(...)` after
+`onError` runs so trigger hosts can retry.
 
 ### Contract metadata and route hooks
 
@@ -1631,8 +1738,13 @@ install `createRateLimitHooks(...)` and `createIdempotencyHooks(...)` where the
 server is composed. Use route hooks for runtime enforcement of route-specific
 policy where the route is wired:
 
+Bind route declarations to the app context once in `lib/routes.ts` with
+`createRoutes<AppContext>()`, then import the resulting builders in feature
+route files.
+
 ```ts
-import { createAuthHooks, defineRouteGroup } from "@beignet/core/server";
+import { createAuthHooks } from "@beignet/core/server";
+import { defineRouteGroup } from "@/lib/routes";
 import type { AppContext } from "@/app-context";
 
 const auth = createAuthHooks<AppContext>()({
@@ -1641,7 +1753,7 @@ const auth = createAuthHooks<AppContext>()({
   },
 });
 
-export const messageRoutes = defineRouteGroup<AppContext>()({
+export const messageRoutes = defineRouteGroup({
   name: "messages",
   routes: [
     {
@@ -1663,7 +1775,7 @@ contract's sole request schema by reference, the server skips the use case's
 input re-parse — one schema, one parse.
 
 Use `{ contract, handle }` as the escape hatch for response headers,
-streaming, and multi-status responses. `defineRoute<AppContext>()` remains
+streaming, and multi-status responses. `defineRoute` remains
 available for full handlers that read hook-added `ctx` fields.
 
 When credentials live in request headers, declare a `headers` schema on the
@@ -1857,6 +1969,10 @@ port is installed, it also creates an active child span. Pass
 `instrumentation: false` to opt out of instrumentation events; tracing is
 controlled by whether the app installs `ports.tracing`.
 
+App-owned `onRun` observers are best-effort. Synchronous throws and rejected
+observer promises are ignored so instrumentation cannot fail a use case or
+replace its original error.
+
 `createInstrumentedAuditLog({ audit, instrumentation })` from
 `@beignet/core/ports` writes durable audit entries first and mirrors sanitized
 audit activity into the resolved instrumentation sink.
@@ -1918,12 +2034,23 @@ export const getTodo = todos
   });
 ```
 
+`.openapi(...)` and `.meta({ openapi: ... })` share the same shallow merge
+semantics. OpenAPI fields from contract groups and earlier calls are preserved,
+while a later value replaces the same field. Structured fields such as
+`responses` are replaced as a whole rather than deep-merged. Prefer
+`.openapi(...)` for operation metadata; use `.meta(...)` when composing it with
+other metadata conventions.
+
 Use `requestBody`, `responses`, and `parameters` overrides when an operation
 needs non-JSON media such as multipart uploads, binary downloads, event streams,
 or cookie parameters. `contractsToOpenAPI(...)` accepts `schemaConverters` for
 non-Zod Standard Schema libraries; custom converters run before Beignet's
 default Zod converter.
 
+Descriptions attached before `.optional()` are preserved on generated query
+and header parameters, matching descriptions attached to the outer optional
+schema.
+
 ### Schema introspection
 
 Contracts expose their schemas for runtime introspection:
@@ -1980,8 +2107,8 @@ standard error envelope.
 | `.body(schema)` | Define request body schema |
 | `.responses({ ... })` | Define or merge response schemas by status code |
 | `.errors({ ... })` | Declare route-owned catalog errors using Beignet's standard error envelope; merges with group and earlier declarations |
-| `.meta(metadata)` | Add custom metadata |
-| `.openapi(options)` | Add OpenAPI metadata (summary, tags, etc.) |
+| `.meta(metadata)` | Merge custom metadata; nested `openapi` fields merge one level deep |
+| `.openapi(options)` | Merge OpenAPI metadata (summary, tags, etc.) |
 
 ## Standard Schema support
 
@@ -1991,7 +2118,10 @@ This package works with any [Standard Schema](https://github.com/standard-schema
 - **Valibot** - Lightweight alternative to Zod
 - **ArkType** - High-performance runtime validation
 
-OpenAPI generation currently requires Zod schemas, even though core contracts can use any Standard Schema-compatible library.
+OpenAPI generation includes a Zod converter and introspector by default. Other
+Standard Schema libraries can supply `schemaConverters` and a
+`schemaIntrospector`; opaque path parameter schemas degrade to required string
+parameters derived from the contract path.
 
 ## Related packages
 

package/dist/agent-capabilities/index.d.ts

@@ -0,0 +1,197 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { type ProviderInstrumentationTarget } from "../providers/index.js";
+import type { TracingPort } from "../tracing/index.js";
+/** Any Standard Schema compatible validator. */
+export type AgentCapabilitySchema = StandardSchemaV1<unknown, unknown>;
+/** Value or promise of that value. */
+export type MaybePromise<T> = T | Promise<T>;
+/** Infer the input accepted by a capability schema. */
+export type InferAgentCapabilitySchemaInput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferInput<Schema>;
+/** Infer the parsed output produced by a capability schema. */
+export type InferAgentCapabilitySchemaOutput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema>;
+/** A typed action that an authenticated agent transport may expose. */
+export interface AgentCapabilityDef<Name extends string = string, Input extends AgentCapabilitySchema = AgentCapabilitySchema, Output extends AgentCapabilitySchema = AgentCapabilitySchema, Ctx = unknown, Principal = unknown> {
+    readonly kind: "agentCapability";
+    readonly name: Name;
+    readonly description: string;
+    readonly input: Input;
+    readonly output: Output;
+    readonly handle: (args: {
+        capability: AgentCapabilityDef<Name, Input, Output, Ctx, Principal>;
+        ctx: Ctx;
+        principal: Principal;
+        input: InferAgentCapabilitySchemaOutput<Input>;
+    }) => MaybePromise<InferAgentCapabilitySchemaInput<Output>>;
+}
+/** Broad capability definition shape tied to one context and principal. */
+export interface AgentCapabilityFor<Ctx, Principal> {
+    readonly kind: "agentCapability";
+    readonly name: string;
+    readonly description: string;
+    readonly input: AgentCapabilitySchema;
+    readonly output: AgentCapabilitySchema;
+    readonly handle: (args: {
+        capability: never;
+        ctx: Ctx;
+        principal: Principal;
+        input: never;
+    }) => MaybePromise<unknown>;
+}
+/** Broad capability definition shape used by registries and adapters. */
+export type AnyAgentCapabilityDef = AgentCapabilityFor<never, never>;
+/** Infer a capability's application context. */
+export type AgentCapabilityContext<Capability extends AnyAgentCapabilityDef> = Capability extends {
+    handle(args: {
+        ctx: infer Ctx;
+    }): unknown;
+} ? Ctx : never;
+/** Infer a capability's verified principal. */
+export type AgentCapabilityPrincipal<Capability extends AnyAgentCapabilityDef> = Capability extends {
+    handle(args: {
+        principal: infer Principal;
+    }): unknown;
+} ? Principal : never;
+/** Infer a capability's raw input. */
+export type AgentCapabilityInput<Capability extends AnyAgentCapabilityDef> = InferAgentCapabilitySchemaInput<Capability["input"]>;
+/** Infer the parsed input passed to capability context and execution. */
+export type AgentCapabilityParsedInput<Capability extends AnyAgentCapabilityDef> = InferAgentCapabilitySchemaOutput<Capability["input"]>;
+/** Infer a capability's validated output. */
+export type AgentCapabilityOutput<Capability extends AnyAgentCapabilityDef> = InferAgentCapabilitySchemaOutput<Capability["output"]>;
+/** Options accepted by `defineAgentCapability(...)`. */
+export interface DefineAgentCapabilityOptions<Name extends string, Input extends AgentCapabilitySchema, Output extends AgentCapabilitySchema, Ctx, Principal> {
+    description: string;
+    input: Input;
+    output: Output;
+    handle(args: {
+        capability: AgentCapabilityDef<Name, Input, Output, Ctx, Principal>;
+        ctx: Ctx;
+        principal: Principal;
+        input: InferAgentCapabilitySchemaOutput<Input>;
+    }): MaybePromise<InferAgentCapabilitySchemaInput<Output>>;
+}
+/** Context-bound capability definition helpers. */
+export interface AgentCapabilities<Ctx, Principal> {
+    defineAgentCapability<const Name extends string, Input extends AgentCapabilitySchema, Output extends AgentCapabilitySchema>(name: Name, options: DefineAgentCapabilityOptions<Name, Input, Output, Ctx, Principal>): AgentCapabilityDef<Name, Input, Output, Ctx, Principal>;
+    defineAgentCapabilityRegistry<const Definitions extends readonly AgentCapabilityFor<Ctx, Principal>[]>(definitions: Definitions): AgentCapabilityRegistry<Definitions>;
+}
+/** Bind application context and principal types once for capability definitions. */
+export declare function createAgentCapabilities<Ctx, Principal>(): AgentCapabilities<Ctx, Principal>;
+/** Error thrown when a capability registry is ambiguous. */
+export declare class AgentCapabilityRegistryError extends Error {
+    constructor(message: string);
+}
+/** Registered capability definitions available to execution adapters. */
+export interface AgentCapabilityRegistry<Definitions extends readonly AnyAgentCapabilityDef[] = readonly AnyAgentCapabilityDef[]> {
+    readonly definitions: Definitions;
+    get(name: string): Definitions[number] | undefined;
+}
+/** Stable capability execution failure categories. */
+export type AgentCapabilityErrorCode = "unknown_capability" | "invalid_input" | "invalid_output" | "execution_failed";
+/** Error raised by capability lookup, validation, or execution. */
+export declare class AgentCapabilityError extends Error {
+    readonly code: AgentCapabilityErrorCode;
+    readonly capabilityName: string;
+    readonly issues?: readonly StandardSchemaV1.Issue[];
+    readonly cause?: unknown;
+    constructor(args: {
+        code: AgentCapabilityErrorCode;
+        capabilityName: string;
+        message: string;
+        issues?: readonly StandardSchemaV1.Issue[];
+        cause?: unknown;
+    });
+}
+/** A parsed invocation passed to the app-owned context resolver. */
+export type AgentCapabilityContextRequest<Definitions extends readonly AnyAgentCapabilityDef[], Principal> = {
+    [Capability in Definitions[number] as Capability["name"]]: {
+        capability: Capability;
+        name: Capability["name"];
+        principal: Principal;
+        input: InferAgentCapabilitySchemaOutput<Capability["input"]>;
+    };
+}[Definitions[number]["name"]];
+/** Stage reached by an agent capability attempt. */
+export type AgentCapabilityRunStage = "lookup" | "input" | "authorization" | "context" | "handler" | "output";
+/** Successful capability lifecycle event with validated application data. */
+export type AgentCapabilityCompletedRunEvent<Ctx, Principal, Definitions extends readonly AnyAgentCapabilityDef[] = readonly AnyAgentCapabilityDef[], Capability extends Definitions[number] = Definitions[number]> = Capability extends Definitions[number] ? {
+    name: Capability["name"];
+    phase: "end";
+    stage: "output";
+    capability: Capability;
+    ctx: Ctx;
+    principal: Principal;
+    input: AgentCapabilityParsedInput<Capability>;
+    output: AgentCapabilityOutput<Capability>;
+    durationMs: number;
+    error?: undefined;
+} : never;
+/** Lifecycle event observed around a capability attempt. */
+export type AgentCapabilityRunEvent<Ctx, Principal, Definitions extends readonly AnyAgentCapabilityDef[] = readonly AnyAgentCapabilityDef[]> = {
+    name: string;
+    phase: "start";
+    stage: "lookup";
+    capability?: Definitions[number];
+    ctx?: undefined;
+    principal: Principal;
+    input?: undefined;
+    output?: undefined;
+    durationMs?: undefined;
+    error?: undefined;
+} | AgentCapabilityCompletedRunEvent<Ctx, Principal, Definitions> | {
+    name: string;
+    phase: "error";
+    stage: AgentCapabilityRunStage;
+    capability?: Definitions[number];
+    ctx?: Ctx;
+    principal: Principal;
+    /** Present only when input validation completed successfully. */
+    input?: unknown;
+    output?: undefined;
+    durationMs: number;
+    error: unknown;
+};
+/** Best-effort lifecycle observer for capability execution. */
+export type AgentCapabilityHook<Ctx, Principal, Definitions extends readonly AnyAgentCapabilityDef[] = readonly AnyAgentCapabilityDef[]> = (event: AgentCapabilityRunEvent<Ctx, Principal, Definitions>) => MaybePromise<void>;
+/** Options for a capability executor. */
+export interface CreateAgentCapabilityExecutorOptions<Ctx, Principal, Definitions extends readonly AnyAgentCapabilityDef[]> {
+    registry: AgentCapabilityRegistry<Definitions>;
+    createContext(request: AgentCapabilityContextRequest<Definitions, Principal>): MaybePromise<Ctx>;
+    hooks?: readonly AgentCapabilityHook<Ctx, Principal, Definitions>[];
+    /** Independent target used to observe failures before context exists. */
+    instrumentation?: ProviderInstrumentationTarget;
+    tracing?: TracingPort;
+}
+/** Raw dynamic invocation accepted by protocol adapters. */
+export interface DynamicAgentCapabilityInvocation<Principal> {
+    name: string;
+    principal: Principal;
+    input: unknown;
+    /**
+     * Transport-owned authorization against the exact parsed input that will be
+     * passed to context construction and the capability handler.
+     */
+    authorize?(request: DynamicAgentCapabilityAuthorization<Principal>): MaybePromise<void>;
+}
+/** Parsed invocation exposed to a dynamic transport authorization callback. */
+export interface DynamicAgentCapabilityAuthorization<Principal> {
+    capability: AnyAgentCapabilityDef;
+    name: string;
+    principal: Principal;
+    input: unknown;
+}
+/** Typed and dynamic execution surface for one capability registry. */
+export interface AgentCapabilityExecutor<Principal, Definitions extends readonly AnyAgentCapabilityDef[]> {
+    execute<Name extends Definitions[number]["name"]>(args: {
+        name: Name;
+        principal: Principal;
+        input: AgentCapabilityInput<Extract<Definitions[number], {
+            name: Name;
+        }>>;
+    }): Promise<AgentCapabilityOutput<Extract<Definitions[number], {
+        name: Name;
+    }>>>;
+    executeDynamic(args: DynamicAgentCapabilityInvocation<Principal>): Promise<unknown>;
+}
+/** Create a validated, traced executor for a capability registry. */
+export declare function createAgentCapabilityExecutor<const Definitions extends readonly AnyAgentCapabilityDef[]>(options: CreateAgentCapabilityExecutorOptions<AgentCapabilityContext<Definitions[number]>, AgentCapabilityPrincipal<Definitions[number]>, Definitions>): AgentCapabilityExecutor<AgentCapabilityPrincipal<Definitions[number]>, Definitions>;
+//# sourceMappingURL=index.d.ts.map

package/dist/agent-capabilities/index.d.ts.map

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