apps 0.0.1-beta.26 → 0.0.1-beta.28

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

@@ -1,4 +1,5 @@
 import type { ProviderError } from "./provider-error.js";
+import type { NetworkRefused } from "./network.js";
 /** GraphQL discovery contracts. Catalogs are evaluated with the selected account. */
 import { Schema, type Effect } from "effect";
 import { type JsonValue } from "./schema.js";
@@ -97,7 +98,7 @@ export interface GraphqlTool {
     readonly description: string;
     readonly readOnly: boolean;
     readonly input: Schema.Decoder<JsonValue>;
-    readonly run: (context: unknown, input: JsonValue) => Effect.Effect<JsonValue, GraphqlError | ProviderError>;
+    readonly run: (context: unknown, input: JsonValue) => Effect.Effect<JsonValue, GraphqlError | ProviderError | NetworkRefused>;
 }
 /** One tool per root field; subscriptions require a separate long-lived host. */
 export type GraphqlTools = Readonly<Record<string, GraphqlTool>>;

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

@@ -6,6 +6,7 @@ import { OpenapiResponseError } from "./api-response-error.js";
 export { ApiErrorResponse, maxApiErrorInstructionsLength, maxApiErrorMessageLength, OpenapiResponseError, } from "./api-response-error.js";
 export { ProviderError } from "./provider-error.js";
 export { McpError } from "./mcp.js";
+export { FetchOptionUnsupported, NetworkRefusal, NetworkRefused, networkRefusalHeader, networkRefusalResponse, networkRefusalStatus, } from "./network.js";
 import { WorkflowFailure, type WorkflowExecution, type WorkflowReplay, type WorkflowHostControls } from "./workflows.js";
 export * from "./workflows.js";
 export * from "./failure.js";

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

@@ -1,7 +1,9 @@
-import type { ProviderError } from "./provider-error.js";
+import { ProviderError } from "./provider-error.js";
+import type { NetworkRefused } from "./network.js";
 /** MCP protocol data uses Effect Schema; executable tool methods use Effect. */
 import { type Effect, type Redacted, Schema } from "effect";
 import type { Elicit, ElicitationFailed } from "./elicitation.js";
+import type { AccountCheckContext, AuthMethods } from "./provider.js";
 import { type JsonValue } from "./schema.js";
 /** Upstream MCP resource bounds, independent of the outer codemode execution budget. */
 export declare const McpClientLimits: Schema.Struct<{
@@ -31,6 +33,37 @@ export declare const McpToolsOptions: Schema.Struct<{
     readonly timeoutMs: Schema.optional<Schema.Number>;
 }>;
 export type McpToolsOptions = typeof McpToolsOptions.Type;
+/**
+ * What `mcpHealth` checks, as decoded: its options, with the account's ID, signal and deadline
+ * taken from the check context.
+ */
+export declare const McpHealthInput: Schema.Struct<{
+    readonly headers: Schema.$Record<Schema.String, Schema.String>;
+    readonly deadline: Schema.optional<Schema.Finite>;
+    readonly url: Schema.String;
+    readonly accountId: Schema.optional<Schema.brand<Schema.String, "acc">>;
+    readonly signal: Schema.optional<Schema.instanceOf<AbortSignal, AbortSignal>>;
+    readonly timeoutMs: Schema.optional<Schema.Number>;
+}>;
+/**
+ * The server a provider check verifies, and the headers that send the checked account's
+ * credentials. The account, signal and deadline come from the check context instead. Both attempts
+ * share one budget that ends `mcpHealthReserveMs` before the deadline. `timeoutMs` bounds the whole
+ * check too; it can shorten the budget, never extend it.
+ */
+export type McpHealthOptions = Pick<typeof McpHealthInput.Type, "url" | "headers" | "timeoutMs">;
+/** What `mcpHealth` reads from the check context the host passes to a provider's `health`. */
+export type McpHealthCheck = Pick<AccountCheckContext<AuthMethods>, "signal" | "deadline"> & {
+    readonly account: {
+        readonly id: string;
+    };
+};
+/**
+ * How long before an account check's deadline `mcpHealth` stops waiting for the server, so it can
+ * still close its session, ending it and then its transport, each within `cleanupTimeoutMs`, and
+ * report why before the host stops waiting.
+ */
+export declare const mcpHealthReserveMs: number;
 /** One parsed server and credential snapshot; never shared across account evaluations. */
 export interface McpConnection {
     readonly url: URL;
@@ -99,7 +132,7 @@ export interface McpTool extends Omit<McpToolMetadata, "outputSchema"> {
     readonly input: Schema.Decoder<JsonValue>;
     readonly output: Schema.Decoder<JsonValue>;
     readonly readOnly?: boolean;
-    readonly run: (context: McpToolContext, input: JsonValue) => Effect.Effect<McpToolResult, McpError | ProviderError | ElicitationFailed>;
+    readonly run: (context: McpToolContext, input: JsonValue) => Effect.Effect<McpToolResult, McpError | ProviderError | NetworkRefused | ElicitationFailed>;
 }
 /** The discovered catalog keyed by remote tool name. */
 export type McpTools = Readonly<Record<string, McpTool>>;
@@ -113,11 +146,25 @@ declare const McpError_base: Schema.Class<McpError, Schema.TaggedStruct<"McpErro
     }>>;
 }>, import("effect/Cause").YieldableError>;
 /**
- * Safe protocol/transport failure; no raw upstream payloads or credentials. `upstream` is the
- * JSON-RPC error the server answered with, bounded and with account secrets replaced.
+ * Safe protocol/transport failure; no raw upstream payloads or credentials. `status` is the HTTP
+ * status a `request` failure was redirected or refused with. Without one, a `request` failure in
+ * the `transport` phase never reached the server; in another phase it may be a JSON-RPC error the
+ * server answered with. `upstream` is that JSON-RPC error, bounded and with account secrets
+ * replaced. A response that is not MCP is `invalid_response`.
  */
 export declare class McpError extends McpError_base {
 }
+declare const McpCredentialsUnverified_base: Schema.Class<McpCredentialsUnverified, Schema.TaggedStruct<"McpCredentialsUnverified", {
+    readonly anonymous: Schema.Union<readonly [Schema.Literal<"answered">, typeof McpError, typeof ProviderError]>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * `mcpHealth` could not show that the server needs the account's credentials, although it accepted
+ * them. `anonymous` is what the same check without credentials met: `answered` when it succeeded,
+ * so a refused key would pass too, or the failure, other than a refusal, that left it undecided.
+ * Only app code raises it; the host reports its fixed message, so no host protocol carries it.
+ */
+export declare class McpCredentialsUnverified extends McpCredentialsUnverified_base {
+}
 /** Public process configuration. Credentials arrive through the selected account. */
 export declare const ProcessConfig: Schema.Struct<{
     readonly command: Schema.NonEmptyString;

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

@@ -0,0 +1,84 @@
+/**
+ * What app code sees when Executor's app network refuses a request, and the fetch options the
+ * app runtime accepts. A refusal is Executor's decision, not the service's: the request never
+ * left Executor. App code runs on workerd, Cloudflare's runtime, on every host.
+ */
+import { Schema } from "effect";
+/**
+ * Why Executor's app network refused a request.
+ * - `private_address`: the destination is a private, loopback or internal address, and this
+ *   instance lets apps reach only public addresses.
+ * - `credential_host`: the request carries a credential handle, and its provider does not allow
+ *   the destination host.
+ * - `credential_app`: the request carries a credential handle that is not valid for this app.
+ * - `credential_expired`: the request carries an expired credential handle.
+ */
+export declare const NetworkRefusal: Schema.Union<readonly [Schema.Struct<{
+    readonly reason: Schema.Literal<"private_address">;
+}>, Schema.Struct<{
+    readonly reason: Schema.Literal<"credential_host">;
+    /** The provider of the credential handle the request carried. */
+    readonly provider: Schema.String;
+    /** The hosts that provider's credentials may reach; empty when it declares none. */
+    readonly allowedHosts: Schema.$Array<Schema.String>;
+}>, Schema.Struct<{
+    readonly reason: Schema.Literal<"credential_app">;
+}>, Schema.Struct<{
+    readonly reason: Schema.Literal<"credential_expired">;
+    /** The provider of the expired credential handle. */
+    readonly provider: Schema.String;
+}>]>;
+export type NetworkRefusal = typeof NetworkRefusal.Type;
+declare const NetworkRefused_base: Schema.Class<NetworkRefused, Schema.TaggedStruct<"NetworkRefused", {
+    /** The refused destination, with its port when the URL names one. */
+    readonly host: Schema.String;
+    readonly refusal: Schema.Union<readonly [Schema.Struct<{
+        readonly reason: Schema.Literal<"private_address">;
+    }>, Schema.Struct<{
+        readonly reason: Schema.Literal<"credential_host">;
+        /** The provider of the credential handle the request carried. */
+        readonly provider: Schema.String;
+        /** The hosts that provider's credentials may reach; empty when it declares none. */
+        readonly allowedHosts: Schema.$Array<Schema.String>;
+    }>, Schema.Struct<{
+        readonly reason: Schema.Literal<"credential_app">;
+    }>, Schema.Struct<{
+        readonly reason: Schema.Literal<"credential_expired">;
+        /** The provider of the expired credential handle. */
+        readonly provider: Schema.String;
+    }>]>;
+}>, import("effect/Cause").YieldableError>;
+/** Executor's app network refused a request before it reached the service. */
+export declare class NetworkRefused extends NetworkRefused_base {
+    get message(): string;
+}
+/**
+ * A refusal reaches app code as a response with this status and header. The header holds the
+ * encoded `NetworkRefused`, so it survives responses without a body, such as to `HEAD`; the
+ * body repeats it as JSON with its message. `ctx.fetch` and the framework's protocol helpers
+ * raise it as `NetworkRefused`; the platform's global `fetch` returns the response. Only
+ * Executor's app network sets the mark: it removes the header from a service's 421 response.
+ */
+export declare const networkRefusalStatus = 421;
+export declare const networkRefusalHeader = "x-executor-refused";
+/** The header's value: the refusal as JSON, URI-encoded so any provider name fits in a header. */
+export declare const NetworkRefusedHeader: Schema.compose<Schema.fromJsonString<typeof NetworkRefused>, Schema.StringFromUriComponent>;
+/** The response Executor's app network returns in place of a request it refused. */
+export declare const networkRefusalResponse: (refused: NetworkRefused) => Response;
+/** RequestInit options the app runtime restricts. */
+export declare const RestrictedFetchOption: Schema.Literals<readonly ["redirect", "cache", "integrity"]>;
+export type RestrictedFetchOption = typeof RestrictedFetchOption.Type;
+/** The values the app runtime accepts for each restricted option. */
+export declare const supportedFetchOptions: Readonly<Record<RestrictedFetchOption, ReadonlyArray<string>>>;
+declare const FetchOptionUnsupported_base: Schema.Class<FetchOptionUnsupported, Schema.TaggedStruct<"FetchOptionUnsupported", {
+    readonly option: Schema.Literals<readonly ["redirect", "cache", "integrity"]>;
+    readonly value: Schema.String;
+    readonly supported: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/** `ctx.fetch` was given a standard RequestInit value the app runtime does not implement. */
+export declare class FetchOptionUnsupported extends FetchOptionUnsupported_base {
+    get message(): string;
+    /** What to do instead, when the standard value has an equivalent the runtime supports. */
+    private get advice();
+}
+export {};

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

@@ -1,4 +1,5 @@
 import type { ProviderError } from "./provider-error.js";
+import type { NetworkRefused } from "./network.js";
 /** Credential-free OpenAPI request declarations and validation schemas retained with app source. */
 import { Schema, type Effect } from "effect";
 import { JsonObject } from "./schema.js";
@@ -219,7 +220,7 @@ 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 | OpenapiResponseError | ProviderError>;
+    readonly run: (context: unknown, input: Schema.Json) => Effect.Effect<unknown, OpenapiError | OpenapiResponseError | ProviderError | NetworkRefused>;
 }
 /** Executable operations keyed by their generated names. */
 export type OpenapiTools = Readonly<Record<string, OpenapiTool>>;

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

@@ -160,6 +160,12 @@ export interface AccountCheckContext<Auth extends AuthMethods> {
     readonly account: AccountOfMethods<Auth>;
     readonly fetch: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
     readonly signal: AbortSignal;
+    /**
+     * When the host stops waiting for the check, in milliseconds since the epoch. A check still
+     * running then fails without its own message, so a check that gives up must do so before it.
+     * Executor always sets it; a host that does not limit the check leaves it out.
+     */
+    readonly deadline?: number;
 }
 /**
  * A safe authenticated read proving the account works for this app. Returning passes; a thrown

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 default?: string;
                     readonly description?: string;
+                    readonly default?: string;
                     readonly format?: "email" | "uri" | "date" | "date-time";
                     readonly title?: string;
                     readonly minLength?: number;
                     readonly maxLength?: number;
                 } | {
                     readonly type: "number" | "integer";
+                    readonly description?: string;
                     readonly default?: number;
                     readonly maximum?: number;
-                    readonly description?: string;
                     readonly title?: string;
                     readonly minimum?: 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

@@ -39,7 +39,8 @@ export declare const parseMcpError: (error: unknown, secrets: readonly string[])
 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; any other thrown value is the app's own error, with
- * its own code and scalar fields. Account secrets are replaced.
+ * 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.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,7 +7,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 | 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;
     }[];
@@ -17,4 +18,4 @@ export declare const mcpCall: (client: Client, name: string, input: JsonObject,
         readonly [x: string]: Schema.Json;
     };
     readonly isError?: boolean;
-}, ProviderError | ElicitationFailed | McpError, never>;
+}, ProviderError | NetworkRefused | ElicitationFailed | McpError, never>;

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

@@ -1,4 +1,5 @@
 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";
@@ -15,10 +16,10 @@ export declare const answeredError: (error: unknown) => UpstreamError | undefine
 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<{
         tools: {
             readonly name: string;
@@ -42,9 +43,9 @@ export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number,
             } | undefined;
         }[];
         server: {
+            readonly description?: string;
             readonly version?: string;
             readonly name?: string;
-            readonly description?: string;
             readonly title?: string;
             readonly instructions?: string;
             readonly icons?: readonly {
@@ -55,7 +56,8 @@ export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number,
             }[];
             readonly websiteUrl?: string;
         } | {};
-    }, ProviderError | McpError, never>;
+    }, 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;
@@ -67,7 +69,7 @@ export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number,
             readonly [x: string]: Schema.Json;
         };
         readonly isError?: boolean;
-    }, ProviderError | import("../index.js").ElicitationFailed | McpError, never>;
+    }, 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,6 +1,7 @@
 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<{
@@ -26,9 +27,9 @@ export declare const mcpClientEffect: (input: McpToolsOptions, changed?: Effect.
             } | undefined;
         }[];
         server: {
+            readonly description?: string;
             readonly version?: string;
             readonly name?: string;
-            readonly description?: string;
             readonly title?: string;
             readonly instructions?: string;
             readonly icons?: readonly {
@@ -39,7 +40,8 @@ export declare const mcpClientEffect: (input: McpToolsOptions, changed?: Effect.
             }[];
             readonly websiteUrl?: string;
         } | {};
-    }, ProviderError | McpError, never>;
+    }, 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;
@@ -51,7 +53,16 @@ export declare const mcpClientEffect: (input: McpToolsOptions, changed?: Effect.
             readonly [x: string]: Schema.Json;
         };
         readonly isError?: boolean;
-    }, ProviderError | import("../index.js").ElicitationFailed | McpError, never>;
+    }, 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

@@ -17,6 +17,7 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
     readonly fallbackSecurity?: GeneratedOperation["request"]["security"];
 }) => Effect.Effect<{
     operations: {
+        readonly description: string;
         readonly name: string;
         readonly request: {
             readonly parameters: readonly {
@@ -57,7 +58,6 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
             };
         };
         readonly path: string;
-        readonly description: string;
         readonly input: {
             readonly [x: string]: Schema.Json;
         };

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

@@ -1,3 +1,4 @@
+import { NetworkRefused } from "../contracts/network.js";
 import { ProviderError } from "../contracts/provider-error.js";
 /** Swagger constructs requests; Effect owns HTTP policy and bounded results. */
 import { Effect, Schema } from "effect";
@@ -19,6 +20,6 @@ export declare function createRequest(config: {
     readonly oauth: readonly string[];
 }): {
     available: (op: OpenapiOperationAccess, account: OpenapiAccount | undefined) => boolean;
-    call: (op: OpenapiOperation, input: unknown, account: OpenapiAccount | undefined, errors: readonly DeclaredError[]) => Effect.Effect<Schema.Json, ProviderError | OpenapiResponseError | OpenapiError, never>;
+    call: (op: OpenapiOperation, input: unknown, account: OpenapiAccount | undefined, errors: readonly DeclaredError[]) => Effect.Effect<Schema.Json, ProviderError | NetworkRefused | OpenapiResponseError | OpenapiError, never>;
 };
 export {};

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

@@ -28,8 +28,8 @@ export declare const routerSkillPrefix = "tools";
 export declare const routerSkillName: (path: string) => string;
 /** A declared operation's catalog entry without schemas. `router` is its owning router's path. */
 export declare const operationSummary: (name: string, router: string, operation: AppOperation, schedules?: readonly OperationSchedule[]) => Effect.Effect<{
-    readonly name: string;
     readonly description: string;
+    readonly name: string;
     readonly title?: string;
     readonly annotations?: {
         readonly title?: string;
@@ -58,8 +58,8 @@ export declare const operationSummary: (name: string, router: string, operation:
 }, HostDeclarationInvalid, never>;
 /** A declared operation's full description, including rendered schemas. */
 export declare const operationDescription: (name: string, router: string, operation: AppOperation, schedules?: readonly OperationSchedule[]) => Effect.Effect<{
-    readonly name: string;
     readonly description: string;
+    readonly name: string;
     readonly inputSchema: {
         readonly [x: string]: Schema.Json;
     };
@@ -121,8 +121,8 @@ export interface CatalogOptions {
  */
 export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined, options: CatalogOptions) => Effect.Effect<{
     tools: ({
-        readonly name: string;
         readonly description: string;
+        readonly name: string;
         readonly inputSchema: {
             readonly [x: string]: Schema.Json;
         };
@@ -158,8 +158,8 @@ export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined,
         readonly router?: string;
         readonly tags?: readonly string[];
     } | {
-        readonly name: string;
         readonly description: string;
+        readonly name: string;
         readonly title?: string;
         readonly annotations?: {
             readonly title?: string;
@@ -188,8 +188,8 @@ export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined,
     })[];
     routers: {
         readonly path: string;
-        readonly error?: import("../index.js").ProviderError | SkillLoadFailed | HostDeclarationInvalid | HostEvaluationFailed | import("../mcp.js").McpError;
         readonly description?: string;
+        readonly error?: import("../index.js").ProviderError | SkillLoadFailed | HostDeclarationInvalid | HostEvaluationFailed | import("../mcp.js").McpError;
         readonly title?: string;
         readonly tags?: {
             readonly [x: string]: string;
@@ -209,8 +209,8 @@ export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined,
  * fail the others. Metadata comes through each source's catalog cache, like a tool listing.
  */
 export declare const routerSkills: (root: AppRouter | DynamicRouter | undefined) => Effect.Effect<{
-    readonly name: string;
     readonly description: string;
+    readonly name: string;
     readonly files: readonly {
         readonly path: string;
         readonly content: string;

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

@@ -13,8 +13,8 @@ export declare const reader: (transport: SkillTransport) => Effect.Effect<{
     json: (url: string) => Effect.Effect<unknown, SkillLoadFailed, never>;
 }, never, never>;
 export declare const githubSkillsEffect: (options: GitHubSkillsOptions) => Effect.Effect<readonly {
-    readonly name: string;
     readonly description: string;
+    readonly name: string;
     readonly files: readonly {
         readonly path: string;
         readonly content: string;
@@ -28,8 +28,8 @@ export declare const githubSkillsEffect: (options: GitHubSkillsOptions) => Effec
 }[], SkillLoadFailed, never>;
 /** Fetch all indexed files and reject a publication whose index changes during the read. */
 export declare const wellKnownSkillsEffect: (options: WellKnownSkillsOptions) => Effect.Effect<readonly {
-    readonly name: string;
     readonly description: string;
+    readonly name: string;
     readonly files: readonly {
         readonly path: string;
         readonly content: string;

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

@@ -1,4 +1,5 @@
 export { ProviderError } from "./contracts/provider-error.js";
+export { FetchOptionUnsupported, NetworkRefused } from "./contracts/network.js";
 export type { AppCache, CacheLoadContext, CacheGetOptions } from "./contracts/cache.js";
 export { CacheError } from "../../app-cache/src/contracts/cache.js";
 /**