apps 0.0.1-beta.1 → 0.0.1-beta.11

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

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

@@ -90,19 +90,28 @@ export interface SkillTransport {
 export interface SkillReaderOptions extends SkillTransport {
     readonly service: string;
 }
-/** A public GitHub repository and an optional immutable commit, tag or branch. */
-export interface GitHubSkillsOptions extends SkillTransport {
+/**
+ * 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.
+ */
+export interface SkillCacheOptions {
+    readonly cache?: import("./cache.js").AppCache;
+    /** Reuse the catalog for this duration. Defaults to five minutes. */
+    readonly freshFor?: import("effect").Duration.Input;
+    /** Serve the retained catalog while refreshing. 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.
+ */
+export interface GitHubSkillsOptions extends SkillTransport, SkillCacheOptions {
     readonly repo: string;
     readonly path?: string;
     readonly ref?: string;
-    /**
-     * Pass `ctx.cache` to keep each commit's skill file list. Content at a commit never changes,
-     * so later reads of the same commit skip the tree fetch. The ref is still resolved each read.
-     */
-    readonly cache?: import("./cache.js").AppCache;
 }
 /** A published directory index, including its listed skill documents and text references. */
-export interface WellKnownSkillsOptions extends SkillTransport {
+export interface WellKnownSkillsOptions extends SkillTransport, SkillCacheOptions {
     readonly url: string;
 }
 /** A folder in the deployed package; omitted path selects skills/. No host filesystem access. */

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

@@ -2,7 +2,7 @@
 import { Schema, type Effect } from "effect";
 import type { RowMetadata, ReadTable, WriteTable } from "../../../app-data/src/index.js";
 import type { Fields, ObjectValue } from "../implementation/schema.js";
-import type { DatabaseSchema, DatabaseSession, AppDatabaseError } from "../../../app-data/src/contracts/database.js";
+import type { DatabaseSchema, DatabaseSession, DatabaseError } from "../../../app-data/src/contracts/database.js";
 /** Names for authored operations and tables. */
 export declare const StorageName: Schema.NonEmptyString;
 declare const AppStorageUnavailable_base: Schema.Class<AppStorageUnavailable, Schema.TaggedStruct<"AppStorageUnavailable", {}>, import("effect/Cause").YieldableError>;
@@ -15,8 +15,8 @@ export declare class AppStorageError extends AppStorageError_base {
 }
 /** The adapter owns the database connection and transaction for the whole authored invocation. */
 export interface AppStorage {
-    readonly read: <A, E>(schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | AppDatabaseError | AppStorageUnavailable | AppStorageError>;
-    readonly mutate: <A, E>(schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | AppDatabaseError | AppStorageUnavailable | AppStorageError>;
+    readonly read: <A, E>(schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | DatabaseError | AppStorageUnavailable | AppStorageError>;
+    readonly mutate: <A, E>(schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | DatabaseError | AppStorageUnavailable | AppStorageError>;
 }
 type InputValue<F extends Fields> = {
     readonly [K in keyof F as F[K]["optionalValue"] extends true ? never : F[K] extends {

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

@@ -1,7 +1,5 @@
 /** Browser authentication protocol. Identity and session storage belong to the host. */
 import { Schema } from "effect";
-import { HttpApi, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
-import { UiFailed, UiForbidden, UiUnauthorized } from "./ui.js";
 /** Opaque correlation ID; possession alone does not authorize an app session. */
 export declare const AppSignInId: Schema.brand<Schema.String, "AppSignInId">;
 export type AppSignInId = typeof AppSignInId.Type;
@@ -10,19 +8,13 @@ export declare const AppSignInCode: Schema.RedactedFromValue<Schema.String>;
 /** A path on the current app origin, including its query and fragment; never a redirect to another host or host-owned route. */
 export declare const AppReturnPath: Schema.brand<Schema.String, "AppReturnPath">;
 export type AppReturnPath = typeof AppReturnPath.Type;
-/** The trusted callback exchanges an authorization code bound to a browser attempt. */
+/** Callback query on the app origin. The code is single-use and works only with its attempt's cookie. */
 export declare const AppSignInCallback: Schema.Struct<{
     readonly request: Schema.brand<Schema.String, "AppSignInId">;
     readonly code: Schema.RedactedFromValue<Schema.String>;
 }>;
-/** Host-owned endpoints on every app origin, independent of the product's login mechanism. */
-export declare const AppSignInApi: HttpApi.HttpApi<"app-sign-in", HttpApiGroup.HttpApiGroup<"appSignIn", HttpApiEndpoint.HttpApiEndpoint<"start", "POST", "/_executor/auth/start", never, never, Schema.toCodecJson<Schema.Struct<{
-    readonly returnTo: Schema.brand<Schema.String, "AppReturnPath">;
-}>>, never, Schema.toCodecJson<Schema.Struct<{
-    readonly url: Schema.String;
-}>>, Schema.toCodecJson<typeof UiForbidden | typeof UiFailed>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"complete", "POST", "/_executor/auth/complete", never, never, Schema.toCodecJson<Schema.Struct<{
-    readonly request: Schema.brand<Schema.String, "AppSignInId">;
-    readonly code: Schema.RedactedFromValue<Schema.String>;
-}>>, never, Schema.toCodecJson<Schema.Struct<{
-    readonly returnTo: Schema.brand<Schema.String, "AppReturnPath">;
-}>>, Schema.toCodecJson<typeof UiUnauthorized | typeof UiForbidden | typeof UiFailed>, never, never>, false>>;
+/** Host-owned callback path on every app origin. */
+export declare const appSignInCallbackPath = "/_executor/auth/callback";
+/** Why the product could not authorize an attempt; the dashboard explains it without retrying. */
+export declare const AppSignInFailure: Schema.Literals<readonly ["ended", "forbidden", "unavailable"]>;
+export type AppSignInFailure = typeof AppSignInFailure.Type;

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

@@ -24,14 +24,33 @@ export declare const WorkflowStepOptions: Schema.Struct<{
     readonly timeout: Schema.optionalKey<Schema.Union<readonly [Schema.Finite, Schema.NonEmptyString]>>;
 }>;
 export type WorkflowStepOptions = typeof WorkflowStepOptions.Type;
+/**
+ * Where and why a run failed: the failing step and the error the app's own code raised, its
+ * message bounded and with account secrets replaced. Runs from before these fields existed have none.
+ */
+export declare const WorkflowFailureDetail: {
+    step: Schema.optionalKey<Schema.String>;
+    errorName: Schema.optionalKey<Schema.String>;
+    message: Schema.optionalKey<Schema.String>;
+};
+/** A failed run's recorded step and app error. */
+export declare const WorkflowRunFailure: Schema.Struct<{
+    step: Schema.optionalKey<Schema.String>;
+    errorName: Schema.optionalKey<Schema.String>;
+    message: Schema.optionalKey<Schema.String>;
+}>;
+export type WorkflowRunFailure = typeof WorkflowRunFailure.Type;
 declare const WorkflowFailure_base: Schema.Class<WorkflowFailure, Schema.TaggedStruct<"WorkflowFailure", {
     readonly reason: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
     readonly retryable: Schema.Boolean;
+    readonly step: Schema.optionalKey<Schema.String>;
+    readonly errorName: Schema.optionalKey<Schema.String>;
+    readonly message: Schema.optionalKey<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
-/** Safe failures cross host boundaries without authored exceptions or account fields. */
+/** Failures cross host boundaries as reason codes plus the app's own bounded error detail. */
 export declare class WorkflowFailure extends WorkflowFailure_base {
 }
-/** Explicitly stop retrying an authored step. Its message stays inside the app runtime. */
+/** Explicitly stop retrying an authored step. Its message is reported like any step error. */
 export declare class NonRetryableError extends Error {
     readonly name = "NonRetryableError";
 }
@@ -45,7 +64,7 @@ export declare const HostedWorkflow: Schema.Struct<{
     readonly outputSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
 }>;
 export type HostedWorkflow = typeof HostedWorkflow.Type;
-/** Results are available only on completed runs; failure details are safe reason codes. */
+/** Results are available only on completed runs; failures carry a reason code and app error detail. */
 export declare const WorkflowRun: Schema.Union<readonly [Schema.Struct<{
     readonly status: Schema.Literals<readonly ["queued", "running", "waiting", "paused", "waitingForPause"]>;
     readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
@@ -66,6 +85,12 @@ export declare const WorkflowRun: Schema.Union<readonly [Schema.Struct<{
 }>, Schema.Struct<{
     readonly status: Schema.Literal<"errored">;
     readonly error: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
+    /** The failing step and the app's own error, when the run recorded them. */
+    readonly failure: Schema.optionalKey<Schema.Struct<{
+        step: Schema.optionalKey<Schema.String>;
+        errorName: Schema.optionalKey<Schema.String>;
+        message: Schema.optionalKey<Schema.String>;
+    }>>;
     readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
     readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
     readonly app: Schema.NonEmptyString;
@@ -104,6 +129,12 @@ export declare const WorkflowRunPage: Schema.Struct<{
     }>, Schema.Struct<{
         readonly status: Schema.Literal<"errored">;
         readonly error: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
+        /** The failing step and the app's own error, when the run recorded them. */
+        readonly failure: Schema.optionalKey<Schema.Struct<{
+            step: Schema.optionalKey<Schema.String>;
+            errorName: Schema.optionalKey<Schema.String>;
+            message: Schema.optionalKey<Schema.String>;
+        }>>;
         readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
         readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
         readonly app: Schema.NonEmptyString;

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

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

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

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

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

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

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

@@ -3,4 +3,6 @@ import type { ResolvedAccounts } from "../contracts/host.js";
 /** Missing host support is explicit on use; ordinary apps do not need cache support. */
 export declare const unavailableCache: HostCache;
 /** Account scopes are derived from trusted current bindings. Loaders get a fresh owned HTTP signal. */
-export declare const authorCache: (host: HostCache, accounts: ResolvedAccounts, signal: AbortSignal) => AppCache;
+export declare const authorCache: (host: HostCache, accounts: ResolvedAccounts, signal: AbortSignal, 
+/** The invocation's trusted deadline. Waiting on another caller's load never runs past it. */
+deadline?: number) => AppCache;

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

@@ -1,6 +1,6 @@
 import { Duration, Effect, Schema } from "effect";
 import type { AppCache, CacheLoadContext } from "../contracts/cache.js";
-import { type JsonValue } from "../contracts/schema.js";
+import { JsonObject, type JsonValue } from "../contracts/schema.js";
 export interface CatalogCacheOptions {
     /** App/build scope, optionally narrowed to the current account. */
     readonly cache?: AppCache;
@@ -11,6 +11,11 @@ export interface CatalogCacheOptions {
     /** Await a fresh revision at an explicit logical connection or refresh boundary. */
     readonly revalidate?: boolean;
 }
+/** One load: the tools, and optionally a record describing the whole catalog. */
+export interface CatalogLoad<A> {
+    readonly tools: readonly A[];
+    readonly header?: JsonObject;
+}
 export declare const catalogCache: <A extends {
     readonly name: string;
 }, S>(options: CatalogCacheOptions & {
@@ -21,9 +26,11 @@ export declare const catalogCache: <A extends {
         readonly schema: Schema.Decoder<S>;
         readonly of: (tool: A) => S;
     };
-    readonly load: (context?: CacheLoadContext) => Effect.Effect<readonly A[], unknown>;
+    readonly load: (context?: CacheLoadContext) => Effect.Effect<CatalogLoad<A>, unknown>;
 }) => Effect.Effect<{
     list: () => Effect.Effect<readonly A[], unknown, never>;
+    /** The record stored with the current revision, if the source supplied one. */
+    header: () => Effect.Effect<JsonObject | undefined, unknown>;
     summaries: () => Effect.Effect<S[], unknown, never>;
     resolve: (name: string) => Effect.Effect<A | undefined, unknown, never>;
 }, unknown, never>;

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

@@ -66,10 +66,10 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
                 } | {
                     readonly type: "number" | "integer";
                     readonly default?: number;
+                    readonly maximum?: number;
                     readonly description?: string;
                     readonly title?: string;
                     readonly minimum?: number;
-                    readonly maximum?: number;
                 } | {
                     readonly type: "boolean";
                     readonly default?: boolean;

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

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

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

@@ -1,10 +1,7 @@
 import { Effect } from "effect";
 import { GraphqlToolsOptions } from "../contracts/graphql.js";
-import type { DynamicTools } from "../contracts/dynamic-tools.js";
 import { type CatalogCacheOptions } from "./catalog-cache.js";
 import { type OperationKinds } from "./protocol-operations.js";
 export interface GraphqlCatalogOptions extends GraphqlToolsOptions, CatalogCacheOptions {
 }
-export declare const graphqlCatalog: (options: GraphqlCatalogOptions, kinds: OperationKinds) => Effect.Effect<{
-    dynamicTools: DynamicTools;
-}, unknown, never>;
+export declare const graphqlCatalog: (options: GraphqlCatalogOptions, kinds: OperationKinds) => Effect.Effect<import("./operations.js").RouterDeclaration<unknown, unknown>, unknown, never>;

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

@@ -1,5 +1,4 @@
 import { Effect } from "effect";
-import type { DynamicTools } from "../contracts/dynamic-tools.js";
 import { McpToolsOptions } from "../contracts/mcp.js";
 import { type CatalogCacheOptions } from "./catalog-cache.js";
 import { type OperationKinds } from "./protocol-operations.js";
@@ -7,6 +6,4 @@ import { type OperationKinds } from "./protocol-operations.js";
 export interface McpCatalogOptions extends McpToolsOptions, CatalogCacheOptions {
 }
 /** Construction opens no transport unless explicit revalidation is requested. */
-export declare const mcpCatalog: (options: McpCatalogOptions, kinds: OperationKinds) => Effect.Effect<{
-    dynamicTools: DynamicTools;
-}, unknown, never>;
+export declare const mcpCatalog: (options: McpCatalogOptions, kinds: OperationKinds) => Effect.Effect<import("./operations.js").RouterDeclaration<unknown, unknown>, unknown, never>;

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

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

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

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