apps 0.0.1-beta.7 → 0.0.1-beta.73

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, 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,6 +125,10 @@ 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. */
@@ -114,11 +165,19 @@ 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.
+ * 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>;
@@ -127,6 +186,11 @@ export interface AccountCheck<Auth extends AuthMethods> {
 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.
@@ -146,12 +210,32 @@ 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;
+/**
+ * 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];
 /** One selected account, discriminated by its author-chosen method name. */

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

@@ -1,5 +1,6 @@
 /** Portable Agent Skills returned by an app factory or loaded from published files. */
 import { Schema } from "effect";
+import { ApiError } from "../../../utils/src/api-error.js";
 /** Canonical resource path within one skill. */
 export declare const SkillFilePath: Schema.NonEmptyString;
 /** UTF-8 text resource. Reading a resource never executes it. */
@@ -40,13 +41,25 @@ export declare const AppSkillSource: Schema.Struct<{
     readonly "allowed-tools": Schema.optionalKey<Schema.String>;
 }>;
 export type AppSkillSource = typeof AppSkillSource.Type;
-declare const SkillDefinitionInvalid_base: Schema.Class<SkillDefinitionInvalid, Schema.TaggedStruct<"SkillDefinitionInvalid", {
+/** Invalid selected skill files fail the load. Errors identify the file without disclosing its contents. */
+export declare const SkillDefinitionInvalid: Schema.Class<{
+    readonly file: string;
+    readonly reason: "metadata" | "files" | "directory" | "missing-document" | "frontmatter" | "name-mismatch";
+} & ApiError & {
+    readonly _tag: "SkillDefinitionInvalid";
+}, Omit<Schema.TaggedStruct<"SkillDefinitionInvalid", {
     readonly file: Schema.NonEmptyString;
     readonly reason: Schema.Literals<readonly ["files", "directory", "missing-document", "frontmatter", "metadata", "name-mismatch"]>;
-}>, import("effect/Cause").YieldableError>;
-/** Invalid selected skill files fail the load. Errors identify the file without disclosing its contents. */
-export declare class SkillDefinitionInvalid extends SkillDefinitionInvalid_base {
-}
+} & {
+    readonly message: typeof import("../../../utils/src/api-error.js").MessageField;
+}>, "~type.make.in"> & {
+    readonly "~type.make.in": {
+        readonly reason: "metadata" | "files" | "directory" | "missing-document" | "frontmatter" | "name-mismatch";
+        readonly file: string;
+        readonly _tag?: "SkillDefinitionInvalid";
+    };
+}, ApiError>;
+export type SkillDefinitionInvalid = typeof SkillDefinitionInvalid.Type;
 /** One evaluated catalog cannot contain ambiguous names. */
 export declare const AppSkills: Schema.$Array<Schema.Struct<{
     readonly files: Schema.$Array<Schema.Struct<{
@@ -66,11 +79,16 @@ declare const SkillLoadFailed_base: Schema.Class<SkillLoadFailed, Schema.TaggedS
     readonly reason: Schema.Literals<readonly ["source", "request", "rate_limited", "document", "limit", "changed", "encoding"]>;
     readonly message: Schema.optional<Schema.String>;
     readonly status: Schema.optional<Schema.Int>;
+    readonly missing: Schema.optional<Schema.Literals<readonly ["repository", "ref"]>>;
 }>, import("effect/Cause").YieldableError>;
 /**
  * A skill loader failure shown to people. `message` is the explanation they read; write it for
  * them and never include URLs, tokens or response bodies. `reason` selects the title and whether
  * a retry can help. Custom loaders throw this error to get the same presentation as built-ins.
+ * With `source`, `missing` names what the service's answer points to as missing: the `repository`,
+ * or the branch or tag (`ref`). It may be missing, or not readable with the request's credentials.
+ * Without it, the source's settings or the paths it lists are not valid.
+ * These fields choose the explanation; they never show that the failure lies outside Executor.
  */
 export declare class SkillLoadFailed extends SkillLoadFailed_base {
 }
@@ -80,6 +98,8 @@ export declare const skillLoadLimits: {
     readonly fileBytes: 2000000;
     readonly totalBytes: 20000000;
     readonly concurrency: 8;
+    /** The request that checks whether a kept catalog's publication changed. */
+    readonly checkMillis: 5000;
 };
 /** Invocation-owned transport and cancellation, supplied by the app context. */
 export interface SkillTransport {
@@ -91,25 +111,42 @@ export interface SkillReaderOptions extends SkillTransport {
     readonly service: string;
 }
 /**
- * Catalog reuse shared by remote skill loaders, with the same policy as MCP tool catalogs. Pass
- * `ctx.cache` to keep the loaded catalog; without it every read fetches the source again.
+ * Catalog reuse shared by remote skill loaders. Pass `ctx.cache` to keep the loaded catalog;
+ * without it every read fetches the source again. Unlike an MCP tool catalog, a skill catalog
+ * past `freshFor` is not served while it refreshes: the read first asks the source whether its
+ * publication changed, so agents never read skills that a refresh replaces moments later.
  */
 export interface SkillCacheOptions {
     readonly cache?: import("./cache.js").AppCache;
-    /** Reuse the catalog for this duration. Defaults to five minutes. */
+    /** Reuse the catalog without asking the source for this duration. Defaults to five minutes. */
     readonly freshFor?: import("effect").Duration.Input;
-    /** Serve the retained catalog while refreshing. Defaults to one day. */
+    /**
+     * Keep the catalog this long after `freshFor`. A read then confirms it with one request and
+     * loads the files again only when the publication changed. Defaults to one day.
+     */
     readonly staleFor?: import("effect").Duration.Input;
 }
 /**
- * A public GitHub repository and an optional immutable commit, tag or branch. With a cache, a
- * branch or tag is resolved again when the catalog refreshes, and each commit's file list is kept.
+ * Whose access reads the repository. A public repository needs neither field. A private one takes
+ * a GitHub account and its token, sent on every request of this read. The token comes only with
+ * its account, so the catalog is cached in that account's scope and failures name the account.
  */
-export interface GitHubSkillsOptions extends SkillTransport, SkillCacheOptions {
+export type GitHubSkillsAccount = import("./cache.js").AccountCredential<{
+    /**
+     * The account's token or its handle, such as `account.fields.token`. Its provider declares
+     * hosts `github.com` and `raw.githubusercontent.com`, so app code never holds the value.
+     */
+    readonly token: string;
+}>;
+/**
+ * A GitHub repository and an optional immutable commit, tag or branch. With a cache, a branch or
+ * tag is resolved again once the catalog is past `freshFor`, and each commit's file list is kept.
+ */
+export type GitHubSkillsOptions = SkillTransport & SkillCacheOptions & GitHubSkillsAccount & {
     readonly repo: string;
     readonly path?: string;
     readonly ref?: string;
-}
+};
 /** A published directory index, including its listed skill documents and text references. */
 export interface WellKnownSkillsOptions extends SkillTransport, SkillCacheOptions {
     readonly url: string;

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

@@ -0,0 +1,63 @@
+/**
+ * App-owned SQLite. An app with migrations in `migrations/` reads and writes its own database with
+ * plain SQL. The author API mirrors Cloudflare's `SqlStorage`, so tools built for Durable Object
+ * SQLite fit it.
+ */
+/** A value SQLite stores or returns. */
+export type SqlValue = string | number | null | ArrayBuffer;
+/** One result row, keyed by column name. */
+export type SqlRow = Record<string, SqlValue>;
+/** The rows of one statement, already read, and what the statement read and wrote. */
+export interface SqlCursor<Row extends SqlRow = SqlRow> extends Iterable<Row> {
+    readonly columnNames: readonly string[];
+    readonly rowsRead: number;
+    readonly rowsWritten: number;
+    toArray(): Row[];
+    /** The only row. Throws unless the statement returned exactly one. */
+    one(): Row;
+}
+/**
+ * Read-only SQL. Query tools receive this. A query runs in a transaction that is always rolled
+ * back, so nothing it changes commits; one that changes rows fails.
+ */
+export interface SqlReader {
+    exec<Row extends SqlRow = SqlRow>(query: string, ...bindings: SqlValue[]): SqlCursor<Row>;
+}
+/** SQL inside one transaction. */
+export type SqlTransaction = SqlReader;
+/**
+ * Writable SQL. Outside a transaction every statement commits on its own. `transaction` runs its
+ * callback synchronously in one SQLite transaction, so no transaction can stay open while the app
+ * waits on anything else; throwing rolls it back. Apps call outside services between transactions.
+ */
+export interface Sql extends SqlReader {
+    transaction<T>(work: (tx: SqlTransaction) => Synchronous<T>): T;
+}
+/** A transaction callback's result: a Promise means the callback awaited, which is refused. */
+export type Synchronous<T> = T extends PromiseLike<unknown> ? never : T;
+/** The Durable Object storage a data facet hands its app. App code never receives it. */
+export interface AppSqlStorage {
+    readonly sql: {
+        exec(query: string, ...bindings: SqlValue[]): {
+            readonly columnNames: string[];
+            readonly rowsRead: number;
+            readonly rowsWritten: number;
+            toArray(): Record<string, SqlValue>[];
+        };
+    };
+    transactionSync<T>(work: () => T): T;
+}
+/**
+ * Tables Executor keeps in an app's database: applied migrations, workflow step receipts, and
+ * `_executor_legacy_rows (table_name, id, body)`, the rows of the document API apps used before
+ * SQL, with JSON bodies (empty for apps that never stored any). Apps should only read them; a
+ * changed migration history fails the next deploy.
+ */
+export declare const reservedTablePrefix = "_executor_";
+/** Where an app keeps its migrations: `0001_create_notes.sql`, applied in number order. */
+export declare const migrationsDirectory = "migrations";
+/**
+ * The most values one statement may bind. Durable Object SQLite sets `SQLITE_LIMIT_VARIABLE_NUMBER`
+ * to 100 on every host; `ctx.sql` checks it first so the error names the limit.
+ */
+export declare const sqlBindingsLimit = 100;

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

@@ -1,12 +1,30 @@
 /** Browser-to-host operations bind identity and authentication outside authored app code. */
 import { Schema } from "effect";
-import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/unstable/httpapi";
+import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api";
 /** Non-secret page context injected by the serving host. */
 export declare const UiContext: Schema.Struct<{
     readonly deployment: Schema.NonEmptyString;
     readonly profile: Schema.optional<Schema.NonEmptyString>;
     readonly expectedProfileRevision: Schema.optional<Schema.Int>;
 }>;
+/** A problem with one of the page profile's accounts, from stored state. Labels are the owner's own names. */
+export type UiAccountProblem = {
+    readonly provider: string;
+    readonly reason: "missing" | "removed" | "incompatible";
+} | {
+    readonly provider: string;
+    readonly account: string;
+    readonly reason: "credentials_rejected" | "forbidden" | "upstream_unavailable" | "check_failed";
+};
+/** Account problems found when the page opened, with dashboard links that resolve them. */
+export interface UiAccountNotice {
+    readonly app: string;
+    readonly problems: readonly UiAccountProblem[];
+    /** The profile's accounts in the dashboard. */
+    readonly fix: string;
+    /** The dashboard chooser, returning to this page. */
+    readonly choose: string;
+}
 /** Retained browser bytes. Hosts authorize access before reading or rendering them. */
 export interface AppUiAsset {
     readonly body: Uint8Array;