apps 0.0.1-beta.0 → 0.0.1-beta.2

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

@@ -1,5 +1,83 @@
+import { ProviderError } from "../contracts/provider-error.js";
 /** Discover GraphQL tools live; transport, decoding and cancellation stay in Effect. */
-import { Effect } from "effect";
-import { GraphqlError, GraphqlToolsOptions, type GraphqlTools } from "../contracts/graphql.js";
+import { Effect, Schema } from "effect";
+import { OperationTypeNode } from "graphql";
+import { GraphqlError, GraphqlIntrospection, GraphqlToolsOptions, type GraphqlToolDefinition, type GraphqlTools, type GraphqlTypeRef } from "../contracts/graphql.js";
+import { JsonObject } from "../effect.js";
 /** Resolve schema and calls per account evaluation; never cache credentials or tools globally. */
-export declare const graphqlToolsEffect: (input: GraphqlToolsOptions) => Effect.Effect<GraphqlTools, GraphqlError>;
+export declare const graphqlClientEffect: (input: GraphqlToolsOptions) => Effect.Effect<{
+    request: (phase: "discover" | "call", query: string, variables?: JsonObject) => Effect.Effect<{
+        readonly [x: string]: Schema.Json;
+    }, ProviderError | GraphqlError, never>;
+    discover: Effect.Effect<{
+        readonly __schema: {
+            readonly queryType: {
+                readonly name: string;
+            } | null;
+            readonly mutationType: {
+                readonly name: string;
+            } | null;
+            readonly types: readonly {
+                readonly kind: "SCALAR" | "OBJECT" | "INTERFACE" | "UNION" | "ENUM" | "INPUT_OBJECT" | "LIST" | "NON_NULL";
+                readonly name: string;
+                readonly fields: readonly {
+                    readonly name: string;
+                    readonly description: string | null;
+                    readonly args: readonly {
+                        readonly name: string;
+                        readonly description: string | null;
+                        readonly type: GraphqlTypeRef;
+                        readonly defaultValue: string | null;
+                    }[];
+                    readonly type: GraphqlTypeRef;
+                }[] | null;
+                readonly inputFields: readonly {
+                    readonly name: string;
+                    readonly description: string | null;
+                    readonly type: GraphqlTypeRef;
+                    readonly defaultValue: string | null;
+                }[] | null;
+                readonly enumValues: readonly {
+                    readonly name: string;
+                }[] | null;
+            }[];
+        };
+    }, ProviderError | GraphqlError, never>;
+}, GraphqlError, never>;
+/** Build serializable definitions once per introspection revision, without compiling validators. */
+export declare const graphqlDefinitions: (catalog: GraphqlIntrospection) => Effect.Effect<{
+    name: string;
+    kind: OperationTypeNode.QUERY | OperationTypeNode.MUTATION;
+    field: string;
+    description: string;
+    arguments: {
+        name: string;
+        type: string;
+    }[];
+    inputSchema: {
+        type: string;
+        additionalProperties: boolean;
+        properties: {
+            select?: {
+                type: string;
+                minLength: number;
+                description: string;
+            };
+            arguments: {
+                readonly [x: string]: Schema.Json;
+            };
+        };
+        required: string[];
+        $defs: {
+            [k: string]: {
+                readonly [x: string]: Schema.Json;
+            };
+        };
+    };
+    composite: boolean;
+    selection: string;
+}[], GraphqlError, never>;
+/** Bind only the selected definition to current credentials and compile its input decoder. */
+export declare const adaptGraphqlTool: (client: Effect.Success<ReturnType<typeof graphqlClientEffect>>, definition: GraphqlToolDefinition) => Effect.Effect<import("../contracts/graphql.js").GraphqlTool, GraphqlError, never>;
+/** Low-level callers can still request a complete invocation-owned tool map. */
+export declare const graphqlToolsEffect: (input: GraphqlToolsOptions) => Effect.Effect<GraphqlTools, GraphqlError | ProviderError>;

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

@@ -0,0 +1,16 @@
+/**
+ * Minimal zlib (RFC 1950) and DEFLATE (RFC 1951) decoder. Git packfiles concatenate zlib streams
+ * without lengths, so readers must know where each stream ends. Platform decompression streams do
+ * not report that, so this decoder returns the offset after the stream's Adler-32 checksum.
+ */
+/** The stream is malformed. */
+export declare class InflateError extends Error {
+}
+/** The decoded stream would exceed the caller's limit. */
+export declare class InflateLimitExceeded extends Error {
+}
+/** Decode one zlib stream starting at `start`, returning its bytes and the offset after it. */
+export declare const inflateZlib: (input: Uint8Array, start: number, limit: number) => {
+    readonly data: Uint8Array;
+    readonly end: number;
+};

package/types/apps/src/implementation/input-problems.d.ts

@@ -0,0 +1,3 @@
+import { HostInputInvalid } from "../contracts/host.js";
+/** Failing input paths and expected shapes from a schema decode failure, without supplied values. */
+export declare const inputInvalid: (error: unknown) => HostInputInvalid;

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

@@ -1,3 +1,4 @@
+import type { ProviderError } from "../contracts/provider-error.js";
 /** One upstream call, with form requests forwarded to the invocation's existing elicitation capability. */
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { Effect, Schema } from "effect";
@@ -5,7 +6,7 @@ import { ElicitationFailed } from "../contracts/elicitation.js";
 import { McpError, type McpToolContext } from "../contracts/mcp.js";
 import type { JsonObject } from "../contracts/schema.js";
 /** Register prompts only around tools/call, preserve metadata, and close every callback with the call. Never retries. */
-export declare const mcpCall: (client: Client, name: string, input: JsonObject, context: McpToolContext, timeoutMs: number, failure: (phase: McpError["phase"], error: unknown) => McpError) => Effect.Effect<{
+export declare const mcpCall: (client: Client, name: string, input: JsonObject, context: McpToolContext, timeoutMs: number, failure: (phase: McpError["phase"], error: unknown) => McpError | ProviderError) => Effect.Effect<{
     readonly content: readonly {
         readonly [x: string]: Schema.Json;
     }[];
@@ -16,4 +17,4 @@ export declare const mcpCall: (client: Client, name: string, input: JsonObject,
         readonly [x: string]: Schema.Json;
     } | undefined;
     readonly isError?: boolean | undefined;
-}, ElicitationFailed | McpError, never>;
+}, ProviderError | ElicitationFailed | McpError, never>;

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

@@ -0,0 +1,12 @@
+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";
+/** Metadata policy for HTTP/SSE sources. A missing cache keeps discovery invocation-local. */
+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>;

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

@@ -1,3 +1,4 @@
+import type { ProviderError } from "../contracts/provider-error.js";
 /** Shared MCP pagination, wire parsing and calls. Transport owns connection lifetime. */
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { jsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/types.js";
@@ -8,20 +9,23 @@ import type { JsonObject } from "../effect.js";
 export declare const mcpJsonSchemaValidator: jsonSchemaValidator;
 /** An operation owns its connection; it must close even when interrupted. */
 export interface WithMcpClient {
-    <A, E>(mode: "discover" | "call", use: (client: Client) => Effect.Effect<A, E>): Effect.Effect<A, E | McpError>;
+    <A, E>(mode: "discover" | "call", use: (client: Client) => Effect.Effect<A, E>): Effect.Effect<A, E | McpError | ProviderError>;
 }
 /** Shared client operations never cache catalogs or account credentials. */
-export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number, failure: (phase: McpError["phase"], error: unknown) => McpError): {
+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 description?: string | undefined;
+        readonly outputSchema?: {
+            readonly [x: string]: Schema.Json;
+        } | undefined;
         readonly annotations?: {
             readonly title?: string;
             readonly readOnlyHint?: boolean;
@@ -29,10 +33,7 @@ export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number,
             readonly idempotentHint?: boolean;
             readonly openWorldHint?: boolean;
         } | undefined;
-        readonly outputSchema?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-    }[], McpError, never>;
+    }[], ProviderError | McpError, never>;
     call: (name: string, input: JsonObject, context: McpToolContext) => Effect.Effect<{
         readonly content: readonly {
             readonly [x: string]: Schema.Json;
@@ -44,7 +45,7 @@ export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number,
             readonly [x: string]: Schema.Json;
         } | undefined;
         readonly isError?: boolean | undefined;
-    }, import("../index.js").ElicitationFailed | McpError, never>;
+    }, ProviderError | import("../index.js").ElicitationFailed | McpError, never>;
 };
 /** Transport-independent operations consumed by the app tool adapter. */
 export type McpClient = ReturnType<typeof mcpClient>;

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

@@ -1,4 +1,4 @@
 import { Effect } from "effect";
 import { McpError, ProcessConfig } from "../contracts/mcp.js";
 /** Each discovery/call owns and closes its subprocess. Deployment never starts it. */
-export declare const stdioToolsEffect: (input: ProcessConfig) => Effect.Effect<Readonly<Record<string, import("../contracts/mcp.js").McpTool>>, McpError, never>;
+export declare const stdioToolsEffect: (input: ProcessConfig) => Effect.Effect<Readonly<Record<string, import("../contracts/mcp.js").McpTool>>, import("../index.js").ProviderError | McpError, never>;

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

@@ -1,6 +1,9 @@
+import type { ProviderError } from "../contracts/provider-error.js";
 /** Adapt any MCP transport into ordinary tools with shared validation behavior. */
 import { Effect } from "effect";
-import { McpError, type McpTools } from "../contracts/mcp.js";
+import { McpError, type McpTools, type McpToolMetadata } from "../contracts/mcp.js";
 import type { McpClient } from "./mcp-client.js";
-/** Evaluate fresh metadata for the account bound to this client. */
-export declare const adaptMcpTools: (client: McpClient) => Effect.Effect<McpTools, McpError>;
+/** Compile only the selected tool and bind its executable to the current invocation. */
+export declare const adaptMcpTool: (client: McpClient, tool: McpToolMetadata) => Effect.Effect<import("../contracts/mcp.js").McpTool, McpError, never>;
+/** Discover a complete catalog for probes and uncached low-level callers. */
+export declare const adaptMcpTools: (client: McpClient) => Effect.Effect<McpTools, McpError | ProviderError>;

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

@@ -1,4 +1,41 @@
-import { Effect } from "effect";
+import { ProviderError } from "../contracts/provider-error.js";
+import { Effect, Schema } from "effect";
 import { McpError, McpToolsOptions } from "../contracts/mcp.js";
 /** Discover and call with a fresh selected-account transport for each operation. */
-export declare const mcpToolsEffect: (input: McpToolsOptions) => Effect.Effect<Readonly<Record<string, import("../contracts/mcp.js").McpTool>>, McpError, never>;
+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?: {
+            readonly title?: string;
+            readonly readOnlyHint?: boolean;
+            readonly destructiveHint?: boolean;
+            readonly idempotentHint?: boolean;
+            readonly openWorldHint?: boolean;
+        } | undefined;
+    }[], 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;
+        }[];
+        readonly _meta?: {
+            readonly [x: string]: Schema.Json;
+        } | undefined;
+        readonly structuredContent?: {
+            readonly [x: string]: Schema.Json;
+        } | undefined;
+        readonly isError?: boolean | undefined;
+    }, ProviderError | import("../index.js").ElicitationFailed | McpError, never>;
+}, McpError, never>;
+/** Discover and compile all tools for connection probes and low-level consumers. */
+export declare const mcpToolsEffect: (input: McpToolsOptions) => Effect.Effect<Readonly<Record<string, import("../contracts/mcp.js").McpTool>>, ProviderError | McpError, never>;

package/types/apps/src/implementation/openapi-compile.d.ts

@@ -0,0 +1,119 @@
+/** Compile an OpenAPI document into tool declarations inside the app runtime, never a second execution engine. */
+import { Effect, Schema } from "effect";
+import { JsonObject } from "../contracts/schema.js";
+import { OpenapiCompileError as TemplateError } from "../contracts/openapi-compile.js";
+import type { OpenApiImport } from "../contracts/openapi-document.js";
+import { type GeneratedOperation, type GeneratedSecrets } from "../contracts/openapi-document.js";
+/** Compile a revision of a live OpenAPI source into tool declarations for the app runtime. */
+export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocument: unknown, options?: {
+    readonly baseUrl?: string;
+    readonly allowedOrigin?: string;
+    readonly securitySchemes?: Readonly<Record<string, JsonObject>>;
+    readonly fallbackSecurity?: GeneratedOperation["request"]["security"];
+}) => Effect.Effect<{
+    operations: {
+        readonly name: string;
+        readonly path: string;
+        readonly description: string;
+        readonly request: {
+            readonly parameters: readonly {
+                readonly name: string;
+                readonly in: "query" | "path" | "header" | "cookie";
+                readonly required?: boolean;
+                readonly schema?: {
+                    readonly [x: string]: Schema.Json;
+                };
+                readonly content?: {
+                    readonly [x: string]: Schema.Json;
+                };
+                readonly style?: string;
+                readonly explode?: boolean;
+                readonly allowReserved?: boolean;
+                readonly allowEmptyValue?: boolean;
+            }[];
+            readonly security: readonly {
+                readonly [x: string]: readonly string[];
+            }[];
+            readonly responses: {
+                readonly [x: string]: {
+                    readonly [x: string]: Schema.Json;
+                };
+            };
+            readonly requestBody?: {
+                readonly content: {
+                    readonly [x: string]: {
+                        readonly schema?: {
+                            readonly [x: string]: Schema.Json;
+                        };
+                        readonly encoding?: {
+                            readonly [x: string]: Schema.Json;
+                        };
+                    };
+                };
+                readonly required?: boolean;
+            };
+        };
+        readonly input: {
+            readonly [x: string]: Schema.Json;
+        };
+        readonly method: "HEAD" | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
+        readonly securitySchemes: {
+            readonly [x: string]: {
+                readonly [x: string]: Schema.Json;
+            };
+        };
+        readonly baseUrl: string;
+        readonly openapi: string;
+        readonly outputSchema?: {
+            readonly [x: string]: Schema.Json;
+        };
+        readonly operationId?: string;
+        readonly streaming?: true;
+        readonly errorResponses?: readonly {
+            readonly code: string;
+            readonly status: number;
+            readonly message: {
+                readonly source: "body";
+            } | {
+                readonly source: "schema";
+                readonly value: string;
+            };
+            readonly schema: {
+                readonly [x: string]: Schema.Json;
+            };
+        }[];
+    }[];
+    definitions: {
+        [k: string]: {
+            readonly [x: string]: Schema.Json;
+        };
+    };
+    methods: {
+        [k: string]: readonly {
+            readonly scheme: string;
+            readonly field: string;
+            readonly part: "value" | "username" | "password";
+            readonly prefix: string;
+        }[];
+    };
+    secrets: GeneratedSecrets[];
+    oauth: {
+        name: string;
+        config: {
+            discover: string;
+        } | {
+            authorizationUrl: string;
+            tokenUrl: string;
+            scopes: readonly string[];
+        };
+    }[];
+    schemes: {
+        [x: string]: {
+            readonly [x: string]: Schema.Json;
+        };
+    };
+    pinnedOrigin: string | undefined;
+    fallback: readonly {
+        readonly [x: string]: readonly string[];
+    }[] | undefined;
+}, TemplateError, never>;

package/types/apps/src/implementation/openapi-document.d.ts

@@ -0,0 +1,51 @@
+import { Schema } from "effect";
+import { JsonObject } from "../contracts/schema.js";
+/** Resolve OpenAPI objects once with Swagger; schemas retain their original recursive references.
+ * Scalar first upgrades Swagger 2.0 and OpenAPI 3.0 to 3.1, so the importer has one dialect and
+ * 3.1 keywords that appear in 3.0 documents keep their meaning.
+ * Unsupported versions, references and conversions throw TemplateError at the import boundary.
+ */
+export declare function openApiDocument(input: unknown): Promise<{
+    spec: {
+        readonly openapi: string;
+        readonly paths: {
+            readonly [x: string]: {
+                readonly [x: string]: Schema.Json;
+            };
+        };
+        readonly security?: readonly {
+            readonly [x: string]: readonly string[];
+        }[];
+        readonly servers?: readonly {
+            readonly url: string;
+            readonly variables?: {
+                readonly [x: string]: Schema.Json;
+            };
+        }[];
+        readonly components?: {
+            readonly securitySchemes?: {
+                readonly [x: string]: {
+                    readonly [x: string]: Schema.Json;
+                };
+            };
+            readonly schemas?: {
+                readonly [x: string]: {
+                    readonly [x: string]: Schema.Json;
+                };
+            };
+        };
+    };
+    definitions: Map<string, {
+        readonly [x: string]: Schema.Json;
+    }>;
+    /** Inspect a component schema without expanding its children. OpenAPI object refs must already be resolved by Swagger. */
+    resolve(value: JsonObject): JsonObject;
+    /** Compose a Draft 2020-12 schema around API Schema Objects. Only values passed to
+     * `api` use the document's OpenAPI dialect; Executor-authored wrappers are already
+     * Draft 2020-12 and must not be reinterpreted. Reached components are converted once into
+     * the shared `definitions` and stay references here; nothing is inlined or copied per operation.
+     */
+    schema(build: (api: (input: Schema.Json) => JsonObject) => JsonObject): JsonObject;
+}>;
+/** A parsed document with one reference scope and one schema dialect. */
+export type OpenApiDocument = Awaited<ReturnType<typeof openApiDocument>>;

package/types/apps/src/implementation/openapi-names.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Group generated OpenAPI tool names as `<group>.<leaf>`, ported from Executor v1's tool paths.
+ * The group is the first tag, or the first meaningful path segment. The leaf is the operationId
+ * without a repeated group prefix, or a method-and-path name when there is no operationId.
+ */
+export interface OperationNameInput {
+    readonly operationId: string | undefined;
+    /** The first non-empty tag. */
+    readonly tag: string | undefined;
+    readonly method: string;
+    readonly path: string;
+}
+/**
+ * Plan one name per input, in input order. Names that collide are refined together: first by
+ * the path's version segment, then by the HTTP method, then by a stable hash. Refinement only
+ * touches the colliding names, so adding an operation never renames an unrelated one.
+ */
+export declare const planOperationNames: (inputs: readonly OperationNameInput[]) => string[];

package/types/apps/src/implementation/openapi-request.d.ts

@@ -1,11 +1,17 @@
-/** HTTP serialization for normalized OpenAPI operations. */
+import { ProviderError } from "../contracts/provider-error.js";
+/** Swagger constructs requests; Effect owns HTTP policy and bounded results. */
 import { Effect, Schema } from "effect";
-import { OpenapiError, type CredentialBinding, type OpenapiOperation, type OpenapiAccount } from "../contracts/openapi.js";
+import { OpenapiResponseError } from "../contracts/api-response-error.js";
+import { OpenapiError, type CredentialBinding, type OpenapiOperation, type OpenapiAccount, type OpenapiErrorResponse } from "../contracts/openapi.js";
+type DeclaredError = OpenapiErrorResponse & {
+    readonly decoder: Schema.Decoder<Schema.Json>;
+};
 /** Create request helpers from credential-free generated authentication metadata. */
 export declare function createRequest(config: {
     readonly methods: Readonly<Record<string, readonly CredentialBinding[]>>;
     readonly oauth: readonly string[];
 }): {
-    available: (op: OpenapiOperation, method: string | undefined) => boolean;
-    call: (op: OpenapiOperation, input: unknown, account: OpenapiAccount | undefined) => Effect.Effect<Schema.Json, OpenapiError, never>;
+    available: (op: OpenapiOperation, account: OpenapiAccount | undefined) => boolean;
+    call: (op: OpenapiOperation, input: unknown, account: OpenapiAccount | undefined, errors: readonly DeclaredError[]) => Effect.Effect<Schema.Json, ProviderError | OpenapiResponseError | OpenapiError, never>;
 };
+export {};

package/types/apps/src/implementation/openapi-source.d.ts

@@ -0,0 +1,40 @@
+/** Revisioned OpenAPI sources. Calls read a manifest, one operation and only its schema dependencies. */
+import { Duration } from "effect";
+import type { AppCache } from "../contracts/cache.js";
+import { OpenapiOperation, type OpenapiToolsOptions } from "../contracts/openapi.js";
+import { JsonObject, JsonValue } from "../contracts/schema.js";
+import type { DynamicTools } from "../contracts/dynamic-tools.js";
+import { type OperationKinds } from "./protocol-operations.js";
+/** Static credential placement and destination are reviewed when the app is authored/imported. */
+export interface OpenapiSourceOptions extends Omit<OpenapiToolsOptions, "operations" | "definitions"> {
+    readonly cache: AppCache;
+    readonly source: {
+        readonly url: string;
+    } | {
+        readonly document: JsonObject;
+    };
+    readonly allowedOrigin: string;
+    readonly securitySchemes: Readonly<Record<string, JsonObject>>;
+    readonly baseUrl?: string;
+    readonly freshFor?: Duration.Input;
+    readonly staleFor?: Duration.Input;
+    /**
+     * Query or mutation overrides keyed by the document's operationId. An operation without an
+     * operationId is keyed by its generated name without the kind, such as `users.getUsers`.
+     */
+    readonly kinds?: OperationKinds;
+    readonly fallbackSecurity?: OpenapiOperation["request"]["security"];
+    readonly patches?: readonly {
+        readonly op: "add" | "remove" | "replace";
+        readonly path: string;
+        readonly value?: JsonValue;
+    }[];
+}
+/** JSON-object patches are static app configuration and are reapplied to every revision. */
+export declare function patchOpenapi(root: JsonObject, patches: OpenapiSourceOptions["patches"]): JsonObject;
+/** No I/O during app construction. All accounts share credential-free compilation. */
+export declare const liveOpenapiOperations: (options: OpenapiSourceOptions) => {
+    readonly queries: {};
+    readonly mutations: {};
+    readonly dynamicTools: DynamicTools;
+};

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

@@ -1,5 +1,41 @@
 /** Evaluate normalized metadata into ordinary tools, with account-specific security filtering. */
-import { Effect } from "effect";
-import { OpenapiError, OpenapiToolsOptions, type OpenapiTools } from "../contracts/openapi.js";
+import { Effect, Schema } from "effect";
+import { OpenapiError, OpenapiToolsOptions, type OpenapiTools, type OpenapiOperation, type OpenapiParameterDefaults } from "../contracts/openapi.js";
+import type { JsonObject, JsonValue } from "../contracts/schema.js";
+/** Names of shared definitions a JSON value references directly as `#/$defs/<name>`. */
+export declare function references(value: JsonValue, found?: Set<string>): Set<string>;
+/**
+ * Make a schema self-contained with only the shared definitions it reaches. Cycles stay
+ * references to the same definition. A missing definition stays unresolved and fails when
+ * the schema compiles. The schema's own `$defs` keep precedence.
+ */
+export declare const bundler: (definitions: Readonly<Record<string, JsonObject>>) => (schema: JsonObject) => JsonObject;
+/**
+ * Make account-bound parameters optional. Validators omit the values so they stay account-free;
+ * the published schema includes them as `default` so callers can see what an omission sends.
+ */
+export declare const parameterDefaultsInput: (op: OpenapiOperation, defaults: OpenapiParameterDefaults | undefined, publish: boolean) => JsonObject;
+/** Account-free validators can be reused inside a Worker for one immutable revision. */
+export declare const prepareOpenapiOperation: (op: OpenapiOperation, definitions: Readonly<Record<string, JsonObject>>, defaults?: OpenapiParameterDefaults) => Effect.Effect<{
+    input: Schema.declareConstructor<Schema.Json, Schema.Json, readonly [], Schema.Json>;
+    errors: {
+        decoder: Schema.declareConstructor<Schema.Json, Schema.Json, readonly [], Schema.Json>;
+        code: string;
+        status: number;
+        message: {
+            readonly source: "body";
+        } | {
+            readonly source: "schema";
+            readonly value: string;
+        };
+        schema: {
+            readonly [x: string]: Schema.Json;
+        };
+    }[];
+    output: () => {
+        readonly [x: string]: Schema.Json;
+    } | undefined;
+}, never, never>;
+export type PreparedOpenapiOperation = Effect.Success<ReturnType<typeof prepareOpenapiOperation>>;
 /** Decode retained metadata and expose only operations supported by the selected account. */
-export declare const openapiToolsEffect: (options: OpenapiToolsOptions) => Effect.Effect<OpenapiTools, OpenapiError>;
+export declare const openapiToolsEffect: (options: OpenapiToolsOptions, prepared?: ReadonlyMap<string, PreparedOpenapiOperation>) => Effect.Effect<OpenapiTools, OpenapiError>;

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

@@ -0,0 +1,10 @@
+import { Option } from "effect";
+import { ProviderError } from "../contracts/provider-error.js";
+/** Parse and rebuild the allowlisted fields, including when the input is already an Error instance. */
+export declare function parseProviderError(error: unknown): Option.Option<ProviderError>;
+/** Classify only explicit HTTP evidence. Raw provider content never enters the error. */
+export declare function httpProviderError(status: number, headers?: Readonly<Record<string, string>>): ProviderError | undefined;
+/** Attach the account used by the enclosing operation, without preserving arbitrary thrown fields. */
+export declare function accountProviderError<E>(error: E, accountId: string): E | ProviderError;
+/** GraphQL has no standard auth code; recognize these documented codes without guessing from prose. */
+export declare function graphqlProviderError(errors: readonly unknown[], status: number): ProviderError | undefined;

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

@@ -64,6 +64,10 @@ declare const ImportedJsonSchema: unique symbol;
 export declare const importedJsonSchema: (decoder: EffectSchema.Decoder<unknown>) => unknown | undefined;
 /** Attach a composed discovery document without replacing its authoritative native decoder. */
 export declare const withJsonSchemaDocument: <S extends EffectSchema.Decoder<unknown>>(decoder: S, document: JsonObject) => S;
+/** Compute a value on first use and reuse it. */
+export declare const once: <A>(compute: () => A) => (() => A);
+/** Attach a discovery document that is built only when it is first read. */
+export declare const withLazyJsonSchemaDocument: <S extends EffectSchema.Decoder<unknown>>(decoder: S, document: () => JsonObject) => S;
 /**
  * Relocate a self-contained JSON Schema under a document pointer. Resolve references
  * before nesting so account schemas can reuse definition names, IDs and anchors.
@@ -76,12 +80,9 @@ export declare const compileJsonSchemaDecoder: (document: JsonObject) => Effect.
         readonly [x: string]: EffectSchema.Json;
     };
 }, ValidationError, never>;
+export declare const lazyJsonSchemaDecoder: (document: () => JsonObject) => Effect.Effect<EffectSchema.declareConstructor<EffectSchema.Json, EffectSchema.Json, readonly [], EffectSchema.Json>, never, never>;
 /** Preserve the JSON document; compile its validator only when a value is first decoded. */
-export declare const jsonSchemaDecoder: (input: unknown) => Effect.Effect<EffectSchema.declareConstructor<EffectSchema.Json, EffectSchema.Json, readonly [], EffectSchema.Json> & {
-    [ImportedJsonSchema]: {
-        readonly [x: string]: EffectSchema.Json;
-    };
-}, ValidationError, never>;
+export declare const jsonSchemaDecoder: (input: unknown) => Effect.Effect<EffectSchema.declareConstructor<EffectSchema.Json, EffectSchema.Json, readonly [], EffectSchema.Json>, ValidationError, never>;
 /** Import JSON metadata now; unsupported schemas and invalid values fail when parsed. */
 export declare const jsonSchema: (input: unknown) => Schema<EffectSchema.Json>;
 /** Database declaration retained by primitive constructors; nested payload schemas are not database fields. */

package/types/apps/src/implementation/skill-files.d.ts

@@ -0,0 +1,10 @@
+/** One parser for packaged, GitHub and well-known skill files. */
+import { Effect } from "effect";
+import { AppSkillSource, SkillDefinitionInvalid, SkillFile, type FolderSkillsOptions } from "../contracts/skills.js";
+/** Parse one skill directory, retaining its full document and validating an optional source name. */
+export declare const skillFromFiles: (input: readonly SkillFile[], source?: {
+    readonly directory?: string;
+    readonly name?: string;
+}) => Effect.Effect<AppSkillSource, SkillDefinitionInvalid>;
+/** Select immediate skill directories from packaged text files. Never accesses the host filesystem. */
+export declare const folderSkillsEffect: (options: FolderSkillsOptions) => Effect.Effect<readonly AppSkillSource[], SkillDefinitionInvalid>;