apps 0.0.1-beta.5 → 0.0.1-beta.7

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

@@ -1,5 +1,5 @@
 /** Provider declarations use native Effect schemas. The trusted host interprets them. */
-import { Data, Schema } from "effect";
+import { Data, type Effect, Schema } from "effect";
 import { type AccountId } from "./schema.js";
 declare const SecretsMethod_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Readonly<A> & {
     readonly _tag: "secrets";
@@ -84,10 +84,54 @@ export declare class OAuth2Method<Response extends Schema.Decoder<unknown>> exte
 export type AuthMethod = SecretsMethod<Schema.Decoder<unknown>> | OAuth2Method<Schema.Decoder<unknown>>;
 /** Auth method names are chosen by the provider author. */
 export type AuthMethods = Readonly<Record<string, AuthMethod>>;
-/** A provider declaration. The future host derives its identity from normalized content. */
+/**
+ * Upstream identity that a passing account check may report for display. Only these fields are
+ * retained; the host never stores raw provider responses.
+ */
+export declare const AccountInfo: Schema.Struct<{
+    readonly externalId: Schema.optionalKey<Schema.String>;
+    readonly displayName: Schema.optionalKey<Schema.String>;
+    readonly username: Schema.optionalKey<Schema.String>;
+    readonly email: Schema.optionalKey<Schema.String>;
+    readonly avatarUrl: Schema.optionalKey<Schema.String>;
+    readonly profileUrl: Schema.optionalKey<Schema.String>;
+}>;
+export type AccountInfo = typeof AccountInfo.Type;
+/** A passing account check. Failures are thrown, so there is no failing variant. */
+export declare const AccountCheckResult: Schema.Struct<{
+    readonly accountInfo: Schema.optionalKey<Schema.Struct<{
+        readonly externalId: Schema.optionalKey<Schema.String>;
+        readonly displayName: Schema.optionalKey<Schema.String>;
+        readonly username: Schema.optionalKey<Schema.String>;
+        readonly email: Schema.optionalKey<Schema.String>;
+        readonly avatarUrl: Schema.optionalKey<Schema.String>;
+        readonly profileUrl: Schema.optionalKey<Schema.String>;
+    }>>;
+}>;
+export type AccountCheckResult = typeof AccountCheckResult.Type;
+/** The account a provider's check verifies, with invocation-owned HTTP and cancellation. */
+export interface AccountCheckContext<Auth extends AuthMethods> {
+    readonly account: AccountOfMethods<Auth>;
+    readonly fetch: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+    readonly signal: AbortSignal;
+}
+/**
+ * A safe authenticated read proving the account works for this app. Returning passes; a thrown
+ * `ProviderError` or HTTP status failure classifies the problem. Any other failure, including a
+ * timeout, means the check could not verify the account, not that its credentials are bad.
+ */
+export interface AccountCheck<Auth extends AuthMethods> {
+    run(context: AccountCheckContext<Auth>): Effect.Effect<AccountCheckResult | void, unknown>;
+}
+/** A provider declaration. The host derives its identity from the declaration, never its check. */
 export declare class Provider<Auth extends AuthMethods> extends Data.Class<{
     readonly name: string;
     readonly auth: Auth;
+    /**
+     * Stored without its method types so a specific provider still fills a general slot. The host
+     * binds the account against this provider's methods before running it.
+     */
+    readonly health?: AccountCheck<AuthMethods>;
 }> {
     /** Declare zero or more accounts from this provider without performing I/O. */
     many(): ManyAccounts<Auth>;
@@ -102,12 +146,14 @@ export declare class ManyAccounts<Auth extends AuthMethods> extends ManyAccounts
 }
 /** Infer the data for one method from its native Effect decoder. */
 export type AuthMethodData<Method> = Method extends SecretsMethod<infer Fields> ? Fields["Type"] : Method extends OAuth2Method<infer Response> ? Response["Type"] : never;
-/** One selected account, discriminated by its author-chosen method name. */
-export type AccountOf<P> = P extends Provider<infer Auth> ? {
+/** One account for these methods, discriminated by its author-chosen method name. */
+export type AccountOfMethods<Auth extends AuthMethods> = {
     readonly [Method in keyof Auth & string]: {
         readonly id: AccountId;
         readonly method: Method;
         readonly fields: AuthMethodData<Auth[Method]>;
     };
-}[keyof Auth & string] : never;
+}[keyof Auth & string];
+/** One selected account, discriminated by its author-chosen method name. */
+export type AccountOf<P> = P extends Provider<infer Auth> ? AccountOfMethods<Auth> : never;
 export {};

package/types/apps/src/contracts/router.d.ts

@@ -0,0 +1,59 @@
+/** Routers group operations. Keys form tool paths; each operation keeps its own kind. */
+import { Schema, type Effect } from "effect";
+import type { HostedTool, HostedToolSummary } from "./host.js";
+import type { AppOperation } from "./operations.js";
+/** Object keys that JavaScript gives special meaning, so no router may use them. */
+export declare const reservedRouterKeys: ReadonlySet<string>;
+/** One static path segment. Dots separate segments, so a key never contains one. */
+export declare const RouterKey: Schema.String;
+/** An image a client may show beside a router, such as an MCP server's own icon. Models never read it. */
+export declare const RouterIcon: Schema.Struct<{
+    readonly src: Schema.NonEmptyString;
+    readonly mimeType: Schema.optionalKey<Schema.String>;
+    readonly sizes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly theme: Schema.optionalKey<Schema.Literals<readonly ["light", "dark"]>>;
+}>;
+export type RouterIcon = typeof RouterIcon.Type;
+/**
+ * What an agent should know about a group of tools. `instructions` is published as a skill;
+ * `tags` describes labels that tools in this router carry, such as OpenAPI tags.
+ */
+export declare const RouterMeta: Schema.Struct<{
+    readonly title: Schema.optionalKey<Schema.String>;
+    readonly description: Schema.optionalKey<Schema.String>;
+    readonly instructions: Schema.optionalKey<Schema.String>;
+    readonly icons: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly src: Schema.NonEmptyString;
+        readonly mimeType: Schema.optionalKey<Schema.String>;
+        readonly sizes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly theme: Schema.optionalKey<Schema.Literals<readonly ["light", "dark"]>>;
+    }>>>;
+    readonly tags: Schema.optionalKey<Schema.$Record<Schema.NonEmptyString, Schema.String>>;
+}>;
+export type RouterMeta = typeof RouterMeta.Type;
+/** A statically declared router. Children are operations or further routers. */
+export interface AppRouter {
+    readonly kind: "router";
+    readonly meta?: RouterMeta;
+    readonly children: Readonly<Record<string, AppNode>>;
+}
+/**
+ * A router whose tools are discovered when read, such as an MCP server or OpenAPI document.
+ * Names are relative to the router and may contain dots. `readOnly: true` marks a query;
+ * anything else is a mutation. Resolution never requires listing.
+ */
+export interface DynamicRouter {
+    readonly kind: "dynamic";
+    /** Metadata supplied by the source. Author metadata on the router takes precedence. */
+    readonly meta?: () => Effect.Effect<RouterMeta, unknown>;
+    readonly list: () => Effect.Effect<readonly HostedTool[], unknown>;
+    readonly resolve: (name: string) => Effect.Effect<AppOperation | undefined, unknown>;
+    /** Names and descriptions without schemas. Omitted sources reduce list(). */
+    readonly summaries?: () => Effect.Effect<readonly HostedToolSummary[], unknown>;
+    /** One tool's full metadata without listing. Omitted sources search list(). */
+    readonly describe?: (name: string) => Effect.Effect<HostedTool | undefined, unknown>;
+    /** Static author metadata, merged over the source's metadata. */
+    readonly overrides?: RouterMeta;
+}
+/** Anything a router can contain. */
+export type AppNode = AppOperation | AppRouter | DynamicRouter;

package/types/apps/src/graphql.d.ts

@@ -4,7 +4,5 @@ import { type GraphqlCatalogOptions } from "./implementation/graphql-catalog.js"
 export { GraphqlError, type GraphqlToolsOptions } from "./contracts/graphql.js";
 export type { GraphqlCatalogOptions } from "./implementation/graphql-catalog.js";
 /** Lazy tools with optional persistent metadata caching for the selected account. */
-export declare const graphqlOperations: (options: GraphqlCatalogOptions, kinds?: OperationKinds) => Promise<{
-    dynamicTools: import("./contracts/dynamic-tools.js").DynamicTools;
-}>;
+export declare const graphqlRouter: (options: GraphqlCatalogOptions, kinds?: OperationKinds) => Promise<import("./index.js").RouterDeclaration<unknown, unknown>>;
 export type { OperationKinds } from "./implementation/protocol-operations.js";

package/types/apps/src/implementation/account-router.d.ts

@@ -0,0 +1,12 @@
+import { type RouterDeclaration } from "./router.js";
+/**
+ * Discover each selected account's router and combine matching names.
+ * Calls take { accountId, input }; each branch retains its account's input schema,
+ * credentials, approval and output validation. Empty selections expose no operations.
+ * Discovery is sequential and cancellation follows the caller's signal.
+ */
+export declare const accountRouter: <Account extends {
+    readonly id: string;
+}>(accounts: readonly Account[], discover: (account: Account) => Promise<RouterDeclaration>, options: {
+    readonly signal: AbortSignal;
+}) => Promise<RouterDeclaration>;

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

@@ -4,7 +4,7 @@ import type { AppRequirements, AppContext, QueryContext, MutationContext, Webhoo
 import { type PromiseMethods } from "./authoring.js";
 import { type WorkflowDeclaration } from "./workflows.js";
 import type { WorkflowContext } from "../contracts/workflows.js";
-import { type OperationDeclaration } from "./operations.js";
+import { type RouterDeclaration } from "./router.js";
 import { type Schema } from "./schema.js";
 type PromiseCatalog<Catalog> = Catalog extends Readonly<Record<string, object>> ? {
     readonly [Name in keyof Catalog]: {
@@ -14,15 +14,16 @@ type PromiseCatalog<Catalog> = Catalog extends Readonly<Record<string, object>>
 /** Author definition projected from native capabilities. Excluding callable objects keeps
  * factories from being inferred as definitions and preserves contextual handler inference. */
 export type AppDefinition<Requirements extends AppRequirements> = {
-    readonly [Key in keyof NativeDefinition<WebhookContext<Requirements>>]: Key extends "workflows" ? Readonly<Record<string, WorkflowDeclaration<WorkflowContext<Requirements>>>> : Key extends "schedules" ? Readonly<Record<string, ScheduleDeclaration<MutationContext<Requirements>>>> : Key extends "queries" ? Readonly<Record<string, OperationDeclaration<"query", QueryContext<Requirements>>>> : Key extends "mutations" ? Readonly<Record<string, OperationDeclaration<"mutation", MutationContext<Requirements>>>> : Key extends "webhooks" ? PromiseCatalog<NonNullable<NativeDefinition<WebhookContext<Requirements>>[Key]>> : NativeDefinition<WebhookContext<Requirements>>[Key];
+    readonly [Key in keyof NativeDefinition<WebhookContext<Requirements>>]: Key extends "workflows" ? Readonly<Record<string, WorkflowDeclaration<WorkflowContext<Requirements>>>> : Key extends "schedules" ? Readonly<Record<string, ScheduleDeclaration<MutationContext<Requirements>>>> : Key extends "tools" ? RouterDeclaration<QueryContext<Requirements>, MutationContext<Requirements>> : Key extends "webhooks" ? PromiseCatalog<NonNullable<NativeDefinition<WebhookContext<Requirements>>[Key]>> : NativeDefinition<WebhookContext<Requirements>>[Key];
 } & {
     readonly name?: never;
-    readonly tools?: never;
+    readonly queries?: never;
+    readonly mutations?: never;
     readonly call?: never;
 };
 /** Adapt operation and webhook catalogs without evaluating their handlers. */
 export type EffectDefinition<Def> = {
-    readonly [Key in keyof Def]: Key extends "dynamicTools" ? NonNullable<NativeDefinition<unknown>["dynamicTools"]> : Key extends "workflows" ? Readonly<Record<string, import("../contracts/workflows.js").AppWorkflow>> : Key extends "schedules" ? NonNullable<NativeDefinition<unknown>["schedules"]> : Key extends "queries" | "mutations" ? Readonly<Record<string, import("../contracts/operations.js").AppOperation>> : Key extends "webhooks" ? NonNullable<NativeDefinition<WebhookContext>["webhooks"]> : Key extends "skills" ? NonNullable<NativeDefinition<unknown>["skills"]> : Key extends "dynamicSkills" ? NonNullable<NativeDefinition<unknown>["dynamicSkills"]> : Def[Key];
+    readonly [Key in keyof Def]: Key extends "tools" ? NonNullable<NativeDefinition<unknown>["tools"]> : Key extends "workflows" ? Readonly<Record<string, import("../contracts/workflows.js").AppWorkflow>> : Key extends "schedules" ? NonNullable<NativeDefinition<unknown>["schedules"]> : Key extends "webhooks" ? NonNullable<NativeDefinition<WebhookContext>["webhooks"]> : Key extends "skills" ? NonNullable<NativeDefinition<unknown>["skills"]> : Key extends "dynamicSkills" ? NonNullable<NativeDefinition<unknown>["dynamicSkills"]> : Def[Key];
 };
 declare const InternalApp: unique symbol;
 /** Recognize a declaration from this framework instance before host adaptation. */

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

@@ -1,6 +1,6 @@
 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. */
     readonly cache?: AppCache;
@@ -11,6 +11,11 @@ export interface CatalogCacheOptions {
     /** Await a fresh revision at an explicit logical connection or refresh boundary. */
     readonly revalidate?: boolean;
 }
+/** 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 & {
@@ -21,9 +26,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/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 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>;
+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,5 +1,4 @@
 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 OperationKinds } from "./protocol-operations.js";
@@ -7,6 +6,4 @@ import { type OperationKinds } from "./protocol-operations.js";
 export interface McpCatalogOptions extends McpToolsOptions, CatalogCacheOptions {
 }
 /** 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

@@ -56,7 +56,7 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
         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 +67,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-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/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> & {

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,6 +1,7 @@
 /** 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, 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: {
@@ -9,8 +10,12 @@ export declare const secrets: <Fields extends Schema.Decoder<unknown>>(options:
 }) => 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: {
+/** Author options: the account check is an ordinary async function. */
+export interface ProviderOptions<Auth extends AuthMethods> {
     readonly name: string;
     readonly auth: Auth;
-}) => Provider<Auth>;
+    /** 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>;