@beignet/core 0.0.33 → 0.0.35

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @beignet/core
 
+## 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
+
+- 8226b4c: Isolate notification channel failures, add app-owned preference checks, provide independently retryable queued delivery through existing job dispatchers, and document the app structure for queued notification workers.
+- 9345cc9: Stabilize the pre-1.0 public surface around factory-only providers, canonical server and testing imports, consistent memory naming, and the removal of deprecated aliases.
+
 ## 0.0.33
 
 ### 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 |
@@ -68,7 +69,6 @@ name the framework area they depend on.
 | `@beignet/core/payments` | Payments port, memory payments adapter, and memory payments provider |
 | `@beignet/core/pagination` | Offset/cursor page types, normalizers, and result helpers |
 | `@beignet/core/ports` | App-facing ports, auth, audit, policies, cache, storage, logging, and redaction |
-| `@beignet/core/ports/testing` | Port and policy test helpers |
 | `@beignet/core/providers` | Provider lifecycle and instrumentation primitives |
 | `@beignet/core/search` | Search index definitions, SearchPort, memory adapter, memory provider, and helpers |
 | `@beignet/core/schedules` | Schedule primitives |
@@ -76,7 +76,7 @@ name the framework area they depend on.
 | `@beignet/core/server-only` | Static lint marker for modules that must stay out of client bundles |
 | `@beignet/core/tasks` | Operational task definitions and inline task execution |
 | `@beignet/core/tenancy` | Branded tenant scope helpers for repository boundaries |
-| `@beignet/core/testing` | Test context factories, memory port fixtures, provider install helper, factories, seeds, and database harnesses |
+| `@beignet/core/testing` | Port and policy assertions, recording adapters, test context factories, memory port fixtures, provider install helper, factories, seeds, and database harnesses |
 | `@beignet/core/tracing` | Dependency-free W3C trace context primitives |
 | `@beignet/core/uploads` | Upload definitions (`createUploads<AppContext>()` app-bound builder), router, signer port, and test signer |
 | `@beignet/core/uploads/client` | Browser upload client for server and direct uploads |
@@ -90,6 +90,74 @@ 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`; `ctx` is undefined until context construction succeeds. 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:
@@ -230,6 +298,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
@@ -271,9 +346,12 @@ provider `name` that defaults to `"memory-mailer"`.
 `{ notifications: NotificationPort }` backed by
 `createInlineNotificationDispatcher(...)`. Channel handlers receive an app
 service context built lazily through the server context blueprint on each
-send, so registration order does not matter. Options accept the dispatcher's
-`onError` handler plus a provider `name` that defaults to
-`"inline-notifications"`.
+send, so registration order does not matter. One failed channel does not block
+the remaining channels. Inline sends return ordered `sent`, `skipped`, and
+`failed` results; queued dispatchers also return `queued`. Set
+`failureMode: "throw"` to reject after every channel has run. Options also
+accept an app-owned `preferences` evaluator, the dispatcher's `onError` result
+mapper, and a provider `name` that defaults to `"inline-notifications"`.
 
 ```typescript
 // server/providers.ts
@@ -290,8 +368,56 @@ export const providers = [
 
 Replace `createMemoryMailerProvider(...)` with a real mail provider such as
 `@beignet/provider-mail-resend` for production delivery. Production apps can
-keep the inline notifications provider and run it from jobs or listeners, or
-replace it with an app-owned dispatcher when delivery needs custom semantics.
+keep the inline provider or define a central notification registry and a
+`defineNotificationDeliveryJob(...)`. Install
+`createQueuedNotificationsProvider(...)` after the app's jobs provider to
+enqueue one independently retryable job per channel. Register the delivery job
+with every BullMQ/Inngest worker or outbox registry that can receive it.
+
+```typescript
+// server/notifications.ts
+import {
+  defineNotificationDeliveryJob,
+  defineNotificationRegistry,
+} from "@beignet/core/notifications";
+import type { AppContext } from "@/app-context";
+import { WelcomeNotification } from "@/features/users/notifications";
+
+export const notificationRegistry = defineNotificationRegistry<AppContext>([
+  WelcomeNotification,
+]);
+
+export const DeliverNotificationJob =
+  defineNotificationDeliveryJob<AppContext>({
+    registry: notificationRegistry,
+  });
+```
+
+```typescript
+// server/index.ts
+import { createQueuedNotificationsProvider } from "@beignet/core/notifications";
+import { createNextServer, createNextServerLoader } from "@beignet/next";
+
+export const getServer = createNextServerLoader(async () => {
+  const { providers } = await import("./providers");
+  const { DeliverNotificationJob } = await import("./notifications");
+
+  return createNextServer({
+    // ...
+    providers: [
+      ...providers,
+      createQueuedNotificationsProvider({
+        deliveryJob: DeliverNotificationJob,
+      }),
+    ],
+  });
+});
+```
+
+The delivery job defaults to three attempts with exponential backoff. The
+queued dispatcher validates notification payloads before enqueueing and uses
+the app's existing `jobs` port, so the same setup works with direct job
+providers or `createOutboxJobDispatcher(...)`.
 
 ## Entitlements
 
@@ -499,6 +625,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,
@@ -534,8 +669,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.
@@ -575,7 +710,7 @@ without importing provider implementation code.
       "requiredTables": ["cache_entries"],
       "registration": {
         "required": true,
-        "tokens": ["cacheProvider", "createCacheProvider"]
+        "tokens": ["createCacheProvider"]
       },
       "watchers": ["cache"]
     }
@@ -730,10 +865,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
 
@@ -794,6 +933,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:
 
@@ -841,7 +984,7 @@ import { createTestContextFactory, createTestPorts } from "@beignet/core/testing
 import {
   createTestTenant,
   createTestUserActor,
-} from "@beignet/core/ports/testing";
+} from "@beignet/core/testing";
 
 const fixture = createTestPorts<AppContext["ports"]>({
   base: appPorts,
@@ -1037,12 +1180,13 @@ Use `installProviderForTest(...)` to run provider setup against test ports
 without hand-rolling setup, port merge, and lifecycle plumbing:
 
 ```ts
+import type { CachePort } from "@beignet/core/ports";
 import { installProviderForTest } from "@beignet/core/testing";
+import { createRedisCacheProvider } from "@beignet/provider-cache-redis";
 
 const { ports, result, start, stop } = await installProviderForTest(
-  redisCacheProvider,
+  createRedisCacheProvider(),
   {
-    ports: { devtools },
     config: { URL: "redis://localhost:6379" },
   },
 );
@@ -1123,7 +1267,7 @@ ORM table objects, or provider SDKs directly.
 
 ### Port testing helpers
 
-Use `@beignet/core/ports/testing` when tests need stable actor, tenant,
+Use `@beignet/core/testing` when tests need stable actor, tenant,
 authorization, or audit assertions:
 
 ```ts
@@ -1133,7 +1277,7 @@ import {
   createTestActivityContext,
   createTestTenant,
   createTestUserActor,
-} from "@beignet/core/ports/testing";
+} from "@beignet/core/testing";
 
 const activity = createTestActivityContext({
   actor: createTestUserActor("user_1", { role: "admin" }),
@@ -1187,7 +1331,7 @@ import {
   createRecordingEventBus,
   createRecordingJobDispatcher,
   createRecordingProviderInstrumentation,
-} from "@beignet/core/ports/testing";
+} from "@beignet/core/testing";
 import { drainOutbox } from "@beignet/core/outbox";
 import { createProviderInstrumentation } from "@beignet/core/providers";
 
@@ -1468,6 +1612,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
@@ -1518,6 +1667,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.
@@ -1534,7 +1688,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,
@@ -1545,9 +1699,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
 
@@ -1580,8 +1735,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>()({
@@ -1590,7 +1750,7 @@ const auth = createAuthHooks<AppContext>()({
   },
 });
 
-export const messageRoutes = defineRouteGroup<AppContext>()({
+export const messageRoutes = defineRouteGroup({
   name: "messages",
   routes: [
     {
@@ -1612,7 +1772,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
@@ -1806,6 +1966,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.
@@ -1867,12 +2031,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:
@@ -1883,7 +2058,6 @@ getTodo.schema.query;      // Query parameter schema
 getTodo.schema.body;       // Request body schema
 getTodo.schema.responses;  // Response schemas by status code
 getTodo.path;              // "/api/todos/:id"
-getTodo.pathTemplate;      // "/api/todos/:id" (alias)
 getTodo.method;            // "GET"
 getTodo.metadata;          // { auth: "required", ... }
 ```
@@ -1930,8 +2104,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
 
@@ -1941,7 +2115,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,167 @@
+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 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";
+/** Lifecycle event observed around a capability attempt. */
+export interface AgentCapabilityRunEvent<Ctx, Principal> {
+    name: string;
+    phase: "start" | "end" | "error";
+    stage: AgentCapabilityRunStage;
+    ctx?: Ctx;
+    principal: Principal;
+    durationMs?: number;
+    error?: unknown;
+}
+/** Best-effort lifecycle observer for capability execution. */
+export type AgentCapabilityHook<Ctx, Principal> = (event: AgentCapabilityRunEvent<Ctx, Principal>) => 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>[];
+    /** 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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"}