apps 0.0.1-beta.0 → 0.0.1-beta.10

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

@@ -0,0 +1,15 @@
+import { Schema } from "effect";
+declare const ProviderError_base: Schema.Class<ProviderError, Schema.TaggedStruct<"ProviderError", {
+    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">>;
+}>, 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.
+ */
+export declare class ProviderError extends ProviderError_base {
+}
+export {};

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

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

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

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

@@ -0,0 +1,122 @@
+/** Portable Agent Skills returned by an app factory or loaded from published files. */
+import { Schema } from "effect";
+/** Canonical resource path within one skill. */
+export declare const SkillFilePath: Schema.NonEmptyString;
+/** UTF-8 text resource. Reading a resource never executes it. */
+export declare const SkillFile: Schema.Struct<{
+    readonly path: Schema.NonEmptyString;
+    readonly content: Schema.String;
+}>;
+export type SkillFile = typeof SkillFile.Type;
+/** Agent Skills format constraints, not Executor execution or storage budgets. */
+export declare const skillFormatLimits: {
+    readonly nameCharacters: 64;
+    readonly descriptionCharacters: 1024;
+    readonly compatibilityCharacters: 500;
+};
+/** A lowercase alphanumeric skill directory name with single separating hyphens. */
+export declare const AppSkillName: Schema.NonEmptyString;
+/** Frontmatter is metadata only. In particular, allowed-tools never grants execution authority. */
+export declare const AppSkillMetadata: Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly description: Schema.String;
+    readonly license: Schema.optionalKey<Schema.String>;
+    readonly compatibility: Schema.optionalKey<Schema.String>;
+    readonly metadata: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly "allowed-tools": Schema.optionalKey<Schema.String>;
+}>;
+export type AppSkillMetadata = typeof AppSkillMetadata.Type;
+/** Files use paths relative to this skill directory; reading one never executes its contents. */
+export declare const AppSkillSource: Schema.Struct<{
+    readonly files: Schema.$Array<Schema.Struct<{
+        readonly path: Schema.NonEmptyString;
+        readonly content: Schema.String;
+    }>>;
+    readonly name: Schema.NonEmptyString;
+    readonly description: Schema.String;
+    readonly license: Schema.optionalKey<Schema.String>;
+    readonly compatibility: Schema.optionalKey<Schema.String>;
+    readonly metadata: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly "allowed-tools": Schema.optionalKey<Schema.String>;
+}>;
+export type AppSkillSource = typeof AppSkillSource.Type;
+declare const SkillDefinitionInvalid_base: Schema.Class<SkillDefinitionInvalid, 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 {
+}
+/** One evaluated catalog cannot contain ambiguous names. */
+export declare const AppSkills: Schema.$Array<Schema.Struct<{
+    readonly files: Schema.$Array<Schema.Struct<{
+        readonly path: Schema.NonEmptyString;
+        readonly content: Schema.String;
+    }>>;
+    readonly name: Schema.NonEmptyString;
+    readonly description: Schema.String;
+    readonly license: Schema.optionalKey<Schema.String>;
+    readonly compatibility: Schema.optionalKey<Schema.String>;
+    readonly metadata: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly "allowed-tools": Schema.optionalKey<Schema.String>;
+}>>;
+/** Short display name for a skill source, such as "GitLab" or an index host name. */
+export declare const SkillServiceName: Schema.String;
+declare const SkillLoadFailed_base: Schema.Class<SkillLoadFailed, Schema.TaggedStruct<"SkillLoadFailed", {
+    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>;
+}>, 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.
+ */
+export declare class SkillLoadFailed extends SkillLoadFailed_base {
+}
+/** Bounds shared by skill loaders across all app hosts. */
+export declare const skillLoadLimits: {
+    readonly files: 1000;
+    readonly fileBytes: 2000000;
+    readonly totalBytes: 20000000;
+    readonly concurrency: 8;
+};
+/** Invocation-owned transport and cancellation, supplied by the app context. */
+export interface SkillTransport {
+    readonly fetch?: typeof globalThis.fetch | undefined;
+    readonly signal?: AbortSignal | undefined;
+}
+/** A custom loader's transport and the service name shown when a request fails. */
+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.
+ */
+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;
+}
+/** A published directory index, including its listed skill documents and text references. */
+export interface WellKnownSkillsOptions extends SkillTransport, SkillCacheOptions {
+    readonly url: string;
+}
+/** A folder in the deployed package; omitted path selects skills/. No host filesystem access. */
+export interface FolderSkillsOptions {
+    readonly files: readonly SkillFile[];
+    readonly path?: string;
+}
+export {};

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/swagger-client.d.ts

@@ -0,0 +1,29 @@
+/** Narrow declarations for the untyped public swagger-client APIs used by our adapters.
+ * Returned data remains unknown and is decoded before it enters Executor.
+ */
+declare module "swagger-client" {
+    const SwaggerClient: {
+        buildRequest(options: {
+            spec: unknown;
+            operationId?: string;
+            pathName?: string;
+            method?: string;
+            parameters?: Readonly<Record<string, unknown>>;
+            requestBody?: unknown;
+            requestContentType?: string;
+            securities?: {
+                authorized: Readonly<Record<string, unknown>>;
+            };
+        }): unknown;
+        resolve(options: {
+            spec: unknown;
+            skipNormalization: boolean;
+            useCircularStructures: boolean;
+            requestInterceptor: () => never;
+        }): Promise<{
+            spec: unknown;
+            errors: readonly unknown[];
+        }>;
+    };
+    export default SwaggerClient;
+}

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

@@ -1,10 +1,8 @@
 /** GraphQL helpers. Requires the optional graphql peer. */
-import { type OperationKinds } from "./implementation/protocol-operations.js";
-import type { GraphqlToolsOptions } from "./contracts/graphql.js";
+import type { OperationKinds } from "./implementation/protocol-operations.js";
+import { type GraphqlCatalogOptions } from "./implementation/graphql-catalog.js";
 export { GraphqlError, type GraphqlToolsOptions } from "./contracts/graphql.js";
-/** Discover operations for the selected account. Kinds override uncertain upstream read-only hints. */
-export declare const graphqlOperations: (options: GraphqlToolsOptions, kinds?: OperationKinds) => Promise<{
-    queries: Record<string, import("./index.js").Operation<import("effect/Schema").Json, unknown, "query", import("./index.js").OperationContext>>;
-    mutations: Record<string, import("./index.js").Operation<import("effect/Schema").Json, unknown, "mutation", import("./index.js").OperationContext>>;
-}>;
+export type { GraphqlCatalogOptions } from "./implementation/graphql-catalog.js";
+/** Lazy tools with optional persistent metadata caching for the selected account. */
+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/host.d.ts

@@ -1,6 +1,7 @@
 import { type HostContext, type ResolvedAccountsInput } from "./contracts/host.js";
 import { type ElicitationHandler } from "./contracts/elicitation.js";
 export type { HostContext, ResolvedAccountsInput } from "./contracts/host.js";
+export { isolatedCacheSession } from "./implementation/cache-session.js";
 /** Parse trusted account bindings and an optional exact-call approval. Throws safe boundary errors on invalid input. */
 export declare const hostContext: (accounts: ResolvedAccountsInput, approval?: unknown) => HostContext;
 /** Portable Promise handler. Invoke only after the host has authorized and resolved accounts. */

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 "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"]> : 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-session.d.ts

@@ -0,0 +1,7 @@
+import type { HostCache } from "../contracts/cache.js";
+/** Own all refresh promises until drained or cancelled. Only generated trusted bridges create sessions. */
+export declare const isolatedCacheSession: (callback: (input: unknown) => Promise<unknown>) => {
+    cache: HostCache;
+    drain: () => Promise<void>;
+    cancel: () => Promise<void>;
+};

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

@@ -0,0 +1,8 @@
+import type { AppCache, HostCache } from "../contracts/cache.js";
+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, 
+/** 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

@@ -0,0 +1,36 @@
+import { Duration, Effect, Schema } from "effect";
+import type { AppCache, CacheLoadContext } from "../contracts/cache.js";
+import { JsonObject, type JsonValue } from "../contracts/schema.js";
+export interface CatalogCacheOptions {
+    /** App/build scope, optionally narrowed to the current account. */
+    readonly cache?: AppCache;
+    /** Reuse metadata for this duration. Defaults to five minutes. */
+    readonly freshFor?: Duration.Input;
+    /** Serve retained metadata while refreshing. Defaults to one day. */
+    readonly staleFor?: Duration.Input;
+    /** 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 & {
+    readonly prefix: readonly JsonValue[];
+    readonly schema: Schema.Decoder<A>;
+    /** Schema-free projection stored beside the full pages, so browsing never reads schemas. */
+    readonly summary: {
+        readonly schema: Schema.Decoder<S>;
+        readonly of: (tool: A) => S;
+    };
+    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/dynamic-skills.d.ts

@@ -0,0 +1,7 @@
+/** Author-facing lazy skill sources adapt once to the framework's Effect execution path. */
+import type { DynamicSkills } from "../contracts/dynamic-skills.js";
+import type { AppSkillSource } from "../contracts/skills.js";
+/** Declare skills that load only when skills are read, such as `list: () => githubSkills({...})`. */
+export declare const dynamicSkills: (source: {
+    readonly list: () => readonly AppSkillSource[] | Promise<readonly AppSkillSource[]>;
+}) => DynamicSkills;