apps 0.0.1-beta.4 → 0.0.1-beta.41

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

@@ -0,0 +1,89 @@
+/** OAuth declarations frozen for host protocols 1 through 5. */
+import { Schema } from "effect";
+/** 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>;
+/** 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
+ * 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,12 @@
 /** 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";
+/**
+ * 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 +14,8 @@ 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>>;
 }> {
 }
 /** How an OAuth client authenticates at the token endpoint; raw Basic is an explicit provider compatibility option. */
@@ -15,11 +23,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 +50,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 +74,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 +122,75 @@ 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>>;
 }> {
 }
 /** 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 +205,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/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 {
 }
@@ -102,14 +120,26 @@ export interface SkillCacheOptions {
     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 when the catalog refreshes, 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,58 @@
+/**
+ * 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";

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;