apps 0.0.1-beta.2 → 0.0.1-beta.21

package/types/apps/src/implementation/catalog-cache.d.ts

@@ -1,8 +1,8 @@
 import { Duration, Effect, Schema } from "effect";
 import type { AppCache, CacheLoadContext } from "../contracts/cache.js";
-import { type JsonValue } from "../contracts/schema.js";
+import { JsonObject, type JsonValue } from "../contracts/schema.js";
 export interface CatalogCacheOptions {
-    /** App/build scope, optionally narrowed to the current account. */
+    /** The app's cache. An account's catalog is kept in that account's scope. */
     readonly cache?: AppCache;
     /** Reuse metadata for this duration. Defaults to five minutes. */
     readonly freshFor?: Duration.Input;
@@ -11,9 +11,37 @@ export interface CatalogCacheOptions {
     /** Await a fresh revision at an explicit logical connection or refresh boundary. */
     readonly revalidate?: boolean;
 }
+/**
+ * Whose catalog a remote router reads. A public server takes neither field. Credential headers
+ * come only with the account they belong to, so an authenticated catalog always has its account.
+ */
+export type CatalogAccount = {
+    readonly account?: undefined;
+    readonly headers?: undefined;
+} | {
+    /** The selected account, as `accounts.<slot>` provides it. */
+    readonly account: {
+        readonly id: string;
+    };
+    /** Headers for this account's requests, such as its credentials. */
+    readonly headers?: Readonly<Record<string, string>>;
+};
+/**
+ * The cache an account's catalog lives in: the account's own scope, which token renewals keep.
+ * Credentials never enter a key. Headers without an account, or an account the app was not
+ * given, fail with `invalid`.
+ */
+export declare const catalogScope: <E>(options: CatalogCacheOptions & CatalogAccount, invalid: () => E) => Effect.Effect<AppCache | undefined, E>;
+/** One load: the tools, and optionally a record describing the whole catalog. */
+export interface CatalogLoad<A> {
+    readonly tools: readonly A[];
+    readonly header?: JsonObject;
+}
 export declare const catalogCache: <A extends {
     readonly name: string;
-}, S>(options: CatalogCacheOptions & {
+}, S>(options: Omit<CatalogCacheOptions, "cache"> & {
+    /** The scope from `catalogScope`; undefined keeps discovery invocation-local. */
+    readonly cache: AppCache | undefined;
     readonly prefix: readonly JsonValue[];
     readonly schema: Schema.Decoder<A>;
     /** Schema-free projection stored beside the full pages, so browsing never reads schemas. */
@@ -21,9 +49,11 @@ export declare const catalogCache: <A extends {
         readonly schema: Schema.Decoder<S>;
         readonly of: (tool: A) => S;
     };
-    readonly load: (context?: CacheLoadContext) => Effect.Effect<readonly A[], unknown>;
+    readonly load: (context?: CacheLoadContext) => Effect.Effect<CatalogLoad<A>, unknown>;
 }) => Effect.Effect<{
     list: () => Effect.Effect<readonly A[], unknown, never>;
+    /** The record stored with the current revision, if the source supplied one. */
+    header: () => Effect.Effect<JsonObject | undefined, unknown>;
     summaries: () => Effect.Effect<S[], unknown, never>;
     resolve: (name: string) => Effect.Effect<A | undefined, unknown, never>;
 }, unknown, never>;

package/types/apps/src/implementation/elicitation.d.ts

@@ -58,18 +58,18 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
                 } | {
                     readonly type: "string";
                     readonly default?: string;
-                    readonly format?: "email" | "uri" | "date" | "date-time";
                     readonly description?: string;
+                    readonly format?: "email" | "uri" | "date" | "date-time";
                     readonly title?: string;
                     readonly minLength?: number;
                     readonly maxLength?: number;
                 } | {
                     readonly type: "number" | "integer";
                     readonly default?: number;
+                    readonly maximum?: number;
                     readonly description?: string;
                     readonly title?: string;
                     readonly minimum?: number;
-                    readonly maximum?: number;
                 } | {
                     readonly type: "boolean";
                     readonly default?: boolean;

package/types/apps/src/implementation/failure-detail.d.ts

@@ -0,0 +1,26 @@
+import { Redacted } from "effect";
+import type { ResolvedAccounts } from "../contracts/host.js";
+/** Fields of `FailureDetail` as constructor input. */
+export interface FailureDetail {
+    readonly source?: "app" | "storage" | "service";
+    readonly errorName?: string;
+    readonly code?: string;
+    readonly message?: string;
+}
+/**
+ * Every credential field value of a slot-to-account record, longest first. Accepts both resolved
+ * host accounts and bound author accounts; each account keeps its credential values in `fields`.
+ */
+export declare const accountFieldSecrets: (accounts: unknown) => string[];
+/** Every credential field value of an invocation's selected accounts. */
+export declare const accountSecrets: (accounts: Redacted.Redacted<ResolvedAccounts>) => string[];
+/** Replace account secrets and bound the message for the runtime boundary. */
+export declare const boundFailureMessage: (message: string, secrets: readonly string[]) => string;
+/** `Name: message` for any thrown value, before redaction. */
+export declare const describeFailure: (error: unknown) => string;
+/**
+ * Describe what an operation raised for the app's own caller. App data failures keep their
+ * reason as a code, as do app cache failures; any other thrown value is the app's own error.
+ * Account secrets are replaced.
+ */
+export declare const failureDetail: (error: unknown, secrets: readonly string[]) => FailureDetail;

package/types/apps/src/implementation/graphql-catalog.d.ts

@@ -1,10 +1,7 @@
 import { Effect } from "effect";
 import { GraphqlToolsOptions } from "../contracts/graphql.js";
-import type { DynamicTools } from "../contracts/dynamic-tools.js";
-import { type CatalogCacheOptions } from "./catalog-cache.js";
+import { type CatalogAccount, type CatalogCacheOptions } from "./catalog-cache.js";
 import { type OperationKinds } from "./protocol-operations.js";
-export interface GraphqlCatalogOptions extends GraphqlToolsOptions, CatalogCacheOptions {
-}
-export declare const graphqlCatalog: (options: GraphqlCatalogOptions, kinds: OperationKinds) => Effect.Effect<{
-    dynamicTools: DynamicTools;
-}, unknown, never>;
+/** An endpoint, the account whose schema it is, and the metadata policy. */
+export type GraphqlCatalogOptions = Omit<GraphqlToolsOptions, "accountId" | "headers"> & CatalogCacheOptions & CatalogAccount;
+export declare const graphqlCatalog: (options: GraphqlCatalogOptions, kinds: OperationKinds) => Effect.Effect<import("./operations.js").RouterDeclaration<unknown, unknown>, unknown, never>;

package/types/apps/src/implementation/mcp-catalog.d.ts

@@ -1,12 +1,11 @@
 import { Effect } from "effect";
-import type { DynamicTools } from "../contracts/dynamic-tools.js";
 import { McpToolsOptions } from "../contracts/mcp.js";
-import { type CatalogCacheOptions } from "./catalog-cache.js";
+import { type CatalogAccount, type CatalogCacheOptions } from "./catalog-cache.js";
 import { type OperationKinds } from "./protocol-operations.js";
-/** Metadata policy for HTTP/SSE sources. A missing cache keeps discovery invocation-local. */
-export interface McpCatalogOptions extends McpToolsOptions, CatalogCacheOptions {
-}
+/**
+ * A server, the account whose catalog it is, and the metadata policy for HTTP/SSE sources. A
+ * missing cache keeps discovery invocation-local.
+ */
+export type McpCatalogOptions = Omit<McpToolsOptions, "accountId" | "headers"> & CatalogCacheOptions & CatalogAccount;
 /** Construction opens no transport unless explicit revalidation is requested. */
-export declare const mcpCatalog: (options: McpCatalogOptions, kinds: OperationKinds) => Effect.Effect<{
-    dynamicTools: DynamicTools;
-}, unknown, never>;
+export declare const mcpCatalog: (options: McpCatalogOptions, kinds: OperationKinds) => Effect.Effect<import("./operations.js").RouterDeclaration<unknown, unknown>, unknown, never>;

package/types/apps/src/implementation/mcp-client.d.ts

@@ -14,26 +14,42 @@ export interface WithMcpClient {
 /** Shared client operations never cache catalogs or account credentials. */
 export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number, failure: (phase: McpError["phase"], error: unknown) => McpError | ProviderError): {
     list: Effect.Effect<{
-        readonly name: string;
-        readonly inputSchema: {
-            readonly [x: string]: Schema.Json;
-        };
-        readonly description?: string | undefined;
-        readonly _meta?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly title?: string | undefined;
-        readonly outputSchema?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly annotations?: {
+        tools: {
+            readonly name: string;
+            readonly inputSchema: {
+                readonly [x: string]: Schema.Json;
+            };
+            readonly description?: string | undefined;
+            readonly _meta?: {
+                readonly [x: string]: Schema.Json;
+            } | undefined;
+            readonly title?: string | undefined;
+            readonly annotations?: {
+                readonly title?: string;
+                readonly readOnlyHint?: boolean;
+                readonly destructiveHint?: boolean;
+                readonly idempotentHint?: boolean;
+                readonly openWorldHint?: boolean;
+            } | undefined;
+            readonly outputSchema?: {
+                readonly [x: string]: Schema.Json;
+            } | undefined;
+        }[];
+        server: {
+            readonly version?: string;
+            readonly name?: string;
+            readonly description?: string;
             readonly title?: string;
-            readonly readOnlyHint?: boolean;
-            readonly destructiveHint?: boolean;
-            readonly idempotentHint?: boolean;
-            readonly openWorldHint?: boolean;
-        } | undefined;
-    }[], ProviderError | McpError, never>;
+            readonly instructions?: string;
+            readonly icons?: readonly {
+                readonly src: string;
+                readonly mimeType?: string;
+                readonly sizes?: readonly string[];
+                readonly theme?: "light" | "dark";
+            }[];
+            readonly websiteUrl?: string;
+        } | {};
+    }, ProviderError | McpError, never>;
     call: (name: string, input: JsonObject, context: McpToolContext) => Effect.Effect<{
         readonly content: readonly {
             readonly [x: string]: Schema.Json;

package/types/apps/src/implementation/mcp.d.ts

@@ -4,26 +4,42 @@ import { McpError, McpToolsOptions } from "../contracts/mcp.js";
 /** Discover and call with a fresh selected-account transport for each operation. */
 export declare const mcpClientEffect: (input: McpToolsOptions, changed?: Effect.Effect<void, unknown>) => Effect.Effect<{
     list: Effect.Effect<{
-        readonly name: string;
-        readonly inputSchema: {
-            readonly [x: string]: Schema.Json;
-        };
-        readonly description?: string | undefined;
-        readonly _meta?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly title?: string | undefined;
-        readonly outputSchema?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly annotations?: {
+        tools: {
+            readonly name: string;
+            readonly inputSchema: {
+                readonly [x: string]: Schema.Json;
+            };
+            readonly description?: string | undefined;
+            readonly _meta?: {
+                readonly [x: string]: Schema.Json;
+            } | undefined;
+            readonly title?: string | undefined;
+            readonly annotations?: {
+                readonly title?: string;
+                readonly readOnlyHint?: boolean;
+                readonly destructiveHint?: boolean;
+                readonly idempotentHint?: boolean;
+                readonly openWorldHint?: boolean;
+            } | undefined;
+            readonly outputSchema?: {
+                readonly [x: string]: Schema.Json;
+            } | undefined;
+        }[];
+        server: {
+            readonly version?: string;
+            readonly name?: string;
+            readonly description?: string;
             readonly title?: string;
-            readonly readOnlyHint?: boolean;
-            readonly destructiveHint?: boolean;
-            readonly idempotentHint?: boolean;
-            readonly openWorldHint?: boolean;
-        } | undefined;
-    }[], ProviderError | McpError, never>;
+            readonly instructions?: string;
+            readonly icons?: readonly {
+                readonly src: string;
+                readonly mimeType?: string;
+                readonly sizes?: readonly string[];
+                readonly theme?: "light" | "dark";
+            }[];
+            readonly websiteUrl?: string;
+        } | {};
+    }, ProviderError | McpError, never>;
     call: (name: string, input: import("../index.js").JsonObject, context: import("../mcp.js").McpToolContext) => Effect.Effect<{
         readonly content: readonly {
             readonly [x: string]: Schema.Json;

package/types/apps/src/implementation/openapi-compile.d.ts

@@ -4,8 +4,11 @@ import { JsonObject } from "../contracts/schema.js";
 import { OpenapiCompileError as TemplateError } from "../contracts/openapi-compile.js";
 import type { OpenApiImport } from "../contracts/openapi-document.js";
 import { type GeneratedOperation, type GeneratedSecrets } from "../contracts/openapi-document.js";
-/** Compile a revision of a live OpenAPI source into tool declarations for the app runtime. */
-export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocument: unknown, options?: {
+/** Compile a revision of a live OpenAPI source into tool declarations for the app runtime.
+ * The document is consumed: compilation upgrades it in place instead of copying it. It must be a
+ * tree, with no object reached twice, as parsed JSON is.
+ */
+export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocument: JsonObject, options?: {
     readonly baseUrl?: string;
     readonly allowedOrigin?: string;
     readonly securitySchemes?: Readonly<Record<string, JsonObject>>;
@@ -13,8 +16,6 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
 }) => Effect.Effect<{
     operations: {
         readonly name: string;
-        readonly path: string;
-        readonly description: string;
         readonly request: {
             readonly parameters: readonly {
                 readonly name: string;
@@ -53,10 +54,12 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
                 readonly required?: boolean;
             };
         };
+        readonly path: string;
+        readonly description: string;
         readonly input: {
             readonly [x: string]: Schema.Json;
         };
-        readonly method: "HEAD" | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
+        readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
         readonly securitySchemes: {
             readonly [x: string]: {
                 readonly [x: string]: Schema.Json;
@@ -67,6 +70,7 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
         readonly outputSchema?: {
             readonly [x: string]: Schema.Json;
         };
+        readonly tags?: readonly string[];
         readonly operationId?: string;
         readonly streaming?: true;
         readonly errorResponses?: readonly {

package/types/apps/src/implementation/openapi-document.d.ts

@@ -1,11 +1,24 @@
 import { Schema } from "effect";
 import { JsonObject } from "../contracts/schema.js";
-/** Resolve OpenAPI objects once with Swagger; schemas retain their original recursive references.
+/**
+ * An object in a document that was validated as JSON when it was read. Compilation only turns JSON
+ * into JSON, so inside it an object's shape is checked, not its every leaf again: re-validating
+ * whole documents was most of a large API's compile time.
+ */
+export declare const DocumentObject: Schema.declare<{
+    readonly [x: string]: Schema.Json;
+}, {
+    readonly [x: string]: Schema.Json;
+}>;
+export declare const documentObject: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
+    readonly [x: string]: Schema.Json;
+};
+/** Resolve OpenAPI objects once; schemas retain their original recursive references.
  * Scalar first upgrades Swagger 2.0 and OpenAPI 3.0 to 3.1, so the importer has one dialect and
  * 3.1 keywords that appear in 3.0 documents keep their meaning.
  * Unsupported versions, references and conversions throw TemplateError at the import boundary.
  */
-export declare function openApiDocument(input: unknown): Promise<{
+export declare function openApiDocument(input: JsonObject): Promise<{
     spec: {
         readonly openapi: string;
         readonly paths: {

package/types/apps/src/implementation/openapi-request.d.ts

@@ -6,12 +6,19 @@ import { OpenapiError, type CredentialBinding, type OpenapiOperation, type Opena
 type DeclaredError = OpenapiErrorResponse & {
     readonly decoder: Schema.Decoder<Schema.Json>;
 };
+/** What decides whether an account can call an operation: its transport and security. */
+export interface OpenapiOperationAccess {
+    readonly streaming?: true;
+    readonly request: {
+        readonly security: OpenapiOperation["request"]["security"];
+    };
+}
 /** Create request helpers from credential-free generated authentication metadata. */
 export declare function createRequest(config: {
     readonly methods: Readonly<Record<string, readonly CredentialBinding[]>>;
     readonly oauth: readonly string[];
 }): {
-    available: (op: OpenapiOperation, account: OpenapiAccount | undefined) => boolean;
+    available: (op: OpenapiOperationAccess, account: OpenapiAccount | undefined) => boolean;
     call: (op: OpenapiOperation, input: unknown, account: OpenapiAccount | undefined, errors: readonly DeclaredError[]) => Effect.Effect<Schema.Json, ProviderError | OpenapiResponseError | OpenapiError, never>;
 };
 export {};

package/types/apps/src/implementation/openapi-source.d.ts

@@ -3,8 +3,8 @@ import { Duration } from "effect";
 import type { AppCache } from "../contracts/cache.js";
 import { OpenapiOperation, type OpenapiToolsOptions } from "../contracts/openapi.js";
 import { JsonObject, JsonValue } from "../contracts/schema.js";
-import type { DynamicTools } from "../contracts/dynamic-tools.js";
 import { type OperationKinds } from "./protocol-operations.js";
+import { type RouterDeclaration } from "./router.js";
 /** Static credential placement and destination are reviewed when the app is authored/imported. */
 export interface OpenapiSourceOptions extends Omit<OpenapiToolsOptions, "operations" | "definitions"> {
     readonly cache: AppCache;
@@ -33,8 +33,4 @@ export interface OpenapiSourceOptions extends Omit<OpenapiToolsOptions, "operati
 /** JSON-object patches are static app configuration and are reapplied to every revision. */
 export declare function patchOpenapi(root: JsonObject, patches: OpenapiSourceOptions["patches"]): JsonObject;
 /** No I/O during app construction. All accounts share credential-free compilation. */
-export declare const liveOpenapiOperations: (options: OpenapiSourceOptions) => {
-    readonly queries: {};
-    readonly mutations: {};
-    readonly dynamicTools: DynamicTools;
-};
+export declare const liveOpenapiRouter: (options: OpenapiSourceOptions) => RouterDeclaration;

package/types/apps/src/implementation/openapi-upgrade.d.ts

@@ -0,0 +1,4 @@
+type Node = Record<string, unknown>;
+/** Upgrade a 3.0 document the caller owns. Any other version is returned unchanged. */
+export declare const upgradeOpenApi30InPlace: (document: Node) => Node;
+export {};

package/types/apps/src/implementation/operations.d.ts

@@ -7,16 +7,39 @@ import type { ToolAnnotations } from "../contracts/tools.js";
 import type { JsonObject } from "../contracts/schema.js";
 import { type Schema } from "./schema.js";
 declare const NativeOperation: unique symbol;
-declare const HandlerContext: unique symbol;
-/** A server-only declaration with its category preserved for catalog validation. */
+declare const QueryHandlerContext: unique symbol;
+declare const MutationHandlerContext: unique symbol;
+/**
+ * A server-only declaration with its category preserved for catalog validation. Queries and
+ * mutations carry their handler context under different phantom keys, so a router can type a
+ * query's handler from its query context alone.
+ */
 export interface OperationDeclaration<Kind extends "query" | "mutation", Context = never> {
-    readonly [HandlerContext]?: (context: Context) => void;
+    readonly [QueryHandlerContext]?: "query" extends Kind ? (context: Context) => void : never;
+    readonly [MutationHandlerContext]?: "mutation" extends Kind ? (context: Context) => void : never;
     readonly kind: Kind;
     readonly [NativeOperation]: Omit<AppOperation<never>, "kind" | "input"> & {
         readonly kind: Kind;
         readonly input: EffectSchema.Decoder<unknown>;
     };
 }
+/**
+ * A router declaration. The phantom contexts let `defineApp` type inline handlers; protocol
+ * routers accept any context because their operations only use the framework's own capabilities.
+ * The native router is held under a private key in implementation/router.ts.
+ */
+export interface RouterDeclaration<Query = unknown, Mutation = unknown> {
+    readonly [QueryHandlerContext]?: (context: Query) => void;
+    readonly [MutationHandlerContext]?: (context: Mutation) => void;
+    readonly [NativeRouterKey]: unknown;
+}
+/** An operation or nested router under one key. Each child is typed only by its own kind's context. */
+export interface RouterChild<Query, Mutation> {
+    readonly [QueryHandlerContext]?: (context: Query) => void;
+    readonly [MutationHandlerContext]?: (context: Mutation) => void;
+}
+/** Private key for a router's native definition. */
+export declare const NativeRouterKey: unique symbol;
 /** Typed operation handles drive browser reference inference without bundling handlers. */
 export interface Operation<Input, Output, Kind extends "query" | "mutation", Context = AppContext> extends OperationDeclaration<Kind, Context> {
     readonly [NativeOperation]: AppOperation<Input, Output> & {
@@ -56,8 +79,18 @@ export declare const operationOptions: <Input, Output>(options: OperationOptions
     title?: string;
     description?: string;
 };
+/**
+ * Replace a native operation's approval. Property descriptors are copied so an output schema that
+ * a protocol adapter builds only when read stays lazy.
+ */
+export declare const approvedOperation: <Input, Native extends AppOperation<Input, unknown>>(operation: Native, approval: Approval<Input>) => Native;
 /** Attach the same approval function to a generated or shared operation. */
 export declare const withApproval: <Input, Output, Kind extends "query" | "mutation", Context>(operation: Operation<Input, Output, Kind, Context>, approval: Approval<Input>) => Operation<Input, Output, Kind, Context>;
+/**
+ * The advisory hints an operation carries, such as an MCP server's `destructiveHint`. App code
+ * reads them to choose an approval; the framework never infers one from them.
+ */
+export declare const toolAnnotations: (operation: OperationDeclaration<"query" | "mutation", never>) => ToolAnnotations | undefined;
 /** Read operation. External reads are allowed; only database writes are mechanically prohibited. */
 export declare const query: <Input, Output, Context extends AppContext = QueryContext>(options: OperationOptions<Input, Output>, run: (context: Context, input: Input) => Promise<Output>) => Operation<Input, Output, "query", Context>;
 /** Explicit write operation. Database writes roll back on failure; external effects cannot be undone. */

package/types/apps/src/implementation/protocol-operations.d.ts

@@ -17,8 +17,7 @@ interface ProtocolOperation {
     readonly run: (context: OperationContext, input: JsonValue) => Effect.Effect<unknown, unknown>;
 }
 /** Unknown behavior defaults to mutation. Classification never enforces an external service's behavior. */
-export declare const protocolOperations: (operations: Readonly<Record<string, ProtocolOperation>>, kinds?: OperationKinds) => {
-    queries: Record<string, Operation<Schema.Json, unknown, "query", OperationContext>>;
-    mutations: Record<string, Operation<Schema.Json, unknown, "mutation", OperationContext>>;
-};
+export declare const protocolOperations: (operations: Readonly<Record<string, ProtocolOperation>>, kinds?: OperationKinds) => Record<string, Operation<Schema.Json, unknown, "query" | "mutation", OperationContext>>;
+/** Operations already discovered, as a router keyed by upstream name. */
+export declare const protocolRouter: (operations: Readonly<Record<string, ProtocolOperation>>, kinds?: OperationKinds) => import("./operations.js").RouterDeclaration<unknown, unknown>;
 export {};

package/types/apps/src/implementation/provider.d.ts

@@ -1,16 +1,30 @@
 /** Pure constructors over the native provider contracts. */
 import { Effect, Schema } from "effect";
-import { type AuthMethods, OAuth2Config, OAuth2Method, Provider, SecretsMethod } from "../contracts/provider.js";
+import { type PromiseMethod } from "./authoring.js";
+import { type AccountCheck, type AuthMethods, type FieldExposure, OAuth2Config, OAuth2Method, Provider, SecretsMethod } from "../contracts/provider.js";
 import type { ValidationError } from "../contracts/schema.js";
 /** Declare a secrets method with an Effect decoder. */
 export declare const secrets: <Fields extends Schema.Decoder<unknown>>(options: {
     readonly label: string;
     readonly fields: Fields;
+    readonly exposure?: Readonly<Record<string, FieldExposure>>;
 }) => SecretsMethod<Fields>;
 /** Validate OAuth endpoints while declaring their app-visible response projection. */
-export declare const oauth2: <Response extends Schema.Decoder<unknown>>(config: OAuth2Config, response: Response) => Effect.Effect<OAuth2Method<Response>, ValidationError>;
-/** Retain the provider and literal method names without registering or authenticating it. */
-export declare const defineProvider: <const Auth extends AuthMethods>(options: {
+export declare const oauth2: <Response extends Schema.Decoder<unknown>>(config: OAuth2Config, response: Response, exposure?: Readonly<Record<string, FieldExposure>>) => Effect.Effect<OAuth2Method<Response>, ValidationError>;
+/** Author options: the account check is an ordinary async function. */
+export interface ProviderOptions<Auth extends AuthMethods> {
     readonly name: string;
     readonly auth: Auth;
-}) => Provider<Auth>;
+    /**
+     * Hosts the credentials may be sent to: `api.example.com`, `api.example.com:8443`, or
+     * `*.example.com` for one level of subdomain. Secret fields then reach app code as handles
+     * that the outbound network replaces only on requests to these hosts. An account records the
+     * hosts it was connected for; changing them does not change the provider, but an existing
+     * account sends only to hosts it was connected for until it is connected again.
+     */
+    readonly hosts?: readonly string[];
+    /** Verify a connected account with a safe read, optionally reporting its upstream identity. */
+    readonly health?: PromiseMethod<AccountCheck<Auth>["run"]>;
+}
+/** Retain the provider and literal method names without registering or authenticating it. */
+export declare const defineProvider: <const Auth extends AuthMethods>({ health, ...options }: ProviderOptions<Auth>) => Provider<Auth>;