apps 0.0.1-beta.25 → 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/openapi-compile.d.ts

@@ -1,11 +1,39 @@
 /** Shared OpenAPI compilation diagnostics. */
 import { Schema } from "effect";
-export declare const OpenapiCompileErrorCode: Schema.Literals<readonly ["server_protocol", "server_url", "external_reference", "circular_reference", "schema_keyword", "schema_reference", "missing_component", "openapi_version", "auth_helper", "auth_missing", "operation_path", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
+export declare const OpenapiCompileErrorCode: Schema.Literals<readonly ["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"]>;
+/** A declared operation the importer left out, and why. */
+export declare const OpenapiSkippedOperation: Schema.Struct<{
+    /** The tool name the operation would have; reading that tool reports why it is missing. */
+    readonly name: Schema.String;
+    /** The HTTP method, such as `GET`. */
+    readonly method: Schema.String;
+    /** The path as the definition declares it. */
+    readonly path: Schema.String;
+    readonly code: Schema.Literals<readonly ["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: Schema.String;
+}>;
+export type OpenapiSkippedOperation = typeof OpenapiSkippedOperation.Type;
 declare const OpenapiCompileError_base: Schema.Class<OpenapiCompileError, Schema.TaggedStruct<"OpenapiCompileError", {
-    readonly code: Schema.Literals<readonly ["server_protocol", "server_url", "external_reference", "circular_reference", "schema_keyword", "schema_reference", "missing_component", "openapi_version", "auth_helper", "auth_missing", "operation_path", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
+    readonly code: Schema.Literals<readonly ["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: Schema.String;
+    readonly skipped: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        /** The tool name the operation would have; reading that tool reports why it is missing. */
+        readonly name: Schema.String;
+        /** The HTTP method, such as `GET`. */
+        readonly method: Schema.String;
+        /** The path as the definition declares it. */
+        readonly path: Schema.String;
+        readonly code: Schema.Literals<readonly ["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: Schema.String;
+    }>>>;
+    readonly origins: Schema.optionalKey<Schema.$Array<Schema.String>>;
 }>, import("effect/Cause").YieldableError>;
-/** A safe generation failure, translated into product HTTP errors at the boundary. */
+/**
+ * A safe generation failure. `reason` explains the cause; `skipped` lists the declared operations
+ * it left out and why, and `origins` the origins operations resolve to when none of them matches
+ * the allowed origin. Reading one left-out tool fails with this error for that operation alone.
+ */
 export declare class OpenapiCompileError extends OpenapiCompileError_base {
+    get message(): string;
 }
 export {};

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

@@ -20,7 +20,8 @@ export type OpenapiErrorResponse = typeof OpenapiErrorResponse.Type;
 /** Resolved OpenAPI parameter shared by import validation and request construction. */
 export declare const OpenapiParameter: Schema.Struct<{
     readonly name: Schema.String;
-    readonly in: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+    /** OpenAPI 3.2's `querystring` is the whole query string, serialized from one `content` value. */
+    readonly in: Schema.Literals<readonly ["path", "query", "querystring", "header", "cookie"]>;
     readonly required: Schema.optionalKey<Schema.Boolean>;
     readonly schema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
     readonly style: Schema.optionalKey<Schema.String>;
@@ -45,7 +46,7 @@ export declare const OpenapiOperation: Schema.Struct<{
     /** The document's operationId, when it declares one. `kinds` overrides are keyed by it. */
     readonly operationId: Schema.optionalKey<Schema.String>;
     readonly description: Schema.String;
-    readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]>;
+    readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "QUERY"]>;
     readonly path: Schema.String;
     readonly baseUrl: Schema.String;
     readonly openapi: Schema.String;
@@ -54,7 +55,8 @@ export declare const OpenapiOperation: Schema.Struct<{
     readonly request: Schema.Struct<{
         readonly parameters: Schema.$Array<Schema.Struct<{
             readonly name: Schema.String;
-            readonly in: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+            /** OpenAPI 3.2's `querystring` is the whole query string, serialized from one `content` value. */
+            readonly in: Schema.Literals<readonly ["path", "query", "querystring", "header", "cookie"]>;
             readonly required: Schema.optionalKey<Schema.Boolean>;
             readonly schema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
             readonly style: Schema.optionalKey<Schema.String>;
@@ -92,6 +94,8 @@ export declare const OpenapiOperation: Schema.Struct<{
     }>>>;
 }>;
 export type OpenapiOperation = typeof OpenapiOperation.Type;
+/** Safe methods, whose operations are queries unless `kinds` says otherwise. QUERY is OpenAPI 3.2's. */
+export declare const isOpenapiReadMethod: (method: OpenapiOperation["method"]) => method is "GET" | "HEAD" | "OPTIONS" | "QUERY";
 /** Map a selected account field to one Swagger credential value. */
 export declare const CredentialBinding: Schema.Struct<{
     readonly scheme: Schema.String;
@@ -125,7 +129,7 @@ export declare const OpenapiToolsOptions: Schema.Struct<{
         /** The document's operationId, when it declares one. `kinds` overrides are keyed by it. */
         readonly operationId: Schema.optionalKey<Schema.String>;
         readonly description: Schema.String;
-        readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]>;
+        readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "QUERY"]>;
         readonly path: Schema.String;
         readonly baseUrl: Schema.String;
         readonly openapi: Schema.String;
@@ -134,7 +138,8 @@ export declare const OpenapiToolsOptions: Schema.Struct<{
         readonly request: Schema.Struct<{
             readonly parameters: Schema.$Array<Schema.Struct<{
                 readonly name: Schema.String;
-                readonly in: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+                /** OpenAPI 3.2's `querystring` is the whole query string, serialized from one `content` value. */
+                readonly in: Schema.Literals<readonly ["path", "query", "querystring", "header", "cookie"]>;
                 readonly required: Schema.optionalKey<Schema.Boolean>;
                 readonly schema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
                 readonly style: Schema.optionalKey<Schema.String>;
@@ -223,7 +228,12 @@ export declare const defaultOpenapiResponseLimits: {
     readonly maxBodyBytes: 16777216;
     readonly readTimeoutMs: 30000;
 };
-/** Media returned as text rather than a base64 file. NDJSON remains an unparsed text result. */
+/**
+ * A sequence of JSON values, one per line or record: NDJSON, JSON Lines and `json-seq`, whose
+ * items OpenAPI 3.2 describes with `itemSchema`. The body is not one JSON value.
+ */
+export declare const isOpenapiJsonSequence: (type: string) => boolean;
+/** Media returned as text rather than a base64 file. JSON sequences remain unparsed text. */
 export declare const isOpenapiTextMedia: (type: string) => boolean;
 /** A form field that carries raw file bytes: OpenAPI 3.1 `contentMediaType` without an
  * encoding, or the `format: binary` string that 3.1 documents still commonly use. */

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/implementation/openapi-compile.d.ts

@@ -11,6 +11,8 @@ import { type GeneratedOperation, type GeneratedSecrets } from "../contracts/ope
 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<{
@@ -19,7 +21,7 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
         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;
@@ -59,7 +61,7 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
         readonly input: {
             readonly [x: string]: Schema.Json;
         };
-        readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+        readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "QUERY";
         readonly securitySchemes: {
             readonly [x: string]: {
                 readonly [x: string]: Schema.Json;
@@ -87,6 +89,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;

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

@@ -13,10 +13,18 @@ export declare const DocumentObject: Schema.declare<{
 export declare const documentObject: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
     readonly [x: string]: Schema.Json;
 };
+/** One JSON Pointer reference token. */
+export declare const pointerToken: (key: string) => string;
+/**
+ * Decode one part of the definition, located by the JSON Pointer `at`. A mismatch names the
+ * pointer of the first failing value and what was expected there.
+ */
+export declare const decodeDefinition: <S extends Schema.Decoder<unknown>>(schema: S, value: unknown, at: string, what: string) => S["Type"];
 /** Resolve OpenAPI objects once; schemas retain their original recursive references.
- * Scalar first upgrades Swagger 2.0 and OpenAPI 3.0 to 3.1, so the importer has one dialect and
- * 3.1 keywords that appear in 3.0 documents keep their meaning.
- * Unsupported versions, references and conversions throw TemplateError at the import boundary.
+ * Scalar first upgrades Swagger 2.0 and OpenAPI 3.0 to 3.1, so the importer reads 3.1 and 3.2,
+ * whose Schema Objects share one dialect, and 3.1 keywords that appear in 3.0 documents keep
+ * their meaning. Unsupported versions, references and conversions throw TemplateError at the
+ * import boundary.
  */
 export declare function openApiDocument(input: JsonObject): Promise<{
     spec: {
@@ -51,14 +59,20 @@ export declare function openApiDocument(input: JsonObject): Promise<{
     definitions: Map<string, {
         readonly [x: string]: Schema.Json;
     }>;
+    /**
+     * The JSON Pointer of the object a local reference resolved to, so a diagnostic can locate
+     * a resolved Response, Parameter, Request Body or Path Item where the definition declares it.
+     */
+    origin(value: unknown): string | undefined;
     /** Inspect a component schema without expanding its children. OpenAPI object refs must already be resolved by Swagger. */
     resolve(value: JsonObject): JsonObject;
     /** Compose a Draft 2020-12 schema around API Schema Objects. Only values passed to
      * `api` use the document's OpenAPI dialect; Executor-authored wrappers are already
-     * Draft 2020-12 and must not be reinterpreted. Reached components are converted once into
-     * the shared `definitions` and stay references here; nothing is inlined or copied per operation.
+     * Draft 2020-12 and must not be reinterpreted. `api` takes the schema's JSON Pointer in the
+     * definition, which failures name. Reached components are converted once into the shared
+     * `definitions` and stay references here; nothing is inlined or copied per operation.
      */
-    schema(build: (api: (input: Schema.Json) => JsonObject) => JsonObject): JsonObject;
+    schema(build: (api: (input: Schema.Json, at: string) => JsonObject) => JsonObject): JsonObject;
 }>;
 /** A parsed document with one reference scope and one schema dialect. */
 export type OpenApiDocument = Awaited<ReturnType<typeof openApiDocument>>;

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

@@ -11,8 +11,13 @@ export interface OperationNameInput {
     readonly path: string;
 }
 /**
- * Plan one name per input, in input order. Names that collide are refined together: first by
- * the path's version segment, then by the HTTP method, then by a stable hash. Refinement only
- * touches the colliding names, so adding an operation never renames an unrelated one.
+ * Name every input, in input order. Names that collide, whether or not they come from an
+ * operationId, are refined together: first by the path's version segment, then by the path
+ * segments that tell them apart (`GET /items` and `GET /items/{id}` are `items.getItems` and
+ * `items.getItemsById`), then by the whole path, then by the HTTP method, then by a stable hash.
+ * Refinement only touches the colliding names, so adding an operation never renames an unrelated
+ * one.
  */
-export declare const planOperationNames: (inputs: readonly OperationNameInput[]) => string[];
+export declare const planOperationNames: <I extends OperationNameInput>(inputs: readonly I[]) => (I & {
+    readonly name: string;
+})[];

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

@@ -16,6 +16,12 @@ export interface OpenapiSourceOptions extends Omit<OpenapiToolsOptions, "operati
     readonly allowedOrigin: string;
     readonly securitySchemes: Readonly<Record<string, JsonObject>>;
     readonly baseUrl?: string;
+    /**
+     * A path inserted between the server and every operation's path, for a definition that omits a
+     * leading segment, such as `/projects/{project}`. Each `{name}` becomes a required string path
+     * parameter of every tool, unless the operation already declares it without placing it.
+     */
+    readonly pathPrefix?: string;
     readonly freshFor?: Duration.Input;
     readonly staleFor?: Duration.Input;
     /**

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";