apps 0.0.1-beta.26 → 0.0.1-beta.27

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

@@ -1,7 +1,8 @@
-import type { ProviderError } from "./provider-error.js";
+import { ProviderError } from "./provider-error.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 +32,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;
@@ -113,11 +145,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/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/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/mcp-client.d.ts

@@ -56,6 +56,7 @@ export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number,
             readonly websiteUrl?: string;
         } | {};
     }, ProviderError | McpError, never>;
+    check: Effect.Effect<void, ProviderError | McpError, never>;
     call: (name: string, input: JsonObject, context: McpToolContext) => Effect.Effect<{
         readonly content: readonly {
             readonly [x: string]: Schema.Json;

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

@@ -1,6 +1,6 @@
 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";
 /** 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<{
@@ -40,6 +40,7 @@ export declare const mcpClientEffect: (input: McpToolsOptions, changed?: Effect.
             readonly websiteUrl?: string;
         } | {};
     }, ProviderError | McpError, never>;
+    check: Effect.Effect<void, ProviderError | McpError, never>;
     call: (name: string, input: import("../index.js").JsonObject, context: import("../mcp.js").McpToolContext) => Effect.Effect<{
         readonly content: readonly {
             readonly [x: string]: Schema.Json;
@@ -53,5 +54,14 @@ export declare const mcpClientEffect: (input: McpToolsOptions, changed?: Effect.
         readonly isError?: boolean;
     }, ProviderError | 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 | 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>;

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

@@ -1,11 +1,30 @@
 /** HTTP MCP helpers. Requires the optional @modelcontextprotocol/sdk peer. */
 import type { OperationKinds } from "./implementation/protocol-operations.js";
+import type { McpHealthOptions } from "./contracts/mcp.js";
+import type { AccountCheckContext, AuthMethods } from "./contracts/provider.js";
 import { type McpCatalogOptions } from "./implementation/mcp-catalog.js";
 export type { McpCatalogOptions } from "./implementation/mcp-catalog.js";
-export { McpError, type McpToolContext, type McpToolsOptions, type McpToolResult, } from "./contracts/mcp.js";
+export { McpCredentialsUnverified, McpError, type McpHealthOptions, type McpToolContext, type McpToolsOptions, type McpToolResult, } from "./contracts/mcp.js";
 /**
  * A router over a server's tools for the selected account. Its title, description and
  * instructions come from the server. Kinds override uncertain upstream read-only hints.
  */
 export declare const mcpRouter: (options: McpCatalogOptions, kinds?: OperationKinds) => Promise<import("./index.js").RouterDeclaration<unknown, unknown>>;
+/**
+ * A provider `health` check for an MCP server. Pass the check context `health` receives, then the
+ * server's `url` and the `headers` that send the account's credentials:
+ * `health: (check) => mcpHealth(check, { url, headers: headers(check.account) })`.
+ *
+ * It connects with those headers, initializes, and reads the first page of tools, then does the
+ * same without any headers. No tool runs. The check passes only when the server accepts the account
+ * and refuses the attempt without credentials. A refused account throws `ProviderError`, as HTTP
+ * helpers do. An unreachable or unusable server throws `McpError`. A server that also answers
+ * without credentials, or whose answer to that attempt is not a refusal, throws
+ * `McpCredentialsUnverified`. Either error means the check could not verify the account, and the
+ * account form explains why. Send credentials only in `headers`; the attempt without them uses the
+ * same `url`. The check context's `signal` cancels both attempts, and they share one budget that
+ * ends early enough before its `deadline` to report a server that did not answer in time.
+ * `timeoutMs` can only shorten that budget.
+ */
+export declare const mcpHealth: <Auth extends AuthMethods>(check: AccountCheckContext<Auth>, options: McpHealthOptions) => Promise<void>;
 export type { OperationKinds } from "./implementation/protocol-operations.js";