apps 0.0.1-beta.1 → 0.0.1-beta.100

package/types/apps/src/contracts/protocols/oauth-6.d.ts

@@ -0,0 +1,74 @@
+/**
+ * OAuth declarations frozen for host protocols 6 onward: `./oauth.ts`'s with an explicit
+ * authorization-server metadata URL on discovery. The module imports only `effect` and
+ * `./oauth.ts`, so no change elsewhere in the repository can alter it.
+ */
+import { Schema } from "effect";
+/**
+ * OAuth endpoints and protocol choices. Omitted grant means authorization code; clients remain
+ * host-owned. Declared endpoints may name an RFC 7009 `revocationUrl`; discovery reads the
+ * server's `revocation_endpoint` metadata instead.
+ */
+export declare const OAuth2Config: Schema.Union<readonly [Schema.Struct<{
+    readonly discover: Schema.String;
+    /** Fetch this exact metadata document and verify its issuer against discovery. */
+    readonly authorizationServerMetadataUrl: Schema.optionalKey<Schema.String>;
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+    readonly revocationUrl: Schema.optionalKey<Schema.Never>;
+    readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly tokenResponse: Schema.optionalKey<Schema.Struct<{
+        readonly path: Schema.String;
+    }>>;
+    readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+    readonly authorizationParams: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
+}>, Schema.Struct<{
+    /** Its query is kept; it cannot set protocol parameters or repeat `authorizationParams`. */
+    readonly authorizationUrl: Schema.String;
+    readonly tokenUrl: Schema.String;
+    readonly revocationUrl: Schema.optionalKey<Schema.String>;
+    readonly scopes: Schema.$Array<Schema.String>;
+    /** RFC 8414 issuer identifier. Declared issuers are checked against the callback's `iss`. */
+    readonly issuer: Schema.optionalKey<Schema.String>;
+    readonly discover: Schema.optionalKey<Schema.Never>;
+    readonly authorizationServerMetadataUrl: Schema.optionalKey<Schema.Never>;
+    readonly tokenResponse: Schema.optionalKey<Schema.Struct<{
+        readonly path: Schema.String;
+    }>>;
+    readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+    readonly authorizationParams: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
+}>, Schema.Struct<{
+    readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
+    readonly grant: Schema.Literal<"client_credentials">;
+    readonly discover: Schema.String;
+    /** Fetch this exact metadata document and verify its issuer against discovery. */
+    readonly authorizationServerMetadataUrl: Schema.optionalKey<Schema.String>;
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+    readonly revocationUrl: Schema.optionalKey<Schema.Never>;
+    readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>, Schema.Struct<{
+    readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly discover: Schema.optionalKey<Schema.Never>;
+    readonly authorizationServerMetadataUrl: Schema.optionalKey<Schema.Never>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
+    readonly grant: Schema.Literal<"client_credentials">;
+    readonly tokenUrl: Schema.String;
+    readonly revocationUrl: Schema.optionalKey<Schema.String>;
+    readonly scopes: Schema.$Array<Schema.String>;
+}>]>;
+export type OAuth2Config = typeof OAuth2Config.Type;

package/types/apps/src/contracts/protocols/oauth.d.ts

@@ -0,0 +1,134 @@
+/**
+ * OAuth declarations frozen for host protocols 1 through 5. The module imports only `effect`, so
+ * no change elsewhere in the repository can alter it. `./oauth-6.ts` holds the declaration later
+ * protocols use.
+ */
+import { Schema } from "effect";
+/** Absolute HTTP(S) URL; local HTTP hosts are supported. */
+export declare const HttpUrl: Schema.String;
+/** How an OAuth client authenticates at the token endpoint; raw Basic is an explicit provider compatibility option. */
+export declare const OAuthClientAuth: Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+export type OAuthClientAuth = typeof OAuthClientAuth.Type;
+/** Machine clients always authenticate; public clients cannot use the client-credentials grant. */
+export declare const OAuthSecretClientAuth: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+/** Parameters the host sets on every authorization request; a declaration cannot replace them. */
+export declare const reservedAuthorizationParams: readonly ["response_type", "client_id", "redirect_uri", "state", "scope", "code_challenge", "code_challenge_method", "nonce", "resource", "request", "request_uri"];
+/** A protocol parameter only the host sets on the authorization request. */
+export type ReservedAuthorizationParam = (typeof reservedAuthorizationParams)[number];
+/**
+ * Extra authorization request parameters, such as `access_type: "offline"`. RFC 6749 §3.1
+ * lets services define their own; the protocol and security parameters stay host-owned.
+ */
+export declare const OAuthAuthorizationParams: Schema.$Record<Schema.String, Schema.String>;
+/**
+ * A declared `authorizationUrl` may carry its own query (RFC 6749 §3.1 keeps it). Each parameter
+ * is declared once, in the URL or in `authorizationParams`, and never names a host-owned one.
+ */
+export declare const declaredAuthorizationQuery: import("effect/SchemaAST").Filter<{
+    readonly authorizationUrl: string;
+    readonly authorizationParams?: Readonly<Record<string, string>>;
+}>;
+/** How the token endpoint reads requests. RFC 6749 uses a form; some services want JSON. */
+export declare const OAuthTokenRequestFormat: Schema.Literals<readonly ["form", "json"]>;
+export type OAuthTokenRequestFormat = typeof OAuthTokenRequestFormat.Type;
+/**
+ * Where a service nests the grant in its token response, as a dot-separated member path. Slack
+ * returns a user token under `authed_user`.
+ */
+export declare const OAuthTokenResponse: Schema.Struct<{
+    readonly path: Schema.String;
+}>;
+export type OAuthTokenResponse = typeof OAuthTokenResponse.Type;
+/** Options for services that differ from RFC 6749 in how they read requests. */
+export declare const tokenRequestOptions: {
+    /** Joins requested scopes; Linear wants `","`. Defaults to RFC 6749's space. */
+    scopeSeparator: Schema.optionalKey<Schema.String>;
+    /** Encoding of token requests. Defaults to `"form"`; Atlassian, ClickUp and Notion need `"json"`. */
+    tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
+};
+export declare const oauthOptions: {
+    /**
+     * Read the grant from this nested member of the token response when the top-level response has
+     * no access token or no scope. Slack's user tokens use `{ path: "authed_user" }`.
+     */
+    tokenResponse: Schema.optionalKey<Schema.Struct<{
+        readonly path: Schema.String;
+    }>>;
+    grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+    /**
+     * Service-defined authorization request parameters, such as Google's
+     * `{ access_type: "offline", prompt: "consent" }`. Host-owned protocol parameters
+     * (`state`, `scope`, `redirect_uri`, PKCE and the others in `reservedAuthorizationParams`)
+     * are rejected. A discovered endpoint's own query parameter of the same name is replaced.
+     */
+    authorizationParams: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+    /** Omitted uses discovery; null explicitly suppresses the resource parameter. */
+    resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    /** Joins requested scopes; Linear wants `","`. Defaults to RFC 6749's space. */
+    scopeSeparator: Schema.optionalKey<Schema.String>;
+    /** Encoding of token requests. Defaults to `"form"`; Atlassian, ClickUp and Notion need `"json"`. */
+    tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
+};
+/**
+ * OAuth endpoints and protocol choices. Omitted grant means authorization code; clients remain
+ * host-owned. Declared endpoints may name an RFC 7009 `revocationUrl`; discovery reads the
+ * server's `revocation_endpoint` metadata instead.
+ */
+export declare const OAuth2Config: Schema.Union<readonly [Schema.Struct<{
+    readonly discover: Schema.String;
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+    readonly revocationUrl: Schema.optionalKey<Schema.Never>;
+    readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly tokenResponse: Schema.optionalKey<Schema.Struct<{
+        readonly path: Schema.String;
+    }>>;
+    readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+    readonly authorizationParams: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
+}>, Schema.Struct<{
+    /** Its query is kept; it cannot set protocol parameters or repeat `authorizationParams`. */
+    readonly authorizationUrl: Schema.String;
+    readonly tokenUrl: Schema.String;
+    readonly revocationUrl: Schema.optionalKey<Schema.String>;
+    readonly scopes: Schema.$Array<Schema.String>;
+    /** RFC 8414 issuer identifier. Declared issuers are checked against the callback's `iss`. */
+    readonly issuer: Schema.optionalKey<Schema.String>;
+    readonly discover: Schema.optionalKey<Schema.Never>;
+    readonly tokenResponse: Schema.optionalKey<Schema.Struct<{
+        readonly path: Schema.String;
+    }>>;
+    readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+    readonly authorizationParams: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
+}>, Schema.Struct<{
+    readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
+    readonly grant: Schema.Literal<"client_credentials">;
+    readonly discover: Schema.String;
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+    readonly revocationUrl: Schema.optionalKey<Schema.Never>;
+    readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>, Schema.Struct<{
+    readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly discover: Schema.optionalKey<Schema.Never>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
+    readonly grant: Schema.Literal<"client_credentials">;
+    readonly tokenUrl: Schema.String;
+    readonly revocationUrl: Schema.optionalKey<Schema.String>;
+    readonly scopes: Schema.$Array<Schema.String>;
+}>]>;
+export type OAuth2Config = typeof OAuth2Config.Type;

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

@@ -3,12 +3,21 @@ declare const ProviderError_base: Schema.Class<ProviderError, Schema.TaggedStruc
     readonly reason: Schema.Literals<readonly ["unauthorized", "forbidden", "rate_limited", "unavailable", "rejected"]>;
     readonly status: Schema.optional<Schema.Int>;
     readonly accountId: Schema.optional<Schema.brand<Schema.String, "acc">>;
+    readonly phase: Schema.optional<Schema.Literals<readonly ["connect", "discover", "call"]>>;
+    readonly upstream: Schema.optional<Schema.Struct<{
+        readonly code: Schema.Union<readonly [Schema.Int, Schema.String]>;
+        readonly message: Schema.optionalKey<Schema.String>;
+    }>>;
 }>, import("effect/Cause").YieldableError>;
 /**
  * A recognized service failure. App authors can throw this ordinary Error from
  * async code. Supply only a known reason and the account used for that request.
  * Never include response bodies, messages, URLs or credentials. A bare 403 is
  * `rejected`; `forbidden` requires explicit evidence of insufficient permission.
+ *
+ * The framework adds the phase the failure happened in, and `upstream`: the error code and
+ * description the service stated in its documented error format, such as a Bearer challenge's
+ * `error` and `error_description`. Account secrets in that text are replaced.
  */
 export declare class ProviderError extends ProviderError_base {
 }

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

@@ -1,6 +1,13 @@
 /** 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 { Placement } from "./placement.js";
 import { type AccountId } from "./schema.js";
+/**
+ * How app code sees a field of a provider that declares hosts. Unmarked string fields are secret:
+ * app code receives sealed handles that only the host's outbound network turns into values.
+ * `plain` fields are not secret. `raw` fields are secret, but app code reads the real value.
+ */
+export type FieldExposure = "plain" | "raw";
 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";
 } & import("effect/Pipeable").Pipeable;
@@ -8,6 +15,10 @@ declare const SecretsMethod_base: new <A extends Record<string, any> = {}>(args:
 export declare class SecretsMethod<Fields extends Schema.Decoder<unknown>> extends SecretsMethod_base<{
     readonly label: string;
     readonly fields: Fields;
+    /** Fields marked with `plain()` or `raw()`. */
+    readonly exposure?: Readonly<Record<string, FieldExposure>>;
+    /** The only places the outbound network sends this method's secret fields; see `Placement`. */
+    readonly request?: readonly Placement[];
 }> {
 }
 /** How an OAuth client authenticates at the token endpoint; raw Basic is an explicit provider compatibility option. */
@@ -15,11 +26,26 @@ export declare const OAuthClientAuth: Schema.Literals<readonly ["none", "client_
 export type OAuthClientAuth = typeof OAuthClientAuth.Type;
 /** Machine clients always authenticate; public clients cannot use the client-credentials grant. */
 export declare const OAuthSecretClientAuth: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+/** Parameters the host sets on every authorization request; a declaration cannot replace them. */
+export declare const reservedAuthorizationParams: readonly ["response_type", "client_id", "redirect_uri", "state", "scope", "code_challenge", "code_challenge_method", "nonce", "resource", "request", "request_uri"];
+/** A protocol parameter only the host sets on the authorization request. */
+export type ReservedAuthorizationParam = (typeof reservedAuthorizationParams)[number];
 /**
  * Extra authorization request parameters, such as `access_type: "offline"`. RFC 6749 §3.1
  * lets services define their own; the protocol and security parameters stay host-owned.
  */
 export declare const OAuthAuthorizationParams: Schema.$Record<Schema.String, Schema.String>;
+/** How the token endpoint reads requests. RFC 6749 uses a form; some services want JSON. */
+export declare const OAuthTokenRequestFormat: Schema.Literals<readonly ["form", "json"]>;
+export type OAuthTokenRequestFormat = typeof OAuthTokenRequestFormat.Type;
+/**
+ * Where a service nests the grant in its token response, as a dot-separated member path. Slack
+ * returns a user token under `authed_user`.
+ */
+export declare const OAuthTokenResponse: Schema.Struct<{
+    readonly path: Schema.String;
+}>;
+export type OAuthTokenResponse = typeof OAuthTokenResponse.Type;
 /**
  * OAuth endpoints and protocol choices. Omitted grant means authorization code; clients remain
  * host-owned. Declared endpoints may name an RFC 7009 `revocationUrl`; discovery reads the
@@ -27,15 +53,23 @@ export declare const OAuthAuthorizationParams: Schema.$Record<Schema.String, Sch
  */
 export declare const OAuth2Config: Schema.Union<readonly [Schema.Struct<{
     readonly discover: Schema.String;
+    /** Fetch this exact metadata document and verify its issuer against discovery. */
+    readonly authorizationServerMetadataUrl: Schema.optionalKey<Schema.String>;
     readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
     readonly tokenUrl: Schema.optionalKey<Schema.Never>;
     readonly revocationUrl: Schema.optionalKey<Schema.Never>;
     readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly tokenResponse: Schema.optionalKey<Schema.Struct<{
+        readonly path: Schema.String;
+    }>>;
     readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
     readonly authorizationParams: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
     readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
     readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
 }>, Schema.Struct<{
+    /** Its query is kept; it cannot set protocol parameters or repeat `authorizationParams`. */
     readonly authorizationUrl: Schema.String;
     readonly tokenUrl: Schema.String;
     readonly revocationUrl: Schema.optionalKey<Schema.String>;
@@ -43,28 +77,41 @@ export declare const OAuth2Config: Schema.Union<readonly [Schema.Struct<{
     /** RFC 8414 issuer identifier. Declared issuers are checked against the callback's `iss`. */
     readonly issuer: Schema.optionalKey<Schema.String>;
     readonly discover: Schema.optionalKey<Schema.Never>;
+    readonly authorizationServerMetadataUrl: Schema.optionalKey<Schema.Never>;
+    readonly tokenResponse: Schema.optionalKey<Schema.Struct<{
+        readonly path: Schema.String;
+    }>>;
     readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
     readonly authorizationParams: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
     readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
     readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
 }>, Schema.Struct<{
+    readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
     readonly grant: Schema.Literal<"client_credentials">;
     readonly discover: Schema.String;
+    /** Fetch this exact metadata document and verify its issuer against discovery. */
+    readonly authorizationServerMetadataUrl: Schema.optionalKey<Schema.String>;
     readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
     readonly tokenUrl: Schema.optionalKey<Schema.Never>;
     readonly revocationUrl: Schema.optionalKey<Schema.Never>;
     readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>, Schema.Struct<{
     readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
     readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
-}>, Schema.Struct<{
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly discover: Schema.optionalKey<Schema.Never>;
+    readonly authorizationServerMetadataUrl: Schema.optionalKey<Schema.Never>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
     readonly grant: Schema.Literal<"client_credentials">;
     readonly tokenUrl: Schema.String;
     readonly revocationUrl: Schema.optionalKey<Schema.String>;
     readonly scopes: Schema.$Array<Schema.String>;
-    readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
-    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
-    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
-    readonly discover: Schema.optionalKey<Schema.Never>;
 }>]>;
 export type OAuth2Config = typeof OAuth2Config.Type;
 /** Default app-visible OAuth projection. Refresh tokens and client secrets remain with the host. */
@@ -78,16 +125,77 @@ declare const OAuth2Method_base: new <A extends Record<string, any> = {}>(args:
 export declare class OAuth2Method<Response extends Schema.Decoder<unknown>> extends OAuth2Method_base<{
     readonly config: OAuth2Config;
     readonly response: Response;
+    /** Response fields marked with `plain()` or `raw()`. */
+    readonly exposure?: Readonly<Record<string, FieldExposure>>;
+    /** The only places the outbound network sends this method's secret fields; see `Placement`. */
+    readonly request?: readonly Placement[];
 }> {
 }
 /** Supported declarations; these acquire credentials rather than normalize them. */
 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;
+    /**
+     * When the host stops waiting for the check, in milliseconds since the epoch. A check still
+     * running then fails without its own message, so a check that gives up must do so before it.
+     * Executor always sets it; a host that does not limit the check leaves it out.
+     */
+    readonly deadline?: number;
+}
+/**
+ * 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. A
+ * thrown error's own message is shown to the user, bounded and with the checked credentials
+ * replaced, so write it for them.
+ */
+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;
+    /**
+     * The hosts this provider's credentials may be sent to. When present, secret fields reach app
+     * code as handles that the outbound network replaces only on requests to these hosts.
+     */
+    readonly hosts?: readonly string[];
+    /**
+     * 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 +210,34 @@ 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> ? {
+/**
+ * Render an account's credential placements. Each renders the method's `request` with the fields
+ * app code holds, so a request built with them is one the outbound network accepts.
+ */
+export interface AccountRequest {
+    /**
+     * The headers the method's `request` places credentials in, by lowercase name. Spread them into
+     * a request's headers. Throws when the method declares no `request`.
+     */
+    headers(): Record<string, string>;
+    /**
+     * `input` with the query parameters the method's `request` places credentials in, replacing any
+     * of the same name. Throws when the method declares no `request`.
+     */
+    url(input: string | URL): string;
+}
+/** 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]>;
+        /** See `AccountRequest`. */
+        readonly headers: AccountRequest["headers"];
+        /** See `AccountRequest`. */
+        readonly url: AccountRequest["url"];
     };
-}[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/contracts/schedules.d.ts

@@ -33,9 +33,15 @@ export declare const ScheduleTiming: Schema.Union<readonly [Schema.Struct<{
     }>;
 }>]>;
 export type ScheduleTiming = typeof ScheduleTiming.Type;
-/** A named trigger attached to the mutation it invokes, including schema-validated arguments. */
+/**
+ * A named trigger attached to the mutation it invokes, including schema-validated arguments.
+ * `scope: "app"` marks an app schedule: one schedule, run without a caller with the app's accounts.
+ * Without it, each member who enables the schedule has a copy that runs as them; bundles of
+ * protocol 12 and earlier declare only those.
+ */
 export declare const OperationSchedule: Schema.Struct<{
     readonly name: Schema.NonEmptyString;
+    readonly scope: Schema.optionalKey<Schema.Literal<"app">>;
     readonly timing: Schema.Union<readonly [Schema.Struct<{
         readonly kind: Schema.Literal<"interval">;
         readonly milliseconds: Schema.Int;

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

@@ -12,6 +12,27 @@ export declare const AccountId: Schema.brand<Schema.String, "acc">;
 export type AccountId = typeof AccountId.Type;
 /** Absolute HTTP(S) URL; local HTTP hosts are supported. */
 export declare const HttpUrl: Schema.String;
+/** One problem with a declaration: where in it, and what is wrong there. */
+export declare const DeclarationIssue: Schema.Struct<{
+    readonly path: Schema.$Array<Schema.String>;
+    readonly message: Schema.String;
+}>;
+export type DeclarationIssue = typeof DeclarationIssue.Type;
+declare const DeclarationInvalid_base: Schema.Class<DeclarationInvalid, Schema.TaggedStruct<"DeclarationInvalid", {
+    readonly declaration: Schema.String;
+    readonly issues: Schema.$Array<Schema.Struct<{
+        readonly path: Schema.$Array<Schema.String>;
+        readonly message: Schema.String;
+    }>>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * An author's declaration, such as the options of `oauth2()`, did not match its schema. Unlike
+ * {@link ValidationError} it names each failing path and problem, because the value is the
+ * author's own source. Messages never include supplied values.
+ */
+export declare class DeclarationInvalid extends DeclarationInvalid_base {
+    get message(): string;
+}
 declare const ValidationError_base: Schema.Class<ValidationError, Schema.TaggedStruct<"ValidationError", {}>, import("effect/Cause").YieldableError>;
 /** Invalid input. Never includes supplied values, credentials or response bodies. */
 export declare class ValidationError extends ValidationError_base {

package/types/apps/src/contracts/shared-catalog.d.ts

@@ -0,0 +1,11 @@
+import type { HostedCatalog, HostedRouter, HostedSharedCatalog, HostedTool } from "./protocols/current.js";
+/** A catalog with each definition and each distinct `$defs` its tools' schemas hold sent once. */
+export declare const shareCatalog: (catalog: {
+    readonly tools: ReadonlyArray<HostedTool>;
+    readonly routers: ReadonlyArray<HostedRouter>;
+}) => HostedSharedCatalog;
+/**
+ * The catalog a shared catalog was made from; undefined when it names a definition or `$defs`
+ * it does not send.
+ */
+export declare const restoreSharedCatalog: (catalog: HostedSharedCatalog) => HostedCatalog | undefined;