apps 0.0.1-beta.0 → 0.0.1-beta.1

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

@@ -1,14 +1,43 @@
-/** Normalized OpenAPI metadata retained with app source; no compiler or protocol client is required. */
+import type { ProviderError } from "./provider-error.js";
+/** Credential-free OpenAPI request declarations and validation schemas retained with app source. */
 import { Schema, type Effect } from "effect";
 import { JsonObject } from "./schema.js";
-/** One parameter's HTTP placement and serialization. */
-export declare const RequestParameter: Schema.Struct<{
+import { type OpenapiResponseError } from "./api-response-error.js";
+/** Tagged error shapes retain an explicit source for their public message. */
+export declare const OpenapiErrorResponse: Schema.Struct<{
+    readonly code: Schema.NonEmptyString;
+    readonly status: Schema.Int;
+    readonly message: Schema.Union<readonly [Schema.Struct<{
+        readonly source: Schema.Literal<"body">;
+    }>, Schema.Struct<{
+        readonly source: Schema.Literal<"schema">;
+        readonly value: Schema.NonEmptyString;
+    }>]>;
+    readonly schema: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+/** A retained declaration used to validate an HTTP failure before exposing its code. */
+export type OpenapiErrorResponse = typeof OpenapiErrorResponse.Type;
+/** Resolved OpenAPI parameter shared by import validation and request construction. */
+export declare const OpenapiParameter: Schema.Struct<{
     readonly name: Schema.String;
-    readonly in: Schema.Literals<readonly ["path", "query", "header"]>;
-    readonly style: Schema.String;
-    readonly explode: Schema.Boolean;
+    readonly in: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+    readonly required: Schema.optionalKey<Schema.Boolean>;
+    readonly schema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly style: Schema.optionalKey<Schema.String>;
+    readonly explode: Schema.optionalKey<Schema.Boolean>;
+    readonly allowReserved: Schema.optionalKey<Schema.Boolean>;
+    readonly allowEmptyValue: Schema.optionalKey<Schema.Boolean>;
+    readonly content: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+}>;
+export type OpenapiParameter = typeof OpenapiParameter.Type;
+/** Preserve media schemas and Encoding Objects for Swagger request construction. */
+export declare const OpenapiRequestBody: Schema.Struct<{
+    readonly required: Schema.optionalKey<Schema.Boolean>;
+    readonly content: Schema.$Record<Schema.String, Schema.Struct<{
+        readonly schema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        readonly encoding: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    }>>;
 }>;
-export type RequestParameter = typeof RequestParameter.Type;
 /** Credential-free operation data emitted by the OpenAPI importer. */
 export declare const OpenapiOperation: Schema.Struct<{
     readonly name: Schema.NonEmptyString;
@@ -16,35 +45,73 @@ export declare const OpenapiOperation: Schema.Struct<{
     readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]>;
     readonly path: Schema.String;
     readonly baseUrl: Schema.String;
-    readonly parameters: Schema.$Array<Schema.Struct<{
-        readonly name: Schema.String;
-        readonly in: Schema.Literals<readonly ["path", "query", "header"]>;
-        readonly style: Schema.String;
-        readonly explode: Schema.Boolean;
-    }>>;
-    readonly body: Schema.Literals<readonly ["json", "base64", "none"]>;
+    readonly openapi: Schema.String;
+    readonly securitySchemes: Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    /** The resolved OpenAPI Operation Object; Executor schemas remain separate. */
+    readonly request: Schema.Struct<{
+        readonly parameters: Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly in: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+            readonly required: Schema.optionalKey<Schema.Boolean>;
+            readonly schema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+            readonly style: Schema.optionalKey<Schema.String>;
+            readonly explode: Schema.optionalKey<Schema.Boolean>;
+            readonly allowReserved: Schema.optionalKey<Schema.Boolean>;
+            readonly allowEmptyValue: Schema.optionalKey<Schema.Boolean>;
+            readonly content: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        }>>;
+        readonly requestBody: Schema.optionalKey<Schema.Struct<{
+            readonly required: Schema.optionalKey<Schema.Boolean>;
+            readonly content: Schema.$Record<Schema.String, Schema.Struct<{
+                readonly schema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                readonly encoding: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+            }>>;
+        }>>;
+        readonly security: Schema.$Array<Schema.$Record<Schema.String, Schema.$Array<Schema.String>>>;
+        readonly responses: Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    }>;
     /** Streams remain in the metadata but cannot run through a single-result tool call. */
     readonly streaming: Schema.optionalKey<Schema.Literal<true>>;
-    readonly security: Schema.$Array<Schema.$Array<Schema.String>>;
     readonly input: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
     readonly outputSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly errorResponses: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly code: Schema.NonEmptyString;
+        readonly status: Schema.Int;
+        readonly message: Schema.Union<readonly [Schema.Struct<{
+            readonly source: Schema.Literal<"body">;
+        }>, Schema.Struct<{
+            readonly source: Schema.Literal<"schema">;
+            readonly value: Schema.NonEmptyString;
+        }>]>;
+        readonly schema: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    }>>>;
 }>;
 export type OpenapiOperation = typeof OpenapiOperation.Type;
-/** One field's placement, potentially combined with other fields in an authentication method. */
+/** Map a selected account field to one Swagger credential value. */
 export declare const CredentialBinding: Schema.Struct<{
     readonly scheme: Schema.String;
     readonly field: Schema.String;
-    readonly in: Schema.Literals<readonly ["header", "query"]>;
-    readonly name: Schema.String;
+    readonly part: Schema.Literals<readonly ["value", "username", "password"]>;
     readonly prefix: Schema.String;
 }>;
 export type CredentialBinding = typeof CredentialBinding.Type;
 /** Selected credentials stay in the server runtime, separate from operation metadata. */
 export declare const OpenapiAccount: Schema.Struct<{
+    readonly id: Schema.optional<Schema.brand<Schema.String, "acc">>;
     readonly method: Schema.String;
     readonly fields: Schema.$Record<Schema.String, Schema.Unknown>;
 }>;
 export type OpenapiAccount = typeof OpenapiAccount.Type;
+/**
+ * Parameter values bound by the selected account, grouped as in tool input. Callers may omit
+ * these parameters; an explicit value still takes precedence and the API still authorizes it.
+ */
+export declare const OpenapiParameterDefaults: Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly query: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+}>;
+export type OpenapiParameterDefaults = typeof OpenapiParameterDefaults.Type;
 /** Parsed options for one account's evaluation. */
 export declare const OpenapiToolsOptions: Schema.Struct<{
     readonly operations: Schema.$Array<Schema.Struct<{
@@ -53,37 +120,76 @@ export declare const OpenapiToolsOptions: Schema.Struct<{
         readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]>;
         readonly path: Schema.String;
         readonly baseUrl: Schema.String;
-        readonly parameters: Schema.$Array<Schema.Struct<{
-            readonly name: Schema.String;
-            readonly in: Schema.Literals<readonly ["path", "query", "header"]>;
-            readonly style: Schema.String;
-            readonly explode: Schema.Boolean;
-        }>>;
-        readonly body: Schema.Literals<readonly ["json", "base64", "none"]>;
+        readonly openapi: Schema.String;
+        readonly securitySchemes: Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        /** The resolved OpenAPI Operation Object; Executor schemas remain separate. */
+        readonly request: Schema.Struct<{
+            readonly parameters: Schema.$Array<Schema.Struct<{
+                readonly name: Schema.String;
+                readonly in: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+                readonly required: Schema.optionalKey<Schema.Boolean>;
+                readonly schema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                readonly style: Schema.optionalKey<Schema.String>;
+                readonly explode: Schema.optionalKey<Schema.Boolean>;
+                readonly allowReserved: Schema.optionalKey<Schema.Boolean>;
+                readonly allowEmptyValue: Schema.optionalKey<Schema.Boolean>;
+                readonly content: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+            }>>;
+            readonly requestBody: Schema.optionalKey<Schema.Struct<{
+                readonly required: Schema.optionalKey<Schema.Boolean>;
+                readonly content: Schema.$Record<Schema.String, Schema.Struct<{
+                    readonly schema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                    readonly encoding: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                }>>;
+            }>>;
+            readonly security: Schema.$Array<Schema.$Record<Schema.String, Schema.$Array<Schema.String>>>;
+            readonly responses: Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        }>;
         /** Streams remain in the metadata but cannot run through a single-result tool call. */
         readonly streaming: Schema.optionalKey<Schema.Literal<true>>;
-        readonly security: Schema.$Array<Schema.$Array<Schema.String>>;
         readonly input: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
         readonly outputSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        readonly errorResponses: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+            readonly code: Schema.NonEmptyString;
+            readonly status: Schema.Int;
+            readonly message: Schema.Union<readonly [Schema.Struct<{
+                readonly source: Schema.Literal<"body">;
+            }>, Schema.Struct<{
+                readonly source: Schema.Literal<"schema">;
+                readonly value: Schema.NonEmptyString;
+            }>]>;
+            readonly schema: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        }>>>;
     }>>;
+    /**
+     * Component schemas stored once per app and referenced as `#/$defs/<name>`. Operations
+     * generated before shared definitions carry their own `$defs` and omit this.
+     */
+    readonly definitions: Schema.optional<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>>;
     readonly methods: Schema.$Record<Schema.String, Schema.$Array<Schema.Struct<{
         readonly scheme: Schema.String;
         readonly field: Schema.String;
-        readonly in: Schema.Literals<readonly ["header", "query"]>;
-        readonly name: Schema.String;
+        readonly part: Schema.Literals<readonly ["value", "username", "password"]>;
         readonly prefix: Schema.String;
     }>>>;
     readonly oauth: Schema.$Array<Schema.String>;
     readonly account: Schema.optional<Schema.Struct<{
+        readonly id: Schema.optional<Schema.brand<Schema.String, "acc">>;
         readonly method: Schema.String;
         readonly fields: Schema.$Record<Schema.String, Schema.Unknown>;
     }>>;
+    readonly parameterDefaults: Schema.optional<Schema.Struct<{
+        readonly path: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+        readonly query: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+        readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    }>>;
     readonly signal: Schema.optional<Schema.instanceOf<AbortSignal, AbortSignal>>;
     readonly fetch: Schema.optional<Schema.declare<typeof fetch, typeof fetch>>;
 }>;
 /** JSON imports are decoded at the helper boundary, without assertions in app source. */
-export type OpenapiToolsOptions = Omit<typeof OpenapiToolsOptions.Type, "operations"> & {
+export type OpenapiToolsOptions = Omit<typeof OpenapiToolsOptions.Type, "operations" | "definitions"> & {
     readonly operations: unknown;
+    readonly definitions?: unknown;
 };
 declare const OpenapiError_base: Schema.Class<OpenapiError, Schema.TaggedStruct<"OpenapiError", {
     readonly reason: Schema.Literals<readonly ["invalid_definition", "invalid_input", "request"]>;
@@ -98,8 +204,22 @@ export interface OpenapiTool {
     readonly readOnly: boolean;
     readonly outputSchema?: JsonObject;
     readonly input: Schema.Decoder<Schema.Json>;
-    readonly run: (context: unknown, input: Schema.Json) => Effect.Effect<unknown, OpenapiError>;
+    readonly run: (context: unknown, input: Schema.Json) => Effect.Effect<unknown, OpenapiError | OpenapiResponseError | ProviderError>;
 }
 /** Executable operations keyed by their generated names. */
 export type OpenapiTools = Readonly<Record<string, OpenapiTool>>;
+/** Tool calls buffer one bounded result; live event streams require an authored subscription. */
+export declare const defaultOpenapiResponseLimits: {
+    readonly maxBodyBytes: 16777216;
+    readonly readTimeoutMs: 30000;
+};
+/** Media returned as text rather than a base64 file. NDJSON remains an unparsed text result. */
+export declare const isOpenapiTextMedia: (type: string) => boolean;
+/** A form field that carries raw file bytes: OpenAPI 3.1 `contentMediaType` without an
+ * encoding, or the `format: binary` string that 3.1 documents still commonly use. */
+export declare const isOpenapiFileSchema: (shape: Readonly<Record<string, unknown>>) => boolean;
+/** JSON-safe binary result, independent of the host's file storage. */
+export declare const openapiBinaryResultSchema: JsonObject;
+/** Classify request media for JSON-safe tool arguments; Swagger owns wire serialization. */
+export declare const openapiMediaKind: (type: string) => "form" | "text" | "binary" | "json" | "multipart";
 export {};

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

@@ -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>>;

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

@@ -0,0 +1,113 @@
+/** 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;
+}
+/** A public GitHub repository and an optional immutable commit, tag or branch. */
+export interface GitHubSkillsOptions extends SkillTransport {
+    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 {
+    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/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/graphql.d.ts

@@ -1,10 +1,10 @@
 /** 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 graphqlOperations: (options: GraphqlCatalogOptions, kinds?: OperationKinds) => Promise<{
+    dynamicTools: import("./contracts/dynamic-tools.js").DynamicTools;
 }>;
 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-operations.d.ts

@@ -1,9 +1,13 @@
-import type { OperationContext } from "../contracts/operations.js";
+/** Combine account-bound protocol operations without changing their upstream inputs. */
+import { Effect, Schema } from "effect";
+import type { DynamicTools } from "../contracts/dynamic-tools.js";
+import type { AppOperation, OperationContext } from "../contracts/operations.js";
 import { type JsonValue } from "../contracts/schema.js";
 import { type Operation } from "./operations.js";
 type Operations = {
-    readonly queries: Readonly<Record<string, Operation<JsonValue, unknown, "query", OperationContext>>>;
-    readonly mutations: Readonly<Record<string, Operation<JsonValue, unknown, "mutation", OperationContext>>>;
+    readonly queries?: Readonly<Record<string, Operation<JsonValue, unknown, "query", OperationContext>>>;
+    readonly dynamicTools?: DynamicTools;
+    readonly mutations?: Readonly<Record<string, Operation<JsonValue, unknown, "mutation", OperationContext>>>;
 };
 /**
  * Discover each selected account's protocol operations and combine matching names.
@@ -28,5 +32,120 @@ export declare const accountOperations: <Account extends {
             readonly input: unknown;
         }, unknown, "mutation", import("../index.js").AppContext>;
     };
+} | {
+    dynamicTools: {
+        list: () => Effect.Effect<{
+            readonly name: string;
+            readonly description: string;
+            readonly inputSchema: {
+                readonly [x: string]: Schema.Json;
+            };
+            readonly _meta?: {
+                readonly [x: string]: Schema.Json;
+            };
+            readonly title?: string;
+            readonly outputSchema?: {
+                readonly [x: string]: Schema.Json;
+            };
+            readonly annotations?: {
+                readonly title?: string;
+                readonly readOnlyHint?: boolean;
+                readonly destructiveHint?: boolean;
+                readonly idempotentHint?: boolean;
+                readonly openWorldHint?: boolean;
+            };
+            readonly schedules?: readonly {
+                readonly name: string;
+                readonly timing: {
+                    readonly kind: "interval";
+                    readonly milliseconds: number;
+                } | {
+                    readonly kind: "cron";
+                    readonly calendar: {
+                        readonly expression: string;
+                        readonly timezone: string;
+                    };
+                };
+                readonly input: Schema.Json;
+            }[];
+            readonly readOnly?: boolean;
+        }[], unknown, never>;
+        summaries: () => Effect.Effect<{
+            readonly name: string;
+            readonly description: string;
+            readonly title?: string;
+            readonly annotations?: {
+                readonly title?: string;
+                readonly readOnlyHint?: boolean;
+                readonly destructiveHint?: boolean;
+                readonly idempotentHint?: boolean;
+                readonly openWorldHint?: boolean;
+            };
+            readonly schedules?: readonly {
+                readonly name: string;
+                readonly timing: {
+                    readonly kind: "interval";
+                    readonly milliseconds: number;
+                } | {
+                    readonly kind: "cron";
+                    readonly calendar: {
+                        readonly expression: string;
+                        readonly timezone: string;
+                    };
+                };
+                readonly input: Schema.Json;
+            }[];
+            readonly readOnly?: boolean;
+        }[], unknown, never>;
+        describe: (name: string) => Effect.Effect<{
+            readonly name: string;
+            readonly description: string;
+            readonly inputSchema: {
+                readonly [x: string]: Schema.Json;
+            };
+            readonly _meta?: {
+                readonly [x: string]: Schema.Json;
+            };
+            readonly title?: string;
+            readonly outputSchema?: {
+                readonly [x: string]: Schema.Json;
+            };
+            readonly annotations?: {
+                readonly title?: string;
+                readonly readOnlyHint?: boolean;
+                readonly destructiveHint?: boolean;
+                readonly idempotentHint?: boolean;
+                readonly openWorldHint?: boolean;
+            };
+            readonly schedules?: readonly {
+                readonly name: string;
+                readonly timing: {
+                    readonly kind: "interval";
+                    readonly milliseconds: number;
+                } | {
+                    readonly kind: "cron";
+                    readonly calendar: {
+                        readonly expression: string;
+                        readonly timezone: string;
+                    };
+                };
+                readonly input: Schema.Json;
+            }[];
+            readonly readOnly?: boolean;
+        } | undefined, unknown, never>;
+        resolve: (name: string) => Effect.Effect<AppOperation<unknown, unknown> | undefined, unknown, never>;
+    };
+    queries: {
+        [k: string]: Operation<{
+            readonly accountId: string;
+            readonly input: unknown;
+        }, unknown, "query", import("../index.js").AppContext>;
+    };
+    mutations: {
+        [k: string]: Operation<{
+            readonly accountId: string;
+            readonly input: unknown;
+        }, unknown, "mutation", import("../index.js").AppContext>;
+    };
 }>;
 export {};

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

@@ -22,7 +22,7 @@ export type AppDefinition<Requirements extends AppRequirements> = {
 };
 /** 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 "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];
 };
 declare const InternalApp: unique symbol;
 /** Recognize a declaration from this framework instance before host adaptation. */