apps 0.0.1-beta.3 → 0.0.1-beta.30

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

@@ -1,8 +1,8 @@
 import { Duration, Effect, Schema } from "effect";
 import type { AppCache, CacheLoadContext } from "../contracts/cache.js";
-import { type JsonValue } from "../contracts/schema.js";
+import { JsonObject, type JsonValue } from "../contracts/schema.js";
 export interface CatalogCacheOptions {
-    /** App/build scope, optionally narrowed to the current account. */
+    /** The app's cache. An account's catalog is kept in that account's scope. */
     readonly cache?: AppCache;
     /** Reuse metadata for this duration. Defaults to five minutes. */
     readonly freshFor?: Duration.Input;
@@ -11,9 +11,37 @@ export interface CatalogCacheOptions {
     /** Await a fresh revision at an explicit logical connection or refresh boundary. */
     readonly revalidate?: boolean;
 }
+/**
+ * Whose catalog a remote router reads. A public server takes neither field. Credential headers
+ * come only with the account they belong to, so an authenticated catalog always has its account.
+ */
+export type CatalogAccount = {
+    readonly account?: undefined;
+    readonly headers?: undefined;
+} | {
+    /** The selected account, as `accounts.<slot>` provides it. */
+    readonly account: {
+        readonly id: string;
+    };
+    /** Headers for this account's requests, such as its credentials. */
+    readonly headers?: Readonly<Record<string, string>>;
+};
+/**
+ * The cache an account's catalog lives in: the account's own scope, which token renewals keep.
+ * Credentials never enter a key. Headers without an account, or an account the app was not
+ * given, fail with `invalid`.
+ */
+export declare const catalogScope: <E>(options: CatalogCacheOptions & CatalogAccount, invalid: () => E) => Effect.Effect<AppCache | undefined, E>;
+/** 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 & {
+}, S>(options: Omit<CatalogCacheOptions, "cache"> & {
+    /** The scope from `catalogScope`; undefined keeps discovery invocation-local. */
+    readonly cache: AppCache | undefined;
     readonly prefix: readonly JsonValue[];
     readonly schema: Schema.Decoder<A>;
     /** Schema-free projection stored beside the full pages, so browsing never reads schemas. */
@@ -21,9 +49,11 @@ export declare const catalogCache: <A extends {
         readonly schema: Schema.Decoder<S>;
         readonly of: (tool: A) => S;
     };
-    readonly load: (context?: CacheLoadContext) => Effect.Effect<readonly A[], unknown>;
+    readonly load: (context?: CacheLoadContext) => Effect.Effect<CatalogLoad<A>, unknown>;
 }) => Effect.Effect<{
     list: () => Effect.Effect<readonly A[], unknown, never>;
+    /** The record stored with the current revision, if the source supplied one. */
+    header: () => Effect.Effect<JsonObject | undefined, unknown>;
     summaries: () => Effect.Effect<S[], unknown, never>;
     resolve: (name: string) => Effect.Effect<A | undefined, unknown, never>;
 }, unknown, never>;

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

@@ -12,15 +12,15 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
                 readonly [x: string]: {
                     readonly type: "string";
                     readonly enum: readonly string[];
-                    readonly default?: string;
                     readonly description?: string;
+                    readonly default?: string;
                     readonly title?: string;
                     readonly enumNames?: readonly string[];
                 } | {
                     readonly type: "string";
                     readonly enum: readonly string[];
-                    readonly default?: string;
                     readonly description?: string;
+                    readonly default?: string;
                     readonly title?: string;
                 } | {
                     readonly type: "string";
@@ -28,8 +28,8 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
                         readonly const: string;
                         readonly title: string;
                     }[];
-                    readonly default?: string;
                     readonly description?: string;
+                    readonly default?: string;
                     readonly title?: string;
                 } | {
                     readonly type: "array";
@@ -37,8 +37,8 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
                         readonly type: "string";
                         readonly enum: readonly string[];
                     };
-                    readonly default?: readonly string[];
                     readonly description?: string;
+                    readonly default?: readonly string[];
                     readonly title?: string;
                     readonly minItems?: number;
                     readonly maxItems?: number;
@@ -50,30 +50,30 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
                             readonly title: string;
                         }[];
                     };
-                    readonly default?: readonly string[];
                     readonly description?: string;
+                    readonly default?: readonly string[];
                     readonly title?: string;
                     readonly minItems?: number;
                     readonly maxItems?: number;
                 } | {
                     readonly type: "string";
+                    readonly description?: string;
                     readonly default?: string;
                     readonly format?: "email" | "uri" | "date" | "date-time";
-                    readonly description?: string;
                     readonly title?: string;
                     readonly minLength?: number;
                     readonly maxLength?: number;
                 } | {
                     readonly type: "number" | "integer";
-                    readonly default?: number;
                     readonly description?: string;
+                    readonly default?: number;
+                    readonly maximum?: number;
                     readonly title?: string;
                     readonly minimum?: number;
-                    readonly maximum?: number;
                 } | {
                     readonly type: "boolean";
-                    readonly default?: boolean;
                     readonly description?: string;
+                    readonly default?: boolean;
                     readonly title?: string;
                 };
             };

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

@@ -0,0 +1,46 @@
+import { Option, Redacted } from "effect";
+import type { ResolvedAccounts } from "../contracts/host.js";
+import { McpError } from "../contracts/mcp.js";
+import type { ProviderError } from "../contracts/provider-error.js";
+import { type FailureFields, type FailurePhase, type UpstreamError } from "../contracts/failure.js";
+/** Fields of `FailureDetail` as constructor input. */
+export interface FailureDetail {
+    readonly source?: "app" | "storage" | "service";
+    readonly errorName?: string;
+    readonly code?: string;
+    readonly message?: string;
+    readonly fields?: FailureFields;
+}
+/**
+ * Every credential field value of a slot-to-account record, longest first. Accepts both resolved
+ * host accounts and bound author accounts; each account keeps its credential values in `fields`.
+ */
+export declare const accountFieldSecrets: (accounts: unknown) => string[];
+/** Every credential field value of an invocation's selected accounts. */
+export declare const accountSecrets: (accounts: Redacted.Redacted<ResolvedAccounts>) => string[];
+/** Replace account secrets and bound the message for the runtime boundary. */
+export declare const boundFailureMessage: (message: string, secrets: readonly string[]) => string;
+/**
+ * Replace account secrets in the error a service stated, as it leaves the bundle. A message
+ * shortened where it was read can end partway through a secret; that part is replaced too.
+ */
+export declare const redactUpstream: (upstream: UpstreamError | undefined, secrets: readonly string[]) => UpstreamError | undefined;
+/**
+ * A provider failure as it leaves the bundle: in the phase it happened, unless its raiser named a
+ * more precise one, with account secrets replaced in the error the service stated.
+ */
+export declare const leavingProviderError: (error: ProviderError, secrets: readonly string[], phase?: FailurePhase) => ProviderError;
+/**
+ * Rebuild an MCP failure's allowlisted fields, with account secrets replaced in the server's
+ * error. Absent fields have no key, as catalogs cross the boundary as JSON values.
+ */
+export declare const parseMcpError: (error: unknown, secrets: readonly string[]) => Option.Option<McpError>;
+/** `Name: message` for any thrown value, before redaction. */
+export declare const describeFailure: (error: unknown) => string;
+/**
+ * Describe what an operation raised for the app's own caller. App data failures keep their
+ * reason as a code, as do app cache failures and OpenAPI and MCP service failures, such as an
+ * `mcpHealth` check that cannot reach its server or cannot verify the credentials; any other thrown
+ * value is the app's own error, with its own code and scalar fields. Account secrets are replaced.
+ */
+export declare const failureDetail: (error: unknown, secrets: readonly string[]) => FailureDetail;

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

@@ -1,10 +1,7 @@
 import { Effect } from "effect";
 import { GraphqlToolsOptions } from "../contracts/graphql.js";
-import type { DynamicTools } from "../contracts/dynamic-tools.js";
-import { type CatalogCacheOptions } from "./catalog-cache.js";
+import { type CatalogAccount, type CatalogCacheOptions } from "./catalog-cache.js";
 import { type OperationKinds } from "./protocol-operations.js";
-export interface GraphqlCatalogOptions extends GraphqlToolsOptions, CatalogCacheOptions {
-}
-export declare const graphqlCatalog: (options: GraphqlCatalogOptions, kinds: OperationKinds) => Effect.Effect<{
-    dynamicTools: DynamicTools;
-}, unknown, never>;
+/** An endpoint, the account whose schema it is, and the metadata policy. */
+export type GraphqlCatalogOptions = Omit<GraphqlToolsOptions, "accountId" | "headers"> & CatalogCacheOptions & CatalogAccount;
+export declare const graphqlCatalog: (options: GraphqlCatalogOptions, kinds: OperationKinds) => Effect.Effect<import("./operations.js").RouterDeclaration<unknown, unknown>, unknown, never>;

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

@@ -1,4 +1,5 @@
 import { ProviderError } from "../contracts/provider-error.js";
+import { NetworkRefused } from "../contracts/network.js";
 /** Discover GraphQL tools live; transport, decoding and cancellation stay in Effect. */
 import { Effect, Schema } from "effect";
 import { OperationTypeNode } from "graphql";
@@ -8,7 +9,7 @@ import { JsonObject } from "../effect.js";
 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>;
+    }, ProviderError | NetworkRefused | GraphqlError, never>;
     discover: Effect.Effect<{
         readonly __schema: {
             readonly queryType: {
@@ -42,7 +43,7 @@ export declare const graphqlClientEffect: (input: GraphqlToolsOptions) => Effect
                 }[] | null;
             }[];
         };
-    }, ProviderError | GraphqlError, never>;
+    }, ProviderError | NetworkRefused | GraphqlError, never>;
 }, GraphqlError, never>;
 /** Build serializable definitions once per introspection revision, without compiling validators. */
 export declare const graphqlDefinitions: (catalog: GraphqlIntrospection) => Effect.Effect<{
@@ -80,4 +81,4 @@ export declare const graphqlDefinitions: (catalog: GraphqlIntrospection) => Effe
 /** 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>;
+export declare const graphqlToolsEffect: (input: GraphqlToolsOptions) => Effect.Effect<GraphqlTools, GraphqlError | ProviderError | NetworkRefused>;

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

@@ -1,4 +1,5 @@
 import type { ProviderError } from "../contracts/provider-error.js";
+import type { NetworkRefused } from "../contracts/network.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";
@@ -6,15 +7,15 @@ 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 | ProviderError) => Effect.Effect<{
+export declare const mcpCall: (client: Client, name: string, input: JsonObject, context: McpToolContext, timeoutMs: number, failure: (phase: McpError["phase"], error: unknown) => McpError | ProviderError | NetworkRefused) => 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 | ElicitationFailed | McpError, never>;
+    };
+    readonly isError?: boolean;
+}, ProviderError | NetworkRefused | ElicitationFailed | McpError, never>;

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

@@ -1,12 +1,11 @@
 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 CatalogAccount, 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 {
-}
+/**
+ * A server, the account whose catalog it is, and the metadata policy for HTTP/SSE sources. A
+ * missing cache keeps discovery invocation-local.
+ */
+export type McpCatalogOptions = Omit<McpToolsOptions, "accountId" | "headers"> & CatalogCacheOptions & CatalogAccount;
 /** Construction opens no transport unless explicit revalidation is requested. */
-export declare const mcpCatalog: (options: McpCatalogOptions, kinds: OperationKinds) => Effect.Effect<{
-    dynamicTools: DynamicTools;
-}, unknown, never>;
+export declare const mcpCatalog: (options: McpCatalogOptions, kinds: OperationKinds) => Effect.Effect<import("./operations.js").RouterDeclaration<unknown, unknown>, unknown, never>;

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

@@ -1,51 +1,75 @@
 import type { ProviderError } from "../contracts/provider-error.js";
+import type { NetworkRefused } from "../contracts/network.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";
 import { Effect, Schema } from "effect";
 import { McpError, type McpToolContext } from "../contracts/mcp.js";
+import type { UpstreamError } from "../contracts/failure.js";
 import type { JsonObject } from "../effect.js";
+/**
+ * The JSON-RPC error a server answered a request with, if `error` is one. The SDK formats its
+ * message as `MCP error <code>: <message>`; the server's own message follows that prefix.
+ */
+export declare const answeredError: (error: unknown) => UpstreamError | undefined;
 /** Use the framework-owned interpreter at the MCP SDK's synchronous validation boundary. */
 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 | ProviderError>;
+    <A, E>(mode: "discover" | "call", use: (client: Client) => Effect.Effect<A, E>): Effect.Effect<A, E | McpError | ProviderError | NetworkRefused>;
 }
 /** Shared client operations never cache catalogs or account credentials. */
-export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number, failure: (phase: McpError["phase"], error: unknown) => McpError | ProviderError): {
+export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number, failure: (phase: McpError["phase"], error: unknown) => McpError | ProviderError | NetworkRefused): {
     list: Effect.Effect<{
-        readonly name: string;
-        readonly inputSchema: {
-            readonly [x: string]: Schema.Json;
-        };
-        readonly description?: string | undefined;
-        readonly _meta?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly title?: string | undefined;
-        readonly outputSchema?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly annotations?: {
+        tools: {
+            readonly name: string;
+            readonly inputSchema: {
+                readonly [x: string]: Schema.Json;
+            };
+            readonly description?: string | undefined;
+            readonly _meta?: {
+                readonly [x: string]: Schema.Json;
+            } | undefined;
+            readonly title?: string | undefined;
+            readonly annotations?: {
+                readonly title?: string;
+                readonly readOnlyHint?: boolean;
+                readonly destructiveHint?: boolean;
+                readonly idempotentHint?: boolean;
+                readonly openWorldHint?: boolean;
+            } | undefined;
+            readonly outputSchema?: {
+                readonly [x: string]: Schema.Json;
+            } | undefined;
+        }[];
+        server: {
+            readonly description?: string;
+            readonly version?: string;
+            readonly name?: string;
             readonly title?: string;
-            readonly readOnlyHint?: boolean;
-            readonly destructiveHint?: boolean;
-            readonly idempotentHint?: boolean;
-            readonly openWorldHint?: boolean;
-        } | undefined;
-    }[], ProviderError | McpError, never>;
+            readonly instructions?: string;
+            readonly icons?: readonly {
+                readonly src: string;
+                readonly mimeType?: string;
+                readonly sizes?: readonly string[];
+                readonly theme?: "light" | "dark";
+            }[];
+            readonly websiteUrl?: string;
+        } | {};
+    }, ProviderError | NetworkRefused | McpError, never>;
+    check: Effect.Effect<void, ProviderError | NetworkRefused | McpError, never>;
     call: (name: string, input: JsonObject, context: 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>;
+        };
+        readonly isError?: boolean;
+    }, ProviderError | NetworkRefused | 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>>, import("../index.js").ProviderError | McpError, never>;
+export declare const stdioToolsEffect: (input: ProcessConfig) => Effect.Effect<Readonly<Record<string, import("../contracts/mcp.js").McpTool>>, import("../index.js").ProviderError | import("../index.js").NetworkRefused | McpError, never>;

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

@@ -1,4 +1,5 @@
 import type { ProviderError } from "../contracts/provider-error.js";
+import type { NetworkRefused } from "../contracts/network.js";
 /** Adapt any MCP transport into ordinary tools with shared validation behavior. */
 import { Effect } from "effect";
 import { McpError, type McpTools, type McpToolMetadata } from "../contracts/mcp.js";
@@ -6,4 +7,4 @@ import type { McpClient } from "./mcp-client.js";
 /** 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>;
+export declare const adaptMcpTools: (client: McpClient) => Effect.Effect<McpTools, McpError | ProviderError | NetworkRefused>;

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

@@ -1,41 +1,68 @@
 import { ProviderError } from "../contracts/provider-error.js";
 import { Effect, Schema } from "effect";
-import { McpError, McpToolsOptions } from "../contracts/mcp.js";
+import { McpCredentialsUnverified, McpError, McpToolsOptions, type McpHealthCheck, type McpHealthOptions } from "../contracts/mcp.js";
+import { NetworkRefused } from "../contracts/network.js";
 /** Discover and call with a fresh selected-account transport for each operation. */
 export declare const mcpClientEffect: (input: McpToolsOptions, changed?: Effect.Effect<void, unknown>) => Effect.Effect<{
     list: Effect.Effect<{
-        readonly name: string;
-        readonly inputSchema: {
-            readonly [x: string]: Schema.Json;
-        };
-        readonly description?: string | undefined;
-        readonly _meta?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly title?: string | undefined;
-        readonly outputSchema?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly annotations?: {
+        tools: {
+            readonly name: string;
+            readonly inputSchema: {
+                readonly [x: string]: Schema.Json;
+            };
+            readonly description?: string | undefined;
+            readonly _meta?: {
+                readonly [x: string]: Schema.Json;
+            } | undefined;
+            readonly title?: string | undefined;
+            readonly annotations?: {
+                readonly title?: string;
+                readonly readOnlyHint?: boolean;
+                readonly destructiveHint?: boolean;
+                readonly idempotentHint?: boolean;
+                readonly openWorldHint?: boolean;
+            } | undefined;
+            readonly outputSchema?: {
+                readonly [x: string]: Schema.Json;
+            } | undefined;
+        }[];
+        server: {
+            readonly description?: string;
+            readonly version?: string;
+            readonly name?: string;
             readonly title?: string;
-            readonly readOnlyHint?: boolean;
-            readonly destructiveHint?: boolean;
-            readonly idempotentHint?: boolean;
-            readonly openWorldHint?: boolean;
-        } | undefined;
-    }[], ProviderError | McpError, never>;
+            readonly instructions?: string;
+            readonly icons?: readonly {
+                readonly src: string;
+                readonly mimeType?: string;
+                readonly sizes?: readonly string[];
+                readonly theme?: "light" | "dark";
+            }[];
+            readonly websiteUrl?: string;
+        } | {};
+    }, ProviderError | NetworkRefused | McpError, never>;
+    check: Effect.Effect<void, ProviderError | NetworkRefused | 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>;
+        };
+        readonly isError?: boolean;
+    }, ProviderError | NetworkRefused | import("../index.js").ElicitationFailed | McpError, never>;
 }, McpError, never>;
+/**
+ * Check one account: initialize and read the first page of tools with the account's headers, then
+ * repeat that with no headers on a fresh transport. A refused account fails with its
+ * `ProviderError`, and anything else that stops the first check is an `McpError`; the second never
+ * runs. The check passes only when the server refuses the second, which shows it checked the
+ * credentials. Otherwise it fails with `McpCredentialsUnverified`. Both share one budget, which
+ * ends early enough before the check context's deadline to close the session and report why.
+ */
+export declare const mcpHealthEffect: (check: McpHealthCheck, options: McpHealthOptions) => Effect.Effect<void, ProviderError | NetworkRefused | McpError | McpCredentialsUnverified, 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>;
+export declare const mcpToolsEffect: (input: McpToolsOptions) => Effect.Effect<Readonly<Record<string, import("../contracts/mcp.js").McpTool>>, ProviderError | NetworkRefused | McpError, never>;

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

@@ -0,0 +1,16 @@
+/** Typed refusals and option checks for the fetch app code receives from the framework. */
+import { Effect } from "effect";
+import type { HttpClientResponse } from "effect/unstable/http";
+import { type NetworkRefused } from "../contracts/network.js";
+type Fetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** Fail with the refusal a protocol helper's response carries, or continue to its own handling. */
+export declare const failOnNetworkRefusal: (response: HttpClientResponse.HttpClientResponse) => Effect.Effect<void, NetworkRefused>;
+/**
+ * The fetch app code receives as `ctx.fetch`. It rejects a RequestInit value the app runtime
+ * would reject, naming the option, on every host. A request Executor's app network refused
+ * rejects with `NetworkRefused`: the service never answered, so there is no response to return.
+ */
+export declare const appFetch: (fetch: Fetch) => Fetch;
+/** The invocation's correlated, cancellable fetch, as app code receives it. */
+export declare const appInvocationFetch: (signal: AbortSignal) => Effect.Effect<Fetch, never, never>;
+export {};

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

@@ -1,24 +1,35 @@
 /** 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 { OpenapiErrorResponse } from "../contracts/openapi.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?: {
+import { type OpenApiDocument } from "./openapi-document.js";
+/** Keep tagged errors, including response/component refs and anyOf alternatives.
+ * Public text comes from a declared string message or the schema's static description.
+ * `scripts/check-api-errors.ts` applies this to Executor's own API documents.
+ */
+export declare function errorResponses(document: OpenApiDocument, operation: JsonObject, at: string): OpenapiErrorResponse[];
+/** Compile a revision of a live OpenAPI source into tool declarations for the app runtime.
+ * The document is consumed: compilation upgrades it in place instead of copying it. It must be a
+ * tree, with no object reached twice, as parsed JSON is.
+ */
+export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocument: JsonObject, options?: {
     readonly baseUrl?: string;
     readonly allowedOrigin?: string;
+    /** Inserted between every operation's server and path; see `prefixParameters`. */
+    readonly pathPrefix?: 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 name: string;
         readonly request: {
             readonly parameters: readonly {
                 readonly name: string;
-                readonly in: "query" | "path" | "header" | "cookie";
+                readonly in: "query" | "path" | "querystring" | "header" | "cookie";
                 readonly required?: boolean;
                 readonly schema?: {
                     readonly [x: string]: Schema.Json;
@@ -53,10 +64,11 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
                 readonly required?: boolean;
             };
         };
+        readonly path: string;
         readonly input: {
             readonly [x: string]: Schema.Json;
         };
-        readonly method: "HEAD" | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
+        readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "QUERY";
         readonly securitySchemes: {
             readonly [x: string]: {
                 readonly [x: string]: Schema.Json;
@@ -67,6 +79,7 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
         readonly outputSchema?: {
             readonly [x: string]: Schema.Json;
         };
+        readonly tags?: readonly string[];
         readonly operationId?: string;
         readonly streaming?: true;
         readonly errorResponses?: readonly {
@@ -83,6 +96,14 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
             };
         }[];
     }[];
+    /** Declared operations left out of `operations`, in definition order. */
+    skipped: {
+        readonly name: string;
+        readonly method: string;
+        readonly path: string;
+        readonly code: "server_protocol" | "server_url" | "external_reference" | "circular_reference" | "schema_keyword" | "schema_reference" | "missing_component" | "openapi_version" | "auth_helper" | "auth_missing" | "operation_path" | "operation_method" | "duplicate_operation" | "server_missing" | "multiple_hosts" | "parameter_encoding" | "parameter_style" | "request_body" | "combined_oauth" | "auth_method" | "event_stream" | "input_schema" | "no_operations" | "no_supported_operations" | "invalid_document" | "source_generation" | "authoring_reference";
+        readonly reason: string;
+    }[];
     definitions: {
         [k: string]: {
             readonly [x: string]: Schema.Json;