apps 0.0.1-beta.9 → 0.0.1-beta.91

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 { AccountCredential, AppCache, CacheLoadContext } from "../contracts/cache.js";
 import { JsonObject, type JsonValue } from "../contracts/schema.js";
 export interface CatalogCacheOptions {
-    /** App/build scope, optionally narrowed to the current account. */
+    /** 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,14 +11,39 @@ export interface CatalogCacheOptions {
     /** Await a fresh revision at an explicit logical connection or refresh boundary. */
     readonly revalidate?: boolean;
 }
+/** Whose catalog a remote router reads, and the headers, such as credentials, it sends. */
+export type CatalogAccount = AccountCredential<{
+    /** Headers for this account's requests, such as its credentials. */
+    readonly headers?: Readonly<Record<string, string>>;
+}>;
+/** Why a read cannot use its account's scope. */
+export type CatalogScopeProblem = "missing-account" | "unselected-account";
+/**
+ * The cache an account's catalog lives in: the account's own scope, which token renewals keep.
+ * `credential` is what the read sends, such as headers or a token; it never enters a key. A
+ * credential without an account, or an account the app was not given, fails with `invalid`.
+ */
+export declare const catalogScope: <E>(options: {
+    readonly cache?: AppCache | undefined;
+    readonly account?: {
+        readonly id: string;
+    } | undefined;
+}, credential: unknown, invalid: (problem: CatalogScopeProblem) => 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;
 }
+/** The catalog a refresh replaces, read only when its loader asks for it. */
+export interface KeptCatalog<A> {
+    readonly header: JsonObject | undefined;
+    readonly tools: Effect.Effect<readonly A[], unknown>;
+}
 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. */
@@ -26,7 +51,13 @@ export declare const catalogCache: <A extends {
         readonly schema: Schema.Decoder<S>;
         readonly of: (tool: A) => S;
     };
-    readonly load: (context?: CacheLoadContext) => Effect.Effect<CatalogLoad<A>, unknown>;
+    /** Past `freshFor`, serve the kept catalog while refreshing, or refresh first. */
+    readonly stale?: "serve" | "revalidate";
+    /**
+     * Load the catalog. A refresh also gets the catalog it replaces, if one is kept, so a source
+     * that can confirm it is unchanged need not load it again.
+     */
+    readonly load: (context?: CacheLoadContext, kept?: Effect.Effect<KeptCatalog<A> | undefined, unknown>) => 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. */

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

@@ -1,5 +1,5 @@
 /** Validate both sides of a tool's form and bind delivery to its invocation lifetime. */
-import { Effect, Schema } from "effect";
+import { Effect, Schema, type Context } from "effect";
 import { ElicitationFailed, type ElicitationHandler, type Elicit } from "../contracts/elicitation.js";
 /** Parse a form and retain its response parser, so invalid answers can be rejected before consuming a host continuation. */
 export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
@@ -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,11 +37,11 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
                         readonly type: "string";
                         readonly enum: readonly string[];
                     };
-                    readonly default?: readonly string[];
                     readonly description?: string;
-                    readonly title?: string;
+                    readonly default?: readonly string[];
                     readonly minItems?: number;
                     readonly maxItems?: number;
+                    readonly title?: string;
                 } | {
                     readonly type: "array";
                     readonly items: {
@@ -50,30 +50,30 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
                             readonly title: string;
                         }[];
                     };
-                    readonly default?: readonly string[];
                     readonly description?: string;
-                    readonly title?: string;
+                    readonly default?: readonly string[];
                     readonly minItems?: number;
                     readonly maxItems?: number;
+                    readonly title?: string;
                 } | {
                     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 title?: string;
                 } | {
                     readonly type: "number" | "integer";
+                    readonly description?: string;
                     readonly default?: number;
+                    readonly minimum?: 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;
                 };
             };
@@ -99,5 +99,8 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
         } | undefined;
     }, ElicitationFailed, never>;
 }, ElicitationFailed, never>;
-/** Bind a validated interaction to the live invocation; transport adapters share its form parser. */
-export declare const makeElicit: (handler: ElicitationHandler | undefined, signal: AbortSignal) => Elicit;
+/**
+ * Bind a validated interaction to the live invocation; transport adapters share its form parser.
+ * Authored code's Promise calls run in the invocation's telemetry, like framework callers.
+ */
+export declare const makeElicit: (handler: ElicitationHandler | undefined, signal: AbortSignal, telemetry: Context.Context<never>) => Elicit;

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

@@ -0,0 +1,64 @@
+/** Event declarations and the per-invocation emitter. Emitted events leave in the reply. */
+import { Effect, Schema as EffectSchema } from "effect";
+import { EmittedEvent, type AppEvent, type EmitOptions } from "../contracts/events.js";
+import { type Fields, type Infer, type ObjectValue, type Schema } from "./schema.js";
+declare const Native: unique symbol;
+/** An event an app emits. Declare it in `defineApp`'s requirements under `events`. */
+export interface EventDeclaration<F extends Fields, P extends Schema<unknown, boolean>> {
+    readonly [Native]: AppEvent;
+    readonly description: string;
+    readonly filters: F;
+    readonly payload: P;
+}
+/** Any declared event, for requirement constraints. */
+export type AnyEventDeclaration = EventDeclaration<Fields, Schema<unknown, boolean>>;
+/**
+ * Declare an event. `filters` are scalar fields subscribers can narrow on, such as a repository;
+ * every emitted occurrence supplies their values. `payload` describes each occurrence's data.
+ */
+export declare const event: <const F extends Fields = {}, P extends Schema<unknown, boolean> = Schema<unknown>>(options: {
+    readonly description: string;
+    readonly filters?: F;
+    readonly payload: P;
+}) => EventDeclaration<F, P>;
+/** The native declaration retained by an author event. */
+export declare const nativeEvent: (declaration: unknown) => AppEvent | undefined;
+/** JSON Schema for each declared event, as the host reads it from requirements. */
+export declare const declaredEvents: (events: Readonly<Record<string, AppEvent>>) => Effect.Effect<{
+    readonly [x: string]: {
+        readonly description: string;
+        readonly filters: {
+            readonly [x: string]: EffectSchema.Json;
+        };
+        readonly payload: {
+            readonly [x: string]: EffectSchema.Json;
+        };
+    };
+}, EffectSchema.SchemaError, never>;
+/** Emit options typed by the event's filters: required exactly when it declares some. */
+type OptionsFor<F extends Fields> = keyof F extends never ? [options?: Omit<EmitOptions<never>, "filters">] : [options: EmitOptions<ObjectValue<F>> & {
+    readonly filters: ObjectValue<F>;
+}];
+/** `ctx.events` in mutations and webhook handlers. */
+export interface EventEmitter<Events extends Readonly<Record<string, AnyEventDeclaration>>> {
+    /**
+     * Record an occurrence. It is delivered only if this invocation succeeds. Invalid data, filters
+     * or options throw here, before anything is recorded.
+     */
+    readonly emit: <Name extends keyof Events & string>(name: Name, data: Infer<Events[Name]["payload"]>, ...options: OptionsFor<Events[Name]["filters"]>) => void;
+}
+/** One invocation's buffer. The handler reads `emitted` only after the invocation succeeds. */
+export declare const makeEmitter: (input: {
+    readonly events: Readonly<Record<string, AppEvent>>;
+    /** Every account ID bound to this invocation, which an emit may name. */
+    readonly accounts: readonly string[];
+    /**
+     * The caller's account IDs. An emit that names no account is attributed to the only one, if
+     * there is exactly one. App accounts never count: they are bound to every call.
+     */
+    readonly attributable: readonly string[];
+    /** The webhook's source account, which an emit names by default. */
+    readonly sourceAccount?: string;
+    readonly emitted: EmittedEvent[];
+}) => EventEmitter<Readonly<Record<string, AnyEventDeclaration>>>;
+export {};

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

@@ -1,25 +1,48 @@
-import { Redacted } from "effect";
-import type { ResolvedAccounts } from "../contracts/host.js";
+import { Option, Redacted } from "effect";
+import { McpError as HostMcpError, SkillLoadFailed as HostSkillLoadFailed, type ResolvedAccounts } from "../contracts/host.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`.
+ * Every credential field value of an invocation's accounts by scope, longest first. The accounts
+ * may not have been checked yet, so each scope is read only when it is a slot-to-account record;
+ * 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<HostMcpError>;
+/** Rebuild only the allowlisted skill loader fields from an author-visible rejection. */
+export declare const parseSkillLoadFailed: (error: unknown) => Option.Option<HostSkillLoadFailed>;
 /** `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; any other thrown value is the app's own error. 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-catalog.d.ts

@@ -1,7 +1,7 @@
 import { Effect } from "effect";
 import { GraphqlToolsOptions } from "../contracts/graphql.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 {
-}
+/** 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/input-problems.d.ts

@@ -1,3 +1,7 @@
 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;
+/**
+ * Failing input paths and what each expects, from a schema decode failure, without supplied
+ * values. An expected object names its keys, so a caller can correct nesting from the problem.
+ * A missing key also asks about a place where `input`, the rejected input, may have that key.
+ */
+export declare const inputInvalid: (error: unknown, input: unknown) => HostInputInvalid;

package/types/apps/src/implementation/invocation-timing.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Divide a tool invocation's time, on its own isolate's clock, by who the work belonged to:
+ * Executor, the app's authored code, upstream providers, a person answering an elicitation, or
+ * another call loading a cache entry this one waits for. Background work no caller waits on runs
+ * beside the division and is reported apart.
+ * Each boundary declares its owner where the work starts (see `owned`); the invocation's own span is
+ * Executor's. The host adds the other isolates' parts.
+ */
+import { Effect } from "effect";
+/** The span `makeElicit` opens while a person answers. */
+export declare const elicitationWaitSpan = "app.elicitation.wait";
+/** The span around each workflow control an app calls, which Executor answers. */
+export declare const workflowControlSpan = "app.workflow.control";
+/**
+ * Run a tool operation in its `app.<operation>` span and time it from the span's own start to its
+ * own end. The span records each part, and the isolated handler returns them to the host.
+ */
+export declare const timedInvocation: (operation: "call" | "query" | "mutate") => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, import("effect/Tracer").ParentSpan>>;

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

@@ -1,4 +1,4 @@
-import { Atom } from "effect/unstable/reactivity";
+import { Atom } from "effect/reactivity";
 import { AppQueryFailed, type OperationReference, type QueryTransport } from "../contracts/live.js";
 import type { Operation } from "./operations.js";
 import { type Schema } from "./schema.js";
@@ -14,5 +14,5 @@ export declare const mutationReference: <Mutation>(name: Mutation extends Operat
 export declare const liveQueryAtom: <Input, Output>(reference: OperationReference<Input, Output, "query">, input: NoInfer<Input>, options: {
     readonly output: Schema<NoInfer<Output>, boolean>;
     readonly transport: QueryTransport;
-}) => Atom.Atom<import("effect/unstable/reactivity/AsyncResult").AsyncResult<NoInfer<Output>, import("effect/Cause").NoSuchElementError | AppQueryFailed>>;
+}) => Atom.Atom<import("effect/reactivity/AsyncResult").AsyncResult<NoInfer<Output>, import("effect/Cause").NoSuchElementError | AppQueryFailed>>;
 export {};

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,9 +1,11 @@
 import { Effect } from "effect";
 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<import("./operations.js").RouterDeclaration<unknown, unknown>, unknown, never>;

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

@@ -1,18 +1,25 @@
 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<{
         tools: {
             readonly name: string;
@@ -36,11 +43,11 @@ 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 title?: string;
             readonly icons?: readonly {
                 readonly src: string;
                 readonly mimeType?: string;
@@ -49,19 +56,20 @@ 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;
         }[];
         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-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,11 +27,11 @@ 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 title?: string;
             readonly icons?: readonly {
                 readonly src: string;
                 readonly mimeType?: string;
@@ -39,19 +40,29 @@ 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;
         }[];
         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/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 {};